Bug#679622: fim: package description review
On 20120630@10:10, Justin B Rye wrote:
> Package: fim
> Version: 0.3-beta-prerelease-1.3+b1
> Severity: wishlist
> Tags: patch
>
> The package description for fim has a few English language problems.
>
> > Package: fim
> > Architecture: any
> > Depends: ${shlibs:Depends}, ${misc:Depends}
> > Description: a scriptable frame buffer and ascii art image viewer
>
> First minor issue: DevRef says there's no need for an initial article.
Ok!
> And it's "ASCII" art (in fact I'd hyphenate it as ASCII-art to clarify
> the structure).
I prefer change to "ASCII art": capitalized "ascii" because it's an
acronym, but I prefer not to use the hyphen.
> > FIM is a highly customizable and scriptable image viewer targeted at the
> ^ xxx
> I'd like to suggest including the explanation for the name here, just
> in passing - "FIM (Fbi IMproved) is..."
Ok!
>
> "The users" has another surplus article.
>
> > users who are confortable with software like the Vim text editor or the
> > Mutt
>~
> > mail user agent (it aims to be a swiss army knife for viewing images).
>~~ ~
> Typo: s/confortable/comfortable/
>
> I would suggest using a semicolon instead of parentheses.
Ok!
>
> The term "swiss army knife" should be capitalised "Swiss Army knife".
Ok!
>
> > It is based on the Fbi image viewer (by Gerd Hoffmann), and works
> > primarily in
>
> Given that this package description doesn't give the names of FIM's
> own upstream authors, and given that anybody interested in Fbi can
> just install the Debian package, I don't think there's any point
> mentioning Gerd Hoffman here.
Yep this is misleading and unnecessary -- I remove it.
>
> > the Linux framebuffer console.
>
> For consistency, "frame buffer".
Right!
I'll propagate this to FIM's internals and documentation.
> Thanks for mentioning Linux, though;
> this is a useful warning to Debian GNU/kFreeBSD users that at least
> that functionality isn't really "Architecture: any".
Well, from source, FIM is not Linux specific, but if one compiles it
to use the Linux framebuffer, then yes.
By the way, this particular package is Linux specific.
>
> > It is multidevice : it has X support, too (via the SDL library) and it
> > supports
> > ascii art output (via the aalib library).
>
> There shouldn't be a space before that colon - but then again I would
> eliminate that clause anyway, since "multidevice" is an esoteric
> software-development buzzword that contributes nothing in particular
> to this description.
True.
> I would recommend boiling this sentence and the
> previous one down to "It is based on the image viewer Fbi, and works
> primarily in the Linux frame buffer console, though it also has
> support for X (via the SDL library) and ASCII-art output (via aalib)."
Rephrased as:
It is based on the FBI image viewer, and works primarily in the Linux
frame buffer console, though it can have X support (via the SDL library,
if configured) and it supports ASCII art output (via the aalib library).
>
> > It is capable of regular expressions based (on filename) image
> > viewing,vim-like
> ~~ ~~
> "Regular expressions based (on filename)" needs a rewrite; "vim"
> should be capitalised for consistency; and there's a missing space.
Ok.
>
> > autocommands, it offers GNU readline command line autocompletion and
> > history,
>
> "It is capable of A, B, it offers C and D, E"... this list is
> structurally unsound.
>
> > completely customizable key bindings, external/internal (if-while based)
>
> The hyphen in "if-while based" is inappropriate - FIM's scripting
> language has separate "if" and "while" structures, so what you mean
> is "if/while-based" (or maybe "with loops and conditionals").
Let it be if/while-based, for now.
>
> > scriptability (through return codes, standard input/output, and commands
> > given
> > at invocation time, initialization file), internal filename-based image
> > search,
>
> Cramming all this complexity into a parenthetical phrase has broken
> it slightly - should that be "at invocation time or in an
> initialization file"?
Well, both.
>
> > and much more features.
>
> Grammar nitpickers would insist on "many more features". I would
> suggest instead moving the word "features" to the start of this
> paragraph-long sentence and making it an explicit bulleted list.
>
> My suggested version:
>
> ! Description: scriptable frame buffer and ASCII-art image viewer
> ! FIM (Fbi IMproved) is a highly customizable and scriptable image viewer
> ! targeted at users who are comfortable with software like the Vim text
> ! editor or the Mutt mail user agent; it aims to be a Swiss Army knife for
> ! viewing images. It is based on the image viewer Fbi, and works primarily
> ! in the Linux frame buffer console,
Bug#679622: fim: package description review
Package: fim
Version: 0.3-beta-prerelease-1.3+b1
Severity: wishlist
Tags: patch
The package description for fim has a few English language problems.
> Package: fim
> Architecture: any
> Depends: ${shlibs:Depends}, ${misc:Depends}
> Description: a scriptable frame buffer and ascii art image viewer
First minor issue: DevRef says there's no need for an initial article.
And it's "ASCII" art (in fact I'd hyphenate it as ASCII-art to clarify
the structure).
> FIM is a highly customizable and scriptable image viewer targeted at the
^ xxx
I'd like to suggest including the explanation for the name here, just
in passing - "FIM (Fbi IMproved) is..."
"The users" has another surplus article.
> users who are confortable with software like the Vim text editor or the Mutt
~
> mail user agent (it aims to be a swiss army knife for viewing images).
~~ ~
Typo: s/confortable/comfortable/
I would suggest using a semicolon instead of parentheses.
The term "swiss army knife" should be capitalised "Swiss Army knife".
> It is based on the Fbi image viewer (by Gerd Hoffmann), and works primarily
> in
Given that this package description doesn't give the names of FIM's
own upstream authors, and given that anybody interested in Fbi can
just install the Debian package, I don't think there's any point
mentioning Gerd Hoffman here.
> the Linux framebuffer console.
For consistency, "frame buffer". Thanks for mentioning Linux, though;
this is a useful warning to Debian GNU/kFreeBSD users that at least
that functionality isn't really "Architecture: any".
> It is multidevice : it has X support, too (via the SDL library) and it
> supports
> ascii art output (via the aalib library).
There shouldn't be a space before that colon - but then again I would
eliminate that clause anyway, since "multidevice" is an esoteric
software-development buzzword that contributes nothing in particular
to this description. I would recommend boiling this sentence and the
previous one down to "It is based on the image viewer Fbi, and works
primarily in the Linux frame buffer console, though it also has
support for X (via the SDL library) and ASCII-art output (via aalib)."
> It is capable of regular expressions based (on filename) image
> viewing,vim-like
~~ ~~
"Regular expressions based (on filename)" needs a rewrite; "vim"
should be capitalised for consistency; and there's a missing space.
> autocommands, it offers GNU readline command line autocompletion and history,
"It is capable of A, B, it offers C and D, E"... this list is
structurally unsound.
> completely customizable key bindings, external/internal (if-while based)
The hyphen in "if-while based" is inappropriate - FIM's scripting
language has separate "if" and "while" structures, so what you mean
is "if/while-based" (or maybe "with loops and conditionals").
> scriptability (through return codes, standard input/output, and commands
> given
> at invocation time, initialization file), internal filename-based image
> search,
Cramming all this complexity into a parenthetical phrase has broken
it slightly - should that be "at invocation time or in an
initialization file"?
> and much more features.
Grammar nitpickers would insist on "many more features". I would
suggest instead moving the word "features" to the start of this
paragraph-long sentence and making it an explicit bulleted list.
My suggested version:
! Description: scriptable frame buffer and ASCII-art image viewer
! FIM (Fbi IMproved) is a highly customizable and scriptable image viewer
! targeted at users who are comfortable with software like the Vim text
! editor or the Mutt mail user agent; it aims to be a Swiss Army knife for
! viewing images. It is based on the image viewer Fbi, and works primarily
! in the Linux frame buffer console, though it also has support for X (via
! the SDL library) and ASCII-art output (via aalib).
! .
! Its features include:
! * viewing images by filename regular expressions;
! * Vim-like autocommands;
! * GNU readline command line autocompletion and history;
! * completely customizable key bindings;
! * external/internal (if/while-based) scriptability through return codes,
! standard input/output, and commands given at invocation time or in
! an initialization file;
! * internal filename-based image search;
! * and much more.
--
JBR
Ankh kak! (Ancient Egyptian blessing)
diff -ru fim-0.3-beta-prerelease.pristine/debian/control fim-0.3-beta-prerelease/debian/control
--- fim-0.3-beta-prerelease.pristine/debian/control 2012-06-29 10:21:03.0 +0100
+++ fim-0.3-beta-prerelease/debian/control 2012-06-30 09:57:40.127392507 +0100
@@ -9,17 +9,21 @@
Package: fim
Architecture: any
Depends: ${shlibs:Depends}, ${misc:
