sandbox/xml2rst/README

   1 =======
   2 xml2rst
   3 =======
   4
   5 .. contents::
   6
   7 What is xml2rst?
   8 ================
   9
  10 `xml2rst` is a tool to generate reStructuredText_ syntax back from
  11 `Docutils XML`_ input. This way you can create an XML files using
  12 `Docutils XML`_ from some other format (such as ODF_) and then
  13 transform the result to reStructuredText_.
  14
  15 .. _flavor:
  16
  17 Using xml2rst
  18 =============
  19
  20 `xml2rst` is currently implemented as an XSLT_ stylesheet usable in
  21 three flavors:
  22
  23 1. ``xml2rst.py``
  24
  25    This script uses ``rst/xml2rst.xsl`` through the XSLT_ engine
  26    available through the lxml_ package [#deb-lxml]_. It also uses
  27    Python callbacks for some advanced functionality.
  28
  29    This is the preferred method of using `xml2rst` but depends on the
  30    lxml_ package. This is also what is installed normally.
  31
  32    .. [#deb-lxml] Under Debian based operating systems try ``apt-get
  33       install python-lxml``.
  34
  35    Run ``xml2rst --help`` for information on how to run it.
  36
  37 2. ``rst/xml2rst-nopy.xsl``
  38
  39    This is the core XSLT_ script without using Python. It uses EXSLT_
  40    and therefore needs an EXSLT_ capable XSLT_ processors such as
  41    xsltproc_ [#deb-xsltproc]_.
  42
  43    If you can't use ``xml2rst.py`` because you don't have lxml_ you
  44    may try this flavor. This version is no longer actively maintained,
  45    though.
  46
  47    .. [#deb-xsltproc] Under Debian based operating systems try
  48       ``apt-get install xsltproc``.
  49
  50    Run ``perldoc rst/xml2rst-nopy.xsl`` for information on how to run
  51    it.
  52
  53 3. ``rst/xml2rst-noexslt.xsl``
  54
  55    This version can be processed with every XSLT_ processor like
  56    Xalan_ [#deb-xalan]_.
  57
  58    If you can use neither ``xml2rst.py`` nor ``xml2rst-nopy.xsl`` you
  59    may try this flavor. This version is no longer actively maintained,
  60    though.
  61
  62    .. [#deb-xalan] Under Debian based operating systems try ``apt-get
  63       install xalan``.
  64
  65    Run ``perldoc rst/xml2rst-noexslt.xsl`` for information on how to
  66    run it.
  67
  68 Availability
  69 ============
  70
  71 `xml2rst` is available through the `Docutils Subversion repository`_
  72 as part of the Docutils sandbox in ``sandbox/xml2rst``.
  73
  74 Moreover you can fetch it directly from the current maintainer at
  75 http://www.merten-home.de/FreeSoftware/xml2rst/
  76
  77 Installation
  78 ============
  79
  80 After you obtained the package run ``python setup.py install``.
  81
  82 Depending on the flavor_ you choose you need to install certain
  83 packages to run `xml2rst`.
  84
  85 Copyright and license
  86 =====================
  87
  88 Copyright (C) 2005, 2006 by Stefan Merten and David Priest
  89 Copyright (C) 2009, 2010, 2011 by Stefan Merten
  90
  91 License is GPL_ v2 or later.
  92
  93 Development
  94 ===========
  95
  96 Tests
  97 -----
  98
  99 There are test suites in ``tests*``. Use filterunit_ to run tests.
 100
 101 ToDos
 102 -----
 103
 104 ``xml2rst.xsl`` and ``xml2rst.py`` contain a couple of comments marked
 105 with ``TODO`` which contain things which should be done.
 106
 107 Plans
 108 -----
 109
 110 ``xml2rst`` should become a normal reStructuredText writer. Starting
 111 with V1.0 functionality is moved to a Python based implementation.
 112
 113 .. ############################################################################
 114
 115 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 116
 117 .. _Docutils XML: http://docutils.sourceforge.net/docs/ref/doctree.html
 118
 119 .. _XSLT: http://www.w3.org/TR/1999/REC-xslt-19991116
 120
 121 .. _Docutils Subversion repository: http://docutils.sourceforge.net/docs/dev/repository.html
 122
 123 .. _xalan: http://xalan.apache.org/
 124
 125 .. _GPL: http://www.gnu.org/copyleft/gpl.html
 126
 127 .. _ODF: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office
 128
 129 .. _EXSLT: http://www.exslt.org/
 130
 131 .. _xsltproc: http://xmlsoft.org/XSLT/xsltproc2.html
 132
 133 .. _lxml: http://codespeak.net/lxml/
 134
 135 .. _filterunit: http://www.merten-home.de/FreeSoftware/filterunit/