RELEASE-NOTES.txt

   1 ========================
   2  Docutils Release Notes
   3 ========================
   4
   5 :Contact: grubert@users.sourceforge.net
   6 :Date: $Date$
   7 :Revision: $Revision$
   8 :Web site: http://docutils.sourceforge.net/
   9 :Copyright: This document has been placed in the public domain.
  10
  11
  12 This document summarizes the major changes in recent releases.  For a
  13 more detailed list of changes, please see the `Docutils History`_.
  14
  15 .. _Docutils History: HISTORY.html
  16
  17 .. contents::
  18
  19 Future changes
  20 ==============
  21
  22 * docutils.io.FileInput/FileOutput will no longer do a
  23   system-exit on IOError by default.
  24
  25   Roadmap:
  26
  27   :0.10: change of default behaviour to the equivalent of
  28          ``handle_io_errors=False``,
  29          ignore and deprecate the `handle_io_errors` option.
  30          (allows us to clean up Docutils code and remove the error handling
  31          code from the FileInput/FileOutput classes)
  32   :0.10 + n:   deprecation warning to stderr if FileInput/FileOutput
  33                is called with `handle_io_errors`,
  34   :0.10 + n+1: remove the `handle_io_errors` option.
  35
  36
  37 Changes Since 0.9.1
  38 ===================
  39
  40 .. Note::
  41
  42    Docutils 0.9.x is the last version supporting Python 2.3.
  43
  44    Docutils 0.10 is compatible with Python versions from 2.4 to 3.2
  45    (cf. `Python 3 compatibility`_).
  46
  47 * General:
  48
  49   - ``docutils/math``, ``docutils/error_reporting.py``, and
  50     ``docutils/urischemes.py`` moved to the utils package.
  51     Code importing these modules needs to adapt, e.g.::
  52
  53       try:
  54           import docutils.math as math
  55       except ImportError:
  56           import docutils.utils.math as math
  57
  58 .. _Python 3 compatibility: README.html#python-3-compatibility
  59
  60
  61 Release 0.9.1 (2012-06-17)
  62 ==========================
  63
  64 * General:
  65
  66   Several fixes for Python 3 usage.
  67
  68 * docutils/setup.py
  69
  70   - Fix [ 3527842 ]. Under Python 3, converted tests and tools were
  71     installed in the PYTHONPATH. Converted tests are now
  72     stored in ``docutils/test3/``, tools no longer need conversion.
  73
  74     If you installed one of Docutils versions 0.7 ... 0.9 with
  75     ``setup.py install`` under Python 3, remove the spurious
  76     ``test/`` and ``tools/`` directories in the site library root.
  77
  78
  79 Release 0.9 (2012-05-02)
  80 =========================
  81
  82 * General:
  83
  84   - reStructuredText "code" role and directive with syntax highlighting
  85     by Pygments_.
  86   - "code" option of the "include" directive.
  87
  88   .. _Pygments: http://pygments.org/
  89
  90   - Fix [ 3402314 ] allow non-ASCII whitespace, punctuation
  91     characters and "international" quotes around inline markup.
  92
  93   - Fix handling of missing stylesheets.
  94
  95 * setup.py
  96
  97   - Fix [ 2971827 ] and [ 3442827 ]
  98     extras/roman.py moved to docutils/utils/roman.py
  99
 100 * docutils/utils.py -> docutils/utils/__init__.py
 101
 102   - docutils.utils is now a package (providing a place for sub-modules)
 103
 104 * docutils/writers/html4css1/__init__.py
 105
 106   - change default for `math-output` setting to MathJax
 107
 108 * docutils/writers/latex2e/__init__.py
 109
 110   - Support the `abbreviation` and `acronym` standard roles.
 111   - Record only files required to generate the LaTeX source as dependencies.
 112   - Use ``\setcounter{secnumdepth}{0}`` instead of ``*``-versions
 113     when suppressing LaTeX section numbering.
 114
 115
 116 Release 0.8.1 (2011-08-30)
 117 ==========================
 118
 119 * General:
 120
 121   - Fix [ 3364658 ] (Change last file with Apache license to BSD-2-Clause)
 122     and [ 3395920 ] (correct copyright info for rst.el).
 123
 124 * docutils/writers/latex2e/__init__.py
 125
 126   - Clean up Babel language setting. Restores Sphinx compatibility.
 127
 128
 129 Release 0.8 (2011-07-07)
 130 ========================
 131
 132 * COPYING:
 133
 134   - Some additions to the Docutils core are released under the 2-Clause BSD
 135     license.
 136
 137 * General:
 138
 139   - Handle language codes according to `BCP 47`_.
 140   - If the specified langauage is not supported by Docutils,
 141     warn and fall back to English.
 142   - Math support: reStructuredText "math" role and directive,
 143     ``math`` and ``math_block`` doctree elements.
 144   - Orphaned "python" reader and "newlatex2e" writer moved to the sandbox.
 145
 146   .. _BCP 47: http://www.rfc-editor.org/rfc/bcp/bcp47.txt
 147
 148 * reStructuredText:
 149
 150   - most directives now support a "name" option that attaches a
 151     reference name. So you can write ::
 152
 153       .. figure:: image.png
 154          :name: figure name
 155
 156     as a short form of ::
 157
 158       .. _figure name:
 159
 160       .. figure:: image.png
 161
 162 Internationalization:
 163
 164 * Added lithuanian mappings.
 165
 166 Components:
 167
 168 * HTML writer:
 169
 170   - New setting "math-output" with support for HTML, MathML, and LaTeX.
 171
 172 * LaTeX2e writer:
 173
 174   - Convert image URI to a local file path.
 175   - Apply [ 3148141 ] fix multicolumn support when a colspanning cell
 176     has more than one paragraph (Wolfgang Scherer).
 177
 178 * XeTeX writer:
 179
 180   - New writer generating LaTeX code for compiling with ``xelatex``.
 181
 182     XeTeX uses unicode and modern font technologies.
 183
 184 * and fixes and enhancements here and there.
 185
 186
 187 Release 0.7 (2010-07-07)
 188 ========================
 189
 190 Components:
 191
 192 * HTML writer:
 193
 194   - Support SVG and SWF images (thanks to Stefan Rank).
 195   - Generate valid XHTML for centered images with targets.
 196     Use CSS classes instead of "align" tags for image alignment.
 197
 198 * LaTeX2e writer:
 199
 200   - Use the ``\url`` command for URLs (breaks long URLs instead of writing
 201     into the margin).
 202   - Preserve runs of spaces in 'inline literals'.
 203   - Deprecate ``figure_footnotes`` setting.
 204   - Rename ``use_latex_footnotes`` setting to `docutils_footnotes`__.
 205   - New ``latex_preamble`` setting.
 206   - Use PDF standard fonts (Times/Helvetica/Courier) as default.
 207   - `hyperref` package called with ``unicode`` option (see the
 208     `hyperref config tips`__ for how to override).
 209   - Drop the special `output_encoding`__ default ("latin-1").
 210     The Docutils wide default (usually "UTF-8") is used instead.
 211
 212 __ docs/user/config.html#docutils-footnotes
 213 __ docs/user/latex.html#hyperlinks
 214 __ docs/user/latex.html#output-encoding
 215
 216 * manpage writer:
 217
 218   - Titles level 1, that is ``.SH``, always uppercase.
 219   - Apply patch from mg: literal text should be bold in man-pages.
 220
 221 General:
 222
 223 * io.FileInput opens files as text files with universal newline support
 224   (mode "rU", configurable with the new optional argument "mode").
 225
 226 * setup.py:
 227
 228   - Python 3 support: copy test/ and tools/ to the build-dir
 229     and convert Python sources with 2to3.
 230
 231
 232 Release 0.6 (2009-10-11)
 233 ========================
 234
 235 .. Note::
 236
 237    Docutils 0.5 is the last version supporting Python 2.2.
 238
 239    Docutils 0.6 is compatible with Python versions from 2.3 up to 2.6
 240    and convertible to 3.1 code.
 241
 242 .. note::
 243
 244    The "newlatex" writer is orphaned.
 245
 246    The recommended way to generate PDF output is to use either the
 247    LaTeX2e writer or one of the alternatives listed at
 248    http://docutils.sourceforge.net/docs/user/links.html#pdf.
 249
 250 * reStructuredText:
 251
 252   - Allow length units for all length specifications.
 253   - Allow percent sign in "scale" argument of "figure" and "image" directives.
 254   - Bugfix: The "figalign" argument of a figure now works as intended
 255     (aligning the figure not its contents).
 256   - Align images with class "align-[right|center|left]"
 257     (allows setting the alignment of an image in a figure).
 258   - Hard tabs in literal inclusions are replaced by spaces. This is
 259     configurable via the new "tab-width" option of the "include" directive
 260     (a negative tab-width prevents tab expansion).
 261
 262 * HTML writer:
 263
 264   - ``--stylesheet`` and ``--stylesheet-path`` options now support a comma
 265     separated list of stylesheets.
 266
 267 * LaTeX2e writer:
 268
 269   - New defaults:
 270     - font-encoding: "T1" (formerly implicitely set by 'ae').
 271     - use-latex-toc: true (ToC with page numbers).
 272     - use-latex-footnotes: true (no mixup with figures).
 273     - Float placement defaults to "here definitely" (configurable).
 274     - Align of image in a figure defaults to 'center'.
 275     - Use class defaults for page margins ('typearea' now optional).
 276   - Support LaTeX packages as ``--stylesheet`` arguments.
 277   - Use ``bp`` for lengths without unit or unit ``pt``,
 278     do not convert ``px`` to ``pt``.
 279   - Do not use 'ae' and 'aeguill' packages if font-encoding is set to ''.
 280   - Set sub- and superscript role argument as text not math.
 281   - Support custom roles based on standard roles.
 282   - Load packages and define macros only if required in the document.
 283   - All Docutils specific LaTeX macros are prefixed with ``DU``.
 284   - Better conformance to Docutils specifications with "use_latex_toc".
 285   - If 'sectnum_xform' is False, the 'sectnum' directive triggers
 286     section numbering by LaTeX.
 287   - Use default font in admonitions and sidebar.
 288   - Typeset generic topic as "quote with title".
 289   - Use template (file and configuration option).
 290   - Render doctest blocks as literal blocks (indented).
 291
 292 * ODT writer:
 293
 294   - moved from sandbox to Doctutils core.
 295
 296 * manpage writer:
 297
 298   - moved from sandbox to Doctutils core.
 299
 300
 301 Release 0.5 (2008-06-25)
 302 ========================
 303
 304 Components:
 305
 306 * HTML writer.
 307
 308   - Dropped all ``name`` attributes of ``a`` elements (``id`` is
 309     universally supported now).
 310
 311 * LaTeX2e writer:
 312
 313   - Better bibTeX citation support.
 314   - Add ``--literal-block-env``
 315
 316 * PEP writer:
 317
 318   - Changed to support new python.org website structure and
 319     pep2pyramid.py.
 320
 321 reStructuredText:
 322
 323 * Changed the directive API to a new object-oriented system.
 324   (Compatibility for the old, functional-style directive interface is
 325   retained.)  See the updated `Creating reStructuredText Directives`__
 326   how-to.
 327
 328   __ docs/howto/rst-directives.html
 329
 330 * Allow ``+`` and ``:`` in reference names requested for citations.
 331
 332 Documentation:
 333
 334 * Added `Deploying Docutils Securely`__
 335
 336   __ docs/howto/security.txt
 337
 338 Internationalization:
 339
 340 * Added hebrew mappings.
 341
 342 General:
 343
 344 * Configuration files are now assumed and required to be
 345   UTF-8-encoded.
 346
 347 * Added docutils/writers/html4css1/template.txt.
 348
 349 * Enhance emacs support.
 350
 351
 352 Release 0.4 (2006-01-09)
 353 ========================
 354
 355 .. Note::
 356
 357    Docutils 0.4.x is the last version that will support Python 2.1.
 358    Docutils 0.5 will *not* be compatible with Python 2.1; Python 2.2
 359    or later will be required.
 360
 361    Docutils 0.4.x is the last version that will make compromises in
 362    its HTML output for Netscape Navigator 4.  Docutils 0.5 will
 363    require more up-to-date browsers (the exact definition is to be
 364    determined).
 365
 366 Components:
 367
 368 * Added an `S5/HTML writer`__ and the rst2s5.py__ front end:
 369   multi-platform, multi-browser HTML slide shows.
 370
 371   __ docs/user/slide-shows.html
 372   __ docs/user/tools.html#rst2s5-py
 373
 374 * The newlatex2e writer is nearing completion.
 375
 376 * Added a DocTree reader, ``publish_doctree`` and
 377   ``publish_from_doctree`` convenience functions, for document tree
 378   extraction and reprocessing.
 379
 380 reStructuredText:
 381
 382 * Added directives: "container__" (generic block-level container),
 383   "default-role__" (role used for \`backtick\` syntax), "title__"
 384   (document title metadata), and "date__" (generate the current local
 385   date, for substitution definitions).
 386
 387   __ docs/ref/rst/directives.html#container
 388   __ docs/ref/rst/directives.html#default-role
 389   __ docs/ref/rst/directives.html#title
 390   __ docs/ref/rst/directives.html#date
 391
 392 * Length units are now supported for image__ sizes.
 393
 394   __ docs/ref/rst/directives.html#image
 395
 396 * Added `standard definition files`__ for special characters etc.
 397
 398   __ docs/ref/rst/definitions.html
 399
 400 Internationalization:
 401
 402 * Added Japanese and Simplified Chinese language mappings, and support
 403   for double-width CJK-characters in tables and section titles.
 404
 405 Documentation:
 406
 407 * Added a `guide for distributors`__ (package maintainers) and a
 408   `guide for developers`__.
 409
 410   __ docs/dev/distributing.html
 411   __ docs/dev/hacking.html
 412
 413 General:
 414
 415 * Added significant `Emacs support for reST`__.
 416
 417   __ docs/user/emacs.html
 418
 419 * Added a `--strip-comments`__ option.
 420
 421   __ docs/user/config.html#strip-comments
 422
 423 * `--embed-stylesheet`__ is now the default for the HTML writer
 424   (rather than --link-stylesheet).
 425
 426   __ docs/user/config.html#embed-stylesheet
 427
 428
 429 Release 0.3.9 (2005-05-26)
 430 ==========================
 431
 432 * Added "file_insertion_enabled__" and "raw_enabled__" settings.
 433
 434   __ docs/user/config.html#file-insertion-enabled
 435   __ docs/user/config.html#raw-enabled
 436
 437 * Added `auto-enumerated lists`__.
 438
 439   __ docs/ref/rst/restructuredtext.html#enumerated-lists
 440
 441 * Added `"header" and "footer"`__ directives.
 442
 443   __ docs/ref/rst/directives.html#document-header-footer
 444
 445 * Added "list-table__" directive.
 446
 447   __ docs/ref/rst/directives.html#list-table
 448
 449 * Added support for `section subtitles`__.
 450
 451   __ docs/user/config.html#sectsubtitle-xform
 452
 453 * Added "field_name_limit__" and "option_limit__" settings to HTML writer.
 454
 455   __ docs/user/config.html#field-name-limit
 456   __ docs/user/config.html#option-limit
 457
 458 * Added "cloak_email_addresses__" setting to HTML writer.
 459
 460   __ docs/user/config.html#cloak-email-addresses
 461
 462 * UTF-8 BOMs are now removed from the input stream.
 463
 464
 465 Release 0.3.7 (2004-12-24)
 466 ==========================
 467
 468 * A special "`line block`__" syntax has been added.  (Also see the
 469   `quick reference`__.)
 470
 471   __ docs/ref/rst/restructuredtext.html#line-blocks
 472   __ docs/user/rst/quickref.html#line-blocks
 473
 474 * Empty sections are now allowed.
 475
 476 * A "raw__" role has been added.
 477
 478   __ docs/ref/rst/roles.html#raw
 479
 480 * The LaTeX writer now escapes consecutive dashes (like "--" or "---")
 481   so that they are no longer transformed by LaTeX to en or em dashes.
 482   (Please see the FAQ__ for how to represent such dashes.)
 483
 484   __ FAQ.html#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document
 485
 486 * A `dependency recorder`__ has been added.
 487
 488   __ docs/user/config.html#record-dependencies
 489
 490 * A directive has been added for `compound paragraphs`__.
 491
 492   __ docs/ref/rst/directives.html#compound-paragraph
 493
 494
 495 Release 0.3.5 (2004-07-29)
 496 ==========================
 497
 498 * Improved, extended and reorganized the documentation__.
 499
 500   __ docs/index.html
 501
 502 * Added "csv-table__" directive.
 503
 504   __ docs/ref/rst/directives.html#csv-table