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

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: