[anjbe]

In practice --help output is mostly useless—it’s neither simple enough for a quick overview nor comprehensive enough to actually know what I can do. Tried “less --help” lately? It spits out ten pages of output!

Plus, every program does --help differently. Does it spit out short output or tons of output so that I need a pager? Does it fork and execute a pager itself, or do I have to run the program again and pipe it to less manually? And then it turns out some programs print --help output to stderr, not stdout, so the pager doesn’t display any output until I do “blahblah --help 2>&1 | less”.

A good manpage beats --help all hollow. It’s simultaneously more brief and more (usefully) verbose. The Synopsis section provides a quick overview of flags, if I just need a quick reminder to jog my memory. But if I want to know the details of a particular flag, I can just scroll down to it or search for it. Mandoc, the default manpage formatter in OpenBSD, even has semantic search built in. It uses more(1)'s built‐in tags functionality to take me straight to whatever flag I want. (You can get this functionality on Linux too by installing mandoc: http://mdocml.bsd.lv/)

Really, horrendous and arcane manpages are a trope that mostly exists in the Linux/GNU world. In BSDs, especially OpenBSD and FreeBSD, clear, simple documentation is a priority. No need for --help or “bropages” when the actual manpages are perfectly clear. For example, check out OpenBSD’s signify(1) manual (http://man.openbsd.org/signify.1), used for cryptographic signing and verification. Compare that to the monstrosity that is gpg(1)… (https://www.gnupg.org/documentation/manpage.en.html)