sandbox/xml2rst/README.rst

   1 =======
   2 xml2rst
   3 =======
   4
   5 .. contents::
   6
   7 ----------------
   8 What is xml2rst?
   9 ----------------
  10
  11 `xml2rst` is a tool to generate reStructuredText_ syntax back from
  12 `Docutils XML`_ input. This way one can create XML files using
  13 `Docutils XML`_ from some other format (such as ODF_) and then
  14 transform them to reStructuredText_.
  15
  16 It is currently implemented as an XSLT_ stylesheet.
  17
  18 ------------
  19 Availability
  20 ------------
  21
  22 `xml2rst` is available through the `Docutils Subversion repository`_
  23 as part of the Docutils sandbox at
  24 http://svn.berlios.de/viewcvs/docutils/trunk/sandbox/xml2rst
  25
  26 Moreover you can fetch it directly from the current maintainer at
  27 http://www.merten-home.de/FreeSoftware/xml2rst/
  28
  29 ------------
  30 Installation
  31 ------------
  32
  33 `xml2rst` needs no special installation. Just use it with your
  34 favorite XSLT processor such as Xalan_. Check Synopsis_ for
  35 instructions how to do this.
  36
  37 ---------------------
  38 Copyright and license
  39 ---------------------
  40
  41 Copyright (C) 2005, 2006 by Stefan Merten and David Priest
  42
  43 License is GPL_ v2 or later.
  44
  45 -------------
  46 Documentation
  47 -------------
  48
  49 Synopsis
  50 ========
  51
  52 ``Xalan`` `docutils.xml` ``xml2rst.xsl``
  53
  54 ``testXSLT`` ``-xsl`` ``xml2rst.xsl`` ``-in`` `docutils.xml`
  55
  56 Options
  57 =======
  58
  59 The following options are supported. They are XSLT parameters for the
  60 whole script and must be given to the XSLT processor by the respective
  61 option (Xalan: ``-p``, testXSLT: ``-param``).
  62
  63 -param ``adornment`` `adornment_configuration`
  64   Configures title markup to use so different styles can be requested
  65   easily.
  66
  67   The value of the parameter must be a string made up of a sequence of
  68   character pairs. The first character of a pair is "o" (overline) or
  69   "u" (underline) and the second character is the character to use for
  70   the markup.
  71
  72   The first and the second character pair is used for document title
  73   and subtitle, the following pairs are used for section titles where
  74   the third pair is used for the top level section title.
  75
  76   Defaults to ``o=o-u=u-u~u:u.u``\ `````.
  77
  78 -param ``fold`` `folding_length`
  79   Configures whether long text lines in paragraphs should be folded
  80   and to which length. This option is for input not coming from reST
  81   which may have no internal line feeds in plain text strings.
  82
  83   If folding is enabled text strings which are not in a linefeed
  84   preserving context are first white-space normalized and then broken
  85   according to the folding rules. Folding rules put out the first word
  86   and continue to do so with the following words unless the next word
  87   would cross the folding boundary. Words are delimited by
  88   white-space.
  89
  90   Defaults to ``0``, i.e. no folding.
  91
  92 Unsupported features
  93 ====================
  94
  95 It is generally not possible to create an exact reproduction of an
  96 original reStructuredText source from an intermediate XML file. The
  97 reason is that Docutils transports pretty much but not all information
  98 of the original source into the XML. Also the sequence of things is
  99 changed sometimes.
 100
 101 However, the coverage of Docutils features of ``xml2rst`` is pretty
 102 good. A few minor features are not supported:
 103
 104 * ``.. contents:: :local:``
 105
 106 * Fully minimized style for literal blocks
 107
 108 * ``<raw>`` element as inline element
 109
 110 * Substitution references for ``replace::`` substitutions
 111
 112 * Counting roman numbers in enumerated lists
 113
 114 * Special table types like ``list-table::`` and ``csv-table::``
 115
 116 Example
 117 =======
 118
 119 For a roundtrip try::
 120
 121   rst2xml your_file.rst | xalan -xsl xml2rst.xsl | diff - your_file.rst
 122
 123 -----------
 124 Development
 125 -----------
 126
 127 Docutils version 0.3.7
 128 ======================
 129
 130 `xml2rst` has been developed for Docutils v0.3.7. It does not
 131 necessarily reflect all new features which became part of Docutils
 132 since that version.
 133
 134 Check the big comment at the beginning of the file to find out what
 135 needs consideration.
 136
 137 ToDos
 138 =====
 139
 140 The ``xml2rst.xsl`` contains a couple of comments marked with ``TODO``
 141 which contain things which should be done.
 142
 143 .. ############################################################################
 144
 145 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 146
 147 .. _Docutils XML: http://docutils.sourceforge.net/docs/ref/doctree.html
 148
 149 .. _XSLT: http://www.w3.org/TR/1999/REC-xslt-19991116
 150
 151 .. _Docutils Subversion repository: http://docutils.sourceforge.net/docs/dev/repository.html
 152
 153 .. _Xalan: http://xalan.apache.org/
 154
 155 .. _GPL: http://www.gnu.org/copyleft/gpl.html
 156
 157 .. _ODF: http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office