BIRCH - Adding local documentation

BIRCH - Adding documentation for locally-installed programs

The BIRCH Home Page has links to three indices for all documentation:

Within the indices, there is a hierarchy of web pages, listing all programs in a package, all programs in a category, and pages for each individual program. All of these pages are generated automatically from two databases: one database for BIRCH core software (birchdb), and another database for locally-installed software (lbirchdb).

The process of adding new documentation is as follows:

add documentation files to a subdirectory in $BIRCH/local/doc
add datafiles to a subdirectory in $BIRCH/local/dat
add descriptions and paths for doc and data files to lbirchdb database
run htmdoc.py to generate HTML index files

4.1 Documentation files

Documentation files are added to the $BIRCH/local/doc directory. As a general guideline, it is best to put files into subdirectories, rather than having large numbers of files in the main $BIRCH/doc directory. The $BIRCH/doc directory is organized with a separate directory for each package. For example, documentation files for the PHYLIP programs are found in the $BIRCH/doc/Phylip directory. Even when there is only one program and one documentation file, it is still best to create a separate directory for that program.

Note: remember to make your files world-readable and directories world-readable and world-executable.

The next step is to create a file called docfiles.ace, listing the documentation files for the package. (In Section 2.3, we will read this file into the lbirchdb database.) For example, if you were installing the Staden package, and the documentation was in $local/doc/staden, type

doc2ace.py $BIRCH/local/doc/staden

to create docfiles.ace.

In this particular case, not all documentation is included in the files distriubted with the package. You can add links to the docfiles.ace using a text editor. For example, you might make a copy of a File object such as

File : "$BIRCH\/local\/doc\/staden\/manual_unix.pdf"
Pick_me_to_call "$ACE_FILE_LAUNCHER" "$BIRCh\/local\/doc\/staden\/manual_unix.pdf"

and edit these lines to point to the main URL for the Staden Package:

File : "http:\/\/staden.sourceforge.net\/"
Pick_me_to_call "$ACE_FILE_LAUNCHER" "http:\/\/staden.sourceforge.net\/"

Notes:

1. lbirchdb requires that all slash characters be escaped using a backslash, so every "/" in the file has to be represented by "\/".
2. To ensure that each File object has a unique name, we use the simple convention of naming each File object using the same path that is found on the Pick_me_to_call line.

The modified docfiles.ace file is now ready to be read by lbirchdb.

4.2 Data files

Many programs have supplementary datafiles. These might include things such as scoring matrices for similarity search programs, alternative genetic codes for translation programs, or even sample datasets. Data files are added to the $BIRCH/local/dat directory. As mentioned above for documentation, it is best to have a different subdirectory for each program or package, rather than having large numbers of files in the main $BIRCH/local/dat directory. Even when there is only one program and one data file, it is still best to create a separate directory for that program.

Note: remember to make your files world-readable and directories world-readable and world-executable.

The process for making a list of datafiles is similar to that for documentation. For example, if the datafiles for the Staden Package are in $BIRCH/local/dat/staden, type

dat2ace.py $BIRCH/local/dat/staden

to create datfiles.ace. In this case, every file in $local/dat/staden will be listed in datfiles.ace. Since not every file is necessarily data, you may wish to edit out some File objects before reading datfiles.ace into lbirchdb.

Where there are a large number of datafiles, an alternative is to delete all File objects from datfiles.ace, and replace them with a single object that simply points to the directory.

File : "$BIRCH\/local\/dat\/staden"
Pick_me_to_call "$ACE_FILE_LAUNCHER" "$BIRCh\/local\/dat\/staden"

When this link is read by a browser, the browser will show a view of the entire directory.

4.3 The lbirchdb database

The lbirchdb database is managed using the ACeDB database system. For a more in-depth description of how to use ACeDB, see the ACeDB Package documentation. In particular, see the ACeDB HowTo for a quick reference to important tasks.

4.3.1 Read in the File: lists

The next step is to read the lists of files into the birchdb database. Type 'lbirchdb' :

Choose Edit

Next choose Read .ace file, and answer "Yes" when prompted for Write Access. Use the file menu to find your docfiles.ace file, and open the file. Next, choose 'Read all'. If all of the File objects are successfully read in, the menu should looke something like this:

Click on 'Close File' to close the .ace file parser window.

Next, read in 'datfiles.ace' in using the same method as above.

For any class listed in the main window, you can get a list of all members of that class. For example, to see all of the File objects that were read in from the two files, double click on the 'File' class, and a KeySet window will appear listing all Files:

4.3.2 Check and Annotate the File objects

The object of this section is to add descriptive titles to File objects, and to make sure that the links work. Usually, if one works, then all of the files in the directory should work. For example, in the Main KeySet of File objects, click on $BIRCh/local/doc/staden/manual_unix.pdf. This will bring up the File object for the file. You can add a title by right-clicking in the File: window, and choosing 'Update'. This will show, in blue, fields that currently contain no data.

On the 'Description' line, click on '?Text'. The ?Text field will turn yellow, indicating that it is ready for input.

Type in a short title that describes this file and press the ENTER key. (You can get out of a yellow field by right-clicking and choosing 'Cancel'. Usually, the shorter the title, the better. Right click again and choose 'Save'. Your window should look like this:

You can test your link by clicking on 'Pick_me_to_call'. This should launch your file in a PDF viewer. If your file does not launch, there are two possibilities.

The file path is incorrect. This shouldn't happen, but there are occasions where symbolic links might give the wrong file path. You could quit lbirchdb without saving at this point, and edit the docfiles.ace file to give the correct paths. Usually all paths can be changed in one step using a global Replace command. Alternatively, you could change each Pick_me_to_call line directly in the lbirchdb program.
lbirchdb is calling a program that is not found on your system. For example, by default, BIRCH will use the 'acroread' command to launch Adobe Acrobat. If Acrobat is not installed on your system, of if the command to launch it is different (eg. /usr/local/Acrobat/acroread) you would get a 'command not found' message. The fix is to change the environment variable $ACE_PDF_COMMAND to the command on your system that opens a PDF viewer. This varible must be changed in both local.cshrc.source and local.profile.source, found in the $local/admin directory.

What's going on here?

The environment variable $ACE_FILE_LAUNCHER specifies a script used to launch a file. Pick_me_to_call generates a Unix command consisting of the name of the script, followed by the filename. Since the lbircdb script sets $ACE_FILE_LAUNCHER to 'chooseviewer', the actual command that is run is

chooseviewer $BIRCH/local/doc/staden/manual_unix.pdf

The chooseviewer script works a lot like MIME, in that it chooses the viewer based on the file extension. For each file extension (eg. pdf, ps, html, jpg) a script is called that knows how to handle each kind of file.

4.3.3 Annotate the Package and Program objects

Refer to the ACeDB HowTo for more details on creating and editing objects in ACeDB.

In this section we will create a Package object for the Staden Package, and Program objects for the main application programs in this package. Each object will contain links to documentation files, as well as other information about the programs and the package.

First, we need a Package object. In the main ACeDB window, right-click on the Edit button, and choose "Add/Rename/Delete/Alias Objects". Click on "Yes" to obtain Write Access.
In the "Add/Rename/Delete/Alias Objects" window, Enter the name "Staden" , and click on the word "Package", which will cause "Package" to appear in the blue "Class:" field.

Click on "Create" to bring up a blank window for the Staden object. To add information to this object, right click in the window and choose "Update". The available fields will now appear in the Staden window.

Enter a title on the Description line, as you did for the Description line in the File objects above.

The Description line has a ?Text field. However, most other lines in the Package class have fields that point to other classes. That is, these fields don't contain text, per se, but rather links to other objects. On the Category line, You can choose from a list of already-existing Category objects by clicking by clicking on ?Category, which will highlight the field in yellow. A message will pop up saying that you can either choose an object from another window, or you can bring up a list of Category objects by pressing the "TAB" key.

For example, if you want to assign the Staden Package to the Category "Sequence", double-click on the word "Sequence" in the Main Keyset, and it will be added to the Category field. You can add as many Category objects as you wish.

Similarly, the main documents for the Staden package can be added one by one to the Documentation fields.

So far, no Program objects have been created for the Staden Package. We can create them implicitly by typing new names into the Program fields, rather than choosing objects. Each time you type in a Program name, you will be prompted to verify that you wish to create a new object.

In this example, we will create four Program objects. (For the moment, we won't input any Data objects to the Package itself. Next, choose one or more Platform objects, depending on whether you will have binaries installed for one or more platforms. In this example, we'll only choose 'linux-intel'. Finally, since Staden is part of the local installation, rather than part of the BIRCH core, choose 'local' on the Installation line. Your final Package object should look something like this:

At this point, if you haven't already done so, go to the main ACeDB window and press the "Save" button.

Finally, we need to add information to each of the Program objects that we have created. For example, double-click on 'trev' to bring up the trev object.

Notice that this time, there is already some data in the object, a link to the Staden Package. This link was implicitly-created when we added trev to the Staden Package object. After filling in information for trev, the final object might look something like this:

Several things are worth noting:

Interface - This line says that the program is launched from the command line, and has a graphic interface. Command line arguments taken from the trev manual pages are included.
Documentation - This line was entered manually, since the file it refers to was not in the main $BIRCH/local/doc/staden directory, but rather in the manual subdirectory.
Sample_input - It makes more sense to put this file here, rather than on the Data line.

4.4. htmldoc.py - Creating documentation index web pages

The final step is to update the web documentation to include your new data objects. Type

python $birch/script/htmldoc.py

The htmldoc.py script reads both the core birchdb database and your lbirchdb database, and creates web documentation for the merged data. For an example of how the documentation might be represented at a local BIRCH site, click here.

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