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