使用 Maven 创建用户指南文档

Question

我需要编写和构建易于维护、美观、易于更改 pdf 和 html 5 格式的文档。源格式必须易于编辑。这个 maven 插件必须支持我的公司组织（字体、颜色、图片等）、TOC 生成、不同文件中的章节分离、图像文件的集成、将代码片段放入文档中的简单方法。我有 Maven 构建，我想知道目前最好的决定是什么？

我正在调查两个选项：

• Doxia - 使用 md(markdown) 作为输入格式。有免费的 WSWG md 编辑器，支持很多前面提到的东西，等等。需要外部仓库来保存它的工件。
• Asciidoctor - 使用 asdcii 文档作为输入格式。支持使用片段等进行模板化。

使用这个插件有什么好处和坏处？ 还有其他好的解决方案吗？

Answer 1

从我尝试首先使用 Doxia 然后使用 AsciiDoc 构建文档的尝试中，我意识到 Asciidoc 更好。它允许

• 使用 yaml 文件轻松设置样式。 Default造型也很不错。
• Asciidoc 作为一种标记语言非常有据可查：Uder Guide AsciiDoc
• 有很好的在线editors，语言比markdown更强大，比xml格式更容易写。
• 很好的examples 与 Maven 和 ascii doc 一起使用并且易于理解 configurations。