[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: releasenotes

On Thu, Oct 07, Justin B Rye wrote:
> People are talking about the Squeeze release notes being nearly
> ready for a call for translations.  I hope they are remembering that
> before the call for translations there needs to be a quick
> debian-l10n-english proofreading run-through, and before *that* we
> need to come up with some factually accurate content.

Nobody's called for any d-l-e run-through yet, but I thought it would
make sense to get on with a first pass anyway, ignoring all the minor
typos and non-native-English-speakerisms for now and just looking for
content that needs to be checked.


 * 2.1.2 "Package management"
   This bit's badly messed up:

     The preferred program for interactive package management from a
     terminal is aptitude. For a non-interactive command line interface
     for package management, it is recommended to use apt-get. apt-get
     is also the preferred tool for upgrades between major releases.

   "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?

   Besides, on what grounds are the release notes telling me not to
   use aptitude's CLI for routine package management on Squeeze?  How
   else am I going to perform an "aptitude purge ~c"?

   Also, "between major releases" is overstated: it wasn't true for
   Etch-to-Lenny and may or may not be true for Squeeze-to-Wheezy.

   I'm hoping this text can be rephrased as follows:

     For users familiar with aptitude's full-screen mode, this is
     the preferred interface for normal package management. However,
     the recommended command line tool for the Lenny to Squeeze
     upgrade is apt-get.

 * 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.


 * 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").

 * 4.4.5. "Upgrading the kernel and udev"
   Should this crossreference to Xen?  As mentioned on d-l-e:

 * 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.

 * 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?

 * 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..."


 * 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"?

 * 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?)

 * 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 [...]

 * 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 ?

 * 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.

JBR - and today's single word in West Greenlandic is:
       "Silly me, I went and spoke out of turn as usual!"

Reply to: