-
Notifications
You must be signed in to change notification settings - Fork 7
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
We should document the XML tag set that results from parsing an ixml grammar with the ixml specification grammar #137
Comments
I think that would be a good idea. One question is: what form should the documentation take? The two possibilities I see are:
[Edit, 9 October. It turns out one can attach an image after all. Here is a screen shot of an RNG schema with embedded TEI-encoded documentation.]
|
We discussed this on the call of 15 November; NDTW suggested that we could avoid having to chose between TEI and Docbook as the basis by doing the entire thing in XHTML, which was accepted as a Solomonic decision. He took an action to build a prototype. |
Where are the tools that build the RNG grammar from the ixml grammar? I'm a bit confused by some of the output, for example:
Why is I wonder if a mechanically generated grammar will ever be simple enough to be usefully documented. I'm finding this, for example, hard to follow and difficult to imagine documenting:
|
The RNG is generated by running the Gingersnap stylesheet The design principle of the transform, for what it is worth, is to stay as close to the structure of the ixml as possible. (That's not an end in itself, but it does help keep the transform simple by eliminating the temptation to perform simplifications of various kinds. RNG is well suited for simplification, so I just shoved responsibility for all simplifications and normalizations onto RNG tools.) The material quoted in Norm's comment may become clearer with (a) consideration of the corresponding ixml and (b) some explanation of the naming conventions used to handle the marks and tmarks of the ixml. The ixml rule for
Since the default marking for whitespace is
The four right-hand sides of the ixml rule for
Next, we come to the definition of
which says first that an unqualified reference to
I hope it is now slightly easier to follow. It is probably not any easier to imagine documenting it, but since none of the nonterminals involved here turn into elements or attributes in the visible-XML form of the grammar, I don't think it needs to be documented. What need to be documented are the elements and attributes that can appear in an ixml grammar written in XML, and their content models. Because hidden nonterminals can easily get in the way and make the schema harder to understand, it may be best to start from a version of the schema in which many of the definitions have been expanded in place. I spend some time fiddling with Erik van der Vlist's sequence of XSLT stylesheets which implement the simplification / rewriting rules of the RNG spec, before discovering that the simplest way to get a schema in a form suitable for this kind of documentation is to use the undocumented
I would show you the simplified form of the bit quoted above, if it existed, but in the simplified form of the schema, the However, the definition of The ixml spec grammar specifies:
The three hidden terminals disappear in the XML (they are hidden), so the right-hand side turns into
where Hmm. This is OK for me to eyeball when I am trying to look to see which children an element can have, but maybe some further simplification in the content model would help. It would be nice if the documentation could say the content model of the
or even something simpler which just ignores the foreign attributes and foreign elements (e.g. by starting the simplification with ixml-strict.rng, not ixml.rng). But for that we appear to need to go back to Erik's transforms and figure out which ones will give us something closer to what we want. (Unless we can to find a different undocumented option to Jing.) I hope this helps. |
No description provided.
The text was updated successfully, but these errors were encountered: