Your support for our advertisers helps cover the cost of hosting, research, and maintenance of this document

Formatting Information — An introduction to typesetting with LATEX

### In this section…

If you’re using a system which has the tlmgr auto-installer, you don’t need this section except for very rare occasions. The TEX Live Package Manager can be used to find, download, and install packages without you needing to know anything about where they come from or where they get put. The rest of this chapter is for people who want to do it by hand.

If you have to install a package manually, you can use the indexes on any CTAN server to find the package you need and the directory where it can be downloaded.

Some packages are available as ZIP files in TEX Directory Structure (TDS) format, which is faster and more convenient to use. Others are just plain zip files, or you can download all the needed files individually.

If you go to a package’s CTAN page (http://ctan.org/pkg/name) this will show the package details, and if the package is available in TDS format, there will be a link labelled ‘TDS archive’ with a file ending in .tds.zip.

Download this and unzip it straight into your personal TEX directory, where LATEX will find it first, overriding any other version that might have been installed with your distribution. The correct place for your personal TEX directory is described in § A.2.

If there is no TDS zip file, there will be a prominent link at bottom right labelled ‘Download the contents of this package in one zip archive’.

Download the zip file to a temporary directory. If you use Windows, create a folder like Computer\System\Users\your~name\temp or just C:\tmp or C:\temp for this; Mac and Linux systems already have a /tmp directory.

Unzip it, then move the files into the directories as shown in Table 3.1.

If there is no ZIP file at all, what you need to look for is almost always two files, one ending in .dtx and the other in .ins. The first is a DOCTEX file, which combines the package programs and their documentation in a single file. The second is the installation program (much smaller). You MUST always download both these files (and maybe others in the download folder) if there is no ZIP file.

If neither the two files nor the package ZIP are there, it means one of two things:

• Either the package is part of a much larger bundle which you SHOULD NOT normally update yourself unless you are updating your entire LATEX system;

• or it’s one of a few rare or unusual packages still supplied as a single hand-made .sty or .cls file originally written for the now obsolete LATEX 2.09, or perhaps by an author who has a doctrinal or philosophical objection to using DOCTEX.

On Unix-based systems (including Mac OS X and GNU/Linux), that's all you need to do. On Windows systems running MiKTEX, you MUST reindex your File Name Database (FNDB, see the last step ‘Shared systems and MIKTEX: update your index’) before LATEX will be able to find the new files.

### 3.2.2 Installing a class or package manually

There are four steps to installing a LATEX class or package:

1. Extract the class or package files

Use your directory browser of file manager (eg My Computer, Finder, Thunar, Dolphin, etc) to find the folder where you unzipped or downloaded the .dtx and .ins files.

Run LATEX on the .ins file. That is, open the file in your editor and process it as if it were a LATEX document (which it is), or if you prefer, type latex followed by the .ins filename in a command window in the directory where the file is.

This will extract all the files needed from the .dtx file (which is why you must have both of them present in the directory).

If this is a non-TDS zip file, or individually-downloaded files, note down or print the names of the files created if there are a lot of them (read the log file if you want to see their names again).

2. Create the documentation

Run PDFLATEX on the .dtx file twice. This will create a .pdf file of documentation explaining what the package is for and how to use it. Two passes through LATEX are needed in order to resolve any internal crossreferences in the text (a feature we’ll come onto later). If there is a BIBTEX file of references, or if you need the Index, you will need to process bibtex, biber, makeindex, or other ancillary programs. I very strongly recommend doing this with the Build menu of your editor, or with the latexmk tool.

3. Install the files

This step is not needed if you used a TDS zip file.

Move the files created in the step ‘Extract the class or package files’ from your temporary directory to the right subdirectories in your personal TEX directory (see below). Always put the files in your ‘personal’ TEX directory tree, a) to prevent your new package accidentally overwriting master files in the main TEX directories and b) to avoid your newly-installed files being overwritten when you next update your version of TEX. Never, never, NEVER put files into your TEX distribution’s main directory tree. (If you are updating a shared system, however, you can put the files into the local (shared) TEX directory tree.)

### Table 3.1: Where to put files from packages

 Type Subdirectory Description .cls tex/latex/classname Document class file .sty tex/latex/packagename Package (style) file .bst bibtex/bst/packagename BIBTEX style file .dvi doc/packagename package documentation .pdf doc/packagename package documentation .fd tex/latex/mfnfss Font Definition files for METAFONT fonts .fd tex/latex/psnfss Font Definition files for PostScript Type 1 fonts .fd tex/latex/typeface Font Definition files for other fonts .mf fonts/source/public/typeface METAFONT font outline .pfb fonts/type1/foundry/typeface PostScript Type 1 outline .ttf fonts/truetype/foundry TrueType font files .otf fonts/opentype/foundry OpenType font files .afm fonts/afm/foundry/typeface Adobe Font Metrics .tfm fonts/tfm/foundry/typeface TEX Font Metrics .vf fonts/vf/foundry/typeface TEX virtual fonts .png tex/generic PNG images .jpg tex/generic JPG images others tex/latex/packagename other types of file unless instructed otherwise

‘The right place’ sometimes causes confusion, especially if your TEX installation is old or does not conform to the TDS. For a TDS-conformant system, ‘the right place’ is your personal TEX directory tree unless you are a systems manager updating a shared machine, in which case it’s the local TEX directory tree. Your personal TEX directory tree is in your home directory (folder):

• Unix & GNU/Linux systems: ~/texmf/

• Apple Macintosh OS X: ~/Library/texmf;

• Windows systems: Computer/username/texmf (on obsolete Windows systems you can use C:\texmf).

Create this directory now if it does not already exist. You will need to create subdirectories within this directory: see Table 3.1.

Often there is just a .sty file to move but in the case of complex packages there may be more, and they belong in different locations. For example, new BIBTEX packages or font packages will typically have several subdirectories of files to install. This is why it is important to create a subdirectory for the package within your personal TEX directory, rather than dump the files into misc along with other unrelated stuff.

4. Shared systems and MIKTEX: update your index

On Unix & GNU/Linux systems (including Apple Macintosh OS X) you MUST NOT run the TEX indexer program or create an ls-R database in your personal TEX directory. These systems search your personal TEX directory automatically.

Otherwise:

• Windows MIKTEX users (only) MUST use the MIKTEX Administration program to add your new personal TEX folder to MIKTEX’s search tree when you first create it.

After that, each time you update files in there, you MUST run the File Name DataBase (FNDB) updater in the MIKTEX Administration program, otherwise TEX will never see your newly-installed files.

• If you are updating a shared system, putting the files into the local TEX directory tree, you MUST run your TEX indexer program afterwards to update the package database.

This program comes with every modern version of TEX and is variously called texhash, mktexlsr, or even configure, or it might just be a mouse click on a button or menu in your configuration system (like MIKTEX’s). Read the documentation that came with your installation to find out which it is.

### On MIKTEX and shared systems, run your TEX indexer program after making changes

This step is essential, otherwise nothing will work.

### Exercise 10: Install a package

The tlmgr auto-updater is widely used in TEX Live systems except where TEX has been installed from Debian-based Unix system packages. On Windows and Apple Mac, and on Unix systems where TEX Live has been installed from the TUG DVD or download, tlmgr is the normal way to update packages. The manual process described above is only for those cases where tlmgr cannot be used.

This includes the thousands of installations which do not conform to the TDS, such as old shared Unix systems and some Microsoft Windows systems, so there is no way for an installation program to guess where to put the files: you have to know this yourself. There are also systems where the owner, user, or installer has chosen not to follow the recommended TDS directory structure, or is unable to do so for policy or security reasons (such as a shared system where she cannot write to a locked disk or directory).

The reason for having the local texmf directory (usually called texmf-local or texmf.local) is to provide a place for local modifications on a shared or managed system (such as a server) which will override but otherwise not interfere with the main TEX installation directory tree. Your installation should already be configured to look in the personal and local directories first, so that any updates to standard packages will be found there before the copies in the main texmf tree. All modern TEX installations do this, but if not, you can edit texmf/web2c/texmf.cnf (or on a shared system, ask your systems manager or support person to do so). There is an example in § A.5.

### 3.2.3 Replicating the TDS

If you have a distribution which has installed an auto-updater like tlmgr then you’ll probably never have to update a package manually anyway, so you won’t need this section unless you need to install something from outside the standard distribution such as a private, corporate, or commercial package or typeface.

The TEX Directory Structure is documented at http://www.tug.org/tds/. I find it useful to make the subdirectory structure of your personal TEX directory (eg texmf, see § A.2) the same as that of the main installation texmf directory, so that I have all the main branches of the tree ready for future use. Examine the subdirectories of texmf/tex/latex/ in your installation for examples. For additions to packages which came with your LATEX distribution, you can then use the same subdirectory name and position in your personal TEX directory as the original used in the main texmf/... directory. LATEX will then always use the updated version.

If you want to recreate the entire subdirectory structure ready for use, you can do it under Unix & GNU/Linux systems (including Apple Macintosh OS X) with the commands below. This example uses the Ubuntu/Debian directory /usr/local/share/texmf rather than MacTEX’s /usr/local/texlive/yyyy/texmf-dist (replacing yyyy with the year of the MacTEX distribution) or Red Hat’s /usr/share/texmf-local, so modify the cd command appropriately, and on a Mac, use ~/Library/texmf/{} in the second command:

```cd /usr/local/share/texmf
find . -type d -exec mkdir -p ~/texmf/{} \;
```

Windows provides no way of doing this, although you could install Cygwin, which provides you with the standard Unix tools in a Command window.

1. MiKTEX users MUST note that you cannot process .ins files inside MiKTEX’s own installation folders: you have to process them elsewhere first, hence the need for a temporary directory.

2. For example, there is no separate xcolor.dtx and xcolor.ins for the xcolor package because it forms part of the graphics bundle, which is included with all LATEX systems anyway. Such packages change very rarely, as they form part of the kernel of LATEX and are very stable. You should never try to update these packages in isolation.

3. Almost all of these have been updated to work with LATEX, so they should be installed as in the penultimate step ‘Install the files’, but there are a few remaining.