Minor changes to Build Settings docs (#9808)

1 files changed, 27 insertions, 25 deletions

diff --git a/lib/spack/docs/build_settings.rst b/lib/spack/docs/build_settings.rst
index 07e4ab13b8..da2730baa1 100644
--- a/lib/spack/docs/build_settings.rst
+++ b/lib/spack/docs/build_settings.rst
@@ -5,15 +5,16 @@
 
 .. _build-settings:
 
-======================================
-Build customization
-======================================
+===================
+Build Customization
+===================
 
 Spack allows you to customize how your software is built through the
 ``packages.yaml`` file.  Using it, you can make Spack prefer particular
-implementations of virtual dependencies (e.g., compilers, MPI, or BLAS),
+implementations of virtual dependencies (e.g., MPI or BLAS/LAPACK),
 or you can make it prefer to build with particular compilers.  You can
-also tell Spack to use *external* installations of certain software.
+also tell Spack to use *external* software installations already
+present on your system.
 
 At a high level, the ``packages.yaml`` file is structured like this:
 
@@ -28,14 +29,14 @@ At a high level, the ``packages.yaml`` file is structured like this:
      all:
        # settings that apply to all packages.
 
-So you can either set build preferences *specifically* for one package,
-or you can specify that certain settings should apply to all packages.
+So you can either set build preferences specifically for *one* package,
+or you can specify that certain settings should apply to *all* packages.
 The types of settings you can customize are described in detail below.
 
 Spack's build defaults are in the default
 ``etc/spack/defaults/packages.yaml`` file.  You can override them in
 ``~/.spack/packages.yaml`` or ``etc/spack/packages.yaml``. For more
-details on how this works, see :ref:`configuration-scopes`
+details on how this works, see :ref:`configuration-scopes`.
 
 .. _sec-external-packages:
 
@@ -61,11 +62,12 @@ directory. Here's an example of an external configuration:
          openmpi@1.4.3%gcc@4.4.7 arch=linux-x86_64-debian7+debug: /opt/openmpi-1.4.3-debug
          openmpi@1.6.5%intel@10.1 arch=linux-x86_64-debian7: /opt/openmpi-1.6.5-intel
 
-This example lists three installations of OpenMPI, one built with gcc,
-one built with gcc and debug information, and another built with Intel.
+This example lists three installations of OpenMPI, one built with GCC,
+one built with GCC and debug information, and another built with Intel.
 If Spack is asked to build a package that uses one of these MPIs as a
-dependency, it will use the the pre-installed OpenMPI in
-the given directory. Packages.yaml can also be used to specify modules
+dependency, it will use the pre-installed OpenMPI in
+the given directory. ``packages.yaml`` can also be used to specify modules
+to load instead of the installation prefixes.
 
 Each ``packages.yaml`` begins with a ``packages:`` token, followed
 by a list of package names.  To specify externals, add a ``paths`` or ``modules``
@@ -82,9 +84,9 @@ though the package and compiler may not ever be built.
 
 The packages configuration can tell Spack to use an external location
 for certain package versions, but it does not restrict Spack to using
-external packages.  In the above example, if an OpenMPI 1.8.4 became
-available Spack may choose to start building and linking with that version
-rather than continue using the pre-installed OpenMPI versions.
+external packages.  In the above example, since newer versions of OpenMPI
+are available, Spack will choose to start building and linking with the
+latest version rather than continue using the pre-installed OpenMPI versions.
 
 To prevent this, the ``packages.yaml`` configuration also allows packages
 to be flagged as non-buildable.  The previous example could be modified to
@@ -120,12 +122,12 @@ Concretization Preferences
 --------------------------
 
 Spack can be configured to prefer certain compilers, package
-versions, depends_on, and variants during concretization.
+versions, dependencies, and variants during concretization.
 The preferred configuration can be controlled via the
-``~/.spack/packages.yaml`` file for user configuations, or the
+``~/.spack/packages.yaml`` file for user configurations, or the
 ``etc/spack/packages.yaml`` site configuration.
 
-Here's an example packages.yaml file that sets preferred packages:
+Here's an example ``packages.yaml`` file that sets preferred packages:
 
 .. code-block:: yaml
 
@@ -138,17 +140,17 @@ Here's an example packages.yaml file that sets preferred packages:
      all:
        compiler: [gcc@4.4.7, gcc@4.6:, intel, clang, pgi]
        providers:
-         mpi: [mvapich, mpich, openmpi]
+         mpi: [mvapich2, mpich, openmpi]
 
 At a high level, this example is specifying how packages should be
-concretized.  The opencv package should prefer using gcc 4.9 and
+concretized.  The opencv package should prefer using GCC 4.9 and
 be built with debug options.  The gperftools package should prefer version
-2.2 over 2.4.  Every package on the system should prefer mvapich for
-its MPI and gcc 4.4.7 (except for opencv, which overrides this by preferring gcc 4.9).
+2.2 over 2.4.  Every package on the system should prefer mvapich2 for
+its MPI and GCC 4.4.7 (except for opencv, which overrides this by preferring GCC 4.9).
 These options are used to fill in implicit defaults.  Any of them can be overwritten
 on the command line if explicitly requested.
 
-Each packages.yaml file begins with the string ``packages:`` and
+Each ``packages.yaml`` file begins with the string ``packages:`` and
 package names are specified on the next level. The special string ``all``
 applies settings to each package. Underneath each package name is
 one or more components: ``compiler``, ``variants``, ``version``,
@@ -169,7 +171,7 @@ gcc to pgi will thus be preferred over the xlc compiler.
 
 The syntax for the ``provider`` section differs slightly from other
 concretization rules.  A provider lists a value that packages may
-``depend_on`` (e.g, mpi) and a list of rules for fulfilling that
+``depend_on`` (e.g, MPI) and a list of rules for fulfilling that
 dependency.
 
 .. _package_permissions:
@@ -213,7 +215,7 @@ packages will be installed with user and group write privileges, and
 world read privileges. Those packages will be owned by the group
 ``spack``.
 
-The ``group`` attribute assigns a unix-style group to a package. All
+The ``group`` attribute assigns a Unix-style group to a package. All
 files installed by the package will be owned by the assigned group,
 and the sticky group bit will be set on the install prefix and all
 directories inside the install prefix. This will ensure that even