clarify how link text is parsed in relation to named attributes (PR #33)

* rewrite much of the description of link attribute parsing to reflect the simplified parsing behavior implemented in https://github.com/asciidoctor/asciidoctor/issues/2059
* remove the detail about how positional attributes are parsed, which will be covered in a dedicated page

Authored by: David Jencks <djencks@apache.org>

CHANGELOG.adoc

@@ -4,6 +4,11 @@ This document summarizes the changes introduced to the AsciiDoc Language Documen
 For a detailed view of what's changed, refer to the repository's
 https://github.com/asciidoctor/asciidoc-docs/commits/main[commit history].
 
+== Published Q1 2021
+
+Fixed::
+* Rewrite much of link-macro-attribute-parsing.adoc to reflect the simplified parsing behavior implemented in https://github.com/asciidoctor/asciidoctor/issues/2059.
+
 == Published Q4 2020
 
 These changes were committed and merged into the main branch starting on November 24, 2020.

modules/macros/pages/link-macro-attribute-parsing.adoc

 = Link Macro Attribute Parsing
 
 If named attributes are detected between the square brackets of a link macro (including URL macros), that text is parsed as an attribute list.
-This page explains the conditions when this occurs and how to write the linked text so it does not get caught up in this parsing.
+This page explains the conditions when this occurs and how to write the linked text so it is recognized as a single positional attribute.
 
 == Linked text alongside named attributes
 
@@ -12,8 +12,14 @@ Normally, the whole text between the square brackets of a link macro is treated
 https://discuss.asciidoctor.org[Discuss Asciidoctor]
 ----
 
-However, if the text contains both an equals sign (`=`) and a comma (`,`), and the comma comes after the equals sign, the text is parsed as an attribute list.
-In this case, the linked text is the first positional attribute.
+However, if the text contains an equals sign (`=`), the text is parsed as an xref:attributes:element-attributes.adoc#attribute-list[attribute list].
+The exact rules for attribute list parsing and positional attributes are rather complex, and discussed on xref:attributes:positional-and-named-attributes.adoc[].
+As a simplified rule, to be sure that the linked text is recognized properly, it can either:
+
+* contain no comma (`,`) or equals sign (`=`)
+* or be enclosed in double quotes (`"`).
+
+There are several other situations in which text before the first comma may be recognized as the linked text.
 
 The following example shows a URL macro with custom linked text alongside named attributes.
 
@@ -22,26 +28,31 @@ The following example shows a URL macro with custom linked text alongside named
 https://discuss.asciidoctor.org[Discuss Asciidoctor,role=resource,window=_blank]
 ----
 
-If you want to define a single named attribute, but leave the linked text empty (so it falls back to the URL), then you need to start the attribute list with a comma.
-In other words, you need to leave a slot for the linked text so that the parser knows where it ends.
-Otherwise, the parser will treat the named attribute as the linked text.
+Let's consider a case where the linked text contains a comma and the macro also has named attributes.
+In this case, you must enclose the linked text in double quotes so that it is recognized as a single (positional) attribute.
 
 [source]
 ----
-https://discuss.asciidoctor.org[,role=resource]
+https://example.org["Google, Yahoo, Bing",role=teal]
 ----
 
-When attribute parsing is enabled, the link macro recognizes all the common attributes (id, role, and opts).
-It also recognizes a handful of attributes that are specific to the link macro.
+Similarly, if the linked text contains an equals sign, the text may be enclosed in double quotes to assure recognition as a positional attribute.
 
-Let's consider a case when the linked text contains a comma and macro also has named attributes.
-In this case, you must enclose the linked text in double quotes so that it gets preserved by the parser.
+[source]
+----
+https://example.org["1=2 posits the problem of inequality"]
+----
+
+Finally, for automatic linked text and named attributes, you simply specify the named attributes.
 
 [source]
 ----
-https://example.org["Google, Yahoo, Bing",role=teal]
+https://discuss.asciidoctor.org[role=bagel,window=_blank,opts=nofollow]
 ----
 
+The link macro recognizes all the common attributes (id, role, and opts).
+It also recognizes a handful of attributes that are specific to the link macro.
+
 == Target a separate window
 
 By default, the link produced by a link macro will target the current window.
@@ -67,8 +78,8 @@ https://asciidoctor.org[Asciidoctor,window=_blank]
 
 === noopener and nofollow
 
-When the value of the `window` attribute is `_blank`, the AsciiDoc processor should also add the `rel="noopener"` attribute to the link tag in the HTML output.
-Doing so is considered a security best pratice.
+When the value of the `window` attribute is `_blank`, the AsciiDoc processor will also add the `rel="noopener"` attribute to the link tag in the HTML output.
+Doing so is considered a security best practice.
 
 If the window is not `_blank`, you need to enable this behavior explicitly by setting the `noopener` option on the macro: