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 6: Managing page ranges and compressed references · Previous: Formatting selected entries and page references with processors

Managing page ranges and compressed references

An index entry may refer to:

one isolated page;
several separate pages;
a continuous discussion extending across several pages;
several consecutive occurrences that should be shown as one range.

ConTeXt provides two different mechanisms:

\startregister and \stopregister mark an explicit range whose beginning and end are known;
compress=yes merges consecutive page references collected from repeated entries.

These mechanisms solve related but different problems.

Goal. This guide shows how to create an explicit page range, compress repeated references automatically, choose between the two methods, and avoid accidental or misleading ranges.

1. Distinguish isolated references from ranges

Repeated ordinary entries produce a list of page references:

\index{justice}

If the same entry occurs on pages 2, 5, and 9, the index may show:

justice  2, 5, 9

A continuous discussion is better represented as a range:

justice  12–16

A range should indicate continuity. It should not be used merely because two unrelated mentions happen to occur on adjacent pages.

2. Mark an explicit page range

Use \startregister at the beginning of the range and \stopregister at the end:

\startregister[index][justice-range]{justice}

This discussion of justice begins here.

\page

The discussion continues on the next page.

\stopregister[index][justice-range]

The arguments are:

Argument	Function
`index`	Name of the register
`justice-range`	Unique label identifying this range
`justice`	Entry printed in the register

The opening and closing commands must use the same register name and the same range label.

2.1. Use a unique label

The label identifies the open range:

\startregister[index][justice-range]{justice}

Close it with:

\stopregister[index][justice-range]

A different range needs a different label:

\startregister[index][education-range]{education}
...
\stopregister[index][education-range]

The label is internal and is not printed in the index.

2.2. Keep the range tied to a continuous discussion

Place the opening command where the substantial discussion begins:

\startregister[index][citizenship-range]{citizenship}

Place the closing command where it ends:

\stopregister[index][citizenship-range]

Do not include unrelated material merely to obtain a longer range.

3. Use explicit ranges in custom registers

The same mechanism works with a custom register:

\defineregister
  [names]

\startregister[names][plato-range]{Plato}

A discussion of Plato begins here.

\page

The discussion continues.

\stopregister[names][plato-range]

For a register of works:

\defineregister
  [works]

\startregister[works][republic-range]
  {Plato+\emph{Republic}}

...

\stopregister[works][republic-range]

If a separate sorting form is needed, test the complete syntax in a minimal document before applying it throughout a large project.

4. Create overlapping ranges

Range labels allow several ranges to remain open at the same time:

\startregister[index][justice-range]{justice}

A discussion of justice begins.

\startregister[index][education-range]{education}

The discussion now also concerns education.

\page

The discussion of justice ends here.

\stopregister[index][justice-range]

The discussion of education continues.

\page

\stopregister[index][education-range]

The two ranges overlap, but each is closed independently with its own label.

Why labels matter. Range labels let ConTeXt distinguish several open ranges, even when they overlap or end in a different order from the one in which they began.

5. Compress repeated consecutive references automatically

When the same ordinary entry is recorded on consecutive pages, use:

\setupregister
  [index]
  [compress=yes]

For example:

\index{justice}
Text on the first page.

\page

\index{justice}
Text on the second page.

\page

\index{justice}
Text on the third page.

Without compression, the references may appear separately:

justice  1, 2, 3

With compress=yes, ConTeXt can combine them:

justice  1–3

5.1. Enable compression when defining a custom register

Compression can be set when the register is defined:

\defineregister
  [names]
  [compress=yes]

Then repeated consecutive occurrences such as:

\names{Plato}
...
\page
\names{Plato}
...
\page
\names{Plato}

can be shown as one range.

5.2. Enable compression when configuring the register

Compression can also be configured separately:

\defineregister
  [names]

\setupregister
  [names]
  [compress=yes]

This form keeps the definition and presentation settings separate.

5.3. Enable compression at placement

For a local placement decision:

\placeindex
  [compress=yes]

or:

\placeregister
  [names]
  [compress=yes]

For a project-wide policy, a definition or setup in the preamble is usually clearer.

6. Choose between explicit ranges and automatic compression

Use an explicit range when:

the entry describes one continuous discussion;
the beginning and end are known;
the entry need not be repeated on every page;
several ranges may overlap.

Use automatic compression when:

ordinary entry commands already occur on each relevant page;
the occurrences happen to be consecutive;
ConTeXt should merge those references during register generation.

Need	Recommended method
Mark one discussion extending across pages	`\startregister` and `\stopregister`
Merge repeated entries on consecutive pages	`compress=yes`
Keep non-consecutive references separate	Ordinary entries, with or without compression
Handle overlapping discussions	Explicit ranges with unique labels

Do not confuse the two methods. Automatic compression infers a range from consecutive recorded occurrences. An explicit range asserts that the indexed discussion itself extends continuously from its opening point to its closing point.

7. Combine ranges with ordinary references

An entry may have both isolated references and a range:

\index{justice}

An introductory mention of justice.

\page

\startregister[index][justice-main]{justice}

The principal discussion begins.

\page

The principal discussion continues.

\stopregister[index][justice-main]

\page

\index{justice}

A later isolated reference.

The index can then contain:

justice  1, 2–3, 4

This structure distinguishes:

an introductory occurrence;
the principal continuous discussion;
a later occurrence.

8. Combine ranges with processors

A processor can distinguish a range from ordinary page references.

Define a processor:

\defineprocessor
  [principal]
  [style=bold]

Apply it to the range entry:

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

...

\stopregister[index][justice-main]

Depending on the desired result, processors may also be applied to page references. Test processor placement carefully when ranges are involved, because the same processor can affect both ends of a range.

For a simple and predictable index, begin with an unprocessed range and add processor formatting only after the range itself works correctly.

9. Understand what compression does not mean

In this context, compress=yes combines consecutive references:

144, 145, 146

into a range:

144–146

It does not necessarily abbreviate repeated digits according to a house style such as:

144–46

or:

144–6

Digit elision is a separate typographic convention and should not be assumed from the register compression setting.

10. Complete minimal working example

The following MWE demonstrates:

isolated index references;
one explicit range;
one automatically compressed sequence;
overlapping explicit ranges;
a custom register;
placement of both registers.

\mainlanguage[en]

\setuppapersize
  [A5]

\setupbodyfont
  [libertinus,10pt]

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

\defineregister
  [names]
  [compress=yes]

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

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

\starttext

\title{Managing page ranges and compressed references}

\section{Introduction}

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

\names{Plato}
Plato is mentioned on this page.

\page

\section{A continuous discussion}

\startregister[index][justice-main]{justice}

The principal discussion of justice begins here.

\names{Plato}
Plato is discussed again.

\page

The discussion of justice continues.

\names{Plato}

\startregister[index][education-main]{education}

The argument now also concerns education.

\page

The principal discussion of justice ends here.

\stopregister[index][justice-main]

The discussion of education continues.

\names{Plato}

\page

The discussion of education ends here.

\stopregister[index][education-main]

\index{justice}
Justice receives one final isolated mention.

\page

\completeindex

\page

\completeregister
  [names]

\stoptext

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. Copy and paste locally to compile the MWE to inspect the page sequence and the final registers.

With a stable compilation, the subject index should distinguish isolated references from the explicit ranges, while the consecutive occurrences of “Plato” in the custom register are eligible for automatic compression.

Compile the document at least twice. Compile it again after changing range boundaries, labels, or compression settings.

11. Frequent errors

11.1. Omitting the range label

Avoid:

\startregister[index]{justice}
...
\stopregister[index]

Use a label:

\startregister[index][justice-range]{justice}
...
\stopregister[index][justice-range]

11.2. Using different labels at the beginning and end

Incorrect:

\startregister[index][justice-range]{justice}
...
\stopregister[index][justice-main]

Correct:

\startregister[index][justice-range]{justice}
...
\stopregister[index][justice-range]

11.3. Closing the wrong register

Incorrect:

\startregister[index][justice-range]{justice}
...
\stopregister[names][justice-range]

The register name must match:

\stopregister[index][justice-range]

11.4. Reusing one label for unrelated ranges

Do not reuse:

\startregister[index][main]{justice}
...
\stopregister[index][main]

\startregister[index][main]{education}
...
\stopregister[index][main]

Prefer descriptive unique labels:

justice-main
education-main

11.5. Forgetting to close a range

An open range must be closed:

\stopregister[index][justice-range]

Keep the opening and closing commands visible and use descriptive labels to make unmatched ranges easier to find.

11.6. Using an explicit range for unrelated adjacent mentions

Two mentions on consecutive pages do not automatically form one continuous discussion.

Use ordinary entries and let compress=yes handle consecutive references when compression is editorially acceptable.

11.7. Expecting automatic compression without repeated entries

Compression works from recorded occurrences.

This records only one occurrence:

\index{justice}

To let ConTeXt infer a sequence, the same entry must be recorded on each relevant page.

For a discussion that spans pages without repeated commands, use an explicit range.

11.8. Using inconsistent sorting or printed forms

These may be treated as different entries:

\index{Justice}
\index{justice}

Likewise, inconsistent sorting keys can prevent references from being combined.

Use one canonical entry form throughout the document.

11.9. Expecting one compilation to update the range

Compile repeatedly:

context filename.tex
context filename.tex

A further run may be required after moving range boundaries or changing pagination.

11.10. Assuming compression abbreviates page digits

The setting:

compress=yes

combines consecutive pages into a range. It does not by itself define a house style for shortening the second page number.

12. A practical workflow

Decide whether the reference represents isolated occurrences or one continuous discussion.
Use ordinary register commands for isolated occurrences.
Use \startregister and \stopregister for a known continuous range.
Assign every explicit range a unique descriptive label.
Enable compress=yes when consecutive ordinary references should be merged.
Keep entry forms and sorting keys consistent.
Test overlapping ranges in a small document.
Compile repeatedly.
Inspect the final index for misleading or accidental ranges.

13. What this guide has established

Create an explicit range with:

\startregister[index][justice-range]{justice}
...
\stopregister[index][justice-range]

Compress repeated consecutive references with:

\setupregister
  [index]
  [compress=yes]

Use explicit ranges for continuous discussions whose boundaries are known.

Use automatic compression when repeated ordinary entries occur on consecutive pages.

The two methods can coexist:

justice  1, 4–7, 12

A well-designed index uses ranges to communicate continuity, not merely to reduce the number of printed references.

14. Next steps

Return to the complete list of practical guides:

Index and register how-to guides

For the syntax of \startregister, \stopregister, and register compression settings, consult:

Index and register reference

For the conceptual distinction between an occurrence, an inferred sequence, and an explicit range, consult:

Explanation of indexes and registers