29 lines
3.6 KiB
Markdown
29 lines
3.6 KiB
Markdown
## 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.
|