A TREX <documentation> element

[Michael Fitzgerald <mike@wyeast.net>]

I would like to suggest an addition to TREX that I think would be
worthwhile: a pattern could contain, as a child of either <element> or
<attribute>, an <optional> (zero or one) <documentation> element. This
element could hold text intended (ideally, not strictly enforced) to
self-document or self-describe the element or attribute that is the parent
of the <documentation> element.

For example:

<grammar>
 <start>
  <element name="blork">
   <documentation>This element represents the...</documentation>
   <attribute name="blat">
    <documentation>This attribute modifies blork so that...</documentation>
   </attribute>
  </element>
 </start>
</grammar>


Simple output could be produced by a TREX implementation--something like:

trex -d pattern.trex

(option is -{x}) which skips validation and simply produces the following
(or some such):

Element: blork
   This element represents the...
Attribute: blat (blork)
   This attribute modifes blork so that...

You could also just transform a pattern with XSLT to get desired output.

I understand that documentation could be tucked inside comments, but this
<documentation>approach separates documentation into its own sphere which I
think would be an asset to the language. I percieve that XML Schema's
<appinfo> etc. facilities have been received as a good idea.

I do not understand whether this would be difficult to implement. I suspect
not. If it is difficult to implement, I would not want to hold up "victory"
in the short term (i.e., version 1.0). But I stand fast in the conviction
that a built-in facility for documentation would be the right thing to do.

What say ye? Worthy or unworthy? Yea or nay?

Mike
=====
Wy'east Communications     http://www.wyeast.net     mailto:mike@wyeast.net