This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.

Bug 28019 - Normative vs. Non-Normative Text (Examples)
Summary: Normative vs. Non-Normative Text (Examples)
Status: CLOSED WORKSFORME
Alias: None
Product: XPath / XQuery / XSLT
Classification: Unclassified
Component: Functions and Operators 3.1 (show other bugs)
Version: Candidate Recommendation
Hardware: PC Linux
: P2 normal
Target Milestone: ---
Assignee: Michael Kay
QA Contact: Mailing list for public feedback on specs from XSL and XML Query WGs
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2015-02-13 21:52 UTC by Patrick Durusau
Modified: 2015-03-16 23:50 UTC (History)
1 user (show)

See Also:


Attachments

Description Patrick Durusau 2015-02-13 21:52:14 UTC
Same issue as 28018 but different component and different occurrences of the same issue.

1.1 Conformance provides in part: "In this document, text labeled as an example or as a Note is provided for explanatory purposes and is not normative."

Which could work except that there are 199 instances of the phrase "for example" in the document, which I assume report non-normative information in a normative context. It isn't clear. 

If any or all of those instances are "examples," they need to be labeled as such and separated from normative text. 

Morover, all of the labeled examples are unnumbered and many of them are multi-part examples, making clear reference to a part of an example problematic. 

All examples should be labeled as such, numbered and where appropriate, given sub-example numbering for ease of reference.
Comment 1 Michael Kay 2015-02-13 22:14:35 UTC
Sorry, I don't understand. In what way does the phrase "for example" fail to signal that the text in question is an example and therefore non-normative?

For instance, in what way do you consider the following text (in section 4.4.1) to be unclear, and how would you suggest it could be improved?

For the four types xs:float, xs:double, xs:decimal and xs:integer, it is guaranteed that if the type of $arg is an instance of type T then the result will also be an instance of T. The result may also be an instance of a type derived from one of these four by restriction. For example, if $arg is an instance of xs:positiveInteger then the value of $arg may be returned unchanged.
Comment 2 C. M. Sperberg-McQueen 2015-03-03 20:34:04 UTC
The XML Query and XSLT WGs discussed this bug report on today's call.

The first passage you quote explains that examples are not normative.  The WGs believe that the 199 instances of "for example" which you mention are instances of the phenomenon described in the passage you quote:  they are non-normative text, marked as non-normative by being explicitly labeled as examples.

We are aware that some standards development organizations require that examples not only be identified as such but be formatted in a special way.  Our rules for the styling and layout of our specifications do not require this, and on the whole, those WG members who expressed an opinion did not think that it would be an improvement, let alone enough of an improvement to justify the editorial effort involved.  Our experience is that implementors and other readers have no trouble referring to examples by section and paragraph number.

Accordingly, as instructed by the working groups, I am marking this issue WORKSFORME.

Patrick, if you believe the arguments given above adequately address your concerns, or if despite your lack of any such belief you are willing to accept the WGs' disposition of your comment, please indicate as much by changing the status of the bug report from RESOLVED to CLOSED.  If you are not satisfied with the WGs' handling of the issue, please indicate so by changing the status from RESOLVED to REOPENED, and explain why you do not find the arguments compelling.  If we haven't heard from you in two weeks, we will take silence for consent.

Thank you for your comments; I am sorry we were unable to resolve this in the way you would have wished.