version 1.2, 2010/05/16 22:28:33 |
version 1.12, 2010/07/04 22:04:04 |
|
|
.\" $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 |
Line 65 Thus, the following are equivalent: |
|
Line 66 Thus, the following are equivalent: |
|
.Sh REFERENCE |
.Sh REFERENCE |
This section is a canonical reference of all macros, arranged |
This section is a canonical reference of all macros, arranged |
alphabetically. |
alphabetically. |
|
.Ss \&am |
|
The syntax of this macro is the same as that of |
|
.Sx \&ig , |
|
except that a leading argument must be specified. |
|
It is ignored, as are its children. |
|
.Ss \&ami |
|
The syntax of this macro is the same as that of |
|
.Sx \&ig , |
|
except that a leading argument must be specified. |
|
It is ignored, as are its children. |
|
.Ss \&am1 |
|
The syntax of this macro is the same as that of |
|
.Sx \&ig , |
|
except that a leading argument must be specified. |
|
It is ignored, as are its children. |
|
.Ss \&de |
|
The syntax of this macro is the same as that of |
|
.Sx \&ig , |
|
except that a leading argument must be specified. |
|
It is ignored, as are its children. |
|
.Ss \&dei |
|
The syntax of this macro is the same as that of |
|
.Sx \&ig , |
|
except that a leading argument must be specified. |
|
It is ignored, as are its children. |
|
.Ss \&ds |
|
Define a string. |
|
This macro is intended to have two arguments, |
|
the name of the string to define and its content. |
|
Currently, it is ignored including its arguments, |
|
and the number of arguments is not checked. |
|
.Ss \&de1 |
|
The syntax of this macro is the same as that of |
|
.Sx \&ig , |
|
except that a leading argument must be specified. |
|
It is ignored, as are its children. |
|
.Ss \&el |
|
The |
|
.Qq else |
|
half of an if/else conditional. |
|
Pops a result off the stack of conditional evaluations pushed by |
|
.Sx \&ie |
|
and uses it as its conditional. |
|
If no stack entries are present (e.g., due to no prior |
|
.Sx \&ie |
|
calls) |
|
then false is assumed. |
|
The syntax of this macro is similar to |
|
.Sx \&if |
|
except that the conditional is missing. |
|
.Ss \&ie |
|
The |
|
.Qq if |
|
half of an if/else conditional. |
|
The result of the conditional is pushed into a stack used by subsequent |
|
invocations of |
|
.Sx \&el , |
|
which may be separated by any intervening input (or not exist at all). |
|
Its syntax is equivalent to |
|
.Sx \&if . |
.Ss \&if |
.Ss \&if |
Begins a conditional. |
Begins a conditional. |
Has the following syntax: |
Right now, the conditional evaluates to true |
|
if and only if it starts with the letter |
|
.Sy n , |
|
indicating processing in |
|
.Xr nroff 1 |
|
style as opposed to |
|
.Xr troff 1 |
|
style. |
|
If a conditional is false, its children are not processed, but are |
|
syntactically interpreted to preserve the integrity of the input |
|
document. |
|
Thus, |
.Pp |
.Pp |
|
.D1 \&.if t \e .ig |
|
.Pp |
|
will discard the |
|
.Sq \&.ig , |
|
which may lead to interesting results, but |
|
.Pp |
|
.D1 \&.if t \e .if t \e{\e |
|
.Pp |
|
will continue to syntactically interpret to the block close of the final |
|
conditional. |
|
Sub-conditionals, in this case, obviously inherit the truth value of |
|
the parent. |
|
This macro has the following syntax: |
|
.Pp |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent -compact |
\&.if COND \e{\e |
\&.if COND \e{\e |
BODY... |
BODY... |
|
|
BODY |
BODY |
.Ed |
.Ed |
.Pp |
.Pp |
COND is a conditional (TODO: document). |
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 |
.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{ , |
Line 121 macro is discarded. |
|
Line 219 macro 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. |
scope of the prior macro, not only the text preceding the close, with the |
|
.Sq \e} |
|
collapsing into a zero-width space. |
.Ss \&ig |
.Ss \&ig |
Ignore input. |
Ignore input. |
Accepts the following syntax: |
Accepts the following syntax: |
Line 163 the subsequent invocation of |
|
Line 263 the subsequent invocation of |
|
.Sx \&if |
.Sx \&if |
will first signify the end of comment, then be invoked as a macro. |
will first signify the end of comment, then be invoked as a macro. |
This behaviour really shouldn't be counted upon. |
This behaviour really shouldn't be counted upon. |
|
.Ss \&rm |
|
Remove a request, macro or string. |
|
This macro is intended to have one argument, |
|
the name of the request, macro or string to be undefined. |
|
Currently, it is ignored including its arguments, |
|
and the number of arguments is not checked. |
|
.Ss \&nr |
|
Define a register. |
|
A register is an arbitrary string value that defines some sort of state, |
|
which influences parsing and/or formatting. |
|
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf \. Sx \&nr Cm name value |
|
.Pp |
|
The |
|
.Cm value |
|
may, at the moment, only be an integer. |
|
The |
|
.Cm name |
|
is defined up to the next whitespace. |
|
The following register |
|
.Cm name |
|
requests are recognised: |
|
.Bl -tag -width Ds |
|
.It Cm nS |
|
If set to a positive integer value, certain |
|
.Xr mdoc 7 |
|
macros will behave as if they were defined in the |
|
.Em SYNOPSIS |
|
section. |
|
Otherwise, this behaviour is unset (even if called within the |
|
.Em SYNOPSIS |
|
section itself). |
|
Note that invoking a new |
|
.Xr mdoc 7 |
|
section will unset this value. |
|
.El |
|
.Ss \&tr |
|
Output character translation. |
|
This macro is intended to have one argument, |
|
consisting of an even number of characters. |
|
Currently, it is ignored including its arguments, |
|
and the number of arguments is not checked. |
.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 |
troff implementations, at this time limited to GNU troff |
|
|
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
|
The |
|
.Cm nS |
|
request to |
|
.Sx \&nr |
|
is only compatible with OpenBSD's groff. |
|
.It |
Historic groff did not accept white-space buffering the custom END tag |
Historic groff did not accept white-space buffering the custom END tag |
for the |
for the |
.Sx \&ig |
.Sx \&ig |
macro. |
macro. |
|
.It |
|
The |
|
.Sx \&if |
|
and family would print funny white-spaces with historic groff when |
|
depending on next-line syntax. |
.El |
.El |
.Sh AUTHORS |
.Sh AUTHORS |
The |
The |