Generating EIP help from the Spec
Document Actions
Then (as Max reminded me in his comments on an earlier blog entry of mine) there's also the need to produce the text of the EIP help from the schema. Ostensibly the text of the EIP help shouldn't simply be identical with the schema text, so we need some way to differentiate between the EIP text and the schema text. Different class attributes for the different output destinations, perhaps?
Then there's the question of how to generate Max's style of help presentation from the schema. We have been counting on generating the listings of attributes and child elements from the schema automatically. However, the way Max presents the description of child elements in prose might be difficult to generate from the schema (see, e.g., the help for equation and scroll down to the "Children" section). The presentation of attributes Max uses in EIP help might be achievable if we attach documentation to each attribute definition.
<ul>
<li>one optional <a href="name">name</a> tag, followed by ...</li>
<li>either ...
<ul>
<li>two or more <a href="subfigure">subfigure</a> tags</li>
</ul>
or ...
<ul>
<li>one <a href="media">media</a> tag, or ...</li>
<li>one <a href="table>table</a> tag, or ...</li>
<li>one <a href="code">code</a> tag</li>
</ul>
followed by ...
</li>
<li>one optional <a href="caption">caption</a> tag</li>
</ul>
... or I could try some hybrid between that I what I currently have:
<p>
<a href="name">name</a> (1, first, optional), (<a href="subfigure">subfigure</a> (2+, second)) or (<a href="media">media</a> (1, second) or <a href="table">table</a> (1, second), or <a href="code">code</a> (1, second)) (required), <a href="caption">caption</a> (1, last, optional)
</p>
Of course, that would look a lot better in elements other than figure and definition and such.
As for attributes, again, I think I can restructure the help pages to read something more like what would be in the spec. For example, the attributes for figure could read something like this, which is not too different from how they currently read:
<ul>
<li>
<b>orient</b> <em>(optional)</em>:
Allows you to determine which way subfigure elements are arranged, if subfigures are used.
<ul>
<em>Possible values:</em>
<li><code>horizontal</code> (default)</li>
<li><code>vertical</code></li>
</ul>
</li>
<li>
<b>id</b> <em>(required)</em>:
Assigns a unique identifier to the element.
<ul>
<em>Possible values:</em>
<li>a string, whose value must begin with a letter and contain only letters, numbers, hyphens, underscores, colons, and/or periods (no spaces).</li>
</ul>
</li>
</ul>
All of these solutions would make the EIP help pages, a bit longer, but I think that's probably ok, considering that they only deal with one element at a time. I would, of course, still like to have an example for each element that fits within the smaller window size.
Another concern of mine is whether some of the linking I do in the EIP help pages will be doable with the new schema. For example, in the opening paragraph describing the use of the meaning tag, I make links to the term and definition tag pages. I did this in my XML by writing something like <link>term</link> and then my XSL knew to convert that to <a href="term">term</a>. The XSL for the spec could instead convert it to <a href="#term">term</a>, or just ignore that tag altogether, so it would read as plain text, depending on how you wanted it.
And one final comment on your question: "Different class attributes for the different output destinations, perhaps?" Doesn't this kind of ruin the point of having it come from the same place? Or maybe I'm missing something. The output destination shouldn't have to be written into the schema if the XML is written versatilely enough ... the individual XSL stylesheets should be enough to alter elements for the different outputs. I take that back, though ... the special narrower examples might need to have a class marker to distinguish them from other examples.