Legacy Document

Inside Macintosh: Apple Guide Complete / Part 4 - Scripting Guide Files

Chapter 10 - Guide Script Command Reference / Guide Script Command Descriptions

/ Specifying "Look For" Help

<Synonym>

You can use the <Synonym> command to specify a synonymous term for an existing index term. Apple Guide uses the synonym list when parsing a search phrase.

<Synonym> indexTerm, synonym

indexTerm

A text string that specifies an existing index term.

synonym

A text string specifying a word or phrase that is synonymous with the index term specified in the indexTerm parameter.

DESCRIPTION

After a user enters a phrase in the search phrase entry box and clicks Search, Apple Guide parses it. After removing any words specified by <Ignore> commands and, except for words on the exception list, stemming common word variations to a root word, Apple Guide examines the list of synonyms for the phrase. If the phrase is a synonym specified by a <Synonym> command, Apple Guide replaces the synonym with its equivalent index term and searches for the phrase in the list of index terms. (Note that at this point in the search, Apple Guide searches the list of index terms only if it found the phrase on the synonym list.)

If Apple Guide does not find the phrase in the synonym list, then Apple Guide looks in the synonym list again, this time for each word in the parsed phrase. If Apple Guide finds a word on the synonym list, it replaces the word in the phrase with its equivalent index term. Apple Guide then looks in the index for a term matching the parsed phrase (this time any words that are synonyms have been replaced by their equivalent index terms). If Apple Guide finds a match for the phrase, Apple Guide displays the topics for the index term. If it does not find the phrase in the index, Apple Guide searches the list of index terms for each word. If Apple Guide finds a matching index term for more than one word in the phrase, Apple Guide intersects the results and displays any topics that are common to both words.

By using <Synonym> commands, you can increase the likelihood that the search phrase entered by the user will match an index term. For example, you can use a <Synonym> command to specify that the index term "copying" has a synonym "duplic" (which is the stemmed form of the word "duplicate"). In this case, when the user enters the search phrase "duplicate" Apple Guide stems the word to "duplic", finds "duplic" on the synonym list and replaces it with "copying", then looks in the index for a term matching "copying".

If Apple Guide finds a match, it displays the topics associated with the index term.

SPECIAL CONSIDERATIONS

Apple Guide first looks in the synonym list for the reduced phrase, and only later (if necessary) looks for each word in the synonym list. For example, using the synonym list shown in Examples, if the user enters the phrase "How do I open a file and print it?", Apple Guide parses this search phrase to "open file print" and looks for this phrase in the synonym list. Apple Guide does not find this phrase in the synonym list. Note that in this case Apple Guide does not replace "open file" with "opening" because Apple Guide looks in the synonym list for the entire phrase, not for phrases within the phrase.

Because the phrase "open file print" isn't in the synonym list, Apple Guide looks in the list again, this time for each word ("open", "file", and "print"). The word "open" is a synonym (for "opening"), "file" is a synonym (for "documents"), and "print" is a synonym (for "printing"). After replacing each word with its equivalent index term (if any), the parsed phrase becomes "opening documents printing". Apple Guide looks in the index for this phrase, and in this example, does not find an index term for the phrase. So Apple Guide looks in the index for each word in the phrase and displays the intersection of the result.

If no topics are common to both words, Apple Guide instructs the user to narrow the search. For example, the user might narrow the search to "How do I open a file?" In this case, Apple Guide reduces the phrase to "open file" and does replace the phrase with its equivalent index term, "opening".

Note that for a multi-word index term that contains one or more words that are synonyms, you need to create a synonym which is an exact equivalent of the index term. For example, assume the synonym list is as shown in Examples. Because this list doesn't include a synonym for the index term "file server", when the user enters this phrase Apple Guide looks in the synonym list for the entire phrase. If it fails to find a synonym for the entire phrase, it looks in the synonym list for each word, replacing "file" with "documents". Apple Guide then looks in the index for the phrase "documents server". If it fails to find the phrase in the index, it then looks in the index for each word and intersects the results. Thus, as demonstrated in this example, Apple Guide will not report a successful search for the phrase "file server". Therefore, you must create a synonym which is an exact equivalent of the index term

<Synonym> "file server", "file server"

In summary, you only need to create a synonym that is an exact equivalent of the index term if the index term contains multiple words, and one or more words in the phrase are synonyms for other index terms.

EXAMPLES

#specify words that are synonymous with existing index term
#specify an existing index term, then the synonym
<Synonym> "copying", "clone"
<Synonym> "copying", "duplic"
<Synonym> "copying", "copy"
<Synonym> "copying", "Copy command"
<Synonym> "deleting", "Clear command"
<Synonym> "deleting", "cut"
<Synonym> "deleting", "Cut command"
<Synonym> "deleting", "delet"
<Synonym> "deleting", "delete"
<Synonym> "deleting", "get rid"
<Synonym> "documents", "docum"
<Synonym> "documents", "file"
<Synonym> "memory", "RAM"
<Synonym> "memory", "memory available"
<Synonym> "opening", "double click"
<Synonym> "opening", "open"
<Synonym> "opening", "Open command"
<Synonym> "opening", "open file"
<Synonym> "opening", "execute"
<Synonym> "opening", "run"
<Synonym> "Page Setup", "landscape"
<Synonym> "Page Setup", "landscape print"
<Synonym> "Page Setup", "page format"
<Synonym> "Page Setup", "Page Setup command"
<Synonym> "Page Setup", "paper size"
<Synonym> "Page Setup", "portrait"
<Synonym> "Page Setup", "printer choice"
<Synonym> "Page Setup", "printer option"
<Synonym> "Page Setup", "print choice"
<Synonym> "Page Setup", "print option"
<Synonym> "pop-up menu", "pop up"
<Synonym> "pop-up menu", "pop up menu"
<Synonym> "pop-up menu", "popup"
<Synonym> "pop-up menu", "popup menu"
<Synonym> "printer drivers", "print driver"
<Synonym> "printer drivers", "print software"
<Synonym> "printer drivers", "printer driver"
<Synonym> "printer drivers", "printer software"
<Synonym> "printing", "print"
<Synonym> "printing", "printer"
<Synonym> "printing", "print file"
<Synonym> "printing", "print window"
<Synonym> "printing", "Print command"
<Synonym> "printing", "ImageWrit"
<Synonym> "printing", "LaserWrit"
<Synonym> "printing", "spool"