![]() ![]() | ![]() |
version 1.135, 2010/07/16 21:09:39 | version 1.188, 2011/05/26 09:26:16 | ||
---|---|---|---|
|
|
||
.\" $Id$ | .\" $Id$ | ||
.\" | .\" | ||
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv> | .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> | ||
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> | .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> | ||
.\" | .\" | ||
.\" Permission to use, copy, modify, and distribute this software for any | .\" Permission to use, copy, modify, and distribute this software for any | ||
|
|
||
language is used to format | language is used to format | ||
.Bx | .Bx | ||
.Ux | .Ux | ||
manuals. In this reference document, we describe its syntax, structure, | manuals. | ||
and usage. Our reference implementation is mandoc; the | This reference document describes its syntax, structure, and | ||
usage. | |||
The reference implementation is | |||
.Xr mandoc 1 ; | |||
the | |||
.Sx COMPATIBILITY | .Sx COMPATIBILITY | ||
section describes compatibility with other troff \-mdoc implementations. | section describes compatibility with other troff \-mdoc implementations. | ||
.Pp | .Pp | ||
|
|
||
.Nm | .Nm | ||
document follows simple rules: lines beginning with the control | document follows simple rules: lines beginning with the control | ||
character | character | ||
.Sq \. | .Sq \&. | ||
are parsed for macros. Other lines are interpreted within the scope of | are parsed for macros. | ||
prior macros: | Text lines, those not beginning with the control character, are | ||
interpreted within the scope of prior macros: | |||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Sh Macro lines change control state. | \&.Sh Macro lines change control state. | ||
Other lines are interpreted within the current state. | Text lines are interpreted within the current state. | ||
.Ed | .Ed | ||
.Sh LANGUAGE SYNTAX | .Sh LANGUAGE SYNTAX | ||
.Nm | .Nm | ||
documents may contain only graphable 7-bit ASCII characters, the space | documents may contain only graphable 7-bit ASCII characters, the space | ||
character, and, in certain circumstances, the tab character. All | character, and, in certain circumstances, the tab character. | ||
manuals must have | .Pp | ||
.Ux | If the first character of a text line is a space, that line is printed | ||
line terminators. | with a leading newline. | ||
.Ss Comments | .Ss Comments | ||
Text following a | Text following a | ||
.Sq \e\*q , | .Sq \e\*q , | ||
whether in a macro or free-form text line, is ignored to the end of | whether in a macro or text line, is ignored to the end of | ||
line. A macro line with only a control character and comment escape, | line. | ||
A macro line with only a control character and comment escape, | |||
.Sq \&.\e\*q , | .Sq \&.\e\*q , | ||
is also ignored. Macro lines with only a control character and optionally | is also ignored. | ||
whitespace are stripped from input. | Macro lines with only a control character and optional whitespace are | ||
.Ss Reserved Characters | stripped from input. | ||
Within a macro line, the following characters are reserved: | .Ss Reserved Terms | ||
Within a macro line, the following terms are reserved: | |||
.Pp | .Pp | ||
.Bl -tag -width Ds -offset indent -compact | .Bl -tag -width Ds -offset indent -compact | ||
.It \&. | .It \&. | ||
.Pq period | .Pq period | ||
.It \e. | |||
.Pq escaped period | |||
.It \&, | .It \&, | ||
.Pq comma | .Pq comma | ||
.It \&: | .It \&: | ||
|
|
||
.Pq exclamation | .Pq exclamation | ||
.It \&| | .It \&| | ||
.Pq vertical bar | .Pq vertical bar | ||
.It \e*(Ba | |||
.Pq reserved-word vertical bar | |||
.El | .El | ||
.Pp | .Pp | ||
Use of reserved characters is described in | For general use in macro lines, these can be escaped with a non-breaking | ||
.Sx MACRO SYNTAX . | space | ||
For general use in macro lines, these characters must either be escaped | .Pq Sq \e& . | ||
with a non-breaking space | In text lines, these may be used as normal punctuation. | ||
.Pq Sq \e& | |||
or, if applicable, an appropriate escape sequence used. | |||
.Ss Special Characters | .Ss Special Characters | ||
Special characters may occur in both macro and free-form lines. | Special characters may occur in both macro and text lines. | ||
Sequences begin with the escape character | Sequences begin with the escape character | ||
.Sq \e | .Sq \e | ||
followed by either an open-parenthesis | followed by either an open-parenthesis | ||
|
|
||
.Sq \&[ | .Sq \&[ | ||
for n-character sequences (terminated at a close-bracket | for n-character sequences (terminated at a close-bracket | ||
.Sq \&] ) ; | .Sq \&] ) ; | ||
or a single one-character sequence. | or a single one character sequence. | ||
See | See | ||
.Xr mandoc_char 7 | .Xr mandoc_char 7 | ||
for a complete list. | for a complete list. | ||
|
|
||
.Ss Text Decoration | .Ss Text Decoration | ||
Terms may be text-decorated using the | Terms may be text-decorated using the | ||
.Sq \ef | .Sq \ef | ||
escape followed by an indicator: B (bold), I, (italic), R (Roman), or P | escape followed by an indicator: B (bold), I (italic), R (Roman), or P | ||
(revert to previous mode): | (revert to previous mode): | ||
.Pp | .Pp | ||
.D1 \efBbold\efR \efIitalic\efP | .Dl \efBbold\efR \efIitalic\efP | ||
.Pp | .Pp | ||
A numerical representation 3, 2, or 1 (bold, italic, and Roman, | A numerical representation 3, 2, or 1 (bold, italic, and Roman, | ||
respectively) may be used instead. | respectively) may be used instead. | ||
A text decoration is valid within | If a macro opens a font scope after calling | ||
the current font scope only: if a macro opens a font scope alongside | .Sq \ef , | ||
its own scope, such as | such as with | ||
.Sx \&Bf | .Sx \&Bf , | ||
.Cm \&Sy , | the | ||
in-scope invocations of | |||
.Sq \ef | .Sq \ef | ||
are only valid within the font scope of the macro. | mode will be restored upon exiting the | ||
If | .Sx \&Bf | ||
.Sq \ef | scope. | ||
is specified outside of any font scope, such as in unenclosed, free-form | |||
text, it will affect the remainder of the document. | |||
.Pp | .Pp | ||
Text may also be sized with the | Note this form is | ||
.Sq \es | |||
escape, whose syntax is one of | |||
.Sq \es+-n | |||
for one-digit numerals; | |||
.Sq \es(+-nn | |||
or | |||
.Sq \es+-(nn | |||
for two-digit numerals; and | |||
.Sq \es[+-N] , | |||
.Sq \es+-[N] , | |||
.Sq \es'+-N' , | |||
or | |||
.Sq \es+-'N' | |||
for arbitrary-digit numerals: | |||
.Pp | |||
.D1 \es+1bigger\es-1 | |||
.D1 \es[+10]much bigger\es[-10] | |||
.D1 \es+(10much bigger\es-(10 | |||
.D1 \es+'100'much much bigger\es-'100' | |||
.Pp | |||
Note these forms are | |||
.Em not | .Em not | ||
recommended for | recommended for | ||
.Nm , | .Nm , | ||
which encourages semantic annotation. | which encourages semantic annotation. | ||
.Ss Predefined Strings | .Ss Predefined Strings | ||
Historically, | Historically, | ||
.Xr groff 1 | troff | ||
also defined a set of package-specific | also defined a set of package-specific | ||
.Dq predefined strings , | .Dq predefined strings , | ||
which, like | which, like | ||
|
|
||
.Pq vertical bar . | .Pq vertical bar . | ||
.Ss Whitespace | .Ss Whitespace | ||
Whitespace consists of the space character. | Whitespace consists of the space character. | ||
In free-form lines, whitespace is preserved within a line; un-escaped | In text lines, whitespace is preserved within a line; unescaped | ||
trailing spaces are stripped from input (unless in a literal context). | trailing spaces are stripped from input (unless in a literal context). | ||
Blank free-form lines, which may include whitespace, are only permitted | Blank text lines, which may include whitespace, are only permitted | ||
within literal contexts. | within literal contexts. | ||
.Pp | .Pp | ||
In macro lines, whitespace delimits arguments and is discarded. | In macro lines, whitespace delimits arguments and is discarded. | ||
If arguments are quoted, whitespace within the quotes is retained. | If arguments are quoted, whitespace within the quotes is retained. | ||
.Ss Quotation | .Ss Quotation | ||
Macro arguments may be quoted with a double-quote to group | Macro arguments may be quoted with double-quotes to group | ||
space-delimited terms or to retain blocks of whitespace. | space-delimited terms or to retain blocks of whitespace. | ||
A quoted argument begins with a double-quote preceded by whitespace. | A quoted argument begins with a double-quote preceded by whitespace. | ||
The next double-quote not pair-wise adjacent to another double-quote | The next double-quote not pairwise adjacent to another double-quote | ||
terminates the literal, regardless of surrounding whitespace. | terminates the literal, regardless of surrounding whitespace. | ||
.Pp | .Pp | ||
This produces tokens | Note that any quoted text, even if it would cause a macro invocation | ||
.Sq a" , | when unquoted, is considered literal text. | ||
.Sq b c , | |||
.Sq de , | |||
and | |||
.Sq fg" . | |||
Note that any quoted term, be it argument or macro, is indiscriminately | |||
considered literal text. | |||
Thus, the following produces | Thus, the following produces | ||
.Sq \&Em a : | .Sq Op "Fl a" : | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Em "Em a" | \&.Op "Fl a" | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
In free-form mode, quotes are regarded as opaque text. | In text lines, quotes are regarded as opaque text. | ||
.Ss Dates | |||
There are several macros in | |||
.Nm | |||
that require a date argument. | |||
The canonical form for dates is the American format: | |||
.Pp | |||
.D1 Cm Month Day , Year | |||
.Pp | |||
The | |||
.Cm Day | |||
value is an optionally zero-padded numeral. | |||
The | |||
.Cm Month | |||
value is the full month name. | |||
The | |||
.Cm Year | |||
value is the full four-digit year. | |||
.Pp | |||
Reduced form dates are broken-down canonical form dates: | |||
.Pp | |||
.D1 Cm Month , Year | |||
.D1 Cm Year | |||
.Pp | |||
Some examples of valid dates follow: | |||
.Pp | |||
.D1 "May, 2009" Pq reduced form | |||
.D1 "2009" Pq reduced form | |||
.D1 "May 20, 2009" Pq canonical form | |||
.Ss Scaling Widths | .Ss Scaling Widths | ||
Many macros support scaled widths for their arguments, such as | Many macros support scaled widths for their arguments, such as | ||
stipulating a two-inch list indentation with the following: | stipulating a two-inch list indentation with the following: | ||
|
|
||
See | See | ||
.Sx COMPATIBILITY . | .Sx COMPATIBILITY . | ||
.Ss Sentence Spacing | .Ss Sentence Spacing | ||
When composing a manual, make sure that your sentences end at the end of | When composing a manual, make sure that sentences end at the end of | ||
a line. | a line. | ||
By doing so, front-ends will be able to apply the proper amount of | By doing so, front-ends will be able to apply the proper amount of | ||
spacing after the end of sentence (unescaped) period, exclamation mark, | spacing after the end of sentence (unescaped) period, exclamation mark, | ||
or question mark followed by zero or more non-sentence closing | or question mark followed by zero or more non-sentence closing | ||
delimiters ( | delimiters | ||
.Ns Sq \&) , | .Po | ||
.Sq \&) , | |||
.Sq \&] , | .Sq \&] , | ||
.Sq \&' , | .Sq \&' , | ||
.Sq \&" ) . | .Sq \&" | ||
.Pc . | |||
.Pp | .Pp | ||
The proper spacing is also intelligently preserved if a sentence ends at | The proper spacing is also intelligently preserved if a sentence ends at | ||
the boundary of a macro line, e.g., | the boundary of a macro line. | ||
For example: | |||
.Pp | .Pp | ||
.D1 \&Xr mandoc 1 \. | .Dl \&.Xr mandoc 1 \&. | ||
.D1 \&Fl T \&Ns \&Cm ascii \. | .Dl \&.Fl T \&Ns \&Cm ascii \&. | ||
.Sh MANUAL STRUCTURE | .Sh MANUAL STRUCTURE | ||
A well-formed | A well-formed | ||
.Nm | .Nm | ||
document consists of a document prologue followed by one or more | document consists of a document prologue followed by one or more | ||
sections. | sections. | ||
.Pp | .Pp | ||
The prologue, which consists of (in order) the | The prologue, which consists of the | ||
.Sx \&Dd , | .Sx \&Dd , | ||
.Sx \&Dt , | .Sx \&Dt , | ||
and | and | ||
.Sx \&Os | .Sx \&Os | ||
macros, is required for every document. | macros in that order, is required for every document. | ||
.Pp | .Pp | ||
The first section (sections are denoted by | The first section (sections are denoted by | ||
.Sx \&Sh ) | .Sx \&Sh ) | ||
|
|
||
.Pp | .Pp | ||
The following is a well-formed skeleton | The following is a well-formed skeleton | ||
.Nm | .Nm | ||
file: | file for a utility | ||
.Qq progname : | |||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Dd $\&Mdocdate$ | \&.Dd $\&Mdocdate$ | ||
\&.Dt mdoc 7 | \&.Dt PROGNAME section | ||
\&.Os | \&.Os | ||
\&.Sh NAME | \&.Sh NAME | ||
\&.Nm foo | \&.Nm progname | ||
\&.Nd a description goes here | \&.Nd a description goes here | ||
\&.\e\*q The next is for sections 2, 3, & 9 only. | |||
\&.\e\*q .Sh LIBRARY | \&.\e\*q .Sh LIBRARY | ||
\&.\e\*q For sections 2, 3, & 9 only. | |||
\&.\e\*q Not used in OpenBSD. | |||
\&.Sh SYNOPSIS | \&.Sh SYNOPSIS | ||
\&.Nm foo | \&.Nm progname | ||
\&.Op Fl options | \&.Op Fl options | ||
\&.Ar | \&.Ar | ||
\&.Sh DESCRIPTION | \&.Sh DESCRIPTION | ||
|
|
||
\&.Nm | \&.Nm | ||
utility processes files ... | utility processes files ... | ||
\&.\e\*q .Sh IMPLEMENTATION NOTES | \&.\e\*q .Sh IMPLEMENTATION NOTES | ||
\&.\e\*q The next is for sections 2, 3, & 9 only. | \&.\e\*q Not used in OpenBSD. | ||
\&.\e\*q .Sh RETURN VALUES | \&.\e\*q .Sh RETURN VALUES | ||
\&.\e\*q The next is for sections 1, 6, 7, & 8 only. | \&.\e\*q For sections 2, 3, & 9 only. | ||
\&.\e\*q .Sh ENVIRONMENT | \&.\e\*q .Sh ENVIRONMENT | ||
\&.\e\*q For sections 1, 6, 7, & 8 only. | |||
\&.\e\*q .Sh FILES | \&.\e\*q .Sh FILES | ||
\&.\e\*q The next is for sections 1 & 8 only. | |||
\&.\e\*q .Sh EXIT STATUS | \&.\e\*q .Sh EXIT STATUS | ||
\&.\e\*q For sections 1, 6, & 8 only. | |||
\&.\e\*q .Sh EXAMPLES | \&.\e\*q .Sh EXAMPLES | ||
\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. | |||
\&.\e\*q .Sh DIAGNOSTICS | \&.\e\*q .Sh DIAGNOSTICS | ||
\&.\e\*q The next is for sections 2, 3, & 9 only. | \&.\e\*q For sections 1, 4, 6, 7, & 8 only. | ||
\&.\e\*q .Sh ERRORS | \&.\e\*q .Sh ERRORS | ||
\&.\e\*q For sections 2, 3, & 9 only. | |||
\&.\e\*q .Sh SEE ALSO | \&.\e\*q .Sh SEE ALSO | ||
\&.\e\*q .Xr foobar 1 | \&.\e\*q .Xr foobar 1 | ||
\&.\e\*q .Sh STANDARDS | \&.\e\*q .Sh STANDARDS | ||
|
|
||
\&.\e\*q .Sh CAVEATS | \&.\e\*q .Sh CAVEATS | ||
\&.\e\*q .Sh BUGS | \&.\e\*q .Sh BUGS | ||
\&.\e\*q .Sh SECURITY CONSIDERATIONS | \&.\e\*q .Sh SECURITY CONSIDERATIONS | ||
\&.\e\*q Not used in OpenBSD. | |||
.Ed | .Ed | ||
.Pp | .Pp | ||
The sections in a | The sections in an | ||
.Nm | .Nm | ||
document are conventionally ordered as they appear above. | document are conventionally ordered as they appear above. | ||
Sections should be composed as follows: | Sections should be composed as follows: | ||
.Bl -ohang -offset Ds | .Bl -ohang -offset Ds | ||
.It Em NAME | .It Em NAME | ||
The name(s) and a short description of the documented material. | The name(s) and a one line description of the documented material. | ||
The syntax for this as follows: | The syntax for this as follows: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Nm name0 | \&.Nm name0 , | ||
\&.Nm name1 | \&.Nm name1 , | ||
\&.Nm name2 | \&.Nm name2 | ||
\&.Nd a short description | \&.Nd a one line description | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
Multiple | |||
.Sq \&Nm | |||
names should be separated by commas. | |||
.Pp | |||
The | The | ||
.Sx \&Nm | .Sx \&Nm | ||
macro(s) must precede the | macro(s) must precede the | ||
|
|
||
For the first, utilities (sections 1, 6, and 8), this is | For the first, utilities (sections 1, 6, and 8), this is | ||
generally structured as follows: | generally structured as follows: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Nm foo | \&.Nm bar | ||
\&.Op Fl v | \&.Op Fl v | ||
\&.Op Fl o Ar file | \&.Op Fl o Ar file | ||
\&.Op Ar | \&.Op Ar | ||
\&.Nm bar | \&.Nm foo | ||
\&.Op Fl v | \&.Op Fl v | ||
\&.Op Fl o Ar file | \&.Op Fl o Ar file | ||
\&.Op Ar | \&.Op Ar | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
Commands should be ordered alphabetically. | |||
.Pp | |||
For the second, function calls (sections 2, 3, 9): | For the second, function calls (sections 2, 3, 9): | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Vt extern const char *global; | |||
\&.In header.h | \&.In header.h | ||
\&.Vt extern const char *global; | |||
\&.Ft "char *" | \&.Ft "char *" | ||
\&.Fn foo "const char *src" | \&.Fn foo "const char *src" | ||
\&.Ft "char *" | \&.Ft "char *" | ||
\&.Fn bar "const char *src" | \&.Fn bar "const char *src" | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
Ordering of | |||
.Sx \&In , | |||
.Sx \&Vt , | |||
.Sx \&Fn , | |||
and | |||
.Sx \&Fo | |||
macros should follow C header-file conventions. | |||
.Pp | |||
And for the third, configurations (section 4): | And for the third, configurations (section 4): | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Cd \*qit* at isa? port 0x2e\*q | \&.Cd \*qit* at isa? port 0x2e\*q | ||
|
|
||
.Sx \&Vt , | .Sx \&Vt , | ||
and | and | ||
.Sx \&Ft . | .Sx \&Ft . | ||
All of these macros are output on their own line. If two such | All of these macros are output on their own line. | ||
dissimilar macros are pair-wise invoked (except for | If two such dissimilar macros are pairwise invoked (except for | ||
.Sx \&Ft | .Sx \&Ft | ||
before | before | ||
.Sx \&Fo | .Sx \&Fo | ||
|
|
||
.Sx \&Nm | .Sx \&Nm | ||
macro, up to the next | macro, up to the next | ||
.Sx \&Nm , | .Sx \&Nm , | ||
.Sx \&Sx , | .Sx \&Sh , | ||
or | or | ||
.Sx \&Ss | .Sx \&Ss | ||
macro or the end of an enclosing block, whichever comes first. | macro or the end of an enclosing block, whichever comes first. | ||
.It Em DESCRIPTION | .It Em DESCRIPTION | ||
This expands upon the brief, one-line description in | This begins with an expansion of the brief, one line description in | ||
.Em NAME . | .Em NAME : | ||
It usually contains a break-down of the options (if documenting a | .Bd -literal -offset indent | ||
The | |||
\&.Nm | |||
utility does this, that, and the other. | |||
.Ed | |||
.Pp | |||
It usually follows with a breakdown of the options (if documenting a | |||
command), such as: | command), such as: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
The arguments are as follows: | The arguments are as follows: | ||
|
|
||
This is useful when implementing standard functions that may have side | This is useful when implementing standard functions that may have side | ||
effects or notable algorithmic implications. | effects or notable algorithmic implications. | ||
.It Em RETURN VALUES | .It Em RETURN VALUES | ||
This section is the dual of | This section documents the | ||
.Em EXIT STATUS , | return values of functions in sections 2, 3, and 9. | ||
which is used for commands. | |||
It documents the return values of functions in sections 2, 3, and 9. | |||
.Pp | .Pp | ||
See | See | ||
.Sx \&Rv . | .Sx \&Rv . | ||
.It Em ENVIRONMENT | .It Em ENVIRONMENT | ||
Documents any usages of environment variables, e.g., | Lists the environment variables used by the utility, | ||
.Xr environ 7 . | and explains the syntax and semantics of their values. | ||
The | |||
.Xr environ 7 | |||
manual provides examples of typical content and formatting. | |||
.Pp | .Pp | ||
See | See | ||
.Sx \&Ev . | .Sx \&Ev . | ||
.It Em FILES | .It Em FILES | ||
Documents files used. | Documents files used. | ||
It's helpful to document both the file and a short description of how | It's helpful to document both the file name and a short description of how | ||
the file is used (created, modified, etc.). | the file is used (created, modified, etc.). | ||
.Pp | .Pp | ||
See | See | ||
.Sx \&Pa . | .Sx \&Pa . | ||
.It Em EXIT STATUS | .It Em EXIT STATUS | ||
Command exit status for section 1, 6, and 8 manuals. | This section documents the | ||
This section is the dual of | command exit status for section 1, 6, and 8 utilities. | ||
.Em RETURN VALUES , | |||
which is used for functions. | |||
Historically, this information was described in | Historically, this information was described in | ||
.Em DIAGNOSTICS , | .Em DIAGNOSTICS , | ||
a practise that is now discouraged. | a practise that is now discouraged. | ||
|
|
||
.It Em EXAMPLES | .It Em EXAMPLES | ||
Example usages. | Example usages. | ||
This often contains snippets of well-formed, well-tested invocations. | This often contains snippets of well-formed, well-tested invocations. | ||
Make doubly sure that your examples work properly! | Make sure that examples work properly! | ||
.It Em DIAGNOSTICS | .It Em DIAGNOSTICS | ||
Documents error conditions. | Documents error conditions. | ||
This is most useful in section 4 manuals. | This is most useful in section 4 manuals. | ||
|
|
||
See | See | ||
.Sx \&St . | .Sx \&St . | ||
.It Em HISTORY | .It Em HISTORY | ||
The history of any manual without a | A brief history of the subject, including where support first appeared. | ||
.Em STANDARDS | |||
section should be described in this section. | |||
.It Em AUTHORS | .It Em AUTHORS | ||
Credits to authors, if applicable, should appear in this section. | Credits to the person or persons who wrote the code and/or documentation. | ||
Authors should generally be noted by both name and an e-mail address. | Authors should generally be noted by both name and email address. | ||
.Pp | .Pp | ||
See | See | ||
.Sx \&An . | .Sx \&An . | ||
.It Em CAVEATS | .It Em CAVEATS | ||
Explanations of common misuses and misunderstandings should be explained | Common misuses and misunderstandings should be explained | ||
in this section. | in this section. | ||
.It Em BUGS | .It Em BUGS | ||
Extant bugs should be described in this section. | Known bugs, limitations, and work-arounds should be described | ||
in this section. | |||
.It Em SECURITY CONSIDERATIONS | .It Em SECURITY CONSIDERATIONS | ||
Documents any security precautions that operators should consider. | Documents any security precautions that operators should consider. | ||
.El | .El | ||
.Sh MACRO SYNTAX | .Sh MACRO SYNTAX | ||
Macros are one to three three characters in length and begin with a | Macros are one to three three characters in length and begin with a | ||
control character , | control character, | ||
.Sq \&. , | .Sq \&. , | ||
at the beginning of the line. | at the beginning of the line. | ||
An arbitrary amount of whitespace may sit between the control character | An arbitrary amount of whitespace may sit between the control character | ||
|
|
||
.Pp | .Pp | ||
The | The | ||
.Em Callable | .Em Callable | ||
column indicates that the macro may be called subsequent to the initial | column indicates that the macro may also be called by passing its name | ||
line-macro. | as an argument to another macro. | ||
If a macro is not callable, then its invocation after the initial line | If a macro is not callable but its name appears as an argument | ||
macro is interpreted as opaque text, such that | to another macro, it is interpreted as opaque text. | ||
For example, | |||
.Sq \&.Fl \&Sh | .Sq \&.Fl \&Sh | ||
produces | produces | ||
.Sq Fl \&Sh . | .Sq Fl \&Sh . | ||
.Pp | .Pp | ||
The | The | ||
.Em Parsable | .Em Parsed | ||
column indicates whether the macro may be followed by further | column indicates whether the macro may call other macros by receiving | ||
(ostensibly callable) macros. | their names as arguments. | ||
If a macro is not parsable, subsequent macro invocations on the line | If a macro is not parsed but the name of another macro appears | ||
will be interpreted as opaque text. | as an argument, it is interpreted as opaque text. | ||
.Pp | .Pp | ||
The | The | ||
.Em Scope | .Em Scope | ||
|
|
||
Multi-line scope closed by an explicit closing macro. | Multi-line scope closed by an explicit closing macro. | ||
All macros contains bodies; only | All macros contains bodies; only | ||
.Sx \&Bf | .Sx \&Bf | ||
contains a head. | and | ||
.Pq optionally | |||
.Sx \&Bl | |||
contain a head. | |||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB | \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB | ||
\(lBbody...\(rB | \(lBbody...\(rB | ||
\&.Yc | \&.Yc | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXX" | .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXX" | ||
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope | .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope | ||
.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed | .It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed | ||
.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef | .It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef | ||
.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek | .It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek | ||
|
|
||
.Pc | .Pc | ||
don't have heads; only one | don't have heads; only one | ||
.Po | .Po | ||
.Sx \&It Fl column | .Sx \&It | ||
in | |||
.Sx \&Bl Fl column | |||
.Pc | .Pc | ||
has multiple heads. | has multiple heads. | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
|
|
||
\(lBbody...\(rB | \(lBbody...\(rB | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
.Bl -column -compact -offset indent "MacroX" "CallableX" "ParsableX" "closed by XXXXXXXXXXX" | .Bl -column -compact -offset indent "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" | ||
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope | .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope | ||
.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El | .It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El | ||
.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh | .It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh | ||
.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss | .It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss | ||
|
|
||
\(lBbody...\(rB \&Yc \(lBtail...\(rB | \(lBbody...\(rB \&Yc \(lBtail...\(rB | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
.Bl -column "MacroX" "CallableX" "ParsableX" "closed by XXXX" -compact -offset indent | .Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -compact -offset indent | ||
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope | .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope | ||
.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao | .It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao | ||
.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac | .It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac | ||
.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo | .It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo | ||
|
|
||
.El | .El | ||
.Ss Block partial-implicit | .Ss Block partial-implicit | ||
Like block full-implicit, but with single-line scope closed by | Like block full-implicit, but with single-line scope closed by | ||
.Sx Reserved Characters | .Sx Reserved Terms | ||
or end of line. | or end of line. | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB | \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
.Bl -column "MacroX" "CallableX" "ParsableX" -compact -offset indent | .Bl -column "MacroX" "CallableX" "ParsedX" -compact -offset indent | ||
.It Em Macro Ta Em Callable Ta Em Parsable | .It Em Macro Ta Em Callable Ta Em Parsed | ||
.It Sx \&Aq Ta Yes Ta Yes | .It Sx \&Aq Ta Yes Ta Yes | ||
.It Sx \&Bq Ta Yes Ta Yes | .It Sx \&Bq Ta Yes Ta Yes | ||
.It Sx \&Brq Ta Yes Ta Yes | .It Sx \&Brq Ta Yes Ta Yes | ||
|
|
||
.Sx In-line . | .Sx In-line . | ||
.Ss In-line | .Ss In-line | ||
Closed by | Closed by | ||
.Sx Reserved Characters , | .Sx Reserved Terms , | ||
end of line, fixed argument lengths, and/or subsequent macros. | end of line, fixed argument lengths, and/or subsequent macros. | ||
In-line macros have only text children. | In-line macros have only text children. | ||
If a number (or inequality) of arguments is | If a number (or inequality) of arguments is | ||
.Pq n , | .Pq n , | ||
then the macro accepts an arbitrary number of arguments. | then the macro accepts an arbitrary number of arguments. | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lbres...\(rb | \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB | ||
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... | \&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... | ||
\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN | \&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
.Bl -column "MacroX" "CallableX" "ParsableX" "Arguments" -compact -offset indent | .Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -compact -offset indent | ||
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments | .It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments | ||
.It Sx \&%A Ta \&No Ta \&No Ta >0 | .It Sx \&%A Ta \&No Ta \&No Ta >0 | ||
.It Sx \&%B Ta \&No Ta \&No Ta >0 | .It Sx \&%B Ta \&No Ta \&No Ta >0 | ||
.It Sx \&%C Ta \&No Ta \&No Ta >0 | .It Sx \&%C Ta \&No Ta \&No Ta >0 | ||
|
|
||
.It Sx \&%T Ta \&No Ta \&No Ta >0 | .It Sx \&%T Ta \&No Ta \&No Ta >0 | ||
.It Sx \&%U Ta \&No Ta \&No Ta >0 | .It Sx \&%U Ta \&No Ta \&No Ta >0 | ||
.It Sx \&%V Ta \&No Ta \&No Ta >0 | .It Sx \&%V Ta \&No Ta \&No Ta >0 | ||
.It Sx \&Ad Ta Yes Ta Yes Ta n | .It Sx \&Ad Ta Yes Ta Yes Ta >0 | ||
.It Sx \&An Ta Yes Ta Yes Ta n | .It Sx \&An Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Ap Ta Yes Ta Yes Ta 0 | .It Sx \&Ap Ta Yes Ta Yes Ta 0 | ||
.It Sx \&Ar Ta Yes Ta Yes Ta n | .It Sx \&Ar Ta Yes Ta Yes Ta n | ||
.It Sx \&At Ta Yes Ta Yes Ta 1 | .It Sx \&At Ta Yes Ta Yes Ta 1 | ||
|
|
||
.It Sx \&Bt Ta \&No Ta \&No Ta 0 | .It Sx \&Bt Ta \&No Ta \&No Ta 0 | ||
.It Sx \&Bx Ta Yes Ta Yes Ta n | .It Sx \&Bx Ta Yes Ta Yes Ta n | ||
.It Sx \&Cd Ta Yes Ta Yes Ta >0 | .It Sx \&Cd Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Cm Ta Yes Ta Yes Ta n | .It Sx \&Cm Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Db Ta \&No Ta \&No Ta 1 | .It Sx \&Db Ta \&No Ta \&No Ta 1 | ||
.It Sx \&Dd Ta \&No Ta \&No Ta >0 | .It Sx \&Dd Ta \&No Ta \&No Ta n | ||
.It Sx \&Dt Ta \&No Ta \&No Ta n | .It Sx \&Dt Ta \&No Ta \&No Ta n | ||
.It Sx \&Dv Ta Yes Ta Yes Ta n | .It Sx \&Dv Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Dx Ta Yes Ta Yes Ta n | .It Sx \&Dx Ta Yes Ta Yes Ta n | ||
.It Sx \&Em Ta Yes Ta Yes Ta >0 | .It Sx \&Em Ta Yes Ta Yes Ta >0 | ||
.It Sx \&En Ta \&No Ta \&No Ta 0 | .It Sx \&En Ta \&No Ta \&No Ta 0 | ||
.It Sx \&Er Ta Yes Ta Yes Ta >0 | .It Sx \&Er Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Es Ta \&No Ta \&No Ta 0 | .It Sx \&Es Ta \&No Ta \&No Ta 0 | ||
.It Sx \&Ev Ta Yes Ta Yes Ta n | .It Sx \&Ev Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Ex Ta \&No Ta \&No Ta n | .It Sx \&Ex Ta \&No Ta \&No Ta n | ||
.It Sx \&Fa Ta Yes Ta Yes Ta n | .It Sx \&Fa Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Fd Ta \&No Ta \&No Ta >0 | .It Sx \&Fd Ta \&No Ta \&No Ta >0 | ||
.It Sx \&Fl Ta Yes Ta Yes Ta n | .It Sx \&Fl Ta Yes Ta Yes Ta n | ||
.It Sx \&Fn Ta Yes Ta Yes Ta >0 | .It Sx \&Fn Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Fr Ta \&No Ta \&No Ta n | .It Sx \&Fr Ta \&No Ta \&No Ta n | ||
.It Sx \&Ft Ta Yes Ta Yes Ta n | .It Sx \&Ft Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Fx Ta Yes Ta Yes Ta n | .It Sx \&Fx Ta Yes Ta Yes Ta n | ||
.It Sx \&Hf Ta \&No Ta \&No Ta n | .It Sx \&Hf Ta \&No Ta \&No Ta n | ||
.It Sx \&Ic Ta Yes Ta Yes Ta >0 | .It Sx \&Ic Ta Yes Ta Yes Ta >0 | ||
.It Sx \&In Ta \&No Ta \&No Ta n | .It Sx \&In Ta \&No Ta \&No Ta 1 | ||
.It Sx \&Lb Ta \&No Ta \&No Ta 1 | .It Sx \&Lb Ta \&No Ta \&No Ta 1 | ||
.It Sx \&Li Ta Yes Ta Yes Ta n | .It Sx \&Li Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Lk Ta Yes Ta Yes Ta n | .It Sx \&Lk Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Lp Ta \&No Ta \&No Ta 0 | .It Sx \&Lp Ta \&No Ta \&No Ta 0 | ||
.It Sx \&Ms Ta Yes Ta Yes Ta >0 | .It Sx \&Ms Ta Yes Ta Yes Ta >0 | ||
.It Sx \&Mt Ta Yes Ta Yes Ta >0 | .It Sx \&Mt Ta Yes Ta Yes Ta >0 | ||
|
|
||
.Ss \&%A | .Ss \&%A | ||
Author name of an | Author name of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. Multiple authors should each be accorded their own | block. | ||
Multiple authors should each be accorded their own | |||
.Sx \%%A | .Sx \%%A | ||
line. Author names should be ordered with full or abbreviated | line. | ||
forename(s) first, then full surname. | Author names should be ordered with full or abbreviated forename(s) | ||
first, then full surname. | |||
.Ss \&%B | .Ss \&%B | ||
Book title of an | Book title of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. This macro may also be used in a non-bibliographic context when | block. | ||
This macro may also be used in a non-bibliographic context when | |||
referring to book titles. | referring to book titles. | ||
.Ss \&%C | .Ss \&%C | ||
Publication city or location of an | Publication city or location of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. | block. | ||
.Pp | |||
.Em Remarks : | |||
this macro is not implemented in | |||
.Xr groff 1 . | |||
.Ss \&%D | .Ss \&%D | ||
Publication date of an | Publication date of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. This should follow the reduced or canonical form syntax | block. | ||
described in | Recommended formats of arguments are | ||
.Sx Dates . | .Ar month day , year | ||
or just | |||
.Ar year . | |||
.Ss \&%I | .Ss \&%I | ||
Publisher or issuer name of an | Publisher or issuer name of an | ||
.Sx \&Rs | .Sx \&Rs | ||
|
|
||
.Ss \&%Q | .Ss \&%Q | ||
Institutional author (school, government, etc.) of an | Institutional author (school, government, etc.) of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. Multiple institutional authors should each be accorded their own | block. | ||
Multiple institutional authors should each be accorded their own | |||
.Sx \&%Q | .Sx \&%Q | ||
line. | line. | ||
.Ss \&%R | .Ss \&%R | ||
|
|
||
.Ss \&%T | .Ss \&%T | ||
Article title of an | Article title of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. This macro may also be used in a non-bibliographical context | block. | ||
when referring to article titles. | This macro may also be used in a non-bibliographical context when | ||
referring to article titles. | |||
.Ss \&%U | .Ss \&%U | ||
URI of reference document. | URI of reference document. | ||
.Ss \&%V | .Ss \&%V | ||
|
|
||
.Sx \&Rs | .Sx \&Rs | ||
block. | block. | ||
.Ss \&Ac | .Ss \&Ac | ||
Closes an | Close an | ||
.Sx \&Ao | .Sx \&Ao | ||
block. Does not have any tail arguments. | block. | ||
Does not have any tail arguments. | |||
.Ss \&Ad | .Ss \&Ad | ||
Address construct: usually in the context of an computational address in | Memory address. | ||
memory, not a physical (post) address. | Do not use this for postal addresses. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Ad [0,$] | .Dl \&.Ad [0,$] | ||
.D1 \&.Ad 0x00000000 | .Dl \&.Ad 0x00000000 | ||
.Ss \&An | .Ss \&An | ||
Author name. | Author name. | ||
This macro may alternatively accepts the following arguments, although | Requires either the name of an author or one of the following arguments: | ||
these may not be specified along with a parameter: | .Pp | ||
.Bl -tag -width 12n -offset indent | .Bl -tag -width "-nosplitX" -offset indent -compact | ||
.It Fl split | .It Fl split | ||
Renders a line break before each author listing. | Start a new output line before each subsequent invocation of | ||
.Sx \&An . | |||
.It Fl nosplit | .It Fl nosplit | ||
The opposite of | The opposite of | ||
.Fl split . | .Fl split . | ||
.El | .El | ||
.Pp | .Pp | ||
In the AUTHORS section, the default is not to split the first author | The default is | ||
listing, but all subsequent author listings, whether or not they're | .Fl nosplit . | ||
interspersed by other macros or text, are split. | The effect of selecting either of the | ||
Thus, specifying | |||
.Fl split | .Fl split | ||
will cause the first listing also to be split. | modes ends at the beginning of the | ||
If not in the AUTHORS section, the default is not to split. | .Em AUTHORS | ||
section. | |||
In the | |||
.Em AUTHORS | |||
section, the default is | |||
.Fl nosplit | |||
for the first author listing and | |||
.Fl split | |||
for all other author listings. | |||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.An -nosplit | .Dl \&.An -nosplit | ||
.D1 \&.An J. D. Ullman . | .Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv | ||
.Pp | |||
.Em Remarks : | |||
the effects of | |||
.Fl split | |||
or | |||
.Fl nosplit | |||
are re-set when entering the AUTHORS section, so if one specifies | |||
.Sx \&An Fl nosplit | |||
in the general document body, it must be re-specified in the AUTHORS | |||
section. | |||
.Ss \&Ao | .Ss \&Ao | ||
Begins a block enclosed by angled brackets. | Begin a block enclosed by angle brackets. | ||
Does not have any head arguments. | Does not have any head arguments. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac | .Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Aq . | .Sx \&Aq . | ||
.Ss \&Ap | .Ss \&Ap | ||
Inserts an apostrophe without any surrounding white-space. | Inserts an apostrophe without any surrounding whitespace. | ||
This is generally used as a grammatical device when referring to the verb | This is generally used as a grammatical device when referring to the verb | ||
form of a function: | form of a function. | ||
.Bd -literal -offset indent | .Pp | ||
\&.Fn execve Ap d | Examples: | ||
.Ed | .Dl \&.Fn execve \&Ap d | ||
.Ss \&Aq | .Ss \&Aq | ||
Encloses its arguments in angled brackets. | Encloses its arguments in angle brackets. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Fl -key= \&Ns \&Aq \&Ar val | .Dl \&.Fl -key= \&Ns \&Aq \&Ar val | ||
.Pp | .Pp | ||
.Em Remarks : | .Em Remarks : | ||
this macro is often abused for rendering URIs, which should instead use | this macro is often abused for rendering URIs, which should instead use | ||
|
|
||
.Ss \&Ar | .Ss \&Ar | ||
Command arguments. | Command arguments. | ||
If an argument is not provided, the string | If an argument is not provided, the string | ||
.Dq file ... | .Dq file ...\& | ||
is used as a default. | is used as a default. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Fl o \&Ns \&Ar file1 | .Dl \&.Fl o \&Ns \&Ar file1 | ||
.D1 \&.Ar | .Dl \&.Ar | ||
.D1 \&.Ar arg1 , arg2 . | .Dl \&.Ar arg1 , arg2 . | ||
.Ss \&At | .Ss \&At | ||
Formats an AT&T version. | Formats an AT&T version. | ||
Accepts at most one parameter: | Accepts one optional argument: | ||
.Bl -tag -width 12n -offset indent | .Pp | ||
.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact | |||
.It Cm v[1-7] | 32v | .It Cm v[1-7] | 32v | ||
A version of | A version of | ||
.At . | .At . | ||
.It Cm V[.[1-4]]? | .It Cm V[.[1-4]]? | ||
A system version of | A version of | ||
.At . | .At V . | ||
.El | .El | ||
.Pp | .Pp | ||
Note that these parameters do not begin with a hyphen. | Note that these arguments do not begin with a hyphen. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.At | .Dl \&.At | ||
.D1 \&.At V.1 | .Dl \&.At V.1 | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Bsx , | .Sx \&Bsx , | ||
|
|
||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
.Ss \&Bc | .Ss \&Bc | ||
Closes a | Close a | ||
.Sx \&Bo | .Sx \&Bo | ||
block. Does not have any tail arguments. | block. | ||
Does not have any tail arguments. | |||
.Ss \&Bd | .Ss \&Bd | ||
Begins a display block. | Begin a display block. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Bd -ragged -offset indent | .Bd -ragged -offset indent | ||
.Pf \. Sx \&Bd | .Pf \. Sx \&Bd | ||
.Fl type | .Fl Ns Ar type | ||
.Op Fl offset Ar width | .Op Fl offset Ar width | ||
.Op Fl compact | .Op Fl compact | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
A display is collection of macros or text which may be collectively | Display blocks are used to select a different indentation and | ||
offset or justified in a manner different from that | justification than the one used by the surrounding text. | ||
of the enclosing context. | They may contain both macro lines and text lines. | ||
By default, the block is preceded by a vertical space. | By default, a display block is preceded by a vertical space. | ||
.Pp | .Pp | ||
Each display is associated with a type, which must be one of the | The | ||
following arguments: | .Ar type | ||
.Bl -tag -width 12n -offset indent | must be one of the following: | ||
.It Fl ragged | .Bl -tag -width 13n -offset indent | ||
Only left-justify the block. | .It Fl centered | ||
.It Fl unfilled | Centre-justify each line. | ||
Do not justify the block at all. | Using this display type is not recommended; many | ||
.Nm | |||
implementations render it poorly. | |||
.It Fl filled | .It Fl filled | ||
Left- and right-justify the block. | Left- and right-justify the block. | ||
.It Fl literal | .It Fl literal | ||
Alias for | Do not justify the block at all. | ||
.Fl unfilled . | Preserve white space as it appears in the input. | ||
.It Fl centered | .It Fl ragged | ||
Centre-justify each line. | Only left-justify the block. | ||
.It Fl unfilled | |||
An alias for | |||
.Fl literal . | |||
.El | .El | ||
.Pp | .Pp | ||
The type must be provided first. | The | ||
Secondary arguments are as follows: | .Ar type | ||
.Bl -tag -width 12n -offset indent | must be provided first. | ||
.It Fl offset Ar val | Additional arguments may follow: | ||
Offset by the value of | .Bl -tag -width 13n -offset indent | ||
.Ar val , | .It Fl offset Ar width | ||
which is interpreted as one of the following, specified in order: | Indent the display by the | ||
.Ar width , | |||
which may be one of the following: | |||
.Bl -item | .Bl -item | ||
.It | .It | ||
As one of the pre-defined strings | One of the pre-defined strings | ||
.Ar indent , | .Cm indent , | ||
the width of standard indentation; | the width of standard indentation; | ||
.Ar indent-two , | .Cm indent-two , | ||
twice | twice | ||
.Ar indent ; | .Cm indent ; | ||
.Ar left , | .Cm left , | ||
which has no effect; | which has no effect; | ||
.Ar right , | .Cm right , | ||
which justifies to the right margin; and | which justifies to the right margin; or | ||
.Ar center , | .Cm center , | ||
which aligns around an imagined centre axis. | which aligns around an imagined centre axis. | ||
.It | .It | ||
As a precalculated width for a named macro. | A macro invocation, which selects a predefined width | ||
associated with that macro. | |||
The most popular is the imaginary macro | The most popular is the imaginary macro | ||
.Ar \&Ds , | .Ar \&Ds , | ||
which resolves to | which resolves to | ||
.Ar 6n . | .Sy 6n . | ||
.It | .It | ||
As a scaling unit following the syntax described in | A width using the syntax described in | ||
.Sx Scaling Widths . | .Sx Scaling Widths . | ||
.It | .It | ||
As the calculated string length of the opaque string. | An arbitrary string, which indents by the length of this string. | ||
.El | .El | ||
.Pp | .Pp | ||
If not provided an argument, it will be ignored. | When the argument is missing, | ||
.Fl offset | |||
is ignored. | |||
.It Fl compact | .It Fl compact | ||
Do not assert a vertical space before the block. | Do not assert vertical space before the display. | ||
.El | .El | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Bd \-unfilled \-offset two-indent \-compact | \&.Bd \-literal \-offset indent \-compact | ||
Hello world. | Hello world. | ||
\&.Ed | \&.Ed | ||
.Ed | .Ed | ||
|
|
||
argument are equivalent, as are | argument are equivalent, as are | ||
.Fl symbolic | .Fl symbolic | ||
and | and | ||
.Cm \&Sy, | .Cm \&Sy , | ||
and | and | ||
.Fl literal | .Fl literal | ||
and | and | ||
|
|
||
See also | See also | ||
.Sx \&Li , | .Sx \&Li , | ||
.Sx \&Ef , | .Sx \&Ef , | ||
.Sx \&Em , | |||
and | and | ||
.Sx \&Sy . | .Sx \&Sy . | ||
.Ss \&Bk | .Ss \&Bk | ||
Begins a collection of macros or text not breaking the line. | For each macro, keep its output together on the same output line, | ||
Its syntax is as follows: | until the end of the macro or the end of the input line is reached, | ||
whichever comes first. | |||
Line breaks in text lines are unaffected. | |||
The syntax is as follows: | |||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Bk Fl words | .D1 Pf \. Sx \&Bk Fl words | ||
.Pp | .Pp | ||
Subsequent arguments are ignored. | |||
The | The | ||
.Fl words | .Fl words | ||
argument is required. | argument is required; additional arguments are ignored. | ||
.Pp | .Pp | ||
Each line within a keep block is kept intact, so the following example | The following example will not break within each | ||
will not break within each | |||
.Sx \&Op | .Sx \&Op | ||
macro line: | macro line: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
|
|
||
Be careful in using over-long lines within a keep block! | Be careful in using over-long lines within a keep block! | ||
Doing so will clobber the right margin. | Doing so will clobber the right margin. | ||
.Ss \&Bl | .Ss \&Bl | ||
Begins a list composed of one or more list entries. | Begin a list. | ||
Its syntax is as follows: | Lists consist of items specified using the | ||
.Sx \&It | |||
macro, containing a head or a body or both. | |||
The list syntax is as follows: | |||
.Bd -ragged -offset indent | .Bd -ragged -offset indent | ||
.Pf \. Sx \&Bl | .Pf \. Sx \&Bl | ||
.Fl type | .Fl Ns Ar type | ||
.Op Fl width Ar val | .Op Fl width Ar val | ||
.Op Fl offset Ar val | .Op Fl offset Ar val | ||
.Op Fl compact | .Op Fl compact | ||
.Op HEAD ... | .Op HEAD ... | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
A list is associated with a type, which is a required argument. | The list | ||
Other arguments are | .Ar type | ||
.Fl width , | is mandatory and must be specified first. | ||
defined per-type as accepting a literal or | The | ||
.Fl width | |||
and | |||
.Fl offset | |||
arguments accept | |||
.Sx Scaling Widths | .Sx Scaling Widths | ||
value; | or use the length of the given string. | ||
.Fl offset , | The | ||
also accepting a literal or | .Fl offset | ||
.Sx Scaling Widths | is a global indentation for the whole list, affecting both item heads | ||
value setting the list's global offset; and | and bodies. | ||
.Fl compact , | For those list types supporting it, the | ||
suppressing the default vertical space printed before each list entry. | .Fl width | ||
A list entry is specified by the | argument requests an additional indentation of item bodies, | ||
.Sx \&It | to be added to the | ||
macro, which consists of a head and optional body (depending on the list | .Fl offset . | ||
type). | Unless the | ||
.Fl compact | |||
argument is specified, list entries are separated by vertical space. | |||
.Pp | |||
A list must specify one of the following list types: | A list must specify one of the following list types: | ||
.Bl -tag -width 12n -offset indent | .Bl -tag -width 12n -offset indent | ||
.It Fl bullet | .It Fl bullet | ||
A list offset by a bullet. | No item heads can be specified, but a bullet will be printed at the head | ||
The head of list entries must be empty. | of each item. | ||
List entry bodies are positioned after the bullet. | Item bodies start on the same output line as the bullet | ||
The | and are indented according to the | ||
.Fl width | .Fl width | ||
argument varies the width of list bodies' left-margins. | argument. | ||
.It Fl column | .It Fl column | ||
A columnated list. | A columnated list. | ||
The | The | ||
.Fl width | .Fl width | ||
argument has no effect. | argument has no effect; instead, each argument specifies the width | ||
The number of columns is specified as parameters to the | of one column, using either the | ||
.Sx \&Bl | |||
macro. | |||
These dictate the width of columns either as | |||
.Sx Scaling Widths | .Sx Scaling Widths | ||
or literal text. | syntax or the string length of the argument. | ||
If the initial macro of a | If the first line of the body of a | ||
.Fl column | .Fl column | ||
list is not an | list is not an | ||
.Sx \&It , | |||
an | |||
.Sx \&It | .Sx \&It | ||
context spanning each line is implied until an | macro line, | ||
.Sx \&It | .Sx \&It | ||
line macro is encountered, at which point list bodies are interpreted as | contexts spanning one input line each are implied until an | ||
.Sx \&It | |||
macro line is encountered, at which point items start being interpreted as | |||
described in the | described in the | ||
.Sx \&It | .Sx \&It | ||
documentation. | documentation. | ||
.It Fl dash | .It Fl dash | ||
A list offset by a dash (hyphen). | Like | ||
The head of list entries must be empty. | .Fl bullet , | ||
List entry bodies are positioned past the dash. | except that dashes are used in place of bullets. | ||
The | |||
.Fl width | |||
argument varies the width of list bodies' left-margins. | |||
.It Fl diag | .It Fl diag | ||
Like | Like | ||
.Fl inset , | .Fl inset , | ||
but with additional formatting to the head. | except that item heads are not parsed for macro invocations. | ||
The | .\" but with additional formatting to the head. | ||
.Fl width | |||
argument varies the width of list bodies' left-margins. | |||
.It Fl enum | .It Fl enum | ||
An enumerated list offset by the enumeration from 1. | A numbered list. | ||
The head of list entries must be empty. | Formatted like | ||
List entry bodies are positioned after the enumeration. | .Fl bullet , | ||
The | except that cardinal numbers are used in place of bullets, | ||
.Fl width | starting at 1. | ||
argument varies the width of list bodies' left-margins. | |||
.It Fl hang | .It Fl hang | ||
Like | Like | ||
.Fl tag , | .Fl tag , | ||
but instead of list bodies positioned after the head, they trail the | except that the first lines of item bodies are not indented, but follow | ||
head text. | the item heads like in | ||
The | .Fl inset | ||
.Fl width | lists. | ||
argument varies the width of list bodies' left-margins. | |||
.It Fl hyphen | .It Fl hyphen | ||
Synonym for | Synonym for | ||
.Fl dash . | .Fl dash . | ||
.It Fl inset | .It Fl inset | ||
List bodies follow the list head. | Item bodies follow items heads on the same line, using normal inter-word | ||
The | spacing. | ||
Bodies are not indented, and the | |||
.Fl width | .Fl width | ||
argument is ignored. | argument is ignored. | ||
.It Fl item | .It Fl item | ||
This produces blocks of text. | No item heads can be specified, and none are printed. | ||
The head of list entries must be empty. | Bodies are not indented, and the | ||
The | |||
.Fl width | .Fl width | ||
argument is ignored. | argument is ignored. | ||
.It Fl ohang | .It Fl ohang | ||
List bodies are positioned on the line following the head. | Item bodies start on the line following item heads and are not indented. | ||
The | The | ||
.Fl width | .Fl width | ||
argument is ignored. | argument is ignored. | ||
.It Fl tag | .It Fl tag | ||
A list offset by list entry heads. List entry bodies are positioned | Item bodies are indented according to the | ||
after the head as specified by the | |||
.Fl width | .Fl width | ||
argument. | argument. | ||
When an item head fits inside the indentation, the item body follows | |||
this head on the same output line. | |||
Otherwise, the body starts on the output line following the head. | |||
.El | .El | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&El | |||
and | |||
.Sx \&It . | .Sx \&It . | ||
.Ss \&Bo | .Ss \&Bo | ||
Begins a block enclosed by square brackets. | Begin a block enclosed by square brackets. | ||
Does not have any head arguments. | Does not have any head arguments. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent -compact | ||
\&.Bo 1 , | \&.Bo 1 , | ||
\&.Dv BUFSIZ \&Bc | \&.Dv BUFSIZ \&Bc | ||
.Ed | .Ed | ||
|
|
||
Encloses its arguments in square brackets. | Encloses its arguments in square brackets. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Bq 1 , \&Dv BUFSIZ | .Dl \&.Bq 1 , \&Dv BUFSIZ | ||
.Pp | .Pp | ||
.Em Remarks : | .Em Remarks : | ||
this macro is sometimes abused to emulate optional arguments for | this macro is sometimes abused to emulate optional arguments for | ||
|
|
||
See also | See also | ||
.Sx \&Bo . | .Sx \&Bo . | ||
.Ss \&Brc | .Ss \&Brc | ||
Closes a | Close a | ||
.Sx \&Bro | .Sx \&Bro | ||
block. Does not have any tail arguments. | block. | ||
Does not have any tail arguments. | |||
.Ss \&Bro | .Ss \&Bro | ||
Begins a block enclosed by curly braces. | Begin a block enclosed by curly braces. | ||
Does not have any head arguments. | Does not have any head arguments. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent -compact | ||
\&.Bro 1 , ... , | \&.Bro 1 , ... , | ||
\&.Va n \&Brc | \&.Va n \&Brc | ||
.Ed | .Ed | ||
|
|
||
Encloses its arguments in curly braces. | Encloses its arguments in curly braces. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Brq 1 , ... , \&Va n | .Dl \&.Brq 1 , ... , \&Va n | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Bro . | .Sx \&Bro . | ||
|
|
||
no argument is provided. | no argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Bsx 1.0 | .Dl \&.Bsx 1.0 | ||
.D1 \&.Bsx | .Dl \&.Bsx | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
.Sx \&Ux . | .Sx \&Ux . | ||
.Ss \&Bt | .Ss \&Bt | ||
Prints | Prints | ||
.Dq is currently in beta test. | .Dq is currently in beta test . | ||
.Ss \&Bx | .Ss \&Bx | ||
Format the BSD version provided as an argument, or a default value if no | Format the BSD version provided as an argument, or a default value if no | ||
argument is provided. | argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Bx 4.4 | .Dl \&.Bx 4.4 | ||
.D1 \&.Bx | .Dl \&.Bx | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
.Ss \&Cd | .Ss \&Cd | ||
Configuration declaration. | Kernel configuration declaration. | ||
This denotes strings accepted by | This denotes strings accepted by | ||
.Xr config 8 . | .Xr config 8 . | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Cd device le0 at scode? | .Dl \&.Cd device le0 at scode? | ||
.Pp | .Pp | ||
.Em Remarks : | .Em Remarks : | ||
this macro is commonly abused by using quoted literals to retain | this macro is commonly abused by using quoted literals to retain | ||
white-space and align consecutive | whitespace and align consecutive | ||
.Sx \&Cd | .Sx \&Cd | ||
declarations. | declarations. | ||
This practise is discouraged. | This practise is discouraged. | ||
|
|
||
Useful when specifying configuration options or keys. | Useful when specifying configuration options or keys. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Cm ControlPath | .Dl \&.Cm ControlPath | ||
.D1 \&.Cm ControlMaster | .Dl \&.Cm ControlMaster | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Fl . | .Sx \&Fl . | ||
|
|
||
It is followed by a newline. | It is followed by a newline. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.D1 \&Fl abcdefgh | .Dl \&.D1 \&Fl abcdefgh | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Bd | .Sx \&Bd | ||
and | and | ||
.Sx \&Dl . | .Sx \&Dl . | ||
.Ss \&Db | .Ss \&Db | ||
Start a debugging context. | Switch debugging mode. | ||
This macro is parsed, but generally ignored. | |||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Db Cm on | off | .D1 Pf \. Sx \&Db Cm on | off | ||
.Pp | |||
This macro is ignored by | |||
.Xr mandoc 1 . | |||
.Ss \&Dc | .Ss \&Dc | ||
Closes a | Close a | ||
.Sx \&Do | .Sx \&Do | ||
block. Does not have any tail arguments. | block. | ||
Does not have any tail arguments. | |||
.Ss \&Dd | .Ss \&Dd | ||
Document date. | Document date. | ||
This is the mandatory first macro of any | This is the mandatory first macro of any | ||
|
|
||
manual. | manual. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Dd Cm date | .D1 Pf \. Sx \&Dd Ar month day , year | ||
.Pp | .Pp | ||
The | The | ||
.Cm date | .Ar month | ||
field may be either | is the full English month name, the | ||
.Ar $\&Mdocdate$ , | .Ar day | ||
which signifies the current manual revision date dictated by | is an optionally zero-padded numeral, and the | ||
.Ar year | |||
is the full four-digit year. | |||
.Pp | |||
Other arguments are not portable; the | |||
.Xr mandoc 1 | |||
utility handles them as follows: | |||
.Bl -dash -offset 3n -compact | |||
.It | |||
To have the date automatically filled in by the | |||
.Ox | |||
version of | |||
.Xr cvs 1 , | .Xr cvs 1 , | ||
or instead a valid canonical date as specified by | the special string | ||
.Sx Dates . | .Dq $\&Mdocdate$ | ||
If a date does not conform, the current date is used instead. | can be given as an argument. | ||
.It | |||
A few alternative date formats are accepted as well | |||
and converted to the standard form. | |||
.It | |||
If a date string cannot be parsed, it is used verbatim. | |||
.It | |||
If no date string is given, the current date is used. | |||
.El | |||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Dd $\&Mdocdate$ | .Dl \&.Dd $\&Mdocdate$ | ||
.D1 \&.Dd $\&Mdocdate: July 21 2007$ | .Dl \&.Dd $\&Mdocdate: July 21 2007$ | ||
.D1 \&.Dd July 21, 2007 | .Dl \&.Dd July 21, 2007 | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Dt | .Sx \&Dt | ||
|
|
||
It is followed by a newline. | It is followed by a newline. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Dl % mandoc mdoc.7 | less | .Dl \&.Dl % mandoc mdoc.7 \e(ba less | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Bd | .Sx \&Bd | ||
and | and | ||
.Sx \&D1 . | .Sx \&D1 . | ||
.Ss \&Do | .Ss \&Do | ||
Begins a block enclosed by double quotes. Does not have any head | Begin a block enclosed by double quotes. | ||
arguments. | Does not have any head arguments. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot | .Bd -literal -offset indent -compact | ||
\&.Do | |||
April is the cruellest month | |||
\&.Dc | |||
\e(em T.S. Eliot | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Dq . | .Sx \&Dq . | ||
.Ss \&Dq | .Ss \&Dq | ||
Encloses its arguments in double quotes. | Encloses its arguments in | ||
.Dq typographic | |||
double-quotes. | |||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent -compact | .Bd -literal -offset indent -compact | ||
|
|
||
.Ed | .Ed | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Qq , | |||
.Sx \&Sq , | |||
and | |||
.Sx \&Do . | .Sx \&Do . | ||
.Ss \&Dt | .Ss \&Dt | ||
Document title. | Document title. | ||
|
|
||
.Bd -ragged -offset indent | .Bd -ragged -offset indent | ||
.Pf \. Sx \&Dt | .Pf \. Sx \&Dt | ||
.Oo | .Oo | ||
.Cm title | .Ar title | ||
.Oo | .Oo | ||
.Cm section | .Ar section | ||
.Op Cm volume | arch | .Op Ar volume | arch | ||
.Oc | .Oc | ||
.Oc | .Oc | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
Its arguments are as follows: | Its arguments are as follows: | ||
.Bl -tag -width Ds -offset Ds | .Bl -tag -width Ds -offset Ds | ||
.It Cm title | .It Ar title | ||
The document's title (name), defaulting to | The document's title (name), defaulting to | ||
.Qq UNKNOWN | .Dq UNKNOWN | ||
if unspecified. | if unspecified. | ||
It should be capitalised. | It should be capitalised. | ||
.It Cm section | .It Ar section | ||
The manual section. | The manual section. | ||
This may be one of | This may be one of | ||
.Ar 1 | .Ar 1 | ||
|
|
||
.Ar paper | .Ar paper | ||
.Pq paper . | .Pq paper . | ||
It should correspond to the manual's filename suffix and defaults to | It should correspond to the manual's filename suffix and defaults to | ||
.Qq 1 | .Dq 1 | ||
if unspecified. | if unspecified. | ||
.It Cm volume | .It Ar volume | ||
This overrides the volume inferred from | This overrides the volume inferred from | ||
.Ar section . | .Ar section . | ||
This field is optional, and if specified, must be one of | This field is optional, and if specified, must be one of | ||
|
|
||
or | or | ||
.Ar CON | .Ar CON | ||
.Pq contributed manuals . | .Pq contributed manuals . | ||
.It Cm arch | .It Ar arch | ||
This specifies a specific relevant architecture. | This specifies a specific relevant architecture. | ||
If | If | ||
.Cm volume | .Ar volume | ||
is not provided, it may be used in its place, else it may be used | is not provided, it may be used in its place, else it may be used | ||
subsequent that. | subsequent that. | ||
It, too, is optional. | It, too, is optional. | ||
|
|
||
.Ar luna88k , | .Ar luna88k , | ||
.Ar mac68k , | .Ar mac68k , | ||
.Ar macppc , | .Ar macppc , | ||
.Ar mips64 , | |||
.Ar mvme68k , | .Ar mvme68k , | ||
.Ar mvme88k , | .Ar mvme88k , | ||
.Ar mvmeppc , | .Ar mvmeppc , | ||
|
|
||
.El | .El | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Dt FOO 1 | .Dl \&.Dt FOO 1 | ||
.D1 \&.Dt FOO 4 KM | .Dl \&.Dt FOO 4 KM | ||
.D1 \&.Dt FOO 9 i386 | .Dl \&.Dt FOO 9 i386 | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Dd | .Sx \&Dd | ||
|
|
||
Defined variables such as preprocessor constants. | Defined variables such as preprocessor constants. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Dv BUFSIZ | .Dl \&.Dv BUFSIZ | ||
.D1 \&.Dv STDOUT_FILENO | .Dl \&.Dv STDOUT_FILENO | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Er . | .Sx \&Er . | ||
|
|
||
value if no argument is provided. | value if no argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Dx 2.4.1 | .Dl \&.Dx 2.4.1 | ||
.D1 \&.Dx | .Dl \&.Dx | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
.Sx \&Eo . | .Sx \&Eo . | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Ec Op Cm TERM | .D1 Pf \. Sx \&Ec Op Ar TERM | ||
.Pp | .Pp | ||
The | The | ||
.Cm TERM | .Ar TERM | ||
argument is used as the enclosure tail, for example, specifying \e(rq | argument is used as the enclosure tail, for example, specifying \e(rq | ||
will emulate | will emulate | ||
.Sx \&Dc . | .Sx \&Dc . | ||
|
|
||
End a display context started by | End a display context started by | ||
.Sx \&Bd . | .Sx \&Bd . | ||
.Ss \&Ef | .Ss \&Ef | ||
Ends a font mode context started by | End a font mode context started by | ||
.Sx \&Bf . | .Sx \&Bf . | ||
.Ss \&Ek | .Ss \&Ek | ||
Ends a keep context started by | End a keep context started by | ||
.Sx \&Bk . | .Sx \&Bk . | ||
.Ss \&El | .Ss \&El | ||
Ends a list context started by | End a list context started by | ||
.Sx \&Bl . | .Sx \&Bl . | ||
.Pp | .Pp | ||
See also | See also | ||
|
|
||
stylistically decorating technical terms. | stylistically decorating technical terms. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Em Warnings! | .Dl \&.Em Warnings! | ||
.D1 \&.Em Remarks : | .Dl \&.Em Remarks : | ||
.Pp | |||
See also | |||
.Sx \&Bf , | |||
.Sx \&Sy , | |||
and | |||
.Sx \&Li . | |||
.Ss \&En | .Ss \&En | ||
This macro is obsolete and not implemented. | This macro is obsolete and not implemented in | ||
.Xr mandoc 1 . | |||
.Ss \&Eo | .Ss \&Eo | ||
An arbitrary enclosure. | An arbitrary enclosure. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Eo Op Cm TERM | .D1 Pf \. Sx \&Eo Op Ar TERM | ||
.Pp | .Pp | ||
The | The | ||
.Cm TERM | .Ar TERM | ||
argument is used as the enclosure head, for example, specifying \e(lq | argument is used as the enclosure head, for example, specifying \e(lq | ||
will emulate | will emulate | ||
.Sx \&Do . | .Sx \&Do . | ||
|
|
||
Display error constants. | Display error constants. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Er EPERM | .Dl \&.Er EPERM | ||
.D1 \&.Er ENOENT | .Dl \&.Er ENOENT | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Dv . | .Sx \&Dv . | ||
|
|
||
.Xr environ 7 . | .Xr environ 7 . | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Ev DISPLAY | .Dl \&.Ev DISPLAY | ||
.D1 \&.Ev PATH | .Dl \&.Ev PATH | ||
.Ss \&Ex | .Ss \&Ex | ||
Inserts text regarding a utility's exit values. | Insert a standard sentence regarding exit values. | ||
This macro must have first the | Its syntax is as follows: | ||
.Fl std | .Pp | ||
argument specified, then an optional | .D1 Pf \. Sx \&Ex Fl std Op Ar utility | ||
.Ar utility . | .Pp | ||
If | When | ||
.Ar utility | .Ar utility | ||
is not provided, the document's name as stipulated in | is not specified, the document's name set by | ||
.Sx \&Nm | .Sx \&Nm | ||
is provided. | is used. | ||
.Pp | |||
See also | |||
.Sx \&Rv . | |||
.Ss \&Fa | .Ss \&Fa | ||
Function argument. | Function argument. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
|
|
||
the last argument will also have a trailing comma. | the last argument will also have a trailing comma. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Fa \(dqconst char *p\(dq | .Dl \&.Fa \(dqconst char *p\(dq | ||
.D1 \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq | .Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq | ||
.D1 \&.Fa foo | .Dl \&.Fa foo | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Fo . | .Sx \&Fo . | ||
.Ss \&Fc | .Ss \&Fc | ||
Ends a function context started by | End a function context started by | ||
.Sx \&Fo . | .Sx \&Fo . | ||
.Ss \&Fd | .Ss \&Fd | ||
Historically used to document include files. | Historically used to document include files. | ||
|
|
||
output. | output. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Fl a b c | .Dl \&.Fl a b c | ||
.D1 \&.Fl \&Pf a b | .Dl \&.Fl \&Pf a b | ||
.D1 \&.Fl | .Dl \&.Fl | ||
.D1 \&.Op \&Fl o \&Ns \&Ar file | .Dl \&.Op \&Fl o \&Ns \&Ar file | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Cm . | .Sx \&Cm . | ||
|
|
||
Its syntax is as follows: | Its syntax is as follows: | ||
.Bd -ragged -offset indent | .Bd -ragged -offset indent | ||
.Pf \. Ns Sx \&Fn | .Pf \. Ns Sx \&Fn | ||
.Op Cm functype | .Op Ar functype | ||
.Cm funcname | .Ar funcname | ||
.Op Oo Cm argtype Oc Cm argname | .Op Oo Ar argtype Oc Ar argname | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
Function arguments are surrounded in parenthesis and | Function arguments are surrounded in parenthesis and | ||
|
|
||
If no arguments are specified, blank parenthesis are output. | If no arguments are specified, blank parenthesis are output. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Fn "int funcname" "int arg0" "int arg1" | .Dl \&.Fn \*qint funcname\*q \*qint arg0\*q \*qint arg1\*q | ||
.D1 \&.Fn funcname "int arg0" | .Dl \&.Fn funcname \*qint arg0\*q | ||
.D1 \&.Fn funcname arg0 | .Dl \&.Fn funcname arg0 | ||
.Bd -literal -offset indent -compact | .Bd -literal -offset indent -compact | ||
\&.Ft functype | \&.Ft functype | ||
\&.Fn funcname | \&.Fn funcname | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
When referring to a function documented in another manual page, use | |||
.Sx \&Xr | |||
instead. | |||
See also | See also | ||
.Sx MANUAL STRUCTURE | .Sx MANUAL STRUCTURE | ||
and | and | ||
|
|
||
.Sx \&Fn . | .Sx \&Fn . | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Fo Cm funcname | .D1 Pf \. Sx \&Fo Ar funcname | ||
.Pp | .Pp | ||
Invocations usually occur in the following context: | Invocations usually occur in the following context: | ||
.Bd -ragged -offset indent | .Bd -ragged -offset indent | ||
.Pf \. Sx \&Ft Cm functype | .Pf \. Sx \&Ft Ar functype | ||
.br | .br | ||
.Pf \. Sx \&Fo Cm funcname | .Pf \. Sx \&Fo Ar funcname | ||
.br | .br | ||
.Pf \. Sx \&Fa Oo Cm argtype Oc Cm argname | .Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname | ||
.br | .br | ||
\.\.\. | \&.\.\. | ||
.br | .br | ||
.Pf \. Sx \&Fc | .Pf \. Sx \&Fc | ||
.Ed | .Ed | ||
|
|
||
.Sx \&Fa , | .Sx \&Fa , | ||
.Sx \&Fc , | .Sx \&Fc , | ||
and | and | ||
.Sx \&Ft . | |||
.Ss \&Ft | .Ss \&Ft | ||
A function type. | A function type. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Ft Cm functype | .D1 Pf \. Sx \&Ft Ar functype | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Ft int | .Dl \&.Ft int | ||
.Bd -literal -offset indent -compact | .Bd -literal -offset indent -compact | ||
\&.Ft functype | \&.Ft functype | ||
\&.Fn funcname | \&.Fn funcname | ||
|
|
||
and | and | ||
.Sx \&Fo . | .Sx \&Fo . | ||
.Ss \&Fx | .Ss \&Fx | ||
Format the FreeBSD version provided as an argument, or a default value | Format the | ||
.Fx | |||
version provided as an argument, or a default value | |||
if no argument is provided. | if no argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Fx 7.1 | .Dl \&.Fx 7.1 | ||
.D1 \&.Fx | .Dl \&.Fx | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
but used for instructions rather than values. | but used for instructions rather than values. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Ic hash | .Dl \&.Ic hash | ||
.D1 \&.Ic alias | .Dl \&.Ic alias | ||
.Pp | .Pp | ||
Note that using | Note that using | ||
.Sx \&Bd No Fl literal | .Sx \&Bd Fl literal | ||
or | or | ||
.Sx \&D1 | .Sx \&D1 | ||
is preferred for displaying code; the | is preferred for displaying code; the | ||
|
|
||
macro is used when referring to specific instructions. | macro is used when referring to specific instructions. | ||
.Ss \&In | .Ss \&In | ||
An | An | ||
.Qq include | .Dq include | ||
file. | file. | ||
In the | In the | ||
.Em SYNOPSIS | .Em SYNOPSIS | ||
section (only if invoked as the line macro), the first argument is | section (only if invoked as the line macro), the first argument is | ||
preceded by | preceded by | ||
.Qq #include , | .Dq #include , | ||
the arguments is enclosed in angled braces. | the arguments is enclosed in angle brackets. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.In sys/types | .Dl \&.In sys/types | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx MANUAL STRUCTURE . | .Sx MANUAL STRUCTURE . | ||
|
|
||
.Fl diag | .Fl diag | ||
have the following syntax: | have the following syntax: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&It Cm args | .D1 Pf \. Sx \&It Ar args | ||
.Pp | .Pp | ||
Lists of type | Lists of type | ||
.Fl bullet , | .Fl bullet , | ||
|
|
||
Calling the pseudo-macro | Calling the pseudo-macro | ||
.Sq \&Ta | .Sq \&Ta | ||
will open a new phrase scope (this must occur on a macro line to be | will open a new phrase scope (this must occur on a macro line to be | ||
interpreted as a macro). Note that the tab phrase delimiter may only be | interpreted as a macro). | ||
used within the | Note that the tab phrase delimiter may only be used within the | ||
.Sx \&It | .Sx \&It | ||
line itself. | line itself. | ||
Subsequent this, only the | Subsequent this, only the | ||
|
|
||
.Sx \&It , | .Sx \&It , | ||
for example, | for example, | ||
.Pp | .Pp | ||
.D1 .It \(dqcol1 ; <TAB> col2 ;\(dq \&; | .Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&; | ||
.Pp | .Pp | ||
will preserve the semicolon whitespace except for the last. | will preserve the semicolon whitespace except for the last. | ||
.Pp | .Pp | ||
|
|
||
Specify a library. | Specify a library. | ||
The syntax is as follows: | The syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Lb Cm library | .D1 Pf \. Sx \&Lb Ar library | ||
.Pp | .Pp | ||
The | The | ||
.Cm library | .Ar library | ||
parameter may be a system library, such as | parameter may be a system library, such as | ||
.Cm libz | .Ar libz | ||
or | or | ||
.Cm libpam , | .Ar libpam , | ||
in which case a small library description is printed next to the linker | in which case a small library description is printed next to the linker | ||
invocation; or a custom library, in which case the library name is | invocation; or a custom library, in which case the library name is | ||
printed in quotes. | printed in quotes. | ||
|
|
||
.Sx MANUAL STRUCTURE . | .Sx MANUAL STRUCTURE . | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Lb libz | .Dl \&.Lb libz | ||
.D1 \&.Lb mdoc | .Dl \&.Lb mdoc | ||
.Ss \&Li | .Ss \&Li | ||
Denotes text that should be in a literal font mode. | Denotes text that should be in a literal font mode. | ||
Note that this is a presentation term and should not be used for | Note that this is a presentation term and should not be used for | ||
stylistically decorating technical terms. | stylistically decorating technical terms. | ||
.Pp | |||
See also | |||
.Sx \&Bf , | |||
.Sx \&Sy , | |||
and | |||
.Sx \&Em . | |||
.Ss \&Lk | .Ss \&Lk | ||
Format a hyperlink. | Format a hyperlink. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Lk Cm uri Op Cm name | .D1 Pf \. Sx \&Lk Ar uri Op Ar name | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Lk http://bsd.lv "The BSD.lv Project" | .Dl \&.Lk http://bsd.lv \*qThe BSD.lv Project\*q | ||
.D1 \&.Lk http://bsd.lv | .Dl \&.Lk http://bsd.lv | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Mt . | .Sx \&Mt . | ||
|
|
||
Synonym for | Synonym for | ||
.Sx \&Pp . | .Sx \&Pp . | ||
.Ss \&Ms | .Ss \&Ms | ||
Display a mathematical symbol. | |||
Its syntax is as follows: | |||
.Pp | |||
.D1 Pf \. Sx \&Ms Ar symbol | |||
.Pp | |||
Examples: | |||
.Dl \&.Ms sigma | |||
.Dl \&.Ms aleph | |||
.Ss \&Mt | .Ss \&Mt | ||
Format a | Format a | ||
.Qq mailto: | .Dq mailto: | ||
hyperlink. | hyperlink. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Mt Cm address | .D1 Pf \. Sx \&Mt Ar address | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Mt discuss@manpages.bsd.lv | .Dl \&.Mt discuss@manpages.bsd.lv | ||
.Ss \&Nd | .Ss \&Nd | ||
A one-line description of the manual's content. | A one line description of the manual's content. | ||
This may only be invoked in the | This may only be invoked in the | ||
.Em SYNOPSIS | .Em SYNOPSIS | ||
section subsequent the | section subsequent the | ||
|
|
||
macro. | macro. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Sx \&Nd mdoc language reference | .Dl \&.Sx \&Nd mdoc language reference | ||
.D1 \&.Sx \&Nd format and display UNIX manuals | .Dl \&.Sx \&Nd format and display UNIX manuals | ||
.Pp | .Pp | ||
The | The | ||
.Sx \&Nd | .Sx \&Nd | ||
|
|
||
to mark up the name of the manual page. | to mark up the name of the manual page. | ||
.Ss \&No | .Ss \&No | ||
A | A | ||
.Qq noop | .Dq noop | ||
macro used to terminate prior macro contexts. | macro used to terminate prior macro contexts. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Sx \&Fl ab \&No cd \&Fl ef | .Dl \&.Sx \&Fl ab \&No cd \&Fl ef | ||
.Ss \&Ns | .Ss \&Ns | ||
Suppress a space. | |||
Following invocation, text is interpreted as free-form text until a | |||
macro is encountered. | |||
.Pp | |||
This has no effect when invoked at the start of a macro line. | |||
.Pp | |||
Examples: | |||
.Dl \&.Fl o \&Ns \&Ar output | |||
.Pp | |||
See also | |||
.Sx \&No | |||
and | |||
.Sx \&Sm . | |||
.Ss \&Nx | .Ss \&Nx | ||
Format the NetBSD version provided as an argument, or a default value if | Format the | ||
.Nx | |||
version provided as an argument, or a default value if | |||
no argument is provided. | no argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Nx 5.01 | .Dl \&.Nx 5.01 | ||
.D1 \&.Nx | .Dl \&.Nx | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
.Ss \&Oc | .Ss \&Oc | ||
Closes multi-line | Close multi-line | ||
.Sx \&Oo | .Sx \&Oo | ||
context. | context. | ||
.Ss \&Oo | .Ss \&Oo | ||
|
|
||
.Sx \&Op . | .Sx \&Op . | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent -compact | ||
\&.Oo | \&.Oo | ||
\&.Op Fl flag Ns Ar value | \&.Op Fl flag Ns Ar value | ||
\&.Oc | \&.Oc | ||
|
|
||
Prints the argument(s) in brackets. | Prints the argument(s) in brackets. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Op \&Fl a \&Ar b | .Dl \&.Op \&Fl a \&Ar b | ||
.D1 \&.Op \&Ar a | b | .Dl \&.Op \&Ar a | b | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Oo . | .Sx \&Oo . | ||
|
|
||
file. | file. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Os Op Cm system | .D1 Pf \. Sx \&Os Op Ar system Op Ar version | ||
.Pp | .Pp | ||
The optional | The optional | ||
.Cm system | .Ar system | ||
parameter specifies the relevant operating system or environment. | parameter specifies the relevant operating system or environment. | ||
Left unspecified, it defaults to the local operating system version. | Left unspecified, it defaults to the local operating system version. | ||
This is the suggested form. | This is the suggested form. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Os | .Dl \&.Os | ||
.D1 \&.Os KTH/CSC/TCS | .Dl \&.Os KTH/CSC/TCS | ||
.D1 \&.Os BSD 4.3 | .Dl \&.Os BSD 4.3 | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Dd | .Sx \&Dd | ||
|
|
||
.Em Remarks : | .Em Remarks : | ||
this macro has been deprecated. | this macro has been deprecated. | ||
.Ss \&Ox | .Ss \&Ox | ||
Format the OpenBSD version provided as an argument, or a default value | Format the | ||
.Ox | |||
version provided as an argument, or a default value | |||
if no argument is provided. | if no argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Ox 4.5 | .Dl \&.Ox 4.5 | ||
.D1 \&.Ox | .Dl \&.Ox | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
.Sx \&Ux . | .Sx \&Ux . | ||
.Ss \&Pa | .Ss \&Pa | ||
A file-system path. | A file-system path. | ||
If an argument is not provided, the string | |||
.Dq \(ti | |||
is used as a default. | |||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Pa /usr/bin/mandoc | .Dl \&.Pa /usr/bin/mandoc | ||
.D1 \&.Pa /usr/share/man/man7/mdoc.7 | .Dl \&.Pa /usr/share/man/man7/mdoc.7 | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Lk . | .Sx \&Lk . | ||
|
|
||
.Sx \&Po . | .Sx \&Po . | ||
.Ss \&Pf | .Ss \&Pf | ||
Removes the space | Removes the space | ||
.Pq Qq prefix | .Pq Dq prefix | ||
between its arguments. | between its arguments. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. \&Pf Cm prefix suffix | .D1 Pf \. \&Pf Ar prefix suffix | ||
.Pp | .Pp | ||
The | The | ||
.Cm suffix | .Ar suffix | ||
argument may be a macro. | argument may be a macro. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Pf \e. \&Sx \&Pf \&Cm prefix suffix | .Dl \&.Pf \e. \&Sx \&Pf \&Ar prefix suffix | ||
.Ss \&Po | .Ss \&Po | ||
Multi-line version of | Multi-line version of | ||
.Sx \&Pq . | .Sx \&Pq . | ||
|
|
||
See also | See also | ||
.Sx \&Po . | .Sx \&Po . | ||
.Ss \&Qc | .Ss \&Qc | ||
Close quoted context opened by | |||
.Sx \&Qo . | |||
.Ss \&Ql | .Ss \&Ql | ||
Format a single-quoted literal. | |||
See also | |||
.Sx \&Qq | |||
and | |||
.Sx \&Sq . | |||
.Ss \&Qo | .Ss \&Qo | ||
Multi-line version of | |||
.Sx \&Qq . | |||
.Ss \&Qq | .Ss \&Qq | ||
Encloses its arguments in | |||
.Dq typewriter | |||
double-quotes. | |||
Consider using | |||
.Sx \&Dq . | |||
.Pp | |||
See also | |||
.Sx \&Dq , | |||
.Sx \&Sq , | |||
and | |||
.Sx \&Qo . | |||
.Ss \&Re | .Ss \&Re | ||
Closes a | Close an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. | block. | ||
Does not have any tail arguments. | Does not have any tail arguments. | ||
.Ss \&Rs | .Ss \&Rs | ||
Begins a bibliographic | Begin a bibliographic | ||
.Pq Dq reference | .Pq Dq reference | ||
block. | block. | ||
Does not have any head arguments. | Does not have any head arguments. | ||
|
|
||
before the rendered output, else the block continues on the current | before the rendered output, else the block continues on the current | ||
line. | line. | ||
.Ss \&Rv | .Ss \&Rv | ||
Inserts text regarding a function call's return value. | |||
This macro must consist of the | |||
.Fl std | |||
argument followed by an optional | |||
.Ar function . | |||
If | |||
.Ar function | |||
is not provided, the document's name as stipulated by the first | |||
.Sx \&Nm | |||
is provided. | |||
.Pp | |||
See also | |||
.Sx \&Ex . | |||
.Ss \&Sc | .Ss \&Sc | ||
Close single-quoted context opened by | |||
.Sx \&So . | |||
.Ss \&Sh | .Ss \&Sh | ||
Begin a new section. | |||
For a list of conventional manual sections, see | |||
.Sx MANUAL STRUCTURE . | |||
These sections should be used unless it's absolutely necessary that | |||
custom sections be used. | |||
.Pp | |||
Section names should be unique so that they may be keyed by | |||
.Sx \&Sx . | |||
.Pp | |||
See also | |||
.Sx \&Pp , | |||
.Sx \&Ss , | |||
and | |||
.Sx \&Sx . | |||
.Ss \&Sm | .Ss \&Sm | ||
Switches the spacing mode for output generated from macros. | Switches the spacing mode for output generated from macros. | ||
Its syntax is as follows: | Its syntax is as follows: | ||
|
|
||
.D1 Pf \. Sx \&Sm Cm on | off | .D1 Pf \. Sx \&Sm Cm on | off | ||
.Pp | .Pp | ||
By default, spacing is | By default, spacing is | ||
.Cm on . | .Ar on . | ||
When switched | When switched | ||
.Cm off , | .Ar off , | ||
no white space is inserted between macro arguments and between the | no white space is inserted between macro arguments and between the | ||
output generated from adjacent macros, but free-form text lines | output generated from adjacent macros, but text lines | ||
still get normal spacing between words and sentences. | still get normal spacing between words and sentences. | ||
.Ss \&So | .Ss \&So | ||
Multi-line version of | |||
.Sx \&Sq . | |||
.Ss \&Sq | .Ss \&Sq | ||
Encloses its arguments in | |||
.Dq typewriter | |||
single-quotes. | |||
.Pp | |||
See also | |||
.Sx \&Dq , | |||
.Sx \&Qq , | |||
and | |||
.Sx \&So . | |||
.Ss \&Ss | .Ss \&Ss | ||
Begin a new sub-section. | |||
Unlike with | |||
.Sx \&Sh , | |||
there's no convention for sub-sections. | |||
Conventional sections, as described in | |||
.Sx MANUAL STRUCTURE , | |||
rarely have sub-sections. | |||
.Pp | |||
Sub-section names should be unique so that they may be keyed by | |||
.Sx \&Sx . | |||
.Pp | |||
See also | |||
.Sx \&Pp , | |||
.Sx \&Sh , | |||
and | |||
.Sx \&Sx . | |||
.Ss \&St | .Ss \&St | ||
Replace an abbreviation for a standard with the full form. | |||
The following standards are recognised: | |||
.Pp | |||
.Bl -tag -width "-p1003.1g-2000X" -compact | |||
.It \-p1003.1-88 | |||
.St -p1003.1-88 | |||
.It \-p1003.1-90 | |||
.St -p1003.1-90 | |||
.It \-p1003.1-96 | |||
.St -p1003.1-96 | |||
.It \-p1003.1-2001 | |||
.St -p1003.1-2001 | |||
.It \-p1003.1-2004 | |||
.St -p1003.1-2004 | |||
.It \-p1003.1-2008 | |||
.St -p1003.1-2008 | |||
.It \-p1003.1 | |||
.St -p1003.1 | |||
.It \-p1003.1b | |||
.St -p1003.1b | |||
.It \-p1003.1b-93 | |||
.St -p1003.1b-93 | |||
.It \-p1003.1c-95 | |||
.St -p1003.1c-95 | |||
.It \-p1003.1g-2000 | |||
.St -p1003.1g-2000 | |||
.It \-p1003.1i-95 | |||
.St -p1003.1i-95 | |||
.It \-p1003.2-92 | |||
.St -p1003.2-92 | |||
.It \-p1003.2a-92 | |||
.St -p1003.2a-92 | |||
.It \-p1387.2-95 | |||
.St -p1387.2-95 | |||
.It \-p1003.2 | |||
.St -p1003.2 | |||
.It \-p1387.2 | |||
.St -p1387.2 | |||
.It \-isoC | |||
.St -isoC | |||
.It \-isoC-90 | |||
.St -isoC-90 | |||
.It \-isoC-amd1 | |||
.St -isoC-amd1 | |||
.It \-isoC-tcor1 | |||
.St -isoC-tcor1 | |||
.It \-isoC-tcor2 | |||
.St -isoC-tcor2 | |||
.It \-isoC-99 | |||
.St -isoC-99 | |||
.It \-iso9945-1-90 | |||
.St -iso9945-1-90 | |||
.It \-iso9945-1-96 | |||
.St -iso9945-1-96 | |||
.It \-iso9945-2-93 | |||
.St -iso9945-2-93 | |||
.It \-ansiC | |||
.St -ansiC | |||
.It \-ansiC-89 | |||
.St -ansiC-89 | |||
.It \-ansiC-99 | |||
.St -ansiC-99 | |||
.It \-ieee754 | |||
.St -ieee754 | |||
.It \-iso8802-3 | |||
.St -iso8802-3 | |||
.It \-ieee1275-94 | |||
.St -ieee1275-94 | |||
.It \-xpg3 | |||
.St -xpg3 | |||
.It \-xpg4 | |||
.St -xpg4 | |||
.It \-xpg4.2 | |||
.St -xpg4.2 | |||
.St -xpg4.3 | |||
.It \-xbd5 | |||
.St -xbd5 | |||
.It \-xcu5 | |||
.St -xcu5 | |||
.It \-xsh5 | |||
.St -xsh5 | |||
.It \-xns5 | |||
.St -xns5 | |||
.It \-xns5.2 | |||
.St -xns5.2 | |||
.It \-xns5.2d2.0 | |||
.St -xns5.2d2.0 | |||
.It \-xcurses4.2 | |||
.St -xcurses4.2 | |||
.It \-susv2 | |||
.St -susv2 | |||
.It \-susv3 | |||
.St -susv3 | |||
.It \-svid4 | |||
.St -svid4 | |||
.El | |||
.Ss \&Sx | .Ss \&Sx | ||
Reference a section or sub-section. | |||
The referenced section or sub-section name must be identical to the | |||
enclosed argument, including whitespace. | |||
.Pp | |||
Examples: | |||
.Dl \&.Sx MANUAL STRUCTURE | |||
.Pp | |||
See also | |||
.Sx \&Sh | |||
and | |||
.Sx \&Ss . | |||
.Ss \&Sy | .Ss \&Sy | ||
Format enclosed arguments in symbolic | |||
.Pq Dq boldface . | |||
Note that this is a presentation term and should not be used for | |||
stylistically decorating technical terms. | |||
.Pp | |||
See also | |||
.Sx \&Bf , | |||
.Sx \&Li , | |||
and | |||
.Sx \&Em . | |||
.Ss \&Tn | .Ss \&Tn | ||
Format a tradename. | |||
.Pp | |||
Examples: | |||
.Dl \&.Tn IBM | |||
.Ss \&Ud | .Ss \&Ud | ||
Prints out | Prints out | ||
.Dq currently under development. | .Dq currently under development . | ||
.Ss \&Ux | .Ss \&Ux | ||
Format the UNIX name. | Format the UNIX name. | ||
Accepts no argument. | Accepts no argument. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Ux | .Dl \&.Ux | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
A variable name. | A variable name. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Va foo | .Dl \&.Va foo | ||
.D1 \&.Va const char *bar ; | .Dl \&.Va const char *bar ; | ||
.Ss \&Vt | .Ss \&Vt | ||
A variable type. | A variable type. | ||
This is also used for indicating global variables in the | This is also used for indicating global variables in the | ||
|
|
||
which is used for function return types. | which is used for function return types. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Vt unsigned char | .Dl \&.Vt unsigned char | ||
.D1 \&.Vt extern const char * const sys_signame[] \&; | .Dl \&.Vt extern const char * const sys_signame[] \&; | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx MANUAL STRUCTURE | .Sx MANUAL STRUCTURE | ||
|
|
||
Close a scope opened by | Close a scope opened by | ||
.Sx \&Xo . | .Sx \&Xo . | ||
.Ss \&Xo | .Ss \&Xo | ||
Open an extension scope. | Extend the header of an | ||
This macro originally existed to extend the 9-argument limit of troff; | .Sx \&It | ||
since this limit has been lifted, the macro has been deprecated. | macro or the body of a partial-implicit block macro | ||
beyond the end of the input line. | |||
This macro originally existed to work around the 9-argument limit | |||
of historic | |||
.Xr roff 7 . | |||
.Ss \&Xr | .Ss \&Xr | ||
Link to another manual | Link to another manual | ||
.Pq Qq cross-reference . | .Pq Qq cross-reference . | ||
Its syntax is as follows: | Its syntax is as follows: | ||
.Pp | .Pp | ||
.D1 Pf \. Sx \&Xr Cm name section | .D1 Pf \. Sx \&Xr Ar name section | ||
.Pp | .Pp | ||
The | The | ||
.Cm name | .Ar name | ||
and | and | ||
.Cm section | .Ar section | ||
are the name and section of the linked manual. | are the name and section of the linked manual. | ||
If | If | ||
.Cm section | .Ar section | ||
is followed by non-punctuation, an | is followed by non-punctuation, an | ||
.Sx \&Ns | .Sx \&Ns | ||
is inserted into the token stream. | is inserted into the token stream. | ||
This behaviour is for compatibility with | This behaviour is for compatibility with | ||
.Xr groff 1 . | GNU troff. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.D1 \&.Xr mandoc 1 | .Dl \&.Xr mandoc 1 | ||
.D1 \&.Xr mandoc 1 \&; | .Dl \&.Xr mandoc 1 \&; | ||
.D1 \&.Xr mandoc 1 \&Ns s behaviour | .Dl \&.Xr mandoc 1 \&Ns s behaviour | ||
.Ss \&br | .Ss \&br | ||
Emits a line-break. | |||
This macro should not be used; it is implemented for compatibility with | |||
historical manuals. | |||
.Pp | |||
Consider using | |||
.Sx \&Pp | |||
in the event of natural paragraph breaks. | |||
.Ss \&sp | .Ss \&sp | ||
Emits vertical space. | |||
This macro should not be used; it is implemented for compatibility with | |||
historical manuals. | |||
Its syntax is as follows: | |||
.Pp | |||
.D1 Pf \. Sx \&sp Op Ar height | |||
.Pp | |||
The | |||
.Ar height | |||
argument must be formatted as described in | |||
.Sx Scaling Widths . | |||
If unspecified, | |||
.Sx \&sp | |||
asserts a single vertical space. | |||
.Sh COMPATIBILITY | .Sh COMPATIBILITY | ||
This section documents compatibility between mandoc and other other | This section documents compatibility between mandoc and other other | ||
troff implementations, at this time limited to GNU troff | troff implementations, at this time limited to GNU troff | ||
.Pq Qq groff . | .Pq Qq groff . | ||
The term | The term | ||
.Qq historic groff | .Qq historic groff | ||
refers to groff versions before the | refers to groff versions before 1.17, | ||
which featured a significant update of the | |||
.Pa doc.tmac | .Pa doc.tmac | ||
file re-write | file. | ||
.Pq somewhere between 1.15 and 1.19 . | |||
.Pp | .Pp | ||
Heirloom troff, the other significant troff implementation accepting | Heirloom troff, the other significant troff implementation accepting | ||
\-mdoc, is similar to historic groff. | \-mdoc, is similar to historic groff. | ||
.Pp | .Pp | ||
The following problematic behaviour is found in groff: | |||
.ds hist (Historic groff only.) | |||
.Pp | |||
.Bl -dash -compact | .Bl -dash -compact | ||
.It | .It | ||
Old groff fails to assert a newline before | Display macros | ||
.Sx \&Bd Fl ragged compact . | .Po | ||
.Sx \&Bd , | |||
.Sx \&Dl , | |||
and | |||
.Sx \&D1 | |||
.Pc | |||
may not be nested. | |||
\*[hist] | |||
.It | .It | ||
groff behaves inconsistently when encountering | .Sx \&At | ||
.Pf non- Sx \&Fa | with unknown arguments produces no output at all. | ||
children of | \*[hist] | ||
Newer groff and mandoc print | |||
.Qq AT&T UNIX | |||
and the arguments. | |||
.It | |||
.Sx \&Bd Fl column | |||
does not recognize trailing punctuation characters when they immediately | |||
precede tabulator characters, but treats them as normal text and | |||
outputs a space before them. | |||
.It | |||
.Sx \&Bd Fl ragged compact | |||
does not start a new line. | |||
\*[hist] | |||
.It | |||
.Sx \&Dd | |||
with non-standard arguments behaves very strangely. | |||
When there are three arguments, they are printed verbatim. | |||
Any other number of arguments is replaced by the current date, | |||
but without any arguments the string | |||
.Dq Epoch | |||
is printed. | |||
.It | |||
.Sx \&Fl | |||
does not print a dash for an empty argument. | |||
\*[hist] | |||
.It | |||
.Sx \&Fn | |||
does not start a new line unless invoked as the line macro in the | |||
.Em SYNOPSIS | |||
section. | |||
\*[hist] | |||
.It | |||
.Sx \&Fo | .Sx \&Fo | ||
regarding spacing between arguments. | with | ||
In mandoc, this is not the case: each argument is consistently followed | .Pf non- Sx \&Fa | ||
by a single space and the trailing | children causes inconsistent spacing between arguments. | ||
.Sq \&) | In mandoc, a single space is always inserted between arguments. | ||
suppresses prior spacing. | |||
.It | .It | ||
groff behaves inconsistently when encountering | |||
.Sx \&Ft | .Sx \&Ft | ||
and | |||
.Sx \&Fn | |||
in the | in the | ||
.Em SYNOPSIS : | .Em SYNOPSIS | ||
at times newline(s) are suppressed depending on whether a prior | causes inconsistent vertical spacing, depending on whether a prior | ||
.Sx \&Fn | .Sx \&Fn | ||
has been invoked. | has been invoked. | ||
In mandoc, this is not the case. | |||
See | See | ||
.Sx \&Ft | .Sx \&Ft | ||
and | and | ||
.Sx \&Fn | .Sx \&Fn | ||
for the normalised behaviour. | for the normalised behaviour in mandoc. | ||
.It | .It | ||
Historic groff does not break before an | |||
.Sx \&Fn | |||
when not invoked as the line macro in the | |||
.Em SYNOPSIS | |||
section. | |||
.It | |||
Historic groff formats the | |||
.Sx \&In | .Sx \&In | ||
badly: trailing arguments are trashed and | ignores additional arguments and is not treated specially in the | ||
.Em SYNOPSIS | .Em SYNOPSIS . | ||
is not specially treated. | \*[hist] | ||
.It | .It | ||
groff does not accept the | .Sx \&It | ||
.Sq \&Ta | sometimes requires a | ||
pseudo-macro as a line macro. | .Fl nested | ||
mandoc does. | flag. | ||
\*[hist] | |||
In new groff and mandoc, any list may be nested by default and | |||
.Fl enum | |||
lists will restart the sequence only for the sub-list. | |||
.It | .It | ||
The comment syntax | .Sx \&Li | ||
.Sq \e." | followed by a reserved character is incorrectly used in some manuals | ||
is no longer accepted. | instead of properly quoting that character, which sometimes works with | ||
historic groff. | |||
.It | .It | ||
In groff, the | .Sx \&Lk | ||
only accepts a single link-name argument; the remainder is misformatted. | |||
.It | |||
.Sx \&Pa | .Sx \&Pa | ||
macro does not format its arguments when used in the FILES section under | does not format its arguments when used in the FILES section under | ||
certain list types. | certain list types. | ||
mandoc does. | |||
.It | .It | ||
Historic groff does not print a dash for empty | .Sx \&Ta | ||
.Sx \&Fl | can only be called by other macros, but not at the beginning of a line. | ||
arguments. | |||
mandoc and newer groff implementations do. | |||
.It | .It | ||
groff behaves irregularly when specifying | .Sx \&%C | ||
is not implemented. | |||
.It | |||
Historic groff only allows up to eight or nine arguments per macro input | |||
line, depending on the exact situation. | |||
Providing more arguments causes garbled output. | |||
The number of arguments on one input line is not limited with mandoc. | |||
.It | |||
Historic groff has many un-callable macros. | |||
Most of these (excluding some block-level macros) are callable | |||
in new groff and mandoc. | |||
.It | |||
.Sq \(ba | |||
(vertical bar) is not fully supported as a delimiter. | |||
\*[hist] | |||
.It | |||
.Sq \ef | .Sq \ef | ||
.Pq font face | |||
and | |||
.Sq \ef | |||
.Pq font family face | |||
.Sx Text Decoration | .Sx Text Decoration | ||
within line-macro scopes. | escapes behave irregularly when specified within line-macro scopes. | ||
mandoc follows a consistent system. | |||
.It | .It | ||
In mandoc, negative scaling units are truncated to zero; groff would | Negative scaling units return to prior lines. | ||
move to prior lines. | Instead, mandoc truncates them to zero. | ||
Furthermore, the | .El | ||
.Sq f | .Pp | ||
scaling unit, while accepted, is rendered as the default unit. | The following features are unimplemented in mandoc: | ||
.Pp | |||
.Bl -dash -compact | |||
.It | .It | ||
In quoted literals, groff allowed pair-wise double-quotes to produce a | .Sx \&Bd | ||
standalone double-quote in formatted output. | .Fl file Ar file . | ||
This idiosyncratic behaviour is not applicable in mandoc. | |||
.It | .It | ||
Display offsets | |||
.Sx \&Bd | .Sx \&Bd | ||
.Fl offset Ar center | .Fl offset Ar center | ||
and | and | ||
.Fl offset Ar right | .Fl offset Ar right . | ||
are disregarded in mandoc. | Groff does not implement centered and flush-right rendering either, | ||
Furthermore, troff specifies a | but produces large indentations. | ||
.Fl file Ar file | |||
argument that is not supported in mandoc. | |||
Lastly, since text is not right-justified in mandoc (or even groff), | |||
.Fl ragged | |||
and | |||
.Fl filled | |||
are aliases, as are | |||
.Fl literal | |||
and | |||
.Fl unfilled . | |||
.It | .It | ||
Historic groff has many un-callable macros. | The | ||
Most of these (excluding some block-level macros) are now callable. | .Sq \eh | ||
.It | .Pq horizontal position , | ||
The vertical bar | .Sq \ev | ||
.Sq \(ba | .Pq vertical position , | ||
made historic groff | .Sq \em | ||
.Qq go orbital | .Pq text colour , | ||
but has been a proper delimiter since then. | .Sq \eM | ||
.It | .Pq text filling colour , | ||
.Sx \&It Fl nested | .Sq \ez | ||
is assumed for all lists (it wasn't in historic groff): any list may be | .Pq zero-length character , | ||
nested and | .Sq \ew | ||
.Fl enum | .Pq string length , | ||
lists will restart the sequence only for the sub-list. | .Sq \ek | ||
.It | .Pq horizontal position marker , | ||
Some manuals use | .Sq \eo | ||
.Sx \&Li | .Pq text overstrike , | ||
incorrectly by following it with a reserved character and expecting the | |||
delimiter to render. | |||
This is not supported in mandoc. | |||
.It | |||
In groff, the | |||
.Sx \&Cd , | |||
.Sx \&Er , | |||
.Sx \&Ex , | |||
and | and | ||
.Sx \&Rv | .Sq \es | ||
macros were stipulated only to occur in certain manual sections. | .Pq text size | ||
mandoc does not have these restrictions. | escape sequences are all discarded in mandoc. | ||
.It | .It | ||
Newer groff and mandoc print | The | ||
.Qq AT&T UNIX | .Sq \ef | ||
prior to unknown arguments of | scaling unit is accepted by mandoc, but rendered as the default unit. | ||
.Sx \&At ; | .It | ||
older groff did nothing. | In quoted literals, groff allows pairwise double-quotes to produce a | ||
standalone double-quote in formatted output. | |||
This is not supported by mandoc. | |||
.El | .El | ||
.Sh SEE ALSO | .Sh SEE ALSO | ||
.Xr man 1 , | |||
.Xr mandoc 1 , | .Xr mandoc 1 , | ||
.Xr eqn 7 , | |||
.Xr man 7 , | |||
.Xr mandoc_char 7 | .Xr mandoc_char 7 | ||
.Xr roff 7 , | |||
.Xr tbl 7 | |||
.Sh HISTORY | |||
The | |||
.Nm | |||
language first appeared as a troff macro package in | |||
.Bx 4.4 . | |||
It was later significantly updated by Werner Lemberg and Ruslan Ermilov | |||
in groff-1.17. | |||
The standalone implementation that is part of the | |||
.Xr mandoc 1 | |||
utility written by Kristaps Dzonsons appeared in | |||
.Ox 4.6 . | |||
.Sh AUTHORS | .Sh AUTHORS | ||
The | The | ||
.Nm | .Nm | ||
reference was written by | reference was written by | ||
.An Kristaps Dzonsons Aq kristaps@bsd.lv . | .An Kristaps Dzonsons Aq kristaps@bsd.lv . | ||
.\" | |||
.\" XXX: this really isn't the place for these caveats. | |||
.\" . | |||
.\" . | |||
.\" .Sh CAVEATS | |||
.\" There are many ambiguous parts of mdoc. | |||
.\" . | |||
.\" .Pp | |||
.\" .Bl -dash -compact | |||
.\" .It | |||
.\" .Sq \&Fa | |||
.\" should be | |||
.\" .Sq \&Va | |||
.\" as function arguments are variables. | |||
.\" .It | |||
.\" .Sq \&Ft | |||
.\" should be | |||
.\" .Sq \&Vt | |||
.\" as function return types are still types. Furthermore, the | |||
.\" .Sq \&Ft | |||
.\" should be removed and | |||
.\" .Sq \&Fo , | |||
.\" which ostensibly follows it, should follow the same convention as | |||
.\" .Sq \&Va . | |||
.\" .It | |||
.\" .Sq \&Va | |||
.\" should formalise that only one or two arguments are acceptable: a | |||
.\" variable name and optional, preceding type. | |||
.\" .It | |||
.\" .Sq \&Fd | |||
.\" is ambiguous. It's commonly used to indicate an include file in the | |||
.\" synopsis section. | |||
.\" .Sq \&In | |||
.\" should be used, instead. | |||
.\" .It | |||
.\" Only the | |||
.\" .Sq \-literal | |||
.\" argument to | |||
.\" .Sq \&Bd | |||
.\" makes sense. The remaining ones should be removed. | |||
.\" .It | |||
.\" The | |||
.\" .Sq \&Xo | |||
.\" and | |||
.\" .Sq \&Xc | |||
.\" macros should be deprecated. | |||
.\" .It | |||
.\" The | |||
.\" .Sq \&Dt | |||
.\" macro lacks clarity. It should be absolutely clear which title will | |||
.\" render when formatting the manual page. | |||
.\" .It | |||
.\" A | |||
.\" .Sq \&Lx | |||
.\" should be provided for Linux (\(`a la | |||
.\" .Sq \&Ox , | |||
.\" .Sq \&Nx | |||
.\" etc.). | |||
.\" .It | |||
.\" There's no way to refer to references in | |||
.\" .Sq \&Rs/Re | |||
.\" blocks. | |||
.\" .It | |||
.\" The \-split and \-nosplit dictates via | |||
.\" .Sq \&An | |||
.\" are re-set when entering and leaving the AUTHORS section. | |||
.\" .El | |||
.\" . |