Обсуждение: [PATCH] Add CSS to support discoverable ids in the public documentation website

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.

Regards,
Brar

[1]
https://www.postgresql.org/message-id/20230323093555.3icw7zetwtmtrrzu@alvherre.pgsql
[2]
https://www.postgresql.org/message-id/91edf03b-7b63-67b6-7f44-bfeb48e97056@gmx.de

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

On Wed, Apr 19, 2023 at 4:08 PM Jonathan S. Katz <jkatz@postgresql.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

On 19.04.2023 at 22:21, Melanie Plageman wrote:
> On Wed, Apr 19, 2023 at 4:08 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:
>> On 4/13/23 9:41 AM, Brar Piening wrote:
>>> 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.
>> 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?
> 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.


I have no qualifications or whatsoever to comment on the visual design,
so I will not be involved in any bike shedding but please note that the
patch here does not and cannot chose the symbol we are displaying. Being
pure CSS it only changes the default color and visibility of the symbol.
The symbol was part of the xslt modifications in the patch that I sent
to hackers and was commited in commit e2922702a3. If you really think
that changing the symbol is important or useful, you'll probably have to
carry the discussion back to hackers (maybe to the original thread).

Regards,
Brar

On 4/19/23 5:08 PM, Brar Piening wrote:
> On 19.04.2023 at 22:21, Melanie Plageman wrote:
>> On Wed, Apr 19, 2023 at 4:08 PM Jonathan S. Katz 
>> <jkatz@postgresql.org> wrote:
>>> On 4/13/23 9:41 AM, Brar Piening wrote:
>>>> 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.
>>> 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?
>> 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.

I think to do the link icon successfully, we should also attempt to 
automatically copy the text to the clipboard as well. We already have a 
basis for this thanks to some of the work we did on the downloads page, 
so adapting it for this purpose would be fairly trivial.

> I have no qualifications or whatsoever to comment on the visual design,
> so I will not be involved in any bike shedding but please note that the
> patch here does not and cannot chose the symbol we are displaying. Being
> pure CSS it only changes the default color and visibility of the symbol.
> The symbol was part of the xslt modifications in the patch that I sent
> to hackers and was commited in commit e2922702a3. If you really think
> that changing the symbol is important or useful, you'll probably have to
> carry the discussion back to hackers (maybe to the original thread).

Yeah, I noticed that while testing the patch further and looking at the 
current display in the devel docs.

For now, I committed Brar's patch as is, with an updated comment[1]. I 
think there is more to be done here on usability, but, at least for Beta 
1, we should be hiding the anchors by default.

Jonathan

[1] https://git.postgresql.org/gitweb/?p=pgweb.git;a=commit;h=c7a5951d2

On 22.04.23 20:48, Jonathan S. Katz wrote:
> I think to do the link icon successfully, we should also attempt to 
> automatically copy the text to the clipboard as well. We already have a 
> basis for this thanks to some of the work we did on the downloads page, 
> so adapting it for this purpose would be fairly trivial.

Looking at the existing examples we have considered during the work on 
these patches, I have not seen one that does this.  I don't think I 
would like it.