单源文档工具

Question

什么OSS（或免费）工具可用于起草可用于生成手册的文档的单一来源？具体来说，采用以下格式：

• HTML网站
• PDF文件
• 嵌入式（在应用程序中;可能是HTML）1
• 文字（可选）
• 手册页（可选）

其他要求：

• 工具适用于技术作者（不必是WYSIWYG）。
• XML / SGML源代码
• 高质量PDF输出（与TeX相当）
• 多平台

扩大要求1

相同的命令行应用程序用两种语言（C和Java）编写。使用XML来描述命令行选项（其中一些特定于一种语言或另一种语言），可以直接将XML转换为Java类或C函数，该函数将帮助写入标准输出。这确保了可以将帮助嵌入到二进制文件中，而不必依赖于外部文件。

看来AsciiDoc没有这种能力。还有其他选择吗？

Answer 1

满足你的大多数要求，我以前用过的是AsciiDoc。

但是，AsciiDoc不是XML源格式，而是选择简单的文本格式。它可以输出HTML和Docbook，可以呈现为PDF或其他格式。源文本也足以用于纯文本呈现。

另一个流行的选择是reStructuredText。

Answer 2

我一直在考虑在我们的工程团队中传播DocBook作为Word的替代品。有许多工具链可用。工程师最简单的可能是DocBook XSL，Apache FOP，以及Ant或Make。这就是我一直在做我的DocBook的东西。如果您真的喜欢LaTeX，那么您可能需要查看DBLaTeX以获取DocBook到LaTeX发布环境。

如果你不介意走出自由环境，那么<oXygen/> XML Editor提供了一个非常好的WYSIWYG DocBook编辑器。我没有那么多使用它，但它确实看起来非常有前景。

Answer 3

Doxygen是文档生成器，非常受欢迎，可以在variety of formats中输出文档。虽然它的主要目的是构建从源注释中提取的文档（来自众多语言），但它也可以作为一般的手动编写工具使用。实际上，Doxygen网站和手册都是以这种方式生成的。

Answer 4

Sphinx是一个为Docutils添加许多功能的工具，允许在reStructuredText中编写“智能和漂亮的文档”。它最初是为了生成新的Python文档而创建的，但正被许多其他项目采用。