References notes and floats/Registers and index/Explanation

Indexes and registers in ConTeXt  ·  Overview  ·  Explanation  ·  Explanation of indexes and registers

Under construction. This page explains the conceptual model behind the commands used in the tutorial, how-to guides, and reference pages.

This page has recently been revised and reorganized.

Further corrections, additions, and improvements are welcome. Please feel free to edit or modify this page to improve it.

Explanation of indexes and registers

An index is often described as an alphabetical list followed by page numbers. That description is useful for readers, but it hides the processing model used to create the result.

In ConTeXt, an index or register is built from occurrences recorded throughout the document. Each occurrence contributes structured information: an entry, a sorting form, a location, an optional hierarchy, and sometimes a processor or userdata. The register subsystem collects those occurrences, groups related ones, sorts them, merges their references, and finally renders the result when the register is placed.

Purpose. This page explains how the principal layers of an index or register interact. It does not provide a sequence of tasks or a complete list of command options.

1. The complete processing model

The basic sequence is:

document occurrence
        |
        v
entry data and sorting data
        |
        v
register instance
        |
        v
page location or page range
        |
        v
collection and aggregation
        |
        v
sorting and duplicate handling
        |
        v
placement
        |
        v
rendered index or register

Each stage answers a different question:

Stage	Question
Occurrence	Where in the document is this item mentioned?
Entry data	What should appear in the register?
Sorting data	Under which alphabetical position should it be filed?
Register instance	In which collection does the occurrence belong?
Reference	Which page or page range should be attached to it?
Aggregation	Which occurrences belong to the same entry?
Placement	Where and how should the completed register be printed?

2. Entries and occurrences are not the same thing

An entry is the conceptual item represented in the register. An occurrence is one place in the document where that item is recorded.

For example:

\index{justice}

records one occurrence of the entry justice at the current location.

If the same command appears on several pages, ConTeXt does not normally create several independent printed entries. It groups the occurrences under one entry and attaches several references to it.

Conceptually:

occurrence on page 12  \
occurrence on page 27   >  entry: justice  ->  12, 27, 41
occurrence on page 41  /

Key distinction. The entry is the indexed object. The occurrences are the document locations from which its references are collected.

3. Displayed forms and sorting forms

The text printed in the register does not have to be the text used for sorting.

Consider:

\index[Plato+Republic]
      {Plato+\emph{Republic}}

The optional argument contains plain sorting data:

Plato+Republic

The braced argument contains the displayed form:

Plato+\emph{Republic}

This separation is important because typographical markup, capitalization, punctuation, abbreviations, and language-specific forms may not be suitable sorting data.

Representation	Function
Sorting form	Determines alphabetical order.
Displayed form	Determines what the reader sees.

The two forms may be identical, but they serve different purposes.

3.1. Why formatting should not control sorting

Formatting commands describe appearance. Sorting requires stable comparable text.

A title may be printed as:

\emph{The Republic}

while its sorting form may be:

Republic

The distinction allows the project to ignore a leading article without changing the reader-facing title.

4. Hierarchical entries express conceptual structure

Registers can contain several levels.

For example:

Plato
    Laws
    Republic

The hierarchy may be supplied in ordinary syntax with a plus sign:

\index[Plato+Republic]
      {Plato+\emph{Republic}}

or through structured fields:

\setstructurepageregister
  [works]
  [entries:1={Plato},
   keys:1={Plato},
   entries:2={\emph{Republic}},
   keys:2={Republic}]
  []

The two interfaces express the same conceptual separation:

Level	Example
First-level entry	Plato
Second-level entry	Republic

Hierarchy is not merely visual indentation. It contributes to the identity and grouping of the register entry.

5. Registers are named collections

A register instance determines which collection receives an occurrence.

The predefined register is named index:

\index{justice}

Additional registers can be defined:

\defineregister[persons]
\defineregister[works]

They create separate collections:

\persons{Plato}

and:

\works{Republic}

The same word may therefore occur in several registers without the registers being merged.

Register identity. The register instance is part of the occurrence's identity. An entry in persons and an entry in works belong to different collections even when their displayed text is identical.

6. Processors add named rendering roles

A processor is a named transformation applied when register data is rendered.

For example:

\defineprocessor
  [main]
  [style=bold]

An occurrence can then use:

\index[main->justice]{justice}

The processor name main expresses an editorial role. Its current visual effect is defined separately.

This produces a useful separation:

Layer	Example	Responsibility
Entry identity	justice	Determines what is indexed.
Sorting form	justice	Determines order.
Processor	main	Marks a rendering role.
Processor definition	style=bold	Determines appearance.

A processor should not be confused with a sorting key. One controls presentation; the other controls order.

7. References belong to occurrences

Every occurrence is associated with a document location.

The most common reference is the current page number. ConTeXt records that page when the occurrence is processed.

Several occurrences of the same entry may therefore produce:

justice  12, 27, 41

The references do not exist independently of occurrences. They are derived from the locations at which the occurrences were recorded.

7.1. Page ranges

An explicit range records one continuous span:

\startregister
  [index]
  [guardianeducation]
  {education+guardians}

...

\stopregister
  [index]
  [guardianeducation]

The shared tag identifies the opening and closing points of the same range.

Conceptually:

range opening  ->  pages 12--15  <-  range closing

A page range is therefore not a list of separate occurrences. It is one occurrence with an extended location.

8. Duplicate handling depends on entry identity

When several occurrences have the same register instance, hierarchy, and key data, ConTeXt can group them under one printed entry.

For example:

\index{justice}

on three pages normally produces one entry with three references.

The grouping logic does not automatically treat arbitrary userdata as part of the entry identity.

This matters when two distinct entities have the same displayed name:

John Smith

If their register keys and hierarchy are identical, they may be merged even when their userdata contains different identifiers.

Identity rule. If two records must remain distinct, encode that distinction in their keys or hierarchy. Do not rely only on auxiliary userdata.

9. Userdata stores occurrence-specific metadata

Structured insertion allows arbitrary metadata to be stored with an occurrence:

\setstructurepageregister
  [index]
  [entries=justice,
   keys=justice]
  [role=m,
   source=chapter-one]

The third argument contains userdata.

Userdata may record:

• an XML identifier;
• an authority-file identifier;
• an editorial role;
• a source division;
• a language;
• a confidence value;
• a project-specific classification.

ConTeXt stores these values but does not assign them an automatic visible form.

A custom rendering command may retrieve one field:

\currentregisterpageuserdata{role}

This creates a clear distinction:

Data	Automatic effect
Entry	Printed in the register.
Key	Used for sorting and grouping.
Reference	Printed as a page location.
Userdata	Stored for custom processing; not printed automatically.

10. Placement is separate from collection

Recording occurrences and printing the final register are separate operations.

Occurrences are inserted throughout the document:

\index{justice}

The completed register is placed later:

\placeregister[index]

This separation allows one register to collect entries from:

• several sections;
• several chapters;
• several components;
• an entire product;
• XML or Lua processing pipelines.

Placement triggers the visible presentation of data already collected by the register subsystem.

10.1. Placement does not create occurrences

The command:

\placeregister[index]

does not scan the document for words. It renders occurrences that were explicitly recorded during processing.

10.2. Placement does not define the register

The register instance and its settings already exist before placement. Placement determines where the result appears, not what belongs to it.

11. Configuration and content have different roles

In a multi-file project, the layers are usually distributed as follows:

Project layer	Register responsibility
Environment	Defines registers, processors, formatting, and shared macros.
Components	Record occurrences beside the content they describe.
Product	Assembles the complete document.
Back-matter component	Places the completed registers.

This organisation mirrors the conceptual model:

shared rules       -> environment
document locations -> components
global collection  -> product processing
final rendering    -> back matter

12. XML separates occurrence wording from canonical data

In XML, the visible wording of an occurrence may differ from the canonical register entry.

For example:

<title ref="plato-republic">the dialogue on justice</title>

The phrase printed in the paragraph is:

the dialogue on justice

but the authority record may supply:

Plato
    Republic

The XML reference connects the occurrence to the canonical data.

This separation is valuable because the visible phrase may be:

• inflected;
• abbreviated;
• translated;
• paraphrased;
• dependent on local syntax.

The canonical register entry should therefore come from explicit fields or an authority record rather than from the visible wording alone.

13. Lua acts as a preparation layer

Lua is useful when register data must be:

• resolved from identifiers;
• validated;
• normalised;
• combined from several sources;
• cached;
• reported when missing or ambiguous.

A typical pipeline is:

stable identifier
        |
        v
Lua lookup and validation
        |
        v
separate sorting and display fields
        |
        v
\setstructurepageregister
        |
        v
ConTeXt register subsystem

Lua should normally prepare the data rather than reproduce ConTeXt's sorting and rendering logic.

Division of labour. XML or Lua determines which data should be registered. ConTeXt remains responsible for collecting occurrences, sorting entries, aggregating references, and typesetting the result.

14. The full architecture

The complete model can be represented as follows:

source document
    |
    +--> visible text
    |
    +--> register occurrence
             |
             +--> register instance
             +--> sorting key
             +--> displayed entry
             +--> hierarchy
             +--> processor
             +--> userdata
             +--> page location
                         |
                         v
                 register collection
                         |
                         +--> grouping
                         +--> sorting
                         +--> duplicate handling
                         +--> reference aggregation
                         |
                         v
                     placement
                         |
                         v
              final index or register

Each item in the final register is therefore the result of several coordinated layers, not the direct reproduction of one source string.

15. Common conceptual confusions

15.1. “The entry and the key are the same thing”

They may contain the same text, but they have different functions. The entry is printed; the key controls sorting.

15.2. “A processor defines the entry”

A processor supplies a named transformation. It does not replace the entry's identity or sorting data.

15.3. “Userdata should appear automatically”

Userdata is stored metadata. It must be retrieved explicitly by custom code if it is to affect the visible result.

15.4. “Placing an index searches the document”

Placement renders occurrences already recorded. It does not discover terms automatically.

15.5. “Every occurrence becomes a separate printed entry”

Equivalent occurrences are normally aggregated under one entry with several references.

15.6. “The visible XML phrase should become the register entry”

The visible phrase may be context-dependent. Canonical entry data should come from explicit attributes or authority records when available.

15.7. “Lua should sort and typeset the register”

Lua may prepare data, but ConTeXt already provides the collection, sorting, merging, reference, and rendering mechanisms.

16. What this explanation has established

Indexes and registers in ConTeXt are built from structured occurrences.

The principal relationships are:

1. an occurrence records one indexed location;
2. an entry identifies what is indexed;
3. a sorting form determines alphabetical order;
4. a displayed form determines reader-facing text;
5. hierarchy organises related entries;
6. a register instance selects the collection;
7. a processor assigns a named rendering role;
8. a reference records the page or range;
9. userdata preserves auxiliary metadata;
10. aggregation combines related occurrences;
11. placement renders the completed collection.

Key conclusion. A register is not merely a list generated at the end of a document. It is the rendered result of a data model that keeps semantic identity, sorting behaviour, displayed text, document location, and presentation separate.

17. See also

• Indexes and registers in ConTeXt
• Indexes and registers tutorial
• Indexes and registers: how-to guides
• Index and register command reference
• Structuring index entries and cross-references
• Formatting an index
• Managing structured register data
• Managing indexes in a project environment

Indexes and registers in ConTeXt  ·  Overview  ·  Explanation  ·  Explanation of indexes and registers