I strongly disagree with the “ Don’t bother with man pages” advice. It’s extremely annoying when tools don’t provide a manpage. The overhead of opening up a browser to reference command is cumbersome and highly annoying.
There are tools such as pandoc that make generating manpages from various source formats very easy.
Perhaps it is just my grouchy old man syndrome…
For many years I've had this function in my RC files for macOS:
pman() { man -t "$@" | open -f -a Preview; }
f=$(mktemp);man -t "$@" > "$f" && ( {some-pdf-viewer} "$f" ; rm "$f" )
... replacing '{some-pdf-viewer}' with whatever PDF viewer works for you. There is probably one that will take the document on stdin, but I am not aware of one.
I realize I'm late to the party here, but thought is was worth posting anyway. (edited for typo)
MANPAGER=<some-pdf-viewer> man -T pdf <command>
pman='some-pdf-viewer <(man -t "$@")'
git config --global help.format manI also consider this terrible advice. I don’t want to jump to a different program, plus man pages are greppable. And you want the man pages that apply to the machine you’re using (versions, etc) — especially important when you’re using a remote machine (think how common then idiom is to do `ssh foo man blah|less` )
We also didn't mean not to use man pages at all. We just find more people use the built-in help and web pages, so if you have limited time/resources, it's better spent on those things.
In retrospect, perhaps it was worded a bit strongly. I am enjoying the debate, though. The meta point, and part of the reason for this document to exist, is that perhaps it's a good idea to question our 30-year-old traditions and see if we can come up with better ways of doing things. This seems to have got people talking again. :)
There have been so many tries to make something better than man pages, and all of them tend to fall down because the solution is usually super complex. Usually, you are dealing with html or some archeo-crontastic typesetting format (which honestly, gets you man + hyperlinks and some better formatting). I guess the dream of GNU info is still alive.
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.
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".
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.
Interestingly enough, GNU utilities include a message in each man page that tells you to run info <cmd> for more detailed information :)
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).
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.
Write the help for the more verbose of the two, then trim it back for the other.
Everyone gets what they want.