Package: awesome
Version: 3.4.12-2
Severity: wishlist
Tags: patch
Surprisingly for such a relatively mature and high-profile package,
awesome has several typos and grammar/usage problems in its package
description. Currently:
> Description: highly configurable, next generation framework window manager
> for X
^^^^^^^^^^^^^^^ ^^^^^^^^^
^^^^^
It's all grammatical, but while I'm editing things I would also
suggest changing this synopsis, for three reasons.
1) If you're not going to mention dwm, "next generation" conveys only
"it was newer than something or other else when we wrote this" (or
possibly "I'm a huge fan of eighties scifi serials").
2) This "framework window manager" jargon was specifically invented
to refer to awesome, so it's not helpful for uninitiated readers.
Even after reading the docs I'm not sure what it means - is it
saying its layouts are based on a system of "frames", or that
awesome is a window manager that provides a metaphorical framework
for doing everyday work, or is it a garbled attempt to say that
awesome is a "window management framework"?
3) How many window managers are there in Debian that aren't for X?
> Highly configurable window manager for X. It is primarly targeted at power
Sentence fragment. Besides, "highly configurable" was the one thing
I was certain belonged in the short description, so it would be nice
if the long description could start some other way.
Typo: s/primarly/primarily/
What's missing here is any hint at what general family of window
managers awesome falls into - floating, or tiling, or what? The man
page is relatively informative...
> users, developers and any people dealing with every day computing tasks and
^ ^^^^^^^^^^ ^
(I'll also push it towards the debian-l10n-english "house style" and
insert a "Harvard" comma here.)
"Any people" is subtly non-native-speakerish; maybe you were trying
to avoid "anybody" (and the taboo against "singular they"). "Users"
would fit, but it's repetitive. Personally I'd just say "anyone"
and to hell with the taboo, but there are alternatives - for
instance "and all those dealing with..."
Typo: s/every day/everyday/
> want to have fine-grained control on its graphical environment.
^^^^ ^^^^^^^ ^^ ^^^
More grammar problems:
* it's either "and wanting" or "who want";
* less urgently, the "to have" is redundant; if they want to have
control, they want control;
* "on" is the wrong preposition (it's control "over" a thing);
* what's the antecedent of "its"? The window manager? The version
of this text on the awesome home page has "theirs" (presumably a
typo for "their"), which implies the answer is the "people".
(I could complain at this stage that this is verging on false
advertising - awesome *isn't* for random non-developers who just want
a configurable WM; it's for users who can casually learn a new
object-oriented programming language, and that pretty much rules out
arts graduates like me. But since it goes on to feature Lua
prominently in the next paragraph I won't bother.)
> .
> awesome is very extensible and programmable using the Lua programming
> language.
^^^^^^^ ^^^^ ^ ^^^^^^^^^^^^ ^^^^^^^^^^^
Each of the first three paragraphs starts with the name "awesome".
This isn't an advert, so you don't need to keep repeating the brand
name so much.
Add another comma (to keep the "very" associated with "extensible"
instead of applying to "programmable" as well). I would also suggest
changing "very" to "highly".
Repetition of "program*"; either call awesome "scriptable" or call
Lua a "scripting language" (but not both).
> It provides an easily usable and very-well documented API to configure and
^^ ^^^^^^^^^^^^^ ^^^^^^^^^
Another unclear antecedent: is "it" awesome or Lua? If it's awesome,
say "providing"; if it's Lua, say "which provides". Oh - the upstream
version has "we"! In that case go for the former.
"Easily usable" would be more natural as "easy-to-use"; on the other
hand "very-well documented" has a surplus hyphen.
> define the behaviour of your window manager.
^
Standardising towards en_US, so s/our/or/ - to match the man page!
Throwing in a second person pronoun now seems odd after this
description has referred to the various kinds of user in third person
and tied itself in knots to avoid "singular they". Why not just "to
define its behavior"?
> .
> awesome also supports tiled window management, multi-head, use XCB instead
> of Xlib for better performance, does not need mouse (can be fully keyboard
> driven) and implements many of the Freedesktop standards.
All of these features need tweaking in one way or another.
* Saying that awesome "also" supports tiled window management is
strange when there has been no mention of what its *primary*
layout mode is (and even stranger when most of the reviews I find
on the Internet claim that it's *mainly* tiling).
* "Multi-head" doesn't have a verb. If it follows on from
"supports", that's slightly unidiomatic ("has multi-head support"
would be okay, but a bit jargonish).
* "Use XCB" should be "uses".
* There's a missing article in "does not need mouse"; the
parenthesised bit doesn't fit very well, and uses "fully" where I
would recommend "entirely".
* Again I'd insert a Harvard comma, or maybe semicolons all through.
* "Many of the Freedesktop standards" is vaguely oddly phrased. Try
dropping "of the".
> It also use tags instead of workspace, which gives better flexibility on
^^^^
"Also" was how you introduced the last list of features - it's
beginning to give the impression of a poorly planned string of
afterthoughts. Online reviews say this is one of awesome's most
significant selling points, so it should probably be promoted to the
start of the list (followed by the one about mouse-free operation).
"On" is the wrong preposition again - you probably want "in".
> windows display.
"Windows display"? I assume this is "the display of windows"; you
could phrase that as "window display" (no need for plural marking on
an attributive noun), but I would recommend "flexibility in
displaying windows".
> .
> Remote control is possible via D-Bus.
Why does this get a paragraph to itself instead of being in the list?
Why would end users particularly care that it's implemented using
D-Bus? And come to that, when it says "remote control", does that
mean "with a Wiimote", or "over SSH", or what? The answer appears to
be that it's "remote" in the sense of inter-process communication,
in that awesome-client provides a CLI which can generate virtual
keypresses and suchlike over a socket connection.
My tentative recommended version is:
| Description: highly configurable X window manager
| awesome manages windows dynamically in floating or tiled layouts. It is
| primarily targeted at power users, developers, and all those dealing with
| everyday computing tasks and looking for fine-grained control over their
| graphical environment.
| .
| It is highly extensible and scriptable via the Lua programming language,
| providing an easy-to-use and very well documented API to configure its
| behavior.
| .
| awesome uses tags instead of workspaces, which gives better flexibility
| in displaying windows, and can be entirely keyboard-driven, not needing a
| mouse. It also supports multi-headed configurations; uses XCB instead of
| Xlib for better performance; implements many freedesktop standards; and
| can be controlled over D-Bus from awesome-client.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru awesome-3.4.12.pristine/debian/control awesome-3.4.12/debian/control
--- awesome-3.4.12.pristine/debian/control 2012-06-13 09:56:04.000000000 +0100
+++ awesome-3.4.12/debian/control 2012-07-08 20:26:39.751392353 +0100
@@ -13,19 +13,18 @@
Recommends: x11-xserver-utils, rlwrap, feh
Depends: ${shlibs:Depends}, ${misc:Depends}, menu, dbus-x11
Provides: x-window-manager
-Description: highly configurable, next generation framework window manager for X
- Highly configurable window manager for X. It is primarly targeted at power
- users, developers and any people dealing with every day computing tasks and
- want to have fine-grained control on its graphical environment.
+Description: highly configurable X window manager
+ awesome manages windows dynamically in floating or tiled layouts. It is
+ primarily targeted at power users, developers, and all those dealing with
+ everyday computing tasks and looking for fine-grained control over their
+ graphical environment.
.
- awesome is very extensible and programmable using the Lua programming language.
- It provides an easily usable and very-well documented API to configure and
- define the behaviour of your window manager.
+ It is highly extensible and scriptable via the Lua programming language,
+ providing an easy-to-use and very well documented API to configure its
+ behavior.
.
- awesome also supports tiled window management, multi-head, use XCB instead
- of Xlib for better performance, does not need mouse (can be fully keyboard
- driven) and implements many of the Freedesktop standards.
- It also use tags instead of workspace, which gives better flexibility on
- windows display.
- .
- Remote control is possible via D-Bus.
+ awesome uses tags instead of workspaces, which gives better flexibility
+ in displaying windows, and can be entirely keyboard-driven, not needing a
+ mouse. It also supports multi-headed configurations; uses XCB instead of
+ Xlib for better performance; implements many freedesktop standards; and
+ can be controlled over D-Bus from awesome-client.
