[Cialug] Man Skeptics

[Tim Wilson]

You could always run “strings” on it. But yes, I agree. It does seem odd
that you have to run an application to figure out what the application
does. And as you pointed out, what is the help option?  It’s not uniform,
and even if it was, that’s exactly what a nefarious application would use.
And there’s a good chance that built-in help would increase the size of the
executable, for something that may never be used in production.

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

> 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
>
> >
>
> >
>
> >
>
> >
>
> _______________________________________________
>
> Cialug mailing list
>
> Cialug at cialug.org
>
> https://www.cialug.org/cgi-bin/mailman/listinfo/cialug
>
> --
Tim
Required reading: http://bccplease.com/