From b064c0a69cf0857da0df41f1e8fc78e1de554562 Mon Sep 17 00:00:00 2001
From: Federico Zenith <federico.zenith@member.fsf.org>
Date: Sat, 10 Nov 2007 10:10:16 +0000
Subject: [PATCH] Some more improvements/corrections CCMAIL:
 michael.pyne@kdemail.net

svn path=/trunk/KDE/kdesdk/doc/scripts/kdesvn-build/; revision=734875
---
 doc/index.docbook | 282 +++++++++++++++++++++++-----------------------
 1 file changed, 142 insertions(+), 140 deletions(-)

diff --git a/doc/index.docbook b/doc/index.docbook
index feeab79..757d487 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -14,6 +14,7 @@
   <!ENTITY subversion '<application>Subversion</application>'>
   <!ENTITY sudo '<application>Sudo</application>'>
   <!ENTITY unsermake '<application>Unsermake</application>'>
+  <!ENTITY url '<acronym>URL</acronym>'>
 
   <!-- These define shortcut entities for some of the configuration options.
        Just add them as necessary.
@@ -182,7 +183,7 @@ The complete list of required tools can be found from the
 Requirements</ulink> page.
 </para>
 
-<para>Here is a list of some of the things you'll need:</para>
+<para>Here is a list of some of the things you will need:</para>
 <itemizedlist>
 
 <listitem><para>&automake; version 1.7, or higher. (&kde; 3 only)</para></listitem>
@@ -208,14 +209,14 @@ 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:
+copy of &Qt; whether you have it installed or not, so it is not necessary for you
+to have it. If you do not 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 <link linkend="configure-data">configuration file</link>, as you
-  won't need it, and having it would add extra time to your build.</para>
+  will not need it, and having it would add extra time to your build.</para>
 </listitem>
 
 <listitem>
@@ -225,9 +226,9 @@ to have it. If you don't want to use the &Qt; copy, you need to do these things:
 </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.3 if you're building &kde; 4.</para>
+  <para>If you do not already have &Qt; installed, install it, including any
+  relevant -dev or -devel packages. You will need at least &Qt; 3.3 if you are
+  building &kde; 3.5, or &Qt; 4.3 if you are building &kde; 4.</para>
 
   <note><para>If you are building &kde; 4 it is highly recommended to use the
   qt-copy version of &Qt;, making sure to apply recommended patches (this is
@@ -258,7 +259,7 @@ required software.
 <title>Install &kdesvn-build;</title>
 <para>
 You probably already have a version of the &kdesvn-build; script installed
-in your system. However, if you don't, you can download it from
+in your system. However, if you do not, you can download it from
 <ulink url="http://kdesvn-build.kde.org/">&kdesvn-build; home page</ulink>,
 or you can find it from its home in the &kde; source repository.</para>
 
@@ -295,16 +296,16 @@ was not found, or you may run a previously-installed version by mistake.</para>
 <sect3 id="setup-rcfile">
 <title>Prepare the configuration file</title>
 
-<para>Although &kdesvn-build; doesn't require you to create a <link linkend="configure-data">configuration file</link>, it
+<para>Although &kdesvn-build; does not require you to create a <link linkend="configure-data">configuration file</link>, it
 makes the work flow much easier. Using a <link linkend="configure-data">configuration file</link>, you can control which
-modules are installed, or remove modules you don't want to install. &kdesvn-build;
+modules are installed, or remove modules you do not 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
-<link linkend="configure-data">configuration file</link></para>
+<link linkend="configure-data">configuration file</link>. </para>
 
 <para>The <link linkend="configure-data">configuration file</link> should be called <filename>.kdesvn-buildrc</filename>. 
 This file should be installed on
-the home folder (<filename>~/</filename>), and contain all configuration data
+the home folder (<filename class="directory">~/</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
@@ -359,17 +360,18 @@ the latest stable release of &kde; instead of using your distribution packages
 
 <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>
+<filename class="directory">~/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; &subversion; repository. (<filename>~/kdesvn/build/qt-copy</filename>)</para>
+module from the &kde; &subversion; repository
+(<filename class="directory">~/kdesvn/build/qt-copy</filename>).</para>
 
 <para>For Qt versions that support installation, this also controls where to
 install qt-copy.</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
+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;
 &subversion; account</ulink>.</para></listitem>
 </itemizedlist>
@@ -412,12 +414,12 @@ 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 log files are kept in <filename class="directory">~/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>
+it is sufficient to look at <filename class="directory">~/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
+that module. If the file says (at the bottom) that you are missing some
 packages, try installing the package (including any appropriate -dev packages)
 before trying to build that module, and pass the <link
 linkend="cmdline-reconfigure">--reconfigure</link> option after install the
@@ -425,7 +427,7 @@ missing packages.</para>
 
 <para>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
+resolved within a few days. If it is not resolved within that time, feel free
 to mail the <email>kde-devel@kde.org</email> (subscription may be required first)
 in order to report the build failure.</para>
 
@@ -563,13 +565,13 @@ text terminals and the following six are graphical displays.
 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
+a <quote>Custom Session</quote> when you login. With this option, your session settings are
 loaded from the <filename>.xsession</filename> file in your home directory. If
 you have already modified this file as described above, this option should load
 you into your new &kde; installation.
 </para>
 
-<para>If it doesn't, there's something else you can try that should normally
+<para>If it does not, there is something else you can try that should normally
 work: Press <keycombo action="simul">&Ctrl;&Alt;<keycap>F2</keycap></keycombo>,
 and you will be presented to a text terminal. Log in using the dedicated user
 and type:
@@ -651,7 +653,7 @@ module.
 </para></listitem>
 
 <listitem><para>
-&kdesvn-build; has <link linkend="kdesvn-build-color">colorized output.</link>
+&kdesvn-build; has <link linkend="kdesvn-build-color">colorized output</link>.
 </para></listitem>
 
 <listitem><para>
@@ -678,7 +680,7 @@ linkend="conf-revision">revision</link> is checked out of a module.
 <listitem><para>
 &kdesvn-build; can automatically switch a source directory to checkout from
 a different repository, branch, or tag. This happens automatically when you
-change an option that changes what the repository URL should be, but you must
+change an option that changes what the repository &url; should be, but you must
 use the <link linkend="cmdline-svn-only">--svn-only</link> option to let
 &kdesvn-build; know that it is acceptable to perform the switch.
 </para></listitem>
@@ -746,8 +748,8 @@ 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 &subversion; the first time for
+&kdesvn-build; will automatically download and create the required <filename class="directory">/admin</filename>
+directory for a module if it is not downloaded from &subversion; the first time for
 some reason. This only applies to &kde; 3 modules, as /admin is not required
 for qt-copy or &kde; 4 modules.
 </para></listitem>
@@ -856,7 +858,7 @@ reasons why a build can fail in the first place.</para>
 
 <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
+option, which defaults to <filename class="directory"><symbol>${source-dir}</symbol>/log</filename> (where
 <symbol>${source-dir}</symbol> is the value of the <link linkend="conf-source-dir">source-dir</link>
 option. The in rest of this section, this value will be referred to as
 <symbol>${log-dir}</symbol>).</para>
@@ -868,8 +870,8 @@ May 26, 2004, it would create a directory called <filename>2004-05-26-02</filena
 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>.
+logs for your latest run, called <filename class="directory">latest</filename>. So the logs for
+the most recent &kdesvn-build; run should always be under <filename class="directory"><symbol>${log-dir}</symbol>/latest</filename>.
 </para>
 
 <para>Now, each directory for a &kdesvn-build; run will itself contain a set of
@@ -881,11 +883,11 @@ which will allow you to determine which modules built and which failed.</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>.
+last &kdesvn-build; run would be found in <filename class="directory"><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>,
+and not under <filename class="directory"><symbol>${log-dir}</symbol>/latest/kdelibs</filename>.
 </para></note>
 
-<para>In each module log directory, you'll find a set of files for each
+<para>In each module log directory, you will 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
@@ -911,7 +913,7 @@ 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 &subversion; 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>
+but is instead at the &konsole; or terminal where you ran &kdesvn-build;.</para>
 </tip>
 
 </sect3>
@@ -955,7 +957,7 @@ end module
 <para>
 <replaceable>module-name</replaceable> must be a module from the &kde; &subversion; repository (for
 example, kdelibs or kdebase). Some options override global options, some
-add to global options, and some global options simply can't be overridden.
+add to global options, and some global options simply cannot be overridden.
 </para>
 
 <para>
@@ -965,8 +967,8 @@ authors using the address you can find <link linkend="authors">above</link>.
 </para>
 
 <itemizedlist>
-<listitem><para><link linkend="conf-apidox">apidox</link>, to build API Documentation</para></listitem>
-<listitem><para><link linkend="conf-apply-qt-patches">apply-qt-patches</link>, to enhance qt-copy</para></listitem>
+<listitem><para><link linkend="conf-apidox">apidox</link>, to build API Documentation.</para></listitem>
+<listitem><para><link linkend="conf-apply-qt-patches">apply-qt-patches</link>, to enhance qt-copy.</para></listitem>
 <listitem><para><link linkend="conf-binpath">binpath</link>, to set the <envar>PATH</envar> variable.</para></listitem>
 <listitem><para><link linkend="conf-branch">branch</link>, to checkout from a branch instead of /trunk.</para></listitem>
 <listitem><para><link linkend="conf-build-dir">build-dir</link>, to set the directory to build in.</para></listitem>
@@ -1042,7 +1044,7 @@ a different program which &kdesvn-build; has not been corrected to use yet.
 <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 should not
 do any harm to enable it. The default is to enable the patches.</entry>
 </row>
 
@@ -1050,11 +1052,11 @@ do any harm to enable it. The default is to enable the patches.</entry>
 <entry>binpath</entry>
 <entry>Overrides global</entry>
 <entry><para>Set this option to set the environment variable PATH while building.
-You can't override this setting in a module option. The default value is
+You cannot override this setting in a module option. The default value is
 <filename class="directory">/bin:/usr/bin:/usr/local/bin:/usr/X11R6/bin</filename>. This environment
 variable should include the colon-separated paths of your development
-toolchain. The paths <filename class="directory">$KDEDIR/bin</filename> and
-<filename class="directory">$QTDIR/bin</filename> are automatically added. You
+toolchain. The paths <filename class="directory">$<envar>KDEDIR</envar>/bin</filename> and
+<filename class="directory">$<envar>QTDIR</envar>/bin</filename> are automatically added. You
 may use the tilde (~) for any paths you add using this option.</para>
 </entry>
 </row>
@@ -1063,13 +1065,14 @@ may use the tilde (~) for any paths you add using this option.</para>
 <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>
+default of <replaceable>trunk</replaceable>, where &kde; development occurs.
+For instance, to checkout &kde; 3.4 branch, you would set this option to
+<replaceable>3.4</replaceable>.</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
+required arts module does not 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
+may have to manually specify the &url; to download from using the <link
 linkend="conf-override-url">override-url</link> option.</para>
 </entry>
 </row>
@@ -1083,8 +1086,8 @@ are three different ways to use it:
 
 <listitem><para>Relative to the &kde; &subversion; source directory (see <link
 linkend="conf-source-dir">the source-dir option</link>). This is the default, and
-the way the script worked up to version v0.61. This mode is selected if you
-type a directory name that doesn't start with a tilde (~) or a slash (/).</para>
+the way the script worked up to version 0.61. This mode is selected if you
+type a directory name that does not start with a tilde (~) or a slash (/).</para>
 <para>The default value is <filename class="directory">build</filename>.</para></listitem>
 
 <listitem><para>Absolute path. If you specify a path that begins with a /, then that path
@@ -1107,7 +1110,7 @@ Perhaps surprisingly, this option can be changed per module.
 <entry>Overrides global</entry>
 <entry>Set this option to checkout &subversion; sources piece by piece. The value
 for this option should be a space separated list of directories to checkout.
-If you don't include the admin directory, it will automatically be included (if
+If you do not include the admin directory, it will automatically be included (if
 necessary). When checking out piece by piece, the admin directory will be
 pulled in from kde-common, which is where it exists on the &subversion; server.
 Although this option overrides the global option, be aware that setting this as
@@ -1156,9 +1159,9 @@ option.</para>
 
 <row id="conf-colorful-output">
 <entry>colorful-output</entry>
-<entry>Can't be overridden</entry>
+<entry>Cannot be overridden</entry>
 <entry>Set this option to <replaceable>false</replaceable> to disable the colorful output of &kdesvn-build;.
-This option defaults to <replaceable>true</replaceable>. Note that &kdesvn-build; won't output the
+This option defaults to <replaceable>true</replaceable>. Note that &kdesvn-build; will not output the
 color codes to anything but a terminal (such as xterm, &konsole;, or the normal
 &Linux; console).
 </entry>
@@ -1187,10 +1190,10 @@ extragear-network using this option.
 
 <row id="conf-disable-agent-check">
 <entry>disable-agent-check</entry>
-<entry>Can't be overridden</entry>
-<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
+<entry>Cannot be overridden</entry>
+<entry>Normally if you are using &ssh; to download the &subversion; sources (such as
+if you are using the svn+ssh protocol), &kdesvn-build; will try and make sure that
+if you are using ssh-agent, it is actually managing some &ssh; identities. This is
 to try and prevent &ssh; from asking for your pass phrase for every module. You can
 disable this check by setting <option>disable-agent-check</option> to <replaceable>true</replaceable>.
 </entry>
@@ -1216,10 +1219,10 @@ directive to choose directories that you want to check out.</para>
 
 <row id="conf-email-address">
 <entry>email-address</entry>
-<entry>Can't be overridden</entry>
+<entry>Cannot be overridden</entry>
 <entry>
 <para>Set this option to the e-mail address &kdesvn-build; should send from should
-it ever need to send e-mail. You do not need to worry about this if you don't
+it ever need to send e-mail. You do not need to worry about this if you do not
 use any feature which send e-mail. (They are all disabled by default).
 </para>
 
@@ -1231,7 +1234,7 @@ needs this option.
 
 <row id="conf-email-on-compile-error">
 <entry>email-on-compile-error</entry>
-<entry>Can't be overridden</entry>
+<entry>Cannot be overridden</entry>
 <entry>
 <para>You can set this option to the email address to send a report to when a
 module fails to build. &kdesvn-build; will wait until all the modules are done
@@ -1254,7 +1257,7 @@ linkend="conf-do-not-compile">do-not-compile</link> option. This option makes it
 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
+<para>Any changes do not take effect until the next time
 <command>make <option>-f</option> Makefile.cvs</command> is
 run, either automatically by the script, or manually by the <link
 linkend="cmdline-refresh-build"><option>--refresh-build</option></link> or <link
@@ -1291,7 +1294,7 @@ linkend="conf-make-install-prefix">make-install-prefix</link> option as well.</e
 
 <row id="conf-kde-languages">
 <entry>kde-languages</entry>
-<entry>Can't be overridden</entry>
+<entry>Cannot 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>
@@ -1316,9 +1319,9 @@ French language, however.</para>
 <entry>libpath</entry>
 <entry>Overrides global</entry>
 <entry>Set this option to set the environment variable LD_LIBRARY_PATH while
-building. You can't override this setting in a module option. The default
-value is blank, but the paths <filename class="directory">$KDEDIR/lib</filename> and
-<filename class="directory">$QTDIR/lib</filename> are automatically
+building. You cannot override this setting in a module option. The default
+value is blank, but the paths <filename class="directory">$<envar>KDEDIR</envar>/lib</filename> and
+<filename class="directory">$<envar>QTDIR</envar>/lib</filename> are automatically
 added. You may use the tilde (~) for any paths you add using this option.
 </entry>
 </row>
@@ -1391,7 +1394,7 @@ linkend="conf-tag">tag</link> options instead whenever they are applicable.
 
 <row id="conf-niceness">
 <entry>niceness</entry>
-<entry>Can't be overridden</entry>
+<entry>Cannot be overridden</entry>
 <entry>Set this option to a number between 20 and 0. The higher the number, the
 lower a priority &kdesvn-build; will set for itself. The default is 10.
 </entry>
@@ -1409,20 +1412,20 @@ effect of a stray &subversion; update messing up the build system.</entry>
 <row id="conf-override-url">
 <entry>override-url</entry>
 <entry>Overrides global</entry>
-<entry>If you set this option, &kdesvn-build; will use its value as the URL
+<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
 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>.
+cannot figure out what you mean using <link linkend="conf-branch">branch</link>.
 </entry>
 </row>
 
 <row id="conf-qtdir">
 <entry>qtdir</entry>
 <entry>Overrides global</entry>
-<entry>Set this option to set the environment variable QTDIR while building.
-You can't override this setting in a module option. If you don't specify
+<entry>Set this option to set the environment variable <envar>QTDIR</envar> while building.
+You cannot override this setting in a module option. If you do not specify
 this option, it defaults to
-<filename class="directory"><varname>$(source-dir)</varname>/build/qt-copy</filename>,
+<filename class="directory"><symbol>${source-dir}</symbol>/build/qt-copy</filename>,
 which uses the qt-copy module included in the &kde; source repository.
 You may use a tilde (~) to represent your home directory.
 </entry>
@@ -1445,7 +1448,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 <replaceable>all</replaceable>) and the time taken to compile &kde;,
 since &kdesvn-build; will be unable to perform incremental builds.</para>
 </entry>
 </row>
@@ -1466,7 +1469,7 @@ configuration.</entry>
 <entry>Overrides global</entry>
 <entry><para>This option accepts a space-separated set of values, where the first value
 is the environment variable to set, and the rest of the values is what you
-want the variable set to. For example, to set the variable RONALD to
+want the variable set to. For example, to set the variable <envar>RONALD</envar> 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
@@ -1480,7 +1483,7 @@ globally).</para>
 <entry>source-dir</entry>
 <entry>Overrides global</entry>
 <entry>This option is used to set the directory on your computer to store the &kde;
-&subversion; sources at. If you don't specify this value, the default is
+&subversion; sources at. If you do not specify this value, the default is
 <filename class="directory">~/kdesvn</filename>. If
 you do specify this value, use an absolute path name.
 </entry>
@@ -1499,16 +1502,16 @@ by default.
 <entry>svn-server</entry>
 <entry>Overrides global</entry>
 <entry>This option is used to set the server used to check out from &subversion;.
-The default is the anonymous &subversion; repository, <emphasis>svn://anonsvn.kde.org/</emphasis></entry>
+The default is the anonymous &subversion; repository, <filename>svn://anonsvn.kde.org/</filename></entry>
 </row>
 
 <row id="conf-tag">
 <entry>tag</entry>
 <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
+<para><emphasis>Note:</emphasis> The odds are very good that you <emphasis>do not
+want</emphasis> 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
@@ -1541,9 +1544,9 @@ require &cmake;, and &cmake; use is not permitted on any other modules.
 qt-copy. Set this option to <replaceable>true</replaceable> to enable the script's
 srcdir != builddir mode. When enabled,
 &kdesvn-build; will copy the qt-copy source module to the build directory,
-and perform builds from there. That means your QTDIR environment variable
+and perform builds from there. That means your <envar>QTDIR</envar> environment variable
 should be set to
-<filename class="directory">$(qt-copy-build-dir)/qt-copy/lib</filename>
+<filename class="directory">$<symbol>{qt-copy-build-dir}</symbol>/qt-copy/lib</filename>
 instead. You should also change your <link linkend="conf-qtdir">qtdir</link>
 option accordingly. Incremental &make; should still work in this mode, as the
 timestamps will be preserved after the copy. If you use the
@@ -1555,15 +1558,15 @@ This option defaults to <replaceable>true</replaceable>.
 
 <row id="conf-use-stable-kde">
 <entry>use-stable-kde</entry>
-<entry>Can't be overridden</entry>
+<entry>Cannot 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.
+for &kde; 4, which is not 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
+download for &kde; 3.5 (or 3.4, etc.). However, this is not 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>
 
@@ -1606,7 +1609,7 @@ do anything special to keep it updated.
 <title>Command Line Options and Environment Variables</title>
 
 <para>
-This script doesn't use environment variables. If you need to set environment
+This script does not use environment variables. If you need to set environment
 variables for the build or install process, please see the <link
 linkend="conf-set-env">set-env</link> option.
 </para>
@@ -1620,21 +1623,21 @@ The script accepts the following command-line options:
 <varlistentry id="cmdline-help">
 <term><option>--help</option></term>
 <listitem><para>
-only display simple help on this script.
+Only display simple help on this script.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-version">
 <term><option>--version</option></term>
 <listitem><para>
-display the program version.
+Display the program version.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-author">
 <term><option>--author</option></term>
 <listitem><para>
-display contact information for the
+Display contact information for the
 author.
 </para></listitem>
 </varlistentry>
@@ -1642,7 +1645,7 @@ author.
 <varlistentry id="cmdline-color">
 <term><option>--color</option></term>
 <listitem><para>
-enable colorful output.
+Enable colorful output.
 </para></listitem>
 </varlistentry>
 
@@ -1657,21 +1660,21 @@ of this run. <replaceable>value</replaceable> should be between 0 and 20.
 <varlistentry id="cmdline-no-color">
 <term><option>--no-color</option></term>
 <listitem><para>
-disable colorful output.
+Disable colorful output.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-pretend">
 <term><option>--pretend</option> (or <option>-p</option>)</term>
 <listitem><para>
-don't actually DO anything, but act like you did.
+Do not actually <emphasis>do</emphasis> anything, but act like you did.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-quiet">
 <term><option>--quiet</option> (or <option>-q</option>)</term>
 <listitem><para>
-Don't be as noisy with the output. With this switch only the basics are
+Do not be as noisy with the output. With this switch only the basics are
 output.
 </para></listitem>
 </varlistentry>
@@ -1686,28 +1689,28 @@ Only output warnings and errors.
 <varlistentry id="cmdline-verbose">
 <term><option>--verbose</option></term>
 <listitem><para>
-Be very descriptive about what's going on, and what &kdesvn-build; is doing.
+Be very descriptive about what is going on, and what &kdesvn-build; is doing.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-svn-only">
 <term><option>--svn-only</option></term>
 <listitem><para>
-only perform the source update.
+Only perform the source update.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-build-only">
 <term><option>--build-only</option></term>
 <listitem><para>
-only perform the build process.
+Only perform the build process.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-ignore-modules">
 <term><option>--ignore-modules</option></term>
 <listitem><para>
-don't include the modules passed on the rest of the command line in the update/build
+Do not include the modules passed on the rest of the command line in the update/build
 process.
 </para></listitem>
 </varlistentry>
@@ -1715,38 +1718,38 @@ process.
 <varlistentry id="cmdline-no-svn">
 <term><option>--no-svn</option></term>
 <listitem><para>
-skip contacting the &subversion; server.
+Skip contacting the &subversion; server.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-no-build">
 <term><option>--no-build</option></term>
 <listitem><para>
-skip the build process.
+Skip the build process.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-no-install">
 <term><option>--no-install</option></term>
 <listitem><para>
-don't automatically install packages after they're built.
+Do not automatically install packages after they are built.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-debug">
 <term><option>--debug</option></term>
 <listitem><para>
-enables debug mode for the script. Currently
-this means that all output will be dumped to STDOUT in addition to being
+Enables debug mode for the script. Currently
+this means that all output will be dumped to the standard output in addition to being
 logged in the log directory like normal. Also, many functions are much more
-verbose about what they're doing in debugging mode.
+verbose about what they are doing in debugging mode.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-no-rebuild-on-fail">
 <term><option>--no-rebuild-on-fail</option></term>
 <listitem><para>
-don't try and
+Do not try to
 rebuild modules that have failed building from scratch. &kdesvn-build; will
 never try to do this to a module that already was tried to be built from
 scratch.
@@ -1756,22 +1759,21 @@ scratch.
 <varlistentry id="cmdline-refresh-build">
 <term><option>--refresh-build</option></term>
 <listitem><para>
-recreate the build system and make from scratch.
+Recreate the build system and make from scratch.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-reconfigure">
 <term><option>--reconfigure</option></term>
 <listitem><para>
-run the configure script again
-without cleaning the build directory.
+Run the configure script again without cleaning the build directory.
 </para></listitem>
 </varlistentry>
 
 <varlistentry id="cmdline-recreate-configure">
 <term><option>--recreate-configure</option></term>
 <listitem><para>
-run <command>make <option>-f</option>
+Run <command>make <option>-f</option>
 Makefile.cvs</command> again to create the configure script, and continue
 building as normal. This option implies <option><link linkend="cmdline-reconfigure">--reconfigure</link></option>.
 </para></listitem>
@@ -1813,7 +1815,7 @@ the environment variables (such as <envar>PATH</envar> and
 <varlistentry id="cmdline-prefix">
 <term><option>--prefix=&lt;/path/to/kde&gt;</option></term>
 <listitem><para>
-which allows you to change the directory that &kde; will be installed to from the command line.
+This allows you to change the directory that &kde; will be installed to from the command line.
 This option implies <link linkend="cmdline-reconfigure"><option>--reconfigure</option></link>.
 </para></listitem>
 </varlistentry>
@@ -1821,7 +1823,7 @@ This option implies <link linkend="cmdline-reconfigure"><option>--reconfigure</o
 <varlistentry id="cmdline-build-system-only">
 <term><option>--build-system-only</option></term>
 <listitem><para>
-stop after running <command>make <option>-f</option> Makefile.cvs</command>. The configure
+Stop after running <command>make <option>-f</option> Makefile.cvs</command>. The configure
 script will still need to be run, which &kdesvn-build; will do next time. This lets you
 prepare all the configure scripts at once so you can view the <command>./configure
 <option>--help</option></command> for each module, and edit your configure-flags accordingly.
@@ -1831,7 +1833,7 @@ prepare all the configure scripts at once so you can view the <command>./configu
 <varlistentry id="cmdline-install"><term><option>--install</option></term>
 <listitem><para>
 If this is the only command-line option, it tries to install all of the modules contained in
-successfully-built, except for qt-copy, which doesn't need installation. If command-line
+successfully-built, except for qt-copy, which does not need installation. If command-line
 options are specified after <option>--install</option>, they are all assumed to be modules to install.
 </para></listitem>
 </varlistentry>
@@ -1842,7 +1844,7 @@ options are specified after <option>--install</option>, they are all assumed to
 You can use this option to override an option in your <link linkend="configure-data">configuration file</link> 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>.
+<userinput><option>--log-dir=<filename class="directory"><replaceable>/path/to/dir</replaceable></filename></option></userinput>.
 </para></listitem>
 </varlistentry>
 
@@ -1860,7 +1862,7 @@ would do: <option>--kdemultimedia,use-unsermake=false</option>.
 
 <para>
 Any other command-line options are assumed to be modules to update and build.
-Please, don't mix building with installing.
+Please, do not mix building with installing.
 </para>
 
 </chapter>
@@ -1919,7 +1921,7 @@ variables to build qt-copy that are not normally required for the rest of &kde;.
 
 <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
+and optimizations that have not yet made it to the official &Qt;. To enable
 these, set the &apply-qt-patches; option to <replaceable>true</replaceable>. After
 making this change you may have to run <userinput><command>kdesvn-build</command>
 <option>--refresh-build</option> <option>qt-copy</option></userinput>.
@@ -2004,8 +2006,8 @@ 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
+programs. Setting a negative (or even 0) &niceness; for &kdesvn-build; is not
+a great idea, as it will not help run time significantly, but will make your
 computer seem very sluggish should you still need to use it.
 </para></note>
 
@@ -2032,12 +2034,12 @@ normal):</para>
 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
+briefly need elevated permissions when run. They are not 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.
+is not 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>
 
@@ -2081,9 +2083,9 @@ build a module.
 <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
 do not support it and are automatically stopped from using &unsermake;.
-So if you think you have enabled &unsermake; and you still don't
+So if you think you have enabled &unsermake; and you still do not
 see a progress report when building the module, it may be possible that the
-module doesn't support &unsermake;.</para>
+module does not support &unsermake;.</para>
 </sect2>
 
 </sect1>
@@ -2109,7 +2111,7 @@ 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
+If you do not 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>
@@ -2131,7 +2133,7 @@ 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
+<para>Also, sometimes an application may need other directories and it is 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>
@@ -2246,7 +2248,7 @@ end module
 &kdesvn-build; will automatically update or checkout &unsermake;
 while performing the other updates. If you prefer to manage &unsermake;
 yourself, then it is possible to do so, by setting the value for &use-unsermake;
-to <option>self</option> instead of <replaceable>true</replaceable>.</para>
+to <replaceable>self</replaceable> instead of <replaceable>true</replaceable>.</para>
 
 <para>When this is done, &kdesvn-build; will still try to use
 &unsermake;, but will not perform the updates. You
@@ -2292,7 +2294,7 @@ there are some things that can be done.
 <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
+range from a generic request for a version, to a specific &url; to download
 for advanced users.
 </para>
 
@@ -2324,8 +2326,8 @@ end module
 
 </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!
+<tip><para>You can specify a global branch value. But if you do so, do not forget
+to specify a different branch for modules that should not use the global branch!
 </para></tip>
 </sect3>
 
@@ -2340,15 +2342,15 @@ guess the correct path improperly: &module-base-path; and &override-url;.
 <listitem><para>
 &module-base-path; is used to help &kdesvn-build; fill in the missing part of
 a module's path. In the &kde; repository, all of the paths are of the form
-<filename>svnRoot/module-base-path/module-name</filename>. Normally &kdesvn-build;
-can figure out the appropriate middle part by itself. When it can't, you can use
+<filename class="directory">svnRoot/module-base-path/<replaceable>module-name</replaceable></filename>. Normally &kdesvn-build;
+can figure out the appropriate middle part by itself. When it cannot, you can use
 &module-base-path;, like this:
 </para>
 
 <informalexample>
 <screen>
 module qt-copy
-  # branch doesn't work here yet
+  # branch does not work here yet
   module-base-path branches/qt/3.3
 end module
 </screen>
@@ -2400,7 +2402,7 @@ 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.
+and is quick to fail if it will not work.
 </para></listitem>
 
 <listitem><para>
@@ -2429,7 +2431,7 @@ 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
+of these steps are skipped, since the clean rebuild does not usually fail except
 for a real error.</para>
 </note>
 </sect3>
@@ -2437,7 +2439,7 @@ for a real error.</para>
 <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
+source code changes in a way &kdesvn-build; does not recognize, you may need to
 manually rebuild the module.</para>
 
 <para>You can do this by simply running <userinput><command>kdesvn-build</command>
@@ -2452,15 +2454,15 @@ 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>.
+<para>By default, the build directory is <filename class="directory">~/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>
+<filename class="directory">~/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>touch</command> <filename class="directory">~/kdesvn/build/<replaceable>arts</replaceable></filename></userinput>
 <prompt>%</prompt> <userinput><command>kdesvn-build</command></userinput>
 </screen>
 </informalexample>
@@ -2487,15 +2489,15 @@ the &cmd-no-rebuild-on-fail; command line option.</para>
 
 <sect2 id="changing-environment">
 <title>Changing environment variable settings</title>
-<para>&kdesvn-build; doesn't read the environment from the caller like the
+<para>&kdesvn-build; does not read the environment from the caller like the
 vast majority of most programs do. Instead, it uses the settings it reads
 from the <link linkend="configure-data">configuration file</link> to construct the environment. This is done mainly to
-ensure that build are repeatable. In other words,
+ensure that builds are 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.
+that &kdesvn-build; does not 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
@@ -2571,8 +2573,8 @@ 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 <userinput><option>--<replaceable>option-name</replaceable>=value</option></userinput>.
-&kdesvn-build; will recognize whether 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
+&kdesvn-build; will recognize whether it does not know what the option is, and search
+for the name in its list of option names. If it does not 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>
 
@@ -2662,7 +2664,7 @@ an offline copy for the module you want.
 
 <screen>
 module kdelibs
-  use-unsermake false    # unsermake can't build apidox
+  use-unsermake false    # unsermake cannot build apidox
   apidox        true     # build and install apidox
 end module
 </screen>
@@ -2673,7 +2675,7 @@ end module
 <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
+access the &kde; source repository do not 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 &ssh; password,
 so by default, &kdesvn-build; will check if the Agent is running before
@@ -2807,7 +2809,7 @@ several major space-using pieces when using &kdesvn-build;:</para></note>
 <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
+actually want. &kdesvn-build; will not delete source code from disk even if you
 delete the entry from the <link linkend="configure-data">configuration file</link>, so make sure that you go and delete unused
 source checkouts from the source directory. Note that the source files are
 downloaded from the Internet, you <emphasis>should not</emphasis> delete them
@@ -2815,7 +2817,7 @@ 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
+the odds are good that you do), you probably do not need to install the
 qt-copy module. That will shave about 200 megabytes off of the on-disk source
 size.</para>
 
@@ -2844,7 +2846,7 @@ for &kdesvn-build; to perform the time-saving incremental builds.</para>
 
 <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
+&kde;, which does not run from the build directory. This typically takes less
 space than the build directory. It is harder to get exact figures however.
 </para></listitem>
 </orderedlist>
@@ -2860,7 +2862,7 @@ 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
+hard to create a good bug report to get your bug resolved, and you will likely
 have to re-enable debugging information for the affected application and
 rebuild to help a developer fix the crash. So, remove debugging information
 at your own risk!
@@ -2926,7 +2928,7 @@ the same.</para>
 
 <para>Not all of &kde; has been ported to use &cmake; at this point. For example,
 the <link linkend="conf-apidox">apidox</link> option is rather useless until the
-equivalent infrastructure is ready. I've tried to warn about such things but
+equivalent infrastructure is ready. I have tried to warn about such things but
 not all deficiencies may be caught by &kdesvn-build; for now.</para>
 
 </sect1>