[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