dagwieers / asciidoc-odf

ODF backend for AsciiDoc
98 stars 26 forks source link

= ODF backend for AsciiDoc :author: Dag Wieers :data-uri: :lang: en

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

[TIP] Flat ODF files (+.fodt+ and +.fodp+) are supported by LibreOffice/OpenOffice 3 and newer. For OpenOffice, follow http://user.services.openoffice.org/en/forum/viewtopic.php?f=47&t=44216[these instructions]. You can (<<a2x,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.

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 https://github.com/dagwieers/asciidoc-odf/issues[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.

==== Converting to MS Word

After that, if you want to convert the document to docx you can use libreoffice like this:

# soffice --headless --invisible --convert-to docx document.fodt

=== 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

[[a2x]] === 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 <<a2x,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 ["ditaa",scaling="4",width="125mm",height="50mm",align="center"]

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

[listing] .... [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:

[listing] .... [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:

[listing] .... [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):

[listing] .... [cols=3]

Continued text flow inside 3 columns.

.Even a list is possible

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

[listing] .... [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 +-cover.png+ in your ++ 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: https://bugzilla.redhat.com/show_bug.cgi?id=752393[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.

== Further Reading A few documents explain the ODF specification, the file format and the syntax:

And about using Open Source toolchains for publishing:

// vim: set syntax=asciidoc: