Horton

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

Karl O. Pinc <kop@karlpinc.com>

View thread View on postgr.es
From: "Karl O. Pinc" <kop@karlpinc.com>
To: Brar Piening <brar@gmx.de>
Cc: Peter Eisentraut <peter.eisentraut@enterprisedb.com>, Tom Lane <tgl@sss.pgh.pa.us>, vignesh C <vignesh21@gmail.com>, Alvaro Herrera <alvherre@alvh.no-ip.org>, Ian Lawrence Barwick <barwick@gmail.com>, pgsql-hackers <pgsql-hackers@postgresql.org>
Date: 2023-01-16T00:28:24Z
Lists: 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 also think that the XSLT should error and halt
when there's no id (in the expected places).  
Instead of just giving a warning and keeping going. Otherwise
they'll constantly be ignored warnings and periodically
there will have to be patches to supply missing ids.

To solve the "which id is missing where so I can fix it"
problem, I propose the error text show the chapter title,
all the enclosing sub-section titles, and any previous existing
varlistentry ids occurring before the tag with the
missing attribute.  At least for varlistentry-s.  For
sections you could do chapter and enclosing sub-section
titles and the title of the section with the problem.
That should be enough for an author to find the place
in the source sgml that needs fixing.

Maybe, possibly, you can see how this is done by looking
at whatever XSLT there is that automatically generates
ids for sections without ids, so that the table of contents
have something to link to.  In any case, XSLT is really
good at "looking at" parent/enclosing XML, so producing
a useful error message shouldn't be _that_ hard.  I've
definitely done this sort of thing before so I can tell you
it's readily doable.

Regards,

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

Commits

  1. doc: Make HTML ids discoverable

  2. Add missing XML ID attribute

  3. postgres_fdw: Add support for parallel abort.

  4. Add missing XML ID attributes

  5. Add XML ID attributes to create_subscription.sgml.

  6. Stop recommending auto-download of DTD files, and indeed disable it.

  7. Doc: add XML ID attributes to <sectN> and <varlistentry> tags.

  8. Allow left join removals and unique joins on partitioned tables

  9. Improve GIN cost estimation