Doc: Turn "Specifying Environment Settings" into how-tos

Add a line drawing that describes the environment settings
hierarchy.

Task-number: QTCREATORBUG-29361
Change-Id: I7869797154c0e70263528a8635ea7f2dcee30f30
Reviewed-by: Eike Ziller <eike.ziller@qt.io>

doc/qtcreator/src/cmake/creator-projects-cmake-building.qdoc

@@ -88,7 +88,8 @@
     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}.
+    select \uicontrol {Batch Edit}. For more information, see
+    \l{Batch edit environment settings}.
 
     To build using the current configuration, select \uicontrol {Run CMake}.
     While building, the button text changes to \uicontrol {Stop CMake}. Select

doc/qtcreator/src/editors/creator-code-completion.qdoc

@@ -197,12 +197,13 @@
     \if defined(qtcreator)
     Also specify a text string or C++ or QML code construct
     in the snippet editor, depending on the snippet category.
+
+    You can use \l{Use Qt Creator variables}{predefined variables} in
+    snippets.
     \else
     Also specify a text string or QML code in the snippet editor, depending on
     the snippet category.
     \endif
-    You can use \l{Using Qt Creator Variables}{predefined variables} in
-    snippets.
 
     The snippet editor offers:
 
@@ -299,8 +300,6 @@
     \preferences > \uicontrol Nim > \uicontrol Tools,
     and enter the path to the tool executable in the \uicontrol Path field.
 
-    \sa {Document code}
+    \sa {Document code}, {Use Qt Creator variables}
-    \else
-    \include qtcreator-variables.qdocinc qtcreator variables
     \endif
 */

doc/qtcreator/src/editors/creator-only/creator-language-server.qdoc

@@ -81,7 +81,7 @@
         \li In the \uicontrol Name field, enter a name for the language server.
             Select the \inlineimage icons/replace.png
             (\uicontrol {Variables}) button to use a variable for the server
-            name. For more information, see \l{Using Qt Creator Variables}.
+            name. For more information, see \l{Use Qt Creator variables}.
         \li In the \uicontrol {Language} field, select
             \uicontrol {Set MIME Types} to select the MIME types of the files to
             send to the language server. In the field below, you can enter file
@@ -113,7 +113,7 @@
         \li In the \uicontrol Name field, enter a name for the language server.
             Select the \inlineimage icons/replace.png
             (\uicontrol {Variables}) button to use a variable for the server
-            name. For more information, see \l{Using Qt Creator Variables}.
+            name. For more information, see \l{Use Qt Creator variables}.
         \li In the \uicontrol Java field, enter the path to the Java executable.
         \li In the \uicontrol {Java Language Server} field, enter the path to
             the Java language server \c .jar file. You can download the Java

doc/qtcreator/src/howto/creator-external-tools.qdoc

@@ -35,10 +35,12 @@
 
     \image qtcreator-external-tools.png
 
+    \if defined(qtcreator)
     Select the \inlineimage icons/replace.png
     (\uicontrol {Variables}) button in a field to select from a list of
-    \l{Using Qt Creator Variables}{variables} that are available in a
+    \l{Use Qt Creator variables}{variables} that are available in a
     particular context.
+    \endif
 
     To configure external tools:
 
@@ -71,8 +73,8 @@
 
         \if defined(qtcreator)
         \li In the \uicontrol {Base environment} field, select whether to run
-            the tool in the system environment or the \l{Build Environment}
+            the tool in the system environment or the \l{Specify the environment for projects}
-            {build environment} or \l {Selecting the Run Environment}
+            {build environment} or \l {Specify the run environment}
             {run environment} of the active project. Select the build or run
             environment if the system environment does not have the necessary
             PATH settings to find the tool chain, for example.
@@ -82,20 +84,12 @@
 
         \li In the \uicontrol Environment field, select \uicontrol Change to modify
             environment variable values for build and run environments in
-            the \uicontrol {Edit Environment Changes} dialog.
+            the \uicontrol {Edit Environment} dialog.
-            \if defined(qtcreator)
-            For more information about how to add and remove variable values,
-            see \l{Batch Editing}.
-            \endif
-
 
             To globally change the system environment from the one in which
             \QC is started, select \preferences >
             \uicontrol Environment > \uicontrol System, and then select
             \uicontrol Change in the \uicontrol Environment field.
-            \if defined(qtcreator)
-            For more information, see \l{Specifying Environment Settings}.
-            \endif
 
         \li Select the \uicontrol {Modifies current document} check box to make sure
             that if the current document is modified by the tool, it is saved
@@ -121,6 +115,11 @@
     configuration file to the folder.
 
     \sa {Run QML files}, {Use external text editors}, {Use Qt Linguist}
+
+    \if defined(qtcreator)
+    \sa {Batch edit environment settings}, {Specify the environment for projects},
+    {Use Qt Creator variables}
+    \endif
 */
 
 /*!

doc/qtcreator/src/projects/creator-only/creator-build-settings-qmake.qdoc

@@ -21,7 +21,7 @@
     checkbox.
 
     Select the build directory in the \uicontrol {Build Directory} field. You
-    can use the \l{Using Qt Creator Variables}{variables} that are listed when
+    can use the \l{Use Qt Creator variables}{variables} that are listed when
     you select the \inlineimage icons/replace.png (\uicontrol {Variables})
     button.
 

doc/qtcreator/src/projects/creator-only/creator-projects-kits.qdoc

@@ -151,7 +151,7 @@
         \li Select \uicontrol Change to modify environment variable values for
             build environments in the \uicontrol {Edit Environment Changes}
             dialog. For more information about how to add and remove variable
-            values, see \l{Batch Editing}.
+            values, see \l{Batch edit environment settings}.
     \row
         \li \uicontrol {Force UTF-8 MSVC compiler output}
         \li Either switches the language of MSVC to English or keeps the

doc/qtcreator/src/projects/creator-only/creator-projects-settings-build.qdoc

@@ -110,10 +110,8 @@
     tested or grouping commands, are not supported because the value of the
     \uicontrol Executable field is always placed first when constructing the command.
 
-    You can use \l {Using Environment Variables}{environment variables} as
+    You can \l {Use Qt Creator variables}{use \QC variables} in arguments,
-    values in the fields. In addition, you can \l {Using Qt Creator Variables}
+    executable paths, and working directories.
-    {use \QC variables} in arguments, executable paths, and working
-    directories.
 
     \section1 Build Steps
 

doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc

@@ -1,16 +1,17 @@
-// Copyright (C) 2021 The Qt Company Ltd.
+// Copyright (C) 2023 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
-    \previouspage creator-build-dependencies.html
+    \page creator-how-set-project-environment.html
-    \page creator-project-settings-environment.html
+    \previouspage creator-how-tos.html
-    \nextpage creator-custom-output-parsers.html
 
-    \title Specifying Environment Settings
+    \ingroup creator-how-to-projects
 
-    You can specify the environment you want to use for building
+    \title Specify the environment for projects
-    a project in the \uicontrol {Build Environment} section of
+
-    the \uicontrol {Build Settings}.
+    The environment for a project is determined according to a settings hierarchy:
+
+    \image qtcreator-environment-settings-hierarchy.webp {Environment settings hierarchy}
 
     By default, the environment in which \QC was started is used and modified
     to include the Qt version. Depending on the selected Qt version, \QC
@@ -18,36 +19,109 @@
     existing environment variables or add, reset and unset new variables
     based on your project requirements.
 
-    To globally change the system environment from the one in which
+    The final environment is specified separately for each kit. With
-    \QC is started, select \preferences >
+    project-specific environment settings you can change the environment for
-    \uicontrol Environment > \uicontrol System, and then select
+    all kits that you use to build, deploy, and run the project simultaneously,
-    \uicontrol Change in the \uicontrol Environment field.
+    rather than having to change it separately for each kit.
+
+    The changes are stored in the local project-specific \c{CMakeLists.txt.user}
+    or \c{.pro.user} file, depending on the build system you use, such as CMake
+    or qmake. Therefore, they are not suitable for sharing between developers or
+    development PCs. To share settings, incorporate them into the build system.
+    For example, if you use CMake, make the changes in the \c {CMakeLists.txt}
+    file, and if you use qmake, make the changes in the \c{.pro} file.
+
+    \section1 Globally change the environment
+
+    To globally change the environment from the one in which \QC is started,
+    select \preferences > \uicontrol Environment > \uicontrol System, and then
+    select \uicontrol Change in the \uicontrol Environment field.
 
     \image qtcreator-preferences-environment-system.webp "Environment preferences System tab"
 
-    In addition, you can specify custom environment variables in the
+    \section1 Change the environment for a project
-    \uicontrol {Project Settings} > \uicontrol Environment settings.
-    They are added to all build environments. The final build environment
-    is specified separately for each kit. The project-specific environment
-    settings enable you to amend the build environment for all kits that
-    you use to build the project simultaneously, rather than having to edit
-    it separately for each kit.
 
-    \image qtcreator-build-environment.png "Build Environment"
+    To change the system environment for a project from the one in which
+    \QC is started, select \uicontrol Projects > \uicontrol {Project Settings}
+    > \uicontrol Environment.
 
-    The changes are stored in the local project specific \c{CMakeLists.txt.user}
+    \image qtcreator-projects-environment.webp {Environment tab in Project Settings}
-    or \c{.pro.user} file, depending on the build system you use. Therefore,
-    they are not suitable for sharing between developers or development PCs. To
-    share settings, incorporate them into the build system. For example, if you
-    use CMake, make the changes in the \c {CMakeLists.txt} file, and if you use
-    qmake, make the changes in the \c{.pro} file.
 
-    \section1 Batch Editing
+    \section1 Specify the build environment
 
-    To modify environment variable values for build or run environments,
+    Specify the build environment to use for a kit in \uicontrol Projects >
-    select \uicontrol {Batch Edit} in the \uicontrol {Build Environment}
+    \uicontrol {Build Settings} > \uicontrol {Build Environment}.
-    or \uicontrol {Environment} pane and enter environment variables in
+
-    the \uicontrol {Edit Environment} dialog.
+    \image qtcreator-build-environment.png {Build Environment section in Build Settings}
+
+    \section2 Clear the build environment
+
+    To build with a clean system environment, select the \uicontrol {Clear
+    system environment} check box. \QC discards the current environment, and
+    populates a clean system environment with the environment variables that
+    the compilers and tools need. Therefore, the environment is never totally
+    empty, even after you clear it.
+
+    \section1 Specify the run environment
+
+    \QC automatically selects the environment used for running the application
+    based on the \l{glossary-device}{device} type. You can edit the environment
+    or select another environment in \uicontrol Projects >
+    \uicontrol {Run Settings} > \uicontrol {Environment}.
+
+    You can edit existing environment variables or add, reset and unset new
+    variables.
+
+    \image qtcreator-run-environment.png {Environment section in Run Settings}
+
+    When running on the desktop, the \uicontrol {Build Environment} is used by
+    default, but you can also use the \uicontrol {System Environment} without the
+    additions made to the build environment.
+
+    To modify the environment variable values for the run environment,
+    double-click environment variables or their values and change them inline,
+    or select \uicontrol {Batch Edit} to change several variable values at a
+    time.
+
+    \section2 Clean the run environment
+
+    To run in a clean system environment, select \uicontrol {Clean Environment}.
+
+    \section2 Run on devices
+
+    When running on a mobile device connected to the development host, \QC
+    fetches information about the \uicontrol {Device Environment} from the device.
+    Usually, it does not make sense to edit the device environment.
+
+    \sa {Batch edit environment settings}, {Specifying Build Settings},
+    {Specifying Run Settings}, {Use Qt Creator variables}
+*/
+
+/*!
+    \page creator-how-to-batch-edit-environment-settings.html
+    \previouspage creator-how-tos.html
+
+    \ingroup creator-how-to-projects
+
+    \title Batch edit environment settings
+
+    You can change the environment variable values for build or run environments
+    either for a particular project or globally for all projects in the
+    \uicontrol {Edit Environment} dialog:
+
+    \list
+        \li To change values globally, select \uicontrol Change in the
+            \l {Globally change the environment}{global environment preferences}.
+        \li To change values for a project, select \uicontrol {Batch Edit} in the
+            \l {Change the environment for a project}{project},
+            \l {Specify the build environment}{build}, or
+            \l {Specify the run environment}{run} environment settings.
+    \endlist
+
+    \image qtcreator-edit-environment.webp {Edit Environment dialog}
+
+    Use the following syntax to enter environment variable names and values:
+    \c {<VARIABLE>=<VALUE>}.
 
     To remove a variable value from the environment, enter the variable name.
     For example, \c TEST sets the value of the \c TEST variable empty when
@@ -70,21 +144,6 @@
     To temporarily disable a variable, add a hash character (#) to the beginning
     of the line.
 
-    \section1 Clearing the System Environment
+    \sa {Specify the environment for projects}, {Specifying Build Settings},
-
+    {Use Qt Creator variables}
-    To build with a clean system environment, select the \uicontrol {Clear
-    system environment} check box. \QC discards the current environment, and
-    populates a clean system environment with the environment variables that
-    the compilers and tools need. Therefore, the environment is never totally
-    empty, even after you clear it.
-
-    \section1 Using Environment Variables
-
-    You can use any environment variables in build, deploy, and run
-    configurations. For a list of variable names, select \uicontrol {Build
-    Settings} > \uicontrol {Build Environment} > \uicontrol Details.
-    Environment variables are referenced using the native syntax: $VARNAME
-    or ${VARNAME} on Unix and %VARNAME% on Windows.
-
-    \include qtcreator-variables.qdocinc qtcreator variables
 */

doc/qtcreator/src/projects/creator-only/creator-projects-settings-overview.qdoc

@@ -14,13 +14,12 @@
 
     \title Configuring Projects
 
-    When you install Qt for a target platform, such as Android or QNX,
+    When you install Qt for a development or target platform, such as Linux,
-    \l{https://www.qt.io/download-qt-installer}{\QOI}
+    \macos, Windows, Android or QNX, \l{https://www.qt.io/download-qt-installer}
-    creates \l{glossary-buildandrun-kit}{kits} for the development
+    {\QOI} creates \l{glossary-buildandrun-kit}{kits} for the development targets.
-    targets.
 
-    Select the kits to use in the \uicontrol {Configure Projects}
+    Select the kits to use for a project in the \uicontrol {Configure Projects}
-    view when you open a project for the first time. At least one kit must be
+    view when you open the project for the first time. At least one kit must be
     active.
 
     To maintain the list of active kits for a currently open project, switch to
@@ -29,7 +28,7 @@
     \image qtcreator-projects-kits.webp {Sidebar in the Projects mode}
 
     To specify build or run settings for a kit, select \uicontrol Build or
-    \uicontrol Run below the kit.
+    \uicontrol Run below the kit name.
 
     \section1 Overriding Global Preferences
 
@@ -45,7 +44,7 @@
                 \li \l{Specify dependencies}{Dependencies}
                 \li \l{Document code}{Documentation Comments}
                 \li \l{Specify editor settings}{Editor}
-                \li \l{Specifying Environment Settings}{Environment}
+                \li \l{Specify the environment for projects}{Environment}
                 \li \l{Applying Refactoring Actions}{Quick Fixes}
                 \li \l{To-Do Entries}{To-Do} (experimental)
             \endlist
@@ -69,7 +68,7 @@
     lists the kits that are compatible with your project. To activate one or more
     kits, click them.
 
-    \image qtcreator-project-kits.png
+    \image qtcreator-project-kits.png {List of kits in Projects mode sidebar}
 
     The list displays kits from \preferences >
     \uicontrol Kits. Warning and error icons indicate that the kit configuration

doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-desktop.qdocinc

@@ -27,7 +27,7 @@
 
     To run with special environment variables set up, select them in the
     \uicontrol {Run Environment} section. For more information, see
-    \l {Selecting the Run Environment}.
+    \l {Specify the run environment}.
 
     When building an application, \QC creates a list of directories where the
     linker will look for libraries that the application links to. By

doc/qtcreator/src/projects/creator-only/creator-projects-settings-run.qdoc

@@ -95,31 +95,6 @@
     \include creator-projects-settings-run-qnx.qdocinc run settings qnx
     \include linux-mobile/creator-projects-settings-run-b2qt.qdocinc run settings boot2qt
 
-    \section1 Selecting the Run Environment
-
-    \QC automatically selects the environment used for running the application
-    based on the \l{glossary-device}{device} type. You can edit the environment
-    or select another environment in the \uicontrol {Run Environment} section.
-
-    You can edit existing environment variables or add, reset and unset new
-    variables.
-
-    \image qtcreator-run-environment.png {Run Environment section}
-
-    When running on the desktop, the \uicontrol {Build Environment} is used by
-    default, but you can also use the \uicontrol {System Environment} without the
-    additions made to the build environment. For more information, see
-    \l {Build Environment} and \l{Specifying Environment Settings}.
-
-    To run in a clean system environment, select \uicontrol {Clean Environment}.
-
-    When running on a mobile device connected to the development host, \QC
-    fetches information about the \uicontrol {Device Environment} from the device.
-    Usually, it does not make sense to edit the device environment.
-
-    To modify the environment variable values for the run environment, select
-    \uicontrol {Batch Edit}. For more information, see \l{Batch Editing}.
-
     \section1 Specifying a Custom Executable to Run
 
     If you use CMake, Meson or the generic project type in \QC, or want

doc/qtcreator/src/projects/creator-only/qtcreator-how-to-use-qtc-variables.qdoc

@@ -1,13 +1,19 @@
-// Copyright (C) 2021 The Qt Company Ltd.
+// Copyright (C) 2023 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
 /*!
-//! [qtcreator variables]
+    \page creator-how-to-use-qtc-variables.html
-    \section1 Using Qt Creator Variables
+    \previouspage creator-how-tos.html
 
-    You can use \QC variables in arguments, executable paths, and working
+    \ingroup creator-how-to-projects
-    directories. The variables take care of quoting their expansions, so you do
+
-    not need to put them in quotes.
+    \title Use Qt Creator variables
+
+    You can use \QC variables in \uicontrol Preferences,
+    \uicontrol {Build Settings}, and \uicontrol {Run Settings}, in fields that
+    set arguments, executable paths, and working directories, for example. The
+    variables take care of quoting their expansions, so you do not need to put
+    them in quotes.
 
     Select the \inlineimage icons/replace.png
     (\uicontrol {Variables}) button in a field to select from a list of
@@ -15,7 +21,7 @@
     For more information about each variable, move the cursor over it in the
     list.
 
-    \image qtcreator-variables.png "Qt Creator Variables dialog displaying a tooltip"
+    \image qtcreator-variables.png {Qt Creator Variables dialog showing a tooltip}
 
     The following syntax enables you to use environment variables as \QC
     variables: %{Env:VARNAME}.
@@ -38,7 +44,7 @@
     backreferences. For example, if \c %{variable} is \c my123var, then
     \c %{variable/(..)(\d+)/\2\1} is expanded to \c {123myvar}.
 
-    Instead of the forward slash, you can also use the pound sign (\c #) as
+    Instead of the forward slash, you can also use the number sign (\c #) as
     the substitution character. This can be helpful if the value is supposed
     to be a file path, in which case forward slashes might get translated
     to backslashes on Windows hosts.
@@ -48,5 +54,6 @@
     \badcode
     %{variable:-default}
     \endcode
-//! [qtcreator variables]
+
+    \sa {Specify the environment for projects}, {Specifying Build Settings},
 */

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -39,7 +39,6 @@
                         \li \l{Conan Build Configuration}
                     \endlist
                 \li \l{Specifying Run Settings}
-                \li \l{Specifying Environment Settings}
                 \li \l{Using Custom Output Parsers}
                 \li \l{Sharing Project Settings}
             \endlist