Fatmawati Achmad Zaenuri/Shutterstock Fatmawati Achmad Zaenuri / Shutterstock

Want your new Linux program to look professional? Give it a man page. We’ll show you the easiest, and fastest, way to do it.

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

佩奇 (The man Pages )

There’s a kernel of truth in the old Unix joke, “the only command you need to know is man.” The man pages contain a wealth of knowledge, and they should be the first place you turn when you want to learn about a command.

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

Providing a man page for a utility or command you’ve written elevates it from a useful piece of code to a fully-formed Linux package. People expect a man page to be provided for a program that’s been written for Linux. If you’re natively supporting Linux, a man page is mandatory if you want your program to be taken seriously.

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

Historically the man pages have been written using a set of formatting macros. When you call upon man to open a page, it calls groff to read the file and generate formatted output, according to the macros in the file. The output is piped into less, and then?displayed for you.

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

Unless you create man pages frequently, writing one and manually inserting the macros is hard work. The act of creating a man page that parses correctly and looks right can overtake your aim to provide a concise, yet thorough, description of your command.

除非您經常創建man頁，否則很難編寫一頁并手動插入宏。 創建正確解析并看起來正確的man頁的行為可能會超出您的目標，即為您的命令提供簡潔而透徹的描述。

You should be concentrating on your content, not battling an obscure set of macros.

您應該專注于內容，而不是與晦澀難懂的宏作斗爭。

搶救潘多克 (pandoc to the Rescue )

The pandoc program reads markdown files and generates new ones in about 40 different markup languages and document formats, including that of the man page. It totally transforms the man page writing process so you don’t have to wrestle with hieroglyphics.

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

To get started, you can install pandoc on Ubuntu with this command:

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

sudo apt-get install pandoc

On Fedora, the command you need is the following:

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

sudo dnf install pandoc

On Manjaro, type:

在Manjaro上，輸入：

sudo pacman -Syu pandoc

男人的頁面 (Sections of a man Page )

man pages contain sections that follow a standard naming convention.?The sections your man page needs are dictated by the sophistication of the command you’re describing.

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

At a minimum, most man pages contain these sections:

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

• Name: The name of the command and a pithy one-liner that describes its function.

  名稱 ：命令的名稱和描述其功能的簡潔代碼。

• Synopsis: A terse description of the invocations someone can use to launch the program. These show the types of accepted command-line parameters.

  簡介 ：簡短描述可以用來啟動程序的調用。 這些顯示了可接受的命令行參數的類型。

• Description: A description of the command or function.

  描述 ：命令或功能的描述。

• Options: A list of command-line options, and what they do.

  選項 ：命令行選項及其作用的列表。

• Examples: Some examples of common usage.

  例子 ：一些常用的例子。

• Exit Values: The possible return codes and their meanings.

  退出值 ：可能的返回碼及其含義。

• Bugs: A list of known bugs and quirks. Sometimes, this is supplemented with (or replaced by) a link to the issue tracker for the project.

  錯誤 ：已知錯誤和怪癖的清單。 有時，這可以通過指向項目問題跟蹤器的鏈接來補充(或替換為鏈接)。

• Author: The person or people who wrote the command.

  作者 ：編寫命令的人。

• Copyright: Your copyright message. These also usually include the type of license under which the program is released.

  版權 ：您的版權信息。 這些通常還包括發布程序所依據的許可證類型。

If you look through some of the more complicated man pages, you’ll see there are many other sections, as well. For example, try man man. You don’t have to include them all, though—just those you really need. man pages are no place for wordiness.

如果您瀏覽一些更復雜的man頁，還將看到其他許多部分。 例如，嘗試man man 。 但是，您不必包括所有內容，而只是您真正需要的內容。 man頁無處可羅。

Some other sections you’ll see reasonably frequently are:

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

• See Also: Other commands related to the subject matter some would find useful or relevant.

  另請參見 ：與主題相關的其他命令可能會有用或相關。

• Files: A list of files included in the package.

  文件 ：軟件包中包含的文件列表。

• Caveats: Other points to know or watch out for.

  注意事項 ：需要了解或注意的其他事項 。

• History: A change history for the command.

  歷史記錄 ：命令的更改歷史記錄。

手冊各節 (Sections of the Manual )

The Linux manual is made up of all the man pages, which is then split into these numbered sections:

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

Executable programs: Or, shell commands.

可執行程序：或者，shell命令。

System calls: Functions provided by the kernel.

系統調用：內核提供的功能。

Library calls: Functions within program libraries.

庫調用：程序庫中的函數。

Special files.

特殊文件。

File formats and conventions: For example, “/etc/passwd”.

文件格式和約定：例如，“ / etc / passwd”。

Games.

游戲。

Miscellaneous: Macro packages and conventions, such as groff.

其他：宏包和約定，例如groff 。

System administration commands: Usually reserved for root.

系統管理命令：通常保留給root用戶。

Kernel routines: Not usually installed by default.

內核例程：默認情況下通常不安裝。

Every man page must indicate to which section it belongs, and it must also be stored in the appropriate location for that section, as we’ll see later on. The man pages for commands and utilities belong in section one.

每個man頁都必須指出它屬于哪個部分，并且還必須將其存儲在該部分的適當位置，這將在后面介紹。 有關命令和實用程序的man頁在第一部分中。

手冊頁的格式 (The Format of a man Page )

The groff macro format is not easy to visually parse. In contrast, markdown is a breeze.

groff宏格式不容易從視覺上解析。 相比之下，降價很容易。

Below is a man page in?groff.

以下是groff的手冊頁。

The same page is shown below in markdown.

降價顯示在同一頁面。

前事 (Front Matter)

The first three lines form something called front matter. These must all start with a percentage sign (%), with no leading spaces but one afterward, followed by:

前三行形成所謂的前沿問題 。 這些都必須以百分號( % )開頭，開頭不能有空格，但后面要跟一個：

• The first line: Contains the name of the command, followed by the manual section in parentheses, with no spaces. The name becomes the left and right sections of the man page header. By convention, the command name is in uppercase, although you’ll find plenty that aren’t. Anything that follows the command name and manual section number becomes the left section of the footer. It’s convenient to use this for the software version number.

  第一行：包含命令名稱，后跟括號中的手冊部分，不帶空格。 該名稱將成為man頁標題的左側和右側部分。 按照慣例，命令名稱是大寫的，盡管您會發現很多不是的。 命令名稱和手冊部分編號之后的所有內容都將成為頁腳的左側部分。 將其用于軟件版本號很方便。

• The second line: The name(s) of the author(s). These are displayed in an automatically-generated authors section of the man page. You don’t have to add an “Authors” section—just include at least one name here.

  第二行：作者的姓名。 這些顯示在man頁的自動生成的作者部分中。 您無需添加“作者”部分，只需在此處至少包含一個名稱即可。

• The third line: The date, which also becomes the center part of the footer.

  第三行：日期，它也成為頁腳的中心部分。

名稱 (Name)

Sections are indicated by lines that start with a number sign (#), which is the markup that indicates a header in markdown. The number sign (#)?must be the first character on the line, followed by a space.

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

The name section holds a snappy one-liner that includes the name of the command, a space, a hyphen (-), a space, and then a very short description of what the command does.

名稱部分包含一個活潑的單行代碼，其中包括命令的名稱，空格，連字符( - )，空格，然后是命令功能的簡短描述。

概要 (Synopsis)

The synopsis holds the different formats the command line can take. This command can accept a search pattern or a command-line option. The two asterisks (**) on either side of the command name mean the name will be displayed in bold on the man page. A single asterisk (*) on either side of some text causes the man page to display it underlined.

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

By default, a line break is followed by a blank line. To force a hard break without a blank line, you can use a trailing?backslash (\).

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

描述 (Description)

The description explains what the command or program does. It should cover the important details succinctly. Remember, you’re not writing a user’s guide.

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

Using two number signs (##) at the start of a line creates a level two heading. You can use these to break your description into smaller chunks.

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

選件 (Options)

The options section contains a description of any command-line options that can be used with the command. By convention, these are displayed in bold, so include two asterisks (**) before and after them. Include the text description of the options on the next line and start it with a colon (:), followed by a space.

選項部分包含可與該命令一起使用的所有命令行選項的說明。 按照約定，它們以粗體顯示，因此在其前后應包含兩個星號( ** )。 包括選項在下一行文字說明，并用冒號啟動( : )，后跟一個空格。

If the description is short enough, man?will display it on the same line as the command-line option. If it’s too long, it’s displayed as an indented paragraph that begins on the line below the command-line option.

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

例子 (Examples)

The examples section contains a selection of different command-line formats. Note that we start the description lines with a colon (:), just as we did the options section.

示例部分包含不同的命令行格式的選擇。 需要注意的是，我們用冒號開始描述線( : )，就像我們做的選項部分。

退出值 (Exit Values)

This section lists the return values your command sends back to the calling process. This might be the shell if you called it from the command line, or a script if you launched it from a shell script.?We start description lines with a colon (:) in this section, too.

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

蟲子 (Bugs)

The bugs section lists known bugs, gotchas, or quirks people need to know about. For open-source projects, it’s common to include a link here to the project’s issue tracker to check on the status of any bugs or report new ones.

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

版權 (Copyright)

The copyright section contains your copyright statement, and, usually, a description of the type of license under which the software is released.

版權部分包含您的版權聲明，通常包含對發布該軟件所依據的許可證類型的描述。

高效的工作流程 (An Efficient Workflow)

You can edit your man page in your favorite editor. Most that support syntax highlighting will be aware of markdown and color the text to highlight headings, as well as bold and underline it. That’s great as far as it goes, but you’re not looking at a rendered man page, which is the real proof in the pudding.

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

Open a terminal window in the directory that contains your markdown file.?With it open in your editor, periodically save your file to your hard drive. Each time you do, you can execute the following command in the terminal window:

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

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

Once you’ve used this command, you can press the Up arrow to repeat it, and then press Enter.

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

This command also invokes?pandoc on the markdown file (here, it’s called “ms.1.md”):

此命令還會在markdown文件上調用pandoc (在這里，它稱為“ ms.1.md”)：

• The -s (standalone) option generates a top-to-bottom complete man page, rather than just some text in man format.

  -s (獨立)選項會生成一個從上到下的完整man頁，而不只是一些man格式的文本。

• The -t (output type) option with the “man” operator tells pandoc to generate its output in man format. We haven’t told pandoc to send its output to a? file, so it’ll be sent to stdout.

  帶有“ man”運算符的-t (輸出類型)選項告訴pandoc以man格式生成其輸出。 我們尚未告訴pandoc將其輸出發送到文件，因此它將被發送到stdout 。

We’re also piping that output into man?with the -l (local file) option. It tells man?not to search through the man database looking for the man page. Instead, it should open the named file. If the filename is -,?man will take its input from stdin.

我們還將使用-l (本地文件)選項將輸出輸出到man 。 它告訴man不要在man數據庫中搜索以查找man頁面。 而是應打開命名文件。 如果文件名是- ，則man將從stdin接受輸入。

What this boils down to is you can save from your editor and press Q to close man?if it’s running in the terminal window. Then, you can press the Up arrow, followed by Enter to see a rendered version of your man page, right inside man.

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

創建您的手冊頁 (Creating Your man Page)

After you’ve completed your man page, you need to create a final version of it, and then install it on your system. The following command tells?pandoc?to generate a man page called “ms.1”:

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

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

This follows the convention of naming the man page after the command it describes and appending the manual section number as though it were a file extension.

這遵循以下約定：在描述的命令后命名man頁，并附加手冊的章節號，就好像它是文件擴展名一樣。

This creates an “ms.1” file, which is our new man page. Where do we put it? This command will tell us where?man searches for man pages:

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

manpath

The results give us the following info:

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

• /usr/share/man: The location of the standard library of man pages. We don’t add pages to this library.

  / usr / share / man： man頁標準庫的位置。 我們不會將頁面添加到該庫中。

• /usr/local/share/man: This symbolic link points to “/usr/local/man.”

  / usr / local / share / man：此符號鏈接指向“ / usr / local / man”。

• /usr/local/man: This is where we need to place our new man page.

  / usr / local / man：這是我們需要放置新man頁的地方。

Note that the different manual sections are contained within their own directories: man1, man2, man3, and so on. If the directory for the section doesn’t exist, we need to create it.

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

To do so, we type the following:

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

sudo mkdir /usr/local/man/man1

We then copy the “ms.1” file to the correct directory:

然后，我們將“ ms.1”文件復制到正確的目錄中：

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

man expects the man pages to be compressed, so we’ll use?gzip to compress it:

man希望壓縮man頁，因此我們將使用gzip 進行壓縮 ：

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

To make man add the new file to its database, type the following:

為了使man新的文件添加到它的數據庫，輸入以下命令：

sudo mandb

That’s it! We can now call our new man page the same as any other by typing:

而已！ 現在，我們可以通過鍵入以下內容來將我們的新man頁稱為其他man頁：

man ms

Our new man page is found and displayed.

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

It looks just like any other man page, with bold, underlined, and indented text in the appropriate places.

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

Lines of description that fit next to the option they describe appear on the same line. Lines that are too long to fit appear below the option they describe.

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

We’ve also automatically generated an “Authors” section. The footer also includes the software version number, date, and command name, as defined in the front matter.

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

如果你想 。 。 。 (If You Want to . . .)

Once pandoc has created your?man page, you can also directly edit the file in the groff macro format before moving it to the man page directory, and gzip it.

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

翻譯自: https://www.howtogeek.com/682871/how-to-create-a-man-page-on-linux/

總結

以上是生活随笔為你收集整理的如何在Linux上创建手册页的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。