W3C home > Mailing lists > Public > public-qt-comments@w3.org > February 2015

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

From: <bugzilla@jessica.w3.org>
Date: Fri, 13 Feb 2015 21:06:03 +0000
To: public-qt-comments@w3.org
Message-ID: <bug-28013-523@http.www.w3.org/Bugs/Public/>
https://www.w3.org/Bugs/Public/show_bug.cgi?id=28013

            Bug ID: 28013
           Summary: Unnumbered Definitions – Unidentified Cross-References
           Product: XPath / XQuery / XSLT
           Version: Candidate Recommendation
          Hardware: PC
                OS: Linux
            Status: NEW
          Severity: normal
          Priority: P2
         Component: XQuery 3.1
          Assignee: jonathan.robie@gmail.com
          Reporter: patrick@durusau.net
        QA Contact: public-qt-comments@w3.org

This is a duplicate of 28012 but on a different component. I was unable to
select multiple components for a recurring issue in each component. Sorry.


“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:06:05 UTC

This archive was generated by hypermail 2.3.1 : Friday, 13 February 2015 21:06:05 UTC