[sdk/kdesrc-build/docbook_historied_per_file] doc: kde-projects: Don't auto-filter git-repo's direct children.

[Michael Pyne]

Git commit 26461b97d3f53c09024bc602ddaca3c904a3b043 by Michael Pyne.
Committed on 12/07/2013 at 03:41.
Pushed by ashark into branch 'docbook_historied_per_file'.

kde-projects: Don't auto-filter git-repo's direct children.

Kind of a mouthful, but remove a filter that was added to avoid
automatically including an actual git repository's children that were
also git repositories. E.g. think of something like a SuperBuild git
module that also had its component git modules as logical children
within projects.kde.org.

This filter is unnecessary now that kdesrc-build supports both kde.org
metadata (kde-build-metadata/build-script-ignore) and user-configurable
module filtering (ignore-modules option).

More importantly this filter precludes many other desirable types of
group syntax (e.g. including all of kdebindings just by asking for
kdebindings).

So we remove the filter. The trouble I've seen so far is that it is
now rather difficult to build *only* kdelibs, since kde/kdelibs is a
logical parent of nepomuk-core, nepomuk-widgets, and kactivities. This
can be worked-around by using a normal single module declaration. E.g.

    module kdelibs
        repository kde:kdelibs
    end module

On the other hand, the recently-added config file option
"ignore-modules" should now remove any kde-projects modules that contain
a path component(s) matching the ignored module. You may have to be
specific with a given ignore atom for this reason (e.g. ignore
playground/libs, not 'libs' otherwise you'll also ignore
kdegraphics/libs at this point... though that was also true before this
commit).

BUG:321667

Original commit: a0338664
https://invent.kde.org/sdk/kdesrc-build/-/commit/a033866429b62c29fd93aea843c2f21427634ec8

M  +12   -0    doc/getting-started/kde-modules-and-selection.docbook
M  +12   -0    doc/kdesrc-buildrc/conf-options-table.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/26461b97d3f53c09024bc602ddaca3c904a3b043

diff --git a/doc/getting-started/kde-modules-and-selection.docbook b/doc/getting-started/kde-modules-and-selection.docbook
index 7af9af7f..eedcd576 100644
--- a/doc/getting-started/kde-modules-and-selection.docbook
+++ b/doc/getting-started/kde-modules-and-selection.docbook
@@ -326,6 +326,18 @@ module-set <replaceable>utils</replaceable>
     # This option "subtracts out" modules from the modules chosen by use-modules, above.
     <option><link linkend="conf-ignore-modules">ignore-modules</link></option> <replaceable>kremotecontrol</replaceable>
 end module-set
+
+module-set <replaceable>graphics</replaceable>
+    <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>
+
+    # This option chooses what modules to look for in the database.
+    <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>extragear/graphics</replaceable>
+
+    # This option "subtracts out" modules from the modules chosen by use-modules, above.
+    # In this case, *both* extragear/graphics/kipi-plugins and
+    # extragear/graphics/kipi-plugins/kipi-plugins-docs are ignored
+    <option><link linkend="conf-ignore-modules">ignore-modules</link></option> <replaceable>extragear/graphics/kipi-plugins</replaceable>
+end module-set
 </programlisting>
 </example>
 
diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index c7e6ffdb..c7279992 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -434,6 +434,18 @@ instead skipped entirely. Use this option when you want to build an entire
 <link linkend="kde-projects-module-sets">kde-projects</link> project grouping
 <emphasis>except for</emphasis> some specific modules.</para>
 
+<para>The option value does not necessarily have to name the module directly.
+Any module that has full consecutive parts of its <link
+linkend="kde-projects-module-sets">&kde; projects module path</link> match one
+of the option values will be ignored, so you can ignore multiple modules this
+way.</para>
+
+<para>For example, an option value of <replaceable>libs</replaceable> would
+result in both <symbol>kde/kdegraphics/libs</symbol> and
+<symbol>playground/libs</symbol> being excluded (though not
+<symbol>kde/kdelibs</symbol> since the full part <quote>kdelibs</quote> is what
+is compared).</para>
+
 <tip><para>See also <xref linkend="example-ignoring-a-module"/>.</para></tip>
 
 <para>This option was introduced with &kdesrc-build; 1.16.</para>