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

Bug#864166: marked as done (release-notes: proofreading sweep - issues.dbk)

Your message dated Wed, 13 Feb 2019 22:17:40 +0100
with message-id <9e1cecf0-2612-cae4-1f16-4d142dbfec1e@debian.org>
and subject line Re: Bug#864166: release-notes: proofreading sweep - issues.dbk
has caused the Debian Bug report #864166,
regarding release-notes: proofreading sweep - issues.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.)


-- 
864166: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=864166
Debian Bug Tracking System
Contact owner@bugs.debian.org with problems
--- Begin Message --- 
Package: release-notes
Severity: wishlist

All of these are "stylistic", and could thus be put off until after
the release if we have to; they include some pretty annoying errors,
but nothing that would stop readers understanding what's intended.

 Index: issues.dbk
 ===================================================================
 --- issues.dbk	(revision 11524)
 +++ issues.dbk	(working copy)
 @@ -17,10 +17,10 @@
  </para>
  
  <section id="upgrade-specific-issues">
 -  <title>Upgrade specific items for &Releasename;</title>
 +  <title>Upgrade specific items for &releasename;</title>
    <para>
      This section covers items related to the upgrade from
 -    &Oldreleasename; to &Releasename;
 +    &oldreleasename; to &releasename;
    </para>
    <section id="late-mounting-usr">
      <!-- jessie to stretch -->
 @@ -42,7 +42,7 @@
      <para>
        This means that for &releasename; all systems where <filename>/usr</filename>
        is a separate partition need to use an initramfs generator that will mount
 -      <filename>/usr</filename>. All initramfs generators in &Releasename; do so.
 +      <filename>/usr</filename>. All initramfs generators in &releasename; do so.
      </para>
    </section>
    <section id="deprecation-of-ftp-apt-mirrors">

In all the pages I've reviewed so far the dominant standard is
lowercase "stretch", even when it appears in an otherwise capitalising
context such as the start of a sentence.  (It's not clear why
&Releasename; even exists.)

 @@ -50,9 +50,10 @@
      <title>FTP access to Debian hosted mirrors will be removed</title>
      <para>
        Debian hosted mirrors will stop providing FTP access.  If you
 -      have been using the ftp protocol in your sources.list, please
 -      migrate to http.  Please consider the following example for
 -      migrating:<screen>
 +      have been using the <literal>ftp:</literal> protocol in your
 +      <filename>sources.list</filename>, please migrate to
 +      <literal>http:</literal>.  Please consider the following example
 +      for migrating:<screen>
  deb http://deb.debian.org/debian          stretch         main
  deb http://deb.debian.org/debian-security stretch/updates main
  
FTP is either a capitalised initialism or a literal string; and the
string that needs to go in an APT sources-list file has a colon (we
*don't* want people to search-and-replace ftp://ftp.debian.org into
http://http.debian.org).  Ideally we'd rephrase this not to assume the
APT sources-list file is called sources.list, but that's going beyond
a stylistic change.

 @@ -91,35 +92,42 @@
        The list of obsolete packages includes:
        <itemizedlist>
          <listitem>
 -          <para>Most "-dbg" packages have been removed from the main
 -          archive.  They have been replaced by "-dbgsym" packages that
 -          are available from the "debian-debug" archive.  Please see
 +          <para>Most <quote>-dbg</quote> packages have been removed
 +	    from the main archive.  They have been replaced by
 +	    <quote>-dbgsym</quote> packages that are available from the
 +	    <quote>debian-debug</quote> archive.  Please see
            <xref linkend="debug-archive" />
            </para>

Just standardising the use of markup.  Or maybe some of them should be
<literal> instead?  Anyway, reserve ASCII-quotes for the commandline.

          </listitem>
          <listitem>
            <para>The password managers <systemitem role="package">fpm2</systemitem>
            and <systemitem role="package">kedpm</systemitem>
            are no longer maintained upstream. Please use another password
 -          manager like pass, keepassx, or keepass2. Make sure that you
 -          extract your passwords from fpm2 and kedpm before removing the packages.
 +          manager like <systemitem role="package">pass</systemitem>,
 +          <systemitem role="package">keepassx</systemitem>, or
 +          <systemitem role="package">keepass2</systemitem>.
 +          Make sure that you extract your passwords from <systemitem
 +	  role="package">fpm2</systemitem> and <systemitem
 +	  role="package">kedpm</systemitem> before removing the packages.
            </para>
          </listitem>

Consistency again.  Last time I checked docbook actually supported
<package>, but maybe that would require some sort of extra setup.

          <listitem>
            <para>
            The <systemitem role="package">net-tools</systemitem> package
 -          will be deprecated in favor of
 +          is being deprecated in favor of
            <systemitem role="package">iproute2</systemitem>.
            See <xref linkend="iproute2" /> or the
            <ulink url="https://www.debian.org/doc/manuals/debian-reference/ch05#_the_low_level_network_configuration";>
 -          Debian reference manual</ulink> for more informations.
 +          Debian reference manual</ulink> for more information.
            </para>
          </listitem>
        </itemizedlist>

"Will be deprecated" tells me nothing - I'm pretty sure
network-manager *will* one day be deprecated.  If we're already moving
away from it, it already *is* deprecated.  But I'll assume this is
just an English usage problem (like the pluralised "information") and
classify it in with the stylistic bugs.

(It would be nice if the releasenotes *also* mentioned that things
have stopped depending on ifupdown, with the result that it runs the
risk of being automatically uninstalled by aptitude - a nasty
potential upgrade glitch not related to the one that keeps disabling
my wifi.  But that's a content change, so it should go in a separate
bugreport, and maybe not for this page.)

 @@ -119,10 +123,10 @@
     </para>
   </section>
   <section id="deprecated-components">
-    <title>Deprecated components for &Releasename;</title>
+    <title>Deprecated components for &releasename;</title>
     <para>
       With the next release of &debian; &nextrelease; (codenamed
-      &Nextreleasename;) some features will be deprecated. Users
+      &nextreleasename;) some features will be deprecated. Users
       will need to migrate to other alternatives to prevent
       trouble when updating to &nextrelease;.
     </para>
 @@ -170,7 +174,7 @@
        has an issue that can cause some programs compiled as position
        independent executables to crash with a non-descriptive issue
        like <literal>segmentation fault</literal>.  This issue is
 -      solved in the linux version provided in 8.8 (version 3.16.43 or
 +      solved in the Linux version provided in 8.8 (version 3.16.43 or
        later) and in the kernel provided in Debian 9 (version 4.9 or
        later).
      </para>

On the one hand, releases get names like "stretch"; on the other,
Linux is normally capitalised (unlike the package linux-image-*), and
indeed was earlier in this paragraph.

 @@ -184,11 +192,11 @@
          If you are <emphasis>running</emphasis> an affected version of
          the kernel during the upgrade, we highly recommend that you
          perform a reboot into the stretch kernel right after the
 -        upgrade to avoid hitting this
 +        upgrade to avoid hitting this.
      </para>

Ultra-trivial punctuation fix.
  
      <section id="pie-admin-issues">
 -      <title>Behaviour changes of PIE for system administrators and developers</title>
 +      <title>Behavior changes of PIE for system administrators and developers</title>
        <note>
          <para>
            This section is mainly intended for developers or system

We're standardising (sorry, standardizing) on en-US in this document.

 @@ -203,9 +211,9 @@
        <itemizedlist>
          <listitem>
            <para>
 -            The <command>file</command> tool (among other) will
 -            classify such binaries as "shared object" rather than
 -            an "executable".  If you have filters based on binary
 +            The <command>file</command> tool (among others) will
 +            classify such binaries as <quote>shared object</quote> rather than
 +            an <quote>executable</quote>.  If you have filters based on binary
              files, these may need to be updated (e.g. spamfilters).
            </para>
          </listitem>

English usage and markup fixes.

 @@ -223,14 +231,14 @@
            <para>
              Historically, position independent executables have been
              associated with performance loss on some hardware.
 -            Notably the Debian architecture i386 (32-bit Intel
 +            Notably the Debian architecture <literal>i386</literal> (32-bit Intel
              machines).  While GCC 5 and GCC 6 have greatly <ulink

I don't know if we're consistently treating architecture names as
literal strings, but here it seems useful to help clarify the point
that it's a semi-arbitrary name rather than an accurate description.

              url="https://software.intel.com/en-us/blogs/2014/12/26/new-optimizations-for-x86-in-upcoming-gcc-50-32bit-pic-mode";>improved
              performance for position independent executables on 32-bit
 -            Intel</ulink>, this optimisation may not be applicable to
 +            Intel</ulink>, this optimization may not be applicable to
              all architectures.  Please consider evaluating the
 -            performance of your code if you are targetting machine
 -            architectures with very limited number of registers.
 +            performance of your code if you are targeting machine
 +            architectures with a very limited number of registers.
            </para>
          </listitem>
        </itemizedlist>

Language and locale fixes - in fact "targetting" is generally
considered a spelling mistake even in en-GB.

 @@ -258,16 +266,16 @@
    </section>
    <section id="i386-is-now-almost-i686" arch="i386">
      <!-- Jessie to Stretch -->
 -    <title>Minimum requirements for 32-bit Intel is now i686 (with a minor exception)</title>
 +    <title>Minimum requirement for 32-bit Intel is now i686 (with a minor exception)</title>

Requirements "are", this one requirement "is".

      <para>
        The 32-bit PC support (known as the Debian architecture
 -      "i386") now no longer covers a plain i586 processor.  The
 -      new baseline is the i686, although some i586 processors
 -      (e.g. the "AMD Geode") will remain supported.
 +      <literal>i386</literal>) now no longer covers a plain i586
 +      processor.  The new baseline is the i686, although some i586
 +      processors (e.g. the <quote>AMD Geode</quote>) will remain supported.
      </para>
      <para>
        The supported i586 processors have all the features of an i686
 -      processor <emphasis>except</emphasis> the "long NOP" (NOPL)
 +      processor <emphasis>except</emphasis> the <quote>long NOP</quote> (NOPL)
        instruction.  The following shell script may be a useful
        indicator (assuming only one processor is installed in the
        machine):

Standardising markup.

 @@ -292,7 +300,7 @@
      <!-- Jessie to Stretch -->
      <title>32-bit MIPS now requires an R2 processor</title>
      <para>
 -      The 32-bit MIPS support (both big and little endian) now requires a
 +      The 32-bit MIPS support (both big- and little-endian) now requires a
        processor supporting MIPS32 Release 2 of the MIPS instruction set.
        Notably the Loongson-2E/2F and systems based on them (including the
        Yeeloong laptop) are no longer supported.

Punctuation fix.

 @@ -325,7 +333,7 @@
    <para>
      Note that the package <systemitem
      role="package">debian-security-support</systemitem> helps to track
 -    security support status of installed packages.
 +    the security support status of installed packages.
    </para>

Article usage fix.
  
    <section id="browser-security">
 @@ -340,7 +348,7 @@
        Additionally, library interdependencies make it impossible to
        update to newer upstream releases. Therefore, browsers built
        upon the webkit, qtwebkit and khtml engines are included in
 -      &Releasename;, but not covered by security support.  These
 +      &releasename;, but not covered by security support.  These
        browsers should not be used against untrusted websites.
      </para>
      <para>

The upstream "brand names" for these are things like "QtWebKit", but
I'll leave those alone and just standardise the one that's used
repeatedly (here and in the rest of this section).

 @@ -376,7 +384,7 @@
      </para>
      <para>
        In addition, these packages will not receive any security
 -      updates during the lifetime of the &Releasename; release.
 +      updates during the lifetime of the &releasename; release.
      </para>
  </section>
  
 @@ -386,7 +394,7 @@
    <title>Package specific issues</title>
    <para>
      In most cases, packages should upgrade smoothly between
 -    &Oldreleasename; and &Releasename;.  There are a small number of
 +    &oldreleasename; and &releasename;.  There are a small number of
      cases where some intervention may be required, either before or
      during the upgrade; these are detailed below on a per-package
      basis.
 @@ -396,7 +404,7 @@
      <title>Older ciphers and SSH1 protocol disabled in OpenSSH by default</title>
      <para>
        The OpenSSH 7 release has disabled some older ciphers and the SSH1
 -      protocol by default.  Please be careful when upgrading machines,
 +      protocol by default.  Please be careful when upgrading machines
        where you only have SSH access.
      </para>
      <para>

Using a comma here would make it a descriptive relative clause (saying
that all machines are accessed by SSH) rather than a definitive one
(saying that this applies only to machines *such that* you're
accessing them by SSH).  In theory this is a substantive change to the
text, but at worst it's only telling people to be careful...

 @@ -414,17 +422,18 @@
        may affect your system.
      </para>
      <section id="apt-unpriv-acquire">
 -      <title>APT now fetches files with an unprivileged user ("_apt")</title>
 +      <title>APT now fetches files as an unprivileged user
        (<quote>_apt</quote>)</title>
        <para>

This sounded as if it was talking about "files with an unprivileged
user"; instead make it clear that it's talking about doing the
fetching as that user.

(Or should user/groupnames be in <literal>s or something?  At any
rate, not ASCII quotes.)

          APT will now attempt to discard all root privileges before
          fetching files from mirrors.  APT can detect some common cases
 -        where this will fail and fallback to fetching things as root
 +        where this will fail and fall back to fetching things as root

The general rule for stuff like this is: one word as a noun, two words
as a verb.  Compare "setup" in the next line, which would be "set up"
as a verb.

          with a warning.  However, it may fail to detect some exotic
 -        setups (e.g. uid-specific firewall rules).
 +        setups (e.g. UID-specific firewall rules).
        </para>

And this one *isn't* defined in the glossary.  Come to that, nor is
APT.

        <para>
          If you experience issues with this feature, please change to
 -        the "_apt" user and check that it:
 +        the <quote>_apt</quote> user and check that it:
        </para>
        <itemizedlist>
          <listitem>
 @@ -446,8 +455,8 @@
              can resolve DNS names and download files.  Example methods for testing:
              <screen>
  # From the dnsutils package (if using tor, please check with tor-resolve instead).
 -$ nslookup debian.org >/dev/null || echo "Cannot resolve debian.org"
 -$ wget -q https://debian.org/ -O- > /dev/null || echo "Cannot download index page of debian.org"
 +$ nslookup debian.org &gt;/dev/null || echo "Cannot resolve debian.org"
 +$ wget -q https://debian.org/ -O- &gt; /dev/null || echo "Cannot download index page of debian.org"
  </screen>
              For DNS issues, please check that
              <filename>/etc/resolv.conf</filename> is readable.

Avoid risky symbols in XML-based markup.

 @@ -462,15 +471,15 @@
          description in the manual page.
        </para>
        <para>
 -        The old engine assigned one pin priority per package,
 +        The old engine assigned one pin priority per package;
          the new one assigns pin priorities per version. It then picks
          the version with the highest pin that is not a downgrade or that has
 -        a pin > 1000.
 +        a pin &gt; 1000.
        </para>
        <para>
          This changes the effect of some pins, especially negative ones.
          Previously, pinning a version to -1 effectively prevented the
 -        package from being installed (the package pin was -1),
 +        package from being installed (the package pin was -1);
          it now only prevents the version of this package from being
          installed.
        </para>

Two underpunctuated "run-on" sentences; one risky symbol.

 @@ -485,7 +494,7 @@
          </para>
        </note>
        <para>
 -        To improve the download stability and ensure security of the
 +        To improve download stability and ensure security of the
          downloaded content, APT now requires the following from an
          APT repository:
        </para>

Article usage

 @@ -496,7 +505,7 @@
          <listitem>
            <para>
              All metadata must include at least SHA256 checksums of all
 -            items.  This includes the gpg signature of the InRelease
 +            items.  This includes the GPG signature of the InRelease
              file.
            </para>
          </listitem>

To match the glossary.

 @@ -503,7 +512,7 @@
          <listitem>
            <para>
              Signatures on the InRelease file should be done with a key
 -            at the size of 2048 bit or larger.
 +            size of 2048 bits or larger.
            </para>
          </listitem>
        </itemizedlist>

Idiomatic English.

 @@ -523,9 +532,10 @@
      <note>
        <para>
          This change only applies if your X Display Manager supports
 -        running X as rootless (or if you start X manually via
 +        running X without root privileges (or if you start X manually via
          <command>startx</command>).  Currently the only known display
 -        manager supporting this is gdm.  Other display managers simply
 +        manager supporting this is <systemitem role="package">gdm</systemitem>.
 +        Other display managers simply
          start X as root regardless of this change.
        </para>
      </note>

"Rootless" isn't a common way of expressing this even in technical
jargon, and the word has a distracting non-technical sense (which even
seems as if it would make sense here: it would mean "without a root
window").

This way of phrasing it makes it really difficult to work out that
using startx *does* require the installation of xserver-xorg-legacy.

 @@ -556,23 +566,25 @@
        <filename>~/.local/share/xorg/</filename>.
      </para>
      <para>
 -      If these requirements are not possible, please install the
 +      If these requirements cannot be met, please install the
        <systemitem role="package">xserver-xorg-legacy</systemitem>
        package to reinstate the setuid Xorg.
      </para>
    </section>

Material that should maybe go in a separate bugreport:

It seems to me that this convoluted phrasing is going to trick a lot
of users into getting unusable systems.  If I have understood
correctly, it would help enormously if it just gave a couple of
examples -

        If these requirements cannot be met (for instance, if you're
	using <command>startx</command> or an old graphics card),

And then there's the libinput issue, which turns out to be completely
separate and needs its own entry in this list.

    <section id="upstart-removed">
      <title>Upstart removed</title>
      <para>Due to the lack of upstream maintainers,
 -      the Upstart init system has been removed from &Releasename;.
 +      the Upstart init system has been removed from stretch.
        If your system relies on this package, you should note that it will not be updated
 -      during the lifetime of &debian; &release;, 
 -      and starting from &debian; &nextrelease; (&Nextreleasename;),
 -      upstart jobs could be removed from packages.
 +      during the lifetime of Debian 9, and starting from Debian 10 (buster),
 +      Upstart jobs may be removed from packages.
      </para>

A classic case where it's only true of one particular release, and
obfuscating that will only make life harder when we're preparing the
release-notes for buster.

      <para>
 -      Please consider switching to a supported init system, like systemd or openrc.
 +      Please consider switching to a supported init system, like systemd or OpenRC.
      </para>
    </section>

Upstream standard brandnames.
  
 @@ -580,10 +592,10 @@
    <!--Jessie to Stretch-->
      <title>HP mv2120</title>
      <para>
 -      The default u-boot settings from HP no longer work with &debian; &Releasename;.
 -      Before you can upgrade to &debian; &release;, you have to change some settings
 -      in the u-boot configuration. 
 -      The new settings are compatible with &debian; &oldrelease; and &debian; &release;, so it's
 +      The default u-boot settings from HP no longer work with Debian stretch.
 +      Before you can upgrade to Debian 9, you will have to change some settings
 +      in the u-boot configuration.
 +      The new settings are compatible with Debian 8 and 9, so it's
        recommended to make the changes before the upgrade.
        If you have serial console access to the mv2120, you can run some
        commands in u-boot. Simply interrupt the boot process by pressing a
 @@ -611,7 +623,7 @@
        and uses <command>fw_setenv</command> to update two boot variables.
      </para>
      <para>
 -      Please note that &debian; &release; will be the last release to support the HP mv2120.
 +      Please note that Debian 9 will be the last release to support the HP mv2120.
      </para>
    </section>
    <!--end of HP mv2120-->

If it's only true of stretch, say "stretch".

 @@ -618,7 +630,7 @@
    
  
    <section id="debhelper">
 -    <title>The debhelper tool now generates dbgsym packages by default</title>
 +    <title>The debhelper tool now generates <quote>dbgsym</quote> packages by default</title>
      <note>
        <para>
          This section is mainly intended for developers or organizations

Consistency with the following.

 @@ -626,7 +638,7 @@
        </para>
      </note>
      <para>
 -      The debhelper tool suite will now generate "dbgsym" packages by
 +      The debhelper tool suite will now generate <quote>dbgsym</quote> packages by
        default for ELF binaries.  If you develop and package binaries,
        please check that your tooling supports these extra
        auto-generated packages.

(Couldn't we have put this next to the item about -dbg packages?  Or
merged the two?)

 @@ -633,7 +645,8 @@
      </para>
      <para>
        If you use <systemitem role="package">reprepro</systemitem>, you
 -      want to upgrade it to at least version 4.17.0.  For aptly, you
 +      want to upgrade it to at least version 4.17.0.  For <systemitem
 +      role="package">aptly</systemitem>, you
        will need at least version 1.0.0, which is unfortunately not
        available in Debian stretch.
      </para>

Why mark one as a package and not the other?

 @@ -640,7 +653,7 @@
      <para>
        Should your tooling be unable to cope with these gracefully, you
        can ask debhelper to disable this feature by adding
 -      "noautodbgsym" in the DEB_BUILD_OPTIONS variable of your build
 +      <quote><literal>noautodbgsym</literal></quote> in the DEB_BUILD_OPTIONS variable of your build
        service.  Please see <ulink
        url="https://manpages.debian.org/stretch/debhelper/dh_strip.1.en.html";>the
        dh_strip manpage for more information</ulink>

Standardising markup.

 @@ -664,22 +677,22 @@
        The <command>openssl enc</command> command changed the default digest
        (used to create the key from passphrase) from MD5 to SHA256. The digest can
        be specified with the <command>-md</command> option in case old files need
 -      to be decrypted with newer openssl (or the other way around).
 +      to be decrypted with newer OpenSSL (or the other way around).
      </para>
      <para>
        The 3DES and RC4 ciphers are no longer available for TLS/SSL communication.
 -      Servers linked against openssl can't offer them and clients can't connect
 -      to servers which offer only those. This means that openssl and Windows XP
 +      Servers linked against OpenSSL can't offer them and clients can't connect
 +      to servers which offer only those. This means that OpenSSL and Windows XP
        share no common cipher.
      </para>
      <para>
        The package <systemitem role="package">libssl-dev</systemitem> provides
 -      header files to compile against openssl 1.1.0. The API changed a lot and
 +      header files to compile against OpenSSL 1.1.0. The API changed a lot and
        it is possible that the software won't compile anymore. There is an
        <ulink url="https://wiki.openssl.org/index.php/1.1_API_Changes";>overview of
        the changes</ulink>. If you can't update your software, there is also
        <systemitem role="package">libssl1.0-dev</systemitem> which provides headers
 -      against openssl 1.0.2.
 +      against OpenSSL 1.0.2.
      </para>
    </section>

It starts out drawing a distinction between literal command string and
upstream brandname but then stops.  The alternative would be to mark
it as a package.
  
 @@ -687,8 +700,8 @@
      <title>Perl changes that may break third-party software</title>
      <note>
        <para>
 -        This section applies to code maintained outside &debian; &release; -
 -        local, third-party or legacy Perl scripts and modules.
 +        This section applies to code maintained outside Debian -
 +        local, third-party, or legacy Perl scripts and modules.
        </para>
      </note>

Why does this even need to specify a release?  "Maintained outside
Debian 9" would includes software in sid.

      <itemizedlist>
 @@ -704,17 +717,17 @@
        </listitem>
        <listitem>
          <para>
 -          The current working directory (<literal>.</literal>) has been removed
 +          The current working directory (<filename>.</filename>) has been removed
            from the default list of include directories,
            <literal>@INC</literal>. This may affect usage of
 -          <literal>require()</literal>, <literal>do()</literal> etc., where the
 +          <literal>require()</literal>, <literal>do()</literal>, etc., where the
            arguments are files in the current directory.
          </para>
        </listitem>

A pedantic use of markup and a pedantic Harvard comma.

        <listitem>
          <para>
 -          The full list of changes in Perl since the version in &debian;
 -          &oldrelease; is available in <ulink
 +          The full list of changes in Perl since the version in Debian 8
 +          is available in <ulink
              url="https://metacpan.org/pod/release/RJBS/perl-5.22.0/pod/perldelta.pod";>perl522delta</ulink>
            and <ulink
              url="https://metacpan.org/pod/release/RJBS/perl-5.24.0/pod/perldelta.pod";>perl524delta</ulink>.

Saying "&debian; &oldrelease;" is pointless, since for any other
release or distro these are likely to be the wrong URLs.

 @@ -730,7 +743,7 @@
        incompatible with the Perl version in stretch. The
        <systemitem role="package">postgresql-plperl-9.4</systemitem> package
        will be removed during the update, rendering server-side Perl procedures
 -      dysfunctional. Upgrading to PostgreSQL 9.6 should be unaffected, the
 +      dysfunctional. Upgrading to PostgreSQL 9.6 should be unaffected; the
        procedures will work in the new PostgreSQL cluster if the
        <systemitem role="package">postgresql-plperl-9.6</systemitem> package
        is installed. If unsure, take a backup of your PostgreSQL 9.4 clusters

Run-on sentence.

 @@ -739,11 +752,13 @@
    </section>
  
    <section id="iproute2">
 -  <title>net-tools will be deprecated in favor of iproute2</title>
 +  <title><systemitem role="package">net-tools</systemitem> will be
 +  deprecated in favor of <systemitem
 +  role="package">iproute2</systemitem></title>

Markup standardisation.  Fingers crossed we can someday use <package>.

      <para>
        The <systemitem role="package">net-tools</systemitem> package
        is no longer part of new installations by default,
 -      since it's priority has been lowered from important to optional.
 +      since its priority has been lowered from important to optional.
        Users are instead advised to use the modern
        <systemitem role="package">iproute2</systemitem> toolset
        (which has been part of new installs for several releases already).
 
Plain spelling error.

It would be nice if this item was accompanied by one about ifupdown
having lost the dependencies that used to hold it installed, but
that's not a matter for a stylistic-only patch.
-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package

Index: issues.dbk
===================================================================
--- issues.dbk	(revision 11526)
+++ issues.dbk	(working copy)
@@ -12,15 +12,15 @@
 Sometimes, changes introduced in a new release have side-effects
 we cannot reasonably avoid, or they expose
 bugs somewhere else. This section documents issues we are aware of.  Please also
-read the errata, the relevant packages' documentation, bug reports and other
+read the errata, the relevant packages' documentation, bug reports, and other
 information mentioned in <xref linkend="morereading"/>.
 </para>
 
 <section id="upgrade-specific-issues">
-  <title>Upgrade specific items for &Releasename;</title>
+  <title>Upgrade specific items for &releasename;</title>
   <para>
     This section covers items related to the upgrade from
-    &Oldreleasename; to &Releasename;
+    &oldreleasename; to &releasename;
   </para>
   <section id="late-mounting-usr">
     <!-- jessie to stretch -->
@@ -42,7 +42,7 @@
     <para>
       This means that for &releasename; all systems where <filename>/usr</filename>
       is a separate partition need to use an initramfs generator that will mount
-      <filename>/usr</filename>. All initramfs generators in &Releasename; do so.
+      <filename>/usr</filename>. All initramfs generators in &releasename; do so.
     </para>
   </section>
   <section id="deprecation-of-ftp-apt-mirrors">
@@ -50,8 +50,8 @@
     <title>FTP access to Debian hosted mirrors will be removed</title>
     <para>
       Debian hosted mirrors will stop providing FTP access.  If you
-      have been using the ftp protocol in your sources.list, please
-      migrate to http.  Please consider the following example for
+      have been using the <literal>ftp:</literal> protocol in your sources.list, please
+      migrate to <literal>http:</literal>.  Please consider the following example for
       migrating:<screen>
 deb http://deb.debian.org/debian          stretch         main
 deb http://deb.debian.org/debian-security stretch/updates main
@@ -91,9 +91,9 @@
       The list of obsolete packages includes:
       <itemizedlist>
         <listitem>
-          <para>Most "-dbg" packages have been removed from the main
-          archive.  They have been replaced by "-dbgsym" packages that
-          are available from the "debian-debug" archive.  Please see
+          <para>Most <quote>-dbg</quote> packages have been removed from the main
+          archive.  They have been replaced by <quote>-dbgsym</quote> packages that
+          are available from the <quote>debian-debug</quote> archive.  Please see
           <xref linkend="debug-archive" />
           </para>
         </listitem>
@@ -101,18 +101,22 @@
           <para>The password managers <systemitem role="package">fpm2</systemitem>
           and <systemitem role="package">kedpm</systemitem>
           are no longer maintained upstream. Please use another password
-          manager like pass, keepassx, or keepass2. Make sure that you
-          extract your passwords from fpm2 and kedpm before removing the packages.
+          manager like <systemitem role="package">pass</systemitem>,
+          <systemitem role="package">keepassx</systemitem>, or
+          <systemitem role="package">keepass2</systemitem>. Make sure that you
+          extract your passwords from <systemitem
+          role="package">fpm2</</systemitem> and <systemitem
+          role="package">kedpm</systemitem> before removing the packages.
           </para>
         </listitem>
         <listitem>
           <para>
           The <systemitem role="package">net-tools</systemitem> package
-          will be deprecated in favor of
+          is being deprecated in favor of
           <systemitem role="package">iproute2</systemitem>.
           See <xref linkend="iproute2" /> or the
           <ulink url="https://www.debian.org/doc/manuals/debian-reference/ch05#_the_low_level_network_configuration";>
-          Debian reference manual</ulink> for more informations.
+          Debian reference manual</ulink> for more information.
           </para>
         </listitem>
       </itemizedlist>
@@ -119,10 +123,10 @@
     </para>
   </section>
   <section id="deprecated-components">
-    <title>Deprecated components for &Releasename;</title>
+    <title>Deprecated components for &releasename;</title>
     <para>
       With the next release of &debian; &nextrelease; (codenamed
-      &Nextreleasename;) some features will be deprecated. Users
+      &nextreleasename;) some features will be deprecated. Users
       will need to migrate to other alternatives to prevent
       trouble when updating to &nextrelease;.
     </para>
@@ -170,7 +174,7 @@
       has an issue that can cause some programs compiled as position
       independent executables to crash with a non-descriptive issue
       like <literal>segmentation fault</literal>.  This issue is
-      solved in the linux version provided in 8.8 (version 3.16.43 or
+      solved in the Linux version provided in 8.8 (version 3.16.43 or
       later) and in the kernel provided in Debian 9 (version 4.9 or
       later).
     </para>
@@ -184,11 +188,11 @@
         If you are <emphasis>running</emphasis> an affected version of
         the kernel during the upgrade, we highly recommend that you
         perform a reboot into the stretch kernel right after the
-        upgrade to avoid hitting this
+        upgrade to avoid hitting this.
     </para>
 
     <section id="pie-admin-issues">
-      <title>Behaviour changes of PIE for system administrators and developers</title>
+      <title>Behavior changes of PIE for system administrators and developers</title>
       <note>
         <para>
           This section is mainly intended for developers or system
@@ -203,9 +207,9 @@
       <itemizedlist>
         <listitem>
           <para>
-            The <command>file</command> tool (among other) will
-            classify such binaries as "shared object" rather than
-            an "executable".  If you have filters based on binary
+            The <command>file</command> tool (among others) will
+            classify such binaries as <quote>shared object</quote> rather than
+            an <quote>executable</quote>.  If you have filters based on binary
             files, these may need to be updated (e.g. spamfilters).
           </para>
         </listitem>
@@ -223,14 +227,14 @@
           <para>
             Historically, position independent executables have been
             associated with performance loss on some hardware.
-            Notably the Debian architecture i386 (32-bit Intel
+            Notably the Debian architecture <literal>i386</literal> (32-bit Intel
             machines).  While GCC 5 and GCC 6 have greatly <ulink
             url="https://software.intel.com/en-us/blogs/2014/12/26/new-optimizations-for-x86-in-upcoming-gcc-50-32bit-pic-mode";>improved
             performance for position independent executables on 32-bit
-            Intel</ulink>, this optimisation may not be applicable to
+            Intel</ulink>, this optimization may not be applicable to
             all architectures.  Please consider evaluating the
-            performance of your code if you are targetting machine
-            architectures with very limited number of registers.
+            performance of your code if you are targeting machine
+            architectures with a very limited number of registers.
           </para>
         </listitem>
       </itemizedlist>
@@ -258,16 +262,16 @@
   </section>
   <section id="i386-is-now-almost-i686" arch="i386">
     <!-- Jessie to Stretch -->
-    <title>Minimum requirements for 32-bit Intel is now i686 (with a minor exception)</title>
+    <title>Minimum requirement for 32-bit Intel is now i686 (with a minor exception)</title>
     <para>
       The 32-bit PC support (known as the Debian architecture
-      "i386") now no longer covers a plain i586 processor.  The
+      <literal>i386</literal>) now no longer covers a plain i586 processor.  The
       new baseline is the i686, although some i586 processors
-      (e.g. the "AMD Geode") will remain supported.
+      (e.g. the <quote>AMD Geode</quote>) will remain supported.
     </para>
     <para>
       The supported i586 processors have all the features of an i686
-      processor <emphasis>except</emphasis> the "long NOP" (NOPL)
+      processor <emphasis>except</emphasis> the <quote>long NOP</quote> (NOPL)
       instruction.  The following shell script may be a useful
       indicator (assuming only one processor is installed in the
       machine):
@@ -292,7 +296,7 @@
     <!-- Jessie to Stretch -->
     <title>32-bit MIPS now requires an R2 processor</title>
     <para>
-      The 32-bit MIPS support (both big and little endian) now requires a
+      The 32-bit MIPS support (both big- and little- endian) now requires a
       processor supporting MIPS32 Release 2 of the MIPS instruction set.
       Notably the Loongson-2E/2F and systems based on them (including the
       Yeeloong laptop) are no longer supported.
@@ -325,7 +329,7 @@
   <para>
     Note that the package <systemitem
     role="package">debian-security-support</systemitem> helps to track
-    security support status of installed packages.
+    the security support status of installed packages.
   </para>
 
   <section id="browser-security">
@@ -340,7 +344,7 @@
       Additionally, library interdependencies make it impossible to
       update to newer upstream releases. Therefore, browsers built
       upon the webkit, qtwebkit and khtml engines are included in
-      &Releasename;, but not covered by security support.  These
+      &releasename;, but not covered by security support.  These
       browsers should not be used against untrusted websites.
     </para>
     <para>
@@ -376,7 +380,7 @@
     </para>
     <para>
       In addition, these packages will not receive any security
-      updates during the lifetime of the &Releasename; release.
+      updates during the lifetime of the &releasename; release.
     </para>
 </section>
 
@@ -386,7 +390,7 @@
   <title>Package specific issues</title>
   <para>
     In most cases, packages should upgrade smoothly between
-    &Oldreleasename; and &Releasename;.  There are a small number of
+    &oldreleasename; and &releasename;.  There are a small number of
     cases where some intervention may be required, either before or
     during the upgrade; these are detailed below on a per-package
     basis.
@@ -396,7 +400,7 @@
     <title>Older ciphers and SSH1 protocol disabled in OpenSSH by default</title>
     <para>
       The OpenSSH 7 release has disabled some older ciphers and the SSH1
-      protocol by default.  Please be careful when upgrading machines,
+      protocol by default.  Please be careful when upgrading machines
       where you only have SSH access.
     </para>
     <para>
@@ -414,17 +418,18 @@
       may affect your system.
     </para>
     <section id="apt-unpriv-acquire">
-      <title>APT now fetches files with an unprivileged user ("_apt")</title>
+      <title>APT now fetches files as an unprivileged user
+      (<quote>_apt</quote>)</title>
       <para>
         APT will now attempt to discard all root privileges before
         fetching files from mirrors.  APT can detect some common cases
-        where this will fail and fallback to fetching things as root
+        where this will fail and fall back to fetching things as root
         with a warning.  However, it may fail to detect some exotic
-        setups (e.g. uid-specific firewall rules).
+        setups (e.g. UID-specific firewall rules).
       </para>
       <para>
         If you experience issues with this feature, please change to
-        the "_apt" user and check that it:
+        the <quote>_apt</quote> user and check that it:
       </para>
       <itemizedlist>
         <listitem>
@@ -446,8 +451,8 @@
             can resolve DNS names and download files.  Example methods for testing:
             <screen>
 # From the dnsutils package (if using tor, please check with tor-resolve instead).
-$ nslookup debian.org >/dev/null || echo "Cannot resolve debian.org"
-$ wget -q https://debian.org/ -O- > /dev/null || echo "Cannot download index page of debian.org"
+$ nslookup debian.org &gt;/dev/null || echo "Cannot resolve debian.org"
+$ wget -q https://debian.org/ -O- &gt; /dev/null || echo "Cannot download index page of debian.org"
 </screen>
             For DNS issues, please check that
             <filename>/etc/resolv.conf</filename> is readable.
@@ -462,15 +467,15 @@
         description in the manual page.
       </para>
       <para>
-        The old engine assigned one pin priority per package,
+        The old engine assigned one pin priority per package;
         the new one assigns pin priorities per version. It then picks
         the version with the highest pin that is not a downgrade or that has
-        a pin > 1000.
+        a pin &gt; 1000.
       </para>
       <para>
         This changes the effect of some pins, especially negative ones.
         Previously, pinning a version to -1 effectively prevented the
-        package from being installed (the package pin was -1),
+        package from being installed (the package pin was -1);
         it now only prevents the version of this package from being
         installed.
       </para>
@@ -485,7 +490,7 @@
         </para>
       </note>
       <para>
-        To improve the download stability and ensure security of the
+        To improve download stability and ensure security of the
         downloaded content, APT now requires the following from an
         APT repository:
       </para>
@@ -496,7 +501,7 @@
         <listitem>
           <para>
             All metadata must include at least SHA256 checksums of all
-            items.  This includes the gpg signature of the InRelease
+            items.  This includes the GPG signature of the InRelease
             file.
           </para>
         </listitem>
@@ -503,7 +508,7 @@
         <listitem>
           <para>
             Signatures on the InRelease file should be done with a key
-            at the size of 2048 bit or larger.
+            size of 2048 bits or larger.
           </para>
         </listitem>
       </itemizedlist>
@@ -523,9 +528,10 @@
     <note>
       <para>
         This change only applies if your X Display Manager supports
-        running X as rootless (or if you start X manually via
+        running X without root privileges (or if you start X manually via
         <command>startx</command>).  Currently the only known display
-        manager supporting this is gdm.  Other display managers simply
+        manager supporting this is <systemitem role="package">gdm</systemitem>.
+        Other display managers simply
         start X as root regardless of this change.
       </para>
     </note>
@@ -556,7 +562,7 @@
       <filename>~/.local/share/xorg/</filename>.
     </para>
     <para>
-      If these requirements are not possible, please install the
+      If these requirements cannot be met, please install the
       <systemitem role="package">xserver-xorg-legacy</systemitem>
       package to reinstate the setuid Xorg.
     </para>
@@ -565,14 +571,13 @@
   <section id="upstart-removed">
     <title>Upstart removed</title>
     <para>Due to the lack of upstream maintainers,
-      the Upstart init system has been removed from &Releasename;.
+      the Upstart init system has been removed from stretch.
       If your system relies on this package, you should note that it will not be updated
-      during the lifetime of &debian; &release;, 
-      and starting from &debian; &nextrelease; (&Nextreleasename;),
-      upstart jobs could be removed from packages.
+      during the lifetime of Debian 9, and starting from Debian 10 (buster),
+      Upstart jobs may be removed from packages.
     </para>
     <para>
-      Please consider switching to a supported init system, like systemd or openrc.
+      Please consider switching to a supported init system, like systemd or OpenRC.
     </para>
   </section>
 
@@ -580,10 +585,10 @@
   <!--Jessie to Stretch-->
     <title>HP mv2120</title>
     <para>
-      The default u-boot settings from HP no longer work with &debian; &Releasename;.
-      Before you can upgrade to &debian; &release;, you have to change some settings
+      The default u-boot settings from HP no longer work with Debian stretch.
+      Before you can upgrade to Debian 9, you have to change some settings
       in the u-boot configuration. 
-      The new settings are compatible with &debian; &oldrelease; and &debian; &release;, so it's
+      The new settings are compatible with Debian 7 and Debian 8, so it's
       recommended to make the changes before the upgrade.
       If you have serial console access to the mv2120, you can run some
       commands in u-boot. Simply interrupt the boot process by pressing a
@@ -611,7 +616,7 @@
       and uses <command>fw_setenv</command> to update two boot variables.
     </para>
     <para>
-      Please note that &debian; &release; will be the last release to support the HP mv2120.
+      Please note that Debian 9 will be the last release to support the HP mv2120.
     </para>
   </section>
   <!--end of HP mv2120-->
@@ -618,7 +623,7 @@
   
 
   <section id="debhelper">
-    <title>The debhelper tool now generates dbgsym packages by default</title>
+    <title>The debhelper tool now generates <quote>dbgsym</quote> packages by default</title>
     <note>
       <para>
         This section is mainly intended for developers or organizations
@@ -626,7 +631,7 @@
       </para>
     </note>
     <para>
-      The debhelper tool suite will now generate "dbgsym" packages by
+      The debhelper tool suite will now generate <quote>dbgsym</quote> packages by
       default for ELF binaries.  If you develop and package binaries,
       please check that your tooling supports these extra
       auto-generated packages.
@@ -633,7 +638,8 @@
     </para>
     <para>
       If you use <systemitem role="package">reprepro</systemitem>, you
-      want to upgrade it to at least version 4.17.0.  For aptly, you
+      want to upgrade it to at least version 4.17.0.  For <systemitem
+      role="package">aptly</systemitem>, you
       will need at least version 1.0.0, which is unfortunately not
       available in Debian stretch.
     </para>
@@ -640,7 +646,7 @@
     <para>
       Should your tooling be unable to cope with these gracefully, you
       can ask debhelper to disable this feature by adding
-      "noautodbgsym" in the DEB_BUILD_OPTIONS variable of your build
+      <quote><literal>noautodbgsym</literal></quote> in the DEB_BUILD_OPTIONS variable of your build
       service.  Please see <ulink
       url="https://manpages.debian.org/stretch/debhelper/dh_strip.1.en.html";>the
       dh_strip manpage for more information</ulink>
@@ -664,22 +670,22 @@
       The <command>openssl enc</command> command changed the default digest
       (used to create the key from passphrase) from MD5 to SHA256. The digest can
       be specified with the <command>-md</command> option in case old files need
-      to be decrypted with newer openssl (or the other way around).
+      to be decrypted with newer OpenSSL (or the other way around).
     </para>
     <para>
       The 3DES and RC4 ciphers are no longer available for TLS/SSL communication.
-      Servers linked against openssl can't offer them and clients can't connect
-      to servers which offer only those. This means that openssl and Windows XP
+      Servers linked against OpenSSL can't offer them and clients can't connect
+      to servers which offer only those. This means that OpenSSL and Windows XP
       share no common cipher.
     </para>
     <para>
       The package <systemitem role="package">libssl-dev</systemitem> provides
-      header files to compile against openssl 1.1.0. The API changed a lot and
+      header files to compile against OpenSSL 1.1.0. The API changed a lot and
       it is possible that the software won't compile anymore. There is an
       <ulink url="https://wiki.openssl.org/index.php/1.1_API_Changes";>overview of
       the changes</ulink>. If you can't update your software, there is also
       <systemitem role="package">libssl1.0-dev</systemitem> which provides headers
-      against openssl 1.0.2.
+      against OpenSSL 1.0.2.
     </para>
   </section>
 
@@ -687,8 +693,8 @@
     <title>Perl changes that may break third-party software</title>
     <note>
       <para>
-        This section applies to code maintained outside &debian; &release; -
-        local, third-party or legacy Perl scripts and modules.
+        This section applies to code maintained outside Debian -
+        local, third-party, or legacy Perl scripts and modules.
       </para>
     </note>
     <itemizedlist>
@@ -704,17 +710,17 @@
       </listitem>
       <listitem>
         <para>
-          The current working directory (<literal>.</literal>) has been removed
+          The current working directory (<filename>.</filename>) has been removed
           from the default list of include directories,
           <literal>@INC</literal>. This may affect usage of
-          <literal>require()</literal>, <literal>do()</literal> etc., where the
+          <literal>require()</literal>, <literal>do()</literal>, etc., where the
           arguments are files in the current directory.
         </para>
       </listitem>
       <listitem>
         <para>
-          The full list of changes in Perl since the version in &debian;
-          &oldrelease; is available in <ulink
+          The full list of changes in Perl since the version in Debian
+          8 is available in <ulink
             url="https://metacpan.org/pod/release/RJBS/perl-5.22.0/pod/perldelta.pod";>perl522delta</ulink>
           and <ulink
             url="https://metacpan.org/pod/release/RJBS/perl-5.24.0/pod/perldelta.pod";>perl524delta</ulink>.
@@ -730,7 +736,7 @@
       incompatible with the Perl version in stretch. The
       <systemitem role="package">postgresql-plperl-9.4</systemitem> package
       will be removed during the update, rendering server-side Perl procedures
-      dysfunctional. Upgrading to PostgreSQL 9.6 should be unaffected, the
+      dysfunctional. Upgrading to PostgreSQL 9.6 should be unaffected; the
       procedures will work in the new PostgreSQL cluster if the
       <systemitem role="package">postgresql-plperl-9.6</systemitem> package
       is installed. If unsure, take a backup of your PostgreSQL 9.4 clusters
@@ -739,11 +745,13 @@
   </section>
 
   <section id="iproute2">
-  <title>net-tools will be deprecated in favor of iproute2</title>
+  <title><systemitem role="package">net-tools</systemitem> will be
+  deprecated in favor of <systemitem
+  role="package">iproute2</systemitem></title>
     <para>
       The <systemitem role="package">net-tools</systemitem> package
       is no longer part of new installations by default,
-      since it's priority has been lowered from important to optional.
+      since its priority has been lowered from important to optional.
       Users are instead advised to use the modern
       <systemitem role="package">iproute2</systemitem> toolset
       (which has been part of new installs for several releases already).

--- End Message ---
--- Begin Message --- 
Scanning through this bug, this is all about the stretch release-notes,
and the changes have been applied at that time if relevant.

Closing.

Paul

Attachment: signature.asc
Description: OpenPGP digital signature


--- End Message ---
Reply to: