You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The four construct inventories (ExaDev/ooxml.js#65, ExaDev/odf.js#59, ExaDev/markdown-codec#63, ExaDev/pdf-codec#66 — verdict tables in their latest comments) are complete, and their collective answer to the vocabulary question in #22 is settled enough to build: three of the four codecs need no node kind beyond the five #22 already names, and the fourth proposes exactly one. This issue adds the kinds additively on top of the 4.0.0 tree package (#23) — new descriptor kinds and package tables, no change to existing node shapes — so the per-codec reading work can start against a stable target.
The five construct kinds, confirmed by every inventory:
contentControl — a typed container of content: docx block and inline SDTs, legacy w:ffData form fields, ODF office:forms controls in ordinary odt and TOC/index wrappers as typed containers, PDF AcroForm widgets with their field tree. Contested member: xlsx data validation as a range-scoped input constraint (falls to residue if range-scoped controls are refused).
field — instruction plus cached result, extent as containment: docx w:fldChar/w:instrText and w:fldSimple, the ODF field-master families and the everyday simple-field set, ODF cross-reference displays, pptx a:fld (which confirms the kind is genuinely cross-format rather than a docx-only shape).
anchor — a named extent or reference-site marker: docx bookmarks, comment extents, footnote/endnote references, xlsx tables and defined names, ODF text:bookmark and text:reference-mark*, PDF sticky notes and markup annotations, markdown footnote markers.
link — target plus wrapped runs: reserved for block-scoped or annotated extents a flat ContentRun.hyperlink cannot express (markdown link/image titles; PDF link annotations whose rect matches no recovered run) and for internal targets (docx @w:anchor, pptx slide jumps, PDF GoTo//Dest). Run-level hyperlinks stay where they are per the standing reconciliation on Two-channel fidelity: harmonised semantic construct vocabulary plus a quarantined residue channel #22.
provenance — author/date wrappers around content: docx w:ins/w:del and move tracking, ODF text:tracked-changes/text:changed-region with its inline markers.
The marker-plus-definition split. All four inventories independently land notes, comments, and their kin on the same shape: an anchor marker at the reference site plus a definitions-table entry for the body (docx footnotes/endnotes/comments, ODF text:note and office:annotation, markdown footnotes, PDF sticky notes and markup annotations). The definitions-table facility shipped with 4.0.0, so this needs only the anchor marker kind and the tables' entry shapes.
The one proposed new generic kind: the ODF text:section nesting container (ExaDev/odf.js#59). ContentSection cannot host it — it is page geometry with one pageSize/margins pair and does not nest, while text:section nests arbitrarily and usually does not change page geometry at all (columns, protection, naming, linked external chapters via text:section-source, which the odm reader already models section-shaped). Degrading to contentControl would bury the structural meaning. Decision needed here: a first-class nesting container kind, or the documented fallback of degrade-to-contentControl-with-residue (text:name, style:name, protected flag) if a new kind is refused.
The three package-level tables pdf-codec proposes (ExaDev/pdf-codec#66), riding the same package-table mechanism as definitions and styles rather than tree nodes:
layers — PDF optional-content groups (/OCProperties plus /OC membership on BDC spans): layer definitions at package level, a layer reference on extracted items. A cross-format analogue exists (ODF Draw's layer model), which is what makes this semantic rather than residue. Today content an author hid in an OFF layer extracts as if visible.
attachments — PDF embedded files (/Names /EmbeddedFiles, /FileAttachment, /EF, /AF): a package attachment list. docx and ODF package attachments make this cross-format rather than PDF-specific.
navigation/destinations — PDF /Outlines and the /Dests//Names name tree: a navigation table plus named destinations, the resolution point both internal links and outline targets need. One names-tree walker in pdf-codec serves embedded files, destinations, and outlines together.
All three are contested in the pdf inventory — the fallback for each is residue, and #22 owns the calls. Layers and attachments also change currently-extracted output, so landing them wants fixtures with known state first.
What else the inventories collectively require, as fields rather than kinds (each rides the model that already owns it):
an internal-target vocabulary for link — anchor-name targets shared by docx @w:anchor, pptx slide jumps, and PDF GoTo//Dest, with bookmarks, xlsx tables/defined names, and PDF named destinations supplying the other ends
a chart union member on ContentEmbeddedObject (ODF office:chart, xlsx charts) — decided jointly across the ooxml and odf lanes
a checked/task field and item identity on list membership, plus a blockquote container, in the tree's list work (markdown task lists, multi-block item boundaries, blockquote nesting depth)
a language annotation on the code representation (markdown fence info strings, first word only; the remainder is residue)
ContentFormula canonical-plus-source for LaTeX (markdown math preserves source text today as the interim)
ContentSection fields for docx break type and header/footer attachment; floating-image placement on ContentImageBlock is flagged contestable rather than decided (layout-adjacent)
xlsx conditional formatting and ODF table:content-validation/calcext:conditional-format: one joint decision across the two codec issues — candidate shape is a definitions-table conditionalStyle entry, else residue
PDF /PageLabels may want a shared cross-format page-numbering decision
Gating. The per-codec implementation issues are filed and blocked on this issue landing the kinds additively (links in the comment below, and listed on the umbrella #22). A corpus gate stands before shapes freeze: several semantic candidates — notably docx SDT/field/bookmark shapes, ODF fields/notes/TOCs, and PDF AcroForm/OCG — have no real producer file in any of the repos, and each candidate should be checked against one real file of the relevant producer before the vocabulary is frozen.
The four construct inventories (ExaDev/ooxml.js#65, ExaDev/odf.js#59, ExaDev/markdown-codec#63, ExaDev/pdf-codec#66 — verdict tables in their latest comments) are complete, and their collective answer to the vocabulary question in #22 is settled enough to build: three of the four codecs need no node kind beyond the five #22 already names, and the fourth proposes exactly one. This issue adds the kinds additively on top of the 4.0.0 tree package (#23) — new descriptor kinds and package tables, no change to existing node shapes — so the per-codec reading work can start against a stable target.
The five construct kinds, confirmed by every inventory:
contentControl— a typed container of content: docx block and inline SDTs, legacyw:ffDataform fields, ODFoffice:formscontrols in ordinary odt and TOC/index wrappers as typed containers, PDF AcroForm widgets with their field tree. Contested member: xlsx data validation as a range-scoped input constraint (falls to residue if range-scoped controls are refused).field— instruction plus cached result, extent as containment: docxw:fldChar/w:instrTextandw:fldSimple, the ODF field-master families and the everyday simple-field set, ODF cross-reference displays, pptxa:fld(which confirms the kind is genuinely cross-format rather than a docx-only shape).anchor— a named extent or reference-site marker: docx bookmarks, comment extents, footnote/endnote references, xlsx tables and defined names, ODFtext:bookmarkandtext:reference-mark*, PDF sticky notes and markup annotations, markdown footnote markers.link— target plus wrapped runs: reserved for block-scoped or annotated extents a flatContentRun.hyperlinkcannot express (markdown link/image titles; PDF link annotations whose rect matches no recovered run) and for internal targets (docx@w:anchor, pptx slide jumps, PDFGoTo//Dest). Run-level hyperlinks stay where they are per the standing reconciliation on Two-channel fidelity: harmonised semantic construct vocabulary plus a quarantined residue channel #22.provenance— author/date wrappers around content: docxw:ins/w:deland move tracking, ODFtext:tracked-changes/text:changed-regionwith its inline markers.The marker-plus-definition split. All four inventories independently land notes, comments, and their kin on the same shape: an
anchormarker at the reference site plus a definitions-table entry for the body (docx footnotes/endnotes/comments, ODFtext:noteandoffice:annotation, markdown footnotes, PDF sticky notes and markup annotations). The definitions-table facility shipped with 4.0.0, so this needs only the anchor marker kind and the tables' entry shapes.The one proposed new generic kind: the ODF
text:sectionnesting container (ExaDev/odf.js#59).ContentSectioncannot host it — it is page geometry with one pageSize/margins pair and does not nest, whiletext:sectionnests arbitrarily and usually does not change page geometry at all (columns, protection, naming, linked external chapters viatext:section-source, which the odm reader already models section-shaped). Degrading tocontentControlwould bury the structural meaning. Decision needed here: a first-class nesting container kind, or the documented fallback of degrade-to-contentControl-with-residue (text:name,style:name, protected flag) if a new kind is refused.The three package-level tables pdf-codec proposes (ExaDev/pdf-codec#66), riding the same package-table mechanism as definitions and styles rather than tree nodes:
/OCPropertiesplus/OCmembership onBDCspans): layer definitions at package level, a layer reference on extracted items. A cross-format analogue exists (ODF Draw's layer model), which is what makes this semantic rather than residue. Today content an author hid in an OFF layer extracts as if visible./Names /EmbeddedFiles,/FileAttachment,/EF,/AF): a package attachment list. docx and ODF package attachments make this cross-format rather than PDF-specific./Outlinesand the/Dests//Namesname tree: a navigation table plus named destinations, the resolution point both internal links and outline targets need. One names-tree walker in pdf-codec serves embedded files, destinations, and outlines together.All three are contested in the pdf inventory — the fallback for each is residue, and #22 owns the calls. Layers and attachments also change currently-extracted output, so landing them wants fixtures with known state first.
What else the inventories collectively require, as fields rather than kinds (each rides the model that already owns it):
link— anchor-name targets shared by docx@w:anchor, pptx slide jumps, and PDFGoTo//Dest, with bookmarks, xlsx tables/defined names, and PDF named destinations supplying the other endsContentEmbeddedObject(ODFoffice:chart, xlsx charts) — decided jointly across the ooxml and odf lanesContentFormulacanonical-plus-source for LaTeX (markdown math preserves source text today as the interim)ContentSectionfields for docx break type and header/footer attachment; floating-image placement onContentImageBlockis flagged contestable rather than decided (layout-adjacent)table:content-validation/calcext:conditional-format: one joint decision across the two codec issues — candidate shape is a definitions-tableconditionalStyleentry, else residue/PageLabelsmay want a shared cross-format page-numbering decisionGating. The per-codec implementation issues are filed and blocked on this issue landing the kinds additively (links in the comment below, and listed on the umbrella #22). A corpus gate stands before shapes freeze: several semantic candidates — notably docx SDT/field/bookmark shapes, ODF fields/notes/TOCs, and PDF AcroForm/OCG — have no real producer file in any of the repos, and each candidate should be checked against one real file of the relevant producer before the vocabulary is frozen.