% rm /tmp/fooChapter 6. Asciidoctor Primer
Table of Contents
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 Asciidoctor documentation. Some of the examples used in this chapter have been taken from the AsciiDoc Syntax Quick Reference.
6.1. 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 /tmp/foo, use rm(1).
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 ----
6.2. Headings
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
Section levels cannot be skipped when nesting sections. The following syntax is not correct. = Document Title == Level 2 ==== Level 4 |
6.3. 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.
6.4. Lists
Asciidoctor supports a few types of lists, the most common are ordered and unordered.
To get more information about lists, see AsciiDoc Syntax Quick Reference.
6.5. Links
6.5.1. External links
To point to another website the link macro should be used.
link:https://www.FreeBSD.org[FreeBSD]
As the Asciidoctor documentation describes, the |
6.5.2. Internal link
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 urls.adoc file from ~/doc/shared folder.
include::shared/{lang}/urls.adoc[]Then create a link using the Asciidoctor variable to the
ipsec-mustarticle.extref:{ipsec-must}[IPSec-Must article]And this would be rendered as.
6.6. Images and Icons
Images and icons play a crucial role in enhancing the overall user experience. These visual elements are strategically integrated to convey information, clarify concepts, and provide a visually engaging interface.
6.6.1. Images
Images help illustrate complex concepts, making them more accessible to users.
The first step will be to add the image in the images directory in the path:
~/website/static/images/ for the website.
~/documentation/static/images/ for the documentation.
For example, to add a new image to the FreeBSD installation process, the image will be saved to the path ~/documentation/static/images/books/handbook/bsdinstall/new-image3.png.
The next step will be to configure the Asciidoctor attributes images-path and imagesdir.
We are going to use as an example the header of the FreeBSD Release Engineering article.
= FreeBSD Release Engineering
:doctype: article
[...]
:images-path: articles/freebsd-releng/ (1)
[...]
:imagesdir: ../../../images/{images-path} (2)
[...]| 1 | Makes reference to the path inside /static/images folder. |
| 2 | Makes reference to the Asciidoctor attribute. |
Once the image is in the correct path and the Asciidoctor attributes have been configured in the document, the image macro can be used.
This is an example:
image::new-image3.png[New step in the FreeBSD install process]
To improve accessibility, it is mandatory to add descriptive text to each image. |
6.6.2. Icons
Icons serve as intuitive symbols for quick recognition and navigation.
The first step to use icons is to add the icons property to the Asciidoctor properties section, at the top of each document.
:icons: font
Once the Asciidoctor icon property has been set an icon supported by Font Awesome can be added.
This is an example about how to use the envelope icon:
icon:envelope[link=mailto:test@example.com, title="contact"]
To improve the accessibility of the website, the |
Last modified on: September 20, 2023 by Sergio Carlavilla Delgado