version 1.12, 2010/07/04 22:04:04 |
version 1.45, 2013/12/15 21:23:52 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010, 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 roff |
.Nm roff |
.Nd roff language reference |
.Nd roff language reference for mandoc |
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm roff |
.Nm roff |
language is a general-purpose text-formatting language. The purpose of |
language is a general purpose text formatting language. |
this document is to consistently describe those language constructs |
Since traditional implementations of the |
accepted by the |
.Xr mdoc 7 |
|
and |
|
.Xr man 7 |
|
manual formatting languages are based on it, |
|
many real-world manuals use small numbers of |
|
.Nm |
|
requests intermixed with their |
|
.Xr mdoc 7 |
|
or |
|
.Xr man 7 |
|
code. |
|
To properly format such manuals, the |
.Xr mandoc 1 |
.Xr mandoc 1 |
utility. It is a work in progress. |
utility supports a tiny subset of |
.Pp |
|
An |
|
.Nm |
.Nm |
document follows simple rules: lines beginning with the control |
requests. |
characters |
Only these requests supported by |
.Sq \. |
.Xr mandoc 1 |
|
are documented in the present manual, |
|
together with the basic language syntax shared by |
|
.Nm , |
|
.Xr mdoc 7 , |
|
and |
|
.Xr man 7 . |
|
For complete |
|
.Nm |
|
manuals, consult the |
|
.Sx SEE ALSO |
|
section. |
|
.Pp |
|
Input lines beginning with the control character |
|
.Sq \&. |
|
are parsed for requests and macros. |
|
Such lines are called |
|
.Dq request lines |
or |
or |
.Sq \(aq |
.Dq macro lines , |
are parsed for macros. Other lines are interpreted within the scope of |
respectively. |
prior macros: |
Requests change the processing state and manipulate the formatting; |
.Bd -literal -offset indent |
some macros also define the document structure and produce formatted |
\&.xx Macro lines change control state. |
output. |
Other lines are interpreted within the current state. |
The single quote |
.Ed |
.Pq Qq \(aq |
|
is accepted as an alternative control character, |
|
treated by |
|
.Xr mandoc 1 |
|
just like |
|
.Ql \&. |
|
.Pp |
|
Lines not beginning with control characters are called |
|
.Dq text lines . |
|
They provide free-form text to be printed; the formatting of the text |
|
depends on the respective processing context. |
.Sh LANGUAGE SYNTAX |
.Sh LANGUAGE SYNTAX |
.Nm |
.Nm |
documents may contain only graphable 7-bit ASCII characters, the space |
documents may contain only graphable 7-bit ASCII characters, the space |
character, and, in certain circumstances, the tab character. All |
character, and, in certain circumstances, the tab character. |
manuals must have |
The backslash character |
.Ux |
.Sq \e |
line terminators. |
indicates the start of an escape sequence for |
.Sh MACRO SYNTAX |
.Sx Comments , |
Macros are arbitrary in length and begin with a control character , |
.Sx Special Characters , |
.Sq \. |
.Sx Predefined Strings , |
|
and |
|
user-defined strings defined using the |
|
.Sx ds |
|
request. |
|
.Ss Comments |
|
Text following an escaped double-quote |
|
.Sq \e\(dq , |
|
whether in a request, macro, or text line, is ignored to the end of the line. |
|
A request line beginning with a control character and comment escape |
|
.Sq \&.\e\(dq |
|
is also ignored. |
|
Furthermore, request lines with only a control character and optional |
|
trailing whitespace are stripped from input. |
|
.Pp |
|
Examples: |
|
.Bd -literal -offset indent -compact |
|
\&.\e\(dq This is a comment line. |
|
\&.\e\(dq The next line is ignored: |
|
\&. |
|
\&.Sh EXAMPLES \e\(dq This is a comment, too. |
|
\&example text \e\(dq And so is this. |
|
.Ed |
|
.Ss Special Characters |
|
Special characters are used to encode special glyphs and are rendered |
|
differently across output media. |
|
They may occur in request, 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. |
|
The indicator or numerical representative may be preceded by C |
|
(constant-width), which is ignored. |
|
.Pp |
|
The two-character indicator |
|
.Sq BI |
|
requests a font that is both bold and italic. |
|
It may not be portable to old roff implementations. |
|
.Pp |
|
Examples: |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It Li \efBbold\efR |
|
Write in \fBbold\fP, then switch to regular font mode. |
|
.It Li \efIitalic\efP |
|
Write in \fIitalic\fP, then return to previous font mode. |
|
.It Li \ef(BIbold italic\efP |
|
Write in \f(BIbold italic\fP, then return to previous font mode. |
|
.El |
|
.Pp |
|
Text decoration is |
|
.Em not |
|
recommended for |
|
.Xr mdoc 7 , |
|
which encourages semantic annotation. |
|
.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 |
|
Predefined strings are not recommended for use, |
|
as they differ across implementations. |
|
Those supported by |
|
.Xr mandoc 1 |
|
are listed in |
|
.Xr mandoc_char 7 . |
|
Manuals using these predefined strings are almost certainly not portable. |
|
.Ss Whitespace |
|
Whitespace consists of the space character. |
|
In text lines, whitespace is preserved within a line. |
|
In request and 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 |
|
Literal space characters can be produced in the output |
|
using escape sequences. |
|
In macro lines, they can also be included in arguments using quotation; see |
|
.Sx MACRO SYNTAX |
|
for details. |
|
.Pp |
|
Blank text lines, which may include whitespace, are only permitted |
|
within literal contexts. |
|
If the first character of a text line is a space, that line is printed |
|
with a leading newline. |
|
.Ss Scaling Widths |
|
Many requests and 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 followed 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 |
or |
.Sq \(aq , |
.Sq v |
at the beginning of the line. |
is necessarily non-portable across output media. |
An arbitrary amount of whitespace may sit between the control character |
See |
and the macro name. |
.Sx COMPATIBILITY . |
Thus, the following are equivalent: |
.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 ".Bl -tag -width 2i" -offset indent -compact |
|
.It Li \&.Bl -tag -width 2i |
|
two-inch tagged list indentation in |
|
.Xr mdoc 7 |
|
.It Li \&.HP 2i |
|
two-inch tagged list indentation in |
|
.Xr man 7 |
|
.It Li \&.sp 2v |
|
two vertical spaces |
|
.El |
|
.Ss Sentence Spacing |
|
Each sentence 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 |
|
The proper spacing is also intelligently preserved if a sentence ends at |
|
the boundary of a macro line. |
|
.Pp |
|
Examples: |
|
.Bd -literal -offset indent -compact |
|
Do not end sentences mid-line like this. Instead, |
|
end a sentence like this. |
|
A macro would end like this: |
|
\&.Xr mandoc 1 \&. |
|
.Ed |
|
.Sh REQUEST SYNTAX |
|
A request or macro line consists of: |
|
.Pp |
|
.Bl -enum -compact |
|
.It |
|
the control character |
|
.Sq \&. |
|
or |
|
.Sq \(aq |
|
at the beginning of the line, |
|
.It |
|
optionally an arbitrary amount of whitespace, |
|
.It |
|
the name of the request or the macro, which is one word of arbitrary |
|
length, terminated by whitespace, |
|
.It |
|
and zero or more arguments delimited by whitespace. |
|
.El |
|
.Pp |
|
Thus, the following request lines are all equivalent: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.if |
\&.ig end |
\&.\ \ \ \&if |
\&.ig end |
|
\&. ig end |
.Ed |
.Ed |
.Sh REFERENCE |
.Sh MACRO SYNTAX |
This section is a canonical reference of all macros, arranged |
Macros are provided by the |
alphabetically. |
.Xr mdoc 7 |
|
and |
|
.Xr man 7 |
|
languages and can be defined by the |
|
.Sx \&de |
|
request. |
|
When called, they follow the same syntax as requests, except that |
|
macro arguments may optionally be quoted by enclosing them |
|
in double quote characters |
|
.Pq Sq \(dq . |
|
Quoted text, even if it contains whitespace or would cause |
|
a macro invocation when unquoted, is always considered literal text. |
|
Inside quoted text, pairs of double quote characters |
|
.Pq Sq Qq |
|
resolve to single double quote characters. |
|
.Pp |
|
To be recognised as the beginning of a quoted argument, the opening |
|
quote character must be preceded by a space character. |
|
A quoted argument extends to the next double quote character that is not |
|
part of a pair, or to the end of the input line, whichever comes earlier. |
|
Leaving out the terminating double quote character at the end of the line |
|
is discouraged. |
|
For clarity, if more arguments follow on the same input line, |
|
it is recommended to follow the terminating double quote character |
|
by a space character; in case the next character after the terminating |
|
double quote character is anything else, it is regarded as the beginning |
|
of the next, unquoted argument. |
|
.Pp |
|
Both in quoted and unquoted arguments, pairs of backslashes |
|
.Pq Sq \e\e |
|
resolve to single backslashes. |
|
In unquoted arguments, space characters can alternatively be included |
|
by preceding them with a backslash |
|
.Pq Sq \e\~ , |
|
but quoting is usually better for clarity. |
|
.Pp |
|
Examples: |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It Li .Fn strlen \(dqconst char *s\(dq |
|
Group arguments |
|
.Qq const char *s |
|
into one function argument. |
|
If unspecified, |
|
.Qq const , |
|
.Qq char , |
|
and |
|
.Qq *s |
|
would be considered separate arguments. |
|
.It Li .Op \(dqFl a\(dq |
|
Consider |
|
.Qq \&Fl a |
|
as literal text instead of a flag macro. |
|
.El |
|
.Sh REQUEST REFERENCE |
|
The |
|
.Xr mandoc 1 |
|
.Nm |
|
parser recognises the following requests. |
|
Note that the |
|
.Nm |
|
language defines many more requests not implemented in |
|
.Xr mandoc 1 . |
|
.Ss \&ad |
|
Set line adjustment mode. |
|
This line-scoped request is intended to have one argument to select |
|
normal, left, right, or centre adjustment for subsequent text. |
|
Currently, it is ignored including its arguments, |
|
and the number of arguments is not checked. |
.Ss \&am |
.Ss \&am |
The syntax of this macro is the same as that of |
Append to a macro definition. |
.Sx \&ig , |
The syntax of this request is the same as that of |
except that a leading argument must be specified. |
.Sx \&de . |
It is ignored, as are its children. |
It is currently ignored by |
|
.Xr mandoc 1 , |
|
as are its children. |
.Ss \&ami |
.Ss \&ami |
The syntax of this macro is the same as that of |
Append to a macro definition, specifying the macro name indirectly. |
.Sx \&ig , |
The syntax of this request is the same as that of |
except that a leading argument must be specified. |
.Sx \&dei . |
It is ignored, as are its children. |
It is currently ignored by |
|
.Xr mandoc 1 , |
|
as are its children. |
.Ss \&am1 |
.Ss \&am1 |
The syntax of this macro is the same as that of |
Append to a macro definition, switching roff compatibility mode off |
.Sx \&ig , |
during macro execution. |
except that a leading argument must be specified. |
The syntax of this request is the same as that of |
It is ignored, as are its children. |
.Sx \&de1 . |
|
It is currently ignored by |
|
.Xr mandoc 1 , |
|
as are its children. |
|
.Ss \&cc |
|
Changes the control character. |
|
Its syntax is as follows: |
|
.Bd -literal -offset indent |
|
.Pf . Cm \&cc Op Ar c |
|
.Ed |
|
.Pp |
|
If |
|
.Ar c |
|
is not specified, the control character is reset to |
|
.Sq \&. . |
|
Trailing characters are ignored. |
.Ss \&de |
.Ss \&de |
The syntax of this macro is the same as that of |
Define a |
.Sx \&ig , |
.Nm |
except that a leading argument must be specified. |
macro. |
It is ignored, as are its children. |
Its syntax can be either |
|
.Bd -literal -offset indent |
|
.Pf . Cm \&de Ar name |
|
.Ar macro definition |
|
\&.. |
|
.Ed |
|
.Pp |
|
or |
|
.Bd -literal -offset indent |
|
.Pf . Cm \&de Ar name Ar end |
|
.Ar macro definition |
|
.Pf . Ar end |
|
.Ed |
|
.Pp |
|
Both forms define or redefine the macro |
|
.Ar name |
|
to represent the |
|
.Ar macro definition , |
|
which may consist of one or more input lines, including the newline |
|
characters terminating each line, optionally containing calls to |
|
.Nm |
|
requests, |
|
.Nm |
|
macros or high-level macros like |
|
.Xr man 7 |
|
or |
|
.Xr mdoc 7 |
|
macros, whichever applies to the document in question. |
|
.Pp |
|
Specifying a custom |
|
.Ar end |
|
macro works in the same way as for |
|
.Sx \&ig ; |
|
namely, the call to |
|
.Sq Pf . Ar end |
|
first ends the |
|
.Ar macro definition , |
|
and after that, it is also evaluated as a |
|
.Nm |
|
request or |
|
.Nm |
|
macro, but not as a high-level macro. |
|
.Pp |
|
The macro can be invoked later using the syntax |
|
.Pp |
|
.D1 Pf . Ar name Op Ar argument Op Ar argument ... |
|
.Pp |
|
Regarding argument parsing, see |
|
.Sx MACRO SYNTAX |
|
above. |
|
.Pp |
|
The line invoking the macro will be replaced |
|
in the input stream by the |
|
.Ar macro definition , |
|
replacing all occurrences of |
|
.No \e\e$ Ns Ar N , |
|
where |
|
.Ar N |
|
is a digit, by the |
|
.Ar N Ns th Ar argument . |
|
For example, |
|
.Bd -literal -offset indent |
|
\&.de ZN |
|
\efI\e^\e\e$1\e^\efP\e\e$2 |
|
\&.. |
|
\&.ZN XtFree . |
|
.Ed |
|
.Pp |
|
produces |
|
.Pp |
|
.D1 \efI\e^XtFree\e^\efP. |
|
.Pp |
|
in the input stream, and thus in the output: \fI\^XtFree\^\fP. |
|
.Pp |
|
Since macros and user-defined strings share a common string table, |
|
defining a macro |
|
.Ar name |
|
clobbers the user-defined string |
|
.Ar name , |
|
and the |
|
.Ar macro definition |
|
can also be printed using the |
|
.Sq \e* |
|
string interpolation syntax described below |
|
.Sx ds , |
|
but this is rarely useful because every macro definition contains at least |
|
one explicit newline character. |
|
.Pp |
|
In order to prevent endless recursion, both groff and |
|
.Xr mandoc 1 |
|
limit the stack depth for expanding macros and strings |
|
to a large, but finite number. |
|
Do not rely on the exact value of this limit. |
.Ss \&dei |
.Ss \&dei |
The syntax of this macro is the same as that of |
Define a |
.Sx \&ig , |
.Nm |
except that a leading argument must be specified. |
macro, specifying the macro name indirectly. |
It is ignored, as are its children. |
The syntax of this request is the same as that of |
.Ss \&ds |
.Sx \&de . |
Define a string. |
It is currently ignored by |
This macro is intended to have two arguments, |
.Xr mandoc 1 , |
the name of the string to define and its content. |
as are its children. |
Currently, it is ignored including its arguments, |
|
and the number of arguments is not checked. |
|
.Ss \&de1 |
.Ss \&de1 |
The syntax of this macro is the same as that of |
Define a |
.Sx \&ig , |
.Nm |
except that a leading argument must be specified. |
macro that will be executed with |
It is ignored, as are its children. |
.Nm |
|
compatibility mode switched off during macro execution. |
|
This is a GNU extension not available in traditional |
|
.Nm |
|
implementations and not even in older versions of groff. |
|
Since |
|
.Xr mandoc 1 |
|
does not implement |
|
.Nm |
|
compatibility mode at all, it handles this request as an alias for |
|
.Sx \&de . |
|
.Ss \&ds |
|
Define a user-defined string. |
|
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string |
|
.Pp |
|
The |
|
.Ar name |
|
and |
|
.Ar string |
|
arguments are space-separated. |
|
If the |
|
.Ar string |
|
begins with a double-quote character, that character will not be part |
|
of the string. |
|
All remaining characters on the input line form the |
|
.Ar string , |
|
including whitespace and double-quote characters, even trailing ones. |
|
.Pp |
|
The |
|
.Ar string |
|
can be interpolated into subsequent text by using |
|
.No \e* Ns Bq Ar name |
|
for a |
|
.Ar name |
|
of arbitrary length, or \e*(NN or \e*N if the length of |
|
.Ar name |
|
is two or one characters, respectively. |
|
Interpolation can be prevented by escaping the leading backslash; |
|
that is, an asterisk preceded by an even number of backslashes |
|
does not trigger string interpolation. |
|
.Pp |
|
Since user-defined strings and macros share a common string table, |
|
defining a string |
|
.Ar name |
|
clobbers the macro |
|
.Ar name , |
|
and the |
|
.Ar name |
|
used for defining a string can also be invoked as a macro, |
|
in which case the following input line will be appended to the |
|
.Ar string , |
|
forming a new input line passed to the |
|
.Nm |
|
parser. |
|
For example, |
|
.Bd -literal -offset indent |
|
\&.ds badidea .S |
|
\&.badidea |
|
H SYNOPSIS |
|
.Ed |
|
.Pp |
|
invokes the |
|
.Cm SH |
|
macro when used in a |
|
.Xr man 7 |
|
document. |
|
Such abuse is of course strongly discouraged. |
.Ss \&el |
.Ss \&el |
The |
The |
.Qq else |
.Qq else |
Line 113 If no stack entries are present (e.g., due to no prior |
|
Line 626 If no stack entries are present (e.g., due to no prior |
|
.Sx \&ie |
.Sx \&ie |
calls) |
calls) |
then false is assumed. |
then false is assumed. |
The syntax of this macro is similar to |
The syntax of this request is similar to |
.Sx \&if |
.Sx \&if |
except that the conditional is missing. |
except that the conditional is missing. |
|
.Ss \&EN |
|
End an equation block. |
|
See |
|
.Sx \&EQ . |
|
.Ss \&EQ |
|
Begin an equation block. |
|
See |
|
.Xr eqn 7 |
|
for a description of the equation language. |
|
.Ss \&fam |
|
Change the font family. |
|
This line-scoped request is intended to have one argument specifying |
|
the font family to be selected. |
|
It is a groff extension, and currently, it is ignored including its |
|
arguments, and the number of arguments is not checked. |
|
.Ss \&hw |
|
Specify hyphenation points in words. |
|
This line-scoped request is currently ignored. |
|
.Ss \&hy |
|
Set automatic hyphenation mode. |
|
This line-scoped request is currently ignored. |
.Ss \&ie |
.Ss \&ie |
The |
The |
.Qq if |
.Qq if |
Line 131 Begins a conditional. |
|
Line 665 Begins a conditional. |
|
Right now, the conditional evaluates to true |
Right now, the conditional evaluates to true |
if and only if it starts with the letter |
if and only if it starts with the letter |
.Sy n , |
.Sy n , |
indicating processing in |
indicating processing in nroff style as opposed to troff style. |
.Xr nroff 1 |
|
style as opposed to |
|
.Xr troff 1 |
|
style. |
|
If a conditional is false, its children are not processed, but are |
If a conditional is false, its children are not processed, but are |
syntactically interpreted to preserve the integrity of the input |
syntactically interpreted to preserve the integrity of the input |
document. |
document. |
Thus, |
Thus, |
.Pp |
.Pp |
.D1 \&.if t \e .ig |
.D1 \&.if t .ig |
.Pp |
.Pp |
will discard the |
will discard the |
.Sq \&.ig , |
.Sq \&.ig , |
which may lead to interesting results, but |
which may lead to interesting results, but |
.Pp |
.Pp |
.D1 \&.if t \e .if t \e{\e |
.D1 \&.if t .if t \e{\e |
.Pp |
.Pp |
will continue to syntactically interpret to the block close of the final |
will continue to syntactically interpret to the block close of the final |
conditional. |
conditional. |
Sub-conditionals, in this case, obviously inherit the truth value of |
Sub-conditionals, in this case, obviously inherit the truth value of |
the parent. |
the parent. |
This macro has the following syntax: |
This request has the following syntax: |
.Pp |
.Bd -literal -offset indent |
.Bd -literal -offset indent -compact |
|
\&.if COND \e{\e |
\&.if COND \e{\e |
BODY... |
BODY... |
\&.\e} |
\&.\e} |
.Ed |
.Ed |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent |
\&.if COND \e{ BODY |
\&.if COND \e{ BODY |
BODY... \e} |
BODY... \e} |
.Ed |
.Ed |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent |
\&.if COND \e{ BODY |
\&.if COND \e{ BODY |
BODY... |
BODY... |
\&.\e} |
\&.\e} |
.Ed |
.Ed |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent |
\&.if COND \e |
\&.if COND \e |
BODY |
BODY |
.Ed |
.Ed |
Line 190 evaluate as false. |
|
Line 719 evaluate as false. |
|
.Pp |
.Pp |
If the BODY section is begun by an escaped brace |
If the BODY section is begun by an escaped brace |
.Sq \e{ , |
.Sq \e{ , |
scope continues until a closing-brace macro |
scope continues until a closing-brace escape sequence |
.Sq \.\e} . |
.Sq \.\e} . |
If the BODY is not enclosed in braces, scope continues until the next |
If the BODY is not enclosed in braces, scope continues until |
macro or word. |
the end of the line. |
If the COND is followed by a BODY on the same line, whether after a |
If the COND is followed by a BODY on the same line, whether after a |
brace or not, then macros |
brace or not, then requests and macros |
.Em must |
.Em must |
begin with a control character. |
begin with a control character. |
It is generally more intuitive, in this case, to write |
It is generally more intuitive, in this case, to write |
|
|
\&.\e} |
\&.\e} |
.Ed |
.Ed |
.Pp |
.Pp |
than having the macro follow as |
than having the request or macro follow as |
.Pp |
.Pp |
.D1 \&.if COND \e{ .foo |
.D1 \&.if COND \e{ .foo |
.Pp |
.Pp |
The scope of a conditional is always parsed, but only executed if the |
The scope of a conditional is always parsed, but only executed if the |
conditional evaluates to true. |
conditional evaluates to true. |
.Pp |
.Pp |
Note that text subsequent a |
Note that the |
.Sq \&.\e} |
|
macro is discarded. |
|
Furthermore, if an explicit closing sequence |
|
.Sq \e} |
.Sq \e} |
is specified in a free-form line, the entire line is accepted within the |
is converted into a zero-width escape sequence if not passed as a |
scope of the prior macro, not only the text preceding the close, with the |
standalone macro |
|
.Sq \&.\e} . |
|
For example, |
|
.Pp |
|
.D1 \&.Fl a \e} b |
|
.Pp |
|
will result in |
.Sq \e} |
.Sq \e} |
collapsing into a zero-width space. |
being considered an argument of the |
|
.Sq \&Fl |
|
macro. |
.Ss \&ig |
.Ss \&ig |
Ignore input. |
Ignore input. |
Accepts the following syntax: |
Its syntax can be either |
.Pp |
.Bd -literal -offset indent |
.Bd -literal -offset indent -compact |
.Pf . Cm \&ig |
\&.ig |
.Ar ignored text |
BODY... |
|
\&.. |
\&.. |
.Ed |
.Ed |
.Bd -literal -offset indent -compact |
.Pp |
\&.ig END |
or |
BODY... |
.Bd -literal -offset indent |
\&.END |
.Pf . Cm \&ig Ar end |
|
.Ar ignored text |
|
.Pf . Ar end |
.Ed |
.Ed |
.Pp |
.Pp |
In the first case, input is ignored until a |
In the first case, input is ignored until a |
.Sq \&.. |
.Sq \&.. |
macro is encountered on its own line. |
request is encountered on its own line. |
In the second case, input is ignored until a |
In the second case, input is ignored until the specified |
.Sq \&.END |
.Sq Pf . Ar end |
is encountered. |
macro is encountered. |
Text subsequent the |
Do not use the escape character |
.Sq \&.END |
|
or |
|
.Sq \&.. |
|
is discarded. |
|
.Pp |
|
Do not use the escape |
|
.Sq \e |
.Sq \e |
anywhere in the definition of END. |
anywhere in the definition of |
It causes very strange behaviour. |
.Ar end ; |
Furthermore, if you redefine a |
it would cause very strange behaviour. |
.Nm |
|
macro, such as |
|
.Pp |
.Pp |
|
When the |
|
.Ar end |
|
macro is a roff request or a roff macro, like in |
|
.Pp |
.D1 \&.ig if |
.D1 \&.ig if |
.Pp |
.Pp |
the subsequent invocation of |
the subsequent invocation of |
.Sx \&if |
.Sx \&if |
will first signify the end of comment, then be invoked as a macro. |
will first terminate the |
This behaviour really shouldn't be counted upon. |
.Ar ignored text , |
|
then be invoked as usual. |
|
Otherwise, it only terminates the |
|
.Ar ignored text , |
|
and arguments following it or the |
|
.Sq \&.. |
|
request are discarded. |
|
.Ss \&ne |
|
Declare the need for the specified minimum vertical space |
|
before the next trap or the bottom of the page. |
|
This line-scoped request is currently ignored. |
|
.Ss \&nh |
|
Turn off automatic hyphenation mode. |
|
This line-scoped request is currently ignored. |
.Ss \&rm |
.Ss \&rm |
Remove a request, macro or string. |
Remove a request, macro or string. |
This macro is intended to have one argument, |
This request is intended to have one argument, |
the name of the request, macro or string to be undefined. |
the name of the request, macro or string to be undefined. |
Currently, it is ignored including its arguments, |
Currently, it is ignored including its arguments, |
and the number of arguments is not checked. |
and the number of arguments is not checked. |
.Ss \&nr |
.Ss \&nr |
Define a register. |
Define or change a register. |
A register is an arbitrary string value that defines some sort of state, |
A register is an arbitrary string value that defines some sort of state, |
which influences parsing and/or formatting. |
which influences parsing and/or formatting. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&nr Cm name value |
.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar value |
.Pp |
.Pp |
The |
The |
.Cm value |
.Ar value |
may, at the moment, only be an integer. |
may, at the moment, only be an integer. |
The |
If it is prefixed by a sign, the register will be |
.Cm name |
incremented or decremented instead of assigned to. |
is defined up to the next whitespace. |
.Pp |
The following register |
The following register |
.Cm name |
.Ar name |
requests are recognised: |
is handled specially: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
.It Cm nS |
.It Cm nS |
If set to a positive integer value, certain |
If set to a positive integer value, certain |
.Xr mdoc 7 |
.Xr mdoc 7 |
macros will behave as if they were defined in the |
macros will behave in the same way as in the |
.Em SYNOPSIS |
.Em SYNOPSIS |
section. |
section. |
Otherwise, this behaviour is unset (even if called within the |
If set to 0, these macros will behave in the same way as outside the |
.Em SYNOPSIS |
.Em SYNOPSIS |
section itself). |
section, even when called within the |
Note that invoking a new |
.Em SYNOPSIS |
|
section itself. |
|
Note that starting a new |
.Xr mdoc 7 |
.Xr mdoc 7 |
section will unset this value. |
section with the |
|
.Cm \&Sh |
|
macro will reset this register. |
.El |
.El |
.Ss \&tr |
.Ss \&ns |
Output character translation. |
Turn on no-space mode. |
This macro is intended to have one argument, |
This line-scoped request is intended to take no arguments. |
consisting of an even number of characters. |
|
Currently, it is ignored including its arguments, |
Currently, it is ignored including its arguments, |
and the number of arguments is not checked. |
and the number of arguments is not checked. |
|
.Ss \&ps |
|
Change point size. |
|
This line-scoped request is intended to take one numerical argument. |
|
Currently, it is ignored including its arguments, |
|
and the number of arguments is not checked. |
|
.Ss \&so |
|
Include a source file. |
|
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf \. Cm \&so Ar file |
|
.Pp |
|
The |
|
.Ar file |
|
will be read and its contents processed as input in place of the |
|
.Sq \&.so |
|
request line. |
|
To avoid inadvertent inclusion of unrelated files, |
|
.Xr mandoc 1 |
|
only accepts relative paths not containing the strings |
|
.Qq ../ |
|
and |
|
.Qq /.. . |
|
.Pp |
|
This request requires |
|
.Xr man 1 |
|
to change to the right directory before calling |
|
.Xr mandoc 1 , |
|
per convention to the root of the manual tree. |
|
Typical usage looks like: |
|
.Pp |
|
.Dl \&.so man3/Xcursor.3 |
|
.Pp |
|
As the whole concept is rather fragile, the use of |
|
.Sx \&so |
|
is discouraged. |
|
Use |
|
.Xr ln 1 |
|
instead. |
|
.Ss \&ta |
|
Set tab stops. |
|
This line-scoped request can take an arbitrary number of arguments. |
|
Currently, it is ignored including its arguments. |
|
.Ss \&tr |
|
Output character translation. |
|
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf \. Cm \&tr Ar [ab]+ |
|
.Pp |
|
Pairs of |
|
.Ar ab |
|
characters are replaced |
|
.Ar ( a |
|
for |
|
.Ar b ) . |
|
Replacement (or origin) characters may also be character escapes; thus, |
|
.Pp |
|
.Dl tr \e(xx\e(yy |
|
.Pp |
|
replaces all invocations of \e(xx with \e(yy. |
|
.Ss \&T& |
|
Re-start a table layout, retaining the options of the prior table |
|
invocation. |
|
See |
|
.Sx \&TS . |
|
.Ss \&TE |
|
End a table context. |
|
See |
|
.Sx \&TS . |
|
.Ss \&TS |
|
Begin a table, which formats input in aligned rows and columns. |
|
See |
|
.Xr tbl 7 |
|
for a description of the tbl language. |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section documents compatibility between mandoc and other other |
This section documents compatibility between mandoc and other |
troff implementations, at this time limited to GNU troff |
.Nm |
|
implementations, at this time limited to GNU troff |
.Pq Qq groff . |
.Pq Qq groff . |
The term |
The term |
.Qq historic groff |
.Qq historic groff |
refers to groff versions before the |
refers to groff version 1.15. |
.Pa doc.tmac |
|
file re-write |
|
.Pq somewhere between 1.15 and 1.19 . |
|
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
|
In mandoc, the |
|
.Sx \&EQ , |
|
.Sx \&TE , |
|
.Sx \&TS , |
|
and |
|
.Sx \&T& , |
|
macros are considered regular macros. |
|
In all other |
|
.Nm |
|
implementations, these are special macros that must be specified without |
|
spacing between the control character (which must be a period) and the |
|
macro name. |
|
.It |
The |
The |
.Cm nS |
.Cm nS |
request to |
register is only compatible with OpenBSD's groff-1.15. |
.Sx \&nr |
|
is only compatible with OpenBSD's groff. |
|
.It |
.It |
Historic groff did not accept white-space buffering the custom END tag |
Historic groff did not accept white-space before a custom |
for the |
.Ar end |
|
macro for the |
.Sx \&ig |
.Sx \&ig |
macro. |
request. |
.It |
.It |
The |
The |
.Sx \&if |
.Sx \&if |
and family would print funny white-spaces with historic groff when |
and family would print funny white-spaces with historic groff when |
depending on next-line syntax. |
using the next-line syntax. |
.El |
.El |
|
.Sh SEE ALSO |
|
.Xr mandoc 1 , |
|
.Xr eqn 7 , |
|
.Xr man 7 , |
|
.Xr mandoc_char 7 , |
|
.Xr mdoc 7 , |
|
.Xr tbl 7 |
|
.Rs |
|
.%A Joseph F. Ossanna |
|
.%A Brian W. Kernighan |
|
.%I AT&T Bell Laboratories |
|
.%T Troff User's Manual |
|
.%R Computing Science Technical Report |
|
.%N 54 |
|
.%C Murray Hill, New Jersey |
|
.%D 1976 and 1992 |
|
.%U http://www.kohala.com/start/troff/cstr54.ps |
|
.Re |
|
.Rs |
|
.%A Joseph F. Ossanna |
|
.%A Brian W. Kernighan |
|
.%A Gunnar Ritter |
|
.%T Heirloom Documentation Tools Nroff/Troff User's Manual |
|
.%D September 17, 2007 |
|
.%U http://heirloom.sourceforge.net/doctools/troff.pdf |
|
.Re |
|
.Sh HISTORY |
|
The RUNOFF typesetting system, whose input forms the basis for |
|
.Nm , |
|
was written in MAD and FAP for the CTSS operating system by Jerome E. |
|
Saltzer in 1964. |
|
Doug McIlroy rewrote it in BCPL in 1969, renaming it |
|
.Nm . |
|
Dennis M. Ritchie rewrote McIlroy's |
|
.Nm |
|
in PDP-11 assembly for |
|
.At v1 , |
|
Joseph F. Ossanna improved roff and renamed it nroff |
|
for |
|
.At v2 , |
|
then ported nroff to C as troff, which Brian W. Kernighan released with |
|
.At v7 . |
|
In 1989, James Clarke re-implemented troff in C++, naming it groff. |
.Sh AUTHORS |
.Sh AUTHORS |
The |
.An -nosplit |
|
This |
.Nm |
.Nm |
reference was written by |
reference was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
|
and |
|
.An Ingo Schwarze Aq Mt schwarze@openbsd.org . |