Return to man.7 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.109, 2011/09/06 17:56:00 | version 1.127, 2014/06/22 16:39:45 | ||
---|---|---|---|
|
|
||
.\" $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, 2012, 2013 Ingo Schwarze <schwarze@openbsd.org> | |||
.\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.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 | ||
Lines not beginning with the control character are | .Dq macro lines . | ||
interpreted within the scope of 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. | ||
Text lines are interpreted within the current state. | Text lines are interpreted within the current state. | ||
.Ed | .Ed | ||
.Sh LANGUAGE SYNTAX | |||
.Nm | |||
documents may contain only graphable 7-bit ASCII characters, the | |||
space character, and the tab character. | |||
The back-space character | |||
.Sq \e | |||
indicates the start of an escape sequence for | |||
.Sx Comments , | |||
.Sx Predefined Strings , | |||
and | |||
.Sx Special Characters . | |||
.Ss Comments | |||
Text following an escaped double-quote | |||
.Sq \e\(dq , | |||
whether in a macro or text line, is ignored to the end of | |||
line. | |||
A macro line beginning with a control character and comment escape | |||
.Sq \&.\e\(dq | |||
is also ignored. | |||
Furthermore, | |||
macro lines with only a control character and optional trailing | |||
whitespace are | |||
stripped from input. | |||
.Pp | .Pp | ||
Examples: | Many aspects of the basic syntax of the | ||
.Bd -literal -offset indent -compact | |||
\&.\e\(dq This is a comment line. | |||
\&.\e\(dq The next line is ignored: | |||
\&. | |||
\&.Em Emphasis \e\(dq This is also a comment. | |||
.Ed | |||
.Ss Special Characters | |||
Special characters are used to encode special glyphs and are rendered | |||
differently across output media. | |||
They may occur in both macro and text 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. | |||
.Pp | |||
Examples: | |||
.Bl -tag -width Ds -offset indent -compact | |||
.It Li \e(em | |||
Two-letter em dash escape. | |||
.It Li \ee | |||
One-letter backslash escape. | |||
.El | |||
.Pp | |||
See | |||
.Xr mandoc_char 7 | |||
for a complete list. | |||
.Ss Text Decoration | |||
Terms may be text-decorated using the | |||
.Sq \ef | |||
escape followed by an indicator: B (bold), I (italic), R (regular), or P | |||
(revert to previous mode). | |||
A numerical representation 3, 2, or 1 (bold, italic, and regular, | |||
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. | |||
.Pp | |||
Examples: | |||
.Bl -tag -width Ds -offset indent -compact | |||
.It Li \efBbold\efR | |||
Write in bold, then switch to regular font mode. | |||
.It Li \efIitalic\efP | |||
Write in italic, then return to previous font mode. | |||
.El | |||
.Ss Predefined Strings | |||
Predefined strings, like | |||
.Sx Special Characters , | |||
mark special output glyphs. | |||
Predefined strings are escaped with the slash-asterisk, | |||
.Sq \e* : | |||
single-character | |||
.Sq \e*X , | |||
two-character | |||
.Sq \e*(XX , | |||
and N-character | |||
.Sq \e*[N] . | |||
.Pp | |||
Examples: | |||
.Bl -tag -width Ds -offset indent -compact | |||
.It Li \e*(Am | |||
Two-letter ampersand predefined string. | |||
.It Li \e*q | |||
One-letter double-quote predefined string. | |||
.El | |||
.Pp | |||
These strings are set using | |||
.Xr roff 7 , | |||
although | |||
.Nm | .Nm | ||
consists of several pre-set escapes listed in | language are based on the | ||
.Xr mandoc_char 7 . | .Xr roff 7 | ||
.Ss Whitespace | language; see the | ||
Whitespace consists of the space character. | .Em LANGUAGE SYNTAX | ||
In text lines, whitespace is preserved within a line. | |||
In macro lines, whitespace delimits arguments and is discarded. | |||
.Pp | |||
Unescaped trailing spaces are stripped from text line input unless in a | |||
literal context. | |||
In general, trailing whitespace on any input line is discouraged for | |||
reasons of portability. | |||
In the rare case that a blank character is needed at the end of an | |||
input line, it may be forced by | |||
.Sq \e\ \e& . | |||
.Pp | |||
In general, space characters can be rendered as literal | |||
characters by using non-breaking space escapes or | |||
.Sx Quotation . | |||
If the first character of a text line is a space, that line is printed | |||
with a leading newline. | |||
.Ss Quotation | |||
Macro arguments may be quoted with double-quotes to so that the | |||
enclosed text is one literal term. | |||
Quoted text, even if whitespace or if it would cause a macro invocation | |||
when unquoted, is considered literal text. | |||
.Pp | |||
A quoted argument begins with a double-quote preceded by whitespace. | |||
The next double-quote not pairwise adjacent to another double-quote | |||
terminates the literal, regardless of surrounding whitespace. | |||
.Pp | |||
Examples: | |||
.Bl -tag -width Ds -offset indent -compact | |||
.It Li .BR a \(dqb c\(dq d | |||
Group arguments | |||
.Qq b c | |||
into one un-bolded argument. | |||
If unspecified, | |||
.Qq a | |||
and | and | ||
.Qq c | .Em MACRO SYNTAX | ||
will be in bold, | sections in the | ||
.Qq b | .Xr roff 7 | ||
and | manual for details, in particular regarding | ||
.Qq d | comments, escape sequences, whitespace, and quoting. | ||
in regular font mode. | |||
Furthermore, will be preserved between | |||
.Qq b | |||
and | |||
.Qq c . | |||
.El | |||
.Ss Scaling Widths | |||
Many macros support scaled widths for their arguments. | |||
The syntax for a scaled width 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. | |||
.Pp | |||
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. | |||
See | |||
.Sx COMPATIBILITY . | |||
.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. | |||
.Pp | |||
Examples: | |||
.Bl -tag -width Ds -offset indent -compact | |||
.It \&.HP 2i | |||
two-inch tagged list indentation | |||
.Pq see Sx \&HP | |||
.It \&.sp 2v | |||
two vertical spaces | |||
.Pq see Sx \&sp | |||
.El | |||
.Ss Sentence Spacing | |||
Sentences should terminate at the end of an input line. | |||
By doing this, a formatter 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 . | |||
.Pp | |||
Examples: | |||
.Bd -literal -offset indent -compact | |||
Do not end sentences mid-line like this. Instead, | |||
end a sentence like this. | |||
A new sentence gets a new line. | |||
.Ed | |||
.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 | ||
|
|
||
.Bd -literal -offset indent | .Bd -literal -offset indent | ||
\&.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 one line about what it does | ||
\&.\e\(dq .SH LIBRARY | \&.\e\(dq .SH LIBRARY | ||
\&.\e\(dq For sections 2 & 3 only. | \&.\e\(dq For sections 2, 3, and 9 only. | ||
\&.\e\(dq 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] \efIfile ...\efR | ||
\&.SH DESCRIPTION | \&.SH DESCRIPTION | ||
The \efBfoo\efR utility processes files... | The \efBfoo\efR utility processes files ... | ||
\&.\e\(dq .Sh CONTEXT | |||
\&.\e\(dq For section 9 functions only. | |||
\&.\e\(dq .SH IMPLEMENTATION NOTES | \&.\e\(dq .SH IMPLEMENTATION NOTES | ||
\&.\e\(dq Not used in OpenBSD. | \&.\e\(dq Not used in OpenBSD. | ||
\&.\e\(dq .SH RETURN VALUES | \&.\e\(dq .SH RETURN VALUES | ||
\&.\e\(dq For sections 2, 3, & 9 only. | \&.\e\(dq For sections 2, 3, and 9 function return values only. | ||
\&.\e\(dq .SH ENVIRONMENT | \&.\e\(dq .SH ENVIRONMENT | ||
\&.\e\(dq For sections 1, 6, 7, & 8 only. | \&.\e\(dq For sections 1, 6, 7, and 8 only. | ||
\&.\e\(dq .SH FILES | \&.\e\(dq .SH FILES | ||
\&.\e\(dq .SH EXIT STATUS | \&.\e\(dq .SH EXIT STATUS | ||
\&.\e\(dq For sections 1, 6, & 8 only. | \&.\e\(dq For sections 1, 6, and 8 only. | ||
\&.\e\(dq .SH EXAMPLES | \&.\e\(dq .SH EXAMPLES | ||
\&.\e\(dq .SH DIAGNOSTICS | \&.\e\(dq .SH DIAGNOSTICS | ||
\&.\e\(dq For sections 1, 4, 6, 7, & 8 only. | \&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. | ||
\&.\e\(dq .SH ERRORS | \&.\e\(dq .SH ERRORS | ||
\&.\e\(dq For sections 2, 3, & 9 only. | \&.\e\(dq For sections 2, 3, 4, and 9 errno settings only. | ||
\&.\e\(dq .SH SEE ALSO | \&.\e\(dq .SH SEE ALSO | ||
\&.\e\(dq .BR foo ( 1 ) | \&.\e\(dq .BR foobar ( 1 ) | ||
\&.\e\(dq .SH STANDARDS | \&.\e\(dq .SH STANDARDS | ||
\&.\e\(dq .SH HISTORY | \&.\e\(dq .SH HISTORY | ||
\&.\e\(dq .SH AUTHORS | \&.\e\(dq .SH AUTHORS | ||
|
|
||
.Em NAME . | .Em NAME . | ||
It usually contains a break-down of the options (if documenting a | It usually contains a break-down of the options (if documenting a | ||
command). | command). | ||
.It Em CONTEXT | |||
This section lists the contexts in which functions can be called in section 9. | |||
The contexts are autoconf, process, or interrupt. | |||
.It Em IMPLEMENTATION NOTES | .It Em IMPLEMENTATION NOTES | ||
Implementation-specific notes should be kept here. | Implementation-specific notes should be kept here. | ||
This is useful when implementing standard functions that may have side | This is useful when implementing standard functions that may have side | ||
|
|
||
Make sure that examples work properly! | Make sure that examples work properly! | ||
.It Em DIAGNOSTICS | .It Em DIAGNOSTICS | ||
Documents error conditions. | Documents error conditions. | ||
This is most useful in section 4 manuals. | In section 4 and 9 manuals, these are usually messages | ||
printed by the kernel to the console and to the kernel log. | |||
In section 1, 6, 7, and 8, these are usually messages | |||
printed by userland programs to the standard error output. | |||
.Pp | |||
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 | ||
discouraged. | discouraged. | ||
.It Em ERRORS | .It Em ERRORS | ||
Documents error handling in sections 2, 3, and 9. | Documents | ||
.Xr errno 2 | |||
settings in sections 2, 3, 4, and 9. | |||
.It Em SEE ALSO | .It Em SEE ALSO | ||
References other manuals with related topics. | References other manuals with related topics. | ||
This section should exist for most manuals. | This section should exist for most manuals. | ||
|
|
||
.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 | |||
.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 \&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 PD Ta set vertical paragraph distance: Op Ar height | ||
As with in-line macros, the head is scoped to the current line and, in | .It Sx \&br Ta force output line break in text mode (no arguments) | ||
one circumstance, the next line (the next-line stipulations as in | .It Sx \&sp Ta force vertical space: Op Ar height | ||
.Sx Line Macros | .It Sx fi , nf Ta fill mode and no-fill mode (no arguments) | ||
apply here as well). | .It Sx in Ta additional indent: Op Ar width | ||
.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 | .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 | ||
.Sx MACRO SYNTAX . | .Sx MACRO SYNTAX . | ||
.Ss \&AT | .Ss \&AT | ||
Sets the volume for the footer for compatibility with man pages from | Sets the volume for the footer for compatibility with man pages from | ||
.Tn AT&T UNIX | .At | ||
releases. | releases. | ||
The optional arguments specify which release it is from. | The optional arguments specify which release it is from. | ||
.Ss \&B | .Ss \&B | ||
|
|
||
.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 . | ||
|
|
||
.Sx \&PP , | .Sx \&PP , | ||
and | and | ||
.Sx \&TP . | .Sx \&TP . | ||
.Ss \&PD | |||
Specify the vertical space to be inserted before each new paragraph. | |||
.br | |||
The syntax is as follows: | |||
.Bd -filled -offset indent | |||
.Pf \. Sx \&PD | |||
.Op Cm height | |||
.Ed | |||
.Pp | |||
The | |||
.Cm height | |||
argument is a | |||
.Xr roff 7 | |||
scaling width. | |||
It defaults to | |||
.Cm 1v . | |||
If the unit is omitted, | |||
.Cm v | |||
is assumed. | |||
.Pp | |||
This macro affects the spacing before any subsequent instances of | |||
.Sx \&HP , | |||
.Sx \&IP , | |||
.Sx \&LP , | |||
.Sx \&P , | |||
.Sx \&PP , | |||
.Sx \&SH , | |||
.Sx \&SS , | |||
and | |||
.Sx \&TP . | |||
.Ss \&PP | .Ss \&PP | ||
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 | ||
|
|
||
.Sx \&PP . | .Sx \&PP . | ||
.Ss \&UC | .Ss \&UC | ||
Sets the volume for the footer for compatibility with man pages from | Sets the volume for the footer for compatibility with man pages from | ||
BSD releases. | .Bx | ||
releases. | |||
The optional first argument specifies which release it is from. | The optional first argument specifies which release it is from. | ||
.Ss \&UE | |||
End a uniform resource identifier block. | |||
This is a non-standard GNU extension, included only for compatibility. | |||
See | |||
.Sx \&UE . | |||
.Ss \&UR | |||
Begin a uniform resource identifier block. | |||
This is a non-standard GNU extension, included only for compatibility. | |||
It has the following syntax: | |||
.Bd -literal -offset indent | |||
.Pf \. Sx \&UR Ar uri | |||
link description to be shown | |||
.Pf \. Sx UE | |||
.Ed | |||
.Ss \&br | .Ss \&br | ||
Breaks the current line. | Breaks the current line. | ||
Consecutive invocations have no further effect. | Consecutive invocations have no further effect. | ||
|
|
||
.Ss \&fi | .Ss \&fi | ||
End literal mode begun by | End literal mode begun by | ||
.Sx \&nf . | .Sx \&nf . | ||
.Ss \&ft | |||
Change the current font mode. | |||
See | |||
.Sx Text Decoration | |||
for a listing of available font modes. | |||
.Ss \&in | .Ss \&in | ||
Indent relative to the current indentation: | Indent relative to the current indentation: | ||
.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 \&EE Ta 0 Ta current Ta compat | |||
.It Sx \&EX Ta 0 Ta current Ta compat | |||
.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 \&PD Ta 1 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 \&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 \& | |||
.It Sx \&UE Ta 0 Ta current Ta none Ta compat | |||
.It Sx \&UR Ta 1 Ta current Ta part Ta compat | |||
.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 mentions some areas of questionable portability between | ||
implementations of the | implementations of the | ||
.Nm | .Nm | ||
language. | language. | ||
More incompatibilities exist. | |||
.Pp | .Pp | ||
.Bl -dash -compact | .Bl -dash -compact | ||
.It | .It | ||
|
|
||
.Sx \&nf . | .Sx \&nf . | ||
This behaviour may not be portable. | This behaviour may not be portable. | ||
.It | .It | ||
In quoted literals, GNU troff allowed pair-wise double-quotes to produce | |||
a standalone double-quote in formatted output. | |||
It is not known whether this behaviour is exhibited by other formatters. | |||
.It | |||
troff suppresses a newline before | troff suppresses a newline before | ||
.Sq \(aq | .Sq \(aq | ||
macro output; in mandoc, it is an alias for the standard | macro output; in mandoc, it is an alias for the standard | ||
.Sq \&. | .Sq \&. | ||
control character. | control character. | ||
.It | .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 | |||
.Pp | |||
The | The | ||
.Sq \eh | .Sx EE , | ||
.Pq horizontal position , | .Sx EX , | ||
.Sq \ev | .Sx OP , | ||
.Pq vertical position , | .Sx UE , | ||
.Sq \em | |||
.Pq text colour , | |||
.Sq \eM | |||
.Pq text filling colour , | |||
.Sq \ez | |||
.Pq zero-length character , | |||
.Sq \ew | |||
.Pq string length , | |||
.Sq \ek | |||
.Pq horizontal position marker , | |||
.Sq \eo | |||
.Pq text overstrike , | |||
and | and | ||
.Sq \es | .Sx UR | ||
.Pq text size | macros are part of the GNU extended | ||
escape sequences are all discarded in mandoc. | .Nm | ||
.It | macro set, and may not be portable to non-GNU troff implementations. | ||
The | |||
.Sq \ef | |||
scaling unit is accepted by mandoc, but rendered as the default unit. | |||
.It | |||
The | |||
.Sx \&sp | |||
macro does not accept negative values in mandoc. | |||
In GNU troff, this would result in strange behaviour. | |||
.El | |||
.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 , | .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . | ||
.Mt kristaps@bsd.lv . | |||
.Sh CAVEATS | .Sh CAVEATS | ||
Do not use this language. | Do not use this language. | ||
Use | Use |