[sdk/kdesrc-build/docbook_historied_per_file] doc/cmdline: Merge kdesrc-build --run and kdesrc-run

Git commit 9113a2a9a8b27dd9f70e812fa958367cfa9dcec6 by Andrew Shark.
Committed on 17/02/2024 at 17:50.
Pushed by ashark into branch 'docbook_historied_per_file'.

Merge kdesrc-build --run and kdesrc-run

This fixes multiple issues with kdesrc-run and kdesrc-build --run

When using the --run parameter, the environment variables of global module were applied (from set-env options). But this is incorrect, since global cannot be treated as usual module. Its build system is defined as generic. In its prepareModuleBuildEnvironment these variables were setted:
- PKG_CONFIG_PATH
- LD_LIBRARY_PATH
- PATH
They have nothing to do with launched module's variables, except PATH, but even that was because of global install-dir matches the module's install-dir in most cases.

The kdesrc-run did sourced module's prefix.sh instead (located in its build-dir). That setted the following variables:
- PATH (the correct, from module)
- XDG_DATA_DIRS
- XDG_CONFIG_DIRS
- QT_PLUGIN_PATH
- QML2_IMPORT_PATH
- QT_QUICK_CONTROLS_STYLE_PATH

This commit fixes the broken behavior of --run, and the broken behavior of kdesrc-run.

Fixes: #145
Fixes: #114

Other fixes:
- Now the parameters after --run that starts with minuses are passed to the start-program, and not considered as options of kdesrc-build
- When setting parameters to the runned executable, they are actually applied. Previously the run script surrounded the $@ in the quotes.
- Fixed indentation and unnecessary semicolons in executable script.
- Made more clear note information when launching. The debug level controls if it will be displayed.

Original commit: 301b9b4c
https://invent.kde.org/sdk/kdesrc-build/-/commit/301b9b4caf1b84bf2e14bd616fec06683f5a2d18

M  +3    -23   doc/cmdline/supported-cmdline-params.docbook

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

diff --git a/doc/cmdline/supported-cmdline-params.docbook b/doc/cmdline/supported-cmdline-params.docbook
index fb02d2d3..2a8014b6 100644
--- a/doc/cmdline/supported-cmdline-params.docbook
+++ b/doc/cmdline/supported-cmdline-params.docbook
@@ -59,31 +59,11 @@ a few).
 </varlistentry>
 
 <varlistentry id="cmdline-run">
-<term><option><link linkend="cmdline-run">--run</link></option> (or <option>--start-program</option>) <parameter>program [parameters ...]</parameter></term>
+<term><option><link linkend="cmdline-run">--run</link></option> (or <option>--start-program</option>) [-e|--exec name] [-f|--fork] <parameter>program [parameters ...]</parameter></term>
 <listitem><para>
 This option interprets the next item on the command line as a program to run,
-and &kdesrc-build; will then finish reading the configuration file, update the
-environment as normal, and then execute the given program.</para>
-
-<para>This will not work to start a shell with the &kdesrc-build; environment
-in most cases however, since interactive shells typically reset at least part
-of the environment variables (such as <envar>PATH</envar> and
-${install-dir}) in the startup sequence.
-</para>
-
-<tip><para>If you want to see the environment used by &kdesrc-build;, you
-can run the <command>printenv</command> command:</para>
-<informalexample>
-<screen>$ <command>kdesrc-build</command> <parameter>--run</parameter> <parameter>printenv</parameter>
-KDE_SESSION_VERSION=4
-SDL_AUDIODRIVER=alsa
-LANGUAGE=
-XCURSOR_THEME=Oxygen_Blue
-LESS=-R -M --shift 5
-QMAIL_CONTROLDIR=/var/qmail/control
-... etc.
-</screen>
-</informalexample></tip>
+and &kdesrc-build; will then finish reading the configuration file, source the
+prefix.sh to apply environment variables, and then execute the given program.</para>
 </listitem>
 </varlistentry>