A help file is a small file system: a header, a directory and a set of internal files, each with a short header of its own. All numbers are little-endian.
File header
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
| 0 | 4 | u32 | Magic | Always 0x00035F3F: the bytes 3F 5F 03 00 |
| 4 | 4 | u32 | DirectoryStart | The offset of the directory’s internal file header |
| 8 | 4 | u32 | FirstFreeBlock | The offset of the first free block, or 0xFFFFFFFF |
| 12 | 4 | u32 | EntireFileSize | The size of the whole file in bytes |
Internal file header
Every internal file, the directory included, starts with these 9 bytes. The content follows at once. A file can have spare room after its content.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
| 0 | 4 | u32 | ReservedSpace | Bytes reserved for the file, this header included |
| 4 | 4 | u32 | UsedSpace | Bytes of content |
| 8 | 1 | u8 | FileFlags | Normally 4 |
Free list
Space the compiler no longer needs is kept in free blocks, each pointing at the next.
| Offset | Size | Type | Name | Description |
|---|---|---|---|---|
| 0 | 4 | u32 | FreeSpace | The size of the block, this header included |
| 4 | 4 | u32 | NextFreeBlock | The offset of the next free block, or 0xFFFFFFFF |
Directory
The directory is an internal file whose content is a
B+ tree. Its keys are the names of the internal files,
and its values are the offsets of their headers from the start of the help file (structure
z4).
Names beginning with a vertical bar are the compiler’s own files. Names without it are files the help project asked to include as they are (baggage). Some Windows 3.0 files name their bitmaps without the bar.
The internal files
| Name | What it holds |
|---|---|
|SYSTEM | The compiler version, compression flags, title and settings |
|TOPIC | The text, in blocks of records |
|Phrases | The phrase table used to compress the text |
|PhrIndex, |PhrImage | The Hall compression tables, Windows 95 and later |
|FONT | The font list |
|CONTEXT | The hash of each context name and its topic |
|TTLBTREE | Each topic’s title |
|KWBTREE, |KWDATA, |KWMAP | The keyword index; other letters (|AWBTREE …) hold the indexes of other footnote letters |
|TOMAP | Windows 3.0: each topic number’s position |
|CTXOMAP | The numeric map used by applications to open a topic |
|bm0, |bm1 … | Pictures |
|CF0 … | Macros that run when a secondary window opens |
|Viola | Default window of each topic |
|Rose | Macros attached to search keywords |
|Petra | The source file each topic came from, when the compiler was asked to record it |
These names and meanings come from the HELPDECO notes. Indexes gives the layouts of the tables.
Checking the file
EntireFileSize and every internal file’s offset can be checked against the
size of the file. A help file whose size does not match, or whose directory points past
its end, has been cut short.