Chapter 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).

% 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
----

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 1

==== Level 3

6.3. Paragraphs

Paragraphs do not 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.4.1. 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.

  1. First item

  2. Second item

    1. Subsecond item

  3. Third item

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

To point to another website the link macro should be used.

link:https://www.FreeBSD.org[FreeBSD]

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.

To point to another book or article the Asciidoctor variables should be used. For example, in the cups article, to point to ipsec-must these steps should be used.

  1. Include the urls.adoc file from ~/doc/shared folder.

    include::shared/{lang}/urls.adoc[]

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

    IPSec-Must article

The extref macro is defined as an extension. It is designed to render the correct link across the different outputs

6.5.3. Links to the same file or to another file in the same book

Books are structured in different directories to keep a sane layout. To create a link from one subdirectory of a book to another subdirectory of the same book, use the crossref macro:

crossref:doc-build[documentation-makefile, This link]

And this would be rendered as

This link

The crossref macro is defined as an extension. It is designed to render the correct link across the different outputs

Use the crossref macro for intra-document links too. Although it might be inconvenient to write the name of the current document, it ensures the correct link is rendered across the different outputs

Do not use either the xref macro or its shortcut << >>. They do not work well in all output formats.

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.

Here is the example header of the FreeBSD Release Engineering article.

= FreeBSD Release Engineering
:doctype: article

[...]

:images-path: articles/freebsd-releng/ (1)


[...]

:imagesdir: ../../../images/{images-path} (2)

[...]
1Makes reference to the path inside /static/images folder.
2Makes 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 as shown in the example above.

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 title attribute is mandatory.

6.7. Creating an Index in FDP Articles and Books

Creating an index in FreeBSD Documentation Project documents is easy, because the index tooling is already built into AsciiDoctor. An index is simply a new section in a document or a new chapter in a book. Here’s a quick summary on how to generate an index for FreeBSD FDP books, articles, and multi-part documents.

The FDP toolkit does not generate an index for HTML output, only PDF output.

6.7.1. Creating an Index for Article Documents

Articles are single-part documents as opposed to muli-part documents like books. If the article is short - one or two pages - an index is hardly worth the trouble. But for larger articles, it can help the reader to easily locate specific terms.

AsciiDoctor only allows level 1 headings (== MyHeading) and higher levels for articles. It does not allow level 0 headings (= MyHeading) for articles, only books.

Here is a procedure for creating an index for an article.

  1. Decide where to place the index. The best location is usually at the end of the article.

  2. Add a new section to the bottom of the _index.adoc file. This tells AsciiDoctor where the index is to be placed. Use the following construction:

    [index]
== Index

  3. Continue below with "Tagging Terms for an Index"

6.7.2. Creating an Index for Book Documents

There are several additional steps necessary for building a book index. An index is a new chapter, and the steps below show how to integrate the new chapter into an existing book.

  1. Create a new chapter by copying an existing chapter. Usually, copying the last existing chapter works well. Here, chapter10 is used as the name of the last chapter.

    cd <bookdir>
cp -av chapter10 index

    Change the front matter in the index/_index.adoc as described below. Edit index/_index.adoc and change the title, and any "prev:" field. Also change the weight value.

      ---
  title: Index
  prev: books/mybook/chapter10
  description: Index
  tags: ["firewall", "IPFW", "Virtual Machine", "VM", "QEMU"]
  showBookMenu: true
  weight: 140
  path: "/books/mybook/index/"
  ---

    Make the weight value the highest value of any chapter in the book. This puts the index at the end of the book.

    Also, add or change the next: field in the front matter of the previous chapter (chapter10/_index.adoc).

  2. After all the front matter put the index header and title at the end as shown below. Use a level 0 section header for the title "Index". This puts the index on a separate page.

      . . .

  ifndef::env-beastie[]
  toc::[]
  include::../../../../../shared/asciidoctor.adoc[]
  endif::[]

  [index]
  = Index

6.7.3. Tagging Terms for the Index

Follow this procedure to tag items for the index.

  1. Now go through all the text in all the chapters and tag each term to be indexed. Add the indexterm:[] tags on their own line near the term. The tag placement can be on the line before or after the term - just be consistent. Note how subindex terms are specified.

    The quick brown fox jumps over the lazy dog.
indexterm:[fox] indexterm:[dog] indexterm:[animal, fox] indexterm:[animal, dog]

    This example creates four index entries as follows (all shown on page 1):

      A
    animal
        dog  1
        fox  1
  D
    dog  1
  F
    fox  1

    Additional notes

    Multiple tags on the same line are permitted. However, do not use tags on the same line as the term like this:

    Do not do this:
The quick brown fox jumps over the lazy dog. indexterm:[fox] indexterm[dog] indexterm[animal, fox] indexterm:[animal, dog]

    This tagging style (added to the end) conflicts with the FDP "One Sentence Per Line" directive and vale(1) will complain.

  2. Avoid tagging terms inside any block listings. The tags show up in the output. Instead, put the tags on a separate line either before the listing header or after the listing body. Leave one extra line before the listing header.

    indexterm:[fox] indexterm[dog] indexterm[animal, fox] indexterm:[animal, dog]
(Leave a blank line here.)
[.programlisting]
....
The quick brown fox jumps over the lazy dog.
....

  3. Avoid tagging terms inside [NOTE], [TIP], [WARNING], [IMPORTANT], and similar structures. The tags show up in the output in some cases.

  4. Be consistent in tag usage. Keep a running list of decisions on indexing. If a term in a tag is singular or capitalized or contains multiple words, always use the same stye of the term in other tags.

    Avoid mixing term styles like this:

    indexterm:[jump] indexterm:[jumps over] indexterm[Jump]

  5. Not every instance of a term needs its own tag. If there are several sentences together, each having the same term, or even nearby paragraphs having the same term, just tag the term once. The index entry will be the same for all of them. AsciiDoctor does not filter out multiple index entries on the same page.

  6. If tagging terms in a numbered procedure, place the tags on separate lines with '+' for continuation.

    Example:

    [.procedure]
====
. On the FreeBSD host, install the necessary packages - man:qemu[1], man:sudo[8] (or man:doas[1]).
The examples in this book use sudo.
+
indexterm:[QEMU, pkg install] indexterm:[sudo] indexterm:[sudo, pkg install]
+
[subs=+quotes]
----
# *pkg install qemu sudo*
----
+
. Create a directory layout for the files to be used.
+
indexterm:[SCRIPTS] indexterm:[ISO] indexterm:[fetch]
+
[subs=+quotes]
----
% *mkdir -p ~/ipfw/VM ~/ipfw/SCRIPTS ~/ipfw/ISO*
% *cd ~/ipfw/ISO*
% *fetch https://download.freebsd.org/releases/amd64/amd64/ISO-IMAGES/#<latest version>#/FreeBSD-#<latest-version>#-RELEASE-amd
64-dvd1.iso*
----
+
indexterm:[tap] indexterm:[bridge]
+
. Create the bridge and tap devices for the virtual machines (VMs) to use.
+
. Finish everything and go home.
====

  7. Make the document normally (make DOC_LANG=whatever). When the book is completed, open the PDF version and review the index for errors and consistency.

6.8. Conclusion

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

Last modified on: September 22, 2024 by Fernando Apesteguía

Home