如何从 JavaDoc 生成 PDF(包括概述和包摘要) [英] How to generate a PDF from JavaDoc (including overview and package summaries)
问题描述
我已经为我的应用程序编写了大量 JavaDoc 文档，并在 overview.html 和 package.html 文件中添加了许多有用的信息(包括前者的插图链接在 doc-files/ 中).Maven 的 Javadoc 插件很好地使用了标准的 javadoc 工具来生成经典的 JavaDoc 框架集，但现在我需要生成包含整个文档的 PDF.
I have written extensive JavaDoc documentation on my application, and added lots of useful info at overview.html and package.html files (including links on the former to illustrations in doc-files/). Maven's Javadoc plugin nicely uses the standard javadoc tool to generate the classic JavaDoc frameset, but now I need to generate a PDF with the whole documentation.
AurigaDoclet 生成非常漂亮的 PDF，我能够制作 DocFlex 也适用.但是，两者都忽略了我的 overview.html 和 package.html 文件(在 Maven 内部和外部都尝试过——PDF 将是一次性的，因为我宁愿从长远来看，拥有 HTML).
AurigaDoclet generates very pretty PDFs, and I was able to make DocFlex work also. However, both ignore my overview.html and package.html files (tried both inside and outside Maven - the PDF will be a once-only thing, since I'd rather have the HTMLs on the long run).
有谁知道如何让 AurigaDoclet 识别我的非 Java 文件?或者，另一种方法是从源代码或 JavaDoc 生成的 HTML 生成看起来不错的 PDF?
Does anyone know how to make AurigaDoclet recoginze my non-Java files? Or, alternatively, another to generate a decent-looking PDF from either the source code or the JavaDoc-generated HTML?
推荐答案
搞定了.在尝试了所有可能的工具直接从源代码生成之后，我返回到 HTMLDOC.它不是 JavaDoc 感知的，但它构建得非常好，只需进行一些调整就足以使其生成一个非常有用的 PDF.
Nailed it. After trying all the possible tools to generate straight from the source, I returned to HTMLDOC. It is not JavaDoc-aware, but it is so well built that a few tweaks are enough to make it generate a pretty usable PDF.
这里是我是如何做到的一步一步的描述:
Here goes a step-by-step description of how I did it:
在发布页面上下载软件；
以您喜欢的方式生成您的传统 HTML 文档(Ant、Maven、命令行 javadoc - 您的选择)；
Generate your traditional HTML docs in your preferred way (Ant, Maven, command-line javadoc - your choice);
GUI 很好，但手动添加所有文件可能很麻烦，因此只需创建一个文档类型设置为网页"的 .book 文件，从生成的 javadoc 的根文件夹中添加一个 HTML 文件(例如，overview-summary.html，任何人都会做，仅供第5步参考).在输出"选项卡上，选择 PDF 格式并为其设置名称，然后为您的内容添加其他选项(徽标、颜色、这里有很多很酷的东西).保存这个项目(比如，myjavadocpdf.book)并关闭 GUI
The GUI is nice, but adding all files manually can be cumbersome, so just create a .book file with Document Type set to "Web Page", add one of the HTML files from your generated javadoc's root folder (e.g., overview-summary.html, anyone will do, it's just for reference on step 5). On the Output tab select the PDF format and set a name for it, and add other options to your heart's content (logos, colors, lots of cool stuff here). Save this project (say, myjavadocpdf.book) and close the GUI
在您的 javadoc 中生成所有 HTML 文件的列表.我是用 Cygwin 的 find 命令完成的(我的 DOS/cmd shell 时代已经过去了)，但是你可以做任何你想做的事情，只要你得到一个文件列表.在我的情况下是 find .|grep html$ |排序 -r >files.txt 做到了；对于 Windows 用户，dir/s/b *.html >files.txt 应该做同样的事情(但请记住，如果 s 在下一步中看起来像这样，您可能需要将 s 替换为 /s).
Generate a list of all HTML files in your javadoc. I did it with Cygwin's find command (my DOS/cmd shell days are long over), but you can do anything you want, as long as you get a file list. In my case a find . | grep html$ | sort -r > files.txt did the trick;
For Windows users, dir /s/b *.html > files.txt should do the same (but keep in mind you may have to replace s with /s if they appear like so on the next step).
在您最喜欢的纯文本编辑器中打开在第 3 步中生成的 .book 文件(作为程序员，您应该对此有强烈的看法，所以我会保留自己的看法 - NOT ;-) ) 并将第 4 步生成的列表附加到这个 .book 文件中(它将文件列表保留在最后，让生活变得真正简单).不要忘记修复相对路径，如果需要使用全局搜索/替换(这就是为什么您需要在第 3 步中至少添加一个文件 - 以查看 htmldoc 需要哪种文件路径模式)；
Open the .book file generated on step 3 in your favorite pure text editor (as a programmer you should have strong opinions on that, so will keep my opinions to myself - NOT ;-) ) and append the list generated on step 4 to this .book file (it keeps the list of files at the end, making life really easy). Don't forget to fix the relative paths, if needed with a global search/replace (that's why you needed at least one file added on step 3 - to see which file path pattern htmldoc expects);
现在您应该按照方便的顺序对文件进行排序.我把我的概述放在最前面，然后是包描述和每个类，然后是完整的索引，最后是其他所有内容.请记住，您删除的任何文件都将成为外部(因此已损坏)链接，因此请明智地选择；
Now you should sort the files in a convenient order. I put my overview first, then package descriptions and each class, then the full index, and everything else at the end. Remember that any file you delete will become an external (hence broken) link, so choose wisely;
保存您的 .book 文件并在 HTMLDOC 上重新打开它.瞧:添加和排序的所有文件.点击生成.就是这样！
Save your .book file and re-open it on HTMLDOC. Voila: all files added and sorted. Click on generate. That's it!
您可能想要摆弄图像(提示:使用 HTML 宽度/高度，而不是样式/css).最后，生成的文件出奇地好:外观漂亮且完全可导航内部和外部链接.当您认为该工具根本不了解 Java(Doc) 时，这令人印象深刻...
You may want to fiddle with images (hint: use HTML width/height, not style/css). In the end, the resulting file is surprisingly good: nice looking and fully navigable for internal and external links. Impressive when you consider that the tool is not Java(Doc) aware at all...
软件现在不受原作者的影响；更新的链接，谢谢@mohammed
software is now free from original author; updated links, thank you @mohammed
这篇关于如何从 JavaDoc 生成 PDF(包括概述和包摘要)的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
