Glossary

The words this site uses. In the chapters, a dotted word shows its definition when you hover it, and leads here when you click it.

Screen

E-ink: Each pixel holds charged black and white particles. A voltage pulls one color to the surface. The image stays when the power is off, which is why e-readers last weeks, but changing it is slow (hundreds of milliseconds) and can leave a ghost of the previous image. Learn more →
Waveform: The panel controller knows several waveforms. Inkshelf uses GL16 for page turns, GC16 for a full clean refresh, and the firmware also offers DU, A2, GC4 and DU4. Learn more →
GC16: The slow, full-quality waveform: 16 grays, and every pixel is driven, so it flashes and wipes ghosts. Learn more →
GL16: The 16-gray waveform for page turns: it drives only the pixels that change, so it does not flash, but ghosts build up. Learn more →
DU / A2: Fast waveforms that only know black and white (DU) or are tuned for animation (A2): quick, but crude. Learn more →
Ghosting: A faint trace of the previous image left after a partial refresh. A full (flashing) refresh clears it. Learn more →
Full refresh: Inkshelf flashes every 5 page turns of a comic and every 6 of a text book, and whenever a screen changes completely. Learn more →

Device

Framebuffer: The block of memory (/dev/fb0) the panel controller reads pixels from. Writing to it changes nothing on screen until a refresh. Learn more →
Canvas: Where Inkshelf draws: a 1404×1872 gray image in shared memory, upright. A refresh copies it, rotated, to the framebuffer. Learn more →
ioctl: A system call that sends a device-specific command to a driver, here to ask the panel for a refresh (MXCFB_SEND_UPDATE). Learn more →
cgo: Go's bridge to C code. Inkshelf does not use it, so a plain go build makes the reader's program on any computer. Learn more →
IPC: Inter-process communication: how the app and the reader's firmware talk, through shared memory and message queues. Learn more →
Shared memory: Memory two processes see at once. The firmware publishes its state there, such as which app is in the foreground. Learn more →
Message queue: A mailbox in the kernel: one process posts messages, another reads them. Inkshelf reads input and firmware events from two. Learn more →
Foreground: The app the reader shows. Only the foreground app may read input and refresh the screen. Learn more →
Event loop: The one goroutine that polls for input and firmware messages every 20 ms and calls the app. It is the only one that draws. Learn more →
Emulator: A stand-in for the reader in a web page on your computer: the real event loop and screens, with a fake firmware. Learn more →
Static binary: A program that carries everything it needs inside one file, so it runs on the reader without any library installed there. Learn more →
Task: What the PocketBook firmware calls a running app. It knows each one by its process group id (pgid). Learn more →
Hot path: Code that runs for every pixel of every page turn. Tuned against the ARM assembly, and changed only with benchmarks. Learn more →

Images

16 grays: The InkPad 3 shows 16 levels from black to white, 17 apart on the 0–255 scale: 0, 17, 34, … 255. Learn more →
Dithering: Hiding the lack of grays by spreading each pixel’s rounding error onto its neighbours, so the eye sees the right average. Learn more →
Tone curve: A table that maps each input gray to an output gray: here it stretches the contrast and darkens the mid-tones for e-ink. Learn more →
.pg4: Inkshelf’s page image file: a small header, then two pixels per byte (4 bits each), ready to draw. Learn more →
Nibble: Half a byte: 4 bits, a number from 0 to 15. Exactly one of the 16 grays. Learn more →
Box filter: Shrinking an image by making each new pixel the average of the source pixels it covers. Learn more →
Gamma: A curve that brightens or darkens the mid-grays while keeping black and white. Inkshelf uses 1.8 to darken the grays of page images for e-ink; text gets none. Learn more →
Histogram: A count of how many pixels have each gray level. It shows at a glance whether a scan is faded. Learn more →

Books

EPUB: A zip of web pages (XHTML), stylesheets, images and fonts, plus a package file that says in what order to read them. Learn more →
Package document (OPF): The EPUB’s table of contents for machines: metadata, the manifest of every file, and the spine. Learn more →
Manifest: The list of every file in the EPUB, each with an id and a media type. Learn more →
Spine: The reading order: a list of manifest ids. Items marked linear="no" are reached only by links (notes, for example). Learn more →
Navigation document: The human table of contents of an EPUB 3, an XHTML page with a <nav> list (or the older NCX file). Learn more →
Reflowable: A book whose text is laid out again for the screen and font size, like a web page, as opposed to fixed layout. Learn more →
Fixed layout: A book whose pages have a set size and position for everything, like a PDF; Inkshelf draws each page whole. Learn more →
Cascade: CSS’s rule for which declaration wins when several apply: !important first, then the style attribute, then specificity, then the later rule. Learn more →
Specificity: How precise a CSS selector is, counted as (ids, classes, element names). The more precise rule wins. Learn more →
em: A length relative to the font size: 1.5em is one and a half times the text size. Inkshelf stores lengths in hundredths of an em. Learn more →

Layout

Block: One paragraph, heading, image or rule in Inkshelf’s document model, with its margins and a list of runs. Learn more →
Run: A stretch of text with one style (italic, bold, a size, a link…). A block is a list of runs. Learn more →
Line breaking: Choosing where each line ends. Inkshelf is greedy: it fills a line with as many words as fit, then starts the next. Learn more →
Hyphenation: Cutting a word at the end of a line with a hyphen. Liang’s patterns find where a word may be cut. Learn more →
Justification: Spreading the space left at the end of a line over its gaps, so both edges are straight. Learn more →
Bidi: Bidirectional text: Arabic or Hebrew (right to left) mixed with Latin (left to right) on one line. Learn more →
Pagination: Cutting a chapter’s lines into pages, keeping a heading with what follows and a paragraph’s first two lines together. Learn more →
Rune offset: A position in a chapter counted in characters (Go calls them runes). It stays the same when the font size changes; page numbers do not. Learn more →
Virtual page: 1500 characters of an EPUB. A stable “page number” for progress and the server, whatever the font size. Learn more →
Orphan: A paragraph’s first line left alone at the bottom of a page. Inkshelf moves it to the next page instead. Learn more →
Location: Where you are in an EPUB: a chapter number and a rune offset in it. What Inkshelf saves instead of a page number. Learn more →
index.json: Made at download time: each chapter’s character count, the table of contents and the page list, so progress needs no layout. Learn more →
Glyph: The drawn shape of a character in a font. Usually one per character, but a ligature is one glyph for several, and an Arabic letter has one per position in its word. Learn more →
Baseline: The line letters sit on. Inkshelf places text by the top of its line; the baseline is the font's ascent below it. Learn more →
Kerning: A small adjustment of the space between two given letters, such as A and V, stored in the font. Learn more →
Hinting: Snapping a glyph's outline to the pixel grid. With full hinting, advances are whole pixels, so a glyph can be rasterized once and reused. Learn more →
Alpha mask: A small image saying how much of each pixel a glyph covers, 0 to 255. Drawing text blends the ink into the page through it. Learn more →
Font fallback: Drawing the characters a font lacks with another font that has them: DejaVu Sans, then Go's font. Learn more →
.notdef: The glyph a font draws for a character it does not have: usually an empty box, nicknamed "tofu". Learn more →
Shaping: Turning a run of characters into the right glyphs at the right places, by the font's own rules: Arabic letters join, Hebrew points stack. Learn more →

App

Screen: One page of the app’s UI (library, series, reader…), a Go package that draws itself and handles its taps. Learn more →
Target: A rectangle a screen registers while it draws, with what to do when it is tapped. Learn more →
State: Everything the app knows (current screen, books, downloads…), in one struct guarded by one mutex. Learn more →
state.Update: The only way another goroutine changes the state: take the lock, change it, and ask for one repaint if needed. Learn more →
Mutex: A lock: only one goroutine at a time may hold it, so they never change the same data at once. Learn more →
…Locked: A function whose name ends in Locked runs with the state’s mutex already held, and never takes it itself. Learn more →
Deadlock: Two goroutines each wait for a lock the other holds, forever. A fixed lock order prevents it. Learn more →
Goroutine: Go’s lightweight thread. Inkshelf starts them only from the main thread, with state.Go. Learn more →
Wakeup: A doorbell for a background loop: ringing it many times wakes the loop once, and never blocks the ringer. Learn more →

Servers

Server: Where books come from: Komga (comics), Mealie (recipes) or Calibre-Web (EPUB and CBZ). The app sees them through one Go interface. Learn more →
Shelf: The downloaded books on the reader, one folder each, with book.json written last. Learn more →
Registry: The one package that knows every kind of server: it opens the right one for each entry of config.json. Only the programs in cmd/ import it. Learn more →
OPDS: A catalog of books as Atom feeds, a page at a time. Inkshelf reads Calibre-Web through it. Learn more →
Sort key: What a title sorts by: without accents or a leading article, its numbers compared as numbers. "Le Tome 2" files under T, before "Tome 10". Learn more →
Atomic rename: Write a file under a temporary name, then rename it: other code sees the old file or the whole new one, never half. Learn more →
Debounce: Wait until things calm down before acting: ten quick page turns send one progress update, 3 s after the last. Learn more →
Watchdog: A timer that gives up on a download when no data has arrived for 30 seconds. Learn more →
Syncer: The part of Inkshelf that sends reading progress to the server, a few seconds after the last page turn. Learn more →