-.\" $Id: roff.7,v 1.63 2015/01/20 21:16:51 schwarze Exp $
+.\" $Id: roff.7,v 1.75 2015/09/24 18:41:22 schwarze Exp $
.\"
.\" 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
.\" purpose with or without fee is hereby granted, provided that the above
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: January 20 2015 $
+.Dd $Mdocdate: September 24 2015 $
.Dt ROFF 7
.Os
.Sh NAME
.D1 \efI\e^XtFree\e^\efP.
.Pp
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
Since macros and user-defined strings share a common string table,
defining a macro
.Ss \&hypp
Define hyphenation penalties.
This is a Heirloom extension and currently ignored.
-.Ss \&hys
+.Ss \&hys
Set hyphenation space.
This is a groff extension and currently ignored.
.Ss \&ie
.Pq string defined ,
.Sq e
.Pq even page ,
-.Sq r
-.Pq register accessed ,
.Sq t
.Pq troff mode ,
or
.Pq vroff mode ,
COND evaluates to false.
.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
integer number, it is evaluated according to the rules of
.Sx Numerical expressions
Set an input line trap.
Its syntax is as follows:
.Pp
-.D1 Pf . Cm it Ar number macro
+.D1 Pf . Cm it Ar expression macro
.Pp
The named
.Ar macro
-will be invoked after processing the specified
-.Ar number
-of input text lines.
+will be invoked after processing the number of input text lines
+specified by the numerical
+.Ar expression .
+While evaluating the
+.Ar expression ,
+the unit suffixes described below
+.Sx Scaling Widths
+are ignored.
.Ss \&itc
Set an input line trap, not counting lines ending with \ec.
Currently unsupported.
See
.Xr man 7 .
Ignored by
-.Xr mdoc 7.
+.Xr mdoc 7 .
.Ss \&nh
Turn off automatic hyphenation mode.
Currently ignored.
Temporarily turn off line numbering.
Currently unsupported.
.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.
.Ss \&nr
Define or change a register.
Currently unsupported.
.Ss \&pshape
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
Include output of a shell command.
Ignored because insecure.
.Ss \&ss
Set space character size.
Currently ignored.
-.Ss \&sty
+.Ss \&sty
Associate style with a font position.
This is a groff extension and currently ignored.
.Ss \&substring
.Ss \&ta
Set tab stops.
Takes an arbitrary number of arguments.
-Currently ignored.
+Currently unsupported.
.Ss \&tc
-Change tab repetion character.
+Change tab repetition character.
Currently unsupported.
.Ss \&TE
End a table context.
.Sx \&TS .
.Ss \&ti
Temporary indent.
-Currently ignored.
+Currently unsupported.
.Ss \&tkf
Enable track kerning for a font.
Currently ignored.
This is a Heirloom extension and currently ignored.
.Ss \&watchlength
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.
.Ss \&watchn
Notify on change of register.
.Sq +
or
.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
The following binary operators are implemented.
Unless otherwise stated, they behave as in the C language:
maximum (not available in C)
.El
.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.
Inside parentheses, whitespace is ignored.
.Sh ESCAPE SEQUENCE REFERENCE
.No \e* Ns Ar c
and
.No \e*( Ns Ar cc .
+.Ss \e,
+Left italic correction (groff extension); ignored by
+.Xr mandoc 1 .
.Ss \e-
Special character
.Dq mathematical minus sign .
+.Ss \e/
+Right italic correction (groff extension); ignored by
+.Xr mandoc 1 .
.Ss \e[ Ns Ar name ]
.Sx Special Characters
with names of arbitrary length, see
and
.No \en( Ns Ar cc .
.Ss \eo\(aq Ns Ar string Ns \(aq
-Overstrike
-.Ar string ;
-ignored by
-.Xr mandoc 1 .
+Overstrike, writing all the characters contained in the
+.Ar string
+to the same output position.
+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
Set number register; ignored by
.Xr mandoc 1 .
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.
+Output the next character without advancing the cursor position.
.Sh COMPATIBILITY
-This section documents compatibility between mandoc and other
+The
+.Xr mandoc 1
+implementation of the
.Nm
-implementations, at this time limited to GNU troff
-.Pq Qq groff .
-The term
-.Qq historic groff
-refers to groff version 1.15.
+language is intentionally incomplete.
+Unimplemented features include:
.Pp
.Bl -dash -compact
.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
.Sq u
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.
.It
-In mandoc, the
-.Sx \&EQ ,
-.Sx \&TE ,
-.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.
+Width measurements are implemented in a crude way
+and often yield wrong results.
+Explicit movement requests and escapes are ignored.
.It
-The
-.Cm nS
-register is only compatible with OpenBSD's groff-1.15.
+There is no concept of output pages, no support for floats,
+graphics drawing, and picture inclusion;
+terminal output is always continuous.
.It
-Historic groff did not accept white-space before a custom
-.Ar end
-macro for the
-.Sx \&ig
-request.
+Requests regarding color, font families, and glyph manipulation
+are ignored.
+Font support is very limited.
+Kerning is not implemented, and no ligatures are produced.
.It
The
-.Sx \&if
-and family would print funny white-spaces with historic groff when
-using the next-line syntax.
+.Qq \(aq
+macro control character does not suppress output line breaks.
+.It
+Diversions are not implemented,
+and support for traps is very incomplete.
+.It
+While recursion is supported,
+.Sx \&while
+loops are not.
.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
.Xr mandoc 1 ,
.Xr eqn 7 ,
git.ckatri.com / mandoc.git / blobdiff