Caucus CSNAP
Last revised 27 January 2003

I. Introduction

This page describes the purpose and use of CSNAP, the Caucus Snapshot utility.

The normal use of Caucus provides a sophisticated web-based conferencing environment, where each page is dynamically generated from a central server according to the current state of the conference. 

But sometimes it can be useful to have a static "snapshot" of a conference -- something that can be carried away on a disk, something that does not depend on access to the Caucus server.  These uses can include:

 

II. What does it do?

CSNAP is a set of "stand-alone" CML scripts included with Caucus 4.x.  It is run as a sweba script.  It prompts for a list of conferences, and then writes a set of static HTML pages that reproduce the content of the selected conferences.  The content includes all of the items and responses, any files uploaded into the conferences, and the information about all the participants in the conferences.

The "snapshot" also mimics, as much as possible, the look and feel of the Caucus interface.  All of the usual links are active, but any functions that require processing (such as searching) or storage (such as adding new responses) are disabled.

CSNAP writes all of the output files into a directory in such a way that the entire directory can be picked up and moved elsewhere, if desired, without affecting its use.  (In technical terms, all of the links between the files use relative URLs).  The result can be immediately viewed by a local browser (using "open file"), or placed on a web server to be viewed over the 'net.

 

III. How is it run?

To run CSNAP, login (with a terminal emulation or command-line window) to the userid or account that owns the Caucus files.  Run the csnap script.  The script will prompt you for the names of the conferences you want, and for the name of a directory (where to place the output).  Alternately you may supply various options on the command line -- see the header comments in the file CML/CSNAP44/main/csnap.cml for details.

CSNAP is a relatively slow program, so be prepared to let it run a while.  Once the initial prompts are answered, it can run unattended, and will produce progress reports as it works its way through the conference(s). 

Note 1:  You can run CSNAP while Caucus is active, but if new responses are added to a conference while CSNAP is processing it, some of the resultant files may be inconsistent in places.  If you are taking the conference snapshot as a "final report", it's a good idea to close down access to the conference while CSNAP is running.

Note 2:  The Caucus userid with the same name as the userid or account that owns the Caucus files must be able to join the selected conference(s).  When CSNAP runs, it runs as if it were that user, and thus has whatever access rights that user has.

Note 3:  To run CSNAP "continuously" on a set of conferences, see the file autocsnap in the Caucus home directory.  The comments in the file contain detailed instructions for use.

 

IV. Social and Technical Notes on CDROM production

Producing a CD of a snapshot of an on-line event or set of conferences can be a really exciting and useful way to bring closure to an event.  There are some things to keep in mind, however, when producing such a CD:

  1. Security and publication.  Make sure that the contents of the CD do not cause any security or publication-related issues.  Is the information ready to be made public?  Was there clear notification in the conferences that participants' writings could be made public, or at least distributed to other participants in digital form?  Are there any copyright issues?

  2. Portability.  Remember that people may be reading the CD on a variety of platforms.  The best approach for maximum portability is to use a CD-writer package that can write both ISO9660 "Joliet extension" format, and Macintosh "HFS" format.  Such CD's are called "hybrid" CDs because they actually contain two different filesystems that point at the same set of data.  The Macintosh "Toast" software is one such package.

    CSNAP writes all of the conference files in what is called "8.3" format (all files have an up-to 8 character name followed by a dot and a 3-character extension).  This format is readable on all platforms, even in the original (non-Joliet) ISO9660 format.  However, since the length of usernames and uploaded files is outside the control of Caucus, there may still be filenames longer than "8.3".  So using at least the "Joliet" (and preferably the hybrid) format will produce better results.

  3. Ease of Use.  Once the format issue is resolved, actually making the CD is pretty straight-forward.  All of the files and subdirectories that CSNAP creates in the output directory are just copied onto the top level directory of the CD.  When the end-user reads the CD, they just point their browser to the CD, and open the "index.htm" file.

    This can be made even easier (and "slicker") for end-users who have Windows.  Just add the files shelexec.exe and autorun.inf to the top level directory of the CD.  If the Windows end-user has designated a "default browser", inserting the CD automatically pops up a browser window that displays the top-level index.htm file!

 

V. More Information and Technical Notes

  1. There is a set of (slightly dated) detailed instructions for the steps involved in creating a truly professional-looking CSNAP of a Caucus site.  (Note: the Mac CD burning software Toast 4 now makes the actual burning of the CD a trivial drag-and-drop, as opposed to the long list of steps required in the above instructions.)

  2. To get custom caucus center logos to be displayed, you must either:
    • change the variable 'cs41' in CML/CSNAP44/main/csnap.cml to be the name of the interface directory that you wish to use.  It defaults to CS41 (Caucus 4.36 or earlier) or CC44 (Caucus 4.4 or later).

    • or use the "-i interface" option on the csnap command line.  E.g. "csnap -i XYZ" uses interface XYZ instead of CS41 or CC44.

  3. The csnap script has been updated to include the FILES subdirectory (see below).  Note, however, that the CSNAP output will contain a symbolic link to the existing FILES subdirectory.  If you are copying the output directory (to make a CD, or to put the results on a different computer), you must use a method that will follow the symbolic link.  For example, if you are using unix 'tar', you must use the 'h' option.

  4. Part of the above update includes two macros, %files(name text) and %files_url(name).  Use these macros when you have files that you want to (a) manually move into your Caucus site (as opposed to going through the normal Caucus "attach a file" procedure), and (b) would like to have manually included in your CSNAP results.

    These macros assume you have created a directory called public_html/FILES in your Caucus site, and put files (or files in subdirectories) there.  Then %files(xyz.ext X Y Z) will display a pop-up link to public_html/FILES/xyz.ext, and label it "X Y Z".

 

VI. Customization

If you have Caucus 4.4 (or higher) installed, you can make custom changes to the CSNAP scripts, to make your snapshop come out the way you want.

Copy any CSNAP CML script files you want to change, from CML/CSNAP44/main, to a new directory CML/CSNAP44/main.1.  Then edit the files there (in the main.1 directory).  These files will "override" any files with the same name in the "main" directory, and they will be unaffected even if you install a later upgrade to the software.

For example, a very simple customization is to remove the "You are so-and-so" link in the upper right hand corner of each page.  (There is some debate as to the utility of that link, since it comes up the same no matter who the viewer really is.)

To make this change, copy the file youare.i from CML/CSNAP44/main to CML/CSNAP44/main.1, edit it there, and simply remove the line that says: 

   "You are <A HREF="../PEOPLE/$inc(1).htm">$per_name($inc(1))</A>.