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

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

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

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

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

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

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

但是，编写 Markdown 的易用性与 Markdown 的最终（缺乏）强大功能相悖。除非您嵌入大量 HTML（那样您还不如不使用 Markdown），否则您将无法获得在长篇材料中变得更重要的许多语义丰富性。选择 Markdown 来处理所有事情是很诱人的，因为它降低了贡献的门槛，但是在选择让开发人员还是用户（在这种情况下是作者和读者）的生活更轻松时，成功的项目往往会偏向用户。

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

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