HTML Help Workshop is installed with 2 main executables:
hhc.exe is the console version of the HTML Help Compiler.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:
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.
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.
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.)
