[Toybox] [PATCH] Canonicalize the usage: lines for the POSIX toys.

[enh]

On Sat, Feb 1, 2020 at 11:58 PM Rob Landley <rob at landley.net> 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