httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christophe JAILLET <>
Subject [VOTE] Update our documentation building tool chain
Date Sat, 29 Sep 2018 07:03:46 GMT

There is a bug in the Xalan, the XSLT 1.0 engine we are using, that 
prevents our doc building tool chain to generate correct documentation.

By not correct, I mean:
    - ISO-8859-1 non ASCII characters are replaced again by their HTML 
entities equivalent (in the French doc for example)
    - breaks the man pages generation

A possible workaround is to use UTF-8 instead of ISO-8859-1.
The only drawback I see, is that some html files will be slightly bigger 
and a bit less readable because of the use of entities. This is not a 
that big problem.

However, Xalan looks mostly unmaintained since about 10 years. 
Xalan-Java 2.7.1, the one we are using, was released in November 2007. 
The latest release is Xalan-Java 2.7.2 on released in April 2014. This 
is mainly a maintenance release which fixes a CVE and a few bugs.

As per Xalan documentation, the JDK or JRE 1.3.x (2000), 1.4.x (2002), 
or 5.x (2004) is required.
As per our doc build documentation, we need at least Java 1.2 (1998) to 
build the doc.
Java 8 (2014) is LTS and is supported until 2025
Java 9 (2017)
Java 10 (2018)
Java 11 (2018) is apparently LTS

Another XSLT engine could also be used. I've tried the latest Saxon (well, a was released 2 days ago, but there is no 
details yet)
My first results are:
    - a " all" takes ~3 min, instead of ~2 min with Xalan
    - generated files looks just fine
    - it removes some spaces only XML nodes. The generated code is 
slightly smaller.
      The generated code could be slightly less readable in some cases. 
I've not seen
      any issue in the rendering of the pages without these few spaces
    - Saxon is XSLT 3.0. This could be used to simplify our xsl files.
      However, I've looked at the 2.0 and 3.0 changes, and I'm not sure 
we could have
      a real use of it. Maybe dynamic Xpath, more built-in functions 
available or
      Text Value Templates?
      Not sure either that we need to upgrades the rules at all. It 
already works great.
    - this is a drop-in replacement. We just need to replace 2 jar files
      by a new one. That's all
    - We only need yo change a <func:function to a <xsl:function and the 
doc build
      out of the box
    - as per Saxon doc, it require Java 5+, 6+ or 8+ depending of the 
version we take

So, now is your turn to give your feeling about it:

Do we need to change something?
[ ] this mail is too long, do whatever you want, I just want something 
that works
[ ] no. I can leave with the current tool chain
[ ] yes. Let clean some dust and update what is needed

What version of XSLT is best for us?

[ ] 1.0 - this is what I'm used to, keep things stable
[ ] 2.0
[ ] 3.0 - the later the better, and/or the new functionalities rock!

Should we change our XSLT engine?
[ ] No, I love Xalan and it is ASF. Just move to UTF-8 everywhere.
[ ] Yes and Saxon is a good candidate. The license of the Home Edition
     is Mozilla Public License version 2.0.
[ ] Yes and ______ should be used instead

What is the oldest version of Java we should support?
[ ] 1.2 - what we claim now
[ ] 1.3 - what is needed required by Xalan 1.7.1
[ ] 1.4
[ ] 5.0 - what is required by Saxon 9.6
[ ] 6 - what is required by Saxon 9.7 and 9.8
[ ] 7
[ ] 8 - what is required by the latest Saxon 9.9
[ ] 9
[ ] 10
[ ] 11

Depending of the minimum Java requirement consensus, we could also 
wonder if:
    - we still need jakarta-oro Regex parser (ASF, but retired since 
2010-09-01). Regex in Java are considered stable since a long time now
      [ ] keep it
      [ ] Axe it

    - we need to upgrade Ant. (Latest is 1.10.5. Ant 1.9.*: JDK 1.5+, 
Ant 1.8.*: JDK 1.4+, Ant 1.7.*: JDK 1.3+, Ant 1.6.*: JDK 1.2+)
      [ ] keep 1.6.5, we don't need to change
      [ ] 1.9.x, recent enough, still maintained, but not the latest. 
Should be the more stable
      [ ] 1.10.x, the later the better, and/or the new functionalities 

    - any other topic?

Thanks for your feedback,

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message