Commits

Ronald Oussoren committed ad9214a

- Fix markup error in 00README.txt (PB Templates), and likewise in C-API.txt
- Enhance intro.txt
- Add TODO note to api-notes-macosx.txt, because of previous item
- update_html.py adds HTML version of PB Template readme to Docs
- run update_html.py

Comments (0)

Files changed (11)

pyobjc/Doc/C-API.html

 work with Objective-C objects, using (static) methods in a class is much
 more convenient.</p>
 <p>The C API is defined in <code><span>pyobjc-api.h</span></code>. This file is currently not installed
-because the API is not entirely stable.</p>
-<p>XXX: Insert reference to the CodeGeneration scripts.</p>
+because the API is not entirely stable. This is the only file that can
+be included from outside of the 'Modules/objc' directory, future versions of
+the bridge may use additional linker flags to make sure that the module doesn't
+export symbols other than the module init function.</p>
+<p>The easiest way to wrap global functions and constants is by using the scripts
+in Scripts/CodeGenerators. This script is unsupported and might not work on
+anything but the Apple headers, but if it works it will save you a lot of work.</p>
 <h2><a name="limititations">Limititations</a></h2>
 <p>An important limitation of the current C API is that you can only use the API
 from one C file in the implementation of an extension module. This limitation
 otherwise. Reasons for failure include: not being able to locate the module
 and API version conflicts.</p>
 <p>Loading the API will make it impossible to unload the <code><span>calling_module</span></code>.</p>
+<p>NOTE: Using the API other than by the mechanism described in this document 
+is unsupported.</p>
 <h2><a name="compatibility-macros">Compatibility Macros</a></h2>
 <p>On MacOS X, the version guard macro <code><span>MAC_OS_X_VERSION_MAX_ALLOWED</span></code> will 
 always be available.</p>
 </pre>
 <p>This is a variation on <code><span>PyObjC_PythonToId</span></code> than can be used with 
 <code><span>PyArg_Parse</span></code>.</p>
+<pre>
+int PyObjCClass_Convert(PyObject* object, void* pvar);
+</pre>
+<p>This is a variation on <code><span>PyObjCClass_GetClass</span></code> than can be used with 
+<code><span>PyArg_Parse</span></code>.</p>
+<pre>
+int PyObjCSelector_Convert(PyObject* object, void* pvar);
+</pre>
+<p>Write the <code><span>SEL</span></code> for a selector object into <code><span>*pvar</span></code>. 
+For use with <code><span>PyArg_Parse</span></code>.</p>
+<pre>
+int PyObjC_ConvertBOOL(PyObject* object, void* pvar);
+</pre>
+<p>Write <code><span>YES</span></code> into <code><span>*pvar</span></code> if <code><span>object</span></code> is true, write <code><span>NO</span></code> otherwise.
+<code><span>*pvar</span></code> should be of type BOOL.  For use with <code><span>PyArg_Parse</span></code>.</p>
+<pre>
+int PyObjC_ConvertChar(PyObject* object, void* pvar);
+</pre>
+<p>Write the value of a string of length 1 into the character (type char)
+at <code><span>*pvar</span></code>. For use with <code><span>PyArg_Parse</span></code>.</p>
 </body>
 </html>

pyobjc/Doc/C-API.txt

 
   int PyObjCSelector_Convert(PyObject* object, void* pvar);
 
-Write the ``SEL`` for a selector object into *pvar. 
+Write the ``SEL`` for a selector object into ``*pvar``. 
 For use with ``PyArg_Parse``.
 
 ::
 
   int PyObjC_ConvertBOOL(PyObject* object, void* pvar);
 
-Write ``YES`` into *pvar if ``object`` is true, write ``NO`` otherwise.
-*pvar should be of type BOOL.  For use with ``PyArg_Parse``.
+Write ``YES`` into ``*pvar`` if ``object`` is true, write ``NO`` otherwise.
+``*pvar`` should be of type BOOL.  For use with ``PyArg_Parse``.
 
 ::
 

pyobjc/Doc/ProjectBuilder-Templates.html

+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+Python Project Templates</title>
+<meta name="Author" content="Bill Bumgarner" />
+<meta name="Contact" content="bbum@codefab.com" />
+<title>
+Contents</title>
+</head>
+<body>
+<h2>Python Project Templates</h2>
+<table>
+<tbody valign="top">
+<tr><th >Author:</th>
+<td>Bill Bumgarner</td></tr>
+<tr><th >Contact:</th>
+<td><a href="mailto:bbum@codefab.com">bbum@codefab.com</a></td></tr>
+</tbody>
+</table>
+<p>To use the project templates, simply copy (or link) them into the Project
+Templates directory used by Project Builder.  The project templates are also
+included in the PyObjC installer package.</p>
+<h2>Contents</h2>
+<ul>
+<li><a href="#notes" id="id2" name="id2">Notes</a></li>
+<li><a href="#cocoa-python-templates" id="id3" name="id3">Cocoa-Python Templates</a></li>
+<li><a href="#cocoa-python-application" id="id4" name="id4">Cocoa-Python Application</a></li>
+<li><a href="#cocoa-python-objc-application" id="id5" name="id5">Cocoa-Python-ObjC Application</a></li>
+<li><a href="#cocoa-python-document-based-application" id="id6" name="id6">Cocoa-Python Document-based Application</a></li>
+<li><a href="#cocoa-python-objc-document-based-application" id="id7" name="id7">Cocoa-Python-ObjC Document-based Application</a></li>
+</ul>
+<h2><a href="#id2" name="notes">Notes</a></h2>
+<ul>
+<li>In all cases that involve loading frameworks or bundles, all of the classes
+in that framework or bundle can be made available by using the
+<code><span>loadBundle()</span></code> function in the <code><span>objc</span></code> module:<pre>
+objc.loadBundle(&quot;MyFramework&quot;, globals(), bundle_path=&quot;/path/to/MyFramework.framework&quot;)
+</pre>
+<p>This has the effect of importing all of the classes in the bundle or
+framework into the current python scope's globals.  For all intents and
+purposes, it is similar to:</p>
+<pre>
+from Foundation import *
+</pre>
+</li>
+<li>There is risk that the pyobjc modules compiled for one version of python
+will not work with another.  Where this may be a problem is if the a
+standalone application is packaged with the pyobjc modules compiled
+against, say, the Fink or Framework builds of Python, but is then executed
+using the Apple supplied python binary.</li>
+</ul>
+<blockquote>
+<ul>
+<li>The <i>Project Templates</i> directory includes a <strong>clean.py</strong> script that
+removes noise files from the project templates.   When working on project
+templates, it is recommended that this script be invoked before creating a
+test project from one of the templates.   For example, the presence of
+user specific project builder settings will cause any projects created
+from a template to be incorrect.</li>
+</ul>
+</blockquote>
+<h2><a href="#id3" name="cocoa-python-templates">Cocoa-Python Templates</a></h2>
+<p>The Cocoa-Python templates all create various different kinds of Cocoa
+application projects.   Some of the resulting projects are incompatible with
+Apple's build of Python[#].  Be sure and pick the correct project type for your
+needs.</p>
+<h2><a href="#id4" name="cocoa-python-application">Cocoa-Python Application</a></h2>
+<p>A project created from this template is designed to implement standalone,
+pure-Python, applications that are compatible with Apple's build of Python as
+well as all other builds of python that support PyObjC.</p>
+<p>When building the 'install' target, the resulting application wrapper will
+included the PyObjC module and can be launched on any stock OS X 10.2 system
+without requiring PyObjC to be preinstalled.</p>
+<h2><a href="#id5" name="cocoa-python-objc-application">Cocoa-Python-ObjC Application</a></h2>
+<p>A project created from this template includes an embedded framework project
+into which all compiled code can be placed.  Upon launch, the application
+automatically dynamically loads the embedded framework containing the
+compiled code.</p>
+<p>Each Framework's Resources directory is automatically added to sys.path.</p>
+<!-- Cocoa-Python Application (Embedded Interpreter)
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+<!-- This project template uses an embedded Python interpreter.  As such,
+Objective-C classes can be freely mixed into the project along with Python
+classes.   However, because it uses an embedded interpreter, this project
+must be built and run after some version of Python is installed that can
+support an embedded interpreter.  Alternatively, an application based on this
+template must include a build of Python within its app wrapper. -->
+<!-- This type of project is not compatible with Apple's build of Python. -->
+<h2><a href="#id6" name="cocoa-python-document-based-application">Cocoa-Python Document-based Application</a></h2>
+<p>This template works like the <a href="#cocoa-python-application">Cocoa-Python Application</a> template in that it
+is compatible with the Apple build of Python.   It creates an application
+that uses Cocoa's Multiple Document Architecture in the same fashion as the
+default Cocoa Document-based Application supplied with Project Builder.</p>
+<h2><a href="#id7" name="cocoa-python-objc-document-based-application">Cocoa-Python-ObjC Document-based Application</a></h2>
+<p>A project created from this template includes an embedded framework project
+into which all compiled code can be placed.  Upon launch, the application
+automatically dynamically loads the embedded framework containing the
+compiled code. It is based on the <a href="#cocoa-python-document-based-application">Cocoa-Python Document-based Application</a>
+template.  It creates an application that uses Cocoa's Multiple Document 
+Architecture in the same fashion as the default Cocoa Document-based 
+Application supplied with Project Builder.</p>
+<p>Each Framework's Resources directory is automatically added to sys.path.</p>
+<!-- Cocoa-Python Document-based Application (Embedded Interpreter)
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
+<!-- This template works like the `Cocoa-Python Application (Embedded
+Interpreter)`_ template in that it is incompatible with the Apple build of
+Python.   It creates an application that uses Cocoa's Multiple Document
+Architecture in the same fashion as the default Cocoa Document-based
+Application supplied with Project Builder. -->
+<hr /><table id="id1">
+<tbody valign="top">
+<tr><td><b>[<a name="id1">1</a>]</b></td><td><font size=-1><i>Apple's build of python lacks a shared or static library to which an
+application can be linked.  As such, it is impossible to embed the
+Python interpreter into an application.  Because of this, it is
+impossible to directly link compiled objective-c directly into an
+application project.  Hence, the &quot;Apple Python compatible&quot; projects are
+labeled as 100% pure Python.  Since bundles and frameworks can be
+loaded into such applications, it is still possible to use compiled
+classes.</i></font><br />
+</td></tr>
+</tbody>
+</table>
+</body>
+</html>

pyobjc/Doc/PyObjCTools.html

+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+PyObjCTools: The PyObjC Toolbox</title>
+</head>
+<body>
+<h2>PyObjCTools: The PyObjC Toolbox</h2>
+<h3 id="introduction">Introduction</h3>
+<p>The package <code><span>PyObjCTools</span></code> contains a number of (basicly unrelated) modules
+with usefull functionality. These have been placed inside a module to avoid
+cluttering the global namespace.</p>
+<p>The rest of this document provides documentation for these modules, but lets
+start with a short overview.</p>
+<ul>
+<li><code><span>PyObjCTools.AppHelper</span></code></li>
+</ul>
+<p>Utility functions for use with the <code><span>AppKit</span></code> module.</p>
+<ul>
+<li><code><span>PyObjCTools.Conversion.py</span></code></li>
+</ul>
+<p>Functions for converting between Cocoa and pure Python data structures.</p>
+<ul>
+<li><code><span>PyObjCTools.KeyValueCoding.py</span></code></li>
+</ul>
+<p>A python API for working with Key-Value Coding. XXX: Link</p>
+<ul>
+<li><code><span>PyObjCTools.KeyValueCodingSupport.py</span></code></li>
+</ul>
+<p>Utility functions and mix-in classes for working with Key-Value Coding. This
+module is deprecated.</p>
+<ul>
+<li><code><span>PyObjCTools.NibClassBuilder.py</span></code></li>
+</ul>
+<p>Module containing a magic super-class that can read information about the
+actual super-class and implemented actions and outlets from a NIB file.</p>
+<ul>
+<li><code><span>PyObjCTools.pluginbuilder.py</span></code></li>
+</ul>
+<p>Extension of <code><span>bundlebuilder</span></code> (XXX: Link) that allows you to build python-based
+plugin bundles, such as panes for the System Preferences application and
+screen savers.</p>
+<ul>
+<li><code><span>PyObjCTools.Signals.py</span></code></li>
+</ul>
+<p>Module that tries to print usefull information when the program gets a fatal
+exception. This module should only be used during development.</p>
+</body>
+</html>

pyobjc/Doc/api-notes-macosx.html

 </ul>
 </li>
 </ul>
+<p>TODO: Add documentation about weak linking (see intro.txt).</p>
 <h2><a href="#id2" name="introduction">Introduction</a></h2>
 <p>This document describes the restrictions w.r.t. supported APIs and classes
 on MacOS X. In general you can use classes and global functions just like

pyobjc/Doc/api-notes-macosx.txt

 
 .. Contents::
 
+TODO: Add documentation about weak linking (see intro.txt).
+
+
 Introduction
 ------------
 

pyobjc/Doc/intro.html

 :copyright: 2003 The PyObjC Project -->
 <h2>Contents</h2>
 <ul>
-<li><a href="#work-in-progress" id="id2" name="id2">WORK IN PROGRESS</a></li>
-<li><a href="#preface" id="id3" name="id3">Preface</a></li>
-<li><a href="#objective-c-for-pyobjc-users" id="id4" name="id4">Objective-C for PyObjC users</a></li>
-<li><a href="#overview-of-the-bridge" id="id5" name="id5">Overview of the bridge</a></li>
-<li><a href="#cocoa-for-python-programmers" id="id6" name="id6">Cocoa for Python programmers</a></li>
-<li><a href="#building-applications" id="id7" name="id7">Building applications</a><ul>
-<li><a href="#pure-python-buildapp-py" id="id8" name="id8">&quot;Pure Python&quot; :  buildapp.py</a></li>
-<li><a href="#ide-approach-project-builder" id="id9" name="id9">&quot;IDE approach&quot; : Project builder</a></li>
+<li><a href="#work-in-progress" id="id3" name="id3">WORK IN PROGRESS</a></li>
+<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="#methods-and-functions" id="id8" name="id8">Methods and functions</a></li>
+<li><a href="#reference-counts" id="id9" name="id9">Reference counts</a></li>
+</ul>
+</li>
+<li><a href="#cocoa-for-python-programmers" id="id10" name="id10">Cocoa for Python programmers</a></li>
+<li><a href="#building-applications" id="id11" name="id11">Building applications</a><ul>
+<li><a href="#pure-python-buildapp-py" id="id12" name="id12">&quot;Pure Python&quot; :  buildapp.py</a></li>
+<li><a href="#ide-approach-project-builder" id="id13" name="id13">&quot;IDE approach&quot; : Project builder</a></li>
 </ul>
 </li>
 </ul>
-<h2><a href="#id2" name="work-in-progress">WORK IN PROGRESS</a></h2>
-<p>This document is work in progress and thin on details.</p>
-<h2><a href="#id3" name="preface">Preface</a></h2>
+<h2><a href="#id3" name="work-in-progress">WORK IN PROGRESS</a></h2>
+<p>This document is work in progress.</p>
+<h2><a href="#id4" name="preface">Preface</a></h2>
 <p>PyObjC is a bridge between Python and Objective-C. It allows you to write 
 Python scripts that use and extend existing Objective-C class libraries, 
 most importantly the <a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa libraries</a> by <a href="http://www.apple.com/">Apple</a>.</p>
 <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="#id4" name="objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></h2>
+<h2><a href="#id5" name="objective-c-for-pyobjc-users">Objective-C for PyObjC users</a></h2>
+<p>It is necessary to understand a little bit of Objective-C to use PyObjC,
+this helps you to better understand the class libraries and makes it easier
+to read (and translate) example code.</p>
 <p>Objective-C is an object-oriented programming language that is an extension 
 of C and borrows heavily from Smalltalk. It features single inheritance with
 (in theory) multiple root classes and dynamic dispatch of methods. This is
 <p>Object allocation and initialization are explicit and seperate actions in 
 Objective-C. The former is done by the class-method <code><span>alloc</span></code>, while the
 latter is done by instance-methods whose name customarily starts with <code><span>init</span></code>.</p>
+<p>Objective-C code looks just like plain C code, with some easily recognizable
+extensions for the Object-Oriented parts of the language. And example class
+declaration (usually found in <code><span>.h</span></code> files) and implementation (usually found
+in <code><span>.m</span></code> files) are listed below). Class declarations are easily recognized as 
+blocks of code between <code><span>@interface</span></code> and <code><span>@end</span></code>, and simularly the 
+implementation is between <code><span>@implementation</span></code> and <code><span>@end</span></code>. Calling methods
+is done using expressions enclosed with brackets (name?), e.g. 
+<code><span>[foo</span> <span>method]</span></code>.  This is the same as <code><span>foo.method()</span></code> in Python.</p>
+<p>A class declaration:</p>
+<pre>
+@interface MYClass : MySuperClass
+{
+   id  anInstanceVariable;
+   int anotherInstanceVariable;
+}
+
++aClassMethod;
+
+-(int)anInstanceMethodWithArg1:arg1 andArg2:(BOOL)arg2;
+@end
+</pre>
+<p>A class implemenation:</p>
+<pre>
+@implementation MYClass
+
++aClassMethod
+{
+     id res = [[MYClass alloc] init];
+     return res;
+}
+
+-(int)anInstanceMethodWithArg1:arg1 andArg2:(BOOL)arg2
+{
+     int res;
+
+     if (arg2) {
+             res = [self fooWith:arg1];
+     } else {
+             res = [arg1 bar];
+     }
+}
+
+@end
+</pre>
+<p>Objective-C also features exceptions, but as those are mostly used for disaster
+recovery and not for normal error handling you won't see them very often
+in example code. The <a href="http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/index.html">The Objective-C Programming Language</a> if you want to
+know more about exceptions in Objective-C.</p>
 <p>For more information about Objective-C see:</p>
 <ul>
 <li><a href="http://developer.apple.com/techpubs/macosx/Cocoa/ObjectiveC/index.html">The Objective-C Programming Language</a> at <a href="http://www.apple.com/">Apple</a>.</li>
 </ul>
-<h2><a href="#id5" name="overview-of-the-bridge">Overview of the bridge</a></h2>
+<h2><a href="#id6" name="overview-of-the-bridge">Overview of the bridge</a></h2>
+<h3><a href="#id7" name="classes">Classes</a></h3>
 <p>Objective-C classes are visible as Python classes and can be subclassed just
 like normal Python classes. The major differences between normal Python classes
 and Objective-C classes are the way you create instances and the fact that 
-Objective-C classes have odd names.</p>
+Objective-C methods have odd names.</p>
+<p>Another thing to keep in mind is that the names of Objective-C classes must
+be unique, without taking modules into account. That is, it is <i>not</i> possible
+to have two modules that define a class with the same name. If you write classes
+that will be used outside of a single project it is customary to pick a 
+(short) prefix and stick that in front of all class names, e.g. Apple <code><span>NS</span></code> 
+as the prefix in the <a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa libraries</a>.</p>
 <p>As described in <a href="#objective-c-for-pyobjc-users">Objective-C for PyObjC users</a> the creation of Objective-C 
 objects is a two-stage process. You first call the class method <code><span>alloc</span></code>, and
 then call some variation of <code><span>init</span></code> to initialize the objects. The newly
 created object is the result of the call to <code><span>init</span></code>. Most classes have 
 convienence class methods that combine the calls to <code><span>alloc</span></code> and <code><span>init</span></code>.</p>
+<h3><a href="#id8" name="methods-and-functions">Methods and functions</a></h3>
 <p>Objective-C methods are bridged to Python callables. Because Objective-C method 
 names can contain colons it is necessary to translate methods names. The rules
 for translation are:</p>
 <li>Concatenate all elements of the method name: <code><span>someMethod:withFoo:andBar:</span></code></li>
 <li>Then convert all colons to underscores: <code><span>someMethod_withFoo_andBar_</span></code></li>
 </ul>
-<p>The bridged method usually has the same number of arguments as the orginal 
-method and also returns the same as the original method. In special 
-circumstances the method interface may be different from the Objective-C 
-interface, those methods are document in 'some other document'. Furthermore,
-some methods have pass-by-reference arguments (that is a pointer to a single
-value that is used to transfer data to (in), from (out) or to-and-from (inout)
-the method. The arguments that are passed to methods is present as normal 
-arguments in the bridged method (e.g. if the method has an <code><span>int*</span></code> argument
-the bridged method has has an integer argument).  Data that is passed from the
-function results in additional return values from the function.</p>
-<p>When the bridge cannot automaticly deduce the right signature for a method, or
-if you want to add a method whose name cannot be transformed into Python (
-for example a methodname containing <code><span>$</span></code>), you'll have to add explicit hints
-to your code. You do this by calling the function <code><span>objc.selector</span></code> and using
-the result instead of your method definition:</p>
+<p>Wrapped/bridged methods (and functions) have the same number of arguments
+as the corresponding Objective-C method or function, unless otherwise noted
+in the documentation (<a href="api-notes-macosx.html">Notes on supported APIs and classes on MacOS X</a> for
+Cocoa on MacOS X).</p>
+<p>One group of exceptions to this rule can be described in a global way. Some
+methods and functions have pointers as arguments, specifically pointers to
+a single value that is passed in and/or out of the function. These arguments
+are sometimes called <i>pass by reference</i> arguments, and can be subdived into
+three types of arguments: <code><span>in</span></code> arguments are used to pass data to the 
+function, <code><span>out</span></code> arguments are used to pass data from the function (e.g. and
+additional return value) and <code><span>inout</span></code> arguments are a combination of the two.</p>
+<p>The <code><span>in</span></code> and <code><span>inout</span></code> arguments for a method are also present in the Python
+interface for that method (or function). In python the value passed to the
+function is a &quot;normal&quot; argument. <code><span>Out</span></code> arguments are not present in the 
+argument list of the Python function.</p>
+<p>If a function (or method) has one or more output arguments (<code><span>out</span></code> or 
+<code><span>inout</span></code>) the output values are returned as part of the return value of the
+method. That is, the return value of the function is a tuple containing
+the return value of the C function (or method), followed by the values of
+the <code><span>out</span></code> in <code><span>inout</span></code> arguments in the order the are present in the argument
+list. If the C function (or method) has return type <code><span>void</span></code>, the tuple contains
+only the output arguments. As a final complication, methods with a single output
+argument and return type <code><span>void</span></code>, have the value of the output argument as
+the return value (e.g. not a tuple containing the return value).</p>
+<p>The rules for pass by reference arguments may look quite complicated, but
+it turns out this is very straightforward when working with them.</p>
+<p>As an example of a method with two output arguments, NSMatrix has a method
+named <code><span>getNumberOfRows_columns_</span></code> with the following signature:</p>
+<pre>
+(void)getNumberOfRows:(int *)rowCount columns:(int *)columnCount
+</pre>
+<p>You use this method in python like this:</p>
+<pre>
+rowCount, columnCount = matrix.getNumberOfRows_columns_()
+</pre>
+<p>When you define methods in a subclass of an Objective-C class, the bridge has
+to tell the Objective-C runtime what the signature of those methods is. The
+basic rule is that all arguments as well as the return value are objects (just
+like with normal Python methods). The bridge will automaticly pick a better 
+signature when it has more information available. Specifically, if you 
+overide an existing method the bridge will assume you want to use the same
+method signature. And 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>The end result is that you almost never 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 call-back 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>
+<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>
 <pre>
 class MyObject (NSObject):
         def someMethod_(self, arg):
 
         someMethod_ = objc.selector(someMethod_, ...)
 </pre>
-<p>The other arguments of <code><span>objc.selector</span></code> (not shown in the example) provide
-additional information about the method to the bridge, see the online 
-documentation for more information about this function. It is almost never
-necessary to use this technique.</p>
-<p>If you write a method for an Objecitve-C class in Python, PyObjC will try to
-deduce the method's signature. If it's overriding a method, the signature of
-the method that is overridden is taken. If it's a method that appears
-<i>anywhere</i> in an informal protocol definition in a framework that's currently
-loaded, PyObjC takes the signature from there. (Most wrapped frameworks have a
-submodule named <code><span>protocols.py</span></code> that contains informal protocol definitions.)</p>
-<h2><a href="#id6" name="cocoa-for-python-programmers">Cocoa for Python programmers</a></h2>
+<h3><a href="#id9" name="reference-counts">Reference counts</a></h3>
+<p>The <a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa libraries</a>, and most (if not all) other class libraries for 
+Objective-C use explicit reference counting to manage memory. The methods
+<code><span>retain</span></code>, <code><span>release</span></code> and <code><span>autorelease</span></code> are used to manage these 
+reference counts. You won't have to manage reference counts in Python, the
+bridge does all that work for you.</p>
+<p>The only reasons reference counts are mentioned at all are to tell you about
+ignoring them, and more importantly to introduce you to some issues w.r.t. 
+reference counting.</p>
+<p>It turns out that Cocoa uses a primitive form of <a href="http://www.python.org/doc/current/lib/module-weakref.html">weak references</a>. Those 
+are not true <a href="http://www.python.org/doc/current/lib/module-weakref.html">weak references</a> as in Python, but use-cases where an object 
+stores a reference to another object without increasing the reference count
+for that other object. The bridge cannot solve the issues this introduces
+for you, which means that you get hard crashes when you're not carefull when
+dealing with those <a href="http://www.python.org/doc/current/lib/module-weakref.html">weak references</a>.</p>
+<p>The basic rule to deal with weak references is: make sure objects stays
+alive as long as someone might have a weak reference to them. Due to the way
+the bridge works, this means that you must make sure that you don't create
+weak references from Objective-C to a plain Python object. The Python
+object stays alive, but the proxy object as seen by the Objective-C code is
+actually an autoreleased object that will be cleaned up unless the Objective-C
+code increases its reference count.</p>
+<p>The document <a href="api-notes-macosx.html">Notes on supported APIs and classes on MacOS X</a> contains 
+information about classes that work with weak references. The most important
+are notification centers and <code><span>NSOutlineView</span></code>, to be exact: the outline view
+stores weak references to the objects return by the method 
+<code><span>outlineView:child:ofItem:</span></code> of its data source. The easiest way to avoid
+crashes with outline views is to make sure that you model for the view uses
+subclasses of <code><span>NSObject</span></code> to represent the nodes in the outline view.</p>
+<h2><a href="#id10" 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 functioins from the AppKit framework are available
 after you import <code><span>AppKit</span></code> in your Python script.</p>
+<p>These helper modules contain <i>only</i> functions, constants and classes that 
+wrap items in the corresponding framework. All utility functions and classes 
+are located in the <code><span>PyObjCTools</span></code> package and <code><span>objc</span></code> module.</p>
+<p>This makes it easier to find documentation for an item: if you import it 
+from the wrapper module for an Objective-C framework the documentation for
+that item can be found in the documentation for the framework, otherwise the
+item is documented in the PyObjC documentation.</p>
 <p>The module <code><span>PyObjCTools.NibClassBuilder</span></code> can be used to make working with 
 NIB files more convenient. This module can be used to extract information 
 about classes from NIB files, both as a standalone tool generating source code 
 and during runtime. See the online documentation for this module for more
 information.</p>
-<p><strong>TODO</strong>:</p>
-<ul>
-<li>Links to example PyObjC scripts.</li>
-</ul>
+<p>PyObjC includes a number of examples that show how to use Cocoa from
+Python. The <a href="../Examples/00ReadMe.html">PyObjC Example index</a> contains an overview of those examples.</p>
 <p>More information on Cocoa programming can be found at:</p>
 <ul>
 <li><a href="http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html">Cocoa documentation at the Apple developer website</a></li>
 <li><a href="http://www.stepwise.com/">stepwise.com</a></li>
 <li>Your local bookstore or library</li>
 </ul>
-<h2><a href="#id7" name="building-applications">Building applications</a></h2>
+<h2><a href="#id11" name="building-applications">Building applications</a></h2>
 <p>There are two different ways to build applications with PyObjC. There are no
 major advantages to using either one of them, use the one that is most 
 convenient to you.</p>
-<h3><a href="#id8" name="pure-python-buildapp-py">&quot;Pure Python&quot; :  buildapp.py</a></h3>
+<h3><a href="#id12" name="pure-python-buildapp-py">&quot;Pure Python&quot; :  buildapp.py</a></h3>
 <p>PyObjC includes a copy of the <code><span>bundlebuilder</span></code> module. This module will be
 part of the Python 2.3 MacPython release and offers a way to build
 distutils-style scripts  for building (standalone) applications.</p>
 incompatible Python version.</p>
 <p>The online documentation for <code><span>bundlebuilder</span></code> contains more information on 
 building <code><span>buildapp.py</span></code> scripts and how to invoke them. There are plenty of
-example <code><span>buildapp.py</span></code> scripts in the various <a href="../Examples">Examples</a> subfolders.</p>
-<h3><a href="#id9" name="ide-approach-project-builder">&quot;IDE approach&quot; : Project builder</a></h3>
+example <code><span>buildapp.py</span></code> scripts in the various <a href="../Examples/00ReadMe.txt">Examples</a> subfolders.</p>
+<h3><a href="#id13" name="ide-approach-project-builder">&quot;IDE approach&quot; : Project builder</a></h3>
 <p>PyObjC includes a number of Project Builder templates that can be used to 
-build (standalone) applications.</p>
-<p><strong>TODO</strong>:</p>
-<ul>
-<li>Expand this section, input needed as I don't use Project Builder</li>
-<li>Add link to documentation about our templates</li>
-<li>Add link to documentation for Project Builder</li>
-</ul>
+build (standalone) applications. Those templates are used like any other
+Project Builder template. The only non-obvious detail is that you have to
+add your sources as resources, but Project Builder usually does the right
+thing when you add a new file.</p>
+<p>The templates will build an application that makes use of the installed copy
+<code><span>/usr/bin/python</span></code> (e.g. the one shipped by Apple in MacOS X 10.2) and will 
+copy the PyObjC modules into the application bundle. This means that this 
+application bundle should be useable on any MacOS X 10.2 system.</p>
+<p>See <a href="ProjectBuilder-Templates.html">the documentation for the templates</a> for more details.</p>
+<p>XXX: But what about Panther, which seems to ship with Python 2.3, at the 
+very least you'll get warnings about the PyObjC extension modules (wrong 
+ABI version).</p>
+<p>XXX: The documentation for the templates should be installed into the 
+documentation folder on the DMG, otherwise the link above won't work, I've
+hacked <code><span>Scripts/update_html.py</span></code> to copy the HTML file to the Doc directory,
+but that is not a pretty solution.</p>
 </body>
 </html>

pyobjc/Doc/intro.txt

 WORK IN PROGRESS
 ----------------
 
-This document is work in progress and thin on details.
+This document is work in progress.
 
 
 Preface
 Overview of the bridge
 ----------------------
 
+Classes
+.......
+
 Objective-C classes are visible as Python classes and can be subclassed just
 like normal Python classes. The major differences between normal Python classes
 and Objective-C classes are the way you create instances and the fact that 
-Objective-C classes have odd names.
+Objective-C methods have odd names.
+
+Another thing to keep in mind is that the names of Objective-C classes must
+be unique, without taking modules into account. That is, it is *not* possible
+to have two modules that define a class with the same name. If you write classes
+that will be used outside of a single project it is customary to pick a 
+(short) prefix and stick that in front of all class names, e.g. Apple ``NS`` 
+as the prefix in the `Cocoa libraries`_.
 
 As described in `Objective-C for PyObjC users`_ the creation of Objective-C 
 objects is a two-stage process. You first call the class method ``alloc``, and
 created object is the result of the call to ``init``. Most classes have 
 convienence class methods that combine the calls to ``alloc`` and ``init``.
 
+Methods and functions
+.....................
+
 Objective-C methods are bridged to Python callables. Because Objective-C method 
 names can contain colons it is necessary to translate methods names. The rules
 for translation are:
 
 * Then convert all colons to underscores: ``someMethod_withFoo_andBar_``
 
-The bridged method usually has the same number of arguments as the orginal 
-method and also returns the same as the original method. In special 
-circumstances the method interface may be different from the Objective-C 
-interface, those methods are document in 'some other document'. Furthermore,
-some methods have pass-by-reference arguments (that is a pointer to a single
-value that is used to transfer data to (in), from (out) or to-and-from (inout)
-the method. The arguments that are passed to methods is present as normal 
-arguments in the bridged method (e.g. if the method has an ``int*`` argument
-the bridged method has has an integer argument).  Data that is passed from the
-function results in additional return values from the function.
+Wrapped/bridged methods (and functions) have the same number of arguments
+as the corresponding Objective-C method or function, unless otherwise noted
+in the documentation (`Notes on supported APIs and classes on MacOS X`_ for
+Cocoa on MacOS X).
 
-When the bridge cannot automaticly deduce the right signature for a method, or
-if you want to add a method whose name cannot be transformed into Python (
-for example a methodname containing ``$``), you'll have to add explicit hints
-to your code. You do this by calling the function ``objc.selector`` and using
-the result instead of your method definition::
+.. _`Notes on supported APIs and classes on MacOS X`: api-notes-macosx.html
+
+One group of exceptions to this rule can be described in a global way. Some
+methods and functions have pointers as arguments, specifically pointers to
+a single value that is passed in and/or out of the function. These arguments
+are sometimes called *pass by reference* arguments, and can be subdived into
+three types of arguments: ``in`` arguments are used to pass data to the 
+function, ``out`` arguments are used to pass data from the function (e.g. and
+additional return value) and ``inout`` arguments are a combination of the two.
+
+The ``in`` and ``inout`` arguments for a method are also present in the Python
+interface for that method (or function). In python the value passed to the
+function is a "normal" argument. ``Out`` arguments are not present in the 
+argument list of the Python function.
+
+If a function (or method) has one or more output arguments (``out`` or 
+``inout``) the output values are returned as part of the return value of the
+method. That is, the return value of the function is a tuple containing
+the return value of the C function (or method), followed by the values of
+the ``out`` in ``inout`` arguments in the order the are present in the argument
+list. If the C function (or method) has return type ``void``, the tuple contains
+only the output arguments. As a final complication, methods with a single output
+argument and return type ``void``, have the value of the output argument as
+the return value (e.g. not a tuple containing the return value). 
+
+The rules for pass by reference arguments may look quite complicated, but
+it turns out this is very straightforward when working with them.
+
+As an example of a method with two output arguments, NSMatrix has a method
+named ``getNumberOfRows_columns_`` with the following signature::
+
+   (void)getNumberOfRows:(int *)rowCount columns:(int *)columnCount
+
+You use this method in python like this::
+
+   rowCount, columnCount = matrix.getNumberOfRows_columns_()
+
+When you define methods in a subclass of an Objective-C class, the bridge has
+to tell the Objective-C runtime what the signature of those methods is. The
+basic rule is that all arguments as well as the return value are objects (just
+like with normal Python methods). The bridge will automaticly pick a better 
+signature when it has more information available. Specifically, if you 
+overide an existing method the bridge will assume you want to use the same
+method signature. And 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.
+
+The end result is that you almost never 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 call-back 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).
+
+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::
 
 	class MyObject (NSObject):
 		def someMethod_(self, arg):
 
 		someMethod_ = objc.selector(someMethod_, ...)
 
-The other arguments of ``objc.selector`` (not shown in the example) provide
-additional information about the method to the bridge, see the online 
-documentation for more information about this function. It is almost never
-necessary to use this technique.
+Reference counts
+................
 
-If you write a method for an Objecitve-C class in Python, PyObjC will try to
-deduce the method's signature. If it's overriding a method, the signature of
-the method that is overridden is taken. If it's a method that appears
-*anywhere* in an informal protocol definition in a framework that's currently
-loaded, PyObjC takes the signature from there. (Most wrapped frameworks have a
-submodule named ``protocols.py`` that contains informal protocol definitions.)
+The `Cocoa libraries`_, and most (if not all) other class libraries for 
+Objective-C use explicit reference counting to manage memory. The methods
+``retain``, ``release`` and ``autorelease`` are used to manage these 
+reference counts. You won't have to manage reference counts in Python, the
+bridge does all that work for you.
+
+The only reasons reference counts are mentioned at all are to tell you about
+ignoring them, and more importantly to introduce you to some issues w.r.t. 
+reference counting.
+
+It turns out that Cocoa uses a primitive form of `weak references`_. Those 
+are not true `weak references`_ as in Python, but use-cases where an object 
+stores a reference to another object without increasing the reference count
+for that other object. The bridge cannot solve the issues this introduces
+for you, which means that you get hard crashes when you're not carefull when
+dealing with those `weak references`_.
+
+.. _`weak references`: http://www.python.org/doc/current/lib/module-weakref.html
+
+The basic rule to deal with weak references is: make sure objects stays
+alive as long as someone might have a weak reference to them. Due to the way
+the bridge works, this means that you must make sure that you don't create
+weak references from Objective-C to a plain Python object. The Python
+object stays alive, but the proxy object as seen by the Objective-C code is
+actually an autoreleased object that will be cleaned up unless the Objective-C
+code increases its reference count.
+
+The document `Notes on supported APIs and classes on MacOS X`_ contains 
+information about classes that work with weak references. The most important
+are notification centers and ``NSOutlineView``, to be exact: the outline view
+stores weak references to the objects return by the method 
+``outlineView:child:ofItem:`` of its data source. The easiest way to avoid
+crashes with outline views is to make sure that you model for the view uses
+subclasses of ``NSObject`` to represent the nodes in the outline view.
 
 
 Cocoa for Python programmers
 
 Cocoa frameworks are mapped onto Python packages with the same name, that is
 the classes, constants and functioins from the AppKit framework are available
-after you import ``AppKit`` in your Python script.
+after you import ``AppKit`` in your Python script. 
+
+These helper modules contain *only* functions, constants and classes that 
+wrap items in the corresponding framework. All utility functions and classes 
+are located in the ``PyObjCTools`` package and ``objc`` module. 
+
+This makes it easier to find documentation for an item: if you import it 
+from the wrapper module for an Objective-C framework the documentation for
+that item can be found in the documentation for the framework, otherwise the
+item is documented in the PyObjC documentation.
 
 The module ``PyObjCTools.NibClassBuilder`` can be used to make working with 
 NIB files more convenient. This module can be used to extract information 
 and during runtime. See the online documentation for this module for more
 information.
 
-**TODO**:
-
-* Links to example PyObjC scripts.
-
+PyObjC includes a number of examples that show how to use Cocoa from
+Python. The `PyObjC Example index`_ contains an overview of those examples.
 
 More information on Cocoa programming can be found at:
 
 
 * Your local bookstore or library
 
+.. _`PyObjC Example index`: ../Examples/00ReadMe.html
+
 ..  _`Cocoa libraries`: http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html
 
 ..  _`Cocoa documentation at the Apple developer website`: http://developer.apple.com/techpubs/macosx/Cocoa/CocoaTopics.html
 building ``buildapp.py`` scripts and how to invoke them. There are plenty of
 example ``buildapp.py`` scripts in the various `Examples`__ subfolders.
 
-.. __: ../Examples
+.. __: ../Examples/00ReadMe.txt
 
 
 "IDE approach" : Project builder
 ................................
 
 PyObjC includes a number of Project Builder templates that can be used to 
-build (standalone) applications.
+build (standalone) applications. Those templates are used like any other
+Project Builder template. The only non-obvious detail is that you have to
+add your sources as resources, but Project Builder usually does the right
+thing when you add a new file.
 
-**TODO**:
+The templates will build an application that makes use of the installed copy
+``/usr/bin/python`` (e.g. the one shipped by Apple in MacOS X 10.2) and will 
+copy the PyObjC modules into the application bundle. This means that this 
+application bundle should be useable on any MacOS X 10.2 system.
 
-* Expand this section, input needed as I don't use Project Builder
+See `the documentation for the templates`__ for more details.
 
-* Add link to documentation about our templates
+.. __: ProjectBuilder-Templates.html
 
-* Add link to documentation for Project Builder
+XXX: But what about Panther, which seems to ship with Python 2.3, at the 
+very least you'll get warnings about the PyObjC extension modules (wrong 
+ABI version).
+
+XXX: The documentation for the templates should be installed into the 
+documentation folder on the DMG, otherwise the link above won't work, I've
+hacked ``Scripts/update_html.py`` to copy the HTML file to the Doc directory,
+but that is not a pretty solution.

pyobjc/Doc/wrapping.html

 The following code tells the brigde about this better method signature:</p>
 <pre>
 import objc
-objc.set_signature_for_selector(&quot;ClassName&quot;, &quot;selector:withArguments:&quot;,
+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

pyobjc/ProjectBuilder Extras/Project Templates/00README.txt

 default Cocoa Document-based Application supplied with Project Builder.
 
 Cocoa-Python-ObjC Document-based Application
------------------------------
+--------------------------------------------
 
 A project created from this template includes an embedded framework project
 into which all compiled code can be placed.  Upon launch, the application

pyobjc/Scripts/update_html.py

 
 print "Generateing HTML documentation"
 os.path.walk('Doc', rest2HTML, ['Doc/announcement.txt'])
-rest2HTML(None, '.', ['Install.txt', 'ReadMe.txt', 'Examples/00ReadMe.txt', 'Installer Package/ReadMe.txt'])
+rest2HTML(None, '.', ['Install.txt', 'ReadMe.txt', 'Examples/00ReadMe.txt', 'Installer Package/ReadMe.txt', 'ProjectBuilder Extras/Project Templates/00README.txt'], )
+os.rename('ProjectBuilder Extras/Project Templates/00README.html', 'Doc/ProjectBuilder-Templates.html')