RELEASE-NOTES.txt

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