--help isn't even the lowest common denominator. An incorrect argument list is. The program knows it was given incorrect arguments, it should show help.
Oh god please no, I hate the rare program that poops my terminal full of seven pages of output and I have to use like shift+pgup or the mouse to get back up to see the only four useful words of output: "option --anakyze not recognized". This also confuses the heck out of beginners.
MariaDB also doesn't print the entire manual when it goes "syntax error at ' OR 1=1". It makes no sense.
You can include "See --help for more information" at the end of every error to make sure everyone knows where to find that, though, since indeed not every program uses the same syntax for usage. 90% of the time I don't need a copy of a program's manual in my scrollback when I, say ,typo something or forgot that two options are incompatible. There is a reason scrollback exists and I use it for that purpose. I'll look up the manual or run --help in another terminal tab/window, or choose to run it in the current one at my own discretion thank you
Just to throw this out there: let's also hate on programs that give you seven pages of output for --help but print it to stderr so you have to jump through shell redirection hoops to pipe it to a pager to be able to read or search through it.
This reminds me of something I remember having installed years ago that would format `man` pages as a nice document (using... grotty or something??) and open them in Preview or something. I think it was on a mac and it was 15+ years ago.
Genuinely my least favorite thing in the terminal is when I forget some detail about... usually CURL, since they use the capitals AND the lowercase letter arguments for very different things. So I end up having to use the / command in `less` to search for some common word for 3-5 minutes because the manpage is so disorganized. We have a much better tool than the Terminal for viewing long-form text content, so maybe I just need to alias `man` to open a website that publishes manpages.
Many programs prefer to be concise when their arguments are wrong, perhaps on the assumption that it's probably a simple typo rather than a request for screenfuls of help information. This sometimes is and sometimes isn't an ergonomic choice. (I usually prefer conciseness.)
But asking for `--help` is unambiguous, and is in fact the lowest common denominator way to be explicit about it.
Very few things grind my gears like having to search through a wall of "--help" output and lengthy list of arguments to find the error that describes the problem. Screenfulls of text when the error is "Option 'b' unknown" isn't helpful.
This seems like it would be solved completely by printing the error message ("option b unknown"), and then also printing the "--help" stuff. You can see the error inthe first line(s), so `head` will make that easy to see, but anyone trying to print the help text will get it.
If you need to learn something (e.g. you're taking a class or your supervisor wants you to learn something), then reading the documentation is a good idea.
If you already know the content, but accidentally made a typo and are trying to debug it, then reading the documentation isn't going to help. An error message pointing out the problem will help.
I had a teacher like that in High School. "I made a mistake in this proof, but I'm not sure what it is." "You have the book for the course, the answer is in there."
Reading techical documentation is a skill. It's one that is sorely lacking in IT from develpers to ops. RTFM when learning is a valid lesson in and of itself.
No but the sports referee perhaps specializes in one or a few games/leagues.
And at high levels, a referee role is probably similar to physician/lawyer where you'll have annual rule updates/changes, jurisprudence history of past rulings, and conventions/associations of referees where they will be spending money, time and effort when not on the field.
Now multiply the referee's game or league types by everything in /usr/bin
-? should be lowest common denominator, because that is exactly equivalent to passing incorrect argument list when using getopt(). Whether that should produce concise help of the kind "usage: foo -abcdeEf <file>" or full help is another question.
> b) don't have a file named, say, `-a` in the current working directory.
Rather:
b) don't have a file with a single letter name in your CWD, like `a`
Try this:
touch a
ls -?
And yes, it's even more damning; you don't generally find legitimate files named `-a` or similar - rather, it's clear indication of someone invoking some CLI command wrong (`cp` comes to mind). However, single-letter files and folders are a relatively frequent thing to see.
I don't see it. What are you trying to show with 'a' instead of '-l'? Why would a file named 'a' interact with a glob like '-?'?
$ touch a
$ ls -?
zsh: no matches found: -?
$ bash -c 'ls -?'
ls: invalid option -- '?'
Try 'ls --help' for more information.
$ dash -c 'ls -?'
ls: invalid option -- '?'
Try 'ls --help' for more information.
$ touch ./-l
$ ls -?
.rw-rw-r-- 0 user 10 Feb 18:32 -l
.rw-rw-r-- 0 user 10 Feb 18:31 a
> The common denominator for getting help would be man(1).
That's... not what a common denominator means. It's far easier to check for `--help` or `-h` and print _something_ than write a whole document in a weird markup language for man.
"common denominator" is the thing that is guaranteed common for all commands.
man(1) is, provided that people produce man pages. It's also orthogonal and composable without interference: one can write a man page for commands that don't have man pages.
Flags are not, because commands parse their arguments in whatever way; all commands can accept arguments but arguments are also part of the operational interface contract. man(1) is decoupling all possible problems out.
It is also extremely obvious than `man foo` is side-effect free, whereas `foo whatever`, whether `whatever` can be `--help` or anything else, has unknown effects when the command is unknown.
Some argue that man pages are too rich; well the man pages can just also start with a summary identical to what a hypothetical `--help` flag would output.
Turns out this is the conventional `SYNOPSYS` title of section 1 man pages, and possibly the `OPTIONS` one; if these are absent or badly written then one could reasonably posit that a hypothetical `--help` flag output would be just as unhelpful; cue the wads of commands that "--helpfully" output `foo [-4236xXksirtTgsdv]` as help, which tells you nothing really helpful.
My understanding is the opposite: man pages are much more difficult to produce than plain help text, so it's unreasonable to expect they'll always be available, while help is easy enough to (almost) always be there. If you use any CLI library at all, it will automatically be generated. If you don't, the equivalent of `argv[1] == "--help"` is good enough.
These days, I'm positively surprised when I find man pages for a program, whereas I'm annoyed when one doesn't support --help.
> man pages are much more difficult to produce than plain help text
They're absolutely trivial to generate these days, gone are the days of having to deal with roff, you can write a quite dumb markdown file and produce a man page out of it in short order.
I'm not necessarily saying they're _difficult_, but it should be obvious they're relatively harder. For --help, the least I could do would be a conditional at the top of the program, or let my CLI library auto-generate it for me. For man pages, I have to go out of my way to explicitly generate and distribute them.
There are people arguing that? My feeling is that man pages are usually so thin as to be useless in 50%+ scenarios I need them. I really wished the culture defaulted to expecting all software to come with Info pages.
An incorrect argument list should concisely tell me what is wrong with the argument list, and that I can use --help to explain the whole thing. I don't want to scroll up 20 pages to fix a typo - assuming the program even printed a specific error before it printed 20 pages of help.
Sometimes, arguably, you can do better. For instance, some CLI tools try to guess what the user was trying to accomplish, and show a more specialized message. Eg. kubectl will tell users that a particular kind of resource they were looking for doesn't exist, but there are some with similar names.
This is especially useful in situations where the help text is enormous (dozens and dozens of options).
I agree with this, but would also point out that many junior engineers I've worked with completely give and ask for help if the program doesn't do what they want it to and prints out many lines of help. Even if there is a clear message at the top of the large output, they get overwhelmed.
