Manually patched a few things that didn't get merged in, but should.

gvanrossum · gvanrossum · commit da27fd267346 · 2007-08-17T00:24:54.000Z
diff --git a/Doc/Makefile b/Doc/Makefile
@@ -4,9 +4,9 @@
 #
 
 # You can set these variables from the command line.
-PYTHON       ?= python
-SVNROOT      ?= http://svn.python.org/projects
-SPHINXOPTS   ?=
+PYTHON       = python
+SVNROOT      = http://svn.python.org/projects
+SPHINXOPTS   =
 
 ALLSPHINXOPTS = -b$(BUILDER) -dbuild/doctrees $(SPHINXOPTS) . build/$(BUILDER)
 
@@ -55,7 +55,7 @@ web: build
 htmlhelp: BUILDER = htmlhelp
 htmlhelp: build
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      "build/hhp/pydoc.hhp project file."
+	      "build/htmlhelp/pydoc.hhp project file."
 
 clean:
 	-rm -rf build/*
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
@@ -79,6 +79,9 @@ As you can see, the module-specific markup consists of two directives, the
    The ``synopsis`` option should consist of one sentence describing the
    module's purpose -- it is currently only used in the Global Module Index.
 
+   The ``deprecated`` option can be given (with no value) to mark a module as
+   deprecated; it will be designated as such in various locations then.
+
 .. describe:: moduleauthor
 
    The ``moduleauthor`` directive, which can appear multiple times, names the
@@ -333,6 +336,13 @@ the current module, or the built-in function of that name.  In contrast,
 ``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
 module.
 
+Normally, names in these roles are searched first without any further
+qualification, then with the current module name prepended, then with the
+current module and class name (if any) prepended.  If you prefix the name with a
+dot, this order is reversed.  For example, in the documentation of the
+:mod:`codecs` module, ``:func:`open``` always refers to the built-in function,
+while ``:func:`.open``` refers to :func:`codecs.open`.
+
 A similar heuristic is used to determine whether the name is an attribute of
 the currently documented class.
 
diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst
@@ -16,9 +16,10 @@ AIFF is Audio Interchange File Format, a format for storing digital audio
 samples in a file.  AIFF-C is a newer version of the format that includes the
 ability to compress the audio data.
 
-**Caveat:**  Some operations may only work under IRIX; these will raise
-:exc:`ImportError` when attempting to import the :mod:`cl` module, which is only
-available on IRIX.
+.. warning::
+   
+   Some operations may only work under IRIX; these will raise :exc:`ImportError`
+   when attempting to import the :mod:`cl` module, which is only available on IRIX.
 
 Audio files have a number of parameters that describe the audio data. The
 sampling rate or frame rate is the number of times per second the sound is
diff --git a/Doc/library/codeop.rst b/Doc/library/codeop.rst
@@ -46,11 +46,13 @@ To do just the former:
    (``'single'``, the default) or as an expression (``'eval'``).  Any other value
    will cause :exc:`ValueError` to  be raised.
 
-   **Caveat:** It is possible (but not likely) that the parser stops parsing with a
-   successful outcome before reaching the end of the source; in this case, trailing
-   symbols may be ignored instead of causing an error.  For example, a backslash
-   followed by two newlines may be followed by arbitrary garbage.  This will be
-   fixed once the API for the parser is better.
+   .. warning::
+      
+      It is possible (but not likely) that the parser stops parsing with a
+      successful outcome before reaching the end of the source; in this case,
+      trailing symbols may be ignored instead of causing an error.  For example,
+      a backslash followed by two newlines may be followed by arbitrary garbage.
+      This will be fixed once the API for the parser is better.
 
 
 .. class:: Compile()
diff --git a/Doc/library/fileinput.rst b/Doc/library/fileinput.rst
@@ -149,10 +149,12 @@ and the backup file remains around; by default, the extension is ``'.bak'`` and
 it is deleted when the output file is closed.  In-place filtering is disabled
 when standard input is read.
 
-**Caveat:** The current implementation does not work for MS-DOS 8+3 filesystems.
+.. warning::
+   
+   The current implementation does not work for MS-DOS 8+3 filesystems.
 
-The two following opening hooks are provided by this module:
 
+The two following opening hooks are provided by this module:
 
 .. function:: hook_compressed(filename, mode)
 
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
@@ -536,7 +536,7 @@ instantiated directly, but always through the module-level function
    Finds the caller's source filename and line number. Returns the filename, line
    number and function name as a 3-element tuple.
 
-   .. versionchanged:: 2.5
+   .. versionchanged:: 2.4
       The function name was added. In earlier versions, the filename and line number
       were returned as a 2-element tuple..
 
diff --git a/Doc/library/marshal.rst b/Doc/library/marshal.rst
@@ -42,14 +42,16 @@ and dictionaries are only supported as long as the values contained therein are
 themselves supported; and recursive lists and dictionaries should not be written
 (they will cause infinite loops).
 
-**Caveat:** On machines where C's ``long int`` type has more than 32 bits (such
-as the DEC Alpha), it is possible to create plain Python integers that are
-longer than 32 bits. If such an integer is marshaled and read back in on a
-machine where C's ``long int`` type has only 32 bits, a Python long integer
-object is returned instead.  While of a different type, the numeric value is the
-same.  (This behavior is new in Python 2.2.  In earlier versions, all but the
-least-significant 32 bits of the value were lost, and a warning message was
-printed.)
+.. warning::
+   
+   On machines where C's ``long int`` type has more than 32 bits (such as the
+   DEC Alpha), it is possible to create plain Python integers that are longer
+   than 32 bits. If such an integer is marshaled and read back in on a machine
+   where C's ``long int`` type has only 32 bits, a Python long integer object
+   is returned instead.  While of a different type, the numeric value is the
+   same.  (This behavior is new in Python 2.2.  In earlier versions, all but the
+   least-significant 32 bits of the value were lost, and a warning message was
+   printed.)
 
 There are functions that read/write files as well as functions operating on
 strings.
diff --git a/Doc/library/mimetools.rst b/Doc/library/mimetools.rst
@@ -4,6 +4,7 @@
 
 .. module:: mimetools
    :synopsis: Tools for parsing MIME-style message bodies.
+   :deprecated:
 
 
 .. deprecated:: 2.3
diff --git a/Doc/library/multifile.rst b/Doc/library/multifile.rst
@@ -4,6 +4,7 @@
 
 .. module:: multifile
    :synopsis: Support for reading files which contain distinct parts, such as some MIME data.
+   :deprecated:
 .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
 
 
diff --git a/Doc/library/rfc822.rst b/Doc/library/rfc822.rst
@@ -4,6 +4,7 @@
 
 .. module:: rfc822
    :synopsis: Parse 2822 style mail messages.
+   :deprecated:
 
 
 .. deprecated:: 2.3
diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst
@@ -17,9 +17,11 @@ The :mod:`shutil` module offers a number of high-level operations on files and
 collections of files.  In particular, functions are provided  which support file
 copying and removal.
 
-**Caveat:**  On MacOS, the resource fork and other metadata are not used.  For
-file copies, this means that resources will be lost and  file type and creator
-codes will not be correct.
+.. warning::
+   
+   On MacOS, the resource fork and other metadata are not used.  For file copies,
+   this means that resources will be lost and  file type and creator codes will
+   not be correct.
 
 
 .. function:: copyfile(src, dst)
diff --git a/Doc/library/stringprep.rst b/Doc/library/stringprep.rst
@@ -4,6 +4,7 @@
 
 .. module:: stringprep
    :synopsis: String preparation, as per RFC 3453
+   :deprecated:
 .. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
 .. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
 
diff --git a/Doc/library/unicodedata.rst b/Doc/library/unicodedata.rst
@@ -107,7 +107,7 @@ the following functions:
    based on the definition of canonical equivalence and compatibility equivalence.
    In Unicode, several characters can be expressed in various way. For example, the
    character U+00C7 (LATIN CAPITAL LETTER C WITH CEDILLA) can also be expressed as
-   the sequence U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA).
+   the sequence U+0327 (COMBINING CEDILLA) U+0043 (LATIN CAPITAL LETTER C).
 
    For each character, there are two normal forms: normal form C and normal form D.
    Normal form D (NFD) is also known as canonical decomposition, and translates
@@ -126,6 +126,10 @@ the following functions:
    (NFKC) first applies the compatibility decomposition, followed by the canonical
    composition.
 
+   Even if two unicode strings are normalized and look the same to
+   a human reader, if one has combining characters and the other
+   doesn't, they may not compare equal.
+
    .. versionadded:: 2.3
 
 In addition, the module exposes the following constant:
diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst
@@ -168,11 +168,11 @@ ZipFile Objects
    .. note::
 
       If the ZipFile was created by passing in a file-like object as the  first
-      argument to the constructor, then the object returned by :meth:`open` shares the
+      argument to the constructor, then the object returned by :meth:`.open` shares the
       ZipFile's file pointer.  Under these  circumstances, the object returned by
-      :meth:`open` should not  be used after any additional operations are performed
+      :meth:`.open` should not  be used after any additional operations are performed
       on the  ZipFile object.  If the ZipFile was created by passing in a string (the
-      filename) as the first argument to the constructor, then  :meth:`open` will
+      filename) as the first argument to the constructor, then  :meth:`.open` will
       create a new file object that will be held by the ZipExtFile, allowing it to
       operate independently of the  ZipFile.
 
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
@@ -987,7 +987,7 @@ Comparison of objects of the same type depends on the type:
 
 * Strings are compared lexicographically using the numeric equivalents (the
   result of the built-in function :func:`ord`) of their characters.  Unicode and
-  8-bit strings are fully interoperable in this behavior.
+  8-bit strings are fully interoperable in this behavior. [#]_
 
 * Tuples and lists are compared lexicographically using comparison of
   corresponding elements.  This means that to compare equal, each element must
@@ -1272,6 +1272,12 @@ groups from right to left).
    cases, Python returns the latter result, in order to preserve that
    ``divmod(x,y)[0] * y + x % y`` be very close to ``x``.
 
+.. [#] While comparisons between unicode strings make sense at the byte
+   level, they may be counter-intuitive to users. For example, the
+   strings ``u"\u00C7"`` and ``u"\u0327\u0043"`` compare differently,
+   even though they both represent the same unicode character (LATIN
+   CAPTITAL LETTER C WITH CEDILLA).
+
 .. [#] The implementation computes this efficiently, without constructing lists or
    sorting.
 
diff --git a/Doc/tools/sphinx-build.py b/Doc/tools/sphinx-build.py
@@ -10,5 +10,14 @@
 import sys
 
 if __name__ == '__main__':
+
+    if sys.version_info[:3] < (2, 5, 0):
+        print >>sys.stderr, """\
+Error: Sphinx needs to be executed with Python 2.5 or newer.
+(If you run this from the Makefile, you can set the PYTHON variable
+to the path of an alternative interpreter executable.)
+"""
+        sys.exit(1)
+
     from sphinx import main
     sys.exit(main(sys.argv))
