如果软件项目的任何一个方面经常被忽略，那就是文档。 从长远来看，未记录的软件是无法使用的软件。 问题是，编写软件文档可能是一件繁琐的工作，尤其是在涉及复杂的格式设置时：目录，脚注，尾注，超链接等。
曾几何时，记录项目的典型方法是编写HTML。 但是出现了一个更好的方法：使用易于以原始格式阅读但可以快速呈现以产生复杂标记的文本格式。
为了满足这种需求，已经开发了几种不同的文本格式-有些来自博客社区，有些来自更正式的软件开发圈子。 在这里，我们将研究四种最常见的格式，它们的优缺点以及它们最适合的项目类型。
降价促销
Markdown 由John Gruber在2004年开发，最初是为博客创建的，目的是提供一种无需使用易碎的内联HTML即可快速将普通格式添加到纯文本文档的方法。 想法是，原始文档及其注释应可作为文本阅读，但也应提供视觉提示，以使读者一目了然地掌握文档的结构。
从那时起，Markdown已成为许多场所中从文本到富文本格式的事实上的标准。 例如，GitHub 使用Markdown的变体在问题注释中添加样式。
IDG
Markdown最初是为博客而设计的。 它易于键入和记住，但缺乏更复杂的文档所需的灵活性。
Markdown专家
Markdown的最大好处是易于采用，广泛使用和广泛支持。 Markdown文档可以原样阅读，而无需呈现为HTML，并且仍然可以理解。 大部分基本格式（重点，标题，超链接等）都可以在数分钟内学习到，并且备有很多备忘单，以带您了解更高级的概念。
大多数文本编辑器都包含对Markdown的支持，或具有添加它的插件。 对于某些编辑器（如Visual Studio Code），该支持超出了语法突出显示的范围，包括预览或导出结果HTML。
降价优惠
Markdown的第一个主要缺点是，它并不是为生成文档而设计的。 因为它主要针对博客作者，所以本机不支持许多文档通用的元素，例如目录。
这导致了Markdown的另一个大缺点：它是事实上的标准。 您从Markdown获得什么样的行为完全取决于实现。 最终结果是一家冰淇淋店购买了Markdown的“香精”，其中许多精妙地互不兼容。 如果每个人都同意使用完全相同的工具来生成和处理Markdown，这并不是很糟糕，但是对于规模较大的项目而言，这很难实施。
解决此难题的一种可能解决方案是Markdown的一个名为Commonmark的分支 ，该分支试图标准化Markdown并消除其歧义。 Markdown的某些实现现在使用Commonmark规范，同时添加了自己的自定义更改。 例如，GitHub Flavored Markdown具有诸如任务列表项之类的元素的扩展。 但是，其他流行的变体（例如Pandoc文档生成工具使用的Pandoc Markdown）不遵循Commonmark。
降价用例
由于这些限制，Markdown最好用于不需要大量文档的较小项目，例如，创建一个运行几个屏幕的自述文件，或者记录一个只有几个调用的API。 对于更苛刻的要求，Markdown可能无法扩展。
reStructuredText
像Markdown一样，reStructuredText（简称“ reST”）使用简单的内联标记来允许将纯文本呈现为HTML，同时保持原始文本的高度可读性。 reST格式最初是为了帮助记录Python社区中所做的工作而开发的。 它是从Zope项目完成的工作中发展而来的，它的第一个正式版本通过Python在2002年问世。
IDG
reStructuredText或reST不会比Markdown复杂得多，但是可以提供更多的格式化功能。
reStructuredText的优点
开箱即用，reST所支持的标记比Markdown还要多。 例如，表格并不是Markdown规范的正式组成部分。 尽管第三方在Markdown中增加了对表格的支持，但不能保证Markdown的任何特定实现都会支持它们。 相比之下，reST支持开箱即用的表格格式。
此外，默认情况下，reST支持许多其他有用的文档元素，包括脚注，引文和目录。 reST有一个核心规范，这意味着关于reST实现应如何表现的唯一真理。 该规范的一种实际实现是Docutils项目 。
与Markdown相比，reST的另一个主要优势是对附加功能的内置支持。 如果给定的reST实现要修改语法，则可以在保留核心reST功能的同时进行修改。 例如， Sphinx文档工具以这种方式建立在reST上。
reStructuredText缺点
如果您当前是Markdown用户，并且要切换到reST，请提前警告：许多reST格式语法与Markdown的语法都不一样。 例如，Markdown中的文字块在该块的上方和下方都有三个反引号。 在休息，文字块开始与双冒号（ ::在块之前的线的端部 ），并且需要缩进或引用被分开设置。 此外，许多reST语法元素都是空格敏感的，这是该项目起源于Python社区的标志。 但是，如果您没有Markdown的投资或经验，那么这些差异就不会成为问题。
reStructuredText用例
对于那些Markdown规模过大且长期需要更强大功能的项目，使用reST是明智的选择。 可以通过Pandoc之类的工具将现有的Markdown文本转换为reST。
阿西多克
Asciidoc最初于2002年在Python社区中开发。 像reStructuredText一样，Aciidoc接受Markdown的可读标记概念，并将其扩展为解决更多用例。 虽然基本格式语法（粗体，斜体等）类似于Markdown，但Asciidoc包括开箱即用的软件项目中通常使用的复杂格式功能。
IDG
Asciidoc比reST或Markdown更为冗长，但是其块元素结构允许对打印和在线文档进行高度灵活的格式化。
Asciidoc专业人士
Asciidoc允许通过块元素在内部构造文档。 例如，文档的标题块包含有关文档的元数据，包括标题，作者，修订信息和其他元数据。 块元素可以嵌套，从而允许更复杂的布局。 而且Asciidoc可以实现所有这些，而不会增加很多键入开销。
属性的另一个强大的Asciidoc功能。 属性允许开发人员创建名称/值对，本质上是变量，并为它们分配块级别或内联。 将此与插件或附件结合使用，可以扩展Asciidoc以解决各种自定义方案。
Asciidoc的工具集还旨在支持比数字文档更多的功能。 如O'Reilly Atlas平台所使用的，它可用于导出印刷书籍的版式。
害处
Asciidoc的最大缺点是缺少对Asciidoc规范的单独定义-一种可以重新实现的独立形式语法。 Asciidoctor，最常用的Asciidoc工具，通常被视为Asciidoc的参考实现。 但是，尝试为Asciidoc创建单独的正式规范尚未产生任何有用的结果。
Asciidoc用例
由于其强大的输出和内部文档结构功能，如果您要创建将经历多个化身的文档，例如，如果您计划从文件中生成打印文档，或者为您敞开大门，Asciidoc是最佳选择。其他格式。 其他格式也可以实现这些功能，但是Asciidoc的功能和工具链（ Asciidoctor应用程序 ）已经在这些用例中大放异彩。
组织模式
组织模式格式最初创建于2003年，是Emacs文本编辑器的扩展。 最初的目的不只是要编写快速轮廓和列出待办事项，而是将其发展成为一个更加复杂的项目。
IDG
组织模式主要设计用于个人组织和项目跟踪，而不是复杂的文档。
组织模式专家
组织模式与Markdown具有许多相同的优点。 它易于学习，易于使用，并且可以使源文本非常容易用肉眼阅读。
Org-mode的大多数格式化功能都围绕任务或计划安排，例如要做的事情列表，为任务定时进出，制定议程以及格式化表格中的文本。
尽管Org-mode诞生于Emacs，但其他文本编辑器（包括Vim，Visual Studio Code和Sublime Text）也通过插件支持Org-mode。 但是，并非所有这些代码编辑器都提供与Emacs相同的组织模式支持范围。
组织模式缺点
至少对于那些不熟悉Emacs的人来说，Org-mode的最大缺点可能是对Emacs密钥绑定的严重依赖。 按键绑定使您能够以最少的击键次数完成许多常见任务。 但是，如果您还不习惯在Emacs中使用这种工作方式，则学习曲线可能会令人望而却步。 您可能需要一段时间才能感到有成效。
另一个缺点是Org-mode没有形式语法。 规范的实现是Emacs软件包。 确实存在Org-mode语法的草稿版本 ，但与Asciidoc的草稿版本一样，它不过是草稿而已。
最后，与Markdown，reStructuredText和Asciidoc不同，大多数组织模式实现都没有实时预览的形式。 Emacs通过附加的次要模式org-preview-html-mode填补了这一空白，该模式通过在微型浏览器中将其呈现为HTML来自动预览保存的文件。 但是其他组织模式实现（例如为Microsoft Visual Studio Code创建的实现）还没有。
组织模式用例
由于组织模式主要面向任务，因此它不适用于公共文档。 最好是由几个人使用的内部文档来跟踪进度或共享有关团队工作的信息，并使用一个最小的，相互共享的工具集（例如Emacs）来完成此工作。
From: https://www.infoworld.com/article/3336202/markdown-vs-alternatives-for-software-documentation.html
394
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
