update August 19, 2005

This script is a shortcut way of entering information for many documentation files into a birchdb database. For each file in the target directory with one of the file extensions listed below, write a File object to the file docfiles.ace, in the current working directory. docfiles.ace can be read in birchdb or lbirchdb in the Edit --> Read  .ace file menu. File objects can then be added to Program or Package objects.

The target directory dirname is the name of a directory either in $BIRCH/doc or in $local/doc (= $BIRCH/local/doc). Even if dirname is a symbolic link to another directory, do NOT use the fully-qualified path of that directory on the command line, or incorrect filenames will be written to docfiles.ace. The safest way to run this command is to use the environment varibles, as shown in the SYNOPSIS.

Files with the following file extensions are recognized as documentation files:

• pdf, PDF - Adobe Portable Document Format
• ps,PS - Adobe PostScript
• txt, asc - ASCII text
• html,htm,HTML,HTM - Hypertext Markup Language
• man - Unix manual pages
• doc - MS-Word format
• sxw, sxi, sxc - StarOffice/OpenOffice formats
  

If the directory $local/doc/staden contains the files manual_unix.pdf and overview.html, the following File objects will be written to docfiles.ace:

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

File : "$local\/doc\/staden\/overview.html"
Pick_me_to_call "$ACE_FILE_LAUNCHER" "$local\/doc\/staden\/overview.html"

1. It is always a good idea to examine docfiles.ace in a text editor before reading it into the database. For example, you may wish to delete some File objects, or create new ones before reading this file into the database. This step can also be done in lbirchdb.
   
2. In .ace files, all Unix seperator characters are escaped using the '\' character.
   

dat2ace.sh