version 1.81, 2017/06/01 19:05:37 |
version 1.99, 2018/08/16 14:07:11 |
|
|
.\" $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,2011,2013-2015,2017 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010-2018 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 |
Line 86 character, and, in certain circumstances, the tab char |
|
Line 86 character, and, in certain circumstances, the tab char |
|
The backslash character |
The backslash character |
.Sq \e |
.Sq \e |
indicates the start of an escape sequence, used for example for |
indicates the start of an escape sequence, used for example for |
.Sx Comments , |
.Sx Comments |
.Sx Special Characters , |
|
.Sx Predefined Strings , |
|
and |
and |
user-defined strings defined using the |
.Sx Special Characters . |
.Sx ds |
|
request. |
|
For a listing of escape sequences, consult the |
For a listing of escape sequences, consult the |
.Sx ESCAPE SEQUENCE REFERENCE |
.Sx ESCAPE SEQUENCE REFERENCE |
below. |
below. |
Line 169 Text decoration is |
|
Line 165 Text decoration is |
|
recommended for |
recommended for |
.Xr mdoc 7 , |
.Xr mdoc 7 , |
which encourages semantic annotation. |
which encourages semantic annotation. |
.Ss Predefined Strings |
|
Predefined strings, like |
|
.Sx Special Characters , |
|
mark special output glyphs. |
|
Predefined strings are escaped with the slash-asterisk, |
|
.Sq \e* : |
|
single-character |
|
.Sq \e*X , |
|
two-character |
|
.Sq \e*(XX , |
|
and N-character |
|
.Sq \e*[N] . |
|
.Pp |
|
Examples: |
|
.Bl -tag -width Ds -offset indent -compact |
|
.It Li \e*(Am |
|
Two-letter ampersand predefined string. |
|
.It Li \e*q |
|
One-letter double-quote predefined string. |
|
.El |
|
.Pp |
|
Predefined strings are not recommended for use, |
|
as they differ across implementations. |
|
Those supported by |
|
.Xr mandoc 1 |
|
are listed in |
|
.Xr mandoc_char 7 . |
|
Manuals using these predefined strings are almost certainly not portable. |
|
.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 206 Unescaped trailing spaces are stripped from text line |
|
Line 174 Unescaped trailing spaces are stripped from text line |
|
literal context. |
literal context. |
In general, trailing whitespace on any input line is discouraged for |
In general, trailing whitespace on any input line is discouraged for |
reasons of portability. |
reasons of portability. |
In the rare case that a blank character is needed at the end of an |
In the rare case that a space character is needed at the end of an |
input line, it may be forced by |
input line, it may be forced by |
.Sq \e\ \e& . |
.Sq \e\ \e& . |
.Pp |
.Pp |
Line 412 Create an alias for a number register. |
|
Line 380 Create an alias for a number register. |
|
Currently unsupported. |
Currently unsupported. |
.It Ic \&als Ar newname oldname |
.It Ic \&als Ar newname oldname |
Create an alias for a request, string, macro, or diversion. |
Create an alias for a request, string, macro, or diversion. |
Currently unsupported. |
|
.It Ic \&am Ar macroname Op Ar endmacro |
.It Ic \&am Ar macroname Op Ar endmacro |
Append to a macro definition. |
Append to a macro definition. |
The syntax of this request is the same as that of |
The syntax of this request is the same as that of |
Line 527 Trailing characters are ignored. |
|
Line 494 Trailing characters are ignored. |
|
Center the next |
Center the next |
.Ar N |
.Ar N |
input lines without filling. |
input lines without filling. |
Currently ignored. |
.Ar N |
|
defaults to 1. |
|
An argument of 0 or less ends centering. |
|
Currently, high level macros abort centering. |
.It Ic \&cf Ar filename |
.It Ic \&cf Ar filename |
Output the contents of a file. |
Output the contents of a file. |
Ignored because insecure. |
Ignored because insecure. |
|
|
.Pp |
.Pp |
in the input stream, and thus in the output: \fI\^XtFree\^\fP. |
in the input stream, and thus in the output: \fI\^XtFree\^\fP. |
Each occurrence of \e\e$* is replaced with all the arguments, |
Each occurrence of \e\e$* is replaced with all the arguments, |
joined together with single blank characters. |
joined together with single space characters. |
.Pp |
.Pp |
Since macros and user-defined strings share a common string table, |
Since macros and user-defined strings share a common string table, |
defining a macro |
defining a macro |
Line 808 This is a Heirloom extension and currently unsupported |
|
Line 778 This is a Heirloom extension and currently unsupported |
|
Set a trap within a diversion. |
Set a trap within a diversion. |
Currently unsupported. |
Currently unsupported. |
.It Ic \&ec Op Ar char |
.It Ic \&ec Op Ar char |
Change the escape character. |
Enable the escape mechanism and change the escape character. |
Currently unsupported. |
The |
|
.Ar char |
|
argument defaults to the backslash |
|
.Pq Sq \e . |
.It Ic \&ecr |
.It Ic \&ecr |
Restore the escape character. |
Restore the escape character. |
Currently unsupported. |
Currently unsupported. |
|
|
.Ic \&EQ . |
.Ic \&EQ . |
.It Ic \&eo |
.It Ic \&eo |
Disable the escape mechanism completely. |
Disable the escape mechanism completely. |
Currently unsupported. |
|
.It Ic \&EP |
.It Ic \&EP |
End a picture started by |
End a picture started by |
.Ic \&BP . |
.Ic \&BP . |
|
|
.Ar font |
.Ar font |
arguments are supported: |
arguments are supported: |
.Bl -tag -width 4n -offset indent |
.Bl -tag -width 4n -offset indent |
.It Cm B , BI , 3 , 4 |
.It Cm B , BI , CB , 3 , 4 |
switches to |
switches to |
.Sy bold |
.Sy bold |
font |
font |
.It Cm I , 2 |
.It Cm I , CI , 2 |
switches to |
switches to |
.Em underlined |
.Em underlined |
font |
font |
.It Cm R , CW , 1 |
.It Cm R , CR , CW , 1 |
switches to normal font |
switches to normal font |
.It Cm P No "or no argument" |
.It Cm P No "or no argument" |
switches back to the previous font |
switches back to the previous font |
Line 1040 If the first character of |
|
Line 1012 If the first character of |
|
is |
is |
.Sq c |
.Sq c |
.Pq character available , |
.Pq character available , |
.Sq d |
|
.Pq string defined , |
|
.Sq e |
.Sq e |
.Pq even page , |
.Pq even page , |
.Sq t |
.Sq t |
Line 1054 it evaluates to false. |
|
Line 1024 it evaluates to false. |
|
If the first character of |
If the first character of |
.Ar condition |
.Ar condition |
is |
is |
|
.Sq d , |
|
it evaluates to true if the rest of |
|
.Ar condition |
|
is the name of an existing user defined macro or string; |
|
otherwise, it evaluates to false. |
|
.It |
|
If the first character of |
|
.Ar condition |
|
is |
.Sq r , |
.Sq r , |
it evaluates to true if the rest of |
it evaluates to true if the rest of |
.Ar condition |
.Ar condition |
Line 1294 Set title line length. |
|
Line 1273 Set title line length. |
|
Currently ignored. |
Currently ignored. |
.It Ic \&mc Ar glyph Op Ar dist |
.It Ic \&mc Ar glyph Op Ar dist |
Print margin character in the right margin. |
Print margin character in the right margin. |
Currently ignored. |
The |
|
.Ar dist |
|
is currently ignored; instead, 1n is used. |
.It Ic \&mediasize Ar media |
.It Ic \&mediasize Ar media |
Set the device media size. |
Set the device media size. |
This is a Heirloom extension and currently ignored. |
This is a Heirloom extension and currently ignored. |
Line 1333 Currently unsupported. |
|
Line 1314 Currently unsupported. |
|
Temporarily turn off line numbering. |
Temporarily turn off line numbering. |
Currently unsupported. |
Currently unsupported. |
.It Ic \&nop Ar body |
.It Ic \&nop Ar body |
Execute the rest of the input line as a request or macro line. |
Execute the rest of the input line as a request, macro, or text line, |
Currently unsupported. |
skipping the |
.It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression |
.Ic \&nop |
|
request and any space characters immediately following it. |
|
This is mostly used to indent text lines inside macro definitions. |
|
.It Ic \&nr Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression Op Ar stepsize |
Define or change 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. |
|
|
If it is prefixed by a sign, the register will be |
If it is prefixed by a sign, the register will be |
incremented or decremented instead of assigned to. |
incremented or decremented instead of assigned to. |
.Pp |
.Pp |
|
The |
|
.Ar stepsize |
|
is used by the |
|
.Ic \en+ |
|
auto-increment feature. |
|
It remains unchanged when omitted while changing an existing register, |
|
and it defaults to 0 when defining a new register. |
|
.Pp |
The following |
The following |
.Ar register |
.Ar register |
is handled specially: |
is handled specially: |
Line 1428 Currently ignored. |
|
Line 1420 Currently ignored. |
|
Print all number registers on standard error output. |
Print all number registers on standard error output. |
Currently ignored. |
Currently ignored. |
.It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset |
.It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset |
Set horizontal page offset. |
Set a horizontal page offset. |
Currently ignored. |
If no argument is specified, the page offset is reverted to its |
|
previous value. |
|
If a sign is specified, the new page offset is calculated relative |
|
to the current one; otherwise, it is absolute. |
|
The argument follows the syntax of |
|
.Sx Scaling Widths |
|
and the default scaling unit is |
|
.Cm m . |
.It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size |
.It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size |
Change point size. |
Change point size. |
Currently ignored. |
Currently ignored. |
Line 1451 This is a groff extension and currently ignored. |
|
Line 1450 This is a groff extension and currently ignored. |
|
.It Ic \&rchar Ar glyph ... |
.It Ic \&rchar Ar glyph ... |
Remove glyph definitions. |
Remove glyph definitions. |
Currently unsupported. |
Currently unsupported. |
.It Ic \&rd Op Ar prompt Op Ar agument ... |
.It Ic \&rd Op Ar prompt Op Ar argument ... |
Read from standard input. |
Read from standard input. |
Currently ignored. |
Currently ignored. |
.It Ic \&recursionlimit Ar maxrec maxtail |
.It Ic \&recursionlimit Ar maxrec maxtail |
Line 1470 This is a Heirloom extension and currently ignored. |
|
Line 1469 This is a Heirloom extension and currently ignored. |
|
Justify the next |
Justify the next |
.Ar N |
.Ar N |
input lines to the right margin without filling. |
input lines to the right margin without filling. |
Currently ignored. |
.Ar N |
|
defaults to 1. |
|
An argument of 0 or less ends right adjustment. |
.It Ic \&rm Ar macroname |
.It Ic \&rm Ar macroname |
Remove a request, macro or string. |
Remove a request, macro or string. |
.It Ic \&rn Ar oldname newname |
.It Ic \&rn Ar oldname newname |
Rename a request, macro, diversion, or string. |
Rename a request, macro, diversion, or string. |
Currently unsupported. |
In |
|
.Xr mandoc 1 , |
|
user-defined macros, |
|
.Xr mdoc 7 |
|
and |
|
.Xr man 7 |
|
macros, and user-defined strings can be renamed, but renaming of |
|
predefined strings and of |
|
.Nm |
|
requests is not supported, and diversions are not implemented at all. |
.It Ic \&rnn Ar oldname newname |
.It Ic \&rnn Ar oldname newname |
Rename a number register. |
Rename a number register. |
Currently unsupported. |
Currently unsupported. |
Line 1767 logical and (corresponds to C |
|
Line 1777 logical and (corresponds to C |
|
.Ic && ) |
.Ic && ) |
.It Ic \&: |
.It Ic \&: |
logical or (corresponds to C |
logical or (corresponds to C |
.Ic \&|| ) |
.Ic || ) |
.It Ic <? |
.It Ic <? |
minimum (not available in C) |
minimum (not available in C) |
.It Ic >? |
.It Ic >? |
|
|
.Sx Special Characters |
.Sx Special Characters |
with two-letter names, see |
with two-letter names, see |
.Xr mandoc_char 7 . |
.Xr mandoc_char 7 . |
.Ss \e*[ Ns Ar name ] |
.Ss \e* Ns Bq Ar name |
Interpolate the string with the |
Interpolate the string with the |
.Ar name ; |
.Ar name . |
see |
|
.Sx Predefined Strings |
|
and |
|
.Sx ds . |
|
For short names, there are variants |
For short names, there are variants |
.No \e* Ns Ar c |
.No \e* Ns Ar c |
and |
and |
.No \e*( Ns Ar cc . |
.No \e*( Ns Ar cc . |
|
.Pp |
|
One string is predefined on the |
|
.Nm |
|
language level: \e*(.T expands to the name of the output device, |
|
for example ascii, utf8, ps, pdf, html, or markdown. |
|
.Pp |
|
Macro sets traditionally predefine additional strings which are not |
|
portable and differ across implementations. |
|
Those supported by |
|
.Xr mandoc 1 |
|
are listed in |
|
.Xr mandoc_char 7 . |
|
.Pp |
|
Strings can be defined, changed, and deleted with the |
|
.Ic \&ds , |
|
.Ic \&as , |
|
and |
|
.Ic \&rm |
|
requests. |
.Ss \e, |
.Ss \e, |
Left italic correction (groff extension); ignored by |
Left italic correction (groff extension); ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
Line 1843 Special character |
|
Line 1868 Special character |
|
.Ss \e/ |
.Ss \e/ |
Right italic correction (groff extension); ignored by |
Right italic correction (groff extension); ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.Ss \e[ Ns Ar name ] |
.Ss \e Ns Bq Ar name |
.Sx Special Characters |
.Sx Special Characters |
with names of arbitrary length, see |
with names of arbitrary length, see |
.Xr mandoc_char 7 . |
.Xr mandoc_char 7 . |
Line 1899 Move down by half a line; ignored by |
|
Line 1924 Move down by half a line; ignored by |
|
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.Ss \ee |
.Ss \ee |
Backslash special character. |
Backslash special character. |
.Ss \eF[ Ns Ar name ] |
.Ss \eF Ns Bq Ar name |
Switch font family (groff extension); ignored by |
Switch font family (groff extension); ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
For short names, there are variants |
For short names, there are variants |
.No \eF Ns Ar c |
.No \eF Ns Ar c |
and |
and |
.No \eF( Ns Ar cc . |
.No \eF( Ns Ar cc . |
.Ss \ef[ Ns Ar name ] |
.Ss \ef Ns Bq Ar name |
Switch to the font |
Switch to the font |
.Ar name , |
.Ar name , |
see |
see |
Line 1915 For short names, there are variants |
|
Line 1940 For short names, there are variants |
|
.No \ef Ns Ar c |
.No \ef Ns Ar c |
and |
and |
.No \ef( Ns Ar cc . |
.No \ef( Ns Ar cc . |
.Ss \eg[ Ns Ar name ] |
.Ss \eg Ns Bq Ar name |
Interpolate the format of a number register; ignored by |
Interpolate the format of a number register; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
For short names, there are variants |
For short names, there are variants |
|
|
.Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq |
.Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq |
Set the height of the current font; ignored by |
Set the height of the current font; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.Ss \eh\(aq Ns Ar width Ns \(aq |
.Ss \eh\(aq Ns Oo Cm \&| Oc Ns Ar width Ns \(aq |
Horizontal motion relative to the current position. |
Horizontal motion. |
|
If the vertical bar is given, the motion is relative to the current |
|
indentation. |
|
Otherwise, it is relative to the current position. |
The default scaling unit is |
The default scaling unit is |
.Cm m . |
.Cm m . |
.Ss \ek[ Ns Ar name ] |
.Ss \ek Ns Bq Ar name |
Mark horizontal input place in register; ignored by |
Mark horizontal input place in register; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
For short names, there are variants |
For short names, there are variants |
|
|
.Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq |
.Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq |
Vertical line drawing function; ignored by |
Vertical line drawing function; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq |
.Ss \el\(aq Ns Ar width Ns Oo Ar c Oc Ns \(aq |
Horizontal line drawing function; ignored by |
Draw a horizontal line of |
.Xr mandoc 1 . |
.Ar width |
.Ss \eM[ Ns Ar name ] |
using the glyph |
|
.Ar c . |
|
.Ss \eM Ns Bq Ar name |
Set fill (background) color (groff extension); ignored by |
Set fill (background) color (groff extension); ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
For short names, there are variants |
For short names, there are variants |
.No \eM Ns Ar c |
.No \eM Ns Ar c |
and |
and |
.No \eM( Ns Ar cc . |
.No \eM( Ns Ar cc . |
.Ss \em[ Ns Ar name ] |
.Ss \em Ns Bq Ar name |
Set glyph drawing color (groff extension); ignored by |
Set glyph drawing color (groff extension); ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
For short names, there are variants |
For short names, there are variants |
|
|
Character |
Character |
.Ar number |
.Ar number |
on the current font. |
on the current font. |
.Ss \en[ Ns Ar name ] |
.Ss \en Ns Oo +|- Oc Ns Bq Ar name |
Interpolate the number register |
Interpolate the number register |
.Ar name . |
.Ar name . |
For short names, there are variants |
For short names, there are variants |
.No \en Ns Ar c |
.No \en Ns Ar c |
and |
and |
.No \en( Ns Ar cc . |
.No \en( Ns Ar cc . |
|
If the optional sign is specified, |
|
the register is first incremented or decremented by the |
|
.Ar stepsize |
|
that was specified in the relevant |
|
.Ic \&nr |
|
request, and the changed value is interpolated. |
.Ss \eo\(aq Ns Ar string Ns \(aq |
.Ss \eo\(aq Ns Ar string Ns \(aq |
Overstrike, writing all the characters contained in the |
Overstrike, writing all the characters contained in the |
.Ar string |
.Ar string |
to the same output position. |
to the same output position. |
In terminal and HTML output modes, |
In terminal and HTML output modes, |
only the last one of the characters is visible. |
only the last one of the characters is visible. |
|
.Ss \ep |
|
Break the output line at the end of the current word. |
.Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq |
.Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq |
Set number register; ignored by |
Set number register; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
Line 1985 Change point size; ignored by |
|
Line 2023 Change point size; ignored by |
|
Alternative forms |
Alternative forms |
.No \es Ns Oo +|- Oc Ns Ar n , |
.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 \(aq Ns Ar number Ns \(aq , |
.No \es Ns [ Oo +|- Oc Ns Ar number ] , |
.No \es Ns Bq Oo +|- Oc Ns Ar number , |
and |
and |
.No \es Ns Oo +|- Oc Ns [ Ar number Ns ] |
.No \es Ns Oo +|- Oc Ns Bq Ar number |
are also parsed and ignored. |
are also parsed and ignored. |
.Ss \et |
.Ss \et |
Horizontal tab; ignored by |
Horizontal tab; ignored by |
Line 1995 Horizontal tab; ignored by |
|
Line 2033 Horizontal tab; ignored by |
|
.Ss \eu |
.Ss \eu |
Move up by half a line; ignored by |
Move up by half a line; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.Ss \eV[ Ns Ar name ] |
.Ss \eV Ns Bq Ar name |
Interpolate an environment variable; ignored by |
Interpolate an environment variable; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
For short names, there are variants |
For short names, there are variants |
Line 2022 as device control function; ignored in nroff mode and |
|
Line 2060 as device control function; ignored in nroff mode and |
|
.Ss \ex\(aq Ns Ar number Ns \(aq |
.Ss \ex\(aq Ns Ar number Ns \(aq |
Extra line space function; ignored by |
Extra line space function; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.Ss \eY[ Ns Ar name ] |
.Ss \eY Ns Bq Ar name |
Output a string as a device control function; ignored in nroff mode and by |
Output a string as a device control function; ignored in nroff mode and by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
For short names, there are variants |
For short names, there are variants |