Re: Request for review: xz-utils package description

[Jonathan Nieder <jrnieder@gmail.com>]

Ben Finney wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:

>> Package: liblzma0
>> Description: XZ (and LZMA) format compression library
>>  XZ is the successor to the Lempel-Ziv/Markov-chain Algorithm
>>  compression format, which gives memory-hungry but powerful
>>  compression (often better than bzip2) and fast, easy decompression.
> 
> My mental parser trips on that “… gives memory-hungry but powerful
> compression …”, looking for the object (“gives compression to what?”). I
> would suggest:
> 
>     … which implements memory-hungry but powerful compression …

A file format does not really implement anything but a plan.  How
about “provides”?

Part of the problem is that the sentence is describing two things at
once.  On one hand, there is the algorithm, which has the
characteristics described, and on the other hand, there are the file
formats it manipulates.  Trying to fix that does not seem to improve
matters, though.

	XZ is the successor to the LZMA compression format.  Both use
	the Lempel-Ziv/Markov-chain Algorithm, which is characterized
	by memory-hungry but powerful compression (often better than
	bzip2) and fast, easy decompression.

Strictly speaking, the XZ format does not use LZMA1, so this is more
misleading than the previous formulation.

Hmm.

> That whole reference to “7-Zip's related format” should be
> parenthetical:
> 
>     … used by lzma. (For 7-Zip's related format, instead use the ‘p7zip’
>     package.)

Thanks.

>>  For more information on the XZ format, see the xz-utils package.
> 
> Rather than referring to a *package* for information, either refer to
> the *documentation* (somewhere), or preferably drop this altogether.

The intent was to refer to the package description (that should have
been spelled out, I know).  That is, the intent was something like
this:

	For more information on the XZ format, refer to the xz-utils
	package description.

But I do not know if boilerplate like this is good practice.  Are
package descriptions expected to be self-contained?  It might be good
for them to be, so that if a package is removed from the archive it
does not hinder the readability of other package descriptions.

The differences between the XZ and LZMA formats are not as relevant
for the library packages as for xz-utils: an administrator considering
xz-utils has to decide whether to install lzma instead, whereas there
is no LZMA format compression library to compare liblzma to.  (The
lzma-dev package only has support for decompression, and liblz does
not support the LZMA format.)  The differences between XZ and lzip
would be more relevant, but I don’t know enough to say much about
that.

> I think the synopses can be improved slightly. Since XZ is a
> “compression format”, this could work:
> 
>     Package: liblzma0
>     Description: XZ (and LZMA) compression format – runtime library
> 
>     Package: xz-utils
>     Description: XZ (and LZMA) compression format – command-line utilities
>     
>     Package: liblzma-dev
>     Description: XZ (and LZMA) compression format – development files
>     
>     Package: liblzma-doc
>     Description: XZ (and LZMA) compression format – API documentation

If I install all them all, have I installed the compression format?
How about something like this?

	Package: liblzma0
	Description: XZ (and LZMA) format compression library

	Package: xz-utils
	Description: XZ (and LZMA) format compression utilities

	Package: liblzma-dev
	Description: XZ (and LZMA) format compression development files

	Package: liblzma-doc
	Description: XZ (and LZMA) format compression API documentation

Regards,
Jonathan