updated mac installation instructions: better text, added the info about mac_framework_link

doc/install.txt

@@ -145,24 +145,30 @@ Mac
 - If the above required libraries are not already installed on your Mac, one option is first, to
   install `MacPorts <http://www.macports.org/>`__.
 
-- Then, in order to install one or more of the required libraries, one way is to use "port install", e.g. as follows:
+- Then, in order to install one or more of the required libraries, use "port install", e.g. as follows:
 
     .. code-block:: bash
 
-        $ sudo port install gcc44 py25-zlib py25-numpy py25-scipy mercurial python_select
+        $ sudo port install gcc44 py25-scipy mercurial python_select
 
-    Note that compiling gcc takes a significant time (hours) so it is probably
-    not the best solution if you are in a rush! It may happen that SciPy
-    fails to compile the first time and still compiles just fine on a second
-    try. Same thing with py25-zlib.
+    This will install all the required theano dependencies.  Note that
+    compiling gcc takes significant time (hours)! SciPy depends on ATLAS (a
+    good BLAS implementation) and numpy, so these will be installed for you automatically.
 
-- Please note that in order to use the MacPorts version of python, you might
+- You might have some old versions of gcc, SciPy, numpy, Python installed on
+  your system, perhaps via XCode. It is a good idea to use **either** the
+  MacPorts version of everything **or** some other set of compatible versions
+  (provided by fink, or by XCode). The advantages of MacPorts are the
+  transparency with which everything can be installed and the fact that
+  packages are updated quite frequently.
+
+- In order to use the MacPorts version of python, you might
   need to explicitly select it with ``sudo python_select python25``. The
   reason this is necessary is because you might have an Apple-provided python
   (via, for example, an XCode installation). After performing this step, you
   should check that the symbolic link provided by ``which python`` points to
   the MacPorts python. For instance, on Snow Leopard with the latest MacPorts, 
-  the output of ``which python`` is ``/opt/local/bin/python`` and the symbolic
+  the output of ``which python`` is ``/opt/local/bin/python`` and this symbolic
   link points to ``/opt/local/bin/python2.5``. When executing ``sudo
   python_select python26-apple`` (which you should **not** do), the link
   points to ``/usr/bin/python2.6``.
@@ -175,36 +181,49 @@ Mac
   is not the case, then you might have some old installation of ``scipy`` in your
   ``PYTHONPATH`` so you should edit ``PYTHONPATH`` accordingly.
 
-- The same advice applies to ``numpy``.
+- Please follow the same procedure with ``numpy``.
 
 - Put ``export PYTHONPATH=/opt/local/lib/python2.5/site-packages:$PYTHONPATH``
-  in your ``.bashrc`` in order to include your MacPorts packages in Python's
-  path.
+  in your ``.bashrc`` in order to include your MacPorts Python packages 
+  (numpy, scipy) in Python's path.
 
 - Make sure that the gcc version that you have installed on your system is
-  up-to-date. If you have an old version of XCode lying around, chances are
-  this is the case. You can check with ``which gcc``: if it says
-  ``/usr/bin/gcc`` then you should install gcc_select from MacPorts (``sudo port install
-  gcc_select``). Use ``gcc_select -l`` to see which gcc installs you have on
-  the system. Then execute ``sudo gcc_select mp-gcc44`` to create a symlink
-  that points to the correct (MacPorts) gcc (version 4.4 in this case).
+  up-to-date (at the very least 3.4, but 4.x is better). If you have an old
+  version of XCode lying around, chances are that your gcc install is old. You
+  should also check  ``which gcc``: if it says  ``/usr/bin/gcc`` then you
+  should install gcc_select from MacPorts (``sudo port install gcc_select``)
+  and use the MacPorts-provided gcc. Use ``gcc_select -l`` to see which gcc
+  installs you have on the system. Then execute ``sudo gcc_select mp-gcc44``
+  to create a symlink that points to the correct (MacPorts) gcc (version 4.4
+  in this case).
 
 - This is covered in the MacPorts installation process, but make sure that
   your ``PATH`` environmental variable contains ``/opt/local/bin`` and
-  ``/opt/local/sbin`` before any other paths (to make sure that the python and
+  ``/opt/local/sbin`` before any other paths (to ensure that the python and
   gcc binaries that you installed with MacPorts are visible first).
 
 - Likewise, you need to
   ``export LD_LIBRARY_PATH=/opt/local/lib:$LD_LIBRARY_PATH`` if this is not
   the case already (so that we link to the correct libraries).
 
-- ``scipy`` depends on ATLAS (a BLAS library), which will be installed by MacPorts.
+- An obscure ``Bus error`` can sometimes be caused when linking
+  Theano-generated object files against the ``framework`` library in Leopard.
+  For this reason, we've disabled linking with ``-framework Python``, since on 
+  most configurations this solves the ``Bus error`` problem. If this default
+  configuration causes problems with your Python/theano installation and you think
+  that linking with ``-framework Python`` might help, then either set
+  ``THEANO_FLAGS=cmodule.mac_framework_link`` or edit your ``~/.theanorc`` to
+  contain
+
+    .. code-block:: bash
+
+      [cmodule]
+      mac_framework_link=True
 
-These installation instructions have not tested recently, please infom us of your results! 
+Please infom us if you have trouble installing and running Theano on your mac.
 We would be especially interested in dependencies that we missed listing, as well as tests
 that fail on your platform (use the ``theano-users@googlegroups.com`` mailing list,
-but note that you must first register to it, by going to 
-`http://groups.google.com/group/theano-users`_).
+but note that you must first register to it, by going to `theano-users`_).
 
 
 Windows