Implement and archive Phase 5 help system

This commit is contained in:
2026-09-07 09:59:21 +02:00
parent e236306657
commit cc82830889
23 changed files with 1950 additions and 56 deletions

View File

@@ -34,7 +34,7 @@ Besondere Risiken sind unverändert ausgeführte alte Kompilate nach einer Text
| 04 | [Ausführung und Output](../2026-09-06-phase-5-04-ausfuehrung-und-output/proposal.md) | 01, 02, 03 | Fortsetzbare VM-Sitzung, Reset, Ausgabe, Shell und Textdruck |
| 05 | [Formular-Designer](../2026-09-06-phase-5-05-formular-designer/proposal.md) | 01, 02, 03 | Visuelles Gestalten und konsistenter Ereigniscode |
| 06 | [Debugger und Direktfenster](../2026-09-06-phase-5-06-debugger-und-direktfenster/proposal.md) | 03, 04 | Quellgenaues Debuggen, Watches, Immediate, History und Fehlerhalte |
| 07 | [Hilfesystem](../../phase-5-07-hilfesystem/proposal.md) | 02, 03 | Offline-Markdown-Hilfe und Kontextnavigation |
| 07 | [Hilfesystem](../2026-09-07-phase-5-07-hilfesystem/proposal.md) | 02, 03 | Offline-Markdown-Hilfe und Kontextnavigation |
| 08 | [Integration und Phasenabnahme](../../phase-5-08-integration-und-phasenabnahme/proposal.md) | 0107 | Durchgängiger Arbeitsablauf, Befehlsabdeckung und nachgewiesener PLAN-Status |
```text

View File

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-09-06

View File

@@ -0,0 +1,28 @@
## Context
Die Hilfe soll laut PLAN.md die tatsächlich implementierte Dokumentation unter docs anzeigen. Fensterverwaltung und F1-Befehlsweg stammen aus 02; Token-/Prozedurkontext aus 03. Die existierenden Markdown-Dateien enthalten Tabellen, Codeblöcke, Überschriften und relative Verweise. Es gibt noch keinen Markdown-Hilferenderer.
## Goals / Non-Goals
**Goals:** Eine Dokumentationsquelle für CLI-Leser und IDE, offline paketiert, stabile Link- und Kontextziele.
**Non-Goals:** Browser, Webserver, HTML-/JavaScript-Ausführung, Download von Hilfethemen oder separate handgepflegte Kopie der Referenztexte.
## Decisions
1. Die relevanten docs-Dateien werden beim Build direkt eingebettet. Ein kleiner Themenkatalog ordnet Dateipfad und Überschriftenanker den Inhalten zu. Er enthält Index/Contents und Kontextaliasse, aber keine duplizierten Erklärungstexte. Include-Struktur und Katalogprüfung müssen fehlende Dokumente beim Build/Test sichtbar machen. Eine Laufzeitinstallation benötigt keinen Checkout.
2. Markdown wird in logische Blöcke und Inline-Spans übersetzt und mit vorhandenen ratatui-Mitteln gerendert. Vor Implementierung kurz vorhandene Workspace-Abhängigkeiten prüfen; falls kein Parser verfügbar ist, ist ein einzelner fokussierter CommonMark-Parser zweckmäßiger als ein eigener Parser für Tabellen, Escapes, Code und Links. Keine volle Terminal-Markdown-Anwendung als Subprozess. Bibliothekswahl wird erst in der Umsetzung nach API-/Lizenzprüfung festgelegt, der Vertrag bleibt unabhängig davon.
3. Fensterbreite bestimmt Fließtextumbruch; Code und breite Tabellen verwenden horizontales Scrollen. Der Leseanker besteht aus Thema, Block/Offset und fokussiertem Link, nicht aus einer alten Bildschirmzeile. Unicode-Breiten kommen aus der vorhandenen Darstellung. Resize berechnet nur das Layout neu.
4. Interne Ziele werden relativ zur Quelldatei normalisiert und gegen eingebettete Dateien/Anker aufgelöst. Pfade außerhalb der eingebetteten Dokumente werden nicht als beliebige lokale Dateien gelesen. Externe Links erhalten eine sichtbare URL und Hinweis, öffnen aber nicht automatisch Browser oder Shell. Unbekannte/fehlende interne Ziele sind prüfbare Fehler, keine stillen Nullaktionen.
5. Kontextauflösung verwendet normalisierte Token mit Typ-Suffixen, Forms-Klasse/Property und konkrete IDE-Befehls-ID. Bei Mehrdeutigkeit erscheint die Trefferliste, ohne Treffer der Index mit übernommenem Suchwort. Designer liefert einfache Kontextdaten über den Rahmen; 07 benötigt seine Implementierung nicht als Compilerabhängigkeit, 08 prüft die echte Integration.
6. Besuchshistorie speichert maximal 20 Rücksprungzustände einschließlich Leseposition. Ctrl+F1 geht in der Reihenfolge des Contents-Katalogs zum nächsten Thema und bleibt am Ende mit erkennbarem Hinweis stehen. Esc stellt den vorherigen Fokus wieder her. Tutorial, Keyboard und Using Help sind normale Markdown-Seiten; About verwendet die Paketversion des gebauten Programms.
## Risks / Trade-offs
- Anker ändern sich bei Dokumentpflege → Linkprüfung über alle eingebetteten Inhalte und Kontextaliasse.
- Eingebettete Dateien vergrößern das Binary → nur Dokumentation, keine Originalarchive oder Testdaten einbetten; keine Laufzeit-Netzwerkabhängigkeit.
- Eigener Markdownparser wächst → vorhandene/fokussierte Parserbibliothek verwenden, Darstellung bleibt kleines IDE-Modul.
## Migration Plan
Dokumenttexte bleiben unter docs die Quelle. Fehlende Bedienungsseiten werden dort ergänzt und in den Katalog aufgenommen. Keine Benutzerdatenmigration; neue Releases liefern die passende Hilfe automatisch mit.

View File

@@ -0,0 +1,28 @@
## Why
Die Markdown-Referenzen sind vorhanden, aber in der IDE nicht erreichbar. Phase 5 verlangt daraus ein offline nutzbares Hilfesystem mit Kontextsuche, dynamischem Umbruch und der dokumentierten Tastaturnavigation.
## What Changes
- Markdown-Hilfefenster aus den mitgelieferten docs mit Überschriften, Absätzen, Listen, Tabellen, Code und sichtbaren Links.
- F1-Kontextauflösung für Sprache, Bibliothek, Formulare, Eigenschaften und IDE-Befehle; Index, Contents, Keyboard, Tutorial und About.
- Tab/Shift+Tab, Enter, Alt+F1 mit 20 Rücksprüngen, Ctrl+F1, Shift+F1 und Esc einschließlich Resize-/Fokuserhalt.
- Offline-Paketierung ohne Abhängigkeit vom aktuellen Arbeitsverzeichnis und reproduzierbare Prüfung interner Links.
## Capabilities
### New Capabilities
- `ide-hilfe`: Markdown-Hilfefenster aus den mitgelieferten docs mit Überschriften, Absätzen, Listen, Tabellen, Code und sichtbaren Links.
### Modified Capabilities
Keine bestehenden Anforderungen werden ersetzt; die neue IDE-Fähigkeit ergänzt die vorhandenen Laufzeit- und Dateiformatverträge.
## Impact
tb-ide-Hilfe, docs/ und Paketierung von tb; nutzt Fensterverwaltung und Editor-Kontext. Kein Webdienst und keine eigene zweite Dokumentationssammlung.
**Abhängigkeiten:** [phase-5-02-ide-rahmen](../2026-09-06-phase-5-02-ide-rahmen/proposal.md), [phase-5-03-editor-und-inkrementelle-uebersetzung](../2026-09-06-phase-5-03-editor-und-inkrementelle-uebersetzung/proposal.md).
**Gesamtplanung:** [Phase-5-Übersicht](../2026-09-06-phase-5-01-projekt-und-dokumentmodell/phase-5-uebersicht.md). Die Nummern geben eine gültige Umsetzungsreihenfolge an; OpenSpec erzwingt Change-Abhängigkeiten nicht automatisch.

View File

@@ -0,0 +1,41 @@
## Purpose
Macht die mitgelieferte Markdown-Dokumentation als offline verfügbare, kontextsensitive IDE-Hilfe mit verlässlicher Navigation und variabler Fenstergröße nutzbar.
## ADDED Requirements
### Requirement: Mitgelieferte Dokumente und Markdown-Darstellung
Die Hilfe SHALL die aktuelle Dokumentation aus docs einschließlich Sprach-, Bibliotheks-, Forms- und IDE-Bedienungsreferenz ohne Netzwerk und unabhängig vom Arbeitsverzeichnis bereitstellen. Überschriften, Absätze, Listen, Codeblöcke, Tabellen und Links SHALL lesbar dargestellt werden; Fließtext SHALL nach Fensterbreite umbrechen, Code und Tabellen SHALL ohne Informationsverlust umgebrochen oder horizontal scrollbar sein. Resize SHALL Thema und logische Leseposition erhalten.
#### Scenario: Start außerhalb des Repositorys
- **WHEN** das gebaute tb aus einem Verzeichnis ohne docs gestartet wird
- **THEN** sind Index, Referenzthemen und Tutorial weiterhin vollständig erreichbar
#### Scenario: Schmales Hilfefenster
- **WHEN** ein Thema mit Tabelle, Unicode und Code bei schmaler Fensterbreite geöffnet und anschließend vergrößert wird
- **THEN** bleiben alle Inhalte erreichbar, Links bedienbar und die Leseposition demselben Inhalt zugeordnet
### Requirement: Kontextsensitive Themenwahl
F1/Topic und entsprechend konfigurierter Rechtsklick SHALL das Thema zum Token unter dem Editorcursor, zur Designerklasse/-eigenschaft oder zum fokussierten IDE-Befehl öffnen. Sprache und Bibliothek SHALL unabhängig von Großschreibung und mit Typ-Suffixen gefunden werden. Bei mehreren passenden Themen SHALL eine Auswahl erscheinen; ohne passenden Kontext SHALL eine verständliche Suche beziehungsweise der Index erscheinen.
#### Scenario: Property und BASIC-Funktion
- **WHEN** F1 zuerst auf einer Formulareigenschaft und danach auf einer BASIC-Funktion mit Dollar-Suffix ausgelöst wird
- **THEN** öffnet die Hilfe jeweils das zugehörige dokumentierte Thema einschließlich dessen passendem Abschnitt
### Requirement: Links und Verlauf
Interne Links SHALL als ◄Thema► sichtbar sein. Tab/Shift+Tab SHALL den Linkfokus bewegen, Enter SHALL folgen, Alt+F1 SHALL bis zu 20 besuchte Zustände zurückführen und Ctrl+F1 SHALL das nächste Thema in der dokumentierten Themenreihenfolge öffnen. Esc SHALL die Hilfe schließen und den vorherigen Fokus wiederherstellen. Fehlende Ziele SHALL eine Diagnose liefern; externe Links SHALL als extern erkennbar sein und nicht automatisch einen Prozess oder Netzwerkzugriff auslösen.
#### Scenario: Rücksprung mit Leseposition
- **WHEN** ein Link nach Scrollen verfolgt und Alt+F1 gedrückt wird
- **THEN** kehrt die Hilfe zu Thema, Leseposition und Linkfokus vor dem Sprung zurück
#### Scenario: Grenze des Verlaufs
- **WHEN** mehr als 20 Themenwechsel erfolgen
- **THEN** bleiben die letzten 20 Rücksprünge möglich, ältere Einträge werden nachvollziehbar verdrängt und weiterer Rücksprung verändert den Zustand nicht
### Requirement: Hilfe-Einstiege
Help SHALL Index, Contents, Keyboard, Topic/F1, Using Help/Shift+F1, Tutorial und About anbieten. Index SHALL Themen alphabetisch auffindbar machen und Contents SHALL die Dokumenthierarchie abbilden. Keyboard und Tutorial SHALL die tatsächlich implementierte IDE-Bedienung erklären; About SHALL Version und Copyright anzeigen.
#### Scenario: Tutorial folgen
- **WHEN** der Benutzer Tutorial öffnet und den dort beschriebenen Weg zum Erstellen, Gestalten, Debuggen und Ausführen verfolgt
- **THEN** stimmen Befehle und Tasten mit der Oberfläche überein und alle internen Verweise sind auflösbar

View File

@@ -0,0 +1,17 @@
## 1. Dokumente und Darstellung
- [x] 1.1 Die relevanten docs-Inhalte mit stabilem Datei-/Themen-/Ankerkatalog in tb einbetten; ein Test startet die Hilfe aus einem temporären Verzeichnis ohne Checkout und findet alle Referenzseiten.
- [x] 1.2 Den Markdown-Block-/Inline-Pfad mit vorhandenen Abhängigkeiten oder einem einzelnen geeigneten Parser anbinden; Renderproben prüfen Überschriften, Listen, Escapes, Links, Codeblöcke und Tabellen.
- [x] 1.3 Dynamischen Umbruch und horizontales Scrollen für breite Inhalte implementieren; TestBackend-Prüfungen mit Unicode und Resize erhalten Thema, Leseposition und Linkfokus.
## 2. Kontext und Navigation
- [x] 2.1 F1-/Rechtsklick-Kontext aus Editor, Forms-Property und IDE-Befehl auf Themen/Anker abbilden; Tests prüfen Typ-Suffixe, Großschreibung, Mehrdeutigkeit und fehlenden Treffer.
- [x] 2.2 Tab/Shift+Tab, Enter, Alt+F1, Ctrl+F1 und Esc integrieren; Eingabetests belegen Linkfolge, 20 Rücksprünge, Ende der Themenreihenfolge und vorherigen Fensterfokus.
- [x] 2.3 Interne Pfade/Anker prüfen und externe Ziele sichtbar ohne automatische Ausführung behandeln; Tests belegen fehlende Ziele, Pfadbegrenzung und unterbleibende Prozess-/Netzwerkaufrufe.
## 3. Hilfe-Einstiege und Abnahme
- [x] 3.1 Index, Contents, Keyboard, Using Help, Tutorial und About anbinden und fehlende Bedienungsseiten unter docs ergänzen; Menü-/Shortcut-Tests öffnen jeden Einstieg und zeigen die gebaute Version.
- [x] 3.2 Alle eingebetteten relativen Links und Kontextaliasse mit einer ausführbaren Katalogprüfung absichern; sie muss bei absichtlich fehlendem Ziel scheitern.
- [x] 3.3 Die Hilfe-Spec-Szenarien in verification.md zuordnen und cargo test -p tb-ide sowie Formatprüfung ausführen; der Tutorial-/Designer-Gesamtweg wird zusätzlich in 08 geprüft.

View File

@@ -0,0 +1,84 @@
# Verification Report: phase-5-07-hilfesystem
Stand: 2026-09-07. Proposal, Design, neun Aufgaben sowie vier Anforderungen
mit sechs Szenarien wurden gegen den aktuellen Code und ausführbare Tests geprüft.
## Ergebnis
| Dimension | Ergebnis |
| --- | --- |
| Completeness | 9/9 Aufgaben; 4/4 Anforderungen umgesetzt |
| Correctness | 6/6 Szenarien zugeordnet und geprüft |
| Coherence | Eingebettete docs als einzige Textquelle; vorhandene App-, Fenster-, Designer- und Renderingpfade |
| Offene Befunde | 0 CRITICAL, 0 WARNING, 0 SUGGESTION |
## Anforderungen und Szenarien
Implementierung: `crates/tb-ide/src/help.rs`, Dispatcher in `app.rs`,
Renderaufruf in `render.rs`, Property-Kontext in `designer.rs`.
Neue Nachweise: `crates/tb-ide/tests/help.rs`.
| Requirement / Scenario | Implementierung und Nachweis |
| --- | --- |
| Mitgelieferte Dokumente / Start außerhalb des Repositorys | `DOCUMENTS` bindet elf aktuelle docs-Dateien und den verlinkten PLAN direkt per `include_str!` ein. `Catalog` erzeugt Index und Contents aus diesen Seiten. `help_works_from_a_directory_without_checkout` startet den Testprozess in einem temporären Verzeichnis ohne docs; `offline_help_child` öffnet dort dieselbe `App`, alle Hilfe-Einstiege sowie Sprach-, Bibliotheks-, Forms-, IDE-Referenz und Tutorial mit TestBackend. Der normale tb-Einstieg benutzt diese App unabhängig vom Arbeitsverzeichnis. |
| Markdown / Schmales Hilfefenster | `Page::parse` verarbeitet CommonMark einschließlich Tabellen mit pulldown-cmark; `layout` berechnet Fließtextzeilen anhand der Zellbreite. Code und Tabellen behalten ihre vollständigen Zeichen und sind horizontal scrollbar. `Position` speichert Seite, Block, Zeichenoffset und Linkfokus. `markdown_blocks_escapes_links_and_unicode_layout` prüft Listen, Formatierung, Escapes, Links, Unicode und verlustfreie Blockprojektion bei vier Breiten. `code_and_tables_remain_reachable_after_resize_and_horizontal_scroll` und `links_history_resize_scroll_and_focus_use_real_events` prüfen schmale TestBackend-Fenster, echte Scrolltasten und Resize bei erhaltenem Leseanker und Linkfokus. |
| Kontextsensitive Themenwahl / Property und BASIC-Funktion | `token_at`, `normalize`, `Catalog::search`, `help_context` und `design_help_context` verbinden BASIC-Tokens samt Typsuffix mit Dokumentabschnitten und Designerklasse/-eigenschaft. `command_target` bildet konkrete Befehls-IDs ab. `context_functions_properties_commands_and_unknown_queries` prüft F1 auf `lEfT$`, Form.Caption im aktiven Property-Wertfeld, den fokussierten Save-Project-Menübefehl, Mehrdeutigkeit und unbekanntes Suchwort. `every_command_and_forms_alias_resolves_and_invalid_alias_fails` prüft alle Menübefehle beider Modi und alle Properties der 19 Forms-Klassen. |
| Links und Verlauf / Rücksprung mit Leseposition | `Help::visit`, `follow`, `back`, `focus_link`, `help_key` halten Navigation und Fenstersitzung zusammen. `links_history_resize_scroll_and_focus_use_real_events` folgt nach Scrollen per Enter einem Link und stellt mit Alt+F1 exakt Seite, Offset und Linkfokus wieder her. Esc restauriert das vorherige Fenster; `help_preserves_fullscreen_and_does_not_modify_designer_or_source` prüft zusätzlich Output-Vollbild, Designerzustand und Suchergebnis-Rücksprünge. |
| Links und Verlauf / Grenze des Verlaufs | `Help::visit` hält maximal 20 Rücksprungzustände. `twenty_back_steps_end_of_contents_and_all_entries` führt 25 Wechsel und anschließend die letzten 20 Rücksprünge aus. Weiteres Zurück verändert keinen Zustand und zeigt den Grenzhinweis. Ctrl+F1 folgt der Contents-Dateireihenfolge und bleibt am Ende mit Hinweis stehen. |
| Hilfe-Einstiege / Tutorial folgen | Alle sieben Help-Einstiege sind angebunden; About zeigt die gebaute Paketversion und Autoren. `twenty_back_steps_end_of_contents_and_all_entries` bedient Menüs und Shortcuts. `docs/tutorial.md` wurde gegen New Project/Form, Toolbox-Platzierung, Caption/F2, F12-Ereignisauswahl, Startdatei, F9/F8/F5 und die vorhandenen Designer-/Debugger-/Ausführungstests abgeglichen. Alle Tutorialverweise werden durch `Catalog::validate` geprüft. Der zusätzliche durchgehende Tutorial-/Designer-Abnahmelauf bleibt gemäß Aufgabe 3.3 in Change 08. |
## Weitere Vertragsprüfungen
- `catalog_links_and_missing_targets_are_checked` prüft sämtliche internen
Kataloglinks und Überschriftenanker. Absichtlich fehlende Dateien, Anker,
ungültige Prozentkodierungen und Pfade außerhalb des Katalogs schlagen fehl.
Doppelte Überschriften einschließlich Namenskollisionen erhalten eindeutige Anker.
- Kontextaliasse werden durch dieselbe Zielauflösung geprüft; ein absichtlich
falscher Befehlsanker erzeugt einen Fehler. Klasse und Property stammen aus
der vorhandenen Forms-Metadatenquelle, die Texte weiterhin aus docs.
- `right_click_configuration_and_external_link_follow` prüft den Optionsschalter,
sichtbare externe URLs und Enter auf einem externen Ziel. Es erfolgt kein
Shell-Auftrag; die Hilfe besitzt keinen Datei-, Prozess- oder Netzwerkpfad.
Die bestehende App-Regression belegt weiterhin Rechtsklick-Zustellung an ein
laufendes BASIC-Programm mit Output-Fokus.
- Index sortiert Themen und Abschnitte alphabetisch, Contents bildet die
Dokument-/Überschriftenhierarchie ab. Suche ohne Treffer erhält das Suchwort
und bietet Index/Contents an; Mehrdeutigkeit erzeugt eine bedienbare Linkliste.
- `docs/hilfe.md`, `docs/tastatur.md` und `docs/tutorial.md` sind normale
eingebettete Markdown-Seiten. Es gibt weder eine zweite Referenzsammlung
noch externe Renderer. Die Build-Abhängigkeit pulldown-cmark 0.13.4 wurde
nach Prüfung der CommonMark-/Tabellen-API und MIT-Lizenz ohne Default-Features
aufgenommen. Darstellungsbreiten und Fenster verwenden vorhandene Bibliotheken.
## Behobene Befunde
- Frühes Rechtsklick-Routing fing anfangs Programmmauseingaben ab. Kontext-Hilfe
respektiert jetzt den laufenden Output-Fokus; die bisherige App-Regression besteht.
- Hilfe aus Output-Vollbild wurde vom Vollbild verdeckt. Öffnen und Schließen
sichern und restaurieren nun auch diesen Fokuszustand.
- Allgemeine Menügruppen waren für einzelne Befehle zu ungenau. Eine exhaustive
Zuordnung der konkreten Befehls-IDs verweist auf die jeweiligen Bedienabschnitte;
der Katalogtest sichert die Ziele ab.
- Einfache Überschriftenzähler konnten bei einem bereits vorhandenen Suffix
kollidieren. Eine Menge der vergebenen Anker verhindert solche Kollisionen.
- Benachbarte Inline-Spans gleichen Stils werden zusammengefasst, damit
kombinierende Unicode-Zeichen bei der Terminaldarstellung zusammenbleiben.
- Die bisherige Phase-07-Platzhalterdarstellung und die vollständig überholte
Feature-Phasen-Sperre wurden entfernt. Hilfe und Bedienungsübersicht zeigen
den implementierten Stand; die native Exporterzeugung bleibt Phase 6.
## Abschlussprüfungen
- `cargo test -p tb-ide`: 79 Tests bestanden, keine Fehler oder Ignore-Fälle;
zusätzlich ein erfolgreicher Offline-Kindprozess mit derselben Hilfe-App.
Enthalten sind elf Hilfetests sowie alle bestehenden App-, Dokument-, Editor-,
Designer-, Debugger- und Ausführungstests.
- `cargo clippy --workspace --all-targets -- -D warnings`: bestanden.
- `cargo fmt --all -- --check`: bestanden.
- `git diff --check`: bestanden.
- `openspec validate --all --strict`: 23/23 gültig. Bestehende INFO-Hinweise
zu langen Anforderungstexten sind keine Validierungsfehler.
Keine Prüfdimension des Changes wurde ausgelassen. Der zusätzliche Gesamtweg
in Change 08 gehört wie geplant zur späteren Phasenabnahme. Es bestehen keine
offenen Befunde; der Change ist zur Synchronisierung und Archivierung bereit.