[Bug 10850] New: [XQuery11] Editorial: Samples used in specification (ab)use the math prefix

http://www.w3.org/Bugs/Public/show_bug.cgi?id=10850

           Summary: [XQuery11] Editorial: Samples used in specification
                    (ab)use the math prefix
           Product: XPath / XQuery / XSLT
           Version: Member-only Editors Drafts
          Platform: PC
        OS/Version: Windows NT
            Status: NEW
          Severity: normal
          Priority: P2
         Component: XQuery 1.1
        AssignedTo: jonathan.robie@redhat.com
        ReportedBy: oliver@cbcl.co.uk
         QAContact: public-qt-comments@w3.org
             Group: XSLXQuery_WG


The sample module declarations/definitions use in the specification all use the
prefix math.  Now that the prefix math is used throughout the specifications
referring to a different namespace this is potentially confusing.

For example, the sample module import statement (4.2) is:

module namespace math = "http://example.org/math-functions";

This is likely to lead to confusion, as:
a) This breaks the conventions defined in F&O
b) People may take from this that the math namespace is
"http://example.org/math-functions".
c) It could be construed from this that to use the math functions, the math
prefix must be imported as a module.


Another example that needs changing is (4.12):

To illustrate the above rules, suppose that a certain schema defines a type
named triangle. Suppose that a library module imports the schema, binds its
target namespace to the prefix geometry, and declares a function with the
following function signature: math:area($t as geometry:triangle) as xs:double.
If a query wishes to use this function, it must import both the library module
and the schema on which it is based. Importing the library module alone would
not provide access to the definition of the type geometry:triangle used in the
signature of the area function.

The following example illustrates a module import:

import module namespace math =
  "http://example.org/math-functions";

A simple change of prefix would suffice, for example "geometry"; although it
would be nice to change the word math in the namespace URI too.


Similarly in 4.14 (Default namespace declaration):

The following example illustrates the declaration of a default function
namespace:

declare default function namespace 
     "http://example.org/math-functions";

This example could just use http://www.w3.org/2005/xpath-functions/math


4.16 (Variable declarations) has another "bad" example:

The following declaration, which might appear in a library module, declares a
variable whose name includes a namespace prefix:
declare variable $math:pi as xs:double := 3.14159E0;

In this case it is particularly confusing, as there is a function math:pi()!


4.18 Function Declaration:

The following (new) example demonstrates how annotations can be used on
function declarations:

An implementation can define annotations, in its own namespace, to support
functionality beyond the scope of this specification. For instance, an
implementation that supports external Java functions might use an annotation to
associate a Java function with an XQuery external function:

declare %java:method("java.lang.Math.sin") function math:sin($a) external;

However if an implementation did implement this it would be very remiss not to
report the fact that the function math:sin already exists!


4.19 Option Declaration:

declare namespace math = "http://example.org/MathLibrary";
declare option exq:java-class "math = java.lang.Math";

This is another redefinition of the math prefix - probably best to use another
example entirely!

-- 
Configure bugmail: http://www.w3.org/Bugs/Public/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.

Received on Thursday, 30 September 2010 13:42:26 UTC