BIRCH
BIRCH - Customize Documentation
Note: if you are updating an existing BIRCH implementation, you can probably just re-run customdoc.py without changeing any files.

Purpose: To replace URLs, directory names etc. in HTML documentation to correspond to your local site.

What gets changed:

  1. Main URL for BIRCH web site
  2. URL for BIRCH documentation and data files
  3. Email address for BIRCH administrator
  4. userid for BIRCH administrator
These values are changed in all HTML documentation files, so that users can find things and get help on YOUR local system. These changes are made by a Python script called customdoc.py. customdoc.py reads a list these 4 parameters from the file oldstr.param, and reads the new values from newstr.param. It then searches the HTML files in the directories listed in htmldir.param, and makes the substitutions.

Most of these parameters are pretty straightforward, but parameters 1 & 2 need some explanations.

Three choices for URLs

There are three alternatives for setting up these URLs:
At this point, you can skip running customdoc.py, if things look too complicated, but your documentation will all refer to people and pages at the University of Manitoba. Or, if you choose option 1 now, you can always change the URLs using customdoc.py, but you will have to create your own oldstr and newstr files, as described below.

Option 1 (default) : Only users logged into your BIRCH server(s) can read the documentation

This is the most foolproof but also the most limited way to make documenatation available. In this method, users simply use the browser to open the documentation files by clicking on the name of the document. If you bookmark the main BIRCH document, index.html, it is effectively the same as bookmarking any web site, but you can only get to it when logged onto your BIRCH server.

If BIRCH was installed in /home/birch, the URLs might look something like this:

file:///home/birch/public_html/index.html
file:///home/birch

Option 2: Documentation is  available through your local Web server (symbolic links allowed).

To make the documentation available from anywhere on the Web, a BIRCH implementation in /home/birch, where 'birch' is the userid of the BIRCH administrator, would look something like:

http://home.cc.umanitoba.ca/~birch
http://home.cc.umanitoba.ca/~birch/birchhomedir

The first URL points to the public_html directory of user birch (by convention
of the Apache Web server, which most sites use). This directory contains
a symbolic link called 'birchhomedir' which points to the birch home directory /home/birch. This second link makes it possible to point a browser at any file in the entire BIRCH system, but is typically used for viewing documentation and data files.

BUT, some Web servers are configured so that most users are not permitted to use symbolic links in their web sites (Arrrrgh!!!)

Option 3: Documentation is available through your local Web server (symbolic links NOT allowed).

The BIRCH web pages at the Univ. of Manitoba are organized as illustrated below:
website_schema.gif  

The main URL is the address that users will use to get to the BIRCH web site. At the Univ. of Manitoba, this URL points to the public_html directory for user 'psgendb' .  public_html contains all of the BIRCH documentation and tutorials, with the exception of documentation files for programs, which are found in $BIRCH/doc. Depending on how your web server is configured, it may be possible to just create symbolic links from public_html, so that web pages within public_html could use relative HTML links to get to get to these documents. However, for security reasons, some sites do not permit symbolic links  in personal web sites, but they are permitted on the campus webserver. As a workaround, fully qualified HTML links can be made to a URL for the web server, which points to a symbolic link from the University web server to /home/psgendb/BIRCHDEV. In the example above, the symbolic link called 'psgendb' is found in the directory '/www/data/faculties/afs/plant_science/'. This link points to /home/psgendb/BIRCHDEV, the BIRCH home directory. The URL corresponding to this link is 'http://home.cc.umanitoba.ca/~psgendb/birchhomedir/BIRCHDEV'. Therefore, this URL allows read access to any file in the BIRCH hierarchy.

Running customdoc.py

Read the manual page for customdoc.py. Once you understand how this works, you can modify and oldstr.param to correspond to you local system. oldstr.param and htmdir.param should probably not need to be changed.

Now, you're ready to update the HTML files. In the install-birch directory, type

python customdoc.py oldstr.param newstr.param htmldir.param

The script will echo the names of directories visited, and lines changed to the terminal window.
You can use customdoc.py for future automated changes to web pages by creating your own .param files.

At this point, the documentation for your local copy of BIRCH should have custom filepaths, directory names, email addresses etc. Exit the browser now, and restart it. Open $BIRCH/public_html/index.html. and continue the installation process.

Special note: Changing Option 1 to Options 2 or 3


Suppose you had originally chosen Option 1 above, and wanted to change to Option 2. Create a file called opt1.param containing the strings to change:

file:///home/birch/public_html/index.html
file:///home/birch

Create another file called opt2.param containing what you want them changed to:

http://home.cc.umanitoba.ca/~birch
http://home.cc.umanitoba.ca/~birch/birchhomedir

Now, run customdoc.py:

python customdoc.py opt1.param opt2.param htmldir.param


Please send suggestions of comments regarding this page to psgendb@cc.umanitoba.ca