version 1.106, 2018/10/04 15:16:23 |
version 1.111, 2019/01/01 03:45:29 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2010-2018 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010-2019 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 |
|
|
code. |
code. |
To properly format such manuals, the |
To properly format such manuals, the |
.Xr mandoc 1 |
.Xr mandoc 1 |
utility supports a tiny subset of |
utility supports a subset of |
.Nm |
.Nm |
requests and escapes. |
requests and escapes. |
Only these requests and escapes supported by |
Even though this manual page lists all |
|
.Nm |
|
requests and escape sequences, it only contains partial information |
|
about requests not supported by |
.Xr mandoc 1 |
.Xr mandoc 1 |
are documented in the present manual, |
and about language features that do not matter for manual pages. |
together with the basic language syntax shared by |
|
.Nm , |
|
.Xr mdoc 7 , |
|
and |
|
.Xr man 7 . |
|
For complete |
For complete |
.Nm |
.Nm |
manuals, consult the |
manuals, consult the |
Line 89 indicates the start of an escape sequence, used for ex |
|
Line 87 indicates the start of an escape sequence, used for ex |
|
.Sx Comments |
.Sx Comments |
and |
and |
.Sx Special Characters . |
.Sx Special Characters . |
For a listing of escape sequences, consult the |
For a complete listing of escape sequences, consult the |
.Sx ESCAPE SEQUENCE REFERENCE |
.Sx ESCAPE SEQUENCE REFERENCE |
below. |
below. |
.Ss Comments |
.Ss Comments |
Line 135 One-letter backslash escape. |
|
Line 133 One-letter backslash escape. |
|
See |
See |
.Xr mandoc_char 7 |
.Xr mandoc_char 7 |
for a complete list. |
for a complete list. |
.Ss Text Decoration |
.Ss Font Selection |
Terms may be text-decorated using the |
In |
.Sq \ef |
.Xr mdoc 7 |
escape followed by an indicator: B (bold), I (italic), R (regular), or P |
and |
(revert to previous mode). |
.Xr man 7 |
A numerical representation 3, 2, or 1 (bold, italic, and regular, |
documents, fonts are usually selected with macros. |
respectively) may be used instead. |
The |
The indicator or numerical representative may be preceded by C |
.Ic \ef |
(constant-width), which is ignored. |
escape sequence and the |
|
.Ic \&ft |
|
request can be used to manually change the font, |
|
but this is not recommended in |
|
.Xr mdoc 7 |
|
documents. |
|
Such manual font changes are overridden by many subsequent macros. |
.Pp |
.Pp |
The two-character indicator |
The following fonts are supported: |
.Sq BI |
|
requests a font that is both bold and italic. |
|
It may not be portable to old roff implementations. |
|
.Pp |
.Pp |
|
.Bl -tag -width CW -offset indent -compact |
|
.It Cm B |
|
Bold font. |
|
.It Cm BI |
|
A font that is both bold and italic. |
|
.It Cm CB |
|
Bold constant width font. |
|
Same as |
|
.Cm B |
|
in terminal output. |
|
.It Cm CI |
|
Italic constant width font. |
|
Same as |
|
.Cm I |
|
in terminal output. |
|
.It Cm CR |
|
Regular constant width font. |
|
Same as |
|
.Cm R |
|
in terminal output. |
|
.It Cm CW |
|
An alias for |
|
.Cm CR . |
|
.It Cm I |
|
Italic font. |
|
.It Cm P |
|
Return to the previous font. |
|
If a macro caused a font change since the last |
|
.Ic \ef |
|
eascape sequence or |
|
.Ic \&ft |
|
request, this returns to the font before the last font change in |
|
the macro rather than to the font before the last manual font change. |
|
.It Cm R |
|
Roman font. |
|
This is the default font. |
|
.It Cm 1 |
|
An alias for |
|
.Cm R . |
|
.It Cm 2 |
|
An alias for |
|
.Cm I . |
|
.It Cm 3 |
|
An alias for |
|
.Cm B . |
|
.It Cm 4 |
|
An alias for |
|
.Cm BI . |
|
.El |
|
.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 |
Line 159 Write in \fIitalic\fP, then return to previous font mo |
|
Line 210 Write in \fIitalic\fP, then return to previous font mo |
|
.It Li \ef(BIbold italic\efP |
.It Li \ef(BIbold italic\efP |
Write in \f(BIbold italic\fP, then return to previous font mode. |
Write in \f(BIbold italic\fP, then return to previous font mode. |
.El |
.El |
.Pp |
|
Text decoration is |
|
.Em not |
|
recommended for |
|
.Xr mdoc 7 , |
|
which encourages semantic annotation. |
|
.Ss Whitespace |
.Ss Whitespace |
Whitespace consists of the space character. |
Whitespace consists of the space character. |
In text lines, whitespace is preserved within a line. |
In text lines, whitespace is preserved within a line. |
Line 193 Many requests and macros support scaled widths for the |
|
Line 238 Many requests and macros support scaled widths for the |
|
The syntax for a scaled width is |
The syntax for a scaled width is |
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , |
.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , |
where a decimal must be preceded or followed by at least one digit. |
where a decimal must be preceded or followed by at least one digit. |
Negative numbers, while accepted, are truncated to zero. |
|
.Pp |
.Pp |
The following scaling units are accepted: |
The following scaling units are accepted: |
.Pp |
.Pp |
|
|
.It i |
.It i |
inch |
inch |
.It P |
.It P |
pica (~1/6 inch) |
pica (1/6 inch) |
.It p |
.It p |
point (~1/72 inch) |
point (1/72 inch) |
.It f |
.It f |
scale |
scale |
.Sq u |
.Sq u |
|
|
.It u |
.It u |
default horizontal span for the terminal |
default horizontal span for the terminal |
.It M |
.It M |
mini-em (~1/100 em) |
mini-em (1/100 em) |
.El |
.El |
.Pp |
.Pp |
Using anything other than |
Using anything other than |
Line 597 macros, whichever applies to the document in question. |
|
Line 641 macros, whichever applies to the document in question. |
|
.Pp |
.Pp |
Specifying a custom |
Specifying a custom |
.Ar endmacro |
.Ar endmacro |
macro works in the same way as for |
works in the same way as for |
.Ic \&ig ; |
.Ic \&ig ; |
namely, the call to |
namely, the call to |
.Sq Pf . Ar endmacro |
.Sq Pf . Ar endmacro |
Line 864 This is a Heirloom extension and currently ignored. |
|
Line 908 This is a Heirloom extension and currently ignored. |
|
Enable or disable an OpenType feature. |
Enable or disable an OpenType feature. |
This is a Heirloom extension and currently ignored. |
This is a Heirloom extension and currently ignored. |
.It Ic \&fi |
.It Ic \&fi |
Switch to fill mode. |
Break the output line and switch to fill mode, |
See |
which is active by default but can be ended with the |
.Xr man 7 . |
.Ic \&nf |
Ignored in |
request. |
.Xr mdoc 7 . |
In fill mode, input from subsequent input lines is added to |
|
the same output line until the next word no longer fits, |
|
at which point the output line is broken. |
|
This request is implied by the |
|
.Xr mdoc 7 |
|
.Ic \&Sh |
|
macro and by the |
|
.Xr man 7 |
|
.Ic \&SH , |
|
.Ic \&SS , |
|
and |
|
.Ic \&EE |
|
macros. |
.It Ic \&fkern Ar font minkern |
.It Ic \&fkern Ar font minkern |
Control the use of kerning tables for a font. |
Control the use of kerning tables for a font. |
This is a Heirloom extension and currently ignored. |
This is a Heirloom extension and currently ignored. |
Line 894 This is a Heirloom extension and currently ignored. |
|
Line 950 This is a Heirloom extension and currently ignored. |
|
Conditionally define a special font. |
Conditionally define a special font. |
This is a groff extension and currently ignored. |
This is a groff extension and currently ignored. |
.It Ic \&ft Op Ar font |
.It Ic \&ft Op Ar font |
Change the font. |
Change the font; see |
The following |
.Sx Font Selection . |
|
The |
.Ar font |
.Ar font |
arguments are supported: |
argument defaults to |
.Bl -tag -width 4n -offset indent |
.Cm P . |
.It Cm B , BI , CB , 3 , 4 |
|
switches to |
|
.Sy bold |
|
font |
|
.It Cm I , CI , 2 |
|
switches to |
|
.Em underlined |
|
font |
|
.It Cm R , CR , CW , 1 |
|
switches to normal font |
|
.It Cm P No "or no argument" |
|
switches back to the previous font |
|
.El |
|
.Pp |
|
This request takes effect only locally and may be overridden |
|
by macros and escape sequences. |
|
.It Ic \&ftr Ar newname Op Ar oldname |
.It Ic \&ftr Ar newname Op Ar oldname |
Translate font name. |
Translate font name. |
This is a groff extension and currently ignored. |
This is a groff extension and currently ignored. |
Line 1318 Declare the need for the specified minimum vertical sp |
|
Line 1359 Declare the need for the specified minimum vertical sp |
|
before the next trap or the bottom of the page. |
before the next trap or the bottom of the page. |
Currently ignored. |
Currently ignored. |
.It Ic \&nf |
.It Ic \&nf |
Switch to no-fill mode. |
Break the output line and switch to no-fill mode. |
See |
Subsequent input lines are kept together on the same output line |
.Xr man 7 . |
even when exceeding the right margin, |
Ignored by |
and line breaks in subsequent input cause output line breaks. |
.Xr mdoc 7 . |
This request is implied by the |
|
.Xr mdoc 7 |
|
.Ic \&Bd Fl unfilled |
|
and |
|
.Ic \&Bd Fl literal |
|
macros and by the |
|
.Xr man 7 |
|
.Ic \&EX |
|
macro. |
|
The |
|
.Ic \&fi |
|
request switches back to the default fill mode. |
.It Ic \&nh |
.It Ic \&nh |
Turn off automatic hyphenation mode. |
Turn off automatic hyphenation mode. |
Currently ignored. |
Currently ignored. |
|
|
.Xr mandoc 1 |
.Xr mandoc 1 |
.Nm |
.Nm |
parser recognises the following escape sequences. |
parser recognises the following escape sequences. |
Note that the |
|
.Nm |
|
language defines more escape sequences not implemented in |
|
.Xr mandoc 1 . |
|
In |
In |
.Xr mdoc 7 |
.Xr mdoc 7 |
and |
and |
Line 1834 described in the |
|
Line 1882 described in the |
|
.Sx LANGUAGE SYNTAX |
.Sx LANGUAGE SYNTAX |
section above. |
section above. |
.Pp |
.Pp |
In |
A backslash followed by any character not listed here |
.Xr mandoc 1 , |
|
a backslash followed by any character not listed here |
|
simply prints that character itself. |
simply prints that character itself. |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
.It Ic \e<newline> |
.It Ic \e<newline> |
Line 1847 on both lines together as if it were on a single input |
|
Line 1893 on both lines together as if it were on a single input |
|
The escape sequence backslash-space |
The escape sequence backslash-space |
.Pq Sq \e\ \& |
.Pq Sq \e\ \& |
is an unpaddable space-sized non-breaking space character; see |
is an unpaddable space-sized non-breaking space character; see |
.Sx Whitespace . |
.Sx Whitespace |
|
and |
|
.Xr mandoc_char 7 . |
|
.It Ic \e! |
|
Embed text up to and including the end of the input line into the |
|
current diversion or into intermediate output without interpreting |
|
requests, macros, and escapes. |
|
Currently unsupported. |
.It Ic \e\(dq |
.It Ic \e\(dq |
The rest of the input line is treated as |
The rest of the input line is treated as |
.Sx Comments . |
.Sx Comments . |
Line 1864 Macro argument expansion, see |
|
Line 1917 Macro argument expansion, see |
|
Hyphenation allowed at this point of the word; ignored by |
Hyphenation allowed at this point of the word; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.It Ic \e& |
.It Ic \e& |
Non-printing zero-width character; see |
Non-printing zero-width character, |
.Sx Whitespace . |
often used for various kinds of escaping; see |
|
.Sx Whitespace , |
|
.Xr mandoc_char 7 , |
|
and the |
|
.Dq MACRO SYNTAX |
|
and |
|
.Dq Delimiters |
|
sections in |
|
.Xr mdoc 7 . |
.It Ic \e\(aq |
.It Ic \e\(aq |
Acute accent special character; use |
Acute accent special character; use |
.Ic \e(aa |
.Ic \e(aa |
|
|
.Sx Special Characters |
.Sx Special Characters |
with two-letter names, see |
with two-letter names, see |
.Xr mandoc_char 7 . |
.Xr mandoc_char 7 . |
|
.It Ic \e) |
|
Zero-width space transparent to end-of-sentence detection; |
|
ignored by |
|
.Xr mandoc 1 . |
.It Ic \e*[ Ns Ar name Ns Ic \&] |
.It Ic \e*[ Ns Ar name Ns Ic \&] |
Interpolate the string with the |
Interpolate the string with the |
.Ar name . |
.Ar name . |
Line 1907 Left italic correction (groff extension); ignored by |
|
Line 1972 Left italic correction (groff extension); ignored by |
|
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.It Ic \e- |
.It Ic \e- |
Special character |
Special character |
.Dq mathematical minus sign . |
.Dq mathematical minus sign ; |
|
see |
|
.Xr mandoc_char 7 |
|
for details. |
.It Ic \e/ |
.It Ic \e/ |
Right italic correction (groff extension); ignored by |
Right italic correction (groff extension); ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
|
.It Ic \e: |
|
Breaking the line is allowed at this point of the word |
|
without inserting a hyphen. |
|
.It Ic \e? |
|
Embed the text up to the next |
|
.Ic \e? |
|
into the current diversion without interpreting requests, macros, |
|
and escapes. |
|
This is a groff extension and currently unsupported. |
.It Ic \e[ Ns Ar name Ns Ic \&] |
.It Ic \e[ Ns Ar name Ns Ic \&] |
.Sx Special Characters |
.Sx Special Characters |
with names of arbitrary length, see |
with names of arbitrary length, see |
Line 1918 with names of arbitrary length, see |
|
Line 1995 with names of arbitrary length, see |
|
.It Ic \e^ |
.It Ic \e^ |
One-twelfth em half-narrow space character, effectively zero-width in |
One-twelfth em half-narrow space character, effectively zero-width in |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
|
.It Ic \e_ |
|
Underline special character; use |
|
.Ic \e(ul |
|
instead. |
.It Ic \e` |
.It Ic \e` |
Grave accent special character; use |
Grave accent special character; use |
.Ic \e(ga |
.Ic \e(ga |
Line 1938 Digit width space character. |
|
Line 2019 Digit width space character. |
|
.It Ic \eA\(aq Ns Ar string Ns Ic \(aq |
.It Ic \eA\(aq Ns Ar string Ns Ic \(aq |
Anchor definition; ignored by |
Anchor definition; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
|
.It Ic \ea |
|
Leader character; ignored by |
|
.Xr mandoc 1 . |
.It Ic \eB\(aq Ns Ar string Ns Ic \(aq |
.It Ic \eB\(aq Ns Ar string Ns Ic \(aq |
Interpolate |
Interpolate |
.Sq 1 |
.Sq 1 |
|
|
.Ar string |
.Ar string |
conforms to the syntax of |
conforms to the syntax of |
.Sx Numerical expressions |
.Sx Numerical expressions |
explained above and |
explained above or |
.Sq 0 |
.Sq 0 |
otherwise. |
otherwise. |
.It Ic \eb\(aq Ns Ar string Ns Ic \(aq |
.It Ic \eb\(aq Ns Ar string Ns Ic \(aq |
Line 1965 Draw graphics function; ignored by |
|
Line 2049 Draw graphics function; ignored by |
|
.It Ic \ed |
.It Ic \ed |
Move down by half a line; ignored by |
Move down by half a line; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
|
.It Ic \eE |
|
Escape character intended to not be interpreted in copy mode. |
|
In |
|
.Xr mandoc 1 , |
|
it currently does the same as |
|
.Ic \e |
|
itself. |
.It Ic \ee |
.It Ic \ee |
Backslash special character. |
Backslash special character. |
.It Ic \eF[ Ns Ar name Ns Ic \&] |
.It Ic \eF[ Ns Ar name Ns Ic \&] |
|
|
Switch to the font |
Switch to the font |
.Ar name , |
.Ar name , |
see |
see |
.Sx Text Decoration . |
.Sx Font Selection . |
For short names, there are variants |
For short names, there are variants |
.Ic \ef Ns Ar c |
.Ic \ef Ns Ar c |
and |
and |
.Ic \ef( Ns Ar cc . |
.Ic \ef( Ns Ar cc . |
|
An empty name |
|
.Ic \ef[] |
|
defaults to |
|
.Ic \efP . |
.It Ic \eg[ Ns Ar name Ns Ic \&] |
.It Ic \eg[ Ns Ar name Ns Ic \&] |
Interpolate the format of a number register; ignored by |
Interpolate the format of a number register; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
Line 2046 the register is first incremented or decremented by th |
|
Line 2141 the register is first incremented or decremented by th |
|
that was specified in the relevant |
that was specified in the relevant |
.Ic \&nr |
.Ic \&nr |
request, and the changed value is interpolated. |
request, and the changed value is interpolated. |
|
.It Ic \eO Ns Ar digit , Ic \eO[5 Ns arguments Ns Ic \&] |
|
Suppress output. |
|
This is a groff extension and currently unsupported. |
|
With an argument of |
|
.Ic 1 , 2 , 3 , |
|
or |
|
.Ic 4 , |
|
it is ignored. |
.It Ic \eo\(aq Ns Ar string Ns Ic \(aq |
.It Ic \eo\(aq Ns Ar string Ns Ic \(aq |
Overstrike, writing all the characters contained in the |
Overstrike, writing all the characters contained in the |
.Ar string |
.Ar string |
Line 2057 Break the output line at the end of the current word. |
|
Line 2160 Break the output line at the end of the current word. |
|
.It Ic \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns Ic \(aq |
.It Ic \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns Ic \(aq |
Set number register; ignored by |
Set number register; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
|
.It Ic \er |
|
Move up by one line; ignored by |
|
.Xr mandoc 1 . |
.It Ic \eS\(aq Ns Ar number Ns Ic \(aq |
.It Ic \eS\(aq Ns Ar number Ns Ic \(aq |
Slant output; ignored by |
Slant output; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
|
|
.Xr mandoc 1 |
.Xr mandoc 1 |
implementation of the |
implementation of the |
.Nm |
.Nm |
language is intentionally incomplete. |
language is incomplete. |
Unimplemented features include: |
Major unimplemented features include: |
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
Line 2135 never reads or writes external files except via |
|
Line 2241 never reads or writes external files except via |
|
requests with safe relative paths. |
requests with safe relative paths. |
.It |
.It |
There is no automatic hyphenation, no adjustment to the right margin, |
There is no automatic hyphenation, no adjustment to the right margin, |
and no centering; the output is always set flush-left. |
and very limited support for centering; the output is always set flush-left. |
.It |
.It |
Support for setting tabulator positions |
Support for setting tabulator and leader characters is missing, |
and tabulator and leader characters is missing, |
|
and support for manually changing indentation is limited. |
and support for manually changing indentation is limited. |
.It |
.It |
The |
The |
|
|
.It |
.It |
Width measurements are implemented in a crude way |
Width measurements are implemented in a crude way |
and often yield wrong results. |
and often yield wrong results. |
Explicit movement requests and escapes are ignored. |
Support for explicit movement requests and escapes is limited. |
.It |
.It |
There is no concept of output pages, no support for floats, |
There is no concept of output pages, no support for floats, |
graphics drawing, and picture inclusion; |
graphics drawing, and picture inclusion; |
terminal output is always continuous. |
terminal output is always continuous. |
.It |
.It |
Requests regarding color, font families, and glyph manipulation |
Requests regarding color, font families, font sizes, |
are ignored. |
and glyph manipulation are ignored. |
Font support is very limited. |
Font support is very limited. |
Kerning is not implemented, and no ligatures are produced. |
Kerning is not implemented, and no ligatures are produced. |
.It |
.It |
|
|
.Qq \(aq |
.Qq \(aq |
macro control character does not suppress output line breaks. |
macro control character does not suppress output line breaks. |
.It |
.It |
Diversions are not implemented, |
Diversions and environments are not implemented, |
and support for traps is very incomplete. |
and support for traps is very incomplete. |
|
.It |
|
Use of macros is not supported inside |
|
.Xr tbl 7 |
|
code. |
.El |
.El |
.Pp |
.Pp |
The special semantics of the |
The special semantics of the |