From a3cff33a6910d2bcc5f562e2aaa873d3fcf80db0 Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Tue, 16 Feb 2021 12:18:36 -0700
Subject: [PATCH] resolves #50 standardize on the term link text instead of
linked text (PR #53)
---
CHANGELOG.adoc | 1 +
.../ROOT/pages/syntax-quick-reference.adoc | 2 +-
.../pages/document-attributes-reference.adoc | 2 +-
.../positional-and-named-attributes.adoc | 2 +-
modules/macros/pages/autolinks.adoc | 4 +--
modules/macros/pages/email-macro.adoc | 6 ++---
modules/macros/pages/inter-document-xref.adoc | 2 +-
.../pages/link-macro-attribute-parsing.adoc | 26 +++++++++----------
modules/macros/pages/link-macro.adoc | 4 +--
modules/macros/pages/links.adoc | 8 +++---
modules/macros/pages/url-macro.adoc | 3 ++-
11 files changed, 31 insertions(+), 29 deletions(-)
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index 335aeb1..5d3a5f9 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -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
diff --git a/modules/ROOT/pages/syntax-quick-reference.adoc b/modules/ROOT/pages/syntax-quick-reference.adoc
index d7b2300..235a817 100644
--- a/modules/ROOT/pages/syntax-quick-reference.adoc
+++ b/modules/ROOT/pages/syntax-quick-reference.adoc
@@ -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
diff --git a/modules/attributes/pages/document-attributes-reference.adoc b/modules/attributes/pages/document-attributes-reference.adoc
index d1e4c03..5e40d39 100644
--- a/modules/attributes/pages/document-attributes-reference.adoc
+++ b/modules/attributes/pages/document-attributes-reference.adoc
@@ -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
diff --git a/modules/attributes/pages/positional-and-named-attributes.adoc b/modules/attributes/pages/positional-and-named-attributes.adoc
index e7a0b30..383cb54 100644
--- a/modules/attributes/pages/positional-and-named-attributes.adoc
+++ b/modules/attributes/pages/positional-and-named-attributes.adoc
@@ -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.
diff --git a/modules/macros/pages/autolinks.adoc b/modules/macros/pages/autolinks.adoc
index 1c5eafb..9e9615f 100644
--- a/modules/macros/pages/autolinks.adoc
+++ b/modules/macros/pages/autolinks.adoc
@@ -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.
diff --git a/modules/macros/pages/email-macro.adoc b/modules/macros/pages/email-macro.adoc
index ef4776b..1777b07 100644
--- a/modules/macros/pages/email-macro.adoc
+++ b/modules/macros/pages/email-macro.adoc
@@ -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].
diff --git a/modules/macros/pages/inter-document-xref.adoc b/modules/macros/pages/inter-document-xref.adoc
index 4f5557c..7f2cc23 100644
--- a/modules/macros/pages/inter-document-xref.adoc
+++ b/modules/macros/pages/inter-document-xref.adoc
@@ -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).
diff --git a/modules/macros/pages/link-macro-attribute-parsing.adoc b/modules/macros/pages/link-macro-attribute-parsing.adoc
index 1fa158a..115c299 100644
--- a/modules/macros/pages/link-macro-attribute-parsing.adoc
+++ b/modules/macros/pages/link-macro-attribute-parsing.adoc
@@ -1,11 +1,11 @@
= 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]
----
diff --git a/modules/macros/pages/link-macro.adoc b/modules/macros/pages/link-macro.adoc
index f53809c..4963a00 100644
--- a/modules/macros/pages/link-macro.adoc
+++ b/modules/macros/pages/link-macro.adoc
@@ -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
diff --git a/modules/macros/pages/links.adoc b/modules/macros/pages/links.adoc
index 9952ef7..f84eaf0 100644
--- a/modules/macros/pages/links.adoc
+++ b/modules/macros/pages/links.adoc
@@ -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]
----
diff --git a/modules/macros/pages/url-macro.adoc b/modules/macros/pages/url-macro.adoc
index d1df980..2427184 100644
--- a/modules/macros/pages/url-macro.adoc
+++ b/modules/macros/pages/url-macro.adoc
@@ -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.
--
GitLab