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 29825 - [FO31] (editorial) Some inline code samples with more than one function name in it get hyperlinked, leading to hard-to-read text
Summary: [FO31] (editorial) Some inline code samples with more than one function name ...
Status: CLOSED FIXED
Alias: None
Product: XPath / XQuery / XSLT
Classification: Unclassified
Component: Functions and Operators 3.1 (show other bugs)
Version: Candidate Recommendation
Hardware: PC Windows NT
: P2 editorial
Target Milestone: ---
Assignee: Michael Kay
QA Contact: Mailing list for public feedback on specs from XSL and XML Query WGs
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2016-09-15 19:19 UTC by Abel Braaksma
Modified: 2016-12-16 19:55 UTC (History)
0 users

See Also:

Attachments

Description Abel Braaksma 2016-09-15 19:19:29 UTC 
The formula used for calculating idiv is hard to read because it is fully underlined and linked to the fn:abs function. There are more functions in this calculation, it seems odd to link it to fn:abs, or to link it at all. 

I suggest to either link the individual functions, or to remove the link entirely.

The hyperlinked text in 4.2.5 is: 

fn:abs($N * $arg2) le fn:abs($arg1) and fn:compare($N * $arg2, 0) eq fn:compare($arg1, 0).

As an aside, I think writing it out is (arguably) more readable:

fn:abs($N * $arg2) le fn:abs($arg1) 
and 
fn:compare($N * $arg2, 0) eq fn:compare($arg1, 0)
Comment 1 Michael Kay 2016-09-15 22:44:19 UTC 
Unfortunately the markup and stylesheet I inherited in F+O doesn't mark up function names with <function>fn:abs</function>, it marks them as <code>fn:abs</code>, and the stylesheet interprets a code element starting with fn: as a hyperlink. Horrid, but it's a lot of work to change it.
Comment 2 Abel Braaksma 2016-09-16 13:09:45 UTC 
How does it work on other places then? For instance, the following appears to be formatted as <code>...</code>, but does not get underlined:

From 4.5.1. fn:number
* The expression fn:number($item2/description) returns xs:double('NaN').
* Then fn:number() returns 1.5e1.

There appears to be a certain randomness, but the majority goes right for inline code samples (when starting with a function name), and where it is just the QName of the function, not a code sample, it is about a 6:4 chance:

* code samples, 15x wrong, 2+ fu names linked
  with: //code[(parent::*:a)][text()[matches(., '^[fma]\w+:\c+.*\w+:\w+')]]

* code samples, 169x right (no linking for 2+ fu names)
  with: //code[not(parent::*:a)][text()[matches(., '^[fma]\w+:\c+.*\w+:\w+')]]

* single function names, 406 times arguably wrong (no linking)
  with: //code[not(parent::*:a)][text()[matches(., '[fma]\w+:[\c#]+$')]]

* function names, 570 times right (with linking)
  with: //code[parent::*:a][text()[matches(., '[fma]\w+:[\c#]+$')]]

But I understand that, esp. if it is hard to fix, there are better things to do right now.
Comment 3 Michael Kay 2016-09-20 21:35:53 UTC 
Many of those that are not underlined are marked up as executable examples rather than with code markup:

            <fos:test>
               <fos:expression>fn:number($item1/quantity)</fos:expression>
               <fos:result>5.0e0</fos:result>
            </fos:test>

There is actually a step in the build process to run these examples as test cases, but it's a while since I ran it (mainly because until recently, there have been many examples that weren't yet executable in Saxon).
Comment 4 Michael Kay 2016-09-20 22:06:00 UTC 
I have changed the stylesheet so that it only creates a hyperlink for <code> markup if the code consists of a standalone QName (not part of a larger expression).

I have changed the code in 4.2.5 to use block-level <eg> markup instead of inline <code> markup.
Comment 5 Abel Braaksma 2016-09-21 00:40:03 UTC 
Thanks, that's a good readability improvement (I assume with QName you also mean to underline function references like fn:concat#3?)