diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 16027ea5cbd4d7e60c2fbb28f8d9a6be172cfdac..3ba86be14fb3b9d8ca2569bdac4890248fa27e7d 100644 --- a/CHANGELOG.adoc +++ b/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. diff --git a/modules/macros/pages/link-macro-attribute-parsing.adoc b/modules/macros/pages/link-macro-attribute-parsing.adoc index 63347058b7689f0e0e73ead6dce276d0f2a12888..3a27187508c8b7b37838d72a2cdde5714bb26649 100644 --- a/modules/macros/pages/link-macro-attribute-parsing.adoc +++ b/modules/macros/pages/link-macro-attribute-parsing.adoc @@ -1,7 +1,7 @@ = 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: