Commit a3cff33a authored by Dan Allen's avatar Dan Allen
Browse files

resolves #50 standardize on the term link text instead of linked text (PR #53)

parent fc6ca8e2
......@@ -17,6 +17,7 @@ Added::
Changed::
* Clarify the rules for include tag filtering; emphasize that the wildcards can only be used once
* Standardize on the "link text" term instead of "linked text" (#50)
== Published Q4 2020
......
......@@ -165,7 +165,7 @@ include::macros:example$url.adoc[tag=b-linkattrs]
IMPORTANT: The `link:` macro prefix is _not_ required when the target starts with a URL scheme like `https:`.
The URL scheme acts as an implicit macro prefix.
CAUTION: If the linked text contains a comma and the text is followed by one or more named attributes, you must enclose the text in double quotes.
CAUTION: If the link text contains a comma and the text is followed by one or more named attributes, you must enclose the text in double quotes.
Otherwise, the text will be cut off at the comma (and the remaining text will get pulled into the attribute parsing).
.URLs with spaces and special characters
......
......@@ -917,7 +917,7 @@ Defaults to the value of the `outfilesuffix` attribute.
|_empty_
|{n}
|{n}
|Prints the URI of a link after the linked text.
|Prints the URI of a link after the link text.
_PDF converter only_.
|showtitle
......
......@@ -14,7 +14,7 @@ Here are some examples:
* `image:` and `image::` (1) alt text, (2) width, (3) height
* Delimited blocks: (1) block name (aka style)
* Other inline quoted text: (1) role and ID shorthand
* `link:` and `xref:` (1) linked text
* `link:` and `xref:` (1) link text
* Custom blocks and macros can specify positional attributes
For example, the following two image macros are equivalent.
......
......@@ -22,8 +22,8 @@ include::example$url.adoc[tag=base-co]
----
<.> The trailing period will not get caught up in the link.
The URL is also used as the linked text.
If you want to custom the linked text, you can use the xref:url-macro.adoc[URL macro].
The URL is also used as the link text.
If you want to use xref:url-macro.adoc#link-text[custom link text], you must use the xref:url-macro.adoc[URL macro].
In plain text documents, a bare URL is often enclosed in angle brackets.
......
......@@ -4,7 +4,7 @@ The mailto macro is a specialization of the URL macro that adds support for augm
== Subject and body
Like with other URL macros, the first positional attribute of the email macro is the linked text.
Like with other URL macros, the first positional attribute of the email macro is the link text.
If a comma is present in the text, and the text is not enclosed in quotes, or the comma comes after the closing quote, the next positional attribute is treated as subject line.
For example, you can configure the email link to prepopulate the subject line when the reader clicks the link using the following syntax:
......@@ -25,12 +25,12 @@ mailto:join@discuss.example.org[Subscribe,Subscribe me,I want to join]
When the reader clicks the link, a conforming email client will fill in the body with "I want to join".
If you want to leave the linked text blank (so it falls back to the email address), start the attribute list with a comma so as to leave a blank slot for it.
If you want to leave the link text blank (so it falls back to the email address), start the attribute list with a comma so as to leave a blank slot for it.
[source]
----
mailto:join@discuss.example.org[,Subscribe me,I want to join]
----
If either the linked text, subject, or body contains a comma, that value must be enclosed in double quotes.
If either the link text, subject, or body contains a comma, that value must be enclosed in double quotes.
To learn more about how the attributes are parsed, refer to xref:link-macro-attribute-parsing.adoc[attribute parsing].
......@@ -98,5 +98,5 @@ To solve this problem, you can define the following two attributes:
:relfilesuffix: /
----
Now, the cross reference `+<<filename.adoc,linked text>>+` will resolve to [.path]_../filename_ instead of [.path]_filename.html_.
Now, the cross reference `+<<filename.adoc,link text>>+` will resolve to [.path]_../filename_ instead of [.path]_filename.html_.
Since this change is specific to the website architecture described, you want to be sure to only set these attributes in that particular environment (either using an ifdef directive or via the API).
= 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 is recognized as a single positional attribute.
This page explains the conditions when this occurs and how to write the link text so it is recognized as a single positional attribute.
== Linked text alongside named attributes
Normally, the whole text between the square brackets of a link macro is treated as the linked text (i.e., the first positional attribute).
Normally, the whole text between the square brackets of a link macro is treated as the link text (i.e., the first positional attribute).
[source]
----
......@@ -14,42 +14,42 @@ https://discuss.asciidoctor.org[Discuss Asciidoctor]
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:
As a simplified rule, to be sure that the link 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.
There are several other situations in which text before the first comma may be recognized as the link text.
Let's consider some examples.
The following example shows a URL macro with custom linked text alongside named attributes.
The following example shows a URL macro with custom link text alongside named attributes.
[source]
----
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 capture in its entirety as the first positional attribute.
Let's consider a case where the link text contains a comma and the macro also has named attributes.
In this case, you must enclose the link text in double quotes so that it is capture in its entirety as the first positional attribute.
[source]
----
https://example.org["Google, DuckDuckGo, Bing",role=teal]
----
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.
Similarly, if the link text contains an equals sign, you can enclose the link 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"]
----
The double quote enclosure is not required in all cases when the linked text contains an equals sign.
The double quote enclosure is not required in all cases when the link 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).
Finally, to use named attributes without specifying link 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 link text).
[source]
----
......@@ -114,7 +114,7 @@ To fine tune indexing within the site, you can specify the nofollow option even
=== Blank window shorthand
Since configuring an external link to target a blank window is a common practice, AsciiDoc provides a shorthand for it.
Instead of having to include `window=_blank` in the attribute list, you can add a caret (`+^+`) to the end of the linked text.
Instead of having to include `window=_blank` in the attribute list, you can add a caret (`+^+`) to the end of the link text.
[source]
----
......@@ -123,7 +123,7 @@ include::example$url.adoc[tag=linkattrs-s]
CAUTION: If you use the caret syntax more than once in a single paragraph, you may need to escape the first occurrence with a backslash.
If the attribute list has both linked text and named attributes, the caret should fall at the end of the linked text, but inside the double quotes if present.
If the attribute list has both link text and named attributes, the caret should fall at the end of the link text, but inside the double quotes if present.
[source]
----
......
......@@ -15,7 +15,7 @@ link:<target>[<attrlist>]
----
The `<target>` becomes the target of the link.
the `<attrlist>` is the linked text unless a named attribute is detected.
the `<attrlist>` is the link text unless a named attribute is detected.
See xref:link-macro-attribute-parsing.adoc[link macro attribute list] to learn how the `<attrlist>` is parsed.
Like all inline macros, the link macro can be escaped using a leading backslash (`\`).
......@@ -42,7 +42,7 @@ If the target file is an HTML file, and you want to link directly to an anchor w
include::example$url.adoc[tag=hash]
----
Note that when linking to a relative file, even if it's an HTML file, the linked text is required.
Note that when linking to a relative file, even if it's an HTML file, the link text is required.
// FIXME: this feels like it needs subsections
== When to use the link macro
......
......@@ -7,7 +7,7 @@ The pages in this section document how to add and customize links in an AsciiDoc
== URLs and links
The target of a link is a {url-url-def}[Uniform Resource Locator^] (URL), otherwise known as a web address.
The text you click to be navigate to that target is referred to as the linked text.
The text you click to be navigate to that target is referred to as the link text.
NOTE: You may sometimes see the term URI used in place of a URL.
Although the URI is more technically correct in some cases, URL is the accepted term.
......@@ -21,7 +21,7 @@ You can learn more about this behavior in xref:autolinks.adoc[].
== Link-related macros
Instead of showing the bare URL or email address as the linked text, you may want to customize that text.
Instead of showing the bare URL or email address as the link text, you may want to customize that text.
Or perhaps you want to apply attributes to the link, such as a role.
To do so, you'd use either the xref:url-macro.adoc[URL macro] or, if you're linking to xref:complex-urls.adoc[a complex URL], the more explicit xref:link-macro.adoc[link macro].
......@@ -32,7 +32,7 @@ When linking to an email address, you can use the specialized xref:email-macro.a
[#hide-uri-scheme]
== Hide the URL scheme
If the linked text is a bare URL (aka URI), whether that link was created automatically or using a link-related macro, you can configure the AsciiDoc processor to hide the scheme (e.g., _https://_).
If the link text is a bare URL (aka URI), whether that link was created automatically or using a link-related macro, you can configure the AsciiDoc processor to hide the scheme (e.g., _https://_).
Hiding the scheme can make the URL more readable--perhaps even recognizable--to a person less familiar with technical nomenclature.
To configure the AsciiDoc processor to display the linked URL without the scheme part, set the `hide-uri-scheme` attribute in the header of the AsciiDoc document.
......@@ -102,7 +102,7 @@ include::example$url.adoc[tag=irc]
----
// end::basic[]
Additionally, you can format the linked text.
Additionally, you can format the link text.
[source]
----
......
......@@ -37,7 +37,8 @@ Type "https://asciidoctor.org[]" into the location bar of your browser.
The more typical reason, however, is to specify custom link text.
== Custom linked text
[#link-text]
== Custom link text
Instead of displaying the URL, you can configure the link to display custom text.
When the reader clicks on the text, they are directed to the target of the link, the URL.
......
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