Re: Bug#672848: please reconsider package description
Martin Eberhard Schauer wrote:
> reviewing a translation of the package description (1)
I'll include it inline for easier reference:
# Description: tool to edit disk quotas from the command line
# Quotatool is a utility to set filesystem quotas from the commandline.
# Most quota-utilities are interactive, requiring manual intervention from the
# user. Quotatool on the other hand is not, making it suitable for use in
# scripts and other non-interactive situations. This is very useful to edit
# disk quotas from scripts.
> I found that
> it mixes the terms filesystem quota und disk quota. It is basically
> the upstream description (2) with the last sentence added.
>
> I'm not sure whether they mean exactly the same. I'm also unsure
> whether the average (novice) user knows the term quota.
I would expect them to know it, but the trouble is, they may well be
more familiar with the word in contexts like "achieving your quota"
(where it's a *minimum* level).
The reason for using "disk quota" is that it's the Diskquota system in
the Linux kernel - that's its name; but it's not self-explanatory on
its own, so "filesystem quotas" is an attempt to make it clearer.
Before we carry on: quotatool Recommends, but doesn't otherwise refer
to, the package quota. It would be nice if that package's description
held a canonical explanation of disk quotas, but in fact it's awful,
talking only about implementation and development history.
> As the manpage (3) describes
[...]
> the tool deals with the setting of ressource limits/limitations.
>
> As starting point for further discussion please consider my suggestion:
>
> non-interactive command line tool to limit disk usage
Good, this puts its distinctive selling point in the synopsis - "edit"
to me suggests some sort of persistent Text User Interface, which is
exactly wrong (in fact that's its competitor "edquota").
> Quotatool can both set hard or soft limits on block and inode usage and
> set and reset grace periods.
This is trying to pack in too much detail, and leaves me wondering why
it *doesn't* mention support for group quotas. In fact quotatool can
control any aspect of quotas that's supported on my system, just like
the tools in the package quota can. It would make more sense to start
with something like:
Quotatool is a utility for manipulating the Linux Diskquota system, which
sets file system usage caps for users.
Or maybe:
Quotatool is a utility for manipulating file system usage caps via the
Linux Diskquota system. It can set hard or soft limits with adjustable
grace periods on block or inode usage for users and groups.
(My patch has the short version.)
> .
> Most quota-utilities are interactive, requiring manual intervention
> from the user. Quotatool on the other hand is not, making it suitable
> for use in scripts and other non-interactive situations. This is very
> useful to edit disk quotas from scripts.
This bit was already pretty good, but being really nitpicky:
* "quota-utilities" doesn't need a hyphen;
* just how many other diskquota utilities are there, anyway?
* it says "user" when it means "admin" (only root can edit quotas);
* you can't avoid manual interaction by manually writing a script;
* that whole last sentence is particularly repetitive;
* doublespaced sentences (just a d-l-e "house style" thing).
So how about:
non-interactive command line tool to limit disk usage
Quotatool is a utility for manipulating the Linux Diskquota system, which
sets file system usage caps for users.
.
The "edquota" tool in the standard quota package goes through a text
editor; "quotatool" on the other hand can set disk quotas directly from
the command line, and is suitable for use in scripts and other
non-interactive situations.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru quotatool-1.4.12.pristine/debian/control quotatool-1.4.12/debian/control
--- quotatool-1.4.12.pristine/debian/control 2012-02-26 12:16:08.000000000 +0000
+++ quotatool-1.4.12/debian/control 2012-05-14 10:21:08.927716619 +0100
@@ -10,9 +10,11 @@
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Recommends: quota
-Description: tool to edit disk quotas from the command line
- Quotatool is a utility to set filesystem quotas from the commandline.
- Most quota-utilities are interactive, requiring manual intervention from the
- user. Quotatool on the other hand is not, making it suitable for use in
- scripts and other non-interactive situations. This is very useful to edit
- disk quotas from scripts.
+Description: non-interactive command line tool to limit disk usage
+ Quotatool is a utility for manipulating the Linux Diskquota system, which
+ sets file system usage caps for users.
+ .
+ The "edquota" tool in the standard quota package goes through a text
+ editor; "quotatool" on the other hand can set disk quotas directly from
+ the command line, and is suitable for use in scripts and other
+ non-interactive situations.
Reply to: