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:

[source,latex]

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.