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