initial cowbuilder support in pdebuild

pbuilder supports pdebuild/cowbuilder

login/execute/update/create etc. can also be --login/--execute/--update/--create etc.
to cater for cowbuilder

documentation updates / XML typesetting fixes.
manpage fixes / spellchecking

generally what I did while I was on plane trip from Debconf Mexico to Japan.

13 files changed, 447 insertions, 296 deletions

diff --git a/ChangeLog b/ChangeLog
index 6beb98d..26131d7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,52 @@
+2006-05-24  Junichi Uekawa  <dancer@debian.org>
+
+	* pbuilder-buildpackage-funcs: quiet down cowprotect, it's giving
+	out useless output, like the following:
+
+	Copying back the cached apt archive contents
+	/var/cache/pbuilder/build/cow.12278/etc/passwd
+	/var/cache/pbuilder/build/cow.12278/etc/group
+	Copying source file
+
+	
+	* pbuilder.8: fix pbuilder execute command-line specification to
+	reflect that script can receive command-line parameters.
+
+	* pdebuild: add a in invocation to pbuilder execute "--", to avoid
+	reorder in cowbuilder, and still work with pbuilder.
+
+	* pdebuild.1: document --pbuilder option.
+
+	* pbuilderrc.5: document the new option
+
+	* pdebuild-checkparams: --pbuilder option. Use pbuilder as default.
+	It is possible to use cowbuilder.
+
+	* pbuilder: add --XXX options as compatibility options for cowbuilder.
+
+	* pdebuild (ARCHITECTURE): use PDEBUILD_PBUILDER instead of calling pbuilder directly,
+	and use cowdancer-compatible command-line options.
+
+	* Documentation/pbuilder-doc.xml: generally spellcheck, and revise.
+
+	* pdebuild.1: spellcheck
+
+	* pdebuild-user-mode-linux.1: spellcheck
+
+	* pbuilderrc.5: spellcheck
+
+	* pbuilder-modules: remove mention of potato/woody, since they
+	probably don't work
+	(pbuilder-options): remove potato/woody.
+
+	* pbuilder.8: remove woody from supported list of distributions,
+	we know dpkg from then doesn't really work with modern kernel.
+	(well, they do, but I don't want this documented/advertised)
+	
+	* pbuilder-user-mode-linux.1: spellcheck
+
+	* pbuilder.8: spellcheck
+
 2006-05-22  Junichi Uekawa  <dancer@debian.org>
 
 	* debian/TODO: update TODO, amd64-x86 cross build is documented and functional.
diff --git a/Documentation/pbuilder-doc.xml b/Documentation/pbuilder-doc.xml
index 149f57d..611271e 100644
--- a/Documentation/pbuilder-doc.xml
+++ b/Documentation/pbuilder-doc.xml
@@ -4,7 +4,7 @@
   and the latest version is found in CVS repository. -->
 <book xml:lang="en">
   <bookinfo>
-    <date>2006-3-8</date>
+    <date>2006-5-24</date>
     <title>pbuilder User's Manual</title>
     <abbrev>pbuilder-doc</abbrev>
     <subtitle>Usage and operations</subtitle>
@@ -45,7 +45,7 @@
 	installed.
       </para>
       <para>
-	The primary aim of pbuilder is different from other
+	The primary aim of <command>pbuilder</command> is different from other
 	auto-building systems in Debian in that its aim is not
 	to try to build as many packages as possible.
         It does not try to guess
@@ -55,7 +55,7 @@
       <para>
 	In this way, <command>pbuilder</command> tries to ensure
 	that packages
-	tested against pbuilder will build properly in
+	tested against <command>pbuilder</command> will build properly in
 	most Debian installations, hopefully resulting
 	in a good overall Debian source-buildability.
       </para>
@@ -112,11 +112,11 @@
 	will update the chroot image.
 	It will extract the chroot, invoke <command>apt-get update</command>
 	and <command>apt-get dist-upgrade</command> inside the
-	chroot, and then recreate the base tarball.
+	chroot, and then recreate the base tar-ball.
       </para>
       <para>
 	It is possible to switch the distribution which the chroot
-	tarball is targeted at at this point.
+	tar-ball is targeted at at this point.
 	Specify <command><option>--distribution <parameter>sid</parameter></option> <option>--override-config</option></command> to change the distribution
 	to sid.
 	<footnote>
@@ -184,9 +184,9 @@
       </para>
       <para>
 	There is a slightly different mode of operation available
-	in pdebuild since version 0.97. pdebuild usually runs
+	in <command>pdebuild</command> since version 0.97. <command>pdebuild</command> usually runs
 	<command>debian/rules clean</command> outside of the chroot;
-	however, it is possible to change the behavior to run it
+	however, it is possible to change the behaviour to run it
 	inside the chroot with
 	the <command><option>--use-pdebuild-internal</option></command>.
 	It will try to bind mount the working directory inside chroot,
@@ -198,7 +198,7 @@
 	<listitem>
 	  <para>
 	    Satisfies build-dependency inside the chroot before creating source package.
-	    (which is a good point that current pdebuild cannot do).
+	    (which is a good point that current <command>pdebuild</command> cannot do).
 	  </para>
 	</listitem>
 	<listitem>
@@ -206,8 +206,8 @@
 	  from inside the chroot.</para>
 	</listitem>
 	<listitem>
-	  <para>Building with pdebuild does not guarantee
-	  that it works with pbuilder.</para>
+	  <para>Building with <command>pdebuild</command> does not guarantee
+	  that it works with <command>pbuilder</command>.</para>
 	</listitem>
 	<listitem>
 	  <para>If making the source package fails,
@@ -235,12 +235,12 @@
       <para>
 	<filename>/etc/pbuilderrc</filename> and
 	<filename>${HOME}/.pbuilderrc</filename>
-	are read in when pbuilder is invoked.
+	are read in when <command>pbuilder</command> is invoked.
 	The possible options are documented in
 	the pbuilderrc.5 manual page.
       </para>
       <para>
-	It is useful to use --configfile option to load up a pre-set
+	It is useful to use <option>--configfile</option> option to load up a preset
 	configuration file  when switching between configuration files for
 	different distributions.
       </para>
@@ -270,17 +270,17 @@
 	packages that are being built with
 	<command>pbuilder</command> to affect the environment outside the chroot.
 	When BUILDUSERNAME configuration option is also set,
-	pbuilder will use the specified user name and fakeroot for building packages,
+	<command>pbuilder</command> will use the specified user name and fakeroot for building packages,
 	instead of running as root inside chroot.
       </para>
       <para>
-	Even when using the fakerooting method, pbuilder will run with
+	Even when using the fakerooting method, <command>pbuilder</command> will run with
 	root privilege when it is required.
 	For example, when installing
-	packages to the chroot, pbuilder will run under root privilege.
+	packages to the chroot, <command>pbuilder</command> will run under root privilege.
       </para>
       <para>
-	To be able to invoke pbuilder without being
+	To be able to invoke <command>pbuilder</command> without being
 	root, you need to use user-mode-linux, as explained
 	in <xref linkend="pbuilder-uml"/>.
       </para>
@@ -288,7 +288,7 @@
     <sect1 id="backporting">
       <title>Using pbuilder for back-porting</title>
       <para>
-	pbuilder can be used for back-porting software from
+	<command>pbuilder</command> can be used for back-porting software from
 	the latest Debian distribution to
 	the older stable distribution, by using a chroot that contains
 	an image of the older distribution, and building packages inside the
@@ -317,14 +317,14 @@
     <sect1 id="massbuild">
       <title>Mass-building packages</title>
       <para>
-	pbuilder can be automated, because its operations are
+	<command>pbuilder</command> can be automated, because its operations are
 	non-interactive.
-	It is possible to run pbuilder through multiple packages
+	It is possible to run <command>pbuilder</command> through multiple packages
 	non-interactively.
 	Several such scripts are known to exist.
 	Junichi Uekawa has been running such a script since 2001,
 	and has been filing bugs on packages that fail the
-	test of pbuilder. There were several problems with auto-building:
+	test of <command>pbuilder</command>. There were several problems with auto-building:
       </para>
       <itemizedlist>
 	<listitem>
@@ -343,18 +343,18 @@
 	</listitem>
       </itemizedlist>
       <para>
-	Most of the initial bugs have been resolved in the pbuilder
+	Most of the initial bugs have been resolved in the <command>pbuilder</command>
 	sweep done around 2002, but these transitional problems which
 	affect a large portion of Debian Archive do arise from time to
 	time.  Regression tests have their values.
       </para>
       <para>
 	A script that was used by Junichi Uekawa is now included in
-	the pbuilder distribution, as <command>pbuildd.sh</command>.
+	the <command>pbuilder</command> distribution, as <command>pbuildd.sh</command>.
 	It is available in <filename>/usr/share/doc/pbuilder/examples/pbuildd/</filename>
 	and its configuration is in <filename>/etc/pbuilder/pbuildd-config.sh</filename>.
 	It should be easy enough to set up for people who are used to
-	pbuilder. It has been running for quite a while, and it should be
+	<command>pbuilder</command>. It has been running for quite a while, and it should be
 	possible to set the application up on your system also.
 	However, it is a new introduction, and please file bugs
 	to the Debian BTS if you know of possible problems,
@@ -373,7 +373,7 @@
 	</listitem>
 	<listitem>
 	  <para>Because you are running random build scripts, it is better to use
-	  the fakeroot option of pbuilder, to avoid running the build
+	  the fakeroot option of <command>pbuilder</command>, to avoid running the build
 	  under root privilege.</para>
 	</listitem>
 	<listitem>
@@ -393,7 +393,7 @@
     <sect1>
       <title>Auto-backporting scripts</title>
       <para>
-	There are some people who use pbuilder to automatically back-port
+	There are some people who use <command>pbuilder</command> to automatically back-port
 	a subset of packages to the stable distribution.
       </para>
       <para>
@@ -405,7 +405,7 @@
     <sect1 id="autotesting">
       <title>Using pbuilder for automated testing of packages</title>
       <para>
-	pbuilder can be used for automated testing of packages.
+	<command>pbuilder</command> can be used for automated testing of packages.
 	It has the feature of allowing hooks to be placed,
 	and these hooks can try to install packages inside
 	the chroot, or run them, or whatever else that
@@ -413,7 +413,7 @@
       </para>
       <itemizedlist>
 	<listitem>
-	  <para>Automatic install-remove-upgrade-remove-install-purge-upgrade-purge testsuite (distributed as an example, <filename>B91dpkg-i</filename>),
+	  <para>Automatic install-remove-upgrade-remove-install-purge-upgrade-purge test-suite (distributed as an example, <filename>B91dpkg-i</filename>),
 	    or just check that everything installs somewhat (<filename>execute_installtest.sh</filename>).</para>
 	</listitem>
 
@@ -424,7 +424,7 @@
 	<listitem>
 	  <para>Automatic debian-test of the package?
 	  The debian-test package has been removed from Debian.
-	  A pbuilder implementation can be found as 
+	  A <command>pbuilder</command> implementation can be found as 
 	  debian/pbuilder-test directory, implemented through B92pkg-test script.</para>
 	</listitem>
      </itemizedlist>
@@ -462,35 +462,38 @@ export DEBIAN_BUILDGCCVER=3.2
   <chapter id="pbuilder-uml">
     <title>Using User-mode-linux with pbuilder</title>
     <para>
-      NOTE that since October 2004, pbuilder for user-mode-linux is
-      not distributed, since user-mode-linux itself is broken in
-      Debian.  A functional user-mode-linux will hopefully be fixed
-      before Debian etch release, but it is not quite determined yet
-      if pbuilder-uml will be ready for etch.
+      NOTE that since October 2004, <command>pbuilder</command> for
+      user-mode-linux is not distributed, since
+      <command>user-mode-linux</command> itself is broken in Debian.
+      A functional <command>user-mode-linux</command> will hopefully
+      be fixed before Debian etch release, but it is not quite
+      determined yet if <command>pbuilder-user-mode-linux</command>
+      will be ready for etch.
     </para>
     <para>
-      It is possible to use user-mode-linux
-      by invoking <command>pbuilder-uml</command>
-      instead of <command>pbuilder</command>.
-      <command>pbuilder-uml</command> doesn't require
-      root privileges, and it uses
-      the copy-on-write (COW) disk access method of User-mode-linux
-      which typically makes it much faster
-      than the traditional <command>pbuilder</command>.
+      It is possible to use user-mode-linux by invoking
+      <command>pbuilder-user-mode-linux</command> instead of
+      <command>pbuilder</command>.
+      <command>pbuilder-user-mode-linux</command> doesn't require root
+      privileges, and it uses the copy-on-write (COW) disk access
+      method of <command>User-mode-linux</command> which typically
+      makes it much faster than the traditional
+      <command>pbuilder</command>.
     </para>
     <para>
-      User-mode-linux is a somewhat less proven platform
-      than the standard Unix tools which
+      <command>User-mode-linux</command> is a somewhat less proven
+      platform than the standard Unix tools which
       <command>pbuilder</command> relies on
-      (<command>chroot</command>,
-      <command>tar</command>,
-      and <command>gzip</command>)
-      but mature enough to support <command>pbuilder-uml</command>
-      since its version 0.59.
-      And since then, pbuilder-uml has seen a rapid evolution.
+      (<command>chroot</command>, <command>tar</command>, and
+      <command>gzip</command>) but mature enough to support
+      <command>pbuilder-user-mode-linux</command> since its version
+      0.59.  And since then,
+      <command>pbuilder-user-mode-linux</command> has seen a rapid
+      evolution.
     </para>
     <para>
-      The configuration of pbuilder-uml goes in three steps:
+      The configuration of <command>pbuilder-user-mode-linux</command>
+      goes in three steps:
       <itemizedlist>
 	<listitem>
 	  <para>Configuration of user-mode-linux</para>
@@ -506,13 +509,14 @@ export DEBIAN_BUILDGCCVER=3.2
     <sect1 id="user-mode-linux-config">
       <title>Configuring user-mode-linux</title>
       <para>
-	UML isn't completely trivial to set up.
-	It would probably be useful to acquaint yourself with it a bit
-	before attempting to use rootstrap or pbuilder-uml.
-	For details,
-	read <filename>/usr/share/doc/uml-utilities/README.Debian</filename>
-	and the user-mode-linux documentation.
-	(It's in a separate package, user-mode-linux-doc.)
+	user-mode-linux isn't completely trivial to set up.  It would
+	probably be useful to acquaint yourself with it a bit before
+	attempting to use <command>rootstrap</command> or
+	<command>pbuilder-user-mode-linux</command>.  For details,
+	read
+	<filename>/usr/share/doc/uml-utilities/README.Debian</filename>
+	and the <command>user-mode-linux</command> documentation.  (It's in a separate
+	package, user-mode-linux-doc.)
       </para>
       <para>
 	<command>user-mode-linux</command> requires
@@ -609,7 +613,7 @@ PBUILDER_UML_IMAGE="/home/dancer/uml-image"
 	    </para>
 	  </listitem>
 	  <listitem>
-	    <para>Run <command>pbuilder-user-mode-linux create --distribution sid</command> to create the image.</para>
+	    <para>Run <command>pbuilder-user-mode-linux <option>create --distribution sid</option></command> to create the image.</para>
 	  </listitem>
 	  <listitem>
 	    <para>Try running <command>pbuilder-user-mode-linux build</command>.</para>
@@ -618,28 +622,30 @@ PBUILDER_UML_IMAGE="/home/dancer/uml-image"
       </para>
     </sect1>
     <sect1 id="consideruml">
-      <title>Considerations for running pbuilder-uml</title>
+      <title>Considerations for running pbuilder-user-mode-linux</title>
       <para>
-	pbuilder-user-mode-linux emulates most of pbuilder, but there
+	<command>pbuilder-user-mode-linux</command> emulates most of <command>pbuilder</command>, but there
 	are some differences.
       </para>
       <itemizedlist>
 	<listitem>
 	  <para>	
-	    pbuilder-user-mode-linux does not support all options of pbuilder
+	    <command>pbuilder-user-mode-linux</command> does not support all options of <command>pbuilder</command>
 	    properly yet. This is a problem, and will be addressed as
 	    specific areas are discovered.
 	  </para>
 	</listitem>
 	<listitem>
 	  <para>
-	    /tmp is handled differently inside pbuilder-uml.
-	    In pbuilder-uml, /tmp is mounted as tmpfs inside UML,
-	    so accessing files under /tmp from outside user-mode-linux
-	    does not work.
-	    It affects options like
-	    <command><option>--configfile</option></command>,
-	    and when trying to build packages placed under <filename>/tmp</filename>.
+	    /tmp is handled differently inside
+	    <command>pbuilder-user-mode-linux</command>.  In
+	    <command>pbuilder-user-mode-linux</command>,
+	    <filename>/tmp</filename> is mounted as tmpfs inside UML,
+	    so accessing files under <filename>/tmp</filename> from
+	    outside user-mode-linux does not work.  It affects options
+	    like <command><option>--configfile</option></command>, and
+	    when trying to build packages placed under
+	    <filename>/tmp</filename>.
 	  </para>
 	</listitem>
       </itemizedlist>
@@ -647,8 +653,8 @@ PBUILDER_UML_IMAGE="/home/dancer/uml-image"
     <sect1 id="paralleluml">
       <title>Parallel running of pbuilder-user-mode-linux</title>
       <para>
-	To run pbuilder-uml in parallel on a system, there are a few things
-	to bear in mind.
+	To run <command>pbuilder-user-mode-linux</command> in parallel
+	on a system, there are a few things to bear in mind.
       </para>
       <itemizedlist>
 	<listitem>
@@ -657,9 +663,9 @@ PBUILDER_UML_IMAGE="/home/dancer/uml-image"
 	</listitem>
 	<listitem>
 	  <para>
-	    If you are not using slirp, UML processes which are
+	    If you are not using slirp, user-mode-linux processes which are
 	    running in parallel need to have different IP addresses.
-	    Just trying to run the <command>pbuilder-uml</command>
+	    Just trying to run the <command>pbuilder-user-mode-linux</command>
 	    several times will result in failure to access the network.
 	    But something like the following will work:
 	    <screen>
@@ -674,28 +680,31 @@ done
       </itemizedlist>
     </sect1>
     <sect1 id="pbuilderumlwrap">
-      <title>Using pbuilder-uml as a wrapper script to start up a virtual machine</title>
+      <title>Using pbuilder-user-mode-linux as a wrapper script to start up a virtual machine</title>
       <para>
-	It is possible to use pbuilder-uml for other uses than just building Debian
-	packages.
-	<command>pbuilder-user-mode-linux login</command>
-	will let a user use a shell inside the user-mode-linux
-	pbuilder base image,
-	and <command>pbuilder-user-mode-linux execute</command> will
-	allow the user to execute a script inside the image.
+	It is possible to use
+	<command>pbuilder-user-mode-linux</command> for other uses
+	than just building Debian packages.
+	<command>pbuilder-user-mode-linux
+	<option>login</option></command> will let a user use a shell
+	inside the user-mode-linux <command>pbuilder</command> base
+	image, and <command>pbuilder-user-mode-linux
+	<option>execute</option></command> will allow the user to
+	execute a script inside the image.
       </para>
       <para>
 	You can use the script to install ssh and add a new user,
-	so that it is possible to access inside the UML through ssh.
+	so that it is possible to access inside the user-mode-linux through ssh.
       </para>
       <para>
 	Note that it is not possible to use a script from
-	<filename>/tmp</filename> due to the way pbuilder-uml mounts
-	a tmpfs at <filename>/tmp</filename>.
+	<filename>/tmp</filename> due to the way
+	<command>pbuilder-user-mode-linux</command> mounts a tmpfs at
+	<filename>/tmp</filename>.
       </para>
       <para>
 	The following example script may be useful in starting a sshd
-	inside uml.
+	inside user-mode-linux.
       </para>
       <screen>
 #!/bin/bash
@@ -724,33 +733,33 @@ read
     <sect1>
       <title>pbuilder create fails</title>
       <para>
-	It often happens that pbuilder cannot create the latest chroot.
-	Try upgrading pbuilder and debootstrap.
+	It often happens that <command>pbuilder</command> cannot create the latest chroot.
+	Try upgrading <command>pbuilder</command> and debootstrap.
 	It is currently only possible to create software that handles the
 	past. Future prediction is a feature which may be added later after
 	we have become comfortable with the past.
       </para>
       <para>
-	There are people who occasionally backport debootstrap to stable
+	There are people who occasionally back port debootstrap to stable
 	versions; hunt for them.
       </para>
       <para>
 	When there are errors with the debootstrap phase,
 	the debootstrap script needs to be fixed.
-	pbuilder does not provide a way to work around debootstrap.
+	<command>pbuilder</command> does not provide a way to work around debootstrap.
       </para>
     </sect1>
     <sect1 id="bindmountlimits">
       <title>Directories that cannot be bind-mounted</title>
       <para>
-	Because of the way pbuilder works, there are several directories
-	which cannot be bind-mounted when running pbuilder.
-	The directories include <filename>/tmp</filename>,
-	<filename>/var/cache/pbuilder</filename>,
-	and system directories such as <filename>/etc</filename> and
-	<filename>/usr</filename>.
-	The recommendation is to use directories under the user's home directory
-	for bind-mounts.
+	Because of the way <command>pbuilder</command> works, there
+	are several directories which cannot be bind-mounted when
+	running <command>pbuilder</command>.  The directories include
+	<filename>/tmp</filename>,
+	<filename>/var/cache/pbuilder</filename>, and system
+	directories such as <filename>/etc</filename> and
+	<filename>/usr</filename>.  The recommendation is to use
+	directories under the user's home directory for bind-mounts.
       </para>
     </sect1>
     <sect1 id="modifyupdate">
@@ -769,20 +778,21 @@ $ cp C10shell ~/loginhooks/E10shell
 $ sudo pbuilder update --hookdir ~/loginhooks/E10shell
       </screen>
       <para>
-	It is also possible to add --save-after-exec
-	and/or --save-after-login options
+	It is also possible to add <option>--save-after-exec</option>
+	and/or <option>--save-after-login</option> options
 	to the <command>pbuilder login</command> session
 	to accomplish the goal.
-	It is possible to add the --uml-login-nocow option
-	to <command>pbuilder-user-mode-linux login</command> session
+	It is possible to add the <option>--uml-login-nocow</option> option
+	to <command>pbuilder-user-mode-linux <option>login</option></command> session
 	as well.
       </para>
     </sect1>
     <sect1 id="BUILDRESULTUID">
       <title>Setting BUILDRESULTUID for sudo sessions</title>
       <para>
-	It is possible to set BUILDRESULTUID=$SUDO_UID in pbuilderrc
-	to set the proper BUILDRESULTUID when using sudo.
+	It is possible to set
+	<screen>BUILDRESULTUID=$SUDO_UID</screen> in pbuilderrc to set
+	the proper BUILDRESULTUID when using <command>sudo</command>.
       </para>
     </sect1>
     <sect1 id="tmpdir">
@@ -799,25 +809,25 @@ $ sudo pbuilder update --hookdir ~/loginhooks/E10shell
       </para>
       <para>
 	An example script is provided as
-	<filename>examples/D10tmp</filename> with pbuilder.
+	<filename>examples/D10tmp</filename> with <command>pbuilder</command>.
       </para>
     </sect1>
     <sect1 id="DISTRIBUTIONSWITCH">
-      <title>Creating a shortcut for running pbuilder with a specific distribution</title>
+      <title>Creating a shortcut for running <command>pbuilder</command> with a specific distribution</title>
       <para>
-	When working with multiple chroots, it would be nice to work with
-	scripts that reduce the amount of typing.
-	An example script
-	<filename>pbuilder-distribution.sh</filename> is provided as an example.
-	Invoking the script as <filename>pbuilder-woody</filename> will invoke
-	pbuilder with a woody chroot.
+	When working with multiple chroots, it would be nice to work
+	with scripts that reduce the amount of typing.  An example
+	script <filename>pbuilder-distribution.sh</filename> is
+	provided as an example.  Invoking the script as
+	<filename>pbuilder-sarge</filename> will invoke
+	<command>pbuilder</command> with a sarge chroot.
       </para>
     </sect1>
     <sect1>
       <title>Using special apt sources lists, and local packages</title>
       <para>
-	If you have some very specialized requirements on your
-	apt setup inside pbuilder,
+	If you have some very specialised requirements on your
+	apt setup inside <command>pbuilder</command>,
 	it is possible to specify that through
 	the <command><option>--othermirror</option></command>
 	option.
@@ -825,7 +835,7 @@ $ sudo pbuilder update --hookdir ~/loginhooks/E10shell
 	<command><option>--othermirror "deb http://local/mirror stable main|deb-src http://local/source/repository ./"</option></command>
       </para>
       <para>
-	To use the local filesystem instead of http, it is necessary to do
+	To use the local file system instead of HTTP, it is necessary to do
 	bind-mounting.
 	<command><option>--bindmounts</option></command>
 	is a command-line option useful for such cases.
@@ -870,9 +880,10 @@ cd /var/cache/pbuilder/result/
     <sect1>
       <title>Different bash prompts inside pbuilder login</title>
       <para>
-	To make distinguishing bash prompts inside pbuilder
-	easier, it is possible to set environment variables such as PS1
-	inside <filename>pbuilderrc</filename>
+	To make distinguishing bash prompts inside
+	<command>pbuilder</command> easier, it is possible to set
+	environment variables such as PS1 inside
+	<filename>pbuilderrc</filename>
       </para>
       <para>
 	With versions of bash more recent than 2.05b-2-15,
@@ -896,32 +907,33 @@ cd /var/cache/pbuilder/result/
     <sect1>
       <title>Using /var/cache/apt/archives for the package cache</title>
       <para>
-	For the help of low-bandwidth systems,
-	it is possible to use <filename>/var/cache/apt/archives</filename> as the
-	package cache.
-	Just specify it instead of the default <filename>/var/cache/pbuilder/aptcache</filename>.
+	For the help of low-bandwidth systems, it is possible to use
+	<filename>/var/cache/apt/archives</filename> as the package
+	cache.  Just specify it instead of the default
+	<filename>/var/cache/pbuilder/aptcache</filename>.
       </para>
       <para>
-	It is however not possible to do so currently with the user-mode-linux
-	version of pbuilder, because <filename>/var/cache/apt/archives</filename>
-	is usually only writable by root.
+	It is however not possible to do so currently with the
+	user-mode-linux version of <command>pbuilder</command>,
+	because <filename>/var/cache/apt/archives</filename> is
+	usually only writable by root.
       </para>
       <para>
-	Use of dedicated tools such as apt-proxy is recommended, since caching of packages
-	would benefit the system outside the scope of pbuilder.
+	Use of dedicated tools such as apt-proxy is recommended, since
+	caching of packages would benefit the system outside the scope
+	of <command>pbuilder</command>.
       </para>
     </sect1>
-    <sect1 id="woodybackport">
-      <title>pbuilder backported to stable Debian releases</title>
+    <sect1 id="stablebackport">
+      <title>pbuilder back ported to stable Debian releases</title>
       <para>
-	Currently stable backport to sarge is not known to be available.
-	It should hopefully soon be available.
+	Currently stable back port of pbuilder is avialable at backports.org.
       </para>
     </sect1>
     <sect1 id="LOGNAME">
       <title>Warning about LOGNAME not being defined</title>
       <para>
-	You might see a lot of warning messages when running pbuilder.
+	You might see a lot of warning messages when running <command>pbuilder</command>.
       </para>
       <para>
 	<screen>
@@ -929,15 +941,16 @@ cd /var/cache/pbuilder/result/
 	</screen>
       </para>
       <para>
-	It is currently safe to ignore this warning message.
-	Please report back if you find any problem with having LOGNAME unset.
-	Setting LOGNAME caused a few problems when invoking chroot.
+	It is currently safe to ignore this warning message.  Please
+	report back if you find any problem with having LOGNAME unset.
+	Setting LOGNAME caused a few problems when invoking
+	<command>chroot</command>.
       </para>
     </sect1>
     <sect1 id="nobuildconflictessential">
       <title>Cannot Build-conflict against an essential package</title>
       <para>
-	pbuilder does not currently allow Build-Conflicts against
+	<command>pbuilder</command> does not currently allow Build-Conflicts against
 	essential packages.
 	It should be obvious that essential packages should not be
 	removed from a working Debian system, and a source
@@ -948,28 +961,29 @@ cd /var/cache/pbuilder/result/
     <sect1>
       <title>Avoiding the "ln: Invalid cross-device link" message</title>
       <para>
-	By default, pbuilder uses hard links to manage the pbuilder package cache.
-	It is not possible to make hard links across different devices;
-	and thus this error will occur, depending on your set up.
-	If this happens, set <screen>APTCACHEHARDLINK=no</screen>
-	in your pbuilderrc file.
+	By default, <command>pbuilder</command> uses hard links to
+	manage the <command>pbuilder</command> package cache.  It is
+	not possible to make hard links across different devices; and
+	thus this error will occur, depending on your set up.  If this
+	happens, set <screen>APTCACHEHARDLINK=no</screen> in your
+	pbuilderrc file.
       </para>
     </sect1>
     <sect1>
       <title>Using fakechroot</title>
       <para>
-	It is possible to use <command>fakechroot</command> instead of being root
-	to run pbuilder; however, several things make this impractical.
-	<command>fakechroot</command> overrides library loads and tries to
-	override default libc functions when providing the functionality of
-	virtual chroot.
-	However, some binaries do no use libc to function, or override the overriding
-	provided by fakechroot.
-	One example is <command>ldd</command>.
-	Inside <command>fakechroot</command>,
-	<command>ldd</command>
-	will check the library dependency outside of the chroot,
-	which is not the expected behavior.
+	It is possible to use <command>fakechroot</command> instead of
+	being root to run <command>pbuilder</command>; however,
+	several things make this impractical.
+	<command>fakechroot</command> overrides library loads and
+	tries to override default libc functions when providing the
+	functionality of virtual <command>chroot</command>.  However,
+	some binaries do no use libc to function, or override the
+	overriding provided by <command>fakechroot</command>.  One
+	example is <command>ldd</command>.  Inside
+	<command>fakechroot</command>, <command>ldd</command> will
+	check the library dependency outside of the chroot, which is
+	not the expected behaviour.
       </para>
       <para>
 	To work around the problem, fakechroot provides a patch for debootstrap.
@@ -982,7 +996,7 @@ cd /var/cache/pbuilder/result/
     <sect1 id="debconfinsidepbuilder">
       <title>Using debconf inside pbuilder sessions</title>
       <para>
-	To use debconf inside pbuilder, setting DEBIAN_FRONTEND to
+	To use debconf inside <command>pbuilder</command>, setting DEBIAN_FRONTEND to
 	<quote>readline</quote> in <filename>pbuilderrc</filename> should work.
 	Setting it to <quote>dialog</quote> should also work, but make sure
 	whiptail or dialog is installed inside the chroot.
@@ -991,20 +1005,20 @@ cd /var/cache/pbuilder/result/
     <sect1 id="nodev">
       <title>nodev mount options hinder pbuilder activity</title>
       <para>
-	If you see messages such as this when building a chroot, you are mounting the filesystem with
+	If you see messages such as this when building a chroot, you are mounting the file system with
 	the nodev option.
       </para>
       <screen>
 	/var/lib/dpkg/info/base-files.postinst: /dev/null: Permission denied
       </screen>
       <para>
-	You will also have problems if you mount the filesystem with
+	You will also have problems if you mount the file system with
 	the noexec option, or nosuid.
-	Make sure you do not have these flags set when mounting the filesystem for
+	Make sure you do not have these flags set when mounting the file system for
 	<filename>/var/cache/pbuilder</filename> or $BUILDPLACE.
       </para>
       <para>
-	This is not a problem when using User-mode-linux.
+	This is not a problem when using <command>user-mode-linux</command>.
       </para>
       <para>
 	See <ulink url="http://bugs.debian.org/316135">
@@ -1015,38 +1029,43 @@ cd /var/cache/pbuilder/result/
     <sect1 id="faqslowpbuilder">
       <title>pbuilder is slow</title>
       <para>
-	pbuilder is often slow. The slowest part of pbuilder is extracting the tar.gz every time
-	pbuilder is invoked. That can be avoided by using <command>pbuilder-user-mode-linux</command>.
-	<command>pbuilder-user-mode-linux</command> uses
-	COW filesystem, and thus does not need to clean up and recreate the root filesystem.
+	<command>pbuilder</command> is often slow. The slowest part of
+	<command>pbuilder</command> is extracting the tar.gz every
+	time <command>pbuilder</command> is invoked. That can be
+	avoided by using <command>pbuilder-user-mode-linux</command>.
+	<command>pbuilder-user-mode-linux</command> uses COW file
+	system, and thus does not need to clean up and recreate the
+	root file system.
       </para>
       <para>
-	pbuilder-user-mode-linux is slower in executing the actual build system, due to the
-	usual user-mode-linux overhead for system calls. It is more friendly to the hard drive.
+	<command>pbuilder-user-mode-linux</command> is slower in
+	executing the actual build system, due to the usual
+	<command>user-mode-linux</command> overhead for system
+	calls. It is more friendly to the hard drive.
       </para>
       <para>
-	pbuilder with cowdancer is under development, to allow
-	pbuilder to start up faster; when it is ready, it should 
+	<command>pbuilder</command> with cowdancer is under development, to allow
+	<command>pbuilder</command> to start up faster; when it is ready, it should 
 	be able to replace the current setup.
       </para>
     </sect1>
     <sect1 id="chrootmemo">
       <title>Creating a chroot reminder</title>
       <para>
-	You may want a sign that you are inside a chroot, when
-	working with chroot.
-	Check out the <filename>examples/F90chrootmemo</filename>
-	hook script.
-	It will create a file called <filename>/CHROOT</filename>
-	inside your chroot.
+	You may want a sign that you are inside a chroot, when working
+	with chroot.  Check out the
+	<filename>examples/F90chrootmemo</filename> hook script.  It
+	will create a file called <filename>/CHROOT</filename> inside
+	your chroot.
       </para>
     </sect1>
     <sect1 id="sponsor">
       <title>Using pdebuild to sponsor package</title>
       <para>
-	To sign a package marking for sponsorship,
-	it is possible to use<command><option> --auto-debsign</option></command> and
-	<command><option>--debsign-k</option></command> options of pdebuild.
+	To sign a package marking for sponsorship, it is possible to
+	use<command><option> --auto-debsign</option></command> and
+	<command><option>--debsign-k</option></command> options of
+	<command>pdebuild</command>.
       </para>
       <screen>
 	<command>pdebuild  <option>--auto-debsign </option> <option>--debsign-k </option><parameter>XXXXXXXX</parameter></command>
@@ -1055,24 +1074,24 @@ cd /var/cache/pbuilder/result/
     <sect1 id="sourcechanges">
       <title>Why is there a source.changes file in ../?</title>
       <para>
-	When running pdebuild, pbuilder will run dpkg-buildpackage to create a
-	Debian source package to pass it on to pbuilder.
+	When running <command>pdebuild</command>, <command>pbuilder</command> will run dpkg-buildpackage to create a
+	Debian source package to pass it on to <command>pbuilder</command>.
 	File named XXXX_YYY_source.changes is what remains from that process.
 	It is harmless unless you try to upload it to the Debian archive.
       </para>
       <para>
-	This behavior is different when running through --use-pdebuild-internal
+	This behaviour is different when running through <option>--use-pdebuild-internal</option>
       </para>
     </sect1>
     <sect1 id="amd64i386">
       <title>amd64 and i386-mode</title>
       <para>
-	amd64 architectures are capable of running binaries in 
-	i386 mode.
-	It is possible to use pbuilder to run packages, 
-	using <command>linux32</command>
-	and <command>debootstrap <option>--arch</option></command> option.
-	Specifically, a command-line option like the following will work.
+	amd64 architectures are capable of running binaries in i386
+	mode.  It is possible to use <command>pbuilder</command> to
+	run packages, using <command>linux32</command> and
+	<command>debootstrap <option>--arch</option></command> option.
+	Specifically, a command-line option like the following will
+	work.
       </para>
       <para>
 	<screen>
@@ -1085,10 +1104,11 @@ cd /var/cache/pbuilder/result/
     <sect1 id="ccache">
       <title>How to use ccache</title>
       <para>
-	To use ccache with pbuilder, use the following for configuration.
-	Note that the directory used for CCACHE_DIR needs to exist, and 
-	be writable by user within chroot.
-	The default user within chroot is uid=1234.
+	To use <command>ccache</command> with
+	<command>pbuilder</command>, use the following for
+	configuration.  Note that the directory used for CCACHE_DIR
+	needs to exist, and be writable by user within <command>chroot</command>.  The
+	default user within <command>chroot</command> is <screen>uid=1234</screen>.
       </para>
       <screen>
 export CCACHE_DIR="/var/cache/pbuilder/ccache"
@@ -1110,19 +1130,20 @@ BINDMOUNTS="${CCACHE_DIR}"
     <sect1 id="bugreport">
       <title>Reporting bugs </title>
       <para>
-	To report bugs, it would be important to have a 
-	log of what's going wrong.
-	Most of the time, adding a --debug option and re-running the 
-	session should do the trick.
-	Please send the log of such session along with your problem
-	to ease the debugging process.
+	To report bugs, it would be important to have a log of what's
+	going wrong.  Most of the time, adding a
+	<command><option>--debug</option></command> option and
+	re-running the session should do the trick.  Please send the
+	log of such session along with your problem to ease the
+	debugging process.
       </para>
     </sect1>
     <sect1 id="mailinglist">
       <title>Mailing list</title>
       <para>
-	There is a mailing list for pbuilder on alioth (pbuilder-maint@lists.alioth.debian.org).
-	You can subscribe through the alioth web interface.
+	There is a mailing list for <command>pbuilder</command> on
+	alioth (pbuilder-maint@lists.alioth.debian.org).  You can
+	subscribe through the alioth web interface.
 	<ulink url="http://alioth.debian.org/mail/?group_id=30778">
 	  http://alioth.debian.org/mail/?group_id=30778</ulink>.
       </para>
@@ -1133,17 +1154,17 @@ BINDMOUNTS="${CCACHE_DIR}"
 	For coordination and communication,
 	IRC channel #pbuilder on irc.oftc.net is used.
 	Please log your intent there when you are going to 
-	start doing some changes and commiting some change.
+	start doing some changes and committing some change.
       </para>
     </sect1>
     <sect1 id="development">
       <title>Development</title>
       <para>
-	This section is a start of what I want to do
-	later.
+	This section tries to document current development practices
+	and how things generally operate in development.
       </para>
       <para>
-	pbuilder is now co-maintained at alioth.
+	<command>pbuilder</command> is now co-maintained at alioth.
 	There is an alioth project page at
 	<ulink url="http://alioth.debian.org/projects/pbuilder">
 	http://alioth.debian.org/projects/pbuilder</ulink>.
@@ -1154,35 +1175,33 @@ cvs -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder login
 cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
       </screen>
       <para>
-	Testsuites are available in tests/ directory, and 
-	changes are expected not to break the testsuites.
-	<filename>./run-test.sh</filename> is a basic testsuite, which puts a summary in 
+	Test-suites are available in <filename>tests/</filename> directory, and 
+	changes are expected not to break the test-suites.
+	<filename>./run-test.sh</filename> is a basic test-suite, which puts a summary in 
 	<filename>run-test.log</filename>, and <filename>run-test-cdebootstrap.log</filename>.
-	<filename>./run-test-regression.sh</filename> is a regression testsuite,
+	<filename>./run-test-regression.sh</filename> is a regression test-suite,
 	which puts the result in <filename>run-test-regression.log</filename>
       </para>
       <para>
-	When making changes, a description of the 
-	change targeted at developers should be documented in 
-	ChangeLog, and committed.
-	A brief summary of the change targeting end users
-	should be documented in debian/changelog, 
-	so that users can see them.
-	Note that the description of debian/changelog is 
-	targeted at users, and ChangeLog is targeted 
-	at developers.
-	For CVS commit messages, a cut-n-paste of 
-	ChangeLog diff should be enough.
+	When making changes, a description of the change targeted at
+	developers should be documented in
+	<filename>ChangeLog</filename>, and committed.  A brief
+	summary of the change targeting end users should be documented
+	in <filename>debian/changelog</filename>, so that users can
+	see them.  Note that the description of
+	<filename>debian/changelog</filename> is targeted at users,
+	and <filename>ChangeLog</filename> is targeted at developers.
+	For CVS commit messages, a cut-n-paste of
+	<filename>ChangeLog</filename> diff should be enough.
       </para>
       <para>
-	A TODO file is available in debian/TODO.
-	It's mostly not well-maintained, 
-	but hopefully it will be more up-to-date
-	when people start using it.
-	emacs todoo-mode is used in editing the file.
+	A TODO file is available in <filename>debian/TODO</filename>.
+	It's mostly not well-maintained, but hopefully it will be more
+	up-to-date when people start using it.  emacs todoo-mode is
+	used in editing the file.
       </para>
       <para>
-	When releasing a new version of pbuilder,
+	When releasing a new version of <command>pbuilder</command>,
 	the version is tagged with the cvs tag
 	releaseX_XXX.
 	<!-- (shell-command "cd ../ && cvs tag $(dpkg-parsechangelog | sed -n 's/\\./_/;s/^Version: /release/p' )") -->
@@ -1202,7 +1221,7 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
       </para>
       <para>
 	<command>pbuilder login </command> is a debugging feature for
-	pbuilder itself, but it also allows users to have a temporary chroot.
+	<command>pbuilder</command> itself, but it also allows users to have a temporary chroot.
       </para>
       <para>
 	Note that the chroot is cleaned after logging out of the shell,
@@ -1212,7 +1231,7 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
     <sect1>
       <title>Running little programs inside the chroot</title>
       <para>
-	To facilitate using pbuilder for other uses,
+	To facilitate using <command>pbuilder</command> for other uses,
 	<command>pbuilder execute</command> is available.
 	<command>pbuilder execute </command> will take a script
 	specified in the command-line argument, and
@@ -1225,32 +1244,38 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
     </sect1>
   </chapter>
   <chapter id="experimental">
-    <title>Experimental or wish list features of pbuilder</title>
+    <title>Experimental or wish-list features of pbuilder</title>
     <para>
       There are some advanced features, above that of the
-      basic feature of pbuilder, for some specific purposes.
+      basic feature of <command>pbuilder</command>, for some specific purposes.
     </para>
     <sect1 id="lvm">
       <title>Using LVM</title>
       <para>
 	LVM2 has a useful snapshot function that features Copy-on-write images.
-	That could be used for pbuilder just as it can be used for
-	the user-mode-linux pbuilder port.
+	That could be used for <command>pbuilder</command> just as it can be used for
+	the user-mode-linux <command>pbuilder</command> port.
 	It may prove to be faster, but it is not implemented yet,
 	and so no measurement has been made, yet.
       </para>
       <para>
-	User-mode-linux cow support has been preferred for 
-	pbuilder-uml, but the idea of using LVM is interesting.
+	<command>User-mode-linux</command> cow support has been
+	preferred for <command>pbuilder-user-mode-linux</command>, but
+	the idea of using LVM is interesting.
       </para>
     </sect1>
     <sect1 id="cowdancer">
       <title>Using cowdancer</title>
       <para>
-	cowdancer allows copy-on-write semantics on filesystem 
-	using hardlinks and hardlink-breaking-on-write tricks.
-	pbuilder using cowdancer seems to be much faster
-	and it is one ideal point for improvement.
+	<command>cowdancer</command> allows copy-on-write semantics on
+	file system using hard links and hard-link-breaking-on-write
+	tricks.  <command>pbuilder</command> using
+	<command>cowdancer</command> seems to be much faster and it is
+	one ideal point for improvement.
+	<command>cowbuilder</command>, a wrapper for
+	<command>pbuilder</command> for using
+	<command>cowdancer</command> is available from
+	<command>cowdancer</command> package since 0.14
       </para>
     </sect1>
     <sect1 id="withouttargz">
@@ -1258,7 +1283,7 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
       <para>
 	The <command><option>--no-targz</option></command>
 	option of <command>pbuilder</command>
-	will allow usage of pbuilder in a different way
+	will allow usage of <command>pbuilder</command> in a different way
 	from conventional usage.
 	It will try to use an existing chroot,
 	and will not try to clean up after
@@ -1270,8 +1295,8 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
 	It should be possible to create chroot images
 	for <command>dchroot</command> with the following commands:
 	<screen>
-# pbuilder create --distribution potato --no-targz --basetgz /chroot/potato
-# pbuilder create --distribution woody --no-targz --basetgz /chroot/woody
+# pbuilder create --distribution sarge --no-targz --basetgz /chroot/sarge
+# pbuilder create --distribution etch --no-targz --basetgz /chroot/etch
 # pbuilder create --distribution sid --no-targz --basetgz /chroot/sid
 	</screen>
       </para>
@@ -1303,7 +1328,7 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
 	    </row>
 	    <row>
 	      <entry><filename>/var/cache/pbuilder/base.tgz</filename></entry>
-	      <entry>Default location pbuilder uses for base.tgz, the tarball containing a basic Debian installation
+	      <entry>Default location pbuilder uses for base.tgz, the tar-ball containing a basic Debian installation
 	        with only the build-essential packages.
 	      </entry>
 	    </row>
@@ -1313,31 +1338,31 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
 	    </row>
 	    <row>
 	      <entry><filename>/var/cache/pbuilder/aptcache</filename></entry>
-	      <entry>Default location pbuilder will use as apt cache, to store deb packages required during pbuilder build.</entry>
+	      <entry>Default location <command>pbuilder</command> will use as apt cache, to store deb packages required during <command>pbuilder</command> build.</entry>
 	    </row>
 	    <row>
 	      <entry><filename>/var/cache/pbuilder/result</filename></entry>
-	      <entry>Default location pbuilder puts the deb files and other files created after build</entry>
+	      <entry>Default location <command>pbuilder</command> puts the deb files and other files created after build</entry>
 	    </row>
 	    <row>
 	      <entry><filename>/var/cache/pbuilder/pbuilder-umlresult</filename></entry>
-	      <entry>Default location pbuilder-user-mode-linux puts the deb files and other files created after build </entry>
+	      <entry>Default location <command>pbuilder-user-mode-linux</command> puts the deb files and other files created after build </entry>
 	    </row>
 	    <row>
 	      <entry><filename>/var/cache/pbuilder/pbuilder-mnt</filename></entry>
-	      <entry>Default location pbuilder-user-mode-linux uses for mounting the COW filesystem, for chrooting.</entry>
+	      <entry>Default location <command>pbuilder-user-mode-linux</command> uses for mounting the COW file system, for chrooting.</entry>
 	    </row>
 	    <row>
 	      <entry><filename>/tmp</filename></entry>
-	      <entry>pbuilder-user-mode-linux will mount tmpfs for work.</entry>
+	      <entry><command>pbuilder-user-mode-linux</command> will mount tmpfs for work.</entry>
 	    </row>
 	    <row>
 	      <entry><filename>${HOME}/tmp/PID.cow</filename></entry>
-	      <entry>pbuilder-user-mode-linux use this directory for location of COW filesystem.</entry>
+	      <entry><command>pbuilder-user-mode-linux</command> use this directory for location of COW file system.</entry>
 	    </row>
 	    <row>
 	      <entry><filename>${HOME}/uml-image</filename></entry>
-	      <entry>pbuilder-user-mode-linux use this directory for UML full disk image.</entry>
+	      <entry><command>pbuilder-user-mode-linux</command> use this directory for user-mode-linux full disk image.</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
@@ -1365,14 +1390,17 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
 	    </row>
 	    <row>
 	      <entry><filename>/tmp/buildd</filename></entry>
-	      <entry>Default place used in pbuilder to place the Debian package to be processed.
-		/tmp/buildd/packagename-version/ will be the root directory of the package being processed.
-		HOME environment variable is set to this value inside chroot by pbuilder-buildpackage
+	      <entry>Default place used in <command>pbuilder</command>
+	      to place the Debian package to be processed.
+	      <filename>/tmp/buildd/packagename-version/</filename>
+	      will be the root directory of the package being
+	      processed.  HOME environment variable is set to this
+	      value inside chroot by pbuilder-buildpackage
 	      </entry>
 	    </row>
 	    <row>
 	      <entry><filename>/run</filename></entry>
-	      <entry>The script passwd as an argument to pbuilder execute 
+	      <entry>The script passwd as an argument to <command>pbuilder</command> execute 
 		is passed on.
 	      </entry>
 	    </row>
@@ -1385,14 +1413,15 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
 	    <row>
 	      <entry><filename>/var/cache/apt/archives</filename></entry>
 	      <entry>
-		pbuilder copies the content of this directory to and from 
+		<command>pbuilder</command> copies the content of this directory to and from 
 		the aptcache directory of outside chroot.
 	      </entry>
 	    </row>
 	    <row>
 	      <entry><filename>/tmp/XXXX</filename></entry>
-	      <entry>pbuilder-user-mode-linux uses a script in /tmp 
-		to bootstrap into user-mode-linux</entry>
+	      <entry><command>pbuilder-user-mode-linux</command> uses
+	      a script in <filename>/tmp</filename> to bootstrap into
+	      user-mode-linux</entry>
 	    </row>
 	  </tbody>
 	</tgroup>
@@ -1400,21 +1429,21 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
     </sect1>
   </chapter>
   <chapter>
-    <title>Minor details</title>
+    <title>Minor archaeological details</title>
     <sect1>
       <title>Documentation history </title>
       <para>
 	This document was started on 28 Dec 2002 by
 	Junichi Uekawa, trying to document what is known
-	about pbuilder.
+	about <command>pbuilder</command>.
       </para>
       <para>
-	This documentation is available from the pbuilder source tarball,
-	and from the CVS repository of pbuilder (web-based access is possible).
+	This documentation is available from the <command>pbuilder</command> source tar-ball,
+	and from the CVS repository of <command>pbuilder</command> (web-based access is possible).
 	A copy of this documentation can be found on the
 	<ulink url="http://pbuilder.alioth.debian.org/pbuilder-doc.html">Alioth project page for pbuilder</ulink>.
 	<ulink url="http://pbuilder.alioth.debian.org/pbuilder-doc.pdf">There is also a PDF version</ulink>.
-	The homepage for pbuilder is
+	The homepage for <command>pbuilder</command> is
 	<ulink url="http://www.netfort.gr.jp/~dancer/software/pbuilder.html">
 	  http://www.netfort.gr.jp/~dancer/software/pbuilder.html
 	</ulink>
@@ -1434,10 +1463,10 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
       <title>Possibly inaccurate Background History of pbuilder</title>
       <para>
 	The following is a most possibly inaccurate account of how
-	pbuilder came to happen, and other attempts to
-	make something like pbuilder happen.
+	<command>pbuilder</command> came to happen, and other attempts to
+	make something like <command>pbuilder</command> happen.
 	This part of the document was originally in the AUTHORS file,
-	to give credit to those who existed before pbuilder.
+	to give credit to those who existed before <command>pbuilder</command>.
       </para>
       <sect2>
 	<title>The Time Before pbuilder</title>
@@ -1477,7 +1506,7 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
 	<para>
 	  Building packages from source using Build-Depends
 	  information within a chroot sounded trivial; and
-	  pbuilder was born. It was initially a shell script
+	  <command>pbuilder</command> was born. It was initially a shell script
 	  with only a few lines, which called debootstrap
 	  and chroot and dpkg-buildpackage in the same run,
 	  but soon, it was decided that that's too slow.
@@ -1486,7 +1515,7 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
 	  Yes, and it took almost an year to get things somewhat
 	  right, and in the middle of the process, Debian 3.0
 	  was released. Yay.
-	  Debian 3.0 wasn't completely buildable with pbuilder,
+	  Debian 3.0 wasn't completely buildable with <command>pbuilder</command>,
 	  but the amount of packages which are not buildable
 	  is steadily decreasing. (I hope)
 	</para>
@@ -1494,27 +1523,31 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
       <sect2 id="secondyear">
 	<title>And the second year of its life</title>
 	<para>
-	  Someone wanted pbuilder to not run as root, and as
-	  User-mode-linux has become more useful as time passed, I've
-	  started experimenting with pbuilder-uml.  pbuilder-uml has
-	  not been able to run as often as it should, and
-	  bootstrapping user-mode-linux environment has been pretty
-	  hard.
+	  Someone wanted <command>pbuilder</command> to not run as
+	  root, and as User-mode-linux has become more useful as time
+	  passed, I've started experimenting with
+	  <command>pbuilder-user-mode-linux</command>.
+	  <command>pbuilder-user-mode-linux</command> has not stayed
+	  functional as much as I would have liked, and bootstrapping
+	  <command>user-mode-linux</command> environment has been
+	  pretty hard, due to the quality of user-mode-linux code or
+	  packaging at that time, which kept on breaking network
+	  support in one way or the other.
 	</para>
       </sect2>
       <sect2 id="fifthyear">
 	<title>Fifth year of pbuilder</title>
 	<para>
-	  pbuilder is now widely adopted as a 'almost standard' tool
+	  <command>pbuilder</command> is now widely adopted as a 'almost standard' tool
 	  for testing packages, and building packages in a pristine
 	  environment.  There are other similar tools that do similar
 	  tasks, but they do not share the exact same goal.  To
-	  commemorate this fact, pbuilder is now co-maintained with
+	  commemorate this fact, <command>pbuilder</command> is now co-maintained with
 	  several people.
 	</para>
 	<para>
-	  sbuild is now a well-maintained Debian package within
-	  Debian, and with pbuilder being such a slow monstor, some
+	  <command>sbuild</command> is now a well-maintained Debian package within
+	  Debian, and with <command>pbuilder</command> being such a slow monster, some
 	  people prefer the approach of sbuild.  Development to use
 	  LVM-snapshots, cowloop, or cowdancer is hoped to improve the
 	  situation somewhat.
@@ -1523,3 +1556,42 @@ cvs -z3 -d:pserver:anonymous@cvs.alioth.debian.org:/cvsroot/pbuilder co pbuilder
     </sect1>
   </chapter>
 </book>
+
+<!--  LocalWords:  pbuilder xml Exp Junichi Uekawa chroot buildability sid HTTP
+ -->
+<!--  LocalWords:  buildable debootstrap pbuilderrc dist config dsc buildresult
+ -->
+<!--  LocalWords:  basetgz debian pdebuild debuild dpkg buildpackage cowdancer
+ -->
+<!--  LocalWords:  configfile sarge DEBOOTSTRAPOPTS cdebootstrap fakeroot linux
+ -->
+<!--  LocalWords:  BUILDUSERID BUILDUSERNAME fakerooting backporting postgresql
+ -->
+<!--  LocalWords:  gcc gcj javac pbuildd BTS GB installtest lintian linda pkg
+ -->
+<!--  LocalWords:  pentium EXTRAPACKAGES BUILDARCH athlon BUILDGCCVER uml gzip
+ -->
+<!--  LocalWords:  rootstrap slirp SKAS adduser tuntap eth netmask IP tmp tmpfs
+ -->
+<!--  LocalWords:  BUILDPLACE ip ssh sshd xbase passwd cp sed ifconfig README
+ -->
+<!--  LocalWords:  usr mkdir loginhooks sudo hookdir nocow BUILDRESULTUID UID
+ -->
+<!--  LocalWords:  TMPDIR chroots othermirror src bindmounts bindmount cd Sury
+ -->
+<!--  LocalWords:  Ondrej PS pbuild LOGNAME genchanges utmp uid ln fakechroot
+ -->
+<!--  LocalWords:  APTCACHEHARDLINK libc ldd ldconfig debconf FRONTEND readline
+ -->
+<!--  LocalWords:  whiptail nodev noexec nosuid gz chrootmemo debsign XXXXXXXX
+ -->
+<!--  LocalWords:  XXXX YYY amd debootstrapopts ccache DIR blog alioth IRC co
+ -->
+<!--  LocalWords:  CVS cvs ChangeLog changelog diff TODO todoo releaseX XXX LVM
+ -->
+<!--  LocalWords:  targz sbuild dchroot tgz chrooting symlink aptcache PDF Sep
+ -->
+<!--  LocalWords:  DocBook PSGML wysidocbookxml dbuild Wirzenius debbuild Troup
+ -->
+<!--  LocalWords:  perl Ronan Hodek buildd Yay cowloop
+ -->
diff --git a/debian/changelog b/debian/changelog
index 3937825..938ccea 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -8,9 +8,12 @@ pbuilder (0.153) UNRELEASED; urgency=low
     situation.
   * pbuilder-doc.xml: update documentation to add an example snippet for
     using locally built packages from pbuilder.
-    And other minor updates.
+    And other minor updates, including spellchecking.
+  * manpages: spellcheck.
+  * cowdancer support, pbuilder support cowbuilder.
+  * quiet down cowprotect message.
 
- -- Junichi Uekawa <dancer@debian.org>  Wed, 17 May 2006 11:46:36 +0900
+ -- Junichi Uekawa <dancer@debian.org>  Wed, 24 May 2006 09:12:43 +0900
 
 pbuilder (0.152) unstable; urgency=low
 
diff --git a/pbuilder b/pbuilder
index 28170b7..ed563dc 100755
--- a/pbuilder
+++ b/pbuilder
@@ -26,19 +26,19 @@ export PBCURRENTCOMMANDLINEOPERATION="$1"
 umask 0022
 
 case "$1" in
-    create)
+    --create|create)
 	shift;
 	/usr/lib/pbuilder/pbuilder-createbuildenv "$@"
 	;;
-    update)
+    --update|update)
 	shift ;
 	/usr/lib/pbuilder/pbuilder-updatebuildenv "$@"
 	;;
-    build)
+    --build|build)
 	shift ;
 	/usr/lib/pbuilder/pbuilder-buildpackage "$@"
 	;;
-    clean)
+    --clean|clean)
 	shift;
 	. /usr/lib/pbuilder/pbuilder-checkparams
 	if [ -n "$BASEBUILDPLACE" ]; then 
@@ -50,7 +50,7 @@ case "$1" in
 	    clean_subdirectories "$APTCACHE" || true
 	fi
 	;;
-    login)
+    --login|login)
 	shift 
 	. /usr/lib/pbuilder/pbuilder-checkparams
 	. /usr/lib/pbuilder/pbuilder-runhooks
@@ -88,7 +88,7 @@ File extracted to: $BUILDPLACE
 	    fi
 	fi
 	;;
-    execute)
+    --execute|execute)
 	# try to execute arbitrary program.
 	shift
 	. /usr/lib/pbuilder/pbuilder-checkparams
@@ -130,7 +130,7 @@ File extracted to: $BUILDPLACE
 	    fi
 	fi
 	;;
-    dumpconfig)
+    --dumpconfig|dumpconfig)
 	shift
 	. /usr/lib/pbuilder/pbuilder-checkparams
 	. /usr/lib/pbuilder/pbuilder-runhooks
@@ -145,7 +145,7 @@ File extracted to: $BUILDPLACE
 	env;
 	echo " -> end dump config"
 	;;
-    debuild)
+    --debuild|debuild)
 	shift
 	"$0" execute "$@" /usr/lib/pbuilder/pdebuild-internal
 	;;
diff --git a/pbuilder-buildpackage-funcs b/pbuilder-buildpackage-funcs
index 179ba67..3412bfe 100644
--- a/pbuilder-buildpackage-funcs
+++ b/pbuilder-buildpackage-funcs
@@ -70,7 +70,7 @@ function cowprotect () {
     # a hack for cowdancer, used when a file is edited in-place;
     # Copy the file to create a new i-node so that hardlinked original is intact
     for A in "$@"; do
-	if readlink -f "$A"; then
+	if readlink -f "$A" > /dev/null; then
 	    A=$(readlink -f "$A")
 	    mv "$A" "$A"~
 	    cp -a "$A"~ "$A"
diff --git a/pbuilder-modules b/pbuilder-modules
index 2f864cd..16fb4ce 100644
--- a/pbuilder-modules
+++ b/pbuilder-modules
@@ -27,10 +27,10 @@ pbuilder [operation] [pbuilder-options]
 pdebuild [pdebuild-options] -- [pbuilder-options]
 
 command lines:
-pbuilder create [--basetgz base.tgz-path] [--distribution potato|woody|sarge|etch|sid|experimental]
+pbuilder create [--basetgz base.tgz-path] [--distribution sarge|etch|sid|experimental]
   Creates a base.tgz
 
-pbuilder update [--basetgz base.tgz-path] [--distribution potato|woody|sarge|etch|sid|experimental]
+pbuilder update [--basetgz base.tgz-path] [--distribution sarge|etch|sid|experimental]
   Updates a base.tgz
 
 pbuilder build [--basetgz base.tgz-path] pbuilder_2.2.0-1.dsc
@@ -40,7 +40,7 @@ pbuilder clean
   Cleans the temporal build directory.
 
 pbuilder login
-pbuilder execute [command]
+pbuilder execute -- [command] [command-options]
   Logs in to the build environment and execute command.
 
 pbuilder dumpconfig
@@ -52,7 +52,7 @@ pbuilder-options:
  --mirror [mirror location]
  --othermirror [other mirror location in apt deb-line format, delimited with | signs]
  --http-proxy [proxy]
- --distribution [distribution(potato|woody|sarge|sid|etch|experimental)]
+ --distribution [distribution(sarge|sid|etch|experimental)]
  --buildresult [location-to-copy-build-result]
  --aptcache [location of retrieved package files]
  --removepackages [packages-to-remove on pbuilder create]
diff --git a/pbuilder-user-mode-linux.1 b/pbuilder-user-mode-linux.1
index 29c0d23..f414688 100644
--- a/pbuilder-user-mode-linux.1
+++ b/pbuilder-user-mode-linux.1
@@ -191,7 +191,7 @@ This option is only valid when distribution is being specified, for
 update and build targets.
 The format is something like:
 .I "http://http.us.debian.org/debian" 
-which should point to your favorite mirror.
+which should point to your favourite mirror.
 
 This option can optionally be omitted, and left blank,
 in which case, this part is skipped.
diff --git a/pbuilder.8 b/pbuilder.8
index 609dfb6..fae08c3 100644
--- a/pbuilder.8
+++ b/pbuilder.8
@@ -8,7 +8,7 @@ pbuilder \- personal package builder
 .PP
 .BI "pbuilder build [" "options" "] " ".dsc-file"
 .PP
-.BI "pbuilder execute [" "options" "] " "script"
+.BI "pbuilder execute [" "options" "] -- " "script [" "script options" "]"
 .PP
 .BI "pbuilder clean"
 .PP
@@ -146,7 +146,7 @@ This option is only valid when distribution is being specified, for
 update and build targets.
 The format is something like:
 .I "http://http.us.debian.org/debian" 
-which should point to your favorite mirror.
+which should point to your favourite mirror.
 
 This option can optionally be omitted, and left blank,
 in which case, this part is skipped.
@@ -193,7 +193,6 @@ should do.
 Specifies the distribution used. Currently the supported values are
 .B "sid"
 .B "sarge"
-.B "woody"
 .B "etch"
 and 
 .B "experimental".
diff --git a/pbuilderrc.5 b/pbuilderrc.5
index ee11d96..9307998 100644
--- a/pbuilderrc.5
+++ b/pbuilderrc.5
@@ -1,4 +1,4 @@
-.TH "pbuilderrc" 5 "2006 May 15" "Debian" "pbuilder"
+.TH "pbuilderrc" 5 "2006 May 24" "Debian" "pbuilder"
 .SH NAME
 pbuilderrc \- configuration files for personal package builder
 .SH DESCRIPTION
@@ -325,6 +325,14 @@ and
 .BI "PKGNAME_LOGFILE_EXTENTION=" ".build"
 The extension of filename used in pkgname-logfile option.
 
+.TP
+.BI "PDEBUILD_PBUILDER=" "pbuilder"
+Specify what pbuilder implementation to use for pdebuild.
+The currently possible values are
+.B "pbuilder"
+and 
+.B "cowbuilder"
+
 .SH "AUTHOR"
 Initial coding, and main maintenance is done by 
 Junichi Uekawa <dancer@debian.org>.
@@ -338,3 +346,6 @@ The homepage is available at
 .SH "SEE ALSO"
 .RI "pbuilder (" 8 "), "
 .RI "pdebuild (" 1 ")"
+
+\"  LocalWords:  interactiveness noninteractive pdebuild pbuilder buildd
+\"  LocalWords:  pbuilderrc
diff --git a/pdebuild b/pdebuild
index ad38cfa..1756369 100644
--- a/pdebuild
+++ b/pdebuild
@@ -37,13 +37,13 @@ export BUILDRESULTUID=$(id -u)
 export BUILDRESULTGID=$(id -g)
 
 if [ "${USE_PDEBUILD_INTERNAL}" = 'yes' ]; then
-    ${PBUILDERROOTCMD} pbuilder execute "$@" ${EXTRA_CONFIGFILE[@]/#/--configfile } --bindmounts $(readlink -f ..) /usr/lib/pbuilder/pdebuild-internal ${PWD} --debbuildopts "${DEBBUILDOPTS}" --uid "${BUILDRESULTUID}" --gid "${BUILDRESULTGID}"
+    ${PBUILDERROOTCMD} ${PDEBUILD_PBUILDER} --execute "$@" ${EXTRA_CONFIGFILE[@]/#/--configfile } --bindmounts $(readlink -f ..) -- /usr/lib/pbuilder/pdebuild-internal ${PWD} --debbuildopts "${DEBBUILDOPTS}" --uid "${BUILDRESULTUID}" --gid "${BUILDRESULTGID}"
 else
     if ! dpkg-checkbuilddeps -B ; then
 	echo "W: Unmet build-dependency in source"
     fi
     echo "dpkg-buildpackage -S -us -uc -r${BUILDSOURCEROOTCMD} $DEBBUILDOPTS" | perl -pe 's/(^|\s)-[bB](\s|$)/$1$2/g' | /bin/bash
-    ${PBUILDERROOTCMD} pbuilder build "$@" ${EXTRA_CONFIGFILE[@]/#/--configfile } --buildresult "${BUILDRESULT}"  --debbuildopts "${DEBBUILDOPTS}" ../"${PKG_SOURCENAME}_${PKG_VERSION}".dsc
+    ${PBUILDERROOTCMD} ${PDEBUILD_PBUILDER} --build "$@" ${EXTRA_CONFIGFILE[@]/#/--configfile } --buildresult "${BUILDRESULT}"  --debbuildopts "${DEBBUILDOPTS}" ../"${PKG_SOURCENAME}_${PKG_VERSION}".dsc
 fi
 
 # do signing with optional key specifier
diff --git a/pdebuild-checkparams b/pdebuild-checkparams
index 0b60624..6b09d09 100644
--- a/pdebuild-checkparams
+++ b/pdebuild-checkparams
@@ -83,6 +83,11 @@ while [ -n "$1" ]; do
 	    exec 2>&1
 	    shift; shift;
 	    ;;
+	--pbuilder)
+	    echo "  -> using $2 as pbuilder"
+	    PDEBUILD_PBUILDER="$2"
+	    shift; shift;
+	    ;;
 	--help)
 	    showhelp
 	    ;;
@@ -110,3 +115,7 @@ fi
 if [ -z "${CHROOTEXEC}" ]; then
     CHROOTEXEC="chroot $BUILDPLACE "
 fi
+
+if [ -z "${PDEBUILD_PBUILDER}" ]; then
+    PDEBUILD_PBUILDER="pbuilder"
+fi
diff --git a/pdebuild-user-mode-linux.1 b/pdebuild-user-mode-linux.1
index 83bc92b..adfa43f 100644
--- a/pdebuild-user-mode-linux.1
+++ b/pdebuild-user-mode-linux.1
@@ -1,4 +1,4 @@
-.TH "pdebuild\-user\-mode\-linux" 1 "2005 Jul 10" "Debian" "pbuilder"
+.TH "pdebuild\-user\-mode\-linux" 1 "2006 May 24" "Debian" "pbuilder"
 .SH NAME
 pdebuild\-user\-mode\-linux \- pbuilder\-user\-mode\-linux way of doing debuild
 .SH SYNOPSIS
@@ -7,7 +7,7 @@ pdebuild\-user\-mode\-linux \- pbuilder\-user\-mode\-linux way of doing debuild
 .SH "DESCRIPTION"
 A convenience program for 
 .B pbuilder\-user\-mode\-linux
-which invokes pbuilder after obtaining appropriate root privilate 
+which invokes pbuilder after obtaining appropriate root privilege 
 in a Debian source directory.
 One must be inside the source tree containing the
 .B debian
@@ -106,3 +106,5 @@ The homepage is available at
 .RI "pbuilder\-user\-mode\-linux (" 1 "), "
 .RI "pbuilderrc (" 5 "), "
 .RI "pbuilder\-uml.conf (" 5 ") "
+
+\"  LocalWords:  pdebuild linux pbuilder fakeroot
diff --git a/pdebuild.1 b/pdebuild.1
index 2dcb450..07642e3 100644
--- a/pdebuild.1
+++ b/pdebuild.1
@@ -1,4 +1,4 @@
-.TH "pdebuild" 1 "2006 May 15" "Debian" "pbuilder"
+.TH "pdebuild" 1 "2006 May 24" "Debian" "pbuilder"
 .SH NAME
 pdebuild \- pbuilder way of doing debuild
 .SH SYNOPSIS
@@ -7,7 +7,7 @@ pdebuild \- pbuilder way of doing debuild
 .SH DESCRIPTION
 A convenience program for 
 .B pbuilder
-which invokes pbuilder after obtaining appropriate root privilate 
+which invokes pbuilder after obtaining appropriate root privilege 
 in a Debian source directory.
 One must be inside the source tree containing the
 .B debian
@@ -43,7 +43,7 @@ Invoke debsign at the end of pdebuild process.
 .BI "\-\-debsign\-k [" "key\-id" "]"
 Pass 
 .B \-k
-option to debsign to specify which keyid to sign.
+option to debsign to specify which key-id to sign.
 
 .TP
 .BI "\-\-buildresult [" "Directory for build results" "]"
@@ -89,6 +89,10 @@ instead of messages coming to the
 standard output.
 
 .TP
+.BI "\-\-pbuilder [" "pbuilder" "]"
+Specifies which command to invoke as pbuilder.
+
+.TP
 .BI "\-\-help"
 
 Show a brief help message.
@@ -139,3 +143,5 @@ The homepage is available at
 .SH "SEE ALSO"
 .RI "pbuilder (" 8 "), "
 .RI "pbuilderrc (" 5 ") "
+
+\"  LocalWords:  pdebuild pbuilder debuild debian debsign pdebuid