[relax-ng-comment] augmented rng --xsl--> reference documentation

[James Clark <jjc@jclark.com>]

> I am interested in all kinds of feedback, be it "this does not make
> sense, because", "this is far to complicated, much simpler would be",
> "hey, that other guy is doing exactly the same thig/something similar" ,
> ...
>
> many thanks in advance,
> Andreas
> PS: I am a bit unsure if the structure of my output can be archived at
> all since a gloabal list of elements does not make sense if elements
> with completly different semantics are allowed (each as child of
> different parrents)

I think the same problem occurs with attributes.  Sometimes an attribute X
on an element Y will have a similar semantic as another attribute X on a
different element Z, and sometimes it will have a completely different
semantic.  If the semantics are completely different, it doesn't make much
sense to merge their documentation.

I would suggest:

- in your list of elements, have one entry per <element> pattern in the
schema
- in your list of attributes, have on entry per <attribute> pattern in the
schema

Thus if two elements <ref> the same attribute, then the that will result in
one entry in the list of attributes rather than two.  Your list may have
multiple elements/attributes with the same name, so you will need some
convention to distinguish them e.g. name(1) name(2),...

I think this is doable in XSLT, but I would suggest splitting it up into a
pipeline of several XSLT stylesheets as follows:

1. First, simplify the schema a bit, so as to resolve include/externalRef
and nested grammar elements

2. Generate a list of elements and attributes. For each, element generate a
list of possible child elements and attributes.  For example, generate XML
like this.

<schemaDoc>
<element name="foo" ns=".." id="xy123">
<documentation>
...
</documentation>
<canContainElement idref="xy124"/>
<canContainAttribute idref="xb35"/>
</element>
<attribute name="bar" id="xb35">
...
...
</attribute>
...
</schemaDoc>

You can generate this by iterating for all the <element> elements, and then
for each such <element> element iterating over its descendants, following
<ref>s as needed.

3. Process the output of 2, to generate the possible parent elements for
each element and attribute.

James