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

On Sun, 15 Jan 2023 18:01:50 -0600
"Karl O. Pinc" <kop(at)karlpinc(dot)com> wrote:

> Regards XSLT:
>
> I believe the XSLT needs work.

> I believe that overriding the XSLT by copying the original and making
> modifications is the "wrong way" (TM). I think that the right way is
> to declare a xsl:default-mode somewhere in the stylesheets. There
> does not seem to be one, so the default mode for PG doc processing
> could be something like "postgres-mode". And I'd expect it to be
> declared somewhere right at the top of the xml hierarchy. (I forget
> what that is, probably something like "document" or "book" or
> something.) Then, you'd write your for the <xsl:template
> match="varlistentry"> and <xsl:template name="section.heading"> with
> a mode of "postgres-mode", and have your templates call the
> "traditional default", "modeless", templates. That way your not
> copying and patching upstream code, but are instead, in effect,
> calling it as a subroutine.
>
> This should work especially well since, I think, you're just adding
> new output to what the upstream templates do. You're not trying to
> insert new output into the middle of the stock output or otherwise
> modify the stock output.
>
> You're adding only about 6 lines of XSLT to the upstream templates,
> and copying 100+ lines. There must be a better way.
>
> See: https://www.w3.org/TR/xslt-30/#modes
>
> I've never tried this, although I do recall doing something or another
> with modes in the past. And I've not gone so far as to figure out
> (again?) how to call a "modeless template", so you can invoke the
> original, upstream, templates. And setting a default mode seems like
> something of a "big hammer", so should probably be checked over by
> someone who's more steeped in Postgres docs than myself. (Like a
> committer. :) But I believe it is the way to go. To make it work
> you'll need to figure out the XSLT mode selection process and make
> sure that it first selects the "postgres-mode", and then the modeless
> templates, and also still works right when a template calls another
> and explicitly sets a mode.

Drat. I forgot. We're using xsltproc which is XSLT 1.0.

So this is the relevant spec:

https://www.w3.org/TR/1999/REC-xslt-19991116#modes

In XSLT 1.0 there is no xml:default-mode. So I _think_ what you do then
is modify the built-in template rules so that the (default) template
(mode='') is invoked when there is no 'postgres-mode' version of the
template, but otherwise the 'postgres-mode' version of the template
is invoked. Your 'postgres-mode' templates will xsl:call-template
the default template, adding whatever they want to the output produced
by the default template.

See: https://www.w3.org/TR/1999/REC-xslt-19991116#built-in-rule

Regards,

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