[Docutils-develop] [docutils:bugs] #502 Duplicate target not always recognized.

[Günter M. <mi...@us...>]

It seems, that up to now many users did not know that ````link text <target>`_```
creates a <target> with the reference name "link text".

The Sphinx rST primer did start with
~~~rst
Use ```Link text <https://domain.invalid/>`_`` for inline web links. 
~~~
without mentioning that this *named hyperlink reference with embedded URI* also generates a target.

The missing WARNING for *named hyperlink references with embedded alias* did contribute to the confusion. As a result, even the [Docutils Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html) documentation shows warnings after the fix in [r10151].

In order to avoid breaking lots of existing documents,  *named hyperlink references with embedded URI or alias* should not be interpreted as an explicit intention to create a target. 
Rather, like section titles, the  reference name should be treated as [**implicit** hyperlink targets]( https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#implicit-hyperlink-targets).




---

**[bugs:#502] Duplicate target not always recognized.**

**Status:** open-fixed
**Created:** Tue Jun 03, 2025 09:33 AM UTC by Günter Milde
**Last Updated:** Tue Jun 03, 2025 03:33 PM UTC
**Owner:** nobody


Hyperlinks with embedded alias generate both, a `<reference>` and a `<target>`. 
This allows simple references to the target:
~~~
See `here <example.html>`_.

As we have shown here_, ...
~~~
However, it may lead to duplicates:
~~~
_`Here` is an explicit inline target.

See `here <example.html>`_.

As we have shown here_, ...
~~~
The second target gives a WARNING `Duplicate explicit target name: "here".`
Using the reference name results in an ERROR `Duplicate target name, cannot be used as a unique reference: "here".`

However (in versions up to 0.22.rc2), the duplicate target is ignored in case of **embedded internal** targets:
~~~
_`Here` is an explicit inline target.

See `here <elsewhere_>`_.

As we have shown here_, ...

The target is _`elsewhere`.
~~~
There is no WARNING or ERROR and both references link to "elsewhere".

This is fixed in [r10151].


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.