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), 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 _______________________________________________ Toybox mailing list Toybox@lists.landley.net http://lists.landley.net/listinfo.cgi/toybox-landley.net
