第 11 章 手册页

11.1. 介绍

手册页,通常缩写为man 页,最初是为了方便用户快速查找命令语法、设备驱动程序详细信息或配置文件格式而设计的。它们已成为用户、系统管理员和程序员从命令行进行快速参考的极其宝贵的资源。

尽管手册页旨在作为参考材料而不是教程,但手册页中的“示例”部分通常提供详细的用例。

手册页通常由 man(1) 命令以交互方式显示。当用户键入 man ls 时,会搜索与 ls 匹配的手册页。第一个匹配的结果将显示。

11.2. 节

手册页被分组到中。每个节包含特定类别文档的手册页

节号类别

1

通用命令

2

系统调用

3

库函数

4

内核接口

5

文件格式

6

游戏

7

其他

8

系统管理员

9

内核开发者

11.3. 标记

手册页已使用各种标记形式和渲染程序。FreeBSD 已使用 groff(7) 和更新的 mandoc(1)。大多数现有的 FreeBSD 手册页以及所有新的手册页都使用 mdoc(7) 标记形式。这是一种简单的基于行的标记,具有相当强的表达能力。它主要语义化:文本的各个部分根据其内容进行标记,而不是根据渲染时应如何显示进行标记。有一些基于外观的标记,通常最好避免使用。

手册页源代码通常会进行解释并以交互方式显示在屏幕上。源文件可以是普通文本文件,也可以使用 gzip(1) 进行压缩以节省空间。

手册页还可以渲染成其他格式,包括用于打印的 PostScript 或 PDF 生成。请参阅 man(1)

11.3.1. 手册页节

手册页由几个标准节组成。每个节都有一个大写的标题,并且特定类型手册页的节按特定顺序出现。对于类别 1 通用命令手册页,节的顺序如下:

节名称描述

NAME

命令名称

SYNOPSIS

选项和参数的格式

DESCRIPTION

目的和用法的描述

ENVIRONMENT

影响操作的环境设置

EXIT STATUS

退出时返回的错误代码

EXAMPLES

使用示例

COMPATIBILITY

与其他实现的兼容性

SEE ALSO

与相关手册页的交叉引用

STANDARDS

与 POSIX 等标准的兼容性

HISTORY

实现的历史

BUGS

已知错误

AUTHORS

创建命令或编写手册页的人员。

某些节是可选的,特定类型手册页的节组合也各不相同。本章后面将显示最常见类型的示例。

11.3.2. 宏

mdoc(7) 标记基于。以点开头的行包含宏命令,每个命令由两个或三个字母组成。例如,考虑 ls(1) 手册页的这部分内容

.Dd December 1, 2015  (1)
.Dt LS 1
.Sh NAME  (2)
.Nm ls
.Nd list directory contents
.Sh SYNOPSIS  (3)
.Nm  (4)
.Op Fl -libxo  (5)
.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,  (6)
.Op Fl D Ar format  (7)
.Op Ar  (8)
.Sh DESCRIPTION  (9)
For each operand that names a
.Ar file
of a type other than
directory,
.Nm
displays its name as well as any requested,
associated information.
For each operand that names a
.Ar file
of type directory,
.Nm
displays the names of files contained
within that directory, as well as any requested, associated
information.
1定义了文档日期文档标题
2定义了 NAME 节的节标题。然后定义了命令的名称和单行名称描述
3SYNOPSIS 节开始。此节描述了接受的命令行选项和参数。
4名称 (.Nm) 已经定义,这里重复它只是在文本中显示定义的值。
5显示了一个名为 -libxo可选标志Fl 宏在标志的开头添加一个破折号,因此在手册页中显示为 --libxo
6显示了一长串可选的单字符标志。
7定义了一个可选的 -D 标志。如果给出 -D 标志,则后面必须跟一个参数。该参数是一个格式,一个字符串,告诉 ls(1) 显示什么以及如何显示。格式字符串的详细信息在手册页的后面部分给出。
8定义了最终的可选参数。由于未为参数指定名称,因此使用默认值 file …​
9定义了 DESCRIPTION 节的节标题

使用命令 man ls 渲染时,在屏幕上显示的结果如下所示

LS(1)                   FreeBSD General Commands Manual                  LS(1)

NAME
     ls - list directory contents

SYNOPSIS
     ls [--libxo] [-ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1,] [-D format]
        [file ...]

DESCRIPTION
     For each operand that names a file of a type other than directory, ls
     displays its name as well as any requested, associated information.  For
     each operand that names a file of type directory, ls displays the names
     of files contained within that directory, as well as any requested,
     associated information.

可选值显示在方括号内。

11.3.3. 标记指南

mdoc(7) 标记语言并不严格。为了清晰和一致性,FreeBSD 文档项目添加了一些额外的样式指南。

只有宏的第一个字母大写

始终使用大写作为宏的第一个字母,其余字母使用小写。

在新行开始新句子

在新行开始一个新句子,不要在同一行上与现有句子一起开始。

在对手册页进行非微不足道的更改时更新 .Dd

“文档日期”告知读者手册页上次更新的时间。在对手册页进行非微不足道的更改时,更新它非常重要。诸如拼写或标点符号修复之类的微不足道的更改不会影响使用,无需更新 .Dd

提供示例

尽可能向读者展示示例。即使是简单的示例也很有价值,因为对作者来说微不足道的,对读者来说不一定微不足道。三个示例是一个好的目标。一个简单的示例显示了最低要求,一个严肃的示例显示了实际用法,而一个深入的示例演示了不寻常或不明显的特性。

包含 BSD 许可证

在新手册页上包含 BSD 许可证。首选许可证可在 贡献者指南 中找到。

11.3.4. 标记技巧

在包含宏的行上的标点符号前添加空格。示例

.Sh SEE ALSO
.Xr geom 4 ,
.Xr boot0cfg 8 ,
.Xr geom 8 ,
.Xr gptboot 8

请注意,.Xr 行末尾的逗号已放置在空格之后。.Xr 宏期望后面跟着两个参数,外部手册页的名称和节号。空格将标点符号与节号分隔开。如果没有空格,外部链接将错误地指向节 4,8,

11.3.5. 重要的宏

此处将显示一些非常常见的宏。有关更多使用示例,请参阅 mdoc(7)groff_mdoc(7),或在 /usr/share/man/man* 目录中搜索实际用法。例如,要搜索 .Bd 开始显示 宏的示例

% find /usr/share/man/man* | xargs zgrep '.Bd'

11.3.5.1. 组织宏

一些宏用于定义手册页的逻辑块。

组织宏使用

.Sh

节标题。后跟节的名称,传统上全部大写。可以将其视为章节标题。

.Ss

小节标题。后跟小节的名称。用于将 .Sh 节分成小节。

.Bl

开始列表。开始项目列表。

.El

结束列表。

.Bd

开始显示。开始一个特殊的文本区域,例如缩进区域。

.Ed

结束显示。

11.3.5.2. 内联宏

许多宏用于标记内联文本。

内联宏使用

.Nm

名称。在第一次使用时使用名称作为参数调用,然后在以后不使用参数即可显示已定义的名称。

.Pa

文件路径。用于标记文件名和目录路径。

11.4. 手册页示例结构

本节显示了几个常见类别的手册页的最小所需内容。

11.4.1. 第 1 或 8 节命令

第 1 或 8 节命令的首选基本结构

.Dd August 25, 2017
.Dt EXAMPLECMD 8
.Os
.Sh NAME
.Nm examplecmd
.Nd "command to demonstrate section 1 and 8 man pages"
.Sh SYNOPSIS
.Nm
.Op Fl v
.Sh DESCRIPTION
The
.Nm
utility does nothing except demonstrate a trivial but complete
manual page for a section 1 or 8 command.
.Sh SEE ALSO
.Xr exampleconf 5
.Sh AUTHORS
.An Firstname Lastname Aq Mt [email protected]

11.4.2. 第 4 节设备驱动程序

第 4 节设备驱动程序的首选基本结构

.Dd August 25, 2017
.Dt EXAMPLEDRIVER 4
.Os
.Sh NAME
.Nm exampledriver
.Nd "driver to demonstrate section 4 man pages"
.Sh SYNOPSIS
To compile this driver into the kernel, add this line to the
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device exampledriver"
.Ed
.Pp
To load the driver as a module at boot, add this line to
.Xr loader.conf 5 :
.Bd -literal -offset indent
exampledriver_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
driver provides an opportunity to show a skeleton or template
file for section 4 manual pages.
.Sh HARDWARE
The
.Nm
driver supports these cards from the aptly-named Nonexistent
Technologies:
.Pp
.Bl -bullet -compact
.It
NT X149.2 (single and dual port)
.It
NT X149.8 (single port)
.El
.Sh DIAGNOSTICS
.Bl -diag
.It "flashing green light"
Something bad happened.
.It "flashing red light"
Something really bad happened.
.It "solid black light"
Power cord is unplugged.
.El
.Sh SEE ALSO
.Xr example 8
.Sh HISTORY
The
.Nm
device driver first appeared in
.Fx 49.2 .
.Sh AUTHORS
.An Firstname Lastname Aq Mt [email protected]

11.4.3. 第 5 节配置文件

第 5 节配置文件的首选基本结构

.Dd August 25, 2017
.Dt EXAMPLECONF 5
.Os
.Sh NAME
.Nm example.conf
.Nd "config file to demonstrate section 5 man pages"
.Sh DESCRIPTION
.Nm
is an example configuration file.
.Sh SEE ALSO
.Xr example 8
.Sh AUTHORS
.An Firstname Lastname Aq Mt [email protected]

11.5. 测试

测试新的手册页可能具有挑战性。幸运的是,有一些工具可以帮助完成此任务。其中一些,例如 man(1),不会查看当前目录。如果新的手册页位于当前目录中,最好在文件名之前加上 ./。也可以使用绝对路径。

使用 mandoc(1) 的 linter 检查解析错误

% mandoc -T lint ./mynewmanpage.8

使用 textproc/igor 校对手册页

% igor ./mynewmanpage.8

另一个有用的工具是 textproc/vale。它不支持 mdoc(7) 语法,但可以从标准输入读取渲染后的手册页

% man ls | vale

textproc/vale 是高度可配置的。建议阅读其文档。

使用 man(1) 检查更改的最终结果

% man ./mynewmanpage.8

您可以使用 col(1) 过滤 man(1) 的输出并去除退格符,然后在您喜欢的编辑器中加载结果以进行拼写检查

% man ./mynewmanpage.8 | col -b | vim -R -

鼓励使用功能齐全的词典进行拼写检查,可以通过使用 textproc/hunspelltextproc/aspell 并结合 textproc/en-hunspelltextproc/en-aspell 来实现。例如

% aspell check --lang=en --mode=nroff ./mynewmanpage.8

11.6. 用作模板的手册页示例

一些手册页适合作为深入的示例。

手册页源代码位置路径

cp(1)

/usr/src/bin/cp/cp.1

vt(4)

/usr/src/share/man/man4/vt.4

crontab(5)

/usr/src/usr.sbin/cron/crontab/crontab.5

gpart(8)

/usr/src/sbin/geom/class/part/gpart.8


上次修改于:2024 年 3 月 9 日,作者 Danilo G. Baio