1 .\" $Id: man.7,v 1.144 2019/07/09 03:46:59 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: July 9 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 Version 9
165 extension later adopted by GNU.
168 it does the same as the
171 request (switch to fill mode).
173 This is a non-standard Version 9
175 extension later adopted by GNU.
178 it does the same as the
181 request (switch to no-fill mode).
183 Begin a paragraph whose initial output line is left-justified, but
184 subsequent output lines are indented, with the following syntax:
186 .D1 Pf . Ic HP Op Ar width
193 If specified, it's saved for later paragraph left margins;
194 if unspecified, the saved or default width is used.
196 This macro is portable, but deprecated
197 because it has no good representation in HTML output,
198 usually ending up indistinguishable from
201 Text is rendered in italics.
203 Text is rendered alternately in italics and bold face.
204 Whitespace between arguments is omitted in output.
208 Begin an indented paragraph with the following syntax:
210 .D1 Pf . Ic IP Op Ar head Op Ar width
216 scaling width defining the left margin.
217 It's saved for later paragraph left-margins; if unspecified, the saved or
218 default width is used.
222 argument is used as a leading term, flushed to the left margin.
223 This is useful for bulleted paragraphs and so on.
225 Text is rendered alternately in italics and roman (the default font).
226 Whitespace between arguments is omitted in output.
233 End a mailto block started with
235 This is a non-standard GNU extension.
237 Begin a mailto block.
238 This is a non-standard GNU extension.
239 It has the following syntax:
240 .Bd -unfilled -offset indent
241 .Pf . Ic MT Ar address
242 link description to be shown
246 Optional command-line argument.
247 This is a non-standard GNU extension.
248 It has the following syntax:
250 .D1 Pf . Ic OP Ar key Op Ar value
254 is usually a command-line flag and
261 Specify the vertical space to be inserted before each new paragraph.
263 The syntax is as follows:
265 .D1 Pf . Ic PD Op Ar height
274 If the unit is omitted,
278 This macro affects the spacing before any subsequent instances of
290 Begin an undecorated paragraph.
291 The scope of a paragraph is closed by a subsequent paragraph,
292 sub-section, section, or end of file.
293 The saved paragraph left-margin width is reset to the default.
295 Text is rendered alternately in roman (the default font) and bold face.
296 Whitespace between arguments is omitted in output.
300 Explicitly close out the scope of a prior
302 The default left margin is restored to the state before that
306 The syntax is as follows:
308 .D1 Pf . Ic RE Op Ar level
310 Without an argument, the most recent
317 blocks are closed out.
324 Text is rendered alternately in roman (the default font) and italics.
325 Whitespace between arguments is omitted in output.
329 Temporarily reset the default left margin.
330 This has the following syntax:
332 .D1 Pf . Ic RS Op Ar width
339 If not specified, the saved or default width is used.
344 Text is rendered in small size (one point smaller than the default font)
348 The scope of a section is only closed by another section or the end of
350 The paragraph left-margin width is reset to the default.
352 Text is rendered in small size (one point smaller than the default
356 The scope of a sub-section is closed by a subsequent sub-section,
357 section, or end of file.
358 The paragraph left-margin width is reset to the default.
360 Begin a synopsis block with the following syntax:
361 .Bd -unfilled -offset indent
362 .Pf . Ic SY Ar command
367 This is a non-standard GNU extension
368 and very rarely used even in GNU manual pages.
369 Formatting is similar to
372 Set the name of the manual page for use in the page header
373 and footer with the following syntax:
375 .D1 Pf . Ic TH Ar name section date Op Ar source Op Ar volume
377 Conventionally, the document
379 is given in all caps.
382 is usually a single digit, in a few cases followed by a letter.
387 as specified in the ISO-8601 standard;
388 if the argument does not conform, it is printed verbatim.
391 is empty or not specified, the current date is used.
394 string specifies the organisation providing the utility.
402 string replaces the default volume title of the
407 .Dl \&.TH CVS 5 "1992-02-12" GNU
409 Begin a paragraph where the head, if exceeding the indentation width, is
410 followed by a newline; if not, the body follows on the same line after
411 advancing to the indentation width.
412 Subsequent output lines are indented.
413 The syntax is as follows:
414 .Bd -unfilled -offset indent
415 .Pf . Ic TP Op Ar width
416 .Ar head No \e" one line
425 If specified, it's saved for later paragraph left-margins; if
426 unspecified, the saved or default width is used.
430 except that no vertical spacing is inserted before the paragraph.
431 This is a non-standard GNU extension
432 and very rarely used even in GNU manual pages.
434 Sets the volume for the footer for compatibility with man pages from
437 The optional first argument specifies which release it is from.
439 End a uniform resource identifier block started with
441 This is a non-standard GNU extension.
443 Begin a uniform resource identifier block.
444 This is a non-standard GNU extension.
445 It has the following syntax:
446 .Bd -unfilled -offset indent
448 link description to be shown
452 End a synopsis block started with
454 This is a non-standard GNU extension.
456 Indent relative to the current indentation:
458 .D1 Pf . Ic in Op Ar width
462 is signed, the new offset is relative.
463 Otherwise, it is absolute.
464 This value is reset upon the next paragraph, section, or sub-section.
469 macros are classified by scope: line scope or block scope.
470 Line macros are only scoped to the current line (and, in some
471 situations, the subsequent line).
472 Block macros are scoped to the current line and subsequent lines until
473 closed by another block macro.
475 Line macros are generally scoped to the current line, with the body
476 consisting of zero or more arguments.
477 If a macro is scoped to the next line and the line arguments are empty,
478 the next line, which must be text, is used instead.
480 .Bd -literal -offset indent
487 If next-line macros are invoked consecutively, only the last is used.
488 If a next-line macro is followed by a non-next-line macro, an error is
491 The syntax is as follows:
492 .Bd -literal -offset indent
493 \&.YO \(lBbody...\(rB
496 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
497 .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
498 .It Ic AT Ta <=1 Ta current Ta \&
499 .It Ic B Ta n Ta next-line Ta \&
500 .It Ic BI Ta n Ta current Ta \&
501 .It Ic BR Ta n Ta current Ta \&
502 .It Ic DT Ta 0 Ta current Ta \&
503 .It Ic EE Ta 0 Ta current Ta Version 9 At
504 .It Ic EX Ta 0 Ta current Ta Version 9 At
505 .It Ic I Ta n Ta next-line Ta \&
506 .It Ic IB Ta n Ta current Ta \&
507 .It Ic IR Ta n Ta current Ta \&
508 .It Ic OP Ta >=1 Ta current Ta GNU
509 .It Ic PD Ta 1 Ta current Ta \&
510 .It Ic RB Ta n Ta current Ta \&
511 .It Ic RI Ta n Ta current Ta \&
512 .It Ic SB Ta n Ta next-line Ta \&
513 .It Ic SM Ta n Ta next-line Ta \&
514 .It Ic TH Ta >1, <6 Ta current Ta \&
515 .It Ic UC Ta <=1 Ta current Ta \&
516 .It Ic in Ta 1 Ta current Ta Xr roff 7
519 Block macros comprise a head and body.
520 As with in-line macros, the head is scoped to the current line and, in
521 one circumstance, the next line (the next-line stipulations as in
525 The syntax is as follows:
526 .Bd -literal -offset indent
527 \&.YO \(lBhead...\(rB
532 The closure of body scope may be to the section, where a macro is closed
535 sub-section, closed by a section or
537 or paragraph, closed by a section, sub-section,
547 No closure refers to an explicit block closing macro.
549 As a rule, block macros may not be nested; thus, calling a block macro
550 while another block macro scope is open, and the open scope is not
551 implicitly closed, is syntactically incorrect.
552 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
553 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
554 .It Ic HP Ta <2 Ta current Ta paragraph Ta \&
555 .It Ic IP Ta <3 Ta current Ta paragraph Ta \&
556 .It Ic LP Ta 0 Ta current Ta paragraph Ta \&
557 .It Ic ME Ta 0 Ta none Ta none Ta GNU
558 .It Ic MT Ta 1 Ta current Ta to \&ME Ta GNU
559 .It Ic P Ta 0 Ta current Ta paragraph Ta \&
560 .It Ic PP Ta 0 Ta current Ta paragraph Ta \&
561 .It Ic RE Ta <=1 Ta current Ta none Ta \&
562 .It Ic RS Ta 1 Ta current Ta to \&RE Ta \&
563 .It Ic SH Ta >0 Ta next-line Ta section Ta \&
564 .It Ic SS Ta >0 Ta next-line Ta sub-section Ta \&
565 .It Ic SY Ta 1 Ta current Ta to \&YS Ta GNU
566 .It Ic TP Ta n Ta next-line Ta paragraph Ta \&
567 .It Ic TQ Ta n Ta next-line Ta paragraph Ta GNU
568 .It Ic UE Ta 0 Ta current Ta none Ta GNU
569 .It Ic UR Ta 1 Ta current Ta part Ta GNU
570 .It Ic YS Ta 0 Ta none Ta none Ta GNU
573 If a block macro is next-line scoped, it may only be followed by in-line
574 macros for decorating text.
583 font escape sequences can be used to choose fonts.
584 In text lines, the effect of manual font selection by escape sequences
585 only lasts until the next macro invocation; in macro lines, it only lasts
586 until the end of the macro scope.
587 Note that macros like
589 open and close a font scope for each argument.
601 language first appeared as a macro package for the roff typesetting
604 It was later rewritten by James Clark as a macro package for groff.
605 Eric S. Raymond wrote the extended
607 macros for groff in 2007.
608 The stand-alone implementation that is part of the
610 utility written by Kristaps Dzonsons appeared in
615 reference was written by
616 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
projects / FreeBSD / FreeBSD.git / blob