Re: buster and the release notes
Paul Gevers wrote:
> Dear all,
(I'm dropping just debian-i18n)
[...]
> * l10n-english could do a review of the current text of all chapters,
> keeping in mind that especially the issues.dbk file will keep receiving
> updates during the releasing process, so the other files make more sense
> to check first.
I had noticed some paragraphs of issues.dbk that could be improved,
but nothing very dramatic.
> The about.dbk, installing.dbk, moreinfo.dbk and
> release-notes.dbk have close to zero changed or added text, so if the
> previous release notes were acceptable, those files are fine already.
As long as (for instance) the material about ports in installing.dbk
is up to date, yes, the "perennial" sections seem to be in good shape.
How about upgrading.dbk and whatsnew.dbk?
> I
> hope all members that want to contribute to review of proposed changes
> can also subscribe to merge request notifications in the salsa interface
> [1],
Ah, thanks, I hadn't spotted that.
> such that proposals that *don't* go via the bts still get the
> proper attention. Is aiming for a review within two weeks reasonable?
Sounds good to me. As it happens I was just looking at whats-new.dbk
and trying to decide whether to make it one diff for each of the
sections that need work. Instead of fiddling around any more with
that, here it is as one diff for the whole .dbk file:
(Inline commented version, plus attachment.)
diff --git a/en/whats-new.dbk b/en/whats-new.dbk
index 9965419f..f1bfcb5f 100644
--- a/en/whats-new.dbk
+++ b/en/whats-new.dbk
@@ -412,16 +412,16 @@ code.
<section id="de-manpages">
<!-- stretch to buster -->
- <title>Substantial improved man pages for German speaking users</title>
+ <title>Substantially improved man pages for German speaking users</title>
<para>
The documentation (<literal>man</literal>-pages) for several projects like
<systemitem role="package">systemd</systemitem>, <systemitem
role="package">util-linux</systemitem> and <systemitem
- role="package">mutt</systemitem> have been substantially extended and
- added. Please install <systemitem role="package">manpages-de</systemitem>
+ role="package">mutt</systemitem> has been substantially extended.
+ Please install <systemitem role="package">manpages-de</systemitem>
Is this trying to say that it has been extended and material has been
added? Instead of trying to fix it I've treated it as redundant.
to benefit from the improvements. During the lifetime of &releasename;
- backports of further improvements / translations will be provided within
- the <literal>backports</literal> archive.
+ further new/improved translations will be provided within the
+ <literal>backports</literal> archive.
</para>
</section>
"Improvements / translations" seems to be saying that some of the
improvements aren't translations. No, those wouldn't belong in
de-manpages! The alternatives are improvements and *new*
translations.
(And then I've left out the mention of the fact that the things in the
backports archive are backports.)
In section id="nftables":
@@ -433,8 +433,8 @@ code.
binary package includes <literal>iptables-nft</literal> and
<literal>iptables-legacy</literal>, two variants of the
<literal>iptables</literal> command line interface. The nftables-based
- variant is the default in buster and works with the
- <literal>nf_tables</literal> Linux kernel subsystem. The legacy one uses
+ variant, using the <literal>nf_tables</literal> Linux kernel
+ subsystem, is the default in buster. The legacy variant uses
the <literal>x_tables</literal> Linux kernel subsystem. Users can use the
update-alternatives system to select one variant or the other.
</para>
This whole thing is really longwinded, so I'm trying to trim it down
unobtrusively as I smooth out the English.
@@ -456,12 +456,12 @@ code.
</itemizedlist>
</para>
<para>
- All these gained the <literal>-nft</literal> and <literal>-legacy</literal>
- variants as well. The -nft option is for users that don't want -or can't-
- migrate to the native <literal>nftables</literal> command line
("Don't want -or can't- migrate" is at least missing a "to".)
- interface. However users are really enouraged to switch to
- <literal>nftables</literal> interface rather than using the old
- <literal>iptables</literal> interface.
+ All these have also gained <literal>-nft</literal> and <literal>-legacy</literal>
+ variants. The -nft option is for users who can't or don't want
+ to migrate to the native <literal>nftables</literal> command line
+ interface. However, users are strongly enouraged to switch to the
+ <literal>nftables</literal> interface rather than using
+ <literal>iptables</literal>.
</para>
<para>
<literal>nftables</literal> provides a full replacement for
@@ -474,7 +474,7 @@ code.
</para>
<para>
This movement is in line with what other major Linux distributions are
- doing, like RedHat, that now uses <literal>nftables</literal> as <ulink
+ doing, such as RedHat, which now uses <literal>nftables</literal> as its <ulink
url="https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8-beta/html-single/8.0_beta_release_notes/index#networking_2";>default
firewalling tool</ulink>.
</para>
@@ -482,11 +482,11 @@ code.
Also, please note that all <literal>iptables</literal> binaries are now
installed in <literal>/usr/sbin</literal> instead of
<literal>/sbin</literal>. A compatibility symlink is in place, but will be
- dropped after the buster release cycle. Please, don't use hardcoded binary
- paths in scripts or update them manually for the new location.
"Don't do X or Y" implies "don't do Y".
+ dropped after the buster release cycle, so hardcoded binary paths
+ in scripts will need to be corrected and are worth avoiding.
</para>
<para>
- Extensive documentation is available in package's README and NEWS files and
+ Extensive documentation is available in the package's README and NEWS files and
on the <ulink url="&url-wiki;nftables">Debian Wiki</ulink>.
</para>
</section>
(One of several missing definite articles.)
In section id="cryptsetup-luks2":
@@ -495,16 +495,16 @@ code.
<!-- stretch to buster -->
<title>Cryptsetup defaults to on-disk LUKS2 format</title>
<para>
- Debian buster ships with <systemitem role="package">cryptsetup</systemitem>
- which brings the new on-disk <literal>LUKS2</literal> format per default.
This makes it sound as if stretch used some other package, but in fact
even Debian sarge shipped with cryptsetup.
- New <literal>LUKS</literal> volumes will use the <literal>LUKS2</literal>
- format per default.
+ The <systemitem role="package">cryptsetup</systemitem> version
+ shipped with Debian buster uses the new on-disk
+ <literal>LUKS2</literal> format. New <literal>LUKS</literal>
+ volumes will use this format by default.
</para>
<para>
- Other than the previous <literal>LUKS1</literal> format,
+ Unlike the previous <literal>LUKS1</literal> format,
"Other than" usually means "except".
<literal>LUKS2</literal> provides redundancy of metadata, detection of
- metadata corruption and configurable <literal>PBKDF</literal> algorithms.
- Authenticated encryption is supported as well but still marked as
+ metadata corruption, and configurable <literal>PBKDF</literal> algorithms.
+ Authenticated encryption is supported as well, but still marked as
experimental.
</para>
<para>
Just nitpicking the punctuation.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff --git a/en/whats-new.dbk b/en/whats-new.dbk
index 9965419f..9f05d78c 100644
--- a/en/whats-new.dbk
+++ b/en/whats-new.dbk
@@ -412,16 +412,16 @@ code.
<section id="de-manpages">
<!-- stretch to buster -->
- <title>Substantial improved man pages for German speaking users</title>
+ <title>Substantially improved man pages for German speaking users</title>
<para>
The documentation (<literal>man</literal>-pages) for several projects like
<systemitem role="package">systemd</systemitem>, <systemitem
role="package">util-linux</systemitem> and <systemitem
- role="package">mutt</systemitem> have been substantially extended and
- added. Please install <systemitem role="package">manpages-de</systemitem>
+ role="package">mutt</systemitem> has been substantially extended.
+ Please install <systemitem role="package">manpages-de</systemitem>
to benefit from the improvements. During the lifetime of &releasename;
- backports of further improvements / translations will be provided within
- the <literal>backports</literal> archive.
+ further new/improved translations will be provided within the
+ <literal>backports</literal> archive.
</para>
</section>
@@ -433,8 +433,8 @@ code.
binary package includes <literal>iptables-nft</literal> and
<literal>iptables-legacy</literal>, two variants of the
<literal>iptables</literal> command line interface. The nftables-based
- variant is the default in buster and works with the
- <literal>nf_tables</literal> Linux kernel subsystem. The legacy one uses
+ variant, using the <literal>nf_tables</literal> Linux kernel
+ subsystem, is the default in buster. The legacy variant uses
the <literal>x_tables</literal> Linux kernel subsystem. Users can use the
update-alternatives system to select one variant or the other.
</para>
@@ -456,12 +456,12 @@ code.
</itemizedlist>
</para>
<para>
- All these gained the <literal>-nft</literal> and <literal>-legacy</literal>
- variants as well. The -nft option is for users that don't want -or can't-
- migrate to the native <literal>nftables</literal> command line
- interface. However users are really enouraged to switch to
- <literal>nftables</literal> interface rather than using the old
- <literal>iptables</literal> interface.
+ All these have also gained <literal>-nft</literal> and <literal>-legacy</literal>
+ variants. The -nft option is for users who can't or don't want
+ to migrate to the native <literal>nftables</literal> command line
+ interface. However, users are strongly enouraged to switch to the
+ <literal>nftables</literal> interface rather than using
+ <literal>iptables</literal>.
</para>
<para>
<literal>nftables</literal> provides a full replacement for
@@ -474,7 +474,7 @@ code.
</para>
<para>
This movement is in line with what other major Linux distributions are
- doing, like RedHat, that now uses <literal>nftables</literal> as <ulink
+ doing, such as RedHat, which now uses <literal>nftables</literal> as its <ulink
url="https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8-beta/html-single/8.0_beta_release_notes/index#networking_2";>default
firewalling tool</ulink>.
</para>
@@ -482,11 +482,11 @@ code.
Also, please note that all <literal>iptables</literal> binaries are now
installed in <literal>/usr/sbin</literal> instead of
<literal>/sbin</literal>. A compatibility symlink is in place, but will be
- dropped after the buster release cycle. Please, don't use hardcoded binary
- paths in scripts or update them manually for the new location.
+ dropped after the buster release cycle, so hardcoded binary paths
+ in scripts will need to be corrected and are worth avoiding.
</para>
<para>
- Extensive documentation is available in package's README and NEWS files and
+ Extensive documentation is available in the package's README and NEWS files and
on the <ulink url="&url-wiki;nftables">Debian Wiki</ulink>.
</para>
</section>
@@ -495,16 +495,16 @@ code.
<!-- stretch to buster -->
<title>Cryptsetup defaults to on-disk LUKS2 format</title>
<para>
- Debian buster ships with <systemitem role="package">cryptsetup</systemitem>
- which brings the new on-disk <literal>LUKS2</literal> format per default.
- New <literal>LUKS</literal> volumes will use the <literal>LUKS2</literal>
- format per default.
+ The <systemitem role="package">cryptsetup</systemitem> version
+ shipped with Debian buster uses the new on-disk
+ <literal>LUKS2</literal> format. New <literal>LUKS</literal>
+ volumes will use this format by default.
</para>
<para>
- Other than the previous <literal>LUKS1</literal> format,
+ Unlike the previous <literal>LUKS1</literal> format,
<literal>LUKS2</literal> provides redundancy of metadata, detection of
- metadata corruption and configurable <literal>PBKDF</literal> algorithms.
- Authenticated encryption is supported as well but still marked as
+ metadata corruption, and configurable <literal>PBKDF</literal> algorithms.
+ Authenticated encryption is supported as well, but still marked as
experimental.
</para>
<para>
Reply to: