1

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

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

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

  • 输出格式的灵活性:至少,我需要将文档(作为一个整体或选定的块)输出为 PDF 和 HTML。Windows 帮助文件等原生格式的奖励积分。

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

我想知道你们是否知道已经支持这种类型的任何系统?我不反对从头开始写这篇文章,但如果我能帮上忙,我宁愿不重新发明轮子。

到目前为止,我遇到的两个主要候选人是DocBookreST。前者似乎以吸吮而闻名。我对这两个都不熟悉,但有人告诉我,reST 可以让我在其中大获成功。

还有其他建议吗?从头开始构建它会更好吗?

4

2 回答 2

2

DocBook 和 ReStructuredText 绝对是最大的两个竞争对手,但Asciidoc是另一种类似的标记语言,无论标记如何都可读。我个人对 ReStructuredText 更熟悉(因此是更大的支持者),但 Asciidoc 只是另一种选择。

鉴于您到目前为止所描述的内容,听起来MoinMoin非常适合,因为它具有 ReStructuredText 解析器并且可以将页面导出为 PDF。您应该能够提取源代码并根据需要通过任何其他独立工具运行它(但您可能需要对它们进行预处理以去除任何特定于 MoinMoin 的标记)。

如果 MoinMoin 不是您所需要的,Google还会为 ReStructuredText wiki提供一些其他结果。

于 2010-05-15T00:22:42.163 回答
2

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

标记。DocBook XML 标记非常全面,包含对几乎所有可以想象到的方面的支持,这些方面可能包含在技术卷中,然后是一些。这包括交叉引用、脚注等书籍的基本内容,以及专门用于软件文档的标记,如程序列表、参考条目等。对标记的基本参考是DocBook: Norman Walsh 和 Leonard的权威指南穆尔纳。

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

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

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

但是,如果当您想要对生成的输出进行更多控制时,您需要为您的特定用途定制 XSLT 样式表。这可能看起来有些令人生畏,尤其是如果您之前没有 XSLT 的经验。但是,有一本关于该主题的优秀免费书籍:DocBook XSL: Bob Stayton 的完整指南。

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

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


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

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

于 2010-05-16T09:02:52.053 回答