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 5: Formatting selected entries and page references with processors · Previous: Creating multiple registers

Formatting selected entries and page references with processors

The general appearance of a register is controlled with \setupregister. Sometimes, however, only one entry or one page reference should receive special formatting.

Typical cases include:

emphasising a principal discussion of a subject;
distinguishing an important page reference from ordinary occurrences;
marking a provisional or secondary entry;
applying the same local treatment in several different registers.

ConTeXt provides processors for this purpose. A processor is defined once and attached only to the entries or page references that require it.

Goal. This guide shows how to define a processor, apply it to a selected register entry, apply it to a selected page reference, and combine both forms without changing the general register setup.

1. Start from the general register style

Use \setupregister for formatting that applies to the whole register:

\setupregister
  [index]
  [textstyle=normal,
   pagestyle=normal,
   n=2,
   indicator=yes]

This establishes the default presentation.

A processor should be used only for exceptions to that presentation. It is not a replacement for the general register setup.

2. Define a processor

Define a processor with \defineprocessor:

\defineprocessor
  [important]
  [style=bold]

The name important identifies the processor. The settings describe the formatting that it applies.

A processor may combine a style and a colour:

\definecolor
  [ImportantColor]
  [h=7A2E2E]

\defineprocessor
  [important]
  [style=bold,
   color=ImportantColor]

Another processor may mark secondary material more discreetly:

\definecolor
  [SecondaryColor]
  [s=.65]

\defineprocessor
  [secondary]
  [style=italic,
   color=SecondaryColor]

Use meaningful names. Names such as important, secondary, or principal describe the function of the formatting better than names such as red or bold.

3. Apply a processor to an entry

Place the processor name before the entry and separate it from the entry with ->:

\index{important->political philosophy}

The entry “political philosophy” is formatted with the processor important. Other entries retain the general register style:

\index{authority}

\index{important->political philosophy}

\index{sovereignty}

The processor affects the printed entry in the register. It does not print anything in the running text.

3.1. Apply a processor to a custom register

Processors also work with registers created by \defineregister:

\defineregister
  [names]

\defineprocessor
  [important]
  [style=bold]

\names{Plato}

\names{important->Aristotle}

Only “Aristotle” receives the special formatting.

A processor is not tied to one register. Once defined, it can be reused:

\names{important->Plato}

\subjects{important->justice}

\works{important->Republic}

4. Preserve a separate sorting form

A selected entry may require both:

a processor;
a sorting form different from the printed form.

Place the processor in the printed entry:

\names[Beiser, Frederick C.]
  {important->Frederick C. Beiser}

The entry is sorted under “Beiser, Frederick C.” but printed with the important processor.

For a title:

\works[Plato, Republic]
  {important->Plato, \emph{Republic}}

Keep formatting commands out of the sorting key.

4.1. Use processors in hierarchical entries

A processor can be applied to the first level:

\index{important->Plato+Republic}

It can also be attached to a subordinate level:

\index{Plato+important->Republic}

The position of the processor determines which level receives the formatting.

For a formatted title with a separate sorting form:

\works[Plato+Republic]
  {Plato+important->\emph{Republic}}

Use this selectively. The hierarchy should remain visually coherent.

5. Apply a processor to a page reference

To process the page reference rather than the entry text, place the processor in the optional argument:

\index[important->]{political philosophy}

The entry “political philosophy” retains the general entry style, but the page reference for this occurrence receives the important formatting.

For example:

\index{political philosophy}
An ordinary mention of political philosophy.

\page

\index[important->]{political philosophy}
This page contains the principal discussion of political philosophy.

In the index, both occurrences belong to the same entry, but the page number of the principal discussion is distinguished.

Typical use. A processed page reference can identify the page on which a subject is discussed substantially, while unprocessed references indicate passing mentions.

5.1. Do not omit the arrow

This does not apply a processor:

\index[important]{political philosophy}

Without ->, the optional argument is interpreted as a sorting key.

Use:

\index[important->]{political philosophy}

6. Combine a page-reference processor with a sorting key

Place the sorting key after the arrow:

\names[important->Beiser, Frederick C.]
  {Frederick C. Beiser}

This has two effects:

the page reference is formatted with important;
the entry is sorted under “Beiser, Frederick C.”.

For a work:

\works[important->Plato, Republic]
  {Plato, \emph{Republic}}

The printed entry remains unchanged, while the page reference is processed and the sorting key remains explicit.

7. Format both the entry and its page reference

Use a processor in both arguments:

\index[important->]
  {important->political philosophy}

With a sorting key:

\names[important->Beiser, Frederick C.]
  {important->Frederick C. Beiser}

This applies the processor separately to:

the printed entry;
the page reference for that occurrence.

Use this combination only when both elements genuinely require emphasis. In many indexes, highlighting the page reference alone is sufficient.

8. Use different processors for different functions

Different processors can express different editorial meanings:

\definecolor
  [PrincipalColor]
  [h=7A2E2E]

\definecolor
  [SecondaryColor]
  [s=.65]

\defineprocessor
  [principal]
  [style=bold,
   color=PrincipalColor]

\defineprocessor
  [secondary]
  [style=italic,
   color=SecondaryColor]

Apply them to separate occurrences:

\index[principal->]{justice}

\index{justice}

\index[secondary->]{justice}

The resulting page-reference list may distinguish:

a principal discussion;
an ordinary occurrence;
a secondary or incidental occurrence.

= 8.1. Define the editorial meaning before using processors

A processor should have a stable meaning throughout the document.

For example:

Processor	Intended meaning	Suggested treatment
`principal`	Main discussion of the subject	Bold page reference
`secondary`	Secondary or incidental discussion	Italic or grey page reference
`important`	Entry requiring special attention	Bold entry

Do not use the same processor sometimes for importance, sometimes for uncertainty, and sometimes only for decoration.

9. Reuse processors in several registers

A processor can be shared by the general index and custom registers:

\defineregister
  [names]

\defineregister
  [works]

\defineprocessor
  [principal]
  [style=bold]

Then:

\index[principal->]{justice}

\names[principal->Plato]{Plato}

\works[principal->Plato, Republic]
  {Plato, \emph{Republic}}

The processor has the same visual effect wherever it is used.

If different registers require different meanings or treatments, define separate processors:

\defineprocessor
  [principalsubject]
  [style=bold]

\defineprocessor
  [principalwork]
  [style=italic]

10. Complete minimal working example

The following MWE demonstrates:

a general register setup;
two processors;
a processed entry;
a processed page reference;
an ordinary occurrence;
a separate sorting form;
a hierarchical entry;
a custom register.

\mainlanguage[en]

\setuppapersize
  [A5]

\setupbodyfont
  [libertinus,10pt]

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

\defineregister
  [names]

\definecolor
  [PrincipalColor]
  [h=7A2E2E]

\definecolor
  [SecondaryColor]
  [s=.60]

\defineprocessor
  [principal]
  [style=bold,
   color=PrincipalColor]

\defineprocessor
  [secondary]
  [style=italic,
   color=SecondaryColor]

\setupregister
  [index,names]
  [n=1,
   indicator=yes,
   indicatorstyle=bold,
   textstyle=normal,
   pagestyle=normal,
   distance=.75em]

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

\starttext

\title{Formatting selected entries and page references with processors}

\section{Preliminary discussion}

\index{justice}
Justice is introduced as a general philosophical problem.

\index{political philosophy}
Political philosophy concerns the relation between argument,
authority, and collective life.

\names[Plato]{Plato}
Plato is introduced as one of the principal ancient authors.

\page

\section{Principal discussion}

\index[principal->]{justice}
This page contains the principal discussion of justice.

\index{principal->political philosophy}
The entry “political philosophy” itself is emphasised in the index.

\names[principal->Plato]
  {principal->Plato}
This occurrence makes both the entry and its page reference prominent.

\index[Plato+Republic]
  {Plato+principal->\emph{Republic}}
The title \emph{Republic} is emphasised at the subordinate level.

\page

\section{Secondary discussion}

\index[secondary->]{justice}
Justice is mentioned here only as a secondary topic.

\names[Beiser, Frederick C.]
  {Frederick C. Beiser}
Frederick C. Beiser is entered under his family name.

\page

\completeindex

\page

\completeregister
  [names]

\stoptext

Compile the document at least twice. Compile it again after changing processors, entries, or sorting keys.

Because this example must generate several logical pages in order to demonstrate explicit page ranges and compressed references, its complete output is not reproduced here as a PNG. Compile the MWE to inspect the page sequence and the final registers.

11. Frequent errors

11.1. Forgetting to define the processor

This entry requires a processor named principal:

\index{principal->justice}

Define it first:

\defineprocessor
  [principal]
  [style=bold]

11.2. Omitting the arrow

This optional argument is a sorting key:

\index[principal]{justice}

This optional argument applies a processor to the page reference:

\index[principal->]{justice}

11.3. Applying the processor to the wrong element

To format the entry:

\index{principal->justice}

To format the page reference:

\index[principal->]{justice}

To format both:

\index[principal->]
  {principal->justice}

11.4. Losing the sorting key

If a name requires surname sorting, retain the sorting key after the page processor:

\names[principal->Beiser, Frederick C.]
  {Frederick C. Beiser}

Do not replace the sorting key accidentally with:

\names[principal->]
  {Frederick C. Beiser}

unless the printed form also gives the desired sorting order.

11.5. Using a processor for all entries

If every entry or every page reference requires the same style, use \setupregister:

\setupregister
  [index]
  [textstyle=bold,
   pagestyle=italic]

Processors are intended for selected exceptions.

11.6. Assigning several meanings to one processor

Do not use important for principal discussions in one chapter and for uncertain references in another.

Define processors with distinct editorial functions:

\defineprocessor
  [principal]
  [style=bold]

\defineprocessor
  [uncertain]
  [style=italic]

11.7. Over-formatting the index

Too many colours, styles, and processor categories make an index harder to scan.

Prefer a small system with one or two clearly explained distinctions.

11.8. Expecting the index to update after one compilation

Compile the document repeatedly:

context filename.tex
context filename.tex

A further run may be needed after extensive changes.

12. A practical workflow

Define the general register appearance with \setupregister.
Decide which exceptional meanings need visual marking.
Define one processor for each stable editorial meaning.
Apply processor->entry to selected entry text.
Apply [processor->] to selected page references.
Put a sorting key after the arrow when necessary.
Test ordinary, processed, and hierarchical entries together.
Compile repeatedly and inspect the complete register.
Verify that each distinction remains clear in monochrome printing.

13. What this guide has established

Define a processor with:

\defineprocessor
  [principal]
  [style=bold]

Apply it to an entry with:

\index{principal->justice}

Apply it to a page reference with:

\index[principal->]{justice}

Combine it with a sorting key:

\names[principal->Beiser, Frederick C.]
  {Frederick C. Beiser}

Apply it to both the entry and the page reference:

\index[principal->]
  {principal->justice}

Processors provide local exceptions to the general formatting established by \setupregister. Their value lies not merely in visual emphasis, but in expressing a consistent editorial distinction.

14. Next steps

Return to the complete list of practical guides:

Index and register how-to guides

For the syntax of \defineprocessor, \index, and custom register commands, consult:

Index and register reference

For the distinction between global register formatting and local processor-based formatting, consult:

Explanation of indexes and registers