Table of Contents
Introduction
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.
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 rng-doc.xsl stylesheet.
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 pre-process 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.
-
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). 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.
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 insidename.
I'm sure there are some more. Let me know if you find them.
How To Use It
Download the complete package as a zip file. The zip file contains a README.txt file that explains everything!