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