NAME¶

总览 SYNOPSIS¶

groff -Tps -man file ...

man [section] title

描述 DESCRIPTION¶

注意 NET-2 BSD mdoc 手册页也可以使用 groff 处理，只要指定 -mdoc 选项而不是 -man 选项。推荐使用 -mandoc 选项，因为这样会自动判断应当使用哪一个。

导言 PREAMBLE¶

注意 BSD mdoc 格式的手册页以 Dd 命令开始，而不是 TH 命令

手册章节传统上如下定义：

段 SECTIONS¶

其他约定段的内容应为：

总览 SYNOPSIS

简要描述命令或函数接口。 对命令，显示他的命令和参数（包括各种选项）；黑体表示各种参数， 下划线（或斜体字）表示可以替换的选项； 方括号[]中的是可选项，竖线 | 用于把几个选项间隔开， 小括号()中的部分可以自动重复。 对函数，显示需要的数据声明或需 #include 包含的项目，后跟函数声明。

描述 DESCRIPTION

解释命令、函数或格式的用途。 说明其如何与文件及标准输入交互，他们的标准输出及标准错误。 必须要指明的细节。描述一般情况。 选项和参数信息放在 OPTIONS（选项）段。 如果有语法说明和一些复杂的设定， 建议把它们放到 USAGE（用法）段（本段中最好只写一个概要）。

返回值 RETURN VALUE

列出程序或函数会返回的值，指出引发返回值的条件或原因。

退出状态 EXIT STATUS

列出可能的退出状态的值，指出引起返回的程序或原因。

选项 OPTIONS

指出程序可用的选项，及其作用。

用法 USAGE

描述程序的较高级的使用方法。

示例 EXAMPLES

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

文件 FILES

列出程序或函数使用到的文件， 比如配置文件、启动文件和程序直接操作的文件。 给出文件的绝对路径， 使用安装程序调整这些路径以使其与用户的实际情况相符。 对大多数程序来说，缺省的安装路径是 /usr/local， 所以你的文件要与此一致。

环境 ENVIRONMENT

列出影响你的程序的所有环境变量，并说明影响的原因。

诊断 DIAGNOSTICS

写出常会出现的错误概述，并说明解决的办法。 你无需解释系统错误信息或信号， 除非它们会影响到您的程序。

安全 SECURITY

讨论安全问题和相关话题。对应予避免的配置和环境， 可能有安全隐患的命令等等给出警告， 特别是当它们不是很明显时。 单独用一段来讨论安全并不必要；如果比较好理解的话，把它放在其他段中 （比如 描述 或 用法 段）。但是，最好加上它。

遵循 CONFORMING TO

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

注意 NOTES

提供杂项注意事项

BUGS

列出局限、已知的缺点或不便之处，还有其他可能存在的问题。

作者 AUTHOR

列出程序或文件作者，联系办法等。

参见 SEE ALSO

以字母顺序列出相关的手册页（man pages)。通常来讲，这是一个手册页的最后一段。

字体 FONTS¶

对函数，其参数通常用下划线（或斜体）， 在总览（SYNOPSIS)中也是这样 ，其他部分用黑体。 例如

文件名用下划线（或斜体），例如，.IR "/usr/include/stdio.h" ), 但在总览（SYNOPSIS)中，包含的文件用黑体，例如 #include <stdio.h>).

专用宏，一般大写表示，用黑体（如： MAXINT).

列举错误代号时，代号用黑体（这种列举通常使用 .TP 宏命令）。

对其他手册页的引用（或本页中某主体的引用）用黑体。 手册章节号用普通体（如： man(7)). 设置字体的宏命令如下：

.B

黑体

.BI

黑体和下划线（或斜体）交替（描述函数时非常有用）

.BR

黑体和普通体交替（描述引用时非常有用）

.I

下划线（或斜体）

.IB

下划线（或斜体）和黑体交替

.IR

普通体和下划线（或斜体）交替

.RB

普通体和下划线（或斜体）交替

.RI

小号字和黑体交替

.SB

小号字和黑体交替

.SM

小号字（用于缩写）

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

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

安全子集 SAFE SUBSET¶

你还可能使用 troff 转义字符（这些转移符号以 \ 开始）。 但你要在文本中显示反斜线时，用\e。 其他转义字符包括： \', \`, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, 和 \f(xx. 其中 x、xx 是任意字符，N 是任意数字不要使用转义字符来画图。

不要随意使用 bp （break page(中断页））。 sp （vertical space(垂直距离）只应使用正值。 不要用 (de) （define（定义）定义与现有的宏同名的宏（无论 man 或 mdoc)； 这种重新定义可能会被忽略。 每个正缩进 (in) 应对应一个负缩进（即使在使用 RS 和 RE 是也不例外）。 The condition test (if,ie) should only have 't' or 'n' as the condition. 可以使用的只有可忽略的转换 (tr). 改变字体命令 (ft 和 \f 转义序列) 只能带如下参数： 1, 2, 3, 4, R, I, B, P, or CW (ft 命令也可以不带参数)。

如果你是用更多的功能，用各种程序仔细察看一下结果。 如果你肯定某功能是安全的，请告诉我们，以便把他增加到这个列表中。

注意 NOTES¶

Tools processing these files should open the file and examine the first non-whitespace character. 以(.)或（')开始一行，表明是基于 troff 的文件（如： man 或 mdoc)。 如果是（<）表明基于 SGML/XML (如：HTML 或 Docbook)． 其他可能是纯文本。(例如 "catman" 的结果)

有些 man 以'\"和空格再加字符列开始，表示他的预处理方法。 为了 troff 翻译器程序处理起来简单一些， 您仅应使用 tbl(1), 而不是其他什么东东，Linux 可以检测到这一点。 不过，你或许想要包含这些信息以使其可以在其他系统得到处理。 下面是预处理调用的定义：

e

eqn(1)

g

grap(1)

p

pic(1)

r

refer(1)

t

tbl(1)

v

vgrind(1)

文件 FILES¶

BUGS¶

The Sun macro TX 下不能用。

作者 AUTHOR S¶

—

James Clark (jjc@jclark.com) wrote the implementation of the macro package.

—

Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of this manual page.

—

Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO (which influenced this manual page).

—

David A. Wheeler (dwheeler@ida.org) heavily modified this manual page, such as adding detailed information on sections and macros.

参见 SEE ALSO¶

[中文版维护人]¶

[中文版最新更新]¶

《中国linux论坛man手册翻译计划》:¶

跋¶