[Toybox] help text

[enh]

On Fri, Jan 31, 2020 at 6:58 PM Rob Landley <rob at landley.net> wrote:
>
> On 1/31/20 2:54 PM, enh wrote:
> > so, yeah, reality is a mess. but since all of toybox is in one
> > executable, it seems odd for us not to be consistent.
>
> No point implementing the command line again if we can't do a better job. :)
>
> > running
> >
> >   for i in $(busybox --list); do busybox $i --help 2>&1 | grep Usage: ; done
> >
> > and then eyeballing the list shows that busybox manages to
> > consistently use capitals.
>
> I'm all for consistently using capitals in the help text.
>
> These days there's FLAG() macros, I consistently use GLOBAL variable names that
> are the same as the option that populates them, the usage: line isn't
> capitalized, there should be a comment above the NEWTOY() when the order of
> flags matters because the parse logic's being fiddly... (And I don't alphebetize
> options in there so much as group similar types together so I can have fewer
> variable declaration lines...)
>
> There should probably be a documentation section on all this, just dunno if it's
> in code.html, design.html, FAQ.html, cleanup.html... (Maybe there should be a
> docs.html I try to shuffle all of it into? Hmmm...)

i certainly always have trouble with
http://landley.net/toybox/code.html#lib_args --- the ^ and ? that you
explained recently come _after_ a section on globals. it might be
helpful if it was on a page on its own, so it's clear where the
relevant stuff starts and ends. (or just better html formatting of
that page. if you're paying enough attention, there are the filenames
there already. but i've misread that page numerous times.)

more examples might help too. your explanation of ^ versus ? on the
list was more helpful.

or, to your point here, yes, maybe a "how to get the command-line
parsing and help right" how-to type document would be more useful for
that purpose than the current "read the source walkthrough, which
actually serves multiple purposes".

> > (btw, am i the only one who thinks the busybox --list output format is
> > more useful than the toybox one?)
>
> toybox hasn't got a --list, it treats any unrecognized -- as --long. (Leftover
> from back in the days I was trying to squeeze out every byte and going "the
> multiplexer is in every command". I should probably fix that since "simple"
> implying "consistent" has risen above "small" in the goal list. Assuming the
> change won't break somebody's install script...)
>
> Note that "busybox --help" and "busybox" produce the same output, but "toybox
> --help" and "toybox" don't. The busybox without arguments version is
> gratuitously hard to parse; it's got --help info followed by a list with commas
> which screw up "for i in $(toybox); do echo $i; done" even if you chop off the
> right magic number of leading lines.
>
> I explained this to Denys when I met him in person at CELF in 2010
> (http://lists.busybox.net/pipermail/busybox/2010-April/072078.html) and he added
> a --list that produced script consumable output saying in the commit comment it
> was because I asked him to:
>
>   https://git.busybox.net/busybox/commit/?id=5a7c72015c05
>
> Space vs newline is the same as far as most consumers are concerned (the above
> for loop doesn't care), and fitting more on the screen seemed easier on humans
> to me?
>
> That said, adding a "type --help" prompt to "toybox walrus" might be useful, or
> just specifically checking for long so "toybox --list" tells you to run "toybox
> --help". (If you really want --list to be ignored and thus produce the
> toybox-with-no-args output, I can do that? Or do you think the one command per
> line version is superior...?)

i suspect i'm not the only one who didn't know that the existing
`toybox` output is usable in something like `for i in $(toybox) ...`,
whereas the `busybox --list` output is obviously usable.

(i never know with these things. on the one hand, i spend a lot of my
time explaining "obvious unix stuff" to others, but then wasted a
bunch of time this week paying the price for never having bothered to
learn the difference between [ and [[ in the shell. it's like the old
thing about everyone uses 1% of MS Word, they just all use a different
1%... i have no idea here whether the current output fools other
people into thinking they need to use tr or whatever before they can
use it, but until you said a while back that IFS takes care of this it
hadn't occurred to me.)

> >> Rob
>
> Still Rob