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…)

2 Comments »

  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