How to use the various packages and fonts

I realized only lately that what's obvious for me could be a big problem for others and led to horrible headaches, so here is a little guide about how to effectively use what you can download from this small site. A TeX/LaTeX system is a complex thing, so before starting to modify your local installation, please, read what follows very carefully.

One last note: the following information is provided "as is" and without any warranty of any kind either expressed of implied. The entire risk as to the quality and performance of your system is with you. Should the information prove defective, you assume the cost of all necessary servicing, repair or correction.

Everything in place and a place for everything

A TeX/LaTeX system has a complex directory structure clearly detailed in A Directory Structure for TeX Files by the TUG Working Group on a TeX Directory Structure (this document is usually available in your local installation as tds.dvi). Here I don't assume you have read that document and we actually will end up using just little bits of that big structure, but if you have nothing better to do or want to understand more deeply what's going on behind the scene, feel free to read it.

Three trees are a forest

TeX and related programs look for specific files in well know locations: a system wide directory tree, a so called "local" directory tree and, in true multiuser operating systems, a per user private local directory tree. Modification and additional packages should be put in the local directory tree by the system administrators and in the private local directory tree by normal users. The system wide tree is not the safest place to put your custom packages or new fonts because an upgrade to your TeX/LaTeX distribution will probably wipe them out.

Where these trees are and what they are called is subject to your TeX/LaTeX distribution designer and to operating system constraints. Here I will go into details only for MikTeX (a popular Windows distribution), teTeX (the de facto standard distribution in the unix-like world) and TeXLive (a distribution available for a large number of platform, including Windows). The concepts here expressed will certainly apply also to other distributions but details will vary.

Searching order

Ideally, the search order followed by TeX and related programs should be:

  1. the private tree
  2. the local tree
  3. the system wide tree

to give users a chance to "overwrite" some configurable behaviour and upgrading things without messing with the system files, but your distribution could do things in a different way and so I wouldn't be able to help you too much (search order is configurable but it's a complex matter and you should ask help to a local expert).

Perhaps you could find this useful: in a teTeX system, the system configuration file texmf.cnf should define variable TEXMF as:

TEXMF = {$HOMETEXMF,!!$TEXMFLOCAL,!!$TEXMFMAIN}

From this point onward, let me assume that $TEXMFLOCAL represents your local tree. Almost everything that follows will apply unchanged to the three TeX/LaTeX distributions above mentioned. Obviously, in a multiuser environment you need system administrator powers to do any changes to the system wide tree and to the local tree; if you can't use system administrator powers you have to use the private tree in your home directory.

The packages

After all this technical stuff, installing a package is quite simple so take heart and keep reading.

Styles, classes and *.fd should go in $TEXMFLOCAL/tex/latex/, so to install TengTeX create a tengtex/ subdirectory and put tengtex.tex (the Plain TeX wrapper), tengtex.sty (the style file) and the various *.fd files (font description files) there.

Documentation is optional and should go in $TEXMFLOCAL/doc/latex/, so for TengTeX docs create a subdirectory named tengtex/ (for human convenience because is not used by the system (even if some LaTeX distributions have a semi-authomatic mechanism to retrive docs)) and move them there.

The Metafont sources

Metafont files (*.mf) should go in $TEXMFLOCAL/fonts/source/public/, optionally dividing them in more than one subdirectory according their author/name (so, a tiad/ directory for Computer Modern Tengwar, or a teng10/ for Bradfield's font and so on); this division is really optional because TeX works even if you keep everything together, but it really helps humans not to mess everything up :-)

Modern TeX/LaTeX distributions will generate the needed bitmap fonts (*pk) on demand the first time you use them, so there is no need to produce dozens of fonts now and I am not going to explain how to do it.

Refresh

After all these steps you only need one more thing that is often forgot: you must rebuild the database-like structure used by your distribution to speed up searching; the right way depends on the distribution: for MikTeX there's a "Refresh now" command available starting from the Windows' Start menu; for TeXLive there is a similar menu entry (you can also update it by hand running texhash); for teTeX on unix-like machines run the command texhash as root.

Type1 fonts with pdfLaTeX

There's more than a way to produce pdf documents of good quality, but here I'll write only about the use of pdfTeX/pdfLaTeX, a program able to produce directly pdf documents.

To use the Type1 fonts with pdfLaTeX you must instruct it to do so using particular files called font maps. The font archives contains a little text file labeled mappa which lists the fonts of that archive in a manner suitable for using them with pdfLaTeX.

The first thing to do is copying the contents of those files mappa in a new text file (remember to use a text editor for this operation, not a word processor) which you can call as you wish; let me suggest a name like mytengwarfonts.map just for convenience. Put this new file in $TEXMFLOCAL/pdftex/config/

The next step is to locate the file pdftex.cfg in your system wide tree. Once you have found it, copy this file in the same location of mytengwarfonts.map and edit it with a text editor (don't use a word processor!). All you have to add is the single following line at the end of the file:

map +mytengwarfonts.map

Now, if your distribution order search is the Right Order next time you run pdfLaTeX it will read this configuration file and so will end up using also our new font map file.

We're almost there: we still need to copy the fonts and metrics in the right places. Move *.pdf in a new subdirectory of your choice in $TEXMFLOCAL/fonts/type1/public/ and move *.tfm in a new subdirectory of your choice in $TEXMFLOCAL/fonts/tfm/public/ (a wise thing it to call the two subdirectories with the same name). Now rebuild your distribution's database-like structure as outlined above.

If it does not work...

...before anything else try this way: put everything in a single directory and run latex by hand on tengdoc.tex; if it still doesn't work, then there's something terribly wrong in your TeX/LaTeX distribution (or some evil forces don't want let you appreciate the beauty of TengTeX :-)) because in this scenario LaTeX and related programs should be able to find everything without any problem.

This strategy is not useful for troubleshooting problems with Type1 fonts, but if we limit ourselves to Metafont fonts and use latex+dvips by hand we should get a PostScript document identical to the one distributed with the TengTeX bundle.

If you get something working, then try to understand what could have been wrong previously: it could be the search order, or you forget to rebuild the database-like structure or put something in the wrong place. I could be able to help you, but if you write to me for help, please, try to be as precise as possible (operating system, TeX/LaTeX distribution, what you did and what you did not, what worked and what didn't work and the error messages you certainly got) or we'll probably end up fighting forever against wind mills.

Last modified: Thu Jul 31 17:43:14 2003

Valid HTML 4.01! Valid CSS!