Moved all the scripting stuff to a separate section, added all the

missing bits (well, all the bits I could think of) and updated the
rest.

7 files changed, 394 insertions, 40 deletions

diff --git a/Doc/mac/libaepack.tex b/Doc/mac/libaepack.tex
index b8276be..6c275bd 100644
--- a/Doc/mac/libaepack.tex
+++ b/Doc/mac/libaepack.tex
@@ -45,7 +45,7 @@ the Python string representation of a value (the repr() function)
 encoded as a text descriptor.
 \end{funcdesc}
 
-\begin{funcdesc}{unpack}{x}
+\begin{funcdesc}{unpack}{x\optional{, formodulename}}
   \var{x} must be an object of type \class{AEDesc}. This function
   returns a Python object representation of the data in the Apple
   Event descriptor \var{x}. Simple AppleEvent data types (integer,
@@ -53,16 +53,26 @@ encoded as a text descriptor.
   Apple Event lists are returned as Python lists, and the list
   elements are recursively unpacked.  Object references
   (ex. \code{line 3 of document 1}) are returned as instances of
-  \class{aetypes.ObjectSpecifier}.  AppleEvent descriptors with
+  \class{aetypes.ObjectSpecifier}, unless \code{formodulename}
+  is specified.  AppleEvent descriptors with
   descriptor type typeFSS are returned as \class{FSSpec}
   objects.  AppleEvent record descriptors are returned as Python
-  dictionaries, with keys of type \class{?} and elements recursively
+  dictionaries, with 4-character string keys and elements recursively
   unpacked.
+  
+  The optional \code{formodulename} argument is used by the stub packages
+  generated by \module{gensuitemodule}, and ensures that the OSA classes
+  for object specifiers are looked up in the correct module. This ensures
+  that if, say, the Finder returns an object specifier for a window
+  you get an instance of \code{Finder.Window} and not a generic
+  \code{aetypes.Window}. The former knows about all the properties
+  and elements a window has in the Finder, while the latter knows
+  no such things.
 \end{funcdesc}
 
 
 \begin{seealso}
-  \seemodule{AE}{Built-in access to Apple Event Manager routines.}
+  \seemodule{Carbon.AE}{Built-in access to Apple Event Manager routines.}
   \seemodule{aetypes}{Python definitions of codes for Apple Event
                       descriptor types.}
   \seetitle[http://developer.apple.com/techpubs/mac/IAC/IAC-2.html]{
diff --git a/Doc/mac/libaetools.tex b/Doc/mac/libaetools.tex
new file mode 100644
index 0000000..463755b
--- /dev/null
+++ b/Doc/mac/libaetools.tex
@@ -0,0 +1,83 @@
+\section{\module{aetools} ---
+         OSA client support}
+
+\declaremodule{standard}{aetools}
+  \platform{Mac}
+%\moduleauthor{Jack Jansen?}{email}
+\modulesynopsis{Basic support for sending Apple Events}
+\sectionauthor{Jack Jansen}{Jack.Jansen@cwi.nl}
+
+
+The \module{aetools} module contains the basic functionality
+on which Python AppleScript client support is built. It also
+imports and re-exports the core functionality of the
+\module{aetypes} and \module{aepack} modules. The stub packages
+generated by \module{gensuitemodule} import the relevant
+portions of \module{aetools}, so usually you do not need to
+import it yourself. The exception to this is when you
+cannot use a generated suite package and need lower-level
+access to scripting.
+
+The \module{aetools} module itself uses the AppleEvent support
+provided by the \module{Carbon.AE} module. This has one drawback:
+you need access to the window manager, see section \ref{osx-gui-scripts}
+for details. This restriction may be lifted in future releases.
+
+
+The \module{aetools} module defines the following functions:
+
+\begin{funcdesc}{packevent}{ae, parameters, attributes}
+Stores parameters and attributes in a pre-created \code{Carbon.AE.AEDesc}
+object. \code{parameters} and \code{attributes} are 
+dictionaries mapping 4-character OSA parameter keys to Python objects. The
+objects are packed using \code{aepack.pack()}.
+\end{funcdesc}
+
+\begin{funcdesc}{unpackevent}{ae\optional{, formodulename}}
+Recursively unpacks a \code{Carbon.AE.AEDesc} event to Python objects.
+The function returns the parameter dictionary and the attribute dictionary.
+The \code{formodulename} argument is used by generated stub packages to
+control where AppleScript classes are looked up.
+\end{funcdesc}
+
+\begin{funcdesc}{keysubst}{arguments, keydict}
+Converts a Python keyword argument dictionary \code{arguments} to
+the format required by \code{packevent} by replacing the keys,
+which are Python identifiers, by the four-character OSA keys according
+to the mapping specified in \code{keydict}. Used by the generated suite
+packages.
+\end{funcdesc}
+
+\begin{funcdesc}{enumsubst}{arguments, key, edict}
+If the \code{arguments} dictionary contains an entry for \code{key}
+convert the value for that entry according to dictionary \code{edict}.
+This converts human-readable Python enumeration names to the OSA 4-character
+codes.
+Used by the generated suite
+packages.
+\end{funcdesc}
+
+The \module{aetools} module defines the following class:
+
+\begin{classdesc}{TalkTo}{\optional{signature=None, start=0, timeout=0}}
+
+Base class for the proxy used to talk to an application. \code{signature}
+overrides the class attribute \code{_signature} (which is usually set by subclasses)
+and is the 4-char creator code defining the application to talk to.
+\code{start} can be set to true to enable running the application on
+class instantiation. \code{timeout} can be specified to change the
+default timeout used while waiting for an AppleEvent reply.
+\end{classdesc}
+
+\begin{methoddesc}{_start}{}
+Test whether the application is running, and attempt to start it if not.
+\end{methoddesc}
+
+\begin{methoddesc}{send}{code, subcode\optional{, parameters, attributes}}
+Create the AppleEvent \code{Carbon.AE.AEDesc} for the verb with
+the OSA designation \code{code, subcode} (which are the usual 4-character
+strings), pack the \code{parameters} and \code{attributes} into it, send it
+to the target application, wait for the reply, unpack the reply with
+\code{unpackevent} and return the reply appleevent, the unpacked return values
+as a dictionary and the return attributes.
+\end{methoddesc}
diff --git a/Doc/mac/libaetypes.tex b/Doc/mac/libaetypes.tex
index 0c2795a..1b6046d 100644
--- a/Doc/mac/libaetypes.tex
+++ b/Doc/mac/libaetypes.tex
@@ -8,32 +8,128 @@
 \sectionauthor{Vincent Marchetti}{vincem@en.com}
 
 
-The \module{aetypes} defines classes used to represent Apple Event
-object specifiers. An object specifier is essentially an address of an
-object implemented in a Apple Event server. An Apple Event specifier
-is used as the direct object for an Apple Event or as the argument of
-an optional parameter. In AppleScript an object specifier is
-represented by a phrase such as:
-\code{character 23 of document "Semprini"}. The classes defined in
-this module allow this specifier to be represented by a Python object
-which is initialized as follows:
-\code{res = Document(1).Character(23)}
-
-
-The \module{AEObjects} module defines the following class:
-
-\begin{classdesc}{ObjectSpecifier}{want, form, seld, from}
-  This is the base class for representing object specifiers and is
-  generally not constructed directly by the user. Its important
-  functionality is to define an \function{__aepack__()} function,
-  which returns the Apple Event descriptor containing the object
-  specifier.  Its data members, set directly from the constructor
-  arguments, are:
-\end{classdesc}
-
-\begin{memberdesc}{want}
-  A four character string representing the class code of the
-  object. These class codes are specified in Apple Event Suites; for
-  example the standard code for a character object is the 4 bytes
-  \samp{char}.
-\end{memberdesc}
+The \module{aetypes} defines classes used to represent Apple Event data
+descriptors and Apple Event object specifiers.
+
+Apple Event data is is contained in descriptors, and these descriptors
+are typed. For many descriptors the Python representation is simply the
+corresponding Python type: \code{typeText} in OSA is a Python string,
+\code{typeFloat} is a float, etc. For OSA types that have no direct
+Python counterpart this module declares classes. Packing and unpacking
+instances of these classes is handled automatically by \module{aepack}.
+
+An object specifier is essentially an address of an object implemented
+in a Apple Event server. An Apple Event specifier is used as the direct
+object for an Apple Event or as the argument of an optional parameter.
+The \module{aetypes} module contains the base classes for OSA classes
+and properties, which are used by the packages generated by
+\module{gensuitemodule} to populate the classes and properties in a
+given suite.
+
+For reasons of backward compatibility, and for cases where you need to
+script an application for which you have not generated the stub package
+this module also contains object specifiers for a number of common OSA
+classes such as \code{Document}, \code{Window}, \code{Character}, etc.
+
+
+
+The \module{AEObjects} module defines the following classes to represent
+Apple Event descriptor data:
+
+\begin{classdesc}{Unknown}{type, data}
+The representation of OSA descriptor data for which the \module{aepack}
+and \module{aetypes} modules have no support, i.e. anything that is not
+represented by the other classes here and that is not equivalent to a
+simple Python value.
+\end{classdesc}
+
+\begin{classdesc}{Enum}{enum}
+An enumeration value with the given 4-character string value.
+\end{classdesc}
+
+\begin{classdesc}{InsertionLoc}{of, pos}
+Position \code{pos} in object \code{of}.
+\end{classdesc}
+
+\begin{classdesc}{Boolean}{bool}
+A boolean.
+\end{classdesc}
+
+\begin{classdesc}{StyledText}{style, text}
+Text with style information (font, face, etc) included.
+\end{classdesc}
+
+\begin{classdesc}{AEText}{script, style, text}
+Text with script system and style information included.
+\end{classdesc}
+
+\begin{classdesc}{IntlText}{script, language, text}
+Text with script system and language information included.
+\end{classdesc}
+
+\begin{classdesc}{IntlWritingCode}{script, language}
+Script system and language information.
+\end{classdesc}
+
+\begin{classdesc}{QDPoint}{v, h}
+A quickdraw point.
+\end{classdesc}
+
+\begin{classdesc}{QDRectangle}{v0, h0, v1, h1}
+A quickdraw rectangle.
+\end{classdesc}
+
+\begin{classdesc}{RGBColor}{r, g, b}
+A color.
+\end{classdesc}
+
+\begin{classdesc}{Type}{type}
+An OSA type value with the given 4-character name.
+\end{classdesc}
+
+\begin{classdesc}{Keyword}{name}
+An OSA keyword with the given 4-character name.
+\end{classdesc}
+
+\begin{classdesc}{Range}{start, stop}
+A range.
+\end{classdesc}
+
+\begin{classdesc}{Ordinal}{abso}
+Non-numeric absolute positions, such as \code{"firs"}, first, or \code{"midd"},
+middle.
+\end{classdesc}
+
+\begin{classdesc}{Logical}{logc, term}
+The logical expression of applying operator \code{logc} to
+\code{term}.
+\end{classdesc}
+
+\begin{classdesc}{Comparison}{obj1, relo, obj2}
+The comparison \code{relo} of \code{obj1} to \code{obj2}.
+\end{classdesc}
+
+The following classes are used as base classes by the generated stub
+packages to represent AppleScript classes and properties in Python:
+
+\begin{classdesc}{ComponentItem}{which\optional{, fr}}
+Abstract baseclass for an OSA class. The subclass should set the class
+attribute \code{want} to the 4-character OSA class code. Instances of
+subclasses of this class are equivalent to AppleScript Object
+Specifiers. Upon instantiation you should pass a selector in
+\code{which}, and optionally a parent object in \code{fr}.
+\end{classdesc}
+
+\begin{classdesc}{NProperty}{fr}
+Abstract basclass for an OSA property. The subclass should set the class
+attributes \code{want} and \code{which} to designate which property we
+are talking about. Instances of subclasses of this class are Object
+Specifiers.
+\end{classdesc}
+
+\begin{classdesc}{ObjectSpecifier}{want, form, seld\optional{, fr}}
+Base class of \code{ComponentItem} and \code{NProperty}, a general
+OSA Object Specifier. See the Apple Open Scripting Architecture
+documentation for the parameters. Note that this class is not abstract.
+\end{classdesc}
+
diff --git a/Doc/mac/libgensuitemodule.tex b/Doc/mac/libgensuitemodule.tex
new file mode 100644
index 0000000..5ab0cfd
--- /dev/null
+++ b/Doc/mac/libgensuitemodule.tex
@@ -0,0 +1,64 @@
+\section{\module{gensuitemodule} ---
+         Generate OSA stub packages}
+
+\declaremodule{standard}{gensuitemodule}
+  \platform{Mac}
+%\moduleauthor{Jack Jansen?}{email}
+\modulesynopsis{Create a stub package from an OSA dictionary}
+\sectionauthor{Jack Jansen}{Jack.Jansen@cwi.nl}
+
+The \module{gensuitemodule} module creates a Python package implementing
+stub code for the AppleScript suites that are implemented by a specific
+application, according to its AppleScript dictionary.
+
+It is usually invoked by the user through the \program{PythonIDE}, but
+it can also be run as a script from the command line (pass \code{--help}
+for help on the options) or imported from Python code. For an example of
+its use see \file{Mac/scripts/genallsuites.py} in a source distribution,
+which generates the stub packages that are included in the standard
+library.
+
+It defines the following public functions:
+
+\begin{funcdesc}{is_scriptable}{application}
+Returns true if \code{application}, which should be passed as a pathname,
+appears to be scriptable. Take the return value with a grain of salt:
+\program{Internet Explorer} appears not to be scriptable but definitely is.
+\end{funcdesc}
+
+\begin{funcdesc}{processfile}{application\optional{, output, basepkgname, 
+        edit_modnames, creatorsignature, dump, verbose}}
+Create a stub package for \code{application}, which should be passed as
+a full pathname. For a \file{.app} bundle this is the pathname to the
+bundle, not to the executable inside the bundle; for an unbundled CFM
+application you pass the filename of the application binary.
+
+This function asks the application for its OSA terminology resources,
+decodes these resources and uses the resultant data to create the Python
+code for the package implementing the client stubs.
+
+\code{output} is the pathname where the resulting package is stored, if
+not specified a standard "save file as" dialog is presented to
+the user. \code{basepkgname} is the base package on which this package
+will build, and defaults to \module{StdSuites}. Only when generating
+\module{StdSuites} itself do you need to specify this.
+\code{edit_modnames} is a dictionary that can be used to change
+modulenames that are too ugly after name mangling.
+\code{creator_signature} can be used to override the 4-char creator
+code, which is normally obtained from the \file{PkgInfo} file in the
+package or from the CFM file creator signature. When \code{dump} is
+given it should refer to a file object, and \code{processfile} will stop
+after decoding the resources and dump the Python representation of the
+terminology resources to this file. \code{verbose} should also be a file
+object, and specifying it will cause \code{processfile} to tell you what
+it is doing.
+\end{funcdesc}
+
+\begin{funcdesc}{processfile_fromresource}{application\optional{, output, 
+	basepkgname, edit_modnames, creatorsignature, dump, verbose}}
+This function does the same as \code{processfile}, except that it uses a
+different method to get the terminology resources. It opens \code{application}
+as a resource file and reads all \code{"aete"} and \code{"aeut"} resources
+from this file.
+\end{funcdesc}
+
diff --git a/Doc/mac/mac.tex b/Doc/mac/mac.tex
index bbbd3aa..41ff2d3 100644
--- a/Doc/mac/mac.tex
+++ b/Doc/mac/mac.tex
@@ -57,9 +57,8 @@ documented here:
 \input{libmacostools}
 \input{libmacui}
 \input{libframework}
-\input{libminiae}
-\input{libaepack}
-\input{libaetypes}
+
+\input{scripting}
 
 \input{toolbox}                         % MacOS Toolbox Modules
 \input{libcolorpicker}
diff --git a/Doc/mac/scripting.tex b/Doc/mac/scripting.tex
new file mode 100644
index 0000000..f126e3c
--- /dev/null
+++ b/Doc/mac/scripting.tex
@@ -0,0 +1,98 @@
+\chapter{MacPython OSA Modules \label{scripting}}
+
+Python has a fairly complete implementation of the Open Scripting
+Architecure (OSA, also commonly referred to as AppleScript), allowing
+you to control scriptable applications from your Python program,
+and with a fairly pythonic interface. 
+
+For a description of the various components of AppleScript and OSA, and
+to get an understanding of the architecture and terminology, you should
+read Apple's documentation. The "Applescript Language Guide" explains
+the conceptual model and the terminology, and documents the standard
+suite. The "Open Scripting Architecture" document explains how to use
+OSA from an application programmers point of view. In the Apple Help
+Viewer these book sare located in the Developer Documentation, Core
+Technologies section.
+
+
+As an example of scripting an application, the following piece of
+AppleScript will get the name of the frontmost \program{Finder} window
+and print it:
+	
+\begin{verbatim}
+tell application "Finder"
+    get name of window 1
+end tell
+\end{verbatim}
+
+In Python, the following code fragment will do the same:
+
+\begin{verbatim}
+import Finder
+
+f = Finder.Finder()
+print f.get(Finder.window(1).name)
+\end{verbatim}
+
+As distributed the Python library includes packages that implement the
+standard suites, plus packages that interface to a small number of
+common applications.
+
+To send AppleEvents to an application you must first create the Python
+package interfacing to the terminology of the application (what
+\program{Script Editor} calls the "Dictionary"). This can be done from
+within the \program{PythonIDE} or by running the
+\file{gensuitemodule.py} module as a standalone program from the command
+line.
+
+The generated output is a package with a number of modules, one for
+every suite used in the program plus an \module{__init__} module to glue
+it all together. The Python inheritance graph follows the AppleScript
+inheritance graph, so if a programs dictionary specifies that it
+includes support for the Standard Suite, but extends one or two verbs
+with extra arguments then the output suite will contain a module
+\module{Standard_Suite} that imports and re-exports everything from
+\module{StdSuites.Standard_Suite} but overrides the methods that have
+extra functionality. The output of \module{gensuitemodule} is pretty
+readable, and contains the documentation that was in the original
+AppleScript dictionary in Python docstrings, so reading it is a good
+source of documentation.
+
+The output package implements a main class with the same name as the
+package which contains all the AppleScript verbs as methods, with the
+direct object as the first argument and all optional parameters as
+keyword arguments. AppleScript classes are also implemented as Python
+classes, as are comparisons and all the other thingies.
+
+Note that in the current release there is no coupling between the main
+Python class implementing the verbs and the Python classes implementing
+the AppleScript classes. Hence, in the example above we need to use
+\code{f.get(Finder.window(1).name)} in stead of the more Pythonic
+\code{f.window(1).name.get()}.
+
+
+If an AppleScript identifier is not a Python identifier the name is
+mangled according to a small number of rules:
+\begin{itemize}
+    \item spaces are replaced with underscores
+    \item other non-alphanumeric characters are replaced with
+    \code{_xx_} where \code{xx} is the hexadecimal character value
+    \item any Python reserved word gets an underscore appended
+\end{itemize}
+
+Python also has support for creating scriptable applications
+in Python, but
+The following modules are relevant to MacPython AppleScript support:
+
+\localmoduletable
+
+In addition, support modules have been pre-generated for
+\module{Finder}, \module{Terminal}, \module{Explorer},
+\module{Netscape}, \module{CodeWarrior}, \module{SystemEvents} and
+\module{StdSuites}.
+
+\input{libgensuitemodule}
+\input{libaetools}
+\input{libaepack}
+\input{libaetypes}
+\input{libminiae}
diff --git a/Doc/mac/using.tex b/Doc/mac/using.tex
index e44cbfb..c515e03 100644
--- a/Doc/mac/using.tex
+++ b/Doc/mac/using.tex
@@ -67,10 +67,7 @@ format only.
 To run your script from the Terminal window you must make sure that
 \file{/usr/local/bin} is in your shell search path before \file{/usr/bin},
 where the Apple-supplied Python lives (which is version 2.2, as of Mac OS X
-10.2.4). There is one Mac OS X quirk that you need to be aware of: programs
-that talk to the window manager (in other words, anything that has a GUI)
-need to be run in a special way. Use \program{pythonw} in stead of \program{python}
-to start such scripts.
+10.2.4). 
 
 To run your script from the Finder you have two options:
 \begin{itemize}
@@ -84,6 +81,13 @@ 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} in stead of \program{python}
+to start such scripts.
+
 \subsection{configuration}
 
 MacPython honours all standard unix environment variables such as \envvar{PYTHONPATH},