Wednesday, November 26, 2014

Awesome Asciidoctor: Disable Last Updated Text in Footer

When we transform our Asciidoc source files to HTML Asciidoctor will print the date and time the document was last updated in the footer. If we want to disable the Last updated text we disable the document attribute last-update-label.

In the following example Asciidoc file we disable the Last update label in the footer:


= Change footer

To disable the _Last updated_ text
in the footer we disable the document
attribute `last-update-label`.

// Disable last updated text.

When we transform this to HTML we get the following output:

Written with Asciidoctor 1.5.1.

Tuesday, November 25, 2014

Grails Goodness: Create New Application without Wrapper

Since the latest Grails versions a Grails wrapper is automatically created when we execute the create-app command. If we don't want the wrapper to be created we can use the command argument --skip-wrapper. If later we changed our mind and want the Grails wrapper we can simply run the wrapper command from our Grails application directory.

Let's run the create-app command with the --skip-wrapper argument. If we check the contents of the created directory we see that the wrapper files are not created:

$ grails create-app --skip-wrapper sample 
$ cd sample
$ ls
application.properties lib   src   web-app
grails-app  scripts   test

Written with Grails 2.4.4.

Awesome Asciidoctor: Using Document Fragments

Normally all Asciidoc files are processed and transformed to output files by Asciidoctor. But if we start the file name with an underscore (_) the file is not transformed to an output file. This is very useful, because we can define some Asciidoc document fragments and include them in other Asciidoc files, but in the output directory the document fragment is not generated.

Let's create two Asciidoc files. One is _attrs.adoc which is a document fragment file that is used in sample.doc:

// File: _attrs.adoc
:blogger_url: http://mrhaki.blogspot.com
:blogger_tag: Aweseome Asciidoctor
:author: mrhaki
// File: sample.adoc

== Sample

Asciidoctor handles files starting
with an underscore (`_`) differently. The file is
not processed, but can be used in other Asciidoc

More {blogger_url}[blog posts] about
{blogger_tag} available written by {author}.

From the command line we can invoke the asciidoctor command. We also check the directory and see there is only the file sample.html:

$ asciidoctor sample.adoc
$ ls
_attrs.adoc sample.adoc sample.html

The following screenshot shows how the sample.html looks like in a web browser:

Written with Asciidoctor 1.5.1.

Monday, November 24, 2014

Gradle Goodness: Using and Working with Gradle Version

To get the current Gradle version we can use the gradleVersion property of the Gradle object. This returns a string value we can use for displaying the values. If we want to compare Gradle versions we can use the GradleVersion object. With this class we can get the current version, but we can also compare Gradle versions. This can be useful in our build scripts if we have functionality based on a Gradle version.

In the following build file we first have a task that uses the gradleVersion of Gradle. Then inside the task we use the static method current of the GradleVersion class. We get an GradleVersion instance and we display different properties from this instance. In the task compareGradleVersion we create a GradleVersion instance with the static version method. We compare multiple GradleVersion objects and have different functionality based on the Gradle version.

task printGradleVersion << {
    // Get current Gradle version as object.
    final GradleVersion gradleVersion = GradleVersion.current()

    // Print different properties.
    println "Your Gradle version is ${gradleVersion.version}"
    println "Base version: ${gradleVersion.baseVersion}"
    println "Build time  : ${gradleVersion.buildTime}"
    println "Build number: ${gradleVersion.buildNumber}"
    println "Commit id   : ${gradleVersion.revision}"
    println "Next major  : ${gradleVersion.nextMajor}"
    println "Snapshot?   : ${gradleVersion.snapshot}"

task compareGradleVersion << {
    // Current Gradle version.
    final GradleVersion gradleVersion = GradleVersion.current()

    // Gradle version 2.1 as GradleVersion object.
    final GradleVersion gradle2_1 = GradleVersion.version('2.1')

    // Compare versions.
    if (gradleVersion > gradle2_1) {
        println "Your Gradle version is newer than 2.1"
    } else if (gradleVersion == gradle2_1) {
        println "Your Gradle version is 2.1"
    } else {
        println "Your Gradle version is older than 2.1"

When we run the tasks we get the following output:

$ gradle -q printGradleVersion
Gradle version is 2.2

Your Gradle version is 2.2
Base version: Gradle 2.2
Build time  : 2014-11-10 13:31:44 UTC
Build number: none
Commit id   : aab8521f1fd9a3484cac18123a72bcfdeb7006ec
Next major  : Gradle 3.0
Snapshot?   : false
$ gradle -q compareGradleVersion
Your Gradle version is newer than 2.1

Thanks to John Engelman who showed me this class on a pull request for the Gradle Grails plugin.

Written with Gradle 2.2.

Gradle Goodness: Using CopySpec with Tasks

To define a Copy task we specify the files we want to copy and to which directory. This definition is a CopySpec instance. It contains the rules that defines what we want to copy. The archive tasks Jar, Zip and Tar also use a CopySpec instance.

When we create a task of type Copy we get a task object that implements the CopySpec interface. We can use all the methods from this interface to extend our recipe for copying tasks. In the following build file we first define the task website. We use CopySpec methods to configure the task. Then we define a task deploy of type Sync that also implements the CopySpec interface.

// Create a new task of type Copy.
// The website task is of type Copy
// and this means it implements the
// CopySpec interface. 
task website(type: Copy) {
    into "${buildDir}/website"
    from 'src/webroot'

    into 'resources', {
        from 'src/assets'

// We can use all CopySpec methods
// to add new specifications to 
// the existing specifications.
website.into('resources') {
    from 'src/javascript'

// The copySpec method creates 
// a CopySpec instance
// from the closure.
// The copySpec method is part of the
// Project object.
CopySpec manualSpec = copySpec {
    from('src/manual') {
        include '**/*.html'
// And the with method accepts
// the CopySpec we created.

// Print each file path
// that is copied.
website.eachFile { 
    println it.path

// New task of type Sync.
// The Sync task is also implementing
// the CopySpec interface.
// (Just like archive tasks: Zip, Tar, Jar)
task deploy(type: Sync) {
    destinationDir = file("${buildDir}/production")
    from website

// Use rename method from CopySpec.
deploy.rename { file ->
    if (file == 'index.html') {
    } else {

// And finally the exclude method.
deploy.exclude 'man.html'

When we run the deploy task and look at the files in the build directory we see how our copy specifications are executed:

$ gradle deploy


Total time: 3.643 secs
$ tree build/
├── production
│   ├── main.html
│   └── resources
│       ├── app.js
│       └── site.css
└── website
    ├── index.html
    ├── man.html
    └── resources
        ├── app.js
        └── site.css

4 directories, 7 files

Written with Gradle 2.2.

Thursday, November 20, 2014

Awesome Asciidoctor: Changing the Grid and Frame of Tables

We can change the frames and grid of tables we define in Asciidoctor. We use the frames attribute to change the outside frame of a table. We can choose between topbot for top and bottom, sides for only a frame at the sides of the table, none if we don't want a frame. The default value all create a frame around our table with top, sides and bottom.

To change the inner grid of a table we use the grids table attribute. The default value all displays a grid for columns and rows inside the table. The value cols only displays a grid between columns, value rows display a grid between rows and with value none there will be no grid inside our table.

The following Asciidoc sample shows the definition of four tables with different values for the cols table attribute:

.Table with top and bottom frame (topbot)
| Name | Description

| Asciidoctor
| Awesome way to write documentation


.Table with no frame (none)
| Name | Description

| Asciidoctor
| Awesome way to write documentation


.Table with only sides frame (sides)
| Name | Description

| Asciidoctor
| Awesome way to write documentation


.Table with default frame (all)
| Name | Description

| Asciidoctor
| Awesome way to write documentation


When we generate output using the HTML backend we get the following result:

In the next sample we have four tables with different values for the cols attribute:

.Table with no grid (none)
[grid="none", frame="none"]
| Name | Description

| Asciidoctor
| Awesome way to write documentation


.Table with only columns grid (cols)
[grid="cols", frame="none"]
| Name | Description

| Asciidoctor
| Awesome way to write documentation


.Table with only rows grid (rows)
[grid="rows", frame="none"]
| Name | Description

| Asciidoctor
| Awesome way to write documentation


.Table with default rows and columns grid (all)
[grid="all", frame="none"]
| Name | Description

| Asciidoctor
| Awesome way to write documentation


And we get the following output when we transform this source to HTML:

Written with Asciidoctor 1.5.1.

Monday, November 17, 2014

Gradle Goodness: Check Task Dependencies With a Dry Run

We can run a Gradle build without any of the task actions being executed. This is a so-called dry run of our build. We can use the dry run of a build to see if the task dependencies we have defined or are defined in a plugin are defined properly. Because all tasks and task dependencies are resolved if we use the dry run mode we can see in the output which tasks are executed.

We define a simple build file with three tasks and some task dependencies:

def printTaskNameAction = {
    println "Running ${it.name}"

task first << printTaskNameAction

task second(dependsOn: first) << printTaskNameAction

task third(dependsOn: [first, second]) << printTaskNameAction

To run a Gradle build as a dry run we can use the command line option -m or --dry-run. So let's execute the task third with the dry run command line option:

$ gradle -m third
:first SKIPPED
:second SKIPPED
:third SKIPPED


Total time: 2.242 secs

And we see in the output none of the tasks are really executed, because SKIPPED is shown, but we do see the task names of the tasks that are resolved.

Written with Gradle 2.2.

Wednesday, November 12, 2014

Awesome Asciidoctor: Use Asciidoctor Diagram with Gradle

Since Asciidoctor 1.5.0 we can use extensions when we write AsciiDoc documents. These extensions can be written in Ruby or any JVM language. If we use Gradle and the Asciidoctor Gradle plugin to transform our documents we can use both extensions. Of course an extension written in for example Java or Groovy can be included as a regular dependency in our build configuration. As the extension is on the classpath of the asciidoctor task then it can be used. When the extension is a Ruby extension and available as a Ruby gem we need some more configuration in our build file. To use an Asciidoctor extension written in Ruby in our build we must first make sure that we can download the extension. Then we can configure the asciidoctor task from the Asciidoctor Gradle plugin to use the extension.

Let's start with a sample Asciidoctor document which uses the Asciidoctor Diagram extension. With this extension we can embed diagrams as text in our document and get graphical images as output.

= Sample diagram

:imagesdir: images

== Ditaa

// Sample diagram from Asciidoctor Diagram website
// http://asciidoctor.org/docs/asciidoctor-diagram/

[ditaa, "asciidoctor-diagram-process"]
                   | Asciidoctor |-------+
                   |   diagram   |       |
                   +-------------+       | PNG out
                       ^                 |
                       | ditaa in        |
                       |                 v
 +--------+   +--------+----+    /---------------\
 |        |---+ Asciidoctor +--->|               |
 |  Text  |   +-------------+    |   Beautiful   |
 |Document|   |   !magic!   |    |    Output     |
 |     {d}|   |             |    |               |
 +---+----+   +-------------+    \---------------/
     :                                   ^
     |          Lots of work             |

Next we create our Gradle build file. We must apply the Asciidoctor Gradle plugin so we can transform our AsciiDoc documents. And we must apply the JRuby Gradle plugin so we can download Ruby gems and use them from the asciidoctor task. The JRuby plugin adds a gems dependency configuration, which we can use to define the Ruby gems we need. The task jrubyPrepareGems is also added by the plugin and this task will download the gems and extract them in our project build directory. In our asciidoctor task that is added by the Asciidoctor plugin we use the requires property to specify which gem is needed. We also set the gemPath property to the directory which contains the downloaded and extracted Ruby gems. The following build file defines the plugins and configures the tasks we need so we can use Asciidoctor Diagram:

buildscript {
    repositories {

    dependencies {
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.0'
        classpath 'com.github.jruby-gradle:jruby-gradle-plugin:0.1.5'

// Plugin so we can render AsciiDoc documents.
apply plugin: 'org.asciidoctor.gradle.asciidoctor'
// Plugin so we can use Ruby gems when rendering documents.
apply plugin: 'com.github.jruby-gradle.base'

dependencies {
    // gems dependency configuration is added by
    // jruby-gradle-plugin. Here we define
    // the gems we need in our build.
    gems 'rubygems:asciidoctor-diagram:1.2.0'

asciidoctorj {
    // We can change the AsciidoctorJ 
    // dependency version.
    version = '1.5.1'

asciidoctor {
    // jrubyPrepareGems task is added by the JRuby 
    // plugin and will download Ruby gems we have
    // defined in the gems dependency configuration.
    dependsOn jrubyPrepareGems

    // Asciidoctor task needs the
    // asciidoctor-diagram gem, we installed
    // with the jrubyPrepareGems task and
    // gems dependency configuration.
    requires = ['asciidoctor-diagram']

    // Set path to find gems to directory
    // used by jrubyPrepareGems task.
    gemPath = jrubyPrepareGems.outputDir

defaultTasks 'asciidoctor'

To generate our sample document we only have to run $ gradle from the command line. After the documents are generated we can the result in the build/asciidoc directory of our project. The following screenshot shows the generated HTML:

Written with Asciidoctor 1.5.1 and Gradle 2.1.

Monday, November 10, 2014

Awesome Asciidoctor: Styling Columns and Cells in Tables

In a previous post we learned how to use Asciidoc markup in a table. The a character is just one of many styles we can define in our table. In this blog post we see which style options we have. We can either use the cols attribute to define a style for a whole column or specify per cell the style.

We can use the following styles:

  • e: emphasized
  • a: Asciidoc markup
  • m: monospace
  • h: header style, all column values are styled as header
  • s: strong
  • l: literal, text is shown in monospace font and line breaks are kept
  • d: default
  • v: verse, keeps line breaks

The following Asciidoctor source uses the different styles as cols attribute values:

.Table with column style e,a,m
| Emphasized (e) | Asciidoc (a) | Monospaced (m)

| Asciidoctor
| NOTE: *Awesome* way to write documentation
| It is just code


.Table with column style h,s,l
| Header (h) | Strong (s) | Literal (l)

| Asciidoctor
| Awesome way to write documentation
| It is 
just code


.Table with column style d,v
| Default (d) | Verse (v)

| Asciidoctor
| Awesome way 
to write 


When we transform this into HTML using the Asciidoctor HTML backend we get the following result:

We can also override a column styling per cell. We must put the correct styling character before the pipe symbol (|), so the contents of the cell is styled differently:

Table with row style e,a,m in second row
| Emphasized | Asciidoc | Monospaced

| Asciidoctor
| NOTE: *Awesome* way to write documentation
| It is just code

e| Asciidoctor
a| NOTE: *Awesome* way to write documentation
m| It is just code


And the following HTML is generated when we process this Asciidoctor source:

Written with Asciidoctor 1.5.1.

Awesome Asciidoctor: Using Asciidoc in Tables

When we define a table in Asciidoctor and want to use Asciidoc in a table cell it is not interpreted as Asciidoc by default. The text is literally shown and this might not be what we expect. But we can force Asciidoctor to interpret the cell contents as Asciidoctor.

Let's start with a very simple table. The last cell of the first row contains some Asciidoc markup:

:icons: font

// Simple table where we apply some
// Asciidoc markup in the cell contents.

| Name | Description

| Asciidoctor
| NOTE: *Awesome* way to write documentation


When we transform this Asciidoctor source to HTML we see the following output:

Notice that we don't get a nice image for our NOTE is not shown as image when it used in a table cell.

To change this behavior we can configure the table. We can configure a column to have Asciidoc content that needs to be interpreted or we can configure at cell level we want the contents to be interpreted as Asciidoc. We use the character a in the cols attribute when we define the table. Or we use the character a before the table cell separator (|). In the next sample Asciidoctor file we use both ways to make sure the cell contents is Asciidoc markup that needs to be transformed as well:

:icons: font

// We use the cols attribute for our table
// and specify that the contents of the second
// column is Asciidoc markup.

| Name | Description

| Asciidoctor
| NOTE: *Awesome* way to write documentation


// Or we configure per cell the contents
// is Asciidoc markup.

| Name | Description

| Asciidoctor

// We specify for this specific cell the 
// contents is Asciidoc that needs to 
// be processed.
a| NOTE: *Awesome* way to write documentation


Once we have defined the table we get the following generated HTML:

And this time the cell contents is transformed as well.

Written with Asciidoctor 1.5.1.