References notes and floats/Registers and index/Tutorial

Indexes and registers in ConTeXt  ·  Overview  ·  Tutorial  ·  How-to guides  ·  Reference  ·  Explanation  ·  Glossary

🚧 Under construction — This page is still being developed. Feel free to improve the text or code, add tested examples, and correct or clarify any incomplete information.

Tutorial — Creating and formatting your first index  ·  Previous: Indexes and registers overview  ·  Next: Choose a how-to guide

1. Goal

Create a small alphabetical index, add simple and hierarchical entries, control how one entry is sorted, insert a “see” cross-reference, and place the finished index at the end of the document.

At the end of this tutorial, you will understand the basic workflow:

mark entries in the running text
        ↓
collect their page references
        ↓
sort and group the entries
        ↓
place the completed index

Result

You will produce a standard ConTeXt index using:

\index
\seeindex
\setupregister
\placeindex
\completeindex

2. Understand the standard index

In ConTeXt, the ordinary index is the predefined register named index.

The command:

\index{justice}

adds the entry justice to that register and associates it with the current page.

The command does not print the word in the running text. It only records the index entry.

Compare:

\index{justice}

with:

justice\index{justice}

The second form prints the word justice in the document and also records it in the index.

The index entry and the running text are separate

The text inside \index{...} belongs to the index mechanism.

It is not automatically inserted into the running text.

3. Create the first document

Start with the following minimal example.

3.1. MWE: three simple index entries

\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\starttext

Plato\index{Plato} discusses justice\index{justice}
in the \emph{Republic}\index{Republic}.

\page

\subject{Index}

\placeindex

\stoptext

A first standard index containing the entries justice, Plato, and Republic.

This example performs two operations:

1. \index{...} records entries while the text is being composed;
2. \placeindex prints the collected index.

The expected index contains:

J
justice, 1

P
Plato, 1

R
Republic, 1

The precise appearance depends on the current register settings.

4. Attach entries to running text

Register entries should be anchored to a paragraph or another piece of typeset material.

Prefer:

The discussion concerns justice\index{justice}.

Avoid placing the command alone after vertical spacing:

\blank
\index{justice}

An entry that cannot be attached to a suitable location may produce:

[entry not flushed]

Frequent source of errors

A register entry should normally occur inside running text.

Do not place \index by itself on an otherwise empty line or immediately after \blank.

5. Record repeated occurrences

When the same subject occurs on several pages, use the same entry text each time.

5.1. MWE: one entry on several pages

\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\starttext

Justice\index{justice} is introduced here.

\page

The argument concerning justice\index{justice} continues.

\page

A final discussion returns to justice\index{justice}.

\page

\subject{Index}

\placeindex

\stoptext

A single index entry recorded on several pages: justice appears with multiple page references in the final index.

The register groups the occurrences under one entry:

justice, 1, 2, 3

Identical entries are grouped

ConTeXt collects identical index entries and combines their page references in the final register.

6. Add subentries

Use a plus sign to express a hierarchy.

For example:

\index{Plato+Republic}
\index{Plato+Laws}

The text before the plus sign is the principal entry. The text after it is a subentry.

6.1. MWE: principal entries and subentries

\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\starttext

The \emph{Republic}\index{Plato+Republic} examines justice.

\page

The \emph{Laws}\index{Plato+Laws} discusses legislation.

\page

Justice may also be indexed by topic.\index{justice+definition}

\page

\subject{Index}

\placeindex

\stoptext

An index with principal entries and subentries: justice with the subentry definition, and Plato with the subentries Laws and Republic.

The resulting structure is conceptually:

J
justice
    definition, 3

P
Plato
    Laws, 2
    Republic, 1

ConTeXt supports deeper hierarchical entries with additional plus signs:

\index{Plato+Republic+Book I}

Use hierarchy editorially

Do not create a new subentry merely because two words occur together.

Use subentries when the hierarchy helps readers understand and navigate the subject matter.

7. Provide an explicit sorting key

Sometimes the form displayed in the index is not suitable for alphabetical sorting.

For example:

\index[CONTEXT]{\ConTeXt}

Here:

• CONTEXT is the sorting key;
• \ConTeXt is the displayed entry.

7.1. MWE: sorting a formatted entry

\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\starttext

This document is typeset with \ConTeXt\index[CONTEXT]{\ConTeXt}.

It is based on \TeX\index[TEX]{\TeX}.

\page

\subject{Index}

\placeindex

\stoptext

Formatted entries sorted with explicit keys: \ConTeXt is sorted under CONTEXT, and \TeX under TEX.

Use an explicit sorting key when:

• the displayed form contains a macro;
• punctuation should not determine the alphabetical position;
• the printed spelling differs from the intended sorting form;
• a normalized form is needed for a name or technical term.

Sorting keys have a specific purpose

Do not use an explicit sorting key merely to control the general order of uppercase letters, lowercase letters, or diacritics.

Those choices belong to the method and language settings of \setupregister.

8. Add a “see” cross-reference

A cross-reference directs readers from one entry to another.

Use:

\seeindex{ConTeXt}{TeX}

The first argument is the entry under which the cross-reference appears. The second is the target entry.

8.1. MWE: a “see” entry

\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\starttext

The document discusses \TeX\index{TeX} and its descendants.

\seeindex{ConTeXt}{TeX}

\page

\subject{Index}

\placeindex

\stoptext

A “see” cross-reference directing the reader from ConTeXt to the indexed entry TeX.

The register should contain a structure similar to:

C
ConTeXt, see TeX

T
TeX, 1

The exact wording of the cross-reference follows the language configuration of the document.

9. Configure a simple index

The command:

\setupregister[index][...]

configures the standard index.

For a first document, useful settings include:

\setupregister
  [index]
  [n=1,
   indicator=yes,
   compress=yes]

These settings mean:

Setting	Effect
n=1	Places the index in one column.
indicator=yes	Displays alphabetic group headings.
compress=yes	Collapses consecutive page references into a range when possible.

9.1. MWE: a one-column index with compressed references

\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\setupregister
  [index]
  [n=1,
   indicator=yes,
   compress=yes]

\starttext

Justice\index{justice} is discussed here.

\page

The discussion of justice\index{justice} continues.

\page

Justice\index{justice} remains central.

\page

\subject{Index}

\placeindex

\stoptext

A one-column index in which the consecutive references to justice are compressed into the page range 1–3.

With compression enabled, consecutive pages may be displayed as:

justice, 1–3

rather than:

justice, 1, 2, 3

• Note: In the example printed above, the PNG output does not show the page references compressed as 1–3, because, for the sake of economy, the MWE has been typeset on a single page. You can compile the example locally and test it with a longer text distributed across several pages, so that the compressed page range becomes visible in the resulting index.

10. Choose between \placeindex and \completeindex

ConTeXt provides two standard ways to print the index.

10.1. Place the index inside an existing division

Use:

\subject{Index}

\placeindex

Here, you create the heading explicitly and place the register beneath it.

This gives you direct control over the surrounding structure.

10.2. Create a complete index division

Use:

\completeindex

This asks ConTeXt to create the index division and its heading automatically.

The general distinction is:

Command	Function
\placeindex	Places the register content without automatically creating its structural heading.
\completeindex	Creates a complete index division, including its heading.

Placement and structural heading are separate choices

Use \placeindex when the surrounding heading or section has already been created.

Use \completeindex when ConTeXt should create the complete index division.

11. Complete example

The following example combines:

• repeated entries;
• subentries;
• an explicit sorting key;
• a “see” cross-reference;
• one-column formatting;
• compressed page references;
• automatic creation of the final index division.

11.1. MWE: a complete first index

\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\setupregister
  [index]
  [n=1,
   indicator=yes,
   compress=yes]

\starttext

\subject{Plato and justice}

Plato\index{Plato} discusses justice\index{justice}
in the \emph{Republic}\index{Plato+Republic}.

The opening book introduces the problem.\index{Plato+Republic+Book I}

\page

The discussion of justice\index{justice} continues through the dialogue.

The \emph{Laws}\index{Plato+Laws} approaches legislation differently.

\page

This example is typeset with
\ConTeXt\index[CONTEXT]{\ConTeXt}.

\seeindex{ConTeXt system}{ConTeXt}

Justice\index{justice} appears again on this page.

\completeindex

\stoptext

A complete index presented across two pages, combining repeated entries, compressed page references, hierarchical subentries, an explicit sorting key, and a “see” cross-reference.

Second page of the complete index example, continuing the hierarchical entries, compressed references, sorting key, and “see” cross-reference shown on the preceding page.

Third and final page of the complete three-page index example.

Compile the example and verify that:

1. the index is placed at the end of the document;
2. identical entries are grouped;
3. consecutive references to justice are compressed when appropriate;
4. Plato contains hierarchical subentries;
5. \ConTeXt is sorted under the supplied key;
6. the “see” cross-reference appears;
7. the index uses one column;
8. alphabetic indicators are visible.

12. Common mistakes

12.1. Expecting \index to print the indexed word

This:

\index{justice}

records the entry but does not print justice in the running text.

Use:

justice\index{justice}

when the word should also appear in the document.

12.2. Leaving an entry unattached

Avoid isolated index commands after vertical spacing or on empty lines.

Attach entries to ordinary text whenever possible.

12.3. Using inconsistent spellings

These are different entries:

\index{Plato}
\index{plato}

Use consistent spelling and capitalization unless the distinction is intentional.

12.4. Confusing the sorting key with the displayed entry

In:

\index[CONTEXT]{\ConTeXt}

the optional argument controls sorting; the braced argument controls the displayed entry.

12.5. Using a register for a structural list

An alphabetical index is a register.

A table of contents or a list of articles in document order normally belongs to the structural-list mechanism instead.

12.6. Testing with too few entries

A realistic test should include:

• entries beginning with several letters;
• one repeated entry;
• one hierarchical entry;
• one explicit sorting key;
• one cross-reference;
• enough pages to test compression.

13. What this tutorial has established

You have learned how to:

1. add an entry with \index;
2. attach an entry to running text;
3. collect repeated page references;
4. create subentries with the plus-sign syntax;
5. supply a sorting key;
6. create a “see” cross-reference with \seeindex;
7. configure a simple index with \setupregister;
8. distinguish \placeindex from \completeindex;
9. compile a complete elementary index.

The central principle is that an index entry has a displayed form, a sorting position, and one or more associated locations.

14. Next steps

14.1. Structure more elaborate entries

• Structuring index entries and cross-references

14.2. Change the presentation

• Formatting an index

14.3. Create separate editorial registers

• Creating multiple registers

14.4. Consult the documentation

• Register command reference
• Understanding the register mechanism
• Glossary of index and register terminology

Tutorial — Creating and formatting your first index  ·  Previous: Indexes and registers overview  ·  Next: Structuring index entries and cross-references

Indexes and registers in ConTeXt  ·  Overview  ·  Tutorial  ·  How-to guides  ·  Reference  ·  Explanation  ·  Glossary