Copyright (C) 2006 Joerg Kunze

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.

These are installation instructions for documentation.  (Version:
0.1.1 from Tuesday May 02 23:09:35 2006)

0.0.1 The simplest way
----------------------

The simplest way to use this package is by not installing it at all,
but just use it from where it is. *Yes you don't have to install it.
You can just call the programs*. If that's your way do the following:

  1. `cd' into the packages root directory. For example `cd
     ~/myPackages/documentation'.

  2. Call `./siliconBrainInstall' without any parameters.

  3. The last two lines contain settings, which you should include
     somewhere to be executed, where you like to use this package. So
     for instance you can add these two lines to your `.bash_profile'.
     All output of `siliconBrainInstall' is written to `stderr' except
     the last two lines, which are written to `stdout'. So you can also
     call:
          ./siliconBrainInstall > fileToRememberTheSettings

0.0.2 Install the package somewhere
-----------------------------------

If you want the package to be installed somewhere, you have to follow
this section.

   First we have to clarify some concepts.

   The "installationPath" is the directory, where to the package
directory will be installed. An example is `/usr/local' or
`~/myPackages'. This directory must exist prior to installation. You
can use `/usr/local' (or a directory below), if you use siliconBrain
for your own developed software. You can use `/usr' (or a directory
below), if this package is delivered by someone else.

   The "installationDirectory" is the newly created package root
directory. The installationDirectory will be created by
`siliconBrainInstall'. Normally part of its name is the package name
and/or the release number. When you specify the installationDirectory
you can use some place-holders:

`%p'
     This is replaced by the package name. You an use this placeholder
     when you write a script, which will be used for more than one
     siliconBrain package.

`%r'
     The release number of the package. For example "0.1.42".

`%R'
     The release number, but with underscores instead of dots. For
     example "0_1_42".


   So specifying `%p_%R' will result in `documentation_0_1_42'.

   There are three ways to specify installation path and directory:

   * Use `siliconBrainInstall' with either the option `-i' or
     `--interactive' to be prompted for your choices.

   * Specify both as positional parameters on the command-line.

          ./siliconBrainInstall /usr/local documentation

     You can use this if you write a generic script, which has the duty
     to install siliconBrain packages. Then you may write:

          ./siliconBrainInstall /usr/local %p.%r

   * You can set the two environment variables
     `siliconBrainInstallPath' and `siliconBrainInstallDirectory'. This
     could be the choice if you constantly are installing packages.


   As in subsection "The simplest way" at the end the script will
output two lines which you can add to your configuration. And all
output is written to `stderr' and just the two last lines are written
to `stdout'. Thus you can collect the two lines with redirection.

0.0.3 Compile this package
--------------------------

  1. Make sure that the siliconBrain main package is installed.

  2. Make sure that the packages root directory has the same name as the
     package (`documentation'). (If not the directory name will become
     the _new_ package name.)

  3. `cd' to the directory containing the package's source code and
     type `make'.

  4. Use `./siliconBrainInstall' as described in section "Install the
     package somewhere". Or you can use `make install', which just
     calls `siliconBrainInstall' with no arguments. If you do so,
     `siliconBrainInstallPath' and `siliconBrainInstallDirectory'
     should be set correctly.