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):

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.

How does it work

Setting predefined styles

“You should create documentation in Word, RIGHT WAY”.

MS Word as well as Open Office suggest that each element should have only one style. That greatly contradicts to the concept of cascaded styles (CSS), but makes things easier. If we can define such a unique style for text or paragraph, then we need nothing more.

It is always the case with list styles, but sometimes with text or less often paragraph styles.

StyleSubstitor just sets the predefined style for certain elements.

Here we may also do any xml preprocessing. Change the order of elements, insert custom elements. As we do it with xml, such preprocessing is extremely fast.

To extend setting predefined styles routine just make a descendant of StyleSubstitutor in your custom library.

Automatic styles calculation

If you add you custom formatting to any paragraph Open Office simply generates automatic style that references parent (predefined style) and adds properties. Thee properties add or replace predefined style formatting.

Templating technology can’t generate styles, but this converter adds formatting hints to the name of the style. AutoStyleSetter transforms this hint into automatic styles.

BasicPropSetSorter chooses the right property setter class and property setter class sets parent (predefined) class and additional properties.

To extend style substitution just inherit from any property setter class, for example BasicBlockImageParagraph. Or from the basic sorter class BasicPropSetSorter.

All methods should start with h_.

Customizing fodt template

  • Only part of template that is situated between paragraphs, containing text <asciidoctor-od>, is replaced with the content of the asciidoctor file. This allows to make, for example, title pages.

  • Asciidoc document attributes like title, subtitle, author etc. can be used via Open Document variable-set fields. The content of these fields is taken from asciidoc document attributes. For now only text variable-set fields are supported.

  • Out of the box converter supports only two page styles (for portrait and landscape). This can be easily extended by custom conversion library.

Not implemented

Not implemented elements

audio
dlist
inline_button
inline_kbd
inline_menu
open
page_break
pass
quote
section (no special processing for special sections)
sidebar
thematic_break
verse
video

Converter variables

Converter variables are set as global variables. They start with def prefix.

They can now be overriden only in custom library, but the ability to set them as document attributes is in the TODO-list.

Table properties

  • frame and grid are implemented only if (1) both are none, (2) frame is topbot and grid is rows, (3) frame is sides and grid is cols

  • float

  • width (always 100%)

  • options = autowidth

Frame usage

Admonitions and examples are created with the help of a frame.

Frame width in Open Document format can’t be defined in relation to paragraph, only paragraph area. So in lists frames will start from the left page margin.

As frames are aligned to right, it is possible to introduce some attribute that would decrease frame width. The example is in the a-od-my custom library of this project: list-level1-admonition.

Important
 Frames don’t flow across pages

Additional features

Image attributes

  • fitrect — dimensions to fit image in like 100x50mm. Only mm unit is supported

  • srcdpi — resolution of the source image. Usually when we add something to our diagram (like new process to the process diagram), the dimensions of the image change, but resolution doesn’t change. Default — 100 dpi.

  • svgunit — units, in which svg dimensions are defined

This attribute doesn’t eliminate the need to have a set of image for each resolution, but for simple situation it is quite enough.

If fitrect is not defined in inline images it is assumed from the following attributes:

  • def_100_percent_mm — width

  • def_inline_height_mm — height

Page orientation

Page orientation is regulated by special roles: portrait, landscape.

The role can be applied to paragraph, section and caption (table, figure, list, example) elements.

Note
 Page orientation roles switch orientation for all elements to the end of the document. It can be switched back starting at any supported element