sonst_git-fortbildung/Asciidoc.adoc

ASCII-Doc

AsciiDoc ist ein leichtgewichtiges Markup-Format, das speziell entwickelt wurde, um Dokumentationen zu erstellen. Es ist einfach zu schreiben und zu lesen, sowohl im Rohformat als auch im endgültigen gerenderten Format. AsciiDoc-Dateien können in verschiedene Ausgabeformate wie HTML, PDF, DocBook und andere umgewandelt werden, was es zu einem flexiblen Werkzeug für Entwickler, Autoren und auch für Lehrer macht.

Sinn und Vorteile von AsciiDoc:
Einfachheit und Lesbarkeit: AsciiDoc ist textbasiert und leicht zu schreiben, was es ideal für die Zusammenarbeit und Versionskontrolle (durch GIT) macht. Der Text bleibt auch ohne Formatierung leicht lesbar.
Flexibilität: AsciiDoc kann in verschiedene Ausgabeformate konvertiert werden, was es zu einem vielseitigen Werkzeug für die Dokumentation in verschiedenen Kontexten macht.
Vollständige Dokumentation: Es unterstützt fortgeschrittene Dokumentationsfunktionen wie Tabellen, Listen, Quellcode-Hervorhebung, Bilder und vieles mehr.
Integration in Entwicklungstools: AsciiDoc ist oft in Entwicklungsumgebungen (z. B. auch GitCamp) integriert und kann leicht in Projekten verwendet werden, die auf Softwareentwicklung fokussiert sind.

Nachteil: 
Es ist unmöglich exakte Positionen von Texten oder Bildern auf einer Seite anzugeben. Daher ist es für klassische Arbeitsblätter in der Schule nur bedingt geeignet.

Wir streben daher an, zukünftiges Unterrichtsmaterial im ASCII-Doc Format zu veröffentlichen. Ein Gesamt-Export als pdf wird zusätzlich bereitgestellt.
Sie können aber auch einzelne Kapitel in ein pdf-Dokument überführen. In jedem Dokument können am Anfang einige Einstellungen vorgenommen werden. Sie können entscheiden, ob das erzeugte pdf-Dokument die Kommentare für Lehrer enthalten soll oder nicht. Gleiches gilt für die Lösungen. In der Tablet-Version wird ausreichend Platz direkt nach den Aufgaben gelassen, dass die Schülerinnen und Schüler ihre Lösungen direkt in das Dokument hineinschreiben können. 

Im Hauptdokument können Sie außerdem wählen, welche Kapitel integriert werden soll. Damit können Sie Ihren Unterricht individuell gestalten.

Grundlegende Formatierungen in AsciiDoc
Hier sind einige grundlegende Formatierungen, die häufig in AsciiDoc verwendet werden:

Überschriften:
Überschriften werden durch ein oder mehrere Gleichheitszeichen `=` gefolgt von einem Leerzeichen und dem Titel markiert.
Absätze:
Ein normaler Textabsatz wird einfach durch eine leere Zeile vom vorhergehenden und nachfolgenden Text getrennt. Eine neue Zeile bekommt man durch ein Leerzeichen gefolgt von einem `+` am Ende einer Zeile.
Fettschrift und Kursivschrift:
Text kann fett oder kursiv formatiert werden, indem er in Sternchen oder Unterstriche eingeschlossen wird.
Listen:
Ungeordnete Listen werden mit einem Sternchen `*` vor jedem Listenpunkt eingeleitet. Eine Unterliste kann mit einem zweiten Sternchen erzeugt werden. Wichtig ist, dass die Zeile vor und nach der Liste leer sein muss.
Geordnete Listen werden mit einem Punkt eingeleitet. Auch hier können Unterebenen mit mehreren Punkten gekennzeichnet werden.
Links:
Eine URL wird automatisch als Link interpretiert. Steht hinter der URL ein `[` und schließt sich mit einem `]`, wird der Text zwischen den eckigen Klammern als Linktext interpretiert.
Bilder:
Bilder können mit dem `image::`-Schlüsselwort eingebunden werden. Danach muss der Name des Bildes folgen.
Codeblöcke:
Codeblöcke können mit drei Backticks ````` oder durch Einrücken mit vier Leerzeichen erstellt werden. 
console.log("Dies ist ein Codeblock");

Tabellen:
   Tabellen werden durch `|===` eingeleitet und beendet. Innerhalb der einzelnen Zeilen werden die Zellen durch `|` getrennt.

Name  Alter  Beruf
Max   29     Entwickler
Anna  34     Designerin

Genauere Informationen gibt es bei docs.asciidoctor.org/asciidoc/latest/ .

Verwendung von ASCII-Doc
ASCII-Doc-Texte können sie mit einem einfachen Texteditor editieren. Für größere Änderungen empfiehlt sich die Verwendung von [Visual Studio Code](https://code.visualstudio.com/) mit der Extension Asciidoc oder von [AsciidocFX](https://github.com/asciidocfx/AsciidocFX). Beide Programme zeigen die formatierte Ausgabe fortlaufend während der Bearbeitung des Codes an. Möglicherweise machen dabei die mathematischen Formeln oder die Diagramme Probleme, die Erweiterungen der normalen Asciidoc Syntax darstellen. Beim Konvertieren in pdf-Dokumente werden diese aber korrekt dargestellt.

Konvertierung
Die Konvertierung in pdf-Dokumente ist bei Verwendung von mathematischen Formeln nicht ganz einfach, da die notwendige Erweiterung nur in einer bestimmten Linux-Version läuft. Sie funktioniert aber gut, wenn man den vorinstallierten Docker-Container verwendet.

Installieren Sie dazu das [Docker-System](https://docs.docker.com/get-docker/). Suchen Sie innerhalb des Docker-Programms nach dem Image asciidoc/docker-asciidoc und laden Sie es herunter. Unter Windows starten Sie dann in einer Powershell das Docker-Image: 
```
docker run -it -v F:/informatik/KuenstlicheIntelligenz/MLGit:/documents/ asciidoctor/docker-asciidoctor
```
Dabei wird in diesem Beispiel der Ordner F:/Informatik/KuenstlicheIntelligenz/MLGit mit dem Docker-Container verbunden und steht dort im Standard-Verzeichnis /documents zur Verfügung.

Mit dem folgenden Befehl wird dann das .adoc-File in ein pdf-Dokument übersetzt:
```
asciidoctor-pdf -R "." -o "maschine-learning-schueler.pdf" -a allow-uri-read -a imagesoutdir=./.asciidoctor/stem -r asciidoctor-diagram -r asciidoctor-mathematical machine-learning.adoc
```

Tippfilter

In Schülerprogrammen werden wir außerdem Tippfilter-Auszeichnungen verwenden, die es erlauben, aus der fertigen Version eine Rohversion für die Schüler zu erstellen. Sie können die Rohversion automatisiert durch das Batchfile "Erzeuge-Roh.bat" erstellen lassen.

Alternativ können Sie die Erzeugung auch selbst mit Hilfe der _tippfilter.jar_ im Unterordner _tippfilter_ starten. Ausgangsordner für den folgenden Befehl ist der Ordner _perzeptron_:
```
java -jar ../tippfilter/tippfilter.jar or=./java-perzeptron de=./perzeptron-rohversion zielgruppe=roh configfile=bluej.tippfilter
```
Erläuterungen zum Tippfilter finden Sie in der Hilfedatei im Ordner _tippfilter_.