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.

  1. 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.

  2. 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.

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!).

  1. Open the texmf.cnf configuration file in your favorite text editor. I did this.
      emacs /usr/share/texmf/web2c/texmf.cnf
  2. Define a directory for local material. If your configuration file has a line that says something like
       TEXMFLOCAL=$SELFAUTOPARENT/share/texmf
    then you are fine; leave it alone. Some older distributions instead have a line like
       TEXMFLOCAL=/usr/local/share/texmf
    commented out (it starts with a percent sign). If yours is commented out, then below it put the non-commented $SELFAUTOPARENT line (and date the change in the file; sometimes that's helpful). Check that you have the directory on your disk, and create it if needed.
      mkdir /usr/local/share/texmf
  3. Turn on searching of that local directory. A bit further down I found this line
       TEXMF = {$HOMETEXMF,!!$TEXMFLOCAL,!!$TEXMFMAIN}
    I commented this line out by prefixing a percent sign to the line. Below it I added a new line
       TEXMF={$HOMETEXMF,$TEXMFLOCAL,!!$TEXMFMAIN}
    in which I've deleted the twin exclamation points. The twin exclamation points 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. (Older versions have a
       TEXMF=!!$TEXMFMAIN
    line which you can comment out and replace with what's above.)
  4. 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.
  5. 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/local/share/texmf 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/local/share/texmf/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/local/share/texmf/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 ...


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.

  1. 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.

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

    teTeX /usr/local/share/texmf/
    mikTeX c:\localtexmf\
    TeXLive c:\Program Files\TeXLive\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.

  3. 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.

    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.

  4. 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.)

  1. 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.
  2. With the file `SIunits.zip' on my hard drive I followed these steps.
      mkdir /usr/local/share/texmf/tex
      mkdir /usr/local/share/texmf/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/local/share/texmf/tex/latex/
      cd /usr/local/share/texmf/tex/latex/
      unzip SIunits
      cd SIunits
  3. 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
  4. 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).

  1. 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.
  2. Then, with the file on my hard drive, I created the local font source tree.
      mkdir /usr/local/share/texmf/fonts
      mkdir /usr/local/share/texmf/fonts/source
      mkdir /usr/local/share/texmf/fonts/source/public
    With the directory tree set up, I unzipped the files.
      cp brushscr.zip /usr/local/share/texmf/fonts/source/public
      cd /usr/local/share/texmf/fonts/source/public
      unzip brushscr
      cd brushscr
  3. 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/local/share/texmf/fonts/tfm
      mkdir /usr/local/share/texmf/fonts/tfm/public
      mkdir /usr/local/share/texmf/fonts/tfm/public/brushscr
      cp *.tfm /usr/local/share/texmf/fonts/tfm/public/brushscr
    Second, I needed to copy the .vf virtual font files to their place.
     mkdir /usr/local/share/texmf/fonts/vf
     mkdir /usr/local/share/texmf/fonts/vf/public
     mkdir /usr/local/share/texmf/fonts/vf/public/brushscr
     cp *.vf /usr/local/share/texmf/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/local/share/texmf/tex/latex/brushscr
      cp *.fd /usr/local/share/texmf/tex/latex/brushscr
      cp *.sty /usr/local/share/texmf/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/local/share/texmf/fonts/type1
      mkdir /usr/local/share/texmf/fonts/type1/brushscr
      cp *.pfa /usr/local/share/texmf/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/local/share/texmf/dvips
      mkdir /usr/local/share/texmf/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/local/share/texmf/dvips/config
    I edited the new configuration file.
      emacs /usr/local/share/texmf/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'.
  4. 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 2002-Jun-21 (for new texmf.cnf local layout) 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, Stefan Ulrich, and Bill Lawry. Additional corrections, suggestions, or pointers to similar pages for other TeX implementations would be very welcome.  Internet connection provided by Saint Michael's College