Doc: Move info about debugger settings

...to a separate .qdocinc file included from
"Interacting with the Debugger".

Change a conflicting section title in run settings docs.

Task-number: QTCREATORBUG-24500
Change-Id: I6e3e205d1dfdcfabaf80fc18bd2b73c1256644e4
Reviewed-by: hjk <hjk@qt.io>

4 files changed, 217 insertions, 195 deletions

diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdocinc b/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdocinc
new file mode 100644
index 0000000000..28fe490a02
--- /dev/null
+++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-settings.qdocinc
@@ -0,0 +1,212 @@
+/****************************************************************************
+**
+** 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.
+**
+****************************************************************************/
+
+/*!
+
+//! [debugger-settings]
+
+    \section1 Specifying Debugger Settings
+
+    To specify settings for managing debugger processes, select \uicontrol Tools
+     > \uicontrol Options > \uicontrol Debugger. In the \uicontrol General tab,
+     you can specify settings that are common to all debuggers.
+
+    \image qtcreator-debugger-general-options.png
+
+    \section2 Mapping Source Paths
+
+    To enable the debugger to step into the code and display the source code
+    when using a copy of the source tree at a location different from the one
+    at which the libraries were built, map the source paths to target paths:
+
+    \list 1
+        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Debugger >
+            \uicontrol General > \uicontrol Add.
+        \li In the \uicontrol {Source path} field, specify the source path in
+            the debug information of the executable as reported by the debugger.
+        \li In the \uicontrol {Target path} field, specify the actual location
+            of the source tree on the local machine.
+    \endlist
+
+    \section2 Specifying GDB Settings
+
+    To specify settings for managing the GDB process, select \uicontrol Tools >
+    \uicontrol Options > \uicontrol Debugger > \uicontrol GDB.
+
+    \image qtcreator-gdb-options.png "GDB options"
+
+    To specify a timeout for terminating non-responsive GDB processes, set the
+    number of seconds to wait in the \uicontrol {GDB timeout} field. The default
+    value of 20 seconds should be sufficient for most applications, but if
+    loading big libraries or listing source files takes much longer than
+    that on slow machines, you should increase the value.
+
+    To compress several steps into one step for less noisy debugging when
+    stepping into code, select the \uicontrol {Skip known frames when stepping}
+    check box. For example, the atomic reference counting code is skipped, and
+    a single \e {Step Into} for a signal emission ends up directly in the slot
+    connected to it.
+
+    To display a message box as soon as your application receives a signal, such
+    as SIGSEGV, during debugging, select the \uicontrol {Show a message box when
+    receiving a signal} check box.
+
+    GDB allows setting breakpoints on source lines for which no code was
+    generated. In such situations, the breakpoint is shifted to the next
+    source code line for which the code was actually generated. To reflect
+    such temporary changes by moving the breakpoint markers in the source
+    code editor, select the \uicontrol {Adjust breakpoint locations} check box.
+
+    To specify whether the dynamic or the static type of objects will be
+    displayed, select the \uicontrol {Use dynamic object type for display}
+    check box. Keep in mind that choosing the dynamic type might be slower.
+
+    To allow reading the user's default .gdbinit file on debugger startup,
+    select the \uicontrol {Load .gdbinit file on startup} check box.
+
+    To use the default GDB pretty printers installed in your system
+    or linked to the libraries your application uses, select the
+    \uicontrol {Load system GDB pretty printers} check box.
+
+    By default, GDB shows AT&T style disassembly. To switch to the Intel style,
+    select the \uicontrol {Use Intel style disassembly} check box.
+
+    To execute GDB commands after GDB has been started, but before the debugged
+    program is started or attached, and before the debugging helpers are
+    initialized, enter them in the \uicontrol {Additional Startup Commands}
+    field.
+
+    To execute GDB commands after GDB has successfully attached to remote
+    targets, enter them in the \uicontrol {Additional Attach Commands} field.
+    You can add commands to further set up the target here, such as
+    \c {monitor reset} or \c {load}.
+
+    To execute simple Python commands, prefix them with \c python. To execute
+    sequences of Python commands spanning multiple lines, prepend the block
+    with \c python  on a separate line, and append \c end on a separate line.
+    To execute arbitrary Python scripts, use
+    \c {python execfile('/path/to/script.py')}.
+
+    \section2 Specifying Extended GDB Settings
+
+    To specify extended settings for GBD, select \uicontrol Tools >
+    \uicontrol Options > \uicontrol Debugger > \uicontrol {GDB Extended}.
+    The settings give access to advanced or experimental functions of GDB.
+    Enabling them may negatively impact your debugging experience, so use
+    them with care.
+
+    \image qtcreator-gdb-extended-options.png "GDB Extended options"
+
+    To use asynchronous mode to control the inferior, select the
+    respective check box.
+
+    To add common paths to locations of debug information, such as
+    \c {/usr/src/debug}, when starting GDB, select the
+    \uicontrol {Use common locations for debug information} check box.
+
+    To stop when \c qWarning, \c qFatal, or \c abort is called, select the
+    respective check box.
+
+    To enable stepping backwards, select the \uicontrol {Enable reverse
+    debugging} check box. This feature is very slow and unstable on the
+    GDB side. It exhibits unpredictable behavior when going backwards over
+    system calls and is very likely to destroy your debugging session.
+
+    To keep debugging all children after a fork, select the
+    \uicontrol {Debug all child processes} check box.
+
+    \section2 Specifying CDB Settings
+
+    To specify settings for managing the CDB process, select \uicontrol Tools >
+    \uicontrol Options > \uicontrol Debugger > \uicontrol CDB.
+
+    \image qtcreator-cdb-options.png "CDB options"
+
+    You can specify additional arguments for starting CDB in the
+    \uicontrol {Additional arguments} field.
+
+    If a console application does not start up properly in the configured
+    console and the subsequent attach fails, you can diagnose the issue by
+    using CDB's native console. Select the \uicontrol {Use CDB console}
+    check box to override the console set in the Windows system
+    environment variables. Note that the native console does not
+    prompt on application exit.
+
+    To automatically add a breakpoint on the \c CrtCbgReport() function,
+    select the \uicontrol {Stop when CrtCbgReport() is called} check box.
+    This catches runtime error messages caused by \c assert(), for example.
+
+    In the \uicontrol {Break on} group, specify whether the debugger should
+    break on C++ exceptions, on thread creation or exit, on loading or
+    unloading the specified \l{Viewing Modules}{application modules}, or on
+    the specified output.
+
+    To disable first-chance break on access violation exceptions, select the
+    \uicontrol {Ignore first chance access violations} check box.
+    The second occurrence of an access violation will break into the debugger.
+
+    CDB enables setting breakpoints in comments or on source lines for which
+    no code was generated. In such situations, the breakpoint is shifted to
+    the next source code line for which the code was actually generated. To
+    reflect such temporary changes by moving the breakpoint markers in the
+    source code editor, select the \uicontrol {Correct breakpoint location}
+    check box. For more information, see \l{Setting Breakpoints}.
+
+    To use the abstraction layer provided by Python Dumper
+    classes to create a description of data items displayed
+    in the  \uicontrol Locals and \uicontrol Expressions
+    views, select the \uicontrol {Use Python dumper} check box.
+    For more information, see \l{Debugging Helper Implementation}.
+
+    To add information about first-chance and second-chance exceptions
+    to the \uicontrol Issues output pane, select the check boxes
+    in the \uicontrol {Add Exceptions to the Issues View} group.
+
+    \section2 Setting CDB Paths on Windows
+
+    To obtain debugging information for the operating system libraries for
+    debugging Windows applications, add the Symbol Server provided by Microsoft
+    to the symbol search path of the debugger:
+
+    \list 1
+        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Debugger >
+            \uicontrol {CDB Paths}.
+            \image qtcreator-debugger-cdb-paths.png
+        \li In the \uicontrol {Symbol Paths} group, select \uicontrol Insert.
+        \li Select the directory where you want to store the cached information.
+            Use a subfolder in a temporary directory, such as
+            \c {C:\temp\symbolcache}.
+        \li Select \uicontrol OK.
+    \endlist
+
+    \note Populating the cache might take a long time on a slow network
+    connection.
+
+    To use the Source Server infrastructure for fetching missing source files
+    directly from version control or the web, enter the following string in
+    the \uicontrol {Source Paths} field: \c srv*.
+
+//! [debugger-settings]
+*/
diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc
index 1cbfac3d04..84f3132ea2 100644
--- a/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc
+++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger-setup.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2019 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.
@@ -230,198 +230,6 @@
 
     We recommend using the LLDB version that is delivered with the latest Xcode.
 
-    \section1 Specifying Debugger Settings
-
-    To specify settings for managing debugger processes, select \uicontrol Tools
-     > \uicontrol Options > \uicontrol Debugger. In the \uicontrol General tab,
-     you can specify settings that are common to all debuggers.
-
-     \image qtcreator-debugger-general-options.png
-
-    \section2 Specifying GDB Settings
-
-    To specify settings for managing the GDB process, select \uicontrol Tools >
-    \uicontrol Options > \uicontrol Debugger > \uicontrol GDB.
-
-    \image qtcreator-gdb-options.png "GDB options"
-
-    To specify a timeout for terminating non-responsive GDB processes, set the
-    number of seconds to wait in the \uicontrol {GDB timeout} field. The default
-    value of 20 seconds should be sufficient for most applications, but if
-    loading big libraries or listing source files takes much longer than
-    that on slow machines, you should increase the value.
-
-    To compress several steps into one step for less noisy debugging when
-    stepping into code, select the \uicontrol {Skip known frames when stepping}
-    check box. For example, the atomic reference counting code is skipped, and
-    a single \e {Step Into} for a signal emission ends up directly in the slot
-    connected to it.
-
-    To display a message box as soon as your application receives a signal, such
-    as SIGSEGV, during debugging, select the \uicontrol {Show a message box when
-    receiving a signal} check box.
-
-    GDB allows setting breakpoints on source lines for which no code was
-    generated. In such situations, the breakpoint is shifted to the next
-    source code line for which the code was actually generated. To reflect
-    such temporary changes by moving the breakpoint markers in the source
-    code editor, select the \uicontrol {Adjust breakpoint locations} check box.
-
-    To specify whether the dynamic or the static type of objects will be
-    displayed, select the \uicontrol {Use dynamic object type for display}
-    check box. Keep in mind that choosing the dynamic type might be slower.
-
-    To allow reading the user's default .gdbinit file on debugger startup,
-    select the \uicontrol {Load .gdbinit file on startup} check box.
-
-    To use the default GDB pretty printers installed in your system
-    or linked to the libraries your application uses, select the
-    \uicontrol {Load system GDB pretty printers} check box.
-
-    By default, GDB shows AT&T style disassembly. To switch to the Intel style,
-    select the \uicontrol {Use Intel style disassembly} check box.
-
-    To execute GDB commands after GDB has been started, but before the debugged
-    program is started or attached, and before the debugging helpers are
-    initialized, enter them in the \uicontrol {Additional Startup Commands}
-    field.
-
-    To execute GDB commands after GDB has successfully attached to remote
-    targets, enter them in the \uicontrol {Additional Attach Commands} field.
-    You can add commands to further set up the target here, such as
-    \c {monitor reset} or \c {load}.
-
-    To execute simple Python commands, prefix them with \c python. To execute
-    sequences of Python commands spanning multiple lines, prepend the block
-    with \c python  on a separate line, and append \c end on a separate line.
-    To execute arbitrary Python scripts, use
-    \c {python execfile('/path/to/script.py')}.
-
-    \section2 Specifying Extended GDB Settings
-
-    To specify extended settings for GBD, select \uicontrol Tools >
-    \uicontrol Options > \uicontrol Debugger > \uicontrol {GDB Extended}.
-    The settings give access to advanced or experimental functions of GDB.
-    Enabling them may negatively impact your debugging experience, so use
-    them with care.
-
-    \image qtcreator-gdb-extended-options.png "GDB Extended options"
-
-    To use asynchronous mode to control the inferior, select the
-    respective check box.
-
-    To add common paths to locations of debug information, such as
-    \c {/usr/src/debug}, when starting GDB, select the
-    \uicontrol {Use common locations for debug information} check box.
-
-    To stop when \c qWarning, \c qFatal, or \c abort is called, select the
-    respective check box.
-
-    To enable stepping backwards, select the \uicontrol {Enable reverse
-    debugging} check box. This feature is very slow and unstable on the
-    GDB side. It exhibits unpredictable behavior when going backwards over
-    system calls and is very likely to destroy your debugging session.
-
-    To keep debugging all children after a fork, select the
-    \uicontrol {Debug all child processes} check box.
-
-    \section2 Specifying CDB Settings
-
-    To specify settings for managing the CDB process, select \uicontrol Tools >
-    \uicontrol Options > \uicontrol Debugger > \uicontrol CDB.
-
-    \image qtcreator-cdb-options.png "CDB options"
-
-    You can specify additional arguments for starting CDB in the
-    \uicontrol {Additional arguments} field.
-
-    If a console application does not start up properly in the configured
-    console and the subsequent attach fails, you can diagnose the issue by
-    using CDB's native console. Select the \uicontrol {Use CDB console}
-    check box to override the console set in the Windows system
-    environment variables. Note that the native console does not
-    prompt on application exit.
-
-    To automatically add a breakpoint on the \c CrtCbgReport() function,
-    select the \uicontrol {Stop when CrtCbgReport() is called} check box.
-    This catches runtime error messages caused by \c assert(), for example.
-
-    In the \uicontrol {Break on} group, specify whether the debugger should
-    break on C++ exceptions, on thread creation or exit, on loading or
-    unloading the specified \l{Viewing Modules}{application modules}, or on
-    the specified output.
-
-    To disable first-chance break on access violation exceptions, select the
-    \uicontrol {Ignore first chance access violations} check box.
-    The second occurrence of an access violation will break into the debugger.
-
-    CDB enables setting breakpoints in comments or on source lines for which
-    no code was generated. In such situations, the breakpoint is shifted to
-    the next source code line for which the code was actually generated. To
-    reflect such temporary changes by moving the breakpoint markers in the
-    source code editor, select the \uicontrol {Correct breakpoint location}
-    check box. For more information, see \l{Setting Breakpoints}.
-
-    To use the abstraction layer provided by Python Dumper
-    classes to create a description of data items displayed
-    in the  \uicontrol Locals and \uicontrol Expressions
-    views, select the \uicontrol {Use Python dumper} check box.
-    For more information, see \l{Debugging Helper Implementation}.
-
-    To add information about first-chance and second-chance exceptions
-    to the \uicontrol Issues output pane, select the check boxes
-    in the \uicontrol {Add Exceptions to the Issues View} group.
-
-    \section1 Mapping Source Paths
-
-    To enable the debugger to step into the code and display the source code
-    when using a copy of the source tree at a location different from the one
-    at which the libraries were built, map the source paths to target paths:
-
-    \list 1
-
-        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Debugger >
-            \uicontrol General > \uicontrol Add.
-
-        \li In the \uicontrol {Source path} field, specify the source path in
-            the debug information of the executable as reported by the debugger.
-
-        \li In the \uicontrol {Target path} field, specify the actual location
-            of the source tree on the local machine.
-
-    \endlist
-
-    \section1 Setting CDB Paths on Windows
-
-    To obtain debugging information for the operating system libraries for
-    debugging Windows applications, add the Symbol Server provided by Microsoft
-    to the symbol search path of the debugger:
-
-    \list 1
-
-        \li Select \uicontrol Tools > \uicontrol Options > \uicontrol Debugger >
-            \uicontrol {CDB Paths}.
-
-            \image qtcreator-debugger-cdb-paths.png
-
-        \li In the \uicontrol {Symbol Paths} group, select \uicontrol Insert.
-
-        \li Select the directory where you want to store the cached information.
-
-            Use a subfolder in a temporary directory, such as
-            \c {C:\temp\symbolcache}.
-
-        \li Select \uicontrol OK.
-
-    \endlist
-
-    \note Populating the cache might take a long time on a slow network
-    connection.
-
-    To use the Source Server infrastructure for fetching missing source files
-    directly from version control or the web, enter the following string in
-    the \uicontrol {Source Paths} field: \c srv*.
-
     \section1 Setting up FSF GDB for \macos
 
     To use FSF GDB on \macos, you must sign it and add it to the \QC
diff --git a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc
index b10498edc2..723950ef2f 100644
--- a/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc
+++ b/doc/qtcreator/src/debugger/creator-only/creator-debugger.qdoc
@@ -784,6 +784,8 @@
     \l{https://sourceware.org/gdb/onlinedocs/gdb/Core-File-Generation.html}.
 
     \endomit
+
+    \include creator-debugger-settings.qdocinc debugger-settings
 */
 
 
diff --git a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdocinc b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdocinc
index ef3389e27d..ce5b73d07e 100644
--- a/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdocinc
+++ b/doc/qtcreator/src/projects/creator-only/creator-projects-settings-run-debug.qdocinc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 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.
@@ -26,7 +26,7 @@
 /*!
 //! [run settings debugger]
 
-    \section1 Specifying Debugger Settings
+    \section1 Enabling Debugging
 
     \image qtquick-debugging-settings.png "Debugger Settings"