mirror of https://git.FreeBSD.org/doc.git
226 lines
5.7 KiB
Plaintext
226 lines
5.7 KiB
Plaintext
---
|
|
title: Chapter 6. AsciiDoctor Primer
|
|
prev: books/fdp-primer/doc-build
|
|
next: books/fdp-primer/rosetta
|
|
description: A brief introduction to AsciiDoctor
|
|
---
|
|
|
|
[[asciidoctor-primer]]
|
|
= AsciiDoctor Primer
|
|
:doctype: book
|
|
:toc: macro
|
|
:toclevels: 1
|
|
:icons: font
|
|
:sectnums:
|
|
:sectnumlevels: 6
|
|
:source-highlighter: rouge
|
|
:experimental:
|
|
:skip-front-matter:
|
|
:xrefstyle: basic
|
|
:relfileprefix: ../
|
|
:outfilesuffix:
|
|
:sectnumoffset: 6
|
|
|
|
include::shared/en/urls.adoc[]
|
|
|
|
toc::[]
|
|
|
|
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].
|
|
|
|
[[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 [.filename]#/tmp/foo#, use man:rm[1].
|
|
|
|
[source,shell]
|
|
----
|
|
% rm /tmp/foo
|
|
----
|
|
....
|
|
|
|
[[asciidoctor-headings]]
|
|
== 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
|
|
....
|
|
|
|
[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 two type of lists: ordered and unordered.
|
|
To get more information about lists check 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.
|
|
====
|
|
|
|
[[asciidoctor-links-internal]]
|
|
=== 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 [.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.
|
|
+
|
|
....
|
|
link:{ipsec-must}[IPSec-Must article]
|
|
....
|
|
+
|
|
And this would be rendered as.
|
|
+
|
|
link:{ipsec-must}[IPSec-Must article]
|
|
|
|
[[asciidoctor-conclusion]]
|
|
== 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).
|