Files
indd-utils/CLAUDE.md
T

3.3 KiB
Raw Blame History

indd-utils

Rust reader for INDD files (Adobe InDesign's native format) and converter to IDML. Crate and command: indd. Repo: aiongg/indd-utils (private for now). Licence: MIT.

Clean-room rules (read CLEANROOM.md)

  • Never commit anything from corpus/. It holds third-party sample files without redistribution rights. Only files listed in tests/fixtures/README.md may be committed.
  • Every fact about the INDD format goes in docs/format/ with the evidence that supports it (which files, how many, what was compared). Code relies only on documented facts.
  • Do not use knowledge of InDesign internals from memory (InDesign SDK class names, IDs, persistence details). If it can't be shown from the corpus or a permitted reference in CLEANROOM.md, it doesn't go in.
  • Do not install or run InDesign, and do not ask anyone to create INDD files for this project.
  • No golden output files derived from third-party samples. Corpus tests compare against the sibling IDML at run time.
  • Do not name the third-party corpus sources in committed files. The provenance record is corpus/SOURCES.md (local).

Layout

  • src/header.rs, src/container.rs: decoded layers (see docs/format/).
  • tests/fixtures.rs: smoke tests on committed open-licensed samples.
  • tests/corpus.rs: tests over the local corpus/; they skip if absent.
  • tools/inventory.py: corpus inventory (python3 -I tools/inventory.py corpus/).
  • tools/root_values.py [--write]: root style values that every corpus IDML has; regenerates src/idml/root_values.xml (see docs/format/idml-values.md).
  • Analysis scratch scripts go in the session scratchpad, not the repo. Anything worth keeping becomes an indd subcommand.

Corpus

corpus/ (git-ignored, ~3.4 GB): 357 third-party INDD files, 240 with a sibling IDML, plus privately held samples in corpus/own/. corpus/inventory.tsv lists version and pairing per file. Priority: InDesign 18–21, little-endian. Pairs whose IDML DOMVersion is older than the INDD version were probably re-saved after export; trust them less.

Commands

  • cargo test (all tests), cargo clippy --all-targets, cargo fmt.
  • cargo run -q -- info <file>, indd convert in.indd out.idml, indd objects <file>, indd dump <file> <uid>....
  • python3 -I tools/compare.py [--detail TAG --show N]: convert every corpus pair and compare with the reference IDML. This is the main measure of progress; run it after every change.
  • compare.py --all also converts every other INDD/INDT under corpus/ (any version, either byte order) and reports their failures; every run counts converter warnings by kind (--warnings N lists N kinds). --exclude PREFIX leaves out files whose path under corpus/ starts with PREFIX; committed numbers must not include the privately held samples (--exclude own/).
  • Schema validation: tools/validate.sh out.idml <schemas> <jing>, or compare.py --schemas <dir> --jing <dir> (validations run in parallel, --jobs N). Run compare.py --all --schemas … --jing … after changes to the IDML writer: it takes about 3 minutes. The IDML RelaxNG schemas (generated by InDesign, published in the metanorma/idml repo) and Jing (Maven Central) are kept outside the repo, for example in the session scratchpad; do not commit them.