Xref
Key point: A multi-purpose cross-reference between documents.

An xref is a semantic link between two documents, or parts of documents, that can be used in multiple ways, including the following:

  • Assemble documents into a publication.
  • Create associations between document content.
  • Insert content from one document into another as a transclusion.
  • Identify which documents point to a specific document using reverse xrefs.

Unlike links in conventional publishing applications or HTML, PageSeeder xrefs are rich structures that developers can customize or override.

Using labels, or the xref configuration, allows semantics to be attached to xrefs. This makes it possible to represent objects such as footnotes, end notes, citations, and many other structures.

When in review mode, holding the cursor over an xref displays an xref tooltip.

We use the infinity icon for inline xrefs, or xrefs in general.

We use this icon for block xrefs.

Types of xrefs

There are two kinds of xrefs depending on how they appear in the content:

  • Inline xrefs appear as a running piece of content.
  • Block xrefs are defined as a block of content.

Direction and reverse xref

The source document refers to the document containing the original xref in its content. The target document refers to the document being pointed at.

By default, xrefs are double-ended: The reverse xref is the name of the xref from the perspective of the target document.

For developers

In PSML, xrefs are represented using the <xref> or the <blockxref> element.

For more information, see the xref and blockxref elements in the PSML reference on the PageSeeder developer's website.

Xref configuration

While the standard value in the Configuration field drop-down is Default, developers can create custom configurations for specific types of xrefs. Applications of specific configurations could be to help authors xref to a pool of index entries, legal citations, or to a library of maths equations.

For developers: For more information, see the xref config article on the PageSeeder developer’s website.

Resolved and unresolved xrefs

To ensure the integrity of xrefs, when an xref is created. PageSeeder checks that the target document exists. If it does. then the xref is considered resolved. Otherwise, it is considered unresolved, and is displayed in red with the icon .

This can happen if the target document is deleted or the Resolve references option on the upload document dialog is unticked.

Unresolved xrefs can be resolved by:

  1. Editing the fragment containing the xref.
  2. Resolving references in the folder containing the source document, see resolve references dialog.
  3. Resolving references in the group, see the group maintenance page.
  4. Unarchiving a document or folder, see unarchive dialog.

Once an image, link or double-ended xref is resolved, a reverse xref is displayed on the target image, URL or document. It is useful to unresolve references when archiving documents so that the targets are not cluttered with broken reverse xrefs pointing to archived documents.