1MAN(7)                     Linux Programmer's Manual                    MAN(7)
2
3
4

NAME

6       man - macros to format man pages
7

SYNOPSIS

9       groff -Tascii -man file ...
10
11       groff -Tps -man file ...
12
13       man [section] title
14

DESCRIPTION

16       This manual page explains the groff an.tmac macro package (often called
17       the man macro package).  This macro package should be used by  develop‐
18       ers when writing or porting man pages for Linux.  It is fairly compati‐
19       ble with other versions of this macro package,  so  porting  man  pages
20       should  not  be  a  major  problem  (exceptions  include  the NET-2 BSD
21       release, which uses a totally different macro package called mdoc;  see
22       mdoc(7)).
23
24       Note  that  NET-2  BSD  mdoc man pages can be used with groff simply by
25       specifying the -mdoc option instead of  the  -man  option.   Using  the
26       -mandoc  option is, however, recommended, since this will automatically
27       detect which macro package is in use.
28
29       For conventions that should be employed when writing man pages for  the
30       Linux man-pages package, see man-pages(7).
31
32   Title line
33       The  first  command  in a man page (after comment lines, that is, lines
34       that start with .\") should be
35
36              .TH title section date source manual
37
38       For details of the arguments that should be supplied to the TH command,
39       see man-pages(7).
40
41       Note  that  BSD mdoc-formatted pages begin with the Dd command, not the
42       TH command.
43
44   Sections
45       Sections are started with .SH followed by the heading name.
46
47       The only mandatory heading is NAME, which should be the  first  section
48       and  be followed on the next line by a one line description of the pro‐
49       gram:
50
51              .SH NAME
52
53       It is extremely important that this format is followed, and that  there
54       is  a  backslash before the single dash which follows the command name.
55       This syntax is used by the makewhatis(8) program to create  a  database
56       of  short  command  descriptions  for the whatis(1) and apropos(1) com‐
57       mands.
58
59       For a list of other sections that might appear in a  manual  page,  see
60       man-pages(7).
61
62   Fonts
63       The commands to select the type face are:
64
65       .B  Bold
66
67       .BI Bold alternating with italics (especially useful for function spec‐
68           ifications)
69
70       .BR Bold alternating with Roman (especially  useful  for  referring  to
71           other manual pages)
72
73       .I  Italics
74
75       .IB Italics alternating with bold
76
77       .IR Italics alternating with Roman
78
79       .RB Roman alternating with bold
80
81       .RI Roman alternating with italics
82
83       .SB Small alternating with bold
84
85       .SM Small (useful for acronyms)
86
87       Traditionally,  each  command can have up to six arguments, but the GNU
88       implementation removes this limitation (you might still want  to  limit
89       yourself  to 6 arguments for portability's sake).  Arguments are delim‐
90       ited by spaces.  Double quotes can be used to specify an argument which
91       contains  spaces.   All  of  the arguments will be printed next to each
92       other without intervening spaces, so that the .BR command can  be  used
93       to  specify  a word in bold followed by a mark of punctuation in Roman.
94       If no arguments are given, the command is applied to the following line
95       of text.
96
97   Other Macros and Strings
98       Below  are  other relevant macros and predefined strings.  Unless noted
99       otherwise, all macros cause a break (end the  current  line  of  text).
100       Many of these macros set or use the "prevailing indent."  The "prevail‐
101       ing indent" value is set by any  macro  with  the  parameter  i  below;
102       macros  may  omit i in which case the current prevailing indent will be
103       used.  As a result, successive indented paragraphs  can  use  the  same
104       indent  without  respecifying the indent value.  A normal (nonindented)
105       paragraph resets the prevailing indent value to its default value  (0.5
106       inches).   By default a given indent is measured in ens; try to use ens
107       or ems as units for indents, since these will automatically  adjust  to
108       font size changes.  The other key macro definitions are:
109
110   Normal Paragraphs
111       .LP      Same as .PP (begin a new paragraph).
112
113       .P       Same as .PP (begin a new paragraph).
114
115       .PP      Begin a new paragraph and reset prevailing indent.
116
117   Relative Margin Indent
118       .RS i    Start  relative  margin indent: moves the left margin i to the
119                right (if i is omitted, the prevailing indent value is  used).
120                A  new  prevailing  indent is set to 0.5 inches.  As a result,
121                all following paragraph(s) will be indented until  the  corre‐
122                sponding .RE.
123
124       .RE      End  relative margin indent and restores the previous value of
125                the prevailing indent.
126
127   Indented Paragraph Macros
128       .HP i    Begin paragraph with a hanging indent (the first line  of  the
129                paragraph  is at the left margin of normal paragraphs, and the
130                rest of the paragraph's lines are indented).
131
132       .IP x i  Indented paragraph with optional hanging tag.  If the tag x is
133                omitted,  the entire following paragraph is indented by i.  If
134                the tag x is provided, it is hung at the  left  margin  before
135                the following indented paragraph (this is just like .TP except
136                the tag is included with the command instead of being  on  the
137                following  line).   If the tag is too long, the text after the
138                tag will be moved down to the next line (text will not be lost
139                or  garbled).   For  bulleted  lists, use this macro with \(bu
140                (bullet) or \(em (em dash) as the tag, and for numbered lists,
141                use the number or letter followed by a period as the tag; this
142                simplifies translation to other formats.
143
144       .TP i    Begin paragraph with hanging tag.  The tag  is  given  on  the
145                next line, but its results are like those of the .IP command.
146
147   Hypertext Link Macros
148       (Feature  supported  with  groff only.)  In order to use hypertext link
149       macros, it is necessary to load the www.tmac macro  package.   Use  the
150       request .mso www.tmac to do this.
151
152       .URL url link trailer
153                Inserts  a  hypertext  link to the URI (URL) url, with link as
154                the text of the link.  The trailer will be printed immediately
155                afterwards.   When  generating HTML this should translate into
156                the HTML command <A HREF="url">link</A>trailer.
157
158                This and other related macros are new, and many tools won't do
159                anything  with  them,  but  since many tools (including troff)
160                will simply ignore undefined macros (or at worst insert  their
161                text) these are safe to insert.
162
163                It  can be useful to define your own URL macro in manual pages
164                for the benefit of those viewing it with a roff  viewer  other
165                than  groff.   That  way, the URL, link text, and trailer text
166                (if any) are still visible.
167
168                Here's an example:
169                      .de URL
170                      \\$2 \(laURL: \\$1 \(ra\\$3
171                      ..
172                      .if \n[.g] .mso www.tmac
173                      .TH ...
174                      (later in the page)
175                      This software comes from the
176                      .URL "http://www.gnu.org/" "GNU Project" " of the"
177                      .URL "http://www.fsf.org/" "Free Software Foundation" .
178
179                In the above, if groff is being used, the www.tmac macro pack‐
180                age's  definition  of the URL macro will supersede the locally
181                defined one.
182
183       A number of other link macros are available.  See groff_www(7) for more
184       details.
185
186   Miscellaneous Macros
187       .DT      Reset  tabs to default tab values (every 0.5 inches); does not
188                cause a break.
189
190       .PD d    Set  inter-paragraph  vertical  distance  to  d  (if  omitted,
191                d=0.4v); does not cause a break.
192
193       .SS t    Subheading  t  (like  .SH,  but used for a subsection inside a
194                section).
195
196   Predefined Strings
197       The man package has the following predefined strings:
198
199       \*R    Registration Symbol: ®
200
201       \*S    Change to default font size
202
203       \*(Tm  Trademark Symbol: ™
204
205       \*(lq  Left angled double quote: “
206
207       \*(rq  Right angled double quote: ”
208
209   Safe Subset
210       Although technically man is a troff macro package, in reality  a  large
211       number  of  other tools process man page files that don't implement all
212       of troff's abilities.  Thus, it's best to avoid some  of  troff's  more
213       exotic  abilities  where  possible  to permit these other tools to work
214       correctly.  Avoid using the various troff preprocessors (if  you  must,
215       go  ahead and use tbl(1), but try to use the IP and TP commands instead
216       for two-column tables).  Avoid using  computations;  most  other  tools
217       can't  process them.  Use simple commands that are easy to translate to
218       other formats.  The following troff macros  are  believed  to  be  safe
219       (though  in many cases they will be ignored by translators): \", ., ad,
220       bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps,
221       so, sp, ti, tr.
222
223       You may also use many troff escape sequences (those sequences beginning
224       with \).  When you need to include the backslash  character  as  normal
225       text, use \e.  Other sequences you may use, where x or xx are any char‐
226       acters and N is any digit, include: \', \`, \-, \., \", \%, \*x, \*(xx,
227       \(xx,  \$N,  \nx,  \n(xx,  \fx,  and  \f(xx.   Avoid  using  the escape
228       sequences for drawing graphics.
229
230       Do not use the optional parameter for bp (break page).  Use only  posi‐
231       tive  values  for  sp (vertical space).  Don't define a macro (de) with
232       the same name as a macro in this or the mdoc macro package with a  dif‐
233       ferent  meaning;  it's  likely that such redefinitions will be ignored.
234       Every positive indent (in) should be paired with  a  matching  negative
235       indent  (although  you  should  be using the RS and RE macros instead).
236       The condition test (if,ie) should only have 't' or 'n'  as  the  condi‐
237       tion.  Only translations (tr) that can be ignored should be used.  Font
238       changes (ft and the \f escape sequence) should only have the values  1,
239       2,  3,  4,  R,  I, B, P, or CW (the ft command may also have no parame‐
240       ters).
241
242       If you use capabilities beyond these, check the  results  carefully  on
243       several tools.  Once you've confirmed that the additional capability is
244       safe, let the maintainer of this document know about the  safe  command
245       or sequence that should be added to this list.
246

FILES

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

NOTES

252       By all means include full URLs (or URIs) in the text itself; some tools
253       such as man2html(1) can automatically turn them into  hypertext  links.
254       You  can also use the new URL macro to identify links to related infor‐
255       mation.  If you include URLs, use the full URL (e.g.,  <http://www.ker
256       nelnotes.org>) to ensure that tools can automatically find the URLs.
257
258       Tools processing these files should open the file and examine the first
259       nonwhitespace character.  A period (.)  or  single  quote  (')  at  the
260       beginning of a line indicates a troff-based file (such as man or mdoc).
261       A left angle bracket (<) indicates an SGML/XML-based file (such as HTML
262       or  Docbook).   Anything else suggests simple ASCII text (e.g., a "cat‐
263       man" result).
264
265       Many man pages begin with ´\" followed by a space and a list of charac‐
266       ters, indicating how the page is to be preprocessed.  For portability's
267       sake to non-troff translators we recommend that you  avoid  using  any‐
268       thing other than tbl(1), and Linux can detect that automatically.  How‐
269       ever, you might want to include this information so your man  page  can
270       be  handled  by other (less capable) systems.  Here are the definitions
271       of the preprocessors invoked by these characters:
272
273       e  eqn(1)
274
275       g  grap(1)
276
277       p  pic(1)
278
279       r  refer(1)
280
281       t  tbl(1)
282
283       v  vgrind(1)
284

BUGS

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

SEE ALSO

298       apropos(1),  groff(1),  man(1),  man2html(1),  whatis(1), groff_man(7),
299       groff_www(7), man-pages(7), mdoc(7), mdoc.samples(7)
300

COLOPHON

302       This page is part of release 3.25 of the Linux  man-pages  project.   A
303       description  of  the project, and information about reporting bugs, can
304       be found at http://www.kernel.org/doc/man-pages/.
305
306
307
308Linux                             2007-05-30                            MAN(7)
Impressum