[sdk/kdesrc-build/docbook_historied_per_file] doc/kdesrc-buildrc: Add install-environment-driver option.

[Michael Pyne]

Git commit e99c4233335312718bc37933afb2b9071c52d99d by Michael Pyne.
Committed on 30/07/2017 at 19:02.
Pushed by ashark into branch 'docbook_historied_per_file'.

Add install-environment-driver option.

This installs needed KDE-related environment settings without going so
far as to install .xsession support.  For that, see
install-session-driver, whose documentation has been fixed to make clear
it's not a default.

Original commit: 9031e6c8
https://invent.kde.org/sdk/kdesrc-build/-/commit/9031e6c85fddb12ebf4965eb317920e009159188

M  +36   -2    doc/kdesrc-buildrc/conf-options-table.docbook

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

diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index 9d47397f..a843d050 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -594,10 +594,43 @@ flag.
 </entry>
 </row>
 
+<row id="conf-install-environment-driver">
+<entry>install-environment-driver</entry>
+<entry>Cannot be overridden</entry>
+<entry><para>By default, &kdesrc-build; will install a shell script that can be
+sourced in a user's profile setup scripts to easily establish needed environment
+variables to run the Plasma desktop built by &kdesrc-build;.</para>
+
+<para>This driver will alter the following files:</para>
+
+<itemizedlist>
+<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-master.sh</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem>
+<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-user.sh</filename> (normally found at <filename>~/.config/kde-env-user.sh</filename>).</para></listitem>
+</itemizedlist>
+
+<para>The <filename>kde-env-user.sh</filename> is optional.  It is
+intended for user customizations (see the <ulink url="https://userbase.kde.org/KDE_System_Administration/Environment_Variables#Troubleshooting_and_Debugging">Troubleshooting and Debugging</ulink>
+section of the &kde; UserBase for examples of customizable settings), but these settings
+can be set elsewhere by the user in their existing profile setup scripts.</para>
+
+<para>You can disable this feature by setting this option to
+<replaceable>false</replaceable>, and ensuring that the <link
+linkend="conf-install-session-driver">install-session-driver</link> option is
+also disabled.</para>
+
+<para>This option was introduced with &kdesrc-build; 17.08.</para>
+
+<tip><para>&kdesrc-build; will not overwrite your existing files (if present)
+unless you also pass the <option><link
+linkend="cmdline-delete-my-settings">--delete-my-settings</link></option>
+command-line option.</para></tip>
+</entry>
+</row>
+
 <row id="conf-install-session-driver">
 <entry>install-session-driver</entry>
 <entry>Cannot be overridden</entry>
-<entry><para>By default, &kdesrc-build; will try to install a driver for the graphical
+<entry><para>If enabled, &kdesrc-build; will try to install a driver for the graphical
 login manager that allows you to login to your &kdesrc-build;-built &kde; desktop.</para>
 
 <para>This driver will alter the following files:</para>
@@ -609,7 +642,8 @@ login manager that allows you to login to your &kdesrc-build;-built &kde; deskto
 </itemizedlist>
 
 <para>If you maintain your own login driver then you can disable this feature by setting this
-option to <replaceable>false</replaceable>.</para>
+option to <replaceable>false</replaceable>.  If enabled, this feature also enables the
+<link linkend="conf-install-environment-driver">install-environment-driver</link> feature.</para>
 
 <para>This option was introduced with &kdesrc-build; 1.16.</para>