= Using Houdini with an external help server =

== Overview ==

A studio can set up a central help server to serve help to multiple
users of Houdini, instead of each instance of Houdini starting up
its own help server on each machine.

There are two main tasks to setting up a central Houdini help server:

# Start the server on a computer.
# Change the settings in each user's Houdini to use the central server
  instead of its own.
  
== Starting the server ==

Open the command line tools. (on Windows, choose Start > Side Effects
Software > Houdini X.X.XXX > Command Line Tools, on Linux source the
Houdini environment).

In the command line tools shell, go to `$HFS/houdini/scripts/python`.

Type `python start_server.py -p <<port_number>>`

You can type `python start_server.py --help` for a list of options.

TIP:
    Use `python` instead of `hython` to avoid checking out a Houdini
    license.

=== Notes ===

- Simply typing `python start_server.py` uses the default
  `$HFS/mozilla/documents` as the document directory. You can specify
  a directory explicitly on the command line:
  
  `python start_server.py -p <<port_number>> ~/docs`
  
  More interestingly, you can specify _multiple_ directories to
  serve from. The contents of the directories are overlayed, with
  the contents of later directories on the command line overriding
  earlier ones:
  
  `python start_server.py -p <<port_number>> $HFS/mozilla/documents ~/houdini9.1/help`

- On Linux, you can start the help server in the background and then stop the
  process at a later time.  To start the server in the background, use '&' as
  follows:

  `python start_server.py &`

  To stop the server, use the `-k` option along with the 'stop' keyword:

  `python start_server.py -k stop`

  This can be useful if you want to run the help server as a daemon and have
  it automatically start when your machine boots up and stop when your machine
  shuts down.  Note that `-k` can either 'start', 'stop' or 'restart' the
  server.

- When the help server starts up, it writes its process id into a file (as
  defined by the `--pid-file` option).  This is how start_server.py knows which 
  process to kill when it is given the '`-k stop`' option (Linux only).  
  To find out the default location of this file, type 
  `python start_server.py --help` and look under the `--pid-file` documentation.
  If for some reason the help server does not exit cleanly, you may have to 
  manually remove this file before restarting the server.

- This procedure assumes Houdini is installed on the machine you want
  to use for the central server. This is not strictly necessary, but
  to use a central server without Houdini installed on it, you would
  have to copy over the necessary Python files, the documentation, and
  the `index.db` file, and use the options of `start_server.py` to
  specify the file locations, instead of having the script find them
  automatically relative to `$HFS`.

- The help server uses the Python WSGI standard. WSGI is a standard
  designed to let Python web applications run on different web servers
  and CGI implementations. The current implementation runs on top of 
  the standard web server included with Python, however theoretically
  you could modify it to run on top of FastCGI or mod_python in an
  Apache web server. We at Side Effects Software Inc. haven't tried
  this, however, and it would probably require extra development to
  get it to work.

- An alternative way to integrate the Houdini help into an existing web
  server is to run the help server along the main server and simply
  redirect certain URLs on the main web server to the help server.
  The Python web server is small and certainly not as fast or robust
  as Apache, but it should be fast enough to handle hundreds of users
  comfortably.

== Setting up Houdini ==

To set up Houdini to use an external help server:

# Start Houdini.
# Choose Help > Houdini Help.
# Click Settings.
# In the External Help URL field, enter the URL of the external help
  server.

  For example, if you started a central server on port 5050 on a
  computer named `italy`, you would enter
  
  `http://italy:5050/`
  
  ...as the external help URL.
  
NOTE:
    There may be bugs in Houdini where Houdini will try to use a
    hardcoded reference to the local server instead of your
    central server, for example when you first open the help pane
    and it tries to load the home page. These problems should be
    ironed out in future versions.

== Writing wiki pages ==

Files under the directories you specified on the command line
(default `$HFS/mozilla/documents/`, see Starting the Server above)
will be visible on the server. For example, if you have the server
on port 5050 serving `~/docs/`, then `~/docs/mypage.html` will be
available as `http://localhost:5050/mypage.html`.

Houdini's help pages are written in a wiki format that is translated
into HTML by the server.

To write pages in wiki format, create a text file (with the
extension `.txt`) with wiki formatted text (see
[wiki formatting|format]). For example, if you have the server
on port 5050 serving `~/docs/`, then create `~/docs/mypage.txt`.

If you open `http://localhost:5050/mypage.txt` in a browser, you'll
see the wiki text. If you open `http://localhost:5050/mypage` or
`http://localhost:5050/mypage.html`, you'll see the HTML generated
from the wiki text.

NOTE:
    The HTML relies on images, CSS files, JavaScript, etc. from the
    standard documents directory. If you want to create your own
    files to show up on the server, overlay a directory over the
    standard `$HFS/mozilla/documents` directory (see Starting the
    Server above).