HTML Help Workshop returns error after successfully compiled .chm file

Question

I'm facing a quite weird failure after I successfully compiled a .chm file with HTML Help Workshop's hhc.exe.

I created a documentation of my source code with Doxygen. Doxygen creates if you enable GENERATE_HTMLHELP in the doxygen file:

If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three
additional HTML index files: index.hhp, index.hhc, and index.hhk. The index.hhp
is a project file that can be read by Microsoft's HTML Help Workshop (see:
http://www.microsoft.com/en-us/download/details.aspx?id=21138) on Windows.

After Doxygen creates those files, I want to create the .chm file with HTML Help Workshop. For that reason I call hhc.exe in a CMD. After that I can open the .chm file and everything seems fine. But if I ask the CMD for the current errorlevel, it outputs:

"C:\Program Files (x86)\HTML Help Workshop\hhc.exe" index.hhp
Microsoft HTML Help Compiler 4.74.8702

Compiling C:\... folder path ...\index.chm

Compile time: 0 minutes, 0 seconds
37      Topics
346     Local links
12      Internet links
0       Graphics

Created C:\... folder path ...\index.chm, 88,740 bytes
Compression decreased file by 194,682 bytes.

echo %errorlevel%
1

Does anyone have an idea of what the h... is going wrong here and how I can avoid that problem that it's compiled successfully but still returns an error? How can I figure out what's the problem instead of an error "1"?

The problem is that my build server (TFS2015) returns the error and the build is failed.

Answer 1

HTML Help Workshop is installed with 2 main executables:

1. hhc.exe is the console version of the HTML Help Compiler.
2. hhw.exe is the Windows GUI version of HTML Help Compiler.

But the compilation of the HTML Help Project (hhp) to Compiled HTML (chm) is not directly done by those two executables.

Both use for compilation hha.dll - the HTML Help Author library - by calling the exported function HHA_CompileHHP.

The exported functions of this library are:

• EditHhCtrlObject
• EditHhCtrlScript
• FreeFilterDIB
• HHA_CompileHHP
• LoadFilterImage
• LoadJpeg

Microsoft has not published any documentation nor the function declarations of those functions as far as I know.

I suppose from some quick tests with hhc.exe that the function HHA_CompileHHP has BOOL as return type which is int and returns on success TRUE, i.e. the value 1, and on failure FALSE, i.e. the value 0. And it looks like hhc.exe uses this return value without inverting the value as exit/return code.

Therefore the errorlevel is 1 on success and 0 on failure.

The tests I made to verify my assumption:

1. Run HTML Help compiler with name of a project file which does not exist:

   hhc.exe index_1.hhp
   

   Unable to open index_1.hhp.

   The exit code respectively errorlevel is 0. This error message is printed by hhc.exe because the error message can be found in hhc.exe.

2. Set read-only file attribute on already existing output file index.chm and run HTML Help compiler:

   attrib +r index.chm & hhc.exe index.hhp & attrib -r index.chm
   

   HHC5010: Error: Cannot open "C:... folder path ...\index.chm". Compilation stopped.

   The exit code respectively errorlevel is 0. This error message is printed by hha.dll because this error message can be found only in hha.dll.

3. Rename a *.htm file explicitly specified in index.hhp and run HTML Help Compiler:

   ren "file.htm" "renamed file.htm" & hhc.exe index.hhp & ren "renamed file.htm" "file.htm"
   

   Microsoft HTML Help Compiler 4.74.8702
   
   Compiling C:... folder path ...\index.chm
   
   HHC5003: Error: Compilation failed while compiling file.htm.
   
   The following files were not compiled:
   file.htm

   The exit code respectively errorlevel is 0. This error message is printed also by hha.dll because this error message can be found also only in hha.dll.

All error messages are written to handle STDOUT and not to STDERR as typical for console applications. There was never another value than 0 or 1 assigned to errorlevel which is the reason why I suppose the function HHA_CompileHHP returns a simple boolean value.

Conclusion:

The opposite as usual must be done to evaluate on success/failure of an HTML Help compilation for example by using in the batch file:

"%ProgramFiles(x86)%\HTML Help Workshop\hhc.exe" index.hhp
if not errorlevel 1 exit /B 1

In HTML Help Project file (*.hhp file) in section [OPTIONS] a log file can be specified with Error log file=... into which all messages output by HHA_CompileHHP are written additionally to printing them to STDOUT.

But in this case with Doxygen generating the *.hhp file it would be easier to redirect STDOUT in the batch file to a log file although this is also not really needed because most likely the Team Foundation Server is capturing the messages already to a log. (I don't have Team Foundation Server installed.)