Editorial Procedures for

Changes to TEI Guidelines


Document TEI ED A83

C. M. Sperberg-McQueen

19 December 1996

rev. 4 February 1997

Table of Contents

This document summarizes the directory structures, tools, and procedures for use in editing chapters of the TEI Guidelines. It describes the current state of affairs and should apply (mutatis mutandis) to future systems.

1 Basic Principles

The master copies of the Guidelines are housed on machines at each editorial site; each site has

Version-control systems (currently: RCS) are used to keep prior versions of each file available and to help manage file locking.

To the extent possible, all machines used to house master copies should have the same setup: TEI files should have the same directory structure, and the same tools should be available for working with them. When the systems have different tools, the editors should write programs (e.g. shell scripts) to mask the differences as far as possible. This similarity is not an end in itself; its purpose is to simplify the tasks of editing the Guidelines and reduce the chances of time-consuming or catastrophic errors.

2 Directory Structure

2.1 Master and Shadow Directories

There are two sets of directories: one for the live master copies of the files, and one for working copies of files currently being edited.

Master copies of the files are :

Each of these directories has an RCS subdirectory containing RCS-controlled copies of older versions.

In an ideal world, these two directories would each be remotely mounted on the other machine via NFS or something similar, so that each editor could work just on the local machine. In practice, this doesn't always work, so each machine should have a read-only shadow copy of the other machine's files.

2.2 Working Directories

Working directories, for files currently checked out by one editor, are on each machine at

Each of these four directories will have an RCS subdirectory symbolically linked to the corresponding master RCS subdirectory, so that a file can be checked in to the master RCS directory from the editors' working directories.

The following invariants govern the relationships of these directories and should be preserved by all procedures:

2.3 Search Paths and SGML Open Directories

System identifiers in all files should have the file name and extension (in 8+3 form, for maximum portability) only, without any directory information.

To pick up the current production version of each file, software relying on system identifiers should search these directories in this order:

To pick up the newest changes to each file currently being worked on locally, and the production versions of files being worked on by the other editor, the following search path should be used:

When public identifiers are used, SGML Open catalogs should be provided to guide the resolution, thus:

and

To get production copies of all files, software which handles public identifiers should start with the catalog file in the master directory; to get working copies with the newest changes, it should start in the working directories.

2.4 Summary

3 Tools

To simplify maintenance and problem solving, the editors should agree on languages to use for shell scripts and major programs. At present, shell scripts should be written in ksh, csh, or TCL.

There is no current agreement on the language(s) to be used in programs to be shared by the editors; at the time this is written, current production programs are in standard Spitbol, Spitbol with Catspaw extensions, Rexx, C, TCL, and Perl.

The following tools are currently available on tigger.cc.uic.edu and should be available on onions.natcorp.ox.ac.uk:

4 Procedures

This section provides checklists for checking files in and out and performing various maintenance tasks. These tasks should probably be automated as time permits.