path: root/examples/chronicles.adoc

= The Dangerous and Thrilling Documentation Chronicles
Kismet Chameleon; Lazarus het_Draeke
v1.0, 2014-01-01: The first incarnation of {doctitle}
:description: This story chronicles the inexplicable hazards and vicious beasts a +
team must surmount and vanquish on the journey to finding their open source +
project's true power.
:doctype: book
:title-logo: sample-title-logo.jpg
// Settings:
:compat-mode:
:experimental:
:icons: font
:listing-caption: Listing
:sectnums:
:toc:
:toclevels: 3
ifdef::backend-pdf[]
:pagenums:
:pygments-style: bw
:source-highlighter: pygments
endif::[]
// URIs:
:wolper-uri: http://en.wikipedia.org/wiki/Wolpertinger

[abstract]
{description}

== It's a City Under Siege

This journey begins one late Monday afternoon at http://www.devoxx.be/#/[Devoxx].
Our team needs coffee, _desperately_, but none of us dare open the theater doors...

During the first workshop, 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
[.left.thumb]
image::wolpertinger.jpg[Wolpertinger,width=100%,scaledwidth=55%]

You may not be familiar with these {wolper-uri}[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:[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 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_.
Did you have to ask?
If you beat me there, I'll take a http://www.sintbernardus.be/stbernardusabt12.php?l=en[St. Bernardus Abt 12].

[[ravages]]
== The Ravages of Writing

Crystalline XML tags relentlessly bombarded the theater.

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

Despite the assault, we were still attempting to draft an example of a defensive operation.

.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

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

* 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 (at least one)
*** 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.

Got square?

[square]
* one
* two
* three

==== 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
.. By the way, you can't see toes by the light of the teal moons.

Let's start counting from 10.

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

===== 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 wolpertingers we needed to build a *charm*.
But **u**ltimate 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%;
  color: #c7254e;
  white-space: nowrap !important;
  background-color: #f9f2f4;
  border-radius: 4px;
}
```

Where could we go without some Java?

```java
package org.javaee7.cdi.events;

import javax.enterprise.context.SessionScoped;
import javax.enterprise.event.Observes;
import java.io.Serializable;

/**
 * @author The Duke
 */
@SessionScoped
public class GreetingReceiver implements EventReceiver, Serializable {
    private String greet = "Willkommen";

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

    @Override
    public String getGreet() {
        return greet;
    }
}
```

We already showed you an XML example in <<ravages>>.

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

[cols=3,frame=topbot,grid=rows]
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3

^m|Prefix the +{vbar}+ with +{caret}+ to center content horizontally
.<|Prefix the +{vbar}+ with a +.+ and +<+ to align the content to the top of the cell
>|Prefix the +{vbar}+ with +>+ to align the content to the right horizontally

3+^.^e|This content spans three columns (+3{plus}+) and is centered horizontally (+{caret}+) and vertically (+.{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
it
to
the
breaking
point.

[NOTE]
.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
[source,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
----
let foo = Foo()

# Write the field
foo: bar("baz")

# Calls the bar() method
println(foo: bar())
----
====

<<<

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

<<<

== Credits

.Brought to you by OpenDevise
[%header,cols="1,1s,1",grid=rows,frame=topbot]
|===
|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
|===