Indexes and registers in ConTeXt · Overview · Reference · Index and register command reference

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.

Index and register command reference

This page provides a compact reference to the principal commands used to create and manage indexes and registers in ConTeXt.

Scope. Use this page to identify command syntax, arguments, generated commands, and relationships between interfaces. For procedures and complete examples, follow the linked how-to guides.

1. Command overview

Command	Purpose
`\index`	Inserts an occurrence into the predefined `index` register.
`\defineregister`	Defines a new register instance and its occurrence command.
`\setupregister`	Configures sorting, layout, headings, page references, and placement.
`\placeregister`	Places a register under a heading supplied by the document.
`\completeindex` and generated `\complete...` commands	Place a register with its complete structural heading.
`\startregister` / `\stopregister`	Open and close an explicit page range.
`\defineprocessor`	Defines a named transformation for register data or page references.
`\setstructurepageregister`	Inserts an occurrence from decomposed structured fields.
`\currentregisterpageuserdata`	Retrieves occurrence userdata while a page reference is rendered.

2. The predefined index register

ConTeXt provides the register instance index by default.

2.1. Insert a simple entry

\index{justice}

2.2. Separate sorting and display

\index[justice]{Justice}

Argument	Function
`[justice]`	Sorting key
`{Justice}`	Displayed entry

2.3. Create a hierarchy

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

The plus sign separates the first-level entry from its subentry.

2.4. Place the index

\subject{Index}

\placeregister[index]

or:

\completeindex

3. \defineregister

3.1. Basic syntax

\defineregister[name]

Example:

\defineregister[persons]

This creates the occurrence command:

\persons{Plato}

and allows placement with:

\placeregister[persons]

or normally:

\completepersons

3.2. Separate key and displayed entry

\persons[Plato]{Plato}

3.3. Parent-register syntax

A second argument identifies a parent register:

\defineregister
  [child]
  [parent]

Do not write:

\defineregister
  [works]
  [works]

because this defines works as its own parent. Use:

\defineregister[works]

4. Occurrence-command syntax

The predefined \index command and commands generated by \defineregister follow the same general model.

4.1. Simple form

\registercommand{entry}

4.2. Key and displayed form

\registercommand[key]{entry}

4.3. Processor form

\registercommand[processor->key]{entry}

Example:

\index[main->justice]{justice}

4.4. Hierarchical form

\registercommand
  [first-key+second-key]
  {first-entry+second-entry}

5. \setupregister

5.1. Basic syntax

\setupregister
  [register]
  [key=value,
   key=value]

Example:

\setupregister
  [index]
  [n=2,
   balance=yes]

5.2. Configure several registers

\setupregister
  [persons,works]
  [n=2,
   balance=yes]

5.3. Frequently used settings

Setting	Typical values	Purpose
`n`	`1`, `2`, …	Number of columns.
`balance`	`yes`, `no`	Balances the final columns.
`compress`	`yes`, `no`	Controls compression of consecutive page references.
`pagecommand`	command	Applies a custom command while page references are rendered.
`before`	command	Inserts material before the register.
`after`	command	Inserts material after the register.
`style`	style name	Applies a typographical style.
`color`	colour name	Applies a colour.

Version note. The complete option set may change or inherit from related structural-list settings. Check the generated command page and the current source when an option is not documented here.

6. \placeregister and complete-placement commands

6.1. \placeregister

\placeregister[register]

Use this form when the document supplies its own heading:

\subject{Persons}

\placeregister[persons]

6.2. Complete placement

For the predefined index:

\completeindex

For:

\defineregister[persons]

the generated complete-placement command is normally:

\completepersons

7. Explicit page ranges

7.1. Open the range

\startregister
  [register]
  [tag]
  {entry}

Example:

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

7.2. Close the range

\stopregister
  [register]
  [tag]

The register name and tag must match the opening command.

8. \defineprocessor

8.1. Syntax

\defineprocessor
  [name]
  [key=value]

Example:

\defineprocessor
  [main]
  [style=bold]

8.2. Use

\index[main->justice]{justice}

Distinction. A key controls sorting. Formatting such as \emph changes the displayed entry. A processor applies a named rendering transformation.

9. \setstructurepageregister

9.1. Syntax

\setstructurepageregister
  [register]
  [register settings]
  [userdata]

9.2. One-level entry

\setstructurepageregister
  [index]
  [entries=justice,
   keys=justice]
  []

9.3. Two-level entry

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

Field	Function
`entries:1`	Displayed first-level entry.
`keys:1`	First-level sorting key.
`entries:2`	Displayed second-level entry.
`keys:2`	Second-level sorting key.

9.4. Add userdata

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

The third argument stores occurrence-specific metadata. It does not automatically alter sorting, identity, merging, or display.

10. \currentregisterpageuserdata

10.1. Retrieve a field

\currentregisterpageuserdata{role}

10.2. Use it in a page command

\define[1]\PageWithRole
  {#1%
   \doifnotempty
     {\currentregisterpageuserdata{role}}
     {\high{\currentregisterpageuserdata{role}}}}

Activate it with:

\setupregister
  [index]
  [pagecommand=\PageWithRole]

11. XML-related commands

11.1. Read an attribute

\xmlatt{#1}{key}

11.2. Insert a register occurrence from XML

\startxmlsetups xml:term
  \setstructurepageregister
    [index]
    [entries={\xmlatt{#1}{entry}},
     keys={\xmlatt{#1}{key}}]
    [role={\xmlatt{#1}{role}}]
  \xmlflush{#1}
\stopxmlsetups

The XML content printed in the paragraph remains independent of the canonical register entry.

12. Lua-related commands

A TeX wrapper can expose a stable interface to Lua:

\define[5]\RegisterAuthorityWork
  {\setstructurepageregister
     [works]
     [entries:1={#2},
      keys:1={#1},
      entries:2={\emph{#4}},
      keys:2={#3}]
     [authorityid={#5}]}

Lua can call it with:

context.RegisterAuthorityWork(
    work.authorsort,
    work.author,
    work.titlesort,
    work.title,
    work.id
)

Lua prepares and validates data; ConTeXt collects, sorts, merges, compresses, and typesets the register.

13. Project-level organisation

Command or data	Recommended location
`\defineregister`	Environment
`\setupregister`	Environment
`\defineprocessor`	Environment
Shared insertion macros	Environment
Occurrence commands	Components
`\placeregister` or complete-placement command	Product or final back-matter component

14. Generated-command relationships

\defineregister[persons]
        |
        +--> \persons{...}
        |
        +--> \setupregister[persons][...]
        |
        +--> \placeregister[persons]
        |
        +--> \completepersons

For the predefined index:

index
  |
  +--> \index{...}
  |
  +--> \setupregister[index][...]
  |
  +--> \placeregister[index]
  |
  +--> \completeindex

15. Quick selection table

Task	Command
Insert a simple index entry	`\index{entry}`
Separate sorting and display	`\index[key]{entry}`
Create a hierarchy	Separate levels with `+`
Define another register	`\defineregister[name]`
Configure a register	`\setupregister[name][...]`
Place a register under a custom heading	`\placeregister[name]`
Place it with a complete heading	Generated `\complete...` command
Mark a reference role	`\defineprocessor` and `processor->key`
Create a page range	`\startregister` / `\stopregister`
Insert decomposed data	`\setstructurepageregister`
Store occurrence metadata	Third argument of `\setstructurepageregister`
Retrieve page-reference userdata	`\currentregisterpageuserdata`

16. See also

Indexes and registers in ConTeXt · Overview · Reference · Index and register command reference

References notes and floats/Registers and index/Reference

Contents

Index and register command reference

1. Command overview

2. The predefined index register

2.1. Insert a simple entry

2.2. Separate sorting and display

2.3. Create a hierarchy

2.4. Place the index

3. \defineregister

3.1. Basic syntax

3.2. Separate key and displayed entry

3.3. Parent-register syntax

4. Occurrence-command syntax

4.1. Simple form

4.2. Key and displayed form

4.3. Processor form

4.4. Hierarchical form

5. \setupregister

5.1. Basic syntax

5.2. Configure several registers

5.3. Frequently used settings

6. \placeregister and complete-placement commands

6.1. \placeregister

6.2. Complete placement

7. Explicit page ranges

7.1. Open the range

7.2. Close the range

8. \defineprocessor

8.1. Syntax

8.2. Use

9. \setstructurepageregister

9.1. Syntax

9.2. One-level entry

9.3. Two-level entry

9.4. Add userdata

10. \currentregisterpageuserdata

10.1. Retrieve a field

10.2. Use it in a page command

11. XML-related commands

11.1. Read an attribute

11.2. Insert a register occurrence from XML

12. Lua-related commands

13. Project-level organisation

14. Generated-command relationships

15. Quick selection table

16. See also

Navigation menu

Search