On Fri, May 26, 2017 at 12:23 AM, Rob Landley <r...@landley.net> wrote: > On 05/25/2017 07:59 PM, enh wrote: >> On Mon, May 22, 2017 at 7:53 PM, Rob Landley <r...@landley.net> wrote: >>> I could teach the parser to notice multiple usage lines but then how >>> would the option merging work? What would that _mean_ to the parser? >> >> your time would certainly be better spent making "top --help" work right :-) > > I have a window open on that: the first bug is that my infrastructure > had a design assumption that each block of text slotted into one place, > and the block shared by top/iotop confuses it. Requires a design change > and moving some code around. > > (It's been something like 3 days since I looked at said open window > because I got interrupted by $DAYJOB and > https://github.com/landley/mkroot/commits/master and > http://lkml.iu.edu/hypermail/linux/kernel/1705.2/05611.html and so on, > but I intend that to be in the release at the end of the month. I have 6 > days left...) > > After that I might wind up flying to Tokyo again to do GPS and SDK stuff > for a bit, and there's an automotive linux conference I may or may not > be attending (probably not but can't rule it out) > > (I also have a window open replying to Josh Gao, but it's describing the > coding I'm doing to fix it, which I haven't checked in yet. :) > > Spinning many plates. I should get my blog up to date again so people > can at least see what I did. :) > >>> One of my original design assumptions is each command should be small >>> and simple enough that you _can_ have one usage: line. What I intended >>> toybox to do and what android needs it to do have a certain amount of >>> tortion going on. (Reality's usually like that.) >> >> in the case of seq, i just find the man page's style of >> >> seq [OPTION]... LAST >> seq [OPTION]... FIRST LAST >> seq [OPTION]... FIRST INCREMENT LAST >> >> grokable, but > > That would either repeat the [OPTIONS] or not list them in the usage line. > >> usage: seq [-w|-f fmt_str] [-s sep_str] [first] [increment] last >> >> not. (and shouldn't that be "[first [increment]]"?) > > Probably. And in newer help text I tend to CAPITALIZE things that aren't > keywords. (So the keywords in stuff like "find" and "ifconfig" stand out > as keywords.) > > I need to do a help text consistency pass. It's in the "posix > compliance" and "fill out the test suite" heap, after I get proper > mkroot-based tests of ps/modprobe/ifconfig implemented... > >> even doing that >> and including the defaults seems a lot less clear to me than just >> listing the three cases >> >> usage: seq [-w|-f fmt_str] [-s sep_str] [first=1 [increment=1]] last > > It took me a moment to work out you're using =1 to specify a default > value here. I haven't seen that before, and given how many things have > name=value assignments on the command line (dd, ps, env...) it seems > potentially misleading. > >> (the GNU style of just saying "OPTIONS" might help, especially because >> it's kind of random at the moment which options get mentioned in the >> usage line.) > > They all should be. Where they're missing its a bug and I want to fix it. > > I'm trying to make the --help output be both terse and thorough, which > is HARD. Ubuntu commands' --help text... well it varies wildly: > > $ ps --help > > Usage: > ps [options] > > Try 'ps --help <simple|list|output|threads|misc|all>' > or 'ps --help <s|l|o|t|m|a>' > for additional help text. > > For more details see ps(1). > > $ ls --help | wc > 117 834 7414 > > But this is _the_ documentation I'm providing for each command. I don't > have man pages, I have --help output. I really want it to fit on one > 80x25 screen when possible but just couldn't do it for sed, ps, ls... > > Sigh. There's a conflict between "tutorial" and "reference" that comes > up a lot too. Documentation teaching you something you've never seen > before and documentation for when you already have the general idea and > are looking up some detail are different _kinds_ of documentation, and > making one thing do both is really hard. > >> but your time would certainly be better spent making "top --help" work right >> :-) >> >> speaking of kind of random, attached is a patch that makes the --help >> output more consistent about periods when describing flags (because >> the current mostly-never-but-sometimes looks weird). > > $ sed --help > --posix > disable all GNU extensions. > -r, --regexp-extended > use extended regular expressions in the script. > -s, --separate > consider files as separate rather than as a single continuous > long stream. > -u, --unbuffered > load minimal amounts of data from the input files and flush > the output buffers more often > -z, --null-data > separate lines by NUL characters > --help display this help and exit > --version output version information and exit > > Yes, clearly that can't be allowed to ship. :) > > Sigh I agree with this in principle (although I would have gone the > other way and enforced periods),
happy to go the other way too; i only removed them because the current majority was periodless. (i haven't been able to guess whether it's supposed to be "-a All the things" or "-a all the things", but if you choose a style i'm sure i'll have an afternoon where i'm waiting for something for long enough to fit in a mindless semi-automated search and replace.) > but "git am" refuses to apply to a > modified file even when the changes don't remotely conflict, for reasons > I've asked Junio Hamano about and never got a straight answer. > > When there's no actual conflict "git diff > file; git checkout -f; git > am; patch -p1 -i file" works fine. Of course my tree does have conflicts... > > Hunk #1 FAILED at 13. > 1 out of 3 hunks FAILED -- saving rejects to file toys/lsb/seq.c.rej > Hunk #1 FAILED at 8. > 1 out of 2 hunks FAILED -- saving rejects to file > toys/pending/getfattr.c.rej > Hunk #1 FAILED at 1. > 1 out of 1 hunk FAILED -- saving rejects to file toys/posix/cut.c.rej > > Sigh. And the cut.c patch is one big giant hunk for the whole file > because that's the rewrite I did way back when and no longer remember > what I did and need to review my own code as if it's an external > submission when I can find the time... > > (I also wind up with open email windows with half-written replies that I > wind up discarding because a later message rendered it moot. Swap > thrashing is inefficient.) > > But this one, I can send now. :) > > Rob -- Elliott Hughes - http://who/enh - http://jessies.org/~enh/ Android native code/tools questions? Mail me/drop by/add me as a reviewer. _______________________________________________ Toybox mailing list Toybox@lists.landley.net http://lists.landley.net/listinfo.cgi/toybox-landley.net
