#446 Links with bracket references cause unexpected "Hyperlink target is not referenced" error

[Jesse Brennan]

I'm getting a surprising error when running reporting on a minimal RST file.

Here's the minimal.rst:

`a link <different name_>`_

.. _different name: https//www.example.com

Now if I run

rst2html.py minimal.rst --report=1 --traceback > /dev/null
minimal.rst:3: (INFO/1) Hyperlink target "a link" is not referenced.

you see the error I get. As far as I know, this is perfectly valid RST, so I'm wondering if this error message is a bug.

For more context, I encountered this error originally on a different project: https://github.com/myint/rstcheck/issues/77 which makes use of docutils.

[Adam Turner]

It is technically correct output, although I agree surprising.

There are two targets in this document, different name and a link.

different name is referenced by the alias reference syntax in line 1, but a link is never referenced.

The following document generates no errors:

`a link <different name_>`_

reference to `a link`_

.. _different name: https://www.example.com

Alternatively, you could use an anonymous reference:

`a link <different name_>`__

.. _different name: https://www.example.com

Perhaps we could improve the error message?

A

[Günter Milde]

While an error message for valid input would be a bug, this is no error message:

--report=1 requests to print all kind of information, not only errors.

INFO/1 level issues are informational -- caused by valid input, they may indicate a potential to streamline your document or make it more robust.

The embedded alias in a named hyperlink creates a new target, that is not referenced elsewhere:

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.
-- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases

Adding a second underscore should silence the info, whether it is an improvement to your document depends on the context.

Thank you for reporting.

[Jesse Brennan]

Thank you both, that makes a lot of sense. I guess I was confused because I was thinking of "a link" as a reference, not a target. But if I understand now correctly, unless the link is anonymous, then "a link" is both a reference and a target.

It sounds like the solution I'm looking for here is just making the link anonymous. Thanks you!

Perhaps we could improve the error message?

If the error message suggested using an anonymous link, that would have lead me down the right path, but I understand if that's not a desirable change.