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

手册页

在旧的Unix笑话中有一个核心真理，“你需要知道的唯一命令是man。”手册页包含了丰富的知识，当你想了解一个命令时，应该首先打开手册页。

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

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

除非您经常创建手册页，否则编写一个并手动**宏是一项艰巨的工作。创建一个正确解析并看起来正确的手册页的行为可以超越您的目标，从而提供命令的简明、但彻底的描述。

你应该把注意力集中在你的内容上，而不是和一组晦涩难懂的宏作斗争。

相关：如何使用Linux的man命令：隐藏的秘密和基础

潘多克前往救援

pandoc程序读取标记文件并生成大约40种不同标记语言和文档格式的新文件，包括手册页。它完全改变了手册页的写作过程，所以你不必与象形文字搏斗。

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

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

在Manjaro上，键入：

相关：如何使用pandoc在Linux命令行上转换文件

手册页的部分

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

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

• Name：命令的名称和描述其功能的简洁的一行代码。
• 概要：对某人可以用来启动程序的调用的简短描述。它们显示了可接受的命令行参数的类型。
• 描述：对命令或功能的描述。
• 选项：命令行选项的列表，以及它们的作用。
• 例句：一些常用的例句。
• 退出值：可能的返回码及其含义。
• bug：已知bug和怪癖的列表。有时，这是补充（或取代）一个链接的问题跟踪的项目。
• 作者：写命令的人。
• 版权：您的版权信息。这些通常还包括程序发布所依据的许可证类型。

如果您浏览一些更复杂的手册页，您将看到还有许多其他部分。例如，试试男人。你不必把它们都包括进去，尽管只是那些你真正需要的。手册页不是罗嗦的地方。

您经常会看到的其他部分包括：

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

手册的章节

Linux手册由所有手册页组成，然后分为以下编号部分：

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

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

手册页的格式

groff宏格式不容易直观地解析。相比之下，降价是轻而易举的事。

下面是groff中的手册页。

下表中显示了相同的页面。

前沿问题

前三条线形成了所谓的前物质。这些都必须以百分号（%）开头，不带前导空格，后面有一个，后跟：

• 第一行：包含命令的名称，后跟括号中的手动部分，不带空格。该名称将成为手册页标题的左侧和右侧部分。按照惯例，命令名是大写的，尽管你会发现很多不是大写的。任何跟在命令名和手动节号后面的都会变成页脚的左边部分。用这个表示软件版本号很方便。
• 第二行：作者姓名。这些将显示在手册页的自动生成的作者部分中。您不必添加“Authors”部分，只需在此处至少包含一个名称。
• 第三行：日期，它也成为页脚的中心部分。

名称

节由以数字符号（#）开头的行表示，这是标记，表示标记中的标题。数字符号（#）必须是行上的第一个字符，后跟空格。

name部分包含一个快捷的单行，其中包括命令的名称、空格、连字符（-）、空格，然后是命令所做的非常简短的描述。

简介

概要包含命令行可以采用的不同格式。此命令可以接受搜索模式或命令行选项。命令名两侧的两个星号（**）表示该名称将在手册页上以粗体显示。某个文本两侧的单个星号（*）将使手册页带下划线显示。

默认情况下，换行符后跟一个空行。要强制不带空行的硬中断，可以使用尾随的反斜杠（\）。

描述

说明说明了命令或程序的作用。它应该简洁地涵盖重要的细节。记住，你不是在写用户指南。

在行首使用两个数字符号（##）创建第二级标题。你可以用这些来把你的描述分成小块。

选项

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

如果描述足够简短，man将在命令行选项的同一行上显示它。如果太长，则显示为缩进段落，从命令行选项下面的行开始。

示例

示例部分包含不同命令行格式的选择。注意，我们用冒号（：）开始描述行，就像我们在opti***部分所做的那样。

退出值

本节列出了命令发送回调用进程的返回值。如果您从命令行调用它，则可能是shell；如果您从shell脚本启动它，则可能是脚本。在本节中，我们也用冒号（：）开始描述行。

漏洞

bug部分列出了人们需要了解的已知bug、问题或怪癖。对于开源项目，通常会在这里包含一个指向项目问题跟踪程序的链接，以检查任何bug的状态或报告新bug。

版权

“版权”部分包含您的版权声明，通常还包含软件发布所依据的许可证类型的说明。

高效的工作流

您可以在最喜爱的编辑器中编辑手册页。大多数支持语法突出显示的人都会意识到标记和颜色的文本突出标题，以及粗体和下划线。这是伟大的，因为它去，但你没有看到一个呈现的手册页，这是真正的证据布丁。

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

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

此命令还调用标记文件上的pandoc（这里称为“ms.1.md”）：

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

我们还使用-l（本地文件）选项将输出输出到man中。它告诉人们不要在人工数据库中搜索手册页。相反，它应该打开命名文件。如果文件名为-，则man将从stdin获取输入。

归根结底，您可以从编辑器中保存，并按Q键关闭man（如果它在终端窗口中运行）。然后，您可以按向上箭头键，然后按Enter键以查看手册页的呈现版本，就在man中。

相关：Linux上的stdin、stdout和stderr是什么？

创建手册页

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

这遵循的惯例是，按照手册页所描述的命令命名手册页，并将手册节号作为文件扩展名附加。

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

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

• /usr/share/man：手册页标准库的位置。我们不向该库添加页面。
• /usr/local/share/man：这个符号链接指向“/usr/local/man”
• /usr/local/man：这是我们需要放置新手册页的地方。

请注意，不同的手册部分包含在各自的目录中：man1、man2、man3等等。如果节的目录不存在，我们需要创建它。

为此，我们键入以下内容：

然后将“ms.1”文件复制到正确的目录：

man希望手册页被压缩，所以我们将使用gzip来压缩它：

要使man将新文件添加到其数据库中，请键入以下内容：

就这样！现在，我们可以通过键入以下命令将新的手册页与其他手册页相同：

找到并显示我们的新手册页。

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

与所描述的选项相邻的描述行显示在同一行上。太长而无法容纳的行显示在它们所描述的选项下面。

我们还自动生成了一个“Authors”部分。页脚还包括前面定义的软件版本号、日期和命令名。

如果你想。

一旦pandoc创建了您的手册页，您还可以直接以groff宏格式编辑该文件，然后将其移动到手册页目录，并对其进行gzip处理。