Project

Profile

Help

Actions
Send by e-mail Copy link

Bug #5974

open

SaxonJS documentation does not address namespaces

Added by Joel Kalvesmaki about 2 months ago. Updated about 2 months ago.

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

0%

Estimated time:
Applies to JS Branch:
Fix Committed on JS Branch:
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
Copy link
 #1

Updated by John Lumley about 2 months 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
Copy link
 #2

Updated by Debbie Lockett about 2 months 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
Copy link
 #3

Updated by Joel Kalvesmaki about 2 months 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!

Please register to edit this issue

Actions
Send by e-mail Copy link

Also available in: Atom PDF Tracking page