如何在Linux上创建手册页

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页组成，然后将其分为以下编号部分：

1. Executable programs: Or, shell commands.

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

2. System calls: Functions provided by the kernel.

   系统调用：内核提供的功能。

3. Library calls: Functions within program libraries.

   库调用：程序库中的函数。

4. Special files.

   特殊文件。

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

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

6. Games.

   游戏。

7. Miscellaneous: Macro packages and conventions, such as groff.

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

8. System administration commands: Usually reserved for root.

   系统管理命令：通常保留给root用户。

9. 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/