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