Project

Profile

Help

Bug #5974

closed

SaxonJS documentation does not address namespaces

Added by Joel Kalvesmaki about 1 year ago. Updated 6 months ago.

Status:
Closed
Priority:
Normal
Category:
Documentation
Sprint/Milestone:
-
Start date:
2023-04-13
Due date:
% Done:

100%

Estimated time:
Applies to JS Branch:
2, Trunk
Fix Committed on JS Branch:
2, Trunk
Fixed in JS Release:
SEF Generated with:
Platforms:
Company:
-
Contact person:
-
Additional contact persons:
-

Description

Using the following as my guide... https://www.saxonica.com/saxon-js/documentation2/index.html#!browser/events https://www.saxonica.com/saxon-js/demos2/cities ...and the demo from 2021 I was unable to get the most basic interactive functionality off the ground. Turns out that the the template match attributes in the examples above either didn't say what the default namespace was or matched only the no-namespace namespace, and so the templates in my environment didn't get off the ground.

For the cities demo, I downloaded all the pieces one, by one, and got the initial template to work, but no column sorting. Had to add xpath-default-namespace="http://www.w3.org/1999/xhtml" to get it going. For the parallel project I was working on I found it easiest to do some *:div, *:button etc. for the match patterns.

Easy fix here, just massage the documentation and example so that users are aware front and center that they need to be namespace-aware.

If Saxon develops a SaxonJS FAQ with the question, Why won't my events fired?, the namespace topic should be one of the first things mentioned.

Thanks for all the great work put into this!

Actions #1

Updated by John Lumley about 1 year ago

Joel,

The key is given in the documentation for Compiling stylesheets using Saxon-EE https://www.saxonica.com/saxon-js/documentation2/index.html#!starting/export/compiling-using-XJ where a SEF is exported using the -ns:##html5 command line option:

  • -ns:##html5 declares that an unprefixed element name will match either a name in the XHTML namespace, or a name in no namespace. This is to ensure that the resulting behavior is close to that defined by the special rules in the HTML5 specification for XSLT and XPath running against an HTML5 DOM. This command line option is new in Saxon 10, and its use is necessary for SEFs which are to be run under SaxonJS 2 in the browser.

I pretty much always use this.

I'll leave Debbie or Norm to decide on any documentation changes and move this issue to the Saxon-JS project.

Actions #2

Updated by Debbie Lockett about 1 year ago

  • Project changed from Saxon to SaxonJS
  • Category set to Documentation
  • Priority changed from Low to Normal

There is also further in depth explanation about the use of the -ns option at https://www.saxonica.com/saxon-js/documentation2/index.html#!xdm/nodes, which you might find useful.

But you are definitely right that we could improve the documentation on this issue, this is indeed something that frequently trips people up (probably everyone?!).

Adding a FAQ section is a good idea, and it seems like adding some more warnings/pointers about this (e.g. from the pages you mentioned) would be useful.

Actions #3

Updated by Joel Kalvesmaki about 1 year ago

Thanks John and Debbie for the extra pointers, which I hadn't known about.

When I work with a new technology, I tend to go straight for the examples, and then, as needed, visit other parts of the documentation. Any annotations proximate to, or within, those examples are key for orientation.

Such a great technology. I hope it gets widely adopted!

Actions #4

Updated by Debbie Lockett 6 months ago

  • Status changed from New to Resolved
  • Assignee set to Debbie Lockett
  • Applies to JS Branch 2, Trunk added
  • Fix Committed on JS Branch 2, Trunk added

Documentation updates committed. SaxonJS 2 documentation online will be updated with the 2.6 maintenance release.

Actions #5

Updated by Debbie Lockett 6 months ago

  • Status changed from Resolved to Closed
  • % Done changed from 0 to 100
  • Fixed in JS Release set to SaxonJS 2.6

Bug fix applied in the SaxonJS 2.6 maintenance release.

Please register to edit this issue

Also available in: Atom PDF Tracking page