From 37f1574f2e26ed12ce5d52b901f3166b4e4c0bd6 Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Wed, 10 Nov 1999 16:21:37 +0000 Subject: Use \citetitle and \programopt as appropriate. --- Doc/lib/lib.tex | 32 +++++++++--------- Doc/lib/libcurses.tex | 3 +- Doc/lib/libexcs.tex | 26 ++++++++------- Doc/lib/libimaplib.tex | 8 ++--- Doc/lib/libobjs.tex | 4 +-- Doc/lib/libparser.tex | 34 +++++++++---------- Doc/lib/libsocket.tex | 14 ++++---- Doc/lib/libsocksvr.tex | 4 +-- Doc/lib/libsoundex.tex | 17 +++++----- Doc/lib/libstdtypes.tex | 38 +++++++++++---------- Doc/lib/libundoc.tex | 5 +-- Doc/lib/libwhrandom.tex | 20 +++++------ Doc/tut/tut.tex | 88 ++++++++++++++++++++++++------------------------- 13 files changed, 149 insertions(+), 144 deletions(-) diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index f57c961..b0f5705 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -30,16 +30,16 @@ Python is an extensible, interpreted, object-oriented programming language. It supports a wide range of applications, from simple text processing scripts to interactive WWW browsers. -While the \emph{Python Reference Manual} describes the exact syntax and -semantics of the language, it does not describe the standard library -that is distributed with the language, and which greatly enhances its -immediate usability. This library contains built-in modules (written -in C) that provide access to system functionality such as file I/O -that would otherwise be inaccessible to Python programmers, as well as -modules written in Python that provide standardized solutions for many -problems that occur in everyday programming. Some of these modules -are explicitly designed to encourage and enhance the portability of -Python programs. +While the \citetitle[../ref/ref.html]{Python Reference Manual} +describes the exact syntax and semantics of the language, it does not +describe the standard library that is distributed with the language, +and which greatly enhances its immediate usability. This library +contains built-in modules (written in C) that provide access to system +functionality such as file I/O that would otherwise be inaccessible to +Python programmers, as well as modules written in Python that provide +standardized solutions for many problems that occur in everyday +programming. Some of these modules are explicitly designed to +encourage and enhance the portability of Python programs. This library reference manual documents Python's standard library, as well as many optional library modules (which may or may not be @@ -50,11 +50,13 @@ functions and exceptions, many of which are not or incompletely documented in the Reference Manual. This manual assumes basic knowledge about the Python language. For an -informal introduction to Python, see the \emph{Python Tutorial}; the -\emph{Python Reference Manual} remains the highest authority on -syntactic and semantic questions. Finally, the manual entitled -\emph{Extending and Embedding the Python Interpreter} describes how to -add new extensions to Python and how to embed it in other applications. +informal introduction to Python, see the +\citetitle[../tut/tut.html]{Python Tutorial}; the +\citetitle[../ref/ref.html]{Python Reference Manual} remains the +highest authority on syntactic and semantic questions. Finally, the +manual entitled \citetitle[../ext/ext.html]{Extending and Embedding +the Python Interpreter} describes how to add new extensions to Python +and how to embed it in other applications. \end{abstract} diff --git a/Doc/lib/libcurses.tex b/Doc/lib/libcurses.tex index b147670..a108002 100644 --- a/Doc/lib/libcurses.tex +++ b/Doc/lib/libcurses.tex @@ -16,7 +16,8 @@ curses. \begin{seealso} \seetext{Tutorial material on using curses with Python is available - on the Python Web site as Andrew Kuchling's \emph{Curses + on the Python Web site as Andrew Kuchling's +\citetitle[http://www.python.org/doc/howto/curses/curses.html]{Curses Programming with Python}, at \url{http://www.python.org/doc/howto/curses/curses.html}.} \end{seealso} diff --git a/Doc/lib/libexcs.tex b/Doc/lib/libexcs.tex index fb80b76..1c57ee8 100644 --- a/Doc/lib/libexcs.tex +++ b/Doc/lib/libexcs.tex @@ -11,15 +11,17 @@ and users are encouraged to do the same. The source code for those exceptions is present in the standard library module \module{exceptions}; this module never needs to be imported explicitly. -For backward compatibility, when Python is invoked with the \code{-X} -option, most of the standard exceptions are strings\footnote{For -forward-compatibility the new exceptions \exception{Exception}, -\exception{LookupError}, -\exception{ArithmeticError}, \exception{EnvironmentError}, and -\exception{StandardError} are tuples.}. This option may be used to -run code that breaks because of the different semantics of class based -exceptions. The \code{-X} option will become obsolete in future -Python versions, so the recommended solution is to fix the code. +For backward compatibility, when Python is invoked with the +\programopt{-X} option, most of the standard exceptions are +strings\footnote{ + For forward-compatibility the new exceptions \exception{Exception}, + \exception{LookupError}, \exception{ArithmeticError}, + \exception{EnvironmentError}, and \exception{StandardError} are + tuples. +}. This option may be used to run code that breaks because of the +different semantics of class based exceptions. The +\programopt{-X} option will become obsolete in future Python versions, +so the recommended solution is to fix the code. Two distinct string objects with the same value are considered different exceptions. This is done to force programmers to use exception names @@ -122,8 +124,8 @@ created with other than 2 or 3 arguments. In this last case, \setindexsubitem{(built-in exception)} The following exceptions are the exceptions that are actually raised. -They are class objects, except when the \code{-X} option is used to -revert back to string-based standard exceptions. +They are class objects, except when the \programopt{-X} option is used +to revert back to string-based standard exceptions. \begin{excdesc}{AssertionError} Raised when an \keyword{assert} statement fails. @@ -150,7 +152,7 @@ Raised when an \keyword{assert} statement fails. \begin{excdesc}{FloatingPointError} Raised when a floating point operation fails. This exception is always defined, but can only be raised when Python is configured - with the \code{--with-fpectl} option, or the + with the \programopt{-}\programopt{-with-fpectl} option, or the \constant{WANT_SIGFPE_HANDLER} symbol is defined in the \file{config.h} file. \end{excdesc} diff --git a/Doc/lib/libimaplib.tex b/Doc/lib/libimaplib.tex index c96eb1f..c275a6e 100644 --- a/Doc/lib/libimaplib.tex +++ b/Doc/lib/libimaplib.tex @@ -72,10 +72,10 @@ At the end of the module, there is a test section that contains a more extensive example of usage. \begin{seealso} -\seetext{Documents describing the protocol, and sources and binaries -for servers implementing it, can all be found at the University of -Washington's \emph{IMAP Information Center} -(\url{http://www.cac.washington.edu/imap/}).} + \seetext{Documents describing the protocol, and sources and binaries + for servers implementing it, can all be found at the + University of Washington's \emph{IMAP Information Center} + (\url{http://www.cac.washington.edu/imap/}).} \end{seealso} diff --git a/Doc/lib/libobjs.tex b/Doc/lib/libobjs.tex index d19697b..354bebc 100644 --- a/Doc/lib/libobjs.tex +++ b/Doc/lib/libobjs.tex @@ -20,5 +20,5 @@ listing them in order of ascending priority (within a table) and grouping operators that have the same priority in the same box. Binary operators of the same priority group from left to right. (Unary operators group from right to left, but there you have no real -choice.) See Chapter 5 of the \emph{Python Reference Manual} for the -complete picture on operator priorities. +choice.) See Chapter 5 of the \citetitle[../ref/ref.html]{Python +Reference Manual} for the complete picture on operator priorities. diff --git a/Doc/lib/libparser.tex b/Doc/lib/libparser.tex index 5a339b2..db49d89 100644 --- a/Doc/lib/libparser.tex +++ b/Doc/lib/libparser.tex @@ -35,23 +35,23 @@ the \module{parser} module are presented. Most importantly, a good understanding of the Python grammar processed by the internal parser is required. For full information on the -language syntax, refer to the \emph{Python Language Reference}. The -parser itself is created from a grammar specification defined in the file -\file{Grammar/Grammar} in the standard Python distribution. The parse -trees stored in the AST objects created by this module are the -actual output from the internal parser when created by the -\function{expr()} or \function{suite()} functions, described below. The AST -objects created by \function{sequence2ast()} faithfully simulate those -structures. Be aware that the values of the sequences which are -considered ``correct'' will vary from one version of Python to another -as the formal grammar for the language is revised. However, -transporting code from one Python version to another as source text -will always allow correct parse trees to be created in the target -version, with the only restriction being that migrating to an older -version of the interpreter will not support more recent language -constructs. The parse trees are not typically compatible from one -version to another, whereas source code has always been -forward-compatible. +language syntax, refer to the \citetitle[../ref/ref.html]{Python +Language Reference}. The parser itself is created from a grammar +specification defined in the file \file{Grammar/Grammar} in the +standard Python distribution. The parse trees stored in the AST +objects created by this module are the actual output from the internal +parser when created by the \function{expr()} or \function{suite()} +functions, described below. The AST objects created by +\function{sequence2ast()} faithfully simulate those structures. Be +aware that the values of the sequences which are considered +``correct'' will vary from one version of Python to another as the +formal grammar for the language is revised. However, transporting +code from one Python version to another as source text will always +allow correct parse trees to be created in the target version, with +the only restriction being that migrating to an older version of the +interpreter will not support more recent language constructs. The +parse trees are not typically compatible from one version to another, +whereas source code has always been forward-compatible. Each element of the sequences returned by \function{ast2list()} or \function{ast2tuple()} has a simple form. Sequences representing diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex index e8c8731..4abe805 100644 --- a/Doc/lib/libsocket.tex +++ b/Doc/lib/libsocket.tex @@ -9,13 +9,13 @@ This module provides access to the BSD \emph{socket} interface. It is available on \UNIX{} systems that support this interface. For an introduction to socket programming (in C), see the following -papers: \emph{An Introductory 4.3BSD Interprocess Communication -Tutorial}, by Stuart Sechrest and \emph{An Advanced 4.3BSD Interprocess -Communication Tutorial}, by Samuel J. Leffler et al, both in the -\UNIX{} Programmer's Manual, Supplementary Documents 1 (sections PS1:7 -and PS1:8). The \UNIX{} manual pages for the various socket-related -system calls are also a valuable source of information on the details of -socket semantics. +papers: \citetitle{An Introductory 4.3BSD Interprocess Communication +Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD +Interprocess Communication Tutorial}, by Samuel J. Leffler et al, +both in the \citetitle{\UNIX{} Programmer's Manual, Supplementary Documents 1} +(sections PS1:7 and PS1:8). The \UNIX{} manual pages for the various +socket-related system calls are also a valuable source of information +on the details of socket semantics. The Python interface is a straightforward transliteration of the \UNIX{} system call and library interface for sockets to Python's diff --git a/Doc/lib/libsocksvr.tex b/Doc/lib/libsocksvr.tex index 13b6d64..120b049 100644 --- a/Doc/lib/libsocksvr.tex +++ b/Doc/lib/libsocksvr.tex @@ -16,8 +16,8 @@ lost while in transit. The more infrequently used \class{UnixStreamServer} and \class{UnixDatagramServer} classes are similar, but use \UNIX{} domain sockets; they're not available on non-\UNIX{} platforms. For more details on network programming, consult -a book such as W. Richard Steven's \emph{UNIX Network Programming} -or Ralph Davis's \emph{Win32 Network Programming}. +a book such as W. Richard Steven's \citetitle{UNIX Network Programming} +or Ralph Davis's \citetitle{Win32 Network Programming}. These four classes process requests \dfn{synchronously}; each request must be completed before the next request can be started. This isn't diff --git a/Doc/lib/libsoundex.tex b/Doc/lib/libsoundex.tex index 8073a8c..25e82cf 100644 --- a/Doc/lib/libsoundex.tex +++ b/Doc/lib/libsoundex.tex @@ -32,13 +32,12 @@ is equivalent to \begin{seealso} - -\seetext{Donald E. Knuth, \emph{Sorting and Searching,} vol. 3 in -``The Art of Computer Programming.'' Addison-Wesley Publishing -Company: Reading, MA: 1973. pp.\ 391-392. Discusses the origin and -usefulness of the algorithm, as well as the algorithm itself. Knuth -gives his sources as \emph{U.S. Patents 1261167} (1918) and -\emph{1435663} (1922), attributing the algorithm to Margaret K. Odell -and Robert C. Russel. Additional references are provided.} - + \seetext{Donald E. Knuth, \citetitle{Sorting and Searching}, vol. 3 + in ``The Art of Computer Programming.'' Addison-Wesley + Publishing Company: Reading, MA: 1973. pp.\ 391-392. + Discusses the origin and usefulness of the algorithm, as + well as the algorithm itself. Knuth gives his sources as + \emph{U.S. Patents 1261167} (1918) and \emph{1435663} + (1922), attributing the algorithm to Margaret K. Odell and + Robert C. Russel. Additional references are provided.} \end{seealso} diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex index 39c9290..6ae216b 100644 --- a/Doc/lib/libstdtypes.tex +++ b/Doc/lib/libstdtypes.tex @@ -302,14 +302,14 @@ division by \code{pow(2, \var{n})} without overflow check. There are three sequence types: strings, lists and tuples. Strings literals are written in single or double quotes: -\code{'xyzzy'}, \code{"frobozz"}. See Chapter 2 of the \emph{Python -Reference Manual} for more about string literals. Lists are -constructed with square brackets, separating items with commas: -\code{[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, e.g., -\code{a, b, c} or \code{()}. A single item tuple must have a trailing -comma, e.g., \code{(d,)}. +\code{'xyzzy'}, \code{"frobozz"}. See Chapter 2 of the +\citetitle[../ref/ref.html]{Python Reference Manual} for more about +string literals. Lists are constructed with square brackets, +separating items with commas: \code{[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, e.g., \code{a, b, c} or \code{()}. A single +item tuple must have a trailing comma, e.g., \code{(d,)}. \indexii{sequence}{types} \indexii{string}{type} \indexii{tuple}{type} @@ -629,7 +629,8 @@ written as \code{}. \subsubsection{Classes and Class Instances \label{typesobjects}} \nodename{Classes and Instances} -See Chapters 3 and 7 of the \emph{Python Reference Manual} for these. +See Chapters 3 and 7 of the \citetitle[../ref/ref.html]{Python +Reference Manual} for these. \subsubsection{Functions \label{typesfunctions}} @@ -667,7 +668,8 @@ implementing the method. Calling \code{\var{m}(\var{arg-1}, calling \code{\var{m}.im_func(\var{m}.im_self, \var{arg-1}, \var{arg-2}, \textrm{\ldots}, \var{arg-n})}. -See the \emph{Python Reference Manual} for more information. +See the \citetitle[../ref/ref.html]{Python Reference Manual} for more +information. \subsubsection{Code Objects \label{bltin-code-objects}} @@ -689,7 +691,8 @@ source string) to the \keyword{exec} statement or the built-in \stindex{exec} \bifuncindex{eval} -See the \emph{Python Reference Manual} for more information. +See the \citetitle[../ref/ref.html]{Python Reference Manual} for more +information. \subsubsection{Type Objects \label{bltin-type-objects}} @@ -715,9 +718,10 @@ It is written as \code{None}. \subsubsection{The Ellipsis Object \label{bltin-ellipsis-object}} -This object is used by extended slice notation (see the \emph{Python -Reference Manual}). It supports no special operations. There is -exactly one ellipsis object, named \code{Ellipsis} (a built-in name). +This object is used by extended slice notation (see the +\citetitle[../ref/ref.html]{Python Reference Manual}). It supports no +special operations. There is exactly one ellipsis object, named +\constant{Ellipsis} (a built-in name). It is written as \code{Ellipsis}. @@ -868,9 +872,9 @@ attribute. \subsubsection{Internal Objects \label{typesinternal}} -See the \emph{Python Reference Manual} for this information. It -describes code objects, stack frame objects, traceback objects, and -slice objects. +See the \citetitle[../ref/ref.html]{Python Reference Manual} for this +information. It describes code objects, stack frame objects, +traceback objects, and slice objects. \subsection{Special Attributes \label{specialattrs}} diff --git a/Doc/lib/libundoc.tex b/Doc/lib/libundoc.tex index 2967cb8..e8f3736 100644 --- a/Doc/lib/libundoc.tex +++ b/Doc/lib/libundoc.tex @@ -14,8 +14,9 @@ effort spent. \begin{description} \item[\module{Tkinter}] ---- Interface to Tcl/Tk for graphical user interfaces; -Fredrik Lundh is working on this one! See \emph{An Introduction to +--- Interface to Tcl/Tk for graphical user interfaces; Fredrik Lundh +is working on this one! See +\citetitle[http://www.pythonware.com/library/]{An Introduction to Tkinter} at \url{http://www.pythonware.com/library/} for on-line reference material. diff --git a/Doc/lib/libwhrandom.tex b/Doc/lib/libwhrandom.tex index 8df1b77..b79377d 100644 --- a/Doc/lib/libwhrandom.tex +++ b/Doc/lib/libwhrandom.tex @@ -22,13 +22,9 @@ Returns the next random floating point number in the range [0.0 ... 1.0). \end{funcdesc} \begin{funcdesc}{seed}{x, y, z} -Initializes the random number generator from the integers -\var{x}, -\var{y} -and -\var{z}. -When the module is first imported, the random number is initialized -using values derived from the current time. +Initializes the random number generator from the integers \var{x}, +\var{y} and \var{z}. When the module is first imported, the random +number is initialized using values derived from the current time. \end{funcdesc} \begin{funcdesc}{uniform}{a, b} @@ -43,10 +39,10 @@ available at the module level. Therefore one can write either generator = whrandom.whrandom() N = generator.random() \end{verbatim} -% + \begin{seealso} -\seemodule{random}{generators for various random distributions} -\seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183: -An efficient and portable pseudo-random number generator'', -\emph{Applied Statistics} 31 (1982) 188-190} + \seemodule{random}{generators for various random distributions} + \seetext{Wichmann, B. A. \& Hill, I. D., ``Algorithm AS 183: + An efficient and portable pseudo-random number generator'', + \citetitle{Applied Statistics} 31 (1982) 188-190.} \end{seealso} diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex index a125ba7..cb7a4d1 100644 --- a/Doc/tut/tut.tex +++ b/Doc/tut/tut.tex @@ -48,11 +48,12 @@ Python interpreter handy for hands-on experience, but all examples are self-contained, so the tutorial can be read off-line as well. For a description of standard objects and modules, see the -\emph{Python Library Reference} document. The \emph{Python Reference -Manual} gives a more formal definition of the language. To write -extensions in C or \Cpp{}, read the \emph{Extending and Embedding} and -\emph{Python/C API} manuals. There are also several books covering -Python in depth. +\citetitle[../lib/lib.html]{Python Library Reference} document. The +\citetitle[../ref/ref.html]{Python Reference Manual} gives a more +formal definition of the language. To write extensions in C or +\Cpp{}, read \citetitle[../ext/ext.html]{Extending and Embedding the +Python Interpreter} and \citetitle[../api/api.html]{Python/C API +Reference}. There are also several books covering Python in depth. This tutorial does not attempt to be comprehensive and cover every single feature, or even every commonly used feature. Instead, it @@ -60,7 +61,8 @@ introduces many of Python's most noteworthy features, and will give you a good idea of the language's flavor and style. After reading it, you will be able to read and write Python modules and programs, and you will be ready to learn more about the various Python library -modules described in the \emph{Python Library Reference}. +modules described in the \citetitle[../lib/lib.html]{Python Library +Reference}. \end{abstract} @@ -196,11 +198,11 @@ a file as standard input, it reads and executes a \emph{script} from that file. A third way of starting the interpreter is -\samp{python -c command [arg] ...}, which -executes the statement(s) in \code{command}, analogous to the shell's -\code{-c} option. Since Python statements often contain spaces or other -characters that are special to the shell, it is best to quote -\code{command} in its entirety with double quotes. +\samp{\program{python} \programopt{-c} \var{command} [arg] ...}, which +executes the statement(s) in \var{command}, analogous to the shell's +\programopt{-c} option. Since Python statements often contain spaces +or other characters that are special to the shell, it is best to quote +\var{command} in its entirety with double quotes. Note that there is a difference between \samp{python file} and \samp{python