From 6028ae1903fda40ffa85cb7d8c32b95f096dd1d1 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 26 Jul 2023 08:21:34 +0200 Subject: [PATCH 01/43] [QDoc] Switch breadcrumb index from Wiki to Pages --- doc/qdoc/common.qdocconf | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/qdoc/common.qdocconf b/doc/qdoc/common.qdocconf index 550a70e04..c590d9797 100644 --- a/doc/qdoc/common.qdocconf +++ b/doc/qdoc/common.qdocconf @@ -28,7 +28,7 @@ HTML.footer = "
" \ "License.

" \ "

" -navigation.homepage = https://github.com/sailfishos-patches/patchmanager/wiki +navigation.homepage = https://sailfishos-patches.github.io/patchmanager navigation.hometitle = Patchmanager navigation.landingpage = Patchmanager Documentation From 82e0638782a2937d2b153bce62c65fbe058c43a9 Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 25 Jul 2023 14:37:40 +0200 Subject: [PATCH 02/43] [Doc] Begin documenting Patch Metadata properties --- src/index.qdoc | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/index.qdoc b/src/index.qdoc index 65d1d60ad..d920a16f7 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -347,3 +347,17 @@ \section2 \c{/var/lib/environment/patchmanager-dialog/*.conf} \section2 \c{/var/lib/environment/patchmanager/10-dbus.conf} */ + + /****** Patch Metadata Documentation page *******/ +/*! + \title Patch Metadata + \previouspage {Patchmanager Configuration Files} + + \page patchmeta.html overview + + + \target metadata + + JSON file. +*/ + From 316ab7b2093aca9c72710be3c4313efd5e490e4f Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 25 Jul 2023 14:38:11 +0200 Subject: [PATCH 03/43] [Doc] Improve QML Plugin documentation --- src/qml/PatchObject.cpp | 55 ++++++++++++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 15 deletions(-) diff --git a/src/qml/PatchObject.cpp b/src/qml/PatchObject.cpp index 4c86b84e3..5c4b5d19c 100644 --- a/src/qml/PatchObject.cpp +++ b/src/qml/PatchObject.cpp @@ -56,6 +56,33 @@ /*! \qmlsignal PatchObject::busyChanged(); \internal */ +/*! \qmlproperty string PatchObject::details::category + Corresponds to the field of the same name in the patch metadata. See \l{metadata} +*/ +/*! \qmlproperty string PatchObject::details::display_name + Corresponds to the field of the same name in the patch metadata. See \l{metadata} +*/ +/*! \qmlproperty string PatchObject::details::name + Corresponds to the field of the same name in the patch metadata. See \l{metadata} +*/ +/*! \qmlproperty string PatchObject::details::patch + Corresponds to the field of the same name in the patch metadata. See \l{metadata} +*/ +/*! \qmlproperty string PatchObject::details::section + Corresponds to the field of the same name in the patch metadata. See \l{metadata} +*/ +/*! \qmlproperty bool PatchObject::details::isNewPatch + \c true if this patches metadata is in current format, \c false if it's legacy data. See \l{metadata} +*/ +/*! \qmlproperty bool PatchObject::details::patched + \c true if this patch is currently applied, \c false otherwise. +*/ +/*! \qmlproperty string PatchObject::details::ok + \c true if the last apply process succeeded, \c false otherwise. +*/ +/*! \qmlproperty string PatchObject::details::log + Holds the output from the latest patching process. +*/ PatchObject::PatchObject(const QVariantMap &data, QObject *parent) : QObject(parent) @@ -78,6 +105,8 @@ PatchObject::PatchObject(const QVariantMap &data, QObject *parent) /*! \class PatchObject \inmodule org.SfietKonstantin.patchmanager \brief An element to be used as content of an \l {PatchManagerModel} + + Upon construction, the \c data parameter is mapped to PatchObject::detail */ PatchObject::~PatchObject() { @@ -85,14 +114,11 @@ PatchObject::~PatchObject() emit toBeDestroyed(this); } -/*! \qmlproperty var PatchObject::details - - Holds the Patch metadata. -*/ /*! \property PatchObject::details - \inheaderfile PatchObject.hpp - \sa {https://doc.qt.io/qt-5/qqmlpropertymap.html}{QQmlPropertyMap} + Maps the internal property names and values to QML properties. + + See \l {https://doc.qt.io/qt-5/qqmlpropertymap.html}{QQmlPropertyMap} */ QQmlPropertyMap *PatchObject::details() { @@ -104,7 +130,7 @@ QQmlPropertyMap *PatchObject::details() \c true when an internal operation is in progress. */ /*! \property PatchObject::busy - \inheaderfile PatchObject.hpp + \c true when an internal operation is in progress. */ /*! Returns \c true when an internal operation is in progress. */ @@ -116,7 +142,8 @@ bool PatchObject::busy() const /*! Fills the PatchObject's properties from \a data. - \note If there is a "display_name" field in \a data, it is used. Otherwise, patch name is used. + If there is a \c display_name field in \a data, and \a data is treated as regular patch metadata (\c isNewPatch is set to \c true). + Otherwise, the field \c name is used for display name, and the data is treated as legacy metadata. */ void PatchObject::setData(const QVariantMap &data) { @@ -133,10 +160,9 @@ void PatchObject::setData(const QVariantMap &data) } /*! - Calls PatchManager::applyPatch with the patch name. If \a callback is callable, calls it afterwards. - Does nothing if the \c "patched" property is \c true. + Calls PatchManager::applyPatch with the patch name. Calls \a callback afterwards (if callable). - \sa PatchManager::applyPatch + \note Does nothing if the \c patched property is \c true. */ void PatchObject::apply(QJSValue callback) { @@ -176,10 +202,9 @@ void PatchObject::apply(QJSValue callback) } /*! - Calls PatchManager::unapplyPatch() with the patch name. If \a callback is callable, calls it afterwards. - Does nothing if the \c "patched" property is \c false. + Calls PatchManager::unapplyPatch with the patch name. Calls \a callback afterwards (if callable). - \sa PatchManager::unapplyPatch + \note Does nothing if the \c patched property is \c false. */ void PatchObject::unapply(QJSValue callback) { @@ -240,7 +265,7 @@ void PatchObject::uninstall() }); } -/*! Calls PatchManager::resetState. */ +/*! Calls PatchManager::resetState with the patch name. */ void PatchObject::resetState() { qDebug() << Q_FUNC_INFO; From bee700af9a80314f196f7216e06abd309e653b28 Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 25 Jul 2023 16:17:41 +0200 Subject: [PATCH 04/43] [Doc] Expand Documentation to Dev and User documentation --- doc/qdoc/general.qdocconf | 4 +- src/index.qdoc | 122 +++++++--------------- src/patchdev.qdoc | 214 ++++++++++++++++++++++++++++++++++++++ src/user.qdoc | 54 ++++++++++ 4 files changed, 310 insertions(+), 84 deletions(-) create mode 100644 src/patchdev.qdoc create mode 100644 src/user.qdoc diff --git a/doc/qdoc/general.qdocconf b/doc/qdoc/general.qdocconf index 999de6bd1..62b895641 100644 --- a/doc/qdoc/general.qdocconf +++ b/doc/qdoc/general.qdocconf @@ -4,7 +4,9 @@ description = Patchmanager include (common.qdocconf) ## Sources -sources += ../../src/index.qdoc +sources += ../../src/index.qdoc \ + ../../src/patchdev.qdoc \ + ../../src/user.qdoc # for quoting exampledirs += ../../src/bin/patchmanager-daemon diff --git a/src/index.qdoc b/src/index.qdoc index d920a16f7..bcf1234e4 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -4,9 +4,24 @@ \title Patchmanager Documentation - For User documentation, see \l {https://github.com/sailfishos-patches/patchmanager/#information-for-users}{User Documentation}. + For User documentation, see: - For Patch Developer documentation, see \l {https://github.com/sailfishos-patches/patchmanager/#information-for-patch-developers}{Developer Documentation}. + \list + \li \l {Patchmanager for SailfishOS} + \endlist + + For Patch Developer documentation, see: + \list + \li \l{Patch Developer Documentation} + \endlist + + \section1 Translations + + If you want to translate ("localise") Patchmanager to a language you know + well or enhance an existing translation, please read Patchmanager's + corresponding Wiki page + + \l{https://github.com/sailfishos-patches/patchmanager/wiki/Translations-(%22i18n%22,-%22l10n%22)}{Translations-("i18n", "l10n")}. \section1 Internals @@ -54,14 +69,12 @@ When a user activates a patch via the App, a signal is sent to the daemon. - The daemon will then: - - For each file the patch manipulates, a copy of the original file is put into - a cache dir in \c /tmp, and the changes are applied there instead of on the - original file. + When activated, for each file the patch manipulates, a copy of the original + file is put into a cache directory in \c /tmp, and the changes are applied there + instead of on the original file. If there are paths or files involved in the patch which do not exist yet - in the filesystem, they will be created in the cache dir, and a symlink + in the filesystem, they will be created in the cache directory, and a symbolic link pointing to them is placed in the original filesystem. \section2 2. A patched application is launched. @@ -73,81 +86,34 @@ \list \li Intercepts calls to \l {https://www.man7.org/linux/man-pages/man2/open.2.html}{\c{open()} (or \c{open64()})}, \li analyzes which files the call was meant to open - \li asks the Patchmanager daemon (via socket) whether it knows of a patched version. + \li asks the Patchmanager daemon (via UNIX Socket) whether it knows of a patched version. \endlist - If yes, the daemon will return a path to its cachedir, and the library + If yes, the daemon will return a path to its cache directory, and the library redirects the call to that file instead of the original. Otherwise, the \c{open()} is executed on the original file. Certain paths are blacklisted for these operations to reduce the risk of critical services, or PM itself, choking on these redirections. - \note After activating a Patch , the daemon may also inform the UI that some + \warning After activating a Patch , the daemon may also inform the UI that some apps or services need restart. The UI client is expected to issue the command to restart these soon. - As long as the corresponding preocesses are not restarted, the effect of the + As long as the corresponding processes are not restarted, the effect of the applied patch will not show, or may only show partially, depending on the "patch history" of the respective process. - \section1 Patch Installation - There are three ways a Patch can end up on the system: + \note Due to the nature of the interaction between the daemon and the + library, applications which are executed ... \list - \li Web Catalog - \li RPM package - \li TAR package - \li manual installation + \li without respecting \c /etc/ld.so.preload (e.g. Android binaries in the base system) + \li before the daemon has started and initialised \endlist - \section2 Patch folder structure - - All Patches managed by PM are installed under \c /usr/share/patchmanager/patches/NAME, - where NAME is a directory having a unique name. - - That directory must contain at least two files: a \c JSON file called - \c patch.json containing metadata, and a \c diff file called \c{unified_diff.patch}. - - It may optionally also contain: - \list - \li Qt translation (.qm) files - \li icon files in PNG format - \li a QML file called \c main.qml (whose root element is a Sailfish Silica \c{Page}). - \li other QML-compatible files which are referenced/loaded from \c main.qml - \endlist - - \note the directory NAME is usually and by convention the same as the patch - metadata field \c name, but that is not a requirement. NAME should be - reasonably unique though, to avoid name clashes with Patches from others. - - \section2 Web Catalog - - Installation via the Patchmanager Web Catalog is the most common and recomended way of installing a patch. - This is done through the Patchmanager UI, by selecting \uicontrol install on the \l {WebPatchPage}{Patch Page}. - - PM will download metadata and a tarball from the Web Catalog, extract the - tarball into the patch storage location, and generate the necessary JSON file - from the metadata. - - \section2 RPM package - - Patches may be distributed as RPM files, which assure the placement of files - according to the structure explained above. RPM also provides advanced - features like dependencies and scriptlets which may be necessary for correct - operation or installation of a Patch. - - \section2 TAR package - - Patch developers may sometimes distribute Patches in \c tar format. Usually - they also contain the necessary files, but the contents of the tarball may - differ, and recipients of them must assure the layout given above is set up - correctly. - - \section2 manual installation - - Patch developers or users may want to quickly place a Patch under PM's - supervision without going through the hassle of packaging and installing. - This can be done easily, as long as the formats given above are followed. + ... will obviously not see patched file contents. Patch authors are advised + to use other methods (e.g. proper RPM packages, or e.g. systemd services to + manipulate files in these cases, and refrain from using Patches to do that.) \e{to be continued...} @@ -262,9 +228,12 @@ See the output of \c{patchmanager --help} and PatchManagerObject::process() for more information. - There is also a shell script called \c patchmanager-tool, wrapping the capabilities of \c patchmanager to generate more useful functions. + There is also a shell script called \c patchmanager-tool, wrapping the + capabilities of \c patchmanager to generate more useful functions. - \note At the time this was written, \c patchmanager-tool is not yet distributed with the default packages. You can find it in the source repository though, under \c src/tools/. + \note At the time this was written, \c patchmanager-tool is not yet + distributed with the default packages. You can find it in the source + repository though, under \c src/tools/. \section1 Logging and Debugging @@ -327,10 +296,10 @@ \li order \li list of strings, comma-separated \li empty - \li The order of the list of patches, bith in the UI as well as the order they will be applied/activated. + \li The order of the list of patches, both in the UI as well as the order they will be applied/activated. \row \li patchDevelMode - \li Boolesn + \li Boolean \li \c false \li \row @@ -348,16 +317,3 @@ \section2 \c{/var/lib/environment/patchmanager/10-dbus.conf} */ - /****** Patch Metadata Documentation page *******/ -/*! - \title Patch Metadata - \previouspage {Patchmanager Configuration Files} - - \page patchmeta.html overview - - - \target metadata - - JSON file. -*/ - diff --git a/src/patchdev.qdoc b/src/patchdev.qdoc new file mode 100644 index 000000000..e3d393a4d --- /dev/null +++ b/src/patchdev.qdoc @@ -0,0 +1,214 @@ +/*! + + \page patchdev.html overview + \indexpage Patchmanager Documentation + + \title Patch Developer Documentation + + \section1 Patch Installation + + There are three ways a Patch can end up on the system: + + \list + \li Web Catalog + \li RPM package + \li TAR package + \li manual installation + \endlist + + \section2 Web Catalog + + Installation via the Patchmanager Web Catalog is the most common and + recommended way of installing a patch. This is done through the Patchmanager + UI, by selecting \uicontrol install on the \l {WebPatchPage}{Patch Page}. + + PM will download metadata and a tarball from the Web Catalog, extract the + tarball into the patch storage location, and generate the necessary JSON file + from the metadata. + + \sa {Patchmanager Web Catalog}{Web Catalog} + + \section2 RPM package + + Patches may be distributed as RPM files, which assure the placement of files + according to the structure explained above. RPM also provides advanced + features like dependencies and scriptlets which may be necessary for correct + operation or installation of a Patch. + + \section2 TAR package + + Patch developers may sometimes distribute Patches in \c tar format. Usually + they also contain the necessary files, but the contents of the tarball may + differ, and recipients of them must assure the layout given above is set up + correctly. + + \section2 manual installation + + Patch developers or users may want to quickly place a Patch under PM's + supervision without going through the hassle of packaging and installing. + This can be done easily, as long as the formats given above are followed. + + \section1 Patch format + + \section2 Patch folder structure + + All Patches managed by PM are installed under \c /usr/share/patchmanager/patches/$NAME, + where \c $NAME is a directory having a unique name. + + That directory must contain at least two files: a \c JSON file called + \c patch.json containing metadata, and a \c diff file called \c{unified_diff.patch}. + + For information about \c patch.json metadata, see \l{metadata}, and + \l{https://github.com/sailfishos-patches/patchmanager/blob/master/README.md#the-json-metadata-file}{README} + + \c{unified_diff.patch} must be in unified diff format, and must apply against + the filesystem root when using patch with the options \c{ -d / -p 1 --no-backup-if-mismatch } + + It may optionally also contain: + \list + \li Qt translation (.qm) files + \li icon files in PNG format + \li a QML file called \c main.qml (whose root element is a Sailfish Silica \c{Page}). + \li other QML-compatible files which are referenced/loaded from \c main.qml + \endlist + + \note the directory \c $NAME is usually and by convention the same as the + patch metadata field \c name, but that is not a requirement. \c $NAME should + be reasonably unique though, to avoid name clashes with Patches from others. + + \section2 Metadata + + See \l {Patch Metadata} +*/ + +/****** Patch Metadata Documentation page *******/ + +/*! + \title Patch Metadata + + \page patchmeta.html overview + \indexpage Patchmanager Documentation + \previouspage Patch Developer Documentation + + \target metadata + + A JSON file. + + The metadata file contains information about a Patch. It is a simple JSON file, that must be named \c patch.json. + + \warning This files is automatically generated and added to your Patch + distribution if you choose to upload your Patch to the Web Catalog. + You should NOT include one with your Patch if you do that. + + If you distribute your Patch some other way, e.g. as an RPM package, you must + provide a valid \c patch.json file. + + You may use either the \l{newjson}{modern format} or the much simpler \l{legacyjson}{legacy format}. + Both are supported, but the modern one provides more useful features and is recommended. + + \section2 Example patch.json + \target newjson + + This describes the preferred format of \c patch.json. + + \badcode + { + "author": "Jim Example", + "name": "the-internal-patch-name", + "display_name": "Human-facing Patch Name", + "version": "1.0.0", + "category": "calendar", + "description": "This is a long description of what this Patch does.\nIt will be displayed in the Patch page.", + "discussion": "https://example.org/forum/thead?id=9999", + "sources": "https://git.example.org/patch.git", + "donations": "https://example.org/donate", + "compatible": [ "3.2.1.20", "3.3.0.14", "3.3.0.16" ], + "id": NNN, + "last_updated": "2020-04-28T06:56:21.931", + } + \endcode + + \section2 Description of options: + + Required / Recommended: + + \list + \li name: An internal name for the Patch. As this is used as a directory name, it should only contain alphanumeric characters, underscores and hyphens. Notably NO spaces, dollar signs or other special characters should be used! + \li display_name: The name of the Patch, which will be shown on the patch list. + \li version: A version string. It MUST be in the format X.Y.Z + \li author: The name of the principal Patch author or maintainer. Either use your real name, as displayed on Github or Twitter, or your usual nickname. + \li compatible: A list of SailfishOS releases the Patch works on. Versions MUST be given in full with all four fields populated, e.g. "3.3.0.16" (using just "3.3" is invalid). + \endlist + + Optional: + \list + \li description: Explanation of what the Patch does. + \li category: This is used to structure the list of Patches in categories, but also certain categories will cause Patchmanager to restart affected system services or applications. For example, Patches in the category "homescreen" will prompt the user to restart Lipstick after their activation. + \li discussion, sources, donations: Optional links to websites. + \li last_updated": An ISO date string, the Web Catalog sets this. It is used for sorting and update detection. + \endlist + + Reserved: + \list + \li id: A numeric ID used by Web Catalog. This MUST NOT be included in Patches which are not distributed via Web Catalog. + \endlist + + \section2 List of supported categories: + \target jsoncats + + \warning Supplying no category, or a category not on this list will cause the + Patch to be shown in the category "other", and no affected applications will + be restarted after the patch is activated. + + \list + \li "homescreen" - will restart Lipstick + \li "silica" - will restart Lipstick + \li "keyboard" - will restart the keyboard service + \endlist + + These will stop or restart the corresponding system applications (e.g. the + jolla-browser) after activating the Patch. + + \list + \li "browser" + \li "calendar" + \li "camera" + \li "clock" + \li "contacts" + \li "email" + \li "gallery" + \li "media" + \li "messages" + \li "phone" + \li "settings" + \endlist + + \section2 Example patch.json in legacy format + \target legacyjson + + This describes the format of the \c patch.json file in the \e legacy format. + While this is still supported in Patchmanager 3, if possible switch to \l{newjson}{the new format} as it supports more useful information. + + \badcode + { + "name": "Example Patch Name", + "description": "This is a long description of what this Patch does.\nIt will be displayed on the Patch page.", + "category": "email", + "infos": { + "maintainer": "username" + }, + } + \endcode + + \section3 Description of options: + + \list + \li name: The "display name" of the patch, which will be shown on the Patch list. + \li description: Explanation of what the Patch does. + \li maintainer: The name of the principal Patch author or maintainer. Either use your real name, as displayed on Github or Twitter, or your usual nickname. + \li category: see \l{jsoncats}{above} + \endlist + + +*/ + diff --git a/src/user.qdoc b/src/user.qdoc new file mode 100644 index 000000000..2c692009a --- /dev/null +++ b/src/user.qdoc @@ -0,0 +1,54 @@ +/*! + + \page user.html overview + \indexpage Patchmanager Documentation + + \title Patchmanager for SailfishOS + + Patchmanager is a tool for transparently modifying installed files by the + patch utility and for managing the special patch files ("Patches") for doing + so. + + Since version 3.0, Patchmanager does not modify original files on mass + storage, it merely alters their content when they are loaded into RAM to be + executed. + + \section1 Launching + + Patchmanager does not install an application icon on the launcher, but + creates a new entry in SailfishOS' Settings app. + + \section1 Installing + + To install a recent Patchmanager the SailfishOS:Chum community repository can + be used, which is easily accessed with the SailfishOS:Chum GUI application, + which in turn can be installed via the + \l{https://openrepos.net/content/olf/sailfishoschum-gui-installer}{SailfishOS:Chum GUI Installer} + + Alternatively Patchmanager can be installed from + \l{https://openrepos.net/user/16848/programs}{its OpenRepos repository} + using Storeman, which can be installed via the + \l{https://openrepos.net/content/olf/storeman-installer}{Storeman Installer}. + + While these two sources can also be used to manually download and install + Patchmanager, you may alternatively obtain Patchmanager RPMs from + \l{https://github.com/sailfishos-patches/patchmanager/releases}{its releases page at GitHub}. + + \note The Patchmanager's OpenRepos repository and GitHub releases page also + offer the final releases of Patchmanager 3.0 for SailfishOS < 3.4.0 and + Patchmanager 2.3.3 for SailfishOS < 2.2.x. + + \section1 Getting Patches + + Modern Patches for Patchmanager 3 are provided via + \l{https://coderus.openrepos.net/pm2/projects/}{the Web Catalog} + while older Patches were provided as + \l{https://openrepos.net/category/patches}{RPMs at OpenRepos} + and some of them are still maintained. + + Mind that many Patches were first released at OpenRepos but later migrated to + the Web Catalog: For these you will find outdated RPMs, hence always search + in the Web Catalog first. + + +*/ From ff0ddde84b26b74ae2282ddd97b7319e72be0b33 Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 25 Jul 2023 17:06:41 +0200 Subject: [PATCH 05/43] [QDoc] update CSS --- doc/qdoc/pm.css | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/qdoc/pm.css b/doc/qdoc/pm.css index b6759043d..abb295ccd 100644 --- a/doc/qdoc/pm.css +++ b/doc/qdoc/pm.css @@ -1,3 +1,7 @@ +body { margin-left: 15vw; margin-right: 15vw; + font-family: "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; +} +code { font-family: ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace; } a:link { color: #8C001A; text-decoration: none; text-align: left; } a.qa-mark:target:before { content: "***"; color: #ff0000; } a:hover { color: #8C0060; text-align: left; } From 807a52580feed9d406afb0aa826be618f7d22322 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 26 Jul 2023 11:01:02 +0200 Subject: [PATCH 06/43] [QDoc] fix up some of the configs --- doc/qdoc/daemon.qdocconf | 4 +++- doc/qdoc/dialog.qdocconf | 2 +- doc/qdoc/general.qdocconf | 2 +- doc/qdoc/plugin.qdocconf | 2 +- doc/qdoc/qmlplugin.qdocconf | 2 +- src/index.qdoc | 5 ++++- 6 files changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/qdoc/daemon.qdocconf b/doc/qdoc/daemon.qdocconf index 4bdf3ab9d..679347186 100644 --- a/doc/qdoc/daemon.qdocconf +++ b/doc/qdoc/daemon.qdocconf @@ -4,7 +4,9 @@ versionsym = version = 2.0 url = https://github.com/sailfishos-patches/patchmanager -include (common.qdocconf) +include(common.qdocconf) + +headerdirs += ../../src/bin/patchmanager-daemon headerdirs += ../../src/bin/patchmanager-daemon headers.fileextensions = "*.h *.hpp" diff --git a/doc/qdoc/dialog.qdocconf b/doc/qdoc/dialog.qdocconf index 7b5a38dea..4ef9025a7 100644 --- a/doc/qdoc/dialog.qdocconf +++ b/doc/qdoc/dialog.qdocconf @@ -4,7 +4,7 @@ versionsym = version = 2.0 url = https://github.com/sailfishos-patches/patchmanager -include (common.qdocconf) +include(common.qdocconf) sourcedirs = ../../src/bin/dialog diff --git a/doc/qdoc/general.qdocconf b/doc/qdoc/general.qdocconf index 62b895641..1bea1dccf 100644 --- a/doc/qdoc/general.qdocconf +++ b/doc/qdoc/general.qdocconf @@ -1,7 +1,7 @@ project = patchmanager description = Patchmanager -include (common.qdocconf) +include(common.qdocconf) ## Sources sources += ../../src/index.qdoc \ diff --git a/doc/qdoc/plugin.qdocconf b/doc/qdoc/plugin.qdocconf index a010ead14..19578429e 100644 --- a/doc/qdoc/plugin.qdocconf +++ b/doc/qdoc/plugin.qdocconf @@ -4,7 +4,7 @@ versionsym = version = 2.0 url = https://github.com/sailfishos-patches/patchmanager -include (common.qdocconf) +include(common.qdocconf) sourcedirs = ../../src/plugin diff --git a/doc/qdoc/qmlplugin.qdocconf b/doc/qdoc/qmlplugin.qdocconf index caf05f9a2..2ea3cb34d 100644 --- a/doc/qdoc/qmlplugin.qdocconf +++ b/doc/qdoc/qmlplugin.qdocconf @@ -15,5 +15,5 @@ sourcedirs = ../../src/qml sources += qmlplugin.qdoc #sources.fileextensions = "*.cpp *.qdoc *.qml" -# get rid of warnings about undoicumented stuff in patchmanager.h +# try to get rid of warnings about undocumented stuff in patchmanager.h Cpp.ignoretokens += Q_PROPERTY diff --git a/src/index.qdoc b/src/index.qdoc index bcf1234e4..08db88f07 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -21,7 +21,7 @@ well or enhance an existing translation, please read Patchmanager's corresponding Wiki page - \l{https://github.com/sailfishos-patches/patchmanager/wiki/Translations-(%22i18n%22,-%22l10n%22)}{Translations-("i18n", "l10n")}. + \l{https://github.com/sailfishos-patches/patchmanager/wiki/Translations-(%22i18n%22,-%22l10n%22)}{Translations ("i18n", "l10n")}. \section1 Internals @@ -314,6 +314,9 @@ \e{to be written...} \section2 \c{/var/lib/environment/patchmanager-dialog/*.conf} + \e{to be written...} + \section2 \c{/var/lib/environment/patchmanager/10-dbus.conf} + \e{to be written...} */ From 42fc1a2560fecb673bad5af7154163f549609911 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 26 Jul 2023 11:06:48 +0200 Subject: [PATCH 07/43] [QDoc] Remove overview specification --- src/bin/dialog/dialog.qdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/bin/dialog/dialog.qdoc b/src/bin/dialog/dialog.qdoc index aebc26cb6..31c5af387 100644 --- a/src/bin/dialog/dialog.qdoc +++ b/src/bin/dialog/dialog.qdoc @@ -1,6 +1,6 @@ /*! \title Patchmanager Documentation: Startup Dialog - \page index.html overview + \page index.html \indexpage Patchmanager Documentation This is a very simple Sailfish OS application that upon start checks the state of the Patchmanager Daemon to see whether it needs to launch a GUI. From 22377790ceadcb2bca25568251ee7dd2a122fefd Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 26 Jul 2023 11:40:05 +0200 Subject: [PATCH 08/43] [Doc] Add externalpages, rework User Docs --- doc/qdoc/daemon.qdocconf | 2 -- doc/qdoc/general.qdocconf | 3 ++- src/externalpages.qdoc | 36 ++++++++++++++++++++++++++++++++++++ src/user.qdoc | 18 +++++++----------- 4 files changed, 45 insertions(+), 14 deletions(-) create mode 100644 src/externalpages.qdoc diff --git a/doc/qdoc/daemon.qdocconf b/doc/qdoc/daemon.qdocconf index 679347186..0ab7e67dc 100644 --- a/doc/qdoc/daemon.qdocconf +++ b/doc/qdoc/daemon.qdocconf @@ -6,8 +6,6 @@ url = https://github.com/sailfishos-patches/patchmanager include(common.qdocconf) -headerdirs += ../../src/bin/patchmanager-daemon - headerdirs += ../../src/bin/patchmanager-daemon headers.fileextensions = "*.h *.hpp" diff --git a/doc/qdoc/general.qdocconf b/doc/qdoc/general.qdocconf index 1bea1dccf..986fded52 100644 --- a/doc/qdoc/general.qdocconf +++ b/doc/qdoc/general.qdocconf @@ -6,7 +6,8 @@ include(common.qdocconf) ## Sources sources += ../../src/index.qdoc \ ../../src/patchdev.qdoc \ - ../../src/user.qdoc + ../../src/user.qdoc \ + ../../src/externalpages.qdoc # for quoting exampledirs += ../../src/bin/patchmanager-daemon diff --git a/src/externalpages.qdoc b/src/externalpages.qdoc new file mode 100644 index 000000000..dc071e3da --- /dev/null +++ b/src/externalpages.qdoc @@ -0,0 +1,36 @@ +/*! + \externalpage https://doc.qt.io/archives/qt-5.6/ + \title Qt 5.6 Documentation +*/ +/*! + \externalpage https://coderus.openrepos.net/pm2/projects/ + \title {Web Catalog Site} +*/ +/*! + \externalpage https://github.com/sailfishos-patches/patchmanager + \title {Patchmanager GitHub Repository} +*/ +/*! + \externalpage https://github.com/sailfishos-patches/patchmanager/blob/master/README.md + \title {Patchmanager README} +*/ +/*! + \externalpage https://openrepos.net/content/olf/sailfishoschum-gui-installer + \title SailfishOS:Chum GUI Installer +*/ +/*! + \externalpage https://openrepos.net/user/16848/programs + \title OpenRepos repository +*/ +/*! + \externalpage https://openrepos.net/content/olf/storeman-installer + \title Storeman Installer +*/ +/*! + \externalpage https://github.com/sailfishos-patches/patchmanager/releases + \title Releases page +*/ +/*! + \externalpage https://openrepos.net/category/patches + \title Patch RPMs at OpenRepos +*/ diff --git a/src/user.qdoc b/src/user.qdoc index 2c692009a..394a27d73 100644 --- a/src/user.qdoc +++ b/src/user.qdoc @@ -22,17 +22,14 @@ To install a recent Patchmanager the SailfishOS:Chum community repository can be used, which is easily accessed with the SailfishOS:Chum GUI application, - which in turn can be installed via the - \l{https://openrepos.net/content/olf/sailfishoschum-gui-installer}{SailfishOS:Chum GUI Installer} + which in turn can be installed via the \l{SailfishOS:Chum GUI Installer} - Alternatively Patchmanager can be installed from - \l{https://openrepos.net/user/16848/programs}{its OpenRepos repository} - using Storeman, which can be installed via the - \l{https://openrepos.net/content/olf/storeman-installer}{Storeman Installer}. + Alternatively Patchmanager can be installed from its \l{OpenRepos repository} + using Storeman, which can be installed via the \l{Storeman Installer}. While these two sources can also be used to manually download and install - Patchmanager, you may alternatively obtain Patchmanager RPMs from - \l{https://github.com/sailfishos-patches/patchmanager/releases}{its releases page at GitHub}. + Patchmanager, you may alternatively obtain Patchmanager RPMs from its + \l{Releases page} at GitHub. \note The Patchmanager's OpenRepos repository and GitHub releases page also offer the final releases of Patchmanager 3.0 for SailfishOS < 3.4.0 and @@ -40,10 +37,9 @@ \section1 Getting Patches - Modern Patches for Patchmanager 3 are provided via - \l{https://coderus.openrepos.net/pm2/projects/}{the Web Catalog} + Modern Patches for Patchmanager 3 are provided via the \l{Web Catalog Site} while older Patches were provided as - \l{https://openrepos.net/category/patches}{RPMs at OpenRepos} + \l{Patch RPMs at OpenRepos} and some of them are still maintained. Mind that many Patches were first released at OpenRepos but later migrated to From 51afea7b933243de457fa6a5d86528fab867594a Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 26 Jul 2023 12:14:11 +0200 Subject: [PATCH 09/43] [Doc] Daemon: improve docs --- src/bin/patchmanager-daemon/patchmanagerobject.cpp | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/bin/patchmanager-daemon/patchmanagerobject.cpp b/src/bin/patchmanager-daemon/patchmanagerobject.cpp index 530754a5f..6899cc3f1 100644 --- a/src/bin/patchmanager-daemon/patchmanagerobject.cpp +++ b/src/bin/patchmanager-daemon/patchmanagerobject.cpp @@ -1049,7 +1049,7 @@ QString PatchManagerObject::getRpmName(const QString &rpm) const handle command line arguments, and maybe daemonize. If called with any other argument other than \c --daemon, call a method - coreesponding to the command line option on the bus and exit. + coresponding to the command line option on the bus and exit. Currently supported command line options are: @@ -1072,6 +1072,8 @@ QString PatchManagerObject::getRpmName(const QString &rpm) const \li calls the "unapply" action for all patches \endtable + \note this is called from \c main() via \l{https://doc.qt.io/archives/qt-5.6/qtimer.html#singleShot-prop}{QTimer::singleShot} + */ void PatchManagerObject::process() { From 451e1ccb42ca8ed67394cdc67df8ca9b22f5786c Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 26 Jul 2023 12:16:23 +0200 Subject: [PATCH 10/43] [QDoc] Fix double-index problem --- doc/qdoc/general.qdocconf | 7 +++++-- src/index.qdoc | 2 +- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/qdoc/general.qdocconf b/doc/qdoc/general.qdocconf index 986fded52..6ce9f97b3 100644 --- a/doc/qdoc/general.qdocconf +++ b/doc/qdoc/general.qdocconf @@ -8,6 +8,9 @@ sources += ../../src/index.qdoc \ ../../src/patchdev.qdoc \ ../../src/user.qdoc \ ../../src/externalpages.qdoc -# for quoting -exampledirs += ../../src/bin/patchmanager-daemon +# for quoting. WARNING: Setting this wrong, e.g. to +# ../../src/bin/patchmanager-daemon will cause qdoc to create double index.html +# files at the wrong place. +# So, only give paths where the actual files reside: +exampledirs += ../../src/bin/patchmanager-daemon/dbus diff --git a/src/index.qdoc b/src/index.qdoc index 08db88f07..05dc3ab70 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -147,7 +147,7 @@ It is defined as follows: - \quotefile dbus/org.SfietKonstantin.patchmanager.xml + \quotefile org.SfietKonstantin.patchmanager.xml Calls can be issued e.g. like this: From 192210027821e27f59eae7f0e89ee04a5d6a9b2c Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 26 Jul 2023 13:07:22 +0200 Subject: [PATCH 11/43] [Doc] Daemon: improve Journal documentation --- src/bin/patchmanager-daemon/journal.cpp | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/src/bin/patchmanager-daemon/journal.cpp b/src/bin/patchmanager-daemon/journal.cpp index a1f89257c..96c0f12c2 100644 --- a/src/bin/patchmanager-daemon/journal.cpp +++ b/src/bin/patchmanager-daemon/journal.cpp @@ -6,9 +6,16 @@ /*! \class Journal \inmodule PatchManagerDaemon + \brief Interface to the systemd Journal. + + Listens on the systemd Journal for certain messages. + + This is done to be able to detect when Lipstick throws an error on start, + and a file from a patch caused an error. + */ /*! \fn Journal::matchFound() - Emitted when the fileters found a log entry that matched. + Emitted when the filters found a log entry that matched. */ Journal::Journal(QObject *parent) : QObject(parent) @@ -45,7 +52,7 @@ void Journal::wait() thread->start(); } -/*! Attaches itself to the Journal, filetering for \e Lipstick and \e jolla-settings executables. */ +/*! Attaches itself to the Journal, filtering for \e Lipstick and \e jolla-settings executables. */ void Journal::init() { qDebug() << Q_FUNC_INFO; @@ -67,7 +74,7 @@ void Journal::init() wait(); } -/*! Read the message from the Journal, look got certain strings, and emit the matchFound signal if found. +/*! Read the messages, look for certain strings, and emit the matchFound signal if found. Strings looked for are: From b7339c1fc8fba915892446e83c3f7b637893a1f3 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 26 Jul 2023 14:04:31 +0200 Subject: [PATCH 12/43] [Doc] Reference dev patch install docs from user docs --- src/patchdev.qdoc | 1 + src/user.qdoc | 1 + 2 files changed, 2 insertions(+) diff --git a/src/patchdev.qdoc b/src/patchdev.qdoc index e3d393a4d..1ac5effac 100644 --- a/src/patchdev.qdoc +++ b/src/patchdev.qdoc @@ -6,6 +6,7 @@ \title Patch Developer Documentation \section1 Patch Installation + \target patchdevinstall There are three ways a Patch can end up on the system: diff --git a/src/user.qdoc b/src/user.qdoc index 394a27d73..99930da11 100644 --- a/src/user.qdoc +++ b/src/user.qdoc @@ -46,5 +46,6 @@ the Web Catalog: For these you will find outdated RPMs, hence always search in the Web Catalog first. + For other, more advanced methods of installing patches, see \l{patchdevinstall}{Patch Installation} */ From 2083e608b0be3a643dd12a05d2b699ec52a59aeb Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 26 Jul 2023 14:15:20 +0200 Subject: [PATCH 13/43] [Doc] Daemon: improve InotifyWatcher docs --- src/bin/patchmanager-daemon/inotifywatcher.cpp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/bin/patchmanager-daemon/inotifywatcher.cpp b/src/bin/patchmanager-daemon/inotifywatcher.cpp index 79a632ae2..779e433ab 100644 --- a/src/bin/patchmanager-daemon/inotifywatcher.cpp +++ b/src/bin/patchmanager-daemon/inotifywatcher.cpp @@ -80,7 +80,7 @@ INotifyWatcher::INotifyWatcher(QObject *parent) Parameters are the \a path and whether it was \a removed. */ /*! \fn void INotifyWatcher::contentChanged(const QString &path, bool created); - This signal is emitted when directory content has changed + This signal is emitted when directory content has changed. Parameters are the \a path and whether something was \a created. */ INotifyWatcher::~INotifyWatcher() @@ -92,7 +92,7 @@ INotifyWatcher::~INotifyWatcher() ::close(inotifyFd); } -/*! Add \a paths to the list of paths to be watched. */ +/*! This function adds \a paths to the list of paths to be watched and returns the new list. */ QStringList INotifyWatcher::addPaths(const QStringList &paths) { QStringList p = paths; @@ -142,7 +142,7 @@ QStringList INotifyWatcher::addPaths(const QStringList &paths) return p; } -/*! Removes \a paths from the list of paths to be watched. */ +/*! This function removes \a paths from the list of paths to be watched and returns the new path list. */ QStringList INotifyWatcher::removePaths(const QStringList &paths) { QStringList p = paths; From 450577175afe9cd4d11dc65eb76e8c7a90a7cfbe Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 26 Jul 2023 14:15:55 +0200 Subject: [PATCH 14/43] Test: add large padding to html body --- doc/qdoc/pm.css | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/qdoc/pm.css b/doc/qdoc/pm.css index abb295ccd..61aacebc1 100644 --- a/doc/qdoc/pm.css +++ b/doc/qdoc/pm.css @@ -1,4 +1,5 @@ body { margin-left: 15vw; margin-right: 15vw; + padding: 5vw; font-family: "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; } code { font-family: ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace; } From d8d398d4470667ed406614a2deea8c2f08fcdfc2 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 2 Aug 2023 11:34:43 +0200 Subject: [PATCH 15/43] [QDoc] fix linking and autolinking errors --- src/bin/patchmanager-daemon/daemon.qdoc | 2 +- .../patchmanagerobject.cpp | 19 ++++++++---- src/externalpages.qdoc | 29 +++++++++++++++++++ src/index.qdoc | 16 +++++----- src/patchdev.qdoc | 18 ++++++------ src/preload/src/preloadpatchmanager.qdoc | 8 ++--- src/qml/PatchObject.cpp | 4 +-- src/qml/patchmanager.cpp | 23 ++++++++------- src/qml/webpatchesmodel.cpp | 18 ++++++------ 9 files changed, 88 insertions(+), 49 deletions(-) diff --git a/src/bin/patchmanager-daemon/daemon.qdoc b/src/bin/patchmanager-daemon/daemon.qdoc index 943de927b..09eb4c5c4 100644 --- a/src/bin/patchmanager-daemon/daemon.qdoc +++ b/src/bin/patchmanager-daemon/daemon.qdoc @@ -9,7 +9,7 @@ A D-Bus activated background service which manages patch un/installation, listing, de/actvation, and communication with the preload library. - Patchmanager is usually launched by its DBus service. + Patchmanager is usually launched by its D-Bus service. If the \c patchmanager binary is called from command line, it can also serve as a simple CLI to a running daemon. diff --git a/src/bin/patchmanager-daemon/patchmanagerobject.cpp b/src/bin/patchmanager-daemon/patchmanagerobject.cpp index 6899cc3f1..56ac20c0e 100644 --- a/src/bin/patchmanager-daemon/patchmanagerobject.cpp +++ b/src/bin/patchmanager-daemon/patchmanagerobject.cpp @@ -156,7 +156,7 @@ static const QString KEYBOARD_CODE = QStringLiteral("keyboard"); A D-Bus activated background service which manages patch un/installation, listing, de/actvation, and communication with the preload library. - PatchManager is usually launched by its DBus service. + PatchManager is usually launched by its D-Bus service. The binary can also serve as a simple command-line client to a running daemon. See the output of \c{patchmanager --help} for more information. @@ -715,7 +715,7 @@ void PatchManagerObject::doStartLocalServer() - setting up the patch translator - checking configuration constants and environment - - setting up DBus connections to Lipstick and the Store client + - setting up D-Bus connections to Lipstick and the Store client */ void PatchManagerObject::initialize() @@ -1331,7 +1331,11 @@ QString PatchManagerObject::checkEaster() return QString(); } -/*! Calls the corresponding method over D-Bus to update the \l {Patchmanager Web Catalog}{Web Catalog} Metadata. \a params stores the connection properties. */ +/*! Calls the corresponding method over D-Bus to update the \l {Patchmanager Web Catalog}{Web Catalog} Metadata. + \a params holds the query properties. + + \sa requestDownloadCatalog_link + * */ QVariantList PatchManagerObject::downloadCatalog(const QVariantMap ¶ms) { DBUS_GUARD(QVariantList()) @@ -1346,7 +1350,7 @@ QVariantList PatchManagerObject::downloadCatalog(const QVariantMap ¶ms) /*! Calls the corresponding method over D-Bus to download metadata for the patch with the name \a name - \sa requestDownloadPatchInfo + \sa requestDownloadPatchInfo_link */ QVariantMap PatchManagerObject::downloadPatchInfo(const QString &name) { @@ -1470,7 +1474,7 @@ QString PatchManagerObject::maxVersion(const QString &version1, const QString &v For regular processes, \c killall will be performed on them. - For SystemD services, they will be restarted via D-Bus call, or if that fails, via \c systemctl-user. + For systemd services, they will be restarted via D-Bus call, or if that fails, via \c systemctl-user. */ void PatchManagerObject::restartServices() @@ -2563,6 +2567,9 @@ void PatchManagerObject::downloadPatch(const QString &patch, const QUrl &url, co }); } +/*! Connect to the Web Catalog and retrieve a response configured by \a params. + \target requestDownloadCatalog_link + */ void PatchManagerObject::requestDownloadCatalog(const QVariantMap ¶ms, const QDBusMessage &message) { qDebug() << Q_FUNC_INFO << params; @@ -2605,7 +2612,7 @@ void PatchManagerObject::requestDownloadCatalog(const QVariantMap ¶ms, const /*! Retrieve patch metadata from the \l {Patchmanager Web Catalog}{Web Catalog} got patch \a name, reply with message \a message - \target requestDownloadPatchInfo + \target requestDownloadPatchInfo_link */ void PatchManagerObject::requestDownloadPatchInfo(const QString &name, const QDBusMessage &message) { diff --git a/src/externalpages.qdoc b/src/externalpages.qdoc index dc071e3da..a1ad5441b 100644 --- a/src/externalpages.qdoc +++ b/src/externalpages.qdoc @@ -34,3 +34,32 @@ \externalpage https://openrepos.net/category/patches \title Patch RPMs at OpenRepos */ + +/****** Try to fix autlinking errors for Silica types*****/ +/*! + \externalpage https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-sectionheader.html/ + \title SectionHeader +*/ +/*! + \externalpage https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-viewplaceholder.html/ + \title ViewPlaceholder +*/ +/****** Try to fix autlinking errors for standard Qt types*****/ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qml-qtqml-models-listmodel.html + \title ListModel */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qstring.html + \title QString */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qvariant.html + \title QVariant */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qqmlpropertymap.html + \title QQmlPropertyMap */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qabstractitemmodel.html + \title QAbstractItemModel */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qt.html#ItemDataRole-enum + \title DisplayRole */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qt.html#ItemDataRole-enum + \title DecorationRole */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qt.html#ItemDataRole-enum + \title EditRole */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qml-qtqml-qt.html#qsTranslate-method + \title qsTranslate() */ diff --git a/src/index.qdoc b/src/index.qdoc index 05dc3ab70..637964d26 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -268,42 +268,42 @@ \li default \li Description \row - \li applied + \li \c applied \li list of strings, comma-separated \li empty \li stores the list of "activated" patches \row - \li applyOnBoot + \li \c applyOnBoot \li Boolean \li \c false \li Whether to activate Patches at boot, or show the {Patchmanager Documentation: Startup Dialog}{Startup Dialog} \row - \li bitnessMangle + \li \c bitnessMangle \li Boolean \li \c false \li Convert patch contents so they can apply on the local architecture (e.g. \c lib vs. \c lib64 path segments) \row - \li developerMode + \li \c developerMode \li Boolean \li \c false \li \warning \b deprecated. Pre-Patchmanager v3.2.7, this was used to store the settings for "Developer Mode". This has now been split into \c patchDevelMode and \c sfosVersionCheck \row - \li notifyOnSuccess + \li \c notifyOnSuccess \li Boolean \li \c true \li Whether to show success messages in the UI \row - \li order + \li \c order \li list of strings, comma-separated \li empty \li The order of the list of patches, both in the UI as well as the order they will be applied/activated. \row - \li patchDevelMode + \li \c patchDevelMode \li Boolean \li \c false \li \row - \li sfosVersionCheck + \li \c sfosVersionCheck \li Integer (Enum) \li 0 (strict) \li Whether to relax the version checking in the PM GUI. The default will only allow Patches to be downloaded, or activated, whose compatibility field matches the currently running OS version exactly. diff --git a/src/patchdev.qdoc b/src/patchdev.qdoc index 1ac5effac..cedb79944 100644 --- a/src/patchdev.qdoc +++ b/src/patchdev.qdoc @@ -134,19 +134,19 @@ Required / Recommended: \list - \li name: An internal name for the Patch. As this is used as a directory name, it should only contain alphanumeric characters, underscores and hyphens. Notably NO spaces, dollar signs or other special characters should be used! - \li display_name: The name of the Patch, which will be shown on the patch list. - \li version: A version string. It MUST be in the format X.Y.Z - \li author: The name of the principal Patch author or maintainer. Either use your real name, as displayed on Github or Twitter, or your usual nickname. - \li compatible: A list of SailfishOS releases the Patch works on. Versions MUST be given in full with all four fields populated, e.g. "3.3.0.16" (using just "3.3" is invalid). + \li \c name: An internal name for the Patch. As this is used as a directory name, it should only contain alphanumeric characters, underscores and hyphens. Notably NO spaces, dollar signs or other special characters should be used! + \li \c display_name: The name of the Patch, which will be shown on the patch list. + \li \c version: A version string. It MUST be in the format X.Y.Z + \li \c author: The name of the principal Patch author or maintainer. Either use your real name, as displayed on Github or Twitter, or your usual nickname. + \li \c compatible: A list of SailfishOS releases the Patch works on. Versions MUST be given in full with all four fields populated, e.g. "3.3.0.16" (using just "3.3" is invalid). \endlist Optional: \list - \li description: Explanation of what the Patch does. - \li category: This is used to structure the list of Patches in categories, but also certain categories will cause Patchmanager to restart affected system services or applications. For example, Patches in the category "homescreen" will prompt the user to restart Lipstick after their activation. - \li discussion, sources, donations: Optional links to websites. - \li last_updated": An ISO date string, the Web Catalog sets this. It is used for sorting and update detection. + \li \c description: Explanation of what the Patch does. + \li \c category: This is used to structure the list of Patches in categories, but also certain categories will cause Patchmanager to restart affected system services or applications. For example, Patches in the category "homescreen" will prompt the user to restart Lipstick after their activation. + \li \c discussion, sources, donations: Optional links to websites. + \li \c last_updated: An ISO date string, the Web Catalog sets this. It is used for sorting and update detection. \endlist Reserved: diff --git a/src/preload/src/preloadpatchmanager.qdoc b/src/preload/src/preloadpatchmanager.qdoc index de385c81b..031597d12 100644 --- a/src/preload/src/preloadpatchmanager.qdoc +++ b/src/preload/src/preloadpatchmanager.qdoc @@ -49,11 +49,11 @@ \li Default \li Description \row - \li NO_INTERCEPT + \li \c NO_INTERCEPT \li undefined \li Compiles out all of the actual redirection code, leaving the rest in place. Can be used in extreme debugging cases te track what is going on without affecting applications. \row - \li ALLOW_ALL_USERS + \li \c ALLOW_ALL_USERS \li defined \li Only allow preloading for users with an UID >= \c UID_MIN, default 100000 \endtable @@ -82,11 +82,11 @@ \li Default \li Description \row - \li NO_PM_PRELOAD + \li \c NO_PM_PRELOAD \li undefined \li Makes the lib skip finding files to redirect to, effectively diabling it ofr practical purposes. Intended to be set for processes which should operate on unpatched original files. \row - \li PM_PRELOAD_DEBUG + \li \c PM_PRELOAD_DEBUG \li undefined \li Enables debugging output; messages are prefixed with \c{[pm_name]}, \c{[open]}, or \c{[open64]} depending on operation. \endtable diff --git a/src/qml/PatchObject.cpp b/src/qml/PatchObject.cpp index 5c4b5d19c..d2764795a 100644 --- a/src/qml/PatchObject.cpp +++ b/src/qml/PatchObject.cpp @@ -106,7 +106,7 @@ PatchObject::PatchObject(const QVariantMap &data, QObject *parent) \inmodule org.SfietKonstantin.patchmanager \brief An element to be used as content of an \l {PatchManagerModel} - Upon construction, the \c data parameter is mapped to PatchObject::detail + Upon construction, the \c data parameter is mapped to PatchObject::details */ PatchObject::~PatchObject() { @@ -118,7 +118,7 @@ PatchObject::~PatchObject() Maps the internal property names and values to QML properties. - See \l {https://doc.qt.io/qt-5/qqmlpropertymap.html}{QQmlPropertyMap} + See QQmlPropertyMap */ QQmlPropertyMap *PatchObject::details() { diff --git a/src/qml/patchmanager.cpp b/src/qml/patchmanager.cpp index e34dea1f3..5a34a0a2f 100644 --- a/src/qml/patchmanager.cpp +++ b/src/qml/patchmanager.cpp @@ -75,7 +75,10 @@ static const char *noop_strings[] = { \brief Patchmanager QML Plugin */ - +/*! + \typedef VersionCheck + \relates PatchManagerVersionCheck + */ PatchManager::PatchManager(QObject *parent) : QObject(parent) , m_nam(new QNetworkAccessManager(this)) @@ -669,7 +672,7 @@ void PatchManager::checkForUpdates() } /*! - Saves the setting \a name to \a value over DBus. + Saves the setting \a name to \a value over D-Bus. Returns \c true when done, \c false otherwise. \sa {} {PatchManagerObject::putSettings(const QString &name, const QDBusVariant &value)} @@ -686,7 +689,7 @@ bool PatchManager::putSettingsSync(const QString &name, const QVariant &value) } /*! - Saves the setting \a name to \a value over DBus. + Saves the setting \a name to \a value over D-Bus. Calls \a callback in success, \a errorCallback on failure. @@ -697,7 +700,7 @@ void PatchManager::putSettingsAsync(const QString &name, const QVariant &value, } /*! - Returns the setting \a name over DBus. + Returns the setting \a name over D-Bus. Defaults to \a def */ QVariant PatchManager::getSettingsSync(const QString &name, const QVariant &def) const @@ -711,7 +714,7 @@ QVariant PatchManager::getSettingsSync(const QString &name, const QVariant &def) } /*! - Retrieves the setting \a name over DBus. + Retrieves the setting \a name over D-Bus. Defaults to \a def Calls \a callback in success, \a errorCallback on failure. @@ -746,7 +749,7 @@ void PatchManager::errorCall(QJSValue errorCallback, const QString &message) } /*! - Handler for the DBus signal. Sets the internal list to \a updates if different. + Handler for the D-Bus signal. Sets the internal list to \a updates if different. Emits signal /e updatesChanged() */ @@ -763,7 +766,7 @@ void PatchManager::onUpdatesAvailable(const QVariantMap &updates) } /*! - Handler for the DBus signal. Sets the internal list to \a toggle if different. + Handler for the D-Bus signal. Sets the internal list to \a toggle if different. Emits signal /e toggleServicesChanged(bool toggle) */ @@ -781,7 +784,7 @@ void PatchManager::onToggleServicesChanged(bool toggle) /*! - Handler for the DBus signal. Sets the internal property to \a failed if different. + Handler for the D-Bus signal. Sets the internal property to \a failed if different. Emits \e failureChanged(bool failed) */ @@ -798,7 +801,7 @@ void PatchManager::onFailureChanged(bool failed) } /*! - Handler for the DBus signal. Sets the internal list to \a loaded if different. + Handler for the D-Bus signal. Sets the internal list to \a loaded if different. Emits \e loadedChanged(bool loaded) */ @@ -823,7 +826,7 @@ void PatchManager::resolveFailure() } /*! - Helper to translate a DBus reply object \a val to a valid/usable QVariant + Helper to translate a D-Bus reply object \a val to a valid/usable QVariant Recurse up to \a depth (max. 32). diff --git a/src/qml/webpatchesmodel.cpp b/src/qml/webpatchesmodel.cpp index 270ad2613..eb4c24389 100644 --- a/src/qml/webpatchesmodel.cpp +++ b/src/qml/webpatchesmodel.cpp @@ -50,31 +50,31 @@ \li QML Role Name \row \li {Qt::UserRole} - \li description + \li \c description \row \li {Qt::UserRole} - \li last_updated + \li \c last_updated \row \li {Qt::UserRole} - \li name + \li \c name \row \li {Qt::UserRole} - \li display_name + \li \c display_name \row \li {Qt::UserRole} - \li category + \li \c category \row \li {Qt::UserRole} - \li author + \li \c author \row \li {Qt::UserRole} - \li rating + \li \c rating \row \li {Qt::UserRole} - \li total_activations + \li \c total_activations \endtable - \sa {https://doc.qt.io/qt-5/qabstractitemmodel.html}{Qt::QAbstractItemModel} + \sa QAbstractItemModel */ /*! \fn virtual QHash WebPatchesModel::roleNames() const Returns the model's role names. From 618623b29551688d10b78b2c5a6d1df87433d4a0 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 2 Aug 2023 10:15:06 +0200 Subject: [PATCH 16/43] [Doc] Update Web Catalog information... Add note and link to sources --- src/externalpages.qdoc | 10 +++++++--- src/index.qdoc | 6 ++++++ src/qml/patchmanagermodel.cpp | 14 +++++++------- src/qml/webpatchesmodel.cpp | 6 +++--- 4 files changed, 23 insertions(+), 13 deletions(-) diff --git a/src/externalpages.qdoc b/src/externalpages.qdoc index a1ad5441b..db5677ab4 100644 --- a/src/externalpages.qdoc +++ b/src/externalpages.qdoc @@ -4,15 +4,19 @@ */ /*! \externalpage https://coderus.openrepos.net/pm2/projects/ - \title {Web Catalog Site} + \title Web Catalog Site +*/ +/*! + \externalpage https://github.com/CODeRUS/django-test + \title Web Catalog Source Code Repository */ /*! \externalpage https://github.com/sailfishos-patches/patchmanager - \title {Patchmanager GitHub Repository} + \title Patchmanager GitHub Repository */ /*! \externalpage https://github.com/sailfishos-patches/patchmanager/blob/master/README.md - \title {Patchmanager README} + \title Patchmanager README */ /*! \externalpage https://openrepos.net/content/olf/sailfishoschum-gui-installer diff --git a/src/index.qdoc b/src/index.qdoc index 637964d26..d6834e0bd 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -129,6 +129,12 @@ \e{to be continued...} + \section2 Development + + Web Catalog is in production, but its development is in maintainance-only mode. + + The source code is currently maintained at \l {Web Catalog Source Code Repository} + */ /****** Services Documentation page *******/ diff --git a/src/qml/patchmanagermodel.cpp b/src/qml/patchmanagermodel.cpp index d8e60570f..95272c8c6 100644 --- a/src/qml/patchmanagermodel.cpp +++ b/src/qml/patchmanagermodel.cpp @@ -58,17 +58,17 @@ PatchManagerModel::PatchManagerModel(QObject *parent) \li Qt Role \li QML Role Name \row - \li \l{https://doc.qt.io/qt-5/qt.html#ItemDataRole-enum}{Qt::DisplayRole} - \li name + \li {Qt::DisplayRole} + \li \c name \row - \li \l{https://doc.qt.io/qt-5/qt.html#ItemDataRole-enum}{Qt::DecorationRole} - \li section + \li {Qt::DecorationRole} + \li \c section \row - \li \l{https://doc.qt.io/qt-5/qt.html#ItemDataRole-enum}{Qt::EditRole} - \li patchObject + \li {Qt::EditRole} + \li \c patchObject \endtable - \sa {https://doc.qt.io/qt-5/qabstractitemmodel.html}{Qt::QAbstractItemModel} + \sa QAbstractItemModel */ PatchManagerModel::PatchManagerModel(const QList &data, QObject *parent) : QAbstractListModel(parent) diff --git a/src/qml/webpatchesmodel.cpp b/src/qml/webpatchesmodel.cpp index eb4c24389..a074cfb2b 100644 --- a/src/qml/webpatchesmodel.cpp +++ b/src/qml/webpatchesmodel.cpp @@ -118,10 +118,10 @@ WebPatchesModel::~WebPatchesModel() */ /*! \property WebPatchesModel::queryParams - Query parameters + Parameters used to perform the web catalog query. */ /*! \qmlproperty var WebPatchesModel::queryParams - Query parameters + Parameters used to perform the web catalog query. */ /*! \qmlsignal WebPatchesModel::queryParamsChanged() Emitted when query parameters change @@ -172,7 +172,7 @@ bool compareStrings(const QString &a, const QString &b) Retrieves the list of patches from the \l {Patchmanager Web Catalog}{Web Catalog}, and populates the model with its contents, sorting them if necessary. - \sa setSorted() + \sa setSorted(), PatchManagerObject::downloadCatalog() */ void WebPatchesModel::componentComplete() { From 1214446ccce4238a9499e22c480a260f5f0305ff Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 2 Aug 2023 11:51:06 +0200 Subject: [PATCH 17/43] [QDoc] add dependency information... as suggested by to qdoc --write-qa-pages --- doc/qdoc/daemon.qdocconf | 1 + doc/qdoc/dialog.qdocconf | 2 ++ doc/qdoc/general.qdocconf | 2 ++ doc/qdoc/plugin.qdocconf | 2 ++ doc/qdoc/qmlplugin.qdocconf | 1 + 5 files changed, 8 insertions(+) diff --git a/doc/qdoc/daemon.qdocconf b/doc/qdoc/daemon.qdocconf index 0ab7e67dc..b19e39df6 100644 --- a/doc/qdoc/daemon.qdocconf +++ b/doc/qdoc/daemon.qdocconf @@ -5,6 +5,7 @@ version = 2.0 url = https://github.com/sailfishos-patches/patchmanager include(common.qdocconf) +depends += patchmanager qml-plugin headerdirs += ../../src/bin/patchmanager-daemon headers.fileextensions = "*.h *.hpp" diff --git a/doc/qdoc/dialog.qdocconf b/doc/qdoc/dialog.qdocconf index 4ef9025a7..d8f44abab 100644 --- a/doc/qdoc/dialog.qdocconf +++ b/doc/qdoc/dialog.qdocconf @@ -6,5 +6,7 @@ url = https://github.com/sailfishos-patches/patchmanager include(common.qdocconf) +depends += patchmanager daemon qml-plugin + sourcedirs = ../../src/bin/dialog diff --git a/doc/qdoc/general.qdocconf b/doc/qdoc/general.qdocconf index 6ce9f97b3..ff38476bd 100644 --- a/doc/qdoc/general.qdocconf +++ b/doc/qdoc/general.qdocconf @@ -3,6 +3,8 @@ description = Patchmanager include(common.qdocconf) +depends += daemon qml-plugin settings-plugin preload dialog + ## Sources sources += ../../src/index.qdoc \ ../../src/patchdev.qdoc \ diff --git a/doc/qdoc/plugin.qdocconf b/doc/qdoc/plugin.qdocconf index 19578429e..144e7fd89 100644 --- a/doc/qdoc/plugin.qdocconf +++ b/doc/qdoc/plugin.qdocconf @@ -6,6 +6,8 @@ url = https://github.com/sailfishos-patches/patchmanager include(common.qdocconf) +depends += qml-plugin + sourcedirs = ../../src/plugin diff --git a/doc/qdoc/qmlplugin.qdocconf b/doc/qdoc/qmlplugin.qdocconf index 2ea3cb34d..798eb227b 100644 --- a/doc/qdoc/qmlplugin.qdocconf +++ b/doc/qdoc/qmlplugin.qdocconf @@ -7,6 +7,7 @@ url = https://github.com/sailfishos-patches/patchmanager include(common.qdocconf) depends += qtcore qtqml +depends += patchmanager daemon headerdirs = ../../src/qml #headers.fileextensions = "*.h *.hpp" From 32361d2457a24adfcc29b35af2d72d0605ba7cca Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 2 Aug 2023 12:29:18 +0200 Subject: [PATCH 18/43] [Doc] Improve daemon and config docs --- .../patchmanagerobject.cpp | 24 +++++++++++-------- src/index.qdoc | 4 ++++ 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/src/bin/patchmanager-daemon/patchmanagerobject.cpp b/src/bin/patchmanager-daemon/patchmanagerobject.cpp index 56ac20c0e..5dd80daa8 100644 --- a/src/bin/patchmanager-daemon/patchmanagerobject.cpp +++ b/src/bin/patchmanager-daemon/patchmanagerobject.cpp @@ -166,8 +166,7 @@ static const QString KEYBOARD_CODE = QStringLiteral("keyboard"); \enum PatchManagerObject::NotifyAction \relates PatchManagerObject::notify() - This enum specifies the type of notification to emit through \c - PatchManagerObject::notify() + This enum is used to signal state changes in the patch list. \value NotifyActionSuccessApply applying was successful @@ -342,7 +341,7 @@ void PatchManagerObject::notify(const QString &patch, NotifyAction action) } /*! - Returns the list of applied patches via getSettings(). + Returns the list of applied patches via \c getSettings(). \sa getSettings(), getSettings(), setAppliedPatches() */ QSet PatchManagerObject::getAppliedPatches() const @@ -1128,6 +1127,7 @@ void PatchManagerObject::process() QCoreApplication::exit(0); return; } + } @@ -1162,7 +1162,8 @@ bool PatchManagerObject::isPatchApplied(const QString &patch) /*! Calls the corresponding method over D-Bus to apply \a patch - \warning This function always returns an empty(!) \c QVariantMap + \warning This function always returns an empty(!) map! + */ QVariantMap PatchManagerObject::applyPatch(const QString &patch) { @@ -1183,7 +1184,7 @@ QVariantMap PatchManagerObject::applyPatch(const QString &patch) /*! call the corresponding method over D-Bus to unapply \a patch - Returns a \c QVariantMap with the call results. + Returns a map containing the call results. */ QVariantMap PatchManagerObject::unapplyPatch(const QString &patch) @@ -1384,9 +1385,11 @@ QVariantMap PatchManagerObject::getUpdates() const /*! \fn bool PatchManagerObject::putSettings(const QString &name, const QDBusVariant &value) \fn bool PatchManagerObject::putSettings(const QString &name, const QVariant &value) - Store setting called \a name to the persistent config, \c s_newConfigLocation, and give it value \a value + Store a setting called \a name to the persistent config, setting it to \a value. Returns \c true if successful. + + \sa {Patchmanager Configuration Files}, inifile */ bool PatchManagerObject::putSettings(const QString &name, const QDBusVariant &value) { @@ -1412,10 +1415,11 @@ bool PatchManagerObject::putSettings(const QString &name, const QVariant &value) /*! \fn QDBusVariant PatchManagerObject::getSettings(const QString &name, const QDBusVariant &def) \fn QVariant PatchManagerObject::getSettings(const QString &name, const QVariant &def) const - Retrieve a setting called \a name from the persistent config, \c s_newConfigLocation. - Use \a def as the default value if not present. + Retrieve a setting called \a name from the persistent config, using \a def as the default value if not present. + + Returns a variant containing the value(s) if successful. - Returns a \c QDBusVariant or \c QVariant if successful. + \sa {Patchmanager Configuration Files} */ QDBusVariant PatchManagerObject::getSettings(const QString &name, const QDBusVariant &def) @@ -1558,7 +1562,7 @@ QStringList PatchManagerObject::getToggleServicesList() const return m_toggleServices.keys(); } -/*! Returns \c true if whether there are services that should be restarted, \c false otherwise. +/*! Returns \c true when there are services that should be restarted, \c false otherwise. */ bool PatchManagerObject::getToggleServices() const { diff --git a/src/index.qdoc b/src/index.qdoc index d6834e0bd..212aaf5b2 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -319,6 +319,10 @@ \e{to be written...} + The location of the file is determined by the \c s_newConfigLocation constant + of the Patchmanager Daemon source (See the head of + \c{src/bin/patchmanager-daemon/patchmanagerobject.cpp}) + \section2 \c{/var/lib/environment/patchmanager-dialog/*.conf} \e{to be written...} From 81f9030fb8c14fb53d59290d7cc2fbe047d66a03 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 2 Aug 2023 12:40:10 +0200 Subject: [PATCH 19/43] [QDoc] Fix Home page link --- doc/qdoc/common.qdocconf | 2 +- src/externalpages.qdoc | 4 ++++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/qdoc/common.qdocconf b/doc/qdoc/common.qdocconf index c590d9797..bcf2cd5e2 100644 --- a/doc/qdoc/common.qdocconf +++ b/doc/qdoc/common.qdocconf @@ -28,7 +28,7 @@ HTML.footer = "
" \ "License.

" \ "

" -navigation.homepage = https://sailfishos-patches.github.io/patchmanager +navigation.homepage = Documentation Home navigation.hometitle = Patchmanager navigation.landingpage = Patchmanager Documentation diff --git a/src/externalpages.qdoc b/src/externalpages.qdoc index db5677ab4..bbd1e3640 100644 --- a/src/externalpages.qdoc +++ b/src/externalpages.qdoc @@ -1,3 +1,7 @@ +/*! + \externalpage https://sailfishos-patches.github.io/patchmanager + \title Documentation Home +*/ /*! \externalpage https://doc.qt.io/archives/qt-5.6/ \title Qt 5.6 Documentation From b32d8f20b9b2e343e95907ca8e1e5874cd7f796e Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 2 Aug 2023 13:08:28 +0200 Subject: [PATCH 20/43] [Doc] Overhaul Index page --- src/index.qdoc | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/src/index.qdoc b/src/index.qdoc index 212aaf5b2..0cc7583c0 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -4,25 +4,20 @@ \title Patchmanager Documentation - For User documentation, see: + \section1 User documentation + + See: \list \li \l {Patchmanager for SailfishOS} \endlist - For Patch Developer documentation, see: + \section1 Patch Developers + For information for Patch Developers, see: \list \li \l{Patch Developer Documentation} \endlist - \section1 Translations - - If you want to translate ("localise") Patchmanager to a language you know - well or enhance an existing translation, please read Patchmanager's - corresponding Wiki page - - \l{https://github.com/sailfishos-patches/patchmanager/wiki/Translations-(%22i18n%22,-%22l10n%22)}{Translations ("i18n", "l10n")}. - \section1 Internals For information on how PM operates internally, see: @@ -33,18 +28,28 @@ \li \l {Patchmanager Configuration Files} \endlist - \section1 Applications + \section1 Patchmanager Developers + + \section2 Translations + + If you want to translate ("localise") Patchmanager to a language you know + well or enhance an existing translation, please read Patchmanager's + corresponding Wiki page + + \l{https://github.com/sailfishos-patches/patchmanager/wiki/Translations-(%22i18n%22,-%22l10n%22)}{Translations ("i18n", "l10n")}. + + \section2 Applications The Patchmanager project includes the following applications: - \section2 GUI Applications + \section3 GUI Applications \list \li \l {Patchmanager Documentation: Settings Plugin}{Patchmanager Settings Plugin}, a plugin for the Jolla Settings to launch the application \li \l {Patchmanager Documentation: QML Plugin}{Patchmanager QML Plugin}, the main UI Application \li \l {Patchmanager Documentation: Startup Dialog}{Patchmanager Startup Dialog}, a UI shown at Lipstick startup. \endlist - \section2 Infrastructure Applications + \section3 Infrastructure Applications \list \li \l {Patchmanager Documentation: Daemon}{Patchmanager Daemon} \li \l {Patchmanager Documentation: Preload Library}{Preload Library} From acb286205fbb2096d688035b9aa4d8dc2610be18 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 2 Aug 2023 13:25:09 +0200 Subject: [PATCH 21/43] [QDoc] Show things marked as internal as well --- makedocs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/makedocs b/makedocs index 3208debb8..ec07cb3b6 100755 --- a/makedocs +++ b/makedocs @@ -57,7 +57,7 @@ fi printf '## Generating Docs...\n' [ -d $OUT ] && rm -r $OUT -qdoc --no-examples --outputdir $OUT --outputformat HTML --installdir $QMAKE_INSTALL_ROOT/doc doc/qdoc/master.qdocconf --single-exec $@ +qdoc --no-examples --showinternal --outputdir $OUT --outputformat HTML --installdir $QMAKE_INSTALL_ROOT/doc doc/qdoc/master.qdocconf --single-exec $@ printf '## End of Doc generation at "%s"\n' "$OUT" [ $switched_dirs = "true" ] && popd >/dev/null || cd - From 697f9a161baa6762142725fb952f34f04f45a25a Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 2 Aug 2023 13:48:57 +0200 Subject: [PATCH 22/43] [Doc] improve linking --- src/externalpages.qdoc | 18 +++++++++++------- src/qml/patchmanager.cpp | 15 +++++++++------ 2 files changed, 20 insertions(+), 13 deletions(-) diff --git a/src/externalpages.qdoc b/src/externalpages.qdoc index bbd1e3640..70afc0778 100644 --- a/src/externalpages.qdoc +++ b/src/externalpages.qdoc @@ -56,18 +56,22 @@ /*! \externalpage https://doc.qt.io/archives/qt-5.6/qml-qtqml-models-listmodel.html \title ListModel */ /*! \externalpage https://doc.qt.io/archives/qt-5.6/qstring.html - \title QString */ + \title QString */ /*! \externalpage https://doc.qt.io/archives/qt-5.6/qvariant.html - \title QVariant */ + \title QVariant */ /*! \externalpage https://doc.qt.io/archives/qt-5.6/qqmlpropertymap.html - \title QQmlPropertyMap */ + \title QQmlPropertyMap */ /*! \externalpage https://doc.qt.io/archives/qt-5.6/qabstractitemmodel.html - \title QAbstractItemModel */ + \title QAbstractItemModel */ /*! \externalpage https://doc.qt.io/archives/qt-5.6/qt.html#ItemDataRole-enum - \title DisplayRole */ + \title DisplayRole */ /*! \externalpage https://doc.qt.io/archives/qt-5.6/qt.html#ItemDataRole-enum \title DecorationRole */ /*! \externalpage https://doc.qt.io/archives/qt-5.6/qt.html#ItemDataRole-enum - \title EditRole */ + \title EditRole */ /*! \externalpage https://doc.qt.io/archives/qt-5.6/qml-qtqml-qt.html#qsTranslate-method - \title qsTranslate() */ + \title qsTranslate() */ +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qfile.html + \title QFile + \target Qt::QFile::exists() +*/ diff --git a/src/qml/patchmanager.cpp b/src/qml/patchmanager.cpp index 5a34a0a2f..8639971e9 100644 --- a/src/qml/patchmanager.cpp +++ b/src/qml/patchmanager.cpp @@ -617,7 +617,9 @@ void PatchManager::doVote(const QString &patch, int action) putSettingsSync(QStringLiteral("votes/%1").arg(patch), action); } -/*! \internal lets not spoil the fun (or the eggs!). */ +/*! lets not spoil the fun (or the eggs!). + \internal +*/ void PatchManager::checkEaster() { qDebug() << Q_FUNC_INFO; @@ -1016,17 +1018,18 @@ bool PatchManagerTranslator::installTranslator(const QString &patch) return true; } -/*! void PatchManager::activation(const QString & patch, const QString & version); +/*! Some function about \a patch and \a version \warning probably dead code, need to investigate - probably \internal, using \a patch and \a version + \internal */ void PatchManager::activation(const QString & patch, const QString & version) { } -/*! void PatchManager::easterReceived(const QString & easterText); +/*! + Signals that an Easter Egg (containing \a easterText) has been received \warning probably dead code, need to investigate - probably \internal, using \a easterText + \internal */ void PatchManager::easterReceived(const QString & easterText); { @@ -1034,7 +1037,7 @@ void PatchManager::easterReceived(const QString & easterText); /*! Returns \e true if \a filename exists, \e false otherwise. - \sa https://doc.qt.io/qt-5/qfile.html#exists-1 + \sa Qt::QFile::exists() */ bool PatchManager::fileExists(const QString &filename) { From 36be71f5958ca273e786f6af57b57f02210feb1c Mon Sep 17 00:00:00 2001 From: nephros Date: Sat, 5 Aug 2023 08:19:11 +0200 Subject: [PATCH 23/43] Mark Interal --- src/bin/patchmanager-daemon/inotifywatcher.cpp | 1 + src/bin/patchmanager-daemon/journal.cpp | 1 + 2 files changed, 2 insertions(+) diff --git a/src/bin/patchmanager-daemon/inotifywatcher.cpp b/src/bin/patchmanager-daemon/inotifywatcher.cpp index 779e433ab..e164e693a 100644 --- a/src/bin/patchmanager-daemon/inotifywatcher.cpp +++ b/src/bin/patchmanager-daemon/inotifywatcher.cpp @@ -73,6 +73,7 @@ INotifyWatcher::INotifyWatcher(QObject *parent) \inmodule PatchManagerDaemon \inherits QSocketNotifier \brief watches a list of files or directories for changes + \internal */ /*! \fn void INotifyWatcher::directoryChanged(const QString &path, bool removed); \fn void INotifyWatcher::fileChanged(const QString &path, bool removed); diff --git a/src/bin/patchmanager-daemon/journal.cpp b/src/bin/patchmanager-daemon/journal.cpp index 96c0f12c2..3b9ad3345 100644 --- a/src/bin/patchmanager-daemon/journal.cpp +++ b/src/bin/patchmanager-daemon/journal.cpp @@ -7,6 +7,7 @@ /*! \class Journal \inmodule PatchManagerDaemon \brief Interface to the systemd Journal. + \internal Listens on the systemd Journal for certain messages. From 9ca3a360ce7e4efa412383a8bfb65dfcdbf95b7a Mon Sep 17 00:00:00 2001 From: nephros Date: Mon, 14 Aug 2023 10:58:31 +0200 Subject: [PATCH 24/43] [Doc] Index: Better wording for failure state See https://github.com/nephros/patchmanager/pull/6#issuecomment-1676196247 Co-authored-by: olf --- src/index.qdoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/index.qdoc b/src/index.qdoc index 0cc7583c0..fceaf7eb6 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -228,8 +228,8 @@ \c lipstick-patchmanager.service watches the state of the Lipstick service. If Lipstick crashes, Patchmanager Daemon assumes it was caused by a patch - and goes into \c failed state. In this state, all enabled services are - disabled, and PM must be reactivated via the GUI. + and goes into \c failed state. In this state, no Patches are + activated, and PM must be reactivated via the GUI. \section1 Manual Invocation From 56079a37c71082a0815ad5e4d79c632acf23fde0 Mon Sep 17 00:00:00 2001 From: nephros Date: Mon, 14 Aug 2023 12:26:51 +0200 Subject: [PATCH 25/43] [Doc] Index: Better wording for service documentation See https://github.com/nephros/patchmanager/pull/6#issuecomment-1677071232 Co-authored-by: olf --- src/bin/patchmanager-daemon/patchmanagerobject.cpp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/bin/patchmanager-daemon/patchmanagerobject.cpp b/src/bin/patchmanager-daemon/patchmanagerobject.cpp index 5dd80daa8..4a455424f 100644 --- a/src/bin/patchmanager-daemon/patchmanagerobject.cpp +++ b/src/bin/patchmanager-daemon/patchmanagerobject.cpp @@ -1048,7 +1048,7 @@ QString PatchManagerObject::getRpmName(const QString &rpm) const handle command line arguments, and maybe daemonize. If called with any other argument other than \c --daemon, call a method - coresponding to the command line option on the bus and exit. + coresponding to the command line option on D-Bus and exit. Currently supported command line options are: @@ -1141,7 +1141,7 @@ QVariantList PatchManagerObject::listPatches() return QVariantList(); } -/*! Returns all versions contained in all patch metadata. */ +/*! Returns all versions contained in the metadata of all patches, indexed by patch name. */ QVariantMap PatchManagerObject::listVersions() { qDebug() << Q_FUNC_INFO; @@ -1642,7 +1642,7 @@ void PatchManagerObject::loadRequest(bool apply) \li "restarted" \endlist - See also \c lipstick-patchmanager.service, {Patchmanager Service} + See the documentation for \c lipstick-patchmanager.service under {Patchmanager Services} */ void PatchManagerObject::lipstickChanged(const QString &state) { From fc2e90ec5a21896172534793254a0e8afd7dc25c Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 16 Aug 2023 07:14:03 +0200 Subject: [PATCH 26/43] [Doc] document purpose of the dbus env file --- src/externalpages.qdoc | 9 +++++++++ src/index.qdoc | 21 +++++++++++++++++++-- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/src/externalpages.qdoc b/src/externalpages.qdoc index 70afc0778..043b7b0a2 100644 --- a/src/externalpages.qdoc +++ b/src/externalpages.qdoc @@ -75,3 +75,12 @@ \title QFile \target Qt::QFile::exists() */ + + +/*! \externalpage https://doc.qt.io/archives/qt-5.6/qloggingcategory.html#logging-rules + \title Qt Logging Rules +*/ + +/*! \externalpage https://dbus.freedesktop.org/doc/dbus-daemon.1.html + \title D-Bus Documentation +*/ diff --git a/src/index.qdoc b/src/index.qdoc index fceaf7eb6..a59976e0c 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -270,7 +270,7 @@ INI-style configuration file and state storage. It currently consists of two sections: \c settings, and \c votes - \section3 \c settings + \section3 \c [settings] \table \header @@ -332,6 +332,23 @@ \e{to be written...} \section2 \c{/var/lib/environment/patchmanager/10-dbus.conf} - \e{to be written...} + + Standard environment file for a D-Bus service. + + Holds environment variables for the Daemon. + + Configures the location of the socket file used to communicate with + applications in user scope via \c DBUS_SESSION_BUS_ADDRESS. + Per default this is \c {unix:path=/run/user/100000/dbus/user_bus_socket}. + + If unset, the Daemon will fallback to a hardcoded default. + + \warning Due to this setting, the socket can only be accessed by applications + runing as the "Device Owner" user (UID 100000), i.e. either \c nemo or \c defaultuser. + + This file can also be used to alter logging behaviour of the Daemon by changing the value + of \c QT_LOGGING_RULES. Per default this is set to \c{*.debug=false}. + + \sa {D-Bus Documentation}, {Qt Logging Rules} */ From e0de6373fbc386c47ac4cd25f73699238c72b779 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 16 Aug 2023 07:29:26 +0200 Subject: [PATCH 27/43] [Doc] document Dialog environment config --- src/index.qdoc | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/src/index.qdoc b/src/index.qdoc index a59976e0c..511b5fe46 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -329,13 +329,18 @@ \c{src/bin/patchmanager-daemon/patchmanagerobject.cpp}) \section2 \c{/var/lib/environment/patchmanager-dialog/*.conf} - \e{to be written...} - \section2 \c{/var/lib/environment/patchmanager/10-dbus.conf} + Standard environment files for a D-Bus service, read by \c + dbus-org.SfietKonstantin.patchmanager.service. + + Files placed here can be used to alter logging behaviour of the Dialog by + changing the value of \c QT_LOGGING_RULES. - Standard environment file for a D-Bus service. + \note Per default, this location does not exist. + + \section2 \c{/var/lib/environment/patchmanager/10-dbus.conf} - Holds environment variables for the Daemon. + This file is read by the Daemon. Configures the location of the socket file used to communicate with applications in user scope via \c DBUS_SESSION_BUS_ADDRESS. @@ -346,8 +351,9 @@ \warning Due to this setting, the socket can only be accessed by applications runing as the "Device Owner" user (UID 100000), i.e. either \c nemo or \c defaultuser. - This file can also be used to alter logging behaviour of the Daemon by changing the value - of \c QT_LOGGING_RULES. Per default this is set to \c{*.debug=false}. + This file can also be used to alter logging behaviour of the Daemon by + changing the value of \c QT_LOGGING_RULES. Per default this is set to + \c{*.debug=false}. \sa {D-Bus Documentation}, {Qt Logging Rules} */ From 3b88f0b5f0ba0ef67fcfca329c63bda61f5292fb Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 16 Aug 2023 10:04:58 +0200 Subject: [PATCH 28/43] [Doc] QML Plugin: fix link display --- src/qml/plugin.cpp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/qml/plugin.cpp b/src/qml/plugin.cpp index 327ed7d0d..45172ead8 100644 --- a/src/qml/plugin.cpp +++ b/src/qml/plugin.cpp @@ -76,7 +76,7 @@ static QObject *patchmanagertransalator_singleton(QQmlEngine *engine, QJSEngine This property holds the Operating System version. This is used for version checking. */ /*! \qmlproperty bool PatchManager::patchDevelMode - \sa {Patchmanager Configuration Files}, inifile + \sa {Patchmanager Configuration Files}, {inifile}{\c{/etc/patchmanager2.conf}} */ /*! \qmlproperty string PatchManager::patchmanagerVersion This property holds our own version @@ -90,11 +90,11 @@ static QObject *patchmanagertransalator_singleton(QQmlEngine *engine, QJSEngine */ /*! \qmlproperty var PatchManager::updates Map of internal names and metadata of patches which can be updated. - \sa PatchManagerObject::getUpdates, dbus-sys + \sa PatchManagerObject::getUpdates, {dbus-sys}{D-Bus System Service} */ /*! \qmlproperty var PatchManager::updatesNames List of display names of patches which can be updated. - \sa PatchManagerObject::getUpdates, dbus-sys + \sa PatchManagerObject::getUpdates, {dbus-sys}{D-Bus System Service} */ /***** PatchManagerTranslator ******/ From 82b0f725faf3dbbe0e385081fbdfaa5ee1bb1d04 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 16 Aug 2023 10:13:14 +0200 Subject: [PATCH 29/43] [Doc] QML Plugin: Fix link display for Silica things --- src/externalpages.qdoc | 8 ++++++-- src/qml/WebPatchPage.qml | 2 +- src/qml/patchmanager.cpp | 3 +-- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/src/externalpages.qdoc b/src/externalpages.qdoc index 043b7b0a2..34b9891ae 100644 --- a/src/externalpages.qdoc +++ b/src/externalpages.qdoc @@ -46,11 +46,15 @@ /****** Try to fix autlinking errors for Silica types*****/ /*! \externalpage https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-sectionheader.html/ - \title SectionHeader + \title Sailfish.Silica.SectionHeader */ /*! \externalpage https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-viewplaceholder.html/ - \title ViewPlaceholder + \title Sailfish.Silica.ViewPlaceholder +*/ +/*! + \externalpage https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-page.html/ + \title Sailfish.Silica.Page */ /****** Try to fix autlinking errors for standard Qt types*****/ /*! \externalpage https://doc.qt.io/archives/qt-5.6/qml-qtqml-models-listmodel.html diff --git a/src/qml/WebPatchPage.qml b/src/qml/WebPatchPage.qml index f43963504..5e8b9ed75 100644 --- a/src/qml/WebPatchPage.qml +++ b/src/qml/WebPatchPage.qml @@ -101,7 +101,7 @@ Page { /*! \qmlproperty bool fetching - Indicates whether data is currently being downloaded. The WebPatchPage will show a ViewPlaceholder if true. + Indicates whether data is currently being downloaded. The WebPatchPage will show a \l{Sailfish.Silica.ViewPlaceholder}{ViewPlaceholder} if true. Default \c true */ diff --git a/src/qml/patchmanager.cpp b/src/qml/patchmanager.cpp index 4bb410ebd..8c0a0e7f2 100644 --- a/src/qml/patchmanager.cpp +++ b/src/qml/patchmanager.cpp @@ -319,9 +319,8 @@ PatchManagerModel *PatchManager::installedModel() } /*! - Helper for SectionHeader titles. Looks up translations for \a category. + Helper for \l{Sailfish.Silica.SectionHeader}{SectionHeader} titles. Looks up translations for \a category. Returns the translated string. - \sa {https://sailfishos.org/develop/docs/silica/qml-sailfishsilica-sailfish-silica-sectionheader.html/} */ QString PatchManager::trCategory(const QString &category) const { From 53d3eea5c0e4c676dcfe3167571858ba03e2d517 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 16 Aug 2023 10:14:24 +0200 Subject: [PATCH 30/43] [Doc] Update overview pages for config files --- src/index.qdoc | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/index.qdoc b/src/index.qdoc index 511b5fe46..7548f0ddb 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -269,8 +269,12 @@ INI-style configuration file and state storage. + The location of the file is determined by the \c s_newConfigLocation constant + of the Patchmanager Daemon source (See the head of + \c{src/bin/patchmanager-daemon/patchmanagerobject.cpp}) + It currently consists of two sections: \c settings, and \c votes - \section3 \c [settings] + \section3 Config section \c [settings] \table \header @@ -320,13 +324,10 @@ \li Whether to relax the version checking in the PM GUI. The default will only allow Patches to be downloaded, or activated, whose compatibility field matches the currently running OS version exactly. \endtable - \section3 \c [votes] + \section3 Config section [votes] - \e{to be written...} - - The location of the file is determined by the \c s_newConfigLocation constant - of the Patchmanager Daemon source (See the head of - \c{src/bin/patchmanager-daemon/patchmanagerobject.cpp}) + Saves the voting state for each patch a user has voted about in the + {Settings Plugin}{Patchmanager Settings Plugin}. \section2 \c{/var/lib/environment/patchmanager-dialog/*.conf} From c5a04854de289aebbbcaf1ecb57a15dcf5a5eb75 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 16 Aug 2023 10:15:53 +0200 Subject: [PATCH 31/43] [Doc] Clarify relation between Settings and QML plugins --- src/plugin/patchmanager.qml | 5 ++--- src/plugin/plugin.qdoc | 9 ++++----- src/qml/qmlplugin.qdoc | 6 ++---- 3 files changed, 8 insertions(+), 12 deletions(-) diff --git a/src/plugin/patchmanager.qml b/src/plugin/patchmanager.qml index 4f73623c4..72b67819e 100644 --- a/src/plugin/patchmanager.qml +++ b/src/plugin/patchmanager.qml @@ -1,11 +1,10 @@ import org.SfietKonstantin.patchmanager 2.0 /*! \qmltype patchmanager - \inqmlmodule patchmanager + \inqmlmodule org.SfietKonstantin.patchmanager \brief Jolla Settings Plugin Page - \inherits \l {Page} - This loads the main Patchmanager UI from Jolla Settings. + This is a minimal QML Component that loads the main Patchmanager UI from Jolla Settings. */ PatchManagerPage {} diff --git a/src/plugin/plugin.qdoc b/src/plugin/plugin.qdoc index 4a07a8874..be6629201 100644 --- a/src/plugin/plugin.qdoc +++ b/src/plugin/plugin.qdoc @@ -7,12 +7,14 @@ The Settings Plugin makes up the main Patchmanager GUI Application. - Jolla Settings loads this page which in turn loads + Jolla Settings loads {patchmanager}{this page} which in turn loads PatchManagerPage, a part of \l {Patchmanager Documentation: QML Plugin}{Patchmanager QML Plugin}. \section2 Configuration - The Jolla Settings plugin configuration looks like this: + The Jolla Settings plugin configuration looks like below. + It adds an entry to the Settings application, and + optionally can be added to the Top Menu quick links. \badcode { @@ -33,8 +35,5 @@ } \endcode - \section2 Types - - This plugin provides no types. */ diff --git a/src/qml/qmlplugin.qdoc b/src/qml/qmlplugin.qdoc index 155d9edfa..5cc630a5a 100644 --- a/src/qml/qmlplugin.qdoc +++ b/src/qml/qmlplugin.qdoc @@ -5,11 +5,9 @@ \section1 Overview - The QML Plugin makes up the main Patchmanager GUI Application. + The QML Plugin provides the main Patchmanager GUI Application elements. - Jolla Settings loads PatchManagerPage from the QML Plugin. - - It is a both a front-end to the Daemon and a Patch management application. + It serves as a both a front-end to the Daemon, and a Patch management application. It allows to: From abfac147c2cde07e36d55b81537ded828032edd4 Mon Sep 17 00:00:00 2001 From: nephros Date: Thu, 17 Aug 2023 09:53:16 +0200 Subject: [PATCH 32/43] [Doc] QML Plugin: update details property docs --- src/qml/PatchObject.cpp | 95 +++++++++++++++++++++++++++-------------- 1 file changed, 63 insertions(+), 32 deletions(-) diff --git a/src/qml/PatchObject.cpp b/src/qml/PatchObject.cpp index d2764795a..8c3ba577d 100644 --- a/src/qml/PatchObject.cpp +++ b/src/qml/PatchObject.cpp @@ -53,35 +53,63 @@ /*! \qmlsignal PatchObject::toBeDestroyed(PatchObject object); This signal is emitted when \a object is about to be destroyed. (Duh.) */ -/*! \qmlsignal PatchObject::busyChanged(); - \internal -*/ -/*! \qmlproperty string PatchObject::details::category - Corresponds to the field of the same name in the patch metadata. See \l{metadata} -*/ -/*! \qmlproperty string PatchObject::details::display_name - Corresponds to the field of the same name in the patch metadata. See \l{metadata} -*/ -/*! \qmlproperty string PatchObject::details::name - Corresponds to the field of the same name in the patch metadata. See \l{metadata} -*/ -/*! \qmlproperty string PatchObject::details::patch - Corresponds to the field of the same name in the patch metadata. See \l{metadata} -*/ -/*! \qmlproperty string PatchObject::details::section - Corresponds to the field of the same name in the patch metadata. See \l{metadata} -*/ -/*! \qmlproperty bool PatchObject::details::isNewPatch - \c true if this patches metadata is in current format, \c false if it's legacy data. See \l{metadata} -*/ -/*! \qmlproperty bool PatchObject::details::patched - \c true if this patch is currently applied, \c false otherwise. -*/ -/*! \qmlproperty string PatchObject::details::ok - \c true if the last apply process succeeded, \c false otherwise. -*/ -/*! \qmlproperty string PatchObject::details::log - Holds the output from the latest patching process. + +/*! \qmlproperty var PatchObject::details + + The patch \l{metadata} mapped to an QML Object. + + \table + \header + \li Name + \li Type + \li Description + + \row + \li \c category + \li string + \li Corresponds to the field of the same name in the patch metadata. + + \row + \li \c display_name + \li string + \li Corresponds to the field of the same name in the patch metadata. + + \row + \li \c name + \li string + \li Corresponds to the field of the same name in the patch metadata. + + \row + \li \c patch + \li string + \li Corresponds to the field of the same name in the patch metadata. + + \row + \li \c section + \li string + \li Corresponds to the field of the same name in the patch metadata. + + \row + \li \c isNewPatch + \li bool + \li \c true if this patches metadata is in current format, \c false if it's legacy data. + + \row + \li \c patched + \li bool + \li \c true if this patch is currently applied, \c false otherwise. + + \row + \li \c ok + \li bool + \li \c true if the last apply process succeeded, \c false otherwise. + + \row + \li \c log + \li string + \li Holds the output from the latest patching process. + + \endtable */ PatchObject::PatchObject(const QVariantMap &data, QObject *parent) @@ -140,10 +168,13 @@ bool PatchObject::busy() const } /*! - Fills the PatchObject's properties from \a data. + Populates the \l{PatchObject::details}{details} property from \a data. + + If there is a \c display_name field in \a data, and \a data is treated as + regular patch metadata (\c isNewPatch is set to \c true). + Otherwise, the field \c name is used for display name, and the data is + treated as legacy metadata. - If there is a \c display_name field in \a data, and \a data is treated as regular patch metadata (\c isNewPatch is set to \c true). - Otherwise, the field \c name is used for display name, and the data is treated as legacy metadata. */ void PatchObject::setData(const QVariantMap &data) { From e55e1c8c0a1392332e6e3a588954eac271086dfc Mon Sep 17 00:00:00 2001 From: nephros Date: Thu, 17 Aug 2023 10:15:33 +0200 Subject: [PATCH 33/43] fixup! Merge branch 'more-docs' into srcgraph --- src/qml/PatchObject.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/qml/PatchObject.cpp b/src/qml/PatchObject.cpp index 8c3ba577d..2f99f535f 100644 --- a/src/qml/PatchObject.cpp +++ b/src/qml/PatchObject.cpp @@ -168,7 +168,7 @@ bool PatchObject::busy() const } /*! - Populates the \l{PatchObject::details}{details} property from \a data. + Populates the \c details property from \a data. If there is a \c display_name field in \a data, and \a data is treated as regular patch metadata (\c isNewPatch is set to \c true). From 2bbc22a61432d60317dbdabc0d3a3462384db225 Mon Sep 17 00:00:00 2001 From: nephros Date: Thu, 17 Aug 2023 10:22:53 +0200 Subject: [PATCH 34/43] [QDoc] align dependencies with .pro file QT vars --- doc/qdoc/daemon.qdocconf | 1 + doc/qdoc/dialog.qdocconf | 1 + doc/qdoc/qmlplugin.qdocconf | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/qdoc/daemon.qdocconf b/doc/qdoc/daemon.qdocconf index b19e39df6..83e923ec7 100644 --- a/doc/qdoc/daemon.qdocconf +++ b/doc/qdoc/daemon.qdocconf @@ -5,6 +5,7 @@ version = 2.0 url = https://github.com/sailfishos-patches/patchmanager include(common.qdocconf) +depends += qtcore qtdbus qtnetwork depends += patchmanager qml-plugin headerdirs += ../../src/bin/patchmanager-daemon diff --git a/doc/qdoc/dialog.qdocconf b/doc/qdoc/dialog.qdocconf index d8f44abab..bc13b9972 100644 --- a/doc/qdoc/dialog.qdocconf +++ b/doc/qdoc/dialog.qdocconf @@ -6,6 +6,7 @@ url = https://github.com/sailfishos-patches/patchmanager include(common.qdocconf) +depends += qtdbus qtnetwork depends += patchmanager daemon qml-plugin sourcedirs = ../../src/bin/dialog diff --git a/doc/qdoc/qmlplugin.qdocconf b/doc/qdoc/qmlplugin.qdocconf index 798eb227b..20ec038d7 100644 --- a/doc/qdoc/qmlplugin.qdocconf +++ b/doc/qdoc/qmlplugin.qdocconf @@ -6,7 +6,7 @@ url = https://github.com/sailfishos-patches/patchmanager include(common.qdocconf) -depends += qtcore qtqml +depends += qtcore qtqml qtnetwork qtdbus qtgui depends += patchmanager daemon headerdirs = ../../src/qml From 1bfa23012ebe56ee171751f5e20a43722820c9d7 Mon Sep 17 00:00:00 2001 From: nephros Date: Tue, 26 Nov 2024 12:34:05 +0100 Subject: [PATCH 35/43] Doc tools: Add note about missing configuration macro --- makedocs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/makedocs b/makedocs index ec07cb3b6..2c443f16c 100755 --- a/makedocs +++ b/makedocs @@ -52,6 +52,10 @@ if [ -z "$QT_INSTALL_DOCS" ]; then QT_INSTALL_DOCS=/usr/share/doc/qt5 elif [ -f /usr/share/qt5/doc/global/macros.qdocconf ]; then QT_INSTALL_DOCS=/usr/share/qt5/doc + else + printf '## ERROR: global macro config does not exist.\n' + printf "## You probably need to install \'qt5-tools\''\n" + exit 1 fi fi From 27275edfaa63d5c9a994534baac5ee27bcae33f4 Mon Sep 17 00:00:00 2001 From: nephros Date: Wed, 27 Nov 2024 11:36:34 +0100 Subject: [PATCH 36/43] Fix title, it gave a link error --- src/index.qdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/index.qdoc b/src/index.qdoc index 5d9c6c1ff..a03050fe0 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -60,7 +60,7 @@ /****** Overview page *******/ /*! - \title Overview of Patchmanager (PM) + \title Patchmanager Overview \page pmoverview.html overview \indexpage Patchmanager Documentation From 4cb0ce6a2434c2209c968aad68140a559bbce4b4 Mon Sep 17 00:00:00 2001 From: nephros Date: Thu, 28 Nov 2024 17:53:20 +0100 Subject: [PATCH 37/43] [Doc] Various improvements to the main pages --- doc/qdoc/common.qdocconf | 2 +- src/index.qdoc | 74 ++++++++++++++++++++++------------------ src/plugin/plugin.qdoc | 9 ++--- src/qml/qmlplugin.qdoc | 1 + 4 files changed, 47 insertions(+), 39 deletions(-) diff --git a/doc/qdoc/common.qdocconf b/doc/qdoc/common.qdocconf index bcf2cd5e2..384a5bf4f 100644 --- a/doc/qdoc/common.qdocconf +++ b/doc/qdoc/common.qdocconf @@ -21,7 +21,7 @@ HTML.stylesheets += ./pm.css # assign custom HTML footer to replace Qt's default copyright notice HTML.footer = "
" \ "

Patchmanager Documentation\n" \ - "Copyright (c) 2023 Patchmanager for SailfishOS contributors.\n" \ + "Copyright (c) 2023,2024 Patchmanager for SailfishOS contributors.\n" \ "This document may be used under the terms of the " \ "" \ "Creative Commons Attribution Share Alike 4.0 International " \ diff --git a/src/index.qdoc b/src/index.qdoc index a03050fe0..0b4a5ce10 100644 --- a/src/index.qdoc +++ b/src/index.qdoc @@ -208,17 +208,17 @@ \li Component \li Description \row - \li \c UNITDIR/checkForUpdates-org.SfietKonstantin.patchmanager.service + \li \c checkForUpdates-org.SfietKonstantin.patchmanager.service \li service \li - - \li Calls the \c checkForUpdates() method via D-Bus. + \li Calls the \l {PatchManagerObject::checkForUpdates}{checkForUpdates()} method via D-Bus. \row - \li \c UNITDIR/checkForUpdates-org.SfietKonstantin.patchmanager.timer + \li \c checkForUpdates-org.SfietKonstantin.patchmanager.timer \li timer \li - \li Runs the service above, every two hours. \row - \li \c UNITDIR/dbus-org.SfietKonstantin.patchmanager.service + \li \c dbus-org.SfietKonstantin.patchmanager.service \li dbus-activated service \li \l {Patchmanager Documentation: Daemon}{Daemon} \li Starts / activates the D-Bus service. @@ -235,6 +235,7 @@ \endtable \section2 Systemd User Units + \target sd_userunits \table \header @@ -243,15 +244,15 @@ \li Component \li Description \row - \li \c $USERUNITDIR/dbus-org.SfietKonstantin.patchmanager.service + \li \c dbus-org.SfietKonstantin.patchmanager.service \li dbus-activated service \li \l {Patchmanager Documentation: Startup Dialog}{Dialog} \li Starts the Startup Dialog, if necessary. \row - \li \c $USERUNITDIR/lipstick-patchmanager.service + \li \c lipstick-patchmanager.service \li service \li \l {Patchmanager Documentation: Startup Dialog}{Dialog} - \li Calls the \c lipstickChanged() method via D-Bus. + \li Calls the \l {PatchManagerObject::lipstickChanged}{lipstickChanged()} method via D-Bus. \row \li \c /var/lib/environment/patchmanager-dialog/*.conf \li environment file @@ -260,13 +261,16 @@ \endtable \c lipstick-patchmanager.service watches the state of the Lipstick service. - If Lipstick crashes, Patchmanager Daemon assumes it was caused by a patch - and goes into \c failed state. In this state, no Patches are - activated, and PM must be reactivated via the GUI. + If Lipstick crashes, the Patchmanager daemon assumes it was caused by a patch + and goes into \c failed state. In this state, no Patches are activated, and + PM must be reactivated via the GUI. \section1 Manual Invocation - Aside of using appropriate tools as \c systemctl, \c busctl, or \c dbus-send to invoke Patchmanager's functions, the patchmanager binary can also serve as CLI, if called from command line. See the output of \c{patchmanager --help} and PatchManagerObject::process() for more information. + Aside of using appropriate tools as \c systemctl, \c busctl, or \c dbus-send + to invoke Patchmanager's functions, the patchmanager binary can also serve as + CLI, if called from command line. See the output of \c{patchmanager --help} + and PatchManagerObject::process() for more information. There is also a shell script called \c patchmanager-tool, wrapping the capabilities of \c patchmanager to generate more useful functions. @@ -277,9 +281,9 @@ \section1 Logging and Debugging - Debug logging by the Patchmananger daemon can be configured by setting the \c QT_LOGGING_RULES variable to, e.g., \c{"*.debug=true"} in the environment file \c /var/lib/environment/patchmanager/10-dbus.conf + About the contents of the configuration files, see \l {Patchmanager Configuration Files}. - After changing this, Patchmanager's system service must be restarted for evaluating the new values. + After changing its configuration, Patchmanager's system service must be restarted. */ /****** Services Documentation page *******/ @@ -293,15 +297,13 @@ \target inifile - An INI-style configuration file and state storage. + Stores configuration and state storage for the \l {Patchmanager Documentation: Daemon}{Daemon}. - It consists of two sections: \c settings and \c votes + It is an INI-style configuration file and has two possible sections: \c settings and \c votes. - The location of the file is determined by the \c s_newConfigLocation constant - of the Patchmanager Daemon source (See the head of - \c{src/bin/patchmanager-daemon/patchmanagerobject.cpp}) + \note The location of the file is determined by the \c s_newConfigLocation constant + of the daemon source. (See the head of \c{src/bin/patchmanager-daemon/patchmanagerobject.cpp}) - It currently consists of two sections: \c settings, and \c votes \section3 Config section \c [settings] \table @@ -316,28 +318,28 @@ \li empty \li Stores the list of "activated" Patches. \row - \li workingPatches + \li \c workingPatches \li list of strings, comma-separated \li empty \li Stores a list of Patches, which represent a "last-known-good" / working set of enabled Patches. This list is automatically copied from \c applied after each successful run of auto-apply. \row \li \c applyOnBoot - \li Boolean + \li boolean \li \c false \li Whether to activate all enabled Patches during OS startup or to show the {Patchmanager Documentation: Startup Dialog}{Startup Dialog}. \row \li \c bitnessMangle - \li Boolean + \li boolean \li \c false \li Convert Patch contents so they are applicable to the local architecture (e.g., \c lib versus \c lib64 path elements). \row \li \c developerMode - \li Boolean + \li boolean \li \c false \li \warning \b deprecated. Before Patchmanager 3.2.7, this was used to store the settings for the "Developer Mode". This mode has been split into \c patchDevelMode and \c sfosVersionCheck \row \li \c notifyOnSuccess - \li Boolean + \li boolean \li \c true \li Whether to show notifications about successful actions on the GUI. \row @@ -347,34 +349,37 @@ \li The order of Patches, both in the list on the GUI, and the sequence in which they will be activated and hence their patch files applied. \row \li \c patchDevelMode - \li Boolean + \li boolean \li \c false \li \row \li \c sfosVersionCheck - \li Integer (Enum) + \li integer (enum) \li 0 (strict) \li Whether to relax the version checking in the Patchmanager GUI. The default setting will only allow Patches to be downloaded or activated, of which an entry in their compatibility field exactly matches the currently installed OS version. \endtable \section3 Config section [votes] - Saves the voting state for each patch a user has voted about in the - {Settings Plugin}{Patchmanager Settings Plugin}. + Saves the voting state for each patch a user has voted on in the + {Patchmanager Documentation: Settings Plugin}{Settings Plugin}. - \section2 \c{/var/lib/environment/patchmanager-dialog/*.conf} + \section2 \c{/var/lib/environment/patchmanager-dialog/} - Standard environment files for a D-Bus service, read by \c - dbus-org.SfietKonstantin.patchmanager.service. + This location can contain one or more environment files for a systemd service + (see \l {https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html}{systemd.exec}). + Their filename must end in \c{.conf} and are read by \l {sd_userunits}{dbus-org.SfietKonstantin.patchmanager.service}. Files placed here can be used to alter logging behaviour of the Dialog by changing the value of \c QT_LOGGING_RULES. - \note Per default, this location does not exist. + \sa {Patchmanager Services} + + \note In default patchmanager installations, this location does not exist. \section2 \c{/var/lib/environment/patchmanager/10-dbus.conf} - This file is read by the Daemon. + This file is read by the \l {Patchmanager Documentation: Daemon}{Daemon}. Configures the location of the socket file used to communicate with applications in user scope via \c DBUS_SESSION_BUS_ADDRESS. @@ -389,6 +394,7 @@ changing the value of \c QT_LOGGING_RULES. Per default this is set to \c{*.debug=false}. - \sa {D-Bus Documentation}, {Qt Logging Rules} + \sa {Patchmanager Services}, {D-Bus Documentation}, {Qt Logging Rules} + */ diff --git a/src/plugin/plugin.qdoc b/src/plugin/plugin.qdoc index be6629201..daf88010c 100644 --- a/src/plugin/plugin.qdoc +++ b/src/plugin/plugin.qdoc @@ -7,14 +7,15 @@ The Settings Plugin makes up the main Patchmanager GUI Application. - Jolla Settings loads {patchmanager}{this page} which in turn loads + Jolla Settings loads \l {patchmanager}{this page} which in turn loads PatchManagerPage, a part of \l {Patchmanager Documentation: QML Plugin}{Patchmanager QML Plugin}. \section2 Configuration - The Jolla Settings plugin configuration looks like below. - It adds an entry to the Settings application, and - optionally can be added to the Top Menu quick links. + The Jolla Settings plugin configuration (installed at \c + /usr/share/jolla-settings/entries/) looks like below. It adds an entry to + the Settings application, and optionally can be added to the Top Menu quick + links. \badcode { diff --git a/src/qml/qmlplugin.qdoc b/src/qml/qmlplugin.qdoc index 5cc630a5a..4043df1db 100644 --- a/src/qml/qmlplugin.qdoc +++ b/src/qml/qmlplugin.qdoc @@ -6,6 +6,7 @@ \section1 Overview The QML Plugin provides the main Patchmanager GUI Application elements. + It is designed to be invoked through the \l {Patchmanager Documentation: Settings Plugin}{Settings Plugin}. It serves as a both a front-end to the Daemon, and a Patch management application. From 0104ea916aef39782addb54029ba135f14e87b29 Mon Sep 17 00:00:00 2001 From: nephros Date: Fri, 29 Nov 2024 12:44:03 +0100 Subject: [PATCH 38/43] [QDoc Style] Use a Patchmanager CI Palette for the CSS --- doc/qdoc/pm.css | 79 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 72 insertions(+), 7 deletions(-) diff --git a/doc/qdoc/pm.css b/doc/qdoc/pm.css index 61aacebc1..df53670e3 100644 --- a/doc/qdoc/pm.css +++ b/doc/qdoc/pm.css @@ -1,10 +1,75 @@ -body { margin-left: 15vw; margin-right: 15vw; - padding: 5vw; +:root { + /* define our own custom color palette. Colors generated by some online + * tool using the Patchmanager icon. + + "Pflaster" means band-aid in German. + */ + --black: #000000ff; + --pm-pflaster-light: #efd1b3ff; + --pm-pflaster-medium-1: #dda267ff; + --pm-pflaster-medium-2: #dda267ff; + --pm-pflaster-darker: #ad7e52ff; + --pm-pflaster-dark: #584029ff; + --pm-red: #EF1C10ff; + --pm-green: #66BC52ff; + --pm-gray-light-1: #d6dcd7ff; + --pm-gray-light-2: #b8c9c5ff; + --pm-gray-medium-1: #96a9a1ff; + --pm-gray-medium-2: #71928aff; + --pm-gray-dark: #2d3a37ff; + + color: var(--pm-pflaster-dark); + background-color: var(--pm-gray-light-1); +} +html { + color: var(--pm-pflaster-dark); + background-color: var(--pm-gray-light-1); +} + +body { + margin-left: 3vw; margin-right: 3vw; font-family: "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; } -code { font-family: ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace; } -a:link { color: #8C001A; text-decoration: none; text-align: left; } +code { + font-family: SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace; + font-weight: medium; +} +a:link { color: var(--pm-pflaster-darker); text-decoration: none; text-align: left; } a.qa-mark:target:before { content: "***"; color: #ff0000; } -a:hover { color: #8C0060; text-align: left; } -a:visited { color: #8C001A; text-align: left; } -a:visited:hover { color: #8C0060; text-align: left; } +a:hover { color: var(--pm-red); text-align: left; } +a:visited { color: var(--pm-green); text-align: left; } +a:visited:hover { text-decoration: underline; } +/* +a:visited { color: var(--pm-pflaster-dark); text-align: left; } +a:active { color: var(--pm-green); text-align: left; } + +*/ + +.header .breadcrumb { background-color: var(--pm-gray); } + +.generic .odd .alphaChar{ background-color: var(--pm-gray-light-2); } +.generic .even .alphaChar{ background-color: var(--pm-gray-medium-1); } + +table tr.odd { background-color: var(--pm-gray-light-2); } +table tr.even { background-color: var(--pm-gray-medium-1); } + +pre { + background-color: var(--pm-gray-light-2); + color: var(--pm-gray-dark); +} + +hr { background-color: var(--pm-gray-medium-1); + border: 1px solid var(--pm-pflaster-dark); +} +th { + background-color: var(--pm-gray-medium-2); + border-left: 1px solid var(--pm-gray-dark); +} + +.content h2 { + margin-top: 2em; + margin-bottom: 1em; +} +.content h3 { + margin: 0; +} From c85352570a3b0b10b44f952cdc370c5dbf695f92 Mon Sep 17 00:00:00 2001 From: nephros Date: Fri, 29 Nov 2024 12:44:48 +0100 Subject: [PATCH 39/43] [QDoc Style] Use the CSS in html generation --- doc/qdoc/common.qdocconf | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/qdoc/common.qdocconf b/doc/qdoc/common.qdocconf index 384a5bf4f..8812ce294 100644 --- a/doc/qdoc/common.qdocconf +++ b/doc/qdoc/common.qdocconf @@ -17,6 +17,11 @@ codesuffix = "\n" # override/add some things to the stylesheets: HTML.stylesheets += ./pm.css +# the above does not acutally add the stylesheet to the html file, so do it +# manually here. Include the default first. +HTML.headerstyles = \ + " \n" \ + " \n" # assign custom HTML footer to replace Qt's default copyright notice HTML.footer = "

" \ From 42281e726781f798d99c6d0aaeba946060b19908 Mon Sep 17 00:00:00 2001 From: nephros Date: Fri, 29 Nov 2024 13:01:56 +0100 Subject: [PATCH 40/43] [QDoc Style] Use lighter main background --- doc/qdoc/pm.css | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/qdoc/pm.css b/doc/qdoc/pm.css index df53670e3..3d9a2fe6a 100644 --- a/doc/qdoc/pm.css +++ b/doc/qdoc/pm.css @@ -12,6 +12,7 @@ --pm-pflaster-dark: #584029ff; --pm-red: #EF1C10ff; --pm-green: #66BC52ff; + --pm-gray-lightest: ##f1f3f2ff; --pm-gray-light-1: #d6dcd7ff; --pm-gray-light-2: #b8c9c5ff; --pm-gray-medium-1: #96a9a1ff; @@ -19,11 +20,11 @@ --pm-gray-dark: #2d3a37ff; color: var(--pm-pflaster-dark); - background-color: var(--pm-gray-light-1); + background-color: var(--pm-gray-lightest); } html { color: var(--pm-pflaster-dark); - background-color: var(--pm-gray-light-1); + background-color: var(--pm-gray-lightest); } body { @@ -34,9 +35,10 @@ code { font-family: SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace; font-weight: medium; } -a:link { color: var(--pm-pflaster-darker); text-decoration: none; text-align: left; } a.qa-mark:target:before { content: "***"; color: #ff0000; } -a:hover { color: var(--pm-red); text-align: left; } +a:link { color: var(--pm-pflaster-darker); text-decoration: none; text-align: left; } +a:active { color: var(--pm-red); text-align: left; } +a:active:hover { text-decoration: underline; } a:visited { color: var(--pm-green); text-align: left; } a:visited:hover { text-decoration: underline; } /* @@ -45,7 +47,7 @@ a:active { color: var(--pm-green); text-align: left; } */ -.header .breadcrumb { background-color: var(--pm-gray); } +.header .breadcrumb { background-color: var(--pm-gray-light-2); } .generic .odd .alphaChar{ background-color: var(--pm-gray-light-2); } .generic .even .alphaChar{ background-color: var(--pm-gray-medium-1); } @@ -53,8 +55,8 @@ a:active { color: var(--pm-green); text-align: left; } table tr.odd { background-color: var(--pm-gray-light-2); } table tr.even { background-color: var(--pm-gray-medium-1); } -pre { - background-color: var(--pm-gray-light-2); +table, pre { + background-color: var(--pm-gray-light-1); color: var(--pm-gray-dark); } From f7b1a567d44d828e256527d8625c3fc163559cf1 Mon Sep 17 00:00:00 2001 From: nephros Date: Fri, 29 Nov 2024 13:18:13 +0100 Subject: [PATCH 41/43] [QDoc Style] Override some margins --- doc/qdoc/pm.css | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/qdoc/pm.css b/doc/qdoc/pm.css index 3d9a2fe6a..078c24993 100644 --- a/doc/qdoc/pm.css +++ b/doc/qdoc/pm.css @@ -39,8 +39,11 @@ a.qa-mark:target:before { content: "***"; color: #ff0000; } a:link { color: var(--pm-pflaster-darker); text-decoration: none; text-align: left; } a:active { color: var(--pm-red); text-align: left; } a:active:hover { text-decoration: underline; } -a:visited { color: var(--pm-green); text-align: left; } -a:visited:hover { text-decoration: underline; } + +.content a:visited { color: var(--pm-green); text-align: left; } +.content a:visited:hover { text-decoration: underline; } +span.type a:visited { text-decoration: underline; } + /* a:visited { color: var(--pm-pflaster-dark); text-align: left; } a:active { color: var(--pm-green); text-align: left; } @@ -68,10 +71,10 @@ th { border-left: 1px solid var(--pm-gray-dark); } +/* Margins, padding etc */ +.content ul li { padding-left: 0.5em } +.content ul { padding-left: 2.0em; } .content h2 { - margin-top: 2em; - margin-bottom: 1em; -} -.content h3 { - margin: 0; + margin-top: 1.5em; + margin-bottom: 0.5em; } From e5283a5593db5baa58406ae37cac8be4387f42eb Mon Sep 17 00:00:00 2001 From: nephros Date: Fri, 29 Nov 2024 13:25:01 +0100 Subject: [PATCH 42/43] [QDoc Style] Lighter odd/even backgrounds --- doc/qdoc/pm.css | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/qdoc/pm.css b/doc/qdoc/pm.css index 078c24993..6265706ee 100644 --- a/doc/qdoc/pm.css +++ b/doc/qdoc/pm.css @@ -44,6 +44,8 @@ a:active:hover { text-decoration: underline; } .content a:visited:hover { text-decoration: underline; } span.type a:visited { text-decoration: underline; } +.red { color: var(--pm-red); } + /* a:visited { color: var(--pm-pflaster-dark); text-align: left; } a:active { color: var(--pm-green); text-align: left; } @@ -53,10 +55,10 @@ a:active { color: var(--pm-green); text-align: left; } .header .breadcrumb { background-color: var(--pm-gray-light-2); } .generic .odd .alphaChar{ background-color: var(--pm-gray-light-2); } -.generic .even .alphaChar{ background-color: var(--pm-gray-medium-1); } +.generic .even .alphaChar{ background-color: var(--pm-gray-light-1); } table tr.odd { background-color: var(--pm-gray-light-2); } -table tr.even { background-color: var(--pm-gray-medium-1); } +table tr.even { background-color: var(--pm-gray-light-1); } table, pre { background-color: var(--pm-gray-light-1); From c6722d367defdcf066410ae765d302ea9997ea49 Mon Sep 17 00:00:00 2001 From: nephros Date: Fri, 29 Nov 2024 13:45:05 +0100 Subject: [PATCH 43/43] fixup! [Doc] document Preload library --- src/preload/src/preloadpatchmanager.qdoc | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/src/preload/src/preloadpatchmanager.qdoc b/src/preload/src/preloadpatchmanager.qdoc index 031597d12..a23ce66fd 100644 --- a/src/preload/src/preloadpatchmanager.qdoc +++ b/src/preload/src/preloadpatchmanager.qdoc @@ -10,7 +10,7 @@ This library \list - \li Intercepts calls to \l {https://www.man7.org/linux/man-pages/man2/open.2.html}{\c{open()} (or \c{open64()})}, + \li Intercepts calls to \l {https://www.man7.org/linux/man-pages/man2/open.2.html}{\c{open()}} (or \c{open64()}), \li analyzes which files the call was meant to open \li asks the Patchmanager Daemon (via socket) whether it knows of a patched version. \endlist @@ -22,11 +22,8 @@ Certain paths are blacklisted for these operations to reduce the risk of critical services, or PM itself, choking on these redirections. - \e{to be continued...} - \section1 Implementation - \e{to be continued...} \section3 Blacklists: The following two "blacklists" cause the lib to back off redirecting calls for paths matching one of the entries in the list: @@ -51,14 +48,14 @@ \row \li \c NO_INTERCEPT \li undefined - \li Compiles out all of the actual redirection code, leaving the rest in place. Can be used in extreme debugging cases te track what is going on without affecting applications. + \li If defined, compiles out all of the actual redirection code, leaving the rest in place. Can be used in extreme debugging cases to track what is going on without affecting applications. \row \li \c ALLOW_ALL_USERS \li defined - \li Only allow preloading for users with an UID >= \c UID_MIN, default 100000 + \li If undefined, only allow preloading for users with an UID >= \c UID_MIN, default 100000 \endtable - \section1 Running + \section1 Execution \section2 Installation Once the library is installed in one of the standard library paths, the following is added to the file \c /etc/ld.so.preload @@ -84,7 +81,7 @@ \row \li \c NO_PM_PRELOAD \li undefined - \li Makes the lib skip finding files to redirect to, effectively diabling it ofr practical purposes. Intended to be set for processes which should operate on unpatched original files. + \li Makes the lib skip finding files to redirect to, effectively diabling it for practical purposes. Intended to be set for processes which should operate on unpatched original files. \row \li \c PM_PRELOAD_DEBUG \li undefined @@ -95,6 +92,6 @@ \section2 Socket - The library will try to open a socket at \c{/tmp/patchmanager-socket} in order to communicate with the Patchmanager Daemon + The library will try to open a socket at \c{/tmp/patchmanager-socket} in order to communicate with the Patchmanager Daemon. */