On Sat, Feb 1, 2020 at 11:58 PM Rob Landley <[email protected]> wrote: > > On 2/2/20 12:16 AM, enh via Toybox wrote: > > This only touches 24 of the 68 toys/posix/ files --- the others were > > already canonical. > > > > Potentially contentious, so worth stating explicitly, is that there > > were 8 matches for "COMMAND..." amongst all existing help output, > > with 7 matches for various inconsistent variants involving something > > with "ARG", so I resolved that in favor of using "COMMAND..." (which > > is also shorter overall, and avoids nested []s). > > --- > > toys/posix/cal.c | 2 +- > > toys/posix/cat.c | 4 ++-- > > toys/posix/chgrp.c | 2 +- > > toys/posix/cksum.c | 2 +- > > toys/posix/df.c | 2 +- > > Hmmm, that one isn't exactly a file though? (It can be a file, but is usually > a > directory.)
there were a few interesting choices like this... my rationale was that we should say DIR if and only if it _has_ to be a directory (like mkdir/rmdir), and FILE otherwise. this seems to match POSIX. we could just always use PATH everywhere, but that's rarely used in anyone's (toybox/busybox/GNU/POSIX) existing synopses (though it is the most common choice in sections 2 and 3 of the manual!). > > toys/posix/du.c | 2 +- > > toys/posix/echo.c | 2 +- > > toys/posix/env.c | 2 +- > > Eh... grumble grumble. Not _wrong_ exactly... here i was going for consistency with our existing practice (the scores for this and the alternatives are in the commit message.) that said, GNU and POSIX both go for `COMMAND [ARG...]`. i'm happy to move everything to that instead if you prefer. this is part of why i just did toys/posix/ first, so we could see what issues it threw up that we hadn't already discussed. > > toys/posix/file.c | 2 +- > > toys/posix/head.c | 2 +- > > arg vs args isn't worse, but abbreviating "number" to "num" seems harder on > non-english speakers? (Google translate isn't going to know what "num" means.) this is the place where we're currently least consistent. for something like that, we currently have all of: 1. -n N 2. -n NUM 3. -n NUMBER 4. -n # 5. -n LINES 4 is joint shortest (and would only need explaining once, in `toybox --help`), 5 is most helpful but can sometimes be a bit awkward choosing names in a few places, and it's repetitive with the "full" list of options that comes later. (though there's another consistency issue there in that we don't always say "-n LINES\tShow first LINES lines", sometimes just saying "-n\tShow ..." instead. and if we do say we're always going for the "-n LINES" variant in the full list, there are a lot of the existing names that take us past the tab stop.) the other obvious option is the "cop out" that you see with the GNU tools where they just say something like `[OPTIONS]` and make you read the full descriptions below. a half-way house there would be to choose the "most commonly used" ones for the synopsis. but that seems fraught with the MS Word problem. want to try standardizing on 5: "short unique meaningful name"? (definitely worth writing this stuff down! i'm curious how busybox seems to be more consistent than i'm used to --- do they have written rules, or is it consistency by benevolent dictator?) > > toys/posix/kill.c | 2 +- > > toys/posix/logger.c | 2 +- > > toys/posix/ls.c | 2 +- > > In this case it often _is_ a file, so... > > > toys/posix/mkdir.c | 2 +- > > I suppose it's the DOS command, and "dirname" already wasn't easy on > translation. :) yeah, "dirname" seemed weird --- what does "name" add that you didn't already get from "dir"? "directory" would arguably be better, but i felt like that ran afoul of the usual toybox "what's the shortest thing that doesn't actually lose any information?". (alternatives: "path" would be normal for mkdir(2). "file" definitely seems a bit odd here.) also POSIX uses "dir" in this context. > > toys/posix/nice.c | 2 +- > > toys/posix/nohup.c | 2 +- > > toys/posix/patch.c | 2 +- > > toys/posix/renice.c | 2 +- > > toys/posix/rmdir.c | 2 +- > > toys/posix/tar.c | 2 +- > > toys/posix/tee.c | 2 +- > > toys/posix/time.c | 2 +- > > toys/posix/uniq.c | 2 +- > > toys/posix/uuencode.c | 4 ++-- > > 24 files changed, 26 insertions(+), 26 deletions(-) > > Sigh. Applied. > > Rob _______________________________________________ Toybox mailing list [email protected] http://lists.landley.net/listinfo.cgi/toybox-landley.net
