[sdk/kdesrc-build/docbook_historied_per_file] doc: Add (and document) a --query flag, to print information about modules.

[Michael Pyne]

Git commit 79ba8ad94a3d673d4460e897d23d14b011b8fd13 by Michael Pyne.
Committed on 03/05/2016 at 00:46.
Pushed by ashark into branch 'docbook_historied_per_file'.

Add (and document) a --query flag, to print information about modules.

This still takes too long for most shell shortcuts, but will make it
possible to do things like setup shell functions to cd right to a build
dir based only on a module name, check for which git branch a module is
resolved to, or see what config file options a module ended up falling
under.

As part of the documentation changes, I also ported the docs to KF5.

Original commit: 6ce561cb
https://invent.kde.org/sdk/kdesrc-build/-/commit/6ce561cb46fd9b03da6ff1c1fb0c4c46f8b51a0c

M  +60   -0    doc/cmdline/supported-cmdline-params.docbook
M  +5    -4    doc/index.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/79ba8ad94a3d673d4460e897d23d14b011b8fd13

diff --git a/doc/cmdline/supported-cmdline-params.docbook b/doc/cmdline/supported-cmdline-params.docbook
index 98fb5cf4..8de712b2 100644
--- a/doc/cmdline/supported-cmdline-params.docbook
+++ b/doc/cmdline/supported-cmdline-params.docbook
@@ -241,6 +241,66 @@ doing in debugging mode.
 </para></listitem>
 </varlistentry>
 
+<varlistentry id="cmdline-query">
+<term><parameter>--query</parameter>=<userinput><replaceable>mode</replaceable></userinput></term>
+<listitem><para>
+This command causes &kdesrc-build; to query a parameter of the modules in the
+build list (either passed on the command line or read in from the configuration
+file), outputting the result to screen (one module per line).</para>
+
+<para>This option must be provided with a <quote>query mode</quote>, which should be
+one of the following:</para>
+    <itemizedlist>
+    <listitem><para><option>source-dir</option>, which causes &kdesrc-build; to
+        output the full path to where the module's source code is stored.
+        </para></listitem>
+    <listitem><para><option>build-dir</option>, which causes &kdesrc-build; to
+        output the full path to where the module build process occurs.
+        </para></listitem>
+    <listitem><para><option>install-dir</option>, which causes &kdesrc-build; to
+        output the full path to where the module will be installed.
+        </para></listitem>
+    <listitem><para><option>project-path</option>, which causes &kdesrc-build; to
+        output the location of the module within the hierarchy of KDE source
+        code repositories. See <xref linkend="kde-projects-module-sets"/> for
+        more information on this hierarchy.
+        </para></listitem>
+    <listitem><para><option>branch</option>, which causes &kdesrc-build; to
+        output the resolved git branch that will be used for each module, based
+        on the <link linkend="conf-tag">tag</link>, <link
+        linkend="conf-branch">branch</link> and <link
+        linkend="conf-branch-group">branch-group</link> settings in effect.
+        </para></listitem>
+    <listitem><para>Otherwise, option names that are valid for modules in the
+        <link linkend="conf-options-table">configuration file</link> can be
+        used, the resolved value of which will be listed for each module.
+        </para></listitem>
+    </itemizedlist>
+
+<para>
+If a single module is passed on the command line, then the output is simply the
+value of the parameter being queried. If multiple (or no) modules are passed on
+the command line, then each line is prefixed by the name of the module. Either way,
+&kdesrc-build; stops running once each value is output.
+</para>
+
+<para>This option was added with &kdesrc-build; 16.05.</para>
+
+<informalexample>
+<para>For example, the command <quote><command>kdesrc-build</command>
+    <parameter>--query</parameter>
+    <parameter><replaceable>branch</replaceable></parameter>
+    <parameter><replaceable>kactivities</replaceable></parameter>
+    <parameter><replaceable>kdepim</replaceable></parameter></quote>
+might end up with output like:</para>
+<screen>
+kactivities: master
+kdepim: master
+</screen>
+</informalexample>
+</listitem>
+</varlistentry>
+
 <varlistentry id="cmdline-no-rebuild-on-fail">
 <term><parameter>--no-rebuild-on-fail</parameter></term>
 <listitem><para>
diff --git a/doc/index.docbook b/doc/index.docbook
index 0f3a060a..e65ab3c7 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
-<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
   <!--
     Documentation for kdesrc-build.
-    Copyright (c) 2005-2008, 2010-2015 Michael Pyne <mpyne at kde.org>
+    Copyright (c) 2005-2008, 2010-2016 Michael Pyne <mpyne at kde.org>
 
     Copyright (c) 2005 Carlos Leonhard Woelz <carloswoelz at imap-mail.com>
     Copyright (c) 2009 Burkhard Lück <lueck at hube-lueck.de>
@@ -132,6 +132,7 @@
 <year>2013</year>
 <year>2014</year>
 <year>2015</year>
+<year>2016</year>
 <holder>Michael Pyne</holder>
 </copyright>
 
@@ -142,8 +143,8 @@
 
 <legalnotice>&FDLNotice;</legalnotice>
 
-<date>2015-09-12</date>
-<releaseinfo>15.09</releaseinfo>
+<date>2016-05-02</date>
+<releaseinfo>16.05</releaseinfo>
 
 <abstract>
 <para>&kdesrc-build; is a script which builds and installs &kde; software