mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-23 21:20:42 +08:00
179 lines
9.9 KiB
Markdown
179 lines
9.9 KiB
Markdown
|
[#]: subject: "Our favorite markup languages for documentation"
|
|||
|
|
[#]: via: "https://opensource.com/article/22/12/markup-languages-documentation"
|
|||
|
|
[#]: author: "Opensource.com https://opensource.com/users/admin"
|
|||
|
|
[#]: collector: "lkxed"
|
|||
|
|
[#]: translator: "ChatGPT"
|
|||
|
|
[#]: reviewer: "wxy"
|
|||
|
|
[#]: publisher: "wxy"
|
|||
|
|
[#]: url: "https://linux.cn/article-16073-1.html"
|
|||
|
|
|
|||
|
|
你喜欢哪种文档标记语言？
|
|||
|
|
======
|
|||
|
|
|
|||
|
|
![][0]
|
|||
|
|
|
|||
|
|
> 文档对于开源软件项目至关重要。我们询问了我们的贡献者，他们在文档编写中最喜欢使用的标记语言是什么。
|
|||
|
|
|
|||
|
|
文档很重要，而易读的文档更重要。在开源软件世界中，文档可以告诉我们如何使用或贡献一个应用程序，就像 [游戏][1] 的规则书一样。
|
|||
|
|
|
|||
|
|
有很多不同类型的文档：
|
|||
|
|
|
|||
|
|
- 教程
|
|||
|
|
- 操作指南
|
|||
|
|
- 参考指南
|
|||
|
|
- 软件架构
|
|||
|
|
- 产品手册
|
|||
|
|
|
|||
|
|
我们向一些贡献者询问了他们的技术文档工作流程，他们更喜欢使用哪种标记语言，以及为什么会选择其中一种。以下是他们的回答。
|
|||
|
|
|
|||
|
|
### AsciiDoc
|
|||
|
|
|
|||
|
|
过去几年中，[Markdown][2] 一直是我的标准语言。但最近我决定尝试一下 [AsciiDoc][3] 。这种语法并不难，我在 Linux 桌面上的 [Gedit][4] 就支持它。我计划暂时坚持使用它一段时间。
|
|||
|
|
|
|||
|
|
—- [Alan Formy-Duval][5]
|
|||
|
|
|
|||
|
|
就低语法标记语言而言，我更喜欢 AsciiDoc。我喜欢它，是因为其转换过程一致且可预测，没有令人困惑的“口味”变化 。我还喜欢将它输出为 [Docbook][6]，这是一种我信任其持久性和灵活性的标记语言，它有大量的语法标记。
|
|||
|
|
|
|||
|
|
但“正确”的选择往往取决于项目已经在使用什么。如果项目使用某种口味的 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][7]”）。
|
|||
|
|
|
|||
|
|
换句话说，当我的受众是人类读者时，我通常会选择 Markdown，因为它的语法简单，但仍具有足够的语法可以进行转换，因此仍然是一种可接受的存储格式。
|
|||
|
|
|
|||
|
|
虽然像 AsciiDoc 这样简洁的语法看起来更令人吃惊，但如果我的受众是要解析文件的计算机，我会选择 AsciiDoc。
|
|||
|
|
|
|||
|
|
—- [Seth Kenlon][8]
|
|||
|
|
|
|||
|
|
### reStructuredText
|
|||
|
|
|
|||
|
|
我是 [代码即文档][9] 的忠实支持者，它将开发者工具融入到内容流程中。这样可以更轻松地进行高效的审查和协作，尤其是如果工程师是贡献者。
|
|||
|
|
|
|||
|
|
作为一个标记语言的行家，我在 O'Reilly 写了整整一本关于 AsciiDoc 的书，还使用 Markdown 在各个平台上发布了上千篇博文。但目前，我转向使用 [reStructuredText][10]，并维护一些相关工具。
|
|||
|
|
|
|||
|
|
—— [Lorna Mitchell][11]
|
|||
|
|
|
|||
|
|
不得不提到 reStructuredText。在我大量使用 Python 编程时，它已成为我的首选。它也是 Python 长期以来用于文档源码和代码注释的标准。
|
|||
|
|
|
|||
|
|
与 Markdown 相比，我喜欢它不会受到非标准规范的困扰。话虽如此，当我处理更复杂的文档时，确实还得使用许多 Sphinx 的功能和扩展。
|
|||
|
|
|
|||
|
|
—— [Jeremy Stanley][12]
|
|||
|
|
|
|||
|
|
### HTML
|
|||
|
|
|
|||
|
|
能不用标记语言我就不用。
|
|||
|
|
|
|||
|
|
不过，我发现 HTML 比其他标记语言更易于使用。
|
|||
|
|
|
|||
|
|
—— [Rikard Grossman-Nielsen][13]
|
|||
|
|
|
|||
|
|
对我来说，撰写文档有各种方式。这取决于文档将要放在何处，是作为网站的一部分、软件包的一部分，还是可下载的内容。
|
|||
|
|
|
|||
|
|
对于 [Scribus][14] 来说，其内部文档采用 HTML 格式，因为需要使用内部浏览器来访问。对于网站，可能需要使用维基语言。而对于可下载的内容，可以创建 PDF 或 EPUB 格式。
|
|||
|
|
|
|||
|
|
我倾向于在纯文本编辑器中编写文档。我可能会使用 XHTML，以便将这些文件导入到像 Sigil 这样的 EPUB 制作工具中。当然，对于创建 PDF，我会使用 Scribus，虽然我可能会导入用文本编辑器创建的文本文件。Scribus 具有包含图形并精确控制其布局的优势。
|
|||
|
|
|
|||
|
|
Markdown 从未吸引我，我也从未尝试过 AsciiDoc。
|
|||
|
|
|
|||
|
|
—— [Greg Pittman][15]
|
|||
|
|
|
|||
|
|
我目前正在使用 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][16]
|
|||
|
|
|
|||
|
|
### 意料之外的答案：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][17] 的实现，因为它实际上有一个正式的定义。例如，[Pandoc][18] 支持 CommonMark（以及其他几种）。
|
|||
|
|
|
|||
|
|
我开始使用 AsciiDoc，相比于 Markdown，我更喜欢 AsciiDoc，因为它避免了“你使用的是哪个版本”的讨论，并提供了许多有用的功能。过去，让我对 AsciiDoc 感到困扰的是，有一段时间似乎需要安装 Asciidoctor，这是一个我不太想安装的 Ruby 工具链。但是现在，在我所用的 Linux 发行版中，有了更多的实现方式。奇怪的是，Pandoc 可以输出 AsciiDoc，但不支持读取 AsciiDoc。
|
|||
|
|
|
|||
|
|
那些嘲笑我不愿意为 AsciiDoc 安装 Ruby 工具链，却乐意安装 Pandoc 的 Haskell 工具链的人……我听到你们的笑声了。
|
|||
|
|
|
|||
|
|
我羞愧地承认，我现在主要使用 LibreOffice。
|
|||
|
|
|
|||
|
|
——[Chris Hermansen][19]
|
|||
|
|
|
|||
|
|
### 现在就编写文档吧！
|
|||
|
|
|
|||
|
|
文档编写可以通过多种不同的途径来完成，正如这里的作者们展示的那样。对于代码的使用方法，特别是在开源领域，进行文档编写非常重要。这确保其他人能够正确地使用和贡献你的代码。同时，告诉未来的用户你的代码提供了什么也是明智之举。
|
|||
|
|
|
|||
|
|
*（题图：MJ/9543e029-322d-479f-b609-442abc036b73）*
|
|||
|
|
|
|||
|
|
--------------------------------------------------------------------------------
|
|||
|
|
|
|||
|
|
via: https://opensource.com/article/22/12/markup-languages-documentation
|
|||
|
|
|
|||
|
|
作者：[Opensource.com][a]
|
|||
|
|
选题：[lkxed][b]
|
|||
|
|
译者：ChatGPT
|
|||
|
|
校对：[wxy](https://github.com/wxy)
|
|||
|
|
|
|||
|
|
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
|||
|
|
|
|||
|
|
[a]: https://opensource.com/users/admin
|
|||
|
|
[b]: https://github.com/lkxed
|
|||
|
|
[1]: https://opensource.comttps://opensource.com/life/16/11/software-documentation-tabletop-gaming
|
|||
|
|
[2]: https://opensource.com/article/19/9/introduction-markdown
|
|||
|
|
[3]: https://opensource.com/article/22/8/drop-markdown-asciidoc
|
|||
|
|
[4]: https://opensource.com/%20https%3A//opensource.com/article/20/12/gedit
|
|||
|
|
[5]: https://opensource.com/users/alanfdoss
|
|||
|
|
[6]: https://opensource.com/article/17/9/docboo
|
|||
|
|
[7]: http://example.com/
|
|||
|
|
[8]: https://opensource.com/users/seth
|
|||
|
|
[9]: https://opensource.com/article/22/10/docs-as-code
|
|||
|
|
[10]: https://opensource.com/article/19/11/document-python-sphinx
|
|||
|
|
[11]: https://opensource.com/users/lornajane
|
|||
|
|
[12]: https://opensource.com/users/fungi
|
|||
|
|
[13]: https://opensource.com/users/rikardgn
|
|||
|
|
[14]: https://opensource.com/article/21/12/desktop-publishing-scribus
|
|||
|
|
[15]: https://opensource.com/users/greg-p
|
|||
|
|
[16]: https://opensource.com/users/jim-hall
|
|||
|
|
[17]: https://commonmark.org/
|
|||
|
|
[18]: https://opensource.com/downloads/pandoc-cheat-sheet
|
|||
|
|
[19]: https://opensource.com/users/clhermansen
|
|||
|
|
[0]: https://img.linux.net.cn/data/attachment/album/202308/07/225101z4leseqq9zbhn3hh.jpg
|