[sdk/kdesrc-build/docbook_historied_per_file] doc: doc: Organize intro, add better overview.

[Michael Pyne]

Git commit 59ffb11e226d0dc655e97dbd220db7d1552dcbb7 by Michael Pyne.
Committed on 27/05/2012 at 16:46.
Pushed by ashark into branch 'docbook_historied_per_file'.

doc: Organize intro, add better overview.

Original commit: 514372b6
https://invent.kde.org/sdk/kdesrc-build/-/commit/514372b66b75d9d92b56b23e6a0dbdc10d9943fd

M  +3    -0    doc/index.docbook
A  +47   -0    doc/introduction/brief-intro.docbook
M  +2    -29   doc/introduction/index.docbook
C  +3    -14   doc/introduction/intro-toc.docbook [from: doc/introduction/index.docbook - 055% similarity]

https://invent.kde.org/sdk/kdesrc-build/-/commit/59ffb11e226d0dc655e97dbd220db7d1552dcbb7

diff --git a/doc/index.docbook b/doc/index.docbook
index 5e17e98c..6e1f2e3e 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -68,6 +68,8 @@
   <!ENTITY cmd-reconfigure '<link linkend="cmdline-reconfigure">--reconfigure</link>'>
   <!ENTITY cmd-refresh-build '<link linkend="cmdline-refresh-build">--refresh-build</link>'>
   <!ENTITY introduction SYSTEM "introduction/index.docbook">
+  <!ENTITY brief-intro SYSTEM "introduction/brief-intro.docbook">
+  <!ENTITY intro-toc SYSTEM "introduction/intro-toc.docbook">
   <!ENTITY getting-started SYSTEM "getting-started/index.docbook">
   <!ENTITY before-building SYSTEM "getting-started/before-building.docbook">
   <!ENTITY configure-data SYSTEM "getting-started/configure-data.docbook">
@@ -157,6 +159,7 @@ directly from the &kde; project's source code repositories.</para>
 </bookinfo>
 
 &introduction;
+
 &getting-started;
 
 &features;
diff --git a/doc/introduction/brief-intro.docbook b/doc/introduction/brief-intro.docbook
new file mode 100644
index 00000000..a31c7136
--- /dev/null
+++ b/doc/introduction/brief-intro.docbook
@@ -0,0 +1,47 @@
+<sect1 id="brief-intro">
+<title>A brief introduction to &kdesrc-build;</title>
+
+<sect2 id="whatis-kdesrc-build">
+<title>What is &kdesrc-build;?</title>
+
+<para>
+&kdesrc-build; is a script to help users install <ulink
+url="http://www.kde.org/">&kde;</ulink> software from its <ulink
+url="http://subversion.tigris.org/">&subversion;</ulink> and <ulink
+url="http://gitscm.org/">&git;</ulink> source repositories.
+<!-- Deliberately not KDE SC, we can also install Extragear, amarok, etc. -->
+</para>
+
+<para>In addition to simply installing &kde; software, the script can also be
+used to update the installed &kde; software after it is installed. This allows
+you to keep up-to-date with &kde; development.
+</para>
+
+<para>The &kdesrc-build; script can be used to maintain a single individual
+module or an entire &kde; desktop depending on how it is configured.
+</para>
+</sect2>
+
+<sect2 id="operation-in-a-nutshell">
+<title>&kdesrc-build; operation <quote>in a nutshell</quote></title>
+
+<para>&kdesrc-build; intentionally works by using the same tools available to
+the user at the command-line. When &kdesrc-build; is run, the following
+sequence is followed:
+</para>
+
+<orderedlist>
+<listitem>&kdesrc-build; reads in the <link linkend="cmdline">command
+line</link> and <link linkend="configure-data">configuration file</link>, to
+determine what to build, compile options to use, where to install,
+etc.</listitem>
+
+<listitem>&kdesrc-build; performs a source update for each <link
+linkend="module-concept">module</link>. The update continues until all modules
+have been updated. Modules that fail to update normally do not stop the build
+– you will be notified at the end which modules did not
+update.</listitem>
+</orderedlist>
+
+</sect2>
+</sect1>
diff --git a/doc/introduction/index.docbook b/doc/introduction/index.docbook
index 5295e31d..4be81856 100644
--- a/doc/introduction/index.docbook
+++ b/doc/introduction/index.docbook
@@ -1,34 +1,7 @@
 <chapter id="introduction">
 <title>Introduction</title>
 
-<para>
-&kdesrc-build; is a script to help users install <ulink
-url="http://www.kde.org/">&kde;</ulink> software from its <ulink
-url="http://subversion.tigris.org/">&subversion;</ulink> and <ulink
-url="http://gitscm.org/">&git;</ulink> source repositories.
-<!-- Deliberately not KDE SC, we can also install Extragear, amarok, etc. -->
-</para>
-
-<tip><para>This software used to be called kdesvn-build, so you may still see
-references to kdesvn-build on the Internet or in your installed documentation.</para></tip>
-
-<para>
-This guide is an overview to describe the following aspects of &kdesrc-build;
-operation:
-</para>
-
-<itemizedlist>
-<listitem><para>An <link linkend="getting-started">overview</link> of the steps
-required to get started.</para></listitem>
-<listitem><para>Notable <link linkend="features">features</link>.</para></listitem>
-<listitem><para>The <link linkend="configure-data">configuration file</link> syntax
-and options.</para></listitem>
-<listitem><para>The <link linkend="cmdline">command line options</link>.</para></listitem>
-</itemizedlist>
-
-<para>Also documented are the steps which you should perform using
-other tools, (in other words, steps that are not automatically performed by
-&kdesrc-build;).
-</para>
+&brief-intro;
 
+&intro-toc;
 </chapter>
diff --git a/doc/introduction/index.docbook b/doc/introduction/intro-toc.docbook
similarity index 55%
copy from doc/introduction/index.docbook
copy to doc/introduction/intro-toc.docbook
index 5295e31d..78f8e902 100644
--- a/doc/introduction/index.docbook
+++ b/doc/introduction/intro-toc.docbook
@@ -1,16 +1,5 @@
-<chapter id="introduction">
-<title>Introduction</title>
-
-<para>
-&kdesrc-build; is a script to help users install <ulink
-url="http://www.kde.org/">&kde;</ulink> software from its <ulink
-url="http://subversion.tigris.org/">&subversion;</ulink> and <ulink
-url="http://gitscm.org/">&git;</ulink> source repositories.
-<!-- Deliberately not KDE SC, we can also install Extragear, amarok, etc. -->
-</para>
-
-<tip><para>This software used to be called kdesvn-build, so you may still see
-references to kdesvn-build on the Internet or in your installed documentation.</para></tip>
+<sect1 id="intro-toc">
+<title>Documentation Overview</title>
 
 <para>
 This guide is an overview to describe the following aspects of &kdesrc-build;
@@ -31,4 +20,4 @@ other tools, (in other words, steps that are not automatically performed by
 &kdesrc-build;).
 </para>
 
-</chapter>
+</sect1>