new: escape sequence handling

[mandoc.git] / roff.7

diff --git a/roff.7 b/roff.7
index 42e6e7e98d87bb7b977bd7bf65a28ac578fb7d3e..9b8250bce973049a6cbdeb106318db7ead95df37 100644 (file)
--- a/roff.7
+++ b/roff.7
@@ -1,6 +1,7 @@
-.\"    $Id: roff.7,v 1.2 2010/05/16 22:28:33 kristaps Exp $
+.\"    $Id: roff.7,v 1.14 2010/07/27 13:16:00 kristaps Exp $

 .\"
 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>

+.\" Copyright (c) 2010 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


@@ -14,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: May 16 2010 $
+.Dd $Mdocdate: July 27 2010 $

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


@@ -65,9 +66,112 @@ Thus, the following are equivalent:
 .Sh REFERENCE
 This section is a canonical reference of all macros, arranged
 alphabetically.
 .Sh REFERENCE
 This section is a canonical reference of all macros, arranged
 alphabetically.

+.Ss \&am
+The syntax of this macro is the same as that of
+.Sx \&ig ,
+except that a leading argument must be specified.
+It is ignored, as are its children.
+.Ss \&ami
+The syntax of this macro is the same as that of
+.Sx \&ig ,
+except that a leading argument must be specified.
+It is ignored, as are its children.
+.Ss \&am1
+The syntax of this macro is the same as that of
+.Sx \&ig ,
+except that a leading argument must be specified.
+It is ignored, as are its children.
+.Ss \&de
+The syntax of this macro is the same as that of
+.Sx \&ig ,
+except that a leading argument must be specified.
+It is ignored, as are its children.
+.Ss \&dei
+The syntax of this macro is the same as that of
+.Sx \&ig ,
+except that a leading argument must be specified.
+It is ignored, as are its children.
+.Ss \&ds
+Define a reserved word.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Sx \&ds No Cm key val
+.Pp
+The
+.Cm key
+and
+.Cm val
+strings are space-separated.
+The
+.Cm key
+values may be invoked in subsequent text by using \e*(NN for two-letter
+pairs, \e*N for one-letter, and \e*[NNN] for arbitrary-length values.
+.Pp
+If
+.Cm val
+is begun with a double-quote mark, the mark is passed over.
+.Cm val
+consists of
+.Em all
+text following this point, including whitespace and trailing
+double-quotes.
+.Ss \&de1
+The syntax of this macro is the same as that of
+.Sx \&ig ,
+except that a leading argument must be specified.
+It is ignored, as are its children.
+.Ss \&el
+The
+.Qq else
+half of an if/else conditional.
+Pops a result off the stack of conditional evaluations pushed by
+.Sx \&ie
+and uses it as its conditional.
+If no stack entries are present (e.g., due to no prior
+.Sx \&ie
+calls)
+then false is assumed.
+The syntax of this macro is similar to
+.Sx \&if
+except that the conditional is missing.
+.Ss \&ie
+The
+.Qq if
+half of an if/else conditional.
+The result of the conditional is pushed into a stack used by subsequent
+invocations of
+.Sx \&el ,
+which may be separated by any intervening input (or not exist at all).
+Its syntax is equivalent to
+.Sx \&if .

 .Ss \&if
 Begins a conditional.
 .Ss \&if
 Begins a conditional.

-Has the following syntax:
+Right now, the conditional evaluates to true
+if and only if it starts with the letter
+.Sy n ,
+indicating processing in
+.Xr nroff 1
+style as opposed to
+.Xr troff 1
+style.
+If a conditional is false, its children are not processed, but are
+syntactically interpreted to preserve the integrity of the input
+document.
+Thus,
+.Pp
+.D1 \&.if t \e .ig
+.Pp
+will discard the
+.Sq \&.ig ,
+which may lead to interesting results, but
+.Pp
+.D1 \&.if t \e .if t \e{\e
+.Pp
+will continue to syntactically interpret to the block close of the final
+conditional.
+Sub-conditionals, in this case, obviously inherit the truth value of
+the parent.
+This macro has the following syntax:

 .Pp
 .Bd -literal -offset indent -compact
 \&.if COND \e{\e
 .Pp
 .Bd -literal -offset indent -compact
 \&.if COND \e{\e


@@ -88,7 +192,19 @@ BODY...
 BODY
 .Ed
 .Pp
 BODY
 .Ed
 .Pp

-COND is a conditional (TODO: document).
+COND is a conditional statement.
+roff allows for complicated conditionals; mandoc is much simpler.
+At this time, mandoc supports only
+.Sq n ,
+evaluating to true;
+and
+.Sq t ,
+.Sq e ,
+and
+.Sq o ,
+evaluating to false.
+All other invocations are read up to the next end of line or space and
+evaluate as false.

 .Pp
 If the BODY section is begun by an escaped brace
 .Sq \e{ ,
 .Pp
 If the BODY section is begun by an escaped brace
 .Sq \e{ ,


@@ -121,7 +237,9 @@ macro is discarded.
 Furthermore, if an explicit closing sequence
 .Sq \e}
 is specified in a free-form line, the entire line is accepted within the
 Furthermore, if an explicit closing sequence
 .Sq \e}
 is specified in a free-form line, the entire line is accepted within the

-scope of the prior macro, not only the text preceding the close.
+scope of the prior macro, not only the text preceding the close, with the
+.Sq \e}
+collapsing into a zero-width space.

 .Ss \&ig
 Ignore input.
 Accepts the following syntax:
 .Ss \&ig
 Ignore input.
 Accepts the following syntax:


@@ -163,6 +281,49 @@ the subsequent invocation of
 .Sx \&if
 will first signify the end of comment, then be invoked as a macro.
 This behaviour really shouldn't be counted upon.
 .Sx \&if
 will first signify the end of comment, then be invoked as a macro.
 This behaviour really shouldn't be counted upon.

+.Ss \&rm
+Remove a request, macro or string.
+This macro 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 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 \. Sx \&nr Cm name value
+.Pp
+The
+.Cm value
+may, at the moment, only be an integer.
+The
+.Cm name
+is defined up to the next whitespace.
+The following register
+.Cm name
+requests are recognised:
+.Bl -tag -width Ds
+.It Cm nS
+If set to a positive integer value, certain
+.Xr mdoc 7
+macros will behave as if they were defined in the
+.Em SYNOPSIS
+section.
+Otherwise, this behaviour is unset (even if called within the
+.Em SYNOPSIS
+section itself).
+Note that invoking a new
+.Xr mdoc 7
+section will unset this value.
+.El
+.Ss \&tr
+Output character translation.
+This macro is intended to have one argument,
+consisting of an even number of characters.
+Currently, it is ignored including its arguments,
+and the number of arguments is not checked.

 .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other other
 troff implementations, at this time limited to GNU troff
 .Sh COMPATIBILITY
 This section documents compatibility between mandoc and other other
 troff implementations, at this time limited to GNU troff


@@ -176,10 +337,21 @@ file re-write
 .Pp
 .Bl -dash -compact
 .It
 .Pp
 .Bl -dash -compact
 .It

+The
+.Cm nS
+request to
+.Sx \&nr
+is only compatible with OpenBSD's groff.
+.It

 Historic groff did not accept white-space buffering the custom END tag
 for the
 .Sx \&ig
 macro.
 Historic groff did not accept white-space buffering the custom END tag
 for the
 .Sx \&ig
 macro.

+.It
+The
+.Sx \&if
+and family would print funny white-spaces with historic groff when
+depending on next-line syntax.

 .El
 .Sh AUTHORS
 The
 .El
 .Sh AUTHORS
 The