Re: Updated maint-guide contents, question on style
Justin B Rye wrote:
> Osamu Aoki wrote:
>> Also, if you have time, can you read the English source and propose
>> fixes.
>
> Certainly.
Attached is a patch for chapter one. I won't try to explain all of
the English language fixes, since I intend them to be
"semantics-preserving", but I will add some commentary below for
problems with the content (not acted on in the patch).
1 para 2: auto-updating variables are handy, but in contexts like:
# This document has been updated for the Debian
# <literal>&base-release;</literal> release.
it seems unwise to let it *automatically* claim to have been revised.
1.2: This section's a bit pointless; it should either be expanded to
include a full explanation of the roles of DDs/DMs/etc. (what happened
to Debian Contributors?) or reduced to a paragraph of 1.1.
1.3 para 2: the releasenotes say that these days apt-get is
preferred over aptitude for commandline package-management (besides,
aptitude might not be installed), so say "apt-get search foo".
1.3 para 4+: my patch sorts the lists into alphabetical order.
In the explanation of quilt, what does "traveling into the stack"
mean?
By the way, do these documentation pointers really need to use URIs
like "file:///usr/share/doc/quilt/quilt.pdf.gz"? If I'm reading
file:///usr/share/doc/maint-guide/ch-start.en.html, and quilt is also
installed, I would prefer a link to "../quilt/quilt.html" so I can
just open another tab in my browser...
1.3 para 6+, 1.4: you insist that maintainers should "thoroughly read
the documentation of each program, at least" (preferably more than
once). This is only necessary if my trial package is written in mixed
Fortran and Pascal using both autoconf and imake! On the other hand,
I probably will need to skim the docs for make, and there's no "see
man page" link for that because it's build-essential.
1.5 on source packages and binary packages: excuse me while I rant.
It seems to me that newcomers are *entitled* to be confused by this
terminology. A "source package" need contain no sourcecode (not all
languages are compiled), and a "binary package" may contain nothing
but ASCII text (it may even be sourcecode). I've never understood why
we need to call the tarball plus separate .diff.gz and .dsc files a
"package" in the first place! Alas, getting programmers to change
their private jargon is a hopeless cause.
1.5 on DMs: see above on 1.2. Why is this stuck in between the bit
about source packages and the bit about source versions?
1.5 on versioning: this explanation of "versions" and "revisions"
and "Debian versions" is wrong. Policy doesn't use the jargon
described here; it just uses the variable names "upstream_version"
and "debian_revision". Correcting that leaves us with vacuous
non-definitions like this:
* upstream source version: the upstream source version is referred
to as the upstream version.
But this still isn't true - the "upstream_version" is the
Policy-compliant version string used for the Debianised sources. If
the upstream author uses a version string beginning with a letter
then the "upstream_version" will be a different string.
And besides, full Debian version strings can be made up of three
components - there are also epochs.
I can't see how to do a semantics-preserving language-only revision of
this section; I'll have to leave it untouched and come back to it.
1.6: I should read "files in /usr/share/doc/dpkg"? I'm not sure
what that's meant to be pointing at... maybe
README.feature-removal-schedule?
--
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-18 11:19:04.865258955 +0100
@@ -67,18 +67,18 @@
</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
-Debian user, and the prospectus developer. It uses pretty common language, and
-it's well covered with working examples. There is an old Roman saying,
-<emphasis>Longum iter est per preaecepta, breve et efficax per
-exempla!</emphasis> (It's a long way by the rules, but short and efficient with
-examples!).
+This document tries to describe the building of a Debian package to ordinary
+Debian users and prospective developers. It uses fairly non-technical language, and
+it's well covered with working examples. There is an old Latin saying:
+<emphasis>Longum iter est per preacepta, breve et efficax per
+exempla</emphasis> (It's a long way by the rules, but short and efficient with
+examples).
</para>
<para>
This document has been updated for the Debian <literal>&base-release;</literal>
release.
-<footnote><para> The document assumes you are using the
-<literal>&base-release;</literal> system or newer. If you need to follow this
+<footnote><para> The document assumes you are using a
+<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.
@@ -88,25 +88,26 @@
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
-a little about Unix programming but you certainly don't need to be a wizard.
+you were a rookie, you wouldn't be reading this document now :-)
+You do need to know a little about Unix programming but you certainly
+don't need to be a wizard.
<footnote><para>
-You can learn basic operations of the Debian system from
+You can learn about the basic handling of a Debian system from the
<ulink url="&debref;">Debian Reference</ulink>. It contains some pointers to
learn about Unix programming, too.
</para></footnote>
</para>
<para>
One thing is certain, though: to properly create and maintain Debian packages
-you need many hours. Make no mistake, for our system to work the maintainers
+takes many hours. Make no mistake, for our system to work the maintainers
need to be both technically competent and diligent.
</para>
<para>
This document will explain every little (at first maybe irrelevant) step, and
help you create that first package, and to gain some experience in building
-next releases of that and maybe other packages later on.
+the next releases of that and maybe other packages later on.
</para>
<para>
If you need some help on packaging, please read <xref linkend="helpme"/>.
@@ -115,18 +116,19 @@
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
+The translations may be available in packages such as
<systemitem role="package">maint-guide-es</systemitem>.
Please note that this documentation may be slightly outdated.
</para>
-<section id="socialdynamism"><title>Social dynamism of Debian</title>
+<section id="socialdynamism"><title>Social dynamics of Debian</title>
<para>
-Here are my observations of the social dynamism of Debian. I hope this will prepare you for the interaction with Debian.
+Here are my observations of the social dynamics of Debian. I hope
+this will prepare you for your interactions with the Debian community.
</para>
<itemizedlist>
<listitem><para>We all are volunteers.</para>
<itemizedlist>
- <listitem><para>You can not impose others what to do.</para></listitem>
+ <listitem><para>You cannot impose on others what to do.</para></listitem>
<listitem><para>You should be motivated to do things by yourself.</para></listitem>
</itemizedlist></listitem>
<listitem><para>Friendly cooperation is the driving force.</para>
@@ -137,12 +139,12 @@
<listitem><para>Debian is not your school where you get automatic attention of teachers.</para>
<itemizedlist>
<listitem><para>You should be able to learn many things by yourself.</para></listitem>
- <listitem><para>Attention of other volunteers is the very scarce resource.</para></listitem>
+ <listitem><para>Attention from other volunteers is a very scarce resource.</para></listitem>
</itemizedlist></listitem>
<listitem><para>Debian is constantly improving.</para>
<itemizedlist>
<listitem><para>You are expected to make high quality packages.</para></listitem>
- <listitem><para>You should adapt yourself to the change.</para></listitem>
+ <listitem><para>You should adapt yourself to change.</para></listitem>
</itemizedlist></listitem>
</itemizedlist>
<para>
@@ -160,8 +162,8 @@
</section>
<section id="debiandeveloper"><title>Official Debian Developer</title>
<para>
-You can not become an official
-<emphasis role="strong">Debian Developer</emphasis> (DD) over night because it
+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
@@ -171,7 +173,7 @@
<para>
Please note that you do not need to create any new package to become an
official Debian Developer. Contributing to the existing packages can provide a
-path to become an official Debian Developer too. There are many packages
+path to becoming an official Debian Developer too. There are many packages
waiting for good maintainers (see <xref linkend="choose"/>).
</para>
</section>
@@ -192,85 +194,86 @@
<para>
The most important package to install on your development system is the
<systemitem role="package">build-essential</systemitem> package. Once you try
-to install it, it will <emphasis>pull in</emphasis> other packages required to
+to install that, it will <emphasis>pull in</emphasis> other packages required to
have a basic build environment.
</para>
<para>
-For some types of packages, that is all you will require, however there is
+For some types of packages, that is all you will require; however, there is
another set of packages that while not essential for all package builds are
-useful to have install or may be required by your package:
+useful to have installed or may be required by your package:
</para>
<itemizedlist>
<listitem>
<para>
-<systemitem role="package">file</systemitem> - this handy program can determine
-what type a file is. (see <citerefentry> <refentrytitle>file</refentrytitle>
-<manvolnum>1</manvolnum> </citerefentry>)
-</para>
-</listitem>
-<listitem>
-<para>
-<systemitem role="package">patch</systemitem> - this very useful utility will
-take a file containing a difference listing (produced by the
-<command>diff</command> program) and apply it to the original file, producing a
-patched version. (see <citerefentry> <refentrytitle>patch</refentrytitle>
-<manvolnum>1</manvolnum> </citerefentry>)
+<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">perl</systemitem> - Perl is one of the most used
-interpreted scripting languages on today's Unix-like systems, often referred to
-as Unix's Swiss Army Chainsaw. (see <citerefentry>
-<refentrytitle>perl</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>)
+<systemitem role="package">debhelper</systemitem> and
+<systemitem role="package">dh-make</systemitem> -
+<systemitem role="package">dh-make</systemitem> is necessary to create
+the skeleton of our example package, and it will use some of the
+<systemitem role="package">debhelper</systemitem> tools for creating
+packages. They are not essential for this purpose, but are
+<emphasis>highly</emphasis> recommended for new maintainers. It makes
+the whole process very much easier to start, and to control afterwards.
+(See <citerefentry> <refentrytitle>dh_make</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry>, <citerefentry>
+<refentrytitle>debhelper</refentrytitle> <manvolnum>1</manvolnum>
+</citerefentry>.) <footnote><para> There are also some more specialized
+but similar packages such as
+<systemitem role="package">dh-make-perl</systemitem>,
+<systemitem role="package">dh-make-php</systemitem>, etc. </para>
+</footnote>
</para>
</listitem>
<listitem>
<para>
-<systemitem role="package">python</systemitem> - Python is another of the most
-used interpreted scripting languages on the Debian system that combines
-remarkable power with very clear syntax. (see <citerefentry>
-<refentrytitle>python</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>)
+<systemitem role="package">devscripts</systemitem> - this package contains some
+useful scripts that can be helpful for maintainers, but they are also
+not necessary for building packages. Packages recommended and suggested
+by this package are worth looking into. (See <ulink url="&devscripts-readme;"/>.)
</para>
</listitem>
<listitem>
<para>
-<systemitem role="package">autoconf</systemitem>, <systemitem role="package">automake</systemitem> and <systemitem role="package">autotools-dev</systemitem> - many newer programs use configure
-scripts and <filename>Makefile</filename> files preprocessed with help of
-programs like these. (see <literal>info autoconf</literal>, <literal>info
-automake</literal>). The <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.
+<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>
+<manvolnum>1</manvolnum> </citerefentry>.)
</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
-example package, and it will use some of the <systemitem role="package">debhelper</systemitem> tools for creating packages. They are
-not essential for creation of packages, but are <emphasis>highly</emphasis>
-recommended for new maintainers. It makes the whole process very much easier
-to start, and control afterwards. (see <citerefentry>
-<refentrytitle>dh_make</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry>, <citerefentry> <refentrytitle>debhelper</refentrytitle>
-<manvolnum>1</manvolnum> </citerefentry>) <footnote><para> There
-are few similar but specialized packages such as <systemitem role="package">dh-make-perl</systemitem>, <systemitem role="package">dh-make-php</systemitem>, etc. </para> </footnote>
+<systemitem role="package">file</systemitem> - this handy program can determine
+what type a file is. (See <citerefentry> <refentrytitle>file</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry>.)
</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
-also not necessary for building packages. Packages recommended and suggested
-by this package are worth looking into. (see
-<ulink url="&devscripts-readme;"/>.)
+<systemitem role="package">gfortran</systemitem> - the GNU Fortran 95 compiler,
+necessary if your program is written in Fortran. (See <citerefentry>
+<refentrytitle>gfortran</refentrytitle> <manvolnum>1</manvolnum>
+</citerefentry>.)
</para>
</listitem>
<listitem>
<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>
-<manvolnum>1</manvolnum> </citerefentry>)
+<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>
@@ -278,16 +281,8 @@
<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>
-<para>
-<systemitem role="package">gfortran</systemitem> - the GNU Fortran 95 compiler,
-necessary if your program is written in Fortran. (see <citerefentry>
-<refentrytitle>gfortran</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry>)
+when your work gets included in the Debian distribution. (See <citerefentry>
+<refentrytitle>gpg</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
<listitem>
@@ -295,30 +290,36 @@
<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>)
+<citerefentry> <refentrytitle>ppc386</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
<listitem>
<para>
-<systemitem role="package">xutils-dev</systemitem> - some programs, usually
-those made for X11, also use these programs to generate
-<filename>Makefile</filename> files from sets of macro functions. (see
-<citerefentry> <refentrytitle>imake</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry>, <citerefentry> <refentrytitle>xmkmf</refentrytitle>
-<manvolnum>1</manvolnum> </citerefentry>)
+<systemitem role="package">lintian</systemitem> - this is the Debian package
+checker, which can let you know of any common mistakes after you build the
+package, and explains the errors found. (See <citerefentry>
+<refentrytitle>lintian</refentrytitle> <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
-checker that can let you know of any common mistakes after you build the
-package, and explains the errors found. (see <citerefentry>
-<refentrytitle>lintian</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry>,
-<ulink url="&lintian-doc;">Lintian User's Manual</ulink>)
+<systemitem role="package">patch</systemitem> - this very useful utility will
+take a file containing a difference listing (produced by the
+<command>diff</command> program) and apply it to the original file, producing a
+patched version. (See <citerefentry> <refentrytitle>patch</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry>.)
+</para>
+</listitem>
+<listitem>
+<para>
+<systemitem role="package">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>
@@ -335,9 +336,18 @@
</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.
+<systemitem role="package">perl</systemitem> - Perl is one of the most used
+interpreted scripting languages on today's Unix-like systems, often referred to
+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>
@@ -345,19 +355,19 @@
<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.
They are logically organized as a stack, and you can apply (=push), un-apply
-(=pop), refresh them easily by traveling into the stack. (see <citerefentry>
+(=pop), or refresh them easily by traveling into the stack. (See <citerefentry>
<refentrytitle>quilt</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
-<ulink url="&quilt-pdf;">quilt.pdf</ulink>)
+<ulink url="&quilt-pdf;">quilt.pdf</ulink>.)
</para>
</listitem>
<listitem>
<para>
-<systemitem role="package">git</systemitem> - this package provides popular
-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>)
+<systemitem role="package">xutils-dev</systemitem> - some programs, usually
+those made for X11, also use these programs to generate
+<filename>Makefile</filename> files from sets of macro functions. (See
+<citerefentry> <refentrytitle>imake</refentrytitle> <manvolnum>1</manvolnum>
+</citerefentry>, <citerefentry> <refentrytitle>xmkmf</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry>.)
</para>
</listitem>
</itemizedlist>
@@ -368,12 +378,12 @@
going now, but later on you'll be <emphasis>very</emphasis> glad you read it.
</para>
<para>
-If you have specific questions later, I suggest you to read the documents
-mentioned above again. Since this is a tutorial, I intentionally skipped
+If you have specific questions later, I would suggest re-reading the documents
+mentioned above. Since this is a tutorial, I have intentionally skipped
details and provided only pointers to keep it simple.
</para>
</section>
-<section id="needdocs"><title>Documentations you need for development</title>
+<section id="needdocs"><title>Documentation needed for development</title>
<para>
The following is the <emphasis>very important</emphasis> documentation which
you should read along with this document:
@@ -381,10 +391,18 @@
<itemizedlist>
<listitem>
<para>
+<ulink url="&autotools-tutorial;">Autotools
+Tutorial</ulink> provides a very good tutorial for <ulink url="&gnu-build-system;">the GNU Build System known
+as the GNU Autotools</ulink> whose most important components are autoconf,
+automake, libtool, and gettext.
+</para>
+</listitem>
+<listitem>
+<para>
<systemitem role="package">debian-policy</systemitem> - the <ulink url="&debian-policy;">Debian Policy
Manual</ulink> includes explanations of the structure and contents of the
-Debian archive, several OS design issues, the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink>
-(FHS, which says where each file and directory should be) etc. For you, the most
+Debian archive, several OS design issues, the <ulink url="&fhs;">Filesystem Hierarchy Standard</ulink>
+(FHS, which says where each file and directory should be), etc. For you, the most
important thing is that it describes requirements that each package must
satisfy to be included in the distribution (see the local copies of
<ulink url="&policy-pdf;">policy.pdf</ulink> and <ulink url="&fhs-pdf;">fhs-2.3.pdf</ulink>).
@@ -396,17 +414,9 @@
- 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,
-when and where to upload etc. (see the local copy of
-<ulink url="&developers-refpdf;">developers-reference.pdf</ulink>).
-</para>
-</listitem>
-<listitem>
-<para>
-<ulink url="&autotools-tutorial;">Autotools
-Tutorial</ulink> provides 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.
+or adopt packages, how to do NMUs, how to manage bugs, best packaging practices,
+when and where to upload etc. (See the local copy of
+<ulink url="&developers-refpdf;">developers-reference.pdf</ulink>.)
</para>
</listitem>
<listitem>
@@ -416,15 +426,16 @@
<ulink url="&gnu-standard;">GNU Coding Standards</ulink>, and
<ulink url="&gnu-maintainer;">Information for Maintainers of GNU Software</ulink>.
Although Debian does not require these to
-be followed, these are still helpful as guidelines and common sense. (see the local copies of
+be followed, these are still helpful as guidelines and common sense.
+(See the local copies of
<ulink url="&gnu-standard-pdf;">standards.pdf</ulink> and
-<ulink url="&gnu-maintainer-pdf;">maintain.pdf</ulink>).
+<ulink url="&gnu-maintainer-pdf;">maintain.pdf</ulink>.)
</para>
</listitem>
</itemizedlist>
<para>
-If this document contradicts with any of the documents mentioned above, they
-are correct. Please file a bug report on the
+If this document contradicts any of the documents mentioned above, they
+are correct. Please file a bug report on the
<systemitem role="package">maint-guide</systemitem> package using
<command>reportbug</command>.
</para>
@@ -436,73 +447,74 @@
<itemizedlist>
<listitem>
<para>
-<emphasis role="strong">source package</emphasis>: A source package is a set of
+<emphasis role="strong">source package</emphasis>: a source package is a set of
files which contain code and data which you can compile and process into
-execution programs and formatted documents. It usually comes as a combination
+executable 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.
+archiving and compression methods may be used, too.
</para>
</listitem>
<listitem>
<para>
-<emphasis role="strong">binary package</emphasis>: A binary package contains
-execution programs and formatted documents. It usually comes as
+<emphasis role="strong">binary package</emphasis>: a binary package contains
+executable 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
+Don't confuse terms like source of the program and the source package of the
program!
</para>
<para>
-There are several role names used around Debian.
+There are several official names used within Debian to refer to different
+roles.
</para>
<itemizedlist>
<listitem>
<para>
-<emphasis role="strong">upstream author</emphasis>: The person who made the
+<emphasis role="strong">upstream author</emphasis>: the person who made the
original program.
</para>
</listitem>
<listitem>
<para>
-<emphasis role="strong">upstream maintainer</emphasis>: The person who
+<emphasis role="strong">upstream maintainer</emphasis>: the person who
currently maintains the program.
</para>
</listitem>
<listitem>
<para>
-<emphasis role="strong">maintainer</emphasis>: The person who makes Debian
+<emphasis role="strong">maintainer</emphasis>: the person making the Debian
package of the program.
</para>
</listitem>
<listitem>
<para>
-<emphasis role="strong">sponsor</emphasis>: The person who helps maintainers to
-upload packages to the official Debian Package Archive after checking their
-contents.
+<emphasis role="strong">sponsor</emphasis>: a person who helps maintainers to
+upload packages to the official Debian package archive (after checking their
+contents).
</para>
</listitem>
<listitem>
<para>
-<emphasis role="strong">mentor</emphasis>: The person who helps novice
-maintainers on packaging etc.
+<emphasis role="strong">mentor</emphasis>: a person who helps novice
+maintainers with packaging etc.
</para>
</listitem>
<listitem>
<para>
-<emphasis role="strong">Debian Developer</emphasis> (DD): The person who is a
-member of Debian. He has full upload right to the official Debian Package
-Archive.
+<emphasis role="strong">Debian Developer</emphasis> (DD): a member of
+the Debian project with full upload rights to the official Debian package
+archive.
</para>
</listitem>
<listitem>
<para>
-<emphasis role="strong">Debian Maintainer</emphasis> (DM): The person who has
-limited upload right to the official Debian Package Archive.
+<emphasis role="strong">Debian Maintainer</emphasis> (DM): a person with
+limited upload rights to the official Debian package archive.
</para>
</listitem>
</itemizedlist>
@@ -596,11 +608,11 @@
</listitem>
</itemizedlist>
<para>
-Please consider to use web search engine effectively by including search string
+You can use web search engines more effectively by including search strings
such as <literal>site:lists.debian.org</literal> to limit the domain.
</para>
<para>
-Making a small test package is good way to learn details of packaging.
+Making a small test package is a good way to learn details of packaging.
Inspecting existing well maintained packages is the best way to learn how other
people make packages.
</para>
@@ -635,7 +647,8 @@
<ulink url="&bts;">Debian Bug Tracking System</ulink>
and read the documentation there, to be able to
deal with the reports efficiently. I highly recommend reading the
-<ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8. 'Handling bugs'</ulink>.
+<ulink url="&devref-bug-handling;">Debian Developer's Reference, 5.8:
+"Handling bugs"</ulink>.
</para>
<para>
Even if it all worked well, it's time to start praying. Why? Because in just
Reply to: