你喜歡哪種文檔標記語言？

文檔對於開源軟體項目至關重要。我們詢問了我們的貢獻者，他們在文檔編寫中最喜歡使用的標記語言是什麼。

文檔很重要，而易讀的文檔更重要。在開源軟體世界中，文檔可以告訴我們如何使用或貢獻一個應用程序，就像 遊戲 的規則書一樣。

有很多不同類型的文檔：

• 教程
• 操作指南
• 參考指南
• 軟體架構
• 產品手冊

我們向一些貢獻者詢問了他們的技術文檔工作流程，他們更喜歡使用哪種標記語言，以及為什麼會選擇其中一種。以下是他們的回答。

AsciiDoc

過去幾年中，Markdown 一直是我的標準語言。但最近我決定嘗試一下 AsciiDoc 。這種語法並不難，我在 Linux 桌面上的 Gedit 就支持它。我計劃暫時堅持使用它一段時間。

—- Alan Formy-Duval

就低語法標記語言而言，我更喜歡 AsciiDoc。我喜歡它，是因為其轉換過程一致且可預測，沒有令人困惑的「口味」變化 。我還喜歡將它輸出為 Docbook，這是一種我信任其持久性和靈活性的標記語言，它有大量的語法標記。

但「正確」的選擇往往取決於項目已經在使用什麼。如果項目使用某種口味的 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」）。

換句話說，當我的受眾是人類讀者時，我通常會選擇 Markdown，因為它的語法簡單，但仍具有足夠的語法可以進行轉換，因此仍然是一種可接受的存儲格式。

雖然像 AsciiDoc 這樣簡潔的語法看起來更令人吃驚，但如果我的受眾是要解析文件的計算機，我會選擇 AsciiDoc。

—- Seth Kenlon

reStructuredText

我是 代碼即文檔 的忠實支持者，它將開發者工具融入到內容流程中。這樣可以更輕鬆地進行高效的審查和協作，尤其是如果工程師是貢獻者。

作為一個標記語言的行家，我在 O'Reilly 寫了整整一本關於 AsciiDoc 的書，還使用 Markdown 在各個平台上發布了上千篇博文。但目前，我轉向使用 reStructuredText，並維護一些相關工具。

—— Lorna Mitchell

不得不提到 reStructuredText。在我大量使用 Python 編程時，它已成為我的首選。它也是 Python 長期以來用於文檔源碼和代碼注釋的標準。

與 Markdown 相比，我喜歡它不會受到非標準規範的困擾。話雖如此，當我處理更複雜的文檔時，確實還得使用許多 Sphinx 的功能和擴展。

—— Jeremy Stanley

HTML

能不用標記語言我就不用。

不過，我發現 HTML 比其他標記語言更易於使用。

—— Rikard Grossman-Nielsen

對我來說，撰寫文檔有各種方式。這取決於文檔將要放在何處，是作為網站的一部分、軟體包的一部分，還是可下載的內容。

對於 Scribus 來說，其內部文檔採用 HTML 格式，因為需要使用內部瀏覽器來訪問。對於網站，可能需要使用維基語言。而對於可下載的內容，可以創建 PDF 或 EPUB 格式。

我傾向於在純文本編輯器中編寫文檔。我可能會使用 XHTML，以便將這些文件導入到像 Sigil 這樣的 EPUB 製作工具中。當然，對於創建 PDF，我會使用 Scribus，雖然我可能會導入用文本編輯器創建的文本文件。Scribus 具有包含圖形並精確控制其布局的優勢。

Markdown 從未吸引我，我也從未嘗試過 AsciiDoc。

—— Greg Pittman

我目前正在使用 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] = %dn", i, array[i]);
  }
}

HTML 的好處在於你可以立即在任何 Web 瀏覽器中查看結果。而你使用未經樣式化的 HTML 編寫的任何文檔都可以通過添加樣式表來美化。

—— 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 的實現，因為它實際上有一個正式的定義。例如，Pandoc 支持 CommonMark（以及其他幾種）。

我開始使用 AsciiDoc，相比於 Markdown，我更喜歡 AsciiDoc，因為它避免了「你使用的是哪個版本」的討論，並提供了許多有用的功能。過去，讓我對 AsciiDoc 感到困擾的是，有一段時間似乎需要安裝 Asciidoctor，這是一個我不太想安裝的 Ruby 工具鏈。但是現在，在我所用的 Linux 發行版中，有了更多的實現方式。奇怪的是，Pandoc 可以輸出 AsciiDoc，但不支持讀取 AsciiDoc。

那些嘲笑我不願意為 AsciiDoc 安裝 Ruby 工具鏈，卻樂意安裝 Pandoc 的 Haskell 工具鏈的人……我聽到你們的笑聲了。

我羞愧地承認，我現在主要使用 LibreOffice。

——Chris Hermansen

現在就編寫文檔吧！

文檔編寫可以通過多種不同的途徑來完成，正如這裡的作者們展示的那樣。對於代碼的使用方法，特別是在開源領域，進行文檔編寫非常重要。這確保其他人能夠正確地使用和貢獻你的代碼。同時，告訴未來的用戶你的代碼提供了什麼也是明智之舉。

（題圖：MJ/9543e029-322d-479f-b609-442abc036b73）

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

作者：Opensource.com 選題：lkxed 譯者：ChatGPT 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive