Patch #1698768: updated the "using Python on the Mac" intro.

2 files changed, 135 insertions, 173 deletions

diff --git a/Doc/mac/using.tex b/Doc/mac/using.tex
index bf3174d..5b5d9e8 100644
--- a/Doc/mac/using.tex
+++ b/Doc/mac/using.tex
@@ -13,206 +13,166 @@ for the latest 2.3 release for Mac OS 9 and related documentation.
 
 \section{Getting and Installing MacPython \label{getting-OSX}}
 
-Mac OS X 10.3 comes with Python 2.3 pre-installed by Apple.
-This installation does not come with the IDE and other additions, however,
-so to get these you need to install the \program{MacPython for Panther additions}
-from the MacPython website, \url{http://www.cwi.nl/\textasciitilde jack/macpython}.
-
-For MacPython 2.4, or for any MacPython on earlier releases of Mac OS X,
-you need to install a full distribution from the same website.
+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
+(\url{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:
 
 \begin{itemize}
-    \item A \file{MacPython-2.3} folder in your \file{Applications}
-    folder. In here you find the PythonIDE Integrated Development Environment;
-    PythonLauncher, which handles double-clicking Python scripts from
-    the Finder; and the Package Manager.
-    
-    \item A fairly standard \UNIX{} commandline Python interpreter in
-    \file{/usr/local/bin/python}, but without the usual
-    \file{/usr/local/lib/python}.
-    
-    \item A framework \file{/Library/Frameworks/Python.framework}, where
-    all the action really is, but which you usually do not have to be aware of.
+\item 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.
+
+\item 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/.
 \end{itemize}
 
-To uninstall MacPython you can simply remove these three things.
+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.
 
-If you use the ``additions'' installer to install on top of an existing
-Apple-Python you will not get the framework and the commandline interpreter,
-as they have been installed by Apple already, in
-\file{/System/Library/Frameworks/Python.framework} and
-\file{/usr/bin/python}, respectively. You should in principle never modify
-or delete these, as they are Apple-controlled and may be 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.
 
-PythonIDE contains an Apple Help Viewer book called "MacPython Help"
-which you can access through its help menu. If you are completely new to
-Python you should start reading the IDE 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.
 
-If you are familiar with Python on other \UNIX{} platforms you should
-read the section on running Python scripts from the \UNIX{} shell.
 
 \subsection{How to run a Python script}
 
-Your best way to get started with Python on Mac OS X is through the PythonIDE
-integrated development environment, see section \ref{IDE} and use the Help
-menu when the IDE is running.
+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 \url{http://www.barebones.com/products/bbedit/index.shtml}) are
-good choices.  \program{AppleWorks} or any other
-word processor that can save files in ASCII is also a possibility, including
-\program{TextEdit} which is included with OS X.
+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
+\url{http://www.barebones.com/products/bbedit/index.shtml}) are good choices, as
+is \program{TextMate} (see \url{http://macromates.com/}). Other editors include
+\program{Gvim} (\url{http://macvim.org}) and \program{Aquamacs}
+(\url{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. 
+\file{/usr/local/bin} is in your shell search path.
 
 To run your script from the Finder you have two options:
+
 \begin{itemize}
-    \item Drag it to \program{PythonLauncher}
-    \item Select \program{PythonLauncher} as the default application
-    to open your script (or any .py script) through the finder Info window
-    and double-click it.
+\item Drag it to \program{PythonLauncher}
+\item 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.
 \end{itemize}
 
-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.
 
 \subsection{Running scripts with a GUI \label{osx-gui-scripts}}
 
-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 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.
 
-\subsection{configuration}
+With Python 2.5, you can use either \program{python} or \program{pythonw}.
 
-MacPython honours 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{\textasciitilde /.MacOSX/environment.plist}.
-See Apple's Technical Document QA1067 for details.
+\subsection{Configuration}
 
-Installing additional Python packages is most easily done through the
-Package Manager, see the MacPython Help Book for details.
+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{\textasciitilde
+  /.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}, ``Installing Additional Python Packages.''
 
 
 \section{The IDE\label{IDE}}
 
-The \program{Python IDE} (Integrated Development Environment) is a
-separate application that acts as a text editor for your Python code,
-a class browser, a graphical debugger, and more.
-
-The online Python Help contains a quick walkthrough of the IDE that
-shows the major features and how to use them.
-
-\subsection{Using the ``Python Interactive'' window}
-
-Use this window like you would use a normal \UNIX{} command line
-interpreter.
-
-\subsection{Writing a Python Script \label{IDEwrite}}
-
-In addition to using the \program{Python IDE} interactively, you can
-also type out a complete Python program, saving it incrementally, and
-execute it or smaller selections of it.
-
-You can create a new script, open a previously saved script, and save
-your currently open script by selecting the appropriate item in the
-``File'' menu. Dropping a Python script onto the
-\program{Python IDE} will open it for editing.
-
-When the \program{Python IDE} saves a script, it uses the creator code
-settings which are available by clicking on the small black triangle
-on the top right of the document window, and selecting ``save
-options''. The default is to save the file with the \program{Python
-IDE} as the creator, this means that you can open the file for editing
-by simply double-clicking on its icon. You might want to change this
-behaviour so that it will be opened by the
-\program{PythonLauncher}, and run. To do this simply choose
-``PythonLauncher'' from the ``save options''. Note that these
-options are associated with the \emph{file} not the application.
-
-
-\subsection{Executing a script from within the IDE
-            \label{IDEexecution}}
-
-You can run the script in the frontmost window of the \program{Python
-IDE} by hitting the run all button.  You should be aware, however that
-if you use the Python convention \samp{if __name__ == "__main__":} the
-script will \emph{not} be ``__main__'' by default. To get that
-behaviour you must select the ``Run as __main__'' option from the
-small black triangle on the top right of the document window.  Note
-that this option is associated with the \emph{file} not the
-application. It \emph{will} stay active after a save, however; to shut
-this feature off simply select it again.
- 
-
-\subsection{``Save as'' versus ``Save as Applet''
-            \label{IDEapplet}}
-
-When you are done writing your Python script you have the option of
-saving it as an ``applet'' (by selecting ``Save as applet'' from the
-``File'' menu). This has a significant advantage in that you can drop
-files or folders onto it, to pass them to the applet the way
-command-line users would type them onto the command-line to pass them
-as arguments to the script. However, you should make sure to save the
-applet as a separate file, do not overwrite the script you are
-writing, because you will not be able to edit it again.
-
-Accessing the items passed to the applet via ``drag-and-drop'' is done
-using the standard \member{sys.argv} mechanism. See the general
-documentation for more
-% need to link to the appropriate place in non-Mac docs
-
-Note that saving a script as an applet will not make it runnable on a
-system without a Python installation.
-
-%\subsection{Debugger}
-% **NEED INFO HERE**
- 
-%\subsection{Module Browser}
-% **NEED INFO HERE**
- 
-%\subsection{Profiler}
-% **NEED INFO HERE**
-% end IDE
-
-%\subsection{The ``Scripts'' menu}
-% **NEED INFO HERE**
-
-\section{The Package Manager}
-
-Historically MacPython came with a number of useful extension packages
-included, because most Macintosh users do not have access to a development
-environment and C compiler. For Mac OS X that bundling is no longer done,
-but a new mechanism has been made available to allow easy access to
-extension packages.
-
-The Python Package Manager helps you installing additional packages
-that enhance Python. It determines the exact MacOS version  and Python
-version you have and uses that information to download  a database that
-has packages that are tested and tried on that combination. In other
-words: if something is in your Package Manager  window but does not work
-you are free to blame the database maintainer.
-
-PackageManager then checks which of the packages you have installed  and
-which ones are not. This should also work when you have installed packages 
-outside of PackageManager.  You can select packages and install them,
-and PackageManager will work out the requirements and install these too.
-
-Often PackageManager will list a package in two flavors: binary  and
-source. Binary should always work, source will only work if  you have
-installed the Apple Developer Tools. PackageManager will warn  you about
-this, and also about other external dependencies.
-
-PackageManager is available as a separate application and also  as a
-function of the IDE, through the File->Package Manager menu  entry.
+MacPython ships with the standard IDLE development environment. A good
+introduction to using IDLE can be found at
+\url{http://hkn.eecs.berkeley.edu/~dyoo/python/idle_intro/index.html}.
+
+
+\section{Installing Additional Python Packages \label{mac-package-manager}}
+
+There are several methods to install additional Python packages:
+
+\begin{itemize}
+\item \url{http://pythonmac.org/packages/} contains selected compiled packages
+  for Python 2.5, 2.4, and 2.3.
+\item Packages can be installed via the standard Python distutils mode
+  (\samp{python setup.py install}).
+\item Many packages can also be installed via the \program{setuptools}
+  extension.
+\end{itemize}
+
+
+\section{GUI Programming on the Mac}
+
+There are several options for building GUI applications on the Mac with Python.
+
+\emph{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 \url{http://pybojc.sourceforge.net}.
+
+The standard Python GUI toolkit is \module{Tkinter}, based on the cross-platform
+Tk toolkit (\url{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
+\url{http://www.activestate.com}; it can also be built from source.
+
+\emph{wxPython} is another popular cross-platform GUI toolkit that runs natively
+on Mac OS X. Packages and documentation are available from
+\url{http://www.wxpython.org}.
+
+\emph{PyQt} is another popular cross-platform GUI toolkit that runs natively on
+Mac OS X. More information can be found at
+\url{http://www.riverbankcomputing.co.uk/pyqt/}.
+
+
+\section{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 \url{http://undefined.org/python/#py2app}.
+
+\section{Application Scripting}
+
+Python can also be used to script other Mac applications via Apple's Open
+Scripting Architecture (OSA); see
+\url{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 \emph{AppleScript} language for automating your Mac. A related
+package, \emph{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.
+
+\section{Other Resources}
+
+The MacPython mailing list is an excellent support resource for Python users and
+developers on the Mac:
+
+\url{http://www.python.org/community/sigs/current/pythonmac-sig/}
+
+Another useful resource is the MacPython wiki:
+
+\url{http://wiki.python.org/moin/MacPython}
diff --git a/Misc/NEWS b/Misc/NEWS
index 96d427c..36a18c2 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -755,6 +755,8 @@ Tools
 Documentation
 -------------
 
+- Patch #1698768: updated the "using Python on the Mac" intro.
+
 - Bug #1569057: Document that calling file.next() when the file is open for
   writing is undefined.