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