Html Help Workshop Returns Error After Successfully Compiled .chm File

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 cre

Solution 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
ifnot errorlevel 1exit /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.)

Solution 2:

HTML Workshop is a GUI program. When using CMD interactively it does not wait for GUI programs to exit. Therefore there is no error code.

Echo %errorlevel% interactively will never show an error code as well.

This two ways will

Dir && Echo Success || Echo Failure

Dir df:\ & Echo %errorlevel%

[See my answer at Trouble with renaming folders and sub folders using Batch to see what it means]

You will have to read HTML Workshop's documentation to see if it sets an errorlevel. Most GUI programs don't bother.