Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dagwieers/asciidoc-odf
ODF backend for AsciiDoc
https://github.com/dagwieers/asciidoc-odf
Last synced: 3 months ago
JSON representation
ODF backend for AsciiDoc
- Host: GitHub
- URL: https://github.com/dagwieers/asciidoc-odf
- Owner: dagwieers
- Created: 2011-09-29T08:08:49.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2017-09-29T15:45:37.000Z (over 7 years ago)
- Last Synced: 2024-10-23T08:52:59.875Z (3 months ago)
- Language: Python
- Homepage:
- Size: 561 KB
- Stars: 98
- Watchers: 13
- Forks: 26
- Open Issues: 29
-
Metadata Files:
- Readme: README.asciidoc
Awesome Lists containing this project
README
= 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:
- 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
http://user.services.openoffice.org/en/forum/viewtopic.php?f=47&t=44216[these instructions].
You can _(<> 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
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 <> 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
- One
- Beta
- Charlie
--
....
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:
- http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2-part1.pdf[Open Document Format v1.2 schema]
- http://books.evc-cit.info/oobook/book.html[OpenOffice.org XML Essentials]
- http://xml.openoffice.org/general.html[OpenOffice.org XML File Format]
- http://en.wikipedia.org/wiki/OpenDocument_technical_specification[Wikipedia: OpenDocument technical specification]
And about using Open Source toolchains for publishing:
- http://www.dmncommunications.com/presentations/Content_with_OSS_notes.pdf[Creating Quality Content with Open Source Tools]
- http://www.stevestreeting.com/2010/03/07/building-a-new-technical-documentation-tool-chain/[Building a new technical documentation tool chain]
- http://blog.rainwebs.net/2010/02/25/how-to-create-handsome-pdf-documents-without-frustration/[How to Create Handsome PDF Documents Without Frustration]
// vim: set syntax=asciidoc: