[sdk/kdesrc-build/docbook_historied_per_file] doc/kdesrc-buildrc: doc: Improve rc-file layout documentation.

[Michael Pyne]

Git commit 7007b74dca24ce9aa44ee2d545ff1d3d92e59f34 by Michael Pyne.
Committed on 08/09/2011 at 02:15.
Pushed by ashark into branch 'docbook_historied_per_file'.

doc: Improve rc-file layout documentation.

Really this was mostly an excuse to document the new "include" feature.

Original commit: 2d0f0bf6
https://invent.kde.org/sdk/kdesrc-build/-/commit/2d0f0bf661aebb7f5ed487c7253fde1a38bc8790

M  +84   -14   doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/7007b74dca24ce9aa44ee2d545ff1d3d92e59f34

diff --git a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
index 33fe1c66..8db8c20f 100644
--- a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
+++ b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
@@ -7,8 +7,15 @@ To use the script, you must have a file in your home directory called
 like to download and build.
 </para>
 
+<sect2 id="kdesrc-buildrc-layout">
+<title>Layout of the configuration file</title>
+
+<sect3 id="kdesrc-buildrc-layout-global">
+<title>Global configuration</title>
+
 <para>
-It starts with the global options, specified like the following:
+The configuration file starts with the global options, specified like the
+following:
 </para>
 
 <programlisting>
@@ -18,24 +25,91 @@ global
 end global
 </programlisting>
 
+</sect3>
+<sect3 id="kdesrc-buildrc-layout-modules">
+<title>Module configuration</title>
+
 <para>
-It is then followed by one or more module sections, specified like the
-following:
+It is then followed by one or more module sections, specified in one of the
+following two forms:
 </para>
 
+<itemizedlist>
+<listitem>
 <programlisting>
 module <replaceable>module-name</replaceable>
 <replaceable>option-name option-value</replaceable>
 <replaceable>[...]</replaceable>
 end module
 </programlisting>
+</listitem>
+
+<listitem>
+<programlisting>
+module-set <replaceable>module-set-name</replaceable>
+  repository <userinput>kde-projects</userinput> or <userinput><replaceable>git://host.org/path/to/repo.git</replaceable></userinput>
+  use-modules <replaceable>module-names</replaceable>
+
+# Other options may also be set
+<replaceable>option-name option-value</replaceable>
+<replaceable>[...]</replaceable>
+end module-set
+</programlisting>
+</listitem>
+</itemizedlist>
+
+<important><para>Note that the second form, module sets, <emphasis>only works
+for Git-based modules</emphasis>.</para></important>
+
+<para>
+For Subversion modules, <replaceable>module-name</replaceable> must be a module
+from the &kde; &subversion; repository (for example, kdeartwork or
+kde-wallpapers), although it is possible to get around this if you manually
+specify the &subversion; URL.
+</para>
 
 <para>
-<replaceable>module-name</replaceable> must be a module from the &kde; &subversion; repository (for
-example, kdelibs or kdebase). Some options override global options, some
-add to global options, and some global options simply cannot be overridden.
+For Git modules, the module name can be essentially whatever you'd like, as
+long as it does not duplicate any other module name in the configuration. Keep
+in mind the source and build directory layout will be based on the module name
+if you do not use the <link linkend="conf-dest-dir">dest-dir</link> option.
 </para>
 
+<para>However, for Git <emphasis>module sets</emphasis> the
+<replaceable>module-names</replaceable> must correspond with actual git modules
+in the chosen <option>repository</option>. See <link
+linkend="conf-git-repository-base">git-repository-base</link> or <link
+linkend="conf-use-modules">use-modules</link> for more information.
+</para>
+
+</sect3>
+</sect2>
+
+<sect2 id="kdesrc-buildrc-including">
+<title>Including other configuration files</title>
+
+<para>
+Within the configuration file, you may reference other files by using the
+<literal>include</literal> keyword with a file, which will act as if the file
+referenced had been inserted into the configuration file at that point.
+</para>
+
+<informalexample><para>For example, you could have something like this:</para>
+<programlisting>
+global
+    include <replaceable>~/common-kdesrc-build-options</replaceable>
+
+    # Insert specific options here.
+
+end global
+</programlisting>
+</informalexample>
+
+</sect2>
+
+<sect2 id="kdesrc-buildrc-common">
+<title>Commonly used configuration options</title>
+
 <para>
 The following is a list of commonly-used options. Click on the
 option to find out more about it. To see the full list of options, see
@@ -43,18 +117,14 @@ option to find out more about it. To see the full list of options, see
 </para>
 
 <itemizedlist>
-<listitem><para><link linkend="conf-branch">branch</link>, to checkout from a branch instead of /trunk.</para></listitem>
-<listitem><para><link linkend="conf-build-dir">build-dir</link>, to set the directory to build in.</para></listitem>
 <listitem><para><link linkend="conf-cmake-options">cmake-options</link> to define what flags to configure a module with using &cmake;.</para></listitem>
-<listitem><para><link linkend="conf-configure-flags">configure-flags</link> to define what flags to configure a module with.</para></listitem>
-<listitem><para><link linkend="conf-cxxflags">cxxflags</link> to define the <envar>CXXFLAGS</envar> variable.</para></listitem>
+<listitem><para><link linkend="conf-branch">branch</link>, to checkout from a branch instead of /trunk (for &subversion;) or <literal>master</literal> (for Git).</para></listitem>
+<listitem><para><link linkend="conf-configure-flags">configure-flags</link> to define what flags to configure &Qt; with.</para></listitem>
 <listitem><para><link linkend="conf-kdedir">kdedir</link>, to set the directory to install &kde; to.</para></listitem>
-<listitem><para><link linkend="conf-kde-languages">kde-languages</link>, to set the translation packages to download and install.</para></listitem>
-<listitem><para><link linkend="conf-make-options">make-options</link>, to pass options to the &make; program.</para></listitem>
+<listitem><para><link linkend="conf-make-options">make-options</link>, to pass options to the &make; program (such as number of CPUs to use).</para></listitem>
 <listitem><para><link linkend="conf-qtdir">qtdir</link>, to set the path to &Qt;.</para></listitem>
-<listitem><para><link linkend="conf-set-env">set-env</link>, to set an environment variable.</para></listitem>
 <listitem><para><link linkend="conf-source-dir">source-dir</link>, to change where to download the source code to.</para></listitem>
-<listitem><para><link linkend="conf-svn-server">svn-server</link>, to change the server the sources are downloaded from.</para></listitem>
 </itemizedlist>
 
+</sect2>
 </sect1>