eqn.7

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