--- Begin Message ---
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.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
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>
<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),
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
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
@@ -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">
@@ -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>
@@ -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
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>
@@ -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
@@ -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.
--- End Message ---
--- Begin Message ---
On Sat, 3 Jun 2017 21:19:11 +0100 Justin B Rye
<justin.byam.rye@gmail.com> wrote:
> Javier Fernandez-Sanguino wrote:
> > 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?
>
Hi,
I apologise. I should have done that earlier. A lot earlier.
I have put it down on the release team's TODO list for buster[1].
I have applied attached patch (which is most, but not all, of Justin's
changes). I was considering to punt it to avoid unnecessary translation
work. However, after just committing 10 other changes to squeeze as
many erratas into the release notes as possible, I sort of already
burned that bridge.
> 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.
>
Thanks for that. :)
> 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.
> --
> JBR with qualifications in linguistics, experience as a Debian
> sysadmin, and probably no clue about this particular package
>
>
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).
Thanks,
~Niels
[1]
https://wiki.debian.org/Teams/ReleaseTeam/ReleaseCheckList?action=diff&rev2=57&rev1=56
diff --git a/en/moreinfo.dbk b/en/moreinfo.dbk
index ea14df07..d4d3097e 100644
--- a/en/moreinfo.dbk
+++ b/en/moreinfo.dbk
@@ -11,13 +11,13 @@
<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),
whose goal is to create high-quality documentation for Debian users and
-developers. Available documentation includes the Debian Reference, Debian New
+developers, such as the Debian Reference, Debian New
Maintainers Guide, the Debian FAQ, and many more. For full
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
@@ -30,9 +30,9 @@ documentation.
<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">
@@ -50,7 +50,7 @@ standard list etiquette.
<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>
@@ -70,11 +70,11 @@ url="&url-irc-host;">website</ulink>.
<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
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>
@@ -86,7 +86,7 @@ information be needed.
</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
@@ -103,7 +103,7 @@ url="&url-debian-list-archives;">lists</ulink> you are contributing to the
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.
--- End Message ---