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