5.1.1 Using an existing package

To use a package already installed on your system, insert a \usepackage command in your document preamble with the package name in curly braces, as we have already seen in earlier chapters. For example, to use the xcolor package, which lets you typeset in colours (I warned you this was coming!), you would type:

\documentclass[11pt,a4paper,oneside]{report}
\usepackage{xcolor}
\begin{document}
...
\end{document}

You can include several package names in one \usepackage command by separating the names with commas, and you can have more than one \usepackage command.

Some packages allow optional settings in square brackets. If you use these, you must give the package its own separate \usepackage command, like geometry and xcolor shown below:

\documentclass[11pt,a4paper,oneside]{report}
\usepackage{pslatex,palatino,avant,graphicx}
\usepackage[margin=2cm]{geometry}
\usepackage[svgnames]{xcolor}
\begin{document}

\title{\color{Crimson}Practical Typesetting}
\author{\color{DarkSlateBlue}Peter Flynn\\Silmaril Consultants}
\date{\color{ForestGreen}January 2011}
\maketitle

\end{document}

(Incidentally, this is a very crude and cumbersome way to do colours in titling. It's fine for a one-time document, but it will interfere with running heads if you use them; and if it's for a repeatable style we'll see in Chapter 9 how it can be automated as part of the \maketitle command and kept out of the author's way.)

Many packages can have additional formatting specifications in optional arguments in square brackets, in the same way as geometry and xcolor do. Read the documentation for the package concerned to find out what can be done.

  Exercise 12. Add colour

Use the xcolor package to add some colour to your document. Stick with primary colours for the moment.

Use the geometry package to change the margins.

Reprocess and print your document if you have a colour printer (monochrome printers should print it in shades of grey).

5.1.2 Package documentation

To find out what commands a package provides (and thus how to use it), you need to read the documentation. The simplest way is to use your command window and type texdoc followed by the package name. This will bring up the documentation in your PDF or DVI viewer.

If that doesn't find it, in the texmf/doc subdirectory of your installation there should be directories full of .dvi and .pdf files, one for every package installed. These can be previewed or printed like any other DVI or PDF file (see section 4.3.1). If your installation procedure has not installed the documentation, the files can all be downloaded from CTAN.

Before using a package, you should read the documentation carefully, especially the subsection usually called ‘User Interface’, which describes the commands the package makes available. You cannot just guess and hope it will work: you have to read it and find out.

See the next section for details of how to generate the documentation for additional packages you install yourself.

  Exercise 13. Read all about it

Find and view (or print) the documentation on the geometry package you used in the example ‘Add colour’ in section 5.1.1.

Investigate some of the other package documentation files in the directory.

5.2.1 Downloading packages

What you need to look for is always two files, one ending in .dtx and the other in .ins. The first is a DOCTEX file, which combines the package program and its documentation in a single file. The second is the installation routine (much smaller). You must always download both files.

If the two files are not there, it means one of two things:

• Either the package is part of a much larger bundle which you shouldn't normally update unless you change version of LATEX;¹

• or it's one of a few rare or unusual packages still supplied as a single .sty file originally intended for the now obsolete LATEX 2.09.²

Download both files to a temporary directory. If you use Windows, keep a folder like C:\tmp or C:\temp for this; Mac and Linux systems already have a /tmp directory.

1. For example, there is no xcolor.dtx and xcolor.ins for the xcolor package because it forms part of the graphics bundle, which is installed on all LATEX systems anyway. Such packages change very rarely, as they form part of the core of LATEX and are very stable. In general you should never try to update these packages in isolation.
2. You can try to use these if you wish but they are not guaranteed to work, and have now almost all been replaced by LATEXε versions. Always look for the .dtx and .ins pair of files first.

5.2.2 Installing a package

There are four steps to installing a LATEX package:

1. Extract the 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 is it), or if you prefer, type latex followed by the .ins filename in a command window in your temporary directory.

   This will extract all the files needed from the .dtx file (which is why you must have both of them present in the temporary directory). 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 LATEX on the .dtx file twice. This will create a .dvi 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 you prefer to create PDF then run pdfLATEX instead. View or print this file in the usual manner (see section 4.3).

3. Install the files
   

   While the documentation is printing, move or copy the files created in step 1 from your temporary directory to the right place[s] in your TEX's local installation directory tree — always your ‘local’ directory tree, a) to prevent your new package accidentally overwriting files in the main TEX directories; b) to avoid your newly-installed files being overwritten when you next update your version of TEX.

   Table 5.1. Where to put files from packages

   Type	Directory (under your localtexmf/)	Description
   .cls	tex/latex/base	Document class file
   .sty	tex/latex/packagename	Style file: the normal package content
   .bst	bibtex/bst/packagename	BIBTEX style
   .mf	fonts/source/public/typeface	METAFONT outline
   .fd	tex/latex/mfnfss	Font Definition files for METAFONT fonts
   .fd	tex/latex/psnfss	Font Definition files for PostScript Type 1 fonts
   .pfb	/fonts/type1/foundry/typeface	PostScript Type 1 outline
   .afm	/fonts/afm/foundry/typeface	Adobe Font Metrics for Type 1 fonts
   .tfm	/fonts/tfm/foundry/typeface	TEX Font Metrics for METAFONT and Type 1 fonts
   .vf	/fonts/vf/foundry/typeface	TEX virtual fonts
   .dvi	/doc	package documentation
   .pdf	/doc	package documentation
   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 TEX Directory Structure (TDS). For a TDS-conformant system, this is either a) for LATEX packages, a suitably-named subdirectory of your localtexmf/tex/latex/ directory³; b) a suitably-named subdirectory of your localtexmf/ directory for files like BIBTEX styles or font files which are not just for LATEX but can be used in other TEX systems.

   If you really don't know where your local TEX directory tree starts, see the panel ‘Finding out where LATEX looks for stuff’ in this appendix.

   • Unix and GNU/Linux systems should have a /usr/local/share/texmf/ directory;

   • Apple Mac systems should have a ~/Library/texmf folder;

   • MIKTEX systems appear to use the installation directory at C:\Program Files\MikTeX 2.8\tex (but with auto-install you don't need to know this).

   ‘Suitably-named’ means sensible and meaningful (and probably short). For a package like paralist, for example, I'd call the directory paralist.

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

   If there are configuration or other files, read the documentation to find out if there is a special or preferred location to move them to.

4. Update your index
   

   Finally, run your TEX indexer program 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 editor. Read the documentation that came with your installation to find out which it is.

  Run your TEX indexer program after making changes

This last step is utterly essential, otherwise nothing will work.

  Exercise 14. Install a package

Download and install the paralist package (which implements inline lists).

The reason this process has not been automated widely is that there are still 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. 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 political or security reasons (such as a shared system where she cannot write to a protected directory).

The reason for having the local texmf directory (called texmf-local or texmf.local on some systems) is to provide a place for local modifications or personal updates, especially if you are a user on a shared or managed system (Unix, Linux, VMS, Windows NT/2000/XP, etc.) where you may not have write-access to the main TEX installation directory tree. You can also have a personal texmf subdirectory in your own login directory. Your installation should already be configured to look in these directories first, so that any updates to standard packages will be found there before the [superseded] 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 this appendix.

3. See section 5.2.3 for how to create a parallel structure in your local TEX directory if your installation didn't create one for you.

5.2.3 Replicating the TDS

The TEX Directory Structure (TDS) is documented at http://www.tug.org/tds/. I find it useful to make the subdirectory structure of your local texmf directory the same as that of the main installation texmf directory. Examine the subdirectories of texmf/tex/latex/ for examples. For updates of packages which came with your LATEX distribution (as distinct from new ones you are adding yourself), you can then use the same subdirectory name and position in your local texmf/... as the original used in the main texmf/..., and LATEX will then always use the updated version.

If you want to create the entire subdirectory structure ready for use, you can do it under Unix with the following commands (this example uses the Ubuntu/Debian directory /usr/local/share/texmf rather than the Red Hat /usr/share/texmf-local):

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

If you are using Microsoft Windows, you can download Cygwin, which provides you with the standard Unix tools in a shell window. The above command also works on a Mac running OS X if you use /usr/local/texlive/yyyy/texmf-dist in the first command (replacing yyyy with the year of the distribution) and ~/Library/texmf/{} in the second. In other cases, if your directories are not as given in the example, you need to substitute the actual paths to your main texmf and local texmf directories.

5.3.1 The FAQ

For general queries you should read the Frequently-Asked Questions (FAQ) document so that you avoid wasting online time asking about things for which there is already an easily-accessible answer.

The FAQ is managed by the UK TEX Users Group and can be found at http://www.tex.ac.uk/faq/ .

5.3.2 The TEXhax mailing list

Another support resource is the mailing list texhax@tug.org. Again, feel free to ask questions, but again, try to answer the question yourself first (and say what you've tried in your message).

5.3.3 Web sites

The TEX Users Group, as well as most local user groups, maintains a web site (http://www.tug.org) with lots of information about various aspects of the TEX system. See this appendix for information on joining TUG.

5.3.4 News

The Usenet newsgroup comp.text.tex is the principal forum for other questions and answers about LATEX. Feel free to ask questions, but please do not ask frequently-asked questions: read the FAQ instead. The people who answer the questions do so voluntarily, unpaid, and in their own time, so please don't treat this as a commercial support service.

To access Usenet news, type the following URI into your browser's ‘Location’ or ‘Address’ window: news:comp.text.tex (if your browser doesn't support Usenet news properly, change it for one that does, like Mozilla), or download one of the many free newsreaders.⁴

4. Note that this means newsreaders for the Usenet News (NNTP) service. It does not mean syndication readers for RSS, which are a different thing entirely — these are unfortunately also sometimes referred to as ‘newsreaders’.

5.3.5 Google LATEX list

There is a Google Groups mailing list for LATEX users at http://groups.google.com/group/latexusersgroup?hl=en

5.3.6 Commercial support

If you need commercial levels of support, such as 24-hour phone contact, or macro-writing services, you can buy one of the several excellent commercial versions of TEX, or contact a consultancy which deals with TEX (details on the TUG Web site).