Re: doc: add missing "id" attributes to extension packaging page

On Tue, 14 Feb 2023 12:13:18 -0800
Andres Freund <andres@anarazel.de> wrote:

> A small note: As-is this fails on CI, because we don't allow network
> access during the docs build anymore (since it always fails these
> days):
> 
> https://cirrus-ci.com/task/5474029402849280?logs=docs_build#L297
> 
> [17:02:03.114] time make -s -j${BUILD_JOBS} -C doc
> [17:02:04.092] I/O error : Attempt to load network entity
> http://cdn.docbook.org/release/xsl/current/html/sections.xsl
> [17:02:04.092] warning: failed to load external entity
> "http://cdn.docbook.org/release/xsl/current/html/sections.xsl"
> [17:02:04.092] compilation error: file stylesheet-html-common.xsl
> line 17 element import [17:02:04.092] xsl:import : unable to load
> http://cdn.docbook.org/release/xsl/current/html/sections.xsl

This makes me think that it would be useful to add --nonet to the
xsltproc invocations.  That would catch this error before it goes to
CI.

> I think this is just due to the common URL in docbook packages being
> http://docbook.sourceforge.net/release/xsl/current/*
> Because of that the docbook catalog matching logic won't work for
> that file:
> 
> E.g. I have the following in /etc/xml/docbook-xsl.xml, on debian
> unstable: <delegateURI
> uriStartString="http://docbook.sourceforge.net/release/xsl/"
> catalog="file:///usr/share/xml/docbook/stylesheet/docbook-xsl/catalog.xml"/>
> 
> As all our other references use the sourceforge address, this should
> too.

Agreed.

I'm also noticing that the existing xsl:import-s all import entire
docbook stylesheets.  It does not hurt to do this; the output is
unaffected, although I can't say what it means for build performance.
It does keep it simple.  Only one import is needed no matter which
templates we use the import mechanism to extend.  And by importing
"everything" there's no concern about any (unlikely) changes to
the the "internals" of the catalog.

Should we import only what we need or all of docbook?  I don't know.

Regards,

Karl <kop@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein