Re: Clarification plan for apt-listbugs filtering options

On Sun, 16 Sep 2012 22:27:10 +0100 Justin B Rye wrote:

> Francesco Poli wrote:
> [...]
> >  * -S <state> | --stats <state>
> > 
> >   Filter bugs by pending-state, showing only the bugs matching a
> >   specified value. List the pending-state categories that you want to
> >   see, separated by commas and in the desired order. Default:
> >   [forwarded,done,pending,pending-fixed]. Possible values are:
> 
> Oh, "in the desired order"!  Another esoteric feature;

Really, I myself hadn't realized at first that the order was significant
(please recall that I adopted the package: I am not the author of this
part of the code...).

> so the default
> order is significant (and strange).

It looks strange to me too.
That's why I am planning to change it (as you certainly saw, while
reading the second part of my plan).

> I wouldn't have been able to work
> that out without your footnote; telling users to list filters "in the
> desired order" is too close to telling them to list them "in whatever
> order they like", and doesn't clearly imply that it affects the order
> of the output.  I don't want to keep making this longer and longer;
> maybe you could say:
> 
>     Filter (and sort) bugs by pending-state, showing only the bugs
>     matching specified values. List the pending-state categories that
>     you want to see, separated by commas and in the desired order.
>     Default: [forwarded,done,pending,pending-fixed]. Possible values are:

I think that this is more than adequate to clarify how the option works.
I've just updated my "plan": thanks a lot for your accurate help!

> 
> [...]
> > Second part (to be implemented after wheezy is out)
> > ---------------------------------------------------
> [...]
> > Change the output of "apt-listbugs -h", so that it says:
> > 
> >  -s <severities>  : Filter bugs by severities you want to see (or "all")
> >                     [critical,grave,serious].
> >  -T <tags>        : Filter bugs by tags you want to see.
> >  -S <state>       : Filter bugs by pending-state categories you want to see
> >                     [pending,forwarded,pending-fixed,fixed,done].
> >  -B <bug#>        : Filter bugs by number, showing only the specified bugs.
> 
> Should that be <states> plural?

Probably, yes!
Then it should be plural in the man page, as well, shouldn't it?

I've updated my plan accordingly.
Thanks again!

> 
> Otherwise my only remaining concern there is a typographical nitpick -
> anglophone styleguides don't approve of whitespace before colons,
> which means we don't get to use that neat floating colon setup.  It
> would have to be:
> 
>    -s <severities>: Filter bugs by severities you want to see (or "all")
>                     [critical,grave,serious].
>    -T <tags>:       Filter bugs by tags you want to see.
>    -S <states>:     Filter bugs by pending-state categories you want to see
>                     [pending,forwarded,pending-fixed,fixed,done].
>    -B <bug#>:       Filter bugs by number, showing only the specified bugs.
> 
> (On the other hand, now that I'm used to it, I personally think the
> floating-colon approach looks good,

I also feel that it can be left as it is.

> and it presumably means less work
> for translators...)

Well, maybe, but I am not sure.
Take into account that it's done manually, so translators should be
careful and keep the alignment of colons consistent across the various
translated strings.
Since I've already fixed the alignment multiple times, I am planning to
add appropriate note to TRANSLATORS about this (once again, after
wheezy is out)...

-- 
 http://www.inventati.org/frx/frx-gpg-key-transition-2010.txt
 New GnuPG key, see the transition document!
..................................................... Francesco Poli .
 GnuPG key fpr == CA01 1147 9CD2 EFDF FB82  3925 3E1C 27E1 1F69 BFFE

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iQIcBAEBCAAGBQJQV15tAAoJED4cJ+Efab/+pqcP/RG3eJFTa0jwjZd7ls6uMKvf
ayO6kkaqI9VYlIlVS+kTZCcPng3kaLYPoL5aKRFoQWIGLcOE0q+xzGFXFAZJqqB5
e5NtjSezOUWBZTDpVuGrlusRMl/AQuZxDmh3M0SoDz7mrs5S9kFKvIwTXwdhaNgQ
yCwmpzikh4sR0oWuc8sbQHLqXLD6fWTzEzxgont4fYnjbUTVz8P7T+zU2eX69/A5
sPkuukjejwguoI53XGLaMP2vo04SEs/Nrs+8uhd4kVdqK5krn4igitkLLVLsaYK/
jMGt3hM8Wj38lg5HI5NFEa9kVKes7kkHjZkb/0Tu0y5aYxzGmY3JoErzVKUvSXXe
Z/oNYSPzw79gp28H0Y6CO5iOv6Er647PYil6z1+yFTCZUBBYokWxjFDTXwaulGQx
NBP3ZVkjLNcGY3vgIPWh5Xlk9mdGwS8uuqbekle6Jzh4njlddptn20gKXGSYtCgB
4uOELoVeLmAWEUuZCjmBfSFu2ZGI+2rIn5BNffVXee+bAug1wsVbeEeBMrr+wU0M
9z0XoKluAvO6PkMX2P2hpOsnQduRJ6jTTgo5aXTDAhL/IcKuDlYyg+25h3TE/9SM
07krfauVCLy77cmjgajv1uqvRqlRkcehdXjPSmMnwcIPGk2amy0xS3bRkDScQgoS
crH38tlz3jbGMsTTR8v5
=9rdy
-----END PGP SIGNATURE-----