[Pkg-lxde-maintainers] Bug#645248: Please reconsider package description

[Justin B Rye]

Martin Eberhard Schauer wrote:
> working on the German translation of the package description (1) I encountered an
> inconsistent spelling of lxde and other issues with the potential of improvement.
> 
>> Description: Lightweight X11 Desktop Environment configuration data
>>  LXDE (the Lightweight X11 Desktop Environment) is a project aimed
>>  to provide a new desktop environment which is lightweight and fast.
> 
> It is quite common to separate the name of the software resulting in severa
> l packages from the package's function (dev, doc and the like) by means of
>  a dash or brackets. And paragraph one could be shortened:
> 
> Description: Lightweight X11 Desktop Environment (LXDE) - configuration data
>  The LXDE project aims to provide a lightweight and fast desktop environment.

I wouldn't normally recommend relocating the explanation of the name
into the synopsis like this - there's more room in the long
description.  But this phrasing is more natural ("aimed to" is
unidiomatic English), and it avoids repeating "lightweight" and
"desktop environment" within the sentence...

How about just leaving out the step of explicitly saying that LXDE
means Lightweight X11 Desktop Environment, and just leaving that
implicit in the fact that you've capitalised it in the synopsis?

  Description: Lightweight X11 Desktop Environment - configuration data
  Description: Lightweight X11 Desktop Environment - core metapackage
  Description: Lightweight X11 Desktop Environment - metapackage
   The LXDE project aims to provide a lightweight and fast desktop environment.
 
>> It's not designed to be powerful and bloated, but to be usable and slim
>> enough, and keep the resource usage low.  Different from other desktop
>> environments, lxde don't tightly integrate every component. Instead,
>> lxde tried to make all components independent, and each of them can be
>> used independently with fewer dependencies.
> 
> The low utilization of resources is already mentioned (lightweight). And
> perhaps I was mentally absent in my English lessons - the verb forms don't
> fit together (at least for me).

Correct.  And there are half a dozen other less obvious bits of
non-native-speakerish English here too.

>  It's designed to keep the resource usage low, to be usable and slim.
>  Different from other desktop environments, LXDE does not tightly
>  integrate every component. Instead, all components are independent,
>  and each of them can be used on it's own with only a few dependencies.

This is better, but even with one repetition of "independent" removed
it still seems a bit redundant.  I'd suggest: 

   It's designed to be usable but slimline, keeping resource usage low.
   Unlike other desktop environments, LXDE does not tightly integrate
   every component; instead they can each be used on their own without
   many dependencies.

Or on second thoughts given that these features are then repeated in
bulletpoint form below, why not just drop the whole paragraph?

> 
>> Features:
>>  - Lightweight, runs with reasonable memory usage
>>  - Fast, rund well even on older machines produced in 1999
>>  - Good-looking, GTK+ 2 internationalized user interface
>>  - Easy-to-use, the user interface is simple, but usable enough
>>  - Desktop independent (suprise! Every component can be used without LXDE)
>>  - Standard compliant, follows the specs on freedesktop.org

This is continuing the inappropriately heavyweight level of redundancy;
bulletpoint four in particular is no surprise for people who were
paying attention to the first paragraph! 
 
> I don't understand the capitals at the beginning of each item. Typos and
> new wording included, I propose
> 
> Features:
>  - lightweight, runs with reasonable memory usage
>  - fast, runs well even on older machines produced in 1999
>  - good-looking, internationalized user interface GTK+ 2
>  - simple, easy-to-use user interface offering sufficient
>    functionality, but usable enough
>  - desktop independent (Surprise! Every component can be used
>    without LXDE)
>  - standards compliant, follows the freedesktop.org specifications

This still has awkwardly phrased bits, but in general it's a nicely
structured list of features; my version below is mainly just to apply
the d-l-e "house style".

   Features:
    * small, with low memory usage;

(We've already had "lightweight" twice)

    * fast, running well even on machines produced in 1999;

(I can vouch for this, by the way - my testbed machine is a relic from
exactly that year, and is perfectly usable with LXDE.)

    * good-looking, internationalized GTK+ 2 GUI;

(Modified to avoid the repetition of "user interface".)

    * simple and easy-to-use but full-featured user interface;

(Translated into English.)

    * desktop independent (every component can be used without LXDE);

(Not worth an exclamation mark even if we drop the middle paragraph.)

    * standards compliant, following freedesktop.org specifications.

But wait... why is this blurb being attached to lxde-common, a package
likely to be installed automatically, rather than to one of the suite
metapackages that users might be expected to start by choosing, such
as the one named lxde?

> To summarize:

Before I give my own version here's a quick review of the other
packages in the suite:

# Package: lxde-core
[...]
# Description: Meta-package for the Lightweight X11 Desktop Environment Core
#  LXDE (the Lightweight X11 Desktop Environment) is a new project aimed
#  to provide a new desktop environment which is lightweight and fast.
#  .
#  This package is a metapackage depends on the recommended core components
#  of the LXDE. It includes pcmanfm, lxpanel, lxsession, openbox and
#  xscreensaver.
#  .
#  If you just want to pick and choose the core components then feel free
#  to remove this package.

Several linguistic problems and one factual one: lxde-core doesn't
express any direct dependency on lxsession.
        
# Package: lxde
[...]
# Description: Meta-package for the Lightweight X11 Desktop Environment
#  LXDE (the Lightweight X11 Desktop Environment) is a new project aimed
#  to provide a new desktop environment which is lightweight and fast.
#  .
#  This package is a metapackage depends on the core components and
#  recommended components of the LXDE. It includes lxde-core, lxappearance,
#  lxinput, lxsession-edit, lxshortcut, gpicview, lxterminal, lxmusic,
#  leafpad and xarchiver.
#  .
#  If you just want to pick and choose the core components then feel free
#  to remove this package.

This time the list looks factually accurate, but is there any point
trying to itemise the dependencies of a metapackage?  Just describe
the function of the collection well enough that I can decide if I want
it and let the dependency fields themselves do the pointing.

Here are my revised descriptions for all the lxde packages (patch
attached):

Package: lxde-common
Description: Lightweight X11 Desktop Environment - configuration data
 The LXDE project aims to provide a lightweight and fast desktop
 environment.
 .
 This package contains common files for LXDE.

Package: lxde-core
Description: Lightweight X11 Desktop Environment - core metapackage
 The LXDE project aims to provide a lightweight and fast desktop
 environment.
 .
 This is a metapackage to install the recommended core components of
 LXDE. It is also possible to remove this package and just pick and
 choose from its dependencies.
        
Package: lxde
Description: Lightweight X11 Desktop Environment - metapackage
 The LXDE project aims to provide a lightweight and fast desktop
 environment.
 .
 Features:
  * small, with low memory usage;
  * fast, running well even on machines produced in 1999;
  * good-looking, internationalized GTK+ 2 GUI;
  * simple and easy-to-use but full-featured user interface;
  * desktop independent (every component can be used without LXDE);
  * standards compliant, following freedesktop.org specifications.
 .
 This is a metapackage to install all the recommended components of
 LXDE. It is also possible to remove this package and just pick and
 choose from its dependencies.

-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package
-------------- next part --------------
diff -ru lxde-common-0.5.5.pristine/debian/control lxde-common-0.5.5/debian/control
--- lxde-common-0.5.5.pristine/debian/control	2011-07-30 23:59:37.000000000 +0100
+++ lxde-common-0.5.5/debian/control	2011-10-13 22:58:48.748548092 +0100
@@ -16,23 +16,11 @@
 Depends: ${misc:Depends}, ${shlibs:Depends}, lxsession (>= 0.4.4)
 Recommends: lxde-core (>= ${source:Version})
 Suggests: lxlauncher
-Description: Lightweight X11 Desktop Environment configuration data
- LXDE (the Lightweight X11 Desktop Environment) is a project aimed
- to provide a new desktop environment which is lightweight and fast.
+Description: Lightweight X11 Desktop Environment - configuration data
+ The LXDE project aims to provide a lightweight and fast desktop
+ environment.
  .
- It's not designed to be powerful and bloated, but to be usable and slim
- enough, and keep the resource usage low.  Different from other desktop
- environments, lxde don't tightly integrate every component. Instead,
- lxde tried to make all components independent, and each of them can be
- used independently with fewer dependencies.
- .
- Features:
-  - Lightweight, runs with reasonable memory usage
-  - Fast, rund well even on older machines produced in 1999
-  - Good-looking, GTK+ 2 internationalized user interface
-  - Easy-to-use, the user interface is simple, but usable enough
-  - Desktop independent (suprise! Every component can be used without LXDE)
-  - Standard compliant, follows the specs on freedesktop.org
+ This package contains common files for LXDE.
 
 Package: lxde-core
 Architecture: all
@@ -41,16 +29,13 @@
  lxpanel (>= 0.5.5), openbox (>= 3.4.6.1), pcmanfm (>=0.9.8)
 Recommends: gksu, lxterminal | x-terminal-emulator, xscreensaver
 Suggests: chromium-browser | iceweasel | www-browser, lxlauncher
-Description: Meta-package for the Lightweight X11 Desktop Environment Core
- LXDE (the Lightweight X11 Desktop Environment) is a new project aimed
- to provide a new desktop environment which is lightweight and fast.
- .
- This package is a metapackage depends on the recommended core components
- of the LXDE. It includes pcmanfm, lxpanel, lxsession, openbox and
- xscreensaver.
- .
- If you just want to pick and choose the core components then feel free
- to remove this package.
+Description: Lightweight X11 Desktop Environment - core metapackage
+ The LXDE project aims to provide a lightweight and fast desktop
+ environment.
+ .
+ This is a metapackage to install only the core recommended components
+ of LXDE. It is also possible to remove this package and just pick and
+ choose from its dependencies.
 
 Package: lxde
 Architecture: all
@@ -62,14 +47,18 @@
  chromium-browser | iceweasel | www-browser, gdm | x-display-manager,
  lxmusic, menu-xdg, policykit-1-gnome, xserver-xorg
 Suggests: lxlauncher, lxtask
-Description: Meta-package for the Lightweight X11 Desktop Environment
- LXDE (the Lightweight X11 Desktop Environment) is a new project aimed
- to provide a new desktop environment which is lightweight and fast.
- .
- This package is a metapackage depends on the core components and
- recommended components of the LXDE. It includes lxde-core, lxappearance,
- lxinput, lxsession-edit, lxshortcut, gpicview, lxterminal, lxmusic,
- leafpad and xarchiver.
+Description: Lightweight X11 Desktop Environment - metapackage
+ The LXDE project aims to provide a lightweight and fast desktop
+ environment.
  .
- If you just want to pick and choose the core components then feel free
- to remove this package.
+ Features:
+  * small, with low memory usage;
+  * fast, running well even on machines produced in 1999;
+  * good-looking, internationalized GTK+ 2 GUI;
+  * simple and easy-to-use but full-featured user interface;
+  * desktop independent (every component can be used without LXDE);
+  * standards compliant, following freedesktop.org specifications.
+ .
+ This is a metapackage to install all the recommended components of
+ LXDE. It is also possible to remove this package and just pick and
+ choose from its dependencies.