Installing and using custom packages and style files

All modern TeX distributions contain a standard set of document classes and packages. The standard document classes include the classes article, book, amsart, amsbook; the standard packages include the amslatex packages (amsmath, amsthm, etc.) graphicx, xy, fancyhdr, and many more. (To find out if a particular package is available on our system, use the "locate" command; for example, locate fancyhdr will generate a list of files containing the string "fancyhdr"; these include documentation files and the main package file, recognizable by the .sty extension, fancyhdr.sty.)

Unless there is a particular reason to do otherwise, it is recommended to only use classes and packages that are part of the standard distribution. Using non-standard classes or packages significantly reduces the portability of a document. A TeX document requiring a non-standard document class will not compile on systems that do not have the appropriate class file installed. If you send such a file to a colleague at another university, or submit it to an editor of a journal, they will likely have to go through the trouble of downloading the necessary class files in order to process the document. Even if you send along the class file, getting TeX to find and load a class file is, as explained below, a non-trivial task that would leave most people utterly frustrated.

That said, there are situations in which you have to use a custom class file or custom packages. For example, your university may have a thesis class or package available that is customized to the university's format requirements. Also, many journals ask authors of accepted papers to prepare and submit the final version of their paper using in-house style files. (For the reasons mentioned above, I would suggest to use a standard class when writing the paper, and to switch to custom style files only at the time the publisher so requests. This usually occurs at a very late stage in the publication cycle, after the paper has been accepted for publication.)

Document classes and other style files are usually made available for downloading at a publisher's website. For example, the AMS has a separate document class for each of its journals: proc-l.cls for the Proceedings, tran-l.cls for the Transactions, etc. After you have downloaded the necessary files, you have to make these visible to TeX. This is accomplished by the following two steps. (Note: The following instructions are for the UIUC Math Department's Unix network. At other sites, or under different operating systems, the procedures may be slightly different.)

Create a private tex hierarchy. Under your home directory, create a subdirectory "texmf", underneath that directory create another one called "tex". and under this one create a "latex" directory. Thus, you should have a tree of the form
$HOME/texmf/tex/latex/
Place document class files (extension .cls), packages and any other custom style files for use by LaTeX (extensions .sty or .tex) into this directory.
If custom bibtex style files (extension .bst) have been provided, place these into a similar tree of the form
$HOME/texmf/bibtex/bst/
Run the "texhash" program. Simply type "texhash" at the prompt. This will create a database of files inside your texmf directory. The database file is called, appropriately enough, "ls-R", and is located in the top level texmf directory, i.e., the file is $HOME/texmf/ls-R . The ls-R file is an ordinary text file and can be inspected with an editor or a pager like more or less. If the texhash run was successful, this file should contain a listing of all files under your private texmf directory.
Important. Whenever you add new files to your texmf tree, be sure to run texhash. For efficiency reasons, TeX does not search for files, but only consults the ls-R database; if a (non-standard) file is not listed in this database, TeX will not find it.

Note on TEXINPUTS and similar variables. TEXINPUTS is one of several environment variables that are used by TeX. However, it is not recommended to change this or any similar variable, as this will likely have unintended side effects. The proper way to make files or directories visible to TeX is by placing them in an appropriate place in the private texmf hierarchy, as described above.

Back to the LaTeX Tips Page

Last modified: Tue 23 Aug 2011 05:49:20 PM CDT A.J. Hildebrand