1 .\" $Id: man.7,v 1.117 2012/06/20 22:06:30 schwarze Exp $
3 .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org>
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .Dd $Mdocdate: June 20 2012 $
23 .Nd legacy formatting language for manual pages
27 language has been used to write
32 It supports limited control of presentational details like fonts,
33 indentation and spacing.
34 This reference document describes the structure of manual pages
35 and the syntax and usage of the man language.
40 to write your manuals:
42 It lacks support for semantic markup.
49 document, lines beginning with the control character
53 The first word is the macro name.
54 It usually consists of two capital letters.
55 For a list of available macros, see
57 The words following the macro name are arguments to the macro.
59 Lines not beginning with the control character are called
61 They provide free-form text to be printed; the formatting of the text
62 depends on the respective processing context:
63 .Bd -literal -offset indent
64 \&.SH Macro lines change control state.
65 Text lines are interpreted within the current state.
68 Many aspects of the basic syntax of the
70 language are based on the
78 manual for details, in particular regarding
79 comments, escape sequences, whitespace, and quoting.
83 document must contain the
85 macro describing the document's section and title.
86 It may occur anywhere in the document, although conventionally it
87 appears as the first macro.
91 at least one macro or text line must appear in the document.
93 The following is a well-formed skeleton
97 .Bd -literal -offset indent
98 \&.TH PROGNAME 1 2009-10-10
100 \efBprogname\efR \e(en a description goes here
101 \&.\e\(dq .SH LIBRARY
102 \&.\e\(dq For sections 2 & 3 only.
103 \&.\e\(dq Not used in OpenBSD.
105 \efBprogname\efR [\efB\e-options\efR] arguments...
107 The \efBfoo\efR utility processes files...
108 \&.\e\(dq .SH IMPLEMENTATION NOTES
109 \&.\e\(dq Not used in OpenBSD.
110 \&.\e\(dq .SH RETURN VALUES
111 \&.\e\(dq For sections 2, 3, & 9 only.
112 \&.\e\(dq .SH ENVIRONMENT
113 \&.\e\(dq For sections 1, 6, 7, & 8 only.
115 \&.\e\(dq .SH EXIT STATUS
116 \&.\e\(dq For sections 1, 6, & 8 only.
117 \&.\e\(dq .SH EXAMPLES
118 \&.\e\(dq .SH DIAGNOSTICS
119 \&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
121 \&.\e\(dq For sections 2, 3, & 9 only.
122 \&.\e\(dq .SH SEE ALSO
123 \&.\e\(dq .BR foo ( 1 )
124 \&.\e\(dq .SH STANDARDS
125 \&.\e\(dq .SH HISTORY
126 \&.\e\(dq .SH AUTHORS
127 \&.\e\(dq .SH CAVEATS
129 \&.\e\(dq .SH SECURITY CONSIDERATIONS
130 \&.\e\(dq Not used in OpenBSD.
135 document are conventionally ordered as they appear above.
136 Sections should be composed as follows:
137 .Bl -ohang -offset indent
139 The name(s) and a short description of the documented material.
140 The syntax for this is generally as follows:
142 .D1 \efBname\efR \e(en description
144 The name of the library containing the documented material, which is
145 assumed to be a function in a section 2 or 3 manual.
146 For functions in the C library, this may be as follows:
148 .D1 Standard C Library (libc, -lc)
150 Documents the utility invocation syntax, function call syntax, or device
153 For the first, utilities (sections 1, 6, and 8), this is
154 generally structured as follows:
156 .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR...
158 For the second, function calls (sections 2, 3, 9):
160 .D1 \&.B char *name(char *\efIarg\efR);
162 And for the third, configurations (section 4):
164 .D1 \&.B name* at cardbus ? function ?
166 Manuals not in these sections generally don't need a
169 This expands upon the brief, one-line description in
171 It usually contains a break-down of the options (if documenting a
173 .It Em IMPLEMENTATION NOTES
174 Implementation-specific notes should be kept here.
175 This is useful when implementing standard functions that may have side
176 effects or notable algorithmic implications.
178 This section documents the return values of functions in sections 2, 3, and 9.
180 Documents any usages of environment variables, e.g.,
183 Documents files used.
184 It's helpful to document both the file name and a short description of how
185 the file is used (created, modified, etc.).
187 This section documents the command exit status for
188 section 1, 6, and 8 utilities.
189 Historically, this information was described in
191 a practise that is now discouraged.
194 This often contains snippets of well-formed,
195 well-tested invocations.
196 Make sure that examples work properly!
198 Documents error conditions.
199 This is most useful in section 4 manuals.
200 Historically, this section was used in place of
202 for manuals in sections 1, 6, and 8; however, this practise is
205 Documents error handling in sections 2, 3, and 9.
207 References other manuals with related topics.
208 This section should exist for most manuals.
210 .D1 \&.BR bar \&( 1 \&),
212 Cross-references should conventionally be ordered
213 first by section, then alphabetically.
215 References any standards implemented or used, such as
217 .D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq)
219 If not adhering to any standards, the
221 section should be used.
223 A brief history of the subject, including where support first appeared.
225 Credits to the person or persons who wrote the code and/or documentation.
226 Authors should generally be noted by both name and email address.
228 Common misuses and misunderstandings should be explained
231 Known bugs, limitations, and work-arounds should be described
233 .It Em SECURITY CONSIDERATIONS
234 Documents any security precautions that operators should consider.
237 This overview is sorted such that macros of similar purpose are listed
238 together, to help find the best macro for any given purpose.
239 Deprecated macros are not included in the overview, but can be found
240 in the alphabetical reference below.
241 .Ss Page header and footer meta-data
242 .Bl -column "PP, LP, P" description
243 .It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume
244 .It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument)
245 .It Sx UC Ta display BSD version in the page footer (<= 1 argument)
247 .Ss Sections and paragraphs
248 .Bl -column "PP, LP, P" description
249 .It Sx SH Ta section header (one line)
250 .It Sx SS Ta subsection header (one line)
251 .It Sx PP , LP , P Ta start an undecorated paragraph (no arguments)
252 .It Sx RS , RE Ta reset the left margin: Op Ar width
253 .It Sx IP Ta indented paragraph: Op Ar head Op Ar width
254 .It Sx TP Ta tagged paragraph: Op Ar width
255 .It Sx HP Ta hanged paragraph: Op Ar width
256 .It Sx \&br Ta force output line break in text mode (no arguments)
257 .It Sx \&sp Ta force vertical space: Op Ar height
258 .It Sx fi , nf Ta fill mode and no-fill mode (no arguments)
259 .It Sx in Ta additional indent: Op Ar width
262 .Bl -column "PP, LP, P" description
263 .It Sx B Ta boldface font
264 .It Sx I Ta italic font
265 .It Sx R Ta roman (default) font
266 .It Sx SB Ta small boldface font
267 .It Sx SM Ta small roman font
268 .It Sx BI Ta alternate between boldface and italic fonts
269 .It Sx BR Ta alternate between boldface and roman fonts
270 .It Sx IB Ta alternate between italic and boldface fonts
271 .It Sx IR Ta alternate between italic and roman fonts
272 .It Sx RB Ta alternate between roman and boldface fonts
273 .It Sx RI Ta alternate between roman and italic fonts
276 This section is a canonical reference to all macros, arranged
278 For the scoping of individual macros, see
281 Sets the volume for the footer for compatibility with man pages from
284 The optional arguments specify which release it is from.
286 Text is rendered in bold face.
293 Text is rendered alternately in bold face and italic.
295 .Sq .BI this word and that
300 to render in bold face, while
305 Whitespace between arguments is omitted in output.
309 .Dl \&.BI bold italic bold italic
311 The output of this example will be emboldened
315 with spaces stripped between arguments.
325 Text is rendered alternately in bold face and roman (the default font).
326 Whitespace between arguments is omitted in output.
330 for an equivalent example.
341 Included for compatibility.
343 This is a non-standard GNU extension, included only for compatibility.
349 This is a non-standard GNU extension, included only for compatibility.
355 Begin a paragraph whose initial output line is left-justified, but
356 subsequent output lines are indented, with the following syntax:
357 .Bd -filled -offset indent
367 If specified, it's saved for later paragraph left-margins; if unspecified, the
368 saved or default width is used.
378 Text is rendered in italics.
385 Text is rendered alternately in italics and bold face.
386 Whitespace between arguments is omitted in output.
390 for an equivalent example.
400 Begin an indented paragraph with the following syntax:
401 .Bd -filled -offset indent
403 .Op Cm head Op Cm width
410 scaling width defining the left margin.
411 It's saved for later paragraph left-margins; if unspecified, the saved or
412 default width is used.
416 argument is used as a leading term, flushed to the left margin.
417 This is useful for bulleted paragraphs and so on.
427 Text is rendered alternately in italics and roman (the default font).
428 Whitespace between arguments is omitted in output.
432 for an equivalent example.
442 Begin an undecorated paragraph.
443 The scope of a paragraph is closed by a subsequent paragraph,
444 sub-section, section, or end of file.
445 The saved paragraph left-margin width is reset to the default.
455 Optional command-line argument.
456 This is a non-standard GNU extension, included only for compatibility.
457 It has the following syntax:
458 .Bd -filled -offset indent
465 is usually a command-line flag and
491 Text is rendered in roman (the default font).
498 Text is rendered alternately in roman (the default font) and bold face.
499 Whitespace between arguments is omitted in output.
503 for an equivalent example.
513 Explicitly close out the scope of a prior
515 The default left margin is restored to the state of the original
519 Text is rendered alternately in roman (the default font) and italics.
520 Whitespace between arguments is omitted in output.
524 for an equivalent example.
534 Temporarily reset the default left margin.
535 This has the following syntax:
536 .Bd -filled -offset indent
546 If not specified, the saved or default width is used.
551 Text is rendered in small size (one point smaller than the default font)
555 The scope of a section is only closed by another section or the end of
557 The paragraph left-margin width is reset to the default.
559 Text is rendered in small size (one point smaller than the default
563 The scope of a sub-section is closed by a subsequent sub-section,
564 section, or end of file.
565 The paragraph left-margin width is reset to the default.
567 Sets the title of the manual page with the following syntax:
568 .Bd -filled -offset indent
570 .Ar title section date
571 .Op Ar source Op Ar volume
574 Conventionally, the document
576 is given in all caps.
581 as specified in the ISO-8601 standard;
582 if the argument does not conform, it is printed verbatim.
585 is empty or not specified, the current date is used.
588 string specifies the organisation providing the utility.
591 string replaces the default rendered volume, which is dictated by the
596 .Dl \&.TH CVS 5 "1992-02-12" GNU
598 Begin a paragraph where the head, if exceeding the indentation width, is
599 followed by a newline; if not, the body follows on the same line after a
600 buffer to the indentation width.
601 Subsequent output lines are indented.
602 The syntax is as follows:
603 .Bd -filled -offset indent
613 If specified, it's saved for later paragraph left-margins; if
614 unspecified, the saved or default width is used.
624 Sets the volume for the footer for compatibility with man pages from
626 The optional first argument specifies which release it is from.
628 Breaks the current line.
629 Consecutive invocations have no further effect.
634 End literal mode begun by
637 Change the current font mode.
640 for a listing of available font modes.
642 Indent relative to the current indentation:
644 .D1 Pf \. Sx \&in Op Cm width
648 is signed, the new offset is relative.
649 Otherwise, it is absolute.
650 This value is reset upon the next paragraph, section, or sub-section.
652 Don't align to the right margin.
654 Begin literal mode: all subsequent free-form lines have their end of
655 line boundaries preserved.
658 Literal mode is implicitly ended by
663 Insert vertical spaces into output with the following syntax:
664 .Bd -filled -offset indent
671 argument is a scaling width as described in
673 If 0, this is equivalent to the
676 Defaults to 1, if unspecified.
683 macros are classified by scope: line scope or block scope.
684 Line macros are only scoped to the current line (and, in some
685 situations, the subsequent line).
686 Block macros are scoped to the current line and subsequent lines until
687 closed by another block macro.
689 Line macros are generally scoped to the current line, with the body
690 consisting of zero or more arguments.
691 If a macro is scoped to the next line and the line arguments are empty,
692 the next line, which must be text, is used instead.
694 .Bd -literal -offset indent
701 If next-line macros are invoked consecutively, only the last is used.
702 If a next-line macro is followed by a non-next-line macro, an error is
709 The syntax is as follows:
710 .Bd -literal -offset indent
711 \&.YO \(lBbody...\(rB
714 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent
715 .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes
716 .It Sx \&AT Ta <=1 Ta current Ta \&
717 .It Sx \&B Ta n Ta next-line Ta \&
718 .It Sx \&BI Ta n Ta current Ta \&
719 .It Sx \&BR Ta n Ta current Ta \&
720 .It Sx \&DT Ta 0 Ta current Ta \&
721 .It Sx \&I Ta n Ta next-line Ta \&
722 .It Sx \&IB Ta n Ta current Ta \&
723 .It Sx \&IR Ta n Ta current Ta \&
724 .It Sx \&OP Ta 0, 1 Ta current Ta compat
725 .It Sx \&R Ta n Ta next-line Ta \&
726 .It Sx \&RB Ta n Ta current Ta \&
727 .It Sx \&RI Ta n Ta current Ta \&
728 .It Sx \&SB Ta n Ta next-line Ta \&
729 .It Sx \&SM Ta n Ta next-line Ta \&
730 .It Sx \&TH Ta >1, <6 Ta current Ta \&
731 .It Sx \&UC Ta <=1 Ta current Ta \&
732 .It Sx \&br Ta 0 Ta current Ta compat
733 .It Sx \&fi Ta 0 Ta current Ta compat
734 .It Sx \&ft Ta 1 Ta current Ta compat
735 .It Sx \&in Ta 1 Ta current Ta compat
736 .It Sx \&na Ta 0 Ta current Ta compat
737 .It Sx \&nf Ta 0 Ta current Ta compat
738 .It Sx \&sp Ta 1 Ta current Ta compat
743 are included for compatibility with the significant corpus of existing
744 manuals that mix dialects of roff.
745 These macros should not be used for portable
749 Block macros comprise a head and body.
750 As with in-line macros, the head is scoped to the current line and, in
751 one circumstance, the next line (the next-line stipulations as in
755 The syntax is as follows:
756 .Bd -literal -offset indent
757 \&.YO \(lBhead...\(rB
762 The closure of body scope may be to the section, where a macro is closed
765 sub-section, closed by a section or
767 part, closed by a section, sub-section, or
769 or paragraph, closed by a section, sub-section, part,
777 No closure refers to an explicit block closing macro.
779 As a rule, block macros may not be nested; thus, calling a block macro
780 while another block macro scope is open, and the open scope is not
781 implicitly closed, is syntactically incorrect.
782 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent
783 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes
784 .It Sx \&HP Ta <2 Ta current Ta paragraph Ta \&
785 .It Sx \&IP Ta <3 Ta current Ta paragraph Ta \&
786 .It Sx \&LP Ta 0 Ta current Ta paragraph Ta \&
787 .It Sx \&P Ta 0 Ta current Ta paragraph Ta \&
788 .It Sx \&PP Ta 0 Ta current Ta paragraph Ta \&
789 .It Sx \&RE Ta 0 Ta current Ta none Ta compat
790 .It Sx \&RS Ta 1 Ta current Ta part Ta compat
791 .It Sx \&SH Ta >0 Ta next-line Ta section Ta \&
792 .It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \&
793 .It Sx \&TP Ta n Ta next-line Ta paragraph Ta \&
801 If a block macro is next-line scoped, it may only be followed by in-line
802 macros for decorating text.
811 font escape sequences can be used to choose fonts.
812 In text lines, the effect of manual font selection by escape sequences
813 only lasts until the next macro invocation; in macro lines, it only lasts
814 until the end of the macro scope.
815 Note that macros like
817 open and close a font scope for each argument.
819 This section documents areas of questionable portability between
820 implementations of the
830 to close out a literal context opened with
832 This behaviour may not be portable.
834 In quoted literals, GNU troff allowed pair-wise double-quotes to produce
835 a standalone double-quote in formatted output.
836 It is not known whether this behaviour is exhibited by other formatters.
838 troff suppresses a newline before
840 macro output; in mandoc, it is an alias for the standard
846 .Pq horizontal position ,
848 .Pq vertical position ,
852 .Pq text filling colour ,
854 .Pq zero-length character ,
858 .Pq horizontal position marker ,
860 .Pq text overstrike ,
864 escape sequences are all discarded in mandoc.
868 scaling unit is accepted by mandoc, but rendered as the default unit.
872 macro does not accept negative values in mandoc.
873 In GNU troff, this would result in strange behaviour.
875 In page header lines, GNU troff versions up to and including 1.21
878 names explicitly specified in the
880 macro; mandoc and newer groff print the default volume name
891 macro is part of the extended
893 macro set, and may not be portable to non-GNU troff implementations.
905 language first appeared as a macro package for the roff typesetting
908 It was later rewritten by James Clark as a macro package for groff.
909 Eric S. Raymond wrote the extended
911 macros for groff in 2007.
912 The stand-alone implementation that is part of the
914 utility written by Kristaps Dzonsons appeared in
919 reference was written by
920 .An Kristaps Dzonsons ,
921 .Mt kristaps@bsd.lv .
923 Do not use this language.
git.ckatri.com / mandoc.git / blob