[sdk/kdesrc-build] doc: doc: environment - separate docbook
Andrew Shark
null at kde.org
Fri Jan 5 19:07:02 GMT 2024
Git commit 4e14ba8ba891a65db5f7c241b96d8f30129e5b46 by Andrew Shark.
Committed on 05/01/2024 at 19:59.
Pushed by ashark into branch 'master'.
doc: environment - separate docbook
A +127 -0 doc/environment.docbook
M +2 -127 doc/index.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/4e14ba8ba891a65db5f7c241b96d8f30129e5b46
diff --git a/doc/environment.docbook b/doc/environment.docbook
new file mode 100644
index 00000000..d5929b59
--- /dev/null
+++ b/doc/environment.docbook
@@ -0,0 +1,127 @@
+<sect1 id="environment">
+<title>Setting the Environment to Run Your &kde; &plasma; Desktop</title>
+
+<para>
+Assuming you are using a dedicated user to build &kde; &plasma;, and you already have an
+installed &plasma; version, running your new &plasma; may be a bit tricky, as the new
+&plasma; 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="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 sddm 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="https://getfedora.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="https://www.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="https://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="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>
+
+<para>If you intend to setup your own login support you can consult that
+appendix or view the <filename>kde-env-master.sh.in</filename> file
+included with the &kdesrc-build; source.</para>
+
+</sect2>
+
+</sect1>
diff --git a/doc/index.docbook b/doc/index.docbook
index 2e8306bb..e4f365d5 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -78,6 +78,7 @@
<!ENTITY configure-data SYSTEM "configure-data.docbook">
<!ENTITY credits-and-license SYSTEM "credits-and-license.docbook">
<!ENTITY developer-features SYSTEM "developer-features.docbook">
+ <!ENTITY environment SYSTEM "environment.docbook">
]>
<book id="kdesrc-build" lang="&language;">
@@ -443,133 +444,7 @@ linkend="configure-data" /> and in <xref linkend="kdesrc-buildrc" />.
&building-specific-modules;
-<sect1 id="environment">
-<title>Setting the Environment to Run Your &kde; &plasma; Desktop</title>
-
-<para>
-Assuming you are using a dedicated user to build &kde; &plasma;, and you already have an
-installed &plasma; version, running your new &plasma; may be a bit tricky, as the new
-&plasma; 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="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 sddm 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="https://getfedora.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="https://www.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="https://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="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>
-
-<para>If you intend to setup your own login support you can consult that
-appendix or view the <filename>kde-env-master.sh.in</filename> file
-included with the &kdesrc-build; source.</para>
-
-</sect2>
-
-</sect1>
+&environment;
<sect1 id="kde-modules-and-selection">
<title>Module Organization and selection</title>
More information about the kde-doc-english
mailing list