Let’s Learn Latex: Part 5

LaTeX is fully extensible. Just about every command you can think of can be overloaded and redefined in your document. Or the document class definition. Or a custom made package file. This is the beauty of this system. You can start creating great looking documents just using the base system, and if you need to do something fancy you can start pulling in third party modules and code that adds more and more functionality. At the same time, if you ever figure out how to do something very unorthodox and difficult, you can abstract that code into a package you can reuse at a later time.

What is a LaTeX package? Well, it is a file with the extension *.sty which contains some code that either defines new commands, redefines existing ones or provides some other new functionality to the base system. You drop this file in the same directory as your document and then add a single line anywhere in your preamble:

\usepackage{my_package}

Here my_package refers to some file that will need to be named my_package.sty. Once you declare that you are using package, you can start adding the custom commands it defines immediately below. In some cases, declaring the package this way is all you need to do. For example the helvet package changes the default font to Helvetica as soon as you include it:

\documentclass{article}
\usepackage{helvet}
\begin{document}
   ...
\end{document}

There is nothing else that needs to be done after this. Other packages may require you to include some setup commands in the preamble, or trigger commands in the body. In most cases, the documentation provided with the package ought to explain these matters as there is no standard that would apply to all the diverse add-ins you can find out there online.

Once you start messing with the packages, you will probably notice that a single package is usually not enough. On average, you will likely be pulling in two to three packages per document. Sometimes more, sometimes less. If you find yourself importing the same bundle of packages time and time again, you can easily roll them into a single command like this:

\usepackage{helvet, color, graphics}

That said, it is usually beneficial to import each package separately. This way you can quickly comment out packages you don’t need while debugging or re-formatting the document. Keeping declarations on their own lines is especially important for packages which take optional arguments. For example, the geometry package can be declared like this:

\usepackage[margin=1in]{geometry}

This will immediately alter the left and right margins of the document to be exactly 1 inch in size. As you can probably guess, declaring more packages after geometry this way will actually cause an error.

What happens if you issue the \usepackage command without having downloaded it first? Well, it depends. Chances are your LaTeX installation came bundled with a dozen or so useful packages. All of the above mentioned packages for example, should be included by default in your ProText Distribution for Windows. You can find the appropriate *.sty files in their own separate directories in your default LaTeX installation path:

• On windows usually under c:\Progam Files\MiKTeX\tex\latex\
• On unix systems usually in /usr/share/texmf/tex/latex/

If you include a package and it is not in the document’s directory, LaTeX will check if it is located in it’s installation bundle. Unfortunately, it is not as simple as a quick look-up in one of these directories. There is actually a hash table which maps the exact locations of all the installed packages. So installing a new package globally is not as easy as just dropping it in the right directory. The good news is, your system will know right away that the package you are trying to include is neither installed, nor available and will be able to do something about it.

If you are running one of the nice all-bells-and-whistles LaTeX distributions (like MiKTeX which ships with ProTeXt) there is an automated package fetch application built into the system. So chances are that first time you \uspackage something that was not included in the default installation bundle, you will see a pop-up like this:

LaTeX package installer on windows

This also works for document classes which are sort of like packages in their own right. Either way, MiKTeX will check online repositories and download the package for you if it exists. If it cannot find it online, or if your distribution simply does not have a fancy installer your compilation will simply bug out.

Don’t fret though – you can still manually install the package by dumping it into one of the above mentioned paths and then running a magic command called texhash which will re-index said folder and add any new packages to the global hash file, making them available from that point on. On windows you can probably find it under c:\Program Files\MiKTeX\miktex\bin\texhash.exe. On unixes it ought to be in your path, just like all the other tex related commands. It is probably important to mention that you should usually run this command as root/admin because it will likely need to update files that are typically not write accessible to regular users both on Widnows and unix-like systems.

I guess your next question might be “how do I figure out how to use package XYZ?”. Unfortunately, the best answer I can give you is RTFM. And I don’t mean it in an offensive way. I’m just stating a fact here – there are thousands of packages out there, and their functionality and complexity is beyond the scope of this humble guide. While I’m intending to talk about some of the useful or important packages in the next few entries, it is important to know how to be able to find the documentation for all the packages you may have to use on your own.

This should not be a problem for random things you will download from the internet, as the same page where you found the *.sty file will likely also include explanations and examples of how to use said file. For pre-installed packages it may not be as straightforward. Fortunately, there is another magical command that will help you out here: texdoc. This is pretty much man for LaTeX packages. For example running:

texdoc geometry

Should display the documentation for the geometry package. Depending on the whimsy of the package creator, this documentation may be stored a PDF, a text file, or sometimes in a PostScript or DVI format. Linux/Unix users should be able to open all of these with no problems. Windows users may need to download some software to open the last two formats – but fortunately bundles like ProTeXt ship with GhostScript and/or Yap viewers that ought to just work with the texdoc command.

If for some reason you don’t want to use the command line tool, you can always manually browse to the default documentation directory for your package and try to find relevant docs there. Each package usually keeps it’s manuals and sample files in it’s own directory in your LaTeX installation path:

• On windows its: c:\Program Files\MiKTeX\doc\latex\
• On unixes its: /usr/share/texmf-tetex/doc/latex/

Just find the appropriate directory, open it, and view the docs inside.

How to find new/useful LaTeX packages? Well, for one you can Google for them. Pretty much every time you type in something along the lines of “how do I XYZ in LaTeX” the answer is likely to require you to use at least one \usepackage command. But if you just feel like browsing, you can start with the CTAN Catalog. This list by no means all inclusive, but it is a good place to start, and also the primary resource against which your automatic installer is going to check your documents.