Duplicate reference in doctree

[Freek Dijkstra]

Hi,

This might be a docutils question, rather than Sphinx, but perhaps
someone can give me a hint anyway.

Consider the `name <reference_>_` syntax in this example:

>   This should link to `the next section <section-w2zn7enu_>`_.
>
>   .. _section-w2zn7enu:
>
>   Section Title
>   =============
>   Text body.
Gives the following result with `sphinx-build -r xml` (using Sphinx 3.5.1):

>  <document source="test.rst">
>      <paragraph>
>          This should link to <reference name="the next section"
> refid="section-w2zn7enu">the next section</reference>
>          <target names="the\ next\ section"
> refid="section-w2zn7enu"></target>.
>      </paragraph>
>      <target refid="section-w2zn7enu"></target>
>      <section ids="section-title section-w2zn7enu" names="section\
> title section-w2zn7enu">
>          <title>Section Title</title>
>          <paragraph>Text body.</paragraph>
>      </section>
>  </document>
I'm surprised to find two <target> for refid="section-w2zn7enu". I would
have only expected the second one, not the one in the first paragraph.

Why is it there?

My writer outputs both targets, which is wrong. It shouldn't output the
first. I can of course ignore any target witha "names" attribute, but
that feels like a hack to me.

What is the syntactic difference between the two targets?

Regards,
Freek

[Freek Dijkstra]

Thanks for taking the time to read this.

I found the best approach: ignore the <target> nodes, and instead create
a specific pointer for each node that contains >1 ids.

In this case <section ids="section-title section-w2zn7enu" ... > would
create a target.

Regards,
Freek

[Guenter Milde]

Because you requested it:

With a single trailing underscore, the reference is named and the same
target URI may be referred to again. With two trailing underscores, the
reference and target are both anonymous, and the target cannot be
referred to again. These are “one-off” hyperlinks.

-- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases

That means any later use of ::

`the next section`_

will point to section w2zn7enu. If you use an anonymous hyperlink like ::

This should link to `the next section <section-w2zn7enu_>`__.

there would no target element::

<target names="the\ next\ section" refid="section-w2zn7enu"></target>

and you could re-use the name for other anonymous links.

> My writer outputs both targets, which is wrong. It shouldn't output the

> first. I can of course ignore any target with a "names" attribute, but

> that feels like a hack to me.

Actually, most Docutils writers ignore most target nodes.
Instead, dummy targets are created for nodes with more than one ID, if
the output language does not support multiple IDs.
Have a look at the definition of visit_target() in the writer sources.

Günter