Introduction

AsciiDoc is a formatting convention that provides consistency to notes and documents composed in ASCII plain text. Though a sufficient reason to always use AsciiDoc, consistency comes with additional benefits. Primarily, AsciiDoc formatted plain text can be automatically converted into sensible HTML and other back end formats more suitable for publication.

The specific tool to do this conversion is the /usr/bin/asciidoc program found in the Ubuntu/Debian/RPM package called asciidoc Simply call it like this.

$ asciidoc mynotes.txt

And asciidoc will create a file called mynotes.html. That’s all you really need to know to put it to use.

Notes that I keep in a text file will eventually be reviewed, but notes I scribbled onto a pad of graph paper almost always wind up being ephemera.

John Carmack,@ID_AA_Carmack, Jun 3, 2022

Resources

These notes cover many of the most important elements of the format convention (especially to me). However, definitely check out the official full AsciiDoc Documentation.

It seems like the main author of the original Python Asciidoc has stopped working on the project and sources of authoritative information are more nebulous. It seems like some of this is now living here.

http://asciidoc.org/

For a good explanation of why Asciidoc is preferable to that other system, this page from Asciidoctor makes a good case.

Asciidoc Live is a web site that allows you to play with Asciidoc formatting in a very helpful way.

Asciidoctor seems to be very enthusiastic about Asciidoc. Here is the Official Asciidoctor Asciidoc Language Reference. Too bad it’s not easily readable in a simple format like, say, HTML. Wonder where we could find tools that could help us get such a thing. Ahem.

Installation

It used to be that you’d just use your package manager and install asciidoc.

I did find this Github repo that you can clone.

git clone https://github.com/asciidoc/asciidoc

That will contain the python executable.

You need to create an asciidoc.conf file somehow. Maybe you need to run the asciidoc/install-sh script. The install text file suggests that make is the proper way. More experiments will be necessary.

Miscellaneous

A backend is supposed to be specified on the command line with -b (but in normal environments I skip that and it’s been known to work):

  • docbook

  • xhtml11

  • html4

  • linuxdoc

Different document types can be specified:

  • article (the default)

  • book (allows level 0 heading)

  • man page

Use -d to specify document type on command line.

Also note the existence of Pandoc which, in theory, can convert Asciidoc into pretty much anything.

There is also Markdown which seems to have a similar mission to Asciidoc, but I find it more complicated and limiting. (Updated link?) Still, the idea of imparting a consistent structure to your text documents is a good one no matter how you choose to do it.

And there is Sphinx-doc which seems to use reStructuredText as it’s markup syntax. The reST markup seems like a similar but different version of Asciidoc. Either would probably do, but from what I know I prefer the Asciidoc sensibilities when they differ.

And reStructuredText, though I don’t quite understand it’s point yet.

Vim Syntax Highlighting Asciidoc Source Text

When editing text documents with Asciidoc features, you can compound your advantage by using Vim’s syntax highlighting. In some systems installing the package automatically sets this up for you. In other systems, it doesn’t (Centos 6).

Here’s a discussion about how to implement Vim syntax highlighting for Asciidoc documents. It discusses the many options for specifying these files:

  • asciidoc-8.6.3/vim/syntax/asciidoc.vim

  • asciidoc-8.6.3/vim/ftdetect/asciidoc_filetype.vim

Text modification

Output markup AsciiDoc source

  • Emphasized or I usually use underscores.

  • Strong

  • Monospaced (Backticks, like bash)

  • Also Monospaced (Causes problems with a certain object oriented C variant.)

  • “Quoted”

  • Assume Worthless Security. A better passthrough solution that actually works.

  • Assume Weak Stability. The same as before but a bit easier to execute sometimes.

  • This won't work. Actually it does work!

  • Superscripts: x2

  • Subscripts: H2O

  • 🐧

  • *

  • What if you need two hyphens—not an m-dash? -- 

- 'Emphasized' or I _usually_ use underscores.
- *Strong*
- `Monospaced` (Backticks, like bash)
- ++Also Monospaced++ (Causes problems with a certain object oriented
  C variant.)
- ``Quoted''
- pass:[<b>A</b>ssume <b>W</b>orthless <b>S</b>ecurity]. A better passthrough
solution that actually works.
- +++<b>A</b>ssume <b>W</b>eak <b>S</b>tability+++. The same as
before
but a bit easier to execute sometimes.
- +++<strike>This won't work.</strike>+++ Actually it does work!
- Superscripts: x^2^
- Subscripts:   H~2~O
- pass:[&#128039;]
- *
- What if you need two hyphens--not an m-dash? &#45;&#45;

Plus Plus

If writing about C++ , it might be good to disable the ++ by including the following at the top of your document (just after author’s name).

:quotes.++:

Although the previous paragraph rendered into HTML fine, this kind of thing will confuse syntax highlighting. As far as the syntax highlighting in Vim is concerned, everything between the "C" and the word "by" is mono spaced regardless of any measures taking to suppress that behavior. This problem usually arises when C++ is followed by a character other than a space.

Output markup AsciiDoc source

Syntax highlighting is good with this but rendering fails: I tend to write C like this where C is followed by a space.

Syntax highlighting is not ok with this and rendering fails: When using C, followed by some other character, I write C like this.

Syntax highlighting is ok with this and rendering fails: When using C+, followed by some other character, I write C\+ like this.

Syntax highlighting is ok with this, rendering seems fine, and the ASCII is ok: When using C++, followed by some other character, I write C++ like this.

Syntax highlighting is ok with this, rendering seems fine, and the ASCII is rubbish: When using C++, followed by some other character, I write C++ like this.

 
Syntax highlighting is good with this but rendering fails:
I tend to write C++ like this where C++ is followed by a space.

Syntax highlighting is not ok with this and rendering fails:
When using C++, followed by some other character, I write C++ like this.

Syntax highlighting is ok with this and rendering fails:
When using C\++, followed by some other character, I write C\++ like this.

Syntax highlighting is ok with this, rendering seems fine, and the ASCII is ok:
When using pass:[C++], followed by some other character, I write pass:[C++] like this.

Syntax highlighting is ok with this, rendering seems fine, and the ASCII is rubbish:
When using C&#43;&#43;, followed by some other character, I write C&#43;&#43; like this.

Titles

Output markup AsciiDoc source

Titles Are Done Like This

That was Level 1. Level 0 is for book type documents and the topmost title.

Titles Can Be Done Like This Too

A way to get one line titles. At first I was hesitant, but now I pretty much use this style for all titles.

Subtitles Have Levels

This is level 1.

Level 2 On One Line

Here is the normal Level Two title done on a single line.

Level 2 And Beyond

This is level 2.

My Normal Level 3 Title

This is how I normally make titles.

Title 3

A test of the other way to make a Title 3.

Title 4

A test of Title 4.

This Is Also Level 4

A way to get one line subtitles.

Symmetrical Title Markup

If you want your titles to have a nice symmetrical look, that is ok too.

 
Titles Are Done Like This
-------------------------
That was Level 1. Level 0 is for book type documents and the topmost title.

= Titles Can Be Done Like This Too
A way to get one line titles. At first I was hesitant, but now I
pretty much use this style for all titles.

Subtitles Have Levels
---------------------
This is level 1.

== Level 2 On One Line
Here is the normal Level Two title done on a single line.

Level 2 And Beyond
~~~~~~~~~~~~~~~~~~
This is level 2.

=== My Normal Level 3 Title
This is how I normally make titles.

Title 3
^^^^^^^
A test of the other way to make a Title 3.

Title 4
+++++++
A test of Title 4.

===== This Is Also Level 4
A way to get one line subtitles.

==== Symmetrical Title Markup ====
If you want your titles to have a nice symmetrical look, that is ok
too.

Literal Paragraphs

Output markup AsciiDoc source

If a paragraph is indented:

Then it's a literal paragraph and it's rendered
with monospace. Seems like this kind of thing
must be preceded and followed by blank lines.

Another way to achieve this is to put the text in dots.

Then it's a literal paragraph and it's rendered
with monospace. And, no indenting required!
 
If a paragraph is indented:

    Then it's a literal paragraph and it's rendered
    with monospace. Seems like this kind of thing
    must be preceded and followed by blank lines.

Another way to achieve this is to put the text in dots.
........................................
Then it's a literal paragraph and it's rendered
with monospace. And, no indenting required!
........................................

Listing Block

Output markup AsciiDoc source

This style of paragraph is good for code fragments.

Whitespace
   is
      preserved
         here
            in monospace.
The background may be highlighted in a box.
 
This style of paragraph is good for code fragments.
----------------------------------------
Whitespace
   is
      preserved
         here
            in monospace.
The background may be highlighted in a box.
----------------------------------------

Sidebars

Output markup AsciiDoc source
Sidebars

Stuff in here is set off with a different background than even the Listing block. The title will be the title of the sidebar. This is for interruptive material that needs to be inserted somewhere.

 
.Sidebars
****************************************
Stuff in here is set off with a different background than even the
Listing block. The title will be the title of the sidebar. This is for
interruptive material that needs to be inserted somewhere.
****************************************

////////////////////////////////////////
Comment blocks are ignored by the processor. This won't show up in any
rendered output, but of course it's in the text. This might be a good
place to say "Created for ASCIIDoc Processing".
////////////////////////////////////////

Pass Through Block

Output markup AsciiDoc source

Pass Normal HTML

Pass through block. Render dependent.

YouTube Video Embedding

New Asciidoctor seems to support an understanding of YouTube.

video::WC9IxOunoUk[youtube,width=224,height=126]

The classic pass through technique.

SVG

New Asciidoctor seems to support an understanding of SVG.

Here’s a reliable pass through method.

 
*Pass Normal HTML*

++++++++++++++++++++++++++++++++++++++++
<s>Pass through block. Render dependent.</s>
++++++++++++++++++++++++++++++++++++++++

*YouTube Video Embedding*

New Asciidoctor
https://docs.asciidoctor.org/asciidoc/latest/macros/audio-and-video/[seems
to support] an understanding of YouTube.

video::WC9IxOunoUk[youtube,width=224,height=126]

The classic pass through technique.

++++++++++++++++++++++++++++++++++++++++
<iframe width="224" height="126" src="https://www.youtube.com/embed/WC9IxOunoUk"
frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
++++++++++++++++++++++++++++++++++++++++

*SVG*

New Asciidoctor
https://docs.asciidoctor.org/asciidoc/latest/macros/image-svg/[seems
to support] an understanding of SVG.

Here's a reliable pass through method.

++++++++++++++++++++++++++++++++++++++++
<svg height="90px" width="180px" viewBox="-100 -100 400 200"
xmlns="http://www.w3.org/2000/svg" version="1.1">
<a href="http://xed.ch">
<path d="M-100,100 L-68,100 C-55,72 -35,50 -6,38 L0,60 L6,38
C38,50 55,72 68,100 L100,100 L100,68 C72,55 50,33 38,6 L60,0
L38,-6 C50,-33 72,-55 100,-68 L100,-100 L 68,-100 C55,-72 33,-50
6,-38 L0,-60 L-6,-38 C-33,-50 -55,-72 -68,-100 L-100,-100 L-100,-68
C-72,-55 -50,-33 -38,-6 L-60,0 L-38,6 C-50,33 -73,55 -100,68 z M-20,20
L-8,0 L-20,-20 L0,-8 L20,-20 L8,0 L20,20 L0,8 L-20,20 z"
fill="#325d6f" stroke="#003a54" stroke-width="3"></path>
<path d=" M110,0 L88,6 C100,33 122,55 150,68 L150,26 L128,20 L150,14
L150,-14 L128,-20 L150,-26 L150,-68 C122,-55 100,-33 88,-6 z"
fill="#325d6f" stroke="#003a54" stroke-width="3"></path>
<path d=" M200,-26 L200,-100 C247,-84 284,-47 300,-0
C253,16 216,53 200,100 L200,26 L178,20
L200,14 L200,-14 L178,-20 z M226,18 C245,-2
245,-2 267,-14 C255,-33 242,-46
226,-56 z" fill="#325d6f" stroke="#003a54" stroke-width="3"></path>
</a>
</svg>
++++++++++++++++++++++++++++++++++++++++

Quote

Output markup AsciiDoc source

Now this is a quote block with the attribution done nicely. Use [verse] to preserve paragraph formatting.

ASCIIDoc Notes (2006)
— Chris X Edwards 
[quote, Chris X Edwards, ASCIIDoc Notes (2006)]
___________________________________________________________
Now this is a quote block with the attribution done nicely.
Use [verse] to preserve paragraph formatting.
___________________________________________________________

Lists

Output markup AsciiDoc source

There are many ways to do lists.

  • First, make sure that there’s space around the list items.

  • One can use the star.

  • And the dash (-) is fine too.

That was a list. Others include:

  1. Just using a dot (.) gives the correct number and a dot.

    1. Nested lists…

    2. …are fine.

  2. Using a dot dot (..) gives the correct lower case letter.

  3. Using number dot (1.) gives that number and dot.

  4. Using number letter (a.) gives that letter and dot.

  5. List items can be continued past formatting blocks with + alone on a line. 

There are many ways to do lists.

* First, make sure that there's space around the list items.
* One can use the star.
* And the dash (-) is fine too.

That was a list. Others include:

. Just using a dot (.) gives the correct number and a dot.
  .. Nested lists...
  .. ...are fine.
. Using a dot dot (..) gives the correct lower case letter.
. Using number dot (1.) gives that number and dot.
. Using number letter (a.) gives that letter and dot.
. List items can be continued past formatting blocks with + alone on a line.

Definition Lists

Output markup AsciiDoc source
term

This is the definition.

term2

Term2’s definition. 

term::
  This is the definition.
term2::
  Term2's definition.

URLs

Output markup AsciiDoc source 
* http://www.xed.ch[Chris' homepage]
* mailto:xed@pookmail.com[Email Chris]
* [[here]]There is something HERE.
* <<here,Link to Here>>
* link:filename#id[caption]

Images

Output markup AsciiDoc source
Normal Image

xed.ch

Linked

xed.ch

Hot Linking

xed.ch

Block Image

alt_text 

Normal Image::
  image:./Images/logo.png[alt="xed.ch"]
Linked::
  image:./Images/logo.png[alt="xed.ch",link="www.xed.ch"]
Hot Linking::
  image:http://xed.ch/h/Images/logo.png[alt="xed.ch"]
Block Image::
  image::./Images/logo.png[alt_text]

Tables

Tables can be easy and they can be hard. Here’s easy:

A table example….

Table 1. An Example Table (Title Optional)
Pet Cost Cost to feed/day

Average

$226.76

$7.10

cat

$26.50

$1.25

mouse

$.55

$.10

snake

$230.00

$.55

wolf

$650

$26.50

Another table example….

Table 2. CSV data, 15% each column

root

0

0

/root

/bin/bash

bin

1

1

/bin

/sbin/nologin

daemon

2

2

/sbin

/sbin/nologin

adm

3

4

/var/adm

/sbin/nologin

lp

4

7

/var/spool/lpd

/sbin/nologin

sync

5

0

/sbin

/bin/sync

shutdown

6

0

/sbin

/sbin/shutdown
Table 3. Example of a Table For Explaining Weird Syntax
Command Does This Function

sed

Tells you what someone has been saying.

awk

Flightless shore bird.

grep

An assembly of people from Appalachia.

If you need something harder, detailed table information can be found here.

Syntax Highlighting

First this must be prepared. You need to make a directory:

$ sudo mkdir -p /etc/asciidoc/filters/

There are two filters, code and source. The first has only C and Python and Ruby. The source one has many more options. It’s actually a separate GNU project. You have to install source-highlight. Then copy the configuration file for using it:

$ sudo cp /usr/share/asciidoc/filters/source/source-highlight-filter.conf \
/etc/asciidoc/filters/

For CentOS type systems, you should also do something like this:

sudo yum install source-highlight

Then to use it you add this kind of thing immediately above the ------- which starts your code block.

  • [source,c]

  • [source,cc]

  • [source,html]

  • [source,makefile]

  • [source,postscript]

  • [source,py]

  • [source,sh]

  • [source,sql]

Some examples:

A C++ Sample With The Code Filter
// Sample.cc
// A sample C++ file highlighted with code filter.
// This filter is limited to only C, Python, and Ruby.
#include "tricks.h"
using namespace std;

int alpha(int &p, Framework &f) {
    the->setcolor("red");
    float x1= ( f.p2x(p+1) ) - ( f.dC() / 2 );
    switch ( p % 4 ) { // Just some random code.
       case 0:
           the->line(x1, yb, x2, y0);
           break;
       case 1:
           the->line(x1, y0, x2, yb);
           break;
    } // end of switch block
    the->setwidth(0);
    return 0; // Don't expect this to compile.
} //end fun alpha
A C++ Sample With The source Filter
// Sample.cc
// A sample C++ file highlighted with source filter.
// This filter does a lot more languages.
#include "tricks.h"
using namespace std;

int alpha(int &p, Framework &f) {
    the->setcolor("red");
    float x1= ( f.p2x(p+1) ) - ( f.dC() / 2 );
    switch ( p % 4 ) { // Just some random code.
       case 0:
           the->line(x1, yb, x2, y0);
           break;
       case 1:
           the->line(x1, y0, x2, yb);
           break;
    } // end of switch block
    the->setwidth(0);
    return 0; // Don't expect this to compile.
} //end fun alpha

Themes

The default Asciidoc look is ok. It’s got a lot of blue titles and other features and is pretty distinctive. It’s pretty easy to tell a fellow Asciidoc user. I feel like not a lot was done to make changing this easy because fundamentally, Asciidoc is absurdly flexible and, no doubt, the author just imagined you doing whatever you want and getting what you want. Now, how exactly to do that is not so obvious. Here is one way I found to get the customized look I wanted. There is a concept of "themes". If you look under /etc/asciidoc/themes, you’ll see a couple of them, volnitsky and flask. You could make your theme here, but a more personal location would be ~/.asciidoc/themes. I started by copying the flask directory to the local themes directory and then I just started playing around with the CSS contained in it. To have your documents use the theme, you can say :theme: myfuntheme at the top of the document under the title. Or you can specify it with the --theme=myfuntheme option.

I found it pretty annoying that I couldn’t specify the exact path of the theme directory. What I did was I made the theme in my project so it would be saved and tracked with my project, but then I put a link to it in the ~/.asciidoc/themes directory. Problems solved.


[This is the footnote.]