Doc: Revise Qt dbus module landing page

Move some of the detailed information into its own overview page and
reorganize the contents structure. Also, escape the _ character.

Task-number: QTBUG-100369
Pick-to: 6.3
Change-Id: I396877912bed66537e4a97ee3d109ff92e15d843
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

2 files changed, 229 insertions, 172 deletions

diff --git a/src/dbus/doc/src/qtdbus-index.qdoc b/src/dbus/doc/src/qtdbus-index.qdoc
index c2963690f9..ace0c8c338 100644
--- a/src/dbus/doc/src/qtdbus-index.qdoc
+++ b/src/dbus/doc/src/qtdbus-index.qdoc
@@ -32,188 +32,62 @@
 
     \keyword QtDBus
 
-
-    \section1 Introduction
-
     D-Bus is an Inter-Process Communication (IPC) and Remote Procedure
     Calling (RPC) mechanism originally developed for Linux to replace
     existing and competing IPC solutions with one unified protocol. It
-    has also been designed to allow communication between system-level
+    was also designed to allow communication between system-level
     processes (such as printer and hardware driver services) and
     normal user processes.
 
     It uses a fast, binary message-passing protocol, which is suitable
     for same-machine communication due to its low latency and low
     overhead. Its specification is currently defined by the
-    \tt{freedesktop.org} project, and is available to all parties.
+    \tt{freedesktop.org} project and is available to all parties.
 
-    Communication in general happens through a central server
-    application, called the "bus" (hence the name), but direct
+    Communication, in general, happens through a central server
+    application called the "bus" (hence the name), but direct
     application-to-application communication is also possible. When
     communicating on a bus, applications can query which other
     applications and services are available, as well as activate one
     on demand.
 
-    \section1 The Buses
-
-    D-Bus buses are used when many-to-many communication is
-    desired. In order to achieve that, a central server is launched
-    before any applications can connect to the bus: this server is
-    responsible for keeping track of the applications that are
-    connected and for properly routing messages from their source to
-    their destination.
-
-    In addition, D-Bus defines two well-known buses, called the
-    system bus and the session bus. These buses are special in the
-    sense that they have well-defined semantics: some services are
-    defined to be found in one or both of these buses.
-
-    For example, an application wishing to query the list of hardware
-    devices attached to the computer will probably communicate to a
-    service available on the system bus, while the service providing
-    opening of the user's web browser will probably be found on the
-    session bus.
-
-    On the system bus, one can also expect to find restrictions on
-    what services each application is allowed to offer. Therefore, one
-    can be reasonably certain that, if a certain service is present,
-    it is being offered by a trusted application.
-
-    \section1 Concepts
-
-    \section2 Messages
-
-    On the low level, applications communicate over D-Bus by sending
-    messages to one another. Messages are used to relay the remote
-    procedure calls as well as the replies and errors associated
-    with them. When used over a bus, messages have a destination,
-    which means they are routed only to the interested parties,
-    avoiding congestion due to "swarming" or broadcasting.
-
-    A special kind of message called a "signal message"
-    (a concept based on Qt's \l {Signals and Slots} mechanism),
-    however, does not have a pre-defined destination. Since its
-    purpose is to be used in a one-to-many context, signal messages
-    are designed to work over an "opt-in" mechanism.
-
-    The Qt D-Bus module fully encapsulates the low-level concept of
-    messages into a simpler, object-oriented approach familiar to Qt
-    developers. In most cases, the developer need not worry about
-    sending or receiving messages.
-
-    \section2 Service Names
-
-    When communicating over a bus, applications obtain what is
-    called a "service name": it is how that application chooses to be
-    known by other applications on the same bus. The service names
-    are brokered by the D-Bus bus daemon and are used to
-    route messages from one application to another. An analogous
-    concept to service names are IP addresses and hostnames: a
-    computer normally has one IP address and may have one or more
-    hostnames associated with it, according to the services that it
-    provides to the network.
-
-    On the other hand, if a bus is not used, service names are also
-    not used. If we compare this to a computer network again, this
-    would equate to a point-to-point network: since the peer is
-    known, there is no need to use hostnames to find it or its IP
-    address.
-
-    The format of a D-Bus service name is in fact very similar to a
-    host name: it is a dot-separated sequence of letters and
-    digits. The common practice is even to name one's service name
-    according to the domain name of the organization that defined
-    that service.
-
-    For example, the D-Bus service is defined by
-    \tt{freedesktop.org} and can be found on the bus under the
-    service name:
-
-    \snippet code/doc_src_introtodbus.qdoc 0
-
-    \section2 Object Paths
-
-    Like network hosts, applications provide specific services to
-    other applications by exporting objects. Those objects are
-    hierarchically organized, much like the parent-child
-    relationship that classes derived from QObject possess. One
-    difference, however, is that there is the concept of "root
-    object", which all objects have as the ultimate parent.
-
-    If we continue our analogy with Web services, object paths
-    equate to the path part of a URL:
-
-    \image qurl-ftppath.png
-
-    Like them, object paths in D-Bus are formed resembling path
-    names on the filesystem: they are slash-separated labels, each
-    consisting of letters, digits and the underscore character
-    ("\_"). They must always start with a slash and must not end with
-    one.
-
-    \section2 Interfaces
+    \section1 Using the Module
 
-    Interfaces are similar to C++ abstract classes and Java's
-    \c interface keyword and declare the "contract" that is
-    established between caller and callee. That is, they establish
-    the names of the methods, signals, and properties that are
-    available as well as the behavior that is expected from either
-    side when communication is established.
+    \include {module-use.qdocinc} {using the c++ api}
 
-    Qt uses a very similar mechanism in its \l {How to Create Qt
-    Plugins}{Plugin system}: Base classes in C++ are associated
-    with a unique identifier by way of the Q_DECLARE_INTERFACE()
-    macro.
+    \include {module-use.qdocinc} {building with cmake} {DBus}
 
-    D-Bus interface names are, in fact, named in a manner similar to
-    what is suggested by the Qt Plugin System: an identifier usually
-    constructed from the domain name of the entity that defined that
-    interface.
+    \section1 Articles and Guides
 
-    \section2 Cheat Sheet
-
-    To facilitate remembering of the naming formats and their
-    purposes, the following table can be used:
-
-    \table 90%
-    \header \li D-Bus Concept  \li Analogy            \li Name format
-    \row    \li Service name   \li Network hostnames  \li Dot-separated
-                                                       ("looks like a hostname")
-    \row    \li Object path    \li URL path component \li Slash-separated
-                                                       ("looks like a path")
-    \row    \li Interface      \li Plugin identifier  \li Dot-separated
-    \endtable
-
-    \section1 Debugging
-
-    When developing applications that use D-Bus, it is sometimes useful to be able
-    to see information about the messages that are sent and received across the
-    bus by each application.
-
-    This feature can be enabled on a per-application basis by setting the
-    \c QDBUS_DEBUG environment variable before running each application.
-    For example, we can enable debugging only for the car in the
-    \l{D-Bus Remote Controlled Car Example} by running the controller and the
-    car in the following way:
-
-    \snippet code/doc_src_introtodbus.qdoc QDBUS_DEBUG
-
-    Information about the messages will be written to the console the application
-    was launched from.
+    The following documents contain information about Qt's D-Bus integration
+    features and provide details about the mechanisms used to send and receive
+    type information over the bus:
 
+    \list
+      \li \l {Qt D-Bus Overview}
+      \li \l {Using Qt D-Bus Adaptors}
+      \li \l {The Qt D-Bus Type System}
+      \li \l {Qt D-Bus XML compiler (qdbusxml2cpp)}
+      \li \l{D-Bus Viewer}
+    \endlist
 
-    \include module-use.qdocinc using qt module
-    \snippet snippets/CMakeLists.txt cmake_use
+    \section1 Examples
 
-    See also the \l {Build with CMake} overview.
+    \list
+      \li \l{Qt D-Bus Examples}
+    \endlist
 
-    \include module-use.qdocinc building with qmake
-    \snippet snippets/snippets.pro qmake_use
+    \section1 Reference
 
+    \list
+      \li \l{Qt D-Bus C++ Classes}
+      \li \l{CMake Commands in Qt6 DBus}
+    \endlist
 
     \section1 Module Evolution
+
     \l{Changes to Qt D-Bus} lists important changes in the module API
-    and functionality that were done for the Qt 6 series of Qt.
+    and functionality that were made for the Qt 6 series of Qt.
 
     \section1 Licenses and Attributions
 
@@ -224,25 +98,9 @@
     See \l{Qt Licensing} for further details.
 
     Furthermore, Qt D-Bus in Qt \QtVersion may contain third party
-    modules under following permissive licenses:
+    modules under the following permissive licenses:
 
     \generatelist{groupsbymodule attributions-qtdbus}
-
-    \section1 Further Reading
-
-    The following documents contain information about Qt's D-Bus integration
-    features, and provide details about the mechanisms used to send and receive
-    type information over the bus:
-
-    \list
-    \li \l{Using Qt D-Bus Adaptors}
-    \li \l{The Qt D-Bus Type System}
-    \li \l{Qt D-Bus XML compiler (qdbusxml2cpp)}
-    \li \l{Qt D-Bus C++ Classes}
-    \li \l{CMake Commands in Qt6 DBus}
-    \li \l{Qt D-Bus Examples}
-    \li \l{D-Bus Viewer}
-    \endlist
 */
 
 /*!
diff --git a/src/dbus/doc/src/qtdbus-overview.qdoc b/src/dbus/doc/src/qtdbus-overview.qdoc
new file mode 100644
index 0000000000..2b37b33527
--- /dev/null
+++ b/src/dbus/doc/src/qtdbus-overview.qdoc
@@ -0,0 +1,199 @@
+/****************************************************************************
+**
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtdbus-overview.html
+    \title Qt D-Bus Overview
+    \brief Provides insight into the Qt Qt D-Bus module.
+
+    D-Bus is an Inter-Process Communication (IPC) and Remote Procedure
+    Calling (RPC) mechanism originally developed for Linux to replace
+    existing and competing IPC solutions with one unified protocol. It
+    was also designed to allow communication between system-level
+    processes (such as printer and hardware driver services) and
+    normal user processes.
+
+    It uses a fast, binary message-passing protocol, which is suitable
+    for same-machine communication due to its low latency and low
+    overhead. Its specification is currently defined by the
+    \tt{freedesktop.org} project and is available to all parties.
+
+    Communication, in general, happens through a central server
+    application called the "bus" (hence the name), but direct
+    application-to-application communication is also possible. When
+    communicating on a bus, applications can query which other
+    applications and services are available, as well as activate one
+    on demand.
+
+    \section1 The Buses
+
+    D-Bus buses are used when many-to-many communication is
+    desired. In order to achieve that, a central server is launched
+    before any application can connect to the bus. This server is
+    responsible for keeping track of the applications that are
+    connected and for properly routing messages from their source to
+    their destination.
+
+    In addition, D-Bus defines two well-known buses, called the
+    system bus and the session bus. These buses are special in the
+    sense that they have well-defined semantics: some services are
+    defined to be found in one or both of these buses.
+
+    For example, an application wishing to query the list of hardware
+    devices attached to the computer will probably communicate to a
+    service available on the system bus, while the service providing
+    opening of the user's web browser will probably be found on the
+    session bus.
+
+    On the system bus, you can also expect to find restrictions on
+    what services each application is allowed to offer. Therefore, you
+    can be reasonably certain that if a certain service is present,
+    it's being offered by a trusted application.
+
+    \section1 Concepts
+
+    \section2 Messages
+
+    On the low level, applications communicate over D-Bus by sending
+    messages to one another. Messages are used to relay the remote
+    procedure calls as well as the replies and errors associated
+    with them. When used over a bus, messages have a destination,
+    which means they are routed only to the interested parties,
+    avoiding congestion due to "swarming" or broadcasting.
+
+    A special kind of message called a "signal message"
+    (a concept based on Qt's \l {Signals and Slots} mechanism),
+    however, does not have a pre-defined destination. Since its
+    purpose is to be used in a one-to-many context, signal messages
+    are designed to work over an "opt-in" mechanism.
+
+    The Qt D-Bus module fully encapsulates the low-level concept of
+    messages into a simpler, object-oriented approach familiar to Qt
+    developers. In most cases, the developer need not worry about
+    sending or receiving messages.
+
+    \section2 Service Names
+
+    When communicating over a bus, applications obtain what is
+    called a "service name": it is how that application chooses to be
+    known by other applications on the same bus. The service names
+    are brokered by the D-Bus bus daemon and are used to
+    route messages from one application to another. An analogous
+    concept to service names are IP addresses and hostnames: a
+    computer normally has one IP address and may have one or more
+    hostnames associated with it, according to the services that it
+    provides to the network.
+
+    On the other hand, if a bus is not used, service names are also
+    not used. If we compare this to a computer network again, this
+    would equate to a point-to-point network: since the peer is
+    known, there is no need to use hostnames to find it or its IP
+    address.
+
+    The format of a D-Bus service name is in fact very similar to a
+    host name: it is a dot-separated sequence of letters and
+    digits. The common practice is even to name your service name
+    according to the domain name of the organization that defined
+    that service.
+
+    For example, the D-Bus service is defined by
+    \tt{freedesktop.org} and can be found on the bus under the
+    service name:
+
+    \snippet code/doc_src_introtodbus.qdoc 0
+
+    \section2 Object Paths
+
+    Like network hosts, applications provide specific services to
+    other applications by exporting objects. Those objects are
+    hierarchically organized, much like the parent-child
+    relationship that classes derived from QObject possess. One
+    difference, however, is that there is the concept of "root
+    object", which all objects have as the ultimate parent.
+
+    If we continue our analogy with Web services, object paths
+    equate to the path part of a URL:
+
+    \image qurl-ftppath.png
+
+    Like them, object paths in D-Bus are formed resembling path
+    names on the filesystem: they are slash-separated labels, each
+    consisting of letters, digits and the underscore character
+    ("\_"). They must always start with a slash and must not end with
+    one.
+
+    \section2 Interfaces
+
+    Interfaces are similar to C++ abstract classes and Java's
+    \c interface keyword and declare the "contract" that is
+    established between caller and callee. That is, they establish
+    the names of the methods, signals, and properties that are
+    available as well as the behavior that is expected from either
+    side when communication is established.
+
+    Qt uses a very similar mechanism in its \l {How to Create Qt
+    Plugins}{Plugin system}: Base classes in C++ are associated
+    with a unique identifier by way of the Q_DECLARE_INTERFACE()
+    macro.
+
+    D-Bus interface names are, in fact, named in a manner similar to
+    what is suggested by the Qt Plugin System: an identifier usually
+    constructed from the domain name of the entity that defined that
+    interface.
+
+    \section2 Cheat Sheet
+
+    To facilitate remembering of the naming formats and their
+    purposes, the following table can be used:
+
+    \table 90%
+    \header \li D-Bus Concept  \li Analogy            \li Name format
+    \row    \li Service name   \li Network hostnames  \li Dot-separated
+                                                       ("looks like a hostname")
+    \row    \li Object path    \li URL path component \li Slash-separated
+                                                       ("looks like a path")
+    \row    \li Interface      \li Plugin identifier  \li Dot-separated
+    \endtable
+
+    \section1 Debugging
+
+    When developing applications that use D-Bus, it is sometimes useful to be able
+    to see information about the messages that are sent and received across the
+    bus by each application.
+
+    This feature can be enabled on a per-application basis by setting the
+    \c QDBUS_DEBUG environment variable before running each application.
+    For example, we can enable debugging only for the car in the
+    \l{D-Bus Remote Controlled Car Example} by running the controller and the
+    car in the following way:
+
+    \snippet code/doc_src_introtodbus.qdoc QDBUS_DEBUG
+
+    Information about the messages will be written to the console the application
+    was launched from.
+
+*/