[Pkg-utopia-maintainers] Bug#614146: udisks: obfuscatory package description

[Justin B Rye]

Package: udisks
Version: 1.0.1+git20100614-3
Severity: wishlist
Tags: patch

The package description for udisks is unnecessarily jargon-heavy.
It's easy for a non-GNOME desktop not to include any packages that
declare a dependency on udisks, and a user looking for software to
install manually is offered no incentive by the current description.

 Description: abstraction for enumerating block devices
 
The package is not an "abstraction", and the executables it contains
are useful for a lot more than "enumerating block devices" - that
sounds like a job for "find /dev -type b | nl"!

  udisks is an abstraction for enumerating block devices and performing
  operations on them. Any application can access the
  org.freedesktop.UDisks service on the system message bus.
  Some operations (such as formatting disks etc.) are restricted using PolicyKit.

This is sadly lacking in the sort of information that Debian Policy
3.4 says "should" be present in a package description  - the users
reading it are supposed to be able to tell what benefits the software
offers to them, not to applications on buses!

I would suggest starting from scratch with something more like:

 Description: storage media interface
  The udisks daemon serves as an interface to system block devices,
  implemented via D-Bus. It handles operations such as querying, mounting,
  unmounting, formatting, or detaching storage devices such as hard disks
  or USB thumb drives.
  .
  This package also provides the udisks utility, which can be used to
  trigger these operations from the command line (if permitted by
  PolicyKit). External tools such as hdparm are used if available to
  implement extra operations, such as configuring disk spindown times.

(That would also go some way towards closing bug #595114, though that
might require a more detailed list than I can provide.)

While I'm editing this control file, the udisks-doc package can use:

 Description: storage media interface - documentation
  The udisks daemon serves as an interface to system block devices,
  implemented via D-Bus. It handles operations such as querying, mounting,
  unmounting, formatting, or detaching storage devices such as hard disks
  or USB thumb drives.
  .
  This package provides the API reference and manuals in devhelp format.

(That should be enough to make it clear that there's no extra user
documentation here, and indeed nothing that's easily accessible if you
don't happen to have the right specialised API-browser installed.)

-- System Information:
Debian Release: 6.0
  APT prefers stable
  APT policy: (500, 'stable'), (200, 'squeeze-updates')
Architecture: amd64 (x86_64)

Kernel: Linux 2.6.32-5-amd64 (SMP w/2 CPU cores)
Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages udisks depends on:
ii  dbus                  1.2.24-4           simple interprocess messaging syst
ii  libatasmart4          0.17+git20100219-2 ATA S.M.A.R.T. reading and parsing
ii  libc6                 2.11.2-10          Embedded GNU C Library: Shared lib
ii  libdbus-1-3           1.2.24-4           simple interprocess messaging syst
ii  libdbus-glib-1-2      0.88-2.1           simple interprocess messaging syst
ii  libdevmapper1.02.1    2:1.02.48-5        The Linux Kernel Device Mapper use
ii  libglib2.0-0          2.24.2-1           The GLib library of C routines
ii  libgudev-1.0-0        164-3              GObject-based wrapper library for 
ii  libparted0debian1     2.3-5              The GNU Parted disk partitioning s
ii  libpolkit-backend-1-0 0.96-4             PolicyKit backend API
ii  libpolkit-gobject-1-0 0.96-4             PolicyKit Authorization API
ii  libsgutils2-2         1.29-1             utilities for devices using the SC
ii  libudev0              164-3              libudev shared library
ii  udev                  164-3              /dev/ and hotplug management daemo

Versions of packages udisks recommends:
ii  dosfstools                  3.0.9-1      utilities for making and checking 
ii  hdparm                      9.32-1       tune hard disk parameters for high
ii  mtools                      4.0.12-1     Tools for manipulating MSDOS files
pn  ntfs-3g                     <none>       (no description available)
pn  ntfsprogs                   <none>       (no description available)
ii  policykit-1                 0.96-4       framework for managing administrat

Versions of packages udisks suggests:
pn  cryptsetup                    <none>     (no description available)
pn  mdadm                         <none>     (no description available)
pn  reiserfsprogs                 <none>     (no description available)
pn  xfsprogs                      <none>     (no description available)

-- no debconf information

-- 
JBR
Ankh kak! (Ancient Egyptian blessing)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pdreview.patch
Type: text/x-diff
Size: 2128 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/pkg-utopia-maintainers/attachments/20110219/da811f85/attachment.patch>