Re: doc: add missing "id" attributes to extension packaging page - Mailing list pgsql-hackers

On Sun, 15 Jan 2023 18:01:50 -0600
"Karl O. Pinc" <kop@karlpinc.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@karlpinc.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein