Imported Upstream version 3.17.0upstream/3.17.0

27 files changed, 1136 insertions, 257 deletions

diff --git a/Help/guide/tutorial/Complete/CMakeLists.txt b/Help/guide/tutorial/Complete/CMakeLists.txt
index eca79d9df..4d8a3ada8 100644
--- a/Help/guide/tutorial/Complete/CMakeLists.txt
+++ b/Help/guide/tutorial/Complete/CMakeLists.txt
@@ -3,6 +3,8 @@ cmake_minimum_required(VERSION 3.15)
 # set the project name and version
 project(Tutorial VERSION 1.0)
 
+set(CMAKE_DEBUG_POSTFIX d)
+
 add_library(tutorial_compiler_flags INTERFACE)
 target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
 
@@ -37,6 +39,8 @@ add_subdirectory(MathFunctions)
 
 # add the executable
 add_executable(Tutorial tutorial.cxx)
+set_target_properties(Tutorial PROPERTIES DEBUG_POSTFIX ${CMAKE_DEBUG_POSTFIX})
+
 target_link_libraries(Tutorial PUBLIC MathFunctions)
 
 # add the binary tree to the search path for include files
diff --git a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
index dfa84c941..c911625b8 100644
--- a/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Complete/MathFunctions/CMakeLists.txt
@@ -17,7 +17,7 @@ if(USE_MYMATH)
 
   # first we add the executable that generates the table
   add_executable(MakeTable MakeTable.cxx)
-  target_link_libraries(MakeTable tutorial_compiler_flags)
+  target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)
 
   # add the command to generate the source code
   add_custom_command(
diff --git a/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake
index 403b633e1..c2583dfff 100644
--- a/Help/guide/tutorial/MultiPackage/MultiCPackConfig.cmake
+++ b/Help/guide/tutorial/Complete/MultiCPackConfig.cmake
@@ -1,4 +1,3 @@
-
 include("release/CPackConfig.cmake")
 
 set(CPACK_INSTALL_CMAKE_PROJECTS
diff --git a/Help/guide/tutorial/Complete/tutorial.cxx b/Help/guide/tutorial/Complete/tutorial.cxx
index 586d183a7..a4f44d54f 100644
--- a/Help/guide/tutorial/Complete/tutorial.cxx
+++ b/Help/guide/tutorial/Complete/tutorial.cxx
@@ -1,6 +1,5 @@
 // A simple program that computes the square root of a number
 #include <iostream>
-#include <sstream>
 #include <string>
 
 #include "MathFunctions.h"
@@ -9,6 +8,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -18,8 +18,8 @@ int main(int argc, char* argv[])
   // convert input to double
   const double inputValue = std::stod(argv[1]);
 
-  // calculate square root
   const double outputValue = mathfunctions::sqrt(inputValue);
+
   std::cout << "The square root of " << inputValue << " is " << outputValue
             << std::endl;
   return 0;
diff --git a/Help/guide/tutorial/Consumer/CMakeLists.txt b/Help/guide/tutorial/Consumer/CMakeLists.txt
deleted file mode 100644
index a0e4598bc..000000000
--- a/Help/guide/tutorial/Consumer/CMakeLists.txt
+++ /dev/null
@@ -1,51 +0,0 @@
-cmake_minimum_required(VERSION 3.10)
-
-if(NOT DEFINED CMAKE_CXX_STANDARD)
-  set(CMAKE_CXX_STANDARD 11)
-  set(CMAKE_CXX_STANDARD_REQUIRED True)
-endif()
-
-
-function(find_external_dependency name)
-  set(${name}_ROOT ""  CACHE PATH "Root directory to find ${name}")
-  mark_as_advanced(${name}_DIR)
-  find_package(${name} PATHS ${${name}_ROOT} REQUIRED)
-endfunction()
-
-
-project(Consumer)
-
-find_external_dependency(MathFunctions)
-
-add_library(consumer consumer.cxx)
-target_link_libraries(consumer PUBLIC MathFunctions)
-
-# install the consumer library
-install(TARGETS consumer DESTINATION bin EXPORT ConsumerTargets)
-
-# install the configuration targets
-install(EXPORT ConsumerTargets
-  FILE ConsumerTargets.cmake
-  DESTINATION lib/cmake/Consumer
-)
-
-include(CMakePackageConfigHelpers)
-# generate the config file that is includes the exports
-configure_package_config_file(${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in
-  "${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake"
-  INSTALL_DESTINATION "lib/cmake/example"
-  NO_SET_AND_CHECK_MACRO
-  NO_CHECK_REQUIRED_COMPONENTS_MACRO
-  )
-
-# install the configuration file
-install(FILES
-  ${CMAKE_CURRENT_BINARY_DIR}/ConsumerConfig.cmake
-  DESTINATION lib/cmake/Consumer
-  )
-
-# generate the export targets for the build tree
-# needs to be after the install(TARGETS ) command
-export(EXPORT ConsumerTargets
-  FILE "${CMAKE_CURRENT_BINARY_DIR}/ConsumerTargets.cmake"
-)
diff --git a/Help/guide/tutorial/Consumer/Config.cmake.in b/Help/guide/tutorial/Consumer/Config.cmake.in
deleted file mode 100644
index 0b3f1e4ef..000000000
--- a/Help/guide/tutorial/Consumer/Config.cmake.in
+++ /dev/null
@@ -1,14 +0,0 @@
-
-@PACKAGE_INIT@
-
-include(CMakeFindDependencyMacro)
-
-function(find_external_dependency name)
-  set(${name}_ROOT ""  CACHE PATH "Root directory to find ${name}")
-  mark_as_advanced(${name}_DIR)
-  find_dependency(${name} PATHS ${${name}_ROOT} REQUIRED)
-endfunction()
-
-find_external_dependency(MathFunctions)
-
-include ( "${CMAKE_CURRENT_LIST_DIR}/ConsumerTargets.cmake" )
diff --git a/Help/guide/tutorial/Consumer/consumer.cxx b/Help/guide/tutorial/Consumer/consumer.cxx
deleted file mode 100644
index ae7877b5a..000000000
--- a/Help/guide/tutorial/Consumer/consumer.cxx
+++ /dev/null
@@ -1,11 +0,0 @@
-// A simple function that computes the square root of a number
-#include <iostream>
-#include <sstream>
-#include <string>
-
-#include "MathFunctions.h"
-
-double string_square_root(std::string const& value)
-{
-  return mathfunctions::sqrt(std::stod(value));
-}
diff --git a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt
index e6cb8baca..32f5e084a 100644
--- a/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step11/MathFunctions/CMakeLists.txt
@@ -15,7 +15,7 @@ if(USE_MYMATH)
 
   # first we add the executable that generates the table
   add_executable(MakeTable MakeTable.cxx)
-  target_link_libraries(MakeTable tutorial_compiler_flags)
+  target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)
 
   # add the command to generate the source code
   add_custom_command(
diff --git a/Help/guide/tutorial/MultiPackage/CMakeLists.txt b/Help/guide/tutorial/Step12/CMakeLists.txt
index 01d417ad4..eca79d9df 100644
--- a/Help/guide/tutorial/MultiPackage/CMakeLists.txt
+++ b/Help/guide/tutorial/Step12/CMakeLists.txt
@@ -1,11 +1,19 @@
-cmake_minimum_required(VERSION 3.10)
+cmake_minimum_required(VERSION 3.15)
 
 # set the project name and version
 project(Tutorial VERSION 1.0)
 
-set(CMAKE_CXX_STANDARD 11)
-set(CMAKE_CXX_STANDARD_REQUIRED True)
+add_library(tutorial_compiler_flags INTERFACE)
+target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)
 
+# add compiler warning flags just when building this project via
+# the BUILD_INTERFACE genex
+set(gcc_like_cxx "$<COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU>")
+set(msvc_cxx "$<COMPILE_LANG_AND_ID:CXX,MSVC>")
+target_compile_options(tutorial_compiler_flags INTERFACE
+  "$<${gcc_like_cxx}:$<BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused>>"
+  "$<${msvc_cxx}:$<BUILD_INTERFACE:-W3>>"
+)
 
 # control where the static and shared libraries are built so that on windows
 # we don't need to tinker with the path to run the executable
diff --git a/Help/guide/tutorial/Step12/CTestConfig.cmake b/Help/guide/tutorial/Step12/CTestConfig.cmake
new file mode 100644
index 000000000..73efdb1f6
--- /dev/null
+++ b/Help/guide/tutorial/Step12/CTestConfig.cmake
@@ -0,0 +1,7 @@
+set(CTEST_PROJECT_NAME "CMakeTutorial")
+set(CTEST_NIGHTLY_START_TIME "00:00:00 EST")
+
+set(CTEST_DROP_METHOD "http")
+set(CTEST_DROP_SITE "my.cdash.org")
+set(CTEST_DROP_LOCATION "/submit.php?project=CMakeTutorial")
+set(CTEST_DROP_SITE_CDASH TRUE)
diff --git a/Help/guide/tutorial/MultiPackage/Config.cmake.in b/Help/guide/tutorial/Step12/Config.cmake.in
index 17cbabd99..17cbabd99 100644
--- a/Help/guide/tutorial/MultiPackage/Config.cmake.in
+++ b/Help/guide/tutorial/Step12/Config.cmake.in
diff --git a/Help/guide/tutorial/MultiPackage/License.txt b/Help/guide/tutorial/Step12/License.txt
index c62d00b9e..c62d00b9e 100644
--- a/Help/guide/tutorial/MultiPackage/License.txt
+++ b/Help/guide/tutorial/Step12/License.txt
diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt
index a2df2a732..720ee6437 100644
--- a/Help/guide/tutorial/MultiPackage/MathFunctions/CMakeLists.txt
+++ b/Help/guide/tutorial/Step12/MathFunctions/CMakeLists.txt
@@ -17,6 +17,7 @@ if(USE_MYMATH)
 
   # first we add the executable that generates the table
   add_executable(MakeTable MakeTable.cxx)
+  target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)
 
   # add the command to generate the source code
   add_custom_command(
@@ -41,19 +42,18 @@ if(USE_MYMATH)
                         POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
                         )
 
+  target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
   target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
 endif()
 
+target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)
+
 # define the symbol stating we are using the declspec(dllexport) when
 # building on windows
 target_compile_definitions(MathFunctions PRIVATE "EXPORTING_MYMATH")
 
-# setup the version numbering
-set_property(TARGET MathFunctions PROPERTY VERSION "1.0.0")
-set_property(TARGET MathFunctions PROPERTY SOVERSION "1")
-
 # install rules
-install(TARGETS MathFunctions
+install(TARGETS MathFunctions tutorial_compiler_flags
         DESTINATION lib
         EXPORT MathFunctionsTargets)
 install(FILES MathFunctions.h DESTINATION include)
diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx
index ee585568c..ee585568c 100644
--- a/Help/guide/tutorial/MultiPackage/MathFunctions/MakeTable.cxx
+++ b/Help/guide/tutorial/Step12/MathFunctions/MakeTable.cxx
diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx
index 014530062..014530062 100644
--- a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.cxx
+++ b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.cxx
diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h
index 3fb547b4a..3fb547b4a 100644
--- a/Help/guide/tutorial/MultiPackage/MathFunctions/MathFunctions.h
+++ b/Help/guide/tutorial/Step12/MathFunctions/MathFunctions.h
diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx
index 5e622beb5..8153f18be 100644
--- a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.cxx
+++ b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.cxx
@@ -17,11 +17,10 @@ double mysqrt(double x)
   // use the table to help find an initial value
   double result = x;
   if (x >= 1 && x < 10) {
+    std::cout << "Use the table to help find an initial value " << std::endl;
     result = sqrtTable[static_cast<int>(x)];
   }
 
-  // if we have both log and exp then use them
-
   // do ten iterations
   for (int i = 0; i < 10; ++i) {
     if (result <= 0) {
diff --git a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h
index e1c42ef0c..e1c42ef0c 100644
--- a/Help/guide/tutorial/MultiPackage/MathFunctions/mysqrt.h
+++ b/Help/guide/tutorial/Step12/MathFunctions/mysqrt.h
diff --git a/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in b/Help/guide/tutorial/Step12/TutorialConfig.h.in
index 8cd2fc9c6..7e4d7fa1f 100644
--- a/Help/guide/tutorial/MultiPackage/TutorialConfig.h.in
+++ b/Help/guide/tutorial/Step12/TutorialConfig.h.in
@@ -1,3 +1,3 @@
-// the configured version number
+// the configured options and settings for Tutorial
 #define Tutorial_VERSION_MAJOR @Tutorial_VERSION_MAJOR@
 #define Tutorial_VERSION_MINOR @Tutorial_VERSION_MINOR@
diff --git a/Help/guide/tutorial/MultiPackage/tutorial.cxx b/Help/guide/tutorial/Step12/tutorial.cxx
index f97805b1c..a4f44d54f 100644
--- a/Help/guide/tutorial/MultiPackage/tutorial.cxx
+++ b/Help/guide/tutorial/Step12/tutorial.cxx
@@ -8,6 +8,7 @@
 int main(int argc, char* argv[])
 {
   if (argc < 2) {
+    // report version
     std::cout << argv[0] << " Version " << Tutorial_VERSION_MAJOR << "."
               << Tutorial_VERSION_MINOR << std::endl;
     std::cout << "Usage: " << argv[0] << " number" << std::endl;
@@ -15,7 +16,7 @@ int main(int argc, char* argv[])
   }
 
   // convert input to double
-  double inputValue = std::stod(argv[1]);
+  const double inputValue = std::stod(argv[1]);
 
   const double outputValue = mathfunctions::sqrt(inputValue);
 
diff --git a/Help/guide/tutorial/index.rst b/Help/guide/tutorial/index.rst
index d74d16047..a844cbf84 100644
--- a/Help/guide/tutorial/index.rst
+++ b/Help/guide/tutorial/index.rst
@@ -45,7 +45,8 @@ The first feature we will add is to provide our executable and project with a
 version number. While we could do this exclusively in the source code, using
 ``CMakeLists.txt`` provides more flexibility.
 
-First, modify the ``CMakeLists.txt`` file to set the version number.
+First, modify the ``CMakeLists.txt`` file to use the :command:`project` command
+to set the project name and version number.
 
 .. literalinclude:: Step2/CMakeLists.txt
   :language: cmake
@@ -102,9 +103,10 @@ Next let's add some C++11 features to our project by replacing ``atof`` with
 
 We will need to explicitly state in the CMake code that it should use the
 correct flags. The easiest way to enable support for a specific C++ standard
-in CMake is by using the ``CMAKE_CXX_STANDARD`` variable. For this tutorial,
-set the ``CMAKE_CXX_STANDARD`` variable in the ``CMakeLists.txt`` file to 11
-and ``CMAKE_CXX_STANDARD_REQUIRED`` to True:
+in CMake is by using the :variable:`CMAKE_CXX_STANDARD` variable. For this
+tutorial, set the :variable:`CMAKE_CXX_STANDARD` variable in the
+``CMakeLists.txt`` file to 11 and :variable:`CMAKE_CXX_STANDARD_REQUIRED` to
+True:
 
 .. literalinclude:: Step2/CMakeLists.txt
   :language: cmake
@@ -113,7 +115,8 @@ and ``CMAKE_CXX_STANDARD_REQUIRED`` to True:
 Build and Test
 --------------
 
-Run **cmake** or **cmake-gui** to configure the project and then build it
+Run the :manual:`cmake <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool.
 
 For example, from the command line we could navigate to the
@@ -156,11 +159,11 @@ directory:
 .. literalinclude:: Step3/MathFunctions/CMakeLists.txt
   :language: cmake
 
-To make use of the new library we will add an ``add_subdirectory`` call in the
-top-level ``CMakeLists.txt`` file so that the library will get built. We add
-the new library to the executable, and add ``MathFunctions`` as an include
-directory so that the ``mqsqrt.h`` header file can be found. The last few lines
-of the top-level ``CMakeLists.txt`` file should now look like:
+To make use of the new library we will add an :command:`add_subdirectory`
+call in the top-level ``CMakeLists.txt`` file so that the library will get
+built. We add the new library to the executable, and add ``MathFunctions`` as
+an include directory so that the ``mqsqrt.h`` header file can be found. The
+last few lines of the top-level ``CMakeLists.txt`` file should now look like:
 
 .. code-block:: cmake
 
@@ -180,7 +183,7 @@ of the top-level ``CMakeLists.txt`` file should now look like:
                                   )
 
 Now let us make the MathFunctions library optional. While for the tutorial
-there really isn’t any need to do so, for larger projects this is a common
+there really isn't any need to do so, for larger projects this is a common
 occurrence. The first step is to add an option to the top-level
 ``CMakeLists.txt`` file.
 
@@ -189,10 +192,11 @@ occurrence. The first step is to add an option to the top-level
   :start-after: # should we use our own math functions
   :end-before: # add the MathFunctions library
 
-This option will be displayed in the CMake GUI and ccmake with a default
-value of ON that can be changed by the user. This setting will be stored in
-the cache so that the user does not need to set the value each time they run
-CMake on a build directory.
+This option will be displayed in the :manual:`cmake-gui <cmake-gui(1)>` and
+:manual:`ccmake <ccmake(1)>`
+with a default value of ON that can be changed by the user. This setting will
+be stored in the cache so that the user does not need to set the value each
+time they run CMake on a build directory.
 
 The next change is to make building and linking the MathFunctions library
 conditional. To do this we change the end of the top-level ``CMakeLists.txt``
@@ -234,11 +238,13 @@ Since the source code now requires ``USE_MYMATH`` we can add it to
 **Exercise**: Why is it important that we configure ``TutorialConfig.h.in``
 after the option for ``USE_MYMATH``? What would happen if we inverted the two?
 
-Run **cmake** or **cmake-gui** to configure the project and then build it
+Run the :manual:`cmake  <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool. Then run the built Tutorial executable.
 
-Use ccmake or the CMake GUI to update the value of ``USE_MYMATH``. Rebuild and
-run the tutorial again. Which function gives better results, sqrt or mysqrt?
+Use the :manual:`ccmake <ccmake(1)>` executable or the :manual:`cmake-gui <cmake-gui(1)>`
+to update the value of ``USE_MYMATH``. Rebuild and run the tutorial again.
+Which function gives better results, sqrt or mysqrt?
 
 Adding Usage Requirements for Library (Step 3)
 ==============================================
@@ -248,19 +254,20 @@ link and include line while also giving more control over the transitive
 property of targets inside CMake. The primary commands that leverage usage
 requirements are:
 
-  - ``target_compile_definitions``
-  - ``target_compile_options``
-  - ``target_include_directories``
-  - ``target_link_libraries``
+  - :command:`target_compile_definitions`
+  - :command:`target_compile_options`
+  - :command:`target_include_directories`
+  - :command:`target_link_libraries`
 
 Let's refactor our code from `Adding a Library (Step 2)`_ to use the modern
 CMake approach of usage requirements. We first state that anybody linking to
 MathFunctions needs to include the current source directory, while
-MathFunctions itself doesn't. So  this can become an ``INTERFACE`` usage
+MathFunctions itself doesn't. So this can become an ``INTERFACE`` usage
 requirement.
 
 Remember ``INTERFACE`` means things that consumers require but the producer
-doesn't. Add the following lines to the end of ``MathFunctions/CMakeLists.txt``:
+doesn't. Add the following lines to the end of
+``MathFunctions/CMakeLists.txt``:
 
 .. literalinclude:: Step4/MathFunctions/CMakeLists.txt
   :language: cmake
@@ -281,9 +288,10 @@ And here:
   :language: cmake
   :start-after: # so that we will find TutorialConfig.h
 
-Once this is done, run **cmake** or **cmake-gui** to configure the project
-and then build it with your chosen build tool or by using ``cmake --build .``
-from the build directory.
+Once this is done, run the :manual:`cmake  <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
+with your chosen build tool or by using ``cmake --build .`` from the build
+directory.
 
 Installing and Testing (Step 4)
 ===============================
@@ -312,16 +320,17 @@ And to the end of the top-level ``CMakeLists.txt`` we add:
 
 That is all that is needed to create a basic local install of the tutorial.
 
-Run **cmake** or **cmake-gui** to configure the project and then build it
-with your chosen build tool. Run the install step by typing
-``cmake --install .`` (introduced in 3.15, older versions of CMake must use
-``make install``) from the command line, or build the ``INSTALL`` target from
-an IDE. This will install the appropriate header files, libraries, and
-executables.
-
-The CMake variable ``CMAKE_INSTALL_PREFIX`` is used to determine the root of
-where the files will be installed. If using ``cmake --install`` a custom
-installation directory can be given via ``--prefix`` argument. For
+Run the :manual:`cmake  <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
+with your chosen build tool. Run the install step by using the ``install``
+option of the :manual:`cmake  <cmake(1)>` command (introduced in 3.15, older
+versions of CMake must use ``make install``) from the command line, or build
+the ``INSTALL`` target from an IDE. This will install the appropriate header
+files, libraries, and executables.
+
+The CMake variable :variable:`CMAKE_INSTALL_PREFIX` is used to determine the
+root of where the files will be installed. If using ``cmake --install`` a
+custom installation directory can be given via the ``--prefix`` argument. For
 multi-configuration tools, use the ``--config`` argument to specify the
 configuration.
 
@@ -339,25 +348,25 @@ the application is working correctly.
   :start-after: # enable testing
 
 The first test simply verifies that the application runs, does not segfault or
-otherwise crash, and has a zero return value. This is the basic form of a CTest
-test.
+otherwise crash, and has a zero return value. This is the basic form of a
+CTest test.
 
-The next test makes use of the ``PASS_REGULAR_EXPRESSION`` test property to
-verify that the output of the test contains certain strings. In this case,
-verifying that the usage message is printed when an incorrect number of
-arguments are provided.
+The next test makes use of the :prop_test:`PASS_REGULAR_EXPRESSION` test
+property to verify that the output of the test contains certain strings. In
+this case, verifying that the usage message is printed when an incorrect number
+of arguments are provided.
 
 Lastly, we have a function called ``do_test`` that runs the application and
 verifies that the computed square root is correct for given input. For each
 invocation of ``do_test``, another test is added to the project with a name,
 input, and expected results based on the passed arguments.
 
-Rebuild the application and then cd to the binary directory and run
-``ctest -N`` and ``ctest -VV``. For multi-config generators (e.g. Visual
-Studio), the configuration type must be specified. To run tests in Debug mode,
-for example, use ``ctest -C Debug -VV`` from the build directory (not the
-Debug subdirectory!). Alternatively, build the ``RUN_TESTS`` target from the
-IDE.
+Rebuild the application and then cd to the binary directory and run the
+:manual:`ctest <ctest(1)>` executable: ``ctest -N`` and ``ctest -VV``. For
+multi-config generators (e.g. Visual Studio), the configuration type must be
+specified. To run tests in Debug mode, for example, use ``ctest -C Debug -VV``
+from the build directory (not the Debug subdirectory!). Alternatively, build
+the ``RUN_TESTS`` target from the IDE.
 
 Adding System Introspection (Step 5)
 ====================================
@@ -370,7 +379,7 @@ tutorial assume that they are not common.
 
 If the platform has ``log`` and ``exp`` then we will use them to compute the
 square root in the ``mysqrt`` function. We first test for the availability of
-these functions using the ``CheckSymbolExists`` module in the top-level
+these functions using the :module:`CheckSymbolExists` module in the top-level
 ``CMakeLists.txt``. We're going to use the new defines in
 ``TutorialConfig.h.in``, so be sure to set them before that file is configured.
 
@@ -388,22 +397,29 @@ from ``mysqrt.cxx``:
   #cmakedefine HAVE_LOG
   #cmakedefine HAVE_EXP
 
-Modify ``mysqrt.cxx`` to include cmath. Next, in that same file in the
-``mysqrt`` function we can provide an alternate implementation based on
-``log`` and ``exp`` if they are available on the system using the following
-code (don't forget the ``#endif`` before returning the result!):
+If ``log`` and ``exp`` are available on the system, then we will use them to
+compute the square root in the ``mysqrt`` function. Add the following code to
+the ``mysqrt`` function in ``MathFunctions/mysqrt.cxx`` (don't forget the
+``#endif`` before returning the result!):
 
 .. literalinclude:: Step6/MathFunctions/mysqrt.cxx
   :language: c++
   :start-after: // if we have both log and exp then use them
   :end-before: // do ten iterations
 
-Run **cmake** or **cmake-gui** to configure the project and then build it
+We will also need to modify ``mysqrt.cxx`` to include ``cmath``.
+
+.. literalinclude:: Step6/MathFunctions/mysqrt.cxx
+  :language: c++
+  :end-before: #include <iostream>
+
+Run the :manual:`cmake  <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool and run the Tutorial executable.
 
 You will notice that we're not using ``log`` and ``exp``, even if we think they
-should be available. We should realize quickly that we have forgotten to include
-``TutorialConfig.h`` in ``mysqrt.cxx``.
+should be available. We should realize quickly that we have forgotten to
+include ``TutorialConfig.h`` in ``mysqrt.cxx``.
 
 We will also need to update ``MathFunctions/CMakeLists.txt`` so ``mysqrt.cxx``
 knows where this file is located:
@@ -415,10 +431,10 @@ knows where this file is located:
             PRIVATE ${CMAKE_BINARY_DIR}
             )
 
-After making this update, go ahead and build the project again and run the built
-Tutorial executable. If ``log`` and ``exp`` are still not being used, open the
-generated ``TutorialConfig.h`` file from the build directory. Maybe they aren't
-available on the current system?
+After making this update, go ahead and build the project again and run the
+built Tutorial executable. If ``log`` and ``exp`` are still not being used,
+open the generated ``TutorialConfig.h`` file from the build directory. Maybe
+they aren't available on the current system?
 
 Which function gives better results now, sqrt or mysqrt?
 
@@ -427,7 +443,7 @@ Specify Compile Definition
 
 Is there a better place for us to save the ``HAVE_LOG`` and ``HAVE_EXP`` values
 other than in ``TutorialConfig.h``? Let's try to use
-``target_compile_definitions``.
+:command:`target_compile_definitions`.
 
 First, remove the defines from ``TutorialConfig.h.in``. We no longer need to
 include ``TutorialConfig.h`` from ``mysqrt.cxx`` or the extra include in
@@ -460,8 +476,8 @@ First, let's remove the check for the ``log`` and ``exp`` functions in
 ``HAVE_EXP`` from ``mysqrt.cxx``. At the same time, we can remove
 :code:`#include <cmath>`.
 
-In the ``MathFunctions`` subdirectory, a new source file named ``MakeTable.cxx``
-has been provided to generate the table.
+In the ``MathFunctions`` subdirectory, a new source file named
+``MakeTable.cxx`` has been provided to generate the table.
 
 After reviewing the file, we can see that the table is produced as valid C++
 code and that the output filename is passed in as an argument.
@@ -510,7 +526,8 @@ Now let's use the generated table. First, modify ``mysqrt.cxx`` to include
   :language: c++
   :start-after: // a hack square root calculation using simple operations
 
-Run **cmake** or **cmake-gui** to configure the project and then build it
+Run the :manual:`cmake  <cmake(1)>` executable or the
+:manual:`cmake-gui <cmake-gui(1)>` to configure the project and then build it
 with your chosen build tool.
 
 When this project is built it will first build the ``MakeTable`` executable.
@@ -530,26 +547,28 @@ previously in `Installing and Testing (Step 4)`_ , where we were
 installing the binaries that we had built from the source code. In this
 example we will be building installation packages that support binary
 installations and package management features. To accomplish this we will use
-CPack to create platform specific installers. Specifically we need to add
-a few lines to the bottom of our top-level ``CMakeLists.txt`` file.
+CPack to create platform specific installers. Specifically we need to add a
+few lines to the bottom of our top-level ``CMakeLists.txt`` file.
 
 .. literalinclude:: Step8/CMakeLists.txt
   :language: cmake
   :start-after: # setup installer
 
 That is all there is to it. We start by including
-``InstallRequiredSystemLibraries``. This module will include any runtime
-libraries that are needed by the project for the current platform. Next we
-set some CPack variables to where we have stored the license and version
+:module:`InstallRequiredSystemLibraries`. This module will include any runtime
+libraries that are needed by the project for the current platform. Next we set
+some CPack variables to where we have stored the license and version
 information for this project. The version information was set earlier in this
 tutorial and the ``license.txt`` has been included in the top-level source
 directory for this step.
 
-Finally we include the CPack module which will use these variables and some
-other properties of the current system to setup an installer.
+Finally we include the :module:`CPack module <CPack>` which will use these
+variables and some other properties of the current system to setup an
+installer.
 
-The next step is to build the project in the usual manner and then run
-CPack on it. To build a binary distribution, from the binary directory run:
+The next step is to build the project in the usual manner and then run the
+:manual:`cpack <cpack(1)>` executable. To build a binary distribution, from the
+binary directory run:
 
 .. code-block:: console
 
@@ -571,16 +590,17 @@ To create a source distribution you would type:
 Alternatively, run ``make package`` or right click the ``Package`` target and
 ``Build Project`` from an IDE.
 
-Run the installer found in the binary directory. Then run the
-installed executable and verify that it works.
+Run the installer found in the binary directory. Then run the installed
+executable and verify that it works.
 
 Adding Support for a Dashboard (Step 8)
 =======================================
 
-Adding support for submitting our test results to a dashboard is very easy. We
+Adding support for submitting our test results to a dashboard is simple. We
 already defined a number of tests for our project in `Testing Support`_. Now we
 just have to run those tests and submit them to a dashboard. To include support
-for dashboards we include the CTest module in our top-level ``CMakeLists.txt``.
+for dashboards we include the :module:`CTest` module in our top-level
+``CMakeLists.txt``.
 
 Replace:
 
@@ -596,8 +616,8 @@ With:
   # enable dashboard scripting
   include(CTest)
 
-The CTest module will automatically call ``enable_testing()``, so
-we can remove it from our CMake files.
+The :module:`CTest` module will automatically call ``enable_testing()``, so we
+can remove it from our CMake files.
 
 We will also need to create a ``CTestConfig.cmake`` file in the top-level
 directory where we can specify the name of the project and where to submit the
@@ -606,9 +626,11 @@ dashboard.
 .. literalinclude:: Step9/CTestConfig.cmake
   :language: cmake
 
-CTest will read in this file when it runs. To create a simple dashboard you can
-run **cmake** or **cmake-gui** to configure the project, but do not build it
-yet. Instead, change directory to the binary tree, and then run::
+The :manual:`ctest <ctest(1)>` executable will read in this file when it runs.
+To create a simple dashboard you can run the :manual:`cmake <cmake(1)>`
+executable or the :manual:`cmake-gui <cmake-gui(1)>` to configure the project,
+but do not build it yet. Instead, change directory to the binary tree, and then
+run:
 
   ctest [-VV] -D Experimental
 
@@ -619,26 +641,26 @@ type must be specified::
 
 Or, from an IDE, build the ``Experimental`` target.
 
-``ctest`` will build and test the project and submit the results to the Kitware
-public dashboard. The results of your dashboard will be uploaded to Kitware's
-public dashboard here: https://my.cdash.org/index.php?project=CMakeTutorial.
+The :manual:`ctest <ctest(1)>` executable will build and test the project and
+submit the results to Kitware's public dashboard:
+https://my.cdash.org/index.php?project=CMakeTutorial.
 
 Mixing Static and Shared (Step 9)
 =================================
 
-In this section we will show how by using the ``BUILD_SHARED_LIBS`` variable
-we can control the default behavior of ``add_library``, and allow control
-over how libraries without an explicit type (``STATIC``, ``SHARED``, ``MODULE``
-or ``OBJECT``) are built.
+In this section we will show how the :variable:`BUILD_SHARED_LIBS` variable can
+be used to control the default behavior of :command:`add_library`,
+and allow control over how libraries without an explicit type (``STATIC``,
+``SHARED``, ``MODULE`` or ``OBJECT``) are built.
 
-To accomplish this we need to add ``BUILD_SHARED_LIBS`` to the top-level
-``CMakeLists.txt``. We use the ``option`` command as it allows users to
-optionally select if the value should be On or Off.
+To accomplish this we need to add :variable:`BUILD_SHARED_LIBS` to the
+top-level ``CMakeLists.txt``. We use the :command:`option` command as it allows
+users to optionally select if the value should be ON or OFF.
 
 Next we are going to refactor MathFunctions to become a real library that
 encapsulates using ``mysqrt`` or ``sqrt``, instead of requiring the calling
 code to do this logic. This will also mean that ``USE_MYMATH`` will not control
-building MathFuctions, but instead will control the behavior of this library.
+building MathFunctions, but instead will control the behavior of this library.
 
 The first step is to update the starting section of the top-level
 ``CMakeLists.txt`` to look like:
@@ -680,8 +702,8 @@ Finally, update ``MathFunctions/MathFunctions.h`` to use dll export defines:
 At this point, if you build everything, you will notice that linking fails
 as we are combining a static library without position independent code with a
 library that has position independent code. The solution to this is to
-explicitly set the ``POSITION_INDEPENDENT_CODE`` target property of SqrtLibrary
-to be True no matter the build type.
+explicitly set the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property of
+SqrtLibrary to be True no matter the build type.
 
 .. literalinclude:: Step10/MathFunctions/CMakeLists.txt
   :language: cmake
@@ -694,35 +716,39 @@ Using CMake documentation can you find a helper module to simplify this?
 Adding Generator Expressions (Step 10)
 ======================================
 
-Generator expressions are evaluated during build system generation to produce
-information specific to each build configuration.
+:manual:`Generator expressions <cmake-generator-expressions(7)>` are evaluated
+during build system generation to produce information specific to each build
+configuration.
 
-Generator expressions are allowed in the context of many target properties,
-such as ``LINK_LIBRARIES``, ``INCLUDE_DIRECTORIES``, ``COMPILE_DEFINITIONS``
-and others. They may also be used when using commands to populate those
-properties, such as ``target_link_libraries()``,
-``target_include_directories()``,
-``target_compile_definitions()`` and others.
+:manual:`Generator expressions <cmake-generator-expressions(7)>` are allowed in
+the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`,
+:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and others.
+They may also be used when using commands to populate those properties, such as
+:command:`target_link_libraries`, :command:`target_include_directories`,
+:command:`target_compile_definitions` and others.
 
-Generator expressions may be used to enable conditional linking, conditional
-definitions used when compiling, conditional include directories and more.
-The conditions may be based on the build configuration, target properties,
-platform information or any other queryable information.
+:manual:`Generator expressions <cmake-generator-expressions(7)>`  may be used
+to enable conditional linking, conditional definitions used when compiling,
+conditional include directories and more. The conditions may be based on the
+build configuration, target properties, platform information or any other
+queryable information.
 
-There are different types of generator expressions including Logical,
-Informational, and Output expressions.
+There are different types of
+:manual:`generator expressions <cmake-generator-expressions(7)>` including
+Logical, Informational, and Output expressions.
 
 Logical expressions are used to create conditional output. The basic
 expressions are the 0 and 1 expressions. A ``$<0:...>`` results in the empty
 string, and ``<1:...>`` results in the content of "...".  They can also be
 nested.
 
-A common usage of generator expressions is to conditionally add compiler
-flags, such as those for language levels or warnings. A nice pattern is
-to associate this information to an ``INTERFACE`` target allowing this
-information to propagate. Lets start by constructing an ``INTERFACE``
-target and specifying the required C++ standard level of ``11`` instead
-of using ``CMAKE_CXX_STANDARD``.
+A common usage of
+:manual:`generator expressions <cmake-generator-expressions(7)>` is to
+conditionally add compiler flags, such as those for language levels or
+warnings. A nice pattern is to associate this information to an ``INTERFACE``
+target allowing this information to propagate. Lets start by constructing an
+``INTERFACE`` target and specifying the required C++ standard level of ``11``
+instead of using :variable:`CMAKE_CXX_STANDARD`.
 
 So the following code:
 
@@ -739,11 +765,10 @@ Would be replaced with:
   :end-before: # add compiler warning flags just when building this project via
 
 
-Next we add the desired compiler warning flags that we want for our
-project. As warning flags vary based on the compiler we use
-the ``COMPILE_LANG_AND_ID`` generator expression to control which
-flags to apply given a language and a set of compiler ids as seen
-below:
+Next we add the desired compiler warning flags that we want for our project. As
+warning flags vary based on the compiler we use the ``COMPILE_LANG_AND_ID``
+generator expression to control which flags to apply given a language and a set
+of compiler ids as seen below:
 
 .. literalinclude:: Step11/CMakeLists.txt
   :language: cmake
@@ -755,8 +780,8 @@ Looking at this we see that the warning flags are encapsulated inside a
 project will not inherit our warning flags.
 
 
-**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that
-all targets have a ``target_link_libraries()`` call to ``tutorial_compiler_flags``.
+**Exercise**: Modify ``MathFunctions/CMakeLists.txt`` so that all targets have
+a :command:`target_link_libraries` call to ``tutorial_compiler_flags``.
 
 
 Adding Export Configuration (Step 11)
@@ -771,12 +796,12 @@ The next step is to add the necessary information so that other CMake projects
 can use our project, be it from a build directory, a local install or when
 packaged.
 
-The first step is to update our ``install(TARGETS)`` commands to not only
-specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword
+The first step is to update our :command:`install(TARGETS)` commands to not
+only specify a ``DESTINATION`` but also an ``EXPORT``. The ``EXPORT`` keyword
 generates and installs a CMake file containing code to import all targets
-listed in the install command from the installation tree. So let's go ahead
-and explicitly ``EXPORT`` the MathFunctions library by updating the
-``install`` command in ``MathFunctions/CMakeLists.txt`` to look like:
+listed in the install command from the installation tree. So let's go ahead and
+explicitly ``EXPORT`` the MathFunctions library by updating the ``install``
+command in ``MathFunctions/CMakeLists.txt`` to look like:
 
 .. literalinclude:: Complete/MathFunctions/CMakeLists.txt
   :language: cmake
@@ -806,12 +831,12 @@ you will see that CMake will generate an error that looks like:
 What CMake is trying to say is that during generating the export information
 it will export a path that is intrinsically tied to the current machine and
 will not be valid on other machines. The solution to this is to update the
-MathFunctions ``target_include_directories`` to understand that it needs
+MathFunctions :command:`target_include_directories` to understand that it needs
 different ``INTERFACE`` locations when being used from within the build
 directory and from an install / package. This means converting the
-``target_include_directories`` call for MathFunctions to look like:
+:command:`target_include_directories` call for MathFunctions to look like:
 
-.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
+.. literalinclude:: Step12/MathFunctions/CMakeLists.txt
   :language: cmake
   :start-after: # to find MathFunctions.h, while we don't.
   :end-before: # should we use our own math functions
@@ -821,16 +846,16 @@ warn anymore.
 
 At this point, we have CMake properly packaging the target information that is
 required but we will still need to generate a ``MathFunctionsConfig.cmake`` so
-that the CMake ``find_package`` command can find our project. So let's go
+that the CMake :command:`find_package` command can find our project. So let's go
 ahead and add a new file to the top-level of the project called
 ``Config.cmake.in`` with the following contents:
 
-.. literalinclude:: Complete/Config.cmake.in
+.. literalinclude:: Step12/Config.cmake.in
 
 Then, to properly configure and install that file, add the following to the
 bottom of the top-level ``CMakeLists.txt``:
 
-.. literalinclude:: Complete/CMakeLists.txt
+.. literalinclude:: Step12/CMakeLists.txt
   :language: cmake
   :start-after: # install the configuration targets
   :end-before: # generate the export
@@ -840,7 +865,7 @@ project that can be used after the project has been installed or packaged. If
 we want our project to also be used from a build directory we only have to add
 the following to the bottom of the top level ``CMakeLists.txt``:
 
-.. literalinclude:: Complete/CMakeLists.txt
+.. literalinclude:: Step12/CMakeLists.txt
   :language: cmake
   :start-after: # needs to be after the install(TARGETS ) command
 
@@ -848,55 +873,81 @@ With this export call we now generate a ``Targets.cmake``, allowing the
 configured ``MathFunctionsConfig.cmake`` in the build directory to be used by
 other projects, without needing it to be installed.
 
-Import a CMake Project (Consumer)
-=================================
+Packaging Debug and Release (Step 12)
+=====================================
 
-This example shows how a project can find other CMake packages that
-generate ``Config.cmake`` files.
+**Note:** This example is valid for single-configuration generators and will
+not work for multi-configuration generators (e.g. Visual Studio).
 
-It also shows how to state a project's external dependencies when generating
-a ``Config.cmake``.
+By default, CMake's model is that a build directory only contains a single
+configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo. It is
+possible, however, to setup CPack to bundle multiple build directories and
+construct a package that contains multiple configurations of the same project.
 
-Packaging Debug and Release (MultiPackage)
-==========================================
+First, we want to ensure that the debug and release builds use different names
+for the executables and libraries that will be installed. Let's use `d` as the
+postfix for the debug executable and libraries.
 
-By default CMake's model is that a build directory only contains a single
-configuration, be it Debug, Release, MinSizeRel, or RelWithDebInfo.
+Set :variable:`CMAKE_DEBUG_POSTFIX` near the beginning of the top-level
+``CMakeLists.txt`` file:
 
-But it is possible to setup CPack to bundle multiple build directories at the
-same time to build a package that contains multiple configurations of the
-same project.
+.. literalinclude:: Complete/CMakeLists.txt
+  :language: cmake
+  :start-after: project(Tutorial VERSION 1.0)
+  :end-before: target_compile_features(tutorial_compiler_flags
+
+And the :prop_tgt:`DEBUG_POSTFIX` property on the tutorial executable:
+
+.. literalinclude:: Complete/CMakeLists.txt
+  :language: cmake
+  :start-after: # add the executable
+  :end-before: # add the binary tree to the search path for include files
+
+Let's also add version numbering to the MathFunctions library. In
+``MathFunctions/CMakeLists.txt``, set the :prop_tgt:`VERSION` and
+:prop_tgt:`SOVERSION` properties:
 
-First we need to construct a directory called ``multi_config``, which
-will contain all the builds that we want to package together.
+.. literalinclude:: Complete/MathFunctions/CMakeLists.txt
+  :language: cmake
+  :start-after: # setup the version numbering
+  :end-before: # install rules
 
-Second create a ``debug`` and ``release`` directory underneath
-``multi_config``. At the end you should have a layout that looks like:
+From the ``Step12`` directory, create ``debug`` and ``release``
+subbdirectories. The layout will look like:
 
 .. code-block:: none
 
-  ─ multi_config
-      ├── debug
-      └── release
+  - Step12
+     - debug
+     - release
 
-Now we need to setup debug and release builds, which would roughly entail
-the following:
+Now we need to setup debug and release builds. We can use
+:variable:`CMAKE_BUILD_TYPE` to set the configuration type:
 
 .. code-block:: console
 
   cd debug
-  cmake -DCMAKE_BUILD_TYPE=Debug ../../MultiPackage/
+  cmake -DCMAKE_BUILD_TYPE=Debug ..
   cmake --build .
   cd ../release
-  cmake -DCMAKE_BUILD_TYPE=Release ../../MultiPackage/
+  cmake -DCMAKE_BUILD_TYPE=Release ..
   cmake --build .
-  cd ..
 
+Now that both the debug and release builds are complete, we can use a custom
+configuration file to package both builds into a single release. In the
+``Step12`` directory, create a file called ``MultiCPackConfig.cmake``. In this
+file, first include the default configuration file that was created by the
+:manual:`cmake  <cmake(1)>` executable.
+
+Next, use the ``CPACK_INSTALL_CMAKE_PROJECTS`` variable to specify which
+projects to install. In this case, we want to install both debug and release.
+
+.. literalinclude:: Complete/MultiCPackConfig.cmake
+  :language: cmake
 
-Now that both the debug and release builds are complete, we can use
-a custom ``MultiCPackConfig.cmake`` file to package both builds into a single
-release.
+From the ``Step12`` directory, run :manual:`cpack <cpack(1)>` specifying our
+custom configuration file with the ``config`` option:
 
 .. code-block:: console
 
-  cpack --config ../../MultiPackage/MultiCPackConfig.cmake
+  cpack --config MultiCPackConfig.cmake
diff --git a/Help/guide/user-interaction/GUI-Add-Entry.png b/Help/guide/user-interaction/GUI-Add-Entry.png
new file mode 100644
index 000000000..1e9be7efa
--- /dev/null
+++ b/Help/guide/user-interaction/GUI-Add-Entry.png
diff --git a/Help/guide/user-interaction/GUI-Choose-Generator.png b/Help/guide/user-interaction/GUI-Choose-Generator.png
new file mode 100644
index 000000000..19ad2c014
--- /dev/null
+++ b/Help/guide/user-interaction/GUI-Choose-Generator.png
diff --git a/Help/guide/user-interaction/GUI-Configure-Dialog.png b/Help/guide/user-interaction/GUI-Configure-Dialog.png
new file mode 100644
index 000000000..9839cacfa
--- /dev/null
+++ b/Help/guide/user-interaction/GUI-Configure-Dialog.png
diff --git a/Help/guide/user-interaction/GUI-Source-Binary.png b/Help/guide/user-interaction/GUI-Source-Binary.png
new file mode 100644
index 000000000..e33835468
--- /dev/null
+++ b/Help/guide/user-interaction/GUI-Source-Binary.png
diff --git a/Help/guide/user-interaction/index.rst b/Help/guide/user-interaction/index.rst
new file mode 100644
index 000000000..3a1038fa7
--- /dev/null
+++ b/Help/guide/user-interaction/index.rst
@@ -0,0 +1,686 @@
+User Interaction Guide
+**********************
+
+.. only:: html
+
+   .. contents::
+
+Introduction
+============
+
+Where a software package supplies a CMake-based buildsystem
+with the source of their software, the consumer of the
+software is required to run a CMake user interaction tool
+in order to build it.
+
+Well-behaved CMake-based buildsystems do not create any
+output in the source directory, so typically, the user
+performs an out-of-source build and performs the build
+there.  First, CMake must be instructed to generate a
+suitable buildsystem, then the user invokes a build tool
+to process that generated buildsystem.  The generated
+buildsystem is specific to the machine used to generate
+it and is not redistributable.  Each consumer of a provided
+source software package is required to use CMake to
+generate a buildsystem specific to their system.
+
+Generated buildsystems should generally be treated as
+read-only. The CMake files as a primary artifact should
+completely specify the buildsystem and there should be no
+reason to populate properties manually in an IDE for
+example after generating the buildsystem.  CMake will
+periodically rewrite the generated buildsystem, so
+modifications by users will be overwritten.
+
+The features and user interfaces described in this manual
+are available for all CMake-based build systems by virtue
+of providing CMake files.
+
+The CMake tooling may report errors to the user when
+processing provided CMake files, such as reporting that
+the compiler is not supported, or the compiler does not
+support a required compile option, or a dependency can
+not be found.  These errors must be resolved by the user
+by choosing a different compiler,
+:guide:`installing dependencies <Using Dependencies Guide>`,
+or instructing CMake where to find them, etc.
+
+Command Line cmake tool
+-----------------------
+
+A simple but typical use of :manual:`cmake(1)` with a fresh
+copy of software source code is to create a build directory
+and invoke cmake there:
+
+.. code-block:: console
+
+  $ cd some_software-1.4.2
+  $ mkdir build
+  $ cd build
+  $ cmake .. -DCMAKE_INSTALL_PREFIX=/opt/the/prefix
+  $ cmake --build .
+  $ cmake --build . --target install
+
+It is recommended to build in a separate directory to the
+source because that keeps the source directory pristine,
+allows for building a single source with multiple
+toolchains, and allows easy clearing of build artifacts by
+simply deleting the build directory.
+
+The CMake tooling may report warnings which are intended
+for the provider of the software, not intended for the
+consumer of the software.  Such warnings end with "This
+warning is for project developers".  Users may disable
+such warnings by passing the ``-Wno-dev`` flag to
+:manual:`cmake(1)`.
+
+cmake-gui tool
+--------------
+
+Users more accustomed to GUI interfaces may use the
+:manual:`cmake-gui(1)` tool to invoke CMake and generate
+a buildsystem.
+
+The source and binary directories must first be
+populated.  It is always advised to use different
+directories for the source and the build.
+
+.. image:: /guide/user-interaction/GUI-Source-Binary.png
+
+Generating a Buildsystem
+========================
+
+There are several user interface tools which may be used
+to generate a buildsystem from CMake files.  The
+:manual:`ccmake(1)` and :manual:`cmake-gui(1)` tools guide
+the user through setting the various necessary options.
+The :manual:`cmake(1)` tool can be invoked to specify
+options on the command line.  This manual describes options
+which may be set using any of the user interface tools,
+though the mode of setting an option is different for each
+tool.
+
+Command line environment
+------------------------
+
+When invoking :manual:`cmake(1)` with a command line
+buildsystem such as ``Makefiles`` or ``Ninja``, it is
+necessary to use the correct build environment to
+ensure that build tools are available. CMake must be
+able to find the appropriate
+:variable:`build tool <CMAKE_MAKE_PROGRAM>`,
+compiler, linker and other tools as needed.
+
+On Linux systems, the appropriate tools are often
+provided in system-wide locations and may be readily
+installed through the system package manager. Other
+toolchains provided by the user or installed in
+non-default locations can also be used.
+
+When cross-compiling, some platforms may require
+environment variables to be set or may provide
+scripts to set the environment.
+
+Visual Studio ships multiple command prompts and
+``vcvarsall.bat`` scripts for setting up the
+correct environments for command line buildsystems. While
+not strictly necessary to use a corresponding
+command line environment when using a Visual Studio
+generator, doing so has no disadvantages.
+
+When using Xcode, there can be more than one Xcode
+version installed.  Which one to use can be selected
+in a number of different ways, but the most common
+methods are:
+
+* Setting the default version in the preferences
+  of the Xcode IDE.
+* Setting the default version via the ``xcode-select``
+  command line tool.
+* Overriding the default version by setting the
+  ``DEVELOPER_DIR`` environment variable when running
+  CMake and the build tool.
+
+Command line ``-G`` option
+--------------------------
+
+CMake chooses a generator by default based on the
+platform.  Usually, the default generator is sufficient
+to allow the user to proceed to build the software.
+
+The user may override the default generator with
+the ``-G`` option:
+
+.. code-block:: console
+
+  $ cmake .. -G Ninja
+
+The output of ``cmake --help`` includes a list of
+:manual:`generators <cmake-generators(7)>` available
+for the user to choose from.  Note that generator
+names are case sensitive.
+
+On Unix-like systems (including Mac OS X), the
+:generator:`Unix Makefiles` generator is used by
+default.  A variant of that generator can also be used
+on Windows in various environments, such as the
+:generator:`NMake Makefiles` and
+:generator:`MinGW Makefiles` generator.  These generators
+generate a ``Makefile`` variant which can be executed
+with ``make``, ``gmake``, ``nmake`` or similar tools.
+See the individual generator documentation for more
+information on targeted environments and tools.
+
+The :generator:`Ninja` generator is available on all
+major platforms. ``ninja`` is a build tool similar
+in use-cases to ``make``, but with a focus on
+performance and efficiency.
+
+On Windows, :manual:`cmake(1)` can be used to generate
+solutions for the Visual Studio IDE.  Visual Studio
+versions may be specified by the product name of the
+IDE, which includes a four-digit year.  Aliases are
+provided for other means by which Visual Studio
+versions are sometimes referred to, such as two
+digits which correspond to the product version of the
+VisualC++ compiler, or a combination of the two:
+
+.. code-block:: console
+
+  $ cmake .. -G "Visual Studio 2019"
+  $ cmake .. -G "Visual Studio 16"
+  $ cmake .. -G "Visual Studio 16 2019"
+
+Visual Studio generators can target different architectures.
+One can specify the target architecture using the `-A` option:
+
+.. code-block:: console
+
+  cmake .. -G "Visual Studio 2019" -A x64
+  cmake .. -G "Visual Studio 16" -A ARM
+  cmake .. -G "Visual Studio 16 2019" -A ARM64
+
+On Apple, the :generator:`Xcode` generator may be used to
+generate project files for the Xcode IDE.
+
+Some IDEs such as KDevelop4, QtCreator and CLion have
+native support for CMake-based buildsystems.  Those IDEs
+provide user interface for selecting an underlying
+generator to use, typically a choice between a ``Makefile``
+or a ``Ninja`` based generator.
+
+Note that it is not possible to change the generator
+with ``-G`` after the first invocation of CMake.  To
+change the generator, the build directory must be
+deleted and the build must be started from scratch.
+
+When generating Visual Studio project and solutions
+files several other options are available to use when
+initially running :manual:`cmake(1)`.
+
+The Visual Studio toolset can be specified with the
+``-T`` option:
+
+.. code-block:: console
+
+    $ # Build with the clang-cl toolset
+    $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T LLVM
+    $ # Build targeting Windows XP
+    $ cmake.exe .. -G "Visual Studio 16 2019" -A x64 -T v120_xp
+
+Whereas the ``-A`` option specifies the _target_
+architecture, the ``-T`` option can be used to specify
+details of the toolchain used.  For example, `-Thost=x64`
+can be given to select the 64-bit version of the host
+tools.  The following demonstrates how to use 64-bit
+tools and also build for a 64-bit target architecture:
+
+.. code-block:: console
+
+    $ cmake .. -G "Visual Studio 16 2019" -A x64 -Thost=x64
+
+Choosing a generator in cmake-gui
+---------------------------------
+
+The "Configure" button triggers a new dialog to
+select the CMake generator to use.
+
+.. image:: /guide/user-interaction/GUI-Configure-Dialog.png
+
+All generators available on the command line are also
+available in :manual:`cmake-gui(1)`.
+
+.. image:: /guide/user-interaction/GUI-Choose-Generator.png
+
+When choosing a Visual Studio generator, further options
+are available to set an architecture to generate for.
+
+.. image:: /manual/VS-Choose-Arch.png
+
+.. _`Setting Build Variables`:
+
+Setting Build Variables
+=======================
+
+Software projects often require variables to be
+set on the command line when invoking CMake.  Some of
+the most commonly used CMake variables are listed in
+the table below:
+
+========================================== ============================================================
+ Variable                                   Meaning
+========================================== ============================================================
+ :variable:`CMAKE_PREFIX_PATH`              Path to search for
+                                            :guide:`dependent packages <Using Dependencies Guide>`
+ :variable:`CMAKE_MODULE_PATH`              Path to search for additional CMake modules
+ :variable:`CMAKE_BUILD_TYPE`               Build configuration, such as
+                                            ``Debug`` or ``Release``, determining
+                                            debug/optimization flags.  This is only
+                                            relevant for single-configuration buildsystems such
+                                            as ``Makefile`` and ``Ninja``.  Multi-configuration
+                                            buildsystems such as those for Visual Studio and Xcode
+                                            ignore this setting.
+ :variable:`CMAKE_INSTALL_PREFIX`           Location to install the
+                                            software to with the
+                                            ``install`` build target
+ :variable:`CMAKE_TOOLCHAIN_FILE`           File containing cross-compiling
+                                            data such as
+                                            :manual:`toolchains and sysroots <cmake-toolchains(7)>`.
+ :variable:`BUILD_SHARED_LIBS`              Whether to build shared
+                                            instead of static libraries
+                                            for :command:`add_library`
+                                            commands used without a type
+ :variable:`CMAKE_EXPORT_COMPILE_COMMANDS`  Generate a ``compile_commands.json``
+                                            file for use with clang-based tools
+========================================== ============================================================
+
+Other project-specific variables may be available
+to control builds, such as enabling or disabling
+components of the project.
+
+There is no convention provided by CMake for how
+such variables are named between different
+provided buildsystems, except that variables with
+the prefix ``CMAKE_`` usually refer to options
+provided by CMake itself and should not be used
+in third-party options, which should use
+their own prefix instead.  The
+:manual:`cmake-gui(1)` tool can display options
+in groups defined by their prefix, so it makes
+sense for third parties to ensure that they use a
+self-consistent prefix.
+
+Setting variables on the command line
+-------------------------------------
+
+CMake variables can be set on the command line either
+when creating the initial build:
+
+.. code-block:: console
+
+    $ mkdir build
+    $ cd build
+    $ cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug
+
+or later on a subsequent invocation of
+:manual:`cmake(1)`:
+
+.. code-block:: console
+
+    $ cd build
+    $ cmake . -DCMAKE_BUILD_TYPE=Debug
+
+The ``-U`` flag may be used to unset variables
+on the :manual:`cmake(1)` command line:
+
+.. code-block:: console
+
+    $ cd build
+    $ cmake . -UMyPackage_DIR
+
+A CMake buildsystem which was initially created
+on the command line can be modified using the
+:manual:`cmake-gui(1)` and vice-versa.
+
+The :manual:`cmake(1)` tool allows specifying a
+file to use to populate the initial cache using
+the ``-C`` option.  This can be useful to simplify
+commands and scripts which repeatedly require the
+same cache entries.
+
+Setting variables with cmake-gui
+--------------------------------
+
+Variables may be set in the cmake-gui using the "Add Entry"
+button.  This triggers a new dialog to set the value of
+the variable.
+
+.. image:: /guide/user-interaction/GUI-Add-Entry.png
+
+The main view of the :manual:`cmake-gui(1)` user interface
+can be used to edit existing variables.
+
+The CMake Cache
+---------------
+
+When CMake is executed, it needs to find the locations of
+compilers, tools and dependencies.  It also needs to be
+able to consistently re-generate a buildsystem to use the
+same compile/link flags and paths to dependencies.  Such
+parameters are also required to be configurable by the
+user because they are paths and options specific to the
+users system.
+
+When it is first executed, CMake generates a
+``CMakeCache.txt`` file in the build directory containing
+key-value pairs for such artifacts.  The cache file can be
+viewed or edited by the user by running the
+:manual:`cmake-gui(1)` or :manual:`ccmake(1)` tool.  The
+tools provide an interactive interface for re-configuring
+the provided software and re-generating the buildsystem,
+as is needed after editing cached values.  Each cache
+entry may have an associated short help text which is
+displayed in the user interface tools.
+
+The cache entries may also have a type to signify how it
+should be presented in the user interface.  For example,
+a cache entry of type ``BOOL`` can be edited by a
+checkbox in a user interface, a ``STRING`` can be edited
+in a text field, and a ``FILEPATH`` while similar to a
+``STRING`` should also provide a way to locate filesystem
+paths using a file dialog.  An entry of type ``STRING``
+may provide a restricted list of allowed values which are
+then provided in a drop-down menu in the
+:manual:`cmake-gui(1)` user interface (see the
+:prop_cache:`STRINGS` cache property).
+
+The CMake files shipped with a software package may also
+define boolean toggle options using the :command:`option`
+command.  The command creates a cache entry which has a
+help text and a default value.  Such cache entries are
+typically specific to the provided software and affect
+the configuration of the build, such as whether tests
+and examples are built, whether to build with exceptions
+enabled etc.
+
+Invoking the Buildsystem
+========================
+
+After generating the buildsystem, the software can be
+built by invoking the particular build tool.  In the
+case of the IDE generators, this can involve loading
+the generated project file into the IDE to invoke the
+build.
+
+CMake is aware of the specific build tool needed to invoke
+a build so in general, to build a buildsystem or project
+from the command line after generating, the following
+command may be invoked in the build directory:
+
+.. code-block:: console
+
+  $ cmake --build .
+
+The ``--build`` flag enables a particular mode of
+operation for the :manual:`cmake(1)` tool.  It invokes
+the  :variable:`CMAKE_MAKE_PROGRAM` command associated
+with the :manual:`generator <cmake-generators(7)>`, or
+the build tool configured by the user.
+
+The ``--build`` mode also accepts the parameter
+``--target`` to specify a particular target to build,
+for example a particular library, executable or
+custom target, or a particular special target like
+``install``:
+
+.. code-block:: console
+
+  $ cmake --build . --target myexe
+
+The ``--build`` mode also accepts a ``--config`` parameter
+in the case of multi-config generators to specify which
+particular configuration to build:
+
+.. code-block:: console
+
+  $ cmake --build . --target myexe --config Release
+
+The ``--config`` option has no effect if the generator
+generates a buildsystem specific to a configuration which
+is chosen when invoking cmake with the
+:variable:`CMAKE_BUILD_TYPE` variable.
+
+Some buildsystems omit details of command lines invoked
+during the build.  The ``--verbose`` flag can be used to
+cause those command lines to be shown:
+
+.. code-block:: console
+
+  $ cmake --build . --target myexe --verbose
+
+The ``--build`` mode can also pass particular command
+line options to the underlying build tool by listing
+them after ``--``.  This can be useful to specify
+options to the build tool, such as to continue the
+build after a failed job, where CMake does not
+provide a high-level user interface.
+
+For all generators, it is possible to run the underlying
+build tool after invoking CMake.  For example, ``make``
+may be executed after generating with the
+:generator:`Unix Makefiles` generator to invoke the build,
+or ``ninja`` after generating with the :generator:`Ninja`
+generator etc.  The IDE buildsystems usually provide
+command line tooling for building a project which can
+also be invoked.
+
+Selecting a Target
+------------------
+
+Each executable and library described in the CMake files
+is a build target, and the buildsystem may describe
+custom targets, either for internal use, or for user
+consumption, for example to create documentation.
+
+CMake provides some built-in targets for all buildsystems
+providing CMake files.
+
+``all``
+  The default target used by ``Makefile`` and ``Ninja``
+  generators.  Builds all targets in the buildsystem,
+  except those which are excluded by their
+  :prop_tgt:`EXCLUDE_FROM_ALL` target property or
+  :prop_dir:`EXCLUDE_FROM_ALL` directory property.  The
+  name ``ALL_BUILD`` is used for this purpose for the
+  Xcode and Visual Studio generators.
+``help``
+  Lists the targets available for build.  This target is
+  available when using the :generator:`Unix Makefiles` or
+  :generator:`Ninja` generator, and the exact output is
+  tool-specific.
+``clean``
+  Delete built object files and other output files.  The
+  ``Makefile`` based generators create a ``clean`` target
+  per directory, so that an individual directory can be
+  cleaned.  The ``Ninja`` tool provides its own granular
+  ``-t clean`` system.
+``test``
+  Runs tests.  This target is only automatically available
+  if the CMake files provide CTest-based tests.  See also
+  `Running Tests`_.
+``install``
+  Installs the software.  This target is only automatically
+  available if the software defines install rules with the
+  :command:`install` command.  See also
+  `Software Installation`_.
+``package``
+  Creates a binary package.  This target is only
+  automatically available if the CMake files provide
+  CPack-based packages.
+``package_source``
+  Creates a source package.  This target is only
+  automatically available if the CMake files provide
+  CPack-based packages.
+
+For ``Makefile`` based systems, ``/fast`` variants of binary
+build targets are provided. The ``/fast`` variants are used
+to build the specified target without regard for its
+dependencies.  The dependencies are not checked and
+are not rebuilt if out of date.  The :generator:`Ninja`
+generator is sufficiently fast at dependency checking that
+such targets are not provided for that generator.
+
+``Makefile`` based systems also provide build-targets to
+preprocess, assemble and compile individual files in a
+particular directory.
+
+.. code-block:: console
+
+  $ make foo.cpp.i
+  $ make foo.cpp.s
+  $ make foo.cpp.o
+
+The file extension is built into the name of the target
+because another file with the same name but a different
+extension may exist.  However, build-targets without the
+file extension are also provided.
+
+.. code-block:: console
+
+  $ make foo.i
+  $ make foo.s
+  $ make foo.o
+
+In buildsystems which contain ``foo.c`` and ``foo.cpp``,
+building the ``foo.i`` target will preprocess both files.
+
+Specifying a Build Program
+--------------------------
+
+The program invoked by the ``--build`` mode is determined
+by the :variable:`CMAKE_MAKE_PROGRAM` variable.  For most
+generators, the particular program does not need to be
+configured.
+
+===================== =========================== ===========================
+      Generator           Default make program           Alternatives
+===================== =========================== ===========================
+ XCode                 ``xcodebuild``
+ Unix Makefiles        ``make``
+ NMake Makefiles       ``nmake``                   ``jom``
+ NMake Makefiles JOM   ``jom``                     ``nmake``
+ MinGW Makefiles       ``mingw32-make``
+ MSYS Makefiles        ``make``
+ Ninja                 ``ninja``
+ Visual Studio         ``msbuild``
+ Watcom WMake          ``wmake``
+===================== =========================== ===========================
+
+The ``jom`` tool is capable of reading makefiles of the
+``NMake`` flavor and building in parallel, while the
+``nmake`` tool always builds serially.  After generating
+with the :generator:`NMake Makefiles` generator a user
+can run ``jom`` instead of ``nmake``.  The ``--build``
+mode would also use ``jom`` if the
+:variable:`CMAKE_MAKE_PROGRAM` was set to ``jom`` while
+using the :generator:`NMake Makefiles` generator, and
+as a convenience, the :generator:`NMake Makefiles JOM`
+generator is provided to find ``jom`` in the normal way
+and use it as the :variable:`CMAKE_MAKE_PROGRAM`. For
+completeness, ``nmake`` is an alternative tool which
+can process the output of the
+:generator:`NMake Makefiles JOM` generator, but doing
+so would be a pessimisation.
+
+Software Installation
+=====================
+
+The :variable:`CMAKE_INSTALL_PREFIX` variable can be
+set in the CMake cache to specify where to install the
+provided software.  If the provided software has install
+rules, specified using the :command:`install` command,
+they will install artifacts into that prefix.  On Windows,
+the default installation location corresponds to the
+``ProgramFiles`` system directory which may be
+architecture specific.  On Unix hosts, ``/usr/local`` is
+the default installation location.
+
+The :variable:`CMAKE_INSTALL_PREFIX` variable always
+refers to the installation prefix on the target
+filesystem.
+
+In cross-compiling or packaging scenarios where the
+sysroot is read-only or where the sysroot should otherwise
+remain pristine, the :variable:`CMAKE_STAGING_PREFIX`
+variable can be set to a location to actually install
+the files.
+
+The commands:
+
+.. code-block:: console
+
+  $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local \
+    -DCMAKE_SYSROOT=$HOME/root \
+    -DCMAKE_STAGING_PREFIX=/tmp/package
+  $ cmake --build .
+  $ cmake --build . --target install
+
+result in files being installed to paths such
+as ``/tmp/package/lib/libfoo.so`` on the host machine.
+The ``/usr/local`` location on the host machine is
+not affected.
+
+Some provided software may specify ``uninstall`` rules,
+but CMake does not generate such rules by default itself.
+
+Running Tests
+=============
+
+The :manual:`ctest(1)` tool is shipped with the CMake
+distribution to execute provided tests and report
+results.  The ``test`` build-target is provided to run
+all available tests, but the :manual:`ctest(1)` tool
+allows granular control over which tests to run, how to
+run them, and how to report results.  Executing
+:manual:`ctest(1)` in the build directory is equivalent
+to running the ``test`` target:
+
+.. code-block:: console
+
+  $ ctest
+
+A regular expression can be passed to run only tests
+which match the expression.  To run only tests with
+``Qt`` in their name:
+
+.. code-block:: console
+
+  $ ctest -R Qt
+
+Tests can be excluded by regular expression too.  To
+run only tests without ``Qt`` in their name:
+
+.. code-block:: console
+
+  $ ctest -E Qt
+
+Tests can be run in parallel by passing ``-j`` arguments
+to :manual:`ctest(1)`:
+
+.. code-block:: console
+
+  $ ctest -R Qt -j8
+
+The environment variable :envvar:`CTEST_PARALLEL_LEVEL`
+can alternatively be set to avoid the need to pass
+``-j``.
+
+By default :manual:`ctest(1)` does not print the output
+from the tests. The command line argument ``-V`` (or
+``--verbose``) enables verbose mode to print the
+output from all tests.
+The ``--output-on-failure`` option prints the test
+output for failing tests only.  The environment variable
+:envvar:`CTEST_OUTPUT_ON_FAILURE`
+can be set to ``1`` as an alternative to passing the
+``--output-on-failure`` option to :manual:`ctest(1)`.
diff --git a/Help/guide/using-dependencies/index.rst b/Help/guide/using-dependencies/index.rst
new file mode 100644
index 000000000..6fdcc551e
--- /dev/null
+++ b/Help/guide/using-dependencies/index.rst
@@ -0,0 +1,200 @@
+Using Dependencies Guide
+************************
+
+.. only:: html
+
+   .. contents::
+
+Introduction
+============
+
+For developers wishing to use CMake to consume a third
+party binary package, there are multiple possibilities
+regarding how to optimally do so, depending on how
+CMake-aware the third-party library is.
+
+CMake files provided with a software package contain
+instructions for finding each build dependency.  Some
+build dependencies are optional in that the build may
+succeed with a different feature set if the dependency
+is missing, and some dependencies are required.  CMake
+searches well-known locations for each dependency, and
+the provided software may supply additional hints or
+locations to CMake to find each dependency.
+
+If a required dependency is not found by
+:manual:`cmake(1)`, the cache is populated with an entry
+which contains a ``NOTFOUND`` value.  This value can be
+replaced by specifying it on the command line, or in
+the :manual:`ccmake(1)` or :manual:`cmake-gui(1)` tool.
+See the :guide:`User Interaction Guide` for
+more about setting cache entries.
+
+Libraries providing Config-file packages
+----------------------------------------
+
+The most convenient way for a third-party to provide library
+binaries for use with CMake is to provide
+:ref:`Config File Packages`.  These packages are text files
+shipped with the library which instruct CMake how to use the
+library binaries and associated headers, helper tools and
+CMake macros provided by the library.
+
+The config files can usually be found in a directory whose
+name matches the pattern ``lib/cmake/<PackageName>``, though
+they may be in other locations instead.  The
+``<PackageName>`` corresponds to use in CMake code with the
+:command:`find_package` command such as
+``find_package(PackageName REQUIRED)``.
+
+The ``lib/cmake/<PackageName>`` directory will contain a
+file which is either named ``<PackageName>Config.cmake``
+or ``<PackageName>-config.cmake``.  This is the entry point
+to the package for CMake.  A separate optional file named
+``<PackageName>ConfigVersion.cmake`` may also exist in the
+directory.  This file is used by CMake to determine whether
+the version of the third party package satisfies uses of the
+:command:`find_package` command which specify version
+constraints.  It is optional to specify a version when using
+:command:`find_package`, even if a ``ConfigVersion`` file is
+present.
+
+If the ``Config.cmake`` file is found and the
+optionally-specified version is satisfied, then the CMake
+:command:`find_package` command considers the package to be
+found and the entire library package is assumed to be
+complete as designed.
+
+There may be additional files providing CMake macros or
+:ref:`imported targets` for you to use.  CMake does not
+enforce any naming convention for these
+files.  They are related to the primary ``Config`` file by
+use of the CMake :command:`include` command.
+
+:guide:`Invoking CMake <User Interaction Guide>` with the
+intent of using a package of third party binaries requires
+that cmake :command:`find_package` commands succeed in finding
+the package.  If the location of the package is in a directory
+known to CMake, the :command:`find_package` call should
+succeed.  The directories known to cmake are platform-specific.
+For example, packages installed on Linux with a standard
+system package manager will be found in the ``/usr`` prefix
+automatically.  Packages installed in ``Program Files`` on
+Windows will similarly be found automatically.
+
+Packages which are not found automatically are in locations
+not predictable to CMake such as ``/opt/mylib`` or
+``$HOME/dev/prefix``.  This is a normal situation and CMake
+provides several ways for users to specify where to find
+such libraries.
+
+The :variable:`CMAKE_PREFIX_PATH` variable may be
+:ref:`set when invoking CMake <Setting Build Variables>`.
+It is treated as a list of paths to search for
+:ref:`Config File Packages`.  A package installed in
+``/opt/somepackage`` will typically install config files
+such as
+``/opt/somepackage/lib/cmake/somePackage/SomePackageConfig.cmake``.
+In that case, ``/opt/somepackage`` should be added to
+:variable:`CMAKE_PREFIX_PATH`.
+
+The environment variable ``CMAKE_PREFIX_PATH`` may also be
+populated with prefixes to search for packages.  Like the
+``PATH`` environment variable, this is a list and needs to use
+the platform-specific environment variable list item separator
+(``:`` on Unix and ``;`` on Windows).
+
+The :variable:`CMAKE_PREFIX_PATH` variable provides convenience
+in cases where multiple prefixes need to be specified, or when
+multiple different package binaries are available in the same
+prefix.  Paths to packages may also be specified by setting
+variables matching ``<PackageName>_DIR``, such as
+``SomePackage_DIR``.  Note that this is not a prefix but should
+be a full path to a directory containing a config-style package
+file, such as ``/opt/somepackage/lib/cmake/SomePackage/`` in
+the above example.
+
+Imported Targets from Packages
+------------------------------
+
+A third-party package which provides config-file packages may
+also provide :ref:`Imported targets`. These will be
+specified in files containing configuration-specific file
+paths relevant to the package, such as debug and release
+versions of libraries.
+
+Often the third-party package documentation will point out the
+names of imported targets available after a successful
+``find_package`` for a library.  Those imported target names
+can be used with the :command:`target_link_libraries` command.
+
+A complete example which makes a simple use of a third party
+library might look like:
+
+.. code-block:: cmake
+
+    cmake_minimum_required(VERSION 3.10)
+    project(MyExeProject VERSION 1.0.0)
+
+    find_package(SomePackage REQUIRED)
+    add_executable(MyExe main.cpp)
+    target_link_libraries(MyExe PRIVATE SomePrefix::LibName)
+
+See :manual:`cmake-buildsystem(7)` for further information
+about developing a CMake buildsystem.
+
+Libraries not Providing Config-file Packages
+--------------------------------------------
+
+Third-party libraries which do not provide config-file packages
+can still be found with the :command:`find_package` command, if
+a ``FindSomePackage.cmake`` file is available.
+
+These module-file packages are different to config-file packages
+in that:
+
+#. They should not be provided by the third party, except
+   perhaps in the form of documentation
+#. The availability of a ``Find<PackageName>.cmake`` file does
+   not indicate the availability of the binaries themselves.
+#. CMake does not search the :variable:`CMAKE_PREFIX_PATH` for
+   ``Find<PackageName>.cmake`` files.  Instead CMake searches
+   for such files in the :variable:`CMAKE_MODULE_PATH`
+   variable. It is common for users to set the
+   :variable:`CMAKE_MODULE_PATH` when running CMake, and it is
+   common for CMake projects to append to
+   :variable:`CMAKE_MODULE_PATH` to allow use of local
+   module-file packages.
+#. CMake ships ``Find<PackageName>.cmake`` files for some
+   :manual:`third party packages <cmake-modules(7)>`
+   for convenience in cases where the third party does
+   not provide config-file packages directly.  These files are
+   a maintenance burden for CMake, so new Find modules are
+   generally not added to CMake anymore.  Third-parties should
+   provide config file packages instead of relying on a Find
+   module to be provided by CMake.
+
+Module-file packages may also provide :ref:`Imported targets`.
+A complete example which finds such a package might look
+like:
+
+.. code-block:: cmake
+
+    cmake_minimum_required(VERSION 3.10)
+    project(MyExeProject VERSION 1.0.0)
+
+    find_package(PNG REQUIRED)
+
+    # Add path to a FindSomePackage.cmake file
+    list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
+    find_package(SomePackage REQUIRED)
+
+    add_executable(MyExe main.cpp)
+    target_link_libraries(MyExe PRIVATE
+        PNG::PNG
+        SomePrefix::LibName
+    )
+
+The :variable:`<PackageName>_ROOT` variable is also
+searched as a prefix for :command:`find_package` calls using
+module-file packages such as ``FindSomePackage``.