man 中文man页面-man中文

NAME

man - 格式化手册页的宏

总览 SYNOPSIS

groff -Tascii -man file ...

groff -Tps -man file ...

man [section] title

描述 DESCRIPTION

此手册页解释了 groff tmac.man 宏包 (通常叫做 man 宏包) 以及相关的创建手册页的惯例。开发者可以使用这个宏包来为 linux 书写或移植手册文档。它与其他版本的这个宏包一般是兼容的，因此移植不是一个大问题 (但是 NET-2 BSD 发布中使用了一个完全不同的宏包叫做 mdoc，参见 mdoc(7)).

注意 NET-2 BSD mdoc 手册页也可以使用 groff 处理，只要指定 -mdoc 选项而不是 -man 选项。推荐使用 -mandoc 选项，因为这样会自动判断应当使用哪一个。

导言 PREAMBLE

一篇手册页的第一个命令 (注释行之后) 应当是

: .TH title section date source manual,

这里：

title

手册页的标题 (例如， MAN).

section

手册页的章节号应当放在这里 (例如， 7).

date

最后修改日期 -- 记住要在每次修改过此手册页之后修改它，这样可以方便地进行版本控制

source

命令的来源

对于二进制文件，使用这样的表述： GNU, NET-2, SLS Distribution, MCC Distribution.

对于系统调用，使用它适用的内核版本来表述： Linux 0.99.11.

对于库调用，使用函数的来源来表述： GNU, BSD 4.3, Linux DLL 4.4.1.

manual

手册的标题 (例如： Linux Programmer's Manual).

注意 BSD mdoc 格式的手册页以 Dd 命令开始，而不是 TH 命令

手册章节传统上如下定义：

1 Commands: 用户可从 shell 运行的命令
2 System calls: 必须由内核完成的功能
3 Library calls: 大多数 libc 函数，例如 qsort(3))
4 Special files: /dev) 目录中的文件
5 File formats and conventions: /etc/passwd 等人类可读的文件的格式说明
6 Games
7 Macro packages and conventions: 文件系统标准描述，网络协议，ASCII 和其他字符集，还有你眼前这份文档以及其他东西
8 System management commands: 类似 mount(8) 等命令，大部分只能由 root 执行
9 Kernel routines: 这是废弃的章节。原来曾想把一些关于核心的文件放在这里，但是实际上只有极少数可以写成文件放在这里，而且它们也很快过时了。核心开发者可以找到其他更好的资源。

段 SECTIONS

段以 .SH 开始，后跟标题名。如果标题包含空格并且和 .SH 在同一行，则需在标题上加双引号。传统的或建议的标题包括： NAME, 总览 SYNOPSIS, 描述 DESCRIPTION, 返回值 RETURN VALUE, 退出状态 EXIT STATUS, 错误处理 ERROR HANDLING, 错误 ERRORS, 选项 OPTIONS, 用法 USAGE, 示例 EXAMPLES, 文件 FILES, 环境 ENVIRONMENT, 诊断 DIAGNOSTICS, 安全 SECURITY, 遵循 CONFORMING TO, 注意 NOTES, BUGS, 作者 AUTHOR, 和参见 SEE ALSO. 在适合使用约定标题的地方，请使用它；这样做可以使文章更易读、易懂。不过，只要您的标题能够增加易懂性，请放心使用。唯一必须的标题是 NAME, 他应是手册页的第一段，后面应紧跟对该命令的简单描述。比如：

: .SH NAME
chess \- the game of chess

请一定要按照这个格式来写，注意在短横线 (dash `-') 前要有个斜杠 (slash `'). 这种语法结构在 makewhatis(8) 程序为 whatis(1) 和 apropos(1) 命令建立简短命令描述时要用到。

其他约定段的内容应为：

总览 SYNOPSIS: 简要描述命令或函数接口。对命令，显示他的命令和参数（包括各种选项）；黑体表示各种参数，下划线（或斜体字）表示可以替换的选项；方括号[]中的是可选项，竖线 | 用于把几个选项间隔开，小括号()中的部分可以自动重复。对函数，显示需要的数据声明或需 #include 包含的项目，后跟函数声明。
描述 DESCRIPTION: 解释命令、函数或格式的用途。说明其如何与文件及标准输入交互，他们的标准输出及标准错误。必须要指明的细节。描述一般情况。选项和参数信息放在 OPTIONS（选项）段。如果有语法说明和一些复杂的设定，建议把它们放到 USAGE（用法）段（本段中最好只写一个概要）。
返回值 RETURN VALUE: 列出程序或函数会返回的值，指出引发返回值的条件或原因。
退出状态 EXIT STATUS: 列出可能的退出状态的值，指出引起返回的程序或原因。
选项 OPTIONS: 指出程序可用的选项，及其作用。
用法 USAGE: 描述程序的较高级的使用方法。
示例 EXAMPLES: provides one or more examples describing how this function, file or command is used.
文件 FILES: 列出程序或函数使用到的文件，比如配置文件、启动文件和程序直接操作的文件。给出文件的绝对路径，使用安装程序调整这些路径以使其与用户的实际情况相符。对大多数程序来说，缺省的安装路径是 /usr/local，所以你的文件要与此一致。
环境 ENVIRONMENT: 列出影响你的程序的所有环境变量，并说明影响的原因。
诊断 DIAGNOSTICS: 写出常会出现的错误概述，并说明解决的办法。你无需解释系统错误信息或信号，除非它们会影响到您的程序。
安全 SECURITY: 讨论安全问题和相关话题。对应予避免的配置和环境，可能有安全隐患的命令等等给出警告，特别是当它们不是很明显时。单独用一段来讨论安全并不必要；如果比较好理解的话，把它放在其他段中（比如描述或用法段）。但是，最好加上它。
遵循 CONFORMING TO: 描述它实现的任何标准或约定
注意 NOTES: 提供杂项注意事项
BUGS: 列出局限、已知的缺点或不便之处，还有其他可能存在的问题。
作者 AUTHOR: 列出程序或文件作者，联系办法等。
参见 SEE ALSO: 以字母顺序列出相关的手册页（man pages)。通常来讲，这是一个手册页的最后一段。

字体 FONTS

虽然在 UNIX 世界中有各种对手册页（man pages)的不同约定，但在 linux 系统下存在一个字体的标准：

对函数，其参数通常用下划线（或斜体）， 在总览（SYNOPSIS)中也是这样 ，其他部分用黑体。例如

: int myfunction(int argc, char **argv);

文件名用下划线（或斜体），例如，.IR "/usr/include/stdio.h" ), 但在总览（SYNOPSIS)中，包含的文件用黑体，例如 #include <stdio.h>).

专用宏，一般大写表示，用黑体（如： MAXINT).

列举错误代号时，代号用黑体（这种列举通常使用 .TP 宏命令）。

对其他手册页的引用（或本页中某主体的引用）用黑体。手册章节号用普通体（如： man(7)). 设置字体的宏命令如下：

.B

黑体

.BI

黑体和下划线（或斜体）交替（描述函数时非常有用）

.BR

黑体和普通体交替（描述引用时非常有用）

.I

下划线（或斜体）

.IB

下划线（或斜体）和黑体交替

.IR

普通体和下划线（或斜体）交替

.RB

普通体和下划线（或斜体）交替

.RI

小号字和黑体交替

.SB

小号字和黑体交替

.SM

小号字（用于缩写）

按照惯例，每个命令最多可以有六个小节的参数，但是 GNU 去除了这个限制。小节之间以空格隔开。如果某小节含有空格，则需要给其加上双引号。各小节在显示时无间隔，所以 .BR 命令可以指定一个黑体的词，后跟一个普通体的标点。如果命令后无参数，则命令作用于下一行。

其他宏命令和字符串 OTHER MACROS AND STRINGS

下面是其他一些相关的宏和预定义的字符串。除非指明，否则所有的宏在本行文本结束时终止。多数宏使用“流行缩进”（prevailing indent)方式。 “流行缩进”的值由紧跟着宏命令的 i 值指定，如果不指定，那就会使用当前的“流行缩进”值。这样，连续的缩进段就可使用相同的缩进值而不需要重新指定。普通段（不缩进）将“流行缩进”值重值为缺省值（0.5 英寸）。缺省时，缩进是有规则的 en(s)：用 en(s) 或者 em(s) 作为缩进的单位，因为它们会自动地调整字体的大小。 (注：度量距离有不同的单位，当请求需要用到不同的距离时，可以使用默认类型来修饰数字，度量单位是英寸，厘米，pica,en,em,点，unit和垂直行距。 1pica等于1/6英寸，1em等于字母m的宽度，默认宽度取决于troff中使用的字体。En是em的一半。) 其他宏命令定义如下：

普通段（无缩进） Normal Paragraphs

.LP: 与 .PP 相同（开始一个新段）
.P: 与 .PP 相同（开始一个新段）
.PP: 开始一个新段，重置“流行缩进”值。

相对缩进 Relative Margin Indent

.RS i: 开始相对缩进 -- 把左边界右移 i
(如果不指定 i 值，则使用“流行缩进”值）。同时设定“流行缩进”值为 0.5 英寸。直到使用 .RE 结束这些设定。
.RE: 结束相对缩进同时把“流行缩进”恢复原值。

缩进 Indented Paragraph Macros

.HP i: 开始悬挂式缩进（段的第一行从左边揭开时，其余缩进显示）
.IP x i: 在段上标签 x 。如果不指定 x ，则整个段缩进 i 。如果指定了 x ，则 x 之前的段不缩进，之后的段缩进（有些象 .TP ，不过 x 是跟在命令后面而不是在下一行）。如果 x 太长，后面的文本会挪到下一行（文本不会丢失或割断）。

做公告列表，可以用 \(bu (bullet) 或 \(em (em dash). 要用数字或字母列表, 可以用.IP 1. 或 .IP A. 这样转换成其他格式就简单了。

.TP i: 在段上悬挂标签。标签在下一行指定，但是结果和 .IP 相像。

超文本链接宏 Hypertext Link Macros

.UR u: 建立一个超文本链接到 URI (URL) u; 并以 UE 结束。当转换为 HTML 格式时，他会转换为 <A HREF="u">. 有个例外：如果 u 是特殊字符 “ ：”，则之后不能建立任何超级链接，直到以 UE 结束（这用来在不需要超级链接时禁止他）。 LALR(1) 这个宏比较新，很多程序可能并不对他进行处理。但是由于很多工具 (包括 troff) 简单地忽略未定义宏 (或者最坏的将它们插入到文本中), 插入它们是安全的
.UE: 结束相应的 UR 超级链接。转换为HTML后是 </A>.
.UN u: 给超级联接指定名称为 u; 不需要以 UE UE 结束。转换为 HTML 后为： <A NAME="u" id="u"> </A> (the   is optional if support for Mosaic is unneeded).

杂项宏 Miscellaneous Macros

.DT: 重置 tab 值为缺省(每一个0.5英寸)。不引起中断。
.IX ...: 插入索引信息（方便搜索系统工作，或打印索引列表）。在页中索引信息不能正常显示。如果只有一个参数，参数作为独立的索引项指向手册页的内容。如果有两个参数，他可能是 Perl 手册页格式；第一个参数指定类型名（命令名，标题，题头，子段货源素之一），第二个参数指明自己的索引名。另外，长索引形式：每个参数是一个索引项，次级索引项，再次级索引项，等等直到以空参数结束，然后是程序名参数，\m，还有一小段描述。还可能在跟上一个空参数，有可能是页控制信息（如： PAGE START)。举例如下： "programmingtools""make""""make--- build programs".
.PD d: 在段中间垂直距离空开 d (如果不指定，则缺省为 d=0.4v)，不引起中断。
.SS t: 子标题 t 象是 .SH, 但是作为段中的字标题使用）

预定义字符串 Predefined Strings

man 预定义了下列字符串

\*R: 注册符号: ®
\*S: 改变成缺省字体大小
\*(Tm: 商标符号:
\*(lq: 左双引号: ``
\*(rq: 右双引号: ''

安全子集 SAFE SUBSET

理论上 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, ti, tr.

你还可能使用 troff 转义字符（这些转移符号以 \ 开始）。但你要在文本中显示反斜线时，用\e。其他转义字符包括： \', \`, \-, \., \ , \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, 和 \f(xx. 其中 x、xx 是任意字符，N 是任意数字不要使用转义字符来画图。

不要随意使用 bp （break page(中断页））。 sp （vertical space(垂直距离）只应使用正值。不要用 (de) （define（定义）定义与现有的宏同名的宏（无论 man 或 mdoc)；这种重新定义可能会被忽略。每个正缩进 (in) 应对应一个负缩进（即使在使用 RS 和 RE 是也不例外）。 The condition test (if,ie) should only have 't' or 'n' as the condition. 可以使用的只有可忽略的转换 (tr). 改变字体命令 (ft 和 \f 转义序列) 只能带如下参数： 1, 2, 3, 4, R, I, B, P, or CW (ft 命令也可以不带参数)。

如果你是用更多的功能，用各种程序仔细察看一下结果。如果你肯定某功能是安全的，请告诉我们，以便把他增加到这个列表中。

注意 NOTES

尽量在文本中包含完整的 URL（或URIs）；一些工具软件（如： man2html(1) ）能够自动把它们转换为超级链接。您也可用 UR 命令指定链接到相关信息。输入完整的 URL(如：<http://www.kernel-notes.org> )。

Tools processing these files should open the file and examine the first non-whitespace character. 以(.)或（')开始一行，表明是基于 troff 的文件（如： man 或 mdoc)。如果是（<）表明基于 SGML/XML (如：HTML 或 Docbook)．其他可能是纯文本。(例如 "catman" 的结果)

有些 man 以'\"和空格再加字符列开始，表示他的预处理方法。为了 troff 翻译器程序处理起来简单一些，您仅应使用 tbl(1), 而不是其他什么东东，Linux 可以检测到这一点。不过，你或许想要包含这些信息以使其可以在其他系统得到处理。下面是预处理调用的定义：

e: eqn(1)
g: grap(1)
p: pic(1)
r: refer(1)
t: tbl(1)
v: vgrind(1)

文件 FILES

/usr/share/groff/[*/]tmac/tmac.an
/usr/man/whatis

BUGS

大多数宏命令描述的是格式（比如：字体和空格）而不是内容描述（比如：这段文字指向另外一页），与 mdoc 和 DocBook 正好相反（HTML 也有比较多的内容描述）。这使得 man 难以转换为其他形式，不容易与其他文件组合或自动插入交叉引用。遵照以上的安全说明，就比较容易在将来把他转换为其他格式。

The Sun macro TX 下不能用。

作者 AUTHORS

---: 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.

参见 SEE ALSO

apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), whatis(1)

#p#

NAME

man - macros to format man pages

SYNOPSIS

groff -Tascii -man file ...

groff -Tps -man file ...

man [section] title

DESCRIPTION

This manual page explains the groff tmac.an macro package (often called the man macro package) and related conventions for creating manual (man) pages. This macro package should be used by developers when writing or porting man pages for Linux. It is fairly compatible with other versions of this macro package, so porting man pages should not be a major problem (exceptions include the NET-2 BSD release, which uses a totally different macro package called mdoc; see mdoc(7)).

Note that NET-2 BSD mdoc man pages can be used with groff simply by specifying the -mdoc option instead of the -man option. Using the -mandoc option is, however, recommended, since this will automatically detect which macro package is in use.

PREAMBLE

The first command in a man page (after comment lines) should be

: .TH title section date source manual,

where:

title

The title of the man page (e.g., MAN).

section

The section number the man page should be placed in (e.g., 7).

date

The date of the last revision---remember to change this every time a change is made to the man page, since this is the most general way of doing version control.

source

The source of the command.

For binaries, use something like: GNU, NET-2, SLS Distribution, MCC Distribution.

For system calls, use the version of the kernel that you are currently looking at: Linux 0.99.11.

For library calls, use the source of the function: GNU, BSD 4.3, Linux DLL 4.4.1.

manual

The title of the manual (e.g., Linux Programmer's Manual).

Note that BSD mdoc-formatted pages begin with the Dd command, not the TH command.

The manual sections are traditionally defined as follows:

1 Commands: Those commands that can be executed by the user from within a shell.
2 System calls: Those functions which must be performed by the kernel.
3 Library calls: Most of the libc functions, such as qsort(3).
4 Special files: Files found in /dev.
5 File formats and conventions: The format for /etc/passwd and other human-readable files.
6 Games
7 Conventions and miscellaneous: A description of the standard file system layout, network protocols, ASCII and other character codes, this man page, and other things.
8 System management commands: Commands like mount(8), many of which only root can execute.
9 Kernel routines: This is an obsolete manual section. Once it was thought a good idea to document the Linux kernel here, but in fact very little has been documented, and the documentation that exists is outdated already. There are better sources of information for kernel developers.

SECTIONS

Sections are started with .SH followed by the heading name. If the name contains spaces and appears on the same line as .SH, then place the heading in double quotes. Traditional or suggested headings include: NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, EXIT STATUS, ERROR HANDLING, ERRORS, OPTIONS, USAGE, EXAMPLES, FILES, ENVIRONMENT, DIAGNOSTICS, SECURITY, CONFORMING TO, NOTES, BUGS, AUTHOR, and SEE ALSO. Where a traditional heading would apply, please use it; this kind of consistency can make the information easier to understand. However, feel free to create your own headings if they make things easier to understand. The only required heading is NAME, which should be the first section and be followed on the next line by a one line description of the program:

: .SH NAME
chess \- the game of chess

It is extremely important that this format is followed, and that there is a backslash before the single dash which follows the command name. This syntax is used by the makewhatis(8) program to create a database of short command descriptions for the whatis(1) and apropos(1) commands.

Some other traditional sections have the following contents:

SYNOPSIS: briefly describes the command or function's interface. For commands, this shows the syntax of the command and its arguments (including options); boldface is used for as-is text and italics are used to indicate replaceable arguments. Brackets ([]) surround optional arguments, vertical bars (|) separate choices, and ellipses (...) can be repeated. For functions, it shows any required data declarations or #include directives, followed by the function declaration.
DESCRIPTION: gives an explanation of what the command, function, or format does. Discuss how it interacts with files and standard input, and what it produces on standard output or standard error. Omit internals and implementation details unless they're critical for understanding the interface. Describe the usual case; for information on options use the OPTIONS section. If there is some kind of input grammar or complex set of subcommands, consider describing them in a separate USAGE section (and just place an overview in the DESCRIPTION section).
RETURN VALUE: gives a list of the values the library routine will return to the caller and the conditions that cause these values to be returned.
EXIT STATUS: lists the possible exit status values or a program and the conditions that cause these values to be returned.
OPTIONS: describes the options accepted by the program and how they change its behavior.
USAGE: describes the grammar of any sublanguage this implements.
EXAMPLES: provides one or more examples describing how this function, file or command is used.
FILES: lists the files the program or function uses, such as configuration files, startup files, and files the program directly operates on. Give the full pathname of these files, and use the installation process to modify the directory part to match user preferences. For many programs, the default installation location is in /usr/local, so your base manual page should use /usr/local as the base.
ENVIRONMENT: lists all environment variables that affect your program or function and how they affect it.
DIAGNOSTICS: gives an overview of the most common error messages and how to cope with them. You don't need to explain system error messages or fatal signals that can appear during execution of any program unless they're special in some way to your program.
SECURITY: discusses security issues and implications. Warn about configurations or environments that should be avoided, commands that may have security implications, and so on, especially if they aren't obvious. Discussing security in a separate section isn't necessary; if it's easier to understand, place security information in the other sections (such as the DESCRIPTION or USAGE section). However, please include security information somewhere!
CONFORMING TO: describes any standards or conventions this implements.
NOTES: provides miscellaneous notes.
BUGS: lists limitations, known defects or inconveniences, and other questionable activities.
AUTHOR: lists authors of the documentation or program so you can mail in bug reports.
SEE ALSO: lists related man pages in alphabetical order, possibly followed by other related pages or documents. Conventionally this is the last section.

FONTS

Although there are many arbitrary conventions for man pages in the UNIX world, the existence of several hundred Linux-specific man pages defines our font standards:

For functions, the arguments are always specified using italics, even in the SYNOPSIS section, where the rest of the function is specified in bold:

: int myfunction(int argc, char **argv);

Filenames are always in italics (e.g., /usr/include/stdio.h), except in the SYNOPSIS section, where included files are in bold (e.g., #include <stdio.h>).

Special macros, which are usually in upper case, are in bold (e.g., MAXINT).

When enumerating a list of error codes, the codes are in bold (this list usually uses the .TP macro).

Any reference to another man page (or to the subject of the current man page) is in bold. If the manual section number is given, it is given in Roman (normal) font, without any spaces (e.g., man(7)).

The commands to select the type face are:

.B: Bold
.BI: Bold alternating with italics (especially useful for function specifications)
.BR: Bold alternating with Roman (especially useful for referring to other manual pages)
.I: Italics
.IB: Italics alternating with bold
.IR: Italics alternating with Roman
.RB: Roman alternating with bold
.RI: Roman alternating with italics
.SB: Small alternating with bold
.SM: Small (useful for acronyms)

Traditionally, each command can have up to six arguments, but the GNU implementation removes this limitation (you might still want to limit yourself to 6 arguments for portability's sake). Arguments are delimited by spaces. Double quotes can be used to specify an argument which contains spaces. All of the arguments will be printed next to each other without intervening spaces, so that the .BR command can be used to specify a word in bold followed by a mark of punctuation in Roman. If no arguments are given, the command is applied to the following line of text.

OTHER MACROS AND STRINGS

Below are other relevant macros and predefined strings. Unless noted otherwise, all macros cause a break (end the current line of text). Many of these macros set or use the "prevailing indent." The "prevailing indent" value is set by any macro with the parameter i below; macros may omit i in which case the current prevailing indent will be used. As a result, successive indented paragraphs can use the same indent without re-specifying the indent value. A normal (non-indented) paragraph resets the prevailing indent value to its default value (0.5 inches). By default a given indent is measured in ens; try to ens or ems as units for indents, since these will automatically adjust to font size changes. The other key macro definitions are:

Normal Paragraphs

.LP: Same as .PP (begin a new paragraph).
.P: Same as .PP (begin a new paragraph).
.PP: Begin a new paragraph and reset prevailing indent.

Relative Margin Indent

.RS i: Start relative margin indent - moves the left margin i to the right (if i is omitted, the prevailing indent value is used). A new prevailing indent is set to 0.5 inches. As a result, all following paragraph(s) will be indented until the corresponding .RE.
.RE: End relative margin indent and restores the previous value of the prevailing indent.

Indented Paragraph Macros

.HP i: Begin paragraph with a hanging indent (the first line of the paragraph is at the left margin of normal paragraphs, and the rest of the paragraph's lines are indented).
.IP x i: Indented paragraph with optional hanging tag. If the tag x is omitted, the entire following paragraph is indented by i. If the tag x is provided, it is hung at the left margin before the following indented paragraph (this is just like .TP except the tag is included with the command instead of being on the following line). If the tag is too long, the text after the tag will be moved down to the next line (text will not be lost or garbled). For bulleted lists, use this macro with \(bu (bullet) or \(em (em dash) as the tag, and for numbered lists, use the number or letter followed by a period as the tag; this simplifies translation to other formats.
.TP i: Begin paragraph with hanging tag. The tag is given on the next line, but its results are like those of the .IP command.

Hypertext Link Macros

.UR u: Begins a hypertext link to the URI (URL) u; it will end with the corresponding UE command. When generating HTML this should translate into the HTML command <A HREF="u">. There is an exception: if u is the special value ":", then no hypertext link of any kind will be generated until after the closing UE (this permits disabling hypertext links in phrases like LALR(1) when linking is not appropriate). These hypertext link "macros" are new, and many tools won't do anything with them, but since many tools (including troff) will simply ignore undefined macros (or at worst insert their text) these are safe to insert.
.UE: Ends the corresponding UR command; when generating HTML this should translate into </A>.
.UN u: Creates a named hypertext location named u; do not include a corresponding UE command. When generating HTML this should translate into the HTML command <A NAME="u" id="u"> </A> (the   is optional if support for Mosaic is unneeded).

Miscellaneous Macros

.DT: Reset tabs to default tab values (every 0.5 inches); does not cause a break.
.PD d: Set inter-paragraph vertical distance to d (if omitted, d=0.4v); does not cause a break.
.SS t: Subheading t (like .SH, but used for a subsection inside a section).

Predefined Strings

The man package has the following predefined strings:

\*R: Registration Symbol: ®
\*S: Change to default font size
\*(Tm: Trademark Symbol:
\*(lq: Left angled doublequote: ``
\*(rq: Right angled doublequote: ''

SAFE SUBSET

Although technically man is a troff macro package, in reality a large number of other tools process man page files that don't implement all of troff's abilities. Thus, it's best to avoid some of troff's more exotic abilities where possible to permit these other tools to work correctly. Avoid using the various troff preprocessors (if you must, go ahead and use tbl(1), but try to use the IP and TP commands instead for two-column tables). Avoid using computations; most other tools can't process them. Use simple commands that are easy to translate to other formats. The following troff macros are believed to be safe (though in many cases they will be ignored by translators): \ , ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.

You may also use many troff escape sequences (those sequences beginning with \). When you need to include the backslash character as normal text, use \e. Other sequences you may use, where x or xx are any characters and N is any digit, include: \', \`, \-, \., \ , \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, and \f(xx. Avoid using the escape sequences for drawing graphics.

Do not use the optional parameter for bp (break page). Use only positive values for sp (vertical space). Don't define a macro (de) with the same name as a macro in this or the mdoc macro package with a different meaning; it's likely that such redefinitions will be ignored. Every positive indent (in) should be paired with a matching negative indent (although you should be using the RS and RE macros instead). The condition test (if,ie) should only have 't' or 'n' as the condition. Only translations (tr) that can be ignored should be used. Font changes (ft and the \f escape sequence) should only have the values 1, 2, 3, 4, R, I, B, P, or CW (the ft command may also have no parameters).

If you use capabilities beyond these, check the results carefully on several tools. Once you've confirmed that the additional capability is safe, let the maintainer of this document know about the safe command or sequence that should be added to this list.

NOTES

By all means include full URLs (or URIs) in the text itself; some tools such as man2html(1) can automatically turn them into hypertext links. You can also use the new UR macro to identify links to related information. If you include URLs, use the full URL (e.g., <http://www.kernelnotes.org>) to ensure that tools can automatically find the URLs.

Tools processing these files should open the file and examine the first non-whitespace character. A period (.) or single quote (') at the beginning of a line indicates a troff-based file (such as man or mdoc). A left angle bracket (<) indicates an SGML/XML-based file (such as HTML or Docbook). Anything else suggests simple ASCII text (e.g., a "catman" result).

Many man pages begin with '\" followed by a space and a list of characters, indicating how the page is to be preprocessed. For portability's sake to non-troff translators we recommend that you avoid using anything other than tbl(1), and Linux can detect that automatically. However, you might want to include this information so your man page can be handled by other (less capable) systems. Here are the definitions of the preprocessors invoked by these characters:

e: eqn(1)
g: grap(1)
p: pic(1)
r: refer(1)
t: tbl(1)
v: vgrind(1)

FILES

/usr/share/groff/[*/]tmac/tmac.an
/usr/man/whatis

BUGS

Most of the macros describe formatting (e.g., font type and spacing) instead of marking semantic content (e.g., this text is a reference to another page), compared to formats like mdoc and DocBook (even HTML has more semantic markings). This situation makes it harder to vary the man format for different media, to make the formatting consistent for a given media, and to automatically insert cross-references. By sticking to the safe subset described above, it should be easier to automate transitioning to a different reference page format in the future.

The Sun macro TX is not implemented.

AUTHORS

---: 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.