Website Deliverables - webworks.com Previous Next Index Print
A Guide to WebWorks Help 5.0 Search Settings

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":

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.

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:

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.

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:

<WebWorksSynonyms>

<Word value="movie">

<Synonym value="avi" />

<Synonym value="video" />

</Word>

<Word value="picture">

<Synonym value="image" />

<Synonym value="graphic" />

<Synonym value="photo" />

</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).

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).

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.