Making an Index With Elko

Creating an index in Elko is a four-step process:

import a set of index terms and synonyms
build a preliminary index based on this list, by having Elko search the guide for sequences that contain each term
check the index both manually (adding and deleting sequences from the index based on the indexer's judgment, creating ignore and exceptions lists) and automatically (removing inconsistencies such as having an index term repeated as a synonym)
export the information in the stack as a ready-to-compile Index/Look For source file.

Importing

To start the indexing process, you create a list of terms in a text file, with each term on a separate line, and any synonyms separated by commas:

  index term,synonym,another synonym,still another synonym
  another term
  still another term,a synonym

Then open the Elko Index stack and click Import. (You can import as many files as you want.)

When you import a set of index terms, Elko creates a card for each term, with a field for sequences that will become entries for that term. All the terms you've imported are listed in the scrolling list; to see the entries for a term, click it.

Building

During the Build process, Elko searches the Panels and Sequences stacks for occurrences of the index term and its synonyms, and lists each sequence it finds on the index term's card.

You can add or delete synonyms for any term manually, before you build the index. During the build stage, Elko looks for sequences containing the synonyms, as well as sequences containing the index term itself. For example, if you have an index term called "background" with the synonym "desktop", Elko indexes all sequences whose panels contain the word "desktop" as entries under "background".

Index checkboxes screenshot (3.5K) You can also specify sequences you don't want indexed (such as Oops sequences) with the two checkboxes on the first card of the Index stack. The first checkbox causes Elko to ignore sequences whose names start with "Oops:", "Auto Open:", or "Subsequence:". The second checkbox causes Elko to ignore sequences you've marked. (You can mark a sequence by going to its card in the Sequences stack and clicking the checkbox in the upper-right corner.)

When you're satisfied with the index terms and synonyms, go to the first card and click Build. This triggers Elko to search all panel content. When Elko finds a panel whose content contains an index term or one of its synonyms, it puts the sequences that use that panel into the Sequences field for that index term, making them index entries for that term.

Elko asks you whether you want to export the current index at the start of the build, and import an old index at the end, so you can compare the old index with the new one. This can be helpful if you've added or deleted sequences manually after a previous build, or if you want to compare the automatic indexing to the results of an existing text index. Elko indicates the comparison with a character in the left-hand column of the Sequences field. If the column is blank, the sequence was found by the automatic indexer, but didn't appear in the old index. If it contains an asterisk (*), this sequence appeared in the old index, but wasn't found by the auto-indexer. If it contains a bullet, the sequence was in the old index and also was found by the auto-indexer.

If your guide is a mixin, Elko asks whether you want to create a card for each term in the main guide's index. In this case, Build searches your guide for the main guide's index terms, as well as the new terms you imported for the mixin. You can also search the main guide for index terms that are newly defined in your mixin. For any of this to work properly, the Elko folder for the main guide must be in the same folder as the Elko folder for your mixin. If you don't have the Elko folder for your main guide, you can index your mixin, but you won't be able to index under terms that are in the main guide, or index the content of the main guide.

Checking

The list of entries generated by Elko's simple search should be considered a rough draft, at best, of the eventual index - not as a final list. Before you export your index as a source file, you should review each index term's entries.

When you go to an index term's card, you see the list of sequences Elko found for that term. The left-hand column indicates with a bullet whether the sequence will be included in the final index file. You can mark a sequence for inclusion in the index, or exclude it, by clicking the sequence name and then clicking Include or Exclude (or by clicking in the left-hand column). To include or exclude a set of sequences, shift-click or shift-drag to select the set you want, then click Include or Exclude. The Delete button removes a sequence completely from the list; use it to remove clutter if you've decided you definitely do not want to include the selected sequence. Select a sequence and click View to open the sequence's card.

Checking the index is straightforward. For each index term, look at the list of sequences, exclude any that should not be in the final index, and use the Add button to include sequences the automatic indexer missed. If you want an index term to be invisible - available as a Look For term but not in the index itself - check "Exclude this term from index" on that term's card. Finally, make sure the synonyms for each index term are appropriate.

The ignore (stop-words) list can be entered manually by clicking the Ignore List button on the first card. Type the words you want Look For to ignore when the user types them, and click the button again to hide the Ignore list. The Exceptions List works the same way.

When you're satisfied with the entries for each index term, use the Check button to do last-minute automated sanity checking. Check makes sure that:

there are no conflicts between index terms and synonyms (and, if the guide is a mixin no conflicts between terms in your mixin and terms in the main guide)
the Ignore list doesn't contain any of your index terms or synonyms
each eligible sequence appears under at least one index term, and each index term has at least one sequence.

Use the Check button immediately before exporting your index as a GuideScript source file to catch any last-minute problems.

Exporting

When you're finished checking your index and are satisfied with it, click Export. Elko asks for a file name, then creates an Index and Look For file in text format. These files are ready for use by GuideMaker, and can be included in your build file ("Main") and compiled as-is.

Jeanne A. E. DeVoto jaed@jaedworks.com