Wrap .St content in a <span class="St">.

[mandoc.git] / roff.7

diff --git a/roff.7 b/roff.7
index b50d8f746268e454b2f44aadaed14b5e56c9eb84..114f63eddd20dc096e3e077f1ccc34b08e47ebb6 100644 (file)
--- a/roff.7
+++ b/roff.7
@@ -1,7 +1,7 @@
-.\"    $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, 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
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" 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
 .Dt ROFF 7
 .Os
 .Sh NAME


@@ -665,6 +665,8 @@ produces
 .D1 \efI\e^XtFree\e^\efP.
 .Pp
 in the input stream, and thus in the output: \fI\^XtFree\^\fP.
 .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
 .Pp
 Since macros and user-defined strings share a common string table,
 defining a macro


@@ -1003,7 +1005,7 @@ This is a groff extension and currently ignored.
 .Ss \&hypp
 Define hyphenation penalties.
 This is a Heirloom extension and currently ignored.
 .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
 Set hyphenation space.
 This is a groff extension and currently ignored.
 .Ss \&ie


@@ -1057,8 +1059,6 @@ If the first character of COND is
 .Pq string defined ,
 .Sq e
 .Pq even page ,
 .Pq string defined ,
 .Sq e
 .Pq even page ,

-.Sq r
-.Pq register accessed ,

 .Sq t
 .Pq troff mode ,
 or
 .Sq t
 .Pq troff mode ,
 or


@@ -1066,6 +1066,11 @@ or
 .Pq vroff mode ,
 COND evaluates to false.
 .It
 .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
 If COND starts with a parenthesis or with an optionally signed
 integer number, it is evaluated according to the rules of
 .Sx Numerical expressions


@@ -1196,13 +1201,18 @@ This is a Heirloom extension and currently unsupported.
 Set an input line trap.
 Its syntax is as follows:
 .Pp
 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
 .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.
 .Ss \&itc
 Set an input line trap, not counting lines ending with \ec.
 Currently unsupported.


@@ -1318,7 +1328,7 @@ Switch to no-fill mode.
 See
 .Xr man 7 .
 Ignored by
 See
 .Xr man 7 .
 Ignored by

-.Xr mdoc 7.
+.Xr mdoc 7 .

 .Ss \&nh
 Turn off automatic hyphenation mode.
 Currently ignored.
 .Ss \&nh
 Turn off automatic hyphenation mode.
 Currently ignored.


@@ -1332,7 +1342,7 @@ Currently unsupported.
 Temporarily turn off line numbering.
 Currently unsupported.
 .Ss \&nop
 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 \&nr
 Define or change a register.


@@ -1439,7 +1449,7 @@ Retrieve the bounding box of a PostScript file.
 Currently unsupported.
 .Ss \&pshape
 Set a special shape for the current paragraph.
 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 \&pso
 Include output of a shell command.
 Ignored because insecure.


@@ -1552,7 +1562,7 @@ Currently ignored.
 .Ss \&ss
 Set space character size.
 Currently ignored.
 .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
 Associate style with a font position.
 This is a groff extension and currently ignored.
 .Ss \&substring


@@ -1572,9 +1582,9 @@ See
 .Ss \&ta
 Set tab stops.
 Takes an arbitrary number of arguments.
 .Ss \&ta
 Set tab stops.
 Takes an arbitrary number of arguments.

-Currently ignored.
+Currently unsupported.

 .Ss \&tc
 .Ss \&tc

-Change tab repetion character.
+Change tab repetition character.

 Currently unsupported.
 .Ss \&TE
 End a table context.
 Currently unsupported.
 .Ss \&TE
 End a table context.


@@ -1582,7 +1592,7 @@ See
 .Sx \&TS .
 .Ss \&ti
 Temporary indent.
 .Sx \&TS .
 .Ss \&ti
 Temporary indent.

-Currently ignored.
+Currently unsupported.

 .Ss \&tkf
 Enable track kerning for a font.
 Currently ignored.
 .Ss \&tkf
 Enable track kerning for a font.
 Currently ignored.


@@ -1674,7 +1684,7 @@ Notify on change of string or macro.
 This is a Heirloom extension and currently ignored.
 .Ss \&watchlength
 On change, report the contents of macros and strings
 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.
 This is a Heirloom extension and currently ignored.
 .Ss \&watchn
 Notify on change of register.


@@ -1715,6 +1725,14 @@ prefixed by an optional sign
 .Sq +
 or
 .Sq - .
 .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:
 .Pp
 The following binary operators are implemented.
 Unless otherwise stated, they behave as in the C language:


@@ -1761,7 +1779,7 @@ minimum (not available in C)
 maximum (not available in C)
 .El
 .Pp
 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
 except when subexpressions are enclosed in parantheses.
 Inside parentheses, whitespace is ignored.
 .Sh ESCAPE SEQUENCE REFERENCE


@@ -1821,9 +1839,15 @@ For short names, there are variants
 .No \e* Ns Ar c
 and
 .No \e*( Ns Ar cc .
 .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-
 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
 .Ss \e[ Ns Ar name ]
 .Sx Special Characters
 with names of arbitrary length, see


@@ -1948,10 +1972,11 @@ For short names, there are variants
 and
 .No \en( Ns Ar cc .
 .Ss \eo\(aq Ns Ar string Ns \(aq
 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 .
 .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
 Set number register; ignored by
 .Xr mandoc 1 .


@@ -2014,55 +2039,68 @@ Print
 with zero width and height; ignored by
 .Xr mandoc 1 .
 .Ss \ez
 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
 .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
-.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
 .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.
 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
 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
 .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
 .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
 .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
 .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 ,
 .Sh SEE ALSO
 .Xr mandoc 1 ,
 .Xr eqn 7 ,