Add more entries to the glossary.

Written by Jeff Wheeler for GHOP.

Doc/ACKS.txt

@@ -185,6 +185,7 @@ docs@python.org), and we'll be glad to correct the problem.
 * Glyn Webster
 * Bob Weiner
 * Eddy Welbourne
+* Jeff Wheeler
 * Mats Wichmann
 * Gerry Wiener
 * Timothy Wild

Doc/Makefile

@@ -57,6 +57,10 @@ htmlhelp: build
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      "build/htmlhelp/pydoc.hhp project file."
 
+latex: BUILDER = latex
+latex: build
+	@echo "Build finished; the LaTeX files are in build/latex."
+
 clean:
 	-rm -rf build/*
 	-rm -rf tools/sphinx

Doc/README.txt

@@ -48,6 +48,9 @@ Available make targets are:
    To create the CHM file, you need to run the Microsoft HTML Help Workshop
    over the generated project (.hhp) file.
 
+ * "latex", which builds LaTeX source files that can be run with "pdflatex"
+   to produce PDF documents.
+
 A "make update" updates the Subversion checkouts in `tools/`.
 
 

Doc/glossary.rst

@@ -15,6 +15,17 @@ Glossary
    ``...``
       The typical Python prompt of the interactive shell when entering code for
       an indented code block.
+
+   argument
+      A value passed to a function or method, assigned to a name local to
+      the body.  A function or method may have both positional arguments and
+      keyword arguments in its definition.  Positional and keyword arguments
+      may be variable-length: ``*`` accepts or passes (if in the function
+      definition or call) several positional arguments in a list, while ``**``
+      does the same for keyword arguments in a dictionary.
+
+      Any expression may be used within the argument list, and the evaluated
+      value is passed to the local variable.
     
    BDFL
       Benevolent Dictator For Life, a.k.a. `Guido van Rossum
@@ -57,6 +68,22 @@ Glossary
       advanced mathematical feature.  If you're not aware of a need for them,
       it's almost certain you can safely ignore them.
     
+   decorator
+      A function returning another function, usually applied as a function
+      transformation using the ``@wrapper`` syntax.  Common examples for
+      decorators are :func:`classmethod` and :func:`staticmethod`.
+
+      The decorator syntax is merely syntactic sugar, the following two
+      function definitions are semantically equivalent::
+
+         def f(...):
+             ...
+         f = staticmethod(f)
+
+         @staticmethod
+         def f(...):
+             ...
+
    descriptor
       Any *new-style* object that defines the methods :meth:`__get__`,
       :meth:`__set__`, or :meth:`__delete__`.  When a class attribute is a
@@ -94,10 +121,24 @@ Glossary
       statements.  The technique contrasts with the :term:`LBYL` style that is
       common in many other languages such as C.
 
+   expression
+      A piece of syntax which can be evaluated to some value.  In other words,
+      an expression is an accumulation of expression elements like literals, names,
+      attribute access, operators or function calls that all return a value.
+      In contrast to other languages, not all language constructs are expressions,
+      but there are also :term:`statement`\s that cannot be used as expressions,
+      such as :keyword:`print` or :keyword:`if`.  Assignments are also not
+      expressions.
+
    extension module
       A module written in C, using Python's C API to interact with the core and
       with user code.
-    
+
+   function
+      A series of statements which returns some value to a caller. It can also
+      be passed zero or more arguments which may be used in the execution of
+      the body. See also :term:`argument` and :term:`method`.
+
    __future__
       A pseudo module which programmers can use to enable new language features
       which are not compatible with the current interpreter.  For example, the
@@ -241,6 +282,17 @@ Glossary
     
       More information can be found in :ref:`typeiter`.
 
+   keyword argument
+      Arguments which are preceded with a ``variable_name=`` in the call.
+      The variable name designates the local name in the function to which the
+      value is assigned.  ``**`` is used to accept or pass a dictionary of
+      keyword arguments.  See :term:`argument`.
+
+   lambda
+      An anonymous inline function consisting of a single :term:`expression`
+      which is evaluated when the function is called.  The syntax to create
+      a lambda function is ``lambda [arguments]: expression``
+
    LBYL
       Look before you leap.  This coding style explicitly tests for
       pre-conditions before making calls or lookups.  This style contrasts with
@@ -271,6 +323,12 @@ Glossary
       singletons, and many other tasks.
 
       More information can be found in :ref:`metaclasses`.
+
+   method
+      A function that is defined inside a class body.  If called as an attribute
+      of an instance of that class, the method will get the instance object as
+      its first :term:`argument` (which is usually called ``self``).
+      See :term:`function` and :term:`nested scope`.
     
    mutable
       Mutable objects can change their value but keep their :func:`id`.  See
@@ -305,10 +363,32 @@ Glossary
 
       More information can be found in :ref:`newstyle`.
     
+   positional argument
+      The arguments assigned to local names inside a function or method,
+      determined by the order in which they were given in the call.  ``*`` is
+      used to either accept multiple positional arguments (when in the
+      definition), or pass several arguments as a list to a function.  See
+      :term:`argument`.
+
    Python 3000
       Nickname for the next major Python version, 3.0 (coined long ago when the
       release of version 3 was something in the distant future.)
 
+   Pythonic
+      An idea or piece of code which closely follows the most common idioms of
+      the Python language, rather than implementing code using concepts common
+      in other languages.  For example, a common idiom in Python is the :keyword:`for`
+      loop structure; other languages don't have this easy keyword, so people
+      use a numerical counter instead::
+     
+          for i in range(len(food)):
+              print food[i]
+
+      As opposed to the cleaner, Pythonic method::
+
+         for piece in food:
+             print piece
+
    reference count
       The number of places where a certain object is referenced to.  When the
       reference count drops to zero, an object is deallocated.  While reference
@@ -331,6 +411,18 @@ Glossary
       mapping rather than a sequence because the lookups use arbitrary
       :term:`immutable` keys rather than integers.
 
+   slice
+      A list containing a portion of an indexed list-like object.  A slice is
+      created using the subscript notation, ``[]`` with colons between numbers
+      when several are given, such as in ``variable_name[1:3:5]``.  The bracket
+      (subscript) notation uses :class:`slice` objects internally (or in older
+      versions, :meth:`__getslice__` and :meth:`__setslice__`).
+
+   statement
+      A statement is part of a suite (a "block" of code).  A statement is either
+      an :term:`expression` or a one of several constructs with a keyword, such
+      as :keyword:`if`, :keyword:`while` or :keyword:`print`.
+
    type
       The type of a Python object determines what kind of object it is; every
       object has a type.  An object's type is accessible as its

Doc/library/atexit.rst

@@ -96,7 +96,7 @@ passed along to the registered function when it is called::
    # or:
    atexit.register(goodbye, adjective='nice', name='Donny')
 
-Usage as a decorator::
+Usage as a :term:`decorator`::
 
    import atexit
 

Doc/library/bdb.rst

@@ -290,7 +290,7 @@ structure representing a stack trace.
 
 
 The following two methods can be called by clients to use a debugger to debug a
-statement, given as a string.
+:term:`statement`, given as a string.
 
 .. method:: Bdb.run(cmd, [globals, [locals]])
 

Doc/library/codecs.rst

@@ -1119,9 +1119,9 @@ the table.
 |                    |                           |                | all conversions. Can be   |
 |                    |                           |                | used as the system        |
 |                    |                           |                | encoding if no automatic  |
-|                    |                           |                | coercion between byte and |
+|                    |                           |                | :term:`coercion` between  |
-|                    |                           |                | Unicode strings is        |
+|                    |                           |                | byte and Unicode strings  |
-|                    |                           |                | desired.                  |
+|                    |                           |                | is desired.               |
 +--------------------+---------------------------+----------------+---------------------------+
 | unicode_escape     |                           | Unicode string | Produce a string that is  |
 |                    |                           |                | suitable as Unicode       |

Doc/library/codeop.rst

@@ -43,8 +43,8 @@ To do just the former:
    :exc:`OverflowError` or :exc:`ValueError` if there is an invalid literal.
 
    The *symbol* argument determines whether *source* is compiled as a statement
-   (``'single'``, the default) or as an expression (``'eval'``).  Any other value
+   (``'single'``, the default) or as an :term:`expression` (``'eval'``).  Any
-   will cause :exc:`ValueError` to  be raised.
+   other value will cause :exc:`ValueError` to  be raised.
 
    .. warning::
       

Doc/library/contextlib.rst

@@ -17,9 +17,9 @@ Functions provided:
 
 .. function:: contextmanager(func)
 
-   This function is a decorator that can be used to define a factory function for
+   This function is a :term:`decorator` that can be used to define a factory
-   :keyword:`with` statement context managers, without needing to create a class or
+   function for :keyword:`with` statement context managers, without needing to
-   separate :meth:`__enter__` and :meth:`__exit__` methods.
+   create a class or separate :meth:`__enter__` and :meth:`__exit__` methods.
 
    A simple example (this is not recommended as a real way of generating HTML!)::
 

Doc/library/doctest.rst

@@ -1135,7 +1135,8 @@ capabilities, then you should use the advanced API.
 The advanced API revolves around two container classes, which are used to store
 the interactive examples extracted from doctest cases:
 
-* :class:`Example`: A single python statement, paired with its expected output.
+* :class:`Example`: A single python :term:`statement`, paired with its expected
+  output.
 
 * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted
   from a single docstring or text file.

Doc/library/functions.rst

@@ -161,8 +161,8 @@ available.  They are listed here in alphabetical order.
           @classmethod
           def f(cls, arg1, arg2, ...): ...
 
-   The ``@classmethod`` form is a function decorator -- see the description of
+   The ``@classmethod`` form is a function :term:`decorator` -- see the description
-   function definitions in :ref:`function` for details.
+   of function definitions in :ref:`function` for details.
 
    It can be called either on the class (such as ``C.f()``) or on an instance (such
    as ``C().f()``).  The instance is ignored except for its class. If a class
@@ -825,7 +825,7 @@ available.  They are listed here in alphabetical order.
 
    If given, *doc* will be the docstring of the property attribute. Otherwise, the
    property will copy *fget*'s docstring (if it exists).  This makes it possible to
-   create read-only properties easily using :func:`property` as a decorator::
+   create read-only properties easily using :func:`property` as a :term:`decorator`::
 
       class Parrot(object):
           def __init__(self):
@@ -1015,7 +1015,7 @@ available.  They are listed here in alphabetical order.
 
    .. index:: single: Numerical Python
 
-   Return a slice object representing the set of indices specified by
+   Return a :term:`slice` object representing the set of indices specified by
    ``range(start, stop, step)``.  The *start* and *step* arguments default to
    ``None``.  Slice objects have read-only data attributes :attr:`start`,
    :attr:`stop` and :attr:`step` which merely return the argument values (or their
@@ -1063,8 +1063,8 @@ available.  They are listed here in alphabetical order.
           @staticmethod
           def f(arg1, arg2, ...): ...
 
-   The ``@staticmethod`` form is a function decorator -- see the description of
+   The ``@staticmethod`` form is a function :term:`decorator` -- see the
-   function definitions in :ref:`function` for details.
+   description of function definitions in :ref:`function` for details.
 
    It can be called either on the class (such as ``C.f()``) or on an instance (such
    as ``C().f()``).  The instance is ignored except for its class.

Doc/library/functools.rst

@@ -68,9 +68,9 @@ The :mod:`functools` module defines the following functions:
    *WRAPPER_UPDATES* (which updates the wrapper function's *__dict__*, i.e. the
    instance dictionary).
 
-   The main intended use for this function is in decorator functions which wrap the
+   The main intended use for this function is in :term:`decorator` functions which
-   decorated function and return the wrapper. If the wrapper function is not
+   wrap the decorated function and return the wrapper. If the wrapper function is
-   updated, the metadata of the returned function will reflect the wrapper
+   not updated, the metadata of the returned function will reflect the wrapper
    definition rather than the original function definition, which is typically less
    than helpful.
 

Doc/library/inspect.rst

@@ -235,7 +235,7 @@ Note:
 
 .. function:: isfunction(object)
 
-   Return true if the object is a Python function or unnamed (lambda) function.
+   Return true if the object is a Python function or unnamed (:term:`lambda`) function.
 
 
 .. function:: istraceback(object)

Doc/library/operator.rst

@@ -280,10 +280,10 @@ Operations which work with sequences include:
 
 Many operations have an "in-place" version.  The following functions provide a
 more primitive access to in-place operators than the usual syntax does; for
-example, the statement ``x += y`` is equivalent to ``x = operator.iadd(x, y)``.
+example, the :term:`statement` ``x += y`` is equivalent to
-Another way to put it is to say that ``z = operator.iadd(x, y)`` is equivalent
+``x = operator.iadd(x, y)``.  Another way to put it is to say that
-to the compound statement ``z = x; z += y``.
+``z = operator.iadd(x, y)`` is equivalent to the compound statement
-
+``z = x; z += y``.
 
 .. function:: iadd(a, b)
               __iadd__(a, b)

Doc/library/sets.rst

@@ -228,9 +228,9 @@ Sets can only contain immutable elements.  For convenience, mutable :class:`Set`
 objects are automatically copied to an :class:`ImmutableSet` before being added
 as a set element.
 
-The mechanism is to always add a hashable element, or if it is not hashable, the
+The mechanism is to always add a :term:`hashable` element, or if it is not
-element is checked to see if it has an :meth:`__as_immutable__` method which
+hashable, the element is checked to see if it has an :meth:`__as_immutable__`
-returns an immutable equivalent.
+method which returns an immutable equivalent.
 
 Since :class:`Set` objects have a :meth:`__as_immutable__` method returning an
 instance of :class:`ImmutableSet`, it is possible to construct sets of sets.

Doc/library/stdtypes.rst

@@ -2191,8 +2191,8 @@ decimal arithmetic context. The specific types are not treated specially beyond
 their implementation of the context management protocol. See the
 :mod:`contextlib` module for some examples.
 
-Python's :term:`generator`\s and the ``contextlib.contextfactory`` decorator provide a
+Python's :term:`generator`\s and the ``contextlib.contextfactory`` :term:`decorator`
-convenient way to implement these protocols.  If a generator function is
+provide a convenient way to implement these protocols.  If a generator function is
 decorated with the ``contextlib.contextfactory`` decorator, it will return a
 context manager implementing the necessary :meth:`__enter__` and
 :meth:`__exit__` methods, rather than the iterator produced by an undecorated

Doc/library/sys.rst

@@ -86,9 +86,9 @@ always available.
    If *value* is not ``None``, this function prints it to ``sys.stdout``, and saves
    it in ``__builtin__._``.
 
-   ``sys.displayhook`` is called on the result of evaluating an expression entered
+   ``sys.displayhook`` is called on the result of evaluating an :term:`expression`
-   in an interactive Python session.  The display of these values can be customized
+   entered in an interactive Python session.  The display of these values can be
-   by assigning another one-argument function to ``sys.displayhook``.
+   customized by assigning another one-argument function to ``sys.displayhook``.
 
 
 .. function:: excepthook(type, value, traceback)
@@ -617,12 +617,12 @@ always available.
    File objects corresponding to the interpreter's standard input, output and error
    streams.  ``stdin`` is used for all interpreter input except for scripts but
    including calls to :func:`input` and :func:`raw_input`.  ``stdout`` is used for
-   the output of :keyword:`print` and expression statements and for the prompts of
+   the output of :keyword:`print` and :term:`expression` statements and for the
-   :func:`input` and :func:`raw_input`. The interpreter's own prompts and (almost
+   prompts of :func:`input` and :func:`raw_input`. The interpreter's own prompts
-   all of) its error messages go to ``stderr``.  ``stdout`` and ``stderr`` needn't
+   and (almost all of) its error messages go to ``stderr``.  ``stdout`` and
-   be built-in file objects: any object is acceptable as long as it has a
+   ``stderr`` needn't be built-in file objects: any object is acceptable as long
-   :meth:`write` method that takes a string argument.  (Changing these objects
+   as it has a :meth:`write` method that takes a string argument.  (Changing these 
-   doesn't affect the standard I/O streams of processes executed by
+   objects doesn't affect the standard I/O streams of processes executed by
    :func:`os.popen`, :func:`os.system` or the :func:`exec\*` family of functions in
    the :mod:`os` module.)
 

Doc/library/timeit.rst

@@ -88,11 +88,12 @@ The module defines the following public class:
 
    .. note::
 
-      By default, :meth:`timeit` temporarily turns off garbage collection during the
+      By default, :meth:`timeit` temporarily turns off :term:`garbage collection`
-      timing.  The advantage of this approach is that it makes independent timings
+      during the timing.  The advantage of this approach is that it makes
-      more comparable.  This disadvantage is that GC may be an important component of
+      independent timings more comparable.  This disadvantage is that GC may be
-      the performance of the function being measured.  If so, GC can be re-enabled as
+      an important component of the performance of the function being measured.
-      the first statement in the *setup* string.  For example::
+      If so, GC can be re-enabled as the first statement in the *setup* string.
+      For example::
 
          timeit.Timer('for i in xrange(10): oct(i)', 'gc.enable()').timeit()
 

Doc/library/weakref.rst

@@ -22,22 +22,22 @@ In the following, the term :dfn:`referent` means the object which is referred to
 by a weak reference.
 
 A weak reference to an object is not enough to keep the object alive: when the
-only remaining references to a referent are weak references, garbage collection
+only remaining references to a referent are weak references,
-is free to destroy the referent and reuse its memory for something else.  A
+:term:`garbage collection` is free to destroy the referent and reuse its memory
-primary use for weak references is to implement caches or mappings holding large
+for something else.  A primary use for weak references is to implement caches or
-objects, where it's desired that a large object not be kept alive solely because
+mappings holding large objects, where it's desired that a large object not be
-it appears in a cache or mapping.  For example, if you have a number of large
+kept alive solely because it appears in a cache or mapping.  For example, if you
-binary image objects, you may wish to associate a name with each.  If you used a
+have a number of large binary image objects, you may wish to associate a name
-Python dictionary to map names to images, or images to names, the image objects
+with each.  If you used a Python dictionary to map names to images, or images to
-would remain alive just because they appeared as values or keys in the
+names, the image objects would remain alive just because they appeared as values
-dictionaries.  The :class:`WeakKeyDictionary` and :class:`WeakValueDictionary`
+or keys in the dictionaries.  The :class:`WeakKeyDictionary` and
-classes supplied by the :mod:`weakref` module are an alternative, using weak
+:class:`WeakValueDictionary` classes supplied by the :mod:`weakref` module are
-references to construct mappings that don't keep objects alive solely because
+an alternative, using weak references to construct mappings that don't keep
-they appear in the mapping objects.  If, for example, an image object is a value
+objects alive solely because they appear in the mapping objects.  If, for
-in a :class:`WeakValueDictionary`, then when the last remaining references to
+example, an image object is a value in a :class:`WeakValueDictionary`, then when
-that image object are the weak references held by weak mappings, garbage
+the last remaining references to that image object are the weak references held
-collection can reclaim the object, and its corresponding entries in weak
+by weak mappings, garbage collection can reclaim the object, and its
-mappings are simply deleted.
+corresponding entries in weak mappings are simply deleted.
 
 :class:`WeakKeyDictionary` and :class:`WeakValueDictionary` use weak references
 in their implementation, setting up callback functions on the weak references

Doc/reference/compound_stmts.rst

@@ -428,7 +428,7 @@ when the function is called.
 The function definition does not execute the function body; this gets executed
 only when the function is called.
 
-A function definition may be wrapped by one or more decorator expressions.
+A function definition may be wrapped by one or more :term:`decorator` expressions.
 Decorator expressions are evaluated when the function is defined, in the scope
 that contains the function definition.  The result must be a callable, which is
 invoked with the function object as the only argument. The returned value is

Doc/tutorial/stdlib2.rst

@@ -239,8 +239,8 @@ Weak References
 ===============
 
 Python does automatic memory management (reference counting for most objects and
-garbage collection to eliminate cycles).  The memory is freed shortly after the
+:term:`garbage collection` to eliminate cycles).  The memory is freed shortly
-last reference to it has been eliminated.
+after the last reference to it has been eliminated.
 
 This approach works fine for most applications but occasionally there is a need
 to track objects only as long as they are being used by something else.