Doc: Describe changes in CMake build settings

- Added `Show advanced options by default` to
  `Edit > Preferences > CMake > Tools`
- Moved `Autorun CMake` to `Edit > Preferences > CMake > General`
- Reorganize the building with CMake topic and add subtitles for
  readability

Task-number: QTCREATORBUG-28721
Change-Id: Id8bab60bc2e148c067ac1eb3669b544d12031078
Reviewed-by: Cristian Adam <cristian.adam@qt.io>

8 files changed, 70 insertions, 54 deletions

diff --git a/doc/qtcreator/images/qtcreator-build-settings-cmake-configure.webp b/doc/qtcreator/images/qtcreator-build-settings-cmake-configure.webp
new file mode 100644
index 0000000000..4b38b162f4
--- /dev/null
+++ b/doc/qtcreator/images/qtcreator-build-settings-cmake-configure.webp
diff --git a/doc/qtcreator/images/qtcreator-build-settings-cmake-current.webp b/doc/qtcreator/images/qtcreator-build-settings-cmake-current.webp
new file mode 100644
index 0000000000..24278f8dcc
--- /dev/null
+++ b/doc/qtcreator/images/qtcreator-build-settings-cmake-current.webp
diff --git a/doc/qtcreator/images/qtcreator-build-settings-cmake-initial.webp b/doc/qtcreator/images/qtcreator-build-settings-cmake-initial.webp
new file mode 100644
index 0000000000..cee22f09f6
--- /dev/null
+++ b/doc/qtcreator/images/qtcreator-build-settings-cmake-initial.webp
diff --git a/doc/qtcreator/images/qtcreator-cmake-build-settings-initial.png b/doc/qtcreator/images/qtcreator-cmake-build-settings-initial.png
deleted file mode 100644
index 3392c8ee67..0000000000
--- a/doc/qtcreator/images/qtcreator-cmake-build-settings-initial.png
+++ /dev/null
diff --git a/doc/qtcreator/images/qtcreator-cmake-build-settings.png b/doc/qtcreator/images/qtcreator-cmake-build-settings.png
deleted file mode 100644
index 9c88b064d6..0000000000
--- a/doc/qtcreator/images/qtcreator-cmake-build-settings.png
+++ /dev/null
diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc
index 322a72cd71..dac77727a8 100644
--- a/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc
+++ b/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc
@@ -16,42 +16,47 @@
     the \l{Specifying Build Settings}{Build Settings} of the project.
     Alternatively, you can use CMake presets to configure CMake.
 
-    The \uicontrol Configuration field displays the effective CMake call that
-    is constructed by using the values of the \uicontrol {Build directory} and
+    The \uicontrol Configure field displays the effective CMake call that
+    \QC constructs using the values of the \uicontrol {Build directory} and
     \uicontrol {Build type} fields.
 
-    \image qtcreator-cmake-build-settings-initial.png {CMake build settings}
-
-    \uicontrol {Initial Configuration} lists the variables that are used to
-    configure the CMake project for the first time. The default values that
-    are inherited from the kit's CMake configuration are displayed in italic.
-    The initial configuration list of variables is saved in the project's source
-    directory as the \e CMakeLists.txt.user file.
-
-    \uicontrol {Current Configuration} lists the CMake variables in the
-    \c cmake-file-api JSON export in the \c {.cmake/api/v1/reply} directory.
-    The variables that are inherited from the initial configuration are
-    displayed in italic. Mismatched values are displayed in red.
-
-    You can view and edit the actual values of the variables that are passed
-    to CMake. Variable names are listed in the \uicontrol Key column and their
-    current values in the \uicontrol Value column. For more information about
-    the available variables, select \uicontrol Help in the context menu or see
-    \l{CMake: cmake-variables(7)}. For more information about Qt-specific
-    variables, see \l{CMake Variable Reference}.
+    \image qtcreator-build-settings-cmake-configure.webp {CMake configure command}
 
     You can specify additional CMake options, such as \c {--find-debug},
     \c {--trace-expand}, or \c {--warn-uninitialized}, in
     \uicontrol {Additional CMake options}. For more information about
-    the available options, click the link in the field name or see
-    \l{CMake: cmake(1)}.
-
-    After successfully running CMake, you can view and modify the current
-    configuration in \uicontrol {Current Configuration}.
+    the options, click the link in the field name or see \l{CMake: cmake(1)}.
 
     Select \uicontrol {Kit Configuration} to edit the CMake settings for the
     build and run kit selected for the project.
 
+    \section1 Initial Configuration
+
+    \image qtcreator-build-settings-cmake-initial.webp {Initial CMake configuration}
+
+    \uicontrol {Initial Configuration} lists the variables that \QC uses to
+    configure the CMake project for the first time. It shows the default values
+    that come from the kit's CMake configuration in italics. \QC saves the
+    initial configuration list of variables in the project's source
+    directory as the \e CMakeLists.txt.user file.
+
+    \section1 Current Configuration
+
+    \image qtcreator-build-settings-cmake-current.webp {Current CMake configuration}
+
+    \uicontrol {Current Configuration} lists the CMake variables in the
+    \c cmake-file-api JSON export in the \c {.cmake/api/v1/reply} directory.
+    It shows the variables that come from the initial configuration in italics
+    and mismatched values in red.
+
+    After selecting the \uicontrol {Run CMake} button, you can view and
+    change the actual values of the variables that \QC passes to CMake.
+    The  \uicontrol Key column lists variable names, and the \uicontrol Value
+    column lists their current values. For more information about the variables,
+    select \uicontrol Help in the context menu or see
+    \l{CMake: cmake-variables(7)}. For more information about Qt-specific
+    variables, see \l{CMake Variable Reference}.
+
     \section1 CMake Presets
 
     You can use CMake presets files to specify common configure, build, and test
@@ -63,9 +68,9 @@
     \l{https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html}
     {cmake-presets(7)} and store them in project's root directory.
 
-    \QC supports presets up to version 3 (introduced in CMake 3.21), but version
-    checking is not enforced. All the fields from version 3 are read and used if
-    present. Test presets are not supported.
+    \QC supports presets up to version 3 (introduced in CMake 3.21), but does not
+    enforce version checking. It reads and uses all the fields from version 3 if
+    present. It does not support test presets.
 
     You can import the presets the first time you \l {Opening Projects}
     {open a project}, when no \c CMakeLists.txt.user file exists or you have
@@ -292,9 +297,19 @@
     are passed to CMake in \uicontrol {Initial Configuration} or
     \uicontrol {Current Configuration}.
 
-    \image qtcreator-cmake-build-settings.png {CMake variables}
+    \image qtcreator-build-settings-cmake-current.webp {Current CMake configuration}
 
-    To view all variables, select the \uicontrol Advanced check box.
+    You can select several variables and apply an action to them. To clear
+    the selection, click anywhere in the view.
+
+    To change the environment variable values for the CMake build environment,
+    select \uicontrol {Batch Edit}. For more information, see \l{Batch Editing}.
+
+    To build using the current configuration, select \uicontrol {Run CMake}.
+    While building, the button text changes to \uicontrol {Stop CMake}. Select
+    the button to cancel the current build.
+
+    \section2 Adding Variables
 
     To add variables, select \uicontrol Add, and then select the type of
     the variable that you are adding: \uicontrol Boolean, \uicontrol String,
@@ -309,36 +324,40 @@
     To copy the name or value of the selected variable to the clipboard,
     select \uicontrol Copy in the context menu.
 
-    To modify the value of a variable, double-click it, or select it,
+    \section2 Changing Variable Values
+
+    To change the value of a variable, double-click it, or select it,
     and then select \uicontrol Edit. If the initial, current, and kit
     configuration get out of sync, select \uicontrol {Apply Kit Value} or
     \uicontrol {Apply Initial Configuration Value} in the context menu in
     \uicontrol {Initial Configuration} or \uicontrol {Current Configuration}.
 
-    You can apply actions to multiple variables at a time. To clear
-    the selection, select \uicontrol {Clear Selection}.
-
-    To remove the selected variables, select \uicontrol Unset. To undo
-    the removal, select \uicontrol Set.
-
     To reset all the changes that you made, select \uicontrol Reset.
 
-    To modify the environment variable values for the CMake build environment,
-    select \uicontrol {Batch Edit}. For more information, see \l{Batch Editing}.
-
-    To build using the current configuration, select \uicontrol {Run CMake}.
-    While building, the button text changes to \uicontrol {Stop CMake}. Select
-    the button to cancel the current build.
-
     The variable values that you change are passed via \c -D<option>=<value>
     to CMake, which stores the options in the CMakeCache.txt file. This means
     that if you remove the build directory, all the custom variables that are
     not part of the initial CMake configuration are also removed.
 
-    To reconfigure a project using the modified variable values,
+    To reconfigure a project using the changed variable values,
     select \uicontrol Build > \uicontrol {Clear CMake Configuration}, which
     removes the CMakeCache.txt file. This enables you to do a full rebuild.
 
+    \section2 Removing Variables
+
+    To remove the selected variables, select \uicontrol Unset. To undo
+    the removal, select \uicontrol Set.
+
+    \section2 Viewing Advanced Variables
+
+    To view all variables, select the \uicontrol Advanced check box.
+
+    To view all variables by default, select \uicontrol Edit >
+    \uicontrol Preferences > \uicontrol CMake > \uicontrol General >
+    \uicontrol {Show advanced options by default}.
+
+    \image qtcreator-preferences-cmake-general.webp "General tab in CMake Preferences"
+
     \section1 Re-configuring with Initial Variables
 
     To reset CMake variables to the initial ones, select
@@ -352,8 +371,6 @@
     \uicontrol Preferences > \uicontrol CMake > \uicontrol General >
     \uicontrol {Ask before re-configuring with initial parameters}.
 
-    \image qtcreator-preferences-cmake-general.webp {General tab in CMake Preferences}
-
     \section1 Viewing CMake Output
 
     Output from CMake is displayed next to the \uicontrol {Build Settings} and
diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
index 8b7c3fa3d4..a646b5ff53 100644
--- a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
+++ b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
@@ -34,7 +34,10 @@
 
     \QC automatically runs CMake to refresh project information when you edit
     a \c CMakeLists.txt configuration file in a project. Project information is
-    also automatically refreshed when you build the project.
+    also automatically refreshed when you build the project. To disable this
+    behavior, select \uicontrol Edit > \uicontrol Preferences > \uicontrol CMake
+    > \uicontrol General, and then deselect the \uicontrol {Autorun CMake}
+    check box.
 
     \image qtcreator-projects-view-edit.png {CMake project in Projects view}
 
@@ -96,10 +99,6 @@
         \li The \uicontrol {Help file} field displays the path to the
             CMake help file (.qch) that comes with CMake.
 
-        \li Deselect the \uicontrol {Autorun CMake} check box if you do not want
-            to automatically run CMake every time when you save changes to
-            \c {CMakeLists.txt} files.
-
         \li Select \uicontrol Apply to save your changes.
 
     \endlist
diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc
index a99605d96e..acf362877d 100644
--- a/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc
+++ b/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc
@@ -99,7 +99,7 @@
 
     \QC automatically runs CMake when you make changes to \c {CMakeLists.txt}
     files. To disable this feature, select \uicontrol Edit >
-    \uicontrol Preferences > \uicontrol CMake > \uicontrol Tools. Select the
+    \uicontrol Preferences > \uicontrol CMake > \uicontrol General. Select the
     CMake executable to edit, and then deselect the \uicontrol {Autorun CMake}
     check box.