Index (.Hxk) File

Defines the content and organization of an index in a compiled Help (.HxS) file. The markup in the XML-based index (.HxK) file defines the overall properties of the index for the collection, as well as the properties for each individual entry.

An index provides an efficient way to find information based on specific keywords. An .HxK file is used to create the indexes in your Microsoft Help 2 projects. One or more of the following index types are commonly included in a project:

• Keyword

• Associative link

• Context-sensitive Help

• Named URL

Example

The following example shows the basic structure of an index file.

Note

The file consists of tags, each of which contains one or more attributes.

Choose an attribute to see its corresponding topic.

Comments indicate which attributes are required.

Where applicable, defined choices are displayed in parentheses.

All attribute values must be enclosed in quotation marks.

As with all XML documents, the tags and attributes in this file are case-sensitive.

<?xml version="1.0"?>

<!DOCTYPE HelpIndex SYSTEM "MS-Help://Hx/Resources/HelpIndex.dtd">

<HelpIndex

   Name Attribute = "" <!-- Required -->

   Id Attribute = ""

   DTDVersion Attribute = "1.0" <!-- Required -->

   FileVersion Attribute = ""

   AutoInclude Attribute = (Yes | No)

   Merge Attribute = (Yes | No)

   Sort Attribute = (Yes | No)

   UnsortedIndexLoc Atrribute = ""

   Title Attribute = ""

   Visible Attribute = (Yes | No)

   LangId Attribute = ""

   Font Attribute = ""

   FontSize Attribute = ""

   Charset Attribute = ""

   PrefixChars Attribute = ""

>

<Keyword <!-- Can appear 0 or more times -->

   Term Attribute = "" <!-- Required -->

   Ref Attribute = ""

>

   <Jump <!-- Can appear 0 or more times -->

      Url Attribute = "Topic1.htm" <!-- Required -->

   />

</Keyword>

<ToolData <!-- Can appear 0 or more times -->

   Name Attribute = "" <!-- Required -->

   Value Attribute = "" <!-- Required -->

/>

</HelpIndex>

Remarks

The <HelpIndex> tag defines the general options for the entire index, and can appear only once per document, while the <Keyword> tags can appear as often as required. The <ToolData> tag is optional.

There are three types of index entries, as follows:

• Keyword

  These entries link to one or more topics. Each topic associated with the entry is represented by a <Jump> tag, which contains the required URL for navigation. A typical keyword entry looks like this:

  <Keyword
     Term = "queries, using"
     >
     <Jump
        Url = "UseQueries.htm"
     />
  </Keyword>
  

• Cross-reference

  These entries link directly to another entry whose keyword term is specified in the Ref attribute. When a user clicks a cross-reference entry in a viewer, they are taken to the entry specified in the Ref attribute. A typical cross-reference entry looks like this:

  <Keyword
     Term = "Addresses, see URLs"
     Ref = "URLs"
     >
  </Keyword>
  

• Placeholder

  These entries act as a heading for one or more second-tier subentries, each of which is defined by a child <Keyword> tag. Each subentry is indented one level in the final index. A typical placeholder entry looks like this:

  <Keyword
     Term = "ActiveX Controls"
     >
     <Keyword
        Url = "MenuControl.htm"
        Title = "Menu Control"
     />
     <Keyword
        Url = "LinkControl.htm"
        Title = "Link Control"
     />
  </Keyword>
  

The type of entry is defined by the combination of child tags contained in the parent <Keyword> and </Keyword> tags. The following table summarizes the logic used to determine index entry type.

An "X" indicates that the <Keyword> tag contains this attribute or child tag.

"Ignored" indicates that if this attribute or child tag is present, it is ignored.

Entry Type	Jump Attribute	Ref Attribute	Child <Keyword> Tag
Keyword	X	Ignored	Ignored
Cross reference		X	Ignored
Placeholder			X

Note

The respective values assigned to the Id, Name, and Font attributes should not exceed 49 characters. The value assigned to the Title attribute should not exceed 149 characters. If these limits are exceeded, the value is truncated. The compiler does not issue an error or warning at this time.

The value assigned to the Name attribute should contain only valid XML NMTOKEN characters, as defined by the W3C XML specification. If invalid characters are used, the index file may function incorrectly. For more information, see the XML specification on the W3C Web site (http://www.w3.org).

Because comma, semicolon, and colon characters are used to define the index, they need to be escaped. The escape sequence is used when you want the actual character to appear in the term, without affecting the layout of the index. For example, the term ".bmp files, editing;graphics" would result in the following index entries:

.bmp files

&nbsp;&nbsp;&nbsp; editing

graphics

The term ".bmp files%2C editing%3B graphics" would result in the following index entry:

.bmp files, editing; graphics

The following table shows the escape sequences to use.

Character	Escape sequence
comma (,)	%2C
semicolon (;)	%3B
colon (:)	%3A

See Also

Reference

Help XML Tags

Other Resources

Help XML Attributes