Understanding "first link label" in collapsed/shortcut reference link definitions

[muzimuzhi]

In spec 0.30, the definitions of collapsed reference link and shortcut reference link both contain

The contents of the first link label are parsed as inlines, which are used as the link’s text.

Here the meaning of "first link label" is unclear.

On https://spec.commonmark.org/dingus, markdown snippet

[MY link target]: /uri

[my LINK target][]

[my link TARGET]

[MY LINK TARGET]: /uri2

is parsed to

<p><a href="/uri">my LINK target</a></p>
<p><a href="/uri">my link TARGET</a></p>

See permalink. Considering only the case of words, BabelMark 3 gives the same result.

This test shows that the resulting link text in output is the parsing result of the link label making up current collapsed/shortcut reference link, which seems to me that the phrase "first link label" is misleading. If the first link label is chose, then where are the remaining link labels?

There was a similar issue #581 reporting misleading "first link label" in definition of "full reference link", which was resolved by removing that phrase, in commit 5004d7d (Fix misleading text for full reference link., 2019-05-01). Full reference link is special in having its link text explicitly given, but the "first link label" phrase is still misleading in other two kinds of reference links.

PS: I originally found this mystery when reading the GFM spec.

PS 2: When #581 was opened, there're three occurrences of "first link label", all added by the second commit in this repo, master branch: 870e63b (initial commit, 2014-08-14).

[wooorm]

I think you’re conflating the term “label” and the term “definition”:

[MY link target]: /uri
^-- this is a definition: `[MY link target]` could be called a label.

[my LINK target][]
^-- this is a reference: `[my LINK target]` is a label. `[]` could be called another label.

[my link TARGET]
^-- this is a reference: `[my link TARGET]` is a label.

[MY LINK TARGET]: /uri2
^-- this is a definition: `[MY LINK TARGET]` could be called a label.

If two (or more) defintions with the same normalized identifier taken from the label, exist, the first one “wins”.
References, if their label turned into a normalized identifier matches a definition’s normalized identifier, turn into links. To the URL of the first definition.

[muzimuzhi]

[my LINK target][]
^-- this is a reference: `[my LINK target]` is a label. `[]` could be called another label.

Yes "[] could be called another label." is the key for collapsed reference. Unfortunately the Spec 0.30 specifically excludes the possibility of [] becoming a label (boldface added by me)

A link label begins with a left bracket ([) and ends with the first right bracket (]) that is not backslash-escaped. Between these brackets there must be at least one character that is not a space, tab, or line ending.
[...]
A link label must contain at least one character that is not a space, tab, or line ending:
Example 550
Example 551

[my link TARGET]
^-- this is a reference: `[my link TARGET]` is a label.

A shortcut reference has only one label, but the paragraph in the Spec 0.30 still uses phrase "first link label", which makes me confusing. (boldface added by me, again)

A shortcut reference link consists of a link label that matches a link reference definition elsewhere in the document and is not followed by [] or a link label. The contents of the first link label are parsed as inlines, which are used as the link’s text. The link’s URI and title are provided by the matching link reference definition. Thus, [foo] is equivalent to [foo][].

One can argue that its "second label" is omitted...

Maybe the meaning of "[] could be called another label." was once expressed in an older release of the Spec, but I really can't find any similar descriptions in current Spec 0.30.

[jgm]

I agree that this is confusing. I've just deleted the "first"s. Thanks!

[muzimuzhi]

Thank you, too (also for your wonderful pandoc 🎉 )!