version 1.39, 2012/06/12 20:21:04 |
version 1.47, 2014/02/14 23:50:57 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010, 2011, 2013, 2014 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 |
|
|
manual formatting languages are based on it, |
manual formatting languages are based on it, |
many real-world manuals use small numbers of |
many real-world manuals use small numbers of |
.Nm |
.Nm |
requests intermixed with their |
requests and escape sequences intermixed with their |
.Xr mdoc 7 |
.Xr mdoc 7 |
or |
or |
.Xr man 7 |
.Xr man 7 |
Line 41 To properly format such manuals, the |
|
Line 41 To properly format such manuals, the |
|
.Xr mandoc 1 |
.Xr mandoc 1 |
utility supports a tiny subset of |
utility supports a tiny subset of |
.Nm |
.Nm |
requests. |
requests and escapes. |
Only these requests supported by |
Only these requests and escapes supported by |
.Xr mandoc 1 |
.Xr mandoc 1 |
are documented in the present manual, |
are documented in the present manual, |
together with the basic language syntax shared by |
together with the basic language syntax shared by |
Line 85 documents may contain only graphable 7-bit ASCII chara |
|
Line 85 documents may contain only graphable 7-bit ASCII chara |
|
character, and, in certain circumstances, the tab character. |
character, and, in certain circumstances, the tab character. |
The backslash character |
The backslash character |
.Sq \e |
.Sq \e |
indicates the start of an escape sequence for |
indicates the start of an escape sequence, used for example for |
.Sx Comments , |
.Sx Comments , |
.Sx Special Characters , |
.Sx Special Characters , |
.Sx Predefined Strings , |
.Sx Predefined Strings , |
|
|
user-defined strings defined using the |
user-defined strings defined using the |
.Sx ds |
.Sx ds |
request. |
request. |
|
For a listing of escape sequences, consult the |
|
.Sx ESCAPE SEQUENCE REFERENCE |
|
below. |
.Ss Comments |
.Ss Comments |
Text following an escaped double-quote |
Text following an escaped double-quote |
.Sq \e\(dq , |
.Sq \e\(dq , |
Line 146 respectively) may be used instead. |
|
Line 149 respectively) may be used instead. |
|
The indicator or numerical representative may be preceded by C |
The indicator or numerical representative may be preceded by C |
(constant-width), which is ignored. |
(constant-width), which is ignored. |
.Pp |
.Pp |
|
The two-character indicator |
|
.Sq BI |
|
requests a font that is both bold and italic. |
|
It may not be portable to old roff implementations. |
|
.Pp |
Examples: |
Examples: |
.Bl -tag -width Ds -offset indent -compact |
.Bl -tag -width Ds -offset indent -compact |
.It Li \efBbold\efR |
.It Li \efBbold\efR |
Write in bold, then switch to regular font mode. |
Write in \fBbold\fP, then switch to regular font mode. |
.It Li \efIitalic\efP |
.It Li \efIitalic\efP |
Write in italic, then return to previous font mode. |
Write in \fIitalic\fP, then return to previous font mode. |
|
.It Li \ef(BIbold italic\efP |
|
Write in \f(BIbold italic\fP, then return to previous font mode. |
.El |
.El |
.Pp |
.Pp |
Text decoration is |
Text decoration is |
Line 417 The syntax of this request is the same as that of |
|
Line 427 The syntax of this request is the same as that of |
|
It is currently ignored by |
It is currently ignored by |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
as are its children. |
as are its children. |
|
.Ss \&as |
|
Append to a user-defined string. |
|
The syntax of this request is the same as that of |
|
.Sx \&ds . |
|
If a user-defined string with the specified name does not yet exist, |
|
it is set to the empty string before appending. |
.Ss \&cc |
.Ss \&cc |
Changes the control character. |
Changes the control character. |
Its syntax is as follows: |
Its syntax is as follows: |
|
|
is not specified, the control character is reset to |
is not specified, the control character is reset to |
.Sq \&. . |
.Sq \&. . |
Trailing characters are ignored. |
Trailing characters are ignored. |
|
.Ss \&ce |
|
Center some lines. |
|
This line-scoped request is intended to take one integer argument, |
|
specifying how many lines to center. |
|
Currently, it is ignored including its arguments, and the number |
|
of arguments is not checked. |
.Ss \&de |
.Ss \&de |
Define a |
Define a |
.Nm |
.Nm |
Line 631 Begin an equation block. |
|
Line 653 Begin an equation block. |
|
See |
See |
.Xr eqn 7 |
.Xr eqn 7 |
for a description of the equation language. |
for a description of the equation language. |
|
.Ss \&fam |
|
Change the font family. |
|
This line-scoped request is intended to have one argument specifying |
|
the font family to be selected. |
|
It is a groff extension, and currently, it is ignored including its |
|
arguments, and the number of arguments is not checked. |
|
.Ss \&hw |
|
Specify hyphenation points in words. |
|
This line-scoped request is currently ignored. |
.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 798 the name of the request, macro or string to be undefin |
|
Line 829 the name of the request, macro or string to be undefin |
|
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. |
.Ss \&nr |
.Ss \&nr |
Define a register. |
Define or change a register. |
A register is an arbitrary string value that defines some sort of state, |
A register is an arbitrary string value that defines some sort of state, |
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 \. Cm \&nr Ar name Ar value |
.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar value |
.Pp |
.Pp |
The |
The |
.Ar value |
.Ar value |
may, at the moment, only be an integer. |
may, at the moment, only be an integer. |
So far, only the following register |
If it is prefixed by a sign, the register will be |
|
incremented or decremented instead of assigned to. |
|
.Pp |
|
The following register |
.Ar name |
.Ar name |
is recognised: |
is handled specially: |
.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 907 Begin a table, which formats input in aligned rows and |
|
Line 941 Begin a table, which formats input in aligned rows and |
|
See |
See |
.Xr tbl 7 |
.Xr tbl 7 |
for a description of the tbl language. |
for a description of the tbl language. |
|
.Sh ESCAPE SEQUENCE REFERENCE |
|
The |
|
.Xr mandoc 1 |
|
.Nm |
|
parser recognises the following escape sequences. |
|
Note that the |
|
.Nm |
|
language defines more escape sequences not implemented in |
|
.Xr mandoc 1 . |
|
In |
|
.Xr mdoc 7 |
|
and |
|
.Xr man 7 |
|
documents, using escape sequences is discouraged except for those |
|
described in the |
|
.Sx LANGUAGE SYNTAX |
|
section above. |
|
.Pp |
|
A backslash followed by any character not listed here |
|
simply prints that character itself. |
|
.Ss \e<newline> |
|
A backslash at the end of an input line can be used to continue the |
|
logical input line on the next physical input line, joining the text |
|
on both lines together as if it were on a single input line. |
|
.Ss \e<space> |
|
The escape sequence backslash-space |
|
.Pq Sq \e\ \& |
|
is an unpaddable space-sized non-breaking space character; see |
|
.Sx Whitespace . |
|
.Ss \e\(dq |
|
The rest of the input line is treated as |
|
.Sx Comments . |
|
.Ss \e% |
|
Hyphenation allowed at this point of the word; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \e& |
|
Non-printing zero-width character; see |
|
.Sx Whitespace . |
|
.Ss \e\(aq |
|
Acute accent special character; use |
|
.Sq \e(aa |
|
instead. |
|
.Ss \e( Ns Ar cc |
|
.Sx Special Characters |
|
with two-letter names, see |
|
.Xr mandoc_char 7 . |
|
.Ss \e*[ Ns Ar name ] |
|
Interpolate the string with the |
|
.Ar name ; |
|
see |
|
.Sx Predefined Strings |
|
and |
|
.Sx ds . |
|
For short names, there are variants |
|
.No \e* Ns Ar c |
|
and |
|
.No \e*( Ns Ar cc . |
|
.Ss \e- |
|
Special character |
|
.Dq mathematical minus sign . |
|
.Ss \e[ Ns Ar name ] |
|
.Sx Special Characters |
|
with names of arbitrary length, see |
|
.Xr mandoc_char 7 . |
|
.Ss \e^ |
|
One-twelfth em half-narrow space character, effectively zero-width in |
|
.Xr mandoc 1 . |
|
.Ss \e` |
|
Grave accent special character; use |
|
.Sq \e(ga |
|
instead. |
|
.Ss \e{ |
|
Begin conditional input; see |
|
.Sx if . |
|
.Ss \e\(ba |
|
One-sixth em narrow space character, effectively zero-width in |
|
.Xr mandoc 1 . |
|
.Ss \e} |
|
End conditional input; see |
|
.Sx if . |
|
.Ss \e~ |
|
Paddable non-breaking space character. |
|
.Ss \e0 |
|
Digit width space character. |
|
.Ss \eA\(aq Ns Ar string Ns \(aq |
|
Anchor definition; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eB\(aq Ns Ar string Ns \(aq |
|
Test whether |
|
.Ar string |
|
is a numerical expession; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eb\(aq Ns Ar string Ns \(aq |
|
Bracket building function; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eC\(aq Ns Ar name Ns \(aq |
|
.Sx Special Characters |
|
with names of arbitrary length. |
|
.Ss \ec |
|
Interrupt text processing to insert requests or macros; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eD\(aq Ns Ar string Ns \(aq |
|
Draw graphics function; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \ed |
|
Move down by half a line; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \ee |
|
Backslash special character. |
|
.Ss \eF[ Ns Ar name ] |
|
Switch font family (groff extension); ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \eF Ns Ar c |
|
and |
|
.No \eF( Ns Ar cc . |
|
.Ss \ef[ Ns Ar name ] |
|
Switch to the font |
|
.Ar name , |
|
see |
|
.Sx Text Decoration . |
|
For short names, there are variants |
|
.No \ef Ns Ar c |
|
and |
|
.No \ef( Ns Ar cc . |
|
.Ss \eg[ Ns Ar name ] |
|
Interpolate the format of a number register; ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \eg Ns Ar c |
|
and |
|
.No \eg( Ns Ar cc . |
|
.Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq |
|
Set the height of the current font; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eh\(aq Ns Ar number Ns \(aq |
|
Horizontal motion; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \ek[ Ns Ar name ] |
|
Mark horizontal input place in register; ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \ek Ns Ar c |
|
and |
|
.No \ek( Ns Ar cc . |
|
.Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq |
|
Vertical line drawing function; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq |
|
Horizontal line drawing function; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eM[ Ns Ar name ] |
|
Set fill (background) color (groff extension); ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \eM Ns Ar c |
|
and |
|
.No \eM( Ns Ar cc . |
|
.Ss \em[ Ns Ar name ] |
|
Set glyph drawing color (groff extension); ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \em Ns Ar c |
|
and |
|
.No \em( Ns Ar cc . |
|
.Ss \eN\(aq Ns Ar number Ns \(aq |
|
Character |
|
.Ar number |
|
on the current font. |
|
.Ss \en[ Ns Ar name ] |
|
Interpolate the number register |
|
.Ar name . |
|
For short names, there are variants |
|
.No \en Ns Ar c |
|
and |
|
.No \en( Ns Ar cc . |
|
.Ss \eo\(aq Ns Ar string Ns \(aq |
|
Overstrike |
|
.Ar string ; |
|
ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq |
|
Set number register; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eS\(aq Ns Ar number Ns \(aq |
|
Slant output; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq |
|
Change point size; ignored by |
|
.Xr mandoc 1 . |
|
Alternative forms |
|
.No \es Ns Oo +|- Oc Ns Ar n , |
|
.No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq , |
|
.No \es Ns [ Oo +|- Oc Ns Ar number ] , |
|
and |
|
.No \es Ns Oo +|- Oc Ns [ Ar number Ns ] |
|
are also parsed and ignored. |
|
.Ss \et |
|
Horizontal tab; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eu |
|
Move up by half a line; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eV[ Ns Ar name ] |
|
Interpolate an environment variable; ignored by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \eV Ns Ar c |
|
and |
|
.No \eV( Ns Ar cc . |
|
.Ss \ev\(aq Ns Ar number Ns \(aq |
|
Vertical motion; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \ew\(aq Ns Ar string Ns \(aq |
|
Interpolate the width of the |
|
.Ar string ; |
|
ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eX\(aq Ns Ar string Ns \(aq |
|
Output |
|
.Ar string |
|
as device control function; ignored in nroff mode and by |
|
.Xr mandoc 1 . |
|
.Ss \ex\(aq Ns Ar number Ns \(aq |
|
Extra line space function; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \eY[ Ns Ar name ] |
|
Output a string as a device control function; ignored in nroff mode and by |
|
.Xr mandoc 1 . |
|
For short names, there are variants |
|
.No \eY Ns Ar c |
|
and |
|
.No \eY( Ns Ar cc . |
|
.Ss \eZ\(aq Ns Ar string Ns \(aq |
|
Print |
|
.Ar string |
|
with zero width and height; ignored by |
|
.Xr mandoc 1 . |
|
.Ss \ez |
|
Output the next character without advancing the cursor position; |
|
approximated in |
|
.Xr mandoc 1 |
|
by simply skipping the next character. |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section documents compatibility between mandoc and other other |
This section documents compatibility between mandoc and other |
.Nm |
.Nm |
implementations, at this time limited to GNU troff |
implementations, at this time limited to GNU troff |
.Pq Qq groff . |
.Pq Qq groff . |
Line 994 In 1989, James Clarke re-implemented troff in C++, nam |
|
Line 1271 In 1989, James Clarke re-implemented troff in C++, nam |
|
This |
This |
.Nm |
.Nm |
reference was written by |
reference was written by |
.An Kristaps Dzonsons , |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
.Mt kristaps@bsd.lv ; |
|
and |
and |
.An Ingo Schwarze , |
.An Ingo Schwarze Aq Mt schwarze@openbsd.org . |
.Mt schwarze@openbsd.org . |
|