Advanced
Mailing List Archive

Mailing List Archive

  1. Home >
  2. Apache>
  3. Docs
1 2  View All
[VOTE] Update our documentation building tool chain
christophe.jaillet at wanadoo
Sep 29, 2018, 12:03 AM
Post #1 of 29 (6803 views)
Permalink
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
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
christophe.jaillet at wanadoo
Sep 29, 2018, 12:07 AM
Post #2 of 29 (6803 views)
Permalink
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
> [X] 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
>      [X] 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
>      [X] 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
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
covener at gmail
Sep 29, 2018, 6:27 AM
Post #3 of 29 (6803 views)
Permalink
> 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

They don't mean minimums?

Later major JDK's (oracle, IBM) seem to all forks of xalan as the
default transformer, which might explain why there are few
contemporary releases.

Do we need to bring our own at all? Sticking with JDK interfaces has
some benefits.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
lucien.gentis at univ-lorraine
Sep 29, 2018, 6:42 AM
Post #4 of 29 (6803 views)
Permalink
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
>
>
> Thanks for your feedback,
> CJ
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
lucien.gentis at univ-lorraine
Sep 30, 2018, 8:52 AM
Post #5 of 29 (6802 views)
Permalink
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

>>
>>
>> Thanks for your feedback,
>> CJ
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
>> For additional commands, e-mail: docs-help@httpd.apache.org
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
christophe.jaillet at wanadoo
Oct 1, 2018, 1:20 PM
Post #6 of 29 (6796 views)
Permalink
Le 29/09/2018 à 15:27, Eric Covener a écrit :
>> 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
> They don't mean minimums?
>
> Later major JDK's (oracle, IBM) seem to all forks of xalan as the
> default transformer, which might explain why there are few
> contemporary releases.
>
> Do we need to bring our own at all? Sticking with JDK interfaces has
> some benefits.


I've investigate this.

1.6.5 Ant docs state that we need Xalan or another XSLT engine only if
we are using a version of Java older than 1.4.

I guess we can safely assume it is the case nowadays.

However, just removing the Xalan stuff from the lib directory does not
work.
There are some warnings and errors when building.
According to google, the warnings are more or less expected and can be
silently ignored, but the errors break the build process.

First error to trigger is (sory for the mix of English and French):
     [xslt] : Fatal Error! Erreur lors de la vérification du type de
l'expression 'filter-expr(funcall(current, []),
[pred(=(step("attribute", 39), literal-expr(section)))])'. Cause: Erreur
lors de la vérification du type de l'expression
'filter-expr(funcall(current, []), [pred(=(step("attribute", 39),
literal-expr(section)))])'.

This is apparently related to synopsys.sxl.


If I comment:
   <xsl:include href="synopsis.xsl" />
in common.xsl, I then get another error:

    docs/manual/build/build.xml:383: Fatal error during transformation
using /home/tititou36/svn_httpd_trunk/docs/manual/style/manual.en.xsl:
Erreur lors de la vérification du type de l'expression
'com.sun.org.apache.xalan.internal.xsltc.compiler.ForEach@329dbdbf'.

This one looks related to:
    <xsl:for-each select="httpd:override-classes($directives)">
in overrideindex.xsl


The lack of useful (at least to me) diagnostic, makes it hard to find
the root cause of this issues.

Adding -v to the Ant command line doesn't help much either.


So, if any one more used to the Xalan implementation provided in the JDK
could have a look or at least give some pointers, it would be great.

Based on my own tests, and searches, I won't be in any help with this
approach.
The drop-in replacement with Saxon gives much less troubles. :)

CJ


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
lgilbernabe at apache
Oct 1, 2018, 2:14 PM
Post #7 of 29 (6796 views)
Permalink
I have updated long ago the files from es, but i wasn't sure to commit
them as the FR file Lucien is saying.
So now i'm sure it could be done, i will add them to trunk (es modification
only)

@Christophe JAILLET <christophe.jaillet@wanadoo.fr> im not helpfull here,
but i vote +1 to update our build tool :)
rgd

On Mon, 1 Oct 2018 at 22:20, Christophe JAILLET <
christophe.jaillet@wanadoo.fr> wrote:

> Le 29/09/2018 à 15:27, Eric Covener a écrit :
> >> 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
> > They don't mean minimums?
> >
> > Later major JDK's (oracle, IBM) seem to all forks of xalan as the
> > default transformer, which might explain why there are few
> > contemporary releases.
> >
> > Do we need to bring our own at all? Sticking with JDK interfaces has
> > some benefits.
>
>
> I've investigate this.
>
> 1.6.5 Ant docs state that we need Xalan or another XSLT engine only if
> we are using a version of Java older than 1.4.
>
> I guess we can safely assume it is the case nowadays.
>
> However, just removing the Xalan stuff from the lib directory does not
> work.
> There are some warnings and errors when building.
> According to google, the warnings are more or less expected and can be
> silently ignored, but the errors break the build process.
>
> First error to trigger is (sory for the mix of English and French):
> [xslt] : Fatal Error! Erreur lors de la vérification du type de
> l'expression 'filter-expr(funcall(current, []),
> [pred(=(step("attribute", 39), literal-expr(section)))])'. Cause: Erreur
> lors de la vérification du type de l'expression
> 'filter-expr(funcall(current, []), [pred(=(step("attribute", 39),
> literal-expr(section)))])'.
>
> This is apparently related to synopsys.sxl.
>
>
> If I comment:
> <xsl:include href="synopsis.xsl" />
> in common.xsl, I then get another error:
>
> docs/manual/build/build.xml:383: Fatal error during transformation
> using /home/tititou36/svn_httpd_trunk/docs/manual/style/manual.en.xsl:
> Erreur lors de la vérification du type de l'expression
> 'com.sun.org.apache.xalan.internal.xsltc.compiler.ForEach@329dbdbf'.
>
> This one looks related to:
> <xsl:for-each select="httpd:override-classes($directives)">
> in overrideindex.xsl
>
>
> The lack of useful (at least to me) diagnostic, makes it hard to find
> the root cause of this issues.
>
> Adding -v to the Ant command line doesn't help much either.
>
>
> So, if any one more used to the Xalan implementation provided in the JDK
> could have a look or at least give some pointers, it would be great.
>
> Based on my own tests, and searches, I won't be in any help with this
> approach.
> The drop-in replacement with Saxon gives much less troubles. :)
>
> CJ
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
>
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
wrowe at rowe-clan
Oct 1, 2018, 5:28 PM
Post #8 of 29 (6794 views)
Permalink
On Mon, Oct 1, 2018 at 4:15 PM Luis Gil de Bernabé <lgilbernabe@apache.org>
wrote:

> I have updated long ago the files from es, but i wasn't sure to commit
> them as the FR file Lucien is saying.
> So now i'm sure it could be done, i will add them to trunk (es
> modification only)
>
> @Christophe JAILLET <christophe.jaillet@wanadoo.fr> im not helpfull
> here, but i vote +1 to update our build tool :)
> rgd
>

Also +1 to a freshened build toolchain, or trusting the JDK (Open or
otherwise)
to provide the functionality.

Very concerned about trusting utf-8 for anything that is expected to be
console
readable. Not as much the xml/html decorated contents, but the man pages
and any text files concern me. I've been living in a utf-8 console for a
very
long time, but I don't expect my experience is typical.

I'm also not keen on delivering 1%-3% more bytes over the wire where we
can directly represent the contents in an ISO-8859 representation.

That said, shifting to utf-8 also buys us the symbolic sets. Let's avoid
the
emoji's, but various bullets and highlight characters could drastically
improve
the readability of our docs.

So on balance, utf-8 doesn't seem unreasonable, *unless* we expect most
localized users will be reading the plain text of the file.
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
nd at perlig
Oct 1, 2018, 11:57 PM
Post #9 of 29 (6794 views)
Permalink
On Montag, 1. Oktober 2018 23:14:58 CEST Luis Gil de Bernab? wrote:
> I have updated long ago the files from es, but i wasn't sure to commit
> them as the FR file Lucien is saying.
> So now i'm sure it could be done, i will add them to trunk (es
> modification only)

Side note here. All UTF-8 target files have .utf8 as an extension right now
(tr for example). We might need to move all the affected files - or possibly
revisit the httpd manual config. I guess, the former is easier (in terms of
unexpected side effects) and more explicit.

Opinions? If nobody objects I can take care of the file moving part.

Cheers,

>
> @Christophe JAILLET <christophe.jaillet@wanadoo.fr> im not helpfull here,
> but i vote +1 to update our build tool :)
> rgd
>
> On Mon, 1 Oct 2018 at 22:20, Christophe JAILLET <
>
> christophe.jaillet@wanadoo.fr> wrote:
> > Le 29/09/2018 ? 15:27, Eric Covener a ?crit :
> > >> 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
> > >
> > > They don't mean minimums?
> > >
> > > Later major JDK's (oracle, IBM) seem to all forks of xalan as the
> > > default transformer, which might explain why there are few
> > > contemporary releases.
> > >
> > > Do we need to bring our own at all? Sticking with JDK interfaces has
> > > some benefits.
> >
> > I've investigate this.
> >
> > 1.6.5 Ant docs state that we need Xalan or another XSLT engine only if
> > we are using a version of Java older than 1.4.
> >
> > I guess we can safely assume it is the case nowadays.
> >
> > However, just removing the Xalan stuff from the lib directory does not
> > work.
> > There are some warnings and errors when building.
> > According to google, the warnings are more or less expected and can be
> > silently ignored, but the errors break the build process.
> >
> > First error to trigger is (sory for the mix of English and French):
> > [xslt] : Fatal Error! Erreur lors de la v?rification du type de
> >
> > l'expression 'filter-expr(funcall(current, []),
> > [pred(=(step("attribute", 39), literal-expr(section)))])'. Cause: Erreur
> > lors de la v?rification du type de l'expression
> > 'filter-expr(funcall(current, []), [pred(=(step("attribute", 39),
> > literal-expr(section)))])'.
> >
> > This is apparently related to synopsys.sxl.
> >
> > If I comment:
> > <xsl:include href="synopsis.xsl" />
> >
> > in common.xsl, I then get another error:
> > docs/manual/build/build.xml:383: Fatal error during transformation
> >
> > using /home/tititou36/svn_httpd_trunk/docs/manual/style/manual.en.xsl:
> > Erreur lors de la v?rification du type de l'expression
> > 'com.sun.org.apache.xalan.internal.xsltc.compiler.ForEach@329dbdbf'.
> >
> > This one looks related to:
> > <xsl:for-each select="httpd:override-classes($directives)">
> >
> > in overrideindex.xsl
> >
> >
> > The lack of useful (at least to me) diagnostic, makes it hard to find
> > the root cause of this issues.
> >
> > Adding -v to the Ant command line doesn't help much either.
> >
> >
> > So, if any one more used to the Xalan implementation provided in the JDK
> > could have a look or at least give some pointers, it would be great.
> >
> > Based on my own tests, and searches, I won't be in any help with this
> > approach.
> > The drop-in replacement with Saxon gives much less troubles. :)
> >
> > CJ
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> > For additional commands, e-mail: docs-help@httpd.apache.org


"Das Verhalten von Gates hatte mir bewiesen, dass ich auf ihn und seine
beiden Gef?hrten nicht zu z?hlen brauchte" -- Karl May, "Winnetou III"

Im Westen was neues: <http://pub.perlig.de/books.html#apache2>



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
lucien.gentis at univ-lorraine
Oct 2, 2018, 2:01 AM
Post #10 of 29 (6794 views)
Permalink
Le 02/10/2018 à 08:57, André Malo a écrit :
> On Montag, 1. Oktober 2018 23:14:58 CEST Luis Gil de Bernabé wrote:
>> I have updated long ago the files from es, but i wasn't sure to commit
>> them as the FR file Lucien is saying.
>> So now i'm sure it could be done, i will add them to trunk (es
>> modification only)
> Side note here. All UTF-8 target files have .utf8 as an extension right now
> (tr for example). We might need to move all the affected files - or possibly
> revisit the httpd manual config. I guess, the former is easier (in terms of
> unexpected side effects) and more explicit.
>
> Opinions? If nobody objects I can take care of the file moving part.
>
> Cheers,

Do you mean adding .utf8 suffix to all UTF-8 coded html files ?

If so, I think httpd manual config also has to be updated in order
future rebuilds to construct html files with .utf8 suffix :

Example for french :
manual/style/xsl/util/designations.xml : <item charset="UTF-8"
lang="fr">.html.fr</item>
manual/style/lang-targets.xml : <property value=".html.fr"
name="outputext.fr"/>
manual/style/lang/<each language concerned> :
<target-ext>.html.fr</target-ext>

These three xml files are the only ones which contain ".utf8" chain.
>
>> @Christophe JAILLET <christophe.jaillet@wanadoo.fr> im not helpfull here,
>> but i vote +1 to update our build tool :)
>> rgd
>>
>> On Mon, 1 Oct 2018 at 22:20, Christophe JAILLET <
>>
>> christophe.jaillet@wanadoo.fr> wrote:
>>> Le 29/09/2018 à 15:27, Eric Covener a écrit :
>>>>> 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
>>>> They don't mean minimums?
>>>>
>>>> Later major JDK's (oracle, IBM) seem to all forks of xalan as the
>>>> default transformer, which might explain why there are few
>>>> contemporary releases.
>>>>
>>>> Do we need to bring our own at all? Sticking with JDK interfaces has
>>>> some benefits.
>>> I've investigate this.
>>>
>>> 1.6.5 Ant docs state that we need Xalan or another XSLT engine only if
>>> we are using a version of Java older than 1.4.
>>>
>>> I guess we can safely assume it is the case nowadays.
>>>
>>> However, just removing the Xalan stuff from the lib directory does not
>>> work.
>>> There are some warnings and errors when building.
>>> According to google, the warnings are more or less expected and can be
>>> silently ignored, but the errors break the build process.
>>>
>>> First error to trigger is (sory for the mix of English and French):
>>> [xslt] : Fatal Error! Erreur lors de la vérification du type de
>>>
>>> l'expression 'filter-expr(funcall(current, []),
>>> [pred(=(step("attribute", 39), literal-expr(section)))])'. Cause: Erreur
>>> lors de la vérification du type de l'expression
>>> 'filter-expr(funcall(current, []), [pred(=(step("attribute", 39),
>>> literal-expr(section)))])'.
>>>
>>> This is apparently related to synopsys.sxl.
>>>
>>> If I comment:
>>> <xsl:include href="synopsis.xsl" />
>>>
>>> in common.xsl, I then get another error:
>>> docs/manual/build/build.xml:383: Fatal error during transformation
>>>
>>> using /home/tititou36/svn_httpd_trunk/docs/manual/style/manual.en.xsl:
>>> Erreur lors de la vérification du type de l'expression
>>> 'com.sun.org.apache.xalan.internal.xsltc.compiler.ForEach@329dbdbf'.
>>>
>>> This one looks related to:
>>> <xsl:for-each select="httpd:override-classes($directives)">
>>>
>>> in overrideindex.xsl
>>>
>>>
>>> The lack of useful (at least to me) diagnostic, makes it hard to find
>>> the root cause of this issues.
>>>
>>> Adding -v to the Ant command line doesn't help much either.
>>>
>>>
>>> So, if any one more used to the Xalan implementation provided in the JDK
>>> could have a look or at least give some pointers, it would be great.
>>>
>>> Based on my own tests, and searches, I won't be in any help with this
>>> approach.
>>> The drop-in replacement with Saxon gives much less troubles. :)
>>>
>>> CJ
>>>
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
>>> For additional commands, e-mail: docs-help@httpd.apache.org
>
> "Das Verhalten von Gates hatte mir bewiesen, dass ich auf ihn und seine
> beiden Gefährten nicht zu zählen brauchte" -- Karl May, "Winnetou III"
>
> Im Westen was neues: <http://pub.perlig.de/books.html#apache2>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
bfg at blenning
Oct 2, 2018, 3:21 AM
Post #11 of 29 (6794 views)
Permalink
On 02/10/2018 02:28, William A Rowe Jr wrote:
> On Mon, Oct 1, 2018 at 4:15 PM Luis Gil de Bernabé <lgilbernabe@apache.org>
> wrote:
>
>> I have updated long ago the files from es, but i wasn't sure to commit
>> them as the FR file Lucien is saying.
>> So now i'm sure it could be done, i will add them to trunk (es
>> modification only)
>>
>> @Christophe JAILLET <christophe.jaillet@wanadoo.fr> im not helpfull
>> here, but i vote +1 to update our build tool :)
>> rgd
>>
>
> Also +1 to a freshened build toolchain, or trusting the JDK (Open or
> otherwise)
> to provide the functionality.

The toolchain will as far as I understand only be used to build. I don't
understand under which circumstances this would be problematic.

> Very concerned about trusting utf-8 for anything that is expected to be
> console
> readable. Not as much the xml/html decorated contents, but the man pages
> and any text files concern me. I've been living in a utf-8 console for a
> very
> long time, but I don't expect my experience is typical.

I would say that this is the usual experience. I've been trying to find
data on this with no luck, but I would suggest that with perhaps
exception of the English only world, there is an overwhelming majority
who uses UTF-8. If you only use ASCII, as in English, UTF-8 and
ISO-8859-1 becomes the same.

> I'm also not keen on delivering 1%-3% more bytes over the wire where we
> can directly represent the contents in an ISO-8859 representation.

Again, if you're using ASCII only, there is no such overhead. Delivering
entities is a lot more expensive. If at all significant, I expect to see
bandwidth usage drop and not increase.

> That said, shifting to utf-8 also buys us the symbolic sets. Let's avoid
> the
> emoji's, but various bullets and highlight characters could drastically
> improve
> the readability of our docs.

I'm a bit out on a limb here, but AFAICR, these symbols are represented
with 4 byte width and occurs in predictable codepages. It should be easy
to set up a build test that fails if used. If anything, this should be
avoided, because even though fairly widely used, they are a relatively
new introduction. Things may break even though UTF-8 support is in place.

> So on balance, utf-8 doesn't seem unreasonable, *unless* we expect most
> localized users will be reading the plain text of the file.

And even then it's easier than entities.

Attached Files:

Re: [VOTE] Update our documentation building tool chain [ In reply to ]
rainer.jung at kippdata
Oct 2, 2018, 6:54 AM
Post #12 of 29 (6794 views)
Permalink
Am 29.09.2018 um 09:03 schrieb Christophe JAILLET:
> 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
> [ ] 3.0 - the later the better, and/or the new functionalities rock!

Not qualified to answer.

> 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
> [X] 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
>      [X] Axe it

If possible.

>    - 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!

1.9 or 1.10 would be OK for me.

Regards,

Rainer


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
rbowen at rcbowen
Oct 2, 2018, 7:40 AM
Post #13 of 29 (6794 views)
Permalink
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
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
jorton at redhat
Oct 2, 2018, 8:08 AM
Post #14 of 29 (6794 views)
Permalink
On Sat, Sep 29, 2018 at 09:03:46AM +0200, Christophe JAILLET wrote:
> Do we need to change something?
> ==============================
> [X] 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

Didn't seem mutually exclusive ;) I'm strongly in the "just make it
work" camp and break whatever you need to get there!

> What version of XSLT is best for us?
> Should we change our XSLT engine?

fine with changing if required, no idea really on technical differences

> What is the oldest version of Java we should support?

whatever works, I'm personally fine with 8 as minimum.


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
wrowe at rowe-clan
Oct 2, 2018, 9:28 AM
Post #15 of 29 (6794 views)
Permalink
On Tue, Oct 2, 2018 at 5:21 AM Tom Fredrik Blenning <bfg@blenning.no> wrote:

>
> On 02/10/2018 02:28, William A Rowe Jr wrote:
> >
> > Very concerned about trusting utf-8 for anything that is expected to be
> > console
> > readable. Not as much the xml/html decorated contents, but the man pages
> > and any text files concern me. I've been living in a utf-8 console for a
> > very
> > long time, but I don't expect my experience is typical.
>
> I would say that this is the usual experience. I've been trying to find
> data on this with no luck, but I would suggest that with perhaps
> exception of the English only world, there is an overwhelming majority
> who uses UTF-8. If you only use ASCII, as in English, UTF-8 and
> ISO-8859-1 becomes the same.
>

It would be great to have that data.


> > I'm also not keen on delivering 1%-3% more bytes over the wire where we
> > can directly represent the contents in an ISO-8859 representation.
>
> Again, if you're using ASCII only, there is no such overhead. Delivering
> entities is a lot more expensive. If at all significant, I expect to see
> bandwidth usage drop and not increase.
>

Adding to that thought, we are just making the jump from &encoded forms,
so any growth in file size is still smaller than the historical
representations.


> I'm a bit out on a limb here, but AFAICR, these symbols are represented
> with 4 byte width and occurs in predictable codepages. It should be easy
> to set up a build test that fails if used. If anything, this should be
> avoided, because even though fairly widely used, they are a relatively
> new introduction. Things may break even though UTF-8 support is in place.
>

Arrows, Misc Tech symbols, Block symbols character blocks all fall into
3-byte width encoding. I agree that more modern emoji etc are more
problematic for several reasons.
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
rpluem at apache
Oct 5, 2018, 4:03 AM
Post #16 of 29 (6784 views)
Permalink
On 10/02/2018 05:08 PM, Joe Orton wrote:
> On Sat, Sep 29, 2018 at 09:03:46AM +0200, Christophe JAILLET wrote:
>> Do we need to change something?
>> ==============================
>> [X] 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
>
> Didn't seem mutually exclusive ;) I'm strongly in the "just make it
> work" camp and break whatever you need to get there!
>
>> What version of XSLT is best for us?
>> Should we change our XSLT engine?
>
> fine with changing if required, no idea really on technical differences
>
>> What is the oldest version of Java we should support?
>
> whatever works, I'm personally fine with 8 as minimum.
>

+1 to all statements from Joe above.

Regards

Rüdiger


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
toscano.luca at gmail
Oct 6, 2018, 12:34 AM
Post #17 of 29 (6783 views)
Permalink
Il giorno mar 2 ott 2018 alle ore 15:55 Rainer Jung
<rainer.jung@kippdata.de> ha scritto:
>
> Am 29.09.2018 um 09:03 schrieb Christophe JAILLET:
> > 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
> > [ ] 3.0 - the later the better, and/or the new functionalities rock!
>
> Not qualified to answer.
>
> > 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
> > [X] 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
> > [X] Axe it
>
> If possible.
>
> > - 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!
>
> 1.9 or 1.10 would be OK for me.
>
> Regards,
>
> Rainer


+1 to what Rainer said.

Thanks a lot for this work!!

Luca

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
covener at gmail
Jan 7, 2020, 5:41 PM
Post #18 of 29 (6049 views)
Permalink
Digging around in docs-build via Mikes recent thread reminded me of all this.

Christophe, any interest/cycles to revisit? It might be nice to move
up before this analysis ages too much.

My thought to proceed after reviewing the thread: Should we
collaborate on a new docs-build w/ java8 min, external ant, saxon,
old jars removed, and minimal patch to style/ included? I think this
keeps us out of anyones way just trying to build and check in xforms.

On Sat, Oct 6, 2018 at 3:35 AM Luca Toscano <toscano.luca@gmail.com> wrote:
>
> Il giorno mar 2 ott 2018 alle ore 15:55 Rainer Jung
> <rainer.jung@kippdata.de> ha scritto:
> >
> > Am 29.09.2018 um 09:03 schrieb Christophe JAILLET:
> > > 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
> > > [ ] 3.0 - the later the better, and/or the new functionalities rock!
> >
> > Not qualified to answer.
> >
> > > 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
> > > [X] 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
> > > [X] Axe it
> >
> > If possible.
> >
> > > - 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!
> >
> > 1.9 or 1.10 would be OK for me.
> >
> > Regards,
> >
> > Rainer
>
>
> +1 to what Rainer said.
>
> Thanks a lot for this work!!
>
> Luca
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>


--
Eric Covener
covener@gmail.com

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
christophe.jaillet at wanadoo
Jan 8, 2020, 1:33 PM
Post #19 of 29 (6048 views)
Permalink
Hi Eric,

I was just about to remind @dev about this known issue.

Yes, interested to dig further, but honestly, I lack time since several
months.
If I recollect correctly:
   - there is still some corner issues with saxon. (and a few patches
already in trunk, waiting for 2.4.x)
   - it is not possible to handle both saxon and xalan, because of some
incompatible syntax

The main issue about entities generated with latest java in that it
breaks man pages.

As pointed out by Lucien, using UTF-8 is a solution that has already
been used for the French, and Spanish if I remember correctly.

However, I think that there could still be an issue with man pages
generation.
With the latest java, it is just garbage, but using UTF-8 in man.en.xsl
seems to work.

How-ever I'm not sure that the UTF-8 "trick" would work in all build
targets (chm, zip, war, latex which are certainly used by no one but
still available). I also don't know if they are broken or still of any use.



Another approach I tried a few months ago was related to:
   <xsl:output method="text" encoding="ISO-8859-1" indent="no" />
(in use actually, and logical based on my understanding of some java docs)

vs

   <xsl:output method="text" encoding="iso8859_1" indent="no" />    (
(found in a slightly different context on
https://ant.apache.org/manual/Tasks/style.html, § "Using output properties")

This seems to work for html.en file and also for man pages.


but I didn't get time enough to test it correctly. And Google was not
really my friend neither to understand the underlying difference of
"ISO-8859-1" vs "iso8859_1", nor what is "the correct one to use".

Testing would mean for me getting the same result with java8 up to
java12 (or 13?).
Checking that is not that easy on mu Ubuntu VM because older versions of
java are no more supported and available. I have to install other VM to
test with older version of Ubuntu and java.


Will try to find time in the coming weeks. (no promise)
The only step done in my proposals was axing jakarta. (r1853689 and
r1853690)

I also started to test some ant upgrades, but I have the same issues
with testing the un-usual targets (chm, zip, war,...)

CJ


Le 08/01/2020 à 02:41, Eric Covener a écrit :
> Digging around in docs-build via Mikes recent thread reminded me of all this.
>
> Christophe, any interest/cycles to revisit? It might be nice to move
> up before this analysis ages too much.
>
> My thought to proceed after reviewing the thread: Should we
> collaborate on a new docs-build w/ java8 min, external ant, saxon,
> old jars removed, and minimal patch to style/ included? I think this
> keeps us out of anyones way just trying to build and check in xforms.
>
> On Sat, Oct 6, 2018 at 3:35 AM Luca Toscano<toscano.luca@gmail.com> wrote:
>> Il giorno mar 2 ott 2018 alle ore 15:55 Rainer Jung
>> <rainer.jung@kippdata.de> ha scritto:
>>> Am 29.09.2018 um 09:03 schrieb Christophe JAILLET:
>>>> 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
>>>> [ ] 3.0 - the later the better, and/or the new functionalities rock!
>>> Not qualified to answer.
>>>
>>>> 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
>>>> [X] 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
>>>> [X] Axe it
>>> If possible.
>>>
>>>> - 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!
>>> 1.9 or 1.10 would be OK for me.
>>>
>>> Regards,
>>>
>>> Rainer
>> +1 to what Rainer said.
>>
>> Thanks a lot for this work!!
>>
>> Luca
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail:docs-unsubscribe@httpd.apache.org
>> For additional commands, e-mail:docs-help@httpd.apache.org
>>


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
nd at perlig
Jan 8, 2020, 11:14 PM
Post #20 of 29 (6045 views)
Permalink
On Mittwoch, 8. Januar 2020 22:33:19 CET Christophe JAILLET wrote:
> Hi Eric,
>
> I was just about to remind @dev about this known issue.
>
> Yes, interested to dig further, but honestly, I lack time since several
> months.
> If I recollect correctly:
> - there is still some corner issues with saxon. (and a few patches
> already in trunk, waiting for 2.4.x)
> - it is not possible to handle both saxon and xalan, because of some
> incompatible syntax
>
> The main issue about entities generated with latest java in that it
> breaks man pages.
>
> As pointed out by Lucien, using UTF-8 is a solution that has already
> been used for the French, and Spanish if I remember correctly.
>
> However, I think that there could still be an issue with man pages
> generation.
> With the latest java, it is just garbage, but using UTF-8 in man.en.xsl
> seems to work.
>
> How-ever I'm not sure that the UTF-8 "trick" would work in all build
> targets (chm, zip, war, latex which are certainly used by no one but
> still available). I also don't know if they are broken or still of any
> use.

chm and zip I'd keep (they should be in use), war can certainly be killed.
The chm format cannot handle UTF-8 though.

If you'd ask me, I'd rather kill XML/XSLT entirely, as the promises both for
Java and XML/XSLT clearly don't hold anymore. However this also requires
time and effort...

Cheers,
nd
--
Flhacs wird im Usenet grunds?tzlich alsfhc geschrieben. Schreibt man
lafhsc nicht slfach, so ist das schlichtweg hclafs. Hingegen darf man
rihctig ruhig rhitcgi schreiben, weil eine shcalfe Schreibweise bei
irhictg nicht als shflac angesehen wird. -- Hajo Pfl?ger in dnq



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
rbowen at rcbowen
Feb 20, 2020, 10:15 AM
Post #21 of 29 (5834 views)
Permalink
On 1/9/20 2:14 AM, André Malo wrote:
> If you'd ask me, I'd rather kill XML/XSLT entirely, as the promises both for
> Java and XML/XSLT clearly don't hold anymore. However this also requires
> time and effort...

Revisiting a thread that somewhat died out ... I would also be very much
in favor of moving away from XML/Docbook, and towards something
Markdown-based.

The current toolchain has served us very well, but given the discussion
in the "Building docs ..." thread, maybe the time has come to move to
something a little more modern?

--
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
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
isoma at c8h10n4o2
Feb 20, 2020, 10:28 AM
Post #22 of 29 (5834 views)
Permalink
The cloud native computing foundation (especially Kubernetes) is largely
using Hugo and it seems to work well.

Tim

On 20 February 2020 18:16:11 Rich Bowen <rbowen@rcbowen.com> wrote:

> On 1/9/20 2:14 AM, André Malo wrote:
>> If you'd ask me, I'd rather kill XML/XSLT entirely, as the promises both for
>> Java and XML/XSLT clearly don't hold anymore. However this also requires
>> time and effort...
>
> Revisiting a thread that somewhat died out ... I would also be very much
> in favor of moving away from XML/Docbook, and towards something
> Markdown-based.
>
> The current toolchain has served us very well, but given the discussion
> in the "Building docs ..." thread, maybe the time has come to move to
> something a little more modern?




---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
lgilbernabe at apache
Feb 20, 2020, 1:51 PM
Post #23 of 29 (5834 views)
Permalink
I vote up for any upgrade.


El jue., 20 feb. 2020 19:28, Tim Bannister <isoma@c8h10n4o2.org.uk>
escribió:

> The cloud native computing foundation (especially Kubernetes) is largely
> using Hugo and it seems to work well.
>
> Tim
>
> On 20 February 2020 18:16:11 Rich Bowen <rbowen@rcbowen.com> wrote:
>
> > On 1/9/20 2:14 AM, André Malo wrote:
> >> If you'd ask me, I'd rather kill XML/XSLT entirely, as the promises
> both for
> >> Java and XML/XSLT clearly don't hold anymore. However this also requires
> >> time and effort...
> >
> > Revisiting a thread that somewhat died out ... I would also be very much
> > in favor of moving away from XML/Docbook, and towards something
> > Markdown-based.
> >
> > The current toolchain has served us very well, but given the discussion
> > in the "Building docs ..." thread, maybe the time has come to move to
> > something a little more modern?
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
>
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
nd at perlig
Feb 20, 2020, 2:23 PM
Post #24 of 29 (5834 views)
Permalink
Rich Bowen wrote:
> On 1/9/20 2:14 AM, Andr? Malo wrote:
> > If you'd ask me, I'd rather kill XML/XSLT entirely, as the promises both
> > for Java and XML/XSLT clearly don't hold anymore. However this also
> > requires time and effort...
>
> Revisiting a thread that somewhat died out ... I would also be very much
> in favor of moving away from XML/Docbook, and towards something
> Markdown-based.

Markdown is not powerful enough (by design, but well). I'd suggest
restructured text instead. It needs some getting used to, but it should be
able to map all features we need and/or want.

Cheers,
--
"Solides und umfangreiches Buch"
-- aus einer Rezension

<http://pub.perlig.de/books.html#apache2>



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [VOTE] Update our documentation building tool chain [ In reply to ]
mrumph68 at gmail
Feb 21, 2020, 8:26 AM
Post #25 of 29 (5834 views)
Permalink
Found a bug report related to this which was last changed on 2018-08-06:
Bug 57878 - Using UTF-8 for all languages, and avoiding html-entities.
- https://bz.apache.org/bugzilla/show_bug.cgi?id=57878

Mike

On Thu, Feb 20, 2020 at 2:23 PM André Malo <nd@perlig.de> wrote:

> Rich Bowen wrote:
> > On 1/9/20 2:14 AM, André Malo wrote:
> > > If you'd ask me, I'd rather kill XML/XSLT entirely, as the promises
> both
> > > for Java and XML/XSLT clearly don't hold anymore. However this also
> > > requires time and effort...
> >
> > Revisiting a thread that somewhat died out ... I would also be very much
> > in favor of moving away from XML/Docbook, and towards something
> > Markdown-based.
>
> Markdown is not powerful enough (by design, but well). I'd suggest
> restructured text instead. It needs some getting used to, but it should be
> able to map all features we need and/or want.
>
> Cheers,
> --
> "Solides und umfangreiches Buch"
> -- aus einer Rezension
>
> <http://pub.perlig.de/books.html#apache2>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
>
1 2  View All

©2024 GT.net. A Gossamer Threads company.
5th Floor, 455 Granville St., Vancouver, BC V6C 1T1, Canada | Legal