MATH 640-499 Class 14:
Thursday, March 11, 1999
Introduction to LaTeX packages

LaTeX should be viewed as a coordinated set of macros for Donald Knuth's TeX program. These macros are presented as packages, each of which can be loaded either by giving its name as an argument for the \documentclass command, if the package implements a document class, or for the \usepackage command. Thus, the package for a document class called valentine would be invoked by the command \documentclass{valentine}, and would be stored in a file called valentine.cls.

Some examples of LaTeX packages that we have used are the amsmath package, the graphics packages epsf, epsfig and graphix, and the article document class. All of these are included in the "base distribution" of LaTeX. There are other document classes in the base distribution, such as the letter class, book class and report class.

Beyond the packages that are included in the base distribution of LaTeX there are many others available at various places. For example, if you want to read the electronic preprints of physics papers written in LaTeX and available on the Web (for example, at Los Alamos ) you will sometimes have to use the revtex package, which is used for papers prepared for Physical Reviews. We have a copy installed on clam, crab and carp, but if you wanted to use it somewhere else, you might need to get a copy and install it yourself.

Similarly, if you want to submit a review to Mathematical Reviews, you will need special packages for that purpose.

We have seen that LaTeX allows you to define your own commands. This means that any user can extend LaTeX. We have seen some very small examples of this with the custom commands. Actually, any user can extend LaTeX in other ways as well, for example, by creating new environments, new symbols, and even providing bookkeeping on some aspects of a document. This is possible because LaTeX is a programming language though not a very sophisticated one. Examples of things that can be done include creating new packages (like amsmath) and new document classes. Many people have written such packages and contributed their work to the Comprehensive TeX Archive Network (CTAN). There you can find packages for a variety of tasks. We will look at some examples of how to locate, download, install, and use a few of these packages. For the rest of this class, I would like you to go through the activities described below.

For now you should be able to use the packages that you download provided that they are in the current directory or in your new macros/ directory.

Of course, most of us don't have the expertise needed for writing a LaTeX package or a new LaTeX document class, but even the experts can take advantage of the work contributed to the Comprehensive TeX Archive Network (CTAN) by other users.

For example, suppose that you would like to find a LaTeX package to help make it easier to compose exams.

A good place to start to search for a package is TeX and LaTeX Catalogue: Packages and tools, mostly available on CTAN. (about 1 Meg). This has an html search engine, an alphabetical index, and a listing available by FTP.

WARNING: the links at this site seem to be obsolete. Here is a good alternative that features help on browsing CTAN by FTP.

Since it will be convenient to use FTP for getting LaTeX packages, we record some of the basic information here for users in the U.S. From a prompt, give the command line 

   ftp tug.ctan.org
Give your username as ftp and, for a password, give your email address. The commands dir, cd, pwd work as you would expect from your experience with UNIX systems.

The command for searching for files that contain a given string looks like this: 

   quote site index string
where the word "string" is to be replaced by the particular string you want to find, of course.
Let's go to the alphabetical index and look for files that have names starting with the string "exam". We find that there are three packages that look interesting: You can also find these packages by going to the TeX Users Group CTAN directory /tex-archive/macros/latex/contrib/supported/,
and the links here seem to function properly (as of March 1999).

Of these packages, the first looks like the easiest to use. The author says that the package "attempts to make it easy for even a LaTeX novice to prepare exams." In fact, it does seem easy to use. It defines a new documentclass called "exam". That is, you start your LaTeX source file with \documentclass{exam}, and then there are some special commands available. For example, you make a list of questions by writing 

\begin{questions}
\question Here is the text of the first question
\question Here is the text of the next question
  .
  .
  .
\end{questions}
Each question can have several parts. Moreover, there are commands to display point values for questions and commands to add up the total point value of all questions.

The file exam.cls is a LaTeX class file. This contains the macros that are loaded when you use the exam documentclass. The file examdoc.tex is a LaTeX source file that provides documentation that explains how to use the exam documentclass.

While you are using your browser, you can probably download a file to your own account by putting the cursor on the name of the file, holding down the SHIFT key and clicking the LEFT mouse button. If this does not work, try using the file menu, which should list a save command.

Grab the file examdoc.tex, and execute the command latex examdoc. You will probably get a message advising you that you may need to run LaTeX again on the file, in which case you should go ahead and run LaTeX on the file again. After two or three times, you should stop getting the message about running latex again. Now you can view the documentation file on screen by running xdvi examdoc.dvi & and you can print out the file by running dvips examdoc. You can then grab the file exam.cls.

The examdesign package illustrates a method of distribution that is common with more elaborate LaTeX packages. There are two essential files: exam.dtx and exam.ins. Run the command latex exam.dtx to get documentation for the package. If you run the command latex exam.ins, then the class file exam.cls will be created automatically from the file exam.dtx.

You should create a subdirectory, say "macros/" of your root directory, and then make it available to LaTeX by adding a line to your ".cshrc" file (the resource file for the C-shell).
NOTE: It is important to make a backup copy of your .cshrc file.
After backing up the file .cshrc if you are using clam, you can add the following line, but be sure to include the "." just before the ":". 
    setenv TEXINPUTS .:~/macros//:/usr/local/lib/tex/macros//
This line instructs TeX to look for packages first in the current directory (indicated by the dot), then in your directory ~/macros/ and then the system directory. The double slash insures that TeX will look into subdirectories. If you are are using scivis, then the following line may work: 
    setenv TEXINPUTS .:~/macros//:/usr/freeware/lib/texmf/tex//
After you have saved your new .cshrc file, you can put it into effect by typing 
     source .cshrc
You should first test out your new .cshrc file by running a simple LaTeX file that you know has run correctly before.

Now you should be able to use the packages that you download provided that they are either in the current directory or in your new macros/ directory.

email to:Martin Karel