A Short Introduction to L^ATEX

Jeremy Sanders

October 2011

Introduction

L^ATEX (also written as latex and LaTeX) is a system for creating documents. Instead of editing your document in a graphical way, as you would with MS Word or StarOffice, you write a text file in an editor like emacs, and process it with L^ATEX, eventually creating a PostScript or PDF file which you can send to a printer. Therefore L^ATEX is less friendly than a wordprocessor, but has a few advantages:

1. You focus on the content of the document rather than its appearance (though if you have exact requirements for formatting, this makes it fiddly to use).
2. It is great for typesetting mathematics (once you get used to the way you type them in).
3. It is quick to enter documents when you are used to it (its macros can make things quick too).
4. Lots of people in astronomy and physical sciences use it.
5. There are lots of existing packages for adding to the functionality of L^ATEX.
6. The BibTeX package makes writing bibliographies and reference lists easy.

If you are a graduate student, you will certainly use L^ATEX to write papers, to write your thesis (when you get there), and telescope proposals (if you are an observer). I also suggest that you use it to write your first-year report, as that will be a valuable experience. Once you've got the hang of it, it's easy to use.

I'm not going to give a complete introduction to L^ATEX here: I am leaving that to books and the short reference guide I have given to you. It can be quite a complex program and few people understand it fully, however with limited knowledge you can achieve quite a bit.

Steps to using L^ATEX

What you type is stored as a normal text file. In this example we will call it paper.tex (.tex is the normal extension used for L^ATEX source files).

1. Make an input .tex file. We write the contents of paper.tex with a text editor such as emacs or gedit. Remember -- you can leave the editor open if you started it with ``SPMamp;'' after the command.
2. Process the file with the latex command. The file paper.tex is processed with the latex command (type latex paper.tex). If there are no errors an output file, paper.dvi, is produced (dvi is an intermediate type of file which can be viewed on the screen or transformed into PostScript for printing).

   If the latex command prints out that it should be run a second time, you should do that. It prints messages like:

   LaTeX Warning: Label(s) may have changed.
   Rerun to get cross-references right.
   

   latex needs to be run more than once to fix up references (stored in the .aux file) (as it only processes the text forwards). Some documents may need to be processed three times.
3. (Optional) View the output .dvi file with xdvi. paper.dvi can be viewed using the xdvi program to see whether the document was processed correctly (just type xdvi paper.dvi). xdvi often doesn't show figures correctly, examining the PostScript file is the best way of seeing how the document will finally appear. If the document isn't as we would like, we switch back to the editor window. xdvi can be left open and automatically detects the changes to the dvi file each time the .tex file is processed).
4. Convert the .dvi file to Postscript for viewing or printing. paper.dvi can then be converted using dvips to a postscript file for printing or viewing (command dvips paper.dvi), producing paper.ps. [FIXME: check default dvips on cass]. To produce a postscript file to be converted into a PDF file (a standard for transferring documents between different machines), the command dvips -Ppdf paper.dvi should be used for high quality fonts.
5. View the Postscript file. paper.ps can be viewed using gv (gv paper.ps) on the screen.
6. Print the Postscript file. Postscirt is printed using lp (e.g. lp -dhoylegr paper.ps).
7. Convert the Postscript to PDF. To convert a PostScript file to PDF use ps2pdf (ps2psf paper.ps, producing paper.pdf), however the -Ppdf option is required for dvips before doing this to get correct fonts.

   To get A4 paper output in ps2pdf, use ps2pdf -sPAPERSIZE=a4 paper.ps

I have omitted details on how to use the BibTeX command in this sequence.

An easier way

latexmk is a program to automate the processing of a LaTeX document and associated BibTeX files. It can convert a tex file directly to Postscript or PDF. If you are using viewers such as gv or okular, these programs can be set to automatically update their display when the file changes.

Here are examples

# use inpaper.tex to generate inpaper.ps
latexmk -ps inpaper

# use inpaper.tex to generate inpaper.pdf using pdflatex
latexmk -pdf inpaper 

# use inpaper.tex to generate inpaper.pdf using dvips then ps2pdf
latexmk -pdfps inpaper

# every time inpaper.tex changes regenerate inpaper.ps
# open up a viewing program to view inpaper.ps and tell
# it to update when inpaper.ps changes
latexmk -ps -pvc inpaper

Errors processing documents

If latex cannot process a document properly because of an error, it produces an error message and a prompt, such as:

! Undefined control sequence.
l.84 \ssassasaq
               
?

The text after the ``!'' is a message explaining what the problem is. The next line shows the line with the problem, shown after the line number (printed l.linenumber, here the 84th line of the file). At the prompt you can do various things. Quite often you should press x[enter] to stop processing, and then you will go back to the original document and fix it. You can optionally continue by pressing [enter] (press ``?'' for other options).

Document structure

Documents are structured in a particular way. At the top of the document are various header items which specify various option features, and below that is the text. Special L^ATEX commands start with a back-slash. Here is a general overview of the document structure (% at the start of a line makes it a comment line in latex):

% the first line specifies what sort of document it is
% (here article) and options
% article specifies the `style file'
\documentclass[a4paper,12pt]{article}

% now we include various packages to get extra features
\usepackage{times}    % get times font
\usepackage{graphicx} % allow us to insert figures

% you could get wider margins with something like
% \usepackage[a4paper,margin=2cm]{geometry}

% now we start the document
\begin{document}

% optional abstract
\begin{abstract}
hi there
\end{abstract}

% set what is going to go into the title
\title{Document structure}
\author{Jeremy Sanders}
\date{October 2011}
\maketitle   % actually put the title in the output

\section{This is a section heading}
Here is some text below that heading

\subsection{A subsection}
More text. Here is some text. blah blah
blah blah. More text.

A different paragraph...

% now we end the document
\end{document}

In fact, most of this is optional. The shortest document is similar to:

\documentclass{article}
\begin{document}
Hi there!
\end{document}

Complexities

Unfortunately there are two versions of L^ATEX in common use: L^ATEX2e described above, and L^ATEX2.10, an older version (quite often supervisors will not have upgraded their documents yet). 2.10 is slightly different in syntax so you have to be careful. 2.10 documents start with $\backslash$documentstyle and 2e documents start with $\backslash$documentclass. You should use the 2e version in preference to 2.10 as 2.10 compatibility will be lost in the future. If you are a postgraduate, you should use the new mn2e style file instead of the mnras style file when writing papers.

PDFLaTeX

PDFLaTeX allows one to convert directly from LaTeX to PDF format without an intervening .dvi and .ps. It also allows several graphics formats to be directly in the LaTeX file without converting them to postscript. Note that .eps figures are not supported in PDFLaTeX. Also some journals may not allow PDFLaTeX submissions, but arxiv.org does. Using PDFLaTeX is a good way to shrink down your arxiv.org submissions. I recommend PDFLaTeX instead of standard LaTeX for most purposes.

PDFLaTeX supports JPEG (good for photographs), PNG (good for line diagram/solid colour bitmaps) and PDF (good for line diagrams/figures) figures. You can convert EPS figures to PDF using ps2pdf:

> ps2pdf -dEPSCrop in.eps out.pdf

You can convert EPS files to bitmaps using ImageMagick (a.k.a. the convert command) -- see the Plotting and Graphics notes:

> convert in.eps out.png

If you are using PDFLaTeX, graphicx needs to be included with the pdftex option:

\usepackage[pdftex]{graphicx}

If you are submitting to arxiv.org, then you need the line

\pdfoutput=1

after the documentclass statement in the .tex file.

Figures are included normally (see the Plotting and Graphics notes), e.g.

  \begin{figure}
    \centering
    \includegraphics[width=0.99\columnwidth]{mypicture.jpg}
    \caption{My nice photo.}
    \label{fig:photo}
  \end{figure}

BibTeX

BibTeX is a useful system for putting references into LaTeX files. You construct a BibTeX bibliography database file by adding bibliographical entries for the papers you want to refer into a single text file. These entries can be written by hand, or simply pasted from the ADS website. If you want to get the BibTeX entry for a particular paper from ADS, bring up its abstract, and click on ``Bibtex entry for this abstract''. You can then copy and paste this entry into your BibTeX file (e.g. refs.bib). Here is the entry for one of my papers:

@ARTICLE{2008MNRAS.390L..93S,
   author = {{Sanders}, J.~S. and {Fabian}, A.~C.},
    title = "{Sound waves in the intracluster medium of
              the Centaurus cluster}",
  journal = {\mnras},
archivePrefix = "arXiv",
   eprint = {0808.2384},
 keywords = {galaxies: clusters: individual: Centaurus cluster,
             cooling flows, intergalactic medium, X-rays: galaxies},
     year = 2008,
    month = oct,
   volume = 390,
    pages = {L93-L97},
      doi = {10.1111/j.1745-3933.2008.00549.x},
   adsurl = {http://adsabs.harvard.edu/abs/2008MNRAS.390L..93S},
  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

Many of these fields are not used typically, but can be useful if you need to find out more about the paper. The text ``2008MNRAS.390L..93S'' is the name of the paper in the BibTeX database provided by ADS by default. I always change the name given to be more memorable, e.g. ``SandersSound08''.

You can then use your bibliography in your document in the following way:

\documentclass{article}

% the natbib package improves latex's default cite command
\usepackage{natbib}

\begin{document}
\section{Test document}

We can refer to the paper in the following ways using the natbib
bibliography package:

% write "Sanders et al (2008) is a great paper!"
 \cite{SandersSound08} is a great paper!
% write "(Sanders et al 2008)"
 \citep{SandersSound08}
% write "(Sanders et al 2007; Fred et al 2010)"
 \citep{SandersSound08,Fred10}
% write (e.g. Fred et al. 2010)
 \citep[e.g.][]{Fred10}
% write Fred et al. 2010
 \citealt{Fred10}

% this section writes out the bibiliography section
% mnras is the style: requires mnras.bst
\bibliographystyle{mnras}

% refs.bib is the name of your bibtex database
\bibliography{refs}

\end{document}

The great thing about BibTeX is that you can just keep adding interesting papers to your database file. BibTeX will only put them in the references list if you use the citation in the document. It will also sort out the order of papers within the reference list and add suffixes such as ``a'' or ``b'' to the year if necessary.

Using BibTeX

I recommend using latexmk to process your files if you use BibTeX. You can do

latexmk -bibtex mypaper.tex
 or
latexk -bibtex -pdf -bibtex mypaper.tex

Note that you may not need to use the -bibtex option if latexmk is configured to run this automatically. It is difficult to get the ordering of the commands you type in to run bibtex otherwise. If you do it by hand, you need to type at the prompt

# the latex command creates a .aux file containing the references used
latex mypaper

# the bibtex command creates a .bbl file containing the list of
# references which appear in the references section
bibtex mypaper

# puts the references into the text where cite is used
latex mypaper

# fixes up the references if the references have moved around
latex mypaper

arxiv.org and BibTeX

When uploading a paper to the arxiv.org preprint database (astro-ph), do not upload your .bib file containing your entire paper database. Instead include the .bbl file generated by bibtex in your archive file and leave out the .bib file.

About this document ...

A Short Introduction to L^ATEX

This document was generated using the LaTeX2HTML translator Version 2008 (1.71)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -split 0 -font_size 10pt -no_navigation latex_intro.tex

The translation was initiated by Jeremy Sanders on 2011-10-02