Files
indd-utils/docs/format/cross-references.md
T
aiongg dd15594885 feat: write paragraph-level text sources and cross-reference sources
- A text source over several character ranges of one paragraph range is
  written as a child of the ParagraphStyleRange: the ranges at its ends
  are split and the parts inside become its CharacterStyleRange
  children. Sources across paragraph ranges, or holding an XML marker,
  are left out with a warning.
- Text sources with chunk 0x135A0 are written as CrossReferenceSource
  with AppliedFormat. One that holds more than a text variable instance
  is written at paragraph level, since the schema allows no Content in
  it.

Trustworthy pairs: reproduced 10,530,141 -> 10,566,138 (91.50 % ->
91.81 %); HyperlinkTextSource 3,449 -> 5,475, CrossReferenceSource 116,
hyperlinks 3,097 -> 5,149, all with their values. Extra values 26,634 ->
26,516: the 332 values of cross-reference sources written as hyperlink
sources go, and cross-reference sources written around a character
range add their inner ranges (one pair). No key reproduces fewer values.
"spans several text ranges" warnings over all files 9,703 -> 3,277.
Schema validation: 0 failures.
2026-10-08 01:55:40 +00:00

60 lines
2.4 KiB
Markdown

# Cross-reference formats
Cross-reference formats are objects of class 0x1355E. IDML writes each as
a `CrossReferenceFormat` element in `designmap.xml` with `Self` the UID,
holding one `BuildingBlock` element per block, whose `Self` is the
format's `Self`, `BuildingBlock` and the block's index (from 0). The
schema puts them after the sections and before `idPkg:BackingStory`.
Implemented in `src/model/xref.rs`.
## Evidence
All corpus pairs, including those whose IDML is from an older version:
1,215 IDML `CrossReferenceFormat` elements, of which 1,170 have an INDD
object with the same UID. The other 45 are in pairs whose IDML was
exported from another save. All 2,250 class 0x1355E objects in the 251
distinct little-endian files parse with the layout below.
## Format (chunk 0x13593)
| Field | Contents | IDML |
|---|---|---|
| u8, string | Name | `Name` (1,170 of 1,170) |
| u32 | 0 in every sample | `AppliedCharacterStyle="n"` in every sample |
| u16 | 0 or 1, not identified | |
| u32 | Block count | number of `BuildingBlock` elements (1,170 of 1,170) |
| blocks | below | `BuildingBlock`, in order |
**Building block:**
| Field | Contents | IDML |
|---|---|---|
| u32 | Block type (below) | `BlockType` |
| 10 bytes | 0 in every sample | `AppliedCharacterStyle="n"`, `AppliedDelimiter="$ID/"`, `IncludeDelimiter="false"` in every sample |
| u8, string | Custom text; the flag byte is 1 for a built-in key, written with `$ID/` | `CustomText` (3,510 of 3,510) |
| Code | `BlockType` | Blocks in the pairs |
|---|---|---|
| 0 | `CustomStringBuildingBlock` | 1,820 |
| 3 | `PageNumberBuildingBlock` | 650 |
| 4 | `FullParagraphBuildingBlock` | 260 |
| 5 | `ParagraphNumberBuildingBlock` | 260 |
| 6 | `ParagraphTextBuildingBlock` | 260 |
| 7 | `BookmarkNameBuildingBlock` | 260 |
Custom texts in the pairs include `"`, `" on page `, ` on page ` and
`page `; the other block types have `$ID/`.
Every corpus file has the same nine formats, so the fields that are 0
everywhere cannot be located. The converter writes the character style,
delimiter and include-delimiter values above only where those fields are
0, and leaves them out otherwise. It leaves out blocks with other type
codes (none occur in the corpus); the other blocks keep their index.
## Sources in text
Cross-reference sources in text are text sources with chunk 0x135A0;
`hyperlinks.md` describes them. Cross-reference sources inside
footnotes and tracked changes are not converted, because their text is
not.