Chapter 1. General Indexing Guidelines

This page lists a few specifics about the things we like to see in O’Reilly indexes.

O’Reilly Index Don’ts

  • Don’t use any styles (no bold, no italic, etc.). The only exception is our (continued) jump heads, which we include in Frame and InDesign books. These are usually added by the production editor.
  • Don’t add a secondary entry when the primary entry doesn’t have a locator.

    • Do this:

      vector files, defined 26
    • Not this:

      vector files
          defined, 26
  • Don’t alphabetize according to "connecting" terms.

    • Do this:

      passwords
          options, 42
          PPP connection and, 37
          for printer access, 456 <- Good!
          specifying, 1142
          writing scripts for, 517
    • Not this:

      passwords
          for printer access, 456 <- Bad!
          options, 42
          PPP connection and, 37
          specifying, 1142
          writing scripts for, 517

O’Reilly Index Dos

  • Use a maximum of three levels for index entries.
  • Use curly quotes when quotation marks need to appear in an index entry.
  • Place see references in parentheses, on the same line as its subject:

    computers (see desktop computers)
  • Separate two sees with a semicolon:

    accounts (see user accounts; special accounts)
  • Set see also references as the last subentry:

    filesystems, 12, 24, 84
      administering, 161-165
      Windows XP, 223
      (see also partitions)
  • Use an en dash to show a range of pages, but only for topics that span three pages or more, like this:

    exceptions, 14-25
  • List only the first page for a topic discussed on two consecutive pages:

    object persistence, 194
  • When necessary, use "connecting words" to clarify index entries:

    passwords
      options, 42
      PPP connection and, 37
      for printer access, 456
      specifying, 1142
      writing scripts for, 517
  • If an acronym is the main entry, follow it by the name written in full in parentheses. Then, use the name written in full followed by the acronym in parentheses as a see reference:

    FTP (File Transfer Protocol), 198, 257
    File Transfer Protocol (see FTP)
    DNS (Domain Name System), 16, 89, 101
    Domain Name System (see DNS)
  • If the entry has only one line’s worth of locators, remove the see reference:

    central processing units (CPUs), 127
    CPUs (central processing units), 127
  • Place symbols in the "Symbol" portion of the index (it is preferable to index them in the order in which they’re spelled out). Where appropriate, describe how they are used:

    Symbols
    & ampersand, 39
    . dot, 45
    colon, 82, 296
    A
    ampersand (&), for background operation, 39
    C
    colon (:) in search path, 82, 296
    D
    dot (.) in filenames, 45

Indexing the Preface and Appendixes

If the preface just includes the standard O’Reilly boilerplate stuff (a short intro, Using Code Examples, How to Contact Us, Acknowledgments, etc.), there is no need for you to index it. But sometimes an author will include some important material that is worth indexing. Appendixes function in a lot of different ways. If an appendix is just a list of reference material, it is probably not worth indexing.

In both cases, the decision is up to you, the indexer. You can review the frontmatter and appendix and make a determination. If you’re unsure about a particular preface or appendix, you can always ask the production editor. Because you are taking the time to review those pages, we consider them "indexable" and therefore you should charge us for them regardless of whether you insert index markers or not.

Page Breaks in the Index

Some of the following rules may be jettisoned in a tight-signature scenario:

  • A group letter head should not be followed by a single entry at the bottom of a column.
  • Similarly, individual one-line entries can’t be orphaned at the end of an entire letter group.
  • Within any block of entries and their subentries, no single subentry can be orphaned on its own column or page.

    • Wrong:

      entry
          subentry
      ----------------------------
          subentry
          subentry
          subentry
      entry
    • Wrong:

      entry
          subentry
          subentry
          subentry
      -----------------------------
          subentry
      entry
    • entry
          subentry
          subentry
      ---------------------------
          subentry
          subentry
      entry
  • For entries that straddle pagebreaks, a “(continued)” line must appear at the top of the new page (verso pages only).
  • Parenthetical statements are stripped from continued lines, e.g., “& (bitwise AND) operator” becomes “& operator (continued)”.
  • Continued lines should reflect nested entries: “entry, subentry (continued)” – optional if this results in a two-line continuation.
  • Line breaks should not occur between the end of the entry text and the first page number, especially when the result is a single orphaned page number.
  • Page ranges (separated with en dashes) can’t be interrupted by line breaks.
  • Line breaks may not appear within an overly long entry, even if it runs onto 4 lines.
  • If more than two-thirds of one column’s worth of material fills the last page of the index, even out the bottom edges as much as possible. If the two columns cannot be the same height, make the first column slightly higher than the second. (As much as possible, try to make sure columns are balanced in this manner throughout the index.)