如何在 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 。