[Docutils-develop] [ docutils-Feature Requests-3444138 ] Allows easy referencing of section titles

[SourceForge.net <no...@so...>]

Feature Requests item #3444138, was opened at 2011-11-28 06:44
Message generated for change (Comment added) made by goodger
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=422033&aid=3444138&group_id=38414

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: Yuri D'Elia (wavexx)
Assigned to: Nobody/Anonymous (nobody)
Summary: Allows easy referencing of section titles

Initial Comment:
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).

----------------------------------------------------------------------

>Comment By: David Goodger (goodger)
Date: 2011-11-28 06:58

Message:
+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.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=422033&aid=3444138&group_id=38414