Bug #5974: SaxonJS documentation does not address namespaces - SaxonJS - Saxonica Developer Community

Actions

Send by e-mail Copy link

Bug #5974

closed

SaxonJS documentation does not address namespaces

Added by Joel Kalvesmaki over 1 year ago. Updated about 1 year ago.

Status:

Closed

Priority:

Normal

Assignee:

Debbie Lockett

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:

SaxonJS 2.6

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

Updated by John Lumley over 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

Copy link

Updated by Debbie Lockett over 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

Copy link

Updated by Joel Kalvesmaki over 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

Copy link