Return to mdoc.7 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.87, 2010/03/31 07:13:53 | version 1.107, 2010/05/15 07:01:51 | ||
---|---|---|---|
|
|
||
.\" $Id$ | .\" $Id$ | ||
.\" | .\" | ||
.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se> | .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv> | ||
.\" | .\" | ||
.\" Permission to use, copy, modify, and distribute this software for any | .\" Permission to use, copy, modify, and distribute this software for any | ||
.\" purpose with or without fee is hereby granted, provided that the above | .\" purpose with or without fee is hereby granted, provided that the above | ||
|
|
||
.Dd $Mdocdate$ | .Dd $Mdocdate$ | ||
.Dt MDOC 7 | .Dt MDOC 7 | ||
.Os | .Os | ||
. | |||
. | |||
.Sh NAME | .Sh NAME | ||
.Nm mdoc | .Nm mdoc | ||
.Nd mdoc language reference | .Nd mdoc language reference | ||
. | |||
. | |||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||
The | The | ||
.Nm mdoc | .Nm mdoc | ||
|
|
||
.Bx | .Bx | ||
.Ux | .Ux | ||
manuals. In this reference document, we describe its syntax, structure, | manuals. In this reference document, we describe its syntax, structure, | ||
and usage. Our reference implementation is | and usage. Our reference implementation is mandoc; the | ||
.Xr mandoc 1 . | |||
The | |||
.Sx COMPATIBILITY | .Sx COMPATIBILITY | ||
section describes compatibility with | section describes compatibility with other troff \-mdoc implementations. | ||
.Xr groff 1 . | |||
. | |||
.Pp | .Pp | ||
An | An | ||
.Nm | .Nm | ||
|
|
||
\&.Sh Macro lines change control state. | \&.Sh Macro lines change control state. | ||
Other lines are interpreted within the current state. | Other 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 | ||
|
|
||
manuals must have | manuals must have | ||
.Ux | .Ux | ||
line terminators. | line terminators. | ||
. | |||
. | |||
.Ss Comments | .Ss Comments | ||
Text following a | Text following a | ||
.Sq \e" , | .Sq \e" , | ||
|
|
||
.Sq \&.\e" , | .Sq \&.\e" , | ||
is also ignored. Macro lines with only a control charater and optionally | is also ignored. Macro lines with only a control charater and optionally | ||
whitespace are stripped from input. | whitespace are stripped from input. | ||
. | |||
. | |||
.Ss Reserved Characters | .Ss Reserved Characters | ||
Within a macro line, the following characters are reserved: | Within a macro line, the following characters are reserved: | ||
.Pp | .Pp | ||
|
|
||
.It \&| | .It \&| | ||
.Pq vertical bar | .Pq vertical bar | ||
.El | .El | ||
. | |||
.Pp | .Pp | ||
Use of reserved characters is described in | Use of reserved characters is described in | ||
.Sx MACRO SYNTAX . | .Sx MACRO SYNTAX . | ||
|
|
||
with a non-breaking space | with a non-breaking space | ||
.Pq Sq \e& | .Pq Sq \e& | ||
or, if applicable, an appropriate escape sequence used. | 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 free-form lines. | ||
Sequences begin with the escape character | Sequences begin with the escape character | ||
|
|
||
.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. See | or a single one-character sequence. | ||
See | |||
.Xr mandoc_char 7 | .Xr mandoc_char 7 | ||
for a complete list. Examples include | for a complete list. | ||
Examples include | |||
.Sq \e(em | .Sq \e(em | ||
.Pq em-dash | .Pq em-dash | ||
and | and | ||
.Sq \ee | .Sq \ee | ||
.Pq back-slash . | .Pq back-slash . | ||
. | |||
. | |||
.Ss Text Decoration | .Ss Text Decoration | ||
Terms may be text-decorated using the | Terms may be text-decorated using the | ||
.Sq \ef | .Sq \ef | ||
|
|
||
.D1 \efBbold\efR \efIitalic\efP | .D1 \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. A text decoration is valid within | respectively) may be used instead. | ||
A text decoration is valid within | |||
the current font scope only: if a macro opens a font scope alongside | the current font scope only: if a macro opens a font scope alongside | ||
its own scope, such as | its own scope, such as | ||
.Sx \&Bf | .Sx \&Bf | ||
.Cm \&Sy , | .Cm \&Sy , | ||
in-scope invocations of | in-scope invocations of | ||
.Sq \ef | .Sq \ef | ||
are only valid within the font scope of the macro. If | are only valid within the font scope of the macro. | ||
If | |||
.Sq \ef | .Sq \ef | ||
is specified outside of any font scope, such as in unenclosed, free-form | is specified outside of any font scope, such as in unenclosed, free-form | ||
text, it will affect the remainder of the document. | text, it will affect the remainder of the document. | ||
|
|
||
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 | .Xr groff 1 | ||
|
|
||
.Sq \e*[N] . | .Sq \e*[N] . | ||
See | See | ||
.Xr mandoc_char 7 | .Xr mandoc_char 7 | ||
for a complete list. Examples include | for a complete list. | ||
Examples include | |||
.Sq \e*(Am | .Sq \e*(Am | ||
.Pq ampersand | .Pq ampersand | ||
and | and | ||
.Sq \e*(Ba | .Sq \e*(Ba | ||
.Pq vertical bar . | .Pq vertical bar . | ||
. | |||
. | |||
.Ss Whitespace | .Ss Whitespace | ||
In non-literal free-form lines, consecutive blocks of whitespace are | Whitespace consists of the space character. | ||
pruned from input and added later in the output filter, if applicable: | In free-form lines, whitespace is preserved within a line; un-escaped | ||
.Bd -literal -offset indent | trailing spaces are stripped from input (unless in a literal context). | ||
These spaces are pruned from input. | Blank free-form lines, which may include whitespace, are only permitted | ||
\&.Bd \-literal | within literal contexts. | ||
These are not. | |||
\&.Ed | |||
.Ed | |||
. | |||
.Pp | .Pp | ||
In macro lines, whitespace delimits arguments and is discarded. If | In macro lines, whitespace delimits arguments and is discarded. | ||
arguments are quoted, whitespace within the quotes is retained. | If arguments are quoted, whitespace within the quotes is retained. | ||
. | |||
.Pp | |||
Blank lines are only permitted within literal contexts, as are lines | |||
containing only whitespace. Tab characters are only acceptable when | |||
delimiting | |||
.Sq \&Bl \-column | |||
or when in a literal context. | |||
. | |||
. | |||
.Ss Quotation | .Ss Quotation | ||
Macro arguments may be quoted with a double-quote to group | Macro arguments may be quoted with a double-quote to group | ||
space-delimited terms or to retain blocks of whitespace. A quoted | space-delimited terms or to retain blocks of whitespace. | ||
argument begins with a double-quote preceded by whitespace. The next | A quoted argument begins with a double-quote preceded by whitespace. | ||
double-quote not pair-wise adjacent to another double-quote terminates | The next double-quote not pair-wise adjacent to another double-quote | ||
the literal, regardless of surrounding whitespace. | terminates the literal, regardless of surrounding whitespace. | ||
. | |||
.Pp | .Pp | ||
This produces tokens | This produces tokens | ||
.Sq a" , | .Sq a" , | ||
|
|
||
and | and | ||
.Sq fg" . | .Sq fg" . | ||
Note that any quoted term, be it argument or macro, is indiscriminately | Note that any quoted term, be it argument or macro, is indiscriminately | ||
considered literal text. Thus, the following produces | considered literal text. | ||
Thus, the following produces | |||
.Sq \&Em a : | .Sq \&Em a : | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Em "Em a" | \&.Em "Em a" | ||
.Ed | .Ed | ||
. | |||
.Pp | .Pp | ||
In free-form mode, quotes are regarded as opaque text. | In free-form mode, quotes are regarded as opaque text. | ||
. | |||
.Ss Dates | .Ss Dates | ||
There are several macros in | There are several macros in | ||
.Nm | .Nm | ||
that require a date argument. The canonical form for dates is the | that require a date argument. | ||
American format: | The canonical form for dates is the American format: | ||
.Pp | .Pp | ||
.D1 Cm Month Day , Year | .D1 Cm Month Day , Year | ||
.Pp | .Pp | ||
The | The | ||
.Cm Day | .Cm Day | ||
value is an optionally zero-padded numeral. The | value is an optionally zero-padded numeral. | ||
The | |||
.Cm Month | .Cm Month | ||
value is the full month name. The | value is the full month name. | ||
The | |||
.Cm Year | .Cm Year | ||
value is the full four-digit year. | value is the full four-digit year. | ||
.Pp | .Pp | ||
|
|
||
.D1 "May, 2009" Pq reduced form | .D1 "May, 2009" Pq reduced form | ||
.D1 "2009" Pq reduced form | .D1 "2009" Pq reduced form | ||
.D1 "May 20, 2009" Pq canonical 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: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Bl -tag -width 2i | \&.Bl -tag -width 2i | ||
.Ed | .Ed | ||
. | |||
.Pp | .Pp | ||
The syntax for scaled widths is | The syntax for scaled widths is | ||
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , | .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , | ||
where a decimal must be preceded or proceeded by at least one digit. | where a decimal must be preceded or proceeded by at least one digit. | ||
Negative numbers, while accepted, are truncated to zero. The following | Negative numbers, while accepted, are truncated to zero. | ||
scaling units are accepted: | The following scaling units are accepted: | ||
.Pp | .Pp | ||
.Bl -tag -width Ds -offset indent -compact | .Bl -tag -width Ds -offset indent -compact | ||
.It c | .It c | ||
|
|
||
.Sq u , | .Sq u , | ||
or | or | ||
.Sq v | .Sq v | ||
is necessarily non-portable across output media. See | is necessarily non-portable across output media. | ||
See | |||
.Sx COMPATIBILITY . | .Sx COMPATIBILITY . | ||
. | .Ss Sentence Spacing | ||
. | When composing a manual, make sure that your sentences end at the end of | ||
a line. | |||
By doing so, front-ends will be able to apply the proper amount of | |||
spacing after the end of sentence (unescaped) period, exclamation mark, | |||
or question mark followed by zero or more non-sentence closing | |||
delimiters ( | |||
.Ns Sq \&) , | |||
.Sq \&] , | |||
.Sq \&' , | |||
.Sq \&" ) . | |||
.Pp | |||
The proper spacing is also intelligently preserved if a sentence ends at | |||
the boundary of a macro line, e.g., | |||
.Pp | |||
.D1 \&Xr mandoc 1 \. | |||
.D1 \&Fl T \&Ns \&Cm ascii \. | |||
.Sh MANUAL STRUCTURE | .Sh MANUAL STRUCTURE | ||
A well-formed | A well-formed | ||
.Nm | .Nm | ||
|
|
||
\&.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 1 & 8 only. | |||
\&.\e\*q .Sh EXIT STATUS | |||
\&.\e\*q The next is for sections 2, 3, & 9 only. | \&.\e\*q The next is for sections 2, 3, & 9 only. | ||
\&.\e\*q .Sh RETURN VALUES | \&.\e\*q .Sh RETURN VALUES | ||
\&.\e\*q The next is for sections 1, 6, 7, & 8 only. | \&.\e\*q The next is for sections 1, 6, 7, & 8 only. | ||
\&.\e\*q .Sh ENVIRONMENT | \&.\e\*q .Sh ENVIRONMENT | ||
\&.\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 EXAMPLES | \&.\e\*q .Sh EXAMPLES | ||
\&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. | \&.\e\*q The next is for sections 1, 4, 6, 7, & 8 only. | ||
\&.\e\*q .Sh DIAGNOSTICS | \&.\e\*q .Sh DIAGNOSTICS | ||
|
|
||
.Pp | .Pp | ||
The sections in a | The sections in a | ||
.Nm | .Nm | ||
document are conventionally ordered as they appear above. Sections | document are conventionally ordered as they appear above. | ||
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 | The name(s) and a short description of the documented material. | ||
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 | ||
|
|
||
.Sx \&Nm | .Sx \&Nm | ||
and | and | ||
.Sx \&Nd . | .Sx \&Nd . | ||
. | |||
.It Em LIBRARY | .It Em LIBRARY | ||
The name of the library containing the documented material, which is | The name of the library containing the documented material, which is | ||
assumed to be a function in a section 2 or 3 manual. The syntax for | assumed to be a function in a section 2 or 3 manual. | ||
this is as follows: | The syntax for this is as follows: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Lb libarm | \&.Lb libarm | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
See | See | ||
.Sx \&Lb . | .Sx \&Lb . | ||
. | |||
.It Em SYNOPSIS | .It Em SYNOPSIS | ||
Documents the utility invocation syntax, function call syntax, or device | Documents the utility invocation syntax, function call syntax, or device | ||
configuration. | configuration. | ||
|
|
||
.Sx \&Ft , | .Sx \&Ft , | ||
and | and | ||
.Sx \&Vt . | .Sx \&Vt . | ||
. | |||
.It Em DESCRIPTION | .It Em DESCRIPTION | ||
This expands upon the brief, one-line description in | This expands upon the brief, one-line description in | ||
.Em NAME . | .Em NAME . | ||
|
|
||
.Ed | .Ed | ||
.Pp | .Pp | ||
Manuals not documenting a command won't include the above fragment. | Manuals not documenting a command won't include the above fragment. | ||
. | |||
.It Em IMPLEMENTATION NOTES | .It Em IMPLEMENTATION NOTES | ||
Implementation-specific notes should be kept here. This is useful when | Implementation-specific notes should be kept here. | ||
implementing standard functions that may have side effects or notable | This is useful when implementing standard functions that may have side | ||
algorithmic implications. | effects or notable algorithmic implications. | ||
. | |||
.It Em EXIT STATUS | |||
Command exit status for section 1, 6, and 8 manuals. This section is | |||
the dual of | |||
.Em RETURN VALUES , | |||
which is used for functions. Historically, this information was | |||
described in | |||
.Em DIAGNOSTICS , | |||
a practise that is now discouraged. | |||
.Pp | |||
See | |||
.Sx \&Ex . | |||
. | |||
.It Em RETURN VALUES | .It Em RETURN VALUES | ||
This section is the dual of | This section is the dual of | ||
.Em EXIT STATUS , | .Em EXIT STATUS , | ||
which is used for commands. It documents the return values of functions | which is used for commands. | ||
in sections 2, 3, and 9. | 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., | Documents any usages of environment variables, e.g., | ||
.Xr environ 7 . | .Xr environ 7 . | ||
.Pp | .Pp | ||
See | See | ||
.Sx \&Ev . | .Sx \&Ev . | ||
. | |||
.It Em FILES | .It Em FILES | ||
Documents files used. It's helpful to document both the file and a | Documents files used. | ||
short description of how the file is used (created, modified, etc.). | It's helpful to document both the file and a short description of how | ||
the file is used (created, modified, etc.). | |||
.Pp | .Pp | ||
See | See | ||
.Sx \&Pa . | .Sx \&Pa . | ||
. | .It Em EXIT STATUS | ||
Command exit status for section 1, 6, and 8 manuals. | |||
This section is the dual of | |||
.Em RETURN VALUES , | |||
which is used for functions. | |||
Historically, this information was described in | |||
.Em DIAGNOSTICS , | |||
a practise that is now discouraged. | |||
.Pp | |||
See | |||
.Sx \&Ex . | |||
.It Em EXAMPLES | .It Em EXAMPLES | ||
Example usages. This often contains snippets of well-formed, | Example usages. | ||
well-tested invocations. Make doubly sure that your examples work | This often contains snippets of well-formed, well-tested invocations. | ||
properly! | Make doubly sure that your examples work properly! | ||
. | |||
.It Em DIAGNOSTICS | .It Em DIAGNOSTICS | ||
Documents error conditions. This is most useful in section 4 manuals. | Documents error conditions. | ||
This is most useful in section 4 manuals. | |||
Historically, this section was used in place of | Historically, this section was used in place of | ||
.Em EXIT STATUS | .Em EXIT STATUS | ||
for manuals in sections 1, 6, and 8; however, this practise is | for manuals in sections 1, 6, and 8; however, this practise is | ||
|
|
||
See | See | ||
.Sx \&Bl | .Sx \&Bl | ||
.Fl diag . | .Fl diag . | ||
. | |||
.It Em ERRORS | .It Em ERRORS | ||
Documents error handling in sections 2, 3, and 9. | Documents error handling in sections 2, 3, and 9. | ||
.Pp | .Pp | ||
See | See | ||
.Sx \&Er . | .Sx \&Er . | ||
. | |||
.It Em SEE ALSO | .It Em SEE ALSO | ||
References other manuals with related topics. This section should exist | References other manuals with related topics. | ||
for most manuals. Cross-references should conventionally be ordered | This section should exist for most manuals. | ||
first by section, then alphabetically. | Cross-references should conventionally be ordered first by section, then | ||
alphabetically. | |||
.Pp | .Pp | ||
See | See | ||
.Sx \&Xr . | .Sx \&Xr . | ||
. | |||
.It Em STANDARDS | .It Em STANDARDS | ||
References any standards implemented or used. If not adhering to any | References any standards implemented or used. | ||
standards, the | If not adhering to any standards, the | ||
.Em HISTORY | .Em HISTORY | ||
section should be used instead. | section should be used instead. | ||
.Pp | .Pp | ||
See | See | ||
.Sx \&St . | .Sx \&St . | ||
. | |||
.It Em HISTORY | .It Em HISTORY | ||
The history of any manual without a | The history of any manual without a | ||
.Em STANDARDS | .Em STANDARDS | ||
section should be described in this section. | 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 authors, if applicable, should appear in this section. | ||
Authors should generally be noted by both name and an e-mail address. | Authors should generally be noted by both name and an e-mail address. | ||
.Pp | .Pp | ||
See | See | ||
.Sx \&An . | .Sx \&An . | ||
. | |||
.It Em CAVEATS | .It Em CAVEATS | ||
Explanations of common misuses and misunderstandings should be explained | Explanations of 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. | Extant bugs 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. An arbitrary amount of whitespace may | at the beginning of the line. | ||
sit between the control character and the macro name. Thus, the | An arbitrary amount of whitespace may sit between the control character | ||
following are equivalent: | and the macro name. | ||
Thus, the following are equivalent: | |||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Pp | \&.Pp | ||
\&.\ \ \ \&Pp | \&.\ \ \ \&Pp | ||
.Ed | .Ed | ||
. | |||
.Pp | .Pp | ||
The syntax of a macro depends on its classification. In this section, | The syntax of a macro depends on its classification. | ||
In this section, | |||
.Sq \-arg | .Sq \-arg | ||
refers to macro arguments, which may be followed by zero or more | refers to macro arguments, which may be followed by zero or more | ||
.Sq parm | .Sq parm | ||
|
|
||
opens the scope of a macro; and if specified, | opens the scope of a macro; and if specified, | ||
.Sq \&Yc | .Sq \&Yc | ||
closes it out. | closes it out. | ||
. | |||
.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 be called subsequent to the initial | ||
line-macro. If a macro is not callable, then its invocation after the | line-macro. | ||
initial line macro is interpreted as opaque text, such that | If a macro is not callable, then its invocation after the initial line | ||
macro is interpreted as opaque text, such that | |||
.Sq \&.Fl \&Sh | .Sq \&.Fl \&Sh | ||
produces | produces | ||
.Sq Fl \&Sh . | .Sq Fl \&Sh . | ||
. | |||
.Pp | .Pp | ||
The | The | ||
.Em Parsable | .Em Parsable | ||
column indicates whether the macro may be followed by further | column indicates whether the macro may be followed by further | ||
(ostensibly callable) macros. If a macro is not parsable, subsequent | (ostensibly callable) macros. | ||
macro invocations on the line will be interpreted as opaque text. | If a macro is not parsable, subsequent macro invocations on the line | ||
. | will be interpreted as opaque text. | ||
.Pp | .Pp | ||
The | The | ||
.Em Scope | .Em Scope | ||
column, if applicable, describes closure rules. | column, if applicable, describes closure rules. | ||
. | |||
. | |||
.Ss Block full-explicit | .Ss Block full-explicit | ||
Multi-line scope closed by an explicit closing macro. All macros | Multi-line scope closed by an explicit closing macro. | ||
contains bodies; only | All macros contains bodies; only | ||
.Sx \&Bf | .Sx \&Bf | ||
contains a head. | contains a head. | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
|
|
||
\(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" "ParsableX" "closed by XXX" | ||
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope | .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope | ||
|
|
||
.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk | .It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk | ||
.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl | .It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl | ||
.El | .El | ||
. | |||
. | |||
.Ss Block full-implicit | .Ss Block full-implicit | ||
Multi-line scope closed by end-of-file or implicitly by another macro. | Multi-line scope closed by end-of-file or implicitly by another macro. | ||
All macros have bodies; some | All macros have bodies; some | ||
|
|
||
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB | \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB | ||
\(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" "ParsableX" "closed by XXXXXXXXXXX" | ||
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope | .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Scope | ||
|
|
||
.It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh | .It Sx \&Sh Ta \&No Ta \&No Ta closed by Sx \&Sh | ||
.It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss | .It Sx \&Ss Ta \&No Ta \&No Ta closed by Sx \&Sh , Sx \&Ss | ||
.El | .El | ||
. | |||
. | |||
.Ss Block partial-explicit | .Ss Block partial-explicit | ||
Like block full-explicit, but also with single-line scope. Each | Like block full-explicit, but also with single-line scope. | ||
has at least a body and, in limited circumstances, a head | Each has at least a body and, in limited circumstances, a head | ||
.Po | .Po | ||
.Sx \&Fo , | .Sx \&Fo , | ||
.Sx \&Eo | .Sx \&Eo | ||
|
|
||
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ | \&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ | ||
\(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" "ParsableX" "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 Parsable Ta Em Scope | ||
|
|
||
.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo | .It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo | ||
.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc | .It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc | ||
.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 Characters | ||
|
|
||
.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" "ParsableX" -compact -offset indent | ||
.It Em Macro Ta Em Callable Ta Em Parsable | .It Em Macro Ta Em Callable Ta Em Parsable | ||
|
|
||
only when invoked as the first macro | only when invoked as the first macro | ||
in a SYNOPSIS section line, else it is | in a SYNOPSIS section line, else it is | ||
.Sx In-line . | .Sx In-line . | ||
. | |||
. | |||
.Ss In-line | .Ss In-line | ||
Closed by | Closed by | ||
.Sx Reserved Characters , | .Sx Reserved Characters , | ||
end of line, fixed argument lengths, and/or subsequent macros. In-line | end of line, fixed argument lengths, and/or subsequent macros. | ||
macros have only text children. If a number (or inequality) of | In-line macros have only text children. | ||
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 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" "ParsableX" "Arguments" -compact -offset indent | ||
.It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments | .It Em Macro Ta Em Callable Ta Em Parsable Ta Em Arguments | ||
|
|
||
.It Sx \&Ot Ta \&No Ta \&No Ta n | .It Sx \&Ot Ta \&No Ta \&No Ta n | ||
.It Sx \&Ox Ta Yes Ta Yes Ta n | .It Sx \&Ox Ta Yes Ta Yes Ta n | ||
.It Sx \&Pa Ta Yes Ta Yes Ta n | .It Sx \&Pa Ta Yes Ta Yes Ta n | ||
.It Sx \&Pf Ta \&No Ta Yes Ta 1 | .It Sx \&Pf Ta Yes Ta Yes Ta 1 | ||
.It Sx \&Pp Ta \&No Ta \&No Ta 0 | .It Sx \&Pp Ta \&No Ta \&No Ta 0 | ||
.It Sx \&Rv Ta \&No Ta \&No Ta n | .It Sx \&Rv Ta \&No Ta \&No Ta n | ||
.It Sx \&Sm Ta \&No Ta \&No Ta 1 | .It Sx \&Sm Ta \&No Ta \&No Ta 1 | ||
|
|
||
.It Sx \&br Ta \&No Ta \&No Ta 0 | .It Sx \&br Ta \&No Ta \&No Ta 0 | ||
.It Sx \&sp Ta \&No Ta \&No Ta 1 | .It Sx \&sp Ta \&No Ta \&No Ta 1 | ||
.El | .El | ||
. | |||
. | |||
.Sh REFERENCE | .Sh REFERENCE | ||
This section is a canonical reference of all macros, arranged | This section is a canonical reference of all macros, arranged | ||
alphabetically. For the scoping of individual macros, see | alphabetically. | ||
For the scoping of individual macros, see | |||
.Sx MACRO SYNTAX . | .Sx MACRO SYNTAX . | ||
. | |||
.Ss \&%A | .Ss \&%A | ||
Author name of an | Author name of an | ||
.Sx \&Rs | .Sx \&Rs | ||
|
|
||
.Sx \%%A | .Sx \%%A | ||
line. Author names should be ordered with full or abbreviated | line. Author names should be ordered with full or abbreviated | ||
forename(s) first, then full surname. | 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 | ||
|
|
||
.Em Remarks : | .Em Remarks : | ||
this macro is not implemented in | this macro is not implemented in | ||
.Xr groff 1 . | .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. This should follow the reduced or canonical form syntax | ||
described in | described in | ||
.Sx Dates . | .Sx Dates . | ||
. | |||
.Ss \&%I | .Ss \&%I | ||
Publisher or issuer name of an | Publisher or issuer name of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. | block. | ||
. | |||
.Ss \&%J | .Ss \&%J | ||
Journal name of an | Journal name of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. | block. | ||
. | |||
.Ss \&%N | .Ss \&%N | ||
Issue number (usually for journals) of an | Issue number (usually for journals) of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. | block. | ||
. | |||
.Ss \&%O | .Ss \&%O | ||
Optional information of an | Optional information of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. | block. | ||
. | |||
.Ss \&%P | .Ss \&%P | ||
Book or journal page number of an | Book or journal page number of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. | block. | ||
. | |||
.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 | ||
Technical report name of an | Technical report name of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. | block. | ||
. | |||
.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. This macro may also be used in a non-bibliographical context | ||
when referring to article titles. | when referring to article titles. | ||
. | |||
.Ss \&%U | .Ss \&%U | ||
URI of reference document. | URI of reference document. | ||
. | |||
.Ss \&%V | .Ss \&%V | ||
Volume number of an | Volume number of an | ||
.Sx \&Rs | .Sx \&Rs | ||
block. | block. | ||
. | |||
.Ss \&Ac | .Ss \&Ac | ||
Closes an | Closes 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 | Address construct: usually in the context of an computational address in | ||
memory, not a physical (post) address. | memory, not a physical (post) address. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Ad [0,$] | ||
\&.Ad [0,$] | .D1 \&.Ad 0x00000000 | ||
\&.Ad 0x00000000 | |||
.Ed | |||
. | |||
.Ss \&An | .Ss \&An | ||
Author name. This macro may alternatively accepts the following | Author name. | ||
arguments, although these may not be specified along with a parameter: | This macro may alternatively accepts the following arguments, although | ||
these may not be specified along with a parameter: | |||
.Bl -tag -width 12n -offset indent | .Bl -tag -width 12n -offset indent | ||
.It Fl split | .It Fl split | ||
Renders a line break before each author listing. | Renders a line break before each author listing. | ||
|
|
||
.Pp | .Pp | ||
In the AUTHORS section, the default is not to split the first author | In the AUTHORS section, the default is not to split the first author | ||
listing, but all subsequent author listings, whether or not they're | listing, but all subsequent author listings, whether or not they're | ||
interspersed by other macros or text, are split. Thus, specifying | interspersed by other macros or text, are split. | ||
Thus, specifying | |||
.Fl split | .Fl split | ||
will cause the first listing also to be split. If not in the AUTHORS | will cause the first listing also to be split. | ||
section, the default is not to split. | If not in the AUTHORS section, the default is not to split. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.An -nosplit | ||
\&.An -nosplit | .D1 \&.An J. D. Ullman . | ||
\&.An J. E. Hopcraft , | |||
\&.An J. D. Ullman . | |||
.Ed | |||
.Pp | .Pp | ||
.Em Remarks : | .Em Remarks : | ||
the effects of | the effects of | ||
|
|
||
.Sx \&An Fl nosplit | .Sx \&An Fl nosplit | ||
in the general document body, it must be re-specified in the AUTHORS | in the general document body, it must be re-specified in the AUTHORS | ||
section. | section. | ||
. | |||
.Ss \&Ao | .Ss \&Ao | ||
Begins a block enclosed by angled brackets. Does not have any head | Begins a block enclosed by angled brackets. | ||
arguments. | Does not have any head arguments. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac | ||
\&.Fl -key= Ns Ao Ar val Ac | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Aq . | .Sx \&Aq . | ||
. | |||
.Ss \&Ap | .Ss \&Ap | ||
Inserts an apostrophe without any surrounding white-space. This is | Inserts an apostrophe without any surrounding white-space. | ||
generally used as a grammatic device when referring to the verb form of | This is generally used as a grammatic device when referring to the verb | ||
a function: | form of a function: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Fn execve Ap d | \&.Fn execve Ap d | ||
.Ed | .Ed | ||
. | |||
.Ss \&Aq | .Ss \&Aq | ||
Encloses its arguments in angled brackets. | Encloses its arguments in angled brackets. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Fl -key= \&Ns \&Aq \&Ar val | ||
\&.Fl -key= Ns Aq Ar val | |||
.Ed | |||
.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 | ||
|
|
||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Ao . | .Sx \&Ao . | ||
. | |||
.Ss \&Ar | .Ss \&Ar | ||
Command arguments. If an argument is not provided, the string | Command arguments. | ||
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: | ||
.Bd -literal -offset indent | .D1 \&.Fl o \&Ns \&Ar file1 | ||
\&.Fl o Ns Ar file1 | .D1 \&.Ar | ||
\&.Ar | .D1 \&.Ar arg1 , arg2 . | ||
\&.Ar arg1 , arg2 . | |||
.Ed | |||
. | |||
.Ss \&At | .Ss \&At | ||
Formats an AT&T version. Accepts at most one parameter: | Formats an AT&T version. | ||
Accepts at most one parameter: | |||
.Bl -tag -width 12n -offset indent | .Bl -tag -width 12n -offset indent | ||
.It Cm v[1-7] | 32v | .It Cm v[1-7] | 32v | ||
A version of | A version of | ||
|
|
||
Note that these parameters do not begin with a hyphen. | Note that these parameters do not begin with a hyphen. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.At | ||
\&.At | .D1 \&.At V.1 | ||
\&.At V.1 | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Bsx , | .Sx \&Bsx , | ||
|
|
||
.Sx \&Ox , | .Sx \&Ox , | ||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
. | |||
.Ss \&Bc | .Ss \&Bc | ||
Closes a | Closes 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. A display is collection of macros or text which | Begins a display block. | ||
may be collectively offset or justified in a manner different from that | A display is collection of macros or text which may be collectively | ||
of the enclosing context. By default, the block is preceded by a | offset or justified in a manner different from that | ||
vertical space. | of the enclosing context. | ||
By default, the block is preceded by a vertical space. | |||
.Pp | .Pp | ||
Each display is associated with a type, which must be one of the | Each display is associated with a type, which must be one of the | ||
following arguments: | following arguments: | ||
|
|
||
Centre-justify each line. | Centre-justify each line. | ||
.El | .El | ||
.Pp | .Pp | ||
The type must be provided first. Secondary arguments are as follows: | The type must be provided first. | ||
Secondary arguments are as follows: | |||
.Bl -tag -width 12n -offset indent | .Bl -tag -width 12n -offset indent | ||
.It Fl offset Ar width | .It Fl offset Ar width | ||
Offset by the value of | Offset by the value of | ||
|
|
||
.Ar center , | .Ar 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. The most popular is the | As a precalculated width for a named macro. | ||
imaginary macro | The most popular is the imaginary macro | ||
.Ar \&Ds , | .Ar \&Ds , | ||
which resolves to | which resolves to | ||
.Ar 6n . | .Ar 6n . | ||
|
|
||
.Sx \&D1 | .Sx \&D1 | ||
and | and | ||
.Sx \&Dl . | .Sx \&Dl . | ||
. | |||
.Ss \&Bf | .Ss \&Bf | ||
.Ss \&Bk | .Ss \&Bk | ||
.Ss \&Bl | .Ss \&Bl | ||
.\" Begins a list composed of one or more list entries. A list entry is | Begins a list composed of one or more list entries. | ||
.\" specified by the | A list is associated with a type, which is a required argument. | ||
.\" .Sx \&It | Other arguments are | ||
.\" macro, which consists of a head and optional body. By default, a list | .Fl width , | ||
.\" is preceded by a blank line. A list must specify one of the following | defined per-type as accepting a literal or | ||
.\" list types: | .Sx Scaling Widths | ||
.\" .Bl -tag -width 12n | value; | ||
.\" .It Fl bullet | .Fl offset , | ||
.\" A list offset by a bullet. The head of list entries must be empty. | also accepting a literal or | ||
.\" List entry bodies are justified after the bullet. | .Sx Scaling Widths | ||
.\" .It Fl column | value setting the list's global offset; and | ||
.\" A columnated list. The number of columns is specified as arguments to | .Fl compact , | ||
.\" the | suppressing the default vertical space printed before each list entry. | ||
.\" .Sx \&Bl | A list entry is specified by the | ||
.\" macro (the deprecated form of following the invocation of | .Sx \&It | ||
.\" .Fl column | macro, which consists of a head and optional body (depending on the list | ||
.\" is also accepted). Arguments dictate the width of columns specified in | type). | ||
.\" list entries. List entry bodies must be left empty. Columns specified | A list must specify one of the following list types: | ||
.\" in the list entry head are justified to their position in the sequence | .Bl -tag -width 12n -offset indent | ||
.\" of columns. | .It Fl bullet | ||
.\" .It Fl dash | A list offset by a bullet. | ||
.\" A list offset by a dash (hyphen). The head of list entries must be | The head of list entries must be empty. | ||
.\" empty. List entry bodies are justified past the dash. | List entry bodies are positioned after the bullet. | ||
.\" .It Fl diag | The | ||
.\" Like | .Fl width | ||
.\" .Fl inset | argument varies the width of list bodies' left-margins. | ||
.\" lists, but with additional formatting to the head. | .It Fl column | ||
.\" .It Fl enum | A columnated list. | ||
.\" A list offset by a number indicating list entry position. The head of | The | ||
.\" list entries must be empty. List entry bodies are justified past the | .Fl width | ||
.\" enumeration. | argument has no effect. | ||
.\" .It Fl hang | The number of columns is specified as parameters to the | ||
.\" Like | .Sx \&Bl | ||
.\" .Fl tag , | macro. | ||
.\" but instead of list bodies justifying to the head on the first line, | These dictate the width of columns either as | ||
.\" they trail the head text. | .Sx Scaling Widths | ||
.\" .It Fl hyphen | or literal text. | ||
.\" Synonym for | List entry bodies must be left empty. | ||
.\" .Fl dash . | Column bodies have the following syntax: | ||
.\" .It Fl inset | .Pp | ||
.\" Like | .D1 .It col1 <TAB> ... coln | ||
.\" .Fl tag , | .D1 .It col1 Ta ... coln | ||
.\" but list entry bodies aren't justified. | .D1 .It col1 <TAB> col2 Ta coln | ||
.\" .It Fl item | .Pp | ||
.\" An un-justified list. This produces blocks of text. | where columns may be separated by tabs, the literal string | ||
.\" .It Fl ohang | .Qq Ta , | ||
.\" List bodies are placed on the line following the head. | or a mixture of both. | ||
.\" .It Fl tag | These are equivalent except that quoted sections propogate over tabs, | ||
.\" A list offset by list entry heads. List entry bodies are justified | for example, | ||
.\" after the head. | .Pp | ||
.\" .El | .D1 .It \(dqcol1 ; <TAB> col2 ;\(dq ; | ||
.\" .Pp | .Pp | ||
.\" More... | will preserve the semicolon whitespace except for the last. | ||
.\" . | .It Fl dash | ||
A list offset by a dash (hyphen). | |||
The head of list entries must be empty. | |||
List entry bodies are positioned past the dash. | |||
The | |||
.Fl width | |||
argument varies the width of list bodies' left-margins. | |||
.It Fl diag | |||
Like | |||
.Fl inset , | |||
but with additional formatting to the head. | |||
The | |||
.Fl width | |||
argument varies the width of list bodies' left-margins. | |||
.It Fl enum | |||
An enumerated list offset by the enumeration from 1. | |||
The head of list entries must be empty. | |||
List entry bodies are positioned after the enumeration. | |||
The | |||
.Fl width | |||
argument varies the width of list bodies' left-margins. | |||
.It Fl hang | |||
Like | |||
.Fl tag , | |||
but instead of list bodies positioned after the head, they trail the | |||
head text. | |||
The | |||
.Fl width | |||
argument varies the width of list bodies' left-margins. | |||
.It Fl hyphen | |||
Synonym for | |||
.Fl dash . | |||
.It Fl inset | |||
List bodies follow the list head. | |||
The | |||
.Fl width | |||
argument is ignored. | |||
.It Fl item | |||
This produces blocks of text. | |||
The head of list entries must be empty. | |||
The | |||
.Fl width | |||
argument is ignored. | |||
.It Fl ohang | |||
List bodies are positioned on the line following the head. | |||
The | |||
.Fl width | |||
argument is ignored. | |||
.It Fl tag | |||
A list offset by list entry heads. List entry bodies are positioned | |||
after the head as specified by the | |||
.Fl width | |||
argument. | |||
.El | |||
.Ss \&Bo | .Ss \&Bo | ||
Begins a block enclosed by square brackets. Does not have any head | Begins a block enclosed by square brackets. | ||
arguments. | Does not have any head arguments. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Bo 1 , | \&.Bo 1 , | ||
\&.Dv BUFSIZ Bc | \&.Dv BUFSIZ \&Bc | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Bq . | .Sx \&Bq . | ||
. | |||
.Ss \&Bq | .Ss \&Bq | ||
Encloses its arguments in square brackets. | Encloses its arguments in square brackets. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Bq 1 , \&Dv BUFSIZ | ||
\&.Bq 1 , Dv BUFSIZ | |||
.Ed | |||
.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 | ||
|
|
||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Bo . | .Sx \&Bo . | ||
. | |||
.Ss \&Brc | .Ss \&Brc | ||
Closes a | Closes 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. Does not have any head | Begins a block enclosed by curly braces. | ||
arguments. | Does not have any head arguments. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.Bro 1 , ... , | \&.Bro 1 , ... , | ||
\&.Va n Brc | \&.Va n \&Brc | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Brq . | .Sx \&Brq . | ||
. | |||
.Ss \&Brq | .Ss \&Brq | ||
Encloses its arguments in curly braces. | Encloses its arguments in curly braces. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Brq 1 , ... , \&Va n | ||
\&.Brq 1 , ... , Va n | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Bro . | .Sx \&Bro . | ||
. | |||
.Ss \&Bsx | .Ss \&Bsx | ||
Format the BSD/OS version provided as an argument, or a default value if | Format the BSD/OS version provided as an argument, or a default value if | ||
no argument is provided. | no argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Bsx 1.0 | ||
\&.Bsx 1.0 | .D1 \&.Bsx | ||
\&.Bsx | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
.Sx \&Ox , | .Sx \&Ox , | ||
and | and | ||
.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: | ||
.Bd -literal -offset indent | .D1 \&.Bx 4.4 | ||
\&.Bx 4.4 | .D1 \&.Bx | ||
\&.Bx | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
.Sx \&Ox , | .Sx \&Ox , | ||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
. | |||
.Ss \&Cd | .Ss \&Cd | ||
Configuration declaration (suggested for use only in section four | Configuration declaration. | ||
manuals). This denotes strings accepted by | This denotes strings accepted by | ||
.Xr config 8 . | .Xr config 8 . | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Cd device le0 at scode? | ||
\&.Cd device le0 at scode? | |||
.Ed | |||
.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 | white-space and align consecutive | ||
.Sx \&Cd | .Sx \&Cd | ||
declarations. This practise is discouraged. | declarations. | ||
. | This practise is discouraged. | ||
.Ss \&Cm | .Ss \&Cm | ||
Command modifiers. Useful when specifying configuration options or | Command modifiers. | ||
keys. | Useful when specifying configuration options or keys. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Cm ControlPath | ||
\&.Cm ControlPath | .D1 \&.Cm ControlMaster | ||
\&.Cm ControlMaster | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Fl . | .Sx \&Fl . | ||
. | |||
.Ss \&D1 | .Ss \&D1 | ||
One-line indented display. This is formatted by the default rules and | One-line indented display. | ||
is useful for simple indented statements. It is followed by a newline. | This is formatted by the default rules and is useful for simple indented | ||
statements. | |||
It is followed by a newline. | |||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.D1 \&Fl abcdefgh | ||
\&.D1 Fl abcdefgh | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Bd | .Sx \&Bd | ||
and | and | ||
.Sx \&Dl . | .Sx \&Dl . | ||
. | |||
.Ss \&Db | .Ss \&Db | ||
.Ss \&Dc | .Ss \&Dc | ||
Closes a | Closes 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. This is the mandatory first macro of any | Document date. | ||
This is the mandatory first macro of any | |||
.Nm | .Nm | ||
manual. Its calling syntax is as follows: | manual. | ||
Its calling syntax is as follows: | |||
.Pp | .Pp | ||
.D1 \. Ns Sx \&Dd Cm date | .D1 \. Ns Sx \&Dd Cm date | ||
.Pp | .Pp | ||
|
|
||
If a date does not conform, the current date is used instead. | If a date does not conform, the current date is used instead. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Dd $\&Mdocdate$ | ||
\&.Dd $\&Mdocdate$ | .D1 \&.Dd $\&Mdocdate: July 21 2007$ | ||
\&.Dd $\&Mdocdate: July 21 2007$ | .D1 \&.Dd July 21, 2007 | ||
\&.Dd July 21, 2007 | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Dt | .Sx \&Dt | ||
and | and | ||
.Sx \&Os . | .Sx \&Os . | ||
. | |||
.Ss \&Dl | .Ss \&Dl | ||
One-line intended display. This is formatted as literal text and is | One-line intended display. | ||
useful for commands and invocations. It is followed by a newline. | This is formatted as literal text and is useful for commands and | ||
invocations. | |||
It is followed by a newline. | |||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Dl % mandoc mdoc.7 | less | ||
\&.Dl % mandoc mdoc.7 | less | |||
.Ed | |||
.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 | Begins a block enclosed by double quotes. Does not have any head | ||
arguments. | arguments. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.D1 \&Do April is the cruellest month \&Dc \e(em T.S. Eliot | ||
\&.D1 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 double quotes. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent -compact | ||
\&.Dq April is the cruellest month | \&.Dq April is the cruellest month | ||
\e(em T.S. Eliot | \e(em T.S. Eliot | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Do . | .Sx \&Do . | ||
. | |||
.Ss \&Dt | .Ss \&Dt | ||
Document title. This is the mandatory second macro of any | Document title. | ||
This is the mandatory second macro of any | |||
.Nm | .Nm | ||
file. Its calling syntax is as follows: | file. | ||
Its calling syntax is as follows: | |||
.Pp | .Pp | ||
.D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch | .D1 \. Ns Sx \&Dt Cm title section Op Cm volume | arch | ||
.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 Cm title | ||
The document's title (name). This should be capitalised and is | The document's title (name). | ||
required. | This should be capitalised and is required. | ||
.It Cm section | .It Cm section | ||
The manual section. This may be one of | The manual section. | ||
This may be one of | |||
.Ar 1 | .Ar 1 | ||
.Pq utilities , | .Pq utilities , | ||
.Ar 2 | .Ar 2 | ||
|
|
||
.Ar CON | .Ar CON | ||
.Pq contributed manuals . | .Pq contributed manuals . | ||
.It Cm arch | .It Cm arch | ||
This specifies a specific relevant architecture. If | This specifies a specific relevant architecture. | ||
If | |||
.Cm volume | .Cm 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. It, too, is optional. It must be one of | subsequent that. | ||
It, too, is optional. | |||
It must be one of | |||
.Ar alpha , | .Ar alpha , | ||
.Ar amd64 , | .Ar amd64 , | ||
.Ar amiga , | .Ar amiga , | ||
|
|
||
.El | .El | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Dt FOO 1 | ||
\&.Dt FOO 1 | .D1 \&.Dt FOO 4 KM | ||
\&.Dt FOO 4 KM | .D1 \&.Dt FOO 9 i386 | ||
\&.Dt FOO 9 i386 | .D1 \&.Dt FOO 9 KM i386 | ||
\&.Dt FOO 9 KM i386 | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Dd | .Sx \&Dd | ||
and | and | ||
.Sx \&Os . | .Sx \&Os . | ||
. | |||
.Ss \&Dv | .Ss \&Dv | ||
Defined variables such as preprocessor constants. | Defined variables such as preprocessor constants. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Dv BUFSIZ | ||
\&.Dv BUFSIZ | .D1 \&.Dv STDOUT_FILENO | ||
\&.Dv STDOUT_FILENO | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Er . | .Sx \&Er . | ||
. | |||
.Ss \&Dx | .Ss \&Dx | ||
Format the DragonFly BSD version provided as an argument, or a default | Format the DragonFly BSD version provided as an argument, or a default | ||
value if no argument is provided. | value if no argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Dx 2.4.1 | ||
\&.Dx 2.4.1 | .D1 \&.Dx | ||
\&.Dx | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
.Sx \&Ox , | .Sx \&Ox , | ||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
. | |||
.Ss \&Ec | .Ss \&Ec | ||
.Ss \&Ed | .Ss \&Ed | ||
.Ss \&Ef | .Ss \&Ef | ||
.Ss \&Ek | .Ss \&Ek | ||
.Ss \&El | .Ss \&El | ||
.Ss \&Em | .Ss \&Em | ||
Denotes text that should be emphasised. Note that this is a | Denotes text that should be emphasised. | ||
presentation term and should not be used for stylistically decorating | Note that this is a presentation term and should not be used for | ||
technical terms. | stylistically decorating technical terms. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Em Warnings! | ||
\&.Ed Warnings! | .D1 \&.Em Remarks : | ||
\&.Ed Remarks : | |||
.Ed | |||
. | |||
.Ss \&En | .Ss \&En | ||
.Ss \&Eo | .Ss \&Eo | ||
.Ss \&Er | .Ss \&Er | ||
Error constants (suggested for use only in section two manuals). | Display error constants. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Er EPERM | ||
\&.Er EPERM | .D1 \&.Er ENOENT | ||
\&.Er ENOENT | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Dv . | .Sx \&Dv . | ||
. | |||
.Ss \&Es | .Ss \&Es | ||
. | |||
.Ss \&Ev | .Ss \&Ev | ||
Environmental variables such as those specified in | Environmental variables such as those specified in | ||
.Xr environ 7 . | .Xr environ 7 . | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Ev DISPLAY | ||
\&.Ev DISPLAY | .D1 \&.Ev PATH | ||
\&.Ev PATH | |||
.Ed | |||
. | |||
.Ss \&Ex | .Ss \&Ex | ||
Inserts text regarding a utility's exit values. This macro must have | Inserts text regarding a utility's exit values. | ||
first the | This macro must have first the | ||
.Fl std | .Fl std | ||
argument specified, then an optional | argument specified, then an optional | ||
.Ar utility . | .Ar utility . | ||
|
|
||
.Ss \&Fc | .Ss \&Fc | ||
.Ss \&Fd | .Ss \&Fd | ||
.Ss \&Fl | .Ss \&Fl | ||
Command-line flag. Used when listing arguments to command-line | Command-line flag. | ||
utilities. Prints a fixed-width hyphen | Used when listing arguments to command-line utilities. | ||
Prints a fixed-width hyphen | |||
.Sq \- | .Sq \- | ||
before each delimited argument. If no arguments are provided, a hyphen | directly followed by each argument. | ||
is still printed. | If no arguments are provided, a hyphen is printed followed by a space. | ||
If the argument is a macro, a hyphen is prefixed to the subsequent macro | |||
output. | |||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Fl a b c | ||
\&.Fl a b c | .D1 \&.Fl \&Pf a b | ||
\&.Fl | .D1 \&.Fl | ||
\&.Op Fl o Ns Ar file | .D1 \&.Op \&Fl o \&Ns \&Ar file | ||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Cm . | .Sx \&Cm . | ||
. | |||
.Ss \&Fn | .Ss \&Fn | ||
.Ss \&Fo | .Ss \&Fo | ||
.Ss \&Fr | .Ss \&Fr | ||
|
|
||
if no argument is provided. | if no argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Fx 7.1 | ||
\&.Fx 7.1 | .D1 \&.Fx | ||
\&.Fx | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
.Sx \&Ox , | .Sx \&Ox , | ||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
. | |||
.Ss \&Hf | .Ss \&Hf | ||
.Ss \&Ic | .Ss \&Ic | ||
.Ss \&In | .Ss \&In | ||
|
|
||
.Ss \&Lb | .Ss \&Lb | ||
.Ss \&Li | .Ss \&Li | ||
.Ss \&Lk | .Ss \&Lk | ||
Format a hyperlink. The calling syntax is as follows: | Format a hyperlink. | ||
The calling syntax is as follows: | |||
.Pp | .Pp | ||
.D1 \. Ns Sx \&Lk Cm uri Op Cm name | .D1 \. Ns Sx \&Lk Cm uri Op Cm name | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Lk http://bsd.lv "The BSD.lv Project" | ||
\&.Lk http://bsd.lv "The BSD.lv Project" | .D1 \&.Lk http://bsd.lv | ||
\&.Lk http://bsd.lv | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Mt . | .Sx \&Mt . | ||
. | |||
.Ss \&Lp | .Ss \&Lp | ||
.Ss \&Ms | .Ss \&Ms | ||
.Ss \&Mt | .Ss \&Mt | ||
|
|
||
no argument is provided. | no argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Nx 5.01 | ||
\&.Nx 5.01 | .D1 \&.Nx | ||
\&.Nx | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
.Sx \&Ox , | .Sx \&Ox , | ||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
. | |||
.Ss \&Oc | .Ss \&Oc | ||
.Ss \&Oo | .Ss \&Oo | ||
.Ss \&Op | .Ss \&Op | ||
.Ss \&Os | .Ss \&Os | ||
Document operating system version. This is the mandatory third macro of | Document operating system version. | ||
This is the mandatory third macro of | |||
any | any | ||
.Nm | .Nm | ||
file. Its calling syntax is as follows: | file. Its calling syntax is as follows: | ||
|
|
||
.Pp | .Pp | ||
The optional | The optional | ||
.Cm system | .Cm system | ||
parameter specifies the relevant operating system or environment. Left | parameter specifies the relevant operating system or environment. | ||
unspecified, it defaults to the local operating system version. This is | Left unspecified, it defaults to the local operating system version. | ||
the suggested form. | This is the suggested form. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Os | ||
\&.Os | .D1 \&.Os KTH/CSC/TCS | ||
\&.Os KTH/CSC/TCS | .D1 \&.Os BSD 4.3 | ||
\&.Os BSD 4.3 | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Dd | .Sx \&Dd | ||
and | and | ||
.Sx \&Dt . | .Sx \&Dt . | ||
. | |||
.Ss \&Ot | .Ss \&Ot | ||
Unknown usage. | Unknown usage. | ||
.Pp | .Pp | ||
.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 OpenBSD version provided as an argument, or a default value | ||
if no argument is provided. | if no argument is provided. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Ox 4.5 | ||
\&.Ox 4.5 | .D1 \&.Ox | ||
\&.Ox | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
.Sx \&Nx , | .Sx \&Nx , | ||
and | and | ||
.Sx \&Ux . | .Sx \&Ux . | ||
. | |||
.Ss \&Pa | .Ss \&Pa | ||
.Ss \&Pc | .Ss \&Pc | ||
.Ss \&Pf | .Ss \&Pf | ||
|
|
||
.Ss \&Ql | .Ss \&Ql | ||
.Ss \&Qo | .Ss \&Qo | ||
.Ss \&Qq | .Ss \&Qq | ||
. | |||
.Ss \&Re | .Ss \&Re | ||
Closes a | Closes a | ||
.Sx \&Rs | .Sx \&Rs | ||
block. Does not have any tail arguments. | block. | ||
. | Does not have any tail arguments. | ||
.Ss \&Rs | .Ss \&Rs | ||
Begins a bibliographic | Begins a bibliographic | ||
.Pq Dq reference | .Pq Dq reference | ||
block. Does not have any head arguments. The block macro may only | block. | ||
contain | Does not have any head arguments. | ||
The block macro may only contain | |||
.Sx \&%A , | .Sx \&%A , | ||
.Sx \&%B , | .Sx \&%B , | ||
.Sx \&%C , | .Sx \&%C , | ||
|
|
||
child macros (at least one must be specified). | child macros (at least one must be specified). | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .Bd -literal -offset indent -compact | ||
\&.Rs | \&.Rs | ||
\&.%A J. E. Hopcroft | \&.%A J. E. Hopcroft | ||
\&.%A J. D. Ullman | \&.%A J. D. Ullman | ||
|
|
||
block is used within a SEE ALSO section, a vertical space is asserted | block is used within a SEE ALSO section, a vertical space is asserted | ||
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 | ||
.Ss \&Sc | .Ss \&Sc | ||
.Ss \&Sh | .Ss \&Sh | ||
|
|
||
.Ss \&Tn | .Ss \&Tn | ||
.Ss \&Ud | .Ss \&Ud | ||
.Ss \&Ux | .Ss \&Ux | ||
Format the UNIX name. Accepts no argument. | Format the UNIX name. | ||
Accepts no argument. | |||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Ux | ||
\&.Ux | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&At , | .Sx \&At , | ||
|
|
||
.Sx \&Nx , | .Sx \&Nx , | ||
and | and | ||
.Sx \&Ox . | .Sx \&Ox . | ||
. | |||
.Ss \&Va | .Ss \&Va | ||
.Ss \&Vt | .Ss \&Vt | ||
A variable type. This is also used for indicating global variables in the | A variable type. | ||
SYNOPSIS section, in which case a variable name is also specified. Note that | This is also used for indicating global variables in the SYNOPSIS | ||
it accepts | section, in which case a variable name is also specified. | ||
Note that it accepts | |||
.Sx Block partial-implicit | .Sx Block partial-implicit | ||
syntax when invoked as the first macro in the SYNOPSIS section, else it | syntax when invoked as the first macro in the SYNOPSIS section, else it | ||
accepts ordinary | accepts ordinary | ||
|
|
||
which is used for function return types. | which is used for function return types. | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Vt unsigned char | ||
\&.Vt unsigned char | .D1 \&.Vt extern const char * const sys_signame[] ; | ||
\&.Vt extern const char * const sys_signame[] ; | |||
.Ed | |||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&Ft | .Sx \&Ft | ||
and | and | ||
.Sx \&Va . | .Sx \&Va . | ||
. | |||
.Ss \&Xc | .Ss \&Xc | ||
Close a scope opened by | Close a scope opened by | ||
.Sx \&Xo . | .Sx \&Xo . | ||
. | |||
.Ss \&Xo | .Ss \&Xo | ||
Open an extension scope. This macro originally existed to extend the | Open an extension scope. | ||
9-argument limit of troff; since this limit has been lifted, the macro | This macro originally existed to extend the 9-argument limit of troff; | ||
has been deprecated. | since this limit has been lifted, the macro has been deprecated. | ||
. | |||
.Ss \&Xr | .Ss \&Xr | ||
Link to another manual | Link to another manual | ||
.Pq Qq cross-reference . | .Pq Qq cross-reference . | ||
|
|
||
.Cm name | .Cm name | ||
and | and | ||
.Cm section | .Cm section | ||
are the name and section of the linked manual. If | are the name and section of the linked manual. | ||
If | |||
.Cm section | .Cm section | ||
is followed by non-punctuation, an | is followed by non-punctuation, an | ||
.Sx \&Ns | .Sx \&Ns | ||
is inserted into the token stream. This behaviour is for compatibility | is inserted into the token stream. | ||
with | This behaviour is for compatibility with | ||
.Xr groff 1 . | .Xr groff 1 . | ||
.Pp | .Pp | ||
Examples: | Examples: | ||
.Bd -literal -offset indent | .D1 \&.Xr mandoc 1 | ||
\&.Xr mandoc 1 | .D1 \&.Xr mandoc 1 ; | ||
\&.Xr mandoc 1 ; | .D1 \&.Xr mandoc 1 \&Ns s behaviour | ||
\&.Xr mandoc 1 s behaviour | |||
.Ed | |||
. | |||
.Ss \&br | .Ss \&br | ||
.Ss \&sp | .Ss \&sp | ||
. | |||
. | |||
.Sh COMPATIBILITY | .Sh COMPATIBILITY | ||
This section documents compatibility with other roff implementations, at | This section documents compatibility between mandoc and other other | ||
this time limited to | troff implementations, at this time limited to GNU troff | ||
.Xr groff 1 . | .Pq Qq groff . | ||
The term | The term | ||
.Qq historic groff | .Qq historic groff | ||
refers to those versions before the | refers to groff versions before the | ||
.Pa doc.tmac | .Pa doc.tmac | ||
file re-write | file re-write | ||
.Pq somewhere between 1.15 and 1.19 . | .Pq somewhere between 1.15 and 1.19 . | ||
. | |||
.Pp | .Pp | ||
Heirloom troff, the other significant troff implementation accepting | |||
\-mdoc, is similar to historic groff. | |||
.Pp | |||
.Bl -dash -compact | .Bl -dash -compact | ||
.It | .It | ||
The comment syntax | The comment syntax | ||
.Sq \e." | .Sq \e." | ||
is no longer accepted. | is no longer accepted. | ||
.It | .It | ||
In | In groff, the | ||
.Xr groff 1 , | |||
the | |||
.Sx \&Pa | .Sx \&Pa | ||
macro does not format its arguments when used in the FILES section under | macro does not format its arguments when used in the FILES section under | ||
certain list types. This irregular behaviour has been discontinued. | certain list types. | ||
mandoc does. | |||
.It | .It | ||
Historic | Historic groff does not print a dash for empty | ||
.Xr groff 1 | |||
does not print a dash for empty | |||
.Sx \&Fl | .Sx \&Fl | ||
arguments. This behaviour has been discontinued. | arguments. | ||
mandoc and newer groff implementations do. | |||
.It | .It | ||
.Xr groff 1 | groff behaves irregularly when specifying | ||
behaves strangely (even between versions) when specifying | |||
.Sq \ef | .Sq \ef | ||
escapes within line-macro scopes. These aberrations have been | .Sx Text Decoration | ||
normalised. | within line-macro scopes. | ||
mandoc follows a consistent system. | |||
.It | .It | ||
Negative scaling units are now truncated to zero instead of creating | In mandoc, negative scaling units are truncated to zero; groff would | ||
interesting conditions, such as with | move to prior lines. | ||
.Sx \&sp | |||
.Fl 1i . | |||
Furthermore, the | Furthermore, the | ||
.Sq f | .Sq f | ||
scaling unit, while accepted, is rendered as the default unit. | scaling unit, while accepted, is rendered as the default unit. | ||
.It | .It | ||
In quoted literals, groff allowed pair-wise double-quotes to produce a | In quoted literals, groff allowed pair-wise double-quotes to produce a | ||
standalone double-quote in formatted output. This idiosyncratic | standalone double-quote in formatted output. | ||
behaviour is no longer applicable. | This idiosyncratic behaviour is not applicable in mandoc. | ||
.It | .It | ||
Display types | Display types | ||
.Sx \&Bd | .Sx \&Bd | ||
|
|
||
and | and | ||
.Fl right | .Fl right | ||
are aliases for | are aliases for | ||
.Fl left . | .Fl left | ||
The | in manodc. Furthermore, the | ||
.Fl file Ar file | .Fl file Ar file | ||
argument is ignored. Since text is not right-justified, | argument is ignored. | ||
Lastly, since text is not right-justified in mandoc (or even groff), | |||
.Fl ragged | .Fl ragged | ||
and | and | ||
.Fl filled | .Fl filled | ||
|
|
||
and | and | ||
.Fl unfilled . | .Fl unfilled . | ||
.It | .It | ||
Blocks of whitespace are stripped from both macro and free-form text | Historic groff has many un-callable macros. | ||
lines (except when in literal mode), while groff would retain whitespace | Most of these (excluding some block-level macros) are now callable. | ||
in free-form text lines. | |||
.It | .It | ||
Historic groff has many un-callable macros. Most of these (excluding | |||
some block-level macros) are now callable, conforming to the | |||
non-historic groff version. | |||
.It | |||
The vertical bar | The vertical bar | ||
.Sq \(ba | .Sq \(ba | ||
made historic groff | made historic groff | ||
.Qq go orbital | .Qq go orbital | ||
but is a proper delimiter in this implementation. | but has been a proper delimiter since then. | ||
.It | .It | ||
.Sx \&It | .Sx \&It Fl nested | ||
.Fl nested | |||
is assumed for all lists (it wasn't in historic groff): any list may be | is assumed for all lists (it wasn't in historic groff): any list may be | ||
nested and | nested and | ||
.Fl enum | .Fl enum | ||
|
|
||
Some manuals use | Some manuals use | ||
.Sx \&Li | .Sx \&Li | ||
incorrectly by following it with a reserved character and expecting the | incorrectly by following it with a reserved character and expecting the | ||
delimiter to render. This is not supported. | delimiter to render. | ||
This is not supported in mandoc. | |||
.It | .It | ||
In groff, the | In groff, the | ||
.Sx \&Fo | .Sx \&Fo | ||
macro only produces the first parameter. This is no longer the case. | macro only produces the first parameter. | ||
This is not the case in mandoc. | |||
.It | |||
In groff, the | |||
.Sx \&Cd , | |||
.Sx \&Er , | |||
.Sx \&Ex , | |||
and | |||
.Sx \&Rv | |||
macros were stipulated only to occur in certain manual sections. | |||
mandoc does not have these restrictions. | |||
.It | |||
Newer groff and mandoc print | |||
.Qq AT&T UNIX | |||
prior to unknown arguments of | |||
.Sx \&At ; | |||
older groff did nothing. | |||
.El | .El | ||
. | |||
. | |||
.Sh SEE ALSO | .Sh SEE ALSO | ||
.Xr mandoc 1 , | .Xr mandoc 1 , | ||
.Xr mandoc_char 7 | .Xr mandoc_char 7 | ||
. | |||
. | |||
.Sh AUTHORS | .Sh AUTHORS | ||
The | The | ||
.Nm | .Nm | ||
reference was written by | reference was written by | ||
.An Kristaps Dzonsons Aq kristaps@kth.se . | .An Kristaps Dzonsons Aq kristaps@bsd.lv . | ||
.\" | .\" | ||
.\" XXX: this really isn't the place for these caveats. | .\" XXX: this really isn't the place for these caveats. | ||
.\" . | .\" . |