Re: Re: [COMMITTERS] pgsql: Build HTML documentation using XSLT stylesheets by default

On 11/30/16 1:52 PM, Tom Lane wrote:
> However, speed may be the least of its problems. I just noticed that it's
> inserting commas at random places in syntax summaries :-(. For instance,
> the "overlay" entry in table 9.8 looks like
>
> overlay(string, placing
> string, from int [for int])
>
> Neither comma belongs there according to the SGML source, and I don't see
> them in guaibausaurus' rendering of the page:
> https://www.postgresql.org/docs/devel/static/functions-string.html
>
> So I'm forced to the conclusion that I need a newer version of the
> toolchain and/or style sheets. If you've got any idea of just what
> needs to be updated, that would be real helpful. xsltproc itself
> is from "libxslt-1.1.26-2.el6_3.1.x86_64" but I'm unsure what packages
> contain relevant style sheets.

OK, I got it. The component of concern is the DocBook XSL stylesheets,
called docbook-style-xsl on RH-like systems (docbook-xsl on Debian). If
it runs too slow, it's probably too old.

Here you can see a list of available versions:
http://docbook.sourceforge.net/release/xsl/

I noticed a significant slow-down with versions older than 1.76.1. And
indeed CentOS/RHEL 6 comes with 1.75.2.

Also, the issue with the extra commas mentioned above goes away with 1.78.0.

Here is the trick why this isn't reproducible for some:

The local stylesheet file stylesheet.xsl references
http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl. If
you have the docbook-style-xsl package installed, then this URL gets
redirected to your local installation through the XML catalog mechanism.
If you don't have the package installed locally, then xsltproc will
download the stylesheet files from that actual URL and cache them
locally. So if you have an old docbook-style-xsl version, you get old
and slow behavior. If you uninstall it or just never installed it, you
get the latest from the internet.

If you don't want to mess with your local packages, you can also prevent
the use of the XML catalog by setting the environment variable
XML_CATALOG_FILES to empty (e.g., XML_CATALOG_FILES='' make html).

There is some work to be done here to document this and make sure we
wrap releases with appropriate versions and so on, but I hope this
information can keep everyone moving for now.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services