mkphysdir : Script to convert db file into Physics Directory Web Pages

Overview

This script will take a tab delimitted export file from the Personnel database and convert to a bunch of web pages for the Physics Personnel Directory. The entries should be in alphabetic order based on the last name. The database file should contain the fields in @dirfields, tab delimitted, currently:

University ID
Name (last, first)
Research/Administrative group name
Homepage URL
Title
Office Room Numbers
Building office is in
Phone number
FAX number
email address

For each individual listing, the fields specified by @printfields will be put on the web listing, in order. Be sure to use the same field titles as in @dirfields. The Name field will always be printed, and is always first, and should not appear in @printfields. Currently, Title, research group, phone, fax, email, web page, and address (equal to Building+Room number) are also printed.

The script will produce a page for each letter of the alphabet (A.html, B.html, ...) containing listing of users whose last name begin with that letter, as well as the file all.html containing the full directory.

To allow for flexibility as the look of the departmental web pages change, the script composes each file according to the contents of the file structure.txt. The results of processing each element of the list is concatenated together to form the resultant file.

The bulk of the script is dedicated to generate the following elements from the personnel database, named as they would appear in the structure.txt file:

&Directory : This produces the directory entries for all people in the database (with appropriate letter starting last name for the lettered pages). Each person's entry is named so can be indexed on.
&QuickFile : This produces a Quick Index File of the directory entries which would appear in the file, indexed into the &Directory structure.
&Index : This produces an index for each letter of the alphabet, linking to the appropriate web page for the directory for that letter.

The above structures do not contain any wrapping code, so can be placed anywhere (in any structure) in the page. For instance, one would probably want to place the &QuickFile in left hand column of a table, with the &Directory along the right hand side. But this formatting is not included with these elements, and must be set up separately, as is considered part of the overall look. This sort of formatting can be accomplished using the two additional elements allowed in the structure.txt file:

  1. $filename : this also reads the file filename and copies it into the directory web page being constructed, but will expand certain variables in the text. This allows for web pages whose outside shell is almost, but not quite, identical for each starting letter to be made.

The $filename format recognized the following variables:

$LETTER$ : gets replaced with the letter (A,B,... Z) of the index, or the word 'all' for the full directory file.
$TITLE$ : gets replaced with an appropriate title string for the web file, something like Physics Directory - All Entries or Physics Directory - A.

(The above is controlled by %varlist in the code.)

Setup

This section describes what must be done before using the script. This should only have to be done once until the look of the web pages change. This just sets things up so that the directory files look the way that it is wanted. It need not be done everytime there is an update to the personnel database.

The basic requirement before the script can be used is to create/edit the structure.txt file and any files that it references. Both the structure.txt file and any files it refers to should be in the mkphysdir template directory. This directory is /group/phys-admin/project/mkphysdir/www, or if mkphysdir is run with the --test flag, in /group/phys-admin/project/mkphysdir/testwww.

The required process at this step is to express the various directory web pages in terms of the elements of the structure.txt file, basically, the &Index, &QuickFile, and &Directory elements, and whatever glue you need to put them together.

The best approach is probably to pick a single file, edit it in whatever web design program you like, and then examine the source code. The script puts comment lines around every element (e.g. Start of &Index or End of $file), and so you can use these to start breaking the file into pieces. Everything before the first auto-generated element (&Index, &Directory, or &QuickFile) goes into one file, everything between the first and second auto-generated element into another, and so on, putting everything after the last auto-generated element in a final file. These files form the glue which gets included around the auto-generated elements by listing them in order in structure.txt using the #file and $file elements. If there is anything which is specific to the particular letter in the file, you should change that to use one of the $TITLE$ or $LETTER$ variables, and use the $file form, otherwise use the #file form.

Put all these files in the mkphysdir template directory, and edit the structure.txt file to instruct it how to assemble the pieces, and you're all set. But you should probably test it out first (see below, in particular the --test flag).

Running

Once the script is setup (which should not need to be done frequently, only when changing the style of the pages), the database file should be exported and ftp'ed to a PNCE-Unix system (e.g. login.physics.umd.edu) and this script should be run. Usage is

mkphysdir [--test] [dbfile]

Items in brackets are optional. If dbfile is not specified, it will ask for it. If the --test flag is given, it will use the test template directory and populate the http: site instead of the production http: site.