Re: Updated maint-guide contents, question on style
Chapter 7 is another easy one, though it includes a few sentences
where I wasn't sure what you were trying to say.
In 7.1, the solutions suggested for a file collision are (a) using
alternatives, (b) coordinating with other affected packages, and (c)
using a Conflicts. It seems to me that (a) is a subcategory of (b);
you can't set up alternatives unilaterally, can you? I've rephrased
the text to mention (c) first, then (b), giving (a) as an example.
But then what about the omitted option (d), just patching the package
to rename the relevant file?
--
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 23:15:04.017256444 +0100
@@ -4240,48 +4240,49 @@
</chapter>
<chapter id="checkit"><title>Checking the package for errors</title>
<para>
-There are few chores you should know to check the package for errors by
-yourself before uploading packages to public archives.
+There are some techniques you should know for checking a package for errors
+before uploading it to the public archives.
</para>
<para>
-Testing on machine other than your own is also good idea. You must watch
-closely for any warnings or errors for all the test described here.
+It's also a good idea to carry out testing on a machine other than your own. You must watch
+closely for any warnings or errors for all the tests described here.
</para>
-<section id="pinstall"><title>Verifying package for install</title>
+<section id="pinstall"><title>Verifying a package's installation</title>
<para>
-You must test your package if it installs without problem. The <citerefentry>
+You must test your package for whether it installs without problem. The <citerefentry>
<refentrytitle>debi</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
-command helps you to test to install all the generated binary packages.
+command helps you to test installing all the generated binary packages.
</para>
<screen>
$ sudo debi gentoo_0.9.12-1_i386.changes
</screen>
<para>
-You have to make sure that there are no overlapped files with other existing
-packages using the
+To prevent installation problem on different systems, you must make
+sure that there are no filenames conflict with other existing packages,
+using the
<filename>Contents-<replaceable>i386</replaceable></filename> file downloaded
-from the Debian archive to prevent installation problem on different systems.
+from the Debian archive,
The <command>apt-file</command> command may be handy for this task. If there
-are overlapped files, please take actions to avoid the real problem using the
-alternatives mechanism (see <citerefentry>
-<refentrytitle>update-alternatives</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry>) by coordinating with other affected packages or by setting the
-<literal>Conflicts</literal> entry in the <filename>debian/control</filename>
-file.
+are collisions, please take action to avoid this real problem, whether by
+declaring a <literal>Conflicts</literal> relationship in the
+<filename>debian/control</filename> file or by coordinating with other
+affected packages, for instance to use the alternatives mechanism (see
+<citerefentry> <refentrytitle>update-alternatives</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry>).
</para>
</section>
-<section id="pmaintscripts"><title>Verifying package for <emphasis>maintainer scripts</emphasis></title>
+<section id="pmaintscripts"><title>Verifying a package's maintainer scripts</title>
<para>
-All <emphasis>maintainer scripts</emphasis>, i.e.,
+All maintainer scripts (that is,
<filename>preinst</filename>, <filename>prerm</filename>,
-<filename>postinst</filename>, and <filename>postrm</filename> files, are
-non-trivial unless they are auto-generated by the <systemitem role="package">debhelper</systemitem> programs. So do not use them if you are
+<filename>postinst</filename>, and <filename>postrm</filename> files) are
+potentially problematic unless they are auto-generated by the
+<systemitem role="package">debhelper</systemitem> programs. So do not use them if you are
a novice maintainer (see <xref linkend="maintscripts"/>).
</para>
<para>
-If the package makes use of these non-trivial <emphasis>maintainer
-scripts</emphasis>, be sure to test not only for install but also for remove,
-purge, and upgrade. Many <emphasis>maintainer script</emphasis> bugs show up
+If the package makes use of these non-trivial maintainer scripts, be sure to test not only for install but also for remove,
+purge, and upgrade processes. Many maintainer script bugs show up
when packages are removed or purged. Use the <command>dpkg</command> command
as follows to test them.
</para>
@@ -4345,11 +4346,11 @@
last Debian release. Remember to test upgrades from that version too.
</para>
<para>
-Although downgrade is not officially supported, it should be nice to support
-it.
+Although downgrading is not officially supported, supporting it is a
+friendly gesture.
</para>
</section>
-<section id="lintians"><title><systemitem role="package">lintian</systemitem> package</title>
+<section id="lintians"><title>Using <systemitem role="package">lintian</systemitem></title>
<para>
Run <citerefentry> <refentrytitle>lintian</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> on your <filename>.changes</filename>
@@ -4366,23 +4367,23 @@
<para>
Of course, replace the filename with the name of the
<filename>.changes</filename> file generated for your package. The output of
-the <command>lintian</command> command are marked as follows.
+the <command>lintian</command> command uses the following flags.
</para>
<itemizedlist>
<listitem>
<para>
-<literal>E:</literal> for error; a sure policy violation or a packaging error.
+<literal>E:</literal> for error; a sure policy violation or packaging error.
</para>
</listitem>
<listitem>
<para>
-<literal>W:</literal> for warning; a possible policy violation or a packaging
+<literal>W:</literal> for warning; a possible policy violation or packaging
error.
</para>
</listitem>
<listitem>
<para>
-<literal>I:</literal> for info; a information on certain packaging aspects.
+<literal>I:</literal> for info; information on certain aspects of packaging.
</para>
</listitem>
<listitem>
@@ -4399,21 +4400,21 @@
</listitem>
</itemizedlist>
<para>
-For warnings, tune the package to avoid them or verify that the warnings are
-spurious. If spurious, set the <filename>lintian-overrides</filename> files as
+When you see warnings, tune the package to avoid them or verify that the warnings are
+spurious. If spurious, set up <filename>lintian-overrides</filename> files as
described in <xref linkend="lintian"/>.
</para>
<para>
Note that you can build the package with <command>dpkg-buildpackage</command>
-and run <command>lintian</command> on it in one command with <citerefentry>
+and run <command>lintian</command> on it in one command, if you use <citerefentry>
<refentrytitle>debuild</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
-or with <citerefentry> <refentrytitle>pdebuild</refentrytitle>
+or <citerefentry> <refentrytitle>pdebuild</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>.
</para>
</section>
-<section id="debc"><title><command>debc</command> command</title>
+<section id="debc"><title>The <command>debc</command> command</title>
<para>
-You can list files in the binary Debian package by <citerefentry>
+You can list files in the binary Debian package with the <citerefentry>
<refentrytitle>debc</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
command.
</para>
@@ -4421,7 +4422,7 @@
$ debc <replaceable>package</replaceable>.changes
</screen>
</section>
-<section id="debdiff"><title><command>debdiff</command> command</title>
+<section id="debdiff"><title>The <command>debdiff</command> command</title>
<para>
You can compare file contents in two source Debian packages with the
<citerefentry> <refentrytitle>debdiff</refentrytitle> <manvolnum>1</manvolnum>
@@ -4439,12 +4440,12 @@
$ debdiff <replaceable>old-package</replaceable>.changes <replaceable>new-package</replaceable>.changes
</screen>
<para>
-These are useful to identify what has been changed in the source packages, if
-no files have been unintentionally misplaced or removed in the binary packages,
-and if no other inadvertent changes were made when updating binary packages.
+These are useful to identify what has been changed in the source packages
+and to check for inadvertent changes made when updating binary
+packages, such as unintentionally misplacing or removing files.
</para>
</section>
-<section id="interdiff"><title><command>interdiff</command> command</title>
+<section id="interdiff"><title>The <command>interdiff</command> command</title>
<para>
You can compare two <filename>diff.gz</filename> files with the <citerefentry>
<refentrytitle>interdiff</refentrytitle> <manvolnum>1</manvolnum>
@@ -4461,7 +4462,7 @@
<filename>debian/patches/*</filename> file using <command>interdiff</command>, too.
</para>
</section>
-<section id="mc"><title><command>mc</command> command</title>
+<section id="mc"><title>The <command>mc</command> command</title>
<para>
Many of these file inspection operations can be made into an intuitive process
by using a file manager like <citerefentry> <refentrytitle>mc</refentrytitle>
@@ -4473,7 +4474,7 @@
<para>
Be on the lookout for extra unneeded files or zero length files, both in the
binary and source package. Often cruft doesn't get cleaned up properly; adjust
-your <filename>rules</filename> file to compensate for that.
+your <filename>rules</filename> file to compensate for this.
</para>
</section>
</chapter>
Reply to: