[sdk/kdesrc-build/docbook_historied_per_file] doc: doc: Document xsession changes.

Git commit 6e9e91ac2977b4188e33db228e9e794bda2fdfb6 by Michael Pyne.
Committed on 19/11/2012 at 01:14.
Pushed by ashark into branch 'docbook_historied_per_file'.

doc: Document xsession changes.

Original commit: fb5bd6fc
https://invent.kde.org/sdk/kdesrc-build/-/commit/fb5bd6fc33e2c8e1519927780afe3ba8633f1bbf

M  +1    -2    doc/appendix-modules/index.docbook
A  +6    -0    doc/appendix-profile/index.docbook
C  +11   -9    doc/appendix-profile/old-profile-setup.docbook [from: doc/getting-started/environment.docbook - 090% similarity]
M  +26   -0    doc/cmdline/supported-cmdline-params.docbook
M  +115  -153  doc/getting-started/environment.docbook
M  +1    -1    doc/getting-started/kde-modules-and-selection.docbook
M  +4    -0    doc/index.docbook
M  +26   -0    doc/kdesrc-buildrc/conf-options-table.docbook

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

diff --git a/doc/appendix-modules/index.docbook b/doc/appendix-modules/index.docbook
index 0adaebcd..a93a825b 100644
--- a/doc/appendix-modules/index.docbook
+++ b/doc/appendix-modules/index.docbook
@@ -1,5 +1,4 @@
-<appendix>
+<appendix id="appendix-modules">
 <title>&kde; modules and source code organization</title>
 &module-concept;
-
 </appendix>
diff --git a/doc/appendix-profile/index.docbook b/doc/appendix-profile/index.docbook
new file mode 100644
index 00000000..c5fcd59b
--- /dev/null
+++ b/doc/appendix-profile/index.docbook
@@ -0,0 +1,6 @@
+<appendix id="appendix-profile">
+<title>Superseded profile setup procedures</title>
+
+&old-profile-setup;
+
+</appendix>
diff --git a/doc/getting-started/environment.docbook b/doc/appendix-profile/old-profile-setup.docbook
similarity index 90%
copy from doc/getting-started/environment.docbook
copy to doc/appendix-profile/old-profile-setup.docbook
index 8cfb707c..e0781b2a 100644
--- a/doc/getting-started/environment.docbook
+++ b/doc/appendix-profile/old-profile-setup.docbook
@@ -1,12 +1,14 @@
-<sect1 id="environment">
-<title>Setting the Environment to Run Your Fresh &kde;</title>
-
-<para>
-Assuming you are using a dedicated user to build &kde;, and you already have
-an installed &kde; version, running your new &kde; may be a bit tricky, as the new &kde;
-has to take precedence over the old. Change the environment variables to
-make sure it does.
-</para>
+<sect1 id="old-profile-setup">
+<title>Setting up a &kde; login profile</title>
+
+<para>These instructions cover how to setup the profile required to ensure your
+computer can login to your newly-built &kde; &plasma; desktop. &kdesrc-build;
+will normally try to do this automatically (see <xref
+linkend="session-driver"/>). This appendix section can be useful for those who
+cannot use &kdesrc-build;'s support for login profile setup. However the
+instructions may not always be up-to-date, it can also be useful to consult the
+<filename>kde-env-master.sh</filename> file included with the &kdesrc-build;
+source.</para>
 
 <sect2 id="changing-profile">
 <title>Changing your startup profile settings</title>
diff --git a/doc/cmdline/supported-cmdline-params.docbook b/doc/cmdline/supported-cmdline-params.docbook
index 2c435608..cc2498ba 100644
--- a/doc/cmdline/supported-cmdline-params.docbook
+++ b/doc/cmdline/supported-cmdline-params.docbook
@@ -356,6 +356,32 @@ aid.</para></note>
 </listitem>
 </varlistentry>
 
+<varlistentry id="cmdline-delete-my-patches">
+<term><parameter>--delete-my-patches</parameter></term>
+<listitem><para>
+This option is used to let &kdesrc-build; delete source directories that may
+contain user data, so that the module can be re-downloaded. This would normally
+only be useful for &kde; developers (who might have local changes that would be
+deleted).</para>
+
+<para>This is currently only used to checkout modules that have been converted
+from &subversion; to &git;. You should not use this option normally,
+&kdesrc-build; will prompt to be re-run with it if it is needed.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-delete-my-settings">
+<term><parameter>--delete-my-settings</parameter></term>
+<listitem><para>
+This option is used to let &kdesrc-build; overwrite existing files which may contain
+user data.</para>
+
+<para>This is currently only used for xsession setup for the login manager. You
+should not use this option normally, &kdesrc-build; will prompt to be re-run
+with it if it is needed.</para>
+</listitem>
+</varlistentry>
+
 <varlistentry id="cmdline-global-option">
 <term><parameter>--&lt;option-name&gt;=</parameter></term>
 <listitem><para>
diff --git a/doc/getting-started/environment.docbook b/doc/getting-started/environment.docbook
index 8cfb707c..7e438b10 100644
--- a/doc/getting-started/environment.docbook
+++ b/doc/getting-started/environment.docbook
@@ -1,165 +1,127 @@
 <sect1 id="environment">
-<title>Setting the Environment to Run Your Fresh &kde;</title>
+<title>Setting the Environment to Run Your &kde; &plasma; Desktop</title>
 
 <para>
-Assuming you are using a dedicated user to build &kde;, and you already have
-an installed &kde; version, running your new &kde; may be a bit tricky, as the new &kde;
-has to take precedence over the old. Change the environment variables to
-make sure it does.
+Assuming you are using a dedicated user to build &kde;, and you already have an
+installed &kde; version, running your new &kde; may be a bit tricky, as the new
+&kde; has to take precedence over the old. You must change the environment
+variables of your login scripts to make sure the newly-built desktop is used.
 </para>
 
-<sect2 id="changing-profile">
-<title>Changing your startup profile settings</title>
-
-<important><para>The <filename>.bash_profile</filename> is the login settings
-file for the popular <application>bash</application> shell used by many &Linux;
-distributions. If you use a different shell, then you may need to adjust the
-samples given in this section for your particular shell.</para></important>
-
-<para>
-Open or create the <filename>.bash_profile</filename> file in the home directory with your favorite editor,
-and add to the end of the file:
-
-If you are building the qt module (you are by default), add instead:
-
-<programlisting>
-QTDIR=(path to qtdir)   # Such as ~/kdesrc/build/qt by default.
-KDEDIR=(path to kdedir) # Such as ~/kde by default.
-KDEDIRS=$KDEDIR
-PATH=$KDEDIR/bin:$QTDIR/bin:$PATH
-MANPATH=$QTDIR/doc/man:$MANPATH
-
-# Act appropriately if LD_LIBRARY_PATH is not already set.
-if [ -z $LD_LIBRARY_PATH ]; then
-  LD_LIBRARY_PATH=$KDEDIR/lib:$QTDIR/lib
-else
-  LD_LIBRARY_PATH=$KDEDIR/lib:$QTDIR/lib:$LD_LIBRARY_PATH
-fi
-
-export QTDIR KDEDIRS PATH MANPATH LD_LIBRARY_PATH
-</programlisting>
-
-or, if you are not building qt (and are using your system &Qt; instead), add
-this instead:
-
-<programlisting>
-KDEDIR=(path to kdedir)  # Such as ~/kde by default.
-KDEDIRS=$KDEDIR
-PATH=$KDEDIR/bin:$QTDIR/bin:$PATH
-
-# Act appropriately if LD_LIBRARY_PATH is not already set.
-if [ -z $LD_LIBRARY_PATH ]; then
-  LD_LIBRARY_PATH=$KDEDIR/lib
-else
-  LD_LIBRARY_PATH=$KDEDIR/lib:$LD_LIBRARY_PATH
-fi
-
-export KDEDIRS PATH LD_LIBRARY_PATH
-</programlisting>
-</para>
-
-<para>
-If you are not using a dedicated user, set a different $<envar>KDEHOME</envar>
-for your new environment in your <filename>.bash_profile</filename>:
-
-<programlisting>
-export KDEHOME="${HOME}/.kde-svn"
-
-# Create it if needed
-[ ! -e ~/.kde-svn ] &amp;&amp; mkdir ~/.kde-svn
-</programlisting>
-</para>
-
-<note>
-<para>
-If later your K Menu is empty or too crowded with applications from your
-distribution, you may have to set the <acronym>XDG</acronym> environment
-variables in your <filename>.bash_profile</filename>:
-
-<programlisting>
-XDG_CONFIG_DIRS="/etc/xdg"
-XDG_DATA_DIRS="${KDEDIR}/share:/usr/share"
-export XDG_CONFIG_DIRS XDG_DATA_DIRS
-</programlisting>
-
-</para>
-</note>
+<sect2 id="session-driver">
+<title>Automatically installing a login driver</title>
+
+<para>Starting from version 1.16, &kdesrc-build; will try to install an
+appropriate login driver, that will allow you to login to your
+&kdesrc-build;-built &kde; desktop from your login manager. This can be
+disabled by using the <option><link
+linkend="conf-install-session-driver">install-session-driver</link></option>
+configuration file option.</para>
+
+<note><para>Session setup does not occur while &kdesrc-build; is running
+in pretend mode.</para></note>
+
+<para>This driver works by setting up a custom <quote><literal>xsession</literal></quote>
+session type. This type of session should work by default with the &kdm; login
+manager (where it appears as a <quote>Custom</quote> session), but other login
+managers (such as <application>LightDM</application> and
+<application>gdm</application>) may require additional files installed to
+enable <literal>xsession</literal> support.</para>
+
+<sect3 id="xsession-distribution-setup">
+<title>Adding xsession support for distributions</title>
+
+<para>The default login managers for some distributions may require additional
+packages to be installed in order to support <literal>xsession</literal> logins.</para>
+
+<itemizedlist>
+<listitem><para>The <ulink url="http://fedoraproject.org/">Fedora</ulink>
+&Linux; distribution requires the <literal>xorg-x11-xinit-session</literal>
+package to be installed for custom <literal>xsession</literal> login
+support.</para></listitem>
+
+<listitem><para><ulink url="http://debian.org/">Debian</ulink> and
+Debian-derived &Linux; distributions should support custom
+<literal>xsession</literal> logins, but require the
+<option><userinput>allow-user-xsession</userinput></option> option to be set in
+<filename>/etc/X11/Xsession.options</filename>. See also the Debian <ulink
+url="http://www.debian.org/doc/manuals/debian-reference/ch07.en.html#_customizing_the_x_session_classic_method">documentation
+on customizing the X session.</ulink></para></listitem>
+
+<listitem><para>For other distributions, go to <xref
+linkend="xsession-manual-setup"/>.</para></listitem>
+</itemizedlist>
+
+</sect3>
+
+<sect3 id="xsession-manual-setup">
+<title>Manually adding support for xsession</title>
+
+<para>If there were no distribution-specific directions for your distribution
+in <xref linkend="xsession-distribution-setup"/>, you can manually add a
+<quote>Custom xsession login</quote> entry to your distribution's list of
+session types as follows:</para>
+
+<procedure id="proc-adding-xsession-type">
+<title>Adding an .xsession login session type.</title>
+
+<note><para>This procedure will likely require administrative privileges to
+complete.
+</para></note>
+
+<step performance="required">
+<para>Create the file
+<filename>/usr/share/xsessions/kdesrc-build.desktop</filename>.</para>
+</step>
+
+<step performance="required">
+<para>Ensure the file just created has the following text:</para>
+<literallayout><userinput>
+Type=XSession
+Exec=<co id="session-homedir"/><replaceable>$HOME</replaceable>/.xsession
+Name=KDE Plasma Desktop (unstable; kdesrc-build)
+</userinput></literallayout>
+
+<calloutlist>
+<callout arearefs="session-homedir"><para>
+The <replaceable>$HOME</replaceable> entry must be replaced by the full path to
+your home directory (example, <filename
+class="directory">/home/<replaceable>user</replaceable></filename>).  The
+desktop entry specification does not allow for user-generic files.
+</para></callout>
+
+</calloutlist>
+</step>
+
+<step performance="optional"><para>When the login manager is restarted, it
+should show a new session type, <quote>KDE Plasma Desktop (unstable;
+kdesrc-build)</quote> in its list of sessions, which should try to run the
+<filename>.xsession</filename> file installed by &kdesrc-build; if it is
+selected when you login.</para>
+
+<note><para>It may be easiest to restart the computer to restart the login
+manager, if the login manager does not track updates to the <filename
+class="directory">/usr/share/xsessions</filename> directory.</para></note>
+
+</step>
+
+</procedure>
+
+</sect3>
 
 </sect2>
-<sect2 id="starting-kde">
-<title>Starting &kde;</title>
-
-<para>
-Now that you have adjusted your environment settings to use the correct &kde;,
-it is important to ensure that the correct <command>startkde</command> script
-is used as well.
-</para>
-
-<para>
-Open the <filename>.xinitrc</filename> text file from the home directory, or
-create it if necessary. Add the line:
-
-<programlisting>
-<command>exec</command> <option>${KDEDIR}/bin/startkde</option>
-</programlisting>
-</para>
-
-<important><para>On some distributions, it may be necessary to perform the same
-steps with the <filename>.xsession</filename> file, also in the home directory.
-This is especially true when using graphical login managers such as
-&kdm;, <application>gdm</application>, or <application>xdm</application>.</para>
-</important>
-
-<para>
-Now start your fresh &kde;: in &BSD; and &Linux; systems with virtual terminal support,
-<keycombo action="simul">&Ctrl;&Alt;<keycap>F1</keycap></keycombo> ... <keycombo action="simul">&Ctrl;&Alt;<keycap>F12</keycap></keycombo> keystroke combinations are used to switch to Virtual Console 1 through 12.
-This allows you to run more than one desktop environment at the same time. The fist six are
-text terminals and the following six are graphical displays.
-</para>
-
-<para>
-If when you start your computer you are presented to the graphical display
-manager instead, you can use the new &kde; environment, even if it is not listed
-as an option. Most display managers, including &kdm;, have an option to use
-a <quote>Custom Session</quote> when you login. With this option, your session settings are
-loaded from the <filename>.xsession</filename> file in your home directory. If
-you have already modified this file as described above, this option should load
-you into your new &kde; installation.
-</para>
 
-<para>If it does not, there is something else you can try that should normally
-work: Press <keycombo action="simul">&Ctrl;&Alt;<keycap>F2</keycap></keycombo>,
-and you will be presented to a text terminal. Log in using the dedicated user
-and type:
-</para>
-
-<screen>
-<command>startx</command> <option>--</option> <option>:1</option>
-</screen>
+<sect2 id="old-profile-instructions">
+<title>Setting up the environment manually</title>
+<para>This documentation used to include instruction on which environment
+variables to set in order to load up the newly-built desktop. These
+instructions have been moved to an appendix (<xref
+linkend="old-profile-setup"/>).</para>
 
-<tip>
-<para>
-You can run the &kde; from sources and the old &kde; at the same time! Log in
-using your regular user, start the stable &kde; desktop. Press <keycombo
-action="simul">&Ctrl;&Alt;<keycap>F2</keycap></keycombo> (or
-<keycap>F1</keycap>, <keycap>F3</keycap>, etc..), and you will be presented
-with a text terminal. Log in using the dedicated &kde; &subversion; user and
-type:</para>
-
-<screen>
-<command>startx</command> <option>--</option> <option>:1</option>
-</screen>
-
-<para>You can go back to the &kde; desktop of your regular user by pressing the
-shortcut key for the already running desktop. This is normally
-<keycombo action="simul">&Ctrl;&Alt;<keycap>F7</keycap></keycombo>, you may need
-to use <keycap>F6</keycap> or <keycap>F8</keycap> instead. To return to your
-&kdesrc-build;-compiled &kde;, you would use the same sequence, except with the
-next function key. For example, if you needed to enter <keycombo action="simul">&Ctrl;&Alt;<keycap>F7</keycap></keycombo>
-to switch to your regular &kde;, you would need to enter
-<keycombo action="simul">&Ctrl;&Alt;<keycap>F8</keycap></keycombo> to go back
-to your &kdesrc-build; &kde;.</para>
-</tip>
+<para>If you intend to setup your own login support you can consult that
+appendix or view the <filename>sample-kde-env-master.sh</filename> file
+included with the &kdesrc-build; source.</para>
 
 </sect2>
+
 </sect1>
diff --git a/doc/getting-started/kde-modules-and-selection.docbook b/doc/getting-started/kde-modules-and-selection.docbook
index 11d1b0f4..67142d47 100644
--- a/doc/getting-started/kde-modules-and-selection.docbook
+++ b/doc/getting-started/kde-modules-and-selection.docbook
@@ -11,7 +11,7 @@ select the software modules that you want built.
 </para>
 
 <orderedlist>
-<listitem><para>At the lowest level comes Digia's &Qt; library, which is a
+<listitem><para>At the lowest level comes Nokia's &Qt; library, which is a
 very powerful, cross-platform <quote>toolkit</quote> library. &kde; is based on
 &Qt;, and some of the non-&kde; libraries required by &kde; are also based on
 &Qt;. &kdesrc-build; can build &Qt;, or use the one already installed on your
diff --git a/doc/index.docbook b/doc/index.docbook
index 981ad0da..1d426e53 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -97,6 +97,8 @@
   <!ENTITY credits-and-licenses SYSTEM "credits-and-licenses/index.docbook">
   <!ENTITY appendix-modules SYSTEM "appendix-modules/index.docbook">
   <!ENTITY module-concept SYSTEM "appendix-modules/module-concept.docbook">
+  <!ENTITY appendix-profile SYSTEM "appendix-profile/index.docbook">
+  <!ENTITY old-profile-setup SYSTEM "appendix-profile/old-profile-setup.docbook">
 ]>
 
 <book id="kdesrc-build" lang="&language;">
@@ -177,4 +179,6 @@ directly from the &kde; project's source code repositories.</para>
 &credits-and-licenses;
 
 &appendix-modules;
+
+&appendix-profile;
 </book>
diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index fc43a669..c42cbe8e 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -437,6 +437,32 @@ flag.
 </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
+login manager that allows you to login to your &kdesrc-build;-built &kde; desktop.</para>
+
+<para>This driver will alter the following files:</para>
+
+<itemizedlist>
+<listitem><para><filename>~/.xsession</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem>
+<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>If you maintain your own login driver then you can disable this feature by setting this
+option to <replaceable>false</replaceable>.</para>
+
+<para>This option was introduced with &kdesrc-build; 1.16.</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-kdedir">
 <entry>kdedir</entry>
 <entry>Module setting overrides global</entry>