View source for References notes and floats/Registers and index/Tutorial

<!--
Page title:
References notes and floats/Registers and index/Tutorial

Displayed title:
Creating and formatting your first index

Purpose:
Step-by-step tutorial introducing the standard ConTeXt index mechanism.

The tutorial shows how to mark entries, create subentries, provide a
sorting key, add a cross-reference, configure a simple index, and place
the final index with or without an automatically generated heading.

Document type:
Tutorial.

Status:
Under construction.
-->

<div style="background:#eef5fb; border:1px solid #9bbbd4; padding:0.65em 0.9em; margin-bottom:1em;">
'''Indexes and registers in ConTeXt''' &nbsp;·&nbsp;
[[References notes and floats/Registers and index|Overview]] &nbsp;·&nbsp;
'''Tutorial''' &nbsp;·&nbsp;
[[References notes and floats/Registers and index#7. How-to guides|How-to guides]] &nbsp;·&nbsp;
[[References notes and floats/Registers and index/Reference|Reference]] &nbsp;·&nbsp;
[[References notes and floats/Registers and index/Explanation|Explanation]] &nbsp;·&nbsp;
[[References notes and floats/Registers and index/Glossary|Glossary]]
</div>

<div style="background:#fff8d6; border:1px solid #d6b84a; border-left:5px solid #c49a00; padding:0.75em 0.95em; margin:1em 0;">
<span style="font-size:1.15em; margin-right:0.35em;">🚧</span>
'''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.
</div>

<div style="background:#f7f9fb; border:1px solid #c7d3dd; padding:0.65em 0.9em; margin:1em 0;">
'''Tutorial — Creating and formatting your first index''' &nbsp;·&nbsp;
[[References notes and floats/Registers and index|Previous: Indexes and registers overview]] &nbsp;·&nbsp;
[[References notes and floats/Registers and index#7. How-to guides|Next: Choose a how-to guide]]
</div>

__TOC__

== 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:

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

<div style="background:#f2f8ee; border-left:5px solid #6f9b55; padding:0.8em 1em; margin:1em 0;">
'''Result'''

You will produce a standard ConTeXt index using:

<pre>
\index
\seeindex
\setupregister
\placeindex
\completeindex
</pre>
</div>

== 2. Understand the standard index ==

In ConTeXt, the ordinary index is the predefined register named <code>index</code>.

The command:

<pre>
\index{justice}
</pre>

adds the entry <em>justice</em> 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:

<pre>
\index{justice}
</pre>

with:

<pre>
justice\index{justice}
</pre>

The second form prints the word <em>justice</em> in the document and also records it in the index.

<div style="background:#eef5fb; border-left:5px solid #4f81a8; padding:0.8em 1em; margin:1em 0;">
'''The index entry and the running text are separate'''

The text inside <code>\index{...}</code> belongs to the index mechanism.

It is not automatically inserted into the running text.
</div>

== 3. Create the first document ==

Start with the following minimal example.

=== 3.1. MWE: three simple index entries ===

<pre>
\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\starttext

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

\page

\subject{Index}

\placeindex

\stoptext
</pre>

[[File:first-index-standard-01.png|center|600px|thumb|A first standard index containing the entries ''justice'', ''Plato'', and ''Republic''.]]

This example performs two operations:

# <code>\index{...}</code> records entries while the text is being composed;
# <code>\placeindex</code> prints the collected index.

The expected index contains:

<pre>
J
justice, 1

P
Plato, 1

R
Republic, 1
</pre>

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:

<pre>
The discussion concerns justice\index{justice}.
</pre>

Avoid placing the command alone after vertical spacing:

<pre>
\blank
\index{justice}
</pre>

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

<pre>
[entry not flushed]
</pre>

<div style="background:#fbeaea; border-left:5px solid #b74d4d; padding:0.8em 1em; margin:1em 0;">
'''Frequent source of errors'''

A register entry should normally occur inside running text.

Do not place <code>\index</code> by itself on an otherwise empty line or immediately after <code>\blank</code>.
</div>

== 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 ===

<pre>
\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
</pre>

[[File:index-wiki-mwe02.png|center|600px|thumb|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:

<pre>
justice, 1, 2, 3
</pre>

<div style="background:#eef5fb; border-left:5px solid #4f81a8; padding:0.8em 1em; margin:1em 0;">
'''Identical entries are grouped'''

ConTeXt collects identical index entries and combines their page references in the final register.
</div>

== 6. Add subentries ==

Use a plus sign to express a hierarchy.

For example:

<pre>
\index{Plato+Republic}
\index{Plato+Laws}
</pre>

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

=== 6.1. MWE: principal entries and subentries ===

<pre>
\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
</pre>

[[File:index-wiki-subentry-mwe03.png|center|600px|thumb|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:

<pre>
J
justice
    definition, 3

P
Plato
    Laws, 2
    Republic, 1
</pre>

ConTeXt supports deeper hierarchical entries with additional plus signs:

<pre>
\index{Plato+Republic+Book I}
</pre>

<div style="background:#fff4df; border-left:5px solid #d08a24; padding:0.8em 1em; margin:1em 0;">
'''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.
</div>

== 7. Provide an explicit sorting key ==

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

For example:

<pre>
\index[CONTEXT]{\ConTeXt}
</pre>

Here:

* <code>CONTEXT</code> is the sorting key;
* <code>\ConTeXt</code> is the displayed entry.

=== 7.1. MWE: sorting a formatted entry ===

<pre>
\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
</pre>

[[File:index-wiki-mwe04.png|center|600px|thumb|Formatted entries sorted with explicit keys: <code>\ConTeXt</code> is sorted under ''CONTEXT'', and <code>\TeX</code> 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.

<div style="background:#fff4df; border-left:5px solid #d08a24; padding:0.8em 1em; margin:1em 0;">
'''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 <code>method</code> and <code>language</code> settings of <code>\setupregister</code>.
</div>

== 8. Add a “see” cross-reference ==

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

Use:

<pre>
\seeindex{ConTeXt}{TeX}
</pre>

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

=== 8.1. MWE: a “see” entry ===

<pre>
\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\starttext

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

\seeindex{ConTeXt}{TeX}

\page

\subject{Index}

\placeindex

\stoptext
</pre>

[[File:index-wiki-mwe05.png|center|600px|thumb|A “see” cross-reference directing the reader from ''ConTeXt'' to the indexed entry ''TeX''.]]

The register should contain a structure similar to:

<pre>
C
ConTeXt, see TeX

T
TeX, 1
</pre>

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

== 9. Configure a simple index ==

The command:

<pre>
\setupregister[index][...]
</pre>

configures the standard index.

For a first document, useful settings include:

<pre>
\setupregister
  [index]
  [n=1,
   indicator=yes,
   compress=yes]
</pre>

These settings mean:

{| class="wikitable" style="width:100%;"
! style="width:30%;" | Setting
! style="width:70%;" | Effect
|-
| <code>n=1</code>
| Places the index in one column.
|-
| <code>indicator=yes</code>
| Displays alphabetic group headings.
|-
| <code>compress=yes</code>
| Collapses consecutive page references into a range when possible.
|}

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

<pre>
\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
</pre>

[[File:index-wiki-column-mwe06.png|center|600px|thumb|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:

<pre>
justice, 1–3
</pre>

rather than:

<pre>
justice, 1, 2, 3
</pre>

* '''Note''': ''In the example printed above, the PNG output does not show the page references compressed as <code>1–3</code>, 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:

<pre>
\subject{Index}

\placeindex
</pre>

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:

<pre>
\completeindex
</pre>

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

The general distinction is:

{| class="wikitable" style="width:100%;"
! style="width:36%;" | Command
! style="width:64%;" | Function
|-
| <code>\placeindex</code>
| Places the register content without automatically creating its structural heading.
|-
| <code>\completeindex</code>
| Creates a complete index division, including its heading.
|}

<div style="background:#eef5fb; border-left:5px solid #4f81a8; padding:0.8em 1em; margin:1em 0;">
'''Placement and structural heading are separate choices'''

Use <code>\placeindex</code> when the surrounding heading or section has already been created.

Use <code>\completeindex</code> when ConTeXt should create the complete index division.
</div>

== 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 ===

<pre>
\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
</pre>

[[File:index-wiki-complete-mwe07.png|center|600px|thumb|A complete index presented across two pages, combining repeated entries, compressed page references, hierarchical subentries, an explicit sorting key, and a “see” cross-reference.]]

[[File:index-wiki-complete-mwe07 1.png|center|600px|thumb|Second page of the complete index example, continuing the hierarchical entries, compressed references, sorting key, and “see” cross-reference shown on the preceding page.]]

[[File:index-wiki-mwe07-ter.png|center|600px|thumb|Third and final page of the complete three-page index example.]]

Compile the example and verify that:

# the index is placed at the end of the document;
# identical entries are grouped;
# consecutive references to <em>justice</em> are compressed when appropriate;
# <em>Plato</em> contains hierarchical subentries;
# <code>\ConTeXt</code> is sorted under the supplied key;
# the “see” cross-reference appears;
# the index uses one column;
# alphabetic indicators are visible.

== 12. Common mistakes ==

=== 12.1. Expecting \index to print the indexed word ===

This:

<pre>
\index{justice}
</pre>

records the entry but does not print <em>justice</em> in the running text.

Use:

<pre>
justice\index{justice}
</pre>

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:

<pre>
\index{Plato}
\index{plato}
</pre>

Use consistent spelling and capitalization unless the distinction is intentional.

=== 12.4. Confusing the sorting key with the displayed entry ===

In:

<pre>
\index[CONTEXT]{\ConTeXt}
</pre>

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:

# add an entry with <code>\index</code>;
# attach an entry to running text;
# collect repeated page references;
# create subentries with the plus-sign syntax;
# supply a sorting key;
# create a “see” cross-reference with <code>\seeindex</code>;
# configure a simple index with <code>\setupregister</code>;
# distinguish <code>\placeindex</code> from <code>\completeindex</code>;
# 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 ===

* [[References notes and floats/Registers and index/How-to guides/Structuring index entries|Structuring index entries and cross-references]]

=== 14.2. Change the presentation ===

* [[References notes and floats/Registers and index/How-to guides/Formatting an index|Formatting an index]]

=== 14.3. Create separate editorial registers ===

* [[References notes and floats/Registers and index/How-to guides/Creating multiple registers|Creating multiple registers]]

=== 14.4. Consult the documentation ===

* [[References notes and floats/Registers and index/Reference|Register command reference]]
* [[References notes and floats/Registers and index/Explanation|Understanding the register mechanism]]
* [[References notes and floats/Registers and index/Glossary|Glossary of index and register terminology]]

<div style="background:#f7f9fb; border:1px solid #c7d3dd; padding:0.65em 0.9em; margin:1em 0;">
'''Tutorial — Creating and formatting your first index''' &nbsp;·&nbsp;
[[References notes and floats/Registers and index|Previous: Indexes and registers overview]] &nbsp;·&nbsp;
[[References notes and floats/Registers and index/How-to guides/Structuring index entries|Next: Structuring index entries and cross-references]]
</div>

<div style="background:#eef5fb; border:1px solid #9bbbd4; padding:0.65em 0.9em; margin-top:1em;">
'''Indexes and registers in ConTeXt''' &nbsp;·&nbsp;
[[References notes and floats/Registers and index|Overview]] &nbsp;·&nbsp;
'''Tutorial''' &nbsp;·&nbsp;
[[References notes and floats/Registers and index#7. How-to guides|How-to guides]] &nbsp;·&nbsp;
[[References notes and floats/Registers and index/Reference|Reference]] &nbsp;·&nbsp;
[[References notes and floats/Registers and index/Explanation|Explanation]] &nbsp;·&nbsp;
[[References notes and floats/Registers and index/Glossary|Glossary]]
</div>

[[Category:Basics]]