It's time to explain "toybox help text indentation policy". Like the coding style section of code.html, only end-user visible! Yeah yeah, "watching paint dry" levels of thrilling, but I do try to get this right. Consistency helps comprehension, and we don't give people a LOT of documentation so what's there has to work hard.
Most toybox help text has one tab between command line short options and their descriptions. (acpi, base32, base64, blkid, bunzip2, cal, cat, chgrp, chown, cksum, cmp, comm, cmp, df, dmesg, du, echo, env, expand, factor, file, flock, free, fsfreeze, fsync, ftpget, getconf, gpioget, gpioset, gunzip, reboot, halt, poweroff, head, help, host, hostname, httpd, hwclock, i2cdetect, i2cdump, i2cget, i2cset, i2ctransfer, iconv, id, install, ionice, iotop, kill, killall, killall5, ln, logger, login, losetup, lsattr, lspci, lsusb, md5sum and friends, microcom, mkdir, mknod, mkpasswd, mktemp, mount, mountpoint, mv, nbd-client, nbd-server, netcat, netstat, nl, nproc, nsenter, od, oneit, paste, pgrep, pidof, pkill, pmap, printenv, pwd, readlink, rm, rmmod, seq, setfattr, setsid, sha3sum, shuf, sntp, sort, split, strings, su, swapon, switch_root, sysctl, tail, taskset, tee, time, top, touch, truncate, tty, tunctl, umount, uname, uniq, unshare, uptime, uudecode, uuencode, vmstat, watch, watchdog, wc, which, xargs, xxd, zcat) Some commands use TWO tabs (basename, blkdiscard, blockdev, fmt, mix, ping, shred) when things like -s SUFFIX are longer than 8 columns so everything gets bumped rather than having a misaligned column. Some commands (test, ls, ps, inotifyd, tar, ulimit) with a lot of options to get through use a multi-column display, which has two spaces after each option. Note that when "inotifyd" does this what it's documenting ISN'T single character short options starting with a dash, and "tar" cheats because "tar xvzf" doesn't require a dash, so tar --help doesn't put a dash on its (multicolumn) initial option display, which has two spaces. (While "ps" could similarly cheat, I didn't and I haven't actually implemented the BSD style options yet, although the plumbing in lib/args.c is there to distinguish "ps ax" from "ps -ax". It can't handle "ps a -a" but neither can debian's ps, it gives an error if you do that.) Some commands (chattr, chrt, cp, cpio, date, echo, hexedit, ifconfig, makedevs, patch, readelf, rmdir, route, rtcwake, sed, sh, stat, timeout) have a single tab section for "standard" command line short options, and then a two space (or two tab!) section that's either multicolumn or for things that aren't command line sort options, or other generally weird bit usually at the end. Note that "date" uses single space because it's a bit short on horizontal space in 80 columns, but also the %X escapes are very regular. The real issue is some entries have only a single space on the RIGHT before the next column, and having two spaces between "%e day" makes that stand out and looks worse than just one.) There's similar single spacing in the "sed" help, which is the longest help text in the entire project, and inherently kind of of overwhelming. The help text for "find" is just nuts, it cheats extensively: it uses two tabs in the first column, and one tab in the second column, because everything is a --longopt and commands are grouped semi-arbitrarily. They're not remotely alphabetical, they're KIND of grouped by function, and sort of grouped-ish by what argument they take after the option, and really I just did the best I could to make it all line up and fit in the space. And then at the end it's got "%a blah" with two spaces. Oh, and you notice how one help text entry WOULD have only one space before the third column and instead I left a GAP in the third column? Yeah, that one's all over the place. Suggestions welcome. That one's help text is held together by spackle. The help text for "dd" is also nuts, but then dd's command line options ARE nuts. There is no sane way to explain dd's command line options because they're not, and posix still thinks it should handle ebcdic, and some years ago people on this list were honestly trying to convince me that the posix dd specification was IEEE's version of the IETF April Fools RFC's, and not meant to be taken seriously. I don't apologize for that one, it's the least bad I could manage. Some minor cheats: "free" doesn't give -b -k -m -g individual lines and "rm" does this with -rR, "patch" punts on the longopt alignment where "readelf" leaves a blank space, which is preferable? (TODO question, that. See also rmdir, and timeout, and... half the group starting with "chattr" above) "ps" ends with a "Which FIELDs to show." section that's single column and COULD be tab spaced, but having that at the end instead of the beginning would be weird and moving it... peer pressure gain. Works in context. The "grep" help text is possibly wrong. It has 31 commands and is weird-because-long, but possibly that first section (both options of it) should be single tab indent? Except once upon a time -e and -f were on the same line (multicolumn!), so that having tab indents was out and everything being two spaces was eh, close enough, even though the "file search:" section is one column and could be a second section of tab indents. Then when -e and -f got rephrased and didn't fit anymore, but everything ELSE being single space kinda did a peer pressure thing. The "file search" section also _wants_ to be multiline but I can't figure out how to phrase it tersely enough, and the capitalization of the section names is inconsistent with other commands... "mcookie". "modinfo", "openvt", "passwd", "pwgen", "realpath", "uclampset", "wc", and "wget" are all just wrong, and I should fix them. And "renice" only has a usage: line, it needs documenting. And "rfkill" needs... something. As does "vconfig". (Fixing pwgen: --longopt synonyms usually go at the end of the line (in parentheses) so no need for a TRIPLE INDENT to make room for them, and -r is just wrong, it should be [-r CHARS] in the usage and then -r CHARS\t in the list, which fits in one tab. And then there's the --no-capitalize --no-numerals command pairs that I really should figure out a good way for lib/args.c to represent automatically, maybe the [-cA][-n0] blocks at the end could create a --no-thingy option for the "switch off" short opt in the pair if it hasn't already got one? Hmmm. Throw it on the todo heap.) Some dubious things jumped out at me doing a review of "for i in $(toybox); do toybox --help $i | less; done" and then hitting q a lot, like "usage: nice [-n PRIORITY] COMMAND..." not actually having a -n line in the help text. (I mean, the text describes what -n does, it's not WRONG...) And "ulimit" should have "section labels:" rather than just an unexplained blank line, but I don't know what to CALL the sections (the second group is what specific limit(s) to show or set, the first group is control stuff). Some commands are one tab instead of two tab because they don't stick the argument NAME in between the short opt and the description. (setfattr and sha3sum don't but then shred does, and then shuf and sntp don't again...) Probably needs a look over everything to see which is doing what, and whether to convert them all to one style or the other. Also, some commands still have lowercase argument names in their usage: line and should be converted to the new style. I'm annoyed by "usage: ???sum [bcs] [FILE]..." but don't have a mechanism to swap in the current command name there. I feel I _should_ have such a mechanism, and may need to try to address that. It comes up in a number of shared commands (chgrp/chown, reboot/halt/poweroff, egrep and fgrep just claim to be "grep", prlimit claims to be ulimit... basically grep for OLDTOY in toys/*/*.c and then grep -v pending, and that's the ones that might need examining.) Sigh, throw it on the todo heap... I should try to describe "tac" vs "rev" better... Anyway, there should probably be a section in code.html or design.html or something explaining all that. Why the help text is like it is. Rob _______________________________________________ Toybox mailing list Toybox@lists.landley.net http://lists.landley.net/listinfo.cgi/toybox-landley.net