BIRCH
BIRCH - Getting the Documentation onto the Web

Purpose:

The BIRCH web site has a large number of pages that link to each other, as well as linking program documentation and datafilees. While most of the URLs in these links are "relative URLs", it is necessary that some of them be hard links, particularly for documentation and datafiles. When you initially install BIRCH, the documentation and datafiles may not all be web-accessible. In this tutorial, we will go through the process of finding out the URL that will reach your copy of the BIRCH home page, and then we will use the customdoc.py script to change URLs in the BIRCH documentation so that they are all accessible through your BIRCH web site. First, check with your web administrator to find out how to determine the URL for your BIRCH web site. You may have to do a bit of experimentation with a web browser to get it exactly right.

We need to be able to find a URLs that will point to

First: Is there a web server (eg. Apache) running on the host where BIRCH is installed?

In the simplest case, there is a web server such as Apache running on the same host as BIRCH. In the figure, BIRCH has been installed on a host called intron.mylab.ca, in /home/birch. In a typical Apache installation, the user's web site is found in $HOME/public_html, or in this case, /home/birch/public_html. By default, the home page is called 'index.html', and this name need not be included in the URL. Again, typically there is a web server running on the host whose name starts with 'www' or maybe 'home'. URLs therefore have the general structure:

http://www.hostname.domain/~userid

or

http://home.hostname.domain/~userid
Figure 1.

which tells the web server to automatically look at the $HOME/public_html directory for the user whose name is userid. In this case, the URL for the BIRCH home page should be http://www.mylab.ca/~birch. (At some sites, the tilda (~) is not used).


Figure 2.

The second possibility is that the web server is running on a different host from BIRCH. If that is the case, the only way to get the BIRCH web site to be accessible to the world is if the BIRCH home directory is remotely mounted (eg. via NFS) on the web host. In this scenario, all users are assumed to have a web directory on the web server, www.mylab.ca, within the /data/home  directory.  You would need to ask your web administrator to remotely mount your BIRCH web directory (/home/birch/public_html) a this point on the web server. (If security is an issue, your directory could be mounted read-only). Again, the URL for your web site would be  something like http://www.mylab.ca/~birch.

Make your webmeister happy!  Tell him/her/it that the BIRCH web site does NOT use CGI, PHP or Javascript. It is nothing more than read-only documentation.

Once you have determined the correct URL for your BIRCH site, you should be able to view your BIRCH home page (click here for example).

Next: we need to be able to link to files outside of $BIRCH/public_html

Typically, the web server assumes that all your web pages are in your public_html directory. For a lot of good organizational reasons, this is not practical to do in BIRCH. For example, we might want link to any of the documentation files in $BIRCH/doc or the data files in $BIRCH/dat, or the local web pages in $BIRHC/local/public_html. The problem has already been solved for you because $BIRCH/public_html contains a symbolic link to the BIRCH home directory. If you go to $BIRCH /public_html and type 'ls -l' you'll see

lrwxrwxrwx   1 birch  birch        2 Apr 17  2003 birchhomedir -> ../

That way, you can create a URL for any file in any BIRCH directory. For example, for the BIRCH site at http://www.visualgenomics.ca/~birch,  the URL for the file $BIRCH/doc/xylem/shuffle.txt would be http://www.visualgenomics.ca/~birch/birchhomedir/doc/xylem/shuffle.txt.

But what if your web server doesn't allow the use of symbolic links on personal home pages?

For security reasons, some systems that allow web sites for individual users do not allow the use of symbolic links within public_html, especially if they point to directories outside of public_html. One way around this is to have your web master create a symbolic link from some directory on the web server to the remotely-mounted BIRCH home directory. For example, the main BIRCH web site is at http://bhsc01.ucalgary.ca/~birch/public_html. Since symbolic links are not allowed for users at out site, there is a link from the web server at www.umanitoba.ca. This link is called 'birch', and is found in the '/www/data/faculties/afs/plant_science/' directory. The URL that points to the BIRCH home directory is therefore http://www.umanitoba.ca/faculties/afs/plant_science/birch.  If you click on this link, what you'll see is not an HTML web page, but rather a directory listing of the BIRCH home directory. To link to the file $BIRCH/doc/xylem/shuffle.txt, we would use the URL
http://www.umanitoba.ca/faculties/afs/plant_science/birch/doc/xylem/shuffle.txt

Running customdoc.py

By now you should know
  1. URL for your BIRCH web site
  2. URL for your BIRCH home directory
The python script customdoc.py will substitute your values for the current ones. When you do a new BIRCH installation, these two URLs are set to refer to local files. For example, if  the BIRCH home directory is /home/birch, the birchconfig wizard would have created an install-birch/newstr.param file that looked something like this:

~
file:///home/birch/public_html/index.html
file:///home/birch
birch@mylab.ca
/home/birch
birch

These are the values that were substituted into BIRCH web documentation when you did the new install. The "file:///" strings need to be replaced by the correct URLs. Create a file called install-birch/oldURL.param by copying these 2 lines. For example:

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

Now create another file called  install-birch/newURL.param, for example:
 
http://www.mylab.ca/~birch
http://www.mylab.ca/~birch/birchhomedir

To make the changes, run customdoc.py:

python customdoc.py oldURL.param newURL.param htmldir.param

The script will echo the names of directories visited, and lines changed to the terminal window.
You can also 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.

... wait, we're not done yet

When you're sure that the URLs have been correctly changed in the BIRCH documentation, we need to make the changes permanent. The file newstr.param, is read when updating to a new version of BIRCH, and also when when you add new documentation to the $BIRCH/local directory. This file still contains the URLs that you copied to oldURL.param. You need to replace those with the URLs from newURL.param. Thus, your final newstr.param file might look something like:

~
http://www.mylab.ca/~birch
http://www.mylab.ca/~birch/birchhomedir
birch@mylab.ca
/home/birch
birch

The good news: Once newstr.param is correct, you should never have to think about it again. Every time you update to a new version of BIRCH, the values in newstr.param will be used.

P.S. - I promise that this process will be simplified in later releases of BIRCH. (BF)
Please send suggestions of comments regarding this page to birch@bhsc01.ucalgary.ca