[Toybox] top --help

[Rob Landley]

On 02/02/2017 04:59 PM, enh wrote:
> "top --help" doesn't include the TOP_COMMON help. and i'm starting to
> get bug reports from folks confused by this. especially because it
> makes it look like some options disappeared, and enough is genuinely
> different in toybox top that they're relying on the help. (for most
> people, this is the first time they've used the toybox top and ps,
> even though i switched AOSP master in the second half of last year.)

I hope "you can cursor left and right to change which fields it's
sorting by" and "it uses the same -o and -O syntax/names for everything
as ps" are reasonably obvious.

But yeah, I need to fix this...

> aiui from times this came up in the past, this missing infrastructure
> feature isn't easy to fix.

It's not exactly _difficult_, just just fiddly.

The help test parsing is a pile of heuristics like "paragraphs are
separated by blank lines, after you strip off the leading usage: line
(which has a recognizable prefix and format) there's one paragraph of
leading description, then if the second paragraph beginnings with - it's
usage lines that need to be collated/alphabetized, and then the
remaining text is collated in the order it appear in the config file".

Except said heuristics got tweaked a dozen times while I was
implementing, and now I not only need to drill down to the appropriate
point in the logic sticking in all the right printfs to see what it's
doing, but I should really _document_ these heuristics and make sure
they make sense.

Which means I need a large chunk of uninterrupted time (~4 hours) to
build a mental model, and those have been in really short supply
recently. (Just got off another call where $DAYJOB made sad eyes at me
about not focusing exclusively on GPS and ignoring everything else forever).

> so should we just copy & paste the common
> lines in for now? or is there a trick like what's happening with LS
> and LS_COLOR where we can just rewrite the USE_ lines to get the right
> output?

I was experimenting with having lines that just say %CONFIG_SYMBOL% and
having that be what substitutes in the other help text (I.E. manually
controlling the order), but it's one of the many half-finished things
that got backed out and abandoned because I've been swap-thrashing over
too many things this year.

Rob