OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

relax-ng message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: A TREX <documentation> element


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



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC