5 ms·

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

by staunch 13y ago

jeroenjanssens 13y ago
See https://github.com/jeroenjanssens/data-science-toolbox/blob/master/explain https://github.com/jeroenjanssens/data-science-toolbox/blob/... for a bash script that interfaces with 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! :-)
- staunch 13y ago
  Sounds like a job for a little statically compiled Go program :-)
- Flimm 13y ago
  The trouble with that approach is that you have to escape special characters: $ 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
auton1 13y ago
This is a great idea!
jph 13y ago
I'll donate $100 if the author wants to build this and open source it. [Ed: As a shell application locally] A 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.
- toomuchtodo 13y ago
  How about an API where you can POST your script with curl -X and a unique link is returned that explains the script when you hit it with a browser? #shutupandtakemymoney (DevOps is fun, teaching not always)
  - deleted 13y ago
    [deleted]
  - skeletonjelly 13y ago
    I would never install this in this format. I'm not going to POST my bash history! I'd prefer a model where you download a definition file (if it needs to be "updated" at the start frequently)
- idank 13y ago
  Thanks for the incentive, but it's not needed and if I do get around to it, it'll of course be open source. 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.
  - auton1 13y ago
    One advantage of a local repository is that it is more likely to match the software versions on the local machine. However, perhaps the best thing would be to allow both local and remote queries :-)
michaelhoffman 13y ago
You can run the web server locally. See the source code readme: https://github.com/idank/explainshell 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
StavrosK 13y ago
I thought of quickly writing one, but it doesn't have an API. Something like this would work well: 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"], ] etc.
- idank 13y ago
  I had something similar in mind. But this format means that repeated arguments that aren't adjacent will have their help text repeated. Feel free to open a bug and we can discuss the options there.
ajross 13y ago
Um... the output wouldn't be interesting for that iptables command -- it's simply a single program with arguments; no shell syntax involved. 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.
- staunch 13y ago
  If all it did was parse program arguments and display usage info it would be super useful. Bash syntax is mostly trivial while there are thousands of arguments across hundreds of programs.
tlrobinson 13y ago
#!/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) (webrowser.open_new doesn't seem to be always working for me, not sure why, I've never used it before)
- deleted 13y ago
  [deleted]
- SimHacker 13y ago
  At least you didn't try to do that in bash! ;) 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.
  - tlrobinson 13y ago
    I've definitely written a URL escaping routine in bash before :)
petercooper 13y ago
It exists, though does rely on the central service: http://schneems.com/post/61514247453/explain-shell-from-your-shell http://schneems.com/post/61514247453/explain-shell-from-your...
jraines 13y ago
there's this: https://github.com/schneems/explain_shell https://github.com/schneems/explain_shell

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

by staunch 13y ago

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

jeroenjanssens 13y ago

See https://github.com/jeroenjanssens/data-science-toolbox/blob/master/explain https://github.com/jeroenjanssens/data-science-toolbox/blob/... for a bash script that interfaces with 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! :-)

staunch 13y ago
Sounds like a job for a little statically compiled Go program :-)
Flimm 13y ago
The trouble with that approach is that you have to escape special characters: $ 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

auton1 13y ago

This is a great idea!

jph 13y ago

I'll donate $100 if the author wants to build this and open source it. [Ed: As a shell application locally] A 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.

toomuchtodo 13y ago
How about an API where you can POST your script with curl -X and a unique link is returned that explains the script when you hit it with a browser? #shutupandtakemymoney (DevOps is fun, teaching not always)
- deleted 13y ago
  [deleted]
- skeletonjelly 13y ago
  I would never install this in this format. I'm not going to POST my bash history! I'd prefer a model where you download a definition file (if it needs to be "updated" at the start frequently)
idank 13y ago
Thanks for the incentive, but it's not needed and if I do get around to it, it'll of course be open source. 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.
- auton1 13y ago
  One advantage of a local repository is that it is more likely to match the software versions on the local machine. However, perhaps the best thing would be to allow both local and remote queries :-)

michaelhoffman 13y ago

You can run the web server locally. See the source code readme: https://github.com/idank/explainshell 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

StavrosK 13y ago

I thought of quickly writing one, but it doesn't have an API. Something like this would work well: 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"], ] etc.

idank 13y ago
I had something similar in mind. But this format means that repeated arguments that aren't adjacent will have their help text repeated. Feel free to open a bug and we can discuss the options there.

ajross 13y ago

Um... the output wouldn't be interesting for that iptables command -- it's simply a single program with arguments; no shell syntax involved. 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.

staunch 13y ago
If all it did was parse program arguments and display usage info it would be super useful. Bash syntax is mostly trivial while there are thousands of arguments across hundreds of programs.

tlrobinson 13y ago

#!/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) (webrowser.open_new doesn't seem to be always working for me, not sure why, I've never used it before)

deleted 13y ago
[deleted]
SimHacker 13y ago
At least you didn't try to do that in bash! ;) 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.
- tlrobinson 13y ago
  I've definitely written a URL escaping routine in bash before :)

petercooper 13y ago

It exists, though does rely on the central service: http://schneems.com/post/61514247453/explain-shell-from-your-shell http://schneems.com/post/61514247453/explain-shell-from-your...

jraines 13y ago

there's this: https://github.com/schneems/explain_shell https://github.com/schneems/explain_shell