Simplified "Environment-Modules" section in getting started guide. (#6410)

Fixes #2440

The "Getting started" guide should be short and sweet. This commit
simplifies the "Environment-Modules" section pruning:

 - outdated / wrong suggestions as noted in #2440
 - uncommon setups that are better treated in a reference guide

1 files changed, 21 insertions, 58 deletions

diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst
index 186bff9ad1..0f4a23f7fa 100644
--- a/lib/spack/docs/getting_started.rst
+++ b/lib/spack/docs/getting_started.rst
@@ -926,75 +926,38 @@ Once ``curl`` has been installed, you can similarly install the others.
 Environment Modules
 """""""""""""""""""
 
-In order to use Spack's generated environment modules, you must have
-installed one of *Environment Modules* or *Lmod*.  On many Linux
-distributions, this can be installed from the vendor's repository.  For
-example: ``yum install environment-modules`` (Fedora/RHEL/CentOS). If
-your Linux distribution does not have Environment Modules, Spack can
-build it for you!
-
-What follows are three steps describing how to install and use environment-modules with spack.
-
-#. Install ``environment-modules``.
-
-   * ``spack bootstrap`` will build ``environment-modules`` for you (and may build
-     other packages that are useful to the operation of Spack)
-
-   * Install ``environment-modules`` using ``spack install`` with
-     ``spack install environment-modules~X`` (The ``~X`` variant builds without Xorg
-     dependencies, but ``environment-modules`` works fine too.)
-
-#. Add ``modulecmd`` to ``PATH`` and create a ``module`` command. 
-
-   * If you are using ``bash`` or ``ksh``, Spack can currently do this for you as well.
-     After installing ``environment-modules`` following the step
-     above, source Spack's shell integration script. This will automatically
-     detect the lack of ``modulecmd`` and ``module``, and use the installed
-     ``environment-modules`` from ``spack bootstrap`` or ``spack install``.
-     
-     .. code-block:: console
-
-        # For bash/zsh users
-        $ export SPACK_ROOT=/path/to/spack
-        $ . $SPACK_ROOT/share/spack/setup-env.sh
+In order to use Spack's generated module files, you must have
+installed ``environment-modules`` or ``lmod``. The simplest way
+to get the latest version of either of these tools is installing
+it as part of Spack's bootstrap procedure:
 
+.. code-block:: console
 
-   * If you prefer to do it manually,  you can activate with the following 
-     script (or apply the updates to your ``.bashrc`` file manually):
+   $ spack bootstrap
 
-         .. code-block:: sh
+.. warning::
+   At the moment ``spack bootstrap`` is only able to install ``environment-modules``.
+   Extending its capabilities to prefer ``lmod`` where possible is in the roadmap,
+   and likely to happen before the next release.
 
-            TMP=`tempfile`
-            echo >$TMP
-            MODULE_HOME=`spack location --install-dir environment-modules`
-            MODULE_VERSION=`ls -1 $MODULE_HOME/Modules | head -1`
-            ${MODULE_HOME}/Modules/${MODULE_VERSION}/bin/add.modules <$TMP
-            cp .bashrc $TMP
-            echo "MODULE_VERSION=${MODULE_VERSION}" > .bashrc
-            cat $TMP >>.bashrc
+Alternatively, on many Linux distributions, you can install a pre-built binary
+from the vendor's repository. On Fedora/RHEL/CentOS, for example, this can be
+done with the command:
 
-      This is added to your ``.bashrc`` (or similar) files, enabling Environment
-      Modules when you log in.
-        
-#. Test that the ``module`` command is found with:
+.. code-block:: console
 
-   .. code-block:: console
+   $ yum install environment-modules
 
-      $ module avail
+Once you have the tool installed and available in your path, you can source
+Spack's setup file:
 
+.. code-block:: console
 
-If ``tcl`` 8.0 or later is installed on  your system, you can prevent
-spack from rebuilding ``tcl`` as part of the ``environment-modules`` dependency
-stack by adding the following to your ``~/.spack/packages.yaml`` replacing
-version 8.5 with whatever version is installed on your system:
+   $ source share/spack/setup-env.sh
 
-   .. code-block:: yaml
+This activates :ref:`shell support <shell-support>` and makes commands like
+``spack load`` available for use.
 
-      packages:
-          tcl:
-              paths:
-                  tcl@8.5: /usr
-              buildable: False
 
 ^^^^^^^^^^^^^^^^^
 Package Utilities