ASCIIDoc Notes

asciidoc

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

docbook
xhtml11
html4 (my favorite)
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.

Text modification:

Emphasized
Strong
Monospaced (Backticks, like bash)
“Quoted”
Unquoted (Let’s formatting pass unevaluated).
Superscripts: x²
Subscripts: H₂O

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.

Subtitles Have Levels

This is level 1.

Level 2 And Beyond

This is level 2.

Title 3

A test of Title 3.

Title 4

A test of Title 4.

This Is Also Level 4

A way to get one line subtitles.

Literal Paragraphs

If a paragraph is indented: Then it’s a literal paragraph and it’s rendered with monospace. 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

This style of paragraph is good for code fragments.

Whitespace
   is
      preserved
         here
            in monospace.
The background may be highlighted in a box.

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.

Pass Through Block

~~Pass through block. Render dependent.~~

Quote

Now this is a quote block with the attribution done nicely.

ASCIIDoc Notes (2006)
— Chris X Edwards

Lists

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.
1. Nested lists…
2. …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

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

URLs

Chris' homepage
Email Chris
There is something HERE.
Link to Here
caption

Images

Normal Image
Linked
Block Image

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

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/

Then to use it you do stuff like this:

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

[This is the footnote.]