Re: Request for review: xz-utils package description
Justin B Rye wrote:
> I'm coming in late here, but my additional advice would be:
[lots of good advice]
Thanks. I’ll give it another go tomorrow.
> * I gather LZMA is Lempel-Ziv/Markov-chain Algorithm; does XZ have
> a reason for its name? (I'm not saying the package descriptions
> need to explain it, but it wouldn't hurt to include clues.)
It was just a two-letter name that wasn’t taken.
> * It'll probably be easiest if you have a boilerplate "what XZ
> compression is" summary paragraph (or two) that's in each long
> description plus a "what this package provides" paragraph each.
I am a bit uneasy about this advice. A lot of packages have
descriptions in this long boilerplate + short specifics format, and it
can be obnoxious as a system administrator trying to figure out what a
package is. Most of the boilerplate is only useful for some of the
packages, and it does harm by making the others promise by their
length to be more useful descriptions than they actually are.
But anyway, it benefits no one for a single package’s description to
break with convention.
> I would suggest something like
>
> XZ-format compression library
>
> except that I'm a bit baffled at the fact that the library for
> XZ-as-opposed-to-LZMA is liblzma0...
I think the library is named after the algorithm; not sure, though.
Originally, the XZ format was going to be called LZMA2, and its tools
would share the interface (including file extension) of the old LZMA
tools. This makes some sense, since they’re not all that different.
Unfortunately, as LZMA2 was being developed, the LZMA format got
greater adoption, and eventually it became clear that if the lzma
command produced files by default that could not be decompressed with
the older versions, this would break a lot of existing practices. The
name change allows moving forward with the new format without breaking
compatibility, but in a sense it is a compromise.
The library supports the LZMA format, too, of course.
> What I was thinking (based on the old version) was:
>
> The Lempel-Ziv/Markov-chain Algorithm gives memory-hungry but powerful
> compression (often better than bzip2) and fast, easy decompression.
> .
> The native format of liblzma is XZ; it also supports raw (headerless)
> streams and the older LZMA format used by lzma, but not 7-Zip's related
> format (see the package p7zip). Advantages of XZ include:
> [bulleted list goes here?]
> .
> This package provides the shared library.
Looks good --- I don’t think the new version adds anything useful to
that. The only advantages of XZ over LZMA that I think need
mentioning are the crc32 and the magic number (I was very surprised to
learn the LZMA format lacked both).
> XZ-format compression utilities
> The Lempel-Ziv/Markov-chain Algorithm gives memory-hungry but powerful
> compression (often better than bzip2) and fast, easy decompression.
> .
> This package provides the command line tools for working with XZ
> compression, including xz, unxz, xzcat, xzgrep, and so on. They can also
> handle the older LZMA format, and if invoked via appropriate symlinks
> will emulate the behavior of the commands in the lzma package.
>
> Am I getting that right?
Yes, that’s right. (It can emulate the behavior of some commands
included in the lzma package in other distributions but not Debian,
too, but that seems like too small a detail to mention.)
> Are users expected to create their own
> symlinks from ~/bin/lzma to /bin/xz etwhatevera, or is it in the
> postinst? And how will it _not_ interfere with the functioning of
> "lzma" if I've changed what executable the command name invokes?
Users are expected to create them if needed (or the system administrator
can create them in /usr/local/bin). This is temporary, though:
eventually, there will be an xz-lzma package installing them in
/usr/bin and conflicting with lzma. That is not possible yet because
the lzma package is part of the base system through dpkg’s dependency
and so cannot be removed.
> > Package: liblzma-dev
>
> This needs a description that's just a slightly tweaked copy of
> liblmao0's, so I'll ignore it for now. (Or given that this one's
> for compression developers, might it want an extra "technical
> details" paragraph?)
Maybe the information I put in the liblzma0 description (that it
operates on streams, not files, and --- well, I think, though I should
check this --- that it exposes enough low-level details to allow for
an alternative implementation) could go in such a paragraph. It’s not
too important, since the developer with such poor Internet
connectivity as to have to learn about libraries from their package
descriptions seems to be a rare breed.
> > Package: liblzma-doc
> > Description: library for XZ and LZMA compression - API documentation
>
> Insert some boilerplate.
>
> > This package contains a reference manual for the liblzma data
> > compression library, in Doxygen-generated HTML files. The purpose
> > of each struct, macro, and function in the public interface is
> > explained here, but for an overview of this zlib-style interface, one
> > would have to look elsewhere.
>
> That "one would have to" is a rather starchy way of putting it, but
> it'll do.
Maybe something more constructive, like “see zlib-doc”, would be more
reasonable. Unfortunately, the zlib HTML documentation doesn’t seem
to be packaged.
> > Suggestions from the PACKAGERS file in the source tree:
>
> I hadn't realised this was going to be such an epic-length .sig...
> sorry, I'm running late, I'll read it _after_ I've sent this!
Sorry about that. Looking around at the list archives, I noticed that
messages often seem to include the payload after a .sig marker. What
is the purpose of doing that, in general?
Thanks again for your thoughtfulness.
Sincerely,
Jonathan
Reply to: