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

Final validation pending. This glossary has been revised for terminology, internal navigation, and consistency. The remaining task is to verify external and command-page links before removing this notice.

Glossary of index and register terms

1. Glossary entries at a glance

Alphabetic group · Authority data · Canonical entry · Column balance · Complete register · Compression · Cross-reference · Displayed entry · Displayed form · Duplicate handling · Entry · Entry identity · Entry level · First-level entry · Formatting · Generated command · Group indicator · Hierarchical entry · Hierarchy · Index · Index entry · Indexing · Key · Locator · Main entry · Main reference · Merge · Multiple registers · Named register · Number of columns · Occurrence · Occurrence command · Page command · Page range · Page reference · Placement · Preferred term · Processor · Project environment · Range tag · Reference · Reference aggregation · Register · Register collection · Register heading · Register instance · Register layout · Second-level entry · See reference · See-also reference · Sorting · Sorting form · Sorting key · Structured register data · Subentry · Userdata · XML occurrence

2. Glossary

A

Alphabetic group

A subdivision of a register containing entries that begin with the same initial letter or belong to the same sorting group. It may be introduced by an alphabetic heading such as “A”, “B”, or “C”.

Authority data

A controlled source of canonical names, titles, identifiers, and sorting forms. Authority data is especially useful when several textual variants must point to one stable register entry.

Example:

visible text: the dialogue on justice
authority entry: Plato
                 Republic

C

Canonical entry

The stable form chosen to represent an entity in a register, independently of the wording used at a particular occurrence in the running text.

A canonical entry may be supplied directly:

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

or resolved from XML, Lua, or authority data.

Column balance

The adjustment of register columns so that the final columns end at approximately the same vertical position.

Typical setup:

\setupregister
  [index]
  [n=2,
   balance=yes]

Complete register

A register placed through its complete-placement command, which also creates the associated structural heading.

For the predefined index:

\completeindex

For a named register such as persons, the corresponding command is normally:

\completepersons

This differs from \placeregister, which places the register contents without requiring ConTeXt to generate the surrounding heading.

Compression

The reduction of consecutive collected page references into a compact form.

For example, 12, 13, 14, 15 may be rendered as 12--15, depending on the register setup.

Compression operates on several collected page references. It should not be confused with an explicit page range created with \startregister and \stopregister.

Cross-reference

A register entry that directs the reader to another entry rather than primarily to a page number.

Typical editorial forms include See ... and See also ....

Cross-references are used to connect synonyms, variant forms, related concepts, or preferred headings.

D

Displayed entry

The text printed in the final register.

Example:

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

Here, Plato+\emph{Republic} provides the displayed hierarchy.

Displayed form

The reader-facing form of an entry. It may contain capitalization, punctuation, font changes, abbreviations, or other typographical markup.

The displayed form should be kept conceptually separate from the sorting form.

See also: canonical entry, sorting form.

Duplicate handling

The process by which several equivalent occurrences are grouped under one printed register entry.

For example, three occurrences of:

\index{justice}

may produce:

justice  12, 27, 41

Duplicate handling depends on register identity, hierarchy, and key data. Arbitrary userdata does not automatically make two entries distinct.

E

Entry

The conceptual item represented in a register.

An entry is not the same as an occurrence: one entry may be recorded at many locations.

Entry identity

The combination of data that determines whether two occurrences belong to the same printed register entry.

Entry identity normally depends on:

the register instance;
the hierarchy;
the sorting keys;
the structural entry data.

When two entities must remain distinct, that distinction should be encoded in their keys or hierarchy rather than only in userdata.

Entry level

One position in a hierarchical register entry.

For example:

Plato
    Republic

contains:

level 1: Plato;
level 2: Republic.

In structured syntax, levels may be represented as:

entries:1
keys:1
entries:2
keys:2

F

First-level entry

The highest visible level of a hierarchical register entry.

Example:

Plato
    Republic

Here, Plato is the first-level entry.

Formatting

The visual treatment applied to register entries, headings, group indicators, page references, processors, spacing, columns, and other typographical elements.

Formatting should not be confused with sorting or entry identity.

See also: processor, register layout, sorting.

G

Generated command

A command automatically created when a named register is defined.

For example:

\defineregister[persons]

generates an occurrence command such as:

\persons{Plato}

and normally a complete-placement command such as:

\completepersons

Group indicator

A heading or marker that introduces an alphabetic or logical group within a register.

Example:

A
Aristotle ...

P
Plato ...

H

Hierarchical entry

An entry divided into two or more levels.

Ordinary syntax uses a plus sign:

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

Structured syntax uses numbered fields:

entries:1={Plato},
keys:1={Plato},
entries:2={\emph{Republic}},
keys:2={Republic}

Hierarchy

The ordered relation between a main entry and one or more subordinate entries.

Hierarchy contributes to both the intellectual organisation and the identity of register entries.

I

Index

A register designed to help readers locate names, concepts, works, places, or other subjects in a document.

ConTeXt provides the register instance index by default:

\index{justice}

It can be placed with:

\placeregister[index]

or:

\completeindex

Index entry

An entry belonging to the predefined index register.

The term may refer either to the conceptual indexed item or, less precisely, to one occurrence command in the source.

Indexing

The editorial and technical process of selecting items, assigning canonical entries and sorting keys, recording occurrences, and producing the final index.

Indexing includes intellectual decisions as well as command syntax and layout.

K

Key

A normalized value primarily used to sort and group a register entry.

In:

\index[justice]{Justice}

justice is the key and Justice is the displayed entry.

In hierarchical or structured registers, several keys may contribute to the identity and position of an entry.

L

Locator

A reference attached to an index entry, usually a page number or page range.

Examples include 12, 12--15, and 12, 27, 41.

In this documentation, the term page reference is generally preferred when discussing ConTeXt's register mechanism.

M

Main entry

The top-level entry under which subentries or page references are grouped.

Example:

Plato
    Laws
    Republic

Here, Plato is the main entry.

Main reference

A page reference marked as especially important, often by a processor that renders it in bold or another distinctive style.

Example:

\defineprocessor
  [main]
  [style=bold]

\index[main->justice]{justice}

Merge

The grouping of equivalent occurrences under one printed entry.

Multiple registers

Two or more named register instances maintained independently in the same document.

Example:

\defineregister[persons]
\defineregister[works]

N

Named register

A register instance explicitly defined by the user with \defineregister.

Example:

\defineregister[persons]

The name identifies the register collection, its occurrence command, its setup target, and its placement commands.

Number of columns

The number of columns used when a register is placed.

Example:

\setupregister
  [index]
  [n=2]

See also: column balance, register layout.

↑ Back to glossary entries

O

Occurrence

One location in the document at which an entry is recorded.

Example:

\index{justice}

Each occurrence contributes a page reference or range to the corresponding entry.

Occurrence command

A command that records an occurrence in a register.

The predefined occurrence command is:

\index{entry}

A user-defined register creates a command with the same name as the register:

\defineregister[persons]

\persons{Plato}

P

Page command

A command applied while page references are rendered.

Example:

\setupregister
  [index]
  [pagecommand=\PageWithRole]

A page command may use occurrence userdata through:

\currentregisterpageuserdata{field}

Page range

A continuous span associated with one register entry.

Example:

\startregister
  [index]
  [guardianeducation]
  {education+guardians}

...

\stopregister
  [index]
  [guardianeducation]

The tag links the opening and closing commands.

Page reference

The page number attached to an occurrence and printed beside the corresponding register entry.

Several references may be aggregated:

justice  12, 27, 41

See also: locator, reference aggregation.

Placement

The operation that renders a collected register at a chosen point in the document.

Example:

\placeregister[index]

Placement is separate from occurrence recording. It does not scan the document for terms.

Preferred term

The canonical heading chosen when several synonymous or variant forms exist.

Other forms may point to it through cross-references.

See also: canonical entry, cross-reference.

Processor

A processor assigns a named rendering transformation to register data.

Example:

\defineprocessor
  [main]
  [style=bold]

and:

\index[main->justice]{justice}

A processor does not replace the sorting key, the displayed entry, or the hierarchy. In the examples used in this documentation, processors are commonly attached to individual page references in order to distinguish main and secondary occurrences.

Project environment

A shared ConTeXt file containing project-wide definitions and setup commands.

For registers, it commonly contains:

\defineregister;
\setupregister;
\defineprocessor;
shared occurrence macros;
typographical settings.

↑ Back to glossary entries

R

Range tag

A stable identifier connecting the beginning and end of one explicit page range.

Example: guardianeducation in:

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

Reference

A document location associated with a register occurrence.

The most common references are page numbers and page ranges.

See also: locator, page reference, page range.

Reference aggregation

The collection of several references under one printed entry.

Example:

justice  12, 27, 41

Register

A named collection of structured occurrences that ConTeXt can sort, group, aggregate, and place.

An index is one kind of register. Other registers may contain persons, works, places, technical terms, or project-specific entities.

Register collection

The accumulated data belonging to one register instance before or during placement.

The collection includes entries, keys, hierarchy, references, processors, and optional userdata.

Register heading

The title introducing a placed register.

It may be supplied explicitly:

\subject{Index}
\placeregister[index]

or generated by a complete-placement command such as:

\completeindex

Register instance

One named register collection with its own occurrence command, setup, and placement.

Example:

\defineregister[persons]

defines the instance persons.

Register layout

The typographical arrangement of a placed register, including:

number of columns;
column balance;
indentation;
spacing;
group indicators;
headings;
entry styles;
page-reference styles.

S

Second-level entry

A subordinate entry placed under a first-level entry.

Example:

Plato
    Republic

Here, Republic is the second-level entry.

See reference

A cross-reference directing the reader from a non-preferred or variant term to a preferred entry.

Example:

State, see Political community

See also: cross-reference, preferred term.

See-also reference

A cross-reference directing the reader to a related entry while retaining the current one as valid.

Example:

Justice, see also Law

Sorting

The process of ordering register entries according to their sorting keys and the active language or collation rules.

Sorting is distinct from formatting.

Sorting form

The normalized textual form used for ordering an entry.

It may omit typographical markup, leading articles, punctuation, or other material that should not control order.

Sorting key

The value used to determine the alphabetical or logical position of an entry.

Example:

\index[Republic]{\emph{The Republic}}

Here, Republic is the sorting key.

Structured register data

Register information supplied as separate named fields rather than as one compact argument.

Example:

\setstructurepageregister
  [works]
  [entries:1={Plato},
   keys:1={Plato},
   entries:2={\emph{Republic}},
   keys:2={Republic}]
  [authorityid={work-plato-republic}]

Structured data is useful for macros, XML, Lua, databases, and authority files.

Subentry

An entry subordinate to a main or first-level entry.

Example:

Plato
    Laws
    Republic

Laws and Republic are subentries.

See also: hierarchical entry, main entry.

↑ Back to glossary entries

U

Userdata

Occurrence-specific metadata stored with structured register data.

Example:

\setstructurepageregister
  [index]
  [entries=justice,
   keys=justice]
  [role=m,
   source=chapter-one]

Userdata is not printed automatically. It may be retrieved during rendering with:

\currentregisterpageuserdata{role}

↑ Back to glossary entries

X

XML occurrence

A register occurrence generated from XML content or attributes.

The visible XML text and the canonical register entry may remain separate.

Example:

\startxmlsetups xml:term
  \setstructurepageregister
    [index]
    [entries={\xmlatt{#1}{entry}},
     keys={\xmlatt{#1}{key}}]
    [role={\xmlatt{#1}{role}}]
  \xmlflush{#1}
\stopxmlsetups

3. Functional map

Need	Concept	Main command or interface
Record a simple occurrence	Occurrence	`\index`
Define a separate collection	Register instance	`\defineregister`
Control register appearance	Register layout	`\setupregister`
Place collected data	Placement	`\placeregister`
Place with a complete heading	Complete register	`\completeindex` or generated `\complete...`
Create a hierarchy	Hierarchical entry	`+` syntax or numbered structured fields
Separate order from appearance	Sorting key / Displayed entry	optional key plus braced displayed entry
Mark a reference role	Processor	`\defineprocessor`
Record a continuous span	Page range	`\startregister` / `\stopregister`
Insert decomposed data	Structured register data	`\setstructurepageregister`
Store auxiliary metadata	Userdata	third argument of `\setstructurepageregister`
Retrieve occurrence metadata	Page command	`\currentregisterpageuserdata`

4. Conceptual map

occurrence
    |
    +--> register instance
    +--> entry
    +--> sorting key
    +--> displayed form
    +--> hierarchy
    +--> processor
    +--> userdata
    +--> page reference
              |
              v
        register collection
              |
              +--> sorting
              +--> duplicate handling
              +--> reference aggregation
              |
              v
           placement
              |
              v
     final index or register

5. See also

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

References notes and floats/Registers and index/Glossary

Glossary of index and register terms

1. Glossary entries at a glance

2. Glossary

A

Alphabetic group

Authority data

C

Canonical entry

Column balance

Complete register

Compression

Cross-reference

D

Displayed entry

Displayed form

Duplicate handling

E

Entry

Entry identity

Entry level

F

First-level entry

Formatting

G

Generated command

Group indicator

H

Hierarchical entry

Hierarchy

I

Index

Index entry

Indexing

K

Key

L

Locator

M

Main entry

Main reference

Merge

Multiple registers

N

Named register

Number of columns

O

Occurrence

Occurrence command

P

Page command

Page range

Page reference

Placement

Preferred term

Processor

Project environment

R

Range tag

Reference

Reference aggregation

Register

Register collection

Register heading

Register instance

Register layout

S

Second-level entry

See reference

See-also reference

Sorting

Sorting form

Sorting key

Structured register data

Subentry

U

Userdata

X

XML occurrence

3. Functional map