单一来源文档工具答案

【问题标题】：Single source documentation tool单一来源文档工具
【发布时间】：2010-11-19 23:31:23
【问题描述】：

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

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

附加要求：

工具适合技术作家（不必是所见即所得）。
XML/SGML 源
高质量的 PDF 输出（与 TeX 相当）
多平台

扩展要求¹

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

AsciiDoc 似乎没有这个能力。还有其他选择吗？

【问题讨论】：

标签： java pdf-generation documentation-generation

【解决方案1】：

满足您大部分要求的我以前使用过的一个是AsciiDoc。

AsciiDoc 不是 XML 源格式，而是选择简单的文本格式。它可以输出 HTML 和 Docbook，可以渲染成 PDF 或其他格式。源文本也几乎足以用于纯文本演示。

另一个类似的流行选择是reStructuredText。

【讨论】：

AsciiDoc 看起来很棒。您将如何将其与命令行应用程序集成？
一种方法可能是使用描述应用程序命令行选项的 XML 源文件，然后通过转换运行该文件，该转换为应用程序的特定配置（C 或 Java）生成 AsciiDoc 源，仅选择适当的部分）。听起来 AsciiDoc 不是生成实际 C/Java 源代码的正确工具。我会为此使用不同的工具。但是，为您的命令行帮助的所有呈现提供一个通用的 XML 源，听起来确实是件好事。

【解决方案2】：

我一直在考虑宣传 DocBook 作为我们工程组中 Word 的替代品。有许多可用的工具链。对于工程师来说最简单的可能是DocBook XSL、Apache FOP，或者Ant 或Make。这就是我一直在做我的 DocBook 工作的方式。如果您真的很喜欢 LaTeX，那么您可能想查看 DBLaTeX 了解 DocBook 到 LaTeX 的发布环境。

如果您不介意跳出免费环境，那么<oXygen/> XML Editor 提供了一个非常不错的 WYSIWYG DocBook 编辑器。我没怎么用过，但看起来确实很有前途。

【讨论】：

DocBook 非常适合编写手册，它允许您自动保留大量有关文本的元数据。我相信 O'Reilly 的技术书籍是用 DocBook 编写的。
在编写DocBook的时候，还有Maven docbkx-plugincode.google.com/p/docbkx-tools可以用来制作HTML/pdf/等。

【解决方案3】：

Doxygen 是非常流行的文档生成器，可以在variety of formats 中输出文档。尽管它的主要目的是构建从源 cmets（来自多种语言）中提取的文档，但它也可以用作通用的手动编写工具。其实Doxygen网站和手册就是这样生成的。

【讨论】：

【解决方案4】：

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

【讨论】：