[Checkins] SVN: grok/trunk/ Reflect the latest changes in Martian in the upgrade notes.

[Martijn Faassen]

Log message for revision 87667:
  Reflect the latest changes in Martian in the upgrade notes.
  

Changed:
  U   grok/trunk/CHANGES.txt
  U   grok/trunk/doc/upgrade.txt

-=-
Modified: grok/trunk/CHANGES.txt
===================================================================
--- grok/trunk/CHANGES.txt	2008-06-23 07:48:29 UTC (rev 87666)
+++ grok/trunk/CHANGES.txt	2008-06-23 14:00:43 UTC (rev 87667)
@@ -19,7 +19,8 @@
 
 * Refactored class grokkers to make use of Martian's new declarative
   way for retrieving directive data from classes, and Martian's new
-  declarative way to write grokkers.
+  declarative way to write grokkers. See the `upgrade notes`_
+  (``doc/upgrade.txt``) for more information.
 
 Feature changes
 ---------------

Modified: grok/trunk/doc/upgrade.txt
===================================================================
--- grok/trunk/doc/upgrade.txt	2008-06-23 07:48:29 UTC (rev 87666)
+++ grok/trunk/doc/upgrade.txt	2008-06-23 14:00:43 UTC (rev 87667)
@@ -56,12 +56,10 @@
         return list(zope.interface.implementedBy(factory))[0]
 
     class RobotGrokker(martian.ClassGrokker):
-        component_class = Robot
-        directives = [
-            grok.name.bind(name='robot_name'),
-            grok.title.bind(default='A Robot'),
-            grok.provides.bind(get_default=default_provides),
-            ]
+        martian.component(Robot)
+        martian.directive(grok.name, name='robot_name')
+        martian.directive(grok.title, default='A Robot')
+        martian.directive(grok.provides, get_default=default_provides)
 
         def execute(self, factory, config, robot_name, title, provides, **kw):
             config.action(
@@ -71,13 +69,14 @@
                 )
             return True
 
-  Basically, all you need to do is provide a list of *bound*
-  directives in the grokker class and then implement the ``execute``
+  What you need to do is provide the directives in the grokker class
+  using ``martian.directive`` and then implement the ``execute``
   method which will get the class (``factory``) and the configuration
   context (``config``) as positional arguments and then the values of
-  the directives as keyword parameters.  Note that when binding the
-  directives, you may
+  the directives as keyword parameters.
 
+  Note that when using ``martian.directive``, you may
+
   - set the name of the keyword parameter if you want it to be
     different than the directive's name,
 
@@ -87,12 +86,25 @@
   - pass in a factory for a computed default value (``get_default``).
 
   If you need still need to manually retrieve directive values from an
-  object (a class, an instance or a module), you can do so by using
-  the ``get`` method of the bound directive, e.g.::
+  object (a class, an instance or a module), you can do so by
+  explicitly calling ``bind`` on the directive (which accepts the same
+  optional parameters as ``martian.directive``), and then the ``get``
+  method of the bound directive, e.g.::
 
     class_context = grok.context.bind().get(factory, module=module)
     just_module_context = grok.context.bind().get(module=module)
 
+  In most cases it's possible to avoid this though, and use the
+  ``martian.directive`` directive on the class level.
+
+  You can look at ``src/grok/meta.py`` in Grok to see examples.
+
+* Your custom grokker could previously use ``component_class`` and
+  ``priority`` as class-level variables. These have been changed to
+  the ``martian.component`` and the ``martian.priority`` directives
+  that take the value as its first argument. The new
+  ``martian.directive`` directive was introduced above.
+ 
 * Custom directives need to be re-implemented using Martian's new
   ``Directive`` base class.  The directive scope, the type of storage,
   the validator and a potential default value are all defined as
@@ -139,13 +151,16 @@
                 if not isinstance(value, type):
                     raise GrokError("%r is not a class!" % value)
 
-* We moved to newer versions of zope packages, using the KGS list for
-  Zope 3.4c1.  This means your code can now get some new deprecation
+* We moved to newer versions of zope packages. Grok's versions for
+  Zope packages are now based on the KGS list for Zope 3.4c1 (the
+  latest list).  This means your code can now get some new deprecation
   warnings for imports that have been moved. Please check your code
   and fix your imports if you get those warnings.
 
-  If you were using ``zope.publisher.http.applySkin``, you now must
-  use ``grok.util.applySkin``.
+* If you were using ``zope.publisher.http.applySkin``, you now must
+  use ``grok.util.applySkin``. This because
+  ``zope.publisher.http.appySkin`` was removed again in later versions
+  of ``zope.publisher``.
 
 Upgrading to 0.12
 -----------------