Avoid warning "unused variable" when compiling without HAVE_WCHAR.

[mandoc.git] / roff.7

diff --git a/roff.7 b/roff.7
index c8c37cc03070f279c30febbb363470b746351a64..127504f80bf83884889d7a94cdddb1b0074c2e61 100644 (file)
--- a/roff.7
+++ b/roff.7
@@ -1,4 +1,4 @@
-.\"    $Id: roff.7,v 1.65 2015/01/21 20:33:25 schwarze Exp $
+.\"    $Id: roff.7,v 1.72 2015/05/31 23:13: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, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010, 2011, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org>


@@ -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 21 2015 $
+.Dd $Mdocdate: May 31 2015 $

 .Dt ROFF 7
 .Os
 .Sh NAME
 .Dt ROFF 7
 .Os
 .Sh NAME


@@ -1057,8 +1057,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 +1064,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 evalutes 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 +1199,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.


@@ -1439,7 +1447,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.


@@ -1572,7 +1580,7 @@ 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
 Change tab repetion character.
 Currently unsupported.
 .Ss \&tc
 Change tab repetion character.
 Currently unsupported.


@@ -1582,7 +1590,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.


@@ -1715,6 +1723,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:


@@ -1948,7 +1964,7 @@ 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, that is, write all the characters contained in the
+Overstrike, writing all the characters contained in the

 .Ar string
 to the same output position.
 In terminal and HTML output modes,
 .Ar string
 to the same output position.
 In terminal and HTML output modes,


@@ -2015,55 +2031,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 ,