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