编写和维护印刷文档的工具[关闭]答案

【问题标题】：Tool to write and maintain printed documentation [closed]编写和维护印刷文档的工具[关闭]
【发布时间】：2009-12-28 10:42:15
【问题描述】：

我们的一些客户要求提供适合打印格式的最终用户文档。目前，我使用 Microsoft Word 2002 编写文档，并使用非免费 PDF 打印机生成带有可搜索书签的 PDF 文件。然后我将这两个文件存储在 Subversion 存储库中。虽然它可以完成这项工作，但它有一些缺点：

它对版本控制不友好。更具体地说，我无法在分支之间移植更改，而且很难处理徽标或屏幕截图等品牌内容。
我有时会忘记生成输出所需的一些手动步骤，并且 PDF 文件中缺少目录。

我需要一个在 Windows 上工作的工具，允许维护同一文档的并行分支，提供处理图像的简单方法（外部文件将是一个加号）并生成具有可搜索书签的高质量PDF文件。如果它是免费的或开源的，并且具有合理的学习曲线，我也将不胜感激。

目标是为 PHP 驱动的 Intranet 站点制作可打印的最终用户手册，我不是在寻找在线文档或 API 文档工具。你有什么建议？

【问题讨论】：

标签： svn version-control pdf documentation

【解决方案1】：

这可能有点矫枉过正，但我推荐 LyX。它是一个跨平台、OSS、用户友好的 LaTeX 前端。

文档的“源”文件采用文本和版本控制且易于合并。而且直接使用 LyX 代替 LaTeX 在学习曲线方面是一个很大的优势。

我们已经将它用于小组文档，并且在版本控制中合并的能力是一个真正的好处。

【讨论】：

我需要做进一步的测试，但 LyX 看起来是一个有吸引力的选择。 LaTeX 是一个完善的工具，似乎可以满足我的需求。

【解决方案2】：

我喜欢 DocBook + 你首选的 SCM 工具 (Subversion) 来完成这类工作。可以从单一来源生成 html 和 pdf 输出（使用 xsl 转换 + 一些 FOP 处理器）。 DocBook 上手并不简单，但它确实很强大。

【讨论】：

这似乎是 Subversion 团队用于他们的“使用 Subversion 进行版本控制”一书的内容。我将来可能会研究它，但 XML 有点吓到我 ;-)

【解决方案3】：

我建议使用 LaTeX 和良好的工作流程脚本或 Makefile（例如，Google 代码上的 latex-makefile 项目）来处理具有正确编译数量的 dvi/ps 生成。此外，由于处理本地修订非常简单，Mercurial 比 svn 更易于设置/使用，就像 hg init、hg add、hg commit 一样简单！您的培训在这里完成:-)。它让我想起了我是如何在本地使用 RCS 来满足我对 LaTeX 和源文件的需求的。当需要并行版本的文档时，创建分支或简单地克隆存储库也非常容易。

如果您希望留在所见即所得的世界中，另一个更好的版本控制解决方案是使用 Open Office 和OOoSVN extension，它允许存储（更大）的修订未压缩的 XML 文件，但真正处理了差异，这与存储二进制文件时发生的情况相反。不如第一个解决方案恕我直言，但这个解决方案可以避免翻译遗留文档和 LaTeX 学习曲线（老实说，这并不陡峭）。

希望对你有所帮助。

【讨论】：

【解决方案4】：

我们使用 LaTeX 来生成文档。您可以生成任何类型的文档...PDF 等。所有文档都存储在一个额外的 SVN 中。因此很容易通知客户有关文档的更改。

此外，您的团队可以一起处理文档，满足您对多个分支的需求。

我们的文档由 Hudson 定期构建。

【讨论】：

【解决方案5】：

你考虑过 LaTeX。由于它基于源代码的性质，它对 SCM 非常友好，并且有非常强大的功能和包用于 PDF 导出、维护词汇表、首字母缩略词、自动 TOC 生成、嵌入式源代码等。

【讨论】：

【解决方案6】：

在此处查看大量文档工具列表：

http://www.doxygen.nl/links.html

我曾经在我的 Delphi 项目中使用Doc-O-Matic，并且非常喜欢它——但那是几年前的事了。在我们当时的评估中排名第二的是Help & Manual，它的得分几乎与 Doc-o-Matic 一样高。

两者都是商业工具，但从长远来看，它们物有所值。

【讨论】：