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