doc: Revise packages filtering doc section

rpm-software-management · Aug 16, 2024 · a88738e · a88738e
1 parent b52426e
commit a88738e
Show file tree

Hide file tree

Showing 8 changed files with 45 additions and 43 deletions.
diff --git a/dnf5.spec b/dnf5.spec
@@ -330,8 +330,7 @@ It supports RPM packages, modulemd modules, and comps groups & environments.
 %{_mandir}/man7/dnf*-aliases.7.*
 %{_mandir}/man7/dnf*-caching.7.*
 %{_mandir}/man7/dnf*-comps.7.*
-# TODO(jkolarik): filtering is not ready yet
-# %%{_mandir}/man7/dnf*-filtering.7.*
+%{_mandir}/man7/dnf*-filtering.7.*
 %{_mandir}/man7/dnf*-forcearch.7.*
 %{_mandir}/man7/dnf*-installroot.7.*
 # TODO(jkolarik): modularity is not ready yet

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -88,8 +88,7 @@ if(WITH_MAN)
         install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5-aliases.7 DESTINATION share/man/man7)
         install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5-caching.7 DESTINATION share/man/man7)
         install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5-comps.7 DESTINATION share/man/man7)
-        # TODO(jkolarik): filtering is not ready yet
-        # install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5-filtering.7 DESTINATION share/man/man7)
+        install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5-filtering.7 DESTINATION share/man/man7)
         install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5-forcearch.7 DESTINATION share/man/man7)
         install(FILES ${CMAKE_CURRENT_BINARY_DIR}/man/dnf5-installroot.7 DESTINATION share/man/man7)
         # TODO(jkolarik): modularity is not ready yet

diff --git a/doc/api/c++/libdnf5_rpm_package_sack.rst b/doc/api/c++/libdnf5_rpm_package_sack.rst
@@ -1,6 +1,7 @@
 PackageSack
 ===========
 
+.. _api_packagesack-label:
 
 .. doxygenclass:: libdnf5::rpm::PackageSack
     :members:
diff --git a/doc/conf.py.in b/doc/conf.py.in
@@ -153,7 +153,7 @@ man_pages = [
     ('misc/aliases.7', 'dnf5-aliases', 'Aliases for command line arguments', AUTHORS, 7),
     ('misc/caching.7', 'dnf5-caching', 'Caching', AUTHORS, 7),
     ('misc/comps.7', 'dnf5-comps', 'Comps Groups And Environments', AUTHORS, 7),
-    # TODO(jkolarik): ('misc/filtering.7', 'dnf5-filtering', 'Packages Filtering', AUTHORS, 7),
+    ('misc/filtering.7', 'dnf5-filtering', 'Packages Filtering', AUTHORS, 7),
     ('misc/forcearch.7', 'dnf5-forcearch', 'Forcearch Parameter', AUTHORS, 7),
     ('misc/installroot.7', 'dnf5-installroot', 'Installroot Parameter', AUTHORS, 7),
     # TODO(jkolarik): ('misc/modularity.7', 'dnf5-modularity', 'Modularity Overview', AUTHORS, 7),

diff --git a/doc/dnf5.conf-todo.5.rst b/doc/dnf5.conf-todo.5.rst
@@ -157,10 +157,6 @@ This section does not track any deprecated option. For such options see :ref:`De
 
 ``config_file_age``
 
-.. _disable_excludes_options-label:
-
-``disable_excludes``
-
 .. _allow_downgrade_options-label:
 
 ``allow_downgrade``

diff --git a/doc/dnf5.conf.5.rst b/doc/dnf5.conf.5.rst
@@ -16,8 +16,6 @@
     You should have received a copy of the GNU General Public License
     along with libdnf.  If not, see <https://www.gnu.org/licenses/>.
 
-.. TODO(jkolarik): Fix --disableexcludes references, the option is dropped now.
-
 .. _dnf5_conf-label:
 
 ##############################
@@ -741,6 +739,12 @@ configuration.
 
     Default: ``75``
 
+.. _disable_excludes_options-label:
+``disable_excludes``
+    :ref:`list <list-label>`
+
+    Used to disable packages filtering. It can include a list of repository IDs (globs allowed) for which repository-specific excludes are ignored. If it contains the special value ``main``, excludes from the main configuration files are bypassed. If it contains the special value ``*``, no excludes filtering is applied at all.
+
 .. _enablegroups_options-label:
 
 ``enablegroups``
@@ -758,7 +762,7 @@ configuration.
     Exclude packages of this repository, specified by a name or a glob and
     separated by a comma, from all operations.
 
-    Can be disabled using ``--disableexcludes`` command line switch.
+    Can be disabled using ``disable_excludes`` config option.
 
     Default: ``[]``.
 
@@ -788,7 +792,7 @@ configuration.
     so if you 'excludepkgs=*.i386' and 'includepkgs=python*' then only packages starting with python
     that do not have an i386 arch will be seen by DNF5 in this repo.
 
-    Can be disabled using ``--disableexcludes`` command line switch.
+    Can be disabled using ``disable_excludes`` config option.
 
     Default: ``[]``.
 

diff --git a/doc/misc/filtering.7.rst b/doc/misc/filtering.7.rst
@@ -16,9 +16,6 @@
     You should have received a copy of the GNU General Public License
     along with libdnf.  If not, see <https://www.gnu.org/licenses/>.
 
-..
-    # TODO(jkolarik): review, fix according to DNF5 state
-
 .. _filtering_misc_ref-label:
 
 ###################
@@ -28,42 +25,49 @@
 Description
 ===========
 
-Package filtering filters packages out from the available package set, making them invisible to most
-of the ``DNF5`` commands. They cannot be used in a transaction. Packages can be filtered out by either
-`Exclude Filtering` or `Modular Filtering`.
+Package filtering removes packages from the available package set, making them invisible to most ``DNF5`` commands. As a result, these packages cannot be included in any transaction.
 
+There are several ways a package can be filtered out:
 
-Exclude Filtering
-=================
+Global excludes filtering
+=========================
+
+Exclude filtering can be adjusted using the ``includepkgs`` or ``excludepkgs`` configuration options in the DNF5 configuration file. To disable excludes, you can use the ``disable_excludes`` configuration option:
+
+``dnf5 --setopt=disable_excludes=* install bash``
+
+For details about the configuration options see :manpage:`dnf5.conf(5)`, :ref:`DNF5 configuration reference <dnf5_conf-label>`.
+
+
+Repository excludes filtering
+=============================
 
-Exclude Filtering is a mechanism used by a user or by the ``DNF5`` plugin to modify the set of available
-packages. Exclude Filtering can be modified by either ``includepkgs`` or ``excludepkgs`` configuration options in
-configuration files. In addition to user-configured excludes, plugins can also extend the set of excluded packages.
-To disable excludes from the ``DNF5`` plugin you can use the ``--disable-plugin`` command line option.
+Similar to global excludes, but this configuration is repository-specific and only affects packages within the repository where the excludes are set.
 
-To disable all excludes for e.g. the install command you can use the following combination
-of command line options:
 
-``dnf5 --disableexcludes=all --disable-plugin="*" install bash``
+User excludes filtering
+=======================
 
+API users have an additional option how to fine-tune excluded packages using ``*_user_excludes()`` and ``*_user_includes`` methods of the ``PackageSack`` object. See :ref:`PackageSack API <api_packagesack-label>`.
 
-Modular Filtering
+
+Versionlock
+===========
+
+Additionally, the versionlock functionality is implemented using excludes filtering. However, these excludes are applied only during transactional operations.
+For details see :manpage:`dnf5-versionlock(8)`, :ref:`Versionlock command <versionlock_command_ref-label>`.
+
+
+Modular filtering
 =================
 
 Please see `the modularity documentation` for details on how Modular Filtering works.
 
-With modularity, only RPM packages from ``active`` module streams are included in the available
-package set. RPM packages from ``inactive`` module streams, as well as non-modular packages with
-the same name or provides as a package from an ``active`` module stream, are filtered out. Modular
-filtering is not applied to packages added from the command line, installed packages, or packages
-from repositories with ``module_hotfixes=true`` in their ``.repo`` file.
+With modularity, only RPM packages from ``active`` module streams are included in the available package set. RPM packages from ``inactive`` module streams, as well as non-modular packages with the same name or provides as a package from an ``active`` module stream, are filtered out. Modular filtering is not applied to packages added from the command line, installed packages, or packages from repositories with ``module_hotfixes=true`` in their ``.repo`` file.
 
-Disabling of modular filtering is not recommended, because it could cause the system to get into
-a broken state. To disable modular filtering for a particular repository, specify
+Disabling of modular filtering is not recommended, because it could cause the system to get into a broken state. To disable modular filtering for a particular repository, specify
 ``module_hotfixes=true`` in the ``.repo`` file or use ``--setopt=<repo_id>.module_hotfixes=true``.
 
-To discover the module which contains an excluded package use ``dnf5 module provides``.
-
-
-Examples
-========
+..
+    # TODO(mblaha) - `dnf5 module provides` command is not implemented yet
+    # To discover the module which contains an excluded package use ``dnf5 module provides``.
diff --git a/doc/misc/index.rst b/doc/misc/index.rst
@@ -9,13 +9,12 @@ Miscellaneous
     aliases.7
     caching.7
     comps.7
+    filtering.7
     forcearch.7
     installroot.7
     specs.7
 
 ..
-    # TODO(jkolarik): Filtering is not ready yet
-    filtering.7
 
     # TODO(jkolarik): Modularity is not ready yet
     modularity.7