Maintaining Your MSCS Vita

This document describes a system for maintaining vitas. There are three major components to the system:

For the impatient: how to do it.

Version Control

The Problem
The vita changes over time. It is important to be able to figure out if a given vita is up to date. It is helpful to have a record of the changes. There may even be occasions when it would be useful to be able to reconstruct an old version of a vita.

The vita files are shared files. Both you and Loretta need to work on and have access to the files. You should not both be making changes at the same time, and the changes made by one person should not get erased by the other.

A Solution
The solution that we have chosen is a software tool called RCS (Revision Control System) which was written by Walter Tichy, a computer scientist at the University of Karlsruhe. This may be a case of driving tacks with a sledge hammer, since RCS is really designed for maintaining large software packages which are being constructed by large teams of programmers. But it is easy to use and it works.

RCS is normally set up to manage the files in a certain directory, which will be called the working directory. Each file is assigned a two-part version number of the form M.N, where M and N are integers. The version number is recorded inside the file as a special comment line. Other special comment lines record the date that the file was last changed, and who made the changes.

If you wish to have access to one of the files that is controlled by RCS you must check out the file by using the command co. This creates a read-only copy of the file in the working directory. You might do this, for example, to print out a copy of your vita. If you wish to modify the file you must check out and lock it by using the command co -l . (That option is minus el). A locked file can only be modified by the person who locked it. RCS maintains an access list of the people who are allowed to check out files in the working directory. (In the case of your vita, the access list names you and Loretta.)

After making your changes you must check in the file by using the command ci . When a file is checked in its version number is changed from M.N to M.(N+1). In practice you will not need to use execute the co and ci commands yourself. This is handled automatically by make mine and make done. See the instructions.

RCS does not only save the most recent copy of the file. It maintains an archive which contains instructions for generating every previous version of the file. It also records the log messages, modification dates and so on. In the default configuration the archives are kept in a subdirectory (named RCS) of the working directory. The archive associated to the file foo.bar is named foo.bar,v and is not a binary file; it is readable by humans if necessary.

The Vita Document

The vita itself is typeset in plain TeX. The TeX file for, say, Marc Culler's vita is ~mscsinfo/vitas/culler/culler.tex. A very small macro package called mscsvita.tex is used. The use of these macros should be obvious to you after you look at your vita file. The template for a typical vita illustrates all of the TeX control sequences that are defined in mscsvita.tex.

The macro package allows you to generate a short form of your vita which omits some sections. These sections are bracketed by the control sequences \iflongvita and \fi

Each vita file begins with a short header which contains the RCS comments and a few TeX commands to specify information such as the name and e-mail address of the person whose life is being described in the vita.

The Publication List

The Problem
Typing bibliographies in TeX is a pain. There are lots of font changes. You have to remember how to abbreviate the names of all those journals. You have to remember how to cite an article that appeared in a conference proceedings that appeared in a series. And so on.

Everyone in the department follows a different convention for bibliographies.

We need a convenient way to generate a list of all papers published by department members. For example, to prepare the annual report someone has to go through the entire Greenbook and extract the list of papers published that year. Currently this chore is done by hand.

A Solution
The solution that we have chosen is to use a program called Tib which was written by James Alexander, a mathematician at the University of Maryland. Tib reads a database file and generates a TeX file which will typeset the bibliography. An ordinary text editor is used to generate the database file. The Tib program is designed to make it possible to easily cite papers from a Tib database, but we are not using these features for the vita. Those who wish to use Tib in writing papers can reuse the database entries. For those who use BibTeX, there are tools available for converting BibTeX databases to Tib format. The format of the database entries is straightforward. Here is a typical example: 
 %A Marc Culler
 %A P.~B. Shalen
 %T Varieties of representations and splittings of 3-manifolds
 %J |ANNMA2|
 %V 117
 %D 1983
 %P 109-146
Each datum is a TeX comment which begins with a field tag, %A for each author, %T for the title, and so on. A complete list of Tib field tags is available. The entry for the journal name (%J) in the example above is a Tib journal abbreviation for the Annals of Mathematics. Tib journal abbreviations are enclosed by vertical bars. When typesetting the bibliography Tib replaces the Tib abbreviation by the standard abbreviation as used in Math Reviews. You may specify your own journal name rather than use the Tib abbreviation, but it would be silly to do so.

The database of Tib journal abbreviations can be expanded to include new journals. The current list of Tib journal abbreviations is available.

Most of the common situations are covered in the list of Tib examples.

Tib handles most of the annoying details associated with preparing a bibliography without bothering you. For example, if you use an author's full first name in the %A line, Tib will automatically replace it with an initial when typesetting the bibliography.

Warning. There is one detail to be careful about. You should include your own name as an author. This is to simplify the production of the departmental publication list for the annual report. Since one is not supposed to list oneself as an author in a vita bibliography, these entries will be ignored when typesetting the vita. For this to work, however, you must spell your name the same way in the %A entry for each paper.