Clairfy docs regarding installed chapel and chplconfig (chapel-lang#2…

…5987)

Clarifies chplconfig and its relationship with `./configure` and `make
install`.

Resolves the remaining concerns from
chapel-lang#14932

[Reviewed by @mppf]

doc/rst/usingchapel/building.rst

@@ -112,11 +112,11 @@ Chapel can be built and installed to a specific location as follows:
   make
   make install
 
-Running ``./configure`` will save your current configuration of
-``$CHPL_`` settings into a ``chplconfig`` file.  Running it with the
-``--prefix`` or ``--chpl-home`` options permits you to specify where
-and how Chapel should be installed during the ``make install`` step.
-Specifically:
+Running ``./configure`` will save your current configuration of ``$CHPL_``
+settings into a ``chplconfig`` file. This ``chplconfig`` file will be installed
+wherever ``CHPL_HOME`` is. Running ``./configure`` with the ``--prefix`` or
+``--chpl-home`` options permits you to specify where and how Chapel should be
+installed during the ``make install`` step. Specifically:
 
 * ``--prefix=/dir/for/install/`` causes the Chapel compiler,
   libraries, and supporting code to be installed into the directories:
@@ -131,10 +131,11 @@ Specifically:
   ``/usr/local/`` or ``~/``.  Note that elevated privileges are likely
   to be required for any system-wide installation locations.
 
-  Please note that for any prefix-installed version of Chapel, the
-  meaning of ``$CHPL_HOME`` (e.g., as printed by compiler messages)
-  typically refers to ``/dir/for/install/share/chapel/x.yz`` where
-  ``x.yz`` is the Chapel version that was installed.
+  Please note that for any prefix-installed version of Chapel, the meaning of
+  ``$CHPL_HOME`` (e.g., as printed by compiler messages) is the path printed by
+  ``chpl --print-chpl-home``. This is typically
+  ``/dir/for/install/share/chapel/x.yz`` where ``x.yz`` is the Chapel version
+  that was installed.
 
 * ``--chpl-home=/dir/for/install`` copies key files and directories
   from the Chapel source tree into ``/dir/for/install``, preserving

doc/rst/usingchapel/chplenv.rst

@@ -1080,15 +1080,22 @@ Chapel configuration file is found, the definitions of that file are used.
     The ``$CHPL_CONFIG`` variable is the path to the *enclosing*
     directory - not the full path including ``chplconfig`` itself.
 
+.. note::
+
+   In a prefix install, a ``chplconfig`` file is installed in ``$CHPL_HOME``.
+   See :ref:`readme-installing`.
+
 Variable Priority
 ~~~~~~~~~~~~~~~~~
 
 Variable precedence goes in the following order:
 
-1. Explicit compiler flags: ``chpl --env=value``
-2. Environment variables: ``CHPL_ENV=value``
-3. Chapel configuration file: ``~/.chplconfig``
-4. Inferred environment variables: ``printchplenv``
+1. Explicit compiler flags specified as ``chpl --env=value```
+2. Environment variables set by the user (``export CHPL_ENV=value`` or
+   ``CHPL_ENV=value chpl ...``)
+3. Chapel configuration file settings from a ``chplconfig`` file, as described
+   above
+4. Inferred environment variables from ``printchplenv``
 
 
 .. |trade|  unicode:: U+02122 .. TRADE MARK SIGN