From 2b36092db49510772cc85e3d2f390fb75e68c195 Mon Sep 17 00:00:00 2001 From: Graham Perrin Date: Sat, 15 Jul 2023 13:51:14 +0100 Subject: [PATCH] Documentation: primer: AsciiDoc link macro Begin making proper use of the macro. Prefixing: - only where necessary - not with https: or mailto: URL schemes. --- .../fdp-primer/asciidoctor-primer/_index.adoc | 23 ++++++++----------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc index 3ad0e15b60f2..c009930c747c 100644 --- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc +++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc @@ -49,8 +49,8 @@ endif::[] Most FDP documentation is written with AsciiDoc. This chapter explains what that means, how to read and understand the documentation source, and the techniques used. -To get a complete reference of the AsciiDoctor capabilities please consult the link:https://docs.asciidoctor.org/home/[Asciidoctor documentation]. -Some of the examples used in this chapter have been taken from the link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference[AsciiDoc Syntax Quick Reference]. +To get a complete reference of the AsciiDoctor capabilities please consult the https://docs.asciidoctor.org/home/[Asciidoctor documentation]. +Some of the examples used in this chapter have been taken from the https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference[AsciiDoc Syntax Quick Reference]. [[asciidoctor-primer-overview]] == Overview @@ -156,7 +156,7 @@ And this is the second paragraph. == Lists AsciiDoctor supports a few types of lists, the most common are `ordered` and `unordered`. -To get more information about lists, see link:https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc Syntax Quick Reference]. +To get more information about lists, see https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#lists[AsciiDoc Syntax Quick Reference]. [[asciidoctor-ordered-lists]] === Ordered lists @@ -206,17 +206,9 @@ And this would be rendered as. [[asciidoctor-links-external]] === External links -To point to another website the `link` macro should be used. +The `link:` macro prefix is https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#links[*not* required] when the target starts with a URL scheme such as `https:` or `mailto:`. -.... -link:https://www.FreeBSD.org[FreeBSD] -.... - -[NOTE] -==== -As the AsciiDoctor documentation describes, the `link` macro is not required when the target starts with a URL scheme like `https`. -However, it is a good practice to do this anyway to ensure that AsciiDoctor renders the link correctly, especially in non-latin languages like Japanese. -==== +The URL scheme acts as an implicit macro prefix. [[asciidoctor-links-internal]] === Internal link @@ -240,6 +232,11 @@ And this would be rendered as. + extref:{ipsec-must}[IPSec-Must article] +[[asciidoctor-link-macro]] +=== The link macro + +This macro is not often needed. Use cases are https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro/#when-to-use-the-link-macro[specified in Asciidoctor Docs]. + [[asciidoctor-conclusion]] == Conclusion