More LaTeX on Athena: Reports and Advanced Topics (AC-51)

Introduction

This document will cover the LaTeX commands you need to know to produce LaTeX source (.tex) files for reports on Athena. You should be familiar with the basic LaTeX material covered in Essential LaTeX.

LaTeX's typesetting abilities simplify creating a report. LaTeX will create the table of contents, keep track of referencing, and place tables and figures for you. It also makes including other elements of a report easy.

The information in this document is divided into two sections. The first section, ``Writing a Report,'' covers the commands to help you:

The second section of this document, ``Advanced LaTeX Topics,'' covers topics that you might find useful in formatting your report:

This document does not discuss processing, previewing, and printing your report. Such information is standard for LaTeX documents, and is covered in Essential LaTeX on Athena, which is available in the Graphic Arts Copy Center in 11-004 and online. Further information about LaTeX topics is available in the LaTeX User's Guide and Reference Manual. Both documents are available in cluster miniracks and in Athena Reference Sets in Barker and Hayden libraries.

Writing a Report

If your report is fairly short, all you need to know are the basic document style options for report or article. You can create a source (.tex) file to contain both the text of the paper and the commands to format it into a professional-looking report.

If your report is long, you may find it useful to divide your text into multiple files. This has several benefits, including making it easy to edit your text.

This chapter describes several styles for your document, as well as tips for managing long documents.

Document Types

There are just a few basic commands you need to put into your LaTeX source (.tex) file to make a report. Put these lines at the top of your file, filling in your information for the author and title:

\documentclass{report}
\usepackage{fullpage,doublespace}
\author{author's name}
\title{title of report}
\begin{document}
\maketitle
\tableofcontents

These lines tell the LaTeX processor about your document:

After these lines, you include the text of your report. Where you want a chapter heading, put:

\chapter{chapter title}

You can also use other commands to indicate different levels of headers. LaTeX will number the sections appropriately:

\section{section title}
\subsection{subsection title}
\subsection{subsubsection title}
\paragraph{paragraph title}
\subparagraph{subparagraph title}

It isn't necessary to use all these levels, and you probably wouldn't want to for most reports. By default, headings below subsubsection will not be numbered or appear in the table of contents. (See Appendix C.3 of the LaTeX Manual for information on changing this behavior.)

At the very bottom of your file, after all your text, mark the end of the document with the following command:

\end{document}

There may be times when the report formatting class is too much for your short document. You may find that the the font size of the chapter titles is too large, and you may not want a separate title page. Often, the article document class will format a short document more appropriately.

To use the simpler article class, use article instead of report in the \documentclass line of your .tex file:

\documentclass{article}

In the article class, \section, not \chapter, is the top level in the sectioning hierarchy. Do not use the \chapter command; use \section for ``Chapter'' titles. This means that the ``chapter'' titles (i.e., the top-level division) will be in the smaller, section-sized font.

Note that you can't use \section as the top level in a report document class; since the report class expects \chapter to be the top level, your sections would get numbered 0.1, 0.2, etc.

If you're using the report document class, the title page will be printed as a separate page; if you're using the article document class, the title will be printed at the top of the first page of text, unless you use the titlepage optional argument to \documentclass:

 
\documentclass[titlepage]{article}

When your report is long, there are several benefits to dividing your text into multiple files:

The general idea behind using multiple files is to have a main skeleton file that ``includes'' (``reads in'') the other text files when the document is processed. In this main file, you put the commands that are global to the entire paper (such as the \documentstyle command and other style commands), then you use the \include or \input command to include the other files. The \include command and the \input command work the same, effectively, except that \include adds a pagebreak before the text it reads in, and \input does not insert a pagebreak. A good way to divide your text is to put each chapter into a file of its own. Chapters start new pages, but LaTeX will not insert an extra pagebreak if you use \include to include chapters. There is more information on \include and \input in Section 4.4 of the LaTeX Manual.

Here is a sample main.tex file:

\documentstyle[12pt,fullpage]{report}
\title{My Latest Report}
\author{Chris Random User}
\begin{document}
\maketitle
\tableofcontents
\newpage
\include{intro}
\include{report}
\include{advance}
\appendix
\include{sample}
\end{document}

In the example, the files intro.tex, report.tex, advance.tex, and sample.tex are each a chapter in themselves. Thus, the first line of each of these files begins with a \chapter command, and includes the text for that chapter.

This method of maintaining one chapter per file will help you keep your text manageable. Also, if you decide to rearrange your chapters, you can just re-order the \include commands in the main.tex file:

\include{intro}
\include{advance}
\include{report}

Note that you only have to use the \appendix command once, then continue to use the ordinary sectioning commands. The \appendix command is not a sectioning command itself. It just changes the effect of the sectioning commands following the \appendix. (Specifically, it causes chapters to be enumerated with letters rather than numbers.)

Creating Front Matter

As noted in the section on the report style, to make a title page for your document, you include the information in the preamble (between the \usepackage and \begin{document} lines in the main file, or between the \documentclass and \begin{document} lines if no packages are being used), and include the command \maketitle where you want the title page to appear:

\documentclass{report}
\title{This is the Title}
\author{This is your name}
\begin{document}
\maketitle
(the text of your paper)
\end{document}

By default, the title page will include the date on which you processed the document with latex. If you want to override that with a date of your own, put the following line in the preamble with the \title and \author commands:

\date{Your Date Here}

If there are multiple authors, separate their names with the \and command:

\author{Chris Random User \and Pat Haphazard Server}

The commands to produce the table of contents, the list of figures, and the list of tables should also go in your main file. If you need all three lists, and want them to appear on separate pages at the beginning of your document, include the following lines after the \maketitle command and before the text of your document.

\setcounter{page}{1}
\pagenumbering{roman}
\tableofcontents 
\newpage
\listoffigures 
\newpage
\listoftables 
\newpage
\pagenumbering{arabic}
\setcounter{page}{1}

If you don't want to include one of these lists (e.g., if you don't have figures or tables in your document), you can omit the specific list by omitting the command for that list and the \newpage command associated with it.

The \setcounter and \pagenumbering commands allow you to make sure the numbering is correct. In this case, the table of contents will begin numbering at i, ii, etc., then the first page of your text will restart numbering at 1, 2, etc.

Advanced LaTeX Topics

It's easy to customize your page headers and footers using a set of macros available in Athena's consult locker. To use them, type the following line at the athena% prompt:

setenv  TEXINPUTS  .:/afs/athena/contrib/consult/lib/tex/macros:

You could also have these macros permanently available to you by including the above line in your ~/.environment file. To make this take immediate effect, type source ~/.environment from the athena% prompt.

Then, change your \usepackage line so that it includes fancyheadings, and set the pagestyle to fancy. If you originally had something like:

\documentclass{report}
\usepackage{doublespace}

you should change it to:

\documentclass{report}
\usepackage{doublespace,fancyheadings}
\pagestyle{fancy}

The header and footer fields can be defined by commands \lhead{LHEADTEXT} (for the left header), \rfoot{RFOOTTEXT} (for the right footer), and so on for the other fields. These commands, and all of the other commands to control the format of the headers and footers, should be put in the preamble (after the \documentstyle line in your file and before the \begin{document} line).

The page layout is as follows:

lhead                     chead                     rhead

(your text here)
...
lfoot                     cfoot                     rfoot

The L-fields will be flushed left, the C-fields centered and the R-fields flushed right. Each of the six fields and the two ``rules'' (thin horizontal lines) can be defined separately. By default, all the headers and footers are empty, the bottom rule invisible, and the top rule 1/18th of an inch thick.

For example, you might put lines like this in your preamble:

\pagestyle{fancy}
\lfoot{\today}
\cfoot{\thepage}
\rfoot{Your Name Here}

This will put the date, the page number, and your name at the bottom of every page:

17 October 1995            13              Your Name Here

The thickness of the rules below the header and above the footer can be changed by redefining the length parameters \headrulewidth and \footrulewidth. These may be redefined by the \setlength command. A thickness of 0in makes the rule invisible. For example, to make the rule under the header invisible, you'd put the line:

\setlength\headrulewidth{0in}

before the \begin{document} line.

If you want to have multiple lines in a header or footer, you need to separate the lines with a \\. For example, if you wanted the top of every page to have your name, class, and date on separate lines, you'd use:

\documentclass{article}
\usepackage{fanycheadings}
\pagestyle{fancy}
\rhead{Your Name Here}\\
6.xxx\\
\today
\begin{document}

(your text here)

\end{document}

This would end up looking like:

                                           Your Name Here
                                                    6.xxx
                                          17 October 1995
 

(your text here)

If you want to do more complex things with the headers and footers, there is a complete description of all the options available at the top of the macro file. To see it, type:

athena% more /afs/sipb/project/sipb/lib/tex/macros/fancyheadings.sty 

To use tabs, use the tabbing environment. Tab stops are set with the \= command, and \> moves to the next tab stop. Lines are separated by the \\ command.

Here are some of the other commands that are available in this environment:

\+

This causes the left margin of subsequent lines to be indented one tab stop to the right, just as if a \> command were added to the beginning of subsequent lines.

\-

This undoes the effect of a previous \+.

\'

This flushes the text against the next tab stop to the right.

Here is an example:

\begin{tabbing}
If \= it's raining \\
\$>$ then \= put on boots,\\
\$>$ \$>$ take hat;\\
\$>$ or \$>$ smile. \\
Leave house.
\end{tabbing}

This would produce:

If it's raining 
   then put on boots,
        take hat;
   or   smile.
Leave house.

For a full description of all the commands available in this environment, see Section C.9.1 of the LaTeX manual.

Making Figures and Tables

LaTeX allows you to set aside vertical space and assign labels to figures or tables. If you use the figure or table environments, then the space you allocate within one of those environments will not be broken across pages. This guarantees you the amount of contiguous space you ask for so that you can correctly paste or otherwise insert your figure or table into your document.

In addition, you can include a caption to accompany each figure or table, and these captions along with the page numbers on which they appear will be put into a list of figures or list of tables. All you have to do is put the commands \listoffigures and \listoftables in your source (.tex) file where you want the appropriate list to appear. (See Making the Table of Contents and Lists of Figures and Tables, for more information.)

Figures

Here's an example of declaring a figure), including a label for the purpose of cross-referencing (labels are discussed in Cross-Referencing Within the Report):

\begin{figure}
\vspace{1 in}
\caption{A Duck on a Pond}
\label{fig:duckpond}
\end{figure}

A Duck on a Pond

Note that the commands tell LaTeX to make sure that 1 inch of contiguous vertical space is made available, in addition to space needed for the caption. By default, LaTeX places the figure on the same page or after where the figure environment appears, and tries to fit it either at the top or bottom of a page or on a page that contains nothing but figures and/or tables. (For the complete rules on how LaTeX decides to place a figure, see Appendix C.8 of the LaTeX manual.)

To actually have figures appear in your final document, you can either paste them in yourself using scissors and tape, or you can:

For the purposes of formatting a document, LaTeX handles tables in the same way as figures. If you wanted to label and reserve space for a table, you could type:

\begin{table}
\vspace{1.5 in}
\caption{Ducks Seen on Walden Pond}
\label{tbl:duckpond}
\end{table}

and 1.5 inches would be reserved for a table.

To have tables appear in your final document, you can either paste them in yourself using scissors and tape, or use LaTeX's built-in tabular environment to generate tables.

The Tabular Environment

LaTeX has a simple method for generating tables. You use a command that sets up the table, and then specify the data. Indicate how many columns the table should have, what to do to the data within each column, and how to separate each column. When you enter the data, give one row at a time. Separate each data field by an &, and indicate the end of a row by a \\. Here are the commands to produce a table with three columns:

\begin{tabular}{clr}
a& b& c\\aa& bb& cc\\
aaa&
bbb& ccc\\
\end{tabular}

Here is the resulting table:

 a    b     c
 aa   bb   cc
aaa   bbb ccc

In the first column the data is centered, in the second it is left justified and in the right it is right justified. The {clr} argument specifies the format for each column: center, left, right. Changing what is in these curly braces changes the number of columns and how each column is formatted. Notice that the line breaks in the typed text do not affect the format. Rows are separated by the \\ command, and the columns within the rows are separated by the & character.

You can also have boxes around the table and lines separating the columns. LaTeX will put vertical lines wherever you put a | in the column specifications. LaTeX has two commands for creating horizontal lines in tables. \hline creates a horizontal line across the whole table. \cline{m-n} creates a horizontal line from the beginning of column m to the end of column n. Try this example:

\begin{center}
\begin{tabular}{||c|l||r||}\hline
a& b& c\\
\cline{2-3} aa& bb& cc\\
\hline aaa&bbb& ccc\\\hline\hline
\end{tabular}
\end{center}

There is more information about the tabular environment in Section 3.6 of the LaTeX manual.

Including Non-Text

All Athena software packages that produce printable graphics either directly generate PostScript files or generate files that can be converted to PostScript. To include PostScript files in your document, follow these steps:

1. To use the appropriate style files, type the following line at the athena% prompt:

   setenv  TEXINPUTS  .:/afs/athena/contrib/consult/lib/tex/macros:
   

   You could also have these style files permanently available to you by including the above lines in your ~/.environment file. To make this take immediate effect, type:

    
   athena% source  ~/.environment
   

2. Next, add psbox to your \usepackage line. For example, if you had:

   \documentclass[12pt]{report}
   \usepackage{fullpage}
   

   change it to:

   \documentclass[12pt]{report}
   \usepackage{fullpage,psbox}
   

3. If possible, generate the PostScript file such that the picture is flush against the lower left corner. (For example, if idraw is being used, group the entire picture and move it to the lower left corner of the page. If it is a raw PostScript file, add an appropriate translate command, if you know how.) When you do this, the leftmost 1/4 of the PostScript figure may not be printed if you try to print the figure outside of LaTeX. This is because (0,0) is at the lower left corner of the page -- on some printers that section isn't part of the image area. Don't worry about it.
4. Print out the PostScript file. There are two reasons for doing this. The first is to make sure that there are no errors in the PostScript. (If there are, correct them and try again.) The second reason is to get the dimensions of the picture and the location on the page. Measure the height and the width of the graphic. Also, if the graphic is not located in the lower left corner, measure the (x,y) distance from the lower left corner of the page to lower left corner of the graphic in inches; you will need these numbers later.
5. 1. If the PostScript file has the image in the lower left corner of the page, the rest is really easy. At the point where you want the picture to be included, just use a command of the following form:

      \PSbox{filename}{width}{height}
      

      Here, the first argument is the filename of the PostScript file, the second is the width of the graphic, and the third is the height of the graphic. The dimensions can be specified in any units that LaTeX accepts (e.g., 4cm). For example:

      \PSbox{/mit/cruser/duckpond.PS}{8.4in}{1.75in}
      

      The PSbox can be centered, included in a figure, or anything else you want! Since you provide LaTeX with the appropriate height and width information (in the arguments to \PSbox), space is automatically allocated for the graphic.

   2. If the graphic is not in the lower left corner, take the distance from the left side of the page (which you measured in inches) and multiply by -72. Call this number the hoffset. Take the distance from the bottom of the page to the bottom of the graphic (also measured inches), multiply it by -72, and call it the voffset. Then the \PSbox command should be modified to read:

      \PSbox{filename hoffset=hoffset voffset=voffset}{width}{height} 
      

      For example, to include a file which is 4 inches high and 5 inches wide, which is located 3 inches from the bottom of the page and 2 inches from the left side of the page, the \PSbox command would read:

      \PSbox{/mit/cruser/file.PS hoffset=-144 voffset=-216}{5in}{4in}
      

      Here are the commands to include the duck figure:

      \begin{figure}
      \PSbox{duckpond.PS hoffset=-35 voffset=-463}{611pt}{126pt}
      \caption{A Duck on a Pond}
      \label{fig:duckpond}
      \end{figure}
      

   You can also shrink and scale your PostScript figures. To do this, you use hscale and vscale commands to adjust the horizontal and vertical dimensions. For example, if you wanted to include your figure shrunk by half in each direction, you would use:

   \PSbox{/mit/cruser/file.PS hscale=0.5 vscale=0.5}{2.5in}{2in}
   

   Note that the dimensions you include are the size of the figure once it has been scaled, not the full size dimensions. In most cases, you will want to scale your graphic equally both horizontally and vertically.

If you want to preview where the PostScript image appears using xdvi, you can change the psbox in your \usepackage line to be psframe. If you have specified the arguments to \PSbox correctly, a box is drawn around the area where the PostScript image will appear. However, when you print your LaTeX document, the box appears on the printed output as well. You need to change the psframe back to psbox and re-latex your file to remove the box when you print your final copy. Also, since the psframe style only deals with the borders of figures, xdvi will not reflect the effect of any voffset, hoffset, or scale commands.

Including Program Source Code

A program called tgrind is available in the sipb locker to help you convert program listings to a form easily includable in a LaTeX document. (At this printing, it is not available for Sun SPARCclassics.) To use this program, type at the prompt:

athena% add  sipb
athena% tgrind  -latex  -llanguage  filename  >  filename.tex

This will generate a file (filename.tex) of code (-llanguage) formatted for inclusion in a LaTeX file (-latex). For example, to format a C program called mycode.c:

athena% tgrind  -latex  -lc  mycode.c  > mycode.c.tex

You can also format languages other than C:

-lp

Pascal programs

-lcsh

Csh (C shell scripts)

-lsh

sh (Bourne shell scripts)

-ltex

TeX code

-lprolog

prolog

-lratfor

Fortran

-ly

Yacc

-lc++

C++

To include this file in your document:

\tgrindfile{mycode.c.tex}

That's all there is to it. For more information, see the man page on tgrind, and the file /usr/sipb/lib/vgrindefs (after typing add sipb).

References and Bibliographies

Labeling and referring to pieces of your document is very easy. You have to do three things:

Suppose you wanted to refer to your duck figure later on in your document. You could type in:

See Figure 3.2 for some nice ducks.

But suppose you were to move the figure to a different chapter, the ``Duck on a Pond'' figure might not be numbered 3.2 any more, and you would have to edit each reference to rename it. Plus, you would have to maintain a table (mental or otherwise) of what number corresponds to what figure for all the figures in your document.

Instead, you can get LaTeX to maintain this information for you, using its built-in labeling features. To label a figure or table, put the command \label{something} after (or within the argument of) the \caption command. (Do not place the \label command before the \caption command, or the label will refer to the current section number, not the figure or table number.)

\caption{A Duck on a Pond}
\label{fig:duckpond}

\caption{A Duck on a Pond\label{fig:duckpond}}

Now you can refer to the figure by its reference label:

See Figure~\ref{fig:duckpond} for some nice ducks.

(The ~ inserts a normal space and prevents the line from being broken at that point.)

If you now move the figure, the reference will be updated by LaTeX.

One good labeling scheme is type:description, where type would be fig for a figure label, or tbl for a table. Description is a short code for what the figure or table contains (in our example, ``A Duck on a Pond'' has been shortened to duckpond.) This way, if you have a table accompanying that figure (say, listing the different ducks seen on that pond), you can use the label tbl:duckpond without any confusion.

You can also label and reference the following environments as shown in the examples:

equation

e^{i/pi} + 1 = 0 \label{eq:euler}

eqnarray

a^{2} + b^{2} = c^{2} \label{eq:pythagoras}

enumerate

\item Pi-meson and Mu-meson production\label{item:pimu}

You can also label and reference theorem-like environments simply by putting the \label command within the environment. Theorem-like environments are described in Section 3.4.3 of the LaTeX manual.

Make sure to place the \label command correctly (usually the same line is a good place, right after the item you're trying to label), or you may end up referencing the wrong item.

To label a chapter or other portion of your document, the best way to avoid confusion is to put the \label command either within the argument of the sectioning command or right after it:

\section{Wild African Ducks}
\label{sec:afrduck}

\section{Wild African Ducks\label{sec:afrduck}}

Finally, you can refer to labels by what page they are located on, using the \pageref command:

See Figure~\ref{fig:duckpond} on page~\pageref{fig:duckpond}.

To generate your list of references you can create a bibliographic database file. BibTeX will read this file and automatically format the bibliography entries for you. You can then cite bibliography entries by a keyword, much like you would use \ref and \label to reference other parts of your document.

Creating the Database

BibTeX expects the bibliographic database file to be named with an extension of .bib. If your root file is main.tex, then name your database main.bib. The structure of each entry of a .bib file is as follows:

@BOOK{your choice of abbreviation,
    AUTHOR = "author",
    TITLE = "book title",
    PUBLISHER = {publishing company},
    ADDRESS = {where published},
    YEAR = year published}

There are many types of acceptable entries besides book. A list of them and their required fields can be found in Section B.2.1 of the LaTeX Manual. For example:

@ARTICLE{ks:nmr,
    AUTHOR = "Sethuraman, Krishna",
    TITLE = "Nuclear magnetic resonance from {Atlantis}",
    JOURNAL = {American Journal of Bloodshot Physicists},
    YEAR = 1989}

@BOOK{gpf:doofus,
    AUTHOR = "Fishman, George P.",
    TITLE = "My Life With a Doofus",
    PUBLISHER = {Stallion Publishing},
    ADDRESS = {Chicago},
    YEAR = 1987}

BibTeX follows its own capitalization rules when it formats entries. For example, in the @ARTICLE entry type, it capitalizes only the first word of the title, and downcases the rest of the words. To prevent BibTeX from changing capitalization of certain words (such as proper nouns), enclose those words in curly-braces, as in the article title example above.

For multiple authors or editors, separate all of their names with and:

AUTHOR = "Fishman, George P. and Desai, Niraj S. and Sethuraman, Krishna",

George P. Fishman, Niraj S. Desai, and Krishna Sethuraman

To create the bibliography, include the following commands in main.tex:

\bibliography{main}
\bibliographystyle{plain}

These lines will read in the file (main.bib) for BibTeX to read and set the bibliography style (plain in this case).

There are several options for \bibliographystyle:

plain

normal style---listed in alphabetical order and labeled numerically

unsrt

same as plain except entries appear in order of citation

alpha

same as plain except entry labels are used

abbrev

same as plain except uses abbreviations for first names, month names, and journal names

Now that you have the basis for a bibliography, you have to run both latex and bibtex on the document. First, you should run latex (to create a main.aux file, which bibtex reads). Then run bibtex once to get some of the citations and create a .bbl file. Then run latex again so that the cross references between the text file and the bibliography are correct:

athena%  latex  main.tex
athena%  bibtex  main
athena%  latex  main.tex

Be sure to omit the filename extension (.tex}) when you run bibtex. Also, remember that if you add or delete citations or sources, you'll have to re-run latex, then bibtex, then latex again in order to make sure the references and citations are resolved.

Citing Works from the Bibliography

Citing references is very similar to referencing figures or tables, except that you use the \cite command instead of \ref. For example:

See \cite{ks:nmr,gpf:doofus} for general information on these phenomena,
and \cite[p. 69]{ks:nmr} for a short summary of recent research.

See [3, 4] for general information on these phenomena, and [3, p. 69] for a
short summary of recent research.

If you have a few references that you did not explicitly cite in the text of your document, but you would like to include it in the list of references, you use the \nocite command just like you would use the \cite command (in main.tex):

\nocite{baz,fuzz,bong}

where baz, fuzz, and bong are the abbreviations you created for the other texts. To list all of the entries in your .bib file, whether you have cited them or not, use:

\nocite{*}

Note that the entries should only be separated by commas and no white space, or BibTeX will either produce an error or not include your entries in the list of references.

For more information on these topics, please refer to the following pages in the LaTeX manual:

72-74

Bibliography and Citation

74

BibTeX

140-147

Format of the .bib file (also gives info on other entry types)

187-188

Bibliography and Citation

Converting Old Files to LaTeX2e

  \documentstyle[11pt,fullpage]{article}

  \documentclass[11pt]{article}
  \usepackage{fullpage}

  athena% add newtex
  athena% latex209 filename.tex


  





  

    
    

      

    
    
    

      
Comments and feedback to olh-suggest@mit.edu