README.adoc

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 target/publish/html and target/publish/docbook/publish/en-US/pdf directories 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 JCP license just enter mvn -Pjcp

Working on the spec

The spec is split different AsciiDoc file in src/main/doc 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:

Atom

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:

Brackets

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

More information:

AsciiDocFX

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

LiveReload

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

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