[sdk/kdesrc-build/docbook_historied_per_file] doc: kde-projects: Support ignoring given implicit modules.

[Michael Pyne]

Git commit 7f29b5ab2f987ad9e0e89c6a1da4049479339a4d by Michael Pyne.
Committed on 10/02/2013 at 02:30.
Pushed by ashark into branch 'docbook_historied_per_file'.

kde-projects: Support ignoring given implicit modules.

It's kind of annoying to be unable to build all modules in a certain
kde-projects module grouping, *except* for some certain chosen ones.

Now you can: You can add the ignore-modules option in your module-sets
using kde-projects repository.

It accepts a space-separated list of module names (either kdefoo or
kde/module/kdefoo style) to ignore.

Although the intention is to only filter out matching modules in *that*
module-set, it would actually perform the filtering even if you
accidentally put it in the wrong module set due to a fluke of the
implementation (I recommend not relying on this, however).

The documentation has also been updated, including an example of the
usage.

Original commit: 1d769408
https://invent.kde.org/sdk/kdesrc-build/-/commit/1d76940879043865cd1e442c6a0f5acafe1eb1ba

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

https://invent.kde.org/sdk/kdesrc-build/-/commit/7f29b5ab2f987ad9e0e89c6a1da4049479339a4d

diff --git a/doc/getting-started/kde-modules-and-selection.docbook b/doc/getting-started/kde-modules-and-selection.docbook
index 11d1b0f4..8bb6a6f2 100644
--- a/doc/getting-started/kde-modules-and-selection.docbook
+++ b/doc/getting-started/kde-modules-and-selection.docbook
@@ -292,10 +292,44 @@ because &kdesrc-build; will not perform dependency handling.
 </orderedlist>
 
 <note><para>It is worth nothing that &kdesrc-build; will try to build modules
-in the right order, but this depends on other databases being kept up-to-date.
-You can manually do the right thing if necessary by using the technique
-described above.
+in the right order, such as if only <literal>kdegraphics/*</literal> had been
+listed above, but this depends on other databases being kept up-to-date.  You
+can manually list modules in the proper order if necessary by using the
+technique described above.
 </para></note>
 </sect2>
 
+<sect2 id="ignoring-project-modules">
+<title>Filtering out &kde; project modules</title>
+
+<para>You might decide that you'd like to build all programs within a &kde;
+module grouping <emphasis>except</emphasis> for a given program.</para>
+
+<para>For instance, the <literal>kdeutils</literal> group includes a program
+named <application>kremotecontrol</application>. If your computer does not have
+the proper hardware to receive the signals sent by remote controls then you may
+decide that you'd rather not download, build, and install
+<application>kremotecontrol</application> every time you update
+<literal>kdeutils</literal>.</para>
+
+<para>As of &kdesrc-build; 1.16, you can achieve this by using the <link
+linkend="conf-ignore-modules">ignore-modules</link> configuration option.</para>
+
+<example id="example-ignoring-a-module">
+<title>Example for ignoring a kde-project module in a group</title>
+<programlisting>
+module-set <replaceable>utils</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>kdeutils</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
+</programlisting>
+</example>
+
+</sect2>
+
 </sect1>
diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index c42cbe8e..c7e6ffdb 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -425,6 +425,21 @@ on also use that proxy server, if possible, by setting the
 </entry>
 </row>
 
+<row id="conf-ignore-modules">
+<entry>ignore-modules</entry>
+<entry>Can't be overridden</entry>
+<entry><para>Modules named by this option, which would be chosen by &kdesrc-build;
+due to a <link linkend="conf-use-modules">use-modules</link> option, are
+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>
+
+<tip><para>See also <xref linkend="example-ignoring-a-module"/>.</para></tip>
+
+<para>This option was introduced with &kdesrc-build; 1.16.</para>
+</entry>
+</row>
+
 <row id="conf-install-after-build">
 <entry>install-after-build</entry>
 <entry>Module setting overrides global</entry>