Hacker News Reader

Comment by exmadscientist | Hacker News Reader

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.

View on HN

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.

Oh it's worse than that. Some classes and even supervisors I've had, forced me to read documentation, over and above actually doing stuff

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

Would you expect a sports referee to manage a match without knowing the rules of the game?.

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

lol how the sarcasm was lost on hackernews

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.

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.

Yeah, except both the error and the --help are going to stderr. ;-)

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

`?` is a glob for one character so it would work only if you:

a) use bash-like behaviour of an unmatched glob turning into a bare word, e.g with zsh have `setopt NULL_GLOB`.

AND

b) don't have a file named, say, `-a` in the current working directory.

Try this:

    touch ./-l
    ls -?

The common denominator for getting help would be man(1).

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

`info(1)` can burn in hell though.

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.

https://github.com/sunaku/md2man/blob/master/EXAMPLE.markdow...

https://github.com/rtomayko/ronn/blob/master/man/ronn-format...

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.

> Some argue that man pages are too rich

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.

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

Haha true, I missed the most obvious of all!

> Try this: touch a; ls -?

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

ZSH must handle globs in some weird way?

'?' is glob for one character, '-?' means "dash followed by any character", and that's what I'd expect to be matched, and that's what my `ls` does.

> '-?' means "dash followed by any character"

but `a` is not "dash followed by one character" so the glob does not match a `a` file?

my haha nearby was wrong! I should have tested it :)

I have a non-default option on for zsh, which is incredibly useful interactively. (Bash also has this option, but I haven't enabled it.)

Normally, ls doesn't expand globs.

Why did you say to try "touch a; ls -?"? What am I supposed to see from those two commands?

Reply on news.ycombinator.com