docs: one manual, the pages a device has and a printable copy of all of them

Documentation becomes part of the release rather than a job afterwards.
docs/manual is now the only place teacher instructions are written, and
tools/build-manual produces both versions from it:

  classroom-manual.html   installed on every machine, showing only the
                          features THAT device has
  classroom-manual.pdf    the universal printed manual, every feature,
                          with a conditional sentence above each
                          optional page so it stays true in a room that
                          does not have them all

They cannot drift apart because neither is written by hand, and
build-release.sh builds and checks them on every release: a page that
declares a feature with no printed-if fails the build, because that is
exactly how the printed manual comes to state an optional feature as
though every room had it. So does a page naming a feature device.conf
does not have, and an optional feature with no page at all.

WHAT REACHES THE CLASSROOM ACCOUNT. Only a list of setting NAMES, and
only ones the package already defines as optional applications.
classroom-desktop-layout — already the one place that decides what a
device offers — writes them to /run/ekklesia-classroom/features.json,
and classroom-manual filters that against FEATURES before using it. No
values from device.conf, no broker password, no addresses. With no
manifest at all every page is shown, which is the printed manual and is
never wrong, only less specific.

Help is a Quick Launch button beside Parent Call, deliberately not in
the row with the applications: putting it there would move buttons
teachers reach for without looking. Every room gets it, because a
teacher who needs the manual is by definition one who does not know
where to look.

The PDF is written directly rather than converted. A manual is
headings, paragraphs, bullets, steps and one table; writing that with
the standard fonts is a couple of hundred lines and no dependency, so a
release can be built on any machine with Python. Pictures are embedded
in the digital manual as data URIs so it stays one file that works
wherever it is copied and with the network unplugged; the printed
manual names them instead, which is the one thing this builder does not
do and is noted where somebody would look for it.

Two defects found building it, both of which hung or corrupted the
output rather than failing: a paragraph opening with a bold word
matched the bullet guard but not the bullet rule, so nothing consumed
it and the build spun; and a list item wrapped across two source lines
ended the list, so a three-step procedure printed as three steps all
numbered 1.

Also adds the 0.2.6 physical checklist to docs/testing.md and the
release validator's checks for the Wi-Fi regression, the conversion
pipeline on a real Debian, the fonts, the manual and the dock order.

Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
2026-09-22 20:21:39 -05:00
co-authored by Claude Opus 5
parent 55f4c183c7
commit f2942a2946
21 changed files with 2533 additions and 3 deletions
+100
View File
@@ -473,3 +473,103 @@ With `LIVE_ENABLED=true`:
single after reinstall
- [ ] `tools/validate-trixie-release.sh` passes against the 0.1.37 package and
the 0.1.36 package
## Presentations — 0.2.6, the prayer-room laptop
Everything here needs the real television, the real keyboard and the
pastor's own session files. The automated tests and the Plasma lab cover
the logic and the windows; none of them can tell you that Session 7's
text is the right size from the back of the room.
Enable it first, and reboot:
```
sudo sed -i 's/^PRESENTATIONS_ENABLED=.*/PRESENTATIONS_ENABLED=true/' \
/etc/ekklesia-classroom/device.conf
sudo reboot
```
### Download
- [ ] The bar has a **Presentations** button, after the Browser
- [ ] Wonder Ink and Parent Call are still absent from this laptop
- [ ] Download tonight's session in ordinary Chrome
- [ ] It does **not** appear in the library while it is still downloading
- [ ] It appears by itself within a few seconds of the download finishing
- [ ] The title is readable — not a hash, not a long filename
- [ ] The original download is still in Chrome's downloads, untouched
- [ ] Download the **PDF and the PPTX** of the same session: two cards,
the second titled `(2)`, neither overwriting the other
### Quick Look
- [ ] **Quick Look** opens and shows slide 1
- [ ] **Next** and **Previous** move through every slide
- [ ] The text and layout are right — check a slide with a Bible verse
- [ ] Go to the session-number slide, usually slide 2
- [ ] **Use this slide as the picture** changes the card
- [ ] **Back to Presentations** returns without presenting
- [ ] Close the library, open it again: the chosen picture is still there
- [ ] Reboot, open it again: still there
- [ ] `classroom-presentation-import --status` shows `presented never`
That last line is the one that matters. Quick Look, browsing every slide
and changing the picture must not have counted as a presentation.
### Present
- [ ] **Present** from the card fills the **external television**
- [ ] It starts at slide **1**, not at the slide chosen for the picture
- [ ] **Present** from inside Quick Look does the same
- [ ] Space, the arrow keys and Page Up/Page Down all move slides
- [ ] The presentation remote's forward and back buttons work
- [ ] Fonts and layout are right on the television, from the back
- [ ] **Esc** returns to the library — **not** the Impress editor, not a
terminal, not a blank screen
- [ ] Going past the last slide does the same
- [ ] `--status` now shows a presentation time and a count
- [ ] Present it again: the count rises and the expiry moves out 30 days
- [ ] Unplug the network and present again: it still works
### The awkward ones
- [ ] A PDF and a PPTX of the same session look the same on screen
- [ ] A deliberately broken file gives a short message and only
**Remove** — no editor, no terminal
- [ ] A long session (40+ slides) opens without the library freezing
- [ ] Download a Wonder Ink worksheet: it does **not** appear in the
library
### Remove
Use a **test copy**. Not tomorrow's session.
- [ ] **Remove** asks first
- [ ] The card goes, and its slides and pictures go with it
- [ ] The original download in Chrome is untouched
- [ ] It does not come back on the next scan or after a reboot
### The manual
- [ ] **Help** is on the bar, bottom left
- [ ] It opens with no address bar and no tabs
- [ ] It shows Browser, Presentations, sound and the common pages
- [ ] It does **not** mention Wonder Ink, Parent Call or the DVD
- [ ] It works with the network unplugged
- [ ] On a children's classroom machine it shows the opposite set
- [ ] Print `/usr/local/share/ekklesia-classroom/manual/classroom-manual.pdf`
and check the conditional wording reads sensibly in a room that
does not have every feature
- [ ] The revision date is on the printed copy
### Wi-Fi — look, do not touch
The laptop's Wi-Fi is already working through NetworkManager and its
ifupdown stanza is already gone. **Do not run `--adopt` on it.**
- [ ] `classroom-wifi --check` says there is no wireless interface under
ifupdown's control
- [ ] `classroom-wifi --adopt` says "nothing to adopt" and changes nothing
- [ ] `nmcli -g 802-11-wireless.hidden connection show "ROGC Classroom"`
still reports `yes`
- [ ] The laptop still reconnects after a reboot