There are exactly three kinds of manpages:
- Way too detailed
- Not nearly detailed enough
- There is no manpage
I will take 1 any day over 2 or 3. Sometimes I even need 1, so I’m grateful for them.
But holy goddamn is it awful when I just want to use a command for aguably its most common use case and the flag or option for that is lost in a crowd of 30 other switches or buried under some modal subcommand. grep helps if you already know the switch, which isn’t always.
You could argue commands like this don’t have “arguably most common usecases”, so manpages should be completely neutral on singling out examples. But I think the existence of tl;dr is the counterargument.
Tangent complaint: I thought the Unix philosophy was “do one thing, and do it well”? Why then do so many of these shell commands have a billion options? Mostly /s but sometimes it’s flustering.
I can appreciate that. Appologies if you know this already, but just don’t like them. Here are some tips.
It helps a lot to get title/subtitle/flag highlighting. By default man pages are hard to use simply because of how dense they are. It’s much easier to skim when you can separate the parts you are looking for up front from the text.
Don’t forget ‘/’, ‘n’, and ‘N’. First way to use man pages more effectively is to search them easily. And you can search via regex. Often I’m looking for more info on a particular flag. So I’ll press ‘/’ followed by ‘^ *-g’. For a g flag.
Take notes on the side. It saves you time later. Your future self will thank you. And you learn a lot by skimming them.
Man pages can be intimidating/confusing, but, imho, it’s worth training that skill. Even if you are slower up front, it’s totally worth it.
