# HG changeset patch
# User Jeroen Demeyer
# Date 1321607336 3600
# Node ID a0ed53dabbe1dce658c6ebfdff9fe63f9f05b8b7
# Parent 34b00237e846827599803897e455c95e047747a4
Recommend using a symbolic link from /usr/local/bin/sage to $SAGE_ROOT/sage
diff git a/doc/en/installation/binary.rst b/doc/en/installation/binary.rst
 a/doc/en/installation/binary.rst
+++ b/doc/en/installation/binary.rst
@@ 14,7 +14,7 @@
Assumptions: You have a computer with at least 2 GB of free
disk space and the operating system is Linux (32bit or 64bit) or
OS X (10.5.x).
+OS X (10.4 or later).
Highly Recommended: It is highly recommended that you have LaTeX
installed. If you want to view animations, you should install either
@@ 22,57 +22,43 @@
displaying some LaTeX output in the Sage notebook.
Download the latest binary tarball from
http://www.sagemath.org/download.html . For example, it might be
+http://www.sagemath.org/download.html. For example, it might be
called ``sagex.y.zx86_64Linux.tgz``. Unpack it on your computer
in a directory which you have permission to read and write:
+in a directory which you have permission to read and write::
+
+ tar zxvf sagex.y.zx86_64Linux.tgz
+
+You can move the resulting directory ``sagex.y.zx86_64Linux``
+anywhere and still run ``./sage`` from it, as long as the full path name
+has **no spaces** in it. You can also copy the file ``sage`` from
+that directory and put it anywhere, e.g., ``/usr/local/bin/``, but
+then you have to edit the ``#SAGE_ROOT=/path/to/sageversion`` line
+at the top of the copied file ``/usr/local/bin/sage``
+(you should not edit the original ``sage`` executable).
+The variable ``SAGE_ROOT`` should point to the directory
+``sagex.y.zx86_64Linux`` of the extracted Sage tarball.
+As long as ``/usr/local/bin`` is in your
+``$PATH``, you can then type ``sage`` from the command line to run
+Sage. Another approach is to create a symbolic link, say
+``/usr/local/bin/sage``, pointing to ``sagex.y.zx86_64Linux`` ::
+
+ ln s /path/to/sagex.y.zx86_64Linux/sage /usr/local/bin/sage
+
+With this approach, there is no need to edit ``/usr/local/bin/sage``,
+the ``SAGE_ROOT`` path will be discovered automatically thanks to the
+symbolic link.
+When you want to install a new version of Sage, just delete the old
+link and create a new one.
+
+Any time you move the Sage directory, you may see a message like
::
 tar zxvf sagex.y.zx86_64Linux.tgz

You can move the resulting directory ``sagex.y.zx86_64Linux``
anywhere and still run ``sage`` from it, as long as the full path name
has **no spaces** in it. You can also copy the file ``sage`` from
that directory and put it anywhere, e.g., ``/usr/local/bin/``, but
then you have to edit the ``SAGE_ROOT="....."`` line at the top of
that file, replacing the dots with the path to the Sage directory
``sagex.y.zx86_64Linux``. As long as ``/usr/local/bin`` is in your
``$PATH``, you can then type ``sage`` from the command line to run
Sage. Another approach is to create a symbolic link, say
``/usr/local/share/sage``, pointing to ``sagex.y.zx86_64Linux`` ::

 ln s /.../path_to/.../sagex.y.zx86_64Linux /usr/local/share/sage

Then put ``/usr/local/share/sage`` in your ``$PATH``. If you do this,
you can type ``sage`` from the command line to run Sage. Also, if you
install a different version of Sage, you just have to delete the old
link and create one from the new directory to
``/usr/local/share/sage``.

Finally, you can also combine these two approaches, copying ``sage``
to ``/usr/local/bin/``, creating a link ``/usr/local/share/sage``
pointing to ``sagex.y.zx86_64Linux``, and editing
the file ``/usr/local/bin/sage``: change the line ::

 SAGE_ROOT="....."

to ::

 SAGE_ROOT="/usr/local/share/sage"

When you want to install a new version of Sage, just delete the old
link and create a new one; you shouldn't have to replace or modify the
file ``/usr/local/bin/sage``.

The first time you run Sage, and any time you move the Sage directory
or create a link as above, you may see a message saying

::

 The Sage install tree may have moved.
 Regenerating Python.pyo and .pyc files that hardcode the install PATH
 (please wait at most a few minutes)...
 Do not interrupt this.
+ The Sage installation tree may have moved
+ (from /foo to /bar).
+ Changing various hardcoded paths...
+ (Please wait at most a few minutes.)
+ DO NOT INTERRUPT THIS.
We currently distribute ``.dmg`` files for OS X 10.4.x and 10.5.x. But
we would like to make Sage more of a native application. Work for that
diff git a/doc/en/installation/source.rst b/doc/en/installation/source.rst
 a/doc/en/installation/source.rst
+++ b/doc/en/installation/source.rst
@@ 33,7 +33,7 @@
for these systems. You will also find details about `ports `_
to other operating systems or processors which may be taking place.
Assumptions: You have a computer with about 2.5 GB of free
+Assumptions: You have a computer with at least 3 GB of free
disk space running one of the supported version of an
operating system listed at
http://wiki.sagemath.org/SupportedPlatforms
@@ 268,8 +268,8 @@
there are spaces in the path. Running Sage from a directory with
spaces in its name will also fail.
#. Go to http://www.sagemath.org/downloadsource.html , select a mirror,
 and download the file sage\*.tar.
+#. Go to http://www.sagemath.org/downloadsource.html, select a mirror,
+ and download the file ``sagex.y.z.tar``.
This tarfile contains the source code for Sage and the source for
all programs on which Sage depends. Download it into a subdirectory
@@ 345,7 +345,7 @@
::
 grep li "An error" spkg/logs/*
+ grep li "^Error installing" spkg/logs/*
Then paste the contents of the log file(s) with errors to the Sage
support newsgroup http://groups.google.com/group/sagesupport
@@ 479,10 +479,17 @@
#. Optional: Different possibilities to make using Sage a little
easier:
+  Make a symbolic link from ``/usr/local/bin/sage`` (or another
+ directory in your :envvar:`PATH`) to ``$SAGE_ROOT/sage``::
  Copy ``$SAGE_ROOT/sage`` to a location in your ``PATH``. If you do
 this, make sure you edit the line with the ``....``'s at the top of
 the ``sage`` script.
+ ln s /path/to/sagex.y.z/sage /usr/local/bin/sage
+
+ Now simply typing ``sage`` should be sufficient to run Sage.
+
+  Copy ``$SAGE_ROOT/sage`` to a location in your ``PATH``. If you do
+ this, make sure you edit the line ``#SAGE_ROOT=/path/to/sageversion``
+ at the top of the copied ``sage`` script. It is best to edit only
+ the copy, not the original.
 For KDE users, create a bash script {sage} containing the lines
@@ 497,27 +504,11 @@
the Application tab of the Properties of the icon, which you get my
right clicking the mouse on the icon).
  For bash shell users, type ``echo $PATH`` and
 ``cp sage `` into one of these directories, or else
 add this ``bin`` directory to your ``PATH`` variable, e.g., if you use
 the bash shell, add the line

 ::

 PATH="/bin":$PATH
 export PATH

 in your .bashrc file (if it exists; if not, make one). After doing
 this and logging out and in again, typing ``sage`` at a shell prompt
 should start Sage.

 On Linux and OS X systems, you can make an alias to ``$SAGE_ROOT/sage``.
For example, put something similar to the following line in your
 ``.bashrc`` file:
+ ``.bashrc`` file::
 ::

 alias 'sage'='/home/username/sage3.1.2/sage'
+ alias 'sage'='/home/username/sage4.8/sage'
Having done so, quit your terminal emulator and restart it again.
Now typing ``sage`` within your terminal emulator should start
@@ 881,14 +872,18 @@
locations will get updated. For this reason, it might be easier to
simply build Sage in its final location.
#. Make a copy of the ``sage`` script in ``/usr/local/bin``::
+#. Make a symbolic link to the ``sage`` script in ``/usr/local/bin``::
 cp /usr/local/sage4.8/sage /usr/local/bin/
+ ln s /path/to/sagex.y.z/sage /usr/local/bin/sage
+ Alternatively, copy the Sage script::
+
+ cp /path/to/sagex.y.z/sage /usr/local/bin/sage
+
and edit the file ``/usr/local/bin/sage``: ``SAGE_ROOT`` should be
 set to the directory where Sage is installed, for example
 ``/usr/local/sage4.8``. It is recommended not to edit the original
 file ``/usr/local/sage4.8/sage``, only the copy.
+ set to the directory ``/path/to/sagex.y.z/`` where Sage is
+ installed. It is recommended not to edit the original ``sage``
+ script, only the copy in ``/usr/local/bin/sage``.
#. Make sure that all files in the Sage tree are readable by all::