intro page

an approximate* history of documentation formats


[* and mostly inaccurate]

itb

in the beginning…there was ASCII text


[and it was good]

a-zA-Z+

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

dots

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

#!/bin/notenglish

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

bzzzzt

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

y+aml*

flip

not up

support for Maryland

README.md

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

Syntax

simple with complex possibilities

Headers

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

paragraphs

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

checklist

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

links

http://AsciiDoc.org/[AsciiDoc]

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"
                fi
        fi
}

# 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"

issues

Not all AsciiDoc features are supported by all backends

Resources