Formatting information

A beginner's introduction to typesetting with LATEX

Appendix A — Configuring search paths

Peter Flynn

Silmaril Consultants
Textual Therapy Division

v. 3.6 (March 2005)


  1. Installing TEX and LATEX
  2. Using your editor to create documents
  3. Basic document structures
  4. Typesetting, viewing and printing
  5. CTAN, packages, and online help
  6. Other document structures
  7. Textual tools
  8. Fonts and layouts
  9. Programmability (macros)
  10. Compatibility with other systems
  1. Configuring TEX search paths
  2. TEX Users Group membership
  3. The ASCII character set
  4. GNU Free Documentation License

This edition of Formatting Information was prompted by the generous help I have received from TEX users too numerous to mention individually. Shortly after TUGboat published the November 2003 edition, I was reminded by a spate of email of the fragility of documentation for a system like LATEX which is constantly under development. There have been revisions to packages; issues of new distributions, new tools, and new interfaces; new books and other new documents; corrections to my own errors; suggestions for rewording; and in one or two cases mild abuse for having omitted package X which the author felt to be indispensable to users. ¶ I am grateful as always to the people who sent me corrections and suggestions for improvement. Please keep them coming: only this way can this book reflect what people want to learn. The same limitation still applies, however: no mathematics, as there are already a dozen or more excellent books on the market — as well as other online documents — dealing with mathematical typesetting in TEX and LATEX in finer and better detail than I am capable of. ¶ The structure remains the same, but I have revised and rephrased a lot of material, especially in the earlier chapters where a new user cannot be expected yet to have acquired any depth of knowledge. Many of the screenshots have been updated, and most of the examples and code fragments have been retested. ¶ As I was finishing this edition, I was asked to review an article for The PracTEX Journal, which grew out of the Practical TEX Conference in 2004. The author specifically took the writers of documentation to task for failing to explain things more clearly, and as I read more, I found myself agreeing, and resolving to clear up some specific problems areas as far as possible. It is very difficult for people who write technical documentation to remember how they struggled to learn what has now become a familiar system. So much of what we do is second nature, and a lot of it actually has nothing to do with the software, but more with the way in which we view and approach information, and the general level of knowledge of computing. If I have obscured something by making unreasonable assumptions about your knowledge, please let me know so that I can correct it.

Peter Flynn is author of The HTML Handbook and Understanding SGML and XML Tools, and editor of The XML FAQ.



Configuring TEX search paths



    TEX systems run on a huge variety of platforms, and are typically made up of a large number of rather small files. Some computer operating systems have problems with packages like this, as their built-in methods for searching for a file when needed are poor.

    To get around this, TEX uses a technique borrowed from the Unix world, based on a simple hash index for each directory they need to look in. This is known as the ls-R database, from the Unix command (ls -R) which creates it. The program which does this for TEX is actually called after this command: mktexlsr, although it may be renamed texhash or something else on your system. This is the program referred to in step 4.

    However, to know where to make these indexes, and thus where to search, TEX needs to be told about them. In a standard TEX installation this information is in texmf/web2c/texmf.cnf. The file is similar to a Unix shell script, but the only lines of significance for the search paths are the following (this is how they appear in the default Unix installation, omitting the comments):

    TEXMFMAIN = /usr/TeX/texmf
    TEXMFLOCAL = /usr/TeX/texmf-local
    HOMETEXMF = $HOME/texmf
    VARTEXFONTS = /var/lib/texmf

    As you can see, this defines where the main TEX/METAFONT directory is, where the local one is, and where the user's personal (home) one is. It then defines the order in which they are searched, and makes this the system-wide list. A temporary directory for bitmap fonts is set up, and added to the list, defining the places in which texhash or mktexlsr creates its databases.

    In some installations, the local directory is set up in /usr/local/share/texmf or /usr/share/texmf.local or similar variations, so you would substitute this name for /usr/TeX/texmf-local. Under Microsoft Windows, the names will be full paths such as C:\Program Files\TeXLive\texmf. On an Apple Mac, it might be Hard Disk:TeX:texmf.

    If you edit plain-text configuration files with anything other than a plain-text editor (e.g. a wordprocessor), or if you edit them with a plain-text editor which has been set to word-wrap long lines, make sure you turn line-wrapping off so that any long lines are preserved in their correct format.

    Previous Top Next