如果您需要创建传统的技术文档,我可以推荐 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 标记生成各种输出格式。