Return to man.7 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.102, 2011/07/08 09:35:06 | version 1.117, 2012/06/20 22:06:30 | ||
---|---|---|---|
|
|
||
.\" $Id$ | .\" $Id$ | ||
.\" | .\" | ||
.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv> | .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> | ||
.\" Copyright (c) 2011 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 | ||
.\" purpose with or without fee is hereby granted, provided that the above | .\" purpose with or without fee is hereby granted, provided that the above | ||
|
|
||
.Os | .Os | ||
.Sh NAME | .Sh NAME | ||
.Nm man | .Nm man | ||
.Nd man language reference | .Nd legacy formatting language for manual pages | ||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||
The | Traditionally, the | ||
.Nm man | .Nm man | ||
language was historically used to format | language has been used to write | ||
.Ux | .Ux | ||
manuals. | manuals for the | ||
This reference document describes its syntax, structure, and usage. | .Xr man 1 | ||
utility. | |||
It supports limited control of presentational details like fonts, | |||
indentation and spacing. | |||
This reference document describes the structure of manual pages | |||
and the syntax and usage of the man language. | |||
.Pp | .Pp | ||
.Bf -emphasis | .Bf -emphasis | ||
Do not use | Do not use | ||
.Nm | .Nm | ||
to write your manuals. | to write your manuals: | ||
.Ef | .Ef | ||
It lacks support for semantic markup. | |||
Use the | Use the | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
language, instead. | language, instead. | ||
.Pp | .Pp | ||
A | In a | ||
.Nm | .Nm | ||
document follows simple rules: lines beginning with the control | document, lines beginning with the control character | ||
character | |||
.Sq \&. | .Sq \&. | ||
are parsed for macros. | are called | ||
Other lines are interpreted within the scope of | .Dq macro lines . | ||
prior macros: | The first word is the macro name. | ||
It usually consists of two capital letters. | |||
For a list of available macros, see | |||
.Sx MACRO OVERVIEW . | |||
The words following the macro name are arguments to the macro. | |||
.Pp | |||
Lines not beginning with the control character are called | |||
.Dq text lines . | |||
They provide free-form text to be printed; the formatting of the text | |||
depends on the respective processing context: | |||
.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 INPUT ENCODING | |||
.Nm | |||
documents may contain only graphable 7-bit ASCII characters, the | |||
space character, and the tab character. | |||
.Pp | .Pp | ||
Blank lines are acceptable; where found, the output will assert a | Many aspects of the basic syntax of the | ||
vertical space. | .Nm | ||
.Pp | language are based on the | ||
If the first character of a line is a space, that line is printed | .Xr roff 7 | ||
with a leading newline. | language; see the | ||
.Ss Comments | .Em LANGUAGE SYNTAX | ||
Text following a | |||
.Sq \e\*q , | |||
whether in a macro or free-form text line, is ignored to the end of | |||
line. | |||
A macro line with only a control character and comment escape, | |||
.Sq \&.\e\*q , | |||
is also ignored. | |||
Macro lines with only a control character and optionally whitespace are | |||
stripped from input. | |||
.Ss Special Characters | |||
Special characters may occur in both macro and free-form lines. | |||
Sequences begin with the escape character | |||
.Sq \e | |||
followed by either an open-parenthesis | |||
.Sq \&( | |||
for two-character sequences; an open-bracket | |||
.Sq \&[ | |||
for n-character sequences (terminated at a close-bracket | |||
.Sq \&] ) ; | |||
or a single one-character sequence. | |||
See | |||
.Xr mandoc_char 7 | |||
for a complete list. | |||
Examples include | |||
.Sq \e(em | |||
.Pq em-dash | |||
and | and | ||
.Sq \ee | .Em MACRO SYNTAX | ||
.Pq back-slash . | sections in the | ||
.Ss Text Decoration | .Xr roff 7 | ||
Terms may be text-decorated using the | manual for details, in particular regarding | ||
.Sq \ef | comments, escape sequences, whitespace, and quoting. | ||
escape followed by an indicator: B (bold), I (italic), R (Roman), or P | |||
(revert to previous mode): | |||
.Pp | |||
.D1 \efBbold\efR \efIitalic\efP | |||
.Pp | |||
A numerical representation 3, 2, or 1 (bold, italic, and Roman, | |||
respectively) may be used instead. | |||
A text decoration is only valid, if specified in free-form text, until | |||
the next macro invocation; if specified within a macro, it's only valid | |||
until the macro closes scope. | |||
Note that macros like | |||
.Sx \&BR | |||
open and close a font scope with each argument. | |||
.Pp | |||
The | |||
.Sq \ef | |||
attribute is forgotten when entering or exiting a macro block. | |||
.Ss Whitespace | |||
Whitespace consists of the space character. | |||
In free-form lines, whitespace is preserved within a line; unescaped | |||
trailing spaces are stripped from input (unless in a literal context). | |||
Blank free-form lines, which may include spaces, are permitted and | |||
rendered as an empty line. | |||
.Pp | |||
In macro lines, whitespace delimits arguments and is discarded. | |||
If arguments are quoted, whitespace within the quotes is retained. | |||
.Ss Scaling Widths | |||
Many macros support scaled widths for their arguments, such as | |||
stipulating a two-inch paragraph indentation with the following: | |||
.Bd -literal -offset indent | |||
\&.HP 2i | |||
.Ed | |||
.Pp | |||
The syntax for scaled widths is | |||
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:]? , | |||
where a decimal must be preceded or proceeded by at least one digit. | |||
Negative numbers, while accepted, are truncated to zero. | |||
The following scaling units are accepted: | |||
.Pp | |||
.Bl -tag -width Ds -offset indent -compact | |||
.It c | |||
centimetre | |||
.It i | |||
inch | |||
.It P | |||
pica (~1/6 inch) | |||
.It p | |||
point (~1/72 inch) | |||
.It f | |||
synonym for | |||
.Sq u | |||
.It v | |||
default vertical span | |||
.It m | |||
width of rendered | |||
.Sq m | |||
.Pq em | |||
character | |||
.It n | |||
width of rendered | |||
.Sq n | |||
.Pq en | |||
character | |||
.It u | |||
default horizontal span | |||
.It M | |||
mini-em (~1/100 em) | |||
.El | |||
.Pp | |||
Using anything other than | |||
.Sq m , | |||
.Sq n , | |||
.Sq u , | |||
or | |||
.Sq v | |||
is necessarily non-portable across output media. | |||
.Pp | |||
If a scaling unit is not provided, the numerical value is interpreted | |||
under the default rules of | |||
.Sq v | |||
for vertical spaces and | |||
.Sq u | |||
for horizontal ones. | |||
.Em Note : | |||
this differs from | |||
.Xr mdoc 7 , | |||
which, if a unit is not provided, will instead interpret the string as | |||
literal text. | |||
.Ss Sentence Spacing | |||
When composing a manual, make sure that 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 | |||
.Po | |||
.Sq \&) , | |||
.Sq \&] , | |||
.Sq \&' , | |||
.Sq \&" | |||
.Pc . | |||
.Sh MANUAL STRUCTURE | .Sh MANUAL STRUCTURE | ||
Each | Each | ||
.Nm | .Nm | ||
|
|
||
.Pp | .Pp | ||
Beyond | Beyond | ||
.Sx \&TH , | .Sx \&TH , | ||
at least one macro or text node must appear in the document. | at least one macro or text line must appear in the document. | ||
.Pp | .Pp | ||
The following is a well-formed skeleton | The following is a well-formed skeleton | ||
.Nm | .Nm | ||
|
|
||
\&.TH PROGNAME 1 2009-10-10 | \&.TH PROGNAME 1 2009-10-10 | ||
\&.SH NAME | \&.SH NAME | ||
\efBprogname\efR \e(en a description goes here | \efBprogname\efR \e(en a description goes here | ||
\&.\e\*q .SH LIBRARY | \&.\e\(dq .SH LIBRARY | ||
\&.\e\*q For sections 2 & 3 only. | \&.\e\(dq For sections 2 & 3 only. | ||
\&.\e\*q Not used in OpenBSD. | \&.\e\(dq Not used in OpenBSD. | ||
\&.SH SYNOPSIS | \&.SH SYNOPSIS | ||
\efBprogname\efR [\efB\e-options\efR] arguments... | \efBprogname\efR [\efB\e-options\efR] arguments... | ||
\&.SH DESCRIPTION | \&.SH DESCRIPTION | ||
The \efBfoo\efR utility processes files... | The \efBfoo\efR utility processes files... | ||
\&.\e\*q .SH IMPLEMENTATION NOTES | \&.\e\(dq .SH IMPLEMENTATION NOTES | ||
\&.\e\*q Not used in OpenBSD. | \&.\e\(dq Not used in OpenBSD. | ||
\&.\e\*q .SH RETURN VALUES | \&.\e\(dq .SH RETURN VALUES | ||
\&.\e\*q For sections 2, 3, & 9 only. | \&.\e\(dq For sections 2, 3, & 9 only. | ||
\&.\e\*q .SH ENVIRONMENT | \&.\e\(dq .SH ENVIRONMENT | ||
\&.\e\*q For sections 1, 6, 7, & 8 only. | \&.\e\(dq For sections 1, 6, 7, & 8 only. | ||
\&.\e\*q .SH FILES | \&.\e\(dq .SH FILES | ||
\&.\e\*q .SH EXIT STATUS | \&.\e\(dq .SH EXIT STATUS | ||
\&.\e\*q For sections 1, 6, & 8 only. | \&.\e\(dq For sections 1, 6, & 8 only. | ||
\&.\e\*q .SH EXAMPLES | \&.\e\(dq .SH EXAMPLES | ||
\&.\e\*q .SH DIAGNOSTICS | \&.\e\(dq .SH DIAGNOSTICS | ||
\&.\e\*q For sections 1, 4, 6, 7, & 8 only. | \&.\e\(dq For sections 1, 4, 6, 7, & 8 only. | ||
\&.\e\*q .SH ERRORS | \&.\e\(dq .SH ERRORS | ||
\&.\e\*q For sections 2, 3, & 9 only. | \&.\e\(dq For sections 2, 3, & 9 only. | ||
\&.\e\*q .SH SEE ALSO | \&.\e\(dq .SH SEE ALSO | ||
\&.\e\*q .BR foo ( 1 ) | \&.\e\(dq .BR foo ( 1 ) | ||
\&.\e\*q .SH STANDARDS | \&.\e\(dq .SH STANDARDS | ||
\&.\e\*q .SH HISTORY | \&.\e\(dq .SH HISTORY | ||
\&.\e\*q .SH AUTHORS | \&.\e\(dq .SH AUTHORS | ||
\&.\e\*q .SH CAVEATS | \&.\e\(dq .SH CAVEATS | ||
\&.\e\*q .SH BUGS | \&.\e\(dq .SH BUGS | ||
\&.\e\*q .SH SECURITY CONSIDERATIONS | \&.\e\(dq .SH SECURITY CONSIDERATIONS | ||
\&.\e\*q Not used in OpenBSD. | \&.\e\(dq Not used in OpenBSD. | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
The sections in a | The sections in a | ||
|
|
||
.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 OVERVIEW | ||
Macros are one to three characters in length and begin with a | This overview is sorted such that macros of similar purpose are listed | ||
control character, | together, to help find the best macro for any given purpose. | ||
.Sq \&. , | Deprecated macros are not included in the overview, but can be found | ||
at the beginning of the line. | in the alphabetical reference below. | ||
The | .Ss Page header and footer meta-data | ||
.Sq \(aq | .Bl -column "PP, LP, P" description | ||
macro control character is also accepted. | .It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume | ||
An arbitrary amount of whitespace (spaces or tabs) may sit between the | .It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument) | ||
control character and the macro name. | .It Sx UC Ta display BSD version in the page footer (<= 1 argument) | ||
Thus, the following are equivalent: | |||
.Bd -literal -offset indent | |||
\&.PP | |||
\&.\ \ \ PP | |||
.Ed | |||
.Pp | |||
To include space characters in macro arguments, arguments may be quoted; | |||
see the | |||
.Sq MACRO SYNTAX | |||
section in the | |||
.Xr roff 7 | |||
manual for details. | |||
.Pp | |||
The | |||
.Nm | |||
macros are classified by scope: line scope or block scope. | |||
Line macros are only scoped to the current line (and, in some | |||
situations, the subsequent line). | |||
Block macros are scoped to the current line and subsequent lines until | |||
closed by another block macro. | |||
.Ss Line Macros | |||
Line macros are generally scoped to the current line, with the body | |||
consisting of zero or more arguments. | |||
If a macro is scoped to the next line and the line arguments are empty, | |||
the next line, which must be text, is used instead. | |||
Thus: | |||
.Bd -literal -offset indent | |||
\&.I | |||
foo | |||
.Ed | |||
.Pp | |||
is equivalent to | |||
.Sq \&.I foo . | |||
If next-line macros are invoked consecutively, only the last is used. | |||
If a next-line macro is followed by a non-next-line macro, an error is | |||
raised, except for | |||
.Sx \&br , | |||
.Sx \&sp , | |||
and | |||
.Sx \&na . | |||
.Pp | |||
The syntax is as follows: | |||
.Bd -literal -offset indent | |||
\&.YO \(lBbody...\(rB | |||
\(lBbody...\(rB | |||
.Ed | |||
.Pp | |||
.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" | |||
.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes | |||
.It Sx \&AT Ta <=1 Ta current Ta \& | |||
.It Sx \&B Ta n Ta next-line Ta \& | |||
.It Sx \&BI Ta n Ta current Ta \& | |||
.It Sx \&BR Ta n Ta current Ta \& | |||
.It Sx \&DT Ta 0 Ta current Ta \& | |||
.It Sx \&I Ta n Ta next-line Ta \& | |||
.It Sx \&IB Ta n Ta current Ta \& | |||
.It Sx \&IR Ta n Ta current Ta \& | |||
.It Sx \&R Ta n Ta next-line Ta \& | |||
.It Sx \&RB Ta n Ta current Ta \& | |||
.It Sx \&RI Ta n Ta current Ta \& | |||
.It Sx \&SB Ta n Ta next-line Ta \& | |||
.It Sx \&SM Ta n Ta next-line Ta \& | |||
.It Sx \&TH Ta >1, <6 Ta current Ta \& | |||
.It Sx \&UC Ta <=1 Ta current Ta \& | |||
.It Sx \&br Ta 0 Ta current Ta compat | |||
.It Sx \&fi Ta 0 Ta current Ta compat | |||
.It Sx \&ft Ta 1 Ta current Ta compat | |||
.It Sx \&in Ta 1 Ta current Ta compat | |||
.It Sx \&na Ta 0 Ta current Ta compat | |||
.It Sx \&nf Ta 0 Ta current Ta compat | |||
.It Sx \&sp Ta 1 Ta current Ta compat | |||
.El | .El | ||
.Pp | .Ss Sections and paragraphs | ||
Macros marked as | .Bl -column "PP, LP, P" description | ||
.Qq compat | .It Sx SH Ta section header (one line) | ||
are included for compatibility with the significant corpus of existing | .It Sx SS Ta subsection header (one line) | ||
manuals that mix dialects of roff. | .It Sx PP , LP , P Ta start an undecorated paragraph (no arguments) | ||
These macros should not be used for portable | .It Sx RS , RE Ta reset the left margin: Op Ar width | ||
.Nm | .It Sx IP Ta indented paragraph: Op Ar head Op Ar width | ||
manuals. | .It Sx TP Ta tagged paragraph: Op Ar width | ||
.Ss Block Macros | .It Sx HP Ta hanged paragraph: Op Ar width | ||
Block macros comprise a head and body. | .It Sx \&br Ta force output line break in text mode (no arguments) | ||
As with in-line macros, the head is scoped to the current line and, in | .It Sx \&sp Ta force vertical space: Op Ar height | ||
one circumstance, the next line (the next-line stipulations as in | .It Sx fi , nf Ta fill mode and no-fill mode (no arguments) | ||
.Sx Line Macros | .It Sx in Ta additional indent: Op Ar width | ||
apply here as well). | |||
.Pp | |||
The syntax is as follows: | |||
.Bd -literal -offset indent | |||
\&.YO \(lBhead...\(rB | |||
\(lBhead...\(rB | |||
\(lBbody...\(rB | |||
.Ed | |||
.Pp | |||
The closure of body scope may be to the section, where a macro is closed | |||
by | |||
.Sx \&SH ; | |||
sub-section, closed by a section or | |||
.Sx \&SS ; | |||
part, closed by a section, sub-section, or | |||
.Sx \&RE ; | |||
or paragraph, closed by a section, sub-section, part, | |||
.Sx \&HP , | |||
.Sx \&IP , | |||
.Sx \&LP , | |||
.Sx \&P , | |||
.Sx \&PP , | |||
or | |||
.Sx \&TP . | |||
No closure refers to an explicit block closing macro. | |||
.Pp | |||
As a rule, block macros may not be nested; thus, calling a block macro | |||
while another block macro scope is open, and the open scope is not | |||
implicitly closed, is syntactically incorrect. | |||
.Pp | |||
.Bl -column -compact -offset indent "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" | |||
.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes | |||
.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& | |||
.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& | |||
.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& | |||
.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& | |||
.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& | |||
.It Sx \&RE Ta 0 Ta current Ta none Ta compat | |||
.It Sx \&RS Ta 1 Ta current Ta part Ta compat | |||
.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& | |||
.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& | |||
.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& | |||
.El | .El | ||
.Pp | .Ss Physical markup | ||
Macros marked | .Bl -column "PP, LP, P" description | ||
.Qq compat | .It Sx B Ta boldface font | ||
are as mentioned in | .It Sx I Ta italic font | ||
.Sx Line Macros . | .It Sx R Ta roman (default) font | ||
.Pp | .It Sx SB Ta small boldface font | ||
If a block macro is next-line scoped, it may only be followed by in-line | .It Sx SM Ta small roman font | ||
macros for decorating text. | .It Sx BI Ta alternate between boldface and italic fonts | ||
.Sh REFERENCE | .It Sx BR Ta alternate between boldface and roman fonts | ||
.It Sx IB Ta alternate between italic and boldface fonts | |||
.It Sx IR Ta alternate between italic and roman fonts | |||
.It Sx RB Ta alternate between roman and boldface fonts | |||
.It Sx RI Ta alternate between roman and italic fonts | |||
.El | |||
.Sh MACRO REFERENCE | |||
This section is a canonical reference to all macros, arranged | This section is a canonical reference to all macros, arranged | ||
alphabetically. | alphabetically. | ||
For the scoping of individual macros, see | For the scoping of individual macros, see | ||
|
|
||
.Ss \&DT | .Ss \&DT | ||
Has no effect. | Has no effect. | ||
Included for compatibility. | Included for compatibility. | ||
.Ss \&EE | |||
This is a non-standard GNU extension, included only for compatibility. | |||
In | |||
.Xr mandoc 1 , | |||
it does the same as | |||
.Sx \&fi . | |||
.Ss \&EX | |||
This is a non-standard GNU extension, included only for compatibility. | |||
In | |||
.Xr mandoc 1 , | |||
it does the same as | |||
.Sx \&nf . | |||
.Ss \&HP | .Ss \&HP | ||
Begin a paragraph whose initial output line is left-justified, but | Begin a paragraph whose initial output line is left-justified, but | ||
subsequent output lines are indented, with the following syntax: | subsequent output lines are indented, with the following syntax: | ||
|
|
||
.Pp | .Pp | ||
The | The | ||
.Cm width | .Cm width | ||
argument must conform to | argument is a | ||
.Sx Scaling Widths . | .Xr roff 7 | ||
scaling width. | |||
If specified, it's saved for later paragraph left-margins; if unspecified, the | If specified, it's saved for later paragraph left-margins; if unspecified, the | ||
saved or default width is used. | saved or default width is used. | ||
.Pp | .Pp | ||
|
|
||
.Pp | .Pp | ||
The | The | ||
.Cm width | .Cm width | ||
argument defines the width of the left margin and is defined by | argument is a | ||
.Sx Scaling Widths . | .Xr roff 7 | ||
scaling width defining the left margin. | |||
It's saved for later paragraph left-margins; if unspecified, the saved or | It's saved for later paragraph left-margins; if unspecified, the saved or | ||
default width is used. | default width is used. | ||
.Pp | .Pp | ||
|
|
||
.Sx \&PP , | .Sx \&PP , | ||
and | and | ||
.Sx \&TP . | .Sx \&TP . | ||
.Ss \&OP | |||
Optional command-line argument. | |||
This is a non-standard GNU extension, included only for compatibility. | |||
It has the following syntax: | |||
.Bd -filled -offset indent | |||
.Pf \. Sx \&OP | |||
.Cm key Op Cm value | |||
.Ed | |||
.Pp | |||
The | |||
.Cm key | |||
is usually a command-line flag and | |||
.Cm value | |||
its argument. | |||
.Ss \&P | .Ss \&P | ||
Synonym for | Synonym for | ||
.Sx \&LP . | .Sx \&LP . | ||
|
|
||
.Pp | .Pp | ||
The | The | ||
.Cm width | .Cm width | ||
argument must conform to | argument is a | ||
.Sx Scaling Widths . | .Xr roff 7 | ||
scaling width. | |||
If not specified, the saved or default width is used. | If not specified, the saved or default width is used. | ||
.Pp | .Pp | ||
See also | See also | ||
|
|
||
.Pp | .Pp | ||
The | The | ||
.Cm width | .Cm width | ||
argument must conform to | argument is a | ||
.Sx Scaling Widths . | .Xr roff 7 | ||
scaling width. | |||
If specified, it's saved for later paragraph left-margins; if | If specified, it's saved for later paragraph left-margins; if | ||
unspecified, the saved or default width is used. | unspecified, the saved or default width is used. | ||
.Pp | .Pp | ||
|
|
||
.Op Cm height | .Op Cm height | ||
.Ed | .Ed | ||
.Pp | .Pp | ||
Insert | The | ||
.Cm height | .Cm height | ||
spaces, which must conform to | argument is a scaling width as described in | ||
.Sx Scaling Widths . | .Xr roff 7 . | ||
If 0, this is equivalent to the | If 0, this is equivalent to the | ||
.Sx \&br | .Sx \&br | ||
macro. | macro. | ||
|
|
||
.Pp | .Pp | ||
See also | See also | ||
.Sx \&br . | .Sx \&br . | ||
.Sh MACRO SYNTAX | |||
The | |||
.Nm | |||
macros are classified by scope: line scope or block scope. | |||
Line macros are only scoped to the current line (and, in some | |||
situations, the subsequent line). | |||
Block macros are scoped to the current line and subsequent lines until | |||
closed by another block macro. | |||
.Ss Line Macros | |||
Line macros are generally scoped to the current line, with the body | |||
consisting of zero or more arguments. | |||
If a macro is scoped to the next line and the line arguments are empty, | |||
the next line, which must be text, is used instead. | |||
Thus: | |||
.Bd -literal -offset indent | |||
\&.I | |||
foo | |||
.Ed | |||
.Pp | |||
is equivalent to | |||
.Sq \&.I foo . | |||
If next-line macros are invoked consecutively, only the last is used. | |||
If a next-line macro is followed by a non-next-line macro, an error is | |||
raised, except for | |||
.Sx \&br , | |||
.Sx \&sp , | |||
and | |||
.Sx \&na . | |||
.Pp | |||
The syntax is as follows: | |||
.Bd -literal -offset indent | |||
\&.YO \(lBbody...\(rB | |||
\(lBbody...\(rB | |||
.Ed | |||
.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent | |||
.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes | |||
.It Sx \&AT Ta <=1 Ta current Ta \& | |||
.It Sx \&B Ta n Ta next-line Ta \& | |||
.It Sx \&BI Ta n Ta current Ta \& | |||
.It Sx \&BR Ta n Ta current Ta \& | |||
.It Sx \&DT Ta 0 Ta current Ta \& | |||
.It Sx \&I Ta n Ta next-line Ta \& | |||
.It Sx \&IB Ta n Ta current Ta \& | |||
.It Sx \&IR Ta n Ta current Ta \& | |||
.It Sx \&OP Ta 0, 1 Ta current Ta compat | |||
.It Sx \&R Ta n Ta next-line Ta \& | |||
.It Sx \&RB Ta n Ta current Ta \& | |||
.It Sx \&RI Ta n Ta current Ta \& | |||
.It Sx \&SB Ta n Ta next-line Ta \& | |||
.It Sx \&SM Ta n Ta next-line Ta \& | |||
.It Sx \&TH Ta >1, <6 Ta current Ta \& | |||
.It Sx \&UC Ta <=1 Ta current Ta \& | |||
.It Sx \&br Ta 0 Ta current Ta compat | |||
.It Sx \&fi Ta 0 Ta current Ta compat | |||
.It Sx \&ft Ta 1 Ta current Ta compat | |||
.It Sx \&in Ta 1 Ta current Ta compat | |||
.It Sx \&na Ta 0 Ta current Ta compat | |||
.It Sx \&nf Ta 0 Ta current Ta compat | |||
.It Sx \&sp Ta 1 Ta current Ta compat | |||
.El | |||
.Pp | |||
Macros marked as | |||
.Qq compat | |||
are included for compatibility with the significant corpus of existing | |||
manuals that mix dialects of roff. | |||
These macros should not be used for portable | |||
.Nm | |||
manuals. | |||
.Ss Block Macros | |||
Block macros comprise a head and body. | |||
As with in-line macros, the head is scoped to the current line and, in | |||
one circumstance, the next line (the next-line stipulations as in | |||
.Sx Line Macros | |||
apply here as well). | |||
.Pp | |||
The syntax is as follows: | |||
.Bd -literal -offset indent | |||
\&.YO \(lBhead...\(rB | |||
\(lBhead...\(rB | |||
\(lBbody...\(rB | |||
.Ed | |||
.Pp | |||
The closure of body scope may be to the section, where a macro is closed | |||
by | |||
.Sx \&SH ; | |||
sub-section, closed by a section or | |||
.Sx \&SS ; | |||
part, closed by a section, sub-section, or | |||
.Sx \&RE ; | |||
or paragraph, closed by a section, sub-section, part, | |||
.Sx \&HP , | |||
.Sx \&IP , | |||
.Sx \&LP , | |||
.Sx \&P , | |||
.Sx \&PP , | |||
or | |||
.Sx \&TP . | |||
No closure refers to an explicit block closing macro. | |||
.Pp | |||
As a rule, block macros may not be nested; thus, calling a block macro | |||
while another block macro scope is open, and the open scope is not | |||
implicitly closed, is syntactically incorrect. | |||
.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent | |||
.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes | |||
.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& | |||
.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& | |||
.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& | |||
.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& | |||
.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& | |||
.It Sx \&RE Ta 0 Ta current Ta none Ta compat | |||
.It Sx \&RS Ta 1 Ta current Ta part Ta compat | |||
.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& | |||
.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& | |||
.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& | |||
.El | |||
.Pp | |||
Macros marked | |||
.Qq compat | |||
are as mentioned in | |||
.Sx Line Macros . | |||
.Pp | |||
If a block macro is next-line scoped, it may only be followed by in-line | |||
macros for decorating text. | |||
.Ss Font handling | |||
In | |||
.Nm | |||
documents, both | |||
.Sx Physical markup | |||
macros and | |||
.Xr roff 7 | |||
.Ql \ef | |||
font escape sequences can be used to choose fonts. | |||
In text lines, the effect of manual font selection by escape sequences | |||
only lasts until the next macro invocation; in macro lines, it only lasts | |||
until the end of the macro scope. | |||
Note that macros like | |||
.Sx \&BR | |||
open and close a font scope for each argument. | |||
.Sh COMPATIBILITY | .Sh COMPATIBILITY | ||
This section documents areas of questionable portability between | This section documents areas of questionable portability between | ||
implementations of the | implementations of the | ||
|
|
||
.Pp | .Pp | ||
.Bl -dash -compact | .Bl -dash -compact | ||
.It | .It | ||
Do not depend on | |||
.Sx \&SH | |||
or | |||
.Sx \&SS | |||
to close out a literal context opened with | |||
.Sx \&nf . | |||
This behaviour may not be portable. | |||
.It | |||
In quoted literals, GNU troff allowed pair-wise double-quotes to produce | In quoted literals, GNU troff allowed pair-wise double-quotes to produce | ||
a standalone double-quote in formatted output. | a standalone double-quote in formatted output. | ||
It is not known whether this behaviour is exhibited by other formatters. | It is not known whether this behaviour is exhibited by other formatters. | ||
|
|
||
.Sx \&sp | .Sx \&sp | ||
macro does not accept negative values in mandoc. | macro does not accept negative values in mandoc. | ||
In GNU troff, this would result in strange behaviour. | In GNU troff, this would result in strange behaviour. | ||
.It | |||
In page header lines, GNU troff versions up to and including 1.21 | |||
only print | |||
.Ar volume | |||
names explicitly specified in the | |||
.Sx \&TH | |||
macro; mandoc and newer groff print the default volume name | |||
corresponding to the | |||
.Ar section | |||
number when no | |||
.Ar volume | |||
is given, like in | |||
.Xr mdoc 7 . | |||
.El | .El | ||
.Pp | |||
The | |||
.Sx OP | |||
macro is part of the extended | |||
.Nm | |||
macro set, and may not be portable to non-GNU troff implementations. | |||
.Sh SEE ALSO | .Sh SEE ALSO | ||
.Xr man 1 , | .Xr man 1 , | ||
.Xr mandoc 1 , | .Xr mandoc 1 , | ||
|
|
||
system in | system in | ||
.At v7 . | .At v7 . | ||
It was later rewritten by James Clark as a macro package for groff. | It was later rewritten by James Clark as a macro package for groff. | ||
Eric S. Raymond wrote the extended | |||
.Nm | |||
macros for groff in 2007. | |||
The stand-alone implementation that is part of the | The stand-alone implementation that is part of the | ||
.Xr mandoc 1 | .Xr mandoc 1 | ||
utility written by Kristaps Dzonsons appeared in | utility written by Kristaps Dzonsons appeared in | ||
|
|
||
This | This | ||
.Nm | .Nm | ||
reference was written by | reference was written by | ||
.An Kristaps Dzonsons Aq kristaps@bsd.lv . | .An Kristaps Dzonsons , | ||
.Mt kristaps@bsd.lv . | |||
.Sh CAVEATS | .Sh CAVEATS | ||
Do not use this language. | Do not use this language. | ||
Use | Use |