sandbox/odf2docutils/README

   1 ============
   2 odf2docutils
   3 ============
   4
   5 .. contents::
   6
   7 What is odf2docutils?
   8 =====================
   9
  10 `odf2docutils` is a tool to generate `Docutils XML`_ from `Open
  11 Document Format`_ (ODF_). This way you can create a `Docutils XML`_
  12 file from ODF_ input and then transform the result to
  13 reStructuredText_ by using `xml2rst`_.
  14
  15 Using odf2docutils
  16 ==================
  17
  18 Use `odf2docutils` by calling ``odf2docutils.py`` on an ODF_ file. Run
  19 ``odf2docutils --help`` for more information.
  20
  21 Availability
  22 ============
  23
  24 `odf2docutils` is available through the `Docutils Subversion repository`_
  25 as part of the Docutils sandbox in ``sandbox/odf2docutils``.
  26
  27 Moreover you can fetch it directly from the current maintainer at
  28 http://www.merten-home.de/FreeSoftware/odf2docutils/
  29
  30 Installation
  31 ============
  32
  33 `odf2docutils` depends on the lxml_ package [#deb-lxml]_. Make sure
  34 this package is installed before running `odf2docutils`.
  35
  36 After you obtained the package run ``python setup.py install``.
  37
  38 .. [#deb-lxml] Under Debian based operating systems try ``apt-get
  39    install python-lxml``.
  40
  41 Copyright and license
  42 =====================
  43
  44 Copyright (C) 2013 by Stefan Merten
  45
  46 License is GPL_ v2 or later.
  47
  48 Development
  49 ===========
  50
  51 Tests
  52 -----
  53
  54 There are test suites in ``tests``. Use filterunit_ to run tests.
  55
  56 ToDos
  57 -----
  58
  59 So far only a small subset of ODF_ is supported. This may change over
  60 time.
  61
  62 Implementation
  63 --------------
  64
  65 The core of `odf2docutils` is implemented as an XSLT_ stylesheet
  66 called ``odf2docutils.xsl``. So far the script ``odf2docutils.py`` is
  67 only needed for handling ODF_ files and run the XSLT_ processor.
  68
  69 .. ############################################################################
  70
  71 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  72
  73 .. _Docutils XML: http://docutils.sourceforge.net/docs/ref/doctree.html
  74
  75 .. _XSLT: http://www.w3.org/TR/1999/REC-xslt-19991116
  76
  77 .. _Docutils Subversion repository: http://docutils.sourceforge.net/docs/dev/repository.html
  78
  79 .. _GPL: http://www.gnu.org/copyleft/gpl.html
  80
  81 .. _Open Document Format:
  82 .. _ODF: https://www.oasis-open.org/standards#opendocumentv1.2
  83
  84 .. _lxml: http://lxml.de/
  85
  86 .. _filterunit: http://www.merten-home.de/FreeSoftware/filterunit/
  87
  88 .. _xml2rst: http://www.merten-home.de/FreeSoftware/xml2rst/