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