version 1.22, 2011/01/04 15:02:00 |
version 1.31, 2011/08/18 08:58:44 |
Line 57 To produce other characters in the output, use the esc |
|
Line 57 To produce other characters in the output, use the esc |
|
documented in the |
documented in the |
.Xr mandoc_char 7 |
.Xr mandoc_char 7 |
manual. |
manual. |
.Pp |
|
All manuals must have |
|
.Ux |
|
line terminators. |
|
.Sh REQUEST SYNTAX |
.Sh REQUEST SYNTAX |
A request or macro line consists of: |
A request or macro line consists of: |
.Pp |
.Pp |
Line 86 Thus, the following request lines are all equivalent: |
|
Line 82 Thus, the following request lines are all equivalent: |
|
\&.ig end |
\&.ig end |
\&. ig end |
\&. ig end |
.Ed |
.Ed |
|
.Sh MACRO SYNTAX |
|
Macros 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 . |
|
To be recognized as the beginning of a quoted argument, the opening |
|
quote character must be preceded by a space character. |
|
.Pp |
|
A quoted argument may contain whitespace, and pairs of double quote |
|
characters |
|
.Pq Sq Qq |
|
resolve to single double quote characters. |
|
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. |
.Sh REQUEST REFERENCE |
.Sh REQUEST REFERENCE |
The |
The |
.Xr mandoc 1 |
.Xr mandoc 1 |
Line 174 The macro can be invoked later using the syntax |
|
Line 202 The macro can be invoked later using the syntax |
|
.Pp |
.Pp |
.D1 Pf . Ar name Op Ar argument Op Ar argument ... |
.D1 Pf . Ar name Op Ar argument Op Ar argument ... |
.Pp |
.Pp |
Arguments are separated by blank characters and can be quoted |
Regarding argument parsing, see |
using double-quotes |
.Sx MACRO SYNTAX |
.Pq Sq \(dq |
above. |
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 |
.Pp |
The line invoking the macro will be replaced |
The line invoking the macro will be replaced |
in the input stream by the |
in the input stream by the |
Line 319 then false is assumed. |
|
Line 344 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 \&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 414 than having the request or macro follow as |
|
Line 448 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 512 section with the |
|
Line 551 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 /.. . |
|
.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. |
|
|
.Sx \&TS . |
.Sx \&TS . |
.Ss \&TS |
.Ss \&TS |
Begin a table, which formats input in aligned rows and columns. |
Begin a table, which formats input in aligned rows and columns. |
A table consists of an optional single line of table options terminated |
See |
by a semicolon, followed by one or more lines of layout specification |
.Xr tbl 7 |
terminated by a period, then table data. |
for a description of the tbl language. |
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). |
|
If the last cell of a line is |
|
.Cm T{ , |
|
all subsequent lines are included as part of the cell until |
|
.Cm T} |
|
is specified on its own line. |
|
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section documents compatibility between mandoc and other other |
This section documents compatibility between mandoc and other other |
.Nm |
.Nm |
Line 752 refers to groff version 1.15. |
|
Line 624 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 769 using the next-line syntax. |
|
Line 654 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 , |
|
.Xr tbl 7 |
.Rs |
.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 Joseph F. Ossanna |
.%A Brian W. Kernighan |
.%A Brian W. Kernighan |
.%I AT&T Bell Laboratories |
.%I AT&T Bell Laboratories |
Line 808 Joseph F. Ossanna rewrote it in PDP-11 assembly in 197 |
|
Line 689 Joseph F. Ossanna rewrote it in PDP-11 assembly in 197 |
|
and Brian W. Kernighan rewrote it in C in 1975. |
and Brian W. Kernighan rewrote it in C in 1975. |
.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 , |
|
.Mt kristaps@bsd.lv ; |
and |
and |
.An Ingo Schwarze Aq schwarze@openbsd.org . |
.An Ingo Schwarze , |
|
.Mt schwarze@openbsd.org . |