man-page.html

Linux初学者最好的老师就是howto了。相当于函数man。

    作用。同时这个段有个标准化的格式：一连串用逗号隔开的程序或函数名，后面
    跟个破折号，接著是简短（通常只有一行）的说明，介绍该程序（函数、文件）
    应该提供的功能。通过makewhatis(8)，名称段的内容将收集到whatis数据库文件
    中。名称段必须要有而且必须遵循以上格式的理由正是这个makewhatis程序。在
    groff源文件里它看起来一定要象这样子：

   .SH NAME foo \- frobnicate the bar library

   这里\-很重要，其中的反斜线是不可或缺的，它的作用是将后面的破折号同可能在
   命令名称中和该单行描述中用到的其它连字号区分开来。

   _SYNOPSIS（大纲）段_

   ……这一段用以给出可用的程序选项的概览。对于函数来说这个段列出相应的包含
   文件和原型，相应的包含文件和原型，以便程序员知道参数和返回值的类型和个数。

   _DESCRIPTION（描述）段_
   ……你要在这里无可辩驳地证明你的0和1的序列是有点价值的。这里是写下你所有
   知识的地方。它是个名人堂。通过提供详尽和可信的第一手资料，你能赢得其他程
   序员和用户的赞美。要解释参数的用途、文件的格式，以及你完成这件复杂工作所
   用的算法。

   _OPTIONS（选项）段_
   ……给出每个选项如何影响你程序行为的描述。你是知道那是怎么一回事的，是不
   是？

   _FILES（文件）段_

   ……列出程序或函数用到的文件。例如，配置文件、启动文件、程序直接操作的文
   件等。最好给出这些文件的完整路径名，并使安装程序可以改变这个目录，以便让
   用户可以自己选定参数：groff的手册有一个缺省的目录前缀/usr/local，因此缺
   省情况下要访问到/usr/local/lib/groff/* 这些文件 。 然而 ， 如果你使用命令
   “make prefix=/opt/gnu” 进行 安装 ， 那么 手册页 的 存放 地点 将 改为
   /opt/gnu/lib/groff/*。

   _ENVIRONMENT（环境）段_

   ……列出所有对你的程序或函数有影响环境变量，当然还要说明是如何影响的。最
   常见的环境变量是些路径名、文件名或缺省设置等等。

   _DIAGNOSTICS（诊断）段_

   ……应当概略地说明来自你的程序的最常见的错误信息，并指出应当如何处理。不
   必解释系统错误信息（在perror(3)中列出的）或致命错误信号（在psignal(3)中
   列出），因为它们在运行任何程序的过程中都会发生。

   _BUGS（臭虫）段_

   ……理想状态下应该没有这段。如果你有勇气，你可以在这里描述你的系统局限性、
   已知的麻烦之处、某些人会认为是缺陷的特性等。如果你胆子小，将它改名为“应
   该如此”段 ;-)

   _AUTHOR（作者）段_

   ……当你的文档或程序行为（哎呀！）有很多错误并且你想要别人的臭虫报告电邮
   的时候，写上这个节是个好办法。

   _SEE ALSO（参见）节_
 
   这是按照字母顺序给出的相关手册页的列表。
 
   按照惯例，这个是最后一个节。如果这些节都不能满足你，你可以自由地另外发明
   一些节（译者注：这意味著，除了NAME段不能改名字外，你可以将其它所有的段名
   都改成中文。）。那么如何正确地生成该手册页呢？我早就知道你会这样问了，这
   里就是源文件，看吧：

.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH FOO 1 "MARCH 1995" Linux "User Manuals"
.SH NAME
foo \- frobnicate the bar library
.SH SYNOPSIS
.B foo [-bar] [-c
.I config-file
.B ]
.I file
.B ...
.SH DESCRIPTION
.B foo
frobnicates the bar library by tweaking internal
symbol tables. By default it parses all baz segments
and rearranges them in reverse order by time for the
.BR xyzzy (1)
linker to find them. The symdef entry is then compressed
using the WBG (Whiz-Bang-Gizmo) algorithm.
All files are processed in the order specified.
.SH OPTIONS
.IP -b
Do not write `busy' to stdout while processing.
.IP "-c config-file"
Use the alternate system wide
.I config-file
instead of
.IR /etc/foo.conf .
This overrides any
.B FOOCONF
environment variable.
.IP -a
In addition to the baz segments, also parse the
blurfl headers.
.IP -r
Recursive mode. Operates as fast as lightning
at the expense of a megabyte of virtual memory.
.SH FILES
.I /etc/foo.conf
.RS
The system wide configuration file. See
.BR foo (5)
for further details.
.RE
.I ~/.foorc
.RS
Per user configuration file. See
.BR foo (5)
for further details.
.SH ENVIRONMENT
.IP FOOCONF
If non-null the full pathname for an alternate system wide
.IR foo.conf .
Overridden by the
.B -c
option.
.SH DIAGNOSTICS
The following diagnostics may be issued on stderr:

Bad magic number.
.RS
The input file does not look like an archive file.
.RE
Old style baz segments.
.RS
.B foo
can only handle new style baz segments. COBOL
object libraries are not supported in this version.
.SH BUGS
The command name should have been chosen more carefully
to reflect its purpose.
.SH AUTHOR
Jens Schweikhardt <[e-mail]>
.SH "SEE ALSO"
.BR bar (1),
.BR foo (5),
.BR xyzzy (1)

   _3）我如何在一个手册页里替几个程序/函数编写文档？_

   很多程序（grep、egrep等）和函数（printf、fprintf等）的文档都在同一个手册
   页里。然而，如果这些手册页只能通过同一个名字访问的话就会变得一点用处都没
   有。我们不能指望用户会记得egrep的手册页正好就是grep的手册页。因此有必要
   使同一个手册页可以通过不同的名字访问。为此目的我们有几种可行的方法：
    1． 为每个名字弄一个手册页的拷贝。
    2． 用硬连接把所有手册页连到同一个文件。
    3． 使用符号连接指向世纪的手册页。
    4． 使用groff通过“.so”提供的“源”机制。

   第一种方法明显地是在浪费磁盘空间。第二种方法我们不建议使用，理由是catman
   的智能版本可以通过查看文件类型和内容节省很多工作。硬连接将妨碍catman变得
   聪明。（catman的作用是将所有的手册页格式化以便加快显示速度。）第三种方法
   有点小缺点：如果关心的是可移植性，你要注意到有些文件系统不能支持符号连接。
   分析的结果，最佳方案（商标）就是使用groff的源机制。做法如下：如果你打算
   让你的手册页可以用领域1中的名称“foo”和“bar”访问 ， 那么将手册页做在
   foo.1并使得bar.1做成这样子：

   .so man1/foo.1

   指定“man1/”目录部分是非常重要的，文件名“foo.1”同样如此，因为当groff
   由浏览器启动的时候它会以手册基本目录作为其工作目录（cwd），而且groff是参
   照cwd来处理.so的参数的。

   _4）我该使用哪个宏命令包?_

   有好几个宏命令包是特别为编写手册页而设计的。通常它们放在groff的宏命令目
   录/usr/lib/groff/tmac下。其文件名是tmac.<东西>,这里<东西>是groff的-m选项
   的参数。 当给出“-m <东西>”参数时groff会使用tmac.<东西>这个文件。 通常
   “-m”和“<东西>”之间的空格被忽略，所以我们当我们要使用“tmac.an”宏命
   令包来格式化手册页时可以打命令“groff -man”。这就是为什么要起这么个古怪
   的名字 “tmac.an” 的理由 。 除了 “tmac.an” 外还有另一个常用的宏命令包
   tmac.doc，它来源于加利福尼亚的伯克莱大学。很多BSD手册页使用它，看起来UCB
   已经将它作为文档化的标准了。Tmac.doc宏命令确实非常灵活，可是，唉，有些手
   册浏览器不会使用它，而总是使用groff -man。例如，所有我所见过的xman程序都
   会把需要tmac.doc的手册页弄得一团糟。所以，请养成习惯：使用tmac.an——使
   用任何别的宏命令包都被认为有害。tmac.andoc是一个伪宏命令包，它查看源文件
   并载入tmac.an或tmac.doc。实际上任何手册页浏览都器应当使用它，但是直到现
   在都不是所有的程序都这样做，因此最好是坚持使用tmac.an。直到目前我告诉你
   的关于宏命令的东西仅适用于tmac.an。如果你一定要使用tmac.doc，这里有个网
   址指向关于如何使用它的详细信息：http://www.bsdi.com/bsdi-man 在该网页上
   有个可供查询的索引。输入mdoc.samples它会找到mdoc.samples(7)，这是一个编
   写BSD手册页的教程样例。

   _5) 我该使用哪个预处理器?_

   Groff 配有至少三个预处理器：tbl、 eqn和pic （在某些系统里面它们叫做gtbl、
   geqn和gpic。）它们的作用是将预处理器宏及其数据翻译成正式的troff输入。Tbl
   是个表格预处理器，eqn是个公式/数学预处理器，而pic是个图形预处理器。请参
   考其有关的手册页以获得它们提供的功能的更多信息。请将它们放到一边：不要编
   写依赖于任何预处理器的手册页。eqn在类打字机的设备上通常产生出极糟糕的输
   出，不幸的是99%的手册页都是在该类型的设备上看的。例如，XAllocColor.3x使
   用了少量幂函数公式。由于类打字机设备的特点，幂指数会和底数放在同一行。N
   的二次方会显示成“N2"。应当避免使用tbl，因为我所见的所有xman程序都会失败。
   Xman 3.1 使用下列命令来格式化手册页（以signal(7)为例）：

   gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man
   /tmp/xmana01760 2> /dev/null

   这将把使用gtbl的源文件弄的一团糟，因为gtbl的输出被反送到gtbl去，其结果是
   个没有表格的手册页。我不知道gtbl过滤掉自己的输出是个缺点还是特点，也不知
   道xman能否放聪明点不要调用两次gtbl…… 说到底，如果你需要一个表格，自己
   将它格式化好并把它放到.nf 和.fi行之间以便它能保持无格式状态就好。这种情
   况下你不能使用黑体和斜体，但是这个方法能使你的表格在任何情况下都有可以接
   受的样子。我曾见过需要pic预处理器的手册页。但是我不喜欢它。正如以上所说，
   xman不会使用它而且groff确实会对输入作些令人胆战心惊的事情。

   _6）我应该发布我的源文件还是格式化好的文档呢？_
   
   让我们使用优点（+）和缺点（-）来分析几种可能的选择吧：
    1.只有源文件：
       + 发行包更小。
       - 在没有groff的系统下无法访问。
    2.只有未经压缩的已格式化文件：
       + 即使在没有groff的系统仍可访问。
       - 用户不能生成dvi或postscript格式的文件。
       - 在可以处理压缩页的系统中浪费了磁盘空间。
    3. 只有压缩的已格式化文件：
       + 即使在没有groff的系统仍可访问。
       - 用户不能生成dvi或postscript格式的文件。