Compiled CHM file fails to open

Please post all questions and comments regarding Help & Manual 7 here.

Moderators: Alexander Halser, Tim Green

Post Reply
Stefan Malz
Posts: 13
Joined: Tue Nov 28, 2006 5:18 pm

Compiled CHM file fails to open

Unread post by Stefan Malz »

Hi.

One of our H&M files is a documentation frequently updated and extended.

After a small change today (adding two topics) the resulting CHM can no longer be opened. We compiled the H&M file using the Microsoft Help Compiler and the compilation itself seems to work fine. Here are the compiling results:
#Help & Manual command line compiler version 7.5.3 build 4740
Compiling x:\mkcad6\mki_lib6\mki_lib6.hmxz
[Info] Preparing topics
[Info] Preparing table of contents
[Info] Preparing project files
[Info] Preparing merged projects
[Info] Writing topics
[Info] Compilation of x:\mkcad6\mki_lib6\mki_lib6.hmxz started 22.01.2021 13:23:36
[Compiler Results] Help compiler started: C:\Program Files (x86)\HTML Help Workshop\hhc.exe
[Info] Compiling help file
[Compiler Results] Microsoft HTML Help Compiler 4.74.8702 Compiling X:\mkcad6\mki_lib6\mki_lib6.chm Compile time: 0 minutes,
7 seconds 2,002 Topics 25,598 Local links 1 Internet link 44 Graphics Created X:\mkcad6\mki_lib6\mki_lib6.chm, 4,896,5
19 bytes Compression decreased file by 10,998,750 bytes.
[Info] Compilation complete
Switching back to the source file version of yesterday and compiling again, everything works fine. When adding only ONE topic to the old file, is also works. But when adding the SECOND topic, the resulting CHM file cannot be opened. Windows reports:
"Cannot open the file: mk:@MSITStore:X:\mkcad6\mki_lib6\mki_lib6.chm."
There are no errors or warnings during compilation. Computer runs Windows 10 (64 bit), latest edition.

If this a known limitation or error in the Microsoft Help Compiler or the CHM format? Any idea what we can try so solve this?

Best regards
Stefan Malz
John Johann
Posts: 305
Joined: Mon Aug 21, 2017 7:35 pm

Re: Compiled CHM file fails to open

Unread post by John Johann »

Hi Stefan,
One of my projects has over 3000 topics so that shouldn't be a problem. Just takes a while :-).
Did you try publishing the second topic separately just on its own to see if there is something broken in it?
Stefan Malz
Posts: 13
Joined: Tue Nov 28, 2006 5:18 pm

Re: Compiled CHM file fails to open

Unread post by Stefan Malz »

Hi John,

The last working edition of the file has 2.001 topics. After adding ANY one new topic (regardless of location in TOC and textual content), the Help Compiler still compiles without error, but Windows fails to open the resulting CHM file. So it cannot be content-related.
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Compiled CHM file fails to open

Unread post by Tim Green »

Stefan Malz wrote: Sat Jan 23, 2021 3:20 pm So it cannot be content-related.
It will definitely be content related -- not the amount of content but something in the content.

There are a number of possible causes for CHM failures of this kind. The Microsoft CHM system is ancient and was essentially abandoned by Microsoft directly after its release with Windows 98. It has not been updated since then and still includes all its original bugs and quirks. It is an embarrassment, both to Microsoft and to developers who use it, because of its anachronistic, unconfigurable viewer, its lack of support for Unicode and high-resolution displays, its dated appearance that makes programs it is used with look dated as well, and its many arcane incompatibilities and uncorrected bugs

So here are the possible causes (I'm including all of them here for the sake of completeness, even those that are probably not relevant in your case):

Output Path, Output Drive:

This is unlikely to be the the cause in your case. The Microsoft CHM system often has problems with specific characters and combinations of characters in path, folder and file names. It will also fail to display correctly on external drives, network drives and mapped drives (external or network drives assigned to a local drive letter on your computer). To be sure of being able to test correctly after compiling, always publish to a folder on your local computer with a short, simple name, like \Documents\Help\ for example.

Note that CHM is a local help system only. Windows blocks it on external drives, network drives and the Internet for security reasons.

Illegal and Special Characters:

Another frequent cause for problems like this is illegal characters in the path to the CHM file, the CHM file name or topic IDs in your project. ​The entire CHM system is highly allergic to special characters in file names and paths to CHM files. Spaces in folder names are OK, but there should be no spaces in the name of the CHM file itself. Accented characters and non-alphanumeric characters like # or the ' apostrophe in paths, filenames or topic IDs ​will almost always result in failure.

Both the name of your project and the IDs of all the topics in your project (which you can check in the Topic Options tab) should avoid spaces, accented characters and all non-alphanumeric characters. The best policy is to use only A..Z, a..z, 0..9 and the _ underscore character in all file names and topic IDs.

Damaged CHM Compiler:

For reasons that are still unknown, the Microsoft CHM compiler can occasionally spontaneously become damaged or lose its configuration settings. The only solution for this is to uninstall and reinstall the MS HTML Help Workshop compiler package, which you can download with this link:

https://www.helpandmanual.com/download/htmlhelp.exe

First uninstall HTML Help Workshop in the Windows Control Panel. Then restart Windows and reinstall with the installer from the link above.

Important Note: During the installation you will get a misleading message telling you that you "already have a newer version of HTML Help". Ignore this. This only refers to the components for displaying HTML Help, which the package would like to install as well. Since it dates from 1998, all Windows versions now have newer versions of these components so they are not needed. This has nothing to do with the compiler, which is always installed. ;-)

Open Help & Manual and check in View > Program Options > Compilers (HM5 and later) or Tools > Customize > Compilers (HM4 and earlier) that the path to the hhc.exe CHM compiler program is correct.

Invalid image file formats:

​Failures can also be caused by graphics files that the (very ancient and creaky) Microsoft CHM compiler cannot handle correctly. This happens most frequently with BMP files that were saved with a graphics program that uses a non-standard encoding for BMP like run length encoding (RLE). However, it can also occur with other image files and is sometimes also related to the image file name.

This is an ancient bug in the Microsoft CHM compiler that can appear at any time. We can't predict when and where it will occur, because neither we nor Microsoft know what causes it (at least, MS isn't saying). Strangely, the bug will often NOT occur on hardware from Microsoft like the Surface series (so maybe they do know what causes it).

This is the procedure for locating the image that causes the problem:

1. Move all the images to a temporary folder that is not in the project search path.
2. Compile to CHM. Turn the option "Delete temporary files" ON when you do this! (Otherwise the images from the previous compiles will be available in the temp folder and will sabotage the test.)
3. Add a small group of images to the folder and recompile. Repeat until the error occurs.
4. Remove all the images from the last batch except one and recompile.
5. Add the remaining images from the last batch one by one and recompile until the error occurs. Now you have one culprit.
6. Repeat steps 3-5 to make sure there aren't any more problematic images.

Then load the culprit images into a current graphics program (Impict is fine for this) and re-save them. If that fixes it then everything is fine. Otherwise you will also need to change their names. We have see​n​ both the internal format and the image file name and a combination of the two cause this bug. However, there is no rhyme or reason to it and no discernible pattern in the names that trigger the bug.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Stefan Malz
Posts: 13
Joined: Tue Nov 28, 2006 5:18 pm

Re: Compiled CHM file fails to open

Unread post by Stefan Malz »

Thank you for this information.

Amazingly, it was indeed an image problem - although we did neither add nor change an image for more than a year. Applying your method for binary search of the troubling images, we identified two images out of about 50 in the whole project. After converting them from PNG to JPG format, the resulting CHM file can be opened again. Very strange...

Best regards
Stefan Malz
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Compiled CHM file fails to open

Unread post by Tim Green »

Stefan Malz wrote: Tue Jan 26, 2021 8:27 am After converting them from PNG to JPG format, the resulting CHM file can be opened again. Very strange...
Yes, CHM suffers from many strange and mysterious bugs. It is an ancient Windows 98 system that has never been updated and only works at all because current versions of Windows have been patched to accommodate it. :?
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Post Reply