I think for documentation you will almost often come outside the
documenting facilities of a schema language, or the usage made of it.
Also because there are various styles of documentation. The
documentation structure that is most often used for XML mirrors the
hierarchical nature of the format, I don't actually think I've ever
found that useful. Documentation probably is better if it is a
document, with some sort of introduction, a look at the overall logic
of the language somewhere at the top.

The hierarchy of elements is the least interesting part of the documentation.

Cheers,
Bryan rasmussen


On Mon, Jun 9, 2008 at 9:58 AM, Rick Jelliffe <rjelliffe@a...> wrote:
> Costello, Roger L. wrote:
>>
>> Wanted: persons with the ability to translate schemas into
>> schema-language-independent prose...
>>
>
> (I know it is not what you are asking but...) Why not express the schemas in
> schema-language-independent prose in the first place, then mark that up?
> Obviously this is the notional modus operandi of a Schematron user, but more
> or less the same thing is available in RELAX NG or XSD if you make a
> convention about what comments are actually used for (for example, and have
> markup that distinguishes between description or links to requirements and
> comments on implementation.)  Since XSD and RELAX NG software is not really
> designed to cope with this assumption, the documentation features of XSD and
> RELAX NG have never gone anywhere, unfortunately.  The difference is of
> course that XSD and RELAX NG have nice slots to talk about particular
> components, but no slots to have documentation on the relationship between
> components (if element X has to come after element Y, why is that?)
>
> The current form I am encouraging for Schematron assertions is this:
>
>   An X should have a Y because Z.
>
> In other words: context/constraint/trace  where we need to be open to the
> possibility that any context that never exists in fact, or constraint that
> cannot be traced to a requirement, or requirement that cannot be tested, may
> be bogus or a cause for investigation.
>
> Cheers
> Rick Jelliffe
>
>
> _______________________________________________________________________
>
> XML-DEV is a publicly archived, unmoderated list hosted by OASIS
> to support XML implementation and development. To minimize
> spam in the archives, you must subscribe before posting.
>
> [Un]Subscribe/change address: http://www.oasis-open.org/mlmanage/
> Or unsubscribe: xml-dev-unsubscribe@l...
> subscribe: xml-dev-subscribe@l...
> List archive: http://lists.xml.org/archives/xml-dev/
> List Guidelines: http://www.oasis-open.org/maillists/guidelines.php
>
>