[Cialug] Man Skeptics

[Todd Walton]

Here's the original article about "12 factor" cli apps:

https://medium.com/@jdxcode/12-factor-cli-apps-dd3c227a0e46

--
Todd


On Fri, Sep 18, 2020 at 1:28 PM Todd Walton <tdwalton at gmail.com> wrote:

> 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
>
>
>
>