Horton

Thread

Commits

  1. docs: Work around bug in the docbook xsl stylesheets.

  2. Fix XML namespace declarations

  1. fixing bookindex.html bloat

    Andres Freund <andres@anarazel.de> — 2022-02-13T20:16:18Z

    Hi,

Sometime last year I was surprised to see (not on a public list unfortunately)
that bookindex.html is 657kB, with > 200kB just being repetitions of
xmlns="http://www.w3.org/1999/xhtml" xmlns:xlink="http://www.w3.org/1999/xlink"

Reminded of this, due to a proposal to automatically generate docs as part of
cfbot runs (which'd be fairly likely to update bookindex.html), I spent a few
painful hours last night trying to track this down.


The reason for the two xmlns= are different. The
xmlns="http://www.w3.org/1999/xhtml" is afaict caused by confusion on our
part.

Some of our stylesheets use
xmlns="http://www.w3.org/TR/xhtml1/transitional"
others use
xmlns="http://www.w3.org/1999/xhtml"

It's noteworthy that the docbook xsl stylesheets end up with
<html xmlns="http://www.w3.org/1999/xhtml">
so it's a bit pointless to reference http://www.w3.org/TR/xhtml1/transitional
afaict.

Adding xmlns="http://www.w3.org/1999/xhtml" to stylesheet-html-common.xsl gets
rid of xmlns="http://www.w3.org/TR/xhtml1/transitional" in bookindex specific
content.

Changing stylesheet.xsl from transitional to http://www.w3.org/1999/xhtml gets
rid of xmlns="http://www.w3.org/TR/xhtml1/transitional" in navigation/footer.

Of course we should likely change all http://www.w3.org/TR/xhtml1/transitional
references, rather than just the one necessary to get rid of the xmlns= spam.


So far, so easy. It took me way longer to understand what's causing the
all the xmlns:xlink= appearances.

For a long time I was misdirected because if I remove the <xsl:template
name="generate-basic-index"> in stylesheet-html-common.xsl, the number of
xmlns:xlink drastically reduces to a handful. Which made me think that their
existance is somehow our fault. And I tried and tried to find the cause.

But it turns out that this originally is caused by a still existing buglet in
the docbook xsl stylesheets, specifically autoidx.xsl. It doesn't omit xlink
in exclude-result-prefixes, but uses ids etc from xlink.

The reason that we end up with so many more xmlns:xlink is just that without
our customization there ends up being a single
<div xmlns:xlink="http://www.w3.org/1999/xlink" class="index">
and then everything below that doesn't need the xmlns:xlink anymore. But
because stylesheet-html-common.xsl emits the div, the xmlns:xlink is emitted
for each element that autoidx.xsl has "control" over.

Waiting for docbook to fix this seems a bit futile, I eventually found a
bugreport about this, from 2016: https://sourceforge.net/p/docbook/bugs/1384/

But we can easily reduce the "impact" of the issue, by just adding a single
xmlns:xlink to <div class="index">, which is sufficient to convince xsltproc
to not repeat it.


Before:
-rw-r--r-- 1 andres andres 683139 Feb 13 04:31 html-broken/bookindex.html
After:
-rw-r--r-- 1 andres andres 442923 Feb 13 12:03 html/bookindex.html

While most of the savings are in bookindex, the rest of the files are reduced
by another ~100kB.


WIP patch attached. For now I just adjusted the minimal set of
xmlns="http://www.w3.org/TR/xhtml1/transitional", but I think we should update
all.

Greetings,

Andres Freund

  2. Re: fixing bookindex.html bloat

    Andres Freund <andres@anarazel.de> — 2022-02-13T20:42:05Z

    Hi,

On 2022-02-13 12:16:18 -0800, Andres Freund wrote:
> Waiting for docbook to fix this seems a bit futile, I eventually found a
> bugreport about this, from 2016:
> https://sourceforge.net/p/docbook/bugs/1384/

Now also reported to the current repo:
https://github.com/docbook/xslt10-stylesheets/issues/239

While there's been semi-regular changes / fixes, they've not done a release in
years... So even if they fix it, it'll likely not trickle down into distro
packages etc anytime soon, if ever.

Greetings,

Andres Freund

  3. Re: fixing bookindex.html bloat

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-02-14T17:31:25Z

    On 13.02.22 21:16, Andres Freund wrote:
> The reason for the two xmlns= are different. The
> xmlns="http://www.w3.org/1999/xhtml" is afaict caused by confusion on our
> part.
> 
> Some of our stylesheets use
> xmlns="http://www.w3.org/TR/xhtml1/transitional"
> others use
> xmlns="http://www.w3.org/1999/xhtml"
> 
> It's noteworthy that the docbook xsl stylesheets end up with
> <html xmlns="http://www.w3.org/1999/xhtml">
> so it's a bit pointless to reference http://www.w3.org/TR/xhtml1/transitional
> afaict.
> 
> Adding xmlns="http://www.w3.org/1999/xhtml" to stylesheet-html-common.xsl gets
> rid of xmlns="http://www.w3.org/TR/xhtml1/transitional" in bookindex specific
> content.
> 
> Changing stylesheet.xsl from transitional to http://www.w3.org/1999/xhtml gets
> rid of xmlns="http://www.w3.org/TR/xhtml1/transitional" in navigation/footer.
> 
> Of course we should likely change all http://www.w3.org/TR/xhtml1/transitional
> references, rather than just the one necessary to get rid of the xmlns= spam.

Yeah, that is currently clearly wrong.  It appears I originally copied 
the wrong namespace declarations from examples that show how to 
customize the DocBook stylesheets, but those examples were apparently 
wrong or outdated in this respect.  It seems we also lack some namespace 
declarations altogether, as shown by your need to add it to 
stylesheet-html-common.xsl.  This appears to need some careful cleanup.

> The reason that we end up with so many more xmlns:xlink is just that without
> our customization there ends up being a single
> <div xmlns:xlink="http://www.w3.org/1999/xlink" class="index">
> and then everything below that doesn't need the xmlns:xlink anymore. But
> because stylesheet-html-common.xsl emits the div, the xmlns:xlink is emitted
> for each element that autoidx.xsl has "control" over.
> 
> Waiting for docbook to fix this seems a bit futile, I eventually found a
> bugreport about this, from 2016: https://sourceforge.net/p/docbook/bugs/1384/
> 
> But we can easily reduce the "impact" of the issue, by just adding a single
> xmlns:xlink to <div class="index">, which is sufficient to convince xsltproc
> to not repeat it.

I haven't fully wrapped my head around this.  I tried adding xlink to 
our own exclude-result-prefixes, but that didn't seem to have the right 
effect.

  4. Re: fixing bookindex.html bloat

    Andres Freund <andres@anarazel.de> — 2022-02-14T17:51:04Z

    Hi,

On 2022-02-14 18:31:25 +0100, Peter Eisentraut wrote:
> > The reason that we end up with so many more xmlns:xlink is just that without
> > our customization there ends up being a single
> > <div xmlns:xlink="http://www.w3.org/1999/xlink" class="index">
> > and then everything below that doesn't need the xmlns:xlink anymore. But
> > because stylesheet-html-common.xsl emits the div, the xmlns:xlink is emitted
> > for each element that autoidx.xsl has "control" over.
> > 
> > Waiting for docbook to fix this seems a bit futile, I eventually found a
> > bugreport about this, from 2016: https://sourceforge.net/p/docbook/bugs/1384/
> > 
> > But we can easily reduce the "impact" of the issue, by just adding a single
> > xmlns:xlink to <div class="index">, which is sufficient to convince xsltproc
> > to not repeat it.
> 
> I haven't fully wrapped my head around this.  I tried adding xlink to our
> own exclude-result-prefixes, but that didn't seem to have the right effect.

It can't, because it's not one of our stylesheets that causes the xlink: stuff
to be included. It's autoidx.xls - just adding xlink to autoidx's
exclude-result-prefixes fixes the problem "properly", but we can't really
modify it.

The reason adding xmlns:xlink to our div (or even higher up) helps is that
then nodes below it don't need to include it again (when output by autoidx),
which drastically reduces the number of xmlns:xlink. So it's just a somewhat
ugly workaround, but for >100kB it seems better than the alternative.

Greetings,

Andres Freund

  5. Re: fixing bookindex.html bloat

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-02-14T22:06:20Z

    On 14.02.22 18:31, Peter Eisentraut wrote:
> Yeah, that is currently clearly wrong.  It appears I originally copied 
> the wrong namespace declarations from examples that show how to 
> customize the DocBook stylesheets, but those examples were apparently 
> wrong or outdated in this respect.  It seems we also lack some namespace 
> declarations altogether, as shown by your need to add it to 
> stylesheet-html-common.xsl.  This appears to need some careful cleanup.

The attached patch cleans up the xhtml namespace declarations properly, 
I think.

For the xlink business, I don't have a better idea than you, so your 
workaround proposal seems fine.

  6. Re: fixing bookindex.html bloat

    Andres Freund <andres@anarazel.de> — 2022-02-14T23:06:51Z

    Hi,

On 2022-02-14 23:06:20 +0100, Peter Eisentraut wrote:
> The attached patch cleans up the xhtml namespace declarations properly, I
> think.

Looks good to me.


> For the xlink business, I don't have a better idea than you, so your
> workaround proposal seems fine.

K. Will you apply your patch, and then I'll push mine ontop?

Greetings,

Andres Freund

  7. Re: fixing bookindex.html bloat

    Peter Eisentraut <peter.eisentraut@enterprisedb.com> — 2022-02-15T10:16:12Z

    On 15.02.22 00:06, Andres Freund wrote:
> On 2022-02-14 23:06:20 +0100, Peter Eisentraut wrote:
>> The attached patch cleans up the xhtml namespace declarations properly, I
>> think.
> 
> Looks good to me.
> 
> 
>> For the xlink business, I don't have a better idea than you, so your
>> workaround proposal seems fine.
> 
> K. Will you apply your patch, and then I'll push mine ontop?

done

  8. Re: fixing bookindex.html bloat

    Andres Freund <andres@anarazel.de> — 2022-02-15T21:55:12Z

    On 2022-02-15 11:16:12 +0100, Peter Eisentraut wrote:
> On 15.02.22 00:06, Andres Freund wrote:
> > On 2022-02-14 23:06:20 +0100, Peter Eisentraut wrote:
> > > For the xlink business, I don't have a better idea than you, so your
> > > workaround proposal seems fine.
> > 
> > K. Will you apply your patch, and then I'll push mine ontop?
> 
> done

done as well.