# Formatting information ## A beginner's introduction to typesetting with LA TEX ### Chapter 5 — CTAN, packages, and online help ### Peter Flynn #### Silmaril Consultants Textual Therapy Division v. 3.6 (March 2005)
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 LA TEX 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 LA TEX 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. | This document is Copyright © 1999–2005 by Silmaril Consultants under the terms of what is now the GNU Free Documentation License (copyleft). Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled The GNU Free Documentation License. You are allowed to distribute, reproduce, and modify it without fee or further requirement for consent subject to the conditions in section D.5. The author has asserted his right to be identified as the author of this document. If you make useful modifications you are asked to inform the author so that the master copy can be updated. See the full text of the License in Appendix D.

CHAPTER
5
| # CTAN, packages, and online help

The Comprehensive TEX Archive Network (CTAN) is a repository of Web and FTP servers worldwide which contain copies of almost every piece of free software related to TEX and LA TEX.

CTAN is based on three main servers, and there are several online indexes available. There are complete TEX and LA TEX systems for all platforms, utilities for text and graphics processing, conversion programs into and out of LA TEX, printer drivers, extra typefaces, and (possibly the most important) the LA TEX packages. The three main servers are:

- TEX Users Group: `http://www.ctan.org/`

- UK TEX Users Group: `http://www.tex.ac.uk/`

- Deutschsprachige Anwendervereinigung TEX e.V. (DANTE, the German-speaking TEX Users Group); `http://dante.ctan.org/`

## 5.1 Packages

Add-on features for LA TEX are known as packages. Dozens of these are pre-installed with LA TEX and can be used in your documents immediately. They should all be stored in subdirectories of `texmf/tex/latex` named after each package. To find out what other packages are available and what they do, you should use the CTAN search page which includes a link to Graham Williams' comprehensive package catalogue.

A package is a file or collection of files containing extra LA TEX commands and programming which add new styling features or modify those already existing. Installed package files all end with `.sty` (there may be ancillary files as well).

When you try to typeset a document which requires a package which is not installed on your system, LA TEX will warn you with an error message that it is missing (see section 4.2.3.6), and you can then download the package and install it using the instructions in section 5.2. You can also download updates to packages you already have (both the ones that were installed along with your version of LA TEX as well as ones you added).

There is no limit to the number of packages you can have installed on your computer (apart from disk space!), but there is probably a physical limit to the number that can be used inside any one LA TEX document at the same time, although it depends on how big each package is. In practice there is no problem in having even a couple of dozen packages active (the style file for this document uses over 30).

### 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 color package, which lets you typeset in colours (I warned you this was coming!), you would type:

>     \documentclass[11pt,a4paper,oneside]{report}
>     \usepackage{color}
>     \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 shown below:

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

>     \title{\color{red}Practical Typesetting}
>     \author{\color{blue}Peter Flynn\\Silmaril Consultants}
>     \date{\color{green}December 2005}
>     \maketitle

>     \end{document}

(Incidentally, this is a rather crude way to do colours in titling on a once-off basis: if it's for a repeatable style we'll see in Chapter 9 how it can be automated 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 does. Read the documentation for the package concerned to find out what can be done.

> #### Exercise 12. Add colour

> Use the color 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).

CMYK and RGB are not the only colour models. Uwe Kern's xcolor package defines half a dozen, and includes facilities for converting colour values from one model to another.

### 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. In the `texmf/doc` subdirectory of your installation there should be directories full of `.dvi` files, one for every package installed. These can be previewed or printed like any other DVI file (see section 4.3.1). If your installation procedure has not installed the documentation, the DVI 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 create the documentation `.dvi` file 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 Downloading and installing packages

Once you have identified a package you need and haven't already got (or you have got it and need to update it), use the indexes on any CTAN server to find the package you need and the directory where it can be downloaded from.

### 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 LA TEX;1

- or it's one of a few rare or unusual packages still supplied as a single `.sty` file intended for the now obsolete LA TEX2.09.2

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 `color.dtx` and `color.ins` for the color package because it forms part of the graphics bundle, which is installed on all LA TEX systems anyway. Such packages change very rarely, as they form part of the core of LA TEX 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 LA TEXε 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 LA TEX package:

1. Extract the files

   Run LA TEX on the `.ins` file. That is, open the file in your editor and process it as if it were a LA TEX 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 LA TEX 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 LA TEX 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 pdfLA TEX 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 local installation directory tree — always your ‘local’ directory tree, a) to prevent your new package accidentally overwriting files in the main TEX directories; and 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 `texmf-local/`) | 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 (UNDEFINED ACRONYM). For a TDS-conformant system, this is either a) for LA TEX packages, a suitably-named subdirectory of `texmf-local/tex/latex/`3; or b) a suitably-named subdirectory of `texmf-local/` for files like BIBTEX styles which are not just for LA TEX but can be used in other TEX systems.

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

> 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 `texmf-local` directory (called `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 must be configured to look in these directories first, however, so that any updates to standard packages will be found there before the superseded copies in the main `texmf` tree. All modern TEX installations should do this anyway, but if not, you can edit `texmf/web2c/texmf.cnf` yourself. There is an example in this appendix.

3. See section 5.2.3 for how to create a parallel structure in your local 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 directory structure of `texmf-local` the same as that of `texmf`. Examine the subdirectories of `texmf/tex/latex/` for examples. For updates of packages which came with your LA TEX distribution (as distinct from new ones you are adding yourself), you can then use the same subdirectory name and position in `texmf-local/...` as the original used in `texmf/...`.

If you want to create the entire subdirectory structure ready for use, you can do it under Unix with the following commands:

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

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 should also work on a Mac running OS X. In all cases, if your installation directory is not `/usr/TeX`, you need to substitute the actual paths to your `texmf` and `texmf-local` directories.

## 5.3 Online help

The indexes and documentation files on CTAN are the primary online resource for self-help on specific packages, and you should read these carefully before asking questions about packages.

### 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 LA TEX. 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

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