Commits

Bob Ippolito committed 9dea61b

More documentation updates

Comments (0)

Files changed (20)

pyobjc/Doc/PyObjCTools.html

 <ul>
 <li><code><span>PyObjCTools.KeyValueCoding</span></code></li>
 </ul>
-<p>A python API for working with <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/index.html#//apple_ref/doc/uid/10000107i">Key-Value Coding</a>.</p>
+<p>A Python API for working with <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/">Key-Value Coding</a>.</p>
 <ul>
 <li><code><span>PyObjCTools.NibClassBuilder</span></code></li>
 </ul>
 <li><code><span>endSheetMethod(method)</span> <span>-&gt;</span> <span>selector</span></code><p>Convert a method to a form that is suitable to use as the delegate callback
 for sheet methods.</p>
 </li>
-<li><code><span>runEventLoop(argv=None,</span> <span>unexpectedErrorAlert=unexpectedErrorAlert)</span> <span>-&gt;</span> <span>None</span></code><p>Run the evenloop using <code><span>NSApplicationMain</span></code> and ask the user if we should
+<li><code><span>runEventLoop(argv=None,</span> <span>unexpectedErrorAlert=unexpectedErrorAlert)</span> <span>-&gt;</span> <span>None</span></code><p>Run the event loop using <code><span>NSApplicationMain</span></code> and ask the user if we should
 continue if an exception is caught.</p>
 <p>This function doesn't return unless it throws an exception.</p>
 </li>
 </li>
 </ul>
 <h2><a name="pyobjctools-keyvaluecoding"><code><span>PyObjCTools.KeyValueCoding</span></code></a></h2>
-<p>A module for working with Key-Value Coding in python. Key-Value coding is
-explained <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/index.html#//apple_ref/doc/uid/10000107i">on the apple website</a></p>
-<p>This module provides a python interface to some of that functionality. The
-interface is modelled on the <code><span>getattr</span></code> and <code><span>setattr</span></code> functions.</p>
+<p>A module for working with Key-Value Coding in Python. Key-Value Coding is
+explained <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/">on the Apple website</a></p>
+<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>
 <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 attribue <code><span>_key</span></code>, or the vale of <code><span>object._key()</span></code> if
+<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>
 </ul>
 </li>
 <p>Raises <code><span>KeyError</span></code> if the key cannot be changed.</p>
 </li>
 <li><code><span>setKeyPath(object,</span> <span>keypath,</span> <span>value)</span> <span>-&gt;</span> <span>None</span></code><p>The same as <code><span>setKey</span></code>, but now using a key path. A key path is a sequence
-of keys seperated by dots. The <code><span>getKey</span></code> function is used to traverse 
+of keys separated by dots. The <code><span>getKey</span></code> function is used to traverse 
 the path up to the last item, and then <code><span>setKey</span></code> is used to change the value.</p>
 </li>
 </ul>
 <h3><a name="using-the-class-definitions">Using the class definitions</a></h3>
 <p>The module contains a &quot;magic&quot; base (super) class called <code><span>AutoBaseClass</span></code>.
 Subclassing <code><span>AutoBaseClass</span></code> will invoke some magic that will look up the
-proper base class in the class definitions extraced from the nib(s).
+proper base class in the class definitions extracted from the nib(s).
 If you use multiple inheritance to use Cocoa's &quot;informal protocols&quot;,
 you <i>must</i> list <code><span>AutoBaseClass</span></code> as the first base class. For example:</p>
 <pre>
 random crashes of a PyObjC program. These crashes are often caused by 
 Objective-C style weak references or incorrectly implemented protocols.</p>
 <ul>
-<li><code><span>dumpStackOnFatalSignal()</span></code><p>This function will install signal handlers that print a stacktrace and
-then reraise the signal.</p>
+<li><code><span>dumpStackOnFatalSignal()</span></code><p>This function will install signal handlers that print a stack trace and
+then re-raise the signal.</p>
 </li>
 <li><code><span>resetFatalSignals()</span></code><p>Restores the signal handlers to the state they had before the call to
 dumpStackOnFatalSignal.</p>

pyobjc/Doc/PyObjCTools.txt

 
 * ``PyObjCTools.KeyValueCoding``
 
-A python API for working with `Key-Value Coding`__. 
+A Python API for working with `Key-Value Coding`__. 
 
-.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/index.html#//apple_ref/doc/uid/10000107i
+.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/
 
 * ``PyObjCTools.NibClassBuilder``
 
 
 * ``runEventLoop(argv=None, unexpectedErrorAlert=unexpectedErrorAlert) -> None``
 
-  Run the evenloop using ``NSApplicationMain`` and ask the user if we should
+  Run the event loop using ``NSApplicationMain`` and ask the user if we should
   continue if an exception is caught.
 
   This function doesn't return unless it throws an exception.
 ``PyObjCTools.KeyValueCoding``
 ..............................
 
-A module for working with Key-Value Coding in python. Key-Value coding is
-explained `on the apple website`__
+A module for working with Key-Value Coding in Python. Key-Value Coding is
+explained `on the Apple website`__
 
-.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/index.html#//apple_ref/doc/uid/10000107i
+.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/
 
-This module provides a python interface to some of that functionality. The
-interface is modelled on the ``getattr`` and ``setattr`` functions.
+This module provides a Python interface to some of that functionality. The
+interface is modeled on the ``getattr`` and ``setattr`` functions.
 
 * ``getKey(object, key) -> value``
 
   - the value of the attribute ``key``, or the value of ``object.key()`` if
     ``object.key`` is a method.
 
-  - the value of the attribue ``_key``, or the vale of ``object._key()`` if
+  - the value of the attribute ``_key``, or the vale of ``object._key()`` if
     ``object._key`` is a method.
 
 * ``getKeyPath(object, keypath) -> value``
 * ``setKeyPath(object, keypath, value) -> None``
 
   The same as ``setKey``, but now using a key path. A key path is a sequence
-  of keys seperated by dots. The ``getKey`` function is used to traverse 
+  of keys separated by dots. The ``getKey`` function is used to traverse 
   the path up to the last item, and then ``setKey`` is used to change the value.
 
 PyObjCTools.NibClassBuilder
 
 The module contains a "magic" base (super) class called ``AutoBaseClass``.
 Subclassing ``AutoBaseClass`` will invoke some magic that will look up the
-proper base class in the class definitions extraced from the nib(s).
+proper base class in the class definitions extracted from the nib(s).
 If you use multiple inheritance to use Cocoa's "informal protocols",
 you *must* list ``AutoBaseClass`` as the first base class. For example::
 
 
 - ``dumpStackOnFatalSignal()``
 
-  This function will install signal handlers that print a stacktrace and
-  then reraise the signal.
+  This function will install signal handlers that print a stack trace and
+  then re-raise the signal.
 
 - ``resetFatalSignals()``
 

pyobjc/Doc/TODO.html

 <p>This document contains an (incomplete) list of work items.</p>
 <h2><a href="#id2" name="important-items">Important items</a></h2>
 <h3><a href="#id3" name="better-documentation">Better documentation</a></h3>
-<p>There should be more developer documentation and end-user documentation is
-virtually non-existant. Related to this is the website: This should be filled.</p>
-<p>We should also add scripts to convert documentation to a format that is 
-useable on the website.</p>
-<p>Also needed: document listing the differences between Objective-C Cocoa and
-Python Cocoa: which functions/methods are not available, list differences
-in arguments (e.g. NSBeginAlertSheet has a variable number of arguments in
-Objective-C, the format-arguments are not present in Python).</p>
+<p>There should be more developer and and end-user documentation.</p>
 <h3><a href="#id4" name="test-suite">Test suite</a></h3>
 <p>The test suite needs to be enhanced.</p>
 <ul>
 <p>From the top of my head:</p>
 <ul>
 <li>Restructure selector.m, this file is too long and complicated. We could
-do away with the difference between method implemented in Python and ObjC.</li>
+do away with the difference between method implemented in Python and
+Objective-C.</li>
 <li>Likewise for class-builder.m, this file is way to large.</li>
 <li>We've several types that wrap pointer values, such as <code><span>SessionWrapper</span></code> in
 <code><span>Modules/AppKit</span></code>. Should add a function for creating these types, 
 <p>This is post-1.2 work, in general this is a hard problem because it may 
 involve object cycles that cross the Python-ObjC boundary.</p>
 <h3><a href="#id12" name="nscoder-support">NSCoder support</a></h3>
-<p>It might be usefull to add default implementations of <code><span>encodeWithCoder:</span></code> and
+<p>It might be useful to add default implementations of <code><span>encodeWithCoder:</span></code> and
 <code><span>initWithCoder:</span></code> methods to Python subclasses of Objective-C classes that 
 implement these.  Note that property list types should already be serializable
-(int, long, unicode, list, tuple, dict).</p>
+(<code><span>int</span></code>, <code><span>long</span></code>, <code><span>unicode</span></code>, <code><span>list</span></code>, <code><span>tuple</span></code>, <code><span>dict</span></code>).</p>
 <p>See also <cite>Pickle support</cite>.</p>
 <h3><a href="#id13" name="copy"><code><span>-copy</span></code></a></h3>
 <p>There are issues with implementing <code><span>-copy</span></code> in python, these need to be fixed.</p>
 unless <code><span>__slots__</span> <span>==</span> <span>()</span></code></p>
 <h3><a href="#id14" name="known-issues">Known issues</a></h3>
 <p>It is impossible to support methods with a variable number of arguments in the
-generic code (you have to reimplement allmost all of the logic of these 
+generic code (you have to re-implement almost all of the logic of these 
 methods in order to know how many and which types of arguments are expected).
 Luckily there are not many varargs methods and most (if no all) of them can
 be easily avoided.</p>
 <li>Check/cleanup error handling</li>
 <li>Finish in-code documentation for the C code</li>
 <li>SessionWrapper (in <code><span>Modules/AppKit</span></code>) is one of several types that wrap 
-a single pointer, create a function to build such types (simular to
+a single pointer, create a function to build such types (similar to
 <code><span>Modules/objc/struct-wrapper.m</span></code>)</li>
 <li>Use the <code><span>CArray</span></code> API whenever appropriate.</li>
 </ul>
 <h3><a href="#id16" name="cleanup-examples">Cleanup Examples</a></h3>
-<p>The CurrencyConvertor example should be removed, this should be the same as the
+<p>The CurrencyConverter example should be removed, this should be the same as the
 final step of the tutorial. It isn't at the moment because additional cruft in
 the example.</p>
 <ul>
 <p>Links to Apple documentation are not stable, can we add a layer of indirection
 here, e.g. link to the PyObjC website that will redirect to the right
 location?</p>
-<p>But: we should also provide links to locally installed documetation, especially
-in the documentation that will be installed on the users machine.</p>
+<p>We should also provide links to locally installed documentation,
+especially in the documentation that will be installed on the users machine.</p>
 <h3><a href="#id21" name="implement-more-of-nsmutabledictionary-in-oc-pythondictionary">Implement more of NSMutableDictionary in OC_PythonDictionary</a></h3>
 <p>The implementation of OC_PythonDictionary is very minimal, we should add
 additional methods in the NSMutableDictionary interface if those can be 
 <h3><a href="#id27" name="unique-proxies-for-python-objects">Unique proxies for Python objects</a></h3>
 <p>Some Cocoa/CoreFoundation API's basically require that <code><span>a[0]</span> <span>is</span> <span>a[0]</span></code>. The
 container wrappers contain support for that, but we should try to move that
-into the generic core: there should be at most one ObjC proxy object alive
-for every Python object (just like there's at most one Python proxy for every
-ObjC object).</p>
+into the generic core: there should be at most one Objective-C proxy object
+alive for every Python object (just like there's at most one Python proxy for
+every Objective-C object).</p>
 <h3><a href="#id28" name="nsdecimal-vs-decimal">NSDecimal vs decimal</a></h3>
 <p>Check if it is possible to wrap <code><span>NSDecimal</span></code> using <code><span>decimal</span></code> (and v.v.).</p>
 <p>Only implement this when it is possible to convert without loss of information.</p>
 <p>Python 2.4 introduces a decorator syntax. Add convenience functions that
 make it easier to use decorators with PyObjC.</p>
 <p>Also add example programs using decorators. Actually, first add the example(s)
-and extract usefull convenience functions from those.</p>
+and extract useful convenience functions from those.</p>
 <p>An example of a convenience function would be:</p>
 <pre>
 import objc

pyobjc/Doc/TODO.txt

 Better documentation
 ....................
 
-There should be more developer documentation and end-user documentation is
-virtually non-existant. Related to this is the website: This should be filled.
-
-We should also add scripts to convert documentation to a format that is 
-useable on the website.
-
-Also needed: document listing the differences between Objective-C Cocoa and
-Python Cocoa: which functions/methods are not available, list differences
-in arguments (e.g. NSBeginAlertSheet has a variable number of arguments in
-Objective-C, the format-arguments are not present in Python).
+There should be more developer and and end-user documentation.
 
 Test suite
 ..........
 From the top of my head:
 
 * Restructure selector.m, this file is too long and complicated. We could
-  do away with the difference between method implemented in Python and ObjC.
+  do away with the difference between method implemented in Python and
+  Objective-C.
 
 * Likewise for class-builder.m, this file is way to large.
 
 NSCoder support
 ...............
 
-It might be usefull to add default implementations of ``encodeWithCoder:`` and
+It might be useful to add default implementations of ``encodeWithCoder:`` and
 ``initWithCoder:`` methods to Python subclasses of Objective-C classes that 
 implement these.  Note that property list types should already be serializable
-(int, long, unicode, list, tuple, dict).
+(``int``, ``long``, ``unicode``, ``list``, ``tuple``, ``dict``).
 
 See also `Pickle support`.
 
 ............
 
 It is impossible to support methods with a variable number of arguments in the
-generic code (you have to reimplement allmost all of the logic of these 
+generic code (you have to re-implement almost all of the logic of these 
 methods in order to know how many and which types of arguments are expected).
 Luckily there are not many varargs methods and most (if no all) of them can
 be easily avoided.
 * Finish in-code documentation for the C code
 
 * SessionWrapper (in ``Modules/AppKit``) is one of several types that wrap 
-  a single pointer, create a function to build such types (simular to
+  a single pointer, create a function to build such types (similar to
   ``Modules/objc/struct-wrapper.m``)
 
 * Use the ``CArray`` API whenever appropriate.
 Cleanup Examples
 ................
 
-The CurrencyConvertor example should be removed, this should be the same as the
+The CurrencyConverter example should be removed, this should be the same as the
 final step of the tutorial. It isn't at the moment because additional cruft in
 the example.
 
 here, e.g. link to the PyObjC website that will redirect to the right
 location?
 
-But: we should also provide links to locally installed documetation, especially
-in the documentation that will be installed on the users machine.
+We should also provide links to locally installed documentation,
+especially in the documentation that will be installed on the users machine.
 
 Implement more of NSMutableDictionary in OC_PythonDictionary
 .............................................................
 
 Some Cocoa/CoreFoundation API's basically require that ``a[0] is a[0]``. The
 container wrappers contain support for that, but we should try to move that
-into the generic core: there should be at most one ObjC proxy object alive
-for every Python object (just like there's at most one Python proxy for every
-ObjC object).
+into the generic core: there should be at most one Objective-C proxy object
+alive for every Python object (just like there's at most one Python proxy for
+every Objective-C object).
 
 NSDecimal vs decimal
 ....................
 make it easier to use decorators with PyObjC. 
 
 Also add example programs using decorators. Actually, first add the example(s)
-and extract usefull convenience functions from those.
+and extract useful convenience functions from those.
 
 An example of a convenience function would be::
 

pyobjc/Doc/api-notes-macosx.html

 </ul>
 <h3><a href="#id43" name="id1">Class <code><span>NSView</span></code></a></h3>
 <ul>
-<li><code><span>objectAtPoint:rect:</span></code><p>Defined in a catagory on <code><span>NSView</span></code>.</p>
+<li><code><span>objectAtPoint:rect:</span></code><p>Defined in a category on <code><span>NSView</span></code>.</p>
 </li>
 </ul>
 <h3><a href="#id44" name="class-nsibobjectdata">Class <code><span>NSIBObjectData</span></code></a></h3>

pyobjc/Doc/api-notes-macosx.txt

 
 * ``objectAtPoint:rect:``
 
-  Defined in a catagory on ``NSView``.
+  Defined in a category on ``NSView``.
 
 Class ``NSIBObjectData``
 ........................

pyobjc/Doc/classes.html

 </head>
 <body>
 <h2>Python classes and Objective-C code</h2>
-<!-- This file is formatted using the rules for StructuredText -->
+<!-- This file is formatted using the rules for reStructuredText -->
 <!-- Version 0.1 -->
 <h2><a name="introduction">Introduction</a></h2>
 <p>PyObjC is a proxy between Objective-C and Python and allows access to Python

pyobjc/Doc/classes.txt

 Python classes and Objective-C code
 ===================================
 
-.. This file is formatted using the rules for StructuredText
+.. This file is formatted using the rules for reStructuredText
 
 .. Version 0.1
 

pyobjc/Doc/index.html

 <ul>
 <li><a href="tutorial/tutorial.html">Creating your first PyObjC application (tutorial)</a><p>This tutorial guides you though creating a Python based Cocoa application.</p>
 </li>
-<li><a href="tutorial_embed/extending_objc_with_python.html">Adding Python code to an existing ObjC application</a><p>This tutorial teaches you how to extend you existing Objective-C based
+<li><a href="tutorial_embed/extending_objc_with_python.html">Adding Python code to an existing Objective-C application</a><p>This tutorial teaches you how to extend you existing Objective-C based
 Cocoa application using Python.</p>
 </li>
 </ul>

pyobjc/Doc/index.txt

 
   This tutorial guides you though creating a Python based Cocoa application.
 
-* `Adding Python code to an existing ObjC application`_
+* `Adding Python code to an existing Objective-C application`_
 
   This tutorial teaches you how to extend you existing Objective-C based
   Cocoa application using Python.
 
 .. _`Creating your first PyObjC application (tutorial)`: tutorial/tutorial.html
 
-.. _`Adding Python code to an existing ObjC application`: tutorial_embed/extending_objc_with_python.html
+.. _`Adding Python code to an existing Objective-C application`: tutorial_embed/extending_objc_with_python.html
 
 .. _`Notes on supported APIs and classes on Mac OS X`: api-notes-macosx.html

pyobjc/Doc/intro.html

 :copyright: 2003-2005 The PyObjC Project -->
 <h2>Contents</h2>
 <ul>
-<li><a href="#preface" id="id4" name="id4">Preface</a></li>
-<li><a href="#objective-c-for-pyobjc-users" id="id5" name="id5">Objective-C for PyObjC users</a></li>
-<li><a href="#overview-of-the-bridge" id="id6" name="id6">Overview of the bridge</a><ul>
-<li><a href="#classes" id="id7" name="id7">Classes</a></li>
-<li><a href="#messages-and-functions" id="id8" name="id8">Messages and Functions</a></li>
-<li><a href="#reference-counting" id="id9" name="id9">Reference counting</a></li>
-<li><a href="#informal-protocols" id="id10" name="id10">(Informal) protocols</a></li>
-<li><a href="#cocoa-bindings" id="id11" name="id11">Cocoa Bindings</a></li>
-<li><a href="#categories" id="id12" name="id12">Categories</a></li>
+<li><a href="#preface" id="id5" name="id5">Preface</a></li>
+<li><a href="#objective-c-for-pyobjc-users" id="id6" name="id6">Objective-C for PyObjC users</a></li>
+<li><a href="#overview-of-the-bridge" id="id7" name="id7">Overview of the bridge</a><ul>
+<li><a href="#classes" id="id8" name="id8">Classes</a></li>
+<li><a href="#messages-and-functions" id="id9" name="id9">Messages and Functions</a></li>
+<li><a href="#reference-counting" id="id10" name="id10">Reference counting</a></li>
+<li><a href="#informal-protocols" id="id11" name="id11">(Informal) protocols</a></li>
+<li><a href="#cocoa-bindings" id="id12" name="id12">Cocoa Bindings</a></li>
+<li><a href="#categories" id="id13" name="id13">Categories</a></li>
 </ul>
 </li>
-<li><a href="#cocoa-for-python-programmers" id="id13" name="id13">Cocoa for Python programmers</a></li>
-<li><a href="#notes-on-specific-tasks" id="id14" name="id14">Notes on specific tasks</a><ul>
-<li><a href="#working-with-threads" id="id15" name="id15">Working with threads</a></li>
-<li><a href="#finalizers" id="id16" name="id16">Finalizers</a></li>
+<li><a href="#cocoa-for-python-programmers" id="id14" name="id14">Cocoa for Python programmers</a></li>
+<li><a href="#notes-on-specific-tasks" id="id15" name="id15">Notes on specific tasks</a><ul>
+<li><a href="#working-with-threads" id="id16" name="id16">Working with threads</a></li>
+<li><a href="#finalizers" id="id17" name="id17">Finalizers</a></li>
 </ul>
 </li>
-<li><a href="#building-applications" id="id17" name="id17">Building applications</a><ul>
-<li><a href="#py2app-setup-py" id="id18" name="id18">&quot;py2app&quot; :  setup.py</a></li>
-<li><a href="#ide-approach-xcode" id="id19" name="id19">&quot;IDE approach&quot; : Xcode</a></li>
+<li><a href="#building-applications" id="id18" name="id18">Building applications</a><ul>
+<li><a href="#py2app-setup-py" id="id19" name="id19">&quot;py2app&quot; :  setup.py</a></li>
+<li><a href="#ide-approach-xcode" id="id20" name="id20">&quot;IDE approach&quot; : Xcode</a></li>
 </ul>
 </li>
 </ul>
-<h2><a href="#id4" name="preface">Preface</a></h2>
+<h2><a href="#id5" name="preface">Preface</a></h2>
 <p>PyObjC is a bridge between Python and Objective-C.  It allows you to write 
 Python scripts that use and extend existing Objective-C class libraries, 
 most importantly the <a href="http://developer.apple.com/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="#id5" name="objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></h2>
+<h2><a href="#id6" 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
 <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="#id6" name="overview-of-the-bridge">Overview of the bridge</a></h2>
-<h3><a href="#id7" name="classes">Classes</a></h3>
+<h2><a href="#id7" name="overview-of-the-bridge">Overview of the bridge</a></h2>
+<h3><a href="#id8" 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 
 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="#id8" name="messages-and-functions">Messages and Functions</a></h3>
+<h3><a href="#id9" 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>
 </blockquote>
 </li>
 </ol>
-<p>XXX: Notes about varargs</p>
+<p>Note that it is currently not possible to support methods with a variable
+number of arguments from Python.  These selectors must be wrapped by
+custom Objective-C code in order to be accessible by Python.</p>
 <p>Wrapped/bridged methods (and functions) have the same number of arguments
 as the corresponding Objective-C method or function, unless otherwise noted
 in the documentation (<a href="api-notes-macosx.html">Notes on supported APIs and classes on Mac OS X</a> for
 method signature.  Furthermore, if you implement a method in an (informal)
 protocol known to the bridge it will use the signature from the corresponding
 method in that signature.</p>
-<p>XXX: Add information about setters.</p>
 <p>The end result is that you rarely have to add information about the
-signature of methods.  The only known case where you have to tell the bridge
-about the signature of a method is the callback method for sheets.  You can
-use the function <code><span>PyObjCTools.AppHelper.endSheetMethod</span></code> to create an object
-that contains the right information.  This function is used like 
-<code><span>staticmethod</span></code> and <code><span>classmethod</span></code> (as introduced in Python 2.2).</p>
+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>
+<dt><code><span>objc.accessor</span></code>:</dt>
+<dd><p>Use this to wrap a <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/">Key-Value Coding</a> or <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueObserving/">Key-Value Observing</a> compliant
+accessor.</p>
+</dd>
+<dt><code><span>PyObjCTools.AppHelper.endSheetMethod</span></code>:</dt>
+<dd><p>Use this to wrap the implementation of a sheet's &quot;didEndSelector&quot; callback.</p>
+</dd>
+</dl>
 <p>For complete control of the mapping to Objective-C you can use the function
-<code><span>objc.selector</span></code>. See the documentation of the <code><span>objc</span></code> module for the
-arguments you can use with this function. It is normally used like this:</p>
+<code><span>objc.selector</span></code> to create custom descriptors. See the documentation of the
+<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):
         def someMethod_(self, arg):
 
         someMethod_ = objc.selector(someMethod_, ...)
 </pre>
-<h3><a href="#id9" name="reference-counting">Reference counting</a></h3>
+<h3><a href="#id10" 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="#id10" name="informal-protocols">(Informal) protocols</a></h3>
+<h3><a href="#id11" name="informal-protocols">(Informal) 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>
 <p>PyObjC will automatically use the information in the <code><span>informal_protocol</span></code> 
 objects to add the right method signatures to methods, and to warn about
 classes that partially implement a protocol.</p>
-<h3><a href="#id11" name="cocoa-bindings">Cocoa Bindings</a></h3>
-<p>In Mac OS X 10.3 Apple introduced <i>Cocoa Bindings</i>, a method to make it easier
-to create and use <i>Controller</i> objects.</p>
-<p>XXX - Add more here, links, etc.</p>
-<p>Use <code><span>objc.accessor</span></code> to create accessor methods that conform to the 
-expectations of Cocoa Bindings.</p>
-<h3><a href="#id12" name="categories">Categories</a></h3>
+<h3><a href="#id12" 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="#id13" 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>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="#id13" name="cocoa-for-python-programmers">Cocoa for Python programmers</a></h2>
+<h2><a href="#id14" 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="#id14" name="notes-on-specific-tasks">Notes on specific tasks</a></h2>
-<h3><a href="#id15" name="working-with-threads">Working with threads</a></h3>
+<h2><a href="#id15" name="notes-on-specific-tasks">Notes on specific tasks</a></h2>
+<h3><a href="#id16" name="working-with-threads">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="#id16" name="finalizers">Finalizers</a></h3>
+<h3><a href="#id17" name="finalizers">Finalizers</a></h3>
 <p>In Python you can use the method <code><span>__del__</span></code> to clean up resources when your
 object is garbage collected. In Objective-C/Cocoa this is done with a method 
 named <code><span>dealloc</span></code>.</p>
 <p>In PyObjC you should always use the <code><span>__del__</span></code> method, the <code><span>dealloc</span></code> method
 can safely be ignored and the bridge will complain when you try to override
 this method.</p>
-<h2><a href="#id17" name="building-applications">Building applications</a></h2>
+<h2><a href="#id18" name="building-applications">Building applications</a></h2>
 <p>There are two different ways to build applications with PyObjC. py2app
 should be the preferred method, however using the Xcode template can
 be convenient for development.</p>
-<h3><a href="#id18" name="py2app-setup-py">&quot;py2app&quot; :  setup.py</a></h3>
+<h3><a href="#id19" 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="#id19" name="ide-approach-xcode">&quot;IDE approach&quot; : Xcode</a></h3>
+<h3><a href="#id20" 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. Those templates are used like any other
 Xcode template. The only non-obvious detail is that you have to

pyobjc/Doc/intro.txt

       translates to
       ``result = someObject.someMethod_withFoo_andBar_(firstArg, foo, bar)``
 
-XXX: Notes about varargs
+Note that it is currently not possible to support methods with a variable
+number of arguments from Python.  These selectors must be wrapped by
+custom Objective-C code in order to be accessible by Python.
 
 Wrapped/bridged methods (and functions) have the same number of arguments
 as the corresponding Objective-C method or function, unless otherwise noted
 protocol known to the bridge it will use the signature from the corresponding
 method in that signature.
 
-XXX: Add information about setters.
+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,
+we have provided convenience decorators (used like ``staticmethod`` or
+``classmethod``):
 
-The end result is that you rarely have to add information about the
-signature of methods.  The only known case where you have to tell the bridge
-about the signature of a method is the callback method for sheets.  You can
-use the function ``PyObjCTools.AppHelper.endSheetMethod`` to create an object
-that contains the right information.  This function is used like 
-``staticmethod`` and ``classmethod`` (as introduced in Python 2.2).
+``objc.accessor``:
+    Use this to wrap a `Key-Value Coding`_ or `Key-Value Observing`_ compliant
+    accessor.
+
+``PyObjCTools.AppHelper.endSheetMethod``:
+    Use this to wrap the implementation of a sheet's "didEndSelector" callback.
 
 For complete control of the mapping to Objective-C you can use the function
-``objc.selector``. See the documentation of the ``objc`` module for the
-arguments you can use with this function. It is normally used like this::
+``objc.selector`` to create custom descriptors. See the documentation of the
+``objc`` module for the arguments you can use with this function. It is
+normally used like this::
 
 	class MyObject (NSObject):
 		def someMethod_(self, arg):
 Cocoa Bindings
 ..............
 
-In Mac OS X 10.3 Apple introduced *Cocoa Bindings*, a method to make it easier
-to create and use *Controller* objects. 
+In Mac OS X 10.3 Apple introduced `Cocoa Bindings`_, a method to make it easier
+to create and use *Controller* objects using `Key-Value Observing`_ and `Key-Value
+Coding`_.  In order to create accessors compatible with this, you
+must use ``objc.accessor`` to create an appropriate selector descriptor.
 
-XXX - Add more here, links, etc.
-
-Use ``objc.accessor`` to create accessor methods that conform to the 
-expectations of Cocoa Bindings.
+.. _`Cocoa Bindings`: http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaBindings/
+.. _`Key-Value Coding`: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueCoding/
+.. _`Key-Value Observing`: http://developer.apple.com/documentation/Cocoa/Conceptual/KeyValueObserving/
 
 Categories
 ..........

pyobjc/Doc/release-process.html

 <code><span>Modules/objc/pyobjc.h</span></code>.</li>
 <li>Run <code><span>python</span> <span>setup.py</span> <span>sdist</span></code> to build the source tarball.</li>
 <li>Run <code><span>python</span> <span>setup.py</span> <span>bdist_dmg</span></code> to build a binary installer.  This should
-be done on each supported version of Mac OS X.</li>
+be done for each supported version combination of Mac OS X and Python.</li>
 </ul>
 <p>Trash you existing PyObjC installation and reinstall from the new release. Test
 that the new release is working correctly. Installing and testing should be
 done for the binary installer and for the source archive. The latter should
-be done in all supported configurations.  Also test to make sure that an
+be done for all supported configurations.  Also test to make sure that an
 upgrade from a previous release works as expected.</p>
-<p>If the package works as expected upload to a convenient location and ask some
+<p>If the package works as expected, upload to a convenient location and ask some
 other people (like the other maintainers) to test the new release.</p>
 <h2><a name="release-date">Release-date</a></h2>
 <ul>

pyobjc/Doc/release-process.txt

 * Run ``python setup.py sdist`` to build the source tarball.
 
 * Run ``python setup.py bdist_dmg`` to build a binary installer.  This should
-  be done on each supported version of Mac OS X.
+  be done for each supported version combination of Mac OS X and Python.
 
 Trash you existing PyObjC installation and reinstall from the new release. Test
 that the new release is working correctly. Installing and testing should be
 done for the binary installer and for the source archive. The latter should
-be done in all supported configurations.  Also test to make sure that an
+be done for all supported configurations.  Also test to make sure that an
 upgrade from a previous release works as expected.
 
-If the package works as expected upload to a convenient location and ask some
+If the package works as expected, upload to a convenient location and ask some
 other people (like the other maintainers) to test the new release.
 
 Release-date

pyobjc/Doc/structure.html

 <p>The first Python subclass of an Objective-C class introduces a new instance
 variable in the Objective-C object to store the pointer to the Python half of
 the cluster.  This variable is always referenced by name.  The Python half is 
-a subclass of objc_object that already contains a pointer to an Objective-C 
+a subclass of <code><span>objc_object</span></code> that already contains a pointer to an Objective-C 
 object.  This first subclass also introduces a number of class and instance
 methods that the PyObjC bridge uses to maintain the illusion of a single
 object on both sides.  Check class-builder.m for details.</p>
 </dl>
 <h2><a name="reference-counts">Reference counts</a></h2>
 <p>The Objective-C rules for reference counts are pretty easy: A small number
-of class methods (alloc, allocWithZone:, copy, ...) transfer object ownership
-to the caller.  For all other objects you have to call 'retain' if you want
-to keep a reference.  This includes all factory methods (e.g. 
-[NSString stringWithCString:&quot;bla&quot;])!</p>
+of class methods (<code><span>alloc</span></code>, <code><span>allocWithZone:</span></code>, <code><span>copy</span></code>, ...) transfer
+object ownership to the caller.  For all other objects you have to call
+<code><span>retain</span></code> if you want to keep a reference.  This includes all factory
+methods, such as <code><span>[NSString</span> <span>stringWithCString:&quot;bla&quot;]</span></code>!</p>
 <p>When programming Cocoa in Python, you rarely need to worry about
-reference counts: the objc module makes this completely transparent to user.
-This is mostly implemented in [de]pythonify_c_value. Additonal code is needed
-when calling methods that transfer ownership of their return value (as
-described above) and when updating a instance variable in an Objective-C
-object (retain new and release old, in that order). Both are implemented.</p>
+reference counts: the <code><span>objc</span></code> module makes this completely transparent to
+user.  This is mostly implemented in <code><span>[de]pythonify_c_value</span></code>. Additonal
+code is needed when calling methods that transfer ownership of their return
+value (as described above) and when updating a instance variable in an
+Objective-C object (retain new and release old, in that order). Both are
+implemented.</p>
 <h2><a name="strings">Strings</a></h2>
-<p>Python unicode instances are automatically converted to NSString and
-back. An NSString is represented in Python as a subclass of the 'unicode'
-class: objc.pyobjc_unicode.  This is a conversion, because Python's unicode
-type is immutable, but it also maintains a <i>reference</i> to the original
-NSString.  Currently, the conversion is done using UTF-8 for exchange,
-because unicode's internal representation may be changed with a compile
-time flag.</p>
-<p>The original, unwrapped, NSString instance is accessible from Python
-with the .nsstring() method of objc.pyobjc_unicode, mostly for creating an
-updated copy of an NSMutableString's contents.  Since PyObjC 1.2,
-NSString and NSMutableString methods are available from the objc.pyobjc_unicode
-object, though they do not show up via Python's introspection mechanisms.</p>
-<p>For legacy and convenience, Python str instances are automatically coerced
-into unicode when they cross the bridge using the same mechanism that
-automatically converts from str to unicode (using 
+<p>Python <code><span>unicode</span></code> instances are automatically converted to <code><span>NSString</span></code> and
+back.  An <code><span>NSString</span></code> is represented in Python as a subtype of <code><span>unicode</span></code>:
+<code><span>objc.pyobjc_unicode</span></code>.  This performs a conversion, because Python's
+<code><span>unicode</span></code> type is immutable, but it also maintains a <i>reference</i> to the
+original <code><span>NSString</span></code>.  Currently, the conversion is done using UTF-8 for
+exchange, because the internal representation of <code><span>unicode</span></code> is dependent on
+compile time settings.</p>
+<p>The original, unwrapped, <code><span>NSString</span></code> instance is accessible from Python
+with the <code><span>nsstring()</span></code> method of <code><span>objc.pyobjc_unicode</span></code>, primarily used
+to access an updated copy of an <code><span>NSMutableString</span></code>'s contents.  Since
+PyObjC 1.2, <code><span>NSString</span></code> and <code><span>NSMutableString</span></code> methods are available from
+the <code><span>objc.pyobjc_unicode</span></code> object, though they do not show up via Python's
+introspection mechanisms.</p>
+<p>For legacy and convenience, Python <code><span>str</span></code> instances are automatically coerced
+to <code><span>unicode</span></code> when they cross the bridge using the same mechanism that
+automatically converts from <code><span>str</span></code> to <code><span>unicode</span></code> (using 
 <code><span>sys.getdefaultencoding()</span></code>).  This automatic conversion can cause terrible
 things to happen at runtime that are hard to test for, so you may enable an
-<code><span>objc.PyObjCStrBridgeWarning</span></code> at each coercion by calling
+<code><span>objc.PyObjCStrBridgeWarning</span></code> at each coercion attempt by calling
 <code><span>objc.setStrBridgeEnabled(False)</span></code>.  To promote this warning to an exception,
 see the documentation for the <code><span>warnings</span></code> module in the standard library.</p>
 </body>

pyobjc/Doc/structure.txt

 The first Python subclass of an Objective-C class introduces a new instance
 variable in the Objective-C object to store the pointer to the Python half of
 the cluster.  This variable is always referenced by name.  The Python half is 
-a subclass of objc_object that already contains a pointer to an Objective-C 
+a subclass of ``objc_object`` that already contains a pointer to an Objective-C 
 object.  This first subclass also introduces a number of class and instance
 methods that the PyObjC bridge uses to maintain the illusion of a single
 object on both sides.  Check class-builder.m for details.
 ----------------
 
 The Objective-C rules for reference counts are pretty easy: A small number
-of class methods (alloc, allocWithZone:, copy, ...) transfer object ownership
-to the caller.  For all other objects you have to call 'retain' if you want
-to keep a reference.  This includes all factory methods (e.g. 
-[NSString stringWithCString:"bla"])!
+of class methods (``alloc``, ``allocWithZone:``, ``copy``, ...) transfer
+object ownership to the caller.  For all other objects you have to call
+``retain`` if you want to keep a reference.  This includes all factory
+methods, such as ``[NSString stringWithCString:"bla"]``!
 
 When programming Cocoa in Python, you rarely need to worry about
-reference counts: the objc module makes this completely transparent to user.
-This is mostly implemented in [de]pythonify_c_value. Additonal code is needed
-when calling methods that transfer ownership of their return value (as
-described above) and when updating a instance variable in an Objective-C
-object (retain new and release old, in that order). Both are implemented.
+reference counts: the ``objc`` module makes this completely transparent to
+user.  This is mostly implemented in ``[de]pythonify_c_value``. Additonal
+code is needed when calling methods that transfer ownership of their return
+value (as described above) and when updating a instance variable in an
+Objective-C object (retain new and release old, in that order). Both are
+implemented.
 
 Strings
 -------
 
-Python unicode instances are automatically converted to NSString and
-back. An NSString is represented in Python as a subclass of the 'unicode'
-class: objc.pyobjc_unicode.  This is a conversion, because Python's unicode
-type is immutable, but it also maintains a *reference* to the original
-NSString.  Currently, the conversion is done using UTF-8 for exchange,
-because unicode's internal representation may be changed with a compile
-time flag.
+Python ``unicode`` instances are automatically converted to ``NSString`` and
+back.  An ``NSString`` is represented in Python as a subtype of ``unicode``:
+``objc.pyobjc_unicode``.  This performs a conversion, because Python's
+``unicode`` type is immutable, but it also maintains a *reference* to the
+original ``NSString``.  Currently, the conversion is done using UTF-8 for
+exchange, because the internal representation of ``unicode`` is dependent on
+compile time settings.
 
-The original, unwrapped, NSString instance is accessible from Python
-with the .nsstring() method of objc.pyobjc_unicode, mostly for creating an
-updated copy of an NSMutableString's contents.  Since PyObjC 1.2,
-NSString and NSMutableString methods are available from the objc.pyobjc_unicode
-object, though they do not show up via Python's introspection mechanisms.
+The original, unwrapped, ``NSString`` instance is accessible from Python
+with the ``nsstring()`` method of ``objc.pyobjc_unicode``, primarily used
+to access an updated copy of an ``NSMutableString``'s contents.  Since
+PyObjC 1.2, ``NSString`` and ``NSMutableString`` methods are available from
+the ``objc.pyobjc_unicode`` object, though they do not show up via Python's
+introspection mechanisms.
 
-For legacy and convenience, Python str instances are automatically coerced
-into unicode when they cross the bridge using the same mechanism that
-automatically converts from str to unicode (using 
+For legacy and convenience, Python ``str`` instances are automatically coerced
+to ``unicode`` when they cross the bridge using the same mechanism that
+automatically converts from ``str`` to ``unicode`` (using 
 ``sys.getdefaultencoding()``).  This automatic conversion can cause terrible
 things to happen at runtime that are hard to test for, so you may enable an
-``objc.PyObjCStrBridgeWarning`` at each coercion by calling
+``objc.PyObjCStrBridgeWarning`` at each coercion attempt by calling
 ``objc.setStrBridgeEnabled(False)``.  To promote this warning to an exception,
 see the documentation for the ``warnings`` module in the standard library.

pyobjc/Doc/tutorial_reading.html

 <h2>Understanding existing PyObjC examples</h2>
 <h2><a name="introduction">Introduction</a></h2>
 <p>This tutorial is aimed primarily at people with little or no background
-in ObjC and Cocoa, and it will help you to understand PyObjC programs
+in Objective-C and Cocoa, and it will help you to understand PyObjC programs
 written by other people, such as the examples included with the distribution.
 This document is actually not a true tutorial: you do not get to build anything,
 only read and examine things.</p>
 experience with PyObjC, Cocoa and especially Interface Builder.</p>
 <h2><a name="model-view-controller">Model-View-Controller</a></h2>
 <p>If you have used another GUI toolkit in the past it is essential that
-you understand that Cocoa is different. For this once this isn't marketing-speak:
-Cocoa is inherently different from common toolkits such as Tk, wxWindows,
-Carbon, win32 and all the other popular ones. Apple's documentation explains this,
-but in the introductory sections that are often quickly glanced over. It is a
-good idea to refer back to <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/AppArchitecture/index.html">Application Architecture</a> after reading this section. If you really
-want you can break out of the architecture sketched in this section, but
-then you are on your own, really: Cocoa and Interface Builder really
-expect you to follow this model.</p>
-<p>Cocoa is built on the Model-View-Controller paradigm (MVC). What this means
-is that the application code is going to be split into three parts:</p>
+you understand that Cocoa is different.  For this once this isn't
+marketing-speak: Cocoa is inherently different from common toolkits such as
+Tk, wxWindows, Carbon, MFC, etc.  Apple's documentation explains this, but
+such introductory text is often skipped.  It is a good idea to refer back to
+<a href="http://developer.apple.com/documentation/Cocoa/Conceptual/AppArchitecture/index.html">Application Architecture</a> after reading this section.  If you want, you can
+write code that does not follow the Model-View-Controller paradigm, but you
+would be on your own.  Cocoa and Interface Builder are designed to suit this
+model.</p>
+<p>Cocoa is built on the Model-View-Controller paradigm (MVC).  What this means
+is that the application code should be split into three parts:</p>
 <ul>
-<li>The <i>Model</i> is the actual data you are manipulating, plus the operations
-on it. It can be as big as a complete database engine or a scientific
-simulation, or as small as a routine that multiplies one floating point
-number (an amount of money in currency A) by another (the conversion
-rate from currency A to currency B), as in the currency converter
-application you built in the first tutorial.</li>
-<li>The <i>View</i> is what the user sees on-screen, plus his or her interaction
-with it.</li>
-<li>The <i>Controller</i> is the glue that binds these two together. In the
-currency converter example, it is the code that gets called when the user
-presses the &quot;Convert&quot; button, whereupon it gets the data from the &quot;amount&quot;
-and &quot;rate&quot; fields from the View, passes them to the Model for computation
-and sends the result back to the View.</li>
+<li>The <i>Model</i> is the storage of and operations on the data.  The model
+could be as complicated as a large database, or as simple as a
+currency conversion function that only knows how to multiply two floating
+point numbers, as in the Currency Converter application built in the first
+tutorial.</li>
+<li>The <i>View</i> is what the user sees and interacts with on-screen.</li>
+<li>The <i>Controller</i> is the glue that binds the Model and the View together.
+In the Currency Converter tutorial it is the callback that is triggered
+when the user presses the &quot;Convert&quot; button, which gets the data from the
+&quot;amount&quot; and &quot;rate&quot; fields of the View, passes them to the Model for
+computation and sends the result back to the View.</li>
 </ul>
-<p>To summarize: the Model knows nothing about dialogs and buttons and such,
-the View knows nothing about data and algorithms and the Controller ties it
-all together. For really tiny applications, such as the currency converter,
-you could do away with the Model and simply put that code right in the
-Controller. MVC purists say you should not do this, and it can indeed
-make your code harder to read (because the Controller will contain a mix
-of algorithms and glue code), but there is no architectural reason that
-stops you. If you combine the two classes it is customary to use the name
-you would use for your document class, so without &quot;Controller&quot;. Note that
-MVC is not specific to Cocoa, you can use the paradigm with any GUI toolkit,
-but Cocoa really steers you towards it.</p>
+<p>To summarize: the Model knows nothing about the user, the View knows nothing
+about the data and operations, and the Controller only knows how to relate
+the Model and the View.  For really tiny applications, such as the currency
+converter, it may be tempting to do away with the Model and simply put that
+code in the Controller.  You probably shouldn't do this, as it can make
+your code harder to read since it will be a mix of algorithms and glue code,
+however there is no technical limitation that prevents you from doing this.
+If you do combine the functionality of the model and controller, it is
+customary to name it as if it represented the document (without &quot;Controller&quot;).
+Note that the MVC paradigm is not specific to Cocoa and can be used with almost
+any GUI toolkit, but Cocoa is explicitly designed for this paradigm.</p>
 <p>You should have an MVC trio for every distinct unit of information in your
-program. In case of a simple dialog-style application such as Currency Converter
-you will have one such trio. Most applications, however, will have at least
+program.  In case of a simple dialog-style application such as Currency Converter
+you will have one such trio.  Most applications, however, will have at least
 two: one for the application itself and one for the &quot;documents&quot; the application
-handles. These may be real documents (i.e. files), but they could also be more
-abstract. If your application does scientific simulation and you want to be
-able to open two simulation windows at the same time you should use the
-document model.</p>
+handles.  These may be real documents (i.e. files), but a document can be more
+abstract.  For example, if your application does scientific simulations that
+run in separate windows, each simulation could be a document.</p>
 <h2><a name="the-nib-file">The NIB file</a></h2>
 <p>Cocoa and Interface Builder strongly encourage you to use a NIB file
-per MVC trio. Again: follow this encouragement unless you are sure what
-you are doing.</p>
+per MVC trio.   You should follow this encouragement unless you are sure
+that you know what you are doing.</p>
 <p>This brings us to the second big difference between Cocoa and other GUI
-toolkits: almost all the boilerplate code is in the NIB, and therefore
-the source of Cocoa programs, especially example programs that do little
-real work, will look stunningly small if you are familiar with, say,
-Tkinter.</p>
+toolkits: almost all of the boilerplate code is replaced by the NIB.
+The source of Cocoa programs that do little work, especially example programs,
+will typically be much shorter than the equivalent with other toolkits.</p>
 <p>The NIB file is <i>not</i> a description of dialogs and menus and buttons, as you 
-would get out of interface-builders for other toolkits. There, at startup
-something will read the description, create the buttons and hand the finished
-dialog to your code. A NIB file is more: it contains a complete set of frozen
-objects, conceptually similar to a pickle in Python. You tell Interface Builder
-knows about all the relevant classes in your application, the instances you
+would get out of interface-builders for other toolkits.  A NIB file is more:
+it contains a archived object graph that represents the GUI, conceptually
+similar to a pickle in Python.  You tell Interface Builder
+about all the relevant classes in your application, the instances you
 want to create from those classes, and how the classes should connect to
-each other. Interface Builder the actually instantiates the classes, makes
+each other.  Interface Builder the actually instantiates the classes, makes
 all the connections and at that point freezes and stores the whole lot.</p>
-<p>When your NIB is read the objects are thawed, the connections restored and
-the objects get a running start. Again, this is conceptually similar
-to how unpickling works.</p>
-<blockquote>
-<p>The section above explains a lot of the strangeness in PyObjC
-programs: why you don't create windows and other dialogs (they
-already exist); why you shouldn't do initialization in <code><span>__init__</span></code>
-(because it will be called at some undefined point in time, while
-reading the NIB) but in <code><span>awakeFromNib:</span></code> in stead; why you don't
-have to create and initialize the attributes that tie your
-objects together (they are already tied together).</p>
-<p><code><span>awakeFromNib:</span></code> is very similar in nature to <code><span>__setstate__</span></code> for
-a pickled Python object, but it happens after all objects have been
-unserialized.</p>
-</blockquote>
+<p>Unarchival of a NIB happens in two phases.  The objects are restored using the
+<code><span>NSCoding</span></code> protocol (<code><span>initWithCoder:</span></code> is similar to <code><span>__setstate__</span></code> of
+Python's <code><span>pickle</span></code> protocol), and then each object is sent an
+<code><span>awakeFromNib:</span></code> message so that they may do any initialization that depends
+on a fully restored object graph (<code><span>pickle</span></code> does not have this functionality
+built-in).</p>
+<p>The section above explains a lot of the strangeness in AppKit-based PyObjC
+applications:</p>
+<ul>
+<li>Windows and dialogs are typically not explicitly created, because they were
+instantiated by the NIB.</li>
+<li>Initialization is not always done in <code><span>__init__</span></code> or equivalent, because
+the object graph may not be completely unarchived until the first
+<code><span>awakeFromNib:</span></code> is called.</li>
+<li>Attributes that reference other objects are not typically set explicitly,
+but are done by the NIB file during unarchival.</li>
+</ul>
 <p>This also explains why you want separate NIB files for each MVC trio:
-the objects and classes in a NIB file are all unpickled together. In other
-words: if you had created your document window in your application NIB
+the objects and classes in a NIB file are all unarchived together.  In other
+words, if you had created your document window in your application NIB
 (even if you set it to &quot;hidden&quot; initially so it does not show up) it would
 become very difficult to create a second window for a new document.</p>
 <p>If you think about the consequences of this section for a while it will
 become clear why all the boilerplate code is missing from Cocoa applications:
-you don't need it. The NIB file usually contains all of the things that need to
-be done for the Views objects, as is often the case with other gui-builders.
-But in addition the NIB also contains a large proportion of your Model
-functionality: creating the View and Controller objects and tying the
-lot together.</p>
+you don't need it.  Like the output of other gui-builders, a NIB usually
+contains enough information to recreate the view objects, but a NIB can also
+contain a large proportion of the setup for your Model and Controller
+functionality.  This is especially true when using <a href="http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaBindings/">Cocoa Bindings</a>.</p>
 <h2><a name="delegates">Delegates</a></h2>
 <p>If you are familiar with other object-oriented GUI toolkits such as MFC
 another thing to notice is that Cocoa applications often use a <i>delegate</i>
-object where other toolkits would use a subclass. For example: it is not
-common to use your own subclass in stead of <code><span>NSApplication</span></code> for the
-main application object. In stead, <code><span>NSApplication</span></code> objects have a helper
-called its <code><span>delegate</span></code>. The application object will attempt to inform
-its delegate of all sorts of things happening, and the delegate implements
-only the methods for the events in which it is interested.</p>
-<p>For example, the method <code><span>applicationShouldTerminate:</span></code> on the delegate
+object where other toolkits would use a subclass.  For example: it is not
+common to use your own subclass of <code><span>NSApplication</span></code> for the main application
+object.  <code><span>NSApplication</span></code> objects have a helper called its <code><span>delegate</span></code>.
+The application object will attempt to inform its delegate many interesting
+events, and the delegate implements only the methods for the events it is
+interested in.</p>
+<p>For example, the method <code><span>applicationShouldTerminate:</span></code> of the delegate
 is called just before the application quits, and it has a chance to return
-<code><span>NO</span></code> if you don't want to quit just yet.</p>
+<code><span>NO</span></code> if it is not appropriate to quit just yet.</p>
 <h2><a name="examining-a-nib-file">Examining a NIB file</a></h2>
-<p>Let us examine the final NIB of the Currency Converter tutorial with this in mind.
-If you open it and look at the main window (the one with &quot;MainMenu.nib&quot; as
-its title) and select the &quot;Instances&quot; pane you see six objects. Two of these
-have a greyed-out name (&quot;File's Owner&quot; and &quot;First Responder&quot;): these have
-been created for you by Apple. The other four are created by you. Actually:
-&quot;Main Menu&quot; was created by Apple as a convenience, but you are free to modify
-it. The &quot;File's Owner&quot; is either the Controller or the combined Model-Controller
-object, in this case it is the application itself, an instance of <code><span>NSApplication</span></code>.
-Because this application is not a document-based application the MVC trio
-for the actual conversion window are in here too: <code><span>Converter</span></code>, <code><span>Window</span></code> and
-<code><span>ConverterController</span></code> respectively.</p>
+<p>Let us examine the final NIB of the Currency Converter tutorial with this in
+mind.  If you open it and look at the main window (titled &quot;MainMenu.nib&quot;)
+and select the &quot;Instances&quot; pane you should see six objects.  Two of these
+have greyed-out names (&quot;File's Owner&quot; and &quot;First Responder&quot;), these are present
+in every nib can not be changed.  The &quot;File's Owner&quot; is either the Controller
+or the combined Model-Controller object, and is specified by the application
+when it loads the NIB.  For the main nib, which is loaded automatically by
+<code><span>NSApplicationMain</span></code> or <code><span>PyObjCTools.AppHelper.runEventLoop</span></code>, this will be
+the instance of <code><span>NSApplication</span></code>.  Currency Converter is not a document-based
+application, so the MVC trio for the conversion window are in here too.  These
+are named <code><span>Converter</span></code>, <code><span>Window</span></code> and <code><span>ConverterController</span></code> respectively.</p>
 <p>Let us have a look at the <code><span>ConverterController</span></code> object by double clicking it.
 The &quot;MainMenu.nib&quot; window goes to the &quot;Classes&quot; tab, and an info window shows up.
 In the &quot;MainMenu.nib&quot; window the <code><span>ConverterController</span></code> class is selected, and
-you can see it is a subclass of <code><span>NSObject</span></code>. Having the same name for the class
+you can see it is a subclass of <code><span>NSObject</span></code>.  Having the same name for the class
 and the instance is common in Cocoa programs, the main exception being the File
 Owner object.</p>
-<p>The info window shows more information on the <code><span>ConverterController</span></code> class. It
-should pop open to the &quot;attributes&quot; page. In the &quot;Outlets&quot; tab you see that instances
+<p>The info window shows more information on the <code><span>ConverterController</span></code> class.  It
+should pop open to the &quot;attributes&quot; page.  In the &quot;Outlets&quot; tab you see that instances
 of this class have four attributes, <code><span>converter</span></code>, <code><span>rateField</span></code>, <code><span>dollarField</span></code>
-and <code><span>totalField</span></code>. In any instance of <code><span>ConverterController</span></code> you can connect these
-to other objects, as we shall see below. The &quot;Actions&quot; tab shows that there are two
+and <code><span>totalField</span></code>.  In any instance of <code><span>ConverterController</span></code> you can connect these
+to other objects, as we shall see below.  The &quot;Actions&quot; tab shows that there are two
 methods <code><span>convert:</span></code> and <code><span>invertRate:</span></code>, and again you can arrange for these to
 be called on instances of your <code><span>ConverterController</span></code> on certain events by
 making connections.</p>
-<p>So let us now look at the connections for our <code><span>ConverterController</span></code> <i>instance</i>. Select
+<p>So let us now look at the connections for our <code><span>ConverterController</span></code> <i>instance</i>.  Select
 the &quot;Instances&quot; tab in the main window, select <code><span>ConverterController</span></code> and set the info
-window to show &quot;Connections&quot;. You now see all the outlets defined in the class.
+window to show &quot;Connections&quot;.  You now see all the outlets defined in the class.
 Select one, and in the lower half of the info window you will see which object it connects
-to. Moreover, a blue line will also link the object representations in the main window and
+to.  Moreover, a blue line will also link the object representations in the main window and
 in the dialog preview window.</p>
 <p>Finding out who calls your <code><span>convert:</span></code> method is more difficult, though, with this view.
 But, if you select the &quot;Convert&quot; button in the dialog you will see that its <code><span>target</span></code>
-action will go to the <code><span>ConverterController.convert:</span></code> method.</p>
+action will go to the <code><span>ConverterController.convert_</span></code> method.</p>
 <p>Luckily there is a way to find such incoming connections without reverting to guessing.
 For instance, you will be hard put to find who, if anyone, calls 
-<code><span>ConverterController.invertRate:</span></code>. The solution: go to the &quot;MainMenu.nib&quot; window and
-look at the top of the vertical scrollbar. There are two little icons there, one with
-lines and one with squares, with the squares being highlighted. Press it. The view will change
+<code><span>ConverterController.invertRate_</span></code>.  The solution: go to the &quot;MainMenu.nib&quot; window and
+look at the top of the vertical scrollbar.  There are two little icons there, one with
+lines and one with squares, with the squares being highlighted.  Press it.  The view will change
 to a scrollable list with objects in the left column and an indication of connections
-in the right column. You can now see our ConverterController object has four
-outgoing connections (the ones we found earlier) and two incoming connections. Click
-on the incoming connections icon. The view will change again and ConverterController
-will probably scroll out of sight. Locate it, and see that there are two lines
-going out of the ConverterController object. One goes to <code><span>NSButton(Convert)</span></code>
-and is labeled <code><span>convert:</span></code>, we knew about that already. The other one goes to an
+in the right column.  You can now see our ConverterController object has four
+outgoing connections (the ones we found earlier) and two incoming connections.  Click
+on the incoming connections icon.  The view will change again and ConverterController
+will probably scroll out of sight.  Locate it, and see that there are two lines
+going out of the ConverterController object.  One goes to <code><span>NSButton(Convert)</span></code>
+and is labeled <code><span>convert:</span></code>, we knew about that already.  The other one goes to an
 object <code><span>NSMenuItem(Invert</span> <span>Exchange</span> <span>Rate)</span></code> and is labeled <code><span>invertRate:</span></code>, so that
-is where calls to <code><span>invertRate:</span></code> come from. And if you look at where this
+is where calls to <code><span>invertRate:</span></code> come from.  And if you look at where this
 <code><span>NSMenuItem</span></code> sits in the object hierarchy you find that it is an entry in the
 &quot;Edit&quot; menu in the menubar.</p>
 <h2><a name="examining-an-apple-example">Examining an Apple example</a></h2>
-<p>This section remains to be written. Contributions will be gratefully accepted:-)</p>
+<p>This section remains to be written.  Contributions will be gratefully accepted :-)</p>
 </body>
 </html>

pyobjc/Doc/tutorial_reading.txt

 ------------
 
 This tutorial is aimed primarily at people with little or no background
-in ObjC and Cocoa, and it will help you to understand PyObjC programs
+in Objective-C and Cocoa, and it will help you to understand PyObjC programs
 written by other people, such as the examples included with the distribution.
 This document is actually not a true tutorial: you do not get to build anything,
 only read and examine things.
 ---------------------
 
 If you have used another GUI toolkit in the past it is essential that
-you understand that Cocoa is different. For this once this isn't marketing-speak:
-Cocoa is inherently different from common toolkits such as Tk, wxWindows,
-Carbon, win32 and all the other popular ones. Apple's documentation explains this,
-but in the introductory sections that are often quickly glanced over. It is a
-good idea to refer back to `Application Architecture`__ after reading this section. If you really
-want you can break out of the architecture sketched in this section, but
-then you are on your own, really: Cocoa and Interface Builder really
-expect you to follow this model.
+you understand that Cocoa is different.  For this once this isn't
+marketing-speak: Cocoa is inherently different from common toolkits such as
+Tk, wxWindows, Carbon, MFC, etc.  Apple's documentation explains this, but
+such introductory text is often skipped.  It is a good idea to refer back to
+`Application Architecture`__ after reading this section.  If you want, you can
+write code that does not follow the Model-View-Controller paradigm, but you
+would be on your own.  Cocoa and Interface Builder are designed to suit this
+model.
 
 .. __: http://developer.apple.com/documentation/Cocoa/Conceptual/AppArchitecture/index.html
 
-Cocoa is built on the Model-View-Controller paradigm (MVC). What this means
-is that the application code is going to be split into three parts:
+Cocoa is built on the Model-View-Controller paradigm (MVC).  What this means
+is that the application code should be split into three parts:
 
-- The *Model* is the actual data you are manipulating, plus the operations
-  on it. It can be as big as a complete database engine or a scientific
-  simulation, or as small as a routine that multiplies one floating point
-  number (an amount of money in currency A) by another (the conversion
-  rate from currency A to currency B), as in the currency converter
-  application you built in the first tutorial.
+-   The *Model* is the storage of and operations on the data.  The model
+    could be as complicated as a large database, or as simple as a
+    currency conversion function that only knows how to multiply two floating
+    point numbers, as in the Currency Converter application built in the first
+    tutorial.
 
-- The *View* is what the user sees on-screen, plus his or her interaction
-  with it.
+-   The *View* is what the user sees and interacts with on-screen.
 
-- The *Controller* is the glue that binds these two together. In the
-  currency converter example, it is the code that gets called when the user
-  presses the "Convert" button, whereupon it gets the data from the "amount"
-  and "rate" fields from the View, passes them to the Model for computation
-  and sends the result back to the View.
+-   The *Controller* is the glue that binds the Model and the View together.
+    In the Currency Converter tutorial it is the callback that is triggered
+    when the user presses the "Convert" button, which gets the data from the
+    "amount" and "rate" fields of the View, passes them to the Model for
+    computation and sends the result back to the View.
   
-To summarize: the Model knows nothing about dialogs and buttons and such,
-the View knows nothing about data and algorithms and the Controller ties it
-all together. For really tiny applications, such as the currency converter,
-you could do away with the Model and simply put that code right in the
-Controller. MVC purists say you should not do this, and it can indeed
-make your code harder to read (because the Controller will contain a mix
-of algorithms and glue code), but there is no architectural reason that
-stops you. If you combine the two classes it is customary to use the name
-you would use for your document class, so without "Controller". Note that
-MVC is not specific to Cocoa, you can use the paradigm with any GUI toolkit,
-but Cocoa really steers you towards it.
+To summarize: the Model knows nothing about the user, the View knows nothing
+about the data and operations, and the Controller only knows how to relate
+the Model and the View.  For really tiny applications, such as the currency
+converter, it may be tempting to do away with the Model and simply put that
+code in the Controller.  You probably shouldn't do this, as it can make
+your code harder to read since it will be a mix of algorithms and glue code,
+however there is no technical limitation that prevents you from doing this.
+If you do combine the functionality of the model and controller, it is
+customary to name it as if it represented the document (without "Controller").
+Note that the MVC paradigm is not specific to Cocoa and can be used with almost
+any GUI toolkit, but Cocoa is explicitly designed for this paradigm.
 
 You should have an MVC trio for every distinct unit of information in your
-program. In case of a simple dialog-style application such as Currency Converter
-you will have one such trio. Most applications, however, will have at least
+program.  In case of a simple dialog-style application such as Currency Converter
+you will have one such trio.  Most applications, however, will have at least
 two: one for the application itself and one for the "documents" the application
-handles. These may be real documents (i.e. files), but they could also be more
-abstract. If your application does scientific simulation and you want to be
-able to open two simulation windows at the same time you should use the
-document model.
+handles.  These may be real documents (i.e. files), but a document can be more
+abstract.  For example, if your application does scientific simulations that
+run in separate windows, each simulation could be a document.
 
 The NIB file
 ------------
 
 Cocoa and Interface Builder strongly encourage you to use a NIB file
-per MVC trio. Again: follow this encouragement unless you are sure what
-you are doing.
+per MVC trio.   You should follow this encouragement unless you are sure
+that you know what you are doing.
 
 This brings us to the second big difference between Cocoa and other GUI
-toolkits: almost all the boilerplate code is in the NIB, and therefore
-the source of Cocoa programs, especially example programs that do little
-real work, will look stunningly small if you are familiar with, say,
-Tkinter.
+toolkits: almost all of the boilerplate code is replaced by the NIB.
+The source of Cocoa programs that do little work, especially example programs,
+will typically be much shorter than the equivalent with other toolkits.
 
 The NIB file is *not* a description of dialogs and menus and buttons, as you 
-would get out of interface-builders for other toolkits. There, at startup
-something will read the description, create the buttons and hand the finished
-dialog to your code. A NIB file is more: it contains a complete set of frozen
-objects, conceptually similar to a pickle in Python. You tell Interface Builder
-knows about all the relevant classes in your application, the instances you
+would get out of interface-builders for other toolkits.  A NIB file is more:
+it contains a archived object graph that represents the GUI, conceptually
+similar to a pickle in Python.  You tell Interface Builder
+about all the relevant classes in your application, the instances you
 want to create from those classes, and how the classes should connect to
-each other. Interface Builder the actually instantiates the classes, makes
+each other.  Interface Builder the actually instantiates the classes, makes
 all the connections and at that point freezes and stores the whole lot.
 
-When your NIB is read the objects are thawed, the connections restored and
-the objects get a running start. Again, this is conceptually similar
-to how unpickling works.
+Unarchival of a NIB happens in two phases.  The objects are restored using the
+``NSCoding`` protocol (``initWithCoder:`` is similar to ``__setstate__`` of
+Python's ``pickle`` protocol), and then each object is sent an
+``awakeFromNib:`` message so that they may do any initialization that depends
+on a fully restored object graph (``pickle`` does not have this functionality
+built-in).
 
-	The section above explains a lot of the strangeness in PyObjC
-	programs: why you don't create windows and other dialogs (they
-	already exist); why you shouldn't do initialization in ``__init__``
-	(because it will be called at some undefined point in time, while
-	reading the NIB) but in ``awakeFromNib:`` in stead; why you don't
-	have to create and initialize the attributes that tie your
-	objects together (they are already tied together).
-	
-	``awakeFromNib:`` is very similar in nature to ``__setstate__`` for
-	a pickled Python object, but it happens after all objects have been
-	unserialized.
+The section above explains a lot of the strangeness in AppKit-based PyObjC
+applications:
+
+*   Windows and dialogs are typically not explicitly created, because they were
+    instantiated by the NIB.
+
+*   Initialization is not always done in ``__init__`` or equivalent, because
+    the object graph may not be completely unarchived until the first
+    ``awakeFromNib:`` is called.
+
+*   Attributes that reference other objects are not typically set explicitly,
+    but are done by the NIB file during unarchival.
 	
 This also explains why you want separate NIB files for each MVC trio:
-the objects and classes in a NIB file are all unpickled together. In other
-words: if you had created your document window in your application NIB
+the objects and classes in a NIB file are all unarchived together.  In other
+words, if you had created your document window in your application NIB
 (even if you set it to "hidden" initially so it does not show up) it would
 become very difficult to create a second window for a new document.
 
 If you think about the consequences of this section for a while it will
 become clear why all the boilerplate code is missing from Cocoa applications:
-you don't need it. The NIB file usually contains all of the things that need to
-be done for the Views objects, as is often the case with other gui-builders.
-But in addition the NIB also contains a large proportion of your Model
-functionality: creating the View and Controller objects and tying the
-lot together.
+you don't need it.  Like the output of other gui-builders, a NIB usually
+contains enough information to recreate the view objects, but a NIB can also
+contain a large proportion of the setup for your Model and Controller
+functionality.  This is especially true when using `Cocoa Bindings`__.
+
+.. __: http://developer.apple.com/documentation/Cocoa/Conceptual/CocoaBindings/
 
 Delegates
 ---------
 
 If you are familiar with other object-oriented GUI toolkits such as MFC
 another thing to notice is that Cocoa applications often use a *delegate*
-object where other toolkits would use a subclass. For example: it is not
-common to use your own subclass in stead of ``NSApplication`` for the
-main application object. In stead, ``NSApplication`` objects have a helper
-called its ``delegate``. The application object will attempt to inform
-its delegate of all sorts of things happening, and the delegate implements
-only the methods for the events in which it is interested.
+object where other toolkits would use a subclass.  For example: it is not
+common to use your own subclass of ``NSApplication`` for the main application
+object.  ``NSApplication`` objects have a helper called its ``delegate``.
+The application object will attempt to inform its delegate many interesting
+events, and the delegate implements only the methods for the events it is
+interested in.
 
-For example, the method ``applicationShouldTerminate:`` on the delegate
+For example, the method ``applicationShouldTerminate:`` of the delegate
 is called just before the application quits, and it has a chance to return
-``NO`` if you don't want to quit just yet.
+``NO`` if it is not appropriate to quit just yet.
 
 Examining a NIB file
 --------------------
 
-Let us examine the final NIB of the Currency Converter tutorial with this in mind.
-If you open it and look at the main window (the one with "MainMenu.nib" as
-its title) and select the "Instances" pane you see six objects. Two of these
-have a greyed-out name ("File's Owner" and "First Responder"): these have
-been created for you by Apple. The other four are created by you. Actually:
-"Main Menu" was created by Apple as a convenience, but you are free to modify
-it. The "File's Owner" is either the Controller or the combined Model-Controller
-object, in this case it is the application itself, an instance of ``NSApplication``.
-Because this application is not a document-based application the MVC trio
-for the actual conversion window are in here too: ``Converter``, ``Window`` and
-``ConverterController`` respectively.
+Let us examine the final NIB of the Currency Converter tutorial with this in
+mind.  If you open it and look at the main window (titled "MainMenu.nib")
+and select the "Instances" pane you should see six objects.  Two of these
+have greyed-out names ("File's Owner" and "First Responder"), these are present
+in every nib can not be changed.  The "File's Owner" is either the Controller
+or the combined Model-Controller object, and is specified by the application
+when it loads the NIB.  For the main nib, which is loaded automatically by
+``NSApplicationMain`` or ``PyObjCTools.AppHelper.runEventLoop``, this will be
+the instance of ``NSApplication``.  Currency Converter is not a document-based
+application, so the MVC trio for the conversion window are in here too.  These
+are named ``Converter``, ``Window`` and ``ConverterController`` respectively.
 
 Let us have a look at the ``ConverterController`` object by double clicking it.
 The "MainMenu.nib" window goes to the "Classes" tab, and an info window shows up.
 In the "MainMenu.nib" window the ``ConverterController`` class is selected, and
-you can see it is a subclass of ``NSObject``. Having the same name for the class
+you can see it is a subclass of ``NSObject``.  Having the same name for the class
 and the instance is common in Cocoa programs, the main exception being the File
 Owner object.
 
-The info window shows more information on the ``ConverterController`` class. It
-should pop open to the "attributes" page. In the "Outlets" tab you see that instances
+The info window shows more information on the ``ConverterController`` class.  It
+should pop open to the "attributes" page.  In the "Outlets" tab you see that instances
 of this class have four attributes, ``converter``, ``rateField``, ``dollarField``
-and ``totalField``. In any instance of ``ConverterController`` you can connect these
-to other objects, as we shall see below. The "Actions" tab shows that there are two
+and ``totalField``.  In any instance of ``ConverterController`` you can connect these
+to other objects, as we shall see below.  The "Actions" tab shows that there are two
 methods ``convert:`` and ``invertRate:``, and again you can arrange for these to
 be called on instances of your ``ConverterController`` on certain events by
 making connections.
 
-So let us now look at the connections for our ``ConverterController`` *instance*. Select
+So let us now look at the connections for our ``ConverterController`` *instance*.  Select
 the "Instances" tab in the main window, select ``ConverterController`` and set the info
-window to show "Connections". You now see all the outlets defined in the class.
+window to show "Connections".  You now see all the outlets defined in the class.
 Select one, and in the lower half of the info window you will see which object it connects
-to. Moreover, a blue line will also link the object representations in the main window and
+to.  Moreover, a blue line will also link the object representations in the main window and
 in the dialog preview window.
 
 Finding out who calls your ``convert:`` method is more difficult, though, with this view.
 But, if you select the "Convert" button in the dialog you will see that its ``target``
-action will go to the ``ConverterController.convert:`` method.
+action will go to the ``ConverterController.convert_`` method.
 
 Luckily there is a way to find such incoming connections without reverting to guessing.
 For instance, you will be hard put to find who, if anyone, calls 
-``ConverterController.invertRate:``. The solution: go to the "MainMenu.nib" window and
-look at the top of the vertical scrollbar. There are two little icons there, one with
-lines and one with squares, with the squares being highlighted. Press it. The view will change
+``ConverterController.invertRate_``.  The solution: go to the "MainMenu.nib" window and
+look at the top of the vertical scrollbar.  There are two little icons there, one with
+lines and one with squares, with the squares being highlighted.  Press it.  The view will change
 to a scrollable list with objects in the left column and an indication of connections
-in the right column. You can now see our ConverterController object has four
-outgoing connections (the ones we found earlier) and two incoming connections. Click
-on the incoming connections icon. The view will change again and ConverterController
-will probably scroll out of sight. Locate it, and see that there are two lines
-going out of the ConverterController object. One goes to ``NSButton(Convert)``
-and is labeled ``convert:``, we knew about that already. The other one goes to an
+in the right column.  You can now see our ConverterController object has four
+outgoing connections (the ones we found earlier) and two incoming connections.  Click
+on the incoming connections icon.  The view will change again and ConverterController
+will probably scroll out of sight.  Locate it, and see that there are two lines
+going out of the ConverterController object.  One goes to ``NSButton(Convert)``
+and is labeled ``convert:``, we knew about that already.  The other one goes to an
 object ``NSMenuItem(Invert Exchange Rate)`` and is labeled ``invertRate:``, so that
-is where calls to ``invertRate:`` come from. And if you look at where this
+is where calls to ``invertRate:`` come from.  And if you look at where this
 ``NSMenuItem`` sits in the object hierarchy you find that it is an entry in the
 "Edit" menu in the menubar.
 
 Examining an Apple example
 --------------------------
 
-This section remains to be written. Contributions will be gratefully accepted:-)
+This section remains to be written.  Contributions will be gratefully accepted :-)
 
 
 .. _`Creating your first PyObjC application`: tutorial/tutorial.html

pyobjc/Doc/wrapping.html

 <p>Let's say the first argument is an output parameter. Output parameters are 
 denoted in the signature string using the character 'o' before the actual
 argument signature. The 'correct' signature for method is therefore 'v@:o^@@'.
-The following code tells the brigde about this better method signature:</p>
+The following code tells the bridge about this better method signature:</p>
 <pre>
 import objc
 objc.setSignatureForSelector(&quot;ClassName&quot;, &quot;selector:withArguments:&quot;,
      &quot;v@:o^@:@&quot;)
 </pre>
-<p>To anotate method signatures you'll have to add a single character before all
+<p>To annotate method signatures you'll have to add a single character before all
 '^' characters in the signature of a method. The characters are:</p>
 <ul>
 <li>output parameter: o</li>
 implementation of the method from Python and 1 to call a Python implementation
 of the method from Objective-C.</p>
 <p>You also must write a custom wrapper when the method has a variable number
-of arguments. It is often adviseable to documented varargs method as 
+of arguments. It is often advisable to documented varargs method as 
 unsupported, or to support them only using a fixed number of arguments.</p>
 <p>For now it is best to check the source code for the wrappers for the Cocoa 
 class library for more information. We'll add documentation for this in the

pyobjc/Doc/wrapping.txt

 Let's say the first argument is an output parameter. Output parameters are 
 denoted in the signature string using the character 'o' before the actual
 argument signature. The 'correct' signature for method is therefore 'v@:o^@@'.
-The following code tells the brigde about this better method signature::
+The following code tells the bridge about this better method signature::
 
    import objc
    objc.setSignatureForSelector("ClassName", "selector:withArguments:",
    	"v@:o^@:@")
 
-To anotate method signatures you'll have to add a single character before all
+To annotate method signatures you'll have to add a single character before all
 '^' characters in the signature of a method. The characters are:
 
 - output parameter: o
 of the method from Objective-C.
 
 You also must write a custom wrapper when the method has a variable number
-of arguments. It is often adviseable to documented varargs method as 
+of arguments. It is often advisable to documented varargs method as 
 unsupported, or to support them only using a fixed number of arguments.
 
 For now it is best to check the source code for the wrappers for the Cocoa 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.