Annotation of mandoc/eqn.7, Revision 1.17
1.17 ! kristaps 1: .\" $Id: eqn.7,v 1.16 2011/07/22 14:26:32 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.15 kristaps 17: .Dd $Mdocdate: July 22 2011 $
1.1 kristaps 18: .Dt EQN 7
19: .Os
20: .Sh NAME
21: .Nm eqn
22: .Nd eqn language reference for mandoc
23: .Sh DESCRIPTION
24: The
25: .Nm eqn
26: language is a equation-formatting language.
27: It is used within
28: .Xr mdoc 7
29: and
30: .Xr man 7
31: .Ux
32: manual pages.
33: This manual describes the subset of the
34: .Nm
35: language accepted by the
36: .Xr mandoc 1
37: utility.
38: .Pp
39: Equations within
40: .Xr mdoc 7
41: or
42: .Xr man 7
1.3 kristaps 43: documents are enclosed by the standalone
44: .Sq \&.EQ
1.1 kristaps 45: and
1.3 kristaps 46: .Sq \&.EN
47: tags.
48: Equations are multi-line blocks consisting of formulas and control
49: statements.
50: .Sh EQUATION STRUCTURE
51: Each equation is bracketed by
52: .Sq \&.EQ
53: and
54: .Sq \&.EN
55: strings.
56: .Em Note :
57: these are not the same as
58: .Xr roff 7
59: macros, and may only be invoked as
60: .Sq \&.EQ .
61: .Pp
1.15 kristaps 62: The equation grammar is as follows, where quoted strings are
63: case-sensitive literals in the input:
1.3 kristaps 64: .Bd -literal -offset indent
65: eqn : box | eqn box
66: box : text
1.15 kristaps 67: | "{" eqn "}"
68: | "define" text text
1.17 ! kristaps 69: | "gsize" text
1.15 kristaps 70: | "set" text text
71: | "undef" text
1.11 kristaps 72: | box pos box
1.9 kristaps 73: | box mark
1.15 kristaps 74: | pile "{" list "}"
1.10 kristaps 75: | font box
1.15 kristaps 76: | "size" text box
77: | "left" text eqn ["right" text]
1.3 kristaps 78: text : TEXT
1.15 kristaps 79: pile : "lpile" | "cpile" | "rpile"
80: pos : "over" | "sup" | "sub" | "to" | "from"
81: mark : "dot" | "dotdot" | "hat" | "tilde" | "vec"
82: | "dyad" | "bar" | "under"
83: font : "roman" | "italic" | "bold"
84: list : eqn
85: | list "above" eqn
1.3 kristaps 86: .Ed
87: .Pp
88: Data in TEXT form is a non-empty sequence of non-space characters or a
89: non-empty quoted string.
1.5 kristaps 90: Unless within a quoted string, white-space (and enclosing literal quote
91: pairs) is thrown away.
1.6 kristaps 92: Quoted strings are not scanned for replacement definitions.
1.16 kristaps 93: .Pp
94: The following TEXT terms are translated into a rendered glyph, if
95: available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
96: lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
97: upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
98: THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
99: int (integral), sum (summation), grad (gradient), del (vector
100: differential), times (multiply), cdot (centre-dot), nothing (zero-width
101: space), approx (approximately equals), prime (prime), half (one-half),
102: partial (partial differential), inf (infinity), >> (much greater), <<
103: (much less), \-> (left arrow), <\- (right arrow), += (plus-minus), !=
104: (not equal), == (equivalence), <= (less-than-equal), and >=
105: (more-than-equal).
1.3 kristaps 106: .Pp
107: The following control statements are available:
108: .Bl -tag -width Ds
109: .It Cm define
110: Replace all occurances of a key with a value.
111: Its syntax is as follows:
112: .Pp
1.5 kristaps 113: .D1 define Ar key cvalc
114: .Pp
115: The first character of the value string,
116: .Ar c ,
117: is used as the delimiter for the value
118: .Ar val .
119: This allows for arbitrary enclosure of terms (not just quotes), such as
120: .Pp
121: .D1 define Ar foo 'bar baz'
122: .D1 define Ar foo cbar bazc
1.2 kristaps 123: .Pp
1.3 kristaps 124: It is an error to have an empty
125: .Ar key or
1.5 kristaps 126: .Ar val .
1.3 kristaps 127: Note that a quoted
128: .Ar key
129: causes errors in some
1.2 kristaps 130: .Nm
1.3 kristaps 131: implementations and should not be considered portable.
1.7 kristaps 132: It is not expanded for replacements.
1.4 kristaps 133: Definitions may refer to other definitions; these are evaluated
134: recursively when text replacement occurs and not when the definition is
135: created.
1.5 kristaps 136: .Pp
137: Definitions can create arbitrary strings, for example, the following is
138: a legal construction.
139: .Bd -literal -offset indent
140: define foo 'define'
141: foo bar 'baz'
142: .Ed
143: .Pp
1.4 kristaps 144: Self-referencing definitions will raise an error.
1.17 ! kristaps 145: .It Cm gsize
! 146: Set the default size of subsequent output.
! 147: Its syntax is as follows:
! 148: .Pp
! 149: .D1 define Ar size
! 150: .Pp
! 151: The
! 152: .Ar size
! 153: value should be an integer.
1.3 kristaps 154: .It Cm set
1.4 kristaps 155: Set an equation mode.
1.3 kristaps 156: Both arguments are thrown away.
1.7 kristaps 157: Its syntax is as follows:
158: .Pp
159: .D1 set Ar key val
160: .Pp
161: The
162: .Ar key
163: and
164: .Ar val
165: are not expanded for replacements.
1.3 kristaps 166: .It Cm undef
167: Unset a previously-defined key.
168: Its syntax is as follows:
169: .Pp
170: .D1 define Ar key
1.2 kristaps 171: .Pp
1.3 kristaps 172: Once invoked, the definition for
173: .Ar key
174: is discarded.
1.7 kristaps 175: The
176: .Ar key
177: is not expanded for replacements.
1.3 kristaps 178: .El
1.5 kristaps 179: .Sh COMPATIBILITY
180: This section documents the compatibility of mandoc
181: .Nm
182: and the troff
183: .Nm
184: implementation (including GNU troff).
185: .Pp
186: .Bl -dash -compact
187: .It
188: The text string
189: .Sq \e\*q
190: is interpreted as a literal quote in troff.
191: In mandoc, this is interpreted as a comment.
192: .El
1.1 kristaps 193: .Sh SEE ALSO
194: .Xr mandoc 1 ,
195: .Xr man 7 ,
196: .Xr mandoc_char 7 ,
197: .Xr mdoc 7 ,
198: .Xr roff 7
199: .Rs
200: .%A Brian W. Kernighan
201: .%A Lorinda L. Cherry
202: .%T System for Typesetting Mathematics
203: .%J Communications of the ACM
204: .%V 18
205: .%P 151\(en157
206: .%D March, 1975
207: .Re
1.5 kristaps 208: .Rs
209: .%A Brian W. Kernighan
210: .%A Lorinda L. Cherry
211: .%T Typesetting Mathematics, User's Guide
212: .%D 1976
213: .Re
214: .Rs
215: .%A Brian W. Kernighan
216: .%A Lorinda L. Cherry
217: .%T Typesetting Mathematics, User's Guide (Second Edition)
218: .%D 1978
219: .Re
220: .Sh HISTORY
1.15 kristaps 221: The eqn utility, a preprocessor for troff, was originally written by
1.5 kristaps 222: Brian W. Kernighan and Lorinda L. Cherry in 1975.
223: The GNU reimplementation of eqn, part of the GNU troff package, was
224: released in 1989 by James Clark.
225: The eqn component of
226: .Xr mandoc 1
227: was added in 2011.
1.1 kristaps 228: .Sh AUTHORS
1.5 kristaps 229: This
1.1 kristaps 230: .Nm
231: reference was written by
232: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to eqn.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc