Merge topic 'tutorial-misc-fixes'

4b093ae12e Tutorial: Move multi-config install note to the first exercise
653356bed0 Tutorial: Describe install prefix
fdc4511f18 Tutorial: Fix some typos

Acked-by: Kitware Robot <kwrobot@kitware.com>
Reviewed-by: Vito Gamberini <vito.gamberini@kitware.com>
Merge-request: !12062

Help/guide/tutorial/Finding Dependencies.rst

@@ -142,7 +142,7 @@ Build and Run
 -------------
 
 First we must install the ``SimpleTest`` framework. Navigate to the
-``Help/guide/Step10/SimpleTest`` directory and run the following commands
+``Help/guide/Step10/SimpleTest`` directory and run the following commands.
 
 .. code-block:: console
 
@@ -191,7 +191,7 @@ We do this with ``REQUIRED`` because the tests cannot build without
 
   </details>
 
-Next we add the ``SimpleTest::SimpleTest`` target to ``TestMathFunctions``
+Next we add the ``SimpleTest::SimpleTest`` target to ``TestMathFunctions``.
 
 .. raw:: html
 

Help/guide/tutorial/Getting Started with CMake.rst

@@ -449,7 +449,7 @@ executable.
   </details>
 
 Next we need to describe the source files. For the implementation file,
-``MathFunctions.cxx``, this is straight-forward; for the header file
+``MathFunctions.cxx``, this is straightforward; for the header file
 ``MathFunctions.h`` we will need to use a ``FILE_SET``.
 
 We can either give this ``FILE_SET`` its own name, or use the shortcut of naming

Help/guide/tutorial/Installation Commands and Concepts.rst

@@ -66,6 +66,27 @@ to unless instructed to do otherwise. For example, ``RUNTIME`` will be installed
 to the location named by :module:`CMAKE_INSTALL_BINDIR <GNUInstallDirs>`, if
 the variable is available, otherwise they default to ``bin``.
 
+Just like we use :option:`cmake -B` to control what build directory will be
+used by CMake, we have a variety of options for telling CMake where to install
+things. This location is generally referred to as the install prefix. To
+set this at configure time, so that every :option:`cmake --install` performed
+using that build tree defaults to a given prefix, we can use any of:
+
+* the :option:`cmake --install-prefix` option;
+* the :ref:`installDir <CMakePresets installDir>` field in CMake presets; or
+* the :variable:`CMAKE_INSTALL_PREFIX` variable.
+
+.. note::
+  We have discouraged setting ``CMAKE_`` variables inside the project. Setting
+  :variable:`CMAKE_INSTALL_PREFIX` is *particularly* bad practice without very
+  good reasoning for doing so, since it prevents users from ever overriding it.
+  When providing a default, projects should check
+  :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT`.
+
+Alternatively, we can use the
+:option:`cmake --install --prefix <cmake--install --prefix>` option to set the
+install prefix for a single install invocation.
+
 The full list of artifact kind default destinations is described in the
 following table.
 
@@ -140,6 +161,8 @@ Helpful Resources
 -----------------
 
 * :command:`install`
+* :option:`cmake --install-prefix`
+* :option:`cmake --install --prefix <cmake--install --prefix>`
 
 Files to Edit
 -------------
@@ -164,6 +187,14 @@ No special configuration is needed, configure and build as usual.
 
 We can verify the installation is correct with :option:`cmake --install`.
 
+.. note::
+
+  As with CTest, when using a multi-config generator such as Visual Studio, it
+  will be necessary to specify a configuration like ``Debug`` or ``Release``
+  using :option:`cmake --install --config <cmake--install --config>`.
+  This is true whenever using a multi-config generator, and won't be called out
+  specifically in future commands.
+
 .. code-block:: console
 
   cmake --install build --prefix install
@@ -329,15 +360,6 @@ The build command is sufficient to reconfigure the project.
 
 We can verify the installation is correct with :option:`cmake --install`.
 
-.. note::
-
-  As with CTest, when using multi-config generator, eg Visual Studio, it will be
-  necessary to specify a configuration with
-  ``cmake --install --config <config> <remaining flags>``, where
-  ``<config>`` is a value like ``Debug`` or ``Release``. This is true whenever
-  using a multi-config generator, and won't be called out specifically in
-  future commands.
-
 .. code-block:: console
 
   cmake --install build --prefix install
@@ -471,7 +493,7 @@ When importing CMake targets from a target export file, there is no way to
 incompatible version for the one we requested, we'll be stuck with any
 side-effects incurred while we learned that version information.
 
-The answer CMake provides for this problem is a light-weight version file which
+The answer CMake provides for this problem is a lightweight version file which
 only describes this version compatibility information, which can be checked
 before CMake commits to fully importing the file.
 

Help/guide/tutorial/Testing and CTest.rst

@@ -117,11 +117,10 @@ Verify all the tests pass with CTest.
 
 .. note::
 
-  If using a multi-config generator, eg Visual Studio, it will be necessary to
-  specify a configuration with ``ctest -C <config> <remaining flags>``, where
-  ``<config>`` is a value like ``Debug`` or ``Release``. This is true whenever
-  using a multi-config generator, and won't be called out specifically in
-  future commands.
+  When using a multi-config generator such as Visual Studio, it
+  will be necessary to specify a configuration like ``Debug`` or ``Release``
+  using :option:`ctest -C`. This is true whenever using a multi-config
+  generator, and won't be called out specifically in future commands.
 
 .. code-block:: console