# Documentation

# Install & Upgrade

- Setup
  - Debugging Setup
- Configuration
- Security
- Indexing
  - Profiles
- Preparing the search page

# Setup

Before you start, backup your files and your database!

Notes before starting:

- We strongly recommend a MySQL database version >=4 ! An error might occur because you have a (very) old MySQL version (<4, for example the still popular 3.23).
- We recommend that you turn JavaScript on in your browser while you are doing administration of TSEP (setup is also administration!)

The installation / upgrade process:

1. Unzip the downloaded TSEP files. Make sure that you have the folder structure correct.
2. Upload all files to your website, make sure that you have the folder structure correct.
3. /include/global.php should be writeable. chmod 666 this file. (If you do not know what this is, try to install. setup.php will try to this for you.)
4. you should have / create a directory for temporary files which needs to be writeable for PHP as well. (Can be anywhere on the server)
5. Open the setup.php file in the admin directory. This (introduced in 0942) will lead you through the install and/or upgrading process.

- If everything works fine, all will be done by the setup.php. If you have been upgrading you can keep all your old data (logs, stopwords, index, profiles etc. The following should happen:

- the file global.php is changed to match your needs (database connection data)

> Follow the setup until it tells you you are done. Now continue with the next step: configuration.php (skip the next points of this list!)

- If there is an error: the setup.php should tell you about it. You can also use the special debugging function we have included in the setup.php:

> To show output of _TsepTrace()-function-calls within setup.php call the file with the following parameter:

> .../setup.php?debugtrace=on

> You can also explicitly switch it off using:
> .../setup.php?debugtrace=off

> The default is off

> Simply insert _TsepTrace()-calls into setup.php wherever you need it or mean we will need it, if an admin (you) has troubles with setup.php.
> Just use _TsepTrace()-calls - you do not need to check "by yourself", if debugtrace is switched on or not.

setup.php will either create the tables with default values or take your old values when updating and you wish so.

## Feedback

In the end of the setup - or in case you abort we have created a feedback form. In this form you can send statistical, general information and you can also comment to tell us your whishes and needs for TSEP.This is totally optional and anonymous! You decide if you let us know anything and what you let us know. By submitting any information you will help us to make TSEP fit your needs!

You can also directly subscribe to our newsletter. Of course we will never give away your email address and unsubscribing is very easy. You can unsubscribe (and resubscribe every time you like) on our website.

The next page you will see after you press the finish button is the configuration page of the TSEP you have just installed.

Note: In 0942 we have also introduced a new start page for the admin area. This startpage is the index.php in the admin directory. This means, you find most, if not all links to important pages on this page. Open <tsepinstalldir>/admin/ - or <tsepinstalldir>/admin/index.php to access this page. See the page.

See the database model.

# Configuration

This was introduced in v0.912. Open the configutation.php directly after installation and set the correct values, especially for language and the TSEP path - and of course every other value.

Open the configuration.php in the admin directory and make all the changes to your liking.

Note: The option to check if a file exists before returning it as a result can take quite long if you have many results! We have been notified that at one of the sites using TSEP it made a difference of the factor 30 (meaning with the checking it took more than 30 seconds instead of less than 1 second without the checking). The checking can be useful if you delete files after indexing. If you are sure that all files which are indexed still exist on the server you can safely turn it off. We recommend to leave the setting on.

Continue with Security.

# Security

If you are able to use .htaccess we strongly advise you to protect the include and the admin directory using .htaccess once you are done installing!

You should also delete setup.php after your installation / upgrade was successfull.

Short explanation on this: If you do not protect the directories, everyone could use a plugin for example to fill your database. Everyone would be able to change the index - so again: Protect the include and the admin directory using .htaccess

Continue with Indexing your Site

# Indexing

To fill the database with values (content / words of your pages) for the search engine to search for, you have to run the file 'indexer.php'.

If you are calling the indexer.php the old fashioned way (for example by the link in any of the administration pages) you need to input the details asked by the form.

By submitting the form with the appropriate values you will see the results of the indexing after a few seconds. The script will provide information on the number of pages, the title, the URL, the size and the number of indexed words found by the indexing script.

In version 0.942 we introduced a new parameter for the indexer which concerns our users whish for "selectable subdirectories". In a multi-line inputfield, subdirectories can be entered. If this field is

- empty: all subdirectories found under the given Web-Directory are used (works as before)
- not empty: each given subdirectory is appended to the given Web-Directory and files are searched.

In version 0.940 the exclude directories setting has been improved ("Enter the directories to be excluded"). It now functions as follows:

- abc*ef - means 0 to n charcters instead of * Example: "abcdef", "abcdddddef", "abcef",... would be found and excluded
- abc+ef - means 1 to n characters instead of + Example: "abcdef", "abcdddef",... would be found and excluded
- abc?ef - 1 character instead of ? Example: "abcdef", "abceef",... would be found and excluded

The list which is produced by the indexer with the exclusions has been improved too:

- Strikethrough (like this) has not beed checked against the dir_exclude
- Characters in bold were part of the filter

In version 0.938 we added parameters for the indexer. Just enter any of the following in the address area of your browser. Of course put the correct address like 'http://www.yourdomain.com/tsep/admin/' of the indexer.php before it.

indexer.php?startindexing
  this directly starts indexing with the active profile
indexer.php?startindexing&profile=xxx
  this directly starts indexing with the given profile - in this case xxx. Attention: This works only if your profile name does not contain characters which are encoded (spaces included). (also see Profiles)
indexer.php?showcompleteindex
  this shows complete index currently stored

Notes:

- When you search from the search field in the 'indexer.php, this search will not be logged!
- Please also read the restriction on "FAQ: What files can TSEP index" in the complete documentation if you encounter problems.
- Using "Force parsing via HTTP" has (at least) two advantages:
  1. SSI-content is parsed too, so are PHP, Perl etc scripts and
  2. URLs outside your local scope can be indexed i.e. files, which can not be read directly via local-fileopen).

  The disadvantage is, that the indexing-process can be slowed down extremly! In addition, if e.g. an include references to a slow or not existing target, the indexing-process waits, until a possible timeout - this also can cause a 404-page to be returned (and indexed!).

- The options "indexer should find files via directoryscan" and "indexer should run datasupplier-script" are not exclusive! They can be used at the same time. In case of both options are "on", the indexer runs external-datasupply first and directory-scan afterwards.
- If you want to index "dynamic" sites, e.g. sites where the content of pages is drawn from a database please read the "How to index dynamic sites" in the complete documentation
- While the indexer is still running - and indexing (see the loading status bar or the animated icon in your browser) do not stop the loading of the page, but wait until the page has been fully loaded and your browser tells you so. You will not be able to start two instances of the indexer at
  1. the same time
  2. if the indexer stops with an error (see next topic) for the time defined by max_exec_time in php.ini
- The indexer runs a maximum of max_exec_time minutes before PHP closes the proces with a fatal error. The error PHP throws can not be handled by a custom error handler - so the script simply dies of a timeout. The max_exec_time (which defines how long each script can run) is set to 30 minutes as a default.
  If PHP safe_mode is on the code doesn't work and PHP relies on the max_execution_time in the php.ini. If this is the case the indexer notifies the admin.

## Profiles

As you see there are profiles. Each profile can have totally different settings for the indexer. We provide you with one profile called "demo". You can either rename the "demo" profile (Save As-Button) or create a new profile of your own and delete the "demo" profile afterwards - or of course just leave the demo. You can not delete the last profile!

You can choose a profile to use, you can save your settings as profiles ("save " and "save as" buttons), you can rename a profile or delete a profile. When you are deleting a profile all pages which belong to that profile only will be removed from the index as well!

# Preparing the search page

You decide what you want. You want to ...

1. use the pre-made search page
2. include TSEP into your layout?
3. create a search field on your page(s) X and forward the user to the search page Y?

1. to use the pre-made search page 'tsepsearch.php', you are done with the installation.
2. to include the search page in your own page / layout, please follow these steps - make sure that the path to the two files are set correctly!
   1. You need to make sure your page is being processed as a PHP page, ususally this is the case when your page has the extension .php or .php3 add the following code between your SEARCH page <head> ..and.. </head> tag - otherwise the search will look ugly! This example assumes that search.php is located in the same directory as your search page, tsep.css is in a subdirectory called "css".
      <link href="css/tsep.css" rel="stylesheet" type="text/css" />
   2. add the search.php into your page at the position you wish to add the search function like this:
      <?php require ('search.php'); ?>

   > If you want to create your very own search form, please take a look at the 'tsepsearch.php' file provided by us for the fields you need to use.

   > You have now integrated TSEP into your own page.

3. Since people have been asking how they can implement a search field on their pages and forward the user to the actual search page once he enters something in the search field, here is the general solution for this:
   If I get you right, do the following:

> Your sitestructure:

> > /
> > /filex.php
> > /search.php
> > /php/tsep/ ...... here is the complete TSEP structure:
> > /php/tsep/log.php
> > /php/tsep/admin/ .....
> > /php/tsep/include/ .....

> make a (search)form on your page "filex.php".
> HTML Code for this:

> <form action="/php/tsep/log.php" method="get" name="tsepsearchform" id="tsepsearchform">
> <input name="go" type="submit" value="Search" class="submitButton" />
> <input name="q" type="text" class="SearchField" value="Search" />
> <input type="hidden" name="s" value="0" />
> <input type="hidden" name="e" value="<?php echo $tsep_config['config_How_Many_Results'];?>" />
> <input type="hidden" name="user_e" value="<?php echo $tsep_config['config_How_Many_Results'];?>" />
> <input type="hidden" name="searchpagelocation" value="/search.php" />
> </form>

> Create your own "search.php" page. In this page include the premade file:

> <?php require ("/php/tsep/search.php");?>

> For this require you might need to give the full path! Maybe use this instead:

> > $docroot = $GLOBALS['HTTP_SERVER_VARS']['DOCUMENT_ROOT'];
> > <?php require ("{$docroot}/php/tsep/search.php");?>

> Don't forget the CSS from TSEP in your page(s) X and to read the TSEP config! (described in b) )