# Level editor – user manual and in-app help (`editor.tools.help`)

The complete user manual (English, forum audience) lives as Markdown in **`docs/manual/`** (one
file per chapter + `img/`). It is bundled into the jar (`build.gradle` → `processResources` copies
`docs/manual` to `com/eliasmueller/llamamod/editor/tools/help/manual/`) and shown by
**Help → Manual (F1)**.

![manual window](img/editor/manual_chapter.jpg)

## Chapters

`index.md` defines the order and the groups of the contents tree (H2 = group, list links = chapters):
Getting started (01 introduction & concepts, 02 installing, 03 editor window, 04 navigation,
05 selection), Tutorials (first level in 10 minutes, parkour, edit an original level, Blender model),
Building levels (06 geometry, 07 meshes & library, 08 textures, 09 objects incl. cross-world import,
10 waypoints, 11 cameras & triggers, 12 environment, 13 visibility, 14 level settings), Testing and
sharing (15 build/problems/play-test, 16 original levels, 17 sharing), Reference (18 mods, 19
keyboard/mouse/menu, 20 troubleshooting & FAQ, 21 glossary).

Markdown subset (own converter `Markdown`, no dependency): ATX headings (one H1 per file),
paragraphs, bold/italic/code, links, images on their own line, nested lists, GFM tables,
block quotes (callouts), fenced code, rules; no raw HTML. Anchors = GitHub slugs, so the files also
read well on GitHub/forums.

**Generated blocks** `<!-- generated:NAME -->…<!-- /generated:NAME -->` are filled from the live
program (`ManualContent`): `shortcuts` (tool keys, keyed commands, key conflicts), `menus` (every
menu command with key and tooltip), `panels` (dock panels) – from `EditorExtensions`, i.e. built-ins
and all plugins – and `mods` (built-in LlamaMod mods with options, from `ModRegistry`). The window
regenerates them at run time; `ManualTest` rewrites the copies in `docs/manual` when they are stale
(`-Dllamamod.manual.noUpdate=true` turns that off). Key names are locale-independent ("Ctrl+Shift+D").

## Manual window (`ManualWindow`)

Own frame (stays open next to the editor, works while a modal dialog is open): toolbar back /
forward (Alt+Left/Right), contents (Alt+Home), previous / next chapter, search field (Ctrl+F),
Export menu; left: **Contents** tree (groups → chapters → H2 sections, follows navigation) and
**Search** (all words must match; ranked by title hits; excerpt; the words are highlighted on the
page); right: the page (Swing HTML with CSS from the current FlatLaf colours, images scaled to the
page width and loaded synchronously so anchors land correctly, previous/next links at the end).
Internal links navigate, external ones open the browser. Re-rendered on theme change (light/dark).
`-Dllamamod.manual.dir=docs/manual` reads the Markdown from a folder (reloaded on every open) for
writing the manual.

**Export** (`ManualExport`): HTML folder (index.html + one page per chapter with a sidebar,
manual.css with light/dark `prefers-color-scheme`, used images), **one self-contained HTML file**
(all chapters, images as data URIs, links rewritten to in-page anchors – for forum attachments),
and *Print this chapter* (system print dialog → PDF). Also **Help → Export manual as HTML…**.

## Context help (`ContextHelp`, `context-help.txt`)

F1 opens the chapter for what the **mouse pointer** is over (else the focus owner), in the main
window and in every dialog/window owned by it. Topics, collected walking up the component tree:
client property `HelpTopics.PROP` (inspector sections `inspector.x:<title>` / `inspector.g:<group>`,
tool options bar `tool.<id>`), menu items / toolbar buttons (`action.<id>` via the action's
"spec"), tool buttons (`tool.<id>` by tooltip), inner tabs (`tab.<title>`), dock tabs
(`panel.<id>`), the selected node kind inside Inspector/Outliner (`node.<KIND>`), the viewport
(`tool.<active tool>`), the window title (`dialog.<title>`), `window.editor`. Mapping file
`src/main/resources/.../tools/help/context-help.txt` (`topic = file.md#anchor`, `prefix*` keys are
wildcards; exact matches of any candidate beat wildcards). The Help → Manual menu item opens the
manual where it was (F1 key = context).

"?" buttons: every Inspector section header, the tool options bar (next to the tool name), and the
right end of every dock's tab row (FlatLaf trailing component, help for the visible panel).

Shell changes (minimal, backwards compatible): new `editor/ui/HelpTopics` (handler hook + "?"
button helper; without a handler nothing is shown), `InspectorPanel.section` (topic property +
"?"), `ToolOptionsBar` (topic property + "?"), `build.gradle` (processResources). `help.shortcuts`
moved from F1 to Ctrl+F1 (re-registered by the help plugin).

## Tests / verification

* `ManualTest`: every .md is in the contents; exactly one H1 per file; **all internal links and
  anchors resolve**, all images exist, no placeholder images; every `context-help.txt` target
  resolves; generated references contain every tool / every built-in mod; search; HTML folder and
  single-file export; Markdown subset unit checks. Unmapped tools/panels/sections are reported on
  stdout (not a failure, so new plugins do not break the build).
* `ManualTour` (test classes, X display): screenshots for the manual and an end-to-end context-help
  run with java.awt.Robot (real mouse/F1 events) on Xvfb :17. Results: `?` on the Inspector's
  "Object parameters" → 09-objects#object-parameters; F1 over the Textures panel →
  08-textures#texture-manager; F1 over the viewport with the Brush tool → 06-geometry#brush-tool-b;
  F1 over the "Waypoint chain" section → 10-waypoints#waypoint-chain-section; F1 in the modal
  Preferences dialog → 03-editor-window#preferences.
  Images: `img/editor/manual_*.jpg`.

## Maintaining the manual

* Edit `docs/manual/*.md`; run `./gradlew test --tests '*ManualTest*'` (link check + regenerates the
  generated blocks). New chapter: add it to `index.md`.
* New tool/panel/section/dialog: add a line to `context-help.txt` (the test prints what is unmapped).
* Screenshots: `ManualTour` steps `geo,nav,village,manual,context,dark`, `RetakeTour` steps
  `library,insert` (open a `GeoLibDemo` level) and `texpaint` (village), and the other tours
  (`EditorTour`, `ObjectsTour`, `EnvTour`); keep images ≤ 1000 px wide (jar size).
* `SmokeTour` (same command line, GeoLibDemo level): real-input checks of the death plane height
  field (typed value without Enter + OK), Ctrl-inverted snapping of the place tool and the
  Inspector's "Exclude from build"; prints PASS/FAIL.