Re: Request for review: xz-utils package description
Hi again,
I have rewritten the package descriptions following your suggestions.
The updated version is below. I’d also like to respond to your
comments directly.
Ben Finney wrote:
> It's important *not* to say “.xz format” or “.xz file”, since that name
> is a filename suffix and, as you likely know, file names don't
> necessarily have anything to do with the format of the data within that
> file. To conflate the two makes it unclear what is expected when, e.g.,
> a ‘.xz’ file doesn't contain XZip data, or when LZMA data is in a file
> named without the ‘.lzma’ suffix.
Hmm. The upstream maintainer seems to consistently use this
formulation. For example, the source tree contains a file
doc/xz-file-format.txt “The .xz File Format, Version 1.0.4” which uses
the suffix-based language:
| 0. Preface
|
| This document describes the .xz file format (filename suffix
| ".xz", MIME type "application/x-xz"). It is intended that this
| this format replace the old .lzma format used by LZMA SDK and
| LZMA Utils.
But at one point in his suggested package description, he calls these
files “XZ compressed files”. (For reference, his suggestions in full
are included below my own below.) I had forgotten about that ---
thanks! The file format is referred to as the XZ compression format
below.
--
Package: liblzma0
Description: library for XZ and LZMA compression - runtime
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.
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.
Package: liblzma-dev
Description: library for XZ and LZMA compression - development
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.
.
The API is similar to zlib’s stream-based API.
.
This package includes the API headers, static library, and other
files needed to build software that uses liblzma.
Package: liblzma-doc
Description: library for XZ and LZMA compression - API documentation
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.
--
Suggestions from the PACKAGERS file in the source tree:
2. Package description
----------------------
Here is a suggestion which you may use as the package description.
If you can use only one-line description, pick only the first line.
Naturally, feel free to use some other description if you find it
better, and maybe send it to me too.
Library and command line tools for XZ and LZMA compressed files
XZ Utils provide a general purpose data compression library
and command line tools. The native file format is the .xz
format, but also the legacy .lzma format is supported. The .xz
format supports multiple compression algorithms, of which LZMA2
is currently the primary algorithm. With typical files, XZ Utils
create about 30 % smaller files than gzip.
If you are splitting XZ Utils into multiple packages, here are some
suggestions for package descriptions:
xz:
Command line tools for XZ and LZMA compressed files
This package includes the xz compression tool and other command
line tools from XZ Utils. xz has command line syntax similar to
that of gzip. The native file format is the .xz format, but also
the legacy .lzma format is supported. The .xz format supports
multiple compression algorithms, of which LZMA2 is currently the
primary algorithm. With typical files, XZ Utils create about 30 %
smaller files than gzip.
Note that this package doesn't include the files needed for
LZMA Utils 4.32.x compatibility. Install also the xz-lzma
package to make XZ Utils emulate LZMA Utils 4.32.x.
xz-lzma:
LZMA Utils emulation with XZ Utils
This package includes executables and symlinks to make
XZ Utils emulate lzma, unlzma, lzcat, and other command
line tools found from the legacy LZMA Utils 4.32.x package.
liblzma:
Library for XZ and LZMA compressed files
liblzma is a general purpose data compression library with
an API similar to that of zlib. liblzma supports multiple
algorithms, of which LZMA2 is currently the primary algorithm.
The native file format is .xz, but also the legacy .lzma
format and raw streams (no headers at all) are supported.
This package includes the shared library.
liblzma-devel:
Library for XZ and LZMA compressed files
This package includes the API headers, static library, and
other development files related to liblzma.
Reply to: