From 3ca668e96ebec490ad976dbc0aa23f24a4854645 Mon Sep 17 00:00:00 2001 From: aiongg <67543387+aiongg@users.noreply.github.com> Date: Tue, 6 Oct 2026 23:03:09 +0000 Subject: [PATCH] feat: convert text variables and their instances Read text variable definitions (class 0xCAB4) into designmap TextVariable elements with their settings, and write instances (class 0xCA64) as TextVariableInstance elements in place of U+0018. Evidence and the settings left out are in docs/format/text-variables.md. --- docs/format/objects.md | 2 + docs/format/text-variables.md | 121 ++++++++++++++++++++++++++ src/idml/mod.rs | 155 +++++++++++++++++++++++++++++++-- src/model/mod.rs | 21 +++-- src/model/variable.rs | 159 ++++++++++++++++++++++++++++++++++ 5 files changed, 448 insertions(+), 10 deletions(-) create mode 100644 docs/format/text-variables.md create mode 100644 src/model/variable.rs diff --git a/docs/format/objects.md b/docs/format/objects.md index 4f5fe98..1ab0665 100644 --- a/docs/format/objects.md +++ b/docs/format/objects.md @@ -369,6 +369,8 @@ the text position at the start of the run. An item anchored in text has the character U+FFFC at that position and is owned through an object of class 0x262, whose chunk 0x2C8 (u32, u32, UID list) lists the anchored page item. IDML writes the page item element in place of the U+FFFC. +A text variable instance (class 0xCA64) is owned by a U+0018 at its +position; see `text-variables.md`. INDD stores a forced line break as U+000A; IDML writes it as U+2028. The last paragraph return of a story is not written to IDML. diff --git a/docs/format/text-variables.md b/docs/format/text-variables.md new file mode 100644 index 0000000..f3a214a --- /dev/null +++ b/docs/format/text-variables.md @@ -0,0 +1,121 @@ +# Text variables + +Text variable definitions are objects of class 0xCAB4. Instances placed in +text are objects of class 0xCA64, owned by a U+0018 character in the story +(`objects.md`, owned items). Implemented in `src/model/variable.rs`. + +IDML writes each definition as a `TextVariable` element in +`designmap.xml`, between the preference elements and `idPkg:Tags`, as the +schema orders them. Its `Self` is `dTextVariablen` followed by the name; +it has no UID, so definitions were paired with INDD objects by name. + +## Evidence + +All 135 corpus pairs, including those whose IDML is from an older +version. They have 1,347 IDML `TextVariable` elements. Each has exactly +one class 0xCAB4 object with the same name, and no class 0xCAB4 object +lacks an IDML element. The layout below also holds for all 2,496 class +0xCAB4 objects in the 251 distinct little-endian files. + +## Definition (chunk 0x28BD) + +| Field | Contents | +|---|---| +| u32 *n*, segments | Name: *n* UTF-16 code units as text segments (`objects.md`) | +| u32 *n*, segments | Text: the date format of date variables (below) | +| u32 | Type code | +| 20 bytes | Settings, mostly not identified (below) | + +**Type codes** (each code with its `VariableType` in every pair): + +| Code | `VariableType` | Pairs | IDML settings element | +|---|---|---|---| +| 0xCAA1 | `OutputDateType` | 135 | `DateVariablePreference` | +| 0xCAA3 | `CustomTextType` | 2 | `CustomTextVariablePreference` | +| 0xCAA6 | `FileNameType` | 135 | `FileNameVariablePreference` | +| 0xCAA8 | `LastPageNumberType` | 135 | `PageNumberVariablePreference` | +| 0xCAA9 | `ChapterNumberType` | 135 | `ChapterNumberVariablePreference` | +| 0xCAAA | `MatchParagraphStyleType` | 135 | `MatchParagraphStylePreference` | +| 0xCAAB | `ModificationDateType` | 135 | `DateVariablePreference` | +| 0xCAAC | `CreationDateType` | 135 | `DateVariablePreference` | +| 0xCAB5 | `XrefPageNumberType` | 135 | none | +| 0xCAB6 | `XrefChapterNumberType` | 135 | none | +| 0xCAC0 | `LiveCaptionType` | 130 | `CaptionMetadataVariablePreference` | + +**Name.** Equal to IDML `Name` in 1,347 of 1,347. The names of the two +cross-reference variables start with U+001B, which IDML writes as +`` inside the attribute value (270 of 270). + +**Order.** IDML lists the variables sorted by name in code point order +(135 of 135 pairs; U+001B sorts first). The UID order differs in 113. + +**Date format.** For the three date types, the text field is IDML +`Format` (405 of 405, 9 different formats such as `dd.MM.yy` and +`d MMMM yyyy, H:mm`). + +**Running header style.** For type 0xCAAA, the u32 at offset 4 of the +settings is a paragraph style UID. It differs between files, but in all +135 pairs it is the style that IDML writes as +`AppliedParagraphStyle="ParagraphStyle/$ID/NormalParagraphStyle"`. + +## Settings with one value in the corpus + +The other IDML settings have the same value in every pair: + +| Element | Attributes | +|---|---| +| all settings elements | `TextBefore=""`, `TextAfter=""` | +| `PageNumberVariablePreference` | `Format="Current"`, `Scope="SectionScope"` | +| `ChapterNumberVariablePreference` | `Format="Current"` | +| `FileNameVariablePreference` | `IncludePath="false"`, `IncludeExtension="false"` | +| `MatchParagraphStylePreference` | `SearchStrategy="FirstOnPage"`, `ChangeCase="None"`, `DeleteEndPunctuation="false"` | +| `CaptionMetadataVariablePreference` | `MetadataProviderName="$ID/#LinkInfoNameStr"` | +| `CustomTextVariablePreference` | an empty `Contents` string | + +Their INDD fields cannot be located, because nothing varies. The INDD +side has one pattern per type in all 2,496 objects of the little-endian +files (with or without IDML): + +| Types | Text field | 20 settings bytes | +|---|---|---| +| Dates | the format | u32 0 or 0xCAB3, then zeros | +| 0xCAC0 | empty | u32 0x8C64, then zeros | +| 0xCAAA | empty | u32 0, u32 style, then zeros | +| Others | empty | zeros | + +The exception is custom text variables (0xCAA3): in files without IDML, +5 of 7 have a non-empty text field (for example a person's name or a +date), probably the variable's contents, and one has 0xCAB3 in the first +u32. The two in the pairs have an empty text field and an empty +`Contents`. + +The converter writes the settings above only for a definition whose +fields match its type's pattern. Then the INDD data equals that of the +samples, so the IDML settings are taken to be equal too. For any other +definition it writes the date format and the running header style (the +proven fields) and leaves out the rest. A custom text variable with a +non-empty text field gets no `CustomTextVariablePreference`: that the +text is its contents is not proven. + +## Instances (class 0xCA64) + +| Chunk | Contents | +|---|---| +| 0x100B | u8 (1 in every sample), then the name of the variable as an in-object string | +| 0x288B | u32 UID, not used | + +IDML writes an instance as a `TextVariableInstance` element in place of +the U+0018, with `Self` the instance's UID, `Name` the variable's name and +`AssociatedTextVariable` the variable's `Self`. The pairs have 8 +instances, in four copies of one document; all 8 match on all three. +In the 251 little-endian files, all 25 instance names name a definition +of the same file. + +**Result text.** IDML `ResultText` is the text the variable displays. +The INDD does not store it: the four pairs' modification date text +(`October 31, 2023 4:06 PM`) does not occur in the INDD files, either as +single bytes or as UTF-16. The file name instances (4 of 4) show the +INDD file name without its extension, as their settings +(`IncludePath="false"`, `IncludeExtension="false"`) say. The converter +writes `ResultText` only for file name variables with those settings, +and leaves it out (it is optional in the schema) for all others. diff --git a/src/idml/mod.rs b/src/idml/mod.rs index d590fb3..9269778 100644 --- a/src/idml/mod.rs +++ b/src/idml/mod.rs @@ -8,8 +8,8 @@ use std::collections::BTreeMap; use crate::model::{ Attrs, Document, Graphic, GraphicKind, Guide, ItemKind, Matrix, Page, PageItem, Path, Section, - Shape, Spread, Story, Style, StyleGroup, Table, TextFramePreferences, TextRun, TextWrap, Value, - numbering, root_kind, wrap_mode, + Shape, Spread, Story, Style, StyleGroup, Table, TextFramePreferences, TextRun, TextVariable, + TextWrap, Value, numbering, root_kind, variable::Instance, wrap_mode, }; #[derive(Clone, Copy)] @@ -523,6 +523,20 @@ fn style_name(s: &Style) -> String { } /// Escape a style name for use in a `Self` reference (`:` separates groups). +/// A text variable name as IDML writes it: control characters (U+001B in +/// the built-in cross-reference variables) become ``. +fn variable_name(name: &str) -> String { + let mut out = String::with_capacity(name.len()); + for c in name.chars() { + if (c as u32) < 0x20 { + out.push_str(&format!("", c as u32)); + } else { + out.push(c); + } + } + out +} + fn self_name(name: &str) -> String { name.replace('%', "%25").replace(':', "%3a") } @@ -652,6 +666,8 @@ fn page_numbers(doc: &Document) -> Vec { struct Writer<'a> { doc: &'a Document, dom: String, + /// Document file name. + name: String, /// Names of the enclosing style groups of each style or group UID. group_path: std::collections::HashMap>, } @@ -740,6 +756,7 @@ impl Writer<'_> { "idPkg:Preferences", &[("src", "Resources/Preferences.xml".into())], ); + self.text_variables(&mut x); x.empty("idPkg:Tags", &[("src", "XML/Tags.xml".into())]); for l in doc.layers.iter().filter(|l| !l.internal) { x.empty( @@ -807,6 +824,132 @@ impl Writer<'_> { x.finish() } + /// `TextVariable` elements, sorted by name as in every corpus IDML. + /// See docs/format/text-variables.md. + fn text_variables(&self, x: &mut Xml) { + let mut vars: Vec<_> = self.doc.text_variables.iter().collect(); + vars.sort_by(|a, b| a.name.cmp(&b.name)); + for v in vars { + let name = variable_name(&v.name); + x.start("TextVariable") + .attr("Self", format!("dTextVariablen{name}")) + .attr("Name", &name); + if let Some(t) = v.type_name() { + x.attr("VariableType", t); + } + self.variable_preference(x, v); + x.end(); + } + } + + /// The settings element of a text variable. Attributes other than the + /// date format and the running header's style are not located in the + /// INDD; they are written only for variables whose unidentified fields + /// hold the values of every corpus sample, and then with the values + /// those samples have in IDML. + fn variable_preference(&self, x: &mut Xml, v: &TextVariable) { + let same = v.as_in_samples; + let text = |x: &mut Xml, name: &str| { + if same { + x.attr(name, ""); + } + }; + match v.kind { + 0xCAA1 | 0xCAAB | 0xCAAC => { + x.start("DateVariablePreference"); + text(x, "TextBefore"); + x.attr("Format", &v.text); + text(x, "TextAfter"); + x.end(); + } + 0xCAAA => { + x.start("MatchParagraphStylePreference"); + text(x, "TextBefore"); + text(x, "TextAfter"); + x.attr("AppliedParagraphStyle", self.style_ref(v.style, true)); + if same { + x.attr("SearchStrategy", "FirstOnPage") + .attr("ChangeCase", "None") + .attr("DeleteEndPunctuation", "false"); + } + x.end(); + } + _ if !same => {} + 0xCAA3 => { + x.start("CustomTextVariablePreference") + .start("Properties") + .start("Contents") + .attr("type", "string") + .end() + .end() + .end(); + } + 0xCAA6 => { + x.empty( + "FileNameVariablePreference", + &[ + ("TextBefore", String::new()), + ("IncludePath", "false".into()), + ("IncludeExtension", "false".into()), + ("TextAfter", String::new()), + ], + ); + } + 0xCAA8 => { + x.empty( + "PageNumberVariablePreference", + &[ + ("TextBefore", String::new()), + ("Format", "Current".into()), + ("TextAfter", String::new()), + ("Scope", "SectionScope".into()), + ], + ); + } + 0xCAA9 => { + x.empty( + "ChapterNumberVariablePreference", + &[ + ("TextBefore", String::new()), + ("Format", "Current".into()), + ("TextAfter", String::new()), + ], + ); + } + 0xCAC0 => { + x.empty( + "CaptionMetadataVariablePreference", + &[ + ("TextBefore", String::new()), + ("MetadataProviderName", "$ID/#LinkInfoNameStr".into()), + ("TextAfter", String::new()), + ], + ); + } + _ => {} + } + } + + /// A text variable instance in place of its U+0018. + fn variable_instance(&self, x: &mut Xml, v: &Instance) { + let name = variable_name(&v.name); + x.start("TextVariableInstance") + .attr("Self", uref(Some(v.uid))) + .attr("Name", &name); + // The displayed text is not stored. A file name variable with the + // sample settings shows the document's name without extension. + let def = self.doc.text_variables.iter().find(|d| d.name == v.name); + if let Some(d) = def + && d.kind == 0xCAA6 + && d.as_in_samples + { + let stem = self.name.strip_suffix(".indd").unwrap_or(&self.name); + x.attr("ResultText", stem); + } + x.attr("AssociatedTextVariable", format!("dTextVariablen{name}")); + x.end(); + } + fn graphic(&self) -> String { let mut x = Xml::new(); self.package_root(&mut x, "Graphic"); @@ -1778,9 +1921,10 @@ impl Writer<'_> { } // Internal table markers that follow U+0016. '\u{17}' => {} - // Text variables are not converted yet; leave them out - // rather than writing a page number marker. - '\u{18}' if story.text_variables.contains(&pos) => flush(x, &mut buf), + '\u{18}' if story.text_variables.contains_key(&pos) => { + flush(x, &mut buf); + self.variable_instance(x, &story.text_variables[&pos]); + } c => buf.push(c), } pos += ch.len_utf16(); @@ -1857,6 +2001,7 @@ pub fn write(doc: &Document, name: &str, out: impl std::io::Write) -> std::io::R let w = Writer { doc, dom: format!("{}.0", doc.version.major), + name: name.to_string(), group_path: group_paths(doc), }; let mut files: BTreeMap = BTreeMap::new(); diff --git a/src/model/mod.rs b/src/model/mod.rs index f3b661b..590caa7 100644 --- a/src/model/mod.rs +++ b/src/model/mod.rs @@ -5,6 +5,7 @@ pub mod attrs; pub mod color; pub mod font; pub mod table; +pub mod variable; use std::collections::{BTreeMap, HashMap}; @@ -12,6 +13,7 @@ pub use attrs::{Attrs, Value}; pub use color::{Color, Gradient}; pub use font::{Font, FontFamily}; pub use table::{Cell, Table}; +pub use variable::TextVariable; use crate::object::{Cursor, Object}; use crate::{Database, Error, Version}; @@ -43,6 +45,7 @@ pub mod class { /// Holds an item anchored in text. pub const ANCHOR: u32 = 0x262; pub const TEXT_VARIABLE_INSTANCE: u32 = 0xCA64; + pub const TEXT_VARIABLE: u32 = 0xCAB4; pub const STYLE_ROOT_GROUP: u32 = 0xCA8C; pub const STYLE_GROUP: u32 = 0xCA8B; pub const OBJECT_STYLE: u32 = 0x1B901; @@ -334,9 +337,8 @@ pub struct Story { pub anchors: BTreeMap>, /// Tables, by UTF-16 offset of their U+0016. pub tables: BTreeMap, - /// Offsets of text variable instances (U+0018 owning a class 0xCA64 - /// object). Their displayed text is computed by InDesign and not stored. - pub text_variables: std::collections::BTreeSet, + /// Text variable instances, by UTF-16 offset of their U+0018. + pub text_variables: BTreeMap, } #[derive(Debug, Clone, Default, PartialEq)] @@ -361,6 +363,7 @@ pub struct Document { pub style_groups: BTreeMap, pub object_styles: BTreeMap, pub sections: Vec
, + pub text_variables: Vec, /// Problems that did not stop the conversion (content left out). pub warnings: Vec, pub preferences: Option, @@ -533,6 +536,7 @@ impl<'a> Reader<'a> { let mut languages = BTreeMap::new(); let mut style_groups = BTreeMap::new(); let mut object_styles = BTreeMap::new(); + let mut text_variables = Vec::new(); for &(uid, cls) in self.db.classes() { if self.db.object(uid)?.is_none() { continue; @@ -639,6 +643,11 @@ impl<'a> Reader<'a> { } } }, + class::TEXT_VARIABLE => { + if let Some(v) = TextVariable::read(uid, &*self.object(uid)?)? { + text_variables.push(v); + } + } class::LANGUAGE => { if let Some(d) = self.chunk(uid, chunk::LANGUAGE_NAME)? && d.len() > 1 @@ -669,6 +678,7 @@ impl<'a> Reader<'a> { .into_iter() .map(|uid| self.section(uid)) .collect::, _>>()?, + text_variables, warnings: self.warnings.borrow().clone(), preferences: self.document_preferences()?, }) @@ -1289,11 +1299,12 @@ impl<'a> Reader<'a> { } let mut anchors: BTreeMap> = BTreeMap::new(); let mut tables: BTreeMap = BTreeMap::new(); - let mut text_variables = std::collections::BTreeSet::new(); + let mut text_variables = BTreeMap::new(); for (pos, cls, item) in owned { match cls { class::TEXT_VARIABLE_INSTANCE => { - text_variables.insert(pos); + let v = variable::Instance::read(item, &*self.object(item)?)?; + text_variables.insert(pos, v); } class::ANCHOR => { for child in self.children(item, chunk::ANCHOR_CHILDREN)? { diff --git a/src/model/variable.rs b/src/model/variable.rs new file mode 100644 index 0000000..1ec113a --- /dev/null +++ b/src/model/variable.rs @@ -0,0 +1,159 @@ +//! Text variables: definitions (class 0xCAB4) and their instances in text +//! (class 0xCA64). See `docs/format/text-variables.md`. + +use crate::Error; +use crate::object::{Cursor, Object}; + +pub mod chunk { + /// Definition: name, text, type and settings. + pub const DEFINITION: u32 = 0x28BD; + /// Instance: flag byte and the name of its variable. + pub const INSTANCE_NAME: u32 = 0x100B; +} + +/// Variable type codes and their IDML `VariableType`. +pub const TYPES: &[(u32, &str)] = &[ + (0xCAA1, "OutputDateType"), + (0xCAA3, "CustomTextType"), + (0xCAA6, "FileNameType"), + (0xCAA8, "LastPageNumberType"), + (0xCAA9, "ChapterNumberType"), + (0xCAAA, "MatchParagraphStyleType"), + (0xCAAB, "ModificationDateType"), + (0xCAAC, "CreationDateType"), + (0xCAB5, "XrefPageNumberType"), + (0xCAB6, "XrefChapterNumberType"), + (0xCAC0, "LiveCaptionType"), +]; + +#[derive(Debug, Clone, PartialEq)] +pub struct TextVariable { + pub uid: u32, + pub name: String, + /// Type code (see [`TYPES`]). + pub kind: u32, + /// The date format of date variables; the contents of custom text + /// variables (not proven, see the format notes). + pub text: String, + /// Paragraph style of a running header (`MatchParagraphStyleType`). + pub style: Option, + /// The fields not identified hold the values every corpus sample of + /// this type has, so the IDML settings are those of the samples. + pub as_in_samples: bool, +} + +impl TextVariable { + pub fn type_name(&self) -> Option<&'static str> { + TYPES.iter().find(|t| t.0 == self.kind).map(|t| t.1) + } + + pub fn read(uid: u32, obj: &Object) -> Result, Error> { + let Some(data) = obj.chunk(chunk::DEFINITION) else { + return Ok(None); + }; + parse(uid, data).map(Some) + } +} + +/// u32 length and text segments. +fn counted(c: &mut Cursor) -> Result { + match c.u32()? as usize { + 0 => Ok(String::new()), + n => c.segments(n), + } +} + +/// Chunk 0x28BD: name, text, u32 type, then 20 bytes. +fn parse(uid: u32, data: &[u8]) -> Result { + let mut c = Cursor::new(data); + let name = counted(&mut c)?; + let text = counted(&mut c)?; + let kind = c.u32()?; + let rest = c.bytes(c.remaining())?; + let zero = |r: &[u8]| r.iter().all(|&b| b == 0); + let mut style = None; + let as_in_samples = rest.len() == 20 + && match kind { + // Dates: the first u32 is 0 or 0xCAB3 in the samples. + 0xCAA1 | 0xCAAB | 0xCAAC => { + (zero(&rest[..4]) || rest[..4] == [0xB3, 0xCA, 0, 0]) && zero(&rest[4..]) + } + 0xCAC0 => rest[..4] == [0x64, 0x8C, 0, 0] && zero(&rest[4..]), + 0xCAAA => { + style = Some(u32::from_le_bytes(rest[4..8].try_into().unwrap())); + zero(&rest[..4]) && zero(&rest[8..]) + } + _ => zero(rest) && text.is_empty(), + }; + Ok(TextVariable { + uid, + name, + kind, + text, + style: style.filter(|&s| s != 0), + as_in_samples, + }) +} + +/// A text variable placed in text (U+0018 owning a class 0xCA64 object). +#[derive(Debug, Clone, PartialEq)] +pub struct Instance { + pub uid: u32, + /// Name of the variable it shows. + pub name: String, +} + +impl Instance { + pub fn read(uid: u32, obj: &Object) -> Result { + let name = match obj.chunk(chunk::INSTANCE_NAME) { + Some(d) if d.len() > 1 => Cursor::new(&d[1..]).string()?, + _ => String::new(), + }; + Ok(Instance { uid, name }) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn counted_text(s: &str) -> Vec { + let mut v = (s.len() as u32).to_le_bytes().to_vec(); + if !s.is_empty() { + v.extend((0x4000u16 | s.len() as u16).to_le_bytes()); + v.extend(s.as_bytes()); + } + v + } + + #[test] + fn parses_a_date_variable() { + let mut d = counted_text("Output Date"); + d.extend(counted_text("dd.MM.yy")); + d.extend(0xCAA1u32.to_le_bytes()); + d.extend([0xB3, 0xCA, 0, 0]); + d.extend([0; 16]); + let v = parse(0x84, &d).unwrap(); + assert_eq!(v.name, "Output Date"); + assert_eq!(v.text, "dd.MM.yy"); + assert_eq!(v.type_name(), Some("OutputDateType")); + assert!(v.as_in_samples); + } + + #[test] + fn reads_the_running_header_style() { + let mut d = counted_text("Running Header"); + d.extend(counted_text("")); + d.extend(0xCAAAu32.to_le_bytes()); + d.extend([0; 4]); + d.extend(0x81u32.to_le_bytes()); + d.extend([0; 12]); + let v = parse(0x89, &d).unwrap(); + assert_eq!(v.style, Some(0x81)); + assert!(v.as_in_samples); + // Another value in a field not identified. + let last = d.len() - 1; + d[last] = 1; + assert!(!parse(0x89, &d).unwrap().as_in_samples); + } +}