[Toybox] help text

[enh]

On Mon, Jan 27, 2020 at 6:55 AM Rob Landley <rob at landley.net> wrote:
>
> I think there's a missing documentation section in www/code.html or design.html
> or maybe even the FAQ: some help text rationale and/or consistency guidelines.
>
> I'm looking at readelf.c cleanup (no promises) and the -W option says "default
> in toybox". I always just say default, the in toybox part is implicit, but the
> bigger issue is I generally don't put flags that do literally nothing (and are
> merely ignored for compatibility) in the help text, on the theory the help text
> tells somebody who doesn't know how to use the command how to use the command.
> If you literally never need to set this flag, and our support is entirely
> ignoring it when it's supplied to avoid breaking scripts and such, telling
> people they _can_ say it without breaking stuff it seems more confusing than
> helpful? (It doesn't _do_ anything...)

yeah, makes sense --- if we assume that people try something first
rather than read the help text first. i can only remember one case of
the latter. someone complained that toybox didn't do something -- when
the truth was that toybox couldn't _not_ do the thing -- because
they'd only read the help.

luckily i think we're getting to a point where people expect things to
work, so hopefully that will be even less common in future... (i think
we're already seen the turnaround points for both C/C++ and the
command line as far as this is concerned. i often stumble across
fairly advanced uses that grew organically from someone who just
assumed things work, and didn't have enough trouble for me to ever
hear anything.)

(one downside is that i'd hoped that at some point we'd have a checker
compares the USE_TOY strings with the help texts and warns us about
undocumented options. but i suppose we could have some convention
equivalent to "this page deliberately left blank" that goes in the
source but doesn't appear in the --help output.)

> I thought I'd write a mailing list message about it (and let people disagree if
> they're going to), but mailing list messages get buried over time and... this is
> coding style, maybe? (There's a bit on toys/help.h the file, help text is
> mentioned in the creating-a-command checklist...)

docs sgtm, but be warned that i'm likely to send you cleanups for any
consistency rule we agree on... the lack of consistency between the
GNU-style "usage: cmd SOMETHING FILE..." versus POSIX-style "usage:
cmd something file..." say :-)

> Hmmm...
>
> Rob
> _______________________________________________
> Toybox mailing list
> Toybox at lists.landley.net
> http://lists.landley.net/listinfo.cgi/toybox-landley.net