Re: Bug#650111: Please rewrite package description
Martin Eberhard Schauer wrote:
[...]
>> Description: an intelligent whois client
>> This is a new whois (RFC 3912) client rewritten from scratch.
>> It is inspired from and compatible with the usual BSD and RIPE whois(1)
>> programs.
>> It is intelligent and can automatically select the appropriate whois
>> server for most queries.
>> .
>> The package also contains mkpasswd, a features-rich front end to crypt(3).
I'll explicitly mention a few English-language nitpicks before we
worry about the content:
* package synopses don't need leading articles
* s/inspired from/inspired by/
* s/features-rich/feature-rich/
* the RFC says the protocol is "WHOIS", not "whois".
[...]
> At this point I don't know why I need the package. What can it do for me?
> -> Reverse DNS lookups (2).
Apparently we're expected know all the RFCs off by heart. But no,
whois isn't for rDNS lookups, as such. I'd suggest adding a bit of
text about querying online servers for information such as contact
details for IP address assignments.
> A bit of nitpicking: Can something new be rewritten from scratch?
As opposed to "written", you mean? That didn't worry me until you
pointed it out, but I suppose not. And this version of whois is
hardly very "new" anyway, given that its changelog goes back to a past
millennium. The reference to "the usual BSD and RIPE whois(1)
programs" is an obvious sign of age, too - why would any new Debian
user consider those implementations "the usual" ones? In fact, most
WHOIS lookups these days are web-based, so it would probably be a good
idea to mention that this is a commandline tool.
> And why do I need mkpasswd? Why is it bundled with the whois client?
I can guess from the name that it "makes passwords", but calling it a
"front end to crypt(3)" leaves me none the wiser if I don't already
happen to know what crypt is - who says I have manpages-dev installed?
Yes, it's known as crypt(3) because crypt(1) is a *separate* obscure
thing I don't have a manpage for, but this is really no substitute for
an explanation. And the question of what a password-generating tool
would be doing in this package just makes it that bit more baffling
(as has been pointed out before - see #526761).
> Why is it new and why is it intelligent?
The "new" is only in comparison with an unnamed older version of no
particular modern relevance - even the WHOIS client currently
available from ftp.ripe.net is a reimplementation called "whois3",
with a changelog that stretches back no further than 2003.
The explanation of how it can claim to be intelligent, on the other
hand, is right there in the rest of the sentence; it's intelligent in
that it can automatically select the appropriate server for most
queries.
> My first draft for a new package description:
>
> Description: determines ISP names from IP addresses
> This package contains a client for the whois protocol (RFC 3912), written
> from scratch. The client can automatically select the appropriate whois
> server for most queries. It was inspired by the BSD and RIPE whois(1)
> implementations and it is compatible with them.
> .
> The package also contains mkpasswd, a feature-rich front-end to crypt(3).
No, that synopsis isn't in the DevRef-approved nounphrasey format, and
much more importantly it isn't accurate; ISPs are far from being the
only entities that IP ranges can be assigned to.
I would suggest moving the description of its features to the start of
the first paragraph, and putting the historical notes at the end.
> Unfortunately this version does not explain why the package contains
> mkpasswd.
The original RIPE version needed an equivalent tool, and it just got
carried over into this version for no good reason (or to use the
traditional euphemism, for "historical" reasons).
So here's my version:
Description: intelligent WHOIS lookup client
This package contains a commandline client for the WHOIS (RFC 3912)
protocol, which queries online servers for information such as contact
details for IP address assignments. It can intelligently select the
appropriate WHOIS server for most queries. This version is compatible
with and was inspired by the old BSD and RIPE implementations, but was
written from scratch.
.
For historical reasons, the package also contains mkpasswd, a
feature-rich front-end to the password encryption function crypt(3).
Looking at bug #184807 doesn't leave me especially optimistic, though.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: