Thread: A minor bug in doc. Hovering over heading shows # besides it.

Hi,

On page 

https://www.postgresql.org/docs/devel/ddl-basics.html

5.1. Table Basics #

when we hover over Table Basics, it shows # sign postfixed. I think it needs to be removed

I have checked other pages too and the issue is only with this page.

On Thu, 18 Jul 2024 at 16:55, Muhammad Ikram <mmikram@gmail.com> wrote:
> 5.1. Table Basics #
>
> when we hover over Table Basics, it shows # sign postfixed. I think it needs to be removed

Those are meant to be there. They allow you to copy a URL directly to
that doc section.

In [1], there was some talk about using another more suitable
character. If the purpose of the '#' isn't obvious, then maybe we
should use something else.

David

https://www.postgresql.org/message-id/CAAKRu_Z1Xsjmv3b-JaGg2e1JLE2GCZe3+zX7C7WGbraJBfvvzg@mail.gmail.com

David Rowley <dgrowleyml@gmail.com> writes:
> On Thu, 18 Jul 2024 at 16:55, Muhammad Ikram <mmikram@gmail.com> wrote:
>> when we hover over Table Basics, it shows # sign postfixed. I think it needs to be removed

> In [1], there was some talk about using another more suitable
> character. If the purpose of the '#' isn't obvious, then maybe we
> should use something else.

Yeah.  I've found this new feature useful multiple times already,
but the '#' icon is as non-mnemonic and unobvious as could possibly
be.  OTOH, I don't know of a standard icon for this feature.

I wonder if we could make a tooltip worded like "link to this header"
pop up when you hover over the '#'?  That'd improve things a lot
even if we had a better icon.

A different idea is to dispense with the icon and make the section
title itself be a link to itself.

            regards, tom lane

David Rowley <dgrowleyml@gmail.com> writes:
> On Thu, 18 Jul 2024 at 16:55, Muhammad Ikram <mmikram@gmail.com> wrote:
>> when we hover over Table Basics, it shows # sign postfixed. I think it needs to be removed

> In [1], there was some talk about using another more suitable
> character. If the purpose of the '#' isn't obvious, then maybe we
> should use something else.

Yeah.  I've found this new feature useful multiple times already,
but the '#' icon is as non-mnemonic and unobvious as could possibly
be.  OTOH, I don't know of a standard icon for this feature.

A different idea is to dispense with the icon and make the section
title itself be a link to itself.

On Thu, 18 Jul 2024 at 17:18, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> Yeah.  I've found this new feature useful multiple times already,
> but the '#' icon is as non-mnemonic and unobvious as could possibly
> be.  OTOH, I don't know of a standard icon for this feature.

I also find it useful and certainly don't want it to disappear.

There's a unicode character for it.
https://www.unicodepedia.com/unicode/miscellaneous-symbols-and-pictographs/1f517/link-symbol/

David

On Thu, 18 Jul 2024 at 07:40, David Rowley <dgrowleyml@gmail.com> wrote:
>
> On Thu, 18 Jul 2024 at 17:18, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> > Yeah.  I've found this new feature useful multiple times already,
> > but the '#' icon is as non-mnemonic and unobvious as could possibly
> > be.  OTOH, I don't know of a standard icon for this feature.
>
> I also find it useful and certainly don't want it to disappear.
>

+1. I have also already found it useful.

> There's a unicode character for it.
> https://www.unicodepedia.com/unicode/miscellaneous-symbols-and-pictographs/1f517/link-symbol/
>

+1 for that and a "Link to this heading" tooltip.

Regards,
Dean

> On 18 Jul 2024, at 07:18, Tom Lane <tgl@sss.pgh.pa.us> wrote:

> Yeah.  I've found this new feature useful multiple times already,
> but the '#' icon is as non-mnemonic and unobvious as could possibly
> be.  OTOH, I don't know of a standard icon for this feature.

While not a standard the pilcrow [0] is, AFAICT from a bit of looking at other
docs, commonly used for this.  There is a lot of variability though so
whichever we choose it will be wrong one for someone.

--
Daniel Gustafsson

[0] https://en.wikipedia.org/wiki/Pilcrow

On Thu, 18 Jul 2024 at 19:46, Daniel Gustafsson <daniel@yesql.se> wrote:
> There is a lot of variability though so
> whichever we choose it will be wrong one for someone.

I think the tooltip would help reduce the chances of someone being
confused.  For an example, see [1].

David

[1]
https://devblogs.microsoft.com/cppblog/accelerating-compute-intensive-workloads-with-intel-avx-512/#test-system-configuration

Daniel Gustafsson <daniel@yesql.se> writes:
> While not a standard the pilcrow [0] is, AFAICT from a bit of looking at other
> docs, commonly used for this.  There is a lot of variability though so
> whichever we choose it will be wrong one for someone.

I like this suggestion better because that's U+00B6, ie part of
LATIN-1, so it's *far* more likely to render correctly everywhere
than U+01F517 is.  We could also consider the section sign §
(U+00A7).

In any case, a tooltip would help reduce confusion.

            regards, tom lane

> On 18 Jul 2024, at 15:49, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Daniel Gustafsson <daniel@yesql.se> writes:
>> While not a standard the pilcrow [0] is, AFAICT from a bit of looking at other
>> docs, commonly used for this.  There is a lot of variability though so
>> whichever we choose it will be wrong one for someone.
>
> I like this suggestion better because that's U+00B6, ie part of
> LATIN-1, so it's *far* more likely to render correctly everywhere
> than U+01F517 is.  We could also consider the section sign §
> (U+00A7).
>
> In any case, a tooltip would help reduce confusion.

Looking a bit closer, the Python documentation does just this, a pilcrow with a
tool-tip ("Link to this heading") when hovering over it

--
Daniel Gustafsson

Daniel Gustafsson <daniel@yesql.se> writes:
> Looking a bit closer, the Python documentation does just this, a pilcrow with a
> tool-tip ("Link to this heading") when hovering over it

Oh nice --- a precedent!  And one that a fair number of people
will have seen before.  +1 for copying Python.

            regards, tom lane

On 7/18/24 1:59 PM, Daniel Gustafsson wrote:
>> On 18 Jul 2024, at 15:49, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>>
>> Daniel Gustafsson <daniel@yesql.se> writes:
>>> While not a standard the pilcrow [0] is, AFAICT from a bit of looking at other
>>> docs, commonly used for this.  There is a lot of variability though so
>>> whichever we choose it will be wrong one for someone.
>>
>> I like this suggestion better because that's U+00B6, ie part of
>> LATIN-1, so it's *far* more likely to render correctly everywhere
>> than U+01F517 is.  We could also consider the section sign §
>> (U+00A7).
>>
>> In any case, a tooltip would help reduce confusion.
> 
> Looking a bit closer, the Python documentation does just this, a pilcrow with a
> tool-tip ("Link to this heading") when hovering over it

I forgot why we went with the "#" and not the (TIL the name) pilcrow 
symbol, but I'm generally used to seeing the pilcrow when I browse docs 
and may have voiced that at the time (though the record may show 
otherwise). So +1 to that.

Thanks,

Jonathan

On Fri, 19 Jul 2024 at 06:03, Jonathan S. Katz <jkatz@postgresql.org> wrote:
>
> On 7/18/24 1:59 PM, Daniel Gustafsson wrote:
> > Looking a bit closer, the Python documentation does just this, a pilcrow with a
> > tool-tip ("Link to this heading") when hovering over it
>
> I forgot why we went with the "#" and not the (TIL the name) pilcrow
> symbol, but I'm generally used to seeing the pilcrow when I browse docs
> and may have voiced that at the time (though the record may show
> otherwise). So +1 to that.

I'm not really a web developer, but I did have a go at adjusting the
.css file so we show some relevant tooltip text. I was reminded about
this when looking at [1] this morning. That page is using '#' but the
purpose of it seems quite obvious when combined with the tooltip.

I've attached a small patch to adjust the CSS with hopes that it might
inspire someone who actually knows what they're doing with CSS to make
it better.

David

[1]
https://stackoverflow.blog/2024/07/24/developers-want-more-more-more-the-2024-results-from-stack-overflow-s-annual-developer-survey/