Support XSLT 3.0 and other improvements

[bertfrees]

These are some changes I did in order to make the plugin meet our requirements. The main change is the support for XSLT 3.0, which makes it possible to control the visibility of XSLT components, which we need in order to be able to define the public API of our modules.

I still have a list of things that can be improved:

• support for visibility="abstract" and xsl:override
• handle space separated list in mode attribute of xsl:template
• take into account visibility of xsl:mode elements
• when processing xsl:expose, compare component names as EQName instead of strings
• when processing xsl:expose, handle NamedFunctionRef names
• when processing xsl:expose, handle Q{uri}* names
• ...

You can disregard the last commit which is specific to DAISY Pipeline.

[cmarchand]

Thanks a lot, @bertfrees , that's a large improvement. I need some time to validate this, but I have no doubt this should be Ok.
@mricaud , could you help me to review this ?

[mricaud]

Hi guys !

Looks like a really great job @bertfrees !

Maybe I missed something but you add xslt:use-package in <xsl:template match="xslt:import | xslt:include | xslt:use-package"> of get-xfile-dependencies.xsl.
But this element doesn't have an href attribute so it should't work ? (maybe I missed your adding this attribute somewhere before in a package resolution step ?)

Actually I published a new version of get-xfile-dependencies.xsl here. Might be a good idea to add a dependency to call it:

<dependency>
    <groupId>org.mricaud.xml</groupId>
    <artifactId>xut</artifactId>
    <version>0.1.1</version>
</dependency>

Then one could resolve new issues directly there (like package ?)

I unfortunately don't have time to do it now but I can add an issue if you like.

Cheers
Matthieu

[bertfrees]

Thanks for having a look!

I have to confess that I haven't actually been using XSLT 3.0 yet. In order to do these changes I just read the spec. xsl:use-package indeed has no href but a name attribute, I missed that.

Yes, to use your xml-utilities dependency sounds like a good idea. Could one of you guys do it please? I know there is the catalogBuilder-maven-plugin, but I haven't used it before, and I don't know if it will break the Gaulois pipeline.

I can then make another PR for xml-utilities if you like, with these changes. Are the new attributes, type and package-name, OK?

[mricaud]

@cmarchand can you deal with the xut dependency ?
=> Adding the maven dependency will automaticaly trigger the catalog builder to add a new line the generated catalog.xml. Then it should be possible to use the good scheme to point get-xml-file-static-dependency-tree.xsl from any xml tech (gaulois, xproc, xslt..)

I'm not quite sure about these changes.
As far I as understood, the package has to be loaded to the classpath to be used and not from an uri like xsl:import.
get-xml-file-static-dependency-tree.xsl works staticaly by reading the xsl input file, so I don't know how to deal with this ? It would be nice to see how your changes behave on a simple test ?
I added mricaud/xml-utilities#14 to continue the investigation.

[bertfrees]

I'm not sure how Saxon solves the package resolving issue. I haven't tried it, but assumed it would just use the system of URIResolvers that is also used to resolve xsl:import.

This what the spec says about it:

This specification does not define how the implementation locates a package given its name and version. If several matching versions of a package are available, it does not define which of them is chosen. Nor does it define whether this process locates source code or some other representation of the package contents. Such mechanisms are implementation-defined. Use of the package name as a dereferenceable URI is not recommended, because the intent of the packaging feature is to allow a package to be distributed as reusable code and therefore to exist in many different locations.

Anyway, for xsl-doc it should be irrelevant whether the package can be resolved or not, as long as your xsl:use-package contains no xsl:accept with visibility "public" or "final", which we aren't planning to do in DAISY Pipeline. If your xsl:use-package does contain a xsl:accept with visibility "public" or "final", you just have to make sure that the package can be resolved when generating the documentation. Whether doc-available() and document() is the right way to do that, I don't know.

I have made a test here. If you want I could move it to this repository. However it doesn't cover xsl:use-package, exactly because we aren't planning to use it in a way that xsl-doc needs to handle it.

[cmarchand]

In my opinion, xsl:use-package shouldn't be processed by xsl-doc.
Packages are libraries. Packages should have their own documentation, and expose this documentation, and users should consult this documentation to use package.

When, in a Java class, you import an external library, you do not generate this external library javadoc. I do agree problem is a little bit different, but I do not agree to generate a package documentation from a XSL that uses this package.

Saxon requires, to run a XSL that uses a package, that the package has been loaded previously - in the XsltCompiler via importPackage() method. So, currently, there is no PackageResolver, it's up to Java developer to pre-load package before using it. Or packages can be provided on command line via -lib: option

[bertfrees]

OK thanks for the info regarding Saxon.

Packages should have their own documentation, and expose this documentation, and users should consult this documentation to use package.

This is indeed how we are planning to do it. So it's fine for us to drop the support for xsl:use-package in xsl-doc. I decided to try to support it anyway because in theory it is possible to have a xsl:accept with visibility "public" inside the xsl:use-package. What about ignoring xsl:use-package but raise a warning if needed?

<xsl:template match="xsl:use-package">
    <xsl:if test="xslt:accept[@visibility=('public','final')]">
        <!--
            raise warning
        -->
    </xsl:if>
</xsl:template>

[cmarchand]

That sounds a good idea !
I can manage, at least in xslDoc-maven-plugin to display the warning as a Maven Warning.

For xsl:accept, I have to read again specification...

[bertfrees]

Anything else I can do to help here?

[cmarchand]

Excuse me, @bertfrees , I've been very busy these last months. I put this task on the top-most of my list, and plan to merge it current next week.

[bertfrees]

OK thanks! Let me know if I can do something.

[cmarchand]

Did you manage to run successfully all XSpec in maven build ?
I have problems with xspec-maven-plugin...

[bertfrees]

Maybe I forgot to run them. Trying now...

I had to fix something in the POM first (see commit above), but now I'm geting a NullPointerException in the xspec-maven-plugin. The plugin doesn't give me any other information.

[bertfrees]

If I update to the latest version of xspec-maven-plugin:

<plugin>
    <groupId>io.xspec.maven</groupId>
    <artifactId>xspec-maven-plugin</artifactId>
    <version>1.5.2-SNAPSHOT</version>
    <dependencies>
        <dependency>
            <groupId>net.sf.saxon</groupId>
            <artifactId>Saxon-HE</artifactId>
            <version>9.8.0-5</version>
        </dependency>
    </dependencies>

... I get further. It seems I broke some tests. I'll update them.

[cmarchand]

Ok, I get the build work correctly.
Still some fixup to do in XSpec maven plugin !
Thanks a lot

[cmarchand]

Merged, and published release 1.8.

[bertfrees]

Thank you!