sandbox/rst2wordml/readme.rst

   1 ----------
   2 rst2wordml
   3 ----------
   4
   5 `rst2wordml <http://s3.amazonaws.com/hobbit-hole/rst2wordml.zip>`__ is a `reStructuredText
   6 <http://docutils.sf.net/rst>`__ (reST) to `WordprocessingML <http://www.microsoft.com>`__ (WordML) converter.
   7
   8 You can use rst2wordml to convert reST text files to WordML.  The resulting WordML file may then be loaded
   9 into MS Word 2003 or later.  You can then edit, save, or print it as any format that MS Word supports, such as
  10 PDF.
  11
  12 Installation
  13 ------------
  14
  15 Docutils should already be installed before installing rst2wordml.  This guide assumes that Python is
  16 installed at C:\\Python25 and that Docutils has been installed in its default location,
  17 C:\\Python25\\Libs\\site-packages\\docutils.
  18
  19 rst2wordml consists of 2 .py files and a template.xml file:
  20
  21 +--------------------+-----------------------------------------------------+
  22 | **File**           | **Location**                                        |
  23 +====================+=====================================================+
  24 | docutils_wordml.py | C:\\Python25\\Lib\\site-packages\\docutils\\writers |
  25 +--------------------+-----------------------------------------------------+
  26 | rst2wordml.py      | C:\\Python25\\Scripts                               |
  27 +--------------------+-----------------------------------------------------+
  28 | template.xml       | Wherever the .rst file(s) to convert are.           |
  29 +--------------------+-----------------------------------------------------+
  30
  31 The template.xml file is used by rst2wordml to give default styles and formatting options to its output.  See
  32 Options_ for information on custom template files.
  33
  34 Features
  35 --------
  36
  37 Currently not all the features supported by reST are converted by the rst2wordml converter.  Here is a list of
  38 features and their level of support:
  39
  40 - **Impl** means a feature is already implemented.
  41 - **Unknown** means a feature might work but hasn't been tested.
  42 - **Next** means that it should be coming in the near future.
  43 - **None** means that I have no intention of supporting this feature, although I will take patches to support
  44   the feature.
  45
  46 +-------------------------------------+--------+-----------+--------+--------+
  47 |**Feature**                          |**Impl**|**Unknown**|**Next**|**None**|
  48 +=====================================+========+===========+========+========+
  49 |Paragraphs                           |   X    |           |        |        |
  50 +-------------------------------------+--------+-----------+--------+--------+
  51 |Inline markup (bold and italic)      |   X    |           |        |        |
  52 +-------------------------------------+--------+-----------+--------+--------+
  53 |Hyperlinks                           |   X    |           |        |        |
  54 +-------------------------------------+--------+-----------+--------+--------+
  55 |Inline literals                      |   X    |           |        |        |
  56 +-------------------------------------+--------+-----------+--------+--------+
  57 |Bullet Lists                         |   X    |           |        |        |
  58 +-------------------------------------+--------+-----------+--------+--------+
  59 |Enumerated Lists                     |   X    |           |        |        |
  60 +-------------------------------------+--------+-----------+--------+--------+
  61 |Definition Lists                     |   X    |           |        |        |
  62 +-------------------------------------+--------+-----------+--------+--------+
  63 |Field Lists                          |        |           |   X    |        |
  64 +-------------------------------------+--------+-----------+--------+--------+
  65 |Option Lists                         |        |           |        |   X    |
  66 +-------------------------------------+--------+-----------+--------+--------+
  67 |Literal Blocks                       |   X    |           |        |        |
  68 +-------------------------------------+--------+-----------+--------+--------+
  69 |Line Blocks                          |        |           |   X    |        |
  70 +-------------------------------------+--------+-----------+--------+--------+
  71 |Block Quotes                         |   X    |           |        |        |
  72 +-------------------------------------+--------+-----------+--------+--------+
  73 |Doctest Blocks                       |        |           |        |   X    |
  74 +-------------------------------------+--------+-----------+--------+--------+
  75 |Tables                               |   X    |           |        |        |
  76 +-------------------------------------+--------+-----------+--------+--------+
  77 |Images [#]_                          |   X    |           |        |        |
  78 +-------------------------------------+--------+-----------+--------+--------+
  79 |Footnotes [#]_                       |   X    |           |        |        |
  80 +-------------------------------------+--------+-----------+--------+--------+
  81 |Citations                            |   X    |           |        |        |
  82 +-------------------------------------+--------+-----------+--------+--------+
  83 |Directives                           |        |    X      |        |        |
  84 +-------------------------------------+--------+-----------+--------+--------+
  85 |Substitutions                        |   X    |           |        |        |
  86 +-------------------------------------+--------+-----------+--------+--------+
  87 |Comments                             |   X    |           |        |        |
  88 +-------------------------------------+--------+-----------+--------+--------+
  89
  90 This table isn't necessarily exhaustive, though I did go through the specification to come up with this list.
  91
  92 Options
  93 -------
  94
  95 For now rst2wordml only supports a single option, --template=<template xml file>.  The default is a file
  96 called template.xml.  See Implementation_ for information how to create a template file of your own if
  97 template.xml doesn't meet your needs.
  98
  99 Unit Tests
 100 ----------
 101
 102 Included in this release are the beginnings of unit tests, included in the test subdirectory.  Each test
 103 stands on its own as a script and uses doctest to generate a document from the default template.xml file.  To
 104 run each test, just type python <test name>.  If the test generates no output, it passed.
 105
 106 Implementation
 107 --------------
 108
 109 There really is no magic to the implementation of rst2wordml.  The good folks at docutils have factored reST
 110 into a nice set of classes.  To format a new output type for a reST doc, one only need create a new subclass
 111 of Writer class, which I did in the docutils_wordml.py file.
 112
 113 Also, rst2wordml.py is a simple front end for instantiating the conversion process from the command line.
 114
 115 rst2wordml uses a template file similar in concept to the CSS file used by the HTML converter.  The template
 116 file contains the default formatting properties for items such as styles, tables, and lists.  It is
 117 theoretically easy to create a new look for your documents by opening template.xml in MS Word, adjusting the
 118 styles and then saving the file.  Unfortunately, theory doesn't apply here.
 119
 120 If you open template.xml, you'll perhaps notice buried in all the XML, three unique tags not supported by
 121 WordML: <w:rest>, <w:rstlists>, and <w:rstlistdefs>.  These are used by rst2wordml to insert generated data.
 122 Otherwise, the generated output is identical to the template.xml file.
 123
 124 The template file should contain the styles Normal, DefaultParagraphFont, Heading 1, Heading 2, Heading 3,
 125 LiteralBlock, Endnote Text, and Endnote Reference.  Also, list styles for bullet lists and enumerated lists
 126 need to be included.
 127
 128 If you should wish to create your own template.xml file, the easiest thing to do is create a document in MS
 129 Word with these styles and save it out as WordML.  Next, open it in a text editor, and look for the places
 130 where the special tags appear in the original template.xml and place the same tags in your file.
 131
 132 Literate Programming with reST
 133 ------------------------------
 134
 135 One of the reasons that I started writing this converter was to help me document one of the (other) projects
 136 I'm working on.  As I was writing the docs for that project, I was consistently copying and pasting code
 137 samples into literal blocks.  Of course, as the code changed, so did the amount of work keeping it in sync
 138 with the docs.  Literate programming seemed to provide exactly what I needed, code and docs together.
 139
 140 I had seen literate programming used in the book `Physically Based Rendering`_ and I thought it would be cool
 141 to have the ability to write documentation and code in a single file.  After looking at some of the literate
 142 programming tools, I found PyLit_, a *semi-literate programming* module that works with reST.  reST has
 143 everything I need in a markup without having to really learn a markup language.  PyLit can do the code
 144 extraction, rst2html does the conversion to web pages, and rst2wordml can convert to Word files, from which I
 145 can easily make printed copoies or even create PDF files.
 146
 147
 148 .. [#] Images are centered and the dimensions are extracted if the Python Imaging Library is installed.
 149        Otherwise they must be supplied by the author or they default to 100x100.
 150
 151 .. [#] Footnotes in rst2wordml are implemented as end notes to better match the output of the HTML converter.
 152
 153 .. _`Physically Based Rendering`: http://www.amazon.com/Physically-Based-Rendering-Implementation-Interactive/dp/012553180X/ref=pd_bbs_sr_1/103-3091427-3166253?ie=UTF8
 154
 155 .. _`PyLit`: http://pylit.berlios.de/index.html