Re: Request for review: xz-utils package description
Jonathan Nieder <jrnieder@gmail.com> writes:
> Having experienced many package descriptions that are hard to read,
> I do not want to subject the world to another one.
Hurrah! This in itself is an attitude that sets you ahead of many other
maintainers.
> I would like them to convey that
>
> * xz is supposed to replace LZMA Utils. Its native .xz format is
> very similar to .lzma, but it includes a few conveniences people
> tend to rely on in other formats: an integrity check and a magic
> number for use by 'file'.
This is already confusing. You'll need to differentiate between several
distinct things:
* The packages. These are named ‘xz-utils’ and ‘lzma’, yes?
* The data formats. These should be named something like “XZip” and
“LZMA”, for example; you'll need to discover what the actual names
are.
* The typical filename suffix. These are ‘.xz’ and ‘.lzma’, yes?
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.
Be clear in each instance whether you're referring to the data format,
the package name, or the filename suffix.
Can you come up with descriptions that maintain those distinctions, and
re-post them here so we can better understand and begin to inspect the
language use?
--
\ “I have a microwave fireplace in my house. The other night I |
`\ laid down in front of the fire for the evening in two minutes.” |
_o__) —Steven Wright |
Ben Finney
Reply to: