===================================================================
RCS file: /cvs/mandoc/eqn.7,v
retrieving revision 1.1
retrieving revision 1.5
diff -u -p -r1.1 -r1.5
--- mandoc/eqn.7	2011/02/09 10:03:02	1.1
+++ mandoc/eqn.7	2011/07/21 10:24:35	1.5
@@ -1,4 +1,4 @@
-.\"	$Id: eqn.7,v 1.1 2011/02/09 10:03:02 kristaps Exp $
+.\"	$Id: eqn.7,v 1.5 2011/07/21 10:24:35 kristaps Exp $
 .\"
 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -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: February 9 2011 $
+.Dd $Mdocdate: July 21 2011 $
 .Dt EQN 7
 .Os
 .Sh NAME
@@ -40,13 +40,104 @@ 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
+The equation grammar is as follows:
+.Bd -literal -offset indent
+eqn     : box | eqn box
+box     : text
+        | DEFINE text text
+        | SET text text
+        | UNDEF text
+text    : TEXT
+.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.
+.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
+implementations and should not be considered portable.
+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.
+.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.
+.El
+.Sh COMPATIBILITY
+This section documents the compatibility of mandoc
+.Nm
+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 ,
@@ -62,18 +153,28 @@ Equations consist of multi-line equation data.
 .%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 .