Feature #4241: Improve documentation for IXSL extensions - SaxonJS - Saxonica Developer Community

Actions

Send by e-mail Copy link

Feature #4241

closed

Improve documentation for IXSL extensions

Added by Debbie Lockett over 5 years ago. Updated over 4 years ago.

Status:

Closed

Priority:

Normal

Assignee:

Debbie Lockett

Category:

Sprint/Milestone:

Start date:

2019-06-25

Due date:

% Done:

100%

Estimated time:

Applies to JS Branch:

1.0, Trunk

Fix Committed on JS Branch:

1.0, Trunk

Fixed in JS Release:

SEF Generated with:

Platforms:

Company:

Contact person:

Additional contact persons:

Description

Initiated by the forum discussion at https://saxonica.plan.io/boards/5/topics/7515, where it was suggested that it would be good to add an example using ixsl:get() to obtain a more complicated nested property, e.g. ixsl:get($event, 'touches.0.clientX') for event.touches[0].clientX.

In fact, it would be good to review and expand the IXSL extensions documentation in general. To include more examples; and tidy up the information generally. And specifically to align and provide more information about nested properties - as relevant to ixsl:call() ixsl:get(), and ixsl:set-property.

Actions

Copy link

Updated by Debbie Lockett over 5 years ago

Currently examples are included in the "Details" section for the extension functions, while the extension instructions have a separate section for "Examples". It would be good to also extract the function examples into corresponding "Examples" sections: (1) to improve clarity on the functions pages, and (2) to better align the functions and instructions pages.

Note that the structure and format of these pages is adopted (with few changes) from the main Saxon documentation, where the XSL Element Reference pages include an "Examples" section, but Function Library pages do not. It would be good to update the app XSL stylesheets for generating the IXSL extensions section pages, to make this change, and also make further improvements to share template rules where appropriate.

Actions

Copy link

Updated by Debbie Lockett over 5 years ago

Status changed from New to In Progress

Documentation updates committed on Saxon-JS 1.x branch.

App stylesheets:

The new stylesheet el-fnd-body.xsl contains template rules extracted from elements-body.xsl and functions-body.xsl, where the template rules can be shared for processing elements common to the two namespaces (e.g. description, status, details, examples, see-also).
General tidy up for all stylesheets.
New 9.9.1.2 SEF export.

Documentation content (doc/development.xml and ixsl-extension.xml):

Added examples for all IXSL functions and instructions.
General review and tidy up for IXSL extensions section.
"Properties of JavaScript objects" section added (development/properties).

Actions

Copy link

Updated by Debbie Lockett over 5 years ago

Status changed from In Progress to Resolved
Fix Committed on JS Branch 1.0 added

Saxon-JS 1.2.0 documentation updated online.

Actions

Copy link

Updated by Pieter Masereeuw over 5 years ago

Thank you very much for giving the documentation of interfacing with JavaScript more body. I found it very useful to read the new texts and I think that many other users of Saxon-JS will also benefit!

Actions

Copy link

Updated by Debbie Lockett over 5 years ago

Status changed from Resolved to In Progress

Some further documentation corrections for IXSL function signatures, and instruction descriptions:

for ixsl:apply(), ixsl:call(), ixsl:eval(), ixsl:get() return type is item()* rather than item()? (i.e. sequences allowed)
for ixsl:set-style, ixsl:set-property, name attribute has type { token } not eqname
for ixsl:remove-attribute, name attribute has type { eqname } not eqname (i.e. AVT allowed, like ixl:set-attribute/@name)
for ixsl:remove-attribute, namespace attribute is not implemented, so remove reference