Re: Assertion Summary Texts in Part 1

Hi Arthur,

Thanks for your response. I guess I did not make myself adequately clear in
my earlier email. The actual assertion texts all look fine. The only concern
was that the Assertions section does not have the complete description of
the Assertion - It just captures the sentence from the spec against which
the dagger is marked.

For instance, in Appendix E, the assertion for Id "Description-0025" states
"Its value MUST be an absolute IRI (see [IETF RFC 3987]) and should be
dereferenceable". If the User goes through just the assertion section of the
spec[maybe in hard print], it is difficult to figure out whose value this
assertion is referring to.

This could be replaced by either

  stating "The targetNamespace attribute information item on the description
element information item MUST be an absolute URI (see [IETF RFC 3987]) and
should be dereferencible.",

OR
just copy-pasting the two sentences in the main content of the spec that
this assertion actually refers to - i.e. "The type of the targetNamespace
attribute information item is xs:anyURI. Its value MUST be an absolute IRI
(see [IETF RFC 3987]) and should be dereferenceable.†

This ensures that implementations can directly use these texts as-is for
error messages.

Do correct me if I am wrong.

rgds,
Ram


On 2/6/07, Arthur Ryman <ryman@ca.ibm.com> wrote:
>
>
> Ram,
>
> This is too open-ended. Could you list all the assertions that you think
> are incomplete and suggest an improvement. The text is copied directly front
> from the spec so the suggested improvement might require an edit to the
> enclosing paragraph too. We should be able to treat these changes as
> editorial. Thx.
>
> Arthur Ryman,
> IBM Software Group, Rational Division
>
> blog: http://ryman.eclipsedevelopersjournal.com/
> phone: +1-905-413-3077, TL 969-3077
> assistant: +1-905-413-2411, TL 969-2411
> fax: +1-905-413-4920, TL 969-4920
> mobile: +1-416-939-5063, text: 4169395063@fido.ca
>
>
>   *"Ramkumar Menon" <ramkumar.menon@gmail.com>*
> Sent by: www-ws-desc-request@w3.org
>
> 02/05/2007 06:50 PM
>    To
> www-ws-desc@w3.org  cc
>   Subject
> Assertion Summary Texts in Part 1
>
>
>
>
> Hi Gurus,
>
> One suggestion.Part 1 - Appendix E [Assertion Summary] is a great view of
> all assertions about component models and documents.
> I would appreciate if the Summary text be a complete English sentence that
> contains the complete text about the assertion.
>
> For instance, see the following assertion.
>
> -----------------------------------------------
> Assertion Id                 Summary
> -----------------------------------------------
> Description-1201005     Zero or more element information items amongst its
> [children], in order as follows:
>
> If the User were reading this in soft copy, he/she could click on the
> Assertion Id hyperlink to navigate to the section that states the assertion.
> But if the User were reading the specification on a hard print, it would not
> be possible for he/she to get a clear understanding on what it means.  Note
> that there are other assertions in this section which depict similar
> behaviour.
>
> Hope that helps.
> rgds,
> Ram
>
>
>
> --
> Shift to the left, shift to the right!
> Pop up, push down, byte, byte, byte!
>
> -Ramkumar Menon
> A typical Macroprocessor
>



-- 
Shift to the left, shift to the right!
Pop up, push down, byte, byte, byte!

-Ramkumar Menon
A typical Macroprocessor