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