[Python-checkins] CVS: python/dist/src/Doc/tut tut.tex,1.100.2.3,1.100.2.4

Fred L. Drake fdrake@weyr.cnri.reston.va.us
Mon, 21 Feb 2000 12:21:21 -0500 (EST)


Update of /projects/cvsroot/python/dist/src/Doc/tut
In directory weyr:/home/fdrake/projects/python/Doc-152p1/tut

Modified Files:
      Tag: release152p1-patches
	tut.tex 
Log Message:

Sought & adjusted markup that can make LaTeX2HTML drop a space in the
output.


Index: tut.tex
===================================================================
RCS file: /projects/cvsroot/python/dist/src/Doc/tut/tut.tex,v
retrieving revision 1.100.2.3
retrieving revision 1.100.2.4
diff -C2 -r1.100.2.3 -r1.100.2.4
*** tut.tex	2000/02/17 18:02:39	1.100.2.3
--- tut.tex	2000/02/21 17:21:18	1.100.2.4
***************
*** 159,166 ****
  \section{Invoking the Interpreter \label{invoking}}
  
! The Python interpreter is usually installed as \file{/usr/local/bin/python}
! on those machines where it is available; putting \file{/usr/local/bin} in
! your \UNIX{} shell's search path makes it possible to start it by
! typing the command
  
  \begin{verbatim}
--- 159,166 ----
  \section{Invoking the Interpreter \label{invoking}}
  
! The Python interpreter is usually installed as
! \file{/usr/local/bin/python} on those machines where it is available;
! putting \file{/usr/local/bin} in your \UNIX{} shell's search path
! makes it possible to start it by typing the command
  
  \begin{verbatim}
***************
*** 309,314 ****
  can do this by setting an environment variable named
  \envvar{PYTHONSTARTUP} to the name of a file containing your start-up
! commands.  This is similar to the \file{.profile} feature of the \UNIX{}
! shells.
  
  This file is only read in interactive sessions, not when Python reads
--- 309,314 ----
  can do this by setting an environment variable named
  \envvar{PYTHONSTARTUP} to the name of a file containing your start-up
! commands.  This is similar to the \file{.profile} feature of the
! \UNIX{} shells.
  
  This file is only read in interactive sessions, not when Python reads
***************
*** 376,382 ****
  The interpreter acts as a simple calculator: you can type an
  expression at it and it will write the value.  Expression syntax is
! straightforward: the operators \code{+}, \code{-}, \code{*} and \code{/}
! work just like in most other languages (e.g., Pascal or C); parentheses
! can be used for grouping.  For example:
  
  \begin{verbatim}
--- 376,382 ----
  The interpreter acts as a simple calculator: you can type an
  expression at it and it will write the value.  Expression syntax is
! straightforward: the operators \code{+}, \code{-}, \code{*} and
! \code{/} work just like in most other languages (e.g., Pascal or C);
! parentheses can be used for grouping.  For example:
  
  \begin{verbatim}
***************
*** 634,639 ****
  \end{verbatim}
  
! Here's a useful invariant of slice operations: \code{s[:i] + s[i:]}
! equals \code{s}.
  
  \begin{verbatim}
--- 634,639 ----
  \end{verbatim}
  
! Here's a useful invariant of slice operations:
! \code{s[:i] + s[i:]} equals \code{s}.
  
  \begin{verbatim}
***************
*** 909,914 ****
  \section{\keyword{if} Statements \label{if}}
  
! Perhaps the most well-known statement type is the \keyword{if}
! statement.  For example:
  
  \begin{verbatim}
--- 909,914 ----
  \section{\keyword{if} Statements \label{if}}
  
! Perhaps the most well-known statement type is the
! \keyword{if} statement.  For example:
  
  \begin{verbatim}
***************
*** 926,937 ****
  \end{verbatim}
  
! There can be zero or more \keyword{elif} parts, and the \keyword{else}
! part is optional.  The keyword `\keyword{elif}' is short for `else
! if', and is useful to avoid excessive indentation.  An
! \keyword{if} \ldots\ \keyword{elif} \ldots\ \keyword{elif}
! \ldots\ sequence is a substitute for the  \emph{switch} or
! %    ^^^^
  %    Weird spacings happen here if the wrapping of the source text
  %    gets changed in the wrong way.
  \emph{case} statements found in other languages.
  
--- 926,936 ----
  \end{verbatim}
  
! There can be zero or more \keyword{elif} parts, and the
! \keyword{else} part is optional.  The keyword `\keyword{elif}' is
! short for `else if', and is useful to avoid excessive indentation.  An 
! \keyword{if} \ldots\ \keyword{elif} \ldots\ \keyword{elif} \ldots\ sequence
  %    Weird spacings happen here if the wrapping of the source text
  %    gets changed in the wrong way.
+ is a substitute for the  \emph{switch} or
  \emph{case} statements found in other languages.
  
***************
*** 943,950 ****
  iterating over an arithmetic progression of numbers (like in Pascal),
  or giving the user the ability to define both the iteration step and
! halting condition (as C), Python's \keyword{for}\stindex{for}
! statement iterates over the items of any sequence (e.g., a list or a
! string), in the order that they appear in the sequence.  For example
! (no pun intended):
  % One suggestion was to give a real C example here, but that may only
  % serve to confuse non-C programmers.
--- 942,949 ----
  iterating over an arithmetic progression of numbers (like in Pascal),
  or giving the user the ability to define both the iteration step and
! halting condition (as C), Python's
! \keyword{for}\stindex{for} statement iterates over the items of any
! sequence (e.g., a list or a string), in the order that they appear in
! the sequence.  For example (no pun intended):
  % One suggestion was to give a real C example here, but that may only
  % serve to confuse non-C programmers.
***************
*** 1002,1007 ****
  \end{verbatim}
  
! To iterate over the indices of a sequence, combine \function{range()}
! and \function{len()} as follows:
  
  \begin{verbatim}
--- 1001,1006 ----
  \end{verbatim}
  
! To iterate over the indices of a sequence, combine
! \function{range()} and \function{len()} as follows:
  
  \begin{verbatim}
***************
*** 1017,1020 ****
--- 1016,1020 ----
  \end{verbatim}
  
+ 
  \section{\keyword{break} and \keyword{continue} Statements, and
           \keyword{else} Clauses on Loops
***************
*** 1315,1323 ****
  present, it receives a dictionary containing all keyword arguments
  whose keyword doesn't correspond to a formal parameter.  This may be
! combined with a formal parameter of the form \code{*\var{name}}
! (described in the next subsection) which receives a tuple containing
! the positional arguments beyond the formal parameter list.
! (\code{*\var{name}} must occur before \code{**\var{name}}.)  For
! example, if we define a function like this:
  
  \begin{verbatim}
--- 1315,1323 ----
  present, it receives a dictionary containing all keyword arguments
  whose keyword doesn't correspond to a formal parameter.  This may be
! combined with a formal parameter of the form
! \code{*\var{name}} (described in the next subsection) which receives a
! tuple containing the positional arguments beyond the formal parameter
! list.  (\code{*\var{name}} must occur before \code{**\var{name}}.)
! For example, if we define a function like this:
  
  \begin{verbatim}
***************
*** 1389,1394 ****
  There are emerging conventions about the content and formatting of
  documentation strings.
! \index{docstrings}
! \index{documentation strings}
  \index{strings, documentation}
  
--- 1389,1393 ----
  There are emerging conventions about the content and formatting of
  documentation strings.
! \index{docstrings}\index{documentation strings}
  \index{strings, documentation}
  
***************
*** 1714,1722 ****
  value using a non-existent key.
  
! The \code{keys()} method of a dictionary object returns a list of all the
! keys used in the dictionary, in random order (if you want it sorted,
! just apply the \code{sort()} method to the list of keys).  To check
! whether a single key is in the dictionary, use the \code{has_key()}
! method of the dictionary.
  
  Here is a small example using a dictionary:
--- 1713,1721 ----
  value using a non-existent key.
  
! The \code{keys()} method of a dictionary object returns a list of all
! the keys used in the dictionary, in random order (if you want it
! sorted, just apply the \code{sort()} method to the list of keys).  To
! check whether a single key is in the dictionary, use the
! \code{has_key()} method of the dictionary.
  
  Here is a small example using a dictionary:
***************
*** 1902,1907 ****
  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
--- 1901,1905 ----
  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
***************
*** 1980,1991 ****
  \file{.pyc} file is ignored if these don't match.
  
! Normally, you don't need to do anything to create the \file{spam.pyc} file.
! Whenever \file{spam.py} is successfully compiled, an attempt is made to
! write the compiled version to \file{spam.pyc}.  It is not an error if
! this attempt fails; if for any reason the file is not written
! completely, the resulting \file{spam.pyc} file will be recognized as
! invalid and thus ignored later.  The contents of the \file{spam.pyc}
! file are platform independent, so a Python module directory can be
! shared by machines of different architectures.
  
  Some tips for experts:
--- 1978,1990 ----
  \file{.pyc} file is ignored if these don't match.
  
! Normally, you don't need to do anything to create the
! \file{spam.pyc} file.  Whenever \file{spam.py} is successfully
! compiled, an attempt is made to write the compiled version to
! \file{spam.pyc}.  It is not an error if this attempt fails; if for any
! reason the file is not written completely, the resulting
! \file{spam.pyc} file will be recognized as invalid and thus ignored
! later.  The contents of the \file{spam.pyc} file are platform
! independent, so a Python module directory can be shared by machines of
! different architectures.
  
  Some tips for experts:
***************
*** 2014,2021 ****
  
  \item
! A program doesn't run any faster when it is read from a
! \file{.pyc} or \file{.pyo} file than when it is read from a \file{.py}
! file; the only thing that's faster about \file{.pyc} or \file{.pyo}
! files is the speed with which they are loaded.
  
  \item
--- 2013,2020 ----
  
  \item
! A program doesn't run any faster when it is read from a \file{.pyc} or
! \file{.pyo} file than when it is read from a \file{.py} file; the only
! thing that's faster about \file{.pyc} or \file{.pyo} files is the
! speed with which they are loaded.
  
  \item
***************
*** 2224,2233 ****
  
  Note that when using \code{from \var{package} import \var{item}}, the
! item can be either a submodule (or subpackage) of the package, or some
  other name defined in the package, like a function, class or
  variable.  The \code{import} statement first tests whether the item is
  defined in the package; if not, it assumes it is a module and attempts
! to load it.  If it fails to find it, an \exception{ImportError}
! exception is raised.
  
  Contrarily, when using syntax like \code{import
--- 2223,2232 ----
  
  Note that when using \code{from \var{package} import \var{item}}, the
! item can be either a submodule (or subpackage) of the package, or some 
  other name defined in the package, like a function, class or
  variable.  The \code{import} statement first tests whether the item is
  defined in the package; if not, it assumes it is a module and attempts
! to load it.  If it fails to find it, an
! \exception{ImportError} exception is raised.
  
  Contrarily, when using syntax like \code{import
***************
*** 2254,2265 ****
  The only solution is for the package author to provide an explicit
  index of the package.  The import statement uses the following
! convention: if a package's \file{__init__.py} code defines a list named
! \code{__all__}, it is taken to be the list of module names that should
! be imported when \code{from \var{package} import *} is encountered.
! It is up to the package author to keep this list up-to-date when a new
! version of the package is released.  Package authors may also decide
! not to support it, if they don't see a use for importing * from their
! package.  For example, the file \file{Sounds/Effects/__init__.py}
! could contain the following code:
  
  \begin{verbatim}
--- 2253,2264 ----
  The only solution is for the package author to provide an explicit
  index of the package.  The import statement uses the following
! convention: if a package's \file{__init__.py} code defines a list
! named \code{__all__}, it is taken to be the list of module names that
! should be imported when \code{from \var{package} import *} is
! encountered.  It is up to the package author to keep this list
! up-to-date when a new version of the package is released.  Package
! authors may also decide not to support it, if they don't see a use for
! importing * from their package.  For example, the file
! \file{Sounds/Effects/__init__.py} could contain the following code:
  
  \begin{verbatim}
***************
*** 2288,2294 ****
  
  In this example, the echo and surround modules are imported in the
! current namespace because they are defined in the \module{Sound.Effects}
! package when the \code{from...import} statement is executed.  (This also
! works when \code{__all__} is defined.)
  
  Note that in general the practicing of importing * from a module or
--- 2287,2293 ----
  
  In this example, the echo and surround modules are imported in the
! current namespace because they are defined in the
! \module{Sound.Effects} package when the \code{from...import} statement
! is executed.  (This also works when \code{__all__} is defined.)
  
  Note that in general the practicing of importing * from a module or
***************
*** 2316,2324 ****
  with the given name.
  
! When packages are structured into subpackages (as with the \module{Sound}
! package in the example), there's no shortcut to refer to submodules of
! sibling packages - the full name of the subpackage must be used.  For
! example, if the module \module{Sound.Filters.vocoder} needs to use the \module{echo}
! module in the \module{Sound.Effects} package, it can use \code{from
  Sound.Effects import echo}.
  
--- 2315,2324 ----
  with the given name.
  
! When packages are structured into subpackages (as with the
! \module{Sound} package in the example), there's no shortcut to refer
! to submodules of sibling packages - the full name of the subpackage
! must be used.  For example, if the module
! \module{Sound.Filters.vocoder} needs to use the \module{echo} module
! in the \module{Sound.Effects} package, it can use \code{from
  Sound.Effects import echo}.
  
***************
*** 2461,2465 ****
  
  \begin{verbatim}
! >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
  >>> for name, phone in table.items():
  ...     print '%-10s ==> %10d' % (name, phone)
--- 2461,2465 ----
  
  \begin{verbatim}
! >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
  >>> for name, phone in table.items():
  ...     print '%-10s ==> %10d' % (name, phone)
***************
*** 2584,2592 ****
  \samp{f.seek(\var{offset}, \var{from_what})}.  The position is
  computed from adding \var{offset} to a reference point; the reference
! point is selected by the \var{from_what} argument.  A \var{from_what}
! value of 0 measures from the beginning of the file, 1 uses the current
! file position, and 2 uses the end of the file as the reference point.
! \var{from_what} can be omitted and defaults to 0, using the beginning
! of the file as the reference point.
  
  \begin{verbatim}
--- 2584,2592 ----
  \samp{f.seek(\var{offset}, \var{from_what})}.  The position is
  computed from adding \var{offset} to a reference point; the reference
! point is selected by the \var{from_what} argument.  A
! \var{from_what} value of 0 measures from the beginning of the file, 1
! uses the current file position, and 2 uses the end of the file as the
! reference point.  \var{from_what} can be omitted and defaults to 0,
! using the beginning of the file as the reference point.
  
  \begin{verbatim}
***************
*** 2613,2619 ****
  \end{verbatim}
  
! File objects have some additional methods, such as \method{isatty()}
! and \method{truncate()} which are less frequently used; consult the
! Library Reference for a complete guide to file objects.
  
  \subsection{The \module{pickle} Module \label{pickle}}
--- 2613,2620 ----
  \end{verbatim}
  
! File objects have some additional methods, such as
! \method{isatty()} and \method{truncate()} which are less frequently
! used; consult the Library Reference for a complete guide to file
! objects.
  
  \subsection{The \module{pickle} Module \label{pickle}}
***************
*** 2657,2666 ****
  complete documentation for \module{pickle} in the Library Reference.)
  
! \module{pickle} is the standard way to make Python objects which can be
! stored and reused by other programs or by a future invocation of the
! same program; the technical term for this is a \dfn{persistent}
! object.  Because \module{pickle} is so widely used, many authors who
! write Python extensions take care to ensure that new data types such
! as matrices can be properly pickled and unpickled.
  
  
--- 2658,2667 ----
  complete documentation for \module{pickle} in the Library Reference.)
  
! \module{pickle} is the standard way to make Python objects which can
! be stored and reused by other programs or by a future invocation of
! the same program; the technical term for this is a
! \dfn{persistent} object.  Because \module{pickle} is so widely used,
! many authors who write Python extensions take care to ensure that new
! data types such as matrices can be properly pickled and unpickled.
  
  
***************
*** 2670,2675 ****
  Until now error messages haven't been more than mentioned, but if you
  have tried out the examples you have probably seen some.  There are
! (at least) two distinguishable kinds of errors: \emph{syntax errors}
! and \emph{exceptions}.
  
  \section{Syntax Errors \label{syntaxErrors}}
--- 2671,2676 ----
  Until now error messages haven't been more than mentioned, but if you
  have tried out the examples you have probably seen some.  There are
! (at least) two distinguishable kinds of errors:
! \emph{syntax errors} and \emph{exceptions}.
  
  \section{Syntax Errors \label{syntaxErrors}}
***************
*** 2687,2697 ****
  
  The parser repeats the offending line and displays a little `arrow'
! pointing at the earliest point in the line where the error was detected.
! The error is caused by (or at least detected at) the token
! \emph{preceding}
! the arrow: in the example, the error is detected at the keyword
! \keyword{print}, since a colon (\character{:}) is missing before it.
! File name and line number are printed so you know where to look in case
! the input came from a script.
  
  \section{Exceptions \label{exceptions}}
--- 2688,2697 ----
  
  The parser repeats the offending line and displays a little `arrow'
! pointing at the earliest point in the line where the error was
! detected.  The error is caused by (or at least detected at) the token
! \emph{preceding} the arrow: in the example, the error is detected at
! the keyword \keyword{print}, since a colon (\character{:}) is missing
! before it.  File name and line number are printed so you know where to
! look in case the input came from a script.
  
  \section{Exceptions \label{exceptions}}
***************
*** 2722,2728 ****
  Exceptions come in different types, and the type is printed as part of
  the message: the types in the example are
! \exception{ZeroDivisionError},
! \exception{NameError}
! and
  \exception{TypeError}.
  The string printed as the exception type is the name of the built-in
--- 2722,2726 ----
  Exceptions come in different types, and the type is printed as part of
  the message: the types in the example are
! \exception{ZeroDivisionError}, \exception{NameError} and
  \exception{TypeError}.
  The string printed as the exception type is the name of the built-in
***************
*** 2977,2982 ****
  in Smalltalk, classes themselves are objects, albeit in the wider
  sense of the word: in Python, all data types are objects.  This
! provides semantics for importing and renaming.  But, just like in \Cpp{}
! or Modula-3, built-in types cannot be used as base classes for
  extension by the user.  Also, like in \Cpp{} but unlike in Modula-3, most
  built-in operators with special syntax (arithmetic operators,
--- 2975,2980 ----
  in Smalltalk, classes themselves are objects, albeit in the wider
  sense of the word: in Python, all data types are objects.  This
! provides semantics for importing and renaming.  But, just like in
! \Cpp{} or Modula-3, built-in types cannot be used as base classes for
  extension by the user.  Also, like in \Cpp{} but unlike in Modula-3, most
  built-in operators with special syntax (arithmetic operators,
***************
*** 3137,3144 ****
  \end{verbatim}
  
! Class definitions, like function definitions (\keyword{def}
! statements) must be executed before they have any effect.  (You could
! conceivably place a class definition in a branch of an \keyword{if}
! statement, or inside a function.)
  
  In practice, the statements inside a class definition will usually be
--- 3135,3142 ----
  \end{verbatim}
  
! Class definitions, like function definitions
! (\keyword{def} statements) must be executed before they have any
! effect.  (You could conceivably place a class definition in a branch
! of an \keyword{if} statement, or inside a function.)
  
  In practice, the statements inside a class definition will usually be
***************
*** 3272,3278 ****
  \code{MyClass.f} is a function, but \code{x.i} is not, since
  \code{MyClass.i} is not.  But \code{x.f} is not the same thing as
! \code{MyClass.f} --- it is a \emph{method object}, not a function
! object.%
! \obindex{method}
  
  
--- 3270,3275 ----
  \code{MyClass.f} is a function, but \code{x.i} is not, since
  \code{MyClass.i} is not.  But \code{x.f} is not the same thing as
! \code{MyClass.f} --- it is a \obindex{method}\emph{method object}, not
! a function object.
  
  
***************
*** 3634,3639 ****
  \end{verbatim}
  
! In the first form, \code{instance} must be an instance of \class{Class}
! or of a class derived from it.  The second form is a shorthand for
  
  \begin{verbatim}
--- 3631,3637 ----
  \end{verbatim}
  
! In the first form, \code{instance} must be an instance of
! \class{Class} or of a class derived from it.  The second form is a
! shorthand for:
  
  \begin{verbatim}
***************
*** 3815,3822 ****
  Automatic completion of variable and module names is optionally
  available.  To enable it in the interpreter's interactive mode, add
! the following to your \file{\$HOME/.pythonrc.py} file:% $ <- bow to font-lock
  \indexii{.pythonrc.py}{file}
! \refstmodindex{rlcompleter}
! \refbimodindex{readline}
  
  \begin{verbatim}
--- 3813,3819 ----
  Automatic completion of variable and module names is optionally
  available.  To enable it in the interpreter's interactive mode, add
! the following to your \file{\$HOME/.pythonrc.py} file:%
  \indexii{.pythonrc.py}{file}
! \refstmodindex{rlcompleter}\refbimodindex{readline}
  
  \begin{verbatim}