Re: A possible docutils' issue with certain IETF mailarchive URIs ?

--===============8758263157280526946==
Content-Type: multipart/alternative; boundary="0000000000000dd858063a7f0b13"

--0000000000000dd858063a7f0b13
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

Hello Guenter,

Am Mo., 21. Juli 2025 um 19:49 Uhr schrieb Guenter Milde via Docutils-users
<[email protected]>:

> ...
> 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?
> =3D=3D=3D=3D
>
> 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.=
=C2=B9
>
> * 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
> =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
>
> 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

--0000000000000dd858063a7f0b13
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr">Hello Guenter,</div><br><div class=3D"gma=
il_quote gmail_quote_container"><div dir=3D"ltr" class=3D"gmail_attr">Am Mo=
., 21. Juli 2025 um 19:49=C2=A0Uhr schrieb Guenter Milde via Docutils-users=
 &lt;<a href=3D"mailto:[email protected]">docutils-users=
@lists.sourceforge.net</a>&gt;:<br></div><blockquote class=3D"gmail_quote" =
style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);pa=
dding-left:1ex">...<br>
On 2025-06-30, Viktor Ransmayr wrote:<br>...<br>
&gt;=C2=A0 =C2=A0test-IETF-URI-issue.rst:18: (ERROR/3) Unknown target name:=
 &quot;k4-l4mk7qa&quot;.<br>
<br>
&gt; For me it is not clear, if the second mailarchive URI really does &#39=
;violate&#39;<br>
&gt; the reStructuredText Markup Specification - or - if it is a &#39;docut=
ils&#39;<br>
&gt; issue.<br>
<br>
The parsing result conforms with the reStructuredText specification<br>
<a href=3D"https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.ht=
ml" rel=3D"noreferrer" target=3D"_blank">https://docutils.sourceforge.io/do=
cs/ref/rst/restructuredtext.html</a>.<br><br>
Why?<br>
=3D=3D=3D=3D<br>
<br>
Let us simplify the example to the two paragraphs::<br>
<br>
=C2=A0 works: <a href=3D"https://example.org/msg/TljW9V_sIzQJ1PpO4axkKmiWCZ=
I/" rel=3D"noreferrer" target=3D"_blank">https://example.org/msg/TljW9V_sIz=
QJ1PpO4axkKmiWCZI/</a><br>
<br>
=C2=A0 fails: <a href=3D"https://example.org/msg/k4-L4mK7Qa_-F3svmF6uFKKPZ6=
I/" rel=3D"noreferrer" target=3D"_blank">https://example.org/msg/k4-L4mK7Qa=
_-F3svmF6uFKKPZ6I/</a><br>
<br>
Each paragraph is parsed for *inline markup*.=C2=A0 According to the<br>
`recognition order`_ standalone hyperlinks are last to be recognised.<br>
I.e., before looking for an URI, the paragraph is checked for emphasis,<br>
literals, ..., hyperlink references, and interpreted text.<br>
<br>
The second URI contains inline markup consistent with the<br>
`hyperlink reference`_ &quot;k4-l4mk7qa&quot;.<br>
<br>
Unfortunately, the `inline markup recognition rules`_ are rather complex.=
=C2=B9<br>
<br>
* A hyperlink reference has no start-string and the end-string &quot;_&quot=
;.<br>
<br>
* end-strings must end the text block or be followed by whitespace or<br>
=C2=A0 punctuation (ASCII characters - : / &#39; &quot; &lt; ( [ { or simil=
ar non-ASCII<br>
=C2=A0 characters).<br>...<br><br>Workarounds<br>
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D<br>
<br>
escape_ the underscore:<br>
=C2=A0 <a href=3D"https://example.org/msg/k4-L4mK7Qa%5C_-F3svmF6uFKKPZ6I/" =
rel=3D"noreferrer" target=3D"_blank">https://example.org/msg/k4-L4mK7Qa\_-F=
3svmF6uFKKPZ6I/</a><br>
<br>
Mark up as hyperlink reference with `embedded URI`_::<br>
<br>
=C2=A0 `&lt;<a href=3D"https://example.org/msg/k4-L4mK7Qa_-F3svmF6uFKKPZ6I/=
" rel=3D"noreferrer" target=3D"_blank">https://example.org/msg/k4-L4mK7Qa_-=
F3svmF6uFKKPZ6I/</a>&gt;`__<br>
<br>
Wrapping in angle brackets helps for standalone hyperlinks with trailing<br=
>
punctuation like &lt;<a href=3D"https://example.org/msg" rel=3D"noreferrer"=
 target=3D"_blank">https://example.org/msg</a>.&gt; but does not help with<=
br>
underscores.<br>...</blockquote><div><br></div><div>Thanks a lot for your d=
etailled answer &amp; the two workarounds !</div><div><br></div><div>With k=
ind regards,</div><div><br></div><div>Viktor</div><div><br></div></div></di=
v>

--0000000000000dd858063a7f0b13--


--===============8758263157280526946==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline


--===============8758263157280526946==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline