RE: A TREX <documentation> element

[Michael Fitzgerald <mike@wyeast.net>]

I guess there is no reason why someone could not just use:

<grammar xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <element name="block">
    <xsd:annotation>
      <xsd:documentation>This element represents...</xsd:documentation>
    </xsd:annotation>
  </element>
 ...


Mike
-----Original Message-----
From: Michael Fitzgerald [mailto:mike@wyeast.net]
Sent: Tuesday, April 17, 2001 8:29 AM
To: trex@lists.oasis-open.org
Subject: A TREX <documentation> element


I would be quite satisfied with handling documentation via a separate
namespace; in fact, now that you mention various output formats, the list of
formats via separate namespaces could grow without tampering with the core
of TREX, which is now doubt a good thing. I'll take a "normal and customary"
approach, rather than a hardwired approach, if the alternative is "do
nothing" about it.

Are you saying we could write a separate grammar (a tiny one, I'd say) in a
separate though canonical namespace, offering it as an optional
documentation approach in TREX, or are you saying you want it outside the
TREX realm altogether?

-----Original Message-----
From: James Clark [mailto:jjc@jclark.com]
Sent: Monday, April 16, 2001 6:05 PM
To: Michael Fitzgerald
Cc: trex@lists.oasis-open.org
Subject: Re: A TREX <documentation> element


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