Comment by mmalone
6 years ago
They're not saying you shouldn't provide command-line help. Just that you should deliver them through a `help` subcommand and/or through a `--help` flag (like `git` does) because people don't find man pages and because man pages don't work on every platform.
Right. I still prefer terse help text from the command line, and more in-depth in the man pages.
I find commands with copious -h output and having to pipe that into a pager or using scroll back a far worse UX than just opening up a man page that’s easily searchable / scrollable.
Yea that's reasonable, but there are pros and cons and it's also definitely an opinion :).
I don't see the problem with piping help text through a pager (that's literally all `man` is doing). Alternatively, a tool can use a pager automatically (as `git help ...` does). So `man` isn't required to have a pager. Whether you should use a pager by default is a different argument.
That said, I find pagers annoying because it's hard to switch back and forth between typing a command and the docs. That's way easier to do with scrollback. Although someone in this comment thread also mentioned the `PAGER` env var, and that you can set `PAGER=cat`, which is a good pro-tip. So, TIL.
Still, if you're concerned with command-line ergonomics for a broad audience I think there are more people that either 1) know how to `| less` or 2) prefer or don't care about a pager than people who are gonna automatically just know they can do `PAGER=cat man <some-subcommand-of-my-cli-tool>`.
Plus, there's still the cross-platform argument.
Oh, and OP doesn't mention this, but man pages also complicate install, uninstall, versioning, and having multiple versions of a tool installed simultaneously. Built-in help is obviously just works and is distributed with the standalone binary. To use man pages you have to place additional artifacts on the system and make sure they're managed correctly (e.g., versioned). It's additional complexity with basically zero benefit.
So yea. Seems like, as a rule, their guidance is reasonable. I don't see a lot of benefit to using man pages other than "because that's how it's always been done".
> I don't see a lot of benefit to using man pages other than "because that's how it's always been done".
Man pages are organized, categorized, indexed and searchable. It's a common format that can be read by multiple pagers (including dedicated GUI browsers for those so inclined). They're also available when the command might not be. There are definitely benefits over command --help other than the syntax of the invocation.
> I find pagers annoying because it's hard to switch back and forth between typing a command and the docs.
less -X
If people don't know about man, why not teach them? A simple line in the summary -h gives that says: For more information, read the man page: man foo.
> Plus, there's still the cross-platform argument.
This just makes me sad. I don't know exactly where we'd be if every computer system didn't feel it needed to be garbage just because Windows is. But I don't think it'd be quite as bad as where we are.
1 reply →
> That said, I find pagers annoying because it's hard to switch back and forth between typing a command and the docs.
I tend to live inside byobu on the command line, or "pure" tmux/screen depending on availability. When opening a man page or similar I do it in a fresh pane so there is less back & forth.
Or of course usually you are using the CLI within a GUI so you have the option of a separate terminal too, or a web browser to the one version or other docs, though when using an external resources rather than the local man page there is the slight gotcha of making sure versions match (the main docs online may be for a newer revision than the one your OS currently has in its package repo).
Man pages improve discoverability. You only find --help contents if you already know which command you want. Man pages are searchable (with `man -k` or `apropos`).
This is most relevant when it's a tool that isn't going to be immediately obvious anyway (if I'm trying to figure out how to do XYZ on heroku, it's not unreasonable to expect me to look at the heroku program I installed), and especially when it's a tool that might be installed by default or installed and forgotten about.
Agreed. And man page content is searchable too, even with regular expressions while in a pager like less.
Sure, but they advise pulling up a pager anyway if the content is long.
Why not both?
Write the help for the more verbose of the two, then trim it back for the other.
Everyone gets what they want.
Perhaps prioritize a --help flag over a man page, but add both if time permits. In any case, a man page is static text and much easier to implement than --help, especially if you have multiple help modes (e.g. verbose or different sets of commands).
It never even occurs to me to use —help. If a tool doesn’t have a good man page, I just find a different tool.