[Cialug] (no subject)

[Todd Walton]

You know the 12-factor app concept? It's a genius bit of advice for
conceptualizing how your application fits into its environment. Don't
forget logging. Run it as a collection of stateless processes. Gracefully
handle SIGTERMs. Etc. The whole writeup is here: https://12factor.net/

Well, one of the guys who came up with that (I think) got on Hacker News a
while back and proposed a #-factor idea for command line apps. He admitted
it wasn't complete and maybe there were some things not entirely thought
through. But one thing he was sure of was that man pages are history. Build
help into your cli tool and stand up a docs site on the web. But don't
bother with man pages unless you really have to. He says, "they just aren’t
used often enough anymore" and "novice developers are unaware of them".
Those seem like really dumb things to say. Novice developers become
seasoned developers in a matter of time, and who *doesn't* use man pages
when the occasion calls for it?

Two very important things I think man pages provide:

1) I tend to pop into the man page for an unfamiliar command so that I can
get the gist of what the tool is even supposed to be doing. Not just the
technical bits, not just specific flags, but the intro paragraph, which the
help output rarely provides. And looking up help pages on the web is not
always easy. Sometimes they're hard to find, or too verbose, or you're on a
spotty internet connection, and it takes time to do even when it's easily
available.

2) Security. If there's a cli app that I'm not familiar with, I'd rather
not run it just to see its help output. One problem with that is that the
app can do *whatever it wants* when it starts up. It could display help. It
could run something nefarious. It could display help *and* run something
nefarious, so you'd never be the wiser. Another problem is that there are
apps that have a "-h" option that isn't for showing help. You could run
"something -h" and it could be like "Doing something to the current
host...". How quick is your Ctrl-C trigger finger? Does "something" accept
Ctrl-C signals? You'd better hope so! xinit, for example, will take the
"-h" or "--help" options and say "okay! starting up X". I tried "shutdown
-h" and it said "proceeding with immediate shutdown". It was in a
container, so it failed. I don't want to try that on the computer I'm
working on! You get the point.

Man pages provide answers to both of those things, and they don't require
that the provider of the program be both benevolent and willing/competent
to host docs somewhere findable.

I will say though that I have a tiny bit of sympathy for what he's saying
about man pages. They do take some extra discovery process of their own,
however small that is. And writing man pages does take some amount of
effort, however small that can be. (help2man, anyone?) Wouldn't it be nifty
if there were a trusted program you could run against an executable (which
is what 'man' is) that would either extract the contents of the help from
the binary or could run "--help" in a sandbox of sorts and ensure that only
ascii text came from it, not allowing it to do anything else? "Extracting
the contents" is likely impossible and probably at least difficult. But
maybe the latter would be possible. That would allow man-skeptics to write
their detailed help pages, but still allow man lovers like myself to be
okay with it.

--
Todd