Look For
How do I Why can't

How do I stop the stemming in localized Guides?


Apple Guide Complete claims (on page 3-14) that Apple Guide stems words only if the <World Script> command is either absent or set to 0, 0. But when you try to include <World Script> 0, 7 for Swedish and <World Script> 0, 4 for Italy, AG continues to stem words (converting "opzioni", for example, to "opziony").

To get AG to not stem words, you need a localized version of Apple Guide that doesn't have the stemmer in it. A good place to start would be the Apple Guide International Versions Web page.

Why can't Look For find an index entry?


The success of a Look For search depends upon the interaction of four elements: the Ignore command, the Synonym command, the Exception command, and Apple Guide's built-in (English) stemming rules. ["Stemming" is what Apple Guide does to try to get to the root form of a word or words before it trys to match it to an index term.]

Check Apple Guide Complete, pages 3-12 to 3-14, and Real World Apple Guide, page 114, for specific stemming criteria.

For example, in the absence of any <Ignore>, <Exception>, or <Synonym> commands, Apple Guide stems "opening" to "open". To enable all variations of the stemmed form (such as "open", "opened", "opens", "opening", and "opener"), add this line to your Guide Script source files:

<Synonym> "opening", "open"

With this synonym in place, the various forms of "open" will match the index term "opening".

If you choose, you can even anticipate misspelled words. For example, the term 'maintenance' is stemmed to "mainten". If you add these synonyms--

<Synonym> "maintenance","mainten"
<Synonym> "maintenance","maintan"

--a search on either "maintenance" or "maintanance" would be successful. Talk about service!

Note: If your Guide uses mixins, make sure that the mixins are located in the proper location. If you then open the main Guide (to which your mixin is attached), Guide Maker will take the mixin's index modifications into account.

An outline of Look For's search algorithm

When the user types a search phrase, Apple Guide

  1. checks through its Ignore List to see if any of the words are on the Ignore List.
  2. checks the Exception List, to determine whether or not to stem any word(s). For example, if "opening" was not listed as an Exception, Apple Guide would stem "opening" to "open".

    Note: Exceptions apply to single words only.

  3. looks for synonyms for the whole phrase. If AG finds a synonym, the synonym replaces the original phrase.
  4. looks for the result of the previous steps in your Index. If a match is found, the search ends and the results are displayed.
  5. checks the Synonym list for each word in the phrase if step 4 came up empty. If the keyword(s) are defined as synonyms, and the synonym matches a corresponding term in the index, it displays that index term and associated Topics.

A simple example
Using the term "programmers" as an example, here is an outline of how an Apple Guide index entry could be created.
  1. Do not <Ignore> "programmers". This <Ignore> command would shut "programmers" out of your Look For search entirely.
  2. Determine what stem Apple Guide will use in its search. In this case, the parsing engine will reduce "programmers" to "programm" (yes, that's with two "m"s).
  3. Create a <Synonym> linking "programm" to the index term "programmers":

    <Synonym> "programmers", "programm"

Since you've defined a <Synonym>, you don't need an <Exception> in this example. However, instead of performing steps 2 and 3 above, you could create an <Exception> to prevent the desired word from being stemmed:

<Exception> "programmers"

This <Exception> strategy isn't recommended though--it'll handle this one case, but none of the variations. The first strategy--creating a <Synonym> linking the stemmed form of the index term to the actual index term--almost always gives better results.

A slightly more complex example

In this example, the index of the Guide file contains these commands:

<Index> "Using the CD ROM Drive"
  <Header> "How do I"
    <Topic> "Insert a CD"
    <Topic> "Use a CD"
    <Topic> "Listen to Audio CDs"

If the user types "How do I start using my Audio CD" in Look For's search box and clicks Search, it kicks off the following sequence of events:

  1. AG searches the Index for "How do I start using my Audio CD", which it doesn't find. AG then checks the Look For file which contains:

    <Ignore> "How"
    <Ignore> "Do"
    <Ignore> "I"
    <Ignore> "my"
    <Ignore> "start"

    <Synonym> "Using the CD ROM Drive", "Audio CD"
    <Synonym> "Using the CD ROM Drive", "Using Audio CDs"
    <Synonym> "Using the CD ROM Drive", "Music CD"

    <Exception> "Using"
    <Exception> "Playing"
    <Exception> "Exiting"

  2. Since "How", "Do", "I", "my, and "Start" are on the Ignore List, they are removed from the search.
  3. AG searches the Synonyms List for "Using Audio CDs".
  4. The term "Using the CD ROM Drive" matches "Using Audio CDs" in the Index file.
  5. The Index term "Using the CD ROM Drive", and its associated Topics, is then displayed in the Look For search results list.

Double-checking your searching procedure

If you intend to rely on Look For to work its magic on a considerable number of index entries, it is best to test your compiled Guide with Guide Maker's Test Look For utility. Test Look For shows you how Apple Guide goes about analyzing search phrases. Try typing each index term into Test Look For to see how Apple Guide stems the phrase, then set up a synonym for each.

For more information on Guide Maker's Test Look For utility, see Apple Guide Complete, pages 6-8 through 6-12.


© 1997, guideWorks, LLC -- Last updated: 970325 GPB