[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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

> 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”

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

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: