httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <rbo...@rcbowen.com>
Subject Re: [VOTE] Update our documentation building tool chain
Date Tue, 02 Oct 2018 14:40:29 GMT
I, for one, would love to see us move to something MarkDown based. 
However, 1) that would be a HUGE amount of work and 2) it would take a 
lot more work to make something MD-based support all of the fancy 
features that we have hacked into our existing engine over the years.

However, I must also acknowledge that the torch is passed, and I'm not 
particularly active any more. So I must be in the "do what makes sense" 
camp.

On 9/29/18 3:03 AM, Christophe JAILLET wrote:
> Hi,
> 
> 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 
> 9.8.0.14 (well, a 9.9.0.1 was released 2 days ago, but there is no 
> details yet)
> My first results are:
>     - a "build.sh 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 
> rock!
> 
>     - any other topic?
> 
> 
> Thanks for your feedback,
> CJ
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
> 

-- 
Rich Bowen - rbowen@rcbowen.com
http://rcbowen.com/
@rbowen

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message