LaTeX for scientific documentation

Experimental html version of downloadable textbook, see https://www.tacc.utexas.edu/~eijkhout/istc/istc.html
\[ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%% %%%% This text file is part of the source of %%%% `Introduction to High-Performance Scientific Computing' %%%% by Victor Eijkhout, copyright 2012-2020 %%%% %%%% mathjax.tex : macros to facility mathjax use in html version %%%% %%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \newcommand\inv{^{-1}}\newcommand\invt{^{-t}} \newcommand\bbP{\mathbb{P}} \newcommand\bbR{\mathbb{R}} \newcommand\defined{ \mathrel{\lower 5pt \hbox{${\equiv\atop\mathrm{\scriptstyle D}}$}}} \newcommand\macro[1]{$\langle$#1$\rangle$} \newcommand\dtdxx{\frac{\alpha\Delta t}{\Delta x^2}} \] Back to Table of Contents

34 LaTeX for scientific documentation

34.1 The idea behind LaTeX, some history of TeX

crumb trail: > latex > The idea behind LaTeX, some history of TeX

}

TeX is a typesetting system that dates back to the late 1970s. In those days, graphics terminals where you could design a document layout and immediately view it, the way you can with for instance Microsoft Word, were rare. Instead, TeX uses a two-step workflow, where you first type in your document with formatting instructions in an ascii document, using your favorite text editor. Next, you would invoke the latex program, as a sort of compiler, to translate this document to a form that can be printed or viewed.

%% edit mydocument.tex %% latex mydocument %% # print or view the resulting output

The process is comparable to making web pages by typing HTML commands.

This way of working may seem clumsy, but it has some advantages. For instance, the TeX input files are plain ascii, so they can be generated automatically, for instance from a database. Also, you can edit them with whatever your favorite editor happens to be.

Another point in favor of TeX is the fact that the layout is specified by commands that are written in a sort of programming language. This has some important consequences:

  • Separation of concerns: when you are writing your document, you do not have to think about layout. You give the `chapter' command, and the implementation of that command will be decided independently, for instance by you choosing a document style.
  • Changing the layout of a finished document is then done by choosing a different realization of the layout commands in the input file: the same `chapter' command is used, but by choosing a different style the resulting layout is different. This sort of change can be as simple as a one-line change to the document style declaration.
  • If you have unusual typesetting needs, it is possible to write new TeX commands for this. For many needs such extensions have in fact already been written; see section  34.4 .

    The commands in TeX are fairly low level. For this reason, a number of people have written systems on top of TeX that offer powerful features, such as automatic cross-referencing, or generation of a table of contents. The most popular of these systems is LaTeX. Since TeX is an interpreted system, all of its mechanisms are still available to the user, even though LaTeX is loaded on top of it.

    34.1.1 Installing LaTeX

    crumb trail: > latex > The idea behind LaTeX, some history of TeX > Installing LaTeX

    The easiest way to install LaTeX on your system is by downloading the TeX{}live distribution from http://tug.org/texlive . Apple users can also use fink or macports . Various front-ends to TeX exist, such as TeX{}shop on the Mac.

    34.1.2 Running LaTeX

    crumb trail: > latex > The idea behind LaTeX, some history of TeX > Running LaTeX

    In this section you will run the LaTeX compiler

    Originally, the latex compiler would output a device independent file format, named dvi , which could then be translated to PostScript or PDF, or directly printed. These days, many people use the pdflatex program which directly translates .tex files to .pdf files. This has the big advantage that the generated PDF files have automatic cross linking and a side panel with table of contents. An illustration is found below.

    Let us do a simple example.

    \documentclass{article} \begin{document} Hello world! \end{document}

    FIGURE 34.1: A minimal LaTeX document

    Create a text file minimal.tex with the content as in figure  34.1 . Try the command pdflatex minimal or latex minimal . Did you get a file minimal.pdf in the first case or minimal.dvi in the second case? Use a pdf viewer, such as Adobe Reader, or dvips respectively to view the output.

    {If you make a typo, TeX can be somewhat unfriendly. If you get an error message and TeX is asking for input, typing x usually gets you out, or Ctrl-C . Some systems allow you to type e to go directly into the editor to correct the typo.}

    34.2 A gentle introduction to LaTeX

    crumb trail: > latex > A gentle introduction to LaTeX

    Here you will get a very brief run-through of LaTeX features. There are various more in-depth tutorials available, such as the one by Oetiker  [Oetiker:LaTeXintro] .

    34.2.1 Document structure

    crumb trail: > latex > A gentle introduction to LaTeX > Document structure

    Each LaTeX document needs the following lines:

    \documentclass{ .... } % the dots will be replaced \begin{document} \end{document}

    The `documentclass' line needs a class name in between the braces; typical values are `article' or `book'. Some organizations have their own styles, for instance `ieeeproc' is for proceedings of the IEEE.

    All document text goes between

    \begin{document} your text here \verb+ \end{document}

    lines. (Matched `begin' and `end' lines are said to denote an environment , in this case the document environment.)

    The part before the begin of the document is called the `preamble'. It contains customizations for this particular document. For instance, a command to make the whole document double spaced would go in the preamble. If you are using pdflatex to format your document, you want a line

    \usepackage{hyperref}

    here.

    Have you noticed the following?

  • The backslash character is special: it starts a LaTeX command.
  • The braces are also special: they have various functions, such as indicating the argument of a command.
  • The percent character indicates that everything to the end of the line is a comment.

    34.2.2 Some simple text

    crumb trail: > latex > A gentle introduction to LaTeX > Some simple text

    In this section you will learn some basics of text formatting.

    Create a file first.tex with the content of figure  34.1 in it. Type some text in the preamble, that is, before the \n{\ \begin\{document\}} line and run pdflatex on your file.

    {You should get an error message because you are not allowed to have text in the preamble. Only commands are allowed there; all text has to go after \n{\ \begin\{document\}}.}

    Edit your document: put some text in between the \n{\ \begin\{document\}} and \n{\ \end\{document\}} lines. Let your text have both some long lines that go on for a while, and some short ones. Put superfluous spaces between words, and at the beginning or end of lines. Run pdflatex on your document and view the output.

    {You notice that the white space in your input has been collapsed in the output. TeX has its own notions about what space should look like, and you do not have to concern yourself with this matter.}

    Edit your document again, cutting and pasting the paragraph, but leaving a blank line between the two copies. Paste it a third time, leaving several blank lines. Format, and view the output.

    {TeX interprets one or more blank lines as the separation between paragraphs.}

    Add \n{\\usepackage\{pslatex\}} to the preamble and rerun pdflatex on your document. What changed in the output?

    {This should have the effect of changing the typeface from the default to Times Roman.}

    {Typefaces are notoriously unstandardized. Attempts to use different typefaces may or may not work. Little can be said about this in general.}

    Add the following line before the first paragraph:

    \section{This is a section}

    and a similar line before the second. Format. You see that LaTeX automatically numbers the sections, and that it handles indentation different for the first paragraph after a heading.

    Replace article by artikel3 in the documentclass declaration line and reformat your document. What changed?

    {There are many documentclasses that implement the same commands as article (or another standard style), but that have their own layout. Your document should format without any problem, but get a better looking layout.}

    {The artikel3 class is part of most distributions these days, but you can get an error message about an unknown documentclass if it is missing or if your environment is not set up correctly. This depends on your installation. If the file seems missing, download the files from http://tug.org/texmf-dist/tex/latex/ntgclass/ and put them in your current directory; see also section  34.2.9 .}

    34.2.3 Math

    crumb trail: > latex > A gentle introduction to LaTeX > Math

    In this section you will learn the basics of math typesetting

    One of the goals of the original TeX system was to facilitate the setting of mathematics. There are two ways to have math in your document:

  • Inline math is part of a paragraph, and is delimited by dollar signs.
  • Display math is, as the name implies, displayed by itself.

    Put \$x+y\$ somewhere in a paragraph and format your document. Put \n{\ \[ x+y\ \] } somewhere in a paragraph and format.

    {Formulas between single dollars are included in the paragraph where you declare them. Formulas between \n{\ \[ ...\ \] } are typeset in a display.}

    For display equations with a number, use an equation environment. Try this.

    Here are some common things to do in math. Make sure to try them out.

  • Subscripts and superscripts: $x_i^2$. If the sub or superscript is more than a single symbol, it needs to be grouped: $x_{i+1}^{2n}$. If you need a brace in a formula, use $\{ \}$.
  • Greek letters and other symbols: $\alpha\otimes\beta_i$.
  • Combinations of all these $\int_{t=0}^\infty tdt$.

    Take the last example and typeset it as display math. Do you see a difference with inline math?

    {TeX tries not to include the distance between text lines, even if there is math in a paragraph. For this reason it typesets the bounds on an integral sign differently from display math.}

    34.2.4 Referencing

    crumb trail: > latex > A gentle introduction to LaTeX > Referencing

    In this section you will see TeX's cross referencing mechanism in action.

    So far you have not seen LaTeX do much that would save you any work. The cross referencing mechanism of LaTeX will definitely save you work: any counter that LaTeX inserts (such as section numbers) can be referenced by a label. As a result, the reference will always be correct.

    Start with an example document that has at least two section headings. After your first section heading, put the command