Handle output encoding for unicode, numbered and named escape sequences

[mandoc.git] / roff.7

diff --git a/roff.7 b/roff.7
index 49ad11ee0ab4d490e35563c7c165dbdecd5132db..6ac48a7e2e9c20c297a19025c12d946ff2867c1a 100644 (file)
--- a/roff.7
+++ b/roff.7
@@ -1,4 +1,4 @@
-.\"    $Id: roff.7,v 1.49 2014/03/17 06:57:48 schwarze Exp $
+.\"    $Id: roff.7,v 1.58 2014/09/07 00:21:53 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: March 17 2014 $
+.Dd $Mdocdate: September 7 2014 $

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


@@ -239,8 +239,9 @@ pica (~1/6 inch)
 .It p
 point (~1/72 inch)
 .It f
 .It p
 point (~1/72 inch)
 .It f

-synonym for
+scale

 .Sq u
 .Sq u

+by 65536

 .It v
 default vertical span
 .It m
 .It v
 default vertical span
 .It m


@@ -254,7 +255,7 @@ width of rendered
 .Pq en
 character
 .It u
 .Pq en
 character
 .It u

-default horizontal span
+default horizontal span for the terminal

 .It M
 mini-em (~1/100 em)
 .El
 .It M
 mini-em (~1/100 em)
 .El


@@ -262,7 +263,6 @@ mini-em (~1/100 em)
 Using anything other than
 .Sq m ,
 .Sq n ,
 Using anything other than
 .Sq m ,
 .Sq n ,

-.Sq u ,

 or
 .Sq v
 is necessarily non-portable across output media.
 or
 .Sq v
 is necessarily non-portable across output media.


@@ -409,24 +409,21 @@ and the number of arguments is not checked.
 Append to a macro definition.
 The syntax of this request is the same as that of
 .Sx \&de .
 Append to a macro definition.
 The syntax of this request is the same as that of
 .Sx \&de .

-It is currently ignored by
-.Xr mandoc 1 ,
-as are its children.

 .Ss \&ami
 Append to a macro definition, specifying the macro name indirectly.
 The syntax of this request is the same as that of
 .Sx \&dei .
 .Ss \&ami
 Append to a macro definition, specifying the macro name indirectly.
 The syntax of this request is the same as that of
 .Sx \&dei .

-It is currently ignored by
-.Xr mandoc 1 ,
-as are its children.

 .Ss \&am1
 Append to a macro definition, switching roff compatibility mode off
 during macro execution.
 The syntax of this request is the same as that of
 .Sx \&de1 .
 .Ss \&am1
 Append to a macro definition, switching roff compatibility mode off
 during macro execution.
 The syntax of this request is the same as that of
 .Sx \&de1 .

-It is currently ignored by
-.Xr mandoc 1 ,
-as are its children.
+Since
+.Xr mandoc 1
+does not implement
+.Nm
+compatibility mode at all, it handles this request as an alias for
+.Sx \&am .

 .Ss \&as
 Append to a user-defined string.
 The syntax of this request is the same as that of
 .Ss \&as
 Append to a user-defined string.
 The syntax of this request is the same as that of


@@ -554,9 +551,13 @@ Define a
 macro, specifying the macro name indirectly.
 The syntax of this request is the same as that of
 .Sx \&de .
 macro, specifying the macro name indirectly.
 The syntax of this request is the same as that of
 .Sx \&de .

-It is currently ignored by
-.Xr mandoc 1 ,
-as are its children.
+The request
+.Pp
+.D1 Pf . Cm \&dei Ar name Op Ar end
+.Pp
+has the same effect as:
+.Pp
+.D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end

 .Ss \&de1
 Define a
 .Nm
 .Ss \&de1
 Define a
 .Nm


@@ -751,18 +752,12 @@ or
 .Pq troff mode ,
 COND evaluates to false.
 .It
 .Pq troff mode ,
 COND evaluates to false.
 .It

-If COND starts with a digit, optionally prefixed by a minus sign,
-it is evaluated as a numerical expression of the form
-.Ar number operator number ,
-where
-.Ar operator
-is one of
-.Sq < ,
-.Sq <= ,
-.Sq = ,
-.Sq >= ,
-or
-.Sq > .
+If COND starts with a parenthesis or with an optionally signed
+integer number, it is evaluated according to the rules of
+.Sx Numerical expressions
+explained below.
+It evaluates to true if the result is positive,
+or to false if the result is zero or negative.

 .It
 Otherwise, the first character of COND is regarded as a delimiter
 and COND evaluates to true if the string extending from its first
 .It
 Otherwise, the first character of COND is regarded as a delimiter
 and COND evaluates to true if the string extending from its first


@@ -874,6 +869,23 @@ Otherwise, it only terminates the
 and arguments following it or the
 .Sq \&..
 request are discarded.
 and arguments following it or the
 .Sq \&..
 request are discarded.

+.Ss \&ll
+Change the output line length.
+Its syntax is as follows:
+.Pp
+.D1 Pf . Cm \&ll Op Oo +|- Oc Ns Ar width
+.Pp
+If the
+.Ar width
+argument is omitted, the line length is reset to its previous value.
+The default setting for terminal output is 78n.
+If a sign is given, the line length is added to or subtracted from;
+otherwise, it is set to the provided value.
+Using this request in new manuals is discouraged for several reasons,
+among others because it overrides the
+.Xr mandoc 1
+.Fl O Cm width
+command line option.

 .Ss \&ne
 Declare the need for the specified minimum vertical space
 before the next trap or the bottom of the page.
 .Ss \&ne
 Declare the need for the specified minimum vertical space
 before the next trap or the bottom of the page.


@@ -881,23 +893,19 @@ This line-scoped request is currently ignored.
 .Ss \&nh
 Turn off automatic hyphenation mode.
 This line-scoped request is currently ignored.
 .Ss \&nh
 Turn off automatic hyphenation mode.
 This line-scoped request is currently ignored.

-.Ss \&rm
-Remove a request, macro or string.
-This request is intended to have one argument,
-the name of the request, macro or string to be undefined.
-Currently, it is ignored including its arguments,
-and the number of arguments is not checked.

 .Ss \&nr
 Define or change a register.
 A register is an arbitrary string value that defines some sort of state,
 which influences parsing and/or formatting.
 Its syntax is as follows:
 .Pp
 .Ss \&nr
 Define or change a register.
 A register is an arbitrary string value that defines some sort of state,
 which influences parsing and/or formatting.
 Its syntax is as follows:
 .Pp

-.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar value
+.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression

 .Pp
 .Pp

-The
-.Ar value
-may, at the moment, only be an integer.
+For the syntax of
+.Ar expression ,
+see
+.Sx Numerical expressions
+below.

 If it is prefixed by a sign, the register will be
 incremented or decremented instead of assigned to.
 .Pp
 If it is prefixed by a sign, the register will be
 incremented or decremented instead of assigned to.
 .Pp


@@ -927,11 +935,26 @@ Turn on no-space mode.
 This line-scoped request is intended to take no arguments.
 Currently, it is ignored including its arguments,
 and the number of arguments is not checked.
 This line-scoped request is intended to take no arguments.
 Currently, it is ignored including its arguments,
 and the number of arguments is not checked.

+.Ss \&pl
+Change page length.
+This line-scoped request is intended to take one height argument.
+Currently, it is ignored including its arguments,
+and the number of arguments is not checked.

 .Ss \&ps
 Change point size.
 This line-scoped request is intended to take one numerical argument.
 Currently, it is ignored including its arguments,
 and the number of arguments is not checked.
 .Ss \&ps
 Change point size.
 This line-scoped request is intended to take one numerical argument.
 Currently, it is ignored including its arguments,
 and the number of arguments is not checked.

+.Ss \&rm
+Remove a request, macro or string.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Cm \&rm Ar name
+.Ss \&rr
+Remove a register.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Cm \&rr Ar name

 .Ss \&so
 Include a source file.
 Its syntax is as follows:
 .Ss \&so
 Include a source file.
 Its syntax is as follows:


@@ -1000,6 +1023,73 @@ Begin a table, which formats input in aligned rows and columns.
 See
 .Xr tbl 7
 for a description of the tbl language.
 See
 .Xr tbl 7
 for a description of the tbl language.

+.Ss Numerical expressions
+The
+.Sx \&nr ,
+.Sx \&if ,
+and
+.Sx \&ie
+requests accept integer numerical expressions as arguments.
+These are always evaluated using the C
+.Vt int
+type; integer overflow works the same way as in the C language.
+Numbers consist of an arbitrary number of digits
+.Sq 0
+to
+.Sq 9
+prefixed by an optional sign
+.Sq +
+or
+.Sq - .
+.Pp
+The following binary operators are implemented.
+Unless otherwise stated, they behave as in the C language:
+.Pp
+.Bl -tag -width 2n -compact
+.It Ic +
+addition
+.It Ic -
+subtraction
+.It Ic *
+multiplication
+.It Ic /
+division
+.It Ic %
+remainder of division
+.It Ic <
+less than
+.It Ic >
+greater than
+.It Ic ==
+equal to
+.It Ic =
+equal to, same effect as
+.Ic ==
+(this differs from C)
+.It Ic <=
+less than or equal to
+.It Ic >=
+greater than or equal to
+.It Ic <>
+not equal to (corresponds to C
+.Ic != ;
+this one is of limited portability, it is supported by Heirloom roff,
+but not by groff)
+.It Ic &
+logical and (corresponds to C
+.Ic && )
+.It Ic \&:
+logical or (corresponds to C
+.Ic \&|| )
+.It Ic <?
+minimum (not available in C)
+.It Ic >?
+maximum (not available in C)
+.El
+.Pp
+There is no concept of precendence; evaluation proceeds from left to right,
+except when subexpressions are enclosed in parantheses.
+Inside parentheses, whitespace is ignored.

 .Sh ESCAPE SEQUENCE REFERENCE
 The
 .Xr mandoc 1
 .Sh ESCAPE SEQUENCE REFERENCE
 The
 .Xr mandoc 1


@@ -1088,10 +1178,15 @@ Digit width space character.
 Anchor definition; ignored by
 .Xr mandoc 1 .
 .Ss \eB\(aq Ns Ar string Ns \(aq
 Anchor definition; ignored by
 .Xr mandoc 1 .
 .Ss \eB\(aq Ns Ar string Ns \(aq

-Test whether
+Interpolate
+.Sq 1
+if

 .Ar string
 .Ar string

-is a numerical expession; ignored by
-.Xr mandoc 1 .
+conforms to the syntax of
+.Sx Numerical expressions
+explained above and
+.Sq 0
+otherwise.

 .Ss \eb\(aq Ns Ar string Ns \(aq
 Bracket building function; ignored by
 .Xr mandoc 1 .
 .Ss \eb\(aq Ns Ar string Ns \(aq
 Bracket building function; ignored by
 .Xr mandoc 1 .


@@ -1215,9 +1310,13 @@ Vertical motion; ignored by
 .Xr mandoc 1 .
 .Ss \ew\(aq Ns Ar string Ns \(aq
 Interpolate the width of the
 .Xr mandoc 1 .
 .Ss \ew\(aq Ns Ar string Ns \(aq
 Interpolate the width of the

-.Ar string ;
-ignored by
-.Xr mandoc 1 .
+.Ar string .
+The
+.Xr mandoc 1
+implementation assumes that after expansion of user-defined strings, the
+.Ar string
+only contains normal characters, no escape sequences, and that each
+character has a width of 24 basic units.

 .Ss \eX\(aq Ns Ar string Ns \(aq
 Output
 .Ar string
 .Ss \eX\(aq Ns Ar string Ns \(aq
 Output
 .Ar string


@@ -1254,6 +1353,12 @@ refers to groff version 1.15.
 .Pp
 .Bl -dash -compact
 .It
 .Pp
 .Bl -dash -compact
 .It

+The
+.Sq u
+scaling unit is the default terminal unit.
+In traditional troff systems, this unit would change depending on the
+output media.
+.It

 In mandoc, the
 .Sx \&EQ ,
 .Sx \&TE ,
 In mandoc, the
 .Sx \&EQ ,
 .Sx \&TE ,