/[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 8665 by taffit-guest,
Tue Apr 12 23:07:30 2011 UTC
+revision 8772 by osamu,
Sun May  1 05:28:31 2011 UTC
 Line 29 
 for people to check official documentati
  <title>Debian New Maintainers' Guide</title>
  <bookinfo>
  <authorgroup>
- <author> <personname> <firstname>Josip</firstname> <surname>Rodin</surname> </personname> <email>joy-mg@debian.org</email> <contrib>(original contents)</contrib> </author>
+ <!-- do not use firstname and surname tags it braks Japanese.  The same with othercredit -->
- <author> <personname> <firstname>Osamu</firstname> <surname>Aoki</surname> </personname> <email>osamu@debian.org</email> <contrib>(updated contents)</contrib> </author>
+ <author> <personname>Josip Rodin</personname> <email>joy-mg@debian.org</email> <contrib>original contents</contrib> </author>
+ <author> <personname>Osamu Aoki</personname> <email>osamu@debian.org</email> <contrib>updated contents</contrib> </author>
  <!-- translator credits in po4a/translator.*.ent -->
  &othercredit;
  </authorgroup>
-Line 66 
 The New-Maintainer's Debian Packaging Ho
+Line 67 
 The New-Maintainer's Debian Packaging Ho
  </bookinfo>
  <chapter id="start"><title>Getting started The Right Way</title>
  <para>
- This document tries to describe building of a Debian package to the common
+ This document tries to describe the building of a Debian package to ordinary
- Debian user, and the prospectus developer.  It uses pretty common language, and
+ Debian users and prospective developers.  It uses fairly non-technical language, and
- it's well covered with working examples.  There is an old Roman saying,
+ it's well covered with working examples.  There is an old Latin saying:
- <emphasis>Longum iter est per preaecepta, breve et efficax per
+ <emphasis>Longum iter est per praecepta, breve et efficax per
- exempla!</emphasis> (It's a long way by the rules, but short and efficient with
+ exempla</emphasis> (It's a long way by the rules, but short and efficient with
- examples!).
+ examples).
  </para>
  <para>
  This document has been updated for the Debian <literal>&base-release;</literal>
  release.
- <footnote><para> The document assumes you are using the
+ <footnote><para> The document assumes you are using a
- <literal>&base-release;</literal> system or newer.  If you need to follow this
+ <literal>&base-release;</literal> or newer system.  If you need to follow this
  text in an older system (including an older Ubuntu system etc.), you must
  install backported <systemitem role="package">dpkg</systemitem> and
  <systemitem role="package">debhelper</systemitem> packages, at least.
-Line 87 
 install backported <systemitem role="pac
+Line 88 
 install backported <systemitem role="pac
  One of the things that makes Debian such a top-notch distribution is its
  package system.  While there is a vast quantity of software already in the
  Debian format, sometimes you need to install software that isn't.  You may be
- wondering how you can make your own packages and perhaps you think it is a very
+ wondering how you can make your own packages; and perhaps you think it is a very
  difficult task.  Well, if you are a real novice on Linux, it is hard, but if
- you were rookie, you wouldn't be reading this doc now.  :-) You do need to know
+ you were a rookie, you wouldn't be reading this document now&nbsp;:-)
- a little about Unix programming but you certainly don't need to be a wizard.
+ You do need to know a little about Unix programming but you certainly
+ don't need to be a wizard.
  <footnote><para>
- You can learn basic operations of the Debian system from
+ You can learn about the basic handling of a Debian system from the
  <ulink url="&debref;">Debian Reference</ulink>.  It contains some pointers to
  learn about Unix programming, too.
  </para></footnote>
  </para>
  <para>
  One thing is certain, though: to properly create and maintain Debian packages
- you need many hours.  Make no mistake, for our system to work the maintainers
+ takes many hours.  Make no mistake, for our system to work the maintainers
  need to be both technically competent and diligent.
  </para>
  <para>
- This document will explain every little (at first maybe irrelevant) step, and
- help you create that first package, and to gain some experience in building
- next releases of that and maybe other packages later on.
- </para>
- <para>
  If you need some help on packaging, please read <xref linkend="helpme"/>.
  </para>
  <para>
  Newer versions of this document should always be available online at
  <ulink url="&maint-guide;"/> and in the
  <systemitem role="package">maint-guide</systemitem> package.
  The translations may be available in packages such as
  <systemitem role="package">maint-guide-es</systemitem>.
  Please note that this documentation may be slightly outdated.
  </para>
- <section id="socialdynamism"><title>Social dynamism of Debian</title>
  <para>
- Here are my observations of the social dynamism of Debian.  I hope this will prepare you for the interaction with Debian.
+ Since this is a tutorial, I choose to explain each detailed step for some
+ important topics.  Some of them may look irrelevant to you.  Please be patient.
+ I have also intentionally skipped some corner cases and provided only pointers
+ to keep this document simple.
+ </para>
+ <section id="socialdynamics"><title>Social dynamics of Debian</title>
+ <para>
+ Here are some observations of Debian's social dynamics, presented in the hope
+ that it will prepare you for interactions with Debian.
  </para>
  <itemizedlist>
  <listitem><para>We all are volunteers.</para>
      <itemizedlist>
-     <listitem><para>You can not impose others what to do.</para></listitem>
+     <listitem><para>You cannot impose on others what to do.</para></listitem>
      <listitem><para>You should be motivated to do things by yourself.</para></listitem>
      </itemizedlist></listitem>
  <listitem><para>Friendly cooperation is the driving force.</para>
-Line 136 
 Here are my observations of the social d
+Line 140 
 Here are my observations of the social d
  <listitem><para>Debian is not your school where you get automatic attention of teachers.</para>
      <itemizedlist>
      <listitem><para>You should be able to learn many things by yourself.</para></listitem>
-     <listitem><para>Attention of other volunteers is the very scarce resource.</para></listitem>
+     <listitem><para>Attention from other volunteers is a very scarce resource.</para></listitem>
      </itemizedlist></listitem>
  <listitem><para>Debian is constantly improving.</para>
      <itemizedlist>
      <listitem><para>You are expected to make high quality packages.</para></listitem>
-     <listitem><para>You should adapt yourself to the change.</para></listitem>
+     <listitem><para>You should adapt yourself to change.</para></listitem>
      </itemizedlist></listitem>
  </itemizedlist>
  <para>
- Since we focus only on technical aspects of packaging in this document,
+ There are several types of people interacting around Debian with different
- please refer to the following to learn how Debian functions and how you can get involved.
+ roles.
  </para>
  <itemizedlist>
- <listitem><para><ulink url="&logiciellibre;">Debian: 17 ans de logiciel libre,  "do-ocracy" et démocratie</ulink> (Introductory slides in English PDF) </para> </listitem>
+ <listitem>
- <listitem><para><ulink url="&debianorghelp;">How can you help Debian?</ulink> (official) </para> </listitem>
+ <para>
- <listitem><para><ulink url="&debianfaqhelp;">The Debian GNU/Linux FAQ, Chapter 13 - 'Contributing to the Debian Project'</ulink> (semi-official) </para> </listitem>
+ <emphasis role="strong">upstream author</emphasis>: the person who made the
- <listitem><para><ulink url="&debianwikihelp;">Debian Wiki, HelpDebian</ulink> (supplemental) </para> </listitem>
+ original program.
- <listitem><para><ulink url="&nm-do;">Debian New Maintainer site</ulink> (official) </para> </listitem>
+ </para>
- <listitem><para><ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> (supplemental) </para> </listitem>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong">upstream maintainer</emphasis>: the person who
+ currently maintains the program.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong">maintainer</emphasis>: the person making the Debian
+ package of the program.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong">sponsor</emphasis>: a person who helps maintainers to
+ upload packages to the official Debian package archive (after checking their
+ contents).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong">mentor</emphasis>: a person who helps novice
+ maintainers with packaging etc.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong">Debian Developer</emphasis> (DD): a member of
+ the Debian project with full upload rights to the official Debian package
+ archive.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="strong">Debian Maintainer</emphasis> (DM): a person with
+ limited upload rights to the official Debian package archive.
+ </para>
+ </listitem>
  </itemizedlist>
- </section>
- <section id="debiandeveloper"><title>Official Debian Developer</title>
  <para>
- You can not become an official
+ Please note that you cannot become an official
- <emphasis role="strong">Debian Developer</emphasis> (DD) over night because it
+ <emphasis role="strong">Debian Developer</emphasis> (DD) overnight, because it
  takes more than technical skill.  Please do not be discouraged by this.  If it
  is useful to others, you can still upload your package either as a
  <emphasis role="strong">maintainer</emphasis> through a
-Line 170 
 is useful to others, you can still uploa
+Line 210 
 is useful to others, you can still uploa
  <para>
  Please note that you do not need to create any new package to become an
  official Debian Developer.  Contributing to the existing packages can provide a
- path to become an official Debian Developer too.  There are many packages
+ path to becoming an official Debian Developer too.  There are many packages
  waiting for good maintainers (see <xref linkend="choose"/>).
  </para>
+ <para>
+ Since we focus only on technical aspects of packaging in this document,
+ please refer to the following to learn how Debian functions and how you can get involved.
+ </para>
+ <itemizedlist>
+ <listitem><para><ulink url="&logiciellibre;">Debian: 17 years of Free Software, "do-ocracy", and democracy</ulink> (Introductory slides) </para> </listitem>
+ <listitem><para><ulink url="&debianorghelp;">How can you help Debian?</ulink> (official) </para> </listitem>
+ <listitem><para><ulink url="&debianfaqhelp;">The Debian GNU/Linux FAQ, Chapter 13 - "Contributing to the Debian Project"</ulink> (semi-official) </para> </listitem>
+ <listitem><para><ulink url="&debianwikihelp;">Debian Wiki, HelpDebian</ulink> (supplemental) </para> </listitem>
+ <listitem><para><ulink url="&nm-do;">Debian New Maintainer site</ulink> (official) </para> </listitem>
+ <listitem><para><ulink url="&debianmentorfaq;">Debian Mentors FAQ</ulink> (supplemental) </para> </listitem>
+ </itemizedlist>
  </section>
- <section id="needprogs"><title>Programs you need for development</title>
+ <section id="needprogs"><title>Programs needed for development</title>
  <para>
  Before you start anything, you should make sure that you have properly
  installed some additional packages needed for development.  Note that the list
-Line 191 
 or with <literal>dpkg -s <replaceable>pa
+Line 243 
 or with <literal>dpkg -s <replaceable>pa
  <para>
  The most important package to install on your development system is the
  <systemitem role="package">build-essential</systemitem> package.  Once you try
- to install it, it will <emphasis>pull in</emphasis> other packages required to
+ to install that, it will <emphasis>pull in</emphasis> other packages required to
  have a basic build environment.
  </para>
  <para>
- For some types of packages, that is all you will require, however there is
+ For some types of packages, that is all you will require; however, there is
  another set of packages that while not essential for all package builds are
- useful to have install or may be required by your package:
+ useful to have installed or may be required by your package:
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <systemitem role="package">file</systemitem> - this handy program can determine
+ <systemitem role="package">autoconf</systemitem>, <systemitem
- what type a file is.  (see <citerefentry> <refentrytitle>file</refentrytitle>
+ role="package">automake</systemitem>, and <systemitem
- <manvolnum>1</manvolnum> </citerefentry>)
+ role="package">autotools-dev</systemitem> - many newer programs use configure
- </para>
+ scripts and <filename>Makefile</filename> files preprocessed with the help of
- </listitem>
+ programs like these (see <literal>info autoconf</literal>, <literal>info
- <listitem>
+ automake</literal>).  <systemitem role="package">autotools-dev</systemitem>
- <para>
+ keeps up-to-date versions of certain auto files and has documentation about the
- <systemitem role="package">patch</systemitem> - this very useful utility will
+ best way to use those files.
- take a file containing a difference listing (produced by the
- <command>diff</command> program) and apply it to the original file, producing a
- patched version.  (see <citerefentry> <refentrytitle>patch</refentrytitle>
- <manvolnum>1</manvolnum> </citerefentry>)
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">perl</systemitem> - Perl is one of the most used
+ <systemitem role="package">debhelper</systemitem> and
- interpreted scripting languages on today's Unix-like systems, often referred to
+ <systemitem role="package">dh-make</systemitem> -
- as Unix's Swiss Army Chainsaw.  (see <citerefentry>
+ <systemitem role="package">dh-make</systemitem> is necessary to create
- <refentrytitle>perl</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>)
+ the skeleton of our example package, and it will use some of the
+ <systemitem role="package">debhelper</systemitem> tools for creating
+ packages.  They are not essential for this purpose, but are
+ <emphasis>highly</emphasis> recommended for new maintainers.  It makes
+ the whole process very much easier to start, and to control afterwards.
+ (See <citerefentry> <refentrytitle>dh_make</refentrytitle>
+ <manvolnum>1</manvolnum> </citerefentry>, <citerefentry>
+ <refentrytitle>debhelper</refentrytitle> <manvolnum>1</manvolnum>
+ </citerefentry>.) <footnote><para> There are also some more specialized
+ but similar packages such as
+ <systemitem role="package">dh-make-perl</systemitem>,
+ <systemitem role="package">dh-make-php</systemitem>, etc.  </para>
+ </footnote>
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">python</systemitem> - Python is another of the most
+ <systemitem role="package">devscripts</systemitem> - this package contains some
- used interpreted scripting languages on the Debian system that combines
+ useful scripts that can be helpful for maintainers, but they are also
- remarkable power with very clear syntax.  (see <citerefentry>
+ not necessary for building packages.  Packages recommended and suggested
- <refentrytitle>python</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>)
+ by this package are worth looking into.  (See <ulink url="&devscripts-readme;"/>.)
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">autoconf</systemitem>, <systemitem role="package">automake</systemitem> and <systemitem role="package">autotools-dev</systemitem> - many newer programs use configure
+ <systemitem role="package">fakeroot</systemitem> - this utility lets you
- scripts and <filename>Makefile</filename> files preprocessed with help of
+ emulate being root which is necessary for some parts of the build process.
- programs like these.  (see <literal>info autoconf</literal>, <literal>info
+ (See <citerefentry> <refentrytitle>fakeroot</refentrytitle>
- automake</literal>).  The <systemitem role="package">autotools-dev</systemitem>
+ <manvolnum>1</manvolnum> </citerefentry>.)
- keeps up-to-date versions of certain auto files and has documentation about the
- best way to use those files.
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">dh-make</systemitem> and <systemitem role="package">debhelper</systemitem> - <systemitem role="package">dh-make</systemitem> is necessary to create the skeleton of our
+ <systemitem role="package">file</systemitem> - this handy program can determine
- example package, and it will use some of the <systemitem role="package">debhelper</systemitem> tools for creating packages.  They are
+ what type a file is.  (See <citerefentry> <refentrytitle>file</refentrytitle>
- not essential for creation of packages, but are <emphasis>highly</emphasis>
+ <manvolnum>1</manvolnum> </citerefentry>.)
- recommended for new maintainers.  It makes the whole process very much easier
- to start, and control afterwards.  (see <citerefentry>
- <refentrytitle>dh_make</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry>, <citerefentry> <refentrytitle>debhelper</refentrytitle>
- <manvolnum>1</manvolnum> </citerefentry>) <footnote><para> There
- are few similar but specialized packages such as <systemitem role="package">dh-make-perl</systemitem>, <systemitem role="package">dh-make-php</systemitem>, etc.  </para> </footnote>
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">devscripts</systemitem> - this package contains some
+ <systemitem role="package">gfortran</systemitem> - the GNU Fortran 95 compiler,
- nice and useful scripts that can be helpful to the maintainers, but they are
+ necessary if your program is written in Fortran.  (See <citerefentry>
- also not necessary for building packages.  Packages recommended and suggested
+ <refentrytitle>gfortran</refentrytitle> <manvolnum>1</manvolnum>
- by this package are worth looking into.  (see
+ </citerefentry>.)
- <ulink url="&devscripts-readme;"/>.)
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">fakeroot</systemitem> - this utility lets you
+ <systemitem role="package">git</systemitem> - this package provides a popular
- emulate being root which is necessary for some parts of the build process.
+ version control system designed to handle very large projects with speed and
- (see <citerefentry> <refentrytitle>fakeroot</refentrytitle>
+ efficiency; it is used for many high profile open source projects, most notably
- <manvolnum>1</manvolnum> </citerefentry>)
+ the Linux kernel.  (See <citerefentry> <refentrytitle>git</refentrytitle>
+ <manvolnum>1</manvolnum> </citerefentry>,
+ <ulink url="&git-doc;">git Manual</ulink>.)
  </para>
  </listitem>
  <listitem>
-Line 277 
 emulate being root which is necessary fo
+Line 330 
 emulate being root which is necessary fo
  <systemitem role="package">gnupg</systemitem> - a tool that enables you to
  digitally <emphasis>sign</emphasis> packages.  This is especially important if
  you want to distribute it to other people, and you will certainly be doing that
- when your work gets included in the Debian distribution.  (see <citerefentry>
+ when your work gets included in the Debian distribution.  (See <citerefentry>
- <refentrytitle>gpg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>)
+ <refentrytitle>gpg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.)
- </para>
- </listitem>
- <listitem>
- <para>
- <systemitem role="package">gfortran</systemitem> - the GNU Fortran 95 compiler,
- necessary if your program is written in Fortran.  (see <citerefentry>
- <refentrytitle>gfortran</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry>)
  </para>
  </listitem>
  <listitem>
-Line 294 
 necessary if your program is written in
+Line 339 
 necessary if your program is written in
  <systemitem role="package">gpc</systemitem> - the GNU Pascal compiler,
  necessary if your program is written in Pascal.  Worthy of note here is
  <systemitem role="package">fp-compiler</systemitem>, the Free Pascal Compiler,
- which is also good at this task.  (see <citerefentry>
+ which is also good at this task.  (See <citerefentry>
  <refentrytitle>gpc</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
- <citerefentry> <refentrytitle>ppc386</refentrytitle> <manvolnum>1</manvolnum>
+ <citerefentry> <refentrytitle>ppc386</refentrytitle>
- </citerefentry>)
+ <manvolnum>1</manvolnum> </citerefentry>.)
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">xutils-dev</systemitem> - some programs, usually
+ <systemitem role="package">lintian</systemitem> - this is the Debian package
- those made for X11, also use these programs to generate
+ checker, which can let you know of any common mistakes after you build the
- <filename>Makefile</filename> files from sets of macro functions.  (see
+ package, and explains the errors found.  (See <citerefentry>
- <citerefentry> <refentrytitle>imake</refentrytitle> <manvolnum>1</manvolnum>
+ <refentrytitle>lintian</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry>, <citerefentry> <refentrytitle>xmkmf</refentrytitle>
+ </citerefentry>,
- <manvolnum>1</manvolnum> </citerefentry>)
+ <ulink url="&lintian-doc;">Lintian User's Manual</ulink>.)
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">lintian</systemitem> - this is the Debian package
+ <systemitem role="package">patch</systemitem> - this very useful utility will
- checker that can let you know of any common mistakes after you build the
+ take a file containing a difference listing (produced by the
- package, and explains the errors found.  (see <citerefentry>
+ <command>diff</command> program) and apply it to the original file, producing a
- <refentrytitle>lintian</refentrytitle> <manvolnum>1</manvolnum>
+ patched version.  (See <citerefentry> <refentrytitle>patch</refentrytitle>
- </citerefentry>,
+ <manvolnum>1</manvolnum> </citerefentry>.)
- <ulink url="&lintian-doc;">Lintian User's Manual</ulink>)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <systemitem role="package">patchutils</systemitem> - this package contains some
+ utilities to work with patches such as the <command>lsdiff</command>,
+ <command>interdiff</command> and <command>filterdiff</command> commands.
  </para>
  </listitem>
  <listitem>
-Line 334 
 Build From Source) bugs.  (see <citerefe
+Line 385 
 Build From Source) bugs.  (see <citerefe
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">patchutils</systemitem> - this package contains some
+ <systemitem role="package">perl</systemitem> - Perl is one of the most used
- utilities to work with patches such as the <command>lsdiff</command>,
+ interpreted scripting languages on today's Unix-like systems, often referred to
- <command>interdiff</command> and <command>filterdiff</command> commands.
+ as Unix's Swiss Army Chainsaw. (See <citerefentry>
+ <refentrytitle>perl</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <systemitem role="package">python</systemitem> - Python is another of the most
+ used interpreted scripting languages on the Debian system, combining
+ remarkable power with very clear syntax. (See <citerefentry>
+ <refentrytitle>python</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.)
  </para>
  </listitem>
  <listitem>
  <para>
  <systemitem role="package">quilt</systemitem> - this package helps you to
- manage a series of patches by keeping track of the changes each of them makes.
+ manage large numbers of patches by keeping track of the changes each patch
- They are logically organized as a stack, and you can apply (=push), un-apply
+ makes. Patches can be applied, un-applied, refreshed, and more.  (See
- (=pop), refresh them easily by traveling into the stack.  (see <citerefentry>
+ <citerefentry> <refentrytitle>quilt</refentrytitle> <manvolnum>1</manvolnum></citerefentry>,
- <refentrytitle>quilt</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
+ <ulink url="&quilt-pdf;">quilt.pdf</ulink>.)
- <ulink url="&quilt-pdf;">quilt.pdf</ulink>)
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">git</systemitem> - this package provides popular
+ <systemitem role="package">xutils-dev</systemitem> - some programs, usually
- version control system designed to handle very large projects with speed and
+ those made for X11, also use these programs to generate
- efficiency; it is used for many high profile open source projects, most notably
+ <filename>Makefile</filename> files from sets of macro functions.  (See
- the Linux kernel.  (see <citerefentry> <refentrytitle>git</refentrytitle>
+ <citerefentry> <refentrytitle>imake</refentrytitle> <manvolnum>1</manvolnum>
- <manvolnum>1</manvolnum> </citerefentry>,
+ </citerefentry>, <citerefentry> <refentrytitle>xmkmf</refentrytitle>
- <ulink url="&git-doc;">git Manual</ulink>)
+ <manvolnum>1</manvolnum> </citerefentry>.)
  </para>
  </listitem>
  </itemizedlist>
  <para>
  The short descriptions that are given above only serve to introduce you to what
- each package does.  Before continuing please thoroughly read the documentation
+ each package does.  Before continuing please read the documentation
- of each program, at least, for the standard usage.  It may seem like heavy
+ of each relevant program including ones installed through the package dependency such as
+ <command>make</command>, at least, for the standard usage.  It may seem like heavy
  going now, but later on you'll be <emphasis>very</emphasis> glad you read it.
- </para>
+ If you have specific questions later, I would suggest re-reading the documents
- <para>
+ mentioned above.
- If you have specific questions later, I suggest you to read the documents
- mentioned above again.  Since this is a tutorial, I intentionally skipped
- details and provided only pointers to keep it simple.
  </para>
  </section>
- <section id="needdocs"><title>Documentations you need for development</title>
+ <section id="needdocs"><title>Documentation needed for development</title>
  <para>
  The following is the <emphasis>very important</emphasis> documentation which
  you should read along with this document:
-Line 382 
 you should read along with this document
+Line 439 
 you should read along with this document
  <para>
  <systemitem role="package">debian-policy</systemitem> - the <ulink url="&debian-policy;">Debian Policy
  Manual</ulink> includes explanations of the structure and contents of the
  Debian archive, several OS design issues, the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink>
- (FHS, which says where each file and directory should be) etc.  For you, the most
+ (FHS, which says where each file and directory should be), etc.  For you, the most
  important thing is that it describes requirements that each package must
- satisfy to be included in the distribution (see the local copies of
+ satisfy to be included in the distribution. (See the local copies of
- <ulink url="&policy-pdf;">policy.pdf</ulink> and <ulink url="&fhs-pdf;">fhs-2.3.pdf</ulink>).
+ <ulink url="&policy-pdf;">policy.pdf</ulink> and <ulink url="&fhs-pdf;">fhs-2.3.pdf</ulink>.)
  </para>
  </listitem>
  <listitem>
-Line 395 
 satisfy to be included in the distributi
+Line 452 
 satisfy to be included in the distributi
  - the <ulink url="&developers-reference;">Debian Developer's Reference</ulink>
  describes all matters not specifically about the technical
  details of packaging, like the structure of the archive, how to rename, orphan,
- pick up packages, how to do NMUs, how to manage bugs, best packaging practices,
+ or adopt packages, how to do NMUs, how to manage bugs, best packaging practices,
- when and where to upload etc.  (see the local copy of
+ when and where to upload etc.  (See the local copy of
- <ulink url="&developers-refpdf;">developers-reference.pdf</ulink>).
+ <ulink url="&developers-refpdf;">developers-reference.pdf</ulink>.)
  </para>
  </listitem>
+ </itemizedlist>
+ <para>
+ The following is the <emphasis>important</emphasis> documentation which
+ you should read along with this document:
+ </para>
+ <itemizedlist>
  <listitem>
  <para>
  <ulink url="&autotools-tutorial;">Autotools
- Tutorial</ulink> provides very good tutorial for <ulink url="&gnu-build-system;">the GNU Build System known
+ Tutorial</ulink> provides a very good tutorial for <ulink url="&gnu-build-system;">the GNU Build System known
  as the GNU Autotools</ulink> whose most important components are Autoconf,
  Automake, Libtool, and gettext.
  </para>
-Line 415 
 two pieces of documentation from the GNU
+Line 478 
 two pieces of documentation from the GNU
  <ulink url="&gnu-standard;">GNU Coding Standards</ulink>, and
  <ulink url="&gnu-maintainer;">Information for Maintainers of GNU Software</ulink>.
  Although Debian does not require these to
- be followed, these are still helpful as guidelines and common sense.  (see the local copies of
+ be followed, these are still helpful as guidelines and common sense.
+ (See the local copies of
  <ulink url="&gnu-standard-pdf;">standards.pdf</ulink> and
- <ulink url="&gnu-maintainer-pdf;">maintain.pdf</ulink>).
+ <ulink url="&gnu-maintainer-pdf;">maintain.pdf</ulink>.)
  </para>
  </listitem>
  </itemizedlist>
  <para>
- If this document contradicts with any of the documents mentioned above, they
+ If this document contradicts any of the documents mentioned above, they
  are correct.  Please file a bug report on the
  <systemitem role="package">maint-guide</systemitem> package using
  <command>reportbug</command>.
  </para>
  </section>
- <section id="terminology"><title>Basic terminology</title>
- <para>
- There are two types of packages.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="strong">source package</emphasis>: A source package is a set of
- files which contain code and data which you can compile and process into
- execution programs and formatted documents.  It usually comes as a combination
- of <filename>*.orig.tar.gz</filename>, <filename>*.debian.tar.gz</filename> (or
- <filename>*.diff.gz</filename>), and <filename>*.dsc</filename>.  Some other
- archive and compression methods may be used, too.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">binary package</emphasis>: A binary package contains
- execution programs and formatted documents.  It usually comes as
- <filename>*.deb</filename> for the normal Debian system and as
- <filename>*.udeb</filename> for the Debian Installer.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Don't mix terms like source of the program and the source package of the
- program!
- </para>
- <para>
- There are several role names used around Debian.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="strong">upstream author</emphasis>: The person who made the
- original program.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">upstream maintainer</emphasis>: The person who
- currently maintains the program.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">maintainer</emphasis>: The person who makes Debian
- package of the program.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">sponsor</emphasis>: The person who helps maintainers to
- upload packages to the official Debian Package Archive after checking their
- contents.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">mentor</emphasis>: The person who helps novice
- maintainers on packaging etc.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Debian Developer</emphasis> (DD): The person who is a
- member of Debian.  He has full upload right to the official Debian Package
- Archive.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Debian Maintainer</emphasis> (DM): The person who has
- limited upload right to the official Debian Package Archive.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- There are several version names<footnote><para>See <ulink url="&policy-control;#s-f-Version">Debian Policy  Manual: 5.6.12 Version</ulink>.</para></footnote> used around Debian.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="strong">upstream source version</emphasis>: The upstream source
- version is referred as <literal><replaceable>version</replaceable></literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Debian revision</emphasis>: The revision by Debian on
- package is referred as <literal><replaceable>revision</replaceable></literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="strong">Debian package version</emphasis>: The Debian package
- version is referred as the following.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal><replaceable>version</replaceable></literal> for the native Debian
- binary package and for the Debian source package.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>
- for the non-native Debian binary package.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
- <para>
- Please read the other manuals if you need more details on terminology.
- <footnote><para>See lists in <xref linkend="socialdynamism"/> and <xref linkend="needdocs"/>.</para></footnote>
- </para>
- </section>
  <section id="helpme"><title>Where to ask for help</title>
  <para>
  Before you decide to ask your question in some public place, please read the fine documentation.
-Line 554 
 Before you decide to ask your question i
+Line 499 
 Before you decide to ask your question i
  <itemizedlist>
  <listitem>
  <para>
- files in <filename>/usr/share/doc/dpkg</filename>
- </para>
- </listitem>
- <listitem>
- <para>
- files in <filename>/usr/share/doc/debian</filename>
- <!-- /usr/share/doc/debian is used be doc-debian and debian-faq -->
- </para>
- </listitem>
- <listitem>
- <para>
- files in <filename>/usr/share/doc/autotools-dev</filename>
- </para>
- </listitem>
- <listitem>
- <para>
  files in <filename>/usr/share/doc/<replaceable>package</replaceable></filename> for all pertinent packages
  </para>
  </listitem>
-Line 595 
 contents of <ulink url="&debian-devel-ld
+Line 524 
 contents of <ulink url="&debian-devel-ld
  </listitem>
  </itemizedlist>
  <para>
- Please consider to use web search engine effectively by including search string
+ You can use web search engines more effectively by including search strings
  such as <literal>site:lists.debian.org</literal> to limit the domain.
  </para>
  <para>
- Making a small test package is good way to learn details of packaging.
+ Making a small test package is a good way to learn details of packaging.
  Inspecting existing well maintained packages is the best way to learn how other
  people make packages.
  </para>
-Line 634 
 is time for you to dig into the
+Line 563 
 is time for you to dig into the
  <ulink url="&bts;">Debian Bug Tracking System</ulink>
  and read the documentation there, to be able to
  deal with the reports efficiently.  I highly recommend reading the
- <ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8.  'Handling bugs'</ulink>.
+ <ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8.
+ "Handling bugs"</ulink>.
  </para>
  <para>
  Even if it all worked well, it's time to start praying.  Why?  Because in just
-Line 652 
 documentation</emphasis> for details).
+Line 582 
 documentation</emphasis> for details).
  </chapter>
  <chapter id="first"><title>First steps</title>
  <para>
- Let's try to make your own package (or, better even, adopt an existing one).
+ Let's start by creating a package of your own (or, even better,
+ adopting an existing one).
+ </para>
+ <section id="workflow"><title>Debian package building workflow</title>
+ <para>
+ If you are making a Debian package with an upstream program, the
+ typical workflow of Debian package building involves generating several
+ specifically named files for each step as follows.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <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>
+ Add Debian-specific packaging modifications to the upstream program under the
+ <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 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>
+   </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ 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>
+   </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Please note that the character separating
+ <literal><replaceable>package</replaceable></literal> and
+ <literal><replaceable>version</replaceable></literal> was changed from
+ <literal>-</literal> (hyphen) in the tarball name to
+ <literal>_</literal> (underscore) in the Debian package filenames.
+ </para>
+ <para>
+ In the file names above, replace
+ the <literal><replaceable>package</replaceable></literal> part with the <emphasis role="strong">package name</emphasis>,
+ the <literal><replaceable>version</replaceable></literal> part with the <emphasis role="strong">upstream version</emphasis>,
+ the <literal><replaceable>revision</replaceable></literal> part with the <emphasis role="strong">Debian revision</emphasis>,
+ and the <literal><replaceable>arch</replaceable></literal> part with the <emphasis role="strong">package architecture</emphasis>,
+ as defined in the Debian Policy Manual.
+ <footnote> <para> See
+ <ulink url="&policy-source;">5.6.1 Source</ulink>,
+ <ulink url="&policy-package;">5.6.7 Package</ulink>, and
+ <ulink url="&policy-version;">5.6.12 Version</ulink>.
+ The <emphasis role="strong">package architecture</emphasis> follows the
+ Debian Policy Manual: <ulink url="&policy-architecture;">5.6.8 Architecture</ulink>
+ and is automatically assigned by the package build process.</para></footnote>
+ </para>
+ <para>
+ If instead you are making a Debian-specific package with no upstream, the
+ typical workflow of Debian package building is simpler.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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>
+   <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>.dsc</literal></listitem>
+   </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ 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>
+   </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Each step of this outline is explained with detailed examples in later sections.
+ </para>
+ </section>
  <section id="choose"><title>Choose your program</title>
  <para>
  You have probably chosen the package you want to create.  The first thing you
-Line 665 
 using the following.
+Line 684 
 using the following.
  <para>the <command>aptitude</command> command</para>
  </listitem>
  <listitem>
- <para><ulink url="&packages-do;">Debian packages</ulink> web page</para>
+ <para>the <ulink url="&packages-do;">Debian packages</ulink> web page</para>
  </listitem>
  <listitem>
- <para><ulink url="&packages-qa-do;">Debian Package Tracking System</ulink> web page</para>
+ <para>the <ulink url="&packages-qa-do;">Debian Package Tracking System</ulink> web page</para>
  </listitem>
  </itemizedlist>
  <para>
  If the package already exists, well, install it!  :-) If it happens to be
- <emphasis role="strong">orphaned</emphasis> -- if its maintainer is set to
+ <emphasis role="strong">orphaned</emphasis> (that is, if its
- <ulink url="&qa-do;">Debian QA Group</ulink>, you may be able to pick it up if
+ maintainer is set to <ulink url="&qa-do;">Debian QA Group</ulink>),
- it's still available.  You may also adopt a package for which the corresponding
+ you may be able to pick it up if it's still available.  You may also
- maintainer has filed a Request for Adoption
+ adopt a package whose maintainer has filed a Request for Adoption
- (<emphasis role="strong">RFA</emphasis>).
+ (<emphasis role="strong">RFA</emphasis>).<footnote> <para>See
+ <ulink url="&devref-adopt;">Debian Developer's Reference 5.9.5.
+ "Adopting a package"</ulink>.</para> </footnote>
  </para>
  <para>
  There are several package ownership status resources.
-Line 702 
 for most kinds of programs, and the numb
+Line 723 
 for most kinds of programs, and the numb
  archive is much larger than that of contributors with upload rights.  Thus,
  contributions to packages already in the archive are far more appreciated (and
  more likely to receive sponsorship) by other developers <footnote><para> Having
- said that, there will of course always be new programs that are worthwhile
+ said that, there will of course always be new programs that are worth
- packaging.  </para> </footnote>.  You can do that in various ways.
+ packaging.  </para> </footnote>.  You can contribute in various ways.
  </para>
  <itemizedlist>
  <listitem>
-Line 733 
 If you are able to adopt the package, ge
+Line 754 
 If you are able to adopt the package, ge
  examine them.  This document unfortunately doesn't include comprehensive
  information about adopting packages.  Thankfully you shouldn't have a hard time
  figuring out how the package works since someone has already done the initial
- set up for you.  Keep reading, though, a lot of the advice below will still be
+ setup for you.  Keep reading, though; a lot of the advice below will still be
  applicable for your case.
  </para>
  <para>
-Line 743 
 as follows:
+Line 764 
 as follows:
  <itemizedlist>
  <listitem>
  <para>
- First, you must know that program works, and have tried it for some time to
+ First, you must know that the program works, and have tried it for some time to
  confirm its usefulness.
  </para>
  </listitem>
  <listitem>
  <para>
- You must check if no one else is working on the package already at the
+ You must check that no one else is already working on the package on the
  <ulink url="&wnpp-do;">Work-Needing and Prospective Packages</ulink> site.
  If no one else is working on it, file an ITP (Intent
  To Package) bug report to the <systemitem role="package">wnpp</systemitem>
  pseudo-package using <command>reportbug</command>.  If someone's already on it,
  contact them if you feel you need to.  If not - find another interesting
- program that nobody maintains.
+ program that nobody is maintaining.
  </para>
  </listitem>
  <listitem>
  <para>
- That program <emphasis role="strong">must have a license</emphasis>.
+ The software <emphasis role="strong">must have a license</emphasis>.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- For the <literal>main</literal> section, it <emphasis role="strong">must be
+ For the <literal>main</literal> section, Debian Policy requires it
- compliant to all the Debian Free Software Guidelines</emphasis> (<ulink url="&dfsg;">DFSG</ulink>)
+ <emphasis role="strong">to be fully compliant with the Debian Free Software
- and <emphasis role="strong">that program must not require a package outside of
+ Guidelines</emphasis> (<ulink url="&dfsg;">DFSG</ulink>)
- <literal>main</literal></emphasis> for compilation or execution as required by
+ and <emphasis role="strong">not to require a package outside of
- the Debian Policy.  This is desired case.
+ <literal>main</literal></emphasis> for compilation or execution.  This
+ is the desired case.
  </para>
  </listitem>
  <listitem>
  <para>
- For the <literal>contrib</literal> section, it must be compliant to all the
+ For the <literal>contrib</literal> section, it must comply with the
  DFSG but it may require a package outside of <literal>main</literal> for
  compilation or execution.
  </para>
  </listitem>
  <listitem>
  <para>
- For the <literal>non-free</literal> section, it may not be compliant to some of
+ For the <literal>non-free</literal> section, it may be non-compliant
- the DFSG but it <emphasis role="strong">must be distributable</emphasis>.
+ with the DFSG but it <emphasis role="strong">must be distributable</emphasis>.
  </para>
  </listitem>
- </itemizedlist>
+ <listitem>
  <para>
- If you are unsure about where it should go, post the license text on <ulink url="&debian-legal-ldo;">debian-legal@lists.debian.org</ulink>
+ If you are unsure about where it should go, post the license text on
+ <ulink url="&debian-legal-ldo;">debian-legal@lists.debian.org</ulink>
  and ask for advice.
  </para>
  </listitem>
+ </itemizedlist>
+ </listitem>
  <listitem>
  <para>
- That program certainly should <emphasis role="strong">not</emphasis> run setuid
+ The program should <emphasis role="strong">not</emphasis> introduce security
- root, or even better - it shouldn't need to be setuid or setgid to anything.
+ and maintenance concerns to the Debian system.
  </para>
- </listitem>
+ <itemizedlist>
  <listitem>
  <para>
- That program should not be a daemon, or something that goes in
+ The program should be well documented and its code needs to be understandable
- <filename>*/sbin</filename> directories, or open a port as root.
+ (i.e.  not obfuscated).
  </para>
  </listitem>
  <listitem>
  <para>
- That program should result in binary executable form, libraries are harder to
+ You should contact the program's author(s) to check if they agree with packaging it
- handle.
+ and are amicable to Debian.  It is important to be able to consult with the author(s)
+ in case of any problems with the program, so don't try to package
+ unmaintained software.
  </para>
  </listitem>
  <listitem>
  <para>
- That program should be well documented and its code needs to be understandable
+ The program certainly should <emphasis role="strong">not</emphasis> run setuid
- (i.e.  not obfuscated).
+ root, or even better, it shouldn't need to be setuid or setgid to anything.
  </para>
  </listitem>
  <listitem>
  <para>
- You should contact program's author(s) to check if they agree with packaging it
+ The program should not be a daemon, or go in an
- and amicable to Debian.  It is important to be able to consult with author(s)
+ <filename>*/sbin</filename> directory, or open a port as root.
- about the program in case of any program specific problems, so don't try to
- package unmaintained pieces of software.
  </para>
  </listitem>
  </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Of course, the last one is just a safety measures, and intended to save you from
+ enraging users if you do something wrong in some setuid daemon...  When you gain
+ more experience in packaging, you'll be able to package such software.
+ </para>
  <para>
- Of course, these things are just safety measures, and intended to save you from
+ As a new maintainer, you are encouraged to get some experience in packaging
- raging users if you do something wrong in some setuid daemon...  When you gain
+ with easier packages and discouraged from creating complicated packages.
- some more experience in packaging, you'll be able to package such packages.
  </para>
+ <itemizedlist>
+ <listitem><para>Simple packages</para>
+ <itemizedlist>
+   <listitem><para>single binary package, arch = all (collection of data such as wallpaper graphics)</para></listitem>
+   <listitem><para>single binary package, arch = all (executables written in an interpreted language such as POSIX shell)</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>Intermediate complexity packages</para>
+ <itemizedlist>
+   <listitem><para>single binary package, arch = any (executables written in compiled languages such as C and C++)</para></listitem>
+   <listitem><para>multiple binary packages, arch = any + all (packages for executables + documentation)</para></listitem>
+   <listitem><para>upstream source in a format other than <filename>tar.gz</filename> or <filename>tar.bz2</filename></para></listitem>
+   <listitem><para>upstream source containing undistributable contents</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>High complexity packages</para>
+ <itemizedlist>
+   <listitem><para>interpreter module package used by other packages</para></listitem>
+   <listitem><para>generic library package used by other packages</para></listitem>
+   <listitem><para>multiple binary packages including a library package</para></listitem>
+   <listitem><para>source package with multiple upstream sources</para></listitem>
+   <listitem><para>kernel module packages</para></listitem>
+   <listitem><para>kernel patch packages</para></listitem>
+   <listitem><para>any package with non-trivial maintainer scripts</para></listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Packaging high complexity packages is not too hard, but it requires a bit more
+ knowledge. You should seek specific guidance for every complex feature. For
+ example, some languages have their own sub-policy documents:
+ </para>
+ <itemizedlist>
+ <listitem><para><ulink url="&policy-perl;">Perl policy</ulink></para></listitem>
+ <listitem><para><ulink url="&policy-python;">Python policy</ulink></para></listitem>
+ <listitem><para><ulink url="&policy-java;">Java policy</ulink></para></listitem>
+ </itemizedlist>
+ <para>
+ There is another old Latin saying: <emphasis>fabricando fit faber</emphasis>
+ (practice makes perfect).  It is <emphasis>highly</emphasis> recommended to
+ practice and experiment with all the steps of Debian packaging with simple packages
+ while reading this tutorial.  A trivial upstream tarball
+ <filename>hello-sh-1.0.tar.gz</filename> created as followings may offer
+ a good starting point.<footnote><para>Do not worry about the missing
+ <filename>Makefile</filename>.  You can install the <command>hello</command>
+ command by simply using <command>debhelper</command> as in
+ <xref linkend="install"/>, or by modifying the upstream source to add a new
+ <filename>Makefile</filename> with the <literal>install</literal> target as in
+ <xref linkend="modify"/>.</para></footnote>
+ </para>
+ <screen>
+ $ mkdir -p hello-sh/hello-sh-1.0; cd hello-sh/hello-sh-1.0
+ $ cat &gt; hello &lt;&lt;EOF
+ #!/bin/sh
+ # (C) 2011 Foo Bar, GPL2+
+ echo "Hello!"
+ EOF
+ $ chmod 755 hello
+ $ cd ..
+ $ tar -cvzf hello-sh-1.0.tar.gz hello-sh-1.0
+ </screen>
  </section>
  <section id="getit"><title>Get the program, and try it out</title>
  <para>
- So the first thing to do is to find and download the original source code.  I
+ So the first thing to do is to find and download the original source code.
- presume that you already have the source file that you picked up at the
+ Presumably you already have the source file that you picked up at the
  author's homepage.  Sources for free Unix programs usually come in
- <command>tar</command>+<command>gzip</command> format with extension
+ <command>tar</command>+<command>gzip</command> format with the extension
- <filename>.tar.gz</filename>, or
+ <filename>.tar.gz</filename>,
- <command>tar</command>+<command>bzip2</command> format with extension
+ <command>tar</command>+<command>bzip2</command> format with the extension
- <filename>.tar.bz2</filename>.  These usually contain the subdirectory called
+ <filename>.tar.bz2</filename>, or
- <filename><replaceable>programname</replaceable>-<replaceable>version</replaceable></filename>
+ <command>tar</command>+<command>xz</command> format with the extension
- in them and all the sources under it.
+ <filename>.tar.xz</filename>.  These usually contain a directory called
+ <filename><replaceable>package</replaceable>-<replaceable>version</replaceable></filename>
+ with all the sources inside.
  </para>
  <para>
- If the latest version of such sources are available through VCS such as Git,
+ If the latest version of the source is available through a VCS such as Git,
- Subversion, or CVS repository, you need to get it with <literal>git
+ Subversion, or CVS, you need to get it with <literal>git
  clone</literal>, <literal>svn co</literal>, or <literal>cvs co</literal> and
- repack it into <command>tar</command>+<command>gzip</command> format by
+ repack it into <command>tar</command>+<command>gzip</command> format yourself
- yourself using the <literal>--exclude-vcs</literal> option.
+ by using the <literal>--exclude-vcs</literal> option.
  </para>
  <para>
  If your program's source comes as some other sort of archive (for instance, the
  filename ends in <filename>.Z</filename> or
  <filename>.zip</filename><footnote><para> You can identify the archive format
  using the <command>file</command> command when the file extension is not
- enough.  </para> </footnote>), unpack it with appropriate tools and repack it,
+ enough.  </para> </footnote>), you should also unpack it with the
- too.
+ appropriate tools and repack it.
  </para>
  <para>
- As an example, I'll use a program called <command>gentoo</command>, an X GTK+
+ 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 containg <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. Its
+ <footnote><para> This program is already packaged. The
  <ulink url="&gentoo-package;">current version</ulink> uses Autotools as its
- build structure and is substantially different from the following examples
+ build structure and is substantially different from the following examples,
- based on the version 0.9.12.</para>
+ which were based on version 0.9.12.</para>
  </footnote>
  </para>
  <para>
-Line 871 
 Create a subdirectory under your home di
+Line 970 
 Create a subdirectory under your home di
  <filename>debian</filename> or <filename>deb</filename> or anything you find
  appropriate (e.g.  just <filename>~/gentoo</filename> would do fine in this
  case).  Place the downloaded archive in it, and extract it (with <literal>tar
- xzf gentoo-0.9.12.tar.gz</literal>).  Make sure there are no errors, even some
+ xzf gentoo-0.9.12.tar.gz</literal>).  Make sure there are no warning
- <emphasis>irrelevant</emphasis> ones, because there will most probably be
+ messages, even <emphasis>irrelevant</emphasis> ones, because other
- problems unpacking on other people's systems, whose unpacking tools may or may
+ people's unpacking tools may or may not ignore these anomalies, so they
- not ignore those anomalies.  On your console screen, you should see the
+ may have problems unpacking them.  Your shell command line may look
- following.
+ something like this:
  </para>
  <screen>
  $ mkdir ~/gentoo ; cd ~/gentoo
-Line 890 
 Now you have another subdirectory, calle
+Line 989 
 Now you have another subdirectory, calle
  Change to that directory and <emphasis>thoroughly</emphasis> read the provided
  documentation.  Usually there are files named <filename>README*</filename>,
  <filename>INSTALL*</filename>, <filename>*.lsm</filename> or
- <filename>*.html</filename>.  You must find instructions on how to correctly
+ <filename>*.html</filename>.  You must find instructions on how to
  compile and install the program (most probably they'll assume you want to
- install to <filename>/usr/local/bin</filename> directory; you won't be doing
+ install to the <filename>/usr/local/bin</filename> directory; you won't be doing
  that, but more on that later in <xref linkend="destdir"/>).
  </para>
  <para>
- Simple programs come with a <filename>Makefile</filename> file in them and can
+ You should start packaging with a completely clean (pristine) source directory,
- be compiled simply with <literal>make</literal>.<footnote><para>
+ or simply with freshly unpacked sources.
+ </para>
+ </section>
+ <section id="simplemake"><title>Simple build systems</title>
+ <para>
+ Simple programs usually come with a <filename>Makefile</filename> and can
+ be compiled just by invoking <literal>make</literal>.<footnote><para>
  Many modern programs come with a script <filename>configure</filename> which
- creates a <filename>Makefile</filename> file customized for your system upon
+ when executed creates a <filename>Makefile</filename> customized for
- its execution.</para></footnote> Some of them support
+ your system.</para></footnote> Some of them support
- <literal>make check</literal>, which runs included self-checks.  Installation
+ <literal>make check</literal>, which runs included self-tests.  Installation
  to the destination directories is usually done with <literal>make
  install</literal>.
  </para>
-Line 916 
 there's even a <literal>make uninstall</
+Line 1021 
 there's even a <literal>make uninstall</
  all the installed files.
  </para>
  </section>
- <section id="portable"><title>Free portable programs</title>
+ <section id="portable"><title>Popular portable build systems</title>
  <para>
- A lot of Free programs are written in the <ulink url="&c-program;">C</ulink> and
+ A lot of free software programs are written in the <ulink url="&c-program;">C</ulink> and
- <ulink url="&cxx;">C++</ulink> languages.  Many of
+ <ulink url="&cxx;">C++</ulink> languages.  Many of these use Autotools or
- these use Autotools or CMake to make them portable across different platforms.
+ CMake to make them portable across different platforms.  These build tools need
- These tools are used to generate <filename>Makefile</filename> and other
+ to be used to generate the <filename>Makefile</filename> and other
- required source files.  Then, such programs are built with usual <literal>make;
+ required source files first.  Then, such programs are built using the usual
- make install</literal>.
+ <literal>make; make install</literal>.
  </para>
  <para>
- <ulink url="&gnu-build-system;">Autotools</ulink>
+ <ulink url="&gnu-build-system;">Autotools</ulink> is the GNU build
- are the GNU build system comprising <ulink url="&autoconf;">Autoconf</ulink>, <ulink url="&automake;">Automake</ulink>, <ulink url="&libtool;">Libtool</ulink>, and <ulink url="&gettext;">gettext</ulink>.  You can notice
+ system comprising <ulink url="&autoconf;">Autoconf</ulink>,
+ <ulink url="&automake;">Automake</ulink>,
+ <ulink url="&libtool;">Libtool</ulink>, and
+ <ulink url="&gettext;">gettext</ulink>.  You can recognize
  such sources by the <filename>configure.ac</filename>,
  <filename>Makefile.am</filename>, and <filename>Makefile.in</filename> files.
- <footnote><para> See <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink>
+ <footnote><para>Autotools is too big to deal in this small tutorial. This
- and <ulink url="&autotools-readme;"/>.  </para> </footnote>
+ section is meant to provide keywords and references only.  Please make sure to read the
+ <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink> and
+ <ulink url="&autotools-readme;"/>, if you need to use it.</para></footnote>
  </para>
  <para>
- The first step of Autotools work flow is usually that the upstream runs
+ The first step of the Autotools workflow is usually that upstream runs
- <literal>autoreconf -i -f</literal> in the source and distributes this source
+ <literal>autoreconf -i -f</literal> in the source directory and
- with generated files.
+ distributes the generated files along with the source.
  </para>
  <screen>
  configure.ac-----+-&gt; autoreconf -+-&gt; configure
-Line 955 
 files requires some knowledge of <comman
+Line 1065 
 files requires some knowledge of <comman
  <literal>info automake</literal>.
  </para>
  <para>
- The second step of Autotools work flow is usually that the user obtains this
+ 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 to compile program into a
+ the source directory to compile the program into a
- <command><replaceable>binary</replaceable></command>.
+ <command><replaceable>binary</replaceable></command> executable.
  </para>
  <screen>
  Makefile.in -----+                +-&gt; Makefile -----+-&gt; make -&gt; <replaceable>binary</replaceable>
-Line 969 
 config.h.in -----+                +-&gt;
+Line 1079 
 config.h.in -----+                +-&gt;
             config.guess --+
  </screen>
  <para>
- You can change many things in the <filename>Makefile</filename> file such as
+ You can change many things in the <filename>Makefile</filename>; for
- the default file install location using the command option, e.g.
+ instance you can change the default location for file installation
- <command>./configure --prefix=/usr</command>.
+ using the option <command>./configure --prefix=/usr</command>.
  </para>
  <para>
  Although it is not required, updating the <filename>configure</filename> and
- other files with <literal>autoreconf -i -f</literal> as the user may improve
+ other files with <literal>autoreconf -i -f</literal> may improve
  the compatibility of the source.
  <footnote><para>You can automate this by using
  <systemitem role="package">dh-autoreconf</systemitem> package.
-Line 983 
 See <xref linkend="customrules"/>.</para
+Line 1093 
 See <xref linkend="customrules"/>.</para
  </para>
  <para>
  <ulink url="&cmake;">CMake</ulink> is an alternative
- build system.  You can notice such sources by the
+ build system.  You can recognize such sources by the
  <filename>CMakeLists.txt</filename> file.
  </para>
  </section>
  <section id="namever"><title>Package name and version</title>
  <para>
- You should start packaging with a completely clean (pristine) source directory,
+ If the upstream source comes as <filename>gentoo-0.9.12.tar.gz</filename>, you can
- or simply with freshly unpacked sources.
+ take <literal>gentoo</literal> as the (source) <emphasis role="strong">package name</emphasis>
+ and <literal>0.9.12</literal> as the <emphasis role="strong">upstream version</emphasis>.
+ These are used in the <filename>debian/changelog</filename> file described later in
+ <xref linkend="changelog"/>, too.
+ </para>
+ <para>
+ Although this simple approach works most of the times, you may need to adjust
+ <emphasis role="strong">package name</emphasis> and
+ <emphasis role="strong">upstream version</emphasis> by renaming the upstream
+ source to follow Debian Policy and existing convention.
+ </para>
+ <para>
+ You must choose the <emphasis role="strong">package name</emphasis>
+ to consist only of lower case letters (<literal>a-z</literal>), digits
+ (<literal>0-9</literal>), plus (<literal>+</literal>) and minus
+ (<literal>-</literal>) signs, and periods (<literal>.</literal>). It must be
+ at least two characters long, must start with an alphanumeric character, and
+ must not be the same as existing ones.
+ It is a good idea to keep its length within 30 characters.
+ <footnote><para>The default package name field length of <command>aptitude</command> is 30.  For more than 90% of packages, the package name is less than 24 characters.</para></footnote>
+ </para>
+ <!--
+ Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
+ === stat for package name string length ===
+1947 36.9%   mode
+1717 54.7%  50% median
+611 91.0%   90%
+89 99.0%    99%
+12 99.9%    99.9%
+1 100.0%
+ Previous 20 chars is becoming too short for 17% of packages
+ Default aptitude setting display up to 30 chars (98.3%).
+ -->
+ <para>
+ If upstream uses some generic term such as <literal>test-suite</literal> for
+ its name, it is a good idea to rename it to identify its contents explicitly and avoid namespace pollution.
+ <footnote><para>If you follow the
+ <ulink url="&devref-newpackage;">Debian Developer's Reference 5.1. "New packages"</ulink>,
+ the ITP process will usually catch this kind of issues.</para></footnote>
+ </para>
+ <para>
+ You should choose the <emphasis role="strong">upstream version</emphasis>
+ to consist only of
+ alphanumerics (<literal>0-9A-Za-z</literal>), plus (<literal>+</literal>),
+ tildes (<literal>~</literal>), and periods (<literal>.</literal>). It must
+ start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter
+ rule should help you avoid confusing file names.</para></footnote>
+ It is good idea to keep its length within 8 characters if possible.
+ <footnote><para>The default version field length of <command>aptitude</command> is 10.  The Debian revision with preceding hyphen usually consumes 2.  For more than 80% of packages, the upstream version is less than 8 characters and the Debian revision is less than 2 characters.  For more than 90% of packages, the upstream version is less than 10 characters and the Debian revision is less than 3 characters.</para></footnote>
+ </para>
+ <!--
+ Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
+ === stat for upstream version string length ===
+9765 60.2%  50% median and mode
+3765 73.3%
+2789 82.9%
+1158 86.9%
+501 88.6%
+773 91.3%  90%
+55 99.1%   99%
+11 99.9%    99.9
+6 100.0%
+ === stat for debian revision string length ===
+22556 83.3%  50% median and mode
+1106 87.2%
+1312 91.7%   90%
+2127 99.1%   99%
+14 99.9%     99.9%
+ aptitude display 10 = 8char for up + 1char (for -) + 1char for deb
+chars as max for file name of binary debs (package+up+deb+arch+.deb)
+ -->
+ <para>
+ 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 part
+ 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> interprets later versions correctly as upgrades.
+ </para>
+ <para>
+ Version strings <footnote><para>Version strings may be
+ <emphasis role="strong">upstream version</emphasis>
+ (<literal><replaceable>version</replaceable></literal>),
+ <emphasis role="strong">Debian revision</emphasis>
+ (<literal><replaceable>revision</replaceable></literal>), or
+ <emphasis role="strong">version</emphasis>
+ (<literal><replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>).
+ See <xref linkend="newrevision"/> for how the
+ <emphasis role="strong">Debian revision</emphasis> is incremented.
+ </para></footnote>
+ 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:
+ </para>
+ <itemizedlist>
+ <listitem><para>Strings are compared from the head to the tail.</para></listitem>
+ <listitem><para>Letters are larger than digits.</para></listitem>
+ <listitem><para>Numbers are compared as integers.</para></listitem>
+ <listitem><para>Letters are compared in ASCII code order.</para></listitem>
+ <listitem><para>There are special rules for period
+ (<literal>.</literal>), plus (<literal>+</literal>), and tilde
+ (<literal>~</literal>) characters, as follows.</para>
+   <para>
+   <literal>0.0</literal> &lt;
+   <literal>0.5</literal> &lt;
+   <literal>0.10</literal> &lt;
+   <literal>0.99</literal> &lt;
+   <literal>1</literal> &lt;
+   <literal>1.0~rc1</literal> &lt;
+   <literal>1.0</literal> &lt;
+   <literal>1.0+b1</literal> &lt;
+   <literal>1.0+nmu1</literal> &lt;
+   <literal>1.1</literal> &lt;
+   <literal>2.0</literal>
+   </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ One tricky case occurs when upstream releases
+ <filename>gentoo-0.9.12-ReleaseCandidate-99.tar.gz</filename> as the
+ pre-release of <filename>gentoo-0.9.12.tar.gz</filename>.  You need to make
+ sure that the upgrade works properly by renaming the upstream source to
+ <filename>gentoo-0.9.12~rc99.tar.gz</filename>.
  </para>
+ </section>
+ <section id="dh-make"><title>Setting up <command>dh_make</command></title>
  <para>
- For the package to be built correctly, you must make the program's original
+ Set up the shell environment variables <literal>$DEBEMAIL</literal> and
- name lowercase (if it isn't already), and you should move the source directory
+ <literal>$DEBFULLNAME</literal> so that various Debian maintenance
- to
+ tools recognize your email address and name to use for packages. <footnote><para> The
- <filename><replaceable>packagename</replaceable>-<replaceable>version</replaceable></filename>.
- </para>
- <para>
- If the program name consists of more than one word, contract them to one word,
- or make an abbreviation.  For example, program John's little editor for X
- package would be named <systemitem role="package">johnledx</systemitem>, or
- <systemitem role="package">jle4x</systemitem>, or whatever you decide, as long
- as it's under some reasonable limit, e.g.  20 characters.
- </para>
- <para>
- Also check for the exact version of the program (to be included in the package
- version).  If that piece of software is not numbered with versions like
- <literal>X.Y.Z</literal>, but with some kind of date, feel free to use that
- date as the version number, as long as newer version numbers will look larger.
- While it is best to use the same version number as what upstream uses, if it is
- in the format of <literal>09Oct23</literal> you may need to convert it to
- <literal>YYYYMMDD</literal> format, which would be <literal>20091023</literal>,
- to ensure proper order for upgrade with the <command>dpkg</command>
- program.<footnote><para> Version string can be compared by <literal>dpkg
- --compare-versions <replaceable>ver1</replaceable>
- <replaceable>op</replaceable> <replaceable>ver2</replaceable></literal>.  See
- <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> manpage.  </para> </footnote>
- </para>
- <para>
- Some programs won't be numbered at all, in which case you should contact the
- upstream maintainer to see if they've got some other revision-tracking method.
- </para>
- </section>
- <section id="dh-make"><title>Initial Debian package</title>
- <para>
- Let's set up the shell environment variable <literal>$DEBEMAIL</literal> and
- <literal>$DEBFULLNAME</literal> so many Debian maintenance tools recognize your
- name and email address to use for packages as follows.<footnote><para> The
  following text assumes you are using Bash as your login shell.  If you use
- other login shells such as Z shell, use their pertinent configuration files
+ some other login shell such as Z shell, use their corresponding
- instead of <filename>~/.bashrc</filename>.  </para> </footnote>.
+ configuration files instead of <filename>~/.bashrc</filename>. </para> </footnote>
  </para>
  <screen>
  $ cat &gt;&gt;~/.bashrc &lt;&lt;EOF
-Line 1040 
 DEBEMAIL=your.email.address@example.org
+Line 1249 
 DEBEMAIL=your.email.address@example.org
  DEBFULLNAME=Firstname Lastname
  export DEBEMAIL DEBFULLNAME
  EOF
+ $ . ~/.bashrc
  </screen>
+ </section>
+ <section id="non-native-dh-make"><title>Initial non-native Debian package</title>
  <para>
- Let's make an initial Debian package by issuing the <command>dh_make</command>
+ Normal Debian packages are non-native Debian packages made from upstream
+ programs.  If you wish to create a non-native Debian package of an upstream
+ source <filename>gentoo-0.9.12.tar.gz</filename>, you can create an initial
+ non-native Debian package for it by issuing the <command>dh_make</command>
  command as follows.
  </para>
  <screen>
- $ . ~/.bashrc
+ $ cd ~/gentoo
- $ cd ~/gentoo/gentoo-0.9.12
+ $ wget http://example.org/gentoo-0.9.12.tar.gz
+ $ tar -xvzf gentoo-0.9.12.tar.gz
+ $ cd gentoo-0.9.12
  $ dh_make -f ../gentoo-0.9.12.tar.gz
  </screen>
  <para>
  Of course, replace the filename with the name of your original source archive.
  <footnote><para> If the upstream source provides the
  <filename>debian</filename> directory and its contents, run the
- <command>dh_make</command> command with the <literal>--addmissing</literal>
+ <command>dh_make</command> command with the extra option
- option, instead.  The new source <literal>3.0 (quilt)</literal> format is quite
+ <literal>--addmissing</literal>.  The new source <literal>3.0 (quilt)</literal> format is
- robust not to break even for these packages.  You may need to update contents
+ robust enough not to break even for these packages.  You may need to update the contents
  provided by the upstream for your Debian package.  </para> </footnote> See
  <citerefentry> <refentrytitle>dh_make</refentrytitle> <manvolnum>1</manvolnum>
  </citerefentry> for details.
  </para>
  <para>
- Some information will come up.  It will ask you what sort of package you want
+ You should see some output asking you what sort of package you want
- to create.  Gentoo is a single binary package - it creates only one binary, and
+ to create.  Gentoo is a single binary package - it creates only one binary package, i.e,
- thus one <filename>.deb</filename> file - so we will select the first option,
+ one <filename>.deb</filename> file - so we will select the first option
- with the <literal>s</literal> key, check the information on the screen and
+ (with the <literal>s</literal> key), check the information on the screen, and
  confirm by pressing <literal><replaceable>ENTER</replaceable></literal>.
- <footnote><para> There are few choices here: <literal>s</literal> for Single
+ <footnote><para> There are several choices here: <literal>s</literal> for
- binary, <literal>i</literal> for Arch-Independent, <literal>m</literal> for
+ Single binary package, <literal>i</literal> for arch-Independent package, <literal>m</literal> for
- Multiple binary, <literal>l</literal> for Library, <literal>k</literal> for
+ Multiple binary packages, <literal>l</literal> for Library package, <literal>k</literal> for
- Kernel module, <literal>n</literal> for Kernel patch and <literal>b</literal>
+ Kernel module package, <literal>n</literal> for kernel patch package, and <literal>b</literal>
- for <systemitem role="package">cdbs</systemitem>.  This document focuses on the
+ for <systemitem role="package">cdbs</systemitem> package.  This document focuses on the
- use of the <systemitem role="package">debhelper</systemitem> package with the
+ use of the <command>dh</command> command (from the package
- <command>dh</command> command.  This document focuses on the use of the new
+ <systemitem role="package">debhelper</systemitem>) to create a single binary package,
- <command>dh</command> command for Single binary and touches on it for
+ but also touches on how to use it for arch-independent or
- Arch-Independent and Multiple binary.  The <systemitem role="package">cdbs</systemitem> package offers alternative package script
+ multiple binary packages.  The package
- infrastructure to the <command>dh</command> command and outside of the scope of
+ <systemitem role="package">cdbs</systemitem> offers an alternative packaging script
+ infrastructure to the <command>dh</command> command and is outside the scope of
  this document.  </para> </footnote>
  </para>
  <para>
- After this execution of <command>dh_make</command>, a copy of the upstream
+ This execution of <command>dh_make</command> creates a copy of the upstream
- tarball is created as <filename>gentoo_0.9.12.orig.tar.gz</filename> in the
+ tarball as <filename>gentoo_0.9.12.orig.tar.gz</filename> in the
  parent directory to accommodate the creation of the non-native Debian source
- package with the <filename>debian.tar.gz</filename> later.
+ package with the name <filename>debian.tar.gz</filename> later.
  </para>
  <screen>
  $ cd ~/gentoo ; ls -F
-Line 1092 
 gentoo-0.9.12.tar.gz
+Line 1310 
 gentoo-0.9.12.tar.gz
  gentoo_0.9.12.orig.tar.gz
  </screen>
  <para>
- Please note 2 key features in this
+ Please note two key features of this filename
- <filename>gentoo_0.9.12.orig.tar.gz</filename> file name:
+ <filename>gentoo_0.9.12.orig.tar.gz</filename>:
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Package name and version are separated by the <literal>_</literal>
+ Package name and version are separated by the character <literal>_</literal>
  (underscore).
  </para>
  </listitem>
  <listitem>
  <para>
- There is the <filename>.orig</filename> before the
+ The string <filename>.orig</filename> is inserted before the
  <filename>.tar.gz</filename>.
  </para>
  </listitem>
  </itemizedlist>
  <para>
  You should also notice that many template files are created in the source under
- the <filename>debian</filename> directory.  These will be explained in <xref linkend="dreq"/> and <xref linkend="dother"/>.  You should also understand
+ the <filename>debian</filename> directory.  These will be explained in
- that the packaging is not automatic process.  You need to modify the upstream
+ <xref linkend="dreq"/> and <xref linkend="dother"/>.  You should also understand
- source for Debian as <xref linkend="modify"/>.  After all these, you need to
+ that packaging cannot be a fully automated process.  You will need to modify the upstream
- build Debian packages under the proper method as <xref linkend="build"/>,
+ source for Debian (see <xref linkend="modify"/>).  After this, you need to
- check them as <xref linkend="checkit"/>, and upload them as <xref linkend="upload"/>.  I will explain all these steps.
+ use the proper methods for building Debian packages (<xref linkend="build"/>),
+ testing them (<xref linkend="checkit"/>), and uploading them (<xref linkend="upload"/>).
+ All the steps will be explained.
  </para>
  <para>
- Once again, as a new maintainer you are discouraged from creating complicated
+ If you accidentally erased some template files while working on them, you can
- packages, e.g.,
+ recover them by running <command>dh_make</command> with the
- </para>
+ <literal>--addmissing</literal> option again in a Debian package source tree.
- <itemizedlist>
- <listitem>
- <para>
- multiple binary packages,
- </para>
- </listitem>
- <listitem>
- <para>
- library packages,
- </para>
- </listitem>
- <listitem>
- <para>
- kernel module packages,
- </para>
- </listitem>
- <listitem>
- <para>
- kernel patch packages,
- </para>
- </listitem>
- <listitem>
- <para>
- the source file format being neither in <filename>tar.gz</filename> nor
- <filename>tar.bz2</filename>, or
  </para>
- </listitem>
- <listitem>
  <para>
- the source tarball containing undistributable contents.
+ Updating an existing package may get complicated since it may be using older
+ techniques.  While learning the basics, please stick to creating a fresh
+ package; further explanations are given in <xref linkend="update"/>.
  </para>
- </listitem>
- </itemizedlist>
  <para>
- It's not too hard, but it does require a bit more knowledge, so we won't
+ Please note that the source file does not need to contain any build system
- describe all of it here.
+ discussed in <xref linkend="simplemake"/> and <xref linkend="portable"/>.  It
+ could be just a collection of graphical data etc.  Installation of files may be
+ carried out using only <systemitem role="package">debhelper</systemitem> configuration
+ files such as <filename>debian/install</filename> (see
+ <xref linkend="install"/>).
  </para>
+ </section>
+ <section id="native-dh-make"><title>Initial native Debian package</title>
  <para>
- If you accidentally erased some template files while working on them, you can
+ If a package contains source files you are only maintaining for Debian,
- recover them by running <command>dh_make</command> with the
+ possibly only for local use, it may be simpler to create it as a Debian
- <literal>--addmissing</literal> option again in a Debian package source tree.
+ native package. If you have source
+ files in <filename>~/mypackage-1.0</filename>, you can create an initial native
+ Debian package for it by issuing the <command>dh_make</command> command as
+ follows.
  </para>
+ <screen>
+ $ cd ~/mypackage-1.0
+ $ dh_make --native
+ </screen>
  <para>
- Updating an existing package may get complicated since it may be using older
+ Then the <filename>debian</filename> directory and its contents are created
- techniques.  Please stick with fresh packaging cases for now to learn basics.
+ just like <xref linkend="non-native-dh-make"/>.  This does not create a tarball
- I will come back to explain it later in <xref linkend="update"/>.
+ since this is a native Debian package.  But that is the only difference.
+ The rest of the packaging activities are practically the same.
  </para>
  </section>
  </chapter>
-Line 1176 
 Please note that there isn't space here
+Line 1383 
 Please note that there isn't space here
  details of fixing upstream sources, but here are some basic steps and problems
  people often run across.
  </para>
- <section id="quiltrc"><title>Set up <command>quilt</command></title>
+ <section id="quiltrc"><title>Setting up <command>quilt</command></title>
  <para>
- The <command>quilt</command> program offers the basic method to record
+ The program <command>quilt</command> offers a basic method for recording
- modification to the source for the Debian packaging.  Since slightly different
+ modifications to the upstream source for Debian packaging.  It's
- default is desirable, let's create an alias <command>dquilt</command> for
+ useful to have a slightly customized default, so let's create an alias
- Debian packaging by adding the following line to <filename>~/.bashrc</filename>.
+ <command>dquilt</command> for Debian packaging by adding the following
+ line to <filename>~/.bashrc</filename>.
  </para>
  <screen>
- alias dquilt=quilt --quiltrc=~/.quiltrc-dpkg
+ alias dquilt="quilt --quiltrc=~/.quiltrc-dpkg"
  </screen>
  <para>
  Then let's create <filename>~/.quiltrc-dpkg</filename> as follows.
-Line 1192 
 Then let's create <filename>~/.quiltrc-d
+Line 1400 
 Then let's create <filename>~/.quiltrc-d
  <screen>
  d=. ; while [ ! -d $d/debian -a `readlink -e $d` != / ]; do d=$d/..; done
  if [ -d $d/debian ] &amp;&amp; [ -z $QUILT_PATCHES ]; then
-     # Debian packaging case and unset $QUILT_PATCHES
+     # if in Debian packaging tree with unset $QUILT_PATCHES
      QUILT_PATCHES="debian/patches"
      QUILT_PATCH_OPTS="--reject-format=unified"
      QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
-Line 1204 
 fi
+Line 1412 
 fi
  <para>
  See <citerefentry> <refentrytitle>quilt</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> and
- <ulink url="&quilt-pdf;">quilt.pdf</ulink> for how to use
+ <ulink url="&quilt-pdf;">quilt.pdf</ulink> on how to use
  <command>quilt</command>.
  </para>
  </section>
- <section id="fixupstream"><title>Fixing upstream bug</title>
+ <section id="fixupstream"><title>Fixing upstream bugs</title>
  <para>
  Let's assume you find an error in the upstream <filename>Makefile</filename>
- file as follows where <literal>install: gentoo</literal> should have been
+ as follows where <literal>install: gentoo</literal> should have been
  <literal>install: gentoo-target</literal>.
  </para>
  <screen>
-Line 1221 
 install: gentoo
+Line 1429 
 install: gentoo
          install gentoorc-example $(HOME)/.gentoorc
  </screen>
  <para>
- Let's fix this and record this with the <command>dquilt</command> command as
+ Let's fix this and record it with the <command>dquilt</command> command as
  <filename>fix-gentoo-target.patch</filename>.  <footnote><para> The
- <filename>debian/patches</filename> directory should exist now if you run
+ <filename>debian/patches</filename> directory should exist now if you ran
  <command>dh_make</command> as described before.  This example operation creates
- it just in case you are updating the existing package.  </para> </footnote>
+ it just in case you are updating an existing package.  </para> </footnote>
  </para>
  <screen>
  $ mkdir debian/patches
-Line 1242 
 install: gentoo-target
+Line 1450 
 install: gentoo-target
          install gentoorc-example $(HOME)/.gentoorc
  </screen>
  <para>
- Ask <command>dquilt</command> to refresh the patch to create
+ Ask <command>dquilt</command> to generate the patch to create
  <filename>debian/patches/fix-gentoo-target.patch</filename> and add its
  description following <ulink url="&dep3;">DEP-3: Patch Tagging Guidelines</ulink>.
  </para>
-Line 1252 
 $ dquilt header -e
+Line 1460 
 $ dquilt header -e
  ... describe patch
  </screen>
  </section>
+ <section id="destdir"><title>Installation of files to their destination</title>
- <section id="destdir"><title>Installation of files to the destination</title>
  <para>
- Normally, programs install themselves in the <filename>/usr/local</filename>
+ Most third-party software installs itself in the <filename>/usr/local</filename>
- subdirectory.  Since it is reserved for system administrator's (or user's)
+ directory hierarchy.  On Debian this is reserved for private use
- private use, Debian packages must not use that directory but should use system
+ by the system administrator, so packages must not use directories such
- directories such as the <filename>/usr/bin</filename> subdirectory following
+ as <filename>/usr/local/bin</filename> but should instead use system
- the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink> (FHS).
+ directories such as <filename>/usr/bin</filename>, obeying the
+ <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink> (FHS).
  </para>
  <para>
  Normally, <citerefentry> <refentrytitle>make</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> is used to automate building the
- program and the execution of <literal>make install</literal> installs programs
+ program, and executing <literal>make install</literal> installs programs
- directly to the desired destination by the <literal>install</literal> target of
+ directly to the desired destination (following the
- the <filename>Makefile</filename> file.  In order for Debian to provide binary
+ <literal>install</literal> target in the
- packages, the build system installs programs to the file tree image created
+ <filename>Makefile</filename>).  In order for Debian to provide
- under a temporary directory instead to the actual destination.
+ pre-built installable packages, it modifies the build system to install
+ programs into a file tree image created under a temporary directory
+ instead of the actual destination.
  </para>
  <para>
- These 2 differences between (1) the normal program installation and (2) the
+ These two differences between normal program installation on one hand and the
- Debian packaging can be transparently addressed by the <systemitem role="package">debhelper</systemitem> package through the
+ Debian packaging system on the other can be transparently addressed by the
+ <systemitem role="package">debhelper</systemitem> package through the
  <command>dh_auto_configure</command> and <command>dh_auto_install</command>
  commands if the following conditions are met.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- The <filename>Makefile</filename> file follows the GNU conventions to support
+ The <filename>Makefile</filename> must follow GNU conventions and
- <literal>$(DESTDIR)</literal> variable.
+ support the <literal>$(DESTDIR)</literal> variable.
  <footnote><para> See <ulink url="&gnu-destdir;">GNU Coding Standards: 7.2.4 DESTDIR: Support for Staged Installs</ulink>.</para></footnote>
  </para>
  </listitem>
  <listitem>
  <para>
- The source follows the Filesystem Hierarchy Standard (FHS).
+ The source must follow the Filesystem Hierarchy Standard (FHS).
  </para>
  </listitem>
  </itemizedlist>
  <para>
- Programs that use GNU <command>autoconf</command>
+ Programs that use GNU <command>autoconf</command> follow the GNU conventions
- <emphasis>automatically</emphasis> follow the GNU conventions and their
+ automatically, so they can be trivial to package.  On the basis of
- packaging is almost <emphasis>automatic</emphasis>.  With this and other
+ this and other heuristics, it is estimated that the
- heuristics, the <systemitem role="package">debhelper</systemitem> package
+ <systemitem role="package">debhelper</systemitem> package will work for
- estimates that it works for about 90% of packages without making any intrusive
+ about 90% of packages without making any intrusive changes to their
- changes to their build system.  So the packaging is not as complicated as it
+ build system.  So packaging is not as complicated as it may seem.
- may seem.
  </para>
  <para>
- If you need to make changes in the <filename>Makefile</filename> file, you
+ If you need to make changes in the <filename>Makefile</filename>, you
- should make sure to support these <literal>$(DESTDIR)</literal> variable.  The
+ should be careful to support the <literal>$(DESTDIR)</literal>
- <literal>$(DESTDIR)</literal> variable is unset in it and is prepended to each
+ variable.  Although it is unset by default, the <literal>$(DESTDIR)</literal>
- file path used for the program installation.  The packaging script will set
+ variable is prepended to each file path used for the program
- <literal>$(DESTDIR)</literal> to the temporary directory.
+ installation.  The packaging script will set
+ <literal>$(DESTDIR)</literal> to the temporary directory.
  </para>
  <para>
- The temporary directory used by the <command>dh_auto_install</command> command
+ For packages of the single binary type, the temporary directory used
- is chosen as <filename>debian/<replaceable>package</replaceable></filename> for
+ by the <command>dh_auto_install</command> command will be set to
- single binary packages.  <footnote><para> For multiple binary packages, the
+ <filename>debian/<replaceable>package</replaceable></filename>.
+ <footnote><para> For packages of the multiple binary type, 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
  <filename>debian/<replaceable>package-1</replaceable>.install</filename> and
  <filename>debian/<replaceable>package-2</replaceable>.install</filename> files
- will split contents of <filename>debian/tmp</filename> into
+ will split the contents of <filename>debian/tmp</filename> into
  <filename>debian/<replaceable>package-1</replaceable></filename> and
  <filename>debian/<replaceable>package-2</replaceable></filename> temporary
- directories to create multiple binary <filename>*.deb</filename> packages.
+ directories, to create
+ <filename><replaceable>package-1</replaceable>_*.deb</filename> and
+ <filename><replaceable>package-2</replaceable>_*.deb</filename> binary
+ packages.
  </para> </footnote> Everything that is contained in the temporary directory
- will be installed on a user's system when they install your package, the only
+ will be installed on users' systems when they install your package; the only
- difference is that <command>dpkg</command> will be installing the files in the
+ difference is that <command>dpkg</command> will be installing the
- root directory.
+ files to paths relative to the root directory rather than your working
+ directory.
  </para>
  <para>
  Bear in mind that even though your program installs in
  <filename>debian/<replaceable>package</replaceable></filename>, it still needs
- to behave correctly when placed in the root directory, i.e.  when installed
+ to behave correctly when installed from the <filename>.deb</filename>
- from the <filename>.deb</filename> package.  So you must not allow the build
+ package under the root directory.  So you must not allow the build
  system to hardcode strings like
  <literal>/home/me/deb/<replaceable>package</replaceable>-<replaceable>version</replaceable>/usr/share/<replaceable>package</replaceable></literal>
- into the package file.
+ into files in the package.
  </para>
  <para>
  Here's the relevant part of <systemitem role="package">gentoo</systemitem>'s
- <filename>Makefile</filename> file <footnote><para> This is just an example to
+ <filename>Makefile</filename><footnote><para> This is just an example to
- show how the <filename>Makefile</filename> file should look like.  If the
+ show what a <filename>Makefile</filename> should look like.  If the
- <filename>Makefile</filename> file is created by the
+ <filename>Makefile</filename> is created by the
  <command>./configure</command> command, the correct way to fix this kind of
- <filename>Makefile</filename> is to executed the <command>./configure</command>
+ <filename>Makefile</filename> is to execute <command>./configure</command>
- command from the <command>dh_auto_configure</command> command with default
+ from the <command>dh_auto_configure</command> command with default
  options including <literal>--prefix=/usr</literal>.  </para> </footnote>:
  </para>
  <screen>
- # Where to put binary on 'make install'?
+ # Where to put binary executables on 'make install'?
  BIN     = /usr/local/bin
  # Where to put icons on 'make install'?
  ICONS   = /usr/local/share/gentoo
  </screen>
  <para>
  We see that the files are set to install under <filename>/usr/local</filename>.
- Change those paths to:
+ As explained above, that directory hierarchy is reserved for local use on
+ Debian, so change those paths to:
  </para>
  <screen>
- # Where to put binary on 'make install'?
+ # Where to put binary executables on 'make install'?
  BIN     = $(DESTDIR)/usr/bin
  # Where to put icons on 'make install'?
  ICONS   = $(DESTDIR)/usr/share/gentoo
  </screen>
  <para>
- But why in that directory, and not some other?  Because Debian packages never
+ The exact locations that should be used for binaries, icons,
- install files beneath <filename>/usr/local</filename> -- that tree is reserved
+ documentation, etc. are specified in the Filesystem Hierarchy Standard
- for the system administrator's use.  Such files on Debian systems go under
+ (FHS).  You should browse through it and read the sections relevant to
- <filename>/usr</filename> instead.
+ your package.
- </para>
- <para>
- The more exact locations for binaries, icons, documentation etc.  are specified
- in the Filesystem Hierarchy Standard (FHS).  I recommend you
- browse it and read the sections that might concern your package.
  </para>
  <para>
- So, we should install the binary in <filename>/usr/bin</filename> instead of
+ So, we should install binary executables 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> etc.  Notice how there's no manual
+ <filename>/usr/local/man/man1</filename>, and so on.  Notice how there's no manual
  page mentioned in <systemitem role="package">gentoo</systemitem>'s
- <filename>Makefile</filename>, but since the Debian Policy requires that every
+ <filename>Makefile</filename>, but since Debian Policy requires that every
  program has one, we'll make one later and install it in
  <filename>/usr/share/man/man1</filename>.
  </para>
-Line 1387 
 to fix them to use the right locations.
+Line 1599 
 to fix them to use the right locations.
  for?  You can find this out by issuing:
  </para>
  <screen>
- $ grep -nr -e 'usr/local/lib' --include='*.[c|h]' .
+ $ grep -nr --include='*.[c|h]' -e 'usr/local/lib' .
  </screen>
  <para>
  <command>grep</command> will run recursively through the source tree and tell
-Line 1398 
 Edit those files and in those lines repl
+Line 1610 
 Edit those files and in those lines repl
  with <literal>usr/lib</literal>.  This can be done automatically as follows:
  </para>
  <screen>
- $ vim '+argdo %s/usr\/local\/lib/usr\/lib/gce|update' +q \
+ $ sed -i -e 's#usr/local/lib#usr/lib#g' \
        $(find . -type f -name '*.[c|h]')
  </screen>
  <para>
- Be careful that you don't mess up the rest of the code!  :-)
+ If you want to confirm each substitution instead, this can be done interactively as follows:
  </para>
+ <screen>
+ $ vim '+argdo %s#usr/local/lib#usr/lib#gce|update' +q \
+       $(find . -type f -name '*.[c|h]')
+ </screen>
  <para>
- After that you should find the install target (search for line that starts with
+ Next you should find the <literal>install</literal> target (searching
- <literal>install:</literal>, that will usually work) and rename all references
+ for the line that starts with <literal>install:</literal> will usually
- to directories other than ones defined at the top of the
+ work) and rename all references to directories other than ones defined
- <filename>Makefile</filename>.
+ at the top of the <filename>Makefile</filename>.
  </para>
  <para>
- Before your upstream bug fix, <systemitem role="package">gentoo</systemitem>'s
+ Originally, <systemitem role="package">gentoo</systemitem>'s
  install target said:
  </para>
  <screen>
-Line 1421 
 install: gentoo-target
+Line 1638 
 install: gentoo-target
          install gentoorc-example $(HOME)/.gentoorc
  </screen>
  <para>
- Let's fix this and record this with the <command>dquilt</command> command as
+ Let's fix this upstream bug and record it with the <command>dquilt</command> command as
  <filename>debian/patches/install.patch</filename>.
  </para>
  <screen>
-Line 1429 
 $ dquilt new install.patch
+Line 1646 
 $ dquilt new install.patch
  $ dquilt add Makefile
  </screen>
  <para>
- Let's change this for Debian package as following using the editor:
+ In your editor, change this for the Debian package as follows:
  </para>
  <screen>
  install: gentoo-target
-Line 1439 
 install: gentoo-target
+Line 1656 
 install: gentoo-target
          install -m644 gentoorc-example $(DESTDIR)/etc/gentoorc
  </screen>
  <para>
- You've surely noticed that there's now a <literal>install -d</literal> command
+ You'll have noticed that there's now an <literal>install -d</literal> command
  before the other commands in the rule.  The original
- <filename>Makefile</filename> didn't have it because usually the
+ <filename>Makefile</filename> didn't have it because usually
  <literal>/usr/local/bin</literal> and other directories already exist on the
- system where one runs <literal>make install</literal>.  However, since we will
+ system where you are running <literal>make install</literal>.  However, since we will
- install into our own empty (or even nonexistent) directory, we will have to
+ be installing into a newly created private directory tree, we will have to
  create each and every one of those directories.
  </para>
  <para>
-Line 1456 
 of additional documentation that the ups
+Line 1673 
 of additional documentation that the ups
          cp -a docs/* $(DESTDIR)/usr/share/doc/gentoo/html
  </screen>
  <para>
- After careful check, if everything is fine, ask <command>dquilt</command> to
+ Check carefully, and if everything is okay, ask <command>dquilt</command> to
- refresh the patch to create <filename>debian/patches/install.patch</filename>
+ generate the patch to create <filename>debian/patches/install.patch</filename>
  and add its description.
  </para>
  <screen>
-Line 1485 
 Debian specific packaging modification:
+Line 1702 
 Debian specific packaging modification:
  Whenever you make changes that are not specifically related to 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
- program revision and be useful to everyone else.  Also remember to make your
+ revision of the program and be useful to everyone else.  Also remember
- fixes not specific to Debian or Linux (or even Unix!) prior to sending them --
+ 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.
+ Make them portable.  This will make your fixes much easier to apply.
  </para>
  <para>
  Note that you don't have to send the <filename>debian/*</filename> files
-Line 1498 
 upstream.
+Line 1715 
 upstream.
  <para>
  There is one other common problem: libraries are often different from platform
  to platform.  For example, a <filename>Makefile</filename> can contain a
- reference to a library which doesn't exist on Debian systems.  In that case, we
+ reference to a library which doesn't exist on the Debian system.  In that case, we
  need to change it to a library which does exist in Debian, and serves the same
  purpose.
  </para>
  <para>
- So, if there is a line in your program's <filename>Makefile</filename> (or
+ Let's assume a line in your program's <filename>Makefile</filename> (or
- <filename>Makefile.in</filename>) that says something like this (and your
+ <filename>Makefile.in</filename>) as the following.
- program doesn't compile) <footnote><para> The author realizes that this is not
- the best example considering our <systemitem role="package">libncurses</systemitem> package now ships with a
- <filename>libcurses.so</filename> symlink, but he couldn't think of a better
- one.  Suggestions very welcome :-) </para> </footnote>:
  </para>
  <screen>
- LIBS = -lcurses -lsomething -lsomethingelse
+ LIBS = -lfoo -lbar
  </screen>
  <para>
- Let's fix this as <filename>debian/patches/ncurse.patch</filename> by changing
+ If your program doesn't compile since the <literal>foo</literal> library
- <literal>curses</literal> into <literal>ncurses</literal>.
+ doesn't exist and its equivalent is provided by the <literal>foo2</literal>
+ library on the Debian system, you can fix this build problem as
+ <filename>debian/patches/foo2.patch</filename> by changing
+ <literal>foo</literal> into <literal>foo2</literal>.<footnote><para>If there
+ are API changes from the <literal>foo</literal> library to the
+ <literal>foo2</literal> library, required changes to the source code need to be
+ made to match the new API.</para> </footnote>
  </para>
  <screen>
- $ dquilt new ncurse.patch
+ $ dquilt new foo2.patch
  $ dquilt add Makefile
- $ sed -i -e s/-lcurses/-lncurses/g Makefile
+ $ sed -i -e 's/-lfoo/-lfoo2/g' Makefile
  $ dquilt refresh
  $ dquilt header -e
  ... describe patch
-Line 1535 
 that we should edit in order to customiz
+Line 1754 
 that we should edit in order to customiz
  most important of them are <filename>control</filename>,
  <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
+ they are obvious.
+ </para></footnote>
  </para>
  <section id="control"><title><filename>control</filename> file</title>
  <para>
  This file contains various values which <command>dpkg</command>,
  <command>dselect</command>, <command>apt-get</command>,
  <command>apt-cache</command>, <command>aptitude</command>, and other package
- management tools will use to manage the package.  It is defined by the <ulink url="&policy-control;">Debian
+ management tools will use to manage the package.  It is defined by the
- Policy Manual, 5 'Control files and their fields'</ulink>.
+ <ulink url="&policy-control;">Debian Policy Manual, 5 "Control files and their fields"</ulink>.
  </para>
  <para>
  Here is the <filename>control</filename> file <command>dh_make</command>
-Line 1589 
 for e-mail readers and daemons, <literal
+Line 1813 
 for e-mail readers and daemons, <literal
  daemons, <literal>x11</literal> for X11 programs that don't fit anywhere else,
  and many more.
  <footnote> <para>See
- <ulink url="&policy-subsections;">Debian Policy Manual, 2.4 'Sections'</ulink> and
+ <ulink url="&policy-subsections;">Debian Policy Manual, 2.4 "Sections"</ulink> and
  <ulink url="&sections-unstable;">List of sections in <literal>sid</literal></ulink>.</para>
  </footnote>
  </para>
-Line 1600 
 we can omit it.)
+Line 1824 
 we can omit it.)
  <para>
  Line 3 describes how important it is that the user installs this package.
  <footnote> <para>See
- <ulink url="&policy-priorities;">Debian Policy Manual, 2.5 'Priorities'</ulink>.
+ <ulink url="&policy-priorities;">Debian Policy Manual, 2.5 "Priorities"</ulink>.
  </para>
  </footnote>
  </para>
-Line 1639 
 you.  Avoid using commas, ampersands and
+Line 1863 
 you.  Avoid using commas, ampersands and
  The 5th line includes the list of packages required to build your package as
  the <literal>Build-Depends</literal> field.  You can also have the
  <literal>Build-Depends-Indep</literal> field as an additional line, here.
- <footnote><para>See <ulink url="&policy-relationships;#s-sourcebinarydeps">Debian
+ <footnote><para>See
- Policy Manual, 7.7 'Relationships between source and binary packages -
+ <ulink url="&policy-relationships;#s-sourcebinarydeps">Debian Policy Manual, 7.7 "Relationships between source and binary packages - Build-Depends, Build-Depends-Indep, Build-Conflicts, Build-Conflicts-Indep"</ulink>.</para></footnote>
- Build-Depends, Build-Depends-Indep, Build-Conflicts,
+ Some packages like
- Build-Conflicts-Indep'</ulink>.</para></footnote>  Some packages like
  <systemitem role="package">gcc</systemitem> and
  <systemitem role="package">make</systemitem> which are required by the
  <systemitem role="package">build-essential</systemitem> package are implied.  If you need
  to have other tools to build your package, you should add them to these fields.
  Multiple entries are separated with commas; read on for the explanation of
- binary dependencies to find out more about the syntax of these lines.
+ binary package dependencies to find out more about the syntax of these lines.
  </para>
  <itemizedlist>
  <listitem>
-Line 1767 
 these relations; if not, it will be expl
+Line 1990 
 these relations; if not, it will be expl
  <para>
  Here is a simplified description of package relationships.
  <footnote><para>See
- <ulink url="&policy-relationships;">Debian Policy Manual, 7 'Declaring relationships between packages'</ulink>.
+ <ulink url="&policy-relationships;">Debian Policy Manual, 7 "Declaring relationships between packages"</ulink>.
  </para></footnote>
  </para>
  <itemizedlist>
-Line 1945 
 English.  Translations of these descript
+Line 2168 
 English.  Translations of these descript
  Let's insert <literal>Vcs-*</literal> fields to document the Version Control
  System (VCS) location between line 6 and 7.
  <footnote><para>See
- <ulink url="&devref-bpp-vcs;">Developer's Reference, 6.2.5. 'Version Control System location'</ulink>.
+ <ulink url="&devref-bpp-vcs;">Debian Developer's Reference, 6.2.5. "Version Control System location"</ulink>.
  </para></footnote>
  Let's assume that the <systemitem role="package">gentoo</systemitem>
  package has its VCS located in Debian Alioth Git Service at
-Line 1992 
 Finally, here is the updated <filename>c
+Line 2215 
 Finally, here is the updated <filename>c
  <para>
  This file contains the information about package upstream resources, copyright
  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
  <ulink url="&dep5;">DEP-5: Machine-parseable <filename>debian/copyright</filename></ulink>
  provides guidelines for its format.
-Line 2062 
 debian-devel-announce: <ulink url="&howt
+Line 2285 
 debian-devel-announce: <ulink url="&howt
  <section id="changelog"><title><filename>changelog</filename> file</title>
  <para>
  This is a required file, which has a special format described in the
- <ulink url="&policy-dpkgchangelog;">Debian Policy Manual, 4.4 'debian/changelog'</ulink>.
+ <ulink url="&policy-dpkgchangelog;">Debian Policy Manual, 4.4 "debian/changelog"</ulink>.
  This format is used by <command>dpkg</command> and other programs to obtain the
  version number, revision, distribution and urgency of your package.
  </para>
-Line 2143 
 is marked as executable.
+Line 2366 
 is marked as executable.
  Every <filename>rules</filename> file, as any other
  <filename>Makefile</filename>, consists of several targets and their rules
  specifying how to handle the source.  <ulink url="&policy-debianrules;">Debian
- Policy Manual, 4.9 'Main building script: debian/rules'</ulink> explains its
+ Policy Manual, 4.9 "Main building script: debian/rules"</ulink> explains its
  details.
  </para>
  <para>
-Line 2684 
 This installs <command>bash</command> co
+Line 2907 
 This installs <command>bash</command> co
  </listitem>
  </itemizedlist>
  <para>
- For sources using Autotools, use combination of above as <literal>dh --with
- autotools-dev --with autoreconf $@</literal> to be most current with the GNU
- Build System.
- </para>
- <para>
  Many <command>dh_*</command> commands invoked by the new <command>dh</command>
  command can be customized by the corresponding configuration files in the
  <filename>debian</filename> directory.  See <xref linkend="dother"/> and the
-Line 2801 
 possible.
+Line 3019 
 possible.
  <para>
  To control most of what <systemitem role="package">debhelper</systemitem> does
  while building the package, you put optional configuration files under the
- <filename>debian</filename> directory.  This chapter will make an overview of
+ <filename>debian</filename> directory.  This chapter will provide an overview of
- what each of these does and its format.  Please read <ulink url="&debian-policy;">Debian Policy
+ what each of these does and its format.  Please read the <ulink url="&debian-policy;">Debian Policy
  Manual</ulink> and <ulink url="&developers-reference;">Debian Developer's
- Reference</ulink> for guidelines for the packaging.
+ Reference</ulink> for guidelines for packaging.
  </para>
  <para>
  The <command>dh_make</command> command will create some template configuration
-Line 2813 
 filenames suffixed by <literal>.ex</lite
+Line 3031 
 filenames suffixed by <literal>.ex</lite
  prefixed by the binary package name such as
  <literal><replaceable>package</replaceable></literal>.  Take a look at all of
  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
+ they are obvious.
+ </para></footnote>
  </para>
  <para>
- The <command>dh_make</command> command may not create some template
+ Some template configuration files for <systemitem role="package">debhelper</systemitem>
- configuration files for <systemitem role="package">debhelper</systemitem>.  In
+ may not be created by the <command>dh_make</command> command.  In
- such cases, you need to create them with the editor.
+ such cases, you need to create them with an editor.
  </para>
  <para>
- If you wish or need to activate any of those, please do the following.
+ If you wish or need to activate any of these, please do the following:
  </para>
  <itemizedlist>
  <listitem>
  <para>
  rename template files by removing the <literal>.ex</literal> or
- <literal>.EX</literal> suffix if the template files have one.
+ <literal>.EX</literal> suffix if they have one;
  </para>
  </listitem>
  <listitem>
  <para>
- rename the name of these configuration files using the actual binary package
+ rename the configuration files to use the actual binary package
- name in place of <literal><replaceable>package</replaceable></literal>.
+ name in place of <literal><replaceable>package</replaceable></literal>;
  </para>
  </listitem>
  <listitem>
  <para>
- modify template file contents to suit your needs.
+ modify template file contents to suit your needs;
  </para>
  </listitem>
  <listitem>
  <para>
- remove template files which you do not need.
+ remove template files which you do not need;
  </para>
  </listitem>
  <listitem>
  <para>
  modify the <filename>control</filename> file (see <xref linkend="control"/>),
- if necessary.
+ if necessary;
  </para>
  </listitem>
  <listitem>
-Line 2859 
 necessary.
+Line 3082 
 necessary.
  </listitem>
  </itemizedlist>
  <para>
- Those <systemitem role="package">debhelper</systemitem> configuration files
+ Any <systemitem role="package">debhelper</systemitem> configuration files
- without <filename><replaceable>package</replaceable></filename> prefix such as
+ without a <filename><replaceable>package</replaceable></filename> prefix, such as
- <filename>install</filename> apply to the first binary package.  When there are
+ <filename>install</filename>, apply to the first binary package.  When there are
  many binary packages, their configurations can be specified by prefixing their
  name to their configuration filenames such as
  <filename><replaceable>package-1</replaceable>.install</filename>,
  <filename><replaceable>package-2</replaceable>.install</filename>, etc.
  </para>
- <section id="readme"><title><filename>README.Debian</filename> file</title>
+ <section id="readme"><title><filename>README.Debian</filename></title>
  <para>
  Any extra details or discrepancies between the original package and your Debian
  version should be documented here.
  </para>
  <para>
- <command>dh_make</command> created a default one, this is what it looks like:
+ <command>dh_make</command> created a default one; this is what it looks like:
  </para>
  <screen>
  gentoo for Debian
-Line 2887 
 If you have nothing to be documented, re
+Line 3110 
 If you have nothing to be documented, re
  </citerefentry>.
  </para>
  </section>
- <section id="compat"><title><filename>compat</filename> file</title>
+ <section id="compat"><title><filename>compat</filename></title>
  <para>
  The <filename>compat</filename> file defines the <systemitem role="package">debhelper</systemitem> compatibility level.  Currently, you
- should set it to the <systemitem role="package">debhelper</systemitem> V7 by
+ should set it to the <systemitem role="package">debhelper</systemitem> v7 as
- the following.
+ follows:
  </para>
  <screen>
  $ echo 7 &gt; debian/compat
  </screen>
  </section>
- <section id="conffiles"><title><filename>conffiles</filename> file</title>
+ <section id="conffiles"><title><filename>conffiles</filename></title>
  <para>
  One of the most annoying things about software is when you spend a great deal
  of time and effort customizing a program, only to have an upgrade stomp all
  over your changes.  Debian solves this problem by marking such configuration files as conffiles.
  <footnote><para>See <citerefentry> <refentrytitle>dpkg</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> and
- <ulink url="&policy-conffiles;">Debian Policy Manual 'D.2.5 Conffiles'</ulink>.
+ <ulink url="&policy-conffiles;">Debian Policy Manual "D.2.5 Conffiles"</ulink>.
  </para></footnote>
- When you upgrade a package, you'll be prompted whether you want to keep
+ When you upgrade a package, you'll be asked whether you want to keep
  your old configuration files or not.
  </para>
  <para>
- Since <systemitem role="package">debhelper</systemitem> V3, <citerefentry>
+ <citerefentry><refentrytitle>dh_installdeb</refentrytitle> <manvolnum>1</manvolnum>
- <refentrytitle>dh_installdeb</refentrytitle> <manvolnum>1</manvolnum>
+ </citerefentry> <emphasis>automatically</emphasis> flags any files under
- </citerefentry> will <emphasis>automatically</emphasis> flag any files under
  the <filename>/etc</filename> directory as conffiles, so if your program only
  has conffiles there you do not need to specify them in this file.  For most
- package types, the only place there is (and should be conffiles) is under
+ package types, the only place conffiles should ever be is under
- <filename>/etc</filename> and so this file doesn't need to exist.
+ <filename>/etc</filename>, and so this file doesn't need to exist.
  </para>
  <para>
  If your program uses configuration files but also rewrites them on its own,
- it's best not to make them as conffiles because <command>dpkg</command> will
+ it's best not to make them conffiles because <command>dpkg</command> will
  then prompt users to verify the changes all the time.
  </para>
  <para>
  If the program you're packaging requires every user to modify the configuration
- files in the <filename>/etc</filename> directory, there are 2 popular ways to
+ files in the <filename>/etc</filename> directory, there are two popular ways to
- make them not as conffiles to keep <command>dpkg</command> quiet.
+ arrange for them to not be conffiles, keeping <command>dpkg</command> quiet.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- You make a symlink under the <filename>/etc</filename> directory pointing to a
+ Create a symlink under the <filename>/etc</filename> directory pointing to a
  file under the <filename>/var</filename> directory generated by the
- <emphasis>maintainer scripts</emphasis>.
+ maintainer scripts.
  </para>
  </listitem>
  <listitem>
  <para>
- You make a file generated by the <emphasis>maintainer scripts</emphasis> under
+ Create a file generated by the maintainer scripts under the <filename>/etc</filename> directory.
- the <filename>/etc</filename> directory.
  </para>
  </listitem>
  </itemizedlist>
  <para>
- For more information on the <emphasis>maintainer scripts</emphasis>, see <xref linkend="maintscripts"/>.
+ For information on maintainer scripts, see <xref linkend="maintscripts"/>.
  </para>
  </section>
- <section id="crond"><title><filename><replaceable>package</replaceable>.cron.*</filename> files</title>
+ <section id="crond"><title><filename><replaceable>package</replaceable>.cron.*</filename></title>
  <para>
  If your package requires regularly scheduled tasks to operate properly, you can
- use this file to set it up.  You can either setup regular tasks that happen
+ use these files to set that up.  You can set up regular tasks that either happen
- hourly, daily, weekly or monthly or alternatively happen any other time that
+ hourly, daily, weekly, or monthly, or alternatively happen at any other time that
  you wish.  The filenames are:
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <filename>cron.hourly</filename> - Installed as
+ <filename><replaceable>package</replaceable>.cron.hourly</filename> - Installed as
- <filename>/etc/cron.hourly/<replaceable>package</replaceable></filename>: run
+ <filename>/etc/cron.hourly/<replaceable>package</replaceable></filename>; run
- once an hour every hour.
+ once an hour.
  </para>
  </listitem>
  <listitem>
  <para>
- <filename>cron.daily</filename> - Installed as
+ <filename><replaceable>package</replaceable>.cron.daily</filename> - Installed as
- <filename>/etc/cron.daily/<replaceable>package</replaceable></filename>: run
+ <filename>/etc/cron.daily/<replaceable>package</replaceable></filename>; run
- once a day, usually early morning.
+ once a day.
  </para>
  </listitem>
  <listitem>
  <para>
- <filename>cron.weekly</filename> - Installed as
+ <filename><replaceable>package</replaceable>.cron.weekly</filename> - Installed as
- <filename>/etc/cron.weekly/<replaceable>package</replaceable></filename>: run
+ <filename>/etc/cron.weekly/<replaceable>package</replaceable></filename>; run
- once a week, usually early Sunday morning.
+ once a week.
  </para>
  </listitem>
  <listitem>
  <para>
- <filename>cron.monthly</filename> - Installed as
+ <filename><replaceable>package</replaceable>.cron.monthly</filename> - Installed as
  <filename>/etc/cron.monthly/<replaceable>package</replaceable></filename>: run
- once a month, usually early morning on the first of the month.
+ once a month.
  </para>
  </listitem>
  <listitem>
  <para>
- <filename>cron.d</filename> - Installed as
+ <filename><replaceable>package</replaceable>.cron.d</filename> - Installed as
  <filename>/etc/cron.d/<replaceable>package</replaceable></filename>: for any
- other time
+ other time.
  </para>
  </listitem>
  </itemizedlist>
  <para>
- For the named files, the format of them is the shell script.  The different one
+ Most of these files are shell scripts, with the exception of
- is <filename><replaceable>package</replaceable>.cron.d</filename> which follows
+ <filename><replaceable>package</replaceable>.cron.d</filename> which follows
  the format of <citerefentry> <refentrytitle>crontab</refentrytitle>
  <manvolnum>5</manvolnum> </citerefentry>.
  </para>
  <para>
- Note that this doesn't include log rotation; for that, see <citerefentry>
+ No explicit <filename>cron.*</filename> file is needed to set up log rotation;
- <refentrytitle>dh_installlogrotate</refentrytitle> <manvolnum>1</manvolnum>
+ for that, see
- </citerefentry> and <citerefentry> <refentrytitle>logrotate</refentrytitle>
+ <citerefentry><refentrytitle>dh_installlogrotate</refentrytitle>
- <manvolnum>8</manvolnum> </citerefentry>.
+ <manvolnum>1</manvolnum></citerefentry> and
+ <citerefentry><refentrytitle>logrotate</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  </para>
  </section>
- <section id="dirs"><title><filename>dirs</filename> file</title>
+ <section id="dirs"><title><filename>dirs</filename></title>
  <para>
- This file specifies the directories which we need but the normal installation
+ This file specifies any directories which we need but which are not created by the normal installation
  procedure (<literal>make install DESTDIR=...</literal> invoked by
- <literal>dh_auto_install</literal>) somehow doesn't create.  This generally
+ <literal>dh_auto_install</literal>).  This generally
  means there is a problem with the <filename>Makefile</filename>.
  </para>
  <para>
- Files listed in the <filename>install</filename> file doesn't need the
+ Files listed in an <filename>install</filename> file don't need their
  directories created first.  See <xref linkend="install"/>.
  </para>
  <para>
  It is best to try to run the installation first and only use this if you
  run into trouble.  There is no preceding slash on the directory names listed in
  the <filename>dirs</filename> file.
  </para>
  </section>
- <section id="doc-base"><title><filename><replaceable>package</replaceable>.doc-base</filename> file</title>
+ <section id="doc-base"><title><filename><replaceable>package</replaceable>.doc-base</filename></title>
  <para>
- If your package has documentation other than manual pages and info docs, you
+ If your package has documentation other than manual and info pages, you
  should use the <systemitem role="package">doc-base</systemitem> file to
  register it, so the user can find it with e.g.  <citerefentry>
  <refentrytitle>dhelp</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
  <citerefentry> <refentrytitle>dwww</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> or <citerefentry> <refentrytitle>doccentral</refentrytitle>
+ </citerefentry>, or <citerefentry> <refentrytitle>doccentral</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry>.
  </para>
  <para>
-Line 3036 
 This usually includes HTML, PS and PDF f
+Line 3258 
 This usually includes HTML, PS and PDF f
  <filename>/usr/share/doc/<replaceable>packagename</replaceable>/</filename>.
  </para>
  <para>
- This is how <systemitem role="package">gentoo</systemitem>'s doc-base file
+ This is what <systemitem role="package">gentoo</systemitem>'s doc-base file
  <filename>gentoo.doc-base</filename> looks like:
  </para>
  <screen>
-Line 3059 
 manual, in <ulink url="&doc-base;">Debia
+Line 3281 
 manual, in <ulink url="&doc-base;">Debia
  For more details on installing additional documentation, look in <xref linkend="destdir"/>.
  </para>
  </section>
- <section id="docs"><title><filename>docs</filename> file</title>
+ <section id="docs"><title><filename>docs</filename></title>
  <para>
  This file specifies the file names of documentation files we can have
  <citerefentry> <refentrytitle>dh_installdocs</refentrytitle>
-Line 3072 
 directory that are called <filename>BUGS
+Line 3294 
 directory that are called <filename>BUGS
  <filename>README*</filename>, <filename>TODO</filename> etc.
  </para>
  <para>
- For <systemitem role="package">gentoo</systemitem>, I also included some other
+ For <systemitem role="package">gentoo</systemitem>, some other files
- files:
+ are also included:
  </para>
  <screen>
  BUGS
-Line 3085 
 README.gtkrc
+Line 3307 
 README.gtkrc
  TODO
  </screen>
  </section>
- <section id="emacsen"><title><filename>emacsen-*</filename> file</title>
+ <section id="emacsen"><title><filename>emacsen-*</filename></title>
  <para>
  If your package supplies Emacs files that can be bytecompiled at package
  installation time, you can use these files to set it up.
-Line 3099 
 They are installed into the temporary di
+Line 3321 
 They are installed into the temporary di
  If you don't need these, remove them.
  </para>
  </section>
- <section id="examples"><title><filename><replaceable>package</replaceable>.examples</filename> file</title>
+ <section id="examples"><title><filename><replaceable>package</replaceable>.examples</filename></title>
  <para>
  The <citerefentry> <refentrytitle>dh_installexamples</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> command installs files and directories
  listed in this file as example files.
  </para>
  </section>
- <section id="initd"><title><filename><replaceable>package</replaceable>.init</filename> and <filename><replaceable>package</replaceable>.default</filename> files</title>
+ <section id="initd"><title><filename><replaceable>package</replaceable>.init</filename> and <filename><replaceable>package</replaceable>.default</filename></title>
  <para>
- If your package is a daemon that needs to be run at the system start-up, you've
+ If your package is a daemon that needs to be run at system start-up, you've
  obviously disregarded my initial recommendation, haven't you?  :-)
  </para>
  <para>
  The <filename><replaceable>package</replaceable>.init</filename> file is
  installed as the
- <filename>/etc/init.d/<replaceable>package</replaceable></filename> script.
+ <filename>/etc/init.d/<replaceable>package</replaceable></filename> script
+ which starts and stops the daemon.
  Its fairly generic skeleton template is provided by the
  <command>dh_make</command> command as <filename>init.d.ex</filename>.  You'll
  likely have to rename and edit it, a lot, while making sure to provide
-Line 3125 
 gets installed into the temporary direct
+Line 3348 
 gets installed into the temporary direct
  </para>
  <para>
  The <filename><replaceable>package</replaceable>.default</filename> file will
- be installed into
+ be installed as
  <filename>/etc/default/<replaceable>package</replaceable></filename>.  This
- file sets defaults that are sourced by the <filename>.init</filename> script.  Most times this
+ file sets defaults that are sourced by the init script.  This
- <filename>.default</filename> file is used to disable running a daemon, set some default flags or
+ <filename><replaceable>package</replaceable>.default</filename> file
- timeouts.  If your <filename>.init</filename> script has certain <emphasis>settable</emphasis>
+ is most often used to disable running a daemon, or to set some default flags or
- features you want to install these into the <filename>.default</filename> file, not the <filename>.init</filename> script.
+ timeouts.  If your init script has certain configurable
+ features, you can set them in the <filename><replaceable>package</replaceable>.default</filename> file,
+ instead of in the init script itself.
  </para>
  <para>
- If your upstream program has an <filename>.init</filename> file you can either use it or not.  If you
+ If your upstream program provides a file for the init script, you can either use it or not.  If you
- don't use their <filename>init.d</filename> script then create a new one in
+ don't use their init script then create a new one in
- <filename>debian/<replaceable>package</replaceable>.init</filename>.  However
+ <filename><replaceable>package</replaceable>.init</filename>.  However
- if the upstream <filename>.init</filename> script looks fine and installs in the right place you
+ if the upstream init script looks fine and installs in the right place you
- still need to setup the <filename>rc*</filename> symlinks.  To do this you will
+ still need to set up the <filename>rc*</filename> symlinks.  To do this you will
  need to override <command>dh_installinit</command> in the
  <filename>rules</filename> file with the following lines:
  </para>
-Line 3149 
 override_dh_installinit:
+Line 3374 
 override_dh_installinit:
  If you don't need this, remove the files.
  </para>
  </section>
- <section id="install"><title><filename>install</filename> file</title>
+ <section id="install"><title><filename>install</filename></title>
  <para>
  If there are files that need to be installed into your package but your
- standard <literal>make install</literal> won't do it, you put the filenames and
+ standard <literal>make install</literal> won't do it, put the filenames and
  destinations into this <filename>install</filename> file.  They are installed
  by <citerefentry> <refentrytitle>dh_install</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry>.<footnote><para> This replaces the
-Line 3165 
 the <filename>docs</filename> file and n
+Line 3390 
 the <filename>docs</filename> file and n
  <para>
  This <filename>install</filename> file has one line per file installed, with
  the name of the file (relative to the top build directory) then a space then
- the installation directory (relative to the install directory).  One example of
+ the installation directory (relative to the install directory).  One example of where this is used is if a binary <filename>src/<replaceable>bar</replaceable></filename> is left uninstalled; the
- where this is used is where a binary is forgotten to be installed, the
+ <filename>install</filename> file might look like:
- <filename>install</filename> file would look like:
  </para>
  <screen>
- src/foo/mybin usr/bin
+ src/<replaceable>bar</replaceable> usr/bin
  </screen>
  <para>
- This will mean when this package is installed, there will be a binary file
+ This means when this package is installed, there will be a binary executable
- <filename>/usr/bin/mybin</filename>.
+ <filename>/usr/bin/<replaceable>bar</replaceable></filename>.
  </para>
  <para>
  Alternatively, this <filename>install</filename> can have the name of the file
  only without the installation directory when the relative directory path does
- not change.  This format is usually used for a large package that splits build
+ not change.  This format is usually used for a large package that splits the
- result into multiple binary packages using
+ output of its build into multiple binary packages using
  <filename><replaceable>package-1</replaceable>.install</filename>,
  <filename><replaceable>package-2</replaceable>.install</filename>, etc.
  </para>
  <para>
- The <command>dh_install</command> command will fall back to look in
+ The <command>dh_install</command> command will fall back to looking in
  <filename>debian/tmp</filename> for files, if it doesn't find them in the
  current directory (or wherever you've told it to look using
  <literal>--sourcedir</literal>).
  </para>
  </section>
- <section id="info"><title><filename><replaceable>package</replaceable>.info</filename> file</title>
+ <section id="info"><title><filename><replaceable>package</replaceable>.info</filename></title>
  <para>
  If your package has info pages, you should install them using <citerefentry>
  <refentrytitle>dh_installinfo</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> by listing them in the
+ </citerefentry> by listing them in a
- <filename><replaceable>package</replaceable>.info</filename> files.
+ <filename><replaceable>package</replaceable>.info</filename> file.
  </para>
  </section>
- <section id="lintian"><title><filename>{<replaceable>package</replaceable>.|source/}lintian-overrides</filename> files</title>
+ <section id="lintian"><title><filename>{<replaceable>package</replaceable>.,source/}lintian-overrides</filename></title>
  <para>
  If <systemitem role="package">lintian</systemitem> reports an erroneous
- diagnostics for a case when the policy allows exceptions to some rule, you can
+ diagnostic for a case where Debian policy allows exceptions to some rule, you can
  use <filename><replaceable>package</replaceable>.lintian-overrides</filename>
- or <filename>source/lintian-overrides</filename> to quiet it.  Please read
+ or <filename>source/lintian-overrides</filename> to quieten it.  Please read
  <ulink url="&lintian-doc;">Lintian User's Manual</ulink> and refrain
  from abusing this.
  </para>
  <para>
  <filename><replaceable>package</replaceable>.lintian-overrides</filename> is
- for the binary package named as <systemitem role="package"><replaceable>package</replaceable></systemitem> and is installed
+ for the binary package named <systemitem role="package"><replaceable>package</replaceable></systemitem> and is installed
  into
  <filename>usr/share/lintian/overrides/<replaceable>package</replaceable></filename>
  by the <command>dh_lintian</command> command.
-Line 3220 
 by the <command>dh_lintian</command> com
+Line 3444 
 by the <command>dh_lintian</command> com
  is not installed.
  </para>
  </section>
- <section id="manpage"><title><filename>manpage.*</filename> files</title>
+ <section id="manpage"><title><filename>manpage.*</filename></title>
  <para>
  Your program(s) should have a manual page.  If they don't, you should create
- them.  The <command>dh_make</command> command creates few template files for a
+ them.  The <command>dh_make</command> command creates some template files for
- manual page.  These need to be copied and edited for each command without its
+ manual pages.  These need to be copied and edited for each command missing its
  manual page.  Please make sure to remove unused templates.
  </para>
- <section id="manpage1"><title><filename>manpage.1.ex</filename> file</title>
+ <section id="manpage1"><title><filename>manpage.1.ex</filename></title>
  <para>
  Manual pages are normally written in <citerefentry>
  <refentrytitle>nroff</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.
-Line 3237 
 The <filename>manpage.1.ex</filename> te
+Line 3461 
 The <filename>manpage.1.ex</filename> te
  manual page for a brief description of how to edit such a file.
  </para>
  <para>
- The final manual page file name should include the name of the program it is
+ The final manual page file name should give the name of the program it is
  documenting, so we will rename it from <literal>manpage</literal> to
  <literal>gentoo</literal>.  The file name also includes <literal>.1</literal>
  as the first suffix, which means it's a manual page for a user command.  Be
  sure to verify that this section is indeed the correct one.  Here's a short
  list of manual page sections:
  </para>
- <table id="manpage-sections" pgwide="0" frame="topbot" rowsep="1" colsep="1">
+ <informaltable id="manpage-sections" pgwide="0" frame="topbot" rowsep="1" colsep="1">
- <title>manual page sections</title>
  <tgroup cols="3">
    <colspec colwidth="8*" align="left"/> <colspec colwidth="24*" align="left"/> <colspec colwidth="40*" align="left"/>
    <thead>
-Line 3263 
 list of manual page sections:
+Line 3486 
 list of manual page sections:
      <row> <entry>9</entry> <entry>Kernel routines</entry> <entry>Non-standard calls and internals</entry> </row>
    </tbody>
  </tgroup>
- </table>
+ </informaltable>
  <para>
  So <systemitem role="package">gentoo</systemitem>'s man page should be called
  <filename>gentoo.1</filename>.  If there was no <filename>gentoo.1</filename>
  man page in the original source, you should create it by renaming the
  <filename>manpage.1.ex</filename> template to <filename>gentoo.1</filename> and
- edit it by using information from the example and from upstream docs.
+ editing it using information from the example and from the upstream docs.
  </para>
  <para>
  You can use the <command>help2man</command> command to generate a man page out
- of <literal>--help</literal> and <literal>--version</literal> output of each
+ of the <literal>--help</literal> and <literal>--version</literal> output of each
- program, too.  <footnote><para> If the command is missing
+ program, too.  <footnote><para> Note that <command>help2man</command>'s
- <command>info</command> page but have documentation files in the
+ placeholder man page will claim that more detailed documentation is
- <filename>/usr/share/<replaceable>package</replaceable></filename> directory,
+ available in the info system. If the command is missing an
- you should manually edit generated the man page created by the
+ <command>info</command> page, you
+ should manually edit the man page created by the
  <command>help2man</command> command.  </para> </footnote>
  </para>
  </section>
- <section id="manpagesgml"><title><filename>manpage.sgml.ex</filename> file</title>
+ <section id="manpagesgml"><title><filename>manpage.sgml.ex</filename></title>
  <para>
  If on the other hand you prefer writing SGML instead of
  <command>nroff</command>, you can use the <filename>manpage.sgml.ex</filename>
-Line 3306 
 line in the <filename>control</filename>
+Line 3530 
 line in the <filename>control</filename>
  </listitem>
  <listitem>
  <para>
- add a <literal>override_dh_auto_build</literal> target to your
+ add an <literal>override_dh_auto_build</literal> target to your
  <filename>rules</filename> file:
  </para>
  <screen>
-Line 3317 
 override_dh_auto_build:
+Line 3541 
 override_dh_auto_build:
  </listitem>
  </itemizedlist>
  </section>
- <section id="manpagexml"><title><filename>manpage.xml.ex</filename> file</title>
+ <section id="manpagexml"><title><filename>manpage.xml.ex</filename></title>
  <para>
  If you prefer XML over SGML, you can use the <literal>manpage.xml.ex</literal>
  template.  If you do this, you have to:
-Line 3337 
 XSLT processor like <systemitem role="pa
+Line 3561 
 XSLT processor like <systemitem role="pa
  </listitem>
  <listitem>
  <para>
- add the <literal>docbook-xsl</literal>, <literal>docbook-xml</literal> and
+ add the <literal>docbook-xsl</literal>, <literal>docbook-xml</literal>, and
  <literal>xsltproc</literal> packages to the <literal>Build-Depends</literal>
  line in the <literal>control</literal> file
  </para>
  </listitem>
  <listitem>
  <para>
- add a <literal>override_dh_auto_build</literal> target to your
+ add an <literal>override_dh_auto_build</literal> target to your
  <filename>rules</filename> file:
  </para>
  <screen>
-Line 3362 
 override_dh_auto_build:
+Line 3586 
 override_dh_auto_build:
  </itemizedlist>
  </section>
  </section>
- <section id="manpages"><title><filename><replaceable>package</replaceable>.manpages</filename> file</title>
+ <section id="manpages"><title><filename><replaceable>package</replaceable>.manpages</filename></title>
  <para>
  If your package has manual pages, you should install them using <citerefentry>
  <refentrytitle>dh_installman</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> by listing them in the
+ </citerefentry> by listing them in a
- <filename><replaceable>package</replaceable>.manpages</filename> files.
+ <filename><replaceable>package</replaceable>.manpages</filename> file.
  </para>
  <para>
- To install <filename>docs/gentoo.1</filename> for the <systemitem role="package">gentoo</systemitem> package as its manpage, you create a
+ To install <filename>docs/gentoo.1</filename> as a manpage for the <systemitem role="package">gentoo</systemitem> package, create a
- <filename>gentoo.manpages</filename> file as the following.
+ <filename>gentoo.manpages</filename> file as follows.
  </para>
  <screen>
  docs/gentoo.1
  </screen>
  </section>
- <section id="menu"><title><filename>menu</filename> file</title>
+ <section id="menu"><title><filename>menu</filename></title>
  <para>
  X Window System users usually have a window manager with a menu that can be
  customized to launch programs.  If they have installed the Debian <systemitem role="package">menu</systemitem> package, a set of menus for every program on
-Line 3398 
 specifies what kind of interface the pro
+Line 3622 
 specifies what kind of interface the pro
  listed alternatives, e.g.  <literal>text</literal> or <literal>X11</literal>.
  </para>
  <para>
- The next is <literal>section</literal>, where the menu and submenu entry
+ The next is the <literal>section</literal> that the menu and submenu entry
  should appear in.
- <footnote><para> The current list of sections is at
+ <footnote><para> The current list of sections is in
- <ulink url="&menu-structure;">The Debian Menu sub-policy 2.1 'Preferred menu structure'</ulink>.
+ <ulink url="&menu-structure;">The Debian Menu sub-policy 2.1 "Preferred menu structure"</ulink>.
- There were a major reorganization of menu structure for <literal>squeeze</literal>.
+ There was a major reorganization of menu structure for <literal>squeeze</literal>.
  </para> </footnote>
  </para>
  <para>
-Line 3429 
 You can also add other fields like <lite
+Line 3653 
 You can also add other fields like <lite
  </citerefentry>, <citerefentry> <refentrytitle>menufile</refentrytitle>
  <manvolnum>5</manvolnum> </citerefentry>, <citerefentry>
  <refentrytitle>update-menus</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> and
+ </citerefentry>, and
- <ulink url="&menu-policy;">The Debian Menu sub-policy</ulink> for more
+ <ulink url="&policy-menu;">The Debian Menu sub-policy</ulink> for more
  information.
  </para>
  </section>
- <section id="news"><title><filename>NEWS</filename> file</title>
+ <section id="news"><title><filename>NEWS</filename></title>
  <para>
  The <citerefentry> <refentrytitle>dh_installchangelogs</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> command installs this.
  </para>
  </section>
- <section id="maintscripts"><title><filename>{post|pre}{inst|rm}</filename> files</title>
+ <section id="maintscripts"><title><filename>{pre,post}{inst,rm}</filename></title>
  <para>
  These <filename>postinst</filename>, <filename>preinst</filename>,
  <filename>postrm</filename>, and <filename>prerm</filename> files
- <footnote><para> Although I used Bash short hand expression to indicate these
+ <footnote><para> Despite this use of the <command>bash</command>
- files as <filename>{post|pre}{inst|rm}</filename> here, I recommend you to use
+ shorthand expression <filename>{pre,post}{inst,rm}</filename> to indicate these
- pure POSIX (non-Bash) shell for these <emphasis>maintainer scripts</emphasis>
+ filenames, you should use pure POSIX syntax for these maintainer scripts for
- as much as possible for the better compatibility.  </para> </footnote> are
+ compatibility with <command>dash</command> as the system shell.  </para> </footnote> are
  called <emphasis>maintainer scripts</emphasis>.  They are scripts which are put
  in the control area of the package and run by <command>dpkg</command> when your
- package is installed, upgraded or removed.
+ package is installed, upgraded, or removed.
  </para>
  <para>
  As a novice maintainer, you should avoid any manual editing of
- <emphasis>maintainer scripts</emphasis> because they are problematic.  For more
+ maintainer scripts because they are problematic.  For more
- information look in the <ulink url="&policy-mantainerscripts;">Debian
+ information refer to the <ulink url="&policy-mantainerscripts;">Debian
- Policy Manual, 6 'Package maintainer scripts and installation
+ Policy Manual, 6 "Package maintainer scripts and installation
- procedure'</ulink>, and take a look at these example files provided by
+ procedure"</ulink>, and take a look at the example files provided by
  <command>dh_make</command>.
  </para>
  <para>
- If you did not listen to me and made your custom <emphasis>maintainer
+ If you did not listen to me and have created custom maintainer
- scripts</emphasis> for a package, you should make sure to test them not only
+ scripts for a package, you should make sure to test them not only
- for <emphasis role="strong">install</emphasis> and <emphasis role="strong">upgrade</emphasis> but also for <emphasis role="strong">remove</emphasis> and <emphasis role="strong">purge</emphasis>.
+ for <emphasis role="strong">install</emphasis> and
+ <emphasis role="strong">upgrade</emphasis> but also for
+ <emphasis role="strong">remove</emphasis> and
+ <emphasis role="strong">purge</emphasis>.
  </para>
  <para>
  Upgrades to the new version should be silent and non-intrusive (existing users
  should not notice the upgrade except by discovering that old bugs have been
- fixed and there perhaps are new features).
+ fixed and perhaps that there are new features).
  </para>
  <para>
  When the upgrade is necessarily intrusive (eg., config files scattered through
- various home directories with totally different structure), you may consider to
+ various home directories with totally different structure), you may
- set package to the safe default (e.g., disabled service) and provide proper
+ consider as the last resort switching the package to a safe fallback state
- documentations required by the policy (<filename>README.Debian</filename> and
+ (e.g., disabling a service) and providing the proper documentation
- <filename>NEWS.Debian</filename>) as the last resort.  Don't bother user with
+ required by policy (<filename>README.Debian</filename> and
- the <command>debconf</command> note invoked from these <emphasis>maintainer
+ <filename>NEWS.Debian</filename>).  Don't bother the user with
- scripts</emphasis> for upgrades.
+ <command>debconf</command> notes invoked from these maintainer scripts
+ for upgrades.
  </para>
  <para>
- The <systemitem role="package">ucf</systemitem> package provides
+ The <systemitem role="package">ucf</systemitem> package provides a
  <emphasis>conffile-like</emphasis> handling infrastructure to preserve user
- changes for files that may not be labeled <emphasis>conffiles</emphasis> such
+ changes for files that may not be labeled as <emphasis>conffiles</emphasis> such
- as ones managed by the <emphasis>maintainer scripts</emphasis>.  This should
+ as those managed by the maintainer scripts.  This should
  minimize issues associated with them.
  </para>
  <para>
- These <emphasis>maintainer scripts</emphasis> are the Debian enhancements that
+ These maintainer scripts are among the Debian enhancements that
  explain <emphasis role="strong">why people choose Debian</emphasis>.  You must
- be very careful not to annoy them with these.
+ be very careful not to turn them into a source of annoyance.
  </para>
  </section>
- <section id="todo"><title><filename>TODO</filename> file</title>
+ <section id="todo"><title><filename>TODO</filename></title>
  <para>
  The <citerefentry> <refentrytitle>dh_installdocs</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> command installs this.
  </para>
  </section>
- <section id="watch"><title><filename>watch</filename> file</title>
+ <section id="watch"><title><filename>watch</filename></title>
  <para>
  The <filename>watch</filename> file format is documented in the <citerefentry>
  <refentrytitle>uscan</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
  manpage.  The <filename>watch</filename> file configures the
  <command>uscan</command> program (in the <systemitem role="package">devscripts</systemitem> package) to watch the site where you
- originally got the source from.  This is also used by <ulink url="&dehs;">Debian External Health Status (DEHS)</ulink>.
+ originally got the source from.  This is also used by the
+ <ulink url="&dehs;">Debian External Health Status (DEHS)</ulink> service.
  </para>
  <para>
- Here's what I put in it:
+ Here are its contents:
  </para>
  <screen>
  # watch control file for uscan
-Line 3515 
 version=3
+Line 3744 
 version=3
  &sf-net;/gentoo/gentoo-(.+)\.tar\.gz debian uupdate
  </screen>
  <para>
- Normally with this <filename>watch</filename> file, the URL at
+ Normally with a <filename>watch</filename> file, the URL at
  <literal>&sf-net;/gentoo</literal> is downloaded and searched for links of
- the form <literal>&lt;a href=...&gt;</literal>.  The base name (just the part
+ the form <literal>&lt;a href=...&gt;</literal>.  The basename (just the part
- after the final <literal>/</literal>) of these linked URLs are matched against
+ after the final <literal>/</literal>) of each linked URL is compared against
- Perl regular expression (see <citerefentry> <refentrytitle>perlre</refentrytitle>
+ the Perl regular expression pattern (see <citerefentry> <refentrytitle>perlre</refentrytitle>
- <manvolnum>1</manvolnum> </citerefentry>) pattern
+ <manvolnum>1</manvolnum> </citerefentry>)
- <literal>gentoo-(.+)\.tar\.gz</literal>.  Out of matched files, the file with
+ <literal>gentoo-(.+)\.tar\.gz</literal>.  Out of the files that match, the one with
  the greatest version number is downloaded and the <command>uupdate</command>
- program is run to create the updated source tree from them.
+ program is run to create an updated source tree.
  </para>
  <para>
  Although this is true for other sites, the SourceForge download service at
  <ulink url="&sf-net;"/> is an exception.  When the
- <filename>watch</filename> file has an URL matching with the Perl regexp
+ <filename>watch</filename> file has an URL matching the Perl regexp
  <literal>^http://sf\.net/</literal>, the <command>uscan</command> program
- substitutes it with <literal>&qa-do;watch/sf.php/</literal> and
+ replaces it with <literal>&qa-do;watch/sf.php/</literal> and
- then applies this rule.  The URL redirector service at this <ulink url="&qa-do;"/> is designed to offer
+ then applies this rule.  The URL redirector service at <ulink url="&qa-do;"/> is designed to offer
- a stable redirect service to the desired file for the
+ a stable redirect service to the desired file for any
- <filename>watch</filename> file having
+ <filename>watch</filename> pattern of the form
  <literal>&sf-net;/<replaceable>project</replaceable>/<replaceable>tar-name</replaceable>-(.+)\.tar\.gz</literal>.
- This solves issues related to the periodically changing URL there.
+ This solves issues related to periodically changing SourceForge URLs.
  </para>
  </section>
- <section id="sourcef"><title><filename>source/format</filename> file</title>
+ <section id="sourcef"><title><filename>source/format</filename></title>
  <para>
  In the <filename>debian/source/format</filename> file, there should be a single
  line indicating the desired format for the source package (check <citerefentry>
-Line 3562 
 should say either:
+Line 3791 
 should say either:
  The newer <literal>3.0 (quilt)</literal> source format records modifications in
  a <command>quilt</command> patch series within
  <filename>debian/patches</filename>.  Those changes are then automatically
- applied during extraction of the source package.  <footnote><para> See <ulink url="&debsrc3;">DebSrc3.0</ulink> for the
+ applied during extraction of the source package.  <footnote><para> See
- summary information concerning the switch to the new <literal>3.0
+ <ulink url="&debsrc3;">DebSrc3.0</ulink> for a summary on the switch to the new <literal>3.0
  (quilt)</literal> and <literal>3.0 (native)</literal> source formats.  </para>
  </footnote> The Debian modifications are simply stored in a
  <filename>debian.tar.gz</filename> archive containing all files under the
  <filename>debian</filename> directory.  This new format supports inclusion of
  binary files such as PNG icons by the package maintainer without requiring
- tricks.  <footnote><para> Actually, this new format also supports multiple
+ tricks.  <footnote><para>Actually, this new format also supports multiple
  upstream tarballs and more compression methods.  These are beyond the scope of
- this document.  </para> </footnote>
+ this document.</para> </footnote>
  </para>
  <para>
  When <command>dpkg-source</command> extracts a source package in <literal>3.0
-Line 3580 
 When <command>dpkg-source</command> extr
+Line 3809 
 When <command>dpkg-source</command> extr
  the end of the extraction with the <literal>--skip-patches</literal> option.
  </para>
  </section>
- <section id="sourcel"><title><filename>source/local-options</filename> file</title>
+ <section id="sourcel"><title><filename>source/local-options</filename></title>
  <para>
  When you want to manage Debian packaging activities under a VCS, you typically
  create one branch (e.g.  <literal>upstream</literal>) tracking the upstream
-Line 3605 
 unapply-patches
+Line 3834 
 unapply-patches
  abort-on-upstream-changes
  </screen>
  </section>
- <section id="sourceopt"><title><filename>source/options</filename> file</title>
+ <section id="sourceopt"><title><filename>source/options</filename></title>
  <para>
  The autogenerated files in the source tree can be quite annoying for packaging
  since they generate meaningless large patch files.  There are custom modules
-Line 3620 
 You can provide a Perl regular expressio
+Line 3849 
 You can provide a Perl regular expressio
  creating the source package.
  </para>
  <para>
- You can store such <command>dpkg-source</command> option argument in the
+ As a general solution to address this problem of the autogenerated files,
- <filename>source/options</filename> file of the source package as the generic
+ you can store such a <command>dpkg-source</command> option argument in the
- solution to address this problem of the autogenerated files.  The following
+ <filename>source/options</filename> file of the source package.  The following
  will skip creating patch files for <filename>config.sub</filename>,
- <filename>config.guess</filename> and <filename>Makefile</filename>.
+ <filename>config.guess</filename>, and <filename>Makefile</filename>.
  </para>
  <screen>
  extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"
  </screen>
  </section>
- <section id="patches"><title><filename>patches/*</filename> files</title>
+ <section id="patches"><title><filename>patches/*</filename></title>
  <para>
  The old <literal>1.0</literal> source format created a single large
- <filename>diff.gz</filename> file which contains package maintenance files in
+ <filename>diff.gz</filename> file containing package maintenance files in
- <filename>debian</filename> and patch files to the source.  Such a package is a
+ <filename>debian</filename> and patch files for the source.  Such a package is a
  bit cumbersome to inspect and understand for each source tree modification
  later.  This is not so nice.
  </para>
  <para>
  The newer <literal>3.0 (quilt)</literal> source format stores patches in
  <filename>debian/patches/*</filename> files using the <command>quilt</command>
- command.  These patches and other package data which are all constrained under
+ command.  These patches and other package data which are all contained under
  the <filename>debian</filename> directory are packaged as the
  <filename>debian.tar.gz</filename> file.  Since the
  <command>dpkg-source</command> command can handle <command>quilt</command>
  formatted patch data in the <literal>3.0 (quilt)</literal> source without the
- <systemitem role="package">quilt</systemitem> package, it does not need to
+ <systemitem role="package">quilt</systemitem> package, it does not need a
- <literal>Build-Depends</literal> on the <systemitem role="package">quilt</systemitem> package.  <footnote><para> Several methods
+ <literal>Build-Depends</literal> on <systemitem role="package">quilt</systemitem>.
- for the patch set maintenance have been proposed and are in use with Debian
+ <footnote><para> Several methods of patch set maintenance have been proposed and are in use for Debian
  packages.  The <command>quilt</command> system is the preferred maintenance
- system in use.  Other ones are <command>dpatch</command>,
+ system in use.  Others include <command>dpatch</command>,
- <command>dbs</command>, <command>cdbs</command>, etc.  Many of these keep such
+ <command>dbs</command>, and <command>cdbs</command>.  Many of these keep such
  patches as <filename>debian/patches/*</filename> files.  </para> </footnote>
  </para>
  <para>
-Line 3660 
 The <command>quilt</command> command is
+Line 3889 
 The <command>quilt</command> command is
  It records modifications to the source as a stack of <literal>-p1</literal>
  patch files in the <filename>debian/patches</filename> directory and the source
  tree is untouched outside of the <filename>debian</filename> directory.  The
- order of these patches are recorded in the
+ order of these patches is recorded in the
  <filename>debian/patches/series</filename> file.  You can apply (=push),
  un-apply (=pop), and refresh patches easily.  <footnote><para> If you are
  asking a sponsor to upload your package, this kind of clear separation and
- documentation of your changes are very important to expedite the package review
+ documentation of your changes is very important to expedite the package review
  by your sponsor.  </para> </footnote>
  </para>
  <para>
- For <xref linkend="modify"/>, we created 3 patches in
+ For <xref linkend="modify"/>, we created three patches in
  <filename>debian/patches</filename>.
  </para>
  <para>
  Since Debian patches are located in <filename>debian/patches</filename>, please
- make sure to setup the <command>dquilt</command> command properly as described
+ make sure to set up the <command>dquilt</command> command properly as described
  in <xref linkend="quiltrc"/>.
  </para>
  <para>
- When someone (including yourself) provides you with a patch
+ When anyone (including yourself) provides a patch
  <filename><replaceable>foo</replaceable>.patch</filename> to the source later,
- then the modification of a <literal>3.0 (quilt)</literal> source package is
+ modifying a <literal>3.0 (quilt)</literal> source package is
  quite simple:
  </para>
  <screen>
-Line 3693 
 $ dquilt header -e
+Line 3922 
 $ dquilt header -e
  </screen>
  <para>
  The patches stored in the newer <literal>3.0 (quilt)</literal> source format
- must be <emphasis>fuzz</emphasis> free.  You should ensure it as <literal>dquilt
+ must be <emphasis>fuzz</emphasis> free.  You can ensure this with <literal>dquilt
  pop -a; while dquilt push; do dquilt refresh; done</literal>.
  </para>
  </section>
-Line 3704 
 We should now be ready to build the pack
+Line 3933 
 We should now be ready to build the pack
  </para>
  <section id="completebuild"><title>Complete (re)build</title>
  <para>
- In order to properly make complete (re)build of a package, you have to ensure
+ In order to perform a complete (re)build of a package properly, you
- to install
+ need to make sure you have installed
  </para>
  <itemizedlist>
  <listitem>
-Line 3772 
 The only input that will be required of
+Line 4001 
 The only input that will be required of
  twice.
  <footnote><para>
  This GPG key must be signed by a Debian developer to get connected to the web
- of trust and must be registerd to <ulink url="&keyring;">the Debian
+ of trust and must be registered to <ulink url="&keyring;">the Debian
  keyring</ulink>.  This enables your uploaded packages to be accepted to the
  Debian archives.  See
  <ulink url="&keycreate;">Creating a new GPG key</ulink> and
  <ulink url="&keysigning; ">Debian Wiki on Keysigning</ulink>.
  </para></footnote>
+ If you are building Debian packages only for your own local use, you can skip
+ promptings for the GPG signatures on the <filename>.dsc</filename> file and the
+ <filename>.changes</filename> file like this:
  </para>
+ <screen>
+ $ dpkg-buildpackage -us -uc
+ </screen>
  <para>
- After all this is done, you will see the following files in the directory above
+ For a non-native Debian package, e.g.,
- (<filename>~/gentoo</filename>):
+ <systemitem role="package">gentoo</systemitem>, you will see the following
+ files in the parent directory (<filename>~/gentoo</filename>) after building
+ packages:
  </para>
  <itemizedlist>
  <listitem>
-Line 3789 
 After all this is done, you will see the
+Line 4026 
 After all this is done, you will see the
  <filename>gentoo_0.9.12.orig.tar.gz</filename>
  </para>
  <para>
- This is the original source code tarball, merely renamed to the above so that
+ This is the original upstream source code tarball, merely renamed to the above so that
  it adheres to the Debian standard.  Note that this was created initially by the
  <literal>dh_make -f ../gentoo-0.9.12.tar.gz</literal>.
  </para>
-Line 3812 
 people can be sure that it's really your
+Line 4049 
 people can be sure that it's really your
  </para>
  <para>
  This compressed tarball contains your <filename>debian</filename> directory
- contents.  Each and every addition you made to the original source code are
+ contents.  Each and every addition you made to the original source code is
- stored as <command>quilt</command> patches in
+ stored as a <command>quilt</command> patch in
  <filename>debian/patches</filename>.
  </para>
  <para>
-Line 3841 
 install and remove this just like any ot
+Line 4078 
 install and remove this just like any ot
  <filename>gentoo_0.9.12-1_i386.changes</filename>
  </para>
  <para>
- This file describes all the changes made in the current package revision, and
+ This file describes all the changes made in the current package revision;
  it is used by the Debian FTP archive maintenance programs to install the binary
- and source packages in it.  It is partly generated from the
+ and source packages.  It is partly generated from the
  <filename>changelog</filename> file and the <filename>.dsc</filename> file.
  This file is GPG signed, so that people can be sure that it's really yours.
  </para>
  <para>
- As you keep working on the package, behavior will change and new features will
+ As you keep working on the package, its behavior will change and new features will
  be added.  People downloading your package can look at this file and quickly
  see what has changed.  Debian archive maintenance programs will also post the
  contents of this file to the <ulink url="&debian-devel-announce-ldo;">debian-devel-announce@lists.debian.org</ulink>
-Line 3858 
 mailing list.
+Line 4095 
 mailing list.
  </itemizedlist>
  <para>
  The long strings of numbers in the <filename>.dsc</filename> and
- <filename>.changes</filename> files are MD5/SHA1/SHA256 checksums for the files
+ <filename>.changes</filename> files are SHA1/SHA256 checksums for the files
- mentioned.  A person downloading your files can test them with <citerefentry>
+ mentioned.  Anyone downloading your files can test them with <citerefentry>
- <refentrytitle>md5sum</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
+ <refentrytitle>sha1sum</refentrytitle> <manvolnum>1</manvolnum>
- <citerefentry> <refentrytitle>sha1sum</refentrytitle> <manvolnum>1</manvolnum>
+ </citerefentry> or <citerefentry> <refentrytitle>sha256sum</refentrytitle>
- </citerefentry>, or <citerefentry> <refentrytitle>sha256sum</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> and if the numbers don't match,
  they'll know the file is corrupt or has been tampered with.
  </para>
+ <para>
+ For a native Debian package, e.g.,
+ <systemitem role="package">mypackage</systemitem>, you will see the following
+ files in the parent directory after building packages:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>mypackage_1.0.tar.gz</filename>
+ </para>
+ <para>
+ This is the source code tarball created from the
+ <filename>mypackage-1.0</filename> directory by the
+ <command>dpkg-source</command>.  (Its suffix is not <filename>orig.tar.gz</filename>.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>mypackage_1.0.dsc</filename>
+ </para>
+ <para>
+ This is a summary of the contents of the source code as in the non-native
+ Debian package. (There is no Debian revision.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>mypackage_1.0_i386.deb</filename>
+ </para>
+ <para>
+ This is your completed binary package as in the non-native Debian package.
+ (There is no Debian revision.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>mypackage_1.0_i386.changes</filename>
+ </para>
+ <para>
+ This file describes all the changes made in the current package version as in
+ the non-native Debian package. (There is no Debian revision.)
+ </para>
+ </listitem>
+ </itemizedlist>
  </section>
  <section id="autobuilder"><title>Autobuilder</title>
  <para>
  Debian supports many <ulink url="&ports;">ports</ulink>
  with the <ulink url="&buildd;">autobuilder
- network</ulink> running <command>buildd</command> daemons on many different
+ network</ulink> running <command>buildd</command> daemons on computers
- architecture computers.  Although you do not need to do this by yourself, you
+ of many different architectures.  Although you do not need to do this yourself, you
- should be aware of what will happen on your packages.  Let's look into roughly
+ should be aware of what will happen to your packages.  Let's look into roughly
- how your packages are rebuild for many different architectures by them.
+ how they rebuild your packages for multiple architectures.
  <footnote><para> The actual autobuilder system involves much more complicated
  schemes than the one documented here.  Such details are beyond the scope of
  this document.  </para> </footnote>
  </para>
  <para>
  For <literal>Architecture: any</literal> packages, the autobuilder system
- rebuild them.  It ensures to install
+ performs a rebuild.  It ensures the installation of
  </para>
  <itemizedlist>
  <listitem>
-Line 3938 
 create and sign the upload <filename>.ch
+Line 4218 
 create and sign the upload <filename>.ch
  This is why you see your package for other architectures.
  </para>
  <para>
- Although packages listed in the <literal>Build-Depends-indep</literal> field
+ Although packages listed in the <literal>Build-Depends-Indep</literal> field
- are required to be installed for the normal packaging by us (see <xref linkend="completebuild"/>), they are not required to be installed for the
+ are required to be installed for our normal packaging work (see
- autobuilder system since it build only architecture dependent binary packages.
+ <xref linkend="completebuild"/>), they are not required to be installed for the
+ autobuilder system since it builds only architecture dependent binary packages.
  <footnote><para> Unlike under the <systemitem role="package">pbuilder</systemitem> package, the <command>chroot</command>
  environment under the <systemitem role="package">sbuild</systemitem> package
- used by the autobuilder system does not force the minimal system and may leave
+ used by the autobuilder system does not enforce the use of a minimal
- many packages installed.  </para> </footnote> This difference between normal
+ system and may have many leftover packages installed.  </para>
- packaging and autobuilder situation dictates whether you record such required
+ </footnote> This distinction between normal packaging and autobuilding
+ procedures is what dictates whether you should record such required
  packages in the <literal>Build-Depends</literal> or
- <literal>Build-Depends-indep</literal> fields of the
+ <literal>Build-Depends-Indep</literal> fields of the
  <filename>debian/control</filename> file (see <xref linkend="control"/>).
  </para>
  </section>
- <section id="option-sa"><title>Including <filename>orig.tar.gz</filename> for upload</title>
- <para>
- When you first upload the package to the archive, you need to include the
- original <filename>orig.tar.gz</filename> source, too.  If the Debian revision
- number of such package is neither <literal>1</literal> nor
- <literal>0</literal>, you must provide <command>dpkg-buildpackage</command>
- command with the <literal>-sa</literal> option.  On the other hand, the
- <literal>-sd</literal> option will force to exclude the original
- <filename>orig.tar.gz</filename> source.
- </para>
- </section>
  <section id="debuild"><title><command>debuild</command> command</title>
  <para>
- You can automate package build process of the
+ You can automate the <command>dpkg-buildpackage</command> command's
- <command>dpkg-buildpackage</command> command further with the
+ package build process further with the
  <command>debuild</command> command.  See <citerefentry>
  <refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum>
  </citerefentry>.
-Line 3973 
 You can automate package build process o
+Line 4244 
 You can automate package build process o
  <para>
  Customization of the <command>debuild</command> command can be done through
  <filename>/etc/devscripts.conf</filename> or
- <filename>~/.devscripts</filename>.  I would suggest at least following items:
+ <filename>~/.devscripts</filename>.  I would suggest at least the following items:
  </para>
  <screen>
  DEBSIGN_KEYID=Your_GPG_keyID
- DEBUILD_LINTIAN=yes
  DEBUILD_LINTIAN_OPTS=-i -I --show-overrides
  </screen>
  <para>
  With these, packages are signed by your specified GPG key ID (good for
- sponsoring packages) and checked by the <command>lintian</command> command in
+ sponsoring packages) and checked in detail by the <command>lintian</command> command.
- details.
  </para>
  <para>
- Cleaning source and rebuilding package from a user account is as simple as:
+ Cleaning the source and rebuilding the package from your user account is as simple as:
  </para>
  <screen>
  $ debuild
  </screen>
  <para>
- Please note that the <command>dpkg-buildpackage</command> option
+ Here, if you are building Debian packages only for your own local use, you can skip
- <literal>-sa</literal> to include the original <filename>orig.tar.gz</filename>
+ promptings for the GPG signatures on the <filename>.dsc</filename> file and the
- source can be specified as:
+ <filename>.changes</filename> file like this:
  </para>
  <screen>
- $ debuild -sa
+ $ debuild -us -uc
  </screen>
  <para>
- You can clean source tree as simple as:
+ You can clean the source tree as simply as:
  </para>
  <screen>
  $ debuild clean
-Line 4010 
 $ debuild clean
+Line 4279 
 $ debuild clean
  <para>
  For a clean room (<command>chroot</command>) build environment to verify the
  build dependencies, the <systemitem role="package">pbuilder</systemitem>
- package is very useful.  <footnote><para> Since the <systemitem role="package">pbuilder</systemitem> package is still evolving, you have to
+ package is very useful.  <footnote><para> Since the <systemitem
+ role="package">pbuilder</systemitem> package is still evolving, you should
  check the actual configuration situation by consulting the latest official
  documentation.</para> </footnote> This ensures a clean build from the source
  under the <literal>sid</literal> auto-builder for different architectures and
- avoids the severity serious FTBFS (Fails To Build From Source) bug which is
+ avoids a severity serious FTBFS (Fails To Build From Source) bug which is
  always in the RC (release critical) category.
- <footnote><para>See <ulink url="&buildd-do;"/> for more on the
+ <footnote><para>See <ulink url="&buildd-do;"/> for more on
- auto-builder of the Debian package.</para></footnote>
+ Debian package auto-building.</para></footnote>
  </para>
  <para>
- Let's customize the <systemitem role="package">pbuilder</systemitem> package by
+ Let's customize the <systemitem role="package">pbuilder</systemitem> package as
- the following.
+ follows:
  </para>
  <itemizedlist>
  <listitem>
  <para>
- setting <filename>/var/cache/pbuilder/result</filename> directory writable by
+ setting the <filename>/var/cache/pbuilder/result</filename> directory writable by
- the user.
+ for your user account.
  </para>
  </listitem>
  <listitem>
  <para>
  creating a directory, e.g.
  <filename><replaceable>/var/cache/pbuilder/hooks</replaceable></filename>,
- writable by the user to place hook scripts.
+ writable by the user, to place hook scripts in.
  </para>
  </listitem>
  <listitem>
  <para>
- setting <filename>~/.pbuilderrc</filename> or
+ configuring <filename>~/.pbuilderrc</filename> or
- <filename>/etc/pbuilderrc</filename> to include as follows.
+ <filename>/etc/pbuilderrc</filename> to include the followsing.
  </para>
  <screen>
- AUTO_DEBSIGN=yes
+ AUTO_DEBSIGN=${AUTO_DEBSIGN:-yes}
  HOOKDIR=<replaceable>/var/cache/pbuilder/hooks</replaceable>
  </screen>
  </listitem>
-Line 4053 
 This will allow you to sign generated pa
+Line 4323 
 This will allow you to sign generated pa
  <filename>~/.gnupg/</filename> directory.
  </para>
  <para>
- Let's then initialize the local <systemitem role="package">pbuilder</systemitem> <command>chroot</command> system first as
+ First let's initialize the local <systemitem role="package">pbuilder</systemitem> <command>chroot</command> system as
  follows.
  </para>
  <screen>
  $ sudo pbuilder create
  </screen>
  <para>
- If you already have the completed source packages, issue the following commands
+ If you already have a completed source package, issue the following commands
  in the directory where the
  <filename><replaceable>foo</replaceable>.orig.tar.gz</filename>,
  <filename><replaceable>foo</replaceable>.debian.tar.gz</filename>, and
-Line 4070 
 the local <systemitem role="package">pbu
+Line 4340 
 the local <systemitem role="package">pbu
  </para>
  <screen>
  $ sudo pbuilder --update
- $ sudo pbuilder --build <replaceable>foo</replaceable>.dsc
+ $ sudo pbuilder --build <replaceable>foo_version</replaceable>.dsc
  </screen>
  <para>
- Please note that the <command>dpkg-buildpackage</command> option
+ The newly built packages without the GPG signatures will be located in
- <literal>-sa</literal> to include the original <filename>orig.tar.gz</filename>
+ <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.
- source can be specified as:
  </para>
- <screen>
- $ sudo pbuilder --build --debbuildopts -sa <replaceable>foo</replaceable>.dsc
- </screen>
  <para>
- The newly built packages will be located in
+ The GPG signatures on the <filename>.dsc</filename> file and the
- <filename>/var/cache/pbuilder/result/</filename> with non-root ownership.
+ <filename>.changes</filename> file can be generated as:
  </para>
+ <screen>
+ $ cd /var/cache/pbuilder/result/
+ $ debsign <replaceable>foo_version</replaceable>.dsc
+ $ debsign <replaceable>foo_version_arch</replaceable>.changes
+ </screen>
  <para>
- If you already have the updated source tree without generating the matching
+ If you have an updated source tree but have not generated the matching
- source packages, issue the following commands in the source directory where the
+ source package, issue the following commands in the source directory where the
  <filename>debian</filename> directory exists, instead.
  </para>
  <screen>
-Line 4094 
 $ sudo pbuilder --update
+Line 4365 
 $ sudo pbuilder --update
  $ pdebuild
  </screen>
  <para>
- Please note that the <command>dpkg-buildpackage</command> option
+ Here, if you are building Debian packages only for your local use, you can skip
- <literal>-sa</literal> to include the original <filename>orig.tar.gz</filename>
+ promptings for the GPG signatures on the <filename>.dsc</filename> file and the
- source can be specified as:
+ <filename>.changes</filename> file as:
  </para>
  <screen>
- $ pdebuild --debbuildopts -sa
+ $ AUTO_DEBSIGN=no pdebuild
  </screen>
  <para>
  You can log into its <command>chroot</command> environment with the
-Line 4113 
 the <literal>chroot</literal> environmen
+Line 4384 
 the <literal>chroot</literal> environmen
  <filename><replaceable>/var/cache/pbuilder/hooks</replaceable>/B90lintian</filename>
  configured as follows.  <footnote><para> This assumes
  <literal>HOOKDIR=/var/cache/pbuilder/hooks</literal>.  You can find many
- examples of the hook script in the
+ examples of hook scripts in the
  <filename>/usr/share/doc/pbuilder/examples</filename> directory.  </para>
  </footnote>
  </para>
-Line 4132 
 echo +++ end of lintian output +++
+Line 4403 
 echo +++ end of lintian output +++
  </screen>
  <para>
  You need to have access to the latest <literal>sid</literal> environment to
- build packages properly for <literal>sid</literal>.  In reality,
+ build packages properly for <literal>sid</literal>.  In practice,
- <literal>sid</literal> may be experiencing issues which makes it not desirable
+ <literal>sid</literal> may be experiencing issues which makes it undesirable
  for you to migrate your whole system.  The <systemitem role="package">pbuilder</systemitem> package can help you to cope with this
  kind of situation.
  </para>
-Line 4142 
 You may need to update your <literal>sta
+Line 4413 
 You may need to update your <literal>sta
  release for <literal>stable-proposed-updates</literal>,
  <literal>stable/updates</literal>, etc.  <footnote><para> There are some
  restrictions for such updates of your <literal>stable</literal> package.
- </para> </footnote> For such occasions, I am running <literal>sid</literal>
+ </para> </footnote> For such occasions, the fact you may be running a <literal>sid</literal>
- system is not good enough excuse not to update them promptly.  The <systemitem role="package">pbuilder</systemitem> package can help you to access
+ system is not a good enough excuse for failing to update them promptly.  The <systemitem role="package">pbuilder</systemitem> package can help you to access
- environments of almost any Debian derivative distributions of the same CPU
+ environments of almost any Debian derivative distribution of the same CPU
  architecture.
  </para>
  <para>
-Line 4158 
 See <ulink url="&pbuilder;"/>,
+Line 4429 
 See <ulink url="&pbuilder;"/>,
  </section>
  <section id="git-buildpackage"><title><command>git-buildpackage</command> command and similars</title>
  <para>
- If your upstream uses the source code management system (VCS)
+ If your upstream uses a source code management system (VCS)
  <footnote><para>See <ulink url="&debref-vcs;">Version control systems</ulink> for more.</para></footnote>
- to maintain their code, you should consider to use them.  That makes merging
+ to maintain their code, you should consider using it as well.  This makes merging
  and cherry-picking upstream patches much easier.  There are several specialized
- wrapper script packages for the Debian package building for each VCS.
+ wrapper script packages for Debian package building for each VCS.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <systemitem role="package">git-buildpackage</systemitem>: Suite to help with
+ <systemitem role="package">git-buildpackage</systemitem>: a suite to help with
  Debian packages in Git repositories.
  </para>
  </listitem>
-Line 4179 
 maintain Debian packages with Subversion
+Line 4450 
 maintain Debian packages with Subversion
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">cvs-buildpackage</systemitem>: A set of Debian
+ <systemitem role="package">cvs-buildpackage</systemitem>: a set of Debian
  package scripts for CVS source trees.
  </para>
  </listitem>
  </itemizedlist>
  <para>
- There are packages which <emphasis>automate</emphasis> building of packages
+ For advanced audiences, there are packages which <emphasis>automate</emphasis>
- under VCS managed source tree for advanced audiences.  I will not explain them
+ the building of packages under a VCS-managed source tree.  I will not explain them
  in this tutorial.
- <footnote><para> Here are few web resources available for advanced audiences.  </para>
+ <footnote><para> Here are some web resources available for advanced audiences.  </para>
  <itemizedlist>
  <listitem> <para> <ulink url="&git-buildpackage-doc;">Building Debian Packages with git-buildpackage</ulink> </para> </listitem>
  <listitem> <para> <ulink url="&debian-packages-git;">debian packages in git</ulink> </para> </listitem>
  <listitem> <para> <ulink url="&git-debian-packaging;">Using Git for Debian Packaging</ulink> </para> </listitem>
  <listitem> <para> <ulink url="&git-dpm;">git-dpm: Debian packages in Git manager</ulink> </para> </listitem>
  <listitem> <para> <ulink url="&topgit;">Using TopGit to generate quilt series for Debian packaging</ulink> </para> </listitem>
-Line 4202 
 in this tutorial.
+Line 4473 
 in this tutorial.
  <section id="quickrebuild"><title>Quick rebuild</title>
  <para>
  With a large package, you may not want to rebuild from scratch every time while
- you tune details in <filename>debian/rules</filename>.  For testing purposes,
+ you're tuning details in <filename>debian/rules</filename>.  For testing purposes,
  you can make a <filename>.deb</filename> file without rebuilding the upstream
- sources like this <footnote><para> Environment variables which are normally
+ sources like this<footnote><para> Environment variables which are normally
  configured to proper values are not set by this method.  Never create real
  packages to be uploaded using this <emphasis role="strong">quick</emphasis>
  method.  </para> </footnote>:
-Line 4213 
 method.  </para> </footnote>:
+Line 4484 
 method.  </para> </footnote>:
  $ fakeroot debian/rules binary
  </screen>
  <para>
- Or, simply as following to see if it build or not.
+ Or simply do the following to see if it builds or not:
  </para>
  <screen>
  $ fakeroot debian/rules build
-Line 4227 
 proper procedure.  You may not be able t
+Line 4498 
 proper procedure.  You may not be able t
  </chapter>
  <chapter id="checkit"><title>Checking the package for errors</title>
  <para>
- There are few chores you should know to check the package for errors by
+ There are some techniques you should know for checking a package for errors
- yourself before uploading packages to public archives.
+ before uploading it to the public archives.
  </para>
  <para>
- Testing on machine other than your own is also good idea.  You must watch
+ It's also a good idea to carry out testing on a machine other than your own.  You must watch
- closely for any warnings or errors for all the test described here.
+ closely for any warnings or errors for all the tests described here.
  </para>
- <section id="pinstall"><title>Verifying package for install</title>
+ <section id="inadvent"><title>Suspicious changes</title>
  <para>
- You must test your package if it installs without problem.  The <citerefentry>
+ If you find a new autogenerated patch file such as
+ <filename>debian-changes-*</filename> in the
+ <filename>debian/patches</filename> directory after building your non-native
+ Debian package in <literal>3.0 (quilt)</literal> format, chances are you
+ changed some files by accident or the build script modified the upstream
+ source.  If it is your mistake, fix it.  If it is caused by the build script,
+ fix the root cause with <command>dh-autoreconf</command> as in
+ <xref linkend="customrules"/> or work around it with
+ <filename>source/options</filename> as in <xref linkend="sourceopt"/>.
+ </para>
+ </section>
+ <section id="pinstall"><title>Verifying a package's installation</title>
+ <para>
+ You must test your package for whether it installs without problem.  The <citerefentry>
  <refentrytitle>debi</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
- command helps you to test to install all the generated binary packages.
+ command helps you to test installing all the generated binary packages.
  </para>
  <screen>
  $ sudo debi gentoo_0.9.12-1_i386.changes
  </screen>
  <para>
- You have to make sure that there are no overlapped files with other existing
+ To prevent installation problem on different systems, you must make
- packages using the
+ sure that there are no filenames conflicting with other existing packages,
+ using the
  <filename>Contents-<replaceable>i386</replaceable></filename> file downloaded
- from the Debian archive to prevent installation problem on different systems.
+ from the Debian archive,
  The <command>apt-file</command> command may be handy for this task.  If there
- are overlapped files, please take actions to avoid the real problem using the
+ are collisions, please take action to avoid this real problem, whether by
- alternatives mechanism (see <citerefentry>
+ renaming the file, moving a common file to a separate package that
- <refentrytitle>update-alternatives</refentrytitle> <manvolnum>1</manvolnum>
+ multiple packages can depend on, using the alternatives mechanism (see
- </citerefentry>) by coordinating with other affected packages or by setting the
+ <citerefentry><refentrytitle>update-alternatives</refentrytitle>
- <literal>Conflicts</literal> entry in the <filename>debian/control</filename>
+ <manvolnum>1</manvolnum></citerefentry>) in coordination with the
- file.
+ maintainers of other affected packages, or declaring a
+ <literal>Conflicts</literal> relationship in the
+ <filename>debian/control</filename> file.
  </para>
  </section>
- <section id="pmaintscripts"><title>Verifying package for <emphasis>maintainer scripts</emphasis></title>
+ <section id="pmaintscripts"><title>Verifying a package's maintainer scripts</title>
  <para>
- All <emphasis>maintainer scripts</emphasis>, i.e.,
+ All maintainer scripts (that is,
  <filename>preinst</filename>, <filename>prerm</filename>,
- <filename>postinst</filename>, and <filename>postrm</filename> files, are
+ <filename>postinst</filename>, and <filename>postrm</filename> files) are
- non-trivial unless they are auto-generated by the <systemitem role="package">debhelper</systemitem> programs.  So do not use them if you are
+ hard to write correctly unless they are auto-generated by the
+ <systemitem role="package">debhelper</systemitem> programs.  So do not use them if you are
  a novice maintainer (see <xref linkend="maintscripts"/>).
  </para>
  <para>
- If the package makes use of these non-trivial <emphasis>maintainer
+ If the package makes use of these non-trivial maintainer scripts, be sure to test not only for install but also for remove,
- scripts</emphasis>, be sure to test not only for install but also for remove,
+ purge, and upgrade processes.  Many maintainer script bugs show up
- purge, and upgrade.  Many <emphasis>maintainer script</emphasis> bugs show up
  when packages are removed or purged.  Use the <command>dpkg</command> command
  as follows to test them.
  </para>
-Line 4332 
 people will often be upgrading to your p
+Line 4619 
 people will often be upgrading to your p
  last Debian release.  Remember to test upgrades from that version too.
  </para>
  <para>
- Although downgrade is not officially supported, it should be nice to support
+ Although downgrading is not officially supported, supporting it is a
- it.
+ friendly gesture.
  </para>
  </section>
- <section id="lintians"><title><systemitem role="package">lintian</systemitem> package</title>
+ <section id="lintians"><title>Using <systemitem role="package">lintian</systemitem></title>
  <para>
  Run <citerefentry> <refentrytitle>lintian</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> on your <filename>.changes</filename>
-Line 4353 
 $ lintian -i -I --show-overrides gentoo_
+Line 4640 
 $ lintian -i -I --show-overrides gentoo_
  <para>
  Of course, replace the filename with the name of the
  <filename>.changes</filename> file generated for your package.  The output of
- the <command>lintian</command> command are marked as follows.
+ the <command>lintian</command> command uses the following flags.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <literal>E:</literal> for error; a sure policy violation or a packaging error.
+ <literal>E:</literal> for error; a sure policy violation or packaging error.
  </para>
  </listitem>
  <listitem>
  <para>
- <literal>W:</literal> for warning; a possible policy violation or a packaging
+ <literal>W:</literal> for warning; a possible policy violation or packaging
  error.
  </para>
  </listitem>
  <listitem>
  <para>
- <literal>I:</literal> for info; a information on certain packaging aspects.
+ <literal>I:</literal> for info; information on certain aspects of packaging.
  </para>
  </listitem>
  <listitem>
-Line 4386 
 error.
+Line 4673 
 error.
  </listitem>
  </itemizedlist>
  <para>
- For warnings, tune the package to avoid them or verify that the warnings are
+ When you see warnings, tune the package to avoid them or verify that the warnings are
- spurious.  If spurious, set the <filename>lintian-overrides</filename> files as
+ spurious.  If spurious, set up <filename>lintian-overrides</filename> files as
  described in <xref linkend="lintian"/>.
  </para>
  <para>
  Note that you can build the package with <command>dpkg-buildpackage</command>
- and run <command>lintian</command> on it in one command with <citerefentry>
+ and run <command>lintian</command> on it in one command, if you use <citerefentry>
  <refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
- or with <citerefentry> <refentrytitle>pdebuild</refentrytitle>
+ or <citerefentry> <refentrytitle>pdebuild</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry>.
  </para>
  </section>
- <section id="debc"><title><command>debc</command> command</title>
+ <section id="debc"><title>The <command>debc</command> command</title>
  <para>
- You can list files in the binary Debian package by <citerefentry>
+ You can list files in the binary Debian package with the <citerefentry>
  <refentrytitle>debc</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
  command.
  </para>
-Line 4408 
 command.
+Line 4695 
 command.
  $ debc <replaceable>package</replaceable>.changes
  </screen>
  </section>
- <section id="debdiff"><title><command>debdiff</command> command</title>
+ <section id="debdiff"><title>The <command>debdiff</command> command</title>
  <para>
  You can compare file contents in two source Debian packages with the
  <citerefentry> <refentrytitle>debdiff</refentrytitle> <manvolnum>1</manvolnum>
-Line 4426 
 You can also compare file lists in two s
+Line 4713 
 You can also compare file lists in two s
  $ debdiff <replaceable>old-package</replaceable>.changes <replaceable>new-package</replaceable>.changes
  </screen>
  <para>
- These are useful to identify what has been changed in the source packages, if
+ These are useful to identify what has been changed in the source packages
- no files have been unintentionally misplaced or removed in the binary packages,
+ and to check for inadvertent changes made when updating binary
- and if no other inadvertent changes were made when updating binary packages.
+ packages, such as unintentionally misplacing or removing files.
  </para>
  </section>
- <section id="interdiff"><title><command>interdiff</command> command</title>
+ <section id="interdiff"><title>The <command>interdiff</command> command</title>
  <para>
  You can compare two <filename>diff.gz</filename> files with the <citerefentry>
  <refentrytitle>interdiff</refentrytitle> <manvolnum>1</manvolnum>
-Line 4448 
 files as described in <xref linkend="pat
+Line 4735 
 files as described in <xref linkend="pat
  <filename>debian/patches/*</filename> file using <command>interdiff</command>, too.
  </para>
  </section>
- <section id="mc"><title><command>mc</command> command</title>
+ <section id="mc"><title>The <command>mc</command> command</title>
  <para>
  Many of these file inspection operations can be made into an intuitive process
  by using a file manager like <citerefentry> <refentrytitle>mc</refentrytitle>
-Line 4460 
 contents of <filename>*.deb</filename> p
+Line 4747 
 contents of <filename>*.deb</filename> p
  <para>
  Be on the lookout for extra unneeded files or zero length files, both in the
  binary and source package.  Often cruft doesn't get cleaned up properly; adjust
- your <filename>rules</filename> file to compensate for that.
+ your <filename>rules</filename> file to compensate for this.
  </para>
  </section>
  </chapter>
-Line 4473 
 a public archive to share it.
+Line 4760 
 a public archive to share it.
  <para>
  Once you become an official developer,
  <footnote><para>
- See <xref linkend="debiandeveloper"/>.
+ See <xref linkend="socialdynamics"/>.
  </para></footnote>
  you can upload the package to the Debian archive.
  <footnote><para>
  There are publicly accessible archives such as <ulink url="&mentors-dn;"/>
- which work almost the same way as Debian archive and provide upload area for
+ which work almost the same way as the Debian archive and provide an upload area for
- the non-DD.  You can set up an equivalent archive by yourself using tools
+ non-DDs.  You can set up an equivalent archive by yourself using the tools
- listed at <ulink url="&deb-archive;"/>.  So this section is useful for the
+ listed at <ulink url="&deb-archive;"/>.  So this section is useful for
- non-DD, too.
+ non-DDs, too.
  </para></footnote>
  You can do this manually, but it's easier to use the existing
  automated tools, like <citerefentry> <refentrytitle>dupload</refentrytitle>
-Line 4489 
 automated tools, like <citerefentry> <re
+Line 4776 
 automated tools, like <citerefentry> <re
  <refentrytitle>dput</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.
  We'll describe how it's done with <command>dupload</command>.  <footnote><para>
  The <systemitem role="package">dput</systemitem> package seems to come with
- more features and becoming more popular than the <systemitem role="package">dupload</systemitem> package.  It uses the
+ more features and to be becoming more popular than the <systemitem role="package">dupload</systemitem> package.  It uses the
- <filename>/etc/dput</filename> file for the global configuration and the
+ file <filename>/etc/dput</filename> for its global configuration and the
- <filename>~/.dput.cf</filename> file for the per-user one.  It supports Ubuntu
+ file <filename>~/.dput.cf</filename> for per-user configuration.  It supports
- related services out-of-box, too.  </para> </footnote>
+ Ubuntu-related services out-of-the-box, too.  </para> </footnote>
  </para>
  <para>
  First you have to set up <command>dupload</command>'s config file.  You can
-Line 4509 
 these options means.
+Line 4796 
 these options means.
  The <literal>$default_host</literal> option determines which of the upload
  queues will be used by default.  <literal>anonymous-ftp-master</literal> is the
  primary one, but it's possible that you will want to use another one.
- <footnote><para>See <ulink url="&devref-upload;">Debian Developer's Reference 5.6. 'Uploading a package'</ulink>.</para></footnote>
+ <footnote><para>See <ulink url="&devref-upload;">Debian Developer's Reference 5.6. "Uploading a package"</ulink>.</para></footnote>
  </para>
  <para>
- While connected to the Internet, you can upload your package by the following:
+ While connected to the Internet, you can upload your package as follows:
  </para>
  <screen>
  $ dupload gentoo_0.9.12-1_i386.changes
  </screen>
  <para>
- <command>dupload</command> checks that the MD5/SHA1/SHA256 checksums of the
+ <command>dupload</command> checks that the SHA1/SHA256 file checksums
- files match those from the <filename>.changes</filename> file.  If they do not
+ match those listed in the <filename>.changes</filename> file.  If they do not
  match, it will warn you to rebuild it as described in <xref linkend="completebuild"/> so it can be properly uploaded.
  </para>
  <!--
-Line 4529 
 will ask for your password on Debian mac
+Line 4816 
 will ask for your password on Debian mac
  -->
  <para>
  If you encounter an upload problem at <ulink url="&uploadqueue;"/>, you can fix this
- by manually uploading GPG signed <filename>*.commands</filename> file to there
+ by manually uploading a GPG-signed <filename>*.commands</filename> file to there
- with <command>ftp</command>.  <footnote><para> See <ulink url="&uploadqueue-readme;"/>.  Alternatively, you may
+ with <command>ftp</command>.  <footnote><para> See <ulink url="&uploadqueue-readme;"/>.  Alternatively, you can
- use <command>dcut</command> command from the <systemitem role="package">dput</systemitem> package.  </para> </footnote> For example, use
+ use the <command>dcut</command> command from the <systemitem
+ role="package">dput</systemitem> package.  </para> </footnote> For example, using
  <filename>hello.commands</filename>:
  </para>
  <screen>
  -----BEGIN PGP SIGNED MESSAGE-----
+ Hash: SHA1
  Uploader: Foo Bar &lt;Foo.Bar@example.org&gt;
  Commands:
   rm hello_1.0-1_i386.deb
   mv hello_1.0-1.dsx hello_1.0-1.dsc
  -----BEGIN PGP SIGNATURE-----
- Version: 2.6.3ia
+ Version: GnuPG v1.4.10 (GNU/Linux)
- iQCVAwUBNFiQSXVhJ0HiWnvJAQG58AP+IDJVeSWmDvzMUphScg1EK0mvChgnuD7h