/[ddp]/manuals/trunk/maint-guide/maint-guide.en.dbk

Diff of /manuals/trunk/maint-guide/maint-guide.en.dbk

Parent Directory | Revision Log | View Patch Patch

-revision 8709 by osamu,
Fri Apr 22 14:43:26 2011 UTC
+revision 9043 by osamu,
Sat Jan 14 15:28:46 2012 UTC
 Line 105 
 takes many hours.  Make no mistake, for
  need to be both technically competent and diligent.
  </para>
  <para>
- This document will explain every little (at first maybe irrelevant) step, and
- help you create that first package, and to gain some experience in building
- the next releases of that and maybe other packages later on.
- </para>
- <para>
  If you need some help on packaging, please read <xref linkend="helpme"/>.
  </para>
  <para>
-Line 120 
 The translations may be available in pac
+Line 115 
 The translations may be available in pac
  <systemitem role="package">maint-guide-es</systemitem>.
  Please note that this documentation may be slightly outdated.
  </para>
- <section id="socialdynamism"><title>Social dynamics of Debian</title>
+ <para>
+ Since this is a tutorial, I choose to explain each detailed step for some
+ important topics.  Some of them may look irrelevant to you.  Please be patient.
+ I have also intentionally skipped some corner cases and provided only pointers
+ to keep this document simple.
+ </para>
+ <section id="socialdynamics"><title>Social dynamics of Debian</title>
  <para>
  Here are some observations of Debian's social dynamics, presented in the hope
  that it will prepare you for interactions with Debian.
-Line 219 
 please refer to the following to learn h
+Line 220 
 please refer to the following to learn h
  <itemizedlist>
  <listitem><para><ulink url="&logiciellibre;">Debian: 17 years of Free Software, "do-ocracy", and democracy</ulink> (Introductory slides) </para> </listitem>
  <listitem><para><ulink url="&debianorghelp;">How can you help Debian?</ulink> (official) </para> </listitem>
- <listitem><para><ulink url="&debianfaqhelp;">The Debian GNU/Linux FAQ, Chapter 13 - 'Contributing to the Debian Project'</ulink> (semi-official) </para> </listitem>
+ <listitem><para><ulink url="&debianfaqhelp;">The Debian GNU/Linux FAQ, Chapter 13 - "Contributing to the Debian Project"</ulink> (semi-official) </para> </listitem>
  <listitem><para><ulink url="&debianwikihelp;">Debian Wiki, HelpDebian</ulink> (supplemental) </para> </listitem>
  <listitem><para><ulink url="&nm-do;">Debian New Maintainer site</ulink> (official) </para> </listitem>
  <listitem><para><ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> (supplemental) </para> </listitem>
  </itemizedlist>
  </section>
- <section id="needprogs"><title>Programs you need for development</title>
+ <section id="needprogs"><title>Programs needed for development</title>
  <para>
  Before you start anything, you should make sure that you have properly
  installed some additional packages needed for development.  Note that the list
-Line 420 
 those made for X11, also use these progr
+Line 421 
 those made for X11, also use these progr
  </itemizedlist>
  <para>
  The short descriptions that are given above only serve to introduce you to what
- each package does.  Before continuing please thoroughly read the documentation
+ each package does.  Before continuing please read the documentation
- of each program, at least, for the standard usage.  It may seem like heavy
+ of each relevant program including ones installed through the package dependency such as
+ <command>make</command>, at least, for the standard usage.  It may seem like heavy
  going now, but later on you'll be <emphasis>very</emphasis> glad you read it.
- </para>
- <para>
  If you have specific questions later, I would suggest re-reading the documents
- mentioned above.  Since this is a tutorial, I have intentionally skipped
+ mentioned above.
- details and provided only pointers to keep it simple.
  </para>
  </section>
  <section id="needdocs"><title>Documentation needed for development</title>
-Line 438 
 you should read along with this document
+Line 437 
 you should read along with this document
  <itemizedlist>
  <listitem>
  <para>
- <ulink url="&autotools-tutorial;">Autotools
- Tutorial</ulink> provides a very good tutorial for <ulink url="&gnu-build-system;">the GNU Build System known
- as the GNU Autotools</ulink> whose most important components are Autoconf,
- Automake, Libtool, and gettext.
- </para>
- </listitem>
- <listitem>
- <para>
  <systemitem role="package">debian-policy</systemitem> - the <ulink url="&debian-policy;">Debian Policy
  Manual</ulink> includes explanations of the structure and contents of the
  Debian archive, several OS design issues, the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink>
  (FHS, which says where each file and directory should be), etc.  For you, the most
  important thing is that it describes requirements that each package must
- satisfy to be included in the distribution (see the local copies of
+ satisfy to be included in the distribution. (See the local copies of
- <ulink url="&policy-pdf;">policy.pdf</ulink> and <ulink url="&fhs-pdf;">fhs-2.3.pdf</ulink>).
+ <ulink url="&policy-pdf;">policy.pdf</ulink> and <ulink url="&fhs-pdf;">fhs-2.3.pdf</ulink>.)
  </para>
  </listitem>
  <listitem>
-Line 466 
 when and where to upload etc.  (See the
+Line 457 
 when and where to upload etc.  (See the
  <ulink url="&developers-refpdf;">developers-reference.pdf</ulink>.)
  </para>
  </listitem>
+ </itemizedlist>
+ <para>
+ The following is the <emphasis>important</emphasis> documentation which
+ you should read along with this document:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="&autotools-tutorial;">Autotools
+ Tutorial</ulink> provides a very good tutorial for <ulink url="&gnu-build-system;">the GNU Build System known
+ as the GNU Autotools</ulink> whose most important components are Autoconf,
+ Automake, Libtool, and gettext.
+ </para>
+ </listitem>
  <listitem>
  <para>
  <systemitem role="package">gnu-standards</systemitem> - this package contains
-Line 486 
 are correct.  Please file a bug report o
+Line 491 
 are correct.  Please file a bug report o
  <systemitem role="package">maint-guide</systemitem> package using
  <command>reportbug</command>.
  </para>
+ <para>
+ The following is an alternative tutorial documentation which you may
+ read along with this document:
+ </para>
+ <itemizedlist>
+ <listitem><para><ulink url="&debpkg-tutorial0;">Debian Packaging Tutorial</ulink></para></listitem>
+ <listitem><para><ulink url="&debpkg-tutorial1;">Practical session 1: Modifying the grep package</ulink></para></listitem>
+ <listitem><para><ulink url="&debpkg-tutorial2;">Practical session 2: Packaging GNUjump</ulink></para></listitem>
+ <listitem><para><ulink url="&debpkg-tutorial3;">Practical session 3: Packaging a Java library</ulink></para></listitem>
+ </itemizedlist>
  </section>
  <section id="helpme"><title>Where to ask for help</title>
  <para>
-Line 558 
 is time for you to dig into the
+Line 573 
 is time for you to dig into the
  <ulink url="&bts;">Debian Bug Tracking System</ulink>
  and read the documentation there, to be able to
  deal with the reports efficiently.  I highly recommend reading the
- <ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8:
+ <ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8.
  "Handling bugs"</ulink>.
  </para>
  <para>
-Line 580 
 documentation</emphasis> for details).
+Line 595 
 documentation</emphasis> for details).
  Let's start by creating a package of your own (or, even better,
  adopting an existing one).
  </para>
- <section id="workflow"><title>Work flow of the Debian package building</title>
+ <section id="workflow"><title>Debian package building workflow</title>
  <para>
- If you are making a Debian package with an upstream program,
+ If you are making a Debian package with an upstream program, the
- typical work flow of the Debian package building involves generating several
+ typical workflow of Debian package building involves generating several
- specifically named files for each step as the following.
+ specifically named files for each step as follows.
  </para>
  <itemizedlist>
  <listitem>
- <para>We obtain an upstream program file usually in a compressed tar format.</para>
+ <para>Get a copy of the upstream software, usually in a compressed tar format.</para>
    <itemizedlist>
-   <listitem><literal><replaceable>programname</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>
+   <listitem><literal><replaceable>package</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>
    </itemizedlist>
  </listitem>
  <listitem>
  <para>
- We create a non-native Debian source package in the "3.0 (quilt)" format, which refers to the set of input files for
+ Add Debian-specific packaging modifications to the upstream program under the
- the Debian package building, by adding Debian package modifications to the upstream program under the <filename>debian</filename> directory.
+ <filename>debian</filename> directory, and create a non-native source package
+ (that is, the set of input files used for Debian package building) in
+ <literal>3.0 (quilt)</literal> format.
  </para>
    <itemizedlist>
-   <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>.orig.tar.gz</literal></listitem>
+   <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.orig.tar.gz</literal></listitem>
-   <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.debian.tar.gz</literal>
+   <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.debian.tar.gz</literal>
-     <footnote><para>For the older non-native Debian source package in the "1.0" format,
+     <footnote><para>For the older style of non-native Debian source packages in <literal>1.0</literal> format,
-     <literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.diff.gz</literal>
+     <literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.diff.gz</literal>
      is used instead. </para></footnote></listitem>
-   <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.dsc</literal></listitem>
+   <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.dsc</literal></listitem>
    </itemizedlist>
  </listitem>
  <listitem>
  <para>
- We build Debian binary packages, which are ordinary installable package files in <literal>.deb</literal> format (or <literal>.udeb</literal> format, used by the Debian Installer), from the Debian source package.
+ Build Debian binary packages, which are ordinary installable package files in <literal>.deb</literal> format (or <literal>.udeb</literal> format, used by the Debian Installer) from the Debian source package.
  </para>
    <itemizedlist>
-   <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
+   <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
    </itemizedlist>
  </listitem>
  </itemizedlist>
  <para>
- If you are making a Debian specific package without an upstream program instead,
+ Please note that the character separating
- typical work flow of the Debian package building is simpler.
+ <literal><replaceable>package</replaceable></literal> and
+ <literal><replaceable>version</replaceable></literal> was changed from
+ <literal>-</literal> (hyphen) in the tarball name to
+ <literal>_</literal> (underscore) in the Debian package filenames.
+ </para>
+ <para>
+ In the file names above, replace
+ the <literal><replaceable>package</replaceable></literal> part with the <emphasis role="strong">package name</emphasis>,
+ the <literal><replaceable>version</replaceable></literal> part with the <emphasis role="strong">upstream version</emphasis>,
+ the <literal><replaceable>revision</replaceable></literal> part with the <emphasis role="strong">Debian revision</emphasis>,
+ and the <literal><replaceable>arch</replaceable></literal> part with the <emphasis role="strong">package architecture</emphasis>,
+ as defined in the Debian Policy Manual.
+ <footnote> <para> See
+ <ulink url="&policy-source;">5.6.1 Source</ulink>,
+ <ulink url="&policy-package;">5.6.7 Package</ulink>, and
+ <ulink url="&policy-version;">5.6.12 Version</ulink>.
+ The <emphasis role="strong">package architecture</emphasis> follows the
+ Debian Policy Manual: <ulink url="&policy-architecture;">5.6.8 Architecture</ulink>
+ and is automatically assigned by the package build process.</para></footnote>
+ </para>
+ <para>
+ If instead you are making a Debian-specific package with no upstream, the
+ typical workflow of Debian package building is simpler.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- We create a native Debian source package in the "3.0 (native)" format using a compressed tar format in which required files under the <filename>debian</filename> directory are also included.
+ Create a native Debian source package in the <literal>3.0 (native)</literal>
+ format using a single compressed tar file in which all files are included.
  </para>
    <itemizedlist>
-   <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>.tar.gz</literal></listitem>
+   <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.tar.gz</literal></listitem>
-   <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>.dsc</literal></listitem>
+   <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.dsc</literal></listitem>
    </itemizedlist>
  </listitem>
  <listitem>
  <para>
- We build Debian binary packages from the native Debian source package.
+ Build Debian binary packages from the native Debian source package.
  </para>
    <itemizedlist>
-   <listitem><literal><replaceable>programname</replaceable>_<replaceable>version</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
+   <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
    </itemizedlist>
  </listitem>
  </itemizedlist>
  <para>
- Here,
+ Each step of this outline is explained with detailed examples in later sections.
- <literal><replaceable>programname</replaceable></literal> part of the file name is substituted by the
- <emphasis role="strong">package name</emphasis>,
- <literal><replaceable>version</replaceable></literal> part of it is substituted by the
- <emphasis role="strong">upstream version</emphasis>,
- <literal><replaceable>revision</replaceable></literal> part of it is substituted by the
- <emphasis role="strong">Debian revision</emphasis>,
- <literal><replaceable>arch</replaceable></literal> part of it is substituted by the
- <emphasis role="strong">package architecture</emphasis>.
- <footnote><para>
- The <emphasis role="strong">package name</emphasis>, <emphasis
- role="strong">upstream version</emphasis>, and <emphasis role="strong">Debian
- revision</emphasis> must be adjusted to comply with the Debian Policy Manual:
- <ulink url="&policy-source;">5.6.1 Source</ulink>,
- <ulink url="&policy-package;">5.6.7 Package</ulink>, and
- <ulink url="&policy-version;">5.6.12 Version</ulink>.
- The <emphasis role="strong">package architecture</emphasis> follows the
- Debian Policy Manual: <ulink url="&policy-architecture;">5.6.8 Architecture</ulink>
- and is automatically assigned by the package build process.</para></footnote>
- </para>
- <para>
- You should chose the <emphasis role="strong">package name</emphasis>
- which consists only of lower case letters (<literal>a-z</literal>), digits
- (<literal>0-9</literal>), plus (<literal>+</literal>) and minus
- (<literal>-</literal>) signs, and periods (<literal>.</literal>). They must be
- at least two characters long and must start with an alphanumeric character.
- </para>
- <para>
- You should use the <emphasis role="strong">upstream version</emphasis> and the
- <emphasis role="strong">Debian revision</emphasis> which consists only of
- alphanumerics (<literal>a-zA-Z0-9</literal>), plus (<literal>+</literal>),
- tilde (<literal>~</literal>), and periods (<literal>.</literal>). They must
- start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter
- rule should help you avoid confusing file names.</para></footnote>
- </para>
- <para>
- In the following, each step of this is explained with detailed examples.
  </para>
  </section>
  <section id="choose"><title>Choose your program</title>
-Line 813 
 For the <literal>non-free</literal> sect
+Line 817 
 For the <literal>non-free</literal> sect
  with the DFSG but it <emphasis role="strong">must be distributable</emphasis>.
  </para>
  </listitem>
- </itemizedlist>
+ <listitem>
  <para>
- If you are unsure about where it should go, post the license text on <ulink url="&debian-legal-ldo;">debian-legal@lists.debian.org</ulink>
+ If you are unsure about where it should go, post the license text on
+ <ulink url="&debian-legal-ldo;">debian-legal@lists.debian.org</ulink>
  and ask for advice.
  </para>
  </listitem>
+ </itemizedlist>
+ </listitem>
  <listitem>
  <para>
- The program certainly should <emphasis role="strong">not</emphasis> run setuid
+ The program should <emphasis role="strong">not</emphasis> introduce security
- root, or even better, it shouldn't need to be setuid or setgid to anything.
+ and maintenance concerns to the Debian system.
  </para>
- </listitem>
+ <itemizedlist>
  <listitem>
  <para>
- The program should not be a daemon, or go in an
+ The program should be well documented and its code needs to be understandable
- <filename>*/sbin</filename> directory, or open a port as root.
+ (i.e.  not obfuscated).
  </para>
  </listitem>
  <listitem>
  <para>
- The program should be in binary executable form; libraries are harder to handle.
+ You should contact the program's author(s) to check if they agree with packaging it
+ and are amicable to Debian.  It is important to be able to consult with the author(s)
+ in case of any problems with the program, so don't try to package
+ unmaintained software.
  </para>
  </listitem>
  <listitem>
  <para>
- The program should be well documented and its code needs to be understandable
+ The program certainly should <emphasis role="strong">not</emphasis> run setuid
- (i.e.  not obfuscated).
+ root, or even better, it shouldn't need to be setuid or setgid to anything.
  </para>
  </listitem>
  <listitem>
  <para>
- You should contact the program's author(s) to check if they agree with packaging it
+ The program should not be a daemon, or go in an
- and are amicable to Debian.  It is important to be able to consult with the author(s)
+ <filename>*/sbin</filename> directory, or open a port as root.
- in case of any problems with the program, so don't try to package
- unmaintained software.
  </para>
  </listitem>
  </itemizedlist>
+ </listitem>
+ </itemizedlist>
  <para>
- Of course, these are just safety measures, and intended to save you from
+ Of course, the last one is just a safety measures, and intended to save you from
  enraging users if you do something wrong in some setuid daemon...  When you gain
  more experience in packaging, you'll be able to package such software.
  </para>
+ <para>
+ As a new maintainer, you are encouraged to get some experience in packaging
+ with easier packages and discouraged from creating complicated packages.
+ </para>
+ <itemizedlist>
+ <listitem><para>Simple packages</para>
+ <itemizedlist>
+   <listitem><para>single binary package, arch = all (collection of data such as wallpaper graphics)</para></listitem>
+   <listitem><para>single binary package, arch = all (executables written in an interpreted language such as POSIX shell)</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>Intermediate complexity packages</para>
+ <itemizedlist>
+   <listitem><para>single binary package, arch = any (ELF binary executables compiled from languages such as C and C++)</para></listitem>
+   <listitem><para>multiple binary packages, arch = any + all (packages for ELF binary executables + documentation)</para></listitem>
+   <listitem><para>upstream source in a format other than <filename>tar.gz</filename> or <filename>tar.bz2</filename></para></listitem>
+   <listitem><para>upstream source containing undistributable contents</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>High complexity packages</para>
+ <itemizedlist>
+   <listitem><para>interpreter module package used by other packages</para></listitem>
+   <listitem><para>generic ELF library package used by other packages</para></listitem>
+   <listitem><para>multiple binary packages including an ELF library package</para></listitem>
+   <listitem><para>source package with multiple upstream sources</para></listitem>
+   <listitem><para>kernel module packages</para></listitem>
+   <listitem><para>kernel patch packages</para></listitem>
+   <listitem><para>any package with non-trivial maintainer scripts</para></listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Packaging high complexity packages is not too hard, but it requires a bit more
+ knowledge. You should seek specific guidance for every complex feature. For
+ example, some languages have their own sub-policy documents:
+ </para>
+ <itemizedlist>
+ <listitem><para><ulink url="&policy-perl;">Perl policy</ulink></para></listitem>
+ <listitem><para><ulink url="&policy-python;">Python policy</ulink></para></listitem>
+ <listitem><para><ulink url="&policy-java;">Java policy</ulink></para></listitem>
+ </itemizedlist>
+ <para>
+ There is another old Latin saying: <emphasis>fabricando fit faber</emphasis>
+ (practice makes perfect).  It is <emphasis>highly</emphasis> recommended to
+ practice and experiment with all the steps of Debian packaging with simple packages
+ while reading this tutorial.  A trivial upstream tarball
+ <filename>hello-sh-1.0.tar.gz</filename> created as followings may offer
+ a good starting point.<footnote><para>Do not worry about the missing
+ <filename>Makefile</filename>.  You can install the <command>hello</command>
+ command by simply using <command>debhelper</command> as in
+ <xref linkend="install"/>, or by modifying the upstream source to add a new
+ <filename>Makefile</filename> with the <literal>install</literal> target as in
+ <xref linkend="modify"/>.</para></footnote>
+ </para>
+ <screen>
+ $ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
+ $ cat &gt; hello &lt;&lt;EOF
+ #!/bin/sh
+ # (C) 2011 Foo Bar, GPL2+
+ echo "Hello!"
+ EOF
+ $ chmod 755 hello
+ $ cd ..
+ $ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0
+ </screen>
  </section>
  <section id="getit"><title>Get the program, and try it out</title>
  <para>
-Line 867 
 author's homepage.  Sources for free Uni
+Line 942 
 author's homepage.  Sources for free Uni
  <command>tar</command>+<command>bzip2</command> format with the extension
  <filename>.tar.bz2</filename>, or
  <command>tar</command>+<command>xz</command> format with the extension
- <filename>.tar.zx</filename>.  These usually contain a directory called
+ <filename>.tar.xz</filename>.  These usually contain a directory called
- <filename><replaceable>programname</replaceable>-<replaceable>version</replaceable></filename>
+ <filename><replaceable>package</replaceable>-<replaceable>version</replaceable></filename>
  with all the sources inside.
  </para>
  <para>
-Line 887 
 enough.  </para> </footnote>), you shoul
+Line 962 
 enough.  </para> </footnote>), you shoul
  appropriate tools and repack it.
  </para>
  <para>
+ If your program's source comes with some contents which do not comply with
+ DFSG, you should also unpack it to remove such contents and repack it with a
+ modified upstream version containing <literal>dfsg</literal>.
+ </para>
+ <para>
  As an example, I'll use a program called <command>gentoo</command>, a GTK+
  file manager.
  <footnote><para> This program is already packaged. The
-Line 903 
 case).  Place the downloaded archive in
+Line 983 
 case).  Place the downloaded archive in
  xzf gentoo-0.9.12.tar.gz</literal>).  Make sure there are no warning
  messages, even <emphasis>irrelevant</emphasis> ones, because other
  people's unpacking tools may or may not ignore these anomalies, so they
- may have problems unpacking them.  Your shell commandline may look
+ may have problems unpacking them.  Your shell command line may look
  something like this:
  </para>
  <screen>
-Line 925 
 install to the <filename>/usr/local/bin<
+Line 1005 
 install to the <filename>/usr/local/bin<
  that, but more on that later in <xref linkend="destdir"/>).
  </para>
  <para>
- Simple programs come with a <filename>Makefile</filename> and can
+ You should start packaging with a completely clean (pristine) source directory,
+ or simply with freshly unpacked sources.
+ </para>
+ </section>
+ <section id="simplemake"><title>Simple build systems</title>
+ <para>
+ Simple programs usually come with a <filename>Makefile</filename> and can
  be compiled just by invoking <literal>make</literal>.<footnote><para>
  Many modern programs come with a script <filename>configure</filename> which
  when executed creates a <filename>Makefile</filename> customized for
-Line 947 
 all the installed files.
+Line 1033 
 all the installed files.
  </section>
  <section id="portable"><title>Popular portable build systems</title>
  <para>
- A lot of free software is written in the <ulink url="&c-program;">C</ulink> and
+ A lot of free software programs are written in the <ulink url="&c-program;">C</ulink> and
- <ulink url="&cxx;">C++</ulink> languages.  Many of
+ <ulink url="&cxx;">C++</ulink> languages.  Many of these use Autotools or
- these use Autotools or CMake to make them portable across different platforms.
+ CMake to make them portable across different platforms.  These build tools need
- These tools are used to generate the <filename>Makefile</filename> and other
+ to be used to generate the <filename>Makefile</filename> and other
- required source files.  Then, such programs are built using the usual
+ required source files first.  Then, such programs are built using the usual
  <literal>make; make install</literal>.
  </para>
  <para>
-Line 962 
 system comprising <ulink url="&autoconf;
+Line 1048 
 system comprising <ulink url="&autoconf;
  <ulink url="&gettext;">gettext</ulink>.  You can recognize
  such sources by the <filename>configure.ac</filename>,
  <filename>Makefile.am</filename>, and <filename>Makefile.in</filename> files.
- <footnote><para> See the <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink>
+ <footnote><para>Autotools is too big to deal in this small tutorial. This
- and <ulink url="&autotools-readme;"/>.  </para> </footnote>
+ section is meant to provide keywords and references only.  Please make sure to read the
+ <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink> and
+ <ulink url="&autotools-readme;"/>, if you need to use it.</para></footnote>
  </para>
  <para>
  The first step of the Autotools workflow is usually that upstream runs
-Line 989 
 files requires some knowledge of <comman
+Line 1077 
 files requires some knowledge of <comman
  <para>
  The second step of the Autotools workflow is usually that the user obtains this
  distributed source and runs <literal>./configure &amp;&amp; make</literal> in
- the source directory to compile the program into a
+ the source directory to compile the program into an executable command
  <command><replaceable>binary</replaceable></command>.
  </para>
  <screen>
-Line 1003 
 config.h.in -----+                +-&gt;
+Line 1091 
 config.h.in -----+                +-&gt;
  <para>
  You can change many things in the <filename>Makefile</filename>; for
  instance you can change the default location for file installation
- using the option <command>./configure --prefix=/usr</command>.
+ using the option <literal>./configure --prefix=/usr</literal>.
  </para>
  <para>
  Although it is not required, updating the <filename>configure</filename> and
-Line 1021 
 build system.  You can recognize such so
+Line 1109 
 build system.  You can recognize such so
  </section>
  <section id="namever"><title>Package name and version</title>
  <para>
- You should start packaging with a completely clean (pristine) source directory,
+ If the upstream source comes as <filename>gentoo-0.9.12.tar.gz</filename>, you can
- or simply with freshly unpacked sources.
+ take <literal>gentoo</literal> as the (source) <emphasis role="strong">package name</emphasis>
+ and <literal>0.9.12</literal> as the <emphasis role="strong">upstream version</emphasis>.
+ These are used in the <filename>debian/changelog</filename> file described later in
+ <xref linkend="changelog"/>, too.
+ </para>
+ <para>
+ Although this simple approach works most of the times, you may need to adjust
+ <emphasis role="strong">package name</emphasis> and
+ <emphasis role="strong">upstream version</emphasis> by renaming the upstream
+ source to follow Debian Policy and existing convention.
+ </para>
+ <para>
+ You must choose the <emphasis role="strong">package name</emphasis>
+ to consist only of lower case letters (<literal>a-z</literal>), digits
+ (<literal>0-9</literal>), plus (<literal>+</literal>) and minus
+ (<literal>-</literal>) signs, and periods (<literal>.</literal>). It must be
+ at least two characters long, must start with an alphanumeric character, and
+ must not be the same as existing ones.
+ It is a good idea to keep its length within 30 characters.
+ <footnote><para>The default package name field length of <command>aptitude</command> is 30.  For more than 90% of packages, the package name is less than 24 characters.</para></footnote>
+ </para>
+ <!--
+ Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
+ === stat for package name string length ===
+1947 36.9%   mode
+1717 54.7%  50% median
+611 91.0%   90%
+89 99.0%    99%
+12 99.9%    99.9%
+1 100.0%
+ Previous 20 chars is becoming too short for 17% of packages
+ Default aptitude setting display up to 30 chars (98.3%).
+ -->
+ <para>
+ If upstream uses some generic term such as <literal>test-suite</literal> for
+ its name, it is a good idea to rename it to identify its contents explicitly and avoid namespace pollution.
+ <footnote><para>If you follow the
+ <ulink url="&devref-newpackage;">Debian Developer's Reference 5.1. "New packages"</ulink>,
+ the ITP process will usually catch this kind of issues.</para></footnote>
+ </para>
+ <para>
+ You should choose the <emphasis role="strong">upstream version</emphasis>
+ to consist only of
+ alphanumerics (<literal>0-9A-Za-z</literal>), plus (<literal>+</literal>),
+ tildes (<literal>~</literal>), and periods (<literal>.</literal>). It must
+ start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter
+ rule should help you avoid confusing file names.</para></footnote>
+ It is good idea to keep its length within 8 characters if possible.
+ <footnote><para>The default version field length of <command>aptitude</command> is 10.  The Debian revision with preceding hyphen usually consumes 2.  For more than 80% of packages, the upstream version is less than 8 characters and the Debian revision is less than 2 characters.  For more than 90% of packages, the upstream version is less than 10 characters and the Debian revision is less than 3 characters.</para></footnote>
  </para>
+ <!--
+ Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
+ === stat for upstream version string length ===
+9765 60.2%  50% median and mode
+3765 73.3%
+2789 82.9%
+1158 86.9%
+501 88.6%
+773 91.3%  90%
+55 99.1%   99%
+11 99.9%    99.9
+6 100.0%
+ === stat for debian revision string length ===
+22556 83.3%  50% median and mode
+1106 87.2%
+1312 91.7%   90%
+2127 99.1%   99%
+14 99.9%     99.9%
+ aptitude display 10 = 8char for up + 1char (for -) + 1char for deb
+chars as max for file name of binary debs (package+up+deb+arch+.deb)
+ -->
  <para>
- For the package to be built correctly, you must make the program's original
+ If upstream does not use a normal versioning scheme such as
- name lowercase (if it isn't already), and you should move the source directory
+ <literal>2.30.32</literal> but uses some kind of date such as
- to
+ <literal>11Apr29</literal>, a random codename string, or a VCS hash value as part
- <filename><replaceable>packagename</replaceable>-<replaceable>version</replaceable></filename>.
+ of the version, make sure to remove them from the
- </para>
+ <emphasis role="strong">upstream version</emphasis>.  Such information can be
- <para>
+ recorded in the <filename>debian/changelog</filename> file.  If you need to
- If the program name consists of more than one word, contract them to one word,
+ invent a version string, use the <literal>YYYYMMDD</literal> format such as
- or make an abbreviation.  For example, a package of the program "John's little
+ <literal>20110429</literal> as upstream version.  This ensures that
- editor for X" might be named <systemitem role="package">johnledx</systemitem>, or
+ <command>dpkg</command> interprets later versions correctly as upgrades.
- <systemitem role="package">jle4x</systemitem>, or whatever you decide, as long
+ If you need to ensure smooth transition to the normal version scheme such as
- as it's under some reasonable length limit, e.g. 20 characters.
+ <literal>0.1</literal> in future, use the <literal>0~YYMMDD</literal> format
- </para>
+ such as <literal>0~110429</literal> as upstream version, instead.
- <para>
+ </para>
- Also check for the exact version of the program (to be included in the package
+ <para>
- version).  If this piece of software is not numbered with versions like
+ Version strings <footnote><para>Version strings may be
- <literal>X.Y.Z</literal>, but with some kind of date, feel free to use that
+ <emphasis role="strong">upstream version</emphasis>
- date as the version number, as long as newer version numbers will look larger.
+ (<literal><replaceable>version</replaceable></literal>),
- While it is best to use the same version numbering as upstream, if it is
+ <emphasis role="strong">Debian revision</emphasis>
- in the format of <literal>09Oct23</literal> you may need to convert it to
+ (<literal><replaceable>revision</replaceable></literal>), or
- <literal>YYYYMMDD</literal> format, which would be <literal>20091023</literal>,
+ <emphasis role="strong">version</emphasis>
- to ensure that <command>dpkg</command> sees later versions as
+ (<literal><replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>).
- upgrades.<footnote><para> Version strings can be compared with <literal>dpkg
+ See <xref linkend="newrevision"/> for how the
- --compare-versions <replaceable>ver1</replaceable>
+ <emphasis role="strong">Debian revision</emphasis> is incremented.
- <replaceable>op</replaceable> <replaceable>ver2</replaceable></literal>.  See
+ </para></footnote>
- <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum>
+ can be compared using <citerefentry>
- </citerefentry>.  </para> </footnote>
+ <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as follows.
  </para>
+ <screen>
+  $ dpkg --compare-versions <replaceable>ver1</replaceable> <replaceable>op</replaceable> <replaceable>ver2</replaceable>
+ </screen>
  <para>
- Some programs won't be numbered at all, in which case you should contact the
+ The version comparison rule can be summarized as:
- upstream maintainer to see if they've got some other revision-tracking method.
+ </para>
+ <itemizedlist>
+ <listitem><para>Strings are compared from the head to the tail.</para></listitem>
+ <listitem><para>Letters are larger than digits.</para></listitem>
+ <listitem><para>Numbers are compared as integers.</para></listitem>
+ <listitem><para>Letters are compared in ASCII code order.</para></listitem>
+ <listitem><para>There are special rules for period
+ (<literal>.</literal>), plus (<literal>+</literal>), and tilde
+ (<literal>~</literal>) characters, as follows.</para>
+   <para>
+   <literal>0.0</literal> &lt;
+   <literal>0.5</literal> &lt;
+   <literal>0.10</literal> &lt;
+   <literal>0.99</literal> &lt;
+   <literal>1</literal> &lt;
+   <literal>1.0~rc1</literal> &lt;
+   <literal>1.0</literal> &lt;
+   <literal>1.0+b1</literal> &lt;
+   <literal>1.0+nmu1</literal> &lt;
+   <literal>1.1</literal> &lt;
+   <literal>2.0</literal>
+   </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ One tricky case occurs when upstream releases
+ <filename>gentoo-0.9.12-ReleaseCandidate-99.tar.gz</filename> as the
+ pre-release of <filename>gentoo-0.9.12.tar.gz</filename>.  You need to make
+ sure that the upgrade works properly by renaming the upstream source to
+ <filename>gentoo-0.9.12~rc99.tar.gz</filename>.
  </para>
  </section>
- <section id="dh-make"><title>Initial Debian package</title>
+ <section id="dh-make"><title>Setting up <command>dh_make</command></title>
  <para>
  Set up the shell environment variables <literal>$DEBEMAIL</literal> and
  <literal>$DEBFULLNAME</literal> so that various Debian maintenance
- tools recognize your email address and name to use for packages.<footnote><para> The
+ tools recognize your email address and name to use for packages. <footnote><para> The
  following text assumes you are using Bash as your login shell.  If you use
  some other login shell such as Z shell, use their corresponding
- configuration files instead of <filename>~/.bashrc</filename>. </para> </footnote>.
+ configuration files instead of <filename>~/.bashrc</filename>. </para> </footnote>
  </para>
  <screen>
  $ cat &gt;&gt;~/.bashrc &lt;&lt;EOF
- DEBEMAIL=your.email.address@example.org
+ DEBEMAIL="your.email.address@example.org"
- DEBFULLNAME=Firstname Lastname
+ DEBFULLNAME="Firstname Lastname"
  export DEBEMAIL DEBFULLNAME
  EOF
+ $ . ~/.bashrc
  </screen>
+ </section>
+ <section id="non-native-dh-make"><title>Initial non-native Debian package</title>
  <para>
- You can create an initial Debian package by issuing the
+ Normal Debian packages are non-native Debian packages made from upstream
- <command>dh_make</command> command as follows.
+ programs.  If you wish to create a non-native Debian package of an upstream
+ source <filename>gentoo-0.9.12.tar.gz</filename>, you can create an initial
+ non-native Debian package for it by issuing the <command>dh_make</command>
+ command as follows.
  </para>
  <screen>
- $ . ~/.bashrc
+ $ cd ~/gentoo
- $ cd ~/gentoo/gentoo-0.9.12
+ $ wget http://example.org/gentoo-0.9.12.tar.gz
+ $ tar -xvzf gentoo-0.9.12.tar.gz
+ $ cd gentoo-0.9.12
  $ dh_make -f ../gentoo-0.9.12.tar.gz
  </screen>
  <para>
-Line 1095 
 provided by the upstream for your Debian
+Line 1293 
 provided by the upstream for your Debian
  </para>
  <para>
  You should see some output asking you what sort of package you want
- to create.  Gentoo is a single binary package - it creates only one binary, and
+ to create.  Gentoo is a single binary package - it creates only one binary package, i.e,
- thus one <filename>.deb</filename> file - so we will select the first option
+ one <filename>.deb</filename> file - so we will select the first option
  (with the <literal>s</literal> key), check the information on the screen, and
  confirm by pressing <literal><replaceable>ENTER</replaceable></literal>.
- <footnote><para> There are several choices here: <literal>s</literal> for Single
+ <footnote><para> There are several choices here: <literal>s</literal> for
- binary, <literal>i</literal> for arch-Independent, <literal>m</literal> for
+ Single binary package, <literal>i</literal> for arch-Independent package, <literal>m</literal> for
- Multiple binary, <literal>l</literal> for Library, <literal>k</literal> for
+ Multiple binary packages, <literal>l</literal> for Library package, <literal>k</literal> for
- Kernel module, <literal>n</literal> for kernel patch, and <literal>b</literal>
+ Kernel module package, <literal>n</literal> for kernel patch package, and <literal>b</literal>
- for <systemitem role="package">cdbs</systemitem>.  This document focuses on the
+ for <systemitem role="package">cdbs</systemitem> package.  This document focuses on the
  use of the <command>dh</command> command (from the package
- <systemitem role="package">debhelper</systemitem>) to create a single-binary package,
+ <systemitem role="package">debhelper</systemitem>) to create a single binary package,
  but also touches on how to use it for arch-independent or
- multiple-binary packages.  The package
+ multiple binary packages.  The package
  <systemitem role="package">cdbs</systemitem> offers an alternative packaging script
  infrastructure to the <command>dh</command> command and is outside the scope of
  this document.  </para> </footnote>
-Line 1153 
 testing them (<xref linkend="checkit"/>)
+Line 1351 
 testing them (<xref linkend="checkit"/>)
  All the steps will be explained.
  </para>
  <para>
- Once again, as a new maintainer you are discouraged from creating complicated
- packages, e.g.:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- multiple binary packages;
- </para>
- </listitem>
- <listitem>
- <para>
- library packages;
- </para>
- </listitem>
- <listitem>
- <para>
- kernel module packages;
- </para>
- </listitem>
- <listitem>
- <para>
- kernel patch packages;
- </para>
- </listitem>
- <listitem>
- <para>
- packages with the source in a format other than <filename>tar.gz</filename> or
- <filename>tar.bz2</filename>; or
- </para>
- </listitem>
- <listitem>
- <para>
- packages where the source tarball contains undistributable contents.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Doing so is not too hard, but it requires a bit more knowledge, so we won't
- describe all of it here.
- </para>
- <para>
  If you accidentally erased some template files while working on them, you can
  recover them by running <command>dh_make</command> with the
  <literal>--addmissing</literal> option again in a Debian package source tree.
-Line 1203 
 Updating an existing package may get com
+Line 1360 
 Updating an existing package may get com
  techniques.  While learning the basics, please stick to creating a fresh
  package; further explanations are given in <xref linkend="update"/>.
  </para>
+ <para>
+ Please note that the source file does not need to contain any build system
+ discussed in <xref linkend="simplemake"/> and <xref linkend="portable"/>.  It
+ could be just a collection of graphical data etc.  Installation of files may be
+ carried out using only <systemitem role="package">debhelper</systemitem> configuration
+ files such as <filename>debian/install</filename> (see
+ <xref linkend="install"/>).
+ </para>
+ </section>
+ <section id="native-dh-make"><title>Initial native Debian package</title>
+ <para>
+ If a package contains source files you are only maintaining for Debian,
+ possibly only for local use, it may be simpler to create it as a Debian
+ native package. If you have source
+ files in <filename>~/mypackage-1.0</filename>, you can create an initial native
+ Debian package for it by issuing the <command>dh_make</command> command as
+ follows.
+ </para>
+ <screen>
+ $ cd ~/mypackage-1.0
+ $ dh_make --native
+ </screen>
+ <para>
+ Then the <filename>debian</filename> directory and its contents are created
+ just like <xref linkend="non-native-dh-make"/>.  This does not create a tarball
+ since this is a native Debian package.  But that is the only difference.
+ The rest of the packaging activities are practically the same.
+ </para>
  </section>
  </chapter>
  <chapter id="modify"><title>Modifying the source</title>
-Line 1220 
 useful to have a slightly customized def
+Line 1405 
 useful to have a slightly customized def
  line to <filename>~/.bashrc</filename>.
  </para>
  <screen>
- alias dquilt="quilt --quiltrc=~/.quiltrc-dpkg"
+ alias dquilt="quilt --quiltrc=${HOME}/.quiltrc-dpkg"
  </screen>
  <para>
  Then let's create <filename>~/.quiltrc-dpkg</filename> as follows.
-Line 1346 
 installation.  The packaging script will
+Line 1531 
 installation.  The packaging script will
  <literal>$(DESTDIR)</literal> to the temporary directory.
  </para>
  <para>
- For packages of the single-binary type, the temporary directory used
+ For a source package generating a single binary package, the temporary directory used
  by the <command>dh_auto_install</command> command will be set to
  <filename>debian/<replaceable>package</replaceable></filename>.
- <footnote><para> For packages of the multiple-binary type, the
+ <footnote><para> For a source package generating multiple binary packages, the
  <command>dh_auto_install</command> command uses <filename>debian/tmp</filename>
  as the temporary directory while the <command>dh_install</command> command with
  the help of
-Line 1388 
 from the <command>dh_auto_configure</com
+Line 1573 
 from the <command>dh_auto_configure</com
  options including <literal>--prefix=/usr</literal>.  </para> </footnote>:
  </para>
  <screen>
- # Where to put binary on 'make install'?
+ # Where to put executable commands on 'make install'?
  BIN     = /usr/local/bin
  # Where to put icons on 'make install'?
  ICONS   = /usr/local/share/gentoo
-Line 1399 
 As explained above, that directory hiera
+Line 1584 
 As explained above, that directory hiera
  Debian, so change those paths to:
  </para>
  <screen>
- # Where to put binary on 'make install'?
+ # Where to put executable commands on 'make install'?
  BIN     = $(DESTDIR)/usr/bin
  # Where to put icons on 'make install'?
  ICONS   = $(DESTDIR)/usr/share/gentoo
-Line 1411 
 documentation, etc. are specified in the
+Line 1596 
 documentation, etc. are specified in the
  your package.
  </para>
  <para>
- So, we should install the binary in <filename>/usr/bin</filename> instead of
+ So, we should install executable commands in <filename>/usr/bin</filename> instead of
  <filename>/usr/local/bin</filename>, the manual page in
  <filename>/usr/share/man/man1</filename> instead of
  <filename>/usr/local/man/man1</filename>, and so on.  Notice how there's no manual
-Line 1438 
 Edit those files and in those lines repl
+Line 1623 
 Edit those files and in those lines repl
  with <literal>usr/lib</literal>.  This can be done automatically as follows:
  </para>
  <screen>
- $ sed -i 's#usr/local/lib#usr/lib#g' \
+ $ sed -i -e 's#usr/local/lib#usr/lib#g' \
        $(find . -type f -name '*.[c|h]')
  </screen>
  <para>
- If you want to confirm each substituion instead, this can be done interactively as follows:
+ If you want to confirm each substitution instead, this can be done interactively as follows:
  </para>
  <screen>
  $ vim '+argdo %s#usr/local/lib#usr/lib#gce|update' +q \
-Line 1457 
 at the top of the <filename>Makefile</fi
+Line 1642 
 at the top of the <filename>Makefile</fi
  </para>
  <para>
  Originally, <systemitem role="package">gentoo</systemitem>'s
- install target said:
+ <literal>install</literal> target said:
  </para>
  <screen>
  install: gentoo-target
-Line 1527 
 Debian specific packaging modification:
+Line 1712 
 Debian specific packaging modification:
  </listitem>
  </orderedlist>
  <para>
- Whenever you make changes that are not specifically related to Debian package
+ Whenever you make changes that are not specific to the Debian package
  such as <filename>debian/patches/fix-gentoo-target.patch</filename>, be sure to
  send them to the upstream maintainer so they can be included in the next
- revision of the program and be useful to everyone else.  Also remember
+ version of the program and be useful to everyone else.  Also remember
  to avoid making your fixes specific to Debian or Linux - or even Unix!
  Make them portable.  This will make your fixes much easier to apply.
  </para>
-Line 1543 
 upstream.
+Line 1728 
 upstream.
  <para>
  There is one other common problem: libraries are often different from platform
  to platform.  For example, a <filename>Makefile</filename> can contain a
- reference to a library which doesn't exist on Debian systems.  In that case, we
+ reference to a library which doesn't exist on the Debian system.  In that case, we
  need to change it to a library which does exist in Debian, and serves the same
  purpose.
  </para>
  <para>
- So, if there is a line in your program's <filename>Makefile</filename> (or
+ Let's assume a line in your program's <filename>Makefile</filename> (or
- <filename>Makefile.in</filename>) that says something like this (and your
+ <filename>Makefile.in</filename>) as the following.
- program doesn't compile) <footnote><para> The author realizes that this is not
- the best example considering our <systemitem role="package">libncurses</systemitem> package now ships with a
- <filename>libcurses.so</filename> symlink, but he couldn't think of a better
- one.  Suggestions very welcome&nbsp;:-) </para> </footnote>:
  </para>
  <screen>
- LIBS = -lcurses -lsomething -lsomethingelse
+ LIBS = -lfoo -lbar
  </screen>
  <para>
- Let's fix this as <filename>debian/patches/ncurses.patch</filename> by changing
+ If your program doesn't compile since the <literal>foo</literal> library
- <literal>curses</literal> into <literal>ncurses</literal>.
+ doesn't exist and its equivalent is provided by the <literal>foo2</literal>
+ library on the Debian system, you can fix this build problem as
+ <filename>debian/patches/foo2.patch</filename> by changing
+ <literal>foo</literal> into <literal>foo2</literal>.<footnote><para>If there
+ are API changes from the <literal>foo</literal> library to the
+ <literal>foo2</literal> library, required changes to the source code need to be
+ made to match the new API.</para> </footnote>
  </para>
  <screen>
- $ dquilt new ncurses.patch
+ $ dquilt new foo2.patch
  $ dquilt add Makefile
- $ sed -i s/-lcurses/-lncurses/g Makefile
+ $ sed -i -e 's/-lfoo/-lfoo2/g' Makefile
  $ dquilt refresh
  $ dquilt header -e
  ... describe patch
-Line 1574 
 $ dquilt header -e
+Line 1761 
 $ dquilt header -e
  </chapter>
  <chapter id="dreq"><title>Required files under the <filename>debian</filename> directory</title>
  <para>
- There is a new subdirectory under the program's source directory, it's called
+ There is a new subdirectory under the program's source directory, called
  <filename>debian</filename>.  There are a number of files in this directory
  that we should edit in order to customize the behavior of the package.  The
  most important of them are <filename>control</filename>,
- <filename>changelog</filename>, <filename>copyright</filename> and
+ <filename>changelog</filename>, <filename>copyright</filename>, and
  <filename>rules</filename>, which are required for all packages.
  <footnote><para>
  In this chapter, files in the <filename>debian</filename> directory are
- referred without preceding <filename>debian/</filename> for simplicity whenever
+ referred to without the leading <filename>debian/</filename> for simplicity whenever
- they are obvious.
+ the meaning is obvious.
  </para></footnote>
  </para>
- <section id="control"><title><filename>control</filename> file</title>
+ <section id="control"><title><filename>control</filename></title>
  <para>
  This file contains various values which <command>dpkg</command>,
  <command>dselect</command>, <command>apt-get</command>,
  <command>apt-cache</command>, <command>aptitude</command>, and other package
- management tools will use to manage the package.  It is defined by the <ulink url="&policy-control;">Debian
+ management tools will use to manage the package.  It is defined by the
- Policy Manual, 5 'Control files and their fields'</ulink>.
+ <ulink url="&policy-control;">Debian Policy Manual, 5 "Control files and their fields"</ulink>.
  </para>
  <para>
  Here is the <filename>control</filename> file <command>dh_make</command>
-Line 1627 
 Line 1 is the name of the source package
+Line 1814 
 Line 1 is the name of the source package
  Line 2 is the section of the distribution the source package goes into.
  </para>
  <para>
- As you may have noticed, Debian archive is divided in sections:
+ As you may have noticed, the Debian archive is divided into multiple areas:
  <literal>main</literal> (the free software), <literal>non-free</literal> (the
  not really free software) and <literal>contrib</literal> (free software that
- depends on non-free software).  Under those, there are logical subsections that
+ depends on non-free software).  Each of these is divided into sections that
- describe in short what packages are in.  So we have <literal>admin</literal>
+ classify packages into rough categories.  So we have <literal>admin</literal>
- for administrator-only programs, <literal>base</literal> for the basic tools,
+ for administrator-only programs,
  <literal>devel</literal> for programmer tools, <literal>doc</literal> for
  documentation, <literal>libs</literal> for libraries, <literal>mail</literal>
- for e-mail readers and daemons, <literal>net</literal> for network apps and
+ for email readers and daemons, <literal>net</literal> for network apps and
  daemons, <literal>x11</literal> for X11 programs that don't fit anywhere else,
  and many more.
  <footnote> <para>See
- <ulink url="&policy-subsections;">Debian Policy Manual, 2.4 'Sections'</ulink> and
+ <ulink url="&policy-subsections;">Debian Policy Manual, 2.4 "Sections"</ulink> and
  <ulink url="&sections-unstable;">List of sections in <literal>sid</literal></ulink>.</para>
  </footnote>
  </para>
-Line 1650 
 we can omit it.)
+Line 1837 
 we can omit it.)
  <para>
  Line 3 describes how important it is that the user installs this package.
  <footnote> <para>See
- <ulink url="&policy-priorities;">Debian Policy Manual, 2.5 'Priorities'</ulink>.
+ <ulink url="&policy-priorities;">Debian Policy Manual, 2.5 "Priorities"</ulink>.
  </para>
  </footnote>
  </para>
-Line 1658 
 Line 3 describes how important it is tha
+Line 1845 
 Line 3 describes how important it is tha
  <listitem>
  <para>
  The <literal>optional</literal> priority will usually work for new packages
- that do not conflict with others with <literal>required</literal>,
+ that do not conflict with others claiming <literal>required</literal>,
- <literal>important</literal> or <literal>standard</literal> priorities.
+ <literal>important</literal>, or <literal>standard</literal> priority.
  </para>
  </listitem>
  <listitem>
-Line 1670 
 conflict with others with non-<literal>e
+Line 1857 
 conflict with others with non-<literal>e
  </listitem>
  </itemizedlist>
  <para>
- Section and priority are used by the frontends like <command>aptitude</command>
+ Section and priority are used by front-ends like <command>aptitude</command>
  when they sort packages and select defaults.  Once you upload the package to
  Debian, the value of these two fields can be overridden by the archive
  maintainers, in which case you will be notified by email.
-Line 1681 
 we will change the priority to <literal>
+Line 1868 
 we will change the priority to <literal>
  </para>
  <para>
  Line 4 is the name and email address of the maintainer.  Make sure that this
- field includes a valid <literal>To</literal> header for an email, because after
+ field includes a valid <literal>To</literal> header for email, because after
  you upload it, the bug tracking system will use it to deliver bug emails to
- you.  Avoid using commas, ampersands and parenthesis.
+ you.  Avoid using commas, ampersands, or parentheses.
  </para>
  <para>
- The 5th line includes the list of packages required to build your package as
+ Line 5 includes the list of packages required to build your package as
  the <literal>Build-Depends</literal> field.  You can also have the
  <literal>Build-Depends-Indep</literal> field as an additional line, here.
- <footnote><para>See <ulink url="&policy-relationships;#s-sourcebinarydeps">Debian
+ <footnote><para>See
- Policy Manual, 7.7 'Relationships between source and binary packages -
+ <ulink url="&policy-relationships;#s-sourcebinarydeps">Debian Policy Manual, 7.7 "Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep"</ulink>.</para></footnote>
- Build-Depends, Build-Depends-Indep, Build-Conflicts,
+ Some packages like
- Build-Conflicts-Indep'</ulink>.</para></footnote>  Some packages like
  <systemitem role="package">gcc</systemitem> and
  <systemitem role="package">make</systemitem> which are required by the
  <systemitem role="package">build-essential</systemitem> package are implied.  If you need
  to have other tools to build your package, you should add them to these fields.
  Multiple entries are separated with commas; read on for the explanation of
- binary dependencies to find out more about the syntax of these lines.
+ binary package dependencies to find out more about the syntax of these lines.
  </para>
  <itemizedlist>
  <listitem>
-Line 1711 
 satisfy the Debian Policy requirement fo
+Line 1897 
 satisfy the Debian Policy requirement fo
  </listitem>
  <listitem>
  <para>
- For source packages which have some binary packages with <literal>Architecture:
+ Source packages which have binary packages with <literal>Architecture:
- any</literal>, they are rebuild by the autobuilder.  Since this autobuilder
+ any</literal> are rebuilt by the autobuilder.  Since this autobuilder
- procedure runs <literal>debian/rules build</literal> in it while installing
+ procedure installs only the packages listed in the
- only packages listed in the <literal>Build-Depends</literal> field (see <xref linkend="autobuilder"/>), the <literal>Build-Depends</literal> field needs to
+ <literal>Build-Depends</literal> field before running
- list practically all the required packages and the
+ <literal>debian/rules build</literal> (see <xref
- <literal>Build-Depends-indep</literal> is rarely used.
+ linkend="autobuilder"/>), the <literal>Build-Depends</literal> field
+ needs to  list practically all the required packages and
+ <literal>Build-Depends-Indep</literal> is rarely used.
  </para>
  </listitem>
  <listitem>
  <para>
- For source packages which have binary packages only with <literal>Architecture:
+ For source packages with binary packages all of which are <literal>Architecture:
  all</literal>, the <literal>Build-Depends-Indep</literal> field may list all
  the required packages unless they are already listed in the
  <literal>Build-Depends</literal> field to satisfy the Debian Policy requirement
-Line 1734 
 If you are not sure which one should be
+Line 1922 
 If you are not sure which one should be
  <literal>Build-Depends</literal> field to be on the safe side.
  <footnote><para> This somewhat strange situation is a feature well documented
  in the <ulink url="&policy-build-depends-indep;">Debian Policy
- Manual, Footnotes 48</ulink>.  This is not due to the use of the
+ Manual, Footnotes 55</ulink>.  This is not due to the use of the
  <command>dh</command> command in the <filename>debian/rules</filename> file but
  due to how the <command>dpkg-buildpackage</command> works.  The same situation
  applies to the <ulink url="https://bugs.launchpad.net/launchpad-buildd/+bug/238141">auto build system
-Line 1747 
 To find out what packages your package n
+Line 1935 
 To find out what packages your package n
  $ dpkg-depcheck -d ./configure
  </screen>
  <para>
- To manually find exact build dependency for
+ To manually find exact build dependencies for
- <command><replaceable>/usr/bin/foo</replaceable></command>, you execute
+ <command><replaceable>/usr/bin/foo</replaceable></command>, execute
  </para>
  <screen>
  $ objdump -p <replaceable>/usr/bin/foo</replaceable> | grep NEEDED
-Line 1760 
 and for each library listed, e.g., <comm
+Line 1948 
 and for each library listed, e.g., <comm
  $ dpkg -S libfoo.so.6
  </screen>
  <para>
- Then you just take <literal>-dev</literal> version of every package as
+ Then just take the <literal>-dev</literal> version of every package as a
  <literal>Build-Depends</literal> entry.  If you use <command>ldd</command> for
  this purpose, it will report indirect lib dependencies as well, resulting in
  the problem of excessive build dependencies.
-Line 1776 
 Manual</ulink> standards this package fo
+Line 1964 
 Manual</ulink> standards this package fo
  your package.
  </para>
  <para>
- On line 7 you can put the URL of the homepage for the upstream program.
+ On line 7 you can put the URL of the software's upstream homepage.
  </para>
  <para>
  Line 9 is the name of the binary package.  This is usually the same as the name
  of the source package, but it doesn't necessarily have to be that way.
  </para>
  <para>
- Line 10 describes the CPU architecture the binary package can be compiled for.
+ Line 10 describes the architectures the binary package can be compiled for.
- We'll leave this as <literal>any</literal> because <citerefentry>
+ This value is usually one of the following depending
- <refentrytitle>dpkg-gencontrol</refentrytitle> <manvolnum>1</manvolnum>
+ on the type of the binary package.
- </citerefentry> will fill in the appropriate value for any machine this package
+ <footnote><para>See
- gets compiled on.
+ <ulink url="&policy-architecture;">Debian Policy Manual 5.6.8 "Architecture"</ulink>
+ for exact details.
+ </para></footnote>
+ </para>
+ <itemizedlist>
+ <listitem><para><literal>Architecture: any</literal></para>
+   <itemizedlist>
+   <listitem><para>The generated binary package is an architecture dependent one
+     usually in a compiled language.</para></listitem>
+   </itemizedlist>
+ </listitem>
+ <listitem><para><literal>Architecture: all</literal></para>
+   <itemizedlist>
+   <listitem><para>The generated binary package is an architecture independent
+     one usually consisting of text, images, or scripts in an interpreted
+     language.</para></listitem>
+   </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>
+ We leave line 10 as is since this is written in C.
+ <citerefentry><refentrytitle>dpkg-gencontrol</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ will fill in the appropriate architecture value for any machine this source
+ package gets compiled on.
  </para>
  <para>
  If your package is architecture independent (for example, a shell or Perl
-Line 1806 
 Packages can relate to each other in var
+Line 2017 
 Packages can relate to each other in var
  </para>
  <para>
  The package management tools usually behave the same way when dealing with
- these relations; if not, it will be explained.  (see <citerefentry>
+ these relations; if not, it will be explained.  (See <citerefentry>
  <refentrytitle>dpkg</refentrytitle> <manvolnum>8</manvolnum> </citerefentry>,
  <citerefentry> <refentrytitle>dselect</refentrytitle> <manvolnum>8</manvolnum>
  </citerefentry>, <citerefentry> <refentrytitle>apt</refentrytitle>
  <manvolnum>8</manvolnum> </citerefentry>, <citerefentry>
  <refentrytitle>aptitude</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> etc.)
+ </citerefentry>, etc.)
  </para>
  <para>
  Here is a simplified description of package relationships.
  <footnote><para>See
- <ulink url="&policy-relationships;">Debian Policy Manual, 7 'Declaring relationships between packages'</ulink>.
+ <ulink url="&policy-relationships;">Debian Policy Manual, 7 "Declaring relationships between packages"</ulink>.
  </para></footnote>
  </para>
  <itemizedlist>
-Line 1837 
 severe breakage) unless a particular pac
+Line 2048 
 severe breakage) unless a particular pac
  </para>
  <para>
  Use this for packages that are not strictly necessary but are typically used
- with your program.  When a user installs your program, all frontends will
+ with your program.  When a user installs your program, all front-ends will
- likely prompt them to install the recommended packages.
+ probably prompt them to install the recommended packages.
  <command>aptitude</command> and <command>apt-get</command> install recommended
- packages along with your package (but the user can disable this default
+ packages along with your package by default (but the user can disable this
- behaviour).  <command>dpkg</command> will ignore this field.
+ behavior).  <command>dpkg</command> will ignore this field.
  </para>
  </listitem>
  <listitem>
-Line 1850 
 behaviour).  <command>dpkg</command> wil
+Line 2061 
 behaviour).  <command>dpkg</command> wil
  </para>
  <para>
  Use this for packages which will work nicely with your program but are not at
- all necessary.  When a user installs your program, all frontends will likely
+ all necessary.  When a user installs your program, they will probably not be
- prompt them to install the suggested packages.  <command>aptitude</command> can
+ prompted to install suggested packages.  <command>aptitude</command> can
  be configured to install suggested packages along with your package but this is
  not its default.  <command>dpkg</command> and <command>apt-get</command> will
  ignore this field.
-Line 1884 
 severe problems if a particular package
+Line 2095 
 severe problems if a particular package
  <literal>Breaks</literal>
  </para>
  <para>
- The package will be installed while all the listed packages will be broken.
+ When installed the package will break all the listed packages.
- Normally a <literal>Breaks</literal> entry has an earlier than version clause.
+ Normally a <literal>Breaks</literal> entry specifies that it applies to versions earlier than a certain value.
- The resolution is generally to upgrade the listed packages by the higher-level
+ The resolution is generally to use higher-level package management tools to upgrade the listed packages.
- package management tools.
  </para>
  </listitem>
  <listitem>
-Line 1922 
 symbols).
+Line 2132 
 symbols).
  </para>
  <para>
  The fields may restrict their applicability to particular versions of each
- named package.  These versions are listed in parentheses after each individual
+ named package.  The restriction of each individual package is listed in
- package name, and they should contain a relation from the list below followed
+ parentheses after its name, and should contain a relation from the list below
- by the version number.  The relations allowed are: <literal>&lt;&lt;</literal>,
+ followed by a version number value.
- <literal>&lt;=</literal>, <literal>=</literal>, <literal>&gt;=</literal> and
+ The relations allowed are: <literal>&lt;&lt;</literal>,
+ <literal>&lt;=</literal>, <literal>=</literal>, <literal>&gt;=</literal>, and
  <literal>&gt;&gt;</literal> for strictly lower, lower or equal, exactly equal,
- greater or equal and strictly greater, respectively.  For example,
+ greater or equal, and strictly greater, respectively.  For example,
  </para>
  <screen>
  Depends: foo (&gt;= 1.2), libbar1 (= 1.3.4)
-Line 1944 
 The last feature you need to know about
+Line 2155 
 The last feature you need to know about
  <para>
  <citerefentry> <refentrytitle>dh_shlibdeps</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> calculates shared library dependencies
- for binary packages.  It generates a list of ELF executables and shared
+ for binary packages.  It generates a list of <ulink url="&elf;">ELF</ulink> executables and shared
- libraries it has found for each binary package.  Such list is used for
+ libraries it has found for each binary package.  This list is used for
  substituting <literal>${shlibs:Depends}</literal>.
  </para>
  <para>
  <citerefentry> <refentrytitle>dh_perl</refentrytitle> <manvolnum>1</manvolnum>
  </citerefentry> calculates Perl dependencies.  It generates a list of a
- dependency on <literal>perl</literal> or <literal>perlapi</literal> for each binary package.  Such list is used for
+ dependencies on <literal>perl</literal> or <literal>perlapi</literal> for each binary package.  This list is used for
  substituting <literal>${perl:Depends}</literal>.
  </para>
  <para>
- Some <systemitem role="package">debhelper</systemitem> commands may make the
+ Some <systemitem role="package">debhelper</systemitem> commands may cause the
- generated package need to depend on some other packages.  All such commands
+ generated package to depend on some additional packages.  All such commands
  generate a list of required packages for each binary package.
- Such list is used for substituting <literal>${misc:Depends}</literal>.
+ This list is used for substituting <literal>${misc:Depends}</literal>.
  </para>
  <para>
  <citerefentry> <refentrytitle>dh_gencontrol</refentrytitle>
-Line 1971 
 substituting <literal>${shlibs:Depends}<
+Line 2182 
 substituting <literal>${shlibs:Depends}<
  Having said all that, we can leave the <literal>Depends</literal> field exactly
  as it is now, and insert another line after it saying <literal>Suggests:
  file</literal>, because <systemitem role="package">gentoo</systemitem> can use
- some features provided by that <systemitem role="package">file</systemitem>
+ some features provided by the <systemitem role="package">file</systemitem>
  package.
  </para>
  <para> Line 9 is the Homepage URL.  Let's assume this to be at
  <ulink url="&gentoo;"/>.
  </para>
  <para>
- Line 12 is the short description.  Most people screens are 80 columns wide so
+ Line 12 is the short description.  Terminals are conventionally 80 columns wide so
  this shouldn't be longer than about 60 characters.  I'll change it to
  <literal>fully GUI-configurable, two-pane X file manager</literal>.
  </para>
-Line 1992 
 English.  Translations of these descript
+Line 2203 
 English.  Translations of these descript
  <ulink url="&ddtp;">The Debian Description Translation Project - DDTP</ulink>.</para></footnote>
  </para>
  <para>
- Let's insert <literal>Vcs-*</literal> fields to document the Version Control
+ We can insert <literal>Vcs-*</literal> fields to document the Version Control
- System (VCS) location between line 6 and 7.
+ System (VCS) location between lines 6 and 7.
  <footnote><para>See
- <ulink url="&devref-bpp-vcs;">Developer's Reference, 6.2.5. 'Version Control System location'</ulink>.
+ <ulink url="&devref-bpp-vcs;">Debian Developer's Reference, 6.2.5. "Version Control System location"</ulink>.
  </para></footnote>
  Let's assume that the <systemitem role="package">gentoo</systemitem>
- package has its VCS located in Debian Alioth Git Service at
+ package has its VCS located in the Debian Alioth Git Service at
  <literal>git://git.debian.org/git/collab-maint/gentoo.git</literal>.
  </para>
  <para>
-Line 2026 
 Finally, here is the updated <filename>c
+Line 2237 
 Finally, here is the updated <filename>c
  they're fairly easy to work with since they are written in an XML format.
  .
  gentoo features a fairly complex and powerful file identification system,
- coupled to a object-oriented style system, which together give you a lot
+ coupled to an object-oriented style system, which together give you a lot
  of control over how files of different types are displayed and acted upon.
  Additionally, over a hundred pixmap images are available for use in file
  type descriptions.
  .
- gentoo was written from scratch in ANSI C, and it utilises the GTK+ toolkit
+ gentoo was written from scratch in ANSI C, and it utilizes the GTK+ toolkit
  for its interface.
  </screen>
  <para>
  (I've added the line numbers.)
  </para>
  </section>
- <section id="copyright"><title><filename>copyright</filename> file</title>
+ <section id="copyright"><title><filename>copyright</filename></title>
  <para>
- This file contains the information about package upstream resources, copyright
+ This file contains information about the copyright and license of the upstream sources.
- and license information.
+ <ulink url="&policy-copyright;">Debian Policy Manual, 12.5 "Copyright information"</ulink>
- <ulink url="&policy-copyright;">Debian Policy Manual, 12.5 'Copyright information'</ulink>
+ dictates its content and
- dictates its content and
+ <ulink url="&dep5;">DEP-5: Machine-parseable <filename>debian/copyright</filename></ulink>
- <ulink url="&dep5;">DEP-5: Machine-parseable <filename>debian/copyright</filename></ulink>
  provides guidelines for its format.
  </para>
  <para>
-Line 2053 
 provides guidelines for its format.
+Line 2263 
 provides guidelines for its format.
  gpl2</literal> option here to get a template file for the <systemitem role="package">gentoo</systemitem> package released under GPL-2.
  </para>
  <para>
- You must fill in missing information such as the place you got the package
+ You must fill in missing information to complete this file, such as the place you got the package
- from, the actual copyright notice and their license to complete this file.  For
+ from, the actual copyright notice, and the license.  For certain
- the common free software licenses such as GNU GPL-1, GNU GPL-2, GNU GPL-3,
+ common free software licenses (GNU GPL-1, GNU GPL-2, GNU GPL-3,
- LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0 or the Artistic
+ LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0, or the Artistic
- license, you can just refer to the appropriate file in
+ license), you can just refer to the appropriate file in the
  <filename>/usr/share/common-licenses/</filename> directory that exists on every
  Debian system.  Otherwise, you must include the complete license.
  </para>
  <para>
- In short, here's how <systemitem role="package">gentoo</systemitem>'s
+ In short, here's what <systemitem role="package">gentoo</systemitem>'s
  <filename>copyright</filename> file should look like:
  </para>
  <screen>
-Line 2092 
 In short, here's how <systemitem role="p
+Line 2302 
 In short, here's how <systemitem role="p
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  GNU General Public License for more details.
-.
+ .
  You should have received a copy of the GNU General Public License along
  with this program; if not, write to the Free Software Foundation, Inc.,
  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-Line 2105 
 In short, here's how <systemitem role="p
+Line 2315 
 In short, here's how <systemitem role="p
  (I've added the line numbers.)
  </para>
  <para>
- Please follow the HOWTO provided by ftpmasters and sent to
+ Please follow the HOWTO provided by the ftpmasters and sent to
  debian-devel-announce: <ulink url="&howto-copyright;"/>.
  </para>
  </section>
- <section id="changelog"><title><filename>changelog</filename> file</title>
+ <section id="changelog"><title><filename>changelog</filename></title>
  <para>
- This is a required file, which has a special format described in the
+ This is a required file, which has a special format described in
- <ulink url="&policy-dpkgchangelog;">Debian Policy Manual, 4.4 'debian/changelog'</ulink>.
+ <ulink url="&policy-dpkgchangelog;">Debian Policy Manual, 4.4 "debian/changelog"</ulink>.
  This format is used by <command>dpkg</command> and other programs to obtain the
- version number, revision, distribution and urgency of your package.
+ version number, revision, distribution, and urgency of your package.
  </para>
  <para>
  For you, it is also important, since it is good to have documented all changes
-Line 2124 
 saved as <filename>/usr/share/doc/gentoo
+Line 2334 
 saved as <filename>/usr/share/doc/gentoo
  binary package.
  </para>
  <para>
- <command>dh_make</command> created a default one, and this is how it looks
+ <command>dh_make</command> created a default one, and this is what it looks
  like:
  </para>
  <screen>
-Line 2140 
 like:
+Line 2350 
 like:
  </para>
  <para>
  Line 1 is the package name, version, distribution, and urgency.  The name must
- match the source package name, distribution should be either
+ match the source package name; distribution should be
  <literal>unstable</literal> (or even <literal>experimental</literal>)
  <footnote><para> Some people use invalid distribution values such as
- <literal>UNRELEASED</literal> to prevent a package to be accidentally uploaded
+ <literal>UNRELEASED</literal> to prevent a package being accidentally uploaded
  when updating a package in a shared VCS.  </para> </footnote>, and urgency
  shouldn't be changed to anything higher than <literal>low</literal>.  :-)
  </para>
  <para>
  Lines 3-5 are a log entry, where you document changes made in this package
- revision (not the upstream changes - there is special file for that purpose,
+ revision (not the upstream changes - there is a special file for that purpose,
  created by the upstream authors, which you will later install as
  <filename>/usr/share/doc/gentoo/changelog.gz</filename>).  Let's assume your
  ITP (Intent To Package) bug report number was <literal>12345</literal>.  New
- lines must be inserted just before the uppermost line that begins with
+ lines must be inserted just below the uppermost line that begins with
  <literal>*</literal> (asterisk).  You can do it with <citerefentry>
  <refentrytitle>dch</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>, or
  manually with a text editor.
-Line 2179 
 You can read more about updating the <fi
+Line 2389 
 You can read more about updating the <fi
  in <xref linkend="update"/>.
  </para>
  </section>
- <section id="rules"><title><filename>rules</filename> file</title>
+ <section id="rules"><title><filename>rules</filename></title>
  <para>
  Now we need to take a look at the exact rules which <citerefentry>
  <refentrytitle>dpkg-buildpackage</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> will use to actually create the package.  This file is actually
+ </citerefentry> will use to actually create the package.  This file is in fact
  another <filename>Makefile</filename>, but different from the one(s) in the
  upstream source.  Unlike other files in <filename>debian</filename>, this one
  is marked as executable.
  </para>
- <section id="targets"><title>Targets of <filename>rules</filename> file</title>
+ <section id="targets"><title>Targets of the <filename>rules</filename> file</title>
  <para>
- Every <filename>rules</filename> file, as any other
+ Every <filename>rules</filename> file, like any other
- <filename>Makefile</filename>, consists of several targets and their rules
+ <filename>Makefile</filename>, consists of several rules, each of
- specifying how to handle the source.  <ulink url="&policy-debianrules;">Debian
+ which defines a target and how it is carried out.
- Policy Manual, 4.9 'Main building script: debian/rules'</ulink> explains its
+ <footnote><para>You can start learning how to write <filename>Makefile</filename> from
- details.
+ <ulink url="&debref-make;">Debian Reference, 12.2. "Make"</ulink>.
+ The full documentation is available as
+ <ulink url="&gnu-make;"></ulink> or as the
+ <systemitem role="package">make-doc</systemitem> package in the <literal>non-free</literal> archive area.
+ </para></footnote>
+ A new rule begins with its target declaration in the first column.  The
+ following lines beginning with the TAB code (ASCII 9) specify the recipe for
+ carrying out that target.
+ Empty lines and lines beginning with <literal>#</literal> (hash) are treated as
+ comments and ignored.
+ <footnote><para><ulink url="&policy-debianrules;">Debian
+ Policy Manual, 4.9 "Main building script: debian/rules"</ulink> explains the
+ details.</para></footnote>
+ </para>
+ <para>
+ A rule that you want to execute is invoked by its target name as a command line argument.  For
+ example, <literal>debian/rules <replaceable>build</replaceable></literal> and
+ <literal>fakeroot make -f debian/rules <replaceable>binary</replaceable></literal>
+ execute rules for <literal><replaceable>build</replaceable></literal> and
+ <literal><replaceable>binary</replaceable></literal> targets respectively.
  </para>
  <para>
- The simplified explanation of targets are the following.
+ Here is a simplified explanation of the targets:
  </para>
  <itemizedlist>
  <listitem>
  <para>
  <literal>clean</literal> target: to clean all compiled, generated, and useless
- files in the build-tree.  (required)
+ files in the build-tree.  (Required)
  </para>
  </listitem>
  <listitem>
  <para>
  <literal>build</literal> target: to build the source into compiled programs and
- formatted documents in the build-tree.  (required)
+ formatted documents in the build-tree.  (Required)
  </para>
  </listitem>
  <listitem>
-Line 2217 
 formatted documents in the build-tree.
+Line 2446 
 formatted documents in the build-tree.
  <literal>install</literal> target: to install files into a file tree for each
  binary package under the <filename>debian</filename> directory.  If defined,
  <literal>binary*</literal> targets effectively depend on this target.
- (optional)
+ (Optional)
  </para>
  </listitem>
  <listitem>
  <para>
  <literal>binary</literal> target: to create all binary packages (effectively
- combination of <literal>binary-arch</literal> and
+ a combination of <literal>binary-arch</literal> and
- <literal>binary-indep</literal> targets).  (required)<footnote><para> This
+ <literal>binary-indep</literal> targets).  (Required)<footnote><para> This
  target is used by <literal>dpkg-buildpackage</literal> as in <xref linkend="completebuild"/>.  </para> </footnote>
  </para>
  </listitem>
-Line 2232 
 target is used by <literal>dpkg-buildpac
+Line 2461 
 target is used by <literal>dpkg-buildpac
  <para>
  <literal>binary-arch</literal> target: to create arch-dependent
  (<literal>Architecture: any</literal>) binary packages in the parent directory.
- (required)<footnote><para> This target is used by <literal>dpkg-buildpackage
+ (Required)<footnote><para> This target is used by <literal>dpkg-buildpackage
  -B</literal> as in <xref linkend="autobuilder"/>.  </para> </footnote>
  </para>
  </listitem>
-Line 2240 
 target is used by <literal>dpkg-buildpac
+Line 2469 
 target is used by <literal>dpkg-buildpac
  <para>
  <literal>binary-indep</literal> target: to create arch-independent
  (<literal>Architecture: all</literal>) binary packages in the parent directory.
- (required)<footnote><para> This target is used by <literal>dpkg-buildpackage
+ (Required)<footnote><para> This target is used by <literal>dpkg-buildpackage
  -A</literal>.  </para> </footnote>
  </para>
  </listitem>
  <listitem>
  <para>
  <literal>get-orig-source</literal> target: to obtain the most recent version of
- the original source package from upstream archive site.  (optional)
+ the original source package from an upstream archive.  (Optional)
  </para>
  </listitem>
  </itemizedlist>
  <para>
- Rules that you want to execute are invoked as command line arguments (for
+ You are probably overwhelmed by now, but things are much simpler upon examination of the
- example, <literal>./debian/rules build</literal> or <literal>fakeroot make -f
- debian/rules binary</literal>).  After the target name, you can name the
- dependency, program or file that the rule depends on.  After that, there can be
- any number of commands, indented with
- <literal><replaceable>TAB</replaceable></literal>.  A new rule begins with the
- target declaration in the first column.  Empty lines and lines beginning with
- <literal>#</literal> (hash) are treated as comments and ignored.
- </para>
- <para>
- You are probably confused now, but it will all be clear upon examination of the
  <filename>rules</filename> file that <command>dh_make</command> gives us as a
- default.  You should also read <literal>info make</literal> for more
+ default.
- information.
  </para>
  </section>
  <section id="defaultrules"><title>Default <filename>rules</filename> file</title>
-Line 2290 
 Newer <command>dh_make</command> generat
+Line 2508 
 Newer <command>dh_make</command> generat
  </screen>
  <para>
  (I've added the line numbers.  In the actual <filename>rules</filename> file,
- the leading white spaces are TAB codes.)
+ the leading spaces are a TAB code.)
  </para>
  <para>
  You are probably familiar with lines like line 1 from shell and Perl scripts.
-Line 2298 
 It tells the operating system that this
+Line 2516 
 It tells the operating system that this
  <filename>/usr/bin/make</filename>.
  </para>
  <para>
- Line 11 can be uncommented to set <literal>DH_VERBOSE</literal> variable to 1.
+ Line 10 can be uncommented to set the <literal>DH_VERBOSE</literal> variable to 1,
- Then, the <command>dh</command> command will output which
+ so that the <command>dh</command> command outputs which
- <command>dh_*</command> commands are executed by the <command>dh</command>
+ <command>dh_*</command> commands it is executing.
- command.  You can also add <literal>export DH_OPTIONS=-v</literal> line here.
+ You can also add a line <literal>export DH_OPTIONS=-v</literal> here,
- Then each <command>dh_*</command> command will output which commands are
+ so that each <command>dh_*</command> command outputs which commands it
- executed by each <command>dh_*</command> command.  This helps you to understand
+ is executing.  This helps you to understand
- what exactly is going on behind this simple <filename>rules</filename> file and
+ exactly what is going on behind this simple <filename>rules</filename> file and
- to debug its problems.  This new <command>dh</command> is a core part of the
+ to debug its problems.  This new <command>dh</command> is designed to form a core part of the
- <systemitem role="package">debhelper</systemitem> tools and does not hide
+ <systemitem role="package">debhelper</systemitem> tools, and not to hide
  anything from you.
  </para>
  <para>
- Lines 12 and 13 are where all the work is done.  The percent sign means any
+ Lines 12 and 13 are where all the work is done with an implicit rule using the pattern rule.  The percent sign means "any
- targets which then call a single program, <command>dh</command> with the target
+ targets", which then call a single program, <command>dh</command>, with the target
- name.  <footnote><para> This uses the new <systemitem role="package">debhelper</systemitem> V7 features.  Its design concepts are
+ name.  <footnote><para> This uses the new <systemitem role="package">debhelper</systemitem> v7 features.  Its design concepts are
  explained in <ulink url="&debhelper-slides;">Not Your
- Grandpa's Debhelper</ulink> presented at Debconf9 by the <systemitem role="package">debhelper</systemitem> upstream.  Under
+ Grandpa's Debhelper</ulink> presented at DebConf9 by the <systemitem role="package">debhelper</systemitem> upstream.  Under
  <literal>lenny</literal>, <command>dh_make</command> created a much more
- complicated <filename>rules</filename> file with many <command>dh_*</command>
+ complicated <filename>rules</filename> file with explicit rules
- scripts listed for each required explicit targets and frozen them to the state
+ and many <command>dh_*</command> scripts listed for each one, most of
- when it was initially packaged.  This new <command>dh</command> command is
+ which are now unnecessary (and show the package's age). The new <command>dh</command> command is
- simpler and frees us from this constrain.  You still have full power to
+ simpler and frees us from doing the routine work "manually". You still have full power to
- customize this with <literal>override_dh_*</literal> targets.  See <xref linkend="customrules"/>.  It is based only on the <systemitem role="package">debhelper</systemitem> package and does not obfuscate the
+ customize the process with <literal>override_dh_*</literal> targets. See <xref linkend="customrules"/>.  It is based only on the <systemitem role="package">debhelper</systemitem> package and does not obfuscate the
- package building process like the <systemitem role="package">cdbs</systemitem>
+ package building process as the <systemitem role="package">cdbs</systemitem>
- package.  </para> </footnote> The <command>dh</command> command is a wrapper
+ package tends to.  </para> </footnote> The <command>dh</command> command is a wrapper
  script which runs appropriate sequences of <command>dh_*</command> programs
- depending on its argument.  <footnote><para> You can verify actual sequences of
+ depending on its argument.  <footnote><para> You can verify the actual sequences of
  <command>dh_*</command> programs invoked for a given
- <literal><replaceable>target</replaceable></literal> as <literal>dh --no-act
+ <literal><replaceable>target</replaceable></literal> without really running them by invoking <literal>dh --no-act
  <replaceable>target</replaceable></literal> or <literal>debian/rules --
- '--no-act <replaceable>target</replaceable>'</literal> without really running
+ '--no-act <replaceable>target</replaceable>'</literal>.  </para> </footnote>
- them.  </para> </footnote>
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <literal>debian/rules clean</literal> runs <literal>dh clean</literal>; which
+ <literal>debian/rules clean</literal> runs <literal>dh clean</literal>, which
  in turn runs the following:
  </para>
  <screen>
-Line 2358 
 dh_auto_test
+Line 2575 
 dh_auto_test
  <listitem>
  <para>
  <literal>fakeroot debian/rules binary</literal> runs <literal>fakeroot dh
- binary</literal>; which in turn runs the following<footnote><para> This assumes
+ binary</literal>; which in turn runs the following<footnote><para>The following
- that the <systemitem role="package">python-support</systemitem> package is
+ example assumes your <filename>debian/compat</filename> has a value equal or
- installed on the system.  </para> </footnote>:
+ more than 9 to avoid invoking any python support commands automatically.
+ </para>
+ </footnote>:
  </para>
  <screen>
  dh_testroot
-Line 2378 
 dh_installdebconf
+Line 2597 
 dh_installdebconf
  dh_installemacsen
  dh_installifupdown
  dh_installinfo
- dh_pysupport
  dh_installinit
  dh_installmenu
  dh_installmime
-Line 2428 
 for each remaining command.
+Line 2646 
 for each remaining command.
  </listitem>
  </itemizedlist>
  <para>
- The function of <command>dh_*</command> commands are almost self-evident from
+ The functions of <command>dh_*</command> commands are largely self-evident from
- their names.  <footnote><para> For complete information on what do all these
+ their names.  <footnote><para> For complete information on what all these
- <command>dh_*</command> scripts exactly do, and what their other options are,
+ <command>dh_*</command> scripts do exactly, and what their other options are,
  please read their respective manual pages and the <systemitem role="package">debhelper</systemitem> documentation.  </para> </footnote> There
- are few notable ones worth making (over)simplified explanation here assuming
+ are a few notable ones that are worth giving (over)simplified explanations here assuming
- typical build environment based on <filename>Makefile</filename>.
+ a typical build environment based on a <filename>Makefile</filename>.
  <footnote><para> These commands support other build environments such as
  <filename>setup.py</filename> which can be listed by executing
  <literal>dh_auto_build --list</literal> in a package source directory.  </para>
-Line 2442 
 typical build environment based on <file
+Line 2660 
 typical build environment based on <file
  <itemizedlist>
  <listitem>
  <para>
- <command>dh_auto_clean</command> usually executes the following if
+ <command>dh_auto_clean</command> usually executes the following if a
  <filename>Makefile</filename> exists with the <literal>distclean</literal>
- target.  <footnote><para> It actually looks for the first available target of
+ target.  <footnote><para> It actually looks for the first available target
- <literal>distclean</literal>, <literal>realclean</literal> or
+ in the <filename>Makefile</filename> out of
- <literal>clean</literal> in <filename>Makefile</filename> and execute it.
+ <literal>distclean</literal>, <literal>realclean</literal>, or
+ <literal>clean</literal>, and executes that.
  </para> </footnote>
  </para>
  <screen>
-Line 2474 
 make
+Line 2693 
 make
  </listitem>
  <listitem>
  <para>
- <command>dh_auto_test</command> usually executes the following if
+ <command>dh_auto_test</command> usually executes the following if a
  <filename>Makefile</filename> exists with the <literal>test</literal> target.
- <footnote><para> It actually looks for the first available target of
+ <footnote><para> It actually looks for the first available target in
- <literal>test</literal> or <literal>check</literal> in
+ the <filename>Makefile</filename> out of <literal>test</literal> or
- <filename>Makefile</filename> and execute it.  </para> </footnote>
+ <literal>check</literal>, and executes that.</para> </footnote>
  </para>
  <screen>
  make test
-Line 2486 
 make test
+Line 2705 
 make test
  </listitem>
  <listitem>
  <para>
- <command>dh_auto_install</command> usually executes the following if
+ <command>dh_auto_install</command> usually executes the following if a
  <filename>Makefile</filename> exists with the <literal>install</literal> target
  (line folded for readability).
  </para>
-Line 2497 
 make install \
+Line 2716 
 make install \
  </listitem>
  </itemizedlist>
  <para>
- Targets which require the <command>fakeroot</command> command contain
+ All targets which require the <command>fakeroot</command> command will contain
- <command>dh_testroot</command>.  If you are not pretending to be root using
+ <command>dh_testroot</command>, which exits with an error if you are not
- this command, it exits with an error.
+ using this command to pretend to be root.
  </para>
  <para>
  The important part to know about the <filename>rules</filename> file created by
- <command>dh_make</command>, is that it is just a suggestion.  It will work for
+ <command>dh_make</command> is that it is just a suggestion.  It will work for
  most packages but for more complicated ones, don't be afraid to customize it to
- fit your needs.  Only things that you must not change are the names of the
+ fit your needs.
- rules, because all the tools use these names, as mandated by the Debian Policy.
  </para>
  <para>
- Although <literal>install</literal> is not required target, it is supported.
+ Although <literal>install</literal> is not a required target, it is supported.
  <literal>fakeroot dh install</literal> behaves like <literal>fakeroot dh
  binary</literal> but stops after <command>dh_fixperms</command>.
  </para>
-Line 2523 
 with the new <command>dh</command> comma
+Line 2741 
 with the new <command>dh</command> comma
  The <literal>dh $@</literal> command can be customized as follows.
  <footnote><para> If a package installs the
  <filename>/usr/share/perl5/Debian/Debhelper/Sequence/<replaceable>custom_name</replaceable>.pm</filename>
- file, you should activate its customization function by <literal>dh --with
+ file, you should activate its customization function by <literal>dh $@ --with
- <replaceable>custom-name</replaceable> $@</literal>.  </para> </footnote>
+ <replaceable>custom-name</replaceable></literal>.  </para> </footnote>
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Add support of the <command>dh_pysupport</command> command.  (The best choice
+ Add support for the <command>dh_python2</command> command.  (The best choice
- for Python.) <footnote><para> Use of the <command>dh_pysupport</command>
+ for Python.) <footnote><para> Use of the <command>dh_python2</command> command
- command is preferred over use of the <command>dh_pycentral</command> command.
+ is preferred over use of <command>dh_pysupport</command> or
- Do not use the <command>dh_python</command> command.  </para> </footnote>
+ <command>dh_pycentral</command> commands.  Do not use the
+ <command>dh_python</command> command.  </para> </footnote>
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">python-support</systemitem> package in
+ Include the <systemitem role="package">python</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
  <listitem>
  <para>
- Use <literal>dh $@</literal> as usual.  (This is enabled by default)
+ Use <literal>dh $@ --with python2</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ This handles Python modules using the <systemitem role="package">python</systemitem> framework.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ Add support for the <command>dh_pysupport</command> command. (deprecated)
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Include the <systemitem role="package">python-support</systemitem> package in
+ <literal>Build-Depends</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Use <literal>dh $@ --with pysupport</literal>.
  </para>
  </listitem>
  <listitem>
-Line 2555 
 This handles Python modules using the <s
+Line 2797 
 This handles Python modules using the <s
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_pycentral</command> command.
+ Add support for the <command>dh_pycentral</command> command. (deprecated)
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">python-central</systemitem> package in
+ Include the <systemitem role="package">python-central</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
  <listitem>
  <para>
- Use <literal>dh --with python-central $@</literal> instead.
+ Use <literal>dh $@ --with python-central</literal> instead.
  </para>
  </listitem>
  <listitem>
-Line 2583 
 This handles Python modules using the <s
+Line 2825 
 This handles Python modules using the <s
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_installtex</command> command.
+ Add support for the <command>dh_installtex</command> command.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">tex-common</systemitem> package in
+ Include the <systemitem role="package">tex-common</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
  <listitem>
  <para>
- Use <literal>dh --with tex $@</literal> instead.
+ Use <literal>dh $@ --with tex</literal> instead.
  </para>
  </listitem>
  <listitem>
  <para>
- This registers Type 1 fonts, hyphenation patterns, or formats with TeX.
+ This registers Type 1 fonts, hyphenation patterns, and formats with TeX.
  </para>
  </listitem>
  </itemizedlist>
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_quilt_patch</command> and
+ Add support for the <command>dh_quilt_patch</command> and
  <command>dh_quilt_unpatch</command> commands.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">quilt</systemitem> package in
+ Include the <systemitem role="package">quilt</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
  <listitem>
  <para>
- Use <literal>dh --with quilt $@</literal> instead.
+ Use <literal>dh $@ --with quilt</literal> instead.
  </para>
  </listitem>
  <listitem>
  <para>
  This applies and un-applies patches to the upstream source from files in the
- <filename>debian/patches</filename> directory for the <literal>1.0</literal>
+ <filename>debian/patches</filename> directory for a source package in the <literal>1.0</literal> format.
- source package.
  </para>
  </listitem>
  <listitem>
  <para>
  This is not needed if you use the new <literal>3.0 (quilt)</literal> source
- package.
+ package format.
  </para>
  </listitem>
  </itemizedlist>
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_dkms</command> command.
+ Add support for the <command>dh_dkms</command> command.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">dkms</systemitem> package in
+ Include the <systemitem role="package">dkms</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
  <listitem>
  <para>
- Use <literal>dh --with dkms $@</literal> instead.
+ Use <literal>dh $@ --with dkms</literal> instead.
  </para>
  </listitem>
  <listitem>
  <para>
- This correctly handles DKMS usage by the kernel module package.
+ This correctly handles DKMS usage by kernel module packages.
  </para>
  </listitem>
  </itemizedlist>
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_autotools-dev_updateconfig</command> and
+ Add support for the <command>dh_autotools-dev_updateconfig</command> and
  <command>dh_autotools-dev_restoreconfig</command> commands.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">autotools-dev</systemitem> package in
+ Include the <systemitem role="package">autotools-dev</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
  <listitem>
  <para>
- Use <literal>dh --with autotools-dev $@</literal> instead.
+ Use <literal>dh $@ --with autotools-dev</literal> instead.
  </para>
  </listitem>
  <listitem>
-Line 2686 
 This updates and restores <filename>conf
+Line 2927 
 This updates and restores <filename>conf
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_autoreconf</command> and
+ Add support for the <command>dh_autoreconf</command> and
  <command>dh_autoreconf_clean</command> commands.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">dh-autoreconf</systemitem> package in
+ Include the <systemitem role="package">dh-autoreconf</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
  <listitem>
  <para>
- Use <literal>dh --with autoreconf $@</literal> instead.
+ Use <literal>dh $@ --with autoreconf</literal> instead.
  </para>
  </listitem>
  <listitem>
-Line 2710 
 This updates the GNU Build System files
+Line 2951 
 This updates the GNU Build System files
  </listitem>
  <listitem>
  <para>
- Add support to the <command>bash</command> completion feature.
+ Add support for the <command>bash</command> completion feature.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">bash-completion</systemitem> package in
+ Includes the <systemitem role="package">bash-completion</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
  <listitem>
  <para>
- Use <literal>dh --with bash-completion $@</literal> instead.
+ Use <literal>dh $@ --with bash-completion</literal> instead.
  </para>
  </listitem>
  <listitem>
  <para>
- This installs <command>bash</command> completions using configuration file at
+ This installs <command>bash</command> completions using a configuration file at
  <filename>debian/<replaceable>package</replaceable>.bash-completion</filename>.
  </para>
  </listitem>
-Line 2740 
 command can be customized by the corresp
+Line 2981 
 command can be customized by the corresp
  manpage of each command for the customization of such features.
  </para>
  <para>
- Some <command>dh_*</command> commands invoked by the new <command>dh</command>
+ You may need to run <command>dh_*</command> commands invoked via the new <command>dh</command>
- command may require you to run it with some arguments or to run additional
+ with added arguments, or to run additional commands with them, or to skip them.
- commands with them or to skip them.  For such cases, you create an
+ For such cases, you create an
  <literal>override_dh_<replaceable>foo</replaceable></literal> target with its
- rule in the <filename>rules</filename> file only for the
+ rule in the <filename>rules</filename> file defining an
+ <literal>override_dh_<replaceable>foo</replaceable></literal> target for the
  <command>dh_<replaceable>foo</replaceable></command> command you want to
- change.  It basically say <emphasis>run me instead</emphasis>.
+ change.  It basically says <emphasis>run me instead</emphasis>.
  <footnote><para> Under <literal>lenny</literal>, if you wanted to change the
  behavior of a <command>dh_*</command> script you found the relevant line in the
  <filename>rules</filename> file and adjusted it.  </para> </footnote>
  </para>
  <para>
  Please note that the <command>dh_auto_*</command> commands tend to do more than
- what has been discussed as (over)simplified explanation to take care all the
+ what has been discussed in this (over)simplified explanation to take care of all the
- corner cases.  Use of simplified equivalent command instead of these in
+ corner cases.  It is a bad idea to use <literal>override_dh_*</literal> targets
- <literal>override_dh_*</literal> targets except the
+ to substitute simplified equivalent commands (except for the
- <literal>override_dh_auto_clean</literal> target is a bad idea since it may
+ <literal>override_dh_auto_clean</literal> target) since it may
- kill such <systemitem role="package">debhelper</systemitem>'s smart features.
+ bypass such smart <systemitem role="package">debhelper</systemitem> features.
  </para>
  <para>
- If you want to store the system configuration data in the
+ So, for instance, if you want to store system configuration data in the
  <filename>/etc/gentoo</filename> directory instead of the usual
  <filename>/etc</filename> directory for the recent
  <systemitem role="package">gentoo</systemitem> package using Autotools, you can override the default
-Line 2775 
 override_dh_auto_configure:
+Line 3017 
 override_dh_auto_configure:
  <para>
  The arguments given after <literal>--</literal> are appended to the default
  arguments of the auto-executed program to override them.  Using the
- <command>dh_auto_configure</command> command is better than the
+ <command>dh_auto_configure</command> command is better than directly invoking the
  <command>./configure</command> command here since it will only override the
- <literal>--sysconfig</literal> argument and keeps well intended other arguments
+ <literal>--sysconfig</literal> argument and retains any other, benign arguments
  to the <command>./configure</command> command.
  </para>
  <para>
- If <filename>Makefile</filename> of a source for <systemitem role="package">gentoo</systemitem> requires you to specify
+ If the <filename>Makefile</filename> in the source for <systemitem role="package">gentoo</systemitem> requires you to specify
  <literal>build</literal> as its target to build it <footnote><para>
  <command>dh_auto_build</command> without any arguments will execute the first
- target in the <filename>Makefile</filename> file.  </para> </footnote>, you
+ target in the <filename>Makefile</filename>.  </para> </footnote>, you
- create an <literal>override_dh_auto_build</literal> target to enable it.
+ create an <literal>override_dh_auto_build</literal> target to enable this.
  </para>
  <screen>
  override_dh_auto_build:
          dh_auto_build -- build
  </screen>
  <para>
- This ensures to run $(MAKE) with all the default arguments given by the
+ This ensures <literal>$(MAKE)</literal> is run with all the default arguments given by the
- <command>dh_auto_build</command> command and <literal>build</literal> argument.
+ <command>dh_auto_build</command> command plus the <literal>build</literal> argument.
  </para>
  <para>
- If <filename>Makefile</filename> of a source for <systemitem role="package">gentoo</systemitem> requires you to specify the
+ If the <filename>Makefile</filename> in the source for <systemitem role="package">gentoo</systemitem> requires you to specify the
- <literal>packageclean</literal> target to clean it for Debian package instead
+ <literal>packageclean</literal> target to clean it for the Debian package instead
- of the <literal>distclean</literal> or <literal>clean</literal> targets in the
+ of using <literal>distclean</literal> or <literal>clean</literal> targets,
- <filename>Makefile</filename> file, you create an
+ you can create an
- <literal>override_dh_auto_clean</literal> target to enable it.
+ <literal>override_dh_auto_clean</literal> target to enable thit.
  </para>
  <screen>
  override_dh_auto_clean:
          $(MAKE) packageclean
  </screen>
  <para>
- If <filename>Makefile</filename> of a source for <systemitem role="package">gentoo</systemitem> contains <literal>test</literal> target
+ If the <filename>Makefile</filename> in the source for <systemitem role="package">gentoo</systemitem> contains a <literal>test</literal> target
  which you do not want to run for the Debian package building process, you can
- use empty <literal>override_dh_auto_test</literal> target to skip it.
+ use an empty <literal>override_dh_auto_test</literal> target to skip it.
  </para>
  <screen>
  override_dh_auto_test:
-Line 2821 
 changelog file called <filename>FIXES</f
+Line 3063 
 changelog file called <filename>FIXES</f
  The <command>dh_installchangelogs</command> command requires
  <filename>FIXES</filename> as its argument to install it.  <footnote><para> The
  <filename>debian/changelog</filename> and <filename>debian/NEWS</filename>
- files are always automatically installed.  The upstream changelog is searched
+ files are always automatically installed.  The upstream changelog is found
- by converting filenames to the lower case and matching them with the
+ by converting filenames to lower case and matching them against
  <filename>changelog</filename>, <filename>changes</filename>,
  <filename>changelog.txt</filename>, and <filename>changes.txt</filename>.
  </para> </footnote>
-Line 2833 
 override_dh_installchangelogs:
+Line 3075 
 override_dh_installchangelogs:
  </screen>
  <para>
  When you use the new <command>dh</command> command, use of explicit targets
- such as the ones listed in <xref linkend="targets"/> except
+ such as the ones listed in <xref linkend="targets"/>, other than the
- <literal>get-orig-source</literal> target may make it difficult to understand
+ <literal>get-orig-source</literal> target, may make it difficult to understand
  their exact effects.  Please limit explicit targets to
  <literal>override_dh_*</literal> targets and completely independent ones, if
  possible.
-Line 2846 
 possible.
+Line 3088 
 possible.
  <para>
  To control most of what <systemitem role="package">debhelper</systemitem> does
  while building the package, you put optional configuration files under the
- <filename>debian</filename> directory.  This chapter will make an overview of
+ <filename>debian</filename> directory.  This chapter will provide an overview of
- what each of these does and its format.  Please read <ulink url="&debian-policy;">Debian Policy
+ what each of these does and its format.  Please read the <ulink url="&debian-policy;">Debian Policy
  Manual</ulink> and <ulink url="&developers-reference;">Debian Developer's
- Reference</ulink> for guidelines for the packaging.
+ Reference</ulink> for guidelines for packaging.
  </para>
  <para>
  The <command>dh_make</command> command will create some template configuration
-Line 2860 
 prefixed by the binary package name such
+Line 3102 
 prefixed by the binary package name such
  them.
  <footnote><para>
  In this chapter, files in the <filename>debian</filename> directory are
- referred without preceding <filename>debian/</filename> for simplicity whenever
+ referred to without the leading <filename>debian/</filename> for simplicity whenever
- they are obvious.
+ the meaning is obvious.
  </para></footnote>
  </para>
  <para>
- The <command>dh_make</command> command may not create some template
+ Some template configuration files for <systemitem role="package">debhelper</systemitem>
- configuration files for <systemitem role="package">debhelper</systemitem>.  In
+ may not be created by the <command>dh_make</command> command.  In
- such cases, you need to create them with the editor.
+ such cases, you need to create them with an editor.
  </para>
  <para>
- If you wish or need to activate any of those, please do the following.
+ If you wish or need to activate any of these, please do the following:
  </para>
  <itemizedlist>
  <listitem>
  <para>
  rename template files by removing the <literal>.ex</literal> or
- <literal>.EX</literal> suffix if the template files have one.
+ <literal>.EX</literal> suffix if they have one;
  </para>
  </listitem>
  <listitem>
  <para>
- rename the name of these configuration files using the actual binary package
+ rename the configuration files to use the actual binary package
- name in place of <literal><replaceable>package</replaceable></literal>.
+ name in place of <literal><replaceable>package</replaceable></literal>;
  </para>
  </listitem>
  <listitem>
  <para>
- modify template file contents to suit your needs.
+ modify template file contents to suit your needs;
  </para>
  </listitem>
  <listitem>
  <para>
- remove template files which you do not need.
+ remove template files which you do not need;
  </para>
  </listitem>
  <listitem>
  <para>
  modify the <filename>control</filename> file (see <xref linkend="control"/>),
- if necessary.
+ if necessary;
  </para>
  </listitem>
  <listitem>
-Line 2909 
 necessary.
+Line 3151 
 necessary.
  </listitem>
  </itemizedlist>
  <para>
- Those <systemitem role="package">debhelper</systemitem> configuration files
+ Any <systemitem role="package">debhelper</systemitem> configuration files
- without <filename><replaceable>package</replaceable></filename> prefix such as
+ without a <filename><replaceable>package</replaceable></filename> prefix, such as
- <filename>install</filename> apply to the first binary package.  When there are
+ <filename>install</filename>, apply to the first binary package.  When there are
  many binary packages, their configurations can be specified by prefixing their
  name to their configuration filenames such as
  <filename><replaceable>package-1</replaceable>.install</filename>,
  <filename><replaceable>package-2</replaceable>.install</filename>, etc.
  </para>
- <section id="readme"><title><filename>README.Debian</filename> file</title>
+ <section id="readme"><title><filename>README.Debian</filename></title>
  <para>
  Any extra details or discrepancies between the original package and your Debian
  version should be documented here.
  </para>
  <para>
- <command>dh_make</command> created a default one, this is what it looks like:
+ <command>dh_make</command> created a default one; this is what it looks like:
  </para>
  <screen>
  gentoo for Debian
-Line 2937 
 If you have nothing to be documented, re
+Line 3179 
 If you have nothing to be documented, re
  </citerefentry>.
  </para>
  </section>
- <section id="compat"><title><filename>compat</filename> file</title>
+ <section id="compat"><title><filename>compat</filename></title>
  <para>
  The <filename>compat</filename> file defines the <systemitem role="package">debhelper</systemitem> compatibility level.  Currently, you
- should set it to the <systemitem role="package">debhelper</systemitem> V7 by
+ should set it to the <systemitem role="package">debhelper</systemitem> v7 as
- the following.
+ follows:
  </para>
  <screen>
  $ echo 7 &gt; debian/compat
  </screen>
  </section>
- <section id="conffiles"><title><filename>conffiles</filename> file</title>
+ <section id="conffiles"><title><filename>conffiles</filename></title>
  <para>
  One of the most annoying things about software is when you spend a great deal
  of time and effort customizing a program, only to have an upgrade stomp all
  over your changes.  Debian solves this problem by marking such configuration files as conffiles.
  <footnote><para>See <citerefentry> <refentrytitle>dpkg</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> and
- <ulink url="&policy-conffiles;">Debian Policy Manual 'D.2.5 Conffiles'</ulink>.
+ <ulink url="&policy-conffiles;">Debian Policy Manual "D.2.5 Conffiles"</ulink>.
  </para></footnote>
- When you upgrade a package, you'll be prompted whether you want to keep
+ When you upgrade a package, you'll be asked whether you want to keep
  your old configuration files or not.
  </para>
  <para>
- Since <systemitem role="package">debhelper</systemitem> V3, <citerefentry>
+ <citerefentry><refentrytitle>dh_installdeb</refentrytitle> <manvolnum>1</manvolnum>
- <refentrytitle>dh_installdeb</refentrytitle> <manvolnum>1</manvolnum>
+ </citerefentry> <emphasis>automatically</emphasis> flags any files under
- </citerefentry> will <emphasis>automatically</emphasis> flag any files under
  the <filename>/etc</filename> directory as conffiles, so if your program only
  has conffiles there you do not need to specify them in this file.  For most
- package types, the only place there is (and should be conffiles) is under
+ package types, the only place conffiles should ever be is under
- <filename>/etc</filename> and so this file doesn't need to exist.
+ <filename>/etc</filename>, and so this file doesn't need to exist.
  </para>
  <para>
  If your program uses configuration files but also rewrites them on its own,
- it's best not to make them as conffiles because <command>dpkg</command> will
+ it's best not to make them conffiles because <command>dpkg</command> will
  then prompt users to verify the changes all the time.
  </para>
  <para>
  If the program you're packaging requires every user to modify the configuration
- files in the <filename>/etc</filename> directory, there are 2 popular ways to
+ files in the <filename>/etc</filename> directory, there are two popular ways to
- make them not as conffiles to keep <command>dpkg</command> quiet.
+ arrange for them to not be conffiles, keeping <command>dpkg</command> quiet.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- You make a symlink under the <filename>/etc</filename> directory pointing to a
+ Create a symlink under the <filename>/etc</filename> directory pointing to a
  file under the <filename>/var</filename> directory generated by the
- <emphasis>maintainer scripts</emphasis>.
+ maintainer scripts.
  </para>
  </listitem>
  <listitem>
  <para>
- You make a file generated by the <emphasis>maintainer scripts</emphasis> under
+ Create a file generated by the maintainer scripts under the <filename>/etc</filename> directory.
- the <filename>/etc</filename> directory.
  </para>
  </listitem>
  </itemizedlist>
  <para>
- For more information on the <emphasis>maintainer scripts</emphasis>, see <xref linkend="maintscripts"/>.
+ For information on maintainer scripts, see <xref linkend="maintscripts"/>.
  </para>
  </section>
- <section id="crond"><title><filename><replaceable>package</replaceable>.cron.*</filename> files</title>
+ <section id="crond"><title><filename><replaceable>package</replaceable>.cron.*</filename></title>
  <para>
  If your package requires regularly scheduled tasks to operate properly, you can
- use this file to set it up.  You can either setup regular tasks that happen
+ use these files to set that up.  You can set up regular tasks that either happen
- hourly, daily, weekly or monthly or alternatively happen any other time that
+ hourly, daily, weekly, or monthly, or alternatively happen at any other time that
  you wish.  The filenames are:
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <filename>cron.hourly</filename> - Installed as
+ <filename><replaceable>package</replaceable>.cron.hourly</filename> - Installed as
- <filename>/etc/cron.hourly/<replaceable>package</replaceable></filename>: run
+ <filename>/etc/cron.hourly/<replaceable>package</replaceable></filename>; run
- once an hour every hour.
+ once an hour.
  </para>
  </listitem>
  <listitem>
  <para>
- <filename>cron.daily</filename> - Installed as
+ <filename><replaceable>package</replaceable>.cron.daily</filename> - Installed as
- <filename>/etc/cron.daily/<replaceable>package</replaceable></filename>: run
+ <filename>/etc/cron.daily/<replaceable>package</replaceable></filename>; run
- once a day, usually early morning.
+ once a day.
  </para>
  </listitem>
  <listitem>
  <para>
- <filename>cron.weekly</filename> - Installed as
+ <filename><replaceable>package</replaceable>.cron.weekly</filename> - Installed as
- <filename>/etc/cron.weekly/<replaceable>package</replaceable></filename>: run
+ <filename>/etc/cron.weekly/<replaceable>package</replaceable></filename>; run
- once a week, usually early Sunday morning.
+ once a week.
  </para>
  </listitem>
  <listitem>
  <para>
- <filename>cron.monthly</filename> - Installed as
+ <filename><replaceable>package</replaceable>.cron.monthly</filename> - Installed as
  <filename>/etc/cron.monthly/<replaceable>package</replaceable></filename>: run
- once a month, usually early morning on the first of the month.
+ once a month.
  </para>
  </listitem>
  <listitem>
  <para>
- <filename>cron.d</filename> - Installed as
+ <filename><replaceable>package</replaceable>.cron.d</filename> - Installed as
  <filename>/etc/cron.d/<replaceable>package</replaceable></filename>: for any
- other time
+ other time.
  </para>
  </listitem>
  </itemizedlist>
  <para>
- For the named files, the format of them is the shell script.  The different one
+ Most of these files are shell scripts, with the exception of
- is <filename><replaceable>package</replaceable>.cron.d</filename> which follows
+ <filename><replaceable>package</replaceable>.cron.d</filename> which follows
  the format of <citerefentry> <refentrytitle>crontab</refentrytitle>
  <manvolnum>5</manvolnum> </citerefentry>.
  </para>
  <para>
- Note that this doesn't include log rotation; for that, see <citerefentry>
+ No explicit <filename>cron.*</filename> file is needed to set up log rotation;
- <refentrytitle>dh_installlogrotate</refentrytitle> <manvolnum>1</manvolnum>
+ for that, see
- </citerefentry> and <citerefentry> <refentrytitle>logrotate</refentrytitle>
+ <citerefentry><refentrytitle>dh_installlogrotate</refentrytitle>
- <manvolnum>8</manvolnum> </citerefentry>.
+ <manvolnum>1</manvolnum></citerefentry> and
+ <citerefentry><refentrytitle>logrotate</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  </para>
  </section>
- <section id="dirs"><title><filename>dirs</filename> file</title>
+ <section id="dirs"><title><filename>dirs</filename></title>
  <para>
- This file specifies the directories which we need but the normal installation
+ This file specifies any directories which we need but which are not created by the normal installation
  procedure (<literal>make install DESTDIR=...</literal> invoked by
- <literal>dh_auto_install</literal>) somehow doesn't create.  This generally
+ <literal>dh_auto_install</literal>).  This generally
  means there is a problem with the <filename>Makefile</filename>.
  </para>
  <para>
- Files listed in the <filename>install</filename> file doesn't need the
+ Files listed in an <filename>install</filename> file don't need their
  directories created first.  See <xref linkend="install"/>.
  </para>
  <para>
  It is best to try to run the installation first and only use this if you
  run into trouble.  There is no preceding slash on the directory names listed in
  the <filename>dirs</filename> file.
  </para>
  </section>
- <section id="doc-base"><title><filename><replaceable>package</replaceable>.doc-base</filename> file</title>
+ <section id="doc-base"><title><filename><replaceable>package</replaceable>.doc-base</filename></title>
  <para>
- If your package has documentation other than manual pages and info docs, you
+ If your package has documentation other than manual and info pages, you
  should use the <systemitem role="package">doc-base</systemitem> file to
  register it, so the user can find it with e.g.  <citerefentry>
  <refentrytitle>dhelp</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
  <citerefentry> <refentrytitle>dwww</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> or <citerefentry> <refentrytitle>doccentral</refentrytitle>
+ </citerefentry>, or <citerefentry> <refentrytitle>doccentral</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry>.
  </para>
  <para>
-Line 3086 
 This usually includes HTML, PS and PDF f
+Line 3327 
 This usually includes HTML, PS and PDF f
  <filename>/usr/share/doc/<replaceable>packagename</replaceable>/</filename>.
  </para>
  <para>
- This is how <systemitem role="package">gentoo</systemitem>'s doc-base file
+ This is what <systemitem role="package">gentoo</systemitem>'s doc-base file
  <filename>gentoo.doc-base</filename> looks like:
  </para>
  <screen>
-Line 3109 
 manual, in <ulink url="&doc-base;">Debia
+Line 3350 
 manual, in <ulink url="&doc-base;">Debia
  For more details on installing additional documentation, look in <xref linkend="destdir"/>.
  </para>
  </section>
- <section id="docs"><title><filename>docs</filename> file</title>
+ <section id="docs"><title><filename>docs</filename></title>
  <para>
  This file specifies the file names of documentation files we can have
  <citerefentry> <refentrytitle>dh_installdocs</refentrytitle>
-Line 3122 
 directory that are called <filename>BUGS
+Line 3363 
 directory that are called <filename>BUGS
  <filename>README*</filename>, <filename>TODO</filename> etc.
  </para>
  <para>
- For <systemitem role="package">gentoo</systemitem>, I also included some other
+ For <systemitem role="package">gentoo</systemitem>, some other files
- files:
+ are also included:
  </para>
  <screen>
  BUGS
-Line 3135 
 README.gtkrc
+Line 3376 
 README.gtkrc
  TODO
  </screen>
  </section>
- <section id="emacsen"><title><filename>emacsen-*</filename> file</title>
+ <section id="emacsen"><title><filename>emacsen-*</filename></title>
  <para>
  If your package supplies Emacs files that can be bytecompiled at package
  installation time, you can use these files to set it up.
-Line 3149 
 They are installed into the temporary di
+Line 3390 
 They are installed into the temporary di
  If you don't need these, remove them.
  </para>
  </section>
- <section id="examples"><title><filename><replaceable>package</replaceable>.examples</filename> file</title>
+ <section id="examples"><title><filename><replaceable>package</replaceable>.examples</filename></title>
  <para>
  The <citerefentry> <refentrytitle>dh_installexamples</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> command installs files and directories
  listed in this file as example files.
  </para>
  </section>
- <section id="initd"><title><filename><replaceable>package</replaceable>.init</filename> and <filename><replaceable>package</replaceable>.default</filename> files</title>
+ <section id="initd"><title><filename><replaceable>package</replaceable>.init</filename> and <filename><replaceable>package</replaceable>.default</filename></title>
  <para>
- If your package is a daemon that needs to be run at the system start-up, you've
+ If your package is a daemon that needs to be run at system start-up, you've
  obviously disregarded my initial recommendation, haven't you?  :-)
  </para>
  <para>
  The <filename><replaceable>package</replaceable>.init</filename> file is
  installed as the
  <filename>/etc/init.d/<replaceable>package</replaceable></filename> script
- for the <emphasis>init script</emphasis> which starts and stops a daemon.
+ which starts and stops the daemon.
  Its fairly generic skeleton template is provided by the
  <command>dh_make</command> command as <filename>init.d.ex</filename>.  You'll
  likely have to rename and edit it, a lot, while making sure to provide
-Line 3176 
 gets installed into the temporary direct
+Line 3417 
 gets installed into the temporary direct
  </para>
  <para>
  The <filename><replaceable>package</replaceable>.default</filename> file will
- be installed into
+ be installed as
  <filename>/etc/default/<replaceable>package</replaceable></filename>.  This
- file sets defaults that are sourced by the <emphasis>init script</emphasis>.  Most times this
+ file sets defaults that are sourced by the init script.  This
- <filename><replaceable>package</replaceable>.default</filename> file is used to disable running a daemon, set some default flags or
+ <filename><replaceable>package</replaceable>.default</filename> file
- timeouts.  If your <emphasis>init script</emphasis> has certain <emphasis>settable</emphasis>
+ is most often used to disable running a daemon, or to set some default flags or
- features you want to install these into the <filename><replaceable>package</replaceable>.default</filename> file, not the <emphasis>init script</emphasis>.
+ timeouts.  If your init script has certain configurable
+ features, you can set them in the <filename><replaceable>package</replaceable>.default</filename> file,
+ instead of in the init script itself.
  </para>
  <para>
- If your upstream program provides a file for the <emphasis>init script</emphasis>, you can either use it or not.  If you
+ If your upstream program provides a file for the init script, you can either use it or not.  If you
- don't use their <emphasis>init script</emphasis> then create a new one in
+ don't use their init script then create a new one in
  <filename><replaceable>package</replaceable>.init</filename>.  However
- if the upstream <emphasis>init script</emphasis> looks fine and installs in the right place you
+ if the upstream init script looks fine and installs in the right place you
- still need to setup the <filename>rc*</filename> symlinks.  To do this you will
+ still need to set up the <filename>rc*</filename> symlinks.  To do this you will
  need to override <command>dh_installinit</command> in the
  <filename>rules</filename> file with the following lines:
  </para>
-Line 3200 
 override_dh_installinit:
+Line 3443 
 override_dh_installinit:
  If you don't need this, remove the files.
  </para>
  </section>
- <section id="install"><title><filename>install</filename> file</title>
+ <section id="install"><title><filename>install</filename></title>
  <para>
  If there are files that need to be installed into your package but your
- standard <literal>make install</literal> won't do it, you put the filenames and
+ standard <literal>make install</literal> won't do it, put the filenames and
  destinations into this <filename>install</filename> file.  They are installed
  by <citerefentry> <refentrytitle>dh_install</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry>.<footnote><para> This replaces the
-Line 3216 
 the <filename>docs</filename> file and n
+Line 3459 
 the <filename>docs</filename> file and n
  <para>
  This <filename>install</filename> file has one line per file installed, with
  the name of the file (relative to the top build directory) then a space then
- the installation directory (relative to the install directory).  One example of
+ the installation directory (relative to the install directory).  One example of where this is used is if a binary <filename>src/<replaceable>bar</replaceable></filename> is left uninstalled; the
- where this is used is where a binary is forgotten to be installed, the
+ <filename>install</filename> file might look like:
- <filename>install</filename> file would look like:
  </para>
  <screen>
- src/foo/mybin usr/bin
+ src/<replaceable>bar</replaceable> usr/bin
  </screen>
  <para>
- This will mean when this package is installed, there will be a binary file
+ This means when this package is installed, there will be an executable command
- <filename>/usr/bin/mybin</filename>.
+ <filename>/usr/bin/<replaceable>bar</replaceable></filename>.
  </para>
  <para>
  Alternatively, this <filename>install</filename> can have the name of the file
  only without the installation directory when the relative directory path does
- not change.  This format is usually used for a large package that splits build
+ not change.  This format is usually used for a large package that splits the
- result into multiple binary packages using
+ output of its build into multiple binary packages using
  <filename><replaceable>package-1</replaceable>.install</filename>,
  <filename><replaceable>package-2</replaceable>.install</filename>, etc.
  </para>
  <para>
- The <command>dh_install</command> command will fall back to look in
+ The <command>dh_install</command> command will fall back to looking in
  <filename>debian/tmp</filename> for files, if it doesn't find them in the
  current directory (or wherever you've told it to look using
  <literal>--sourcedir</literal>).
  </para>
  </section>
- <section id="info"><title><filename><replaceable>package</replaceable>.info</filename> file</title>
+ <section id="info"><title><filename><replaceable>package</replaceable>.info</filename></title>
  <para>
  If your package has info pages, you should install them using <citerefentry>
  <refentrytitle>dh_installinfo</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> by listing them in the
+ </citerefentry> by listing them in a
- <filename><replaceable>package</replaceable>.info</filename> files.
+ <filename><replaceable>package</replaceable>.info</filename> file.
  </para>
  </section>
- <section id="lintian"><title><filename>{<replaceable>package</replaceable>.|source/}lintian-overrides</filename> files</title>
+ <section id="lintian"><title><filename>{<replaceable>package</replaceable>.,source/}lintian-overrides</filename></title>
  <para>
  If <systemitem role="package">lintian</systemitem> reports an erroneous
- diagnostics for a case when the policy allows exceptions to some rule, you can
+ diagnostic for a case where Debian policy allows exceptions to some rule, you can
  use <filename><replaceable>package</replaceable>.lintian-overrides</filename>
- or <filename>source/lintian-overrides</filename> to quiet it.  Please read
+ or <filename>source/lintian-overrides</filename> to quieten it.  Please read
  <ulink url="&lintian-doc;">Lintian User's Manual</ulink> and refrain
  from abusing this.
  </para>
  <para>
  <filename><replaceable>package</replaceable>.lintian-overrides</filename> is
- for the binary package named as <systemitem role="package"><replaceable>package</replaceable></systemitem> and is installed
+ for the binary package named <systemitem role="package"><replaceable>package</replaceable></systemitem> and is installed
  into
  <filename>usr/share/lintian/overrides/<replaceable>package</replaceable></filename>
  by the <command>dh_lintian</command> command.
-Line 3271 
 by the <command>dh_lintian</command> com
+Line 3513 
 by the <command>dh_lintian</command> com
  is not installed.
  </para>
  </section>
- <section id="manpage"><title><filename>manpage.*</filename> files</title>
+ <section id="manpage"><title><filename>manpage.*</filename></title>
  <para>
  Your program(s) should have a manual page.  If they don't, you should create
- them.  The <command>dh_make</command> command creates few template files for a
+ them.  The <command>dh_make</command> command creates some template files for
- manual page.  These need to be copied and edited for each command without its
+ manual pages.  These need to be copied and edited for each command missing its
  manual page.  Please make sure to remove unused templates.
  </para>
- <section id="manpage1"><title><filename>manpage.1.ex</filename> file</title>
+ <section id="manpage1"><title><filename>manpage.1.ex</filename></title>
  <para>
  Manual pages are normally written in <citerefentry>
  <refentrytitle>nroff</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.
-Line 3288 
 The <filename>manpage.1.ex</filename> te
+Line 3530 
 The <filename>manpage.1.ex</filename> te
  manual page for a brief description of how to edit such a file.
  </para>
  <para>
- The final manual page file name should include the name of the program it is
+ The final manual page file name should give the name of the program it is
  documenting, so we will rename it from <literal>manpage</literal> to
  <literal>gentoo</literal>.  The file name also includes <literal>.1</literal>
  as the first suffix, which means it's a manual page for a user command.  Be
  sure to verify that this section is indeed the correct one.  Here's a short
  list of manual page sections:
  </para>
- <table id="manpage-sections" pgwide="0" frame="topbot" rowsep="1" colsep="1">
+ <informaltable id="manpage-sections" pgwide="0" frame="topbot" rowsep="1" colsep="1">
- <title>manual page sections</title>
  <tgroup cols="3">
    <colspec colwidth="8*" align="left"/> <colspec colwidth="24*" align="left"/> <colspec colwidth="40*" align="left"/>
    <thead>
-Line 3314 
 list of manual page sections:
+Line 3555 
 list of manual page sections:
      <row> <entry>9</entry> <entry>Kernel routines</entry> <entry>Non-standard calls and internals</entry> </row>
    </tbody>
  </tgroup>
- </table>
+ </informaltable>
  <para>
  So <systemitem role="package">gentoo</systemitem>'s man page should be called
  <filename>gentoo.1</filename>.  If there was no <filename>gentoo.1</filename>
  man page in the original source, you should create it by renaming the
  <filename>manpage.1.ex</filename> template to <filename>gentoo.1</filename> and
- edit it by using information from the example and from upstream docs.
+ editing it using information from the example and from the upstream docs.
  </para>
  <para>
  You can use the <command>help2man</command> command to generate a man page out
- of <literal>--help</literal> and <literal>--version</literal> output of each
+ of the <literal>--help</literal> and <literal>--version</literal> output of each
- program, too.  <footnote><para> If the command is missing
+ program, too.  <footnote><para> Note that <command>help2man</command>'s
- <command>info</command> page but have documentation files in the
+ placeholder man page will claim that more detailed documentation is
- <filename>/usr/share/<replaceable>package</replaceable></filename> directory,
+ available in the info system. If the command is missing an
- you should manually edit generated the man page created by the
+ <command>info</command> page, you
+ should manually edit the man page created by the
  <command>help2man</command> command.  </para> </footnote>
  </para>
  </section>
- <section id="manpagesgml"><title><filename>manpage.sgml.ex</filename> file</title>
+ <section id="manpagesgml"><title><filename>manpage.sgml.ex</filename></title>
  <para>
  If on the other hand you prefer writing SGML instead of
  <command>nroff</command>, you can use the <filename>manpage.sgml.ex</filename>
-Line 3357 
 line in the <filename>control</filename>
+Line 3599 
 line in the <filename>control</filename>
  </listitem>
  <listitem>
  <para>
- add a <literal>override_dh_auto_build</literal> target to your
+ add an <literal>override_dh_auto_build</literal> target to your
  <filename>rules</filename> file:
  </para>
  <screen>
-Line 3368 
 override_dh_auto_build:
+Line 3610 
 override_dh_auto_build:
  </listitem>
  </itemizedlist>
  </section>
- <section id="manpagexml"><title><filename>manpage.xml.ex</filename> file</title>
+ <section id="manpagexml"><title><filename>manpage.xml.ex</filename></title>
  <para>
  If you prefer XML over SGML, you can use the <literal>manpage.xml.ex</literal>
  template.  If you do this, you have to:
-Line 3388 
 XSLT processor like <systemitem role="pa
+Line 3630 
 XSLT processor like <systemitem role="pa
  </listitem>
  <listitem>
  <para>
- add the <literal>docbook-xsl</literal>, <literal>docbook-xml</literal> and
+ add the <literal>docbook-xsl</literal>, <literal>docbook-xml</literal>, and
  <literal>xsltproc</literal> packages to the <literal>Build-Depends</literal>
  line in the <literal>control</literal> file
  </para>
  </listitem>
  <listitem>
  <para>
- add a <literal>override_dh_auto_build</literal> target to your
+ add an <literal>override_dh_auto_build</literal> target to your
  <filename>rules</filename> file:
  </para>
  <screen>
-Line 3413 
 override_dh_auto_build:
+Line 3655 
 override_dh_auto_build:
  </itemizedlist>
  </section>
  </section>
- <section id="manpages"><title><filename><replaceable>package</replaceable>.manpages</filename> file</title>
+ <section id="manpages"><title><filename><replaceable>package</replaceable>.manpages</filename></title>
  <para>
  If your package has manual pages, you should install them using <citerefentry>
  <refentrytitle>dh_installman</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> by listing them in the
+ </citerefentry> by listing them in a
- <filename><replaceable>package</replaceable>.manpages</filename> files.
+ <filename><replaceable>package</replaceable>.manpages</filename> file.
  </para>
  <para>
- To install <filename>docs/gentoo.1</filename> for the <systemitem role="package">gentoo</systemitem> package as its manpage, you create a
+ To install <filename>docs/gentoo.1</filename> as a manpage for the <systemitem role="package">gentoo</systemitem> package, create a
- <filename>gentoo.manpages</filename> file as the following.
+ <filename>gentoo.manpages</filename> file as follows.
  </para>
  <screen>
  docs/gentoo.1
  </screen>
  </section>
- <section id="menu"><title><filename>menu</filename> file</title>
+ <section id="menu"><title><filename>menu</filename></title>
  <para>
  X Window System users usually have a window manager with a menu that can be
  customized to launch programs.  If they have installed the Debian <systemitem role="package">menu</systemitem> package, a set of menus for every program on
-Line 3449 
 specifies what kind of interface the pro
+Line 3691 
 specifies what kind of interface the pro
  listed alternatives, e.g.  <literal>text</literal> or <literal>X11</literal>.
  </para>
  <para>
- The next is <literal>section</literal>, where the menu and submenu entry
+ The next is the <literal>section</literal> that the menu and submenu entry
  should appear in.
- <footnote><para> The current list of sections is at
+ <footnote><para> The current list of sections is in
- <ulink url="&menu-structure;">The Debian Menu sub-policy 2.1 'Preferred menu structure'</ulink>.
+ <ulink url="&menu-structure;">The Debian Menu sub-policy 2.1 "Preferred menu structure"</ulink>.
- There were a major reorganization of menu structure for <literal>squeeze</literal>.
+ There was a major reorganization of menu structure for <literal>squeeze</literal>.
  </para> </footnote>
  </para>
  <para>
-Line 3480 
 You can also add other fields like <lite
+Line 3722 
 You can also add other fields like <lite
  </citerefentry>, <citerefentry> <refentrytitle>menufile</refentrytitle>
  <manvolnum>5</manvolnum> </citerefentry>, <citerefentry>
  <refentrytitle>update-menus</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> and
+ </citerefentry>, and
- <ulink url="&menu-policy;">The Debian Menu sub-policy</ulink> for more
+ <ulink url="&policy-menu;">The Debian Menu sub-policy</ulink> for more
  information.
  </para>
  </section>
- <section id="news"><title><filename>NEWS</filename> file</title>
+ <section id="news"><title><filename>NEWS</filename></title>
  <para>
  The <citerefentry> <refentrytitle>dh_installchangelogs</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> command installs this.
  </para>
  </section>
- <section id="maintscripts"><title><filename>{post|pre}{inst|rm}</filename> files</title>
+ <section id="maintscripts"><title><filename>{pre,post}{inst,rm}</filename></title>
  <para>
  These <filename>postinst</filename>, <filename>preinst</filename>,
  <filename>postrm</filename>, and <filename>prerm</filename> files
- <footnote><para> Although I used Bash short hand expression to indicate these
+ <footnote><para> Despite this use of the <command>bash</command>
- files as <filename>{post|pre}{inst|rm}</filename> here, I recommend you to use
+ shorthand expression <filename>{pre,post}{inst,rm}</filename> to indicate these
- pure POSIX (non-Bash) shell for these <emphasis>maintainer scripts</emphasis>
+ filenames, you should use pure POSIX syntax for these maintainer scripts for
- as much as possible for the better compatibility.  </para> </footnote> are
+ compatibility with <command>dash</command> as the system shell.  </para> </footnote> are
  called <emphasis>maintainer scripts</emphasis>.  They are scripts which are put
  in the control area of the package and run by <command>dpkg</command> when your
- package is installed, upgraded or removed.
+ package is installed, upgraded, or removed.
  </para>
  <para>
  As a novice maintainer, you should avoid any manual editing of
- <emphasis>maintainer scripts</emphasis> because they are problematic.  For more
+ maintainer scripts because they are problematic.  For more
- information look in the <ulink url="&policy-mantainerscripts;">Debian
+ information refer to the <ulink url="&policy-mantainerscripts;">Debian
- Policy Manual, 6 'Package maintainer scripts and installation
+ Policy Manual, 6 "Package maintainer scripts and installation
- procedure'</ulink>, and take a look at these example files provided by
+ procedure"</ulink>, and take a look at the example files provided by
  <command>dh_make</command>.
  </para>
  <para>
- If you did not listen to me and made your custom <emphasis>maintainer
+ If you did not listen to me and have created custom maintainer
- scripts</emphasis> for a package, you should make sure to test them not only
+ scripts for a package, you should make sure to test them not only
- for <emphasis role="strong">install</emphasis> and <emphasis role="strong">upgrade</emphasis> but also for <emphasis role="strong">remove</emphasis> and <emphasis role="strong">purge</emphasis>.
+ for <emphasis role="strong">install</emphasis> and
+ <emphasis role="strong">upgrade</emphasis> but also for
+ <emphasis role="strong">remove</emphasis> and
+ <emphasis role="strong">purge</emphasis>.
  </para>
  <para>
  Upgrades to the new version should be silent and non-intrusive (existing users
  should not notice the upgrade except by discovering that old bugs have been
- fixed and there perhaps are new features).
+ fixed and perhaps that there are new features).
  </para>
  <para>
  When the upgrade is necessarily intrusive (eg., config files scattered through
- various home directories with totally different structure), you may consider to
+ various home directories with totally different structure), you may
- set package to the safe default (e.g., disabled service) and provide proper
+ consider as the last resort switching the package to a safe fallback state
- documentations required by the policy (<filename>README.Debian</filename> and
+ (e.g., disabling a service) and providing the proper documentation
- <filename>NEWS.Debian</filename>) as the last resort.  Don't bother user with
+ required by policy (<filename>README.Debian</filename> and
- the <command>debconf</command> note invoked from these <emphasis>maintainer
+ <filename>NEWS.Debian</filename>).  Don't bother the user with
- scripts</emphasis> for upgrades.
+ <command>debconf</command> notes invoked from these maintainer scripts
+ for upgrades.
  </para>
  <para>
- The <systemitem role="package">ucf</systemitem> package provides
+ The <systemitem role="package">ucf</systemitem> package provides a
  <emphasis>conffile-like</emphasis> handling infrastructure to preserve user
- changes for files that may not be labeled <emphasis>conffiles</emphasis> such
+ changes for files that may not be labeled as <emphasis>conffiles</emphasis> such
- as ones managed by the <emphasis>maintainer scripts</emphasis>.  This should
+ as those managed by the maintainer scripts.  This should
  minimize issues associated with them.
  </para>
  <para>
- These <emphasis>maintainer scripts</emphasis> are the Debian enhancements that
+ These maintainer scripts are among the Debian enhancements that
  explain <emphasis role="strong">why people choose Debian</emphasis>.  You must
- be very careful not to annoy them with these.
+ be very careful not to turn them into a source of annoyance.
  </para>
  </section>
- <section id="todo"><title><filename>TODO</filename> file</title>
+ <section id="todo"><title><filename>TODO</filename></title>
  <para>
  The <citerefentry> <refentrytitle>dh_installdocs</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> command installs this.
  </para>
  </section>
- <section id="watch"><title><filename>watch</filename> file</title>
+ <section id="watch"><title><filename>watch</filename></title>
  <para>
  The <filename>watch</filename> file format is documented in the <citerefentry>
  <refentrytitle>uscan</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
  manpage.  The <filename>watch</filename> file configures the
  <command>uscan</command> program (in the <systemitem role="package">devscripts</systemitem> package) to watch the site where you
- originally got the source from.  This is also used by <ulink url="&dehs;">Debian External Health Status (DEHS)</ulink>.
+ originally got the source from.  This is also used by the
+ <ulink url="&dehs;">Debian External Health Status (DEHS)</ulink> service.
  </para>
  <para>
- Here's what I put in it:
+ Here are its contents:
  </para>
  <screen>
  # watch control file for uscan
-Line 3566 
 version=3
+Line 3813 
 version=3
  &sf-net;/gentoo/gentoo-(.+)\.tar\.gz debian uupdate
  </screen>
  <para>
- Normally with this <filename>watch</filename> file, the URL at
+ Normally with a <filename>watch</filename> file, the URL at
  <literal>&sf-net;/gentoo</literal> is downloaded and searched for links of
- the form <literal>&lt;a href=...&gt;</literal>.  The base name (just the part
+ the form <literal>&lt;a href=...&gt;</literal>.  The basename (just the part
- after the final <literal>/</literal>) of these linked URLs are matched against
+ after the final <literal>/</literal>) of each linked URL is compared against
- Perl regular expression (see <citerefentry> <refentrytitle>perlre</refentrytitle>
+ the Perl regular expression pattern (see <citerefentry> <refentrytitle>perlre</refentrytitle>
- <manvolnum>1</manvolnum> </citerefentry>) pattern
+ <manvolnum>1</manvolnum> </citerefentry>)
- <literal>gentoo-(.+)\.tar\.gz</literal>.  Out of matched files, the file with
+ <literal>gentoo-(.+)\.tar\.gz</literal>.  Out of the files that match, the one with
  the greatest version number is downloaded and the <command>uupdate</command>
- program is run to create the updated source tree from them.
+ program is run to create an updated source tree.
  </para>
  <para>
  Although this is true for other sites, the SourceForge download service at
  <ulink url="&sf-net;"/> is an exception.  When the
- <filename>watch</filename> file has an URL matching with the Perl regexp
+ <filename>watch</filename> file has an URL matching the Perl regexp
  <literal>^http://sf\.net/</literal>, the <command>uscan</command> program
- substitutes it with <literal>&qa-do;watch/sf.php/</literal> and
+ replaces it with <literal>&qa-do;watch/sf.php/</literal> and
- then applies this rule.  The URL redirector service at this <ulink url="&qa-do;"/> is designed to offer
+ then applies this rule.  The URL redirector service at <ulink url="&qa-do;"/> is designed to offer
- a stable redirect service to the desired file for the
+ a stable redirect service to the desired file for any
- <filename>watch</filename> file having
+ <filename>watch</filename> pattern of the form
  <literal>&sf-net;/<replaceable>project</replaceable>/<replaceable>tar-name</replaceable>-(.+)\.tar\.gz</literal>.
- This solves issues related to the periodically changing URL there.
+ This solves issues related to periodically changing SourceForge URLs.
  </para>
  </section>
- <section id="sourcef"><title><filename>source/format</filename> file</title>
+ <section id="sourcef"><title><filename>source/format</filename></title>
  <para>
  In the <filename>debian/source/format</filename> file, there should be a single
  line indicating the desired format for the source package (check <citerefentry>
-Line 3613 
 should say either:
+Line 3860 
 should say either:
  The newer <literal>3.0 (quilt)</literal> source format records modifications in
  a <command>quilt</command> patch series within
  <filename>debian/patches</filename>.  Those changes are then automatically
- applied during extraction of the source package.  <footnote><para> See <ulink url="&debsrc3;">DebSrc3.0</ulink> for the
+ applied during extraction of the source package.  <footnote><para> See
- summary information concerning the switch to the new <literal>3.0
+ <ulink url="&debsrc3;">DebSrc3.0</ulink> for a summary on the switch to the new <literal>3.0
  (quilt)</literal> and <literal>3.0 (native)</literal> source formats.  </para>
  </footnote> The Debian modifications are simply stored in a
  <filename>debian.tar.gz</filename> archive containing all files under the
  <filename>debian</filename> directory.  This new format supports inclusion of
  binary files such as PNG icons by the package maintainer without requiring
- tricks.  <footnote><para> Actually, this new format also supports multiple
+ tricks.  <footnote><para>Actually, this new format also supports multiple
  upstream tarballs and more compression methods.  These are beyond the scope of
- this document.  </para> </footnote>
+ this document.</para> </footnote>
  </para>
  <para>
  When <command>dpkg-source</command> extracts a source package in <literal>3.0
-Line 3631 
 When <command>dpkg-source</command> extr
+Line 3878 
 When <command>dpkg-source</command> extr
  the end of the extraction with the <literal>--skip-patches</literal> option.
  </para>
  </section>
- <section id="sourcel"><title><filename>source/local-options</filename> file</title>
+ <section id="sourcel"><title><filename>source/local-options</filename></title>
  <para>
  When you want to manage Debian packaging activities under a VCS, you typically
  create one branch (e.g.  <literal>upstream</literal>) tracking the upstream
-Line 3656 
 unapply-patches
+Line 3903 
 unapply-patches
  abort-on-upstream-changes
  </screen>
  </section>
- <section id="sourceopt"><title><filename>source/options</filename> file</title>
+ <section id="sourceopt"><title><filename>source/options</filename></title>
  <para>
  The autogenerated files in the source tree can be quite annoying for packaging
  since they generate meaningless large patch files.  There are custom modules
-Line 3671 
 You can provide a Perl regular expressio
+Line 3918 
 You can provide a Perl regular expressio
  creating the source package.
  </para>
  <para>
- You can store such <command>dpkg-source</command> option argument in the
+ As a general solution to address this problem of the autogenerated files,
- <filename>source/options</filename> file of the source package as the generic
+ you can store such a <command>dpkg-source</command> option argument in the
- solution to address this problem of the autogenerated files.  The following
+ <filename>source/options</filename> file of the source package.  The following
  will skip creating patch files for <filename>config.sub</filename>,
- <filename>config.guess</filename> and <filename>Makefile</filename>.
+ <filename>config.guess</filename>, and <filename>Makefile</filename>.
  </para>
  <screen>
  extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"
  </screen>
  </section>
- <section id="patches"><title><filename>patches/*</filename> files</title>
+ <section id="patches"><title><filename>patches/*</filename></title>
  <para>
  The old <literal>1.0</literal> source format created a single large
- <filename>diff.gz</filename> file which contains package maintenance files in
+ <filename>diff.gz</filename> file containing package maintenance files in
- <filename>debian</filename> and patch files to the source.  Such a package is a
+ <filename>debian</filename> and patch files for the source.  Such a package is a
  bit cumbersome to inspect and understand for each source tree modification
  later.  This is not so nice.
  </para>
  <para>
  The newer <literal>3.0 (quilt)</literal> source format stores patches in
  <filename>debian/patches/*</filename> files using the <command>quilt</command>
- command.  These patches and other package data which are all constrained under
+ command.  These patches and other package data which are all contained under
  the <filename>debian</filename> directory are packaged as the
  <filename>debian.tar.gz</filename> file.  Since the
  <command>dpkg-source</command> command can handle <command>quilt</command>
  formatted patch data in the <literal>3.0 (quilt)</literal> source without the
- <systemitem role="package">quilt</systemitem> package, it does not need to
+ <systemitem role="package">quilt</systemitem> package, it does not need a
- <literal>Build-Depends</literal> on the <systemitem role="package">quilt</systemitem> package.  <footnote><para> Several methods
+ <literal>Build-Depends</literal> on <systemitem role="package">quilt</systemitem>.
- for the patch set maintenance have been proposed and are in use with Debian
+ <footnote><para> Several methods of patch set maintenance have been proposed and are in use for Debian
  packages.  The <command>quilt</command> system is the preferred maintenance
- system in use.  Other ones are <command>dpatch</command>,
+ system in use.  Others include <command>dpatch</command>,
- <command>dbs</command>, <command>cdbs</command>, etc.  Many of these keep such
+ <command>dbs</command>, and <command>cdbs</command>.  Many of these keep such
  patches as <filename>debian/patches/*</filename> files.  </para> </footnote>
  </para>
  <para>
-Line 3711 
 The <command>quilt</command> command is
+Line 3958 
 The <command>quilt</command> command is
  It records modifications to the source as a stack of <literal>-p1</literal>
  patch files in the <filename>debian/patches</filename> directory and the source
  tree is untouched outside of the <filename>debian</filename> directory.  The
- order of these patches are recorded in the
+ order of these patches is recorded in the
  <filename>debian/patches/series</filename> file.  You can apply (=push),
  un-apply (=pop), and refresh patches easily.  <footnote><para> If you are
  asking a sponsor to upload your package, this kind of clear separation and
- documentation of your changes are very important to expedite the package review
+ documentation of your changes is very important to expedite the package review
  by your sponsor.  </para> </footnote>
  </para>
  <para>
- For <xref linkend="modify"/>, we created 3 patches in
+ For <xref linkend="modify"/>, we created three patches in
  <filename>debian/patches</filename>.
  </para>
  <para>
  Since Debian patches are located in <filename>debian/patches</filename>, please
- make sure to setup the <command>dquilt</command> command properly as described
+ make sure to set up the <command>dquilt</command> command properly as described
  in <xref linkend="quiltrc"/>.
  </para>
  <para>
- When someone (including yourself) provides you with a patch
+ When anyone (including yourself) provides a patch
  <filename><replaceable>foo</replaceable>.patch</filename> to the source later,
- then the modification of a <literal>3.0 (quilt)</literal> source package is
+ modifying a <literal>3.0 (quilt)</literal> source package is
  quite simple:
  </para>
  <screen>
-Line 3744 
 $ dquilt header -e
+Line 3991 
 $ dquilt header -e
  </screen>
  <para>
  The patches stored in the newer <literal>3.0 (quilt)</literal> source format
- must be <emphasis>fuzz</emphasis> free.  You should ensure it as <literal>dquilt
+ must be <emphasis>fuzz</emphasis> free.  You can ensure this with <literal>dquilt
  pop -a; while dquilt push; do dquilt refresh; done</literal>.
  </para>
  </section>
-Line 3755 
 We should now be ready to build the pack
+Line 4002 
 We should now be ready to build the pack
  </para>
  <section id="completebuild"><title>Complete (re)build</title>
  <para>
- In order to properly make complete (re)build of a package, you have to ensure
+ In order to perform a complete (re)build of a package properly, you
- to install
+ need to make sure you have installed
  </para>
  <itemizedlist>
  <listitem>
-Line 3829 
 Debian archives.  See
+Line 4076 
 Debian archives.  See
  <ulink url="&keycreate;">Creating a new GPG key</ulink> and
  <ulink url="&keysigning; ">Debian Wiki on Keysigning</ulink>.
  </para></footnote>
+ If you are building Debian packages only for your own local use, you can skip
+ promptings for the GPG signatures on the <filename>.dsc</filename> file and the
+ <filename>.changes</filename> file like this:
  </para>
+ <screen>
+ $ dpkg-buildpackage -us -uc
+ </screen>
  <para>
- After all this is done, you will see the following files in the directory above
+ For a non-native Debian package, e.g.,
- (<filename>~/gentoo</filename>):
+ <systemitem role="package">gentoo</systemitem>, you will see the following
+ files in the parent directory (<filename>~/gentoo</filename>) after building
+ packages:
  </para>
  <itemizedlist>
  <listitem>
-Line 3840 
 After all this is done, you will see the
+Line 4095 
 After all this is done, you will see the
  <filename>gentoo_0.9.12.orig.tar.gz</filename>
  </para>
  <para>
- This is the original source code tarball, merely renamed to the above so that
+ This is the original upstream source code tarball, merely renamed to the above so that
  it adheres to the Debian standard.  Note that this was created initially by the
  <literal>dh_make -f ../gentoo-0.9.12.tar.gz</literal>.
  </para>
-Line 3863 
 people can be sure that it's really your
+Line 4118 
 people can be sure that it's really your
  </para>
  <para>
  This compressed tarball contains your <filename>debian</filename> directory
- contents.  Each and every addition you made to the original source code are
+ contents.  Each and every addition you made to the original source code is
- stored as <command>quilt</command> patches in
+ stored as a <command>quilt</command> patch in
  <filename>debian/patches</filename>.
  </para>
  <para>
-Line 3892 
 install and remove this just like any ot
+Line 4147 
 install and remove this just like any ot
  <filename>gentoo_0.9.12-1_i386.changes</filename>
  </para>
  <para>
- This file describes all the changes made in the current package revision, and
+ This file describes all the changes made in the current package revision;
  it is used by the Debian FTP archive maintenance programs to install the binary
- and source packages in it.  It is partly generated from the
+ and source packages.  It is partly generated from the
  <filename>changelog</filename> file and the <filename>.dsc</filename> file.
  This file is GPG signed, so that people can be sure that it's really yours.
  </para>
  <para>
- As you keep working on the package, behavior will change and new features will
+ As you keep working on the package, its behavior will change and new features will
  be added.  People downloading your package can look at this file and quickly
  see what has changed.  Debian archive maintenance programs will also post the
  contents of this file to the <ulink url="&debian-devel-announce-ldo;">debian-devel-announce@lists.debian.org</ulink>
-Line 3909 
 mailing list.
+Line 4164 
 mailing list.
  </itemizedlist>
  <para>
  The long strings of numbers in the <filename>.dsc</filename> and
- <filename>.changes</filename> files are MD5/SHA1/SHA256 checksums for the files
+ <filename>.changes</filename> files are SHA1/SHA256 checksums for the files
- mentioned.  A person downloading your files can test them with <citerefentry>
+ mentioned.  Anyone downloading your files can test them with <citerefentry>
- <refentrytitle>md5sum</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
+ <refentrytitle>sha1sum</refentrytitle> <manvolnum>1</manvolnum>
- <citerefentry> <refentrytitle>sha1sum</refentrytitle> <manvolnum>1</manvolnum>
+ </citerefentry> or <citerefentry> <refentrytitle>sha256sum</refentrytitle>
- </citerefentry>, or <citerefentry> <refentrytitle>sha256sum</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> and if the numbers don't match,
  they'll know the file is corrupt or has been tampered with.
  </para>
+ <para>
+ For a native Debian package, e.g.,
+ <systemitem role="package">mypackage</systemitem>, you will see the following
+ files in the parent directory after building packages:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>mypackage_1.0.tar.gz</filename>
+ </para>
+ <para>
+ This is the source code tarball created from the
+ <filename>mypackage-1.0</filename> directory by the
+ <command>dpkg-source</command> command.  (Its suffix is not <filename>orig.tar.gz</filename>.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>mypackage_1.0.dsc</filename>
+ </para>
+ <para>
+ This is a summary of the contents of the source code as in the non-native
+ Debian package. (There is no Debian revision.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>mypackage_1.0_i386.deb</filename>
+ </para>
+ <para>
+ This is your completed binary package as in the non-native Debian package.
+ (There is no Debian revision.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>mypackage_1.0_i386.changes</filename>
+ </para>
+ <para>
+ This file describes all the changes made in the current package version as in
+ the non-native Debian package. (There is no Debian revision.)
+ </para>
+ </listitem>
+ </itemizedlist>
  </section>
  <section id="autobuilder"><title>Autobuilder</title>
  <para>
  Debian supports many <ulink url="&ports;">ports</ulink>
  with the <ulink url="&buildd;">autobuilder
- network</ulink> running <command>buildd</command> daemons on many different
+ network</ulink> running <command>buildd</command> daemons on computers
- architecture computers.  Although you do not need to do this by yourself, you
+ of many different architectures.  Although you do not need to do this yourself, you
- should be aware of what will happen on your packages.  Let's look into roughly
+ should be aware of what will happen to your packages.  Let's look into roughly
- how your packages are rebuild for many different architectures by them.
+ how they rebuild your packages for multiple architectures.
  <footnote><para> The actual autobuilder system involves much more complicated
  schemes than the one documented here.  Such details are beyond the scope of
  this document.  </para> </footnote>
  </para>
  <para>
  For <literal>Architecture: any</literal> packages, the autobuilder system
- rebuild them.  It ensures to install
+ performs a rebuild.  It ensures the installation of
  </para>
  <itemizedlist>
  <listitem>
-Line 3989 
 create and sign the upload <filename>.ch
+Line 4287 
 create and sign the upload <filename>.ch
  This is why you see your package for other architectures.
  </para>
  <para>
- Although packages listed in the <literal>Build-Depends-indep</literal> field
+ Although packages listed in the <literal>Build-Depends-Indep</literal> field
- are required to be installed for the normal packaging by us (see <xref linkend="completebuild"/>), they are not required to be installed for the
+ are required to be installed for our normal packaging work (see
- autobuilder system since it build only architecture dependent binary packages.
+ <xref linkend="completebuild"/>), they are not required to be installed for the
+ autobuilder system since it builds only architecture dependent binary packages.
  <footnote><para> Unlike under the <systemitem role="package">pbuilder</systemitem> package, the <command>chroot</command>
  environment under the <systemitem role="package">sbuild</systemitem> package
- used by the autobuilder system does not force the minimal system and may leave
+ used by the autobuilder system does not enforce the use of a minimal
- many packages installed.  </para> </footnote> This difference between normal
+ system and may have many leftover packages installed.  </para>
- packaging and autobuilder situation dictates whether you record such required
+ </footnote> This distinction between normal packaging and autobuilding
+ procedures is what dictates whether you should record such required
  packages in the <literal>Build-Depends</literal> or
- <literal>Build-Depends-indep</literal> fields of the
+ <literal>Build-Depends-Indep</literal> fields of the
  <filename>debian/control</filename> file (see <xref linkend="control"/>).
  </para>
  </section>
- <section id="option-sa"><title>Including <filename>orig.tar.gz</filename> for upload</title>
- <para>
- When you first upload the package to the archive, you need to include the
- original <filename>orig.tar.gz</filename> source, too.  If the Debian revision
- number of such package is neither <literal>1</literal> nor
- <literal>0</literal>, you must provide <command>dpkg-buildpackage</command>
- command with the <literal>-sa</literal> option.  On the other hand, the
- <literal>-sd</literal> option will force to exclude the original
- <filename>orig.tar.gz</filename> source.
- </para>
- </section>
  <section id="debuild"><title><command>debuild</command> command</title>
  <para>
- You can automate package build process of the
+ You can automate the <command>dpkg-buildpackage</command> command's
- <command>dpkg-buildpackage</command> command further with the
+ package build process further with the
  <command>debuild</command> command.  See <citerefentry>
  <refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum>
  </citerefentry>.
-Line 4024 
 You can automate package build process o
+Line 4313 
 You can automate package build process o
  <para>
  Customization of the <command>debuild</command> command can be done through
  <filename>/etc/devscripts.conf</filename> or
- <filename>~/.devscripts</filename>.  I would suggest at least following items:
+ <filename>~/.devscripts</filename>.  I would suggest at least the following items:
  </para>
  <screen>
  DEBSIGN_KEYID=Your_GPG_keyID
- DEBUILD_LINTIAN=yes
  DEBUILD_LINTIAN_OPTS=-i -I --show-overrides
  </screen>
  <para>
  With these, packages are signed by your specified GPG key ID (good for
- sponsoring packages) and checked by the <command>lintian</command> command in
+ sponsoring packages) and checked in detail by the <command>lintian</command> command.
- details.
  </para>
  <para>
- Cleaning source and rebuilding package from a user account is as simple as:
+ Cleaning the source and rebuilding the package from your user account is as simple as:
  </para>
  <screen>
  $ debuild
  </screen>
  <para>
- Please note that the <command>dpkg-buildpackage</command> option
+ Here, if you are building Debian packages only for your own local use, you can skip
- <literal>-sa</literal> to include the original <filename>orig.tar.gz</filename>
+ promptings for the GPG signatures on the <filename>.dsc</filename> file and the
- source can be specified as:
+ <filename>.changes</filename> file like this:
  </para>
  <screen>
- $ debuild -sa
+ $ debuild -us -uc
  </screen>
  <para>
- You can clean source tree as simple as:
+ You can clean the source tree as simply as:
  </para>
  <screen>
  $ debuild clean
-Line 4061 
 $ debuild clean
+Line 4348 
 $ debuild clean
  <para>
  For a clean room (<command>chroot</command>) build environment to verify the
  build dependencies, the <systemitem role="package">pbuilder</systemitem>
- package is very useful.  <footnote><para> Since the <systemitem role="package">pbuilder</systemitem> package is still evolving, you have to
+ package is very useful.  <footnote><para> Since the <systemitem
+ role="package">pbuilder</systemitem> package is still evolving, you should
  check the actual configuration situation by consulting the latest official
  documentation.</para> </footnote> This ensures a clean build from the source
  under the <literal>sid</literal> auto-builder for different architectures and
- avoids the severity serious FTBFS (Fails To Build From Source) bug which is
+ avoids a severity serious FTBFS (Fails To Build From Source) bug which is
  always in the RC (release critical) category.
- <footnote><para>See <ulink url="&buildd-do;"/> for more on the
+ <footnote><para>See <ulink url="&buildd-do;"/> for more on
- auto-builder of the Debian package.</para></footnote>
+ Debian package auto-building.</para></footnote>
  </para>
  <para>
- Let's customize the <systemitem role="package">pbuilder</systemitem> package by
+ Let's customize the <systemitem role="package">pbuilder</systemitem> package as
- the following.
+ follows:
  </para>
  <itemizedlist>
  <listitem>
  <para>
- setting <filename>/var/cache/pbuilder/result</filename> directory writable by
+ setting the <filename>/var/cache/pbuilder/result</filename> directory writable by
- the user.
+ for your user account.
  </para>
  </listitem>
  <listitem>
  <para>
  creating a directory, e.g.
  <filename><replaceable>/var/cache/pbuilder/hooks</replaceable></filename>,
- writable by the user to place hook scripts.
+ writable by the user, to place hook scripts in.
  </para>
  </listitem>
  <listitem>
  <para>
- setting <filename>~/.pbuilderrc</filename> or
+ configuring <filename>~/.pbuilderrc</filename> or
- <filename>/etc/pbuilderrc</filename> to include as follows.
+ <filename>/etc/pbuilderrc</filename> to include the followsing.
  </para>
  <screen>
- AUTO_DEBSIGN=yes
+ AUTO_DEBSIGN=${AUTO_DEBSIGN:-yes}
  HOOKDIR=<replaceable>/var/cache/pbuilder/hooks</replaceable>
  </screen>
  </listitem>
-Line 4104 
 This will allow you to sign generated pa
+Line 4392 
 This will allow you to sign generated pa
  <filename>~/.gnupg/</filename> directory.
  </para>
  <para>
- Let's then initialize the local <systemitem role="package">pbuilder</systemitem> <command>chroot</command> system first as
+ First let's initialize the local <systemitem role="package">pbuilder</systemitem> <command>chroot</command> system as
  follows.
  </para>
  <screen>
  $ sudo pbuilder create
  </screen>
  <para>
- If you already have the completed source packages, issue the following commands
+ If you already have a completed source package, issue the following commands
  in the directory where the
  <filename><replaceable>foo</replaceable>.orig.tar.gz</filename>,
  <filename><replaceable>foo</replaceable>.debian.tar.gz</filename>, and
-Line 4121 
 the local <systemitem role="package">pbu
+Line 4409 
 the local <systemitem role="package">pbu
  </para>
  <screen>
  $ sudo pbuilder --update
- $ sudo pbuilder --build <replaceable>foo</replaceable>.dsc
+ $ sudo pbuilder --build <replaceable>foo_version</replaceable>.dsc
  </screen>
  <para>
- Please note that the <command>dpkg-buildpackage</command> option
+ The newly built packages without the GPG signatures will be located in
- <literal>-sa</literal> to include the original <filename>orig.tar.gz</filename>
+ <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.
- source can be specified as:
  </para>
- <screen>
- $ sudo pbuilder --build --debbuildopts -sa <replaceable>foo</replaceable>.dsc
- </screen>
  <para>
- The newly built packages will be located in
+ The GPG signatures on the <filename>.dsc</filename> file and the
- <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.
+ <filename>.changes</filename> file can be generated as:
  </para>
+ <screen>
+ $ cd /var/cache/pbuilder/result/
+ $ debsign <replaceable>foo_version</replaceable>.dsc
+ $ debsign <replaceable>foo_version_arch</replaceable>.changes
+ </screen>
  <para>
- If you already have the updated source tree without generating the matching
+ If you have an updated source tree but have not generated the matching
- source packages, issue the following commands in the source directory where the
+ source package, issue the following commands in the source directory where the
  <filename>debian</filename> directory exists, instead.
  </para>
  <screen>
-Line 4145 
 $ sudo pbuilder --update
+Line 4434 
 $ sudo pbuilder --update
  $ pdebuild
  </screen>
  <para>
- Please note that the <command>dpkg-buildpackage</command> option
+ Here, if you are building Debian packages only for your local use, you can skip
- <literal>-sa</literal> to include the original <filename>orig.tar.gz</filename>
+ promptings for the GPG signatures on the <filename>.dsc</filename> file and the
- source can be specified as:
+ <filename>.changes</filename> file as:
  </para>
  <screen>
- $ pdebuild --debbuildopts -sa
+ $ AUTO_DEBSIGN=no pdebuild
  </screen>
  <para>
  You can log into its <command>chroot</command> environment with the
-Line 4164 
 the <literal>chroot</literal> environmen
+Line 4453 
 the <literal>chroot</literal> environmen
  <filename><replaceable>/var/cache/pbuilder/hooks</replaceable>/B90lintian</filename>
  configured as follows.  <footnote><para> This assumes
  <literal>HOOKDIR=/var/cache/pbuilder/hooks</literal>.  You can find many
- examples of the hook script in the
+ examples of hook scripts in the
  <filename>/usr/share/doc/pbuilder/examples</filename> directory.  </para>
  </footnote>
  </para>
-Line 4183 
 echo +++ end of lintian output +++
+Line 4472 
 echo +++ end of lintian output +++
  </screen>
  <para>
  You need to have access to the latest <literal>sid</literal> environment to
- build packages properly for <literal>sid</literal>.  In reality,
+ build packages properly for <literal>sid</literal>.  In practice,
- <literal>sid</literal> may be experiencing issues which makes it not desirable
+ <literal>sid</literal> may be experiencing issues which makes it undesirable
  for you to migrate your whole system.  The <systemitem role="package">pbuilder</systemitem> package can help you to cope with this
  kind of situation.
  </para>
-Line 4193 
 You may need to update your <literal>sta
+Line 4482 
 You may need to update your <literal>sta
  release for <literal>stable-proposed-updates</literal>,
  <literal>stable/updates</literal>, etc.  <footnote><para> There are some
  restrictions for such updates of your <literal>stable</literal> package.
- </para> </footnote> For such occasions, I am running <literal>sid</literal>
+ </para> </footnote> For such occasions, the fact you may be running a <literal>sid</literal>
- system is not good enough excuse not to update them promptly.  The <systemitem role="package">pbuilder</systemitem> package can help you to access
+ system is not a good enough excuse for failing to update them promptly.  The <systemitem role="package">pbuilder</systemitem> package can help you to access
- environments of almost any Debian derivative distributions of the same CPU
+ environments of almost any Debian derivative distribution of the same
  architecture.
  </para>
  <para>
-Line 4209 
 See <ulink url="&pbuilder;"/>,
+Line 4498 
 See <ulink url="&pbuilder;"/>,
  </section>
  <section id="git-buildpackage"><title><command>git-buildpackage</command> command and similars</title>
  <para>
- If your upstream uses the source code management system (VCS)
+ If your upstream uses a source code management system (VCS)
  <footnote><para>See <ulink url="&debref-vcs;">Version control systems</ulink> for more.</para></footnote>
- to maintain their code, you should consider to use them.  That makes merging
+ to maintain their code, you should consider using it as well.  This makes merging
  and cherry-picking upstream patches much easier.  There are several specialized
- wrapper script packages for the Debian package building for each VCS.
+ wrapper script packages for Debian package building for each VCS.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <systemitem role="package">git-buildpackage</systemitem>: Suite to help with
+ <systemitem role="package">git-buildpackage</systemitem>: a suite to help with
  Debian packages in Git repositories.
  </para>
  </listitem>
-Line 4230 
 maintain Debian packages with Subversion
+Line 4519 
 maintain Debian packages with Subversion
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">cvs-buildpackage</systemitem>: A set of Debian
+ <systemitem role="package">cvs-buildpackage</systemitem>: a set of Debian
  package scripts for CVS source trees.
  </para>
  </listitem>
  </itemizedlist>
  <para>
- There are packages which <emphasis>automate</emphasis> building of packages
+ For advanced audiences, there are packages which <emphasis>automate</emphasis>
- under VCS managed source tree for advanced audiences.  I will not explain them
+ the building of packages under a VCS-managed source tree.  I will not explain them
  in this tutorial.
- <footnote><para> Here are few web resources available for advanced audiences.  </para>
+ <footnote><para> Here are some web resources available for advanced audiences.  </para>
  <itemizedlist>
  <listitem> <para> <ulink url="&git-buildpackage-doc;">Building Debian Packages with git-buildpackage</ulink> </para> </listitem>
  <listitem> <para> <ulink url="&debian-packages-git;">debian packages in git</ulink> </para> </listitem>
  <listitem> <para> <ulink url="&git-debian-packaging;">Using Git for Debian Packaging</ulink> </para> </listitem>
  <listitem> <para> <ulink url="&git-dpm;">git-dpm: Debian packages in Git manager</ulink> </para> </listitem>
  <listitem> <para> <ulink url="&topgit;">Using TopGit to generate quilt series for Debian packaging</ulink> </para> </listitem>
-Line 4253 
 in this tutorial.
+Line 4542 
 in this tutorial.
  <section id="quickrebuild"><title>Quick rebuild</title>
  <para>
  With a large package, you may not want to rebuild from scratch every time while
- you tune details in <filename>debian/rules</filename>.  For testing purposes,
+ you're tuning details in <filename>debian/rules</filename>.  For testing purposes,
  you can make a <filename>.deb</filename> file without rebuilding the upstream
- sources like this <footnote><para> Environment variables which are normally
+ sources like this<footnote><para> Environment variables which are normally
  configured to proper values are not set by this method.  Never create real
  packages to be uploaded using this <emphasis role="strong">quick</emphasis>
  method.  </para> </footnote>:
-Line 4264 
 method.  </para> </footnote>:
+Line 4553 
 method.  </para> </footnote>:
  $ fakeroot debian/rules binary
  </screen>
  <para>
- Or, simply as following to see if it build or not.
+ Or simply do the following to see if it builds or not:
  </para>
  <screen>
  $ fakeroot debian/rules build
-Line 4278 
 proper procedure.  You may not be able t
+Line 4567 
 proper procedure.  You may not be able t
  </chapter>
  <chapter id="checkit"><title>Checking the package for errors</title>
  <para>
- There are few chores you should know to check the package for errors by
+ There are some techniques you should know for checking a package for errors
- yourself before uploading packages to public archives.
+ before uploading it to the public archives.
  </para>
  <para>
- Testing on machine other than your own is also good idea.  You must watch
+ It's also a good idea to carry out testing on a machine other than your own.  You must watch
- closely for any warnings or errors for all the test described here.
+ closely for any warnings or errors for all the tests described here.
  </para>
- <section id="pinstall"><title>Verifying package for install</title>
+ <section id="inadvent"><title>Suspicious changes</title>
  <para>
- You must test your package if it installs without problem.  The <citerefentry>
+ If you find a new autogenerated patch file such as
+ <filename>debian-changes-*</filename> in the
+ <filename>debian/patches</filename> directory after building your non-native
+ Debian package in <literal>3.0 (quilt)</literal> format, chances are you
+ changed some files by accident or the build script modified the upstream
+ source.  If it is your mistake, fix it.  If it is caused by the build script,
+ fix the root cause with <command>dh-autoreconf</command> as in
+ <xref linkend="customrules"/> or work around it with
+ <filename>source/options</filename> as in <xref linkend="sourceopt"/>.
+ </para>
+ </section>
+ <section id="pinstall"><title>Verifying a package's installation</title>
+ <para>
+ You must test your package for whether it installs without problem.  The <citerefentry>
  <refentrytitle>debi</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
- command helps you to test to install all the generated binary packages.
+ command helps you to test installing all the generated binary packages.
  </para>
  <screen>
  $ sudo debi gentoo_0.9.12-1_i386.changes
  </screen>
  <para>
- You have to make sure that there are no overlapped files with other existing
+ To prevent installation problem on different systems, you must make
- packages using the
+ sure that there are no filenames conflicting with other existing packages,
+ using the
  <filename>Contents-<replaceable>i386</replaceable></filename> file downloaded
- from the Debian archive to prevent installation problem on different systems.
+ from the Debian archive.
  The <command>apt-file</command> command may be handy for this task.  If there
- are overlapped files, please take actions to avoid the real problem using the
+ are collisions, please take action to avoid this real problem, whether by
- alternatives mechanism (see <citerefentry>
+ renaming the file, moving a common file to a separate package that
- <refentrytitle>update-alternatives</refentrytitle> <manvolnum>1</manvolnum>
+ multiple packages can depend on, using the alternatives mechanism (see
- </citerefentry>) by coordinating with other affected packages or by setting the
+ <citerefentry><refentrytitle>update-alternatives</refentrytitle>
- <literal>Conflicts</literal> entry in the <filename>debian/control</filename>
+ <manvolnum>1</manvolnum></citerefentry>) in coordination with the
- file.
+ maintainers of other affected packages, or declaring a
+ <literal>Conflicts</literal> relationship in the
+ <filename>debian/control</filename> file.
  </para>
  </section>
- <section id="pmaintscripts"><title>Verifying package for <emphasis>maintainer scripts</emphasis></title>
+ <section id="pmaintscripts"><title>Verifying a package's maintainer scripts</title>
  <para>
- All <emphasis>maintainer scripts</emphasis>, i.e.,
+ All maintainer scripts (that is,
  <filename>preinst</filename>, <filename>prerm</filename>,
- <filename>postinst</filename>, and <filename>postrm</filename> files, are
+ <filename>postinst</filename>, and <filename>postrm</filename> files) are
- non-trivial unless they are auto-generated by the <systemitem role="package">debhelper</systemitem> programs.  So do not use them if you are
+ hard to write correctly unless they are auto-generated by the
+ <systemitem role="package">debhelper</systemitem> programs.  So do not use them if you are
  a novice maintainer (see <xref linkend="maintscripts"/>).
  </para>
  <para>
- If the package makes use of these non-trivial <emphasis>maintainer
+ If the package makes use of these non-trivial maintainer scripts, be sure to test not only for install but also for remove,
- scripts</emphasis>, be sure to test not only for install but also for remove,
+ purge, and upgrade processes.  Many maintainer script bugs show up
- purge, and upgrade.  Many <emphasis>maintainer script</emphasis> bugs show up
  when packages are removed or purged.  Use the <command>dpkg</command> command
  as follows to test them.
  </para>
-Line 4383 
 people will often be upgrading to your p
+Line 4688 
 people will often be upgrading to your p
  last Debian release.  Remember to test upgrades from that version too.
  </para>
  <para>
- Although downgrade is not officially supported, it should be nice to support
+ Although downgrading is not officially supported, supporting it is a
- it.
+ friendly gesture.
  </para>
  </section>
- <section id="lintians"><title><systemitem role="package">lintian</systemitem> package</title>
+ <section id="lintians"><title>Using <systemitem role="package">lintian</systemitem></title>
  <para>
  Run <citerefentry> <refentrytitle>lintian</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> on your <filename>.changes</filename>
-Line 4404 
 $ lintian -i -I --show-overrides gentoo_
+Line 4709 
 $ lintian -i -I --show-overrides gentoo_
  <para>
  Of course, replace the filename with the name of the
  <filename>.changes</filename> file generated for your package.  The output of
- the <command>lintian</command> command are marked as follows.
+ the <command>lintian</command> command uses the following flags.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <literal>E:</literal> for error; a sure policy violation or a packaging error.
+ <literal>E:</literal> for error; a sure policy violation or packaging error.
  </para>
  </listitem>
  <listitem>
  <para>
- <literal>W:</literal> for warning; a possible policy violation or a packaging
+ <literal>W:</literal> for warning; a possible policy violation or packaging
  error.
  </para>
  </listitem>
  <listitem>
  <para>
- <literal>I:</literal> for info; a information on certain packaging aspects.
+ <literal>I:</literal> for info; information on certain aspects of packaging.
  </para>
  </listitem>
  <listitem>
-Line 4437 
 error.
+Line 4742 
 error.
  </listitem>
  </itemizedlist>
  <para>
- For warnings, tune the package to avoid them or verify that the warnings are
+ When you see warnings, tune the package to avoid them or verify that the warnings are
- spurious.  If spurious, set the <filename>lintian-overrides</filename> files as
+ spurious.  If spurious, set up <filename>lintian-overrides</filename> files as
  described in <xref linkend="lintian"/>.
  </para>
  <para>
  Note that you can build the package with <command>dpkg-buildpackage</command>
- and run <command>lintian</command> on it in one command with <citerefentry>
+ and run <command>lintian</command> on it in one command, if you use <citerefentry>
  <refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
- or with <citerefentry> <refentrytitle>pdebuild</refentrytitle>
+ or <citerefentry> <refentrytitle>pdebuild</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry>.
  </para>
  </section>
- <section id="debc"><title><command>debc</command> command</title>
+ <section id="debc"><title>The <command>debc</command> command</title>
  <para>
- You can list files in the binary Debian package by <citerefentry>
+ You can list files in the binary Debian package with the <citerefentry>
  <refentrytitle>debc</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
  command.
  </para>
-Line 4459 
 command.
+Line 4764 
 command.
  $ debc <replaceable>package</replaceable>.changes
  </screen>
  </section>
- <section id="debdiff"><title><command>debdiff</command> command</title>
+ <section id="debdiff"><title>The <command>debdiff</command> command</title>
  <para>
  You can compare file contents in two source Debian packages with the
  <citerefentry> <refentrytitle>debdiff</refentrytitle> <manvolnum>1</manvolnum>
-Line 4477 
 You can also compare file lists in two s
+Line 4782 
 You can also compare file lists in two s
  $ debdiff <replaceable>old-package</replaceable>.changes <replaceable>new-package</replaceable>.changes
  </screen>
  <para>
- These are useful to identify what has been changed in the source packages, if
+ These are useful to identify what has been changed in the source packages
- no files have been unintentionally misplaced or removed in the binary packages,
+ and to check for inadvertent changes made when updating binary
- and if no other inadvertent changes were made when updating binary packages.
+ packages, such as unintentionally misplacing or removing files.
  </para>
  </section>
- <section id="interdiff"><title><command>interdiff</command> command</title>
+ <section id="interdiff"><title>The <command>interdiff</command> command</title>
  <para>
  You can compare two <filename>diff.gz</filename> files with the <citerefentry>
  <refentrytitle>interdiff</refentrytitle> <manvolnum>1</manvolnum>
-Line 4499 
 files as described in <xref linkend="pat
+Line 4804 
 files as described in <xref linkend="pat
  <filename>debian/patches/*</filename> file using <command>interdiff</command>, too.
  </para>
  </section>
- <section id="mc"><title><command>mc</command> command</title>
+ <section id="mc"><title>The <command>mc</command> command</title>
  <para>
  Many of these file inspection operations can be made into an intuitive process
  by using a file manager like <citerefentry> <refentrytitle>mc</refentrytitle>
-Line 4511 
 contents of <filename>*.deb</filename> p
+Line 4816 
 contents of <filename>*.deb</filename> p
  <para>
  Be on the lookout for extra unneeded files or zero length files, both in the
  binary and source package.  Often cruft doesn't get cleaned up properly; adjust
- your <filename>rules</filename> file to compensate for that.
+ your <filename>rules</filename> file to compensate for this.
  </para>
  </section>
  </chapter>
-Line 4524 
 a public archive to share it.
+Line 4829 
 a public archive to share it.
  <para>
  Once you become an official developer,
  <footnote><para>
- See <xref linkend="socialdynamism"/>.
+ See <xref linkend="socialdynamics"/>.
  </para></footnote>
  you can upload the package to the Debian archive.
  <footnote><para>
  There are publicly accessible archives such as <ulink url="&mentors-dn;"/>
- which work almost the same way as Debian archive and provide upload area for
+ which work almost the same way as the Debian archive and provide an upload area for
- the non-DD.  You can set up an equivalent archive by yourself using tools
+ non-DDs.  You can set up an equivalent archive by yourself using the tools
- listed at <ulink url="&deb-archive;"/>.  So this section is useful for the
+ listed at <ulink url="&deb-archive;"/>.  So this section is useful for