[Bug 28012] New: Unnumbered Definitions – Unidentified Cross-References

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

            Bug ID: 28012
           Summary: Unnumbered Definitions – Unidentified Cross-References
           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

“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.]
***

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

Received on Friday, 13 February 2015 21:01:51 UTC