# craft-idml IDML (InDesign Markup Language) packages, and InDesign Tagged Text. No `unsafe`. An IDML package is a ZIP whose first entry is an uncompressed `mimetype`, followed by `designmap.xml` (the root `Document` element, which includes the other parts) and the `Resources/`, `MasterSpreads/`, `Spreads/` and `Stories/` parts. Implemented clean-room from the public IDML File Format Specification and from inspecting IDML packages exported from synthetic documents. This crate is the layer between the bytes and IDML's own element tree, with a typed model of the layout, the stories and the resources (`model`): a caller reads it and maps it onto its own document. InCopy Markup (ICML), one story as one XML document, is read and written too (`icml`). ## Reading ```rust # fn main() -> craft_idml::Result<()> { # let bytes: Vec = Vec::new(); # if bytes.is_empty() { return Ok(()); } use craft_idml::{Local, Props}; let mut package = craft_idml::Package::open(&bytes)?; let doc = package.document()?; // designmap.xml with its includes in place for story in doc.top.iter().filter(|e| e.name == "Story") { for range in story.find_all(Local("CharacterStyleRange")) { let size = range.num("PointSize"); // attribute or child let font = range.value("AppliedFont").and_then(|f| craft_idml::value::font_family(&f)); } } for line in &doc.warnings { /* a part designmap.xml lists and the package lacks */ } # Ok(()) } ``` - `Package::part` finds a part by its exact name, then leniently: writers differ in percent-encoding, case, path separators and a leading `./` or `/`. - `Package::document` refuses a package whose `mimetype` says something else, that has no `designmap.xml`, or whose root is not `Document`. An included part that is missing is a warning; one that cannot be read is an error. - Elements are `craft_xml::El`, names as written (`idPkg:Story`), text exact. Processing instructions inside elements are kept (`` is how InDesign writes special characters). Parts are read strictly: one that is cut off is an error, not half a part. - `Props` reads a property in either spelling: an attribute, or a child of ``. ### Limits | `Limits` field | Default | Past it | |---|---|---| | `max_entries` | 100,000 | `Error::TooManyEntries` | | `max_part_bytes` | 512 MiB | `Error::TooLarge` | | `max_total_bytes` (all parts read from one package) | 2 GiB | `Error::TooLarge` | | `xml.max_depth` | 256 | `Error::Part` | | `xml.max_nodes`, `xml.max_attrs_total` (one part) | 8,000,000 and 32,000,000 | `Error::Part` | The ZIP layer is craft-zip: the declared entry count is checked before the archive is indexed, and sizes are checked against what a part really expands to, not what the archive declares. ## Writing ```rust use craft_idml::{El, part_root, part_xml, designmap_xml, write_package, prop, with_props}; let range = with_props(El::new("CharacterStyleRange").with_attr("PointSize", "9"), vec![prop("Leading", "unit", "14")]); let story = part_root("Story").with_child(El::new("Story").with_attr("Self", "u1").with_child(range)); let designmap = El::new("Document") .with_attr("xmlns:idPkg", craft_idml::PACKAGING_NS) .with_attr("DOMVersion", craft_idml::DOM_VERSION) .with_child(El::new("idPkg:Story").with_attr("src", "Stories/Story_u1.xml")); let bytes = write_package(&[ ("META-INF/container.xml", craft_idml::CONTAINER_XML.as_bytes().to_vec()), ("designmap.xml", designmap_xml(&designmap)), ("Stories/Story_u1.xml", part_xml(&story)), ])?; assert!(craft_idml::is_idml(&bytes)); # Ok::<(), craft_idml::Error>(()) ``` Parts are written with an element that has only element children one child per line, and any other element on one line, so story text is never changed by indentation. ## The layout model ```rust # fn main() -> craft_idml::Result<()> { # let bytes: Vec = Vec::new(); # if bytes.is_empty() { return Ok(()); } use craft_idml::model::{apply, spreads}; let doc = craft_idml::Package::open(&bytes)?.document()?; for spread in spreads(&doc) { for page in spread.pages() { let _bounds = page.geometric_bounds(); // top left bottom right let _parent = page.applied_master(); } for (item, to_spread) in spread.all_items() { // nested items too, with their transform let outline = item.geometry(); // subpaths of anchor and direction points if let Some([top, left, _, _]) = outline.bounds() { let _corner = apply(&to_spread, [left, top]); } for graphic in item.graphics() { let _file = graphic.link().and_then(|l| l.uri()); let _embedded = graphic.contents(); } } } # Ok(()) } ``` - `Spread` (and parent spreads, `master`), `Page`, `Guide`, `PageItem` (`ItemKind`: text frames, rectangles, ovals, polygons, lines, groups, buttons, EPS text, and other page item elements by name), `Graphic` (`GraphicKind`: images, EPS, PDF, imported pages, WMF, PICT, SVG) and `Link`. Children keep their document order: page items stack back to front. - Each node keeps its attributes and `` as written (`Values`) and reads them through accessors: `item_transform`, `geometric_bounds`, `applied_master`, `override_list`, `parent_story`, `next_text_frame`, `graphic_bounds`, `contents`, and `num`, `boolean`, `value` for any other property. Anything the model does not type is kept as XML where it stood, without the part's indentation (`tidy`). `to_el` writes a node back: what is read and written again reads the same. - `PathGeometry` (`geometry`, `set_geometry`) holds subpaths of points. A point without a usable anchor is left out, a missing direction point is the anchor, and a subpath holding `NaN` or an infinity is left out whole. At most `MAX_PATH_POINTS` (1,000,000) points are kept. - `Spread::all_items` walks nested groups without recursion, giving each item's transform into spread coordinates (`concat` of the transforms on the way). ## Stories ```rust use craft_idml::model::{Ace, TextNode, stories}; # fn main() -> Result<(), craft_xml::Error> { let part = craft_idml::parse_part(br#" Page
"#)?; let story = stories(&part.elements().cloned().collect::>()).remove(0); let body = story.paragraphs()[0]; assert_eq!(body.paragraph_style(), Some("ParagraphStyle/Body")); assert_eq!(body.characters()[0].values.num("PointSize"), Some(9.0)); assert_eq!(story.text(|a| (a == Ace::PageNumber).then_some('#')), "Page #\n"); # Ok(()) } ``` - `Story`, its `TextNode`s in document order: paragraph and character ranges (`Range`), `Content` (text, and the special characters InDesign writes as ``: `Ace`), `Br`, containers of text (`HyperlinkTextSource`, `Change`, `XMLElement`, `CrossReferenceSource`, `Footnote`, `Note`, `EndnoteRange`), `Table` (rows, columns, and `Cell`s holding text), and page items anchored in the text (the layout model's `PageItem`). - `text` gives a story's, range's, cell's or note's text: content, `\n` for each break, and a character for each special character the caller names. A footnote's, note's or table's text is its own, not the text around it; a hyperlink's or a change's is. - Content keeps its whitespace exactly; elements the model does not type are kept as written. Containers nest as deep as the XML reader allows (256), and text is gathered without recursion. ## Resources - `style_groups` gives the root style groups (`RootParagraphStyleGroup` and the character, object, cell and table ones) as trees of `StyleGroup` and `Style`, written back exactly. `StyleGroup::styles` lists every style with the names of the groups it is in; `Style` has `based_on`, `next_style` and its other children (`other`: an object style's `TextFramePreference`, its effect settings). - `swatches` gives `Color`, `Tint`, `Gradient` (with `stops`), `MixedInk`, `MixedInkGroup` and the None `Swatch`: `spot`, `space`, `color_value`, `base_color`, `tint_value`, `radial`. - `stroke_styles` (dashed with `dash_array`, dotted, striped with `stripe_array`) and `color_groups` (with `members`). - `preference` finds a preference element (`DocumentPreference`, `GridPreference`, …) and `named` every element of a name (`Ink`, `Layer`, `Section`, `Condition`, `NumberingList`). ## ICML `icml::is_icml` sniffs the `SnippetType="InCopyInterchange"` instruction in the first 4 KiB. `icml::read_icml` reads the file as a package part is read, at most `MAX_ICML_BYTES` (512 MiB); a root that is not `Document` or a file without a `Story` is refused, and a reference to a package part (an ICML file has none) is left out with a warning. `Icml::stories` gives its stories; which one to place (usually the first no text frame of the file holds) is the caller's choice. `icml::icml_xml` writes a `Document` with the two `` instructions that mark the file. ## Values `craft_idml::value`: `num` and `point_str` (numbers as IDML writes them), `nums`, `matrix`, `point`, `tint`, `escape_id` / `unescape_id` / `uid` (`Self` ids), `style_name_in` / `style_name_out` / `style_self` (style groups and built-in names), `font_family` (`AppliedFont`), `xmp_value` (dates in `META-INF/metadata.xml`), `base64_encode` / `base64_decode` (embedded `Contents`), `uri_to_path` / `path_to_uri` (link URIs). ## Tagged Text `craft_idml::tagged` reads and writes InDesign Tagged Text: plain text with `` markup. ```rust use craft_idml::tagged; let file = b"\r\n\r\nA word"; assert!(tagged::is_tagged(file)); let text = tagged::parse(file); assert_eq!(text.paragraphs[0].style, "Body"); assert_eq!(text.paragraphs[0].runs[1].format.style.as_deref(), Some("Em")); assert_eq!(tagged::parse(tagged::write(&text.paragraphs).as_bytes()).paragraphs, text.paragraphs); ``` Paragraph styles, character styles, font family, font style and size are kept; other tags are counted (`skipped_tags`) and skipped. ASCII, UTF-8 and UTF-16 (by byte-order mark) are read; ASCII is written, other characters as `<0xXXXX>` UTF-16 code units. Style and font names are cut to `MAX_NAME_CHARS` (256). Every input reads as something. ## Where it came from DesignCraft's `crates/idml` (the package reader and writer, the `` accessors, the value codecs) and `crates/textimport/src/tagged.rs`. DesignCraft's own XML tree is replaced by craft-xml.