diff options
| -rw-r--r-- | Doc/Makefile | 8 | ||||
| -rw-r--r-- | Doc/documenting/markup.rst | 10 | ||||
| -rw-r--r-- | Doc/library/aifc.rst | 7 | ||||
| -rw-r--r-- | Doc/library/codeop.rst | 12 | ||||
| -rw-r--r-- | Doc/library/fileinput.rst | 6 | ||||
| -rw-r--r-- | Doc/library/logging.rst | 2 | ||||
| -rw-r--r-- | Doc/library/marshal.rst | 18 | ||||
| -rw-r--r-- | Doc/library/mimetools.rst | 1 | ||||
| -rw-r--r-- | Doc/library/multifile.rst | 1 | ||||
| -rw-r--r-- | Doc/library/rfc822.rst | 1 | ||||
| -rw-r--r-- | Doc/library/shutil.rst | 8 | ||||
| -rw-r--r-- | Doc/library/stringprep.rst | 1 | ||||
| -rw-r--r-- | Doc/library/unicodedata.rst | 6 | ||||
| -rw-r--r-- | Doc/library/zipfile.rst | 6 | ||||
| -rw-r--r-- | Doc/reference/expressions.rst | 8 | ||||
| -rw-r--r-- | Doc/tools/sphinx-build.py | 9 |
16 files changed, 73 insertions, 31 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index 955fb68..d26117b 100644 --- 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 index 831fad9..ce042a5 100644 --- 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 index 0cfcb52..7f7d7fe 100644 --- 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 index 8a730ec..419e873 100644 --- 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 index d0a3ed9..d45def1 100644 --- 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 index 218fb0d..7e8703a 100644 --- 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 index 010ebc3..6927067 100644 --- 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 index 603bec6..8da385e 100644 --- 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 index c36ccb7..3e79229 100644 --- 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 index fa25ba5..52df013 100644 --- 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 index ef0758d..31d898a 100644 --- 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 index b0944e4..d2f269c 100644 --- 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 index 017d4ee..ec788c5 100644 --- 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 index 5e51bfc..ccc3114 100644 --- 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 index 28c1406..476c82d 100644 --- 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 index 20516b6..8c9331e 100644 --- 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)) |