[sdk/kdesrc-build] doc: doc: other-features - separate docbook

[Andrew Shark]

Git commit 4c8ef70683eb7eaa5890cfa4e7206dc401b42e57 by Andrew Shark.
Committed on 05/01/2024 at 20:00.
Pushed by ashark into branch 'master'.

doc: other-features - separate docbook

M  +2    -142  doc/index.docbook
A  +142  -0    doc/other-features.docbook

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

diff --git a/doc/index.docbook b/doc/index.docbook
index f8b1b1a7..7592879a 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -87,6 +87,7 @@
   <!ENTITY kde-modules-and-selection SYSTEM "kde-modules-and-selection.docbook">
   <!ENTITY kdesrc-build-logging SYSTEM "kdesrc-build-logging.docbook">
   <!ENTITY kdesrc-buildrc SYSTEM "kdesrc-buildrc.docbook">
+  <!ENTITY other-features SYSTEM "other-features.docbook">
 ]>
 
 <book id="kdesrc-build" lang="&language;">
@@ -184,148 +185,7 @@ do with this tool.</para>
 
 &developer-features;
 
-<sect1 id="other-features">
-<title>Other &kdesrc-build; features</title>
-
-<sect2 id="changing-verbosity">
-<title>Changing the amount of output from &kdesrc-build;</title>
-<para>&kdesrc-build; has several options to control the amount of output the
-script generates. In any case, errors will always be output.</para>
-
-<itemizedlist>
-<listitem><para>The <option>--quiet</option> option (short form is
-<option>-q</option>) causes &kdesrc-build; to be mostly silent. Only important
-messages, warnings, or errors will be shown. When available, build progress
-information is still shown.</para></listitem>
-
-<listitem><para>The <option>--really-quiet</option> option (no short form)
-causes &kdesrc-build; to only display important warnings or errors while it is
-running.</para></listitem>
-
-<listitem><para>The <option>--verbose</option> option (short form is
-<option>-v</option>) causes &kdesrc-build; to be very detailed in its
-output.</para></listitem>
-
-<listitem><para>The <option>--debug</option> option is for debugging purposes
-only, it causes &kdesrc-build; to act as if <option>--verbose</option> was
-turned on, causes commands to also output to the terminal, and will display
-debugging information for many functions.</para></listitem>
-</itemizedlist>
-
-</sect2>
-
-<sect2 id="kdesrc-build-color">
-<title>Color output</title>
-<para>When being run from &konsole; or a different terminal, &kdesrc-build;
-will normally display with colorized text.</para>
-
-<para>You can disable this by using the <option>--no-color</option> on the
-command line, or by setting the &colorful-output; option in the <link linkend="configure-data">configuration file</link> to
-<userinput>false</userinput>.
-</para>
-
-<informalexample>
-<para>Disabling color output in the configuration file:</para>
-<screen>
-global
-  colorful-output false
-end global
-</screen>
-</informalexample>
-
-</sect2>
-
-<sect2 id="deleting-build-dir">
-<title>Removing unneeded directories after a build</title>
-<para>Are you short on disk space but still want to run a bleeding-edge
-&kde; checkout?  &kdesrc-build; can help reduce your disk usage when building
-&kde; from &git;.</para>
-
-<note><para>Be aware that building &kde; does take a lot of space. There are
-several major space-using pieces when using &kdesrc-build;:</para></note>
-
-<orderedlist>
-<listitem><para>The actual source checkout can take up a fair amount of space.
-The default modules take up about 1.6 gigabytes of on-disk space. You can reduce
-this amount by making sure that you are only building as many modules as you
-actually want. &kdesrc-build; will not delete source code from disk even if you
-delete the entry from the <link linkend="configure-data">configuration file</link>, so make sure that you go and delete unused
-source checkouts from the source directory. Note that the source files are
-downloaded from the Internet, you <emphasis>should not</emphasis> delete them
-if you are actually using them, at least until you are done using
-&kdesrc-build;.</para>
-
-<para>Also, if you already have a &Qt; installed by your distribution (and
-the odds are good that you do), you probably do not need to install the
-qt module. That will shave about 200 megabytes off of the on-disk source
-size.</para>
-</listitem>
-
-<listitem>
-<para>&kdesrc-build; will create a separate build directory to build the source
-code in. Sometimes &kdesrc-build; will have to copy a source directory to
-create a fake build directory. When this happens, space-saving symlinks are
-used, so this should not be a hassle on disk space. The build directory will
-typically be much larger than the source directory for a module. For example,
-the build directory for kdebase is about 1050 megabytes, whereas kdebase's
-source is only around 550 megabytes.</para>
-
-<para>Luckily, the build directory is not required after a module has
-successfully been built and installed. &kdesrc-build; can automatically
-remove the build directory after installing a module, see the examples below
-for more information. Note that taking this step will make it impossible
-for &kdesrc-build; to perform the time-saving incremental builds.</para>
-</listitem>
-
-<listitem><para>
-Finally, there is disk space required for the actual installation of
-&kde;, which does not run from the build directory. This typically takes less
-space than the build directory. It is harder to get exact figures however.
-</para></listitem>
-</orderedlist>
-
-<para>How do you reduce the space requirements of &kde;?  One way is to
-use the proper compiler flags, to optimize for space reduction instead of
-for speed. Another way, which can have a large effect, is to remove debugging
-information from your &kde; build.
-</para>
-
-<warning><para>
-You should be very sure you know what you are doing before deciding to remove
-debugging information. Running bleeding-edge software means you are running
-software which is potentially much more likely to crash than a stable release.
-If you are running software without debugging information, it can be very
-hard to create a good bug report to get your bug resolved, and you will likely
-have to re-enable debugging information for the affected application and
-rebuild to help a developer fix the crash. So, remove debugging information
-at your own risk!
-</para></warning>
-
-<informalexample>
-<para>Removing the build directory after installation of a module. The source
-directory is still kept, and debugging is enabled:</para>
-
-<screen>
-global
-  configure-flags      --enable-debug
-  remove-after-install builddir        # Remove build directory after install
-end global
-</screen>
-
-<para>Removing the build directory after installation, without debugging
-information, with size optimization.</para>
-
-<screen>
-global
-  cxxflags             -Os             # Optimize for size
-  configure-flags      --disable-debug
-  remove-after-install builddir        # Remove build directory after install
-end global
-</screen>
-</informalexample>
-</sect2>
-
-</sect1>
+&other-features;
 
 </chapter>
 
diff --git a/doc/other-features.docbook b/doc/other-features.docbook
new file mode 100644
index 00000000..96215a58
--- /dev/null
+++ b/doc/other-features.docbook
@@ -0,0 +1,142 @@
+<sect1 id="other-features">
+<title>Other &kdesrc-build; features</title>
+
+<sect2 id="changing-verbosity">
+<title>Changing the amount of output from &kdesrc-build;</title>
+<para>&kdesrc-build; has several options to control the amount of output the
+script generates. In any case, errors will always be output.</para>
+
+<itemizedlist>
+<listitem><para>The <option>--quiet</option> option (short form is
+<option>-q</option>) causes &kdesrc-build; to be mostly silent. Only important
+messages, warnings, or errors will be shown. When available, build progress
+information is still shown.</para></listitem>
+
+<listitem><para>The <option>--really-quiet</option> option (no short form)
+causes &kdesrc-build; to only display important warnings or errors while it is
+running.</para></listitem>
+
+<listitem><para>The <option>--verbose</option> option (short form is
+<option>-v</option>) causes &kdesrc-build; to be very detailed in its
+output.</para></listitem>
+
+<listitem><para>The <option>--debug</option> option is for debugging purposes
+only, it causes &kdesrc-build; to act as if <option>--verbose</option> was
+turned on, causes commands to also output to the terminal, and will display
+debugging information for many functions.</para></listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="kdesrc-build-color">
+<title>Color output</title>
+<para>When being run from &konsole; or a different terminal, &kdesrc-build;
+will normally display with colorized text.</para>
+
+<para>You can disable this by using the <option>--no-color</option> on the
+command line, or by setting the &colorful-output; option in the <link linkend="configure-data">configuration file</link> to
+<userinput>false</userinput>.
+</para>
+
+<informalexample>
+<para>Disabling color output in the configuration file:</para>
+<screen>
+global
+  colorful-output false
+end global
+</screen>
+</informalexample>
+
+</sect2>
+
+<sect2 id="deleting-build-dir">
+<title>Removing unneeded directories after a build</title>
+<para>Are you short on disk space but still want to run a bleeding-edge
+&kde; checkout?  &kdesrc-build; can help reduce your disk usage when building
+&kde; from &git;.</para>
+
+<note><para>Be aware that building &kde; does take a lot of space. There are
+several major space-using pieces when using &kdesrc-build;:</para></note>
+
+<orderedlist>
+<listitem><para>The actual source checkout can take up a fair amount of space.
+The default modules take up about 1.6 gigabytes of on-disk space. You can reduce
+this amount by making sure that you are only building as many modules as you
+actually want. &kdesrc-build; will not delete source code from disk even if you
+delete the entry from the <link linkend="configure-data">configuration file</link>, so make sure that you go and delete unused
+source checkouts from the source directory. Note that the source files are
+downloaded from the Internet, you <emphasis>should not</emphasis> delete them
+if you are actually using them, at least until you are done using
+&kdesrc-build;.</para>
+
+<para>Also, if you already have a &Qt; installed by your distribution (and
+the odds are good that you do), you probably do not need to install the
+qt module. That will shave about 200 megabytes off of the on-disk source
+size.</para>
+</listitem>
+
+<listitem>
+<para>&kdesrc-build; will create a separate build directory to build the source
+code in. Sometimes &kdesrc-build; will have to copy a source directory to
+create a fake build directory. When this happens, space-saving symlinks are
+used, so this should not be a hassle on disk space. The build directory will
+typically be much larger than the source directory for a module. For example,
+the build directory for kdebase is about 1050 megabytes, whereas kdebase's
+source is only around 550 megabytes.</para>
+
+<para>Luckily, the build directory is not required after a module has
+successfully been built and installed. &kdesrc-build; can automatically
+remove the build directory after installing a module, see the examples below
+for more information. Note that taking this step will make it impossible
+for &kdesrc-build; to perform the time-saving incremental builds.</para>
+</listitem>
+
+<listitem><para>
+Finally, there is disk space required for the actual installation of
+&kde;, which does not run from the build directory. This typically takes less
+space than the build directory. It is harder to get exact figures however.
+</para></listitem>
+</orderedlist>
+
+<para>How do you reduce the space requirements of &kde;?  One way is to
+use the proper compiler flags, to optimize for space reduction instead of
+for speed. Another way, which can have a large effect, is to remove debugging
+information from your &kde; build.
+</para>
+
+<warning><para>
+You should be very sure you know what you are doing before deciding to remove
+debugging information. Running bleeding-edge software means you are running
+software which is potentially much more likely to crash than a stable release.
+If you are running software without debugging information, it can be very
+hard to create a good bug report to get your bug resolved, and you will likely
+have to re-enable debugging information for the affected application and
+rebuild to help a developer fix the crash. So, remove debugging information
+at your own risk!
+</para></warning>
+
+<informalexample>
+<para>Removing the build directory after installation of a module. The source
+directory is still kept, and debugging is enabled:</para>
+
+<screen>
+global
+  configure-flags      --enable-debug
+  remove-after-install builddir        # Remove build directory after install
+end global
+</screen>
+
+<para>Removing the build directory after installation, without debugging
+information, with size optimization.</para>
+
+<screen>
+global
+  cxxflags             -Os             # Optimize for size
+  configure-flags      --disable-debug
+  remove-after-install builddir        # Remove build directory after install
+end global
+</screen>
+</informalexample>
+</sect2>
+
+</sect1>