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