b719c43991
The presenter view now doubles as a rehearsal clock that measures without coaching: a countdown against a target time, the time spent on the current slide, and an end-of-run summary (total vs. target and per-slide times, with copy-to-clipboard). Timing lives in a plain, unit-tested RehearsalController fed via an idempotent observe() on every build, so it captures every navigation path. The default target is stored in AppSettings; live adjustment is the K key (typed as MMSS). All rehearsal state is session-only -- nothing is written to disk or into the .md file. - New: models/rehearsal.dart, services/rehearsal_controller.dart, widgets/presentation/rehearsal_summary.dart, plus a controller unit test. - Presenter: countdown + per-slide timer in the clock bar, K to set the target, R resets the run, end-of-run summary dialog, and help/cheatsheet entries. - Settings: presentationTargetSeconds (default target) with a dropdown in the General tab, threaded into FullscreenPresenter.present(). - l10n: new Dutch source strings translated in all seven languages. - Docs: README, CHANGELOG, USER_GUIDE, SHORTCUTS, ARCHITECTURE. Also bundles a pre-existing in-progress change already in the working tree: wire the existing ThemeProfile.tableHeaderBackgroundColor into table rendering (preview, HTML export, file_service) and the settings dialog, plus its translations. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
206 lines
10 KiB
Markdown
206 lines
10 KiB
Markdown
# OciDeck — User Guide
|
||
|
||
OciDeck builds [Marp](https://marp.app/) presentations through a structured,
|
||
slide-by-slide editor. You compose typed slides, preview them live, present them
|
||
(on one or two screens), and export to Markdown, PDF, PPTX, or a self-contained
|
||
HTML file. Files stay standard Marp Markdown, so a deck remains usable in other
|
||
Marp tools.
|
||
|
||
## Creating and opening decks
|
||
|
||
- **New / Open**: use the welcome screen or `Ctrl/Cmd + O`. Multiple decks open in
|
||
**tabs**.
|
||
- **Save**: `Ctrl/Cmd + S`. Saving lays out a tidy project folder next to your
|
||
`.md` (`images/`, `data/`, `logos/`, `themes/`) and copies assets in. See
|
||
[`FILE_FORMAT.md`](FILE_FORMAT.md).
|
||
- **Crash recovery**: unsaved work is snapshotted automatically and offered back
|
||
after an unexpected exit.
|
||
|
||
## Slide types
|
||
|
||
Add a slide and pick a type: **title**, **section** divider, **bullets**, **two
|
||
bullet columns**, **bullets + image**, **two images**, **large image**, **video**,
|
||
**audio**, **quote**, **table**, **source code**, **chart** (bar, line, pie, or
|
||
spider/radar), and **free Markdown**. Each card in the chooser shows a miniature
|
||
wireframe of the layout, and the dialog works entirely with the keyboard
|
||
(`Tab`/`Enter` to choose, `Esc` to cancel). Each type has a dedicated editor on
|
||
the left and a live preview on the right.
|
||
|
||
Text fields support inline Markdown (`**bold**`, `*italic*`, `` `code` ``,
|
||
`[links](…)`). Free-Markdown slides also render fenced code with syntax
|
||
highlighting and `$…$` / `$$…$$` LaTeX math.
|
||
|
||
### Source-code slides
|
||
|
||
Choose a programming language for syntax highlighting (or "plain text") and paste
|
||
your code. It renders as a "code sheet" whose background, text colour and
|
||
**monospace font** come from the active **style profile** (e.g. Courier). Turn
|
||
**syntax colouring** off to show the whole block in a single colour — e.g. bright
|
||
green on black for a classic CRT-terminal look. The text is sized to fill the
|
||
panel — larger when there's room, smaller for long fragments. Stored as a fenced
|
||
code block in the Markdown.
|
||
|
||
### Tables
|
||
|
||
The first row is the header. Press `Enter` inside a cell for a new line within
|
||
that cell. To bring in existing data, **paste a table into any cell** with
|
||
`Ctrl/Cmd+V` (or `Shift+Insert`): a selection copied from a spreadsheet (Excel,
|
||
Numbers, LibreOffice Calc, Google Sheets), CSV text (comma- or
|
||
semicolon-separated), or a markdown table fills the grid from that cell onward,
|
||
adding rows and columns as needed. Ordinary text — even a sentence with a comma
|
||
in it — still pastes into just the one cell.
|
||
|
||
### Charts
|
||
|
||
Pick a type (**bar**, **line**, **pie**, or **spider/radar**) and a title, then
|
||
enter data in the grid: the first column is the labels, each further column is a
|
||
named series. Use **Row** and **Series** to add data; the small ✕ removes a
|
||
row/column. Each series and (for pie/radar) each label can be given its own colour.
|
||
|
||
- **CSV import** — click **CSV importeren**. You can either keep the data **in the
|
||
slide** (inline) or store it **as a CSV file**. A linked CSV lives in the deck's
|
||
`data/` directory and stays the source of truth (edit it in a spreadsheet); the
|
||
grid then shows it read-only until you **Ontkoppelen** (unlink).
|
||
- **Min/max** (optional, bar/line/radar) — on bar and line charts these draw
|
||
horizontal **reference lines**; on a spider/radar chart they fix the **scale**
|
||
(centre to outer ring), shown as evenly spaced values in a small legend beside
|
||
the chart. Leave them empty to scale automatically.
|
||
- **Reading values** — hovering a legend entry highlights its series (or pie
|
||
slice). On a line chart the tooltip belongs to the dot under the cursor and
|
||
shows every overlapping dot at once; on a spider/radar chart hovering a point
|
||
shows its value in a tooltip too. For screen readers every chart also carries
|
||
a text alternative with its type, title, and the values per series.
|
||
- Charts render in the preview, presenter, PDF, and PPTX, and as inline SVG in the
|
||
HTML export.
|
||
|
||
## Image library
|
||
|
||
Image fields open a library that shows every image found in the deck's
|
||
directories, with a grid and a coverflow view, search, and a preview pane. Per
|
||
image you can store a **caption** (source/credit line, shown on the slide) and a
|
||
searchable **description** — in practice your tags. The search box matches file
|
||
names and descriptions.
|
||
|
||
- **Filter untagged images** — the label toggle next to the search box shows
|
||
only images that have no description/tags yet, so you can see at a glance
|
||
which ones still need attention.
|
||
- **Clean up duplicates** — the button in the footer finds byte-identical
|
||
images by md5 checksum. Per group one file is kept (preferring the one used
|
||
in slides, then the oldest), tags and captions of the copies are merged onto
|
||
it, slides that referenced a copy are repointed to the kept file, and the
|
||
copies are deleted — after a confirmation that lists exactly what will
|
||
happen. References are updated in the open decks *and* in `.md`
|
||
presentations found on disk in the search directories, so presentations
|
||
that are not currently open keep working too.
|
||
- **Deleting an image** warns when it is still in use — in open decks (per
|
||
slide) and in presentations on disk that are not currently open (per file,
|
||
marked "not open").
|
||
|
||
## Per-slide options
|
||
|
||
Below each editor you can set:
|
||
|
||
- **Auto-advance** after N seconds.
|
||
- **TLP of this slide** — a Traffic Light Protocol level (see below).
|
||
- Show/hide the **logo** and **footer** on this slide.
|
||
- **Speaker notes**.
|
||
- An optional **audio** attachment.
|
||
|
||
## Traffic Light Protocol (TLP)
|
||
|
||
A deck has an overall TLP level (shown as a marking on the slides). Each slide can
|
||
*also* carry its own level. When you present or export, slides whose level is
|
||
**stricter** than the level chosen for the deck are **withheld** — so the same
|
||
deck can be shown safely to audiences with different clearances. Order, least to
|
||
most restrictive: none < CLEAR < GREEN < AMBER < AMBER+STRICT < RED.
|
||
|
||
Classifying a deck is **optional**. As an extra guardrail, an organisation can
|
||
set a **release ceiling** — a maximum level that may leave the machine; see
|
||
*Exporting* below.
|
||
|
||
## Presenting
|
||
|
||
Start the fullscreen presenter from the toolbar. See
|
||
[`SHORTCUTS.md`](SHORTCUTS.md) for the full key list; highlights: arrows to move,
|
||
`G` for the grid overview, `B`/`W` to blank, `P` for presenter view, `K` for the
|
||
countdown, `R` to reset the timing, `H` for the in-app cheatsheet.
|
||
|
||
### Rehearsing and timing
|
||
|
||
The presenter view (`P`) is also a rehearsal clock — it measures, it does not
|
||
nag. The clock bar shows four things:
|
||
|
||
- **Elapsed** — time since the run started (or since the last `R`).
|
||
- **Remaining** — a countdown against a **target time**. It turns red and shows a
|
||
minus sign once you go over; there is no "speed up" coaching, just the number.
|
||
- **This slide** — how long you have spent on the current slide. Time accumulates
|
||
per slide across the whole run, even if you jump back and forth.
|
||
- **Clock** — the wall-clock time.
|
||
|
||
Set the target time up front under *Settings → General → Presentation*, or change
|
||
it live while presenting with **`K`** (type the minutes and seconds as `MMSS`,
|
||
`Enter` to confirm, `0` to switch the countdown off). **`R`** resets the run —
|
||
elapsed time and per-slide timings — while keeping the target.
|
||
|
||
When you leave the presenter after a run of at least ten seconds, a **summary**
|
||
shows the total time against the target and the time spent per slide, with a
|
||
button to copy the times to the clipboard. This is **session-only**: nothing is
|
||
written to disk or into the `.md` file.
|
||
|
||
### Two screens (beamer + laptop)
|
||
|
||
When a second display is connected, OciDeck automatically shows the **slide on the
|
||
beamer** and the **presenter view on your laptop** (current slide, next slide,
|
||
notes, clock). Use an *extended* (not mirrored) display. Notes:
|
||
|
||
- The keyboard stays on the laptop; clicking the beamer also advances.
|
||
- On macOS the "external" screen is the one without the menu bar.
|
||
|
||
### Annotating while presenting
|
||
|
||
Draw on the slide live with **D** pen, **T** highlighter, **E** eraser, **X**
|
||
laser pointer, and **C** to clear; `Esc` puts the tool away. Drawings are a
|
||
separate layer (never written into the Marp Markdown), mirror live to the beamer,
|
||
and are saved in a `<name>.ink.json` sidecar so they persist with the deck.
|
||
|
||
## Exporting
|
||
|
||
Export to:
|
||
|
||
- **PDF** and **PPTX** (PPTX includes speaker notes) — rendered from the in-app
|
||
slide renderer.
|
||
- **Self-contained HTML** — one offline file; code highlighting, math, charts, and
|
||
mermaid diagrams render in the browser.
|
||
- **Portable package** (`.ocideck`) — a single zip with the Markdown and all
|
||
assets, to hand the whole deck to someone else.
|
||
|
||
**Release ceiling (optional).** When a maximum TLP level is configured, exporting
|
||
a deck classified *above* it is blocked for every format, and the export dialog
|
||
explains why. The ceiling is off by default and classifying a deck stays
|
||
optional — it only stops decks that exceed the configured level.
|
||
|
||
## Accessibility
|
||
|
||
OciDeck aims for WCAG 2.1 in the editor:
|
||
|
||
- **Interface text size** — Settings → General → Accessibility offers 100–200%
|
||
text scaling for the whole editing environment, on top of what the operating
|
||
system asks for. Slides keep their fixed 16:9 design size, so what you see is
|
||
still exactly what you present and export.
|
||
- **Keyboard** — the panel divider between the slide list and the editor can be
|
||
focused with `Tab` and resized with `←`/`→`; the add-slide dialog is fully
|
||
keyboard-operable.
|
||
- **Screen readers** — slide thumbnails announce a concise label ("Slide 3/12:
|
||
title", including the skipped state), charts read out their data as a text
|
||
alternative, and the fullscreen presenter announces every slide change.
|
||
|
||
## Theming and language
|
||
|
||
- **Style profiles** control deck colours (including the source-code background,
|
||
text, font and an optional syntax-colouring toggle), fonts, logo, and footer.
|
||
Every colour can be picked from the presets or entered as a custom hex value. The
|
||
Colours and Logo tabs show which profile you're editing. The bundled Marp theme
|
||
is `assets/themes/ocideck.css`.
|
||
- **App appearance** (including a dark interface) is configurable in settings.
|
||
- The interface is available in Dutch, English, Italian, German, French, Spanish,
|
||
Frisian, and Papiamento.
|