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