让我向您展示一个例子。下面我将详细解释它。如果您以纯文本形式阅读，它将不会显示不同的字体（粗体 和 斜体）。 [TODO: 粗体和斜体在转换为 SGML/HTML 的过程中消失了；请恢复它们。] 请参考 "什么是字体约定？" 段落以获得进一步的解释。接下来是（假设的） man page，针对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 <howto at schweikhardt dot net>
SEE ALSO
bar(1), foo(5), xyzzy(1)
Linux Last change: MARCH 1995 2
|
这是我承诺的解释。
NAME 部分
...是唯一必需的部分。没有 NAME 部分的 man page 就像北极的冰箱一样毫无用处。此部分还具有标准化的格式，由逗号分隔的程序或函数名称列表组成，后跟一个破折号，再后跟程序（或函数或文件）应该提供的功能的简短（通常是一行）描述。通过makewhatis(8)，NAME 部分使其进入whatis数据库文件。Makewhatis是 NAME 部分必须存在的原因，以及它为什么必须遵守我描述的格式的原因。在groff源代码中，它必须看起来像
.SH NAME foo \- frobnicate the bar library
这里的 \- 非常重要。反斜杠是必要的，以使破折号与可能出现在命令名称或单行描述中的连字符区分开来。
SYNOPSIS 部分
...旨在提供可用程序选项的简短概述。对于函数，此部分列出相应的 include 文件和原型，以便程序员了解参数的类型和数量以及返回类型。
DESCRIPTION 部分
...雄辩地解释了为什么您的 0 和 1 序列是值得的。这里是您写下所有知识的地方。这是名人堂。通过使此部分成为可靠和详细信息的来源，赢得其他程序员和用户的钦佩。解释参数的用途、文件格式，以及哪些算法执行繁重的工作。
OPTIONS 部分
...描述了每个选项如何影响程序行为。 你知道的，不是吗？
FILES 部分
...列出程序或函数使用的文件。例如，它列出配置文件、启动文件以及程序直接操作的文件。给出这些文件的完整路径名，并使安装过程修改目录部分以匹配用户偏好是一个好主意：groff手册的默认前缀是 /usr/local，因此它们默认引用 /usr/local/lib/groff/*。但是，如果您使用 'make prefix=/opt/gnu' 进行安装，则 man page 中的引用将更改为 /opt/gnu/lib/groff/*
ENVIRONMENT 部分
...列出所有影响您的程序或函数的环境变量，并说明如何影响，当然。最常见的是，这些变量将保存路径名、文件名或默认选项。
DIAGNOSTICS 部分
...应该概述您的程序中最常见的错误消息以及如何处理它们。 没有必要解释系统错误消息（来自perror(3)）或致命信号（来自psignal(3)），因为它们可能在任何程序的执行过程中出现。
BUGS 部分
...理想情况下应该不存在。如果您很勇敢，您可以在此处描述局限性、已知的不便之处以及其他人可能认为是不良特性的功能。如果您不那么勇敢，请将其重命名为 TO DO 部分 ;-)
AUTHOR 部分
...最好有，以防文档或程序行为中存在严重错误（Bzzt!）并且您想发送错误报告。
SEE ALSO 部分
...是按字母顺序排列的相关 man page 列表。按照惯例，它是最后一个部分。如果其他部分真的不适合到目前为止描述的任何一个部分，您可以自由创建其他部分。那么您究竟是如何生成该 man page 的？我预料到这个问题，这是源代码，卢克
.\" 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 <howto at schweikhardt dot net> .SH "SEE ALSO" .BR bar (1), .BR foo (5), .BR xyzzy (1) |