Add detailed information about profiles

The documentation was missing essential inforation about the concept of profiles.
This is especially important for beginners. Although profiles would deserve a
page of its own, I decided to extend the configuring page because a lot of
useful information was already there.

Task-number: QBS-1386
Change-Id: Ia9c33eb3babcfe902b55583b15db9c4a9ecf87a4
Reviewed-by: Richard Weickelt <richard@weickelt.de>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Christian Kandeler <christian.kandeler@qt.io>

5 files changed, 61 insertions, 22 deletions

diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc
index b3a46bead..f559b481d 100644
--- a/doc/qbs.qdoc
+++ b/doc/qbs.qdoc
@@ -54,7 +54,7 @@
        \li  \l{Setup}
            \list
                \li  \l{Installing}
-               \li  \l{Configuring}
+               \li  \l{Configuring Profiles and Preferences}
                \li  \l{Managing Qt Versions}
            \endlist
        \li  \l{Usage}
@@ -417,7 +417,7 @@
 
     \list
         \li  \l{Installing}
-        \li  \l{Configuring}
+        \li  \l{Configuring Profiles and Preferences}
         \li  \l{Managing Qt Versions}
     \endlist
 */
@@ -656,37 +656,76 @@
     \page configuring.html
     \nextpage qt-versions.html
 
-    \title Configuring
+    \title Configuring Profiles and Preferences
 
-    \section1 Setting Up Toolchains
+    Profiles contain properties that apply to one or more projects. They are
+    stored independently of the project files and are usually not shared between
+    build hosts. Typically, profiles contain module properties, such as
+    installation paths of tools or libraries on the host computer. This approach
+    has the following advantages, among others:
+
+    \list
+        \li Team members with different computer setups can work together
+            smoothly because no host-specific settings end up in the project
+            files.
+        \li Different versions of a tool or library can be used to build the
+            same project without affecting each other.
+    \endlist
+
+    For example, a profile for building C++ applications contains at least the
+    installation path and the type of the compiler toolchain. A profile for
+    building Qt applications contains the toolchain-specific properties as well
+    as the installation paths of the Qt modules.
+
+    This topic describes profiles stored in the \QBS settings. In some cases it
+    might be beneficial to keep profiles explicitly in the project sources. This
+    can be achieved with the \l{Profile} item.
+
+    \section1 Setting Up Toolchain Profiles
+
+    \QBS comes with a helper tool \l{setup-toolchains} that can
+    create profiles for many toolchains. Open a terminal window and type:
 
-    Open a build shell (on Windows open an MSVC command prompt,
-    on other platforms you can usually open the default shell):
     \code
     qbs setup-toolchains --detect
     \endcode
 
-    The tool chain detector automatically sets up a profile for each detected tool chain.
-    You can list the existing profiles by running:
+    This will automatically set up a profile for each detected toolchain on your
+    computer. You can list the existing profiles by running:
+
     \code
     qbs config --list profiles
     \endcode
 
-    Now you should be ready to build your first project with \QBS.
-    Go into examples/helloworld-minimal and type:
+    Some toolchains, especially for bare-metal targets, may require additional
+    module properties. Those can be added with the \l{config} or the
+    \l{config-ui} tools. Now you should be ready to build your first project
+    with \QBS. Go into examples/helloworld-minimal and type:
 
     \code
-    qbs profile:<profile name>
+    qbs build profile:<profile name>
     \endcode
 
-    If you want to build projects that use Qt, additional steps are necessary. Please refer to
+    You have successfully built your first \QBS project. If you want to build
+    projects that use Qt, additional steps are necessary. Please refer to
     \l{Managing Qt Versions} for more information.
 
-    \section1 Managing Settings
+    \section1 Global Preferences
+
+    In addition to profiles, \QBS provides some global preferences such as \c
+    qbsSearchPaths and \c defaultProfile.
+
+    \section1 Managing Profiles and Preferences
+
+    You can use the \l{config} command to manage all \QBS configuration
+    settings, such as profiles and global preferences from the command line,
+    for example:
+
+    \code
+    qbs config profiles.<someprofile>.qbs.architecture arm
+    \endcode
 
-    You can use the \l{config} command to manage \QBS settings, such as
-    preferences and profiles from the command line or the \l{config-ui}
-    command to open the \QBS Settings application where you can manage the
+    For convenience, \QBS provides a tool \l{config-ui} where you can manage the
     settings in a hierarchical view.
 
     \image qbs-settings-gui.png
@@ -921,7 +960,7 @@
     \endcode
 
     The properties that can be set for the \a cpp module are used to control the behavior of
-    your C++ tool chain.
+    your C++ toolchain.
     In addition, you can use FileTaggers and Rules that are explained later.
 
     As soon as your product depends on a module, it can set the properties of the
diff --git a/doc/reference/cli/tools/cli-config-ui.qdoc b/doc/reference/cli/tools/cli-config-ui.qdoc
index 66f46e3e1..d900841d6 100644
--- a/doc/reference/cli/tools/cli-config-ui.qdoc
+++ b/doc/reference/cli/tools/cli-config-ui.qdoc
@@ -49,7 +49,7 @@
 
     \image qbs-settings-gui.png
 
-    For more information, see \l{Configuring}.
+    For more information, see \l{Configuring Profiles and Preferences}.
 
     \section1 Options
 
diff --git a/doc/reference/cli/tools/cli-config.qdoc b/doc/reference/cli/tools/cli-config.qdoc
index e32ffee0e..2b78ff8ef 100644
--- a/doc/reference/cli/tools/cli-config.qdoc
+++ b/doc/reference/cli/tools/cli-config.qdoc
@@ -71,7 +71,7 @@
     You can use the \l{config-ui} command to open the Qbs Settings tool for
     managing settings in a hierarchical view.
 
-    For more information, see \l{Configuring}, \l{Managing Qt Versions},
+    For more information, see \l{Configuring Profiles and Preferences}, \l{Managing Qt Versions},
     \l{Modules}, \l {List of Modules}, and \l{Custom Modules and Items}.
 
     \section1 Options
diff --git a/doc/reference/cli/tools/cli-setup-toolchains.qdoc b/doc/reference/cli/tools/cli-setup-toolchains.qdoc
index af3b25069..70cb0c23b 100644
--- a/doc/reference/cli/tools/cli-setup-toolchains.qdoc
+++ b/doc/reference/cli/tools/cli-setup-toolchains.qdoc
@@ -52,7 +52,7 @@
     compiler executable. If that fails, you need to provide the compiler type as
     a value of the \c --type option.
 
-    For more information, see \l{Configuring}.
+    For more information, see \l{Configuring Profiles and Preferences}.
 
     \section1 Options
 
diff --git a/doc/reference/items/language/profile.qdoc b/doc/reference/items/language/profile.qdoc
index b519ac886..b0eccc803 100644
--- a/doc/reference/items/language/profile.qdoc
+++ b/doc/reference/items/language/profile.qdoc
@@ -36,8 +36,8 @@
     \brief Creates a profile within the project.
 
     The profiles used by \QBS are normally set up on a user's machine and are then available
-    to all projects. See the \l Configuring section for information on how to set up and
-    use profiles on the command line.
+    to all projects. See \l{Configuring Profiles and Preferences} for information on how
+    to set up and use profiles on the command line.
     In some rare cases, however, the creator of a project has complete knowledge about the system
     on which that project is to be built. Then it can make sense to integrate the profile into
     the project: