Doc: Describe Formatter tab in Preferences > CMake

Update screenshots and fix alt text to use {} instead of "".

Task-number: QTCREATORBUG-28721
Change-Id: I9535f099047b36dda2f7a37b181c688e40a534d1
Reviewed-by: Xavier BESSON <developer@xavi-b.fr>
Reviewed-by: Cristian Adam <cristian.adam@qt.io>

8 files changed, 42 insertions, 15 deletions

diff --git a/doc/qtcreator/images/qtcreator-preferences-cmake-formatter.webp b/doc/qtcreator/images/qtcreator-preferences-cmake-formatter.webp
new file mode 100644
index 0000000000..a61b2d7270
--- /dev/null
+++ b/doc/qtcreator/images/qtcreator-preferences-cmake-formatter.webp
diff --git a/doc/qtcreator/images/qtcreator-preferences-cmake-general.png b/doc/qtcreator/images/qtcreator-preferences-cmake-general.png
deleted file mode 100644
index fc096178c7..0000000000
--- a/doc/qtcreator/images/qtcreator-preferences-cmake-general.png
+++ /dev/null
diff --git a/doc/qtcreator/images/qtcreator-preferences-cmake-general.webp b/doc/qtcreator/images/qtcreator-preferences-cmake-general.webp
new file mode 100644
index 0000000000..2eef4e57ee
--- /dev/null
+++ b/doc/qtcreator/images/qtcreator-preferences-cmake-general.webp
diff --git a/doc/qtcreator/images/qtcreator-preferences-cmake-tools.png b/doc/qtcreator/images/qtcreator-preferences-cmake-tools.png
deleted file mode 100644
index c7abce1977..0000000000
--- a/doc/qtcreator/images/qtcreator-preferences-cmake-tools.png
+++ /dev/null
diff --git a/doc/qtcreator/images/qtcreator-preferences-cmake-tools.webp b/doc/qtcreator/images/qtcreator-preferences-cmake-tools.webp
new file mode 100644
index 0000000000..2e5e7d4ef9
--- /dev/null
+++ b/doc/qtcreator/images/qtcreator-preferences-cmake-tools.webp
diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc
index 5d7d2fc6e8..322a72cd71 100644
--- a/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc
+++ b/doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc
@@ -20,7 +20,7 @@
     is constructed by using the values of the \uicontrol {Build directory} and
     \uicontrol {Build type} fields.
 
-    \image qtcreator-cmake-build-settings-initial.png "CMake build settings"
+    \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
@@ -72,12 +72,12 @@
     disabled all kits in the project. To update changes to the
     \c CMakePresets.json file, delete the \c CMakeLists.txt.user file.
 
-    \image qtcreator-cmake-presets-configure.webp "Opening a project that has Cmake presets"
+    \image qtcreator-cmake-presets-configure.webp {Opening a project that has CMake presets}
 
     You can view the presets in the \uicontrol {Initial Configuration} field and
     in the environment configuration field below it.
 
-    \image qtcreator-cmake-presets-environment.webp "CMake environment configuration"
+    \image qtcreator-cmake-presets-environment.webp {CMake environment configuration}
 
     \section2 Configure Presets
 
@@ -292,7 +292,7 @@
     are passed to CMake in \uicontrol {Initial Configuration} or
     \uicontrol {Current Configuration}.
 
-    \image qtcreator-cmake-build-settings.png "CMake variables"
+    \image qtcreator-cmake-build-settings.png {CMake variables}
 
     To view all variables, select the \uicontrol Advanced check box.
 
@@ -352,21 +352,21 @@
     \uicontrol Preferences > \uicontrol CMake > \uicontrol General >
     \uicontrol {Ask before re-configuring with initial parameters}.
 
-    \image qtcreator-preferences-cmake-general.png "General tab in CMake Preferences"
+    \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
     \uicontrol {Run Settings} panes in the \uicontrol Projects mode.
 
-    \image qtcreator-build-cmake-output.png "CMake output in Projects mode"
+    \image qtcreator-build-cmake-output.png {CMake output in Projects mode}
 
     To clear the search results, select the \inlineimage icons/clean_pane_small.png
     (\uicontrol Clear) button.
 
     You can enter a string in the \uicontrol Filter field to filter output.
     To specify filtering options, select the
-    \inlineimage icons/magnifier.png "Filtering options menu"
+    \inlineimage icons/magnifier.png {Filtering options menu}
     button. You can filter output by using regular expressions or
     case-sensitivity. Select \uicontrol {Show Non-matching Lines} to
     hide the lines that match the filter.
@@ -391,7 +391,7 @@
     You can add arguments to pass to CMake and the generator and targets for
     the build command in \uicontrol {Build Steps}.
 
-    \image qtcreator-cmake-build-steps.png "CMake build steps"
+    \image qtcreator-cmake-build-steps.png {CMake build steps}
 
     \note While the other CMake generators are installed together with Qt,
     you usually need to install Ninja yourself.
@@ -407,10 +407,10 @@
             variable.
         \li In \uicontrol Projects > \uicontrol {Build & Run} > \uicontrol Build
             > \uicontrol {Build Settings}, select \uicontrol {Kit Configuration}.
-            \image qtcreator-cmake-kit-configuration.png "Kit CMake Configuration dialog"
+            \image qtcreator-cmake-kit-configuration.png {Kit CMake Configuration dialog}
         \li Select \uicontrol Change next to the \uicontrol {CMake generator}
             field to open the \uicontrol {CMake Generator} dialog.
-            \image qtcreator-cmake-generator.png "CMake Generator dialog"
+            \image qtcreator-cmake-generator.png {CMake Generator dialog}
         \li In \uicontrol Generator, select \uicontrol Ninja.
         \li Select \uicontrol OK to save your changes and close the dialog.
         \li Select \uicontrol Close to close the
diff --git a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
index 34e98d8d30..8b7c3fa3d4 100644
--- a/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
+++ b/doc/qtcreator/src/cmake/creator-projects-cmake.qdoc
@@ -1,4 +1,4 @@
-// Copyright (C) 2022 The Qt Company Ltd.
+// Copyright (C) 2023 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 // **********************************************************************
@@ -36,7 +36,7 @@
     a \c CMakeLists.txt configuration file in a project. Project information is
     also automatically refreshed when you build the project.
 
-    \image qtcreator-projects-view-edit.png "CMake project in Projects view"
+    \image qtcreator-projects-view-edit.png {CMake project in Projects view}
 
     If \QC cannot load the CMake project, the \l Projects view shows a
     \uicontrol {<File System>} project node to avoid scanning the file
@@ -85,7 +85,7 @@
         \li Select \uicontrol Edit > \uicontrol Preferences > \uicontrol CMake >
             \uicontrol Tools.
 
-            \image qtcreator-preferences-cmake-tools.png "Tools tab in CMake Preferences"
+            \image qtcreator-preferences-cmake-tools.webp {Tools tab in CMake Preferences}
 
         \li The \uicontrol Name field displays a name for the CMake
             installation.
@@ -120,7 +120,7 @@
     The kit also specifies the CMake generator that is used for producing
     project files for \QC and the initial configuration parameters:
 
-    \image qtcreator-kits-cmake.png
+    \image qtcreator-kits-cmake.png {Kits preferences}
 
     For more information, see \l {Adding Kits}.
 
@@ -155,6 +155,33 @@
 
     Warnings and errors are displayed in \l {Issues}.
 
+    \section1 Formatting CMake Files
+
+    You can use the \c {cmake-format} tool to format any text in CMake files that
+    you do not guard with a pair of fences. You must install the tool and tell
+    \QC where you installed it. For more information about the tool and how to
+    install it, see \l{https://cmake-format.readthedocs.io/en/latest/index.html}
+    {cmake language tools}.
+
+    To automatically format CMake files upon file save:
+
+    \list 1
+        \li Select \uicontrol Edit > \uicontrol Preferences > \uicontrol CMake >
+            \uicontrol Formatter.
+            \image qtcreator-preferences-cmake-formatter.webp {Formatter tab in CMake Preferences}
+        \li In \uicontrol {CMakeFormat command}, enter the path to
+            \c {cmake-format.exe}.
+        \li Select \uicontrol {Enable auto format on file save} to automatically
+            format CMake files when you save them.
+        \li In \uicontrol {Restrict to MIME types}, add the \l{Adding MIME Types}
+            {MIME types} of the files to format, separated by semicolons. The
+            default value, \c {text/x-cmake} formats CMake files. If the field is
+            empty, all files are formatted.
+        \li Select the \uicontrol {Restrict to files contained in the current
+            project} check box to only format CMake files that belong to the
+            current project.
+    \endlist
+
    \section1 Adding External Libraries to CMake Projects
 
     Through external libraries, \QC can support code completion and syntax
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 d67f493dd1..a99605d96e 100644
--- a/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc
+++ b/doc/qtcreator/src/projects/creator-only/creator-projects-building.qdoc
@@ -103,7 +103,7 @@
     CMake executable to edit, and then deselect the \uicontrol {Autorun CMake}
     check box.
 
-    \image qtcreator-preferences-cmake-tools.png "Tools tab in CMake Preferences"
+    \image qtcreator-preferences-cmake-tools.webp "Tools tab in CMake Preferences"
 
     For more information, see \l {Setting Up CMake}.