[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#863975: marked as done (release-notes: proofreading sweep - old-stuff.dbk)



Your message dated Sat, 03 Jun 2017 09:56:00 +0000
with message-id <5e4edb21-e3f4-1a0a-c5a8-fdd31d02be56@thykier.net>
and subject line Re: Bug#863975: release-notes: proofreading sweep - old-stuff.dbk
has caused the Debian Bug report #863975,
regarding release-notes: proofreading sweep - old-stuff.dbk
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@bugs.debian.org
immediately.)


-- 
863975: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=863975
Debian Bug Tracking System
Contact owner@bugs.debian.org with problems
--- Begin Message ---
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>

--- End Message ---
--- Begin Message ---
Justin B Rye:
> 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.
> 

Thanks!

I have applied the patch and also rewritten some of the content based on
your remarks. :)

> [...]
> 
> 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.
> 

Ack, have left them as-is

> 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.
> 

I opted for a footnote, text:

<literal>deb ftp:</literal><footnote>
  <para>
    <ulink
    url="https://lists.debian.org/debian-announce/2017/msg00001.html";>Debian
    will remove FTP access to all of its official mirrors on
    2017-11-01</ulink>.  If your sources.list contains a
    <literal>debian.org</literal> host, please consider switching to
    <ulink url="https://deb.debian.org";>deb.debian.org</ulink>.
    This note only applies to mirrors hosted by Debian itself.  If you
    use a secondary mirror or a third-party repository, then they may
    still support FTP access after that date.  Please consult with the
    operators of these if you are in doubt.
  </para>
</footnote>

> For Buster we'll also want to mention at least "deb https:".
> 

I added it already along with "tor+" variants.

> 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".
> 

We should but haven't done it.  I am filing a separate bug for that.

> [...]
> 
> 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>
>         
> [...] We should probably replace this whole section with something more like: 
> [...]
> 

Done as well. :)

Thanks,
~Niels

--- End Message ---

Reply to: