Very well done. Now I just wish this was a shell program!
user@server:~$ explain iptables -A INPUT -i eth0 -s ip-to-block -j DROP user@server:~$ explain iptables -A INPUT -i eth0 -s ip-to-block -j DROPA new "explain" command could help me, my team, and save us an enormous amount of time getting up to speed on some of our org's long-term system maintenance scripts.
The main difficulty I had with writing a command line utility is figuring out the UI in a console. Suggestions are welcome of course.
Also, there are two possibilities for a client: the first queries an API on explainshell.com by sending it a command line. This has the advantage of the client being thin, and using the centralized man page database which is probably more accurate. But this means that you're potentially not explaining the exact command you're running locally, which may be confusing.
The second option is to run the man page parser, matcher, etc. locally against the man page on your machine.
However, perhaps the best thing would be to allow both local and remote queries :-)
#shutupandtakemymoney (DevOps is fun, teaching not always)
I'd prefer a model where you download a definition file (if it needs to be "updated" at the start frequently)
#!/usr/bin/env python
import sys
import urllib
import webbrowser
url = "http://explainshell.com/explain?cmd=" + urllib.quote(' '.join(sys.argv[1:]))
webbrowser.open_new(url)
One suggestion though: If there are no command line parameters, then read a line from stdin, so you don't have to play the game of trying to properly escape all of your punctuation in the command line to get it into sys.argv[1:] without any corruption, and can just copy and paste it into stdin.
Hmm, that raises the question of what should happen if you pipe an entire shell script into it, like "./configure"? That might be considered a denial of service attack on explainshell.com.
I wrote this script a while ago. I just needed to update the request because the API had changed a bit since then. Please note that it depends on the scrape tool in the same repository, which in turn depends on the python packages lxml and cssselect. But once you have that set up, you can explain commands from the shell! :-)
$ explain cat filename | sort # won't work
$ explain 'cat filename | sort' # presumably would work
I wonder if the best approach is to make `explain` behave like a prompt. If there was some way it could inherit bash's command history, even better
$ explain
explain> cat filename | sort
POST your query, e.g.: tar zcf - some-dir | ssh some-server "cd /; tar xvzf -"
Returns:
[
["tar(1)": "explanatory text"],
["z": "explanatory text"],
["x": "explanatory text"],
["f file": "explanatory text"],
]
Feel free to open a bug and we can discuss the options there.
I suspect what you really want is an iptables demuddler tool that explains the insane "chains" metaphor and explains how individual packets are going to behave. I'd like that too, but it's not this tool.
https://github.com/idank/explainshell
It should be trivial to whip something up that will generate the right URL for a set of arguments, running either on your local web server or against explainshell.com