Merge branch 'master' of scm.cms.hu-berlin.de:ibi/python

styleguide.md

 # Styleguide für die Migration auf ThinkPython3
-Wir haben ein paar wichtige Punkte gesammelt und hier im Styleguide aufgeschrieben. Diese haben sich im Iterativen Prozess der Aufbereitung der Notebooks ergeben. Es gibt noch viele andere wichtige Dinge zu beachten, die hier nicht festgehalten sind.
+Wir haben ein paar wichtige Punkte gesammelt und hier im Styleguide
+aufgeschrieben. Diese haben sich im iterativen Prozess der
+Aufbereitung der Notebooks ergeben. Es gibt noch viele andere wichtige
+Dinge zu beachten, die hier nicht festgehalten sind. Bitte ergänzt
+diesen Styleguide daher.
 
 ## "Download"-Codezelle
-Dies ist meist die erste Codezelle in den ThinkPython3 Notebooks. Diese dient dazu, Skripte herunterzuladen für Zusatz-Funktionen innerhalb der Notebooks wie bspw.:
-- %%expect Befehl
-- Erstellung von State-Diagrammen
+Dies ist meist die erste Codezelle in den ThinkPython3-Notebooks. Diese dient dazu, Skripte herunterzuladen für Zusatz-Funktionen innerhalb der Notebooks wie bspw.:
+- `%%expect` Befehl
+- Erstellung von Zustandsdiagrammen (State-Diagrams)
 - Nutzung von Turtle in den Notebooks
-Bitte diese Zelle immer übernehmen und die entsprechenden Zellen im Notebook wo diese angewendet werden ebenfalls. Dies ist sichtbar durch das entsprechende Import-Statement (bspw. `import thinkpython`).
+Bitte diese Zelle immer übernehmen und die entsprechenden Zellen im Notebook wo diese angewendet werden ebenfalls. Den `%%expect` Befehl erkennt man in den Zellen (steht direkt am Anfang). Die
+Zustandsdiagramme erkennt man am `from diagram import ...` wie bspw. `from diagram import make_binding, Frame` und natürlich den anschließenden Verwendungen der entsprechenden Funktionen und Objekte wie hier bspw. `make_binding` und `Frame`. `jupyturtle` erkennt man an `import jupyturtle` und den entsprechenden Funktionsaufrufen.
+
+## "%xmode"-Codezelle
+Diese Codezelle befindet sich vor den Aufgaben. Sie sollte immer vor die Aufgaben übernommen werden, da sie einen erweiterten Output liefert der sehr nützlich ist für das Debuggen während der Aufgaben.
 
 ## Inhaltsverzeichnisse
-Zuvor hatten wir Inhaltsverzeichnisse in den Notebooks, die manuell erstellt wurden (bzw. mit einem Plug-in). Da in der neusten Version von Jupyter Notebooks (`Notebook 7`) solche Inhaltsverzeichnisse automatisch anhand der Markdown Überschriften generiert werden, ist die manuelle Generierung der Inhaltsverzeichnisse nicht mehr notwendig.
+Zuvor hatten wir Inhaltsverzeichnisse in den Notebooks, die manuell erstellt wurden (bzw. mit einem Plug-in). Da in der neusten Version von Jupyter-Notebooks (`Notebook 7`) solche Inhaltsverzeichnisse automatisch anhand der Markdown-Überschriften generiert werden, ist die manuelle Generierung der Inhaltsverzeichnisse nicht mehr notwendig.
 
 ## Unsere zusätzlichen Inhalte
 Wir haben öfter auch zusätzliche Inhalte in unseren Notebooks, welche nicht in der entsprechenden ThinkPython Version enthalten sind. Wir versuchen so viele der zusätzlichen Inhalte von zuvor auch in den neuen Notebooks zu übernehmen. Wichtig ist dabei, dass die zusätzlichen Inhalte zu den jeweiligen Notebooks passen. Bei Unsicherheiten, sammelt diese Fälle und wir können sie später diskutieren.
@@ -19,13 +27,13 @@ Wir verwenden in den Erklär-Teilen immer *wir*. Bspw. " ... hier lernen wir XYZ
 
 ## Begriffe im Glossar
 In den Notebooks ist ein Glossar enthalten. Gerade bei diesen Begriffen ist die Übersetzung sehr wichtig und manchmal nicht direkt die erste die in den Sinn kommt. Ein Beispiel für einen solchen "false friend" ist "Exekution" als Übersetzung für "execution". Hierbei ist "Ausführung" richtig.
-Diese Begriffe bitte **verdeutlichen** wenn sie eingeführt bzw. definiert werden. Beispiel: Eine Ansammlung von Operatoren und Zahlen heißt **Ausdruck**. 
+Diese Begriffe bitte **verdeutlichen** wenn sie eingeführt bzw. definiert werden. Beispiel: Eine Ansammlung von Operatoren und Zahlen heißt **Ausdruck**.
 
 ## Hervorhebung in Aufzählungen
 Hier verwenden wir *die kursive Hervorhebung*. Beispiel: Eine Zuweisung hat drei Bestandteile: den *Namen* der Variable ganz links, ein *Gleichheitszeichen*, `=`, und einen *Ausdruck* auf der rechten Seite.
 
 ## Direkte Verweise auf Zellen
-Wenn ein Markdown Text direkt auf die darauffolgende Zelle verweist, dann sollen diese mit *:* enden. Beispiel: Und im nächsten Beispiel ist der Ausdruck eine Zeichenkette:
- 
+Wenn ein Markdown-Text direkt auf die darauffolgende Zelle verweist, dann sollen diese mit *:* enden. Beispiel: Und im nächsten Beispiel ist der Ausdruck eine Zeichenkette:
+
 ## Weitere Beispiele für Formatierungen
 Ein Beispiel findet sich in [diesem Commit](https://scm.cms.hu-berlin.de/ibi/python/-/commit/1653c5b37a17dca5cf7072198f32729d83be3b80) und in [diesem hier](https://scm.cms.hu-berlin.de/ibi/python/-/commit/4decf0cf5a29f9d07f32e3bba0c7d4c6d6dbdc40). Bitte hier die Entfernung von `python` im Markdown-Code ignorieren. Das ist nicht notwendig.