version 1.106, 2018/10/04 15:16:23 |
version 1.109, 2018/12/16 00:17:02 |
|
|
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, it only has 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 135 One-letter backslash escape. |
|
Line 132 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 209 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 237 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 |
Line 894 This is a Heirloom extension and currently ignored. |
|
Line 937 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 1848 The escape sequence backslash-space |
|
Line 1876 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 . |
|
.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 . |
|
|
.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 1911 Special character |
|
Line 1948 Special character |
|
.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 1964 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 1988 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 |
Line 1965 Draw graphics function; ignored by |
|
Line 2018 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 does the same as |
|
.Ic \e |
|
itself for now. |
.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 2110 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 2129 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 2210 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 |