update April 16, 2021

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 target 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 $BIRCH/local/doc. 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, docx - MS-Word format
• sxw, sxi, sxc - StarOffice/OpenOffice formats
• rst - restructured text file
  
• help - help files (usually output from -help option)
  

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

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

File : "$BIRCH\/local\/doc\/staden\/overview.html"
Pick_me_to_call "$ACE_FILE_LAUNCHER" "$BIRCH\/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.py