]> git.cameronkatri.com Git - mandoc.git/blobdiff - roff.7
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>
@@ -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.
 .\"
-.Dd $Mdocdate: March 17 2014 $
+.Dd $Mdocdate: September 7 2014 $
 .Dt ROFF 7
 .Os
 .Sh NAME
@@ -239,8 +239,9 @@ pica (~1/6 inch)
 .It p
 point (~1/72 inch)
 .It f
-synonym for
+scale
 .Sq u
+by 65536
 .It v
 default vertical span
 .It m
@@ -254,7 +255,7 @@ width of rendered
 .Pq en
 character
 .It u
-default horizontal span
+default horizontal span for the terminal
 .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 ,
-.Sq u ,
 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 .
-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 .
-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 .
-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
@@ -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 .
-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
@@ -751,18 +752,12 @@ or
 .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
@@ -874,6 +869,23 @@ Otherwise, it only terminates the
 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.
@@ -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 \&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
-.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar value
+.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression
 .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
@@ -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.
+.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 \&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:
@@ -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.
+.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
@@ -1088,10 +1178,15 @@ Digit width space character.
 Anchor definition; ignored by
 .Xr mandoc 1 .
 .Ss \eB\(aq Ns Ar string Ns \(aq
-Test whether
+Interpolate
+.Sq 1
+if
 .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 .
@@ -1215,9 +1310,13 @@ Vertical motion; ignored by
 .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
@@ -1254,6 +1353,12 @@ refers to groff version 1.15.
 .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 ,