integrate the relative link into the link macro page; use xref macro for interdoc xrefs

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

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

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].
 ----

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
 

modules/macros/pages/relative-link.adoc

-= 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]
-====
-////