Bug#863975: release-notes: proofreading sweep - old-stuff.dbk
Package: release-notes
Severity: wishlist
Tags: patch
This file's the shortest, and only has two trivial stylistic issues,
but might need some attention to the content.
Index: old-stuff.dbk
===================================================================
--- old-stuff.dbk (revision 11524)
+++ old-stuff.dbk (working copy)
@@ -30,7 +30,8 @@
<title>Checking your sources list</title>
<para>
If any of the lines in your <filename>/etc/apt/sources.list</filename> refer to
-'stable', you are effectively already <quote>using</quote> &releasename;. This
+<quote><literal>stable</literal></quote>,
+you are effectively already <quote>using</quote> &releasename;. This
might not be what you want if you are not ready yet for the upgrade. If
you have already run
<literal>apt-get update</literal>, you can still get back without problems
Replacing the use of "verbatim" single-quotes with the markup normally
used for that function in these release-notes.
In a release or two we might want to turn some or all of these
references to "apt-get" into plain "apt", but here I think it doesn't
much matter.
Another change I'm not sure enough about to have put in the patch:
<para>
Open the file <filename>/etc/apt/sources.list</filename> with your favorite
editor (as <literal>root</literal>) and check all lines beginning with
<literal>deb http:</literal> or <literal>deb ftp:</literal> for a reference to
<quote><literal>stable</literal></quote>. If you find any, change
<literal>stable</literal> to <literal>&oldreleasename;</literal>.
</para>
Maybe this wants a footnote pointing to the no-more-FTP announcement:
"https://lists.debian.org/debian-announce/2017/msg00001.html";. Mind
you, this is assuming that FTP will still technically be usable in
Stretch with secondary mirrors; but do we know if there really are any
that support FTP? If not, instead of a possible footnote it'll want a
definite inline warning to start by switching to HTTP.
For Buster we'll also want to mention at least "deb https:".
Incidentally, the release-notes mention /etc/apt/sources.list plenty
of times but never /etc/apt/sources.list.d/*.list files; and soon
we'll also have the option of deb822-style .sources files - see the
sources.list(5) in stretch. We'll need to come up with a generic term
and use that instead; I'd suggest "APT source-list files".
@@ -59,7 +62,7 @@
Do not change any lines that begin with <literal>deb cdrom:</literal>.
Doing so would invalidate the line and you would have to
run <command>apt-cdrom</command> again. Do not be alarmed if a
- 'cdrom' source line refers to <quote><literal>unstable</literal></quote>.
+ <literal>cdrom:</literal> source line refers to <quote><literal>unstable</literal></quote>.
Although confusing, this is normal.
</para>
</important>
As above.
Then there's another section that may need some updating (but again
I've left it untouched in my patch for now):
<title>Upgrade legacy locales to UTF-8</title>
Most of this has been here since squeeze, and the added examples of
bad consequences were basically "upstream wontfix" even then. These
days the docs say things like "neither dbus-daemon nor systemd
supports environment variables with non-UTF-8 names or values", so
it's not just a matter of GNOME - we should probably replace this
whole section with something more like:
<para>
Using a legacy non-UTF-8 locale has been unsupported by desktops and
other mainstream software projects for a long time. Such locales
should be upgraded by running <command>dpkg-reconfigure
locales</command> and selecting a UTF-8 default. You should also
ensure that users are not overriding the default to use a legacy
locale in their environment.
</para>
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Index: old-stuff.dbk
===================================================================
--- old-stuff.dbk (revision 11524)
+++ old-stuff.dbk (working copy)
@@ -30,7 +30,8 @@
<title>Checking your sources list</title>
<para>
If any of the lines in your <filename>/etc/apt/sources.list</filename> refer to
-'stable', you are effectively already <quote>using</quote> &releasename;. This
+<quote><literal>stable</literal></quote>,
+you are effectively already <quote>using</quote> &releasename;. This
might not be what you want if you are not ready yet for the upgrade. If
you have already run
<literal>apt-get update</literal>, you can still get back without problems
@@ -59,7 +60,7 @@
Do not change any lines that begin with <literal>deb cdrom:</literal>.
Doing so would invalidate the line and you would have to
run <command>apt-cdrom</command> again. Do not be alarmed if a
- 'cdrom' source line refers to <quote><literal>unstable</literal></quote>.
+ <literal>cdrom:</literal> source line refers to <quote><literal>unstable</literal></quote>.
Although confusing, this is normal.
</para>
</important>
Reply to: