[贴]中文man手册

本文出自:http://www.cmpp.net 作者: (2001-09-21 09:00:00)

MAN Section: Linux linux 程序员手册 (7) Updated: 16 June 1999   命令名 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/