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