From ed694f8223e45bf24a2bf99dddc9f169a76e4b1b Mon Sep 17 00:00:00 2001
From: Dan Allen <dan.j.allen@gmail.com>
Date: Wed, 9 Dec 2020 02:32:40 -0700
Subject: [PATCH] integrate the relative link into the link macro page; use
 xref macro for interdoc xrefs

---
 modules/macros/examples/url.adoc              |  4 +--
 modules/macros/examples/xref.adoc             |  4 +--
 modules/macros/pages/inter-document-xref.adoc |  2 +-
 modules/macros/pages/link-macro.adoc          | 19 +++++++++++--
 modules/macros/pages/relative-link.adoc       | 28 -------------------
 5 files changed, 22 insertions(+), 35 deletions(-)
 delete mode 100644 modules/macros/pages/relative-link.adoc

diff --git a/modules/macros/examples/url.adoc b/modules/macros/examples/url.adoc
index 23cb30c..2f4518f 100644
--- a/modules/macros/examples/url.adoc
+++ b/modules/macros/examples/url.adoc
@@ -45,11 +45,11 @@ Chat with other Asciidoctor users on the https://discuss.asciidoctor.org/[*maili
 // end::css[]
 
 // tag::link[]
-link:protocol.json[Open the JSON file]
+link:downloads/report.pdf[Get Report]
 // end::link[]
 
 // tag::hash[]
-link:external.html#livereload[LiveReload]
+link:tools.html#editors[]
 // end::hash[]
 
 // used in qr
diff --git a/modules/macros/examples/xref.adoc b/modules/macros/examples/xref.adoc
index 96fa374..f643183 100644
--- a/modules/macros/examples/xref.adoc
+++ b/modules/macros/examples/xref.adoc
@@ -25,11 +25,11 @@ Refer to link:document-b.html#section-b[Section B] for more information.
 // end::bad[]
 
 // tag::base-inter[]
-Refer to <<document-b.adoc#section-b,Section B>> for more information.
+Refer to xref:document-b.adoc#section-b[Section B] for more information.
 // end::base-inter[]
 
 // tag::base-inter-top[]
-Refer to <<document-b.adoc#,Document B>> for more information.
+Refer to xref:document-b.adoc[Document B] for more information.
 // end::base-inter-top[]
 
 // used in qr
diff --git a/modules/macros/pages/inter-document-xref.adoc b/modules/macros/pages/inter-document-xref.adoc
index e20a762..4f5557c 100644
--- a/modules/macros/pages/inter-document-xref.adoc
+++ b/modules/macros/pages/inter-document-xref.adoc
@@ -71,7 +71,7 @@ The following example demonstrates how to use the `relfilesuffix` attribute to c
 = Document Title
 \ifdef::env-github,env-browser[:relfilesuffix: .adoc]
 
-See the <<README#,README>>.
+See the xref:README.adoc[README].
 
 We could also write the link as link:README{relfilesuffix}[README].
 ----
diff --git a/modules/macros/pages/link-macro.adoc b/modules/macros/pages/link-macro.adoc
index 9b26a93..f53809c 100644
--- a/modules/macros/pages/link-macro.adoc
+++ b/modules/macros/pages/link-macro.adoc
@@ -20,15 +20,30 @@ See xref:link-macro-attribute-parsing.adoc[link macro attribute list] to learn h
 
 Like all inline macros, the link macro can be escaped using a leading backslash (`\`).
 
-Here's an example that demonstrates how to use the link macro to link to a relative path:
+== Link to a relative file
+
+If you want to link to a non-AsciiDoc file that is relative to the current document, use the `link` macro in front of the file name.
+
+TIP: To link to a relative AsciiDoc file, use the xref:inter-document-xref.adoc[xref macro] instead.
+
+Here's an example that demonstrates how to use the link macro to link to a relative file path:
 
 [source]
 ----
-link:report.pdf[Get Report]
+include::example$url.adoc[tag=link]
 ----
 
 The AsciiDoc processor will create a link to _report.pdf_ with the text "Get Report", even though the target is not a URL.
 
+If the target file is an HTML file, and you want to link directly to an anchor within that document, append a hash (`#`) followed by the name of the anchor after the file name:
+
+[source]
+----
+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.
+
 // FIXME: this feels like it needs subsections
 == When to use the link macro
 
diff --git a/modules/macros/pages/relative-link.adoc b/modules/macros/pages/relative-link.adoc
deleted file mode 100644
index 60c4f30..0000000
--- a/modules/macros/pages/relative-link.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-= Link to Relative Files
-
-If you want to link to an external file relative to the current document, use the `link` macro in front of the file name.
-
-[source]
-----
-include::example$url.adoc[tag=link]
-----
-
-If your file is an HTML file, you can link directly to a section in the document, append a hash (`#`) followed by the section's ID to the end of the file name.
-
-[source]
-----
-include::example$url.adoc[tag=hash]
-----
-
-////
-You can also create links that refer to sections within the current document.
-
-[source]
-----
-link:user-manual.html[URLs]
-----
-
-====
-link:user-manual.html[URLs]
-====
-////
-- 
GitLab