[Toybox] [PATCH] Clarify fallocate help text.

[enh]

On Mon, Oct 3, 2016 at 11:19 AM, Rob Landley <rob at landley.net> wrote:
> On 09/30/2016 05:05 PM, enh wrote:
>> -l isn't optional, and fallocate accepts the same suffixes as truncate.
>>
>> (As do many other commands. We might prefer to just *not* document
>> this anyway and have to teach people that toybox [mostly] accepts
>> the same set of suffixes everywhere. dd is a place where the suffixes
>> differ, but the fix there might also be to make atollx support the
>> whole dd set.)
>
> Yeah, part of my cleanup todo list is working out what to do there. The
> problem is I've done 2/3 of that cleanup three times now, gotten
> interrupted each time, and lost track of where I was. Trying to check it
> in in smaller chunks this time around, but it's... kinda tangled together.
>
>> I did watch someone work out 3221225472 so they could supply it as an
>> argument to fallocate, though.
>
> Sigh. The shell does $((32<<20)) for you. (Oddly enough, << 10 is a
> kilobyte, <<20 a megabyte, <<30 a gigabyte, <<40 a terabyte, <<50 a
> petabyte...)
>
> I poked the busybox guys about consistently doing 64 bit math on 32 bit
> platforms ages ago, ala
> http://lists.busybox.net/pipermail/busybox/2009-January/068143.html and
> I think I posted here more recently about the "truncate -s 8g" problem
> on 32 bit hosts (argument parsing logic uses longs).
>
>> A half-way solution might be to always
>> have terminology like "-l New length (accepts usual suffixes)", rather
>> than explicitly write them out? (We're already not documenting that
>> 2K==2k, and if we do in future accept the full dd set everywhere,
>> that's two lines of help in a lot of commands.)
>
> Hmmm. Saying "prefixed number" makes sense but saying 'suffixed number"
> seems kinda awkward. Possibly I'm undercaffeinated.

(i think you're thinking "prefix" as in "SI prefix", but they're
prefixes to the _unit_. i'm saying "suffix" because that's what's
actually happening here, and because that's what the truncate help
said, and "prefix" meant something different again in that context.)

> I've tried hard to make toybox's behavior _consistent_, which in theory
> means I shouldn't to be repetitive in the help text. (I don't usually
> point out "-" means stdin or "--" terminates option parsing, for
> example.). Truncate documents them because the truncate man page
> documented them, but they're the same sufixes for any standard command
> line numerical input. (grep -A accepts the suffixes, nice -n accepts
> them... the results aren't meaningful and the range clipping would
> object, but it'll parse them first in the common codepath.)
>
> Because of that I was tempted to move the explanation to "toybox
> --help", but I don't expect most people would see it, and you've pointed
> out people don't see it as a unified whole...

"toybox --help" does seem like the least worst choice (other than
doing nothing).

hopefully we get to a point where "/bin always accepts suffixes" is as
well-known as "-" and "--". though my experience has been that they're
not as well-known as we might think.

> Really it would be nice if there was a way to indicate in the usage:
> line that this is a numerical input. Unfortunately the syntax I'm
> copying from various man pages doesn't seem to have anything like an
> official definition.

we could invent a new syntax, but we'd have to document that somewhere too :-)

>> Bug: 31638516
>
> Is there a way for me to look at these bug reports?

no. the promised "one true bug database for inside and out" still
hasn't shown up. this bug's boring though, it's just my "todo list
bug" that i raised when i saw this so i wouldn't forget.

-- 
Elliott Hughes - http://who/enh - http://jessies.org/~enh/
Android native code/tools questions? Mail me/drop by/add me as a reviewer.