# tools/manual — the pictures in docs/manual

`record.sh` drives the desktop build on a private X server and records the
scenes in `scenes.py` into `docs/manual/media/`:

```bash
tools/manual/record.sh /var/tmp/dr-demo/library              # every scene
tools/manual/record.sh /var/tmp/dr-demo/library develop_zoom # one, and what it needs
tools/manual/record.sh --changed /var/tmp/dr-demo/library    # those whose sources moved
tools/manual/record.sh --check                               # the manual and the scenes agree
tools/manual/record.sh --list
```

Set `DR_LIBRARY_SNAPSHOT` to a pristine copy of the library: a recording
rates, files and merges, and the snapshot is copied over the library first.
Each run starts from a fresh profile under `DR_HOME`.

## Controls by name

The binary is built with `--features automation`, which lets the app answer
"where is the control labelled *Exposure*?" over the Unix socket named by
`DR_AUTOMATION` (`ui/dr-ui/src/automation.rs`). No other build has the
feature, and a build that has it listens only when the variable is set. The
names are the accessible labels a screen reader reads, so a scene says
`click_on('Select@Button')` or `slide('Exposure', 24)` rather than a pixel,
and survives a panel that moves. The pointer itself is still xdotool.

```bash
DR_HOME=/var/tmp/x tools/manual/drive.py launch /some/folder   # a feature build in DR_BIN
tools/manual/drive.py labels                 # every name on screen
tools/manual/drive.py click-on 'Settings@Button'
tools/manual/drive.py ids canvas             # things with no name: id:canvas-image
tools/manual/drive.py stop
```

Grid cells are named by file (`_MG_8393@ListItem`), rating stars `1 star`
to `5 stars`. What a scene cannot name — a point on the photograph, the crop
rectangle's corner — it places relative to something it can
(`drive.photo(fx, fy)`, `id:move-area`).

## Scenes and the manual

Each scene in `scenes.py` declares the pictures it makes, as the manual names
them, and the globs of the sources that could change them. `--check` fails
when the manual shows a picture no scene makes, or a scene makes one the
manual does not show; it reads two files and runs in CI. `--changed`
re-records a scene when one of its sources, or its own code, has changed
since the commit that last touched its pictures.

Two things the scripts know that are not obvious: a Slint `TouchArea` wants
a held press, not xdotool's `click`; and the app is driven on Xvfb rather
than the desktop because under XWayland at scale 2 a pointer warp lands at
twice the coordinate asked for.