README.md: Move all mentions of release tarballs to the installation guide

Author: Matthias Koeppe

README.md

@@ -131,9 +131,8 @@ in the Installation Guide.
     - On personal computers, any subdirectory of your :envvar:`HOME`
       directory should do.
 
-    - For example, you could use `SAGE_ROOT=~/sage/sage-x.y`, which we
-      will use as the running example below, where `x.y` is the
-      current Sage version.
+    - For example, you could use `SAGE_ROOT=~/sage/sage`, which we
+      will use as the running example below.
 
     - You need at least 10 GB of free disk space.
 
@@ -151,31 +150,19 @@ in the Installation Guide.
       capitalization when changing into :envvar:`SAGE_ROOT` can lead to build
       errors for dependencies requiring exact capitalization in path names.
 
-2.  Download/unpack or clone the sources.
+2.  Clone the sources.
 
-    - Go to https://www.sagemath.org/download-source.html, select a mirror,
-      and download the file :file:`sage-x.y.tar.gz`.
+    - Create the directory where `SAGE_ROOT` should be established:
 
-      This compressed archive file contains the source code for Sage and
-      the source for all programs on which Sage depends.
+            $ mkdir -p ~/sage
+            $ cd ~/sage
 
-    - After downloading the source tarball `sage-x.y.tar.gz` into
-      `~/sage/`:
-
-            $ cd ~/sage/
-            $ tar xf sage-x.y.tar.gz  # adapt x.y; takes a while
-
-      This creates the subdirectory `sage-x.y`. Now change into it:
-
-            $ cd sage-x.y/  # adapt x.y
-
-    - [Git] Alternatively, and required for Sage development, clone the Sage
-      git repository:
+    - Clone the Sage git repository:
 
             $ ORIG=https://github.com/sagemath/sage.git
-            $ git clone -c core.symlinks=true --branch develop --tags $ORIG
+            $ git clone -c core.symlinks=true --origin upstream --branch develop --tags $ORIG
 
-      This will create the directory `sage`. (See the section
+      This will create the subdirectory `~/sage/sage`. (See the section
       [Setting up git](https://doc.sagemath.org/html/en/developer/git_setup.html)
       and the following sections in the Sage Developer's Guide
       for more information.)
@@ -190,11 +177,8 @@ in the Installation Guide.
       build will not work if Windows line endings rather than UNIX
       line endings are used.
 
-      Therefore it is crucial that you unpack the source tree from the
-      WSL `bash` using the WSL `tar` utility and not using other
-      Windows tools (including mingw). Likewise, when using `git`, it
-      is recommended (but not necessary) to use the WSL version of
-      `git`.
+      Therefore it is recommended (but not necessary) to use the
+      WSL version of `git`.
 
 3.  [Linux, WSL] Install the required minimal build prerequisites.
 
@@ -473,7 +457,7 @@ Directory Layout
 
 Simplified directory layout (only essential files/directories):
 ```
-SAGE_ROOT                 Root directory (sage-x.y in Sage tarball)
+SAGE_ROOT                 Root directory (create by git clone)
 ├── build
 │   └── pkgs              Every package is a subdirectory here
 │       ├── 4ti2/

src/doc/en/developer/doctesting.rst

@@ -26,7 +26,7 @@ this syntax:
 
 .. CODE-BLOCK:: text
 
-    /path/to/sage-x.y.z/sage -t [--long] /path/to/sage-x.y.z/path/to/module.py[x]
+    /path/to/sage_root/sage -t [--long] /path/to/sage_root/path/to/module.py[x]
 
 where ``--long`` is an optional argument (see :ref:`section-options`
 for more options). The version of ``sage`` used must match the version

src/doc/en/installation/source.rst

@@ -387,9 +387,49 @@ Installation steps
 #. Follow the procedure in the file `README.md <https://github.com/sagemath/sage/#readme>`_
    in ``SAGE_ROOT``.
 
+#. If you need wish to prepare for having to build Sage in an environment
+   without sufficient Internet connectivity:
+
+   - After running ``configure``, you can use ``make download`` to force
+     downloading packages before building. After this, the packages
+     are in the subdirectory ``upstream``.
+
+   - Alternatively, instead of cloning the git repository, you
+     can download a self-contained release tarball for any
+     stable release from the Sage project's
+     `GitHub Releases <https://github.com/sagemath/sage/releases>`_.
+     Use the file named ``sage-x.y.tar.gz`` (1.25 GB as of Sage 10.2)
+     in the Release Assets, which contains a prepopulated subdirectory
+     ``upstream``.
+
+     After downloading the source tarball ```sage-x.y.tar.gz``` into
+     a directory ```~/sage/```::
+
+       $ cd ~/sage/
+       $ tar xf sage-x.y.tar.gz  # adapt x.y; takes a while
+
+     This creates the subdirectory `````sage-x.y```. Now change into it::
+
+       $ cd sage-x.y/  # adapt x.y
+
+     .. note::
+
+        On Windows, it is crucial that you unpack the source tree from the
+        WSL `bash` using the WSL `tar` utility and not using other
+        Windows tools (including mingw).
+
+        This is because the Sage source tree contains symbolic links, and the
+        build will not work if Windows line endings rather than UNIX
+        line endings are used.
+
+   - The Sage mirrors also provide such self-contained tarballs
+     for all `stable releases <https://www.sagemath.org/download-source.html>`_
+     and additionally for all `development releases
+     <https://www.sagemath.org/download-latest.html>`_.
+
 #. Additional remarks:
    You do not need to be logged in as root, since no files are
-   changed outside of the :file:`sage-x.y` directory.
+   changed outside of the :file:`SAGE_ROOT` directory.
    In fact, **it is inadvisable to build Sage as root**, as the root account
    should only be used when absolutely necessary and mistyped commands can have
    serious consequences if you are logged in as root.
@@ -504,7 +544,7 @@ Installation steps
    - Make a symbolic link from :file:`/usr/local/bin/sage` (or another
      directory in your :envvar:`PATH`) to :file:`$SAGE_ROOT/sage`::
 
-         $ ln -s /path/to/sage-x.y/sage /usr/local/bin/sage
+         $ ln -s /path/to/sage_root/sage /usr/local/bin/sage
 
      Now simply typing ``sage`` from any directory should be sufficient to run
      Sage.