Im Gluga Wiki darf grundsätzlich jeder lesen. Änderungen machen, neue Seiten erstellen und Dateien hochladen ist Leuten von der Gluga vorbehalten. Es gibt auch einen eigenen Bereich "private", der nur für die Gluga lesbar ist.

Technik

Die Seiten werden im AsciiDoc Format geschrieben, das ist eine Wiki-Syntax wie viele andere auch. Alle Dateien werden in einem Git-Repository verwaltet, somit besteht auch immer die Möglichkeit, ältere Versionen jeder Datei wieder herzustellen. Beim git push ins zentrale Repository läuft im post-update Hook ein Script, das dann auch die HTML-Seiten aktualisiert.

Mitmachen

  1. git zumindest in Grundzügen verstanden haben, z. B. durch unseren Git Vortrag (PDF)

  2. Den eigenen SSH Public Key an Bernd oder an die Mailingliste Gluga-Users schicken. Wir schalten Euch dann frei und ab diesem Zeitpunkt habt Ihr dann mit diesem Key die Möglichkeit, im Git Änderungen vorzunehmen.

  3. git clone gitosis@git.gluga.de:gluga-wiki.git
    holt Euch dann eine lokale Arbeitskopie des Git-Repositories. Hier könnt Ihr dann also Eure Erweiterungen/Anpassungen vornehmen.

  4. Wechselt jetzt aber erst einmal in Euer Arbeitsverzeichnis, also meist wohl gluga-wiki und dort in das Unterverzeichnis .git/hooks und führt dort
    ln -s ../../bin/pre-commit
    aus. Damit installiert Ihr Euch ein pre-commit Hook Script. Dieses prüft vor jedem Commit alle asciidoc-Dateien auf Syntax-Fehler. Wenn welche gefunden werden, meldet es diese und bricht den Commit ab. Damit wird sichergestellt, dass Dateien, die Syntax-Fehler enthalten (und damit zu Problemen auf der Seite führen würden) gleich gar nicht erst committed werden können. Man erhält die Chance Probleme zu beheben, bevor sie jemand anders gesehen hat.

  5. Wenn Ihr Änderungen macht, bitte überprüft zuerst bei Euch lokal, ob diese auch gut aussehen. Dazu gibt es im bin Verzeichnis das Script build.sh. Es erzeugt aus jeder AsciiDoc Datei eine dazugehörige HTML Datei, die dann im Verzeichnis htdocs liegt. Die könnt Ihr mit Eurem Browser lokal öffnen und anschauen.
    Auf eurem System müssen dazu installiert sein:

    • asciidoc

    • Perl samt Config::IniFiles (kann je nach Distribution z.B. via apt-get install perl-configInifiles oder apt-get install libconfig-inifiles-perl nachgerüstet werden)

    • Fehlen diese, so weist die Ausgabe von build.sh darauf hin

  6. Sobald Ihr mit dem Ergebnis zufrieden seid, stellt ein Commit, gefolgt von einem git push die neue Version online.

  7. Zurückrollen geht natürlich genauso einfach: Alte Version (mit Hilfe von git) wieder herstellen, committen und pushen.

Verzeichnisstruktur

Was gehört wo hin?

asciidoc

Hier liegen die Dateien mit den Inhalten unseres Wiki. Hier werden diese auch editiert. Bei Bedarf kann darunter auch eine Verzeichnis-Hierarchie angelegt werden, um Inhalte weiter zu strukturieren. Bislang liegen alle Dateien direkt in diesem Verzeichnis.

talks

Verzeichnis für die Präsentationen und Handouts der einzelnen Vorträge, Workshops usw. Dateien, die hier liegen werden normaleweise von mindestens einer Datei aus dem asciidoc Verzeichnis verlinkt.

examples

Verzeichnis für Beispiel-Dateien der einzelnen Vorträge, Workshops usw., also Sourcecode-Dateien, und alles was man zum Üben und Nachvollzien zu Hause noch so braucht. Dateien, die hier liegen werden normaleweise von mindestens einer Datei aus dem asciidoc Verzeichnis verlinkt.

web-resources

Hier liegen statische Ressourcen für die Webseite: Stylesheets, JavaScript Files, … Die Dateien aus diesem Verzeichnis werden beim build.sh rekursiv kopiert ins Document Root der Website. Files, die direkt unter web-resources liegen, landen auf oberster Ebene im Document Root.

web-resources/images

Hier hin gehören Bilder, die zur Gestaltung der Wiki-Seite gebraucht werden.

calendar

In diesem Verzeichnis ist vorallem eine Datei wichtig: calenadar.ini Hier werden die Termine und Themen vom Linux-Cafe eingetragen. Die Datei liegt im ini-Format vor, ist recht leicht zu verstehen und mit Kommentaren versehen, was wie eingetragen werden muss, siehe dort. Daraus wird dann beim build.sh die Seite mit den aktuellen Termine und das ical-File erstellt. Termine in der Vergangenheit blendet das Script automatisch aus.

private

Dateien, die nur für die Gluga lesbar sein sollen und nicht im Web erscheinen, z. B. rein interne Dokumente, Vortragsfolien von alten Vorträgen mit ungeklärten Urheberrechten, … Bitte sinnvolle Unterverzeichnisse nutzen bzw. anlegen.

bin

Scripte zur Verwaltung des Repository und des Wiki. Hier sind normalerweise keine Änderungen nötig.

htdocs

Wird erzeugt, wenn build.sh läuft. Hier findet man dann die generierte Website im HTML Format. Diese kann man lokal im Browser öffnen und sich schon mal anschauen, wie die Seiten dann später aussehen. Hier nichts ändern, die Änderungen gehen bei der nächsten Ausführung des Scripts verloren. Dieses Verzeichnis landet nicht im Git.

tmp

Wird erzeugt, wenn build.sh läuft und dient nur für temporäre Dateien. Dieses Verzeichnis landet nicht im Git.

Tipps und Tricks

  • Syntax-Highlighting für vim: http://www.methods.co.nz/asciidoc/chunked/ape.html

    • Wenn seit der Umstellung der Dateieindung auf .asciidoc das Syntaxhighlighting nicht mehr funktioniert kann in /usr/share/vim/vim73/filetype.vim folgendes zur strikten Erkennung des Dateityps eingefügt werden:

        " asciidoc
        au BufNewFile,BufRead *.asciidoc                setf asciidoc

Vielen Dank an den Sponsor dieses Servers NETWAYS Web Service