ASCIIDOC gegen Schreibblockade – Grunt, Gradle und produktives Schreiben

Wer möchte nicht gerne Autor sein.

Ich als Entwickler schreibe viel Dokumentation. Hierfür verwende ich wenn möglich das vorhanden Wiki. Im schlimmsten Fall jedoch schreibe ich Dokumentation mit Word, Excel oder Pages.

Mein erstes Buch habe ich ebenfalls mit Hilfe von Pages geschrieben. Ich würde es nie wieder machen. Viel zu kompliziert und zu unhandlich.

Es sind bereits zwei weitere Bücher in der Mache. Hierfür verwende ich Asciidoc bzw. Asciidoctor und Gradle bzw. Grunt.

Folgendes Gradle-File ist hierfür ausreichend. Hier haben wir bereits Code-Highlighting inklusive.

buildscript {
    repositories {
        mavenRepo name: 'Bintray Asciidoctor repo', url: 'http://dl.bintray.com/content/aalmiray/asciidoctor'
        mavenRepo name: 'Bintray JCenter', url: 'http://jcenter.bintray.com'
    }

    dependencies {
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:0.7.0'
    }
}

apply plugin: 'asciidoctor'

asciidoctor {
    backend = 'html5'
    options = [
            eruby: 'erubis',
            attributes: [
                    'source-highlighter': 'coderay',
                    toc: '',
                    idprefix: '',
                    idseparator: '-'
            ]
    ]
}

Ascii-Doc Dateien werden per Default im Verzeichnis src/asciidoc gesucht. Dateien die geparsed werden haben Standardmäßig die Endung .adoc oder .asciidoc.

Wir erzeugen ein HTML5 Dokument aus dem Asciidoc-Dokument mit folgendem Befehl.

gradle asciidoctor

Das generierte Dokument ist per Default im Output-Verzeichnis “build/asciidoc” abgelegt.

Achtung: Derzeit ist es noch nicht möglich, PDF aus dem Asciidoc mit Gradle zu generieren. Dies ist bereits implementiert, ist aber erst mit dem Gradle-Plugin 0.8.0 verfügbar, das bisher noch nicht released ist.

Für PDF Generierung wäre das Backend nicht html5 sondern fopub

Generierung mit GRUNT

Eine Alternative hierzu ist beispielsweise die Arbeit mit Grunt. Grunt ist ein JavaScript-Task-Runner, mit dem sich so ziemlich alles automatisieren lässt.

Nehmen wir an, asciidoctor ist bereits installiert und auf der Konsole verfügbar.

Dann definieren wir folgende Datei package.json.

{
  "name": "sources",
  "version": "0.0.0",
  "dependencies": {},
  "devDependencies": {
    "grunt": "~0.4.2",
    "grunt-shell": "0.6.1",
    "grunt-contrib-watch": "~0.5.3"
  },
  "engines": {
    "node": ">=0.8.0"
  }
}

Wir benötigen sowohl das grunt-shell plugin, als auch das grunt-watcher plugin. Ziel ist es, wann immer sich die ascii-doc Datei ändert soll das HTML5-Dokument neu generiert werden.

Zusätzlich definieren wir folgende Grunt-Konfiguration.

module.exports = function (grunt) {

grunt.initConfig({
    shell: {
        generateAsciiDoc: {
            command: 'asciidoctor -b html5 -a last-update-label! -a linkcss mybook.adoc'
        },
        generatePDF : {
            command: 'asciidoctor -b docbook mybook.adoc -a last-update-label!; -a linkcss  fopub mybook.xml'
        }
    },

    watch: {
        scripts: {
            files: '*.adoc',
            tasks: ['shell'],
            options: {
                interrupt: true,
                livereload: true
            },
          },
    },

});

grunt.loadNpmTasks('grunt-shell');
grunt.loadNpmTasks('grunt-contrib-watch');
grunt.registerTask('default', ['shell:generateAsciiDoc']);
grunt.registerTask('pdf', ['shell:generatePDF']);
};

Führen wir jetzt auf der Konsole grunt watch aus, so wird das Dokument jedesmal neu generiert wenn wir daran Änderungen vorgenommen haben. Perfekt für die Arbeit am neuen Buch.

Links

Asciidoctor

Asciidoctor Gradle Plugin

ASCII Doc Cheat Sheet

AsciiDoctor Cheat Sheet

AsciiDoctor Writers Guide

Live Reload Browser Plugins

Effective Trainings & Consulting - Martin Dilger



Hat Ihnen dieser Blog-Eintrag gefallen? Ich stelle in diesem Blog Informationen über Tools, Frameworks und Werkzeuge zur Verfügung, die mich produktiver machen. Vielleicht kann ich auch Ihnen helfen, produktiver zu werden.


Ich unterstütze Sie als freier Mitarbeiter bei der Entwicklung von Software-Projekten, Agiler Arbeit sowie Schulungen / Fortbildungen.


Jeden Tag ein bisschen produktiver - ab heute