With Asciidoctor we can use images in our documents with the image directive.
When the document is converted each image gets a caption.
By default the caption label is Figure followed a number for the position of the image in the document.
So the first image has a caption Figure 1..
If we add a block title (text prefixed with a .) to the image then that text is used in the caption as well.
We can customize the caption label, figure counter, caption text or disable the figure caption using a combination of document and image attributes.
We have the following Asciidoctor markup.
We include several images and customize the figure caption settings.
To change the caption label (Figure) we set a different value for the document attribute figure-caption.
In our example we use the value Logo. Any captions following this definition will have the label Logo.
Continue reading →
Asciidoctor has several captions and labels that can be overridden with document attributes.
We need to define a document attribute and assign a new value to override a default caption or label.
We can use UTF-8 characters as the value.
The following list shows captions and labels we can override:
:appendix-caption::caution-caption::example-caption::figure-caption::important-caption::last-update-label::manname-title::note-caption::table-caption::tip-caption::toc-title::untitled-label::version-label::warning-caption:
Continue reading →
Interesting links for week 42 2016:
Continue reading →
When we use the include directive to include another document we can must make sure the included document fits the levels of our main document.
For example the included document shouldn't have level 0 headings if the main document already contains a level 0 heading.
We can change the level offset in the main document before including another document.
This will change the heading levels for the included document so all heading rules are okay.
To change the level offset we use the document attribute leveloffset.
It is best to use a relative value, so if the included document also contains included document the output will still be okay and the heading rules still apply.
Alternatively we can use the leveloffset attribute for the include directive.
In the following sample document we include other files with a level 0 heading:
Continue reading →
Asciidoctor has built-in support for a couple of source syntax highlighting libraries like Coderay, Pygments, highlight.js and prettify.
In this post we learn how to use the Javascript library Prism to do the syntax highlighting for our source blocks.
Because Prism is a Javascript library we must remember this only works for the HTML backend of Asciidoctor.
In the following markup we have two source code listings in Java and Groovy:
Continue reading →
In Asciidoctor we can create a document attribute as a counter attribute.
The attribute is automatically incremented each time we use it in our markup.
We can choose to use numbers or characters.
Only latin characters from 'a' to 'z' or 'A' to 'Z' are allowed.
By default the counter will start at 1, but we can define another start value when we use the counter attribute for the first time.
To define a counter attribute we must prefix the attribute name with counter:.
Each time we use this syntax with the counter: prefix the value is incremented and displayed.
To only display the current value, without incrementing, we simply refer to the document attribute without the counter: prefix.
For example if we want to add a counter attribute with the name steps we would use the following markup in Asciidoctor: {counter:steps}.
Continue reading →
With Asciidoctor we can use text to describe a symbol in our markup.
The text is automatically transformed to a Unicode replacement.
For example if we use the text (C) it is converted to © which is the copyright symbol: ©.
In the following sample we see all the symbol replacements:
Continue reading →
Interesting links for week 41 2016:
Continue reading →
With the Gradle Wrapper task we can specify the name of the generated script files.
By default the names are gradlew and gradlew.bat.
The Wrapper task has the property scriptFile.
We can set a different value for this property to let Gradle generate the script files with a different name.
In the following example we use the value mvnw (they will be surprised the build is so fast... ;-)) as the value:
Continue reading →
Sometime we need to define a project property in our Gradle build file for which the value must be evaluated later than the assignment.
We can do this in different ways in Gradle.
For example for a String type property we can rely on Groovy's support for lazy String evaluation.
If the property is of a different type we can use Closure to define the value.
The Closure code is not executed during the configuration phase directly, but we can write code to invoke the Closure at the right moment and get the value.
Finally we can use the afterEvaluate method of the Project class to define a lazy property.
Let's look at the different options we have with some code samples.
First we look at a lazy String property.
We illustrate this with an example of a multi-project build with the following layout:
Continue reading →
Interesting links for week 40 2016:
Continue reading →
Suppose we have a custom task with some properties that can be configured.
Normally we would add the configuration in the build script.
But we can also use command line options to configure a task.
So when we run the task from the command line we can provide a configuration value for the task on the command line.
To see which command line options are available for a task we can use the Gradle built-in task help followed by the option --task and the task name.
To indicate a property as command line option we use a @Option annotation.
We can specify the name of the command line option, a short description and also the order that is used to display the options with the help task.
Let's create a sample custom task and use the @Option annotation.
In the following build file we create a custom task GenerateVersionFile.
This task generates a file with a default name of version.txt in the build/ directory.
The file contains the project version value. We make the property that defines the output filename as a command line option.
This way the name can be defined when we run Gradle (and still of course using the default configuration in a build file).
Continue reading →
