1 .\" $Id: man.7,v 1.148 2021/08/05 14:31:14 schwarze Exp $
3 .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2011-2015, 2017-2020 Ingo Schwarze <schwarze@openbsd.org>
5 .\" Copyright (c) 2017 Anthony Bentley <bentley@openbsd.org>
6 .\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org>
8 .\" Permission to use, copy, modify, and distribute this software for any
9 .\" purpose with or without fee is hereby granted, provided that the above
10 .\" copyright notice and this permission notice appear in all copies.
12 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
13 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
14 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
15 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
16 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
17 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
18 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 .Dd $Mdocdate: August 5 2021 $
25 .Nd legacy formatting language for manual pages
29 language was the standard formatting language for
31 manual pages from 1979 to 1989.
32 Do not use it to write new manual pages: it is a purely presentational
33 language and lacks support for semantic markup.
40 document, lines beginning with the control character
44 The first word is the macro name.
45 It usually consists of two capital letters.
46 For a list of portable macros, see
48 The words following the macro name are arguments to the macro.
50 Lines not beginning with the control character are called
52 They provide free-form text to be printed; the formatting of the text
53 depends on the respective processing context:
54 .Bd -literal -offset indent
55 \&.SH Macro lines change control state.
56 Text lines are interpreted within the current state.
59 Many aspects of the basic syntax of the
61 language are based on the
69 manual for details, in particular regarding
70 comments, escape sequences, whitespace, and quoting.
74 document starts with the
76 macro specifying the document's name and section, followed by the
78 section formatted as follows:
79 .Bd -literal -offset indent
80 \&.TH PROGNAME 1 1979-01-10
82 \efBprogname\efR \e(en one line about what it does
85 This overview is sorted such that macros of similar purpose are listed
87 Deprecated and non-portable macros are not included in the overview,
88 but can be found in the alphabetical reference below.
89 .Ss Page header and footer meta-data
90 .Bl -column "RS, RE" description
91 .It Ic TH Ta set the title: Ar name section date Op Ar source Op Ar volume
92 .It Ic AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
93 .It Ic UC Ta display BSD version in the page footer (<= 1 argument)
95 .Ss Sections and paragraphs
96 .Bl -column "RS, RE" description
97 .It Ic SH Ta section header (one line)
98 .It Ic SS Ta subsection header (one line)
99 .It Ic PP Ta start an undecorated paragraph (no arguments)
100 .It Ic RS , RE Ta reset the left margin: Op Ar width
101 .It Ic IP Ta indented paragraph: Op Ar head Op Ar width
102 .It Ic TP Ta tagged paragraph: Op Ar width
103 .It Ic PD Ta set vertical paragraph distance: Op Ar height
104 .It Ic in Ta additional indent: Op Ar width
107 .Bl -column "RS, RE" description
108 .It Ic B Ta boldface font
109 .It Ic I Ta italic font
110 .It Ic SB Ta small boldface font
111 .It Ic SM Ta small roman font
112 .It Ic BI Ta alternate between boldface and italic fonts
113 .It Ic BR Ta alternate between boldface and roman fonts
114 .It Ic IB Ta alternate between italic and boldface fonts
115 .It Ic IR Ta alternate between italic and roman fonts
116 .It Ic RB Ta alternate between roman and boldface fonts
117 .It Ic RI Ta alternate between roman and italic fonts
120 This section is a canonical reference to all macros, arranged
122 For the scoping of individual macros, see
126 Sets the volume for the footer for compatibility with man pages from
129 The optional arguments specify which release it is from.
130 This macro is an extension that first appeared in
133 Text is rendered in bold face.
135 Text is rendered alternately in bold face and italic.
137 .Sq .BI this word and that
142 to render in bold face, while
147 Whitespace between arguments is omitted in output.
151 .Dl \&.BI bold italic bold italic
153 Text is rendered alternately in bold face and roman (the default font).
154 Whitespace between arguments is omitted in output.
158 Restore the default tabulator positions.
159 They are at intervals of 0.5 inches.
160 This has no effect unless the tabulator positions were changed with the
165 This is a non-standard Version 9
167 extension later adopted by GNU.
170 it does the same as the
173 request (switch to fill mode).
175 This is a non-standard Version 9
177 extension later adopted by GNU.
180 it does the same as the
183 request (switch to no-fill mode).
185 Begin a paragraph whose initial output line is left-justified, but
186 subsequent output lines are indented, with the following syntax:
188 .D1 Pf . Ic HP Op Ar width
195 If specified, it's saved for later paragraph left margins;
196 if unspecified, the saved or default width is used.
198 This macro is portable, but deprecated
199 because it has no good representation in HTML output,
200 usually ending up indistinguishable from
203 Text is rendered in italics.
205 Text is rendered alternately in italics and bold face.
206 Whitespace between arguments is omitted in output.
210 Begin an indented paragraph with the following syntax:
212 .D1 Pf . Ic IP Op Ar head Op Ar width
218 scaling width defining the left margin.
219 It's saved for later paragraph left-margins; if unspecified, the saved or
220 default width is used.
224 argument is used as a leading term, flushed to the left margin.
225 This is useful for bulleted paragraphs and so on.
227 Text is rendered alternately in italics and roman (the default font).
228 Whitespace between arguments is omitted in output.
235 End a mailto block started with
237 This is a non-standard GNU extension.
239 Begin a mailto block.
240 This is a non-standard GNU extension.
241 It has the following syntax:
242 .Bd -unfilled -offset indent
243 .Pf . Ic MT Ar address
244 link description to be shown
248 Optional command-line argument.
249 This is a non-standard DWB extension.
250 It has the following syntax:
252 .D1 Pf . Ic OP Ar key Op Ar value
256 is usually a command-line flag and
264 extension later adopted by
267 Specify the vertical space to be inserted before each new paragraph.
269 The syntax is as follows:
271 .D1 Pf . Ic PD Op Ar height
280 If the unit is omitted,
284 This macro affects the spacing before any subsequent instances of
296 Begin an undecorated paragraph.
297 The scope of a paragraph is closed by a subsequent paragraph,
298 sub-section, section, or end of file.
299 The saved paragraph left-margin width is reset to the default.
301 Text is rendered alternately in roman (the default font) and bold face.
302 Whitespace between arguments is omitted in output.
306 Explicitly close out the scope of a prior
308 The default left margin is restored to the state before that
312 The syntax is as follows:
314 .D1 Pf . Ic RE Op Ar level
316 Without an argument, the most recent
323 blocks are closed out.
330 Text is rendered alternately in roman (the default font) and italics.
331 Whitespace between arguments is omitted in output.
335 Temporarily reset the default left margin.
336 This has the following syntax:
338 .D1 Pf . Ic RS Op Ar width
345 If not specified, the saved or default width is used.
350 Text is rendered in small size (one point smaller than the default font)
352 This macro is an extension that probably first appeared in SunOS 4.0
353 and was later adopted by GNU and by
357 The scope of a section is only closed by another section or the end of
359 The paragraph left-margin width is reset to the default.
361 Text is rendered in small size (one point smaller than the default
365 The scope of a sub-section is closed by a subsequent sub-section,
366 section, or end of file.
367 The paragraph left-margin width is reset to the default.
369 Begin a synopsis block with the following syntax:
370 .Bd -unfilled -offset indent
371 .Pf . Ic SY Ar command
376 This is a non-standard GNU extension
377 and very rarely used even in GNU manual pages.
378 Formatting is similar to
381 Set the name of the manual page for use in the page header
382 and footer with the following syntax:
384 .D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume
386 Conventionally, the document
388 is given in all caps.
391 is usually a single digit, in a few cases followed by a letter.
396 as specified in the ISO-8601 standard;
397 if the argument does not conform, it is printed verbatim.
400 is empty or not specified, the current date is used.
403 string specifies the organisation providing the utility.
411 string replaces the default volume title of the
416 .Dl \&.TH CVS 5 "1992-02-12" GNU
418 Begin a paragraph where the head, if exceeding the indentation width, is
419 followed by a newline; if not, the body follows on the same line after
420 advancing to the indentation width.
421 Subsequent output lines are indented.
422 The syntax is as follows:
423 .Bd -unfilled -offset indent
424 .Pf . Ic TP Op Ar width
425 .Ar head No \e" one line
434 If specified, it's saved for later paragraph left-margins; if
435 unspecified, the saved or default width is used.
439 except that no vertical spacing is inserted before the paragraph.
440 This is a non-standard GNU extension
441 and very rarely used even in GNU manual pages.
443 Sets the volume for the footer for compatibility with man pages from
446 The optional first argument specifies which release it is from.
447 This macro is an extension that first appeared in
450 End a uniform resource identifier block started with
452 This is a non-standard GNU extension.
454 Begin a uniform resource identifier block.
455 This is a non-standard GNU extension.
456 It has the following syntax:
457 .Bd -unfilled -offset indent
459 link description to be shown
463 End a synopsis block started with
465 This is a non-standard GNU extension.
467 Indent relative to the current indentation:
469 .D1 Pf . Ic in Op Ar width
473 is signed, the new offset is relative.
474 Otherwise, it is absolute.
475 This value is reset upon the next paragraph, section, or sub-section.
480 macros are classified by scope: line scope or block scope.
481 Line macros are only scoped to the current line (and, in some
482 situations, the subsequent line).
483 Block macros are scoped to the current line and subsequent lines until
484 closed by another block macro.
486 Line macros are generally scoped to the current line, with the body
487 consisting of zero or more arguments.
488 If a macro is scoped to the next line and the line arguments are empty,
489 the next line, which must be text, is used instead.
491 .Bd -literal -offset indent
498 If next-line macros are invoked consecutively, only the last is used.
499 If a next-line macro is followed by a non-next-line macro, an error is
502 The syntax is as follows:
503 .Bd -literal -offset indent
504 \&.YO \(lBbody...\(rB
507 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
508 .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
509 .It Ic AT Ta <=1 Ta current Ta \&
510 .It Ic B Ta n Ta next-line Ta \&
511 .It Ic BI Ta n Ta current Ta \&
512 .It Ic BR Ta n Ta current Ta \&
513 .It Ic DT Ta 0 Ta current Ta \&
514 .It Ic EE Ta 0 Ta current Ta Version 9 At
515 .It Ic EX Ta 0 Ta current Ta Version 9 At
516 .It Ic I Ta n Ta next-line Ta \&
517 .It Ic IB Ta n Ta current Ta \&
518 .It Ic IR Ta n Ta current Ta \&
519 .It Ic OP Ta >=1 Ta current Ta DWB
520 .It Ic PD Ta 1 Ta current Ta \&
521 .It Ic RB Ta n Ta current Ta \&
522 .It Ic RI Ta n Ta current Ta \&
523 .It Ic SB Ta n Ta next-line Ta \&
524 .It Ic SM Ta n Ta next-line Ta \&
525 .It Ic TH Ta >1, <6 Ta current Ta \&
526 .It Ic UC Ta <=1 Ta current Ta \&
527 .It Ic in Ta 1 Ta current Ta Xr roff 7
530 Block macros comprise a head and body.
531 As with in-line macros, the head is scoped to the current line and, in
532 one circumstance, the next line (the next-line stipulations as in
536 The syntax is as follows:
537 .Bd -literal -offset indent
538 \&.YO \(lBhead...\(rB
543 The closure of body scope may be to the section, where a macro is closed
546 sub-section, closed by a section or
548 or paragraph, closed by a section, sub-section,
558 No closure refers to an explicit block closing macro.
560 As a rule, block macros may not be nested; thus, calling a block macro
561 while another block macro scope is open, and the open scope is not
562 implicitly closed, is syntactically incorrect.
563 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
564 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
565 .It Ic HP Ta <2 Ta current Ta paragraph Ta \&
566 .It Ic IP Ta <3 Ta current Ta paragraph Ta \&
567 .It Ic LP Ta 0 Ta current Ta paragraph Ta \&
568 .It Ic ME Ta 0 Ta none Ta none Ta GNU
569 .It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU
570 .It Ic P Ta 0 Ta current Ta paragraph Ta \&
571 .It Ic PP Ta 0 Ta current Ta paragraph Ta \&
572 .It Ic RE Ta <=1 Ta current Ta none Ta \&
573 .It Ic RS Ta 1 Ta current Ta to \&RE Ta \&
574 .It Ic SH Ta >0 Ta next-line Ta section Ta \&
575 .It Ic SS Ta >0 Ta next-line Ta sub-section Ta \&
576 .It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU
577 .It Ic TP Ta n Ta next-line Ta paragraph Ta \&
578 .It Ic TQ Ta n Ta next-line Ta paragraph Ta GNU
579 .It Ic UE Ta 0 Ta current Ta none Ta GNU
580 .It Ic UR Ta 1 Ta current Ta part Ta GNU
581 .It Ic YS Ta 0 Ta none Ta none Ta GNU
584 If a block macro is next-line scoped, it may only be followed by in-line
585 macros for decorating text.
594 font escape sequences can be used to choose fonts.
595 In text lines, the effect of manual font selection by escape sequences
596 only lasts until the next macro invocation; in macro lines, it only lasts
597 until the end of the macro scope.
598 Note that macros like
600 open and close a font scope for each argument.
612 language first appeared as a macro package for the roff typesetting
616 The stand-alone implementation that is part of the
618 utility first appeared in
622 .An Douglas McIlroy Aq Mt m.douglas.mcilroy@dartmouth.edu
623 designed and implemented the original version of these macros,
624 wrote the original version of this manual page,
625 and was the first to use them when he edited volume 1 of the
630 later rewrote the macros for groff.
631 .An Eric S. Raymond Aq Mt esr@thyrsus.com
633 .An Werner Lemberg Aq Mt wl@gnu.org
636 macros to groff in 2007.
642 reference were written by
643 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blob