Commits

Bob Ippolito committed d148839

More documentation updates, almost there I think

Comments (0)

Files changed (11)

pyobjc/Doc/ProjectBuilder-SyntaxHighlighting.html

 both the user defaults and within project files.</p>
 </td></tr></tbody></table></td></tr></tbody></table><h2>Contents</h2>
 <ul>
-<li><a href="#installation" id="id2" name="id2">Installation</a></li>
-<li><a href="#documentation" id="id3" name="id3">Documentation</a></li>
-<li><a href="#to-do" id="id4" name="id4">To Do</a></li>
-<li><a href="#misc" id="id5" name="id5">Misc.</a></li>
+<li><a href="#installation" id="id1" name="id1">Installation</a></li>
+<li><a href="#documentation" id="id2" name="id2">Documentation</a></li>
+<li><a href="#to-do" id="id3" name="id3">To Do</a></li>
 </ul>
 <p>Triple-quoted strings are not always treated correctly by Project Builder. This
 seems to be a Project Builder bug.</p>
-<h2><a href="#id2" name="installation">Installation</a></h2>
+<h2><a href="#id1" name="installation">Installation</a></h2>
 <p>Create the directory 'Specifications' within
 <i>~/Developer/ProjectBuilder Extras/</i> or <i>/Developer/ProjectBuilder
 Extras/</i>:</p>
 cp Python.pb*spec ~/Developer/ProjectBuilder\ Extras/Specifications/
 </pre>
 <p>The binary installer will install the specifications for you.</p>
-<h2><a href="#id3" name="documentation">Documentation</a></h2>
+<h2><a href="#id2" name="documentation">Documentation</a></h2>
 <p>The version of Project Builder that ships with the December Developer Tools
 modularizes the support for file types and syntax based colorizing of
 source files.  The base mechanisms and definitions are found in:</p>
  'while',
  'yield']
 </pre>
-<h2><a href="#id4" name="to-do">To Do</a></h2>
+<h2><a href="#id3" name="to-do">To Do</a></h2>
 <ul>
+<li>NOTE: PyObjC's Project Builder support is unmaintained.  It is unlikely that
+any of these items will ever be completed.</li>
 <li>There are a number of other specification files found within the PBXCore.  Of
 particular relevance to Python would be the Compiler Specifications.  It
 would be extremely handy to be able to check syntax and compile Python code
 that turns Python source into .class files.   All of this assumes that
 Python and Jython source can (and should?) be differentiated.</li>
 </ul>
-<h2><a href="#id5" name="misc">Misc.</a></h2>
-<p>This README is formatted as <a href="http://docutils.sourceforge.net/docs/rst/quickstart.html">reStructuredText</a> input.  From it, the HTML and other
-formats can be automatically generated with the <a href="http://docutils.sourceforge.net/">docutils tools</a>.</p>
 </body>
 </html>

pyobjc/Doc/ProjectBuilder-SyntaxHighlighting.txt

 To Do
 -----
 
+- NOTE: PyObjC's Project Builder support is unmaintained.  It is unlikely that
+  any of these items will ever be completed.
+
 - There are a number of other specification files found within the PBXCore.  Of
   particular relevance to Python would be the Compiler Specifications.  It
   would be extremely handy to be able to check syntax and compile Python code
   that turns Python source into .class files.   All of this assumes that
   Python and Jython source can (and should?) be differentiated.
 
-Misc.
------
-
-This README is formatted as reStructuredText_ input.  From it, the HTML and other
-formats can be automatically generated with the `docutils tools`__.
-
-.. _reStructuredText: http://docutils.sourceforge.net/docs/rst/quickstart.html
-.. __: http://docutils.sourceforge.net/
 .. _PyChecker: http://pychecker.sourceforge.net/

pyobjc/Doc/ProjectBuilder-Templates.html

 </ul>
 <h2><a href="#id2" name="notes">Notes</a></h2>
 <ul>
+<li>PyObjC's Project Builder support is unmaintained and its use for new projects
+is not recommended.</li>
 <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>
 from Foundation import *
 </pre>
 </li>
-<li>There is risk that the pyobjc modules compiled for one version of python
+<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
+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>

pyobjc/Doc/Xcode-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@mac.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@mac.com">bbum@mac.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="id1" name="id1">Notes</a></li>
+<li><a href="#cocoa-python-templates" id="id2" name="id2">Cocoa-Python Templates</a></li>
+<li><a href="#cocoa-python-application" id="id3" name="id3">Cocoa-Python Application</a></li>
+</ul>
+<h2><a href="#id1" 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="#id2" name="cocoa-python-templates">Cocoa-Python Templates</a></h2>
+<p>The Cocoa-Python templates all create various different kinds of Cocoa
+application projects.  Be sure and pick the correct project type for your
+needs.</p>
+<h2><a href="#id3" 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.3 system
+without requiring PyObjC to be preinstalled.</p>
+</body>
+</html>

pyobjc/Doc/index.html

 </li>
 <li><a href="structure.html">Structure of the PyObjC package</a><p>An overview of the implementation of PyObjC.</p>
 </li>
-<li>Xcode Python Support<p>XXX - TODO</p>
+<li><a href="Xcode-Templates.html">Xcode Python templates</a><p>Describes the PyObjC Xcode templates.</p>
 </li>
-<li><a href="ProjectBuilder-SyntaxHighlighting.html">Project Builder Python Support</a><p>Describes the Python support for Project Builder, including a TODO list for
-future versions.</p>
+<li><a href="ProjectBuilder-Templates.html">Project Builder Python templates</a><p>Describes the PyObjC Project Builder templates.</p>
+</li>
+<li><a href="ProjectBuilder-SyntaxHighlighting.html">Project Builder Python syntax highlighting</a><p>Describes the Project Builder syntax highlighting for Python.</p>
 </li>
 </ul>
 </body>

pyobjc/Doc/index.txt

 
   An overview of the implementation of PyObjC.
 
-* Xcode Python Support
+* `Xcode Python templates`_
 
-  XXX - TODO
+  Describes the PyObjC Xcode templates.
 
-* `Project Builder Python Support`_
+* `Project Builder Python templates`_
 
-  Describes the Python support for Project Builder, including a TODO list for
-  future versions.
+  Describes the PyObjC Project Builder templates.
 
+* `Project Builder Python syntax highlighting`_
 
-.. _`Project Builder Python Support`: ProjectBuilder-SyntaxHighlighting.html
+  Describes the Project Builder syntax highlighting for Python.
+
+.. _`Xcode Python templates`: Xcode-Templates.html
+
+.. _`Project Builder Python syntax highlighting`: ProjectBuilder-SyntaxHighlighting.html
+
+.. _`Project Builder Python templates`: ProjectBuilder-Templates.html
 
 .. _`An introduction to PyObjC`: intro.html
 

pyobjc/Doc/intro.html

 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
-Smalltalk-like extensions for the Object-Oriented parts of the language.  An
+Smalltalk-like extensions for the object-oriented parts of the language.  An
 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 similarly
 anArray.indexOfObject_inRange_(someObject, someRange)
 </pre>
 <p>This may be awkward and &quot;unpythonic&quot; at first, however this syntax is necessary
-preserve the semantics of Objective-C message dispatch.</p>
+to preserve the semantics of Objective-C message dispatch.</p>
 <p>A class declaration:</p>
 <pre>
 @interface MyClass : MySuperClass
 same name.  It is conventional to choose class names with a short prefix that
 uniquely identify your project or company.  For example, Apple uses <code><span>NS</span></code>
 as the prefix for all classes in the <a href="http://developer.apple.com/referencelibrary/API_Fundamentals/Cocoa-api-date.html">Cocoa libraries</a>.  Note that the <code><span>NS</span></code>
-prefix made much more sense when it was called NeXTStep, but persists to this
+prefix made much more sense when it was called NeXTstep, but persists to this
 day for compatibility reasons.</p>
 <p>As described in <a href="#objective-c-for-pyobjc-users">Objective-C for PyObjC users</a> the creation of Objective-C 
 objects is a two-stage process.  To initialize objects, you first call a
 <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>
-<p>Another gotcha is when you're manually allocating and assigning delegate(-like)
-objects: most of the time <code><span>obj.setDelegate_()</span></code> will <i>not</i> retain the 
-delegate, so you must keep a reference manually.</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>
 <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 NSTableView.</p>
+such as the data source for an <code><span>NSTableView</span></code>.</p>
 <p>Those protocols are represented by instances of <code><span>objc.informal_protocol</span></code>. The
 only ones that have to care about these objects are the maintainers of 
 wrappers around Objective-C frameworks: they have to keep these protocol
 expectations of Cocoa Bindings.</p>
 <h3><a href="#id12" 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 seperate compilation unit and even
-a seperate library. This mechanism is named categories and is used to enhance
+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
 existing classes, for splitting classes in several parts and to document
 informal protocols.</p>
 <p>An example of a category definition:</p>

pyobjc/Doc/intro.txt

 latter is done by instance methods whose name customarily starts with ``init``.
 
 Objective-C code looks just like plain C code, with some easily recognizable
-Smalltalk-like extensions for the Object-Oriented parts of the language.  An
+Smalltalk-like extensions for the object-oriented parts of the language.  An
 example class declaration (usually found in ``.h`` files) and implementation
 (usually found in ``.m`` files) are listed below.  Class declarations are easily
 recognized as blocks of code between ``@interface`` and ``@end``, and similarly
     anArray.indexOfObject_inRange_(someObject, someRange)
     
 This may be awkward and "unpythonic" at first, however this syntax is necessary
-preserve the semantics of Objective-C message dispatch.
+to preserve the semantics of Objective-C message dispatch.
 
 A class declaration::
 
 same name.  It is conventional to choose class names with a short prefix that
 uniquely identify your project or company.  For example, Apple uses ``NS``
 as the prefix for all classes in the `Cocoa libraries`_.  Note that the ``NS``
-prefix made much more sense when it was called NeXTStep, but persists to this
+prefix made much more sense when it was called NeXTstep, but persists to this
 day for compatibility reasons.
 
 As described in `Objective-C for PyObjC users`_ the creation of Objective-C 
 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.
 
-Another gotcha is when you're manually allocating and assigning delegate(-like)
-objects: most of the time ``obj.setDelegate_()`` will *not* retain the 
-delegate, so you must keep a reference manually.
+Another gotcha is that ``obj.setDelegate_()`` often does *not* retain the
+delegate, so a reference should be maintained elsewhere.
 
 (Informal) protocols
 ....................
 
 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 NSTableView.
+such as the data source for an ``NSTableView``.
 
 Those protocols are represented by instances of ``objc.informal_protocol``. The
 only ones that have to care about these objects are the maintainers of 
 ..........
 
 Objective-C has a mechanism for modularize a class definition, it is possible
-to add methods to an existing class in a seperate compilation unit and even
-a seperate library. This mechanism is named categories and is used to enhance
+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
 existing classes, for splitting classes in several parts and to document
 informal protocols.
 

pyobjc/Installer Package/10.4/ReadMe.html

 and examples are found in  the folder <code><span>PyObjC</span> <span>Documentation</span> <span>and</span> <span>Examples</span></code>. 
 Install these by dragging this folder to you disk, <code><span>/Library/Documentation</span></code>
 is a suitable location.</p>
-<p>NOTE: This installer package is for MacOS X 10.3. There is a seperate installer
-for MacOS X 10.2 with the Python 2.2 supplied by Apple. If you use 
-MacPython 2.3 on MacOS X 10.2 you should use the <code><span>Package</span> <span>Manager</span></code> 
+<p>NOTE: This installer package is for Mac OS X 10.3. There is a seperate installer
+for Mac OS X 10.2 with the Python 2.2 supplied by Apple. If you use 
+MacPython 2.3 on Mac OS X 10.2 you should use the <code><span>Package</span> <span>Manager</span></code> 
 application to install PyObjC. In other situation you can install PyObjC from 
 the source archive.</p>
 </body>

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

 Notes
 -----
 
+- PyObjC's Project Builder support is unmaintained and its use for new projects
+  is not recommended.
+
 - 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
   ``loadBundle()`` function in the ``objc`` module::
 
     from Foundation import *
 
-- There is risk that the pyobjc modules compiled for one version of python
+- 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
+  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.
 

pyobjc/setup-lib/build_html.py

             print "*** Can't generate HTML, docarticle.py is missing"
             return
         os.path.walk('Doc', rest2HTML, ['Doc/announcement.txt'])
-        rest2HTML(None, '.', ['Install.txt', 'ReadMe.txt', 'Examples/00ReadMe.txt', 'Installer Package/10.2/ReadMe.txt', 'Installer Package/10.3/ReadMe.txt', 'ProjectBuilder Extras/Project Templates/00README.txt', 'NEWS.txt'])
+        rest2HTML(None, '.', [
+            'NEWS.txt', 'Install.txt', 'ReadMe.txt', 'Examples/00ReadMe.txt',
+            'Installer Package/10.2/ReadMe.txt',
+            'Installer Package/10.3/ReadMe.txt',
+            'Installer Package/10.4/ReadMe.txt',
+            'ProjectBuilder Extras/Project Templates/00README.txt',
+            'Xcode/Project Templates/00README.txt',
+        ])
         if os.path.exists('ProjectBuilder Extras/Project Templates/00README.html'):
                 os.rename('ProjectBuilder Extras/Project Templates/00README.html', 'Doc/ProjectBuilder-Templates.html')
+        if os.path.exists('Xcode/Project Templates/00README.html'):
+                os.rename('Xcode/Project Templates/00README.html', 'Doc/Xcode-Templates.html')
 
 cmdclass = dict(build_html=build_html)
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.