man-page.html

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

       - 要使用哪个压缩格式？.Z？.z？.gz？还是所有的格式？
    4. 同时有源文件及未压缩的已格式化文件：
       + 即使在没有groff的系统仍可访问。
       - 发行包更大。
       - 某些系统可能需要已压缩的格式化手册页。
       - 对已经安装groff的系统来说有点累赘。

   恕我直言最好的方法是仅发布源文件。主要的缺点是它在没有groff的系统里无法
   访问，但这没有关系。Linux文档计划里面超过500个手册页都只有源文件。 来自
   FSF的手册页是只有源文件的。事实上，我很少听说过有软件发布格式化好的手册
   页。如果系统管理员真的关心手册页的可访问性，那么他应该已经装好了groff。

   _7) 使用字体的惯例是什么？_

   首先：不要直接使用字体操作符例如\fB \fP等等。使用带参数的宏命令。这样你
   可以避免一个常见的问题：忘记在单词的末尾把字体改回来，结果把粗体和斜体设
   置扩展到了下一次改字体的时候 。 相信我 ， 这种 情况的发生比你想象中普遍。
   tmac.an宏命令提供了以下字体式样：

       .B 粗体

       .BI 粗体跟斜体

       .BR 粗体跟正体

       .I 斜体

       .IB 斜体跟粗体

       .IR 斜体跟正体

       .RB 正体跟粗体

       .RI 正体跟斜体

       .SM 小（缩放到正常大小的9/10）

       .SB 小跟黑体（所跟的黑体不会缩小）

   “X 跟 Y” 意味著奇数的参数就用X字体，而偶数的参数用Y字体。例如：

       .BI "参数1是黑体，" "参数2是斜体，" "又是黑体" "又是斜体"

   要在参数中使用空格，必须使用双引号。能提供的就这么多。现在告诉你如何使用
   这些字体：（一部分是厚著脸皮从man(7)中偷出来的）

   尽管UNIX世界的手册页里有很多随意的惯例，已有的数百个Linux特定的手册页仍然
   规定了我们的标准：对于函数，参数总是指定为斜体，即使在其他部分要指定为黑
   体的用法段里也一样：

       .BI "myfunction(int " argc ", char **" argv );

   文件名总是斜体，除非在大纲段中，该段中所包含的文件名要用黑体。所以你要用

       .I /usr/include/stdio.h

   和

       .B #include <stdio.h>


   通常用大写字母表示的特殊宏，用黑体：

       .B MAXINT

   要列举错误代码时，这些代码用黑体。这个列表通常按如下方法使用.TP（使用开
   放标记的段落）宏：

       .TP
       .B EBADF
       .I fd is not a valid file descriptor.
       .TP
       .B EINVAL
       .I fd is unsuitable for reading

   对其他手册页（或本手册页）的引用是黑体的。如果给出手册领域号，它使用正体，
   且不带空格：

       .BR man (7)

   缩写词用小字体看上去效果最好。因此我建议

       .SM UNIX
       
       .SM ASCII
       
       .SM TAB
       
       .SM NFS
       
       .SM LALR(1)

   _8) 如何使手册页精益求精？_

   以下是一些指引，可以提高你的文档的可靠性、可读性和“可格式化性”。

   * 测试示例，如果它们能运行的话（使用剪切和粘贴来保证确切地将手册页中的东
     西传给shell），然后将程序的输出放进手册页中，不要把你想象的程序输出敲
     进去。

   * 校对、检查拼写，让别人阅读，如果你的母语不是英语，这点尤其重要。你读的
     这份HOWTO现在还没通过这最后一步，你是否乐意帮点忙呢？
   
   * 测试你的手册页：格式化你的手册页时groff有没有抱怨？最好将所用到的groff
     命令行写成注解。当你调用“man 你的程序”时man(1)命令有没有埋怨？Man(1)
     命令使用格式化系统有没有产生出预期的结果？xman(1x)和tkman(1tk)能处理你
     的手册吗？XFree86 3.1使用xman 3.1.6 - X11R6,它会试图使用

       gzip -c -d < %s > %s
       zcat < %s > %s

     来解压缩。

   * Makewhatis(8)命令能否从NAME段中取出在线描述？


   _9）如何得到完全没有^H^标记的纯文本手册页？_

   请看col(1)，col可以过滤掉退格序列。只要大小写正确，你不用等很久的：

   funnyprompt$ groff -t -e -mandoc -Tascii manpage.1 | col -bx >
   manpage.txt

   -t和-e开关告诉groff 使用tbl和eqn进行预处理。对于不需要预处理的手册页这样
   做有点多余，但是浪费一点CPU周期并不会造成什么损害。另一方面，当-t选项确
   实会造成损害时不要用它：比如表格被格式化得很可怕。你甚至用以下命令可以找
   出（嗯，说“猜想”可能更好）要格式化某个groff文档（不光是手册页)需要什么
   命令：

   funnyprompt$ grog /usr/man/man7/signal.7 groff -t -man
   /usr/man/man7/signal.7

   “Grog”意思是“猜（guess）groff”，其作用正如所述——猜，如果它已经完美
   的话我们就不再需要什么选项。我曾经见过它猜错了宏命令包，但从没见过猜错预
   处理器的。这里有我写的一个小perl脚本，可以删除页眉和页脚，因此在打印滔滔
   不绝的手册页时能省下几页纸。 将它保存成名叫strip-headers的文件 ， 并使用
   chmod 755命令。
   
    #!/usr/bin/perl -wn
    #  make it slurp the whole file at once:
    undef $/;
    #  delete first header:
    s/^\n*.*\n+//;
    #  delete last footer:
    s/\n+.*\n+$/\n/g;
    #  delete page breaks:
    s/\n\n+[^ \t].*\n\n+(\S+).*\1\n\n+/\n/g;
    #  collapse two or more blank lines into a single one:
    s/\n{3,}/\n\n/g;
    #  see what's left...
    print;

   你必须使用它作为“man”命令后面的第一个过滤器，因为它依赖于由groff输出的
   换行符数量，比如：

   funnyprompt$ man bash | strip-headers | col -bx > bash.txt

   _10）如何得到高质量的Postscript手册页？_

   使用你喜欢的PostScript打印机或解释器打印。选项的详细解释请参见问题9）。

   _11）如何使apropos和whatis干活?_

   假定你想知道你系统里装了什么编译器，以及如何调用它们。解决这个（经常问到
   的）问题的方法是

   funnyprompt$ apropos compiler
   f77 (1) - Fortran 77 compiler
   gcc (1) - GNU C and C++ compiler
   pc (1) - Pascal compiler

   Apropos和Whatis程序用于快速查找相关主题的手册页。这两个程序都查找许多个
   名叫 “whatis” 的文件 ， 它们可以在每个手册基本目录下找到。 正如前述，
   whatis数据库文件为目录树下每个手册页准备了一行入口。实际上，这行正是NAME
   段（更精确的说法是：将该行加入，将连字符去掉，同时用圆括号括起该段作为注
   记）。whatis数据库文件是由makewhatis程序建立的。它有好几个版本，所以请参
   考其手册页看看有些什么选项可以使用。为了使makewhatis能正确取出NAME段，坚
   持按照问题2）所述的格式编写NAME段是很重要的。apropos和whatis不同之处是所
   查找的内容在行中的位置和查找的内容。Apropos（相当于man -k）查找其参数在
   行中的任意出现，而whatis（相当于man -f）试图匹配完整的命令名，即连字符前
   面的内容。因此，“whatis cc”在有cc的手册时会告诉你，但是并不告诉你关于
   gcc的东西。


   _ A）复制条款_

   除非另有声明，Linux HOWTO文档是由其各自的作者拥有的。Linux HOWTO文档可以
   部分或全部复制或发布于任何的物理或电子媒体，但是本版权声明必须在所有拷贝
   中保留。商业性的再发布是允许并受到鼓励的；然而，作者会乐意看到在这样的的
   在发布前得到通知。所有的翻译、派生工作或汇总为任何Linux HOWTO文档的工作
   必须含有这份版权声明。这意味著，你不能通过从一份HOWTO文件中派生一些工作
   然后对其附加额外的发布约束。 在得到特许时， 这些规则可以违背，请跟Linux 
   HOWTO协调者联系，其地址列在下面。简而言之，我们希望通过尽可能多的途径促
   进这些信息的传播。然而我们不愿意保留HOWTO文档的版权，但是愿意在任何HOWTO
   文件再发布前得到通知。如果有任何问题，请联系Greg Hankins，Linux HOWTO协
   调者，电子邮件是[e-mail]。

   Copyright 1995,96,97 by Jens Schweikhardt <[e-mail]>
   
   Voice: ++49 7151 909516
   
   Unless otherwise stated, Linux HOWTO documents are copyrighted by
   their respective authors. Linux HOWTO documents may be reproduced and
   distributed in whole or in part, in any medium physical or electronic,
   as long as this copyright notice is retained on all copies. Commercial
   redistribution is allowed and encouraged; however, the author would
   like to be notified of any such distributions. All translations,
   derivative works, or aggregate works incorporating any Linux HOWTO
   documents must be covered under this copyright notice. That is, you
   may not produce a derivative work from a HOWTO and impose additional
   restrictions on its distribution. Exceptions to these rules may be
   granted under certain conditions; please contact the Linux HOWTO
   coordinator at the address given below. In short, we wish to promote
   dissemination of this information through as many channels as
   possible. However, we do wish to retain copyright on the HOWTO
   documents, and would like to be notified of any plans to redistribute
   the HOWTOs. If you have questions, please contact Greg Hankins, the
   Linux HOWTO coordinator, at [e-mail] via email.

</PRE>
  </BODY>
</HTML>