1/09/2017

CHM, Help 1.x files missing Contents Index Search

CHM - Compiled HTML for Microsoft files can appear damaged or unreadable. But they are not, they are often distributed in multiple "pieces" rather than a "singular" name.chm file in older Microsoft PDK, SDK and DDK documentation. (accidentally) moving only the .chm file can result in missing functions when opening the .chm file for viewing.

For example:


The image has been deliberately "blurred" to protect the rights of the publisher. However the controls and navigation pane to the Left have not been "blurred".

You will notice that The usual [Contents][Index][Search] tabs are "missing" from the tab menu.

Typing "anything" into the [ Type in the keyword to find: ] then [List Topics] is equally useless:


The word "untitled" will be returned over and over in the topics list, and link nowhere.

The problem in this case is the directory contains only "one" file:

C:\doc>
|
\_directx.chm

But the original document directory in the original install folder contained:

C:\sdk documentation>
|
\_directx.chm
\_directx.chi


The "missing" .chi file is in fact an index file, and was intended to "separate" changable information from static information when distributing the files on CDROM. It is described somewhat in this old link to Microsoft HTML Help

When you recover or "move" the .chi file into the same directory as the .chm file it (automatically) indexes "on the fly" and the results are as expected (minus the "blurring" effect I added to the image).

That is the "expected" navigation controls on the Left return and are available again.


Also the "existence" of the .chi file causes a "new" file to be created when the .chm file is opened. In fact the procedure is that as soon as the .chm file is opened a compatible .chi file is searched for in the current directory and then a new .chw file is created if the directory is "writable" - this is described as a combined kwords file.. or "chw"ords file. "k" is often used to mean "Index" file in other CHM contexts.. so this could mean "Compile Help Index Words" or "Compile Help Key Words" to support the Index and Search tabs (without the extra "k").



Its further confusing that [some] in fact [many] files compiled in more recent years, especially by third party software programmers, include the index (inside) the single .chm file.

So those .chm file behave as if the .chi file were included in the current location, but are in fact "standalone".

This change in behavior really makes troubleshooting older documentation harder, especially since Compiled Help documentation (about the CHM format) is somewhat rare.. and the change in Help document formats and ramping up of Security blockades to disable and deprecate older Help file formats. -- there simply isn't a lot of care taken to "learn from the past" and "document for the future".

Note: further online research led to the tacky "political" situation between "Public" chm files and "Private" Internal Microsoft MSDN formats. HTML Help versions 1.x 2.x and 3 or 4,5 were on a very rocky road at the end of the last Century (1999-2000) and after announcing and "using internally" a new version of  CHM they basically cancelled and did not deliver. The result was a split or division between versions of CHM 1.x and 2.x (which was never released outside Microsoft). The MSDN Library released on CDROM would use this new "splitted" CHM/CHI/CHW version.. and apparently without formal notice the SDK, DDK documentation.. and perhaps Microsoft Press CDROMs.. but it was never formally documented.

Some people took to reverse engineering the new pseudo-unoffical/official format and came up with tools and "ways" of adding their own .CHM documents to the MSDN versions.. before the later versions of CHM.. so the internal strife were recognized and "patterned" around.. which is nothing new for this era with the company.

The CHM format appears abadonned, but maintained in more and more projects, outside the oversight of Microsoft.. and as they do not maintain much of a corporate history.. perhaps the less involvement and further they get from it the better. But the standard for CHM while not open, or well documented lives on. With only .MD or HTML markup showing a hint at replacing it on GitHub.