sandbox/rst2wordml/readme.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
   7 <title>rst2wordml</title>
   8 <style type="text/css">
   9
  10 /*
  11 :Author: Jay Kint
  12 :Contact: bilbo@hobbit-hole.org
  13 :Date: $Date$
  14 :Revision: $Revision$
  15 :Copyright: This stylesheet has been placed in the public domain.
  16
  17 Cascading sheet to mimic that of "Practical Common Lisp", a clean and
  18 readable stylesheet.
  19 */
  20
  21 /* @import url(html4css.css) */
  22
  23 div.document {
  24   margin: 1in 1in;
  25   font-size: 12pt;
  26 }
  27
  28 .title {
  29   text-align: center;
  30   font-size: 24pt;
  31 }
  32
  33 h1 {
  34   font-size: 18pt;
  35 }
  36
  37 h2 {
  38   font-size: 14pt;
  39 }
  40
  41 div.footer {
  42   font-size: 8pt;
  43 }
  44
  45 table.footnote {
  46   font-size: 10pt;
  47   line-height: 1.5;
  48   margin: 0px 0px 13px 0px;
  49 }
  50
  51 td.label {
  52   font-size: 8pt;
  53 }
  54
  55 p { line-height: 1.5; }
  56
  57 .literal {
  58   font-size: 9pt;
  59 }
  60
  61 td p {
  62   margin: 0 0 13px 0;
  63 }
  64
  65 td p.last {
  66   margin: 0 0 0 0;
  67 }
  68
  69 blockquote {  line-height: 1.5; font-size: 90%;  }
  70 h1, h2, h3, h4, h5, h6 { font-family: Helvetica; }
  71 li { padding-top: 6pt; }
  72
  73 </style>
  74 </head>
  75 <body>
  76 <div class="document" id="rst2wordml">
  77 <h1 class="title">rst2wordml</h1>
  78
  79 <p><a class="reference external" href="http://s3.amazonaws.com/hobbit-hole/rst2wordml.zip">rst2wordml</a> is a <a class="reference external" href="http://docutils.sf.net/rst">reStructuredText</a> (reST) to <a class="reference external" href="http://www.microsoft.com">WordprocessingML</a> (WordML) converter.</p>
  80 <p>You can use rst2wordml to convert reST text files to WordML.  The resulting WordML file may then be loaded
  81 into MS Word 2003 or later.  You can then edit, save, or print it as any format that MS Word supports, such as
  82 PDF.</p>
  83 <div class="section" id="installation">
  84 <h1>Installation</h1>
  85 <p>Docutils should already be installed before installing rst2wordml.  This guide assumes that Python is
  86 installed at C:\Python25 and that Docutils has been installed in its default location,
  87 C:\Python25\Libs\site-packages\docutils.</p>
  88 <p>rst2wordml consists of 2 .py files and a template.xml file:</p>
  89 <table border="1" class="docutils">
  90 <colgroup>
  91 <col width="27%" />
  92 <col width="73%" />
  93 </colgroup>
  94 <thead valign="bottom">
  95 <tr><th class="head"><strong>File</strong></th>
  96 <th class="head"><strong>Location</strong></th>
  97 </tr>
  98 </thead>
  99 <tbody valign="top">
 100 <tr><td>docutils_wordml.py</td>
 101 <td>C:\Python25\Lib\site-packages\docutils\writers</td>
 102 </tr>
 103 <tr><td>rst2wordml.py</td>
 104 <td>C:\Python25\Scripts</td>
 105 </tr>
 106 <tr><td>template.xml</td>
 107 <td>Wherever the .rst file(s) to convert are.</td>
 108 </tr>
 109 </tbody>
 110 </table>
 111 <p>The template.xml file is used by rst2wordml to give default styles and formatting options to its output.  See
 112 <a class="reference internal" href="#options">Options</a> for information on custom template files.</p>
 113 </div>
 114 <div class="section" id="features">
 115 <h1>Features</h1>
 116 <p>Currently not all the features supported by reST are converted by the rst2wordml converter.  Here is a list of
 117 features and their level of support:</p>
 118 <ul class="simple">
 119 <li><strong>Impl</strong> means a feature is already implemented.</li>
 120 <li><strong>Unknown</strong> means a feature might work but hasn't been tested.</li>
 121 <li><strong>Next</strong> means that it should be coming in the near future.</li>
 122 <li><strong>None</strong> means that I have no intention of supporting this feature, although I will take patches to support
 123 the feature.</li>
 124 </ul>
 125 <table border="1" class="docutils">
 126 <colgroup>
 127 <col width="51%" />
 128 <col width="11%" />
 129 <col width="15%" />
 130 <col width="11%" />
 131 <col width="11%" />
 132 </colgroup>
 133 <thead valign="bottom">
 134 <tr><th class="head"><strong>Feature</strong></th>
 135 <th class="head"><strong>Impl</strong></th>
 136 <th class="head"><strong>Unknown</strong></th>
 137 <th class="head"><strong>Next</strong></th>
 138 <th class="head"><strong>None</strong></th>
 139 </tr>
 140 </thead>
 141 <tbody valign="top">
 142 <tr><td>Paragraphs</td>
 143 <td>X</td>
 144 <td>&nbsp;</td>
 145 <td>&nbsp;</td>
 146 <td>&nbsp;</td>
 147 </tr>
 148 <tr><td>Inline markup (bold and italic)</td>
 149 <td>X</td>
 150 <td>&nbsp;</td>
 151 <td>&nbsp;</td>
 152 <td>&nbsp;</td>
 153 </tr>
 154 <tr><td>Hyperlinks</td>
 155 <td>X</td>
 156 <td>&nbsp;</td>
 157 <td>&nbsp;</td>
 158 <td>&nbsp;</td>
 159 </tr>
 160 <tr><td>Inline literals</td>
 161 <td>X</td>
 162 <td>&nbsp;</td>
 163 <td>&nbsp;</td>
 164 <td>&nbsp;</td>
 165 </tr>
 166 <tr><td>Bullet Lists</td>
 167 <td>X</td>
 168 <td>&nbsp;</td>
 169 <td>&nbsp;</td>
 170 <td>&nbsp;</td>
 171 </tr>
 172 <tr><td>Enumerated Lists</td>
 173 <td>X</td>
 174 <td>&nbsp;</td>
 175 <td>&nbsp;</td>
 176 <td>&nbsp;</td>
 177 </tr>
 178 <tr><td>Definition Lists</td>
 179 <td>X</td>
 180 <td>&nbsp;</td>
 181 <td>&nbsp;</td>
 182 <td>&nbsp;</td>
 183 </tr>
 184 <tr><td>Field Lists</td>
 185 <td>&nbsp;</td>
 186 <td>&nbsp;</td>
 187 <td>X</td>
 188 <td>&nbsp;</td>
 189 </tr>
 190 <tr><td>Option Lists</td>
 191 <td>&nbsp;</td>
 192 <td>&nbsp;</td>
 193 <td>&nbsp;</td>
 194 <td>X</td>
 195 </tr>
 196 <tr><td>Literal Blocks</td>
 197 <td>X</td>
 198 <td>&nbsp;</td>
 199 <td>&nbsp;</td>
 200 <td>&nbsp;</td>
 201 </tr>
 202 <tr><td>Line Blocks</td>
 203 <td>&nbsp;</td>
 204 <td>&nbsp;</td>
 205 <td>X</td>
 206 <td>&nbsp;</td>
 207 </tr>
 208 <tr><td>Block Quotes</td>
 209 <td>X</td>
 210 <td>&nbsp;</td>
 211 <td>&nbsp;</td>
 212 <td>&nbsp;</td>
 213 </tr>
 214 <tr><td>Doctest Blocks</td>
 215 <td>&nbsp;</td>
 216 <td>&nbsp;</td>
 217 <td>&nbsp;</td>
 218 <td>X</td>
 219 </tr>
 220 <tr><td>Tables</td>
 221 <td>X</td>
 222 <td>&nbsp;</td>
 223 <td>&nbsp;</td>
 224 <td>&nbsp;</td>
 225 </tr>
 226 <tr><td>Images <a class="footnote-reference" href="#id3" id="id1">[1]</a></td>
 227 <td>X</td>
 228 <td>&nbsp;</td>
 229 <td>&nbsp;</td>
 230 <td>&nbsp;</td>
 231 </tr>
 232 <tr><td>Footnotes <a class="footnote-reference" href="#id4" id="id2">[2]</a></td>
 233 <td>X</td>
 234 <td>&nbsp;</td>
 235 <td>&nbsp;</td>
 236 <td>&nbsp;</td>
 237 </tr>
 238 <tr><td>Citations</td>
 239 <td>X</td>
 240 <td>&nbsp;</td>
 241 <td>&nbsp;</td>
 242 <td>&nbsp;</td>
 243 </tr>
 244 <tr><td>Directives</td>
 245 <td>&nbsp;</td>
 246 <td>X</td>
 247 <td>&nbsp;</td>
 248 <td>&nbsp;</td>
 249 </tr>
 250 <tr><td>Substitutions</td>
 251 <td>X</td>
 252 <td>&nbsp;</td>
 253 <td>&nbsp;</td>
 254 <td>&nbsp;</td>
 255 </tr>
 256 <tr><td>Comments</td>
 257 <td>X</td>
 258 <td>&nbsp;</td>
 259 <td>&nbsp;</td>
 260 <td>&nbsp;</td>
 261 </tr>
 262 </tbody>
 263 </table>
 264 <p>This table isn't necessarily exhaustive, though I did go through the specification to come up with this list.</p>
 265 </div>
 266 <div class="section" id="options">
 267 <h1>Options</h1>
 268 <p>For now rst2wordml only supports a single option, --template=&lt;template xml file&gt;.  The default is a file
 269 called template.xml.  See <a class="reference internal" href="#implementation">Implementation</a> for information how to create a template file of your own if
 270 template.xml doesn't meet your needs.</p>
 271 </div>
 272 <div class="section" id="unit-tests">
 273 <h1>Unit Tests</h1>
 274 <p>Included in this release are the beginnings of unit tests, included in the test subdirectory.  Each test
 275 stands on its own as a script and uses doctest to generate a document from the default template.xml file.  To
 276 run each test, just type python &lt;test name&gt;.  If the test generates no output, it passed.</p>
 277 </div>
 278 <div class="section" id="implementation">
 279 <h1>Implementation</h1>
 280 <p>There really is no magic to the implementation of rst2wordml.  The good folks at docutils have factored reST
 281 into a nice set of classes.  To format a new output type for a reST doc, one only need create a new subclass
 282 of Writer class, which I did in the docutils_wordml.py file.</p>
 283 <p>Also, rst2wordml.py is a simple front end for instantiating the conversion process from the command line.</p>
 284 <p>rst2wordml uses a template file similar in concept to the CSS file used by the HTML converter.  The template
 285 file contains the default formatting properties for items such as styles, tables, and lists.  It is
 286 theoretically easy to create a new look for your documents by opening template.xml in MS Word, adjusting the
 287 styles and then saving the file.  Unfortunately, theory doesn't apply here.</p>
 288 <p>If you open template.xml, you'll perhaps notice buried in all the XML, three unique tags not supported by
 289 WordML: &lt;w:rest&gt;, &lt;w:rstlists&gt;, and &lt;w:rstlistdefs&gt;.  These are used by rst2wordml to insert generated data.
 290 Otherwise, the generated output is identical to the template.xml file.</p>
 291 <p>The template file should contain the styles Normal, DefaultParagraphFont, Heading 1, Heading 2, Heading 3,
 292 LiteralBlock, Endnote Text, and Endnote Reference.  Also, list styles for bullet lists and enumerated lists
 293 need to be included.</p>
 294 <p>If you should wish to create your own template.xml file, the easiest thing to do is create a document in MS
 295 Word with these styles and save it out as WordML.  Next, open it in a text editor, and look for the places
 296 where the special tags appear in the original template.xml and place the same tags in your file.</p>
 297 </div>
 298 <div class="section" id="literate-programming-with-rest">
 299 <h1>Literate Programming with reST</h1>
 300 <p>One of the reasons that I started writing this converter was to help me document one of the (other) projects
 301 I'm working on.  As I was writing the docs for that project, I was consistently copying and pasting code
 302 samples into literal blocks.  Of course, as the code changed, so did the amount of work keeping it in sync
 303 with the docs.  Literate programming seemed to provide exactly what I needed, code and docs together.</p>
 304 <p>I had seen literate programming used in the book <a class="reference external" href="http://www.amazon.com/Physically-Based-Rendering-Implementation-Interactive/dp/012553180X/ref=pd_bbs_sr_1/103-3091427-3166253?ie=UTF8">Physically Based Rendering</a> and I thought it would be cool
 305 to have the ability to write documentation and code in a single file.  After looking at some of the literate
 306 programming tools, I found <a class="reference external" href="http://pylit.berlios.de/index.html">PyLit</a>, a <em>semi-literate programming</em> module that works with reST.  reST has
 307 everything I need in a markup without having to really learn a markup language.  PyLit can do the code
 308 extraction, rst2html does the conversion to web pages, and rst2wordml can convert to Word files, from which I
 309 can easily make printed copoies or even create PDF files.</p>
 310 <table class="docutils footnote" frame="void" id="id3" rules="none">
 311 <colgroup><col class="label" /><col /></colgroup>
 312 <tbody valign="top">
 313 <tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Images are centered and the dimensions are extracted if the Python Imaging Library is installed.
 314 Otherwise they must be supplied by the author or they default to 100x100.</td></tr>
 315 </tbody>
 316 </table>
 317 <table class="docutils footnote" frame="void" id="id4" rules="none">
 318 <colgroup><col class="label" /><col /></colgroup>
 319 <tbody valign="top">
 320 <tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>Footnotes in rst2wordml are implemented as end notes to better match the output of the HTML converter.</td></tr>
 321 </tbody>
 322 </table>
 323 </div>
 324 </div>
 325 </body>
 326 </html>