如何在 Linux 上創建手冊頁

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

手冊頁

古老的 Unix 笑話中有一個真理的核心，“你需要知道的唯一命令是man 。” man頁包含豐富的知識，當您想了解命令時，它們應該是您首先要翻閱的地方。

為您編寫的實用程序或命令提供man頁可將其從有用的代碼提升為完整的 Linux 包。 人們希望為為 Linux 編寫的程序提供man頁。 如果您本身就支持 Linux，那麼如果您希望您的程序被認真對待，那麼man頁是強制性的。

從歷史上看， man頁是使用一組格式化宏編寫的。 當你調用man打開頁面時，它會調用groff來讀取文件並根據文件中的宏生成格式化輸出。 輸出通過管道傳輸到less ，然後為您顯示。

除非您經常創建man頁，否則編寫手冊並手動插入宏是一項艱鉅的工作。 創建一個可以正確解析並看起來正確的man頁的行為可能會超越您提供簡潔而全面的命令描述的目標。

您應該專注於您的內容，而不是與一組晦澀的宏作鬥爭。

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

pandoc 救援

pandoc程序讀取降價文件並以大約 40 種不同的標記語言和文檔格式（包括man頁的格式）生成新文件。 它完全改變了man頁的編寫過程，因此您不必與象形文字搏鬥。

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

 sudo apt-get 安裝 pandoc 

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

 須藤 dnf 安裝 pandoc 

在 Manjaro 上，鍵入：

 sudo pacman -Syu pandoc 

相關：如何使用 pandoc 在 Linux 命令行上轉換文件

手冊頁的部分

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

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

• 名稱：命令的名稱和描述其功能的簡潔的單行字。
• 概要：對某人可以用來啟動程序的調用的簡要描述。 這些顯示了接受的命令行參數的類型。
• 描述：命令或功能的描述。
• 選項：命令行選項列表，以及它們的作用。
• 示例：一些常見用法的示例。
• 退出值：可能的返回碼及其含義。
• 錯誤：已知錯誤和怪癖的列表。 有時，這會補充（或替換為）項目問題跟踪器的鏈接。
• 作者：編寫命令的人。
• 版權：您的版權信息。 這些通常還包括發布程序的許可類型。

如果您瀏覽一些更複雜的man頁，您會發現還有許多其他部分。 例如，嘗試man man 。 不過，您不必將它們全部包含在內——只需包含您真正需要的那些。 man頁不適合冗長。

您會經常看到的其他一些部分是：

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

手冊章節

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

1. 可執行程序：或者，shell 命令。
2. 系統調用：內核提供的函數。
3. 庫調用：程序庫中的函數。
4. 特殊文件。
5. 文件格式和約定：例如，“/etc/passwd”。
6. 遊戲。
7. 雜項：宏包和約定，例如groff 。
8. 系統管理命令：通常為 root 保留。
9. 內核例程：默認情況下通常不安裝。

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

手冊頁的格式

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

下面是groff的手冊頁。

相同的頁面顯示在下面的降價中。

前沿問題

前三行形成了一種叫做front matter的東西。 這些都必須以百分號 ( % ) 開頭，沒有前導空格，只有一個後跟，然後是：

• 第一行：包含命令的名稱，後面是括號中的手冊部分，沒有空格。 該名稱成為man頁標題的左右部分。 按照慣例，命令名稱是大寫的，儘管你會發現很多不是。 命令名稱和手冊部分編號之後的任何內容都將成為頁腳的左側部分。 用這個作為軟件版本號很方便。
• 第二行：作者姓名。 這些顯示在man頁的自動生成的作者部分中。 您不必添加“作者”部分，只需在此處至少包含一個姓名即可。
• 第三行：日期，也成為頁腳的中心部分。

名稱

部分由以數字符號 ( # ) 開頭的行表示，這是在 markdown 中指示標題的標記。 數字符號 ( #)必須是該行的第一個字符，後跟一個空格。

名稱部分包含一個簡潔的單行代碼，其中包括命令的名稱、一個空格、一個連字符 ( - )、一個空格，然後是對該命令作用的非常簡短的描述。

概要

概要包含命令行可以採用的不同格式。 此命令可以接受搜索模式或命令行選項。 命令名稱兩側的兩個星號 ( ** ) 表示該名稱將在man頁上以粗體顯示。 某些文本兩側的單個星號 ( * ) 會導致man頁將其顯示為帶下劃線。

默認情況下，換行符後跟一個空行。 要在沒有空行的情況下強制進行硬中斷，您可以使用尾部反斜杠 ( \ )。

描述

描述解釋了命令或程序的作用。 它應該簡潔地涵蓋重要的細節。 請記住，您不是在編寫用戶指南。

在行首使用兩個數字符號 ( ## ) 會創建一個二級標題。 您可以使用這些將您的描述分解成更小的塊。

選項

選項部分包含可與命令一起使用的任何命令行選項的描述。 按照慣例，它們以粗體顯示，因此在它們之前和之後包括兩個星號 ( ** )。 在下一行包含選項的文本描述，並以冒號 ( : ) 開頭，後跟一個空格。

如果描述足夠短， man會將其顯示在與命令行選項相同的行上。 如果它太長，它會顯示為從命令行選項下方的行開始的縮進段落。

例子

示例部分包含一系列不同的命令行格式。 請注意，我們以冒號 ( : ) 開始描述行，就像我們在選項部分中所做的那樣。

退出值

本節列出了您的命令發送回調用進程的返回值。 如果您從命令行調用它，這可能是 shell；如果您從 shell 腳本啟動它，它可能是腳本。 在本節中，我們也以冒號 ( :開始描述行。

錯誤

錯誤部分列出了人們需要了解的已知錯誤、陷阱或怪癖。 對於開源項目，通常會在此處包含指向項目問題跟踪器的鏈接，以檢查任何錯誤的狀態或報告新錯誤。

版權

版權部分包含您的版權聲明，通常還包含對發佈軟件的許可類型的描述。

高效的工作流程

您可以在您喜歡的編輯器中編輯您的man頁。 大多數支持語法突出顯示的人都會意識到降價並為文本著色以突出顯示標題，以及加粗和下劃線。 就目前而言，這很好，但是您不是在查看渲染的man頁，這是布丁中的真正證明。

在包含您的降價文件的目錄中打開一個終端窗口。 在編輯器中打開它，定期將文件保存到硬盤。 每次執行此操作時，都可以在終端窗口中執行以下命令：

 pandoc ms.1.md -s -t man | /usr/bin/man -l - 

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

此命令還調用降價文件上的pandoc （此處稱為“ms.1.md”）：

• -s （獨立）選項生成一個從上到下的完整man頁，而不僅僅是一些man格式的文本。
• 帶有“man”運算符的-t （輸出類型）選項告訴pandoc以man格式生成其輸出。 我們還沒有告訴pandoc將其輸出發送到文件，因此它將被發送到stdout 。

我們還使用-l （本地文件）選項將該輸出通過管道傳輸到man中。 它告訴man不要在man數據庫中搜索man頁。 相反，它應該打開命名文件。 如果文件名是- ， man將從stdin獲取其輸入。

這歸結為您可以從編輯器中保存並按 Q 關閉man如果它在終端窗口中運行。 然後，您可以按向上箭頭，然後按 Enter 以查看man頁的渲染版本，就在man中。

相關： Linux 上的標準輸入、標準輸出和標準錯誤是什麼？

創建你的手冊頁

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

 pandoc ms.1.md -s -t man -o ms.1 

這遵循在它描述的命令之後命名man頁並附加手冊節號的約定，就好像它是文件擴展名一樣。

這將創建一個“ms.1”文件，這是我們的新man頁。 我們把它放在哪裡？ 該命令將告訴我們man在哪裡搜索man頁：

 人路

結果為我們提供了以下信息：

• /usr/share/man： man頁標準庫的位置。 我們不會將頁面添加到此庫中。
• /usr/local/share/man：這個符號鏈接指向“/usr/local/man”。
• /usr/local/man：這是我們需要放置新man頁的地方。

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

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

 sudo mkdir /usr/local/man/man1

然後我們將“ms.1”文件複製到正確的目錄：

 sudo cp ms.1 /usr/local/man/man1

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

 sudo gzip /usr/local/man/man1/ms.1

要使man將新文件添加到其數據庫中，請鍵入以下內容：

 須藤 mandb 

而已！ 我們現在可以通過鍵入以下內容來調用我們的新man頁：

 男女士

找到並顯示了我們的新man頁。

它看起來就像任何其他man頁一樣，在適當的位置帶有粗體、下劃線和縮進的文本。

與其描述的選項相鄰的描述行出現在同一行。 太長而無法容納的行顯示在它們描述的選項下方。

我們還自動生成了“作者”部分。 頁腳還包括軟件版本號、日期和命令名稱，如前面所定義的。

如果你想 。 . .

一旦pandoc創建了您的man頁，您還可以直接編輯groff宏格式的文件，然後將其移動到man頁目錄，然後gzip 。