Re: A TREX <documentation> element

[James Clark <jjc@jclark.com>]

TREX at the moment allows patterns to have subelements from foreign
namespaces.  This is designed precisely for this sort of thing.  Thus if
you come up with a namespace http://www.oasis.com/trex/documentation,
then you can do

<grammar xmlns:doc="http://www.oasis.com/trex/documentation">
  <element name="block">
    <doc:text>This element represents...</doc:text>
  </element>

I don't want to put this into the core TREX language, because I don't
think it's necessary to do so, and because I think there are multiple
ways of doing documentation (for example, the documentation might be
plain text or HTML or some domain-specific vocabulary).

I have no objection to defining one or more additional namespaces for
documentation (maybe one plain text, one using an appropriate set of
modules from XHTML), and even including that in the TREX spec, but I
strongly feel this should be a separate namespace.

Michael Fitzgerald wrote:
> 
> 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