Commits

Bob Ippolito committed a6c03fe

some documentation updates

Comments (0)

Files changed (16)

Doc/PyObjCTools.html

 <p>Module to make it possible to integrate signal handling into the main
 runloop.</p>
 <ul>
-<li><code><span>PyObjCTools.pluginbuilder</span></code></li>
+<li><code><span>PyObjCTools.Debugging</span></code></li>
 </ul>
-<p>Extension of <code><span>bundlebuilder</span></code> (XXX: Link) that allows you to build python-based
-plugin bundles, such as panes for the System Preferences application and
-screen savers.</p>
+<p>Allows logging of NSException stack traces.  This module should only be used
+during development.</p>
 <ul>
 <li><code><span>PyObjCTools.Signals</span></code></li>
 </ul>
 handling. Nor is it intended to be terribly robust. It may give useful
 information when your program gets unexpected signals, but it might just
 as easily cause a crash when such a signal gets in.</p>
-<h2><a name="pyobjctools-pluginbuilder">PyObjCTools.pluginbuilder</a></h2>
-<p>This module defines one class to build python based plugin bundles for MacOS X.
-Examples of plugin bundles include PreferencePanes and InterfaceBuilder 
-palletes.</p>
-<p>The PluginBuilder class is instantiated with a number of keyword arguments and
-has a <code><span>build()</span></code> method that will do all the work.</p>
-<p>XXX: Add documentation about the constructor arguments</p>
-<p>The module contains a main program that can be used in two ways:</p>
-<pre>
-% python pluginbuilder.py [options] build
-
-% python buildplugin.py [options] build
-</pre>
-<p>Where &quot;buildplugin.py&quot; is a user-supplied setup.py-like script following this
-model:</p>
-<pre>
-from PyObjCTools.pluginbuilder import buildplugin
-
-buildplugin(&lt;lots-of-keyword-args&gt;)
-</pre>
-<p>The script will tell you about the supported arguments if you run it without 
-any arguments.</p>
 </body>
 </html>

Doc/PyObjCTools.txt

 Module to make it possible to integrate signal handling into the main
 runloop.
 
-* ``PyObjCTools.pluginbuilder``
+* ``PyObjCTools.Debugging``
 
-Extension of ``bundlebuilder`` (XXX: Link) that allows you to build python-based
-plugin bundles, such as panes for the System Preferences application and
-screen savers.
+Allows logging of NSException stack traces.  This module should only be used
+during development.
 
 * ``PyObjCTools.Signals``
 
 handling. Nor is it intended to be terribly robust. It may give useful
 information when your program gets unexpected signals, but it might just
 as easily cause a crash when such a signal gets in. 
-
-
-PyObjCTools.pluginbuilder
-.........................
-
-This module defines one class to build python based plugin bundles for MacOS X.
-Examples of plugin bundles include PreferencePanes and InterfaceBuilder 
-palletes.
-
-The PluginBuilder class is instantiated with a number of keyword arguments and
-has a ``build()`` method that will do all the work. 
-
-XXX: Add documentation about the constructor arguments
-
-The module contains a main program that can be used in two ways::
-
-  % python pluginbuilder.py [options] build
-
-  % python buildplugin.py [options] build
-
-Where "buildplugin.py" is a user-supplied setup.py-like script following this
-model::
-
-  from PyObjCTools.pluginbuilder import buildplugin
-
-  buildplugin(<lots-of-keyword-args>)
-
-The script will tell you about the supported arguments if you run it without 
-any arguments.

Doc/api-notes-macosx.html

 </li>
 <li><code><span>setOffScreen:width:height:rowbytes:</span></code><p>This method is not yet supported.</p>
 </li>
+<li><code><span>CGLContextObj</span></code><p>This method is not yet supported.</p>
+</li>
 </ul>
 <h3><a href="#id16" name="class-nsopenglpixelformat">Class <code><span>NSOpenGLPixelFormat</span></code></a></h3>
 <ul>
 <li><code><span>getValues:forAttribute:forVirtualScreen:</span></code><p>This method is not yet supported</p>
 </li>
-<li><code><span>initWithAttributes:</span></code><p>This method is not yet supported</p>
-</li>
 </ul>
 <h3><a href="#id17" name="class-nsquickdrawview">Class <code><span>NSQuickDrawView</span></code></a></h3>
 <ul>
 <h3><a href="#id24" name="class-nsbundle">Class <code><span>NSBundle</span></code></a></h3>
 <ul>
 <li><code><span>bundleForClass:</span></code><p>This method does not work correctly for classes defined in Python, these
-all seem be defined in the <code><span>mainBundle()</span></code>. As a workaround you can use
-the function <code><span>objc.pluginBundle(name)</span></code> to find the NSBundle for your
-Python based bundle. See Examples/PrefPane for an example of its usage.</p>
+all seem be defined in the <code><span>mainBundle()</span></code>. As a workaround for plugin
+bundles built with py2app, you can declare <code><span>__bundle_hack__</span> <span>=</span> <span>True</span></code>
+on one class in the bundle (probably the NSPrincipalClass).  For this
+class, <code><span>bundleForClass:</span></code> will return the expected value.  See
+Examples/Plugins for examples of this.</p>
 </li>
 </ul>
 <h3><a href="#id25" name="class-nscoder">Class <code><span>NSCoder</span></code></a></h3>
 </li>
 </ul>
 <h3><a href="#id40" name="class-nsthread">class <code><span>NSThread</span></code></a></h3>
-<p>When you're using Python 2.3 or later it is safe to call from Objective-C to
-Python on any thread. Otherwise you must be sure that the current thread has
-acquired the GIL. This means you shouldn't use API's that will call back on
-an arbitrary thread unless you're using Python 2.3 or later. It is safe to 
-start new threads using the Python threading API and run non-Cocoa code on 
-those threads, PyObjC contains code that acquires the GIL whenever the runloop
-in the main thread runs.</p>
+<p>It is safe to call from Objective-C to Python on any thread.  It is safe to
+start new threads using the Python threading API and run non-Cocoa code on
+those threads.</p>
 <ul>
-<li><code><span>detachNewThreadSelector:toTarget:withObject:</span></code><p>This method can safely be used when using Python 2.3 or later, on earlier
-releases this will crash the interpreter.</p>
-<p>Make sure that you've either created a thread from Python using the 
+<li><code><span>detachNewThreadSelector:toTarget:withObject:</span></code><p>Make sure that you've either created a thread from Python using the 
 <code><span>thread</span></code> or <code><span>threading</span></code> module, or called <code><span>objc.enableThreading</span></code> before
 using this API. This is necessary to enable threading in the Python 
 interpreter. We don't do this by default because this has a negative 

Doc/api-notes-macosx.txt

 
   This method is not yet supported.
 
+* ``CGLContextObj``
+
+  This method is not yet supported.
+
 Class ``NSOpenGLPixelFormat``
 .............................
 
 
   This method is not yet supported
 
-* ``initWithAttributes:``
-
-  This method is not yet supported
-
 Class ``NSQuickDrawView``
 .........................
 
 * ``bundleForClass:``
 
   This method does not work correctly for classes defined in Python, these
-  all seem be defined in the ``mainBundle()``. As a workaround you can use
-  the function ``objc.pluginBundle(name)`` to find the NSBundle for your
-  Python based bundle. See Examples/PrefPane for an example of its usage.
+  all seem be defined in the ``mainBundle()``. As a workaround for plugin
+  bundles built with py2app, you can declare ``__bundle_hack__ = True``
+  on one class in the bundle (probably the NSPrincipalClass).  For this
+  class, ``bundleForClass:`` will return the expected value.  See
+  Examples/Plugins for examples of this.
 
 Class ``NSCoder``
 .................
 class ``NSThread``
 ..................
 
-When you're using Python 2.3 or later it is safe to call from Objective-C to
-Python on any thread. Otherwise you must be sure that the current thread has
-acquired the GIL. This means you shouldn't use API's that will call back on
-an arbitrary thread unless you're using Python 2.3 or later. It is safe to 
-start new threads using the Python threading API and run non-Cocoa code on 
-those threads, PyObjC contains code that acquires the GIL whenever the runloop
-in the main thread runs.
+It is safe to call from Objective-C to Python on any thread.  It is safe to
+start new threads using the Python threading API and run non-Cocoa code on
+those threads.
 
 * ``detachNewThreadSelector:toTarget:withObject:``
 
-  This method can safely be used when using Python 2.3 or later, on earlier
-  releases this will crash the interpreter.
-
   Make sure that you've either created a thread from Python using the 
   ``thread`` or ``threading`` module, or called ``objc.enableThreading`` before
   using this API. This is necessary to enable threading in the Python 
 classes.</p>
 <h2><a name="todo">TODO</a></h2>
 <ul>
-<li>[Serious] Fix linkage problems. The objC runtime doesn't seem to be 
+<li>[Serious] Fix linkage problems. The ObjC runtime doesn't seem to be 
 initialized correctly and/or the classes in newly loaded frameworks are
 not correctly registered in the runtime.</li>
 <li>Fix the odd bug...<p>I currently get the following text when importing objc:</p>
 TODO
 ----
 
-* [Serious] Fix linkage problems. The objC runtime doesn't seem to be 
+* [Serious] Fix linkage problems. The ObjC runtime doesn't seem to be 
   initialized correctly and/or the classes in newly loaded frameworks are
   not correctly registered in the runtime.
 
 </li>
 <li><a href="classes.html">Python classes and Objective-C code</a><p>Another older overview of PyObjC.</p>
 </li>
-<li><a href="api-notes-macosx.html">Notes on supported APIs and classes on MacOS X</a><p>This document lists the methods and classes that are not fully supported,
+<li><a href="api-notes-macosx.html">Notes on supported APIs and classes on Mac OS X</a><p>This document lists the methods and classes that are not fully supported,
 or supported in an 'unexpected' way.</p>
 </li>
 <li><a href="wrapping.html">How to wrap an Objective-C class library</a><p>This explains how you can provide a python wrapper for an existing 
 
   Another older overview of PyObjC. 
 
-* `Notes on supported APIs and classes on MacOS X`_
+* `Notes on supported APIs and classes on Mac OS X`_
 
   This document lists the methods and classes that are not fully supported,
   or supported in an 'unexpected' way.
 
 .. _`Adding Python code to an existing ObjC application`: tutorial_embed/extending_objc_with_python.html
 
-.. _`Notes on supported APIs and classes on MacOS X`: api-notes-macosx.html
+.. _`Notes on supported APIs and classes on Mac OS X`: api-notes-macosx.html
 </li>
 <li><a href="#cocoa-for-python-programmers" id="id13" name="id13">Cocoa for Python programmers</a></li>
 <li><a href="#notes-on-specific-tasks" id="id14" name="id14">Notes on specific tasks</a><ul>
-<li><a href="#working-with-threads" id="id15" name="id15">Working with threads</a><ul>
-<li><a href="#threading-limitiations-when-using-python-2-2" id="id16" name="id16">Threading limitiations when using Python 2.2</a></li>
+<li><a href="#working-with-threads" id="id15" name="id15">Working with threads</a></li>
+<li><a href="#finalizers" id="id16" name="id16">Finalizers</a></li>
 </ul>
 </li>
-<li><a href="#finalizers" id="id17" name="id17">Finalizers</a></li>
-</ul>
-</li>
-<li><a href="#building-applications" id="id18" name="id18">Building applications</a><ul>
-<li><a href="#pure-python-buildapp-py" id="id19" name="id19">&quot;Pure Python&quot; :  buildapp.py</a></li>
-<li><a href="#ide-approach-xcode" id="id20" name="id20">&quot;IDE approach&quot; : Xcode</a></li>
+<li><a href="#building-applications" id="id17" name="id17">Building applications</a><ul>
+<li><a href="#py2app-setup-py" id="id18" name="id18">&quot;py2app&quot; :  setup.py</a></li>
+<li><a href="#ide-approach-xcode" id="id19" name="id19">&quot;IDE approach&quot; : Xcode</a></li>
 </ul>
 </li>
 </ul>
 <h2><a href="#id4" name="preface">Preface</a></h2>
 <p>PyObjC is a bridge between Python and Objective-C. It allows you to write 
 Python scripts that use and extend existing Objective-C class libraries, 
-most importantly the <a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa libraries</a> by <a href="http://www.apple.com/">Apple</a>.</p>
+most importantly the <a href="http://developer.apple.com/referencelibrary/API_Fundamentals/Cocoa-api-date.html">Cocoa libraries</a> by <a href="http://www.apple.com/">Apple</a>.</p>
 <p>This document describes how to use Objective-C class libraries from Python
 scripts and how to interpret the documentation of those libraries, from the 
 point of view of a Python programmer.</p>
 </pre>
 <p>Objective-C also features exceptions, but as they are mostly used for disaster
 recovery and not for normal error handling you won't see them very often
-in example code. Read <a href="http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/index.html">The Objective-C Programming Language</a> if you want to
+in example code. Read <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html">The Objective-C Programming Language</a> if you want to
 know more about exceptions in Objective-C.</p>
 <p>One thing to keep in mind when translating Objective-C snippets to python is
 that it is valid to call methods on <code><span>nil</span></code> (that is the NULL pointer). Those
 <code><span>AttributeError</span></code>.</p>
 <p>For more information about Objective-C see:</p>
 <ul>
-<li><a href="http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/index.html">The Objective-C Programming Language</a> at <a href="http://www.apple.com/">Apple</a>.</li>
+<li><a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html">The Objective-C Programming Language</a> at <a href="http://www.apple.com/">Apple</a>.</li>
 </ul>
 <h2><a href="#id6" name="overview-of-the-bridge">Overview of the bridge</a></h2>
 <h3><a href="#id7" name="classes">Classes</a></h3>
 to have two Python modules that define a class with the same name. If you write 
 classes that will be used outside of a single project it is customary to pick a 
 (short) prefix and stick that in front of all class names, e.g. Apple <code><span>NS</span></code> 
-as the prefix in the <a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa libraries</a>.</p>
+as the prefix in the <a href="http://developer.apple.com/referencelibrary/API_Fundamentals/Cocoa-api-date.html">Cocoa libraries</a>.</p>
 <p>As described in <a href="#objective-c-for-pyobjc-users">Objective-C for PyObjC users</a> the creation of Objective-C 
 objects is a two-stage process. You first call the class method <code><span>alloc</span></code>, and
 then call some variation of <code><span>init</span></code> to initialize the objects. The newly
 the only Python keywords that are actually used in Cocoa.</p>
 <p>Wrapped/bridged methods (and functions) have the same number of arguments
 as the corresponding Objective-C method or function, unless otherwise noted
-in the documentation (<a href="api-notes-macosx.html">Notes on supported APIs and classes on MacOS X</a> for
-Cocoa on MacOS X).</p>
+in the documentation (<a href="api-notes-macosx.html">Notes on supported APIs and classes on Mac OS X</a> for
+Cocoa on Mac OS X).</p>
 <p>One group of exceptions to this rule can be described in a global way. Some
 methods and functions have pointers as arguments, specifically pointers to
 a single value that is passed in and/or out of the function. These arguments
         someMethod_ = objc.selector(someMethod_, ...)
 </pre>
 <h3><a href="#id9" name="reference-counting">Reference counting</a></h3>
-<p>The <a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa libraries</a>, and most (if not all) other class libraries for 
+<p>The <a href="http://developer.apple.com/referencelibrary/API_Fundamentals/Cocoa-api-date.html">Cocoa libraries</a>, and most (if not all) other class libraries for 
 Objective-C use explicit reference counting to manage memory. The methods
 <code><span>retain</span></code>, <code><span>release</span></code> and <code><span>autorelease</span></code> are used to manage these 
 reference counts. You won't have to manage reference counts in Python, the
 bridge does all that work for you (but see <a href="api-notes-macosx.html">Notes on supported APIs and classes 
-on MacOS X</a> for some advanced issues).</p>
+on Mac OS X</a> for some advanced issues).</p>
 <p>The only reasons reference counts are mentioned at all are to tell you about
 ignoring them, and more importantly to introduce you to some issues w.r.t. 
 reference counting.</p>
 object stays alive, but the proxy object as seen by the Objective-C code is
 actually an autoreleased object that will be cleaned up unless the Objective-C
 code increases its reference count.</p>
-<p>The document <a href="api-notes-macosx.html">Notes on supported APIs and classes on MacOS X</a> contains 
+<p>The document <a href="api-notes-macosx.html">Notes on supported APIs and classes on Mac OS X</a> contains 
 information about classes that work with weak references. The most important
 are notification centers and <code><span>NSOutlineView</span></code>, to be exact: the outline view
 stores weak references to the objects return by the method 
 Python. The <a href="../Examples/00ReadMe.html">PyObjC Example index</a> contains an overview of those examples.</p>
 <p>More information on Cocoa programming can be found at:</p>
 <ul>
-<li><a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa documentation at the Apple developer website</a></li>
-<li><a href="http://developer.apple.com/samplecode/Sample_Code/Cocoa.htm">Cocoa examples at the Apple developer website</a></li>
+<li><a href="http://developer.apple.com/documentation/Cocoa/Cocoa.html">Cocoa documentation at the Apple developer website</a></li>
+<li><a href="http://developer.apple.com/samplecode/Cocoa/index.html">Cocoa examples at the Apple developer website</a></li>
 <li><a href="http://www.stepwise.com/">stepwise.com</a></li>
 <li>Your local bookstore or library</li>
 </ul>
 you're done. The easiest way to that is to create an instance of that class
 bound to a local variable. If the thread is long-lived you may want to arrange
 for recycling the pool once in a while.</p>
-<h4><a href="#id16" name="threading-limitiations-when-using-python-2-2">Threading limitiations when using Python 2.2</a></h4>
-<p>There are some limitation w.r.t. threading when using Python 2.2. The
-combination of Python 2.3 and PyObjC is fully thread-safe.</p>
-<p>You cannot use <code><span>NSThread</span></code> to create new threads, but must use the python 
-primitives instead.</p>
-<p>You must also make sure that Objective-C only makes calls to Python from a 
-thread that owns the Python GIL (that's also the reason for not being able 
-to use <code><span>NSThread</span></code> to create new threads).</p>
-<h3><a href="#id17" name="finalizers">Finalizers</a></h3>
+<h3><a href="#id16" name="finalizers">Finalizers</a></h3>
 <p>In Python you can use the method <code><span>__del__</span></code> to clean up resources when your
 object is garbage collected. In Objective-C/Cocoa this is done with a method 
 named <code><span>dealloc</span></code>.</p>
 <p>In PyObjC you should always use the <code><span>__del__</span></code> method, the <code><span>dealloc</span></code> method
 can safely be ignored and the bridge will complain when you try to override
 this method.</p>
-<h2><a href="#id18" name="building-applications">Building applications</a></h2>
-<p>There are two different ways to build applications with PyObjC. There are no
-major advantages to using either one of them, use the one that is most 
-convenient to you.</p>
-<h3><a href="#id19" name="pure-python-buildapp-py">&quot;Pure Python&quot; :  buildapp.py</a></h3>
-<p>PyObjC includes a copy of the <code><span>bundlebuilder</span></code> module. This module is
-part of the Python 2.3 MacPython release and offers a way to build
-distutils-style scripts for building (standalone) applications.</p>
-<p>An example <code><span>buildapp.py</span></code> script:</p>
+<h2><a href="#id17" name="building-applications">Building applications</a></h2>
+<p>There are two different ways to build applications with PyObjC. py2app
+should be the preferred method, however using the Xcode template can
+be convenient for development.</p>
+<h3><a href="#id18" name="py2app-setup-py">&quot;py2app&quot; :  setup.py</a></h3>
+<p>The PyObjC installer includes a copy of the <code><span>py2app</span></code> package. This package
+offers a way to build distutils scripts for building (standalone)
+applications and plugin bundles.</p>
+<p>An example <code><span>setup.py</span></code> script:</p>
 <pre>
-from bundlebuilder import buildapp
-buildapp(
-        name = 'iClass',
-        mainprogram = &quot;main.py&quot;,
-        resources = [&quot;English.lproj&quot;, &quot;datasource.py&quot; ],
-        nibname = &quot;MainMenu&quot;,
-)   
+from distutils.core import setup
+import py2app
+
+setup(
+    app = [&quot;iClass.py&quot;],
+    data_files = [&quot;English.lproj&quot;],
+)
 </pre>
 <p>During development you typically invoke it from the command line like this:</p>
 <pre>
-python buildapp.py --link build
+python setup.py py2app -A
 </pre>
-<p>This will build an application bundle in a folder named <code><span>build</span></code> in the
-current folder. The <code><span>--link</span></code> option tells <code><span>bundlebuilder</span></code> to add symbolic
-links to the application bundle instead of copies of your source and resource
-files, allowing you to edit them without having to rebuild the application. To
-build a standalone application, either use <code><span>--standalone</span></code> or
-<code><span>--semi-standalone</span></code>. The latter will put all used modules that are not in
-Python's standard library into the application bundle. The result will still
-depend on an installed Python, but yields a relatively compact application.
-<code><span>--standalone</span></code> will cause <code><span>bundlebuilder</span></code> to include <i>everything</i> needed
-into the app bundle, including the entire Python runtime. This is useful if
-you're using a different version of Python that the one that comes with MacOSX
-10.2, or if you fear that a future version of OSX may come with an
-incompatible Python version.</p>
-<p>The online documentation for <code><span>bundlebuilder</span></code> contains more information on 
-building <code><span>buildapp.py</span></code> scripts and how to invoke them. There are plenty of
-example <code><span>buildapp.py</span></code> scripts in the various <a href="../Examples/00ReadMe.txt">Examples</a> subfolders.</p>
-<h3><a href="#id20" name="ide-approach-xcode">&quot;IDE approach&quot; : Xcode</a></h3>
+<p>This will build an application bundle in a folder named <code><span>dist</span></code> in the
+current folder. The <code><span>-A</span></code> option tells <code><span>py2app</span></code> to add symbolic
+links for data folders and files and an Alias to your main script,
+allowing you quickly rebuild the application without doing a full dependency
+scan, with the additional bonus that you can edit them without rebuild. To
+build a standalone application, simply do not use the <code><span>-A</span></code> option.
+Note that if you are using a version of Python shipped with your operating
+system, it will not be included in the application.  Otherwise, your
+application will include stripped down version of the Python runtime that
+you ran setup.py with.</p>
+<p>For more information about <code><span>py2app</span></code> usage, read through some of the
+<code><span>setup.py</span></code> scripts used by the examples in the <a href="../Examples/00ReadMe.txt">Examples</a> folder.
+On any <code><span>setup.py</span></code> script that imports <code><span>py2app</span></code>, you can use the
+following command to see the list of options:</p>
+<pre>
+python setup.py py2app --help
+</pre>
+<h3><a href="#id19" name="ide-approach-xcode">&quot;IDE approach&quot; : Xcode</a></h3>
 <p>PyObjC includes a number of Xcode templates that can be used to 
-build (standalone) applications. Those templates are used like any other
+develop applications. Those templates are used like any other
 Xcode template. The only non-obvious detail is that you have to
 add your sources as resources, but Project Builder usually does the right
 thing when you add a new file.</p>
 <p>The templates will build an application that makes use of the installed copy
-<code><span>/usr/bin/python</span></code> (e.g. the one shipped by Apple in MacOS X 10.2) and will 
-copy the PyObjC modules into the application bundle. This means that this 
-application bundle should be useable on any MacOS X 10.2 system.</p>
-<p>See <a href="ProjectBuilder-Templates.html">the documentation for the templates</a> for more details.</p>
-<p>MacOS X 10.3 seems to ship with Python 2.3 as /usr/bin/python. This means that
-standalone applications build using the Project Builder templates will start
-to complain about Python ABI versions in the <code><span>Console</span></code> when you run them
-on MacOS X 10.3. These are harmless messages caused by the extension modules
-in PyObjC.</p>
+<code><span>/System/Library/Frameworks/Python.framework</span></code> (e.g. the one shipped by
+Apple in Mac OS X 10.3) and will copy the PyObjC modules into the application
+bundle. This means that this application bundle <i>should</i> be useable on any
+Mac OS X 10.3 system, if you do not have any additional dependencies.  Using
+py2app to deploy your application is a more reliable method, and builds more
+compact bundles.</p>
+<p>See <a href="Xcode-Templates.html">the documentation for the templates</a> for more details.</p>
 </body>
 </html>
 
 * `The Objective-C Programming Language`_ at `Apple`_.
 
-.. _`The Objective-C Programming Language`: http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/index.html
+.. _`The Objective-C Programming Language`: http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/index.html
 
 
 Overview of the bridge
 
 Wrapped/bridged methods (and functions) have the same number of arguments
 as the corresponding Objective-C method or function, unless otherwise noted
-in the documentation (`Notes on supported APIs and classes on MacOS X`_ for
-Cocoa on MacOS X).
+in the documentation (`Notes on supported APIs and classes on Mac OS X`_ for
+Cocoa on Mac OS X).
 
-.. _`Notes on supported APIs and classes on MacOS X`: api-notes-macosx.html
+.. _`Notes on supported APIs and classes on Mac OS X`: api-notes-macosx.html
 
 One group of exceptions to this rule can be described in a global way. Some
 methods and functions have pointers as arguments, specifically pointers to
 ``retain``, ``release`` and ``autorelease`` are used to manage these 
 reference counts. You won't have to manage reference counts in Python, the
 bridge does all that work for you (but see `Notes on supported APIs and classes 
-on MacOS X`__ for some advanced issues).
+on Mac OS X`__ for some advanced issues).
 
 .. __: api-notes-macosx.html
 
 actually an autoreleased object that will be cleaned up unless the Objective-C
 code increases its reference count.
 
-The document `Notes on supported APIs and classes on MacOS X`_ contains 
+The document `Notes on supported APIs and classes on Mac OS X`_ contains 
 information about classes that work with weak references. The most important
 are notification centers and ``NSOutlineView``, to be exact: the outline view
 stores weak references to the objects return by the method 
 
 .. _`PyObjC Example index`: ../Examples/00ReadMe.html
 
-..  _`Cocoa libraries`: http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html
+..  _`Cocoa libraries`: http://developer.apple.com/referencelibrary/API_Fundamentals/Cocoa-api-date.html
 
-..  _`Cocoa documentation at the Apple developer website`: http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html
+..  _`Cocoa documentation at the Apple developer website`: http://developer.apple.com/documentation/Cocoa/Cocoa.html
 
-.. _`Cocoa examples at the Apple developer website`: http://developer.apple.com/samplecode/Sample_Code/Cocoa.htm
+.. _`Cocoa examples at the Apple developer website`: http://developer.apple.com/samplecode/Cocoa/index.html
 
 .. _`stepwise.com`: http://www.stepwise.com/
 
 bound to a local variable. If the thread is long-lived you may want to arrange
 for recycling the pool once in a while.
 
-Threading limitiations when using Python 2.2
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There are some limitation w.r.t. threading when using Python 2.2. The
-combination of Python 2.3 and PyObjC is fully thread-safe.
-
-You cannot use ``NSThread`` to create new threads, but must use the python 
-primitives instead.  
-
-You must also make sure that Objective-C only makes calls to Python from a 
-thread that owns the Python GIL (that's also the reason for not being able 
-to use ``NSThread`` to create new threads).  
-
 Finalizers
 ..........
 
 Building applications
 ---------------------
 
-There are two different ways to build applications with PyObjC. There are no
-major advantages to using either one of them, use the one that is most 
-convenient to you.
+There are two different ways to build applications with PyObjC. py2app
+should be the preferred method, however using the Xcode template can
+be convenient for development.
 
-"Pure Python" :  buildapp.py
-............................
+"py2app" :  setup.py
+....................
 
-PyObjC includes a copy of the ``bundlebuilder`` module. This module is
-part of the Python 2.3 MacPython release and offers a way to build
-distutils-style scripts for building (standalone) applications.
+The PyObjC installer includes a copy of the ``py2app`` package. This package
+offers a way to build distutils scripts for building (standalone)
+applications and plugin bundles.
 
-An example ``buildapp.py`` script::
+An example ``setup.py`` script::
 
-	from bundlebuilder import buildapp
-	buildapp(
-		name = 'iClass',
-		mainprogram = "main.py",
-		resources = ["English.lproj", "datasource.py" ],
-		nibname = "MainMenu",
-	)   
+    from distutils.core import setup
+    import py2app
 
+    setup(
+        app = ["iClass.py"],
+        data_files = ["English.lproj"],
+    )
+	
 During development you typically invoke it from the command line like this::
 
-	python buildapp.py --link build
+	python setup.py py2app -A
 
-This will build an application bundle in a folder named ``build`` in the
-current folder. The ``--link`` option tells ``bundlebuilder`` to add symbolic
-links to the application bundle instead of copies of your source and resource
-files, allowing you to edit them without having to rebuild the application. To
-build a standalone application, either use ``--standalone`` or
-``--semi-standalone``. The latter will put all used modules that are not in
-Python's standard library into the application bundle. The result will still
-depend on an installed Python, but yields a relatively compact application.
-``--standalone`` will cause ``bundlebuilder`` to include *everything* needed
-into the app bundle, including the entire Python runtime. This is useful if
-you're using a different version of Python that the one that comes with MacOSX
-10.2, or if you fear that a future version of OSX may come with an
-incompatible Python version.
+This will build an application bundle in a folder named ``dist`` in the
+current folder. The ``-A`` option tells ``py2app`` to add symbolic
+links for data folders and files and an Alias to your main script,
+allowing you quickly rebuild the application without doing a full dependency
+scan, with the additional bonus that you can edit them without rebuild. To
+build a standalone application, simply do not use the ``-A`` option.
+Note that if you are using a version of Python shipped with your operating
+system, it will not be included in the application.  Otherwise, your
+application will include stripped down version of the Python runtime that
+you ran setup.py with.
 
-The online documentation for ``bundlebuilder`` contains more information on 
-building ``buildapp.py`` scripts and how to invoke them. There are plenty of
-example ``buildapp.py`` scripts in the various `Examples`__ subfolders.
+For more information about ``py2app`` usage, read through some of the
+``setup.py`` scripts used by the examples in the `Examples`__ folder.
+On any ``setup.py`` script that imports ``py2app``, you can use the
+following command to see the list of options::
+
+    python setup.py py2app --help
 
 .. __: ../Examples/00ReadMe.txt
 
 ................................
 
 PyObjC includes a number of Xcode templates that can be used to 
-build (standalone) applications. Those templates are used like any other
+develop applications. Those templates are used like any other
 Xcode template. The only non-obvious detail is that you have to
 add your sources as resources, but Project Builder usually does the right
 thing when you add a new file.
 
 The templates will build an application that makes use of the installed copy
-``/usr/bin/python`` (e.g. the one shipped by Apple in MacOS X 10.2) and will 
-copy the PyObjC modules into the application bundle. This means that this 
-application bundle should be useable on any MacOS X 10.2 system.
+``/System/Library/Frameworks/Python.framework`` (e.g. the one shipped by
+Apple in Mac OS X 10.3) and will copy the PyObjC modules into the application
+bundle. This means that this application bundle *should* be useable on any
+Mac OS X 10.3 system, if you do not have any additional dependencies.  Using
+py2app to deploy your application is a more reliable method, and builds more
+compact bundles.
 
 See `the documentation for the templates`__ for more details.
 
-.. __: ProjectBuilder-Templates.html
-
-MacOS X 10.3 seems to ship with Python 2.3 as /usr/bin/python. This means that
-standalone applications build using the Project Builder templates will start
-to complain about Python ABI versions in the ``Console`` when you run them
-on MacOS X 10.3. These are harmless messages caused by the extension modules
-in PyObjC.
+.. __: Xcode-Templates.html

Doc/release-process.html

 </ul>
 </li>
 <li>update the information at a number of software databases:<ul>
-<li>versiontracker.com (billb knows how)</li>
+<li>versiontracker.com (bbum knows how)</li>
 <li>macupdate.com</li>
 <li>freshmeat.net (ronald knows how)</li>
 <li>PyPI database at python.org (run <code><span>python2.3</span> <span>setup.py</span> <span>register</span></code>)</li>

Doc/release-process.txt

 
 * update the information at a number of software databases:
 
-  - versiontracker.com (billb knows how)
+  - versiontracker.com (bbum knows how)
 
   - macupdate.com
 

Doc/tutorial_reading.html

 <p>Let us have a look at the <code><span>ConverterController</span></code> object by double clicking it.
 The &quot;MainMenu.nib&quot; window goes to the &quot;Classes&quot; tab, and an info window shows up.
 In the &quot;MainMenu.nib&quot; window the <code><span>ConverterController</span></code> class is selected, and
-you can see it is a subclass of <code><span>NSobject</span></code>. Having the same name for the class
+you can see it is a subclass of <code><span>NSObject</span></code>. Having the same name for the class
 and the instance is common in Cocoa programs, the main exception being the File
 Owner object.</p>
 <p>The info window shows more information on the <code><span>ConverterController</span></code> class. It

Doc/tutorial_reading.txt

 Let us have a look at the ``ConverterController`` object by double clicking it.
 The "MainMenu.nib" window goes to the "Classes" tab, and an info window shows up.
 In the "MainMenu.nib" window the ``ConverterController`` class is selected, and
-you can see it is a subclass of ``NSobject``. Having the same name for the class
+you can see it is a subclass of ``NSObject``. Having the same name for the class
 and the instance is common in Cocoa programs, the main exception being the File
 Owner object.
 

Doc/wrapping.html

 <p>The compiler will generate a method signature for this method and this can 
 be accessed from Python using the property 'signature' of Objective-C methods. 
 You can also just make up the signature, which is quite easy once you get the
-hang of it. The signature for this method is 'v@:^@@'.</p>
+hang of it. The signature for this method is 'v@:^@@'.  See <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/RuntimeOverview/chapter_4_section_6.html">Type Encodings</a>
+for the list of valid encoding characters for the Apple Objective-C runtime.</p>
 <p>Let's say the first argument is an output parameter. Output parameters are 
 denoted in the signature string using the character 'o' before the actual
 argument signature. The 'correct' signature for method is therefore 'v@:o^@@'.
 The compiler will generate a method signature for this method and this can 
 be accessed from Python using the property 'signature' of Objective-C methods. 
 You can also just make up the signature, which is quite easy once you get the
-hang of it. The signature for this method is 'v@:^@@'.
+hang of it. The signature for this method is 'v@:^@@'.  See `Type Encodings`_
+for the list of valid encoding characters for the Apple Objective-C runtime.
+
+.. _`Type Encodings`: http://developer.apple.com/documentation/Cocoa/Conceptual/ObjectiveC/RuntimeOverview/chapter_4_section_6.html
 
 Let's say the first argument is an output parameter. Output parameters are 
 denoted in the signature string using the character 'o' before the actual