[sdk/kdesrc-build] doc: doc: appendix-profile - separate docbook

[Andrew Shark]

Git commit 047ca98d497befc8ab630c0769b34f1d34803b87 by Andrew Shark.
Committed on 05/01/2024 at 19:57.
Pushed by ashark into branch 'master'.

doc: appendix-profile - separate docbook

A  +168  -0    doc/appendix-profile.docbook
M  +2    -168  doc/index.docbook

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

diff --git a/doc/appendix-profile.docbook b/doc/appendix-profile.docbook
new file mode 100644
index 00000000..a9293a92
--- /dev/null
+++ b/doc/appendix-profile.docbook
@@ -0,0 +1,168 @@
+<appendix id="appendix-profile">
+<title>Superseded profile setup procedures</title>
+
+<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.in</filename> file included with the &kdesrc-build;
+source.</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.
+PATH=${install-dir}/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=${install-dir}:/lib:$QTDIR/lib
+else
+  LD_LIBRARY_PATH=${install-dir}:/lib:$QTDIR/lib:$LD_LIBRARY_PATH
+fi
+
+export QTDIR PATH MANPATH LD_LIBRARY_PATH
+</programlisting>
+
+or, if you are not building qt (and are using your system &Qt; instead), add
+this instead:
+
+<programlisting>
+PATH=${install-dir}/bin:$QTDIR/bin:$PATH
+
+# Act appropriately if LD_LIBRARY_PATH is not already set.
+if [ -z $LD_LIBRARY_PATH ]; then
+  LD_LIBRARY_PATH=${install-dir}/lib
+else
+  LD_LIBRARY_PATH=${install-dir}/lib:$LD_LIBRARY_PATH
+fi
+
+export 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-git"
+
+# Create it if needed
+[ ! -e ~/.kde-git ] && mkdir ~/.kde-git
+</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="${install-dir}/share:/usr/share"
+export XDG_CONFIG_DIRS XDG_DATA_DIRS
+</programlisting>
+
+</para>
+</note>
+
+</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>${install-dir}/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
+sddm, <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 sddm, 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>
+
+<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; &git; 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>
+
+</sect2>
+</sect1>
+
+</appendix>
diff --git a/doc/index.docbook b/doc/index.docbook
index db3eddcf..42e17550 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -69,6 +69,7 @@
   -->
   <!ENTITY advanced-features SYSTEM "advanced-features.docbook">
   <!ENTITY appendix-modules SYSTEM "appendix-modules.docbook">
+  <!ENTITY appendix-profile SYSTEM "appendix-profile.docbook">
 ]>
 
 <book id="kdesrc-build" lang="&language;">
@@ -4391,172 +4392,5 @@ as of &kdesrc-build; version 1.6.3.
 
 &appendix-modules;
 
-<appendix id="appendix-profile">
-<title>Superseded profile setup procedures</title>
-
-<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.in</filename> file included with the &kdesrc-build;
-source.</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.
-PATH=${install-dir}/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=${install-dir}:/lib:$QTDIR/lib
-else
-  LD_LIBRARY_PATH=${install-dir}:/lib:$QTDIR/lib:$LD_LIBRARY_PATH
-fi
-
-export QTDIR PATH MANPATH LD_LIBRARY_PATH
-</programlisting>
-
-or, if you are not building qt (and are using your system &Qt; instead), add
-this instead:
-
-<programlisting>
-PATH=${install-dir}/bin:$QTDIR/bin:$PATH
-
-# Act appropriately if LD_LIBRARY_PATH is not already set.
-if [ -z $LD_LIBRARY_PATH ]; then
-  LD_LIBRARY_PATH=${install-dir}/lib
-else
-  LD_LIBRARY_PATH=${install-dir}/lib:$LD_LIBRARY_PATH
-fi
-
-export 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-git"
-
-# Create it if needed
-[ ! -e ~/.kde-git ] && mkdir ~/.kde-git
-</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="${install-dir}/share:/usr/share"
-export XDG_CONFIG_DIRS XDG_DATA_DIRS
-</programlisting>
-
-</para>
-</note>
-
-</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>${install-dir}/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
-sddm, <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 sddm, 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>
-
-<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; &git; 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>
-
-</sect2>
-</sect1>
-
-</appendix>
+&appendix-profile;
 </book>