如何在 Linux 上创建手册页

想让你的新 Linux 程序看起来很专业吗？给它一个 man 页面。我们将向您展示最简单、最快的方法。

手册页

古老的 Unix 笑话中有一个真理的核心，“你唯一需要知道的命令是 man。” man 页面包含丰富的知识，当您想要了解命令时，它们应该是您首先转向的地方。

为您编写的实用程序或命令提供 man 页面可将其从一段有用的代码提升为一个完整的 Linux 程序包。人们希望为 Linux 编写的程序提供 man 页面。如果您本身就支持 Linux，并且希望您的程序受到重视，那么 man 页面是必需的。

历史上，man 页面是使用一组格式化宏编写的。当您调用 man 打开一个页面时，它会调用 groff 来读取文件并根据文件中的宏生成格式化输出。输出通过管道传输到 less，然后显示给您。

除非您经常创建 man 页面，否则编写一个页面并手动插入宏是一项艰巨的工作。创建一个能够正确解析且看起来正确的 man 页面的行为可能会超出您提供简洁而全面的命令描述的目标。

你应该专注于你的内容，而不是与一组晦涩的宏作斗争。

救援潘多克

pandoc 程序读取 markdown 文件并以大约 40 种不同的标记语言和文档格式生成新文件，包括 man 页面的文件。它完全改变了 man 页面的编写过程，因此您不必为象形文字而苦恼。

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

sudo apt-get install pandoc

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

sudo dnf install pandoc

在 Manjaro 上，输入：

sudo pacman -Syu pandoc

手册页的部分

man 页面包含遵循标准命名约定的部分。您的 man 页面需要的部分由您描述的命令的复杂程度决定。

大多数手册页至少包含以下部分：

• 名称：命令的名称和描述其功能的简明单行。
• 概要：对可用于启动程序的调用的简要描述。这些显示了可接受的命令行参数的类型。
• 描述：命令或函数的描述。
• 选项：命令行选项及其作用的列表。
• Examples：一些常见用法的示例。
• 退出值：可能的返回码及其含义。
• 错误：已知错误和怪癖的列表。有时，它会补充（或替换为）项目问题跟踪器的链接。
• 作者：编写命令的人。
• 版权：您的版权信息。这些通常还包括发布程序所依据的许可类型。

如果您查看一些更复杂的 man 页面，您会发现还有许多其他部分。例如，尝试 man man。不过，您不必将它们全部包括在内——只包括您真正需要的那些。 man 页面不是冗长的地方。

您会经常看到的其他一些部分是：

• 另请参阅：一些人认为有用或相关的与主题相关的其他命令。
• 文件：包中包含的文件列表。
• 注意事项：其他需要了解或注意的事项。
• 历史：命令的更改历史。

手册的章节

Linux 手册由所有 man 页面组成，然后分成这些编号的部分：

1. 可执行程序：或者，shell 命令。
2. 系统调用：内核提供的函数。
3. 库调用：程序库中的函数。
4. 特殊文件。
5. 文件格式和约定：例如，“/etc/passwd”。
6. 游戏。
7. 杂项：宏包和约定，例如groff。
8. 系统管理命令：通常保留给 root。
9. 内核例程：默认情况下通常不安装。

每个 man 页面都必须指明它属于哪个部分，并且还必须存储在该部分的适当位置，我们稍后会看到。命令和实用程序的 man 页面属于第一部分。

手册页的格式

groff 宏格式不容易直观解析。相比之下，Markdown 就轻而易举了。

下面是 groff 中的手册页。

同一页面在 markdown 中显示如下。

前题

前三行构成了一个叫做front matter 的东西。这些都必须以百分号 (%) 开头，没有前导空格，但后面有一个空格，后跟：

• 第一行： 包含命令名称，后面是括号中的手册部分，没有空格。该名称成为 man 页眉的左右部分。按照惯例，命令名称是大写的，尽管您会发现很多不是。命令名称和手册部分编号之后的任何内容都将成为页脚的左侧部分。软件版本号用这个比较方便。
• 第二行：作者姓名。这些显示在 man 页面的自动生成的作者部分。您不必添加“作者”部分，只需在此处至少包含一个姓名即可。
• 第三行：日期，也成为页脚的中间部分。

姓名

部分由以井号 (#) 开头的行表示，这是表示 markdown 中标题的标记。井号 (#) 必须是该行的第一个字符，后跟一个空格。

名称部分包含一个活泼的单行代码，其中包括命令名称、一个空格、一个连字符 (-)、一个空格，然后是对命令功能的非常简短的描述。

概要

概要包含命令行可以采用的不同格式。此命令可以接受搜索模式或命令行选项。命令名称两侧的两个星号 (**) 表示该名称将以粗体显示在 man 页面上。某些文本两侧的单个星号 (*) 会导致 man 页面将其显示为下划线。

默认情况下，换行符后跟一个空行。要在没有空行的情况下强制硬中断，您可以使用尾部反斜杠 (\)。

描述

描述解释了命令或程序的作用。它应该简洁地涵盖重要的细节。请记住，您不是在编写用户指南。

在一行的开头使用两个数字符号 (##) 创建二级标题。您可以使用这些将您的描述分成更小的块。

选项

选项部分包含可与该命令一起使用的任何命令行选项的描述。按照惯例，它们以粗体显示，因此在它们前后包含两个星号 (**)。在下一行包含选项的文本描述，并以冒号 (:) 开头，后跟一个空格。

如果描述足够短，man 会将其显示在与命令行选项相同的行上。如果它太长，它会显示为一个缩进的段落，从命令行选项下方的行开始。

例子

示例部分包含一系列不同的命令行格式。请注意，我们以冒号 (:) 开始描述行，就像我们在选项部分所做的那样。

退出值

此部分列出了您的命令发送回调用进程的返回值。如果您从命令行调用它，则它可能是 shell；如果您从 shell 脚本启动它，则它可能是一个脚本。我们在本节中也以冒号 (:) 开始描述行。

虫子

错误部分列出了人们需要了解的已知错误、陷阱或怪癖。对于开源项目，通常会在此处包含指向项目问题跟踪器的链接，以检查任何错误的状态或报告新错误。

版权

版权部分包含您的版权声明，通常还包含对发布软件所依据的许可类型的描述。

高效的工作流程

您可以在您喜欢的编辑器中编辑您的 man 页面。大多数支持语法高亮显示的都知道 markdown 并为文本着色以突出显示标题，以及粗体和下划线。就目前而言，这已经很棒了，但是您看到的不是呈现的 man 页面，这是布丁中的真实证据。

在包含 markdown 文件的目录中打开终端窗口。在你的编辑器中打开它，定期将你的文件保存到你的硬盘上。每次执行此操作时，您都可以在终端窗口中执行以下命令：

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

使用此命令后，您可以按向上箭头重复它，然后按 Enter。

此命令还会在降价文件（此处称为“ms.1.md”）上调用 pandoc：

• -s（独立）选项生成一个从上到下的完整 man 页面，而不仅仅是一些 man 格式的文本.
• 带有“man”运算符的-t（输出类型）选项告诉pandoc以man格式生成输出。我们还没有告诉 pandoc 将它的输出发送到一个文件，所以它会被发送到 stdout。

我们还使用 -l（本地文件）选项将输出传送到 man。它告诉 man 不要在 man 数据库中搜索 man 页面。相反，它应该打开指定的文件。如果文件名是 -，man 将从 stdin 获取输入。

这归结为您可以从编辑器中保存并按 Q 关闭 man（如果它正在终端窗口中运行）。然后，您可以按向上箭头，然后按 Enter 以在 man 中查看呈现的 man 页面。

创建你的手册页

完成 man 页面后，您需要创建它的最终版本，然后将其安装到您的系统上。以下命令告诉 pandoc 生成一个名为“ms.1”的 man 页面：

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

这遵循了在其描述的命令之后命名 man 页面的惯例，并附加了手册部分编号，就好像它是文件扩展名一样。

这将创建一个“ms.1”文件，这是我们新的 man 页面。我们把它放在哪里？此命令将告诉我们 man 在哪里搜索 man 页面：

manpath

结果为我们提供了以下信息：

• /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 将新文件添加到其数据库，请键入以下内容：

sudo mandb

就是这样！我们现在可以通过键入以下内容来调用我们的新 man 页面：

man ms

找到并显示了我们新的 man 页面。

它看起来就像任何其他 man 页面一样，在适当的位置使用粗体、下划线和缩进文本。

与他们描述的选项相邻的描述行出现在同一行上。太长而不适合的行出现在它们描述的选项下方。

我们还自动生成了“作者”部分。页脚还包括软件版本号、日期和命令名称，如前面所述。

如果你想 。 . .

一旦 pandoc 创建了您的 man 页面，您还可以直接编辑 groff 宏格式的文件，然后再将其移动到 man 页面目录，并将其gzip。