[sdk/kdesrc-build] doc: doc: kdesrc-build-logging - separate docbook

[Andrew Shark]

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

doc: kdesrc-build-logging - separate docbook

M  +1    -78   doc/features.docbook
M  +1    -0    doc/index.docbook
A  +78   -0    doc/kdesrc-build-logging.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/93412946d1e2df4374d280350631da819e5f0caf

diff --git a/doc/features.docbook b/doc/features.docbook
index 2a911dc3..723cb706 100644
--- a/doc/features.docbook
+++ b/doc/features.docbook
@@ -180,83 +180,6 @@ always point to the most recent log entry in the log directory.
 
 </sect1>
 
-<sect1 id="kdesrc-build-logging">
-<title>&kdesrc-build;'s build logging</title>
-
-<sect2 id="logging-overview">
-<title>Logging overview</title>
-
-<para>Logging is a &kdesrc-build; feature whereby the output from every command
-that &kdesrc-build; runs is saved to a file for examination later, if
-necessary. This is done because it is often necessary to have the output of
-these programs when there is a build failure, because there are so many
-reasons why a build can fail in the first place.</para>
-
-<sect3 id="log-directory-layout">
-<title>Logging directory layout</title>
-
-<para>The logs are always stored under the log directory. The destination of
-the log directory is controlled by the <link linkend="conf-log-dir">log-dir</link>
-option, which defaults to <filename class="directory"><symbol>${source-dir}</symbol>/log</filename> (where
-<symbol>${source-dir}</symbol> is the value of the <link linkend="conf-source-dir">source-dir</link>
-option. The in rest of this section, this value will be referred to as
-<symbol>${log-dir}</symbol>).</para>
-
-<para>Under <symbol>${log-dir}</symbol>, is a set of directories, one for every
-time that &kdesrc-build; was run. Each directory is named with the date, and
-the run number. For instance, the second time that &kdesrc-build; is run on
-May 26, 2004, it would create a directory called <filename>2004-05-26-02</filename>,
-where the 2004-05-26 is for the date, and the -02 is the run number.</para>
-
-<para>For your convenience, &kdesrc-build; will also create a link to the
-logs for your latest run, called <filename class="directory">latest</filename>. So the logs for
-the most recent &kdesrc-build; run should always be under <filename class="directory"><symbol>${log-dir}</symbol>/latest</filename>.
-</para>
-
-<para>Now, each directory for a &kdesrc-build; run will itself contain a set of
-directories, one for every &kde; module that &kdesrc-build; tries to build. Also,
-a file called <filename>build-status</filename> will be contained in the directory,
-which will allow you to determine which modules built and which failed.</para>
-
-<note><para>
-If a module itself has a submodule (such as extragear/multimedia,
-playground/utils, or KDE/kdelibs), then there would actually be a matching
-layout in the log directory. For example, the logs for KDE/kdelibs after the
-last &kdesrc-build; run would be found in <filename class="directory"><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>,
-and not under <filename class="directory"><symbol>${log-dir}</symbol>/latest/kdelibs</filename>.
-</para></note>
-
-<para>In each module log directory, you will find a set of files for each
-operation that &kdesrc-build; performs. If &kdesrc-build; updates a module,
-you may see filenames such as <filename>git-checkout-update.log</filename> (for a
-module checkout or when updating a module
-that has already been checked out). If the <command>configure</command>
-command was run, then you would expect to see a <filename>configure.log</filename>
-in that directory.</para>
-
-<para>If an error occurred, you should be able to see an explanation of why in
-one of the files. To help you determine which file contains the error,
-&kdesrc-build; will create a link from the file containing the error (such as
-<filename>build-1.log</filename> to a file called <filename>error.log</filename>).</para>
-
-<para>The upshot to all of this is that to see why a module failed to build
-after your last &kdesrc-build;, the file you should look at first is
-<filename><symbol>${log-dir}</symbol>/latest/<replaceable>module-name</replaceable>/error.log</filename>.
-</para>
-
-<tip><para>If the file <filename>error.log</filename> is empty (especially after
-an installation), then perhaps there was no error. Some of the tools used by
-the &kde; build system will sometimes mistakenly report an error when there was
-none.</para>
-
-<para>Also, some commands will evade &kdesrc-build;'s output redirection and
-bypass the log file in certain circumstances (normally when performing the
-first &git; checkout), and the error output in that case is not in the log file
-but is instead at the &konsole; or terminal where you ran &kdesrc-build;.</para>
-</tip>
-
-</sect3>
-</sect2>
-</sect1>
+&kdesrc-build-logging;
 
 </chapter>
diff --git a/doc/index.docbook b/doc/index.docbook
index b7801670..78e55044 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -85,6 +85,7 @@
   <!ENTITY introduction SYSTEM "introduction.docbook">
   <!ENTITY kde-cmake SYSTEM "kde-cmake.docbook">
   <!ENTITY kde-modules-and-selection SYSTEM "kde-modules-and-selection.docbook">
+  <!ENTITY kdesrc-build-logging SYSTEM "kdesrc-build-logging.docbook">
 ]>
 
 <book id="kdesrc-build" lang="&language;">
diff --git a/doc/kdesrc-build-logging.docbook b/doc/kdesrc-build-logging.docbook
new file mode 100644
index 00000000..91f751ac
--- /dev/null
+++ b/doc/kdesrc-build-logging.docbook
@@ -0,0 +1,78 @@
+<sect1 id="kdesrc-build-logging">
+<title>&kdesrc-build;'s build logging</title>
+
+<sect2 id="logging-overview">
+<title>Logging overview</title>
+
+<para>Logging is a &kdesrc-build; feature whereby the output from every command
+that &kdesrc-build; runs is saved to a file for examination later, if
+necessary. This is done because it is often necessary to have the output of
+these programs when there is a build failure, because there are so many
+reasons why a build can fail in the first place.</para>
+
+<sect3 id="log-directory-layout">
+<title>Logging directory layout</title>
+
+<para>The logs are always stored under the log directory. The destination of
+the log directory is controlled by the <link linkend="conf-log-dir">log-dir</link>
+option, which defaults to <filename class="directory"><symbol>${source-dir}</symbol>/log</filename> (where
+<symbol>${source-dir}</symbol> is the value of the <link linkend="conf-source-dir">source-dir</link>
+option. The in rest of this section, this value will be referred to as
+<symbol>${log-dir}</symbol>).</para>
+
+<para>Under <symbol>${log-dir}</symbol>, is a set of directories, one for every
+time that &kdesrc-build; was run. Each directory is named with the date, and
+the run number. For instance, the second time that &kdesrc-build; is run on
+May 26, 2004, it would create a directory called <filename>2004-05-26-02</filename>,
+where the 2004-05-26 is for the date, and the -02 is the run number.</para>
+
+<para>For your convenience, &kdesrc-build; will also create a link to the
+logs for your latest run, called <filename class="directory">latest</filename>. So the logs for
+the most recent &kdesrc-build; run should always be under <filename class="directory"><symbol>${log-dir}</symbol>/latest</filename>.
+</para>
+
+<para>Now, each directory for a &kdesrc-build; run will itself contain a set of
+directories, one for every &kde; module that &kdesrc-build; tries to build. Also,
+a file called <filename>build-status</filename> will be contained in the directory,
+which will allow you to determine which modules built and which failed.</para>
+
+<note><para>
+If a module itself has a submodule (such as extragear/multimedia,
+playground/utils, or KDE/kdelibs), then there would actually be a matching
+layout in the log directory. For example, the logs for KDE/kdelibs after the
+last &kdesrc-build; run would be found in <filename class="directory"><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>,
+and not under <filename class="directory"><symbol>${log-dir}</symbol>/latest/kdelibs</filename>.
+</para></note>
+
+<para>In each module log directory, you will find a set of files for each
+operation that &kdesrc-build; performs. If &kdesrc-build; updates a module,
+you may see filenames such as <filename>git-checkout-update.log</filename> (for a
+module checkout or when updating a module
+that has already been checked out). If the <command>configure</command>
+command was run, then you would expect to see a <filename>configure.log</filename>
+in that directory.</para>
+
+<para>If an error occurred, you should be able to see an explanation of why in
+one of the files. To help you determine which file contains the error,
+&kdesrc-build; will create a link from the file containing the error (such as
+<filename>build-1.log</filename> to a file called <filename>error.log</filename>).</para>
+
+<para>The upshot to all of this is that to see why a module failed to build
+after your last &kdesrc-build;, the file you should look at first is
+<filename><symbol>${log-dir}</symbol>/latest/<replaceable>module-name</replaceable>/error.log</filename>.
+</para>
+
+<tip><para>If the file <filename>error.log</filename> is empty (especially after
+an installation), then perhaps there was no error. Some of the tools used by
+the &kde; build system will sometimes mistakenly report an error when there was
+none.</para>
+
+<para>Also, some commands will evade &kdesrc-build;'s output redirection and
+bypass the log file in certain circumstances (normally when performing the
+first &git; checkout), and the error output in that case is not in the log file
+but is instead at the &konsole; or terminal where you ran &kdesrc-build;.</para>
+</tip>
+
+</sect3>
+</sect2>
+</sect1>