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 28012 - Unnumbered Definitions – Unidentified Cross-References
Summary: Unnumbered Definitions – Unidentified Cross-References
Status: CLOSED WONTFIX
Alias: None
Product: XPath / XQuery / XSLT
Classification: Unclassified
Component: XPath 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:
: 28013 28014 (view as bug list)
Depends on:
Blocks:
 
Reported: 2015-02-13 21:01 UTC by Patrick Durusau
Modified: 2015-03-17 00:13 UTC (History)
2 users (show)

See Also:


Attachments

Description Patrick Durusau 2015-02-13 21:01:49 UTC
“Definitions” have anchors that allow them to be addressed by cross-references, but you should note that cross-references are text hyperlinks that have no identifier by which a reader can find the definition without using the hyperlink. That is to say when I see:

***
A lexical QName with a prefix can be converted into an expanded QName by resolving its namespace prefix to a namespace URI, using the statically known namespaces. (in the paragraph following production [118] of XPath 3.1)
***

The hyperlinks in the original will take me to various parts of the document where these definitions occur, but if I have printed the document, I have no clue where to look for these definitions.

The better practice is to number all the definitions and since they are all self-contained, to put them in a single location. Additionally, all interlinear references to those definitions (or other internal cross-references) should have a visible reference that enables a reader to find the definition or cross-reference, without use of an internal hyperlink.

Example:

***
A lexical QName Def-21 with a prefix can be converted into an expanded QName Def-19 by resolving its namespace prefix to a namespace URI, using the statically known namespaces. Def-99 [These are fake links to draw your attention to the text in question. The Def numbers are fictitious in this example. Actual references would have the visible definition numbers assigned to the appropriate definition.]
***
Comment 1 Michael Kay 2015-02-15 09:19:09 UTC
(Personal response). The Working Groups decided many years ago not to produce "print" versions of the specifications; there was some experimenal work to do so, but no-one felt the results were very satisfactory. Our only definitive publication is in hypertext designed for online viewing, and if you attempt to print that hypertext and find the results unsatisfactory, that is not our problem. I would encourage you to use the specs the way they are designed to be used, namely online hypertext browsing. For that usage, attaching reference numbers to every link and every anchor would be extremely distracting, especially for those specs like XSLT that are very heavily hyperlinked.

Alternatively, we publish the XML, so if you want an alternative rendition, you could work from the XML master.
Comment 2 Andrew Coleman 2015-03-04 14:11:33 UTC
*** Bug 28013 has been marked as a duplicate of this bug. ***
Comment 3 Andrew Coleman 2015-03-04 14:12:10 UTC
*** Bug 28014 has been marked as a duplicate of this bug. ***
Comment 4 Andrew Coleman 2015-03-04 14:19:04 UTC
The Working Group discussed this bug (together with 28013 and 28014) and decided to resolve as WONTFIX, accepting the rationale offered by Mike Kay in comment 1 (namely: for better or worse, the specs are written to be read in an interactive
hypertext system, not on paper).

Many thanks for taking the time to review these documents.
Comment 5 Patrick Durusau 2015-03-17 00:13:22 UTC
I strongly disagree with forcing readers into a particular mode of reading to use the text. Having said that, the wg has chosen otherwise. If IP restrictions allow, I will seek some other remedy for this issue.