HTML Help Workshop returns 成功编译 .chm 文件后出现错误

Question

在使用 HTML Help Workshop 的 hhc.exe 成功编译 .chm 文件后，我遇到了一个非常奇怪的失败。

我用 Doxygen 创建了我的源代码文档。如果在 doxygen 文件中启用 GENERATE_HTMLHELP，Doxygen 将创建：

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.

在 Doxygen 创建这些文件后，我想使用 HTML Help Workshop 创建 .chm 文件。出于这个原因，我在 CMD 中调用了 hhc.exe。之后我可以打开 .chm 文件，一切似乎都很好。但是如果我向 CMD 询问当前的 errorlevel，它会输出：

"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

有没有人知道这里出了什么问题，以及如何避免编译成功但仍然 returns 错误的问题？我怎样才能找出问题所在而不是错误“1”？

问题是我的构建服务器（TFS2015）returns错误，构建失败。

Answer 1

HTML Workshop 是一个 GUI 程序。当以交互方式使用 CMD 时，它不会等待 GUI 程序退出。因此没有错误代码。

Echo %errorlevel% 交互式也永远不会显示错误代码。

这两种方式都会

Dir && Echo Success || Echo Failure

Dir df:\ & Echo %errorlevel%

[在 Trouble with renaming folders and sub folders using Batch 上查看我的回答以了解其含义]

您必须阅读 HTML Workshop 的文档以查看它是否设置了错误级别。大多数 GUI 程序都不会打扰。

Answer 2

HTML Help Workshop 安装了 2 个主要可执行文件：

hhc.exe 是 控制台 版本的 HTML 帮助编译器。
hhw.exe 是 Windows GUI 版本的 HTML 帮助编译器。

但是HTML Help Project (hhp) 到Compiled HTML (chm) 的编译并不是由这两个可执行文件直接完成的。

两者都用于编译 hha.dll - HTML 帮助作者库 - 通过调用导出函数 HHA_CompileHHP.

本库导出的函数有：

编辑HhCtrl对象
编辑HhCtrlScript
FreeFilterDIB
HHA_CompileHHP
LoadFilterImage
加载Jpeg

据我所知，Microsoft 尚未发布任何文档或这些函数的函数声明。

我假设通过hhc.exe的一些快速测试，函数HHA_CompileHHP具有BOOL作为return类型，它是int 和 return 成功时 TRUE，即值 1，失败时 FALSE，即值 0。看起来 hhc.exe 使用此 return 值而不将值反转为 exit/return 代码。

因此 errorlevel 成功时 1 失败时 0。

我为验证我的假设所做的测试：

运行 HTML 帮助编译器提供一个不存在的项目文件名：
```
hhc.exe index_1.hhp
```
Unable to open index_1.hhp.

退出码分别errorlevel为0。这个错误信息是hhc.exe打印的，因为错误信息可以在hhc.exe.
[=114中找到=]
在已经存在的输出文件上设置只读文件属性index.chm和运行HTML帮助编译器：
```
attrib +r index.chm & hhc.exe index.hhp & attrib -r index.chm
```
HHC5010: Error: Cannot open "C:... folder path ...\index.chm". Compilation stopped.

退出码分别errorlevel为0。此错误信息是由hha.dll打印出来的，因为此错误信息只能在hha.dll.
重命名在 index.hhp 和运行中明确指定的 *.htm 文件 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

退出代码分别errorlevel为0。此错误消息也由hha.dll打印，因为此错误消息也只能在hha.dll.
中找到

所有错误消息都被写入处理 STDOUT 而不是控制台应用程序的典型 STDERR。除了分配给 errorlevel 的 0 或 1 之外，再也没有其他值，这就是为什么我认为函数 HHA_CompileHHP return 是一个简单的布尔值的原因。

结论：

必须执行与往常相反的操作来评估 HTML 帮助编译的 success/failure，例如在批处理文件中使用：

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

在 HTML 帮助项目文件（*.hhp 文件）的 [OPTIONS] 部分中，可以使用 Error log file=... 指定日志文件，其中 HHA_CompileHHP 输出的所有消息另外将它们打印到STDOUT.

但是在这种情况下，使用 Doxygen 生成 *.hhp 文件，将批处理文件中的 STDOUT 重定向到log 文件，尽管这也不是真正需要的，因为 Team Foundation Server 很可能已经将消息捕获到日志中。（我没有安装 Team Foundation Server。）

HTML Help Workshop returns 成功编译 .chm 文件后出现错误

HTML Help Workshop returns error after successfully compiled .chm file

cmd

doxygen

html-help-workshop