update April 2, 2008
htmldoc.py - Create BIRCH HTML documentation from
BIRCH and local databases.
All BIRCH documentation is organized
into two databases, managed using ACeDB found in the following
- The database for documentation files included as part of the BIRCH
- The database for locally-installed documentation files.
To provide a single, unified view of all documentation, htmldoc.py
reads both databases and writes documentation pages to
$BIRCH/public_html/birchdoc. Documentation pages are written to
three subdirectories: category, program and package.
category - this directory contains a
main page called category.html
and for each category, a page listing all programs in that category
package - this directory contains a main page called package.html
, and for each
package, a page listing all programs in that package, as well as
documentation files pertaining to the package in general.
program - this directory contains a main page called program.html
, and for each
program, a page listing all documentation files for that program.
Each time htmldoc.py is run, these directories and their contents are
completely deleted, and new directories and documentation files are
generated from the database.
FILE NAMING CONVENTIONS
Each documentation file is represented
in the database by a File object. For data objects of the type "File",
the name of the data object is identical to the path of the file.
All file paths must begin with the name of a birch environment
variable, which corresponds a birch directory:
- $dat - The $BIRCH/dat directory
- $doc - The $BIRCH/doc directory
- $local - The $BIRCH/local directory
- $tutorials - The $BIRCH/tutorials directory
For example, the file $doc/fsap/numseq.txt would be represented in
birchdb as a file object with the name '$doc/fsap/numseq.txt'. When
htmldoc.py creates a documentation page for the numseq program, it will
include a hypertext link to this file. The prefix for the URL will be
taken from the file $BIRCH/local/newstr.param. This file contains lines
used by customdoc.py to construct URLs to BIRCH documentation. On the
U. of Manitoba BIRCH site, the path to all BIRCH documentation is
listed in this file as
'http\://home.cc.umanitoba.ca/~psgendb'. The URL for
$doc/fsap/numseq.txt would therefore be
documentation for $local/doc/staden/manual_unix.pdf would be
File names can also be URLs pointing to documentation anywhere on the
Internet. In this case, the URL is also used for the hypertext link.
For example, the file object for the NCBI Cn3D program is named
'http://www.ncbi.nlm.nih.gov/Structure/CN3D/cn3d.html", which is also
the URL to that document.
In summary, htmldoc.py creates URLs by either taking the full
name of the File object, if it begins with 'http://' or 'file://', or
if the name begins with '$', the '$' is replaced with the URL prefix
for your BIRCH site.
HOW THE PROGRAM WORKS
- For both databases, data objects Category, Package, Program
and File are dumped to flat files named, respectively category.ace,
package.ace, program.ace and file.ace. If no local birchdb
database exists, no files are generated for that database. This is done
using the script tbirchd.sh, which runs the tace command for both
databases, taking database commands from the file tace.input.
- For all data objects listed in 1, htmldoc.py reads the .ace
files, first from the main birchdb database, and then from the local
- The prefix for all URLs created by htmldoc.py is read from the
- The category, package and program directories in
$BIRCH/public_html/birchdoc are deleted and empty directories are
- New HTML files are written to these directories, as described
Dr. Brian Fristensky
Department of Plant Science
University of Manitoba
Winnipeg, MB Canada R3T 2N2