Managing a one-person TeX system

This page describes how to manage a one-person, local-machine, TeX system such as a one-user Linux system, or a Microsoft win32 system, or a Macintosh. Following the steps below makes it straightforward to install occasional material from CTAN (or elsewhere) and will ease any future upgrades. If you just want a reasonable procedure that won't get a casual user into trouble then you've come to the right place.

This page has two parts. First is an overview of how to lay out your directories to start, along with two step-by-step prescriptions of well-working layouts. Second are guidelines for how to install new material, with examples of how to install a new LaTeX package and how to install a new font .

The advice here assumes that you have one of the modern TeX Directory Structure -compliant distributions such as teTeX for unix-like systems, mikTeX for win32's such as Windows 98 and NT, or, also for win32's, fpTeX (which comes with the TeX Live CD-ROM ). The example operating system commands below are for a Linux system; for other systems you will need to make the small adjustments.

If you do not yet have TeX, the TeX Users Group has a list of TeX implementations , both commercial and free, for various platforms. All come complete with LaTeX, many fonts, etc. If you are just beginning with TeX or LaTeX, have a look at the starter page also.

Overview

There are two points to understand about setting up your TeX system to make it easy to maintain.

The first point arises when you want to make some change to your collection of TeX materials, for instance, if you want to add a new LaTeX package or a new font.

TeX, LaTeX, and friends deal in many small files. For example, every font used in a document may have a `font metric file' that describes how wide each character is, what is its italic correction, etc. Your TeX system can precompute the position of these files so that, instead of scanning the directory tree on your physical disk, your system finds where a file is in a database file called `ls-R', which lists that directory tree. Then your TeX goes straight to that spot in the directory structure on the disk to get the file's contents. (The software libraries that do this work are called `kpath'.)

Point One: If you make any changes to a precomputed portion of your setup then you must rebuild (or `rehash') the database of files, or your changes won't be found.
The second point relates to when you want to make a larger change, such as a once-in-a-couple-of-years updating of your entire TeX distribution. For instance, when MikTeX went from version 1.20 to version 2.0, you might have decided it was a good time to do a wholesale update.

If you've been in the habit of mixing material you've added in with the material that comes with the distribution, then you're looking at the annoying and error-prone task of trying to separate out `your' things, save them while you do the wholesale upgrade, and then add them back in again. Obviously this is not the best way to go.

Point Two: You should have a directory tree that is separate from the main tree, for local material.

Two Prescriptions

Here are two ways that you can set up your TeX system. The first is quite simple, and good enough for ninety-nine percent of users. The second is not much more complicated, and good enough for ninety percent of the remaining users. Try the first prescription, and on the small chance that you find your system responds sluggishly (which will only happen if you have a great deal of local material, or are accessing your drives over a network), switch to the second.

First, a few remarks.

Disclaimer. No solution is right for everyone. These prescriptions are intended only for single-person systems. They tilt toward simplicity of administration over leveraging the sophisticated capabilities of the software. If you are concerned with a bigger system or have specialized needs then you simply must read the kpath documentation .
More Disclamation. I am not an expert at setting the configuration file. If you have some trouble that you cannot figure out after reading the documentation and a good amount of head-scratching then you should try posting to the usenet group comp.text.tex . (I would of course be interested in any suggestions for improvement.)
You need to follow these steps only once, ideally (but not necessarily) just after you've installed a new TeX distribution.

First prescription: the most straightforward system

In this approach you will have a separate local directory tree but its files will not be precomputed into an ls-R database. So you will not run into the frustration of wondering why the system is not finding your files and only realizing some time later that you forgot to rehash the database (something I've done many times!).

Open the texmf.cnf configuration file in your favorite text editor. I did this.
```
  emacs /usr/share/texmf/web2c/texmf.cnf
```
Define a directory for local material. I found this line commented out
```
   TEXMFLOCAL=/usr/share/texmf.local
```
(it started with a percent sign). I activated it by deleting the percent sign (and dated the change in the file; sometimes that's helpful). Then I created the directory on my disk.
```
  mkdir /usr/share/texmf.local
```
Turn on searching of that local directory. A bit further down I found this line
```
   TEXMF=!!$TEXMFMAIN
```
I commented this line out by prefixing a percent sign to the line. Below it I added a new line.
```
   TEXMF={$TEXMFLOCAL,!!$TEXMFMAIN}
```
(About the twin exclamation points: they tell the system that if it does not find a file in the main tree's ls-R database then it should not go on to search the disk. That's OK because your main tree will never change since you will put new things into the local tree. So the rehashing done in step (5) will be up to date forever.)
Insure that searching of that local directory is done on disk. For certain kinds of files (such as .vf files), if the system finds a filename database in the directory tree then it will look for that file only in the database -- it will not go on to search the disk (whether there are twin exclamation points or not). Thus, for those files, forgetting to rehash results in your system saying that it cannot find files that you know are in the right place. To avoid that puzzlement, we will omit creation of that database for the local tree (or, see the second prescription below). I found this line
```
   TEXMFDBS=$TEXMF;$VARTEXFONTS
```
commented it out with a percent sign, and added this just below it.
```
   TEXMFDBS=$TEXMFMAIN;$VARTEXFONTS
```
The version with TEXMF would have caused TEXMFDBS to expand to include the local tree, but now with TEXMFMAIN it will only include the distribution's tree.
Run the command to remake the ls-R filename database. I first checked that there was no ls-R file in the local directory /usr/share/texmf.local and then I did this.
```
   texhash
```
The system responded by telling me that it had made /usr/share/texmf/ls-R (and also a /var/lib/texmf/ls-R file that has to do with user-created fonts that I will not discuss). The main point is that the system did not make /usr/share/texmf.local/ls-R. Consequently, searches of the local material will be made on disk.

Second prescription: also hash the local tree

This prescription differs from the first in only two small ways.

First, skip step (4) above. That is, leave the TEXMFDBS line as this

   TEXMFDBS=$TEXMF,$VARTEXFONTS

and then in step (5) the command to rehash will create a filename database /usr/share/texmf.local/ls-R for the local directory tree.

Second, make yourself remember that after any change to your TeX setup (such as installation of a new package or font into the local tree) you must rehash so that your system can find any changes.

Now, all that you have to remember is ...

... always put new things in the local tree, as described in step (2) of the guidelines below. Note that, as described there, files that you place in your local tree must follow a directory structure that mirrors that of the distribution tree.
... if you went with the second prescription then after you install anything you must rehash the filename database. If you went with the first prescription then there is no harm in this step, but it is not necessary, either.

Guidelines for Installation of New Material

These steps apply to installing most things from the Comprehensive TeX Archive Network . There is also an example of installing a new LaTeX style and an example of installing a new font . Naturally, these examples follow the layout described at the top of this page.

When you download a TeX package from CTAN, if the package has its own separate directory then you should fetch the entire contents of that directory. There might be something in the directory that you will need for installation, configuration, etc.

Put new files in a local texmf tree. The default TeX local root directory is as follows:

teTeX	/usr/share/texmf.local/
mikTeX	c:\localtexmf\
fpTeX	c:\fptex\texmf.local\

We will write $TEXMF for your system's local texmf root.

In your local texmf tree, imitate the directory structure in your main tree. Here's some examples of where files of given extensions should go. (Note that these are unix-style directory separators; on a win32 system change the /'s to \'s.)

.sty, .cls or .fd	$TEXMF/tex/latex/<packagename>/
.dvi, .ps or .pdf	$TEXMF/doc/latex/<packagename>/
.tfm	$TEXMF/fonts/tfm/<supplier>/<fontname>/
.vf	$TEXMF/fonts/vf/<supplier>/<fontname>/
.afm	$TEXMF/fonts/afm/<supplier>/<fontname>/
.pfb	$TEXMF/fonts/type1/<supplier>/<fontname>/
.ttf	$TEXMF/fonts/truetype/<supplier>/<fontname>/

Where of course <packagename>, <fontname> and <supplier> depend upon what's appropriate for the individual file.

Install the package. If it is a LaTeX2e package then you may need to extract the style file for LaTeX to read. Many LaTeX2e packages are written in a literate programming style, with source and documentation in the same file. The documented sources conventionally have the suffix .dtx. So, if you find the package that you want but there is no .sty, instead you see a .dtx and a .ins, then do this.
- Extract a .sty or a .cls. From the command line in the directory where you put the package, type
```
    latex <package_name>.ins
```
  (the `ins' means `install') and it will extract from the .dtx file the desired LaTeX2e-readable file.
- Extract the documentation (this is optional). Type
```
    latex <package_name>.dtx
```
  to get from the .dtx file a .dvi file that contains, typically, both usage and TeX-code documentation. (If LaTeX complains about not finding a .ind file then you can make the index with `makeindex -s gind.ist <package_name>' and then try LaTeX again.) Read the resulting .dvi in the way that you normally do. For instance, you could read it with your .dvi reader, or use `dvips -o<package_name>.ps <package_name>.dvi' to convert it to PostScript.
- Run any extra documention or test files (also optional). Naturally, test files or extra documentation are likely to use the package that they test or discuss, so this step needs to come after you've produced the .sty file.
Often there will also be a `README' file in the directory. Read it; many packages need to do something slightly different than is sketched here.

If needed, update your filename database. If you try to use your new package and get a `... not found' error then probably you forgot this step.

	from a command line	using menus
teTeX	texhash	(launch menu with:) texconfig -> REHASH
mikTeX	initexmf -update-fndb	Start-> Miktex-> Maintenance -> Refresh file name database
fpTeX	texhash	Start-> TeXLive-> Maintenance

(On older systems, the updater program might be called `mktexlsr'). If you follow the first prescription above for managing your TeX setup then there is no need to rehash, but there is no harm in it either.

Finally, if you are having trouble, you should read the documentation for the `kpsewhich' command.

Example: installing a LaTeX package

These are the steps that I went through to install the LaTeX package `SIunits' from CTAN. (As mentioned above, these example commands are appropriate for Linux; they were tested by pasting them in straight from this page. For other operating systems you need to make some small adjustments.)

I went to the search page and typed `SIunits' in the `Search CTAN files for:' box. On the response page, I clicked to get the contents of the entire directory of `macros/latex/contrib/supported/SIunits'. On the next page I chose to receive that directory as a .zip file.
With the file `SIunits.zip' on my hard drive I followed these steps.
```
  mkdir /usr/share/texmf.local/tex
```
```
  mkdir /usr/share/texmf.local/tex/latex
```
(Of course, if you have some of these directories already made then you do not need to make them. Of course, also, you need sufficient permission to make them.) I unzipped the files into the directory that I had just made.
```
  cp SIunits.zip /usr/share/texmf.local/tex/latex/
```
```
  cd /usr/share/texmf.local/tex/latex/
```
```
  unzip SIunits
```
```
  cd SIunits
```
Now that the material was in place, I needed to install the package. Because I recognized the filename extensions .dtx and .ins, and also because the readme file told me to, I ran LaTeX on the .ins file.
```
  latex SIunits.ins
```
And, to generate the documentation I ran LaTeX on the .dtx file
```
  latex SIunits.dtx
```
With that, I could read the documentation using my preferred method (which happens to be to convert to PostScript and then use GhostView).
```
  dvips -Pwww -oSIunits.ps SIunits.dvi
```
```
  gv SIunits.ps
```
Had I followed the second prescription I would have needed to have refreshed the database that TeX searches for files.
```
  texhash
```

Now I am able to `\usepackage{SIunits}' in my LaTeX files .

Example: installing a PostScript font

Fonts can be more involved than style files (lots of small files).

To get the brushscript font (which is a PostScript decorative italic font), I went to www.ctan.org/tex-archive and browsed the fonts directory, which led me to the brushscr subdirectory. From there, I clicked to get the contents of the entire directory. On the next page I chose to receive that directory as a .zip file.

Then, with the file on my hard drive, I created the local font source tree.

  mkdir /usr/share/texmf.local/fonts

  mkdir /usr/share/texmf.local/fonts/source

  mkdir /usr/share/texmf.local/fonts/source/public

With the directory tree set up, I unzipped the files.

  cp brushscr.zip /usr/share/texmf.local/fonts/source/public

  cd /usr/share/texmf.local/fonts/source/public

  unzip brushscr

  cd brushscr

Now I'm in the local font source directory for `brushscr'. The file `AAA_readme.tex' suggested that I could run the `make' program.
```
  make 
```
This created a number of new font files along with a `generate.log' that recorded what happened. To put these font files in the right place, I looked at the layout of the various file types in the distribution's font directory tree /usr/share/texmf/fonts . I made out that I first needed to copy the .tfm font metric file to where TeX would find it.
```
  mkdir /usr/share/texmf.local/fonts/tfm
```
```
  mkdir /usr/share/texmf.local/fonts/tfm/public
```
```
  mkdir /usr/share/texmf.local/fonts/tfm/public/brushscr
```
```
  cp *.tfm /usr/share/texmf.local/fonts/tfm/public/brushscr
```
Second, I needed to copy the .vf virtual font files to their place.
```
 mkdir /usr/share/texmf.local/fonts/vf
```
```
 mkdir /usr/share/texmf.local/fonts/vf/public
```
```
 mkdir /usr/share/texmf.local/fonts/vf/public/brushscr
```
```
 cp *.vf /usr/share/texmf.local/fonts/vf/public/brushscr
```
Third, I needed to put the .fd files in the TeX input directory (and I'll copy the LaTeX .sty file there while I'm at it).
```
  mkdir /usr/share/texmf.local/tex/latex/brushscr
```
```
  cp *.fd /usr/share/texmf.local/tex/latex/brushscr
```
```
  cp *.sty /usr/share/texmf.local/tex/latex/brushscr
```
Fourth, I need to copy the .pfa files (these are the actual fonts, encoded as ASCII; more common are the .pfb files, which are binary versions of the same thing).
```
  mkdir /usr/share/texmf.local/fonts/type1
```
```
  mkdir /usr/share/texmf.local/fonts/type1/brushscr
```
```
  cp *.pfa /usr/share/texmf.local/fonts/type1/brushscr
```
Finally (because I use dvips to convert .dvi files to PostScript), I copied its configuration file to the local tree
```
  mkdir /usr/share/texmf.local/dvips
```
```
  mkdir /usr/share/texmf.local/dvips/config
```
```
  cp /usr/share/texmf/dvips/config/config.ps /usr/share/texmf.local/dvips/config/config.ps
```
and I copied `pbsi.map'.
```
  cp pbsi.map /usr/share/texmf.local/dvips/config
```
I edited the new configuration file.
```
  emacs /usr/share/texmf.local/dvips/config/config.ps
```
I found the lines that say, `This shows how to add your own map file. Remove the comment and adjust the name:' and the next line says `p +myfonts.map' (but it is commented out with a percent sign). I added a line just below that to say (without the percent sign) `p +pbsi.map'.
Had I gone with the second prescription I would have needed to have refreshed the database that TeX searches for files.
```
  texhash
```

Now I can use the BrushScript font in my TeX files .

Sample file

With that style file installation and that font installation , this input file

		 \documentclass{article}
                 \usepackage[T1]{fontenc}
                 \usepackage{pbsi}  
                          
                 \usepackage{SIunits}
                          
                 \begin{document}
                 \begin{center}
                   \bsifamily\Huge A Successful Test
                 \end{center}
                          
                 Big news!
                 We have a running system.
                 It does units such as $9.8 \metre\per\sec$
                 and it also does things in a \textbsi{fancy font}! 
                 \end{document}"

when I ran it through LaTeX, through the dvi-to-PostScript converter, and through the PostScript viewer GhostView

  latex test.tex

  dvips -Pwww -otest.ps test.dvi

  gv test.ps

produced the right output (here converted to .png format with the GIMP for web display).

About this page: CTAN contact information , the CTAN home page, revised 2001-Oct-08 (for new Brushscript) by Jim Hefferon. Adapted from two posts to the usenet group comp.text.tex, one by A. Goreham on 2000-Nov-02 and one by Michael J. Downes on 2001-Mar-26. Improved with suggestions from Thomas Esser and Stefan Ulrich. Additional corrections, suggestions, or pointers to similar pages for other TeX implementations would be very welcome.