[Checkins] SVN: grok/trunk/doc/upgrade.txt Updating the ugprade documentation a bit.

[Martijn Faassen]

Log message for revision 103917:
  Updating the ugprade documentation a bit.
  

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

-=-
Modified: grok/trunk/doc/upgrade.txt
===================================================================
--- grok/trunk/doc/upgrade.txt	2009-09-14 12:16:41 UTC (rev 103916)
+++ grok/trunk/doc/upgrade.txt	2009-09-14 12:46:39 UTC (rev 103917)
@@ -13,43 +13,62 @@
 Upgrading to 1.0b1 (not released)
 ----------------------------------
 
-* The View class (from either grokcore.view or grok itself) has been splitted
-  in to View and CodeView.  If you have a template: use View.  If you have a
-  render method: you must subclass from CodeView instead of View from now on.
+* The ``View`` class (from either grokcore.view or grok itself) has
+  been split into ``View`` and ``CodeView``. ``CodeView`` is only for
+  use with a ``render`` method, and ``View`` is only for templates.
+  
+  If you have a template: use ``View``.  If you have a render method:
+  you must subclass from ``CodeView`` instead of ``View`` from now on.
 
-* The default permission is now grok.View as a replacement for zope.Public.
-  You need to add this permission as a default permission to all
-  users (use zope.Anybody). This requires a change to site.zcml as follows.
+* The default permission is now ``grok.View`` as a replacement for
+  ``zope.Public``.  You need to add this permission as a default
+  permission to all users (use ``zope.Anybody``). This requires a
+  change to ``site.zcml`` as follows::
 
       <grant permission="grok.View"
              principal="zope.Anybody" />
 
-  IF YOU DO NOT MAKE THIS CHANGE, ALL OF YOUR VIEWS WILL BE UNAVAILBLE FOR
-  ANONYMOUS.
+  **If you do not make this change, all of your views will be
+  unavailable for anonymous and the system will ask the user for a
+  password.**
 
-* Grok buildout now creates a paster based project, as grokproject
-  does for some time. It should be possible to update your checkout and
-  run buildout again to switch to the new layout.
+  This change allows you to protect Grok views that come with the
+  default permission by modifying your ``site.zcml``.
 
-* Be careful with the files in 'parts/app' and 'parts/zopectl', esp.
-  'parts/zopectl/access.log' as both folders are deleted.
+* Grok buildout now creates a paster based project. To switch over
+  your projects to this approach, upgrade grokproject (``easy_install
+  -U grokproject``) first and create an empty project. Then examine
+  ``setup.py`` and ``buildout.cfg`` and copy over the files in ``etc``
+  (and adjust them).
 
-* Logfiles are now in 'parts/log', config files are now in 'parts/etc'.
-  Both access and event logs are file-based.
-  Find more information on configuration and settings in 'etc/README.txt'.
+  Please note that ``parts/zopectl`` and ``parts/app`` will be deleted
+  when you re-run buildout. This means that ``parts/zopectl/access.log``
+  will be removed, and you may want to back up this file in advance.
 
-* Start the instance now like:
-    'bin/paster serve parts/etc/deploy.ini'
-  or
-    'bin/projectname-ctl fg'
+  The templates for config files are now in ``etc`` - these get
+  generated by buildout into ``parts/etc``. Logfiles are now in
+  ``parts/log``.
 
-  If you start your instance with 'debug.ini' first point your browser to
-    'http://localhost:8080/@@login.html' and authenticate. This will ev.
-  be removed in a later release.
+  Find more information on configuration and settings in
+  ``etc/README.txt``.
 
-* Interpreter name has been changed from 'bin/python' to 'bin/grokpy' to
-  avoid conflicts with 'virtualenv'.
+  After making these adjustments, you can now run ``buildout`` for the
+  project.
 
+  Start the instance now like::
+
+    bin/paster serve parts/etc/deploy.ini
+  
+  or with::
+
+    bin/projectname-ctl fg
+
+  If you start your instance with ``etc/debug.ini`` first point your
+  browser.
+
+  Interpreter name has been changed from ``bin/python`` to
+  ``bin/grokpy`` to avoid conflicts with virtualenv.
+
 .. _upgrade_notes_1.0a1:
 
 Upgrading to 1.0a1