All BIRCH documentation is organized
into two databases, managed using sql2htmldoc.py. The databasess
are found in the following
directories:
- $BIRCH/public_html/birchdocdb
-
The database for documentation files included as part of the
BIRCH
distribution
- $BIRCH/local/public_html/birchdocdb
- The database for locally-installed documentation files.
To provide a single, unified view of all documentation,
sql2htmldoc.py
reads both databases and writes documentation pages to
$BIRCH/public_html/birchdocdb. 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 sql2htmldoc.py is run, these directories and their
contents are
completely deleted, and new directories and documentation files
are
generated from the database.
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
sql2htmldoc.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\://brassica.plants.umanitoba.ca/~birch'. The
URL for
$doc/fsap/numseq.txt would therefore be
'http\://brassica.plants.umanitoba.ca/~birch/doc/fsap/numseq.txt'.The
documentation
for $local/doc/staden/manual_unix.pdf would be
http\://brassica.plants.umanitoba.ca/~birch/local/doc/staden/manual_unix.pdf'.
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, sql2htmldoc.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.