# 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:

```markdown
---
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, `![caption](images/x.png)` 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.