version 1.64, 2015/01/20 22:45:07 |
version 1.78, 2017/05/05 15:54:59 |
|
|
.\" $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, 2014 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2010, 2011, 2013-2015 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 492 Define a frame and place a picture in it. |
|
Line 492 Define a frame and place a picture in it. |
|
This is a Heirloom extension and currently unsupported. |
This is a Heirloom extension and currently unsupported. |
.Ss \&br |
.Ss \&br |
Break the output line. |
Break the output line. |
See |
|
.Xr man 7 |
|
and |
|
.Xr mdoc 7 . |
|
.Ss \&break |
.Ss \&break |
Break out of a |
Break out of a |
.Sx \&while |
.Sx \&while |
|
|
.D1 \efI\e^XtFree\e^\efP. |
.D1 \efI\e^XtFree\e^\efP. |
.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, |
|
joined together with single blank 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 948 switches to normal font |
|
Line 946 switches to normal font |
|
switches back to the previous font |
switches back to the previous font |
.El |
.El |
.Pp |
.Pp |
This request takes effect only locally, may be overridden by macros |
This request takes effect only locally and may be overridden |
and escape sequences, and is only supported in |
by macros and escape sequences. |
.Xr man 7 |
|
for now. |
|
.Ss \&ftr |
.Ss \&ftr |
Translate font name. |
Translate font name. |
This is a groff extension and currently ignored. |
This is a groff extension and currently ignored. |
Line 1057 If the first character of COND is |
|
Line 1053 If the first character of COND is |
|
.Pq string defined , |
.Pq string defined , |
.Sq e |
.Sq e |
.Pq even page , |
.Pq even page , |
.Sq r |
|
.Pq register accessed , |
|
.Sq t |
.Sq t |
.Pq troff mode , |
.Pq troff mode , |
or |
or |
|
|
.Pq vroff mode , |
.Pq vroff mode , |
COND evaluates to false. |
COND evaluates to false. |
.It |
.It |
|
If the first character of COND is |
|
.Sq r , |
|
it evaluates to true if the rest of COND is the name of an existing |
|
number register; otherwise, it evaluates to false. |
|
.It |
If COND starts with a parenthesis or with an optionally signed |
If COND starts with a parenthesis or with an optionally signed |
integer number, it is evaluated according to the rules of |
integer number, it is evaluated according to the rules of |
.Sx Numerical expressions |
.Sx Numerical expressions |
Line 1196 This is a Heirloom extension and currently unsupported |
|
Line 1195 This is a Heirloom extension and currently unsupported |
|
Set an input line trap. |
Set an input line trap. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 Pf . Cm it Ar number macro |
.D1 Pf . Cm it Ar expression macro |
.Pp |
.Pp |
The named |
The named |
.Ar macro |
.Ar macro |
will be invoked after processing the specified |
will be invoked after processing the number of input text lines |
.Ar number |
specified by the numerical |
of input text lines. |
.Ar expression . |
|
While evaluating the |
|
.Ar expression , |
|
the unit suffixes described below |
|
.Sx Scaling Widths |
|
are ignored. |
.Ss \&itc |
.Ss \&itc |
Set an input line trap, not counting lines ending with \ec. |
Set an input line trap, not counting lines ending with \ec. |
Currently unsupported. |
Currently unsupported. |
Line 1332 Currently unsupported. |
|
Line 1336 Currently unsupported. |
|
Temporarily turn off line numbering. |
Temporarily turn off line numbering. |
Currently unsupported. |
Currently unsupported. |
.Ss \&nop |
.Ss \&nop |
Exexute the rest of the input line as a request or macro line. |
Execute the rest of the input line as a request or macro line. |
Currently unsupported. |
Currently unsupported. |
.Ss \&nr |
.Ss \&nr |
Define or change a register. |
Define or change a register. |
Line 1439 Retrieve the bounding box of a PostScript file. |
|
Line 1443 Retrieve the bounding box of a PostScript file. |
|
Currently unsupported. |
Currently unsupported. |
.Ss \&pshape |
.Ss \&pshape |
Set a special shape for the current paragraph. |
Set a special shape for the current paragraph. |
This is a Heirloom extension and currently ignored. |
This is a Heirloom extension and currently unsupported. |
.Ss \&pso |
.Ss \&pso |
Include output of a shell command. |
Include output of a shell command. |
Ignored because insecure. |
Ignored because insecure. |
Line 1540 is discouraged. |
|
Line 1544 is discouraged. |
|
Use |
Use |
.Xr ln 1 |
.Xr ln 1 |
instead. |
instead. |
|
.Ss \&sp |
|
Break the output line and emit vertical space. |
|
Its syntax is as follows: |
|
.Pp |
|
.D1 Pf \. Cm \&sp Op Ar height |
|
.Pp |
|
The argument follows the syntax of |
|
.Sx Scaling Widths |
|
and defaults to one blank line |
|
.Pq Li 1v . |
.Ss \&spacewidth |
.Ss \&spacewidth |
Set the space width from the font metrics file. |
Set the space width from the font metrics file. |
This is a Heirloom extension and currently ignored. |
This is a Heirloom extension and currently ignored. |
|
|
.Ss \&ta |
.Ss \&ta |
Set tab stops. |
Set tab stops. |
Takes an arbitrary number of arguments. |
Takes an arbitrary number of arguments. |
Currently ignored. |
Currently unsupported. |
.Ss \&tc |
.Ss \&tc |
Change tab repetion character. |
Change tab repetition character. |
Currently unsupported. |
Currently unsupported. |
.Ss \&TE |
.Ss \&TE |
End a table context. |
End a table context. |
|
|
.Sx \&TS . |
.Sx \&TS . |
.Ss \&ti |
.Ss \&ti |
Temporary indent. |
Temporary indent. |
Currently ignored. |
Currently unsupported. |
.Ss \&tkf |
.Ss \&tkf |
Enable track kerning for a font. |
Enable track kerning for a font. |
Currently ignored. |
Currently ignored. |
Line 1674 Notify on change of string or macro. |
|
Line 1688 Notify on change of string or macro. |
|
This is a Heirloom extension and currently ignored. |
This is a Heirloom extension and currently ignored. |
.Ss \&watchlength |
.Ss \&watchlength |
On change, report the contents of macros and strings |
On change, report the contents of macros and strings |
up to the sepcified length. |
up to the specified length. |
This is a Heirloom extension and currently ignored. |
This is a Heirloom extension and currently ignored. |
.Ss \&watchn |
.Ss \&watchn |
Notify on change of register. |
Notify on change of register. |
Line 1715 prefixed by an optional sign |
|
Line 1729 prefixed by an optional sign |
|
.Sq + |
.Sq + |
or |
or |
.Sq - . |
.Sq - . |
|
Each number may be followed by one optional scaling unit described below |
|
.Sx Scaling Widths . |
|
The following equations hold: |
|
.Bd -literal -offset indent |
|
1i = 6v = 6P = 10m = 10n = 72p = 1000M = 240u = 240 |
|
254c = 100i = 24000u = 24000 |
|
1f = 65536u = 65536 |
|
.Ed |
.Pp |
.Pp |
The following binary operators are implemented. |
The following binary operators are implemented. |
Unless otherwise stated, they behave as in the C language: |
Unless otherwise stated, they behave as in the C language: |
Line 1761 minimum (not available in C) |
|
Line 1783 minimum (not available in C) |
|
maximum (not available in C) |
maximum (not available in C) |
.El |
.El |
.Pp |
.Pp |
There is no concept of precendence; evaluation proceeds from left to right, |
There is no concept of precedence; evaluation proceeds from left to right, |
except when subexpressions are enclosed in parantheses. |
except when subexpressions are enclosed in parentheses. |
Inside parentheses, whitespace is ignored. |
Inside parentheses, whitespace is ignored. |
.Sh ESCAPE SEQUENCE REFERENCE |
.Sh ESCAPE SEQUENCE REFERENCE |
The |
The |
Line 1821 For short names, there are variants |
|
Line 1843 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 . |
|
.Ss \e, |
|
Left italic correction (groff extension); ignored by |
|
.Xr mandoc 1 . |
.Ss \e- |
.Ss \e- |
Special character |
Special character |
.Dq mathematical minus sign . |
.Dq mathematical minus sign . |
|
.Ss \e/ |
|
Right italic correction (groff extension); ignored by |
|
.Xr mandoc 1 . |
.Ss \e[ Ns Ar name ] |
.Ss \e[ Ns Ar name ] |
.Sx Special Characters |
.Sx Special Characters |
with names of arbitrary length, see |
with names of arbitrary length, see |
Line 1948 For short names, there are variants |
|
Line 1976 For short names, there are variants |
|
and |
and |
.No \en( Ns Ar cc . |
.No \en( Ns Ar cc . |
.Ss \eo\(aq Ns Ar string Ns \(aq |
.Ss \eo\(aq Ns Ar string Ns \(aq |
Overstrike |
Overstrike, writing all the characters contained in the |
.Ar string ; |
.Ar string |
ignored by |
to the same output position. |
.Xr mandoc 1 . |
In terminal and HTML output modes, |
|
only the last one of the characters is visible. |
.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 . |
|
|
with zero width and height; ignored by |
with zero width and height; ignored by |
.Xr mandoc 1 . |
.Xr mandoc 1 . |
.Ss \ez |
.Ss \ez |
Output the next character without advancing the cursor position; |
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 |
The |
|
.Xr mandoc 1 |
|
implementation of the |
.Nm |
.Nm |
implementations, at this time limited to GNU troff |
language is intentionally incomplete. |
.Pq Qq groff . |
Unimplemented features include: |
The term |
|
.Qq historic groff |
|
refers to groff version 1.15. |
|
.Pp |
.Pp |
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
|
For security reasons, |
|
.Xr mandoc 1 |
|
never reads or writes external files except via |
|
.Sx \&so |
|
requests with safe relative paths. |
|
.It |
|
There is no automatic hyphenation, no adjustment to the right margin, |
|
and no centering; the output is always set flush-left. |
|
.It |
|
Support for setting tabulator positions |
|
and tabulator and leader characters is missing, |
|
and support for manually changing indentation is limited. |
|
.It |
The |
The |
.Sq u |
.Sq u |
scaling unit is the default terminal unit. |
scaling unit is the default terminal unit. |
In traditional troff systems, this unit would change depending on the |
In traditional troff systems, this unit changes depending on the |
output media. |
output media. |
.It |
.It |
In mandoc, the |
Width measurements are implemented in a crude way |
.Sx \&EQ , |
and often yield wrong results. |
.Sx \&TE , |
Explicit movement requests and escapes are ignored. |
.Sx \&TS , |
|
and |
|
.Sx \&T& , |
|
macros are considered regular macros. |
|
In all other |
|
.Nm |
|
implementations, these are special macros that must be specified without |
|
spacing between the control character (which must be a period) and the |
|
macro name. |
|
.It |
.It |
The |
There is no concept of output pages, no support for floats, |
.Cm nS |
graphics drawing, and picture inclusion; |
register is only compatible with OpenBSD's groff-1.15. |
terminal output is always continuous. |
.It |
.It |
Historic groff did not accept white-space before a custom |
Requests regarding color, font families, and glyph manipulation |
.Ar end |
are ignored. |
macro for the |
Font support is very limited. |
.Sx \&ig |
Kerning is not implemented, and no ligatures are produced. |
request. |
|
.It |
.It |
The |
The |
.Sx \&if |
.Qq \(aq |
and family would print funny white-spaces with historic groff when |
macro control character does not suppress output line breaks. |
using the next-line syntax. |
.It |
|
Diversions are not implemented, |
|
and support for traps is very incomplete. |
|
.It |
|
While recursion is supported, |
|
.Sx \&while |
|
loops are not. |
.El |
.El |
|
.Pp |
|
The special semantics of the |
|
.Cm nS |
|
number register is an idiosyncracy of |
|
.Ox |
|
manuals and not supported by other |
|
.Xr mdoc 7 |
|
implementations. |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
.Xr eqn 7 , |
.Xr eqn 7 , |