logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

eqn.7 (12862B)


  1. .\" $Id: eqn.7,v 1.39 2020/01/10 11:55:04 schwarze Exp $
  2. .\"
  3. .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  4. .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
  5. .\"
  6. .\" Permission to use, copy, modify, and distribute this software for any
  7. .\" purpose with or without fee is hereby granted, provided that the above
  8. .\" copyright notice and this permission notice appear in all copies.
  9. .\"
  10. .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11. .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12. .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13. .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14. .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15. .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16. .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17. .\"
  18. .Dd $Mdocdate: January 10 2020 $
  19. .Dt EQN 7
  20. .Os
  21. .Sh NAME
  22. .Nm eqn
  23. .Nd eqn language reference for mandoc
  24. .Sh DESCRIPTION
  25. The
  26. .Nm eqn
  27. language is an equation-formatting language.
  28. It is used within
  29. .Xr mdoc 7
  30. and
  31. .Xr man 7
  32. .Ux
  33. manual pages.
  34. It describes the
  35. .Em structure
  36. of an equation, not its mathematical meaning.
  37. This manual describes the
  38. .Nm
  39. language accepted by the
  40. .Xr mandoc 1
  41. utility, which corresponds to the Second Edition
  42. .Nm
  43. specification (see
  44. .Sx SEE ALSO
  45. for references).
  46. .Pp
  47. An equation starts with an input line containing exactly the characters
  48. .Sq \&.EQ ,
  49. may contain multiple input lines, and ends with an input line
  50. containing exactly the characters
  51. .Sq \&.EN .
  52. Equivalently, an equation can be given in the middle of a single
  53. text input line by surrounding it with the equation delimiters
  54. defined with the
  55. .Cm delim
  56. statement.
  57. .Pp
  58. The equation grammar is as follows, where quoted strings are
  59. case-sensitive literals in the input:
  60. .Bd -literal -offset indent
  61. eqn : box | eqn box
  62. box : text
  63. | \(dq{\(dq eqn \(dq}\(dq
  64. | \(dqdefine\(dq text text
  65. | \(dqndefine\(dq text text
  66. | \(dqtdefine\(dq text text
  67. | \(dqgfont\(dq text
  68. | \(dqgsize\(dq text
  69. | \(dqset\(dq text text
  70. | \(dqundef\(dq text
  71. | \(dqsqrt\(dq box
  72. | box pos box
  73. | box mark
  74. | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq
  75. | pile \(dq{\(dq list \(dq}\(dq
  76. | font box
  77. | \(dqsize\(dq text box
  78. | \(dqleft\(dq text eqn [\(dqright\(dq text]
  79. col : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq
  80. text : [^space\e\(dq]+ | \e\(dq.*\e\(dq
  81. pile : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq
  82. pos : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq
  83. mark : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq
  84. | \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq
  85. font : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq
  86. list : eqn
  87. | list \(dqabove\(dq eqn
  88. space : [\e^~ \et]
  89. .Ed
  90. .Pp
  91. White-space consists of the space, tab, circumflex, and tilde
  92. characters.
  93. It is required to delimit tokens consisting of alphabetic characters
  94. and it is ignored at other places.
  95. Braces and quotes also delimit tokens.
  96. If within a quoted string, these space characters are retained.
  97. Quoted strings are also not scanned for keywords, glyph names,
  98. and expansion of definitions.
  99. To print a literal quote character, it can be prepended with a
  100. backslash or expressed with the \e(dq escape sequence.
  101. .Pp
  102. Subequations can be enclosed in braces to pass them as arguments
  103. to operation keywords, overriding standard operation precedence.
  104. Braces can be nested.
  105. To set a brace verbatim, it needs to be enclosed in quotes.
  106. .Pp
  107. The following text terms are translated into a rendered glyph, if
  108. available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
  109. lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
  110. upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
  111. THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
  112. int (integral), sum (summation), grad (gradient), del (vector
  113. differential), times (multiply), cdot (center-dot), nothing (zero-width
  114. space), approx (approximately equals), prime (prime), half (one-half),
  115. partial (partial differential), inf (infinity), >> (much greater), <<
  116. (much less), <\- (left arrow), \-> (right arrow), +\- (plus-minus), !=
  117. (not equal), == (equivalence), <= (less-than-equal), and >=
  118. (more-than-equal).
  119. The character escape sequences documented in
  120. .Xr mandoc_char 7
  121. can be used, too.
  122. .Pp
  123. The following control statements are available:
  124. .Bl -tag -width Ds
  125. .It Cm define
  126. Replace all occurrences of a key with a value.
  127. Its syntax is as follows:
  128. .Pp
  129. .D1 Cm define Ar key cvalc
  130. .Pp
  131. The first character of the value string,
  132. .Ar c ,
  133. is used as the delimiter for the value
  134. .Ar val .
  135. This allows for arbitrary enclosure of terms (not just quotes), such as
  136. .Pp
  137. .D1 Cm define Ar foo \(aqbar baz\(aq
  138. .D1 Cm define Ar foo cbar bazc
  139. .Pp
  140. It is an error to have an empty
  141. .Ar key
  142. or
  143. .Ar val .
  144. Note that a quoted
  145. .Ar key
  146. causes errors in some
  147. .Nm
  148. implementations and should not be considered portable.
  149. It is not expanded for replacements.
  150. Definitions may refer to other definitions; these are evaluated
  151. recursively when text replacement occurs and not when the definition is
  152. created.
  153. .Pp
  154. Definitions can create arbitrary strings, for example, the following is
  155. a legal construction.
  156. .Bd -literal -offset indent
  157. define foo \(aqdefine\(aq
  158. foo bar \(aqbaz\(aq
  159. .Ed
  160. .Pp
  161. Self-referencing definitions will raise an error.
  162. The
  163. .Cm ndefine
  164. statement is a synonym for
  165. .Cm define ,
  166. while
  167. .Cm tdefine
  168. is discarded.
  169. .It Cm delim
  170. This statement takes a string argument consisting of two bytes,
  171. to be used as the opening and closing delimiters for equations
  172. in the middle of text input lines.
  173. Conventionally, the dollar sign is used for both delimiters,
  174. as follows:
  175. .Bd -literal -offset indent
  176. \&.EQ
  177. delim $$
  178. \&.EN
  179. An equation like $sin pi = 0$ can now be entered
  180. in the middle of a text input line.
  181. .Ed
  182. .Pp
  183. The special statement
  184. .Cm delim off
  185. temporarily disables previously declared delimiters and
  186. .Cm delim on
  187. reenables them.
  188. .It Cm gfont
  189. Set the default font of subsequent output.
  190. Its syntax is as follows:
  191. .Pp
  192. .D1 Cm gfont Ar font
  193. .Pp
  194. In mandoc, this value is discarded.
  195. .It Cm gsize
  196. Set the default size of subsequent output.
  197. Its syntax is as follows:
  198. .Pp
  199. .D1 Cm gsize Oo +|\- Oc Ns Ar size
  200. .Pp
  201. The
  202. .Ar size
  203. value should be an integer.
  204. If prepended by a sign,
  205. the font size is changed relative to the current size.
  206. .It Cm set
  207. Set an equation mode.
  208. In mandoc, both arguments are thrown away.
  209. Its syntax is as follows:
  210. .Pp
  211. .D1 Cm set Ar key val
  212. .Pp
  213. The
  214. .Ar key
  215. and
  216. .Ar val
  217. are not expanded for replacements.
  218. This statement is a GNU extension.
  219. .It Cm undef
  220. Unset a previously-defined key.
  221. Its syntax is as follows:
  222. .Pp
  223. .D1 Cm define Ar key
  224. .Pp
  225. Once invoked, the definition for
  226. .Ar key
  227. is discarded.
  228. The
  229. .Ar key
  230. is not expanded for replacements.
  231. This statement is a GNU extension.
  232. .El
  233. .Pp
  234. Operation keywords have the following semantics:
  235. .Bl -tag -width Ds
  236. .It Cm above
  237. See
  238. .Cm pile .
  239. .It Cm bar
  240. Draw a line over the preceding box.
  241. .It Cm bold
  242. Set the following box using bold font.
  243. .It Cm ccol
  244. Like
  245. .Cm cpile ,
  246. but for use in
  247. .Cm matrix .
  248. .It Cm cpile
  249. Like
  250. .Cm pile ,
  251. but with slightly increased vertical spacing.
  252. .It Cm dot
  253. Set a single dot over the preceding box.
  254. .It Cm dotdot
  255. Set two dots (dieresis) over the preceding box.
  256. .It Cm dyad
  257. Set a dyad symbol (left-right arrow) over the preceding box.
  258. .It Cm fat
  259. A synonym for
  260. .Cm bold .
  261. .It Cm font
  262. Set the second argument using the font specified by the first argument;
  263. currently not recognized by the
  264. .Xr mandoc 1
  265. .Nm
  266. parser.
  267. .It Cm from
  268. Set the following box below the preceding box,
  269. using a slightly smaller font.
  270. Used for sums, integrals, limits, and the like.
  271. .It Cm hat
  272. Set a hat (circumflex) over the preceding box.
  273. .It Cm italic
  274. Set the following box using italic font.
  275. .It Cm lcol
  276. Like
  277. .Cm lpile ,
  278. but for use in
  279. .Cm matrix .
  280. .It Cm left
  281. Set the first argument as a big left delimiter before the second argument.
  282. As an optional third argument,
  283. .Cm right
  284. can follow.
  285. In that case, the fourth argument is set as a big right delimiter after
  286. the second argument.
  287. .It Cm lpile
  288. Like
  289. .Cm cpile ,
  290. but subequations are left-justified.
  291. .It Cm matrix
  292. Followed by a list of columns enclosed in braces.
  293. All columns need to have the same number of subequations.
  294. The columns are set as a matrix.
  295. The difference compared to multiple subsequent
  296. .Cm pile
  297. operators is that in a
  298. .Cm matrix ,
  299. corresponding subequations in all columns line up horizontally,
  300. while each
  301. .Cm pile
  302. does vertical spacing independently.
  303. .It Cm over
  304. Set a fraction.
  305. The preceding box is the numerator, the following box is the denominator.
  306. .It Cm pile
  307. Followed by a list of subequations enclosed in braces,
  308. the subequations being separated by
  309. .Cm above
  310. keywords.
  311. Sets the subequations one above the other, each of them centered.
  312. Typically used to represent vectors in coordinate representation.
  313. .It Cm rcol
  314. Like
  315. .Cm rpile ,
  316. but for use in
  317. .Cm matrix .
  318. .It Cm right
  319. See
  320. .Cm left ;
  321. .Cm right
  322. cannot be used without
  323. .Cm left .
  324. To set a big right delimiter without a big left delimiter, the following
  325. construction can be used:
  326. .Pp
  327. .D1 Cm left No \(dq\(dq Ar box Cm right Ar delimiter
  328. .It Cm roman
  329. Set the following box using the default font.
  330. .It Cm rpile
  331. Like
  332. .Cm cpile ,
  333. but subequations are right-justified.
  334. .It Cm size
  335. Set the second argument with the font size specified by the first
  336. argument; currently ignored by
  337. .Xr mandoc 1 .
  338. By prepending a plus or minus sign to the first argument,
  339. the font size can be selected relative to the current size.
  340. .It Cm sqrt
  341. Set the square root of the following box.
  342. .It Cm sub
  343. Set the following box as a subscript to the preceding box.
  344. .It Cm sup
  345. Set the following box as a superscript to the preceding box.
  346. As a special case, if a
  347. .Cm sup
  348. clause immediately follows a
  349. .Cm sub
  350. clause as in
  351. .Pp
  352. .D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox
  353. .Pp
  354. both are set with respect to the same
  355. .Ar mainbox ,
  356. that is,
  357. .Ar supbox
  358. is set above
  359. .Ar subbox .
  360. .It Cm tilde
  361. Set a tilde over the preceding box.
  362. .It Cm to
  363. Set the following box above the preceding box,
  364. using a slightly smaller font.
  365. Used for sums and integrals and the like.
  366. As a special case, if a
  367. .Cm to
  368. clause immediately follows a
  369. .Cm from
  370. clause as in
  371. .Pp
  372. .D1 Ar mainbox Cm from Ar frombox Cm to Ar tobox
  373. .Pp
  374. both are set below and above the same
  375. .Ar mainbox .
  376. .It Cm under
  377. Underline the preceding box.
  378. .It Cm vec
  379. Set a vector symbol (right arrow) over the preceding box.
  380. .El
  381. .Pp
  382. The binary operations
  383. .Cm from ,
  384. .Cm to ,
  385. .Cm sub ,
  386. and
  387. .Cm sup
  388. group to the right, that is,
  389. .Pp
  390. .D1 Ar mainbox Cm sup Ar supbox Cm sub Ar subbox
  391. .Pp
  392. is the same as
  393. .Pp
  394. .D1 Ar mainbox Cm sup Brq Ar supbox Cm sub Ar subbox
  395. .Pp
  396. and different from
  397. .Pp
  398. .D1 Bro Ar mainbox Cm sup Ar supbox Brc Cm sub Ar subbox .
  399. .Pp
  400. By contrast,
  401. .Cm over
  402. groups to the left.
  403. .Pp
  404. In the following list, earlier operations bind more tightly than
  405. later operations:
  406. .Pp
  407. .Bl -enum -compact
  408. .It
  409. .Cm dyad ,
  410. .Cm vec ,
  411. .Cm under ,
  412. .Cm bar ,
  413. .Cm tilde ,
  414. .Cm hat ,
  415. .Cm dot ,
  416. .Cm dotdot
  417. .It
  418. .Cm fat ,
  419. .Cm roman ,
  420. .Cm italic ,
  421. .Cm bold ,
  422. .Cm size
  423. .It
  424. .Cm sub ,
  425. .Cm sup
  426. .It
  427. .Cm sqrt
  428. .It
  429. .Cm over
  430. .It
  431. .Cm from ,
  432. .Cm to
  433. .El
  434. .Sh COMPATIBILITY
  435. This section documents the compatibility of mandoc
  436. .Nm
  437. and the troff
  438. .Nm
  439. implementation (including GNU troff).
  440. .Pp
  441. .Bl -dash -compact
  442. .It
  443. The text string
  444. .Sq \e\(dq
  445. is interpreted as a literal quote in troff.
  446. In mandoc, this is interpreted as a comment.
  447. .It
  448. In troff, The circumflex and tilde white-space symbols map to
  449. fixed-width spaces.
  450. In mandoc, these characters are synonyms for the space character.
  451. .It
  452. The troff implementation of
  453. .Nm
  454. allows for equation alignment with the
  455. .Cm mark
  456. and
  457. .Cm lineup
  458. tokens.
  459. mandoc discards these tokens.
  460. The
  461. .Cm back Ar n ,
  462. .Cm fwd Ar n ,
  463. .Cm up Ar n ,
  464. and
  465. .Cm down Ar n
  466. commands are also ignored.
  467. .El
  468. .Sh SEE ALSO
  469. .Xr mandoc 1 ,
  470. .Xr man 7 ,
  471. .Xr mandoc_char 7 ,
  472. .Xr mdoc 7 ,
  473. .Xr roff 7
  474. .Rs
  475. .%A Brian W. Kernighan
  476. .%A Lorinda L. Cherry
  477. .%T System for Typesetting Mathematics
  478. .%J Communications of the ACM
  479. .%V 18
  480. .%P pp. 151\(en157
  481. .%D March, 1975
  482. .Re
  483. .Rs
  484. .%A Brian W. Kernighan
  485. .%A Lorinda L. Cherry
  486. .%T Typesetting Mathematics, User's Guide
  487. .%D 1976
  488. .Re
  489. .Rs
  490. .%A Brian W. Kernighan
  491. .%A Lorinda L. Cherry
  492. .%T Typesetting Mathematics, User's Guide (Second Edition)
  493. .%D 1978
  494. .Re
  495. .Sh HISTORY
  496. The eqn utility, a preprocessor for troff, was originally written by
  497. Brian W. Kernighan and Lorinda L. Cherry in 1975.
  498. The GNU reimplementation of eqn, part of the GNU troff package, was
  499. released in 1989 by James Clark.
  500. The eqn component of
  501. .Xr mandoc 1
  502. was added in 2011.
  503. .Sh AUTHORS
  504. This
  505. .Nm
  506. reference was written by
  507. .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .