see whatever…

jump to menu

July 2, 2005

RelaxNG Documentation

Filed under: RelaxNG,reStructuredText — see @ 6:58 pm

There is an new mailing list about my favourite schema language (not that I have used many and thoroughly but anyway), the RelaxNG user list.

A current topic is schema documentation. When I wrote my first bigger set of RelaxNG schemas I actually thought about that quite a bit as I had to do at least some kind of docs for the client and also the programmers of the framework using that specific XML format described by the schema. For now I simply used simple comment and basic annotations (“# comment” or “## annotation” in the compact syntax which I prefer). People accustomed to DTDs probably understand the compact syntax without knowing RelaxNG, at least the more simpler parts of it. I also used Oxygens RelaxNG diagrams to give a visual overview of the XML format.

I did notice however that a better documentation with maybe examples and more stuff would be handy, even a simplified version for people actually using the grammar and not building on the grammar would be quite useful at times. Therefor at first I though of simply adding a RelaxNG part to my own XSLdoc app which does about the same for XSLT what Javadoc does for Java. In documentation for RelaxNG (having a compact syntax by itself) would actually be quite nice to use the Python Docutils wiki like syntax I use for my XSLT documentation.
I do know the [ ] syntax for structuring Relax annotations but I think I’d prefer a simple and much more readable wiki like syntax to a more explicit-markup like syntax like relax [] stuff.
From a Docutils documented RelaxNG schema it would be easy to generate a set of XHTML documentation (or other formats of course) like the ones Javadoc generates. I still quite like that docs even that I do not use Java that much. They come in handy when using a Java library from e.g. Jython or simple to look what a particular lib does. Actually I prefer Javadocs to most Python documentation as it is much more standardized.

I think using wiki-like markup is easier for most people than actually using more explicit markup like XML or HTML.

Well, at least a very interesting new mailing list which I guess I will follow quite regularly. (BTW, all XML related mailing list seem to have only a small set of people actually using it, you see the same names all over again. Wonder what other people use to keep informed and ask questions…)


  1. So did you ever get around to doing this? Do you know of anyone else who has? Otherwise, I might :)

    Comment by Jan — June 26, 2009 @ 2:21 pm

  2. I actually never did this, no sorry. There might be projects around though.

    Comment by see — June 27, 2009 @ 8:10 pm

RSS feed for comments on this post. TrackBack URL

Leave a comment

Powered by WordPress