[Checkins] SVN: grok/trunk/doc/tutorial.rst Note about previous libraries conflicting with grok and ways to fix it.

[Martijn Faassen]

Log message for revision 93843:
  Note about previous libraries conflicting with grok and ways to fix it.
  
  https://bugs.launchpad.net/grok/+bug/125465
  

Changed:
  U   grok/trunk/doc/tutorial.rst

-=-
Modified: grok/trunk/doc/tutorial.rst
===================================================================
--- grok/trunk/doc/tutorial.rst	2008-12-10 13:32:00 UTC (rev 93842)
+++ grok/trunk/doc/tutorial.rst	2008-12-10 13:34:21 UTC (rev 93843)
@@ -119,7 +119,7 @@
 
   $ paster create -t grok Sample
 
-.. _paster: http://pythonpaste.org/script/
+  .. _paster: http://pythonpaste.org/script/
 
 Let's create a first Grok project. A Grok project is a working
 environment for a developer using Grok. In essence, a directory with a
@@ -151,6 +151,28 @@
 
 After all that, Grok, along with a Zope 3 instance, is ready to go. 
 
+.. sidebar:: Common problems installing Grok
+
+  One common problem when installing Grok is library mixup. You may
+  have some libraries installed in your Python interpreter that
+  conflict with libraries that Grok wants to install. If you already
+  have installed Zope 3 previously for instance, you may first have
+  to remove it from your Python's ``site-packages`` directory. 
+ 
+  Another way to make sure Grok doesn't clash with any incompatible
+  libraries is to install and run grokproject from within a
+  virtualenv_, with the ``--no-site-packages`` option enabled. See
+  also `Using Virtualenv for a clean Grok installation`_.
+
+  Modern versions of Mac OS X install Twisted, which in turn has a
+  non-compatible version of ``zope.interface`` as a dependency. This
+  means that the virtualenv option is always recommended on Mac OS X,
+  unless you install a separate version of Python.
+
+  .. _virtualenv: http://pypi.python.org/pypi/virtualenv
+
+  .. _`Using Virtualenv for a clean Grok installation`:  http://grok.zope.org/documentation/how-to/using-virtualenv-for-a-clean-grok-installation
+
 Starting up Zope
 ----------------