#28 Allows easy referencing of section titles

In rst2html, you have three choices regarding to generating toc backlinks:

--no-toc-backlinks
--top-toc-backlinks
--toc-entry-backlinks

However I would like each section title to have a link to itself, or at least
some anchor that allows to have the link to the current section, regardless
whether there's a toc in the document or not.

This is very handy when referencing online documents. Sphinx does something similar by using an on-hover pilcrow:

http://docs.python.org/reference/compound_stmts.html#the-for-statement

after each section title, there's pilcrow (on hover) linking to the current
section.

See the discussion at:

http://thread.gmane.org/gmane.text.docutils.user/6517

<<Use case:

I often need a reference to a section in the docs when answering a question
here or at the Sphinx list. Then, usually I open the HTML version of the
doc, check the content and copy the link from there.

a) With a toc and --toc-entry-backlinks (or a small toc and
--top-toc-backlinks), it is straightforward to

* click at the section heading -> brings you to the toc,
* right-click at the toc entry and select "copy link address",
* paste the link in the editor.

Example:
http://docutils.sourceforge.net/docs/dev/todo.html#epub-html-writer

b) Without a toc or with --no-toc-backlinks, this work-flow does not work:

* no "copyable link" in the document without a toc
* "copyable link" in the toc not easy to find when reading the section with
--no-toc-backlinks.

So, while I don't like Sphinx's "pop-up" pilcrows, I see their use in case
b) (and for other referencable objects).

You could file a feature request at the tracker
http://sourceforge.net/tracker/?group_id=38414&atid=422033

Alternatively, we could offer a new option for the `toc_backlinks` setting:

Enable backlinks from section titles to

* table of contents entries ("entry"),
* to the top of the TOC ("top"),
* to themselves ("self"),
* or disable ("none").

together with a --self-backlinks command line option.

Then, with toc_backlinks == "self", right-click on a section title would
allow to copy the sections URL.>>

That's exactly my use case as well: I generate online documents with rst2html all the time, and whenever I need to reference to a document I usually do link to the relevant section.

I was already aware of the "entry" option (to toc, then get the url), but that's rather inconvenient, and as you say it doesn't work whenever the toc is missing.

I'm personally fine with either the Sphinx solution ("on-hover pilcrow", which would be easy enough to customize via css) or via the "self" behavior (which I like much more at the moment. Admittedly I have never used the back-to-toc feature of the section titles, I would instead certainly use the direct link without further fuss).

[David Goodger]

+0 on implementing a self-link feature.

-1 on implementing it via the TOC backlinks feature, which is orthogonal. This has nothing to do with the TOC.

[Günter Milde]

https://sourceforge.net/p/docutils/feature-requests/77/ is a duplicate.

[Günter Milde]

How about something like the attached minimal example?

The content of the self-referencing link is inserted via CSS:

• content can be changed/suppressed via a custom stylesheet,
• no noise in CSS-unaware browsers with broken/missing/deactivated stylesheet.

We could introduce this for the HTML5 writer, eitherunconditionally or with a to-be-found config setting name¹.
¹ Sphinx uses html_permalinks but this is a bit misleading: are they really permanent?

[Erik Martin-Dorel]

Dear Günter Milde, thanks for suggesting this minimal complete example!

Looks very good to me. And I like as well the fact that it smoothly integrates with CSS.

Regarding the possible naming of the corresponding setting, maybe html_headinglinks or html_sectionlinks would be OK? as it is specific to <h1> etc. constructs.
But personally, I'd vote for this feature to be, either unconditionnaly applied, or triggered by an optional setting that is enabled by default.

Cheers,
Erik

[Erik Martin-Dorel]

Dear Günter Milde and David Goodger,

Do you believe you'd have the time to take a look into this feature? it would be a very useful one anyway :)

But in this case, I don't know if you'd have a preference regarding the activation of this feature? I mean, between:

• Applying it unconditionally (adding always self-referencing links to section titles)
• Applying it by default, unless we pass the CLI option --no-html-section-links
• Or something else?

Regarding the possible output, Günter's template "self-link.html" looks very good!
I'd just want to suggest (if you agree) to add text-decoration: none; for a slightly better rendering… For the record, here is the dump of this html template source in which I applied this suggestion:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Test self-referencing links</title>
<style type="text/css">
a.eigenlink {
  text-decoration: none;
}
h2:hover > a.eigenlink::before {
  font-style: normal;
  color: blue;
  font-size: smaller;
  padding-left: 0.2em;
  content: "¶";
}
</style>
</head>
<body class="with-toc">
<section id="test">
<h2>Test<a class="eigenlink" href="#test" title="Link to this heading"></a></h2>
</section>
</body>
</html>

Kind regards,
Erik

[Günter Milde]

Implemented in r8788

[Günter Milde]

Implemented in Docutils 0.18.
Thank you for the suggestion.