Lesson 16

Documentation and getting help

This lesson shows the main sources of documentation for LaTeX-related software and packages, and how to seek help when you are in trouble.

There are several ways to access the documentation of a package or class.

texdoc

If you’ve installed a TeX distribution (e.g., TeXLive or MikTeX) and included the documentation when you installed it you can access the locally saved documentation using the texdoc command line tool. Using:

texdoc < pkg >

will open the documentation of package <pkg>. The utility will search the available documentation and open what it thinks is the closest match to your search term. You can list and choose from among all the viable results it finds using:

texdoc -l < pkg >

texdoc.net

This is a website which works similarly to the texdoc utility. You can search for documentation they have available just like you would do with texdoc -l and then choose from among the results.

CTAN

CTAN is the Comprehensive TeX Archive Network. Most LaTeX packages are published there. You can search the site for a package to access its documentation. Usually the packages are saved in ctan.org/pkg/<pkg-name> and you can access the README and documentation of the packages stored on CTAN there.

Books on LaTeX

There are several books available that can help you learn more about LaTeX. As a beginner, you will gain a lot from a structured beginners guide, as those can give a lot more detail than we’ve covered here. You might also want access to a reference with more detail and recommendations.

The LaTeX team have a list of books largely written by members. The most notable are Lamport’s official guide and the comprehensive LaTeX Companion.

Other books aimed at learning LaTeX include

Getting help

There are various online forums for asking LaTeX questions; perhaps the most popular today is TeX - LaTeX StackExchange. Whenever you ask a question, it’s best to first get your example clear: what is normally known as a ‘minimal working example’ (MWE). This doesn’t mean the code works (as you wouldn’t be asking otherwise!), but rather it means you’ve done your best to make it clear, self-contained and minimal. The latter means having only enough content to show the issue.

How to provide a minimal working example (MWE)

How do you construct a MWE? Normally easiest is to start from

\documentclass{article}
\usepackage[T1]{fontenc}
\begin{document}
Text
\end{document}

and add lines one at a time until you show the issue. You can try to ‘cut down’ your real file, but that can be a long process.

If you need more text to show page breaking and other effects, then packages such as lipsum may be used to generate nonsense paragaraphs of text while keeping your test file small.

Log file

One thing you will want available is your log file; this is created by LaTeX every time you run it, and has the same name as your input but ending .log.

Depending on your desktop interface, you might need to 'show extensions' to work out which file it is.

In the log file, you can always see the full error messages. LaTeX’s error messages try to be helpful, but they are not the same as messages in word processors.

Some editors also make it hard to see the 'full' text of an error, which can hide key details.

If you have a problem, expert LaTeX users will often ask for a copy of your log file.

Going further

Finally we offer a gallery of small examples showing a range of different subject areas not covered in this introduction, and different LaTeX packages in those areas.