docutils-develop

[Docutils-develop] [docutils:bugs] #446 Links with bracket references cause unexpected "Hyperlink target is not referenced" error

[Jesse B. <jes...@us...>]

---

** [bugs:#446] Links with bracket references cause unexpected "Hyperlink target is not referenced" error**

**Status:** open
**Created:** Thu Apr 21, 2022 07:13 PM UTC by Jesse Brennan
**Last Updated:** Thu Apr 21, 2022 07:13 PM UTC
**Owner:** nobody


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.


---

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.

[Docutils-develop] [docutils:bugs] #446 Links with bracket references cause unexpected "Hyperlink target is not referenced" error

[Adam T. <aa-...@us...>]

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:
```restructuredtext
`a link <different name_>`_

reference to `a link`_

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

Alternatively, you could use an anonymous reference:
```restructuredtext
`a link <different name_>`__

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

Perhaps we could improve the error message?

A


---

** [bugs:#446] Links with bracket references cause unexpected "Hyperlink target is not referenced" error**

**Status:** open
**Created:** Thu Apr 21, 2022 07:13 PM UTC by Jesse Brennan
**Last Updated:** Thu Apr 21, 2022 07:13 PM UTC
**Owner:** nobody


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.


---

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.

[Docutils-develop] [docutils:bugs] #446 Links with bracket references cause unexpected "Hyperlink target is not referenced" error

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

- **status**: open --> closed-invalid
- **Comment**:

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.



---

** [bugs:#446] Links with bracket references cause unexpected "Hyperlink target is not referenced" error**

**Status:** closed-invalid
**Created:** Thu Apr 21, 2022 07:13 PM UTC by Jesse Brennan
**Last Updated:** Fri Apr 29, 2022 03:17 AM UTC
**Owner:** nobody


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.


---

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.

[Docutils-develop] [docutils:bugs] #446 Links with bracket references cause unexpected "Hyperlink target is not referenced" error

[Jesse B. <jes...@us...>]

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.


---

** [bugs:#446] Links with bracket references cause unexpected "Hyperlink target is not referenced" error**

**Status:** closed-invalid
**Created:** Thu Apr 21, 2022 07:13 PM UTC by Jesse Brennan
**Last Updated:** Fri Apr 29, 2022 02:43 PM UTC
**Owner:** nobody


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.


---

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.

Re: [Docutils-develop] [docutils:bugs] #446 Links with bracket references cause unexpected "Hyperlink target is not referenced" error

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

On 2022-04-29, Jesse Brennan via Docutils-develop wrote:

> 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.

A "normal" link is not a target but a link with embedded target sets up
both, a target element (identifier) and a reference to it.

The syntax

  `link name <file:target.txt>`_

is just a shorthand for ::

  `link name`_
  
  .. _link name: file:target.txt
  
This is explained in the reStructuredText specification but I assume it
feels "natural" only in hindsight.

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

Another option would be to increase the report level.

Günter