| 5.6. INI formats | ||
|---|---|---|
 |
Chapter 5. Formats | 
|
| 5.6. INI formats | ||
|---|---|---|
|
|
Chapter 5. Formats |
|
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:
Yes|No
(0|1|2|3|4|5|6|7| 8|9)…
0x(0|1|2|3|4|5|6| 7|8|9|a|b|c|d|e| f|A|B|C|D|E|F)…
hex number|decimal number
Any character (usually alphanumerics plus underscore) repeated up to the terminator (usually EOL, also '=' or '"')
Similar to string, but a file with the same name should exist
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).
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. | ||||
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. | ||
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.
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.
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.
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.
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
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.5. XML formats |  |
5.7. Sitemap formats |