Re: Updated maint-guide contents, question on style
Chapter 5.
It's possible that the reference in 5.3 to debhelper v3 is old enough
to be retired.
I've de-italicised "maintainer scripts" and "init scripts" throughout
(except for the line in 5.18 where it's defining "maintainer scripts")
since I don't see any reason for treating the phrases specially.
In 5.4 I've turned "cron.hourly" etc. in the bulleted list into
"package.cron.hourly" etc., since the text goes on to refer to
"package.cron.d" as the odd one out among them...
Oh, and I've also taken out the claims that cronjobs usually run on
Sunday, on the first of the month, etc., which aren't necessarily
true. My desktop, for instance, does weekly jobs on Wednesdays and
monthly ones on the 15th of the month, when the timestamps in
/var/spool/anacron reach the appropriate ages.
In 5.11 I've changed the dh_install example:
- src/foo/mybin usr/bin
+ src/foo/binary usr/bin
since to me "mybin" sounded more like a directory name.
5.13: your bashglob shorthand is wrong! It's {foo,bar} not {foo|bar}.
Or would it be safer to list them in full?
I've edited 5.14.1 footnote 50 to make it clear that the man pages
generated by help2man will be placeholders claiming that there's more
extensive documentation in the info system. Nowadays that assumption
is unsafe - the GNOME folks apparently abhor both man and info pages.
I've also taken out the reference to /usr/share/package/, since the
man page should still give a pointer even if it's under
/usr/share/doc/package/html or something.
5.18: I've corrected {post|pre}{inst|rm} to {pre,post}{inst,rm}
(chronological order trumps alphabetical order), and upgraded the
recommendation of POSIX syntax to a "should", partly to cut down on
first person pronouns.
--
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-25 19:32:28.328925447 +0100
@@ -2808,10 +2808,10 @@
<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
-what each of these does and its format. Please read <ulink url="&debian-policy;">Debian Policy
+<filename>debian</filename> directory. This chapter will provide an overview of
+what each of these does and its format. Please read the <ulink url="&debian-policy;">Debian Policy
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
@@ -2822,45 +2822,45 @@
them.
<footnote><para>
In this chapter, files in the <filename>debian</filename> directory are
-referred without preceding <filename>debian/</filename> for simplicity whenever
+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
-configuration files for <systemitem role="package">debhelper</systemitem>. In
-such cases, you need to create them with the editor.
+Some template configuration files for <systemitem role="package">debhelper</systemitem>
+may not be created by the <command>dh_make</command> command. In
+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
-name in place of <literal><replaceable>package</replaceable></literal>.
+rename the configuration files to use the actual binary package
+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"/>),
-if necessary.
+if necessary;
</para>
</listitem>
<listitem>
@@ -2871,21 +2871,21 @@
</listitem>
</itemizedlist>
<para>
-Those <systemitem role="package">debhelper</systemitem> configuration files
-without <filename><replaceable>package</replaceable></filename> prefix such as
-<filename>install</filename> apply to the first binary package. When there are
+Any <systemitem role="package">debhelper</systemitem> configuration files
+without a <filename><replaceable>package</replaceable></filename> prefix, such as
+<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
@@ -2899,17 +2899,17 @@
</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
-the following.
+should set it to the <systemitem role="package">debhelper</systemitem> v7 as
+follows:
</para>
<screen>
$ echo 7 > 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
@@ -2918,129 +2918,129 @@
<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 prompted whether you want to keep
+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>
+Since <systemitem role="package">debhelper</systemitem> v3, <citerefentry>
<refentrytitle>dh_installdeb</refentrytitle> <manvolnum>1</manvolnum>
</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
-<filename>/etc</filename> and so this file doesn't need to exist.
+package types, the only place conffiles should ever be is under
+<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
-make them not as conffiles to keep <command>dpkg</command> quiet.
+files in the <filename>/etc</filename> directory, there are two popular ways to
+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
-the <filename>/etc</filename> directory.
+Create a file generated by the maintainer scripts under 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
-hourly, daily, weekly or monthly or alternatively happen any other time that
+use these files to set that up. You can set up regular tasks that either happen
+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>/etc/cron.hourly/<replaceable>package</replaceable></filename>: run
-once an hour every hour.
+<filename><replaceable>package</replaceable>.cron.hourly</filename> - Installed as
+<filename>/etc/cron.hourly/<replaceable>package</replaceable></filename>; run
+once an hour.
</para>
</listitem>
<listitem>
<para>
-<filename>cron.daily</filename> - Installed as
-<filename>/etc/cron.daily/<replaceable>package</replaceable></filename>: run
-once a day, usually early morning.
+<filename><replaceable>package</replaceable>.cron.daily</filename> - Installed as
+<filename>/etc/cron.daily/<replaceable>package</replaceable></filename>; run
+once a day.
</para>
</listitem>
<listitem>
<para>
-<filename>cron.weekly</filename> - Installed as
-<filename>/etc/cron.weekly/<replaceable>package</replaceable></filename>: run
-once a week, usually early Sunday morning.
+<filename><replaceable>package</replaceable>.cron.weekly</filename> - Installed as
+<filename>/etc/cron.weekly/<replaceable>package</replaceable></filename>; run
+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
-is <filename><replaceable>package</replaceable>.cron.d</filename> which follows
+Most of these files are shell scripts, with the exception of
+<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>
-<refentrytitle>dh_installlogrotate</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry> and <citerefentry> <refentrytitle>logrotate</refentrytitle>
-<manvolnum>8</manvolnum> </citerefentry>.
+No explicit <filename>cron.*</filename> file is needed to set up log rotation;
+for that, see
+<citerefentry><refentrytitle>dh_installlogrotate</refentrytitle>
+<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"/>.
</para>
<para>
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 listed in
+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>
@@ -3048,7 +3048,7 @@
<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>
@@ -3071,7 +3071,7 @@
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>
@@ -3084,8 +3084,8 @@
<filename>README*</filename>, <filename>TODO</filename> etc.
</para>
<para>
-For <systemitem role="package">gentoo</systemitem>, I also included some other
-files:
+For <systemitem role="package">gentoo</systemitem>, some other files
+are also included:
</para>
<screen>
BUGS
@@ -3097,7 +3097,7 @@
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.
@@ -3111,23 +3111,23 @@
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
-for the <emphasis>init script</emphasis> which starts and stops a daemon.
+<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
@@ -3138,19 +3138,21 @@
</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 <emphasis>init script</emphasis>. Most times this
-<filename><replaceable>package</replaceable>.default</filename> file is used to disable running a daemon, set some default flags or
-timeouts. If your <emphasis>init script</emphasis> has certain <emphasis>settable</emphasis>
-features you want to install these into the <filename><replaceable>package</replaceable>.default</filename> file, not the <emphasis>init script</emphasis>.
+file sets defaults that are sourced by the init script. This
+<filename><replaceable>package</replaceable>.default</filename> file
+is most often used to disable running a daemon, or to set some default flags or
+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 provides a file for the <emphasis>init script</emphasis>, you can either use it or not. If you
-don't use their <emphasis>init script</emphasis> then create a new one in
+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 script then create a new one in
<filename><replaceable>package</replaceable>.init</filename>. However
-if the upstream <emphasis>init script</emphasis> looks fine and installs in the right place you
-still need to setup the <filename>rc*</filename> symlinks. To do this you will
+if the upstream init script looks fine and installs in the right place you
+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>
@@ -3162,10 +3164,10 @@
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
@@ -3179,51 +3181,51 @@
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
-where this is used is where a binary is forgotten to be installed, the
-<filename>install</filename> file would look like:
+where this is used is if a binary is left uninstalled; the
+<filename>install</filename> file might look like:
</para>
<screen>
-src/foo/mybin usr/bin
+src/foo/binary usr/bin
</screen>
<para>
-This will mean when this package is installed, there will be a binary file
-<filename>/usr/bin/mybin</filename>.
+This means that when this package is installed there will be a binary file
+<filename>/usr/bin/binary</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
-result into multiple binary packages using
+not change. This format is usually used for a large package that splits the 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
-<filename><replaceable>package</replaceable>.info</filename> files.
+</citerefentry> by listing them in a
+<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 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
<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.
@@ -3233,14 +3235,14 @@
is not installed.
</para>
</section>
-<section id="manpage"><title><filename>manpage.*</filename> files</title>
+<section id="manpage"><title><filename>manpage.*</filename></title>
<para>
Your program(s) should have a manual page. If they don't, you should create
-them. The <command>dh_make</command> command creates few template files for a
-manual page. These need to be copied and edited for each command without its
+them. The <command>dh_make</command> command creates some template files for
+manual pages. These need to be copied and edited for each command missing its
manual page. Please make sure to remove unused templates.
</para>
-<section id="manpage1"><title><filename>manpage.1.ex</filename> file</title>
+<section id="manpage1"><title><filename>manpage.1.ex</filename></title>
<para>
Manual pages are normally written in <citerefentry>
<refentrytitle>nroff</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>.
@@ -3250,7 +3252,7 @@
manual page for a brief description of how to edit such a file.
</para>
<para>
-The final manual page file name should include the name of the program it is
+The final manual page file name should give the name of the program it is
documenting, so we will rename it from <literal>manpage</literal> to
<literal>gentoo</literal>. The file name also includes <literal>.1</literal>
as the first suffix, which means it's a manual page for a user command. Be
@@ -3282,19 +3284,20 @@
<filename>gentoo.1</filename>. If there was no <filename>gentoo.1</filename>
man page in the original source, you should create it by renaming the
<filename>manpage.1.ex</filename> template to <filename>gentoo.1</filename> and
-edit it by using information from the example and from upstream docs.
+editing it using information from the example and from the upstream docs.
</para>
<para>
You can use the <command>help2man</command> command to generate a man page out
-of <literal>--help</literal> and <literal>--version</literal> output of each
-program, too. <footnote><para> If the command is missing
-<command>info</command> page but have documentation files in the
-<filename>/usr/share/<replaceable>package</replaceable></filename> directory,
-you should manually edit generated the man page created by the
+of the <literal>--help</literal> and <literal>--version</literal> output of each
+program, too. <footnote><para> Note that <command>help2man</command>'s
+placeholder man page will claim that more detailed documentation is
+available in the info system. If the command is missing an
+<command>info</command> page, you
+should manually edit the man page created by the
<command>help2man</command> command. </para> </footnote>
</para>
</section>
-<section id="manpagesgml"><title><filename>manpage.sgml.ex</filename> file</title>
+<section id="manpagesgml"><title><filename>manpage.sgml.ex</filename></title>
<para>
If on the other hand you prefer writing SGML instead of
<command>nroff</command>, you can use the <filename>manpage.sgml.ex</filename>
@@ -3319,7 +3322,7 @@
</listitem>
<listitem>
<para>
-add a <literal>override_dh_auto_build</literal> target to your
+add an <literal>override_dh_auto_build</literal> target to your
<filename>rules</filename> file:
</para>
<screen>
@@ -3330,7 +3333,7 @@
</listitem>
</itemizedlist>
</section>
-<section id="manpagexml"><title><filename>manpage.xml.ex</filename> file</title>
+<section id="manpagexml"><title><filename>manpage.xml.ex</filename></title>
<para>
If you prefer XML over SGML, you can use the <literal>manpage.xml.ex</literal>
template. If you do this, you have to:
@@ -3350,14 +3353,14 @@
</listitem>
<listitem>
<para>
-add the <literal>docbook-xsl</literal>, <literal>docbook-xml</literal> and
+add the <literal>docbook-xsl</literal>, <literal>docbook-xml</literal>, and
<literal>xsltproc</literal> packages to the <literal>Build-Depends</literal>
line in the <literal>control</literal> file
</para>
</listitem>
<listitem>
<para>
-add a <literal>override_dh_auto_build</literal> target to your
+add an <literal>override_dh_auto_build</literal> target to your
<filename>rules</filename> file:
</para>
<screen>
@@ -3379,18 +3382,18 @@
<para>
If your package has manual pages, you should install them using <citerefentry>
<refentrytitle>dh_installman</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry> by listing them in the
-<filename><replaceable>package</replaceable>.manpages</filename> files.
+</citerefentry> by listing them in a
+<filename><replaceable>package</replaceable>.manpages</filename> file.
</para>
<para>
-To install <filename>docs/gentoo.1</filename> for the <systemitem role="package">gentoo</systemitem> package as its manpage, you create a
-<filename>gentoo.manpages</filename> file as the following.
+To install <filename>docs/gentoo.1</filename> as a manpage for the <systemitem role="package">gentoo</systemitem> package, create a
+<filename>gentoo.manpages</filename> file as follows.
</para>
<screen>
docs/gentoo.1
</screen>
</section>
-<section id="menu"><title><filename>menu</filename> file</title>
+<section id="menu"><title><filename>menu</filename></title>
<para>
X Window System users usually have a window manager with a menu that can be
customized to launch programs. If they have installed the Debian <systemitem role="package">menu</systemitem> package, a set of menus for every program on
@@ -3411,11 +3414,11 @@
listed alternatives, e.g. <literal>text</literal> or <literal>X11</literal>.
</para>
<para>
-The next is <literal>section</literal>, where the menu and submenu entry
-should appear in.
-<footnote><para> The current list of sections is at
+The next is the <literal>section</literal> that the menu and submenu entry
+should appear in.
+<footnote><para> The current list of sections is in
<ulink url="&menu-structure;">The Debian Menu sub-policy 2.1 'Preferred menu structure'</ulink>.
-There were a major reorganization of menu structure for <literal>squeeze</literal>.
+There was a major reorganization of menu structure for <literal>squeeze</literal>.
</para> </footnote>
</para>
<para>
@@ -3442,85 +3445,90 @@
</citerefentry>, <citerefentry> <refentrytitle>menufile</refentrytitle>
<manvolnum>5</manvolnum> </citerefentry>, <citerefentry>
<refentrytitle>update-menus</refentrytitle> <manvolnum>1</manvolnum>
-</citerefentry> and
+</citerefentry>, and
<ulink url="&menu-policy;">The Debian Menu sub-policy</ulink> for more
information.
</para>
</section>
-<section id="news"><title><filename>NEWS</filename> file</title>
+<section id="news"><title><filename>NEWS</filename></title>
<para>
The <citerefentry> <refentrytitle>dh_installchangelogs</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> command installs this.
</para>
</section>
-<section id="maintscripts"><title><filename>{post|pre}{inst|rm}</filename> files</title>
+<section id="maintscripts"><title><filename>{pre,post}{inst,rm}</filename></title>
<para>
These <filename>postinst</filename>, <filename>preinst</filename>,
<filename>postrm</filename>, and <filename>prerm</filename> files
-<footnote><para> Although I used Bash short hand expression to indicate these
-files as <filename>{post|pre}{inst|rm}</filename> here, I recommend you to use
-pure POSIX (non-Bash) shell for these <emphasis>maintainer scripts</emphasis>
-as much as possible for the better compatibility. </para> </footnote> are
+<footnote><para> Despite this use of the <command>bash</command>
+shorthand expression <filename>{pre,post}{inst,rm}</filename> to indicate these
+filenames, you should use pure POSIX syntax for these maintainer scripts for
+compatibility with <command>dash</command> as the system shell. </para> </footnote> are
called <emphasis>maintainer scripts</emphasis>. They are scripts which are put
in the control area of the package and run by <command>dpkg</command> when your
-package is installed, upgraded or removed.
+package is installed, upgraded, or removed.
</para>
<para>
As a novice maintainer, you should avoid any manual editing of
-<emphasis>maintainer scripts</emphasis> because they are problematic. For more
-information look in the <ulink url="&policy-mantainerscripts;">Debian
+maintainer scripts because they are problematic. For more
+information refer to the <ulink url="&policy-mantainerscripts;">Debian
Policy Manual, 6 'Package maintainer scripts and installation
-procedure'</ulink>, and take a look at these example files provided by
+procedure'</ulink>, and take a look at the example files provided by
<command>dh_make</command>.
</para>
<para>
-If you did not listen to me and made your custom <emphasis>maintainer
-scripts</emphasis> for a package, you should make sure to test them not only
-for <emphasis role="strong">install</emphasis> and <emphasis role="strong">upgrade</emphasis> but also for <emphasis role="strong">remove</emphasis> and <emphasis role="strong">purge</emphasis>.
+If you did not listen to me and have created custom maintainer
+scripts for a package, you should make sure to test them not only
+for <emphasis role="strong">install</emphasis> and
+<emphasis role="strong">upgrade</emphasis> but also for
+<emphasis role="strong">remove</emphasis> and
+<emphasis role="strong">purge</emphasis>.
</para>
<para>
Upgrades to the new version should be silent and non-intrusive (existing users
should not notice the upgrade except by discovering that old bugs have been
-fixed and there perhaps are new features).
+fixed and perhaps that there are new features).
</para>
<para>
When the upgrade is necessarily intrusive (eg., config files scattered through
-various home directories with totally different structure), you may consider to
-set package to the safe default (e.g., disabled service) and provide proper
-documentations required by the policy (<filename>README.Debian</filename> and
-<filename>NEWS.Debian</filename>) as the last resort. Don't bother user with
-the <command>debconf</command> note invoked from these <emphasis>maintainer
-scripts</emphasis> for upgrades.
+various home directories with totally different structure), you may
+consider as the last resort switching the package to a safe fallback state
+(e.g., disabling a service) and providing the proper documentation
+required by policy (<filename>README.Debian</filename> and
+<filename>NEWS.Debian</filename>). Don't bother the user with
+<command>debconf</command> notes invoked from these maintainer scripts
+for upgrades.
</para>
<para>
-The <systemitem role="package">ucf</systemitem> package provides
+The <systemitem role="package">ucf</systemitem> package provides a
<emphasis>conffile-like</emphasis> handling infrastructure to preserve user
-changes for files that may not be labeled <emphasis>conffiles</emphasis> such
-as ones managed by the <emphasis>maintainer scripts</emphasis>. This should
+changes for files that may not be labeled as <emphasis>conffiles</emphasis> such
+as those managed by the maintainer scripts. This should
minimize issues associated with them.
</para>
<para>
-These <emphasis>maintainer scripts</emphasis> are the Debian enhancements that
+These maintainer scripts are among the Debian enhancements that
explain <emphasis role="strong">why people choose Debian</emphasis>. You must
-be very careful not to annoy them with these.
+be very careful not to turn them into a source of annoyance.
</para>
</section>
-<section id="todo"><title><filename>TODO</filename> file</title>
+<section id="todo"><title><filename>TODO</filename></title>
<para>
The <citerefentry> <refentrytitle>dh_installdocs</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry> command installs this.
</para>
</section>
-<section id="watch"><title><filename>watch</filename> file</title>
+<section id="watch"><title><filename>watch</filename></title>
<para>
The <filename>watch</filename> file format is documented in the <citerefentry>
<refentrytitle>uscan</refentrytitle> <manvolnum>1</manvolnum> </citerefentry>
manpage. The <filename>watch</filename> file configures the
<command>uscan</command> program (in the <systemitem role="package">devscripts</systemitem> package) to watch the site where you
-originally got the source from. This is also used by <ulink url="&dehs;">Debian External Health Status (DEHS)</ulink>.
+originally got the source from. This is also used by the
+<ulink url="&dehs;">Debian External Health Status (DEHS)</ulink> service.
</para>
<para>
-Here's what I put in it:
+Here are its contents:
</para>
<screen>
# watch control file for uscan
@@ -3528,30 +3536,30 @@
&sf-net;/gentoo/gentoo-(.+)\.tar\.gz debian uupdate
</screen>
<para>
-Normally with this <filename>watch</filename> file, the URL at
+Normally with a <filename>watch</filename> file, the URL at
<literal>&sf-net;/gentoo</literal> is downloaded and searched for links of
-the form <literal><a href=...></literal>. The base name (just the part
-after the final <literal>/</literal>) of these linked URLs are matched against
-Perl regular expression (see <citerefentry> <refentrytitle>perlre</refentrytitle>
-<manvolnum>1</manvolnum> </citerefentry>) pattern
-<literal>gentoo-(.+)\.tar\.gz</literal>. Out of matched files, the file with
+the form <literal><a href=...></literal>. The basename (just the part
+after the final <literal>/</literal>) of each linked URL is compared against
+the Perl regular expression pattern (see <citerefentry> <refentrytitle>perlre</refentrytitle>
+<manvolnum>1</manvolnum> </citerefentry>)
+<literal>gentoo-(.+)\.tar\.gz</literal>. Out of the files that match, the one with
the greatest version number is downloaded and the <command>uupdate</command>
-program is run to create the updated source tree from them.
+program is run to create an updated source tree.
</para>
<para>
Although this is true for other sites, the SourceForge download service at
<ulink url="&sf-net;"/> is an exception. When the
-<filename>watch</filename> file has an URL matching with the Perl regexp
+<filename>watch</filename> file has an URL matching the Perl regexp
<literal>^http://sf\.net/</literal>, the <command>uscan</command> program
-substitutes it with <literal>&qa-do;watch/sf.php/</literal> and
-then applies this rule. The URL redirector service at this <ulink url="&qa-do;"/> is designed to offer
-a stable redirect service to the desired file for the
-<filename>watch</filename> file having
+replaces it with <literal>&qa-do;watch/sf.php/</literal> and
+then applies this rule. The URL redirector service at <ulink url="&qa-do;"/> is designed to offer
+a stable redirect service to the desired file for any
+<filename>watch</filename> pattern of the form
<literal>&sf-net;/<replaceable>project</replaceable>/<replaceable>tar-name</replaceable>-(.+)\.tar\.gz</literal>.
-This solves issues related to the periodically changing URL there.
+This solves issues related to periodically changing SourceForge URLs.
</para>
</section>
-<section id="sourcef"><title><filename>source/format</filename> file</title>
+<section id="sourcef"><title><filename>source/format</filename></title>
<para>
In the <filename>debian/source/format</filename> file, there should be a single
line indicating the desired format for the source package (check <citerefentry>
@@ -3575,8 +3583,8 @@
The newer <literal>3.0 (quilt)</literal> source format records modifications in
a <command>quilt</command> patch series within
<filename>debian/patches</filename>. Those changes are then automatically
-applied during extraction of the source package. <footnote><para> See <ulink url="&debsrc3;">DebSrc3.0</ulink> for the
-summary information concerning the switch to the new <literal>3.0
+applied during extraction of the source package. <footnote><para> See
+<ulink url="&debsrc3;">DebSrc3.0</ulink> for a summary on the switch to the new <literal>3.0
(quilt)</literal> and <literal>3.0 (native)</literal> source formats. </para>
</footnote> The Debian modifications are simply stored in a
<filename>debian.tar.gz</filename> archive containing all files under the
@@ -3593,7 +3601,7 @@
the end of the extraction with the <literal>--skip-patches</literal> option.
</para>
</section>
-<section id="sourcel"><title><filename>source/local-options</filename> file</title>
+<section id="sourcel"><title><filename>source/local-options</filename></title>
<para>
When you want to manage Debian packaging activities under a VCS, you typically
create one branch (e.g. <literal>upstream</literal>) tracking the upstream
@@ -3618,7 +3626,7 @@
abort-on-upstream-changes
</screen>
</section>
-<section id="sourceopt"><title><filename>source/options</filename> file</title>
+<section id="sourceopt"><title><filename>source/options</filename></title>
<para>
The autogenerated files in the source tree can be quite annoying for packaging
since they generate meaningless large patch files. There are custom modules
@@ -3633,38 +3641,38 @@
creating the source package.
</para>
<para>
-You can store such <command>dpkg-source</command> option argument in the
-<filename>source/options</filename> file of the source package as the generic
-solution to address this problem of the autogenerated files. The following
+As a general solution to address this problem of the autogenerated files,
+you can store such a <command>dpkg-source</command> option argument in the
+<filename>source/options</filename> file of the source package. The following
will skip creating patch files for <filename>config.sub</filename>,
-<filename>config.guess</filename> and <filename>Makefile</filename>.
+<filename>config.guess</filename>, and <filename>Makefile</filename>.
</para>
<screen>
extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"
</screen>
</section>
-<section id="patches"><title><filename>patches/*</filename> files</title>
+<section id="patches"><title><filename>patches/*</filename></title>
<para>
The old <literal>1.0</literal> source format created a single large
-<filename>diff.gz</filename> file which contains package maintenance files in
-<filename>debian</filename> and patch files to the source. Such a package is a
+<filename>diff.gz</filename> file containing package maintenance files in
+<filename>debian</filename> and patch files for the source. Such a package is a
bit cumbersome to inspect and understand for each source tree modification
later. This is not so nice.
</para>
<para>
The newer <literal>3.0 (quilt)</literal> source format stores patches in
<filename>debian/patches/*</filename> files using the <command>quilt</command>
-command. These patches and other package data which are all constrained under
+command. These patches and other package data which are all contained under
the <filename>debian</filename> directory are packaged as the
<filename>debian.tar.gz</filename> file. Since the
<command>dpkg-source</command> command can handle <command>quilt</command>
formatted patch data in the <literal>3.0 (quilt)</literal> source without the
-<systemitem role="package">quilt</systemitem> package, it does not need to
-<literal>Build-Depends</literal> on the <systemitem role="package">quilt</systemitem> package. <footnote><para> Several methods
-for the patch set maintenance have been proposed and are in use with Debian
+<systemitem role="package">quilt</systemitem> package, it does not need a
+<literal>Build-Depends</literal> on <systemitem role="package">quilt</systemitem>.
+<footnote><para> Several methods of patch set maintenance have been proposed and are in use for Debian
packages. The <command>quilt</command> system is the preferred maintenance
-system in use. Other ones are <command>dpatch</command>,
-<command>dbs</command>, <command>cdbs</command>, etc. Many of these keep such
+system in use. Others include <command>dpatch</command>,
+<command>dbs</command>, and <command>cdbs</command>. Many of these keep such
patches as <filename>debian/patches/*</filename> files. </para> </footnote>
</para>
<para>
@@ -3673,26 +3681,26 @@
It records modifications to the source as a stack of <literal>-p1</literal>
patch files in the <filename>debian/patches</filename> directory and the source
tree is untouched outside of the <filename>debian</filename> directory. The
-order of these patches are recorded in the
+order of these patches is recorded in the
<filename>debian/patches/series</filename> file. You can apply (=push),
un-apply (=pop), and refresh patches easily. <footnote><para> If you are
asking a sponsor to upload your package, this kind of clear separation and
-documentation of your changes are very important to expedite the package review
+documentation of your changes is very important to expedite the package review
by your sponsor. </para> </footnote>
</para>
<para>
-For <xref linkend="modify"/>, we created 3 patches in
+For <xref linkend="modify"/>, we created three patches in
<filename>debian/patches</filename>.
</para>
<para>
Since Debian patches are located in <filename>debian/patches</filename>, please
-make sure to setup the <command>dquilt</command> command properly as described
+make sure to set up the <command>dquilt</command> command properly as described
in <xref linkend="quiltrc"/>.
</para>
<para>
-When someone (including yourself) provides you with a patch
+When anyone (including yourself) provides a patch
<filename><replaceable>foo</replaceable>.patch</filename> to the source later,
-then the modification of a <literal>3.0 (quilt)</literal> source package is
+modifying a <literal>3.0 (quilt)</literal> source package is
quite simple:
</para>
<screen>
@@ -3706,7 +3714,7 @@
</screen>
<para>
The patches stored in the newer <literal>3.0 (quilt)</literal> source format
-must be <emphasis>fuzz</emphasis> free. You should ensure it as <literal>dquilt
+must be <emphasis>fuzz</emphasis> free. You can ensure this with <literal>dquilt
pop -a; while dquilt push; do dquilt refresh; done</literal>.
</para>
</section>
Reply to: