SVN: r20335 - trunk/quixote/doc

Author: akuchlin
Date: 2003-01-21 21:48:58 -0500 (Tue, 21 Jan 2003)
New Revision: 20335

Modified:
   trunk/quixote/doc/programming.txt
Log:
More rewriting; more markup fixes

Modified: trunk/quixote/doc/programming.txt
==============================================================================
--- trunk/quixote/doc/programming.txt	(original)
+++ trunk/quixote/doc/programming.txt	2003-01-21 21:48:59.000000000 -0500
@@ -341,7 +341,7 @@
 ``name``.
 
 ``request`` is the request object, as it is everywhere else; ``name`` is
-a string containing the next chunk of the path.  ``_q_getname()`` should
+a string containing the next component of the path.  ``_q_getname()`` should
 return either a string (a complete document that will be returned to the
 client) or some object that can be traversed further.  Returning a
 string is useful in simple cases, eg. if you want the ``/user/joe`` URI
@@ -411,11 +411,14 @@
 ``_q_resolve()`` is a hook that lets time-consuming imports 
 be postponed until the code is actually needed
 
-``name`` is a string containing the next chunk of the path.
+``name`` is a string containing the next component of the path.
 ``_q_resolve()`` should do whatever imports are necessary and return a
-module that will be traversed further.  (Other things can be returned,
-such as class instances or whatever, but modules are likely to be the
-most common return type.)
+module that will be traversed further.  (Nothing enforces that this
+function return a module, so you could also return other types, such
+as a class instance, a callable object, or even a string) if the last
+component of the path is being resolved.  Given ``_q_resolve()``'s
+memoization feature, though, returning a module is the most useful
+thing to do.)
 
 ``_q_resolve()`` is only ever called for names that are in
 ``_q_exports`` and that don't already exist in the containing
@@ -434,11 +437,11 @@
             from otherpackage import expensive
             return expensive
 
-Let's say this function is in ``app.ui``.  The first time /expensive
-is accessed, ``_q_resolve('expensive')`` is called, the
+Let's say this function is in ``app.ui``.  The first time
+``/expensive`` is accessed, ``_q_resolve('expensive')`` is called, the
 ``otherpackage.expensive`` module is returned and traversal continues.
 The imported module is also saved as ``app.ui.expensive``, so future
-references to /expensive won't need to invoke the ``_q_resolve()``
+references to ``/expensive`` won't need to invoke the ``_q_resolve()``
 hook.
 
 $Id$