1 .\" $Id: man.7,v 1.143 2019/03/02 22:04:40 schwarze Exp $
3 .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2011-2015,2017,2018,2019 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: March 2 2019 $
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.
131 Text is rendered in bold face.
133 Text is rendered alternately in bold face and italic.
135 .Sq .BI this word and that
140 to render in bold face, while
145 Whitespace between arguments is omitted in output.
149 .Dl \&.BI bold italic bold italic
151 Text is rendered alternately in bold face and roman (the default font).
152 Whitespace between arguments is omitted in output.
156 Restore the default tabulator positions.
157 They are at intervals of 0.5 inches.
158 This has no effect unless the tabulator positions were changed with the
163 This is a non-standard GNU extension.
166 it does the same as the
169 request (switch to fill mode).
171 This is a non-standard GNU extension.
174 it does the same as the
177 request (switch to no-fill mode).
179 Begin a paragraph whose initial output line is left-justified, but
180 subsequent output lines are indented, with the following syntax:
182 .D1 Pf . Ic HP Op Ar width
189 If specified, it's saved for later paragraph left margins;
190 if unspecified, the saved or default width is used.
192 This macro is portable, but deprecated
193 because it has no good representation in HTML output,
194 usually ending up indistinguishable from
197 Text is rendered in italics.
199 Text is rendered alternately in italics and bold face.
200 Whitespace between arguments is omitted in output.
204 Begin an indented paragraph with the following syntax:
206 .D1 Pf . Ic IP Op Ar head Op Ar width
212 scaling width defining the left margin.
213 It's saved for later paragraph left-margins; if unspecified, the saved or
214 default width is used.
218 argument is used as a leading term, flushed to the left margin.
219 This is useful for bulleted paragraphs and so on.
221 Text is rendered alternately in italics and roman (the default font).
222 Whitespace between arguments is omitted in output.
229 End a mailto block started with
231 This is a non-standard GNU extension.
233 Begin a mailto block.
234 This is a non-standard GNU extension.
235 It has the following syntax:
236 .Bd -unfilled -offset indent
237 .Pf . Ic MT Ar address
238 link description to be shown
242 Optional command-line argument.
243 This is a non-standard GNU extension.
244 It has the following syntax:
246 .D1 Pf . Ic OP Ar key Op Ar value
250 is usually a command-line flag and
257 Specify the vertical space to be inserted before each new paragraph.
259 The syntax is as follows:
261 .D1 Pf . Ic PD Op Ar height
270 If the unit is omitted,
274 This macro affects the spacing before any subsequent instances of
286 Begin an undecorated paragraph.
287 The scope of a paragraph is closed by a subsequent paragraph,
288 sub-section, section, or end of file.
289 The saved paragraph left-margin width is reset to the default.
291 Text is rendered alternately in roman (the default font) and bold face.
292 Whitespace between arguments is omitted in output.
296 Explicitly close out the scope of a prior
298 The default left margin is restored to the state before that
302 The syntax is as follows:
304 .D1 Pf . Ic RE Op Ar level
306 Without an argument, the most recent
313 blocks are closed out.
320 Text is rendered alternately in roman (the default font) and italics.
321 Whitespace between arguments is omitted in output.
325 Temporarily reset the default left margin.
326 This has the following syntax:
328 .D1 Pf . Ic RS Op Ar width
335 If not specified, the saved or default width is used.
340 Text is rendered in small size (one point smaller than the default font)
344 The scope of a section is only closed by another section or the end of
346 The paragraph left-margin width is reset to the default.
348 Text is rendered in small size (one point smaller than the default
352 The scope of a sub-section is closed by a subsequent sub-section,
353 section, or end of file.
354 The paragraph left-margin width is reset to the default.
356 Begin a synopsis block with the following syntax:
357 .Bd -unfilled -offset indent
358 .Pf . Ic SY Ar command
363 This is a non-standard GNU extension
364 and very rarely used even in GNU manual pages.
365 Formatting is similar to
368 Set the name of the manual page for use in the page header
369 and footer with the following syntax:
371 .D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume
373 Conventionally, the document
375 is given in all caps.
378 is usually a single digit, in a few cases followed by a letter.
383 as specified in the ISO-8601 standard;
384 if the argument does not conform, it is printed verbatim.
387 is empty or not specified, the current date is used.
390 string specifies the organisation providing the utility.
398 string replaces the default volume title of the
403 .Dl \&.TH CVS 5 "1992-02-12" GNU
405 Begin a paragraph where the head, if exceeding the indentation width, is
406 followed by a newline; if not, the body follows on the same line after
407 advancing to the indentation width.
408 Subsequent output lines are indented.
409 The syntax is as follows:
410 .Bd -unfilled -offset indent
411 .Pf . Ic TP Op Ar width
412 .Ar head No \e" one line
421 If specified, it's saved for later paragraph left-margins; if
422 unspecified, the saved or default width is used.
426 except that no vertical spacing is inserted before the paragraph.
427 This is a non-standard GNU extension
428 and very rarely used even in GNU manual pages.
430 Sets the volume for the footer for compatibility with man pages from
433 The optional first argument specifies which release it is from.
435 End a uniform resource identifier block started with
437 This is a non-standard GNU extension.
439 Begin a uniform resource identifier block.
440 This is a non-standard GNU extension.
441 It has the following syntax:
442 .Bd -unfilled -offset indent
444 link description to be shown
448 End a synopsis block started with
450 This is a non-standard GNU extension.
452 Indent relative to the current indentation:
454 .D1 Pf . Ic in Op Ar width
458 is signed, the new offset is relative.
459 Otherwise, it is absolute.
460 This value is reset upon the next paragraph, section, or sub-section.
465 macros are classified by scope: line scope or block scope.
466 Line macros are only scoped to the current line (and, in some
467 situations, the subsequent line).
468 Block macros are scoped to the current line and subsequent lines until
469 closed by another block macro.
471 Line macros are generally scoped to the current line, with the body
472 consisting of zero or more arguments.
473 If a macro is scoped to the next line and the line arguments are empty,
474 the next line, which must be text, is used instead.
476 .Bd -literal -offset indent
483 If next-line macros are invoked consecutively, only the last is used.
484 If a next-line macro is followed by a non-next-line macro, an error is
487 The syntax is as follows:
488 .Bd -literal -offset indent
489 \&.YO \(lBbody...\(rB
492 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
493 .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
494 .It Ic AT Ta <=1 Ta current Ta \&
495 .It Ic B Ta n Ta next-line Ta \&
496 .It Ic BI Ta n Ta current Ta \&
497 .It Ic BR Ta n Ta current Ta \&
498 .It Ic DT Ta 0 Ta current Ta \&
499 .It Ic EE Ta 0 Ta current Ta GNU
500 .It Ic EX Ta 0 Ta current Ta GNU
501 .It Ic I Ta n Ta next-line Ta \&
502 .It Ic IB Ta n Ta current Ta \&
503 .It Ic IR Ta n Ta current Ta \&
504 .It Ic OP Ta >=1 Ta current Ta GNU
505 .It Ic PD Ta 1 Ta current Ta \&
506 .It Ic RB Ta n Ta current Ta \&
507 .It Ic RI Ta n Ta current Ta \&
508 .It Ic SB Ta n Ta next-line Ta \&
509 .It Ic SM Ta n Ta next-line Ta \&
510 .It Ic TH Ta >1, <6 Ta current Ta \&
511 .It Ic UC Ta <=1 Ta current Ta \&
512 .It Ic in Ta 1 Ta current Ta Xr roff 7
515 Block macros comprise a head and body.
516 As with in-line macros, the head is scoped to the current line and, in
517 one circumstance, the next line (the next-line stipulations as in
521 The syntax is as follows:
522 .Bd -literal -offset indent
523 \&.YO \(lBhead...\(rB
528 The closure of body scope may be to the section, where a macro is closed
531 sub-section, closed by a section or
533 or paragraph, closed by a section, sub-section,
543 No closure refers to an explicit block closing macro.
545 As a rule, block macros may not be nested; thus, calling a block macro
546 while another block macro scope is open, and the open scope is not
547 implicitly closed, is syntactically incorrect.
548 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
549 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
550 .It Ic HP Ta <2 Ta current Ta paragraph Ta \&
551 .It Ic IP Ta <3 Ta current Ta paragraph Ta \&
552 .It Ic LP Ta 0 Ta current Ta paragraph Ta \&
553 .It Ic ME Ta 0 Ta none Ta none Ta GNU
554 .It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU
555 .It Ic P Ta 0 Ta current Ta paragraph Ta \&
556 .It Ic PP Ta 0 Ta current Ta paragraph Ta \&
557 .It Ic RE Ta <=1 Ta current Ta none Ta \&
558 .It Ic RS Ta 1 Ta current Ta to \&RE Ta \&
559 .It Ic SH Ta >0 Ta next-line Ta section Ta \&
560 .It Ic SS Ta >0 Ta next-line Ta sub-section Ta \&
561 .It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU
562 .It Ic TP Ta n Ta next-line Ta paragraph Ta \&
563 .It Ic TQ Ta n Ta next-line Ta paragraph Ta GNU
564 .It Ic UE Ta 0 Ta current Ta none Ta GNU
565 .It Ic UR Ta 1 Ta current Ta part Ta GNU
566 .It Ic YS Ta 0 Ta none Ta none Ta GNU
569 If a block macro is next-line scoped, it may only be followed by in-line
570 macros for decorating text.
579 font escape sequences can be used to choose fonts.
580 In text lines, the effect of manual font selection by escape sequences
581 only lasts until the next macro invocation; in macro lines, it only lasts
582 until the end of the macro scope.
583 Note that macros like
585 open and close a font scope for each argument.
597 language first appeared as a macro package for the roff typesetting
600 It was later rewritten by James Clark as a macro package for groff.
601 Eric S. Raymond wrote the extended
603 macros for groff in 2007.
604 The stand-alone implementation that is part of the
606 utility written by Kristaps Dzonsons appeared in
611 reference was written by
612 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blob