Creating index entries

Index entries are created by adding a special HTML anchor tag next to the target for the index entry. The anchor tag should start with the characters XE_ followed by a keyword. Keywords are collected into a file and are displayed in alphabetical order.

Keyword syntax

The syntax of a keyword is [prefix][level1][levelseparator][level2].

Each keyword starts with a prefix. The prefix is specified in the input file to the application. A keyword can consist of one or more levels. A keyword with more than one level is useful when you would like to group different keywords. After the prefix, the keyword at level one follows. If a keyword has more than one leve,l a separator between the levels is needed. The separator is specified in the input file to the application. Then the next level follows.

Remember: Space characters inside keywords must be replaced with "_" characters. In the generated index, "_" characters are converted back to space characters.

The following table shows examples of valid keyword definitions. The center column shows how the keywords are presented in the generated index.

Table 1. Syntax for index keywords
XE_Copyright Copyright <a name="XE_Copyright"></a>
XE_KeyWordIndex__Syntax_description XE_KeyWordIndex__Input_file_syntax KeyWordIndex       Input file syntax       Syntax description <a name="XE_KeyWordIndex__Syntax_description"></a> <a name="XE_KeyWordIndex__Input_file_syntax"></a>
XE_Users_guide__Chapter_1 XE_Users_guide__Chapter_2 Users guide       Chapter 1       Chapter 2 <a name="XE_Users_guide__Chapter_1"></a> <a name="XE_Users_guide__Chapter_2"></a>  

Keywords must be manually entered into the file that contains the index target. If you are using the rich text editor (RTE), switch to HTML editing mode to make these targets. Index targets are created by adding an HTML anchor tag in front of the index target. The general pattern is <a name="XE_ keyword"><a>. The previous table shows specific examples of this syntax.

Internal references

Index entries can point to other index entries rather than a page in the published site. These are basically internal references within the index itself. In the following example, the entry "software architect" under "roles" links to the second entry for "software architect," not to content page in the published site.

    roles        software architect        [...]     software architect         indexentry1         indexentry2

Internal references are collected in a separate file and follow a special syntax. Each line in the file consists of two keywords with a "tab character (\t)" separator. The first keyword refers to the second keyword in the resulting index. A keyword can only occur once, as a referring keyword, in the file. The second keyword is only allowed to be a one level keyword. The following table shows this relationship:

XE_KeyWord__Author XE_Author
XE_KeyWord__Copyright XE_Copyright

If the referring (second) keyword does exist in an HTML file, the index entry is named "See also ...". If the referring (second) keyword does not exist in an HTML file index entry will be named "See ...".

The previous example results in the following index.

Author Copyright KeyWord     Author, See Author     Copyright, See Copyright

Suppressing index generation

By default, published Web sites include an index, however, this feature can be cleared before publishing. If the check box Include index page is cleared, the published site will not include this feature. This check box is one of the publishing options in Publish Method Configuration.

Configuration file

The KeyWordMap application takes a number of parameters as input. These parameters are specified in a configuration file.

Each row in the configuration file defines one parameter. The order of the rows does not matter. Each part of a row is separated with a "tab character (\t)". The name of the parameters is not case-sensitive. Space characters to the left or right of an item will be removed.  

wwwroot d:/work/rup This is the top directory of the directory structure to traverse. Normally this is the top directory of the site. This parameter is mandatory.
relativepath .. Defines the relative path from where the result of this application is written to the files it refers to. If the result is written to a directory one level below the top of the site, this parameter has the value "..". This parameter is mandatory.
mainresultfile /index/index.htm If this parameter and the parameter "indexresultfile" is se,t a frameset is generated into this file. This is useful when the site contains many keywords. A faster navigation among the keywords is possible. The value of this parameter together with the value of the parameter "wwwroot" shall be a valid path for a file. This parameter is optional.
indexresultfile /index/navig.htm If this parameter and the parameter "mainresultfile" shortcuts to the first keyword of each letter will be generated into this file. A faster navigation among the keywords possible. The value of this parameter together with the value of the parameter "wwwroot" ise a valid path for a file. This parameter is optional.
keywordresultfile /index/contents.htm The actual keyword index is written into this file. The value of this parameter together with the value of the parameter "wwwroot" is a valid path for a file. This parameter is mandatory.
maintitle Index - Rational Unified Process The title of the main index page. This parameter is optional. The default value is "Index - Rational Unified Process".
target ory_doc The name of the target in which the html documents containing the actual keywords is to be shown. This parameter is mandatory.
indextarget index_t The name of the target in which the file defined by the parameter "indexresultfile" is written. This parameter is mandatory if the parameter "indexresultfile" is set.
keywordtarget keyword_t The name of the target in which the file defined by the parameter "keywordresultfile" is written. This parameter is mandatory if the parameter "keywordresultfile" is set.
indexheight 25 When the parameter "indexresultfile" is set, a frameset is created. This parameter defines the height (in pixels) of the frame in which the "indexresultfile" is shown. This parameter is mandatory if the parameter "indexresultfile" is set.
headerfile keywordpreamble.txt This parameter makes it possible for the user to customize this application as much as possible. This parameter is the name of a file that serves as the header for the file defined by the parameter "keywordresultfile". The value of this parameter is either a relative path from where this program is executed or an absolute path. This parameter is mandatory. If you use a cascading-styles-sheet file to control the layout of the index, then the headerfile must contain a link to that cascading-style-sheet file. 
footerfile keywordpostamble.txt This parameter makes it possible for the user to customize this application as much as possible. This parameter is the name of a file that serves as the footer for the file defined by the parameter "keywordresultfile". The value of this parameter is either a relative path from where this program is executed or an absolute path. This parameter is mandatory.
keywordfile keywords.txt This parameter defines the internal references within the index. For more information, see the Internal references. This parameter is optional.
leavedir _borders This parameter can occur in the definition file more than once. It is used to define which directories that will not be searched for keywords. The path is relative to the directory defined by the parameter "wwwroot". This parameter is optional.
mulitdocumentkeyword false This parameter defines if a keyword is allowed to be in more than one document. The default value is false. This parameter is optional.
showdocumenttitle false This parameter defines if the text of the link to a document containing this keyword will be the name of the keyword or the title of the document. Default is false. True is only applicable if the value of the parameter "mulitdocumentkeyword" is set to true. This parameter is optional.
prefix XE_ With this parameter you can define the prefix of the keywords this application will search for. This parameter is optional. The default prefix is "XE_".
levelseparator __ With this parameter you can define the separator between different levels in a keyword this application will search for. This parameter is optional. The default levelseparator is "__".
see , See With this parameter you can define the text before a keyword when it is referring to another keyword. This parameter is optional. The default levelseparator is ", See".
seealso , See also With this parameter you can define the text inserted before a keyword when it is referring to another keyword. This parameter is optional. The default levelseparator is ", See also".
levelstyle levelstyle defaultstyle indexlevel2 1 indexlevel1 This parameter defines which style in a cascading style sheet (CSS) will be used to for the different keyword levels. The syntax to use is [keywordlevel/reservedname][stylename]. - [keywordlevel/reservedname] is either the level of the keyword (1, or 2, or 3, ...). Alternately you can use one of the two reserved names, ("defaultstyle" or "headlinestyle"). - [stylename] is the name of the style. The KeyWordIndex application adds a prefix "p." to the stylename. This means if the style sheet defines define styles for the classes "p.indexlevel1", and "p.indexlevel2", then [stylename] is "indexlevel1" or "indexlevel2". The attribute is optional but if you intend to use cascading style sheets you must specify at least a "defaultstyle". Use the file defined by the parameter "headerfile" to import the styles. You can choose not to use cascading style sheets (CSS). In that case you use the parameter "levelfont" to control format. See the parameter "levelfont".
levelfont levelfont defaultfont Arial Bold +2 1 Times Italic -1 This parameter defines which font that will be used to generate the different keywords. If you have defined any stylesheets, this parameter will be left unnoticed. If you have not specified any stylesheets, this parameter must to be used. The syntax [keywordlevel/reservedname][fontname][fontstyle][fontsize]. - [keywordlevel/reservedname] is either the level of the keyword or one of the reserved names, ("defaultfont" or "headlinefont"). - [fontname] is mapped to the "FACE" attribute of the HTML FONT attribute. - [fontstyle] is mapped to the "<B>" or "<I>" tags. Possible values are Bold, Italic and Plain. - [fontsize] is mapped to the "SIZE" attribute of the HTML FONT attribute. The attribute is optional but if you intend to use Font definition you have to specify at least a "defaultfont".