TomEE Reference card: thanks Asciidoctor

Reference cards are “page(s)” listing in a single place key points and things to know of a product/language/…

To create them you can use the technology you want and i think a lot of them were created using Word, LaTeX etc…

However today generating it in HTML is a kind of must have since it is the easier way to share it but having it in PDF is still important since a RefCard should be available in offline mode too (to keep the original spirit).

Being able to split the content from the layout is a key point of languages like LaTeX, Markdown, Docbook…It is important for a reference card to be able to generate them in multiple formats.

I wanted to start to think to a reference card for TomEE and wondered what would be a good choice.

After having spoken a bit with Dan Allen i discovered Neo4j ref card: http://www.neo4j.org/resources/cypher

It is written in Asciidoc (using the python version) and generating thanks to some custom scripts (bash ones).

Asciidoc seems a good choice because the “wiki” like syntax is as powerful as docbook without being as verbose.

However my main point was to get something portable (windows without cygwin ;)) and easy enough to be updatable.

So basically i started to migrate the Neo4j solution to Asciidoctor (the ruby version of asciidoc converter).

Since Maven is probably still the most well known build tool and easier one for any Java guy i used asciidoctor-maven-plugin as a starting point (Note: i needed to patch it since some issues were introduced in last release).

After some work i handled to get the first TomEE Reference Card version: http://tomee.apache.org/refcard/refcard.html – better with 4 columns, you can use the zoon of your browser to get it normally.

How did i do it?

The whole generator project is available here: http://svn.apache.org/repos/asf/tomee/site/trunk/generators/tomee-refcard/

The main magic is in the pom:

<plugin>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-maven-plugin</artifactId>
  <version>0.1.4-SNAPSHOT</version>
  <configuration>
    <sourceDocumentName>src/slides/refcard.asciidoc</sourceDocumentName>
    <outputDirectory>${slides.output}</outputDirectory>

     <synchronizations>
      <synchronization>
        <source>${slides.input}/css</source>
        <target>${slides.output}/css</target>
      </synchronization>
      <synchronization>
        <source>${slides.input}/js</source>
        <target>${slides.output}/js</target>
      </synchronization>
      <synchronization>
        <source>${slides.input}/images</source>
        <target>${slides.output}/images</target>
      </synchronization>
      </synchronizations>
 
     <title>TomEE RefCard</title>
     <home>refcard</home>

     <attributes>
      <description>RefCard</description>
      <keywords>refcard</keywords>
      <author>RefCard</author>
      <email>users@refcard</email>
      <revdate>${maven.build.timestamp}</revdate>
      <revnumber>${project.version}</revnumber>
      <highlightjsdir>js</highlightjsdir>
      <highlightjs-theme>github</highlightjs-theme>
    </attributes>

    <backend>html5</backend>
    <compact>true</compact>
    <headerFooter>true</headerFooter>
    <sourceHighlighter>highlightjs</sourceHighlighter>

    <templateDir>${slides.input}/backend</templateDir>
    <templateEngine />
  </configuration>
</plugin>

The synchronizations block is just here to copy over the generated folder the needed resources (js, css, …). Then the other important configuration is the templateDir one pointing in the maven project to a folder “backend”. It is simply the templates used to convert asciidoc to html.

This folder is the following one: http://svn.apache.org/repos/asf/tomee/site/trunk/generators/tomee-refcard/src/slides/backend/

Then the layout is simply some div blocks. Each part is in a div block containing all columns of the part. The id of the part is its title then each column get some particular class like:

<div class="col c2-1 c3-1 c4-1 c5-1 c6-1">

Basically cX-Y means “put this block in column Y when there are X columns” (depends the size of the screen).

The only drawback ATM is this information is in the asciidoc (you can have a look to http://svn.apache.org/repos/asf/tomee/site/trunk/generators/tomee-refcard/src/slides/asciidoc/overview.asciidoc for a sample). It could be done automatically but then you don’t control anymore the layout so it can be “nice for eyes” but it can not match anymore the target of the writer.

As a conclusion asciidoctor was a good choice making the content generation easy and the layout handling “as usual” (js/css/…). The good point is its wiki syntax is easy enough to write doc and really more powerful than Markdown. Now it can be used for RefCards, docs (html, docbook/pdf…) and slides (thanks to deckjs for instance https://github.com/rmannibucau/asciidoctor-deckjs-template).

The maven plugin is really great too (when patched but hopefully a 0.1.3.1 version will soon be out) and the asciidoctor:http goal is awesome when writing things (auto re-render the document + make it available through a small http server).

Advertisement