[Toybox] help text

[Rob Landley]

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

Rob