Justin B Rye
2017-06-05 13:00:01 UTC
Package: release-notes
Severity: wishlist
Tags: patch
I'm calling this wishlist as usual, but I'm splitting it into two
patches: one for things that really need doing, one for things that
are stylistic and can be put off if necessary.
First, though: the text still says that doing an upgrade from within
GDM will cause trouble (with a comment from vorlon saying he'd checked
and this was still true). I've heard rumours that this isn't true any
longer... but I'm not in a position to check, and better safe than
sorry, so I'm not going to propose changing the text.
Another thing I'm *not* trying to do this time round is go through all
the references to /etc/apt/sources.list making them more general.
However, the file also contains quite a few leftover references to FTP
package mirrors:
Index: upgrading.dbk
===================================================================
--- upgrading.dbk (revision 11552)
+++ upgrading.dbk (working copy)
@@ -455,7 +455,7 @@
be found via any <quote><literal>deb</literal></quote> line, and install the package with the
highest version number, giving priority to the first line in the
file (thus where you have multiple mirror locations, you'd typically first name a local
-hard disk, then <acronym>CD-ROM</acronym>s, and then HTTP/FTP mirrors).
+hard disk, then <acronym>CD-ROM</acronym>s, and then remote mirrors).
</para>
There was no particular reason to mention protocols here in the first
place.
By the way, I'm not fond of this inconsistent use of <acronym>, but
I'll ignore that even in the low-priority patch.
<para>
@@ -503,14 +503,15 @@
to use other mirrors, preferably a mirror that is closest to you in network terms.
</para>
<para>
-Debian HTTP or FTP mirror addresses can be found at <ulink
+Debian mirror addresses can be found at <ulink
url="&url-debian-mirrors;"></ulink> (look at the <quote>list of Debian
-mirrors</quote> section). HTTP mirrors are generally speedier than FTP mirrors.
+mirrors</quote> section). Note that FTP mirrors are being
+discontinued - see <xref linkend="old-sources"/>.
</para>
I hope I'm getting this syntax right.
<para>
For example, suppose your closest Debian mirror is
-<literal>&url-debian-mirror-eg;</literal>. When inspecting that
-mirror with a web browser or FTP program, you will notice that the main
+<literal>&url-debian-mirror-eg;</literal>. If you inspect that
+mirror with a web browser, you will notice that the main
directories are organized like this:
</para>
<programlisting>
Incorporating a phrasing change: I don't need to inspect it now that
you've told me what it looks like, so it isn't a "when".
@@ -536,23 +537,23 @@
<section id="localmirror">
<title>Adding APT sources for a local mirror</title>
<para>
-Instead of using HTTP or FTP package mirrors, you may wish to modify
+Instead of using HTTP package mirrors, you may wish to modify
<filename>/etc/apt/sources.list</filename> to use a mirror on a local disk
(possibly mounted over <acronym>NFS</acronym>).
</para>
<para>
Or perhaps this should say "remote package mirrors"? At any rate,
I've also renamed the assumed directory structure:
For example, your package mirror may be under
-<filename>/var/ftp/debian/</filename>, and have main directories like this:
+<filename>/var/local/debian/</filename>, and have main directories like this:
</para>
<programlisting>
-/var/ftp/debian/dists/&releasename;/main/binary-&architecture;/...
-/var/ftp/debian/dists/&releasename;/contrib/binary-&architecture;/...
+/var/local/debian/dists/&releasename;/main/binary-&architecture;/...
+/var/local/debian/dists/&releasename;/contrib/binary-&architecture;/...
</programlisting>
<para>
To use this with <systemitem role="package">apt</systemitem>, add this line to your
<filename>sources.list</filename> file:
</para>
-<programlisting>deb file:/var/ftp/debian &releasename; main contrib</programlisting>
+<programlisting>deb file:/var/local/debian &releasename; main contrib</programlisting>
<para>
Note that the <quote><literal>dists</literal></quote> is added implicitly, and the arguments
after the release name are used to expand the path into multiple directories.
(That last one is a good example of &releasename; actually being
useful and needing to be lowercase.)
Next, a less urgent patch (applying on top of that one, though I don't
think the two patches collide anywhere) with stylistic and grammatical
fixes. Some of these issues are badly garbled English, but none of
them are really unintelligible so they can be delayed if necessary.
--- upgrading.dbk 2017-06-05 13:13:42.257552357 +0100
+++ upgrading.dbk.dle 2017-06-05 13:30:06.285740099 +0100
@@ -139,8 +139,8 @@
</para>
<para>
-Generally we recommend using the <emphasis>rescue
-mode</emphasis> of the &releasename; Debian Installer. The advantage of using the
+For emergency recovery we generally recommend using the <emphasis>rescue
+mode</emphasis> of the &releasename; Debian Installer. The advantage of using the
installer is that you can choose between its many methods to find one
that best suits your situation. For more information, please consult the
section <quote>Recovering a Broken System</quote> in chapter 8 of the <ulink
Make it clearer that we don't in fact recommend using it *generally*,
only in this context.
@@ -153,7 +153,7 @@
If that fails, you will need an alternative way to boot your system so you can
access and repair it. One option is to use a special rescue image or a Linux
live CD. After booting from that, you should be able to mount your root file
-system and <literal>chroot</literal> into it to investigate and fix the
+system and <command>chroot</command> into it to investigate and fix the
problem.
</para>
More appropriate markup.
@@ -278,10 +278,10 @@
before you begin upgrading.
</para>
<para>
- Below there are two methods for finding suchs packages by using either
+ Below there are two methods for finding such packages by using either
<command>aptitude</command> or <command>apt-forktracer</command>. Please
note that neither of them are 100% accurate (e.g. the aptitude example
- will list packages that was once provided by Debian but no longer is like
+ will list packages that were once provided by Debian but no longer are, such as
old kernel packages).<screen>
$ aptitude search '~i(!~ODebian)'
$ apt-forktracer | sort
Two kinds of un-English number agreement.
@@ -319,7 +319,7 @@
linkend="old-sources"/>.
</para>
<para>
-To perform this review, launch <command>aptitude</command> in <quote>visual mode</quote> and
+To perform this review, launch <command>aptitude</command> in full-terminal mode and
press <keycap>g</keycap> (<quote>Go</quote>). If it shows any actions, you should review them and either fix
them or implement the suggested actions. If no actions are suggested you will
be presented with a message saying <quote>No packages are scheduled to be installed,
Another attempt to get the unintelligible name of this mode replaced
by an intelligible description. See also below.
@@ -616,7 +616,7 @@
use the package management tool <command>apt-get</command>. In previous
releases, <command>aptitude</command> was recommended for this purpose, but
recent versions of <command>apt-get</command> provide equivalent
-functionality and also have shown to more consistently give the desired
+functionality and also have proven to more consistently give the desired
upgrade results.
</para>
<para>
You don't "show" to do things, but "prove" just about works.
@@ -794,7 +794,7 @@
<command>wajig</command> (running <literal>wajig size</literal>).
They can also be found with
<systemitem role="package">aptitude</systemitem>. Start
-<command>aptitude</command> in <quote>visual mode</quote>,
+<command>aptitude</command> in full-terminal mode,
select <menuchoice><guimenu>Views</guimenu><guimenuitem>New Flat Package
List</guimenuitem></menuchoice>, press <keycap>l</keycap> and enter
<literal>~i</literal>, then press <keycap>S</keycap> and enter
As above.
@@ -1176,7 +1176,7 @@
<para>
If you are unsure about which package to select, run <literal>uname
-r</literal> and look for a package with a similar name. For example, if you
-see '<literal>2.6.32-5-amd64</literal>', it is recommended that you install
+see <quote><literal>2.6.32-5-amd64</literal></quote>, it is recommended that you install
<systemitem role="package">linux-image-amd64</systemitem>.
You may also use <command>apt-cache</command> to see a long
description of each package in order to help choose the best one
Consistent quoting.
@@ -1276,7 +1276,7 @@
<section id="obsolete">
<title>Obsolete packages</title>
<para>
-Introducing lot of new packages, &releasename; also retires and omits quite some
+Introducing lots of new packages, &releasename; also retires and omits quite a few
old packages that were in &oldreleasename;. It provides no upgrade path
for these obsolete packages. While nothing prevents you from continuing to use
an obsolete package where desired, the Debian project will usually discontinue
Two un-English quantifiers.
Severity: wishlist
Tags: patch
I'm calling this wishlist as usual, but I'm splitting it into two
patches: one for things that really need doing, one for things that
are stylistic and can be put off if necessary.
First, though: the text still says that doing an upgrade from within
GDM will cause trouble (with a comment from vorlon saying he'd checked
and this was still true). I've heard rumours that this isn't true any
longer... but I'm not in a position to check, and better safe than
sorry, so I'm not going to propose changing the text.
Another thing I'm *not* trying to do this time round is go through all
the references to /etc/apt/sources.list making them more general.
However, the file also contains quite a few leftover references to FTP
package mirrors:
Index: upgrading.dbk
===================================================================
--- upgrading.dbk (revision 11552)
+++ upgrading.dbk (working copy)
@@ -455,7 +455,7 @@
be found via any <quote><literal>deb</literal></quote> line, and install the package with the
highest version number, giving priority to the first line in the
file (thus where you have multiple mirror locations, you'd typically first name a local
-hard disk, then <acronym>CD-ROM</acronym>s, and then HTTP/FTP mirrors).
+hard disk, then <acronym>CD-ROM</acronym>s, and then remote mirrors).
</para>
There was no particular reason to mention protocols here in the first
place.
By the way, I'm not fond of this inconsistent use of <acronym>, but
I'll ignore that even in the low-priority patch.
<para>
@@ -503,14 +503,15 @@
to use other mirrors, preferably a mirror that is closest to you in network terms.
</para>
<para>
-Debian HTTP or FTP mirror addresses can be found at <ulink
+Debian mirror addresses can be found at <ulink
url="&url-debian-mirrors;"></ulink> (look at the <quote>list of Debian
-mirrors</quote> section). HTTP mirrors are generally speedier than FTP mirrors.
+mirrors</quote> section). Note that FTP mirrors are being
+discontinued - see <xref linkend="old-sources"/>.
</para>
I hope I'm getting this syntax right.
<para>
For example, suppose your closest Debian mirror is
-<literal>&url-debian-mirror-eg;</literal>. When inspecting that
-mirror with a web browser or FTP program, you will notice that the main
+<literal>&url-debian-mirror-eg;</literal>. If you inspect that
+mirror with a web browser, you will notice that the main
directories are organized like this:
</para>
<programlisting>
Incorporating a phrasing change: I don't need to inspect it now that
you've told me what it looks like, so it isn't a "when".
@@ -536,23 +537,23 @@
<section id="localmirror">
<title>Adding APT sources for a local mirror</title>
<para>
-Instead of using HTTP or FTP package mirrors, you may wish to modify
+Instead of using HTTP package mirrors, you may wish to modify
<filename>/etc/apt/sources.list</filename> to use a mirror on a local disk
(possibly mounted over <acronym>NFS</acronym>).
</para>
<para>
Or perhaps this should say "remote package mirrors"? At any rate,
I've also renamed the assumed directory structure:
For example, your package mirror may be under
-<filename>/var/ftp/debian/</filename>, and have main directories like this:
+<filename>/var/local/debian/</filename>, and have main directories like this:
</para>
<programlisting>
-/var/ftp/debian/dists/&releasename;/main/binary-&architecture;/...
-/var/ftp/debian/dists/&releasename;/contrib/binary-&architecture;/...
+/var/local/debian/dists/&releasename;/main/binary-&architecture;/...
+/var/local/debian/dists/&releasename;/contrib/binary-&architecture;/...
</programlisting>
<para>
To use this with <systemitem role="package">apt</systemitem>, add this line to your
<filename>sources.list</filename> file:
</para>
-<programlisting>deb file:/var/ftp/debian &releasename; main contrib</programlisting>
+<programlisting>deb file:/var/local/debian &releasename; main contrib</programlisting>
<para>
Note that the <quote><literal>dists</literal></quote> is added implicitly, and the arguments
after the release name are used to expand the path into multiple directories.
(That last one is a good example of &releasename; actually being
useful and needing to be lowercase.)
Next, a less urgent patch (applying on top of that one, though I don't
think the two patches collide anywhere) with stylistic and grammatical
fixes. Some of these issues are badly garbled English, but none of
them are really unintelligible so they can be delayed if necessary.
--- upgrading.dbk 2017-06-05 13:13:42.257552357 +0100
+++ upgrading.dbk.dle 2017-06-05 13:30:06.285740099 +0100
@@ -139,8 +139,8 @@
</para>
<para>
-Generally we recommend using the <emphasis>rescue
-mode</emphasis> of the &releasename; Debian Installer. The advantage of using the
+For emergency recovery we generally recommend using the <emphasis>rescue
+mode</emphasis> of the &releasename; Debian Installer. The advantage of using the
installer is that you can choose between its many methods to find one
that best suits your situation. For more information, please consult the
section <quote>Recovering a Broken System</quote> in chapter 8 of the <ulink
Make it clearer that we don't in fact recommend using it *generally*,
only in this context.
@@ -153,7 +153,7 @@
If that fails, you will need an alternative way to boot your system so you can
access and repair it. One option is to use a special rescue image or a Linux
live CD. After booting from that, you should be able to mount your root file
-system and <literal>chroot</literal> into it to investigate and fix the
+system and <command>chroot</command> into it to investigate and fix the
problem.
</para>
More appropriate markup.
@@ -278,10 +278,10 @@
before you begin upgrading.
</para>
<para>
- Below there are two methods for finding suchs packages by using either
+ Below there are two methods for finding such packages by using either
<command>aptitude</command> or <command>apt-forktracer</command>. Please
note that neither of them are 100% accurate (e.g. the aptitude example
- will list packages that was once provided by Debian but no longer is like
+ will list packages that were once provided by Debian but no longer are, such as
old kernel packages).<screen>
$ aptitude search '~i(!~ODebian)'
$ apt-forktracer | sort
Two kinds of un-English number agreement.
@@ -319,7 +319,7 @@
linkend="old-sources"/>.
</para>
<para>
-To perform this review, launch <command>aptitude</command> in <quote>visual mode</quote> and
+To perform this review, launch <command>aptitude</command> in full-terminal mode and
press <keycap>g</keycap> (<quote>Go</quote>). If it shows any actions, you should review them and either fix
them or implement the suggested actions. If no actions are suggested you will
be presented with a message saying <quote>No packages are scheduled to be installed,
Another attempt to get the unintelligible name of this mode replaced
by an intelligible description. See also below.
@@ -616,7 +616,7 @@
use the package management tool <command>apt-get</command>. In previous
releases, <command>aptitude</command> was recommended for this purpose, but
recent versions of <command>apt-get</command> provide equivalent
-functionality and also have shown to more consistently give the desired
+functionality and also have proven to more consistently give the desired
upgrade results.
</para>
<para>
You don't "show" to do things, but "prove" just about works.
@@ -794,7 +794,7 @@
<command>wajig</command> (running <literal>wajig size</literal>).
They can also be found with
<systemitem role="package">aptitude</systemitem>. Start
-<command>aptitude</command> in <quote>visual mode</quote>,
+<command>aptitude</command> in full-terminal mode,
select <menuchoice><guimenu>Views</guimenu><guimenuitem>New Flat Package
List</guimenuitem></menuchoice>, press <keycap>l</keycap> and enter
<literal>~i</literal>, then press <keycap>S</keycap> and enter
As above.
@@ -1176,7 +1176,7 @@
<para>
If you are unsure about which package to select, run <literal>uname
-r</literal> and look for a package with a similar name. For example, if you
-see '<literal>2.6.32-5-amd64</literal>', it is recommended that you install
+see <quote><literal>2.6.32-5-amd64</literal></quote>, it is recommended that you install
<systemitem role="package">linux-image-amd64</systemitem>.
You may also use <command>apt-cache</command> to see a long
description of each package in order to help choose the best one
Consistent quoting.
@@ -1276,7 +1276,7 @@
<section id="obsolete">
<title>Obsolete packages</title>
<para>
-Introducing lot of new packages, &releasename; also retires and omits quite some
+Introducing lots of new packages, &releasename; also retires and omits quite a few
old packages that were in &oldreleasename;. It provides no upgrade path
for these obsolete packages. While nothing prevents you from continuing to use
an obsolete package where desired, the Debian project will usually discontinue
Two un-English quantifiers.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package