ARCHIVED: KBML guide

This content has been archived, and is no longer maintained by Indiana University. Information here may no longer be accurate, and links may no longer be available or reliable.

On this page:

Required KBML tags:
A blank KBML template
Special purpose KBML tags:
The who attribute
HTML in KBML
KBML errors to avoid
Some upcoming changes
You do not have sufficient permission to view this document.: This is a link to the KB Style Guide, the bible used by the KB staff. Go to the Style Guide's "Formatting" section for information on the following tags:
- <mi> and <code>
- <strong> and <em>
- Using <br> tags with lists

Required KBML tags

These tags are required in a correctly formatted KBML document:

<kbml>

The <kbml> tag is the top level tag for KBML documents. It identifies the document as a KBML document and contains all the markup of the document.

The <kbml> tag has an optional attribute, name. Use the name attribute when you are creating a document that will be used as a boiler. The name attribute is what Knowledge Management (KM) staff will use in the <boiler> tag to link to the document from within another document.

<kbq>

The <kbq> tag is used to identify the title of a document and should appear at the top of a document. For example, to make the title of a document "What is asynchronous mimsy?", you would include the following:

  <kbq>What is asynchronous mimsy?</kbq>

You can use the <altq> tag to give a document multiple titles. All titles must be enclosed within one set of <kbq> tags. The first title inside the <kbq> tag can be surrounded by <mainq> tags, but these are optional if there is only one title. Additional titles can be added below the main title, surrounded by <altq> tags. (If you add <altq> tags, there must be a default title, and it's best to enclose this in <mainq> tags.) The <altq> tags must include an audience attribute specifying the intended audience for the alternate title, e.g.:

  <kbq>
  <mainq>In Oncourse, how can I do some task?</mainq>
  <altq audience="oncoursecl">Doing some task</altq>
  </kbq>

If you specify an invalid audience, the default title will be displayed instead of the alternate title.

If you would like to use a particular audience for the first time, you need to add the audience to a database before you can use it. To add a new audience, use the titleaudience tool at the command line on Bell. For help, enter titleaudience -h. To see a list of existing audiences, enter titleaudience list. You can also view the list of audiences on the web.

Alternate titles do not display in search returns. For information about specifying an alternate title when using a <kba> tag, see the <kba> section below.

<body>

The <body> tag contains the viewable contents of the KBML document. It appears directly after the </kbq> tag.

<xtra>

Note: <xtra> tags are no longer used in the KMS. However, we must include at least one word between xtra tags.

<xtra> tags appear at the bottom of the document, after the end tag of the <body> element and before the end tag of the <kbml> element. Words enclosed by this tag will be added to the index of searchable terms as referencing the document in which they appear, but will not appear in the live KB.

Note: Adding a hyphen to a keyword in the xtras effectively breaks that keyword. A KB search for a keyword containing a hyphen (e.g., tgtopic-software) will not find documents that have the hyphenated keyword in the xtras. KBSS can find documents with hyphenated keywords in the xtras.

In some cases, it's useful to add a search term to the xtras more than once, which makes the doc appear higher up in the search returns (this is sometimes referred to as "weighting the xtras"). In this case, rather than repeatedly typing the search term, type the search term followed by : (a colon) and the number of times you'd like the term added, for example, password:6. If there is more than one instance of a word in the xtras, only the first instance will be indexed, and succeeding instances will be ignored; make sure, if you're adding a weighted xtra, that the word does not occur elsewhere in the xtras. Note that words enclosed by <xtra> tags imported from KB2 typically appear with ":1" after them.

A blank KBML template

These are all the required tags in a KBML document, in the order in which they appear. The text of the document goes between the opening and closing <body> tags.

  <kbml>

  <kbq></kbq>

  <body>
  </body>

  <xtra></xtra>

  </kbml>

To insert this into an Emacs buffer, open Emacs and type C-c N.

Alternatively, you can use the following commands:

Open Emacs and type C-x C-f, and name your file.
Type M-x kbml-mode. (You can also type C-c m for this step.)
Type C-c C-e.
At the Element: kbml prompt, press Enter.

Special purpose KBML tags

<kba>

The <kba> tag is used to link to other KB documents. The docid you specify with the tag will be expanded by the parser as the hotlinked title of the document, for example:

  For more on obtaining a computer account at IU
  Bloomington, see <kba docid="achn">

Note: If the title of the document ends in a question mark, which is usually the case, do not add punctuation after the <kba> if it occurs at the end of a sentence.

The attributes for the <kba> tag are as follows:

qline="blah": The qline attribute lets you specify an alternate title to display for the given document, for example <kba docid="aala" qline="oncoursecl">. This is useful only if you are pointing to a document that has multiple titles, and you want to display a title other than the default title (i.e., <mainq>) in the document at hand. For more, see the <kbq> section above.
If you view a KB document from the interface of a particular audience, <kba> tags within that document will display the q-lines for the audience you specify in the URL. For example, if you are viewing https://oncoursehelp.iu.edu/helptool/docs/zzzz, all <kba> tags in that document will automatically try to get q-lines with the "oncoursecl" audience from the docs they are pointing to. Barring that, they will get the default title.

To override this behavior, use the qline attribute of the <kba> tag. For the document listed above (zzzz, in the Oncourse interface):

<kba docid="yyyy" qline="box"> Displays "box" title
<kba docid="yyyy">
Displays "oncoursecl" title, from the parent doc

To force the default title to always be displayed (regardless of the currently requested title), enter a non-existent audience, such as "0":
```
  <kba docid="yyyy" qline="0">
```
text="blah": The text attribute lets you specify arbitrary text that will appear in place of the q-line or alternate q-line as the link for the <kba>.
Sometimes we need to link to a KB document using a link with text that does not match either the <mainq> or <altq> text. For example, this can happen if the link is in a table and the link text must be very brief. In cases like this, you can use the text attribute of the <kba> tag to specify any text that you like for the link text, for example:
```
  <kba docid="aqhx" text="Mac OS X" qline="ose">
```
This will create a link to doc aqhx with the link text appearing as "Mac OS X"; when you click that text, aqhx will display with its "ose" q-line.
frag="#blah": The frag attribute lets you link to a specific section of a different KB document, using that section's internal anchor. For example, to link to the "Canvas Guides" section of bexp, use:
```
  <kba docid="bexp" text="Canvas Guides" frag="#canvas">
```

<kbh>

Computing documents often contain technical terms or jargon that's confusing to beginning readers who aren't familiar with the terminology. To address this, KBML has a special "hotitem" tag that lets you link a term or phrase to a KB document that explains its meaning. For example, the first time you mention "HTML" in a text intended for beginning users, you might want to wrap the term in the <kbh> hotitem tag:

  Once you're finished editing the <kbh>HTML</kbh> document,
  copy it to your <code>www</code> directory.

Provided that the term in <kbh> tags is defined in the hotitem database, the browser will list the term in the sidebar under "Terms", with a link to a corresponding KB document. For more about hotitems, see You do not have sufficient permission to view this document..

<noheat>

The <noheat> tag keeps a sample URL from being hotlinked to its source. For example, if you are writing a document about creating a home page, you might want to give an example of a URL that doesn't actually go anywhere. To do this, wrap the URL in <noheat> tags:

  <noheat>http://www.sample.com/not_real.html</noheat>

Be sure to wrap only the URL itself and not any accompanying text in these tags. In other words, the following is incorrect:

  <noheat>Here's a bad URL: http://www.sample.com/not_real.html</noheat>

The following URL types are recognized by the renderer, and will be heated unless you wrap them with <noheat>:

http://
https://
ftp://
telnet://
gopher://

Additionally, there are other URI schemes that are recognized by the validator; these would normally appear within an href="" attribute, but the validator will also pick them up if they appear within the text itself (e.g., within sample code that we reproduce for an owner). These schemes are:

mailto:username@domain
file://localhost/file.txt
news:news.group
javascript:function_name()

The validator will pick up these schemes, attempt to resolve them, and give an error. To prevent the validator from picking them up, wrap them in <noheat> as well.

<example>

You can use the <example> tag to enclose examples of sample output or commands that a user should enter. Its appearance and behavior are similar to the HTML <pre> tag, for example:

  To list all your files, enter at the Unix prompt:

  <example>
    ls -la
  </example>

Note that any white space you include inside the <example> tag will be displayed when the document is viewed. In the above example, the ls -la command will show up indented. The standard way to format an <example> tag is to indent two spaces before the text you are highlighting. For more, see the You do not have sufficient permission to view this document. "<example> tags" section.

<boiler>

The <boiler> tag is used to include boilerplates in KB documents. Boilerplates are KB documents that contain informative comments to be repeated in many texts (e.g., a notice that a particular computer is being removed from service). Note that boilers do not appear in the regular KB as independent documents. For example, for the boiler mskb, which contains instructions for accessing the Microsoft support site, you would use the following to add the boiler to any appropriate KB documents:

  <boiler src="mskb">

The contents of the boilerplate will show up in the document when it's viewed in a browser.

<mi>

This tag name stands for "menu item". Menus of any type as well as items within those menus are delineated with the <mi> tag. Do not use quotation marks or other symbols in place of <mi> tags, as they are reserved for their own uses. For more, see the "<mi> tag" section in the You do not have sufficient permission to view this document..

<code>

Text inside <code> tags appears in a fixed-width font. KB staff use <code> tags for text the user is to enter, for filenames, and in several other cases. Do not add quotation marks around text in <code> tags. For more, see the "<code> tag" section in the You do not have sufficient permission to view this document..

<image>

The <image> tag allows you to insert an image into a KB document. You can use this tag only with images that are in the media database. To add the image file to the media database, use the kbmedia command. For more, see the kbmedia documentation. The file must be world-readable, and the file extension must indicate the format of the image, e.g., .gif or .jpg. For more about using images in the Knowledge Base (style, step-by-step instructions), see ARCHIVED: Using images in the Knowledge Base.

Note: For images to be viewable in a browser, they must be in the GIF (.gif), JPEG (.jpg), or PNG (.png) format. If you would like to add a bitmap (.bmp) image, you need to convert it to one of these formats. You can do this with Photoshop, available from IUware.

The <image> tag in KBML is different from the one in HTML; it offers several options for displaying text instead of, or in addition to, the image. The attributes for the <image> tag in KBML are as follows:

src="z999z": This is the image ID (a five-character identifier assigned to each image). The image ID is assigned when the image is added to the media database.
alt="Alternate text": This required attribute is equivalent to the HTML alt attribute. This text will show up when the image can't be displayed (e.g., in non-graphical browsers, in graphical browsers with images turned off). Generally the text will appear when the page loads; in some graphical browser/platform combinations, it will appear when you mouse over the icon for the missing image. We have no control over how alt text is used; that depends on the browser.
inline="inline": If you use this attribute, the image will appear as an inline image. If you omit this attribute, a link to the image will appear, using the text in the description subtag as the text for the link, which will open in a separate browser window.
who="*@...": Standard who attribute. For more, see the section on The who attribute.

Note: A description attribute used to be required, but is no longer needed and is now useless; it is replaced by the <description> subtag described below. If you see a description attribute in an <image> tag, remove it. The information in the attribute should have already been moved to a <description> subtag.

The <image> tag in KBML also requires a closing tag (</image>).

The optional subtag <description> is available as a way of providing caption information for the image. Within the <description> tag, you can use the following tags to format text:

<big>
<cite>
<code>
<em>
<small>
<strong>
<sub>
<sup>
<tt>

The description tag has an optional width attribute. Use this attribute to indicate a limit on the width of the description. This can be useful, for example, to keep a description well-centered under a small image. The value of this attribute should be a number, roughly equivalent to the number of letters wide the description should be.

Here's an example of how an <image> tag could be used to display an image of the Internet Explorer icon:

  <image src="a004k" inline="inline" alt="The Internet Explorer icon is a lowercase blue e."
  <description width="8">
  <strong><big>Internet Explorer</big></strong>
  </description>
  </image>

<kbsecure>

The <kbsecure> tag is for marking a piece of text as visible only to certain domains. For example, if you had one sentence about something of interest only to Support Center staff in a document visible to all, you would secure that information so it was visible only to the sc domain:

  <p> Blah blah something blah. <kbsecure who="*@sc"> This
    sentence is only for SC staff.</kbsecure> Blah more
    something.  </p>

We used to use <kbsecure> tags to secure information that was relevant only at IU, or only at a particular IU campus. Since more people are connecting from computers that are not on the IU network these days (e.g., using a non-IU ISP), we no longer use <kbsecure> tags this way.

The <kbsecure> tag is only for securing pieces of text within markup. Text includes phrase data tags (<em>, <strong>, <code>, <cite>), <kbh> tags, <example> tags, and special tags (<a>, <kba>, <br>) as well as character data. <kbsecure> tags cannot go in list tags (<ul>, <ol>, <dl>), but they can go inside list item tags (<li>, <dt>, <dd>).

For more about the who attribute, see below.

<word>

The <word> tag is a text-level tag that can identify a text string that ought to be treated as a single word. <word> tags can contain only plain text or character entities (i.e., no tags inside <word> tags). This is most useful for identifying words that begin or end with punctuation (which is normally sloughed off by the KB indexer), for example:

  The best Internet culture periodical is <WORD>Yahoo!</WORD> magazine.

You can also use the <word> tag to prevent a single word that contains white space or punctuation from being split into multiple strings, e.g.:

  <WORD>A/UX</WORD> and <WORD>HP-UX</WORD>

This usage is not strictly necessary, since the KB indexer treats words with internal punctuation both as a single long word and as a set of multiple words separated by the punctuation characters.

<kbmeta>

The <kbmeta> tags were used in KB documents that appeared in the OSE, and we are in the process of removing them.

<kbtable>

See You do not have sufficient permission to view this document..

The who attribute

You can use the who attribute within certain KBML tags to secure content. Access to secured content is determined by user authentication; users are allowed access to a set of domains depending on their status. For example, Support Center staff can view the all, sc, and uits domains. For a list of legal domains, see the kbadm.DomainList table. For an explanation of these domains, see ARCHIVED: Guide to KB keywords (metadata). For more about how people get access to a particular internal domain, see About restricted KB content.

Note: Be extremely cautious when securing information, to ensure that you aren't potentially restricting access from someone who needs it.

Below are the legal KBML tags with which you can use the who attribute:

<h3> through <h6>
<p>
<kbsecure>
<example>
List tags: <dl>, <ol>, <ul>, and <li>
<boiler>
<blockquote>
<kbtable>

Examples of usage

To secure an "SC staff:" note for Support Center staff only:

  <blockquote who="*@sc">
  <strong>SC staff:</strong> This information is for
  SC staff only.
  </blockquote>

To secure a line of text to SC and TCC staff only:

  <p>
    Anybody can see this sentence.
    <kbsecure who="*@sc, *@tcc">But this sentence is 
    internal only!!</kbsecure>
  </p>

HTML in KBML

KBML is loosely based on HTML 2.0, and supports many HTML tags from the HTML 3.2 standard. However, no features specific to HTML 4.0 should be used or implemented at the present time, until HTML 4.0 becomes more widely, correctly, and fully adopted by browsers.

Legal HTML tags

Headings <h3> through <h6> are legal, although <h5> and <h6> tags render too small, so we don't use them in KB docs. Headings <h1> and <h2> are reserved for use in headers and footers of documents; therefore, you can't legally add them to a document.
Lists: <ul>, <ol>, <dl>
List items: <li>, <dt>, <dd>
<p>
<pre>
<blockquote>
Logical styles: <em>, <strong>, <code>, <cite>
Physical styles: <tt>, <sub>, <sup>, <big>, <small>
Note: Do not use <tt>; instead, use <code>. Use <big> and <small> only in the <description> subtag of the <image> tag as described above.
<hr>
<a>
Note: If you need to add a target attribute to an <a href> tag to make the link open in a new window, use this format:
```
  <a href="http://www.something.edu/blah.html" target="new">
```
<br>
<address>

Illegal HTML tags

<h1>, <h2>
<doctype>, <html>, <head>, <title>, <base>
<strike>
<applet>, <font>, <script>, <map>
<div>, <center>, <form>, <isindex>,
<img> (use the KBML <image> tag; see ARCHIVED: Using images in the Knowledge Base)
<table> (use the KBML <kbtable> tag; see You do not have sufficient permission to view this document.)

For more, you can read the KBML Document Type Declaration (DTD) on Bell at /kb/sgml/kbml.dtd and /kb/sgml/kbbody.dtd.

Closing tags

The Knowledge Base is transitioning to the DITA XML scheme. It is important that every tag have an associated closing tag. We do not put closing </li> tags or adding a closing slash to tags like <br>, but do ensure that <p> tags are closed. Some older documents might not have these closing tags, so add them when you see they are missing. When the text of a paragraph occurs before or surrounds something in <example> tags, close each <p> tag before the <example> tag and then use a new <p> tag after the </example> tag if needed for the next paragraph of text. An example follows:

  <p>
  To emulsify a file, enter the following at the command prompt:
  </p>

  <example>
    emulsify filename
  </example>

  <p>
  Replace <code>filename</code> with the name of your
  file.
  </p>

A number of documents contain paragraphs that are broken up by <example> tags but contain only a single <p> and </p> tag surrounding the entire paragraph. This will not cause a problem now, but change these documents to follow the example above. This will make the transition to XML easier.

Character entities

Remember to use character entities when you need to make particular characters appear; i.e., instead of typing < for the less-than symbol, you must type the string < (the ampersand character, the letters l and t, and a semicolon). This is because the SGML parser (that converts KBML to HTML) and web browsers (that convert HTML into viewable pages), may interpret the < as being part of an SGML or HTML tag, thus garbling the output. All characters in ASCII or ISO Latin-1 (including non-English letters) can be produced using character entities; see webmonkey's Special Characters page or the Table of printable Latin-1 Character codes from the HTML 3.2 Reference Specification. Following is a table of the most commonly used special character entities:

Character:	Character entity:
<	`<`
>	`>`
&	`&`
a non-breaking space	` `
tilde	`~`

Important: URLs interact with special characters in sometimes unpredictable ways:

Even if you put a sample URL in <noheat> tags, the renderer recognizes a URL, and performs (or attempts to perform) standard URL processing, sometimes preventing it from properly rendering special characters. To solve this, when using special, non-URL characters in a sample URL, break the connection between the URL scheme and the problem characters. E.g., the following will not render correctly, but will display the ampersand codes in place of the desired < and > :
```
  <example>
    <noheat>http://&lt;hostname&gt;/&lt;full_path&gt;</noheat>
  </example>
```
To make it render correctly, with < and >, use the <noheat> tags to dissociate the URL scheme from the URL address:
```
  <example>
    <noheat>http://</noheat>&lt;hostname&gt;/&lt;full_path&gt;
  </example>
```
This will produce the desired:
```
  http://<hostname>/<full_path>
```
See the noheat section above.
To make a URL heat properly, it cannot contain any spaces. Replace spaces in URLs with the character string %20.
Ampersands are common features in some URLs. Replace any & in a URL with &. You need to do this even if the URL does not appear in the document text but only in an <a href=""> tag.

mailto:

<a href="mailto:"> tags are legal, but we use them in public docs usually only when specifically requested. They may also appear in some internal docs.

KBML errors to avoid

Below are a handful of commonly made, yet not commonly recognized, KBML mistakes. This list is not complete; rather, it's based on common errors appearing in the kbverify script's reports. These are violations of the KBML DTD, and will probably result in junky HTML output. Avoid them at all cost, and remember to always view documents in your browser to verify that the KBML is correct.

Use the who attribute inside a <boiler> tag, rather than <kbsecure> tags surrounding it.
You can't put <kbsecure>s inside <strong>s or other tags at that level.
You can't put <br>s directly inside a <dl>; they have to be inside an enclosing <dd> or <dt>.
<kbtables>s don't have cellspacing attributes, but they do have cellpadding attributes.

Note: For proper spacing before the footer, be sure to add <p></p> after any kbtable at the end of a doc.
<center>s don't exist in KBML.
Don't use a bare & anywhere, even in URLs. Use & (the ampersand character entity) instead. For more about character entities, see the Character entities section above.
<hr> tags have no size or width attribute, and can't be enclosed in <b>s (which we don't use anyway).
Every end tag gets a start tag (the reverse isn't always true), and always remember to use the / (forward slash) in end tags.
Don't wrap <blockquote>s or list tags (<ol>s, <ul>s, <dl>s) in <p>s.
You can't put header tags in <li>s or <p>s, but you can put them inside <blockquote>s inside <li>s.
Opening and closing <xtra>s are required in all KBML docs.
Attribute values (e.g., the value for "type" in <ol type="a">) must be in quotes unless they contain only letters and numbers. It's best to always put quotes around attribute values.
Don't use </li> to end list items. When you do this, you have to be sure to not place any additional tags or text between it and the next tag that's part of the list, i.e., the next <li> tag or a tag that ends the list like </ol>. So for convenience, just don't use them.
Do not place anything inside <noheat> tags except for a URL. This doesn't actually violate KBML, but it will break some KB scripts.
Character entities (e.g., <, &) must be used in <kbq>s when appropriate, but do not use any KBML tags (such as <code>s or <em>s) in <kbq>s.
Remember to place any example URLs (URLs which are not really meant to be hyperlinked, such as "http://www.deathstar.gov"), in <noheat> tags. For more, see the <noheat> section above.
Be sure that the ending text of a document, right before the </body> tag, is either part of a paragraph, or of a list, or else has a <br> tag at its end. Otherwise there will be no blank line between the end of a document and the line "This is document xxxx in domain sc.", at the bottom. (Boilers for the Services Directory break this rule deliberately.)
When creating internal anchors (for a table of contents, usually), do not use "search" as the name of your anchor. That is reserved for kbpresent; an <a href="#search"> link will point to the search box rather than your anchor. (This also appears to apply to "login", which will point to the login/logout area at the top of the page.)
Always look at a document in a web browser before concluding that you are finished editing it. Improperly formatted documents can cause a server error.

It's not exactly an error, but we need to be careful with anchor tags used in conjunction with <h3> and <h4> tags, so that the headers display properly. When you're creating internal anchors that are associated with a header (e.g., when creating a table of contents), make sure that the </a> tag comes immediately after the <a name> tag, for example:

  <a name="options"></a><h3>Options for the parboil command</h3>

Some upcoming changes

In the future we will need to use only lowercase text for KBML tags and attributes, and to close all tags. It's best to get in the habit now of using only lowercase text for tags and attributes, and to make sure all tags are closed (except for <li> tags, as noted in the Errors section above).

When we move to XML, we'll also need to be sure that every piece of text is enclosed in some kind of tags, so keep an eye out for, e.g., paragraphs of text within a list that are set off with <br> tags rather than being properly enclosed in <p> tags, and fix them as you come across them. Boilers with names beginning servdir are an exception to this guideline. To make the Services Directory display properly, the text inside servdir boilers has no <p> tags, and for now this is all right.

`<kba docid="yyyy" qline="box">`	Displays "box" title
`<kba docid="yyyy">`	Displays "oncoursecl" title, from the parent doc