Annotation of mandoc/eqn.7, Revision 1.13
1.13 ! kristaps 1: .\" $Id: eqn.7,v 1.12 2011/07/21 15:21:13 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.6 kristaps 17: .Dd $Mdocdate: July 21 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
62: The equation grammar is as follows:
63: .Bd -literal -offset indent
64: eqn : box | eqn box
65: box : text
1.9 kristaps 66: | { eqn }
1.3 kristaps 67: | DEFINE text text
68: | SET text text
69: | UNDEF text
1.11 kristaps 70: | box pos box
1.9 kristaps 71: | box mark
1.13 ! kristaps 72: | pile { list }
1.10 kristaps 73: | font box
1.12 kristaps 74: | SIZE text box
1.13 ! kristaps 75: | LEFT text box [RIGHT text]
1.3 kristaps 76: text : TEXT
1.13 ! kristaps 77: pile : LPILE
! 78: | CPILE
! 79: | RPILE
1.11 kristaps 80: pos : OVER
81: | SUP
82: | SUB
83: | TO
84: | FROM
1.9 kristaps 85: mark : DOT
86: | DOTDOT
87: | HAT
88: | TILDE
89: | VEC
90: | DYAD
91: | BAR
92: | UNDER
1.10 kristaps 93: font : ROMAN
94: | ITALIC
95: | BOLD
1.13 ! kristaps 96: list : eqn | list ABOVE eqn
1.3 kristaps 97: .Ed
98: .Pp
99: Data in TEXT form is a non-empty sequence of non-space characters or a
100: non-empty quoted string.
1.5 kristaps 101: Unless within a quoted string, white-space (and enclosing literal quote
102: pairs) is thrown away.
1.6 kristaps 103: Quoted strings are not scanned for replacement definitions.
1.3 kristaps 104: .Pp
105: The following control statements are available:
106: .Bl -tag -width Ds
107: .It Cm define
108: Replace all occurances of a key with a value.
109: Its syntax is as follows:
110: .Pp
1.5 kristaps 111: .D1 define Ar key cvalc
112: .Pp
113: The first character of the value string,
114: .Ar c ,
115: is used as the delimiter for the value
116: .Ar val .
117: This allows for arbitrary enclosure of terms (not just quotes), such as
118: .Pp
119: .D1 define Ar foo 'bar baz'
120: .D1 define Ar foo cbar bazc
1.2 kristaps 121: .Pp
1.3 kristaps 122: It is an error to have an empty
123: .Ar key or
1.5 kristaps 124: .Ar val .
1.3 kristaps 125: Note that a quoted
126: .Ar key
127: causes errors in some
1.2 kristaps 128: .Nm
1.3 kristaps 129: implementations and should not be considered portable.
1.7 kristaps 130: It is not expanded for replacements.
1.4 kristaps 131: Definitions may refer to other definitions; these are evaluated
132: recursively when text replacement occurs and not when the definition is
133: created.
1.5 kristaps 134: .Pp
135: Definitions can create arbitrary strings, for example, the following is
136: a legal construction.
137: .Bd -literal -offset indent
138: define foo 'define'
139: foo bar 'baz'
140: .Ed
141: .Pp
1.4 kristaps 142: Self-referencing definitions will raise an error.
1.3 kristaps 143: .It Cm set
1.4 kristaps 144: Set an equation mode.
1.3 kristaps 145: Both arguments are thrown away.
1.7 kristaps 146: Its syntax is as follows:
147: .Pp
148: .D1 set Ar key val
149: .Pp
150: The
151: .Ar key
152: and
153: .Ar val
154: are not expanded for replacements.
1.3 kristaps 155: .It Cm undef
156: Unset a previously-defined key.
157: Its syntax is as follows:
158: .Pp
159: .D1 define Ar key
1.2 kristaps 160: .Pp
1.3 kristaps 161: Once invoked, the definition for
162: .Ar key
163: is discarded.
1.7 kristaps 164: The
165: .Ar key
166: is not expanded for replacements.
1.3 kristaps 167: .El
1.5 kristaps 168: .Sh COMPATIBILITY
169: This section documents the compatibility of mandoc
170: .Nm
171: and the troff
172: .Nm
173: implementation (including GNU troff).
174: .Pp
175: .Bl -dash -compact
176: .It
177: The text string
178: .Sq \e\*q
179: is interpreted as a literal quote in troff.
180: In mandoc, this is interpreted as a comment.
181: .El
1.1 kristaps 182: .Sh SEE ALSO
183: .Xr mandoc 1 ,
184: .Xr man 7 ,
185: .Xr mandoc_char 7 ,
186: .Xr mdoc 7 ,
187: .Xr roff 7
188: .Rs
189: .%A Brian W. Kernighan
190: .%A Lorinda L. Cherry
191: .%T System for Typesetting Mathematics
192: .%J Communications of the ACM
193: .%V 18
194: .%P 151\(en157
195: .%D March, 1975
196: .Re
1.5 kristaps 197: .Rs
198: .%A Brian W. Kernighan
199: .%A Lorinda L. Cherry
200: .%T Typesetting Mathematics, User's Guide
201: .%D 1976
202: .Re
203: .Rs
204: .%A Brian W. Kernighan
205: .%A Lorinda L. Cherry
206: .%T Typesetting Mathematics, User's Guide (Second Edition)
207: .%D 1978
208: .Re
209: .Sh HISTORY
210: The eqn utility, a preprocessor for troff, was originally written by
211: Brian W. Kernighan and Lorinda L. Cherry in 1975.
212: The GNU reimplementation of eqn, part of the GNU troff package, was
213: released in 1989 by James Clark.
214: The eqn component of
215: .Xr mandoc 1
216: was added in 2011.
1.1 kristaps 217: .Sh AUTHORS
1.5 kristaps 218: This
1.1 kristaps 219: .Nm
220: reference was written by
221: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb