mirror of
https://github.com/LCTT/TranslateProject.git
synced 2024-12-26 21:30:55 +08:00
Merge pull request #29840 from wxy/20221208.3-⭐️⭐️-Our-favorite-markup-languages-for-documentation
ATRP:published/20221208.3 ⭐️⭐️ Our favorite markup languages for documentation.md
This commit is contained in:
Xingyu.Wang
GitHub
commit
b7b02b1fd8
@ -0,0 +1,179 @@
|
||||
[#]: 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
|
||||
@ -1,173 +0,0 @@
|
||||
[#]: 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: " "
|
||||
[#]: reviewer: " "
|
||||
[#]: publisher: " "
|
||||
[#]: url: " "
|
||||
|
||||
Our favorite markup languages for documentation
|
||||
======
|
||||
|
||||
Documentation is important for so many reasons. Readable documentation is even more so. In the world of open source software, documentation is how to use or contribute to an application. It's like the rulebook for a [game][1].
|
||||
|
||||
There are many different types of documentation:
|
||||
|
||||
- Tutorials
|
||||
- How-to guides
|
||||
- Reference guides
|
||||
- Software architecture
|
||||
- Product manuals
|
||||
|
||||
We asked some of the Opensource.com contributors about their technical documentation workflow, which markup language they preferred, and why they might use one over the other. Here's what they had to say.
|
||||
|
||||
### AsciiDoc
|
||||
|
||||
For the past several years, [Markdown][2] has been my standard language. But recently I decided to give [AsciiDoc][3] a try. The syntax is not difficult and [Gedit][4] on my Linux desktop supports it. I plan to stick with it for a while.
|
||||
|
||||
—- [Alan Formy-Duval][5]
|
||||
|
||||
In terms of low-syntax markup, I prefer AsciiDoc. I like it because its conversion process is consistent and predictable, with no surprise "flavor" variations to confuse things. I also love that it outputs to [Docbook][6], which is a markup-heavy syntax that I trust for longevity and flexibility.
|
||||
|
||||
But the "right" choice tends to be what a project is already using. I wouldn't write in AsciiDoc if a project uses Strawberry-flavored Markdown. Well, to be fair, I might write in AsciiDoc and then convert it to Strawberry-flavored Markdown with Pandoc.
|
||||
|
||||
I do think there is a time and place for Markdown. I do find it more readable than AsciiDoc. Links in AsciiDoc:
|
||||
|
||||
```
|
||||
http://example.com[Example website]
|
||||
```
|
||||
|
||||
Links in Markdown:
|
||||
|
||||
```
|
||||
[Example.com](http://example.com)
|
||||
```
|
||||
|
||||
The Markdown syntax is intuitive, delivering the information in the same way that I think most of us parse the same data when reading HTML ("Example website…oh, that's blue text, I'll roll over it to see where it goes…it goes to [example.com][7]").
|
||||
|
||||
In other words, when my audience is a human reader, I do often choose Markdown because its syntax is subtle but it's got enough of a syntax to make conversion possible, so it's still an OK storage format.
|
||||
|
||||
AsciiDoc, as minimal as it is, just looks scarier.
|
||||
|
||||
If my audience is a computer that's going to parse a file, I choose AsciiDoc.
|
||||
|
||||
—- [Seth Kenlon][8]
|
||||
|
||||
### reStructuredText
|
||||
|
||||
I'm a big fan of [docs as code][9] and how it brings developer tools into the content workflows. It makes it easier to have efficient reviews and collaboration, especially if engineers are contributors.
|
||||
|
||||
I'm also a bit of a markup connoisseur, having written whole books in AsciiDoc for O'Reilly, a lot of Markdown for various platforms, including a thousand posts on my blog. Currently, I'm a [reStructuredText][10] convert and maintain some of the tooling in that space.
|
||||
|
||||
—- [Lorna Mitchell][11]
|
||||
|
||||
Obligatory mention of reStructuredText. That's my go-to these days as I do a lot of Python programming. It's also been Python's standard for documentation source and code comments for ages.
|
||||
|
||||
I like that it doesn't suffer quite so much from the proliferation of nonstandards that Markdown does. That said, I do use a lot of Sphinx features and extensions when working on more complex documentation.
|
||||
|
||||
—- [Jeremy Stanley][12]
|
||||
|
||||
### HTML
|
||||
|
||||
I rarely use markup languages if I don't have to.
|
||||
|
||||
I find HTML easier to use than other markup languages though.
|
||||
|
||||
—- [Rikard Grossman-Nielsen][13]
|
||||
|
||||
For me, there are various ways to make documentation. It depends on where the documentation is going to be whether on a website, as part of the software package, or something downloadable.
|
||||
|
||||
For [Scribus][14], the internal documentation is in HTML, since an internal browser is used to access it. On a website, you might need to use a Wiki language. For something downloadable you might create a PDF or an EPUB.
|
||||
|
||||
I tend to write the documentation in a plain text editor. I might use XHTML, so that I can then import these files into an EPUB maker like Sigil. And, of course, Scribus is my go-to app for making a PDF, though I would probably be importing a text file created with a text editor. Scribus has the advantage of including and precisely controlling placement of graphics.
|
||||
|
||||
Markdown has never caught on with me, and I've never tried AsciiDoc.
|
||||
|
||||
—- [Greg Pittman][15]
|
||||
|
||||
I'm writing a lot of documentation in HTML right now, so I'll put in a plug for HTML. You can use HTML to create websites, or to create documentation. Note that the two are not really the same — when you're creating websites, most designers are concerned about presentation. But when you're writing documentation, tech writers should focus on content.
|
||||
|
||||
When I write documentation in HTML, I stick to the tags and elements defined by HTML, and I don't worry about how it will look. In other words, I write documentation in "unstyled" HTML. I can always add a stylesheet later. So if I need to make some part of the text stronger (such as a warning) or add emphasis to a word or phrase, I might use the `<strong>` and `<em>` tags, like this:
|
||||
|
||||
```
|
||||
<p><strong>Warning: Lasers!</strong> Do <em>not</em> look into laser with remaining eye.</p>
|
||||
```
|
||||
|
||||
Or to provide a short code sample within the body of a paragraph, I might write:
|
||||
|
||||
```
|
||||
<p>The <code>puts</code> function prints some text to the user.</p>
|
||||
```
|
||||
|
||||
To format a block of code in a document, I use `<pre><code>..</code></pre>` like this:
|
||||
|
||||
```
|
||||
void
|
||||
print_array(int *array, int size)
|
||||
{
|
||||
for (int i = 0; i < size; i++) {
|
||||
printf("array[%d] = %d\n", i, array[i]);
|
||||
}}
|
||||
```
|
||||
|
||||
The great thing about HTML is you can immediately view the results with any web browser. And any documentation you write in unstyled HTML can be made prettier later by adding a stylesheet.
|
||||
|
||||
—- [Jim Hall][16]
|
||||
|
||||
### Unexpected: LibreOffice
|
||||
|
||||
Back in the 80s and 90s when I worked in System V Unix, SunOS, and eventually Solaris, I used the mm macros with `nroff,``troff` and finally `groff`. Read about MM using groff_mm (provided you have them installed.)
|
||||
|
||||
MM isn't really a markup language, but it feels like one. It is a very semantic set of troff and groff macros. It has most things markup language users would expect—headings, numbered lists, and so on.
|
||||
|
||||
My first Unix machine also had Writers' Workbench available on it, which was a boon for many in our organization who had to write technical reports but didn't particularly write in an "engaging manner". A few of its tools have made it to either BSD or Linux—style, diction, and look.
|
||||
|
||||
I also recall a standard generalized markup language (SGML) tool that came with, or perhaps we bought for, Solaris in the very early 90s. I used this for awhile, which may explain why I don't mind typing in my own HTML.
|
||||
|
||||
I've used Markdown a fair bit, but having said that, I should also be saying "which Markdown", because there are endless flavors and levels of features. I'm not a huge fan of Markdown because of that. I guess if I had a lot of Markdown to do I would probably try to gravitate toward some implementation of [CommonMark][17] because it actually has a formal definition. For example, [Pandoc][18] supports CommonMark (as well as several others).
|
||||
|
||||
I started using AsciiDoc, which I much prefer to Markdown as it avoids the "which version are you using" conversation and provides many useful things. What has slowed me down in the past with respect to AsciiDoc is that for some time it seemed to require installing Asciidoctor—a Ruby toolchain which I was not anxious to install. But these days there are more implementations at least in my Linux distro. Curiously, Pandoc emits AsciiDoc but does not read it.
|
||||
|
||||
Those of you laughing at me for not wanting a Ruby toolchain for AsciiDoc but being satisfied with a Haskell toolchain for Pandoc… I hear you.
|
||||
|
||||
I blush to admit that I mostly use LibreOffice these days.
|
||||
|
||||
—- [Chris Hermansen][19]
|
||||
|
||||
### Document now!
|
||||
|
||||
Documentation can be achieved through many different avenues, as the writers here have demonstrated. It's important to document how to use your code, especially in open source. This ensures that other people can use and contribute to your code properly. It's also wise to tell future users what your code is providing.
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/22/12/markup-languages-documentation
|
||||
|
||||
作者：[Opensource.com][a]
|
||||
选题：[lkxed][b]
|
||||
译者：[译者ID](https://github.com/译者ID)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [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
|
||||
Loading…
Reference in New Issue
Block a user