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