Merge topic 'doc-sections'

22aac6669b Help: install: use bullet lists to sort out target kinds
b3f4d50348 Help: ifw.rst: Add toc; mv "Hints" section -> subsection of "Variables"
c671966c20 Help: CPackComponent: Sectioning and rewording
05e56b1897 Help: FetchContent, ExternalProject: Command sections -> subsections

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !4367

2 files changed, 56 insertions, 43 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index a3c64a4..abf6b17 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -126,31 +126,38 @@ Installing Targets
           )
 
 The ``TARGETS`` form specifies rules for installing targets from a
-project.  There are several kinds of target files that may be installed:
+project.  There are several kinds of target :ref:`Output Artifacts`
+that may be installed:
 
 ``ARCHIVE``
-  Static libraries are treated as ``ARCHIVE`` targets, except those
-  marked with the ``FRAMEWORK`` property on macOS (see ``FRAMEWORK``
-  below.) For DLL platforms (all Windows-based systems including
-  Cygwin), the DLL import library is treated as an ``ARCHIVE`` target.
-  On AIX, the linker import file created for executables with
-  :prop_tgt:`ENABLE_EXPORTS` is treated as an ``ARCHIVE`` target.
+  Target artifacts of this kind include:
+
+  * *Static libraries*
+    (except on macOS when marked as ``FRAMEWORK``, see below);
+  * *DLL import libraries*
+    (on all Windows-based systems including Cygwin; they have extension
+    ``.lib``, in contrast to the ``.dll`` libraries that go to ``RUNTIME``);
+  * On AIX, the *linker import file* created for executables with
+    :prop_tgt:`ENABLE_EXPORTS` enabled.
 
 ``LIBRARY``
-  Module libraries are always treated as ``LIBRARY`` targets. For non-
-  DLL platforms shared libraries are treated as ``LIBRARY`` targets,
-  except those marked with the ``FRAMEWORK`` property on macOS (see
-  ``FRAMEWORK`` below.)
+  Target artifacts of this kind include:
+
+  * *Shared libraries*, except
+
+    - DLLs (these go to ``RUNTIME``, see below),
+    - on macOS when marked as ``FRAMEWORK`` (see below).
 
 ``RUNTIME``
-  Executables are treated as ``RUNTIME`` objects, except those marked
-  with the ``MACOSX_BUNDLE`` property on macOS (see ``BUNDLE`` below.)
-  For DLL platforms (all Windows-based systems including Cygwin), the
-  DLL part of a shared library is treated as a ``RUNTIME`` target.
+  Target artifacts of this kind include:
+
+  * *Executables*
+    (except on macOS when marked as ``MACOSX_BUNDLE``, see ``BUNDLE`` below);
+  * DLLs (on all Windows-based systems including Cygwin; note that the
+    accompanying import libraries are of kind ``ARCHIVE``).
 
 ``OBJECTS``
-  Object libraries (a simple group of object files) are always treated
-  as ``OBJECTS`` targets.
+  Object files associated with *object libraries*.
 
 ``FRAMEWORK``
   Both static and shared libraries marked with the ``FRAMEWORK``
diff --git a/Help/cpack_gen/ifw.rst b/Help/cpack_gen/ifw.rst
index 1d1a55b..d7c71b4 100644
--- a/Help/cpack_gen/ifw.rst
+++ b/Help/cpack_gen/ifw.rst
@@ -3,6 +3,10 @@ CPack IFW Generator
 
 Configure and run the Qt Installer Framework to generate a Qt installer.
 
+.. only:: html
+
+  .. contents::
+
 Overview
 ^^^^^^^^
 
@@ -20,32 +24,6 @@ The :module:`CPackIFW` module looks for the location of the
 QtIFW command-line utilities, and defines several commands to
 control the behavior of this generator.
 
-Hints
-^^^^^
-
-Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
-but if you don't use a default path for installation of the QtIFW tools,
-the path may be specified in either a CMake or an environment variable:
-
-.. variable:: CPACK_IFW_ROOT
-
- An CMake variable which specifies the location of the QtIFW tool suite.
-
- The variable will be cached in the ``CPackConfig.cmake`` file and used at
- CPack runtime.
-
-.. variable:: QTIFWDIR
-
- An environment variable which specifies the location of the QtIFW tool
- suite.
-
-.. note::
-  The specified path should not contain "bin" at the end
-  (for example: "D:\\DevTools\\QtIFW2.0.5").
-
-The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
-the value of the :variable:`QTIFWDIR` variable.
-
 Internationalization
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -161,6 +139,8 @@ Package
  Default target directory for installation.
  By default used
  "@ApplicationsDir@/:variable:`CPACK_PACKAGE_INSTALL_DIRECTORY`"
+ (variables embedded in '@' are expanded by the
+ `QtIFW scripting engine <https://doc.qt.io/qtinstallerframework/scripting.html>`_).
 
  You can use predefined variables.
 
@@ -294,6 +274,32 @@ These variables are cached, and may be configured if needed.
 
  The path to ``devtool``.
 
+Hints for Finding QtIFW
+"""""""""""""""""""""""
+
+Generally, the CPack ``IFW`` generator automatically finds QtIFW tools,
+but if you don't use a default path for installation of the QtIFW tools,
+the path may be specified in either a CMake or an environment variable:
+
+.. variable:: CPACK_IFW_ROOT
+
+ An CMake variable which specifies the location of the QtIFW tool suite.
+
+ The variable will be cached in the ``CPackConfig.cmake`` file and used at
+ CPack runtime.
+
+.. variable:: QTIFWDIR
+
+ An environment variable which specifies the location of the QtIFW tool
+ suite.
+
+.. note::
+  The specified path should not contain "bin" at the end
+  (for example: "D:\\DevTools\\QtIFW2.0.5").
+
+The :variable:`CPACK_IFW_ROOT` variable has a higher priority and overrides
+the value of the :variable:`QTIFWDIR` variable.
+
 
 Online installer
 ^^^^^^^^^^^^^^^^