[Toybox] Fwd: Toybox 0.8.11 command help clarifications

[Rob Landley]

Permission to forward my reply to the list received, so...

On 11/12/24 12:14, Craig Poile wrote:
> Dear Rob Landley:
> 
> I'm a technical writer at QNX, a division of BlackBerry. We ship
> toybox with our SDP, and I am adapting the documentation you supply
> for our in-house documentation.

Cool.

> I am hoping to get your help with a few option descriptions that
> I don't understand. My technical knowledge is thin, but I did ask
> developers in-house about a couple of them and they were unable to help.
> 
> 1. For du, it says:
> 
> -d N       Only depth < N
> 
> What does only depth < N mean?

Hmmm, perhaps I should fluff that out a bit. If you include the header 
the help text puts above that group of options, this says:

   What to show:
     -d N       Only depth <N

Which corresponds to the Linux man page:

https://man7.org/linux/man-pages/man1/du.1.html

Which says:

        -d, --max-depth=N
               print the total for a directory (or file, with --all) only
               if it is N or fewer levels below the command line
               argument;  --max-depth=0 is the same as --summarize

I.E. while du is recursing down into subdirectories to find "disk 
usage", only output a size for directories that are N or fewer levels 
away from the command line. (Any child subdirectories are collated into 
the size of the higher levels.) This is a bit like "du -s" only showing 
a single total for each argument, except it gives you intermediate 
granularity.

I used the word "depth" because that's what -d is short for (in hopes 
the mnemonic makes it easier to remember), and didn't I repeat words 
like "show" because it's in the section header.

Would this be better?

   -d N    Combine subdirectories more than N levels deep

(Note: now that I've EXPLAINED it and you know what it MEANS, you can't 
evaluate whether it's a good explanation to the uninitiated EITHER. But 
maybe your coworkers can. :)

> 2. For find, it says:
> -newerXY  FILE   X=acm time > FILE's Y=acm time (Y=t: FILE is literal time)
> 
> What does this mean?

Again, I'm trying to crush down a LOT of info into a small amount of space.

https://man7.org/linux/man-pages/man1/find.1.html

        -newerXY reference
               Succeeds if timestamp X of the file being considered is
               newer than timestamp Y of the file reference.  The letters
               X and Y can be any of the following letters:

               a   The access time of the file reference
               B   The birth time of the file reference
               c   The inode status change time of reference
               m   The modification time of the file reference
               t   reference is interpreted directly as a time

               Some combinations are invalid; for example, it is invalid
               for X to be t.  Some combinations are not implemented on
               all systems; for example B is not supported on all
               systems.  If an invalid or unsupported combination of XY
               is specified, a fatal error results.  Time specifications
               are interpreted as for the argument to the -d option of
               GNU date.  If you try to use the birth time of a reference
               file, and the birth time cannot be determined, a fatal
               error message results.  If you specify a test which refers
               to the birth time of files being examined, this test will
               fail for any files where the birth time is unknown.

>  (Y=t: FILE is literal time)

Y=t means that FILE isn't interpreted as a filename to stat() and get a 
timestamp from, but is instead directly parsed as a time string, using 
the same set of formats understood by the "date" command.

See xparsedate() in lib/xwrap.c for the list, which tries (in order):

1) Unix time (with optional decimal fraction down to nanoseconds)

2) The libc function strptime() using the formats:

     "%Y-%m-%d %T", "%Y-%m-%dT%T", "%a %b %e %H:%M:%S %Z %Y",
     "%H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d", "%H:%M", "%m%d%H%M",
     endian ? "%m%d%H%M%y" : "%y%m%d%H%M",
     endian ? "%m%d%H%M%C%y" : "%C%y%m%d%H%M"

(That third one is the posix "C" locale format, so "actual standards 
compliance" is our fourth attempt at parsing. :)

https://man7.org/linux/man-pages/man3/strptime.3.html

If that's the only part you're confused about (not the atime/mtime/ctime 
part)... I think I tried to say something like "FILE is date string not 
filename" and couldn't fit it in 80 columns. Hmmm... (Y=t: FILE is time 
not filename) brings it to exactly 80 columns, is that clearer? Or maybe 
"FILE is date not filename"? Can't fit "date string" in the available 
space, and it's already USING a full column instead of two column 
left/right...

(The order of entries is not REMOTELY alphabetical there, it's... SORT 
of conceptually collated? But there's just no order I can put them in 
that makes anything close to sense without being completely arbitrary. 
Alphabetical scatters -atime -ctime and -mtime entries all over the 
place, nor does it have -true and -false adjacent...)

*shrug* Cheating on all cylinders...

> 3. For ls, it says:
> sort by:  (also --sort=longname,longname... ends with alphabetical)
> 
> Does "ends with alphabetical" mean that the end of the list should
> be an alphabetic character (i.e., not a comma)?

No, it means if it compared equally falling back through every sort you 
explicitly listed, it'll end by comparing the strings alphabetically as 
a tiebreaker to get a stable sort order.

This is also why alphabetical sort isn't one of the options, because two 
files can't have the same $PATH so fallback sorts after after a case 
sensitive alphabetical sort can never trigger. (Unlike case insensitive 
sort, which CAN have times and thus call fallback sorts.)

Alpha sort is the default behavior when you don't specify a sort type, 
and the other sorts are inserted before that default behavior and fall 
back to it to break ties.

Oh, another ls implementation detail here I didn't really document: if 
you specify the short options -t -u -c and so on, it doesn't do fallback 
sorts if you specify more than one, that's basically intended for one 
"sort by". The CSV codepath can do multiple fallback sorts in order...

> Sincerely,
> 
> Craig

It's good feedback that somebody reading the above for the first time 
couldn't figure out those three, I should probably rephrase them so the 
next person to do so doesn't trip over it. The question is "how" 
(without making it way way longer, the toybox --help text is supposed to 
be small and simple).

Thanks,

Rob