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