Bug#864166: release-notes: proofreading sweep - issues.dbk

[Justin B Rye]

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.

[Niels Thykier]

Control: tags -1 pending

Post by Justin B Rye
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.

Thanks. I have applied almost all of it (except for one case of "&foo;"
-> "Text", where there were no content/typographical cases as far as I
could tell - I didn't want unnecessary fuzzy texts for the translators).

Post by Justin B Rye
[...]
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.)

Ack, we should probably remove &Releasename; (et al). Though that will
be a post stretch thing.

Post by Justin B Rye
[...]
@@ -91,35 +92,42 @@
<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.

I think <literal> is more accurate. I have used that.

Post by Justin B Rye
[...]
Consistency again. Last time I checked docbook actually supported
<package>, but maybe that would require some sort of extra setup.

If I use <package>, it does compile... but the content is no longer
boldface, so something needs to change at least. But agreed, <package>
would be so much better.

Post by Justin B Rye
[...]
(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.)

I have added a warning in the section about net-tools being deprecated
and how to use iproute2.

Post by Justin B Rye
[...]
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.)

I went with <literal>.

Post by Justin B Rye
[...]
@@ -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.

Sadly, then I have confused you. Assuming the system meets the
requirements, then the following will *not* require root:

* startx (from a virtual terminal "owned" by the current user)
* gdm (which knows how to start X without using root)

Post by Justin B Rye
@@ -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>
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),

An example would be good. I will try to add one. :)

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

I have done a draft of that and committed it now.

Post by Justin B Rye
[...]
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".

I agree, but I excluded this one to avoid unnecessary fuzzy translations.

Post by Justin B Rye
@@ -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.

Ack, used <literal> per above.

Post by Justin B Rye
@@ -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?)

The one in 5.1.3 about "Notewprthy obsolete packages"? If anything, it
would be a link from 5.1.3 to this section. But to be honest, I think
they have a different audience.

5.1.3 - if you have dbg packages, you now need to fetch dbgsym instead
from a separate archive.

5.3.5 - if you built deb packages with debhelper, dbgsym packages
magically appear. You need to deal with that.

I see 5.1.3 as a sysadmin (+ developer) section, whereas 5.3.5 is mostly
a developer thing.

Post by Justin B Rye
[...]
[... net-tools is deprecated section ...]
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.

Indeed. I have added a warning for that.

Thanks,
~Niels

[Justin B Rye]

Post by Niels Thykier

Post by Justin B Rye
<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.

Sadly, then I have confused you. Assuming the system meets the
* startx (from a virtual terminal "owned" by the current user)
* gdm (which knows how to start X without using root)

I was assuming otherwise because the first symptom I ran into was that
running startx in the absence of xserver-xorg-legacy gave me an X
session with non-functional mouse and keyboard.

But when I check now, installing every available xserver-xorg-*
package in main including -legacy as well as -input-libinput makes no
difference to that. On a testbed stretch machine with functional
logind and so on but with an old KMS-incapable graphics card, I
haven't found any way of making startx usable.

Switching over to lightdm I can get a usable session without -legacy
as long as I have -input-libinput. So I'm afraid I have no idea
what's going on, or even how many problems there are.

[Niels Thykier]

Hi,

CC'ing debian-x, who I hope can help us with some clarification.

Post by Justin B Rye

Post by Niels Thykier

Post by Justin B Rye
<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>
[...]
This way of phrasing it makes it really difficult to work out that
using startx *does* require the installation of xserver-xorg-legacy.

Sadly, then I have confused you. Assuming the system meets the
* startx (from a virtual terminal "owned" by the current user)
* gdm (which knows how to start X without using root)

I was assuming otherwise because the first symptom I ran into was that
running startx in the absence of xserver-xorg-legacy gave me an X
session with non-functional mouse and keyboard.
But when I check now, installing every available xserver-xorg-*
package in main including -legacy as well as -input-libinput makes no
difference to that. On a testbed stretch machine with functional
logind and so on but with an old KMS-incapable graphics card, I
haven't found any way of making startx usable.

Not sure what is going there. But I haven't used startx for years until
I learned of this feature, so I am probably not the right person to ask
what is going on/why it doesn't work.

Post by Justin B Rye
Switching over to lightdm I can get a usable session without -legacy
as long as I have -input-libinput. So I'm afraid I have no idea
what's going on, or even how many problems there are.

As I understand it, lightdm will start X as root unconditionally, so
that will work with or without -legacy. You want -legacy when using gdm
(or startx) plus have "old drivers".

* @debian-x: Is the above correct?


Thanks,
~Niels

[Julien Cristau]

Post by Niels Thykier
Hi,
CC'ing debian-x, who I hope can help us with some clarification.

Post by Justin B Rye

Post by Niels Thykier

Post by Justin B Rye
<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>

This looks wrong, I believe the package name is gdm3, not gdm.

Post by Niels Thykier

Post by Justin B Rye

Post by Niels Thykier

Post by Justin B Rye
[...]
This way of phrasing it makes it really difficult to work out that
using startx *does* require the installation of xserver-xorg-legacy.

Sadly, then I have confused you. Assuming the system meets the
* startx (from a virtual terminal "owned" by the current user)
* gdm (which knows how to start X without using root)

I was assuming otherwise because the first symptom I ran into was that
running startx in the absence of xserver-xorg-legacy gave me an X
session with non-functional mouse and keyboard.
But when I check now, installing every available xserver-xorg-*
package in main including -legacy as well as -input-libinput makes no
difference to that. On a testbed stretch machine with functional
logind and so on but with an old KMS-incapable graphics card, I
haven't found any way of making startx usable.

Not sure what is going there. But I haven't used startx for years until
I learned of this feature, so I am probably not the right person to ask
what is going on/why it doesn't work.

Post by Justin B Rye
Switching over to lightdm I can get a usable session without -legacy
as long as I have -input-libinput. So I'm afraid I have no idea
what's going on, or even how many problems there are.

As I understand it, lightdm will start X as root unconditionally, so
that will work with or without -legacy. You want -legacy when using gdm
(or startx) plus have "old drivers".

Yes, any reasonable (read: KMS) setup will work fine without -legacy.
In the absence of KMS (e.g. virtualbox, or new hardware not supported by
the drivers we ship), you'll need either -legacy or a DM that hasn't
been updated to starting X as non-root yet.

Cheers,
Julien

[Julien Cristau]

Post by Julien Cristau

Post by Niels Thykier
Hi,
CC'ing debian-x, who I hope can help us with some clarification.
[...]

This looks wrong, I believe the package name is gdm3, not gdm.

Thanks, corrected.

Post by Julien Cristau
[...]

Post by Niels Thykier

Post by Justin B Rye
Switching over to lightdm I can get a usable session without -legacy
as long as I have -input-libinput. So I'm afraid I have no idea
what's going on, or even how many problems there are.

As I understand it, lightdm will start X as root unconditionally, so
that will work with or without -legacy. You want -legacy when using gdm
(or startx) plus have "old drivers".

Yes, any reasonable (read: KMS) setup will work fine without -legacy.
In the absence of KMS (e.g. virtualbox, or new hardware not supported by
the drivers we ship), you'll need either -legacy or a DM that hasn't
been updated to starting X as non-root yet.
Cheers,
Julien

Thanks for confirming.
https://wiki.debian.org/NewInStretch
"""
Upgrade issues
* For many Intel graphics chipsets, the Stretch X server will use the
modeset driver instead of the intel driver. The modeset driver may
require non-free firmware (firmware-misc-nonfree) to activate
features, even on systems which did not use this firmware under
Jessie.
* For some older graphics chipsets, support has been relegated to
"legacy drivers", which require the old setuid X server to run.
Install xserver-xorg-legacy if you require one of these drivers.
"""
I believe the release-notes has the latter point, but not the former. I
will add that now.

That doesn't sound correct either.

* xserver-xorg-legacy is now installed by default, so I'm not sure we
need this
* the firmware requirement has nothing to do with the switch from the
"intel" to the "modesetting" (not modeset) driver.

Cheers,
Julien

[Niels Thykier]

Post by Julien Cristau

Post by Niels Thykier
Hi,
CC'ing debian-x, who I hope can help us with some clarification.
[...]

This looks wrong, I believe the package name is gdm3, not gdm.

Thanks, corrected.

Post by Julien Cristau
[...]

Post by Niels Thykier

Post by Justin B Rye
Switching over to lightdm I can get a usable session without -legacy
as long as I have -input-libinput. So I'm afraid I have no idea
what's going on, or even how many problems there are.

As I understand it, lightdm will start X as root unconditionally, so
that will work with or without -legacy. You want -legacy when using gdm
(or startx) plus have "old drivers".

Yes, any reasonable (read: KMS) setup will work fine without -legacy.
In the absence of KMS (e.g. virtualbox, or new hardware not supported by
the drivers we ship), you'll need either -legacy or a DM that hasn't
been updated to starting X as non-root yet.
Cheers,
Julien

Thanks for confirming.

I also noticed that the wiki has some points on this:
https://wiki.debian.org/NewInStretch

"""
Upgrade issues

* For many Intel graphics chipsets, the Stretch X server will use the
modeset driver instead of the intel driver. The modeset driver may
require non-free firmware (firmware-misc-nonfree) to activate
features, even on systems which did not use this firmware under
Jessie.

* For some older graphics chipsets, support has been relegated to
"legacy drivers", which require the old setuid X server to run.
Install xserver-xorg-legacy if you require one of these drivers.
"""

I believe the release-notes has the latter point, but not the former. I
will add that now.

Thanks,
~Niels

[Baptiste Jammet]

Post by Niels Thykier

Post by Justin B Rye
(It's not clear why
&Releasename; even exists.)

Ack, we should probably remove &Releasename; (et al). Though that will
be a post stretch thing.

Just for info, french translations (and maybe others ?) use capitalized
release names.

Baptiste

[Niels Thykier]

Post by Niels Thykier

Post by Justin B Rye
(It's not clear why
&Releasename; even exists.)

Ack, we should probably remove &Releasename; (et al). Though that will
be a post stretch thing.

Just for info, french translations (and maybe others ?) use capitalized
release names.
Baptiste

Can translators re-map entities? If so, the languages, where this is
necessary, could remap &releasename; to "Stretch" instead of "stretch".
And then it would be consistently lowercase in English and consistently
title-case in French, etc.

Thanks,
~Niels

[Justin B Rye]

Post by Niels Thykier

Just for info, french translations (and maybe others ?) use capitalized
release names.

Can translators re-map entities? If so, the languages, where this is
necessary, could remap &releasename; to "Stretch" instead of "stretch".
And then it would be consistently lowercase in English and consistently
title-case in French, etc.

No, be careful: in some places &releasename; means the literal string
used in APT sources-list files.

The real question is why French gets to use capitalised releasenames
if English doesn't - after all, if the idea is that "stretch" is a
product-name then it should be universally lowercase even in German
(cf. "iPad").

My preferred solution would be to switch over to calling it
"Stretch" even in English, but probably not a week before release.

[Baptiste Jammet]

Hi,

Post by Justin B Rye
The real question is why French gets to use capitalised releasenames
if English doesn't

I think the idea was that release names are proper nouns (from the
toys). And grammatical rules are not the same.

Post by Justin B Rye
- after all, if the idea is that "stretch" is a
product-name then it should be universally lowercase even in German
(cf. "iPad").

I will discuss it on l10n-french.

Post by Justin B Rye

Post by Niels Thykier
Can translators re-map entities?

But we can define our own (in XX/language.ent) if necessary.

Finally, I was only saying that we could keep the &Releasename; entity,
even if it's not used in english. This appears in po files,
and we can translate &releasename; to &Releasename;.

Baptiste

[Holger Wansing]

Hi,

Post by Baptiste Jammet
Finally, I was only saying that we could keep the &Releasename; entity,
even if it's not used in english. This appears in po files,
and we can translate &releasename; to &Releasename;.

And that's exactly how we do it for German.

Holger

--
Sent from my Jolla phone

[Justin B Rye]

Post by Niels Thykier

Post by Justin B Rye
(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.)

I have added a warning in the section about net-tools being deprecated
and how to use iproute2.

A warning about ifupdown? I don't see anything in the version in SVN.
I would suggest adding an extra section immediately after the one
about net-tools, saying something like:

<section id="ifupdown">
<!-- jessie to stretch -->
<title>Reduced dependencies on <systemitem
role="package">ifupdown</systemitem></title>
<para>
The package <systemitem role="package">netbase</systemitem> no
longer recommends <systemitem role="package">ifupdown</systemitem>,
which may therefore be identified as unneeded after the upgrade to
stretch. This may be appropriate if your system uses
<systemitem role="package">network-manager</systemitem>, but if
interfaces are still defined in
<filename>/etc/network/interfaces</filename> then <systemitem
role="package">ifupdown</systemitem> will need to be marked as
manually installed, for instance by running:
<screen>apt-mark manual ifupdown</screen>
</para>
</section>


I do see an added warning about evdev being deprecated in favour of
libinput, but it isn't accurate. It claims "This section is only
relevant if you have tweaked or need to change the default Xorg input
configuration", which just isn't true: the change caught me even on a
vanilla lightdm setup with ordinary keyboard and mouse. Until I
discovered and installed xserver-xorg-input-libinput (new in stretch)
my system was crippled. Advice on how to tweak libinput to support
fancy features does nothing to help users avoid this fate! (Also, the
title "Desktops will migrate..." is wrong; this has nothing to do with
desktops.)


Meanwhile my attempts to track down the bugs in networking.service and
startx have come to a dead end, so I'll just have to hope they were
problems with my setup and won't hit everyone else. The networking
one at least was easily fixed by the pending reboot.


However, the new version in SVN does have some new material, with some
new language errors:

Index: issues.dbk
===================================================================
--- issues.dbk (revision 11588)
+++ issues.dbk (working copy)
@@ -906,9 +914,10 @@
</para>
</section>
<section id="harmless-perl-warnings-during-upgrade">
+ <!-- jessie to stretch -->

And come to think of it there should be lots more of these throughout
this section. Added in the attached patch.

- <title>Harmeless <quote>Unespaced ... in regex is deprecated, ...</quote> warnings during upgrade</title>
+ <title>Harmless <quote>Unescaped ... in regex is deprecated, ...</quote> warnings during upgrade</title>
<para>

Smelling pistakes.

- During the upgrade, you may see some warning like:
+ During the upgrade, you may see some warnings like:

Number agreement.

<screen>
Unescaped left brace in regex is deprecated, passed through in regex; marked by &lt;-- HERE in m/^(.*?)(\\)?\${ &lt;-- HERE ([^{}]+)}(.*)$/ at /usr/share/perl5/Debconf/Question.pm line 72.
Unescaped left brace in regex is deprecated, passed through in regex; marked by &lt;-- HERE in m/\${ &lg;-- HERE ([^}]+)}/ at /usr/share/perl5/Debconf/Config.pm line 30.
@@ -915,7 +924,7 @@
</screen>
</para>
<para>
- These are harmless and happens if <systemitem
+ These are harmless, and happen if <systemitem
role="package">perl-base</systemitem> is upgraded before the
<systemitem role="package">debconf</systemitem> package.
</para>

Number agreement.

[Debian Bug Tracking System]

Post by Niels Thykier
tags -1 pending

Bug #864166 [release-notes] release-notes: proofreading sweep - issues.dbk
Added tag(s) pending.

[Debian Bug Tracking System]

Your message dated Wed, 13 Feb 2019 22:17:40 +0100
with message-id <9e1cecf0-2612-cae4-1f16-***@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 ***@bugs.debian.org
immediately.)