* Add new toplevel chapter, "Using Python." (how to install,

  configure and setup python on different platforms -- at least
  in theory.)
* Move the Python on Mac docs in that chapter.
* Add a new chapter about the command line invocation, by stargaming.

3 files changed, 646 insertions, 0 deletions

diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
new file mode 100644
index 0000000..8a647af
--- /dev/null
+++ b/Doc/using/cmdline.rst
@@ -0,0 +1,427 @@
+.. highlightlang:: none
+
+Invoking the Python executable
+==============================
+
+The CPython interpreter scans the command line and the environment for various
+settings.
+
+.. note:: 
+   
+   Other implementation's command line schemes may differ.  See
+   :ref:`implementations` for further resources.
+
+
+Command line
+------------
+
+When invoking Python, you may specify any of these options::
+
+    python [-dEiOQStuUvxX3?] [-c command | -m module-name | script | - ] [args]
+
+The most common use case is, of course, a simple invocation of a script::
+
+    python myscript.py
+
+
+Interface options
+~~~~~~~~~~~~~~~~~
+
+The interpreter interface resembles that of the UNIX shell:
+
+* When called with standard input connected to a tty device, it prompts for
+  commands and executes them until an EOF (an end-of-file character, you can
+  produce that with *Ctrl-D* on UNIX or *Ctrl-Z, Enter* on Windows) is read.
+* When called with a file name argument or with a file as standard input, it
+  reads and executes a script from that file.
+* When called with ``-c command``, it executes the Python statement(s) given as
+  *command*.  Here *command* may contain multiple statements separated by
+  newlines. Leading whitespace is significant in Python statements!
+* When called with ``-m module-name``, the given module is searched on the
+  Python module path and executed as a script.
+
+In non-interactive mode, the entire input is parsed before it is executed.
+
+An interface option terminates the list of options consumed by the interpreter,
+all consecutive arguments will end up in :data:`sys.argv` -- note that the first
+element, subscript zero (``sys.argv[0]``), is a string reflecting the program's
+source.
+
+.. cmdoption:: -c <command>
+
+   Execute the Python code in *command*.  *command* can be one ore more
+   statements separated by newlines, with significant leading whitespace as in
+   normal module code.
+   
+   If this option is given, the first element of :data:`sys.argv` will be
+   ``"-c"``.
+
+
+.. cmdoption:: -m <module-name>
+
+   Search :data:`sys.path` for the named module and run the corresponding module
+   file as if it were executed with ``python modulefile.py`` as a script.
+   
+   Since the argument is a *module* name, you must not give a file extension
+   (``.py``).  However, the ``module-name`` does not have to be a valid Python
+   identifer (e.g. you can use a file name including a hyphen).
+
+   .. note::
+
+      This option cannot be used with builtin modules and extension modules
+      written in C, since they do not have Python module files.
+   
+   If this option is given, the first element of :data:`sys.argv` will be the
+   full path to the module file.
+   
+   Many standard library modules contain code that is invoked on their execution
+   as a script.  An example is the :mod:`timeit` module::
+
+       python -mtimeit -s 'setup here' 'benchmarked code here'
+       python -mtimeit -h # for details
+
+   .. seealso:: 
+      :func:`runpy.run_module`
+         The actual implementation of this feature.
+
+      :pep:`338` -- Executing modules as scripts
+
+   .. versionchanged:: 2.5
+      The module name can now include packages.
+
+
+.. describe:: <script>
+
+   Execute the Python code contained in *script*, which must be an (absolute or
+   relative) file name.
+
+   If this option is given, the first element of :data:`sys.argv` will be the
+   script file name as given on the command line.
+
+
+.. describe:: -
+
+   Read commands from standard input (:data:`sys.stdin`).  If standard input is
+   a terminal, :option:`-i` is implied.
+
+   If this option is given, the first element of :data:`sys.argv` will be
+   ``"-"``.
+
+   .. seealso:: 
+      :ref:`tut-invoking`
+
+
+If no script name is given, ``sys.argv[0]`` is an empty string (``""``).
+
+
+Generic options
+~~~~~~~~~~~~~~~
+
+.. cmdoption:: -?
+               -h
+               --help
+
+   Print a short description of all command line options.
+
+   .. versionadded:: 2.5
+      The ``--help`` variant.
+
+
+.. cmdoption:: -V
+               --version
+
+   Print the Python version number and exit.  Example output could be::
+    
+       Python 2.5.1
+
+   .. versionadded:: 2.5
+      The ``--version`` variant.
+
+
+Miscellaneous options
+~~~~~~~~~~~~~~~~~~~~~
+
+.. cmdoption:: -d
+
+   Turn on parser debugging output (for wizards only, depending on compilation
+   options).  See also :envvar:`PYTHONDEBUG`.
+
+
+.. cmdoption:: -E
+
+   Ignore environment variables like :envvar:`PYTHONPATH` and
+   :envvar:`PYTHONHOME` that modify the behaviour of the interpreter.
+
+   .. XXX: full list?
+
+
+.. cmdoption:: -i
+
+   When a script is passed as first argument or the :option:`-c` option is used,
+   enter interactive mode after executing the script or the command, even when
+   :data:`sys.stdin` does not appear to be a terminal.  The
+   :envvar:`PYTHONSTARTUP` file is not read.
+   
+   This can be useful to inspect global variables or a stack trace when a script
+   raises an exception.  See also :envvar:`PYTHONINSPECT`.
+
+
+.. cmdoption:: -O
+
+   Turn on basic optimizations.  This changes the filename extension for
+   compiled (:term:`byte code`) files from ``.pyc`` to ``.pyo``.  See also
+   :envvar:`PYTHONOPTIMIZE`.
+
+
+.. cmdoption:: -OO
+
+   Discard docstrings in addition to the :option:`-O` optimizations.
+
+
+.. cmdoption:: -Q <arg>
+
+   Division control. The argument must be one of the following:
+   
+   ``old``
+     division of int/int and long/long return an int or long (*default*)
+   ``new``
+     new division semantics, i.e. division of int/int and long/long returns a
+     float
+   ``warn``
+     old division semantics with a warning for int/int and long/long
+   ``warnall``
+     old division semantics with a warning for all uses of the division operator
+
+   .. seealso::
+      :file:`Tools/scripts/fixdiv.py`
+         for a use of ``warnall``
+
+      :pep:`238` -- Changing the division operator
+
+
+.. cmdoption:: -S
+
+   Disable the import of the module :mod:`site` and the site-dependent
+   manipulations of :data:`sys.path` that it entails.
+
+
+.. cmdoption:: -t
+
+   Issue a warning when a source file mixes tabs and spaces for indentation in a
+   way that makes it depend on the worth of a tab expressed in spaces.  Issue an
+   error when the option is given twice (:option:`-tt`).
+
+
+.. cmdoption:: -u
+   
+   Force stdin, stdout and stderr to be totally unbuffered.  On systems where it
+   matters, also put stdin, stdout and stderr in binary mode.
+   
+   Note that there is internal buffering in :func:`file.readlines` and
+   :ref:`bltin-file-objects` (``for line in sys.stdin``) which is not influenced
+   by this option.  To work around this, you will want to use
+   :func:`file.readline` inside a ``while 1:`` loop.
+
+   See also :envvar:`PYTHONUNBUFFERED`.
+
+
+.. XXX should the -U option be documented?
+
+.. cmdoption:: -v
+   
+   Print a message each time a module is initialized, showing the place
+   (filename or built-in module) from which it is loaded.  When given twice
+   (:option:`-vv`), print a message for each file that is checked for when
+   searching for a module.  Also provides information on module cleanup at exit.
+   See also :envvar:`PYTHONVERBOSE`.
+
+
+.. cmdoption:: -W arg
+   
+   Warning control.  Python's warning machinery by default prints warning
+   messages to :data:`sys.stderr`.  A typical warning message has the following
+   form::
+
+       file:line: category: message
+       
+   By default, each warning is printed once for each source line where it
+   occurs.  This option controls how often warnings are printed.
+
+   Multiple :option:`-W` options may be given; when a warning matches more than
+   one option, the action for the last matching option is performed.  Invalid
+   :option:`-W` options are ignored (though, a warning message is printed about
+   invalid options when the first warning is issued).
+   
+   Warnings can also be controlled from within a Python program using the
+   :mod:`warnings` module.
+
+   The simplest form of argument is one of the following action strings (or a
+   unique abbreviation):
+    
+   ``ignore``
+      Ignore all warnings.
+   ``default``
+      Explicitly request the default behavior (printing each warning once per
+      source line).
+   ``all``
+      Print a warning each time it occurs (this may generate many messages if a
+      warning is triggered repeatedly for the same source line, such as inside a
+      loop).
+   ``module``
+      Print each warning only only the first time it occurs in each module.
+   ``once``
+      Print each warning only the first time it occurs in the program.
+   ``error``
+      Raise an exception instead of printing a warning message.
+      
+   The full form of argument is:: 
+   
+       action:message:category:module:line
+
+   Here, *action* is as explained above but only applies to messages that match
+   the remaining fields.  Empty fields match all values; trailing empty fields
+   may be omitted.  The *message* field matches the start of the warning message
+   printed; this match is case-insensitive.  The *category* field matches the
+   warning category.  This must be a class name; the match test whether the
+   actual warning category of the message is a subclass of the specified warning
+   category.  The full class name must be given.  The *module* field matches the
+   (fully-qualified) module name; this match is case-sensitive.  The *line*
+   field matches the line number, where zero matches all line numbers and is
+   thus equivalent to an omitted line number.
+
+   .. seealso::
+
+      :pep:`230` -- Warning framework
+
+
+.. cmdoption:: -x
+   
+   Skip the first line of the source, allowing use of non-Unix forms of
+   ``#!cmd``.  This is intended for a DOS specific hack only.
+   
+   .. warning:: The line numbers in error messages will be off by one!
+
+
+.. cmdoption:: -3
+
+   Warn about Python 3.x incompatibilities.
+
+   .. versionadded:: 2.6
+
+
+Related files -- UNIX
+---------------------
+
+These are subject to difference depending on local installation conventions;
+:envvar:`prefix` (``${prefix}``) and :envvar:`exec_prefix` (``${exec_prefix}``)
+are installation-dependent and should be interpreted as for GNU software; they
+may be the same.
+
+For example, on most Linux systems, the default for both is :file:`/usr`.
+
++-----------------------------------------------+------------------------------------------+
+| File/directory                                | Meaning                                  |
++===============================================+==========================================+
+| :file:`{exec_prefix}/bin/python`              | Recommended location of the interpreter. |
++-----------------------------------------------+------------------------------------------+
+| :file:`{prefix}/lib/python{version}`,         | Recommended locations of the directories |
+| :file:`{exec_prefix}/lib/python{version}`     | containing the standard modules.         |
++-----------------------------------------------+------------------------------------------+
+| :file:`{prefix}/include/python{version}`,     | Recommended locations of the directories |
+| :file:`{exec_prefix}/include/python{version}` | containing the include files needed for  |
+|                                               | developing Python extensions and         |
+|                                               | embedding the interpreter.               |
++-----------------------------------------------+------------------------------------------+
+| :file:`~/.pythonrc.py`                        | User-specific initialization file loaded |
+|                                               | by the user module; not used by default  |
+|                                               | or by most applications.                 |
++-----------------------------------------------+------------------------------------------+
+
+
+Environment variables
+---------------------
+
+.. envvar:: PYTHONHOME
+   
+   Change the location of the standard Python libraries.  By default, the
+   libraries are searched in :file:`{prefix}/lib/python<version>` and
+   :file:`{exec_prefix}/lib/python<version>`, where :file:`{prefix}` and
+   :file:`{exec_prefix}` are installation-dependent directories, both defaulting
+   to :file:`/usr/local`.
+   
+   When :envvar:`PYTHONHOME` is set to a single directory, its value replaces
+   both :file:`{prefix}` and :file:`{exec_prefix}`.  To specify different values
+   for these, set :envvar:`PYTHONHOME` to :file:`{prefix}:{exec_prefix}``.
+
+
+.. envvar:: PYTHONPATH
+
+   Augments the default search path for module files.  The format is the same as
+   the shell's :envvar:`PATH`: one or more directory pathnames separated by
+   colons.  Non-existent directories are silently ignored.
+   
+   The default search path is installation dependent, but generally begins with
+   :file:`{prefix}/lib/python<version>`` (see :envvar:`PYTHONHOME` above).  It
+   is *always* appended to :envvar:`PYTHONPATH`.
+   
+   If a script argument is given, the directory containing the script is
+   inserted in the path in front of :envvar:`PYTHONPATH`.  The search path can
+   be manipulated from within a Python program as the variable :data:`sys.path`.
+
+
+.. envvar:: PYTHONSTARTUP
+   
+   If this is the name of a readable file, the Python commands in that file are
+   executed before the first prompt is displayed in interactive mode.  The file
+   is executed in the same name space where interactive commands are executed so
+   that objects defined or imported in it can be used without qualification in
+   the interactive session.  You can also change the prompts :data:`sys.ps1` and
+   :data:`sys.ps2` in this file.
+
+
+.. envvar:: PYTHONY2K
+   
+   Set this to a non-empty string to cause the :mod:`time` module to require
+   dates specified as strings to include 4-digit years, otherwise 2-digit years
+   are converted based on rules described in the :mod:`time` module
+   documentation.
+
+
+.. envvar:: PYTHONOPTIMIZE
+   
+   If this is set to a non-empty string it is equivalent to specifying the
+   :option:`-O` option.  If set to an integer, it is equivalent to specifying
+   :option:`-O` multiple times.
+
+
+.. envvar:: PYTHONDEBUG
+   
+   If this is set to a non-empty string it is equivalent to specifying the
+   :option:`-d` option.  If set to an integer, it is equivalent to specifying
+   :option:`-d` multiple times.
+
+
+.. envvar:: PYTHONINSPECT
+   
+   If this is set to a non-empty string it is equivalent to specifying the
+   :option:`-i` option.
+
+
+.. envvar:: PYTHONUNBUFFERED
+   
+   If this is set to a non-empty string it is equivalent to specifying the
+   :option:`-u` option.
+
+
+.. envvar:: PYTHONVERBOSE
+   
+   If this is set to a non-empty string it is equivalent to specifying the
+   :option:`-v` option.  If set to an integer, it is equivalent to specifying
+   :option:`-v` multiple times.
+
+
+.. envvar:: PYTHONCASEOK
+   
+   If this is set, Python ignores case in :keyword:`import` statements.  This
+   only works on Windows.
+
diff --git a/Doc/using/index.rst b/Doc/using/index.rst
new file mode 100644
index 0000000..f8d8ce4
--- /dev/null
+++ b/Doc/using/index.rst
@@ -0,0 +1,17 @@
+.. _using-index:
+
+################
+  Using Python
+################
+
+
+This part of the documentation is devoted to general information on the setup
+of the Python environment on different platform, the invocation of the
+interpreter and things that make working with Python easier.
+
+
+.. toctree::
+
+   cmdline.rst
+   mac.rst
+
diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst
new file mode 100644
index 0000000..7811f37
--- /dev/null
+++ b/Doc/using/mac.rst
@@ -0,0 +1,202 @@
+
+.. _using-on-mac:
+
+***************************
+Using Python on a Macintosh
+***************************
+
+:Author: Bob Savage <bobsavage@mac.com>
+
+
+Python on a Macintosh running Mac OS X is in principle very similar to Python on
+any other Unix platform, but there are a number of additional features such as
+the IDE and the Package Manager that are worth pointing out.
+
+The Mac-specific modules are documented in :ref:`mac-specific-services`.
+
+Python on Mac OS 9 or earlier can be quite different from Python on Unix or
+Windows, but is beyond the scope of this manual, as that platform is no longer
+supported, starting with Python 2.4. See http://www.cwi.nl/~jack/macpython for
+installers for the latest 2.3 release for Mac OS 9 and related documentation.
+
+
+.. _getting-osx:
+
+Getting and Installing MacPython
+================================
+
+Mac OS X 10.4 comes with Python 2.3 pre-installed by Apple. However, you are
+encouraged to install the most recent version of Python from the Python website
+(http://www.python.org). A "universal binary" build of Python 2.5, which runs
+natively on the Mac's new Intel and legacy PPC CPU's, is available there.
+
+What you get after installing is a number of things:
+
+* A :file:`MacPython 2.5` folder in your :file:`Applications` folder. In here
+  you find IDLE, the development environment that is a standard part of official
+  Python distributions; PythonLauncher, which handles double-clicking Python
+  scripts from the Finder; and the "Build Applet" tool, which allows you to
+  package Python scripts as standalone applications on your system.
+
+* A framework :file:`/Library/Frameworks/Python.framework`, which includes the
+  Python executable and libraries. The installer adds this location to your shell
+  path. To uninstall MacPython, you can simply remove these three things. A
+  symlink to the Python executable is placed in /usr/local/bin/.
+
+The Apple-provided build of Python is installed in
+:file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`,
+respectively. You should never modify or delete these, as they are
+Apple-controlled and are used by Apple- or third-party software.
+
+IDLE includes a help menu that allows you to access Python documentation. If you
+are completely new to Python you should start reading the tutorial introduction
+in that document.
+
+If you are familiar with Python on other Unix platforms you should read the
+section on running Python scripts from the Unix shell.
+
+
+How to run a Python script
+--------------------------
+
+Your best way to get started with Python on Mac OS X is through the IDLE
+integrated development environment, see section :ref:`ide` and use the Help menu
+when the IDE is running.
+
+If you want to run Python scripts from the Terminal window command line or from
+the Finder you first need an editor to create your script. Mac OS X comes with a
+number of standard Unix command line editors, :program:`vim` and
+:program:`emacs` among them. If you want a more Mac-like editor,
+:program:`BBEdit` or :program:`TextWrangler` from Bare Bones Software (see
+http://www.barebones.com/products/bbedit/index.shtml) are good choices, as is
+:program:`TextMate` (see http://macromates.com/). Other editors include
+:program:`Gvim` (http://macvim.org) and :program:`Aquamacs`
+(http://aquamacs.org).
+
+To run your script from the Terminal window you must make sure that
+:file:`/usr/local/bin` is in your shell search path.
+
+To run your script from the Finder you have two options:
+
+* Drag it to :program:`PythonLauncher`
+
+* Select :program:`PythonLauncher` as the default application to open your
+  script (or any .py script) through the finder Info window and double-click it.
+  :program:`PythonLauncher` has various preferences to control how your script is
+  launched. Option-dragging allows you to change these for one invocation, or use
+  its Preferences menu to change things globally.
+
+
+.. _osx-gui-scripts:
+
+Running scripts with a GUI
+--------------------------
+
+With older versions of Python, there is one Mac OS X quirk that you need to be
+aware of: programs that talk to the Aqua window manager (in other words,
+anything that has a GUI) need to be run in a special way. Use :program:`pythonw`
+instead of :program:`python` to start such scripts.
+
+With Python 2.5, you can use either :program:`python` or :program:`pythonw`.
+
+
+Configuration
+-------------
+
+Python on OS X honors all standard Unix environment variables such as
+:envvar:`PYTHONPATH`, but setting these variables for programs started from the
+Finder is non-standard as the Finder does not read your :file:`.profile` or
+:file:`.cshrc` at startup. You need to create a file :file:`~
+/.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for details.
+
+For more information on installation Python packages in MacPython, see section
+:ref:`mac-package-manager`.
+
+
+.. _ide:
+
+The IDE
+=======
+
+MacPython ships with the standard IDLE development environment. A good
+introduction to using IDLE can be found at http://hkn.eecs.berkeley.edu/
+dyoo/python/idle_intro/index.html.
+
+
+.. _mac-package-manager:
+
+Installing Additional Python Packages
+=====================================
+
+There are several methods to install additional Python packages:
+
+* http://pythonmac.org/packages/ contains selected compiled packages for Python
+  2.5, 2.4, and 2.3.
+
+* Packages can be installed via the standard Python distutils mode (``python
+  setup.py install``).
+
+* Many packages can also be installed via the :program:`setuptools` extension.
+
+
+GUI Programming on the Mac
+==========================
+
+There are several options for building GUI applications on the Mac with Python.
+
+*PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework, which is
+the foundation of most modern Mac development. Information on PyObjC is
+available from http://pyobjc.sourceforge.net.
+
+The standard Python GUI toolkit is :mod:`Tkinter`, based on the cross-platform
+Tk toolkit (http://www.tcl.tk). An Aqua-native version of Tk is bundled with OS
+X by Apple, and the latest version can be downloaded and installed from
+http://www.activestate.com; it can also be built from source.
+
+*wxPython* is another popular cross-platform GUI toolkit that runs natively on
+Mac OS X. Packages and documentation are available from http://www.wxpython.org.
+
+*PyQt* is another popular cross-platform GUI toolkit that runs natively on Mac
+OS X. More information can be found at
+http://www.riverbankcomputing.co.uk/pyqt/.
+
+
+Distributing Python Applications on the Mac
+===========================================
+
+The "Build Applet" tool that is placed in the MacPython 2.5 folder is fine for
+packaging small Python scripts on your own machine to run as a standard Mac
+application. This tool, however, is not robust enough to distribute Python
+applications to other users.
+
+The standard tool for deploying standalone Python applications on the Mac is
+:program:`py2app`. More information on installing and using py2app can be found
+at http://undefined.org/python/#py2app.
+
+
+Application Scripting
+=====================
+
+Python can also be used to script other Mac applications via Apple's Open
+Scripting Architecture (OSA); see http://appscript.sourceforge.net. Appscript is
+a high-level, user-friendly Apple event bridge that allows you to control
+scriptable Mac OS X applications using ordinary Python scripts. Appscript makes
+Python a serious alternative to Apple's own *AppleScript* language for
+automating your Mac. A related package, *PyOSA*, is an OSA language component
+for the Python scripting language, allowing Python code to be executed by any
+OSA-enabled application (Script Editor, Mail, iTunes, etc.). PyOSA makes Python
+a full peer to AppleScript.
+
+
+Other Resources
+===============
+
+The MacPython mailing list is an excellent support resource for Python users and
+developers on the Mac:
+
+http://www.python.org/community/sigs/current/pythonmac-sig/
+
+Another useful resource is the MacPython wiki:
+
+http://wiki.python.org/moin/MacPython
+