当我在我的 Doc Dish 文章中，关于 为什么应该使用渲染语言进行文档编写 的结尾处，我告诉过您，选择语言是另一天的事情。
好吧，另一天终于到来了。
您可以用来格式化和发布文档的语言种类繁多，您对语言的选择将取决于您项目的需求。在本文中，我将介绍几种不同的语言选项，从最简单的到最复杂的。这绝不是一个详尽的列表，所以在评论中为您的最爱（或最讨厌的）语言辩护吧。
Markdown
Markdown 是最简单的可用标记语言之一。在源格式中，它与纯文本非常相似，这使得它在未渲染的情况下也很容易理解。任何熟悉 wiki 语法或 IRC/即时消息约定的人都会发现它很容易使用。像 GitHub 这样的托管服务会在浏览代码仓库时自动渲染 Markdown 文件，这使得 Markdown 非常适合 README 文件和类似内容。
然而，这种简单性意味着缺乏灵活性。区分不同类型的文本（而不加入一堆 HTML）可能会很困难。由于标准没有明确定义，因此还存在各种 Markdown 实现和衍生版本（例如 CommonMark）。如果您正在为您的项目使用 Markdown，您应该确定您希望贡献者使用的实现和工具。
reStructured Text
reStructured Text（RST 或 reST）与 Markdown 类似，因为它的源格式几乎是纯文本。reStructured Text 最初是作为 Python 工具开发的，现在已广泛用于技术文档，尤其是在与 Sphinx 渲染系统结合使用时。
开发人员欣赏该语言的轻量级标记。尽管如此，reStructured Text 仍具有生成美观文档的灵活性。项目托管服务通常会在浏览器中渲染 reStructured Text 文件（再次使其适用于 README）。与 Markdown 不同，reStructured Text 确实有一个 定义的规范。
DocBook
接下来，事情变得更加复杂。
DocBook 是一个为技术文档设计的 XML 规范。仅仅提到 XML 就足以让一些人望而却步，但它提供的灵活性可能是一个有力的论据，尤其是对于用户文档而言。
与 Publican 等工具结合使用，它可以渲染各种格式的精美文档。Red Hat 和 Fedora 将 DocBook 用于指南和其他长篇文档
DocBook 具有用于 GUI 项目和操作、文本命令以及许多其他常见技术概念的元素。使用 Publican，您可以将文档发布到品牌网站。虽然 DocBook 的源代码可能有点刺眼，但该语言在格式化方面提供了强大的功能和灵活性。
LaTeX
然后是 LaTeX。
LaTeX 是一种功能强大的排版语言，特别适用于数学方程式。一些学术项目出于这个原因使用它。但是，LaTeX 的学习曲线非常陡峭。它的美学吸引力也有待提高。
做出选择
那么您将选择这些（或其他）选项中的哪一个呢？
您对这个问题的回答将取决于您的贡献者和潜在贡献者所适应的内容，以及您将要制作的文档类型。一个需要 README 的小型项目会发现 Markdown 最合适。像 Linux 发行版这样产生长篇指南的较大项目可能会发现 DocBook 是正确的选择。无论您选择什么，重要的是保持文档的更新和可用。
Dish
本文是 Rikki Endsley 协调的 Doc Dish 专栏 的一部分。要为本专栏投稿，请提交您的故事创意 或 联系我们。
12 条评论