Configuration Files

1. The master configuration file, named "mkhtm.ini" and located in the "icons" directory.

2. A local configuration file, located in the current working directory. The name of the local configuration file is set by the "configFile" setting in the master configuration file. Settings in the local configuration file override settings in the master configuration file. This allows each directory to have its own custom configuration.

Configuration files are entirely optional.

Each configuration file contains one or more lines in the following format:

key=string

The following is an alphabetical list of the available configuration file keys.

The following sections lists the valid configuration file settings:

Major Options

There are several different types of index files that can be generated. This option determines the type of index file that will be generated.

index=formatted	default

Creates a pre-formatted index. Preformatted indexes display a fixed list of links in a specific format. The "format" option determines the basic layout of the index, along with other formatting options which affect specific aspects of the layout.

index=sequence

This index type is used to display slides, when the slides must be viewed in a specific order. It does not display a list of links, but instead, it immediately displays a frameset which contains a navigation control panel frame and the first slide file in the directory. Slides can then be viewed sequentially using controls in the navigation control panel frame. This option requires the file "controls.htm" to be located in the "icons" directory. This option must be used with the "slides=window" option. When this option is used, all of the index formatting options are ignored. (frames/JavaScript)

index=searchable

Generates a searchable index using dynamic HTML (frames and JavaScript). The index will be dynamically generated based on keyword(s) entered by the user. This option requires the files "search.htm" and "content.htm" to be located in the "icons" directory. This option must be used with the "slides=window" option. When this option is used, all of the index formatting options are ignored. The "links" option is also ignored, and is automatically set to "open". In addition, the "backlink" option only supports the values "parent", "close", "back", and "URL". (frames/JavaScript)

There are several different types of slide files that can be generated. This option determines the type of slide files that will be generated in the current directory. Since each different slide file type has unique link requirements, this option also affects the way slide links are generated in the index file.

slides=html	default

The generated slide files are identical to the "slides=simple" option below. The index treats slide files no different than any other HTML files, and links to them as specified by the "links" option. This option should not normally be used unless there is a specific reason to do so. (HTML 2.0)

slides=simple

Slides are opened in the same window as the index. Each HTML slide file may contain a "next", "previous", and "home" link. Since HTML slide files contain positional information (links), they cannot be directly included in indexes outside the current directory (using "symlinks.txt"). Therefore, an alias file is automatically created for each remote directory a slide appears in. An alias file is a copy of the original slide file, but with links that are local to the directory in which it appears. (HTML 2.0)

slides=frameset

Slides are opened in the same window as the index. Slides are viewed via a navigation control panel frame. HTML slide files do not contain any navigational links. Instead, a "frameset.htm" file is generated which contains the list of slides. This requires the file "controls.htm" to be located in the icons directory. (frames/JavaScript)

slides=window

Slides are opened in a new window. Slides are viewed via a navigation control panel frame. HTML slide files do not contain any navigational links. Instead, the index file contains the list of slides. This requires the files "controls.htm" and "slides.htm" to be located in the icons directory. (frames/JavaScript)

Each index may have a backlink, which is a link to the parent index of the current index. The backlink appears at the top of the index. This option determines the type of backlink that will be generated.

backlink=none

Creates an index with no backlink.

backlink=parent	default

Creates a text backlink to the parent index, using the parent index title. (HTML 2.0)

backlink=keywords

Creates multiple text backlinks to the parent and each keyword index. (HTML 2.0)

backlink=back

Creates a backlink button which works the same as the browser's "Back" button. (JavaScript)

backlink=smart

Creates a backlink button which links to the referring document. Because of incomplete implementation of JavaScript and cookies, this will not work with Internet Explorer 4.0 or earlier. It is compatible with Internet Explorer, but the behavior will be the same as "backlink=parent". It works fine with Netscape 2.0 or later. (JavaScript/cookies)

backlink=close

Creates a backlink button which closes the current window. (JavaScript)

backlink=URL

Creates a backlink button which links to the specified URL. (HTML 2.0)

Each index may contain a mixture of links to both slide files and other HTML files (including index files). This option determines the way in which links to HTML files (non-slide files) are generated. This option does not affect links to slide files (see the "slides" option). This option is only used if "index=formatted".

links=standard	default

Uses standard links to HTML files. Standard links open the linked document in the same window as the index. (HTML 2.0)

links=open

Opens a new window whenever a link is selected for an HTML file.

Enables the CGI mode of the "mkhtmidx" utility. CGI mode uses the Common Gateway Interface (CGI) to generate indexes dynamically.

When this mode is used, the list of files and directories that can appear in the index is obtained from an index database file which is generated by the "mkhtmidb" utility. The index database file, "index.db", must be located in the current directory or one of its parents (up to 4 levels down). The actual list of links that appear in the generated index is determined by the CGI parameters which define the matching criteria. The index generated by the "mkhtmidx" utility is sent to stdout instead of being written to the file "index.htm", and contains the appropriate content-type header line.

CGI=yes

CGI mode is enabled.

CGI=no	default

CGI mode is disabled.

Index Formatting Options

Uses an index template file to specify the exact format of the index body. This allows full control over the index layout. If the template option is not used or if the template file does not exist, the system will format the index automatically using the default format.

template=filename

Where,  filename is the name (and optional directory path) of the index template file. If filename does not include a path, then the system looks in the "icons" directory for this file. You can use ".\filename" to specify the current directory.

Determines the layout of a formatted index. If the "combine=no" option is used (default), then this option only affects the appearance of the first section in the index (links to directories). The second section will always appear in the single-column description list format (see "format=list" below), unless the "format2" option is used. If the "combine=yes" option is used, this option will determine the layout of the entire index.

format=column

Use the multi-column table format when displaying links to subdirectories. Each link to a subdirectory will display the title and description of the subdirectory's index file, and the optional thumbnail. Each row will normally contain 2 entries, but the number of entries per row can be changed by using the "columns" option.

format=compact

Use the compact table format when displaying links to subdirectories. Each link to a subdirectory will display the thumbnail for the subdirectory, and the title of the subdirectory's index file. Each row will normally contain 6 thumbnails, but the number of thumbnails per row can be changed by using the "columns" option.

format=list

Use the single-column description list format for all entries. Each link will display the title and description of the item on a separate line. Thumbnails will be displayed for links to subdirectories that contain them.

format=thumbnail

Use the thumbnail-only format for all entries. Each link will display only the thumbnail for the directory. If a directory does not contain a thumbnail image, it will not be included in the index. Thumbnails are laid out horizontally, using the full width of the browser window. There are no fixed columns.

format=auto	default

Automatically select one of the formats above.

format=format

Uses a table format with a specific format string which defines the way in which table entries will appear.

Determines the layout of the second section of a formatted index. This affects the way in which links to single HTML files and slides appear. By default, the second section is formatted in the single-column description list format (see "format=list" above) This option is ignored if the "combine=yes" option is used.

format2=format

Where,  format is the format string.

Specifies the number of columns to display in the index. This option is only available if "format=column", "format=compact", or "format=format".

columns=number

Where,  number is the number of columns from 1 to 9 (default = 2).

Specifies the width, in pixels, of the first field in each index entry. This option is only available if "format=column", "format=compact", or "format=format".

columnWidth=pixels

Where,  pixels is the width of the title column in pixels (default = automatic).

Specifies the width, in pixels, of all fields after the first in each index entry. This option is only available when the "format=format" option is used.

columnWidth2=pixels

Where,  pixels is the width of subcolumn 2 in pixels (default = automatic).

Specifies the padding, in pixels, between fields in an index entry. This option is only available when the "format=format" option is used.

iPadding=pixels

Where,  pixels is the padding in pixels (default = 8 pixels).

Specifies the padding, in pixels, between the columns in a multi-column index. This option is only available when the "format=format" option is used.

hPadding=pixels

Where,  pixels is the padding in pixels (default = 8 pixels).

Specifies the padding, in pixels, between the rows in the index. This option is only available when the "format=format" option is used.

vPadding=pixels

Where,  pixels is the padding in pixels (default = 8 pixels).

combine=yes

Combine files and directories into a single list.

combine=no	default

List links to subdirectories in a separate section which preceeds links to non-directories (slides and individual HTML files) in an index. The format of the subdirectory links can be specified using the "format" option.

Specifies whether HTML tables may be used or not.

tables=yes	default

HTML tables may be used.

tables=no

HTML tables will not be used. Instead, a simple unordered list will be used. This option will override any specific table format specified with the "format" option, however you may still use the "format=format" and "format2=format" options.

Specifies whether thumbnails will appear in the index or not.

thumbnails=yes	default

Thumbnails may appear in the index.

thumbnails=no

Thumbnails will not appear in the index. This option may override any specific table format specified with the "format" option.

Other Options

Specifies the attributes to be used in the HTML "BODY" tag for the index and all slides. This allows you to set a background color or image, and to specify the text and link colors. This option is just a shortcut that combines the "indexBody" and "slideBody" options.

body=none

Specifies that no attributes should be used in the HTML "BODY" tag for the index and all slides. If this option is used, any existing attributes will be removed from the index and slide files.

body=attributes

The attributes are inserted directly into the HTML "BODY" tag as follows: <BODY attributes>.

Specifies the attributes to be used in the HTML "BODY" tag for the index. This allows you to set a background color or image, and to specify the text and link colors. See also "slideBody" and "body".

body=none

Specifies that no attributes should be used in the HTML "BODY" tag for the index. If this option is used, any existing attributes will be removed from the index file.

body=attributes

The attributes are inserted directly into the HTML "BODY" tag as follows: <BODY attributes>.

Specifies the attributes to be used in the HTML "BODY" tag for all slides. This allows you to set a background color or image, and to specify the text and link colors. See also "indexBody" and "body".

body=none

Specifies that no attributes should be used in the HTML "BODY" tag for all slides. If this option is used, any existing attributes will be removed from the slide files.

body=attributes

The attributes are inserted directly into the HTML "BODY" tag as follows: <BODY attributes>.

This option may be used in a master configuration file to specify the name of the local configuration files. A local configuration file may exist in each subdirectory, and overrides any options specified in the master configuration file. If this is not specified, then the system will not use local configuration files. This option is ignored if it appears in a local configuration file.

configFile=filename

Where,  filename is the name of the local configuration file.

Specifies whether JavaScript may be used or not.

JavaScript=yes	default

JavaScript may be used.

JavaScript=no

JavaScript will not be used. This option overrides all other options that may use JavaScript for specific features. It guarantees that no JavaScript will be used in the generated HTML files.

Causes the slide images to be scaled when displayed. This option is only available if "slides=html" or "slides=simple".

scale=height

Specifies the height that the browser should scale all slide images to. The height may be either the number of pixels (e.g. scale=480) or a percentage of the current window height (e.g. scale=90%). The height is inserted directly into the HTML "IMG" tag as follows: <IMG HEIGHT="height" SRC="...">.

scale=width,height

Specifies that all slide images should be scaled down to fit within a rectangular area no larger than width × height pixels in size. Scaling will always occur integrally (e.g. 1/2, 1/3, 1/4, ...) so that the image will still look smooth (no "jaggies") when viewed close-up.

This option causes slide files to be generated and used for files with the specified extension. Typically, this is used for video files such as ".avi", ".mov", and ".mpg" files. This option may appear multiple times in a configuration file -- once for each file type to be embedded.

embed=extension

Where,  extension is the file name extension of a file type to be embedded in a slide file (e.g. ".mov").

This option adds the specified file name to the reserved file name list. Reserved file names are not added to an index file if they exist in the directory being indexed. Slide files are not generated for reserved image file names. This option may appear multiple times in a configuration file -- once for each reserved file name, however you are limited to a maximum of about ten reserved file names. This option is typically used in the master configuration file to reserve a file name in all directories (e.g. an alternate thumbnail image file name), but may also be used in a local configuration file to reserve a file name in the current directory only.

reservedFile=filename

Where,  filename is the file name to be reserved. It may be either an HTML file name or an image file name.

This option specifies an alternate image file name that will be displayed as a thumbnail if it appears in a subdirectory which is referenced by this index file. When an index is generated, the system normally searches each referenced subdirectory for the standard thumbnail image files "thumb.gif" and "thumb.jpg". By adding an alternate image file name, it searches for the specified image file name first, and uses that image as the thumbnail if it finds it. Otherwise, it searches for the standard thumbnail image file names. This option may appear multiple times in a configuration file -- once for each thumbnail file name, however you are limited to a maximum of about five thumbnail file names. If this option appears more than once, the last occurence takes precidence over previous occurences (search order is last to first).

This option does not affect the thumbnail image file name that appears in the automatically generated header for the current index. It also does not reserve the thumbnail file name in the current directory. You must use the "reservedFile" option to do that. This option only affects which thumbnails appear in the index body (list of links). This option is typically used in a local configuration file to specify which thumbnails appear in that index when alternate thumbnails are available (e.g. different size or different content).

thumbFile=filename

Where,  filename is the thumbnail image file name.

Sample Master Configuration File

index=formatted
slides=window
links=open
backlink=close
format=auto
configFile=makeindx.bat
embed=avi
embed=mov
embed=mpg
embed=mpeg
embed=rm