Re: [Docutils-users] A possible docutils' issue with certain IETF mailarchive URIs ?

[Viktor R. <vik...@gm...>]

Hello Guenter,

Am Mo., 21. Juli 2025 um 19:49 Uhr schrieb Guenter Milde via Docutils-users
<doc...@li...>:

> ...
> On 2025-06-30, Viktor Ransmayr wrote:
> ...
> >   test-IETF-URI-issue.rst:18: (ERROR/3) Unknown target name:
> "k4-l4mk7qa".
>
> > For me it is not clear, if the second mailarchive URI really does
> 'violate'
> > the reStructuredText Markup Specification - or - if it is a 'docutils'
> > issue.
>
> The parsing result conforms with the reStructuredText specification
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html.
>
> Why?
> ====
>
> Let us simplify the example to the two paragraphs::
>
>   works: https://example.org/msg/TljW9V_sIzQJ1PpO4axkKmiWCZI/
>
>   fails: https://example.org/msg/k4-L4mK7Qa_-F3svmF6uFKKPZ6I/
>
> Each paragraph is parsed for *inline markup*.  According to the
> `recognition order`_ standalone hyperlinks are last to be recognised.
> I.e., before looking for an URI, the paragraph is checked for emphasis,
> literals, ..., hyperlink references, and interpreted text.
>
> The second URI contains inline markup consistent with the
> `hyperlink reference`_ "k4-l4mk7qa".
>
> Unfortunately, the `inline markup recognition rules`_ are rather complex.¹
>
> * A hyperlink reference has no start-string and the end-string "_".
>
> * end-strings must end the text block or be followed by whitespace or
>   punctuation (ASCII characters - : / ' " < ( [ { or similar non-ASCII
>   characters).
> ...
>
> Workarounds
> ===========
>
> escape_ the underscore:
>   https://example.org/msg/k4-L4mK7Qa\_-F3svmF6uFKKPZ6I/
>
> Mark up as hyperlink reference with `embedded URI`_::
>
>   `<https://example.org/msg/k4-L4mK7Qa_-F3svmF6uFKKPZ6I/>`__
>
> Wrapping in angle brackets helps for standalone hyperlinks with trailing
> punctuation like <https://example.org/msg.> but does not help with
> underscores.
> ...


Thanks a lot for your detailled answer & the two workarounds !

With kind regards,

Viktor