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       .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
98              For HTML output, headers and footers are completely suppressed.
99
100              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
106       .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
115       .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
124       .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
131              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
144              The TP macro is the macro used for the explanations you are just
145              reading.
146
147       .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
152              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
157       .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
166       .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
175              To start an indented paragraph with a particular indentation but
176              without  a designator, use `""' (two doublequotes) as the second
177              argument.
178
179              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
184              ·   IP  is  one  of  the three macros used in the man package to
185                  format lists.
186
187              ·   HP is another.  This macro produces a paragraph with a  left
188                  hanging indentation.
189
190              ·   TP is another.  This macro produces an unindented label fol‐
191                  lowed by an indented paragraph.
192
193       .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
204              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
208              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
215       .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
222              Calls to the RS macro can be nested.
223
224       .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
230       .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
236              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
241       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

MACROS TO SET FONTS

247       The standard font is Roman; the default text size is 10 point.
248
249       .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
254       .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
259       .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
264                     .BI this "word and" that
265
266              would  cause  `this'  and  `that'  to appear in bold face, while
267              `word and' appears in italics.
268
269       .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
273       .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
277       .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
281       .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
285       .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
289       .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
294       .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
305       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
308       .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
315                     this is a link to
316                     .UR http://\:randomsite.org/\:fubar
317                     some random site
318                     .UE ,
319                     given as an example
320
321              usually displays like this: “this is a link to some random  site
322              <http://randomsite.org/fubar>, given as an example”.
323
324              The use of \: to insert hyphenless breakpoints is a groff exten‐
325              sion and can be omitted.
326
327       .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
334                     contact
335                     .UR fred.foonly@\:fubar.net
336                     Fred Foonly
337                     .UE
338                     for more information
339
340              usually  displays  like this: “contact Fred Foonly <fred.foonly@
341              fubar.net> for more information”.
342
343              The use of \: to insert hyphenless breakpoints is a groff exten‐
344              sion and can be omitted.
345

MACROS TO DESCRIBE COMMAND SYNOPSES

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
352       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
356       .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
362       .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
368       .YS    This macro restores normal indentation at the end of  a  command
369              synopsis.
370
371       Here is a real example:
372
373              .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
394       produces the following output:
395
396              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
401       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

MISCELLANEOUS

406       The default indentation is 7.2n in troff mode  and  7n  in  nroff  mode
407       except for grohtml which ignores indentation.
408
409       .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
413              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
420       .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
427              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
432       .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
437       .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
442       .PT    Print  the header string.  Redefine this macro to get control of
443              the header.
444
445       .BT    Print the footer string.  Redefine this macro to get control  of
446              the footer.
447
448       The following strings are defined:
449
450       \*S    Switch back to the default font size.
451
452       \*R    The `registered' sign.
453
454       \*(Tm  The `trademark' sign.
455
456       \*(lq
457       \*(rq  Left  and  right  quote.   This  is  equal to `\(lq' and `\(rq',
458              respectively.
459
460       \*(HF  The typeface  used  to  print  headings  and  subheadings.   The
461              default is `B'.
462
463       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
466              '\" word
467
468       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

PORTABILITY AND TROFF REQUESTS

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
479       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
487       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
492       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

FILES

498       man.tmac
499       an.tmac
500              These are wrapper files to call andoc.tmac.
501
502       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
507       an-old.tmac
508              Most man macros are contained in this file.
509
510       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
519       man.local
520              Local changes and customizations should be put into this file.
521

SEE ALSO

523       tbl(1), eqn(1), refer(1), man(1), man(7), groff_mdoc(7)
524

AUTHORS

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.
531
532
533
534Groff Version 1.20.1            9 January 2009                    GROFF_MAN(7)
Impressum