Discover the ☯ of ✍ (Ascii)Docs

The Documentation Chronicles

“Tech Writing Against Word.”

The Documentation Chronicles

“Asciidoctor saves the day!”

The Documentation Chronicles

“The adaptive storm.”

 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
 ​
       .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'

Ascii Art?

                                     (
                                       )     (
                                ___...(-------)-....___
                            .-""       )    (          ""-.
                      .-'``'|-._             )         _.-|
                     /  .--.|   `""---...........---""`   |
                    :  :    |                             |
                    :  :    |                             |
                     \  \   |   _  _  __ __ __ __         |
                      `- `- |  / `/ \|_ |_ |_ |_  _|_ _|_ |
                        `-_`|  \_,\_/|  |  |__|__  |   |  |
                            \                             /
                             \                           /
                              \                         /
                               \                       /
                                `-.__             __.-'
                                   ) ""---...---"" (
                                   `"--...___...--"`
         .===================================================================.
         ||                                                                 ||
         ||    __   _    __   __  __   __          __   ..        __        ||
         ||   |__  /_\  |__) |__ |__) /  \ |\  /| |__) |  | |__/ |__ |\ |   ||
         ||   |   /   \ |  \ |   |  \ \__/ | \/ | |    |__| |  \ |__ | \|   ||
         ||                                                                 ||
         ||                                                                 ||
         ||                            ___                                  ||
         ||                          .'   '.                                ||
         ||                         /       \           oOoOo               ||
         ||                        |         |       ,==|||||               ||
         ||                         \       /       _|| |||||               ||
         ||                          '.___.'    _.-'^|| |||||               ||
         ||                        __/_______.-'     '==HHHHH               ||
         ||                   _.-'` /                   """""               ||
         ||                .-'     /   oOoOo                                ||
         ||                `-._   / ,==|||||                                ||
         ||                    '-/._|| |||||                                ||
         ||                     /  ^|| |||||                                ||
         ||                    /    '==HHHHH                                ||
         ||                   /________"""""                                ||
         ||                   `\       `\                                   ||
         ||                     \        `\   /                             ||
         ||                      \         `\/                              ||
         ||                      /                                          ||
         ||                     /                                           ||
         ||                    /_____                                       ||
         ||                                                                 ||
         ||                                                                 ||
         '==================================================================='
                                           +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'

AsciiDoc is…
lightweight markup
publishing toolchain

Mild punctuation mild

“It’s just text, mate”

Text, how sublime ☕

Asciidoctor
A modern, open source implementation of AsciiDoc in Ruby

Ruby gem
asciidoc processor
AsciiDoc processor

Let’s compare AsciiDoc…

= ``The Documentation Chronicles''
Doc Writer <doc@asciidoc.org>
v1.0, 2013-11-11: The first epic adventure.
:toc: left
:icons: font

Chronicles _inexplicable_ hazards, *vicious* beasts & the battle to tame them.

== Writing Without Pain

A paragraph is just a paragraph. No special syntax required.

* Coffee
* Beer
* http://devoxx.be[Devoxx]

WARNING: Beware of untested `code`. The ((Wolpertinger)) will find you!

[source,ruby]
puts 'Beer, the cure for the common <XML>-hell.'

…to Markdown

# "The Documentation Chronicles"

Chronicles _inexplicable_ hazards, **vicious** beasts & the battle to tame them.

## Writing Without Pain

A paragraph is just a paragraph. No special syntax required.

* Coffee
* Beer
* [http://devoxx.be](Devoxx)

<div class="warning">
  <h5>Warning</h5>
  <p>Beware of untested <code>code</code>. The Wolpertinger will find you!</p>
</div>

{% highlight ruby %}
puts 'Beer, the cure for the common <XML>-hell.'
{% endhighlight %}

…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 xmlns="http://docbook.org/ns/docbook" lang="en">
    <bookinfo>
        <title>&#8220;The Documentation Chronicles&#8221;</title>
        <date>2013-11-11</date>
        <author>
            <firstname>Doc</firstname>
            <surname>Writer</surname>
            <email>doc@asciidoc.org</email>
        </author>
        <authorinitials>DW</authorinitials>
        <revhistory>
            <revision>
                <revnumber>1.0</revnumber>
                <date>2013-11-11</date>
                <authorinitials>DW</authorinitials>
                <revremark>
                    The first epic adventure.
                </revremark>
        ...

…to DocBook (and going…)

                ...
            </revision>
        </revhistory>
    </bookinfo>
    <preface>
        <title/>
        <simpara>
          Chronicles <emphasis>inexplicable</emphasis> hazards,
          <emphasis role="strong">vicious</emphasis> beasts &amp;
          the battle to tame them.
        </simpara>
    </preface>
    <chapter id="_writing_without_pain">
        <title>Writing Without Pain</title>
        <simpara>
            A paragraph is just a paragraph. No special syntax required.
        </simpara>
        <itemizedlist>
            <listitem>
                <simpara>Coffee</simpara>
                ...

…to DocBook (at last!)

            ...
            </listitem>
            <listitem>
                <simpara>Beer</simpara>
            </listitem>
            <listitem>
                <simpara><ulink url="http://devoxx.be">Devoxx</ulink></simpara>
            </listitem>
        </itemizedlist>
        <warning>
            <simpara>
                Beware of untested <literal>code</literal>. The
                <indexterm><primary>Wolpertinger</primary></indexterm> will find you!
            </simpara>
        </warning>
        <programlisting language="ruby" linenumbering="unnumbered">
            <![CDATA[puts 'Beer, the cure for the common <XML>-hell.']]>
        </programlisting>
    </chapter>
</book>

Remember the AsciiDoc?

= ``The Documentation Chronicles''
Doc Writer <doc@asciidoc.org>
v1.0, 2013-11-11: The first epic adventure.
:toc: left
:icons: font

Chronicles _inexplicable_ hazards, *vicious* beasts & the battle to tame them.

== Writing Without Pain

A paragraph is just a paragraph. No special syntax required.

* Coffee
* Beer
* http://devoxx.be[Devoxx]

WARNING: Beware of untested `code`. The ((Wolpertinger)) will find you!

[source,ruby]
puts 'Beer, the cure for the common <XML>-hell.'

see the big picture

gedit asciidoc outline
export icon

Extensions

ast
Document AST

AST extensions

Syntax extensions

Polyglot!

Asciidoctor Java

JRuby

The Ruby Programming Language on the JVM

AsciidoctorJ processor
AsciidoctorJ
AsciidoctorJ usage
AsciidoctorJ build plugins

Any application that can be written in JavaScript will eventually be written in JavaScript.


Atwood's law

Asciidoctor.js

Opal
​
A Ruby to JavaScript cross compiler

Opal
asciidoctorjs compile
asciidoctor.js compilation
github sample
AsciiDoc rendering on GitHub
docgist sample
DocGist
chrome sample
Asciidoctor.js Browser Extension
asciidoctor websockets
Asciidoctor + WebSockets

Unicode compliant++

Notes

Don’t let the "Ascii" in AsciiDoc fool you. AsciiDoc and Asciidoctor have full unicode support.

The Unicode Standard is the universal character-encoding scheme for written characters and text.

Symbol party!

asciidoctor styles
Design Legibility & Aesthetics
[[zen-of-writing]]
= Discover the '☯' of ✍ **[subtle]##(##Ascii[subtle]##)##Doc**s
Dan Allen <http://github.com/mojavelinux[@mojavelinux]>
v2.1, Dec 4, 2013
:hashtag: #asciidoctor #rwx
:copyright: CC BY-SA 2.0
:website: http://asciidoctor.org
:dzslides-aspect: 16-9
:math:
:icons: font
include::attributes.conf[]

[.topic.intro]
== The Documentation Chronicles

``Tech Writing Against Word.''


== !

video::editing-word.ogv[]


[.topic.intro]
== The Documentation Chronicles

``Asciidoctor saves the day!''


== !

video::editing-asciidoc.ogv[]

Drop the </>
not the semantics

“It’s just text, mate”

Experience writing zen!

http://asciidoctor.org