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