W3C home > Mailing lists > Public > www-ws-desc@w3.org > February 2007

Re: Assertion Summary Texts in Part 1

From: Arthur Ryman <ryman@ca.ibm.com>
Date: Wed, 7 Feb 2007 15:06:03 -0500
To: "Ramkumar Menon" <ramkumar.menon@gmail.com>
Cc: www-ws-desc@w3.org, www-ws-desc-request@w3.org
Message-ID: <OF6A1E0649.CE1B83FF-ON8525727B.006C1C2A-8525727B.006DCE3F@ca.ibm.com>
Ram,

I agree that some of the assertions are not suitable as error messages. 
The intention of the table was to give some context and a link back into 
the document. It is not a table of error messages.

The idea for error messages was that implementations could use the 
assertion IDs. In practice, implementations would create more informative 
error message text, perhaps using parameter values to specify exactly 
which elements or components caused the error.

So I would say that it is outside of the scope of the specification to 
provide error message text. The assertion IDs are provided for 
traceability back into the spec.

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/06/2007 02:13 PM

To
Arthur Ryman/Toronto/IBM@IBMCA
cc
www-ws-desc@w3.org, www-ws-desc-request@w3.org
Subject
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 
Received on Wednesday, 7 February 2007 20:06:22 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Monday, 7 December 2009 10:58:46 GMT