Clarify what the word "link" means

[aidantwoods]

Splitting this from #476

There appears to be a discrepancy in meaning when using the word "link".

Autolinks are absolute URIs and email addresses inside < and >. They are parsed as links, with the URL or email address as the link label.

Does the use of the words "link" and "links" correspond to HTML element <a>, or the definition (*)?

(*)

A link contains link text (the visible text), a link destination (the URI that is the link destination), and optionally a link title. There are two basic kinds of links in Markdown. In inline links the destination and title are given immediately after the link text. In reference links the destination and title are defined elsewhere in the document.

From the definition, it would appear that this particular definition only applies to inline links and reference links. However this section is not linked to when used

e.g. in the definition for link text

Links may not contain other links, at any level of nesting. If multiple otherwise valid link definitions appear nested inside each other, the inner-most definition is used.

To repeat the initial question: Does the use of the words "link" and "links" correspond to HTML element <a>, or the definition (*)?

Which leads to another question: Can link text contain an autolink?

The definition of an autolink states that it is a "link" in the same way that link text states that it may not contain any "links".

---

For the purposes of demonstrating how this ambiguity may be resolved (and generally because it would be incomprehensible otherwise), I have used emphasis in the above to indicate when a word holds a definition defined in the CommonMark document. However in blockquotes, hyperlinks have been preserved from the document and no words are emphasised for the purpose of accuracy to the original text.

[fiveop]

Autolinks are absolute URIs and email addresses inside < and >. They are parsed as links, with the URL or email address as the link label.

Does the use of the words "link" and "links" correspond to HTML element , or the definition (*)?

My interpretation is: neither. Rather, "links" refers to the link element of the document data structure that is implicitely defined by this spec. Both "Links" and "Autolinks" parse into this implied structure. There are more words that are used to refer to both the CommonMark representation as well as the part of the implied structure. I think defining this structure explicitly would help clearify a lot of things.

[aidantwoods]

@fiveop that's a good point, perhaps "HTML element" wasn't the best choice there. For brevity, interpret the word hyperlink in the following to mean "link element of the document data structure".

---

Just to sum up the problem, according to the reference parser (and not the spec), the word "link" in

Autolinks are absolute URIs and email addresses inside < and >. They are parsed as links, with the URL or email address as the link label.

Means hyperlink.

While the word "link" in

Links may not contain other links, at any level of nesting. If multiple otherwise valid link definitions appear nested inside each other, the inner-most definition is used.

Means either inline link or reference link (as defined in CommonMark spec).

If the reference parser behaviour is what the spec intends then it should say so explicitly, or if the word "link" means the same thing in both cases then the spec should reference the definition in both places and the reference parser should be corrected. (I'd prefer the latter, since I don't think nesting hyperlinks would be likely to yield a reasonable result across browsers etc... I may be wrong though).

---

Currently the reference parser has the following results which demonstrate this discrepancy in meaning of the word:

[<https://example.com>](https://notexample.com)

to

<p><a href="https://notexample.com"><a href="https://example.com">https://example.com</a></a></p>

and

[[https://example.com](https://example.com)](https://notexample.com)

to

<p>[<a href="https://example.com">https://example.com</a>](https://notexample.com)</p>

[mgeier]

See also https://talk.commonmark.org/t/why-is-link-text-not-allowed-to-contain-other-links/2434.

[jgm]

This interacts with #193.