使用Maven创建用户指南文档

Question

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

我探讨两个选择：

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

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

Answer 1

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

• 简易造型使用yaml文件。 Default造型也很好。
• Asciidoc作为标记语言是非常好记载：Uder Guide AsciiDoc
• 具有良好的网上editors和语言比降价例如更强大，也更容易相较于XML格式来写。
• 好examples使用Maven和ascii文档并易于理解configurations。