The citthesis Document Class

Andrew D. Lewis andrew@mast.queensu.ca

7 March 1997 Last Updated: 27 October 1997

1 Introduction

This is documentation for the L^{A}TEX document class citthesis. As the name suggests, this document class has been designed to make a format for a Doctor’s thesis at The California Institute of Technology. Most of the adaptation was done by Kevin Otto from the MIT thesis style. I have taken what Kevin did, and converted it to a nice document class usable with L^{A}TEX 2ε. It is now something quite different from Kevin’s original…

2 What You Should Have

This package should come with four directories, bin, demo, doc, and sty. The bin directory contains the scripts that you will need to make full use of this package. The demo directory contains a little thesis so you can play and see how everything described below works. The toy thesis also serves as a platform for demonstrating the features of citthesis. The directory doc contains the TEX source for this documentation. The sty directory contains the necessary L^{A}TEX class and package files. These may have to be processed using the directions included (probably in the file 00readme.txt) and then the style files should be placed where TEX can get at them.

3 The Directory Layout

To begin using the citthesis document class, make a directory where all your TEX files will be placed for your thesis. Make subdirectories for each chapter titled chapter1,…,chaptern, where n is the number of chapters your thesis has. Also make directories appendix_a,…,appendix_a_{k} where a_{k} is the kth letter of the alphabet, and k is the number of appendices you have. In each of these subdirectories put any files that will be read in during the processing of that chapter or appendix. Also, make a link in each such subdirectory to itself. Thus, if the subdirectory is named chapterk, type

    ln -s . chapterk

This enables you to TEX in each subdirectory separately and so make corrections to each chapter without having to compile the whole thesis. This will be discussed in Section 4.

Important note: The above links are not made in the demo directory so that the directories may be tarred properly. Therefore, in order to use the demo as indicated below, you will need to make the links in the chapter and appendix subdirectories.

Another Important Note: You should make sure you understand fully what is going on with the symbolic linking as described above. If you do not understand this, you will get all screwed up trying to make things work in each chapter separately as well as working in the main directory. This has been a source of confusion! Prove you deserve that PhD! ;-)

4 The Makefiles

To drive the whole process of compiling your thesis, the main directory, and each of the chapter subdirectories should have its own Makefile. Models for the Makefiles are included in the demo directory. There are various options. In the list below, the central file refers to the file which is the driver TEX file in the directory you are working in, whether this be the main directory, or one of the chapter subdirectories.

make [default] : This will run TEX once on your central file, then run BibTEX, then run TEX twice. This may be set up to do whatever you want, but the idea is that it produces a .dvi file with all references resolved.

make tex : This runs TEX once on your central file.

make bib : This runs BibTEX once on your central file.

This will crash if there is no .aux file present.

   make dvi  : The same as make [default].

make ps : Will take the .dvi file created and make a PostScript file from it. This will crash if you have no .dvi file present.

make clean : This removes all files created during a TEX run

(things like .aux, .log, and .dvi files).

make ps_clean : Does a clean plus removes the PostScript file

if it is present.

   make all  : Does make dvi, make ps, then make clean.

make very_clean : This will do a make clean in each subdirectory.

   make ispell_clean: Removes the .bak files left by ispell.

make update : This will do a make in each subdirectory.

1 Note that the above options, except for the last three, are available in both the main directory and in each chapter subdirectory. You will probably have to edit the Makefiles to suit your own purposes. In particular, there are some variables that are defined that will likely be local to your machine. A model is given in the demo directory that comes with this package. It should be clear how to affect any necessary changes. The differences in the Makefiles in the two types of directories is discussed in the next two sections.

1There are make index, make aindex, and make los targets as well if you are going to use indexing facilities. The target make los is for a list of symbols and this requires the MakeSymbolIndex program which you can get from my homepage (see end of documentation). Also useful is the index.sty package available from CTAN which allows multiple indexes.

4.1 The Main Directory Makefile

The Makefile in the main directory will have a list called alldirs which contains the names of the chapter subdirectories. If you have set up your directory tree as suggested, this should be OK the way it is. In the main directory, it is also possible to execute the make abstract option. This will TEX the file abstract_filename where filename is the name of the central file in your main directory. If you wish you can add options to build your acknowledgements, title page, etc. separately.

4.2 The Subdirectory Makefiles

In the Makefile in the chapter subdirectories the list alldirs contains the directories in the main directory. The options make update and make very_clean are not available in the chapter subdirectories.

A Reiteration of Another Important Note: This is a good time to remind you to think about the symbolic links do. What happens when you L^{A}TEX the contents of a chapter subdirectory? How does this work when you try to run L^{A}TEX in the root directory? Be sure you understand what is going on in the demo before proceeding. (I apologise to experienced UNIX users for whom all this is obvious.)

5 Writing Your Thesis

So here is how to write your thesis (you have to do the research yourself…). Copy^{2} the contents of the directory demo to the directory where you will have your thesis. The file main.tex (I have chosen to call the driver files in each directory main.tex) has the data like your name, the date of the thesis, and all that. You should change that stuff to meet your requirements. What you name all the other files in the directory is up to you. You don’t have to follow what I do in the demo! This data is also in the file abstract_main.tex so if you plan on using the make abstract option, you need to make the changes there as well. The file containing the acknowledgements should be in the main directory. In the demo thesis, the main directory and in the chapter1 subdirectory will contain the file citthesis.bib. This file is present only to prevent crashes in the demo. As soon as you have your own citations, and have put them in a place where BiBTEX can read your database file, you can get rid of the citthesis.bib files. Into each subdirectory put the appropriate TEX files that are to be read in. Handling figures is a matter of preference. I will leave it up to each uses to figure out how to handle that.

Now that all your directories are in place, you can get stuff going. To make a copy of a chapter type make in the subdirectory containing that chapter. This way you can write each chapter separately and not have to compile the whole document each time you make a little change. When you finally have everything straightened out, go the the main directory and type make. Let it chug for a few minutes, and then you will have a beautiful thesis which meets the requirements of the Caltech graduate office.

2Be careful when copying symbolic links. It may be better to tar the whole business then untar it in the new location.

6 Making a Technical Report From Your Thesis

Frequently you will want to make a technical report out of your thesis. Unfortunately, the requirements for a thesis at Caltech do not necessarily lend themselves to the most easily read document. To fix this, you may specify the techreport option when you select the citthesis document class. This option will give you single spacing and running headers which make for an easy reading document. The copyright page, the acknowledgements, and the abstract will not be present when you make a technical report. Nothing needs to be done to remove them. You will have to include a specification of the department when you make a technical report. You do this by using the command \department at the same time you specify the author, date, and title. You may also supply a technical report number with the \techreportnumber command. This is optional. If you specify the department and/or a technical report number and do not use the techreport option, there will be no problems.

Other than adding the department name, you should not have to do anything to get a decent looking technical report. Of course there may be TEX hacking that needs to be done. To aid such hacking the command

    \techreporttest{command1 }{command2 }

is available. Here command1 is executed if the techreport option is requested. Otherwise command2 is executed. This allows you to make hacks appropriate to when techreport is either on or off.

To check all this out, simply specify the techreport option in the demo thesis.

7 Miscellaneous

Here are some things you may like to know.

1. The default point size for citthesis is 11pt. The other available point sizes are 10pt and 12pt.

2. The default for citthesis is for one-sided printing. This is what Caltech requires. However, the two-sided option is available for making copies other than official ones.

3. There is a citthesis bibliography style. The appropriate .bst file is included in the sty directory.

4. Included in the bin directory is a script called rispell. If you have ispell installed you can use this script to do a recursive spell check by typing rispell. If you type rispell directory ispell will be run on all files *.tex in directory.

5. It is possible that you may wish to exclude the abstract or the acknowledgements in certain copies of your thesis. To do this, simply specify the noabstract or noacknowledgements option when you select the citthesis document class. It is possible to omit the abstract in the same manner with the noabstract option.

Please send any comments and errors to: andrew@mast.queensu.ca.

URL: http://penelope.queensu.ca/~andrew/