version 1.14, 2010/07/27 13:16:00 |
version 1.15, 2010/12/06 16:37:32 |
|
|
.Sq \. |
.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. |
|
Other lines are interpreted within the scope of |
prior macros: |
prior macros: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.xx Macro lines change control state. |
\&.xx Macro lines change control state. |
Line 51 manuals must have |
|
Line 52 manuals must have |
|
.Ux |
.Ux |
line terminators. |
line terminators. |
.Sh MACRO SYNTAX |
.Sh MACRO SYNTAX |
Macros are arbitrary in length and begin with a control character , |
Requests and macros are arbitrary in length and begin with a control |
|
character, |
.Sq \. |
.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 |
An arbitrary amount of whitespace may sit between the control character |
and the macro name. |
and the request or macro name. |
Thus, the following are equivalent: |
Thus, the following are equivalent: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
\&.if |
\&.if |
\&.\ \ \ \&if |
\&.\ \ \ \&if |
.Ed |
.Ed |
.Sh REFERENCE |
.Sh REQUEST REFERENCE |
This section is a canonical reference of all macros, arranged |
This section is a canonical reference of all requests recognized by the |
alphabetically. |
.Xr mandoc 1 |
|
.Nm |
|
parser. |
|
The |
|
.Nm |
|
language defines many more requests and macros 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 user-defined |
.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 |
|
A user-defined 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 user-defined 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 user-defined macros and 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. |
.Ss \&dei |
.Ss \&dei |
|
Define a user-defined |
|
.Nm |
|
macro, specifying the macro name indirectly. |
The syntax of this macro is the same as that of |
The syntax of this macro is the same as that of |
.Sx \&ig , |
.Sx \&de . |
except that a leading argument must be specified. |
It is currently ignored by |
It is ignored, as are its children. |
.Xr mandoc 1 , |
|
as are its children. |
|
.Ss \&de1 |
|
Define a user-defined |
|
.Nm |
|
macro that will be executed with |
|
.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 macro as an alias for |
|
.Sx \&de . |
.Ss \&ds |
.Ss \&ds |
Define a reserved word. |
Define a user-defined string. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf \. Sx \&ds No Cm key val |
.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string |
.Pp |
.Pp |
The |
The |
.Cm key |
.Ar name |
and |
and |
.Cm val |
.Ar string |
strings are space-separated. |
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 |
The |
.Cm key |
.Ar string |
values may be invoked in subsequent text by using \e*(NN for two-letter |
can be interpolated into subsequent text by using |
pairs, \e*N for one-letter, and \e*[NNN] for arbitrary-length values. |
.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. |
.Pp |
.Pp |
If |
Since user-defined strings and macros share a common string table, |
.Cm val |
defining a string |
is begun with a double-quote mark, the mark is passed over. |
.Ar name |
.Cm val |
clobbers the user-defined macro |
consists of |
.Ar name , |
.Em all |
and the |
text following this point, including whitespace and trailing |
.Ar name |
double-quotes. |
used for defining a string can also be invoked as a macro, |
.Ss \&de1 |
in which case the following input line will be appended to the |
The syntax of this macro is the same as that of |
.Ar string , |
.Sx \&ig , |
forming a new input line passed to the |
except that a leading argument must be specified. |
.Nm |
It is ignored, as are its children. |
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 134 then false is assumed. |
|
Line 289 then false is assumed. |
|
The syntax of this macro is similar to |
The syntax of this macro 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 242 scope of the prior macro, not only the text preceding |
|
Line 400 scope of the prior macro, not only the text preceding |
|
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. |
macro 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 \&.. |
|
macro 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 293 A register is an arbitrary string value that defines s |
|
Line 461 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 |
The |
.Cm name |
.Ar name |
is defined up to the next whitespace. |
is defined up to the next whitespace. |
The following register |
So far, only the following register |
.Cm name |
.Ar name |
requests are recognised: |
is 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 |
Line 318 Note that invoking a new |
|
Line 486 Note that invoking a new |
|
.Xr mdoc 7 |
.Xr mdoc 7 |
section will unset this value. |
section will unset this value. |
.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 macro is intended to have one argument, |
Line 354 and family would print funny white-spaces with histori |
|
Line 539 and family would print funny white-spaces with histori |
|
depending on next-line syntax. |
depending on next-line syntax. |
.El |
.El |
.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 . |