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

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

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

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

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

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

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

但是编写 Markdown 的容易性与 Markdown 的最终（缺乏）功能相矛盾。除非您嵌入大量 HTML（那么您最好不要使用 Markdown），否则您将无法获得在长篇材料中变得更重要的许多语义丰富性。为了一切都选择 Markdown 是很诱人的，因为它使贡献的门槛非常低，但是当选择让开发人员或用户（在本例中为作者和读者）的生活更轻松时，成功的项目往往会偏爱用户。

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

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