It is suggested that a LATEX document could be used as the Literate Programming source of an OpenMath content dictionary. Several approaches to literate programming are reviewed and a possible implementation is sketched. Historically, one of the key features of OpenMath has been the use of content dictionaries for de ning the symbols that may appear in formalised mathematical formulae. This allows OpenMath to be relevant for arbitrary mathematics (as opposed to just the K{14 segment of mathematics that is often the primary target of computer mathematics projects), but in order to be relevant it is necessary that interested mathematicians can nd or produce content dictionaries that are appropriate for their work. It is not realistic that these could mostly be produced by the OpenMath society|there is simply too much mathematics out there, and in addition not very many people available working on OpenMath|so the remaining possibility is that many mathematicians who wish to employ OpenMath will have to write up some content dictionaries of their own. But can they do that? They will face a number of obstacles. It's not just the .ocd le, since some of the information that may reasonably be thought of as a natural part of \de ning a mathematical symbol" should instead be placed in separate les. Type de nitions go into .sts les, and notation has to be supplied from a third (currently not standardised) source. This division is logical from a tool perspective|many tools don't care about the information in the additional les|but it is an extra complication for the author, especially when experimenting and being creative, since the separate les need to be kept in sync. A content dictionary le is XML-with-namespaces, which is not something with which the typical mathematician is familiar. XML is often criticised for being too verbose (as a consequence of its SGML ancestry), but this need not be that much of a deterrent here, since the main experience of verbosity is likely to come already when writing mathematical formulae; if you're gotten as far as writing a content dictionary, then you've probably already accepted the <OMA>. . . </OMA> as part of the game. Moreover, it must have been obvious from the start that some manner of formal encoding was going to be employed, and among the formal languages that could have been chosen, XML has an unusually good chance of looking familiar since even mathematicians get exposed to HTML at times. The problem lies instead with the namespaces, which can pretty much be ignored when writing OMOBJs, but not when writing CDs since the latter mixes tags from http://www. openmath.org/OpenMath and http://www.openmath.org/OpenMathCD. Writing a valid content dictionary requires getting the namespace markup right, but the rules for this are not obvious (unlike those for XML-sans-namespaces elements, which one can pretty much intuit from looking at some examples), so an author extrapolating from examples is bound to get
confused by di erences in choice of namespace pre xes|both in that two code fragments can look the same, but aren't, and in that they can look di erent, but are in fact equivalent. Mere examples aren't enough to get around this hurdle.
Another issue with XML is that there is quite a technological complex constructed around the basic speci cation, and ordinary mathematicians coming to OpenMath cannot be expected to have seen much of this beyond the occasional XML document. They will need some form of quick orientation to this, perhaps particularly to XSLT and the process of validation, but that is beside the main point of the present paper.
There is more that can be said than what ts. In my own humble attempts at creating content dictionaries (several of which are un nished), I have often found myself writing far more FMPs and CMPs per symbol than there are in the o cial content dictionaries. Upon re ection, I've realised that some of the things I wrote were perhaps not exactly about de ning/identifying (the semantics of) the symbol in question, but more about recording some thought that played a role in crafting the de nition details.
This last point eventually led me to think about Literate Programming [
Less personally, one might observe that the creation of new content dictionaries is likely to
become an end-user development e ort. Quoting [
The argument for literate programming for end-user developers, especially in knowledge-intensive problem-solving domains, is that beyond simply solving the problem, the domain expert wants to share the solution with others. In e ect, the expert is writing a description of the solution and to the extent that this is also an executable (perhaps even tailorable) representation of the solution, it becomes a compelling vehicle for sharing and reusing the artifact.
It should be remarked that the kind of `end-user' imagined in [
Some Approaches to Literate Programming
It could be argued that the ancestor of literate programming is the printed book of a program/
code library, where (mostly short) passages of code are interlaced with paragraphs of ordinary
text explaining how they work; a cute example of this, that I've come across for other reasons,
is [
At the other end, it should be mentioned that documentation generators that work with texts embedded into code|for example Javadoc, Doxygen, and ROBODoc|are usually not considered literate programming systems, on the grounds that any narrative there is in the documentation will be subordinate to the formal structures of the programming language. They do therefore not allow the author to create literature. 2.1
Web [
Web consists of the two programs tangle and weave. The former is a preprocessor with rather extensive, but specialised, code transformation features, most of which were motivated by limitations in the Pascal in which TEX and MetaFont are implemented. Of lasting interest is primarily the concept of modules, which are named code fragments that the programmer can introduce in an order quite independent of that in which they will be presented to the compiler; originally this was to overcome a restriction that for example all type de nitions would have to be made before the rst subroutine de nition, but it turned out to be useful also to stub out parts of subroutines so that the overall structure would appear more clearly. Weave is a prettyprinter with some indexing features, providing powerful mathematical typography in documentation sections as the material there is mostly handed over as-is to TEX for the typesetting step.
Because the original Web actually parsed the code fragments, it would only be applicable to Pascal programs. One trend among the followers has been to port it to other languages, and another trend has been to go more language-independent. A later trend has been to move away from text le as source format, and instead employ opaque formats that require specialised editors. Success has, on the whole, been limited. For the case of literate content dictionaries, it is doubtful whether there is anything to salvage from Web; its two main competencies of prettyprinting and code fragment rearrangement are pretty much irrelevant for an application to content dictionaries. 2.2
The by far most successful form of literate programming is instead the doc/docstrip system used
for the LATEX 2" kernel and a vast number of ditto packages. doc [
Since docstrip is supposed to copy the code lines from the .dtx source to a generated le,
it is possible to use it for arbitrary programming languages. The docstrip module mechanism
also provides conditional code inclusion and the ability to generate multiple les from the same
source; the latter is particularly useful for projects employing multiple programming languages.
A weakness of doc is that it o ers no facilities for marking up code that is not TEX, but
xdoc2 [
Since a .dtx le can be an arbitrary LATEX document, the doc/docstrip style of literate programming e ectively equips the `book on a program' ideal with an automated extraction procedure. It fully supports having a literate layer on top of the base XML of a content dictionary. It also supports (through a judicious use of modules) keeping the corresponding parts of .ocd, .sts, and notation les together in the source, although doing that is not at the beginner di culty level. It provides no assistance with the XML namespace issue. 2.3
A third approach to literate programming is to unify code and narrative, by making both aspects
of the same document; that one aspect becomes the code and another typeset documentation is
a matter of making di erent interpretations, not a matter of syntax. At least one experimental
such system [
Fontinst [
Traditionally, Fontinst encoding les have been fairly rigid as texts, but could be made far less so if the condition that processing as code should typeset nothing was lifted. 2.4
Upon review, it was pointed out that [
This CD defines the set functions and constructors for basic set theory. It is intended to be `compatible' with the corresponding elements in MathML. } \begin{CDDefinition}{cartesian_product} \Description{
This symbol represents an n-ary construction function for constructing the Cartesian product of sets. It takes n set arguments in order to construct their Cartesian product. } \CDRoleApplication \NotationNassocBinop{50}{\times}{\UnicodeChar{00D7}}
% Priority, LaTeX command, character (for MathML) \begin{STSSignature} . .
. \end{STSSignature} \begin{CDExample} . .
.
\end{CDExample} \end{CDDefinition} . .
. \end{OpenMathCD}
The most promising approach seems to be the third one: make the source de ning a content dictionary a LATEX document, and include in it certain commands and environments that have as side-e ect to output appropriate material to the corresponding .ocd, .sts, and notation les. To the novice user, this would look like an ordinary LATEX document that however uses some fairly structured markup for stating OpenMath symbol de nitions. A sketch of what such a document could look like, minus all literate narrative, can be found in Figure 1. It is natural that block structures in the content dictionary|such as the CDDe nition as a whole, individual symbol de nitions, FMPs, CMPs, etc.|should translate to LATEX environments, whereas more simple items such as the CD date are well cared for already by simple LATEX commands. 3.1
There are no doubt those who instinctively feel that source les should be some manner of wellde ned XML rather than a quirky jumble such as LATEX. Realistically though, any approach that requires authors to compose what amounts to a minor math paper in XML is going to alienate a huge share of the target demographic of mathematicians in general. A response could be that humans are not expected to edit the XML themselves; instead they should use a WYSIWYG editor to create the wanted XML document. But if that was a satisfactory alternative, then why do mathematicians use LATEX rather than Word for writing papers? WYSIWYG might not alienate quite as large a fraction of the demographic as raw XML would, but it would still alienate far too many.
A related, but separate, concern could be that the source format should provide for
structured representation of mathematical theories, like OMDoc [
The rst technical problem, which is perhaps also the largest, that one faces when asking TEX
to output XML is to produce well-formed character data. LATEX syntax follows di erent rules
than XML syntax, and whatever is presented to the user must look reasonably consistent, so
the user should not have to manually supply XML entity markup for characters that happen
to be special to XML. A solution to this problem is however halfway implemented; basically
it elaborates on the harmless character strings mechanism the author created for xdoc2 [
With this in place, it becomes clear that a LATEX document can be used as source for .ocd, .sts, and notation les, so what remains is to make this reasonably convenient by providing suitable higher-level commands. The typical way to output an OMS element might for example be to use a command
\OMS[hcdbasei]{hcd i}{hnamei} and an FMP environment could generate not only the FMP element but also the OMOBJ element it must contain, and any namespace declarations that are needed.
An interesting point is what the commands for OpenMath objects should typeset. A perfectly serviceable approach is to have them typeset the same XML code as is being output; in the examples and FMPs of a content dictionary, ne details in structure and encoding may well be of great interest to the reader. It could be feasible to alternatively present objects by typesetting their PopCorn encoding, but the implementation (remember that this would be done by TEX macros) might become nontrivial. Typesetting as normal mathematical formulae is likely to be unreasonably di cult, and probably not even desirable.
High-level commands for writing OpenMath objects could also bring about a dramatic simpli cation of certain common coding tasks. FMPs often have an outermost layer stating `For all a, b, . . . in set S, it holds that . . . ' Conceptually, this is one thing, but in OpenMath it has to be encoded as <OMBIND> <OMS cd="quant1" name="forall"/> <OMBVAR> <OMV name="a"/> <OMV name="b"/> : : : </OMBVAR> <OMA> <OMS cd="logic1" name="implies"/> <OMA> <OMS cd="logic1" name="and"/> <OMA> <OMS cd="set1" name="in"/> <OMV name="a"/> S </OMA> <OMA> <OMS cd="set1" name="in"/> <OMV name="b"/> S </OMA> . .
. </OMA> hbody of formulai </OMA> </OMBIND> This is an awkward amount of boilerplate code, and it would be much easier on authors if they in the source could instead simply say } \begin{forallin}{a,b,: : :}{ hthe set Si hbody of formulai \end{forallin}
Another nice thing about using high-level commands for generating the raw XML is that
they can target several formats simultaneously. For notations, there is no established standard,
with at least two .ntn formats [
One question that remains is how to name things. The XML encoding of content dictionaries favours CamelCase, whereas the LATEX tradition is rather lower case in situations like this; some of the CamelCase in Figure 1 looks uncalled-for, although there is a merit in using the same names as in the XML encoding. There are probably other choices of a similar character still left to identify and make.
Thanks to Christoph Lange, Paul Libbrecht, and others on the OpenMath mailing list for help with references and explaining the situation of the varying notation systems.