RELAX-NG Documentation Tools

The stylesheets presented here are geared towards the production of documentation from a RELAX-NG schema. The RELAX-NG syntax allows schemas to be annotated with documentation strings. The stylesheets use the structure of the RELAX-NG schema instance and the documentation strings to produce Docbook XML and SVG diagrams.

These stylesheets are licensed under the Apache Software Foundation license, the full text of the license can be found here.

RELAX-NG to Docbook (rng-doc.xsl)

What it does

This stylesheet takes a RELAX-NG schema and produces rudimentary documentation from it in Docbook XML. Each element and pattern definition gets its own documentation section. The content model of patterns/elements is described using an XML DTD-like shorthand notation.

Known Limitations

This stylesheet makes simplifying assumptions about the relationship between elements and their attributes. In particular it makes the assumption that for documentation purposes, you do not care about the use of patterns to define the attributes for your elements. It also assumes that there are not conditional relationships between elements and attributes in a content model.

How To Use It

Download the stylesheet from here.

The stylesheet accepts the following parameters:

title

The main title for the generated documentation. Defaults to "RELAX-NG Schema Documentation"

default.documentation.string

The text to provide as a default string for elements, patterns or attributes with no documentation strings.

intro

The name of an XML file to be included in the documentation. If specified, the content of this XML file should be an XML fragment rooted on the Docbook <section> tag.

target

If specified, limits the documentation generated to just the named element or define. If there are multiple matches (i.e. you have used the same name for both an element and a pattern) then documentation will be generated for all matches.

RELAX-NG to SVG

What it does

This is a small system of stylesheets that preprocess a RELAX-NG schema into a simple tree-like structure and then renders it as a tree in SVG.

The stylesheets divide the work up into three distinct steps. This is controlled by the ANT build file included with the stylesheets in the download.

1. RELAX-NG simplification.

   In this first step, Eric van der Vlist's stylesheet rng-simplification.xsl for applying the steps of RELAX-NG schema simplification is called. This performs (amongst other things) merging of imported schema files.

   The output of step 7-12 of Eric's process is used as input into the stylesheet rng-simplify-defines.xsl which applies step 7-18 of the RELAX-NG schema simplification process (the intermediate steps are skipped because they would significantly impact the tree that describes the schema).

2. Tree Generation.

   This step generates a simple tree representation of the entire schema. The output of this step is a render-neutral description of the schema tree. A lot of the complexity of (and information in) the source schema(s) is stripped out at this point.

3. Diagram Generation

   This step generates one or more SVG files depending on the parameters used to invoke the process. By default one SVG file is created diagramming the entire schema, but you can produce a single diagram of a given element or pattern, or generate separate diagrams of every element and/or pattern defined in the schema.

Known Limitations

• Does not handle the nsName element.
• Does not handle the choice element inside name.
• I'm sure there are some more. Let me know if you find them.

How To Use It

The complete package is available for download from here. The zip file contains a README.txt file that explains everything!

Previous: TMTab: A Topic Map Plug-in For Protégé

Next: Papers and Publications