Glossary
Every load-bearing term in the ScriptPub format, defined precisely. Links point to the page where each is covered in full.
Asset — a media file (image, audio, video, font) a document references by
path — conventionally in an assets/ folder beside the work file — but never
contains: the format stores references; resolving them to bytes is tooling.
See Media.
Attribute — a value from a fixed vocabulary carried by a block or mark
(id, href, src, list, lang, origin, rev, data, …).
Persistence is tiered. See Attributes.
Block — one paragraph-level unit of the content stream, a ContentBlock.
Its content follows its kind’s shape. See
Document model.
BlockDef — a block type declaration in config.blocks — id, label,
shape, selector, behavior, indexes, editor flow, foreign-syntax spellings.
See Blocks.
Canonical model — the { config, content, sections, css } data structure
the file parses into and serializes from. The format’s single contract. See
Document model.
Cell — a grid cell: { blocks, attrs? }, optionally spanning / a header /
aligned. See Document model.
Config / FormatConfig — the minimal, non-visual half of a work’s format:
its block types, mark types, editor behavior, adapter settings, and revisions —
plus the in-memory meta. Only what HTML and CSS cannot express. See
Configuration.
Config island — the <script type="application/json" id="scriptpub">
element holding the minimal config (scriptpub, blocks, marks, syntax,
revisions); omitted when trivial. See The file.
Built-in kind — a block or mark from the supported HTML vocabulary, present in every work undeclared: lowercase tag id, lowercase label. A work may override one (same id, Capitalized label); its own custom kinds carry a Capitalized id and label. See Blocks.
Default Paragraph block — the block type (default: true) that is the
fallback for content matching no selector; the built-in p unless a declared
block claims the flag. It declares no selector and writes an unclassed <p>.
See Blocks.
Division — a repeating, ranked structural heading (Act / Sequence /
Scene / Chapter) that forms the outline. A block type becomes a division via
behavior.outline + rank. Distinct from a section. See
Sections & divisions.
Edge block — a block that is a direct <body> child outside every
section element, covered by no section span. Rendered normally, but belongs
to no section. See Sections.
Element attributes — the identity and semantics shared by blocks, marks,
inline objects, and grid cells: class, style, role, epubType, aria,
lang, dir, and custom data. See Attributes.
Grid — a block shape whose content is rows of cells, each
cell a leaf-block stream. Covers tables, side-by-side / dual dialogue, card
grids, and single-cell wrappers (<figure>, <details>, <blockquote>);
one bounded nesting level (a grid never nests in a grid). See
Document model.
Index — a navigator sidebar group (Characters, Locations, …) collected
from block text by a regex pattern. Speaker identity derives from an index,
not a flag. See Blocks.
Inline object / object run — a run carrying one atomic inline object (an inline image or a math expression) instead of text: one caret position, never split; projects as its alt text in plain-text conversion and as empty for inference. See Media and Mathematics.
Kind — a block’s identity — a config.blocks[].id, or the default Paragraph
kind — recognized by matching the element against the declared selectors
(highest specificity wins). See Kind inference.
Mark — inline formatting applied to a run (bold, italic, link, ruby, …), declared with a selector like a block. Marks nest freely. See Marks & links.
MarkUse — a mark on a run: a bare id, or { id, attrs } when it carries
attributes (a link’s href). Stacked outermost-first. See
Document model.
Match rule — a conjunction of text predicates recognizing a kind from its
spelling in one foreign syntax (under BlockDef.syntax); a kind lists
several as a disjunction; first match wins. The file itself uses selectors,
not match rules. See Kind inference.
Matter — a section’s publication partition: front, body, or back.
Standard sections derive it from the vocabulary table; custom sections state
data-spub-matter. See Sections.
Media block — a void-shaped block whose attributes carry a
media src — an image, audio, or video block. What it is resolves from its
selector’s write tag, its type, or its extension — never its kind id. See
Media.
Meta — the in-memory model of the HTML head (title, author,
language, preset, translationOf, …) — serialized only as head markup,
never as JSON. See Configuration and
Metadata.
Narration clip — a block’s slice of the work’s narration audio:
attrs.narration = { src?, start, end } (seconds), defaulting to
meta.narration — the EPUB media-overlay granularity. See
Media.
Run — a stretch of text — or one atomic
inline object — under one mark stack:
{ text?, object?, marks }, exactly one of text / object present. See
Document model.
Section — a unique, named semantic body-level element (Title page, Body, Notes) — never nesting, at most once each. Membership is derived as a SectionSpan. Distinct from a division. See Sections & divisions.
SectionSpan — a resolved half-open range { section, start, end, matter? } over the content, giving each section’s block membership — derived
at parse, never stored. See Document model.
Selector — a kind’s one CSS selector: its recognition rule (matched with
Element.matches semantics, highest specificity wins), the source of its
write spelling (the first alternative’s tag.class compound), and naturally
its stylesheet selector. See Kind inference.
Shape — a block type’s content form: text (runs) · void (attrs only) ·
grid (rows). Exactly three. See
Document model.
spub-base — the one machine layer a file’s stylesheet carries:
@layer spub-base { … } with the theme role tokens, font slots, and
structural floor. Regenerated on every save, skipped on parse; the
document’s own rules follow unlayered and beat it natively. See
The stylesheet.
spub:preset — the metadata-island term recording which app-managed
preset a work’s format was seeded from — a uri or URL, the format’s only
preset trace. See Metadata.
Standard section — an entry of the fixed section vocabulary (id, element,
DPUB-ARIA role, matter, EPUB token): cover, titlepage, toc, body,
appendix, notes, …. Bare header/nav/main/footer imply
titlepage/toc/body/notes. See
Sections.
Spelling / write form — how a kind serializes: in the file, derived from
its selector’s first alternative; in a foreign syntax, the write descriptor
under BlockDef.syntax, applied to the block’s existing runs. See
Kind inference.
Syntax (foreign) — a foreign storage format an app converter can read or
write (md, fountain, fdx, txt, …). A kind’s per-syntax
grammar lives under BlockDef.syntax / MarkDef.syntax; everything else
about foreign formats is app documentation. See
Kind inference.
Translation — an independent work in another language, optionally related
by meta.translationOf + meta.language and block-aligned via origin. See
Translations.