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