8  Structured Page XML Reference

Element inventory with evidence grades and OCR production rules

8.1 Document structure

Every OCR’d page produces one XML document conforming to page.dtd. The root element is <page>:

<page pidx="57" volume="kgw-13">
  <meta model="qwen3.8:27b-mlx" instruction_template="kepler-ocr" lang="orig"
        processed_date="2026-09-28" page_index="057"
        partitur="kepler-ocr@3f400c0df6fa" layers="page-language,base,qwen38"/>
  <header>KGW XIII · Brief 764</header>
  <main>
    <p><marginal side="left" type="line-number">5</marginal>Gott gebe daß es wol gehe. Ich bitte von hertzen</p>
  </main>
  <footnotes>
    <footnote><fn>1</fn> Kepler an Hafenreffer, 11.2.1608</footnote>
  </footnotes>
</page>

The shared declarations (marginal, meta, figure, table, the renditions of hi) come from the page-language core; see Chapter 2.

8.2 Element reference

8.2.1 <page> (root)

Attributes:

Attribute Type Required Description
pidx integer yes 0-based page index within the volume
volume string yes Volume identifier, e.g. kgw-13
lang NMTOKEN no ISO 639-1 language code (de, la, en, …)
source string no PDF path used for OCR

8.2.3 <p> (paragraph)

Main text paragraph. May contain: #PCDATA | hi | fn | marginal | equation | ref.

Never flatten a table or figure into <p>. A <p> is linear prose.

8.2.4 <hi> (typographic emphasis)

Attribute rend: closed vocabulary — italic, bold, spaced, smallcaps, superscript, subscript.

Missing rend is an audit violation (SCH-REND-MISSING). Never use <hi> without rend.

8.2.5 <marginal>

Everything printed in a margin (Chapter 2). A <marginal> stands directly before the first word of the printed line it is printed beside, inside that paragraph (or cell, or letter element).

Attributes (declared in pdai-core.mod; #IMPLIED in the grammar, required by the audit on pages produced by a composed partitur):

Attribute Values
side left, right — the margin where it is printed
type markers line-number, folio, symbol; notes topic, reference, date; collection extensions doc-id (KGW 19), entry-number (medieval-sec)

note, marginal-note, label and gloss are not types; the normalizer maps them to topic. A marginal is never a <p> of its own and never the last thing in a paragraph.

8.2.6 <figure>

<figure ref="fig_057_1">
  <caption>Fig. 1: Epicycle diagram</caption>
  <description>Circle with inner circle, labeled P and O</description>
</figure>

Never replace a figure with an image crop. The <description> element is the text transcription of what the figure contains; <caption> is the printed label.

8.2.7 <table>, <tr>, <th>, <td>

Mathematical ephemerides, trigonometry grids, and data tables must be transcribed as genuine HTML-style table markup — never flattened to <p>. Column counts must be consistent across all <tr> within a <table>. Inline mathematics within cells uses LaTeX syntax ($formula$).

8.2.8 <equation>

Display-mode mathematical expression. Placed as a direct child of <page> or as a block child of <p> (the latter triggers a CSS layout violation that the coherence audit flags).

<equation display="true">$$\sin 30° = \frac{1}{2}$$</equation>

8.2.9 <footnotes>, <footnote>, <fn>

Footnotes always appear at the bottom of the page inside <footnotes>. <fn> is the inline superscript marker; <footnote> is the note entry.

<p>The comet appeared<fn>3</fn> on the 12th.</p>
<footnotes>
  <footnote><fn>3</fn> Observed by Kepler, KGW III p.~47.</footnote>
</footnotes>

8.2.10 Epistolary apparatus (kepler-prim, pirckheimer, karman-nachlass)

<letter-head> contains: <reference>, <date>, <archive>, <salutation>.

<letter-closing> contains: <greeting>, <signature>, <address>, <postscriptum>.

These elements are collection-specific extensions beyond canonical v3.0.

8.3 Evidence grades for schema fields

Every field in the schema YAML carries one of these grades, which determines how confidently OCR can generate it:

Grade Meaning Instruction implication
front-matter Declared explicitly in the edition’s front matter Authoritative; OCR must produce this element
facsimile-only Observed in body pages but not declared in front matter Provisional; OCR should produce it but cannot cite authority
unattested Not seen anywhere Must not appear in schema; do not generate

8.4 Production rules

  1. Page OCR is page-scoped. No cross-page inference. Assemble records in a separate segmentation pass after all pages are complete.
  2. XML must be escaped for editorial angle brackets: use &lt; / &gt;.
  3. <think> blocks and markdown fences from the model must be stripped by the normalizer (ocr_runner.normalize) before the XML is stored.
  4. Ampersands must be escaped to &amp; in all text content.
  5. HTML tags (<b>, <i>, <sup>, <sub>, <br>) are forbidden in PDAI XML and trigger audit code SCH-HTML-TAG.