[sdk/kdesrc-build/docbook_historied_per_file] doc: Update documentation to cover CMake toolchain support.

[Johan Ouwerkerk]

Git commit 93cc3d80fb35cc1ac410c8b5fc2ff016ba5fd4aa by Johan Ouwerkerk.
Committed on 12/01/2020 at 18:58.
Pushed by ashark into branch 'docbook_historied_per_file'.

Update documentation to cover CMake toolchain support.

Original commit: 2cd07365
https://invent.kde.org/sdk/kdesrc-build/-/commit/2cd07365db50bff54419d84909df01b268ccfaef

M  +3    -1    doc/features/features-overview.docbook
M  +23   -0    doc/kdesrc-buildrc/conf-options-table.docbook
M  +4    -0    doc/using-kdesrc-build/basic-features.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/93cc3d80fb35cc1ac410c8b5fc2ff016ba5fd4aa

diff --git a/doc/features/features-overview.docbook b/doc/features/features-overview.docbook
index 41c1cb1c..57f5982b 100644
--- a/doc/features/features-overview.docbook
+++ b/doc/features/features-overview.docbook
@@ -64,7 +64,9 @@ for specific modules as well.</para>
 
 <para>Also, &kdesrc-build; will <link linkend="kdesrc-build-std-flags">add
 standard flags</link> as appropriate to save you the trouble and possible
-errors from typing them yourself.
+errors from typing them yourself. Nota Bene: this does not apply when a (custom)
+toolchain is configured through e.g.:
+<link linkend="conf-cmake-toolchain">cmake-toolchain</link>
 </para></listitem>
 
 <listitem><para>
diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index b3ab4420..78fe34a0 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -240,6 +240,23 @@ unset. If not set <literal>Unix Makefiles</literal> will be used by default.
 value for <literal>cmake-generator</literal>.</para></entry>
 </row>
 
+<row id="conf-cmake-toolchain">
+<entry>cmake-toolchain</entry>
+<entry>Module setting overrides global</entry>
+<entry><para>Use this option to specify a toolchain file to use with &cmake;.
+</para>
+<para>When a valid toolchain file is configured, &kdesrc-build; will
+<emphasis>no longer set environment variables automatically</emphasis>.
+You can use &set-env;, &binpath; and &libpath; to fix up the environment
+manually if your toolchain file does not work out of the box with
+&kdesrc-build;. Refer to <link linkend="kdesrc-build-std-flags">the overview
+of standard flags added by &kdesrc-build;</link> for more information.
+</para>
+<para>Note that if a valid toolchain is also specified through
+<link linkend="conf-cmake-options">cmake-options</link> it will override the
+value for <literal>cmake-toolchain</literal>.</para></entry>
+</row>
+
 <row id="conf-cmake-options">
 <entry>cmake-options</entry>
 <entry>Appends to global options for the default buildsystem, overrides global
@@ -259,6 +276,12 @@ override the value of
 (unsupported) generators are ignored and will not be passed to &cmake;.
 </para>
 
+<para>If a valid toolchain file is specified among the listed options it will
+override the value of
+<link linkend="conf-cmake-toolchain">cmake-toolchain</link>. Invalid
+toolchains are ignored and will not be passed to &cmake;.
+</para>
+
 <para>Since these options are passed directly to the &cmake; command line, they
 should be given as they would be typed into &cmake;. For example:</para>
 
diff --git a/doc/using-kdesrc-build/basic-features.docbook b/doc/using-kdesrc-build/basic-features.docbook
index efb8822b..44f51d5a 100644
--- a/doc/using-kdesrc-build/basic-features.docbook
+++ b/doc/using-kdesrc-build/basic-features.docbook
@@ -48,6 +48,10 @@ like to build a different branch).</para>
 
 <sect2 id="kdesrc-build-std-flags">
 <title>Standard flags added by &kdesrc-build;</title>
+<para>Nota Bene: this section does not apply to modules for which you have
+configured a custom toolchain, using e.g.
+<link linkend="conf-cmake-toolchain">cmake-toolchain</link>.</para>
+
 <para>To save you time, &kdesrc-build; adds some standard paths to your
 environment for you:
 </para>