📄 man-page.html
字号:
<HTML><HEAD><META HTTP-EQUIV="Content-Type" content="text/html; charset=gb2312"><TITLE>Linux Man-Page mini-HOWTO 中译版</TITLE></HEAD> <BODY bgcolor=#FFFFFF MARGINHEIGHT=0 MARGINWIDTH=0> <PRE> _LINUX MAN-PAGE-HOWTO 中文版_ 版权所有1995、96、97、98，作者Jens Schweikhardt，请发email给 <<a href="mailto:schweikh@noc.dfn.de">schweikh@noc.dfn.de</a>> 中文译者 Joe Ren <<a href="mailto:joeren@163.net">joeren@163.net</a>> 校对者（欢迎加入我们的行列！） Zeng Zhaorong <zzr_mail@263.net> 请参阅后面的复制条款，那里有更多的说明。 最后更新日期：1998年3月。单击这里可以浏览作者这篇文章的最新版本。 欢迎提出修正和其他建议！ http://www.shuttle.de/schweikh/home.html 中文翻译日期：1999年9月。 如果你要写个可以通过man(1)命令访问的在线文档（也称为手册页）的话，本文 告诉你一些应当牢记的问题。在这份HOWTO里，一份手册将统称为手册页，而不 管它的实际长度是多少，也不管其性别倾向（man在英文里是男人的意思）。 _目录_ * 0) 文档化的一点想法* 1）手册页是如何被访问的？* 2）一个设定好格式的手册页看起来该是什么样子？* 3）我如何在一个手册页里替几个程序/函数编写文档？* 4）我该使用哪个宏命令包?* 5）我该使用哪个预处理器?* 6）我应该发布我的源文件还是格式化好的文档呢？* 7）使用字体的惯例是什么？* 8）如何使手册页精益求精？* 9）如何得到没有^H^标记的纯文本手册页？* 10）如何得到高质量的Postscript手册页？* 11）如何使apropos和whatis干活？* A）复制条款 _0) 文档化的一点想法_ 我们为什么要写文档？问得有点天真。因为我们想要别人会使用我们的程序、库函 数或我们编制好并可以使用的任何东东。可是光是写文档并不是事情的全部： * 文档必须能让人访问得到。如果它藏在某些不标准的地方，以致文档相关工具找 不到它——那它又有什么用呢？ * 文档必须准确可信。没有什么比程序的行为与文档不一致更讨厌的了。用户会诅 咒你，发给你愤怒的邮件，并将你的工作扔进垃圾桶，坚决不再安装这个怪人 所写的一切东西。 传统且广为人知的UNIX文档化方法是通过man(1)命令实现的。这份HOWTO描述了如 何写出一个手册页，使文档相关工具能够正确地处理它。这些工具中最重要的是 man(1)、xman(1x)、apropos(1)、makewhatis(8)和catman(8)。当然，要使信息 准确可信只能靠你自己了。但即使在这个方面，下面的内容也可以帮助你少走一些 弯路。 _1）手册页是如何被访问的？_ 为了替你的手册页起个正确的名字并安装在正确的位置上，你需要知道访问手册页 过程的机理。所有的手册页都属于一个特定的领域，用一个字符来表示。Linux下 最通用的领域及其名称及说明如下： 领域 名称 及说明 1 用户命令， 可由任何人启动的。 2 系统调用， 即由内核提供的函数。 3 例程， 即库函数。 4 设备， 即/dev目录下的特殊文件。 5 文件格式描述， 例如/etc/passwd。 6 游戏， 不用解释啦！ 7 杂项， 例如宏命令包、惯例等。 8 系统管理员工具， 只能由root启动。 9 其他（Linux特定的）， 用来存放内核例行程序的文档。 n 新文档， 可能要移到更适合的领域。 o 老文档， 可能会在一段期限内保留。 l 本地文档， 与本特定系统有关的。 手册页源文件（格式化系统的输入）的名字就是命令、函数或文件名的名称，后面 跟一个点，再跟著领域字符。如果你要为“passwd”文件的格式写个手册页，你必 须把源文件起名为“passewd.5”。这里我们也有了一个文件名跟命令名一样的例 子。可能还有个库函数也叫passwd。一般是通过分成不同的领域来解决这种冲突的： 命令的用法在文件“passwd.1”而假想的库函数说明在“passwd.3”里面。 有时候在文件名后面会有附加的字符，比如说“xterm.1x”或“wish.1tk”。 这样做的用意是指明该文档是为X Window程序或Tk应用程序编制的。某些手册 浏览器可以使用这些附加的信息。例如xman在可用文档列表中使用“xterm(x)” 和“wish(tk)”这样的名称。 请勿使用n、o和l领域；按照文件系统标准的说法，不赞成使用这些领域。只要用 数字领域就好了。谨防与现有的程序、函数或文件名发生命名冲突。编写另一个编 辑器并叫它ed、sed（聪明的ed）或red（Rocky的ed）实在是个坏主意。确保你的 程序名是唯一的，就能避免有人运行了你的程序却读到了别人的手册页，或反之。 要做到这点，在lsm数据库查询程序名是一个办法。 现在我们知道了该给文件起什么名字。下一步要决定的事情是它最终会被安装（即 用户在你的包里运行make install命令）在什么地方。Linux系统里面，所有的手 册页都放在环境变量MANPATH指定的目录下面。正如shell使用“PATH”环境变量来 确定可执行文件的位置一样，文档相关工具需要使用MANPATH来确定手册页的位置。 实际上， MANPATH的格式跟PATH是一样的。 它们都用冒号来分隔开一组目录列表 （有点不同的是MANPATH不允许空域，也不许使用相对路径，只能使用绝对路径）。 如果MANPATH变量没有设置，或没有被引出来，将会使用一组缺省值，这至少会包 含/usr/man目录。为了加快搜索，并减少目录的大小，由MANPATH指定的目录（也 称为基本目录）有一组子目录分支命名为“man<s>”。这里<s>代表上面的表格中 介绍的领域字符代码。并非所有的领域都由一个子目录代表，理由很简单，没道理 保留一个空白的“mano”目录。然而 ， 会有名叫 “cat<s>” 、 “dvi<s>” 和 “ps<s>”的目录，用于保存用于显示或打印的文档。下面还会介绍。在基本目录 中只能存在一个名为“whatis”的文件，此文件的作用和建立的方法将在本文11） 段那里谈到。要把领域<s>的手册页安装到正确的地方，最安全的方法就是把它放 到/usr/man/man<s>目录下。然而，一个好的Makefile会允许用户通过一个make变 量例如MANDIR自行选择基本目录。大多数GNU包可以使用--prefix=/what/ever选项。 于是手册将被安装到基本目录/what/ever/man下。我建议你也提供一种类似的方法。 由于出现了Linux文件系统标准（FS-Stnd），事情变得更复杂了。FS-Stnd 1.2上 说：（译注：对于只用英语的编程者是更复杂了，但是对于用中文的人却是福音！） “应该对/usr/man目录的结构有所规定，以便支持用其他语言（多语言）写成 的手册页。” 这一点是通过引入另外一级用以区分不同语言的目录级别来实现的 。 再次引FS- Stnd1.2的话： “/usr/man的这种语言子目录命名方案是基于POSIX 1003.1附录E中的标准制订 的，这一标准描述了地区标识字符串——最为人接受的描述文化环境的方法。 地区字符串的格式如下： <语言>[_<地区>][.<字符集>][,<版本>]” （请参阅FS-Stnd以了解一些常见的地区字符串。） 依据这些原则，我们应该将 手册页放在/usr/man/<地区>/man[1-9lno] 目录下。而已格式化的版本应该放在 /usr/man/<地区>/cat[1-9lno]目录下，如果不遵循这一原则，我们就只能为一个 地区提供手册页了。 然而， 我现在还不能推荐你切换到这些目录结构下。 FS- Stnd 1.2也允许 “所有的手册页仅使用一种语言和代码集的系统可以忽略地区子串并将所有 的手册页都放在<mandir>下。例如，如果系统只用ASCII编码的英语手册页， 它们可以存放在/usr/man（的man[1-9]子目录）目录下。（这是传统的做法 和实际安排。）” 在所有的工具（例如xman、tkman、info和许多别的读取手册页的工具）都能处理 新的目录结构前我不会转到这个结构。 （译注：这是英文作者的意见，但是对我们中文用户，转到新结构是唯一能与国际 接轨的方法。） _2）一个设定好格式的手册页看起来该是什么样子？_ 让我给你介绍个例子。下面我会详细介绍内容。光是看这段纯文本，那些特殊的字 样（黑体和斜体)你是看不到的。请参阅“使用字体的惯例是什么？”一节，那里 有更多的解释。这里是为（假想的）foo程序写的手册页。 FOO(1) User Manuals FOO(1)_NAME_ foo - frobnicate the bar library_SYNOPSIS_ _foo [-bar] [-c_ _config-file_ _]_ _file_ _...DESCRIPTION_ _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 _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._OPTIONS_ -b Do not write `busy' to stdout while processing. -c config-file Use the alternate system wide _config-file_ instead of _/etc/foo.conf_. This overrides any _FOOCONF_ environment variable. -a In addition to the baz segments, also parse the blurfl headers. -r Recursive mode. Operates as fast as lightning at the expense of a megabyte of virtual memory._FILES_ _/etc/foo.conf_ The system wide configuration file. See _foo_(5) for fur- ther details. _~/.foorc_ Per user configuration file. See _foo_(5) for further details._ENVIRONMENT_ FOOCONF If non-null the full pathname for an alternate system wide _foo.conf_. Overridden by the -c option._DIAGNOSTICS_ The following diagnostics may be issued on stderr: Bad magic number. The input file does not look like an archive file. Old style baz segments. foo can only handle new style baz segments. COBOL object libraries are not supported in this version._BUGS_ The command name should have been chosen more carefully to reflect its purpose._AUTHOR_ Jens Schweikhardt <schweikh@noc.dfn.de>_SEE ALSO_ _bar_(1), _foo_(5), _xyzzy_(1)Linux Last change: MARCH 1995 2 我答应过解释的，现在请看吧。 _NAME（名称）段_ ……这是唯一必须要有的段落。没有名称段的手册页就象北极的电冰箱一样毫无⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -