Changeset 2297f7d


Ignore:
Timestamp:
08/13/10 12:32:34 (3 years ago)
Author:
Aurélien Bompard <aurelien@…>
Branches:
master
Children:
ffb7bf9
Parents:
9fccc49
git-author:
Aurélien Bompard <aurelien@…> (08/13/10 12:32:34)
git-committer:
Aurélien Bompard <aurelien@…> (08/13/10 12:32:34)
Message:

Convert README from markdown to RST

File:
1 edited

Legend:

Unmodified
Added
Removed

  • README.txt

    r95c8501 r2297f7d  
    11XHTML to ODT XML transformation 
    2 ------------------------------- 
     2=============================== 
    33 
    4 These stylesheets convert namespaced XHTML to [ODT][]. 
     4These stylesheets convert namespaced XHTML to ODT_. 
    55 
    6 You can [download them][download] from the project's [website]. 
     6You can download_ them from the project's website_. 
    77 
    8 The HTML must be well-formed and valid, so I recommand running it through [Tidy][] before sending it to the stylesheets. 
     8The HTML must be well-formed and valid, so I recommand running it through Tidy_ 
     9before sending it to the stylesheets. 
    910 
    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. 
     11Those stylesheets do not build a whole ODT file, they only convert the XHTML to 
     12the equivalent OpenDocument XML. The result can then be inserted in a template 
     13ODT file. The HTML may be included in an ODT document, the ODT will be left 
     14untouched. 
    1115 
    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 
     16.. _website: http://xhtml2odt.org/ 
     17.. _download: http://xhtml2odt.org/dl/ 
     18.. _ODT: http://en.wikipedia.org/wiki/OpenDocument 
     19.. _Tidy: http://tidy.sourceforge.net/ 
    1920 
    2021 
    … …  
    2223------- 
    2324 
    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. 
     25Styles: 
     26    Some default styles will be added to the document, but not on the first 
     27    pass. After converting to ODT, you must run the ``content.xml`` and the 
     28    ``styles.xml`` files (in the ODT file) through the ``xsl/styles.xsl`` 
     29    stylesheet to add the styles. When the default styles are added, the 
     30    stylesheet checks that the style is not already present, so customizations 
     31    to the template ODT file will be preserved. It will however add styles that 
     32    are not used in the text, but that's harmless. 
    2533 
    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. 
     34Images: 
     35    Images are not added, you must manually go trough the ``draw:image`` 
     36    elements in the converted ODT text and use the ``xlink:href`` attribute to 
     37    download or copy the image. While you're at it, you should update the image 
     38    dimensions if the were not provided in the ``img`` tag. 
    2739 
    2840 
    … …  
    3042-------------------- 
    3143 
    32 Three command-line scripts to run the stylesheets are provided, one is Python-based, the other is PHP-based, the last one is shell-based. The first two 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. The shell script is more of a minimalist approach to demonstrate the simplest possible use of the stylesheets. 
     44Three command-line scripts to run the stylesheets are provided, one is 
     45Python-based, the other is PHP-based, the last one is shell-based. The first 
     46two do import the styles and the images, so they can also be used as a code 
     47example for these two steps in other languages and actual export plugins. The 
     48shell script is more of a minimalist approach to demonstrate the simplest 
     49possible use of the stylesheets. 
    3350 
    34 Documentation for the PHP and Python scripts can be generated using the "`make doc`" command. This will require [sphinx][] for Python and [phpDocumentor][] for PHP. 
     51Documentation for the PHP and Python scripts can be generated using the ``make 
     52doc`` command. This will require Sphinx_ for Python and phpDocumentor_ for PHP. 
    3553 
    36 [sphinx]: http://sphinx.pocoo.org/ 
    37 [phpDocumentor]: http://www.phpdoc.org/ 
     54.. _sphinx: http://sphinx.pocoo.org/ 
     55.. _phpDocumentor: http://www.phpdoc.org/ 
    3856 
    39 ### The python script 
     57The python script 
     58^^^^^^^^^^^^^^^^^ 
    4059 
    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: 
     60The python script is the preferred command-line script, because it currently is 
     61a little more complete than the PHP script. It depends on the following Python 
     62modules: 
    4263 
    43  * [uTidylib][] 
    44  * [lxml][] 
    45  * [PIL][] 
     64* uTidylib_ 
     65* lxml_ 
     66* PIL_ 
    4667 
    47 To get information on the script's options, run it with `--help`: 
     68To get information on the script's options, run it with ``--help``:: 
    4869 
    4970    ./xhtml2odt.py --help 
    5071 
    51 The script can be installed on the system with the `make install` command. 
     72The script can be installed on the system with the ``make install`` command. 
    5273 
    53 [uTidylib]: http://pypi.python.org/pypi/uTidylib 
    54 [lxml]: http://pypi.python.org/pypi/lxml 
    55 [PIL]: http://pypi.python.org/pypi/PIL 
     74.. _uTidylib: http://pypi.python.org/pypi/uTidylib 
     75.. _lxml: http://pypi.python.org/pypi/lxml 
     76.. _PIL: http://pypi.python.org/pypi/PIL 
    5677 
    57 ### The PHP script 
     78The PHP script 
     79^^^^^^^^^^^^^^ 
    5880 
    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][]. 
     81The PHP script can be used as an example to create an ODT export plugin for a 
     82PHP-based application. It contains comments on what you should do differently 
     83in a web-based application. If you want a real PHP-based export plugin, you can 
     84look at the code of the `Dotclear ODT export plugin`_. 
    6085 
    61 The PHP script requires the [zip][] module, and will work better with the [tidy][] extension. 
     86The PHP script requires the zip_ module, and will work better with the `tidy 
     87extension`_. 
    6288 
    63 To get information on the script's options, run it with `--help`: 
     89To get information on the script's options, run it with ``--help``:: 
    6490 
    6591    ./xhtml2odt.php --help 
    6692 
    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 
     93.. _Dotclear ODT export plugin: http://lab.dotclear.org/wiki/plugin/odt 
     94.. _zip: http://php.net/manual/en/zip.installation.php 
     95.. _tidy extension: http://php.net/manual/en/book.tidy.php 
    7096 
    7197 
    … …  
    7399----- 
    74100 
    75 The unit tests are python-based, you need to install the [nose][] python module availble from PyPI (or your distribution). 
     101The unit tests are python-based, you need to install the nose_ python module 
     102availble from PyPI (or your distribution). 
    76103 
    77 Then, just run "`nosetests tests`". 
     104Then, just run ``nosetests tests``. 
    78105 
    79 [nose]: http://pypi.python.org/pypi/nose/ 
     106.. _nose: http://pypi.python.org/pypi/nose/ 
    80107 
    81108 
    … …  
    83110---------- 
    84111 
    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) 
     112* `ODT export for Dotclear <http://lab.dotclear.org/wiki/plugin/odt>`_ 
     113* `ODT export for Trac <http://trac-hacks.org/wiki/OdtExportPlugin>`_ 
     114* `ODT export for Dokuwiki <http://www.dokuwiki.org/plugin:odt>`_ 
     115  (not using this project, but similar and by the same author) 
    88116 
    89117 
    … …  
    91119------- 
    92120 
    93 Copyright (C) 2009-2010 [Aurelien Bompard][]. 
     121Copyright (C) 2009-2010 `Aurelien Bompard`_. 
    94122 
    95 Inspired by the work on [docbook2odt][], by Roman Fordinal. 
     123Inspired by the work on docbook2odt_, by Roman Fordinal. Many thanks to him. 
    96124 
    97 [Aurelien Bompard]: http://aurelien.bompard.org/ 
    98 [docbook2odt]: http://open.comsultia.com/docbook2odf/ 
     125.. _Aurelien Bompard: http://aurelien.bompard.org/ 
     126.. _docbook2odt: http://open.comsultia.com/docbook2odf/ 
    99127 
    100128License is LGPL v2.1 or later: http://www.gnu.org/licenses/lgpl-2.1.html 
    … …  
    113141License along with this library; if not, write to the Free Software 
    114142Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA 
     143 
     144.. vim:syntax=rst 
Note: See TracChangeset for help on using the changeset viewer.