在我结束关于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 等工具结合使用，它可以渲染出各种格式的精美文档。红帽和 Fedora 使用 DocBook 来编写指南和其他长篇文档。
DocBook 具有用于 GUI 项目和操作、文本命令以及许多其他常见技术概念的元素。使用 Publican，你可以将你的文档发布到品牌网站。虽然 DocBook 的源代码可能有点难看，但该语言在格式化方面提供了强大的功能和灵活性。
LaTeX
然后是 LaTeX。
LaTeX 是一种强大的排版语言，尤其适用于数学方程式。一些以学术为基础的项目出于这个原因使用它。然而，LaTeX 有一个非常陡峭的学习曲线。它的美学吸引力也有些不足。
做出你的选择
那么你将选择这些（或其他）选项中的哪一个呢？
你对这个问题的答案将取决于你的贡献者和潜在贡献者所熟悉的内容，以及你将要生成的文档类型。需要 README 的小型项目会发现 Markdown 是最合适的选择。像 Linux 发行版这样生成长篇指南的大型项目可能会发现 DocBook 是正确的选择。无论你选择什么，重要的是保持你的文档更新和可用。
专栏
本文是 Rikki Endsley 协调的Doc Dish 专栏的一部分。要为本专栏投稿，请提交您的故事创意或联系我们。
12 条评论