3.  Updating and Re-indexing.

      This section describes the commands that are used to manipulate and change the data base. It explains the procedures for (a) finding references in the data base, (b) adding new references, (c) changing existing references, and (d) deleting references. Remember that all changes, additions, and deletions are done by preparing separate files and then running an `update and reindex' step.

      Checking what's there now. Often you will want to know what is currently in the data base. There is a special command lookbib to look for things and print them out. It searches for articles based on words in the title, or the author's name, or the date. For example, you could find the first paper above with

lookbib aho ullman maximal subsequence 1976
lookbib aho ullman hirschberg

If you don't give enough words, several items will be found; if you spell some wrong, nothing will be found. There are around 4300 papers in the public file; you should always use this command to check when you are not sure whether a certain paper is there or not.

      Additions. To add new papers, just type in, on one or more files, the citations for the new papers. Remember to check first if the papers are already in the data base. For example, if a paper has a previous memo version, this should be treated as a change to an existing entry, rather than a new entry. If several new papers are being typed on the same file, be sure that there is a blank line between each two papers.

      Changes. To change an item, it should be extracted onto a file. This is done with the command

pub.chg key1 key2 key3 ...
where the items key1, key2, key3, etc. are a set of keys that will find the paper, as in the lookbib command. That is, if
lookbib johnson yacc cstr
will find a item (to, in this case, Computing Science Technical Report No. 32, ``YACC: Yet Another Compiler-Compiler,'' by S. C. Johnson) then
pub.chg johnson yacc cstr
will permit you to edit the item. The pub.chg command extracts the item onto a file named ``bibxxx'' where ``xxx'' is a 3-digit number, e.g. ``bib234''. The command will print the file name it has chosen. If the set of keys finds more than one paper (or no papers) an error message is printed and no file is written. Each reference to be changed must be extracted with a separate pub.chg command, and each will be placed on a separate file. You should then edit the ``bibxxx'' file as desired to change the item, using the UNIX editor. Do not delete or change the first line of the file, however, which begins %# and is a special code line to tell the update program which item is being altered. You may delete or change other lines, or add lines, as you wish. The changes are not actually made in the public data base until you run the update command pub.run (see below). Thus, if after extracting an item and modifying it, you decide that you'd rather leave things as they were, delete the ``bibxxx'' file, and your change request will disappear.

      Deletions. To delete an entry from the data base, type the command

pub.del key1 key2 key3 ...
where the items key1, key2, etc. are a set of keys that will find the paper, as with the lookbib command. That is, if
lookbib aho hirschberg ullman
will find a paper,
pub.del aho hirschberg ullman
deletes it. Upper and lower case are equivalent in keys; the command
pub.del Aho Hirschberg Ullman
is an equivalent pub.del command. The pub.del command will print the entry being deleted. It also gives the name of a ``bibxxx'' file on which the deletion command is stored. The actual deletion is not done until the changes, additions, etc. are processed, as with the pub.chg command. If, after seeing the item to be deleted, you change your mind about throwing it away, delete the ``bibxxx'' file and the delete request disappears. Again, if the list of keys does not uniquely identify one paper, an error message is given.

      Remember that the default versions of the commands described here edit a public data base. Do not delete items unless you are sure deletion is proper; usually this means that there are duplicate entries for the same paper. Otherwise, view requests for deletion with skepticism; even if one person has no need for a particular item in the data base, someone else may want it there.

      If an item is correct, but should not appear in the ``List of Publications'' as normally produced, add the line

to the item. This preserves the item intact, but implies ``Do Not List'' to the to the commands that print publication lists. The DNL line is normally used for some technical reports, minor memoranda, or other low-grade publications.

      Update and reindex. When you have completed a session of changes, you should type the command

pub.run file1 file2 ...
where the names ``file1'', ... are the new files of additions you have prepared. You need not list the ``bibxxx'' files representing changes and deletions; they are processed automatically. All of the new items are edited into the standard public data base, and then a new index is made. This process takes about one minute of processor time. The index is not made by re-analyzing and re-sorting the entire data base; the new or changed items are indexed in the usual way and then merged with the previous data files. A complete re-index would be much slower for small changes.

      Normally, you should execute pub.run just before you logoff after performing some edit requests. However, if you don't, the various change request files remain in your directory until you finally do execute pub.run. When the changes are processed, the ``bibxxx'' files are deleted. It is not desirable to wait too long before processing changes, however, to avoid conflicts with someone else who wishes to change the same file. If executing pub.run produces the message ``File bibxxx too old'' it means that someone else has been editing the same file between the time you prepared your changes, and the time you typed pub.run. You must delete such old change files and re-enter them.

      Note that although pub.run discards the ``bibxxx'' files after processing them, your files of additions are left around even after pub.run is finished. If they were typed in only for purposes of updating the data base, you may delete them after they have been processed by pub.run.

      Example. Suppose, for example, that you wish to

Add to the data base the memos ``The Dilogarithm Function of a Real Argument'' by R. Morris, and ``UNIX Software Distribution by Communication Link,'' by M. E. Lesk and A. S. Cohen;
Delete from the data base the item ``Cheap Typesetters'', by M. E. Lesk, SIGLASH Newsletter, 1973; and
Change ``J. Assoc. Comp. Mach.'' to ``Jour. ACM'' in the citation for Aho, Hirschberg, and Ullman shown above.

The procedure would be as follows. First, you would make a file containing the additions, here called ``new.1'', in the normal way using the UNIX editor. In the script shown below, the computer prompts are in italics.

$ ed new.1
%T The Dilogarithm Function of a Real Argument
%A Robert Morris
%M TM 78-1271-1
%D 1978

%T UNIX Software Distribution by Communication Link
%A M. E. Lesk
%A A. S. Cohen
%M TM 78-1274-1, 78-8234-1
%D 1978
w new.1
Next you would specify the deletion, which would be done with the pub.del command:
$ pub.del lesk cheap typesetters siglash

to which the computer responds:

Will delete: (file bib176)

%T Cheap Typesetters
%A M. E. Lesk
%J ACM SIGLASH Newsletter
%V 6
%N 4
%P 14-16
%D October 1973
And then you would extract the Aho, Hirschberg and Ullman paper. The dialogue involved is shown below. First run pub.chg to extract the paper; it responds by printing the citation and informing you that it was placed on file bib123. That file is then edited.
$ pub.chg aho hirschberg ullman
Extracting as file bib123
%T Bounds on the Complexity of the Maximal
Common Subsequence Problem
%A A. V. Aho
%A D. S. Hirschberg
%A J. D. Ullman
%J J. Assoc. Comp. Mach.
%V 23
%N 1
%P 1-12
%M TM 75-1271-7
%D Jan. 1976

$ ed bib123
/Assoc/s/ J/ Jour/p
%J Jour. Assoc. Comp. Mach.
%J Jour. ACM
%# /usr/dict/papers/p76 233 245 change
%T Bounds on the Complexity of the Maximal
Common Subsequence Problem
%A A. V. Aho
%A D. S. Hirschberg
%A J. D. Ullman
%J Jour. ACM
%V 23
%N 1
%P 1-12
%M TM 75-1271-7
%D Jan. 1976

Finally, execute pub.run, making sure to remember that you have prepared a new file ``new.1'':
$ pub.run new.1
Currently, this takes about 1 minute of 11/70 processor time.