/[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 8753 by osamu,
Sat Apr 30 00:19:52 2011 UTC
+revision 9044 by osamu,
Sat Jan 14 15:29:01 2012 UTC
 Line 121 
 important topics.  Some of them may look
  I have also intentionally skipped some corner cases and provided only pointers
  to keep this document simple.
  </para>
- <section id="socialdynamism"><title>Social dynamics of Debian</title>
+ <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 222 
 please refer to the following to learn h
  <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="&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="&nm-do;">Debian New Member 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 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 585 
 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>Workflow 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 workflow 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>package</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>
    </itemizedlist>
  </listitem>
  <listitem>
  <para>
- We create a non-native Debian source package in the <literal>3.0 (quilt)</literal> 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>package</replaceable>_<replaceable>version</replaceable>.orig.tar.gz</literal></listitem>
    <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 <literal>1.0</literal> format,
+     <footnote><para>For the older style of non-native Debian source packages in <literal>1.0</literal> format,
      <literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.diff.gz</literal>
      is used instead. </para></footnote></listitem>
    <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>.dsc</literal></listitem>
-Line 614 
 the Debian package building, by adding D
+Line 626 
 the Debian package building, by adding D
  </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>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
-Line 625 
 We build Debian binary packages, which a
+Line 637 
 We build Debian binary packages, which a
  Please note that the character separating
  <literal><replaceable>package</replaceable></literal> and
  <literal><replaceable>version</replaceable></literal> was changed from
- <literal>-</literal> (hyphen) to <literal>_</literal> (underscore).
+ <literal>-</literal> (hyphen) in the tarball name to
+ <literal>_</literal> (underscore) in the Debian package filenames.
  </para>
  <para>
- Here,
+ In the file names above, replace
- <literal><replaceable>package</replaceable></literal> part of the file name is substituted by the
+ the <literal><replaceable>package</replaceable></literal> part with the <emphasis role="strong">package name</emphasis>,
- <emphasis role="strong">package name</emphasis>,
+ the <literal><replaceable>version</replaceable></literal> part with the <emphasis role="strong">upstream version</emphasis>,
- <literal><replaceable>version</replaceable></literal> part of it is substituted by the
+ the <literal><replaceable>revision</replaceable></literal> part with the <emphasis role="strong">Debian revision</emphasis>,
- <emphasis role="strong">upstream version</emphasis>,
+ and the <literal><replaceable>arch</replaceable></literal> part with the <emphasis role="strong">package architecture</emphasis>,
- <literal><replaceable>revision</replaceable></literal> part of it is substituted by the
+ as defined in the Debian Policy Manual.
- <emphasis role="strong">Debian revision</emphasis>,
+ <footnote> <para> See
- <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>.
-Line 649 
 Debian Policy Manual: <ulink url="&polic
+Line 656 
 Debian Policy Manual: <ulink url="&polic
  and is automatically assigned by the package build process.</para></footnote>
  </para>
  <para>
- If you are making a Debian specific package without an upstream program instead,
+ If instead you are making a Debian-specific package with no upstream, the
- typical workflow of the Debian package building is simpler.
+ typical workflow of Debian package building is simpler.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- We create a native Debian source package in the <literal>3.0 (quilt)</literal> 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>package</replaceable>_<replaceable>version</replaceable>.tar.gz</literal></listitem>
-Line 664 
 We create a native Debian source package
+Line 672 
 We create a native Debian source package
  </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>package</replaceable>_<replaceable>version</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
-Line 672 
 We build Debian binary packages from the
+Line 680 
 We build Debian binary packages from the
  </listitem>
  </itemizedlist>
  <para>
- In the following, each step of this is explained with detailed examples.
+ Each step of this outline is explained with detailed examples in later sections.
  </para>
  </section>
  <section id="choose"><title>Choose your program</title>
-Line 817 
 and ask for advice.
+Line 825 
 and ask for advice.
  </para>
  </listitem>
  </itemizedlist>
+ </listitem>
  <listitem>
  <para>
  The program should <emphasis role="strong">not</emphasis> introduce security
  and maintenance concerns to the Debian system.
  </para>
- </listitem>
  <itemizedlist>
  <listitem>
  <para>
-Line 864 
 with easier packages and discouraged fro
+Line 872 
 with easier packages and discouraged fro
  </para>
  <itemizedlist>
  <listitem><para>Simple packages</para>
-   <itemizedlist>
+ <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 the POSIX shell language)</para></listitem>
+   <listitem><para>single binary package, arch = all (executables written in an interpreted language such as POSIX shell)</para></listitem>
-   <listitem><para>single binary package, arch = all (executables written in interpreter languages)</para></listitem>
+ </itemizedlist>
-   </itemizedlist>
  </listitem>
  <listitem><para>Intermediate complexity packages</para>
-   <itemizedlist>
+ <itemizedlist>
-   <listitem><para>single binary package, arch = any (executables written in compiler languages such as C and C++)</para></listitem>
+   <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 executables + documentation)</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>
+ </itemizedlist>
  </listitem>
  <listitem><para>High complexity packages</para>
-   <itemizedlist>
+ <itemizedlist>
    <listitem><para>interpreter module package used by other packages</para></listitem>
-   <listitem><para>generic library package used by other packages</para></listitem>
+   <listitem><para>generic ELF library package used by other packages</para></listitem>
-   <listitem><para>multiple binary packages containing a library package</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>
+ </itemizedlist>
  </listitem>
  </itemizedlist>
  <para>
  Packaging high complexity packages is not too hard, but it requires a bit more
- knowledge. You should seek specific guidances for every complexity. For example, some interpreter languages have their policy.
+ 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 930 
 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 974 
 or simply with freshly unpacked sources.
+Line 1011 
 or simply with freshly unpacked sources.
  </section>
  <section id="simplemake"><title>Simple build systems</title>
  <para>
- Simple programs come with a <filename>Makefile</filename> and can
+ 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 1040 
 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> executable.
+ <command><replaceable>binary</replaceable></command>.
  </para>
  <screen>
  Makefile.in -----+                +-&gt; Makefile -----+-&gt; make -&gt; <replaceable>binary</replaceable>
-Line 1054 
 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 1073 
 build system.  You can recognize such so
+Line 1110 
 build system.  You can recognize such so
  <section id="namever"><title>Package name and version</title>
  <para>
  If the upstream source comes as <filename>gentoo-0.9.12.tar.gz</filename>, you can
- consider
+ take <literal>gentoo</literal> as the (source) <emphasis role="strong">package name</emphasis>
- <emphasis role="strong">package name</emphasis> to be <literal>gentoo</literal> and
+ and <literal>0.9.12</literal> as the <emphasis role="strong">upstream version</emphasis>.
- <emphasis role="strong">upstream version</emphasis> to be <literal>0.9.12</literal>.
  These are used in the <filename>debian/changelog</filename> file described later in
  <xref linkend="changelog"/>, too.
  </para>
-Line 1083 
 These are used in the <filename>debian/c
+Line 1119 
 These are used in the <filename>debian/c
  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 the Debian Policy and the existing convention.
+ source to follow Debian Policy and existing convention.
  </para>
  <para>
  You must choose the <emphasis role="strong">package name</emphasis>
-Line 1092 
 to consist only of lower case letters (<
+Line 1128 
 to consist only of lower case letters (<
  (<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 good idea to keep its length within 30 characters.
+ 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>
  <!--
-Line 1108 
 Previous 20 chars is becoming too short
+Line 1144 
 Previous 20 chars is becoming too short
  Default aptitude setting display up to 30 chars (98.3%).
  -->
  <para>
- If upstream source uses generic words such as <literal>test-suite</literal> as
+ If upstream uses some generic term such as <literal>test-suite</literal> for
- its name, it is good idea to rename it not to contaminate name space for the
+ its name, it is a good idea to rename it to identify its contents explicitly and avoid namespace pollution.
- package name and to identify its contents explicitly.
  <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>
-Line 1123 
 tildes (<literal>~</literal>), and perio
+Line 1158 
 tildes (<literal>~</literal>), and perio
  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 charactes and the Debian revision is less than 2 characters.  For more than 90% of packages, the upstream version is less than 10 charactes and the Debian revision is less than 3 characters.</para></footnote>
+ <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):
-Line 1148 
 aptitude display 10 = 8char for up + 1ch
+Line 1183 
 aptitude display 10 = 8char for up + 1ch
 chars as max for file name of binary debs (package+up+deb+arch+.deb)
  -->
  <para>
- If the upstream software does not use normal version system like
+ If upstream does not use a normal versioning scheme such as
  <literal>2.30.32</literal> but uses some kind of date such as
- <literal>09Oct23</literal>, a random codename string or a VCS hash value as a part
+ <literal>11Apr29</literal>, a random codename string, or a VCS hash value as part
- of version, make sure to remove them from the
+ of the version, make sure to remove them from the
  <emphasis role="strong">upstream version</emphasis>.  Such information can be
  recorded in the <filename>debian/changelog</filename> file.  If you need to
  invent a version string, use the <literal>YYYYMMDD</literal> format such as
  <literal>20110429</literal> as upstream version.  This ensures that
- <command>dpkg</command> properly sees later versions as upgrades.
+ <command>dpkg</command> interprets later versions correctly as upgrades.
+ If you need to ensure smooth transition to the normal version scheme such as
+ <literal>0.1</literal> in future, use the <literal>0~YYMMDD</literal> format
+ such as <literal>0~110429</literal> as upstream version, instead.
  </para>
  <para>
  Version strings <footnote><para>Version strings may be
-Line 1169 
 Version strings <footnote><para>Version
+Line 1207 
 Version strings <footnote><para>Version
  See <xref linkend="newrevision"/> for how the
  <emphasis role="strong">Debian revision</emphasis> is incremented.
  </para></footnote>
- can be compared with <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry> as the following.
+ can be compared using <citerefentry>
+ <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>
- The version comparison rule can be summarized as the following.
+ The version comparison rule can be summarized as:
  </para>
  <itemizedlist>
- <listitem><para>The strings are compared from the head to the tail.</para></listitem>
+ <listitem><para>Strings are compared from the head to the tail.</para></listitem>
- <listitem><para>Alphabets are larger than numbers.</para></listitem>
+ <listitem><para>Letters are larger than digits.</para></listitem>
- <listitem><para>Numbers are compared as the integer.</para></listitem>
+ <listitem><para>Numbers are compared as integers.</para></listitem>
- <listitem><para>Alphabets are compared in the ASCII code order.</para></listitem>
+ <listitem><para>Letters are compared in ASCII code order.</para></listitem>
- <listitem><para>There are some special rules for periods (<literal>.</literal>), plus (<literal>+</literal>) and tildes (<literal>~</literal>) as the followings.</para>
+ <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;
-Line 1199 
 The version comparison rule can be summa
+Line 1240 
 The version comparison rule can be summa
  </listitem>
  </itemizedlist>
  <para>
- One of the tricky case happens when the upstream releases
+ 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
-Line 1217 
 configuration files instead of <filename
+Line 1258 
 configuration files instead of <filename
  </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
-Line 1322 
 package; further explanations are given
+Line 1363 
 package; further explanations are given
  <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 graphics data etc.  Installation of files may be
+ could be just a collection of graphical data etc.  Installation of files may be
- enabled by <systemitem role="package">debhelper</systemitem> configuration
+ carried out using only <systemitem role="package">debhelper</systemitem> configuration
  files such as <filename>debian/install</filename> (see
- <xref linkend="install"/>) only.
+ <xref linkend="install"/>).
  </para>
  </section>
  <section id="native-dh-make"><title>Initial native Debian package</title>
  <para>
- Debian native packages are simpler to manage if they contain source files you
+ If a package contains source files you are only maintaining for Debian,
- manage only for Debian, possibly only for local uses.  If you have source
+ 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.
-Line 1363 
 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 1489 
 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 1531 
 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 executables 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 1542 
 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 executables 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 1554 
 documentation, etc. are specified in the
+Line 1596 
 documentation, etc. are specified in the
  your package.
  </para>
  <para>
- So, we should install binary executables 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 1600 
 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 1670 
 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 1719 
 $ 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 Policy Manual, 5 "Control files and their fields"</ulink>.
  </para>
  <para>
-Line 1772 
 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
-Line 1803 
 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 1815 
 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 1826 
 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
-Line 1855 
 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 1878 
 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 1891 
 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 1904 
 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 1920 
 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 1950 
 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.
-Line 1981 
 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 1994 
 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 2028 
 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 2066 
 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 2088 
 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 2115 
 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 2136 
 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;">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 2170 
 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 2197 
 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 2236 
 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 2249 
 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>.
  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 2268 
 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 2284 
 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 2323 
 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 2361 
 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 2376 
 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 2384 
 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 2434 
 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 2442 
 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 2502 
 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 2522 
 dh_installdebconf
+Line 2597 
 dh_installdebconf
  dh_installemacsen
  dh_installifupdown
  dh_installinfo
- dh_pysupport
  dh_installinit
  dh_installmenu
  dh_installmime
-Line 2572 
 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 2586 
 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 2618 
 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 2630 
 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 2641 
 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 2667 
 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 for the <command>dh_python2</command> command.  (The best choice
+ for Python.) <footnote><para> Use of the <command>dh_python2</command> command
+ is preferred over use of <command>dh_pysupport</command> or
+ <command>dh_pycentral</command> commands.  Do not use the
+ <command>dh_python</command> command.  </para> </footnote>
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Add support of the <command>dh_pysupport</command> command.  (The best choice
+ Include the <systemitem role="package">python</systemitem> package in
- for Python.) <footnote><para> Use of the <command>dh_pysupport</command>
+ <literal>Build-Depends</literal>.
- command is preferred over use of the <command>dh_pycentral</command> command.
+ </para>
- Do not use the <command>dh_python</command> command.  </para> </footnote>
+ </listitem>
+ <listitem>
+ <para>
+ 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>
- Install the <systemitem role="package">python-support</systemitem> package in
+ Include the <systemitem role="package">python-support</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 pysupport</literal>.
  </para>
  </listitem>
  <listitem>
-Line 2699 
 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 2727 
 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 2830 
 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 2854 
 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 2884 
 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 2919 
 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 2965 
 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 2977 
 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 3004 
 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 to without the 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>
-Line 3368 
 the installation directory (relative to
+Line 3466 
 the installation directory (relative to
  src/<replaceable>bar</replaceable> usr/bin
  </screen>
  <para>
- This means when this package is installed, there will be a binary executable
+ This means when this package is installed, there will be an executable command
  <filename>/usr/bin/<replaceable>bar</replaceable></filename>.
  </para>
  <para>
-Line 3557 
 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>
-Line 3978 
 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 local use, you can skip
+ If you are building Debian packages only for your own local use, you can skip
- promptings for the GPG signitures on the <filename>.dsc</filename> file and the
+ promptings for the GPG signatures on the <filename>.dsc</filename> file and the
- <filename>.changes</filename> file as:
+ <filename>.changes</filename> file like this:
  </para>
  <screen>
  $ dpkg-buildpackage -us -uc
  </screen>
  <para>
- For the non-native Debian package, e.g.,
+ For a non-native Debian package, e.g.,
  <systemitem role="package">gentoo</systemitem>, you will see the following
  files in the parent directory (<filename>~/gentoo</filename>) after building
  packages:
-Line 4074 
 mentioned.  Anyone downloading your file
+Line 4172 
 mentioned.  Anyone downloading your file
  they'll know the file is corrupt or has been tampered with.
  </para>
  <para>
- For the native Debian package, e.g.,
+ 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>
-Line 4084 
 files in the parent directory after buil
+Line 4182 
 files in the parent directory after buil
  <filename>mypackage_1.0.tar.gz</filename>
  </para>
  <para>
- This is the source code tarball merely created from the
+ This is the source code tarball created from the
  <filename>mypackage-1.0</filename> directory by the
- <command>dpkg-source</command>.  (Its suffix is not <filename>orig.tar.gz</filename>.)
+ <command>dpkg-source</command> command.  (Its suffix is not <filename>orig.tar.gz</filename>.)
  </para>
  </listitem>
  <listitem>
-Line 4232 
 Cleaning the source and rebuilding the p
+Line 4330 
 Cleaning the source and rebuilding the p
  $ debuild
  </screen>
  <para>
- Here, if you are building Debian packages only for your local use, you can skip
+ Here, if you are building Debian packages only for your own local use, you can skip
- promptings for the GPG signitures on the <filename>.dsc</filename> file and the
+ promptings for the GPG signatures on the <filename>.dsc</filename> file and the
- <filename>.changes</filename> file as:
+ <filename>.changes</filename> file like this:
  </para>
  <screen>
  $ debuild -us -uc
-Line 4314 
 $ sudo pbuilder --update
+Line 4412 
 $ sudo pbuilder --update
  $ sudo pbuilder --build <replaceable>foo_version</replaceable>.dsc
  </screen>
  <para>
- The newly built packages without the GPG signitures will be located in
+ The newly built packages without the GPG signatures will be located in
  <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.
  </para>
  <para>
- The GPG signitures on the <filename>.dsc</filename> file and the
+ The GPG signatures on the <filename>.dsc</filename> file and the
  <filename>.changes</filename> file can be generated as:
  </para>
  <screen>
-Line 4337 
 $ pdebuild
+Line 4435 
 $ pdebuild
  </screen>
  <para>
  Here, if you are building Debian packages only for your local use, you can skip
- promptings for the GPG signitures on the <filename>.dsc</filename> file and the
+ promptings for the GPG signatures on the <filename>.dsc</filename> file and the
  <filename>.changes</filename> file as:
  </para>
  <screen>
-Line 4386 
 release for <literal>stable-proposed-upd
+Line 4484 
 release for <literal>stable-proposed-upd
  restrictions for such updates of your <literal>stable</literal> package.
  </para> </footnote> For such occasions, the fact you may be running a <literal>sid</literal>
  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 distribution of the same CPU
+ environments of almost any Debian derivative distribution of the same
  architecture.
  </para>
  <para>
-Line 4503 
 To prevent installation problem on diffe
+Line 4601 
 To prevent installation problem on diffe
  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,
+ from the Debian archive.
  The <command>apt-file</command> command may be handy for this task.  If there
  are collisions, please take action to avoid this real problem, whether by
  renaming the file, moving a common file to a separate package that
-Line 4731 
 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>
-Line 4828 
 For the <command>debuild</command> comma
+Line 4926 
 For the <command>debuild</command> comma
  $ debuild -sa
  </screen>
  <para>
- For the <command>debuild</command> command:
+ For the <command>pdebuild</command> command:
  </para>
  <screen>
  $ pdebuild --debbuildopts -sa
-Line 4860 
 For the <command>debuild</command> comma
+Line 4958 
 For the <command>debuild</command> comma
  $ debuild -v<replaceable>1.2</replaceable>
  </screen>
  <para>
- For the <command>debuild</command> command:
+ For the <command>pdebuild</command> command:
  </para>
  <screen>
  $ pdebuild --debbuildopts "-v<replaceable>1.2</replaceable>"
-Line 4983 
 changed and it already exists in the Deb
+Line 5081 
 changed and it already exists in the Deb
  </listitem>
  </itemizedlist>
  <para>
- One of the tricky case happens when you make an experimental package before
+ One tricky case can occur when you make a local package to experiment with
- uploading the normal version, e.g.,
+ the packaging before uploading  the normal version to the official archive,
+ e.g.,
  <literal><replaceable>1.0.1</replaceable>-<replaceable>1</replaceable></literal>.
- For such case, you use a version string in the Debian
+ For smoother upgrades, it is a good idea to create a
- <filename>changelog</filename> file as
+ <filename>changelog</filename> entry with a version string as
- <literal><replaceable>1.0.1</replaceable>-<replaceable>1~rc1</replaceable></literal>. See <xref linkend="namever"/> for the order of version strings.
+ <literal><replaceable>1.0.1</replaceable>-<replaceable>1~rc1</replaceable></literal>.
+ You may unclutter <filename>changelog</filename>
+ by consolidating such local change entries into a single entry for the official package.
+ See <xref linkend="namever"/> for the order of version strings.
  </para>
  <para>
  </para>
  </section>
  <section id="inspectnewupstream"><title>Inspection of the new upstream release</title>
  <para>
- When preparing packages of the a upstream release for the Debian archive, you
+ When preparing packages of a new upstream release for the Debian archive, you
  must check the new upstream release, first.
  </para>
  <para>
-Line 5194 
 Update the <filename>debian/control</fil
+Line 5296 
 Update the <filename>debian/control</fil
  If you want to update the <filename>rules</filename> file created with the
  <filename>Makefile</filename> inclusion mechanism of the Common Debian Build
  System (<systemitem role="package">cdbs</systemitem>) to the
- <command>dh</command> syntax, see
+ <command>dh</command> syntax, see the following to understand its
- <ulink url="&cdbs-doc;">cdbs-doc.pdf.gz</ulink> and understand its
+ <literal>DEB_*</literal> configuration variables.
- <literal>DEB_*</literal> configuration variables.
+ </para>
+ <itemizedlist>
+ <listitem><para>local copy of <ulink url="&cdbs-doc;">cdbs-doc.pdf.gz</ulink></para></listitem>
+ <listitem><para><ulink url="&cdbs-tutorial;">The Common Debian Build System (CDBS), FOSDEM 2009</ulink></para></listitem>
+ </itemizedlist>
  <!--
  <footnote><para> In the
  <systemitem role="package">cdbs</systemitem> (0.4.74) package, there are some
-Line 5205 
 negative descriptions of the <filename>r
+Line 5311 
 negative descriptions of the <filename>r
  only for <literal>lenny</literal> which created explicit targets with long lists
  of <command>dh_*</command> commands.  </para> </footnote>
  -->
- </para>
  </listitem>
  <listitem>
  <para>

 Legend:



Removed from v.8753
 


changed lines


 
Added in v.9044
 Legend:



Removed from v.8753
 


changed lines


 
Added in v.9044
-Removed from v.8753
+Added in v.9044

	ViewVC Help
Powered by ViewVC 1.1.5