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