Commit 7d5c1aea authored by Dan Allen's avatar Dan Allen
Browse files

minor revisions to the link macro attribute parsing page

parent 59a0035c
......@@ -5,7 +5,7 @@ This page explains the conditions when this occurs and how to write the linked t
== Linked text alongside named attributes
Normally, the whole text between the square brackets of a link macro is treated as the linked text.
Normally, the whole text between the square brackets of a link macro is treated as the linked text (i.e., the first positional attribute).
[source]
----
......@@ -20,6 +20,7 @@ As a simplified rule, to be sure that the linked text is recognized properly, it
* 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.
Let's consider some examples.
The following example shows a URL macro with custom linked text alongside named attributes.
......@@ -29,21 +30,26 @@ https://discuss.asciidoctor.org[Discuss Asciidoctor,role=resource,window=_blank]
----
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.
In this case, you must enclose the linked text in double quotes so that it is capture in its entirety as the first positional attribute.
[source]
----
https://example.org["Google, Yahoo, Bing",role=teal]
https://example.org["Google, DuckDuckGo, Bing",role=teal]
----
Similarly, if the linked text contains an equals sign, the text may be enclosed in double quotes to assure recognition as a positional attribute.
Similarly, if the linked text contains an equals sign, you can enclose the linked text in double quotes to ensure the parser recognizes it as the first positional attribute.
[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.
The double quote enclosure is not required in all cases when the linked text contains an equals sign.
Strictly speaking, the enclosure is only required when the text preceding the equals sign matches a valid attribute name.
However, it's best to use the double quotes just to be safe.
Finally, to use named attributes without specifying linked text, you simply specify the named attributes.
(In other words, you leave the first positional attribute empty, in which case the target will be used as the linked text).
[source]
----
......@@ -121,5 +127,5 @@ If the attribute list has both linked text and named attributes, the caret shoul
[source]
----
https://example.org["Google, Yahoo, Bing^",role=teal]
https://example.org["Google, DuckDuckGo, Bing^",role=teal]
----
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment