Drop the angled brackets. Write (Ascii)Docs with pleasure!

mojavelinux.github.com/decks/asciidoc-with-pleasure

http://mojavelinux.github.com/decks/asciidoc-with-pleasure

Writing in DocBook is just… inhumane

I found I was spending more time fixing syntax errors than I was writing the documentation.


Stuart Rackham
Notes

DocBook is a complex language, the markup is difficult to read and even more difficult to write directly — I found I was spending more time typing markup tags, consulting reference manuals and fixing syntax errors, than I was writing the documentation.

Just let me write, dammit!

                                           +yyyyyyyyyyyyyyyyyyyyyyo-
                                          `yNNNNNNNNNNNNNNNNNNNNNMMMNo`
                                        -:::::::::::::::::::::::`.:dMMN-
                                      oNMMMMMMMMMMMMMMMMMMMMMMMMMd/ sMMN`
                                     oMMm+:::::::::::::::::::::+MMM: NMM-
                                     sMMs                       MMMo NMM-
                                     sMMs                       MMMo NMM-
                                     sMMs `mMMMMMMMMMMMMMMMMMd  MMMo NMM-
                                     sMMs  `++++++++++++++++/`  MMMo NMM-
                                     sMMs `mMMMMMMMMMMMMMMMMMd  MMMo NMM-
                                     sMMs  .+++++++++++++++++`  MMMo NMM-
                                     sMMs `dmmmmmmmmmmmmmmmmmh  MMMo NMM-
                                     sMMs  ://///////////////.  MMMo NMM-
                                     sMMs `hmmmmmmmmmmmmmmmmms  MMMo NMM-
                                     sMMs  //////////////////-  MMMo NMM-
                                     sMMs `yddddddddddddddddds  MMMo NMM-
                                     sMMs  /yyyyyyyyyyyyyyyys/  MMMo NMM-
                                     sMMs `ohhhhhhhhhhhhhhhhho  MMMo NMM-
                                     sMMs                       MMMo dMN.
                                     sMMs                       MMMo  .`
                                     :MMMdhhhhhhhhhhhhhhhhhhhhhdMMN.
                                      .shmmmmmmmmmmmmmmmmmmmmmmmho.




       .o.                           o8o   o8o  oooooooooo.
      .888.                          `"'   `"'  `888'   `Y8b
     .8"888.      .oooo.o  .ooooo.  oooo  oooo   888      888  .ooooo.   .ooooo.
    .8' `888.    d88(  "8 d88' `"Y8 `888  `888   888      888 d88' `88b d88' `"Y8
   .88ooo8888.   `"Y88b.  888        888   888   888      888 888   888 888
  .8'     `888.  o.  )88b 888   .o8  888   888   888     d88' 888   888 888   .o8
 o88o     o8888o 8""888P' `Y8bod8P' o888o o888o o888bood8P'   `Y8bod8P' `Y8bod8P'

A lightweight, yet powerful text-based markup language and document generator


that’s got it all!    

Notes

AsciiDoc was created by Stuart Rackham, hailing from New Zealand Comparable to Markdown, yet far more complete

Notes

Mild punctuation mild.png

export-icon.png

Who’s onboard?

asciidoc-github.png
AsciiDoc support on GitHub

I’m amazed by AsciiDoc :-) It handles a lot of use cases well, and some other cases are still possible at least.


Anders Nawroth, Neo4j

Lightweight markup siblings

Side by side

Compare AsciiDoc…

Document Title
==============
John Doe <john.doe@example.com>
v1.0, 2012-12-01

This is the optional preamble (an untitled section body). Useful for
writing simple sectionless documents consisting only of a preamble.

NOTE: The abstract, preface, appendix, bibliography, glossary and
index section titles are significant ('specialsections').

== First section

Document sections start at level 1 and can nest up to four levels deep.

* Item 1
* Item 2

…to DocBook

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book lang="en">
    <bookinfo>
        <title>Document Title</title>
        <date>2012-12-01</date>
        <author>
            <firstname>John</firstname>
            <surname>Doe</surname>
            <email>john.doe@example.com</email>
        </author>
        <authorinitials>JD</authorinitials>
        <revhistory>
            <revision>
                <revnumber>1.0</revnumber>
                <date>2012-12-01</date>
                <authorinitials>JD</authorinitials>
            </revision>
        </revhistory>
    </bookinfo>
    <preface>
        ...

…to DocBook (con’t)

        ...
        <simpara>
            This is the optional preamble (an untitled section body).
            Useful for writing simple sectionless documents consisting
            only of a preamble.
        </simpara>
        <note>
            <simpara>
                The abstract, preface, appendix, bibliography, glossary
                and index section titles are significant
                (<emphasis>specialsections</emphasis>).
            </simpara>
        </note>
    </preface>
    <chapter id="_first_section">
        <title>First section</title>
        <simpara>
            Document sections start at level 1 and can nest up to
            four levels deep.
        </simpara>
        <itemizedlist>
            <listitem>
                <simpara>Item 1</simpara>
                ...

…to DocBook (and going)

                ...
            </listitem>
            <listitem>
                <simpara>Item 2</simpara>
            </listitem>
        </itemizedlist>
    </chapter>
</book>
Notes

DocBook becomes a distraction to the task of writing the documentation. Your focus is on the tags and how to manage them rather than the text.

I use Markdown to write my documention.


Most developers on github

…to Markdown

# Document Title

This is the optional preamble (an untitled section body). Useful for
writing simple sectionless documents consisting only of a preamble.

> **Note**
>
> The abstract, preface, appendix, bibliography, glossary and index
> section titles are significant (*specialsections*).

## First section

Document sections start at level 1 and can nest up to four levels deep.

* Item 1
* Item 2

Hmm, can’t really cover all the requirements :(

Markdown : 1st-grader ::
Asciidoc : PhD student

AsciiDoc markup tour

Heading variants: Underline

Title (Level 0)
===============

Level 1
-------

Level 2
~~~~~~~

Level 3
^^^^^^^

Level 4
+++++++

Heading variants: Symmetric

= Title (Level 0) =

== Level 1 ==

=== Level 2 ===

==== Level 3 ====

===== Level 4 =====

Heading variants: Prefix

= Title (Level 0)

== Level 1

=== Level 2

==== Level 3

===== Level 4
Notes

I prefer using prefix, except underline for the title

Text formatting

This paragraph contains 'emphasized', *strong*, `monospaced` text.

This paragraph has fancy `single-quoted' and ``double-quoted'' text.

To get [underline]#underlined# text, you can use a inline role (i.e., class) named underline.

x*x can be written as x^2 and you swim in H~2~O.

We break at the end of this line +
to keep the text from overflowing.

.Look at me!
This paragraph has it's own title. footnote:[A title can help a paragraph stand out.]

Blocks

Literal block
....
Renders as pre-formatted, monospaced text
....
Source block
.Optional caption
----
public interface Document {}
----

Blocks (con’t)

Sidebar block
.Optional caption
****
Stuff in here is set off with a different background.
****
Quote block
[quote, Linus Torvalds, comp.os.minix (1991)]
____
I'm doing a (free) operating system (just a hobby, won't be big and professional like gnu) for 386(486) AT clones.
____
Notes

Only 4 consecutive delimeters are required. I recommend using the minimum rather than formatting them to match the line length.

Lists

Unordered list
* Linux
** Fedora
** Ubuntu
* Mac OSX
* Windoze
Another unordered list
.Vendors
- Asus
- Lenovo
- Samsung

Lists (con’t)

Ordered list
. Wake up
. Go to work
. Write docs!
.. Open your text editor
.. Experience the joy of text
. Eat cake
Definition list
AsciiDoc:: advanced text-based document generation
DocBook:: keeps a programmer busy for hours

Links & images

Links
http://asciidoc.org

http://asciidoc.org[AsciiDoc project]

[[anchor]]Deep link

<<anchor,Go to deep link>>
Inline image
image:images/logo.png[Logo]
Block image
image::images/logo.png[Logo]
Block image with caption
.Screenshot
image::images/screenshot.png[Screenshot]

Includes

Include file
include::footer.adoc[]

Admonitions

One-liner
NOTE: Just a quick note that you should pay attention.
Two-liner
[NOTE]
Perhaps this one is to your liking?
More expressive
[IMPORTANT]
====
Get the full rich web experience!

* HTML 5, CSS 3 & JavaScript
====
Plain example
.Optional caption
====
Examples are good. They show you how to use stuff.
====

Source highlighting

Tables

Basic table
.Optional caption
[options="header"]
|====================
|Col 1 |Col 2  |Col 3
|1     |Item 1 |a
|2     |Item 2 |b
|3     |Item 3 |c
|====================
Table from CSV
.Contacts
[grid="rows",format="csv"]
[options="header",cols="^,<,<,<,>"]
|==========================
ID,First,Last,Address,Phone
1,Allen,Dan,Denver,3035551212
2,Doe,John,"Washington, D.C.",2025551212
|==========================

Example showcase

Notes

vim, gedit syntax highlighting support

Tip
view docbook with yelp

Drop the <>, but not the semantics

Custom markup

Definition
[macros]
(?su)(?<!\S)[\\]?(?P<name>filename):(?P<target>[\w/])=

[filename-inlinemacro]
ifdef::basebackend-docbook[]
<filename{target@.*/$: class="directory"}>{target}</filename>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<tt>{target}</tt>
endif::basebackend-html[]
Usage
My home directory is filename:/home/dallen/.
Notes

Also acronym-macro.conf

Getting started

Drawbacks

† Work is underway on a Ruby port

Final recap

It's all about the text

Frag the XML and just write docs!

Enjoy writing docs (again)!