search

skarnet / s6

The s6 supervision suite.
https://skarnet.org/software/s6/
ISC License
777 stars 35 forks source link

Philosophy on command line built in help `--help` #23

Closed berney closed 3 years ago

berney commented 3 years ago

I really like s6. I strive to use it, but I do sometimes struggle at times.

I note that all the tools only have terse usage built in. For example s6-svc:

alpine312:~$ s6-svc --help
s6-svc: usage: s6-svc [ -wu | -wU | -wd | -wD | -wr | -wR ] [ -T timeout ] [ -abqhkti12pcyroduxOX ] servicedir

IIUC --help doesn't exist, and its just the error in usage triggering the output. The meaning of -a, or -wu etc isn't in the output.

Contrast to another tool like service (Alpine Linux):

alpine312:~$ service --help
Usage: rc-service [options] [-i] <service> <cmd>...
   or: rc-service [options] -e <service>
   or: rc-service [options] -l
   or: rc-service [options] -r <service>

Options: [ cdDe:ilr:INsSZChqVv ]
  -d, --debug                       set xtrace when running the command
  -D, --nodeps                      ignore dependencies
  -e, --exists <arg>                tests if the service exists or not
  <snip>

I don't use s6 or skalib suite tools all the time and I'm quite forgetful. I need to google the documentation to do simple things because its not clear from commands what they do without the memorising or looking up the documentation. Which is fine. I'm just curious on the rational behind it. Is it purely to minimise the file size and, programming complexity, a separation of concerns, or something else?

I know in alpine I can install the s6-doc package which has HTML documentation, and there's an on-going effort to port man-pages in https://github.com/flexibeast/s6-man-pages, which includes s6-svc. These are what I need for a self-contained system to avoid going online.

skarnet commented 3 years ago

All of the above, plus an attempt to be maximally portable: you need the getopt_long() function in order to parse it, this is a GNU extension, this is not standardized and I'd like to avoid relying on extensions wherever possible (skarnet.org software still works on old and esoteric systems and there's no real reason to break it). Plus getopt_long() is a lot of code and cumbersome to use. Also, I'm lazy and don't like to duplicate documentation. Virtually everyone nowadays has access to a browser and can access online documentation; the Web is excellent at providing that, and inlining doc inside the code of a program has never felt useful to me.

berney commented 3 years ago

Thanks for the quick answer. I understand regarding long options like --help, and I see also why there's no short -h (besides already being used).