Page 1 of 1

Is it possible to display inline documentation for custom XPath/XSLT functions?

Posted: Mon Dec 18, 2017 12:32 pm
by dsxsfs
When you enter a function from the standard XPath library in XSLT, a pop-up appears with syntax rules and a brief explanation. Where is this documentation coming from, and is it possible to add documentation for my custom functions?

Thanks.

Re: Is it possible to display inline documentation for custom XPath/XSLT functions?

Posted: Mon Dec 18, 2017 3:40 pm
by Radu
Hi,

We have some XML configuration files in the main Oxygen library which provide annotations for each XSLT function.
About your custom XSLT functions, are they defined as xsl:functions in the XSLT stylesheet or are they defined in Java extensions?

Regards,
Radu

Re: Is it possible to display inline documentation for custom XPath/XSLT functions?

Posted: Wed Dec 20, 2017 6:03 pm
by dsxsfs
Hi,

These would be simple xsl:function elements that I would put in an XSL file.

Are these .xml files located in a folder somewhere or would I need to dig in a java archive?

Thanks.

Re: Is it possible to display inline documentation for custom XPath/XSLT functions?

Posted: Thu Dec 21, 2017 10:46 am
by Radu
Hi,

So:

These would be simple xsl:function elements that I would put in an XSL file.


Ideally if the xsl:function would have documentation above it like:

Code: Select all

    <xsldoc:doc xmlns:xsldoc="http://www.oxygenxml.com/ns/doc/xsl">
        <xsldoc:desc>Add two params</xsldoc:desc>
        <xsldoc:param name="p1">The first param</xsldoc:param>
        <xsldoc:param name="p2">The second param</xsldoc:param>
    </xsldoc:doc>
    <xsl:function name="abc:add" xmlns:abc="ns">
        <xsl:param name="p1"/>
        <xsl:param name="p2"/>
        <xsl:value-of select="$p1 + $p2"/>
    </xsl:function>


Oxygen should pick up the documentation and use it when proposing the function in the content completion window.
Right now it does not do that so I added an improvement request for it in our internal issues list.

Are these .xml files located in a folder somewhere or would I need to dig in a java archive?


Dig in the main JAR library I'm afraid, open the main "OXYGEN_INSTALL_DIR\lib\oxygen.jar", look for the folder "builtin/xsl-annotations/functions" and it has XML files used depending on the XSLT version.
You can extract such a file (for example xpath-30-functions.xml) outside of Oxygen, and if in the "OXYGEN_INSTALL_DIR\lib\" folder you create a folder structure like this "endorsed/builtin/xsl-annotations/functions/xpath-30-functions.xml", Oxygen should prefer loading the XML from the external location instead of its main JAR library.
Also I'm not sure if just adding the function description there will work or not, this needs to be tested.

Regards,
Radu

Re: Is it possible to display inline documentation for custom XPath/XSLT functions?

Posted: Thu Dec 21, 2017 11:57 am
by dsxsfs
Hi Radu,

I tried adding an extra function to the XML file in the JAR, and that does seem to work.
But that's obviously far from convenient, so I'll either wait until the proposed fix is added, or find an alternative way of documenting my things.

Thanks.

Re: Is it possible to display inline documentation for custom XPath/XSLT functions?

Posted: Thu Dec 21, 2017 12:06 pm
by Radu
Hi,

Agreed. You could start documenting your functions and template using the xd:doc notation:

https://www.oxygenxml.com/doc/versions/19.1/ug-editor/topics/XSLT-Stylesheet-documentation-support.html

and at least Oxygen will help you generate HTML documentation from your XSLT (Tools->Generate Documentation) so that you can share it with others.

Regards,
Radu