PicoSearch FAQ: File Promoting

PicoSearch is primarily an unbiased search engine for finding the exact text and keywords on your website. PicoSearch will report its results in a natural priority ordering, but at times you may wish to help certain URLs to come out on top in your search results. The facility for doing this is called Promote and Demote, and for examples on when to use this, see the What's New announcement that was made when this first came out.

Promotions are easy to use, but we do present here the full instructions so you will understand the possibilities for this powerful feature.

Triggering a Document: To be able to push a URL to the top in the results page, it first has to be visible as a legitimate search result. If you need help in triggering a document to appear at all for a given search, see the FAQ How can I influence the outcome of a search? If you need to make sure the result is visible on the first page so it can then become promoted, increase the "Resuts per Page" setting and/or set the "Maximize Promotion scope", both in your account manager's Promotions options.

Account Manager Controls: The master control for promoting and demoting search results is in the Ranking Options of your account manager, under the Designing topics. There you will find a selector for how many results to show per page, plus the master view box for all of your promotions and demotions. The results per page defaults to 10, but you can set it higher if you need to bring in more URLs for your promotions to act upon.

The Entry Box: The master view box under the Ranking Options is an input for promotions when you want to type in more patterns, but it also acts as a display output for the status of all Promotes and Demotes, including those found by PicoSearch in tags on your documents. Each time you index, all of the promotions from your documents are condensed and redisplayed in this view box. You can thus promote documents from either the account manager's input box, or from HTML tags inserted directly into your documents. You will always be able to check on your accumulated promotional commands in this control panel view. (This is similar to how Partitions work from both typed entries and document tags, seen in one central control area.)

To add your own comments to your promotions input, precede a comment line with either #COMMENT# or . For example:

#COMMENT# this is a promotions comment
<!-- this is another promotions comment

Promote and Demote: There are two ways to promote or demote a document, either (1) from an HTML tag in the document or (2) from a typed entry in your account manager's Promotions and Demotions feature. When you promote from within a file using an HTML tag, you are only promoting that file, so there is no wildcarding within the URL. But from the entries in your account manager, you can promote or demote entire directories as well as specific files, because the URL is a pattern that only has to match left to right. The URL patterns can even contain explicit wildcarding to match different sites or subdirectories, by placing an asterisk character within the pattern and before the ending. But a $ at the end will force the ending to match exactly.
    Thus, http://www.mysite.com/mydir/ will match any file in the top mydir directory, whereas */mydir/ will match any file in any mydir directory. */mydir/$ will match only the index.html files of mydir directories, assuming that PicoSearch found the links with an endslash only, and not as index.html or no endslash at all. Since index.html files are the HTML default and could be seen several ways, you can always check your List Of Documents to know exactly how PicoSearch found those kinds of links, or else make the patterns to catch all possibilities.
    Promotions can work in general (for any search that brings up that document), or for just a keyword. And a demotion is really just a negative promotion, with matching URLs get shoved to the bottom of the results page. In addition to single words, keyword promotion can be for a phrase or a pattern, so that run* would cover run and running (you would still need ran as another word). See below for more details.

Types and Priority: Promotions offer you precise control for the prioritizing of your search results. First of all, there are three types of promotions which get applied in a certain order. Then within each promotion type, there is absolute order sensitivity, that is, the order of your promotion listing in your account manager is the order of promotion (first comes first, second comes second, etc.). The three major types are: Wildcard Promotions, which are super wildcards in the sense of having a star in front of them, and they supersede Word Promotions which are keyed to specific word(s), which supersede General Promotions which just state the URL. You can mix the three types in your promotions list, and the three types will be applied sequentially. Then if URLs are competing within the same type, the exact order will be the order as you have listed.
    So for example, if your site is organized with two different priority directories in addition to all other files, then you could use General Promotions to put */first_priority_files/ before */second_priority_files/ by listing in that order in the Entry Box (then Word and Wildcard promotions would still be able to reorder that order!), or you could have the final say by using Wildcard promotions to list *=*/first_priority_files/ before *=*/second_priority_files/. In both cases the URL itself has a wildcard pattern explicit within it, so the promotion will not only match any files in top directories, but also any subdirectories that have this first and second priority naming scheme. It's a complicated example we know, so don't worry about it unless it interests you, and above all, just feel free to experiment for yourself.

Wildcard Promotions: A wildcard promotion comes above all other promotions. It is like a word promotion but the word is a star. It can be entered from the entry box, or in a file by using an HTML tag that has no words.

Word Promotions: A word promotion is a promotion that will happen on a specific word or word pattern, for a specific file (if done from that file with an HTML tag) or a file group (if done from the entry box). This is quite flexible since the word can be a keyword or phrase (words with spaces between, no quotes needed), and there can be two kinds of wildcard. A * means any number of optional non-space characters, while a ? means only one optional non-space character. Thus, run? will match run or runs, but run* will match run, runs, or running. Be conservative and consider what your users will probably be searching for on your site, since run? also matches runt, and run* also matches runway.
A word promotion comes above general promotions. At indexing time, if there are word promotions for a specific file both in the entry box and the file's HTML, the file's HTML tags are considered more direct and will replace the entry box's promotions just for that file. This way, each time you index you are getting the freshest accumulated promotions.
TIP: Paid accounts have options to minimize the width and number of concordance lines generated, but word promotions work best with a good amount of concordance (turning off the display of concordance is harmless though since that's not the same as minimizing the generation of concordance).

General Promotions: A general promotion has no words associated with it, and cannot be done with an HTML tag. When you do a general promotion from the entry box for a file pattern or directory, this is the weakest promotion, in the sense that any promotion for a specific word or word pattern will come above it.

HTML Tag Promotions: Here are the possibilities for promoting within the HTML of a file. A few basic examples are given, and you can experiment for variations. The tags can be inserted anywhere in the file, since they are processed at indexing time; it's probably best for you to keep them together at the top, in the header.
Note: when a file tag promotion is found, it is inserted into your account manager's promotions display box with a double equals sign, ie. ==. This shows you which promotions came from files, and the order that they will get applied. The == promotions of HTML tags will be discarded and refreshed each time you reindex, so while they are convenient from file maintenance, they don't give the kind of hands-on ordering control that comes from you directly listing promotions in your account manager. Use whichever method works best for your situation.

: This creates a wildcard promotion (the most powerful kind) for the file it is found in. Anytime this URL comes up in a search, it will be on top.
: This creates a wildcard demotion (the most powerful kind) for the file it is found in. Anytime this URL comes up in a search, it will be pushed to the bottom.
: This creates a word promotion for the file it is found in. Anytime this URL comes up in a search because of this word being searched and found within, it will be pushed to the top. A word demotion is also possible by saying PICODEMOTE.
: This creates word, phrase, and stem promotions respectively for the file it is found in. Anytime this URL comes up in a search for word, "the phrase", or any word beginning with 'stem', the URL will be pushed to the top. You can string lots of words and patterns together, so long as they are separated by commas.
TIP: Paid accounts have options to minimize the width and number of concordance lines generated, but word promotions work best with a good amount of concordance (turning off the display of concordance is harmless though since that's not the same as minimizing the generation of concordance).

Entry Box Promotions: Here are the possibilities for typing promotions into the account manager's promotions entry box. A few basic examples are given, and you can experiment for variations.

http://www.mysite.com/filename.html: This creates a general promotion (weaker than specific word promotions but potentially quite wide) for the file that is listed. Anytime this URL comes up in a search, it will be pushed up to the top. The matching is really just a complete left-to-right pattern, so you could also say http://www.mysite.com/filename to promote all URLs that begin with 'filename' in that directory.
http://www.mysite.com/directory/: This creates a general promotion (weaker than specific word promotions but potentially quite wide) for the directory that is listed. Anytime any URL in this directory comes up in a search, it will be pushed up to the top.
-http://www.mysite.com/filename.html: This creates a general demotion for the file that is listed. Anytime this URL comes up in a search, it will be pushed down to the bottom.
word=http://www.mysite.com/filename.html: This creates a word promotion for the file (or files if an extensionless pattern) listed. Word promotions that are found in HTML tags in specific files are converted to this type and displayed after each indexing.
the phrase,stem*=-http://www.mysite.com/filename.html: Here is an combination example of a demotion on the words "the phrase", and any word beginnning with 'stem'. Word promotions that are found in HTML tags in specific files are converted to this format as well.
*=http://www.mysite.com/filename.html: This creates a wildcard promotion (the most powerful kind) for the file (or files if an extensionless pattern) listed. Wildcard promotions that are found in HTML tags in specific files are converted to this type and displayed after each indexing.