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