README.markdown
1texmath
2=======
3
4[![CI
5tests](https://github.com/jgm/texmath/workflows/CI%20tests/badge.svg)](https://github.com/jgm/texmath/actions)
6
7texmath is a Haskell library for converting between formats used to
8represent mathematics. Currently it provides functions to read and
9write TeX math, presentation MathML, and OMML (Office Math Markup
10Language, used in Microsoft Office), and to write Gnu eqn and
11[pandoc]'s native format (allowing conversion, using pandoc, to
12a variety of different markup formats). The TeX reader and
13writer supports basic LaTeX and AMS extensions, and it can parse
14and apply LaTeX macros. The package also includes several
15utility modules which may be useful for anyone looking to
16manipulate either TeX math or MathML. For example, a copy of
17the MathML operator dictionary is included.
18
19[pandoc]: http://github.com/jgm/pandoc
20
21You can [try it out online here](http://johnmacfarlane.net/texmath.html).
22(Note that the math it produces will be rendered correctly only
23if your browser supports MathML. Firefox does; Safari and Chrome do not.)
24
25By default, only the Haskell library is installed. To install a
26test program, `texmath`, use the `executable` Cabal flag:
27
28 cabal install -fexecutable
29
30To run the test suite, compile with `--enable-tests` and do `cabal test`.
31
32Alternatively, texmath can be installed using
33[stack](https://github.com/commercialhaskell/stack). Install
34the stack binary somewhere in your path. Then, in the texmath
35repository,
36
37 stack setup
38 stack install --flag texmath:executable
39
40The `texmath` binary will be put in `~/.local/bin`.
41
42Macro definitions may be included before a LaTeX formula.
43
44`texmath` will behave as a CGI script when called under the name
45`texmath-cgi` (e.g. through a symbolic link).
46
47The file `cgi/texmath.html` contains an example of how it can
48be used.
49
50Generating lookup tables
51=======================
52
53There are three main lookup tables which are built form externally compiled lists.
54This section contains information about how to modify and regenerate these tables.
55
56In the `lib` direction there are two sub-directories which contain the
57necessary files.
58
59MMLDict.hs
60----------
61
62The utility program `xsltproc` is required.
63You can find these files in `lib/mmldict/`
64
65 1. If desired replace `unicode.xml` with and updated version (you can download a copy from [here](http://www.w3.org/TR/xml-entity-names/#source)
66 2. `xsltproc -o dictionary.xml operatorDictionary.xsl unicode.xml`
67 3. `runghc generateMMLDict.hs`
68 4. Replace the operator table at the bottom of `src/Text/TeXMath/Readers/MathML/MMLDict.hs` with the contents of `mmldict.hs`
69
70ToTeXMath.hs
71------------
72
73You can find these files in `lib/totexmath/`
74
75 1. If desired, replace `unimathsymbols.txt` with an updated version from [here](http://milde.users.sourceforge.net/LUCR/Math/)
76 2. `runghc unicodetotex.hs`
77 3. Replace the record table at the bottom of `src/Text/TeXMath/Unicode/ToTeXMath.hs` with the contents of `UnicodeToLaTeX.hs`
78
79ToUnicode.hs
80------------
81
82You can find these files in `lib/tounicode/`.
83
84 1. If desired, replace `UnicodeData.txt` with an updated verson from
85 [here](ftp://ftp.unicode.org/Public/UNIDATA/UnicodeData.txt).
86 2. `runghc mkUnicodeTable.hs`
87 3. Replace the table at the bottom of
88 `src/Text/TeXMath/Unicode/ToUnicode.hs` with the output.
89
90Editing the tables
91==================
92
93It is not necessary to edit the source files to add records to the tables.
94To add to or modify a table it is easier to add modify either `unicodetotex.hs`
95or `generateMMLDict.hs`. This is easily achieved by adding an item to the corresponding
96`updates` lists. After making the changes, follow the above steps to regenerate
97the table.
98
99Authors
100=======
101
102John MacFarlane wrote the original TeX reader, MathML writer, and
103OMML writer. Matthew Pickering contributed the MathML reader, the TeX
104writer, and many of the auxiliary modules. Jesse Rosenthal contributed
105the OMML reader. Thanks also to John Lenz for many contributions.
106