Under construction. This page is being revised as part of the reorganisation of the documentation on indexes and registers in ConTeXt. Examples, screenshots, and links may still change.

Indexes and registers in ConTeXt · Overview · Tutorial · How-to guides · Reference · Explanation
How-to 4: Creating multiple registers · Previous: Formatting an index · End of the how-to guides

Creating multiple registers

A document may need several independent indexes rather than one general index.

Typical examples include:

an index of names;
an index of subjects;
an index of works;
an index of places;
an index of manuscripts or sources.

In ConTeXt, each of these is a separate register. A register is defined with \defineregister, filled with its own entry command, and placed independently.

Goal. This guide shows how to define several registers, add entries to each one, configure them separately, and place them in the back matter of a document.

1. Decide which registers the document needs

Create a separate register only when it gives readers a useful and clearly defined access path.

For example:

Register	Typical contents
Index of names	Authors, editors, historical figures
Index of subjects	Concepts, doctrines, technical topics
Index of works	Books, articles, dialogues, documents
Index of places	Cities, countries, institutions
Index of sources	Manuscripts, archival documents, ancient passages

A short document may need only one general index. Several registers are most useful when their categories are stable and contain enough entries to justify separate lists.

2. Define the registers

Define each register in the document preamble:

\defineregister
  [names]

\defineregister
  [subjects]

\defineregister
  [works]

The names names, subjects, and works are internal identifiers. They should be short, meaningful, and free of spaces.

Each definition creates a corresponding entry command:

\names{Plato}

\subjects{justice}

\works{Republic}

The three entries are collected independently.

3. Add entries to the appropriate register

A single passage may contribute entries to several registers:

\names{Plato}%
Plato discusses
\subjects{justice}%
justice in the
\works{Republic}%
\emph{Republic}.

This records:

“Plato” in the register of names;
“justice” in the register of subjects;
“Republic” in the register of works.

The percent signs suppress unwanted spaces introduced by line breaks in the source.

= 3.1. Keep register commands close to the indexed text

A clear source places each register command next to the relevant expression:

The account of
\subjects{citizenship}%
citizenship in
\names{Aristotle}%
Aristotle's
\works{Politics}%
\emph{Politics} differs from Plato's account.

This makes later checking and revision easier.

= 3.2. Classify ambiguous expressions carefully

The word “Republic” may refer to a title or to a political concept.

For Plato's work:

\works[Plato, Republic]
  {Plato, \emph{Republic}}

For the political concept:

\subjects{republic}

Separate registers make the distinction explicit.

4. Separate the sorting form from the printed form

Custom registers accept a sorting form and a printed form.

For a personal name:

\names[Beiser, Frederick C.]
  {Frederick C. Beiser}

The entry is sorted under “Beiser” but printed as “Frederick C. Beiser”.

For a title:

\works[Plato, Republic]
  {Plato, \emph{Republic}}

The sorting key contains no formatting command, while the printed form preserves the italics.

Recommended practice. Keep sorting forms plain. Put typographic commands such as \emph only in the printed form.

5. Create hierarchical entries

A register may group subordinate entries under a main entry.

For a register of works:

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

\works[Plato+Laws]
  {Plato+\emph{Laws}}

\works[Aristotle+Politics]
  {Aristotle+\emph{Politics}}

This produces a hierarchy similar to:

Aristotle
    Politics
Plato
    Laws
    Republic

A subject register can use the same mechanism:

\subjects{justice+definition}

\subjects{justice+political}

\subjects{education+music}

Use hierarchies only when the relationship between the levels is meaningful. Deeply nested entries are difficult to scan, especially in narrow columns.

6. Configure the registers

Use \setupregister with the internal name of the register:

\setupregister
  [names]
  [n=2,
   indicator=yes]

The other registers can be configured independently:

\setupregister
  [subjects]
  [n=2,
   indicator=yes,
   balance=yes]

\setupregister
  [works]
  [n=1,
   indicator=yes]

A register of names often fits well in two columns. A register containing long titles may be clearer in one column.

= 6.1. Apply common settings to several registers

Shared settings can be applied together:

\setupregister
  [names,subjects,works]
  [indicator=yes,
   indicatorstyle=bold,
   pagestyle=\tfx,
   distance=.75em]

Specific settings can then override the common setup:

\setupregister
  [names,subjects]
  [n=2]

\setupregister
  [works]
  [n=1]

This keeps the registers visually consistent while allowing differences required by their contents.

7. Define the printed titles

The internal names are not necessarily suitable as headings.

Define readable titles with:

\setupheadtext
  [names=Index of names,
   subjects=Index of subjects,
   works=Index of works]

Use parallel and precise titles:

Index of names
Index of subjects
Index of works

For a more specialised document:

\setupheadtext
  [names=Index of personal names,
   subjects=Index of concepts,
   works=Index of cited works]

8. Place the registers

Use \completeregister when each register should appear with its own heading:

\completeregister
  [names]

\completeregister
  [subjects]

\completeregister
  [works]

Use \placeregister when the heading is supplied separately:

\subject{Index of names}

\placeregister
  [names]

= 8.1. Choose between \completeregister and \placeregister

Use:

\completeregister[names]

when the register is an independent titled division.

Use:

\subject{Index of names}
\placeregister[names]

when the document structure or heading level is controlled manually.

Do not combine a manual heading with \completeregister unless two headings are intentionally required.

= 8.2. Place several registers in the back matter

A typical sequence is:

\startbackmatter

\completeregister
  [names]

\completeregister
  [subjects]

\completeregister
  [works]

\stopbackmatter

The order should reflect the needs of the readers and the conventions of the publication.

9. Combine custom registers with the predefined index

A document may contain both a general index and specialised registers.

For example:

\defineregister
  [names]

\defineregister
  [works]

Use the predefined index for subjects:

\index{political philosophy}

Use the custom registers for names and works:

\names{Plato}

\works[Plato, Republic]
  {Plato, \emph{Republic}}

Place them separately:

\completeindex

\completeregister
  [names]

\completeregister
  [works]

An entry may intentionally appear in both the general index and a specialised register, but this should follow a consistent editorial policy.

10. Complete minimal working example

The following MWE creates three independent registers:

an index of names;
an index of subjects;
an index of works.

It also demonstrates sorting forms, printed forms, hierarchical entries, separate formatting, and independent headings.

\mainlanguage[en]

\setuppapersize
  [A5]

\setupbodyfont
  [libertinus,10pt]

\setuplayout
  [backspace=18mm,
   topspace=14mm,
   header=0mm,
   footer=8mm,
   width=middle,
   height=middle]

\defineregister
  [names]

\defineregister
  [subjects]

\defineregister
  [works]

\setupregister
  [names,subjects,works]
  [indicator=yes,
   indicatorstyle=bold,
   pagestyle=\tfx,
   distance=.75em]

\setupregister
  [names,subjects]
  [n=2,
   balance=yes]

\setupregister
  [works]
  [n=1]

\setupheadtext
  [names=Index of names,
   subjects=Index of subjects,
   works=Index of works]

\starttext

\title{Creating multiple registers}

\section{Plato}

\names{Plato}%
Plato examines
\subjects{justice}%
justice in the
\works[Plato+Republic]
  {Plato+\emph{Republic}}%
\emph{Republic}.

The dialogue also gives an important place to
\subjects{education}%
education and
\subjects{political authority}%
political authority.

In the
\works[Plato+Laws]
  {Plato+\emph{Laws}}%
\emph{Laws}, legislation receives more detailed attention.

\section{Aristotle}

\names{Aristotle}%
Aristotle analyses
\subjects{citizenship}%
citizenship in the
\works[Aristotle+Politics]
  {Aristotle+\emph{Politics}}%
\emph{Politics}.

He also distinguishes several forms of
\subjects{constitution}%
constitution.

\section{Modern scholarship}

\names[Beiser, Frederick C.]
  {Frederick C. Beiser}%
Frederick C. Beiser examines major controversies in the history of
German philosophy.

\names[Hagen, Hans]
  {Hans Hagen}%
Hans Hagen is the principal developer of
\subjects{ConTeXt}%
ConTeXt.

\page

\completeregister
  [names]

\page

\completeregister
  [subjects]

\page

\completeregister
  [works]

\stoptext

Compile the document at least twice. Compile it again after changing entries, sorting forms, or register settings.

11. Variant: group short registers under one heading

Several short registers can be grouped inside a common back-matter division:

\startchapter
  [title={Indexes}]

\subject{Index of names}

\placeregister
  [names]

\page

\subject{Index of subjects}

\placeregister
  [subjects]

\page

\subject{Index of works}

\placeregister
  [works]

\stopchapter

This pattern is useful when the individual registers are too short to justify separate chapters.

12. Variant: registers for a critical edition

A critical edition may require registers of authors, works, manuscripts, and cited passages:

\defineregister
  [authors]

\defineregister
  [works]

\defineregister
  [manuscripts]

\defineregister
  [passages]

Possible entries include:

\authors{Plato}

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

\manuscripts{Paris, BnF, gr. 1807}

\passages{Plato, Republic 327a}

Define the headings:

\setupheadtext
  [authors=Index of ancient authors,
   works=Index of ancient works,
   manuscripts=Index of manuscripts,
   passages=Index of cited passages]

Then place the registers:

\completeregister[authors]

\completeregister[works]

\completeregister[manuscripts]

\completeregister[passages]

Check the sorting order. Passage references and manuscript shelfmarks may require carefully designed sorting keys. Test realistic entries before adopting the final structure.

13. Frequent errors

= 13.1. Using a register before defining it

The following command requires a preceding definition:

\names{Plato}

Add:

\defineregister
  [names]

in the preamble.

= 13.2. Using different internal names

This definition:

\defineregister
  [names]

must be matched by:

\setupregister
  [names]
  [n=2]

and:

\placeregister
  [names]

The identifiers name and names are not interchangeable.

= 13.3. Confusing the internal name with the title

Avoid using a long printed title as the identifier:

\defineregister
  [Index of names]

Prefer:

\defineregister
  [names]

\setupheadtext
  [names=Index of names]

= 13.4. Sending entries to the wrong register

A work title should normally be entered in the register of works:

\works[Plato, Republic]
  {Plato, \emph{Republic}}

A conceptual use of “republic” belongs in the subject register:

\subjects{republic}

= 13.5. Creating duplicate headings

Avoid:

\subject{Index of names}

\completeregister
  [names]

Use either:

\completeregister
  [names]

or:

\subject{Index of names}

\placeregister
  [names]

= 13.6. Using inconsistent forms for the same entry

Entries such as:

Frederick Beiser
F. C. Beiser
Frederick C. Beiser

will be treated as distinct unless they share a common sorting and printed form.

Use one canonical form:

\names[Beiser, Frederick C.]
  {Frederick C. Beiser}

= 13.7. Mixing flat and hierarchical entries

These are different structures:

\works[Plato, Republic]
  {Plato, \emph{Republic}}

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

The first is one flat entry. The second places “Republic” under “Plato”.

Choose one structure and apply it consistently.

= 13.8. Expecting complete registers after one compilation

If a register is empty or incomplete, compile the document again:

context filename.tex
context filename.tex

A further run may be necessary after extensive changes.

= 13.9. Creating too many small registers

A separate register with only a few entries may not help readers.

Consider instead:

a general index;
hierarchical entries;
cross-references;
combining related categories.

14. What this guide has established

The basic sequence for a custom register is:

\defineregister
  [names]

Add entries with:

\names{Plato}

Configure it with:

\setupregister
  [names]
  [n=2,
   indicator=yes]

Define its title with:

\setupheadtext
  [names=Index of names]

Place it with:

\completeregister
  [names]

or:

\subject{Index of names}

\placeregister
  [names]

Several registers can coexist in the same document, each with its own entries, hierarchy, formatting, title, and placement.

The essential editorial task is to define clearly what belongs in each register and to apply that classification consistently.

15. Next steps

You have now completed the how-to guides devoted to indexes and registers:

For detailed command syntax and parameters, continue with:

Index and register reference

For the conceptual distinction between an index entry, a sorting form, a printed form, a hierarchy, and a register, consult:

Explanation of indexes and registers