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">&nbsp;</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日  

《中文 MAN PAGE 计划》:www.cmpp.net/


 

Index

命令名
总览
描述
导言
字体
其他宏命令和字符串
普通段(无缩进)
相对缩进
缩进
超文本链接宏
杂项宏
预定义字符串
安全子集
注意事项
文件
已知漏洞
作者
参见
[中文版维护人]
[中文版最新更新]
《中文 MAN PAGE 计划》:www.cmpp.net/

This document was created by man2html, using the manual pages.
Time: 14:43:06 GMT, April 08, 2001