Umbraformat/docs/umbraformat_specification_document.md

Specification: UmbraFormat (Print-Ready Book Document Processor)

1. Executive Summary

UmbraFormat is an automated document transformation engine designed to convert Microsoft Word (.docx) manuscript drafts into print-ready PDF files suitable for physical publication (e.g., KDP, IngramSpark, traditional print runs).

The primary objective of this specification is to establish deterministic rules for handling Front Matter, Body Text, and Back Matter, while ensuring precision in page setup, running headers/footers, pagination, typographic hierarchy, multilingual support, and embedded graphical icon placement.

---

2. Document Layout & Global Specifications

2.1 Target Geometry & Margins

• Trim Size: Standard 6" \times 9" (152.4 mm \times 228.6 mm) or 5.5" \times 8.5" (139.7 mm \times 215.9 mm) configurable.
• Gutter / Inside Margin: Dynamic based on the final total page count:
  • < 150 pages: 0.50 in (12.7 mm)
  • 150 - 300 pages: 0.625 in (15.8 mm)
  • > 300 pages: 0.75 in (19.0 mm)
  • Resolution procedure: the engine builds the document with the lowest-bucket value, renders it to determine the page count, recomputes the gutter, and rebuilds until the page count and gutter agree (fixed point, maximum 3 builds; if the count oscillates across a bucket boundary, the larger gutter is used).
• Outside Margin: 0.375 in (9.5 mm)
• Top Margin: 0.40 in (10.2 mm)
• Bottom Margin: 0.40 in (10.2 mm)
• Header / Footer Distance: 0.25 in (6.35 mm) from the page edge, so header/footer content sits inside the 0.40 in text margin.
• Bleed: 0.125 in (3.175 mm) where full-bleed graphics are present; 0.00 in for standard text pages. Bleed is added to the margins above (the text block stays on the trim area).

2.2 Style System (WA Family)

The output document defines and applies the following named styles. All values below are the authoritative definition; content is assigned by style reference, and paragraph-level direct formatting must not override these properties (the only exception is the Table of Contents tab stop, whose position depends on the final text width, section 2.1).

Property	WA Chapter	WA Section	WA NChp Pgr	WA Nrml Pgr	WA Thkng
Style type	Paragraph	Paragraph	Paragraph	Paragraph	Character
Based on	Heading 1	Normal	Normal	Normal	WA Nrml Pgr
Followed by (next style)	WA NChp Pgr	WA NChp Pgr	WA Nrml Pgr	WA Nrml Pgr	n/a (character style)
Outline level	1 (Heading 1)	Body	Body	Body	n/a
Font	Caladea	Caladea	Caladea	Caladea	Caladea
Font size	18 pt	16 pt	11 pt	11 pt	11 pt
Bold	No	No	No	No	No
Italic	No	No	No	No	Yes
Underline	No	No	No	No	No
Font color	Automatic (black)	Automatic	Automatic	Automatic	Automatic
Alignment	Centered	Centered	Justified	Justified	n/a
Special indentation	None	None	None	First line 0.2 in	n/a
Paragraph indent (left/right)	0	0	0	0	n/a
Spacing before	0 pt	6 pt	0 pt	0 pt	n/a
Spacing after	0 pt	12 pt	0 pt	0 pt	n/a
Line spacing	Multiple 4	Multiple 1.15	Exactly 15 pt	Exactly 15 pt	n/a
Keep with next	Yes	No	No	No	n/a
Keep lines together	Yes	Yes	Yes	Yes	n/a
Widow/orphan control	Yes	Yes	Yes	Yes	n/a
Language	en-US	en-US	en-US	en-US	en-US

WA Section is reserved for the scene-break marker <<<>>> (section 5.1.2); it is not used for section titles.

Style-to-content mapping:

Content	Style
Chapter title	WA Chapter
Scene break <<<>>> (and its *** fallback / ornament)	WA Section
First paragraph of a chapter (no first-line indent)	WA NChp Pgr
All subsequent body paragraphs	WA Nrml Pgr
Inline italic emphasis	WA Thkng
Front matter prose (Foreword, Acknowledgments)	WA Nrml Pgr
Table of Contents entries	WA TOC: Caladea 11 pt, left, exactly 15 pt, 0/0 spacing, right dot-leader tab at the text edge (position applied per paragraph, final text width)

2.3 Pagination & Section Rules

1. Recto / Verso Enforcements:
   • Recto (Right Hand Page): Always odd-numbered. Major sections (Title Page, Chapter 1, Key Back Matter sections) must begin on a Recto page. If necessary, insert an explicitly blank page before them.
   • Verso (Left Hand Page): Always even-numbered.
2. Page Numbering Schemes:
   • Front Matter: Lowercase Roman numerals (i, ii, iii, iv...). Numbering begins implicitly on the Title Page but is suppressed/hidden on display pages (Title, Copyright, Dedication).
   • Body Matter: Arabic numerals (1, 2, 3...). Restarts at 1 on Page 1 of Chapter 1.
   • Back Matter: Continues Arabic numerals from the Body Matter sequentially.

---

3. Structural Breakdown & Processing Rules

3.1 Front Matter Sequence

Front Matter sections must be recognized, categorized, and formatted according to the following canonical order:

Order	Section Name	Pagination Style	Display Number?	Page Placement	Header/Footer
1	Half Title Page	Roman (i)	Hidden	Recto	Suppressed
2	Blank / Ad Card	Roman (ii)	Hidden	Verso	Suppressed
3	Title Page	Roman (iii)	Hidden	Recto	Suppressed
4	Copyright Page	Roman (iv)	Hidden	Verso	Suppressed
5	Dedication	Roman (v)	Hidden	Recto	Suppressed
6	Epigraph	Roman (vi)	Hidden	Recto / Verso	Suppressed
7	Table of Contents	Roman	Visible	Recto	Standard Front
8	Foreword / Preface	Roman	Visible	Recto	Standard Front
9	Acknowledgments	Roman	Visible	Recto	Standard Front

Section Specific Rules:

• Copyright Page: Formatted in small point size (8\text{pt} - 9.5\text{pt}), aligned flush-left or centered at the bottom of the Verso page preceding Chapter 1 or TOC.
• Table of Contents (TOC): Auto-generated or normalized from .docx Heading styles. Dot leaders (\dots) right-aligning to page numbers. Suppresses page numbers for unnumbered front/back matter items if required.

---

3.2 Body Matter Engine

• Chapter Opening Pages:
  • Must start on a Recto page.
  • Top drop (sinkage): Heading starts 1.5" - 2.0" below the top margin.
  • Running headers and footers are suppressed on the first page of every chapter.
• Paragraph Formatting (styles per section 2.2 — no direct paragraph formatting):
  • First Paragraph of Chapter/Section: Style WA NChp Pgr — no first-line indent (0.0 in). Normal capitalization of first word only.
  • Subsequent Paragraphs: Style WA Nrml Pgr — first-line indent of 0.2" (14.4\text{pt}). No extra space between paragraphs (space_after = 0pt, space_before = 0pt).
  • Typography: Caladea 11\text{pt}, line spacing exactly 15\text{pt}.
  • Text Alignment: Fully justified.
  • Automatic hyphenation is disabled document-wide.

---

3.3 Back Matter Sequence

Back Matter elements immediately follow the final chapter:

Order	Section Name	Pagination Style	Display Number?	Page Placement	Header/Footer
1	Appendix / Appendices	Arabic (Continued)	Visible	Recto	Standard Body
2	Endnotes / Notes	Arabic (Continued)	Visible	Recto	Standard Body
3	Glossary	Arabic (Continued)	Visible	Recto	Standard Body
4	Bibliography / Ref	Arabic (Continued)	Visible	Recto	Standard Body
5	Index	Arabic (Continued)	Visible	Recto	Two-Column Grid
6	About the Author	Arabic (Continued)	Visible	Recto	Suppressed/Standard

Section Specific Rules:

• Index: Automatically parsed into 2-column layout with hanging indents (0.15\text{ in}) and smaller font size (8.5\text{pt} - 9.5\text{pt}).
• About the Author: May include an embedded headshot or icon image subject to section 5 rules.

---

4. Header & Footer Specifications

4.1 Running Headers (Body Text)

• Left Page (Verso): [ Author Name ] \quad [ Book Title ]
• Right Page (Recto): [ Chapter Title or Section Title ] \quad
• Font: Caladea, 10\text{pt}, ALL CAPS.

4.2 Running Footers

• Bottom pagination is preferred:
  • Verso Page Number: Bottom-center.
  • Recto Page Number: Bottom-center.
• Font: Caladea, 11\text{pt}.

4.3 Suppression Matrix

Headers and footers must be completely hidden on:

1. All Front Matter pages before TOC.
2. The first page of any major Section/Chapter.
3. Completely blank pages inserted to maintain Recto orientation.

---

5. Graphic Icons & Inline Image Rules

Embedded icons and decorative elements (e.g., scene break ornaments, section header icons) are processed via strict anchoring rules:

5.1 Inline Graphic Categories

1. Chapter Header Icons: Positioned directly above or alongside Heading 1 text. Must be anchored relative to the heading block with fixed aspect ratio (100\% scale lock).
2. Scene Break Ornaments ''<<<>>>'': Style WA Section (section 2.2) — Caladea 16\text{pt}, centered, line spacing Multiple 1.15, 6\text{pt} before, 12\text{pt} after, keep lines together on, keep with next off, so the break shows clear separation without being dragged to the next page.
3. Margin / Decorative Icons:
   • Absolute positioning relative to column or page margin edge.
   • Fallback rule: If a margin icon falls within 0.5\text{ in} of a page boundary overflow, auto-align it inline or remove it via configuration flag --strip-problematic-graphics.

5.2 Graphic Fallback Processing

If a embedded image/icon in the Word file is corrupt, incorrectly formatted, or exceeds printable margin bounds:

• Option A (Default): Re-anchor to the nearest text flow line as a inline block.
• Option B (--strip-graphics flag): Automatically strip non-essential decorative images while preserving structural content and replacing scene breaks with standard asterisks (***).

---

6. Internationalization & Multilingual Support (i18n)

To support non-English target languages (e.g., Spanish, German, CJK, Arabic):

1. Font Fallback & Glyph Coverage:
   • Dynamic font embedding for localized glyph sets (e.g., Noto Serif / Sans families).
   • Primary font is Caladea, fallback is Cambria
   • Automatic hyphenation is disabled document-wide (section 3.2); where a language build re-enables it, dictionary selection follows document language tags (xml:lang).
2. Right-to-Left (RTL) Layout Engines (e.g., Arabic, Hebrew):
   • Reverse Recto/Verso bindings (Recto becomes left page for opening books in RTL bindings).
   • Mirror gutter and outside margins accordingly.
   • Align page numbers and running header positions to RTL standards.
3. Localized Front/Back Matter Titles:
   • Dynamic translation keys for auto-generated headings (e.g., "Table of Contents" \rightarrow "Índice" / "Inhaltsverzeichnis").

---

7. Implementation Checklist & Engine Architecture

[ .DOCX Source Manuscript ]
         │
         ▼
[ Structure Parsing & Tagging Engine ]
  ├── Identify Front / Body / Back Matter
  ├── Map Style Headers (H1, H2, H3, Body)
  └── Extract Images & Anchor Points
         │
         ▼
[ Layout Transformer & Pagination Builder ]
  ├── Enforce Recto / Verso Page Assignments
  ├── Apply Margins, Gutters, and Bleed Settings
  │     └── Resolve dynamic gutter to fixed point (render → page count → rebuild)
  ├── Build Running Headers & Suppressions
  └── Resolve Graphic Positions / Stripping Logic
         │
         ▼
[ PDF/X Render Pipeline ]
  ├── Font Embedding (Subsetted TrueType/OpenType)
  ├── Output Intent: PDF/X-1a:2001 or PDF/X-4 (CMYK)
  └── [ Print-Ready Output PDF File ]

Key Validation Checks Prior to Output Build:

• No orphan headings (keep_with_next enforced).
• No single-line widows/orphans in body text.
• All front matter pages properly use Roman numerals; body restarts at Arabic 1.
• Page count is a multiple of 4 (or padded with clean blank pages at the back).
• Color profile converted to CMYK / Grayscale (300 DPI for graphics).