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

On Thu, 23 Mar 2023 08:24:48 +0100
Brar Piening <brar@gmx.de> wrote:

> On 23.03.2023 at 04:09, Karl O. Pinc wrote:

> > Sorry for the extra work I've put you through.  
> 
> No problem. As always I've learnt something which may help me in the
> future.

I don't know about you, but sadly, my brain eventually leaks. ;-)

> > I'm attaching 2 patches
> > with only minor changes.  

> > 001-add-needed-ids_v1.patch
> >
> > This separates out the addition of ids from the XSLT changes, just
> > to keep things tidy. 

> > 002-make_html_ids_discoverable_v4.patch
> >
> > I changed the linked text, the #, so that the leading space
> > is not linked.  This is arguable, as the extra space makes
> > it easier to put the mouse on the region.

> I tend to prefer a slightly bigger mouseover-region but I don't
> really mind.

I'm leaving it for the committer to review.

> I've changed the format of
> > the error message.  What do you think?  (Try it out by _not_
> > applying 001-add-needed-ids_v1.patch.)
> >
> > Also, the error message now has leading and trailing newlines to
> > make it stand out.

Including the error message/make output here, so everyone can see
easily.

--------------<snip>------------
/usr/bin/xsltproc --nonet --path . --stringparam pg.version '16devel'  stylesheet.xsl postgres-full.xml

Ids are required in order to provide the public HTML documentation with stable URLs for <varlistentry> element content; id missing at: /book[@id = 'postgres']/part[@id = 'appendixes']/appendix[@id = 'contrib']/sect1[@id = 'pgwalinspect']/sect2[@id = 'pgwalinspect-funcs']/variablelist
 
no result for postgres-full.xml
make: *** [Makefile:146: html-stamp] Error 10
--------------<snip>------------

> I like it and think it's ready for commiter.

I've marked it ready for the committer in the commitfest.

> > Outstanding questions (for committer?):
> >
> > The 002-make_html_ids_discoverable_v4.patch generates xhtml <h1>,
> > <h2>, etc. attributes using a XSLT <element> element with a
> > "namespace" attribute.  
> 
> I'm not sure I follow. I cannot see any namespacing weirdness in my
> output.

There's nothing weird in the output, it's all about how
you're generating it in the xslt with

 <xsl:element name="h$level" namespace="...

Output looks right to me.

> Are you using the v1.79.2 styleshhets?

Yes.  But I've got both the ones with namespaces and without
installed.

I've just never had to look at what PG is doing with namespaces
before.  What you've done looks right to me, but I'm pretty
clueless so somebody else should double check.]

> > What character should be used to represent a link anchor?  

> Personally I'd advise to stick with ASCII for now.

+1

Regards,

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