sandbox/xml2rst/README.rst

   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 one can create XML files using
  12 `Docutils XML`_ from some other format (such as ODF_) and then
  13 transform them to reStructuredText_.
  14
  15 .. _flavor:
  16
  17 It is currently implemented as an XSLT_ stylesheet coming in three
  18 flavors:
  19
  20 1. ``xml2rst.xsl``
  21
  22    This version uses EXSLT_ and should be functionally equivalent to
  23    the old version. Because using EXSLT_ this version needs EXSLT_
  24    capable XSLT_ processors such as xsltproc_ [#deb-xsltproc]_.
  25
  26    This version is currently maintained.
  27
  28    .. [#deb-xsltproc] Under Debian based operating systems try
  29       ``apt-get install xsltproc``
  30
  31 2. ``xml2rst.py``
  32
  33    This script uses ``xml2rst.xsl`` but through the XSLT_ engine
  34    available through the lxml_ package [#deb-lxml]_.
  35
  36    .. [#deb-lxml] Under Debian based operating systems try ``apt-get
  37       install python-lxml``
  38
  39 3. ``xml2rst-noexslt.xsl``
  40
  41    This version can be processed with every XSLT_ processor like
  42    Xalan_ [#deb-xalan]_.
  43
  44    This version is no longer maintained, though.
  45
  46    .. [#deb-xalan] Under Debian based operating systems try ``apt-get
  47       install xalan``
  48
  49 Availability
  50 ============
  51
  52 `xml2rst` is available through the `Docutils Subversion repository`_
  53 as part of the Docutils sandbox at
  54 http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/xml2rst
  55
  56 Moreover you can fetch it directly from the current maintainer at
  57 http://www.merten-home.de/FreeSoftware/xml2rst/
  58
  59 Installation
  60 ============
  61
  62 Depending on the flavor_ you choose you need to install certain
  63 packages to run `xml2rst`. If using an XSLT_ processor try ``perldoc
  64 xml2rst.xsl`` for instructions how to run it. If using the script try
  65 ``perldoc xml2rst.py``.
  66
  67 Copyright and license
  68 =====================
  69
  70 Copyright (C) 2005, 2006 by Stefan Merten and David Priest
  71 Copyright (C) 2009, 2010 by Stefan Merten
  72
  73 License is GPL_ v2 or later.
  74
  75 Example
  76 =======
  77
  78 For a roundtrip try::
  79
  80   rst2xml your_file.rst your_file.xml ; xml2rst.py your_file.xml | diff - your_file.rst
  81
  82 Development
  83 ===========
  84
  85 ToDos
  86 -----
  87
  88 ``xml2rst.xsl`` and ``xml2rst.py`` contain a couple of comments marked
  89 with ``TODO`` which contain things which should be done.
  90
  91 .. ############################################################################
  92
  93 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
  94
  95 .. _Docutils XML: http://docutils.sourceforge.net/docs/ref/doctree.html
  96
  97 .. _XSLT: http://www.w3.org/TR/1999/REC-xslt-19991116
  98
  99 .. _Docutils Subversion repository: http://docutils.sourceforge.net/docs/dev/repository.html
 100
 101 .. _xalan: http://xalan.apache.org/
 102
 103 .. _GPL: http://www.gnu.org/copyleft/gpl.html
 104
 105 .. _ODF: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office
 106
 107 .. _EXSLT: http://www.exslt.org/
 108
 109 .. _xsltproc: http://xmlsoft.org/XSLT/xsltproc2.html
 110
 111 .. _lxml: http://codespeak.net/lxml/