Re: [Docutils-users] reST->HTML: internal anchors: problem casting section names to IDs

[Guenter M. <mi...@us...>]

On 2016-03-31, Tom Roche wrote:

> summary
>=======

> Small reST document (linked and attached) has sections with unique
> names. When I use docutils/restview to convert it to HTML, all but one
> section id is created by (speaking `sed`ishly) `s/ /-/g`. However *one*
> section id is "hashed" (i.e., created like a backref), which breaks an
> explicit internal anchor. Why not create all section IDs in the same
> way?

...

> The problem can be illustrated by comparing the section IDs generated
> for the section names={long-term bodywear, short-term bodywear} and the
> success of hand-coded links and generated/TOC links to those sections
> in the text.

> 1. reST section name='short-term bodywear' generates HTML=

>> <div class="section" id="short-term-bodywear">
>> <h2><a class="toc-backref" href="#id8">short-term bodywear</a></h2>

>    Note the form of the div attribute='id': it is the section name with
>    all spaces replaced by dashes, aka 's/ /-/g'. This is as I expect
>    (therefore good :-)

...

> 2. reST section name='long-term bodywear' generates HTML=

>> <div class="section" id="id1">
>> <h2><a class="toc-backref" href="#id10">long-term bodywear</a></h2>

>   Note the form of the div attribute='id', which is NOT as I expect.

> 2.1. This unexpected behavior breaks my hand-coded internal reference
> to section name='long-term bodywear'

>> .. |long-term bodywear| replace:: *long-term bodywear*
>> .. _long-term bodywear: #long-term-bodywear

>> *see also* |long-term bodywear|_

>     which generates (correctly) the following HTML:

>> <p><em>see also</em> <a class="reference external"
>> href="#long-term-bodywear"><em>long-term bodywear</em></a></p>

Here is the problem: you define an external target with the URL
"#long-term-bodywear" (which happens to point to the same document)
therefore also: "reference-external".

Moreover, you define this external link *before* the equally named section.
Now, when Docutils reaches the section header, the name is already "used up"
and the standard fallback naming (via id-number) kicks in.

> 2.2. However the generated TOC link to that section works by
> reproducing the unexpected behavior:

>> <li><a class="reference internal" href="#id1" id="id10">long-term bodywear</a></li>

Yes, as is common for name duplication.


> solution/questions
> ------------------

> ISTM docutils should _always_

> 1. for unique section names: generate `div id`s by `s/ /-/g`
> 2. for duplicate section names (and all backrefs): generate `div id`s
>    by serial numbering, i.e. appending a serial number to string='id'

> So my first question is, am I missing something? Is there a reason to
> *not* behave thusly? 

The point is, this could only be done for "link names", a common namespace
for section names and other targets.


The following works here as expected::

  
  .. howto style a link (e.g., make it italic): see http://docutils.sourcefor
  .. |long-term bodywear| replace:: *long-term bodywear*
  .. |short-term bodywear| replace:: *short-term bodywear*
  
  
  short-term bodywear
  -------------------
  
  *see also* |long-term bodywear|_
  
  long-term bodywear
  ------------------
  
  *see also* |short-term bodywear|_



Günter