Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation: primer: AsciiDoc link macro; and Asciidoctor #223

Closed
wants to merge 3 commits into from
Closed

Documentation: primer: AsciiDoc link macro; and Asciidoctor #223

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2b36092
Documentation: primer: AsciiDoc link macro
grahamperrin Jul 15, 2023
a8482ad
Documentation: primer: Asciidoctor
grahamperrin Jul 15, 2023
8bdbc5f
Merge branch 'freebsd:main' into asciidoc-link-macro
grahamperrin Jul 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 19 additions & 22 deletions documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
---
title: Chapter 6. AsciiDoctor Primer
title: Chapter 6. Asciidoctor Primer
prev: books/fdp-primer/doc-build
next: books/fdp-primer/rosetta
description: A brief introduction to AsciiDoctor
tags: ["AsciiDoc", "AsciiDoctor", "Primer", "Introduction", "Guide"]
description: A brief introduction to Asciidoctor
tags: ["AsciiDoc", "Asciidoctor", "Primer", "Introduction", "Guide"]
showBookMenu: true
weight: 7
path: "/books/fdp-primer/"
---

[[asciidoctor-primer]]
= AsciiDoctor Primer
= Asciidoctor Primer
:doctype: book
:toc: macro
:toclevels: 1
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -97,7 +97,7 @@ To remove */tmp/foo*, use man:rm[1].
[[asciidoctor-headings]]
== Headings

AsciiDoctor supports six headings levels.
Asciidoctor supports six headings levels.
If the document type is `article` only one level 0 (`=`) can be used.
If the document type is `book` then there can be multiple level 0 (`=`) headings.

Expand Down Expand Up @@ -155,8 +155,8 @@ And this is the second paragraph.
[[asciidoctor-lists]]
== 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].
Asciidoctor supports a few types of lists, the most common are `ordered` and `unordered`.
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
Expand Down Expand Up @@ -206,22 +206,14 @@ 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

To point to another book or article the AsciiDoctor variables should be used.
To point to another book or article the Asciidoctor variables should be used.
For example, if we are in the `cups` article and we want to point to `ipsec-must` these steps should be used.

. Include the [.filename]#urls.adoc# file from [.filename]#~/doc/shared# folder.
Expand All @@ -230,7 +222,7 @@ For example, if we are in the `cups` article and we want to point to `ipsec-must
\include::shared/{lang}/urls.adoc[]
....
+
. Then create a link using the AsciiDoctor variable to the `ipsec-must` article.
. Then create a link using the Asciidoctor variable to the `ipsec-must` article.
+
....
extref:{ipsec-must}[IPSec-Must article]
Expand All @@ -240,8 +232,13 @@ 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].
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Amongst the few use cases:

  • The target must be enclosed in a passthrough to escape characters with special meaning

#223 (comment)

… languages with non-latin …

Would passthrough apply?

Under Escape and Prevent Substitutions, Passthroughs begins:

A passthrough is the primary mechanism by which to escape content in AsciiDoc. …

HTH


[[asciidoctor-conclusion]]
== Conclusion

This is the conclusion of this AsciiDoctor primer.
This is the conclusion of this Asciidoctor primer.
For reasons of space and complexity, several things have not been covered in depth (or at all).