version 1.11, 2010/06/27 16:36:22 |
version 1.21, 2011/01/04 12:06:21 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv> |
|
.\" Copyright (c) 2010 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 |
In particular, it serves as the basis for the |
accepted by the |
.Xr mdoc 7 |
|
and |
|
.Xr man 7 |
|
manual formatting macro languages. |
|
This manual describes the subset of the |
|
.Nm |
|
language accepted by the |
.Xr mandoc 1 |
.Xr mandoc 1 |
utility. It is a work in progress. |
utility. |
.Pp |
.Pp |
An |
Input lines beginning with the control characters |
.Nm |
.Sq \&. |
document follows simple rules: lines beginning with the control |
|
characters |
|
.Sq \. |
|
or |
or |
.Sq \(aq |
.Sq \(aq |
are parsed for macros. Other lines are interpreted within the scope of |
are parsed for requests and macros. |
prior macros: |
These define the document structure, change the processing state |
.Bd -literal -offset indent |
and manipulate the formatting. |
\&.xx Macro lines change control state. |
Some requests and macros also produce formatted output, |
Other lines are interpreted within the current state. |
while others do not. |
.Ed |
.Pp |
|
All other input lines provide free-form text to be printed; |
|
the formatting of free-form 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 |
To produce other characters in the output, use the escape sequences |
|
documented in the |
|
.Xr mandoc_char 7 |
|
manual. |
|
.Pp |
|
All manuals must have |
.Ux |
.Ux |
line terminators. |
line terminators. |
.Sh MACRO SYNTAX |
.Sh REQUEST SYNTAX |
Macros are arbitrary in length and begin with a control character , |
A request or macro line consists of: |
.Sq \. |
.Pp |
|
.Bl -enum -compact |
|
.It |
|
the control character |
|
.Sq \&. |
or |
or |
.Sq \(aq , |
.Sq \(aq |
at the beginning of the line. |
at the beginning of the line, |
An arbitrary amount of whitespace may sit between the control character |
.It |
and the macro name. |
optionally an arbitrary amount of whitespace, |
Thus, the following are equivalent: |
.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 REQUEST REFERENCE |
This section is a canonical reference of all macros, arranged |
The |
alphabetically. |
.Xr mandoc 1 |
|
.Nm |
|
parser recognizes 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 center 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 \&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 |
|
Arguments are separated by blank characters and can be quoted |
|
using double-quotes |
|
.Pq Sq \(dq |
|
to allow inclusion of blank characters into arguments. |
|
To include the double-quote character into a quoted argument, |
|
escape it from ending the argument by doubling it. |
|
.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 112 If no stack entries are present (e.g., due to no prior |
|
Line 316 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 \&hy |
|
Set automatic hyphenation mode. |
|
This line-scoped request is currently ignored. |
.Ss \&ie |
.Ss \&ie |
The |
The |
.Qq if |
.Qq if |
Line 130 Begins a conditional. |
|
Line 337 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 189 evaluate as false. |
|
Line 391 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 text following an |
.Sq \&.\e} |
.Sq \&.\e} |
macro is discarded. |
escape sequence is discarded. |
Furthermore, if an explicit closing sequence |
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 specified in a free-form line, the entire line is accepted within the |
scope of the prior macro, not only the text preceding the close, with the |
scope of the prior request, not only the text preceding the close, with the |
.Sq \e} |
.Sq \e} |
collapsing into a zero-width space. |
collapsing into a zero-width space. |
.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. |
Line 274 A register is an arbitrary string value that defines s |
|
Line 486 A register is an arbitrary string value that defines s |
|
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 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 |
So far, only the following register |
.Cm name |
.Ar name |
is defined up to the next whitespace. |
is recognised: |
The following register |
|
.Cm name |
|
requests are recognised: |
|
.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 \&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 inadvertant inclusion of unrelated files, |
|
.Xr mandoc 1 |
|
only accepts relative paths not containing the strings |
|
.Qq ../ |
|
and |
|
.Qq /.. . |
.Ss \&tr |
.Ss \&tr |
Output character translation. |
Output character translation. |
This macro is intended to have one argument, |
This request is intended to have one argument, |
consisting of an even number of characters. |
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 \&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. |
|
A table consists of an optional single line of table options terminated |
|
by a semicolon, followed by one or more lines of layout specification |
|
terminated by a period, then table data. |
|
A table block may also include |
|
.Nm , |
|
.Xr mdoc 7 , |
|
or |
|
.Xr man 7 |
|
macros. |
|
Example: |
|
.Bd -literal -offset indent |
|
\&.TS |
|
box tab(:); \e" Table-wide options. |
|
c | c \e" Layout for first line. |
|
| c | c. \e" Layout for all subsequent lines. |
|
1:2 \e" Data... |
|
3:4 |
|
\&.TE |
|
.Ed |
|
.Pp |
|
Table data is |
|
.Em pre-processed , |
|
that is, data rows are parsed then inserted into the underlying stream |
|
of input data. |
|
This allows data rows to be interspersed by arbitrary macros, such as |
|
.Bd -literal -offset indent |
|
\&.TS |
|
tab(:); |
|
c c c. |
|
1:2:3 |
|
\&.Ao |
|
3:2:1 |
|
\&.Ac |
|
\&.TE |
|
.Ed |
|
.Pp |
|
in the case of |
|
.Xr mdoc 7 |
|
or |
|
.Bd -literal -offset indent |
|
\&.TS |
|
tab(:); |
|
c c c. |
|
\&.ds ab 2 |
|
1:\e*(ab:3 |
|
\&.I |
|
3:2:1 |
|
\&.TE |
|
.Ed |
|
.Pp |
|
in the case of |
|
.Xr man 7 . |
|
.Pp |
|
The first line of a table consists of its options, which consists of |
|
space-separated keys and modifiers terminated by a semicolon. |
|
If the first line does not have a terminating semicolon, it is assumed |
|
that no options are specified and instead a layout is processed. |
|
Some options accept arguments enclosed by paranthesis. |
|
The following case-insensitive options are available: |
|
.Bl -tag -width Ds |
|
.It Cm center |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
This may also be invoked with |
|
.Cm centre . |
|
.It Cm delim |
|
Accepts a two-character argument. |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm expand |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm box |
|
Draw a single-line box around the table. |
|
This may also be invoked with |
|
.Cm frame . |
|
.It Cm doublebox |
|
Draw a double-line box around the table. |
|
This may also be invoked with |
|
.Cm doubleframe . |
|
.It Cm allbox |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm tab |
|
Accepts a single-character argument. |
|
This character is used a delimiter between data cells, which otherwise |
|
defaults to the tab character. |
|
.It Cm linesize |
|
Accepts a natural number (all digits). |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm nokeep |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm decimalpoint |
|
Accepts a single-character argument. |
|
This character will be used as the decimal point with the |
|
.Cm n |
|
layout key. |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm nospaces |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.El |
|
.Pp |
|
The table layout follows table options, except in the case of |
|
.Sx \&T& , |
|
where it immediately procedes invocation. |
|
Layout specifies how data rows are displayed on output. |
|
Each layout line corresponds to a line of data; the last layout line |
|
applies to all remaining data lines. |
|
Layout lines may also be separated by a comma. |
|
Each layout cell consists of one of the following case-insensitive keys: |
|
.Bl -tag -width Ds |
|
.It Cm c |
|
Centre a literal string within its column. |
|
.It Cm r |
|
Right-justify a literal string within its column. |
|
.It Cm l |
|
Left-justify a literal string within its column. |
|
.It Cm n |
|
Justify a number around its decimal point. |
|
If the decimal point is not found on the number, it's assumed to trail |
|
the number. |
|
.It Cm s |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm a |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm ^ |
|
This option is not supported by |
|
.Xr mandoc 1 . |
|
.It Cm \- |
|
Replace the data cell (its contents will be lost) with a single |
|
horizontal line. |
|
This may also be invoked with |
|
.Cm _ . |
|
.It Cm = |
|
Replace the data cell (its contents will be lost) with a double |
|
horizontal line. |
|
.It Cm \(ba |
|
Emit a vertical bar instead of data. |
|
.It Cm \(ba\(ba |
|
Emit a double-vertical bar instead of data. |
|
.El |
|
.Pp |
|
For example, following layout specifies a centre-justified column of |
|
minimum width 10, followed by vertical bar, followed by a left-justified |
|
column of minimum width 10, another vertical bar, then a column |
|
justified about the decimal point in numbers: |
|
.Pp |
|
.Dl c10 | l10 | n |
|
.Pp |
|
Keys may be followed by a set of modifiers. |
|
A modifier is either a modifier key or a natural number for specifying |
|
spacing. |
|
The following case-insensitive modifier keys are available: |
|
.Cm z , |
|
.Cm u , |
|
.Cm e , |
|
.Cm t , |
|
.Cm d , |
|
.Cm f , |
|
.Cm b , |
|
.Cm i , |
|
.Cm b , |
|
and |
|
.Cm i . |
|
All of these are ignored by |
|
.Xr mandoc 1 . |
|
.Pp |
|
The data section follows the last layout row. |
|
By default, cells in a data section are delimited by a tab. |
|
This behaviour may be changed with the |
|
.Cm tab |
|
option. |
|
If |
|
.Cm _ |
|
or |
|
.Cm = |
|
is specified, a single or double line, respectively, is drawn across the |
|
data field. |
|
If |
|
.Cm \e- |
|
or |
|
.Cm \e= |
|
is specified, a line is drawn within the data field (i.e., terminating |
|
within the cell and not draw to the border). |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section documents compatibility between mandoc and other other |
This section documents compatibility between mandoc and other 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 |
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 man 7 , |
|
.Xr mandoc_char 7 , |
|
.Xr mdoc 7 |
|
.Rs |
|
.%A M. E. Lesk |
|
.%T Tbl\(emA Program to Format Tables |
|
.%D June 11, 1976 |
|
.%U http://www.kohala.com/start/troff/v7/man/tbl/tbl.ps |
|
.Re |
|
.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 was written in PL/1 for the CTSS |
|
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 , |
|
Doug McIlroy rewrote it in BCPL in 1969, |
|
Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973, |
|
and Brian W. Kernighan rewrote it in C in 1975. |
.Sh AUTHORS |
.Sh AUTHORS |
The |
.An -nosplit |
|
This partial |
.Nm |
.Nm |
reference was written by |
reference was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons Aq kristaps@bsd.lv |
|
and |
|
.An Ingo Schwarze Aq schwarze@openbsd.org . |