Cross-references & the index

Cross-references and the index are the references that must be filled in by a whole-document pass — the parser captures their inputs, but the resolution that turns them into rendered text is deferred.

In short Unlike hyperlinks, a cross-reference and an index do not leave the displayed text alone — each is meant to be completed by a pass over the entire document. A CrossReferenceSource borrows its display phrase from the target it points at ("see Chapter 3", "page 12") via an applied format; an index is assembled from Topic definitions and zero-width markers scattered through the body copy. Paged's parser records all of these inputs — formats, destinations, topics, and markers — onto the document model, but the resolution and generation that would produce the rendered phrase or the index story are not yet built. This page covers what the parser keeps from each and why nothing prints yet.

Hyperlinks and bookmarks point somewhere and leave the displayed text alone. The two constructs on this page are different: each one is meant to be filled in by a pass over the whole document. A cross-reference borrows its display text from the thing it points at ("see Chapter 3", "page 12"); an index is assembled from markers scattered through the body copy. Both therefore depend on a resolution step — and that step is the part the engine has not built yet. The parser records the inputs; the resolution that turns them into rendered text is deferred.

CrossReferenceSource

A cross-reference source is a marker that says "show, here, a phrase derived from that target." Its AppliedFormat names a CrossReferenceFormat — a template that decides the words ("See", "See also", a page number, the heading text) — and its Destination names the anchor the phrase is built from. The parser keeps the id, name, format ref, and destination.

Attribute · CrossReferenceSource	Type / values	Support	Notes
Self	string id	Supported	The cross-reference source id.
Name	string	Supported	Human-readable name.
AppliedFormat	string ref (CrossReferenceFormat/…)	Parsed, not rendered	The format template that decides the displayed phrase. Kept on the model; not applied.
Destination	string ref (a text anchor / destination)	Parsed, not rendered	The target the phrase is derived from. Kept on the model; not resolved.

The closely related index cross-reference — IDML's CrossReference element, which records a "see / see also" entry within an index rather than inline body text — carries a CrossReferenceType drawn from a fixed vocabulary (CustomCrossReference, CustomCrossReferenceAfter, CustomCrossReferenceBefore, See, SeeAlso, SeeAlsoHerein, SeeHerein, SeeOrAlsoBracket), an optional CustomTypeString for the custom variants, and a ReferencedTopic. The parser folds these into the same cross-reference record.

Supporteda cross-reference resolves to its destination's current page and re-resolves when the destination moves, so its page number stays correct after a reflow

Topic and the index entries

An index has two halves that meet only at resolution time.

The topics are the headings the finished index will list. Each Topic element in the design map declares one term: its id, its display Name, and an optional SortOrder that overrides where it falls alphabetically (so "École" can sort under E, or "1984" under N for "nineteen…"). The parser flattens IDML's nested-topic tree to one record per Self.

Attribute · Topic	Type / values	Support	Notes
Self	string id	Supported	The topic id — what an in-story marker names via AppliedTopic.
Name	string	Supported	The term as it should print in the index.
SortOrder	string	Parsed, not rendered	Optional sort key overriding alphabetical order. Kept; not yet applied.

The markers are the other half: zero-width points scattered through the body text that each say "this spot contributes to a topic." They are serialised inside the story runs as PageReference, IndexEntry, or Index elements — the parser treats all three names the same — and it attaches each one to the paragraph it sits in. A marker that carries an inline TopicName uses that term directly; a marker that instead carries AppliedTopic="Topic/<id>" is meant to be looked up against the Topic table above. Either way the marker inserts no character into the run, so the body text flows past it untouched.

Attribute · PageReference / IndexEntry / Index (in-story marker)	Type / values	Support	Notes
TopicName	string	Parsed, not rendered	The indexed term given inline on the marker. Captured onto the host paragraph.
AppliedTopic	string ref (Topic/<id>)	Parsed, not rendered	Reference to a Topic; the term comes from the topic table when this is used instead of TopicName.
SortOrder	string	Parsed, not rendered	Optional per-marker sort override. Captured; not yet applied.

A marker with neither TopicName nor AppliedTopic has nothing to index and is dropped.

How they resolve

Both constructs run a whole-document pass that turns the captured markers into output:

• A cross-reference resolves its Destination to that destination's current page and produces the page number, re-resolving on every render so the value survives a reflow. The full AppliedFormat template prose (heading-text and "See also" building blocks beyond the page number) is the remaining nuance. Supporteddestination → current page resolved and re-resolved; page-number building block produced
• An index collects every <PageReference> / <IndexEntry> marker, groups them case-insensitively by topic, deduplicates and sorts each topic's page list, and emits a generated index story (topic + tab + page list). Supportedmarkers grouped by topic, page lists deduplicated + sorted, generated index paragraphs emitted

Frequently asked questions

What is the difference between a cross-reference and a hyperlink? A hyperlink jumps to a destination and leaves its displayed text alone. A cross-reference instead derives the very words it shows from its target: its AppliedFormat names a CrossReferenceFormat template that decides the phrase ("See", "See also", a page number, the heading text), and its Destination names the anchor the phrase is built from. The arrow and the words it shows are bound together.

How does IDML represent an index? In two halves that meet only at resolution time. The topics are Topic elements in the design map — each declares a term's id, display Name, and an optional SortOrder. The markers are zero-width points scattered through the story runs (serialised as PageReference, IndexEntry, or Index elements) that each say "this spot contributes to a topic," either via an inline TopicName or an AppliedTopic reference into the topic table.

Does a cross-reference or index marker insert text into the run? No. A cross-reference source and an index marker both add reference metadata without inserting any character, so the body text flows past them untouched. A cross-reference's phrase would only appear after its format is applied to a resolved destination; an index marker contributes to a generated index story rather than to inline text.

Why doesn't Paged print cross-references or an index? Both need a whole-document pass the engine does not yet run. A cross-reference's display text would come from applying its AppliedFormat to a resolved Destination, and an index would come from collecting every marker, grouping by topic, alphabetising (honouring SortOrder), and emitting a generated story. The parser captures all the inputs, but these resolution and generation passes are parsed, not rendered, deferred to SDK Phase 5.