Skip to content
This repository

ODF backend for AsciiDoc

branch: master
README.asciidoc

ODF backend for AsciiDoc

Introduction

The ODF backend for AsciiDoc enables AsciiDoc users to directly convert documents from AsciiDoc to Open Document Format v1.2.

AsciiDoc is a lightweight markup language that maps to DocBook semantics and makes writing (technical) documentation and presentations more enjoyable as it removes styling and formatting from the creative process.

Benefits

The ODF backend provides the following benefits:

  • Visual styling and formatting using LibreOffice
    (no more need to modify pesky XSLT or XSL-FO)

  • Saving and re-applying styles during processing
    (simply modify styles in LibreOffice and save them to reapply)

  • Converting to various formats supported by LibreOffice
    (export plugins include PDF, DOC, HTML, …)

  • Support for flat ODF (.fodt and .fodp) files to help with experimenting
    (flat ODF files are useful for manual styling, debugging or learning ODF)

  • Integration of the various AsciiDoc plugins
    (enabling the use of ascii-art to generate schemas, diagrams and charts)

Tip
Flat ODF files (.fodt and .fodp) are supported by LibreOffice/OpenOffice 3 and newer. For OpenOffice, follow these instructions. You can (use a2x if you need the more common packaged ODF support).

Limitations

Although the current implementation is already quite useful, it is not 100% feature complete. We are working on it and your help in testing and feedback is appreciated.

  • Incomplete implementation lacks eg. complex table support, …

  • Default stylesheet needs improvements (especially for presentations)

We hope to address each of these limitations in the future, and your help and your feedback is welcome, needed and appreciated. There is a list of known issues and requested features.

Installing the ODF backend

The ODF backend actually consists of two plugins, one for ODT support and one for ODP support. You can download these plugins (resp. odt-backend.zip and odp-backend.zip) from: https://github.com/dagwieers/asciidoc-odf/downloads

To install them, use the following command:

# asciidoc --backend install odt-backend.zip
# asciidoc --backend install odp-backend.zip

There are some other plugins available you could use, one is a custom cv theme, the other an optional code filter that supports bash/python and ODF output.

# asciidoc --theme install cv-theme.zip
# asciidoc --filter install code-filter.zip

Once this is finished, you are ready to start using the ODF backend.

Important
You need the latest AsciiDoc source code from the AsciiDoc website in order to use the ODF backend (AsciiDoc v8.6.7 or newer will do fine, once released).

Using the ODF backend

Usage for text documents

Generating an OpenDocument Text file, simply do:

# asciidoc -b odt document.txt

This will produce the file document.fodt which is a flat ODT file, a single XML file that can be opened using any recent LibreOffice.

Usage for presentations

Generating an OpenDocument Presentation file, simply do:

# asciidoc -b odp presentation.txt

This will produce the file presentation.fodp which is a flat ODP file, a single XML file that can be opened using any recent LibreOffice.

Adding a style theme

You can modify a stylesheet and make it available from your asciidoc themes/ directory. Creating an ODF file using a specific theme is easy:

# asciidoc -b odt --theme hp document.txt

Generating proper packaged ODF files using a2x

The latest AsciiDoc release includes a modified a2x program that understands plugin-specific actions. This enables to generate a proper packaged ODF file (not a flat XML ODF file) when using a2x.

If you want to generate a proper (packaged/zipped) ODF file, use

# a2x -v -b odt your_file.txt

You can also provide an ODF or OTT as a template to use styles from, by doing:

# a2x -v -b odt --backend_opts="--base_doc=your_template.ott" your_file.txt

Same is true for generating and styling ODP files:

# a2x -v -b odp --backend_opts="--base_doc=your_template.otp" your_file.txt

Thanks to this, styling becomes very easy. Just open your document in LibreOffice, modify any existing styles, save again as an OTT or OTP file and use it as part of any future ODF conversions.

Important
The a2x and packaged ODF file is not yet ready for prime time. There are some unfinished items related to styling and meta-information. We hope to finish it soon.

Additional functionality

Embedded images

Images can be embedded in your ODF document. To do this use the option -a data-uri on the command line or add the data-uri attribute to your AsciiDoc file:

:data-uri:

When using packaged ODF files, images will be added to the ODF file and not embedded, regardless of the data-uri attribute.

Admonition icon support

If you use admonitions in your documents, please use the options -a icons -a iconsdir=/usr/share/asciidoc/images/icons on the command line or add those attributes in your AsciiDoc file:

:icons:
:iconsdir: /usr/share/asciidoc/images/icons

Numbered titles

If you like titles to be numbered, please use the option -a numbered on the command line or add the numbered attribute to your AsciiDoc file:

:numbered:
Note
The current implementation adds title numbers always. Since numbering chapters/sections is part of the stylesheet in ODF, it is complex to make this a configurable option. Modify the stylesheet if you like to customize this behaviour.

Table of Contents support

The ODF backend has Table of Contents support if you use the option -a toc on the command line or add the toc attribute to your AsciiDoc file:

:toc:

The TOC depth can be specified using the option -a toclevels=2 on the command line or add the toclevels attribute to your AsciiDoc file:

:toclevels: 2
Note
The ODF backend does not stuff the Table of Contents, but only adds the necessary pieces to the ODF file so that LibreOffice can update it. However we also included an event-handler so that when opened the Table of Contents will automatically be updated. This also means that on opening the file the first time, it will automatically be flagged as modified.

Using themes (or custom stylesheets)

The ODF backend can uses themes, which means that it can use alternative stylesheets. Currently the curriculum-vitae example uses its own (basic) theme as an example of how this is supposed to work. To select a theme you can use the option -a theme=cv on the command line or add the theme attribute to your AsciiDoc file:

:theme: cv

This project also provides an adapted a2x to automatically merge the existing styles from an .odt or .ott file, so that one can save the modified work from LibreOffice and use the styles from that document as the input for future documents.

We think this is easier for end-users than extracting the styles and putting it into themes, but both methods are available.

Source code highlighting

We contributed ODF output support for the GNU source-highlight project, as a result you can now have proper syntax highlighting in source output in all your documents by using [source] blocks.

[source,python]
#!/usr/bin/python
import os
print os.name
Important
Make sure you have at least GNU source-highlight 3.1.6 installed !

And alternative (more simple) syntax highlighting is provided as part of the code filter provided in the download section.

Diagram filter support

One of the advantages of AsciiDoc is the choice of filters available, especially for creating diagrams, graphs or charts plenty of options are at your disposal: aafigure, ditaa, graphviz, mscgen, plantuml, …

These plugins take input and create graphics to illustrate your point better. We have provided some examples in the source tree, but this would be the source block for a ditaa graph describing the ODF backend for asciidoc, in pure ascii-art:

Example ditaa diagram
                                                     +------+
                          +--------+              +->|ODF{d}|
                       +->|Flat ODF|-+            |  +------+
+--------+  +--------+ |  |     {d}| | +-------+  +->|PDF{d}|
|Plain   |--+asciidoc+-+  +--------+ +-+unoconv+--+  +------+
|Text {d}|  |    c789|    | ODF{io}| | |   c789|  +->|DOC{d}|
+--------+  +--------+    |Template|-+ +---*---+  |  +------+
                          +--------+       |      +->|PPT{d}|
                                     +-----*-----+   +------+
                                     |libreoffice|
                                     |       c897|
                                     +-----------+

Comment support

AsciiDoc has the functionality to make (inline) comments show in the output, the ODF backend also provides this functionality. When you use the -a showcomments option on the command line or add the showcomments attribute to your AsciiDoc file, like:

:showcomments:

the ODF backend will add the comments to the output marked in yellow.

However, if you like to also have comment blocks displayed in the output, you can use the comment style comment blocks:

[comment]
/////////////////////////////////////////////////////////
This is a multi-line comment that is enabled in normal
output when using the showcomments attribute.
/////////////////////////////////////////////////////////

Annotation support

The ODF backend has support for annotation style comment blocks, these special blocks will result in proper ODF annotations, including owner and timestamp if provided.

Adding an annotation block is done using the following syntax:

[annotation,dag,2011-12-03]
/////////////////////////////////////////////////////////
FIXME:
Insert the various features from the Release Notes
include the information from the presentations
/////////////////////////////////////////////////////////
Note
Annotations are always added to the ODF output but will not be printed, and might be removed depending on the converted document format (e.g. to PDF). If you don’t want annotations in your ODF output, use the hideannotations attribute.

Columns support

In some cases (e.g. very long lists, or booklets) one may wish to provide information in columns on a page so that page estate is better utilized. The ODF backend makes this possible by adding a cols attribute for sections. You can create a two-columns section, by doing:

[cols=2]
== Section title
Text-body will be put in columns.

=== Section subtitle
Everything, including subsections !

You can also make blocks of text use columns, but this cannot include section titles (or subsections):

[cols=3]
--
Continued text flow inside 3 columns.

.Even a list is possible
 - One
 - Beta
 - Charlie
--

And even paragraphs can consist of columns, if you set the cols attribute on a paragraph:

[cols=2]
A very long paragraph that can make use of columns...
Note
If you plan to include subsections in your columns, you have to use this first construction.

Generating books with covers

If you want to generate a book, use the option -d book or add the doctype attribute to your AsciiDoc file:

:doctype: book

The book doctype will create a cover with title, author and date/version information. Depending on the theme this can be influenced and adapted to your needs. The Table-of-Contents and Preamble are put on dedicated pages as well.

The attributes used on the cover page are: author, date and version

By default if you generate a cover, AsciiDoc will look for the file <theme>-cover.png in your <theme> theme directory and add it to the cover. The stylesheet defines the dimensions and where the cover image is placed.

Tip
It is also possible to change the stylesheet to have chapters starting on new pages, make it start on even pages, have different headers and footers on odd/even pages and more…

We may change this functionality in the future to make more advanced cover-pages possible. Development in this area depends on the wishes and the abstractions possible.

Development

You can find the latest version of this AsciiDoc backend at http://github.com/dagwieers/asciidoc-odf

You can help improve the backend by looking for missing/non-working functionality and implementing/fixing it in the odt.conf file. Using LibreOffice and saving your tests, and inspecting how LibreOffice does something helps to understand what is needed for the backend.

If you start off using a flat ODF file, LibreOffice will use flat ODF files as well, so the turn-around time in debugging/development is quite fast.

Any issues or feedback can be communicated using the Github web interface. A list of known issues and requested features are available from: https://github.com/dagwieers/asciidoc-odf/issues

Debugging

Things can always be improved, if you are stuck with an issue or you just want to help out with this project, rejoice because below you will find some hints on how to debug and fix your issue !

Note
Please contribute any improvements to the styles or ODT definition so that other people can enjoy your fixes !

Missing text/section in LibreOffice

If some text/section is missing in LibreOffice, you can debug the ODF file by generating a Flat ODF (.fodt) file and opening it with an editor. Look if the text is part of the file.

Fails to open in LibreOffice

If the ODF file fails to open in LibreOffice, you can perform a syntax-check of the generated Flat ODF (.fodt) using one of the following command:

# jing -i OpenDocument-v1.2-os-schema.rng document.fodt
# xmllint --noout --relaxng OpenDocument-v1.2-os-schema.rng document.fodt

If this outputs an error, it means the ODF file does not conform the schema.

Important
A bug in xmllint that was recently fixed may cause errors not related to ODF output. Make sure that your xmllint ships with the following fix: Bug 752393 - Unimplemented block at relaxng.c:8948

When debugging the generated flat XML ODF file, it can help to look at the schema to understand what’s wrong. Information about the RelaxNG schema is available from: http://relaxng.org/#tutorials

Styles look incorrect

If the output looks different to what you expect, you can modify the styles inside LibreOffice, write it out to a Flat ODF file and compare the created style with the original. You can then change either the odt.conf or the asciidoc.odt.styles so that the output conforms to what LibreOffice produces.

Something went wrong with that request. Please try again.