doc2ace - Create File objects for all documentation files in a directory

update June 15, 2026

NAME

doc2birchdb.py - Create File objects for all documentation files a directory

SYNOPSIS

doc2birchdb.py $doc/dirname
doc2birchdb.py $local/doc/dirname

DESCRIPTION

This script is a shortcut way of entering information for many documentation files into a birchdocdb database. For each file in the target directory with one of the file extensions listed below, write a File object to the file docfiles.tsv, in the target directory. docfiles.tsv can be read in birchdocdbkit.py. File objects can then be added to Program or Package objects.

The target directory dirname is the name of a directory either in $doc or in $local/doc. The safest way to run this command is to use the environment variables, 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
odt,sxw, sxi, sxc - LibreOffice/OpenOffice formats
rst - restructured text file
help - help files (usually output from -help option)

EXAMPLE

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

--------------------------------
-- add file object
INSERT_INTO	FILE	$local/doc/misc/manual.pdf
Description	Manual page
Command	$ACE_FILE_LAUNCHER	$local/doc/misc/manual.pdf
;
--------------------------------
-- add file object
INSERT_INTO	FILE	$local/doc/misc/overview.html
Description	Manual page
Command	$ACE_FILE_LAUNCHER	$local/doc/misc/overview.htmll
;

NOTES

It is always a good idea to proofread docfiles.tsv 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.
In .tsv files, all fields are separated by TAB characters.