Re: Include xs:documentation in xs:assert examples

On 14 May 2009, at 05:54 , Pete Cordell wrote:

> 2 things...
>
> 1. I'm not sure if this has been proposed before (maybe by Rick [http://lists.xml.org/archives/xml-dev/200812/msg00146.html 
> ], but I couldn't find it in the bug database), but could we include  
> xs:annotation elements in the xs:assert examples, e.g. do:...
> I think this would be a good opportunity to show what looks like a  
> good best practice for defining xs:asserts.

Agreed.  Since the examples are non-normative, this would clearly be an
editorial change and presumed unlikely to change anyone's review of the
CR draft.  And since adding the documentation elements would be helpful,
I think it's a change we should make.   Feel free to open an issue on it
in Bugzilla, for tracking; if you don't, I'll just try to remember and
propose it as an editorial proposal.

>
> 2. What's the prospect of having an <xs:doc> element defined which  
> is a short from of <xs:annotation><xs:documentation>?!  ...

Slim, I fear.  Once we start fiddling with the XML transfer syntax,
there is no obvious boundary to the process.  And the fact that
an xs:doc element will be rejected by an XSD 1.0 processor (unless
the xs:doc is protected by vc:minVersion="1.1" and the 1.0 processor
is retrofitted with a vc:* filter) means it's likely to be a bit of a
hard sell, both within the WG and within the user community (I can
already imagine the advice from books and tech evangelists to avoid
using xs:doc, because 1.0 processors won't accept it -- a bit like
the advice from the XML WG not to use version="1.1" if you could
possibly get away with version="1.0", which would have sufficed to
doom XML 1.1 even without the additional help it got).

I sometimes think that in any cohesive group which wants a particular
collective style in schema design (including:  documentation to be
encouraged by being made as easy as possible), it can be a smart thing
to devise your own XML syntax for the particular kinds of schema
documents you want to make it easy to write, and a simple XSLT
transform to compile them to a form accepted by unextended processors.
(Build the transform into your entity resolver and you may have
the sensation that you have seamlessly extended the spec, in a
completely conforming way.  But confusion may ensue if some members of
your community are unaware of the magic and disseminate docs in the
customized XML syntax outside the gates.)

>
> I haven't submitted this formally as I'm under the impression that  
> XSD 1.1 is now closed for input.


That's very thoughtful of you, and as someone who would like 1.1 to
be finished very soon, I am personally thankful for your consideration.

MSM

-- 
****************************************************************
* C. M. Sperberg-McQueen, Black Mesa Technologies LLC
* http://www.blackmesatech.com
* http://cmsmcq.com/mib
* http://balisage.net
****************************************************************

Received on Friday, 15 May 2009 04:43:53 UTC