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.
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). |
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.
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). |
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.
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.
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
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. |
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.
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
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. |
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. |
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.
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.
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:
+------+
+--------+ +->|ODF{d}|
+->|Flat ODF|-+ | +------+
+--------+ +--------+ | | {d}| | +-------+ +->|PDF{d}|
|Plain |--+asciidoc+-+ +--------+ +-+unoconv+--+ +------+
|Text {d}| | c789| | ODF{io}| | | c789| +->|DOC{d}|
+--------+ +--------+ |Template|-+ +---*---+ | +------+
+--------+ | +->|PPT{d}|
+-----*-----+ +------+
|libreoffice|
| c897|
+-----------+
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. /////////////////////////////////////////////////////////
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. |
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. |
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.
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
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 ! |
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.
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
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.
A few documents explain the ODF specification, the file format and the syntax:
And about using Open Source toolchains for publishing: