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