Add substantial content to README.md

README.md

@@ -1,3 +1,76 @@
-# flask-website
+Website auf Jinja2-Basis
+=========================
+
+Die Website auf Mason2-Basis (bzw. Mason1 auf der digi-Instanz) soll durch eine
+Eigenimplementierung auf Jinja2 migriert werden.
+
+Jinja2 läuft auf Django- oder auf Flask-Basis. Wir bevorzugen Flask, da wir
+mutmaßlich keine Datenbank brauchen werden, worauf das mächtigere Django
+stark ausgerichtet ist. Flask ist in der Beziehung leichtgewichtiger.
+
+`flask`
+-----------
+
+Unser auf Jinja2-basierter Application Server mit flask.
+
+
+`templates` und Layoutkaskaden
+----------------------------------
+
+`**/layout.jtml` heißen die kaskadenartig angewendeten Layoutdateien. Wird eine normale Seite mit der
+Dateinamensendung `.html` aufgerufen, wird zunächst versucht, eine Datei namens `layout.jtml` aus dem
+gleichen Verzeichnis zu laden. Schlägt dies fehl, wird die Suche auf der nächsthöheren Verzeichnisebene
+fortgesetzt, und so weiter. Das gleiche geschieht, wenn für eine `layout.jtml` wiederum die nächsthöhere
+gefunden werden soll, aber nur solange jeweils die erste Zeile darin lautet:
+
+    {% extends layout() %}
+
+Anstelle von `layout()` kann auch der Dateipfad von einem beliebigen anderen Template stehen.
+Dieses wird dann verwendet. Enthält es aber selbst wiederum `{% extends layout() %}`, wird zu derselben
+Kaskade zurückgekehrt, als würde es in der eigentlich aufgerufenen Seite stehen.
+Jedwedes direkt angegebene Template außer `layout()` schiebt sich gewissermaßen zwischen
+die aufgerufene Seite und die weitere, normale Layoutkaskade.
+
+`DSL.*`
+-------
+
+Jinja2-Migrationen der Mason-Snippets (`<& /nav1/img, name => "neu" &>`) sind aufrufbar wie folgt:
+
+    `{{ DSL.img(name="neu") }}`
+
+
+Sprachinfix
+-----------
+
+Der Dateiendung der aufgerufenen Seite kann ein `de.`, `en.`, `fr.` oder `it.` vorangehen. Weitere
+Sprachen können jederzeit hinzugefügt werden. Da es aber auch Top-Level-Verzeichnisse mit zwei
+Buchstaben langen Namen geben kann (z.B. `nc/`), werden nur registrierte Sprachkürzel nach dieser
+Logik berücksichtigt.
+
+Erscheint in der URL als erstes Pfadsegment nach der Domain ein Sprachinfix (statt "en" geht
+auch "Englisch/", "English", groß oder klein geschrieben), so wird bevorzugt die
+entsprechende Fassung aufgerufen.
+
+Alternativ, sollte die angefragte Fassung der Seite nicht gefunden werden, wird die englische bzw. die
+deutsche Fassung genommen.
+
+Aufrufe der Funktion `DSL.i18n(de="Text in deutscher Sprache", en="...", ...)` lösen sich entsprechend
+der gefundenen Fassung auf, wenn der Textstring in der angefragten Sprache nicht verfügbar ist. Danach
+wird die englische, dann die deutsche Fassung probiert.
+
+Gleiches gilt für `DSL.i18n` im Filtermodus: `{% filter DSL.i18n %}...{% endfilter %}` kann immer dann
+benutzt werden, wenn für unterschiedliche Sprachen verschiedene HTML-Markups verwendet werden sollen. Alle
+von diesem Filter umfassten Inhalte werden gefiltert nach Elementen mit lang-Attribut. Nur diejenigen
+dieser Elemente, die auf die angefragte bzw. gefundene Sprachfassung passen, werden samt Inhalt angezeigt.
+
+
+Markdown
+--------
+
+Es wird ein Filter `markdown` definiert. In der Layout-Datei kann man diesen wie folgt nutzen:
+
+    {% filter markdown %}
+    {% block content %}Diese Seite hat keinen Inhalt, denn es ist nur die layout.jtml-Datei.{% endblock %}
+    {% endfilter %}
+
 
-Application Gateway uwsgi, Application Webserver flask und Template Engine jinja2 konfiguriert und programmiert.