gh-37309: README.md: Move all mentions of release tarballs to the installation guide
    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->
As proposed in https://groups.google.com/g/sage-
devel/c/5kmxaw105lg/m/liCPKG4bAQAJ

The README.md now starts with instructions to install git and then use
`git clone`.

- Also fixes #30201

<!-- Why is this change required? What problem does it solve? -->
<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes #12345". -->
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [x] The title is concise, informative, and self-explanatory.
- [ ] The description explains in detail what this PR is about.
- [x] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on
- #12345: short description why this is a dependency
- #34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: #37309
Reported by: Matthias Köppe
Reviewer(s): Dima Pasechnik, John H. Palmieri, Matthias Köppe

Author: Release Manager

README.md

@@ -132,9 +132,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.
 
@@ -152,52 +151,64 @@ 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 with `git`:
 
-    - Go to https://www.sagemath.org/download-source.html, select a mirror,
-      and download the file :file:`sage-x.y.tar.gz`.
+    - To check that `git` is available, open a terminal and enter
+      the following command at the shell prompt (`$`):
 
-      This compressed archive file contains the source code for Sage and
-      the source for all programs on which Sage depends.
+            $ git --version
+            git version 2.42.0
 
-    - After downloading the source tarball `sage-x.y.tar.gz` into
-      `~/sage/`:
+      The exact version does not matter, but if this command gives an error,
+      install `git` using your package manager, using one of these commands:
 
-            $ cd ~/sage/
-            $ tar xf sage-x.y.tar.gz  # adapt x.y; takes a while
+            $ sudo pacman -S git                          # on Arch Linux
+            $ sudo apt-get update && apt-get install git  # on Debian/Ubuntu
+            $ sudo yum install git                        # on Fedora/Redhat/CentOS
+            $ sudo zypper install git                     # on openSUSE
+            $ sudo xbps-install git                       # on Void Linux
 
-      This creates the subdirectory `sage-x.y`. Now change into it:
+    - Create the directory where `SAGE_ROOT` should be established:
 
-            $ cd sage-x.y/  # adapt x.y
+            $ mkdir -p ~/sage
+            $ cd ~/sage
 
-    - [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 --filter blob:none  \
+                        --origin upstream --branch develop --tags \
+                        https://github.com/sagemath/sage.git
 
-      This will create the directory `sage`. (See the section
+      This command obtains the most recent development release.
+      Replace `--branch develop` by `--branch master` to select
+      the most recent stable release instead.
+
+      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.)
 
-      Change into it and pick the branch you need, typically
-      the latest development branch:
+    - Change into the created subdirectory:
 
             $ cd sage
-            $ git checkout develop
 
     - [Windows] The Sage source tree contains symbolic links, and the
       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.  Install system packages.
+
+    Either refer for this to the [section on installation from
+    source](https://doc.sagemath.org/html/en/installation/source.html) in the
+    Sage Installation Manual for compilations of system packages
+    that you can install. When done, skip to step 7 (bootstrapping).
 
-3.  [Linux, WSL] Install the required minimal build prerequisites.
+    Alternatively, follow the more fine-grained approach below.
+
+4.  [Linux, WSL] Install the required minimal build prerequisites:
 
     - Compilers: `gcc`, `gfortran`, `g++` (GCC versions from 8.4.0 to 13.x
       and recent versions of Clang (LLVM) are supported).
@@ -206,12 +217,12 @@ in the Installation Guide.
       for a discussion of suitable compilers.
 
     - Build tools: GNU `make`, GNU `m4`, `perl` (including
-      ``ExtUtils::MakeMaker``), `ranlib`, `git`, `tar`, `bc`.
+      `ExtUtils::MakeMaker`), `ranlib`, `git`, `tar`, `bc`.
       See [build/pkgs/_prereq/SPKG.rst](build/pkgs/_prereq/SPKG.rst) for
       more details.
 
     - Python 3.4 or later, or Python 2.7, a full installation including
-      `urllib`; but ideally version 3.9.x, 3.10.x, or 3.11.x, which
+      `urllib`; but ideally version 3.9.x, 3.10.x, 3.11.x, 3.12.x, which
       will avoid having to build Sage's own copy of Python 3.
       See [build/pkgs/python3/SPKG.rst](build/pkgs/python3/SPKG.rst)
       for more details.
@@ -230,22 +241,25 @@ in the Installation Guide.
     [void.txt](build/pkgs/_prereq/distros/void.txt), or visit
     https://doc.sagemath.org/html/en/reference/spkg/_prereq.html#spkg-prereq
 
-4.  [Git] If you plan to do Sage development or otherwise work with ticket branches
-    and not only releases, install the bootstrapping prerequisites. See the
-    files in the folder
+5.  Optional: It is recommended that you have both LaTeX and
+    the ImageMagick tools (e.g. the "convert" command) installed
+    since some plotting functionality benefits from them.
+
+6.  [Development] If you plan to do Sage development or otherwise work with
+    ticket branches and not only releases, install the bootstrapping
+    prerequisites. See the files in the folder
     [build/pkgs/_bootstrap/distros](build/pkgs/_bootstrap/distros), or
     visit
     https://doc.sagemath.org/html/en/reference/spkg/_bootstrap.html#spkg-bootstrap
 
-5.  [Git] If you cloned the Sage repository using `git`, bootstrap the
-    source tree using the following command:
+7.  Bootstrap the source tree using the following command:
 
         $ make configure
 
-    (If the bootstrapping prerequisites are not installed, this command will
-    download a package providing pre-built bootstrap output instead.)
+    (If the bootstrapping prerequisites are not installed, this command
+    will download a package providing pre-built bootstrap output instead.)
 
-6.  Sanitize the build environment. Use the command
+8.  Sanitize the build environment. Use the command
 
         $ env
 
@@ -277,7 +291,7 @@ in the Installation Guide.
       can also add it to your shell profile so that it gets run
       automatically in all future sessions.)
 
-7.  Optionally, decide on the installation prefix (`SAGE_LOCAL`):
+9.  Optionally, decide on the installation prefix (`SAGE_LOCAL`):
 
     - Traditionally, and by default, Sage is installed into the
       subdirectory hierarchy rooted at `SAGE_ROOT/local/`.
@@ -295,15 +309,11 @@ in the Installation Guide.
       installs (`make install` is a no-op).  Therefore the
       installation hierarchy must be writable by the user.
 
-    - See the installation manual for options if you want to
+    - See the Sage Installation Manual for options if you want to
       install into shared locations such as `/usr/local/`.
       Do not attempt to build Sage as `root`.
 
-8.  Optional: It is recommended that you have both LaTeX and
-    the ImageMagick tools (e.g. the "convert" command) installed
-    since some plotting functionality benefits from them.
-
-9.  Optionally, review the configuration options, which includes
+10. Optionally, review the configuration options, which includes
     many optional packages:
 
         $ ./configure --help
@@ -321,7 +331,7 @@ in the Installation Guide.
       a great speedup when switching between different branches, at the
       expense of disk space use.
 
-10. Optional, but highly recommended: Set some environment variables to
+11. Optional, but highly recommended: Set some environment variables to
     customize the build.
 
     For example, the `MAKE` environment variable controls whether to
@@ -343,7 +353,7 @@ in the Installation Guide.
     building Sage, see [the installation
     guide](https://doc.sagemath.org/html/en/installation/source.html#environment-variables).
 
-11. Type `./configure`, followed by any options that you wish to use.
+12. Type `./configure`, followed by any options that you wish to use.
     For example, to build Sage with `gf2x` package supplied by Sage,
     use `./configure --with-system-gf2x=no`.
 
@@ -363,60 +373,60 @@ in the Installation Guide.
     available; only the most recent releases of your distribution will
     have all of these recommended packages.
 
-12. Optional: If you choose to install the additional system packages,
+13. Optional: If you choose to install the additional system packages,
     a re-run of `./configure` will test whether the versions installed
     are usable for Sage; if they are, this will reduce the compilation
     time and disk space needed by Sage. The usage of packages may be
     adjusted by `./configure` parameters (check again the output of
     `./configure --help`).
 
-13. Type `make`.  That's it! Everything is automatic and
+14. Type `make`.  That's it! Everything is automatic and
     non-interactive.
 
     If you followed the above instructions, in particular regarding the
     installation of system packages recommended by the output of
-    `./configure` (step 10), and regarding the parallel build (step 9),
+    `./configure` (step 11), and regarding the parallel build (step 10),
     building Sage takes less than one hour on a modern computer.
     (Otherwise, it can take much longer.)
 
     The build should work fine on all fully supported platforms. If it
     does not, we want to know!
 
-14. Type `./sage` to try it out. In Sage, try for example `2 + 2`,
+15. Type `./sage` to try it out. In Sage, try for example `2 + 2`,
     `plot(x^2)`, `plot3d(lambda x, y: x*y, (-1, 1), (-1, 1))`
     to test a simple computation and plotting in 2D and 3D.
     Type <kbd>Ctrl</kbd>+<kbd>D</kbd> or `quit` to quit Sage.
 
-15. Optional: Type `make ptestlong` to test all examples in the documentation
+16. Optional: Type `make ptestlong` to test all examples in the documentation
     (over 200,000 lines of input!) -- this takes from 10 minutes to
     several hours. Don't get too disturbed if there are 2 to 3 failures,
     but always feel free to email the section of `logs/ptestlong.log` that
     contains errors to the [sage-support mailing list](https://groups.google.com/group/sage-support).
     If there are numerous failures, there was a serious problem with your build.
 
-16. The HTML version of the [documentation](https://doc.sagemath.org/html/en/index.html)
+17. The HTML version of the [documentation](https://doc.sagemath.org/html/en/index.html)
     is built during the compilation process of Sage and resides in the directory
     `local/share/doc/sage/html/`. You may want to bookmark it in your browser.
 
-17. Optional: If you want to build the PDF version of the documentation,
+18. Optional: If you want to build the PDF version of the documentation,
     run `make doc-pdf` (this requires LaTeX to be installed).
 
-18. Optional: Install optional packages of interest to you:
+19. Optional: Install optional packages of interest to you:
     get a list by typing  `./sage --optional` or by visiting the
     [packages documentation page](https://doc.sagemath.org/html/en/reference/spkg/).
 
-19. Optional: Create a symlink to the installed `sage` script in a
-    directory in your `PATH`, for example ``/usr/local``. This will
+20. Optional: Create a symlink to the installed `sage` script in a
+    directory in your `PATH`, for example `/usr/local`. This will
     allow you to start Sage by typing `sage` from anywhere rather than
     having to either type the full path or navigate to the Sage
     directory and type `./sage`. This can be done by running:
 
         $ sudo ln -s $(./sage -sh -c 'ls $SAGE_ROOT/venv/bin/sage') /usr/local/bin
 
-20. Optional: Set up SageMath as a Jupyter kernel in an existing Jupyter notebook
+21. Optional: Set up SageMath as a Jupyter kernel in an existing Jupyter notebook
     or JupyterLab installation, as described in [section
     "Launching SageMath"](https://doc.sagemath.org/html/en/installation/launching.html)
-    in the installation manual.
+    in the Sage Installation Manual.
 
 Alternative Installation using PyPI
 ---------------
@@ -505,7 +515,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/developer/git_setup.rst

@@ -12,11 +12,9 @@ Installing Git
 
 Depending on your platform, use the following to install Git:
 
-Debian / Ubuntu
-    Run ``sudo apt-get install git-core``
-
-Fedora
-    Run ``sudo yum install git-core``
+Linux
+    See :ref:`spkg_git` for the installation command on your
+    Linux distribution.
 
 Windows (WSL)
     We strongly recommend to install the package using the Linux

src/doc/en/developer/walkthrough.rst

@@ -61,8 +61,8 @@ Obtaining the Sage source code
 ==============================
 
 Obviously one needs the Sage source code to develop. You can use your
-local installation of Sage, or (to start from scratch) download it
-from our Sage repository on GitHub::
+local installation of Sage (if you installed Sage from source), or
+(to start from scratch) download it from our Sage repository on GitHub::
 
     [alice@localhost ~]$ git clone --origin upstream https://github.com/sagemath/sage.git
     Cloning into 'sage'...

src/doc/en/installation/source.rst

@@ -373,9 +373,49 @@ Installation steps
 #. Follow the procedure in the file `README.md <https://github.com/sagemath/sage/#readme>`_
    in ``SAGE_ROOT``.
 
+#. If you 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.
@@ -490,7 +530,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.