docutils/RELEASE-NOTES.txt

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