Re: Updated maint-guide contents, question on style
Onward to chapter two. I'm trying to cut down on editing glitches by
previewing the output in xmlcopyeditor; any tips on less painful
methods would be appreciated.
This is the chapter I nearly submitted a wishlist bug-report for
almost a decade ago, since maint-guide claimed to cover every step in
the process of creating a simple Debian package, but turned out to
have a crucial hole in its instructions. If I want to Debianise some
C program that I've found on Freshmeat, everything's fine. But if
I've got a ~/bin directory full of handy scripts that I've written in
some interpreted language, and I want to turn *those* into a .deb, I'm
out of luck - helloworld.sh ought to be simplest imaginable
Debianisation project, but maint-guide insists on starting with a
"make install", and gives no guidance on the step of *creating* an
appropriate "upstream tarball"!
(Come to that, nor does any documentation I've ever found; if you're
not familiar with the traditional C-programming workflow and the
problems make is designed to solve, but need to use it to automate a
quite different process, its manual is unintelligible.)
Now, filling in this missing step would take a lot of work by somebody
other than me, so as a stopgap I'll suggest the alternative of clearly
signposting the hole. Section 2.1 warns against picking a library,
daemon, or setuid program, and insists on executables being in binary
form; at present this looks like an oversight, but instead it could
explicitly advise against interpreted languages. I'm not sure what
justification it could offer for this, though.
Moving on... section 2.3 is "Free portable programs". I don't
understand this title (why isn't it something like "widely used build
systems"?), and I don't completely understand the diagrams. Do the
lines from the bottom indicate "these commands are also somehow
involved in the process", or what?
Section 2.4 ("Package name and version") might need a transfusion
from 1.5, but for now I'm just fixing up the existing version.
The instructions for creating the source package name never say that's
what you're doing; instead they just make a big deal about shortening
"John's little editor for X" because it's more than one word. Who
cares? Not whoever named maint-guide or debian-policy... if the
upstream tarball is johns-little-editor_0.1.tar.gz, renaming it to
jle4x will just make it unrecognisable in the WNPP list.
Section 2.5 says that when packaging gentoo I should pick the "single
binary" package type because gentoo "creates only one binary" -
apparently meaning "creates only one compiled executable". But this
is irrelevant; I might be packaging a dozen executables into a single
evenmoreutils.deb, or I might be packaging mytextdata.deb plus
mytextdata-doc.deb! It needs to state that "binary" here means
"binary-as-opposed-to-source package", and provide some (pointers to)
guidance on how to decide how many binary packages there should be.
Irrelevant footnote: the package description for gentoo says
If you still prefer to hand-edit configuration files, they're fairly
easy to work with since they are written in an XML format.
<para><sarcasm type="bitter">Oh <emphasis role="strong">hurrah</emphasis>.</sarcasm></para>
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
--- maint-guide.en.dbk.pristine 2011-04-17 14:35:41.052916002 +0100
+++ maint-guide.en.dbk 2011-04-20 10:34:20.081259194 +0100
@@ -653,7 +653,8 @@
</chapter>
<chapter id="first"><title>First steps</title>
<para>
-Let's try to make your own package (or, better even, adopt an existing one).
+Let's start by creating a package of your own (or, even better,
+adopting an existing one).
</para>
<section id="choose"><title>Choose your program</title>
<para>
@@ -666,20 +667,21 @@
<para>the <command>aptitude</command> command</para>
</listitem>
<listitem>
-<para><ulink url="&packages-do;">Debian packages</ulink> web page</para>
+<para>the <ulink url="&packages-do;">Debian packages</ulink> web page</para>
</listitem>
<listitem>
-<para><ulink url="&packages-qa-do;">Debian Package Tracking System</ulink> web page</para>
+<para>the <ulink url="&packages-qa-do;">Debian Package Tracking System</ulink> web page</para>
</listitem>
</itemizedlist>
<para>
If the package already exists, well, install it! :-) If it happens to be
-<emphasis role="strong">orphaned</emphasis> -- if its maintainer is set to
-<ulink url="&qa-do;">Debian QA Group</ulink>, you may be able to pick it up if
-it's still available. You may also adopt a package for which the corresponding
-maintainer has filed a Request for Adoption
+<emphasis role="strong">orphaned</emphasis> (that is, if its
+maintainer is set to <ulink url="&qa-do;">Debian QA Group</ulink>),
+you may be able to pick it up if it's still available. You may also
+adopt a package whose maintainer has filed a Request for Adoption
(<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>
+<ulink url="&devref-adopt;">Debian Developer's Reference 5.9.5.
+"Adopting a package"</ulink>.</para> </footnote>
</para>
<para>
There are several package ownership status resources.
@@ -704,8 +706,8 @@
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
-packaging. </para> </footnote>. You can do that in various ways.
+said that, there will of course always be new programs that are worth
+packaging. </para> </footnote>. You can contribute in various ways.
</para>
<itemizedlist>
<listitem>
@@ -735,7 +737,7 @@
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>
@@ -745,46 +747,47 @@
<itemizedlist>
<listitem>
<para>
-First, you must know that program works, and have tried it for some time to
+First, you must know that the program works, and have tried it for some time to
confirm its usefulness.
</para>
</listitem>
<listitem>
<para>
-You must check if no one else is working on the package already at the
+You must check that no one else is already working on the package on the
<ulink url="&wnpp-do;">Work-Needing and Prospective Packages</ulink> site.
If no one else is working on it, file an ITP (Intent
To Package) bug report to the <systemitem role="package">wnpp</systemitem>
pseudo-package using <command>reportbug</command>. If someone's already on it,
contact them if you feel you need to. If not - find another interesting
-program that nobody maintains.
+program that nobody is maintaining.
</para>
</listitem>
<listitem>
<para>
-That program <emphasis role="strong">must have a license</emphasis>.
+The software <emphasis role="strong">must have a license</emphasis>.
</para>
<itemizedlist>
<listitem>
<para>
-For the <literal>main</literal> section, it <emphasis role="strong">must be
-compliant to all the Debian Free Software Guidelines</emphasis> (<ulink url="&dfsg;">DFSG</ulink>)
-and <emphasis role="strong">that program must not require a package outside of
-<literal>main</literal></emphasis> for compilation or execution as required by
-the Debian Policy. This is desired case.
+For the <literal>main</literal> section, Debian Policy requires it
+<emphasis role="strong">to be fully compliant with the Debian Free Software
+Guidelines</emphasis> (<ulink url="&dfsg;">DFSG</ulink>)
+and <emphasis role="strong">not to require a package outside of
+<literal>main</literal></emphasis> for compilation or execution. This
+is the desired case.
</para>
</listitem>
<listitem>
<para>
-For the <literal>contrib</literal> section, it must be compliant to all the
+For the <literal>contrib</literal> section, it must comply with the
DFSG but it may require a package outside of <literal>main</literal> for
compilation or execution.
</para>
</listitem>
<listitem>
<para>
-For the <literal>non-free</literal> section, it may not be compliant to some of
-the DFSG but it <emphasis role="strong">must be distributable</emphasis>.
+For the <literal>non-free</literal> section, it may be non-compliant
+with the DFSG but it <emphasis role="strong">must be distributable</emphasis>.
</para>
</listitem>
</itemizedlist>
@@ -795,77 +798,76 @@
</listitem>
<listitem>
<para>
-That program certainly should <emphasis role="strong">not</emphasis> run setuid
-root, or even better - it shouldn't need to be setuid or setgid to anything.
+The program certainly should <emphasis role="strong">not</emphasis> run setuid
+root, or even better, it shouldn't need to be setuid or setgid to anything.
</para>
</listitem>
<listitem>
<para>
-That program should not be a daemon, or something that goes in
-<filename>*/sbin</filename> directories, or open a port as root.
+The program should not be a daemon, or go in an
+<filename>*/sbin</filename> directory, or open a port as root.
</para>
</listitem>
<listitem>
<para>
-That program should result in binary executable form, libraries are harder to
-handle.
+The program should be in binary executable form; libraries are harder to handle.
</para>
</listitem>
<listitem>
<para>
-That program should be well documented and its code needs to be understandable
+The program should be well documented and its code needs to be understandable
(i.e. not obfuscated).
</para>
</listitem>
<listitem>
<para>
-You should contact program's author(s) to check if they agree with packaging it
-and amicable to Debian. It is important to be able to consult with author(s)
-about the program in case of any program specific problems, so don't try to
-package unmaintained pieces of software.
+You should contact the program's author(s) to check if they agree with packaging it
+and are amicable to Debian. It is important to be able to consult with the author(s)
+in case of any problems with the program, so don't try to package
+unmaintained software.
</para>
</listitem>
</itemizedlist>
<para>
-Of course, these things are just safety measures, and intended to save you from
-raging users if you do something wrong in some setuid daemon... When you gain
-some more experience in packaging, you'll be able to package such packages.
+Of course, these are just safety measures, and intended to save you from
+enraging users if you do something wrong in some setuid daemon... When you gain
+more experience in packaging, you'll be able to package such software.
</para>
</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
-presume that you already have the source file that you picked up at the
+So the first thing to do is to find and download the original source code.
+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
-<command>tar</command>+<command>bzip2</command> format with extension
-<filename>.tar.bz2</filename>. These usually contain the subdirectory called
+<command>tar</command>+<command>bzip2</command> format with the extension
+<filename>.tar.bz2</filename>. These usually contain a directory called
<filename><replaceable>programname</replaceable>-<replaceable>version</replaceable></filename>
-in them and all the sources under it.
+with all the sources inside.
</para>
<para>
-If the latest version of such sources are available through VCS such as Git,
-Subversion, or CVS repository, you need to get it with <literal>git
+If the latest version of the source is available through a VCS such as Git,
+Subversion, or CVS, you need to get it with <literal>git
clone</literal>, <literal>svn co</literal>, or <literal>cvs co</literal> and
-repack it into <command>tar</command>+<command>gzip</command> format by
-yourself using the <literal>--exclude-vcs</literal> option.
+repack it into <command>tar</command>+<command>gzip</command> format yourself
+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,
-too.
+enough. </para> </footnote>), you should also unpack it with the
+appropriate tools and repack it.
</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. Its
+<footnote><para> This program is already packaged. The
<ulink url="&gentoo-package;">current version</ulink> uses Autotools as its
-build structure and is substantially different from the following examples
-based on the version 0.9.12.</para>
+build structure and is substantially different from the following examples,
+which were based on version 0.9.12.</para>
</footnote>
</para>
<para>
@@ -873,11 +875,11 @@
<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
-<emphasis>irrelevant</emphasis> ones, because there will most probably be
-problems unpacking on other people's systems, whose unpacking tools may or may
-not ignore those anomalies. On your console screen, you should see the
-following.
+xzf gentoo-0.9.12.tar.gz</literal>). Make sure there are no warning
+messages, even <emphasis>irrelevant</emphasis> ones, because other
+people's unpacking tools may or may not ignore these anomalies, so they
+may have problems unpacking them. Your shell commandline may look
+something like this:
</para>
<screen>
$ mkdir ~/gentoo ; cd ~/gentoo
@@ -892,18 +894,18 @@
Change to that directory and <emphasis>thoroughly</emphasis> read the provided
documentation. Usually there are files named <filename>README*</filename>,
<filename>INSTALL*</filename>, <filename>*.lsm</filename> or
-<filename>*.html</filename>. You must find instructions on how to correctly
+<filename>*.html</filename>. You must find instructions on how to
compile and install the program (most probably they'll assume you want to
-install to <filename>/usr/local/bin</filename> directory; you won't be doing
+install to the <filename>/usr/local/bin</filename> directory; you won't be doing
that, but more on that later in <xref linkend="destdir"/>).
</para>
<para>
-Simple programs come with a <filename>Makefile</filename> file in them and can
-be compiled simply with <literal>make</literal>.<footnote><para>
+Simple programs come with a <filename>Makefile</filename> and can
+be compiled just by invoking <literal>make</literal>.<footnote><para>
Many modern programs come with a script <filename>configure</filename> which
-creates a <filename>Makefile</filename> file customized for your system upon
-its execution.</para></footnote> Some of them support
-<literal>make check</literal>, which runs included self-checks. Installation
+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>
@@ -920,25 +922,28 @@
</section>
<section id="portable"><title>Free portable programs</title>
<para>
-A lot of Free programs are written in the <ulink url="&c-program;">C</ulink> and
+A lot of free software is written in the <ulink url="&c-program;">C</ulink> and
<ulink url="&cxx;">C++</ulink> languages. Many of
these use Autotools or CMake to make them portable across different platforms.
-These tools are used to generate <filename>Makefile</filename> and other
-required source files. Then, such programs are built with usual <literal>make;
-make install</literal>.
+These tools are used to generate the <filename>Makefile</filename> and other
+required source files. Then, such programs are built using the usual
+<literal>make; make install</literal>.
</para>
<para>
-<ulink url="&gnu-build-system;">Autotools</ulink>
-are the GNU build system comprising <ulink url="&autoconf;">Autoconf</ulink>, <ulink url="&automake;">Automake</ulink>, <ulink url="&libtool;">Libtool</ulink>, and <ulink url="&gettext;">gettext</ulink>. You can notice
+<ulink url="&gnu-build-system;">Autotools</ulink> is the GNU build
+system comprising <ulink url="&autoconf;">Autoconf</ulink>,
+<ulink url="&automake;">Automake</ulink>,
+<ulink url="&libtool;">Libtool</ulink>, and
+<ulink url="&gettext;">gettext</ulink>. You can recognize
such sources by the <filename>configure.ac</filename>,
<filename>Makefile.am</filename>, and <filename>Makefile.in</filename> files.
-<footnote><para> See <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink>
+<footnote><para> See the <ulink url="&autotools-tutorial;">Autotools Tutorial</ulink>
and <ulink url="&autotools-readme;"/>. </para> </footnote>
</para>
<para>
-The first step of Autotools work flow is usually that the upstream runs
-<literal>autoreconf -i -f</literal> in the source and distributes this source
-with generated files.
+The first step of the Autotools workflow is usually that upstream runs
+<literal>autoreconf -i -f</literal> in the source directory and
+distributes the generated files along with the source.
</para>
<screen>
configure.ac-----+-> autoreconf -+-> configure
@@ -957,9 +962,9 @@
<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 && make</literal> in
-the source to compile program into a
+the source directory to compile the program into a
<command><replaceable>binary</replaceable></command>.
</para>
<screen>
@@ -971,13 +976,13 @@
config.guess --+
</screen>
<para>
-You can change many things in the <filename>Makefile</filename> file such as
-the default file install location using the command option, e.g.
-<command>./configure --prefix=/usr</command>.
+You can change many things in the <filename>Makefile</filename>; for
+instance you can change the default location for file installation
+using the option <command>./configure --prefix=/usr</command>.
</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.
@@ -985,7 +990,7 @@
</para>
<para>
<ulink url="&cmake;">CMake</ulink> is an alternative
-build system. You can notice such sources by the
+build system. You can recognize such sources by the
<filename>CMakeLists.txt</filename> file.
</para>
</section>
@@ -1002,25 +1007,25 @@
</para>
<para>
If the program name consists of more than one word, contract them to one word,
-or make an abbreviation. For example, program John's little editor for X
-package would be named <systemitem role="package">johnledx</systemitem>, or
+or make an abbreviation. For example, a package of the program "John's little
+editor for X" might be named <systemitem role="package">johnledx</systemitem>, or
<systemitem role="package">jle4x</systemitem>, or whatever you decide, as long
-as it's under some reasonable limit, e.g. 20 characters.
+as it's under some reasonable length limit, e.g. 20 characters.
</para>
<para>
Also check for the exact version of the program (to be included in the package
-version). If that piece of software is not numbered with versions like
+version). If this piece of software is not numbered with versions like
<literal>X.Y.Z</literal>, but with some kind of date, feel free to use that
date as the version number, as long as newer version numbers will look larger.
-While it is best to use the same version number as what upstream uses, if it is
+While it is best to use the same version numbering as upstream, if it is
in the format of <literal>09Oct23</literal> you may need to convert it to
<literal>YYYYMMDD</literal> format, which would be <literal>20091023</literal>,
-to ensure proper order for upgrade with the <command>dpkg</command>
-program.<footnote><para> Version string can be compared by <literal>dpkg
+to ensure that <command>dpkg</command> sees later versions as
+upgrades.<footnote><para> Version strings can be compared with <literal>dpkg
--compare-versions <replaceable>ver1</replaceable>
<replaceable>op</replaceable> <replaceable>ver2</replaceable></literal>. See
<citerefentry> <refentrytitle>dpkg</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry> manpage. </para> </footnote>
+</citerefentry>. </para> </footnote>
</para>
<para>
Some programs won't be numbered at all, in which case you should contact the
@@ -1029,12 +1034,12 @@
</section>
<section id="dh-make"><title>Initial Debian package</title>
<para>
-Let's set up the shell environment variable <literal>$DEBEMAIL</literal> and
-<literal>$DEBFULLNAME</literal> so many Debian maintenance tools recognize your
-name and email address to use for packages as follows.<footnote><para> The
+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
-instead of <filename>~/.bashrc</filename>. </para> </footnote>.
+some other login shell such as Z shell, use their corresponding
+configuration files instead of <filename>~/.bashrc</filename>. </para> </footnote>.
</para>
<screen>
$ cat >>~/.bashrc <<EOF
@@ -1044,8 +1049,8 @@
EOF
</screen>
<para>
-Let's make an initial Debian package by issuing the <command>dh_make</command>
-command as follows.
+You can create an initial Debian package by issuing the
+<command>dh_make</command> command as follows.
</para>
<screen>
$ . ~/.bashrc
@@ -1056,36 +1061,37 @@
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>
-option, instead. The new source <literal>3.0 (quilt)</literal> format is quite
-robust not to break even for these packages. You may need to update contents
+<command>dh_make</command> command with the extra option
+<literal>--addmissing</literal>. The new source <literal>3.0 (quilt)</literal> format is
+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
-thus 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
+thus one <filename>.deb</filename> file - so we will select the first option
+(with the <literal>s</literal> key), check the information on the screen, and
confirm by pressing <literal><replaceable>ENTER</replaceable></literal>.
-<footnote><para> There are few choices here: <literal>s</literal> for Single
-binary, <literal>i</literal> for Arch-Independent, <literal>m</literal> for
+<footnote><para> There are several choices here: <literal>s</literal> for Single
+binary, <literal>i</literal> for arch-Independent, <literal>m</literal> for
Multiple binary, <literal>l</literal> for Library, <literal>k</literal> for
-Kernel module, <literal>n</literal> for Kernel patch and <literal>b</literal>
+Kernel module, <literal>n</literal> for kernel patch, and <literal>b</literal>
for <systemitem role="package">cdbs</systemitem>. This document focuses on the
-use of the <systemitem role="package">debhelper</systemitem> package with the
-<command>dh</command> command. This document focuses on the use of the new
-<command>dh</command> command for Single binary and touches on it for
-Arch-Independent and Multiple binary. The <systemitem role="package">cdbs</systemitem> package offers alternative package script
-infrastructure to the <command>dh</command> command and outside of the scope of
+use of the <command>dh</command> command (from the package
+<systemitem role="package">debhelper</systemitem>) to create a single-binary package,
+but also touches on how to use it for arch-independent or
+multiple-binary packages. The package
+<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
-tarball is created as <filename>gentoo_0.9.12.orig.tar.gz</filename> in the
+This execution of <command>dh_make</command> creates a copy of the upstream
+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
@@ -1094,70 +1100,72 @@
gentoo_0.9.12.orig.tar.gz
</screen>
<para>
-Please note 2 key features in this
-<filename>gentoo_0.9.12.orig.tar.gz</filename> file name:
+Please note two key features of this filename
+<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
-that the packaging is not automatic process. You need to modify the upstream
-source for Debian as <xref linkend="modify"/>. After all these, you need to
-build Debian packages under the proper method as <xref linkend="build"/>,
-check them as <xref linkend="checkit"/>, and upload them as <xref linkend="upload"/>. I will explain all these steps.
+the <filename>debian</filename> directory. These will be explained in
+<xref linkend="dreq"/> and <xref linkend="dother"/>. You should also understand
+that packaging cannot be a fully automated process. You will need to modify the upstream
+source for Debian (see <xref linkend="modify"/>). After this, you need to
+use the proper methods for building Debian packages (<xref linkend="build"/>),
+testing them (<xref linkend="checkit"/>), and uploading them (<xref linkend="upload"/>).
+All the steps will be explained.
</para>
<para>
Once again, as a new maintainer you are discouraged from creating complicated
-packages, e.g.,
+packages, e.g.:
</para>
<itemizedlist>
<listitem>
<para>
-multiple binary packages,
+multiple binary packages;
</para>
</listitem>
<listitem>
<para>
-library packages,
+library packages;
</para>
</listitem>
<listitem>
<para>
-kernel module packages,
+kernel module packages;
</para>
</listitem>
<listitem>
<para>
-kernel patch packages,
+kernel patch packages;
</para>
</listitem>
<listitem>
<para>
-the source file format being neither in <filename>tar.gz</filename> nor
-<filename>tar.bz2</filename>, or
+packages with the source in a format other than <filename>tar.gz</filename> or
+<filename>tar.bz2</filename>; or
</para>
</listitem>
<listitem>
<para>
-the source tarball containing undistributable contents.
+packages where the source tarball contains undistributable contents.
</para>
</listitem>
</itemizedlist>
<para>
-It's not too hard, but it does require a bit more knowledge, so we won't
+Doing so is not too hard, but it requires a bit more knowledge, so we won't
describe all of it here.
</para>
<para>
@@ -1167,8 +1175,8 @@
</para>
<para>
Updating an existing package may get complicated since it may be using older
-techniques. Please stick with fresh packaging cases for now to learn basics.
-I will come back to explain it later in <xref linkend="update"/>.
+techniques. While learning the basics, please stick to creating a fresh
+package; further explanations are given in <xref linkend="update"/>.
</para>
</section>
</chapter>
Reply to: