Misleading documentation on rST hyperlink syntax.

[gmilde]

Describe the bug

The reStructuredText Primer (doc/usage/restructuredtext/basics.rst) starts the section on External links with

Use ```Link text <https://domain.invalid/>`_`` for inline web links. 

which is, according to the reStructuredText Markup Specification the syntax for a "named hyperlink reference with embedded URI", the most complex and most misunderstood link syntax variant.

Users thus primed will be surprised when a subsequent "inline link" with the same link text results in a WARNING Duplicate explicit target name: "link text" because the syntax is equivalent to the link–target pair ("reference link")

Use ```Link text`_`` for hyperlinks. Add a target block::

    .. _link text: https://domain.invalid/

at a suitable place.

and generates two Doctree elements:

<reference name="Link text" refuri="https://domain.invalid/">Link text</reference>
<target ids="link-text" names="link\ text" refuri="https://domain.invalid/"></target>

The rST analogon to Markup "inline links" is an "anonymous hyperlink reference with embedded URI/alias" which uses a double trailing underline.

There is actually no good reason to use a named link with embedded href
(with single trailing underline):

• If the established reference name is used at several places, a separate named target adds clarity.

• One-off use cases are better served with the anonymous variant (with double trailing underline) or an "normal" anonymous reference – target pair.

Suggestion:

• Start the "primer" documentation section with "reference links". In rST, they are easier than "inline links".
• For "inline links", write

  Use ```Link text <https://domain.invalid/>`__`` for inline web links 
  (**mind the double underline at the end**, for details see the `rST specification`__).
  
  __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases`__
  

How to Reproduce

index.rst:

The references `link text <https://domain.invalid/>`_
and `link text <https://example.com/>`_ generate a warning.

Environment Information

The bug is in the current online documentation
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#external-links

[gmilde]

See #13576 (comment) for an example of the confusion when the "rST primer" is used as primary information on reStructuredText.

[jfbu]

If I am allowed to make a half-serious pedagogical suggestion to improve this reST Primer in our Docs: same as literals need two back ticks not one, hyperlinks are better done with two underscores not one... (I would hesitate saying "inline" hyperlink, because I have no clear idea what "inline" is supposed to be mean here, as if there was a "display block" type of hyperlink? mind that most Sphinx users exclusively belong to HTML rendering world and vocabulary).

[jfbu]

I definitely belong to the category of the surprised users...

[timhoffm]

I have also been bitten by this before. I think "inline" is a misnomer here and the intention was to denote hyperlinks with embedded URIs. I've opened a PR to improve the docs.

[gmilde]

I have also been bitten by this before. I think "inline" is a misnomer here and the intention was to denote hyperlinks with embedded URIs.

It is a "commonmarkism". See inline links in the CommonMark spec.