Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
Gemfile.lock Update Asccidoctor Ruby dependencies to prevent security issue Feb 23, 2018
Guardfile Update guard to ease preview Nov 30, 2015
guard.sh Simplification of spec doc generation by using Asciidoc attribute ins… Jan 23, 2017


CDI Specification document generation

This module contains AsciiDoc sources and configuration to generate CDI documentation in HTML and PDF format for both Apache License 2 and Java Community Process License.

Generating the documentation

Just enter mvn at the command line. Maven will generate final doc in HTML and PDF in target directory with the default license (ASL2).

License in doc

The documentation can be generated for 2 licenses : Apache License v 2.0 (by default) and JCP license. To generate doc with various JCP licenses just change the license-file property with one of the following value:

  • jcp-prefinal: for pre-final license

  • jcp-final-eval: for final evaluation license

  • jcp-final: for final implementation license

  • asl2: (default value) for Apache V2 License

For instance mvn -Dlicense-file=jcp-prefinal will generate docs with JCP pref-final license.

Working on the spec

The spec is split different AsciiDoc file in src/main/asciidoc The master doc (entry point) is cdi-spec.asciidoc which includes all the other part of the spec.

To work in the spec you may want to install a plugin in your IDE (major 3 IDE have AsciiDoc plugins). You can also use a good text editor providing AsciiDoc plugin. Best candidate are:


Install Atom. Then from the Atom editor menus, navigate to Atom  Preferences. From there, open the Packages tab and install:

AsciiDoc Preview package

enables live preview

AsciiDoc package

enables syntax highlighting (AsciiDoc language support)

More information:


Install Brackets. Then from the Brackets file menu, open the extension manager. Browse available extensions and install AsciiDoc Preview.

More information:


To run AsciiDocFX, you will need to:

  1. Install JDK 8

  2. Download the latest AsciidocFX.zip and extract it

  3. Run bin/asciidocfx.bat or bin/asciidocfx.sh

More information:

Using a web browser (preview only)

All you need to preview an AsciiDoc document in a web browser is to install the Chrome extension, the Firefox add-on or the Opera extension. Then you can see the AsciiDoc file rendered as HTML just by visiting it!

Editing the spec with Live Preview

If you want to more than just preview AsciiDoc files in your browser you may need to use an auto-generating mechanism and live preview in your browser. The spec provides script to help you setting up this configuration. Ìt only requires to have Ruby 1.8.7 or higher installed on your machine. More info on Ruby installation on https://www.ruby-lang.org/en/documentation/installation/

When Ruby is installed you’ll have to install bundler ruby gem with gem install bundler command. Then you can use it to install needed gems by entering the following command from spec directory

bundle install

After that, just launch ./preview.sh or preview.bat script to have the html version of the spec generated at each AsciiDoc change.

To have the generated html file automatically reload in your browser you may use LiveReload plugin.


To use Chrome, Firefox or Opera to automatically preview change on your working doc, check out LiveReload. It describes itself as:

LiveReload monitors changes in the file system. As soon as a file is saved, it is sent to the browser using a WebSocket. In addition to reloading the HTML, it supports live updating of CSS and JavaScript in the page.

You can setup LiveReload (for free) on any operating system using the Guard::LiveReload plugin and the companion LiveReload extension for Chrome or Firefox. You can also install Chrome plugin in Opera with the chrome support extension

After installing the Chrome LiveReload extension, you need to check the "Allow access to file URLs" checkbox in Tools > Extensions > LiveReload in order for it to work with local files.

Whenever the AsciiDoc file is changed, first the Guard "shell" plugin will be triggered to generate the HTML file, then the "livereload" plugin will be triggered to send the HTML to the browser.