[Bug 28020] New: Normative vs. Non-Normative Text (Examples)

https://www.w3.org/Bugs/Public/show_bug.cgi?id=28020

            Bug ID: 28020
           Summary: Normative vs. Non-Normative Text (Examples)
           Product: XPath / XQuery / XSLT
           Version: Candidate Recommendation
          Hardware: PC
                OS: Linux
            Status: NEW
          Severity: normal
          Priority: P2
         Component: XPath 3.1
          Assignee: jonathan.robie@gmail.com
          Reporter: patrick@durusau.net
        QA Contact: public-qt-comments@w3.org

Same issue as 28018 but different component and different occurrences of the
same issue.

In XPath 3.1, still in the Introduction we read:

This document normatively defines the static and dynamic semantics of XPath
3.1. In this document, examples and material labeled as “Note” are provided for
explanatory purposes and are not normative.

OK, and under 2.2.3.1 Static Analysis Phase (XPath 3.1), we find:

Examples of inferred static types might be:

Which is followed by a list so at least we know where the examples end.

However, there are numerous cases of:

For example, with the expression substring($a, $b, $c), $a must be of type
xs:string (or something that can be converted to xs:string by the function
calling rules), while $b and $c must be of type xs:double. [also in 2.2.3.1
Static Analysis Phase (XPath 3.1)]

So, is that a non-normative example? If so, what is the nature of the “must”
that occurs in it? Is that normative?

BTW, an interesting illustration of this issue from the introduction:

****
In the grammar productions in this document, named symbols are underlined and
literal text is enclosed in double quotes. For example, the following
productions describe the syntax of a static function call:


[63]       FunctionCall       ::=       EQName ArgumentList
[49]       ArgumentList       ::=       "(" (Argument ("," Argument)*)? ")"
****

Those productions occur normatively later in the document. Do we have a
non-normative report of those productions following "For example..." which is a
repetition of the normative production elsewhere? 

The better course is to use labeled and numbered examples where you want to
give an example.

A rough count shows 231 uses of example in this document so it isn't a small
problem.

-- 
You are receiving this mail because:
You are the QA Contact for the bug.

Received on Friday, 13 February 2015 22:00:50 UTC