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

我负责建立一个文档系统/平台

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

易于本地化：这将需要支持十几种语言。非技术人员添加/更新翻译的能力将是一大优势，尽管不是100%要求

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

理想情况下，通过直观的用户界面web进行管理和部署

我想知道你们是否知道有任何系统已经支持这种类型的东西了？我并不反对从头开始写这篇文章，但如果我能帮上忙的话，我宁愿不要重新发明轮子

到目前为止，我遇到的两个主要候选人是和。前者似乎以吮吸而闻名。我对这两种方法都不熟悉，但有人告诉我，休息会让我走上一段很好的路

---

还有其他建议吗？我从零开始构建它会更好吗？

DocBook和StructuredText无疑是两个最大的竞争对手，但它是另一种类似的标记语言，无论标记如何，都是可读的。我对StructuredText比较熟悉，因此我个人更支持StructuredText，但Asciidoc只是另一种选择

考虑到目前为止您所描述的情况，它听起来似乎非常适合，因为它和。您应该能够提取源代码，并根据需要通过任何其他独立工具运行它，但您可能需要对它们进行预处理，以去除任何特定于MoinMoin的标记

---

如果MoinMoin不是你所需要的，Google还有一些其他的。DocBook和StructuredText无疑是两个最大的竞争对手，但它是另一种类似的标记语言，无论标记是什么，都是可读的。我对StructuredText比较熟悉，因此我个人更支持StructuredText，但Asciidoc只是另一种选择

考虑到目前为止您所描述的情况，它听起来似乎非常适合，因为它和。您应该能够提取源代码，并根据需要通过任何其他独立工具运行它，但您可能需要对它们进行预处理，以去除任何特定于MoinMoin的标记

---

如果MoinMoin不完全是您所需要的，Google还有一些其他功能。

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

标记。DocBook XML标记非常全面，包含对技术卷中可能包含的几乎每个方面的支持，以及一些方面的支持。这包括书籍的基本内容，如交叉引用、脚注等，以及专门用于软件文档的标记，如程序列表、参考条目等。对标记的基本参考是由Norman Walsh和Leonard Muellner编写的

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

创作工具。由于DocBook词汇表的巨大规模，几乎需要某种模式感知编辑器。一个好的编辑器将帮助您选择标记元素，并确保生成有效的标记。一个像样的XML编辑器会做的，但是取决于文档作者的技术，你可能还想考虑一些更人性化的东西。有一些WYSIWYG风格的编辑器可用。我用过，我很满意

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

但是，如果您希望对生成的输出有更多的控制，则需要为您的特定用途定制XSLT样式表。这似乎有点令人望而生畏，尤其是如果您以前没有XSLT的经验。然而，有一本关于这个主题的优秀的免费书：鲍勃·斯泰顿

要将XSL-FO转换为PDF，还需要一个XSL-FO处理器。有免费和开源，还有多种商业选择

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

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

---

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

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

标记。DocBook XML标记非常全面，包含对技术卷中可能包含的几乎每个方面的支持，以及一些方面的支持。这包括书籍的基本内容，如交叉引用、脚注等，以及专门用于软件文档的标记，如程序列表、参考条目等。对标记的基本参考是由Norman Walsh和Leonard Muellner编写的

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

创作工具。由于DocBook词汇表的巨大规模，几乎需要某种模式感知编辑器。一个好的编辑器将帮助您选择标记元素，并确保生成有效的标记。一个像样的XML编辑器会做的，但是取决于文档作者的技术，你可能还想考虑一些更人性化的东西。有一些WYSIWYG风格的编辑器可用。我用过，我很满意

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

但是，如果您希望对生成的输出有更多的控制，则需要为您的特定用途定制XSLT样式表。这似乎有点令人望而生畏，尤其是如果您以前没有XSLT的经验。然而，有一本关于这个主题的优秀的免费书：鲍勃·斯泰顿

要将XSL-FO转换为PDF，还需要一个XSL-FO处理器。有免费和开源，还有多种商业选择

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

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

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