Use \citetitle and \programopt as appropriate.

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{<module 'os' from '/usr/local/lib/python1.5/os.pyc'>}.
 \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 <file}.  In the latter case, input requests from the
@@ -213,9 +215,9 @@ is connected to standard input of the Python interpreter.
 
 When a script file is used, it is sometimes useful to be able to run
 the script and enter interactive mode afterwards.  This can be done by
-passing \code{-i} before the script.  (This does not work if the script
-is read from standard input, for the same reason as explained in the
-previous paragraph.)
+passing \programopt{-i} before the script.  (This does not work if the
+script is read from standard input, for the same reason as explained
+in the previous paragraph.)
 
 \subsection{Argument Passing \label{argPassing}}
 
@@ -224,11 +226,11 @@ arguments thereafter are passed to the script in the variable
 \code{sys.argv}, which is a list of strings.  Its length is at least
 one; when no script and no arguments are given, \code{sys.argv[0]} is
 an empty string.  When the script name is given as \code{'-'} (meaning 
-standard input), \code{sys.argv[0]} is set to \code{'-'}.  When \code{-c
-command} is used, \code{sys.argv[0]} is set to \code{'-c'}.  Options
-found after \code{-c command} are not consumed by the Python
-interpreter's option processing but left in \code{sys.argv} for the
-command to handle.
+standard input), \code{sys.argv[0]} is set to \code{'-'}.  When
+\programopt{-c} \var{command} is used, \code{sys.argv[0]} is set to
+\code{'-c'}.  Options found after \programopt{-c} \var{command} are
+not consumed by the Python interpreter's option processing but left in
+\code{sys.argv} for the command to handle.
 
 \subsection{Interactive Mode \label{interactive}}
 
@@ -1845,11 +1847,9 @@ If you intend to use a function often you can assign it to a local name:
 \section{More on Modules \label{moreModules}}
 
 A module can contain executable statements as well as function
-definitions.
-These statements are intended to initialize the module.
-They are executed only the
-\emph{first}
-time the module is imported somewhere.\footnote{
+definitions.  These statements are intended to initialize the module.
+They are executed only the \emph{first} time the module is imported
+somewhere.\footnote{
         In fact function definitions are also `statements' that are
         `executed'; the execution enters the function name in the
         module's global symbol table.
@@ -1944,22 +1944,22 @@ Some tips for experts:
 \begin{itemize}
 
 \item
-When the Python interpreter is invoked with the \code{-O} flag,
+When the Python interpreter is invoked with the \programopt{-O} flag,
 optimized code is generated and stored in \file{.pyo} files.
 The optimizer currently doesn't help much; it only removes
 \keyword{assert} statements and \code{SET_LINENO} instructions.
-When \code{-O} is used, \emph{all} bytecode is optimized; \code{.pyc}
-files are ignored and \code{.py} files are compiled to optimized
-bytecode.
+When \programopt{-O} is used, \emph{all} bytecode is optimized;
+\code{.pyc} files are ignored and \code{.py} files are compiled to
+optimized bytecode.
 
 \item
-Passing two \code{-O} flags to the Python interpreter (\code{-OO})
-will cause the bytecode compiler to perform optimizations that could
-in some rare cases result in malfunctioning programs.  Currently only
-\code{__doc__} strings are removed from the bytecode, resulting in more 
-compact \file{.pyo} files.  Since some programs may rely on having
-these available, you should only use this option if you know what
-you're doing.
+Passing two \programopt{-O} flags to the Python interpreter
+(\programopt{-OO}) will cause the bytecode compiler to perform
+optimizations that could in some rare cases result in malfunctioning
+programs.  Currently only \code{__doc__} strings are removed from the
+bytecode, resulting in more compact \file{.pyo} files.  Since some
+programs may rely on having these available, you should only use this
+option if you know what you're doing.
 
 \item
 A program doesn't run any faster when it is read from a
@@ -1976,14 +1976,14 @@ script that imports that module.
 
 \item
 It is possible to have a file called \file{spam.pyc} (or
-\file{spam.pyo} when \code{-O} is used) without a module
+\file{spam.pyo} when \programopt{-O} is used) without a module
 \file{spam.py} in the same module.  This can be used to distribute
 a library of Python code in a form that is moderately hard to reverse
 engineer.
 
 \item
 The module \module{compileall}\refstmodindex{compileall} can create
-\file{.pyc} files (or \file{.pyo} files when \code{-O} is used) for
+\file{.pyc} files (or \file{.pyo} files when \programopt{-O} is used) for
 all modules in a directory.
 
 \end{itemize}
@@ -1992,13 +1992,13 @@ all modules in a directory.
 \section{Standard Modules \label{standardModules}}
 
 Python comes with a library of standard modules, described in a separate
-document, the \emph{Python Library Reference} (``Library Reference''
-hereafter).  Some modules are built into the interpreter; these
-provide access to operations that are not part of the core of the
-language but are nevertheless built in, either for efficiency or to
-provide access to operating system primitives such as system calls.
-The set of such modules is a configuration option; e.g., the
-\module{amoeba} module is  only provided on systems that somehow
+document, the \citetitle[../lib/lib.html]{Python Library Reference}
+(``Library Reference'' hereafter).  Some modules are built into the
+interpreter; these provide access to operations that are not part of
+the core of the language but are nevertheless built in, either for
+efficiency or to provide access to operating system primitives such as
+system calls. The set of such modules is a configuration option; e.g.,
+the \module{amoeba} module is only provided on systems that somehow
 support Amoeba primitives.  One particular module deserves some
 attention: \module{sys}\refstmodindex{sys}, which is built into every
 Python interpreter.  The variables \code{sys.ps1} and