Change "Permalink to this {thing}" in tooltips, to "Link to this {thing}"

[pradyunsg]

Describe the bug

According to Wikipedia:

A permalink or permanent link is a URL that is intended to remain unchanged for many years into the future, yielding a hyperlink that is less susceptible to link rot.

Sphinx uses the word "Permalink" in the tooltips for various things, such as headings/definitions/images/code etc. This is not configurable by the user and is not ideal; since not all of the documentation sites have similar policies on how link rot/renaming etc would be handled. This is especially problematic since a lot of Sphinx-based documentation is on ReadTheDocs, which by default has pages like pip.readthedocs.io/en/latest/ which are decidedly not going to present permalinks (unless the documentation author is really careful; which... yea, not guarenteed).

It would be better to change "Permalink" to "Link", avoiding the concern of whether a link is going to be long-lived or not entirely. Plus, it's more "generally correct" -- a permalink is still a link. :)

How to Reproduce

Build any Sphinx documentation, containing one or more headings (eg: https://pradyunsg.me/furo/kitchen-sink/demo/). When hovering over the Sphinx-injected "headerlink", notice that it says "Permalink to this heading".

Expected behavior

Change to "Link to this heading".

Your project

https://github.com/pradyunsg/furo

Screenshots

OS

N/A

Python version

N/A

Sphinx version

4.x

Sphinx extensions

No response

Extra tools

No response

Additional context

Excluding the locale files, there's quite a few instances that would need updating:

./tests/test_directive_code.py:               'title="Permalink to this code">\xb6</a></div>')
./tests/test_directive_code.py:               'title="Permalink to this code">\xb6</a></div>')
./tests/test_ext_inheritance_diagram.py:                   'title="Permalink to this image">\xb6</a></p>\n</div>\n')
./tests/test_ext_inheritance_diagram.py:                   'title="Permalink to this image">\xb6</a></p>\n</figcaption>\n</figure>\n')
./tests/test_ext_inheritance_diagram.py:                   'title="Permalink to this image">\xb6</a></p>\n</div>\n')
./tests/test_ext_inheritance_diagram.py:                   'title="Permalink to this image">\xb6</a></p>\n</figcaption>\n</figure>\n')
./tests/test_ext_inheritance_diagram.py:                   'title="Permalink to this image">\xb6</a></p>\n</div>\n')
./tests/test_ext_inheritance_diagram.py:                   'title="Permalink to this image">\xb6</a></p>\n</figcaption>\n</figure>\n')
./tests/test_build_html.py:                '<a class="headerlink" href="#id1" title="Permalink to this image">¶</a></p>'
./tests/test_build_html.py:                '<a class="headerlink" href="#id1" title="Permalink to this image">¶</a></p>\n</figcaption>'
./tests/test_build_html.py:            'title="Permalink to this heading"><span>[PERMALINK]</span></a></h1>' in content)
./tests/test_markup.py:         ' title="Permalink to this term">¶</a></dt>'
./tests/test_markup.py:         ' title="Permalink to this term">¶</a></dt>'
./sphinx/writers/html5.py:            self.add_permalink_ref(node, _('Permalink to this definition'))
./sphinx/writers/html5.py:            self.add_permalink_ref(node.parent, _('Permalink to this definition'))
./sphinx/writers/html5.py:                self.add_permalink_ref(node, _('Permalink to this term'))
./sphinx/writers/html5.py:                self.add_permalink_ref(node.parent, _('Permalink to this heading'))
./sphinx/writers/html5.py:                                     _('Permalink to this heading'),
./sphinx/writers/html5.py:                self.add_permalink_ref(node.parent, _('Permalink to this table'))
./sphinx/writers/html5.py:            self.add_permalink_ref(node.parent, _('Permalink to this code'))
./sphinx/writers/html5.py:            self.add_permalink_ref(node.parent, _('Permalink to this image'))
./sphinx/writers/html5.py:            self.add_permalink_ref(node.parent.parent, _('Permalink to this toctree'))
./sphinx/writers/html.py:            self.add_permalink_ref(node, _('Permalink to this definition'))
./sphinx/writers/html.py:            self.add_permalink_ref(node.parent, _('Permalink to this definition'))
./sphinx/writers/html.py:                self.add_permalink_ref(node, _('Permalink to this term'))
./sphinx/writers/html.py:                self.add_permalink_ref(node.parent, _('Permalink to this heading'))
./sphinx/writers/html.py:                                     _('Permalink to this heading'),
./sphinx/writers/html.py:                self.add_permalink_ref(node.parent, _('Permalink to this table'))
./sphinx/writers/html.py:            self.add_permalink_ref(node.parent, _('Permalink to this code'))
./sphinx/writers/html.py:            self.add_permalink_ref(node.parent, _('Permalink to this image'))
./sphinx/writers/html.py:            self.add_permalink_ref(node.parent.parent, _('Permalink to this toctree'))
./sphinx/ext/mathjax.py:        self.add_permalink_ref(node, _('Permalink to this equation'))
./sphinx/ext/imgmath.py:        self.add_permalink_ref(node, _('Permalink to this equation'))
./sphinx/themes/basic/static/doctools.js:      attr('title', _('Permalink to this heading')).
./sphinx/themes/basic/static/doctools.js:      attr('title', _('Permalink to this definition')).

If this ends up being OK to do, we should change this no sooner than Sphinx 5.0 (similar to #10041).

[pradyunsg]

If the maintainers are on board for this, I'm happy to file a PR for this! I lean toward not changing the method name add_permalink_ref -- leaving that as a follow up for others.

[kapooramit]

Related to this - can we not add the link icon in the HTML but in the CSS instead? Because of this, an issue that arises is when I used say tocbot to create page's toc that sticks, it shows  at the end of every title....
I think it is coming from the link icon only as I could diagnose...

[pradyunsg]

That is a separate concern. Please file a separate issue for it, since that is separate from (and independent of) changing the tooltips, which is what this issue is for.

Also, Sphinx has .. contents:: which might be what you're looking for.

[john-hen]

I agree with this proposal: the current wording may indeed lead to false expectations and eventual disappointment.

I would however note that there's also the config option html_permalinks to consider. As opposed to the method name, this is not an internal implementation detail. It is exposed to the user and therefore should be changed along with the tool-tips for the sake of consistency.

The question then is what to call this thing? An option named simply html_links would not be very clear. I would suggest to speak of "section links", so html_section_links. That's not entirely accurate, as it also affects links to page elements other than section headings. But it describes the common use case. Users are most likely to notice this feature next to a section heading and then might search the documentation with that term in mind. I think.

If not that, then maybe "item links" would be more comprehensive. But it also quite generic and as such fairly difficult to guess.

Or something else entirely. But the config option should not be forgotten. Unfortunately, it was renamed not that long ago, known as html_add_permalinks until Sphinx 3.5. So then there would be a second deprecated alias.

[AA-Turner]

Fixed in 7e9a206

A