Complete overhaul (linguistic, content-related, and logical) by Claude

docs/additional-material/instructions/binary-numbers.mdx

@@ -10,8 +10,8 @@ import TabItem from '@theme/TabItem';
 
 ## Binärzahlen in Dezimalzahlen umwandeln
 
-Zur Umwandlung einer Binärzahl in eine Dezimalzahl muss das Produkt aus
-Stellenwert und Ziffer jeder Stelle aufsummiert werden.
+Um eine Binärzahl in eine Dezimalzahl umzuwandeln, wird das Produkt aus
+Stellenwert und Ziffer jeder Stelle aufsummiert.
 
 | Potenz         | Stellenwert | Ziffer | Stellenwert \* Ziffer |
 | -------------- | ----------- | ------ | --------------------- |
@@ -30,8 +30,8 @@ Stellenwert und Ziffer jeder Stelle aufsummiert werden.
 
 ## Natürliche Dezimalzahlen in Binärzahlen umwandeln
 
-Zur Umwandlung einer natürlichen Dezimalzahl in eine Binärzahl kann entweder
-eine Stellenwerttabelle oder das Divisions-Verfahren verwendet werden.
+Eine natürliche Dezimalzahl lässt sich entweder mit einer Stellenwerttabelle
+oder dem Divisions-Verfahren in eine Binärzahl umwandeln.
 
 Im Beispiel soll die Zahl 525<sub>10</sub> in eine Binärzahl umgewandelt werden.
 
@@ -76,10 +76,9 @@ Im Beispiel soll die Zahl 525<sub>10</sub> in eine Binärzahl umgewandelt werden
 
 ## Bilden des Zweierkomplements
 
-Zum Bilden des Zweierkomplements wird zunächst das Einerkomplement gebildet,
-d.h. alle Bits werden invertiert. Hierbei ist zu beachten, dass einer positiven
-Binärzahl unendlich viele Nullen vorangestellt sind. Anschließend wird noch eine
-1 hinzuaddiert.
+Das Zweierkomplement entsteht, indem zunächst das Einerkomplement gebildet wird
+(alle Bits werden invertiert) und anschließend eine 1 hinzuaddiert wird. Einer
+positiven Binärzahl sind dabei unendlich viele Nullen vorangestellt.
 
 Im Beispiel soll die Zahl -95<sub>10</sub> im Zweierkomplement dargestellt
 werden.
@@ -90,16 +89,16 @@ werden.
 | Invertieren                                        | 1             | ... | 1             | 0             | 1             | 0             | 0             | 1             | 1             | 0             |
 | 1 Addieren                                         | 1             | ... | 1             | 0             | 1             | 0             | 0             | 1             | 1             | 1             |
 
-:::info
+:::note
 
 Die Rückumwandlung erfolgt analog.
 
 :::
 
 ## Reelle Dezimalzahlen in Binärzahlen umwandeln
 
-Zur Umwandlung einer reellen Dezimalzahl in eine Binärzahl kann entweder eine
-Stellenwerttabelle oder das Multiplikations-Verfahren verwendet werden.
+Eine reelle Dezimalzahl lässt sich entweder mit einer Stellenwerttabelle oder
+dem Multiplikations-Verfahren in eine Binärzahl umwandeln.
 
 Im Beispiel soll die Zahl 0,1<sub>10</sub> in eine Binärzahl umgewandelt werden.
 
@@ -138,12 +137,12 @@ Im Beispiel soll die Zahl 0,1<sub>10</sub> in eine Binärzahl umgewandelt werden
 
 ## Reelle Dezimalzahlen in Gleitkommazahlen umwandeln
 
-Bei der Umwandlung einer reellen Zahl in eine Gleitkommazahl werden zunächst
-Vor- und Nachkommazahl in Binärzahlen umgewandelt. Anschließend wird durch
-Gleiten bzw. Verschieben des Kommas zur führenden 1, dem Runden auf das LSB
-sowie dem Entfernen der führenden 1 die Mantisse ermittelt. Nach dem Ermitteln
-der Mantisse wird zum Exponenten noch der Bias (127 bei einfacher Genauigkeit,
-1023 bei doppelter Genauigkeit) hinzuaddiert sowie das Vorzeichen umgewandelt.
+Bei der Umwandlung einer reellen Zahl in eine Gleitkommazahl werden Vor- und
+Nachkommazahl zunächst in Binärzahlen umgewandelt. Durch Verschieben des Kommas
+zur führenden 1, Runden auf das LSB und Entfernen der führenden 1 entsteht die
+Mantisse. Zum Exponenten wird anschließend der Bias addiert (127 bei einfacher,
+1023 bei doppelter Genauigkeit), und das Vorzeichen wird als einzelnes Bit
+gespeichert.
 
 Im Beispiel soll die Zahl -27,04<sub>10</sub> in eine Gleitkommazahl mit
 einfacher Genauigkeit umgewandelt werden.
@@ -163,16 +162,14 @@ einfacher Genauigkeit umgewandelt werden.
 
 ## Binärzahlen addieren und subtrahieren
 
-Für die Addition von Binärzahlen gelten folgende Regeln:
+Für die Addition von Binärzahlen gelten vier Regeln. Die Subtraktion erfolgt
+durch Addition des Zweierkomplements: `a - b = a + (-b)`.
 
 - Fall 1: `0 + 0 = 0`
 - Fall 2: `0 + 1 = 1`
 - Fall 3: `1 + 0 = 1`
 - Fall 4: `1 + 1 = 0 (Übertrag 1)`
 
-Die Subtraktion von Binärzahlen erfolgt durch die Addition des
-Zweierkomplements. Es gilt: `a - b = a + (-b)`.
-
 <Tabs>
   <TabItem value="a" label="a + b" default>
 
@@ -228,9 +225,9 @@ Im Beispiel werden die Zahlen -3 und -47 addiert.
   </TabItem>
 </Tabs>
 
-:::info
+:::note
 
-Der bei der Addition des Zweierkomplements auftretende mögliche Stellenüberlauf
-wird ignoriert.
+Der bei der Addition des Zweierkomplements möglicherweise auftretende
+Stellenüberlauf wird ignoriert.
 
 :::

docs/additional-material/instructions/debugging.md

@@ -0,0 +1,128 @@
+---
+title: Debuggen mit Eclipse
+description: ''
+sidebar_position: 50
+tags: [debugging, eclipse]
+---
+
+:::tip
+
+Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/) und
+[Eclipse](https://www.eclipse.org/)
+
+:::
+
+Der in Eclipse integrierte Debugger ermöglicht es, ein Java-Programm
+kontrolliert auszuführen, an beliebigen Stellen anzuhalten und den Zustand von
+Variablen sowie den Programmfluss zu inspizieren. Die folgenden Abschnitte
+führen schrittweise durch die wichtigsten Debugging-Funktionen in Eclipse.
+
+## Programm im Debug-Modus starten
+
+Um den Debugger zu nutzen, muss das Programm explizit im Debug-Modus gestartet
+werden. Ohne diesen Modus sind Breakpoints und Schrittausführung nicht
+verfügbar.
+
+- Öffne das gewünschte Java-Projekt in Eclipse
+- Navigiere im _Package Explorer_ zur Startklasse (der Klasse mit der
+  `main`-Methode)
+- Öffne das Kontextmenü der Startklasse (Rechtsklick) und führe **Debug As →
+  Java Application** aus
+
+:::tip
+
+Das Programm kann alternativ über die Werkzeugleiste mit der Schaltfläche
+**Debug** (Käfer-Symbol) oder mit dem Tastaturkürzel `F11` im Debug-Modus
+gestartet werden.
+
+:::
+
+## Breakpoint setzen
+
+Ein Breakpoint markiert eine Zeile, an der die Programmausführung pausieren
+soll. Eclipse hält an dieser Stelle an, bevor die markierte Zeile ausgeführt
+wird.
+
+- Navigiere im Editor zur gewünschten Zeile
+- Führe im grauen Randbereich links der Zeilennummer (Rechtsklick) die Funktion
+  **Toggle Breakpoint** aus
+
+Ein blauer Kreis im Randbereich zeigt an, dass der Breakpoint aktiv ist.
+
+:::tip
+
+Ein Breakpoint kann auch durch einen Doppelklick auf den grauen Randbereich
+links der Zeilennummer gesetzt bzw. entfernt werden.
+
+:::
+
+## Debug-Perspektive verwenden
+
+Sobald das Programm an einem Breakpoint anhält, wechselt Eclipse automatisch in
+die _Debug-Perspektive_. Sie besteht aus mehreren spezialisierten Ansichten, die
+gemeinsam ein vollständiges Bild des aktuellen Programmzustands liefern.
+
+- **Debug**: zeigt den Call Stack (Aufrufhierarchie der aktiven Methoden)
+- **Variables**: zeigt alle aktuell sichtbaren Variablen und deren Werte
+- **Breakpoints**: listet alle gesetzten Breakpoints und erlaubt das
+  Aktivieren/Deaktivieren einzelner Breakpoints
+- **Console**: zeigt die Standardausgabe des laufenden Programms
+- **Expressions**: wertet beliebige Java-Ausdrücke im aktuellen Kontext aus
+  (z.B. `list.size()` oder `obj.getName()`)
+
+## Programm schrittweise ausführen
+
+Sobald das Programm an einem Breakpoint pausiert, stehen verschiedene
+Schritt-Befehle zur Verfügung, um die Ausführung gezielt fortzusetzen und den
+Kontrollfluss zu verfolgen.
+
+- Führe **Run → Step Over** (`F6`) aus, um die aktuelle Zeile vollständig
+  auszuführen und in der nächsten Zeile derselben Methode anzuhalten
+- Führe **Run → Step Into** (`F5`) aus, um in den Rumpf des aufgerufenen
+  Methodenaufrufs hineinzuspringen
+- Führe **Run → Step Return** (`F7`) aus, um die aktuelle Methode vollständig
+  auszuführen und zur aufrufenden Stelle zurückzukehren
+- Führe **Run → Resume** (`F8`) aus, um die Ausführung bis zum nächsten
+  Breakpoint fortzusetzen
+
+## Variablenwerte inspizieren
+
+Die View _Variables_ zeigt den aktuellen Zustand aller sichtbaren Variablen.
+Objekte können aufgeklappt werden, um ihre Felder zu inspizieren.
+
+- Navigiere in der Debug-Perspektive zur View _Variables_
+- Klappe Objekte durch Betätigen des Dreiecks links des Variablennamens auf
+- Der aktuelle Wert einer Variablen wird in der Spalte **Value** angezeigt
+
+:::tip
+
+Fahre im Editor mit der Maus über einen Variablennamen, um dessen aktuellen Wert
+als Tooltip anzuzeigen. Für komplexere Ausdrücke steht die View _Expressions_
+zur Verfügung: Rechtsklick im Editor → **Watch**.
+
+:::
+
+## Bedingten Breakpoint setzen
+
+Ein bedingter Breakpoint pausiert die Ausführung nur dann, wenn eine angegebene
+boolesche Bedingung erfüllt ist. Das ist besonders nützlich, wenn ein Fehler nur
+bei bestimmten Werten auftritt – etwa ab einem bestimmten Schleifendurchlauf.
+
+- Setze zunächst einen gewöhnlichen Breakpoint (siehe oben)
+- Führe im Randbereich auf dem Breakpoint-Symbol (Rechtsklick) die Funktion
+  **Breakpoint Properties...** aus
+- Aktiviere die Option **Enable Condition**
+- Trage eine boolesche Bedingung im Textfeld ein (z.B. `i == 42`)
+- Betätige **OK**
+
+Der Breakpoint pausiert die Ausführung nun nur noch, wenn die angegebene
+Bedingung `true` ergibt.
+
+## Debug-Perspektive verlassen
+
+Nach dem Abschluss der Fehlersuche sollte die Debug-Perspektive ordentlich
+beendet und zur Java-Perspektive zurückgewechselt werden.
+
+- Führe **Run → Terminate** (`Ctrl+F2`) aus, um das laufende Programm zu beenden
+- Wechsle über den Perspektiven-Umschalter in der Werkzeugleiste (oben rechts)
+  zurück zur _Java_-Perspektive

docs/additional-material/instructions/git.md

@@ -5,7 +5,7 @@ sidebar_position: 30
 tags: [git]
 ---
 
-:::info
+:::tip
 
 Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/),
 [Eclipse](https://www.eclipse.org/) und [Git](https://git-scm.com/downloads)
@@ -14,6 +14,10 @@ Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/),
 
 ## Remote Repository anlegen
 
+Ein Remote Repository auf GitHub dient als zentraler Ablageort für den
+Quellcode. Zusätzlich wird ein Personal Access Token benötigt, um sich von der
+Kommandozeile aus zu authentifizieren.
+
 - Registriere Dich bei [GitHub](https://github.com/)
 - Melde Dich bei [GitHub](https://github.com/) an
 - Führe die Funktion **New** aus
@@ -32,6 +36,9 @@ Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/),
 
 ## Git konfigurieren
 
+Vor der ersten Nutzung muss Git mit dem eigenen Namen und der E-Mail-Adresse
+konfiguriert werden. Diese Angaben erscheinen in jedem Commit.
+
 - Starte die Kommandozeile (z.B. Windows PowerShell)
 - Führe den Befehl `git config --global user.name "[Dein Name]"` aus, um den
   Benutzernamen festzulegen (z.B.
@@ -42,6 +49,9 @@ Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/),
 
 ## Lokales Repository anlegen
 
+Ein lokales Repository kann entweder neu initialisiert (Variante A) oder direkt
+vom Remote Repository geklont werden (Variante B).
+
 **Variante A: Via Git Init**
 
 - Starte die Kommandozeile (z.B. Windows PowerShell)
@@ -70,6 +80,8 @@ Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/),
 
 ## Lokales Repository in Eclipse einbinden
 
+Nach dem Anlegen des lokalen Repositorys wird es als Eclipse-Projekt importiert.
+
 - Starte Eclipse
 - Führe die Funktion **File - Import... - General - Projects from Folder or
   Archive** aus und betätige die Drucktaste **Next >**
@@ -79,6 +91,10 @@ Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/),
 
 ## Remote Repository aktualisieren (bei Änderungen im lokalen Repository)
 
+Lokale Änderungen werden indiziert, als Commit versioniert und anschließend ins
+Remote Repository übertragen. Das ist entweder über die Kommandozeile oder
+direkt in Eclipse möglich.
+
 **Variante A: Via Kommandozeile**
 
 - Führe mehrmals den Befehl `git add [Die zu indizierende Datei]` aus, um die
@@ -104,6 +120,10 @@ Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/),
 
 ## Lokales Repository aktualisieren (bei Änderungen im remote Repository)
 
+Änderungen aus dem Remote Repository werden in den lokalen Arbeitsbereich
+übertragen. Das ist entweder über die Kommandozeile oder direkt in Eclipse
+möglich.
+
 **Variante A: Via Kommandozeile**
 
 - Starte die Kommandozeile (z.B. Windows PowerShell)

docs/additional-material/instructions/javafx.md

@@ -5,7 +5,7 @@ sidebar_position: 40
 tags: [javafx]
 ---
 
-:::info
+:::tip
 
 Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/),
 [Eclipse](https://www.eclipse.org/),
@@ -16,6 +16,9 @@ Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/),
 
 ## Scene Builder mit Eclipse verbinden
 
+Damit Eclipse den Scene Builder öffnen kann, muss der Pfad zur ausführbaren
+Datei einmalig konfiguriert werden.
+
 - Starte Eclipse
 - Navigiere zu **Window – Preferences – JavaFX**
 - Gib beim Feld **SceneBuilder executable** den Wert **[Der Pfad zur
@@ -24,6 +27,10 @@ Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/),
 
 ## JavaFX-Anwendung ausführen
 
+Eine JavaFX-Anwendung kann entweder als ausführbare JavaFX-Anwendung über das
+Maven-Plugin (Variante A) oder über eine separate Startklasse (Variante B)
+gestartet werden.
+
 **Variante A: Via ausführbarer JavaFX-Anwendung**
 
 - Starte Eclipse
@@ -97,6 +104,10 @@ public class MainClass {
 
 ## Ausführbare JavaFX-Anwendung debuggen
 
+Um eine ausführbare JavaFX-Anwendung im Debug-Modus zu starten, wird das
+JavaFX-Maven-Plugin um eine Debug-Konfiguration erweitert und anschließend mit
+dem Goal `javafx:run@debug` ausgeführt.
+
 - Starte Eclipse
 - Navigiere in der View _Package Explorer_ zu Deinem Maven-Projekt
 - Navigiere in Deinem Maven-Projekt zur Datei _pom.xml_ und öffne diese

docs/additional-material/instructions/jdk.md

@@ -5,14 +5,18 @@ sidebar_position: 10
 tags: [jdk]
 ---
 
-:::info
+:::tip
 
 Benötigte Tools: [JDK](https://www.oracle.com/java/technologies/downloads/)
 
 :::
 
 ## Quellcode-Datei erstellen
 
+Eine Java-Quellcode-Datei enthält genau eine öffentliche Klasse, deren Name dem
+Dateinamen entsprechen muss. Die Datei liegt in einem Paketordner und trägt die
+Endung _.java_.
+
 - Erstelle ein Arbeitsverzeichnis (z.B. _C:\Users\Daniel Appenmaier\Java_)
 - Erstelle im eben erstellten Arbeitsverzeichnis einen Ordner (z.B. _main_)
 - Erstelle im eben erstellten Ordner eine Datei mit der Endung _.java_ (z.B.
@@ -34,6 +38,9 @@ public class HelloWorld {
 
 ## Quellcode-Datei kompilieren
 
+Der Java-Compiler `javac` übersetzt die Quellcode-Datei in eine Bytecode-Datei
+(_.class_).
+
 - Starte die Kommandozeile (z.B. Windows PowerShell)
 - Führe den Befehl `cd "[Der Pfad zu Deinem Arbeitsverzeichnis]"` aus, um zum
   Arbeitsbereich zu wechseln (z.B. `cd "C:\Users\Daniel Appenmaier\Java"`)
@@ -42,6 +49,8 @@ public class HelloWorld {
 
 ## Bytecode-Datei ausführen
 
+Die Java Virtual Machine `java` führt die kompilierte Bytecode-Datei aus.
+
 - Starte die Kommandozeile (z.B. Windows PowerShell)
 - Führe den Befehl `cd "[Der Pfad zu Deinem Arbeitsverzeichnis]"` aus, um zum
   Arbeitsbereich zu wechseln (z.B. `cd "C:\Users\Daniel Appenmaier\Java"`)