Merge latest two revs, write about.

Doc-26/ACKS

@@ -6,10 +6,6 @@ documentation.  It is probably not complete -- if you feel that you or
 anyone else should be on this list, please let us know (send email to
 docs@python.org), and we'll be glad to correct the problem.
 
-It is only with the input and contributions of the Python community
-that Python has such wonderful documentation -- Thank You!
-
-
 * Aahz
 * Michael Abbott
 * Steve Alexander
@@ -28,9 +24,11 @@ that Python has such wonderful documentation -- Thank You!
 * Robin Boerdijk
 * Michal Bozon
 * Aaron Brancotti
+* Georg Brandl
 * Keith Briggs
 * Lee Busby
 * Lorenzo M. Catucci
+* Carl Cerecke
 * Mauro Cicognini
 * Gilles Civario
 * Mike Clarkson

Doc-26/TODO

@@ -3,5 +3,4 @@ To do after conversion
 
 * split very large files and add toctrees
 * find out which files get "comments disabled" metadata
-* write "About these documents"
 * finish "Documenting Python"

Doc-26/about.rst

@@ -14,8 +14,20 @@ Development of the documentation and its toolchain takes place on the
 docs@python.org mailing list.  We're always looking for volunteers wanting
 to help with the docs, so feel free to send a mail there!
 
+Many thanks go to:
+
+* Fred L. Drake, Jr., the creator of the original Python documentation toolset
+  and writer of much of the content;
+* the `docutils <http://docutils.sf.net/>`_ project for creating
+  reStructuredText and the docutils suite;
+* Fredrik Lundh for his `Alternative Python Reference
+  <http://effbot.org/zone/pyref.htm>`_ project from which Sphinx got many good
+  ideas.
+
 See :ref:`reporting-bugs` for information how to report bugs in Python itself.
 
-.. % include the ACKS file here so that it can be maintained separately
-
+.. including the ACKS file here so that it can be maintained separately
 .. include:: ACKS
+
+It is only with the input and contributions of the Python community
+that Python has such wonderful documentation -- Thank You!

Doc-3k/ACKS

@@ -6,10 +6,6 @@ documentation.  It is probably not complete -- if you feel that you or
 anyone else should be on this list, please let us know (send email to
 docs@python.org), and we'll be glad to correct the problem.
 
-It is only with the input and contributions of the Python community
-that Python has such wonderful documentation -- Thank You!
-
-
 * Aahz
 * Michael Abbott
 * Steve Alexander
@@ -28,9 +24,11 @@ that Python has such wonderful documentation -- Thank You!
 * Robin Boerdijk
 * Michal Bozon
 * Aaron Brancotti
+* Georg Brandl
 * Keith Briggs
 * Lee Busby
 * Lorenzo M. Catucci
+* Carl Cerecke
 * Mauro Cicognini
 * Gilles Civario
 * Mike Clarkson

Doc-3k/TODO

@@ -3,5 +3,4 @@ To do after conversion
 
 * split very large files and add toctrees
 * find out which files get "comments disabled" metadata
-* write "About these documents"
 * finish "Documenting Python"

Doc-3k/about.rst

@@ -14,8 +14,20 @@ Development of the documentation and its toolchain takes place on the
 docs@python.org mailing list.  We're always looking for volunteers wanting
 to help with the docs, so feel free to send a mail there!
 
+Many thanks go to:
+
+* Fred L. Drake, Jr., the creator of the original Python documentation toolset
+  and writer of much of the content;
+* the `docutils <http://docutils.sf.net/>`_ project for creating
+  reStructuredText and the docutils suite;
+* Fredrik Lundh for his `Alternative Python Reference
+  <http://effbot.org/zone/pyref.htm>`_ project from which Sphinx got many good
+  ideas.
+
 See :ref:`reporting-bugs` for information how to report bugs in Python itself.
 
-.. % include the ACKS file here so that it can be maintained separately
-
+.. including the ACKS file here so that it can be maintained separately
 .. include:: ACKS
+
+It is only with the input and contributions of the Python community
+that Python has such wonderful documentation -- Thank You!

Doc-3k/library/calendar.rst

@@ -13,7 +13,8 @@ and provides additional useful functions related to the calendar. By default,
 these calendars have Monday as the first day of the week, and Sunday as the last
 (the European convention). Use :func:`setfirstweekday` to set the first day of
 the week to Sunday (6) or to any other weekday.  Parameters that specify dates
-are given as integers.
+are given as integers. For related
+functionality, see also the :mod:`datetime` and :mod:`time` modules.
 
 Most of these functions and classses rely on the :mod:`datetime` module which
 uses an idealized calendar, the current Gregorian calendar indefinitely extended

Doc-3k/library/collections.rst

@@ -13,10 +13,10 @@
 This module implements high-performance container datatypes.  Currently,
 there are two datatypes, :class:`deque` and :class:`defaultdict`, and
 one datatype factory function, :func:`NamedTuple`. Python already
-includes built-in containers, :func:`dict`, :func:`list`, and
-:func:`tuple`. The optional :mod:`bsddb` module has a :meth:`btopen`
-method that can be used to create in-memory or file based ordered
-dictionaries with string keys.
+includes built-in containers, :class:`dict`, :class:`list`,
+:class:`set`, and :class:`tuple`. In addition, the optional :mod:`bsddb`
+module has a :meth:`bsddb.btopen` method that can be used to create in-memory
+or file based ordered dictionaries with string keys.
 
 Future editions of the standard library may include balanced trees and
 ordered dictionaries.

Doc-3k/library/datetime.rst

@@ -16,7 +16,8 @@
 The :mod:`datetime` module supplies classes for manipulating dates and times in
 both simple and complex ways.  While date and time arithmetic is supported, the
 focus of the implementation is on efficient member extraction for output
-formatting and manipulation.
+formatting and manipulation. For related
+functionality, see also the :mod:`time` and :mod:`calendar` modules.
 
 There are two kinds of date and time objects: "naive" and "aware". This
 distinction refers to whether the object has any notion of time zone, daylight

Doc-3k/library/functions.rst

@@ -244,8 +244,10 @@ available.  They are listed here in alphabetical order.
 .. function:: dict([arg])
    :noindex:
 
-   Create a new dictionary.  The dictionary type is described in
-   :ref:`typesmapping`.
+   Create a new data dictionary.  The dictionary type is described in
+   :ref:`typesmapping`. For other containers see the built in
+   :class:`list`, :class:`set`, and :class:`tuple` classes, and the
+   :mod:`collections` module.
 
 
 .. function:: dir([object])
@@ -325,7 +327,7 @@ available.  They are listed here in alphabetical order.
    ``(1, seq[1])``, ``(2, seq[2])``, .... For example::
 
       >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter')]:
-      >>>	    print i, season
+      >>>     print i, season
       0 Spring
       1 Summer
       2 Fall
@@ -488,7 +490,9 @@ available.  They are listed here in alphabetical order.
    :class:`frozenset` objects.  If *iterable* is not specified, returns a new empty
    set, ``frozenset([])``.
 
-   The frozenset type is described in :ref:`types-set`.
+   The frozenset type is described in :ref:`types-set`. For other containers see the built in
+   :class:`dict`, :class:`list`, and :class:`tuple` classes, and the
+   :mod:`collections` module.
 
    .. versionadded:: 2.4
 
@@ -629,7 +633,9 @@ available.  They are listed here in alphabetical order.
    returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``.  If
    no argument is given, returns a new empty list, ``[]``.
 
-   :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`.
+   :class:`list` is a mutable sequence type, as documented in
+   :ref:`typesseq`. For other containers see the built in :class:`dict`,
+   :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module.
 
 
 .. function:: locals()
@@ -782,6 +788,8 @@ available.  They are listed here in alphabetical order.
    Python enforces that the mode, after stripping ``'U'``, begins with ``'r'``,
    ``'w'`` or ``'a'``.
 
+   See also the :mod:`fileinput` module.
+
    .. versionchanged:: 2.5
       Restriction on first letter of mode string introduced.
 
@@ -919,7 +927,9 @@ available.  They are listed here in alphabetical order.
    :class:`frozenset` objects.  If *iterable* is not specified, returns a new empty
    set, ``set([])``.
 
-   The set type is described in :ref:`types-set`.
+   The set type is described in :ref:`types-set`. For other containers see the built in
+   :class:`dict`, :class:`list`, and :class:`tuple` classes, and the
+   :mod:`collections` module.
 
    .. versionadded:: 2.4
 
@@ -1060,7 +1070,10 @@ available.  They are listed here in alphabetical order.
    3])`` returns ``(1, 2, 3)``.  If no argument is given, returns a new empty
    tuple, ``()``.
 
-   :class:`tuple` is a mutable sequence type, as documented in :ref:`typesseq`.
+   :class:`tuple` is an immutable sequence type, as documented in
+   :ref:`typesseq`. For other containers see the built in :class:`dict`,
+   :class:`list`, and :class:`set` classes, and the :mod:`collections` module.
+
 
 .. function:: type(object)
 

Doc-3k/library/index.rst

@@ -48,22 +48,21 @@ over 2500 additional components available from the `Python Package Index
    strings.rst
    datatypes.rst
    numeric.rst
-   netdata.rst
-   markup.rst
+   filesys.rst
+   persistence.rst
+   archiving.rst
    fileformats.rst
    crypto.rst
-   filesys.rst
-   archiving.rst
-   persistence.rst
    allos.rst
    someos.rst
-   unix.rst
    ipc.rst
+   netdata.rst
+   markup.rst
    internet.rst
    mm.rst
-   tk.rst
    i18n.rst
    frameworks.rst
+   tk.rst
    development.rst
    pdb.rst
    profile.rst
@@ -76,4 +75,5 @@ over 2500 additional components available from the `Python Package Index
    language.rst
    misc.rst
    windows.rst
+   unix.rst
    undoc.rst

Doc-3k/library/os.path.rst

@@ -8,7 +8,9 @@
 
 .. index:: single: path; operations
 
-This module implements some useful functions on pathnames.
+This module implements some useful functions on pathnames. To read or
+write files see :func:`open`, and for accessing the filesystem see the
+:mod:`os` module.
 
 .. warning::
 

Doc-3k/library/os.rst

@@ -9,7 +9,8 @@
 This module provides a more portable way of using operating system dependent
 functionality than importing a operating system dependent built-in module like
 :mod:`posix` or :mod:`nt`. (If you just want to read or write a file see
-:func:`open`.)
+:func:`open`, and if you want to manipulate paths, see the :mod:`os.path`
+module.)
 
 This module searches for an operating system dependent built-in module like
 :mod:`mac` or :mod:`posix` and exports the same functions and data as found

Doc-3k/library/stdtypes.rst

@@ -485,31 +485,34 @@ Sequence Types --- :class:`str`, :class:`unicode`, :class:`list`, :class:`tuple`
 
 There are six sequence types: strings, Unicode strings, lists, tuples, buffers,
 and range objects.
+(For other containers see the built in :class:`dict`, :class:`list`,
+:class:`set`, and :class:`tuple` classes, and the :mod:`collections`
+module.)
+  
 
 .. index::
    object: sequence
    object: string
-   object: Unicode
    object: tuple
    object: list
    object: buffer
    object: range
 
 String literals are written in single or double quotes: ``'xyzzy'``,
-``"frobozz"``.  See :ref:`strings` for more about string literals.  Unicode
-strings are much like strings, but are specified in the syntax using a preceding
-``'u'`` character: ``u'abc'``, ``u"def"``.  Lists are constructed with square
-brackets, separating items with commas: ``[a, b, c]``.  Tuples are constructed
-by the comma operator (not within square brackets), with or without enclosing
-parentheses, but an empty tuple must have the enclosing parentheses, such as
-``a, b, c`` or ``()``.  A single item tuple must have a trailing comma, such as
-``(d,)``.
+``"frobozz"``.  See :ref:`strings` for more about string literals.  In addition
+to the functionality described here, there are also string-specific methods
+described in the :ref:`string-methods` section.  Lists are constructed with
+square brackets, separating items with commas: ``[a, b, c]``.  Tuples are
+constructed by the comma operator (not within square brackets), with or without
+enclosing parentheses, but an empty tuple must have the enclosing parentheses,
+such as ``a, b, c`` or ``()``.  A single item tuple must have a trailing comma,
+such as ``(d,)``.
 
 Buffer objects are not directly supported by Python syntax, but can be created
 by calling the builtin function :func:`buffer`.  They don't support
 concatenation or repetition.
 
-Xrange objects are similar to buffers in that there is no specific syntax to
+Objects of type range are similar to buffers in that there is no specific syntax to
 create them, but they are created using the :func:`range` function.  They don't
 support slicing, concatenation or repetition, and using ``in``, ``not in``,
 :func:`min` or :func:`max` on them is inefficient.
@@ -648,9 +651,9 @@ String Methods
 
 Below are listed the string methods which both 8-bit strings and Unicode objects
 support. In addition, Python's strings support the sequence type methods
-described in the :ref:`typesseq` section (above). To output formatted strings
+described in the :ref:`typesseq` section. To output formatted strings
 use template strings or the ``%`` operator described in the
-:ref:`string-formatting` section (below). Also, see the :mod:`re` module for
+:ref:`string-formatting` section. Also, see the :mod:`re` module for
 string functions based on regular expressions.
 
 .. method:: str.capitalize()
@@ -1399,6 +1402,9 @@ A :dfn:`set` object is an unordered collection of distinct hashable objects.
 Common uses include membership testing, removing duplicates from a sequence, and
 computing mathematical operations such as intersection, union, difference, and
 symmetric difference.
+(For other containers see the built in :class:`dict`, :class:`list`,
+and :class:`tuple` classes, and the :mod:`collections` module.)
+
 
 .. versionadded:: 2.4
 
@@ -1565,12 +1571,19 @@ Mapping Types --- :class:`dict`
 
 A :dfn:`mapping` object maps immutable values to arbitrary objects.  Mappings
 are mutable objects.  There is currently only one standard mapping type, the
-:dfn:`dictionary`.  A dictionary's keys are *almost* arbitrary values.  Only
+:dfn:`dictionary`.
+(For other containers see the built in :class:`list`,
+:class:`set`, and :class:`tuple` classes, and the :mod:`collections`
+module.)
+
+A dictionary's keys are *almost* arbitrary values.  Only
 values containing lists, dictionaries or other mutable types (that are compared
 by value rather than by object identity) may not be used as keys. Numeric types
 used for keys obey the normal rules for numeric comparison: if two numbers
 compare equal (such as ``1`` and ``1.0``) then they can be used interchangeably
-to index the same dictionary entry.
+to index the same dictionary entry. (Note however, that since computers
+store floating-point numbers as approximations it is usually unwise to
+use them as dictionary keys.)
 
 Dictionaries can be created by placing a comma-separated list of ``key: value``
 pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
@@ -1595,19 +1608,16 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
    keyword is retained in the dictionary. For example, these all return a
    dictionary equal to ``{"one": 2, "two": 3}``:
 
+   * ``dict(one=2, two=3)``
+
    * ``dict({'one': 2, 'two': 3})``
 
-   * ``dict({'one': 2, 'two': 3}.items())``
-
-   * ``dict({'one': 2, 'two': 3}.iteritems())``
-
    * ``dict(zip(('one', 'two'), (2, 3)))``
 
    * ``dict([['two', 3], ['one', 2]])``
 
-   * ``dict(one=2, two=3)``
-
-   * ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])``
+   The first example only works for keys that are valid Python
+   identifiers; the others work with any valid keys.
 
    .. versionadded:: 2.2
 

Doc-3k/library/sys.rst

@@ -19,6 +19,9 @@ always available.
    the interpreter, ``argv[0]`` is set to the string ``'-c'``.  If no script name
    was passed to the Python interpreter, ``argv[0]`` is the empty string.
 
+   To loop over the standard input, or the list of files given on the
+   command line, see the :mod:`fileinput` module.
+
 
 .. data:: byteorder
 

Doc-3k/library/time.rst

@@ -6,8 +6,11 @@
    :synopsis: Time access and conversions.
 
 
-This module provides various time-related functions.  It is always available,
-but not all functions are available on all platforms.  Most of the functions
+This module provides various time-related functions. For related
+functionality, see also the :mod:`datetime` and :mod:`calendar` modules.
+
+Although this module is always available,
+not all functions are available on all platforms.  Most of the functions
 defined in this module call platform C library functions with the same name.  It
 may sometimes be helpful to consult the platform documentation, because the
 semantics of these functions varies among platforms.