ekklesiaandClaude Opus 5.5
550c0bf126
Pictures print as the picture — no black bars — at the size and place a teacher chooses; a presentation that runs out of memory says so and can be tried again, and the import service survives it; and a notification's Configure button no longer opens KDE's settings under the teacher account. Published to canary: ekklesia-classroom_0.2.6.2_amd64.deb, sha256 a7ca958ac8352bb194a2685e4339fe8cafceb5fee871e4c023402c7320945618, gated on that file as an upgrade from 0.2.6.1 and from 0.2.2. 0.2.6.1 is still on the server as it was. Stable still answers 0.2.2; nothing here wrote to it. The laptop is offline and will take this when it is next on; no desktop is affected. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The teacher's manual
This directory is the only place teacher instructions are written.
Everything a teacher reads comes out of the .md files beside this one:
- the digital manual on each classroom computer, which shows only the features that computer actually has; and
- the printable PDF, which covers every feature with wording that stays true in a room that does not have all of them.
Both are built by tools/build-manual from these files. There is no
second copy to keep in step, and there is no per-room manual: a room
differs from another room by its device.conf, and the manual reads the
same setting the panel does.
Writing a page
Each page is Markdown with a small header:
---
title: Presentations
order: 40
feature: PRESENTATIONS_ENABLED
printed-if: If your computer has a Presentations button
---
## Downloading a presentation
...
| Field | Means |
|---|---|
title |
The heading, and the entry in the contents |
order |
Where it comes. Common pages are 00–39, optional ones 40+ |
feature |
The device.conf setting that decides whether a computer shows this page. Leave it out for a page every room gets |
printed-if |
The conditional sentence the printed manual puts above the page. Required whenever feature is set |
Only ## and ### headings, ordinary paragraphs, * bullets, 1.
numbered steps, simple | tables,  pictures
and bold are supported. That is deliberate: the same text has to come
out well as a web page and as print, and a manual for teachers does not
need anything else.
Writing style
The existing pages set it, and it matters more than the format:
- Say what the teacher does, not what the computer does.
- One instruction per step, in the order they happen.
- Name things the way the screen names them — Present, Quick Look, the bar along the bottom.
- No paths, no package names, no settings files, no version numbers.
- If something can go wrong, say what to do about it in the same breath.
Building
tools/build-manual # both, into docs/manual/build/
tools/build-manual --check # verify only; what the release runs
tools/build-release.sh builds and checks the manual on every release, so
the digital and printed versions cannot drift apart. The check fails the
build if a page declares a feature with no printed-if, if it names a
feature device.conf does not have, or if the built files are missing.
Screenshots
Pictures live in docs/manual/images/. They are captured from the real
interface with tools/lab/lab shot, never drawn or mocked up. A manual
showing a screen that does not exist is worse than one with no pictures.
They are embedded into the digital manual as data URIs, so it stays a
single file that works wherever it is copied and with the network
unplugged. A picture named by a page that is not in images/ fails the
build, as does one with no caption.
The printed manual prints the caption, not the picture — as
[ Picture: ... — see the computer's own Help ]. Embedding a PNG in a
PDF means decoding it and writing an /XObject, and this builder exists
so that a release needs nothing but Python. If the printed manual ever
needs real pictures, that is the thing to add, and it is a contained
change: render_pdf is the only function that would move.