1GROFF_MAN(7)           Miscellaneous Information Manual           GROFF_MAN(7)
2
3
4

NAME

6       groff_man - groff man macros to support generation of man pages
7

SYNOPSIS

9       groff -man [options ...] [files ...]
10       groff -m man [options ...] [files ...]
11

DESCRIPTION

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

OPTIONS

18       The  man  macros  understand  the following command line options (which
19       define various registers).
20
21       -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
25       -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
28       -rD1   Double-sided  printing.  Footers for even and odd pages are for‐
29              matted differently.
30
31       -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
36       -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
43       -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
48       -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
55              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
65       -rLT=title-length
66              Set title length.  If this option is not given, the title length
67              defaults to the line length.
68
69       -rPnnn Enumeration of pages start with nnn rather than with 1.
70
71       -rSxx  Base  document  font size is xx points (xx can be 10, 11, or 12)
72              rather than 10 points.
73
74       -rSN=width
75              Set sub-subheading indentation to width.  The default is 3n.
76
77       -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

USAGE

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
86       .EX
87       .EE    Example/End Example.  After .EX, filling  is  disabled  and  the
88              font  is  set  to constant-width.  This is useful for formatting
89              code, command, and configuration-file examples.   The  EE  macro
90              restores filling and restores the previous font.
91
92              These  macros are defined on many (but not all) legacy Unix sys‐
93              tems running classic troff.  To be certain  your  page  will  be
94              portable  to  those  systems,  copy  their  definitions from the
95              an-ext.tmac file of a groff installation.
96
97       .HP [nnn]
98              Set up a paragraph with hanging left indentation.  The  indenta‐
99              tion  is  set  to  nnn if that argument is supplied (the default
100              unit is ‘n’ if omitted), otherwise it is  set  to  the  previous
101              indentation  value  specified  with  .TP, .IP, or .HP (or to the
102              default value if none of them have been used  yet).   Font  size
103              and  face  are reset to its default values.  The following para‐
104              graph illustrates the effect of this macro with hanging indenta‐
105              tion  set  to  4 (enclosed by .RS and .RE to set the left margin
106              temporarily to the current indentation):
107
108              This is a paragraph following an invocation of the HP macro.  As
109                  you can see, it produces a paragraph where all lines but the
110                  first are indented.
111
112              Use of this presentation-level macro is deprecated.  While it is
113              universally  portable to legacy Unix systems, a hanging indenta‐
114              tion cannot be expressed naturally under HTML,  and  many  HTML-
115              based manual viewers simply interpret it as a starter for a nor‐
116              mal paragraph.  Thus, any information or distinction  you  tried
117              to express with the indentation may be lost.
118
119       .IP [designator] [nnn]
120              Set  up an indented paragraph, using designator as a tag to mark
121              its beginning.  The indentation is set to nnn if  that  argument
122              is  supplied  (the default unit is ‘n’ if omitted), otherwise it
123              is set to the previous indentation  value  specified  with  .TP,
124              .IP,  or  .HP (or to the default value if none of them have been
125              used yet).  Font size and face of the  paragraph  (but  not  the
126              designator) are reset to its default values.
127
128              To start an indented paragraph with a particular indentation but
129              without a designator, use ‘""’ (two doublequotes) as the  second
130              argument.
131
132              For  example, the following paragraphs were all set up with bul‐
133              lets as the designator, using ‘.IP \(bu 4’.  The whole block has
134              been  enclosed with .RS and .RE to set the left margin temporar‐
135              ily to the current indentation value.
136
137              ·   IP is one of the three macros used in  the  man  package  to
138                  format lists.
139
140              ·   HP  is another.  This macro produces a paragraph with a left
141                  hanging indentation.
142
143              ·   TP is another.  This macro produces an unindented label fol‐
144                  lowed by an indented paragraph.
145
146       .LP
147       .PP
148       .P     These  macros  are  mutual  aliases.   Any of them causes a line
149              break at the current position,  followed  by  a  vertical  space
150              downwards  by  the  amount  specified by the PD macro.  The font
151              size and shape are reset to the  default  value  (normally  10pt
152              Roman).  Finally, the current left margin and the indentation is
153              reset to the default values.
154
155       .RE [nnn]
156              This macro moves the left margin back to  level  nnn,  restoring
157              the previous left margin.  If no argument is given, it moves one
158              level back.  The first level (i.e., no call to .RS yet) has num‐
159              ber 1, and each call to .RS increases the level by 1.
160
161       .RS [nnn]
162              This  macro  moves the left margin to the right by the value nnn
163              if specified (default unit is ‘n’); otherwise it is set  to  the
164              previous  indentation  value specified with .TP, .IP, or .HP (or
165              to the default value if none of them have been used  yet).   The
166              indentation value is then set to the default.
167
168              Calls to the RS macro can be nested.
169
170       .SH [text for a heading]
171              Set  up  an unnumbered section heading sticking out to the left.
172              Prints out all the text following .SH up to the end of the  line
173              (or  the  text in the next input line if there is no argument to
174              .SH) in bold face (or the font specified by the string HF),  one
175              size larger than the base document size.  Additionally, the left
176              margin and the indentation for the following text  is  reset  to
177              the default values.
178
179       .SS [text for a heading]
180              Set  up a secondary, unnumbered section heading.  Prints out all
181              the text following .SS up to the end of the line (or the text in
182              the next input line if there is no argument to .SS) in bold face
183              (or the font specified by the string HF), at the  same  size  as
184              the  base  document size.  Additionally, the left margin and the
185              indentation for the following text is reset to the default  val‐
186              ues.
187
188       .TH title section [extra1] [extra2] [extra3]
189              Set  the  title of the man page to title and the section to sec‐
190              tion, which must take on a value between 1  and  8.   The  value
191              section may also have a string appended, e.g. ‘.pm’, to indicate
192              a specific subsection of the man pages.  Both title and  section
193              are  positioned  at  the left and right in the header line (with
194              section in parentheses immediately appended to title.  extra1 is
195              positioned  in  the  middle of the footer line.  extra2 is posi‐
196              tioned at the left in the footer line (or at the  left  on  even
197              pages  and at the right on odd pages if double-sided printing is
198              active).  extra3 is centered in the header line.
199
200              For HTML output, headers and footers are completely suppressed.
201
202              Additionally, this macro starts a new page; the new line  number
203              is  1 again (except if the ‘-rC1’ option is given on the command
204              line) -- this feature is intended only for  formatting  multiple
205              man pages; a single man page should contain exactly one TH macro
206              at the beginning of the file.
207
208       .TP [nnn]
209              Set up an indented paragraph with label.  The indentation is set
210              to  nnn if that argument is supplied (the default unit is ‘n’ if
211              omitted), otherwise it is set to the previous indentation  value
212              specified with .TP, .IP, or .HP (or to the default value if none
213              of them have been used yet).
214
215              The first input line of text following this macro is interpreted
216              as a string to be printed flush-left, as it is appropriate for a
217              label.  It is not interpreted as part of a paragraph,  so  there
218              is  no attempt to fill the first line with text from the follow‐
219              ing input lines.  Nevertheless, if the label is not as  wide  as
220              the  indentation  the  paragraph  starts  at  the same line (but
221              indented), continuing on the following lines.  If the  label  is
222              wider than the indentation the descriptive part of the paragraph
223              begins on the line following the label, entirely indented.  Note
224              that  neither  font shape nor font size of the label is set to a
225              default value; on the other hand,  the  rest  of  the  text  has
226              default font settings.
227
228              The TP macro is the macro used for the explanations you are just
229              reading.
230
231       .TQ    The TQ macro sets up header continuation for a TP  macro.   With
232              it,  you  can  stack up any number of labels (such as in a glos‐
233              sary, or list of commands) before beginning the  indented  para‐
234              graph.  For an example, look up the documentation of the LP, PP,
235              and P macros.
236
237              This macro is not defined on legacy Unix systems running classic
238              troff.   To  be certain your page will be portable to those sys‐
239              tems, copy its definition from the an-ext.tmac file of  a  groff
240              installation.
241
242       To  summarize,  the following macros cause a line break with the inser‐
243       tion of vertical space (which amount can be changed with the PD macro):
244       SH,  SS, TP, TQ, LP (PP, P), IP, and HP.  The macros RS, RE, EX, and EE
245       also cause a break but no insertion of vertical space.
246

MACROS TO SET FONTS

248       The standard font is Roman; the default text size is 10 point.
249
250       .B [text]
251              Causes text to appear in bold face.  If no text  is  present  on
252              the  line  where  the macro is called the text of the next input
253              line appears in bold face.
254
255       .BI text
256              Causes text on the same line to appear alternately in bold  face
257              and  italic.   The  text  must  be on the same line as the macro
258              call.  Thus
259
260                     .BI this "word and" that
261
262              would cause ‘this’ and ‘that’ to  appear  in  bold  face,  while
263              ‘word and’ appears in italics.
264
265       .BR text
266              Causes  text on the same line to appear alternately in bold face
267              and roman.  The text must be on the same line as the macro call.
268
269       .I [text]
270              Causes text to appear in italic.  If no text is present  on  the
271              line  where  the macro is called the text of the next input line
272              appears in italic.
273
274       .IB text
275              Causes text to appear alternately in italic and bold face.   The
276              text must be on the same line as the macro call.
277
278       .IR text
279              Causes text on the same line to appear alternately in italic and
280              roman.  The text must be on the same line as the macro call.
281
282       .RB text
283              Causes text on the same line to appear alternately in roman  and
284              bold face.  The text must be on the same line as the macro call.
285
286       .RI text
287              Causes  text on the same line to appear alternately in roman and
288              italic.  The text must be on the same line as the macro call.
289
290       .SB [text]
291              Causes the text on the same line or the text on the  next  input
292              line to appear in boldface font, one point size smaller than the
293              default font.
294
295       .SM [text]
296              Causes the text on the same line or the text on the  next  input
297              line to appear in a font that is one point size smaller than the
298              default font.
299
301       The following macros are not defined on  legacy  Unix  systems  running
302       classic  troff.  To be certain your page will be portable to those sys‐
303       tems, copy their definitions from  the  an-ext.tmac  file  of  a  groff
304       installation.
305
306       Using  these macros helps ensure that you get hyperlinks when your man‐
307       ual page is rendered in a browser or other program that is Web-enabled.
308
309       .MT address
310       .ME [punctuation]
311              Wrap an email address.  The argument of .MT is the address; text
312              following,  until  .ME,  is  a  name  to  be associated with the
313              address.  Any argument to the ME macro is pasted to the  end  of
314              the link text.  On a device that is not a browser,
315
316                     contact
317                     .MT fred.foonly@\:fubar.net
318                     Fred Foonly
319                     .ME
320                     for more information
321
322              usually  displays  like this: “contact Fred Foonly <fred.foonly@
323              fubar.net> for more information”.
324
325              The use of \: to insert hyphenless breakpoints is a groff exten‐
326              sion and can be omitted.
327
328       .UR URL
329       .UE [punctuation]
330              Wrap  a  World  Wide  Web hyperlink.  The argument to .UR is the
331              URL; thereafter, lines until .UE are collected and used  as  the
332              link text.  Any argument to the UE macro is pasted to the end of
333              the text.  On a device that is not a browser,
334
335                     this is a link to
336                     .UR http://\:randomsite.org/\:fubar
337                     some random site
338                     .UE ,
339                     given as an example
340
341              usually displays like this: “this is a link to some random  site
342              <http://randomsite.org/fubar>, given as an example”.
343
344              The use of \: to insert hyphenless breakpoints is a groff exten‐
345              sion and can be omitted.
346

MACROS TO DESCRIBE COMMAND SYNOPSES

348       The following macros are not defined on  legacy  Unix  systems  running
349       classic  troff.  To be certain your page will be portable to those sys‐
350       tems, copy their definitions from  the  an-ext.tmac  file  of  a  groff
351       installation.
352
353       These macros are a convenience for authors.  They also assist automated
354       translation tools and help browsers in recognizing command synopses and
355       treating them differently from running text.
356
357       .OP key value
358              Describe  an  optional  command argument.  The arguments of this
359              macro are set surrounded by option braces in the  default  Roman
360              font;  the first argument is printed with a bold face, while the
361              second argument is typeset as italic.
362
363       .SY command
364              Begin synopsis.  Takes a single argument, the name of a command.
365              Text  following,  until  closed  by  .YS,  is set with a hanging
366              indentation with the width of command plus a space.   This  pro‐
367              duces the traditional look of a Unix command synopsis.
368
369       .YS    This  macro  restores normal indentation at the end of a command
370              synopsis.
371
372       Here is a real example:
373
374              .SY groff
375              .OP \-abcegiklpstzCEGNRSUVXZ
376              .OP \-d cs
377              .OP \-f fam
378              .OP \-F dir
379              .OP \-I dir
380              .OP \-K arg
381              .OP \-L arg
382              .OP \-m name
383              .OP \-M dir
384              .OP \-n num
385              .OP \-o list
386              .OP \-P arg
387              .OP \-r cn
388              .OP \-T dev
389              .OP \-w name
390              .OP \-W name
391              .RI [ file
392              .IR .\|.\|. ]
393              .YS
394
395       produces the following output:
396
397              groff [-abcegiklpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir]
398                    [-I dir] [-K arg] [-L arg] [-m name] [-M dir] [-n num]
399                    [-o list] [-P arg] [-r cn] [-T dev] [-w name] [-W name]
400                    [file ...]
401
402       If  necessary, you might use br requests to control line breaking.  You
403       can insert plain text as well; this looks like the traditional (unorna‐
404       mented) syntax for a required command argument or filename.
405

MISCELLANEOUS

407       The  default  indentation  is  7.2n  in troff mode and 7n in nroff mode
408       except for grohtml, which ignores indentation.
409
410       .AT [system [release]]
411              Alter the footer for use with  AT&T  man  pages.   This  command
412              exists only for compatibility; don't use it.  See the groff info
413              manual for more.
414
415       .BT    Print the footer string.  Redefine this macro to get control  of
416              the footer.
417
418       .DT    Set  tabs  every  0.5 inches.  Since this macro is always called
419              during a TH macro, it makes sense to call it  only  if  the  tab
420              positions have been changed.
421
422              Use  of  this presentation-level macro is deprecated.  It trans‐
423              lates poorly to HTML, under which exact whitespace  control  and
424              tabbing  are  not  readily available.  Thus, information or dis‐
425              tinctions that you use .DT to express are likely to be lost.  If
426              you  feel  tempted to use it, you should probably be composing a
427              table using tbl(1) markup instead.
428
429       .PD [nnn]
430              Adjust the empty space before a new paragraph or  section.   The
431              optional  argument  gives  the  amount of space (default unit is
432              ‘v’); without parameter, the value is reset to its default value
433              (1 line in nroff mode, 0.4v otherwise).  This affects the macros
434              SH, SS, TP, LP (resp. PP and P), IP, and HP.
435
436              Use of this presentation-level macro is deprecated.   It  trans‐
437              lates  poorly  to HTML, under which exact control of inter-para‐
438              graph spacing is not readily available.   Thus,  information  or
439              distinctions that you use .PD to express are likely to be lost.
440
441       .PT    Print  the header string.  Redefine this macro to get control of
442              the header.
443
444       .UC [version]
445              Alter the footer for use  with  BSD  man  pages.   This  command
446              exists only for compatibility; don't use it.  See the groff info
447              manual for more.
448
449       The following strings are defined:
450
451       \*R    The ‘registered’ sign.
452
453       \*S    Switch back to the default font size.
454
455       \*(lq
456       \*(rq  Left and right quote.  This is equal to ‘\(lq’  and  ‘\(rq\[cq],
457              respectively.
458
459       \*(HF  The  typeface  used  to  print  headings  and  subheadings.  The
460              default is ‘B’.
461
462       \*(Tm  The ‘trademark’ sign.
463
464       If a preprocessor like tbl or eqn is needed, it has  become  common  to
465       make the first line of the man page look like this:
466
467              '\" word
468
469       Note  the single space character after the double quote.  word consists
470       of letters for the needed preprocessors: ‘e’ for eqn,  ‘r’  for  refer,
471       and  ‘t’  for tbl.  Modern implementations of the man program read this
472       first line and automatically call the right preprocessor(s).
473

PORTABILITY AND TROFF REQUESTS

475       Since the man macros consist of groups of groff requests, one  can,  in
476       principle, supplement the functionality of the man macros with individ‐
477       ual groff requests where necessary.  See the groff  info  pages  for  a
478       complete reference of all requests.
479
480       Note,  however,  that  using  raw troff requests is likely to make your
481       page render poorly on the (increasingly common) class of  viewers  that
482       render  it  to  HTML.   Troff  requests make implicit assumptions about
483       things like character and page sizes that may break in an HTML environ‐
484       ment; also, many of these viewers don't interpret the full troff vocab‐
485       ulary, a problem that can lead to portions of your text being  silently
486       dropped.
487
488       For  portability  to  modern  viewers,  it  is  best to write your page
489       entirely in the requests described on this page.  Further, it  is  best
490       to  completely  avoid  those  we have described as ‘presentation-level’
491       (.HP, .PD, and .DT).
492
493       The macros we  have  described  as  extensions  (.EX/.EE,  .SY/.OP/.YS,
494       .UR/.UE,  and .MT/.ME) should be used with caution, as they may not yet
495       be built in to some viewer that is important to your audience.   If  in
496       doubt, copy the implementation onto your page.
497

FILES

499       man.tmac
500       an.tmac
501              These are wrapper files to call andoc.tmac.
502
503       andoc.tmac
504              Use  this  file in case you don't know whether the man macros or
505              the mdoc package should be used.  Multiple man pages (in  either
506              format) can be handled.
507
508       an-old.tmac
509              Most man macros are contained in this file.
510
511       an-ext.tmac
512              The extension macro definitions for .SY, .OP, .YS, .TQ, .EX/.EE,
513              .UR/.UE, and .MT/.ME are contained in this file.  It is  written
514              in  classic  troff,  and released for free re-use, and not copy‐
515              lefted; manual  page  authors  concerned  about  portability  to
516              legacy  Unix  systems  are  encouraged to copy these definitions
517              into their pages, and maintainers of troff or its workalikes are
518              encouraged to re-use them.
519
520              Note  that  the  definitions for these macros are read after the
521              call of TH, so they will replace macros of the same names  given
522              at the beginning of your file.  If you must use your own defini‐
523              tions for these macros, they must be given after calling TH.
524
525       man.local
526              Local changes and customizations should be put into this file.
527

SEE ALSO

529       tbl(1), eqn(1), refer(1), man(1), man(7), groff_mdoc(7)
530

COPYING

532       Copyright © 1999-2014 Free Software Foundation, Inc.
533
534       Permission is granted to make and distribute verbatim copies of this
535       manual provided the copyright notice and this permission notice are
536       preserved on all copies.
537
538       Permission is granted to copy and distribute modified versions of this
539       manual under the conditions for verbatim copying, provided that the
540       entire resulting derived work is distributed under the terms of a per‐
541       mission notice identical to this one.
542
543       Permission is granted to copy and distribute translations of this man‐
544       ual into another language, under the above conditions for modified ver‐
545       sions, except that this permission notice may be included in transla‐
546       tions approved by the Free Software Foundation instead of in the origi‐
547       nal English.
548

AUTHORS

550       This manual page was originally written for the Debian GNU/Linux system
551       by Susan G. Kleinmann ⟨sgk@debian.org⟩.
552
553       It was corrected and updated by Werner Lemberg ⟨wl@gnu.org⟩.
554
555       The extension macros were documented (and partly designed) by Eric S.
556       Raymond ⟨esr@thyrsus.com⟩; he also wrote the portability advice.
557
558
559
560Groff Version 1.22.3            4 November 2014                   GROFF_MAN(7)
Impressum