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 28017 - Vague references – $N versus 5000 x $N
Summary: Vague references – $N versus 5000 x $N
Status: RESOLVED DUPLICATE of bug 28015
Alias: None
Product: XPath / XQuery / XSLT
Classification: Unclassified
Component: XQuery 3.1 (show other bugs)
Version: Candidate Recommendation
Hardware: PC Linux
: P2 normal
Target Milestone: ---
Assignee: Jonathan Robie
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:24 UTC by Patrick Durusau
Modified: 2015-03-17 08:14 UTC (History)
2 users (show)

See Also:


Attachments

Description Patrick Durusau 2015-02-13 21:24:25 UTC
A duplicate of 28015 but on a different component. I was unable to choose multiple components for a single commment. 

By way of illustration:

[Definition: An atomic value is a value in the value space of an atomic type, as defined in [XML Schema 1.0] or [XML Schema 1.1].] [Definition: A node is an instance of one of the node kinds defined in [XQuery and XPath Data Model (XDM) 3.1].

In the example, you and I both know somewhere in XML Schema 1.0 and XML Schema 1.1 that the “value space of the atomic type” is defined. The same is true for nodes and XQuery and XPath Data Model (XDM) 3.1. But where? The authors of these specifications could insert that information at a cost of $N.

What is the cost of not inserting that information in the current drafts? I estimate the number of people interested in reading these drafts to be 5,000. So each of those person will have to find the same information omitted from these specifications, which is a cost of 5,000 x $N. In terms of convenience to readers and reducing their costs of reading these specifications, references to exact locations in other materials are a necessity.

Vague references are also problematic in terms of users finding the correct reference. The citation above, [XML Schema 1.0] for “value space of an atomic type,” refers to all three parts of XML Schema 1.0.

Part 1, at 3.14.1 (non-normative) The Simple Type Definition Schema Component, has the only reference to “atomic type.”

Part 2, actually has “0” hits for “atomic type.” True enough, “2.5.1.1 Atomic datatypes” is likely the intended reference but that isn’t what the specification says to look for.

Bottom line is that any external reference needs to include in the inline citation the precise internal reference in the work being cited. If you want to inconvenience readers by pointing to internal bibliographies rather than online HTML documents, where available, that’s an editorial choice. But in any event, for every external reference, give the internal reference in the work being cited.

Your readers will appreciate it and it could make your work more accurate as well.
Comment 1 C. M. Sperberg-McQueen 2015-03-03 20:20:39 UTC
As instructed by the XML Query and XSLT WGs on today's joint call, I'm closing this bug as WONTFIX.  For the rationale of this decision, please see bug 28015.
Comment 2 Patrick Durusau 2015-03-16 23:45:07 UTC
See my comments at: https://www.w3.org/Bugs/Public/show_bug.cgi?id=28016
Comment 3 Michael Kay 2015-03-17 08:14:31 UTC
I'm closing this as a duplicate because it costs everyone time and money to have three identical bug reports open and to try to track three separate conversations on the same topic.

*** This bug has been marked as a duplicate of bug 28015 ***