version 1.11, 2010/06/27 16:36:22 |
version 1.16, 2010/12/10 20:58:56 |
|
|
.\" $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 |
|
|
.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 50 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. |
|
.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 |
|
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 , |
.Ss \&ds |
as are its children. |
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 |
.Ss \&de1 |
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 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 macro 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. |
|
.Pp |
|
Since user-defined strings and macros share a common string table, |
|
defining a string |
|
.Ar name |
|
clobbers the user-defined 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 115 then false is assumed. |
|
Line 295 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 223 scope of the prior macro, not only the text preceding |
|
Line 406 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 274 A register is an arbitrary string value that defines s |
|
Line 467 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 299 Note that invoking a new |
|
Line 492 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 335 and family would print funny white-spaces with histori |
|
Line 545 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 . |