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

[Rob Landley]

On 2/2/20 11:28 PM, enh wrote:
> 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.

Yeah, I can see your point. It's just a rough edge.

> 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.

ARG... means there must be one but could be more. (Entirely optional is
[ARG...]) So COMMAND... is right, it's just more subtle than I like.

I want something that concicely provides complete information to people familiar
with toybox, and also something reasonably obvious to people new to toybox. And
those goals kinda fight here. (But then they do in traditional man pages too.
I'd leverage traditional man page syntax more if it was consistent or at least
well-defined, but there's so much ad-hockery...)

>>>  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 the other problem is making it clear "this field is a number".

Maybe -n #LINES ? -n LINE# ? Hmmm... Using -n NUM consistently would let people
know it is a number (albeit not necessarily the _first_ time, but after they'd
figured it out once we'd be consistent), but it doesn't give you any info about
what the option means. (While that is what the long description is for, is it
the best way?)

> 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",

"Show this many LINES at start" or something.

But that's the the -n #LINES problem again. Field is number.

(Is there a tech writer in the house?)

> 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.)

Which is why this has remained on the todo list. (That and it's a moving target
until I've got the commands implemented to 1.0.)

> 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.

I've tried not to do that. That said, the usage: lines of ps and grep and such
do _not_ fit in 80 chars. :)

(Meanwhile, "usage: w".)

> 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.

Yeah, the help text is the only man page we've got. It's the menuconfig test,
the --help output, and the html on the website. It has to Do The Thing.

> 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?)

Benevolent dictator I expect. (Says the guy who used to _be_ said benevolent
dictator but long enough ago the old busybox and toybox policies have kinda
blended together in my head over the years. I inherited reasonable help text
from Erik Andersen, and Denys seems to have done a good job there. And not
having to edit troff to modify the help text makes it a lot easier to do small
cleanups.)

>>>  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.

Sold.

Rob