Re: Request for review: xz-utils package description
I'm coming in late here, but my additional advice would be:
* It's hard enough keeping package names, executables, compression
formats, and file extensions straight; don't force end users to
think in terms of upstream project brandnames like 7-Zip and LZMA
Utils where it's avoidable.
* 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'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.
* Likewise you might want the short descriptions to be the same
except for a final "tools/library/development files", though
that's not essential with a small set like this.
Jonathan Nieder wrote:
> --
> Package: liblzma0
> Description: library for XZ and LZMA compression - runtime
Given that a runt-ime library is a normal one, this description has
a low compression ratio. 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...
> liblzma is a data compression library implementing the compression
> method used by XZ Utils, LZMA Utils, and 7-Zip. Programs can use
> this library to read and write compressed streams, with or without
> the metadata usually included in compressed files, and lower-level
> functions are also included to allow writing variations on the
> compressor and decompressor implementation. The native file format
> is the XZ format, but the legacy LZMA format is also supported.
This tells me lots of stuff I don't want to know and misses out the
main selling point that XZ is like an easy-to-decompress version of
bzip2.
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.
> Package: xz-utils
> Description: high compression-ratio compressor
> This package includes the xz compression tool and other command
> line tools for working with XZ compressed files. Commands provided
> include xz, unxz, xzcat, xzgrep, and so on. With the default
> settings, compression is generally on par with or a little better
> than bzip2, decompression fast, and RAM usage high during
> compression and low during decompression.
> .
> The XZ file format is similar its predecessor the LZMA format, but it
> adds some useful amenities like an integrity check and a magic number
> to allow detecting the format with the ‘file’ utility.
> .
> For compatibility with LZMA Utils, the tools in this package can also
> read and write compressed files in the older LZMA format. If a user
> installs the appropriate symlinks, they will emulate the behavior of
> the lzma, unlzma, lzcat, and other command line tools found in LZMA
> Utils. On the other hand, installing this package will not interfere
> with the functioning of the lzma, unlzma, and lzcat commands from the
> lzma package on a given system.
This has a lot more useful information to convey, but let's see if
factoring out some of it into boilerplate helps:
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? 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?
> 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?)
> 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.
> 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!
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: