如何在Linux上創建手冊頁

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

佩奇

在舊的Unix笑話中有一個真相，“ 您只需要的命令知道是 man“ man 頁麵包含豐富的知識，當您想了解命令時，它們應該是您打開的第一位。

提供一個 man 您編寫的實用程序或命令的頁面將其從有用的代碼片段升級為完整的Linux軟件包。人們期望 man 為Linux編寫的程序提供的頁面。如果您本機支持Linux，則 man 如果您想認真對待程序，則必須填寫該頁面。

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

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

您應該專注於自己的內容，而不是與模糊的宏作鬥爭。

搶救潘多克

pandoc 程序讀取markdown文件並以大約40種不同的標記語言和文檔格式生成新文件，包括 man 頁。它完全改變了 man 頁面編寫過程，因此您不必費心像形文字。

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

須藤apt-get install pandoc

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

須藤dnf安裝pandoc

在Manjaro上，輸入：

須藤pacman -Syu pandoc

手冊頁

man 頁麵包含遵循標準命名約定的部分。您的部分 man 頁面需求由您描述的命令的複雜程度決定。

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

姓名：命令名稱和描述其功能的簡單代碼。
概要：簡短的描述，說明有人可以用來啟動程序的調用。這些顯示了可接受的命令行參數的類型。
產品描述：命令或功能的描述。
選項：命令行選項及其作用的列表。
項目範例 ：一些常用用法示例。
退出值：可能的返回碼及其含義。
錯誤：已知錯誤和怪癖的列表。有時，可以用指向項目問題跟踪器的鏈接來補充（或代替）鏈接。
作者：編寫命令的人。
版權：您的版權信息。這些通常還包括發布程序所依據的許可證類型。

如果您看一些更複雜的 man 頁面上，您還將看到其他許多部分。例如，嘗試 man man。但是，您不必包括所有內容，而只是您真正需要的內容。 man 頁面上沒有冗長的地方。

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

參見：與主題相關的其他命令可能會有用或相關。
檔：軟件包中包含的文件列表。
注意事項：要了解或提防的其他要點。
歷史：命令的更改歷史記錄。

手冊各節

Linux手冊由所有 man 頁，然後將其分為以下編號部分：

可執行程序： 或者，shell命令。
系統調用： 內核提供的功能。
圖書館電話： 程序庫中的功能。
特殊文件。
文件格式和約定： 例如，“ / etc / passwd”。
遊戲。
其他： 宏包和約定，例如 groff.
系統管理命令： 通常保留給root。
內核例程： 默認情況下通常不安裝。

祇限 man 該頁面必須指明它屬於哪個部分，並且還必須將其存儲在該部分的適當位置，這將在後面介紹。的 man 有關命令和實用程序的頁面在第一部分中。

手冊頁的格式

groff 宏格式不容易直觀地解析。相比之下，降價很容易。

以下是手冊頁 groff.

降價顯示在同一頁面。

前事

前三行形成一個稱為前題。這些都必須以百分號（%），後面沒有空格，後面跟著一個：

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

姓名

這些部分由以數字符號（#），即表示markdown中的標頭的標記。數字符號（#) 必須是該行的第一個字符，後跟一個空格。

名稱部分包含一個活潑的單行代碼，其中包含命令的名稱，空格，連字符（-），空格，然後是該命令的簡短描述。

概要

內容提要包含命令行可以採用的不同格式。該命令可以接受搜索模式或命令行選項。兩個星號（**）在命令名稱的兩側表示該名稱將以粗體顯示在 man 頁。單個星號（*）在某些文本的兩邊會導致 man 頁面上用下劃線顯示。

默認情況下，換行符後是空白行。要強制硬中斷而沒有空白行，可以使用尾隨反斜杠（).

產品描述

該說明解釋了命令或程序的功能。它應該簡要地涵蓋重要的細節。請記住，您並不是在編寫用戶指南。

使用兩個數字符號（##）在一行的開頭創建一個二級標題。您可以使用它們將您的描述分成較小的塊。

選項

選項部分包含可與該命令一起使用的所有命令行選項的說明。按照慣例，它們以粗體顯示，因此請添加兩個星號（**）之前和之後。在下一行中包含選項的文本描述，並以冒號（:），後跟一個空格。

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

項目範例

示例部分包含不同的命令行格式的選擇。請注意，我們在描述行中以冒號（:），就像我們在“選項”部分所做的一樣。

退出值

本部分列出了命令發送回調用過程的返回值。如果是從命令行調用的，則可能是shell；如果是從shell腳本啟動的，則可能是腳本。我們以冒號（:）。

錯誤

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

版權

高效的工作流程

您可以編輯 man 您喜歡的編輯器中的頁面。支持語法高亮顯示的大多數代碼將意識到降價並為文本加上顏色以高亮顯示標題，以及將其加粗和加下劃線。就目前而言，這很好，但您並不是在看渲染 man 頁，這是布丁中的真實證明。

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

潘多克ms.1.md -s -t man | / usr / bin / man -l-

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

該命令還調用 pandoc 在降價文件上（在這裡，它稱為“ ms.1.md”）：

-s （獨立）選項生成自上而下的完整內容 man 頁面，而不僅僅是其中的一些文本 man 格式。
-t （輸出類型）選項與“ man”運算符告訴 pandoc 產生它的輸出 man 格式。我們還沒有告訴 pandoc 將其輸出發送到文件，以便將其發送到 stdout.

我們還將管道輸出到 man 與 -l （本地文件）選項。它說 man 不要搜索 man 數據庫尋找 man 頁。而是應打開命名文件。如果文件名是 -, man 將從 stdin.

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

創建您的手冊頁

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

潘多克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等。如果該部分的目錄不存在，我們需要創建它。

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

須藤mkdir / usr / local / man / man1

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

須藤cp ms.1 / usr / local / man / man1

man 期望 man 要壓縮的頁面，因此我們將使用 gzip 壓縮它:

須藤gzip /usr/local/man/man1/ms.1

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

sudo mandb

而已！現在我們可以叫新 man 通過鍵入以下內容來使頁面與其他頁面相同：

女士

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

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

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

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

如果你想。。。

一旦 pandoc 創建了您的 man 頁面上，您也可以直接在 groff 宏格式，然後再將其移至 man 頁面目錄，以及 gzip 它。

原始文章

佩奇