= The Dangerous & _Thrilling_ Documentation Chronicles: Based on True Events
Kismet Caméléon; Lazarus het_Draeke
v1.0, 2014-01-01
:description: This story chronicles the inexplicable hazards and vicious beasts a \
team must conquer and vanquish on their journey to discovering the true power of \
Open Source.
:organization: Company Name
:doctype: book
:preface-title: Preface
// Settings:
:experimental:
:reproducible:
:icons: font
:listing-caption: Listing
:sectnums:
:toc:
:toclevels: 3
:xrefstyle: short
ifdef::backend-pdf[]
:pdf-theme: chronicles
:pdf-themesdir: {docdir}
:title-logo-image: image:sample-banner.svg[pdfwidth=4.25in,align=center]
:source-highlighter: rouge
//:rouge-style: github
endif::[]
// URIs:
:uri-devoxx: https://devoxx.be
:uri-devoxx-top-talks: https://www.youtube.com/watch?v=1OpAgZvYXLQ&list=PLRsbF2sD7JVq7fv1GZGORShSUIae1ZAPy&index=1
:uri-stbernardusabt12: http://www.sintbernardus.be/stbernardusabt12.php?l=en
:uri-wolpertinger: http://en.wikipedia.org/wiki/Wolpertinger

[%notitle]
--
[abstract]
{description}
--

== It's a City Under Siege

This journey begins one late Monday afternoon at {uri-devoxx}[((Devoxx))].
(((Conference,Devoxx)))
Our team needs coffee, _desperately_, but none of us dare open the theater doors...

During the {uri-devoxx-top-talks}[opening university session], a script-happy warlock inadvertently released a legion of Wolpertingers!
To leave now would mean *code dismemberment and certain death*.

Behold -> the horror!

.Wolpertinger, stuffed
image::wolpertinger.jpg[Wolpertinger,pdfwidth=50%,link={uri-wolpertinger},float=left,role=thumb]

(((Wolpertinger)))
(((Ravenous Beast,Wolpertinger)))
You may not be familiar with these {uri-wolpertinger}[ravenous beasts].
Trust us, they'll eat your shorts and suck loops from your code.
In light of this danger, we've searched high and wide for the security crew's defensive operations manual.
We can't find it and the DefOps{empty}footnote:defops[DefOps is a portmanteau of "`defensive`" and "`operations`".] werewolves haven't returned from their rendezvous at Bier Central.
They've either eaten each other or fallen victim to the Wolpertingers roaming the streets of ((Antwerp)).
Quick, hit kbd:[Ctrl,Alt,Backspace] or select menu:File[Quit] and let's bail out of here!

WARNING: Working with DefOps{empty}footnote:defops[] werewolves leads to howling and trying to train aggressive regular expressions with Pavlovian reinforcement.

_Weak light from the hallway trickled across the theater, chased by a distant scream._

=== Rendezvous Point

Come on, [[bier-central,Bier Central]]_Bier Central_, of course!
Did you have to ask?
If you beat me there, order me a {uri-stbernardusabt12}[St. Bernardus Abt 12].
Here's some €.

[#ravages]
== The Ravages of Writing

Crystalline XML tags relentlessly bombarded the theater.

.XML tags
[,xml]
----
<author id="1">
  <personname>
    <firstname>Lazarus</firstname>
    <surname>het Draeke</surname>
  </personname>
</author>
----

Despite the assault, we continued our pursuit to draft a DefOps{empty}footnote:defops[] plan.

.DefOps Plan
====
Click btn:[Download Zip] to download the defensive operation plan bundle.

OMG!
Somebody please save us now!
I want my mum -- and an extra-large double macchiato, please.
====

Unfortunaly, Lazarus and I had both come to the conclusion that we weren't going to get out of this without corrupted hardrives if we didn't locate caffeine within the next few hours.

=== A Recipe for Potion That Will Ensure You Win the Hearts of Developers

This potion for a sample document contains the following ingredients, which are listed in a very random, chaotically nested order.

.Ingredients for Potion that Demystifies Documents
* all the headings
** syntax highlighted source code
*** non-syntax highlighted source code or just a listing block
* quote block
** verse block
*** table with some cell formatting
**** sequential paragraphs
***** admonition blocks, but use them sparingly
*** bullet list with nesting
** numbered list with nesting
** definition list
*** sidebar
* example block
** block image (no inline images)
*** inline formatting in a paragraph
**** two fresh Burdockian leaves
***** They must be harvested by the light of the teal moons.

Are you square?

[square]
* one
* two
* three

What is there to do?

* [x] Done
* [ ] Next
* Who's counting?

==== Searching for Burdockian

.Steps for finding and preparing Burdockian leaves
. Locate dusty botany
.. Sneeze
... Sneeze some more
. Find section on Burdockian
.. Review its characteristics
... Take a picture of the diagram of its leaves
.... Don't rip out the picture like a troglodyte
..... Don't do it, I'm watching you
. Put on your hiking boots
. Freeze your butt off on the side of a mountain at midnight

Let's skip a few steps and start counting from 10.

[start=10]
. arabic (10)
.. loweralpha (a)
... lowerroman (i)
... lowerroman (ii)
... lowerroman (iii)
... lowerroman (iv)
.... upperalpha (A)
. arabic (11)

It's time for a top 5 list, made using the `reversed` option on an ordered list!

[%reversed]
. Stone Imperial Russian Stout
. Pliny the Elder
. Chimay Grande Réserve (Blue)
. St. Bernardus Abt 12
. Westvleteren 12 (XII)

How about a list with some terms?

* Fruits

Apple::
The round fruit of a tree of the rose family, which typically has thin red or green skin and crisp flesh.
Yes, I said _flesh_.

Pear::
A yellowish- or brownish-green edible fruit that is typically narrow at the stalk and wider toward the base, with sweet, slightly gritty flesh.
More flesh.
Mmmmm.

* Vegetables

Carrot::
An orange-colored root eaten as a vegetable.
Beware, it's a favorite of the Wolpertinger.

===== Are You Still Here?

.Move, move, move!
[CAUTION]
====
The Wolpertingers can smell your procrastination.
It's not their fault you can't find your boots.
====

====== Sigh...

TIP: Your boots are in your closet.

== Dawn on the Plateau

Lazarus was hanging from the bottom limb of a Burdockian tree, licking the bark.

[quote,Mark Tobey]
On pavements and the bark of trees I have found whole worlds.

"`If there are whole worlds on that bark, he just swallowed them,`" Kizmet replied.

[verse,The documentation attorneys]
____
No bark was harmed in the making of this potion.
    We're not so sure about a couple ants though.

        Nor those worlds...

     Crap, I smell an injunction.
____

We'd retrieved the leaves, but we'd obviously lost our minds in the process.

[verse]
Roses are +++<span style="color: #FF0000">red</span>+++.
Violets are +++<span style="color: #0000FF">blue</span>+++__-ish__.

== Words Seasoned with Power

To _tame_ the [.wild]#wild# wolpertingers, we needed to build a *charm*.
But **ul**timate victory could only be won if we divined the *_true name_* of the __war__lock.

"`What kind of charm?`" Lazarus asked. "`An odoriferous one or a mineral one?`"
Kizmet shrugged. "`The note from Olaf's desk says '`wormwood and licorice,`' but these could be normal groceries for werewolves.`"

"`Well the H~2~O written on the security whiteboard could be part of a shopping list, but I don't think the local bodega also sells e = mc^2^,`" Lazarus replied.

"`Wait!`" Indigo plucked a small vial from her desk's top drawer and held it toward us.
The vial's label read '```e = mc^2^ *_the scent of science_* _smells like a genius_```'.

=== Can I Get Some `Code`?

[%hardbreaks]
Sure.
Have a listing block.

----
This is an example of a listing block.
The content inside is rendered as <pre> text.
----

But I'm not giving you any highlighting shazam just yet.

.What is a listing block?
****
Like literal blocks, the content in listing blocks is displayed exactly as you entered it.
Listing block content is rendered as `<pre>` text.

The `listing` style is applied to an element, such as a paragraph, by setting the `listing` attribute on that element.
****

Let's get our #((highlighting))# on!

<<<

Install Prawn:

 $ gem install prawn

Then create your first PDF document in Ruby!

.Generates a basic PDF document using Prawn
[,ruby]
----
require 'prawn' # <1>

Prawn::Document.generate 'output.pdf' do # <3>
  text 'Hello, World!' # <2>
end
----
<1> Imports Prawn library
<2> Adds text “Hello, World!” to first page
<3> Writes PDF to [file]_output.pdf_ after executing all statements

How about some source code that styles code? So meta!

[,css]
----
code {
  padding: 2px 4px;
  font-size: 90%;
  font-weight: normal;
  color: #c7254e;
  white-space: nowrap !important;
  background-color: #f9f2f4;
  border-radius: 4px;
}
----

Where could we go without some Java(TM)?
Naturally, some autosizing is necessary.

[%autofit,java]
----
package org.javaee7.cdi.events;

import javax.annotation.PostConstruct;
import javax.enterprise.context.SessionScoped;
import javax.enterprise.event.Observes;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import javax.ws.rs.*;

/**
 * This session-scoped bean receives greeting strings from the event bus
 * and provides access to the collection of these greetings via a REST API.
 *
 * @author The Duke
 * @since 1.0
 */
@SessionScoped
public class GreetingReceiver implements EventReceiver, Serializable {

    private List<String> greetings;

    @PostConstruct
    void init() {
        this.greetings = new ArrayList<String>();
    }

    void receive(@Observes String greet) {
        this.greetings.add(greet);
    }

    @GET
    @Produces("application/json")
    public List<String> listAll(@QueryParam("start") Integer start, @QueryParam("max") Integer max) {
        int numGreetings = this.greetings.size();

        if (numGreetings == 0 || max == 0) {
            return Collections.<String>emptyList();
        }

        if (start == null) {
            start = 0;
        }

        if (max == null) {
            max = numGreetings;
        }

        return this.greetings.subList(start, Math.min(max + start, numGreetings));
    }

}
----

We already showed you an XML example in <<ravages>>, a language we often rant about over beers at <<bier-central>>.

I'll trade you a little table for some of that bark.

[cols=4,frame=ends,grid=rows]
|===
|Column 1 |Column 2 |Column 3 |Column 4

^m|Prefix `{vbar}` with `{caret}` to center content horizontally within the cell.
.>|Prefix `{vbar}` with a `.` and `>` to align content to the bottom of the cell.
^.^|Prefix `{vbar}` with a `^`, `.`, and `^` to place content in the middle of the cell.
>|Prefix `{vbar}` with `>` to align content to the right horizontally within the cell.

4+^e|This content spans all four columns (`4{plus}`) and is centered horizontally (`{caret}`) within the cell.
|===

Wait.
What?
Where is this story going?

`<span>`:: an html tag that makes me crazy

align:: something I never get going in the right direction.
Also has to do with my poor verbal communication skills

float::
style::
don't make me laugh

Does anyone have the time?

Tg lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborumj.

== Keeping It Together

On this page we have nested "`keep together`" logic.
The combined block will be shifted to the next page if there isn't room available on this one.

[verse]
First,
we
need
to
waste
several
lines
using
a
verse
to
push
the
next
block
to
its
breaking
point.

[NOTE%unbreakable]
.What happens if there is both a field and a method with the same name?
====
Back to the previous example, suppose that we have both a field and a method with the same name, as in:

.Java class with a field and method that share the same name
[,java]
----
public class Foo {
  public String bar;

  public String bar() {
    return bar;
  }
}
----

*Golo resolves methods first, fields last.*
Hence, the following Golo code will resolve the `bar()` method, not the `bar` field:

.Golo picks the method over the field with the same name
[,golo]
----
let foo = Foo()

foo: bar("baz") # <1>

println(foo: bar()) # <2>
----
<1> Writes the field
<2> Calls the `bar()` method
====

<<<

Here's a preview of how each heading level is rendered.

[discrete]
= Heading 1 (Level 0)

filler content

[discrete]
== Heading 2 (Level 1)

filler content

[discrete]
=== Heading 3 (Level 2)

filler content

[discrete]
==== Heading 4 (Level 3)

filler content

[discrete]
===== Heading 5 (Level 4)

filler content

[discrete]
====== Heading 6 (Level 5)

filler content

---

--
Here's some content inside an open block.
--

[appendix]
== Credits

.Brought to you with icon:heart[set=fas,role=love] by OpenDevise
[%header%footer,cols="2,2s,^4",grid=rows,frame=ends,width=75%,caption=]
|===
|Name |Title |Alias

|Sarah White
|President
|http://twitter.com/carbonfray[@carbonfray]

|Dan Allen
|Vice President
|http://twitter.com/mojavelinux[@mojavelinux]

3+^.e|Powered by Open Source
|===

[index]
== Index