使用Maven创建用户指南文档

Question

我需要编写和构建易于维护，良好的浏览，以改变pdf和html 5格式的文档。源格式必须易于编辑。这个maven插件必须支持我的公司organziation theam（字体，颜色，图片等），TOC生成，不同文件中章节的分离，图像文件的集成，在文档中放置代码snipets的简便方法。我有Maven构建，我想知道当前最好的决策是什么？

我正在调查两个选项：

• Doxia - 使用md（markdown）作为输入格式。有WSWG md免费 编辑器，支持很多上述东西等。需要外部回购作为其工件。
• Asciidoctor - 使用asdcii doc作为输入格式。使用片段等支持模板。

使用此插件有哪些优点和不足之处？ 还有其他好的解决方案吗？

Answer 1

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

• 使用 yaml 文件轻松设置样式。 Default样式也非常好。
• 作为标记语言的Asciidoc 非常良好记录：Uder Guide AsciiDoc
• 有良好的在线editors，语言比降价功能更强大，与 xml 格式相比更容易编写。
• 使用Maven和ascii doc时很好examples，并且易于理解configurations。