Bug#864166: release-notes: proofreading sweep - issues.dbk
Control: tags -1 pending
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).
> [...]
>
> 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.
> [...]
> @@ -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.
>
I think <literal> is more accurate. I have used that.
> [...]
>
> 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.
> [...]
>
> (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.
> [...]
> 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>.
> [...]
>
> @@ -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)
> @@ -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),
>
An example would be good. I will try to add one. :)
> 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.
> [...]
> 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.
> @@ -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.
> @@ -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.
> [...]
> [... 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
Reply to: