Toolkit: KeyWordIndex

Process Engineer Toolkit > User's Guide > Tools Reference > KeyWordIndex

The syntax of a keyword
Define keyword in an HTML file
Internal Index References File
Configuration file
How to execute the application

The KeyWordIndex application is very useful to create an index of keywords for a Web site. The KeyWordIndex application traverses a directory structure containing HTML files. Within each HTML file the application searches for keywords. A keyword is an anchor tag where the name is of the syntax described below. All found keywords are collected to a file. The keywords are displayed in alphabetical order. For an example of the result of the KeyWordIndex application see.

The syntax of a keyword

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. To have a multileveled keyword 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 level a separator between the levels is needed. The separator is specified in the input file to the application. Then the next level follows. And so on ... If a keyword contains a space character it has to be replaced with a "_" character. In the final output from the application the "_" character is replaced with a space character. All levels in a keyword identifies the keyword.

Here follows some examples of valid keyword definitions. In the right column you can see examples of how the keywords will be presented in the final index.

keyword syntax		resulting index
XE_Copyright XE_KeyWordIndex__Syntax_description XE_KeyWordIndex__Input_file_syntax XE_Users_guide__Chapter_1 XE_Users_guide__Chapter_2		Copyright KeyWordIndex Input file syntax Syntax description Users guide Chapter 1 Chapter 2

Defining keywords in an HTML file

The keywords are entered into the HTML file where you want the index entry to refer to.

You use the A-tag (the A-tag is sometimes referred to as a "bookmark" or "anchor") to enter keywords into the HTML files; for example "<A name="XE_KeyWord"> </A>" For example, the keywords above will look as follows in the HTML code:

HTML code

Internal Index References File

Sometimes you want an entry in the index not to point to a specific file. Instead you want to the index entry to point somewhere else in the index file. These are internal references within the index itself.

For example, in the small index-example below, the entry roles/software architect below will bring you to the entry software architect, and not to another HTML page.

    software architect
        bla
        blo
    roles
       software architect

These "internal references" are collected in a separate text file, and follows a special syntax. Each line in the file consists of two keywords with a "tab character (\t)" separator. The first keyword will refers to the second one in the resulting index.

A keyword can only occur once, as a referring key word, in the file. The second keyword is only allowed to be a one level keyword. For example,

XE_KeyWord__Author	XE_Author
XE_KeyWord__Copyright	XE_Copyright

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

The example above will result in the following little index.

Author
Copyright
KeyWord
Author, See Author
Copyright, See Copyright

Configuration File

The KepyWordMap 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 are not case sensitive. Space characters to the left or right of an item will be removed.

Below is an example of how a configuration file may look.

wwwroot
relativepath
mainresultfile
indexresultfile
keywordresultfile
maintitle
target
indextarget
keywordtarget
indexheight
headerfile
footerfile
keywordfile
leaveDir
mulitdocumentkeyword
showdocumenttitle
prefix
levelseparator
see
seealso
levelstyle
levelstyle
levelstyle
levelstyle

d:/work/rup
..
/index/index.htm
/index/navig.htm
/index/contents.htm
Index - Rational Unified Process
ory_doc
index_t
keyword_t
25
keywordpreamble.htm
keywordpostamble.htm
keywords.txt
_borders
false
false
XE_
__
, See
, See also
defaultstyle
1
2
headlinestyle

indexlevel2
indexlevel1
indexlevel2
indexheading


Name of the parameter	Example value	Description
wwwroot	d:/work/rup	This is the top directory of the directory structure to traverse. Normally this is the top directory of the whole 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 parameters shall have the value "..". This parameter is mandatory.
mainresultfile	/index/index.htm	If this parameter and the parameter "indexresultfile" is set a frameset will be generated into this file. This is useful when the site contains huge number of keywords. A faster navigation among the keywords 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" shall be 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" shall be 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	To make it possible for the user to customize this application as much as possible this parameter exists. This parameter is the name of a file that will serve 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	To make it possible for the user to customize this application as much as possible this parameter exists. This parameter is the name of a file that will serve 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. See the Internal Index References File for more details. 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 shall 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 shall 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 shall 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 shall search for. This parameter is optional. The default levelseparator is "__".
see	, See	With this parameter you can define the text inserted infront of a keyword when it is reffering to another keyword. This parameter is optional. The default levelseparator is ", See".
seealso	, See also	With this parameter you can define the text inserted infront of a keyword when it is reffering 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) that shall 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, ...etc.) or 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 have to 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. please See the parameter "levelfont" for details.
levelfont levelfont	defaultfont Arial Bold +2 1 Times Italic -1	This parameter defines which font that shall 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 have to be used. The syntax is [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".

How to execute the application

Read the System Requirements to understand what is needed to execute this application.

To execute the KeyWordIndex as a Java application type:

java -classpath ../../ruptools/RUP.jar ruptools.KeyWordIndex -r keywordconfigfile.txt -c ASCII -h helpfile.txt

The parameters can be entered in any order.
-r	The file defining the behaviour of the application.
-l	The file with language dependent messages Parameter is optional.
-c	The characterset to use when reading input. Default is local characterset. Parameter is optional.
-h	File containing text to make the output from the application language dependent. Parameter is optional.

Rational Unified Process