Open Document converter for Asciidoctor

Table of Contents

• Open Document converter for Asciidoctor
  • About
  • Usage
    • With docker
      • With a-od simplified utility
      • Or step by step without a-od
    • As a ruby script
      • Convert adoc to preliminary content file
      • Convert preliminary content file to fodt

About

Open Document converter for Asciidoctor allows to convert asciidoc documentation into fodt (plain Open Document) format. It relies on Asciidoctor project.

Fodt file may be converted with LibreOffice SDK or CLI into pdf, odt, docx, doc etc.

Examples (built automatically as a part of CI routine):

• source asciidoc file;

• fodt file (indexes are not updated);

• odt file;

• pdf file;

• docx file — yes, sometimes messy, but generally not so bad and there is always a possibility to simplify conversion rules and tailor them to the needs of the exact project.

The asciidoctor-open-document converter can be extended in the following ways:

• custom fodt template. Allows to customize paragraph properties, text properties, page properties (orientation, header, footer and like), list properties, table properties. Custom fodt template can contain title page or any before/after content;

• custom slim templates;

• custom xml-content preprocessor;

• custom Open Document style setters.

Usage

With docker

With a-od simplified utility

Assuming you need to convert test.adoc from the current directory to odt format.

docker run --rm -v $(pwd):/documents/ curs/asciidoctor-od a-od test.adoc odt

General syntax of a-od is:

a-od [file] [output format] [custom fodt temlate] [custom conversion library]

To use asciidoctor cli options add --asciidoctor at the end and any asciidoctor cli options. For example, to convert foo.adoc to pdf with revision number v5 use:

a-od foo.adoc pdf --asciidoctor -a revnumber=v5

Or step by step without a-od

• Convert adoc to preliminary Open Document content file

  The following steps assume that asciidoc file test.adoc is in the /my-adoc directory. As a result we want to get test.fodt and test.pdf.

  docker run --rm -v $(pwd):/documents/ curs/asciidoctor-od a-od-pre -r asciidoctor-mathematical -r asciidoctor-diagram test.adoc -o pre.xml

  Here asciidoctor-mathematical and asciidoctor-diagram extensions are used.

• Convert preliminary Open Document content file to fodt

  docker run --rm -v $(pwd):/documents/ curs/asciidoctor-od a-od-out -c /usr/local/a-od/a-od-my/my-cp-example.rb -i pre.xml -o test.fodt

  Here the custom library is used. It contains examples of custom features: positioning equation number, paragraph alignment role, code highlighting, positioning admonitions inside of the list element.

• Convert fodt to pdf, odt, docx

  docker run --rm -v $(pwd):/documents/ curs/asciidoctor-od java -jar /usr/local/a-od/lo-kts-converter.main.jar -f pdf,odt,docx -i test.fodt

As a ruby script

Conversion consists of 2 steps.

1. Convert adoc to preliminary content file

2. Convert preliminary content file to fodt

Convert adoc to preliminary content file

Conversion to preliminary content file is done by the standard asciidoctor command with a slim template (slim folder of a source code).

asciidoctor -T [path to slim] -b fodt asciidoc_file.adoc

There is a wrapper a-od-pre in docker image. Use it like a normal asciidoctor command. It just sets slim template and backend.

Convert preliminary content file to fodt

Conversion to final fodt file is done with the asciidoctor-od.rb script.

ruby [path to script]/a-od-producer.rb -i [prelimenary content file] -o [final file] -c [custom process library] -f [fodt template]

There is a wrapper a-od-out in docker image. It just runs ruby with a-od-producer.rb.

More details can be found in Open Document converter for Asciidoctor documentation.