Change "Permalink to this headline" to use "heading" instead

[pradyunsg]

Describe the bug

Sphinx-generated tooltips for headings use "Headline" instead of "Heading".

Picking out of https://ell.stackexchange.com/questions/196585/headline-vs-heading-vs-header:

"Headline" is normally used when an article appears as one of a collection of articles, such as a newspaper. If the article is reprinted separately, the headline becomes the "title". While a headline can also be called a heading, the term "heading" is more often used for what goes at the top of a section or sub-section of an article. [snip]

In fact, I would avoid the word "headline" except in reference to a newspaper or some publication/text organized in a way very similar to a newspaper.

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 "Headline" instead of "Heading".

Expected behavior

Instead of:

• Permalink to this headline

The tooltip should be:

• Permalink 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

The relevant chunk of code:

sphinx/sphinx/writers/html5.py

Lines 386 to 398 in f38bd8e

	def depart_title(self, node: Element) -> None:
	close_tag = self.context[-1]
	if (self.config.html_permalinks and self.builder.add_permalinks and
	node.parent.hasattr('ids') and node.parent['ids']):
	# add permalink anchor
	if close_tag.startswith('</h'):
	self.add_permalink_ref(node.parent, _('Permalink to this headline'))
	elif close_tag.startswith('</a></h'):
	self.body.append('</a><a class="headerlink" href="#%s" ' %
	node.parent['ids'][0] +
	'title="%s">%s' % (
	_('Permalink to this headline'),
	self.config.html_permalinks_icon))

This will also need some update to the translated strings, which means that this will likely need to be a Sphinx 5.0+ change?

[pradyunsg]

FWIW, "Link to this heading" would be a better name IMO -- even though it's a more "drastic" rephrasing. :)

[tk0miya]

+1; Reasonable. Could you make a PR, please? Then I'll merge this into the master branch.

Note: To keep the message translated, it would be better to change it in the major release.

[mgeier]

FWIW, "Link to this heading" would be a better name IMO

I agree.

"permalink" has a quite specific meaning which I think cannot be guaranteed by Sphinx. In fact, in many cases (probably the majority of sites out there), the generated link will contain something like latest, which is definitely not a permalink!

[pradyunsg]

+1; Reasonable. Could you make a PR, please? Then I'll merge this into the master branch.

Happy to! Is there any specific thing that I'd need to do other than modifying the two spots in the codebase that use this string (via _("Permalink to this headline"))? Specifically, do the translation files need updating? If so, how should I do that?

[tk0miya]

It's okay to change the strings only. All translations are managed at transifex.com. And strings on our codebase will be synchronized to transifex.com automatically by weekly batch (see https://github.com/sphinx-doc/sphinx/actions/workflows/transifex.yml)

[pradyunsg]

It ended up being more than two spots, but, hey, this PR has been filed! :)

[pradyunsg]

"permalink" has a quite specific meaning which I think cannot be guaranteed by Sphinx. In fact, in many cases (probably the majority of sites out there), the generated link will contain something like latest, which is definitely not a permalink!

This is a good point and I agree that this is not-great!

It is, however, a separate and broader concern compared to this issue (intentionally restricted to just "headline") -- so... I've filed #10049, which is where we can discuss replacing the "Permalink" word. :)

[pradyunsg]

Thanks @tk0miya for the quick response, review and merge! ^.^