sandbox/OpenDocument/README.txt

   1 =========
   2 OdtWriter
   3 =========
   4
   5
   6 What is odtwriter?
   7 ==================
   8
   9 odtwriter is a back-end, writer for Docutils.  odtwriter produces
  10 a .odt file that obeys the standards for ODF (Open Document
  11 Format).  These files are usable in oowriter which is part of
  12 OpenOffice.
  13
  14
  15 Where to Find It
  16 ================
  17
  18 odtwriter is available through SVN (Subversion).  It is under
  19 sandbox/OpenDocument.  See:
  20
  21 - http://docutils.sourceforge.net/docs/dev/repository.html
  22
  23 - http://svn.berlios.de/viewcvs/docutils/trunk/
  24
  25
  26 Documentation
  27 =============
  28
  29 Documentation is in docs/odtwriter.txt/html.
  30
  31
  32 Additional Information
  33 ======================
  34
  35 For more information on Docutils, see: http://docutils.sourceforge.net/
  36
  37
  38 History
  39 =======
  40
  41 2009/03/01
  42 ---------------
  43
  44 Improvements to images and figures -- (1) Images and figures not
  45 text wrapped by default.  (2) Added Docutils class "wrap" to force
  46 wrapping of images and figures.
  47
  48
  49 2008/10/28 -- Version 1.3d
  50 --------------------------
  51
  52 Added command line flags --endnotes-end-doc and
  53 --no-endnotes-end-doc to place footnotes and citations at the end
  54 of the document instead of at the end of the page.  Generates
  55 endnotes instead of footnotes.
  56
  57 A fix to table generation.
  58
  59
  60 2008/10/23 -- Version 1.3c
  61 --------------------------
  62
  63 Fixes for line blocks.  These are now indented correctly, I
  64 believe, even when inside a block quote.  There are new styles for
  65 line blocks (rststyle-lineblock1, ...).  See the doc.
  66
  67 Fixes to footnotes.  Auto-numbered and auto-symbol footnotes seem
  68 to work correctly now.  There is a constant (footnote_chars)
  69 containing the symbols (\*, \**, \***, ++, etc).
  70
  71 Added support for citations.
  72
  73 Fixed sections -- Now start at correct level.
  74
  75 Added styles rststyle-title and rststyle-subtitle.
  76
  77 Various source code clean-ups.
  78
  79 Added style rststyle-footnote and rststyle-citation.
  80
  81
  82 2008/07/08 -- Version 1.3b
  83 --------------------------
  84
  85 Added support for sub-script and super-script (:sub: and :sup:).
  86
  87 Added support for classifier on definition list terms.
  88
  89
  90 2008/07/03 -- Version 1.3a
  91 --------------------------
  92
  93 Added support for the meta directive.  See docs.
  94
  95 Added support for additional ``visit_``/``depart_`` methods.
  96
  97 Regularized some of the methods that generated fields: revision,
  98 version, date, address, contact, copyright, organization, etc.
  99
 100 Added more control for control of paper size, thanks to Michael
 101 Schutte:
 102
 103 1. __init__.py attempts to run paperconf.  If paperconf succeeds
 104    and if the styles.odt file does not contain paper size, the size
 105    is inserted into the styles.xml in the generated document.
 106
 107 2. Added rst2odt_prepstyles.py script -- Drop page size
 108    specifications from styles.xml in STYLE_FILE.odt.
 109
 110 Added tools/rst2odt_prepstyles.py to the distribution.
 111
 112
 113
 114 2008/04/18 -- Version 1.2b
 115 --------------------------
 116
 117 Increased maximum header levels.  Added new header styles
 118 rststyle-heading6 and rststyle-heading7 to styles.odt.
 119
 120 Fixed bug related to lists inside of definition of a definition
 121 list.  Fixed handling of indentation levels.  Thanks to Stefan
 122 Merten for help with this.
 123
 124
 125 2008/03/20 -- Version 1.2a, again
 126 ---------------------------------
 127
 128 Fix for footnotes -- Removed extra space between footnote reference
 129 and preceding text.
 130
 131 Added support for the Docutils raw directive.  Raw XML content is
 132 now parsed to produce an ElementTree subtree which is inserted
 133 into the ODF content tree.  See the doc (section "The raw
 134 directive") for a few notes on using the raw directive with
 135 odtwriter.
 136
 137
 138 2008/01/06 -- Version 1.2a
 139 --------------------------
 140
 141 Added Stefan Merten's implementation of custom style names.
 142
 143 A few miscellaneous fixes, e.g. some related to the Pygments
 144 source code highlighting.
 145
 146 Added an empty/do-nothing implementation for the raw directive.
 147
 148
 149 2008/01/06 -- Version 1.1a, again
 150 ---------------------------------
 151
 152 Fixes to figures and images -- The caption on a figure is
 153 displayed below the image in a space that is the same width as the
 154 image.  Also did some clean-up to the code that determines the
 155 size of images and the code that generates them.
 156
 157
 158 2007/12/20 -- Version 1.1a, again
 159 ---------------------------------
 160
 161 Removed extra numbers in table of contents and section titles when
 162 the sectnum directive is used.
 163
 164
 165 2007/12/20 -- Version 1.1a
 166 --------------------------
 167
 168 Another image fix -- If PIL is installed and if the height and
 169 width of an image are not specified in an image directive and if
 170 the scale is specified in an image, then odtwriter attempts to use
 171 PIL/Image to determine the size (height, width) of the image before
 172 scaling.
 173
 174 Document title: (1) The document title and top level section
 175 headings were both being given style rststyle-heading1.  Now,
 176 document title gets rststyle-heading1 and top level sections get
 177 rststyle-heading2.  Basically, section heading levels are bumped up
 178 by 1. (2) The command line flag --title is now implemented.  It
 179 overrides the document title in the source document if present.
 180
 181
 182 2007/12/19 -- Version 1.1a
 183 --------------------------
 184
 185 Minor fixes for images.  But, we still cannot position an image
 186 correctly *within* a paragraph.
 187
 188
 189 2007/12/07 -- Version 1.1a
 190 --------------------------
 191
 192 Fixes to sourcecode highlighting.
 193
 194 Fixes to images:
 195
 196 - Eliminated storing the same image multiple times in the .odt file.
 197
 198 - Fix to images defined in image substitution definitions.
 199
 200
 201 2007/10/05 -- Version 1.1a
 202 --------------------------
 203
 204 Adapted odtwriter to the stronger XML namespace handling in lxml 2.0.
 205
 206
 207 2007/10/01 -- Version 1.0e, again
 208 ---------------------------------
 209
 210 A significant improvement to the content generated for literal
 211 blocks thanks to a patch from Johan Holmberg.
 212
 213
 214 2007/03/14 -- Version 1.0e
 215 --------------------------
 216
 217 Fix so that rst.Directive class is not used for older versions of
 218 Docutils.  They do not implement that class.
 219
 220 Fix so that if ElementTree is in the standard Python library,
 221 odtwriter will also look for it there.
 222
 223
 224 2007/03/14 -- Version 1.0d
 225 --------------------------
 226
 227 Added support for highlights block/directive.
 228
 229 Fixed styles in highlights, epigraphs, and blockquotes.  Bullet and
 230 enum lists now have their own styles in each of these block types.
 231
 232
 233 2007/03/12 -- Version 1.0d
 234 --------------------------
 235
 236 Added support for epigraph and the associated attribution.  Added
 237 and fixed styles for epigraph, attribution, and block-quote.
 238
 239 Added support for line-block.  Added style for line blocks.
 240
 241 Added support for substitution (replace directive).  Actually, the
 242 substitution is done before odtwriter starts walking the tree.
 243 But, I added the visit/depart methods so as to eliminate the error
 244 messages.
 245
 246 Fixed visit_Text so that it can add *multiple* text nodes that are
 247 all children of the same node.
 248
 249
 250 2007/03/09 -- Version 1.0d
 251 --------------------------
 252
 253 Fix for non-utf-8 character sets, e.g. Russian.
 254
 255
 256 2007/03/08 -- Version 1.0d
 257 --------------------------
 258
 259 Added support for footnotes.
 260
 261
 262 2007/02/21 -- Version 1.0c
 263 --------------------------
 264
 265 Fixed headers and footers.  Added support for references/URLs.
 266
 267
 268 2007/02/20 -- Version 1.0c
 269 --------------------------
 270
 271 Renamed directive "syntaxhighlight" to "sourcecode".  Also changed
 272 to a single argument, which can be "on" or "off" or <lexer-name>.
 273
 274
 275 2007/01/15 -- Version 1.0c
 276 --------------------------
 277
 278 Fix for footers -- Error traceback occurred when there is no
 279 footer, i.e. no .. footer:: directive and none of
 280 --generator, --date, --time, --source-link, --source-url=URL.
 281
 282 Another fix for titles, headers, and footers -- The title of the
 283 document was being shoved to the bottom of the document.
 284
 285 Enhancement to table of contents -- Now there are separate list
 286 styles for list inside the table of contents and lists outside the
 287 table of contents.  See styles rststyle-bulletlist,
 288 rststyle-tocbulletlist, rststyle-enumlist, and
 289 rststyle-tocenumlist.
 290
 291 2007/01/08 -- Version 1.0c
 292 --------------------------
 293
 294 Added support for ..header:: and ..footer:: directives.  Added
 295 styles rststyle-header and rststyle-footer.  The generator,
 296 date/time, and generated-by decorations are now combined with the
 297 content from the ..footer:: directive.
 298
 299 Made fix to literal_blocks so that interior spaces in a line are
 300 preserved.
 301
 302
 303 2007/01/05 -- Version 1.0c
 304 --------------------------
 305
 306 Added support for the "table" directive.  Insert title into output
 307 with new rststyle-table-title style.
 308
 309 Added limited support for "container" directive.  Limitations: (1)
 310 Only the first class in the list of classes (arguments) is used
 311 and (2) that class/style must be a paragraph style and not (for
 312 example) a character style.
 313
 314
 315 2006/12/31 -- Version 1.0b
 316 --------------------------
 317
 318 Fixed imports to match latest version of Pygments.
 319
 320
 321 2006/12/29 -- Version 1.0b
 322 --------------------------
 323
 324 Added a separate lexer for LaTeX syntax highlighting.
 325
 326
 327 2006/12/27 -- Version 1.0b
 328 --------------------------
 329
 330 Added a Docutils directive which enables user (1) to turn syntax
 331 highlighting in literal code blocks on and off and (2) to specify
 332 which lexer (language) to use during syntax highlighing.
 333
 334 Updated the documentation to describe the syntax highlighting
 335 directive.
 336
 337
 338 2006/12/22 -- Version 1.0b
 339 --------------------------
 340
 341 Implemented visit_line, depart_line, visit_line_block,
 342 depart_line_block.
 343
 344 Implemented visit_subtitle and visit_subtitle as references to
 345 visit_title and depart_title.
 346
 347
 348 2006/12/19 -- Version 1.0b
 349 --------------------------
 350
 351 Added syntax highlighting for literal code blocks.  Syntax
 352 highlighting is applied only if Pygments is installed and the
 353 --add-syntax-highlighting command line flag is used.  Pygments can
 354 be found here:  http://pygments.pocoo.org/.  See the odtwriter
 355 documentation for information about the styles used for syntax
 356 highlighting.
 357
 358
 359 2006/12/18 -- Version 1.0b
 360 --------------------------
 361
 362 Fixed zipfile so that members of .odt have UNIX access permissions
 363 and are stored deflated.
 364
 365
 366 2006/12/07
 367 ----------
 368
 369 Fix for ElementTree getparent() and fixed zip DEFLATE.
 370   - ElementTree does not implement getparent().  Created wrapper
 371     class to support this.
 372   - Use of ZipInfo instances prevented compression.  Remove it.
 373
 374 Removed references to IPShell
 375
 376
 377 2006/10/18
 378 ----------
 379
 380 Added support for images and figures.
 381
 382
 383
 384