13. September 2008
Ich werde immer wieder von verschiedenen Seiten zum Entwicklungsstand von CSSDoc gefragt. Die Idee scheint also recht gut zu sein, auch innerhalb von YAML hat sich diese Art der Kommentierung von CSS-Dateien bewährt. Dennoch wird CSSDoc außerhalb von YAML kaum angewendet. Ein immer wieder geäußerter Kritikpunkt - zuviel Schreibarbeit. Nun, da kann man was machen.
Also habe ich mir vorhin meine aktuelle Liebingsentwicklungsumgebung Aptana Studio gegriffen und mich etwas näher mit den so genannten Snippets beschäftigt. Vom Prinzip her sind das kleine Textbausteine, die über einfache Textvariablen vor dem Einfügen vom Nutzer angepasst werden können. Für etwas mehr Komfort bei der Arbeit mit CSSDoc genau der richtige Ansatz. Also habe ich schnell ein paar Snippets für die wichtigsten Anwendungsfälle erstellt und in einem kleinen Projekt zusammengefasst:
- file comments
- section comments (2 Ebenen)
- bugfix-/workaround-comments
- single line comments
Das sollten aus meiner Erfahrung die am häufigsten benötigten Textbausteine sein und damit die Arbeit mit CSSDoc etwas leichter von der Hand gehen. Dann mal schnell an die Einbindung in Aptana ...
Einbindung in Aptana
Die Einbindung der CSSDoc Snippets ist schnell erledigt. Im ersten Schritt muss das Projekt (Download am Ende des Beitrags) importiert werden. Hierfür bietet sich die Import-Funktion im File-Menü an. Im folgenden Dialog wählt man General -> Existing Projects into Workspace, um das heruntergeladene Projekt vollständig in den eigenen Workspace zu übernehmen.
Im zweiten Dialog des Imports geben Sie das Root-Verzeichnis des zu importierenden Projekts an, anschließend kann man ein oder mehrere Projekte (Verzeichnisse) importieren. Es empfielt es sich, den Haken für “copy projects into workspace” zu setzen, um die Dateien wirklich an Ort und Stelle zu haben. Ist das Projekt in den Workspace eingespielt, sollte es im Projekt-Reiter stehen und geöffnet sein (siehe rechte Box auf dem folgenden Screenshot).
Und das war’s auch schon. Ab sofort sollte im Reiter Snippets ein neuer Listenpunkt CSSDoc Snippets verfügbar sein. Achten Sie darauf, dass das Projekt immer geöffnet ist. Sobald Sie das Projekt schließen, werden die darin enhaltenen Snippets deaktiviert.
Anwendung
Sind die CSSDoc Snippets installiert, ist die Anwendung letztlich ein Kinderspiel. Öffnen Sie eine vorhandene oder neue CSS-Datei (ich hab für das Beispiel eine neue CSS-Datei erstellt) und klicken Sie mit einem Doppelklick auf z.B. das Snippet @file comment.
Daraufhin öffnet Aptana ein kleines Dialogfenster, in welchem Sie einen Titeltext vergeben können, Angaben zu Autor und Version, sowie Angaben zum Copyright einfügen können. Nicht benötigte Angaben lassen Sie einfach aus und löschen die entsprechende leere Zeile nachträglich aus dem eingefügten Textblock (Fallunterscheidungen lassen sich in die Abfragen leider nicht einbauen).
Sind alle Felder ausgefüllt, reicht ein Kick auf “Ok” und ... Voila! ... ein vollständig ausgefüllter section comment steht im Dokument. Beim @file comment Snippet habe ich mir erlaubt, zusätzlich zwei Platzhalter (Revision und Date) für die Arbeit mit Subversion zu ergänzen.
Auf die gleiche Art und Weise können section comments oder auch Kommentare für Bugfixes oder Workarounds erzeugen, in der Form wie ich sie in den Stylesheets (speziell: core/iehacks.css) des YAML Frameworks verwende. Zumindest mir erleichert das die Dokumentation von Bugfixes sehr.
Das einzige kleine Problem, welches ich bisher noch nicht lösen konnte, das erste Leerzeichen in der ersten Zeile des DocBlocks unterschlägt Aptana offenbar, weshalb in dieser Zeile die Einrückung nicht ganz sauber ist. Aber ich glaube, damit kann ich momentan ganz gut leben. Wer weiß, wie man dieses Problem beheben kann, gebe mir bitte ein Zeichen.
Anpassungen und Feedback
Snippets sind in Aptana sehr einfach zu realisieren. Innerhalb des “CSSDoc Snippets” Projekts liegen die einzelnen Snippets im Ordner snippets. Aptana sucht in allen offenen Projekten nach Ordnern mit exakt diesem Namen und sortiert darin befindliche Snippets selbsständig in die Liste der verfügbaren Codebausteine ein. Änderungen in den Dateien werden sofort übernommen. Die Syntax ist verhältnismäßig einfach, die Hilfefunktion von Aptana gibt ebenfalls Auskunft über Aufbau und Funktionsweise.
Die Codeschnipsel sind nichts besonderes, weswegen ich Sie gern zum Download zur Verfügung stelle und auch unter keine spezielle Lizenz stelle. Wenn Sie dem einen oder anderen helfen, mit CSSDoc zu arbeiten, dann ist mir das Lohn und Freude genug. Dennoch würde ich mich in diesem Fall natürlich über Feedback (Hinweise zu Fehlern, Verbesserungsvorschläge usw.) freuen.
Tja, das war’s auch schon als kleine Spielerei zum Samstag Nachmittag.
Nachtrag: Es hat nur ein paar Stunden gedauert, dann hatte Eric Eggert das Thema in seinem Blog ebenfalls aufgegriffen und ein ähnliches Paket für Textmate auf dem Mac geschnürt. Von hier aus ein großes Dankeschön für die Unterstützung.
Download
cssdoc_snippets_v0.1.zip (3 kB)
Samstag, 13.09.08 (21:59 Uhr)
Dem kann ich mich nur anschließen.
Liebe Grüße
Micha
Dienstag, 16.09.08 (18:05 Uhr)
Ein kleiner Vorschlag: im Ordner snippets einen Unterordner CSSDoc anlegen und dort die Files ablegen, das erleichtert die Pflege und Übersicht, wenn man selbst auch andere eigene Snippets verwaltet.
Übrigens, Du hast mich weider mal auf eine Idee gebracht… ;)
Dienstag, 11.11.08 (10:48 Uhr)
hallo und ein riesen dank an die entwickler von cssdoc
kurz gesagt, herr dirk jesse, ein riesen dank an sie für yaml, ihr buch “css-layouts”, die arbeit an cssdoc und ihre mühen und verdienste in der css welt! in meinen augen sind sie, herr grochtdreis, herr hiebl (ich bin überzeugter joomlaianer), herr laborenz und “der rest der bande” die wirklichen helden des alltages!
nun aber nochmals ein paar worte zu cssdoc….
ich habe nach dem buch “css-layouts” angefangen noch mehr kommentare tzu schreiben, noch strukturierter, habe mir größte mühe gegeben, meine stile zu kommentieren. denn endlich hat sich mal jemand gedanken gemacht um die konformitäten, stukturen und sauberen, aufgeräumten code.
ich hasse nicht viel im leben, bin eher friedlicher natur, aber wenn ich sonst nichts hasse, unstrukturierten, unkommentierten code umso mehr!
und seit ich die cssdoc snippets in meinem aptana benutze, kommt nur noch sauberster code am ende raus.
bitte macht weiter so, wie gesagt, ihr, die ihr euch um standards bemüht, seid die wirklichen helden des (source code)-alltags ;-)
ach, bei der gelegenheit-
wie könnte man ein solches konzept auf html übertragen? gibt es dazu bereits überlegungen? wenn welche? und sollte es überlegungen geben, wie kann ich mich daran beteiligen? ...ich möchte der welt schließlich auch etwas gutes tun!
mit besten grüßen aus dem kühlen norden deutschlands
ludwig k
Dienstag, 18.11.08 (20:09 Uhr)
Hi,
ich hab’ für Komodo Edit ein importierbares Snippet-Paket erstellt, das unter thorstenpeh.de/uploads/komodo/snippets/cssdoc/CSSDoc.kpz herunter geladen werden kann.
In die Snippets sind Tabstops integriert, so dass man mit der Tabtaste zwischen den Eingabefeldern vorwärts springen kann.
Der Import funktioniert über Menü “Toolbox > Import Package…” oder direkt über die Toolbox selbst, wo man ein Paket nach Rechtsklick importieren kann.
Vielleicht hilft es ja jemandem.
Freitag, 06.03.09 (04:14 Uhr)
Danke für die Snippets.
Gibts eine Möglichkeit wie in Zend Studio Variablen automatisch auszuwerten? Sprich zB für $year$ oder ähnliches das aktuelle Jahr einzufügen?
Samstag, 07.03.09 (02:48 Uhr)
Hallo Bernhard,
falls Du Bezug auf meinen Kommentar nimmst und Komodo Edit meinst, kann man ein neues Snippet erstellen und als Inhalt einen “interpolation shortcut” setzen, der zum Zeitpunkt des Einfügens interpretiert wird. Das geht auch mit dem Datum. Die Doku dazu findest Du unter http://docs.activestate.com/komodo/5.0/shortcuts.html.
Viel Erfolg.
Samstag, 07.03.09 (13:58 Uhr)
Hey Thorsten,
meinte eigentlich Aptana. Im Zend Studio habe ich Variablen wie zB ${date} zur Verfügung, welches mir das aktuelle Darum im Snippet ersetzt, oder ${year}. Gibt’s sowas für Aptana auch?
LG
Bernhard
Samstag, 07.03.09 (14:04 Uhr)
Hallo Bernhard,
Meines Wissen bietet Aptana ein solches Feature momentan noch nicht an. Allerdings arbeite ich generell mit Subversion und dessen Möglichkeit, bei jedem Commit automatisch einen Datumssting einzufügen, weshalb ich hier nicht auf die Funktionalität im Editor angewiesen bin.
Samstag, 07.03.09 (14:22 Uhr)
Danke, das wollte ich wissen!
Finde es leider beim ZendStudio etwas besser gelöst. Auch die New-File-Templates und Wizards :(
Funktioniert es bei euch im Aptana Studio als Eclipse-Plugin das Syntax-Color-Schene zu ändern? Ich kann zwar .col-Files laden, aber es ändert sich nichts am Highlight, was ich sehr schade finde..
Freitag, 29.05.09 (17:35 Uhr)
hi!
danke für dieses feature und den artikel. werde es ab heute nutzen !
da du ganz fit in aptana zu sein scheinst, erlaube mir eine frage ... wie ist es möglich in aptana während der html editierung sonderzeichen einzufügen, sowas wie “ ” o.ä.
ich finde leider keinen autocomplet und keine hilfe dazu.
merci und grüße
martin
Mittwoch, 07.07.10 (09:20 Uhr)
Eine schöne Sache; endlich hat sich jemand einer adäquaten Lösung im Aptana Studio angenommen. Ich habe CSSDoc Snippets bisweilen händisch eingefügt, jeweils ein Template angelegt und dieses dann in das jeweilige Projekt eingefügt.
Aber mit dieser Lösung ist mir ein wenig Mehraufwand genommen und eine durchaus elegante Lösung gegeben.
Vielen Dank für diesen Support.