需要建议 - 开发灵活的文档系统，重点关注本地化[关闭]

Question

我负责构建文档系统/平台。

以下是主要要求的简短列表：

• 轻松本地化：这需要支持十几种左右的语言。（非技术人员添加/更新翻译的能力将是一个很大的优势，尽管不是 100% 需要）

• 输出格式的灵活性：至少，我需要将文档（作为整体或选定的块）输出为 PDF 和 HTML。Windows 帮助文件等本机格式的奖励积分。

• 通过直观的用户界面（最好是 Web）进行管理和部署。

我想知道你们是否知道已经有支持此类事物的系统？我并不反对从头开始写这篇文章，但如果可以的话，我宁愿不重新发明轮子。

到目前为止我遇到的两个主要候选人是 文档书 和 休息. 。前者似乎已经赢得了糟糕的名声。我对这两者都不熟悉，但我听说休息会让我在这方面取得很大进展。

还有其他建议吗？我从头开始构建这个会更好吗？

Answer 1

如果您需要创建传统的技术文档，我可以推荐 DocBook：书籍，分为章节，分为章节等。我认为主要考虑三点：标记本身、编辑工具链和发布工具链。

标记。 DocBook XML 标记非常全面，包含对技术卷中可能包含的几乎所有可以想象的方面的支持。这包括书籍的基本内容，例如交叉引用、脚注等。以及专门用于软件文档的标记，如程序列表、参考条目等。对标记的基本引用是 文档书：权威指南 作者：诺曼·沃尔什和伦纳德·穆尔纳。

内容的语言可以使用明确标记 lang 属性，使得源文档可以包含多种语言的内容，并且可以在处理阶段提取所需的语言版本。

创作工具。 由于 DocBook 词汇表的庞大规模，某种“模式感知”编辑器几乎是必需的。一个好的编辑器将帮助您选择标记元素，并确保您生成有效的标记。一个像样的 XML 编辑器就可以了，但根据文档作者的技术水平，您可能还需要考虑一些更用户友好的编辑器。有一些所见即所得风格的编辑器可用。（我用过 XMLMind XML 编辑器, ，我对此非常满意。）

发布工具。 从 DocBook XML 标记生成输出的事实上的标准方法是 文档书 XSL 样式表分布。它支持多种输出格式，包括 HTML、XSL-FO（用于 PDF 输出）、HTML 帮助，甚至手册页。样式表生成的输出可以由许多参数控制，当您想要调整输出时，首先要参考的是 参考文档 与样式表一起分发。

但是，如果您想要对生成的输出进行更多控制，则需要针对您的特定用途自定义 XSLT 样式表。这可能看起来有点令人畏惧，尤其是如果您以前没有 XSLT 经验的话。然而，有一本关于这个主题的优秀免费书籍： DocBook XSL：完整指南 鲍勃·斯泰顿着。

要将 XSL-FO 转换为 PDF，您还需要 XSL-FO 处理器。有免费和开源的 阿帕切FOP 然后还有多种商业选择。

最有可能的是，您的发布过程最终可能看起来像文档的构建系统。您将拥有一个自动化系统（可能由 Make 或 Ant 等构建工具驱动），它将采用 XML 格式的文档源并将其转换为所需语言的所需输出格式。

---

总而言之，如果您希望生成类似书籍的线性详细技术文档，我想说 DocBook 是一个不错的选择。主要缺点是标记的复杂性，这会给作者带来相当大的学习曲线，并且可能需要特殊的创作工具。此外，自定义 DocBook XSL 样式表的输出可能会非常复杂。

如果您希望生成更少的“书本式”和更多的“在线式”文档（文档主题相互关联），您可能需要看看 DITA 另一种基于 XML 的替代方案。我还没有使用过它，但它还附带了一个工具链，用于从 XML 标记生成各种输出格式。

Answer 2

DocBook 和 ReStructuredText 绝对是两个最大的竞争对手，但是 阿西多克 是另一种类似的标记语言，无论标记如何，它都是可读的。我个人更熟悉（因此也是 ReStructuredText 的更大支持者），但 Asciidoc 只是另一个选择。

鉴于您到目前为止所描述的内容，听起来像是 摩因摩因 将是一个很好的选择，因为它 有一个 ReStructuredText 解析器 和 它可以将页面导出为 PDF. 。您应该能够提取源代码并根据需要通过任何其他独立工具运行它（但您可能需要对它们进行预处理以去除任何 MoinMoin 特定的标记）。

谷歌还有其他一些 ReStructuredText wiki 的结果 如果 MoinMoin 不正是您所需要的。