1GROFF_MAN(7) Miscellaneous Information Manual GROFF_MAN(7)
2
6 groff_man - groff `man' macros to support generation of man pages
7
9 groff -man [options ...] [files ...]
10 groff -m man [options ...] [files ...]
11
13 The man macros used to generate man pages with groff were written by
14 James Clark. This document provides a brief summary of the use of each
15 macro in that package.
16
18 The man macros understand the following command line options (which
19 define various registers).
20 -rcR=1 This option (the default if in nroff mode) creates a single,
22 very long page instead of multiple pages. Say -rcR=0 to disable
23 it.
24 -rC1 If more than one manual page is given on the command line, num‐
26 ber the pages continuously, rather than starting each at 1.
27 -rD1 Double-sided printing. Footers for even and odd pages are for‐
29 matted differently.
30 -rFT=dist
32 Set distance of the footer relative to the bottom of the page if
33 negative or relative to the top if positive. The default is
34 -0.5i.
35 -rHY=flags
37 Set hyphenation flags. Possible values are 1 to hyphenate with‐
38 out restrictions, 2 to not hyphenate the last word on a page,
39 4 to not hyphenate the last two characters of a word, and 8 to
40 not hyphenate the first two characters of a word. These values
41 are additive; the default is 14.
42 -rIN=width
44 Set body text indentation to width. The default is 7n for
45 nroff, 7.2n for troff. For nroff, this value should always be
46 an integer multiple of unit `n' to get consistent indentation.
47 -rLL=line-length
49 Set line length. If this option is not given, the line length
50 is set to respect any value set by a prior `.ll' request, (which
51 must be in effect when the `.TH' macro is invoked), if this dif‐
52 fers from the built-in default for the formatter; otherwise it
53 defaults to 78n in nroff mode and 6.5i in troff mode.
54 Note that the use of a `.ll' request to initialize the line
56 length is supported for backward compatibility with some ver‐
57 sions of the man program; direct initialization of the `LL' reg‐
58 ister should always be preferred to the use of such a request.
59 In particular, note that a `.ll 65n' request does not preserve
60 the normal nroff default line length, (the man default initial‐
61 ization to 78n prevails), whereas, the `-rLL=65n' option, or an
62 equivalent `.nr LL 65n' request preceding the use of the `TH'
63 macro, does set a line length of 65n.
64 -rLT=title-length
66 Set title length. If this option is not given, the title length
67 defaults to the line length.
68 -rPnnn Enumeration of pages start with nnn rather than with 1.
70 -rSxx Base document font size is xx points (xx can be 10, 11, or 12)
72 rather than 10 points.
73 -rSN=width
75 Set sub-subheading indentation to width. The default is 3n.
76 -rXnnn After page nnn, number pages as nnna, nnnb, nnnc, etc. For
78 example, the option `-rX2' produces the following page numbers:
79 1, 2, 2a, 2b, 2c, etc.
80
82 This section describes the available macros for manual pages. For fur‐
83 ther customization, put additional macros and requests into the file
84 man.local which is loaded immediately after the man package.
85 .TH title section [extra1] [extra2] [extra3]
87 Set the title of the man page to title and the section to sec‐
88 tion, which must take on a value between 1 and 8. The value
89 section may also have a string appended, e.g. `.pm', to indicate
90 a specific subsection of the man pages. Both title and section
91 are positioned at the left and right in the header line (with
92 section in parentheses immediately appended to title. extra1 is
93 positioned in the middle of the footer line. extra2 is posi‐
94 tioned at the left in the footer line (or at the left on even
95 pages and at the right on odd pages if double-sided printing is
96 active). extra3 is centered in the header line.
97 For HTML output, headers and footers are completely suppressed.
99 Additionally, this macro starts a new page; the new line number
101 is 1 again (except if the `-rC1' option is given on the command
102 line) -- this feature is intended only for formatting multiple
103 man pages; a single man page should contain exactly one TH macro
104 at the beginning of the file.
105 .SH [text for a heading]
107 Set up an unnumbered section heading sticking out to the left.
108 Prints out all the text following SH up to the end of the line
109 (or the text in the next input line if there is no argument to
110 SH) in bold face (or the font specified by the string HF), one
111 size larger than the base document size. Additionally, the left
112 margin and the indentation for the following text is reset to
113 the default values.
114 .SS [text for a heading]
116 Set up a secondary, unnumbered section heading. Prints out all
117 the text following SS up to the end of the line (or the text in
118 the next input line if there is no argument to SS) in bold face
119 (or the font specified by the string HF), at the same size as
120 the base document size. Additionally, the left margin and the
121 indentation for the following text is reset to the default val‐
122 ues.
123 .TP [nnn]
125 Set up an indented paragraph with label. The indentation is set
126 to nnn if that argument is supplied (the default unit is `n' if
127 omitted), otherwise it is set to the previous indentation value
128 specified with TP, IP, or HP (or to the default value if none of
129 them have been used yet).
130 The first input line of text following this macro is interpreted
132 as a string to be printed flush-left, as it is appropriate for a
133 label. It is not interpreted as part of a paragraph, so there
134 is no attempt to fill the first line with text from the follow‐
135 ing input lines. Nevertheless, if the label is not as wide as
136 the indentation the paragraph starts at the same line (but
137 indented), continuing on the following lines. If the label is
138 wider than the indentation the descriptive part of the paragraph
139 begins on the line following the label, entirely indented. Note
140 that neither font shape nor font size of the label is set to a
141 default value; on the other hand, the rest of the text has
142 default font settings.
143 The TP macro is the macro used for the explanations you are just
145 reading.
146 .TQ The TQ macro sets up header continuation for a .TP macro. With
148 it, you can stack up any number of labels (such as in a glos‐
149 sary, or list of commands) before beginning the indented para‐
150 graph. For an example, look just past the next paragraph.
151 This macro is not defined on legacy Unix systems running classic
153 troff. To be certain your page will be portable to those sys‐
154 tems, copy its definition from the an-ext.tmac file of a groff
155 installation.
156 .LP
158 .PP
159 .P These macros are mutual aliases. Any of them causes a line
160 break at the current position, followed by a vertical space
161 downwards by the amount specified by the PD macro. The font
162 size and shape are reset to the default value (normally 10pt
163 Roman). Finally, the current left margin and the indentation
164 are restored.
165 .IP [designator] [nnn]
167 Set up an indented paragraph, using designator as a tag to mark
168 its beginning. The indentation is set to nnn if that argument
169 is supplied (the default unit is `n' if omitted), otherwise it
170 is set to the previous indentation value specified with TP, IP,
171 or HP (or to the default value if none of them have been used
172 yet). Font size and face of the paragraph (but not the designa‐
173 tor) are reset to its default values.
174 To start an indented paragraph with a particular indentation but
176 without a designator, use `""' (two doublequotes) as the second
177 argument.
178 For example, the following paragraphs were all set up with bul‐
180 lets as the designator, using `.IP \(bu 4'. The whole block has
181 been enclosed with `.RS' and `.RE' to set the left margin tempo‐
182 rarily to the current indentation value.
183 · IP is one of the three macros used in the man package to
185 format lists.
186 · HP is another. This macro produces a paragraph with a left
188 hanging indentation.
189 · TP is another. This macro produces an unindented label fol‐
191 lowed by an indented paragraph.
192 .HP [nnn]
194 Set up a paragraph with hanging left indentation. The indenta‐
195 tion is set to nnn if that argument is supplied (the default
196 unit is `n' if omitted), otherwise it is set to the previous
197 indentation value specified with TP, IP, or HP (or to the
198 default value if none of them have been used yet). Font size
199 and face are reset to its default values. The following para‐
200 graph illustrates the effect of this macro with hanging indenta‐
201 tion set to 4 (enclosed by .RS and .RE to set the left margin
202 temporarily to the current indentation):
203 This is a paragraph following an invocation of the HP macro. As
205 you can see, it produces a paragraph where all lines but the
206 first are indented.
207 Use of this presentation-level macro is deprecated. While it is
209 universally portable to legacy Unix systems, a hanging indenta‐
210 tion cannot be expressed naturally under HTML, and many HTML-
211 based manual viewers simply interpret it as a starter for a nor‐
212 mal paragraph. Thus, any information or distinction you tried
213 to express with the indentation may be lost.
214 .RS [nnn]
216 This macro moves the left margin to the right by the value nnn
217 if specified (default unit is `n'); otherwise it is set to the
218 previous indentation value specified with TP, IP, or HP (or to
219 the default value if none of them have been used yet). The
220 indentation value is then set to the default.
221 Calls to the RS macro can be nested.
223 .RE [nnn]
225 This macro moves the left margin back to level nnn, restoring
226 the previous left margin. If no argument is given, it moves one
227 level back. The first level (i.e., no call to RS yet) has num‐
228 ber 1, and each call to RS increases the level by 1.
229 .EX
231 .EE Example/End Example. After EX, filling is disabled and the font
232 is set to constant-width. This is useful for formatting code,
233 command, and configuration-file examples. The EE macro restores
234 the previous font.
235 These macros are defined on many (but not all) legacy Unix sys‐
237 tems running classic troff. To be certain your page will be
238 portable to those systems, copy their definitions from the
239 an-ext.tmac file of a groff installation.
240 To summarize, the following macros cause a line break with the inser‐
242 tion of vertical space (which amount can be changed with the PD macro):
243 SH, SS, TP, TQ, LP (PP, P), IP, and HP. The macros RS, RE, EX, and EE
244 also cause a break but no insertion of vertical space.
245
247 The standard font is Roman; the default text size is 10 point.
248 .SM [text]
250 Causes the text on the same line or the text on the next input
251 line to appear in a font that is one point size smaller than the
252 default font.
253 .SB [text]
255 Causes the text on the same line or the text on the next input
256 line to appear in boldface font, one point size smaller than the
257 default font.
258 .BI text
260 Causes text on the same line to appear alternately in bold face
261 and italic. The text must be on the same line as the macro
262 call. Thus
263 .BI this "word and" that
265 would cause `this' and `that' to appear in bold face, while
267 `word and' appears in italics.
268 .IB text
270 Causes text to appear alternately in italic and bold face. The
271 text must be on the same line as the macro call.
272 .RI text
274 Causes text on the same line to appear alternately in roman and
275 italic. The text must be on the same line as the macro call.
276 .IR text
278 Causes text on the same line to appear alternately in italic and
279 roman. The text must be on the same line as the macro call.
280 .BR text
282 Causes text on the same line to appear alternately in bold face
283 and roman. The text must be on the same line as the macro call.
284 .RB text
286 Causes text on the same line to appear alternately in roman and
287 bold face. The text must be on the same line as the macro call.
288 .B [text]
290 Causes text to appear in bold face. If no text is present on
291 the line where the macro is called the text of the next input
292 line appears in bold face.
293 .I [text]
295 Causes text to appear in italic. If no text is present on the
296 line where the macro is called the text of the next input line
297 appears in italic.
298
300 The following macros are not defined on legacy Unix systems running
301 classic troff. To be certain your page will be portable to those sys‐
302 tems, copy their definitions from the an-ext.tmac file of a groff
303 installation.
304 Using these macros helps ensure that you get hyperlinks when your man‐
306 ual page is rendered in a browser or other program that is Web-enabled.
307 .UR URL
309 .UE [punctuation]
310 Wrap a World Wide Web hyperlink. The argument to UR is the URL;
311 thereafter, lines until UE are collected and used as the link
312 text. Any argument to the UE macro is pasted to the end of the
313 text. On a device that is not a browser,
314 this is a link to
316 .UR http://\:randomsite.org/\:fubar
317 some random site
318 .UE ,
319 given as an example
320 usually displays like this: “this is a link to some random site
322 <http://randomsite.org/fubar>, given as an example”.
323 The use of \: to insert hyphenless breakpoints is a groff exten‐
325 sion and can be omitted.
326 .MT address
328 .ME [punctuation]
329 Wrap an email address. The argument of MT is the address; text
330 following, until ME, is a name to be associated with the
331 address. Any argument to the ME macro is pasted to the end of
332 the link text. On a device that is not a browser,
333 contact
335 .UR fred.foonly@\:fubar.net
336 Fred Foonly
337 .UE
338 for more information
339 usually displays like this: “contact Fred Foonly <fred.foonly@
341 fubar.net> for more information”.
342 The use of \: to insert hyphenless breakpoints is a groff exten‐
344 sion and can be omitted.
345
347 The following macros are not defined on legacy Unix systems running
348 classic troff. To be certain your page will be portable to those sys‐
349 tems, copy their definitions from the an-ext.tmac file of a groff
350 installation.
351 These macros are a convenience for authors. They also assist automated
353 translation tools and help browsers in recognizing command synopses and
354 treating them differently from running text.
355 .SY command
357 Begin synopsis. Takes a single argument, the name of a command.
358 Text following, until closed by YS, is set with a hanging inden‐
359 tation with the width of command plus a space. This produces
360 the traditional look of a Unix command synopsis.
361 .OP key value
363 Describe an optional command argument. The arguments of this
364 macro are set surrounded by option braces in the default Roman
365 font; the first argument is printed with a bold face, while the
366 second argument is typeset as italic.
367 .YS This macro restores normal indentation at the end of a command
369 synopsis.
370 Here is a real example:
372 .SY groff
374 .OP \-abcegiklpstzCEGNRSUVXZ
375 .OP \-d cs
376 .OP \-f fam
377 .OP \-F dir
378 .OP \-I dir
379 .OP \-K arg
380 .OP \-L arg
381 .OP \-m name
382 .OP \-M dir
383 .OP \-n num
384 .OP \-o list
385 .OP \-P arg
386 .OP \-r cn
387 .OP \-T dev
388 .OP \-w name
389 .OP \-W name
390 .RI [ file
391 .IR .\|.\|. ]
392 .YS
393 produces the following output:
395 groff [-abcegiklpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir]
397 [-I dir] [-K arg] [-L arg] [-m name] [-M dir] [-n num]
398 [-o list] [-P arg] [-r cn] [-T dev] [-w name] [-W name]
399 [file ...]
400 If necessary, you might use br requests to control line breaking. You
402 can insert plain text as well; this looks like the traditional (unorna‐
403 mented) syntax for a required command argument or filename.
404
406 The default indentation is 7.2n in troff mode and 7n in nroff mode
407 except for grohtml which ignores indentation.
408 .DT Set tabs every 0.5 inches. Since this macro is always called
410 during a TH request, it makes sense to call it only if the tab
411 positions have been changed.
412 Use of this presentation-level macro is deprecated. It trans‐
414 lates poorly to HTML, under which exact whitespace control and
415 tabbing are not readily available. Thus, information or dis‐
416 tinctions that you use DT to express are likely to be lost. If
417 you feel tempted to use it, you should probably be composing a
418 table using tbl(@MAN1DIR@) markup instead.
419 .PD [nnn]
421 Adjust the empty space before a new paragraph or section. The
422 optional argument gives the amount of space (default unit is
423 `v'); without parameter, the value is reset to its default value
424 (1 line in nroff mode, 0.4v otherwise). This affects the macros
425 SH, SS, TP, LP (resp. PP and P), IP, and HP.
426 Use of this presentation-level macro is deprecated. It trans‐
428 lates poorly to HTML, under which exact control of inter-para‐
429 graph spacing is not readily available. Thus, information or
430 distinctions that you use PD to express are likely to be lost.
431 .AT [system [release]]
433 Alter the footer for use with AT&T man pages. This command
434 exists only for compatibility; don't use it. See the groff info
435 manual for more.
436 .UC [version]
438 Alter the footer for use with BSD man pages. This command
439 exists only for compatibility; don't use it. See the groff info
440 manual for more.
441 .PT Print the header string. Redefine this macro to get control of
443 the header.
444 .BT Print the footer string. Redefine this macro to get control of
446 the footer.
447 The following strings are defined:
449 \*S Switch back to the default font size.
451 \*R The `registered' sign.
453 \*(Tm The `trademark' sign.
455 \*(lq
457 \*(rq Left and right quote. This is equal to `\(lq' and `\(rq',
458 respectively.
459 \*(HF The typeface used to print headings and subheadings. The
461 default is `B'.
462 If a preprocessor like tbl or eqn is needed, it has become usage to
464 make the first line of the man page look like this:
465 '\" word
467 Note the single space character after the double quote. word consists
469 of letters for the needed preprocessors: `e' for eqn, `r' for refer,
470 and `t' for tbl. Modern implementations of the man program read this
471 first line and automatically call the right preprocessor(s).
472
474 Since the man macros consist of groups of groff requests, one can, in
475 principle, supplement the functionality of the man macros with individ‐
476 ual groff requests where necessary. See the groff info pages for a
477 complete reference of all requests.
478 Note, however, that using raw troff requests is likely to make your
480 page render poorly on the (increasingly common) class of viewers that
481 render it to HTML. Troff requests make implicit assumptions about
482 things like character and page sizes that may break in an HTML environ‐
483 ment; also, many of these viewers don't interpret the full troff vocab‐
484 ulary, a problem which can lead to portions of your text being silently
485 dropped.
486 For portability to modern viewers, it is best to write your page
488 entirely in the requests described on this page. Further, it is best
489 to completely avoid those we have described as `presentation-level'
490 (HP, PD, and DT).
491 The macros we have described as extensions (.EX/.EE, .SY/.OP/.YS,
493 .UR/.UE, and .MT/.ME) should be used with caution, as they may not yet
494 be built in to some viewer that is important to your audience. If in
495 doubt, copy the implementation onto your page.
496
498 man.tmac
499 an.tmac
500 These are wrapper files to call andoc.tmac.
501 andoc.tmac
503 Use this file in case you don't know whether the man macros or
504 the mdoc package should be used. Multiple man pages (in either
505 format) can be handled.
506 an-old.tmac
508 Most man macros are contained in this file.
509 an-ext.tmac
511 The extension macro definitions for .SY, .OP, .YS, .TQ, .EX/.EE,
512 .UR/.UE, and .MT/.ME are contained in this file. It is written
513 in classic troff, and released for free re-use, and not copy‐
514 lefted; manual page authors concerned about portability to
515 legacy Unix systems are encouraged to copy these definitions
516 into their pages, and maintainers of troff or its workalikes are
517 encouraged to re-use them.
518 man.local
520 Local changes and customizations should be put into this file.
521
523 tbl(1), eqn(1), refer(1), man(1), man(7), groff_mdoc(7)
524
526 This manual page was originally written for the Debian GNU/Linux system
527 by Susan G. Kleinmann ⟨sgk@debian.org⟩. It was corrected and updated
528 by Werner Lemberg ⟨wl@gnu.org⟩. The extension macros were documented
529 (and partly designed) by Eric S. Raymond ⟨esr@thyrsus.com⟩; he also
530 wrote the portability advice.
531Groff Version 1.20.1 9 January 2009 GROFF_MAN(7)