Re: releasenotes
Steve Langasek wrote:
>> "Interactive" is a genuinely confusing misnomer; it turns out that
>> it means "full-screen Text User Interface" versus "Command Line
>> Interface", but what can it mean to recommend the *only* program
>> with such a TUI as the *preferred* one?
>
> I'm not sure what you find confusing about this. The aptitude TUI allows
> you to interactively edit the upgrade solution. The apt-get command does
> not, it only presents the user with the option to confirm or reject the
> proposed solution. Referring to one as interactive and the other as
> non-interactive may be imprecise, but I don't think it's really confusing.
Might this be because you already knew what it was trying to say? It
certainly confused me - I assumed it was really talking about the kind
of package management involved in non-interactive intallations.
Nonetheless, why post to the list if I'm not going to take advice?
I'll drop it unless people ask for a revised patch.
>> * In the same section:
>> The paragraph about Recommends being installed by default (and the
>> footnote claiming that this is a change that increases diskspace
>> requirements) is a leftover New-In-Lennyism, and should go.
>
> It is not leftover, this is new information that was not included in the
> lenny release notes at time of release. It's documented here so that people
> will see it - adding it now to the lenny release notes isn't going to reach
> the target audience.
Ah! Right, I was comparing online versions to find the stale parts.
> The text should perhaps be tweaked to clarify that this was already true in
> lenny.
No, I wouldn't have objected if the sources had had a comment.
Dropping this section too.
>> upgrading.dbk:
>>
>> * 4.2.1 "Review actions pending in package manager"
>> This uses a *different* unintelligible name for aptitude's TUI:
>
>> To perform this review, launch aptitude in "visual mode" and
>> press g ("Go").
>
>> That's visual as opposed to reading the screen via sonar, right?
>> We should standardise on a single comprehensible name for this:
>
>> To perform this review, launch aptitude in full-screen mode and
>> press g ("Go").
>
> "visual mode" is the definitive name for this mode as used in the aptitude
> manpage. The release notes are not the place to be coining new terms for
> things. Please take the naming up with the aptitude maintainer.
The problem is we're not even using *consistent* demented obfuscatory
jargon from section to section: "interactive" last time, "visual" this
time. Still, if I start arguing while I'm drinking this coffee I'll
never stop, so forget it.
>> * 4.4.5. "Upgrading the kernel and udev"
>> Should this crossreference to Xen? As mentioned on d-l-e:
>> http://lists.debian.org/debian-l10n-english/2011/01/msg00106.html
>
> Yes, I think that would be a good idea. Can you follow up to the bug report
> and mention that, perhaps proposing text? (There's still no Xen text in the
> release notes to cross-reference, so this is the best place to keep that
> request to avoid losing track of it.)
Okay, but I'll finish splitting out my existing patches first.
>> * 4.6.1. "Installing the kernel metapackage"
>> The material about kernel-package versus "make deb-pkg" needs to be
>> rephrased slightly, but I'm not sure what it's safe to say.
>
>> There are some differences in these two approaches, please
>> consult the respective package's documentation.
>
>> This is an example of my rule of thumb that any sentence with
>> "respective" in it needs reworking. But as far as I can see there
>> *is* no packaged documentation for the "make deb-pkg" approach, so
>> we either need to find a URL or throw this line out.
>
> I agree. In general I'm unhappy with the changes to the documentation of
> kernel-package for squeeze; we don't want to recommend users build their own
> kernel for no reason, but I also don't think we should associate this with
> "adventure". I would favor a rewrite of this paragraph.
Currently:
<para>
For the more adventurous there is an easy way to compile your own custom
kernel on &debian;. Install the <systemitem
role="package">kernel-package</systemitem> tool and read the documentation in
<filename>/usr/share/doc/kernel-package</filename>. Alternatively,
you can also use the kernel sources, provided in the <systemitem
role="package">linux-source-2.6</systemitem> package. You can make use of the
<literal>deb-pkg</literal> target available in the sources' makefile for
building a binary package. There are some differences in these two approaches,
please consult the respective package's documentation.
</para>
Just reshuffling it into what seems a more natural order:
<para>
There are also two different easy ways to compile your own custom
kernel on &debian; as a binary package from the kernel sources, which
are provided via the <systemitem
role="package">linux-source-2.6</systemitem> package. Either install the
<systemitem role="package">kernel-package</systemitem> tool (and read the
documentation in <filename>/usr/share/doc/kernel-package</filename>) or
use the <literal>deb-pkg</literal> target which is now available in the
sources' makefile.
</para>
Is this worth the disruption or should we stick to just ripping out
the last sentence?
>> * 4.4.3. "Make sure you have sufficient space for the upgrade"
>> The tip to use deborphan is a leftover from Etch, and looking more
>> and more stale now that even apt itself provides better ways of
>> spotting obsolete libraries. Can we get rid of it?
>
> For long-lived systems, deborphan still tells me about packages that were
> auto-installed before apt knew to track them and are now obsolete. I think
> we should keep this here for one more release cycle.
Yes, fair enough (I had a query about popcon-largest-unused and
relatime that I squelched on similar grounds).
>> * 4.10. "Obsolete packages"
>> The item on replacements for apt-proxy is a bit long-winded. Just
>> say "apt-proxy is no longer provided; although no automatic upgrade
>> path exists, users can switch to alternatives such as..."
>
> Ack.
Separate patch.
>> issues.dbk:
>
>> * 5.1.2. "mdadm metadata format change requires recent Grub"
>
>> To ensure a bootable system, please make sure to use grub-pc
>> 1.98+20100720-1 or later, which is provided by Debian squeeze
>
>> How is this an upgrade issue if Squeeze's version *fixes* it?
>> Does it mean "please make sure the new version in Squeeze has
>> installed its GRUB bootloader code to the MBR"?
>
> Yes, this is about making sure that the correct version of grub is being
> used for booting, which is not ensured by installing / upgrading the grub-pc
> package.
Patch attached, without the word "MBR" since I'm not confident it's
universally approproate.
>> * 5.1.3. "pam_userdb.so breakage with newer libdb"
>> This needs some hint at who'd be affected (i.e. users of exotic
>> login setups?)
>
> The users affected by it are those who use pam_userdb. Does that really
> need to be spelled out?
It wouldn't hurt, because alarmed users will discover that they have
indeed got a /lib/security/pam_userdb.so on their systems. How do
they know whether something's using it? My patch prefixes "If you
authenticate users against a Berkeley DB database, you should be aware
that".
>> * 5.3. "sieve service moving to its IANA-allocated port"
>> When it says:
>> Starting with the version 4.38 of the Debian netbase package, the
>> sieve service will be moved from port 2000 [...]
>> What it should say is:
>> In the version of netbase in Squeeze, the sieve service has been
>> moved from port 2000 [...]
>
> Ack.
Patch.
>> * 5.5.2. "Device and other administrative permissions"
>> "See the consolekit documentation for more information" is cruel -
>> it doesn't even provide manpages. Perhaps a link to
>> http://www.freedesktop.org/wiki/Software/ConsoleKit ?
>
> Seems reasonable to me.
Patch with URL referenced as "upstream wiki"...
>> * 5.6.2. "Kernel mode setting"
>> Add some extra clues (a single hyphen would go a long way) that
>> this is kernelspace video mode-setting, not kernel-mode setting.
>> Obvious if you know; alarming bafflegab if you don't.
>
> Ack to a hyphen.
Which means I could demote it to a proofreading issue, I suppose, but
micropatch attached.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru release-notes.pristine//en/upgrading.dbk release-notes/en/upgrading.dbk
--- release-notes.pristine//en/upgrading.dbk 2011-02-01 17:35:20.493027527 +0000
+++ release-notes/en/upgrading.dbk 2011-02-01 23:03:56.473255696 +0000
@@ -2017,13 +2017,11 @@
<listitem>
<para>
<systemitem role="package">apt-proxy</systemitem> is no longer
- provided, alternatives to this tool include
+ provided; although no automatic upgrade path exists, users can switch
+ to alternatives such as
<systemitem role="package">apt-cacher-ng</systemitem>,
- <systemitem role="package">apt-cacher</systemitem> and
- <systemitem role="package">approx</systemitem>. Although no
- automatic upgrade path exists, user of <systemitem
- role="package">apt-proxy</systemitem> can switch to these alternatives
- by manually installing any of these packages.
+ <systemitem role="package">apt-cacher</systemitem>, or
+ <systemitem role="package">approx</systemitem>.
</para>
</listitem>
<listitem>
diff -ru release-notes.pristine//en/issues.dbk release-notes/en/issues.dbk
--- release-notes.pristine//en/issues.dbk 2011-02-01 17:35:20.496916343 +0000
+++ release-notes/en/issues.dbk 2011-02-01 23:17:35.068922844 +0000
@@ -639,8 +639,9 @@
granted automatically to the user currently logged on physically to the
system: video and audio devices, network roaming, power management,
device mounting. The cdrom, floppy, audio, video, plugdev and powerdev
-groups are no longer useful. See the <systemitem
-role="package">consolekit</systemitem> documentation for more information.
+groups are no longer useful. See the <ulink
+url="http://www.freedesktop.org/wiki/Software/ConsoleKit";>upstream
+wiki</ulink> for more information.
</para>
<para>
Most graphical programs requiring root permissions now rely on <ulink
diff -ru release-notes.pristine//en/upgrading.dbk release-notes/en/upgrading.dbk
--- release-notes.pristine//en/upgrading.dbk 2011-02-01 17:35:20.493027527 +0000
+++ release-notes/en/upgrading.dbk 2011-02-01 22:56:46.760925403 +0000
@@ -1244,15 +1244,14 @@
opportunity to get the benefits provided by the new kernel version.
</para>
<para>
-For the more adventurous there is an easy way to compile your own custom
-kernel on &debian;. Install the <systemitem
-role="package">kernel-package</systemitem> tool and read the documentation in
-<filename>/usr/share/doc/kernel-package</filename>. Alternatively,
-you can also use the kernel sources, provided in the <systemitem
-role="package">linux-source-2.6</systemitem> package. You can make use of the
-<literal>deb-pkg</literal> target available in the sources' makefile for
-building a binary package. There are some differences in these two approaches,
-please consult the respective package's documentation.
+There are also two different easy ways to compile your own custom
+kernel on &debian; as a binary package from the kernel sources, which
+are provided via the <systemitem
+role="package">linux-source-2.6</systemitem> package. Either install the
+<systemitem role="package">kernel-package</systemitem> tool (and read the
+documentation in <filename>/usr/share/doc/kernel-package</filename>) or
+use the <literal>deb-pkg</literal> target which is now available in the
+sources' makefile.
</para>
<para>
If possible, it is to your advantage to upgrade the kernel package separately
diff -ru release-notes.pristine//en/issues.dbk release-notes/en/issues.dbk
--- release-notes.pristine//en/issues.dbk 2011-02-01 17:35:20.496916343 +0000
+++ release-notes/en/issues.dbk 2011-02-01 23:18:51.549263775 +0000
@@ -721,7 +721,7 @@
</section>
<section>
- <title>Kernel mode setting</title>
+ <title>Kernel mode-setting</title>
<para>
Kernel drivers for Intel (starting from i830), ATI/AMD (from the
original Radeon to the Radeon HD 5xxx <quote>Evergreen</quote> series)
diff -ru release-notes.pristine//en/issues.dbk release-notes/en/issues.dbk
--- release-notes.pristine//en/issues.dbk 2011-02-01 17:35:20.496916343 +0000
+++ release-notes/en/issues.dbk 2011-02-01 23:07:19.616913625 +0000
@@ -75,9 +75,9 @@
Versions of <systemitem role="package">grub-pc</systemitem> older than
1.98+20100720-1 will not be able to boot directly off
a <acronym>RAID</acronym> with the 1.x metadata formats (the new default is
-1.2). To ensure a bootable system, please make sure to use <systemitem
-role="package">grub-pc</systemitem>
-1.98+20100720-1 or later, which is provided by Debian &releasename;. An
+1.2). To ensure a bootable system, please make sure that the new
+version of <systemitem role="package">grub-pc</systemitem> provided by Debian
+&releasename; has installed its bootloader code to the disk. An
unbootable system may be rescued with <ulink
url="http://www.supergrubdisk.org/super-grub2-disk/";>Super Grub2 Disk</ulink>
or <ulink url="http://grml.org";>grml</ulink>.
diff -ru release-notes.pristine//en/issues.dbk release-notes/en/issues.dbk
--- release-notes.pristine//en/issues.dbk 2011-02-01 17:35:20.496916343 +0000
+++ release-notes/en/issues.dbk 2011-02-01 23:10:38.668913473 +0000
@@ -87,7 +87,8 @@
<section id="pam_userdb">
<title>pam_userdb.so breakage with newer libdb</title>
<para>
-Some Berkeley Database version 7 files created with libdb3 cannot be read by
+If you authenticate users against a Berkeley DB database, you should
+be aware that some Berkeley Database version 7 files created with libdb3 cannot be read by
newer libdb versions (see bug <ulink url="&url-bts;521860">#521860</ulink>).
As a workaround, the files can be recreated with <command>db4.8_load</command>,
from the <systemitem role="package">db4.8-util</systemitem> package.
diff -ru release-notes.pristine//en/issues.dbk release-notes/en/issues.dbk
--- release-notes.pristine//en/issues.dbk 2011-02-01 17:35:20.496916343 +0000
+++ release-notes/en/issues.dbk 2011-02-01 23:12:43.405256472 +0000
@@ -444,9 +444,9 @@
url="http://www.iana.org/assignments/port-numbers";>the IANA registry</ulink>.
</para>
<para>
-Starting with the version 4.38 of the Debian <systemitem
-role="package">netbase</systemitem> package, the <literal>sieve</literal>
-service will be moved from port 2000 to port 4190 in the
+In the version of <systemitem role="package">netbase</systemitem> in
+&releasename, the <literal>sieve</literal>
+service has been moved from port 2000 to port 4190 in the
<filename>/etc/services</filename> file.
</para>
<para>
Reply to: