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