intro page

an approximate* history of documentation formats

[* and mostly inaccurate]


in the beginning…there was ASCII text

[and it was good]


then in the 1980s* other countries got electricity

[* that’s an estimate]

take that

Americans learned there are other languages and invented Perl as revenge

Perl begat regexen

Perl gave us regular expressions* so we could find out what cartoon swearing means


in English dots only go on the letter i*, but suddenly people started dotting round vowels


document headers were introduced to warn people of the coming barbarism*

caffienated documentation

documentation got hyper and we all got nesting instinct

<html><body><h1><font color=#ffffff><strong><em><a name="purple_watermelon">unicorns</a></em></strong></font></h1></body></html>

the human is the computer

we built hand-crafted* documentation snowflakes


We can fix this!!!

the birth of markup

simplified formatting pretending to be other formatting

when simple isn’t simple

markup begat templates*

this is not the Highlander you remember

there can never be only one*

snowflakes galore



not up

support for Maryland

exec table

MarkDown requires tools* to create a Table of Contents

welcome to the promised Doc

AsciiDoc to the rescue

ASCII bunny

< What's up AsciiDoc? >
   \   \
        \ /\
        ( )
      .( o ).

What is asciidoc?

Some output formats

Where is it supported?

What about MarkDown?

Key use cases for me

Document Conversion

Getting Graphic


simple with complex possibilities


= document title ( level 0 )
== title level 1
=== title level 2
== title level 1
=== title level 2
==== title level 3


text with a blank line before and after

another paragraph

and another

text with a blank line before and after

another paragraph

and another

unordered lists

* Dr. Seuss
** thing1
** thing2
* cars
** VW thing
* Addams Family
** thing

ordered list

. one
. two
. three
.. three and a third
.. three and two thirds
. four
  1. one
  2. two
  3. three
    1. three and a third
    2. three and two thirds
  4. four


* [*] check
* [] cash
* [] credit


source code

Use four dashes, ----, alone on lines to start and end the block

function find_ssh_agent() {
        if [ ! -S "$SSH_AUTH_SOCK" ] ; then
                # Find the your first SSH socket file if you don't already have one
                local pS=$( ls /tmp/ssh-*/agent.* | head -1 )
                # Verify potential_SAS is a socket, has correct uid and gid and also the dir has correct uid and gid
                if [ -S "$pS" -a -O "$pS" -a -G "$pS" -a -O "${pS%/*}" -a -G "${pS%/*}" ] ; then
                        export SSH_AUTH_SOCK="$pS"

# Find an SSH_AUTH_SOCK, call ssh. Use '\ssh' to get ssh w/o the helper fx()
alias ssh="find_ssh_agent; echo $SSH_AUTH_SOCK; ssh-add -l; ssh"


Not all AsciiDoc features are supported by all backends