[sdk/kdesrc-build/docbook_historied_per_file] doc: Use XDG_STATE_HOME for persistent data file

Git commit 23df6e04c36ac3b92e726852e5165906bb324c8d by Ignacy Kajdan.
Committed on 21/01/2022 at 17:40.
Pushed by ashark into branch 'docbook_historied_per_file'.

Use XDG_STATE_HOME for persistent data file

Original commit: 4a2c0a8f
https://invent.kde.org/sdk/kdesrc-build/-/commit/4a2c0a8fe776490fde92bec120bfae51d9e9c982

M  +5    -3    doc/cmdline/supported-cmdline-params.docbook
M  +17   -13   doc/getting-started/before-building.docbook
M  +10   -7    doc/getting-started/configure-data.docbook
M  +26   -15   doc/kdesrc-buildrc/conf-options-table.docbook
M  +57   -7    doc/using-kdesrc-build/advanced-features.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/23df6e04c36ac3b92e726852e5165906bb324c8d

diff --git a/doc/cmdline/supported-cmdline-params.docbook b/doc/cmdline/supported-cmdline-params.docbook
index 25c4f8cc..75c2c452 100644
--- a/doc/cmdline/supported-cmdline-params.docbook
+++ b/doc/cmdline/supported-cmdline-params.docbook
@@ -496,9 +496,11 @@ This option was added with &kdesrc-build; 1.16. See also the
 <listitem><para>
 This interprets the next command line parameter as the file to read the
 configuration options from. The default value for this parameter is
-<filename>kdesrc-buildrc</filename> (checked in the current directory) if
-it is present, or <filename>~/.kdesrc-buildrc</filename> otherwise. See
-also <xref linkend="kdesrc-buildrc" />.
+<filename>kdesrc-buildrc</filename> (checked in the current working directory).
+If this file doesn't exist, <filename>~/.config/kdesrc-buildrc</filename>
+(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if
+<envar>$XDG_CONFIG_HOME</envar> is set) will be used instead. See also
+<xref linkend="kdesrc-buildrc"/>.
 </para></listitem>
 </varlistentry>
 
diff --git a/doc/getting-started/before-building.docbook b/doc/getting-started/before-building.docbook
index d6920929..b4853081 100644
--- a/doc/getting-started/before-building.docbook
+++ b/doc/getting-started/before-building.docbook
@@ -151,15 +151,17 @@ without having to fully specify its path every time.</para></tip>
 <sect3 id="setup-rcfile">
 <title>Prepare the configuration file</title>
 
-<para>&kdesrc-build; uses a <link linkend="configure-data">configuration
-file</link> (located at <filename>~/.kdesrc-buildrc</filename>) to control
-which modules are built, where they are installed to, etc.</para>
+<para>&kdesrc-build; uses a <link linkend="configure-data">configuration file</link>
+to control which modules are built, where they are installed to, etc.
+This file is located at <filename>~/.config/kdesrc-buildrc</filename>
+(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if
+<envar>$XDG_CONFIG_HOME</envar> is set).</para>
 
 <para>You can use a program included with &kdesrc-build;, called
 <application>kdesrc-build-setup</application> in order to prepare a simple
 kdesrc-build configuration. You can then edit the
-<filename>~/.kdesrc-buildrc</filename> from there to make any changes you see
-fit.</para>
+<filename>~/.config/kdesrc-buildrc</filename> configuration file to make
+any changes you see fit.</para>
 
 <para><application>kdesrc-build-setup</application> itself runs from a terminal
 (instead of using a graphical interface), just like &kdesrc-build;, so you can
@@ -169,17 +171,19 @@ use it even if you have no graphical interface available yet.</para>
 <title>Manual setup of configuration file</title>
 
 <para>You can also setup your configuration file manually, by copying the
-included sample configuration file
-<filename>kdesrc-buildrc-kf5-sample</filename> to
-<filename>~/.kdesrc-buildrc</filename> and then editing the file.  <xref
-linkend="kdesrc-buildrc"/> will be a useful reference for this, especially its
-<link linkend="conf-options-table">table of configuration options</link>.
+included sample configuration file <filename>kdesrc-buildrc-kf5-sample</filename>
+to <filename>~/.config/kdesrc-buildrc</filename> and then editing the file.
+<xref linkend="kdesrc-buildrc"/> will be a useful reference for this, especially
+its <link linkend="conf-options-table">table of configuration options</link>.
 </para>
 
 <para>&kdesrc-build; contains many recommended configuration files to support
-&kde; Frameworks 5, &plasma; 5, and other &kde; applications.  The <application>kdesrc-build-setup</application> refers to these files in the configuration file it generates, but you can also use them
-yourself.  See <xref linkend="kdesrc-buildrc-including"/> for information on how
-to use other configuration files from your own <filename>~/.kdesrc-buildrc</filename>.</para>
+&kde; Frameworks 5, &plasma; 5, and other &kde; applications. The
+<application>kdesrc-build-setup</application> refers to these files in the
+configuration file it generates, but you can also use them yourself. See
+<xref linkend="kdesrc-buildrc-including"/> for information on how to use other
+configuration files from your own <filename>kdesrc-buildrc</filename>.
+</para>
 
 <para>You can find more information about the syntax of the <link
 linkend="configure-data">configuration file</link> in <xref
diff --git a/doc/getting-started/configure-data.docbook b/doc/getting-started/configure-data.docbook
index 5643e977..4ce65d40 100644
--- a/doc/getting-started/configure-data.docbook
+++ b/doc/getting-started/configure-data.docbook
@@ -2,15 +2,18 @@
 <title>Setting the Configuration Data</title>
 
 <para>
-To use &kdesrc-build;, you should have a file in your home directory called
-<filename>.kdesrc-buildrc</filename>, which sets the general options and sets the modules
-you would like to download and build.
+To use &kdesrc-build;, you should have a file in your <filename>~/.config</filename>
+(or in <envar>$XDG_CONFIG_HOME</envar>, if set) directory called
+<filename>kdesrc-buildrc</filename>, which sets the general options and
+specifies the modules you would like to download and build.
 </para>
 
-<note><para>It is possible to use different configuration files for &kdesrc-build;,
-which is described in <xref linkend="kdesrc-buildrc" />. If you need to use
-multiple configurations, please see that section. Here, we will assume the
-configuration is stored in <filename>~/.kdesrc-buildrc</filename>.</para></note>
+<note><para>
+It is possible to use different configuration files for &kdesrc-build;, which is
+described in <xref linkend="kdesrc-buildrc" />. If you need to use multiple
+configurations, please see that section. Here, we will assume that the
+configuration is stored in <filename>~/.config/kdesrc-buildrc</filename>.
+</para></note>
 
 <para>
 The easiest way to proceed is to use the
diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index 64230a63..379cfa80 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -214,9 +214,16 @@ change at all.</para></important>
 <row id="conf-checkout-only">
 <entry>checkout-only</entry>
 <entry>Module setting overrides global</entry>
-<entry><para>This option was removed in January 2022. It used to control
-the ability to checkout subsets of a module from a Subversion repository.</para>
-</entry>
+<entry><para>Set this option to checkout &subversion; sources piece by piece. The
+value for this option should be a space-separated list of directories to
+checkout.  Although this option overrides the global option, be aware that
+setting this as a global option makes no sense.
+</para>
+
+<para>Note that this setting has no effect on &git; modules due to the
+operation of the &git; source control system.</para>
+
+<para>See <xref linkend="checking-out-parts"/> for an example.</para></entry>
 </row>
 
 <row id="conf-cmake-generator">
@@ -405,13 +412,13 @@ for every module. You can disable this check by setting
 <entry><para>Use this option to select a specific set of directories not to be built in a
 module (instead of all of them). The directories not to build should be space-separated.</para>
 
-<para>Note that the sources to the programs will still be downloaded.</para>
+<para>Note that the sources to the programs will still be downloaded. You can use
+the <link linkend="conf-checkout-only">checkout-only</link>
+directive to choose directories that you want to check out.</para>
 
-<para>For example, to disable building the <literal>codeeditor</literal> and <literal>minimaltest</literal>
-directories of the <literal>syntaxhighlighting</literal> framework, you
-would add <userinput>do-not-compile codeeditor minimaltest</userinput>
-compiling, you would add "do-not-compile juk kscd" to your syntaxhighlighting
-options.</para>
+<para>For example, to hold &juk; and &kscd; in the kdemultimedia module from
+compiling, you would add "do-not-compile juk kscd" to your kdemultimedia
+settings.</para>
 
 <para>See <xref linkend="not-compiling"/> for an example.</para>
 </entry>
@@ -1025,12 +1032,16 @@ cannot figure out what you mean using <link linkend="conf-branch">branch</link>.
 <row id="conf-persistent-data-file">
 <entry>persistent-data-file</entry>
 <entry>Cannot be overridden</entry>
-<entry><para>Use this option to change where &kdesrc-build; stores its persistent
-data. The default is to store this data in a file called
-<filename>.kdesrc-build-data</filename> placed in the same directory as the
-configuration file in use. If you have multiple available configurations in the
-same directory you may want to manually set this option so that the different
-configurations do not end up with conflicting persistent data.</para>
+<entry><para>Use this option to change where &kdesrc-build; stores its
+persistent data. The default is to store this data in a file called
+<filename>.kdesrc-build-data</filename>, placed in the same directory as the
+configuration file in use. If the global configuration file is in use, it will
+be saved to <filename>~/.local/state/kdesrc-build-data</filename>
+(<filename>$XDG_STATE_HOME/kdesrc-build-data</filename>, if
+<envar>$XDG_STATE_HOME</envar> is set). If you have multiple available
+configurations in the same directory, you may want to manually set this option,
+so that different configurations do not end up with conflicting persistent data.
+</para>
 
 <para>This option was added with &kdesrc-build; 1.15.</para>
 </entry>
diff --git a/doc/using-kdesrc-build/advanced-features.docbook b/doc/using-kdesrc-build/advanced-features.docbook
index 6c41cc2e..45e73a44 100644
--- a/doc/using-kdesrc-build/advanced-features.docbook
+++ b/doc/using-kdesrc-build/advanced-features.docbook
@@ -9,19 +9,69 @@ has features to make this easy. There are several complementing ways to
 do this.
 </para>
 
+<sect3 id="checking-out-parts">
+<title>Checking out portions of a module</title>
+
+<para>This is perhaps the best way to do this. When it works, it will save you
+download time and disk space. What happens is that &kdesrc-build; will download
+only the parts of a module that you specify. This is done using the &checkout-only;
+option for a module, which will specify a list of directories to download.
+</para>
+
+<tip><para>
+If you do not already know what to download from a module, it may be a good idea
+to browse the &subversion; layout for a module first, using
+<ulink url="https://websvn.kde.org/branches/KDE/4.6/">WebSVN</ulink>. <!--FIXME outdated-->
+</para></tip>
+
+<informalexample>
+<para>To only grab &kuser; and <application>KSystemLog</application> from
+kdeadmin, you could use &checkout-only; like this:</para>
+
+<screen>
+module <replaceable>kdeadmin</replaceable>
+  &checkout-only; <replaceable>kuser ksystemlog</replaceable>
+end module
+</screen>
+
+</informalexample>
+
+<important><para>The directories will be built in the order they are listed
+in the option. If one of the directories needs something else from the module
+to compile, then you need to make sure they are both in the &checkout-only;
+line, and that the required dependency goes before the directory that needs it.</para>
+
+<para>Also, sometimes an application may need other directories and it is hard
+to figure out what they are, which may require some trial and error of constantly
+adding directories to the option to figure out. This option depends on support
+from the build system of the module, so it is only useful for modules that are
+collections of individual applications.</para>
+</important>
+
+<para>One final note to make about this option: If you change the value of this
+option, you should use <userinput><command>kdesrc-build</command>
+<option>&cmd-refresh-build;</option> <option><replaceable>module</replaceable></option></userinput>
+in order to ensure that the module is reconfigured properly. In addition,
+&kdesrc-build; will never remove existing files if you take away the number of
+directories from your &checkout-only; option, or add the option to a module that
+has already been checked out.</para>
+
+</sect3>
+
 <sect3 id="not-compiling">
 <title>Removing directories from a build</title>
-<para>It is possible to download an entire repository
-but have the build system leave out a few directories when it does
-the build. This requires that the module uses &cmake; and that the
-module's build system allows the directory to remove to be
-optional.
+<para>Instead of restricting what is downloaded, it is possible to download
+everything but have the build system leave out a few directories when it does
+the build. This may be useful if one directory always breaks and is
+unnecessary to the rest of the module.
 </para>
 
-<para>This is controlled with the &do-not-compile; option.</para>
+<para>This is controlled with the &do-not-compile; option. It works similar
+to the &checkout-only; option just described, in that it is simply a list of
+directories that should not be compiled.</para>
 
 <important><para>
-This option requires at least that the
+Also like &checkout-only;, this option requires at least that the
 build system for the module is reconfigured after changing
 it. This is done using the <userinput><command>kdesrc-build</command>
 <option>&cmd-reconfigure;</option>