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

NAME

6       groff_man - GNU roff macro package for formatting man pages
7

SYNOPSIS

9       groff -man [option ...] [input-file ...]
10       groff -m man [option ...] [input-file ...]
11

DESCRIPTION

13       The  man  macro  package  for  groff  is  used  to produce manual pages
14       (“man pages”) like the one you are reading.  GNU roff's  implementation
15       was written by James Clark.
16
17       This  document  presents  the  macros thematically to aid learners; for
18       those needing only a quick reference, the following  table  lists  them
19       alphabetically, with cross-references to appropriate subsections below.
20
21       Macro   Meaning                         Subsection
22       ───────────────────────────────────────────────────────────────────
23       .B      Bold                            Font style macros
24       .BI     Bold, italic alternating        Font style macros
25       .BR     Bold, roman alternating         Font style macros
26       .EE     Example end                     Document structure macros
27       .EX     Example begin                   Document structure macros
28       .I      Italic                          Font style macros
29       .IB     Italic, bold alternating        Font style macros
30       .IP     Indented paragraph              Paragraph macros
31       .IR     Italic, roman alternating       Font style macros
32       .LP     (Left) paragraph                Paragraph macros
33       .ME     Mail-to end                     Hyperlink and email macros
34       .MT     Mail-to start                   Hyperlink and email macros
35       .OP     (Command-line) option           Command synopsis macros
36       .P      Paragraph                       Paragraph macros
37       .PP     Paragraph                       Paragraph macros
38       .RB     Roman, bold alternating         Font style macros
39       .RE     Relative-indent end             Document structure macros
40       .RI     Roman, italic alternating       Font style macros
41       .RS     Relative-indent start           Document structure macros
42       .SB     Small bold                      Font style macros
43       .SH     Section heading                 Document structure macros
44       .SM     Small                           Font style macros
45       .SS     Subection heading               Document structure macros
46       .SY     Synopsis start                  Command synopsis macros
47       .TH     Title heading                   Document structure macros
48       .TP     Tagged paragraph                Paragraph macros
49       .TQ     Tagged paragraph continuation   Paragraph macros
50       .UE     URL end                         Hyperlink and email macros
51       .UR     URL start                       Hyperlink and email macros
52       .YS     Synopsis end                    Command synopsis macros
53
54       Macros  whose use we discourage (.AT, .BT, .DT, .HP, .PD, .PT, and .UC)
55       are described in subsection “Deprecated features”, below.
56
57   Macro reference preliminaries
58       Each macro is described in a tagged paragraph.  Closely related macros,
59       such as .EX and .EE, are grouped together.
60
61       Optional  macro arguments are indicated by surrounding them with square
62       brackets.  If a macro accepts multiple arguments, arguments  containing
63       whitespace  must  be  double-quoted ("one two"), to be interpreted cor‐
64       rectly.  Most macro arguments are strings that will be output as  text;
65       exceptions are noted.
66
67       Bear in mind that groff is fundamentally a programming system for type‐
68       setting.  Consequently, the verb “to set” is frequently used  below  in
69       the sense “to typeset”.
70
71   Document structure macros
72       The  highest  level of organization of a man page is determined by this
73       group of macros.  .TH (title heading) identifies the document as a  man
74       page  and  defines  information  enabling its indexing by mandb(8) or a
75       similar tool.  Sections (.SH), one of which is mandatory  and  many  of
76       which  are standardized, facilitate quick location of relevant material
77       by the reader and aid the man page writer to discuss all essential  as‐
78       pects of the topic.  Subsections (.SS) are optional and permit sections
79       that grow long to develop in a controlled way.  Many technical  discus‐
80       sions  require examples; lengthy ones, especially those reflecting mul‐
81       tiple lines of input to or output from the system, are usefully  brack‐
82       eted by .EX and .EE.  When none of the foregoing meets a structural de‐
83       mand, a section of the discussion can be manually indented  within  .RS
84       and .RE macros.
85
86       .TH title section [footer-middle] [footer-outside] [header-middle]
87              Define  the  title  of  the man page as title and the section as
88              section.  See man(1) for details on the section numbers and suf‐
89              fixes  applicable  to  your system.  title and section are posi‐
90              tioned together at the left and right in the header  line  (with
91              section  in parentheses immediately appended to title).  footer-
92              middle is centered in the footer line.  footer-outside is  posi‐
93              tioned  at  the  left in the footer line (or at the left on even
94              pages and at the right on odd pages if double-sided printing  is
95              active).  header-middle is centered in the header line.  If sec‐
96              tion is a simple integer between 1 and 9 (inclusive), or is  ex‐
97              actly “3p”, there is no need to specify header-middle; the macro
98              package will supply text for it.
99
100              For HTML output, headers and footers are completely suppressed.
101
102              Additionally, this macro starts a new page; the page  number  is
103              reset  to  1  (unless  the  -rC1  option is given on the command
104              line).  This feature is intended only  for  formatting  multiple
105              man pages.
106
107              A  man  page  should contain exactly one .TH call at or near the
108              beginning of the file, prior to any other macro calls.
109
110              By convention, footer-middle is  the  most  recent  modification
111              date  of the man page source document, and footer-outside is the
112              name and version or release of the project providing it.
113
114       .SH [heading-text]
115              Set heading-text as a section heading flush left.  The text fol‐
116              lowing  .SH  up  to the end of the line, or the text on the next
117              input line if .SH is given no arguments, is set in bold (or  the
118              font  specified  by the string register HF) slightly larger than
119              the base font size.  Additionally, the left margin and  indenta‐
120              tion  affecting  subsequent text are reset to their default val‐
121              ues.  Text on input lines after heading-text is set as a  normal
122              paragraph (.PP).
123
124              The  content  of  heading-text and ordering of sections has been
125              standardized by common practice, as has much of  the  layout  of
126              material  within sections.  For example, a section called “Name”
127              or “NAME” must exist, must be the first section  after  the  .TH
128              call, and must contain only a line of the form
129                     page-topic[, ...] \- summary-description
130              for  a man page to be properly indexed.  See man(7) for the con‐
131              ventions prevailing on your system.
132
133       .SS [subheading-text]
134              Set subheading-text as a subsection  heading  indented  (by  de‐
135              fault) partway between a section heading and a normally-indented
136              paragraph (.PP).  The text following .SS up to the  end  of  the
137              line,  or the text on the next input line if .SS is given no ar‐
138              guments, is set in bold (or the font  specified  by  the  string
139              register HF) at the base font size.  Additionally, the left mar‐
140              gin and indentation affecting subsequent text are reset to their
141              default  values.   Text  on input lines after subheading-text is
142              set as a normal paragraph (.PP).
143
144       .EX
145       .EE    Begin and end example.  After .EX, filling and  hyphenation  are
146              disabled  and  a  constant-width  (monospaced) font is selected.
147              Calling .EE enables filling and restores the  previous  hyphena‐
148              tion setting and font.
149
150              Example  regions are useful for formatting code, shell sessions,
151              and text file contents.
152
153              These macros are defined on many (but not all) legacy Unix  sys‐
154              tems  running  classic  troff.   To be certain your page will be
155              portable to those  systems,  copy  their  definitions  from  the
156              an-ext.tmac file of a groff installation.
157
158       .RS [indent]
159              Move the left margin to the right by the value indent, if speci‐
160              fied, and by a default amount otherwise; see  subsection  “Hori‐
161              zontal and vertical spacing” below.  Calls to .RS can be nested;
162              each call increments by 1 the indentation  level  used  by  .RE.
163              The indentation level prior to any .RS calls is 1.
164
165       .RE [level]
166              Move  the  left margin back to that corresponding to indentation
167              level level.  If no argument is given, move the left margin  one
168              level back.
169
170   Paragraph macros
171       A  typical  paragraph (.PP) is set at the current left margin, which by
172       default is indented from the left margin of the output device.  In  man
173       pages  and  other technical literature, definition lists are frequently
174       encountered; these can be set as “tagged  paragraphs”  (.TP  and  .TQ),
175       which have one or more leading tags followed by a paragraph that has an
176       additional left indent.  The indented paragraph (.IP) macro  is  useful
177       to continue the indented content of a narrative started with .TP, or to
178       present an itemized or ordered list.
179
180       .LP
181       .PP
182       .P     Begin a new paragraph; these macros are synonymous.  They  break
183              the  output line at the current position, followed by a vertical
184              space downward by a default amount (which can be changed by  the
185              deprecated .PD macro).  The font size and style are reset to de‐
186              faults; see subsection “Font style macros” below.  Finally,  the
187              left margin and indentation are reset to default values.
188
189       .TP [indent]
190              Set a tagged, indented paragraph.  The input line following this
191              macro, known as the tag, is printed at the current left  margin.
192              Subsequent  text  is  indented by indent, if specified, and by a
193              default amount otherwise; see subsection “Horizontal and  verti‐
194              cal spacing” below.
195
196              If  the  tag  is  not  as wide as the indentation, the paragraph
197              starts on the same line as the tag, at the  applicable  indenta‐
198              tion,  and continues on the following lines.  Otherwise, the de‐
199              scriptive part of the paragraph begins on the line following the
200              tag, entirely indented.  The line containing the tag can include
201              a macro call, for instance to set the tag in bold with .B.
202
203              .TP was used to write the first paragraph of this description of
204              .TP, and .IP the subsequent ones.
205
206       .TQ    Set  an  additional  tag  for  a paragraph tagged with .TP.  The
207              pending output line is broken.  The tag on the input  line  fol‐
208              lowing this macro and subsequent lines are handled as with .TP.
209
210              This macro is not defined on legacy Unix systems running classic
211              troff.  To be certain your page will be portable to  those  sys‐
212              tems,  copy  its definition from the an-ext.tmac file of a groff
213              installation.
214
215              The descriptions of .LP, .PP, and .P above  were  written  using
216              .TP and .TQ.
217
218       .IP [tag] [indent]
219              Set an indented paragraph with an optional tag.  The tag and in‐
220              dent arguments, if present, are handled as with  .TP,  with  the
221              exception  that  the  tag argument to .IP cannot include a macro
222              call.
223
224              Two convenient use cases for .IP are
225
226                     (1) to start a new paragraph with the same indentation as
227                         the previous .IP or .TP paragraph, if no indent argu‐
228                         ment is given; and
229
230                     (2) to set a paragraph with a short tag that is  not  se‐
231                         mantically  important,  such as a bullet (•)—obtained
232                         with the ‘\(bu’ character escape—or list  enumerator,
233                         as seen in this very paragraph.
234
235   Command synopsis macros
236       Command  synopses  are  a  staple  of section 1 and 8 man pages.  These
237       macros aid you to construct one that has the classical Unix appearance.
238       Furthermore, some tools are able to interpret these macros semantically
239       and treat them appropriately for localization and/or  presentation.   A
240       command synopsis is wrapped in .SY/.YS calls, with command-line options
241       of some formats indicated by .OP.
242
243       These macros are not defined on legacy  Unix  systems  running  classic
244       troff.  To be certain your page will be portable to those systems, copy
245       their definitions from the an-ext.tmac file of a groff installation.
246
247       .SY command
248              Begin synopsis.  Hyphenation is turned off.  The  command  argu‐
249              ment  is  set in bold.  The output line is filled as normal, but
250              if a break is required, subsequent output lines are indented  by
251              the width of command plus a space.
252
253       .OP option-name [option-argument]
254              Indicate an optional command parameter called option-name, which
255              is set in bold.  If the option takes an  argument,  specify  op‐
256              tion-argument  using  a  noun,  abbreviation, or hyphenated noun
257              phrase.  If present, option-argument is preceded by a space  and
258              set  in italics.  Square brackets (in roman) surround both argu‐
259              ments.
260
261       .YS    End synopsis.  Restore indentation and hyphenation  to  previous
262              values.
263
264       Multiple  .SY/.YS  blocks can be specified, for instance to distinguish
265       differing modes of operation of a complex  command  like  tar(1);  each
266       will be separated by a paragraph space.
267
268       .SY  can also be repeated multiple times before a closing .YS, which is
269       useful to indicate synonymous ways of invoking a particular mode of op‐
270       eration.
271
272       For example,
273
274              .SY groff
275              .OP \-abcegiklpstzCEGNRSUVXZ
276              .OP \-d cs
277              .OP \-f fam
278              .OP \-F dir
279              .OP \-I dir
280              .OP \-K arg
281              .OP \-L arg
282              .OP \-m name
283              .OP \-M dir
284              .OP \-n num
285              .OP \-o list
286              .OP \-P arg
287              .OP \-r cn
288              .OP \-T dev
289              .OP \-w name
290              .OP \-W name
291              .RI [ file
292              \&.\|.\|.\&]
293              .YS
294              .
295              .SY groff
296              .B \-h
297              .SY groff
298              .B \-\-help
299              .YS
300
301       produces the following output.
302
303              groff [-abcegiklpstzCEGNRSUVXZ] [-d cs] [-f fam] [-F dir]
304                    [-I dir] [-K arg] [-L arg] [-m name] [-M dir] [-n num]
305                    [-o list] [-P arg] [-r cn] [-T dev] [-w name] [-W name]
306                    [file ...]
307
308              groff -h
309              groff --help
310
311       Several features of the above example are of note.
312
313       •      The empty request (.), which does nothing, is used for  vertical
314              spacing  in the input file for readability by the document main‐
315              tainer.  Do not put empty lines in a roff source document.
316
317       •      The command and option names are presented in bold  to  cue  the
318              user that they should be input literally.
319
320       •      Option  dashes are specified with the ‘\-’ escape sequence; this
321              is an important practice to make them clearly visible and to fa‐
322              cilitate  cut-and-paste  from  the  rendered man page to a shell
323              prompt or text file.
324
325       •      Option arguments and command operands are presented  in  italics
326              (underlined on some output devices, such as terminals and emula‐
327              tors), to cue the user that they must be replaced with appropri‐
328              ate text.
329
330       •      Symbols  that  are  neither to be typed literally nor simply re‐
331              placed appear in the roman style; brackets surround optional ar‐
332              guments, and an ellipsis indicates that the previous syntactical
333              element may be repeated arbitrarily.
334
335              Some  man  pages  use  a   brace-and-pipe   notation   such   as
336              “{--diff|--compare}”  to  indicate  that one and only one of the
337              ‘|’-separated items within the braces must be  input.   If  this
338              braced  construct  is furthermore surrounded by square brackets,
339              it means that at most one of the items is accepted.
340
341              Authors of man pages should note the use of the zero-width space
342              escape  sequence  ‘\&’  on both sides of the ellipsis; this is a
343              good practice to avoid surprises in the event the ellipsis  gets
344              refilled  in  your  text editor.  See “Portability”, below.  The
345              morbidly curious may consult groff(7) regarding the narrow-space
346              escape sequence ‘\|’.
347
348   Hyperlink and email macros
349       Email  addresses  are  bracketed  with  .MT/.ME and URL hyperlinks with
350       .UR/.UE.
351
352       These macros are not defined on legacy  Unix  systems  running  classic
353       troff.  To be certain your page will be portable to those systems, copy
354       their definitions from the an-ext.tmac file of a groff installation.
355
356       .MT address
357       .ME [punctuation]
358              Identify address as an RFC 6068 addr-spec for  a  “mailto:”  URI
359              with  the  text between the two macro calls as the link text.  A
360              punctuation argument to .ME is placed at the  end  of  the  link
361              text  without  intervening  space.  Note that address may not be
362              visible in the output text, particularly if the man page is  be‐
363              ing  viewed as HTML.  On a device that is not a browser, address
364              is set in angle brackets after the link text and before punctua‐
365              tion.
366
367              When rendered by groff to a TTY or PostScript output device,
368
369                     Contact
370                     .MT fred.foonly@\:fubar.net
371                     Fred Foonly
372                     .ME
373                     for more information.
374
375              displays  as:  “Contact  Fred Foonly ⟨fred.foonly@fubar.net⟩ for
376              more information.”.
377
378              The use of ‘\:’ to insert hyphenless discretionary breaks  is  a
379              groff extension and can be omitted.
380
381       .UR URL
382       .UE [punctuation]
383              Identify  URL as an RFC 3986 URI hyperlink with the text between
384              the two macro calls as the link text.  A punctuation argument to
385              .UE  is  placed  at the end of the link text without intervening
386              space.  Note that URL may not be visible  in  the  output  text,
387              particularly  if the man page is being viewed as HTML.  On a de‐
388              vice that is not a browser, URL is set in angle  brackets  after
389              the link text and before punctuation.
390
391              When rendered by groff to a TTY or PostScript output device,
392
393                     The GNU Project of the Free Software Foundation hosts the
394                     .UR https://\:www.gnu.org/\:software/\:groff/
395                     Groff home page
396                     .UE .
397
398              displays  as:  “The  GNU Project of the Free Software Foundation
399              hosts  the  Groff   home   page   ⟨https://www.gnu.org/software/
400              groff/⟩.”.
401
402              The  use  of ‘\:’ to insert hyphenless discretionary breaks is a
403              groff extension and can be omitted.
404
405   Font style macros
406       The man macro package is limited in its font styling options,  offering
407       only  bold  (.B), italic (.I), and roman (the default).  Italic text is
408       usually set underscored instead on terminals and other classical nroff-
409       style  output  devices.   The  .SM  and .SB macros set text in roman or
410       bold, respectively, at a smaller point size; these differ visually from
411       regular-sized  roman  or  bold text only on troff-style output devices.
412       The foregoing macros cause word breaks before  and  after  their  argu‐
413       ments,  but it is often necessary to set text in different styles with‐
414       out intervening whitespace.  The macros .BI, .BR, .IB,  .IR,  .RB,  and
415       .RI,  where ‘B’, ‘I’, and ‘R’ indicate bold, italic, and roman, respec‐
416       tively, set their  odd-  and  even-numbered  arguments  in  alternating
417       styles, with no whitespace separating them.
418
419       Because  font styles are presentational rather than semantic, conflict‐
420       ing traditions have arisen regarding which font styles should  be  used
421       to  mark  file  or path names, environment variables, in-line literals,
422       and even man page cross-references.
423
424       The default font size and family (for troff output devices) is 10-point
425       Times.  The default style is roman.
426
427       .B [text]
428              Set  text in bold.  If the macro is given no arguments, the text
429              of the next input line is set in bold.
430
431              Use bold for literal portions of syntax synopses,  for  command-
432              line  options  in  running text, and for literals that are major
433              topics of the subject under discussion; for example,  this  page
434              uses  bold for macro and register names.  In .EX/.EE examples of
435              interactive I/O (such as a shell session), set  only  the  user-
436              typed input in bold.
437
438       .I [text]
439              Set  text  in  italics.  If the macro is given no arguments, the
440              text of the next input line is set in italics.
441
442              Use italics for file and path names, for environment  variables,
443              for  enumeration  or  preprocessor  constants in C, for variable
444              (user-determined) portions of syntax synopses, for the first oc‐
445              currence only of a technical concept being introduced, for names
446              of works of software (including commands and functions, but  ex‐
447              cluding  names  of operating systems or their kernels), and any‐
448              where a parameter requiring replacement by the user  is  encoun‐
449              tered.  An exception involves variable text in a context that is
450              already marked up in italics, such as file or  path  names  with
451              variable  components;  in  such  cases, follow the convention of
452              mathematical typography: set the file or path name in italics as
453              usual  (see .IR below), but use roman for the variable part, and
454              italics again in running roman text when referring to the  vari‐
455              able material.
456
457       .SM [text]
458              Set  text  one point size smaller than the default size.  If the
459              macro is given no arguments, the text of the next input line  is
460              set smaller.
461
462              Note: nroff-style output devices, such as terminals, will render
463              text at the normal font size instead.  Do not rely upon  .SM  to
464              communicate semantic information distinct from using roman style
465              at the normal size; it will be hidden from  readers  using  such
466              devices.
467
468       .SB [text]
469              Set  text in bold, one point size smaller than the default size.
470              If the macro is given no arguments, the text of the  next  input
471              line is set smaller and in bold.
472
473              Note: nroff-style output devices, such as terminals, will render
474              text in bold at the normal font size instead.  Do not rely  upon
475              .SB to communicate semantic information distinct from using bold
476              style at the normal size; it will be hidden from  readers  using
477              such devices.
478
479       Note  what is not prescribed for setting in bold or italics above: ele‐
480       ments of “synopsis language” such as ellipses and brackets  around  op‐
481       tions; proper names and adjectives; titles of anything other than works
482       of literature or software; identifiers for standards documents or tech‐
483       nical   reports   such   as  CSTR  #54,  RFC  1918,  Unicode  11.0,  or
484       POSIX.1-2017; acronyms; and occurrences after the first of a  technical
485       term  or  piece  of  jargon.  Again, the names of operating systems and
486       their kernels are, by practically universal convention, set in roman.
487
488       Be frugal with the use of italics for emphasis, and  particularly  with
489       the use of bold.  Brief runs of literal text, such as references to in‐
490       dividual characters or short strings, including section and  subsection
491       headings  of  man  pages,  are  suitable objects for quotation; see the
492       ‘\(lq’, ‘\(rq’, ‘\(oq’, and ‘\(cq’ escapes in subsection  “Portability”
493       below.
494
495       Unlike  the  above font style macros, the font alternation macros below
496       accept only arguments on the same line as the macro  call.   If  white‐
497       space  is  required within one of the arguments, first consider whether
498       the same result could be achieved with as much  clarity  by  using  the
499       single-style  macros  on separate input lines.  When it cannot, double-
500       quote an argument with one or more embedded space characters.   Setting
501       all   three  different  styles  within  one  whitespace-delimited  word
502       presents challenges; it is possible with the ‘\c’ and/or ‘\f’  escapes,
503       but see subsection “Portability” below for caveats.
504
505       .BI bold-text italic-text ...
506              Set each argument in bold and italics, alternately.
507
508                     .BI \-r name = n
509
510       .BR bold-text roman-text ...
511              Set each argument in bold and roman, alternately.
512
513                     Any such change becomes effective with the first use of
514                     .BR .NH ,
515                     .I after
516                     the new alias is defined.
517
518       .IB italic-text bold-text ...
519              Set each argument in italics and bold, alternately.
520
521                     All macro package files must be named
522                     .IB name .tmac
523                     to fully use the
524                     .I tmac
525                     mechanism.
526
527       .IR italic-text roman-text ...
528              Set each argument in italics and roman, alternately.
529
530                     This is the first command of the
531                     .IR prologue .
532
533       .RB roman-text bold-text ...
534              Set each argument in roman and bold, alternately.
535
536                     Also, the statement
537                     .RB \(oq "delim on" \(cq
538                     is not handled specially.
539
540       .RI roman-text italic-text ...
541              Set each argument in roman and italics, alternately.
542
543                     .RI [ file
544                     \&.\|.\|.\&]
545
546   Horizontal and vertical spacing
547       The  indent  argument accepted by .RS, .IP, .TP, and the deprecated .HP
548       is a number plus an optional scaling indicator.  If no scaling  indica‐
549       tor is given, the man package assumes ‘n’; that is, the width of a let‐
550       ter “n” in the font current when the macro is called.  See section “Nu‐
551       merical Expressions” in groff(7) for further details.  An indent speci‐
552       fied in a call to .IP, .TP, or the deprecated .HP  persists  until  (1)
553       another  of these macros is called with an explicit indent argument, or
554       (2) .SH, .SS, or .PP or its synonyms is called; these clear the  indent
555       entirely.
556
557       Indents  set  by  .RS  move the left margin and persist until .RS, .RE,
558       .SH, or .SS is called.  The default indentation, exhibited by  ordinary
559       .PP  paragraphs not within an .RS/.RE relative indent, is 7.2n in troff
560       mode and 7n in nroff mode.  The HTML output device is an exception;  it
561       ignores  indentation  completely.   This same indentation is used again
562       (additively) for the defaults of .IP, .TP, .RS, and the deprecated .HP.
563       Section headings (.SH) are set flush with the left margin of the output
564       device, and subsection headings (.SS) are indented 3n.
565
566       Resist the temptation to mock up tabular or  multi-column  output  with
567       ASCII  tab characters or the indentation arguments to .IP, .TP, .RS, or
568       the deprecated .HP; the result may not render comprehensibly on an out‐
569       put device you fail to check, or which is developed in the future.  The
570       table preprocessor tbl(1) can likely meet your needs.
571
572       The following macros cause a line break with the insertion of  vertical
573       space:  .SH, .SS, .TP, .TQ, .PP (and its synonyms), .IP, and the depre‐
574       cated .HP.  The default inter-section and  inter-paragraph  spacing  is
575       1  line  in  nroff mode, and 0.4v in troff mode.  (The deprecated macro
576       .PD can change this vertical spacing, but its use is discouraged.)  The
577       macros  .RS,  .RE,  .EX, and .EE also cause a break but no insertion of
578       vertical space.
579
580   Number registers
581       Number registers are described in section “Options” below.
582
583   String registers
584       The following strings are defined.
585
586       \*R    expands to the character escape for the “registered sign” glyph,
587              ‘\(rg’, if available, and “(Reg.)” otherwise.
588
589       \*S    expands  to  an escape setting the font size to the document de‐
590              fault.
591
592       \*(HF  expands to the font identifier used to print headings  and  sub‐
593              headings.  The default is ‘B’.
594
595       \*(lq
596       \*(rq  expand to the character escapes for left and right double-quota‐
597              tion marks, ‘\(lq’ and ‘\(rq’, respectively.
598
599       \*(Tm  expands to the character escape for the “trade mark sign” glyph,
600              ‘\(tm’, if available, and “(TM)” otherwise.
601
602   Interaction with preprocessors
603       When  a  preprocessor like tbl or eqn is needed, a hint can be given to
604       the man page formatter by making the first line of a man page look like
605       this:
606
607              '\" word
608
609       Note that the line starts with an apostrophe ('), not a dot, and that a
610       single space character follows the double quote.  The word consists  of
611       one  letter  for  each needed preprocessor: ‘e’ for eqn, ‘r’ for refer,
612       and ‘t’ for tbl.  Modern implementations of the man  program  interpret
613       this first line and automatically call the right preprocessor(s).
614
615       The  usual  tbl  and  eqn macros for table and equation inclusion, .TS,
616       .T&, .TE, .EQ, and .EN, may be used freely.  Note that nroff output de‐
617       vices are extremely limited in presentation of mathematical equations.
618
619   Portability
620       The two major syntactical categories of roff languages are requests and
621       escapes.  Since the man macros are implemented in terms  of  groff  re‐
622       quests and escapes, one can, in principle, supplement the functionality
623       of man with these lower-level elements where necessary.
624
625       Note, however, that using raw groff requests is  likely  to  make  your
626       page  render  poorly on the class of viewers that transform it to HTML.
627       Some requests make implicit assumptions about things like character and
628       page  sizes  that  may  not  hold in an HTML environment; also, many of
629       these viewers don't interpret the full groff vocabulary, a problem that
630       can lead to portions of your text being silently dropped.
631
632       For  portability  to  modern viewers, it is best to write your page en‐
633       tirely with the macros described in this  page  (except  for  the  ones
634       identified as deprecated, which should be avoided).  The macros we have
635       described as extensions (.EX/.EE, .SY/.OP/.YS,  .UR/.UE,  and  .MT/.ME)
636       should  be  used  with caution, as they may not yet be built in to some
637       viewer that is important to your audience.  If in doubt, copy  the  im‐
638       plementation  into your page—after the .TH call and the “Name” section,
639       to accommodate timid mandb implementations.
640
641       Similar caveats apply to escapes.  Some escape  sequences  are  however
642       required  for  correct typesetting even in man pages and usually do not
643       cause portability problems:
644
645       \"     Comment.  Everything after the double-quote to the  end  of  the
646              input  line  is  ignored.   Whole-line  comments  are frequently
647              placed immediately after the empty request ‘.’.
648
649       \newline
650              Join the next input line to the current one.  Except for the up‐
651              date of the input line counter (used for diagnostic messages and
652              related purposes), a series of lines ending in backslash-newline
653              is  transparent  to groff.  Use this escape to break excessively
654              input long lines for document maintenance.
655
656       \~     Adjustable, non-breaking space character.  Use  this  escape  to
657              prevent  a  break  inside  a short phrase or between a numerical
658              quantity and its corresponding unit(s).
659
660                     Before starting the motor, set the output speed to\~1.
661                     There are 1,024\~bytes in 1\~kiB.
662                     CSTR\~#8 documents the B language.
663
664       \&     Zero-width space.  Append to an input line to prevent an end-of-
665              sentence  punctuation sequence from being recognized as such, or
666              insert at the beginning of an input line to  prevent  a  dot  or
667              apostrophe from being interpreted as the beginning of a roff re‐
668              quest.
669
670       \(aq   ASCII apostrophe.  Use for syntax elements of  programming  lan‐
671              guages because some output devices might replace unescaped apos‐
672              trophes with right single quotation marks.
673
674       \(oq   Opening single quotation mark.
675       \(cq   Closing single quotation mark.
676
677              Use these for paired directional single quotes, ‘like this’.
678
679       \(dq   ASCII double-quote.  Sometimes needed after macro calls to  pre‐
680              vent  the  interpretation  of the ASCII quotation mark character
681              ‘"’ as the beginning or end of a macro argument.
682
683       \(lq   Left double quotation mark.
684       \(rq   Right double quotation mark.
685
686              Use these for paired directional double quotes, “like this”.
687
688       \(em   Em-dash.  Use for an interruption in  a  sentence—such  as  this
689              one.
690
691       \(en   En-dash.  Use to separate the two ends of a range, in particular
692              between numbers, for example: the digits 1–9.
693
694       \(ga   ASCII grave accent.  Use for syntax elements of programming lan‐
695              guages,  for  example  shell command substitutions, because some
696              output devices might replace unescaped grave accents  with  left
697              single quotation marks.
698
699       \(ha   ASCII circumflex accent.  Use for syntax elements of programming
700              languages because some output devices  might  replace  unescaped
701              circumflex accents with non-ASCII glyphs like the Unicode U+02C6
702              modifier letter circumflex.
703
704       \(ti   ASCII tilde.  Use for syntax elements of  programming  languages
705              because  some output devices might replace unescaped tildes with
706              non-ASCII glyphs like the Unicode U+02DC small tilde.
707
708       \-     Minus sign.  Also use this to display syntax elements  that  re‐
709              quire the ASCII hyphen-minus character, for example command-line
710              options and C language operators.  The unescaped ‘-’ input char‐
711              acter  is  not appropriate for these cases because it may render
712              as a hyphen on some output devices.
713
714       \c     If this escape sequence occurs at the end of an input  line,  no
715              white  space  is  inserted  between the last glyph on it and the
716              first glyph resulting from the next input line.  This  is  occa‐
717              sionally  useful when three different fonts are needed in a sin‐
718              gle word.
719
720                     Normally, the final output file should be named
721                     .IB file .pdf\c
722                     \&.
723
724              Note that when using this trick with the .BI or .RI macros,  you
725              will  need  to manually add an italic correction escape ‘\/’ be‐
726              fore the ‘\c’ due to way macros expand their arguments.
727
728                     Files processed with
729                     .B groff \-mom
730                     (or
731                     .BI "\-m " mom\/\c
732                     ) produce PostScript output by default.
733
734              Alternatively, and perhaps with  better  portability,  the  ‘\f’
735              font  escape sequence can be used; see below.  Using ‘\c’ to in‐
736              clude the output from more than one input line  into  the  next-
737              line  argument of a .TP macro will render incorrectly with groff
738              1.22.3, mandoc 1.14.1, older versions  of  these  programs,  and
739              perhaps with some other formatters.
740
741       \e     Widely  used in man pages to represent a backslash output glyph.
742              It works reliably as long as the .ec request is not used,  which
743              should never happen in man pages, and it is slightly more porta‐
744              ble than the more exact ‘\(rs’ (“reverse  solidus”)  escape  se‐
745              quence.
746
747       \fB, \fI, \fR, \fP
748              Switch to bold, italic, roman, or back to the previous font, re‐
749              spectively.  Either these or ‘\c’ is needed when three different
750              fonts are required in a single whitespace-delimited word.
751
752                     .RB [ \-\-reference\-dictionary=\fI\,name\/\fP ]
753
754                     .RB [ \-\-reference\-dictionary=\c
755                     .IR name ]
756
757              Font escapes may be more portable than ‘\c’.  As shown above, it
758              is up to you to account for italic  corrections  with  ‘\/’  and
759              ‘\,’,  which  are themselves groff extensions, if desired and if
760              supported by your implementation.
761
762              Note that ‘\fP’ reliably returns to the style in use immediately
763              preceding  the previous ‘\f’ escape only if no sectioning, para‐
764              graph, or font face macro calls have intervened.
765
766              As long as only two fonts are needed in any  single  whitespace-
767              delimited  word, font alternation macros like .BI usually result
768              in more readable source code than ‘\f’ escapes do.
769
770       For maximum portability, escape sequences and  special  characters  not
771       listed above are better avoided in man pages.
772
773   Deprecated features
774       Use of the following is discouraged.
775
776       .AT [system [release]]
777              Alter  the  footer  for  use with AT&T man pages, overriding any
778              definition of the footer-outside argument to  .TH.   This  macro
779              exists only for compatibility; don't use it.
780
781              The first argument system can be:
782
783                     3      7th edition (default)
784
785                     4      System III
786
787                     5      System V
788
789              The  optional second argument release specifies the release num‐
790              ber, such as in “System V Release 3”.
791
792       .BT    Set the page footer.  Redefine this macro to get control of  the
793              footer.
794
795       .DT    Set  tabs  every  0.5 inches.  Since this macro is always called
796              during a .TH macro, it makes sense to call it only  if  the  tab
797              positions have been changed.
798
799              Use  of  this presentation-level macro is deprecated.  It trans‐
800              lates poorly to HTML, under which exact whitespace  control  and
801              tabbing  are  not  readily available.  Thus, information or dis‐
802              tinctions that you use .DT to express are likely to be lost.  If
803              you  feel  tempted to use it, you should probably be composing a
804              table using tbl(1) markup instead.
805
806       .HP [indent]
807              Set up a paragraph with a hanging left indentation.  The  indent
808              argument, if present, is handled as with .TP.
809
810              Use of this presentation-level macro is deprecated.  While it is
811              universally portable to legacy Unix systems, a hanging  indenta‐
812              tion  cannot  be  expressed naturally under HTML, and many HTML-
813              based manual viewers simply interpret it as a starter for a nor‐
814              mal  paragraph.   Thus, any information or distinction you tried
815              to express with the indentation may be lost.
816
817       .PD [vertical-space]
818              Define the vertical space between paragraphs  or  (sub)sections.
819              The  optional  argument  vertical-space  specifies the amount of
820              space; the default scaling is ‘v’).  Without  an  argument,  the
821              spacing  is reset to its default value; see “Horizontal and ver‐
822              tical spacing” above.
823
824              Use of this presentation-level macro is deprecated.   It  trans‐
825              lates  poorly  to HTML, under which exact control of inter-para‐
826              graph spacing is not readily available.   Thus,  information  or
827              distinctions that you use .PD to express are likely to be lost.
828
829       .PT    Set  the page header.  Redefine this macro to get control of the
830              header.
831
832       .UC [version]
833              Alter the footer for use with BSD man pages, overriding any def‐
834              inition  of  the footer-outside argument to .TH.  This macro ex‐
835              ists only for compatibility; don't use it.
836
837              The argument version can be:
838
839                     3      3rd Berkeley Distribution (default)
840
841                     4      4th Berkeley Distribution
842
843                     5      4.2 Berkeley Distribution
844
845                     6      4.3 Berkeley Distribution
846
847                     7      4.4 Berkeley Distribution
848
849   History
850       According to its own man(7) page, Version 7 Unix (1979)  supported  all
851       of  the macros described in this page not listed as GNU extensions, ex‐
852       cept .P, .SB, .SS, and the deprecated .AT, .BT, .PT, and .UC.  The only
853       string  registers  defined were R and S; no number registers were docu‐
854       mented.
855

OPTIONS

857       The following groff options set number registers recognized and used by
858       the man macro package.
859
860       -rcR=1 Continuous  rendering.   Create a single, very long page instead
861              of multiple pages.  This is the  default  in  nroff  mode.   Use
862              -rcR=0 to disable it.
863
864       -rC1   Number  pages  continuously.  If more than one man page is given
865              on the command line, number the pages continuously, rather  than
866              starting each at 1.
867
868       -rD1   Enable  double-sided  printing.   Footers for even and odd pages
869              are formatted differently; see the description of .TH in  “Docu‐
870              ment structure macros”, above.
871
872       -rFT=footer-distance
873              Set  distance  of the footer, relative to the bottom of the page
874              if negative or relative to the top if positive,  to  footer-dis‐
875              tance.  The default is -0.5i.
876
877       -rHY=flags
878              Set  hyphenation  flags.   Permissible values of flags are docu‐
879              mented in section “Hyphenation” of groff(7).  The default  is  4
880              if  continuous rendering is enabled (-rcR=1 above), and 6 other‐
881              wise.
882
883       -rIN=indent
884              Set the body text indentation (for normal paragraphs) to indent.
885              See  “Horizontal and vertical spacing” above for the default in‐
886              dentation value.  For nroff, indent should always be an  integer
887              multiple of unit ‘n’ to get consistent indentation.
888
889       -rLL=line-length
890              Set  line  length.  If this option is not given, the line length
891              is set to respect any value set by a prior “.ll” request  (which
892              must  be  in effect when the .TH macro is invoked), if this dif‐
893              fers from the built-in default for the formatter;  otherwise  it
894              defaults to 78n in nroff mode and 6.5i in troff mode.
895
896              Note  that  the  use  of  a “.ll” request to initialize the line
897              length is supported for backward compatibility  with  some  ver‐
898              sions of the man program; direct initialization of the LL regis‐
899              ter should always be preferred to the use of such a request.  In
900              particular,  note that a “.ll 65n” request does not preserve the
901              normal nroff default line length (the man default initialization
902              to  78n prevails), whereas the -rLL=65n option, or an equivalent
903              “.nr LL 65n” request preceding the use of the  .TH  macro,  does
904              set a line length of 65n.
905
906       -rLT=title-length
907              Set title length.  If this option is not given, the title length
908              defaults to the line length.
909
910       -rPn   Start enumeration of pages at n rather than 1.
911
912       -rSpoint-size
913              Use point-size as the base document font size.  Acceptable  val‐
914              ues are 10, 11, or 12.  See subsection “Font style macros” above
915              for the default.
916
917       -rSN=subsection-indent
918              Set subsection indentation to subsection-indent.  See  “Horizon‐
919              tal  and  vertical  spacing”  above  for the default indentation
920              value.
921
922       -rXp   After page p, number pages as pa, pb, pc, and so forth.  For ex‐
923              ample,  the  option -rX2 produces the following page numbers: 1,
924              2, 2a, 2b, 2c, and so on.
925

FILES

927       /usr/share/groff/1.22.4/tmac/man.tmac
928       /usr/share/groff/1.22.4/tmac/an.tmac
929              These are wrapper files to call andoc.tmac.
930
931       /usr/share/groff/1.22.4/tmac/andoc.tmac
932              This brief groff program detects whether the man or  mdoc  macro
933              package  is being used by a document and loads the correct macro
934              definitions, taking advantage of the fact that pages using  them
935              must  call  .TH or .Dd, respectively, as their first macro.  Be‐
936              cause the wrappers above load this file, a man program  or  user
937              typing,  for  example,  “groff -man page.1”, need not know which
938              package the file page.1 uses.  Multiple  man  pages,  in  either
939              format, can be handled.
940
941       /usr/share/groff/1.22.4/tmac/an-old.tmac
942              Most  man  macros are contained in this file.  It also loads the
943              GNU extensions from an-ext.tmac (see below).
944
945       /usr/share/groff/1.22.4/tmac/an-ext.tmac
946              The extension macro definitions for .SY, .OP, .YS, .TQ, .EX/.EE,
947              .UR/.UE,  and .MT/.ME are contained in this file, which is writ‐
948              ten in classic troff and permissively  licensed—not  copylefted.
949              Man page authors concerned about portability to legacy Unix sys‐
950              tems are encouraged to copy these definitions into their  pages,
951              and  maintainers  of troff implementations or work-alike systems
952              that format man pages are encouraged to re-use them.
953
954              Note that the definitions for these macros are  read  after  the
955              call  of  .TH, so they will replace any macros of the same names
956              preceding it in your file.  If you use your own  implementations
957              of  these macros, they must be defined after calling .TH to have
958              any effect.
959
960       /etc/groff/site-tmac/man.local
961              Local changes and customizations should be put into this file.
962

NOTES

964       Some tips on troubleshooting your man pages follow.
965
966.RS doesn't indent relative to my indented paragraph
967              The .RS macro sets the indentation relative to the amount  of  a
968              normal  paragraph  (.PP and its synonyms).  The same default in‐
969              dentation amount is used for .RS, .IP, .TP, and  the  deprecated
970              .HP.   If  you  need  to start an indent relative to an indented
971              paragraph, call .RS repeatedly until an  acceptable  indentation
972              is  achieved,  or  give  .RS  an indentation argument that is at
973              least as much as the paragraph's indentation amount relative  to
974              an  adjacent  .PP paragraph.  See “Horizontal and vertical spac‐
975              ing” above for the values.
976
977.RE doesn't reset the indent to the expected level
978       • warning: scale indicator invalid in this context
979       • warning: number register 'an-saved-marginn' not defined
980       • warning: number register 'an-saved-prevailing-indentn' not defined
981              The .RS macro takes an indentation amount as  an  argument;  the
982              .RE  macro's  argument  is  a specific indentation level.  .RE 1
983              goes to the level before any .RS macros were called, .RE 2  goes
984              to  the  level of the first .RS call you made, and so forth.  If
985              you desire symmetry in your macro calls, simply  issue  one  .RE
986              without an argument for each .RS that precedes it.
987
988              After  calls  to the .SH and .SS sectioning macros, all relative
989              indents are cleared and calls to .RE have no effect.
990

AUTHORS

992       The GNU version of the man macro package was written by James Clark and
993       contributors.  The extension macros were written by Werner Lemberg ⟨wl@
994       gnu.org⟩ and Eric S. Raymond ⟨esr@thyrsus.com⟩.
995
996       This document was originally written for the Debian GNU/Linux system by
997       Susan  G.  Kleinmann ⟨sgk@debian.org⟩.  It was corrected and updated by
998       Werner Lemberg and G. Branden Robinson.  The extension macros were doc‐
999       umented by Eric S. Raymond; he also originated the portability section,
1000       to which Ingo Schwarze contributed most of the material on  escape  se‐
1001       quences.
1002

SEE ALSO

1004       Groff:  The  GNU Implementation of troff, by Trent A. Fisher and Werner
1005       Lemberg, is the main groff documentation.  You can browse  it  interac‐
1006       tively with “info groff”.
1007
1008       tbl(1), eqn(1), and refer(1) are preprocessors used with man pages.
1009
1010       man(1) describes the man page formatter on your system.
1011
1012       groff_mdoc(7)  describes the groff version of the BSD-originated alter‐
1013       native macro package for man pages.
1014
1015       groff(7), groff_char(7), man(7)
1016
1017
1018
1019groff 1.22.4                    19 January 2023                   GROFF_MAN(7)
Impressum