RELEASE-NOTES.txt

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