version 1.1, 2010/05/16 19:08:11 |
version 1.6, 2010/05/24 22:25:58 |
Line 65 Thus, the following are equivalent: |
|
Line 65 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 that always evaluates to false. |
Has the following syntax: |
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... |
|
|
.Ed |
.Ed |
.Bd -literal -offset indent -compact |
.Bd -literal -offset indent -compact |
\&.if COND \e{ BODY |
\&.if COND \e{ BODY |
|
BODY... \e} |
|
.Ed |
|
.Bd -literal -offset indent -compact |
|
\&.if COND \e{ BODY |
BODY... |
BODY... |
\&.\e} |
\&.\e} |
.Ed |
.Ed |
|
|
BODY |
BODY |
.Ed |
.Ed |
.Pp |
.Pp |
COND is a conditional (TODO: document). |
COND is a conditional (for the time being, this always evaluates to |
|
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 112 The scope of a conditional is always parsed, but only |
|
Line 194 The scope of a conditional is always parsed, but only |
|
conditional evaluates to true. |
conditional evaluates to true. |
.Pp |
.Pp |
Note that text subsequent a |
Note that text subsequent a |
|
.Sq \&.\e} |
|
macro is discarded. |
|
Furthermore, if an explicit closing sequence |
.Sq \e} |
.Sq \e} |
is discarded. |
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. |
.Ss \&ig |
.Ss \&ig |
Ignore input until a |
Ignore input. |
.Sq \.\. |
Accepts the following syntax: |
|
.Pp |
|
.Bd -literal -offset indent -compact |
|
\&.ig |
|
BODY... |
|
\&.. |
|
.Ed |
|
.Bd -literal -offset indent -compact |
|
\&.ig END |
|
BODY... |
|
\&.END |
|
.Ed |
|
.Pp |
|
In the first case, input is ignored until a |
|
.Sq \&.. |
macro is encountered on its own line. |
macro is encountered on its own line. |
Note that text subsequent the |
In the second case, input is ignored until a |
.Sq \.\. |
.Sq \&.END |
|
is encountered. |
|
Text subsequent the |
|
.Sq \&.END |
|
or |
|
.Sq \&.. |
is discarded. |
is discarded. |
|
.Pp |
|
Do not use the escape |
|
.Sq \e |
|
anywhere in the definition of END. |
|
It causes very strange behaviour. |
|
Furthermore, if you redefine a |
|
.Nm |
|
macro, such as |
|
.Pp |
|
.D1 \&.ig if |
|
.Pp |
|
the subsequent invocation of |
|
.Sx \&if |
|
will first signify the end of comment, then be invoked as a macro. |
|
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 \&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 |
|
This section documents compatibility between mandoc and other other |
|
troff implementations, at this time limited to GNU troff |
|
.Pq Qq groff . |
|
The term |
|
.Qq historic groff |
|
refers to groff versions before the |
|
.Pa doc.tmac |
|
file re-write |
|
.Pq somewhere between 1.15 and 1.19 . |
|
.Pp |
|
.Bl -dash -compact |
|
.It |
|
Historic groff did not accept white-space buffering the custom END tag |
|
for the |
|
.Sx \&ig |
|
macro. |
|
.It |
|
The |
|
.Sx \&if |
|
and family would print funny white-spaces with historic groff when |
|
depending on next-line syntax. |
|
.El |
.Sh AUTHORS |
.Sh AUTHORS |
The |
The |
.Nm |
.Nm |