

                     HOWTO correctly use the install.bas
                     -----------------------------------

The test is extremely complex and flexible and has limited capability to recover
from some sorts of errors. If just one of the configuration files is not set up
correctly, you will get countless confusing errors that are difficult to debug.

TOC
1. How the test works
2. The configuration files
3. The reference files
4. Create a configuration for a specific minor office version

1. How the test works
---------------------

First the test verifies (and ensures) that all required workdirectories exist.
They will be created, if not present.

The test collects all files below the office installation directory and stores
the names into one huge array.

If the reference files do not exist yet, the array will be split up in several
smaller arrays depending on the configuration in the categories file and the 
i18n-files. The smaller arrays will be written to the appropriate directories.
The remains of the list ends up in the common.ref-file. The filenames are 
stored UTF-8 encoded and case-insensitive. You need to set bCREATE to TRUE
if you want to create the reference files.

If the ref-files exist, they will be loaded and merged into a second array.

First test is to compare the filenames from the current installation with 
those from the reference files to find all missing files. Missing files are 
printed to the log (max 20) and removed from the reference-array.

Second test is to look for newly added files. They will be printed as well
(max 20) and removed from the current-array.

What remains are the files that are common for both arrays. The reference-
files contain information about the size of the files from the version from 
which they have been created.

Now the sizes are compared, file by file. Because any file touched by 
development changes its size somehow, the test allows for a tolerance of 10%.
This can be overridden by rules. However, per default any change of more
than 10% in size is an error and will be printed to the log (again max 20)


2. The configuration files
-----------------------

The files can be found at <testtoolpath>/framework/install/input

=== category.dat ===
This file contains a list of categories. They have to belong to the [system]-
section. The names of the categories can be chosen at random but should reflect 
the content somehow. The categories are used as directory-names for the ref-
files.
Any category found in this file will be searched for in the i18n-files.
Comments begin with a #.

=== i18n_XX.dat ===
XX stands for a language code like 01 for en_US or 55 for pt_BR

These files contain language-specific information. Below the section [system]
you have to put the three different strings/numbers by which localized files 
are identified. The identifiers are (e.g. for en_US):

shortname=en-US
longname=english
langcode=01

The identifiers are followed by the categories found in the category-file.
Here the categories get a value assigned, a path to some localized files
or directories, e.g.

readme=share/readme/README_en-US
...

For each installed/supported language such a file must exist! All categories
must exist in the categories-file. Comments begin with a #.

=== rules.dat ===
The rules-file is used when all the files that exist equally in the current
installation and in the reference files are compared by size. You can tweak
the behavior of the comparision with some simple keywords followed by a
unique pattern that identifies the file/directory to which the rule is to 
be applied. Currently four rules are supported:
1. smaller (allows the file to shrink by 20%)
2. larger (allows the file to grow by 20%)
3. skip (do not test at all)
4. fixed (do not allow the file to change size)
Comments begin with #.


3. The reference files
----------------------

The reference files end up in following directory if they do not exist
and the variable bCREATE in the install.bas is set to TRUE:

<testtoolpath>/framework/install/input/sysinst/$Productname/$Platform

Here directories for all categories defined in category.dat should exist
and the directories should be filled with the appropriate files named
XX.ref where XX is the language code.
The directory contains the file common.ref as well.

4. Create a configuration for a specific minor office version
Here i will hopefully soon put a sample-session on how to make the
install test work.
