This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.
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.
There was substantial sympathy for the point raised here when the XML Query and XSLT working groups discussed this bug report on their joint call today. In some cases, of course, the specs do point to specific passages of the external specs, but not in all. In particular, when in the editors' judgement the specific reference is important for correct understanding of the passage in our own spec, the editors attempt to provide specific references. If there are particular cases in which more specific reference is essential to understanding, but only generic reference is provided, then it would be helpful to raise bugs against the particular cases. At the same time, however, there was reluctance to adopt a general rule that all references to other specs be accompanied by the identification of specific passages in those specs, and the WGs did not adopt any such general rule in our discussion today. In some cases, it would be difficult to identify one specific location in the other spec. The notion that simple types (including but not limited to atomics) possess a lexical space and a value space is so fundamental to XSD's system of simple types, and so pervasive, that the identification of a specific textual locus would seem pointless. In this particular case, the situation of a reader who does not know what a value space is will not in fact be made much more comfortable by a specific reference to the definition of 'value space' in XSD Part 2, since the editors of XSD 1.0 are on record as saying many times that the XSD spec was written only for implementors, and that the difficulties of other readers were of no consequence. But even if we assume, for the sake of argument, that a specific location could almost always usefully be cited, and that doing so would save the reader a bit of time, the WGs see no prospect of following consistently and in all cases the good advice given here. We agree that it would be good to save the reader's time, but the reader's time doesn't come from the same budget as the editor's time. We do not believe we have the resources necessary to instruct our editors to adopt this principle. Accordingly, I am closing this bug with the status WONTFIX. This is intended to signal that we agree, in principle, that in a perfect world the specs would do a better job on this point. But in this imperfect world, given the choice of accepting this imperfection and the delays which would be incurred by attempting to remove it, we choose to an imperfect but published spec over a perfect but perpetually unfinished one. Patrick, in your role as originator of the bug report, you now have the responsibility of changing the status of the bug from RESOLVED to CLOSED, to signal that you are satisfied that the WGs have given serious consideration to your comment and that you are willing to accept the WGs' resolution of the issue, or else to change the status to REOPEN, to indicate that you are not willing to accept the WGs' proposed disposition of the comment. If we haven't heard back from you in two weeks, we will take your silence to mean consent. Thank you for your careful reading and comments; I am sorry we were unable to resolve this issue in a more satisfactory way.
I have thought very long and hard about asking the wg to reopen this issue. I was nearly persuaded by Michael's comments but I want to make sure the wg understands the consequences of "wontfix," the full consequences of "wontfix." I concede at the outset that there are many standards, due to poor structuring, are more difficult to reference than others. However, there are references in this group of four standards, that were closely coordinated according to the PR, that are just a vague as to historical references we all use in XML. To say nothing of internal references that also lack section titles/numbers. I am sure that to the editors and members of the wg, all of these documents are nearly transparent. That is no surprise given the amount of attention and time that has been invested in them. But the goal of these documents was to be standards, not memos of a common understanding reached by a small group over the months/years of working on these documents. A standard for electrical plugs or railway track isn't much of a standard if anyone approaching it had better be a regular attendee at the meetings creating it. I don't mean to minimize the burden structuring and cross-referencing would put on the editors. Been there and done that personally. And there is no need to fear a long list of definitions in part of the document. Definitions at appropriate places are not a problem so long as they can be cited with certainly and not batches of definitions strung together. Separation of definitions from each other also has the advantage that any comment to be made about the subject of that definition can be made in place. One need not worry that somewhere else in the document there is another statement about that item. (I am not saying that is the case here, I got stuck on organization issues and haven't reached pulling every item and its mentions out of this group of texts.) I deeply appreciate all of the work that has gone into these drafts and hope that at a minimum, internal references and references between these drafts can be made more useful for readers and hopefully other implementors. Patrick
[personal response] | A standard for electrical plugs or railway track isn't much of a | standard if anyone approaching it had better be a regular attendee | at the meetings creating it. Since we had over 50 implementations of XQuery 1 and XPath 2, I'm not sure that comments like this are productive. Clearly people outside the Working Groups were able to implement the specifications. In some cases such people sent test results, without having previously contacted us. That's not to say the documents are perfect and could never be improved. But they are not as bad as you imply.
Well if you want this work done on the documents I edit, you're going to have to find another editor. I haven't got the time.
(In reply to Liam R E Quin from comment #3) > [personal response] > > | A standard for electrical plugs or railway track isn't much of a > | standard if anyone approaching it had better be a regular attendee > | at the meetings creating it. > > Since we had over 50 implementations of XQuery 1 and XPath 2, I'm not sure > that comments like this are productive. Clearly people outside the Working > Groups were able to implement the specifications. In some cases such people > sent test results, without having previously contacted us. > > That's not to say the documents are perfect and could never be improved. But > they are not as bad as you imply. Personal: Liam I think you took my comment more personally than I ever intended. My point was to illustrate that drafting a document a group understands isn't the same thing as drafting a standard for public consumption. I took great pains to express my appreciation for the work on these documents so I would ask that you re-read my comments as trying to make a useful distinction, if poorly worded. BTW, I never said the documents were "bad," or even implied that. I said readers could read them more easily with specific references between these "coordinated" drafts. Why do you take criticism = bad? Patrick
Patrick, you did comment more positively overall - I just took issue with that one statement, and didn't want it to remain on the record unchallenged. We go to a lot of trouble to try and make sure the specs can be implemented by people outside the Working Group, of course. If we've failed in that then the specs would be pretty bad at meeting their purpose. You've done a detailed and careful review which is much appreciated, but which, unfortunately, the two Working Groups don't have resources to give the consideration that it deserves.
*** Bug 28016 has been marked as a duplicate of this bug. ***
*** Bug 28017 has been marked as a duplicate of this bug. ***
Patrick, Most people when they raise bug reports use a title that summarizes the problem they are raising. You chose, for some reason, to use a title that asserts monetary value in fixing the problem. I don't know why you did that, but I think it was a bad mistake, because it encourages us to think hard about costs and benefits, and that is likely to have the opposite effect from the one intended. On a back-of-an-envelope calculation, I would estimate the investment in creating this family of specifications as being somewhere in the order of $10m. Some of this cost has been borne by large companies, some by start-ups; a lot of it is actually free time given by volunteers who earned nothing for the work. By contrast, our readers get free use of the material. Some of our readers (companies like Intel and Altova) have built significant commercial products using these specifications as design input, for which they have contributed nothing. I'm not complaining: we know what we are doing. But many members of the WG are struggling to justify travel costs or continuing participation to their management: do you seriously think that the argument "we need to spend more money so that our competitors can reduce their costs" is going to carry much weight? Our readers are getting a free lunch. You are telling us it would be a better free lunch if we added caviar. We also need to question your assumption that improving the rigour of the specifications will increase their value. The most successful specification produced by these working groups to date, measured by the number of people using implementations of the spec, is (by a large margin) XPath 1.0. Yet XPath 1.0 is also (by a large margin) the least rigorous of the specifications. To put it in perspective, the specification of the sum() function has increased from 26 words in XPath 1.0 to about 320 words in XPath 3.1. There was a cost in doing that, which one could attempt to measure. Can we start to measure the value? Was it a good return on investment? Is there any evidence that XPath 3.1 implementations are cheaper to produce as a result? I very much doubt it. I think all the evidence points the other way. Most of us, like you, are obsessive perfectionists by nature, and we do this kind of "improvement" work because it is in our character to do it. Anyone holding the purse-strings and looking at the value of the work would tell us to stop now and ship the thing. Sorry that this comment is totally unrelated to the true subject of your bug report. But that's your fault, for choosing a title that was unrelated to the subject.
Patrick, I'm responding both as co-chair of the XML Query WG *and* as somebody who has been deeply involved in de jure standardization for three decades, as well as editor of an extremely large suite of standards (ISO/IEC 9075, Database Language SQL). I'm deeply sympathetic to the concern you've raised. As you implied, it's a common concern amongst many standards, probably most standards in the ICT field. However, as you well know, standardization is a delicate balancing act of tensions in multiple dimensions. One of those dimensions is, of course, cost vs benefit, to which you alluded in your initial comment. Another is the classic problem of "good, fast, and cheap -- pick two" (in this case, "good" represents quality of specification, "fast" represents the length of time to develop the specification, and "cheap" represents the cost of developing the spec). Yet a third is time-to-publication vs value-to-implementers -- a more valuable spec (in, for example, the terms you suggest in your initial comment) almost certainly guarantees a delay in publication. That delay is not necessarily reduceable by adding more resources (see "The Mythical Man-Month"), but a sufficiently long delay may well make the standard no longer timely, either because implementers have gone ahead and implemented *something* or because they've decided to go an entirely different direction. Because my full-time job for the last 30 years has been standardization, and particularly editing the SQL standard, I have had the luxury of paying incredible attention to details of the kind that seem to concern you. Almost nobody else on the planet involved in data management standards has that luxury, and our increasingly limited resources in the XML Query WG and XSLT WG do not include anybody whose full time job is QT standards. With both sympathy and respect for your view and your comments, I have to say that I do not believe that it is possible for us to head in the direction you'd like us to go (with respect to this bug, at least). If you were able to join the WG, we would happily accept the additional resources you might be able to offer to pursue this direction. Without that, we are simply unable to respond favorably at this point in the development of XQuery and its associated documents. Sorry! Jim
The WG has made a significant effort to improve many of the references in the documents given the time and resources available. This has been done under more specific bug reports. We have therefore decided to resolve this generic bug as fixed.