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