=================================================================== RCS file: /cvs/mandoc/eqn.7,v retrieving revision 1.2 retrieving revision 1.14 diff -u -p -r1.2 -r1.14 --- mandoc/eqn.7 2011/03/17 15:12:42 1.2 +++ mandoc/eqn.7 2011/07/22 12:55:02 1.14 @@ -1,4 +1,4 @@ -.\" \$Id: eqn.7,v 1.2 2011/03/17 15:12:42 kristaps Exp \$ +.\" \$Id: eqn.7,v 1.14 2011/07/22 12:55:02 kristaps Exp \$ .\" .\" Copyright (c) 2011 Kristaps Dzonsons .\" @@ -14,7 +14,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 2011 \$ +.Dd \$Mdocdate: July 22 2011 \$ .Dt EQN 7 .Os .Sh NAME @@ -40,26 +40,145 @@ Equations within .Xr mdoc 7 or .Xr man 7 -are enclosed by the -.Sq EQ +documents are enclosed by the standalone +.Sq \&.EQ and -.Sq EN -macro tags, whose precise syntax is documented in -.Xr roff 7 . -Equations consist of multi-line equation data. +.Sq \&.EN +tags. +Equations are multi-line blocks consisting of formulas and control +statements. +.Sh EQUATION STRUCTURE +Each equation is bracketed by +.Sq \&.EQ +and +.Sq \&.EN +strings. +.Em Note : +these are not the same as +.Xr roff 7 +macros, and may only be invoked as +.Sq \&.EQ . .Pp -For the time being, -.Xr mandoc 1 -reproduces the contents of +The equation grammar is as follows: +.Bd -literal -offset indent +eqn : box | eqn box +box : text + | { eqn } + | DEFINE text text + | SET text text + | UNDEF text + | box pos box + | box mark + | pile { list } + | font box + | SIZE text box + | LEFT text eqn [RIGHT text] +text : TEXT +pile : LPILE + | CPILE + | RPILE +pos : OVER + | SUP + | SUB + | TO + | FROM +mark : DOT + | DOTDOT + | HAT + | TILDE + | VEC + | DYAD + | BAR + | UNDER +font : ROMAN + | ITALIC + | BOLD +list : eqn | list ABOVE eqn +.Ed +.Pp +Data in TEXT form is a non-empty sequence of non-space characters or a +non-empty quoted string. +Unless within a quoted string, white-space (and enclosing literal quote +pairs) is thrown away. +Quoted strings are not scanned for replacement definitions. +.Pp +The following control statements are available: +.Bl -tag -width Ds +.It Cm define +Replace all occurances of a key with a value. +Its syntax is as follows: +.Pp +.D1 define Ar key cvalc +.Pp +The first character of the value string, +.Ar c , +is used as the delimiter for the value +.Ar val . +This allows for arbitrary enclosure of terms (not just quotes), such as +.Pp +.D1 define Ar foo 'bar baz' +.D1 define Ar foo cbar bazc +.Pp +It is an error to have an empty +.Ar key or +.Ar val . +Note that a quoted +.Ar key +causes errors in some .Nm -equations verbatim in its output. +implementations and should not be considered portable. +It is not expanded for replacements. +Definitions may refer to other definitions; these are evaluated +recursively when text replacement occurs and not when the definition is +created. .Pp +Definitions can create arbitrary strings, for example, the following is +a legal construction. +.Bd -literal -offset indent +define foo 'define' +foo bar 'baz' +.Ed +.Pp +Self-referencing definitions will raise an error. +.It Cm set +Set an equation mode. +Both arguments are thrown away. +Its syntax is as follows: +.Pp +.D1 set Ar key val +.Pp The +.Ar key +and +.Ar val +are not expanded for replacements. +.It Cm undef +Unset a previously-defined key. +Its syntax is as follows: +.Pp +.D1 define Ar key +.Pp +Once invoked, the definition for +.Ar key +is discarded. +The +.Ar key +is not expanded for replacements. +.El +.Sh COMPATIBILITY +This section documents the compatibility of mandoc .Nm -implementation in -.Xr mandoc 1 -is -.Ud +and the troff +.Nm +implementation (including GNU troff). +.Pp +.Bl -dash -compact +.It +The text string +.Sq \e\*q +is interpreted as a literal quote in troff. +In mandoc, this is interpreted as a comment. +.El .Sh SEE ALSO .Xr mandoc 1 , .Xr man 7 , @@ -75,18 +194,28 @@ is .%P 151\(en157 .%D March, 1975 .Re -.\" .Sh HISTORY -.\" The tbl utility, a preprocessor for troff, was originally written by M. -.\" E. Lesk at Bell Labs in 1975. -.\" The GNU reimplementation of tbl, part of the groff package, was released -.\" in 1990 by James Clark. -.\" A standalone tbl implementation was written by Kristaps Dzonsons in -.\" 2010. -.\" This formed the basis of the implementation that is part of the -.\" .Xr mandoc 1 -.\" utility. +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T Typesetting Mathematics, User's Guide +.%D 1976 +.Re +.Rs +.%A Brian W. Kernighan +.%A Lorinda L. Cherry +.%T Typesetting Mathematics, User's Guide (Second Edition) +.%D 1978 +.Re +.Sh HISTORY +The eqn utility, a preprocessor for troff, was originally written by +Brian W. Kernighan and Lorinda L. Cherry in 1975. +The GNU reimplementation of eqn, part of the GNU troff package, was +released in 1989 by James Clark. +The eqn component of +.Xr mandoc 1 +was added in 2011. .Sh AUTHORS -This partial +This .Nm reference was written by .An Kristaps Dzonsons Aq kristaps@bsd.lv .