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

On Wed, Apr 19, 2023 at 4:08 PM Jonathan S. Katz <jkatz(at)postgresql(dot)org> wrote:
> 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?

Not to contribute to the dreaded bikeshedding, but David Rowley and
I were actually chatting about our favorite hover-over icons after we
noticed the new "#" on the online docs.

Personally, I don't really like the paragraph symbol for our use case,
because we are now allowing linking to specific elements that do not
have a section number. For example a specific GUC on a page [1]. Python
docs use the hover-over paragraph symbol [2] but they appear to only
link to numbered sections that are accessible via the table of contents.

I find the "#" pretty meaningless and the paper clip a bit silly.
Personally, I think the link icon is the nicest. David pointed out [3]
does this, and it is quite visually appealing.

- Melanie

[1] https://www.postgresql.org/docs/devel/runtime-config-resource.html#GUC-SHARED-BUFFERS
[2] https://docs.python.org/3/reference/datamodel.html#the-standard-type-hierarchy
[3] https://devblogs.microsoft.com/cppblog/accelerating-compute-intensive-workloads-with-intel-avx-512/#test-system-configuration