单源文档工具

Question

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

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

其他要求：

• 工具适合技术作家（不必是WYSIWYG）。
• XML / SGML来源
• 高质量PDF输出（与TeX相当）
• 多平台

扩展需求 ¹

相同的命令行应用程序用两种语言（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文档而创建的，但正被许多其他项目采用。