[sdk/kdesrc-build/docbook_historied_per_file] doc: Commit kdesvn-build documentation improvements, to the correct branch this time.
Michael Pyne
null at kde.org
Fri May 10 10:14:25 BST 2024
Git commit a1e5bda0d2fb4f87e4f9e2964c47c001dc2829a5 by Michael Pyne.
Committed on 05/01/2006 at 04:56.
Pushed by ashark into branch 'docbook_historied_per_file'.
Commit kdesvn-build documentation improvements, to the correct branch this time.
svn path=/trunk/KDE/kdesdk/doc/scripts/kdesvn-build/; revision=494452
Original commit: 53fa05c5
https://invent.kde.org/sdk/kdesrc-build/-/commit/53fa05c5eafe7525acad8d21667b3a7cd4472646
M +12 -15 doc/cmdline/index.docbook
C +116 -31 doc/features/features-overview.docbook [from: doc/features/index.docbook - 051% similarity]
M +2 -140 doc/features/index.docbook
A +78 -0 doc/features/kdesvn-build-logging.docbook
M +112 -26 doc/getting-started/before-building.docbook
M +24 -8 doc/getting-started/building-and-troubleshooting.docbook
M +34 -21 doc/getting-started/configure-data.docbook
M +92 -34 doc/getting-started/environment.docbook
M +2 -2 doc/getting-started/index.docbook
M +61 -5 doc/index.docbook
M +10 -9 doc/introduction/index.docbook
M +73 -24 doc/kdesvn-buildrc/index.docbook
A +530 -0 doc/using-kdesvn-build/advanced-features.docbook
A +202 -0 doc/using-kdesvn-build/basic-features.docbook
A +83 -0 doc/using-kdesvn-build/developer-features.docbook
A +14 -0 doc/using-kdesvn-build/index.docbook
A +188 -0 doc/using-kdesvn-build/other-features.docbook
A +17 -0 doc/using-kdesvn-build/using-kdesvn-build-preface.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/a1e5bda0d2fb4f87e4f9e2964c47c001dc2829a5
diff --git a/doc/cmdline/index.docbook b/doc/cmdline/index.docbook
index 30b0d0d9..9efb0147 100644
--- a/doc/cmdline/index.docbook
+++ b/doc/cmdline/index.docbook
@@ -42,6 +42,14 @@ enable colorful output.
</para></listitem>
</varlistentry>
+<varlistentry id="cmdline-nice">
+<term><option>--nice=<replaceable>value</replaceable></option></term>
+<listitem><para>
+Sets the &niceness; value to <replaceable>value</replaceable> for the duration
+of this run. <replaceable>value</replaceable> should be between 0 and 20.
+</para></listitem>
+</varlistentry>
+
<varlistentry id="cmdline-no-color">
<term><option>--no-color</option></term>
<listitem><para>
@@ -165,22 +173,11 @@ building as normal. This option implies <option><link linkend="cmdline-reconfig
</para></listitem>
</varlistentry>
-<varlistentry id="cmdline-resume">
-<term><option>--resume</option></term>
-<listitem><para>
-which tries to continue building from where
-the script stopped last time. The script starts building the module after the
-last module to be compiled last time the script was run, whether or not it
-succeeded. This option implies <link linkend="cmdline-no-svn"><option>--no-svn</option></link>. You
-should not specify other module names on the command line.
-</para></listitem>
-</varlistentry>
-
<varlistentry id="cmdline-resume-from">
<term><option>--resume-from</option></term>
<listitem><para>
-which is like <link linkend="cmdline-resume"><option>--resume</option></link>, except that you supply
-the module to start building from as the next parameter on the command line. This option
+This option is used to resume the build starting from the given module, which
+should be the next option on the command line. This option
implies <link linkend="cmdline-no-svn"><option>--no-svn</option></link>. You should not specify
other module names on the command line.
</para></listitem>
@@ -224,7 +221,7 @@ options are specified after <option>--install</option>, they are all assumed to
<varlistentry id="cmdline-global-option">
<term><option>--<option-name>=</option></term>
<listitem><para>
-You can use this option to override an option in your configuration file for
+You can use this option to override an option in your &rcfile; for
every module. For instance, to override the <link
linkend="conf-log-dir">log-dir</link> option, you would do:
<option>--log-dir=/path/to/dir</option>.
@@ -234,7 +231,7 @@ linkend="conf-log-dir">log-dir</link> option, you would do:
<varlistentry id="cmdline-module-option">
<term><option>--<module-name>,<option-name>=</option></term>
<listitem><para>
-You can use this option to override an option in your configuration file for
+You can use this option to override an option in your &rcfile; for
a specific module. For instance, to override the <link
linkend="conf-use-unsermake">use-unsermake</link> option for kdemultimedia, you
would do: <option>--kdemultimedia,use-unsermake=false</option>.
diff --git a/doc/features/index.docbook b/doc/features/features-overview.docbook
similarity index 51%
copy from doc/features/index.docbook
copy to doc/features/features-overview.docbook
index d35ed137..07b95d85 100644
--- a/doc/features/index.docbook
+++ b/doc/features/features-overview.docbook
@@ -1,20 +1,129 @@
-<chapter id="features">
-<title>Script Features</title>
+<sect1 id="features-overview">
+<title>Feature Overview</title>
<para>
&kdesvn-build; features include:
</para>
-
<itemizedlist>
+<listitem><para>
+For developers: Supports <link linkend="building-apidox">building the API
+documentation</link> for a module.
+</para></listitem>
+
+<listitem><para>
+Supports <link linkend="changing-verbosity">output message levels</link>
+ranging from being very quiet to a full debug level.
+</para></listitem>
+
+<listitem><para>
+Has excellent support for the <link linkend="using-qt-copy">qt-copy module</link>,
+including optionally applying bugfix and optimization patches to the qt-copy
+module.
+</para></listitem>
+
+<listitem><para>
+&kdesvn-build; has <link linkend="kdesvn-build-color">colorized output.</link>
+</para></listitem>
+
+<listitem><para>
+&kdesvn-build; does not require a <acronym>GUI</acronym> present to operate. So,
+you can build &kde; without needing an alternate graphical environment.
+</para></listitem>
+
+<listitem><para>
+Supports setting default options for all modules (such as the compilation
+settings or the configuration options). Such options can normally be changed
+for specific modules as well.</para>
+
+<para>Also, &kdesvn-build; will <link linkend="kdesvn-build-std-flags">add
+standard flags</link> as appropriate to save you the trouble and possible
+errors from typing them yourself.
+</para></listitem>
+
+<listitem><para>
+&kdesvn-build; can <link linkend="partial-builds">checkout only portions of a
+module</link>, for those situations where you only need one program from a
+large module.
+</para></listitem>
+
+<listitem><para>
+For developers: Will <link linkend="ssh-agent-reminder">remind you</link> if
+you use svn+ssh:// but <application>ssh-agent</application> is not running, as
+this will lead to repeated password requests from
+<application>ssh</application>.
+</para></listitem>
+
+<listitem><para>
+Can <link linkend="email-reports">e-mail reports</link> of errors to a user.
+</para></listitem>
+
+<listitem><para>
+Can <link linkend="deleting-build-dir">delete the build directory</link> of a
+module after its installation to save space at the expense of future compilation
+time.
+</para></listitem>
+
+<listitem><para>
+The locations for the directories used by &kdesvn-build; are configurable (even
+per module).
+</para></listitem>
+
+<listitem><para>
+Can use <application>sudo</application>, or a different user-specified command
+to <link linkend="root-installation">install modules</link> so that
+&kdesvn-build; does not need to be run as the super user.
+</para></listitem>
+
+<listitem><para>
+&kdesvn-build; runs <link linkend="build-priority">with reduced priority</link>
+by default to allow you to still use your computer while &kdesvn-build; is
+working.
+</para></listitem>
+
+<listitem><para>
+Has support for using &kde;'s &svn; <link linkend="using-branches">tags and
+branches</link>.
+</para></listitem>
+
+<listitem><para>
+&kdesvn-build; will use a set of techniques to <link linkend="building-successfully">try
+and guarantee</link> a successful build.
+</para></listitem>
+
+<listitem><para>
+There is support for <link linkend="resuming">resuming a build</link> from a
+given module. You can even <link linkend="ignoring-modules">ignore some
+modules</link> temporarily for a given build.
+</para></listitem>
+
+<listitem><para>
+&kdesvn-build; also supports using the ~/ sequence to stand for your home
+directory in the &rcfile;.
+</para></listitem>
+
<listitem><para>
Automatically checks out or updates modules from &svn;, as
appropriate.
</para></listitem>
<listitem><para>
-Times the build process for modules.
+&kdesvn-build; can quickly perform a <link linkend="partial-builds">partial
+build</link> of a module directly from the command line, when you only need
+to update part of a module.
+</para></listitem>
+
+<listitem><para>
+&kdesvn-build; will automatically download and create the required <filename>/admin</filename>
+directory for a module if it isn't downloaded from &svn; the first time for
+some reason.
+</para></listitem>
+
+<listitem><para>
+&kdesvn-build; will show the <link linkend="build-progress">progress of your
+build</link> when using &unsermake;, and will always time the build process so
+you know after the fact how long it took.
</para></listitem>
<listitem><para>
@@ -23,8 +132,7 @@ make, which is prone to failure after certain kinds of commits.
</para></listitem>
<listitem><para>
-Can resume a previous script, or start the build process from a particular
-module.
+Can resume a build from a particular module.
</para></listitem>
<listitem><para>
@@ -33,8 +141,7 @@ a base &kde; single-user installation from the anonymous &svn; repository.
</para></listitem>
<listitem><para>
-Comes with <ulink url="http://www.kde.me.uk/index.php?page=unsermake">Unsermake</ulink>
-support.
+Comes with &unsermake; support.
</para></listitem>
<listitem><para>
@@ -121,26 +228,4 @@ configuration option</link>.
</itemizedlist>
-<para>
-Things that &kdesvn-build; does NOT do:
-</para>
-
-<itemizedlist>
-
-<listitem><para>
-Find the fastest &kde; &svn; mirror. There is not even a list shipped
-with the script at this point, although the default server should work
-fine.
-</para></listitem>
-
-<listitem><para>
-Brush your teeth. You should remember to do that yourself.
-</para></listitem>
-
-<listitem><para>
-The script probably is not bug-free. Sorry.
-</para></listitem>
-
-</itemizedlist>
-
-</chapter>
+</sect1>
diff --git a/doc/features/index.docbook b/doc/features/index.docbook
index d35ed137..011befab 100644
--- a/doc/features/index.docbook
+++ b/doc/features/index.docbook
@@ -1,146 +1,8 @@
<chapter id="features">
<title>Script Features</title>
-<para>
-&kdesvn-build; features include:
-</para>
+&features-overview;
-
-<itemizedlist>
-
-<listitem><para>
-Automatically checks out or updates modules from &svn;, as
-appropriate.
-</para></listitem>
-
-<listitem><para>
-Times the build process for modules.
-</para></listitem>
-
-<listitem><para>
-Automatically tries to rebuild modules that were using incremental
-make, which is prone to failure after certain kinds of commits.
-</para></listitem>
-
-<listitem><para>
-Can resume a previous script, or start the build process from a particular
-module.
-</para></listitem>
-
-<listitem><para>
-Comes built-in with a sane set of default options appropriate for building
-a base &kde; single-user installation from the anonymous &svn; repository.
-</para></listitem>
-
-<listitem><para>
-Comes with <ulink url="http://www.kde.me.uk/index.php?page=unsermake">Unsermake</ulink>
-support.
-</para></listitem>
-
-<listitem><para>
-Tilde-expansion for your configuration options. For example, you can
-specify:
-<programlisting>qtdir ~/kdesvn/build/qt-copy</programlisting>
-</para></listitem>
-
-<listitem><para>
-Configurable build, source, and logging directories
-</para></listitem>
-
-<listitem><para>
-Automatically sets up a build system, with the source directory not the
-same as the build directory, in order to keep the source directory
-pristine. The exception is <application>qt-copy</application>, which is not designed to be built like
-that (unless you would like to test the
-<link linkend="conf-use-qt-builddir-hack"><quote>qt with a separate build directory hack</quote></link>).
-</para></listitem>
-
-<listitem><para>
-You can specify global options to apply to every module to check out, and
-you can specify options to apply to individual modules as well.
-</para></listitem>
-
-<listitem><para>
-Since the autotools sometimes get out of sync with changes to the
-source tree, you can force a rebuild of a module by creating a file called
-.refresh-me in the build directory of the module in question, or by running
-&kdesvn-build; with the <option>--refresh-build</option> option.
-</para></listitem>
-
-<listitem><para>
-You can specify various environment values to be used during the build,
-including <envar>KDEDIR</envar>, <envar>QTDIR</envar>, <envar>DO_NOT_COMPILE</envar>,
-and <envar>CXXFLAGS</envar>.
-</para></listitem>
-
-<listitem><para>
-Command logging. Logs are dated and numbered so that you always have a
-log of a script run. Also, a special symlink called latest is created to
-always point to the most recent log entry in the log directory.
-</para></listitem>
-
-<listitem><para>
-If you are using a user build of &kde; instead of a system build (for which
-you must be root to install), you can use the script to install for you. I
-haven not audited this code, and it makes ample use of the <function>system()</function>
-call, so I would not recommend running it as root at this point.
-</para></listitem>
-
-<listitem><para>
-You can use <link linkend="conf-make-install-prefix">make-install-prefix</link> to
-prefix the make install command line with a separate command, which is useful
-for sudo.
-</para></listitem>
-
-<listitem><para>
-You can use the <link linkend="conf-apidox">apidox</link> option to automatically
-build and install the API documentation for some modules.
-</para></listitem>
-
-<listitem><para>
-You can check out only a portion of a &kde; &svn; module. For example,
-you could check out only the <application>taglib</application> from
-<application>kdesupport</application>, or only <application>K3B</application> from
-<application>extragear/multimedia</application>. The script will automatically pull in
-<application>kde-common</application> if necessary to make the build work.
-</para></listitem>
-
-<listitem><para>
-You can <quote>pretend</quote> to do the operations. If you pass
-<option>--pretend</option> or <option>-p</option> on the
-command line, the script will give a very verbose description of the commands
-it is about to execute, without actually executing it.
-</para></listitem>
-
-<listitem><para>
-Support for checking out specific branches of &svn;
-modules. This work still needs to be completed, but you already select the branch you
-want to build using the <link linkend="conf-module-base-path">module-base-path
-configuration option</link>.
-</para></listitem>
-
-</itemizedlist>
-
-<para>
-Things that &kdesvn-build; does NOT do:
-</para>
-
-<itemizedlist>
-
-<listitem><para>
-Find the fastest &kde; &svn; mirror. There is not even a list shipped
-with the script at this point, although the default server should work
-fine.
-</para></listitem>
-
-<listitem><para>
-Brush your teeth. You should remember to do that yourself.
-</para></listitem>
-
-<listitem><para>
-The script probably is not bug-free. Sorry.
-</para></listitem>
-
-</itemizedlist>
+&kdesvn-build-logging;
</chapter>
diff --git a/doc/features/kdesvn-build-logging.docbook b/doc/features/kdesvn-build-logging.docbook
new file mode 100644
index 00000000..c064be16
--- /dev/null
+++ b/doc/features/kdesvn-build-logging.docbook
@@ -0,0 +1,78 @@
+<sect1 id="kdesvn-build-logging">
+<title>&kdesvn-build;'s build logging</title>
+
+<sect2 id="logging-overview">
+<title>Logging overview</title>
+
+<para>Logging is a &kdesvn-build; feature whereby the output from every command
+that &kdesvn-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><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 &kdesvn-build; was run. Each directory is named with the date, and
+the run number. For instance, the second time that &kdesvn-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, &kdesvn-build; will also create a link to the
+logs for your latest run, called <filename>latest</filename>. So the logs for
+the most recent &kdesvn-build; run should always be under <filename><symbol>${log-dir}</symbol>/latest</filename>.
+</para>
+
+<para>Now, each directory for a &kdesvn-build; run will itself contain a set of
+directories, one for every &kde; module that &kdesvn-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 &kdesvn-build; run would be found in <filename><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>,
+and not under <filename><symbol>${log-dir}</symbol>/latest/kdelibs</filename>.
+</para></note>
+
+<para>In each module log directory, you'll find a set of files for each
+operation that &kdesvn-build; performs. If &kdesvn-build; updates a module,
+you may see filenames such as <filename>svn-co.log</filename> (for a
+module checkout) or <filename>svn-up.log</filename> (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,
+&kdesvn-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 &kdesvn-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 &kdesvn-build;'s output redirection and
+bypass the log file in certain circumstances (normally when performing the
+first &svn; 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 &kdesvn-build;</para>
+</tip>
+
+</sect3>
+</sect2>
+</sect1>
diff --git a/doc/getting-started/before-building.docbook b/doc/getting-started/before-building.docbook
index 227ea41f..ead4b59e 100644
--- a/doc/getting-started/before-building.docbook
+++ b/doc/getting-started/before-building.docbook
@@ -1,8 +1,11 @@
<sect1 id="before-building">
<title>Preparing the System to Build &kde;</title>
+<sect2 id="before-building-users">
+<title>Setup a new user account</title>
+
<para>
-It is recommended that you download and build &kde; using a user
+It is recommended that you download and build &kde; using a separate user
account. If you already have &kde; packages installed, the best choice
would be to create a different (dedicated) user to build and run the new &kde;.
The advantage of building &kde; with a dedicated user is you can not break
@@ -11,24 +14,67 @@ things go wrong.
</para>
<para>
-Later, you can do a root installation if you wish. This document
-does not cover a root installation. If you are performing a system
-wide install, you probably already know what you are doing anyway.
+Later, you can do a system installation if you wish. This document
+does not cover a system installation. If you are performing a system
+wide install, you should already know what you are doing. If not, then you
+may want to consult the documentation, or help sites, for your distribution
+in order to prepare and use the system installation correctly.
</para>
+</sect2>
+<sect2 id="before-building-preparation">
+<title>Ensure your system is ready to build &kde; source</title>
+
<para>Before using the &kdesvn-build; script (or any other building
strategy) you must install the development tools and libraries needed for &kde;.
-You need the Qt library, version 3.3.0 or greater, Automake 1.8,
-Autoconf 2.5X (better if >=2.57 as a bug was reported with lower versions),
-the subversion (svn) client, the gcc compiler with C++ support, libxml2,
-openssl, libbz2, and many more (for a complete list, visit the
-<ulink url="http://www.kde.org/info/requirements/3.4.php">KDE Compilation
-Requirements</ulink>). You can usually get those tools packaged for your system
-from your distribution or vendor.
+The complete list of required tools can be found from the
+<ulink url="http://www.kde.org/info/requirements/3.5.php">&kde; Compilation
+Requirements</ulink> page.
+</para>
+
+<para>Here is a list of some of the things you'll need:</para>
+<itemizedlist>
+<listitem><para>Automake version 1.7, or higher.</para></listitem>
+<listitem><para>Autoconf version 2.57, or higher.</para></listitem>
+<listitem><para>The &svn; client program, including support for Secure
+HTTP (https). To ensure needed support, you can run
+<userinput><command>svn <option>--version</option></command></userinput>.
+If the ra_dav module says that it handles the https scheme then you should be
+set to go.</para></listitem>
+<listitem><para>The gcc compiler, with support for C++. Version 3.3 or 3.4 works
+the best at this point.</para></listitem>
+<listitem><para>Be sure to check the <ulink
+url="http://www.kde.org/info/requirements/3.5.php">&kde; Compilation
+Requirements</ulink> page to make sure that any other needed libraries are
+included.</para></listitem>
+</itemizedlist>
+
+<para>One exception is the &Qt; library. &kdesvn-build; will normally install a
+copy of &Qt; whether you have it installed or not, so it's not necessary for you
+to have it. If you don't want to use the &Qt; copy, you need to do these things:
</para>
+<itemizedlist>
+<listitem>
+ <para>Make sure to remove the qt-copy module from your &rcfile;, as you
+ won't need it, and having it would add extra time to your build.</para>
+</listitem>
+
+<listitem>
+ <para>Change the setting of the <link linkend="conf-qtdir">qtdir</link>
+ option in your &rcfile; to point to your system &Qt;. This is normally
+ equal to the setting of $<envar>QTDIR</envar> for your system.</para>
+</listitem>
+
+<listitem>
+ <para>If you don't already have &Qt; installed, install it, including any
+ relevant -dev or -devel packages. You'll need at least &Qt; 3.3 if you're
+ building &kde; 3.5, or &Qt; 4.0 if you're building &kde; 4.</para>
+</listitem>
+</itemizedlist>
+
<para>
-Some of these packages are divided into libs, programs or utilities and
+Some of these packages are divided into libraries (or programs or utilities), and
development packages. You will need at least the program or library and
its development package. If in doubt, install all. The libraries you need
will change depending on the modules you intend to build, as each module
@@ -39,27 +85,67 @@ about the specific tools and techniques used to install and find the
required software.
</para>
+</sect2>
+
+<sect2 id="before-building-prepare-script">
+<title>Setup kdesvn-build</title>
+
+<sect3 id="get-kdesvn-build">
+<title>Install kdesvn-build</title>
<para>
You probably already have a version of the &kdesvn-build; script installed
-in your system. &kdesvn-build;requires you to create a configuration file, named
-<filename>.kdesvn-buildrc</filename>. This file should be installed on
-the home folder (~/), and contain all configuration data
+in your system. However, if you don't, you can download it from
+&homepage;, or you can find it from its home in the &kde; source
+repository.</para>
+
+<orderedlist>
+<listitem><para>To download &kdesvn-build; from its &homepage;, simply go to the
+&homepage; and download the latest appropriate release. The release is
+packaged as a compressed tarball archive, which you can extract using &ark; or
+<command>tar</command>. The contents of the archive include the actual
+&kdesvn-build; script, and a sample configuration file
+(<filename>kdesvn-buildrc-sample</filename>).</para></listitem>
+
+<listitem><para>Or, you can obtain &kdesvn-build; from its source repository,
+located at: <ulink url="http://websvn.kde.org/trunk/KDE/kdesdk/scripts/">http://websvn.kde.org/trunk/KDE/kdesdk/scripts/</ulink>.
+This is the &kde; Software Development Kit scripting directory, which is the
+home of &kdesvn-build;. You can click on the <filename>kdesvn-build</filename> entry which will
+bring you to a page where you can download the latest revision. Do so, and
+save it to a convenient spot on your hard disk. Do the same for <filename>kdesvn-buildrc-sample</filename>
+if you need to.</para></listitem>
+</orderedlist>
+
+<para>No matter which technique you use, you need to make sure that the
+<filename>kdesvn-build</filename> file is executable. For convenience you
+should make sure it is in a directory contained in the <envar>PATH</envar>
+environment variable, otherwise you may get messages saying that the command
+was not found.</para>
+</sect3>
+
+<sect3 id="setup-rcfile">
+<title>Prepare the configuration file</title>
+
+<para>Although &kdesvn-build; doesn't require you to create a &rcfile;, it
+makes the work flow much easier. Using a &rcfile;, you can control which
+modules are installed, or remove modules you don't want to install. &kdesvn-build;
+by default installs a useful &kde; installation using very generic installation
+flags, which may be different from your needs. So it is best to use a
+&rcfile;</para>
+
+<para>The &rcfile; should be called <filename>.kdesvn-buildrc</filename>.
+This file should be installed on
+the home folder (<filename>~/</filename>), and contain all configuration data
required for the script to run, like configuration options,
compiling options, location of the sources, the destination of the installation
(prefix), the modules that should be built, &etc;. The default configuration
-data is provided by the <filename>kdesvn-buildrc-sample</filename> file.
-You can find more information about the syntax of the configuration file
-in <xref linkend="configure-data" /> and in <xref linkend="kdesvn-buildrc" />.
+data is provided by the <filename>kdesvn-buildrc-sample</filename> file, which
+you can copy over as <filename>~/.kdesvn-buildrc</filename> and then edit.
</para>
-<para>
-A good way to get the latest version is to browse the kdesdk/scripts page
-at the <ulink url="http://websvn.kde.org/trunk/KDE">websvn.kde.org</ulink> website.
-You will see a list of the files available in the kdesdk/scripts directory in
-the &kde; &svn; repository. Click the &kdesvn-build; link and download
-the latest version of the script. Do the same for the
-<filename>kdesvn-buildrc-sample</filename> file.
-Make the script executable, and be sure it is in your path.
+<para>You can find more information about the syntax of the &rcfile;
+in <xref linkend="configure-data" /> and in <xref linkend="kdesvn-buildrc" />.
</para>
+</sect3>
+</sect2>
</sect1>
diff --git a/doc/getting-started/building-and-troubleshooting.docbook b/doc/getting-started/building-and-troubleshooting.docbook
index 53379bff..6472d0bc 100644
--- a/doc/getting-started/building-and-troubleshooting.docbook
+++ b/doc/getting-started/building-and-troubleshooting.docbook
@@ -12,16 +12,32 @@ the script:
</para>
<para>
-Now, the script should start downloading the sources and compiling them. It is
-unlikely that you will succeed in the first time you compile &kde;. Do not despair!
-Check the log files to see if you are missing some tools or development packages
-(the location of the log files is set by the log-dir variable in the configuration
-file). Sometimes, the main development branch get very unstable and hard to build,
-especially when a development freeze is close. Be patient. You can find more common
-examples of things that can go wrong and their solutions, as well as general tips and
-strategies to build &kde; in the
+Now, the script should start downloading the sources and compiling them. Depending on
+how many modules you are downloading, it is possible that &kdesvn-build;
+will not succeed the first time you compile &kde;. Do not despair!
+</para>
+
+<para>&kdesvn-build; logs the output of every command it runs. By default,
+the log files are kept in <filename>~/kdesvn/log</filename>. To see what
+the caused an error for a module in the last &kdesvn-build; command, usually
+it is sufficient to look at <filename>~/kdesvn/log/latest/<replaceable>module-name</replaceable>/error.log</filename>.</para>
+
+<para>In that file, you will see the error that caused the build to fail for
+that module. If the file says (at the bottom) that you're missing some packages,
+try installing the package (including any appropriate -dev packages) before
+trying to build that module. Or, if the error appears to be a build error
+then it is probably an error with the &kde; source, which will hopefully be
+resolved within a few days. If it isn't resolved within that time, feel free
+to mail the <email>kde-devel at kde.org</email> (subscription may be required first)
+in order to report the build failure.</para>
+
+<para>You can find more common examples of things that can go wrong and their
+solutions, as well as general tips and strategies to build &kde; in the
<ulink url="http://quality.kde.org/develop/cvsguide/buildstep.php#step1">
Building &kde; from Source Step by Step Guide</ulink>.
</para>
+<note><para>For more information about &kdesvn-build;'s logging features,
+please see <xref linkend="kdesvn-build-logging"/>.</para></note>
+
</sect1>
diff --git a/doc/getting-started/configure-data.docbook b/doc/getting-started/configure-data.docbook
index b734495b..3d3f92bc 100644
--- a/doc/getting-started/configure-data.docbook
+++ b/doc/getting-started/configure-data.docbook
@@ -2,38 +2,51 @@
<title>Setting the Configuration Data</title>
<para>
-To use the script, you must have a file in your home directory called
+To use &kdesvn-build;, you should have a file in your home directory called
<filename>.kdesvn-buildrc</filename>, which sets the general options and sets the modules
you would like to download and build.
</para>
+<note><para>It is possible to use different configuration files for &kdesvn-build;,
+which is described in <xref linkend="kdesvn-buildrc" />. If you need to use
+multiple configurations, please see that section. Here, we will assume the
+configuration is stored in <filename>~/.kdesvn-buildrc</filename>.</para></note>
+
<para>
-Use the <filename>kdesvn-buildrc-sample</filename> file as a
-template, setting global options, and the modules you want to build.
+The easiest way to proceed is to use the
+<filename>kdesvn-buildrc-sample</filename> file as a template, changing global
+options to match your wants, and also change the list of modules you want to
+build.
</para>
<para>
-Select the server used to check out from &svn;, by setting the svn-server
-global option. The default is the anonymous &svn; repository,
-<emphasis>svn://anonsvn.kde.org/</emphasis>, but change it
-if you have a <ulink url="http://developer.kde.org/documentation/misc/firststepsaccount">&kde;
-&svn; account</ulink>, or if there is <ulink url="http://developer.kde.org/source/anonsvn.html">
-a mirror close to you</ulink>.
+The default settings should actually already be appropriate to perform a
+&kde; build. Some settings that you may wish to alter include:
+
+<itemizedlist>
+<listitem><para><link linkend="conf-binpath">binpath</link>, to change the list of
+directories that will be searched for commands. This is exactly the same as
+the <envar>PATH</envar> variable in the shell.</para></listitem>
+<listitem><para><link linkend="conf-kdedir">kdedir</link>, which changes the
+destination directory that &kde; is installed to. This defaults to
+<filename>~/kde</filename>, which is a single-user installation.</para></listitem>
+<listitem><para><link linkend="conf-qtdir">qtdir</link>, which controls the
+path to the installation of &Qt; to use. The defaults to using the qt-copy
+module from the &kde; &svn; repository. (<filename>~/kdesvn/build/qt-copy</filename>)</para></listitem>
+<listitem><para><link linkend="conf-svn-server">svn-server</link>, which
+selects what URL to download the sources from. This is useful if you are a
+developer with a <ulink url="http://developer.kde.org/documentation/misc/firststepsaccount.php">&kde;
+&svn; account</ulink>.</para></listitem>
+</itemizedlist>
</para>
<para>
-Pay close attention to the kdedir and qtdir global variables, as the first sets
-where your &kde; build is going to be installed, (by default to
-<filename>~/kde</filename>), and the second where (and if) your qt library is
-going to be built and installed, (by default to
-<filename>~/kdesvn/build/qt-copy</filename>). You will need to know the
-kdedir and qtdir location later, to set up the environment variables
-that are necessary to run your new installation.
-Check if the listed modules are in fact the modules you want to build.
-The default options from the <filename>kdesvn-buildrc-sample</filename> file
-should be enough to get a fairly complete &kde; installation.
-Save the resulting as <filename>.kdesvn-buildrc</filename> in your home
-folder.
+After the global section is a list of modules to build, bracketed by
+module ... end module lines. Check if the listed modules are in fact the
+modules you want to build. The default options from the
+<filename>kdesvn-buildrc-sample</filename> file should be enough to get a
+fairly complete &kde; installation. Save the result as
+<filename>.kdesvn-buildrc</filename> in your home folder.
</para>
<para>
diff --git a/doc/getting-started/environment.docbook b/doc/getting-started/environment.docbook
index 0f5e64c0..04645386 100644
--- a/doc/getting-started/environment.docbook
+++ b/doc/getting-started/environment.docbook
@@ -8,34 +8,59 @@ has to take precedence over the old. Change the environment variables to
make sure it does.
</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-copy module (you are by default), add instead:
+
<programlisting>
-KDEDIR=(path to kdedir)
+QTDIR=(path to qtdir) # Such as ~/kdesvn/build/qt-copy by default.
+KDEDIR=(path to kdedir) # Such as ~/kde by default.
KDEDIRS=$KDEDIR
PATH=$KDEDIR/bin:$QTDIR/bin:$PATH
-LD_LIBRARY_PATH=$KDEDIR/lib:$LD_LIBRARY_PATH
-export KDEDIRS PATH LD_LIBRARY_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=$KDEDIR/lib:$QTDIR/lib
+else
+ LD_LIBRARY_PATH=$KDEDIR/lib:$QTDIR/lib:$LD_LIBRARY_PATH
+fi
+
+export QTDIR KDEDIRS PATH MANPATH LD_LIBRARY_PATH
</programlisting>
-If you are building the qt-copy module, add instead:
+or, if you are not building qt-copy (and are using your system &Qt; instead), add
+this instead:
<programlisting>
-QTDIR=(path to qtdir)
-KDEDIR=(path to kdedir)
+KDEDIR=(path to kdedir) # Such as ~/kde by default.
KDEDIRS=$KDEDIR
PATH=$KDEDIR/bin:$QTDIR/bin:$PATH
-MANPATH=$QTDIR/doc/man:$MANPATH
-LD_LIBRARY_PATH=$KDEDIR/lib:$QTDIR/lib:$LD_LIBRARY_PATH
-export QTDIR KDEDIRS PATH MANPATH LD_LIBRARY_PATH
+
+# Act appropriately if LD_LIBRARY_PATH is not already set.
+if [ -z $LD_LIBRARY_PATH ]; then
+ LD_LIBRARY_PATH=$KDEDIR/lib
+else
+ LD_LIBRARY_PATH=$KDEDIR/lib:$LD_LIBRARY_PATH
+fi
+
+export KDEDIRS 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>:
+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-svn"
@@ -47,8 +72,9 @@ export KDEHOME="${HOME}/.kde-svn"
<note>
<para>
-If later your menu is empty or too crowded with applications from your distribution,
-you may have to set the xdg environment variables in your <filename>.bash_profile</filename>:
+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"
@@ -59,49 +85,81 @@ export XDG_CONFIG_DIRS XDG_DATA_DIRS
</para>
</note>
+</sect2>
+<sect2 id="starting-kde">
+<title>Starting &kde;</title>
+
<para>
-Now that we are done with the you have to make sure that the right <application>startkde</application>
-script is going to be used:
+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 (or <filename>.xsession</filename>,
-depending on the distribution) from the home directory, or create it if necessary. Add the
-line:
+Open the <filename>.xinitrc</filename> text file from the home directory, or
+create it if necessary. Add the line:
<programlisting>
-exec ${KDEDIR}/bin/startkde
+<command>exec</command> <option>${KDEDIR}/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
+&kdm;, <application>gdm</application>, or <application>xdm</application>.</para>
+</important>
+
<para>
-Now start your fresh &kde;: in BSD and Linux systems with virtual terminal support,
-Ctrl+Alt+F1...F12 keystroke combinations are used to switch to Virtual Console 1 through 12.
+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 boot 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. Press Crtl + Alt + F2,
-and you will be presented to a text terminal. Log in using the dedicated user and type:
+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 &kdm;, have an option to use
+a "Custom Session" 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 doesn't, there's 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>
-startx -- :1
+<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 Crtl + Alt + F2 (or F1, F3, etc..), and you will be presented
-to a text terminal. Log in using the dedicated user and type "startx -- :1". You can go back to the
-regular user by pressing Crtl + Alt + F6 (Or F7, F8, etc... Try them out! One of them is the right
-one.) To return to KDE from sources, press Crtl + Alt + F7 (or F6, F8,etc..). Now you can switch
-between your KDE versions, and test the new one knowing you can quickly return to the safety of
-the stable KDE desktop.
-</para>
-</tip>
+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; &svn; 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
+&kdesvn-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 &kdesvn-build; &kde;.</para>
+</tip>
+</sect2>
</sect1>
diff --git a/doc/getting-started/index.docbook b/doc/getting-started/index.docbook
index fe4124d1..44d8059f 100644
--- a/doc/getting-started/index.docbook
+++ b/doc/getting-started/index.docbook
@@ -11,8 +11,8 @@ In this chapter, we show how to use the &kdesvn-build; to checkout modules from
All topics present in this chapter are covered with even more detail in the
<ulink url="http://quality.kde.org/develop/cvsguide/buildstep.php">
Building &kde; from Source Step by Step Guide</ulink>, at the
-<ulink url="http://quality.kde.org">&kde; Quality Team Website</ulink>.
-If you are compiling KDE for the first time, it is a good idea to read
+<ulink url="http://quality.kde.org">&kde; Quality Team Web site</ulink>.
+If you are compiling &kde; for the first time, it is a good idea to read
it, or consult it as a reference source. You will find detailed information
about packaging tools and requirements, common compilation pitfalls and
strategies and information about running your new &kde; installation.
diff --git a/doc/index.docbook b/doc/index.docbook
index c0f2e646..a1916dfc 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -6,6 +6,53 @@
<!ENTITY % English "INCLUDE"> <!-- Change language only here -->
<!ENTITY svn "<application>Subversion</application>">
<!ENTITY kdesvn-build "<application>kdesvn-build</application>">
+ <!ENTITY rcfile '<link linkend="configure-data">configuration file</link>'>
+ <!ENTITY cmd-line-option '<link linkend="cmdline">command line option</link>'>
+ <!ENTITY homepage '<ulink url="http://kdesvn-build.kde.org/">&kdesvn-build; home page</ulink>'>
+ <!ENTITY unsermake '<ulink url="http://www.kde.me.uk/index.php&page=unsermake"><application>unsermake</application></ulink>'>
+ <!ENTITY BSD '<acronym>BSD</acronym>'>
+
+ <!-- These define shortcut entities for some of the configuration options.
+ Just add them as necessary.
+ -->
+
+ <!ENTITY configure-flags '<link linkend="conf-configure-flags">configure-flags</link>'>
+ <!ENTITY apply-qt-patches '<link linkend="conf-apply-qt-patches">apply-qt-patches</link>'>
+ <!ENTITY kdedir '<link linkend="conf-kdedir">kdedir</link>'>
+ <!ENTITY qtdir '<link linkend="conf-qtdir">qtdir</link>'>
+ <!ENTITY build-dir '<link linkend="conf-build-dir">build-dir</link>'>
+ <!ENTITY module-base-path '<link linkend="conf-module-base-path">module-base-path</link>'>
+ <!ENTITY override-url '<link linkend="conf-override-url">override-url</link>'>
+ <!ENTITY source-dir '<link linkend="conf-source-dir">source-dir</link>'>
+ <!ENTITY email-address '<link linkend="conf-email-address">email-address</link>'>
+ <!ENTITY email-on-compile-error '<link linkend="conf-email-on-compile-error">email-on-compile-error</link>'>
+ <!ENTITY colorful-output '<link linkend="conf-colorful-output">colorful-output</link>'>
+ <!ENTITY tag '<link linkend="conf-tag">tag</link>'>
+ <!ENTITY apidox '<link linkend="conf-apidox">apidox</link>'>
+ <!ENTITY branch '<link linkend="conf-branch">branch</link>'>
+ <!ENTITY no-rebuild-on-fail '<link linkend="conf-no-rebuild-on-fail">no-rebuild-on-fail</link>'>
+ <!ENTITY inst-apps '<link linkend="conf-inst-apps">inst-apps</link>'>
+ <!ENTITY do-not-compile '<link linkend="conf-do-not-compile">do-not-compile</link>'>
+ <!ENTITY checkout-only '<link linkend="conf-checkout-only">checkout-only</link>'>
+ <!ENTITY svn-server '<link linkend="conf-svn-server">svn-server</link>'>
+ <!ENTITY make-install-prefix '<link linkend="conf-make-install-prefix">make-install-prefix</link>'>
+ <!ENTITY niceness '<link linkend="conf-niceness">niceness</link>'>
+ <!ENTITY set-env '<link linkend="conf-set-env">set-env</link>'>
+ <!ENTITY libpath '<link linkend="conf-libpath">libpath</link>'>
+ <!ENTITY binpath '<link linkend="conf-binpath">binpath</link>'>
+ <!ENTITY use-unsermake '<link linkend="conf-use-unsermake">use-unsermake</link>'>
+
+ <!-- These define shortcut entities for some of the command line options.
+ Just add them as necessary.
+ -->
+ <!ENTITY cmd-nice '<link linkend="cmdline-nice">--nice</link>'>
+ <!ENTITY cmd-ignore-modules '<link linkend="cmdline-ignore-modules">--ignore-modules</link>'>
+ <!ENTITY cmd-resume-from '<link linkend="cmdline-resume-from">--resume-from</link>'>
+ <!ENTITY cmd-no-rebuild-on-fail '<link linkend="cmdline-no-rebuild-on-fail">--no-rebuild-on-fail</link>'>
+ <!ENTITY cmd-reconfigure '<link linkend="cmdline-reconfigure">--reconfigure</link>'>
+ <!ENTITY cmd-refresh-build '<link linkend="cmdline-refresh-build">--refresh-build</link>'>
+
+ <!ENTITY ssh '<application>SSH</application>'>
<!ENTITY introduction SYSTEM "introduction/index.docbook">
<!ENTITY getting-started SYSTEM "getting-started/index.docbook">
<!ENTITY before-building SYSTEM "getting-started/before-building.docbook">
@@ -13,8 +60,16 @@
<!ENTITY building-and-troubleshooting SYSTEM "getting-started/building-and-troubleshooting.docbook">
<!ENTITY environment SYSTEM "getting-started/environment.docbook">
<!ENTITY features SYSTEM "features/index.docbook">
+ <!ENTITY features-overview SYSTEM "features/features-overview.docbook">
+ <!ENTITY kdesvn-build-logging SYSTEM "features/kdesvn-build-logging.docbook">
<!ENTITY kdesvn-buildrc SYSTEM "kdesvn-buildrc/index.docbook">
<!ENTITY cmdline SYSTEM "cmdline/index.docbook">
+ <!ENTITY using-kdesvn-build SYSTEM "using-kdesvn-build/index.docbook">
+ <!ENTITY using-kdesvn-build-preface SYSTEM "using-kdesvn-build/using-kdesvn-build-preface.docbook">
+ <!ENTITY basic-features SYSTEM "using-kdesvn-build/basic-features.docbook">
+ <!ENTITY advanced-features SYSTEM "using-kdesvn-build/advanced-features.docbook">
+ <!ENTITY developer-features SYSTEM "using-kdesvn-build/developer-features.docbook">
+ <!ENTITY other-features SYSTEM "using-kdesvn-build/other-features.docbook">
<!ENTITY credits-and-licenses SYSTEM "credits-and-licenses/index.docbook">
]>
@@ -39,7 +94,7 @@
</authorgroup>
<copyright>
-<year>2005</year>
+<year>2006</year>
<holder>Michael Pyne</holder>
</copyright>
@@ -51,11 +106,11 @@
<legalnotice>&FDLNotice;</legalnotice>
-<date>2005-06-18</date>
-<releaseinfo>0.98</releaseinfo>
+<date>2006-01-04</date>
+<releaseinfo>1.0.0</releaseinfo>
<abstract>
-<para>The &kdesvn-build; is a Perl script which builds and installs &kde; directly from the sources found in the &kde; &svn; repository.</para>
+<para>&kdesvn-build; is a script which builds and installs &kde; directly from the sources found in the &kde; &svn; repository.</para>
</abstract>
<keywordset>
@@ -68,7 +123,6 @@
</bookinfo>
-
&introduction;
&getting-started;
@@ -79,6 +133,8 @@
&cmdline;
+&using-kdesvn-build;
+
&credits-and-licenses;
</book>
diff --git a/doc/introduction/index.docbook b/doc/introduction/index.docbook
index 04030117..26658967 100644
--- a/doc/introduction/index.docbook
+++ b/doc/introduction/index.docbook
@@ -2,18 +2,19 @@
<title>Introduction</title>
<para>
-&kdesvn-build; is a Perl script to help users install <ulink
-url="http://www.kde.org/">&kde;</ulink> from <ulink
-url="http://subversion.tigris.org/">&svn;</ulink>. You may also want to
-consider the kde-build script include with &kde;'s kdesdk module.
+&kdesvn-build; is a script to help users install <ulink
+url="http://www.kde.org/">&kde;</ulink> from its <ulink
+url="http://subversion.tigris.org/">&svn;</ulink> source repository.
</para>
<para>
-Here we document the &kdesvn-build; configuration file syntax and options, its
-command line options, features, and an overview of all necessary steps required
-to build &kde; from source, including the steps which you should perform using
-other tools, or in other words, steps that are not automatically performed
-by the &kdesvn-build; script.
+Here we document the &kdesvn-build; &rcfile; syntax and options, its <link
+linkend="cmdline">command line options</link>, <link
+linkend="features">features</link>, and an <link
+linkend="getting-started">overview</link> of all necessary steps required to
+build &kde; from source, including the steps which you should perform using
+other tools, or in other words, steps that are not automatically performed by
+the &kdesvn-build; script.
</para>
</chapter>
diff --git a/doc/kdesvn-buildrc/index.docbook b/doc/kdesvn-buildrc/index.docbook
index c2a45122..cfd2a38a 100644
--- a/doc/kdesvn-buildrc/index.docbook
+++ b/doc/kdesvn-buildrc/index.docbook
@@ -7,8 +7,6 @@ To use the script, you must have a file in your home directory called
like to download and build.
</para>
-
-
<para>
It starts with the global options, specified like the following:
</para>
@@ -59,7 +57,8 @@ authors using the address you can find <link linkend="authors">above</link>.
<listitem><para><link linkend="conf-do-not-compile">do-not-compile</link>, to mark directories to skip building.</para></listitem>
<listitem><para><link linkend="conf-inst-apps">inst-apps</link>, to only build and install some directories.</para></listitem>
<listitem><para><link linkend="conf-install-after-build">install-after-build</link>, to avoid installing after the build process.</para></listitem>
-<listitem><para><link linkend="conf-kdedir">kdedir</link>, to set the directory to install KDE to.</para></listitem>
+<listitem><para><link linkend="conf-kdedir">kdedir</link>, to set the directory to install &kde; to.</para></listitem>
+<listitem><para><link linkend="conf-kde-languages">kde-languages</link>, to set the translation packages to download and install.</para></listitem>
<listitem><para><link linkend="conf-libpath">libpath</link>, to set the <envar>LD_LIBRARY_PATH</envar> variable.</para></listitem>
<listitem><para><link linkend="conf-make-install-prefix">make-install-prefix</link>, to run a helper program (like sudo) during make install.</para></listitem>
<listitem><para><link linkend="conf-make-options">make-options</link>, to pass options to the make program.</para></listitem>
@@ -68,12 +67,11 @@ authors using the address you can find <link linkend="authors">above</link>.
<listitem><para><link linkend="conf-module-base-path">module-base-path</link>, to change where to download the module from (useful for branches and tags).</para></listitem>
<listitem><para><link linkend="conf-niceness">niceness</link>, to change the CPU priority.</para></listitem>
<listitem><para><link linkend="conf-no-rebuild-on-fail">no-rebuild-on-fail</link>, to avoid running make again if it fails.</para></listitem>
-<listitem><para><link linkend="conf-qtdir">qtdir</link>, to set the path to Qt.</para></listitem>
+<listitem><para><link linkend="conf-qtdir">qtdir</link>, to set the path to &Qt;.</para></listitem>
<listitem><para><link linkend="conf-set-env">set-env</link>, to set an environment variable.</para></listitem>
<listitem><para><link linkend="conf-source-dir">source-dir</link>, to change where to download the source code to.</para></listitem>
<listitem><para><link linkend="conf-stop-on-failure">stop-on-failure</link>, to make kdesvn-build stop as soon as a failure is encountered.</para></listitem>
<listitem><para><link linkend="conf-svn-server">svn-server</link>, to change the server the sources are downloaded from.</para></listitem>
-<listitem><para><link linkend="conf-use-qt-builddir-hack">use-qt-builddir-hack</link>, to give Qt a separate build directory from its source like KDE.</para></listitem>
<listitem><para><link linkend="conf-use-unsermake">use-unsermake</link>, to use the advanced unsermake build system.</para></listitem>
</itemizedlist>
@@ -101,10 +99,15 @@ as well.
<row id="conf-apidox">
<entry>apidox</entry>
<entry>Overrides global</entry>
-<entry>Set this option to <quote>true</quote> in order to have &kdesvn-build; automatically
+<entry><para>
+Set this option to <quote>true</quote> in order to have &kdesvn-build; automatically
build and install the API documentation for the module after the normal build/install
process. This only works for modules where <command>make apidox</command> does something,
including kdelibs, kdebase, and koffice, among others.
+</para>
+<para>This option does not work for modules using &unsermake; support, due to
+deficiencies in the unsermake build system.
+</para>
</entry>
</row>
@@ -114,7 +117,7 @@ including kdelibs, kdebase, and koffice, among others.
<entry>This option is only useful for qt-copy. If it is set to a non-zero value,
then the apply-patches script in qt-copy will be run prior to building, in
order to apply the non-official patches to the qt-copy. Since these patches
-are normally the reason for using qt-copy instead of a stock Qt, it shouldn't
+are normally the reason for using qt-copy instead of a stock &Qt;, it shouldn't
do any harm to enable it. The default is to enable the patches.</entry>
</row>
@@ -134,12 +137,12 @@ may use the tilde (~) for any paths you add using this option.</para>
<row id="conf-branch">
<entry>branch</entry>
<entry>Overrides global</entry>
-<entry><para>Set this option to checkout from a branch of KDE instead of the
-default of "trunk", where KDE development occurs. For instance, to checkout
-KDE 3.4 branch, you would set this option to "3.4".</para>
+<entry><para>Set this option to checkout from a branch of &kde; instead of the
+default of "trunk", where &kde; development occurs. For instance, to checkout
+&kde; 3.4 branch, you would set this option to "3.4".</para>
<para>Note that some modules use a different branch name. Notably, the
-required arts module doesn't go by KDE version numbers. The arts that
-accompanied KDE 3.4 was version 1.4.</para>
+required arts module doesn't go by &kde; version numbers. The arts that
+accompanied &kde; 3.4 was version 1.4.</para>
<para>If kdesvn-build fails to properly download a branch with this option, you
may have to manually specify the URL to download from using the <link
linkend="conf-override-url">override-url</link> option.</para>
@@ -203,7 +206,7 @@ set of configure options than the rest of &kde;, so this option
<entry>Set this option to false to disable the colorful output of &kdesvn-build;.
This option defaults to <quote>true</quote>. Note that &kdesvn-build; won't output the
color codes to anything but a terminal (such as xterm, &konsole;, or the normal
-Linux console).
+&Linux; console).
</entry>
</row>
@@ -233,7 +236,7 @@ extragear-network using this option.
<entry>Normally if you're using SSH to download the Subversion sources (such as
if you're using the svn+ssh protocol), kdesvn-build will try and make sure that
if you're using ssh-agent, it is actually managing some SSH identities. This is
-to try and prevent SSH from asking for your passphrase for every module. You can
+to try and prevent SSH from asking for your pass phrase for every module. You can
disable this check by setting disable-agent-check to true.
</entry>
</row>
@@ -244,7 +247,7 @@ disable this check by setting disable-agent-check to true.
<entry><para>Use this option to set the <envar>DO_NOT_COMPILE</envar> environment variable prior to
running the configure script. According to the <ulink
url="http://developer.kde.org/documentation/other/developer-faq.html">&kde;
-Developer FAQ</ulink>, this should cause any toplevel directory you pass to not be
+Developer FAQ</ulink>, this should cause any top-level directory you pass to not be
built. The directories should be space-separated.</para>
<para>Note that the sources to the programs will still be downloaded. You can use
@@ -290,7 +293,7 @@ is usually not what you want.
<entry>Overrides global</entry>
<entry><para>This is the opposite of the <link
linkend="conf-do-not-compile">do-not-compile</link> option. This option makes it
-so that only the given toplevel directories are built. The directories should
+so that only the given top-level directories are built. The directories should
be space-separated.</para>
<para>Any changes don't take effect until the next time
@@ -311,7 +314,7 @@ directive to choose directories that you want to check out.</para>
<entry>Overrides global</entry>
<entry>This option is used to install the package after it successfully builds.
This option is enabled by default. If you want to disable this, you need to
-set this option to 0 in the configuration file. You can also use the
+set this option to 0 in the &rcfile;. You can also use the
<link linkend="cmdline-no-install"><option>--no-install</option></link> command line flag.
</entry>
</row>
@@ -325,6 +328,29 @@ needing root access, you may want to read about the <link
linkend="conf-make-install-prefix">make-install-prefix</link> option as well.</entry>
</row>
+<row id="conf-kde-languages">
+<entry>kde-languages</entry>
+<entry>Can't be overridden</entry>
+<entry><para>This option allows you to choose to download and install localization
+packages along with &kde;. You might do this if you do not live in the United
+States and would like to &kde; translated into your native language.</para>
+
+<para>To use this option, set it to a space-separated list of languages to
+install. Each language has a language code associated with it, which you
+can look up at this page: <ulink
+url="http://i18n.kde.org/teams/">http://i18n.kde.org/teams/</ulink>.
+</para>
+
+<para>It is alright to choose only one language. By default, none are downloaded,
+which means &kde; will display in American English.</para>
+
+<para>For instance, to choose to install French, you would set the option to
+something like: <userinput><option>kde-languages</option> <replaceable>fr</replaceable></userinput>.
+You would still need to use &kcontrol; in order to choose the
+French language, however.</para>
+</entry>
+</row>
+
<row id="conf-libpath">
<entry>libpath</entry>
<entry>Can't be overridden</entry>
@@ -398,7 +424,7 @@ following template:
<varname>$svn-server</varname>/home/kde/<varname>$module-base-path</varname>/<varname>$module-name</varname>.
</para>
<para>The default value is either <quote>trunk</quote> or
-<quote>trunk/KDE</quote>, depending on the modulename.</para>
+<quote>trunk/KDE</quote>, depending on the module name.</para>
</entry>
</row>
@@ -423,7 +449,7 @@ effect of a stray &svn; update messing up the build system.</entry>
<entry>override-url</entry>
<entry>Overrides global</entry>
<entry>If you set this option, kdesvn-build will use its value as the URL
-to pass to Subversion <emphasis>completely unchanged</emphasis>. You should
+to pass to &svn; <emphasis>completely unchanged</emphasis>. You should
generally use this if you want to download a specific release but kdesvn-build
can't figure out what you mean using <link linkend="conf-branch">branch</link>.
</entry>
@@ -458,7 +484,7 @@ installed.
</para>
<para>Note that using this option can have a significant detrimental impact on
-both your bandwidth usage (if you use 'all') and the time taken to compile KDE,
+both your bandwidth usage (if you use 'all') and the time taken to compile &kde;,
since kdesvn-build will be unable to perform incremental builds.</para>
</entry>
</row>
@@ -472,7 +498,7 @@ want the variable set to. For example, to set the variable RONALD to
McDonald, you would put in the appropriate section this command:</para>
<screen><command>set-env</command> <envar>RONALD</envar> <userinput>McDonald</userinput></screen>
<para>This option is special in that it can be repeated without overriding
-earlier set-env settings in the same section of the configuration file. This
+earlier set-env settings in the same section of the &rcfile;. This
way you can set more than one environment variable per module (or
globally).</para>
</entry>
@@ -509,11 +535,11 @@ by default.
<entry>Overrides global</entry>
<entry><para>Use this option to download a specific release of a module.</para>
<para><emphasis>NOTE:</emphasis> The odds are very good that you DO NOT WANT
-to use this option. KDE releases are available in tarball form from <ulink
-url="ftp://ftp.kde.org/">The KDE FTP site</ulink> or one of <ulink
+to use this option. &kde; releases are available in tarball form from <ulink
+url="ftp://ftp.kde.org/">The &kde; FTP site</ulink> or one of <ulink
url="http://download.kde.org/download.php">its mirrors</ulink>.</para>
<para>If you are using kdesvn-build because you have having trouble getting
-a KDE release to build on your distribution, consider using the <ulink
+a &kde; release to build on your distribution, consider using the <ulink
url="http://developer.kde.org/build/konstruct/">Konstruct build tool</ulink>
instead, which works from the release tarballs.</para>
</entry>
@@ -538,6 +564,29 @@ This option defaults to <quote>true</quote>.
</entry>
</row>
+<row id="conf-use-stable-kde">
+<entry>use-stable-kde</entry>
+<entry>Can't be overridden</entry>
+<entry><para>Since &kdesvn-build; has support for building &kde; 3 and 4, there
+needs to be some way to tell which version to build. By default, &kdesvn-build;
+will build the main line of &kde; development (called /trunk). But, this is
+for &kde; 4, which isn't yet ready for wide release.
+</para>
+
+<para>You can use the &branch; option globally or for a module in order to
+download for &kde; 3.5 (or 3.4, etc.). However, this isn't convenient as some
+modules (such as kdesupport) are shared by 3.5 and 4. In addition, it is a
+lot of branch options that must be added to the configuration file.</para>
+
+<para>So, if you set this global option to <option>true</option>, &kdesvn-build;
+will automatically download the &kde; 3.5 version of modules such as kdelibs
+and qt-copy, instead of downloading the &kde; 4 version. You can still use
+the &branch; or &tag; options for a module to override the setting that
+&kdesvn-build; picks. This way you can easily choose to download &kde; 3.5
+instead of the pre-release &kde; 4.</para>
+</entry>
+</row>
+
<row id="conf-use-unsermake">
<entry>use-unsermake</entry>
<entry>Overrides global</entry>
diff --git a/doc/using-kdesvn-build/advanced-features.docbook b/doc/using-kdesvn-build/advanced-features.docbook
new file mode 100644
index 00000000..31def4fa
--- /dev/null
+++ b/doc/using-kdesvn-build/advanced-features.docbook
@@ -0,0 +1,530 @@
+<sect1 id="advanced-features">
+<title>Advanced features</title>
+
+<sect2 id="partial-builds">
+<title>Partially building a module</title>
+<para>It is possible to build only pieces from a single &kde; module. For
+example, you may want to compile only one program from a module. &kdesvn-build;
+has features to make this easy. There are several complementing ways to
+do this.
+</para>
+
+<sect3 id="checking-out-parts">
+<title>Checking out portions of a module</title>
+
+<para>This is perhaps the best way to do this. When it works, it will save you
+download time and disk space. What happens is that &kdesvn-build; will download
+only the parts of a module that you specify. This is done using the &checkout-only;
+option for a module, which will specify a list of directories to download.
+</para>
+
+<tip><para>
+If you don't already know what to download from a module, it may be a good idea
+to browse the Subversion layout for a module first, using
+<ulink url="http://websvn.kde.org/branches/KDE/3.5/">WebSVN</ulink>.
+</para></tip>
+
+<informalexample>
+<para>To only grab &kuser; and &kdat; from kdeadmin, you could use &checkout-only;
+like this:</para>
+
+<screen>
+module <replaceable>kdeadmin</replaceable>
+ &checkout-only; <replaceable>kuser kdat</replaceable>
+end module
+</screen>
+
+</informalexample>
+
+<important><para>The directories will be built in the order they are listed
+in the option. If one of the directories needs something else from the module
+to compile, then you need to make sure they are both in the &checkout-only;
+line, and that the required dependency goes before the directory that needs it.</para>
+
+<para>Also, sometimes an application may need other directories and it's hard
+to figure out what they are, which may require some trial and error of constantly
+adding directories to the option to figure out.</para>
+</important>
+
+<para>One final note to make about this option: If you change the value of this
+option, you should use <userinput><command>kdesvn-build</command>
+<option>&cmd-refresh-build;</option> <option><replaceable>module</replaceable></option></userinput>
+in order to ensure that the module is reconfigured properly. In addition,
+&kdesvn-build; will never remove existing files if you take away the number of
+directories from your &checkout-only; option, or add the option to a module that
+has already been checked out.</para>
+
+</sect3>
+
+<sect3 id="not-compiling">
+<title>Removing directories from a build</title>
+<para>Instead of restricting what is downloaded, it is possible to download
+everything but have the build system leave out a few directories when it does
+the build. This may be useful if one directory always breaks and is
+unnecessary to the rest of the module.
+</para>
+
+<para>This is controlled with the &do-not-compile; option. It works similar
+to the &checkout-only; option just described, in that it is simply a list of
+directories that should not be compiled.</para>
+
+<important><para>
+Also like &checkout-only;, this option requires at least that the
+<command>configure</command> script is run again for the module after changing
+it. This is done using the <userinput><command>kdesvn-build</command>
+<option>&cmd-reconfigure;</option>
+<option><replaceable>module</replaceable></option></userinput> command.
+</para></important>
+
+<informalexample>
+<para>To remove the dcoppython directory from the kdebindings build process:</para>
+
+<screen>
+module <replaceable>kdebindings</replaceable>
+ &do-not-compile; <replaceable>dcoppython</replaceable>
+end module
+</screen>
+</informalexample>
+
+</sect3>
+
+<sect3 id="limiting-using-inst-apps">
+<title>Compiling a few directories from a full module</title>
+
+<para>You can use the &inst-apps; option to specify that only a few directories
+out of a full module are to be built (but the entire module is still
+downloaded).
+</para>
+
+<para>This option is like the combination of &checkout-only; and &do-not-compile;:
+it downloads the entire module like &do-not-compile;, but only compiles the
+directories you specify, like &checkout-only;. Because of this it is usually
+better to simply use &checkout-only; instead.
+</para>
+
+<para>The same warnings apply as for the other two options, you must reconfigure
+the module if you change the value of &inst-apps;.
+</para>
+</sect3>
+
+</sect2>
+
+<sect2 id="using-unsermake">
+<title>Using &unsermake;</title>
+
+<para><application>unsermake</application> is an application designed to hook
+into the KDE build system and improve the build process by replacing some of
+the tools normally used (including <application>automake</application> and
+<application>make</application>). It is especially useful for those who
+are performing distributed compilation as it is much faster than the normal
+build system in this situation. However, even for a single computer build,
+unsermake is faster than the competition.
+</para>
+
+<para>In addition, unsermake includes support for estimating the progress of
+the current build procedure. &kdesvn-build; takes advantage of this to
+provide a build progress indication when compiling. See also <xref linkend='build-progress' />.
+</para>
+
+<para>&kdesvn-build; provides support for using <application>unsermake</application>
+automatically. &kdesvn-build; will use <application>unsermake</application>
+by default when it is possible to use it with a module.
+</para>
+
+<informalexample>
+<para>To disable <application>unsermake</application> support for every module,
+do the following:</para>
+
+<screen>
+global
+ use-unsermake false
+end global
+</screen>
+
+<para>To enable <application>unsermake</application> for a single module, even
+if it is disabled globally, do the following:</para>
+
+<screen>
+module <replaceable>module-name</replaceable>
+ use-unsermake true
+
+ # other options go here...
+end module
+</screen>
+</informalexample>
+
+<note><para>
+&kdesvn-build; will automatically update or checkout <application>unsermake</application>
+while performing the other updates. If you prefer to manage <application>unsermake</application>
+yourself, then it is possible to do so, by setting the value for &use-unsermake;
+to <symbol>self</symbol> instead of <symbol>true</symbol>.</para>
+
+<para>When this is done, &kdesvn-build; will still try to use
+<application>unsermake</application>, but will not perform the updates. You
+can either alter &binpath; to point to the correct unsermake directory, or
+checkout and update <application>unsermake</application> yourself from its
+module (currently kdenonbeta/unsermake).
+</para></note>
+
+</sect2>
+
+<sect2 id="using-branches">
+<title>Branching and tagging support for &kdesvn-build;</title>
+
+<sect3 id="branches-and-tags">
+<title>What are branches and tags?</title>
+
+<para>&svn; supports managing the history of the &kde; source code. &kde;
+uses this support to create branches for development, and to tag the repository
+every so often with a new version release.
+</para>
+
+<para>For example, the &kmail; developers may be working on a new feature in
+a different branch in order to avoid breaking the version being used by most
+developers. This branch has development ongoing inside it, even while the
+main branch (called /trunk) may have development going on inside of it.
+</para>
+
+<para>A tag, on the other hand, is a snapshot of the source code repository
+at a position in time. This is used by the &kde; administration team to mark
+off a version of code suitable for release and still allow the developers to
+work on the code.
+</para>
+
+<para>In &svn;, there is no difference between branches, tags, or trunk within
+the code. It is only a convention used by the developers. This makes it
+difficult to properly support branches and tags within &kdesvn-build;. However,
+there are some things that can be done.
+</para>
+
+</sect3>
+
+<sect3 id="branch-support">
+<title>How to use branches and tags</title>
+
+<para>Support for branches and tags is handled by a set of options, which
+range from a generic request for a version, to a specific URL to download
+for advanced users.
+</para>
+
+<para>The easiest method is to use the &branch; and &tag; options. You simply
+use the option along with the name of the desired branch or tag for a module,
+and &kdesvn-build; will try to determine the appropriate location within the
+&kde; repository to download from. For most &kde; modules this works very
+well.</para>
+
+<informalexample>
+<para>To download kdelibs from &kde; 3.5 (which is simply known as the 3.5 branch):
+</para>
+
+<screen>
+module kdelibs
+ branch <replaceable>3.5</replaceable>
+ # other options...
+end module
+</screen>
+
+<para>Or, to download kdemultimedia as it was released with &kde; 3.4.3:</para>
+
+<screen>
+module kdemultimedia
+ tag <replaceable>3.4.3</replaceable>
+ # other options...
+end module
+</screen>
+
+</informalexample>
+
+<tip><para>You can specify a global branch value. But if you do so, don't forget
+to specify a different branch for modules that shouldn't use the global branch!
+</para></tip>
+</sect3>
+
+<sect3 id="advanced-branches">
+<title>Advanced branch support options</title>
+
+<para>&kdesvn-build; supports two options for situations where &branch; and &tag;
+guess the correct path improperly: &module-base-path; and &override-url;
+</para>
+
+<itemizedlist>
+<listitem><para>
+module-base-path is used to help &kdesvn-build; fill in the missing part of
+a modules path. In the &kde; repository, all of the paths are of the form
+svnRoot/module-base-path/module-name. Normally &kdesvn-build; can figure out
+the appropriate middle part by itself. When it can't, you can use module-base-path,
+like this:
+</para>
+
+<informalexample>
+<screen>
+module qt-copy
+ # branch doesn't work here yet
+ module-base-path branches/qt/3.3
+end module
+</screen>
+
+<para>This would cause &kdesvn-build; to download qt-copy from (in this example),
+svn://anonsvn.kde.org/home/kde/<replaceable>branches/qt/3.3</replaceable>/qt-copy
+</para>
+</informalexample>
+</listitem>
+
+<listitem><para>The override-url option, on the other hand, requires you to
+specify the exact path to download from. However, this allows you to pull from
+paths that &kdesvn-build; would have no hope of downloading from.
+</para>
+
+<informalexample>
+<screen>
+module qt-copy
+ # Specify exact path to grab.
+ override-url svn://anonsvn.kde.org/home/kde/branches/qt/3.3/qt-copy
+end module
+</screen>
+</informalexample>
+
+<important><para>
+&kdesvn-build; will not touch or correct the value you specify for override-url
+at all, so if you change your &svn-server; setting, you may need to update this
+as well.
+</para></important>
+
+</listitem>
+</itemizedlist>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="building-successfully">
+<title>How &kdesvn-build; tries to ensure a successful build.</title>
+
+<sect3 id="automatic-rebuilds">
+<title>Automatic rebuilds</title>
+
+<para>Due to various issues with the &kde; build system, some of which
+are mitigated by using unsermake, &kdesvn-build; will automatically perform
+a series of steps to automatically try to get a module to compile when it
+fails.</para>
+
+<orderedlist>
+<listitem><para>On the first failure, &kdesvn-build; will simply re-run the
+<command>make</command>. Believe it or not, but this sometimes actually works,
+and is quick to fail if it won't work.
+</para></listitem>
+
+<listitem><para>
+On the second failure, &kdesvn-build; will try to reconfigure the module and
+then rebuild it. This usually catches situations where a build system file
+changed that requires reconfiguration but the build system did not perform that
+step automatically.
+</para>
+
+<para>The module build directory is left intact for this step, so except for the
+reconfigure step, this will also fail quickly if the build cannot be performed.
+</para>
+</listitem>
+
+<listitem><para>
+If the module still fails to build, &kdesvn-build; will give up and move on
+to the next module. There are still things that you can do to <link
+linkend="manual-rebuilds">manually try to get the module to build</link>,
+however.
+</para></listitem>
+</orderedlist>
+
+<note><para>
+&kdesvn-build; will detect most cases where the build system needs to be
+reconfigured and will reconfigure automatically in that case.
+</para>
+
+<para>Also, if &kdesvn-build; was building the module for the first time, all
+of these steps are skipped since the clean rebuild doesn't usually fail except
+for a real error.</para>
+</note>
+</sect3>
+
+<sect3 id="manual-rebuilds">
+<title>Manually rebuilding a module</title>
+<para>If you make a change to a module's option settings, or the module's
+source code changes in a way &kdesvn-build; doesn't recognize, you may need to
+manually rebuild the module.</para>
+
+<para>You can do this by simply running <userinput><command>kdesvn-build</command>
+ <option>--refresh-build</option> <option><replaceable>module</replaceable></option></userinput>
+</para>
+
+<para>If you would like to have &kdesvn-build; automatically rebuild the module
+during the next normal build update instead, you can create a special file.
+Every module has a build directory. If you create a file called <filename>.refresh-me</filename>
+in the build directory for a module, &kdesvn-build; will rebuild the module
+next time the build process occurs, even if it would normally perform the
+faster incremental build.</para>
+
+<tip>
+<para>By default, the build directory is <filename>~/kdesvn/build/<replaceable>module</replaceable>/</filename>.
+If you change the setting of the &build-dir; option, then use that instead of
+<filename>~/kdesvn/build</filename>.</para>
+</tip>
+
+<informalexample>
+<para>Rebuild using <filename>.refresh-me</filename> for module <replaceable>arts</replaceable></para>
+<screen>
+<prompt>%</prompt> <userinput><command>touch</command> <filename>~/kdesvn/build/<replaceable>arts</replaceable></filename></userinput>
+<prompt>%</prompt> <userinput><command>kdesvn-build</command></userinput>
+</screen>
+</informalexample>
+</sect3>
+
+<sect3 id="controlling-rebuild-behavior">
+<title>Controlling rebuild behavior</title>
+<para>You may not want &kdesvn-build; to always try and rebuild a module.
+You can permanently disable this behavior by changing the option &no-rebuild-on-fail;
+to have the value <userinput>true</userinput>.</para>
+
+<para>You can disable this behavior temporarily (for one command) by using
+the &cmd-no-rebuild-on-fail; command line option.</para>
+
+<informalexample>
+<screen>
+<prompt>%</prompt> <userinput><command>kdesvn-build</command> <option>--no-rebuild-on-fail</option></userinput>
+</screen>
+</informalexample>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="changing-environment">
+<title>Changing environment variable settings.</title>
+<para>&kdesvn-build; doesn't read the environment from the caller like the
+vast majority of most programs do. Instead, it uses the settings it reads
+from the &rcfile; to construct the environment. This is done mainly to
+ensure that when you build a module, the build is repeatable. In other words,
+&kdesvn-build; can build a module even if you forgot what you set your
+environment variables to in the shell you ran &kdesvn-build; from.</para>
+
+<para>However, you may want to change the setting for environment variables
+that &kdesvn-build; doesn't provide an option for directly.
+This is possible with the &set-env; option.</para>
+
+<para>Unlike most options, it can be set more than once, and it accepts two
+entries, separated by a space. The first one is the name of the environment
+variable to set, and the remainder of the line is the value.</para>
+
+<informalexample>
+<para>Set DISTRO=BSD for all modules:</para>
+<screen>
+global
+ set-env <replaceable>DISTRO</replaceable> <replaceable>BSD</replaceable>
+end global
+</screen>
+</informalexample>
+
+</sect2>
+
+<sect2 id="resuming">
+<title>Resuming builds</title>
+
+<sect3 id="resuming-failed">
+<title>Resuming a failed or canceled build</title>
+
+<para>You can tell &kdesvn-build; to start building from a different module
+than it normally would. This can be useful when a set of modules failed, or
+if you canceled a build run in the middle. You can control this using the
+&cmd-resume-from; option.</para>
+
+<note><para>Using &cmd-resume-from; will skip the source code update.</para>
+</note>
+
+<informalexample>
+<para>Resuming the build starting from kdebase.</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesvn-build</command> <option>--resume-from=<replaceable>kdebase</replaceable></option></userinput>
+</screen>
+</informalexample>
+
+</sect3>
+
+<sect3 id="ignoring-modules">
+<title>Ignoring modules in a build</title>
+
+<para>Similar to the way you can <link linkend="resuming-failed">resume the
+build from a module</link>, you can instead choose to update and build everything
+normally, but ignore a set of modules.</para>
+
+<para>You can do this using the &cmd-ignore-modules; option. This option tells
+&kdesvn-build; to ignore all the of rest of the modules on the command line when
+performing the update and build.</para>
+
+<informalexample>
+<para>Ignoring extragear/multimedia and kdenonbeta during a full run.</para>
+<screen>
+<prompt>%</prompt> <userinput><command>kdesvn-build</command> <option>--ignore-modules</option> <replaceable>extragear/multimedia kdenonbeta</replaceable></userinput>
+</screen>
+</informalexample>
+
+</sect3>
+</sect2>
+
+<sect2 id="changing-env-from-cmd-line">
+<title>Changing options from the command line</title>
+
+<sect3 id="changing-global-opts">
+<title>Changing global options</title>
+<para>You can change the setting of options read from the &rcfile; directly
+from the command line. This change will override the configuration file
+setting, but is only temporary. It only takes effect as long as it is still
+present on the command line.</para>
+
+<para>&kdesvn-build; allows you to change options named like <replaceable>option-name</replaceable>
+by passing an argument on the command line in the form <option>--<replaceable>option-name</replaceable>=value</option>.
+&kdesvn-build; will recognize if it doesn't know what the option is, and search
+for the name in its list of option names. If it doesn't recognize the name, it
+will warn you, otherwise it will remember the value you set it to and override
+any setting from the configuration file.</para>
+
+<informalexample>
+<para>Setting the &source-dir; option to <filename>/dev/null</filename> for
+testing.</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesvn-build</command> <option>--pretend</option> <option>--<replaceable>source-dir</replaceable>=<replaceable>/dev/null</replaceable></option></userinput>
+</screen>
+
+<para>Disabling unsermake from the command line. --refresh-build is used to
+force the changes to unsermake to take effect.</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesvn-build</command> <option>--pretend</option> <option>--refresh-build</option> <option>--<replaceable>use-unsermake</replaceable>=<replaceable>false</replaceable></option></userinput>
+</screen>
+
+</informalexample>
+
+</sect3>
+
+<sect3 id="changing-module-opts">
+<title>Changing module options</title>
+<para>It is also possible to change options only for a specific module. The
+syntax is similar: --<replaceable>module</replaceable>,<replaceable>option-name</replaceable>=<replaceable>value</replaceable>.
+</para>
+
+<para>This change overrides any duplicate setting for the module found in the
+&rcfile;, and applies only while the option is passed on the command line.</para>
+
+<informalexample>
+<para>Using a different build directory for the kdeedu module:</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesvn-build</command> <option>--<replaceable>kdeedu</replaceable>,<replaceable>build-dir</replaceable>=<replaceable>temp-build</replaceable></option></userinput>
+</screen>
+
+</informalexample>
+
+</sect3>
+
+</sect2>
+
+</sect1>
diff --git a/doc/using-kdesvn-build/basic-features.docbook b/doc/using-kdesvn-build/basic-features.docbook
new file mode 100644
index 00000000..bb3ef4ea
--- /dev/null
+++ b/doc/using-kdesvn-build/basic-features.docbook
@@ -0,0 +1,202 @@
+<sect1 id="basic-features">
+<title>Basic &kdesvn-build; features</title>
+
+<sect2 id="using-qt-copy">
+<title>qt-copy support</title>
+<para>&kdesvn-build; strives to maintain excellent support for the qt-copy
+module included in the &kde; &svn; repository.</para>
+
+<note><para>
+qt-copy is a copy of the source code for the latest release of the &Qt; toolkit
+used by &kde;. It also contains a patchset of optimization and bug improvement
+patches which may optionally be applied. These patches are still compatible
+with the &Qt; library so that code produced using qt-copy will run with normal
+&Qt;.
+</para></note>
+
+<para>Most of the differences required for qt-copy are handled automatically by
+&kdesvn-build;. However, there are a few differences you may need to know
+about.</para>
+
+<itemizedlist>
+<listitem><para>Normally the value for &configure-flags; for a module is
+appended to the global setting for &configure-flags;. However, the
+&configure-flags; setting for qt-copy will replace the global setting since
+they are not equivalent command lines.
+</para></listitem>
+
+<listitem><para>&kdesvn-build; will automatically define some extra environment
+variables to build qt-copy that are not normally required for the rest of &kde;.
+</para></listitem>
+
+<listitem><para>
+qt-copy also has support for an optional patch set containing some bug fixes
+and optimizations that haven't yet made it to the official &Qt;. To enable
+these, set the &apply-qt-patches; option to <userinput>true</userinput>. After
+making this change you may have to run <userinput><command>kdesvn-build</command>
+<option>--refresh-build</option> <option>qt-copy</option></userinput>.
+</para></listitem>
+
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="kdesvn-build-std-flags">
+<title>Standard flags added by &kdesvn-build;</title>
+<para>To save you time, &kdesvn-build; adds some standard paths to your
+environment for you:
+</para>
+
+<itemizedlist>
+<listitem><para>
+The path to the &kde; and &Qt; libraries is added to the
+<envar>LD_LIBRARY_PATH</envar> variable automatically. This means that you
+do not need to edit &libpath; to include them.
+</para></listitem>
+
+<listitem><para>
+The path to the &kde; and &Qt; development support programs are added to the
+<envar>PATH</envar> variable automatically. This means that you do not need to
+edit &binpath; to include them.
+</para></listitem>
+
+<listitem><para>
+The path to the &kde;-provided <application>pkg-config</application> is added
+automatically to <envar>PKG_CONFIG_PATH</envar>. This means that you do not
+need to use &set-env; to add these.
+</para></listitem>
+
+<listitem><para>
+The setting for &kdedir; is automatically propagated to the <envar>KDEDIR</envar>
+environment variable while building. (<envar>KDEDIRS</envar> is not affected).
+</para></listitem>
+
+<listitem><para>
+The setting for &qtdir; is automatically propagated to the <envar>QTDIR</envar>
+environment variable while building.
+</para></listitem>
+
+<listitem><para>
+&kdesvn-build; will automatically adjust the environment as necessary to account
+for the setting of the &use-unsermake; option.
+</para></listitem>
+
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="build-priority">
+<title>Changing &kdesvn-build;'s build priority.</title>
+<para>Programs can run with different priority levels on Operating Systems
+nowadays, including &Linux; and &BSD;. This allows the system to allocate time
+for the different programs in accordance with how important they are.
+</para>
+
+<para>&kdesvn-build; will normally allocate itself a low priority so that the
+rest of the programs on your system are unaffected and can run normally.
+Using this technique, &kdesvn-build; will use extra CPU when it is available.
+</para>
+
+<para>&kdesvn-build; will still maintain a high enough priority level so that
+it runs before routine batch processes and before CPU donation programs
+such as <ulink url="http://setiathome.ssl.berkeley.edu/">Seti at Home</ulink>.
+</para>
+
+<para>To alter &kdesvn-build; so that it uses a higher, or lower priority level
+permanently, then you need to adjust the &niceness; setting in the
+&rcfile;. The &niceness; setting controls how <quote>nice</quote> &kdesvn-build; is to other
+programs. In other words, having a higher &niceness; gives &kdesvn-build; a
+lower priority. So to give &kdesvn-build; a higher priority, reduce the
+&niceness; (and vice versa). The &niceness; can go from 0 (not nice at all,
+highest priority) to 20 (super nice, lowest priority).</para>
+
+<para>You can also temporarily change the priority for &kdesvn-build; by
+using the &cmd-nice; &cmd-line-option;. The value to the option is used
+exactly the same as for &niceness;.</para>
+
+<note><para>It is possible for some programs run by the super user to have a
+negative nice value, with a correspondingly even higher priority for such
+programs. Setting a negative (or even 0) &niceness; for &kdesvn-build; isn't
+a great idea, as it won't help run time significantly, but will make your
+computer seem very sluggish should you still need to use it.
+</para></note>
+
+<informalexample>
+<para>To run &kdesvn-build; with a niceness of 15 (a lower priority than
+normal):</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesvn-build</command> <option>--nice=<replaceable>15</replaceable></option></userinput>
+</screen>
+
+<para>Or, you can edit the &rcfile; to make the change permanent:</para>
+
+<screen>
+ &niceness; <replaceable>15</replaceable>
+</screen>
+
+</informalexample>
+</sect2>
+
+<sect2 id="root-installation">
+<title>Installation as the superuser</title>
+<para>You may wish to have &kdesvn-build; run the installation with super user
+privileges. This may be for the unrecommended system-wide installation.
+This is also useful when using a recommended single user &kde; build, however.
+This is because some modules (especially kdebase) install programs that will
+briefly need elevated permissions when run. They aren't able to achieve these
+permission levels unless they are installed with the elevated permissions.
+</para>
+
+<para>You could simply run &kdesvn-build; as the super user directly, but this
+isn't recommended, since the program has not been audited for that kind of use.
+Although it should be safe to run the program in this fashion, it is better to
+avoid running as the super user when possible.</para>
+
+<para>To take care of this, &kdesvn-build; provides the &make-install-prefix;
+option. You can use this option to specify a command to use to perform the
+installation as another user. The recommended way to use this command is with
+the <application>sudo</application> program, which will run the
+install command as the super user.
+</para>
+
+<informalexample>
+<para>For example, to install all modules using <application>sudo</application>,
+you could do something like this:</para>
+
+<screen>
+global
+ &make-install-prefix; <replaceable>sudo</replaceable>
+ # Other options
+end global
+</screen>
+
+<para>To use &make-install-prefix; for only a single module, this would work:
+</para>
+
+<screen>
+module <replaceable>kdemultimedia</replaceable>
+ &make-install-prefix; <replaceable>sudo</replaceable>
+end module
+</screen>
+</informalexample>
+
+</sect2>
+
+<sect2 id="build-progress">
+<title>Showing the progress of a module build.</title>
+<para>This feature is always available, and is automatically enabled when
+possible. What this does is display an estimated build progress while
+building a module, that way you know about how much longer it will take to
+build a module.
+</para>
+
+<para>In order to use this feature, the &use-unsermake; option must be enabled
+for the module. This option is normally enabled by default, but some modules
+don't support the option, and they are automatically stopped from using
+unsermake. So if you think you have enabled unsermake and you still don't
+see a progress report when building the module, it may be possible that the
+module doesn't support unsermake.</para>
+</sect2>
+
+</sect1>
diff --git a/doc/using-kdesvn-build/developer-features.docbook b/doc/using-kdesvn-build/developer-features.docbook
new file mode 100644
index 00000000..e3aee1a4
--- /dev/null
+++ b/doc/using-kdesvn-build/developer-features.docbook
@@ -0,0 +1,83 @@
+<sect1 id="developer-features">
+<title>Features for &kde; developers</title>
+
+<sect2 id="building-apidox">
+<title>Building API Documentation</title>
+<para>&kdesvn-build; can automatically install additional documentation
+generated from the sources in a module. This only works on some modules,
+and is only useful for &kde; developers.</para>
+
+<important>
+<para>This feature does not work for modules built using the <link linkend="using-unsermake">unsermake</link>
+build system. Since this is the default build system for modules that can
+use unsermake, you would need to disable unsermake support. See <link
+linkend="example-apidox">example below</link> for more information.
+</para>
+</important>
+
+<para>To enable this, simply set the &apidox; option to true in the &rcfile;,
+for the module that you would like documentation for. Not all modules have
+documentation. Modules that do include kdelibs, kdebase, and kdepim.
+</para>
+
+<note>
+<para>If you have access to the Internet, the API documentation for &kde; is
+also available online. In Konqueror, you can use the shortcut <quote>kde:<replaceable>className</replaceable></quote>.
+</para>
+
+<para>You can also visit the &kde; documentation web site at <ulink
+url="http://www.englishbreakfastnetwork.org/apidocs/">English Breakfast Network</ulink>.
+</para>
+
+<para>Finally, it is possible to download the documentation in an archived
+form, from <ulink url="http://developer.kde.org/documentation/library/libraryref.php">The &kde; Developer's Corner</ulink>.
+Click on the &kde; version you want documented, and then you can download
+an offline copy for the module you want.
+</para>
+</note>
+
+<informalexample id="example-apidox">
+<para>Installing API Documentation for kdelibs.</para>
+
+<screen>
+module kdelibs
+ use-unsermake false # unsermake can't build apidox
+ apidox true # build and install apidox
+end module
+</screen>
+</informalexample>
+
+</sect2>
+
+<sect2 id="ssh-agent-reminder">
+<title>SSH Agent checks</title>
+<para>&kdesvn-build; can ensure that &kde; developers that use &ssh; to
+access the &kde; source repository don't accidentally forget to leave the
+&ssh; Agent tool enabled. This can cause &kdesvn-build; to hang indefinitely
+waiting for the developer to type in their <acronym>SSH</acronym> password,
+so by default, &kdesvn-build; will check if the Agent is running before
+performing source updates.
+</para>
+
+<note><para>This is only done for &kde; developers using &ssh;. This is because
+no password is required for the default anonymous checkout. &svn; will handle
+passwords for the second possible protocol for KDE developers, https.
+</para></note>
+
+<para>You may wish to disable the &ssh; Agent check, in case of situations where
+&kdesvn-build; is mis-detecting the presence of an agent. To disable the
+agent check, set the <option>disable-agent-check</option> option to
+<userinput>true</userinput>.</para>
+
+<informalexample>
+<para>Disabling the &ssh; agent check</para>
+<screen>
+global
+ disable-agent-check <userinput><replaceable>true</replaceable></userinput>
+end global
+</screen>
+</informalexample>
+
+</sect2>
+
+</sect1>
diff --git a/doc/using-kdesvn-build/index.docbook b/doc/using-kdesvn-build/index.docbook
new file mode 100644
index 00000000..6d7fe429
--- /dev/null
+++ b/doc/using-kdesvn-build/index.docbook
@@ -0,0 +1,14 @@
+<chapter id="using-kdesvn-build">
+<title>Using &kdesvn-build;</title>
+
+&using-kdesvn-build-preface;
+
+&basic-features;
+
+&advanced-features;
+
+&developer-features;
+
+&other-features;
+
+</chapter>
diff --git a/doc/using-kdesvn-build/other-features.docbook b/doc/using-kdesvn-build/other-features.docbook
new file mode 100644
index 00000000..a437a8ae
--- /dev/null
+++ b/doc/using-kdesvn-build/other-features.docbook
@@ -0,0 +1,188 @@
+<sect1 id="other-features">
+<title>Other &kdesvn-build; features</title>
+
+<sect2 id="changing-verbosity">
+<title>Changing the amount of output from &kdesvn-build;</title>
+<para>&kdesvn-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 &kdesvn-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 &kdesvn-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 &kdesvn-build; to be very detailed in its
+output.</para></listitem>
+
+<listitem><para>The <option>--debug</option> option is for debugging purposes
+only, it causes &kdesvn-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="kdesvn-build-color">
+<title>Color output</title>
+<para>When being run from &konsole; or a different terminal, &kdesvn-build;
+will normally display with colorized test.</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 &rcfile; to
+<userinput>false</userinput>.
+</para>
+
+<informalexample>
+<para>Disabling color output in the configuration file</para>
+<screen>
+global
+ colorful-output <userinput><replaceable>false</replaceable></userinput>
+end global
+</screen>
+</informalexample>
+
+</sect2>
+
+<sect2 id="email-reports">
+<title>E-mailing build failure reports</title>
+<para>&kdesvn-build; can send a e-mail report to an e-mail address of your
+choice when a module fails to build for whatever reason. The way it works
+is that you choose an e-mail address that &kdesvn-build; will send from,
+and an e-mail address to notify when there is an error.</para>
+
+<para>&kdesvn-build; will then, at the end of a complete run, construct an
+e-mail if there were any modules that failed to build. The e-mail will contain
+an abbreviated failure log for each module. Only one e-mail is sent for a
+run, even if 15 modules failed to build.
+</para>
+
+<para>This feature is not enabled by default. To enable it, you need to set
+both the &email-address; and &email-on-compile-error; options. <option>email-address</option>
+controls the address &kdesvn-build; sends from, and <option>email-on-compile-error</option>
+controls where to send the e-mail message to.
+</para>
+
+<tip>
+<para>&kdesvn-build; uses the Perl-standard Mail::Mailer module to send e-mail.
+It is included with Perl 5.8, and is installable with Perl 5.6. Mail::Mailer
+supports <application>Sendmail</application> (including <application>Sendmail</application>-compatible
+e-mail clients), native <acronym>SMTP</acronym> transport, and <application>qmail</application>
+</para>
+</tip>
+
+<informalexample>
+<para>Sending email from foo at example.com to bar at example.com on a build failure.</para>
+
+<screen>
+global
+ email-address foo at example.com # From: address for any kdesvn-build e-mail
+ email-on-compile-error bar at example.com # To: address for build failure e-mail
+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? &kdesvn-build; can help reduce your disk usage when building
+&kde; from &svn;.</para>
+
+<note><para>Be aware that building &kde; does take a lot of space. There are
+several major space-using pieces when using &kdesvn-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. &kdesvn-build; won't delete source code from disk even if you
+delete the entry from the &rcfile;, 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
+&kdesvn-build;.</para>
+
+<para>Also, if you already have a &Qt; installed by your distribution (and
+the odds are good that you do), you probably don't need to install the
+qt-copy module. That will shave about 200 megabytes off of the on-disk source
+size.</para>
+
+<para>One thing to note is that due to the way &svn; works, there are actually
+two files on disk for every file checked-out from the repository. &kdesvn-build;
+does not have code at this point to try and minimize the source size when the
+source is not being used.
+</para>
+</listitem>
+
+<listitem>
+<para>&kdesvn-build; will create a separate build directory to build the source
+code in. Sometimes &kdesvn-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 455 megabytes, whereas kdebase's
+source is only around 195 megabytes.</para>
+
+<para>Luckily, the build directory is not required after a module has
+successfully been built and installed. &kdesvn-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 &kdesvn-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 doesn't 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'll 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>
diff --git a/doc/using-kdesvn-build/using-kdesvn-build-preface.docbook b/doc/using-kdesvn-build/using-kdesvn-build-preface.docbook
new file mode 100644
index 00000000..d3e767e2
--- /dev/null
+++ b/doc/using-kdesvn-build/using-kdesvn-build-preface.docbook
@@ -0,0 +1,17 @@
+<sect1 id="using-kdesvn-build-preface">
+<title>Preface</title>
+
+<para>Normally using &kdesvn-build; after you have gone through <xref linkend="getting-started" />
+is as easy as doing the following from a terminal prompt:</para>
+
+<screen>
+<prompt>%</prompt> <command><userinput>kdesvn-build</userinput></command>
+</screen>
+
+<para>&kdesvn-build; will then download the sources for &kde;, try to configure
+and build them, and then install them.</para>
+
+<para>Read on to discover how &kdesvn-build; does this, and what else you can
+do with this tool.</para>
+
+</sect1>
More information about the kde-doc-english
mailing list