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

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

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

所以，这就是我的观点。文档语言不是一刀切的，因此为正在编写的文档选择合适的语言至关重要。

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