Re: [PATCH] Add CSS to support discoverable ids in the public documentation website

Hi,

On 4/13/23 9:41 AM, Brar Piening wrote:
> Dear PostgreSQL website maintainers,
> 
> commit e2922702a3 added the XSLT transformation to add links (<a
> href="#...">#</a>) that make elements with ids discoverable to the
> postgresql docs. I expect the links to (unconditionally due to the lack
> of CSS support for now) appear in the devel-docs with the next nightly
> build.
> 
> As suggested in [1] I've created a patch for pgweb that adds the CSS to
> hide the links and display them when hovering the element they are
> referring to.
> 
> Since I wasn't fully aware of the correct procedure, I initially sent
> the patch to pgsql-hackers but I've learnt that it should be sent to
> this list instead.
> 
> Attached is the (unmodified) patch I initially sent to pgsql-hackers in
> [2]. Please see the thread in pgsql-hackers for the discussion so far.

Thanks for doing this! This is something I've personally wanted for the 
docs for years and I'm glad to see it's being done.

I did start testing and overall it looks good -- I have not found any 
glaring problems. I'd like to go through a bit more before committing, 
but that's certainly doable before the PG16 Beta 1 release.

There is a bikesheddable[1] element over what icon we should use: I see 
this range from #, paper clip, paragraph symbol, et al., with those 3 
being the most common.

I personally like the paperclip given how it's synonymous with "link", 
but that may also give the illusion that we also automatically copy the 
link to the clipboard. Perhaps "#" is good enough?

Thanks,

Jonathan

[1] https://en.wiktionary.org/wiki/bikeshedding