Doc: Display info about using Qt Creator variables in QDS Manual

They are needed for some more advanced actions.

- Move the section to a .qdocinc file that is included as
  necessary and modify defines where needed.
- Describe using tooltips to get more info about variables.
- Add a screenshot.

Change-Id: Ieb03ccf7de5f0c493c98ae356cdda4b4d3915832
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

4 files changed, 84 insertions, 45 deletions

diff --git a/doc/qtcreator/images/qtcreator-variables.png b/doc/qtcreator/images/qtcreator-variables.png
new file mode 100644
index 0000000000..ab306c0bca
--- /dev/null
+++ b/doc/qtcreator/images/qtcreator-variables.png
diff --git a/doc/qtcreator/src/editors/creator-code-completion.qdoc b/doc/qtcreator/src/editors/creator-code-completion.qdoc
index c635776fb5..67d0278b13 100644
--- a/doc/qtcreator/src/editors/creator-code-completion.qdoc
+++ b/doc/qtcreator/src/editors/creator-code-completion.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2020 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -218,12 +218,13 @@
     when you write code.
     \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{Using Qt Creator Variables}{predefined variables} in snippets.
+    in the snippet editor, depending on the snippet category.
     \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 provides you with:
 
@@ -319,5 +320,7 @@
     To use Nimsuggest, you must install it on the development PC. Then select
     \uicontrol Tools > \uicontrol Options > \uicontrol Nim > \uicontrol Tools,
     and enter the path to the tool executable in the \uicontrol Path field.
+    \else
+    \include qtcreator-variables.qdocinc qtcreator variables
     \endif
 */
diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc
index 5dbdb44b17..f038e90005 100644
--- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc
+++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-environment.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2020 The Qt Company Ltd.
+** Copyright (C) 2021 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the Qt Creator documentation.
@@ -93,49 +93,11 @@
 
     \section1 Using Environment Variables
 
-    You can use any environment variables to in build, deploy, and run
+    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}.
+    Settings} > \uicontrol {Build Environment} > \uicontrol Details.
     Environment variables are referenced using the native syntax: $VARNAME
     or ${VARNAME} on Unix and %VARNAME% on Windows.
 
-    \section1 Using Qt Creator Variables
-
-    You can use \QC variables in arguments, executable paths, and working
-    directories. The variables take care of quoting their expansions, so you do
-    not need to put them in quotes. Select the \inlineimage replace.png
-    (\uicontrol {Variables}) button in a field to select from a list of
-    variables that are available in a particular context.
-
-    The following syntax enables you to use environment variables as \QC
-    variables: %{Env:VARNAME}.
-
-    \QC uses pattern substitution when expanding variable names. To replace the
-    first match of \e pattern within \e variable with \e replacement, use:
-
-    \badcode
-    %{variable/pattern/replacement}
-    \endcode
-
-    To replace all matches of \e pattern within \e variable with \e replacement,
-    use:
-
-    \badcode
-    %{variable//pattern/replacement}
-    \endcode
-
-    The pattern can be a regular expression and the replacement can contain
-    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
-    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.
-
-    To use the default value if the variable is not set, use:
-
-    \badcode
-    %{variable:-default}
-    \endcode
+    \include qtcreator-variables.qdocinc qtcreator variables
 */
diff --git a/doc/qtcreator/src/projects/creator-qtcreator-variables.qdocinc b/doc/qtcreator/src/projects/creator-qtcreator-variables.qdocinc
new file mode 100644
index 0000000000..65c0fe10bf
--- /dev/null
+++ b/doc/qtcreator/src/projects/creator-qtcreator-variables.qdocinc
@@ -0,0 +1,74 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator documentation.
+**
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+**
+****************************************************************************/
+
+/*!
+//! [qtcreator variables]
+    \section1 Using Qt Creator Variables
+
+    You can use \QC variables in arguments, executable paths, and working
+    directories. The variables take care of quoting their expansions, so you do
+    not need to put them in quotes.
+
+    Select the \inlineimage replace.png
+    (\uicontrol {Variables}) button in a field to select from a list of
+    variables that are available in a particular context.
+    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"
+
+    The following syntax enables you to use environment variables as \QC
+    variables: %{Env:VARNAME}.
+
+    \QC uses pattern substitution when expanding variable names. To replace the
+    first match of \e pattern within \e variable with \e replacement, use:
+
+    \badcode
+    %{variable/pattern/replacement}
+    \endcode
+
+    To replace all matches of \e pattern within \e variable with \e replacement,
+    use:
+
+    \badcode
+    %{variable//pattern/replacement}
+    \endcode
+
+    The pattern can be a regular expression and the replacement can contain
+    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
+    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.
+
+    To use the default value if the variable is not set, use:
+
+    \badcode
+    %{variable:-default}
+    \endcode
+//! [qtcreator variables]
+*/