想讓你的新Linux程式看起來很專業嗎？給它一個手冊頁。我們將向您展示最簡單、最快的方法。

手冊頁

在舊的Unix笑話中有一個核心真理，“你需要知道的唯一命令是man。”手冊頁包含了豐富的知識，當你想了解一個命令時，應該首先開啟手冊頁。

為您編寫的實用程式或命令提供一個手冊頁，可以將其從一段有用的程式碼提升到一個完整的Linux包。人們希望為一個為Linux編寫的程式提供一個手冊頁。如果您本機支援Linux，那麼如果您希望您的程式受到重視，那麼手冊頁是必需的。

歷史上，手冊頁是使用一組格式化巨集編寫的。當您呼叫man開啟一個頁面時，它會呼叫groff來讀取檔案並根據檔案中的巨集生成格式化輸出。輸出透過管道傳輸到less，然後為您顯示。

除非您經常建立手冊頁，否則編寫一個並手動**巨集是一項艱鉅的工作。建立一個正確解析並看起來正確的手冊頁的行為可以超越您的目標，從而提供命令的簡明、但徹底的描述。

你應該把注意力集中在你的內容上，而不是和一組晦澀難懂的巨集作鬥爭。

相關：如何使用Linux的man命令：隱藏的祕密和基礎

潘多克前往救援

pandoc程式讀取標記檔案並生成大約40種不同標記語言和文件格式的新檔案，包括手冊頁。它完全改變了手冊頁的寫作過程，所以你不必與象形文字搏鬥。

首先，您可以使用以下命令在Ubuntu上安裝pandoc：

在Fedora上，您需要的命令如下：

在Manjaro上，鍵入：

相關：如何使用pandoc在Linux命令列上轉換檔案

手冊頁的部分

手冊頁包含遵循標準命名約定的部分。您的手冊頁需要的部分由您所描述的命令的複雜程度決定。

大多數手冊頁至少包含以下部分：

• Name：命令的名稱和描述其功能的簡潔的一行程式碼。
• 概要：對某人可以用來啟動程式的呼叫的簡短描述。它們顯示了可接受的命令列引數的型別。
• 描述：對命令或功能的描述。
• 選項：命令列選項的列表，以及它們的作用。
• 例句：一些常用的例句。
• 退出值：可能的返回碼及其含義。
• bug：已知bug和怪癖的列表。有時，這是補充（或取代）一個連結的問題跟蹤的專案。
• 作者：寫命令的人。
• 版權：您的版權資訊。這些通常還包括程式釋出所依據的許可證型別。

如果您瀏覽一些更復雜的手冊頁，您將看到還有許多其他部分。例如，試試男人。你不必把它們都包括進去，儘管只是那些你真正需要的。手冊頁不是羅嗦的地方。

您經常會看到的其他部分包括：

• 另請參閱：與主題相關的其他命令有些人會覺得有用或相關。
• 檔案：包中包含的檔案列表。
• 注意事項：需要了解或注意的其他事項。
• 歷史記錄：命令的更改歷史記錄。

手冊的章節

Linux手冊由所有手冊頁組成，然後分為以下編號部分：

1. 可執行程式：或，shell命令。
2. 系統呼叫：核心提供的函式。
3. 庫呼叫：程式庫中的函式。
4. 特殊檔案。
5. 檔案格式和約定：例如，“/etc/passwd”。
6. 遊戲。
7. 雜項：巨集包和約定，如groff。
8. 系統管理命令：通常為root使用者保留。
9. 核心例程：預設情況下通常不安裝。

每個手冊頁都必須指明它屬於哪個節，並且還必須儲存在該節的適當位置，我們將在後面看到。命令和實用程式的手冊頁屬於第一節。

手冊頁的格式

groff巨集格式不容易直觀地解析。相比之下，降價是輕而易舉的事。

下面是groff中的手冊頁。

下表中顯示了相同的頁面。

前沿問題

前三條線形成了所謂的前物質。這些都必須以百分號（%）開頭，不帶前導空格，後面有一個，後跟：

• 第一行：包含命令的名稱，後跟括號中的手動部分，不帶空格。該名稱將成為手冊頁標題的左側和右側部分。按照慣例，命令名是大寫的，儘管你會發現很多不是大寫的。任何跟在命令名和手動節號後面的都會變成頁尾的左邊部分。用這個表示軟體版本號很方便。
• 第二行：作者姓名。這些將顯示在手冊頁的自動生成的作者部分中。您不必新增“Authors”部分，只需在此處至少包含一個名稱。
• 第三行：日期，它也成為頁尾的中心部分。

名稱

節由以數字符號（#）開頭的行表示，這是標記，表示標記中的標題。數字符號（#）必須是行上的第一個字元，後跟空格。

name部分包含一個快捷的單行，其中包括命令的名稱、空格、連字元（-）、空格，然後是命令所做的非常簡短的描述。

簡介

概要包含命令列可以採用的不同格式。此命令可以接受搜尋模式或命令列選項。命令名兩側的兩個星號（**）表示該名稱將在手冊頁上以粗體顯示。某個文字兩側的單個星號（*）將使手冊頁帶下劃線顯示。

預設情況下，換行符後跟一個空行。要強制不帶空行的硬中斷，可以使用尾隨的反斜槓（\）。

描述

說明說明了命令或程式的作用。它應該簡潔地涵蓋重要的細節。記住，你不是在寫使用者指南。

在行首使用兩個數字符號（##）建立第二級標題。你可以用這些來把你的描述分成小塊。

選項

選項部分包含可與命令一起使用的任何命令列選項的說明。按照慣例，它們以粗體顯示，因此在它們前後包含兩個星號（**）。在下一行包含選項的文字描述，並以冒號（：）開頭，後跟空格。

如果描述足夠簡短，man將在命令列選項的同一行上顯示它。如果太長，則顯示為縮排段落，從命令列選項下面的行開始。

示例

示例部分包含不同命令列格式的選擇。注意，我們用冒號（：）開始描述行，就像我們在opti***部分所做的那樣。

退出值

本節列出了命令傳送回撥用程序的返回值。如果您從命令列呼叫它，則可能是shell；如果您從shell指令碼啟動它，則可能是指令碼。在本節中，我們也用冒號（：）開始描述行。

漏洞

bug部分列出了人們需要了解的已知bug、問題或怪癖。對於開源專案，通常會在這裡包含一個指向專案問題跟蹤程式的連結，以檢查任何bug的狀態或報告新bug。

版權

“版權”部分包含您的版權宣告，通常還包含軟體釋出所依據的許可證型別的說明。

高效的工作流

您可以在最喜愛的編輯器中編輯手冊頁。大多數支援語法突出顯示的人都會意識到標記和顏色的文字突出標題，以及粗體和下劃線。這是偉大的，因為它去，但你沒有看到一個呈現的手冊頁，這是真正的證據布丁。

在包含標記檔案的目錄中開啟終端視窗。在編輯器中開啟後，定期將檔案儲存到硬碟。每次執行此操作時，都可以在終端視窗中執行以下命令：

使用此命令後，可以按向上箭頭重複，然後按Enter鍵。

此命令還呼叫標記檔案上的pandoc（這裡稱為“ms.1.md”）：

• -s（獨立）選項生成從上到下的完整手冊頁，而不僅僅是一些man格式的文字。
• 帶有“man”運算子的-t（output type）選項告訴pandoc以man格式生成其輸出。我們還沒有告訴pandoc將其輸出傳送到一個檔案，所以它將被髮送到stdout。

我們還使用-l（本地檔案）選項將輸出輸出到man中。它告訴人們不要在人工資料庫中搜索手冊頁。相反，它應該開啟命名檔案。如果檔名為-，則man將從stdin獲取輸入。

歸根結底，您可以從編輯器中儲存，並按Q鍵關閉man（如果它在終端視窗中執行）。然後，您可以按向上箭頭鍵，然後按Enter鍵以檢視手冊頁的呈現版本，就在man中。

相關：Linux上的stdin、stdout和stderr是什麼？

建立手冊頁

完成手冊頁後，需要建立手冊頁的最終版本，然後將其安裝到系統上。下面的命令告訴pandoc生成一個名為“ms.1”的手冊頁：

這遵循的慣例是，按照手冊頁所描述的命令命名手冊頁，並將手冊節號作為副檔名附加。

這將建立一個“ms.1”檔案，這是我們的新手冊頁。我們把它放在哪裡？此命令將告訴我們在哪裡人工搜尋手冊頁：

結果為我們提供了以下資訊：

• /usr/share/man：手冊頁標準庫的位置。我們不向該庫新增頁面。
• /usr/local/share/man：這個符號連結指向“/usr/local/man”
• /usr/local/man：這是我們需要放置新手冊頁的地方。

請注意，不同的手冊部分包含在各自的目錄中：man1、man2、man3等等。如果節的目錄不存在，我們需要建立它。

為此，我們鍵入以下內容：

然後將“ms.1”檔案複製到正確的目錄：

man希望手冊頁被壓縮，所以我們將使用gzip來壓縮它：

要使man將新檔案新增到其資料庫中，請鍵入以下內容：

就這樣！現在，我們可以透過鍵入以下命令將新的手冊頁與其他手冊頁相同：

找到並顯示我們的新手冊頁。

它看起來就像任何其他手冊頁一樣，在適當的位置有粗體、下劃線和縮排文字。

與所描述的選項相鄰的描述行顯示在同一行上。太長而無法容納的行顯示在它們所描述的選項下面。

我們還自動生成了一個“Authors”部分。頁尾還包括前面定義的軟體版本號、日期和命令名。

如果你想。

一旦pandoc建立了您的手冊頁，您還可以直接以groff巨集格式編輯該檔案，然後將其移動到手冊頁目錄，並對其進行gzip處理。