Understanding the distinction between main entries and subentries in an index is crucial for creating an organized and navigable index in DITA documentation.

Main Entries

Main entries in an index represent primary terms or concepts that users are likely to search for when seeking information. These entries typically appear at the top-level of the index and serve as headings or anchors for related subentries. Main entries are the primary access points to the content and are usually listed alphabetically. They provide a high-level overview of what topics or information can be found in the documentation.

Subentries

Subentries, on the other hand, are more specific terms or concepts related to a main entry. They provide detailed, granular access points to specific content within the documentation. Subentries are typically indented under their corresponding main entry, creating a hierarchical structure. This hierarchical arrangement allows users to navigate through the index efficiently, starting with a main entry and then drilling down to find precise information. Subentries can also be listed alphabetically under the main entry they belong to.

Example:

Here’s an example in DITA XML format illustrating the difference between main entries and subentries in an index:

<index>
  <entry term="Installation" loc="ch01_installation.html" />
    <subentry term="System Requirements" loc="ch01_requirements.html" />
    <subentry term="Step-by-Step Guide" loc="ch01_guide.html" />
  <entry term="Configuration" loc="ch02_configuration.html" />
    <subentry term="Basic Settings" loc="ch02_basic.html" />
    <subentry term="Advanced Settings" loc="ch02_advanced.html" />
</index>

In this example, “Installation” and “Configuration” are main entries, serving as the primary access points. Under “Installation,” there are subentries such as “System Requirements” and “Step-by-Step Guide,” providing more specific details related to installation. Similarly, under “Configuration,” you have subentries like “Basic Settings” and “Advanced Settings,” offering detailed configuration options.