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