【发布时间】：2010-10-14 03:21:06
【问题描述】：
【问题讨论】：
标签： documentation markdown markup restructuredtext textile
【发布时间】：2010-10-14 03:21:06
【问题描述】：
我知道在更大的编程和技术社区中常用的三种主要语言：Textile、Markdown 和 reStructuredText。这三个都可以在几个小时内学会，或者在附近的备忘单上“飞翔”。
纺织
- 由 Redmine 和 Ruby 社区使用
- 目前在 Stack Overflow 上标记了 113 个问题
- 与 HTML 最相似，但可读性最低的源码
- 三种语言中最简单的嵌套列表
- 非程序员或不懂 HTML 的人无法理解
- 非常适合复杂的短文档（带有链接、嵌套列表、代码、自定义 HTML）；例如：简短的文档、操作方法、博客或 CMS 内容
- Syntax reference
降价
- 似乎没有母语“社区”，但...
- 在 Stack Overflow 上标记了 1274 个问题*
- 强调源代码的可读性，类似于电子邮件传统
- 简单的 HTML 嵌入（您只需输入标签）
- 除了嵌入 HTML 之外，没有办法制作表格
- 如果你知道 Stack Overflow，你就已经知道了
- 如果您已经了解 reStructuredText，则很容易学习
- 格式的自动电子邮件地址混淆（带尖括号）
- Syntax reference
reStructuredText（A.K.A. ReST）
- 在 Python 社区中很受欢迎
- 在 Stack Overflow 上标记了 285 个问题
- 如果你问我，对空格和对齐有点挑剔
- 列表（尤其是嵌套列表）和段落似乎总是打架
- 非程序员可读
- 只能构建目录的格式（通过 Python 参考实现中的扩展）
- 直接转换为其他格式，如 PDF 和 XML
- 非常适合包含大量散文的大型文档（例如，作为用户手册的 docbook 的替代品）
- Syntax reference
【讨论】：
-
对于 ReST 的用户来说，sphinx.pocoo.org 看起来是一个非常好的工具，可用于大型树状结构的参考文档集合。
-
当我在 Emacs 中硬包装内容时，reStructuredText 中的列表和段落没有任何问题。事实上，它们的功能与我期望的完全一样:-)
-
Markdown 有一些扩展，允许用 ASCII 编写表格。
-
ReST 也有出色的工具支持：例如基于浏览器的notex.ch 是实验、学习和使用 ReST（基于 sphinx.pocoo.org 后端）的好工具。
你也可以考虑asciidoc
- 相对可读的标记
- 简单的命令行使用
- 有些人可能认为它在语法方面相对“挑剔”（相对灵活）
- docbook 和 (x)html 输出
【讨论】：
-
不幸的是，asciidoc 对于包含多个段落的列表项有一种可怕的语法：您必须用仅包含一个加号（是的，一个“+”）的单行来分隔它们。
-
@Martin：多段列表项真的那么重要吗？如果您需要多个段落，标题/部分不是比列表更合适吗？
-
AsciiDoc 的最大优势在于它支持更多的功能。它可以创建书籍，有提示部分，许多输出...powerman.name/doc/asciidoc
lightweight markup languages 上的维基百科页面对各种选项进行了很好的比较，并显示了常用语法（标题、粗体、斜体等）
【讨论】：
我试图在这里涵盖所有各种轻量级标记语言：
http://www.subspacefield.org/~travis/static_blog_generators.html
如您所见，它从“我如何制作安全博客”开始——即生成静态 HTML 的博客，然后我发现自己陷入了标记语言、模板系统等领域。
更新
我只重新关注具有 python 实现的 LWML，它们在这里：
http://www.subspacefield.org/~travis/python_lightweight_markup_languages.html
到目前为止，我已经尝试过 markdown 和 ReST，但我更喜欢后者 HTML sn-ps 嵌入在其他页面中。表格、交叉引用、间接链接等...
【讨论】：
文档？
doxygen 怎么样？
我已经将它用于我需要记录的一些 c/c++ 项目。
甚至你也可以像 doxygen 作者用于 doxygen 文档一样“滥用”它
【讨论】：