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 3ad0e15b60..9638651e68 100644 --- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc +++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc @@ -1,247 +1,247 @@ --- -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 :icons: font :sectnums: :sectnumlevels: 6 :sectnumoffset: 6 :partnums: :source-highlighter: rouge :experimental: :images-path: books/fdp-primer/ ifdef::env-beastie[] ifdef::backend-html5[] :imagesdir: ../../../../images/{images-path} endif::[] ifndef::book[] include::shared/authors.adoc[] include::shared/mirrors.adoc[] include::shared/releases.adoc[] include::shared/attributes/attributes-{{% lang %}}.adoc[] include::shared/{{% lang %}}/teams.adoc[] include::shared/{{% lang %}}/mailing-lists.adoc[] include::shared/{{% lang %}}/urls.adoc[] toc::[] endif::[] ifdef::backend-pdf,backend-epub3[] include::../../../../../shared/asciidoctor.adoc[] endif::[] endif::[] ifndef::env-beastie[] toc::[] include::../../../../../shared/asciidoctor.adoc[] 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]. +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]. [[asciidoctor-primer-overview]] == Overview In the original days of computers, electronic text was simple. There were a few character sets like ASCII or EBCDIC, but that was about it. Text was text, and what you saw really was what you got. No frills, no formatting, no intelligence. Inevitably, this was not enough. When text is in a machine-usable format, machines are expected to be able to use and manipulate it intelligently. Authors want to indicate that certain phrases should be emphasized, or added to a glossary, or made into hyperlinks. Filenames could be shown in a “typewriter” style font for viewing on screen, but as “italics” when printed, or any of a myriad of other options for presentation. It was once hoped that Artificial Intelligence (AI) would make this easy. The computer would read the document and automatically identify key phrases, filenames, text that the reader should type in, examples, and more. Unfortunately, real life has not happened quite like that, and computers still require assistance before they can meaningfully process text. More precisely, they need help identifying what is what. Consider this text: To remove [.filename]#/tmp/foo#, use man:rm[1]. [source,shell] ---- % rm /tmp/foo ---- It is easy for the reader to see which parts are filenames, which are commands to be typed in, which parts are references to manual pages, and so on. But the computer processing the document cannot reliably determine this. For this we need markup. The previous example is actually represented in this document like this: .... To remove */tmp/foo*, use man:rm[1]. [source,shell] ---- % rm /tmp/foo ---- .... [[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. This is an example of headings in an `article`. .... = Document Title (Level 0) == Level 1 Section Title === Level 2 Section Title ==== Level 3 Section Title ===== Level 4 Section Title ====== Level 5 Section Title == Another Level 1 Section Title .... [WARNING] ==== Section levels cannot be skipped when nesting sections. The following syntax is not correct. .... = Document Title == Level 2 ==== Level 4 .... ==== [[asciidoctor-paragraphs]] == Paragraphs Paragraphs don't require special markup in AsciiDoc. A paragraph is defined by one or more consecutive lines of text. To create a new paragraph leave one blank line. For example, this is a heading with two paragraphs. .... = This is the heading This is the first paragraph. This is also the first paragraph. And this is the second paragraph. .... [[asciidoctor-lists]] == Lists -AsciiDoctor supports a few types of lists, the most common are `ordered` and `unordered`. +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-ordered-lists]] === Ordered lists To create an ordered list use the `.` character. For example, this is an ordered list. .... . First item . Second item .. Subsecond item . Third item .... And this would be rendered as. . First item . Second item .. Subsecond item . Third item [[asciidoctor-unordered-lists]] === Unordered lists To create an unordered list use the `*` character. For example, this is an unordered list. .... * First item * Second item ** Subsecond item * Third item .... And this would be rendered as. * First item * Second item ** Subsecond item * Third item [[asciidoctor-links]] == Links [[asciidoctor-links-external]] === External links To point to another website the `link` macro should be used. .... 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. +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. ==== [[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. + .... \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] .... + And this would be rendered as. + extref:{ipsec-must}[IPSec-Must article] [[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).