Content-type: text/html
Manpage of MAN
MAN
Section: Linux linux 程序员手册
(7)
Updated: 16 June 1999
Index
Return to Main Contents
命令名
man - 格式化显示 man pages
总览
groff -Tascii -man
file
...
groff -Tps -man
file
...
man
[section]
title
描述
本手册页对 groff tamc.an 宏命令包以及创建包含这些宏命令的手册页
(man pages)的有关约定作一些说明。
本手册用于帮助开发人员创建或发布 linux 手册页(linux man pages)。
本手册与其他版本的兼容性良好,
所以发布不会是个问题
(除非包含 net-2 BSD 版本,它使用完全不同的宏命令包(叫做 mdoc),
您可以察看 mdoc(7) 获取更详细的说明)。
不过使用 man -mdoc xxxx 也可以察看 mdoc 格式的文件。
而且我们推荐您使用该参数,因为他会自动检查文件所使用的宏命令的类别。
导言
手册页中的第一个命令一般是:
其中:
-
- 标题
-
手册页的标题(通常与命令名相同)(比如: MAN)。
- 章节号
-
手册页的章节号(比如: 7 )
- 日期
-
最后更新日期 -- 要记得每次更新后都把日期改为最新,
这也是进行版本控制 的好方法。
- 资源 ???
-
(MISSING SOME PARTS)
手册名 手册名(比如: Linux Programmer's Manual(Linux 程序员手册))。
注意 BSD mdoc 格式的页以 Dd 命令开始,而不是 .TH 命令。
手册的各章节内容通常如下规定:
(一个手册可以有好几节,比如 man(1)、man(7)等,
可分别用 man 1 man 、 man 7 man来察看。)
-
- 1 命令
-
命令的使用方法,可以使用的参数等。
- 2 系统调用
-
只有系统才能执行的函数
- 3 库调用
-
大多是 libc 函数,如 qsort(3)
- 4 特殊文件
-
文件在
/dev
中。
- 文件的格式,比如
-
/etc/passwd
及其他可读文件。
- 6 游戏
-
- 7 宏命令包和约定
-
一些描述,关于标准文件系统设计、网络协议,ASCII 和 其他字符编码、man page
(手册页)和其他。
- 8 系统管理命令
-
诸如 mount(8) 之类的命令,多数只有 root 可以执行。
- 9 内核程序
-
这个章节几乎不用了。
原来曾想把一些关于核心的文件放在这里,
但是实际上只有极少数可以写成文件放在这里,而且它们也很快过时了。
核心开发者可以找到其他更好的资源。
段
段以 .SH 开始,后跟标题。
如果标题包含空格并且和 .SH 在同一行,则需在标题上加双引号。
约定(推荐使用)的标题包括:
NAME(命令名),SYNOPSIS(总览),DESCRIPTION(描述),
RETURN VALUE (or RETURN VALUES)(返回值),
EXIT STATUS(退出状态),ERROR HANDLING(错误处理),
ERRORS(错误),OPTIONS(选项),
USAGE(用法),FILES(文件),ENVIRONMENT(环境),
DIAGNOSTICS(诊断),SECURITY(安全),
CONFORMING TO(遵循),NOTES(注意事项),BUGS(已知漏洞),
AUTHOR(作者),和 SEE ALSO(参见).
在适合使用约定标题的地方,请使用他;
这样做可以使文章更易读、易懂。
不过,只要您的标题能够增加易懂性,请放心使用。
唯一必须的标题是 NAME(命令名),他应是手册页的第一段,
后面应紧跟对该命令的简单描述。比如:
.SH NAME 命令名 chess - the game of chess
请一定要按照这个格式来写,注意在短横线(-)前要有个斜杠()。
这种语法结构在 makewhatis(8)程序中为
whatis(1) 和 apropos(1) 建立简短命令描述时要用到。
其他约定段的内容应为:
- 总览
-
简要描述命令或函数接口。
对命令,显示他的命令和参数(包括各种选项);黑体表示各种参数,
下划线(或斜体字)表示可以替换的选项;
方括号[]中的是可选项,竖线 | 用于把几个选项间隔开,
小括号()中的部分可以自动重复。
对函数,显示需要的数据声明或需包含的项目,后跟函数声明。
- 描述
-
解释命令、函数或格式的用途。
说明其如何与文件及标准输入交互,他们的标准输出及标准错误。
必须要指明的细节。描述一般情况。
选项和参数信息放在 OPTIONS(参数)段。
如果有语法说明和一些复杂的设定,
建议把它们放到 USAGE(用法)段(本段中可写一个概要)。
- 返回值
-
列出程序或函数会返回的值,指出引发返回值的条件或原因。
- 退出状态
-
列出可能的退出状态的值,指出引起返回的程序或原因(可以与“返回值”段合并)。
- 参数
-
指出程序可用的参数,及其作用。
- 用法
-
描述程序的较高级的使用方法。
- 文件
-
列出程序或函数使用到的文件,
比如配置文件、启动文件和程序直接操作的文件。
给出文件的绝对路径,
使用安装程序调整这些路径以使其与用户的实际情况相符。
对大多数程序来说,缺省的安装路径是 /usr/local,
所以你的文件要与此一致。
- 环境
-
列出影响你的程序的所有环境变量,并说明影响的原因。
- 诊断
-
写出常会出现的错误概述,并说明解决的办法。
你无需解释系统错误信息或信号,
除非它们会影响到您的程序。
- 安全
-
讨论安全问题和相关话题。对应予避免的配置和环境,
可能有安全隐患的命令等等给出警告,
特别是当它们不是很明显时。
单独用一段来讨论安全并不必要;如果比较好理解的话,把它放在其他段中
(比如 描述 或 用法 段)。但是,不能不写。
- 约定
-
描述该程序的标准和约定(或是习惯用法)。
- 已知漏洞
-
列出局限、已知的缺点或不便之处,还有其他可能存在的问题。
- 作者
-
列出程序或文件作者,联系办法等。
- 参见
-
以字母顺序列出相关的手册页(man pages)。通常来讲,这是一个手册页的最后一段。
字体
虽然在 UNIX 世界中有各种对手册页(man pages)的不同约定,
但在 linux 系统下存在一个字体的标准:
对函数,其参数通常用下划线(或斜体),
在总览(SYNOPSIS)中也是这样,其他部分用黑体。
文件名用下划线(或斜体),但在总览(SYNOPSIS)中不是,
包含的文件用黑体(如: #include )。
专用宏,一般大写表示,用黑体(如: MAXINT)。
列举错误代号时,代号用黑体(这种列举通常使用 .TP 宏命令)。
对其他手册页的引用(或本页中某主体的引用)用黑体。
手册章节号用普通体(如: man(7)).
设置字体的宏命令如下:
- .B
-
黑体
.BI
黑体和下划线(或斜体)交替(描述函数时非常有用)
.BR
黑体和普通体交替(描述引用时非常有用)
.I
下划线(或斜体)
.IB
下划线(或斜体)和黑体交替
.IR
下划线(或斜体)和普通体交替
.RI
普通体和下划线(或斜体)交替
.SB
小号字和黑体交替
.SM
小号字(用于缩写)
按照惯例,每个命令最多可以有六个小节的参数,
但是 GNU 去除了这个限制。小节之间以空格隔开。
如果某小节含有空格,则需要给其加上双引号。
各小节在显示时无间隔,所以 .BR 命令可以指定一个黑体的词,
后跟一个普通体的标点。如果命令后无参数,则命令作用于下一行。
其他宏命令和字符串
下面是其他一些相关的宏和预定义的字符串。
除非指明,否则所有的宏在本行文本结束时终止。
多数宏使用“流行缩进”(prevailing indent)方式。
“流行缩进”的值由紧跟着宏命令的 i 值指定,
如果不指定,那就会使用当前的“流行缩进”值。
这样,连续的缩进段就可使用相同的缩进值而不需要重新指定。
普通段(不缩进)将“流行缩进”值重值为缺省值(0.5 英寸)。
缺省时,缩进是有规则的 en(s):用 en(s) 或者 em(s) 作为缩进的单位,
因为它们会自动地调整字体的大小。
(注:度量距离有不同的单位,当请求需要用到不同的距离时,可以使用默认
类型来修饰数字,度量单位是英寸,厘米,pica,en,em,点,unit和垂直行距。
1pica等于1/6英寸,1em等于字母m的宽度,默认宽度取决于troff中使用
的字体。En是em的一半。)
其他宏命令定义如下:
普通段(无缩进)
- .LP
-
与
.PP
相同(开始一个新段)
.P
同上
.PP
开始一个新段,重置“流行缩进”值。
相对缩进
-
-
开始相对缩进 -- 把左边界右移 i (如果不指定 i 值,则使用“流行缩进”值 )。
同时设定“流行缩进”值为 0.5 英寸。
直到使用
.RE结束这些设定。
- .RE
-
结束相对缩进同时把“流行缩进”恢复原值。
缩进
- .HP i
-
开始悬挂式缩进(段的第一行从左边揭开时,其余缩进显示)
- .IP x i
-
在段上标签 x 。如果不指定 x ,则整个段缩进 i。
如果指定了 x ,则 x 之前的段不缩进,
之后的段缩进(有些象 .TP,不过 x 是跟在命令后面而不是在下一行)。
如果 x 太长,后面的文本会挪到下一行
(文本不会丢 失或割断)。
做公告列表,可以用
.IP * (bullet) 或 .IP --- (em dash) 要用数字或字母列表
时,可以用 .IP 1. 或 .IP A. ,他们会转换成其他 格式。
- .TP i
-
在段上悬挂标签。标签在下一行指定,但是结果和 .IP 相像。
超文本链接宏
- .UR u
-
建立一个超文本链接到 URI(URL)
u;
并以
UE
结束。当转换为 HTML 格式时,他会转换为 <A HREF="u">。
有个例外:如果 u 是“ :”,则之后不能建立任何超级链接,
直到以 UE 结束(这用来在不需要超级链接时禁止他)。
这个宏比较新,很多程序可能并不对他进行处理。
<A NAME="u" id="u"> </A>
杂项宏
- .DT
-
重置 tab 值为缺省(每一个0.5英寸)。不引起中断。
- .IX ...
-
插入索引信息(方便搜索系统工作,或打印索引列表)。
在页中索引信息不能正常显示。
如果只有一个参数,
参数作为独立的索引项指向手册页的内容。
如果有两个参数,他可能是 Perl 手册页格式;
第一个参数指定类型名
(命令名,标题 ,题头,子段货源素之一),
第二个参数指明自己的索引名。
另外,长索引形式:每个参数是一个索引项,
次级索引项,再次级索引项,等等直到以空参数结束,
然后是程序名参数,\m,还有一小段描述。
还可能在跟上一个空参数,有可能是页控制信息
(如: PAGE START)。举例如下:
"programmingtools""make""""make--- build programs".
- .PD d
-
在段中间垂直距离空开 d (如果不指定,则缺省为 d=0.4v),不引起中断。
- .SS t
-
子标题 t (象是
.SH,
但是作为段中的字标题使用)
预定义字符串
- \*R
-
注册符号
- \*S
-
改变成缺省字体大小
- \*(Tm
-
商标符号
- \*(lq
-
左双引号
- \*(rg
-
右双引号
安全子集
理论上 man 是一个 troff 宏命令包,
实际上很多工具程序没有支持所有的 man 宏命令。
因此,为了这些程序可以正常工作最好忽略 troff 的一些比较另类的宏。
避免使用各种不同的 troff 预处理程序
(如果必须的话,用 tbl(1)吧
但是在建立双列表时请使用 IP 和 TP 命令)。
避免使用计算;大多数其他程序不能处理他。
使用简单的命令比较容易转换为其他格式。
下面的宏命令一般认为是安全的(虽然多数时候他们都被忽略了):
\", . , ad , bp , br , ce ,
de, ds, el , ie , if , fi ,
ft, hy, ig , in , na , ne ,
nf, nh, ps , so , sp , tr .
你还可能使用 troff 转义字符(这些转移符号以 \ 开始)。
但你要在文本中显示反斜线时,用\。
其他转义字符包括:
\' ,\` ,\- ,\. ,\" ,\% ,\*x ,\*(xx ,
\(xx ,\$N ,\nx,
\n(xx ,\fx,\f(xx。
其中 x、xx 是任意字符,N 是任意数字不要使用转义字符来画图。
不要随意使用 bp(break page(中断页))。
sp(vertical space(垂直距离)只应使用正值。
不要用(de(define(定义)))定义与现有的宏同名的宏(无论 man 或 mdoc);
这种重新定义可能会被忽略。
每个正缩进应对应一个负缩进(即使在使用 RS 和 RE 是也不例外)。
可以使用的只有可忽略的转换(tr).
改变字体命令(ft 和 \f)只能带如下参数:
1,2,3,4,R,I,B,P,CW
(ft 命令也可以不带参数)。
如果你是用更多的功能,用各种程序仔细察看一下结果。
如果你肯定某功能是安全的,请告诉我们,以便把他增加到这个列表中。
注意事项
尽量在文本中包含完整的 URL(或URIs);
一些工具软件(如:man2html(1))能够自动把它们转换为超级链接。
您也可用 UR 命令指定链接到相关信息。
输入完整的 URL(如: )。 以(.)或(')开始一行,
表明是基于 troff 的文件(如: man 或 mdoc)。
如果是(<)表明基于 SGML/XML (如:HTML 或 Docbook).
其他可能是纯文本。
有些 man 以'\"和空格再加字符列开始,表示他的预处理方法。
为了 troff 翻译器程序处理起来简单一些,
您仅应使用 tbl(1) 而不是其他什么东东,Linux 可以检测到这一点。
不过,你或许想要包含这些信息以使其可以在其他系统得到处理。
下面是预处理调用的定义:
e eqn(1) g grap(1) p pic(1) r refer(1) t tbl(1) v vgrind(1)
文件
/usr/local/lib/groff/tmac/tmac.an
/usr/man/whatis
已知漏洞
大多数宏命令描述的是格式(比如:字体和空格)而不是内容描述
(比如: 这段文字指向另外一页),
与 mdoc 和 DocBook 正好相反(HTML 也有比较多的内容描述)。
这使得 man 难以转换为其他形式,
不容易与其他文件组合或自动插入交叉引用。
遵照以上的安全说明,就比较容易在将来把他转换为其他格式。
Sun 的 macro TX 下不能用。
作者
- ---
-
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.
参见
apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), whatis(1).
[中文版维护人]
姓名:RedCandle E-mail:redcandle51@chinaren.com
[中文版最新更新]
2000年11月06日
Index
- 命令名
-
- 总览
-
- 描述
-
- 导言
-
- 段
-
- 字体
-
- 其他宏命令和字符串
-
- 普通段(无缩进)
-
- 相对缩进
-
- 缩进
-
- 超文本链接宏
-
- 杂项宏
-
- 预定义字符串
-
- 安全子集
-
- 注意事项
-
- 文件
-
- 已知漏洞
-
- 作者
-
- 参见
-
- [中文版维护人]
-
- [中文版最新更新]
-
- 《中文 MAN PAGE 计划》:www.cmpp.net/
-
This document was created by
man2html,
using the manual pages.
Time: 14:43:06 GMT, April 08, 2001