Re: request for review: lbzip2
ERSEK Laszlo <lacos@caesar.elte.hu> writes:
> On Tue, 6 Oct 2009, Ben Finney wrote:
>
> >> "It isn't restricted to regular files on input, nor output."
> >
> > This might be better put in (brief, please!) terms of what its
> > capability is. Perhaps:
> >
> > It can operate on streams (stdin and stdout) as well as files.
>
> This exact formulation is beside the point, as stdin and stdout can be
> perfectly redirected from regular files (and lseek() will work on
> them).
That suggestion was for improvements to the use of language, which is
exactly the point of bringing a package description to this forum for
review.
> Okay, how about we scrap the whole description and go with this:
>
> Package name: lbzip2
>
> Short desc: parallel (multi-threaded) bzip2 compressor/decompressor
Please choose one or the other of “parallel” or “multi-threaded” for the
synopsis. My preference would be for the latter, as being more precise.
“bzip2 compressor/decompressor” is awkward; better to say “bzip2
implementation” or some other simple noun. I think you said “filter”
before.
My suggestion:
fast, multi-threaded bzip2 filter program
The synopsis is a readable descriptive noun clause, not a grab-bag of
key words. The Debian package management tools allow easy searching on
the full package description; please don't cram stuff into the synopsis
just to accommodate pathological use cases.
> Long desc:
>
> For users having a multi-core computer, lbzip2 is arguably the fastest
> bzip2 decompressor for most bz2 files downloaded from the internet. (On
> dual-core computers, the 7za utility from the p7zip-full package may prove
> more efficient.)
The first sentence is trying to have a person (“users”) as subject,
which makes it clumsy as that's not its actual topic. Instead, it's a
sentence about lbzip2 on multi-core computers.
Also, “arguably” can leave the reader wondering whether you have some
special meaning of “fastest” (which, based on your earlier descriptions,
you actually don't). You can make a less equivocal statement than
“arguably”.
You probably also want to say something about both of “parallel” and
“multi-threaded” in there, to ensure the *long* description matches
searches on those terms. How about:
lbzip2 is a multi-threaded implementation of bzip2, suited for
synchronous and parallel processing. On a multi-core computer,
lbzip2 is commonly the fastest bzip2 decompressor for most bz2 files
found on the internet. (On dual-core computers, the 7za utility from
the p7zip-full package may prove more efficient.)
> lbzip2 nicely integrates with GNU tar. Even on single core computers,
> lbzip2 can speed up archiving in combination with tar, because lbzip2
> allows compression to overlap with disk usage to a greater extent than
> bzip2 does.
Justin's suggestions for this paragraph are good, I have nothing further
to add.
> What do you think?
That's a vast improvement, addressing exactly the focus a package long
description is meant for. With Justin's suggestions and mine above, I
would say the long description is ready to go.
--
\ “My business is to teach my aspirations to conform themselves |
`\ to fact, not to try and make facts harmonise with my |
_o__) aspirations.“ —Thomas Henry Huxley, 1860-09-23 |
Ben Finney
Reply to: