3.6 KiB
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.