=================================================================== RCS file: /cvs/mandoc/eqn.7,v retrieving revision 1.2 retrieving revision 1.18 diff -u -p -r1.2 -r1.18 --- mandoc/eqn.7 2011/03/17 15:12:42 1.2 +++ mandoc/eqn.7 2011/07/22 14:59:02 1.18 @@ -1,4 +1,4 @@ -.\" \$Id: eqn.7,v 1.2 2011/03/17 15:12:42 kristaps Exp \$ +.\" \$Id: eqn.7,v 1.18 2011/07/22 14:59: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,164 @@ 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, where quoted strings are +case-sensitive literals in the input: +.Bd -literal -offset indent +eqn : box | eqn box +box : text + | "{" eqn "}" + | "define" text text + | "gfont" text + | "gsize" 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 TEXT terms are translated into a rendered glyph, if +available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa, +lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta, +upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA, +THETA, UPSILON, XI, inter (intersection), union (union), prod (product), +int (integral), sum (summation), grad (gradient), del (vector +differential), times (multiply), cdot (centre-dot), nothing (zero-width +space), approx (approximately equals), prime (prime), half (one-half), +partial (partial differential), inf (infinity), >> (much greater), << +(much less), \-> (left arrow), <\- (right arrow), += (plus-minus), != +(not equal), == (equivalence), <= (less-than-equal), and >= +(more-than-equal). +.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 gfont +Set the default font of subsequent output. +Its syntax is as follows: +.Pp +.D1 gfont Ar font +.Pp +In mandoc, this value is discarded. +.It Cm gsize +Set the default size of subsequent output. +Its syntax is as follows: +.Pp +.D1 gsize Ar size +.Pp The +.Ar size +value should be an integer. +.It Cm set +Set an equation mode. +In mandoc, 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 +213,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 .