draw.io embeds, tabs and references

A draw.io diagram embedded from another page is not converted in the main pass. It becomes a Capable Diagram Reference, and that happens in a second pass once every diagram it might point at has been migrated and saved.

That ordering is the whole reason the second pass exists: a reference is useless until its target is there.

#What a reference is

A reference points at a diagram that lives somewhere else, rather than holding its own copy. Edit the original and every reference follows. That is the same behaviour the draw.io embed had, which is why it is the right target.

#Multi-tab files

A draw.io file can hold several tabs, and an embed can point at a specific one. Preserving that choice through a migration is the fiddliest part of the whole diagram family, and there is a known problem with it.

#The case the tool cannot detect

A single embed of a multi-tab file that pointed at tab 2 shows no symptom the automatic check can see, so it is passed as clean. Those pages have to be added to the repair tool by page id.

#Titles

An earlier bug let machine-generated titles leak onto references. The same repair tool replaces them with the diagram's real title where it can.

#A few things that catch people out

• Tab recovery depends on page history still holding the migration version. If it does not, or if that was the page's first version, the tabs cannot be recovered.

• References are matched to their original embeds positionally by diagram name, so two diagrams sharing a name on one page can be given the wrong tab.

• A single, non-embedded diagram macro that pointed at a specific tab loses that choice, and the repair tool does not cover it.

#Related

The second pass exists so references have something to point at.