From 09666c23ee7c93ebb3c3c1d79451387d575d97bf Mon Sep 17 00:00:00 2001
From: Robin Sonnabend <robin@fsmpi.rwth-aachen.de>
Date: Sun, 26 Feb 2017 23:32:37 +0100
Subject: [PATCH] documentation
---
server.py | 5 ++
templates/documentation.html | 166 +++++++++++++++++++++++++++++++++++
templates/layout.html | 3 +
views/forms.py | 2 +-
4 files changed, 175 insertions(+), 1 deletion(-)
create mode 100644 templates/documentation.html
diff --git a/server.py b/server.py
index 2751f41..cbe9fd0 100755
--- a/server.py
+++ b/server.py
@@ -109,8 +109,13 @@ def index():
todos_table = TodosTable(todos) if todos is not None else None
return render_template("index.html", open_protocols=open_protocols, protocol=protocol, todos=todos, todos_table=todos_table)
+@app.route("/documentation")
@login_required
+def documentation():
+ return render_template("documentation.html")
+
@app.route("/types/list")
+@login_required
def list_types():
is_logged_in = check_login()
user = current_user()
diff --git a/templates/documentation.html b/templates/documentation.html
new file mode 100644
index 0000000..a1d66e6
--- /dev/null
+++ b/templates/documentation.html
@@ -0,0 +1,166 @@
+{% extends "layout.html" %}
+{% from "macros.html" import render_table %}
+{% block title %}Dokumentation{% endblock %}
+
+{% block content %}
+<div class="row">
+ <div id="left-column", class="col-lg-6">
+ <h3>Protokollsystem</h3>
+ Das Protokollsystem dient der Planung von Sitzungen und Verwaltung von Protokollen. Die anstehenden Sitzungen der nächsten Woche sind auf der <a href="{{url_for("index")}}">Startseite</a>, alle Protokolle unter <a href="{{url_for("list_protocols")}}">Protokolle</a> zu finden.
+ <h4 id="planung">Sitzungsplanung</h4>
+ Sollte das Protokoll noch nicht existieren:
+ <ol>
+ <li>Gehe auf <a href="{{url_for("new_protocol")}}">Neu</a></li>
+ <li>Wähle bei „Typ“ den Typ der Sitzung aus.</li>
+ <li>Gib das Datum der Sitzung ein.</li>
+ <li>Anlegen</li>
+ </ol>
+ Wenn es existiert:
+ <ol>
+ <li>Gehe auf <a href="{{url_for("list_protocols")}}">Protokolle</a></li>
+ <li>Wähle die Sitzung aus. Noch ausstehende Sitzungen sind ganz oben.</a>
+ </ol>
+ Auf der Seite der Sitzung siehst du die Tagesordnung.
+ <ul>
+ <li>Die ersten und letztes TOPs sind Standard-TOPs, die jede Sitzung hat. Die kannst du nur über beim Protokolltyp ändern, nicht beim Protokoll selbst.</li>
+ <li>Die mittleren TOPs gehören nur zu dieser Sitzung. Du kannst welche hinzufügen oder sie umsortieren.</li>
+ <li>Solltest du die TOPs nicht bearbeiten können, handelt es sich um ein Protokoll, das du lesen, aber nicht bearbeiten kannst. Mehr dazu bei <a href="#Rechteverwaltung">Rechteverwaltung</a>.</li>
+ </ul>
+ <h4 id="wie">Wie schreibe ich eine Protokoll?</h4>
+ <ol>
+ <li>Protokoll auswählen (s.o.)</li>
+ <li>mit „In Etherpad“ die Vorlage in das Etherpad schreiben.</li>
+ <li>mit „Etherpad“ das Etherpad öffnen</li>
+ <li>verlese Tagesordnung und Todos</li>
+ <li>falls Todo erledigt, markiere als erledigt (Details siehe <a href="#Todos">Todos</a></li>
+ <li>schreibe das Protokoll im Etherpad</li>
+ <li>Importiere das Protokoll am Ende mit „Aus Etherpad“</li>
+ <li>Falls Fehler auftreten, behebe sie (siehe <a href="#Fehler">Fehler</a></li>
+ <li>Wenn keine Fehler mehr auftreten, drucke das Protokoll mit „Löschen” (unten beim Anhang) aus.</li>
+ <li>Korrekturlesen lassen und im Etherpad korrigieren, dann nochmal „aus Etherpad“</li>
+ <li>drucken, abheften und per Mail versenden</li>
+ </ol>
+ <h4 id="fehler">Was, wenn etwas nicht funktioniert?</h4>
+ <ul>
+ <li>Typische Web-Fehler (404, 500, etc.) sollten nicht auftreten. Wenn sie es doch tun, wende dich bitte an die <a href="mailto:{{config.ADMIN_MAIL}}">Admins</a></li>
+ <li>Wenn beim Parsen, Kompilieren, versenden, hochladen, … Fehler auftreten, werden sie aufgelistet. Die Fehler aller Protokolle findest du unter <a href="{{url_for("list_errors")}}">Fehler</a>. Bei sehr langen Beschreibungen (z.B. LaTeX-Kompilierfehlern) solltest du den einzelnen Fehler anklicken, um die ganze Beschreibung zu erhalten.</li>
+ <li>Wenn die Fehlerbeschreibung dir nicht ausreicht, um den Fehler zu beheben, wende dich an jemand erfahreneren und lass dir helfen.</li>
+ </ul>
+ <h4 id="todos">Todosystem</h4>
+ Das Protokollsystem verwaltet Todos über mehrere Protokolle hinweg. Offene Todos werden in die Protokollvorlage eingefügt.
+ <ul>
+ <li>Jedes Todo hat eine (oder durch Kommata oder Leerzeichen getrennt mehrere) Personen, die es erledigen sollen.</li>
+ <li>Todos haben auch einen Zustand, in dem sie sich befinden. Es gibt:
+ <ul>
+ {# todo: list states #}
+ </ul>
+ </li>
+ <li>Alle Todos findest du unter <a href="{{url_for("list_todos")}}">Todos</a>.</li>
+ </ul>
+
+ <h4 id="suche">Suche</h4>
+ <a href="{{url_for("list_protocols")}}">Protokolle</a>, <a href="{{url_for("list_todos")}}">Todos</a> und <a href="{{url_for("list_decisions")}}">Beschlüsse</a> können durchsucht werden.
+ Im Suchfeld können mehrere durch Leerzeichen getrennte Suchbegriffe angegeben werden: <code>Begriff1 Begriff2</code>.
+ Angezeigt werden alle Ergebnisse, die jeden der Suchbegriffe (unabhängig von Groß- oder Kleinschreibung) enthalten.
+ Wenn ein Suchbegriff ein Leerzeichen beinhaltet, muss er mit Anführungszeichen umrandet werden: <code>"Begriff1 mit Leerzeichen" Begriff2</code>.
+
+ <h4 id="rechte">Rechteverwaltung</h4>
+ Das Protkollsystem hat ein Konzept von Rechteverwaltung, dass auf den Benutzergruppen im LDAP basiert.
+ Rechte werden pro Protokolltyp eingestellt.
+ Die vorhandenen Rechtestufen sind „Darf öffentliche Version einsehen“, „Darf interne Version einsehen“ und „Darf Ändern“.
+ Jedes Protokoll hat eine öffentliche Gruppe, eine interne Gruppe und eine Einstellung, ob es öffentlich ist.<br>
+
+ Die öffentliche Version einsehen dürfen:
+ <ul>
+ <li>Nicht authentifizierte Nutzer, wenn der Protokolltyp „Öffentlich“ eingestellt ist.</li>
+ <li>Authentifizierte Nutzer auch dann, wenn es nicht „Öffentlich“ eingestellt ist, aber sie die „Öffentliche Gruppe“ oder die „Interne Gruppe” des Protokolltyps haben. Wenn keine Gruppe eingestellt ist, kann auch kein Nutzer diese haben.</li>
+ </ul>
+ Die interne Version einsehen dürfen:
+ <ul>
+ <li>Authentifizierte Nutzer, wenn sie die „Interne Gruppe” des Protokolls haben.</li>
+ </ul>
+ Das Protokoll bearbeiten dürfen alle, die die interne Version einsehen dürfen.<br>
+
+ Vom Protokoll wird eine interne und eine öffentliche Version generiert, wenn es Inhalte gibt, die nur intern sind.
+ Todos sind generell intern, Beschlüsse sind generell öffentlich (d.h. einsehbar, wenn man das Recht „Darf öffentliche Version sehen“ hat).
+ </div>
+ <div id="right-column", class="col-lg-6">
+ <h3 id="syntax">Syntax</h3>
+ Ein Dokument beginn mit einigen Metadaten, danach kommen nacheinander die Tagesordnungspunkte, die durch Listen strukturiert sind.
+ Darüberhinaus gibt es Tags, mit denen URLs, Beschlüsse oder ToDos markiert werden können.
+
+ <h4 id="metadaten">Metadaten</h4>
+ Die Syntax der Metadaten ist <code>#Name;Wert</code> und die einzelnen Einträge werden durch Zeilenumbrüche getrennt. Folgende Metadaten werden unterstützt und sollten angegeben werden:
+ <ul>
+ <li><code>#Datum;01.01.2017</code> Das Datum der Sitzung</li>
+ <li><code>#Anwesende;Gustav, Geier</code> Alle anwesenden Personen</li>
+ <li><code>#Beginn;19:00</code> Beginn der Sitzung</li>
+ <li><code>#Ende;21:42</code> Ende der Sitzung</li>
+ <li><code>#Autor;Gustav</code> Autor (oder Autoren) des Protokolls</li>
+ <li><code>#Ort;Fachschaft</code> Ort der Sitzung
+ </ul>
+ <h4 id="tops">Tagesordnungspunkte</h4>
+ Ein TOP besteht aus einem Titel und beliebigem Inhalt.
+ Ein TOP ist eine besondere Liste und kann somit wie eine Liste verwendet werden.
+<pre>
+{TOP Tagesordnungspunkt
+ Inhalt;
+}
+</pre>
+ <h4 id="liste">Liste</h4>
+ Die Liste ist das einzige strukturierende Element.
+ Liste können (quasi) beliebig geschachtelt werden (bis LaTeX nicht mehr will).
+ Die Elemente der Liste werden durch Semikolons getrennt.
+<pre>
+{TOP Tagesordnungspunkt
+ Zeile mit Text drin;
+ Hier eine geschachtelte Liste: {
+ Details zu diesem Punkt.;
+ Mehr Details zu diesen Punkt.;
+ };
+ Und ein anderer Punkt.;
+};
+</pre>
+
+ Text, der vor der öffnenden Klammer <code>{</code> oder in derselben Zeile hinter der Klammer steht, wird als Name der Liste angesehen.
+ Listen in der höchsten Ebene müssen TOPs sein.
+{% if config.PRIVATE_KEYWORDS|length > 0 %}
+ <h4 id="intern">Interne Abschnitte</h4>
+ Wenn der Name einer Liste (bis auf Leerzeichen und einen optionalen <code>:</code>) eins aus
+ <code>{{config.PRIVATE_KEYWORDS|join(" ")}}</code>
+ ist, ist diese Liste intern.
+ Daher wird sie nur in der internen Version des Protokolls angezeigt.
+<pre>
+{TOP Tagesordnungspunkt
+ Dieser Punkt ist öffentlich.;
+ {{config.PRIVATE_KEYWORDS[0]}}: {
+ Dieser Punkt ist intern.;
+ Dieser auch.;
+ };
+ Dieser ist wieder öffentlich.;
+}
+</pre>
+
+ <h4 id="tag">Tags</h4>
+ Tags können Text besonders hervorheben oder bestimmte Aktionen ausführen.
+ Die grundsätzliche Syntax ist <code>[Name;Arg1;Arg2;…]</code>, wobei theoretisch beliebig viele Argumente angegeben werden können.;
+ <h5>URL-Tag</h5>
+ Mittel <code>[url;https://protokolle.fsmpi.rwth-aachen.de ]</code> kann ein entsprechend formatierter Link eingebunden werden.
+ Das Leerzeichen am Ende ist nicht notwendig für das Protokollsystem, erleichtert aber das Anklicken im Etherpad.
+ <h5>Beschluss-Tag</h5>
+ <code>[beschluss;Wir beschließen etwas tolles.]</code> erzeugt einen Beschluss im Protokoll.
+ Ein Beschluss wird zusätzlich am Anfang des Protokoll angezeigt.
+ Die Beschlüsse sind online durchsuchbar.
+ <h5>Todo-Tag</h5>
+ In den Protokollen können <a href="#todos">Todos</a> verwaltet werden.
+ Ein neuer Todo wird mit <code>[todo;Name;Aufgabe]</code> angelegt.
+ Dieser ist dasnn online und in den Mails sichtbar.
+ Falls der Name einer Mail <a href="{{url_for("list_todomails")}}">zugeordnet</a> ist, wird diese Person (oder AG, AK, …) per Mail über ihre offenen Todos informiert.
+ Mehrere Personen können durch Leerzeichen oder Kommata getrennt angegeben werden.
+
+ Ein bereits bestehender Todo wird mit der zusätzlichen Option <code>[…;id 1338]</code> in ein neues Protokoll eingefügt. Wird dieser Todo dann geändert, passiert das auch im Protokollsystem.
+ Außerdem kann der Status des Todos, z.B. <code>[…;done;…]</code> angegeben werden.
+{% endif %}
+ </div>
+</div>
+{% endblock %}
diff --git a/templates/layout.html b/templates/layout.html
index c8b88d0..8ea321b 100644
--- a/templates/layout.html
+++ b/templates/layout.html
@@ -66,6 +66,9 @@ Diese Seite ist leer.
{% endblock %}
</div>
+<footer>{# todo: check how to make a footer in bootstrap #}
+ <a href="{{url_for("documentation")}}">Dokumentation</a>
+</footer>
<script src="{{url_for("static", filename="js/jquery.min.js")}}"></script>
<script src="{{url_for("static", filename="js/bootstrap.min.js")}}"></script>
</body>
diff --git a/views/forms.py b/views/forms.py
index 6e91d33..bf8d363 100644
--- a/views/forms.py
+++ b/views/forms.py
@@ -104,7 +104,7 @@ class NewTodoForm(FlaskForm):
self.protocoltype_id.choices = get_protocoltype_choices(protocoltypes, add_all=False)
class TodoForm(FlaskForm):
- who = StringField("Person", validators=[InputRequired("Bitte gib an, wer das Todo erledigen soll.")])
+ who = StringField("Person")
description = StringField("Aufgabe", validators=[InputRequired("Bitte gib an, was erledigt werden soll.")])
tags = StringField("Weitere Tags")
done = BooleanField("Erledigt")
--
GitLab