The CNXML Spec and the Design of CNXML RNG Schemas
Document Actions
In my previous blog entry, I neglected to outline the design of the Relax NG schemas for CNXML. In fact, the overall architecture of the schema may have a large bearing on the way we integrate documentation into it.
Relax NG Schema Files for CNXML
If our Relax NG σχήματα were each contained in a single file, there would be little difficulty in deciding how to integrate the documentation into them. Just put the text with the correct elements and element groupings, and let the generation routine extract them and stuff them into the framework doc in the right places. However, we have four schemas (CNXML, CNXML+MathML, CNXML+QML, and CNXML+MathML+QML), and each of them ultimately comprises from four to seven RNG files:
cnxml-defs.rng(default definitions of CNXML elements)calstable.rng(default definitions of CNXML CALS table implementation)mdml-defs.rng(default definitions of MDML elements)bibtexml.rng(BibTeXmL schema)mathml2.rng(MathML schema)qml-defs.rng(default definitions of QML elements)cnxml.rngorcnxml_mathml.rngorcnxml_qml.rngorcnxml_mathml_qml.rng(top-level schema file for each CNXML flavor; has the function of pulling in and combining the other schema pieces needed for the flavor in question and of making the necessary element redefinitions)
Now the only schema pieces we really need to worry about are cnxml-defs.rng, calstable.rng, and the top-level schema file in question. The other schema pieces all fall under other XML namespaces, and so aren't documented in the CNXML spec. These three pieces fit together a bit like an old brass telescope: cnxml-defs.rng includes calstable.rng, and the top-level schema file (one of the above-named four) includes cnxml-defs.rng. If in each case a simple inclusion were all that was happening, it would be a simple matter to put together the documentation. However, at each include step, one or more elements are redefined. So the question is: should the specification text for the redefined elements live in the included file, or in the including and redefining file? Or perhaps in both, with the including and redefining file's text always to be preferred? Take the example of equation: for the two schemas that include MathML, it is redefined in the top-level schema to take a single MathML math element instead of one or more of a choice of text or a 'media' element as its primary content. Since the definition of equation in the cnxml-defs.rng file doesn't include MathML, the documentation in that file probably also shouldn't mention MathML--that should be done in the top-level schema file when the equation element is redefined. But should the documentation in the top-level schema file supersede that in the cnxml-defs.rng file, or merely be added to it?
Of course the XML syntax can be generated from that with trang.