Reading and preserving tagged XML

An application can ignore the tagged-XML layer for layout, but one that saves a document has to carry it through unchanged.

In short Reading the layer means following the design map's idPkg:Tags and idPkg:BackingStory references, reading the XMLTag list, and walking the XmlStory for XMLElement nodes and the placed content they point at. Most documents need little of this: an untagged InDesign document has one Root element and nothing else. Preserving the layer is simpler and matters more: copy the XML/ parts as they are, keep the design map's references to them, and keep the ids of the stories and frames the tree points at.

Reading the layer

The layer has no effect on where anything lands on a page, so a renderer or a text extractor can skip it. An application that wants the structure, for example to export content by tag, reads it in four steps:

1. Find the parts. The design map names XML/Tags.xml in idPkg:Tags and XML/BackingStory.xml in idPkg:BackingStory. It does not reference XML/Mapping.xml, which InDesign does not write.
2. Read the tags. Each XMLTag in Tags.xml is a Self and a Name.
3. Walk the tree. The XmlStory in the backing story is shaped like a story; XMLElement nodes sit among its character ranges and nest inside each other. Each names its tag in MarkupTag.
4. Resolve placed content. An XMLElement that labels content already on a page names it by Self in XMLContent; the text itself stays in the layout story.

If the backing story holds only the Root element, the document is untagged and there is nothing more to read. That is the case for almost every document in the census.

Preserving the layer

An application that opens a document, changes something and saves it is responsible for everything it did not change, including a layer it never read:

• Copy the XML/ parts unchanged. Regenerating them from nothing would drop the author's structure; the zero-width U+FEFF characters in the backing story are part of it.
• Keep the design map references idPkg:Tags and idPkg:BackingStory.
• Keep the ids the tree points at. An XMLElement refers to placed content by its Self, so renaming a story or a frame on save breaks that link.

"Not read" and "not kept" are different things. A tool can leave the layer alone and still return it intact.

In Paged: no part of the XML layer is read: there is no reader for XMLTag, XmlStory or XMLElement, and the design map's idPkg:BackingStory reference is not followed. The XML parts are kept as raw bytes and copied byte for byte on save, like every part Paged does not model; an unedited round trip of the corpus reproduces all 99 tested packages exactly. The .paged container keeps the same parts. Planned

Frequently asked questions

Does a renderer need the tagged-XML layer? No. The layout comes entirely from the spreads, stories and styles; the XML layer labels that content without changing it.

How do I tell whether a document is tagged? Look at XML/BackingStory.xml. An untagged document's XmlStory holds a single XMLElement with MarkupTag="XMLTag/Root"; a tagged one has more elements.

What must a tool keep when it saves an IDML file? The XML/ parts as they were, the design map's idPkg:Tags and idPkg:BackingStory references, and the Self ids of stories and frames that the XML tree refers to.

Does Paged keep the XML layer when it saves? Yes. It does not read the layer, but it copies the XML parts byte for byte on save.