手册页

手册页是随软件安装的参考文档。章节编号用于区分主题：第 1 节记录用户命令， 第 2 节记录系统调用，第 3 节记录库函数，第 4 节记录设备和特殊文件， 第 5 节记录文件格式和约定，第 7 节记录概览和协议，第 8 节记录管理命令。 带章节号的查询可以选择预期页面：

man 2 open
man 3 printf
man 5 passwd

章节、名称和概要 #

应同时根据名称和章节选择页面，因为同一个名称可能表示命令、函数或文件。 页面源文件和安装后的文件名通常使用 name.section 形式，例如 printf.1 和 printf.3。 NAME 节提供 name \- 单行描述；apropos 等工具会索引该行。 SYNOPSIS 节对命令使用命令行表示法，对 API 使用声明表示法。

约定的章节包括 NAME、SYNOPSIS、DESCRIPTION、OPTIONS 或 PARAMETERS、 RETURN VALUE、ERRORS、ENVIRONMENT、FILES、ATTRIBUTES、STANDARDS、 HISTORY 或 VERSIONS、EXAMPLES、NOTES、BUGS、SEE ALSO 和 AUTHORS。 只包含适用章节，但应记录可观察的失败和兼容性边界，而不是将其隐含。 Linux API 页面使用 ATTRIBUTES 记录线程安全性等属性。

使用 roff 编写 #

手册页使用 roff 输入，可以采用语义化的 mdoc 宏包或 man 宏包。 mandoc(1) 能解析、验证并渲染两种格式。mdoc 词汇记录函数名、选项、参数和交叉引用等语义结构， 从而能够一致地生成终端、HTML 和 PostScript 输出。

最小的 mdoc 文档会标识名称、概要、描述、选项、退出状态和参考资料：

.Dd August 7, 2026
.Dt EXAMPLE 1
.Os
.Sh NAME
.Nm example
.Nd print an example message
.Sh SYNOPSIS
.Nm
.Op Fl q
.Sh DESCRIPTION
The .Nm utility writes a message to standard output.

在 roff 输入行开头，. 和 ' 引入请求；使用 \& 转义字面量开头的控制字符。 将字面量反斜杠写成 \(rs，或使用宏包文档规定的转义方式；命令选项中使用 \- 表示语义上的减号。 相较于改变字体，应优先使用 mdoc 的 .Fl、.Ar、.Fn 和 .Xr 等语义宏， 因为渲染器可以在不同输出格式中保留其含义。

交叉引用同时标识名称和章节，例如 mdoc 中的 .Xr open 2 或 man 标记中的 open(2)。 SEE ALSO 列表应引用定义相关行为的命令、API、配置文件或规范。

检查和渲染 #

使用 mandoc -T lint file.1 检测结构问题，使用 mandoc -T utf8 file.1 检查终端输出。 使用 GNU roff 时，groff -man -Tutf8 file.1 或 groff -mdoc -Tutf8 file.1 会渲染相应的宏语言。即使项目从源元数据生成页面，也需要经过检查的渲染路径， 因为生成的输入可能违反宏语法或转义规则。

Linux man-pages 项目记录 Linux 内核用户空间 ABI 以及许多 libc 接口。 各个软件包负责其命令和文件格式的文档。应从负责的上游源记录标准、最早适用版本、 差异、错误条件和线程安全属性，而不是从单台机器推断这些信息。