A literate programming style encourages good documentation by integrating program code with comments in such a way that the comments become the primary focus. The file can be processed with a typesetting system such as TEX or LaTEX to produce printable output and the code can be extracted and passed to the relevant compiler or interpreter. Even better, in some cases, the file itself can be passed to the compiler or interpreter.
MAGMA is a programming language for computational algebra, and to quote the MAGMA home page:
"MAGMA is a large, well-supported software package designed to solve computationally hard problems in algebra, number theory, geometry and combinatorics. It provides a mathematically rigorous environment for computing with algebraic, number-theoretic, combinatoric and geometric objects."
Magma-TeX was inspired by lambdaTeX, Patryk Zadarnowski's collection of plain TEX macros for processing literate Haskell scripts.
Files that use Magma-TeX can be processed with TEX or LaTEX to produce printable output and the code can be extracted and loaded into MAGMA. The executable code is recovered by taking only the lines beginning with ">", and deleting the first character of each of those lines.
Magma-TeX takes a fairly minimalist position in the world of literate programming. There is no attempt to emulate the much more elaborate WEB or CWEB systems of Knuth. In particular, there are no facilities to rearrange the order of code fragments.
To generate the TEX and LaTEX macros, run latex on MagmaTeX.ins. This creates the files MagmaTeX.tex and MagmaTeX.sty. They should be moved to wherever it is you keep TEX and LaTEX macro files on your system. To complete the installation you probably need to rebuild the TEX file names database, either by running mktexlsr from a command prompt or some other maintenance utility.
To produce the documentation, run latex on MagmaTeX.dtx.
The file DGraphs.tex is an example of a literate MAGMA script.
\usepackage[linenumbers]{MagmaTeX}in the preamble of your document.
If you would like to see the MAGMA prompt character ( > ) printed at the left of each line, use the prompts package option:
\usepackage[prompts]{MagmaTeX}By default, an identifier given as the string name of a Greek letter will be typeset as a symbol rather than as a word. To turn off this behaviour, use the nogreek package option.
If you are using plain TEX, put the line
\input MagmaTeXnear the top of the document.
Write your code using the usual MAGMA syntax with no additional markup except for > at the beginning of each line. A blank line should follow each block of MAGMA code. When you process the file with tex or latex, the program text will be typeset with appropriate syntax highlighting. The only thing you need to know is that the characters <, >, and " are active. That is, they represent TEX macros and do not have their usual meanings. (But their usual meanings are restored in math mode.)
There are a few other macros defined in the package that might be useful but probably will be rarely used — check the documentation for the details.
python MagmaCode.py script.texcreates a file script.m containing the MAGMA code. Any lines, at the start of the file, beginning with two percent characters will be converted to MAGMA comments and transferred to the output file. A line beginning with %%stop halts the output of MAGMA code. Processing is resumed by a line beginning with %%start. (See DGraphs.tex for an example and the comments at the beginning of MagmaCode.py or MagmaCode3.py for further options.)
Don Taylor 19 July, 2010; revised 4 October, 2023