Introduction

For many years, the TCB Group has prepared its major reports and proposals using RCS, the Unix Revision Control System. While not as full-featured as CVS, it offers most everything we need to use locally - version control, access by multiple users, good Makefile support - without being too complex. As such, we will likely continue to use it for years to come to support large, multi-author documents.

Rather than trying to re-invent the RCS documentation, new users are encouraged to review the RCS man pages:

• man rcs
• man co
• man ci

Further information is available on the RCS homepage, or in the "Applying RCS/SCCS" book from the TCB Group Library.

Using RCS with TCB Reports

The first step for using our RCS trees is to create a sub-directory in your home directory for the report; this will hold your local copies of the data, which you can work on without modifying the other users' data. In here should be links to the RCS and FIGS directories from the main report directory, given by the proposal maintainer. The RCS directory is for the LaTeX files you will be writing; the FIGS directory is for EPS and PDF figures, which are not so often modified.

You can create and populate these directories thusly:

   cd; mkdir MYREPORT2004; cd MYREPORT2004
   ln -s /home/Proposal/REPORT2004/RCS /home/Proposal/REPORT2004/FIGS .
   co RCS/*

This will check out all current files in the RCS directory. An 'ls' should show you a lot of '*.tex' files (NOT *.tex,v; if you see those, you're in the wrong directory!). Note that these files will not be locked, so others will be able to check them out; if you want to work on your specific file, you will have to check it out and lock it while you're working on it, as so:

• co -l MYFILE.tex
• Edit file
• ci MYFILE.tex

Make sure you only lock the files you are actively working on, and that you check those in as soon as possible! Do not keep files checked out for longer than you need to.

The files are compiled into their final PDF form using pdflatex, which is invoked through the shared Makefile (also in RCS). To use this Makefile, type:

• make - makes the proposal in PDF form.
• make locks - determines which files are currently locked.
• More options may be found by looking at the Makefile; it should be fairly easy to understand.

A final checklist of points to to keep in mind:

• NEVER, EVER WRITE DIRECTLY INTO THE RCS DIRECTORY!!!
  While this warning is sent out every year, almost everytime somebody forgets and writes directly into the directory. This screws up processing and hurts the entire group. BE CAREFUL! I wouldn't be yelling if I didn't think it was important.
• Make sure to only keep files checked out for as long as you're using them. And only work on what you can manage.
  • This especially applies to the bibliography files (*.bib) that are used by everyone in the group regularly.
• Before you check in anything in, rebuild the proposal in your work space to ensure that it all still works. You don't want to check in a broken file and make life more difficult for others.
• It is often faster to run your 'make's on a fast Linux box or other machine with good serial performance. Also, if your test builds are taking too long, you may want to build into local disk space instead of the shared file system.
• Write good changelogs. It's well worth spending thirty seconds to document what you have done now, rather than spending hours later trying to work out when you made a fateful change...