Hacker News Reader

Sure, but adding --help to a command means that the output of help is not exceptional, thus you're expecting it in stdout. If on the other hand you invoke the command incorrectly, and the author decides the best thing to do is print out the help in such cases, then yes, it should be stderr.

Let's take the cut command for instance. If you read the man page you discover it's job is to parse fields out of each line of input. Printing a usage message into STDOUT is not part of its documented behaviour. It is therefore an exceptional event.

cut does the right thing:

- if you run cut with no input and no parameters, it outputs an error message to STDERR

- if you run cut --help it outputs usage info to STDOUT

This is what I'd expect based on the man page. Running cut with no parameters is undefined, hence the output to STDERR. Running cut --help is defined, so the output goes to STDERR.

I think people get confused because some tools, when run without any input, output the full help info to STDERR, instead of suggesting the user run foo --help*.

So foo* and foo --help* appear to be equivalent. Until you pipe into less*.

> This is going to sound snotty

The word you’re looking for is “condescending”.

Regardless, there is no argument about software freedom to be made here.

You’re allowed, be it open or close source, to write and publish software that defies common, well-established conventions.

You can pretend that it’s some sort of first amendment right to do so if you like, and attempt to deflect your unwillingness to write software that behaves properly as incompetence on the users’ end.

But whether anyone will be convinced by that is a separate question, and those who aren’t convinced certainly have the right to tell you, in turn, that your software sucks. This does not inflige on your rights to write broken software.

I believe you have completely misunderstood my "argument".

This is going to sound snotty, but arguments were made for people who sort of knew what they were doing. You probably shouldn't be touching the comments box if you don't know what it does. These thoughts were written assuming a basic understanding of the language they were written on.

> Asking for help is an exceptional event.

"Exceptional event" is not a useful or well defined concept. A better concept is "error" or "unexpected result".

Asking for help is a request for information. The normal, non-error, expected result is that a bunch of text will show up on the output. It is entirely reasonable that the "next command in the pipe" might want to do something with that expected output.

I shouldn't have to guess whether or not you think the output I specifically requested is "exceptional", so it's entirely reasonable to expect that programs in general consistently put user-requested help on stdout.

You are of course free to write your software any way you want. And I'm free to think it's stupid, and to not use your software.

If the next command in the pipe wants to do something with non-normal output of a command, then yes, it should do something with that. And the command can redirect stderr to stdout with the use of `2>&1`.

Yes. You're unlikely to like my software. I don't recommend you use it.

> Unix and its derivatives were made for people who sort of knew what they were doing. [...] You probably shouldn't be touching the shell if you don't know what that does.

You really do not need to be such a grumpy elitist. People are not born with Unix knowledge already in their heads. Asking questions, raising doubts, and getting answers from more knowledgeable users is a very effective way of learning new things!

With that said, can you make an example of a legitimate use of `command1 --help | command2`, where `command2` does something useful and is not `less`?

I don't mean to disagree with your first paragraph, but I do pipe help to grep (or rg) all the time. (And never to less, who uses a non-paging/scrollback terminal emulator in 2023? Why else would that be beneficial, just to clear it when I've read what I wanted?)

I use `less` with help output because if the help output is long, it starts me at the top of the help output rather than the bottom, and the top usually has a nice summary of the command usage that I usually want to read.

More importantly, I can easily find things by searching with less's `/` hotkey. Relying on the terminal emulator's built-in search isn't great because (a) I'm not used to it - I am more used to vim's keybindings, and the search hotkey `/` is the same in vim, and (b) that's also going to search all the output from before I ran --help (not as big of a gripe, but still somewhat annoying).

I can see how that's a reasonable preference. Though I fall in @OjFord's camp. I have a mouse scroll wheel and I'm not afraid to use it. But... I have to remember to hit return a few times beforehand because it's sometimes hard to find the top of help when you're scrolling up in the terminal.

And if your brain is wired for vi, then that makes complete sense.

But... the cool thing about using the scrollwheel to scroll up to see the --help output is it's always there. If you pipe it into less, it disappears as soon as you exit less. So if you're writing a big, beefy command with lots of unfamiliar options, you can start typing down at the prompt and then scroll up to read the help output. It's annoying when you type that you immediately scroll back down to the bottom of the terminal buffer, and I think all terminal emulators default to doing this, but maybe it's a configurable behaviour.

This also works with `man <command> | cat`.

Also... how many times have I had to type out `git branch -a | cat` and tried to remember to put the `| cat` in it. I HATE that the stock git cli automagically pipes to /usr/bin/pager. If I wanted to pipe the output to /usr/bin/pager, I would type `command | /usr/bin/pager`. But now I'm just kvetching.

Yeah ok now you say it I realise I do sometimes pipe help to less too. It's just that typically I'll run it bare or piped to grep/rg first, and potentially stop there. I too don't use terminal search for pretty much the same reason, and just never got into it for whatever reason.

(Alacritty has a tonne of great features I just haven't taken the time to learn the muscle memory to use.. ctrl-j/k bindings to scroll back and some custom patterns to open as URLs is about it.)

Sure. I don't need to be a grumpy elitist.

The problem isn't that you get a usage message when you ask for it. It's that you get a usage message (written to STDOUT) when you don't. Many commands will print out the usage message when command line options specify a condition that can't be met. I find this frequently when ssh'ing into busybox based systems. Busybox's find command is much less "refined" than comparable desktop OS finds (BSD & GNU/Linux).

So if I do something like:

  ssh me@foo.example.com "find . -type f | while read line; do sha256sum \$line; done" | tr -s ' ' | cut -f 2,1 -d ' ' | sort | uniq -c

And expect output that looks something like a sorted line of hashes, I will be sorely disappointed.

Exceptional events yes like when the help output is printed due to incorrect usage. But when calling with --help directly it's the expected output.

> This is going to sound snotty [...] Asking for help is an exceptional event.

Yup, sounds pretty snotty.

> 2>&1. You probably shouldn't be touching the shell if you don't know what that does...

I use the shell almost daily, and have shipped industry-leading products.

2>&1 is a vague memory because I'm not sure if I've ever done that; and I certainly shouldn't have to know some arcane shell trick to read the manual.

It turns out that the right answer doesn't even depend on your level of shell knowledge or on how you tend to use the shell.

I use much more complicated pipe tricks than that interactively on a daily basis, and I definitely don't think of them as "arcane". As somebody who does that, it's useful to me to know which channel the data I want to pipe are going to come out on. Which is why help, which is normal requested output, should obviously go to stdout.

Usage messages issued in response to actual user errors are different, of course.

Sure. But the comment wasn't "You probably shouldn't be touching the shell if you haven't shipped industry-leading products" it was "You probably shouldn't be touching the shell if you don't know what that does."

Also, if you needed to use it every day, I suspect it would be more familiar than a vague memory.

I use the shell almost daily.

I don't pipe command output daily, though. I use the shell because often it's easier than point-and-click for a lot of operations.

The shell has plenty of use cases that don't involve piping output. Saying you shouldn't touch the shell unless you understand piping output is like saying you shouldn't touch a refrigerator unless you know the perfect temperature to store milk.

I am ambivalent. I see the value in what you're saying, and we owe so much to the ad-hoc accumulation of what we now call the gnu toolset.

On the other hand, a system that has been designed coherently is much nicer to use.

I think this might be the crux of my discomfort with the OP's exhortation we should all adhere to his preferences. Unix and it's derivatives are great because there's a long history of people trying to do things, finding it hard and then slathering on a layer of functionality which is invoked through abstractions that are novel and probably inconsistent with those abstractions that came before. You don't need to ask anyone's permission and you won't find people saying "meh. you shouldn't do it that way." (okay. maybe a few, but you can ignore them. The Unix(tm) police won't show up to cart you away like what happens with VMS.)

But the flip side of this is, yes, cruft.

The reason you pipe exceptional events to STDERR [..]

Uh-huh. And then you get developers that do this (from inside a f#@<ing library, of all things):

  FILE *stream = (level == LOGGER_LEVEL_ERROR) ? stderr : stdout;

If it's not an error, it is not exceptional, so it should go to stdout, right? Yay for personal agency!

I'd be more convinced by a technical argument, than this appeal to "personal agency"

Is there no value in following a convention?

Sure. But the benefit of open source is you can do whatever the eff you want. I just don't like being told "I have a use case that dictates your behaviour. You need to follow that use case, even though it's not your use case and contravenes an existing convention."

This is sort of my hot button issue. After years of working on BSAFE, OpenSSL, firefox and libnss, I hate that people say "Hey. Great software. Here's a list of things you must add to it. Of course I'm not going to pay you."

Why should I change my code to adhere to someone else's conventions when they're in opposition to existing conventions?