.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.
第 11 章 手册页
目录
11.1. 介绍
手册页,通常缩写为man 页,最初是为了方便用户快速查找命令语法、设备驱动程序详细信息或配置文件格式而设计的。它们已成为用户、系统管理员和程序员从命令行进行快速参考的极其宝贵的资源。
尽管手册页旨在作为参考材料而不是教程,但手册页中的“示例”部分通常提供详细的用例。
手册页通常由 man(1) 命令以交互方式显示。当用户键入 man ls
时,会搜索与 ls
匹配的手册页。第一个匹配的结果将显示。
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. 宏
1 | 定义了文档日期和文档标题。 |
2 | 定义了 NAME 节的节标题。然后定义了命令的名称和单行名称描述。 |
3 | SYNOPSIS 节开始。此节描述了接受的命令行选项和参数。 |
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.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
% man ./mynewmanpage.8 | col -b | vim -R -
鼓励使用功能齐全的词典进行拼写检查,可以通过使用 textproc/hunspell 或 textproc/aspell 并结合 textproc/en-hunspell 或 textproc/en-aspell 来实现。例如
% aspell check --lang=en --mode=nroff ./mynewmanpage.8
11.6. 用作模板的手册页示例
一些手册页适合作为深入的示例。
手册页 | 源代码位置路径 |
---|---|
/usr/src/bin/cp/cp.1 | |
/usr/src/share/man/man4/vt.4 | |
/usr/src/usr.sbin/cron/crontab/crontab.5 | |
/usr/src/sbin/geom/class/part/gpart.8 |
上次修改于:2024 年 3 月 9 日,作者 Danilo G. Baio