SPB Git

Repository Public

overview.md 5.0 KB

# Architecture overview

ORIX Docs is a thin SwiftUI + AppKit application on top of Packages/ORIXDocsKit, a Swift package whose targets do not import SwiftUI. Every engine can be built, tested and benchmarked from the command line without launching the app.

# Targets

Target Depends on Responsibility
DocModel Foundation The document model (value types, Codable, Sendable), styles and inheritance, numbering and cross-reference resolution, editing operations, track changes.
DocContainer DocModel Defensive ZIP reader/writer, shared import/export types (DocFormat, FormatWarning, ImportResult, ExportResult).
DocDOCX DocModel, DocContainer WordprocessingML import and export.
DocFormats DocModel, DocContainer Native .orixdoc container, Markdown, HTML, RTF, plain text, PDF text import.
DocMath DocModel, SwiftMath LaTeX math parsing and typesetting to Core Graphics.
DocReferences DocModel BibTeX / BibLaTeX, RIS and CSL-JSON parsing; citation and bibliography formatting.
DocLayout DocModel, DocMath Core Text line layout, pagination, page rendering, PDF publishing.
DocReview DocModel Document comparison (diff) and comparison reports.
DocAudit DocModel Document quality auditor and research checks.
DocTemplates DocModel The template library.
DocAutomation all of the above Workflows, batch processing, the orixdocs command-line tool.

# The document model in one page

  • A DocumentModel is a value. Undo is a stack of values; arrays are copy-on-write, so a snapshot shares storage with its successor.
  • body is a flat [Block]. A block is a paragraph, a table, a page/column break, a section break, a generated list (contents, figures, tables) or the generated bibliography.
  • Sections are Word-like: DocumentModel.pageSetup describes the first section, and each .sectionBreak block carries the PageSetup of the section it starts. Headers and footers live in PageSetup.
  • A Paragraph is a list of Runs. A run is text with optional (inheritable) CharProps, an optional character style, an optional tracked Revision, an optional FormatRevision and the ids of the comments anchored on it.
  • Inline objects (image, shape, equation, note reference, citation, cross-reference, field, bookmark) are runs whose text is U+FFFC and whose inline holds the payload. A forced line break is U+2028 in the text; a tab is \t.
  • Every text offset is a UTF-16 code unit offset, always aligned on a composed character boundary (String.composedBoundary…). Never index paragraph text with Swift Character counts or scalar counts.
  • Formatting is resolved as: document defaults → paragraph style chain (basedOn) → character style chain → direct properties. StyleSheet.paraProps / charProps return fully resolved values. Built-in style ids equal Word's (Normal, Heading1, Title, Caption, FootnoteText …), see StyleID.
  • Lists: Paragraph.list references a ListDefinition in DocumentModel.lists plus a level. Labels are computed, never stored in the text.
  • Captions are ordinary paragraphs of style Caption that contain a .field(.sequence("Figure")) inline. Display equations are paragraphs holding one .equation inline with display == true.
  • Footnotes and endnotes: a .note(NoteRef) inline in the text, content in DocumentModel.notes[id].
  • Citations: a .citation(Citation) inline referencing BibEntry.keys of DocumentModel.bibliography. Their displayed text and the bibliography are produced by a CitationFormatting implementation (DocReferences), never stored.
  • Numbering(document) computes list labels, heading numbers, sequence values, note numbers, citation order, the outline and cross-reference targets in one pass. Anything that shows a number reads it there.
  • Tables: Table.columnWidths is the grid; a TableCell covers colSpan grid columns; vertical merges use vMerge (restart / continue) exactly like WordprocessingML. Cells hold paragraphs only (no nested tables).
  • Images are stored once in DocumentModel.assets (not part of the JSON encoding) and referenced by id from ImageObject.
  • Tracked changes: an inserted run carries Revision(kind: .insertion); deleted text stays in the paragraph with Revision(kind: .deletion); Paragraph.markRevision tracks the paragraph mark. Paragraph.visibleText is the text with all changes accepted.

# Conventions

  • Swift 6 language mode, strict concurrency. Model types are Sendable values.
  • No network access anywhere in the package. No third-party dependency except SwiftMath (math typesetting).
  • Importers treat input as hostile and report everything they cannot carry over as FormatWarnings; they never drop content silently.
  • Every source file starts with the ORIX file header (project, file path, description, author, contact).
  • Tests use Swift Testing (import Testing).
Files main
Menu

Theme