Bug#864043: release-notes: proofreading sweep - moreinfo.dbk

[Justin B Rye]

Package: release-notes
Severity: wishlist
Tags: patch

I ought to have time to do a second sweep, so I won't worry about
followups to my existing bugs yet. Today, another easy one.

Index: moreinfo.dbk
===================================================================
--- moreinfo.dbk (revision 11526)
+++ moreinfo.dbk (working copy)
@@ -6,18 +6,18 @@
]>

<chapter id="ch-moreinfo" lang="en">
-<title>More information on &debian;</title>
+<title>More information on Debian</title>

This is the one file where I've noticed any cases where I want to
eliminate a couple of uses of "&debian;". Anybody who wants to
recycle this text for use in another distro is going to have to reword
every line anyway, and they'll have an easier time of it if they can
find all the distro-name references by searching for the one string
"Debian". If they tried rejigging it so "&debian;" expands to Ubuntu
or something they'd just get a page full of lies about Ubuntu
interspersed with hardcoded references to Debian - there's a nice
example in this next bit:

<section id="morereading">
<title>Further reading</title>
<para>
Beyond these release notes and the installation guide, further documentation on
-&debian; is available from the Debian Documentation Project (DDP),
+Debian is available from the Debian Documentation Project (DDP),

See above.

whose goal is to create high-quality documentation for Debian users and
-developers. Available documentation includes the Debian Reference, Debian New
-Maintainers Guide, the Debian FAQ, and many more. For full
+developers, such as the Debian Reference, Debian New
+Maintainers' Guide, and Debian FAQ. For full

Simpler and stylistically better phrasing. For a start, "many more"
doesn't match up with non-count-noun "documentation" (and the phrase
is repeated later in this page, is redundant with "includes"). In the
process of reorganising I've added an apostrophe in the same place as
it occurs in the title page of the DNMG, and made the use of definite
articles consistent.

details of the existing resources see the <ulink
url="&url-ddp;">Debian Documentation website</ulink> and the
-<ulink url="&url-wiki;">Debian Wiki website</ulink>.
+<ulink url="&url-wiki;">Debian Wiki</ulink>.
</para>
<para>
Documentation for individual packages is installed into

"Wiki website" is redundant (and here, repetitive). It would also
work if we phrased it as "the [Debian Wiki] and [DDP] websites".

@@ -30,9 +30,9 @@
<section id="gethelp">
<title>Getting help</title>
<para>
-There are many sources of help, advice, and support for Debian users, but these
-should only be considered if research into documentation of the issue has
-exhausted all sources. This section provides a short introduction to these sources
+There are many sources of help, advice, and support for Debian users, though
+these should only be considered after researching the issue in available
+documentation. This section provides a short introduction to these sources
which may be helpful for new Debian users.
</para>
<section id="lists">

Rephrased to make it comprehensible. The old version used "sources"
one way, then a different way, then tried to refer back to "these
sources" meaning the former. The reference to "research into
documentation" was also slightly confusing.

@@ -50,7 +50,7 @@
<section id="irc">
<title>Internet Relay Chat</title>
<para>
-Debian has an IRC channel dedicated to the support and aid of Debian users,
+Debian has an IRC channel dedicated to support and aid for Debian users,
located on the OFTC IRC network. To access the channel, point your favorite
IRC client at irc.debian.org and join <literal>#debian</literal>.
</para>

Referring to the aid *of* users is ambiguous. In fact usually it's
both by and for users, but the side we're talking about is "for".

@@ -70,11 +70,11 @@
<section id="bugs">
<title>Reporting bugs</title>
<para>
-We strive to make &debian; a high quality operating system; however
+We strive to make Debian a high-quality operating system; however

None of this paragraph is reusable for &randomdistro;. Then the
hyphen in "high-quality" isn't completely compulsory, but we mentioned
"high-quality documentation" earlier, so be consistent.

that does not mean that the packages we provide are totally free of bugs.
Consistent with Debian's <quote>open development</quote> philosophy and as a service to our
users, we provide all the information on reported bugs at our own Bug Tracking
-System (BTS). The BTS is browseable at <ulink
+System (BTS). The BTS can be browsed at <ulink
url="&url-bts;"></ulink>.
</para>
<para>

There's some debate about the spelling of "brows(e)able", but avoiding
the issue makes it sound better anyway.

@@ -86,7 +86,7 @@
</para>
<para>
You can submit a bug report using the program <command>reportbug</command> or
-manually using e-mail. You can read more about the Bug Tracking System and how
+manually using e-mail. You can find out more about the Bug Tracking System and how
to use it by reading the reference documentation (available at
<filename>/usr/share/doc/debian</filename> if you have <systemitem
role="package">doc-debian</systemitem> installed) or online at the <ulink

You can read more by reading the docs? When I read things, my
objective isn't to end up having read more, it's to find out about
stuff.

(This document uses the minority spelling "e-mail", but at least it's
consistent about it.)

@@ -103,7 +103,7 @@
community. Identifying (and also solving) problems related to the development
of the distribution by participating on the development <ulink
url="&url-debian-list-archives;">lists</ulink> is also extremely helpful. To
-maintain Debian's high quality distribution, <ulink
+maintain Debian's high-quality distribution, <ulink
url="&url-bts;">submit bugs</ulink> and help developers track
them down and fix them. The tool <systemitem
role="package">how-can-i-help</systemitem> helps you to find suitable reported bugs to work on.

Another extra hyphen for the third repetition of the same phrase. If
I could think of a good enough synonym I would substitute it in for
(probably) the middle one, but nothing else fits quite as well.

[Javier Fernandez-Sanguino]

Dear Justin,

Thank you for this review. Although I can agree to many of these changes, I
do not think it is wise to make them so close to the release date, when
translation teams have updated (or are in the process of updating) the
translations in preparation of the Release.

Release Notes should be string frozen at some point, they should not be a
loving target. These type of stylistic changes ("&debian;" to "Debian"")
should in my opinion, be done post-release.

At the very least, translation teams should be informed (specially those
currently close to or at 100% [1]). So they are aware and have time to
do/plan a last review/update before $RELEASE.


Saludos

Javier

[1] https://www.debian.org/releases/testing/statistics.html
There are currently 9 (out of 19) translations which are over 90%)

[Justin B Rye]

Post by Javier Fernandez-Sanguino
Dear Justin,
Thank you for this review. Although I can agree to many of these changes, I do
not think it is wise to make them so close to the release date, when
translation teams have updated (or are in the process of updating) the
translations in preparation of the Release.

The only way to avoid this situation would be for somebody to make an
announcement that translation work will need to start on such-and-such
a date, leaving enough time for finalising the English text *before*
that starts. Do you think we can try that approach for Buster?

So far I've been dealing with the pages that don't change much from
release to release, suggesting changes that aren't particularly
urgent, but the pages I'm planning to get round to in the next couple
of days still contain factual inaccuracies that need fixing.

Meanwhile, my test upgrades so far (multiple trials on two different
machines) have consistently run into a couple of nasty undocumented
glitches - the upgrade disables my network connection (a restart of
networking.service that errors out), and the new version of X doesn't
respond to input devices until I install xserver-xorg-input-libinput.
I was hoping to find some mention of these issues in pending bug
reports, but it doesn't look like it.

[Baptiste Jammet]

Hello Justin,
(dropping the bug and d-l-e, keeping -doc)

Post by Justin B Rye
Meanwhile, my test upgrades so far (multiple trials on two different
machines) have consistently run into a couple of nasty undocumented
glitches - the upgrade disables my network connection (a restart of
networking.service that errors out),
the new version of X doesn't
respond to input devices until I install xserver-xorg-input-libinput.

there is #860259. Could you propose something ?

Thanks
Baptiste

[Justin B Rye]

Post by Baptiste Jammet
Hello Justin,
(dropping the bug and d-l-e, keeping -doc)

Post by Justin B Rye
Meanwhile, my test upgrades so far (multiple trials on two different
machines) have consistently run into a couple of nasty undocumented
glitches - the upgrade disables my network connection (a restart of
networking.service that errors out),
the new version of X doesn't
respond to input devices until I install xserver-xorg-input-libinput.

there is #860259. Could you propose something ?

I'm afraid I don't understand the situation well enough. From my
point of view, it doesn't look like a documentation bug - it looks as
if xserver-xorg-input-evdev stops functioning at all under stretch,
which is an obvious release-critical bug. But if that was true I
would have expected other people to have noticed. *Is* there a way of
making evdev continue to work after the dist-upgrade? Or should it be
replaced by a transition package pulling in x-x-i-libinput?


Meanwhile on the same page of debian-user archives I see people are
also running into the minor problem that stretch initramfs expects
/etc/initramfs-tools/conf.d/resume to contain the UUID of a valid swap
device, giving a boot-time delay if, for instance, you've run mkswap
since install time (even if you never use resume). That's *another*
thing that ought to be mentioned in issues.dbk.

[Justin B Rye]

[Resend - sorry, I thought mail to #864043 would go to the list]

Post by Justin B Rye
Meanwhile, my test upgrades so far (multiple trials on two different
machines) have consistently run into a couple of nasty undocumented
glitches - the upgrade disables my network connection (a restart of
networking.service that errors out), and the new version of X doesn't
respond to input devices until I install xserver-xorg-input-libinput.
I was hoping to find some mention of these issues in pending bug
reports, but it doesn't look like it.

Have both of these issues been adequately documented by now? They sound
like the kind of issues that ought to be documented (assuming they are a
general problem).

Sorry, no. This dist-upgrade has been the trickiest I've seen for a
decade or so, and most of the glitches aren't really documented.

#1) X starts needing xserver-xorg-input-libinput, which will be pulled
in by default if you've got xserver-xorg-input-all installed, but not
otherwise (symptoms: input stops working). There's a new item about
libinput, but it basically fails to address this issue.

#2) independently, startx stops working with similar symptoms, but
nothing I've found makes it work again, regardless of what else I
install (in particular, xserver-xorg-legacy makes no difference).
The only solution I've found is to switch to lightdm (which might as
well happen before the dist-upgrade). If nobody else is seeing this
then I don't even know what to report a bug against.

#3) after an upgrade, ifupdown is marked as automatically installed
and no longer held in by dependencies, so things like aptitude want
to uninstall it as junk. Fortunately I'd noticed this was likely to
happen before I started doing upgrades, so I've never had my network
crippled by this. I suggested some text about this in
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=864166#57

#4) at the end of the dist-upgrade needrestart restarts networking,
which fails - the wifi interface gives errors as if I'd defined two
gateway addresses. You can tell needrestart not to do this, but
fortunately it's fixed by a reboot, and a reboot was the next step
in the dist-upgrade anyway. However, it's easy to imagine ways this
could combine with the other items on this list to be a real problem.
I can't reproduce the issue outside the context of a dist-upgrade, so
again I don't know where the bug is exactly, and if nobody else is
seeing it then I don't know if it warrants being mentioned in the
release-notes.

It's possible that #2 amd #4 only hit me because I'm doing my trial
upgrades on an old machine, and I'm not using a mainstream desktop
environment (just fvwm). But I haven't heard anybody claiming to have
done any bug-free upgrades, so it's hard to be confident.

[Justin B Rye]

Post by Justin B Rye
Sorry, no. This dist-upgrade has been the trickiest I've seen for a
decade or so, and most of the glitches aren't really documented.
#1) X starts needing xserver-xorg-input-libinput, which will be pulled
in by default if you've got xserver-xorg-input-all installed, but not
otherwise (symptoms: input stops working). There's a new item about
libinput, but it basically fails to address this issue.

In particular it fails to mention the crucial detail below.

Post by Justin B Rye
#2) independently, startx stops working with similar symptoms, but
nothing I've found makes it work again, regardless of what else I
install (in particular, xserver-xorg-legacy makes no difference).
The only solution I've found is to switch to lightdm (which might as
well happen before the dist-upgrade). If nobody else is seeing this
then I don't even know what to report a bug against.

After confirming that I was also getting these symptoms on a third
machine with less antiquated hardware, I've finally tracked down what
I was missing: the user starting the session needs to be a member of
group "input". Or root, of course, which is why it's not needed with
lightdm; but it's a new requirement with libinput that doesn't seem to
be documented anywhere - certainly not in release-notes section 5.3.3.

(In fact it's so undocumented that even the page for libinput on the
ArchLinux wiki never mentions the word "group"! I can see mentions of
the input group in old touchpad HOWTOs written in the days when
libinput was an obscure alternative approach, but there's no hint
it would be needed with my oldfashioned psaux mouse and keyboard.)

Post by Justin B Rye
#3) after an upgrade, ifupdown is marked as automatically installed
and no longer held in by dependencies, so things like aptitude want
to uninstall it as junk. Fortunately I'd noticed this was likely to
happen before I started doing upgrades, so I've never had my network
crippled by this. I suggested some text about this in
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=864166#57
#4) at the end of the dist-upgrade needrestart restarts networking,
which fails - the wifi interface gives errors as if I'd defined two
gateway addresses. You can tell needrestart not to do this, but
fortunately it's fixed by a reboot, and a reboot was the next step
in the dist-upgrade anyway. However, it's easy to imagine ways this
could combine with the other items on this list to be a real problem.
I can't reproduce the issue outside the context of a dist-upgrade, so
again I don't know where the bug is exactly, and if nobody else is
seeing it then I don't know if it warrants being mentioned in the
release-notes.

Again, I can confirm this as absolutely reproducible, but it only
happens if you've got needrestart installed, which according to popcon
is under 2% of users (and hopefully the kind that can cope). And
under normal circumstances, "systemctl restart networking.service"
still works correctly on Stretch.

Post by Justin B Rye
It's possible that #2 amd #4 only hit me because I'm doing my trial
upgrades on an old machine, and I'm not using a mainstream desktop
environment (just fvwm). But I haven't heard anybody claiming to have
done any bug-free upgrades, so it's hard to be confident.

I've seen no sign of other sufferers from #2 or #4 on debian-user, so
maybe it doesn't matter.

[Debian Bug Tracking System]

Your message dated Sat, 10 Jun 2017 00:05:00 +0000
with message-id <18db42ba-7d40-1fc4-25b2-***@thykier.net>
and subject line Re: Bug#864043: release-notes: proofreading sweep - moreinfo.dbk
has caused the Debian Bug report #864043,
regarding release-notes: proofreading sweep - moreinfo.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.)