version 1.24, 2011/01/24 23:17:19 |
version 1.50, 2014/03/30 19:47:48 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010, 2011, 2013, 2014 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 |
|
|
The |
The |
.Nm roff |
.Nm roff |
language is a general purpose text formatting language. |
language is a general purpose text formatting language. |
In particular, it serves as the basis for the |
Since traditional implementations of the |
.Xr mdoc 7 |
.Xr mdoc 7 |
and |
and |
.Xr man 7 |
.Xr man 7 |
manual formatting macro languages. |
manual formatting languages are based on it, |
This manual describes the subset of the |
many real-world manuals use small numbers of |
.Nm |
.Nm |
language accepted by the |
requests and escape sequences intermixed with their |
|
.Xr mdoc 7 |
|
or |
|
.Xr man 7 |
|
code. |
|
To properly format such manuals, the |
.Xr mandoc 1 |
.Xr mandoc 1 |
utility. |
utility supports a tiny subset of |
|
.Nm |
|
requests and escapes. |
|
Only these requests and escapes supported by |
|
.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 |
.Pp |
Input lines beginning with the control characters |
Input lines beginning with the control character |
.Sq \&. |
.Sq \&. |
or |
|
.Sq \(aq |
|
are parsed for requests and macros. |
are parsed for requests and macros. |
These define the document structure, change the processing state |
Such lines are called |
and manipulate the formatting. |
.Dq request lines |
Some requests and macros also produce formatted output, |
or |
while others do not. |
.Dq macro lines , |
|
respectively. |
|
Requests change the processing state and manipulate the formatting; |
|
some macros also define the document structure and produce formatted |
|
output. |
|
The single quote |
|
.Pq Qq \(aq |
|
is accepted as an alternative control character, |
|
treated by |
|
.Xr mandoc 1 |
|
just like |
|
.Ql \&. |
.Pp |
.Pp |
All other input lines provide free-form text to be printed; |
Lines not beginning with control characters are called |
the formatting of free-form text depends on the respective |
.Dq text lines . |
processing context. |
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. |
character, and, in certain circumstances, the tab character. |
To produce other characters in the output, use the escape sequences |
The backslash character |
documented in the |
.Sq \e |
|
indicates the start of an escape sequence, used for example for |
|
.Sx Comments , |
|
.Sx Special Characters , |
|
.Sx Predefined Strings , |
|
and |
|
user-defined strings defined using the |
|
.Sx ds |
|
request. |
|
For a listing of escape sequences, consult the |
|
.Sx ESCAPE SEQUENCE REFERENCE |
|
below. |
|
.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 |
.Xr mandoc_char 7 |
manual. |
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 |
.Pp |
All manuals must have |
The two-character indicator |
.Ux |
.Sq BI |
line terminators. |
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 |
|
.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 ".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 |
.Sh REQUEST SYNTAX |
A request or macro line consists of: |
A request or macro line consists of: |
.Pp |
.Pp |
Line 87 Thus, the following request lines are all equivalent: |
|
Line 336 Thus, the following request lines are all equivalent: |
|
\&. ig end |
\&. ig end |
.Ed |
.Ed |
.Sh MACRO SYNTAX |
.Sh MACRO SYNTAX |
Macros can be defined by the |
Macros are provided by the |
|
.Xr mdoc 7 |
|
and |
|
.Xr man 7 |
|
languages and can be defined by the |
.Sx \&de |
.Sx \&de |
request. |
request. |
When called, they follow the same syntax as requests, except that |
When called, they follow the same syntax as requests, except that |
macro arguments may optionally be quoted by enclosing them |
macro arguments may optionally be quoted by enclosing them |
in double quote characters |
in double quote characters |
.Pq Sq \(dq . |
.Pq Sq \(dq . |
To be recognized as the beginning of a quoted argument, the opening |
Quoted text, even if it contains whitespace or would cause |
quote character must be preceded by a space character. |
a macro invocation when unquoted, is always considered literal text. |
.Pp |
Inside quoted text, pairs of double quote characters |
A quoted argument may contain whitespace, and pairs of double quote |
|
characters |
|
.Pq Sq Qq |
.Pq Sq Qq |
resolve to single double quote characters. |
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 |
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. |
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 |
Leaving out the terminating double quote character at the end of the line |
Line 118 In unquoted arguments, space characters can alternativ |
|
Line 372 In unquoted arguments, space characters can alternativ |
|
by preceding them with a backslash |
by preceding them with a backslash |
.Pq Sq \e\~ , |
.Pq Sq \e\~ , |
but quoting is usually better for clarity. |
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 |
.Sh REQUEST REFERENCE |
The |
The |
.Xr mandoc 1 |
.Xr mandoc 1 |
.Nm |
.Nm |
parser recognizes the following requests. |
parser recognises the following requests. |
Note that the |
Note that the |
.Nm |
.Nm |
language defines many more requests not implemented in |
language defines many more requests not implemented in |
Line 130 language defines many more requests not implemented in |
|
Line 402 language defines many more requests not implemented in |
|
.Ss \&ad |
.Ss \&ad |
Set line adjustment mode. |
Set line adjustment mode. |
This line-scoped request is intended to have one argument to select |
This line-scoped request is intended to have one argument to select |
normal, left, right, or center adjustment for subsequent text. |
normal, left, right, or centre adjustment for subsequent text. |
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 \&am |
.Ss \&am |
Line 155 The syntax of this request is the same as that of |
|
Line 427 The syntax of this request is the same as that of |
|
It is currently ignored by |
It is currently ignored by |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
as are its children. |
as are its children. |
|
.Ss \&as |
|
Append to a user-defined string. |
|
The syntax of this request is the same as that of |
|
.Sx \&ds . |
|
If a user-defined string with the specified name does not yet exist, |
|
it is set to the empty string before appending. |
|
.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 \&ce |
|
Center some lines. |
|
This line-scoped request is intended to take one integer argument, |
|
specifying how many lines to center. |
|
Currently, it is ignored including its arguments, and the number |
|
of arguments is not checked. |
.Ss \&de |
.Ss \&de |
Define a |
Define a |
.Nm |
.Nm |
Line 348 then false is assumed. |
|
Line 644 then false is assumed. |
|
The syntax of this request 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 \&ft |
|
Change the font. |
|
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf . Cm \&ft Op Ar font |
|
.Pp |
|
The following |
|
.Ar font |
|
arguments are supported: |
|
.Bl -tag -width 4n -offset indent |
|
.It Cm B , BI , 3 , 4 |
|
switches to |
|
.Sy bold |
|
font |
|
.It Cm I , 2 |
|
switches to |
|
.Em underlined |
|
font |
|
.It Cm R , CW , 1 |
|
switches to normal font |
|
.It Cm P No "or no argument" |
|
switches back to the previous font |
|
.El |
|
.Pp |
|
This request takes effect only locally, may be overridden by macros |
|
and escape sequences, and is only supported in |
|
.Xr man 7 |
|
for now. |
|
.Ss \&hw |
|
Specify hyphenation points in words. |
|
This line-scoped request is currently ignored. |
.Ss \&hy |
.Ss \&hy |
Set automatic hyphenation mode. |
Set automatic hyphenation mode. |
This line-scoped request is currently ignored. |
This line-scoped request is currently ignored. |
Line 363 Its syntax is equivalent to |
|
Line 705 Its syntax is equivalent to |
|
.Sx \&if . |
.Sx \&if . |
.Ss \&if |
.Ss \&if |
Begins a conditional. |
Begins a conditional. |
Right now, the conditional evaluates to true |
This request has the following syntax: |
if and only if it starts with the letter |
.Bd -literal -offset indent |
.Sy n , |
\&.if COND BODY |
indicating processing in nroff style as opposed to troff style. |
.Ed |
|
.Bd -literal -offset indent |
|
\&.if COND \e{BODY |
|
BODY...\e} |
|
.Ed |
|
.Bd -literal -offset indent |
|
\&.if COND \e{\e |
|
BODY... |
|
\&.\e} |
|
.Ed |
|
.Pp |
|
COND is a conditional statement. |
|
Currently, |
|
.Xr mandoc 1 |
|
supports the following subset of roff conditionals: |
|
.Bl -bullet |
|
.It |
|
If |
|
.Sq \&! |
|
is prefixed to COND, the condition is logically inverted. |
|
.It |
|
If the first character of COND is |
|
.Sq n |
|
.Pq nroff mode |
|
or |
|
.Sq o |
|
.Pq odd page , |
|
COND evaluates to true. |
|
.It |
|
If the first character of COND is |
|
.Sq c |
|
.Pq character available , |
|
.Sq d |
|
.Pq string defined , |
|
.Sq e |
|
.Pq even page , |
|
.Sq r |
|
.Pq register accessed , |
|
or |
|
.Sq t |
|
.Pq troff mode , |
|
COND evaluates to false. |
|
.It |
|
If COND starts with a digit, optionally prefixed by a minus sign, |
|
it is evaluated as a numerical expression of the form |
|
.Ar number operator number , |
|
where |
|
.Ar operator |
|
is one of |
|
.Sq < , |
|
.Sq <= , |
|
.Sq = , |
|
.Sq >= , |
|
or |
|
.Sq > . |
|
.It |
|
Otherwise, the first character of COND is regarded as a delimiter |
|
and COND evaluates to true if the string extending from its first |
|
to its second occurrence is equal to the string extending from its |
|
second to its third occurrence. |
|
.It |
|
If COND cannot be parsed, it evaluates to false. |
|
.El |
|
.Pp |
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. |
Line 384 will continue to syntactically interpret to the block |
|
Line 789 will continue to syntactically interpret to the block |
|
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 request has the following syntax: |
|
.Bd -literal -offset indent |
|
\&.if COND \e{\e |
|
BODY... |
|
\&.\e} |
|
.Ed |
|
.Bd -literal -offset indent |
|
\&.if COND \e{ BODY |
|
BODY... \e} |
|
.Ed |
|
.Bd -literal -offset indent |
|
\&.if COND \e{ BODY |
|
BODY... |
|
\&.\e} |
|
.Ed |
|
.Bd -literal -offset indent |
|
\&.if COND \e |
|
BODY |
|
.Ed |
|
.Pp |
.Pp |
COND is a conditional statement. |
|
roff allows for complicated conditionals; mandoc is much simpler. |
|
At this time, mandoc supports only |
|
.Sq n , |
|
evaluating to true; |
|
and |
|
.Sq t , |
|
.Sq e , |
|
and |
|
.Sq o , |
|
evaluating to false. |
|
All other invocations are read up to the next end of line or space and |
|
evaluate as false. |
|
.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 escape sequence |
scope continues until the end of the input line containing the |
.Sq \.\e} . |
matching closing-brace escape sequence |
|
.Sq \e} . |
If the BODY is not enclosed in braces, scope continues until |
If the BODY is not enclosed in braces, scope continues until |
the end of the line. |
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 |
Line 443 than having the request or macro follow as |
|
Line 816 than having the request or macro follow as |
|
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 following an |
Note that the |
.Sq \&.\e} |
|
escape sequence 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 request, 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. |
Its syntax can be either |
Its syntax can be either |
Line 496 Otherwise, it only terminates the |
|
Line 874 Otherwise, it only terminates the |
|
and arguments following it or the |
and arguments following it or the |
.Sq \&.. |
.Sq \&.. |
request are discarded. |
request are discarded. |
|
.Ss \&ll |
|
Change the output line length. |
|
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf . Cm \&ll Op Ar width |
|
.Pp |
|
If the |
|
.Ar width |
|
argument is omitted, the line length is reset to its previous value. |
|
The default setting for terminal output is 78n. |
|
Using this request in new manuals is discouraged for several reasons, |
|
among others because it overrides the |
|
.Xr mandoc 1 |
|
.Fl O Cm width |
|
command line option. |
.Ss \&ne |
.Ss \&ne |
Declare the need for the specified minimum vertical space |
Declare the need for the specified minimum vertical space |
before the next trap or the bottom of the page. |
before the next trap or the bottom of the page. |
Line 510 the name of the request, macro or string to be undefin |
|
Line 903 the name of the request, macro or string to be undefin |
|
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 \. Cm \&nr Ar name Ar value |
.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar value |
.Pp |
.Pp |
The |
The |
.Ar value |
.Ar value |
may, at the moment, only be an integer. |
may, at the moment, only be an integer. |
So far, only the following register |
If it is prefixed by a sign, the register will be |
|
incremented or decremented instead of assigned to. |
|
.Pp |
|
The following register |
.Ar name |
.Ar name |
is 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 |
Line 541 section with the |
|
Line 937 section with the |
|
.Cm \&Sh |
.Cm \&Sh |
macro will reset this register. |
macro will reset this register. |
.El |
.El |
|
.Ss \&ns |
|
Turn on no-space mode. |
|
This line-scoped request is intended to take no arguments. |
|
Currently, it is ignored including its arguments, |
|
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 |
.Ss \&so |
Include a source file. |
Include a source file. |
Its syntax is as follows: |
Its syntax is as follows: |
|
|
will be read and its contents processed as input in place of the |
will be read and its contents processed as input in place of the |
.Sq \&.so |
.Sq \&.so |
request line. |
request line. |
To avoid inadvertant inclusion of unrelated files, |
To avoid inadvertent inclusion of unrelated files, |
.Xr mandoc 1 |
.Xr mandoc 1 |
only accepts relative paths not containing the strings |
only accepts relative paths not containing the strings |
.Qq ../ |
.Qq ../ |
and |
and |
.Qq /.. . |
.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 |
.Ss \&tr |
Output character translation. |
Output character translation. |
This request is intended to have one argument, |
Its syntax is as follows: |
consisting of an even number of characters. |
.Pp |
Currently, it is ignored including its arguments, |
.D1 Pf \. Cm \&tr Ar [ab]+ |
and the number of arguments is not checked. |
.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& |
.Ss \&T& |
Re-start a table layout, retaining the options of the prior table |
Re-start a table layout, retaining the options of the prior table |
invocation. |
invocation. |
Line 578 Begin a table, which formats input in aligned rows and |
|
Line 1015 Begin a table, which formats input in aligned rows and |
|
See |
See |
.Xr tbl 7 |
.Xr tbl 7 |
for a description of the tbl language. |
for a description of the tbl language. |
|
.Sh ESCAPE SEQUENCE REFERENCE |
|
The |
|
.Xr mandoc 1 |
|
.Nm |
|
parser recognises the following escape sequences. |
|
Note that the |
|
.Nm |
|
language defines more escape sequences not implemented in |
|
.Xr mandoc 1 . |
|
In |
|
.Xr mdoc 7 |
|
and |
|
.Xr man 7 |
|
documents, using escape sequences is discouraged except for those |
|
described in the |
|
.Sx LANGUAGE SYNTAX |
|
section above. |
|
.Pp |
|
A backslash followed by any character not listed here |
|
simply prints that character itself. |
|
.Ss \e<newline> |
|
A backslash at the end of an input line can be used to continue the |
|
logical input line on the next physical input line, joining the text |
|
on both lines together as if it were on a single input line. |
|
.Ss \e<space> |
|
The escape sequence backslash-space |
|
.Pq Sq \e\ \& |
|
is an unpaddable space-sized non-breaking space character; see |
|
.Sx Whitespace . |
|
.Ss \e\(dq |
|
The rest of the input line is treated as |
|
.Sx Comments . |
|
.Ss \e% |
|
Hyphenation allowed at this point of the word; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \e& |
|
Non-printing zero-width character; see |
|
.Sx Whitespace . |
|
.Ss \e\(aq |
|
Acute accent special character; use |
|
.Sq \e(aa |
|
instead. |
|
.Ss \e( Ns Ar cc |
|
.Sx Special Characters |
|
with two-letter names, see |
|
.Xr mandoc_char 7 . |
|
.Ss \e*[ Ns Ar name ] |
|
Interpolate the string with the |
|
.Ar name ; |
|
see |
|
.Sx Predefined Strings |
|
and |
|
.Sx ds . |
|
For short names, there are variants |
|
.No \e* Ns Ar c |
|
and |
|
.No \e*( Ns Ar cc . |
|
.Ss \e- |
|
Special character |
|
.Dq mathematical minus sign . |
|
.Ss \e[ Ns Ar name ] |
|
.Sx Special Characters |
|
with names of arbitrary length, see |
|
.Xr mandoc_char 7 . |
|
.Ss \e^ |
|
One-twelfth em half-narrow space character, effectively zero-width in |
|
.Xr mandoc 1 . |
|
.Ss \e` |
|
Grave accent special character; use |
|
.Sq \e(ga |
|
instead. |
|
.Ss \e{ |
|
Begin conditional input; see |
|
.Sx if . |
|
.Ss \e\(ba |
|
One-sixth em narrow space character, effectively zero-width in |
|
.Xr mandoc 1 . |
|
.Ss \e} |
|
End conditional input; see |
|
.Sx if . |
|
.Ss \e~ |
|
Paddable non-breaking space character. |
|
.Ss \e0 |
|
Digit width space character. |
|
.Ss \eA\(aq Ns Ar string Ns \(aq |
|
Anchor definition; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eB\(aq Ns Ar string Ns \(aq |
|
Test whether |
|
.Ar string |
|
is a numerical expession; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eb\(aq Ns Ar string Ns \(aq |
|
Bracket building function; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eC\(aq Ns Ar name Ns \(aq |
|
.Sx Special Characters |
|
with names of arbitrary length. |
|
.Ss \ec |
|
Interrupt text processing to insert requests or macros; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eD\(aq Ns Ar string Ns \(aq |
|
Draw graphics function; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \ed |
|
Move down by half a line; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \ee |
|
Backslash special character. |
|
.Ss \eF[ Ns Ar name ] |
|
Switch font family (groff extension); ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \eF Ns Ar c |
|
and |
|
.No \eF( Ns Ar cc . |
|
.Ss \ef[ Ns Ar name ] |
|
Switch to the font |
|
.Ar name , |
|
see |
|
.Sx Text Decoration . |
|
For short names, there are variants |
|
.No \ef Ns Ar c |
|
and |
|
.No \ef( Ns Ar cc . |
|
.Ss \eg[ Ns Ar name ] |
|
Interpolate the format of a number register; ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \eg Ns Ar c |
|
and |
|
.No \eg( Ns Ar cc . |
|
.Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq |
|
Set the height of the current font; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eh\(aq Ns Ar number Ns \(aq |
|
Horizontal motion; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \ek[ Ns Ar name ] |
|
Mark horizontal input place in register; ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \ek Ns Ar c |
|
and |
|
.No \ek( Ns Ar cc . |
|
.Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq |
|
Vertical line drawing function; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq |
|
Horizontal line drawing function; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eM[ Ns Ar name ] |
|
Set fill (background) color (groff extension); ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \eM Ns Ar c |
|
and |
|
.No \eM( Ns Ar cc . |
|
.Ss \em[ Ns Ar name ] |
|
Set glyph drawing color (groff extension); ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \em Ns Ar c |
|
and |
|
.No \em( Ns Ar cc . |
|
.Ss \eN\(aq Ns Ar number Ns \(aq |
|
Character |
|
.Ar number |
|
on the current font. |
|
.Ss \en[ Ns Ar name ] |
|
Interpolate the number register |
|
.Ar name . |
|
For short names, there are variants |
|
.No \en Ns Ar c |
|
and |
|
.No \en( Ns Ar cc . |
|
.Ss \eo\(aq Ns Ar string Ns \(aq |
|
Overstrike |
|
.Ar string ; |
|
ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq |
|
Set number register; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eS\(aq Ns Ar number Ns \(aq |
|
Slant output; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq |
|
Change point size; ignored by |
|
.Xr mandoc 1 . |
|
Alternative forms |
|
.No \es Ns Oo +|- Oc Ns Ar n , |
|
.No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq , |
|
.No \es Ns [ Oo +|- Oc Ns Ar number ] , |
|
and |
|
.No \es Ns Oo +|- Oc Ns [ Ar number Ns ] |
|
are also parsed and ignored. |
|
.Ss \et |
|
Horizontal tab; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eu |
|
Move up by half a line; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eV[ Ns Ar name ] |
|
Interpolate an environment variable; ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \eV Ns Ar c |
|
and |
|
.No \eV( Ns Ar cc . |
|
.Ss \ev\(aq Ns Ar number Ns \(aq |
|
Vertical motion; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \ew\(aq Ns Ar string Ns \(aq |
|
Interpolate the width of the |
|
.Ar string ; |
|
ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eX\(aq Ns Ar string Ns \(aq |
|
Output |
|
.Ar string |
|
as device control function; ignored in nroff mode and by |
|
.Xr mandoc 1 . |
|
.Ss \ex\(aq Ns Ar number Ns \(aq |
|
Extra line space function; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eY[ Ns Ar name ] |
|
Output a string as a device control function; ignored in nroff mode and by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \eY Ns Ar c |
|
and |
|
.No \eY( Ns Ar cc . |
|
.Ss \eZ\(aq Ns Ar string Ns \(aq |
|
Print |
|
.Ar string |
|
with zero width and height; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \ez |
|
Output the next character without advancing the cursor position; |
|
approximated in |
|
.Xr mandoc 1 |
|
by simply skipping the next character. |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section documents compatibility between mandoc and other other |
This section documents compatibility between mandoc and other |
.Nm |
.Nm |
implementations, at this time limited to GNU troff |
implementations, at this time limited to GNU troff |
.Pq Qq groff . |
.Pq Qq groff . |
Line 589 refers to groff version 1.15. |
|
Line 1269 refers to groff version 1.15. |
|
.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 |
register is only compatible with OpenBSD's groff-1.15. |
register is only compatible with OpenBSD's groff-1.15. |
Line 606 using the next-line syntax. |
|
Line 1299 using the next-line syntax. |
|
.El |
.El |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
|
.Xr eqn 7 , |
.Xr man 7 , |
.Xr man 7 , |
.Xr mandoc_char 7 , |
.Xr mandoc_char 7 , |
.Xr mdoc 7 , |
.Xr mdoc 7 , |
Line 630 using the next-line syntax. |
|
Line 1324 using the next-line syntax. |
|
.%U http://heirloom.sourceforge.net/doctools/troff.pdf |
.%U http://heirloom.sourceforge.net/doctools/troff.pdf |
.Re |
.Re |
.Sh HISTORY |
.Sh HISTORY |
The RUNOFF typesetting system was written in PL/1 for the CTSS |
The RUNOFF typesetting system, whose input forms the basis for |
operating system by Jerome ("Jerry") E. Saltzer in 1961. |
|
It was first used as the main documentation tool by Multics since 1963. |
|
Robert ("Bob") H. Morris ported it to the GE-635 and called it |
|
.Nm , |
.Nm , |
Doug McIlroy rewrote it in BCPL in 1969, |
was written in MAD and FAP for the CTSS operating system by Jerome E. |
Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973, |
Saltzer in 1964. |
and Brian W. Kernighan rewrote it in C in 1975. |
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 |
.An -nosplit |
.An -nosplit |
This partial |
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 |
and |
.An Ingo Schwarze Aq schwarze@openbsd.org . |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org . |