[Python-Dev] ReST-ing Misc/NEWS

[Skip Montanaro]

I just checked in a ReST-ified version of Misc/NEWS.  While the total number
of changes was fairly large, the number of different types of changes made
were quite small.  The overwhelming majority of changes involved properly
highlighting section and subsection headers.  

I'll review the changes here so that people who modify this file in the
future will be able to easily adapt to the new format.

First, to process Misc/NEWS using ReST, you'll need the latest docutils
snapshot:

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

David Goodger made a change to the allowable structure of internal
references which simplified my job significantly.

The changes required fell into the following categories:

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

    What's New in Python 2.3 alpha 1?
    =================================

    *XXX Release date: DD-MMM-2002 XXX*

* Subsections are underlined with a single row of hyphens:

    Type/class unification and new-style classes
    --------------------------------------------

* Places where "balanced" single quotes were used were switched to use
  just apostrophes (`string' -> 'string').

* In a few places asterisks needed to be escaped which would otherwise have
  been interpreted as beginning blocks of italic or bold text, e.g.:

    - The type of tp_free has been changed from "void (*)(PyObject \*)"
      to "void (*)(void \*)".

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

* One instance of a word ending with an underscore needed to be quoted
  ("PyCmp_" became "``PyCmp_``").

* One table was converted to ReST form (search Misc/NEWS for "New codecs"
  for this example).

* A few places where chunks of code or indented text were displayed needed
  to be properly introduced (preceding paragraph terminated by "::" and the
  chunk of code or text indented w.r.t. the paragraph).  For example:

    - Note that PyLong_AsDouble can fail!  This has always been true,
      but no callers checked for it.  It's more likely to fail now,
      because overflow errors are properly detected now.  The proper way
      to check: ::

          double x = PyLong_AsDouble(some_long_object);
          if (x == -1.0 && PyErr_Occurred()) {
              /* The conversion failed. */
              }

Not yet addressed is whether to automatically convert Misc/NEWS to other
formats (such as HTML).  I assume an automatic conversion to HTML is in the
cards, with the output made available on the python.org website.

Skip