cmd - 成功编译 .chm 文件后 HTML Help Workshop 返回错误

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 询问当前的错误级别，它会输出:

"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

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

问题是我的构建服务器(TFS2015)返回错误并且构建失败。

Answer 1

HTML Help Workshop 安装有 2 个主要可执行文件:

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

但是 HTML 帮助项目 (hhp) 到编译 HTML (chm) 的编译并不是由这两个可执行文件直接完成的。

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

该库导出的函数有:

• 编辑HhCtrlObject
• 编辑HhCtrl脚本
• FreeFilterDIB
• HHA_CompileHHP
• 加载滤镜图像
• 加载Jpeg

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

我假设通过 hhc.exe 进行一些快速测试该功能 HHA_CompileHHP有BOOL作为返回类型，即 int并成功返回 TRUE ，即值 1 ，以及失败时FALSE ，即值 0 。它看起来像 hhc.exe使用此返回值而不反转该值作为退出/返回代码。

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

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

1. 使用不存在的项目文件名运行 HTML 帮助编译器:

   hhc.exe index_1.hhp
   

   Unable to open index_1.hhp.

   退出代码分别为errorlevel为 0。此错误消息由 hhc.exe 打印因为错误信息可以在 hhc.exe 中找到.

2. 在现有输出文件上设置只读文件属性 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 中找到.

3. 重命名 index.hhp 中明确指定的 *.htm 文件并运行 HTML 帮助编译器:

   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 。除了 0 或 1 之外，从来没有其他值分配给 errorlevel。这就是为什么我认为函数 HHA_CompileHHP返回一个简单的 bool 值。

结论:

必须像往常一样执行相反的操作来评估 HTML 帮助编译的成功/失败，例如通过在批处理文件中使用:

"%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重定向到日志文件会更容易，尽管这也不是真正的之所以需要，是因为 Team Foundation Server 很可能正在将消息捕获到日志中。 (我没有安装 Team Foundation Server。)