Skip to content

Instantly share code, notes, and snippets.

@eropple
Created December 19, 2025 17:26
Show Gist options
  • Select an option

  • Save eropple/8289bce828b91b1f803f2da2bcada15f to your computer and use it in GitHub Desktop.

Select an option

Save eropple/8289bce828b91b1f803f2da2bcada15f to your computer and use it in GitHub Desktop.

Definitions

Standard terminology for the book indexer system. Terms align with ISO 999:1996, Chicago Manual of Style, and ASI best practices.

Core Structural Terms

Entry The complete unit in an index. Contains a heading, zero or more subentries, zero or more locators, and zero or more cross-references. An entry must have at least one locator OR one cross-reference.

Heading The text term that names an entry. A noun or noun phrase. The heading is what readers look up alphabetically. Also called "headword" in some sources.

Subentry A child entry nested under a parent entry. Has its own heading, locators, and optional cross-references. Represents a more specific aspect of the parent concept. Subentries can have their own subentries (sub-subentries), but convention limits depth to 3 levels.

Locator A reference to where content appears in the source text. The term is intentionally broader than "page number" to accommodate different reference types.

Locator Type Example Description
page 45 Single page reference
page_range 45-48 Contiguous pages discussing the topic
footnote 45n, 45n3 Footnote on a page (optionally numbered)
figure fig. 12 Reference to a figure
table table 3.1 Reference to a table
chapter ch. 3 Chapter-level reference

Cross-Reference Terms

Cross-reference A link between entries. Points readers from one term to another. Two primary types exist.

See reference Directs the reader from a non-preferred term to the canonical term. The entry with a See reference has no locators of its own — all information is under the target entry.

Labor unions. See Unions, labor

See also reference Points to related entries with additional information. Appears after locators. The current entry has its own content; the target has supplementary content.

Labor unions, 45-47, 112. See also Worker rights

See under / See also under Variants that clarify hierarchical position. Used when the target is a subentry rather than a main entry.

Organized labor. See under Unions

Structural Relationships

Double posting Creating multiple access points for the same concept under different headings. Both entries have identical locators. Increases discoverability.

Design, furniture, 223
Furniture design, 223

Flipped entry A form of double posting where word order is inverted.

African Americans, business ownership, 247-248
Business ownership, African Americans, 247-248

Hierarchy

Index entries form a tree structure:

Entry (main heading)
├── Locator(s)
├── Cross-reference(s)
└── Subentry (subheading)
    ├── Locator(s)
    ├── Cross-reference(s)
    └── Sub-subentry (rare)
        └── Locator(s)

Maximum conventional depth: 3 levels (entry → subentry → sub-subentry).

Rendering Terms

These terms describe output format, not data structure. Included for completeness.

Indented style Subentries appear on separate lines with visual indentation.

Democracy, 12
  Athenian origins, 45-47
  modern challenges, 203-210

Run-in style Subentries follow the main heading on the same line, separated by punctuation.

Democracy, 12; Athenian origins, 45-47; modern challenges, 203-210

Data Model Implications

Core entities for the system:

Entity Contains Relationships
Entry heading, justification has many Subentries, Locators, CrossReferences
Subentry heading, justification belongs to Entry, has many Locators, CrossReferences
Locator type, value, justification belongs to Entry or Subentry
CrossReference type (see/see_also), justification belongs to Entry or Subentry, references target Entry

Justification fields support the success criteria requirement for human-readable explanations of each decision.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment