On Mon, Jan 27, 2020 at 6:55 AM Rob Landley <[email protected]> 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 > [email protected] > http://lists.landley.net/listinfo.cgi/toybox-landley.net _______________________________________________ Toybox mailing list [email protected] http://lists.landley.net/listinfo.cgi/toybox-landley.net
