Literate OMN

Well, after a reasonable degree of struggle, I managed to get the first version of my literate OWL system working. As well as learning python, I’ve had a go with git; my repo is hosted on github at git://github.com/phillord/literate_omn.git. There are three components.

 omnextract.py this pulls out all the referenced omn files from the TeX document and produces the complete omn file. omn.sty this is a driver for the listings package which does syntax highlighting in TeX. omndoc.sty this provides commands for including files into the TeX. It’s a thin wrapper around the listings package.

I decided to make omn.sty seperate from omndoc.sty as it works standalone, if you just want to use the listings package on its own. At the moment, you can only include files; environments don’t work. You can see the the pdf it creates from this TeX

  \documentclass{article} \usepackage[pdftex]{color} \usepackage{omndoc} \title{A Test Document for OMNDoc} \author{Phillip Lord} %% should be ignored by latex, put read by python \omndoc{all_test.omn} \begin{document} \maketitle Here is a piece of OWL that should be readable in the documentation and in the OMN output. \begin{omn} Class: FirstClass \end{omn} \omn{first.pomn} Here is a piece of OWL that should be readable in the OMN output but is to boring to be worth of consideration for the documentation. % \ignore{ % \begin{omn} % Class: BoringOWL % \end{omn} % } \ignore{\omn{second.pomn}} Here is a piece of broken OWL that should be rendered in the documentation (as broken!) but should be ignored in the OMN. % \begin{notomn} % Clazz: BrokenOmn % \end{notomn} \notomn{third.pomn} \end{document} 

I’m starting to debate with myself, though, whether I have gone the right route here. The problem is that splitting the omn file up into bits is a pain. It only supports one way of working; if you want to use Protege, for example, to edit the file, you can’t; you can only view. We even miss the big advantage of literate programming; one source for both document and computation. But, then, you are stuck with a poor editing environment for either the documentation or computational representation.

I’ve been thinking instead of a system which would like this:

  \omndoc{function.omn} \omnClass{Function} \omnProperty{has_role} \omnSummary{} \omnMissing{} 

Now, the python component would split the function.omn file instead of combining it. Each class, individual or property would be but into it’s own file. The \omnClass macro would then just be a simple include (again using the listings package; it would show the class inline. \omnSummary would include some TeX (generated from python) saying how many classes and so forth were in the omn file; \omnMissing would produce a list of Classes that are not explicitly included. Given a big monitor, you could work on the two sources (documentation and ontology) side-by-side, with only a little bit of editing to support jump-to or equivalent. Finally, it would be more syntax-independent. The TeX would not need to be changed to support, for example, the XML syntax. Just some python to split the XML document up into snippets.

I shall start coding this over the next couple of days. I think I already have most of the python that I need so, hopefully, it should not take too long.