From 59762d2b675059d0ea9afcdf53a1437a8f655c44 Mon Sep 17 00:00:00 2001 From: Nicholas Bennett Date: Tue, 23 Nov 2021 14:58:08 +0200 Subject: Docs: 6.2 Release review Removed notes related to minor Qt5 changes. Spelling and grammar correction. Utilized notes and warnings formatting in places for clarity. Updated the name of the online qdocconf file. Used grouping to create the important topics list. Removed qt 5 to qt 5 migration guides from important topics. Task-number: QTBUG-97120 Pick-to: 6.2 Change-Id: Ide5354e987c5175a08030cf32d78b38bae68e53e Reviewed-by: Robert Griebl --- doc/configuration.qdoc | 18 ++++++------- doc/container.qdoc | 15 ++++++----- doc/controller.qdoc | 3 +-- doc/debugging.qdoc | 3 +++ doc/elements-apps.qdoc | 4 ++- doc/elements-common.qdoc | 2 ++ doc/elements-systemui.qdoc | 6 +++-- doc/index.qdoc | 18 ++----------- doc/installation.qdoc | 26 ++++++++++--------- doc/installer.qdoc | 10 +++++--- doc/intents.qdoc | 24 ++++++++++++------ doc/introduction.qdoc | 9 ++++--- doc/manifest.qdoc | 3 +++ doc/migration-guide-6.2.qdoc | 5 +++- doc/online/applicationmanager.qdocconf | 26 ------------------- doc/online/qtapplicationmanager.qdocconf | 26 +++++++++++++++++++ doc/qmlmodule.qdoc | 3 +++ doc/resources.qdoc | 37 +++++++++++++++------------ doc/singlevsmultiprocess.qdoc | 33 +++++++++++++----------- doc/systemui.qdoc | 19 ++++++++------ doc/troubleshooting.qdoc | 43 ++++++++++++++++---------------- doc/write-applications.qdoc | 11 +++++--- doc/yaml.qdoc | 1 + 23 files changed, 192 insertions(+), 153 deletions(-) delete mode 100644 doc/online/applicationmanager.qdocconf create mode 100644 doc/online/qtapplicationmanager.qdocconf (limited to 'doc') diff --git a/doc/configuration.qdoc b/doc/configuration.qdoc index 841dd45d..aa19459b 100644 --- a/doc/configuration.qdoc +++ b/doc/configuration.qdoc @@ -30,11 +30,13 @@ /*! \page configuration.html +\ingroup qtappman +\ingroup qtappman-highlights \title Configuration - +\brief Configure the application manager through configuration (config) files and the command line. \section1 Main Configuration -You can configure the application manager through config files and the command line. To display the +You can configure the application manager through configuration (config) files and the command line. To display the currently supported command line options, run \c{appman --help}. Some of these options can also be set via config files that are referenced on the command line with the \c{--config-file } option. @@ -75,10 +77,10 @@ or across multiple config files, the final value is resolved based on these rule on the command line. Values are overridden by config files, as they are loaded. \li Options that are specified directly via the command line always override values in any config file. - \li There is one exception: options that expect a list of values, such as \c -I or - \c ui/importPaths. In this case, all values, regardless of where they are specified, are - merged into one single, final list. \endlist +\note There is one exception: options that expect a list of values, such as \c -I or +\c ui/importPaths. In this case, all values, regardless of where they are specified, are +merged into one single, final list. \table 100% \header @@ -109,7 +111,7 @@ or across multiple config files, the final value is resolved based on these rule file, for example, to split the configuration cleanly, into a device specific and a UI specific part. All the config files' content are merged in the order in which they appear on the command line: keys that didn't appear in an earlier config value are - taken as is; duplicate keys are merged according to the following algorithm: + taken as is; duplicate keys are merged according to the following rules: \list 1 \li Scalar values overwrite earlier config values. \li Lists are appended to the content from earlier lists. @@ -182,7 +184,7 @@ or across multiple config files, the final value is resolved based on these rule \li \b --dbus \li string \li Registers the ApplicationManager, ApplicationInstaller, NotificationManager, and - WindowManager on the specified D-Bus: can be a full D-Bus bus specification string, + WindowManager on the specified D-Bus. This can be a full D-Bus bus specification string, \c session, \c system, \c auto (default), or \c none (for no registration at all). Use the \c auto keyword on the desktop or during development only. This keyword implies @@ -195,8 +197,6 @@ or across multiple config files, the final value is resolved based on these rule keeping the NotificationManager on the session bus. See the more advanced config-file option\c dbus below. - \note As of Qt 5.13, the new \c auto keyword replaces the old \c --start-session-dbus - flag. \row \li [\c dbus] \li map diff --git a/doc/container.qdoc b/doc/container.qdoc index 4392639d..1135194f 100644 --- a/doc/container.qdoc +++ b/doc/container.qdoc @@ -31,6 +31,9 @@ \page containers.html \title Containers +\ingroup qtappman +\ingroup qtappman-highlights +\brief Describes an execution environment for an executable. In the application manager context, a \b container describes an execution environment for an executable: either an application's binary or its runtime binary, in multi-process mode. The @@ -97,7 +100,7 @@ in multi-process mode: devices. For GPUs that follow Linux standards, such as Intel, make sure to have \c{/dev/dri/*} available within the container. \li You have to implement PID mapping in your plugin; unless your container solution shares its - PID namespace with the rest of the ssytem. This is necessary if you want to make use of the + PID namespace with the rest of the system. This is necessary if you want to make use of the application manager's security features. Each connection coming into the application manager via the Wayland or D-Bus Unix local sockets is queried for the PID of the application that requests the connection. The application manager verifies these PIDs against the PIDs of all @@ -165,8 +168,8 @@ plugins: container: [ "/full/path/to/softwarecontainers.so", "/another/plugin.so" ] \endcode -Note that the application manager does \b not load plugins automatically if they are placed -in a specific directory, since container plugins control the central security mechanism for +\note The application manager does \b not load plugins automatically if they are placed +in a specific directory. This is because container plugins control the central security mechanism for separating applications. \target container-integration @@ -195,8 +198,8 @@ The \c process container accepts the following configuration settings: \li \c controlGroups \li object \li A two-stage mapping object to allow for more readable code when dealing with \c cgroups - from the System UI via Container::controlGroup. The top-level keys are readable group names - that are used to interface with Container::controlGroup. The values themselves are maps + from the System UI via Container::controlGroup. The top-level \c keys are readable group names + that are used to interface with Container::controlGroup. The values themselves are \c maps between multiple low-level \c cgroup sub-system names and the actual \c cgroup names within those sub-systems, such as: @@ -232,7 +235,7 @@ control which container integration is used: preserve the order of the mappings. Each key is interpreted as a standard Unix wildcard expression that is matched against the application ID. The first match stops the algorithm and the mapping's value is used as the container integration ID. If no matches are found, - the resulting containter integration ID is an empty string. + the resulting container integration ID is an empty string. \badcode containers: diff --git a/doc/controller.qdoc b/doc/controller.qdoc index 20b47f3f..602e00df 100644 --- a/doc/controller.qdoc +++ b/doc/controller.qdoc @@ -30,8 +30,7 @@ /*! \page appman-controller.html \title Controller -\brief A command-line utility to trigger the installation of a specified package on the - target device. +\brief A command-line utility to trigger the installation of a specified package on a target device. \ingroup qtappman-tools The \c{appman-controller} is a command-line utility that can be used by the developer, or diff --git a/doc/debugging.qdoc b/doc/debugging.qdoc index 271b2fb3..56eac81b 100644 --- a/doc/debugging.qdoc +++ b/doc/debugging.qdoc @@ -30,7 +30,10 @@ /*! \page debugging.html +\ingroup qtappman +\ingroup qtappman-highlights \title Logging and Debugging +\brief The application manager installs its own message handler to format logging output neatly. \section1 Logging diff --git a/doc/elements-apps.qdoc b/doc/elements-apps.qdoc index 05f7bd0a..0c663f29 100644 --- a/doc/elements-apps.qdoc +++ b/doc/elements-apps.qdoc @@ -31,7 +31,9 @@ \page qml-apps.html \title QtApplicationManager.Application QML module -\brief Qt Application Manager module to use in applications. +\ingroup qtappman +\ingroup qtappman-highlights +\brief Contains the components and types to use in an application. The QtApplicationManager.Application QML module contains the components and types to use in an application. diff --git a/doc/elements-common.qdoc b/doc/elements-common.qdoc index d62e199d..c951f44e 100644 --- a/doc/elements-common.qdoc +++ b/doc/elements-common.qdoc @@ -31,6 +31,8 @@ \page qml-common.html \title QtApplicationManager QML module +\ingroup qtappman +\ingroup qtappman-highlights \brief Qt Application Manager module common to both System UI and applications. The QtApplicationManager QML module contains the components and types available to both System UI diff --git a/doc/elements-systemui.qdoc b/doc/elements-systemui.qdoc index 79ba7fe7..47344e41 100644 --- a/doc/elements-systemui.qdoc +++ b/doc/elements-systemui.qdoc @@ -31,7 +31,9 @@ \page qml-sysui.html \title QtApplicationManager.SystemUI QML module -\brief Qt Application Manager module for use in a System UI +\ingroup qtappman +\ingroup qtappman-highlights +\brief Qt Application Manager module for use in a System UI. The QtApplicationManager.SystemUI QML module contains the components and types to use in a System UI. @@ -41,7 +43,7 @@ Singleton QML types need not be declared, they are referenced by their type name Instantiable QML types are declared with their name followed by curly braces. These declarations may be nested, creating parent-child relationships between the items. -Non-Instantiable QML types are return values provided to the System UI code, that allow the user +QML types that cannot be instantiated are return values provided to the System UI code, that allow the user direct access to data that would otherwise only be available (partially) through the singletons' item models. diff --git a/doc/index.qdoc b/doc/index.qdoc index a6d70c83..c08e85e1 100644 --- a/doc/index.qdoc +++ b/doc/index.qdoc @@ -42,22 +42,8 @@ compositing window manager using the APIs that are exported from the C++ side. For a high-level overview, see \l{The Qt Application Manager}{Introduction to the Qt Application Manager}. \section1 Important topics -\list - \li \l{Installation} - \li \l{Configuration} - \li \l{Troubleshoot} - \li \l{The System UI} - \li \l{Write Applications} - \li \l{Application Installer} - \li \l{Logging and Debugging} - \li \l{Containers} - \li \l{Intents} - \li \l{Use Qt Resources} - \li \l{Single-Process vs. Multi-Process Mode} - \li \l{Migrating code from 5.11 to 5.12} - \li \l{Migrating code from 5.13 to 5.14} - \li \l{Migrating code from 5.15 to 6.2} -\endlist + +\annotatedlist qtappman-highlights \section1 Tools \annotatedlist qtappman-tools diff --git a/doc/installation.qdoc b/doc/installation.qdoc index 871facd4..1adc6985 100644 --- a/doc/installation.qdoc +++ b/doc/installation.qdoc @@ -31,7 +31,9 @@ \page installation.html \title Installation - +\brief Discusses Qt Application Manager installation considerations, such as; support, prerequisites, code coverage data and system setup. +\ingroup qtappman +\ingroup qtappman-highlights \section1 Supported Platforms The application manager is tested regularly on multiple platforms. @@ -63,7 +65,6 @@ To build the application manager with all its features, the following components \list \li \b Qt 6.2.0 or higher. - \li \b openssl \e{- Linux only and only if you need the installer functionality}. Qt needs to be built with openssl support. The required minimum version is defined by Qt. \li \b libyaml 1.6 or higher. @@ -76,15 +77,16 @@ apt-get install libyaml-dev libarchive-dev libssl-dev \endcode \note On platforms without \c pkg-config (for example, Windows or macOS) as well as on platforms -that lack one of the dependencies, the bundled versions of these libraries from the \c src/3rdparty +that lack one of the prerequisites, the bundled versions of these libraries from the \c src/3rdparty folder are automatically used instead. Make sure you are aware of the licensing implications, -since these bundled 3rdparty libs will be linked in as static libraries. This option is not meant -for production, but for development and testing environments only. +since these bundled 3rdparty libs will be linked in as static libraries. + +\warning This option is not meant for production, but for development and testing environments only. \section1 Multi-process vs. Single-process By default, the application manager always tries to build in multi-process mode, but falls back -to single-process mode, if certain dependencies are not available, such as: +to single-process mode, if certain multi-process mode dependencies are not available, such as: \list \li You are building for \b Linux. @@ -98,7 +100,7 @@ You can force the build mode via the respective \c --force-multi-process and \target build \section1 Build -The application manager uses \c cmake for its build system. The basic installation steps are: +The application manager uses \c CMake for its build system. The basic installation steps are: \code mkdir @@ -116,17 +118,17 @@ mkdir && cmake --install . \endcode -There are various options that can be given to \c cmake to tailor the build to suit your needs. +There are various options that can be given to \c CMake to tailor the build to suit your needs. -With Qt's new cmake based build system, there are three ways to set configure options for Qt +With Qt's new CMake based build system, there are three ways to set configure options for Qt modules: \list 1 \li You can call \c cmake from a shell and specify the options as \c -DINPUT_