21 Sep
2023
21 Sep
'23
9:06 a.m.
That's it, isn't it? Man pages are great if you a) already know the name of
the program you want (c'mon, apropos/man -k have never really worked that
well), and b) have at least a vague idea of how to use it. If you want to
look up what a flag does, or whether there's a flag that does what you
need, they can't be beat.
But they aren't great for either exploration or discoverability.
Now, this is less of a problem when a command takes its input on stdin,
writes its output to stdout, any errors to stderr, and it has, like, five
or fewer different options. For the use case of
programs-which-are-really-filter-stages designed to be connected via pipes,
and when there aren't all that many of them, it works fine. Once something
else is on the table, yeah, the man page is at best incomplete and at worst
basically useless.
Say what you will about VMS, its HELP functionality makes it much easier to
go from "I want to do X" to "And here's a sequence of commands that
will do
X" when you don't already have a good mental model of what's on the
system.
Adam