ekklesiaandClaude Opus 5.5
940f63e0e5
The black bars above and below a printed picture were neither in the picture nor in the layout. A PNG or JPEG in a tab of its own is shown by the engine on a viewer page whose background is rgb(14, 14, 14), and Qt prints page backgrounds by default; 0.2.6.1 printed that page. A picture is now taken as itself — drawn onto white, capped at 300 dpi across Letter — and laid out on the printer's paper by the preview, with Size (as large as fits down to 25%), Position (nine squares), Paper (automatic, upright, sideways) and Fill the whole page, which says it cuts the edges off and is never the default. The preview is the PDF that prints, laid out again after each change. Worksheet PDFs and lesson pages get no picture controls and are unchanged. Page backgrounds are no longer printed for lesson pages either, as in Chrome; Blink darkens light text when it does that, so a white-on-black page prints readable grey on white. "Colour" is "Color" in the print interface and the manual. Lab: 135 print checks, now including eight picture layouts measured on the job file CUPS kept — byte-identical to the preview, within 1 point of where asked, no ink anywhere else. Printed from the real session with the pointer: 50% top left, Elmer-66, the same. Not yet on paper. 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.