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 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)
• Outside Margin: 0.50 in (12.7 mm)
• Top Margin: 0.75 in (19.0 mm)
• Bottom Margin: 0.75 in (19.0 mm)
• Bleed: 0.125 in (3.175 mm) where full-bleed graphics are present; 0.00 in for standard text pages.

2.2 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:
  • First Paragraph of Chapter/Section: No first-line indent (0.0 in). Normal capitalization of first word only.
  • Subsequent Paragraphs: First-line indent of 0.18" - 0.25" (13\text{pt} - 18\text{pt}). No extra space between paragraphs (space_after = 0pt, space_before = 0pt).
  • Text Alignment: Fully justified with micro-typography hyphenation enabled.

---

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: Set in matching body font or clean sans-serif (e.g., 8.5\text{pt} - 9.5\text{pt} Small Caps or Regular with 1.5\text{pt} letter spacing).

4.2 Running Footers

• Bottom pagination is preferred:
  • Verso Page Number: Bottom-center.
  • Recto Page Number: Bottom-center.

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 ''<<<>>>'':
   • Centered horizontally between paragraphs.
   • Top/Bottom space: 12\text{pt} before, 12\text{pt} after.
   • Keep with next set to False to avoid orphaned breaks, but tied to surrounding block spacing.
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 dictionary selection based on 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
  ├── 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).