[Python-Dev] Misc/NEWS (was: Two random and nearly unrelated ideas)
David Goodger
goodger@users.sourceforge.net
Wed, 04 Sep 2002 22:44:23 -0400
[Skip]
>> While adding a blurb to Misc/NEWS about the change to the thread
>> ticker and check interval, it occurred to me that perhaps Misc/NEWS
>> would benefit from conversion to ReST format. You could pump an
>> HTML version out to the website periodically.
I have the Docutils site auto-regenerated via a small cron script.
Any time any of the source text files change, within an hour the site
reflects the change. It makes site maintenance easy.
(BTW, Skip, thanks for the bug report. I'll be looking into it ASAP.)
[Guido]
> Nice idea. How much additional mark-up would this add to quote the
> occasional reST meta-character?
Very little, depending on the desired effect. The extreme case would
be if you want to mark up everything possible. The result may look
too busy in the source text form though, especially because there are
so many Python identifiers, expressions, code snippets, and file names
that *could* be marked up. It's a trade-off.
The nice thing is that Misc/NEWS is already almost valid
reStrucuturedText (which shouldn't be surprising, since
reStrucuturedText is based on common usage). In fact, most (if not
all) of the standalone text files are almost there: README, PLAN.txt,
etc. It wouldn't be much work to bring them up to spec.
Here are the areas of Misc/NEWS that would require editing:
* Sections: The two-line titles aren't supported. Either they should
be combined into one line, or the "Release date" line should become
part of the section body. Either::
What's New in Python 2.2 final? Release date: 21-Dec-2001
==========================================================
or::
What's New in Python 2.2 final?
===============================
Release date: 21-Dec-2001
* Subsections (like "Core and builtins", "Library", "Extension
modules", etc.): These could be made into true subsections by
underlining them with dashes (and changing to title case)::
Core and Builtins
-----------------
I notice that there are many headers for empty subsections (such as
"Tools/Demos" and "Build" in "What's New in Python 2.2 final?").
Should they be removed?
* Inline literals (filenames, identifiers, expressions and code
snippets): Surround with double-backquotes to get monospaced,
uninterpreted text (like HTML TT tags). There are so many of these
that it may be best to be selective.
* Literal blocks: Example code should be indented and prefaced with
double-colons ("::" at the end of the preceding paragraph). Doctest
blocks (interactive sessions, begin with ">>> " and end with a blank
line) don't need this, although it wouldn't hurt.
> Can you convert a section for test and show me?
I'll be happy to help. Hmm. Looking at the 2.2.1 Misc/NEWS file, I
see sections for 2.2.1 final, 2.2.1c2, etc., but they're missing from
the CVS Misc/NEWS file. Is this normal because of separate development
branches or is something amiss?
Following is a converted section from the current Misc/NEWS.
Minimally marked up:
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
What's New in Python 2.3 alpha 1?
=================================
XXX Release date: DD-MMM-2002 XXX
Type/class unification and new-style classes
--------------------------------------------
- Assignment to __class__ is disallowed if either the old and the new
class is a statically allocated type object (such as defined by an
extension module). This prevents anomalies like ``2 .__class__ =
bool``.
- New-style object creation and deallocation have been sped up
significantly; they are now faster than classic instance creation
and deallocation.
- The __slots__ variable can now mention "private" names, and the
right thing will happen (e.g. ``__slots__ = ["__foo"]``).
- The built-ins slice() and buffer() are now callable types. The
types classobj (formerly class), code, function, instance, and
instancemethod (formerly instance-method), which have no built-in
names but are accessible through the types module, are now also
callable. The type dict-proxy is renamed to dictproxy.
- Cycles going through the __class__ link of a new-style instance are
now detected by the garbage collector.
- Classes using __slots__ are now properly garbage collected.
[SF bug 519621]
- Tightened the __slots__ rules: a slot name must be a valid Python
identifier.
- The constructor for the module type now requires a name argument and
takes an optional docstring argument. Previously, this constructor
ignored its arguments. As a consequence, deriving a class from a
module (not from the module type) is now illegal; previously this
created an unnamed module, just like invoking the module type did.
[SF bug 563060]
- A new type object, 'basestring', is added. This is a common base
type for 'str' and 'unicode', and can be used instead of
``types.StringTypes``, e.g. to test whether something is "a string":
``isinstance(x, basestring)`` is True for Unicode and 8-bit strings.
This is an abstract base class and cannot be instantiated directly.
- Changed new-style class instantiation so that when C's __new__
method returns something that's not a C instance, its __init__ is
not called. [SF bug #537450]
- Fixed super() to work correctly with class methods. [SF bug #535444]
- If you try to pickle an instance of a class that has __slots__ but
doesn't define or override __getstate__, a TypeError is now raised.
This is done by adding a bozo __getstate__ to the class that always
raises TypeError. (Before, this would appear to be pickled, but the
state of the slots would be lost.)
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
Maximally marked up:
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
What's New in Python 2.3 alpha 1?
=================================
XXX Release date: DD-MMM-2002 XXX
Type/class unification and new-style classes
--------------------------------------------
- Assignment to ``__class__`` is disallowed if either the old and the
new class is a statically allocated type object (such as defined by
an extension module). This prevents anomalies like ``2 .__class__ =
bool``.
- New-style object creation and deallocation have been sped up
significantly; they are now faster than classic instance creation
and deallocation.
- The ``__slots__`` variable can now mention "private" names, and the
right thing will happen (e.g. ``__slots__ = ["__foo"]``).
- The built-ins ``slice()`` and ``buffer()`` are now callable types.
The types classobj (formerly class), code, function, instance, and
instancemethod (formerly instance-method), which have no built-in
names but are accessible through the ``types`` module, are now also
callable. The type dict-proxy is renamed to dictproxy.
- Cycles going through the ``__class__`` link of a new-style instance
are now detected by the garbage collector.
- Classes using ``__slots__`` are now properly garbage collected.
[SF bug 519621]
- Tightened the ``__slots__`` rules: a slot name must be a valid
Python identifier.
- The constructor for the module type now requires a name argument and
takes an optional docstring argument. Previously, this constructor
ignored its arguments. As a consequence, deriving a class from a
module (not from the module type) is now illegal; previously this
created an unnamed module, just like invoking the module type did.
[SF bug 563060]
- A new type object, ``basestring``, is added. This is a common base
type for ``str`` and ``unicode``, and can be used instead of
``types.StringTypes``, e.g. to test whether something is "a string":
``isinstance(x, basestring)`` is ``True`` for Unicode and 8-bit
strings. This is an abstract base class and cannot be instantiated
directly.
- Changed new-style class instantiation so that when C's ``__new__``
method returns something that's not a C instance, its ``__init__``
is not called. [SF bug #537450]
- Fixed ``super()`` to work correctly with class methods. [SF bug #535444]
- If you try to pickle an instance of a class that has ``__slots__``
but doesn't define or override ``__getstate__``, a ``TypeError`` is
now raised. This is done by adding a bozo ``__getstate__`` to the
class that always raises ``TypeError``. (Before, this would appear
to be pickled, but the state of the slots would be lost.)
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
--
David Goodger <goodger@users.sourceforge.net> Open-source projects:
- Python Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)
- The Go Tools Project: http://gotools.sourceforge.net/