Repository Public
1// ORIX Docs2// File: Packages/ORIXDocsKit/Sources/DocFormats/ExportSupport.swift3// Description: What the exporters share: export options, resolution of tracked changes, the feature scan behind the loss reports4// (preflight and export warnings come from the same table), resolved text of fields / cross-references / citations.5//6// Author: Simon-Pierre Boucher7// Contact: contact@spboucher.ai8import Foundation9import DocModel10import DocContainer1112public struct ExportOptions: Sendable {13 /// Renders citations and the bibliography. Without it citations are written as pandoc keys (`[@key]`).14 public var citations: (any CitationFormatting)?15 /// Converts LaTeX (source, display) to MathML markup for HTML export. Without it equations are written as LaTeX text.16 public var mathML: (@Sendable (String, Bool) -> String?)?17 /// true: export the document as if every tracked change were accepted. false: as if every change were rejected.18 public var acceptChanges: Bool19 /// Markdown only: returns the path to write for an image (the caller saves the file). nil: images are embedded as data URIs.20 public var imagePath: (@Sendable (Asset) -> String?)?21 public init() { citations = nil; mathML = nil; acceptChanges = true; imagePath = nil }22}2324// MARK: - Tracked changes2526enum ChangeResolver {27 static func hasChanges(_ doc: DocumentModel) -> Bool {28 var found = false29 doc.forEachParagraphEverywhere { p, _, _ in if p.hasTrackedChanges { found = true } }30 if !found { found = doc.notes.values.contains { $0.paragraphs.contains(where: \.hasTrackedChanges) } }31 return found32 }3334 /// The document with every tracked change accepted (or rejected) and no revision mark left.35 static func resolved(_ doc: DocumentModel, accept: Bool) -> DocumentModel {36 guard hasChanges(doc) else { return doc }37 var out = doc38 out.body = resolve(doc.body, accept: accept)39 for (id, note) in doc.notes {40 var n = note41 n.paragraphs = resolve(note.paragraphs.map(Block.paragraph), accept: accept).compactMap(\.paragraph)42 if n.paragraphs.isEmpty { n.paragraphs = [Paragraph(style: StyleID.footnoteText)] }43 out.notes[id] = n44 }45 return out46 }4748 private static func resolve(_ p: Paragraph, accept: Bool) -> (paragraph: Paragraph, joinsNext: Bool) {49 var q = p50 q.runs = p.runs.compactMap { run -> Run? in51 var r = run52 if let rev = r.revision {53 if (rev.kind == .deletion) == accept { return nil }54 r.revision = nil55 }56 if let f = r.formatRevision {57 if !accept { r.props = f.previous; r.charStyle = f.previousCharStyle }58 r.formatRevision = nil59 }60 return r61 }62 var joins = false63 if let mark = p.markRevision { joins = (mark.kind == .deletion) == accept }64 q.markRevision = nil65 q.normalize()66 return (q, joins)67 }6869 private static func resolve(_ blocks: [Block], accept: Bool) -> [Block] {70 var out: [Block] = []71 var pending: Paragraph? // a paragraph whose mark disappears: the next paragraph is appended to it72 for block in blocks {73 switch block {74 case .paragraph(let p):75 let (q, joins) = resolve(p, accept: accept)76 var current = q77 if var head = pending { head.runs += q.runs; head.normalize(); current = head; pending = nil }78 if joins { pending = current } else { out.append(.paragraph(current)) }79 case .table(var t):80 if let head = pending { out.append(.paragraph(head)); pending = nil }81 for r in t.rows.indices {82 for c in t.rows[r].cells.indices {83 let cell = resolve(t.rows[r].cells[c].paragraphs.map(Block.paragraph), accept: accept).compactMap(\.paragraph)84 t.rows[r].cells[c].paragraphs = cell.isEmpty ? [Paragraph(style: StyleID.tableText)] : cell85 }86 }87 out.append(.table(t))88 default:89 if let head = pending { out.append(.paragraph(head)); pending = nil }90 out.append(block)91 }92 }93 if let head = pending { out.append(.paragraph(head)) }94 return out95 }96}9798// MARK: - Feature scan and loss reports99100/// Counts the features of a document that some export format cannot carry.101struct FeatureScan {102 var comments = 0, trackedChanges = 0, equations = 0, footnotes = 0, endnotes = 0, images = 0, floatingObjects = 0, shapes = 0103 var tables = 0, mergedCells = 0, cellFormatting = 0, citations = 0, crossRefs = 0, pageFields = 0, otherFields = 0, bookmarks = 0104 var listParagraphs = 0, headings = 0, links = 0105 var headersFooters = false, sections = 0, pageBreaks = 0, multiColumn = false, pageDecor = false106 var tocBlocks = 0, bibliographyBlocks = 0107 var fonts = 0, colours = 0, underline = 0, highlights = 0, charEffects = 0, paragraphFormatting = 0, customStyles = 0108 var preservedParts = 0, codeBlocks = 0, emphasis = 0109110 init(_ doc: DocumentModel) {111 comments = doc.comments.count112 preservedParts = doc.preservedParts.count113 let builtIn = Set(StyleSheet.standard().styles.map(\.id))114 func visit(_ p: Paragraph, inTable: Bool = false) {115 if p.markRevision != nil { trackedChanges += 1 }116 if p.list != nil { listParagraphs += 1 }117 if ModelIdiom.headingLevel(p, styles: doc.styles) != nil { headings += 1 }118 if p.style == StyleID.code { codeBlocks += 1 }119 if !builtIn.contains(p.style) { customStyles += 1 }120 var direct = p.props121 direct.outlineLevel = nil122 if ModelIdiom.isRule(p) { direct.borderBottom = nil }123 // Column alignment, list continuation indents and nested-quote indents are structure, not formatting.124 if inTable { direct.alignment = nil }125 if p.style == StyleID.listParagraph || p.style == StyleID.quote { direct.indentLeft = nil }126 if !direct.isEmpty { paragraphFormatting += 1 }127 for r in p.runs {128 if r.revision != nil || r.formatRevision != nil { trackedChanges += 1 }129 let c = r.props130 if c.fontFamily != nil || c.fontSize != nil { fonts += 1 }131 if c.color != nil { colours += 1 }132 if c.highlight != nil { highlights += 1 }133 if c.underline == true { underline += 1 }134 if c.bold == true || c.italic == true || c.strikethrough == true { emphasis += 1 }135 if c.link != nil { links += 1 }136 if c.smallCaps == true || c.allCaps == true || c.tracking != nil || c.baselineShift != nil { charEffects += 1 }137 guard let inline = r.inline else { continue }138 switch inline {139 case .image(let i): images += 1; if i.placement.isFloating { floatingObjects += 1 }140 case .shape(let s): shapes += 1; if s.placement.isFloating { floatingObjects += 1 }141 case .equation: equations += 1142 case .note(let n): if n.kind == .footnote { footnotes += 1 } else { endnotes += 1 }143 case .citation: citations += 1144 case .crossRef: crossRefs += 1145 case .field(let f):146 switch f {147 case .pageNumber, .pageCount, .headingText: pageFields += 1148 default: otherFields += 1149 }150 case .bookmark: bookmarks += 1151 }152 }153 }154 func decor(_ s: PageSetup) {155 if !s.header.isEmpty || !s.footer.isEmpty { headersFooters = true }156 if s.columns > 1 { multiColumn = true }157 if s.border != nil || s.background != nil || s.watermark != nil { pageDecor = true }158 }159 decor(doc.pageSetup)160 for block in doc.body {161 switch block {162 case .paragraph(let p): visit(p)163 case .table(let t):164 tables += 1165 for row in t.rows {166 for cell in row.cells {167 if cell.colSpan > 1 || cell.vMerge != .none { mergedCells += 1 }168 if cell.shading != nil || cell.borderTop != nil || cell.borderBottom != nil || cell.borderLeft != nil || cell.borderRight != nil || cell.formula != nil { cellFormatting += 1 }169 cell.paragraphs.forEach { visit($0, inTable: true) }170 }171 }172 case .pageBreak: pageBreaks += 1173 case .sectionBreak(let s): sections += 1; decor(s.setup)174 case .toc: tocBlocks += 1175 case .bibliography: bibliographyBlocks += 1176 }177 }178 for note in doc.notes.values { note.paragraphs.forEach { visit($0) } }179 }180}181182enum LossReport {183 /// What exporting to `format` loses, derived from the document's content only (nothing is exported).184 static func warnings(for doc: DocumentModel, format: DocFormat, options: ExportOptions) -> [FormatWarning] {185 let s = FeatureScan(doc)186 var w = WarningCollector()187 func add(_ severity: FormatWarning.Severity, _ feature: String, _ detail: String, when count: Int) {188 guard count > 0 else { return }189 w.add(severity, feature, count > 1 ? "\(detail) (\(count) occurrences)" : detail)190 }191 func flag(_ severity: FormatWarning.Severity, _ feature: String, _ detail: String, when condition: Bool) {192 if condition { w.add(severity, feature, detail) }193 }194 let name = format.displayName195 switch format {196 case .orixdoc:197 return []198 case .docx:199 return [FormatWarning(.info, feature: "DOCX", detail: "DOCX export is handled by the DocDOCX module; its losses are reported there.")]200 case .pdf:201 return [FormatWarning(.info, feature: "PDF", detail: "PDF export is produced by the layout engine; this module only imports PDF text.")]202 case .markdown, .html, .rtf, .txt:203 break204 }205 // Common to every lossy format.206 add(.approximated, "Tracked changes", "Tracked changes are not kept; the document is written with every change \(options.acceptChanges ? "accepted" : "rejected")", when: s.trackedChanges)207 add(.dropped, "Comments", "Comments cannot be stored in \(name)", when: s.comments)208 flag(.dropped, "Headers and footers", "Headers and footers cannot be stored in \(name).", when: s.headersFooters)209 add(.dropped, "Sections", "Section breaks and their page setup are not kept", when: s.sections)210 flag(.dropped, "Columns", "Multi-column layout is not kept.", when: s.multiColumn)211 flag(.dropped, "Page decoration", "Page borders, backgrounds and watermarks are not kept.", when: s.pageDecor)212 add(.dropped, "Shapes", "Shapes are not kept; only their text is written", when: s.shapes)213 add(.dropped, "Page-dependent fields", "Page numbers, page counts and running headings are left empty", when: s.pageFields)214 add(.approximated, "Fields", "Fields (title, author, date, caption numbers) are written as their current text", when: s.otherFields)215 add(.approximated, "Cross-references", "Cross-references are written as their current text", when: s.crossRefs)216 add(.dropped, "Preserved DOCX content", "Uninterpreted parts kept from an imported DOCX are only stored in .orixdoc and .docx", when: s.preservedParts)217 if options.citations == nil {218 add(.approximated, "Citations", "No citation formatter was supplied: citations are written as keys ([@key])", when: s.citations)219 add(.approximated, "Bibliography", "No citation formatter was supplied: the bibliography is not rendered", when: s.bibliographyBlocks)220 } else {221 add(.approximated, "Citations", "Citations and the bibliography are written as formatted text", when: s.citations + s.bibliographyBlocks)222 }223 switch format {224 case .markdown:225 w.add(.info, "Page setup", "Paper size, margins and orientation are not stored in Markdown.")226 add(.dropped, "Fonts", "Font families and sizes cannot be expressed in Markdown", when: s.fonts)227 add(.dropped, "Colours", "Text colours cannot be expressed in Markdown", when: s.colours)228 add(.approximated, "Highlight", "Highlights are written as <mark>; the colour is not kept", when: s.highlights)229 add(.approximated, "Underline", "Underline is written as inline HTML (<u>)", when: s.underline)230 add(.dropped, "Character effects", "Small caps, all caps, tracking and baseline shifts are not kept", when: s.charEffects)231 add(.dropped, "Paragraph formatting", "Alignment, indents, spacing, tabs and borders are not kept", when: s.paragraphFormatting)232 add(.dropped, "Custom styles", "Paragraphs with custom styles are written as plain paragraphs", when: s.customStyles)233 add(.dropped, "Page breaks", "Page breaks are not kept", when: s.pageBreaks)234 add(.approximated, "Floating objects", "Floating images are written inline", when: s.floatingObjects)235 add(.approximated, "Image sizes", "Markdown has no image size: images come back at their natural size", when: s.images)236 add(.approximated, "Merged table cells", "Merged cells are written as separate cells", when: s.mergedCells)237 add(.dropped, "Table formatting", "Cell shading, borders and formulas are not kept", when: s.cellFormatting)238 add(.approximated, "Endnotes", "Endnotes are written as footnotes", when: s.endnotes)239 add(.approximated, "Generated lists", "Tables of contents and lists of figures are written as static lists", when: s.tocBlocks)240 case .html:241 w.add(.info, "Page setup", "Paper size, margins and orientation are not stored in HTML.")242 add(.approximated, "Page breaks", "Page breaks are written as CSS print breaks", when: s.pageBreaks)243 add(.approximated, "Floating objects", "Floating objects are written with CSS floats", when: s.floatingObjects)244 add(.dropped, "Character effects", "Tracking and baseline shifts are not kept", when: s.charEffects)245 add(.dropped, "Table formulas and borders", "Cell borders and formulas are not kept", when: s.cellFormatting)246 if options.mathML == nil {247 add(.approximated, "Equations", "No MathML converter was supplied: equations are written as LaTeX source", when: s.equations)248 }249 case .rtf:250 w.add(.info, "Styles", "Named styles are flattened to direct formatting in RTF.")251 add(.approximated, "Equations", "Equations are written as their LaTeX source", when: s.equations)252 add(.approximated, "Footnotes and endnotes", "Notes are appended at the end of the document", when: s.footnotes + s.endnotes)253 add(.approximated, "Floating objects", "Floating images are written inline", when: s.floatingObjects)254 add(.approximated, "Generated lists", "Tables of contents and lists of figures are written as static text", when: s.tocBlocks)255 add(.dropped, "Table formatting", "Cell borders and formulas are not kept", when: s.cellFormatting)256 add(.dropped, "Bookmarks", "Bookmarks are not kept", when: s.bookmarks)257 case .txt:258 flag(.dropped, "Formatting", "Fonts, colours, styles and paragraph formatting are not kept in plain text.",259 when: s.fonts + s.colours + s.emphasis + s.underline + s.highlights + s.paragraphFormatting + s.headings + s.customStyles + s.codeBlocks > 0)260 add(.dropped, "Images", "Images are replaced by their alternative text", when: s.images)261 add(.dropped, "Links", "Link targets are not kept", when: s.links)262 add(.approximated, "Tables", "Tables are written as tab-separated lines", when: s.tables)263 add(.approximated, "Equations", "Equations are written as their LaTeX source", when: s.equations)264 add(.approximated, "Footnotes and endnotes", "Notes are appended at the end of the text", when: s.footnotes + s.endnotes)265 add(.approximated, "Generated lists", "Tables of contents and lists of figures are written as static text", when: s.tocBlocks)266 default: break267 }268 return w.warnings269 }270}271272// MARK: - Citations in pandoc syntax273274enum CitationSyntax {275 private static func isKeyStart(_ u: Unicode.Scalar) -> Bool { u.properties.isAlphabetic || ("0"..."9").contains(Character(u)) || u == "_" }276 private static func isKeyInner(_ u: Unicode.Scalar) -> Bool { ":.#$%&-+?<>~/".unicodeScalars.contains(u) }277278 /// "[see @smith2020, p. 4; -@doe]" without the brackets.279 static func render(_ c: Citation) -> String {280 c.items.map { item in281 var s = ""282 if let p = item.prefix, !p.isEmpty { s += p + " " }283 s += (item.suppressAuthor ? "-@" : "@") + item.key284 if let l = item.locator, !l.isEmpty { s += ", " + l }285 if let x = item.suffix, !x.isEmpty { s += (item.locator?.isEmpty ?? true ? ", " : " ") + x }286 return s287 }.joined(separator: "; ")288 }289290 /// Parses the inside of a bracketed pandoc citation. nil when some item has no `@key`.291 static func parse(_ inner: String) -> Citation? {292 var items: [CitationItem] = []293 for part in inner.split(separator: ";", omittingEmptySubsequences: false) {294 let u = Array(part.unicodeScalars)295 var at = -1296 var i = 0297 while i < u.count {298 if u[i] == "@", i + 1 < u.count, isKeyStart(u[i + 1]), i == 0 || u[i - 1] == " " || u[i - 1] == "-" || u[i - 1] == "\u{A0}" { at = i; break }299 i += 1300 }301 guard at >= 0 else { return nil }302 var end = at + 1303 while end < u.count, isKeyStart(u[end]) || (isKeyInner(u[end]) && end + 1 < u.count && (isKeyStart(u[end + 1]) || isKeyInner(u[end + 1]))) { end += 1 }304 let key = String(String.UnicodeScalarView(u[(at + 1)..<end]))305 var suppress = false306 var prefixEnd = at307 if at > 0, u[at - 1] == "-" { suppress = true; prefixEnd = at - 1 }308 let prefix = String(String.UnicodeScalarView(u[..<prefixEnd])).trimmingCharacters(in: .whitespaces)309 var rest = String(String.UnicodeScalarView(u[end...])).trimmingCharacters(in: .whitespaces)310 if rest.hasPrefix(",") { rest = String(rest.dropFirst()).trimmingCharacters(in: .whitespaces) }311 var item = CitationItem(key: key, suppressAuthor: suppress)312 if !prefix.isEmpty { item.prefix = prefix }313 if !rest.isEmpty {314 let lower = rest.lowercased()315 let terms = ["p.", "pp.", "page", "pages", "chap.", "ch.", "chapter", "sec.", "section", "§", "vol.", "fig.", "figure", "no.", "para.", "¶", "l.", "ll.", "n.", "nn."]316 if terms.contains(where: { lower.hasPrefix($0) }) || (rest.first?.isNumber ?? false) { item.locator = rest } else { item.suffix = rest }317 }318 items.append(item)319 }320 return items.isEmpty ? nil : Citation(items: items)321 }322}323324// MARK: - Export context325326/// Everything an exporter needs about one document: the change-resolved model, its numbering and the text of generated content.327struct ExportContext {328 let doc: DocumentModel329 let numbering: Numbering330 let options: ExportOptions331 var warnings = WarningCollector()332333 init(_ source: DocumentModel, options: ExportOptions) {334 doc = ChangeResolver.resolved(source, accept: options.acceptChanges)335 numbering = Numbering(doc)336 self.options = options337 }338339 func citationText(_ c: Citation) -> String {340 if let f = options.citations { return f.citationText(c, document: doc, numbering: numbering) }341 return "[" + CitationSyntax.render(c) + "]"342 }343344 /// Text of a field inside `p`. `sequenceIndex` counts the sequence fields already met in the paragraph.345 func fieldText(_ field: Field, in p: Paragraph, sequenceIndex: inout Int) -> String {346 switch field {347 case .sequence:348 let values = numbering.sequences[p.id] ?? []349 defer { sequenceIndex += 1 }350 return sequenceIndex < values.count ? String(values[sequenceIndex]) : "?"351 default:352 return numbering.staticFieldText(field, document: doc) ?? ""353 }354 }355356 func crossRefText(_ ref: CrossRef) -> String { numbering.crossRefText(ref, pageOf: { _ in nil }) }357358 /// Id of the paragraph a cross-reference points to.359 func crossRefTarget(_ ref: CrossRef) -> String? {360 let target = numbering.bookmarks[ref.target] ?? ref.target361 return numbering.targetExists(target) ? target : nil362 }363364 func headingNumberPrefix(_ p: Paragraph) -> String { numbering.headingNumbers[p.id].map { $0 + " " } ?? "" }365366 func noteMark(_ ref: NoteRef) -> String { numbering.noteMark(ref) }367368 /// Notes in reference order: footnotes first, then endnotes.369 var orderedNotes: [(ref: NoteRef, note: Note)] {370 numbering.footnoteOrder.compactMap { id in doc.notes[id].map { (NoteRef(kind: .footnote, id: id), $0) } }371 + numbering.endnoteOrder.compactMap { id in doc.notes[id].map { (NoteRef(kind: .endnote, id: id), $0) } }372 }373374 /// Entries of a generated list: (level, text, target paragraph id).375 func entries(of toc: TOCBlock) -> [(level: Int, text: String, target: String)] {376 switch toc.kind {377 case .contents:378 return numbering.outline.filter { $0.level <= toc.maxLevel }.map { ($0.level, ($0.number.map { $0 + " " } ?? "") + $0.text, $0.id) }379 case .figures, .tables:380 let label = toc.kind == .figures ? "Figure" : "Table"381 return numbering.captions.filter { $0.value.label == label }.sorted { $0.value.number < $1.value.number }.map { (1, $0.value.text, $0.key) }382 }383 }384385 /// Formatted bibliography entries, nil when no formatter was supplied.386 func bibliographyParagraphs() -> [Paragraph]? {387 options.citations?.bibliographyParagraphs(document: doc, numbering: numbering)388 }389390 /// Plain text of a paragraph with every inline object replaced by text (used for alt text, plain text, slugs).391 func flatText(_ p: Paragraph, noteMarks: Bool = false) -> String {392 var out = ""393 var seq = 0394 for r in p.runs {395 guard let inline = r.inline else { out += r.text; continue }396 switch inline {397 case .image(let i): if !i.altText.isEmpty { out += "[\(i.altText)]" }398 case .shape(let s): out += s.text399 case .equation(let e): out += e.latex400 case .note(let n): if noteMarks { out += "[\(noteMark(n))]" }401 case .citation(let c): out += citationText(c)402 case .crossRef(let ref): out += crossRefText(ref)403 case .field(let f): out += fieldText(f, in: p, sequenceIndex: &seq)404 case .bookmark: break405 }406 }407 return out408 }409410 /// Static loss report merged with what the exporter noticed while writing.411 func finalWarnings(source: DocumentModel, format: DocFormat) -> [FormatWarning] {412 var all = LossReport.warnings(for: source, format: format, options: options)413 for w in warnings.warnings where !all.contains(where: { $0.id == w.id }) { all.append(w) }414 return all415 }416}417