References notes and floats/Registers and index/How-to guides/Structuring index entries

From Wiki
Jump to navigation Jump to search


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 incomplete information.

How-to guide — Structuring index entries and cross-references  ·  Previous: Creating and formatting your first index  ·  Next: Formatting an index

1. Goal

Use the standard ConTeXt index mechanism to create:

  • principal entries;
  • subentries;
  • deeper hierarchical entries;
  • displayed entries with explicit sorting keys;
  • “see” cross-references.

This guide assumes that you already know how to add an ordinary entry with \index and place the resulting index with \placeindex or \completeindex.

For a step-by-step introduction, see:

Main commands 

\index
\seeindex
\placeindex
\completeindex

2. Distinguish entry structure from page references

An index entry contains at least two kinds of information: 

entry structure
      +
one or more page references

For example: 

\index{Plato+Republic}

records:

  • Plato as the principal entry;
  • Republic as its subentry;
  • the current page as the location of that occurrence.

The plus sign defines the hierarchy. It is not printed as part of the final index.

Conceptually: 

Plato+Republic
       ↓
Plato
    Republic, 1

Structure and location are separate

The text inside \index{...} determines the structure and displayed wording of the entry.

ConTeXt associates that entry with the page on which the command occurs.

3. Create principal entries

A principal entry is an entry without a higher-level parent.

Use: 

\index{justice}
\index{Plato}
\index{Republic}

In running text: 

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

The index contains three independent principal entries: 

justice, 1
Plato, 1
Republic, 1

Use principal entries when each subject should be directly accessible in the alphabetical index.

4. Create subentries

Use a plus sign to separate a principal entry from a subentry: 

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

The result is conceptually: 

Plato
    Laws, 2
    Republic, 1

The principal entry groups related subordinate topics.

4.1. Choose a meaningful hierarchy

A hierarchy should express an editorial relationship, not merely reproduce the wording of the sentence.

For example: 

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

is useful because the works are grouped under their author.

Similarly: 

\index{justice+definition}
\index{justice+political function}
\index{justice+relation to law}

groups several aspects of one concept.

Do not create accidental hierarchies

A subentry should express a stable conceptual or editorial relation.

Do not create a hierarchy merely because two words occur together in the running text.

4.2. MWE: principal entries and subentries

\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\setupregister
  [index]
  [n=1]

\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

The resulting index contains: 

justice
    definition, 3

Plato
    Laws, 2
    Republic, 1

Output image

After compiling the example locally, convert the index page to PNG and insert the validated output here.


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

5. Create deeper entry levels

Additional plus signs create deeper hierarchical levels: 

\index{Plato+Republic+Book I}
\index{Plato+Republic+Book II}
\index{Plato+Laws+Book III}

Conceptually: 

Plato
    Laws
        Book III, 3
    Republic
        Book I, 1
        Book II, 2

Each plus sign introduces another subordinate level.

5.1. Keep the hierarchy readable

A technically possible hierarchy is not always a useful hierarchy.

Compare: 

\index{Plato+Republic+Book I+Thrasymachus+definition of justice}

with: 

\index{justice+Thrasymachus}
\index{Plato+Republic+Book I}

The second approach may be easier for readers because it provides two direct access points:

  • the concept under discussion;
  • the location within the work.

Use the shallowest hierarchy that remains informative

Deep hierarchies can become difficult to scan and may produce narrow or visually unbalanced entries.

Before adding another level, consider whether a separate principal entry would provide a better access point.

5.2. MWE: three hierarchical levels

\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\setupregister
  [index]
  [n=1]

\starttext

The opening discussion occurs in
Book I of the \emph{Republic}.\index{Plato+Republic+Book I}

\page

A later argument occurs in
Book II of the \emph{Republic}.\index{Plato+Republic+Book II}

\page

The legislation is discussed in
Book III of the \emph{Laws}.\index{Plato+Laws+Book III}

\page

\subject{Index}

\placeindex

\stoptext

Expected structure: 

Plato
    Laws
        Book III, 3
    Republic
        Book I, 1
        Book II, 2


6. Provide an explicit sorting key

The form displayed in the index and the form used for sorting may differ.

Use the optional argument of \index to supply an explicit sorting key: 

\index[CONTEXT]{\ConTeXt}

Here:

Part Function
[CONTEXT] Sorting key used to determine the alphabetical position.
{\ConTeXt} Entry displayed in the final index.

6.1. Use a sorting key when the displayed form contains a command

A formatted name or logo may not provide a convenient sorting form: 

\index[CONTEXT]{\ConTeXt}
\index[TEX]{\TeX}

This ensures that the entries are sorted under ordinary alphabetic strings.

6.2. Use a sorting key to ignore punctuation or presentation

For example: 

\index[Republic]{\emph{Republic}} or:

<pre> 
\index[Plato, Republic]{Plato, \emph{Republic}}

The sorting key determines the entry’s position, while the braced argument determines its printed form.

6.3. Use a sorting key consistently

Entries that should be grouped together must use compatible displayed forms and sorting keys.

Avoid inconsistent constructions such as: 

\index[CONTEXT]{\ConTeXt}
\index[Context]{ConTeXt}
\index{context}

unless the three distinctions are intentional.

A sorting key is not a general sorting method

An explicit key changes the sorting form of one entry.

It should not be used to control the general treatment of uppercase letters, lowercase letters, accents, or language-specific collation.

Configure those matters with the language and method settings of \setupregister.

6.4. MWE: sorting formatted entries with explicit keys

\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.

7. Combine sorting keys with subentries

Sorting keys can also be used with structured entries.

For example, a displayed form containing formatting commands may be entered under a plain-text sorting form: 

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

Conceptually: 

sorting form:   Plato+Republic
displayed form: Plato+\emph{Republic}

A more elaborate example is: 

\index[Plato+Republic+Book 01]
       {Plato+\emph{Republic}+Book I}

This allows:

  • the displayed form to contain italics or other special typography;
  • the sorting form to remain plain and predictable;
  • numbered components to be normalized when necessary.

Keep structure parallel

When a structured displayed entry is given an explicit sorting key, keep the hierarchy of the sorting key parallel to the hierarchy of the displayed entry.

Each level in the sorting form should correspond to the same level in the displayed form.

8. Create a “see” cross-reference

A “see” cross-reference directs the reader from one possible entry to another preferred entry.

Use: 

\seeindex{ConTeXt}{TeX}

The arguments have the following roles:

Argument Function
{ConTeXt} Entry under which the cross-reference appears.
{TeX} Target named by the cross-reference.

Conceptually: 

ConTeXt, see TeX

The target should normally also exist as an indexed entry: 

\index{TeX}
\seeindex{ConTeXt}{TeX}

Cross-references are register entries

A “see” reference is not inserted as arbitrary text after the index has been produced.

It is recorded as a structured register entry and sorted with the other entries.

8.1. MWE: creating a “see” cross-reference

\setuppapersize[A6]

\setupbodyfont
  [libertinus,10pt]

\starttext

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

\seeindex{ConTeXt}{TeX}

\page

\subject{Index}

\placeindex

\stoptext

The register should contain a structure similar to: 

ConTeXt, see TeX

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

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

9. Create cross-references for subentries

A cross-reference may also direct the reader toward a structured entry.

For example: 

\index{Plato+Republic}
\seeindex{Republic}{Plato+Republic}

Conceptually: 

Plato
    Republic, 1

Republic, see Plato, Republic

This can be useful when readers may look for the same subject under more than one alphabetical access point.

Another example: 

\index{justice+Thrasymachus}
\seeindex{Thrasymachus}{justice+Thrasymachus}

Do not create circular cross-references

Avoid constructions such as: 

\seeindex{Plato}{Republic}
\seeindex{Republic}{Plato}

A cross-reference should direct the reader toward the preferred or fuller entry, not create a loop between two unresolved alternatives.

10. Decide when to duplicate an entry instead

A “see” reference is useful when one entry is only an alternative access form.

Sometimes, however, two real entries are more useful than one entry plus a cross-reference.

Compare: 

\index{Plato+justice}
\seeindex{justice}{Plato+justice}

with: 

\index{Plato+justice}
\index{justice+Plato}

Use a cross-reference when:

  • one heading is preferred;
  • the alternative heading should not carry its own page references;
  • the reader only needs redirection.

Use two indexed entries when:

  • both access points are independently meaningful;
  • readers may search under either concept;
  • both entries should display page references.

Editorial decision

Cross-references and duplicated access points solve different problems.

Choose according to how readers are likely to search the index, not merely according to which source command is shorter.

11. Maintain consistency in a large index

A long index benefits from a small editorial policy established before final indexing.

Decide consistently:

  • whether personal names use direct or inverted order;
  • whether works are principal entries or subentries under authors;
  • whether concepts use singular or plural forms;
  • how capitalization is handled;
  • how many hierarchy levels are allowed;
  • when alternative terms receive “see” references;
  • when two independent access points are created;
  • which displayed forms require explicit sorting keys.

A simple project convention might be:

Category Entry pattern Example
Person Family name, given name \index{Plato}
Work Author + work \index{Plato+Republic}
Concept Concept + aspect \index{justice+definition}
Alternative term “See” reference \seeindex{fairness}{justice}
Formatted technical name Explicit sorting key \index[CONTEXT]{\ConTeXt}

For a multi-file publication, these rules should be documented and, where possible, centralized in a shared environment.

12. Common problems

12.1. The plus sign appears in the wrong place

This: 

\index{Plato + Republic}

may introduce unwanted spaces into the entry structure.

Prefer: 

\index{Plato+Republic}

Use the plus sign as a structural separator, without surrounding spaces.

12.2. Similar entries do not merge

These may be treated as distinct entries: 

\index{Plato+Republic}
\index{Plato+The Republic}
\index{plato+Republic}

Standardize spelling, capitalization, and hierarchy.

12.3. The displayed form sorts unexpectedly

A macro or formatted expression may not provide the desired sorting form: 

\index{\ConTeXt}

Supply an explicit key: 

\index[CONTEXT]{\ConTeXt}

12.4. A sorting key is used to solve a language problem

Do not create manual keys for every accented or uppercase entry merely to force a general order.

Use: 

\setupregister
  [index]
  [language=...,
   method=...]

The appropriate settings are discussed in:

12.5. The cross-reference target has no indexed entry

This construction: 

\seeindex{ConTeXt}{TeX}

directs the reader toward TeX, but does not itself create a page-bearing TeX entry.

Add the target where it occurs: 

\TeX\index{TeX}

12.6. The hierarchy is too deep

A long chain such as: 

\index{philosophy+ancient philosophy+Greek philosophy+Plato+Republic+justice}

may be technically expressible but difficult to use.

Prefer several deliberate access points: 

\index{Plato+Republic}
\index{justice+Plato}
\index{Greek philosophy+Plato}

13. Complete example

The following example combines:

  • principal entries;
  • two- and three-level hierarchies;
  • explicit sorting keys;
  • a “see” cross-reference;
  • several alternative access points.

13.1. MWE: structured entries and cross-references

\setuppapersize[A6]

\setupbodyfont
  [libertinus,9pt]

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

\starttext

\subject{Plato, justice, and ConTeXt}

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

The opening discussion occurs in
Book I.\index{Plato+Republic+Book I}

\page

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

Justice is also discussed as a political virtue.
\index{justice+political virtue}

\page

This example is typeset with
\ConTeXt\index[CONTEXT]{\ConTeXt}
and is based on
\TeX\index[TEX]{\TeX}.

\seeindex{Republic}{Plato+Republic}
\seeindex{ConTeXt system}{ConTeXt}

\page

\subject{Index}

\placeindex

\stoptext

Compile the example and verify that:

  1. Plato appears as a principal entry;
  2. Republic and Laws appear as subentries under Plato;
  3. Book I appears below Republic;
  4. justice contains separate conceptual subentries;
  5. \ConTeXt and \TeX use explicit sorting keys;
  6. Republic redirects to the structured entry under Plato;
  7. ConTeXt system redirects to ConTeXt.


14. What this guide has established

This guide has shown how to:

  1. create principal entries;
  2. group related subjects as subentries;
  3. create deeper hierarchical levels;
  4. separate displayed forms from sorting forms;
  5. use explicit sorting keys for formatted entries;
  6. direct readers with “see” cross-references;
  7. create cross-references toward structured entries;
  8. distinguish cross-references from duplicated access points;
  9. maintain a consistent editorial indexing policy.

The central principle is that an index entry is an editorial structure: its hierarchy, displayed form, sorting form, and cross-references should be designed according to how readers will search the document.

15. Next steps

15.1. Change the visual presentation

15.2. Create independent editorial registers

15.3. Configure multilingual sorting

15.4. Consult commands and terminology

How-to guide — Structuring index entries and cross-references  ·  Previous: Creating and formatting your first index  ·  Next: Formatting an index

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

Retrieved from "https://wiki.contextgarden.net/index.php?title=References_notes_and_floats/Registers_and_index/How-to_guides/Structuring_index_entries&oldid=43480"