Asciidoctor ist eine schnelle, quelloffene Textverarbeitungs- und Publikationswerkzeugkette zur Konvertierung von AsciiDoc-Inhalten in HTML5, DocBook, PDF, man-Pages und andere Formate. Asciidoctor ist in Ruby geschrieben und läuft auf allen gängigen Betriebssystemen. Das Asciidoctor-Projekt wird auf GitHub - Asciidoctor gehostet.

Ab hier werden root-Rechte zur Ausführung der nachfolgenden Befehle benötigt. Um der Benutzer root zu werden, geben Sie bitte nachfolgenden Befehl ein:

$ su -
Password: 

Zur Installation von Asciidoctor über ein rpm-Paket, soll hier das Repository eines Drittanbieters genutzt werden, da Asciidoctor nicht im CentOS-Repository enthalten ist.

Nachfolgend soll das Repository des Drittanbieters EPEL genutzt werden. Eine Anleitung, wie das Repository des Drittanbieters EPEL eingebunden werden könnte, kann unter nachfolgendem internen Link nachgelesen werden:

• EPEL CentOS 7

Zur Installation von Asciidoctor wird nachfolgendes Paket benötigt:

• rubygem-asciidoctor - ist im epel-Repository des Drittanbieters EPEL enthalten

Mit nachfolgendem Befehl, wird das Pakete rubygem-asciidoctor installiert:

# yum install rubygem-asciidoctor
Loaded plugins: changelog, langpacks, priorities
325 packages excluded due to repository priority protections
Resolving Dependencies
--> Running transaction check
---> Package rubygem-asciidoctor.noarch 0:1.5.6.1-1.el7 will be installed
--> Processing Dependency: /usr/bin/ruby for package: rubygem-asciidoctor-1.5.6.1-1.el7.noarch
--> Processing Dependency: ruby(release) for package: rubygem-asciidoctor-1.5.6.1-1.el7.noarch
--> Running transaction check
---> Package ruby.x86_64 0:2.0.0.648-35.el7_6 will be installed
--> Processing Dependency: rubygem(bigdecimal) >= 1.2.0 for package: ruby-2.0.0.648-35.el7_6.x86_64
--> Processing Dependency: ruby(rubygems) >= 2.0.14.1 for package: ruby-2.0.0.648-35.el7_6.x86_64
---> Package ruby-libs.x86_64 0:2.0.0.648-35.el7_6 will be installed
--> Running transaction check
---> Package rubygem-bigdecimal.x86_64 0:1.2.0-35.el7_6 will be installed
---> Package rubygems.noarch 0:2.0.14.1-35.el7_6 will be installed
--> Processing Dependency: rubygem(rdoc) >= 4.0.0 for package: rubygems-2.0.14.1-35.el7_6.noarch
--> Processing Dependency: rubygem(psych) >= 2.0.0 for package: rubygems-2.0.14.1-35.el7_6.noarch
--> Processing Dependency: rubygem(io-console) >= 0.4.2 for package: rubygems-2.0.14.1-35.el7_6.noarch
--> Running transaction check
---> Package rubygem-io-console.x86_64 0:0.4.2-35.el7_6 will be installed
---> Package rubygem-psych.x86_64 0:2.0.0-35.el7_6 will be installed
---> Package rubygem-rdoc.noarch 0:4.0.0-35.el7_6 will be installed
--> Processing Dependency: ruby(irb) = 2.0.0.648 for package: rubygem-rdoc-4.0.0-35.el7_6.noarch
--> Processing Dependency: rubygem(json) >= 1.7.7 for package: rubygem-rdoc-4.0.0-35.el7_6.noarch
--> Running transaction check
---> Package ruby-irb.noarch 0:2.0.0.648-35.el7_6 will be installed
---> Package rubygem-json.x86_64 0:1.7.7-35.el7_6 will be installed
--> Finished Dependency Resolution

Changes in packages about to be updated:


Dependencies Resolved

================================================================================
 Package                 Arch       Version                   Repository   Size
================================================================================
Installing:
 rubygem-asciidoctor     noarch     1.5.6.1-1.el7             epel        214 k
Installing for dependencies:
 ruby                    x86_64     2.0.0.648-35.el7_6        updates      72 k
 ruby-irb                noarch     2.0.0.648-35.el7_6        updates      93 k
 ruby-libs               x86_64     2.0.0.648-35.el7_6        updates     2.8 M
 rubygem-bigdecimal      x86_64     1.2.0-35.el7_6            updates      84 k
 rubygem-io-console      x86_64     0.4.2-35.el7_6            updates      55 k
 rubygem-json            x86_64     1.7.7-35.el7_6            updates      80 k
 rubygem-psych           x86_64     2.0.0-35.el7_6            updates      83 k
 rubygem-rdoc            noarch     4.0.0-35.el7_6            updates     322 k
 rubygems                noarch     2.0.14.1-35.el7_6         updates     220 k

Transaction Summary
================================================================================
Install  1 Package (+9 Dependent packages)

Total download size: 4.0 M
Installed size: 13 M
Is this ok [y/d/N]: y
Downloading packages:
(1/10): ruby-2.0.0.648-35.el7_6.x86_64.rpm                 |  72 kB   00:00     
(2/10): ruby-irb-2.0.0.648-35.el7_6.noarch.rpm             |  93 kB   00:00     
(3/10): rubygem-bigdecimal-1.2.0-35.el7_6.x86_64.rpm       |  84 kB   00:00     
(4/10): rubygem-asciidoctor-1.5.6.1-1.el7.noarch.rpm       | 214 kB   00:00     
(5/10): rubygem-io-console-0.4.2-35.el7_6.x86_64.rpm       |  55 kB   00:00     
(6/10): rubygem-json-1.7.7-35.el7_6.x86_64.rpm             |  80 kB   00:00     
(7/10): rubygem-psych-2.0.0-35.el7_6.x86_64.rpm            |  83 kB   00:00     
(8/10): ruby-libs-2.0.0.648-35.el7_6.x86_64.rpm            | 2.8 MB   00:00     
(9/10): rubygem-rdoc-4.0.0-35.el7_6.noarch.rpm             | 322 kB   00:00     
(10/10): rubygems-2.0.14.1-35.el7_6.noarch.rpm             | 220 kB   00:00     
--------------------------------------------------------------------------------
Total                                              7.5 MB/s | 4.0 MB  00:00     
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
  Installing : ruby-libs-2.0.0.648-35.el7_6.x86_64                         1/10 
  Installing : ruby-irb-2.0.0.648-35.el7_6.noarch                          2/10 
  Installing : rubygem-bigdecimal-1.2.0-35.el7_6.x86_64                    3/10 
  Installing : rubygem-json-1.7.7-35.el7_6.x86_64                          4/10 
  Installing : rubygem-psych-2.0.0-35.el7_6.x86_64                         5/10 
  Installing : rubygem-io-console-0.4.2-35.el7_6.x86_64                    6/10 
  Installing : rubygems-2.0.14.1-35.el7_6.noarch                           7/10 
  Installing : ruby-2.0.0.648-35.el7_6.x86_64                              8/10 
  Installing : rubygem-rdoc-4.0.0-35.el7_6.noarch                          9/10 
  Installing : rubygem-asciidoctor-1.5.6.1-1.el7.noarch                   10/10 
  Verifying  : ruby-2.0.0.648-35.el7_6.x86_64                              1/10 
  Verifying  : ruby-irb-2.0.0.648-35.el7_6.noarch                          2/10 
  Verifying  : ruby-libs-2.0.0.648-35.el7_6.x86_64                         3/10 
  Verifying  : rubygem-bigdecimal-1.2.0-35.el7_6.x86_64                    4/10 
  Verifying  : rubygems-2.0.14.1-35.el7_6.noarch                           5/10 
  Verifying  : rubygem-json-1.7.7-35.el7_6.x86_64                          6/10 
  Verifying  : rubygem-rdoc-4.0.0-35.el7_6.noarch                          7/10 
  Verifying  : rubygem-asciidoctor-1.5.6.1-1.el7.noarch                    8/10 
  Verifying  : rubygem-psych-2.0.0-35.el7_6.x86_64                         9/10 
  Verifying  : rubygem-io-console-0.4.2-35.el7_6.x86_64                   10/10 

Installed:
  rubygem-asciidoctor.noarch 0:1.5.6.1-1.el7                                    

Dependency Installed:
  ruby.x86_64 0:2.0.0.648-35.el7_6                                              
  ruby-irb.noarch 0:2.0.0.648-35.el7_6                                          
  ruby-libs.x86_64 0:2.0.0.648-35.el7_6                                         
  rubygem-bigdecimal.x86_64 0:1.2.0-35.el7_6                                    
  rubygem-io-console.x86_64 0:0.4.2-35.el7_6                                    
  rubygem-json.x86_64 0:1.7.7-35.el7_6                                          
  rubygem-psych.x86_64 0:2.0.0-35.el7_6                                         
  rubygem-rdoc.noarch 0:4.0.0-35.el7_6                                          
  rubygems.noarch 0:2.0.14.1-35.el7_6                                           

Complete!

Mit nachfolgendem Befehl kann überprüft werden, welche Inhalte mit den Paket rubygem-asciidoctor installiert wurden.

# rpm -qil rubygem-asciidoctor
Name        : rubygem-asciidoctor
Version     : 1.5.6.1
Release     : 1.el7
Architecture: noarch
Install Date: Wed 04 Sep 2019 08:53:23 AM CEST
Group       : Development/Languages
Size        : 844362
License     : MIT
Signature   : RSA/SHA256, Thu 24 Aug 2017 01:54:38 PM CEST, Key ID 6a2faea2352c64e5
Source RPM  : rubygem-asciidoctor-1.5.6.1-1.el7.src.rpm
Build Date  : Thu 24 Aug 2017 01:52:36 PM CEST
Build Host  : buildvm-18.phx2.fedoraproject.org
Relocations : (not relocatable)
Packager    : Fedora Project
Vendor      : Fedora Project
URL         : https://github.com/asciidoctor/asciidoctor
Summary     : A fast, open source AsciiDoc implementation in Ruby
Description :
A fast, open source text processor and publishing toolchain, written in Ruby,
for transforming AsciiDoc markup into HTML 5, DocBook 4.5, DocBook 5.0 and
custom output formats. The transformation from AsciiDoc to custom output
formats is performed by running the nodes in the parsed document tree through a
collection of templates written in a template language supported by Tilt.
/usr/bin/asciidoctor
/usr/bin/asciidoctor-safe
/usr/share/gems/gems/asciidoctor-1.5.6.1
/usr/share/gems/gems/asciidoctor-1.5.6.1/CHANGELOG.adoc
/usr/share/gems/gems/asciidoctor-1.5.6.1/CONTRIBUTING.adoc
/usr/share/gems/gems/asciidoctor-1.5.6.1/LICENSE.adoc
/usr/share/gems/gems/asciidoctor-1.5.6.1/README-fr.adoc
/usr/share/gems/gems/asciidoctor-1.5.6.1/README-jp.adoc
/usr/share/gems/gems/asciidoctor-1.5.6.1/README-zh_CN.adoc
/usr/share/gems/gems/asciidoctor-1.5.6.1/README.adoc
/usr/share/gems/gems/asciidoctor-1.5.6.1/bin
/usr/share/gems/gems/asciidoctor-1.5.6.1/bin/asciidoctor
/usr/share/gems/gems/asciidoctor-1.5.6.1/bin/asciidoctor-safe
/usr/share/gems/gems/asciidoctor-1.5.6.1/data
/usr/share/gems/gems/asciidoctor-1.5.6.1/data/locale
/usr/share/gems/gems/asciidoctor-1.5.6.1/data/locale/attributes.adoc
/usr/share/gems/gems/asciidoctor-1.5.6.1/data/stylesheets
/usr/share/gems/gems/asciidoctor-1.5.6.1/data/stylesheets/asciidoctor-default.css
/usr/share/gems/gems/asciidoctor-1.5.6.1/data/stylesheets/coderay-asciidoctor.css
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/abstract_block.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/abstract_node.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/attribute_list.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/block.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/callouts.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli/invoker.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/cli/options.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/converter
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/converter.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/converter/base.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/converter/composite.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/converter/docbook45.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/converter/docbook5.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/converter/factory.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/converter/html5.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/converter/manpage.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/converter/template.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/hash
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/hash/key.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/io
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/io/binread.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/io/write.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/string
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/string/chr.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/string/limit_bytesize.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/symbol
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/symbol/empty.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/1.8.7/symbol/length.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/nil_or_empty.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/regexp
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/regexp/is_match.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/string
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/core_ext/string/limit_bytesize.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/document.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/extensions.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/helpers.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/inline.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/list.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/parser.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/path_resolver.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/reader.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/section.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/stylesheets.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/substitutors.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/table.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/timings.rb
/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/version.rb
/usr/share/gems/specifications/asciidoctor-1.5.6.1.gemspec
/usr/share/man/man1/asciidoctor.1.gz

Zum Abschluss kann mit nachfolgendem Befehl überprüft werden, ob ein Aufruf möglich ist und Asciidoctor nutzbar ist:

# asciidoctor -V
Asciidoctor 1.5.6.1 [http://asciidoctor.org]
Runtime Environment (ruby 2.0.0p648 (2015-12-16) [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

Der Asciidoctor-Prozessor wird typischerweise verwendet, um ein AsciiDoc-Dokument zu analysieren und in eine Vielzahl von Formaten wie HTML, DocBook, PDF oder man-Pages zu konvertieren. Nachfolgend soll beschrieben werden, wie das Ausgabeformat festgelegt werden kann.

Der Prozessor erzeugt das Ausgabeformat mit Hilfe eines Konverters. Jeder Konverter wird auf den Namen eines Backends abgebildet. Es muss das Backend angegeben werden - und damit wird der Konverter bestimmt - was über die Kommandozeilenoption

-b (--backend)

oder die Backend-API-Option durchgeführt wird.

HINWEIS - Wenn kein Backend angegeben ist, verwendet der Prozessor den Konverter für das Standard-Backend (html5).

Asciidoctor stellt mehrere eingebaute Konverter zur Verfügung, die auf die folgenden Backend-Namen abgebildet werden:

Asciidoctor besitzt auch mehrere Add-On-Konverter, die durch Hinzufügen der entsprechenden Bibliothek zum Laufzeitpfad mit nachfolgendem Befehl (z.B. -r asciidoctor-pdf) angeschlossen werden können. Diese Konverter werden auf die folgenden Backend-Namen abgebildet:

Es gibt auch Konverter für HTML5-Präsentationssysteme wie reveal.js und Bespoke.js. Diese Konverter befinden sich noch in der Entwicklung und werden dokumentiert, sobald neue Versionen verfügbar sind.

Das Standardausgabeformat von Asciidoctor ist HTML.

Nachfolgend soll ein Beispieldokument erstellt, verarbeiten und es mit dem html5-Konverter von Asciidoctor konvertiert werden.

1. Erstellen einer AsciiDoc-Datei wie die unten stehende
2. Speichern der Datei als /tmp/mysample.adoc

= My First Experience with the Dangers of Documentation

In my world, we don't have to worry about mutant, script-injecting warlocks.
No.
We have something far worse.
We're plagued by Wolpertingers.

== Origins

You may not be familiar with these https://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.

Um /tmp/mysample.adoc von der Kommandozeile aus in HTML zu konvertieren, sind nachfolgende Schritte notwendig:

1. Öffnen einer Konsole (shell)
2. Wechseln in das Verzeichnis, das das mysample.adoc-Dokument enthält.

   # cd /tmp

3. Aufruf des Asciidoctor-Prozessor mit dem Befehl asciidoctor, gefolgt von dem Namen des Dokuments, das konvertiert werden soll:

   # asciidoctor mysample.adoc

HINWEIS - Der Standardkonverter von Asciidoctor ist html5, so dass es nicht notwendig ist, die Option -b im Befehl anzugeben.

HINWEIS - Es werden keine Meldungen auf der Konsole ausgegeben.

Mit nachfolgendem Befehl kann nun überprüft werden, ob die Konvertierung statt gefunden hat und eine HTML-Datei erzeugt wurde:

# ls -l mysample.*
-rw-r--r-- 1 root root   382 Sep  4 10:32 mysample.adoc
-rw-r--r-- 1 root root 31350 Sep  4 10:33 mysample.html

HINWEIS - Asciidoctor leitet den Namen des Ausgabedokuments aus dem Namen des Eingabedokuments ab.

Zur Überprüfung ob kann nun die soeben neu erstellte HTML-Datei - /tmp/mysample.html in einem Webbrowser geöffnet werden. Das HTML-Dokument sollte wie das unterstehende Bild aussehen.

Der Text, die Titel und der Link des Dokuments werden mit dem Standard-Asciidoctor-Stylesheet formatiert, das in die HTML-Ausgabe eingebettet ist. Als Ergebnis kann /tmp/mysample.html auf jedem Computer gespeichert werden und es wird genauso aussehen.

Asciidoctor verwendet CSS für das Styling von HTML-Dokumenten und JavaScript für die Generierung von Dokumentenattributen wie Inhaltsverzeichnis und Fußnoten.

Es wird mit einem Stylesheet namens

• asciidoctor.css erstellt und mitgeliefert.

Wenn ein Dokument mit dem html5-Backend generiert wird, wird das Stylesheet asciidoctor.css standardmäßig in die HTML-Ausgabe eingebettet (wenn der abgesicherte Modus kleiner als SECURE ist).

HINWEIS - Es gibt auch die Möglichkeit, auf das Stylesheet zu verlinken, anstatt es einzubetten.

Dies ist das obligatorische Verhalten, wenn der abgesicherte Modus SECURE ist. Wenn der Stylesheet verlinkt wird, kann der abgesicherte Modus gesenkt werden (Safe ist der empfohlene Wert).

Damit das Dokument mit dem Stylesheet verknüpft ist, kann das Attribut linkcss im Kopf des Dokuments gesetzte werden.

Nachfolgender Befehl verlinkt auf das Stylesheet bei der Erstellung des HTML-Dokuments, anstatt es einzubetten:

# asciidoctor -a linkcss mysample.adoc

HINWEIS - Wenn das Verzeichnis nun betrachtet wird, sollten neben mysample.adoc und mysample.html auch die Datei asciidoctor.css zu sehen sein, was mit nachfolgendem Befehl überprüft werden kann:

# ls -l mysample.* *.css
-rw-r--r-- 1 root root 29984 Sep  4 11:08 asciidoctor.css
-rw-r--r-- 1 root root   382 Sep  4 10:32 mysample.adoc
-rw-r--r-- 1 root root  1397 Sep  4 11:08 mysample.html

Das linkcss-Attribut kopiert asciidoctor.css automatisch in das Ausgabeverzeichnis. Zusätzlich kann /mtp/mysample.html im Webrowser eingesehen werden und

<link rel="stylesheet" href="./asciidoctor.css">

ist nun im <head> Tag zu sehen, anstelle des eingebetteten CSS-Stylesheet.

Wenn es nicht gewünscht sein sollte, dass CSS_Stylesheets auf die HTML-Ausgabe des Dokuments angewendet werden sollen, deaktiviert nachfolgender Befehl bei der Erstellung das Stylesheet-Attribut komplett.

# asciidoctor -a stylesheet! mysample.adoc

HINWEIS - Wenn das Verzeichnis nun betrachtet wird, sollten neben mysample.adoc und mysample.html keine Datei namens asciidoctor.css zu sehen sein, was mit nachfolgendem Befehl überprüft werden kann:

# ls -l mysample.* *.css
ls: cannot access *.css: No such file or directory
-rw-r--r-- 1 root root  382 Sep  4 10:32 mysample.adoc
-rw-r--r-- 1 root root 1158 Sep  4 11:16 mysample.html

Eine der Stärken von Asciidoctor ist die Einfachheit, mit der der Standard-Stylesheet gegen ein alternatives Asciidoctor-Thema austauschen werden kann oder ein eigenes benutzerdefiniertes Stylesheet verwenden werden kann.

Eine der spezielleren Anwendungen von AsciiDoc ist es, als Abkürzung für die Generierung von man-Pages (kurz für Manual Pages) für Unix und Unix-ähnliche Betriebssysteme zu dienen.

Eine man-Page ist in der Roff-Satzsprache kodiert. Durch die Einhaltung einer bestimmten Struktur in der man-Page Quellcode-Datei kann der man-Befehl den Inhalt analysieren und ein formatiertes Dokument in einem textuellen (Befehlszeilen-)Seitendarstellung präsentieren. Die man-Page-Seiten bieten einen einheitlichen Hilfskatalog für alle Befehle im System. Eine vollständige Beschreibung finden Sie auf der Roff-Manualseite (oder über die Befehle man roff oder man 7 man ein).

Asciidoctor kann roff-formatierte man-Pages erzeugen, wenn die Struktur des AsciiDoc-Dokuments mit der Manpage-Doctype-Struktur übereinstimmt.

Um eine roff-formatierte man-Page aus einer AsciiDoc-Datei zu erzeugen, die den Manpage-Doctype deklariert, ist nachfolgender Befehl auszuführen:

# asciidoctor -b manpage source.adoc

HINWEIS - Der man-Page Converter setzt den Namen der Ausgabedatei auf progname.1, wobei progname der Name des Befehls und 1 die Volumennummer ist, wie durch den Doctitle des Quelldokuments definiert wurde.

Bei der Konvertierung in das man-Page-Format werden die Titel aller Level-0- und Level-1-Abschnitte von Asciidoctor in Großbuchstaben geschrieben. Dadurch wird die Eingabe von Abschnittsüberschriften in Großbuchstaben erspart. Es macht das Dokument auch auf andere Ausgabeformate portierbar, da dieser Stil nur in der Ausgabe der Manualseite benötigt wird, um den Konventionen zu entsprechen.

ACHTUNG - Wenn Ruby 2.4 oder besser verwenden wird, wird Asciidoctor jeden Buchstaben im Titel, der von der Unicode-Spezifikation als ein Großbuchstabenäquivalent erkannt wird (einschließlich nicht-lateinischer Buchstaben), in Großbuchstaben schreiben. Vor Ruby 2.4 konnte Ruby nur lateinische Buchstaben in Großbuchstaben schreiben.

Asciidoctor kann auch HTML- und PDF-Versionen ähnlich der man-Ausgabe für die Anzeige in anderen Kontexten erzeugen. Um die man-Page stattdessen in HTML zu sehen, kann der Befhl wie folgt ausgeführt werden:

# asciidoctor source.adoc

Nachfolgend eine man-Page Vorlage, die in AsciiDoc für den exemplarischen Befehl test erstellt werden soll:

= test(1)
Vorname Nachname
v1.0.0
:doctype: manpage
:manmanual: TEST
:mansource: TEST
:man-linkstyle: pass:[blue R < >]

== Name

test - description of the command

== Synopsis

*test* [_OPTION_]... _FILE_...

== Options

*-o, --out-file*=_OUT_FILE_::
  Write result to file _OUT_FILE_.

== Exit status

*0*::
  Success.
  Execution was successful.

*1*::
  Failure.
  Execution was NOT successful.

== Resources

*Project web site:* http://www.tachtler.net

== Copying

Copyright (C) 2008 {author}. +
Free use of this software is granted under the terms of the MIT License.

Der man-Page-Doctype hat die folgenden erforderlichen Teile:

Ein man-Page-Dokumentenkopf ist obligatorisch. Die Titelzeile enthält den Namen der Manual-Seite, gefolgt von der manuellen Abschnittsnummer in runden Klammern. Der Titelname sollte keine Leerzeichen enthalten. Die manuelle Abschnittsnummer ist eine einzelne Ziffer, optional gefolgt von einem einzelnen Zeichen.

Der erste Abschnitt der Manual-Seite ist obligatorisch, muss den Titel „NAME“ tragen und einen einzelnen Absatz (in der Regel eine einzige Zeile) enthalten, der aus einer Liste von einem oder mehreren Komma getrennten Befehlsnamen besteht, die durch ein Strichzeichen vom Befehlszweck getrennt sind. Der Bindestrich muss auf beiden Seiten mindestens ein Leerzeichen aufweisen.

Der zweite Abschnitt der man-Page ist obligatorisch und muss den Titel „SYNOPSIS“ tragen.

Die nachfolgenden Abschnitte sind optional, aber typische Abschnitte sind

• „SEE ALSO“
• „BUGS REPORTS“
• „AUTHORS“
• „COPYRIGHT“

Es gibt mehrere eingebaute Dokumentattribute, die nur man-Pages betreffen. Wenn sie verwendet werden, müssen sie im Dokumenten Kopf (Document Header) gesetzt werden.

Ein vollständiges Beispiel befindet sich unter AsciiDoc-Quelltext der man-Page Asciidoctor. Die man-Page für Asciidoctor wird mit dem in Asciidoctor integrierten man-Page Konverter erzeugt.