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