| 1 | XHTML to ODT XML transformation
|
|---|
| 2 | -------------------------------
|
|---|
| 3 |
|
|---|
| 4 | These stylesheets convert namespaced XHTML to [ODT][].
|
|---|
| 5 |
|
|---|
| 6 | You can [download them][download] from the project's [website].
|
|---|
| 7 |
|
|---|
| 8 | The HTML must be well-formed and valid, so I recommand running it through [Tidy][] before sending it to the stylesheets.
|
|---|
| 9 |
|
|---|
| 10 | Those stylesheets do not build a whole ODT file, they only convert the XHTML to the equivalent OpenDocument XML. The result can then be inserted in a template ODT file. The HTML may be included in an ODT document, the ODT will be left untouched.
|
|---|
| 11 |
|
|---|
| 12 | This is based on the work on [docbook2odt][], by Roman Fordinal. Many thanks to him.
|
|---|
| 13 |
|
|---|
| 14 | [ODT]: http://en.wikipedia.org/wiki/OpenDocument
|
|---|
| 15 | [Tidy]: http://tidy.sourceforge.net/
|
|---|
| 16 | [docbook2odt]: http://open.comsultia.com/docbook2odf/
|
|---|
| 17 | [download]: http://xhtml2odt.org/dl/
|
|---|
| 18 | [website]: http://xhtml2odt.org
|
|---|
| 19 |
|
|---|
| 20 |
|
|---|
| 21 | Caveats
|
|---|
| 22 | -------
|
|---|
| 23 |
|
|---|
| 24 | **Styles** : some default styles will be added to the document, but not on the first pass. After converting to ODT, you must run the `content.xml` and the `styles.xml` files (in the ODT file) through the `xsl/styles.xsl` stylesheet to add the styles. When the default styles are added, the stylesheet checks that the style is not already present, so customizations to the template ODT file will be preserved. It will however add styles that are not used in the text, but that's harmless.
|
|---|
| 25 |
|
|---|
| 26 | **Images** : images are not added, you must manually go trough the draw:image elements in the converted ODT text and use the xlink:href attribute to download or copy the image. While you're at it, you should update the image dimensions if the were not provided in the img tag.
|
|---|
| 27 |
|
|---|
| 28 |
|
|---|
| 29 | Command-line scripts
|
|---|
| 30 | --------------------
|
|---|
| 31 |
|
|---|
| 32 | Two command-line scripts to run the stylesheets are provided, one is Python-based, the other is PHP-based. They do import the styles and the images, so they can also be used as a code example for these two steps in other languages and actual export plugins.
|
|---|
| 33 |
|
|---|
| 34 | Documentation for both scripts can be generated using the "`make doc`" command. This will require [sphinx][] for python and [phpDocumentor][] for PHP.
|
|---|
| 35 |
|
|---|
| 36 | [sphinx]: http://sphinx.pocoo.org/
|
|---|
| 37 | [phpDocumentor]: http://www.phpdoc.org/
|
|---|
| 38 |
|
|---|
| 39 | ### The python script
|
|---|
| 40 |
|
|---|
| 41 | The python script is the preferred command-line script, because it currently is a little more complete than the PHP script. It depends on the following Python modules:
|
|---|
| 42 |
|
|---|
| 43 | * [uTidylib][]
|
|---|
| 44 | * [lxml][]
|
|---|
| 45 | * [PIL][]
|
|---|
| 46 |
|
|---|
| 47 | To get information on the script's options, run it with `--help`:
|
|---|
| 48 |
|
|---|
| 49 | ./xhtml2odt.py --help
|
|---|
| 50 |
|
|---|
| 51 | The script can be installed on the system with the `make install` command.
|
|---|
| 52 |
|
|---|
| 53 | [uTidylib]: http://pypi.python.org/pypi/uTidylib
|
|---|
| 54 | [lxml]: http://pypi.python.org/pypi/lxml
|
|---|
| 55 | [PIL]: http://pypi.python.org/pypi/PIL
|
|---|
| 56 |
|
|---|
| 57 | ### The PHP script
|
|---|
| 58 |
|
|---|
| 59 | The PHP script can be used as an example to create an ODT export plugin for a PHP-based application. It contains comments on what you should do differently in a web-based application. If you want a real PHP-based export plugin, you can look at the code of the [Dotclear ODT export plugin][].
|
|---|
| 60 |
|
|---|
| 61 | The PHP script requires the [zip][] module, and will work better with the [tidy][] extension.
|
|---|
| 62 |
|
|---|
| 63 | To get information on the script's options, run it with `--help`:
|
|---|
| 64 |
|
|---|
| 65 | ./xhtml2odt.php --help
|
|---|
| 66 |
|
|---|
| 67 | [Dotclear ODT export plugin]: http://lab.dotclear.org/wiki/plugin/odt
|
|---|
| 68 | [zip]: http://php.net/manual/en/zip.installation.php
|
|---|
| 69 | [tidy]: http://php.net/manual/en/book.tidy.php
|
|---|
| 70 |
|
|---|
| 71 |
|
|---|
| 72 | Tests
|
|---|
| 73 | -----
|
|---|
| 74 |
|
|---|
| 75 | The unit tests are python-based, you need to install the [nose][] python module availble from PyPI (or your distribution).
|
|---|
| 76 |
|
|---|
| 77 | Then, just run "`nosetests tests`".
|
|---|
| 78 |
|
|---|
| 79 | [nose]: http://pypi.python.org/pypi/nose/
|
|---|
| 80 |
|
|---|
| 81 |
|
|---|
| 82 | References
|
|---|
| 83 | ----------
|
|---|
| 84 |
|
|---|
| 85 | * [ODT export for Dotclear](http://lab.dotclear.org/wiki/plugin/odt)
|
|---|
| 86 | * [ODT export for Trac](http://trac-hacks.org/wiki/OdtExportPlugin)
|
|---|
| 87 | * [ODT export for Dokuwiki](http://www.dokuwiki.org/plugin:odt) (not using this project, but similar and by the same author)
|
|---|
| 88 |
|
|---|
| 89 |
|
|---|
| 90 | License
|
|---|
| 91 | -------
|
|---|
| 92 |
|
|---|
| 93 | Copyright (C) 2009-2010 [Aurelien Bompard][].
|
|---|
| 94 |
|
|---|
| 95 | Inspired by the work on [docbook2odt][], by Roman Fordinal.
|
|---|
| 96 |
|
|---|
| 97 | [Aurelien Bompard]: http://aurelien.bompard.org/
|
|---|
| 98 | [docbook2odt]: http://open.comsultia.com/docbook2odf/
|
|---|
| 99 |
|
|---|
| 100 | License is LGPL v2 or later: http://www.gnu.org/licenses/lgpl-2.0.html
|
|---|
| 101 |
|
|---|
| 102 | This library is free software; you can redistribute it and/or
|
|---|
| 103 | modify it under the terms of the GNU Library General Public
|
|---|
| 104 | License as published by the Free Software Foundation; either
|
|---|
| 105 | version 2 of the License, or (at your option) any later version.
|
|---|
| 106 |
|
|---|
| 107 | This library is distributed in the hope that it will be useful,
|
|---|
| 108 | but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|---|
| 109 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|---|
| 110 | Library General Public License for more details.
|
|---|
| 111 |
|
|---|
| 112 | You should have received a copy of the GNU Library General Public
|
|---|
| 113 | License along with this library; if not, write to the
|
|---|
| 114 | Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
|
|---|
| 115 | Boston, MA 02110-1301, USA.
|
|---|
| 116 |
|
|---|
