在我的关于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 是正确的选择。无论您选择什么，重要的是保持文档的更新和可用。
专题
本文是 Rikki Endsley 协调的Doc Dish 专栏的一部分。要为本专栏投稿，请提交您的故事想法或联系我们。
12 条评论