/[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 8611 by osamu,
Thu Mar 31 16:47:55 2011 UTC
+revision 8786 by osamu,
Tue May  3 01:59:08 2011 UTC
 Line 2
  <!-- -*- DocBook -*- -->
  <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+ <!ENTITY % trans    SYSTEM "po4a/maint-guide.en.ent">   %trans;
  <!ENTITY % common   SYSTEM "common.ent">   %common;
  <!ENTITY % version  SYSTEM "version.ent">  %version;
  ]>
  <book lang="en">
  <!-- This is UTF-8 encoded. -->
- <title>Debian New Maintainers' Guide</title>
+ <!--
- <bookinfo>
+ This is reorganized to make this document robust for translation
- <authorgroup>
+ when some externally referenced information changes.
- <author> <personname> <firstname>Josip</firstname> <surname>Rodin</surname> </personname> <email>joy-mg@debian.org</email> <contrib>(original contents)</contrib> </author>
- <author> <personname> <firstname>Osamu</firstname> <surname>Aoki</surname> </personname> <email>osamu@debian.org</email> <contrib>(updated contents)</contrib> </author>
- <!-- BEGIN: Add othercredit for translator via po4a/maint-guide.*.patch -->
+ If you want to add extra contents to this document, please do so by
- <!-- END: Add othercredit for translator via po4a/maint-guide.*.patch -->
+  * adding tag like &othercredit; in English and provide it for each language.
+  * add extra content within msgstr but within <footnote>...</footnote>
+ Please note there will be content checker to match tags of msgid and msgstr.
+ The second rule is a way to get exception to this rule.
+ Please try to correct something in translation.  If you think contents needs fix,
+ Let's fix it in the root cause.
+ Please understand to keep this document focused.  Not everything you think important
+ for new maintainer should be written down.  Something social needs to be elsewhere.
+ Some thing should be left to the practice.  Something needs to be left for exercise
+ for people to check official documentations.
+ -->
+ <title>Debian New Maintainers' Guide</title>
+ <bookinfo>
+ <authorgroup>
+ <!-- do not use firstname and surname tags it braks Japanese.  The same with othercredit -->
+ <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>
  <releaseinfo>version &docversion;</releaseinfo>
  <pubdate>&docisodate;</pubdate>
-Line 33 
 version 2 or higher.
+Line 49 
 version 2 or higher.
  <para>
  This document was made using with these two documents as examples:
  </para>
+ <itemizedlist>
+ <listitem>
  <para>
  Making a Debian Package (AKA the Debmake Manual), copyright © 1997 Jaldhar
  Vyas.
  </para>
+ </listitem>
+ <listitem>
  <para>
  The New-Maintainer's Debian Packaging Howto, copyright © 1997 Will Lowe.
  </para>
+ </listitem>
+ </itemizedlist>
  </legalnotice>
  <!-- toc -->
  </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>squeeze</literal>
+ This document has been updated for the Debian <literal>&base-release;</literal>
- release.  <footnote><para> The document assumes you are using the
+ release.
- <literal>squeeze</literal> system.  If you need to follow this text in the
+ <footnote><para> The document assumes you are using a
- <literal>lenny</literal> system, you must install backported <systemitem role="package">dpkg</systemitem> and <systemitem role="package">debhelper</systemitem> packages, at least.  </para> </footnote>
+ <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.
+ </para> </footnote>
  </para>
  <para>
  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 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
+ If you need some help on packaging, please read <xref linkend="helpme"/>.
- 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"/> .
+ 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>
  <para>
- Newer versions of this document should always be available online at <ulink url="http://www.debian.org/doc/maint-guide/">http://www.debian.org/doc/maint-guide/</ulink>
+ Since this is a tutorial, I choose to explain each detailed step for some
- and in the <systemitem role="package">maint-guide</systemitem> package.
+ 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>
-  Translation in [[this language]] is also available in the
- <systemitem role="package">maint-guide-xy</systemitem> package.
- -->
- <section id="needprogs"><title>Programs you need for development</title>
  <para>
- Before you start anything, you should make sure that you have properly
+ Here are some observations of Debian's social dynamics, presented in the hope
- installed some additional packages needed for development.  Note that the list
+ that it will prepare you for interactions with Debian.
- doesn't contain any packages marked <literal>essential</literal> or
- <literal>required</literal> - we expect that you have those installed already.
  </para>
+ <itemizedlist>
+ <listitem><para>We all are volunteers.</para>
+     <itemizedlist>
+     <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>
+     <itemizedlist>
+     <listitem><para>Your contribution should not overstrain others.</para></listitem>
+     <listitem><para>Your contribution is valuable only when others appreciate it.</para></listitem>
+     </itemizedlist></listitem>
+ <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 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 change.</para></listitem>
+     </itemizedlist></listitem>
+ </itemizedlist>
  <para>
- The following packages come with the standard Debian installation, so you
+ There are several types of people interacting around Debian with different
- probably have them already (along with any additional packages they depend on).
+ roles.
- Still, you should check it with <literal>aptitude show
- <replaceable>package</replaceable></literal>.
  </para>
+ <itemizedlist>
+ <listitem>
  <para>
- The most important package to install on your development system is the
+ <emphasis role="strong">upstream author</emphasis>: the person who made the
- <systemitem role="package">build-essential</systemitem> package.  Once you try
+ original program.
- to install it, it will <emphasis>pull in</emphasis> other packages required to
- have a basic build environment.
  </para>
+ </listitem>
+ <listitem>
  <para>
- For some types of packages, that is all you will require, however there is
+ <emphasis role="strong">upstream maintainer</emphasis>: the person who
- another set of packages that while not essential for all package builds are
+ currently maintains the program.
- useful to have install or may be required by your package:
  </para>
- <itemizedlist>
+ </listitem>
  <listitem>
  <para>
- <systemitem role="package">file</systemitem> - this handy program can determine
+ <emphasis role="strong">maintainer</emphasis>: the person making the Debian
- what type a file is.  (see <citerefentry> <refentrytitle>file</refentrytitle>
+ package of the program.
- <manvolnum>1</manvolnum> </citerefentry>)
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">patch</systemitem> - this very useful utility will
+ <emphasis role="strong">sponsor</emphasis>: a person who helps maintainers to
- take a file containing a difference listing (produced by the
+ upload packages to the official Debian package archive (after checking their
- <command>diff</command> program) and apply it to the original file, producing a
+ contents).
- 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
+ <emphasis role="strong">mentor</emphasis>: a person who helps novice
- interpreted scripting languages on today's Unix-like systems, often referred to
+ maintainers with packaging etc.
- 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
+ <emphasis role="strong">Debian Developer</emphasis> (DD): a member of
- used interpreted scripting languages on the Debian system that combines
+ the Debian project with full upload rights to the official Debian package
- remarkable power with very clear syntax.  (see <citerefentry>
+ archive.
- <refentrytitle>python</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>)
  </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
+ <emphasis role="strong">Debian Maintainer</emphasis> (DM): a person with
- scripts and <filename>Makefile</filename> files preprocessed with help of
+ limited upload rights to the official Debian package archive.
- programs like these.  (see <literal>info autoconf</literal>, <literal>info
+ </para>
- automake</literal>).  The <systemitem role="package">autotools-dev</systemitem>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Please note that you cannot become an official
+ <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
+ <emphasis role="strong">sponsor</emphasis> or as a
+ <emphasis role="strong">Debian Maintainer</emphasis>.
+ </para>
+ <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 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 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
+ doesn't contain any packages marked <literal>essential</literal> or
+ <literal>required</literal> - we expect that you have those installed already.
+ </para>
+ <para>
+ The following packages come with the standard Debian installation, so you
+ probably have them already (along with any additional packages they depend on).
+ Still, you should check it with <literal>aptitude show
+ <replaceable>package</replaceable></literal>
+ or with <literal>dpkg -s <replaceable>package</replaceable></literal>.
+ </para>
+ <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 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
+ another set of packages that while not essential for all package builds are
+ useful to have installed or may be required by your package:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <systemitem role="package">autoconf</systemitem>, <systemitem
+ role="package">automake</systemitem>, and <systemitem
+ role="package">autotools-dev</systemitem> - many newer programs use configure
+ scripts and <filename>Makefile</filename> files preprocessed with the help of
+ programs like these (see <literal>info autoconf</literal>, <literal>info
+ automake</literal>).  <systemitem role="package">autotools-dev</systemitem>
  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">debhelper</systemitem> and
- example package, and it will use some of the <systemitem role="package">debhelper</systemitem> tools for creating packages.  They are
+ <systemitem role="package">dh-make</systemitem> -
- not essential for creation of packages, but are <emphasis>highly</emphasis>
+ <systemitem role="package">dh-make</systemitem> is necessary to create
- recommended for new maintainers.  It makes the whole process very much easier
+ the skeleton of our example package, and it will use some of the
- to start, and control afterwards.  (see <citerefentry>
+ <systemitem role="package">debhelper</systemitem> tools for creating
- <refentrytitle>dh_make</refentrytitle> <manvolnum>1</manvolnum>
+ packages.  They are not essential for this purpose, but are
- </citerefentry>, <citerefentry> <refentrytitle>debhelper</refentrytitle>
+ <emphasis>highly</emphasis> recommended for new maintainers.  It makes
- <manvolnum>1</manvolnum> </citerefentry>,
+ the whole process very much easier to start, and to control afterwards.
- <filename>/usr/share/doc/debhelper/README</filename>) <footnote><para> There
+ (See <citerefentry> <refentrytitle>dh_make</refentrytitle>
- 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>
+ <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">devscripts</systemitem> - this package contains some
- nice and useful scripts that can be helpful to the maintainers, but they are
+ useful scripts that can be helpful for maintainers, but they are also
- also not necessary for building packages.  Packages recommended and suggested
+ not necessary for building packages.  Packages recommended and suggested
- by this package are worth looking into.  (see
+ by this package are worth looking into.  (See <ulink url="&devscripts-readme;"/>.)
- <filename>/usr/share/doc/devscripts/README.gz</filename>)
  </para>
  </listitem>
  <listitem>
  <para>
  <systemitem role="package">fakeroot</systemitem> - this utility lets you
  emulate being root which is necessary for some parts of the build process.
- (see <citerefentry> <refentrytitle>fakeroot</refentrytitle>
+ (See <citerefentry> <refentrytitle>fakeroot</refentrytitle>
- <manvolnum>1</manvolnum> </citerefentry>)
+ <manvolnum>1</manvolnum> </citerefentry>.)
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">gnupg</systemitem> - a tool that enables you to
+ <systemitem role="package">file</systemitem> - this handy program can determine
- digitally <emphasis>sign</emphasis> packages.  This is especially important if
+ what type a file is.  (See <citerefentry> <refentrytitle>file</refentrytitle>
- you want to distribute it to other people, and you will certainly be doing that
+ <manvolnum>1</manvolnum> </citerefentry>.)
- when your work gets included in the Debian distribution.  (see <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>
+ necessary if your program is written in Fortran.  (See <citerefentry>
  <refentrytitle>gfortran</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry>)
+ </citerefentry>.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <systemitem role="package">git</systemitem> - this package provides a popular
+ version control system designed to handle very large projects with speed and
+ efficiency; it is used for many high profile open source projects, most notably
+ the Linux kernel.  (See <citerefentry> <refentrytitle>git</refentrytitle>
+ <manvolnum>1</manvolnum> </citerefentry>,
+ <ulink url="&git-doc;">git Manual</ulink>.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <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>
+ <refentrytitle>gpg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.)
  </para>
  </listitem>
  <listitem>
-Line 208 
 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>.)
- <filename>/usr/share/doc/lintian/lintian.html/index.html</filename>)
+ </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 248 
 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>.)
- <filename>/usr/share/doc/quilt/README.Debian</filename>)
  </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>
- <filename>/usr/share/doc/git-doc/index.html</filename>)
+ <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 read the documentation
+ 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.
+ If you have specific questions later, I would suggest re-reading the documents
+ mentioned above.
+ </para>
+ </section>
+ <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:
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <systemitem role="package">debian-policy</systemitem> - the <ulink url="http://www.debian.org/doc/devel-manuals#policy">Debian Policy
+ <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 Filesystem Hierarchy Standard
+ Debian archive, several OS design issues, the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink>
- (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
+ satisfy to be included in the distribution. (See the local copies of
- <filename>&debian-policy;</filename>).
+ <ulink url="&policy-pdf;">policy.pdf</ulink> and <ulink url="&fhs-pdf;">fhs-2.3.pdf</ulink>.)
  </para>
  </listitem>
  <listitem>
  <para>
- <systemitem role="package">developers-reference</systemitem> - the <ulink url="http://www.debian.org/doc/devel-manuals#devref">Debian Developer's
+ <systemitem role="package">developers-reference</systemitem>
- Reference</ulink> describes all matters not specifically about the technical
+ - 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
+ when and where to upload etc.  (See the local copy of
- <filename>&developers-reference;</filename>).
+ <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="http://www.lrde.epita.fr/~adl/autotools.html">Autotools
+ <ulink url="&autotools-tutorial;">Autotools
- Tutorial</ulink> provides very good tutorial for <ulink url="http://en.wikipedia.org/wiki/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 311 
 Automake, Libtool, and gettext.
+Line 474 
 Automake, Libtool, and gettext.
  <listitem>
  <para>
  <systemitem role="package">gnu-standards</systemitem> - this package contains
- two pieces of documentation from the GNU project: <ulink url="http://www.gnu.org/prep/standards/html_node/index.html">GNU Coding
+ two pieces of documentation from the GNU project:
- Standards</ulink>, and <ulink url="http://www.gnu.org/prep/maintain/html_node/index.html">Information for
+ <ulink url="&gnu-standard;">GNU Coding Standards</ulink>, and
- Maintainers of GNU Software</ulink>.  Although Debian does not require these to
+ <ulink url="&gnu-maintainer;">Information for Maintainers of GNU Software</ulink>.
- be followed, these are still helpful as guidelines and common sense.  (see
+ Although Debian does not require these to
- <filename>/usr/share/doc/gnu-standards/standards.html</filename> and
+ be followed, these are still helpful as guidelines and common sense.
- <filename>/usr/share/doc/gnu-standards/maintain.html</filename>).
+ (See the local copies of
+ <ulink url="&gnu-standard-pdf;">standards.pdf</ulink> and
+ <ulink url="&gnu-maintainer-pdf;">maintain.pdf</ulink>.)
  </para>
  </listitem>
  </itemizedlist>
  <para>
- If this document contradicts with what the Debian Policy Manual and Debian
+ If this document contradicts any of the documents mentioned above, they
- Developer's Reference describes, they are correct.  Please file a bug report on
+ are correct.  Please file a bug report on the
- the <systemitem role="package">maint-guide</systemitem> package.
+ <systemitem role="package">maint-guide</systemitem> package using
- </para>
+ <command>reportbug</command>.
- <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
- of each program, 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>
  </section>
- <section id="terminology"><title>Basic terminology</title>
+ <section id="helpme"><title>Where to ask for help</title>
  <para>
- There are two types of packages.
+ Before you decide to ask your question in some public place, please read the fine documentation.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <emphasis role="strong">source package</emphasis>: A source package is a set of
+ files in <filename>/usr/share/doc/<replaceable>package</replaceable></filename> for all pertinent packages
- 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
+ contents of <literal><command>man</command> <replaceable>command</replaceable></literal> for all pertinent commands
- 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
+ contents of <literal><command>info</command> <replaceable>command</replaceable></literal> for all pertinent commands
- original program.
  </para>
  </listitem>
  <listitem>
  <para>
- <emphasis role="strong">upstream maintainer</emphasis>: The person who
+ contents of <ulink url="&debian-mentors-ldo;">debian-mentors@lists.debian.org mailing list archive</ulink>
- currently maintains the program.
  </para>
  </listitem>
  <listitem>
  <para>
- <emphasis role="strong">maintainer</emphasis>: The person who makes Debian
+ contents of <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org mailing list archive</ulink>
- package of the program.
  </para>
  </listitem>
- <listitem>
+ </itemizedlist>
  <para>
- <emphasis role="strong">sponsor</emphasis>: The person who helps maintainers to
+ You can use web search engines more effectively by including search strings
- upload packages to the official Debian Package Archive after checking their
+ such as <literal>site:lists.debian.org</literal> to limit the domain.
- contents.
  </para>
- </listitem>
- <listitem>
  <para>
- <emphasis role="strong">mentor</emphasis>: The person who helps novice
+ Making a small test package is a good way to learn details of packaging.
- maintainers on packaging etc.
+ Inspecting existing well maintained packages is the best way to learn how other
+ people make packages.
  </para>
- </listitem>
- <listitem>
  <para>
- <emphasis role="strong">Debian Developer</emphasis> (DD): The person who is a
+ If you still have questions about packaging that you couldn't find answers to
- member of Debian.  He has full upload right to the official Debian Package
+ in the available documentation and web resources, you can ask them interactively.
- Archive.
  </para>
- </listitem>
+ <itemizedlist>
  <listitem>
  <para>
- <emphasis role="strong">Debian Maintainer</emphasis> (DM): The person who has
+ <ulink url="&debian-mentors-ldo;">debian-mentors@lists.debian.org mailing list</ulink>. (This mailing list is for the novice.)
- limited upload right to the official Debian Package Archive.
  </para>
  </listitem>
- </itemizedlist>
- <para>
- There are several version names used around Debian.
- </para>
- <itemizedlist>
  <listitem>
  <para>
- <emphasis role="strong">upstream source version</emphasis>: The upstream source
+ <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org mailing list</ulink>. (This mailing list is for the expert.)
- version is referred as <literal><replaceable>version</replaceable></literal>.
  </para>
  </listitem>
  <listitem>
  <para>
- <emphasis role="strong">Debian revision</emphasis>: The revision by Debian on
+ <ulink url="&irc-debian;">IRC</ulink> such as <literal>#debian-mentors</literal>.
- package is referred as <literal><replaceable>revision</replaceable></literal>.
  </para>
  </listitem>
- <listitem>
+ </itemizedlist>
  <para>
- <emphasis role="strong">Debian package version</emphasis>: The Debian package
+ The more experienced Debian developers will gladly help you, if you ask
- version is referred as the following.
+ properly after making your required efforts.
  </para>
- <itemizedlist>
- <listitem>
  <para>
- <literal><replaceable>version</replaceable></literal> for the native Debian
+ When you receive a bug report (yes, actual bug reports!), you will know that it
- binary package and for the Debian source package.
+ 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>.
  </para>
- </listitem>
- <listitem>
  <para>
- <literal><replaceable>version</replaceable>-<replaceable>revision</replaceable></literal>
+ Even if it all worked well, it's time to start praying.  Why?  Because in just
- for the non-native Debian binary package.
+ a few hours (or days) users from all around the world will start to use your
+ package, and if you made some critical error you'll get mailbombed by numerous
+ angry Debian users...  Just kidding.  :-)
  </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
  <para>
- Please read the other manuals if you need more details on terminology.
+ Relax and be ready for bug reports, because there is a lot more work to be done
+ before your package will be fully in line with Debian policies and its best
+ practice guidelines (once again, read the <emphasis>real
+ documentation</emphasis> for details).  Good luck!
  </para>
  </section>
- <section id="debiandeveloper"><title>Official Debian Developer</title>
+ </chapter>
+ <chapter id="first"><title>First steps</title>
  <para>
- You can not become an official <emphasis role="strong">Debian
+ Let's start by creating a package of your own (or, even better,
- Developer</emphasis> (DD) over night because it takes more than technical
+ adopting an existing one).
- 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 <emphasis role="strong">sponsor</emphasis> or as a <emphasis role="strong">Debian
- Maintainer</emphasis>.  See <ulink url="&newmaint;">Debian New
- Maintainers</ulink> for more.
  </para>
+ <section id="workflow"><title>Debian package building workflow</title>
  <para>
- Please note that you do not need to create any new package to become an
+ If you are making a Debian package with an upstream program, the
- official Debian Developer.  Contributing to the existing packages can provide a
+ typical workflow of Debian package building involves generating several
- path to become an official Debian Developer too.  There are many packages
+ specifically named files for each step as follows.
- waiting for good maintainers (see <xref linkend="choose"/> ).
  </para>
- </section>
+ <itemizedlist>
- <section id="helpme"><title>Where to ask for help</title>
+ <listitem>
- <!--
+ <para>Get a copy of the upstream software, usually in a compressed tar format.</para>
-  /usr/share/doc/debian is used be doc-debian and debian-faq
+   <itemizedlist>
- -->
+   <listitem><literal><replaceable>package</replaceable>-<replaceable>version</replaceable>.tar.gz</literal></listitem>
+   </itemizedlist>
+ </listitem>
+ <listitem>
  <para>
- Before you decide to ask your question in some public place, please just RTFM.
+ Add Debian-specific packaging modifications to the upstream program under the
- That includes documentation in <filename>/usr/share/doc/dpkg</filename>,
+ <filename>debian</filename> directory, and create a non-native source package
- <filename>/usr/share/doc/debian</filename>,
+ (that is, the set of input files used for Debian package building) in
- <filename>&autotools-dev;</filename>,
+ <literal>3.0 (quilt)</literal> format.
- <filename>/usr/share/doc/<replaceable>package</replaceable>/*</filename> files
- and the <command>man</command>/<command>info</command> pages for all the
- programs mentioned in this document.  See all the information at <ulink url="&nm-home;">&nm-home;</ulink>.
  </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>
- Making a small test package is good way to learn details of packaging.
+ 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.
- Inspecting existing well maintained packages is the best way to learn how other
- people make packages.
  </para>
+   <itemizedlist>
+   <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>-<replaceable>revision</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
+   </itemizedlist>
+ </listitem>
+ </itemizedlist>
  <para>
- If you still have questions about packaging that you couldn't find answers to
+ Please note that the character separating
- in the available documentation and web resources, you can ask them on the
+ <literal><replaceable>package</replaceable></literal> and
- Debian Mentors' mailing list at <ulink url="http://lists.debian.org/debian-mentors/">debian-mentors@lists.debian.org</ulink>.
+ <literal><replaceable>version</replaceable></literal> was changed from
- The more experienced Debian developers will gladly help you, but do read at
+ <literal>-</literal> (hyphen) in the tarball name to
- least some of the documentation before asking a question!
+ <literal>_</literal> (underscore) in the Debian package filenames.
  </para>
  <para>
- See <ulink url="http://lists.debian.org/debian-mentors/">http://lists.debian.org/debian-mentors/</ulink>
+ In the file names above, replace
- for more information about this mailing list.
+ 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>
- When you receive a bug report (yes, actual bug reports!), you will know that it
+ If instead you are making a Debian-specific package with no upstream, the
- is time for you to dig into the <ulink url="http://www.debian.org/Bugs/">Debian
+ typical workflow of Debian package building is simpler.
- 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="http://www.debian.org/doc/manuals/developers-reference/pkgs.html#bug-handling">Developer's
- Reference, 5.8.  'Handling bugs'</ulink>.
  </para>
+ <itemizedlist>
+ <listitem>
  <para>
- If you still have questions, ask on the Debian Developers' mailing list at
+ Create a native Debian source package in the <literal>3.0 (native)</literal>
- <ulink url="http://lists.debian.org/debian-devel/">debian-devel@lists.debian.org</ulink>.
+ format using a single compressed tar file in which all files are included.
- See <ulink url="http://lists.debian.org/debian-devel/">http://lists.debian.org/debian-devel/</ulink>
- for more information about this mailing list.
  </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>
- Even if it all worked well, it's time to start praying.  Why?  Because in just
+ Build Debian binary packages from the native Debian source package.
- a few hours (or days) users from all around the world will start to use your
- package, and if you made some critical error you'll get mailbombed by numerous
- angry Debian users...  Just kidding.  :-)
  </para>
+   <itemizedlist>
+   <listitem><literal><replaceable>package</replaceable>_<replaceable>version</replaceable>_<replaceable>arch</replaceable>.deb</literal></listitem>
+   </itemizedlist>
+ </listitem>
+ </itemizedlist>
  <para>
- Relax and be ready for bug reports, because there is a lot more work to be done
+ Each step of this outline is explained with detailed examples in later sections.
- before your package will be fully in line with Debian policies and its best
- practice guidelines (once again, read the <emphasis>real
- documentation</emphasis> for details).  Good luck!
  </para>
  </section>
- </chapter>
- <chapter id="first"><title>First steps</title>
- <para>
- Let's try to make your own package (or, better even, adopt an existing one).
- </para>
  <section id="choose"><title>Choose your program</title>
  <para>
  You have probably chosen the package you want to create.  The first thing you
  need to do is check if the package is in the distribution archive already by
- using <command>aptitude</command>.
+ using the following.
- </para>
- <para>
- You can also check package information through <ulink url="http://www.debian.org/distrib/packages">package search page</ulink> and
- <ulink url="http://packages.qa.debian.org/common/index.html">Debian Package
- Tracking System</ulink>.
  </para>
+ <itemizedlist>
+ <listitem>
+ <para>the <command>aptitude</command> command</para>
+ </listitem>
+ <listitem>
+ <para>the <ulink url="&packages-do;">Debian packages</ulink> web page</para>
+ </listitem>
+ <listitem>
+ <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="http://qa.debian.org/">Debian QA Group</ulink>, you may be able to
+ maintainer is set to <ulink url="&qa-do;">Debian QA Group</ulink>),
- pick it up if it's still available (check the ownership status at <ulink url="http://bugs.debian.org/wnpp">Debian Bug report logs: Bugs in package wnpp
+ you may be able to pick it up if it's still available.  You may also
- in unstable</ulink>).  You may also adopt a package for which the corresponding
+ adopt a package whose maintainer has filed a Request for Adoption
- 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>
- Several different views of orphaned or RFA'ed packages are available at:
+ There are several package ownership status resources.
  </para>
  <itemizedlist>
  <listitem>
- <para>
+ <para> <ulink url="&wnpp-do;">Work-Needing and Prospective Packages</ulink> </para>
- <ulink url="http://www.debian.org/devel/wnpp/">Work-Needing and Prospective
- Packages</ulink>
- </para>
  </listitem>
  <listitem>
- <para>
+ <para> <ulink url="&wnpp-bts;">Debian Bug report logs: Bugs in pseudo-package <systemitem role="package">wnpp</systemitem> in <literal>unstable</literal></ulink> </para>
- <ulink url="http://wnpp.debian.net/">Debian Packages that Need Lovin'</ulink>
- </para>
  </listitem>
  <listitem>
- <para>
+ <para> <ulink url="&wnpp-dn;">Debian Packages that Need Lovin'</ulink> </para>
- <ulink url="http://members.hellug.gr/serzan/wnpp/">Browse WNPP bugs based on
+ </listitem>
- debtags</ulink>
+ <listitem>
- </para>
+ <para> <ulink url="&wnpp-debtags;">Browse <systemitem role="package">wnpp</systemitem> bugs based on debtags</ulink> </para>
  </listitem>
  </itemizedlist>
  <para>
-Line 573 
 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 584 
 taking over orphaned, yet actively used,
+Line 734 
 taking over orphaned, yet actively used,
  </listitem>
  <listitem>
  <para>
- joining <ulink url="http://wiki.debian.org/Teams">packaging teams</ulink>
+ joining <ulink url="&teams;">packaging teams</ulink>
  </para>
  </listitem>
  <listitem>
-Line 594 
 triaging bugs of very popular packages
+Line 744 
 triaging bugs of very popular packages
  </listitem>
  <listitem>
  <para>
- preparing <ulink url="http://www.debian.org/doc/developers-reference/pkgs.html#nmu-qa-upload">QA
+ preparing <ulink url="&devref-nmu;">QA or NMU uploads</ulink>
- or NMU uploads</ulink>
  </para>
  </listitem>
  </itemizedlist>
-Line 605 
 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 615 
 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 <ulink url="http://www.de.debian.org/devel/wnpp/being_packaged">the list of packages
+ You must check that no one else is already working on the package on the
- being worked on</ulink>.  If no one else is working on it, file an ITP (Intent
+ <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 (DFSG)</emphasis> (see
+ <emphasis role="strong">to be fully compliant with the Debian Free Software
- <ulink url="http://www.debian.org/social_contract#guidelines">http://www.debian.org/social_contract#guidelines</ulink>)
+ Guidelines</emphasis> (<ulink url="&dfsg;">DFSG</ulink>)
- and <emphasis role="strong">that program must not require a package outside of
+ and <emphasis role="strong">not to require a package outside of
- <literal>main</literal></emphasis> for compilation or execution as required by
+ <literal>main</literal></emphasis> for compilation or execution.  This
- the Debian Policy.  This is desired case.
+ 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="http://lists.debian.org/debian-legal/">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, these things are just safety measures, and intended to save you from
+ Of course, the last one is just a safety measures, and intended to save you from
- raging users if you do something wrong in some setuid daemon...  When you gain
+ enraging users if you do something wrong in some setuid daemon...  When you gain
- some more experience in packaging, you'll be able to do such packages, but even
+ more experience in packaging, you'll be able to package such software.
- the experienced developers consult the <ulink url="http://lists.debian.org/debian-mentors/">debian-mentors@lists.debian.org</ulink>
- mailing list when they are in doubt.  And people there will gladly help.
  </para>
  <para>
- For more help about these, check in <ulink url="http://www.debian.org/doc/devel-manuals#devref">Debian Developer's
+ As a new maintainer, you are encouraged to get some experience in packaging
- Reference</ulink>.
+ with easier packages and discouraged from creating complicated packages.
  </para>
+ <itemizedlist>
+ <listitem><para>Simple packages</para>
+ <itemizedlist>
+   <listitem><para>single binary package, arch = all (collection of data such as wallpaper graphics)</para></listitem>
+   <listitem><para>single binary package, arch = all (executables written in an interpreted language such as POSIX shell)</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>Intermediate complexity packages</para>
+ <itemizedlist>
+   <listitem><para>single binary package, arch = any (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>cvs co</literal>, or <literal>svn co</literal> and
+ 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>
+ 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>, an X GTK+
+ As an example, I'll use a program called <command>gentoo</command>, a GTK+
- file manager.<footnote><para> This program is already packaged.  Current
+ file manager.
- version 0.15.3 has changed substantially from the version 0.9.12 in the
+ <footnote><para> This program is already packaged. The
- following examples.  </para> </footnote>
+ <ulink url="&gentoo-package;">current version</ulink> uses Autotools as its
+ build structure and is substantially different from the following examples,
+ which were based on version 0.9.12.</para>
+ </footnote>
  </para>
  <para>
  Create a subdirectory under your home directory named
  <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 765 
 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"/> ).
+ 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>.  Some of them support
+ or simply with freshly unpacked sources.
- <literal>make check</literal>, which runs included self-checks.  Installation
+ </para>
+ </section>
+ <section id="simplemake"><title>Simple build systems</title>
+ <para>
+ Simple programs usually come with a <filename>Makefile</filename> and can
+ be compiled just by invoking <literal>make</literal>.<footnote><para>
+ Many modern programs come with a script <filename>configure</filename> which
+ when executed creates a <filename>Makefile</filename> customized for
+ your system.</para></footnote> Some of them support
+ <literal>make check</literal>, which runs included self-tests.  Installation
  to the destination directories is usually done with <literal>make
  install</literal>.
  </para>
-Line 788 
 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="http://en.wikipedia.org/wiki/C_(programming_language)">C</ulink> and
+ A lot of free software programs are written in the <ulink url="&c-program;">C</ulink> and
- <ulink url="http://en.wikipedia.org/wiki/C++">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="http://en.wikipedia.org/wiki/GNU_build_system">Autotools</ulink>
+ <ulink url="&gnu-build-system;">Autotools</ulink> is the GNU build
- are the GNU build system comprising <ulink url="http://en.wikipedia.org/wiki/Autoconf">Autoconf</ulink>, <ulink url="http://en.wikipedia.org/wiki/Automake">Automake</ulink>, <ulink url="http://en.wikipedia.org/wiki/GNU_Libtool">Libtool</ulink>, and <ulink url="http://en.wikipedia.org/wiki/GNU_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="http://www.lrde.epita.fr/~adl/autotools.html">Autotools Tutorial</ulink>
+ <footnote><para>Autotools is too big to deal in this small tutorial. This
- and <filename>&autotools-dev;</filename>.  </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 827 
 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 841 
 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.
+ See <xref linkend="customrules"/>.</para></footnote>
  </para>
  <para>
- <ulink url="http://en.wikipedia.org/wiki/CMake">CMake</ulink> is an alternative
+ <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>
- For the package to be built correctly, you must make the program's original
+ If upstream uses some generic term such as <literal>test-suite</literal> for
- name lowercase (if it isn't already), and you should move the source directory
+ its name, it is a good idea to rename it to identify its contents explicitly and avoid namespace pollution.
- to
+ <footnote><para>If you follow the
- <filename><replaceable>packagename</replaceable>-<replaceable>version</replaceable></filename>.
+ <ulink url="&devref-newpackage;">Debian Developer's Reference 5.1. "New packages"</ulink>,
- </para>
+ the ITP process will usually catch this kind of issues.</para></footnote>
- <para>
+ </para>
- If the program name consists of more than one word, contract them to one word,
+ <para>
- or make an abbreviation.  For example, program John's little editor for X
+ You should choose the <emphasis role="strong">upstream version</emphasis>
- package would be named <systemitem role="package">johnledx</systemitem>, or
+ to consist only of
- <systemitem role="package">jle4x</systemitem>, or whatever you decide, as long
+ alphanumerics (<literal>0-9A-Za-z</literal>), plus (<literal>+</literal>),
- as it's under some reasonable limit, e.g.  20 characters.
+ tildes (<literal>~</literal>), and periods (<literal>.</literal>). It must
- </para>
+ start with a digit (<literal>0-9</literal>).  <footnote><para>This stricter
- <para>
+ rule should help you avoid confusing file names.</para></footnote>
- Also check for the exact version of the program (to be included in the package
+ It is good idea to keep its length within 8 characters if possible.
- version).  If that piece of software is not numbered with versions like
+ <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>
- <literal>X.Y.Z</literal>, but with some kind of date, feel free to use that
+ </para>
- 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
+ Osamu's archive stat (2011-04-23, sid, kfreebsd-amd64):
- in the format of <literal>09Oct23</literal> you may need to convert it to
+ === stat for upstream version string length ===
- <literal>YYYYMMDD</literal> format, which would be <literal>20091023</literal>,
+9765 60.2%  50% median and mode
- to ensure proper order for upgrade with the <command>dpkg</command>
+3765 73.3%
- program.<footnote><para> Version string can be compared by <literal>dpkg
+2789 82.9%
- --compare-versions <replaceable>ver1</replaceable>
+1158 86.9%
- <replaceable>op</replaceable> <replaceable>ver2</replaceable></literal>.  See
+501 88.6%
- <citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum>
+773 91.3%  90%
- </citerefentry> manpage.  </para> </footnote>
+55 99.1%   99%
- </para>
+11 99.9%    99.9
- <para>
+6 100.0%
- Some programs won't be numbered at all, in which case you should contact the
+ === stat for debian revision string length ===
- upstream maintainer to see if they've got some other revision-tracking method.
+22556 83.3%  50% median and mode
- </para>
+1106 87.2%
- </section>
+1312 91.7%   90%
- <section id="dh-make"><title>Initial Debian package</title>
+2127 99.1%   99%
- <para>
+14 99.9%     99.9%
- Let's set up the shell environment variable <literal>$DEBEMAIL</literal> and
- <literal>$DEBFULLNAME</literal> so many Debian maintenance tools recognize your
+ aptitude display 10 = 8char for up + 1char (for -) + 1char for deb
- name and email address to use for packages as follows.<footnote><para> The
+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>
+ Set up the shell environment variables <literal>$DEBEMAIL</literal> and
+ <literal>$DEBFULLNAME</literal> so that various Debian maintenance
+ tools recognize your email address and name to use for packages. <footnote><para> The
  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 909 
 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 961 
 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"/>),
- </para>
+ testing them (<xref linkend="checkit"/>), and uploading them (<xref linkend="upload"/>).
- <para>
+ All the steps will be explained.
- Once again, as a new maintainer you are discouraged from creating complicated
- packages, e.g.,
- </para>
- <itemizedlist>
- <listitem>
- <para>
- multiple binary packages,
- </para>
- </listitem>
- <listitem>
- <para>
- library packages,
  </para>
- </listitem>
- <listitem>
- <para>
- kernel module packages,
- </para>
- </listitem>
- <listitem>
- <para>
- kernel patch packages,
- </para>
- </listitem>
- <listitem>
  <para>
- the source file format being neither in <filename>tar.gz</filename> nor
+ If you accidentally erased some template files while working on them, you can
- <filename>tar.bz2</filename>, or
+ recover them by running <command>dh_make</command> with the
+ <literal>--addmissing</literal> option again in a Debian package source tree.
  </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 1045 
 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 program <command>quilt</command> offers a basic method for recording
+ modifications to the upstream source for Debian packaging.  It's
+ useful to have a slightly customized default, so let's create an alias
+ <command>dquilt</command> for Debian packaging by adding the following
+ line to <filename>~/.bashrc</filename>.
+ </para>
+ <screen>
+ alias dquilt="quilt --quiltrc=~/.quiltrc-dpkg"
+ </screen>
  <para>
- The <command>quilt</command> program offers the basic method to record
+ Then let's create <filename>~/.quiltrc-dpkg</filename> as follows.
- modification to the source for the Debian packaging.  Since slightly different
- default is desirable for Debian packaging, let's set up
- <filename>~/.quiltrc</filename> as follows.  <footnote><para> You can disable
- this configuration by starting the <command>quilt</command> command as
- <literal>quilt --quiltrc /dev/null ...</literal>.  </para> </footnote>
  </para>
  <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_PATCHES="debian/patches"
-     QUILT_PATCH_OPTS=--unified-reject-files
+     QUILT_PATCH_OPTS="--reject-format=unified"
-     QUILT_DIFF_ARGS=-p ab --no-timestamps --no-index --color=auto
+     QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
-     QUILT_REFRESH_ARGS=-p ab --no-timestamps --no-index
+     QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
-     QUILT_COLORS=diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33
+     QUILT_COLORS="diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:diff_ctx=35:diff_cctx=33"
      if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi
  fi
  </screen>
  <para>
  See <citerefentry> <refentrytitle>quilt</refentrytitle>
  <manvolnum>1</manvolnum> </citerefentry> and
- <filename>/usr/share/doc/quilt/quilt.html</filename> 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 1086 
 install: gentoo
+Line 1429 
 install: gentoo
          install gentoorc-example $(HOME)/.gentoorc
  </screen>
  <para>
- Let's fix this and record this with the <command>quilt</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
- $ quilt new fix-gentoo-target.patch
+ $ dquilt new fix-gentoo-target.patch
- $ quilt add Makefile
+ $ dquilt add Makefile
  </screen>
  <para>
  You change the <filename>Makefile</filename> file as follows.
-Line 1107 
 install: gentoo-target
+Line 1450 
 install: gentoo-target
          install gentoorc-example $(HOME)/.gentoorc
  </screen>
  <para>
- Ask <command>quilt</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.
+ description following <ulink url="&dep3;">DEP-3: Patch Tagging Guidelines</ulink>.
  </para>
  <screen>
- $ quilt refresh
+ $ dquilt refresh
- $ quilt header -e
+ $ dquilt header -e
  ... describe patch
  </screen>
  </section>
- <section id="destdir"><title>Installation of files to the destination</title>
+ <section id="destdir"><title>Installation of files to their 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 Filesystem Hierarchy Standard (<ulink url="http://www.debian.org/doc/packaging-manuals/fhs/fhs-2.3.html">FHS</ulink>,
+ directories such as <filename>/usr/bin</filename>, obeying the
- <filename>/usr/share/doc/debian-policy/fhs/fhs-2.3.html</filename>).
+ <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.
- (<filename>/usr/share/doc/gnu-standards/standards.html#Makefile-Conventions</filename>).
+ <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 (see
- <filename>/usr/share/doc/debian-policy/fhs/</filename>).  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 1253 
 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 1261 
 you the filename and the line number for
+Line 1607 
 you the filename and the line number for
  </para>
  <para>
  Edit those files and in those lines replace <literal>usr/local/lib</literal>
- with <literal>usr/lib</literal>.
+ 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>
- After your upstream bug fix, <systemitem role="package">gentoo</systemitem>'s
+ Originally, <systemitem role="package">gentoo</systemitem>'s
  install target said:
  </para>
  <screen>
-Line 1287 
 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>quilt</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>
- $ quilt new install.patch
+ $ dquilt new install.patch
- $ quilt add Makefile
+ $ 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 1305 
 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 1322 
 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>quilt</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>
- $ quilt refresh
+ $ dquilt refresh
- $ quilt header -e
+ $ dquilt header -e
  ... describe patch
  </screen>
  <para>
-Line 1351 
 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 1364 
 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>
- $ quilt new ncurse.patch
+ $ dquilt new foo2.patch
- $ quilt add Makefile
+ $ dquilt add Makefile
- $ sed -i -e s/-lcurses/-lncurses/g Makefile
+ $ sed -i -e 's/-lfoo/-lfoo2/g' Makefile
- $ quilt refresh
+ $ dquilt refresh
- $ quilt header -e
+ $ dquilt header -e
  ... describe patch
  </screen>
  </section>
  </chapter>
  <chapter id="dreq"><title>Required files under the <filename>debian</filename> directory</title>
  <para>
- There is a new subdirectory under the program's source directory, it's called
+ There is a new subdirectory under the program's source directory, called
  <filename>debian</filename>.  There are a number of files in this directory
  that we should edit in order to customize the behavior of the package.  The
  most important of them are <filename>control</filename>,
- <filename>changelog</filename>, <filename>copyright</filename> and
+ <filename>changelog</filename>, <filename>copyright</filename>, and
  <filename>rules</filename>, which are required for all packages.
+ <footnote><para>
+ In this chapter, files in the <filename>debian</filename> directory are
+ referred to without the leading <filename>debian/</filename> for simplicity whenever
+ the meaning is obvious.
+ </para></footnote>
  </para>
- <section id="control"><title><filename>control</filename> file</title>
+ <section id="control"><title><filename>control</filename></title>
  <para>
  This file contains various values which <command>dpkg</command>,
  <command>dselect</command>, <command>apt-get</command>,
  <command>apt-cache</command>, <command>aptitude</command>, and other package
- management tools will use to manage the package.  It is defined by the <ulink url="http://www.debian.org/doc/debian-policy/ch-controlfields.html">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 1433 
 created for us:
+Line 1791 
 created for us:
  (I've added the line numbers.)
  </para>
  <para>
- Lines 1-6 are the control information for the source package.
+ Lines 1-7 are the control information for the source package.
+ Lines 9-13 are the control information for the binary package.
  </para>
  <para>
  Line 1 is the name of the source package.
-Line 1442 
 Line 1 is the name of the source package
+Line 1801 
 Line 1 is the name of the source package
  Line 2 is the section of the distribution the source package goes into.
  </para>
  <para>
- As you may have noticed, Debian archive is divided in sections:
+ As you may have noticed, the Debian archive is divided into multiple areas:
  <literal>main</literal> (the free software), <literal>non-free</literal> (the
  not really free software) and <literal>contrib</literal> (free software that
- depends on non-free software).  Under those, there are logical subsections that
+ depends on non-free software).  Each of these is divided into sections that
- describe in short what packages are in.  So we have <literal>admin</literal>
+ classify packages into rough categories.  So we have <literal>admin</literal>
- for administrator-only programs, <literal>base</literal> for the basic tools,
+ for administrator-only programs,
  <literal>devel</literal> for programmer tools, <literal>doc</literal> for
  documentation, <literal>libs</literal> for libraries, <literal>mail</literal>
- for e-mail readers and daemons, <literal>net</literal> for network apps and
+ for email readers and daemons, <literal>net</literal> for network apps and
  daemons, <literal>x11</literal> for X11 programs that don't fit anywhere else,
- and many more.  See the <ulink url="http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections">Debian
+ and many more.
- Policy Manual, 2.4 'Sections'</ulink> and <ulink url="http://packages.debian.org/unstable/">List of sections in 'sid'</ulink>
+ <footnote> <para>See
- for the guidance.
+ <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>
  <para>
  Let's change it then to x11.  (A <literal>main/</literal> prefix is implied so
  we can omit it.)
  </para>
  <para>
- Line 3 describes how important it is that the user installs this package.  See
+ Line 3 describes how important it is that the user installs this package.
- the <ulink url="http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities">Debian
+ <footnote> <para>See
- Policy Manual, 2.5 'Priorities'</ulink> for the guidance.
+ <ulink url="&policy-priorities;">Debian Policy Manual, 2.5 "Priorities"</ulink>.
+ </para>
+ </footnote>
  </para>
  <itemizedlist>
  <listitem>
  <para>
  The <literal>optional</literal> priority will usually work for new packages
- that do not conflict with others with <literal>required</literal>,
+ that do not conflict with others claiming <literal>required</literal>,
- <literal>important</literal> or <literal>standard</literal> priorities.
+ <literal>important</literal>, or <literal>standard</literal> priority.
  </para>
  </listitem>
  <listitem>
-Line 1481 
 conflict with others with non-<literal>e
+Line 1844 
 conflict with others with non-<literal>e
  </listitem>
  </itemizedlist>
  <para>
- Section and priority are used by the frontends like <command>aptitude</command>
+ Section and priority are used by front-ends like <command>aptitude</command>
  when they sort packages and select defaults.  Once you upload the package to
  Debian, the value of these two fields can be overridden by the archive
  maintainers, in which case you will be notified by email.
-Line 1492 
 we will change the priority to <literal>
+Line 1855 
 we will change the priority to <literal>
  </para>
  <para>
  Line 4 is the name and email address of the maintainer.  Make sure that this
- field includes a valid <literal>To</literal> header for an email, because after
+ field includes a valid <literal>To</literal> header for email, because after
  you upload it, the bug tracking system will use it to deliver bug emails to
- you.  Avoid using commas, ampersands and parenthesis.
+ you.  Avoid using commas, ampersands, or parentheses.
  </para>
  <para>
- The 5th line includes the list of packages required to build your package as
+ Line 5 includes the list of packages required to build your package as
  the <literal>Build-Depends</literal> field.  You can also have the
- <literal>Build-Depends-Indep</literal> field as an additional line, here.  (see
+ <literal>Build-Depends-Indep</literal> field as an additional line, here.
- the <ulink url="http://www.debian.org/doc/debian-policy/ch-relationships.html#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>).  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
+ <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 1519 
 satisfy the Debian Policy requirement fo
+Line 1884 
 satisfy the Debian Policy requirement fo
  </listitem>
  <listitem>
  <para>
- For source packages which have some binary packages with <literal>Architecture:
+ Source packages which have binary packages with <literal>Architecture:
- any</literal>, they are rebuild by the autobuilder.  Since this autobuilder
+ any</literal> are rebuilt by the autobuilder.  Since this autobuilder
- procedure runs <literal>debian/rules build</literal> in it while installing
+ procedure installs only the packages listed in the
- only packages listed in the <literal>Build-Depends</literal> field (see <xref linkend="autobuilder"/> ), the <literal>Build-Depends</literal> field needs to
+ <literal>Build-Depends</literal> field before running
- list practically all the required packages and the
+ <literal>debian/rules build</literal> (see <xref
- <literal>Build-Depends-indep</literal> is rarely used.
+ linkend="autobuilder"/>), the <literal>Build-Depends</literal> field
+ needs to  list practically all the required packages and
+ <literal>Build-Depends-Indep</literal> is rarely used.
  </para>
  </listitem>
  <listitem>
  <para>
- For source packages which have binary packages only with <literal>Architecture:
+ For source packages with binary packages all of which are <literal>Architecture:
  all</literal>, the <literal>Build-Depends-Indep</literal> field may list all
  the required packages unless they are already listed in the
  <literal>Build-Depends</literal> field to satisfy the Debian Policy requirement
-Line 1541 
 for the <literal>clean</literal> target.
+Line 1908 
 for the <literal>clean</literal> target.
  If you are not sure which one should be used, use the
  <literal>Build-Depends</literal> field to be on the safe side.
  <footnote><para> This somewhat strange situation is a feature well documented
- in the <ulink url="http://www.debian.org/doc/debian-policy/footnotes.html#f48">Debian Policy
+ in the <ulink url="&policy-build-depends-indep;">Debian Policy
- Manual, Footnotes 48</ulink>.  This is not due to the use of the
+ Manual, Footnotes 55</ulink>.  This is not due to the use of the
  <command>dh</command> command in the <filename>debian/rules</filename> file but
  due to how the <command>dpkg-buildpackage</command> works.  The same situation
  applies to the <ulink url="https://bugs.launchpad.net/launchpad-buildd/+bug/238141">auto build system
-Line 1555 
 To find out what packages your package n
+Line 1922 
 To find out what packages your package n
  $ dpkg-depcheck -d ./configure
  </screen>
  <para>
- To manually find exact build dependency for
+ To manually find exact build dependencies for
- <command><replaceable>/usr/bin/foo</replaceable></command>, you execute
+ <command><replaceable>/usr/bin/foo</replaceable></command>, execute
  </para>
  <screen>
  $ objdump -p <replaceable>/usr/bin/foo</replaceable> | grep NEEDED
-Line 1568 
 and for each library listed, e.g., <comm
+Line 1935 
 and for each library listed, e.g., <comm
  $ dpkg -S libfoo.so.6
  </screen>
  <para>
- Then you just take <literal>-dev</literal> version of every package as
+ Then just take the <literal>-dev</literal> version of every package as a
  <literal>Build-Depends</literal> entry.  If you use <command>ldd</command> for
  this purpose, it will report indirect lib dependencies as well, resulting in
  the problem of excessive build dependencies.
-Line 1579 
 the problem of excessive build dependenc
+Line 1946 
 the problem of excessive build dependenc
  next to <systemitem role="package">debhelper</systemitem>.
  </para>
  <para>
- Line 6 is the version of the <ulink url="http://www.debian.org/doc/devel-manuals#policy">Debian Policy
+ Line 6 is the version of the <ulink url="&debian-policy;">Debian Policy
  Manual</ulink> standards this package follows, the one you read while making
  your package.
  </para>
  <para>
- On line 7 you can put the URL of the homepage for the upstream program.
+ On line 7 you can put the URL of the software's upstream homepage.
  </para>
  <para>
  Line 9 is the name of the binary package.  This is usually the same as the name
  of the source package, but it doesn't necessarily have to be that way.
  </para>
  <para>
- Line 10 describes the CPU architecture the binary package can be compiled for.
+ Line 10 describes the architectures the binary package can be compiled for.
- We'll leave this as <literal>any</literal> because <citerefentry>
+ This value is usually one of the following depending
- <refentrytitle>dpkg-gencontrol</refentrytitle> <manvolnum>1</manvolnum>
+ on the type of the binary package.
- </citerefentry> will fill in the appropriate value for any machine this package
+ <footnote><para>See
- gets compiled on.
+ <ulink url="http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Architecture">Debian Policy Manua 5.6.8 "Architecture"</ulink>
+ for exact details.
+ </para></footnote>
+ </para>
+ <itemizedlist>
+ <listitem><para><literal>Architecture: any</literal></para>
+   <itemizedlist>
+   <listitem><para>The generated binary package is an architecture dependent one
+     usually in a compiled language.</para></listitem>
+   </itemizedlist>
+ </listitem>
+ <listitem><para><literal>Architecture: all</literal></para>
+   <itemizedlist>
+   <listitem><para>The generated binary package is an architecture independent
+     one usually consisting of text, images, or scripts in an interpreted
+     language.</para></listitem>
+   </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ <para>
+ We leave line 10 as is since this is written in C.
+ <citerefentry><refentrytitle>dpkg-gencontrol</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ will fill in the appropriate architecture value for any machine this source
+ package gets compiled on.
  </para>
  <para>
  If your package is architecture independent (for example, a shell or Perl
-Line 1614 
 Packages can relate to each other in var
+Line 2004 
 Packages can relate to each other in var
  </para>
  <para>
  The package management tools usually behave the same way when dealing with
- these relations; if not, it will be explained.  (see <citerefentry>
+ these relations; if not, it will be explained.  (See <citerefentry>
  <refentrytitle>dpkg</refentrytitle> <manvolnum>8</manvolnum> </citerefentry>,
  <citerefentry> <refentrytitle>dselect</refentrytitle> <manvolnum>8</manvolnum>
  </citerefentry>, <citerefentry> <refentrytitle>apt</refentrytitle>
  <manvolnum>8</manvolnum> </citerefentry>, <citerefentry>
  <refentrytitle>aptitude</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> etc.)
+ </citerefentry>, etc.)
  </para>
  <para>
- This is what the dependencies mean:
+ Here is a simplified description of package relationships.
+ <footnote><para>See
+ <ulink url="&policy-relationships;">Debian Policy Manual, 7 "Declaring relationships between packages"</ulink>.
+ </para></footnote>
  </para>
  <itemizedlist>
  <listitem>
-Line 1642 
 severe breakage) unless a particular pac
+Line 2035 
 severe breakage) unless a particular pac
  </para>
  <para>
  Use this for packages that are not strictly necessary but are typically used
- with your program.  When a user installs your program, all frontends will
+ with your program.  When a user installs your program, all front-ends will
- likely prompt them to install the recommended packages.
+ probably prompt them to install the recommended packages.
  <command>aptitude</command> and <command>apt-get</command> install recommended
- packages along with your package (but the user can disable this default
+ packages along with your package by default (but the user can disable this
- behaviour).  <command>dpkg</command> will ignore this field.
+ behavior).  <command>dpkg</command> will ignore this field.
  </para>
  </listitem>
  <listitem>
-Line 1655 
 behaviour).  <command>dpkg</command> wil
+Line 2048 
 behaviour).  <command>dpkg</command> wil
  </para>
  <para>
  Use this for packages which will work nicely with your program but are not at
- all necessary.  When a user installs your program, all frontends will likely
+ all necessary.  When a user installs your program, they will probably not be
- prompt them to install the suggested packages.  <command>aptitude</command> can
+ prompted to install suggested packages.  <command>aptitude</command> can
  be configured to install suggested packages along with your package but this is
  not its default.  <command>dpkg</command> and <command>apt-get</command> will
  ignore this field.
-Line 1670 
 ignore this field.
+Line 2063 
 ignore this field.
  This is stronger than <literal>Depends</literal>.  The package will not be
  installed unless the packages it pre-depends on are installed and
  <emphasis>correctly configured</emphasis>.  Use this <emphasis>very</emphasis>
- sparingly and only after discussing it on the <ulink url="http://lists.debian.org/debian-devel/">debian-devel@lists.debian.org</ulink>
+ sparingly and only after discussing it on the <ulink url="&debian-devel-ldo;">debian-devel@lists.debian.org</ulink>
  mailing list.  Read: don't use it at all.  :-)
  </para>
  </listitem>
-Line 1689 
 severe problems if a particular package
+Line 2082 
 severe problems if a particular package
  <literal>Breaks</literal>
  </para>
  <para>
- The package will be installed while all the listed packages will be broken.
+ When installed the package will break all the listed packages.
- Normally a <literal>Breaks</literal> entry has an earlier than version clause.
+ Normally a <literal>Breaks</literal> entry specifies that it applies to versions earlier than a certain value.
- The resolution is generally to upgrade the listed packages by the higher-level
+ The resolution is generally to use higher-level package management tools to upgrade the listed packages.
- package management tools.
  </para>
  </listitem>
  <listitem>
-Line 1702 
 package management tools.
+Line 2094 
 package management tools.
  <para>
  For some types of packages where there are multiple alternatives virtual names
  have been defined.  You can get the full list in the
- <filename>/usr/share/doc/debian-policy/virtual-package-names-list.txt.gz</filename>
+ <ulink url="&virtual-package;">virtual-package-names-list.txt.gz</ulink>
  file.  Use this if your program provides a function of an existing virtual
  package.
  </para>
-Line 1728 
 symbols).
+Line 2120 
 symbols).
  <para>
  The fields may restrict their applicability to particular versions of each
  named package.  These versions are listed in parentheses after each individual
- package name, and they should contain a relation from the list below followed
+ package name, and should contain a relation from the list below followed
  by the version number.  The relations allowed are: <literal>&lt;&lt;</literal>,
- <literal>&lt;=</literal>, <literal>=</literal>, <literal>&gt;=</literal> and
+ <literal>&lt;=</literal>, <literal>=</literal>, <literal>&gt;=</literal>, and
  <literal>&gt;&gt;</literal> for strictly lower, lower or equal, exactly equal,
- greater or equal and strictly greater, respectively.  For example,
+ greater or equal, and strictly greater, respectively.  For example,
  </para>
  <screen>
  Depends: foo (&gt;= 1.2), libbar1 (= 1.3.4)
-Line 1744 
 Replaces: quux (&lt;&lt; 5), quux-foo (&
+Line 2136 
 Replaces: quux (&lt;&lt; 5), quux-foo (&
  <para>
  The last feature you need to know about is
  <literal>${shlibs:Depends}</literal>, <literal>${perl:Depends}</literal>,
- <literal>${misc:Depends}</literal>, etc.  These entries are substituted by the
+ <literal>${misc:Depends}</literal>, etc.
- list generated by other <systemitem role="package">debhelper</systemitem>
- components when the <citerefentry> <refentrytitle>dh_gencontrol</refentrytitle>
- <manvolnum>1</manvolnum> </citerefentry> command is executed.
  </para>
  <para>
  <citerefentry> <refentrytitle>dh_shlibdeps</refentrytitle>
- <manvolnum>1</manvolnum> </citerefentry> will scan it for binaries and
+ <manvolnum>1</manvolnum> </citerefentry> calculates shared library dependencies
- libraries determine their shared library dependencies and detect which packages
+ for binary packages.  It generates a list of ELF executables and shared
- they are in, such as <systemitem role="package">libc6</systemitem> or
+ libraries it has found for each binary package.  This list is used for
- <systemitem role="package">xlib6g</systemitem>, after your package has been
+ substituting <literal>${shlibs:Depends}</literal>.
- built and installed into the temporary directory.  This list of shared library
+ </para>
- dependencies is used for <literal>${shlibs:Depends}</literal>.
+ <para>
- </para>
+ <citerefentry> <refentrytitle>dh_perl</refentrytitle> <manvolnum>1</manvolnum>
- <para>
+ </citerefentry> calculates Perl dependencies.  It generates a list of a
- The package list generated by the <citerefentry>
+ dependencies on <literal>perl</literal> or <literal>perlapi</literal> for each binary package.  This list is used for
- <refentrytitle>dh_perl</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
+ substituting <literal>${perl:Depends}</literal>.
- is used for <literal>${perl:Depends}</literal>.
+ </para>
- </para>
+ <para>
- <para>
+ Some <systemitem role="package">debhelper</systemitem> commands may cause the
- Some <systemitem role="package">debhelper</systemitem> commands may make the
+ generated package to depend on some additional packages.  All such commands
- generated package need to depend on some other packages.  This list of required
+ generate a list of required packages for each binary package.
- packages is used for <literal>${misc:Depends}</literal>.
+ This list is used for substituting <literal>${misc:Depends}</literal>.
+ </para>
+ <para>
+ <citerefentry> <refentrytitle>dh_gencontrol</refentrytitle>
+ <manvolnum>1</manvolnum> </citerefentry> generates
+ <filename>DEBIAN/control</filename> for each binary package while
+ substituting <literal>${shlibs:Depends}</literal>,
+ <literal>${perl:Depends}</literal>, <literal>${misc:Depends}</literal>, etc.
  </para>
  <para>
  Having said all that, we can leave the <literal>Depends</literal> field exactly
  as it is now, and insert another line after it saying <literal>Suggests:
  file</literal>, because <systemitem role="package">gentoo</systemitem> can use
- some features provided by that <systemitem role="package">file</systemitem>
+ some features provided by the <systemitem role="package">file</systemitem>
  package.
  </para>
+ <para> Line 9 is the Homepage URL.  Let's assume this to be at
+ <ulink url="&gentoo;"/>.
+ </para>
  <para>
- Line 12 is the short description.  Most people screens are 80 columns wide so
+ Line 12 is the short description.  Terminals are conventionally 80 columns wide so
  this shouldn't be longer than about 60 characters.  I'll change it to
  <literal>fully GUI-configurable, two-pane X file manager</literal>.
  </para>
-Line 1785 
 Line 13 is where the long description go
+Line 2184 
 Line 13 is where the long description go
  gives more details about the package.  Column 1 of each line should be empty.
  There must be no blank lines, but you can put a single <literal>.</literal>
  (dot) in a column to simulate that.  Also, there must be no more than one blank
- line after the long description.
+ line after the long description. <footnote><para>These descriptions are in
+ English.  Translations of these descriptions are provided by
+ <ulink url="&ddtp;">The Debian Description Translation Project - DDTP</ulink>.</para></footnote>
  </para>
  <para>
- Let's insert <literal>Vcs-*</literal> fields documented in <ulink url="http://www.debian.org/doc/manuals/developers-reference/best-pkging-practices.html#bpp-vcs">Developer's
+ We can insert <literal>Vcs-*</literal> fields to document the Version Control
- Reference, 6.2.5.  'Version Control System location'</ulink> between line 6 and
+ System (VCS) location between lines 6 and 7.
-.  Let's assume that the <systemitem role="package">gentoo</systemitem>
+ <footnote><para>See
- package is located in Debian Alioth Git Service at
+ <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 the Debian Alioth Git Service at
  <literal>git://git.debian.org/git/collab-maint/gentoo.git</literal>.
  </para>
  <para>
-Line 1806 
 Finally, here is the updated <filename>c
+Line 2210 
 Finally, here is the updated <filename>c
 Standards-Version: 3.8.4
 Vcs-Git: git://git.debian.org/git/collab-maint/gentoo.git
 Vcs-browser: http://git.debian.org/?p=collab-maint/gentoo.git
-Homepage: http://www.obsession.se/gentoo/
+Homepage: &gentoo;
 Package: gentoo
 Architecture: any
-Line 1819 
 Finally, here is the updated <filename>c
+Line 2223 
 Finally, here is the updated <filename>c
  they're fairly easy to work with since they are written in an XML format.
  .
  gentoo features a fairly complex and powerful file identification system,
- coupled to a object-oriented style system, which together give you a lot
+ coupled to an object-oriented style system, which together give you a lot
  of control over how files of different types are displayed and acted upon.
  Additionally, over a hundred pixmap images are available for use in file
  type descriptions.
  .
- gentoo was written from scratch in ANSI C, and it utilises the GTK+ toolkit
+ gentoo was written from scratch in ANSI C, and it utilizes the GTK+ toolkit
  for its interface.
  </screen>
  <para>
  (I've added the line numbers.)
  </para>
  </section>
- <section id="copyright"><title><filename>copyright</filename> file</title>
+ <section id="copyright"><title><filename>copyright</filename></title>
  <para>
- This file contains the information about package upstream resources, copyright
+ This file contains information about the copyright and license of the upstream sources.
- and license information.  Its format is not dictated by the Debian Policy
+ <ulink url="&policy-copyright;">Debian Policy Manual, 12.5 "Copyright information"</ulink>
- Manual, but the content is (<ulink url="http://www.debian.org/doc/debian-policy/ch-docs.html#s-copyrightfile">Debian
+ dictates its content and
- Policy Manual, 12.5 'Copyright information'</ulink>).  You may also consult
+ <ulink url="&dep5;">DEP-5: Machine-parseable <filename>debian/copyright</filename></ulink>
- <ulink url="http://dep.debian.net/deps/dep5/">DEP-5: Machine-parseable
+ provides guidelines for its format.
- debian/copyright</ulink>.
  </para>
  <para>
  <command>dh_make</command> can give you a template
-Line 1846 
 debian/copyright</ulink>.
+Line 2249 
 debian/copyright</ulink>.
  gpl2</literal> option here to get a template file for the <systemitem role="package">gentoo</systemitem> package released under GPL-2.
  </para>
  <para>
- You must fill in missing information such as the place you got the package
+ You must fill in missing information to complete this file, such as the place you got the package
- from, the actual copyright notice and their license to complete this file.  For
+ from, the actual copyright notice, and the license.  For certain
- the common free software licenses such as GNU GPL-1, GNU GPL-2, GNU GPL-3,
+ common free software licenses (GNU GPL-1, GNU GPL-2, GNU GPL-3,
- LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0 or the Artistic
+ LGPL-2, LGPL-2.1, LGPL-3, GNU FDL-1.2, GNU FDL-1.3, Apache-2.0, or the Artistic
- license, you can just refer to the appropriate file in
+ license), you can just refer to the appropriate file in the
  <filename>/usr/share/common-licenses/</filename> directory that exists on every
  Debian system.  Otherwise, you must include the complete license.
  </para>
  <para>
- In short, here's how <systemitem role="package">gentoo</systemitem>'s
+ In short, here's what <systemitem role="package">gentoo</systemitem>'s
  <filename>copyright</filename> file should look like:
  </para>
  <screen>
-Line 1885 
 In short, here's how <systemitem role="p
+Line 2288 
 In short, here's how <systemitem role="p
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  GNU General Public License for more details.
-.
+ .
  You should have received a copy of the GNU General Public License along
  with this program; if not, write to the Free Software Foundation, Inc.,
  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
-Line 1898 
 In short, here's how <systemitem role="p
+Line 2301 
 In short, here's how <systemitem role="p
  (I've added the line numbers.)
  </para>
  <para>
- Please follow the HOWTO provided by ftpmasters and sent to
+ Please follow the HOWTO provided by the ftpmasters and sent to
- debian-devel-announce: <ulink url="&copyright-howto;">&copyright-howto;</ulink>.
+ debian-devel-announce: <ulink url="&howto-copyright;"/>.
  </para>
  </section>
- <section id="changelog"><title><filename>changelog</filename> file</title>
+ <section id="changelog"><title><filename>changelog</filename></title>
  <para>
- This is a required file, which has a special format described in the <ulink url="http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog">Debian
+ This is a required file, which has a special format described in
- Policy Manual, 4.4 'debian/changelog'</ulink>.  This format is used by
+ <ulink url="&policy-dpkgchangelog;">Debian Policy Manual, 4.4 "debian/changelog"</ulink>.
- <command>dpkg</command> and other programs to obtain the version number,
+ This format is used by <command>dpkg</command> and other programs to obtain the
- revision, distribution and urgency of your package.
+ version number, revision, distribution, and urgency of your package.
  </para>
  <para>
  For you, it is also important, since it is good to have documented all changes
-Line 1917 
 saved as <filename>/usr/share/doc/gentoo
+Line 2320 
 saved as <filename>/usr/share/doc/gentoo
  binary package.
  </para>
  <para>
- <command>dh_make</command> created a default one, and this is how it looks
+ <command>dh_make</command> created a default one, and this is what it looks
  like:
  </para>
  <screen>
-Line 1933 
 like:
+Line 2336 
 like:
  </para>
  <para>
  Line 1 is the package name, version, distribution, and urgency.  The name must
- match the source package name, distribution should be either
+ match the source package name; distribution should be
  <literal>unstable</literal> (or even <literal>experimental</literal>)
  <footnote><para> Some people use invalid distribution values such as
- <literal>UNRELEASED</literal> to prevent a package to be accidentally uploaded
+ <literal>UNRELEASED</literal> to prevent a package being accidentally uploaded
  when updating a package in a shared VCS.  </para> </footnote>, and urgency
  shouldn't be changed to anything higher than <literal>low</literal>.  :-)
  </para>
  <para>
  Lines 3-5 are a log entry, where you document changes made in this package
- revision (not the upstream changes - there is special file for that purpose,
+ revision (not the upstream changes - there is a special file for that purpose,
  created by the upstream authors, which you will later install as
  <filename>/usr/share/doc/gentoo/changelog.gz</filename>).  Let's assume your
  ITP (Intent To Package) bug report number was <literal>12345</literal>.  New
- lines must be inserted just before the uppermost line that begins with
+ lines must be inserted just below the uppermost line that begins with
  <literal>*</literal> (asterisk).  You can do it with <citerefentry>
  <refentrytitle>dch</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>, or
  manually with a text editor.
-Line 1969 
 You will end up with something like this
+Line 2372 
 You will end up with something like this
  </para>
  <para>
  You can read more about updating the <filename>changelog</filename> file later
- in <xref linkend="update"/> .
+ in <xref linkend="update"/>.
  </para>
  </section>
- <section id="rules"><title><filename>rules</filename> file</title>
+ <section id="rules"><title><filename>rules</filename></title>
  <para>
  Now we need to take a look at the exact rules which <citerefentry>
  <refentrytitle>dpkg-buildpackage</refentrytitle> <manvolnum>1</manvolnum>
- </citerefentry> will use to actually create the package.  This file is actually
+ </citerefentry> will use to actually create the package.  This file is in fact
  another <filename>Makefile</filename>, but different from the one(s) in the
  upstream source.  Unlike other files in <filename>debian</filename>, this one
  is marked as executable.
  </para>
- <section id="targets"><title>Targets of <filename>rules</filename> file</title>
+ <section id="targets"><title>Targets of the <filename>rules</filename> file</title>
  <para>
- Every <filename>rules</filename> file, as any other
+ Every <filename>rules</filename> file, like any other
- <filename>Makefile</filename>, consists of several targets and their rules
+ <filename>Makefile</filename>, consists of several targets and their rules.
- specifying how to handle the source.  <ulink url="http://www.debian.org/doc/debian-policy/ch-source.html#s-debianrules">Debian
+ <footnote><para>You can start learning how to write <filename>Makefile</filename> from
- Policy Manual, 4.9 'Main building script: debian/rules'</ulink> explains its
+ <ulink url="&debref-make;">Debian Reference, 12.2 "Make"</ulink>.
- details.
+ The full documentation is available as
+ <ulink url="&gnu-make;"></ulink> or as the
+ <systemitem role="package">make-doc</systemitem> package in the non-free archive area.
+ </para></footnote>
+ A new rule begins with its target declaration in the first column.  The
+ following lines beginning with the TAB code (ASCII 9) specify its rule.
+ Empty lines and lines beginning with <literal>#</literal> (hash) are treated as
+ comments and ignored.
+ <footnote><para><ulink url="&policy-debianrules;">Debian
+ Policy Manual, 4.9 "Main building script: debian/rules"</ulink> explains the
+ details.</para></footnote>
+ </para>
+ <para>
+ A rule that you want to execute is invoked by its target name as a command line argument.  For
+ example, <literal>debian/rules <replaceable>build</replaceable></literal> and
+ <literal>fakeroot make -f debian/rules <replaceable>binary</replaceable></literal>
+ execute rules for <literal><replaceable>build</replaceable></literal> and
+ <literal><replaceable>binary</replaceable></literal> targets trespectively.
  </para>
  <para>
- The simplified explanation of targets are the following.
+ Here is a simplified explanation of the targets:
  </para>
  <itemizedlist>
  <listitem>
  <para>
  <literal>clean</literal> target: to clean all compiled, generated, and useless
- files in the build-tree.  (required)
+ files in the build-tree.  (Required)
  </para>
  </listitem>
  <listitem>
  <para>
  <literal>build</literal> target: to build the source into compiled programs and
- formatted documents in the build-tree.  (required)
+ formatted documents in the build-tree.  (Required)
  </para>
  </listitem>
  <listitem>
-Line 2010 
 formatted documents in the build-tree.
+Line 2430 
 formatted documents in the build-tree.
  <literal>install</literal> target: to install files into a file tree for each
  binary package under the <filename>debian</filename> directory.  If defined,
  <literal>binary*</literal> targets effectively depend on this target.
- (optional)
+ (Optional)
  </para>
  </listitem>
  <listitem>
  <para>
  <literal>binary</literal> target: to create all binary packages (effectively
- combination of <literal>binary-arch</literal> and
+ a combination of <literal>binary-arch</literal> and
- <literal>binary-indep</literal> targets).  (required)<footnote><para> This
+ <literal>binary-indep</literal> targets).  (Required)<footnote><para> This
- target is used by <literal>dpkg-buildpackage</literal> as in <xref linkend="completebuild"/> .  </para> </footnote>
+ target is used by <literal>dpkg-buildpackage</literal> as in <xref linkend="completebuild"/>.  </para> </footnote>
  </para>
  </listitem>
  <listitem>
  <para>
  <literal>binary-arch</literal> target: to create arch-dependent
  (<literal>Architecture: any</literal>) binary packages in the parent directory.
- (required)<footnote><para> This target is used by <literal>dpkg-buildpackage
+ (Required)<footnote><para> This target is used by <literal>dpkg-buildpackage
- -B</literal> as in <xref linkend="autobuilder"/> .  </para> </footnote>
+ -B</literal> as in <xref linkend="autobuilder"/>.  </para> </footnote>
  </para>
  </listitem>
  <listitem>
  <para>
  <literal>binary-indep</literal> target: to create arch-independent
  (<literal>Architecture: all</literal>) binary packages in the parent directory.
- (required)<footnote><para> This target is used by <literal>dpkg-buildpackage
+ (Required)<footnote><para> This target is used by <literal>dpkg-buildpackage
  -A</literal>.  </para> </footnote>
  </para>
  </listitem>
  <listitem>
  <para>
  <literal>get-orig-source</literal> target: to obtain the most recent version of
- the original source package from upstream archive site.  (optional)
+ the original source package from an upstream archive.  (Optional)
  </para>
  </listitem>
  </itemizedlist>
  <para>
- Rules that you want to execute are invoked as command line arguments (for
+ You are probably overwhelmed by now, but things are much simpler upon examination of the
- example, <literal>./debian/rules build</literal> or <literal>fakeroot make -f
- debian/rules binary</literal>).  After the target name, you can name the
- dependency, program or file that the rule depends on.  After that, there can be
- any number of commands, indented with
- <literal><replaceable>TAB</replaceable></literal>.  A new rule begins with the
- target declaration in the first column.  Empty lines and lines beginning with
- <literal>#</literal> (hash) are treated as comments and ignored.
- </para>
- <para>
- You are probably confused now, but it will all be clear upon examination of the
  <filename>rules</filename> file that <command>dh_make</command> gives us as a
- default.  You should also read <literal>info make</literal> for more
+ default.
- information.
  </para>
  </section>
  <section id="defaultrules"><title>Default <filename>rules</filename> file</title>
-Line 2083 
 Newer <command>dh_make</command> generat
+Line 2492 
 Newer <command>dh_make</command> generat
  </screen>
  <para>
  (I've added the line numbers.  In the actual <filename>rules</filename> file,
- the leading white spaces are TAB codes.)
+ the leading spaces are a TAB code.)
  </para>
  <para>
  You are probably familiar with lines like line 1 from shell and Perl scripts.
-Line 2091 
 It tells the operating system that this
+Line 2500 
 It tells the operating system that this
  <filename>/usr/bin/make</filename>.
  </para>
  <para>
- Line 10 can be uncommented to set <literal>DH_VERBOSE</literal> variable to 1.
+ Line 10 can be uncommented to set the <literal>DH_VERBOSE</literal> variable to 1,
- Then, the <command>dh</command> command will output which
+ so that the <command>dh</command> command outputs which
- <command>dh_*</command> commands are executed by the <command>dh</command>
+ <command>dh_*</command> commands it is executing.
- command.  You can also add <literal>export DH_OPTIONS=-v</literal> line here.
+ You can also add a line <literal>export DH_OPTIONS=-v</literal> here,
- Then each <command>dh_*</command> command will output which commands are
+ so that each <command>dh_*</command> command outputs which commands it
- executed by each <command>dh_*</command> command.  This helps you to understand
+ is executing.  This helps you to understand
- what exactly is going on behind this simple <filename>rules</filename> file and
+ exactly what is going on behind this simple <filename>rules</filename> file and
- to debug its problems.  This new <command>dh</command> is a core part of the
+ to debug its problems.  This new <command>dh</command> is designed to form a core part of the
- <systemitem role="package">debhelper</systemitem> tools and does not hide
+ <systemitem role="package">debhelper</systemitem> tools, and not to hide
  anything from you.
  </para>
  <para>
- Lines 12 and 13 are where all the work is done.  The percent sign means any
+ Lines 12 and 13 are where all the work is done with an implicit rule using the pattern rule.  The percent sign means "any
- targets which then call a single program, <command>dh</command> with the target
+ targets", which then call a single program, <command>dh</command>, with the target
- name.  <footnote><para> This uses the new <systemitem role="package">debhelper</systemitem> V7 features.  Its design concepts are
+ name.  <footnote><para> This uses the new <systemitem role="package">debhelper</systemitem> v7 features.  Its design concepts are
- explained in <ulink url="http://joey.kitenet.net/talks/debhelper/debhelper-slides.pdf">Not Your
+ explained in <ulink url="&debhelper-slides;">Not Your
- Grandpa's Debhelper</ulink> presented at Debconf9 by the <systemitem role="package">debhelper</systemitem> upstream.  Under
+ Grandpa's Debhelper</ulink> presented at DebConf9 by the <systemitem role="package">debhelper</systemitem> upstream.  Under
  <literal>lenny</literal>, <command>dh_make</command> created a much more
- complicated <filename>rules</filename> file with many <command>dh_*</command>
+ complicated <filename>rules</filename> file with explicit rules
- scripts listed for each required explicit targets and frozen them to the state
+ and many <command>dh_*</command> scripts listed for each one, most of
- when it was initially packaged.  This new <command>dh</command> command is
+ which are now unnecessary (and show the package's age). The new <command>dh</command> command is
- simpler and frees us from this constrain.  You still have full power to
+ simpler and frees us from doing the routine work "manually". You still have full power to
- customize this with <literal>override_dh_*</literal> targets.  See <xref linkend="customrules"/> .  It is based only on the <systemitem role="package">debhelper</systemitem> package and does not obfuscate the
+ customize the process with <literal>override_dh_*</literal> targets. See <xref linkend="customrules"/>.  It is based only on the <systemitem role="package">debhelper</systemitem> package and does not obfuscate the
- package building process like the <systemitem role="package">cdbs</systemitem>
+ package building process as the <systemitem role="package">cdbs</systemitem>
- package.  </para> </footnote> The <command>dh</command> command is a wrapper
+ package tends to.  </para> </footnote> The <command>dh</command> command is a wrapper
  script which runs appropriate sequences of <command>dh_*</command> programs
- depending on its argument.  <footnote><para> You can verify actual sequences of
+ depending on its argument.  <footnote><para> You can verify the actual sequences of
  <command>dh_*</command> programs invoked for a given
- <literal><replaceable>target</replaceable></literal> as <literal>dh --no-act
+ <literal><replaceable>target</replaceable></literal> without really running them by invoking <literal>dh --no-act
  <replaceable>target</replaceable></literal> or <literal>debian/rules --
- '--no-act <replaceable>target</replaceable>'</literal> without really running
+ '--no-act <replaceable>target</replaceable>'</literal>.  </para> </footnote>
- them.  </para> </footnote>
  </para>
  <itemizedlist>
  <listitem>
  <para>
- <literal>debian/rules clean</literal> runs <literal>dh clean</literal>; which
+ <literal>debian/rules clean</literal> runs <literal>dh clean</literal>, which
  in turn runs the following:
  </para>
  <screen>
-Line 2221 
 for each remaining command.
+Line 2629 
 for each remaining command.
  </listitem>
  </itemizedlist>
  <para>
- The function of <command>dh_*</command> commands are almost self-evident from
+ The functions of <command>dh_*</command> commands are largely self-evident from
- their names.  <footnote><para> For complete information on what do all these
+ their names.  <footnote><para> For complete information on what all these
- <command>dh_*</command> scripts exactly do, and what their other options are,
+ <command>dh_*</command> scripts do exactly, and what their other options are,
  please read their respective manual pages and the <systemitem role="package">debhelper</systemitem> documentation.  </para> </footnote> There
- are few notable ones worth making (over)simplified explanation here assuming
+ are a few notable ones that are worth giving (over)simplified explanations here assuming
- typical build environment based on <filename>Makefile</filename>.
+ a typical build environment based on a <filename>Makefile</filename>.
  <footnote><para> These commands support other build environments such as
  <filename>setup.py</filename> which can be listed by executing
  <literal>dh_auto_build --list</literal> in a package source directory.  </para>
-Line 2235 
 typical build environment based on <file
+Line 2643 
 typical build environment based on <file
  <itemizedlist>
  <listitem>
  <para>
- <command>dh_auto_clean</command> usually executes the following if
+ <command>dh_auto_clean</command> usually executes the following if a
  <filename>Makefile</filename> exists with the <literal>distclean</literal>
- target.  <footnote><para> It actually looks for the first available target of
+ target.  <footnote><para> It actually looks for the first available target
- <literal>distclean</literal>, <literal>realclean</literal> or
+ in the <filename>Makefile</filename> out of
- <literal>clean</literal> in <filename>Makefile</filename> and execute it.
+ <literal>distclean</literal>, <literal>realclean</literal>, or
+ <literal>clean</literal>, and executes that.
  </para> </footnote>
  </para>
  <screen>
-Line 2267 
 make
+Line 2676 
 make
  </listitem>
  <listitem>
  <para>
- <command>dh_auto_test</command> usually executes the following if
+ <command>dh_auto_test</command> usually executes the following if a
  <filename>Makefile</filename> exists with the <literal>test</literal> target.
- <footnote><para> It actually looks for the first available target of
+ <footnote><para> It actually looks for the first available target in
- <literal>test</literal> or <literal>check</literal> in
+ the <filename>Makefile</filename> out of <literal>test</literal> or
- <filename>Makefile</filename> and execute it.  </para> </footnote>
+ <literal>check</literal>, and executes thait.  </para> </footnote>
  </para>
  <screen>
  make test
-Line 2279 
 make test
+Line 2688 
 make test
  </listitem>
  <listitem>
  <para>
- <command>dh_auto_install</command> usually executes the following if
+ <command>dh_auto_install</command> usually executes the following if a
  <filename>Makefile</filename> exists with the <literal>install</literal> target
  (line folded for readability).
  </para>
-Line 2290 
 make install \
+Line 2699 
 make install \
  </listitem>
  </itemizedlist>
  <para>
- Targets which require the <command>fakeroot</command> command contain
+ All targets which require the <command>fakeroot</command> command will contain
- <command>dh_testroot</command>.  If you are not pretending to be root using
+ <command>dh_testroot</command>, which exits with an error if you are not
- this command, it exits with an error.
+ using this command to pretend to be root.
  </para>
  <para>
  The important part to know about the <filename>rules</filename> file created by
- <command>dh_make</command>, is that it is just a suggestion.  It will work for
+ <command>dh_make</command> is that it is just a suggestion.  It will work for
  most packages but for more complicated ones, don't be afraid to customize it to
- fit your needs.  Only things that you must not change are the names of the
+ fit your needs.  The only things that you must not change are the names of the
  rules, because all the tools use these names, as mandated by the Debian Policy.
  </para>
  <para>
- Although <literal>install</literal> is not required target, it is supported.
+ Although <literal>install</literal> is not a required target, it is supported.
  <literal>fakeroot dh install</literal> behaves like <literal>fakeroot dh
  binary</literal> but stops after <command>dh_fixperms</command>.
  </para>
-Line 2322 
 file, you should activate its customizat
+Line 2731 
 file, you should activate its customizat
  <itemizedlist>
  <listitem>
  <para>
- Add support of the <command>dh_pysupport</command> command.  (The best choice
+ Add support for the <command>dh_pysupport</command> command.  (The best choice
  for Python.) <footnote><para> Use of the <command>dh_pysupport</command>
  command is preferred over use of the <command>dh_pycentral</command> command.
  Do not use the <command>dh_python</command> command.  </para> </footnote>
-Line 2330 
 Do not use the <command>dh_python</comma
+Line 2739 
 Do not use the <command>dh_python</comma
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">python-support</systemitem> package in
+ Include the <systemitem role="package">python-support</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
  <listitem>
  <para>
- Use <literal>dh $@</literal> as usual.  (This is enabled by default)
+ Use <literal>dh $@</literal> as usual.  (Use of <command>dh_pysupport</command> is the default)
  </para>
  </listitem>
  <listitem>
-Line 2348 
 This handles Python modules using the <s
+Line 2757 
 This handles Python modules using the <s
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_pycentral</command> command.
+ Add support for the <command>dh_pycentral</command> command.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">python-central</systemitem> package in
+ Include the <systemitem role="package">python-central</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
-Line 2376 
 This handles Python modules using the <s
+Line 2785 
 This handles Python modules using the <s
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_installtex</command> command.
+ Add support for the <command>dh_installtex</command> command.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">tex-common</systemitem> package in
+ Include the <systemitem role="package">tex-common</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
-Line 2392 
 Use <literal>dh --with tex $@</literal>
+Line 2801 
 Use <literal>dh --with tex $@</literal>
  </listitem>
  <listitem>
  <para>
- This registers Type 1 fonts, hyphenation patterns, or formats with TeX.
+ This registers Type 1 fonts, hyphenation patterns, and formats with TeX.
  </para>
  </listitem>
  </itemizedlist>
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_quilt_patch</command> and
+ Add support for the <command>dh_quilt_patch</command> and
  <command>dh_quilt_unpatch</command> commands.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">quilt</systemitem> package in
+ Include the <systemitem role="package">quilt</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
-Line 2417 
 Use <literal>dh --with quilt $@</literal
+Line 2826 
 Use <literal>dh --with quilt $@</literal
  <listitem>
  <para>
  This applies and un-applies patches to the upstream source from files in the
- <filename>debian/patches</filename> directory for the <literal>1.0</literal>
+ <filename>debian/patches</filename> directory for a source package in the <literal>1.0</literal> format.
- source package.
  </para>
  </listitem>
  <listitem>
  <para>
  This is not needed if you use the new <literal>3.0 (quilt)</literal> source
- package.
+ package format.
  </para>
  </listitem>
  </itemizedlist>
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_dkms</command> command.
+ Add support for the <command>dh_dkms</command> command.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">dkms</systemitem> package in
+ Include the <systemitem role="package">dkms</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
-Line 2447 
 Use <literal>dh --with dkms $@</literal>
+Line 2855 
 Use <literal>dh --with dkms $@</literal>
  </listitem>
  <listitem>
  <para>
- This correctly handles DKMS usage by the kernel module package.
+ This correctly handles DKMS usage by kernel module packages.
  </para>
  </listitem>
  </itemizedlist>
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_autotools-dev_updateconfig</command> and
+ Add support for the <command>dh_autotools-dev_updateconfig</command> and
  <command>dh_autotools-dev_restoreconfig</command> commands.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">autotools-dev</systemitem> package in
+ Include the <systemitem role="package">autotools-dev</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
-Line 2479 
 This updates and restores <filename>conf
+Line 2887 
 This updates and restores <filename>conf
  </listitem>
  <listitem>
  <para>
- Add support of the <command>dh_autoreconf</command> and
+ Add support for the <command>dh_autoreconf</command> and
  <command>dh_autoreconf_clean</command> commands.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">dh-autoreconf</systemitem> package in
+ Include the <systemitem role="package">dh-autoreconf</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
-Line 2503 
 This updates the GNU Build System files
+Line 2911 
 This updates the GNU Build System files
  </listitem>
  <listitem>
  <para>
- Add support to the <command>bash</command> completion feature.
+ Add support for the <command>bash</command> completion feature.
  </para>
  <itemizedlist>
  <listitem>
  <para>
- Install the <systemitem role="package">bash-completion</systemitem> package in
+ Includes the <systemitem role="package">bash-completion</systemitem> package in
  <literal>Build-Depends</literal>.
  </para>
  </listitem>
-Line 2519 
 Use <literal>dh --with bash-completion $
+Line 2927 
 Use <literal>dh --with bash-completion $
  </listitem>
  <listitem>
  <para>
- This installs <command>bash</command> completions using configuration file at
+ This installs <command>bash</command> completions using a configuration file at
  <filename>debian/<replaceable>package</replaceable>.bash-completion</filename>.
  </para>
  </listitem>
-Line 2527 
 This installs <command>bash</command> co
+Line 2935 
 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
  manpage of each command for the customization of such features.
  </para>
  <para>
- Some <command>dh_*</command> commands invoked by the new <command>dh</command>
+ You may need to run <command>dh_*</command> commands invoked via the new <command>dh</command>
- command may require you to run it with some arguments or to run additional
+ with added arguments, or to run additional commands with them, or to skip them.
- commands with them or to skip them.  For such cases, you create an
+ For such cases, you create an
  <literal>override_dh_<replaceable>foo</replaceable></literal> target with its
- rule in the <filename>rules</filename> file only for the
+ rule in the <filename>rules</filename> file defining an
+ <literal>override_dh_<replaceable>foo</replaceable></literal> target for the
  <command>dh_<replaceable>foo</replaceable></command> command you want to
- change.  It basically say <emphasis>run me instead</emphasis>.
+ change.  It basically says <emphasis>run me instead</emphasis>.
  <footnote><para> Under <literal>lenny</literal>, if you wanted to change the
  behavior of a <command>dh_*</command> script you found the relevant line in the
  <filename>rules</filename> file and adjusted it.  </para> </footnote>
  </para>
  <para>
  Please note that the <command>dh_auto_*</command> commands tend to do more than
- what has been discussed as (over)simplified explanation to take care all the
+ what has been discussed in this (over)simplified explanation to take care of all the
- corner cases.  Use of simplified equivalent command instead of these in
+ corner cases.  It is a bad idea to use <literal>override_dh_*</literal> targets
- <literal>override_dh_*</literal> targets except the
+ to substitute simplified equivalent commands (except for the
- <literal>override_dh_auto_clean</literal> target is a bad idea since it may
+ <literal>override_dh_auto_clean</literal> target) since it may
- kill such <systemitem role="package">debhelper</systemitem>'s smart features.
+ bypass such smart <systemitem role="package">debhelper</systemitem> features.
  </para>
  <para>
- If you want to store the system configuration data for the <systemitem role="package">gentoo</systemitem> package in the
+ So, for instance, if you want to store system configuration data in the
  <filename>/etc/gentoo</filename> directory instead of the usual
- <filename>/etc</filename> directory, you can override the default
+ <filename>/etc</filename> directory for the recent
+ <systemitem role="package">gentoo</systemitem> package using Autotools, you can override the default
  <literal>--sysconfig=/etc</literal> argument given by the
  <command>dh_auto_configure</command> command to the
- <command>./configure</command> command by the following.  <footnote><para> The
+ <command>./configure</command> command by the following.
- <systemitem role="package">gentoo</systemitem> package uses the GNU build
- system, also known as the Autotools.  See <ulink url="http://en.wikipedia.org/wiki/GNU_build_system">http://en.wikipedia.org/wiki/GNU_build_system</ulink>.
- </para> </footnote>
  </para>
  <screen>
  override_dh_auto_configure:
-Line 2575 
 override_dh_auto_configure:
+Line 2977 
 override_dh_auto_configure:
  <para>
  The arguments given after <literal>--</literal> are appended to the default
  arguments of the auto-executed program to override them.  Using the
- <command>dh_auto_configure</command> command is better than the
+ <command>dh_auto_configure</command> command is better than directly invoking the
  <command>./configure</command> command here since it will only override the
- <literal>--sysconfig</literal> argument and keeps well intended other arguments
+ <literal>--sysconfig</literal> argument and retains any other, benign arguments
  to the <command>./configure</command> command.
  </para>
  <para>
- If <filename>Makefile</filename> of a source for <systemitem role="package">gentoo</systemitem> requires you to specify
+ If the <filename>Makefile</filename> in the source for <systemitem role="package">gentoo</systemitem> requires you to specify
  <literal>build</literal> as its target to build it <footnote><para>
  <command>dh_auto_build</command> without any arguments will execute the first
- target in the <filename>Makefile</filename> file.  </para> </footnote>, you
+ target in the <filename>Makefile</filename>.  </para> </footnote>, you
- create an <literal>override_dh_auto_build</literal> target to enable it.
+ create an <literal>override_dh_auto_build</literal> target to enable this.
  </para>
  <screen>
  override_dh_auto_build:
          dh_auto_build -- build
  </screen>
  <para>
- This ensures to run $(MAKE) with all the default arguments given by the
+ This ensures $(MAKE) is run with all the default arguments given by the
- <command>dh_auto_build</command> command and <literal>build</literal> argument.
+ <command>dh_auto_build</command> command plus the <literal>build</literal> argument.
  </para>
  <para>
- If <filename>Makefile</filename> of a source for <systemitem role="package">gentoo</systemitem> requires you to specify the
+ If the <filename>Makefile</filename> in the source for <systemitem role="package">gentoo</systemitem> requires you to specify the
- <literal>packageclean</literal> target to clean it for Debian package instead
+ <literal>packageclean</literal> target to clean it for the Debian package instead
- of the <literal>distclean</literal> or <literal>clean</literal> targets in the
+ of using <literal>distclean</literal> or <literal>clean</literal> targets,
- <filename>Makefile</filename> file, you create an
+ you can create an
- <literal>override_dh_auto_clean</literal> target to enable it.
+ <literal>override_dh_auto_clean</literal> target to enable thit.
  </para>
  <screen>
  override_dh_auto_clean:
          $(MAKE) packageclean
  </screen>
  <para>
- If <filename>Makefile</filename> of a source for <systemitem role="package">gentoo</systemitem> contains <literal>test</literal> target
+ If the <filename>Makefile</filename> in the source for <systemitem role="package">gentoo</systemitem> contains a <literal>test</literal> target
  which you do not want to run for the Debian package building process, you can
- use empty <literal>override_dh_auto_test</literal> target to skip it.
+ use an empty <literal>override_dh_auto_test</literal> target to skip it.
  </para>
  <screen>
  override_dh_auto_test:
-Line 2621 
 changelog file called <filename>FIXES</f
+Line 3023 
 changelog file called <filename>FIXES</f
  The <command>dh_installchangelogs</command> command requires
  <filename>FIXES</filename> as its argument to install it.  <footnote><para> The
  <filename>debian/changelog</filename> and <filename>debian/NEWS</filename>
- files are always automatically installed.  The upstream changelog is searched
+ files are always automatically installed.  The upstream changelog is found
- by converting filenames to the lower case and matching them with the
+ by converting filenames to lower case and matching them against
  <filename>changelog</filename>, <filename>changes</filename>,
  <filename>changelog.txt</filename>, and <filename>changes.txt</filename>.
  </para> </footnote>
-Line 2633 
 override_dh_installchangelogs:
+Line 3035 
 override_dh_installchangelogs:
  </screen>
  <para>
  When you use the new <command>dh</command> command, use of explicit targets
- such as the ones listed in <xref linkend="targets"/> except
+ such as the ones listed in <xref linkend="targets"/>, other than the
- <literal>get-orig-source</literal> target may make it difficult to understand
+ <literal>get-orig-source</literal> target, may make it difficult to understand
  their exact effects.  Please limit explicit targets to
  <literal>override_dh_*</literal> targets and completely independent ones, if
  possible.
-Line 2646 
 possible.
+Line 3048 
 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="http://www.debian.org/doc/devel-manuals#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="http://www.debian.org/doc/devel-manuals#devref">Debian Developer's
+ 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 2658 
 filenames suffixed by <literal>.ex</lite
+Line 3060 
 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"/> ),
+ modify the <filename>control</filename> file (see <xref linkend="control"/>),
- if necessary.
+ if necessary;
  </para>
  </listitem>
  <listitem>
  <para>
- modify the <filename>rules</filename> file (see <xref linkend="rules"/> ), if
+ modify the <filename>rules</filename> file (see <xref linkend="rules"/>), if
  necessary.
  </para>
  </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 2732 
 If you have nothing to be documented, re
+Line 3139 
 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 configuration files
+ over your changes.  Debian solves this problem by marking such configuration files as conffiles.
- so that when you upgrade a package, you'll be prompted whether you want to keep
+ <footnote><para>See <citerefentry> <refentrytitle>dpkg</refentrytitle>
- your old configuration or not.
+ <manvolnum>1</manvolnum> </citerefentry> and
+ <ulink url="&policy-conffiles;">Debian Policy Manual "D.2.5 Conffiles"</ulink>.
+ </para></footnote>
+ 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"/> .
+ directories created first.  See <xref linkend="install"/>.
  </para>
  <para>
- It is best to first try to run the installation first and only use this if you
+ 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.
+ 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 2876 
 This usually includes HTML, PS and PDF f
+Line 3287 
 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 2893 
 Files: /usr/share/doc/gentoo/html/*.html
+Line 3304 
 Files: /usr/share/doc/gentoo/html/*.html
  For information on the file format, see <citerefentry>
  <refentrytitle>install-docs</refentrytitle> <manvolnum>8</manvolnum>
  </citerefentry> and the <systemitem role="package">doc-base</systemitem>
- manual, in <filename>/usr/share/doc/doc-base/doc-base.html/</filename>.
+ manual, in <ulink url="&doc-base;">Debian doc-base Manual</ulink>.
  </para>
  <para>
- For more details on installing additional documentation, look in <xref linkend="destdir"/> .
+ 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 2912 
 directory that are called <filename>BUGS
+Line 3323 
 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 2925 
 README.gtkrc
+Line 3336 
 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 2939 
 They are installed into the temporary di
+Line 3350 
 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
- Filesystem Hierarchy Standard (see
+ <ulink url="&lsb;">Linux Standard Base</ulink> (LSB) compliant headers.  It
- <filename>/usr/share/doc/debian-policy/fhs/</filename>) compliant headers.  It
  gets installed into the temporary directory by <citerefentry>
  <refentrytitle>dh_installinit</refentrytitle> <manvolnum>1</manvolnum>
  </citerefentry>.
  </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 init script.  Most times this
+ file sets defaults that are sourced by the init script.  This
- default file is used to disable running a daemon, set some default flags or
+ <filename><replaceable>package</replaceable>.default</filename> file
- timeouts.  If your init 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 default file, not the init 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 init 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 init.d 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 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 2990 
 override_dh_installinit:
+Line 3403 
 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 3006 
 the <filename>docs</filename> file and n
+Line 3419 
 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
- <filename>/usr/share/doc/lintian/lintian.html/index.html</filename> and refrain
+ <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 3061 
 by the <command>dh_lintian</command> com
+Line 3473 
 by the <command>dh_lintian</command> com
  is not installed.
  </para>
  </section>
  <section id="m