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