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