Department of Engineering

Report Writing with LaTeX at CUED

Introduction

This document doesn't attempt to teach you LaTeX but it does pick out some issues that arise when people start producing long documents. LaTeX was designed with technical reports very much in mind, so before you consider using any other method, look at the list of LaTeX's strengths first.

Front ends

pdflatex will produce PDF files directly, and accepts JPG, PNG and PDF graphics files (but not encapsulated postscript files). latex will produce DVI files and only copes with encapsulated postscript files. A few facilities (ever fewer) are only available with latex

Another more committal choice is whether to use a front-end like Lyx.

Sources of Information

The help system's LaTeX page is quite extensive. It includes information on

• LaTeX in General - LaTeX: An introduction and Advanced LaTeX are short, locally produced documents. The Not So Short Introduction to LaTeX2e is more extensive. LaTeX for Word Processor Users introduces LaTeX to those already proficient with Word.
• Maths - Try LaTeX Maths and Graphics or Math into LaTeX (by G. Grätzer).
• Graphics - Try LaTeX Maths and Graphics or Using Imported Graphics in LaTeX2e Documents (by Keith Reckdahl)
• Packages - Look at CUED's list of locally installed packages. The TeX and LaTeX Catalogue describes packages available elsewhere.
• LaTeX in depth - LaTeXe help is an extensive indexed reference.

and there's also a keyword search of the LaTeX documents on this server.

Setting Up

The document class specified in the "\documentclass" line determines the basic appearance of the document (rather in the way that templates or Master Pages do in other programs). Packages (loaded in using the "\usepackage" command) are add-ons that augment or change the standard LaTeX features. Both classes and packages can be given options by using square brackets (see the use of the graphicx package below as an example).

• Classes - Standard LaTeX has few standard classes of document. The most relevant for longer documents are article, report, and book. The differences are minor
  • book - can contain parts and chapters. subparagraphs possible. New chapters begin on a right page. Supports \frontmatter, \mainmatter and \backmatter commands.
  • report - can contain chapters. Numbering starts at 0. New chapters begin on a right page.
  • article - no parts. Numbering begins at 1.

  Journals sometimes have class files for you to use. Use them whenever you can. We have a few of these installed (e.g. the Royal Society's rs class, Elsevier's elsart class and some IEEE material), but many others exist (see, for example, CUP's LaTeX support, and Kluwer Academic's author instructions and style files).

  There are several thesis-related classes around. Most are university-specific. Some have been designed for easy customisation. One that's often mentioned is ucthesis from the University of California.

  It's possible to write one's own class files. 2 local options are available

  • LaTeX IIB project report classes based on the article class, was written here for 4th years to use.
  • Harish Bhanderi's CUED PhD/MPhil Thesis Style is of more general use.
• Packages - There are hundreds. Start with the few you need (perhaps fancyhdr and graphicx), then add others as necessary. Adding too many risks unfortunate interactions.
• Structure - The following should be more than enough for 4th Year Reports

  \documentclass{IIBproject}
  \usepackage[dvips]{graphicx}
  \usepackage{fancyhdr}
  \usepackage{setspace}
  
  
  \bibliographystyle{plain}
  
  % The next line sets 1.5 spacing
  \onehalfspacing
  \begin{document}
  
  % Title Page
  \author{A Student (college code)}
  \title{Just a Test}
  \projectgroup{A}
  \pagestyle{empty}
  \maketitle
  \thispagestyle{empty}
  
  % Summary
  \pagestyle{fancy}
  
  \begin{abstract}
  ...
  \end{abstract}
  
  \tableofcontents
  \listoffigures
  \newpage
  
  %Introduction - load in the intro.tex file
  \input{intro}
  
  %Theory and Design of Experiment - load in the theory.tex file
  \input{theory}
  
  % ....
  
  %Conclusions
  \input{conclusions}
  
  \bibliography{test} % load in the info produced from test.bib
  
  \appendix
  \input{appendix}
  
  \end{document}
  

  If you're writing a book you may wish to add \frontmatter, \mainmatter and \backmatter too, so that arabic page numbering begins after the contents, etc.

Standard Features

• Cross referencing - Use the \label command to set places you want to reference. Use \ref to refer by section and \pageref to refer by pagenumber. If you put a label after or in a figure's caption, then a \ref to that label will give the figure number, otherwise it will give the section number.
• Footnotes - use \footnote. The footnotes are numbered in a single sequence through the whole document. \usepackage[perpage]{footmisc} gives per-page numbering. \usepackage{endnotes} puts all the 'footnotes' at the end of the document.
• Floats - 2 types: table and figure. I always use [htbp] as placement parameters. By default LaTeX doesn't add text to a page that is over 70% covered with graphics. See the float hints for how to override this. Use the endfloat package to put all figures at the end of a document.
• Graphics - easy enough. See the local LaTeX Maths and Graphics guide or the definitive Using Imported Graphics in LaTeX2e Documents (by Keith Reckdahl).
• Screen dumps - on CUED's teaching system use KSnapshot or Gimp in the applications panel. Typing import foo.eps offers similar facilities.
• Tables - Many options. Try to keep it simple. The general guides provide enough information for most situations. Multipage tables can be produced using the longtable package. If you need color, look at the colortbl package.
• Maths - if standard LaTeX maths isn't sufficient you can always use the AMS-LaTeX package.
• Numbering - With bigger documents you may want to have per-section figure and equation numbering. The class sometimes provides this. Alternatively, you can use

  \usepackage{chngcntr}
  
  \counterwithin{figure}{section}
  \counterwithin{equation}{section}
  \begin{document}
  ...
  

• Program source code - The verbatim package has a "\verbatiminput" command to include files without formatting them. If your code uses TABS you may need to run your code through expand first.

  The listings package typesets program listings putting keywords, comments etc into different font styles. The example below shows how to format inline fragments and import (part of) external files for C++ code.

  ...
  \usepackage{listings}
  \begin{document}
  \lstset{language=C++}
  ...
  \begin{lstlisting}{}
  for(int i=0; i<n; i++)
      cout << "loop";
  \end{lstlisting}
  
  \lstinputlisting{test.cc}
  \lstinputlisting[first=10,last=50]{test.cc}
  

  Line numbers and other languages are supported too.
• Bibliography - Why use bibtex? So that you can use the same bibliography database file for various documents. Also it's easy to change styles. Create a bibliography file with an entry for each item. bibview or emacs' bibtex mode makes this fairly painless. A typical entry looks like this.

  @BOOK
    {KandR,
     AUTHOR  = "Kernighan, Brian W. and Ritchie, Dennis M.",
     TITLE   = "{The C Programming Language Second Edition}",
     PUBLISHER = "Prentice-Hall, Inc.",
     YEAR = 1988
    }
  

  The fields are described in the bibtex handout. The first field is the tag used when you \cite the item. How this appears in the text depends on the packages used and the bibliography style. If you call the bibtex file test.bib then the styles in the framework suggested above should work ok. In your main latex document you need \bibliographystyle{plain} at the top to set the style and \bibliography{test} where you want the bibliography to appear. Note that you'll initially have to run latex, bibtex, latex and latex again on your document before everything appears. After that, you only have to run latex unless you change the bibliography file.

  If you want multiple citations sorted, use the citesort package.

  If you want citations superscripted, use the overcite package. To have superscripts in the References section, add the following to your LaTeX document

     \makeatletter \renewcommand\@biblabel[1]{$^{#1}$} \makeatother
  

  If the journal you're writing for doesn't provide a bibliography style file, we have a number of alternatives online. The natbib package is well documented (see the natbib reference sheet for the essentials).

  An alternative to the plain style used in the above example is unsrt which lists references in citation order rather than author order. To have references at the end of each chapter, use chapterbib or bibunits.

  If none of the supplied styles are adequate, then the custom-bib can be used by typing latex makebst.tex from the command line to customise your own style - it's self-documenting; just accept the offered defaults if you have doubts.

  See the bibliographies page for more information.

• Acronyms - The acronym package helps to ensure that at exactly one expanded version of each acronym appears in the text. The same package can be used for glossaries. See Glossaries and Acronyms with LaTeX for an introduction.
• Appendices - The appendix package offers more control. Tweaking the following should give you enough extra features

  \usepackage{appendix}
  \renewcommand{\appendixtocname}{TOC appendix title}
  \renewcommand{\appendixpagename}{Inline appendix title}
  ...
  \appendix
  \appendixpage
  \addappheadtotoc
  \section{1st appendix section}
  

Common Problems

• Fiddling - Don't customise any more than you need to! Worry about content. Accept LaTeX's way of presenting things unless there are good reasons to do otherwise. n.b., the first paragraph of a section isn't supposed to be indented!
• Quotas - Postscript files are big. You can use compressed files by doing the following
  1. Copy the BoundingBox line from each eps file and put it into a new file with the same name as the original eps file, but with ".bb" added
  2. Compress the postscript files
  3. Use the compressed filenames with \includegraphics
• Speed-
  1. Use \usepackage[draft]{graphicx} for drafts of documents with lots of postscript.
  2. Comment out the \input lines relating to parts of the document you're not working on. The page-numbers and cross-references may not come out correctly, but this may not matter at this stage. If you want the page-numbers and cross-references to be as in the final document, use \include instead of \input, and use the \includeonly command to select sections to process. E.g.

     \includeonly{chapter1,chapter3}
     \include{chapter1}
     \include{chapter2}
     \include{chapter3}
     

     will process only chapters 1 and 3 and will assume that chapter 2 hasn't changed since it was last processed. Note however that \include (unlike \input) will force a page break.
• To get the Appendix mentioned in your table of contents, use the tocbibind package.
• To change the title of the references section, use "\renewcommand\refname{New Title}" for articles and "\renewcommand\bibname{New Title}" for books.
• Changing the margins - Use the geometry package. "\usepackage{geometry} ... \geometry{margin=1in}" will set side margins to 1 inch. Alternatively, you can explicitly set the margins - see the Advanced LaTeX document for details.
• To change the style of section headings, look at the titlesec package
• Annotating a postscript file - Use xfig or psfrag
• Squeezing more onto the page - See the squeezing space in LaTeX notes.
• See CUED's LaTeX Frequently Asked Questions if you're stuck, or mail Tim Love.