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