A documentation toolchain based on AsciiDoctor. It implements custom processors for technical writing, organizing documentation and task management.

Features

[def] - Definition Block: Add definitions with custom formatting.
include::{}[ ] - Include (extended): Includes files using special variables.
cwiki:[ ] - Inline Cwiki: Inserting links to Confluence Wiki pages.
task:[ ] - Inline Task: Insert links to Jira and GitHub.
cite:[ ] - Inline BibTeX: Inserting citations from a BibTeX file.
srclnk:[ ] - Inline Source Link: Inserting links to source files on GitHub.
math:[ ] - Inline Math: Inserting math expressions.
[math] - Math Block: Add long math formulae.
[req] - Requirement Block: Add requirements with custom formatting.
[TODO] - Todo Block: Add a custom TODO admonition block.
call:[ ] - Inline Callout Macro: Arbitrarily add numbered callouts.

Prerequisites

• Apache Maven

• asciidoctorj-1.6.0. There is no artifact publicly available at the moment. Please follow these steps:

  1. Checkout asciidoctorj-1.6.0

  2. Navigate to the root of the asciidoctorj-1.6.0 project and run ./gradlew assemble

  3. Install the dependency to your local maven repository by running

mvn install:install-file -Dfile=./asciidoctorj-core/build/libs/asciidoctorj-1.6.0-SNAPSHOT.jar -DgroupId=org.asciidoctor -DartifactId=asciidoctorj -Dversion=1.6.0-SNAPSHOT -Dpackaging=jar

• snuggletex-1.2.3. This is a custom fork of SnuggleTex that supports a few more LaTeX symbols in math expressions. Please follow these steps:

  1. Checkout snuggletex-1.2.3 and switch to branch enfore.

  2. Navigate to the root of the snuggletex project and run mvn package

  3. Install the dependency to your local maven repository by running

mvn install:install-file -Dfile=./snuggletex-core/target/snuggletex-core-1.2.2.jar -DgroupId=uk.ac.ed.ph.snuggletex -DartifactId=snuggletex-core -Dversion=1.2.3-SNAPSHOT -Dpackaging=jar

Once installed, remember to update the project dependencies within your IDE. In Eclipse you can do this by right clicking on the project → Maven → Update Project. That should resolve dependency related errors.

To import Asciispec into Eclipse, install the m2e plugin and use the project import wizard.

Build

To build the project, clone this repository, navigate to the project folder and run the following command (optionally add -Dmaven.test.skip=true to skip tests):

mvn clean package

After maven has successfully finished building the project, a zip file containing the asciispec tool will be available under asciispec/target/asciispec-bin.zip

Installation

Add AsciiSpec to your shell profile with the path to the asciispec/bin directory on your system:

export PATH=$PATH:~/path/to/asciispec/bin/

If the AsciiSpec tool is found by your system, running AsciiSpec with the -h flag will print a help page:

asciispec -h

Usage

Convert to HTML

Generates a sample.html file in the current directory:

asciispec sample.adoc

Convert to DocBook:

Generates a sample.xml file in the current directory.

asciispec -b docbook sample.adoc

DocBook format can be further converter to PDF with asciidoctor-fopub. This fork of the fopub project contains some cosmetic changes.

Help

Running asciispec -h will print the AsciiDoctor help page.
For more options, see the CLI Options section of the AsciiDoctor user manual.

Documentation

HTML Documentation	http://numberfour.github.io/asciispec
Userguide	Userguide: Introduction to AsciiDoc syntax and some basic AsciiSpec usage tips.
Other	Troubleshooting: Help for getting started and debugging installation errors.