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

大约在去年的这个时候，我为本专栏撰写了一篇关于各种标记语言的简短介绍。最近，语言选择的话题被多次提及，因此我认为现在可能是时候以更公开的偏见重新审视这个问题了。我在这里解释为什么我喜欢我使用的语言，而不是为您规定任何东西。毕竟，我不是医生。

一位同事询问了我对一篇比较 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 来处理所有事情是很诱人的，因为它降低了贡献的门槛，但是当选择让开发人员或用户（在这种情况下是作者和读者）的生活更轻松时，成功的项目往往会偏爱用户。

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

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