noqqe


blog | sammelsurium | projects | about

Explain | Shell-Kommandos visualisiert erklären

2010-08-29 @ bash, debian, development, dokumentation, explain, find, png, python script, shell, ubuntu, vain

Neulich bin ich über das github Profil von Peter Hofmann gestolpert. Darin befand sich ein Projekt, welches ich sehr interessant fand.

Explain versucht Shell Kommandos zu erklären und zu visualisieren. Gerade für Blogs oder andere Dokumentationen finde ich das mehr als sinnvoll. Es erstellt aus einem simpel gestricktem Markdown File eine ASCII-Art ähnliche Erläuterung des Kommandos. Beispielsweise:

$ ./explain.py command.markdown
find . -iname '*.png' -exec echo '<br><img src="{}">' ; > gallery.html
\_/ | ___________/  ________/ ___________________/ |  ___________/
  |  |       |             |               |           |        |
  |  |       |             |               |           |        - Ausgeben nach
  |  |       |             |               |           |           gallery.html
  |  |       |             |               |           |
  |  |       |             |               |           - find Syntax Ende.
  |  |       |             |               |
  |  |       |             |               - mit folgendem Inhalt aus.
  |  |       |             |
  |  |       |             - und führe echo
  |  |       |
  |  |       - alle Dateien die mit .png enden
  |  |
  |  - im aktuellen Verzeichnis
  |
  - Finde (via find)

(PlainText: /uploads/2009/09/015)

Die Syntax des Files das zur Deklaration der Ausgabe dient:

find . -iname '*.png' -exec echo '<br><img src="{}">' ; > gallery.html
---- ! -------------  ---------- --------------------- ! -------------

Finde (via find)

im aktuellen Verzeichnis

alle Dateien die mit .png enden

und führe echo

mit folgendem Inhalt aus.

find Syntax Ende.

Ausgeben nach gallery.html

Die Trennzeichen  sind via Parameter austauschbar und auch ansonsten tut das kleine Python Script seinen Job hervorragend. Sollte demnächst mal wieder ein Kommando erläutert werden müssen, werde ich definitiv darauf zurückgreifen. Weitere Beispiele auch unter:

[1] http://www.uninformativ.de/?section=news&ndo=single&newsid=118 [2] http://github.com/vain/explain

Comments (6)

noqqe on 2010-08-30T01:11:50
Ich kritisiere meinen Blogpost an dieser Stelle selbst und frage mich, ob es nun ein Markdown oder ein Markup File bzw. Mechanismus ist, den ich oben beschreibe.

vain on 2010-08-30T14:26:15
Also, ich tendiere da eher zu „up“. :) Cheers!

Eddard on 2010-08-30T23:40:07
Kurze verständnissfrage. was ist der unterschied bzw. worum geht es bei Markup/down

noqqe on 2010-08-30T23:58:07
Markup: Aus Daten einer bestimmten Form werden neue Daten generiert, welche das Endprodukt darstellen. Sozusagen Rohdaten-&gt;Ergebnis Markdown: schätze ich umgekehrt. Soweit ich das richtig verstanden habe. Lasse mich aber gerne korrigieren. :)

vain on 2010-08-31T02:27:44
Hmmm, ich kenne den Begriff „Markup“ als Kurzform für „Markup Language“ oder eben eine „Auszeichnungssprache“, mit der du dem Inhalt eines Dokuments Eigenschaften hinzufügen kannst. Also Beispiel LaTeX: Mit „textbf{Hallo}“ sagst du aus, dass das Wort „Hallo“ bitte fett gedruckt werden soll. Weiß jetzt nicht, ob das ein hartes Kriterium ist, aber für mich gehört zu einer Markup-Sprache auch immer dazu, dass die Dokumente mit einem einfachen Texteditor bearbeitbar sind. „Markdown“ kenne ich jetzt nur als Namen einer konkreten Markup-Sprache. Ob die das nun aus Spaß an der Freude „down“ statt „up“ genannt haben oder ob es da einen tieferen Sinn gibt, weiß ich nicht. ;) Vielleicht liegt es daran, dass Markdown einige Dinge implizit aus der Plain-Text-Formatierung übernimmt, Absätze oder Listen zum Beispiel. Es ist also näher am Text („down“, weiter unten, auf keiner so hohen Abstraktionsebene) als zum Beispiel HTML – oder so? Keine Ahnung, reine Spekulation. ;) Das, was beim Explain-Skript als Eingabe verlangt wird, ist in gewissem Sinne eine ganz, ganz einfache Markup-Sprache. Der Inhalt deines „Dokuments“ ist der zu erklärende Befehl samt den Kommentaren. Und das versiehst du durch einfache Mittel mit weiteren Informationen: Markierung des Bereiches für jeden Kommentar und Trennung der einzelnen Kommentare mit einer Leerzeile. Das alles kannst du auch ohne weitere Hilfsmittel in einem einfachen Texteditor machen. Wäre jetzt zumindest meine Interpretation der Dinge. :)

noqqe on 2010-08-31T11:23:18
Der Preis für den längsten Kommentar im Blog geht übrigens an vain ;) Schön erklärt. Jetzt hab ich's auch verstanden :)