Bob Ippolito avatar Bob Ippolito committed be95ce7

- Documentation updates (some, not all)

- NSAutoreleasePool observer to make sure the global_release_pool isn't
around after it's popped.

- ``OC_PythonObject``, the proxy for Python objects that do not have
an Objective-C superclass and are not otherwise special-cased, now
act slightly more like typical Objective-C objects (supporting
``-isEqual:``, ``-hash``, and ``-compare:``). This allows them
to work with Key-Value Coding if they are contained by an Objective-C
object, among other things.

- New objc.signature decorator that allows easier specification of
objc.selector wrappers for functions when using Python 2.4::

@objc.signature('i@:if')
def methodWithX_andY_(self, x, y):
return 0

- ``PyObjCTools.KeyValueCoding.getKeyPath`` now supports all of the
Array Operators supported by Mac OS X 10.4.

Comments (0)

Files changed (26)

Doc/ProjectBuilder-SyntaxHighlighting.html

 <table width="90%" border="1" align="center">
 <tbody><tr><td><table width="100%"><tbody><tr>
 <td bgcolor="#ffff33" width="15%">
-Warning</td><td><p>None of this is documented or supported by <strong>Apple</strong>.  Don't ask <strong>Apple</strong> for
+Warning</td><td><p>Project Builder support is not maintained in PyObjC, is likely
+out of date, and is not guaranteed to work at all.
+None of this is documented or supported by <strong>Apple</strong>.  Don't ask <strong>Apple</strong> for
 support and don't blame me if something breaks.  A lot could break as
 <strong>Project Builder</strong> stores a tremendous amount of highly dynamic information in
 both the user defaults and within project files.</p>

Doc/ProjectBuilder-SyntaxHighlighting.txt

 :Date: 12/16/2002
 
 .. WARNING::
+   Project Builder support is not maintained in PyObjC, is likely
+   out of date, and is not guaranteed to work at all.
    None of this is documented or supported by **Apple**.  Don't ask **Apple** for
    support and don't blame me if something breaks.  A lot could break as
    **Project Builder** stores a tremendous amount of highly dynamic information in

Doc/PyObjCTools.html

 <p>This module provides a Python interface to some of that functionality. The
 interface is modeled on the <code><span>getattr</span></code> and <code><span>setattr</span></code> functions.</p>
 <ul>
-<li><code><span>getKey(object,</span> <span>key)</span> <span>-&gt;</span> <span>value</span></code><p>Find the value for <code><span>key</span></code>. Raises <code><span>KeyError</span></code> if the key is not a valid
-attribute of the object.</p>
-<p>To find the value of a key the following values are tried for a key named
-<code><span>key</span></code> (first match wins):</p>
+<li><code><span>getKey(object,</span> <span>key)</span> <span>-&gt;</span> <span>value</span></code><blockquote>
+<p>Get the attribute referenced by 'key'. The key is used
+to build the name of an attribute, or attribute accessor method.</p>
+<p>The following attributes and accesors are tried (in this order):</p>
 <ul>
-<li>the return value of <code><span>object.get_key()</span></code></li>
-<li>the return value of <code><span>object.getKey()</span></code></li>
-<li>the return value of <code><span>object._get_key()</span></code></li>
-<li>the return value of <code><span>object._getKey()</span></code></li>
-<li>the value of the attribute <code><span>key</span></code>, or the value of <code><span>object.key()</span></code> if
-<code><span>object.key</span></code> is a method.</li>
-<li>the value of the attribute <code><span>_key</span></code>, or the vale of <code><span>object._key()</span></code> if
-<code><span>object._key</span></code> is a method.</li>
+<li>Accessor 'getKey'</li>
+<li>Accesoor 'get_key'</li>
+<li>Accessor or attribute 'key'</li>
+<li>Accessor or attribute 'isKey'</li>
+<li>Attribute '_key'</li>
 </ul>
+<p>If none of these exist, raise KeyError</p>
+</blockquote>
 </li>
 <li><code><span>getKeyPath(object,</span> <span>keypath)</span> <span>-&gt;</span> <span>value</span></code><p>Like <code><span>getKey</span></code> but using a key path. The <code><span>keypath</span></code> is a sequence of keys
 separated by dots. It calls <code><span>getKey</span></code> to follow the path and returns the

Doc/PyObjCTools.txt

 
 * ``getKey(object, key) -> value``
 
-  Find the value for ``key``. Raises ``KeyError`` if the key is not a valid
-  attribute of the object.
+    Get the attribute referenced by 'key'. The key is used
+    to build the name of an attribute, or attribute accessor method.
 
-  To find the value of a key the following values are tried for a key named
-  ``key`` (first match wins):
+    The following attributes and accesors are tried (in this order):
 
-  - the return value of ``object.get_key()``
+    - Accessor 'getKey'
+    - Accesoor 'get_key'
+    - Accessor or attribute 'key'
+    - Accessor or attribute 'isKey'
+    - Attribute '_key'
 
-  - the return value of ``object.getKey()``
-
-  - the return value of ``object._get_key()``
-
-  - the return value of ``object._getKey()``
-
-  - the value of the attribute ``key``, or the value of ``object.key()`` if
-    ``object.key`` is a method.
-
-  - the value of the attribute ``_key``, or the vale of ``object._key()`` if
-    ``object._key`` is a method.
+    If none of these exist, raise KeyError
 
 * ``getKeyPath(object, keypath) -> value``
 

Doc/announcement.txt

    pythonmac-sig@python.org
    cocoa-dev@lists.apple.com
 
-subject: ANN: PyObjC 1.3.1
+subject: ANN: PyObjC 1.3.5
 
-PyObjC 1.3.1 is now available for download at http://pyobjc.sourceforge.net/  
+PyObjC 1.3.5 is now available for download at http://pyobjc.sourceforge.net/  
 
 PyObjC is a bridge between Python and Objective-C.  It allows full
 featured Cocoa applications to be written in pure Python.  It is also
 PyObjC also supports full introspection of Objective-C classes and 
 direct invocation of Objective-C APIs from the interactive interpreter.
 
-PyObjC requires Mac OS X 10.2 or later and Python 2.3 or later.  PyObjC works 
-with the Apple provided Python installation in Mac OS X 10.3 (and later),
+PyObjC requires Mac OS X 10.2 or later and Python 2.3 or later.  PyObjC
+works with the Apple provided Python installation in Mac OS X 10.3 (and later),
 MacPython 2.3, and MacPython 2.4.
 
 This release features several bugfixes, improved documentation, new Xcode
-templates, and many major enhancements.  See the news file at 
-http://pyobjc.sourceforge.net/NEWS-1.3.txt for more information.
+templates, Tiger support and many major enhancements.  See the news file at 
+http://pyobjc.sourceforge.net/NEWS-1.3.5.txt for more information.
 
 PyObjC is released with an open source license (MIT style).
 

Doc/api-notes-macosx.html

 <h2>Contents</h2>
 <ul>
 <li><a href="#introduction" id="id2" name="id2">Introduction</a></li>
-<li><a href="#core-objective-c-runtime" id="id3" name="id3">Core Objective-C runtime</a><ul>
-<li><a href="#class-protocol" id="id4" name="id4">Class Protocol</a></li>
+<li><a href="#core-objective-c-runtime" id="id3" name="id3">Core Objective-C runtime</a></li>
+<li><a href="#addressbook-framework" id="id4" name="id4">Addressbook framework</a></li>
+<li><a href="#appkit-framework" id="id5" name="id5">AppKit framework</a><ul>
+<li><a href="#class-nsapplication" id="id6" name="id6">Class NSApplication</a></li>
+<li><a href="#class-nsbezierpath" id="id7" name="id7">Class NSBezierPath</a></li>
+<li><a href="#class-nsbitmapimagerep" id="id8" name="id8">Class <code><span>NSBitmapImageRep</span></code></a></li>
+<li><a href="#class-nsfont" id="id9" name="id9">Class <code><span>NSFont</span></code></a></li>
+<li><a href="#class-nsgraphicscontext" id="id10" name="id10">Class <code><span>NSGraphicsContext</span></code></a></li>
+<li><a href="#class-nslayoutmanager" id="id11" name="id11">Class <code><span>NSLayoutManager</span></code></a></li>
+<li><a href="#class-nsmatrix" id="id12" name="id12">Class <code><span>NSMatrix</span></code></a></li>
+<li><a href="#class-nsmovie" id="id13" name="id13">Class <code><span>NSMovie</span></code></a></li>
+<li><a href="#class-nsopenglcontext" id="id14" name="id14">Class <code><span>NSOpenGLContext</span></code></a></li>
+<li><a href="#class-nsopenglpixelformat" id="id15" name="id15">Class <code><span>NSOpenGLPixelFormat</span></code></a></li>
+<li><a href="#class-nsquickdrawview" id="id16" name="id16">Class <code><span>NSQuickDrawView</span></code></a></li>
+<li><a href="#class-nssimplehorizontaltypesetter" id="id17" name="id17">Class <code><span>NSSimpleHorizontalTypesetter</span></code></a></li>
+<li><a href="#class-nsview" id="id18" name="id18">Class <code><span>NSView</span></code></a></li>
+<li><a href="#class-nswindow" id="id19" name="id19">Class <code><span>NSWindow</span></code></a></li>
 </ul>
 </li>
-<li><a href="#addressbook-framework" id="id5" name="id5">Addressbook framework</a></li>
-<li><a href="#appkit-framework" id="id6" name="id6">AppKit framework</a><ul>
-<li><a href="#class-nsapplication" id="id7" name="id7">Class NSApplication</a></li>
-<li><a href="#class-nsbezierpath" id="id8" name="id8">Class NSBezierPath</a></li>
-<li><a href="#class-nsbitmapimagerep" id="id9" name="id9">Class <code><span>NSBitmapImageRep</span></code></a></li>
-<li><a href="#class-nsfont" id="id10" name="id10">Class <code><span>NSFont</span></code></a></li>
-<li><a href="#class-nsgraphicscontext" id="id11" name="id11">Class <code><span>NSGraphicsContext</span></code></a></li>
-<li><a href="#class-nslayoutmanager" id="id12" name="id12">Class <code><span>NSLayoutManager</span></code></a></li>
-<li><a href="#class-nsmatrix" id="id13" name="id13">Class <code><span>NSMatrix</span></code></a></li>
-<li><a href="#class-nsmovie" id="id14" name="id14">Class <code><span>NSMovie</span></code></a></li>
-<li><a href="#class-nsopenglcontext" id="id15" name="id15">Class <code><span>NSOpenGLContext</span></code></a></li>
-<li><a href="#class-nsopenglpixelformat" id="id16" name="id16">Class <code><span>NSOpenGLPixelFormat</span></code></a></li>
-<li><a href="#class-nsquickdrawview" id="id17" name="id17">Class <code><span>NSQuickDrawView</span></code></a></li>
-<li><a href="#class-nssimplehorizontaltypesetter" id="id18" name="id18">Class <code><span>NSSimpleHorizontalTypesetter</span></code></a></li>
-<li><a href="#class-nsview" id="id19" name="id19">Class <code><span>NSView</span></code></a></li>
-<li><a href="#class-nswindow" id="id20" name="id20">Class <code><span>NSWindow</span></code></a></li>
+<li><a href="#foundation-framework" id="id20" name="id20">Foundation framework</a><ul>
+<li><a href="#class-nsarray" id="id21" name="id21">Class <code><span>NSArray</span></code></a></li>
+<li><a href="#class-nsautoreleasepool" id="id22" name="id22">Class <code><span>NSAutoreleasePool</span></code></a></li>
+<li><a href="#class-nscoder" id="id23" name="id23">Class <code><span>NSCoder</span></code></a></li>
+<li><a href="#class-nsdata" id="id24" name="id24">Class <code><span>NSData</span></code></a></li>
+<li><a href="#class-nsdecimalnumber-and-the-nsdecimal-type" id="id25" name="id25">Class <code><span>NSDecimalNumber</span></code> and the <code><span>NSDecimal</span></code> type</a></li>
+<li><a href="#class-nsdictionary" id="id26" name="id26">Class <code><span>NSDictionary</span></code></a></li>
+<li><a href="#class-nsexception" id="id27" name="id27">Class <code><span>NSException</span></code></a></li>
+<li><a href="#class-nsfault" id="id28" name="id28">Class <code><span>NSFault</span></code></a></li>
+<li><a href="#class-nsindexset" id="id29" name="id29">Class <code><span>NSIndexSet</span></code></a></li>
+<li><a href="#class-nsinvocation" id="id30" name="id30">Class <code><span>NSInvocation</span></code></a></li>
+<li><a href="#class-nsmutablearray" id="id31" name="id31">Class <code><span>NSMutableArray</span></code></a></li>
+<li><a href="#class-nsmutablestring" id="id32" name="id32">Class <code><span>NSMutableString</span></code></a></li>
+<li><a href="#class-nsnetservice" id="id33" name="id33">Class <code><span>NSNetService</span></code></a></li>
+<li><a href="#class-nsobject" id="id34" name="id34">Class <code><span>NSObject</span></code></a></li>
+<li><a href="#class-nsscriptobjectspecifier" id="id35" name="id35">Class <code><span>NSScriptObjectSpecifier</span></code></a></li>
+<li><a href="#class-nsstring" id="id36" name="id36">Class <code><span>NSString</span></code></a></li>
+<li><a href="#class-nsthread" id="id37" name="id37">class <code><span>NSThread</span></code></a></li>
 </ul>
 </li>
-<li><a href="#foundation-framework" id="id21" name="id21">Foundation framework</a><ul>
-<li><a href="#class-nsarray" id="id22" name="id22">Class <code><span>NSArray</span></code></a></li>
-<li><a href="#class-nsautoreleasepool" id="id23" name="id23">Class <code><span>NSAutoreleasePool</span></code></a></li>
-<li><a href="#class-nscoder" id="id24" name="id24">Class <code><span>NSCoder</span></code></a></li>
-<li><a href="#class-nsdata" id="id25" name="id25">Class <code><span>NSData</span></code></a></li>
-<li><a href="#class-nsdecimalnumber-and-the-nsdecimal-type" id="id26" name="id26">Class <code><span>NSDecimalNumber</span></code> and the <code><span>NSDecimal</span></code> type</a></li>
-<li><a href="#class-nsdictionary" id="id27" name="id27">Class <code><span>NSDictionary</span></code></a></li>
-<li><a href="#class-nsexception" id="id28" name="id28">Class <code><span>NSException</span></code></a></li>
-<li><a href="#class-nsfault" id="id29" name="id29">Class <code><span>NSFault</span></code></a></li>
-<li><a href="#class-nsindexset" id="id30" name="id30">Class <code><span>NSIndexSet</span></code></a></li>
-<li><a href="#class-nsinvocation" id="id31" name="id31">Class <code><span>NSInvocation</span></code></a></li>
-<li><a href="#class-nsmutablearray" id="id32" name="id32">Class <code><span>NSMutableArray</span></code></a></li>
-<li><a href="#class-nsmutablestring" id="id33" name="id33">Class <code><span>NSMutableString</span></code></a></li>
-<li><a href="#class-nsnetservice" id="id34" name="id34">Class <code><span>NSNetService</span></code></a></li>
-<li><a href="#class-nsobject" id="id35" name="id35">Class <code><span>NSObject</span></code></a></li>
-<li><a href="#class-nsscriptobjectspecifier" id="id36" name="id36">Class <code><span>NSScriptObjectSpecifier</span></code></a></li>
-<li><a href="#class-nsset" id="id37" name="id37">Class <code><span>NSSet</span></code></a></li>
-<li><a href="#class-nsstring" id="id38" name="id38">Class <code><span>NSString</span></code></a></li>
-<li><a href="#class-nsthread" id="id39" name="id39">class <code><span>NSThread</span></code></a></li>
+<li><a href="#interfacebuilder-framework" id="id38" name="id38">InterfaceBuilder framework</a><ul>
+<li><a href="#class-ibobjcsourceparser" id="id39" name="id39">Class <code><span>IBObjCSourceParser</span></code></a></li>
+<li><a href="#id1" id="id40" name="id40">Class <code><span>NSView</span></code></a></li>
+<li><a href="#class-nsibobjectdata" id="id41" name="id41">Class <code><span>NSIBObjectData</span></code></a></li>
+<li><a href="#class-ibobjectcontainer" id="id42" name="id42">Class <code><span>IBObjectContainer</span></code></a></li>
+<li><a href="#class-ibxmldecoder" id="id43" name="id43">Class <code><span>IBXMLDecoder</span></code></a></li>
+<li><a href="#class-ibsplitscrollview" id="id44" name="id44">Class <code><span>IBSplitScrollView</span></code></a></li>
 </ul>
 </li>
-<li><a href="#interfacebuilder-framework" id="id40" name="id40">InterfaceBuilder framework</a><ul>
-<li><a href="#class-ibobjcsourceparser" id="id41" name="id41">Class <code><span>IBObjCSourceParser</span></code></a></li>
-<li><a href="#id1" id="id42" name="id42">Class <code><span>NSView</span></code></a></li>
-<li><a href="#class-nsibobjectdata" id="id43" name="id43">Class <code><span>NSIBObjectData</span></code></a></li>
-<li><a href="#class-ibobjectcontainer" id="id44" name="id44">Class <code><span>IBObjectContainer</span></code></a></li>
-<li><a href="#class-ibxmldecoder" id="id45" name="id45">Class <code><span>IBXMLDecoder</span></code></a></li>
-<li><a href="#class-ibsplitscrollview" id="id46" name="id46">Class <code><span>IBSplitScrollView</span></code></a></li>
-</ul>
-</li>
-<li><a href="#preferencepanes-framework" id="id47" name="id47">PreferencePanes framework</a></li>
-<li><a href="#screensaver-framework" id="id48" name="id48">ScreenSaver framework</a><ul>
-<li><a href="#class-screensaverdefaults" id="id49" name="id49">Class <code><span>ScreenSaverDefaults</span></code></a></li>
-<li><a href="#class-screensaverview" id="id50" name="id50">Class <code><span>ScreenSaverView</span></code></a></li>
-</ul>
-</li>
+<li><a href="#preferencepanes-framework" id="id45" name="id45">PreferencePanes framework</a></li>
 </ul>
 <p>TODO: Add documentation about weak linking (see intro.txt).</p>
 <h2><a href="#id2" name="introduction">Introduction</a></h2>
-<p>This document describes the restrictions w.r.t. supported APIs and classes
-on Mac OS X. In general you can use classes and global functions just like
-in Objective-C (e.g. the Apple developer documentation applies), but in some
-cases there are special considerations.</p>
-<p>We also do not provide access to global functions that are not useful for
-Python programs, those functions are listed below.</p>
-<p>This document lists the exceptions to the basic rules. If a method uses pointers
+<p>This document describes the restrictions with regard to supported APIs and
+classes on Mac OS X.  In general, classes and global functions are used just
+as they are in Objective-C (e.g. the Apple developer documentation applies),
+but in some cases there are special considerations.</p>
+<p>Global functions that are not useful for Python programs are not callable from
+Python, as listed below.</p>
+<p>This document lists the exceptions to the basic rules.  If a method uses pointers
 to return additional values, the Python wrapper for that method returns a tuple
-containing the original return value and the additional values. You don't have
-to pass values for those arguments, unless the method uses the values you
-pass in.</p>
+containing the original return value and the additional values.  It is not necessary
+to provide values for pointer arguments unless their initial value is used by the
+method.  Additionally, <code><span>objc.NULL</span></code> can be passed to denote that these arguments
+should be <code><span>NULL</span></code> rather than a pointer to allocated memory.</p>
 <p>This document is targeted at the latest supported version of Mac OS X (currently
-Mac OS X 10.3.x); unless specifically noted the same restrictions apply to 
-earlier versions of Mac OS X. Earlier versions of the OS have less extensive
-APIs, PyObjC does <i>not</i> provide a compatibility layer.</p>
-<p>Frameworks not listed below are not wrapped by PyObjC, they can still be
-accessed although without access to constants and global functions defined
-by those frameworks.</p>
+Mac OS X 10.4.x).  Unless specifically noted, the same restrictions apply to 
+earlier versions of Mac OS X.  Earlier versions of Mac OS X have less extensive
+APIs, and PyObjC does <i>not</i> provide a compatibility layer except when necessary
+to support its own operation.</p>
 <p>This document is not entirely complete, but does cover the most used APIs.
 Classes not mentioned in this document may very well work properly.</p>
+<p>Frameworks that do not have PyObjC wrappers can be loaded at runtime using
+the <code><span>objc.loadBundle</span></code>, <code><span>objc.loadBundleFunctions</span></code> and
+<code><span>objc.loadBundleVariables</span></code> functions.  In a future version of PyObjC,
+there will be an Objective-C header parser that can be used to automate this
+process and to generate wrappers.</p>
 <h2><a href="#id3" name="core-objective-c-runtime">Core Objective-C runtime</a></h2>
-<h3><a href="#id4" name="class-protocol">Class Protocol</a></h3>
-<ul>
-<li><code><span>descriptionForClassMethod:</span></code>, <code><span>descriptionForInstanceMethod</span></code><p>These methods are not supported. Protocols are hardly ever used explicitly
-in Cocoa therefore this should not be a problem.</p>
-</li>
-</ul>
-<h2><a href="#id5" name="addressbook-framework">Addressbook framework</a></h2>
-<p>We do not provide access to the global functions in this framework, because
-the same functionality can be accessed by using the object-oriented interface.</p>
-<h2><a href="#id6" name="appkit-framework">AppKit framework</a></h2>
-<p>The callback methods for the NSSheet API's have a non-default signature
+<h2><a href="#id4" name="addressbook-framework">Addressbook framework</a></h2>
+<p>The global functions in this framework are not wrapped, as the same 
+functionality can be accessed by using the object-oriented interface.</p>
+<h2><a href="#id5" name="appkit-framework">AppKit framework</a></h2>
+<p>The callback methods for the <code><span>NSSheet</span></code> API's have a non-default signature
 and no fixed name. You should therefore explicitly specify the signature. This
 is done by calling the <code><span>endSheetMethod</span></code> function after defining your
 callback:</p>
 <pre>
-class MYClass (NSObject):
-        def mysheetDidEnd(self, panel, returnCode, contextInfo):
+class MyClass(NSObject):
+        def mySheetDidEnd(self, panel, returnCode, contextInfo):
                 &quot;&quot;&quot; Actual implementation goes here &quot;&quot;&quot;
                 pass
 
-        mysheetDidEnd = PyObjCTools.AppHelper.endSheetMethod(
-                mysheetDidEnd)
+        mySheetDidEnd = PyObjCTools.AppHelper.endSheetMethod(
+                mySheetDidEnd)
+</pre>
+<p>In Python 2.4, this may be written using a decorator as such:</p>
+<pre>
+class MyClass(NSObject):
+        @PyObjCTools.AppHelper.endSheetMethod
+        def mySheetDidEnd(self, panel, returnCode, contextInfo):
+                &quot;&quot;&quot; Actual implementation goes here &quot;&quot;&quot;
+                pass
 </pre>
 <p>Unless otherwise noted, all <code><span>contextInfo</span></code> arguments are passed as integers,
 not as arbitrary pointers.</p>
-<h3><a href="#id7" name="class-nsapplication">Class NSApplication</a></h3>
-<p><code><span>NSModalSession</span></code> objects are wrapped as opaque values. You can check if
-two wrapper objects refer to the same session object by comparing their
-<code><span>ptr</span></code> attributes.</p>
-<h3><a href="#id8" name="class-nsbezierpath">Class NSBezierPath</a></h3>
+<h3><a href="#id6" name="class-nsapplication">Class NSApplication</a></h3>
+<p><code><span>NSModalSession</span></code> objects are wrapped as opaque values.  Two wrapper objects
+refer to the same session object if their <code><span>ptr</span></code> attributes are equal.</p>
+<h3><a href="#id7" name="class-nsbezierpath">Class NSBezierPath</a></h3>
 <ul>
 <li><code><span>getLineDash:count:phase:</span></code><p>Use <code><span>getLineDash_count_phase_(0)</span></code> to get the length of the pattern, and
 then use <code><span>getLineDash_count_phase_(actualCount)</span></code> to fetch all information.
 <li><code><span>setAssociatedPoints:atIndex:</span></code><p>Implementing this method in Python is not yet supported.</p>
 </li>
 </ul>
-<h3><a href="#id9" name="class-nsbitmapimagerep">Class <code><span>NSBitmapImageRep</span></code></a></h3>
+<h3><a href="#id8" name="class-nsbitmapimagerep">Class <code><span>NSBitmapImageRep</span></code></a></h3>
 <ul>
 <li><code><span>getBitMapDataPlanes</span></code><p>This method is not supported (yet)</p>
 </li>
 <li><code><span>initWithBitmapDataPlanes:pixesWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpaceName:bytesPerRow:bitsPerPixel:</span></code><p>This method is not supported (yet)</p>
 </li>
 </ul>
-<h3><a href="#id10" name="class-nsfont">Class <code><span>NSFont</span></code></a></h3>
+<h3><a href="#id9" name="class-nsfont">Class <code><span>NSFont</span></code></a></h3>
 <ul>
 <li><code><span>positionsForCompositeSequence:numberOfGlyphs:pointArray:</span></code><p>This method is not supported (yet)</p>
 </li>
 </ul>
-<h3><a href="#id11" name="class-nsgraphicscontext">Class <code><span>NSGraphicsContext</span></code></a></h3>
+<h3><a href="#id10" name="class-nsgraphicscontext">Class <code><span>NSGraphicsContext</span></code></a></h3>
 <ul>
 <li><code><span>focusStack</span></code><p>This method is not supported.</p>
 </li>
 at the moment.</p>
 </li>
 </ul>
-<h3><a href="#id12" name="class-nslayoutmanager">Class <code><span>NSLayoutManager</span></code></a></h3>
+<h3><a href="#id11" name="class-nslayoutmanager">Class <code><span>NSLayoutManager</span></code></a></h3>
 <ul>
 <li><code><span>getGlyphs:range:</span></code><p>This method is not yet supported</p>
 </li>
 <li><code><span>rectArrayForGlyphRange:withinSelectedGlyphRange:inTextContainer:rectCount:</span></code><p>This method is not yet supported</p>
 </li>
 </ul>
-<h3><a href="#id13" name="class-nsmatrix">Class <code><span>NSMatrix</span></code></a></h3>
+<h3><a href="#id12" name="class-nsmatrix">Class <code><span>NSMatrix</span></code></a></h3>
 <ul>
 <li><code><span>sortUsingFunction:context:</span></code><p>Calling this method from Python is supported, overriding it in Python
 is not. The <code><span>context</span></code> can be an arbitrary python object.</p>
 </li>
 </ul>
-<h3><a href="#id14" name="class-nsmovie">Class <code><span>NSMovie</span></code></a></h3>
+<h3><a href="#id13" name="class-nsmovie">Class <code><span>NSMovie</span></code></a></h3>
 <p>The return value of <code><span>QTMovie</span></code> and the sole argument of <code><span>initWithMovie:</span></code>
-are QT.Movie objects. Using these methods requires the use of MacPython 2.3.</p>
-<h3><a href="#id15" name="class-nsopenglcontext">Class <code><span>NSOpenGLContext</span></code></a></h3>
+are <code><span>Carbon.Qt.Movie</span></code> objects.</p>
+<h3><a href="#id14" name="class-nsopenglcontext">Class <code><span>NSOpenGLContext</span></code></a></h3>
 <ul>
 <li><code><span>getValues:forParameter:</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>
+<h3><a href="#id15" 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>
 </ul>
-<h3><a href="#id17" name="class-nsquickdrawview">Class <code><span>NSQuickDrawView</span></code></a></h3>
+<h3><a href="#id16" name="class-nsquickdrawview">Class <code><span>NSQuickDrawView</span></code></a></h3>
 <ul>
-<li><code><span>qdPort</span></code><p>This method returns an instance of type Carbon.QuickDraw. This 
-requires MacPython.</p>
+<li><code><span>qdPort</span></code><p>This method returns an instance of type <code><span>Carbon.Qd.GrafPort</span></code>.</p>
 </li>
 </ul>
-<h3><a href="#id18" name="class-nssimplehorizontaltypesetter">Class <code><span>NSSimpleHorizontalTypesetter</span></code></a></h3>
+<h3><a href="#id17" name="class-nssimplehorizontaltypesetter">Class <code><span>NSSimpleHorizontalTypesetter</span></code></a></h3>
 <ul>
 <li><code><span>baseOfTypesetterGlyphInfo</span></code><p>This method is not yet supported</p>
 </li>
 <li><code><span>layoutGlyphsInHorizontalLineFragment:baseline:</span></code><p>This method is not yet supported</p>
 </li>
 </ul>
-<h3><a href="#id19" name="class-nsview">Class <code><span>NSView</span></code></a></h3>
+<h3><a href="#id18" name="class-nsview">Class <code><span>NSView</span></code></a></h3>
 <ul>
 <li><code><span>sortSubviewsUsingFunction:context:</span></code><p>Calling this method from Python is supported, overriding it in Python
 is not. The <code><span>context</span></code> can be an arbitrary python object.</p>
 </li>
 </ul>
-<h3><a href="#id20" name="class-nswindow">Class <code><span>NSWindow</span></code></a></h3>
+<h3><a href="#id19" name="class-nswindow">Class <code><span>NSWindow</span></code></a></h3>
 <ul>
 <li><code><span>graphicsPort</span></code><p>This method is not yet supported</p>
 </li>
 <li><code><span>windowRef</span></code><p>This method is not yet supported</p>
 </li>
 </ul>
-<h2><a href="#id21" name="foundation-framework">Foundation framework</a></h2>
+<h2><a href="#id20" name="foundation-framework">Foundation framework</a></h2>
 <p>NOTE: The list below is mostly based on scripts that find methods that can
 not be automatically handled by the bridge. We have not yet performed a manual
 search for such methods in the Cocoa documentation.</p>
-<p>The <code><span>-forward::</span></code> and <code><span>performv::</span></code> methods are not supported.  You can
-work-around this using normal Python function invocation.</p>
-<p>Structs are wrapped using a struct-like type. They can be accessed using the
-field-names from Objective-C, or you can access them as sequences. Accessing
-them as sequences is necessary for backward compatibility and is deprecated.</p>
-<h3><a href="#id22" name="class-nsarray">Class <code><span>NSArray</span></code></a></h3>
+<p>The <code><span>-forward::</span></code> and <code><span>performv::</span></code> methods are not supported.  Normal Python
+function invocation can be used instead.</p>
+<p>Structs are wrapped using a struct-like type.  Struct members can be accessed
+using the field names as attributes, or they can be accessed as sequences for
+backwards compatibility.</p>
+<h3><a href="#id21" name="class-nsarray">Class <code><span>NSArray</span></code></a></h3>
 <ul>
-<li><code><span>initWithObjects:</span></code>, <code><span>arrayWithObjects:</span></code><p>These methods are not supported, use <code><span>initWithArray:</span></code> instead.</p>
-</li>
 <li><code><span>getObjects:</span></code><p>This method is not supported, accessing the objects using the usual
 accessor methods is just as efficient as using this method.</p>
 </li>
 <li><code><span>getObjects:inRange:</span></code><p>This method is not supported, accessing the objects using the usual
 accessor methods is just as efficient as using this method.</p>
 </li>
-<li><code><span>sortedArrayUsingFunction:context:</span></code> and <code><span>sortedArrayUsingFunction:context:hint</span></code><p>These methods can be called from Python, but you cannot override them
-from Python. This limitation will be lifted in a future version of PyObjC.</p>
+<li><code><span>sortedArrayUsingFunction:context:</span></code> and <code><span>sortedArrayUsingFunction:context:hint</span></code><p>These methods can be called from Python, but Python can not override them.
+This limitation will be lifted in a future version of PyObjC.</p>
 <p>The <code><span>context</span></code> can be an arbitrary python object.</p>
 </li>
 <li><code><span>addObserver:toObjectsAtIndexes:forKeyPath:options:context:</span></code><p>The context is an integer, not a <code><span>void*</span></code>.</p>
 </li>
 </ul>
-<h3><a href="#id23" name="class-nsautoreleasepool">Class <code><span>NSAutoreleasePool</span></code></a></h3>
-<p>The bridge automatically manages reference counts for you, but you're still 
+<h3><a href="#id22" name="class-nsautoreleasepool">Class <code><span>NSAutoreleasePool</span></code></a></h3>
+<p>The bridge automatically manages reference counts for you, but it is still 
 required to make an autorelease pool available.</p>
-<p>In simple, single-threaded GUI programs you don't have to do anything for this,
-because NSRunLoop does this for you and PyObjC creates an initial pool for the
-main thread.</p>
-<p>If you create lots of Cocoa objects in a loop it can be useful to manually create
-a pool to reclaim memory as soon as possible. The proper idiom for this is:</p>
+<p>In single-threaded programs that use <code><span>NSRunLoop</span></code> or are not long-lived,
+it is not necessary to explicitly manage <code><span>NSAutoreleasePool</span></code>, as
+<code><span>NSRunLoop</span></code> will push and pop one for each iteration, and PyObjC creates
+a <code><span>NSAutoreleasePool</span></code> in the thread it is imported in.</p>
+<p>When creating a large amount of objects in a loop, it may be useful to
+manually create a pool to reclaim memory as soon as possible. The proper
+idiom for this is:</p>
 <pre>
 while &lt;test&gt;:
         pool = NSAutoreleasePool.alloc().init()
 
         del pool
 </pre>
-<p>That is, you <i>must</i> ensure that the previous pool is deallocated before you create
-a new one, the code below will silently leak memory:</p>
+<p>The previous pool <i>must</i> be deallocated before a new one is
+created.  For example, the code below will <i>silently leak memory</i>:</p>
 <pre>
 while &lt;test&gt;:
+        # This pool is allocated BEFORE the previous is
+        # garbage collected, so the stack grows!
         pool = NSAutoreleasePool.alloc().init()
 
         # ... Do work here ...
 </pre>
-<h3><a href="#id24" name="class-nscoder">Class <code><span>NSCoder</span></code></a></h3>
+<p>In threads other than the main thread, as with Objective-C applications, it
+is necessary to create an <code><span>NSAutoreleasePool</span></code> as soon as possible before
+using other Objective-C objects.</p>
+<h3><a href="#id23" name="class-nscoder">Class <code><span>NSCoder</span></code></a></h3>
 <p>The following methods are not supported in the current version of PyObjC.
 This limitation will be lifted in a future version of the bridge.</p>
 <ul>
 <li><code><span>encodeValuesOfObjCType:</span></code><p>Use multiple calls to <code><span>encodeValueOfObjCType:at:</span></code> instead.</p>
 </li>
-<li><code><span>decodeValuesOfObjCType:</span></code><p>Use multiple calls to <code><span>decodeValueOfObjCType:at:</span></code> instead. Note that
-that won't work if your trying to read back data that was written using
+<li><code><span>decodeValuesOfObjCType:</span></code><p>Use multiple calls to <code><span>decodeValueOfObjCType:at:</span></code> instead.
+Note that this will not read back data that was written using
 <code><span>encodeValuesOfObjCType:</span></code>.</p>
 </li>
 </ul>
 <p>The method <code><span>decodeBytesWithoutReturnedLength:</span></code> is not supported, use 
-<code><span>decodeBytesWithReturnedLength:</span></code> instead. It is not possible to safely
+<code><span>decodeBytesWithReturnedLength:</span></code> instead.  It is not possible to safely
 represent the return value of this method in Python.</p>
-<h3><a href="#id25" name="class-nsdata">Class <code><span>NSData</span></code></a></h3>
+<h3><a href="#id24" name="class-nsdata">Class <code><span>NSData</span></code></a></h3>
 <p>NSData subclasses support the Python buffer protocol, and any Python
 object that implements the Python buffer protocol (except str and unicode)
 are wrapped as an NSData subclass.</p>
 </li>
 <li><code><span>deserializeInts:count:atIndex:</span></code><p>This is a deprecated method, see Apple documentation.</p>
 </li>
-<li><code><span>getBytes:</span></code>, <code><span>getBytes:length:</span></code>, <code><span>getBytes:range:</span></code>
-Use <code><span>bytes</span></code> instead, and then use subscripting to get the
-desired range.</li>
+<li><code><span>getBytes:</span></code>, <code><span>getBytes:length:</span></code>, <code><span>getBytes:range:</span></code><p>Use <code><span>bytes</span></code> instead, and then use subscripting to get the
+desired range.</p>
+</li>
 </ul>
-<h3><a href="#id26" name="class-nsdecimalnumber-and-the-nsdecimal-type">Class <code><span>NSDecimalNumber</span></code> and the <code><span>NSDecimal</span></code> type</a></h3>
+<h3><a href="#id25" name="class-nsdecimalnumber-and-the-nsdecimal-type">Class <code><span>NSDecimalNumber</span></code> and the <code><span>NSDecimal</span></code> type</a></h3>
 <p>NSDecimal is wrapped by a Python type.</p>
 <p>Creating an <code><span>NSDecimal</span></code> instance: <code><span>NSDecimal(value)</span></code> or 
 <code><span>NSDecimal(mantisssa,</span> <span>exponent,</span> <span>isNegative)</span></code>.  <code><span>Value</span></code> can be a string,
 int or long (not a float because of the representation issues for floats).</p>
 <p>Converting an <code><span>NSDecimal</span></code> to a float or int: <code><span>aDecimal.as_int()</span></code> and
 <code><span>aDecimal.as_float</span></code>.</p>
-<h3><a href="#id27" name="class-nsdictionary">Class <code><span>NSDictionary</span></code></a></h3>
+<h3><a href="#id26" name="class-nsdictionary">Class <code><span>NSDictionary</span></code></a></h3>
 <p>The (undocumented) methods <code><span>getKeys:</span></code>, <code><span>getObjects:</span></code> and 
 <code><span>getObjects:andKeys:</span></code> are not supported.</p>
-<h3><a href="#id28" name="class-nsexception">Class <code><span>NSException</span></code></a></h3>
+<h3><a href="#id27" name="class-nsexception">Class <code><span>NSException</span></code></a></h3>
 <ul>
 <li><code><span>raise:format:</span></code>, <code><span>raise:format:arguments:</span></code><p>These methods are not supported because they accept a variable number of
-arguments. Use Python's <code><span>%</span></code> operator to format the message.</p>
+arguments.  Use Python's <code><span>%</span></code> operator to format the message.  A future
+version of PyObjC may be able to parse format strings and do the right
+thing.</p>
 </li>
 </ul>
-<h3><a href="#id29" name="class-nsfault">Class <code><span>NSFault</span></code></a></h3>
+<h3><a href="#id28" name="class-nsfault">Class <code><span>NSFault</span></code></a></h3>
 <p>The <code><span>extraData</span></code> argument/return value for <code><span>-extraData</span></code> and 
 <code><span>setTargetClassextraData:</span></code> is represented as an integer.</p>
-<h3><a href="#id30" name="class-nsindexset">Class <code><span>NSIndexSet</span></code></a></h3>
+<h3><a href="#id29" name="class-nsindexset">Class <code><span>NSIndexSet</span></code></a></h3>
 <ul>
 <li><code><span>getIndexes:maxCount:inIndexRange:</span></code>
 The usage is:<pre>
 </pre>
 </li>
 </ul>
-<h3><a href="#id31" name="class-nsinvocation">Class <code><span>NSInvocation</span></code></a></h3>
-<p>In some versions of Mac OS X, NSInvocation doesn't work properly with structs
-that contain padding. Such structs are not used in the Mac OS X API, but may
-be present in 3th party code. This leads to problems when <code><span>forwardInvocation:</span></code>
-is used to call a method that has such a struct as one of its arguments.</p>
-<h3><a href="#id32" name="class-nsmutablearray">Class <code><span>NSMutableArray</span></code></a></h3>
+<h3><a href="#id30" name="class-nsinvocation">Class <code><span>NSInvocation</span></code></a></h3>
+<p>In some versions of Mac OS X, <code><span>NSInvocation</span></code> doesn't work properly with structs
+that contain padding for alignment.  Such structs are not used in the Mac OS X API,
+but may be present in 3rd party code.  This leads to problems when
+<code><span>forwardInvocation:</span></code> is used to call a method that has such a struct as one of
+its arguments.</p>
+<h3><a href="#id31" name="class-nsmutablearray">Class <code><span>NSMutableArray</span></code></a></h3>
 <ul>
 <li><code><span>sortUsingFunction:context:</span></code>, <code><span>sortUsingFunction:context:range:</span></code><p>Calling this method from Python is supported, overriding it in a subclass
-is not. This limitation will be fixed in a later version of PyObjC.</p>
-<p>The <code><span>context</span></code> can be an arbitrary python object.</p>
+is not.  This limitation will be fixed in a later version of PyObjC.</p>
+<p>The <code><span>context</span></code> can be an arbitrary Python object.</p>
 </li>
 </ul>
-<h3><a href="#id33" name="class-nsmutablestring">Class <code><span>NSMutableString</span></code></a></h3>
+<h3><a href="#id32" name="class-nsmutablestring">Class <code><span>NSMutableString</span></code></a></h3>
 <ul>
 <li><code><span>appendFormat:</span></code><p>This method is not supported because it accepts a variable number of 
 arguments. Use Python's <code><span>%</span></code> operator to format strings.</p>
 </li>
 </ul>
-<h3><a href="#id34" name="class-nsnetservice">Class <code><span>NSNetService</span></code></a></h3>
+<h3><a href="#id33" name="class-nsnetservice">Class <code><span>NSNetService</span></code></a></h3>
 <ul>
 <li><code><span>addresses</span></code><p>When calling this from Python this methods returns a tuple of address info
 tuples, like the values returned by <code><span>socket.getpeeraddr()</span></code>.</p>
 </li>
 </ul>
-<h3><a href="#id35" name="class-nsobject">Class <code><span>NSObject</span></code></a></h3>
+<h3><a href="#id34" name="class-nsobject">Class <code><span>NSObject</span></code></a></h3>
 <ul>
 <li><code><span>observationInfo</span></code>, <code><span>setObservationInfo:</span></code><p>These methods can be used from Python, but the <code><span>observationInfo</span></code> is 
 represented by an integer instead of <code><span>void*</span></code>. This probably makes it
 </li>
 <li><code><span>observeValueForKeyPath:ofObject:change:context:</span></code><p>The context is an integer</p>
 </li>
-<li><code><span>methodForSelector:</span></code>, <code><span>instanceMethodForSelector:</span></code><p>These methods return instances of objc.IMP. The major difference with
-Objective-C is that you don't have to, or even can, pass the selector to
-the IMP. In other words, the interface is the same as for unbound
-instance methods: you have to pass <code><span>self</span></code> and the method arguments.</p>
+<li><code><span>methodForSelector:</span></code>, <code><span>instanceMethodForSelector:</span></code><p>These methods return instances of <code><span>objc.IMP</span></code>.  The major difference from
+Objective-C is that the selector argument is omitted.  In other words,
+using an <code><span>objc.IMP</span></code> is the same as using an unbound selector; <code><span>self</span></code>
+must be passed explicitly as the first argument, and the other arguments
+are passed as usual.</p>
 <p>WARNING: This interface is experimental and might change in a future version
 of PyObjC.</p>
 </li>
 </ul>
-<h3><a href="#id36" name="class-nsscriptobjectspecifier">Class <code><span>NSScriptObjectSpecifier</span></code></a></h3>
+<h3><a href="#id35" name="class-nsscriptobjectspecifier">Class <code><span>NSScriptObjectSpecifier</span></code></a></h3>
 <ul>
 <li><code><span>indicesOfObjectsByEvaluatingWithContainer:count:</span></code><p>Implementing this in Python is not supported yet. We're looking for a way
 to avoid leaking the returned buffer, as we cannot return a pointer to an
 internal data-structure.</p>
 </li>
 </ul>
-<h3><a href="#id37" name="class-nsset">Class <code><span>NSSet</span></code></a></h3>
-<ul>
-<li><code><span>initWithObjects:</span></code>, <code><span>setWithObjects:</span></code><p>This method is not supported, use <code><span>initWithArray:</span></code> instead.</p>
-</li>
-</ul>
-<h3><a href="#id38" name="class-nsstring">Class <code><span>NSString</span></code></a></h3>
-<p>Objective-C strings are usually represented as instances of a subclass of
+<h3><a href="#id36" name="class-nsstring">Class <code><span>NSString</span></code></a></h3>
+<p>Objective-C strings are represented as instances of a subclass of
 the Python type <code><span>unicode</span></code>.  Since Python <code><span>unicode</span></code> objects are immutable,
 working with <code><span>NSMutableString</span></code> can be tricky.  If you need to update the
 Python representation of the string, use <code><span>aString.self()</span></code>, which will be a
-new string.</p>
+new Python proxy for the same <code><span>NSMutableString</span></code> instance.</p>
 <ul>
-<li><code><span>initWithCharactersNoCopy:length:freeWhenDone:</span></code><p>This method is unsupported because we cannot guarantee that the buffer will
+<li><code><span>initWithCharactersNoCopy:length:freeWhenDone:</span></code><p>This method is unsupported because we can not guarantee that the buffer will
 be available as long as the string is. Use <code><span>initWithCharacters:</span></code> instead.</p>
 </li>
-<li><code><span>getCharacters:</span></code> and <code><span>getCharacters:range:</span></code><p>These methods are not supported at the moment. This limitation will be lifted
+<li><code><span>getCharacters:</span></code> and <code><span>getCharacters:range:</span></code><p>These methods are not supported at the moment.  This limitation will be lifted
 in a future version of the bridge.</p>
 </li>
 <li><code><span>getCString:maxLength:range:remainingRange:</span></code> and <code><span>getCString:maxLength:</span></code><p>Calling these methods from Python is supported, overriding them from 
 bridge.</p>
 </li>
 <li><code><span>getCString:</span></code><p>This method is not supported. Use <code><span>getCString:maxLength:</span></code> instead (using
-the length of the string as the maximum length). This limitation will be
+the length of the string as the maximum length).  This limitation will be
 lifted in a future version of the bridge.</p>
 </li>
 <li><code><span>stringWithFormat:</span></code>, <code><span>initWithFormat:</span></code>, <code><span>initWithFormat:locale:</span></code>,
 <code><span>stringByAppendingFormat:</span></code><p>These methods are not supported because they accept a variable number of 
-arguments. Use Python's <code><span>%</span></code> operator to format strings.</p>
+arbitrarily typed arguments.  Use Python's <code><span>%</span></code> operator to format strings.
+A future version of PyObjC may be able to parse format strings and do the
+right thing here.</p>
 </li>
 <li><code><span>initWithFormat:arguments:</span></code>, <code><span>initWithFormat:locale:arguments:</span></code><p>These are also not supported, with the same workaround.</p>
 </li>
 </ul>
-<h3><a href="#id39" name="class-nsthread">class <code><span>NSThread</span></code></a></h3>
+<h3><a href="#id37" name="class-nsthread">class <code><span>NSThread</span></code></a></h3>
 <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>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 
-performance impact.</p>
+<li><code><span>detachNewThreadSelector:toTarget:withObject:</span></code><p>As with Objective-C, make sure to create an <code><span>NSAutoreleasePool</span></code> in this
+the detached thread.</p>
 </li>
 </ul>
-<h2><a href="#id40" name="interfacebuilder-framework">InterfaceBuilder framework</a></h2>
+<h2><a href="#id38" name="interfacebuilder-framework">InterfaceBuilder framework</a></h2>
 <p>I (Ronald) have not found documentation for this framework, therefore the
 following methods with a &quot;difficult&quot; signature are not supported.</p>
 <p>Please let me know if there is documentation for this framework.</p>
-<h3><a href="#id41" name="class-ibobjcsourceparser">Class <code><span>IBObjCSourceParser</span></code></a></h3>
+<h3><a href="#id39" name="class-ibobjcsourceparser">Class <code><span>IBObjCSourceParser</span></code></a></h3>
 <ul>
 <li><code><span>parseClass:</span></code></li>
 </ul>
-<h3><a href="#id42" name="id1">Class <code><span>NSView</span></code></a></h3>
+<h3><a href="#id40" name="id1">Class <code><span>NSView</span></code></a></h3>
 <ul>
 <li><code><span>objectAtPoint:rect:</span></code><p>Defined in a category on <code><span>NSView</span></code>.</p>
 </li>
 </ul>
-<h3><a href="#id43" name="class-nsibobjectdata">Class <code><span>NSIBObjectData</span></code></a></h3>
+<h3><a href="#id41" name="class-nsibobjectdata">Class <code><span>NSIBObjectData</span></code></a></h3>
 <ul>
 <li><code><span>restoreFromObjectDataInfo:</span></code></li>
 <li><code><span>snapshotIntoObjectDataInfo:</span></code></li>
 </ul>
-<h3><a href="#id44" name="class-ibobjectcontainer">Class <code><span>IBObjectContainer</span></code></a></h3>
+<h3><a href="#id42" name="class-ibobjectcontainer">Class <code><span>IBObjectContainer</span></code></a></h3>
 <ul>
 <li><code><span>decodeObjectToIntMapTableForKey:fromCoder:alwaysCreate:</span></code></li>
 <li><code><span>decodeObjectToObjectMapTableForKey:fromCoder:alwaysCreate:</span></code></li>
 </ul>
-<h3><a href="#id45" name="class-ibxmldecoder">Class <code><span>IBXMLDecoder</span></code></a></h3>
+<h3><a href="#id43" name="class-ibxmldecoder">Class <code><span>IBXMLDecoder</span></code></a></h3>
 <ul>
 <li><code><span>allocObjectWithClassName:</span></code></li>
 </ul>
-<h3><a href="#id46" name="class-ibsplitscrollview">Class <code><span>IBSplitScrollView</span></code></a></h3>
+<h3><a href="#id44" name="class-ibsplitscrollview">Class <code><span>IBSplitScrollView</span></code></a></h3>
 <ul>
 <li><code><span>getMinimumX:maximumX:</span></code></li>
 </ul>
-<h2><a href="#id47" name="preferencepanes-framework">PreferencePanes framework</a></h2>
+<h2><a href="#id45" name="preferencepanes-framework">PreferencePanes framework</a></h2>
 <p>This framework seems to define useful classes like <code><span>NSAuthorization</span></code> and
 <code><span>NSKeychain</span></code>, but these are not documented and some useful methods have
 a hard signature.</p>
 <p>The only documented class, <code><span>NSPreferencePane</span></code>, is fully supported.</p>
-<h2><a href="#id48" name="screensaver-framework">ScreenSaver framework</a></h2>
-<h3><a href="#id49" name="class-screensaverdefaults">Class <code><span>ScreenSaverDefaults</span></code></a></h3>
-<p>This class is fully supported.</p>
-<h3><a href="#id50" name="class-screensaverview">Class <code><span>ScreenSaverView</span></code></a></h3>
-<p>This class is fully supported.</p>
 </body>
 </html>

Doc/api-notes-macosx.txt

 Introduction
 ------------
 
-This document describes the restrictions w.r.t. supported APIs and classes
-on Mac OS X. In general you can use classes and global functions just like
-in Objective-C (e.g. the Apple developer documentation applies), but in some
-cases there are special considerations.
+This document describes the restrictions with regard to supported APIs and
+classes on Mac OS X.  In general, classes and global functions are used just
+as they are in Objective-C (e.g. the Apple developer documentation applies),
+but in some cases there are special considerations.
 
-We also do not provide access to global functions that are not useful for
-Python programs, those functions are listed below.
+Global functions that are not useful for Python programs are not callable from
+Python, as listed below.
 
-This document lists the exceptions to the basic rules. If a method uses pointers
+This document lists the exceptions to the basic rules.  If a method uses pointers
 to return additional values, the Python wrapper for that method returns a tuple
-containing the original return value and the additional values. You don't have
-to pass values for those arguments, unless the method uses the values you
-pass in.
+containing the original return value and the additional values.  It is not necessary
+to provide values for pointer arguments unless their initial value is used by the
+method.  Additionally, ``objc.NULL`` can be passed to denote that these arguments
+should be ``NULL`` rather than a pointer to allocated memory.
 
 This document is targeted at the latest supported version of Mac OS X (currently
-Mac OS X 10.3.x); unless specifically noted the same restrictions apply to 
-earlier versions of Mac OS X. Earlier versions of the OS have less extensive
-APIs, PyObjC does *not* provide a compatibility layer.
-
-Frameworks not listed below are not wrapped by PyObjC, they can still be
-accessed although without access to constants and global functions defined
-by those frameworks.
+Mac OS X 10.4.x).  Unless specifically noted, the same restrictions apply to 
+earlier versions of Mac OS X.  Earlier versions of Mac OS X have less extensive
+APIs, and PyObjC does *not* provide a compatibility layer except when necessary
+to support its own operation.
 
 This document is not entirely complete, but does cover the most used APIs.
 Classes not mentioned in this document may very well work properly.
 
+Frameworks that do not have PyObjC wrappers can be loaded at runtime using
+the ``objc.loadBundle``, ``objc.loadBundleFunctions`` and
+``objc.loadBundleVariables`` functions.  In a future version of PyObjC,
+there will be an Objective-C header parser that can be used to automate this
+process and to generate wrappers.
+
 Core Objective-C runtime
 ------------------------
 
-Class Protocol
-..............
-
-* ``descriptionForClassMethod:``, ``descriptionForInstanceMethod``
-
-  These methods are not supported. Protocols are hardly ever used explicitly
-  in Cocoa therefore this should not be a problem.
-
 Addressbook framework
 ---------------------
 
-We do not provide access to the global functions in this framework, because
-the same functionality can be accessed by using the object-oriented interface.
+The global functions in this framework are not wrapped, as the same 
+functionality can be accessed by using the object-oriented interface.
 
 AppKit framework
 ----------------
 
-The callback methods for the NSSheet API's have a non-default signature
+The callback methods for the ``NSSheet`` API's have a non-default signature
 and no fixed name. You should therefore explicitly specify the signature. This
 is done by calling the ``endSheetMethod`` function after defining your
 callback::
 	
-	class MYClass (NSObject):
-		def mysheetDidEnd(self, panel, returnCode, contextInfo):
+	class MyClass(NSObject):
+		def mySheetDidEnd(self, panel, returnCode, contextInfo):
 			""" Actual implementation goes here """
 			pass
 
-		mysheetDidEnd = PyObjCTools.AppHelper.endSheetMethod(
-			mysheetDidEnd)
+		mySheetDidEnd = PyObjCTools.AppHelper.endSheetMethod(
+			mySheetDidEnd)
+
+In Python 2.4, this may be written using a decorator as such::
+
+	class MyClass(NSObject):
+		@PyObjCTools.AppHelper.endSheetMethod
+		def mySheetDidEnd(self, panel, returnCode, contextInfo):
+			""" Actual implementation goes here """
+			pass
 
 Unless otherwise noted, all ``contextInfo`` arguments are passed as integers,
 not as arbitrary pointers.
 Class NSApplication
 ...................
 
-``NSModalSession`` objects are wrapped as opaque values. You can check if
-two wrapper objects refer to the same session object by comparing their
-``ptr`` attributes.
+``NSModalSession`` objects are wrapped as opaque values.  Two wrapper objects
+refer to the same session object if their ``ptr`` attributes are equal.
 
 Class NSBezierPath
 ..................
 .................
 
 The return value of ``QTMovie`` and the sole argument of ``initWithMovie:``
-are QT.Movie objects. Using these methods requires the use of MacPython 2.3.
+are ``Carbon.Qt.Movie`` objects.
 
 Class ``NSOpenGLContext``
 .........................
 
 * ``qdPort``
 
-  This method returns an instance of type Carbon.QuickDraw. This 
-  requires MacPython.
+  This method returns an instance of type ``Carbon.Qd.GrafPort``.
 
 Class ``NSSimpleHorizontalTypesetter``
 ......................................
 not be automatically handled by the bridge. We have not yet performed a manual
 search for such methods in the Cocoa documentation.
 
-The ``-forward::`` and ``performv::`` methods are not supported.  You can
-work-around this using normal Python function invocation.
+The ``-forward::`` and ``performv::`` methods are not supported.  Normal Python
+function invocation can be used instead.
 
-Structs are wrapped using a struct-like type. They can be accessed using the
-field-names from Objective-C, or you can access them as sequences. Accessing
-them as sequences is necessary for backward compatibility and is deprecated.
+Structs are wrapped using a struct-like type.  Struct members can be accessed
+using the field names as attributes, or they can be accessed as sequences for
+backwards compatibility.
 
 Class ``NSArray``
 .................
 
-* ``initWithObjects:``, ``arrayWithObjects:``
-
-  These methods are not supported, use ``initWithArray:`` instead.
-
 * ``getObjects:``
 
   This method is not supported, accessing the objects using the usual
 
 * ``sortedArrayUsingFunction:context:`` and ``sortedArrayUsingFunction:context:hint``
 
-  These methods can be called from Python, but you cannot override them
-  from Python. This limitation will be lifted in a future version of PyObjC.
+  These methods can be called from Python, but Python can not override them.
+  This limitation will be lifted in a future version of PyObjC.
 
   The ``context`` can be an arbitrary python object.
 
 Class ``NSAutoreleasePool``
 ...........................
 
-The bridge automatically manages reference counts for you, but you're still 
+The bridge automatically manages reference counts for you, but it is still 
 required to make an autorelease pool available. 
 
-In simple, single-threaded GUI programs you don't have to do anything for this,
-because NSRunLoop does this for you and PyObjC creates an initial pool for the
-main thread.
+In single-threaded programs that use ``NSRunLoop`` or are not long-lived,
+it is not necessary to explicitly manage ``NSAutoreleasePool``, as
+``NSRunLoop`` will push and pop one for each iteration, and PyObjC creates
+a ``NSAutoreleasePool`` in the thread it is imported in.
 
-If you create lots of Cocoa objects in a loop it can be useful to manually create
-a pool to reclaim memory as soon as possible. The proper idiom for this is::
+When creating a large amount of objects in a loop, it may be useful to
+manually create a pool to reclaim memory as soon as possible. The proper
+idiom for this is::
 
 	while <test>:
 		pool = NSAutoreleasePool.alloc().init()
 
 		del pool
 
-That is, you *must* ensure that the previous pool is deallocated before you create
-a new one, the code below will silently leak memory::
+The previous pool *must* be deallocated before a new one is
+created.  For example, the code below will *silently leak memory*::
 
 	while <test>:
+                # This pool is allocated BEFORE the previous is
+                # garbage collected, so the stack grows!
 		pool = NSAutoreleasePool.alloc().init()
 
 		# ... Do work here ...
 
+In threads other than the main thread, as with Objective-C applications, it
+is necessary to create an ``NSAutoreleasePool`` as soon as possible before
+using other Objective-C objects.
+
 Class ``NSCoder``
 .................
 
 
 * ``decodeValuesOfObjCType:``
 
-  Use multiple calls to ``decodeValueOfObjCType:at:`` instead. Note that
-  that won't work if your trying to read back data that was written using
+  Use multiple calls to ``decodeValueOfObjCType:at:`` instead.
+  Note that this will not read back data that was written using
   ``encodeValuesOfObjCType:``.
 
 The method ``decodeBytesWithoutReturnedLength:`` is not supported, use 
-``decodeBytesWithReturnedLength:`` instead. It is not possible to safely
+``decodeBytesWithReturnedLength:`` instead.  It is not possible to safely
 represent the return value of this method in Python.
 
 
   This is a deprecated method, see Apple documentation.
 
 * ``getBytes:``, ``getBytes:length:``, ``getBytes:range:``
+
   Use ``bytes`` instead, and then use subscripting to get the
   desired range.
 
 * ``raise:format:``, ``raise:format:arguments:``
 
   These methods are not supported because they accept a variable number of
-  arguments. Use Python's ``%`` operator to format the message.
+  arguments.  Use Python's ``%`` operator to format the message.  A future
+  version of PyObjC may be able to parse format strings and do the right
+  thing.
 
 Class ``NSFault``
 .................
 Class ``NSInvocation``
 ......................
 
-In some versions of Mac OS X, NSInvocation doesn't work properly with structs
-that contain padding. Such structs are not used in the Mac OS X API, but may
-be present in 3th party code. This leads to problems when ``forwardInvocation:``
-is used to call a method that has such a struct as one of its arguments.
+In some versions of Mac OS X, ``NSInvocation`` doesn't work properly with structs
+that contain padding for alignment.  Such structs are not used in the Mac OS X API,
+but may be present in 3rd party code.  This leads to problems when
+``forwardInvocation:`` is used to call a method that has such a struct as one of
+its arguments.
 
 Class ``NSMutableArray``
 ........................
 * ``sortUsingFunction:context:``, ``sortUsingFunction:context:range:``
 
   Calling this method from Python is supported, overriding it in a subclass
-  is not. This limitation will be fixed in a later version of PyObjC.
+  is not.  This limitation will be fixed in a later version of PyObjC.
 
-  The ``context`` can be an arbitrary python object.
+  The ``context`` can be an arbitrary Python object.
 
 Class ``NSMutableString``
 .........................
 
 * ``methodForSelector:``, ``instanceMethodForSelector:``
 
-  These methods return instances of objc.IMP. The major difference with
-  Objective-C is that you don't have to, or even can, pass the selector to
-  the IMP. In other words, the interface is the same as for unbound
-  instance methods: you have to pass ``self`` and the method arguments.
+  These methods return instances of ``objc.IMP``.  The major difference from
+  Objective-C is that the selector argument is omitted.  In other words,
+  using an ``objc.IMP`` is the same as using an unbound selector; ``self``
+  must be passed explicitly as the first argument, and the other arguments
+  are passed as usual.
 
   WARNING: This interface is experimental and might change in a future version
   of PyObjC.
   to avoid leaking the returned buffer, as we cannot return a pointer to an
   internal data-structure.
 
-Class ``NSSet``
-...............
-
-* ``initWithObjects:``, ``setWithObjects:``
-
-  This method is not supported, use ``initWithArray:`` instead.
-
-
 Class ``NSString``
 ..................
 
-Objective-C strings are usually represented as instances of a subclass of
+Objective-C strings are represented as instances of a subclass of
 the Python type ``unicode``.  Since Python ``unicode`` objects are immutable,
 working with ``NSMutableString`` can be tricky.  If you need to update the
 Python representation of the string, use ``aString.self()``, which will be a
-new string.
+new Python proxy for the same ``NSMutableString`` instance.
 
 * ``initWithCharactersNoCopy:length:freeWhenDone:`` 
 
-  This method is unsupported because we cannot guarantee that the buffer will
+  This method is unsupported because we can not guarantee that the buffer will
   be available as long as the string is. Use ``initWithCharacters:`` instead.
 
 * ``getCharacters:`` and ``getCharacters:range:``
 
-  These methods are not supported at the moment. This limitation will be lifted
+  These methods are not supported at the moment.  This limitation will be lifted
   in a future version of the bridge.
 
 * ``getCString:maxLength:range:remainingRange:`` and ``getCString:maxLength:``
 * ``getCString:``
 
   This method is not supported. Use ``getCString:maxLength:`` instead (using
-  the length of the string as the maximum length). This limitation will be
+  the length of the string as the maximum length).  This limitation will be
   lifted in a future version of the bridge.
  
 * ``stringWithFormat:``, ``initWithFormat:``, ``initWithFormat:locale:``,
   ``stringByAppendingFormat:``
 
   These methods are not supported because they accept a variable number of 
-  arguments. Use Python's ``%`` operator to format strings.
+  arbitrarily typed arguments.  Use Python's ``%`` operator to format strings.
+  A future version of PyObjC may be able to parse format strings and do the
+  right thing here.
 
 * ``initWithFormat:arguments:``, ``initWithFormat:locale:arguments:``
 
 
 * ``detachNewThreadSelector:toTarget:withObject:``
 
-  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 
-  interpreter. We don't do this by default because this has a negative 
-  performance impact.
+  As with Objective-C, make sure to create an ``NSAutoreleasePool`` in this
+  the detached thread.
 
 InterfaceBuilder framework
 --------------------------
 ``NSKeychain``, but these are not documented and some useful methods have
 a hard signature.
 
-The only documented class, ``NSPreferencePane``, is fully supported.
-
-ScreenSaver framework
----------------------
-
-Class ``ScreenSaverDefaults``
-.............................
-
-This class is fully supported.
-
-Class ``ScreenSaverView``
-.........................
-
-This class is fully supported.
-
+The only documented class, ``NSPreferencePane``, is fully supported.
 <h2>Python classes and Objective-C code</h2>
 <!-- This file is formatted using the rules for reStructuredText -->
 <!-- Version 0.2 -->
-<h2><a>Introduction</a></h2>
+<h2><a name="introduction">Introduction</a></h2>
 <p>PyObjC is a proxy between Objective-C and Python and allows access to Python
-classes from Objective-C and vice versa.  PyObjC also allows you to subclass
-Objective-C classes from Python.</p>
-<h2><a>Accessing Python objects from Objective-C</a></h2>
+classes from Objective-C and vice versa.  PyObjC also allows Python to subclass
+Objective-C classes, and these subclasses will be natively visible to both runtimes.</p>
+<h2><a name="accessing-python-objects-from-objective-c">Accessing Python objects from Objective-C</a></h2>
 <p>All Python objects can be accessed from Objective-C through proxy objects. 
 Whenever a Python object crosses the line from Python to Objective-C a proxy
 object is created (of class <code><span>OC_PythonObject</span></code>, a subclass of <code><span>NSProxy</span></code>).
 <li>Python numbers (<code><span>int</span></code>, <code><span>float</span></code>, <code><span>long</span></code>) are translated into
 <code><span>NSNumber</span></code> instances.  Their identity is not preserved across the bridge.</li>
 <li>Python <code><span>str</span></code> is proxied using <code><span>OC_PythonString</span></code>, a subclass of
-<code><span>NSString</span></code>.  You may use a Python <code><span>str</span></code> anywhere a <code><span>NSString</span></code> is
-expected, but you should use <code><span>unicode</span></code> whenever possible.
+<code><span>NSString</span></code>.  A Python <code><span>str</span></code> may be used anywhere a <code><span>NSString</span></code> is
+expected, but <code><span>unicode</span></code> should be used whenever possible.
 <code><span>OC_PythonString</span></code> will use the default encoding of <code><span>NSString</span></code>, which is
 normally MacRoman but could be something else.</li>
 <li>Python <code><span>unicode</span></code> is proxied using <code><span>OC_PythonUnicode</span></code>, a subclass of
-<code><span>NSString</span></code>.  You may use a Python <code><span>unicode</span></code> anywhere a <code><span>NSString</span></code>
+<code><span>NSString</span></code>.  A Python <code><span>unicode</span></code> may be used anywhere a <code><span>NSString</span></code>
 is expected.</li>
 <li>Python <code><span>dict</span></code> is proxied using <code><span>OC_PythonDictionary</span></code>, a subclass of
-<code><span>NSMutableDictionary</span></code>.  This allows you to use a Python <code><span>dict</span></code>
-everywhere where an <code><span>NSDictionary</span></code> is expected.</li>
+<code><span>NSMutableDictionary</span></code>.  A Python <code><span>dict</span></code> may be used anywhere 
+an <code><span>NSDictionary</span></code> is expected.</li>
 <li>Python <code><span>list</span></code> and <code><span>tuple</span></code> are proxied using <code><span>OC_PythonArray</span></code>, a
-subclass of <code><span>NSMutableArray</span></code>.  This allows you to use a Python <code><span>list</span></code>
-or <code><span>tuple</span></code> everywhere where an <code><span>NSArray</span></code> is expected.</li>
+subclass of <code><span>NSMutableArray</span></code>.  Python <code><span>list</span></code> or <code><span>tuple</span></code> objects
+may be used anywhere an <code><span>NSArray</span></code> is expected.</li>
 <li>Python objects that implement the Python buffer API, except for <code><span>str</span></code>
 and <code><span>unicode</span></code>, are proxied using <code><span>OC_PythonData</span></code>, a <code><span>NSData</span></code> subclass.
-This allows you to use instances of classes such as <code><span>buffer</span></code>,
-<code><span>array.array</span></code>, <code><span>mmap.mmap</span></code>, etc. anywhere <code><span>NSData</span></code> is expected.</li>
+Objects that implement the Python buffer API such as <code><span>buffer</span></code>,
+<code><span>array.array</span></code>, <code><span>mmap.mmap</span></code>, etc. may be used anywhere a <code><span>NSData</span></code> is
+expected.</li>
 </ul>
-<p>The special cases allow for more transparent bridging between Python and
+<p>These special cases allow for more transparent bridging between Python and
 Objective-C.</p>
-<h2><a>Accessing Objective-C objects from Python</a></h2>
+<h2><a name="accessing-objective-c-objects-from-python">Accessing Objective-C objects from Python</a></h2>
 <p>Objective-C objects are accessed through proxy objects that forward method
 calls from Python to Objective-C.  All proxy objects are instances of 
 <code><span>objc.objc_object</span></code>, or a subclass of this class.</p>
 <p>See the section 'Method protocol' for a description of how PyObjC translates 
 between Python and Objective-C method calls.</p>
-<h2><a>Accessing Objective-C classes from Python</a></h2>
+<h2><a name="accessing-objective-c-classes-from-python">Accessing Objective-C classes from Python</a></h2>
 <p>Objective-C classes are also accessed through proxy objects, but those are
 subclasses of <code><span>objc.objc_class</span></code>.  The proxies for Objective-C classes are 
 classes in Python.</p>
 <p>Instances are created by calling allocator class methods (like <code><span>+alloc</span></code> or
-factory methods).  Objective-C instances cannot be created by using the class
+factory methods).  Objective-C instances can not be created by using the class
 as a factory function.</p>
 <p>It is possible to create subclasses from Objective-C classes using the normal
 mechanism.  There are some limitations though:</p>
 <code><span>objc.formal_protocol</span></code>'s constructor.</p>
 <p>A subclass of an Objective-C (proxy) class is not only a Python class, but also
 an Objective-C class.  This means that it is possible to create instances of 
-these classes from Objective-C using normal Objective-C syntax, although you
-must locate the class using the function <code><span>objc_lookUpClass</span></code> (e.g. defining
-<code><span>@class</span> <span>MyPythonClass</span></code> will not work).  One of the results of this feature
-is that these classes can be used to implement classes that are defined in
-Interface Builder NIB files.</p>
-<p>Like Python classes, Objective-C classes can have instance variables.  If you
-define new instance variables in the Python subclass they will only be visible
-in Python, and not in Objective-C.  This means that normal Python instance
-variables cannot be used as 'outlets' in interface builder.  Those can be 
-defined using special properties: <code><span>objc.ivar</span></code> or <code><span>objc.IBOutlet</span></code>.</p>
+these classes from Objective-C using normal Objective-C syntax, although the
+class must be located using the function <code><span>NSClassFromString</span></code> or equivalent
+(e.g. <a href="mailto:defining``@class">defining``@class</a> MyPythonClass`` will not work).  One of the results of
+this feature is that these classes can be used to implement classes that are
+defined in Interface Builder NIB files.</p>
+<p>Like Python classes, Objective-C classes can have instance variables.  Normal
+Python instance variables in a Python subclass will only be visible from Python,
+and not Objective-C (except when using Key-Value Coding).  This means that
+normal Python instance variables can not be used as outlets in Interface Builder.
+Objective-C visible instance variables can be defined using special properties:
+<code><span>objc.ivar</span></code> and <code><span>objc.IBOutlet</span></code>.</p>
 <p>The Objective-C class:</p>
 <pre>
 @interface MyClass : NSObject
 // ...
 @end // MyClass
 </pre>
-<p>can be defined in Python like this:</p>
+<p>The Python equivalent:</p>
 <pre>
-class MyClass (NSObject):
+class MyClass(NSObject):
   my_outlet1 = objc.IBOutlet('my_outlet1')
   my_outlet2 = objc.IBOutlet('my_outlet2')
   my_ivar = objc.ivar('my_ivar')
 
 # ...
 </pre>
-<h2><a>Method protocol</a></h2>
+<h2><a name="method-protocol">Method protocol</a></h2>
 <p>There is a straightforward translation from Objective-C method names to
 Python method names: Concatenate all parts of the Objective-C method name
 (without any whitespace) and then replace all colons by underscores.</p>
 (void)myAction:(id)sender     &lt;-&gt;     def myAction_(self, sender)
 method:(int)x andY:y          &lt;-&gt;     def method_andY_(self, x, y)
 </pre>
-<p>As can be seen in the examples above, Objective-C allows you to specify
-the types of arguments and the return value, while this is not possible in
+<p>As can be seen in the examples above, Objective-C allows explicit specification
+of the types of arguments and the return value, while this is not possible in
 Python.  This is not a problem when calling existing Objective-C methods, 
 because PyObjC will automatically read the needed information from the 
 Objective-C runtime, but it can be a problem when defining new Objective-C
 methods in Python.</p>
 <p>PyObjC therefore provides a function to define the signature of a python method
 in subclasses of Objective-C classes.  This function, objc.selector, should be
-used whenever you define a method that does not extend or override an existing
+used whenever defining a method that does not extend or override an existing
 Objective-C method in the superclass.</p>
 <p>The following Objective-C class:</p>
 <pre>
 </pre>
 <p>can be defined in Python like this:</p>
 <pre>
-class MyClass (NSObject):
+class MyClass(NSObject):
 
         def methodWithX_andY_(self, x, y):
-                pass
+                return 0
 
-        methodWithX_and_Y_ = selector(methodWithX_andY_,
+        methodWithX_andY_ = objc.selector(methodWithX_andY_,
                 signature='i@:if')
 
         def myAction_(self, sender):
                 pass
 
-        myAction_ = selector(myAction_,
+        myAction_ = objc.selector(myAction_,
                 signature='v@:')
 </pre>
+<p>In Python 2.4, it is also possible to write this example as such:</p>
+<pre>
+class MyClass(NSObject):
+
+        @objc.signature('i@:if')
+        def methodWithX_andY_(self, x, y):
+                return 0
+
+        @objc.signature('v@:')
+        def myAction_(self, sender):
+                pass
+</pre>
 <p>The explicit selectors don't really help to increase readability, especially
-given the cryptic signature strings.  It is therefore advisable to use other
+given the cryptic type signature strings.  It is therefore advisable to use other
 methods to define the signature if possible, the most likely way to do this
 is by using existing <code><span>objc.informal_protocol</span></code> definitions (like 
 <code><span>AppKit.NSOutlineViewDataSource</span></code>).</p>
-<p>There is one instance where you don't have to define the signature: The default
-signature is for a method that returns and object and where all arguments are
-also objects.  Functions that do not use a &quot;return&quot; statement will have
-a default signature that returns void, to better support Key-Value Coding.</p>
+<p>Unless explicitly specified as above, or defined by a superclass or protocol,
+PyObjC creates a default signature with an object return value, and object
+arguments.  If no return statement is in the function, then the return value
+is <code><span>void</span></code>, such as the above <code><span>myAction_</span></code>.  Fortunately, these cases cover
+most usage of PyObjC, so it is not often necessary to explicitly define selectors
+as above.</p>
 </body>
 </html>
 ------------
 
 PyObjC is a proxy between Objective-C and Python and allows access to Python
-classes from Objective-C and vice versa.  PyObjC also allows you to subclass
-Objective-C classes from Python. 
+classes from Objective-C and vice versa.  PyObjC also allows Python to subclass
+Objective-C classes, and these subclasses will be natively visible to both runtimes.
 
 Accessing Python objects from Objective-C
 -----------------------------------------
   ``NSNumber`` instances.  Their identity is not preserved across the bridge.
 
 - Python ``str`` is proxied using ``OC_PythonString``, a subclass of
-  ``NSString``.  You may use a Python ``str`` anywhere a ``NSString`` is
-  expected, but you should use ``unicode`` whenever possible.
+  ``NSString``.  A Python ``str`` may be used anywhere a ``NSString`` is
+  expected, but ``unicode`` should be used whenever possible.
   ``OC_PythonString`` will use the default encoding of ``NSString``, which is
   normally MacRoman but could be something else.
 
 - Python ``unicode`` is proxied using ``OC_PythonUnicode``, a subclass of
-  ``NSString``.  You may use a Python ``unicode`` anywhere a ``NSString``
+  ``NSString``.  A Python ``unicode`` may be used anywhere a ``NSString``
   is expected.
 
 - Python ``dict`` is proxied using ``OC_PythonDictionary``, a subclass of
-  ``NSMutableDictionary``.  This allows you to use a Python ``dict``
-  everywhere where an ``NSDictionary`` is expected.
+  ``NSMutableDictionary``.  A Python ``dict`` may be used anywhere 
+  an ``NSDictionary`` is expected.
 
 - Python ``list`` and ``tuple`` are proxied using ``OC_PythonArray``, a
-  subclass of ``NSMutableArray``.  This allows you to use a Python ``list``
-  or ``tuple`` everywhere where an ``NSArray`` is expected.
+  subclass of ``NSMutableArray``.  Python ``list`` or ``tuple`` objects
+  may be used anywhere an ``NSArray`` is expected.
 
 - Python objects that implement the Python buffer API, except for ``str``
   and ``unicode``, are proxied using ``OC_PythonData``, a ``NSData`` subclass.
-  This allows you to use instances of classes such as ``buffer``,
-  ``array.array``, ``mmap.mmap``, etc. anywhere ``NSData`` is expected.
+  Objects that implement the Python buffer API such as ``buffer``,
+  ``array.array``, ``mmap.mmap``, etc. may be used anywhere a ``NSData`` is
+  expected.
 
-The special cases allow for more transparent bridging between Python and
+These special cases allow for more transparent bridging between Python and
 Objective-C.
 
 Accessing Objective-C objects from Python
 classes in Python. 
 
 Instances are created by calling allocator class methods (like ``+alloc`` or
-factory methods).  Objective-C instances cannot be created by using the class
+factory methods).  Objective-C instances can not be created by using the class
 as a factory function.
 
 It is possible to create subclasses from Objective-C classes using the normal
 
 A subclass of an Objective-C (proxy) class is not only a Python class, but also
 an Objective-C class.  This means that it is possible to create instances of 
-these classes from Objective-C using normal Objective-C syntax, although you
-must locate the class using the function ``objc_lookUpClass`` (e.g. defining
-``@class MyPythonClass`` will not work).  One of the results of this feature
-is that these classes can be used to implement classes that are defined in
-Interface Builder NIB files.
+these classes from Objective-C using normal Objective-C syntax, although the
+class must be located using the function ``NSClassFromString`` or equivalent
+(e.g. defining``@class MyPythonClass`` will not work).  One of the results of
+this feature is that these classes can be used to implement classes that are
+defined in Interface Builder NIB files.
 
-Like Python classes, Objective-C classes can have instance variables.  If you
-define new instance variables in the Python subclass they will only be visible
-in Python, and not in Objective-C.  This means that normal Python instance
-variables cannot be used as 'outlets' in interface builder.  Those can be 
-defined using special properties: ``objc.ivar`` or ``objc.IBOutlet``.
+Like Python classes, Objective-C classes can have instance variables.  Normal
+Python instance variables in a Python subclass will only be visible from Python,
+and not Objective-C (except when using Key-Value Coding).  This means that
+normal Python instance variables can not be used as outlets in Interface Builder.
+Objective-C visible instance variables can be defined using special properties:
+``objc.ivar`` and ``objc.IBOutlet``.
 
 The Objective-C class::
 
   // ...
   @end // MyClass
 
-can be defined in Python like this::
+The Python equivalent::
 
-  class MyClass (NSObject):
+  class MyClass(NSObject):
     my_outlet1 = objc.IBOutlet('my_outlet1')
     my_outlet2 = objc.IBOutlet('my_outlet2')
     my_ivar = objc.ivar('my_ivar')
   (void)myAction:(id)sender	<->	def myAction_(self, sender)
   method:(int)x andY:y		<->	def method_andY_(self, x, y)
 
-As can be seen in the examples above, Objective-C allows you to specify
-the types of arguments and the return value, while this is not possible in
+As can be seen in the examples above, Objective-C allows explicit specification
+of the types of arguments and the return value, while this is not possible in
 Python.  This is not a problem when calling existing Objective-C methods, 
 because PyObjC will automatically read the needed information from the 
 Objective-C runtime, but it can be a problem when defining new Objective-C
 
 PyObjC therefore provides a function to define the signature of a python method
 in subclasses of Objective-C classes.  This function, objc.selector, should be
-used whenever you define a method that does not extend or override an existing
+used whenever defining a method that does not extend or override an existing
 Objective-C method in the superclass. 
 
 The following Objective-C class::
 	-(int)methodWithX:(int)x andY:(float)y;
 	-(void)myAction:(id)sender;
 
-can be defined in Python like this:
+can be defined in Python like this::
 
-::
-
-	class MyClass (NSObject):
+	class MyClass(NSObject):
 
 		def methodWithX_andY_(self, x, y):
-			pass
+			return 0
 
-		methodWithX_and_Y_ = selector(methodWithX_andY_,
+		methodWithX_andY_ = objc.selector(methodWithX_andY_,
 			signature='i@:if')
 
 		def myAction_(self, sender):
 			pass
 
-		myAction_ = selector(myAction_,
+		myAction_ = objc.selector(myAction_,
 			signature='v@:')
 
+
+In Python 2.4, it is also possible to write this example as such::
+
+	class MyClass(NSObject):
+	
+		@objc.signature('i@:if')
+		def methodWithX_andY_(self, x, y):
+			return 0
+
+		@objc.signature('v@:')
+		def myAction_(self, sender):
+			pass
+
 The explicit selectors don't really help to increase readability, especially
-given the cryptic signature strings.  It is therefore advisable to use other
+given the cryptic type signature strings.  It is therefore advisable to use other
 methods to define the signature if possible, the most likely way to do this
 is by using existing ``objc.informal_protocol`` definitions (like 
 ``AppKit.NSOutlineViewDataSource``). 
 
-There is one instance where you don't have to define the signature: The default
-signature is for a method that returns and object and where all arguments are
-also objects.  Functions that do not use a "return" statement will have
-a default signature that returns void, to better support Key-Value Coding.
+Unless explicitly specified as above, or defined by a superclass or protocol,
+PyObjC creates a default signature with an object return value, and object
+arguments.  If no return statement is in the function, then the return value
+is ``void``, such as the above ``myAction_``.  Fortunately, these cases cover
+most usage of PyObjC, so it is not often necessary to explicitly define selectors
+as above.
 </head>
 <body>
 <h2>GNUstep support in PyObjC</h2>
+<p><strong>WARNING</strong>: GNUStep support is broken.  If you would like to help, let us know.</p>
 <p>PyObjC has limited support for GNUstep, the 'objc' and 'Foundation' packages
 build and pass some, but by far not all, unittests.  More work is needed to
 make the GNUstep port as stable as the Mac OS X &quot;port&quot;.</p>
 GNUstep support in PyObjC
 =========================
 
+**WARNING**: GNUStep support is broken.  If you would like to help, let us know.
+
 PyObjC has limited support for GNUstep, the 'objc' and 'Foundation' packages
 build and pass some, but by far not all, unittests.  More work is needed to
 make the GNUstep port as stable as the Mac OS X "port".
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <title>
 An introduction to PyObjC</title>
+<title>
+Contents</title>
 </head>
 <body>
 <h2>An introduction to PyObjC</h2>
 :contact: pyobjc-dev@lists.sourceforge.net
 :URL: http://pyobjc.sourceforge.net/
 :copyright: 2003-2005 The PyObjC Project -->
-<table border="1" width="80%" align="center"><tbody><tr><td><i><center>Contents</center></i><br />
+<h2>Contents</h2>
 <ul>
-<li><a href="#preface">Preface</a></li>
-<li><a href="#objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></li>
-<li><a href="#overview-of-the-bridge">Overview of the bridge</a><ul>
-<li><a href="#classes">Classes</a></li>
-<li><a href="#messages-and-functions">Messages and Functions</a></li>
-<li><a href="#reference-counting">Reference counting</a></li>
-<li><a href="#protocols">Protocols</a></li>
-<li><a href="#cocoa-bindings">Cocoa Bindings</a></li>
-<li><a href="#categories">Categories</a></li>
+<li><a href="#preface" id="id6" name="id6">Preface</a></li>
+<li><a href="#objective-c-for-pyobjc-users" id="id7" name="id7">Objective-C for PyObjC users</a></li>
+<li><a href="#overview-of-the-bridge" id="id8" name="id8">Overview of the bridge</a><ul>
+<li><a href="#classes" id="id9" name="id9">Classes</a></li>
+<li><a href="#messages-and-functions" id="id10" name="id10">Messages and Functions</a></li>
+<li><a href="#reference-counting" id="id11" name="id11">Reference counting</a></li>
+<li><a href="#protocols" id="id12" name="id12">Protocols</a></li>
+<li><a href="#cocoa-bindings" id="id13" name="id13">Cocoa Bindings</a></li>
+<li><a href="#categories" id="id14" name="id14">Categories</a></li>
 </ul>
 </li>
-<li><a href="#cocoa-for-python-programmers">Cocoa for Python programmers</a></li>
-<li><a href="#notes-on-specific-tasks">Notes on specific tasks</a><ul>
-<li><a href="#working-with-threads">Working with threads</a></li>
-<li><a href="#finalizers">Finalizers</a></li>
-<li><a href="#copying">Copying</a></li>
+<li><a href="#cocoa-for-python-programmers" id="id15" name="id15">Cocoa for Python programmers</a></li>
+<li><a href="#notes-on-specific-tasks" id="id16" name="id16">Notes on specific tasks</a><ul>
+<li><a href="#working-with-threads" id="id17" name="id17">Working with threads</a></li>
+<li><a href="#finalizers" id="id18" name="id18">Finalizers</a></li>
+<li><a href="#copying" id="id19" name="id19">Copying</a></li>
 </ul>
 </li>
-<li><a href="#building-applications">Building applications</a><ul>
-<li><a href="#py2app-setup-py">&quot;py2app&quot; :  setup.py</a></li>
-<li><a href="#ide-approach-xcode">&quot;IDE approach&quot; : Xcode</a></li>
+<li><a href="#building-applications" id="id20" name="id20">Building applications</a><ul>
+<li><a href="#py2app-setup-py" id="id21" name="id21">&quot;py2app&quot; :  setup.py</a></li>
+<li><a href="#ide-approach-xcode" id="id22" name="id22">&quot;IDE approach&quot; : Xcode</a></li>
 </ul>
 </li>
 </ul>
-</td></tr></tbody></table>
-<h2><a href="#id6">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, 
+<h2><a href="#id6" name="preface">Preface</a></h2>
+<p>PyObjC is a bridge between Python and Objective-C.  It allows Python 
+scripts to use and extend existing Objective-C class libraries;
 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>
-<h2><a href="#id7">Objective-C for PyObjC users</a></h2>
+<h2><a href="#id7" name="objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></h2>
 <p>It is recommended that you take the time to understand a little bit about
 Objective-C before jumping into PyObjC development.  The class libraries
 that you will be using from Cocoa are not documented in Python, and their
 <dd><p><code><span>someObject</span></code>, <code><span>someRange</span></code></p>
 </dd>
 </dl>
-<p>As you'll see later, the straightforward translation of such a message to
+<p>As documented later, the straightforward translation of such a message to
 Python is:</p>
 <pre>
 anArray.indexOfObject_inRange_(someObject, someRange)
 <ul>
 <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="#id8">Overview of the bridge</a></h2>
-<h3><a href="#id9">Classes</a></h3>
+<h2><a href="#id8" name="overview-of-the-bridge">Overview of the bridge</a></h2>
+<h3><a href="#id9" name="classes">Classes</a></h3>
 <p>Objective-C classes are visible as (new-style) Python classes and can be 
 subclassed just like normal Python classes.  All the usual introspection
 mechanisms work as well, as do <code><span>__slots__</span></code> and descriptors.  The major 
 differences between normal Python classes and Objective-C classes are the way 
 that instances are created and initialized, and the fact that Objective-C
 selectors look strange when translated to Python methods.</p>
-<p>You can use multiple inheritance when subclassing an Objective-C class, so
+<p>Multiple inheritance may be used when subclassing an Objective-C class, so
 long as the Objective-C class is the first base class and there is only one
 Objective-C base class.  The Objective-C runtime does not support multiple
 inheritance.  These mix-in classes should not contain different
 prefix made much more sense when it was called NeXTstep, but persists to this
 day for compatibility reasons.</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.  To initialize objects, you first call a
+objects is a two-stage process.  To initialize objects, first call a
 class method to allocate the memory (typically <code><span>alloc</span></code>), and then call an
 initializer (typically starts with <code><span>init</span></code>).  Some classes have class methods
 which perform this behind the scenes, especially classes that create cached,
 immutable, or singleton instances.</p>
-<h3><a href="#id10">Messages and Functions</a></h3>
+<h3><a href="#id10" name="messages-and-functions">Messages and Functions</a></h3>
 <p>Objective-C methods are bridged to Python methods.  Because Objective-C
 message dispatch syntax can not be translated directly to Python, a few
 simple translations must take place.  The rules for these translations are:</p>
 </ul>
 </blockquote>
 </li>
-<li>Use this translated selector as you would a normal Python method.
+<li>Use this translated selector as a normal Python method.
 The arguments must be passed in the same order, and the number of
 arguments passed will normally be equal to the number of underscores
 in the method name; exceptions to this rule and the behavior of &quot;result&quot;
 <pre>
 (void)getNumberOfRows:(int *)rowCount columns:(int *)columnCount
 </pre>
-<p>You use this method in python like this:</p>
+<p>This method is used from Python like this:</p>
 <pre>
 rowCount, columnCount = matrix.getNumberOfRows_columns_()
 </pre>
 <p>When a function or method has an array of values and the length of that array
-as arguments, you can pass <code><span>None</span></code> as the length.  The length of the sequence
-that is used for the array of values is passed to Objective-C as the length
-argument.</p>
+as arguments, <code><span>None</span></code> may be passed as the length to specify that the length
+of the given sequence should be used.</p>
 <p>Python's <code><span>array.array</span></code> type may be used to represent a C array if the
 typestr and size match what is expected by the selector.  Numeric, numarray,
-and other third party array types are not supported in PyObjC 1.3.</p>
-<p>When you define methods in a subclass of an Objective-C class, the bridge has
-to tell the Objective-C runtime what the signature of those methods is.  The
-basic rule is that all arguments as well as the return value are objects (just
-like with normal Python methods).  The bridge will automatically pick a better 
-signature when it has more information available.  Specifically, if you 
-override an existing method the bridge will assume you want to use the same
-method signature.  Furthermore, if you implement a method in an (informal)
+and other third party array types are not supported in PyObjC 1.3.5.</p>
+<p>When defining methods in an Objective-C subclass, the bridge must provide
+type signatures for each method to the Objective-C runtime.  The default
+type signature is for all arguments as well as the return value to be objects (just
+like with normal Python methods).  If there is no return statement in the implementation,
+then the return value will be void.  The bridge will automatically pick a better 
+signature when it has more information available.  Specifically, a method overrides 
+an existing method, the bridge will assume you want to use the same
+method signature.  Furthermore, if the method is implemented in an (informal)
 protocol known to the bridge it will use the signature from the corresponding
 method in that signature.</p>
-<p>The end result is that you rarely have to add information about the
-signature of methods.  For the two most common cases where this is necessary,
+<p>The end result is that it is rarely necessary to explicitly add information about
+the signature of methods.  For the two most common cases where this is necessary,
 we have provided convenience decorators (used like <code><span>staticmethod</span></code> or
 <code><span>classmethod</span></code>):</p>
 <dl>
 <code><span>objc</span></code> module for the arguments you can use with this function.  It is
 normally used like this:</p>
 <pre>
-class MyObject (NSObject):
+class MyObject(NSObject):
+
+        # -(void)someMethod:(float)arg
         def someMethod_(self, arg):
                 pass
 
-        someMethod_ = objc.selector(someMethod_, ...)
+        someMethod_ = objc.selector(someMethod_, signature='v@:f')
 </pre>
-<h3><a href="#id11">Reference counting</a></h3>
+<p>From Python 2.4, there is a decorator for this purpose:</p>
+<pre>
+class MyObject(NSObject):
+
+        @objc.signature('v@:f')
+        def someMethod_(self, arg):
+                pass
+</pre>
+<h3><a href="#id11" name="reference-counting">Reference counting</a></h3>
 <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 
 subclasses of <code><span>NSObject</span></code> to represent the nodes in the outline view.</p>
 <p>Another gotcha is that <code><span>obj.setDelegate_()</span></code> often does <i>not</i> retain the
 delegate, so a reference should be maintained elsewhere.</p>
-<h3><a href="#id12">Protocols</a></h3>
+<h3><a href="#id12" name="protocols">Protocols</a></h3>
 <p>Cocoa defines a number of formal and informal protocols that specify methods
 that should be implemented by a class if it is to be used in a specific role,
 such as the data source for an <code><span>NSTableView</span></code>.</p>
 objects to add the right method signatures to methods, and to warn about
 classes that partially implement a protocol.</p>
 <p>See <a href="protocols.html">PyObjC protocol support</a> for more information.</p>
-<h3><a href="#id13">Cocoa Bindings</a></h3>
+<h3><a href="#id13" name="cocoa-bindings">Cocoa Bindings</a></h3>
 <p>In Mac OS X 10.3 Apple introduced <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaBindings/">Cocoa Bindings</a>, a method to make it easier
 to create and use <i>Controller</i> objects using <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueObserving/">Key-Value Observing</a> and
 <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/">Key-Value Coding</a>.  In order to create accessors compatible with this, you
 must use <code><span>objc.accessor</span></code> to create an appropriate selector descriptor.</p>
-<h3><a href="#id14">Categories</a></h3>
+<h3><a href="#id14" name="categories">Categories</a></h3>
 <p>Objective-C has a mechanism for modularize a class definition, it is possible
 to add methods to an existing class in a separate compilation unit and even
 a separate library.  This mechanism is named categories and is used to enhance
 <p>This is not very clear, PyObjC therefore also provides the following 
 mechanism, implemented on top of <code><span>objc.classAddMethods</span></code>:</p>
 <pre>
-class NSObject (objc.Category(NSObject)):
+class NSObject(objc.Category(NSObject)):
         def objectFootprint(self):
                 pass
 </pre>
 <p>To make it clear that <code><span>objc.Category</span></code> performs a special task the name in
 the class definition must be the same as the <code><span>__name__</span></code> of the argument
 to <code><span>objc.Category</span></code>.</p>
-<h2><a href="#id15">Cocoa for Python programmers</a></h2>
+<h2><a href="#id15" name="cocoa-for-python-programmers">Cocoa for Python programmers</a></h2>
 <p>Cocoa frameworks are mapped onto Python packages with the same name; that is
 the classes, constants and functions from the AppKit framework are available
 after you import <code><span>AppKit</span></code> in your Python script.</p>
 <li><a href="http://www.stepwise.com/">stepwise.com</a></li>
 <li>Your local bookstore or library</li>
 </ul>
-<h2><a href="#id16">Notes on specific tasks</a></h2>
-<h3><a href="#id17">Working with threads</a></h3>
-<p>When you create a thread and want to use PyObjC from that thread you will
-have to create an <code><span>NSAutoreleasePool</span></code> in that thread and clean it up when
-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>
-<h3><a href="#id18">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 Python subclasses of Objective-C classes you can use either convention.  You
-should pick one convention for your own code, the order in which <code><span>__del__</span></code>
-and <code><span>dealloc</span></code> methods are called is undefined.</p>
-<h3><a href="#id19">Copying</a></h3>
-<p>It is possible to implement the <code><span>NSCopying</span></code> protocol in your classes.  Some
-care must be taken when you inherit from a class that already implements 
-that protocol.</p>
-<p>Some classes copy the template object manually, you'll have to copy your 
-own fields manually in that case.  Other classes use a convenience function
-that creates the copy.  In that case you wont have to copy your own fields.
-However, the fields in the copy will rever to the same objects as the 
-fields in the original (that is, the copy will share some state with the
-original).  This is no problem when the fields rever to immutable values (such
-as integers), but is probably not what you want when the fields rever to
-mutable values (such as lists).</p>
+<h2><a href="#id16" name="notes-on-specific-tasks">Notes on specific tasks</a></h2>
+<h3><a href="#id17" name="working-with-threads">Working with threads</a></h3>
+<p>Most of Cocoa, and thus PyObjC, requires an <code><span>NSAutoreleasePool</span></code> in order to function
+properly.  PyObjC does this automatically on the first thread it is imported from,
+but other threads will require explicit <code><span>NSAutoreleasePool</span></code> management.  The following
+practice for working with <code><span>NSAutoreleasePool</span></code> is recommended:</p>
+<pre>
+pool = NSAutoreleasePool.alloc().init()
+...
+del pool
+</pre>
+<p>Typically this will be done at the beginning and end of the thread.  It is important
+to use <code><span>del</span></code> before rebinding the <code><span>pool</span></code> local to another <code><span>NSAutoreleasePool</span></code>
+instance, otherwise it will not have the intended effect.</p>
+<p>For long running threads and tight loops, it can also be useful to use this pattern
+in the body of the loop in order to optimize memory usage.  For example, <code><span>NSRunLoop</span></code>
+will be create a new <code><span>NSAutoreleasePool</span></code> at the beginning of each run loop iteration
+and release it at the end.</p>
+<h3><a href="#id18" name="finalizers">Finalizers</a></h3>
+<p>In normal Python, there are two methods for writing finalizers: implementing
+<code><span>__del__</span></code>, and using <code><span>weakref.ref</span></code> callbacks.  Generally, <code><span>__del___</span></code> is
+discouraged as it does not allow the object to participate in cyclic garbage
+collection and create uncollectible garbage if not implemented properly.
+<code><span>weakref.ref</span></code> callbacks avoid this restriction as they do not provide a real
+reference to the object.</p>
+<p>In Objective-C, there is no cyclic garbage collection, so all Objective-C
+objects (including subclasses from Python) are already subject to these
+restrictions.  When subclassing an Objective-C class, you may implement
+<code><span>dealloc</span></code> or <code><span>__del__</span></code>.  If you implement <code><span>dealloc</span></code>, ensure that
+you call the super <code><span>dealloc</span></code> at the end.  If you implement both 
+<code><span>__del__</span></code> and <code><span>dealloc</span></code>, the order in which they are called is
+undefined.</p>
+<p>It is not currently possible to create a <code><span>weakref.ref</span></code> for any Objective-C
+object.  It is probably technically possible to do, but tricky, so it
+may eventually be implemented in a future version of PyObjC (especially
+if a future Objective-C runtime supports it).</p>
+<h3><a href="#id19" name="copying">Copying</a></h3>
+<p>It is possible for a Python subclass of an Objective-C class to implement
+the <code><span>NSCopying</span></code> protocol.  Some care must be taken when the superclass
+already implements the protocol.</p>
+<p>Some <code><span>NSCopying</span></code> compliant Objective-C classes copy the template object
+manually.  In those cases the Python subclass must also copy the additional
+ivars manually.</p>
+<p>Other <code><span>NSCopying</span></code> compliant Objective-C classes use a convenience function
+that creates a shallow copy of the object and all of its ivars.  In those
+cases the Python subclass will not have to explicitly copy all of the ivars.
+However, the ivars in the copy will refer to the same objects as the original,
+and will thus share some state.  As with shallow copies in Python, if any of
+the ivars refer to mutable objects (<code><span>list</span></code>, <code><span>dict</span></code>, etc.) it may be
+desirable to explicitly make shallow or deep copies of the mutable ivars.</p>
 <p>NOTE: PyObjC might introduce a helper class when you inherit from a class
-that implements <code><span>NSCopying</span></code>.  You should not rely on the existance of this
-class.</p>
-<p>NOTE2: You shouldn't assign to <code><span>SomeClass.copyWithZone_</span></code> unless that class
-already implements <code><span>copyWithZone:</span></code>.  If you do you may end up with seemingly
-random memory coruption.</p>
-<h2><a href="#id20">Building applications</a></h2>
+that implements <code><span>NSCopying</span></code> as an internal implementation detail.
+External code should not rely on the existance of this class.</p>
+<p>NOTE2: <code><span>SomeClass.copyWithZone_</span></code> should not be implemented unless a
+superclass already implements <code><span>copyWithZone:</span></code>, or else the behavior
+will be undefined (memory corruption, crashes, etc.).</p>
+<h2><a href="#id20" name="building-applications">Building applications</a></h2>
 <p>There are two different recommended ways to build applications with PyObjC.</p>
-<h3><a href="#id21">&quot;py2app&quot; :  setup.py</a></h3>
+<h3><a href="#id21" 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>
 <pre>
 python setup.py py2app --help
 </pre>
-<h3><a href="#id22">&quot;IDE approach&quot; : Xcode</a></h3>
+<h3><a href="#id22" name="ide-approach-xcode">&quot;IDE approach&quot; : Xcode</a></h3>
 <p>PyObjC includes a number of Xcode templates that can be used to 
 develop applications, using the same underlying functionality that
 is in py2app.  These templates are used like any other Xcode template,
 Preface
 -------
 
-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, 
+PyObjC is a bridge between Python and Objective-C.  It allows Python 
+scripts to use and extend existing Objective-C class libraries;
 most importantly the `Cocoa libraries`_ by `Apple`_.
 
 This document describes how to use Objective-C class libraries from Python
 Arguments:
     ``someObject``, ``someRange``
 
-As you'll see later, the straightforward translation of such a message to
+As documented later, the straightforward translation of such a message to
 Python is::
 
     anArray.indexOfObject_inRange_(someObject, someRange)
 that instances are created and initialized, and the fact that Objective-C
 selectors look strange when translated to Python methods.
 
-You can use multiple inheritance when subclassing an Objective-C class, so
+Multiple inheritance may be used when subclassing an Objective-C class, so
 long as the Objective-C class is the first base class and there is only one
 Objective-C base class.  The Objective-C runtime does not support multiple
 inheritance.  These mix-in classes should not contain different
 day for compatibility reasons.
 
 As described in `Objective-C for PyObjC users`_ the creation of Objective-C 
-objects is a two-stage process.  To initialize objects, you first call a
+objects is a two-stage process.  To initialize objects, first call a
 class method to allocate the memory (typically ``alloc``), and then call an
 initializer (typically starts with ``init``).  Some classes have class methods
 which perform this behind the scenes, especially classes that create cached,
     - ``class`` translates to ``class__``
     - ``raise`` translates to ``raise__``
 
-3. Use this translated selector as you would a normal Python method.
+3. Use this translated selector as a normal Python method.
    The arguments must be passed in the same order, and the number of
    arguments passed will normally be equal to the number of underscores
    in the method name; exceptions to this rule and the behavior of "result"
 
    (void)getNumberOfRows:(int *)rowCount columns:(int *)columnCount
 
-You use this method in python like this::
+This method is used from Python like this::
 
    rowCount, columnCount = matrix.getNumberOfRows_columns_()
 
 When a function or method has an array of values and the length of that array
-as arguments, you can pass ``None`` as the length.  The length of the sequence
-that is used for the array of values is passed to Objective-C as the length
-argument. 
+as arguments, ``None`` may be passed as the length to specify that the length
+of the given sequence should be used.
 
 Python's ``array.array`` type may be used to represent a C array if the
 typestr and size match what is expected by the selector.  Numeric, numarray,
-and other third party array types are not supported in PyObjC 1.3.
+and other third party array types are not supported in PyObjC 1.3.5.
 
-When you define methods in a subclass of an Objective-C class, the bridge has
-to tell the Objective-C runtime what the signature of those methods is.  The
-basic rule is that all arguments as well as the return value are objects (just
-like with normal Python methods).  The bridge will automatically pick a better 
-signature when it has more information available.  Specifically, if you 
-override an existing method the bridge will assume you want to use the same
-method signature.  Furthermore, if you implement a method in an (informal)
+When defining methods in an Objective-C subclass, the bridge must provide
+type signatures for each method to the Objective-C runtime.  The default
+type signature is for all arguments as well as the return value to be objects (just
+like with normal Python methods).  If there is no return statement in the implementation,
+then the return value will be void.  The bridge will automatically pick a better 
+signature when it has more information available.  Specifically, a method overrides 
+an existing method, the bridge will assume you want to use the same
+method signature.  Furthermore, if the method is implemented in an (informal)
 protocol known to the bridge it will use the signature from the corresponding
 method in that signature.
 
-The end result is that you rarely have to add information about the
-signature of methods.  For the two most common cases where this is necessary,
+The end result is that it is rarely necessary to explicitly add information about
+the signature of methods.  For the two most common cases where this is necessary,
 we have provided convenience decorators (used like ``staticmethod`` or
 ``classmethod``):
 
 ``objc`` module for the arguments you can use with this function.  It is
 normally used like this::
 
-	class MyObject (NSObject):
+	class MyObject(NSObject):
+
+		# -(void)someMethod:(float)arg
 		def someMethod_(self, arg):
 			pass
 
-		someMethod_ = objc.selector(someMethod_, ...)
+		someMethod_ = objc.selector(someMethod_, signature='v@:f')
+
+From Python 2.4, there is a decorator for this purpose::
+
+	class MyObject(NSObject):
+
+		@objc.signature('v@:f')
+		def someMethod_(self, arg):
+			pass
+
 
 Reference counting
 ..................
 This is not very clear, PyObjC therefore also provides the following 
 mechanism, implemented on top of ``objc.classAddMethods``::
 
-	class NSObject (objc.Category(NSObject)):
+	class NSObject(objc.Category(NSObject)):
 		def objectFootprint(self):
 			pass
 
 Working with threads
 ....................
 
-When you create a thread and want to use PyObjC from that thread you will
-have to create an ``NSAutoreleasePool`` in that thread and clean it up when
-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.
+Most of Cocoa, and thus PyObjC, requires an ``NSAutoreleasePool`` in order to function
+properly.  PyObjC does this automatically on the first thread it is imported from,
+but other threads will require explicit ``NSAutoreleasePool`` management.  The following
+practice for working with ``NSAutoreleasePool`` is recommended::
+
+	pool = NSAutoreleasePool.alloc().init()
+	...
+	del pool
+
+Typically this will be done at the beginning and end of the thread.  It is important
+to use ``del`` before rebinding the ``pool`` local to another ``NSAutoreleasePool``
+instance, otherwise it will not have the intended effect.
+
+For long running threads and tight loops, it can also be useful to use this pattern
+in the body of the loop in order to optimize memory usage.  For example, ``NSRunLoop``
+will be create a new ``NSAutoreleasePool`` at the beginning of each run loop iteration
+and release it at the end.
 
 Finalizers
 ..........
 
-In Python you can use the method ``__del__`` to clean up resources when your
-object is garbage collected.  In Objective-C/Cocoa this is done with a method 
-named ``dealloc``. 
+In normal Python, there are two methods for writing finalizers: implementing
+``__del__``, and using ``weakref.ref`` callbacks.  Generally, ``__del___`` is
+discouraged as it does not allow the object to participate in cyclic garbage
+collection and create uncollectible garbage if not implemented properly.
+``weakref.ref`` callbacks avoid this restriction as they do not provide a real
+reference to the object.
 
-In Python subclasses of Objective-C classes you can use either convention.  You
-should pick one convention for your own code, the order in which ``__del__``
-and ``dealloc`` methods are called is undefined.
+In Objective-C, there is no cyclic garbage collection, so all Objective-C
+objects (including subclasses from Python) are already su