1 							-*- text -*-

     2 

     3 If you edited Misc/NEWS before it was converted to ReST format skimming this

     4 file should help make the transition a bit easier.  For full details about

     5 Docutils and ReST, go to the Docutils website:

     6 

     7     http://docutils.sourceforge.net/

     8 

     9 To process Misc/NEWS using Docutils, you'll need the latest docutils

    10 snapshot:

    11 

    12     http://docutils.sf.net/docutils-snapshot.tgz

    13 

    14 Docutils works with Python 2.2 or newer.

    15 

    16 To process NEWS into NEWS.html, first install Docutils, and then run

    17 this command:

    18 

    19     python .../docutils/tools/rst2html.py NEWS NEWS.html

    20 

    21 Here ".../docutils" is the directory into which the above snapshot was

    22 extracted.  (I hope this recipe will change for the better.)

    23 

    24 David Goodger made a change to the allowable structure of internal

    25 references which greatly simplified initial conversion of the file.

    26 

    27 The changes required fell into the following categories:

    28 

    29 * The top-level "What's New" section headers changed to:

    30 

    31     What's New in Python 2.3 alpha 1?

    32     =================================

    33 

    34     *Release date: DD-MMM-2002*

    35 

    36   Note that the release date line is emphasized, with a "*" at each

    37   end.

    38 

    39 * Subsections are underlined with a single row of hyphens:

    40 

    41     Type/class unification and new-style classes

    42     --------------------------------------------

    43 

    44 * Places where "balanced" single quotes were used were changed to use

    45   apostrophes as both the opening and closing quote (`string' -> 'string').

    46 

    47 * In a few places asterisks needed to be escaped which would otherwise have

    48   been interpreted as beginning blocks of italic or bold text, e.g.:

    49 

    50     - The type of tp_free has been changed from "``void (*)(PyObject *)``"

    51       to "``void (*)(void *)``".

    52 

    53   Note that only the asterisks preceded by whitespace needed to be escaped.

    54 

    55 * One instance of a word ending with an underscore needed to be quoted

    56   ("PyCmp_" became "``PyCmp_``").

    57 

    58 * One table was converted to ReST form (search Misc/NEWS for "New codecs"

    59   for this example).

    60 

    61 * A few places where chunks of code or indented text were displayed needed

    62   to be properly introduced (preceding paragraph terminated by "::" and the

    63   chunk of code or text indented w.r.t. the paragraph).  For example:

    64 

    65     - Note that PyLong_AsDouble can fail!  This has always been true,

    66       but no callers checked for it.  It's more likely to fail now,

    67       because overflow errors are properly detected now.  The proper way

    68       to check::

    69 

    70           double x = PyLong_AsDouble(some_long_object);

    71           if (x == -1.0 && PyErr_Occurred()) {

    72               /* The conversion failed. */

    73               }