Re: Updated maint-guide contents, question on style
Chapter 6. This one didn't take long...
6.1: I've taken out the references to md5sums, which were deprecated a
while back.
6.4: the man page says DEBUILD_LINTIAN=yes is the default; should the
example config perhaps skip that line?
6.5: when you say "setting /var/cache/pbuilder/result directory
writable by the user", I assume you don't mean "chmod u+w" (it's
already user-writable); I've changed it to say "writable for your user
account" (and I imagine I'd do that with chgrp jbr and chmod g+w).
--
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-26 12:39:22.721258717 +0100
@@ -3717,8 +3717,8 @@
</para>
<section id="completebuild"><title>Complete (re)build</title>
<para>
-In order to properly make complete (re)build of a package, you have to ensure
-to install
+In order to perform a complete (re)build of a package properly, you
+need to make sure you have installed
</para>
<itemizedlist>
<listitem>
@@ -3825,8 +3825,8 @@
</para>
<para>
This compressed tarball contains your <filename>debian</filename> directory
-contents. Each and every addition you made to the original source code are
-stored as <command>quilt</command> patches in
+contents. Each and every addition you made to the original source code is
+stored as a <command>quilt</command> patch in
<filename>debian/patches</filename>.
</para>
<para>
@@ -3854,14 +3854,14 @@
<filename>gentoo_0.9.12-1_i386.changes</filename>
</para>
<para>
-This file describes all the changes made in the current package revision, and
+This file describes all the changes made in the current package revision;
it is used by the Debian FTP archive maintenance programs to install the binary
-and source packages in it. It is partly generated from the
+and source packages. It is partly generated from the
<filename>changelog</filename> file and the <filename>.dsc</filename> file.
This file is GPG signed, so that people can be sure that it's really yours.
</para>
<para>
-As you keep working on the package, behavior will change and new features will
+As you keep working on the package, its behavior will change and new features will
be added. People downloading your package can look at this file and quickly
see what has changed. Debian archive maintenance programs will also post the
contents of this file to the <ulink url="&debian-devel-announce-ldo;">debian-devel-announce@lists.debian.org</ulink>
@@ -3871,11 +3871,10 @@
</itemizedlist>
<para>
The long strings of numbers in the <filename>.dsc</filename> and
-<filename>.changes</filename> files are MD5/SHA1/SHA256 checksums for the files
-mentioned. A person downloading your files can test them with <citerefentry>
-<refentrytitle>md5sum</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>,
-<citerefentry> <refentrytitle>sha1sum</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry>, or <citerefentry> <refentrytitle>sha256sum</refentrytitle>
+<filename>.changes</filename> files are SHA1/SHA256 checksums for the files
+mentioned. Anyone downloading your files can test them with <citerefentry>
+<refentrytitle>sha1sum</refentrytitle> <manvolnum>1</manvolnum>
+</citerefentry> or <citerefentry> <refentrytitle>sha256sum</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> and if the numbers don't match,
they'll know the file is corrupt or has been tampered with.
</para>
@@ -3884,17 +3883,17 @@
<para>
Debian supports many <ulink url="&ports;">ports</ulink>
with the <ulink url="&buildd;">autobuilder
-network</ulink> running <command>buildd</command> daemons on many different
-architecture computers. Although you do not need to do this by yourself, you
-should be aware of what will happen on your packages. Let's look into roughly
-how your packages are rebuild for many different architectures by them.
+network</ulink> running <command>buildd</command> daemons on computers
+of many different architectures. Although you do not need to do this yourself, you
+should be aware of what will happen to your packages. Let's look into roughly
+how they rebuild your packages for multiple architectures.
<footnote><para> The actual autobuilder system involves much more complicated
schemes than the one documented here. Such details are beyond the scope of
this document. </para> </footnote>
</para>
<para>
For <literal>Architecture: any</literal> packages, the autobuilder system
-rebuild them. It ensures to install
+performs a rebuild. It ensures the installation of
</para>
<itemizedlist>
<listitem>
@@ -3951,16 +3950,18 @@
This is why you see your package for other architectures.
</para>
<para>
-Although packages listed in the <literal>Build-Depends-indep</literal> field
-are required to be installed for the normal packaging by us (see <xref linkend="completebuild"/>), they are not required to be installed for the
-autobuilder system since it build only architecture dependent binary packages.
+Although packages listed in the <literal>Build-Depends-Indep</literal> field
+are required to be installed for our normal packaging work (see
+<xref linkend="completebuild"/>), they are not required to be installed for the
+autobuilder system since it builds only architecture dependent binary packages.
<footnote><para> Unlike under the <systemitem role="package">pbuilder</systemitem> package, the <command>chroot</command>
environment under the <systemitem role="package">sbuild</systemitem> package
-used by the autobuilder system does not force the minimal system and may leave
-many packages installed. </para> </footnote> This difference between normal
-packaging and autobuilder situation dictates whether you record such required
+used by the autobuilder system does not enforce the use of a minimal
+system and may have many leftover packages installed. </para>
+</footnote> This distinction between normal packaging and autobuilding
+procedures is what dictates whether you should record such required
packages in the <literal>Build-Depends</literal> or
-<literal>Build-Depends-indep</literal> fields of the
+<literal>Build-Depends-Indep</literal> fields of the
<filename>debian/control</filename> file (see <xref linkend="control"/>).
</para>
</section>
@@ -3968,17 +3969,17 @@
<para>
When you first upload the package to the archive, you need to include the
original <filename>orig.tar.gz</filename> source, too. If the Debian revision
-number of such package is neither <literal>1</literal> nor
-<literal>0</literal>, you must provide <command>dpkg-buildpackage</command>
+number of this package is neither <literal>1</literal> nor
+<literal>0</literal>, you must provide the <command>dpkg-buildpackage</command>
command with the <literal>-sa</literal> option. On the other hand, the
-<literal>-sd</literal> option will force to exclude the original
+<literal>-sd</literal> option will force the exclusion of the original
<filename>orig.tar.gz</filename> source.
</para>
</section>
<section id="debuild"><title><command>debuild</command> command</title>
<para>
-You can automate package build process of the
-<command>dpkg-buildpackage</command> command further with the
+You can automate the <command>dpkg-buildpackage</command> command's
+package build process further with the
<command>debuild</command> command. See <citerefentry>
<refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum>
</citerefentry>.
@@ -3986,7 +3987,7 @@
<para>
Customization of the <command>debuild</command> command can be done through
<filename>/etc/devscripts.conf</filename> or
-<filename>~/.devscripts</filename>. I would suggest at least following items:
+<filename>~/.devscripts</filename>. I would suggest at least the following items:
</para>
<screen>
DEBSIGN_KEYID=Your_GPG_keyID
@@ -3995,11 +3996,10 @@
</screen>
<para>
With these, packages are signed by your specified GPG key ID (good for
-sponsoring packages) and checked by the <command>lintian</command> command in
-details.
+sponsoring packages) and checked in detail by the <command>lintian</command> command.
</para>
<para>
-Cleaning source and rebuilding package from a user account is as simple as:
+Cleaning the source and rebuilding the package from your user account is as simple as:
</para>
<screen>
$ debuild
@@ -4013,7 +4013,7 @@
$ debuild -sa
</screen>
<para>
-You can clean source tree as simple as:
+You can clean the source tree as simply as:
</para>
<screen>
$ debuild clean
@@ -4023,37 +4023,39 @@
<para>
For a clean room (<command>chroot</command>) build environment to verify the
build dependencies, the <systemitem role="package">pbuilder</systemitem>
-package is very useful. <footnote><para> Since the <systemitem role="package">pbuilder</systemitem> package is still evolving, you have to
+package is very useful. <footnote><para> Since the <systemitem
+role="package">pbuilder</systemitem> package is still evolving, you should
check the actual configuration situation by consulting the latest official
documentation.</para> </footnote> This ensures a clean build from the source
under the <literal>sid</literal> auto-builder for different architectures and
-avoids the severity serious FTBFS (Fails To Build From Source) bug which is
+avoids a severity serious FTBFS (Fails To Build From Source) bug which is
always in the RC (release critical) category.
-<footnote><para>See <ulink url="&buildd-do;"/> for more on the
-auto-builder of the Debian package.</para></footnote>
+<footnote><para>See <ulink url="&buildd-do;"/> for more on
+Debian package auto-building.
+.</para></footnote>
</para>
<para>
-Let's customize the <systemitem role="package">pbuilder</systemitem> package by
-the following.
+Let's customize the <systemitem role="package">pbuilder</systemitem> package as
+follows:
</para>
<itemizedlist>
<listitem>
<para>
-setting <filename>/var/cache/pbuilder/result</filename> directory writable by
-the user.
+setting the <filename>/var/cache/pbuilder/result</filename> directory writable by
+for your user account.
</para>
</listitem>
<listitem>
<para>
creating a directory, e.g.
<filename><replaceable>/var/cache/pbuilder/hooks</replaceable></filename>,
-writable by the user to place hook scripts.
+writable by the user, to place hook scripts in.
</para>
</listitem>
<listitem>
<para>
-setting <filename>~/.pbuilderrc</filename> or
-<filename>/etc/pbuilderrc</filename> to include as follows.
+configuring <filename>~/.pbuilderrc</filename> or
+<filename>/etc/pbuilderrc</filename> to include the followsing.
</para>
<screen>
AUTO_DEBSIGN=yes
@@ -4066,14 +4068,14 @@
<filename>~/.gnupg/</filename> directory.
</para>
<para>
-Let's then initialize the local <systemitem role="package">pbuilder</systemitem> <command>chroot</command> system first as
+First let's initialize the local <systemitem role="package">pbuilder</systemitem> <command>chroot</command> system as
follows.
</para>
<screen>
$ sudo pbuilder create
</screen>
<para>
-If you already have the completed source packages, issue the following commands
+If you already have a completed source package, issue the following commands
in the directory where the
<filename><replaceable>foo</replaceable>.orig.tar.gz</filename>,
<filename><replaceable>foo</replaceable>.debian.tar.gz</filename>, and
@@ -4098,8 +4100,8 @@
<filename>/var/cache/pbuilder/result/</filename> with non-root ownership.
</para>
<para>
-If you already have the updated source tree without generating the matching
-source packages, issue the following commands in the source directory where the
+If you have an updated source tree but have not generated the matching
+source package, issue the following commands in the source directory where the
<filename>debian</filename> directory exists, instead.
</para>
<screen>
@@ -4126,7 +4128,7 @@
<filename><replaceable>/var/cache/pbuilder/hooks</replaceable>/B90lintian</filename>
configured as follows. <footnote><para> This assumes
<literal>HOOKDIR=/var/cache/pbuilder/hooks</literal>. You can find many
-examples of the hook script in the
+examples of hook scripts in the
<filename>/usr/share/doc/pbuilder/examples</filename> directory. </para>
</footnote>
</para>
@@ -4145,8 +4147,8 @@
</screen>
<para>
You need to have access to the latest <literal>sid</literal> environment to
-build packages properly for <literal>sid</literal>. In reality,
-<literal>sid</literal> may be experiencing issues which makes it not desirable
+build packages properly for <literal>sid</literal>. In practice,
+<literal>sid</literal> may be experiencing issues which makes it undesirable
for you to migrate your whole system. The <systemitem role="package">pbuilder</systemitem> package can help you to cope with this
kind of situation.
</para>
@@ -4155,9 +4157,9 @@
release for <literal>stable-proposed-updates</literal>,
<literal>stable/updates</literal>, etc. <footnote><para> There are some
restrictions for such updates of your <literal>stable</literal> package.
-</para> </footnote> For such occasions, I am running <literal>sid</literal>
-system is not good enough excuse not to update them promptly. The <systemitem role="package">pbuilder</systemitem> package can help you to access
-environments of almost any Debian derivative distributions of the same CPU
+</para> </footnote> For such occasions, the fact you may be running a <literal>sid</literal>
+system is not a good enough excuse for failing to update them promptly. The <systemitem role="package">pbuilder</systemitem> package can help you to access
+environments of almost any Debian derivative distribution of the same CPU
architecture.
</para>
<para>
@@ -4171,16 +4173,16 @@
</section>
<section id="git-buildpackage"><title><command>git-buildpackage</command> command and similars</title>
<para>
-If your upstream uses the source code management system (VCS)
+If your upstream uses a source code management system (VCS)
<footnote><para>See <ulink url="&debref-vcs;">Version control systems</ulink> for more.</para></footnote>
-to maintain their code, you should consider to use them. That makes merging
+to maintain their code, you should consider using it as well. This makes merging
and cherry-picking upstream patches much easier. There are several specialized
-wrapper script packages for the Debian package building for each VCS.
+wrapper script packages for Debian package building for each VCS.
</para>
<itemizedlist>
<listitem>
<para>
-<systemitem role="package">git-buildpackage</systemitem>: Suite to help with
+<systemitem role="package">git-buildpackage</systemitem>: a suite to help with
Debian packages in Git repositories.
</para>
</listitem>
@@ -4192,19 +4194,19 @@
</listitem>
<listitem>
<para>
-<systemitem role="package">cvs-buildpackage</systemitem>: A set of Debian
+<systemitem role="package">cvs-buildpackage</systemitem>: a set of Debian
package scripts for CVS source trees.
</para>
</listitem>
</itemizedlist>
<para>
-There are packages which <emphasis>automate</emphasis> building of packages
-under VCS managed source tree for advanced audiences. I will not explain them
+For advanced audiences, there are packages which <emphasis>automate</emphasis>
+the building of packages under a VCS-managed source tree. I will not explain them
in this tutorial.
-<footnote><para> Here are few web resources available for advanced audiences. </para>
+<footnote><para> Here are some web resources available for advanced audiences. </para>
<itemizedlist>
-<listitem> <para> <ulink url="&git-buildpackage-doc;">Building Debian Packages with git-buildpackage</ulink> </para> </listitem>
-<listitem> <para> <ulink url="&debian-packages-git;">debian packages in git</ulink> </para> </listitem>
+<listitem> <para> <ulink url="&git-buildpackage-doc;">Building Debian Packages with git-buildpackage</ulink> </para> </listitem>
+<listitem> <para> <ulink url="&debian-packages-git;">debian packages in git</ulink> </para> </listitem>
<listitem> <para> <ulink url="&git-debian-packaging;">Using Git for Debian Packaging</ulink> </para> </listitem>
<listitem> <para> <ulink url="&git-dpm;">git-dpm: Debian packages in Git manager</ulink> </para> </listitem>
<listitem> <para> <ulink url="&topgit;">Using TopGit to generate quilt series for Debian packaging</ulink> </para> </listitem>
@@ -4215,9 +4217,9 @@
<section id="quickrebuild"><title>Quick rebuild</title>
<para>
With a large package, you may not want to rebuild from scratch every time while
-you tune details in <filename>debian/rules</filename>. For testing purposes,
+you're tuning details in <filename>debian/rules</filename>. For testing purposes,
you can make a <filename>.deb</filename> file without rebuilding the upstream
-sources like this <footnote><para> Environment variables which are normally
+sources like this<footnote><para> Environment variables which are normally
configured to proper values are not set by this method. Never create real
packages to be uploaded using this <emphasis role="strong">quick</emphasis>
method. </para> </footnote>:
@@ -4226,7 +4228,7 @@
$ fakeroot debian/rules binary
</screen>
<para>
-Or, simply as following to see if it build or not.
+Or simply do the following to see if it builds or not:
</para>
<screen>
$ fakeroot debian/rules build
Reply to: