version 1.30, 2011/07/28 14:17:11 |
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 |
|
|
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 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. |
|
Only these requests 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 for |
|
.Sx Comments , |
|
.Sx Special Characters , |
|
.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 |
.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 |
|
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 |
|
.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 83 Thus, the following request lines are all equivalent: |
|
Line 333 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 114 In unquoted arguments, space characters can alternativ |
|
Line 369 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 126 language defines many more requests not implemented in |
|
Line 399 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 151 The syntax of this request is the same as that of |
|
Line 424 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 \&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 |
Define a |
Define a |
.Nm |
.Nm |
Line 353 Begin an equation block. |
|
Line 638 Begin an equation block. |
|
See |
See |
.Xr eqn 7 |
.Xr eqn 7 |
for a description of the equation language. |
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 |
.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 520 the name of the request, macro or string to be undefin |
|
Line 814 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 578 only accepts relative paths not containing the strings |
|
Line 875 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 |
.Ss \&ta |
Set tab stops. |
Set tab stops. |
This line-scoped request can take an arbitrary number of arguments. |
This line-scoped request can take an arbitrary number of arguments. |
|
|
.Xr tbl 7 |
.Xr tbl 7 |
for a description of the tbl language. |
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 |
.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 679 using the next-line syntax. |
|
Line 992 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 . |