[Python-checkins] python/dist/src/Doc/lib libfuncs.tex,1.153,1.154

[rhettinger at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv32452

Modified Files:
	libfuncs.tex 
Log Message:
As discussed on python-dev, banish apply(), buffer(), coerce(), and
intern() to a separate region in the docs.



Index: libfuncs.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libfuncs.tex,v
retrieving revision 1.153
retrieving revision 1.154
diff -C2 -d -r1.153 -r1.154
*** libfuncs.tex	18 Nov 2003 19:48:57 -0000	1.153
--- libfuncs.tex	25 Nov 2003 21:48:21 -0000	1.154
***************
*** 61,84 ****
  \end{funcdesc}
  
- \begin{funcdesc}{apply}{function, args\optional{, keywords}}
-   The \var{function} argument must be a callable object (a
-   user-defined or built-in function or method, or a class object) and
-   the \var{args} argument must be a sequence.  The \var{function} is
-   called with \var{args} as the argument list; the number of arguments
-   is the length of the tuple.
-   If the optional \var{keywords} argument is present, it must be a
-   dictionary whose keys are strings.  It specifies keyword arguments
-   to be added to the end of the argument list.
-   Calling \function{apply()} is different from just calling
-   \code{\var{function}(\var{args})}, since in that case there is always
-   exactly one argument.  The use of \function{apply()} is equivalent
-   to \code{\var{function}(*\var{args}, **\var{keywords})}.
-   Use of \function{apply()} is not necessary since the ``extended call
-   syntax,'' as used in the last example, is completely equivalent.
- 
-   \deprecated{2.3}{Use the extended call syntax instead, as described
-                    above.}
- \end{funcdesc}
- 
  \begin{funcdesc}{basestring}{}
    This abstract type is the superclass for \class{str} and \class{unicode}.
--- 61,64 ----
***************
*** 105,118 ****
  \end{funcdesc}
  
- \begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}}
-   The \var{object} argument must be an object that supports the buffer
-   call interface (such as strings, arrays, and buffers).  A new buffer
-   object will be created which references the \var{object} argument.
-   The buffer object will be a slice from the beginning of \var{object}
-   (or from the specified \var{offset}). The slice will extend to the
-   end of \var{object} (or will have a length given by the \var{size}
-   argument).
- \end{funcdesc}
- 
  \begin{funcdesc}{callable}{object}
    Return true if the \var{object} argument appears callable, false if
--- 85,88 ----
***************
*** 163,172 ****
  \end{funcdesc}
  
- \begin{funcdesc}{coerce}{x, y}
-   Return a tuple consisting of the two numeric arguments converted to
-   a common type, using the same rules as used by arithmetic
-   operations.
- \end{funcdesc}
- 
  \begin{funcdesc}{compile}{string, filename, kind\optional{,
                            flags\optional{, dont_inherit}}}
--- 133,136 ----
***************
*** 583,601 ****
  \end{funcdesc}
  
- \begin{funcdesc}{intern}{string}
-   Enter \var{string} in the table of ``interned'' strings and return
-   the interned string -- which is \var{string} itself or a copy.
-   Interning strings is useful to gain a little performance on
-   dictionary lookup -- if the keys in a dictionary are interned, and
-   the lookup key is interned, the key comparisons (after hashing) can
-   be done by a pointer compare instead of a string compare.  Normally,
-   the names used in Python programs are automatically interned, and
-   the dictionaries used to hold module, class or instance attributes
-   have interned keys.  \versionchanged[Interned strings are not
-   immortal (like they used to be in Python 2.2 and before);
-   you must keep a reference to the return value of \function{intern()}
-   around to benefit from it]{2.3}
- \end{funcdesc}
- 
  \begin{funcdesc}{isinstance}{object, classinfo}
    Return true if the \var{object} argument is an instance of the
--- 547,550 ----
***************
*** 1116,1118 ****
--- 1065,1135 ----
    and \code{zip()} raised a \exception{TypeError} instead of returning
    \code{[]}]{2.4} 
+ \end{funcdesc}
+ 
+ 
+ % ---------------------------------------------------------------------------	
+ 
+ 
+ \section{Non-essential Built-in Functions \label{non-essential-built-in-funcs}}
+ 
+ There are several built-in functions that are no longer essential to learn,
+ know or use in modern Python programming.  They have been kept here to
+ maintain backwards compatability with programs written for older versions
+ of Python.
+ 
+ Python programmers, trainers, students and bookwriters should feel free to
+ bypass these functions without concerns about missing something important.
+ 
+ 
+ \setindexsubitem{(non-essential built-in functions)}
+ 
+ \begin{funcdesc}{apply}{function, args\optional{, keywords}}
+   The \var{function} argument must be a callable object (a
+   user-defined or built-in function or method, or a class object) and
+   the \var{args} argument must be a sequence.  The \var{function} is
+   called with \var{args} as the argument list; the number of arguments
+   is the length of the tuple.
+   If the optional \var{keywords} argument is present, it must be a
+   dictionary whose keys are strings.  It specifies keyword arguments
+   to be added to the end of the argument list.
+   Calling \function{apply()} is different from just calling
+   \code{\var{function}(\var{args})}, since in that case there is always
+   exactly one argument.  The use of \function{apply()} is equivalent
+   to \code{\var{function}(*\var{args}, **\var{keywords})}.
+   Use of \function{apply()} is not necessary since the ``extended call
+   syntax,'' as used in the last example, is completely equivalent.
+ 
+   \deprecated{2.3}{Use the extended call syntax instead, as described
+                    above.}
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{buffer}{object\optional{, offset\optional{, size}}}
+   The \var{object} argument must be an object that supports the buffer
+   call interface (such as strings, arrays, and buffers).  A new buffer
+   object will be created which references the \var{object} argument.
+   The buffer object will be a slice from the beginning of \var{object}
+   (or from the specified \var{offset}). The slice will extend to the
+   end of \var{object} (or will have a length given by the \var{size}
+   argument).
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{coerce}{x, y}
+   Return a tuple consisting of the two numeric arguments converted to
+   a common type, using the same rules as used by arithmetic
+   operations.
+ \end{funcdesc}
+ 
+ \begin{funcdesc}{intern}{string}
+   Enter \var{string} in the table of ``interned'' strings and return
+   the interned string -- which is \var{string} itself or a copy.
+   Interning strings is useful to gain a little performance on
+   dictionary lookup -- if the keys in a dictionary are interned, and
+   the lookup key is interned, the key comparisons (after hashing) can
+   be done by a pointer compare instead of a string compare.  Normally,
+   the names used in Python programs are automatically interned, and
+   the dictionaries used to hold module, class or instance attributes
+   have interned keys.  \versionchanged[Interned strings are not
+   immortal (like they used to be in Python 2.2 and before);
+   you must keep a reference to the return value of \function{intern()}
+   around to benefit from it]{2.3}
  \end{funcdesc}