Command line version

[OndroNR]

I would appreciate command line version, so I could write explain tar xzvf archive.tar.gz or even explain !!.

[xiongchiamiov]

I was going to attempt that this weekend. :)

[xiongchiamiov]

So the first major difficulty I've run into is that explainshell uses lexgrog for parsing. lexgrog is part of man-db, an alternative man implementation that's only used on a few Linux distros. Notably, this doesn't include CentOS (though perhaps it will eventually, since it's in Fedora), or any non-Linux Unixes (the BSDs, OS X).

I think you can do the same thing with groff, given enough work, but the simpler option is to just use whatis - it seems to give us the same sort of output, albeit only for installed manpages (but that's what we're working off of for a local version, right?).

[idank]

I think we should start with a client that queries explainshell.com, so it can be as thin as possible and require none of the dependencies needed to run explainshell locally.

So the only thing missing is an API at explainshell.com/api/?command=... that returns the structure exposed by the matcher, who given a command string returns a list of (start-index, end-index, help-text) that we found a matching argument for in the man page.

Then a client simply calls this API and can do cool things like colorize each argument(s) with its help text, like the web interface does with the lines.

[xiongchiamiov]

Although the dependencies are a bitch, the advantage of doing a purely-client implementation is that it gets the info for the man pages on the system, rather than some arbitrary other system. This irons out problems with version mismatches between Linux distros (the packages on CentOS are significantly older than Ubuntu), implementation mismatches (e.g. bsd ls vs. gnu ls), and miscellaneous locally-installed programs (that aren't global enough to be included in explainshell.com).

That being said, an API-querying thin client is probably easier to create (and certainly to install). I think there's motivation for both existing.

[petems]

This would be an awesome feature, I can imagine the cross-platform-ness being a bit of a headache though...

[weakish]

A quick and dirty wrapper using command line browser (w3m) to view explainshell pages: https://gist.github.com/weakish/733022#file-explainshell-rc

[idank]

I agree it could get messy if the man page the site has is different than the one you have locally (perhaps in the future, you could submit your copy to explainshell.com and it will remember it?). But I think over time as more man pages will be added, the problem might become smaller and smaller. I'm not particularly keen on keeping multiple versions of the same program, besides different variants such as gnu/bsd/etc.

The main argument for working with the live site as I see it is that it contains manual corrections that I've done, and in the future I expect these corrections to be done by users too, resulting in more accuracy than that provided by the automatic extractor algorithm.

Having said that, I'll help in any way I can to get a nice fully local explainshell.

[OndroNR]

As beginner user of linux I would be satisfied with thin client, that queries explainshell.com for quick lookup of simple commands. But sometime I work offline, so I would use standalone version as well.

[patcon]

+1 for api

[drewcrawford]

+1 for API

If the API supports man page submission, then the CLI application could just upload the local manpage if an acceptable one isn't available on the server. By this solution, you have the advantage desired by @xiongchiamiov of providing output for all local manpages, and the advantage desired by @idank for relying on manually-moderated information if it is available. Further, the output of explainshell.com improves, both reducing the need for and streamlining the manpage submission process.

[idank]

That sounds like a nice solution @drewcrawford. I haven't really started thinking of an API for submitting man pages, that would be quite tricky, but it's definitely something I'd like to do at some point.

[joyrexus]

@xiongchiamiov In lieu of a RESTful API, one can replicate the backend (mongorestore dump/explainshell) and hack up a little CLI interface. FWIW, here's an elementary proof-of-concept.

The classification collection could of course be munged for easier querying.

[troydm]

Here is my command line version perl script #76
Needs only vanila perl and curl to run