5.6. INI formats

5.6.1. Preface

INI files are text files with CRLF line endings. They are divided into uniquely named sections. The beginning each of section is denoted by a line of the following form: "[section type]" where section type is a series of words. Each section type is followed by lines up to the next section that specify data for that section and each different section type may have a different format.

There are two main types of format following the section type: Each line is variable = value[, value]… Each line is a just an EOL terminated string.

Also any line beginning with a semicolon (;) is a comment and will be ignored. NOTE that the author (who has since left MS) of MS' chm compiler (HHC & HHA) has said that it is only safe to put comments before any section names have been specified (ie at the start of the file). Tests with HHW 1.3 (HHA Version 4.74.8702), however indicate that it is safe to put comments on any line. This may not be true for older versions, however.

The following variables are used below in the description of values in the different format descriptions:

bool

Yes|No

decimal number

(0|1|2|3|4|5|6|7| 8|9)…

hex number

0x(0|1|2|3|4|5|6| 7|8|9|a|b|c|d|e| f|A|B|C|D|E|F)…

number

hex number|decimal number

string

Any character (usually alphanumerics plus underscore) repeated up to the terminator (usually EOL, also '=' or '"')

path

Similar to string, but a file with the same name should exist

5.6.2. HHP format

5.6.2.1. Preface

The HHP or HTML Help Project format is used by MS' HTML Help Workshop (HHW) to compile CHM files. There are various titbits of info out there on the web, in Usenet & in the docs for various programs. So far I have not found a complete reference for this format.

These files have the INI format.

HHW dies if any line is 1024 or more characters (not including CRLF).

5.6.2.2. Sections

5.6.2.2.1. [OPTIONS]

This is a variable=value section sorted by variable name (using memcmp), except for Custom tab, which occurs at the end.

Table 5.50. Explanations for all the different [OPTIONS] that are displayed and preserved by HHW.

Variable & type[a] Explanation Recommended setting Default  
Auto Index= bool When this is on the compiler will remove any KLinks from the HTML files & place them in the index. KLinks are essentially the <object> tags, with the appropriate attributes <param> tags.   No  
Auto TOC= number This uses the heading tags in your HTML files to generate the contents. The number is the maximum level of tag to place in the contents. eg 1 = <h1>, 2 = <h2>, 9 = <h9> WARNING: HHW modifies your HHC file if you specify this. IMO this is a bug: HHW should just slurp through a pipe or temporary file.   No  
Binary Index= bool   Yes Yes  
Binary TOC= bool   Yes No  
CITATION= string Doesn't seem to have any effect.      
COMPRESS= number Doesn't seem to have any effect.      
COPYRIGHT= string Doesn't seem to have any effect.      
Compatibility= 1.0|1.1 or later Anything other than 1.0 is treated as 1.1 or later 1.1 or later 1.1 or later  
Compiled file= path     hhp stem.chm  
Contents file= path The name HHW gives to new files is Table of Contents.hhc      
Create CHI file= bool     No  
DBCS= bool If you find any thing about this please tell us. No  
Default Font= string , number , number The string is the name of the font, the first number is the point size & the last number is the character set used by the font. For acceptable values see *_CHARSET defines in wingdi.h from the Windows SDK or the same file in MinGW or Wine. Also see this Knowledge Base page. Most of the time you will only want to use 0, which is the value for ANSI, which is the subset of ASCII used by Windows.      
Default Window= string There is no default, but when you add a window definition HHW will change this.      
Default topic= path If there are any files in the [FILES] section then the default for this option will be the first one.      
Display compile notes= bool        
Display compile progress= bool        
Enhanced decompilation= bool     No  
Error log file= path        
Flat= bool If this is on then all the files will be stored in the root directory of the CHM. This means that each file in the CHM must have a unique name, otherwise one may overwrite the other. No No  
Full text search stop list file= path The name of a text file containing a list of words that are not to be placed in the ful-text search index.      
Full-text search= bool Set this to Yes if you want the CHM compiler to add a Full-text serch index to the CHM. Yes No  
IGNORE= string Doesn't seem to have any effect.      
Index file= path The name HHW gives to new files is Index.hhk      
Language= hex number string The hex number is an LCID & the optional string is the name of the language and sub-language that the hex number corresponds to.   OS ?thread?user?system? LCID.  
PREFIX= string Doesn't seem to have any effect.      
Sample Staging Path= path This must be samples or any upper-case variation of it or this feature will NOT work.      
Sample list file= path        
TMPDIR=string        
Title= string The string to put on the title bar.      
Custom tab=" string ", string Can put multiple lines of this option to define more than one custom tab.      

[a] The following were strings in hha.dll & were accepted by HHW, but it didn't display or preserve them: Word Breaker, PredefinedSubsets, EnableStructuralSubsetting, FTS for untitled topics, Information Types=path, Index separators, DAT FILE, URL ROOT, REPLACE, VERSION, WARNING, ROOT, BUILD, BMROOT. If you find out their meaning or find any more please tell us about them.

5.6.2.2.2. [WINDOWS]

This is a variable=value section sorted by order of addition.

Each line has the following format:

string =" string ", " path ", " path ", " path ", " path ", " path ", " string ", " path ", " string ", number , number , [ number , number , number , number ], number , number , number , number , number , number , number

Table 5.51. Summary of the arguments for each [WINDOWS] entry.

Argument number[a] Explanation
0 The window type.
1 The title bar text.
2 The TOC file.
3 The Index file.
4 The Default file.
5 The file shown when the Home button is pressed.
6 The file shown when the Jump 1 button is pressed.
7 The text of the Jump 1 button.
8 The file shown when the Jump 2 button is pressed.
9 The text of the Jump 2 button.
10 A bit feild of navigation pane styles.
11 Width of the navigation pane in pixels.
12 A bit field of the buttons to show.
13 Initial position of the window on the screen: [left, top, right, bottom].
14 Style Flags. As set in the Win32 SetWindowLong & CreateWindow APIs.
15 Extended Style Flags. As set in the Win32 SetWindowLong & CreateWindowEx APIs.
16 Window show state. As set in the Win32 ShowWindow API. SW_HIDE works well - don't use it. The following are buggy in HH 1.31: SW_SHOWMINIMIZED, SW_MINIMIZE, SW_SHOWMINNOACTIVE - grey toolbars, no nav pane or HTML display when unminimized; SW_MAXIMIZE - maximizes the navigation pane, if present; SW_FORCEMINIMIZE - works same as SW_HIDE, when should just minimize.
17 Whether or not the navigation pane is initially closed. 1 = closed, 0 = open
18 The default navigation pane. 0 = TOC, 1 = Index, 2 = Search, 3 = Favorites, 4 = History (not implemented by HH), 5 = Author, 11-19 = Custom panes.
19 Where the navigation pane tabs should be. 0 = Top, 1 = Left, 2 = Bottom & anything else makes the tabs appear to be behind the pane on Win95.
20 ID to send in WM_NOTIFY messages.

[a] HHW currently accepts only 21 arguments. If you find any more please tell us about them.

Table 5.52. Buttons to put in the HH toolbar.

Value[a] Explanation Recommended setting
0x00000002 Hide/Show button hides/shows the navigation pane. On
0x00000004 Back button. On
0x00000008 Forward button. On
0x00000010 Stop button. On
0x00000020 Refresh button. On
0x00000040 Home button. On
0x00000080 Next button. Not implemented by HH. Off
0x00000100 Previous button. Not implemented by HH. Off
0x00000200 Notes button. Not implemented by HH. Off
0x00000400 Contents button. Not implemented by HH. Off
0x00000800 Locate button. Jumps to the current topic in the contents pane. On
0x00001000 Options button. On
0x00002000 Print button. On
0x00004000 Index button. Not implemented by HH. Off
0x00008000 Search button. Not implemented by HH. Off
0x00010000 History button. Not implemented by HH. Off
0x00020000 Favorites button. Not implemented by HH. Off
0x00040000 Jump 1 button. Customised using argument 7 of the [WINDOWS] entry. Either
0x00080000 Jump 2 button. Customised using argument 9 of the [WINDOWS] entry. Either
0x00100000 Font button. Changes the size of the text shown in the IE HTML display pane. On
0x00200000 Next button. Jumps to the next topic in the contents pane. Requires Binary TOC to be on. On
0x00400000 Previous button. Jumps to the previous topic in the contents pane. Requires Binary TOC to be on. On

[a] The rest of the buttons either do nothing or are unknown. If you find out what others do please tell us.

Table 5.53. Navigation pane styles.

Value[a] Explanation Recommended setting
0x00000001 Automatically hide/show tri-pane window: when the help window has focus the navigation pane is visible, otherwise it is hidden. Off
0x00000002 Keep the help window on top. Off
0x00000004 No title bar Off
0x00000008 No default window styles (only HH_WINTYPE.dwStyles) Either
0x00000010 No default extended window styles (only HH_WINTYPE.dwExStyles) Either
0x00000020 Use a tri-pane window On
0x00000040 No text on toolbar buttons On
0x00000080 Post WM_QUIT message when window closes Off
0x00000100 When the current topic changes automatically sync contents and index. On
0x00000200 Send tracking notification messages Off
0x00000400 Include search tab in navigation pane On
0x00000800 Include history tab in navigation pane Off
0x00001000 Include favorites tab in navigation pane On
0x00002000 Put current HTML title in title bar On
0x00004000 Only display the navigation window Off
0x00008000 Don't display a toolbar Off
0x00010000 MSDN Menu Off
0x00020000 Advanced FTS UI. On
0x00040000 After initial creation, user controls window size/position On
0x00080000 Use custom tab #1 Off
0x00100000 Use custom tab #2 Off
0x00200000 Use custom tab #3 Off
0x00400000 Use custom tab #4 Off
0x00800000 Use custom tab #5 Off
0x01000000 Use custom tab #6 Off
0x02000000 Use custom tab #7 Off
0x04000000 Use custom tab #8 Off
0x08000000 Use custom tab #9 Off
0x10000000 The window type has a margin On

[a] The rest of the navigation pane styles either do nothing or are unknown. If you find out what others do please tell us.

5.6.2.2.3. [MERGE FILES]

This is a list of CHMs to merge this one with. See the Merge Files feature in the features list for more information. Help 2 only used Collections to merge CHMs. HHA Version 4.74.8702 will crash if there are more than 1148 entries in the merge files list (could be a mem thing, but probably not). Note that the internal file formats only allow storage of 1004 entries in the internal binary merge files list. Any lines that begin with a comment character (;), after any whitespace, are ignored. Any whitespace at the end or start of a filename is stripped away.

5.6.2.2.4. [FILES]

This is a list of files that should be compiled into the CHM by the compiler. Files linked to from the TOC or Index or other HTML files will also be compiled into the CHM. It is known that Help 2 only compiled files listed to be put in the CHM.

5.6.2.2.5. [TEXT POPUPS]

This is a list of text files and header files that contain the text for various popups that can be displayed using the Popup command of the HH ActiveX control.

5.6.2.2.6. [INFOTYPES]

It is unknown how this section is formatted since the current version of HHW refuses to output anything in this section. I guess that the help viewer doesn't yet implement this feature. If you find a past or future version that does output this section please let us know.

5.6.2.2.7. [MAP]

Each line has the following format:

#define string number or #include path

5.6.2.2.8. [ALIAS]

This is a variable=value section sorted by the numerical value of the variable.

Each line has the following format:

number|string = path ; This is a comment or #include path

5.6.2.2.9. [SUBSETS]

It is unknown how this section is formatted since the current version of HHW refuses to output this section. I guess that the help viewer doesn't yet implement this feature. If you find a past or future version that does output this section please let us know.

5.6.3. HHS format

HHS (HTML Help Samples) files are used by MS' HTML Help Workshop (HHW) to compile samples into CHM files. At the time of writing there was a single titbit of info out there on the web.

Below is an example of a HHS file

[Example1]
ID=Example1
DistributionMediaDestination=MyProject\Example1
DefaultClientCopyDestination=\MyProject\Example1
SourceLocation=Samples\Example1\

5.6.4. SFL format