A Guide to WebWorks Help 5.0 Search Settings

Last Modified: October 26, 2006

ePublisher Pro

The purpose of this article is to explain the WebWorks Help 5.0 search engine and the user-defined settings for customizing search results.

We use a third-party search engine to compile and return search results in WebWorks Help 5.0 output. However, there are several markers you can add and XML files you can modify to get the search behavior you’re looking for in your particular project.

How does it work?

The Search function of WebWorks Help 5.0 searches an index of words compiled from all topics in a book (or over several books in a merged help set). It assigns a value to each match according to where in the document the matching word or phrase is found. By default, the highest values are given to matches from keyword markers and main headings. Smaller values are assigned to lower-level headings and body text. After adding the match values for each document, it assigns rankings based on how each topic's score compares to the highest score returned.

Table 1: Default Search Weights
Document Element	Search Score
Keyword marker	100
Document description	50
Document summary	50
Docunent Title	20
Heading1	15
Heading2	10
Caption	10
Heading3	7
Table Heading	5
H4	4
H5	4
H6	3
H7	2
All others	1

For example, a user searches for the string "media playback". The search returns the following matches for either "media" or "playback":

TopicOne - 1 title, 2 heading1, 3 body, 2 heading3

TopicTwo - 1 keyword, 3 heading1, 6 body

TopicThree - 2 heading1, 3 heading3, 11 body, 1 caption

According to the default scoring weights, TopicOne would score 67 (20+ 30 + 3 + 14). TopicTwo would score 151 (100 + 45 + 6). TopicThree would score 72 (30 + 21 + 11 + 10). Therefore, the rankings (percentages of the highest score) would display to the user as:

1. TopicTwo - 100%

2. TopicThree - 48%

3. TopicOne - 44%

That's the basic principal behind the search logic. You can configure the behavior of the search function (including adding or adjusting score values) by performing a format or target override on a file located in the ePublisher Pro installation directory here:

Formats\WebWorks Help 5.0\Transforms\wwhelp_files.xml

That file also contains some more notes and information on the variables you can change to achieve the desired results.

Also, you can add increased functionality to your searches by defining search synonyms, which will score matches when a similar word or phrase is encountered.

For information on performing project target overrides, please see Creating Project Target Overrides.

Keyword Markers

You can increase the search score of a particular article by inserting markers containing the most relevant search terms for that topic. This will ensure that when a user searches for a particular word, your designated topic will appear higher in the list of results. Follow these steps:

1)	In your FrameMaker document, create a new marker called “Keyword.”

2)	Insert a new Keyword marker anywhere in your topic.

3)	Add keywords to the marker text that will have the most relevance to the particular article in a text search. Separate terms with a comma.

4)	Insert the marker and save your document.

5)	In your ePublisher Pro project, scan the document(s).

6)	In the Style Designer, ensure the Marker type value for the Keyword marker is set to “Keywords.”

7)	Regenerate output to apply the changes.

Synonyms

By defining a list of synonyms, you can increase the effectiveness of a search by grouping similar words together as a single result. For example, you define movie, video, and avi as synonyms. If a user searches for one of those terms, a match will be scored if any of the three are found in a document.

To add these definitions, you’ll need to perform an override on a file called synonyms.xml, located by default in the ePublisher Pro installation directory here:

\Formats\WebWorks Help 5.0\Files\wwhdata\common\

Once the file is copied to the correct location in your project directory, open it in any text- or XML-editing application (e.g., NotePad), and add entries to the <WebWorksSynonyms> section. For example, your synonyms might look like this:

</Word>

</Word>

</WebWorksSynonyms>

The Synonyms feature does not recognize multiple word values or synonyms. And, it ignores words (and synonyms) of 2 letters or less. Also, its search logic is quite literal. That is, it finds only what you type, and only if the exact form is in the text. For example, it does not find plurals or phrases, and it even includes punctuation.

Minimum word length & common words

When performing a text search, the WebWorks Help 5.0 search engine follows a couple of guidelines designed to make the search more efficient and the results more helpful. By default, the minimum length of a word in the search results is 3 letters. ePublisher Pro also comes with a list of terms which appear commonly in many types of documents, and are therefore left out of search results. You can modify both the minimum length and the list of common words by performaing a target override on a file called locales.xml, located by default in the ePublisher Pro installation directory, here:

Formats\Shared\common\locale

Note: For tips on performing the override, see Creating Project Target Overrides.

Note: Because this file is in the Shared formats directory, your project folder hierarchy should look like this:
MyProject\Targets\MyWWHelpTarget\Shared\common\locale

Minimum length

To change the minimum number of letters in a WebWorks Help 5.0 search result:

1)	Open locales.xml in an XML- or text-editing application (e.g., NotePad).

2)	Find the Locale used by your project (default English is “en”).

3)	Under the `<Search>` section, change the `MinimumWordLength` value to the desired number of characters in the shortest word the search should return.

Common words to skip

To change the list of words which will not be returned in a WebWorks Help 5.0 search:

1)	Open locales.xml in an XML- or text-editing application (e.g., NotePad).

2)	Find the Locale used by your project (default English is “en”).

3)	Under the <Search> section, modify the <StopWords> values to reflect the list of words which should not appear in your project’s search results.

XHTML 1.0 CSS WAI-A