chore: Dokumentation und Beispiele

Author: RamonDevPrivate

README.TurtleProgramming.png

@@ -1,16 +1,20 @@
 # _Live View Programming_ mit jeder Programmiersprache
 
-Das _Live View Programming_ (LVP) bietet Ihnen für die Programmierung ein einfaches Textprotokoll an, um mediale Inhalte im Web-Browser darzustellen, also Texte, Bilder, Grafiken, Videos, inteaktive Animationen etc. Kommandos stellen auch nützliche Fähigkeiten bereit, die man z.B. zur Dokumentation von Code gebrauchen kann.
+Live View Programming (LVP) stellt ein einfaches Textprotokoll bereit, mit dem sich mediale Inhalte direkt im Web-Browser darstellen lassen, darunter Texte, Bilder, Grafiken, Videos und interaktive Animationen.
+
+Das Protokoll dient als sprachunabhängige Schnittstelle zwischen Ihrem eigenen Programm und LVP. Die Kommunikation erfolgt über Kommandos, die durch gewöhnliche Konsolenausgaben erzeugt werden. Diese Kommandos können Inhalte transformieren und sie im Browser medial aufbereitet anzeigen.
+
+Auf diese Weise stellt LVP praktische Funktionen bereit, die sich beispielsweise für die Code-Dokumentation, die Erzeugung von Turtle-Grafiken oder das Erstellen interaktiver HTML-Elemente nutzen lassen.
+
 
-**Eine detaillierte Übersicht des Protokolls mit allen Kommandos folgt noch.**
 
 ## 🚀 Nutze das _Live View Programming_
 
 Wenn Sie das _Live View Programming_ ausprobieren möchten, ist Folgendes zu tun:
 
 ### 1. Lade die `.jar`-Datei herunter
 
-* Stellen Sie sicher, dasss Sie mit einem aktuellen JDK (Java Development Kit) arbeiten; es empfiehlt sich das [TemurinJDK](https://adoptium.net/temurin/releases/)
+* Stellen Sie sicher, dasss Sie mit einem aktuellen JDK (Java Development Kit) arbeiten; es empfiehlt sich das [OpenJDK](https://jdk.java.net/25/)
 * Laden Sie die aktuelle `.jar`-Datei herunter, die Ihnen als Asset zum [aktuellen Release](https://github.com/denkspuren/LiveViewProgramming/releases) als Download angeboten wird; die Datei hat den Namen `lvp-<Version>.jar`
 * Laden Sie `demo.java`-Datei herunter, die Ihnen ebenfalls als Asset zum [aktuellen Release](https://github.com/denkspuren/LiveViewProgramming/releases) als Download angeboten wird.
 
@@ -56,26 +60,74 @@ java -jar lvp-1.0.0.jar --log demo.java
 > Mehrere Argumente können kombiniert werden, z.B.:  
 > `java -jar lvp-<Version>.jar --watch-filter=src/lib/**/*.java --log=Debug --port=50001 --config src/*View.java`
 
-### 3. So nutzt man das _Live View Programming_
+### 3. Einbinden von Quellen
+Damit eigene Programme mit LVP kommunizieren können, werden sie innerhalb von LVP als Laufzeitumgebung ausgeführt. Diese Programme werden im Kontext von LVP als Quellen bezeichnet.
+
+Die Programme selbst benötigen keine zusätzlichen Abhängigkeiten und können in beliebigen Programmiersprachen geschrieben sein. Es gibt zwei Möglichkeiten, Quellen in LVP zu definieren.
+
+#### Variante 1: Übergabe über die Konsole
 
-Die Datei `demo.java` dient als einfaches Beispiel für den Einstieg in das Live View Programming (LVP).  
+Wie oben gezeigt, können Quellen als Argument beim Konsolenaufruf übergeben werden. Dabei lassen sich beliebig viele Quellen definieren. Alle angegebenen Quellen werden mit dem über --cmd übergebenen Befehl ausgeführt.
 
-Damit LVP funktioniert, **muss der Server die Datei beobachten (watchen)** – sobald Änderungen erkannt werden, wird der Code automatisch neu ausgeführt und die Ausgabe aktualisiert.
+Wird das Argument `--cmd` nicht gesetzt, versucht LVP standardmäßig, die Quellen als Java-Programme auszuführen.
 
-Innerhalb einer [`void main()`-Methode](https://openjdk.org/jeps/495) lassen sich interaktive Inhalte erzeugen, indem man `println`-Ausgaben entsprechend dem Protokoll erzeugt. Diese Inhalte werden anschließend im Browser angezeigt.
+#### Variante 2: Konfigurationsdatei (sources.json)
 
-**Beispiel:**
+Bei einer größeren Anzahl von Quellen oder wenn Quellen unterschiedlich gestartet werden sollen (z. B. mit verschiedenen Startbefehlen), empfiehlt sich die Verwendung einer sources.json-Datei im Wurzelverzeichnis der Ausführung.
 
+Wird LVP mit dem Argument `--config` gestartet, werden die in dieser Datei definierten Quellen zusätzlich ausgeführt.
+
+Ein Beispiel für den Aufbau der Datei befindet sich im Ordner examples.
+
+Beide Varianten lassen sich auch kombinieren.
+
+### 4. Das Protokoll
+Im Folgenden eine grobe Übersicht über den generellen Aufbau des Protokolls. Ein ausführlicheres Beispiel finden Sie in `demo.java`, sowie weitere kleine Beispiele in dem Ordner `examples`.
+
+Einzeilige Kommandos:
 ```java
-import lvp.Clerk;
+println("Markdown: # Ich bin eine Überschrift");
+```
 
-void main() {
-    println("Markdown: # Hello World");
-}
+Mehrzeilige Kommandos:
+```java
+println("""
+  Markdown:
+  # Ich bin eine Überschrift
+  Ich bin **Text**.
+  ~~~
+""");
 ```
-Dieser einfache Aufruf rendert eine Markdown-Überschrift direkt im Browser. Weitere Ausgaben, Grafiken oder Interaktionen können durch zusätzliche Kommandos ergänzt werden.
+Kommandos bestehen aus einem Namen und einem Inhalt. Dabei wird zwischen einzeiligen und mehrzeiligen Kommandos unterschieden. Ein mehrzeiliges Kommando wird durch `~~~` beendet.
+
+<br/>
+
+```java
+println("""
+  Text[template]:
+  ## Beispiel
+  Irgendein ${0} anzeigen.
+  ~~~
+  | Markdown
+
+  Text: Beispiel
+  | Text[template] | Markdown
+""")
+
+```
+Durch Piping können die Ergebnisse eines Kommandos an ein anderes Kommando weitergegeben werden.
+
+### Kommandos und Anweisungen
+[Hier folgt eine Übersicht über alle Kommandos]
+- Register
+- Markdown
+- Html
+- Css
+- Javascript
+- ....
+
 
-### Troubleshooting
+## Troubleshooting
 
 > Error starting server: Address already in use: bind
 

README.md

@@ -1,56 +1,89 @@
+import static java.lang.IO.println;
 List<String> obst = List.of("Apfel", "Birne", "Banane");
 void main() {
     println("""
             Clear
-            Markdown: ## Einkaufsliste
+            Markdown: # Wie nutze ich LVP?
+            Markdown:
+            Das neue LVP Protokoll bietet viele Möglichkeiten, um Textausgaben zu transformieren und
+            daraus mediale Darstellungen im Browser anzeigen zu lassen. Diese Demo soll einen Überblick über die Möglichkeiten geben, die LVP bietet. Hier sieht man wie statische Markdown Texte erstellt werden können, die dann im Browser angezeigt werden. Diese können einzeilig sein, oder auch mehrzeilig, wie hier. Wesentlich spannender ist aber die Möglichkeit, dynamische Inhalte zu erstellen, wie im folgenden Beispiel zu sehen ist.
+            ~~~
+
             Markdown:
             """);
     println(buildObstListe());
     println("~~~");
+
+    println("""
+            Markdown:
+            ## Kommandoinhalte durch Pipelines reichen
+            Ergebnisse von Kommandos können durch Pipelines an andere Kommandos weitergereicht werden, um diese weiter zu verarbeiten. Das ist aber nur für Kommandos möglich, die auch tatsächlich eine Ausgabe haben. Das Markdown Kommando hat zum Beispiel keine Ausgabe, die weiterverarbeitet werden könnte, da es sein Ergebnis direkt im Browser anzeigt.
+            ~~~
+            """);
+
+    
     println("""
             Text[template]:
             ## Beispiel
-            Irgendein ${0} anzeigen.
+            Im folgenden Beispiel sieht man, wie das Text Kommando genutzt wird, um ein Template zu erstellen. Das Kommando selbst erzeugt keine Anzeige im Browser. Es ermöglicht aber, Platzhalter zu definieren, die dann durch die Pipeline mit ${0} gefüllt werden können.
             ~~~
             | Markdown
 
-            Text: Text
+            Text: Inhalten
             | Text[template] | Markdown
+            """);
+              
 
-            Text[t2]:
-            ## Syntax Überschrift
-            Das ist die Syntax
-            ${0}
-            Danach
+    println("""
+            Markdown:
+            Man sieht hier auch, dass sich das Text Kommando Inhalte merken kann, indem man eine ID vergibt, in diesem Fall "template". So kann ein Template mehrmals benutzt werden.
             ~~~
+            """);
 
-            Cutout: ./syntax.md
-            | Text[t2] | Markdown
 
-            Text[t3]:
-            ```java
-            ${0}
-            ```
-            ~~~
+    println("""
+        Text[t2]:
+        Jetzt fehlt nur noch die Dokumentation des Codes. Dazu kann das Codeblock Kommando genutzt werden. Es erstellt Codeblöcke, die im Browser angezeigt werden und dort auch bearbeitet werden können. Damit das funktioniert, muss das Ergebnis dieses Kommandos in einem Markdown Codeblock eingebettet werden.
 
-            Codeblock:./intro.java;// example
-            | Text[t3] | Markdown
+        ```java
+        ${0}
+        ```
+        ~~~
+        
+        Codeblock:./demo.java;// example
+        | Text[t2] | Markdown
+        """);
 
-            Register[skipId]: Counter wc
-            Text:
-            Hello World
-            ~~~
-            | Counter | Html
+    println("""
+        Register[skipId]: Counter wc
+        Text[wc-text]:
+        ## Externe Kommandos
+        In diesem Beispiel wird gezeigt, wie LVP um externe Kommandos erweitert werden kann. Durch die Register Anweisung können beliebige Kommandos registriert werden, die dann in LVP genutzt werden können. In diesem Fall wird das Kommando "wc" registriert, das die Anzahl der Wörter in einem Text zählt. Das Kommando erwartet den Text als Eingabe und gibt die Anzahl der Wörter als Ausgabe zurück.
+        </br>
+        Das Ergebnis: ${0}
+        ~~~
+        | Counter | Text[wc-text] | Markdown
 
-            """);
+        Markdown: ### Eigene Kommandos registrieren
+        
+        Register: Reverse java --enable-preview ./examples/ExternerService.java
+        Text[reverse-text]:
+        So kann man natürlich auch eigene Kommandos erstellen, die dann in LVP genutzt werden können. In diesem Fall wird ein Kommando registriert, das einen Text umkehrt. Das Kommando erwartet den Text als Eingabe und gibt den umgekehrten Text als Ausgabe zurück.
+        ~~~
+        | Reverse | Markdown        
+        """);
+
+        //TODO: Turtle Beispiel
+
+        //TODO: Interaktive HTML Elemente Beispiel
 
 }
 
 // example
 String buildObstListe() {
     String out = "";
     for (String o : obst) {
-        out += "**" + o + "**\n";
+        out += "- **" + o + "**\n";
     }
     return out;
 }

demo.java

@@ -1,4 +1,5 @@
 import java.util.Scanner;
+import static java.lang.IO.println;
 
 /// Register with:
 /// Register: Reverse java --enable-preview external.java

demo_sources.json

@@ -13,7 +13,7 @@
 
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <maven.compiler.release>24</maven.compiler.release>
+    <maven.compiler.release>25</maven.compiler.release>
   </properties>
 
 
@@ -52,7 +52,7 @@
           <artifactId>maven-compiler-plugin</artifactId>
           <version>3.13.0</version>
           <configuration>
-            <release>24</release>
+            <release>25</release>
             <compilerArgs>--enable-preview</compilerArgs>
           </configuration>
         </plugin>