你喜欢哪种文档标记语言？
文档对于开源软件项目至关重要。我们询问了我们的贡献者，他们在文档编写中最喜欢使用的标记语言是什么。
文档 文档标记语言 MarkDown
文档对于开源软件项目至关重要。我们询问了我们的贡献者，他们在文档编写中最喜欢使用的标记语言是什么。
![](/data/attachment/album/202308/07/225101z4leseqq9zbhn3hh.jpg)



> 
> 文档对于开源软件项目至关重要。我们询问了我们的贡献者，他们在文档编写中最喜欢使用的标记语言是什么。
> 
> 
> 


文档很重要，而易读的文档更重要。在开源软件世界中，文档可以告诉我们如何使用或贡献一个应用程序，就像 [游戏](https://opensource.comttps://opensource.com/life/16/11/software-documentation-tabletop-gaming) 的规则书一样。


有很多不同类型的文档：


* 教程
* 操作指南
* 参考指南
* 软件架构
* 产品手册


我们向一些贡献者询问了他们的技术文档工作流程，他们更喜欢使用哪种标记语言，以及为什么会选择其中一种。以下是他们的回答。


### AsciiDoc


过去几年中，[Markdown](https://opensource.com/article/19/9/introduction-markdown) 一直是我的标准语言。但最近我决定尝试一下 [AsciiDoc](https://opensource.com/article/22/8/drop-markdown-asciidoc) 。这种语法并不难，我在 Linux 桌面上的 [Gedit](https://opensource.com/%20https%3A//opensource.com/article/20/12/gedit) 就支持它。我计划暂时坚持使用它一段时间。


—- [Alan Formy-Duval](https://opensource.com/users/alanfdoss)


就低语法标记语言而言，我更喜欢 AsciiDoc。我喜欢它，是因为其转换过程一致且可预测，没有令人困惑的“口味”变化 。我还喜欢将它输出为 [Docbook](https://opensource.com/article/17/9/docboo)，这是一种我信任其持久性和灵活性的标记语言，它有大量的语法标记。


但“正确”的选择往往取决于项目已经在使用什么。如果项目使用某种口味的 Markdown，我就不会使用 AsciiDoc。嗯，公平地说，我可能会使用 AsciiDoc，然后使用 Pandoc 将其转换为草莓味的 Markdown。


当然，我认为 Markdown 有其应用的时间和场合。我发现它比 AsciiDoc 更易读。AsciiDoc 中的链接是这样：



```
http://example.com [Example website]

```

而 Markdown 中的链接是这样：



```
[Example.com](http://example.com)

```

Markdown 的语法直观，以读取 HTML 的方式呈现信息，大多数人都以相同的方式解析此类数据（“Example website……哦，那是蓝色的文本，我将悬停一下以查看它指向哪里……它指向 [example.com](http://example.com/)”）。


换句话说，当我的受众是人类读者时，我通常会选择 Markdown，因为它的语法简单，但仍具有足够的语法可以进行转换，因此仍然是一种可接受的存储格式。


虽然像 AsciiDoc 这样简洁的语法看起来更令人吃惊，但如果我的受众是要解析文件的计算机，我会选择 AsciiDoc。


—- [Seth Kenlon](https://opensource.com/users/seth)


### reStructuredText


我是 [代码即文档](https://opensource.com/article/22/10/docs-as-code) 的忠实支持者，它将开发者工具融入到内容流程中。这样可以更轻松地进行高效的审查和协作，尤其是如果工程师是贡献者。


作为一个标记语言的行家，我在 O'Reilly 写了整整一本关于 AsciiDoc 的书，还使用 Markdown 在各个平台上发布了上千篇博文。但目前，我转向使用 [reStructuredText](https://opensource.com/article/19/11/document-python-sphinx)，并维护一些相关工具。


—— [Lorna Mitchell](https://opensource.com/users/lornajane)


不得不提到 reStructuredText。在我大量使用 Python 编程时，它已成为我的首选。它也是 Python 长期以来用于文档源码和代码注释的标准。


与 Markdown 相比，我喜欢它不会受到非标准规范的困扰。话虽如此，当我处理更复杂的文档时，确实还得使用许多 Sphinx 的功能和扩展。


—— [Jeremy Stanley](https://opensource.com/users/fungi)


### HTML


能不用标记语言我就不用。


不过，我发现 HTML 比其他标记语言更易于使用。


—— [Rikard Grossman-Nielsen](https://opensource.com/users/rikardgn)


对我来说，撰写文档有各种方式。这取决于文档将要放在何处，是作为网站的一部分、软件包的一部分，还是可下载的内容。


对于 [Scribus](https://opensource.com/article/21/12/desktop-publishing-scribus) 来说，其内部文档采用 HTML 格式，因为需要使用内部浏览器来访问。对于网站，可能需要使用维基语言。而对于可下载的内容，可以创建 PDF 或 EPUB 格式。


我倾向于在纯文本编辑器中编写文档。我可能会使用 XHTML，以便将这些文件导入到像 Sigil 这样的 EPUB 制作工具中。当然，对于创建 PDF，我会使用 Scribus，虽然我可能会导入用文本编辑器创建的文本文件。Scribus 具有包含图形并精确控制其布局的优势。


Markdown 从未吸引我，我也从未尝试过 AsciiDoc。


—— [Greg Pittman](https://opensource.com/users/greg-p)


我目前正在使用 HTML 撰写大量文档，所以我要为 HTML 代言一下。你可以使用 HTML 创建网站或创建文档。请注意，这两者实际上并不相同 —— 当你创建网站时，大多数设计师关注的是呈现。但是当你编写文档时，技术作者应该专注于内容。


当我用 HTML 撰写文档时，我遵循 HTML 定义的标签和元素，并不关心它的外观。换句话说，我用“未经样式化”的 HTML 编写文档。稍后我总是可以添加样式表。因此，如果我需要强调文本的某一部分（比如警告），或者给单词或短语加重语气，我可能会使用 `<strong>` 和 `<em>` 标签，像这样：



```
<p><strong>警告：激光！</strong>不要用你剩下的那只眼睛看向激光。</p>

```

或者在段落中提供一个简短的代码示例，我可能会这样写：



```
<p><code>puts</code> 函数将一些文本输出给用户。</p>

```

要在文档中格式化一段代码块，我使用 `<pre><code>..</code></pre>`，如下所示：



```
void
print_array(int *array, int size)
{
  for (int i = 0; i < size; i++) {
    printf("array[%d] = %d\n", i, array[i]);
  }
}

```

HTML 的好处在于你可以立即在任何 Web 浏览器中查看结果。而你使用未经样式化的 HTML 编写的任何文档都可以通过添加样式表来美化。


—— [Jim Hall](https://opensource.com/users/jim-hall)


### 意料之外的答案：LibreOffice


在上世纪 80/90 年代，当我在 System V Unix、SunOS，最后是 Solaris 上工作时，我使用了 `nroff`、`troff` 和最终的 `groff` 与 `mm` 宏。你可以了解一下使用 `groff_mm` 的 MM（前提是你已经安装了它们）。


MM 并不是真正的标记语言，但它感觉像是。它是一套非常语义化的 troff 和 groff 宏。它具备标记语言用户所期望的大多数功能，如标题、有序列表等等。


我的第一台 Unix 机器上也安装了 “Writers' Workbench”，这对我们组织中需要撰写技术报告但没有特别进行“引人入胜”写作的许多人来说是一个福音。它的一些工具已经进入了 BSD 或 Linux 环境，比如样式（style）、用词检查（diction）和外观（look）。


我还记得早在上世纪 90 年代初期，Solaris 附带了一个标准通用标记语言（SGML）工具，也可能是我们购买了这个工具。我曾经使用它一段时间，这可能解释了为什么我不介意手动输入 HTML。


我使用过很多 Markdown，我应该说是“哪种 Markdown”，因为它有无数种风格和功能级别。正因为如此，我并不是 Markdown 的铁杆粉丝。我想，如果我有很多 Markdown 要处理，我可能会尝试使用一些 [CommonMark](https://commonmark.org/) 的实现，因为它实际上有一个正式的定义。例如，[Pandoc](https://opensource.com/downloads/pandoc-cheat-sheet) 支持 CommonMark（以及其他几种）。


我开始使用 AsciiDoc，相比于 Markdown，我更喜欢 AsciiDoc，因为它避免了“你使用的是哪个版本”的讨论，并提供了许多有用的功能。过去，让我对 AsciiDoc 感到困扰的是，有一段时间似乎需要安装 Asciidoctor，这是一个我不太想安装的 Ruby 工具链。但是现在，在我所用的 Linux 发行版中，有了更多的实现方式。奇怪的是，Pandoc 可以输出 AsciiDoc，但不支持读取 AsciiDoc。


那些嘲笑我不愿意为 AsciiDoc 安装 Ruby 工具链，却乐意安装 Pandoc 的 Haskell 工具链的人……我听到你们的笑声了。


我羞愧地承认，我现在主要使用 LibreOffice。


——[Chris Hermansen](https://opensource.com/users/clhermansen)


### 现在就编写文档吧！


文档编写可以通过多种不同的途径来完成，正如这里的作者们展示的那样。对于代码的使用方法，特别是在开源领域，进行文档编写非常重要。这确保其他人能够正确地使用和贡献你的代码。同时，告诉未来的用户你的代码提供了什么也是明智之举。


*（题图：MJ/9543e029-322d-479f-b609-442abc036b73）*




---


via: <https://opensource.com/article/22/12/markup-languages-documentation>


作者：[Opensource.com](https://opensource.com/users/admin) 选题：[lkxed](https://github.com/lkxed) 译者：ChatGPT 校对：[wxy](https://github.com/wxy)


本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出

