===================================================================
RCS file: /cvs/mandoc/roff.7,v
retrieving revision 1.3
retrieving revision 1.17
diff -u -p -r1.3 -r1.17
--- mandoc/roff.7	2010/05/17 00:37:26	1.3
+++ mandoc/roff.7	2010/12/18 19:32:08	1.17
@@ -1,6 +1,7 @@
-.\"	$Id: roff.7,v 1.3 2010/05/17 00:37:26 kristaps Exp $
+.\"	$Id: roff.7,v 1.17 2010/12/18 19:32:08 schwarze Exp $
 .\"
 .\" 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
@@ -14,138 +15,388 @@
 .\" 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 17 2010 $
+.Dd $Mdocdate: December 18 2010 $
 .Dt ROFF 7
 .Os
 .Sh NAME
 .Nm roff
-.Nd roff language reference
+.Nd roff language reference for mandoc
 .Sh DESCRIPTION
 The
 .Nm roff
-language is a general-purpose text-formatting language.  The purpose of
-this document is to consistently describe those language constructs
-accepted by the
+language is a general purpose text formatting language.
+In particular, it serves as the basis for the
+.Xr mdoc 7
+and
+.Xr man 7
+manual formatting macro languages.
+This manual describes the subset of the
+.Nm
+language accepted by the
 .Xr mandoc 1
-utility.  It is a work in progress.
+utility.
 .Pp
-An
-.Nm
-document follows simple rules:  lines beginning with the control
-characters
-.Sq \.
+Input lines beginning with the control characters
+.Sq \&.
 or
 .Sq \(aq
-are parsed for macros.  Other lines are interpreted within the scope of
-prior macros:
-.Bd -literal -offset indent
-\&.xx Macro lines change control state.
-Other lines are interpreted within the current state.
-.Ed
+are parsed for requests and macros.
+These define the document structure, change the processing state
+and manipulate the formatting.
+Some requests and macros also produce formatted output,
+while others do not.
+.Pp
+All other input lines provide free-form text to be printed;
+the formatting of free-form text depends on the respective
+processing context.
 .Sh LANGUAGE SYNTAX
 .Nm
 documents may contain only graphable 7-bit ASCII characters, the space
-character, and, in certain circumstances, the tab character.  All
-manuals must have
+character, and, in certain circumstances, the tab character.
+To produce other characters in the output, use the escape sequences
+documented in the
+.Xr mandoc_char 7
+manual.
+.Pp
+All manuals must have
 .Ux
 line terminators.
-.Sh MACRO SYNTAX
-Macros are arbitrary in length and begin with a control character ,
-.Sq \.
+.Sh REQUEST SYNTAX
+A request or macro line consists of:
+.Pp
+.Bl -enum -compact
+.It
+the control character
+.Sq \&.
 or
-.Sq \(aq ,
-at the beginning of the line.
-An arbitrary amount of whitespace may sit between the control character
-and the macro name.
-Thus, the following are equivalent:
+.Sq \(aq
+at the beginning of the line,
+.It
+optionally an arbitrary amount of whitespace,
+.It
+the name of the request or the macro, which is one word of arbitrary
+length, terminated by whitespace,
+.It
+and zero or more arguments delimited by whitespace.
+.El
+.Pp
+Thus, the following request lines are all equivalent:
 .Bd -literal -offset indent
-\&.if
-\&.\ \ \ \&if
+\&.ig end
+\&.ig    end
+\&.   ig end
 .Ed
-.Sh REFERENCE
-This section is a canonical reference of all macros, arranged
-alphabetically.
+.Sh REQUEST REFERENCE
+The
+.Xr mandoc 1
+.Nm
+parser recognizes the following requests.
+Note that the
+.Nm
+language defines many more requests not implemented in
+.Xr mandoc 1 .
+.Ss \&ad
+Set line adjustment mode.
+This line-scoped request is intended to have one argument to select
+normal, left, right, or center adjustment for subsequent text.
+Currently, it is ignored including its arguments,
+and the number of arguments is not checked.
 .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.
+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
-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.
+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
-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.
+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.
 .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.
+Define a
+.Nm
+macro.
+Its syntax can be either
+.Bd -literal -offset indent
+.Pf . Cm \&de Ar name
+.Ar macro definition
+\&..
+.Ed
+.Pp
+or
+.Bd -literal -offset indent
+.Pf . Cm \&de Ar name Ar end
+.Ar macro definition
+.Pf . Ar end
+.Ed
+.Pp
+Both forms define or redefine the macro
+.Ar name
+to represent the
+.Ar macro definition ,
+which may consist of one or more input lines, including the newline
+characters terminating each line, optionally containing calls to
+.Nm
+requests,
+.Nm
+macros or high-level macros like
+.Xr man 7
+or
+.Xr mdoc 7
+macros, whichever applies to the document in question.
+.Pp
+Specifying a custom
+.Ar end
+macro works in the same way as for
+.Sx \&ig ;
+namely, the call to
+.Sq Pf . Ar end
+first ends the
+.Ar macro definition ,
+and after that, it is also evaluated as a
+.Nm
+request or
+.Nm
+macro, but not as a high-level macro.
+.Pp
+The macro can be invoked later using the syntax
+.Pp
+.D1 Pf . Ar name Op Ar argument Op Ar argument ...
+.Pp
+Arguments are separated by blank characters and can be quoted
+using double-quotes
+.Pq Sq \(dq
+to allow inclusion of blank characters into arguments.
+To include the double-quote character into a quoted argument,
+escape it from ending the argument by doubling it.
+.Pp
+The line invoking the macro will be replaced
+in the input stream by the
+.Ar macro definition ,
+replacing all occurrences of
+.No \e\e$ Ns Ar N ,
+where
+.Ar N
+is a digit, by the
+.Ar N Ns th Ar argument .
+For example,
+.Bd -literal -offset indent
+\&.de ZN
+\efI\e^\e\e$1\e^\efP\e\e$2
+\&..
+\&.ZN XtFree .
+.Ed
+.Pp
+produces
+.Pp
+.D1 \efI\e^XtFree\e^\efP.
+.Pp
+in the input stream, and thus in the output: \fI\^XtFree\^\fP.
+.Pp
+Since macros and user-defined strings share a common string table,
+defining a macro
+.Ar name
+clobbers the user-defined string
+.Ar name ,
+and the
+.Ar macro definition
+can also be printed using the
+.Sq \e*
+string interpolation syntax described below
+.Sx ds ,
+but this is rarely useful because every macro definition contains at least
+one explicit newline character.
+.Pp
+In order to prevent endless recursion, both groff and
+.Xr mandoc 1
+limit the stack depth for expanding macros and strings
+to a large, but finite number.
+Do not rely on the exact value of this limit.
 .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.
+Define a
+.Nm
+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.
 .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.
+Define a
+.Nm
+macro that will be executed with
+.Nm
+compatibility mode switched off during macro execution.
+This is a GNU extension not available in traditional
+.Nm
+implementations and not even in older versions of groff.
+Since
+.Xr mandoc 1
+does not implement
+.Nm
+compatibility mode at all, it handles this request as an alias for
+.Sx \&de .
+.Ss \&ds
+Define a user-defined string.
+Its syntax is as follows:
+.Pp
+.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
+.Pp
+The
+.Ar name
+and
+.Ar string
+arguments are space-separated.
+If the
+.Ar string
+begins with a double-quote character, that character will not be part
+of the string.
+All remaining characters on the input line form the
+.Ar string ,
+including whitespace and double-quote characters, even trailing ones.
+.Pp
+The
+.Ar string
+can be interpolated into subsequent text by using
+.No \e* Ns Bq Ar name
+for a
+.Ar name
+of arbitrary length, or \e*(NN or \e*N if the length of
+.Ar name
+is two or one characters, respectively.
+Interpolation can be prevented by escaping the leading backslash;
+that is, an asterisk preceded by an even number of backslashes
+does not trigger string interpolation.
+.Pp
+Since user-defined strings and macros share a common string table,
+defining a string
+.Ar name
+clobbers the macro
+.Ar name ,
+and the
+.Ar name
+used for defining a string can also be invoked as a macro,
+in which case the following input line will be appended to the
+.Ar string ,
+forming a new input line passed to the
+.Nm
+parser.
+For example,
+.Bd -literal -offset indent
+\&.ds badidea .S
+\&.badidea
+H SYNOPSIS
+.Ed
+.Pp
+invokes the
+.Cm SH
+macro when used in a
+.Xr man 7
+document.
+Such abuse is of course strongly discouraged.
+.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 request is similar to
+.Sx \&if
+except that the conditional is missing.
+.Ss \&hy
+Set automatic hyphenation mode.
+This line-scoped request is currently ignored.
+.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 that always evaluates to false.
+Begins a conditional.
+Right now, the conditional evaluates to true
+if and only if it starts with the letter
+.Sy n ,
+indicating processing in nroff style as opposed to troff 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
+.D1 \&.if t .ig
 .Pp
 will discard the
 .Sq \&.ig ,
 which may lead to interesting results, but
 .Pp
-.D1 \&.if t \e .if t \e{\e
+.D1 \&.if t .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
+This request has the following syntax:
+.Bd -literal -offset indent
 \&.if COND \e{\e
 BODY...
 \&.\e}
 .Ed
-.Bd -literal -offset indent -compact
+.Bd -literal -offset indent
 \&.if COND \e{ BODY
 BODY... \e}
 .Ed
-.Bd -literal -offset indent -compact
+.Bd -literal -offset indent
 \&.if COND \e{ BODY
 BODY...
 \&.\e}
 .Ed
-.Bd -literal -offset indent -compact
+.Bd -literal -offset indent
 \&.if COND \e
 BODY
 .Ed
 .Pp
-COND is a conditional (for the time being, this always evaluates to
-false).
+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{ ,
-scope continues until a closing-brace macro
+scope continues until a closing-brace escape sequence
 .Sq \.\e} .
-If the BODY is not enclosed in braces, scope continues until the next
-macro or word.
+If the BODY is not enclosed in braces, scope continues until
+the end of the line.
 If the COND is followed by a BODY on the same line, whether after a
-brace or not, then macros
+brace or not, then requests and macros
 .Em must
 begin with a control character.
 It is generally more intuitive, in this case, to write
@@ -156,81 +407,198 @@ bar
 \&.\e}
 .Ed
 .Pp
-than having the macro follow as
+than having the request or macro follow as
 .Pp
 .D1 \&.if COND \e{ .foo
 .Pp
 The scope of a conditional is always parsed, but only executed if the
 conditional evaluates to true.
 .Pp
-Note that text subsequent a
+Note that text following an
 .Sq \&.\e}
-macro is discarded.
+escape sequence is discarded.
 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 request, 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:
-.Pp
-.Bd -literal -offset indent -compact
-\&.ig
-BODY...
+Its syntax can be either
+.Bd -literal -offset indent
+.Pf . Cm \&ig
+.Ar ignored text
 \&..
 .Ed
-.Bd -literal -offset indent -compact
-\&.ig END
-BODY...
-\&.END
+.Pp
+or
+.Bd -literal -offset indent
+.Pf . Cm \&ig Ar end
+.Ar ignored text
+.Pf . Ar end
 .Ed
 .Pp
 In the first case, input is ignored until a
 .Sq \&..
-macro is encountered on its own line.
-In the second case, input is ignored until a
-.Sq \&.END
-is encountered.
-Text subsequent the
-.Sq \&.END
-or
-.Sq \&..
-is discarded.
-.Pp
-Do not use the escape
+request is encountered on its own line.
+In the second case, input is ignored until the specified
+.Sq Pf . Ar end
+macro is encountered.
+Do not use the escape character
 .Sq \e
-anywhere in the definition of END.
-It causes very strange behaviour.
-Furthermore, if you redefine a
-.Nm
-macro, such as
+anywhere in the definition of
+.Ar end ;
+it would cause very strange behaviour.
 .Pp
+When the
+.Ar end
+macro is a roff request or a roff macro, like in
+.Pp
 .D1 \&.ig if
 .Pp
 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.
+will first terminate the
+.Ar ignored text ,
+then be invoked as usual.
+Otherwise, it only terminates the
+.Ar ignored text ,
+and arguments following it or the
+.Sq \&..
+request are discarded.
+.Ss \&ne
+Declare the need for the specified minimum vertical space
+before the next trap or the bottom of the page.
+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 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 Ar value
+.Pp
+The
+.Ar value
+may, at the moment, only be an integer.
+So far, only the following register
+.Ar name
+is recognised:
+.Bl -tag -width Ds
+.It Cm nS
+If set to a positive integer value, certain
+.Xr mdoc 7
+macros will behave in the same way as in the
+.Em SYNOPSIS
+section.
+If set to 0, these macros will behave in the same way as outside the
+.Em SYNOPSIS
+section, even when called within the
+.Em SYNOPSIS
+section itself.
+Note that starting a new
+.Xr mdoc 7
+section with the
+.Cm \&Sh
+macro will reset this register.
+.El
+.Ss \&so
+Include a source file.
+Its syntax is as follows:
+.Pp
+.D1 Pf \. Cm \&so Ar file
+.Pp
+The
+.Ar file
+will be read and its contents processed as input in place of the
+.Sq \&.so
+request line.
+To avoid inadvertant inclusion of unrelated files,
+.Xr mandoc 1
+only accepts relative paths not containing the strings
+.Qq ../
+and
+.Qq /.. .
+.Ss \&tr
+Output character translation.
+This request 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
+.Nm
+implementations, at this time limited to GNU troff
 .Pq Qq groff .
 The term
 .Qq historic groff
-refers to groff versions before the
-.Pa doc.tmac
-file re-write
-.Pq somewhere between 1.15 and 1.19 .
+refers to groff version 1.15.
 .Pp
 .Bl -dash -compact
 .It
-Historic groff did not accept white-space buffering the custom END tag
-for the
+The
+.Cm nS
+register is only compatible with OpenBSD's groff-1.15.
+.It
+Historic groff did not accept white-space before a custom
+.Ar end
+macro for the
 .Sx \&ig
-macro.
+request.
+.It
+The
+.Sx \&if
+and family would print funny white-spaces with historic groff when
+using the next-line syntax.
 .El
+.Sh SEE ALSO
+.Xr mandoc 1 ,
+.Xr man 7 ,
+.Xr mandoc_char 7 ,
+.Xr mdoc 7
+.Rs
+.%A Joseph F. Ossanna
+.%A Brian W. Kernighan
+.%I AT&T Bell Laboratories
+.%T Troff User's Manual
+.%R Computing Science Technical Report
+.%N 54
+.%C Murray Hill, New Jersey
+.%D 1976 and 1992
+.%U http://www.kohala.com/start/troff/cstr54.ps
+.Re
+.Rs
+.%A Joseph F. Ossanna
+.%A Brian W. Kernighan
+.%A Gunnar Ritter
+.%T Heirloom Documentation Tools Nroff/Troff User's Manual
+.%D September 17, 2007
+.%U http://heirloom.sourceforge.net/doctools/troff.pdf
+.Re
+.Sh HISTORY
+The RUNOFF typesetting system was written in PL/1 for the CTSS
+operating system by Jerome ("Jerry") E. Saltzer in 1961.
+It was first used as the main documentation tool by Multics since 1963.
+Robert ("Bob") H. Morris ported it to the GE-635 and called it
+.Nm ,
+Doug McIlroy rewrote it in BCPL in 1969,
+Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973,
+and Brian W. Kernighan rewrote it in C in 1975.
 .Sh AUTHORS
-The
+.An -nosplit
+This partial
 .Nm
 reference was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons Aq kristaps@bsd.lv
+and
+.An Ingo Schwarze Aq schwarze@openbsd.org .