[Toybox] help text

[enh]

On Mon, Jan 27, 2020 at 7:08 PM Rob Landley <rob at landley.net> wrote:
>
> On 1/27/20 9:59 AM, enh wrote:
> > On Mon, Jan 27, 2020 at 6:55 AM Rob Landley <rob at landley.net> wrote:
> > luckily i think we're getting to a point where people expect things to
> > work, so hopefully that will be even less common in future... (i think
> > we're already seen the turnaround points for both C/C++ and the
> > command line as far as this is concerned. i often stumble across
> > fairly advanced uses that grew organically from someone who just
> > assumed things work, and didn't have enough trouble for me to ever
> > hear anything.)
>
> That's always been the goal. :)
>
> I suspect I've passed the halfway point of implementing toysh, and according to
> the scripts/install.sh PENDING= line (which more or less agrees with
> status.html) that leaves:
>
> dd diff expr ftpd less tr vi wget awk sh sha512sum sha256sum unxz xzcat bc bison
> flex make nm ar gzip
>
> Of which "dd expr tr awk make gzip" are build tools that are probably the
> priority next (in the "needed to build LFS" bucket), "diff less vi" are
> development tools that are nice to have on the system but generally not used by
> the build,
>
> wget is a corner case (fetching source packages, although a read-only git that
> can clone is probably on the same level), and ftpd is kind of that and kind of
> completeness because we have ftpget and ftpput that talk to one.
>
> I should fill out sha512sum sha256sum (mostly checking source package signatures
> but I think the kernel module signing might use it?), and unxz and xzcat are to
> support .xz tarball extraction largely because I _have_ public domain xz code
> (if a bit stale at this point and in need of much cleanup).
>
> Both nm and ar are really "toolchain" (binutil and elfutils should supply both),
> but they're also low-hanging-fruit from an implementation standpoint...
>
> And of course bc bison and flex are the kernel build being stupid. All of them
> should build _after_ the base system, but the kernel needs them as dependencies
> because crazy people, and thus... sigh. (Solving the circular dependencies of
> the base system. They won't take my patches to REMOVE the dependencies, so...)
>
> Oh, and standalone toybox system bringup needs route and probably init.
>
> But actually starting to see a path to 1.0 here...
>
> > (one downside is that i'd hoped that at some point we'd have a checker
> > compares the USE_TOY strings with the help texts and warns us about
> > undocumented options. but i suppose we could have some convention
> > equivalent to "this page deliberately left blank" that goes in the
> > source but doesn't appear in the --help output.)
>
> First I've heard of it, but it shouldn't be too hard to do? (Yeah, some kind of
> COMPAT_IGNORE -x should be feasible. The plumbing to parse this stuff already
> exists in mkflags.c and config2help.c, although the two of them aren't currently
> speaking to each other...
>
> >> I thought I'd write a mailing list message about it (and let people disagree if
> >> they're going to), but mailing list messages get buried over time and... this is
> >> coding style, maybe? (There's a bit on toys/help.h the file, help text is
> >> mentioned in the creating-a-command checklist...)
> >
> > docs sgtm, but be warned that i'm likely to send you cleanups for any
> > consistency rule we agree on... the lack of consistency between the
> > GNU-style "usage: cmd SOMETHING FILE..." versus POSIX-style "usage:
> > cmd something file..." say :-)
>
> I've been doing ALLCAPS for named arguments (which is basically the shell
> capitalized $VARNAME convention) because it stands out more in the descriptions,
> ala:
>
>     usage: uudecode [-o OUTFILE] [INFILE]
>
>     Decode file from stdin (or INFILE).
>
>     -o  Write to OUTFILE instead of filename in header
>
> I was unaware there was a gnu convention? That would indeed have (mildly) argued
> against it, but:
>
>   SYNOPSIS
>        bash [options] [command_string | file]
>
>   SYNOPSIS
>        ld [options] objfile ...
>
>   SYNOPSIS
>        gzip [ -acdfhklLnNrtvV19 ] [--rsyncable] [-S suffix] [ name ...  ]
>        gunzip [ -acfhklLnNrtvV ] [-S suffix] [ name ...  ]
>        zcat [ -fhLV ] [ name ...  ]
>
>   $ help umask
>   umask: umask [-p] [-S] [mode]
>       Display or set file mode mask.
>
> It doesn't seem like it _is_ a gnu convention? (Not consistently, anyway...)

interesting. looks like the GNU command-line convention differs from
the man page convention:

~$ ls --help
Usage: ls [OPTION]... [FILE]...

but as you say, there's definitely inconsistency:

~$ ld --help
Usage: ld [options] file...

the info pages seem to use capitals where they show synopses at all:

11.1 ‘cp’: Copy files and directories
=====================================

‘cp’ copies files (or, optionally, directories).  The copy is completely
independent of the original.  You can either copy one file to another,
or copy arbitrarily many files to a destination directory.  Synopses:

     cp [OPTION]... [-T] SOURCE DEST
     cp [OPTION]... SOURCE... DIRECTORY
     cp [OPTION]... -t DIRECTORY SOURCE...

(and in that case at least, so does the GNU man page
http://man7.org/linux/man-pages/man1/cp.1.html)


so, yeah, reality is a mess. but since all of toybox is in one
executable, it seems odd for us not to be consistent.

running

  for i in $(busybox --list); do busybox $i --help 2>&1 | grep Usage: ; done

and then eyeballing the list shows that busybox manages to
consistently use capitals.

(btw, am i the only one who thinks the busybox --list output format is
more useful than the toybox one?)

> Rob