我为什么喜欢这些标记语言

大约去年的这个时候，我为本专栏写了一篇各种标记语言的简要介绍。最近几次都提到了语言选择的话题，所以我认为现在可能是时候再次审视这个主题，并更公开地表达我的偏见了。我在这里解释为什么我更喜欢我使用的语言，而不是为您开任何处方。毕竟，我不是医生。

一位同事问我对一篇比较 reStructuredText 和 Markdown 用于技术文档的文章的看法。我们公司的文档是用 reStucturedText 编写的，并使用 Sphinx 渲染，但我时不时地发出声音，想转向像 DocBook XML 这样的东西。对我来说，reStructuredText 介于反金发姑娘区域，它不像 Markdown 那样超级简单，但也不像 DocBook XML 那样丰富。它的亮点是使用 Sphinx 为 Python 自动生成模块文档。

最近，Copyleft Guide 的首席维护者宣布，他打算从 LaTeX 切换到 CommonMark 或 AsciiDoc。由于从未使用过 AsciiDoc，我对自己如此强烈地支持它感到有点惊讶，但随着我进行了后续对话，我意识到它非常适合类似书籍的文档。

“将内容与演示文稿分离，”他们说。像 DocBook 和 AsciiDoc 这样的语言允许作者说，例如：“这是一个 GUI 按钮。” 它最终可能会以粗体渲染，但您不仅仅添加 <em> 并称之为结束。内容与演示文稿分离；例如，像 Asciidoctor 这样的渲染工具使用级联样式表 (CSS) 来控制演示文稿。

我最喜欢在类似书籍的文档中做的事情是包含标注。警告、提示等是对您的读者重要的功能。在大多数情况下，读者最终会略读书的某些部分，要么是因为他们正在寻找特定部分，要么是因为您的散文太无聊而他们失去了兴趣。标注特别重要的部分有助于确保读者获得您真正、真正希望他们知道的信息。此外，它们还为文本墙添加了不错的间断。公平地说，reSTucturedText 对这些提供了一些支持，但我从未能够使它们像我希望的那样漂亮或在源代码中那么明显。

现在，我还没有赞扬什么？Markdown。可怜的 Markdown。别误会我的意思，我喜欢 Markdown。这篇文章就是以 Markdown 格式提交给编辑的。我在学校用 Markdown 记笔记。它非常容易边写边读源文件。对于简短的独立文档，Markdown 是最好的。

但是，编写 Markdown 的简易性与 Markdown 的最终（缺乏）强大功能不一致。除非您嵌入大量 HTML（那么您还不如不使用 Markdown），否则您将无法获得在长篇材料中变得更重要的许多语义丰富性。选择 Markdown 用于一切都很诱人，因为它使贡献的门槛如此之低，但是在选择让开发者或用户（在这种情况下是作者和读者）的生活更轻松时，成功的项目往往会偏爱用户。

所以这就是全部。文档语言不是万能的，因此为正在编写的文档选择合适的语言至关重要。

在评论中告诉我您为什么喜欢您选择的语言。