Re: [VOTE] Update our documentation building tool chain

[Christophe JAILLET <ch...@wanadoo.fr>]

Le 30/09/2018 à 17:52, Lucien Gentis a écrit :
>
>
> Le 29/09/2018 à 15:42, Lucien Gentis a écrit :
>>
>>
>> Le 29/09/2018 à 09:03, Christophe JAILLET a écrit :
>>> 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
>>> [x] 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
>>> [x] 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.
>>> [x] 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?
>> In addition to XSLT version and XSLT engine updates, why not use 
>> UTF-8 instead of ISO-8859-1 ?
>> It works for all languages while ISO-8859-1 is only for occidental 
>> languages.
>>
>> UTF-8 html files are just a bit longer as ISO-8859-1 : for example 
>> bind.html.fr is 1% longer in UTF-8 than in ISO-8859-1
>> About readability, there's for me no difference between UTF-8 and 
>> ISO-8859-1 files.
>> Last, it solves the two problems :
>> --- man pages are correctly encoded
>> --- html files are generated without HTML entities.
>>
>> I'll try this weekend to rebuild french doc in UTF-8
>
> French doc (trunk) is yet in UTF-8
>
> I replaced all occurrences of "ISO-8859-1" by "UTF-8" in following 
> files :
> manual/style/manual.fr.xsl
> manual/style/xsl/util/designations.xml (only for fr line)
> manual/style/lang/fr.xml
>
> Feel free to give any feedback
>
> Lucien

Hi,

For information, I've updated the "en" files accordingly to switch to 
UTF-8 on trunk. (see r1878788)

Looks good to me, both for html files and man pages.

Tested with OpenJDK 11.0.7

CJ


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