Manpages

title 手 册 页 的 标 题

(例 如 ， MAN).

应 当 放 在 这 里 (例 如 ， 7).
date 最 后 修 改 日 期 -- 记 住 要 在 每 次 修 改 过 此 手 册 页 之 后 修 改 它 ，

这 样 可 以 方 便 地 进 行 版 本 控 制

Distribution, MCC Distribution. 对 于 系 统 调 用 ， 使 用 它 适 用 的 内 核 版 本 来 表 述 ： Linux 0.99.11. 对 于 库 调 用 ， 使 用 函 数 的 来 源 来 表 述 ： GNU, BSD 4.3, Linux DLL 4.4.1.

注 意 BSD mdoc 格 式 的 手 册 页 以 Dd 命 令 开 始 ， 而 不 是 TH 命 令 手 册 章 节 传 统 上 如 下 定 义 ：

1 Commands 用 户 可 从 shell 运 行 的 命 令
2 System calls 必 须 由 内 核 完 成 的 功 能
3 Library calls 大 多 数 libc 函 数 ， 例 如 qsort(3))
4 Special files

/dev) 目 录 中 的 文 件

5 File formats and conventions

/etc/passwd 等 人 类 可 读 的 文 件 的 格 式 说 明

7 Macro packages and conventions 文 件 系 统 标 准 描 述 ， 网 络 协 议 ， ASCII 和 其 他 字 符 集 ， 还 有 你 眼 前 这 份 文 档 以 及 其 他 东 西
8 System management commands 类 似 mount(8) 等 命 令 ， 大 部 分 只 能 由 root 执 行
9 Kernel routines 这 是 废 弃 的 章 节 。 原 来 曾 想 把 一 些 关 于 核 心 的 文 件 放 在 这 里 ， 但 是 实 际 上 只 有 极 少 数 可 以 写 成 文 件 放 在 这 里 ， 而 且 它 们 也 很 快 过 时 了 。 核 心 开 发 者 可 以 找 到 其 他 更 好 的 资 源 。

段 SECTIONS

段 以 .SH 开 始 ， 后 跟 标 题 名 。 如 果 标 题 包 含 空 格 并 且 和 .SH 在 同 一 行 ， 则 需 在 标 题 上 加 双 引 号 。 传 统 的 或 建 议 的 标 题 包 括 ： NAME, 总 览 SYNOPSIS, 描 述 DESCRIPTION, 返 回 值 RETURN VALUE, 退 出 状 态 EXIT STATUS, 错 误 处 理 ERROR HANDLING, 错 误 ERRORS, 选 项 OPTIONS, 用 法 USAGE, 示 例 EXAMPLES, 文 件 FILES, 环 境 ENVIRONMENT, 诊 断 DIAGNOSTICS, 安 全 SECURITY, 遵 循 CONFORMING TO, 注 意 NOTES, BUGS, 作 者 AUTHOR, 和 参 见 SEE ALSO. 在 适 合 使 用 约 定 标 题 的 地 方 ， 请 使 用 它 ； 这 样 做 可 以 使 文 章 更 易 读 、 易 懂 。 不 过 ， 只 要 您 的 标 题 能 够 增 加 易 懂 性 ， 请 放 心 使 用 。 唯 一 必 须 的 标 题 是 NAME, 他 应 是 手 册 页 的 第 一 段 ， 后 面 应 紧 跟 对 该 命 令 的 简 单 描 述 。 比 如 ：

.SH NAME
chess \- the game of chess 请 一 定 要 按 照 这 个 格 式 来 写 ， 注 意 在 短 横 线 (dash ’-’) 前 要 有 个 斜 杠 (slash ’´). 这 种 语 法 结 构 在 makewhatis(8) 程 序 为 whatis(1) 和 apropos(1) 命 令 建 立 简 短 命 令 描 述 时 要 用 到 。 其 他 约 定 段 的 内 容 应 为 ：

[]中 的 是 可 选 项 ， 竖 线 | 用 于 把 几 个 选 项 间 隔 开 ， 小 括 号 ()中 的 部 分 可 以 自 动 重 复 。 对 函 数 ， 显 示 需 要 的 数 据 声 明 或 需 #include 包 含 的 项 目 ， 后 跟 函 数 声 明 。 描 述
DESCRIPTION 解 释 命 令 、 函 数 或 格 式 的 用 途 。 说 明 其 如 何 与 文 件 及 标 准 输 入 交 互 ， 他 们 的 标 准 输 出 及 标 准 错 误 。 必 须 要 指 明 的 细 节 。 描 述 一 般 情 况 。 选 项 和 参 数 信 息 放 在 OPTIONS（ 选 项 ） 段 。 如 果 有 语 法 说 明 和 一 些 复 杂 的 设 定 ， 建 议 把 它 们 放 到 USAGE（ 用 法 ） 段 （ 本 段 中 最 好 只 写 一 个 概 要 ） 。 返 回 值
RETURN VALUE 列 出 程 序 或 函 数 会 返 回 的 值 ， 指 出 引 发 返 回 值 的 条 件 或 原 因 。 退 出 状 态
EXIT STATUS 列 出 可 能 的 退 出 状 态 的 值 ， 指 出 引 起 返 回 的 程 序 或 原 因 。

provides one or more examples describing how this function, file or command is used.

/usr/local， 所 以 你 的 文 件 要 与 此 一 致 。 环 境
ENVIRONMENT 列 出 影 响 你 的 程 序 的 所 有 环 境 变 量 ， 并 说 明 影 响 的 原 因 。 诊 断
DIAGNOSTICS 写 出 常 会 出 现 的 错 误 概 述 ， 并 说 明 解 决 的 办 法 。 你 无 需 解 释 系 统 错 误 信 息 或 信 号 ， 除 非 它 们 会 影 响 到 您 的 程 序 。

CONFORMING TO 描 述 它 实 现 的 任 何 标 准 或 约 定

man pages)。 通 常 来 讲 ， 这 是 一 个 手 册 页 的 最 后 一 段 。

字 体 FONTS

虽 然 在 UNIX 世 界 中 有 各 种 对 手 册 页 （ man pages)的 不 同 约 定 ， 但 在 linux 系 统 下 存 在 一 个 字 体 的 标 准 ： 对 函 数 ， 其 参 数 通 常 用 下 划 线 （ 或 斜 体 ） ， 在 总 览 （ SYNOPSIS)中 也 是 这 样 ， 其 他 部 分 用 黑 体 。 例 如

int myfunction(int argc, char **argv); 文 件 名 用 下 划 线 （ 或 斜 体 ） ， 例 如 ， .IR "/usr/include/stdio.h" ), 但 在 总 览 （ SYNOPSIS)中 ， 包 含 的 文 件 用 黑 体 ， 例 如 #include <stdio.h>). 专 用 宏 ， 一 般 大 写 表 示 ， 用 黑 体 （ 如 ： MAXINT). 列 举 错 误 代 号 时 ， 代 号 用 黑 体 （ 这 种 列 举 通 常 使 用 .TP 宏 命 令 ） 。 对 其 他 手 册 页 的 引 用 （ 或 本 页 中 某 主 体 的 引 用 ） 用 黑 体 。 手 册 章 节 号 用 普 通 体 （ 如 ： man(7)). 设 置 字 体 的 宏 命 令 如 下 ：

GNU 去 除 了 这 个 限 制 。 小 节 之 间 以 空 格 隔 开 。 如 果 某 小 节 含 有 空 格 ， 则 需 要 给 其 加 上 双 引 号 。 各 小 节 在 显 示 时 无 间 隔 ， 所 以 .BR 命 令 可 以 指 定 一 个 黑 体 的 词 ， 后 跟 一 个 普 通 体 的 标 点 。 如 果 命 令 后 无 参 数 ， 则 命 令 作 用 于 下 一 行 。

其 他 宏 命 令 和 字 符 串 OTHER MACROS AND STRINGS

下 面 是 其 他 一 些 相 关 的 宏 和 预 定 义 的 字 符 串 。 除 非 指 明 ， 否 则 所 有 的 宏 在 本 行 文 本 结 束 时 终 止 。 多 数 宏 使 用 “流 行 缩 进 ”（ prevailing indent)方 式 。 “流 行 缩 进 ”的 值 由 紧 跟 着 宏 命 令 的 i 值 指 定 ， 如 果 不 指 定 ， 那 就 会 使 用 当 前 的 “流 行 缩 进 ”值 。 这 样 ， 连 续 的 缩 进 段 就 可 使 用 相 同 的 缩 进 值 而 不 需 要 重 新 指 定 。 普 通 段 （ 不 缩 进 ） 将 “流 行 缩 进 ”值 重 值 为 缺 省 值 （ 0.5 英 寸 ） 。 缺 省 时 ， 缩 进 是 有 规 则 的 en(s)： 用 en(s) 或 者 em(s) 作 为 缩 进 的 单 位 ， 因 为 它 们 会 自 动 地 调 整 字 体 的 大 小 。 (注 ： 度 量 距 离 有 不 同 的 单 位 ， 当 请 求 需 要 用 到 不 同 的 距 离 时 ， 可 以 使 用 默 认 类 型 来 修 饰 数 字 ， 度 量 单 位 是 英 寸 ， 厘 米 ， pica,en,em,点 ， unit和 垂 直 行 距 。 1pica等 于 1/6英 寸 ， 1em等 于 字 母 m的 宽 度 ， 默 认 宽 度 取 决 于 troff中 使 用 的 字 体 。 En是 em的 一 半 。 ) 其 他 宏 命 令 定 义 如 下 ： 普 通 段 （ 无 缩 进 ） Normal Paragraphs