## 5. Using teTeX.

Theoretically, at least, everything is installed correctly and is ready to run. teTeX is a very large software package. As with any complex software package, you'll want to start by learning teTeX slowly, instead of being overwhelmed by its complexity.

At the same time, we want the software to do something useful. So instead of watching TeX typeset

Hello, World!''

as Professor Knuth suggests in the The TeXBook, we'll produce a couple of teTeX's own documents in order to test it.

The next section, Printing the documentation, is really a tutorial for operating teTeX. It covers printing the documentation included with teTeX (which is in LaTeX and .dvi format, of course). The following section, TeX and LaTeX commands, is more of a cookbook'' than a tutorial. It discusses how to format LaTeX documents, and covers a few of the commands and environments of the more commonly used document classes.

The section LaTeX extension packages and other resources tells how to use the many pre-existing LaTeX packages to customize documents to your specifications.

## 5.1 Printing the documentation.

You should be logged in as root the first few times you run teTeX. If you aren't, metafont may not be able to create the necessary directories for its fonts. The texconfig program includes an option to make the font directories world-writable, but if you're working on a multi-user system, security considerations may make this option impractical or undesirable.

In either instance, if you don't have the appropriate permissions to write to the directories where the fonts are stored, metafont will complain loudly because it can't make the directories. You won't see any output because you have a bunch of zero-length font characters. This is no problem. Simply log out, re-login as root, and repeat the offending operation.

The nice thing about teTeX is that, if you blow it, no real harm is done. It's not like a compiler, where, say, you will trash the root partition if a pointer goes astray. What, you haven't read the teTeX manual yet? Of course you haven't. It's still in the distribution, in source code form, waiting to be output.

So, without further delay, you will want to read the teTeX manual. It's located in the directory

/usr/lib/teTeX/texmf/doc/tetex.


The LaTeX source for the manual is called TETEXDOC.tex. (The .tex extension is used for both TeX and LaTeX files. Some editors, like emacs(1), can tell the difference.) There is also a file TETEXDOC.dvi included with the distribution, which you might want to keep in a safe place---say, another directory ---in case you want to test your .dvi drivers later. With that out of the way, type

latex TETEXDOC.tex

LaTeX will print several warnings. The first,
LaTeX Warning: Label(s) may have changed. Rerun to get the
cross-references right.

is standard. It's common to build a document's Table of Contents by LaTeXing the document twice. So, repeat the command. The other warnings can be safely ignored. They simply are informing you that some of the FTP paths mentioned in the documentation are too wide for their alloted spaces. (If you're really inquisitive, look at one of the TeX references for a discussion of \hbox and \vbox.)

teTeX will have generated several files from TETEXDOC.tex. The one that we're interested in is TETEXDOC.dvi. This is the device-independent output which you can send either to the screen or the printer. If you're running teTeX under the X Windows System, you can preview the document with xdvi(1).

For the present, let's assume that you have a HP LaserJet II. You would give the command

dvilj2 TETEXDOC.dvi

which will write a PCL output file from TETEXDOC.dvi, including soft fonts which will be downloaded to the LaserJet. This is not a feature of TeX or LaTeX, but a feature provided by dvilj2(1). Other .dvi drivers provide features which are relevant to the devices they support. dvilj2(1) will fill the font requests which were made in the original LaTeX document with the the closest equivalents available on the system. In the case of a plain-text document like TETEXDOC.tex, there isn't much difficulty. All of the fonts requested by TETEXDOC.tex will be generated by metafont, which is automatically invoked by dvilj2(1) and generates the fonts if they aren't already present. (If you're running dvilj2(1) for the first time, the program needs to generate all of the fonts, which could take up to several days if you're using a really slow machine.) There are several options which control font generation via dvilj2(1); they're outlined in the manual page. At this point, you shouldn't need to operate metafont directly. If you do, then something has gone awry with your installation. All of the .dvi drivers will invoke metafont directly via the kpathsea path-searching library---also beyond the scope of this document---and you don't need to do any more work with metafont for the present---all of the metafont sources for the Computer Modern font library are provided.

You can print TETEXDOC.lj with the command

lpr TETEXDOC.lj

You may need to install a printer filter that understands PCL. Look at the Printing-HOWTO for details.

The nine-page teTeX Guide provides some useful information for further configuring your system, some of which I have mentioned, much which this document doesn't cover.

Some of the information in the next section I haven't been able to test, because I have a non-PostScript HP Deskjet 400 color ink jet printer connected to Chanel3's parallel port. However, not owning a PostScript printer is no barrier to printing text and graphics from your text documents. See the section Ghostscript to install Ghostscript, if it isn't already installed on your system.

## 5.2 TeX and LaTeX commands.

### Document structure.

Preparing documents for TeX typesetting is easy. Make sure there's a blank line between the paragraphs of a plain text file, and run file through the TeX program with the command

TeX your_text_file

The result will be a file of the same base name and the extension .dvi. The text is set in 10-point, Computer Modern Roman, single-spaced, with justified left and right margins. If you receive error messages from special characters like dollar signs, escape them with a backslash character, \, and run TeX on the file again. You should be able to process the resulting file with the .dvi file translator of your choice (see above) to get printed output.

The only other peculiarity of TeX input files is to make sure that you use opening and closing quotes, which are denoted in the input file with the grave accent and single quote characters. Emacs' TeX mode will do this for you automatically.

"These are ascii-type quotes."
These are TeX-style' quotes.''

You can consult a guide like A Gentle Introduction to TeX, described above, for hints on how to make modifications to the default TeX page format.

Documents formatted for LaTeX have a few more rules, but with complex documents, LaTeX can greatly simplify the formatting process.

Essentially, LaTeX is a document markup language which tries to separate the output style from the document's logical content. For example, formatting a section heading with TeX would require specifying 36 points of white space above the heading, then the heading itself set in bold, 24-point type, then copying the heading text and page number to the Table of Contents, then leaving 24 points of white space after the heading. By contrast, LaTeX has the \section{} command, which does all of the work for you. If you need to change the format of the section headings throughout your document, you can change the definition of \section{} instead of the text in the document. You can see where this would save hours of reformatting for documents of more than a dozen pages in length.

All LaTeX documents have three sections: a preamble, the body text, and a postamble. These terms are standard jargon and are widely used by TeXperts.

The preamble, at a minimum, specifies the type of document to be produced---the document class---and a statement which signals the beginning of the document's body text. For example:

\documentclass{article}
\begin{document}

The document's postamble is usually very simple. Except in specialized cases, it contains only the statement:
\end{document}

Note the \begin{document} and \end{document} pairing. In LaTeX, this is called an environment. All text must appear within an environment, and many commands are effective only in the environments in which they're called. The document environment is the only instance where LaTeX enforces this convention, however. That is, it's the only environment that is required in a document. (An exception is letter class, which also requires you to declare \begin{letter} and  \end{letter}. See the section Letters.) However, many formatting features are specified as environments. They're described in the following sections.

The document classes can be called with arguments. For example, instead of the default, 10-point type used as the base point size, as in the previous example, we could have specified

\documentclass[12pt]{article}

to produce the document using 12 points as the base point size. The document class, article, makes the necessary adjustments.

There are a few document classes which are commonly used. They're described below. The report class is similar to article class, but produces a title page and starts each section on a new page. The letter class includes special definitions for addresses, salutations, and closings, a few of which are described below.

You can include canned LaTeX code, commonly known as a package, with the \usepackage{} command.

\usepackage{fancyhdr}

The command above would include the LaTeX style file fancyhdr.sty from one of the TEXINPUTS directories, which you and teTeX specified during installation and setup processes.

\documentclass{article}
\usepackage{fancyhdr}
\begin{document}


Note that the \usepackage{} declarations are given before the \begin{document} statement; that is, in the document preamble.

fancyhdr.sty extends the \pagestyle{} command so that you can create custom headers and footers. Most LaTeX document classes provide headers and footers of the following standard page styles:

\pagestyle{plain}       % default pages style -- page number centered at
% the bottom of the page.
\pagestyle{empty}       % no headers or footers
\pagestyle{headings}    % print section number and page number at the
% top of the page.

Everything on a line to the right of the percent sign is a comment.

The \pagestyle{} command doesn't take effect until the following page. To change the headers and footers on the current page, use the command

\thispagestyle{the_pagestyle}


### Characters and type styles.

Character styles are partially a function of the fonts specified in the document. However, bold and italic character emphasis should be available for every font present on the system. Underlining, too, can be used, though its formatting presents special problems. See section LaTeX extension packages and other resources, below.

You can specify text to be emphasized in several ways. The most portable is the \em command. All text within its scope is italicized by default. For example:

This word will be {\em emphasized.}

If you have italicized text that runs into text which is not italicized, you can specify an italic correction factor to be used. The command for this is \/; that is, a backslash and a forward slash.
This example {\em will\/} print correctly.

This example will {\em not} print correctly.

Slightly less portable, but still acceptable in situations where they're used singly, are the commands \it, \bf, and \tt, which specify that the characters within their scope be printed using italic, bold, and monospaced (teletype) typefaces, respectively.
{\tt This text will be printed monospaced,}
{\it this text will be italic,} and
{\bf this text will be bold\dots} all in one paragraph.

The command \dots prints a series of three periods for ellipses, which will not break across a line.

The most recent version of LaTeX, which is what you have, includes commands which account for instances where one emphasis command would supersede another.

This is {\it not {\bf bold italic!}}

What happens is that teTeX formats the text with the italic typeface until it encounters the \bf command, at which point it switches to boldface type.

To get around this, the NFSS scheme of selecting font shapes requires three parameters for each typeface: shape, series, and family. Not all font sets will include all of these styles. LaTeX will print a warning, however, if it needs to substitute another font.

You can specify the following font shapes:

\textup{text}           % upright shape (the default)
\textit{text}           % italic
\textsl{text}           % slanted
\textsc{text}           % small caps

These are the two series that most fonts have:
\textmd{text}           % medium series (the default)
\textbf{text}           % boldface series.

There are generally three families of type available.
\textrm{text}           % roman (the default)
\textsf{text}           % sans serif
\texttt{text}           % typewriter (monospaced, Courier-like)

Setting font styles using these parameters, you can combine effects.
\texttt{\textit{This example likely will result in a font
substitution, because many fonts don't include a typewriter italic
typeface.}}

The font family defaults to Computer Modern, which is a bit-mapped font. Other font families are usually PostScript-format Type 1 fonts. See section Using PostScript fonts for details on how to specify them.

There are also many forms of accents and special characters which are available for typesetting. This is only a few of them. (Try typesetting these on your own printer.)

\'{o}   \{e}   \^{o}   \"{u}   \={o}   \c{c}   ? !

Finally, there are characters which are used as meta- or escape characters in TeX and LaTeX. One of them, the dollar sign, is mentioned above. The complete set of metacharacters, which need to be escaped with a backslash to be used literally, is:
# $% & _ { }  There are also different alphabets available, like Greek and Cyrillic. LaTeX provides many facilities for setting non-English text, which are covered by some of the other references mentioned here ### Margins and line spacing. Changing margins in a TeX or LaTeX document is not a straightforward task. A lot depends on the relative indent of the text you're trying to adjust the margin for. The placement of the margin-changing command is also significant. For document-wide changes to LaTeX documents, the \evensidemargin and \oddsidemargin commands are available. They affect the left-hand margins of the even-numbered and odd-numbered pages, respectively. For example, \evensidemargin=1in \oddsidemargin=1in  adds on inch to the left-hand margin of the even and odd pages in addition to the standard one-inch, left-hand margin. These commands affect the entire document and will shift the entire body of the text right and left across a page, regardless of any local indent, so they're safe to use with LaTeX environments like verse and list. Below is a set of margin-changing macros which I wrote. They have a different effect than the commands mentioned above. Because they use plain TeX commands, they're not guaranteed to honor the margins of any LaTeX environments which may be in effect, but you can place them anywhere in a document and change the margins from that point on. %% margins.sty -- v. 0.1 by Robert Kiesling %% Copies of this code may be freely distributed in verbatim form. %% %% Some elementary plain TeX margin-changing commands. Lengths are %% in inches: %% \leftmargin{1} %% sets the document's left margin in 1 inch. %% \leftindent{1} %% sets the following paragraphs' indent in %% 1 inch. %% \rightindent{1} %% sets the following paragraphs' right margins %% %% in 1 inch. %% \llength{3} %% sets the following lines' lengths to 3 inches. %% \message{Margins macros...} \def\lmargin#1{\hoffset = #1 in} \def\lindent#1{\leftskip = #1 in} \def\rindent#1{\rightskip = #1 in} \def\llength#1{\hsize = #1 in} %% %% (End of margins macros.}  Place this code in a file called margins.sty in your local $TEXINPUTS directory. The commands are explained in the commented section of the file. To include them in a document, use the command
\usepackage{margins}

in the document preamble.

While we're on the subject, if you don't want the right margin to be justified, which is the default, you can tell LaTeX to use ragged right margins by giving the command:

\raggedright


Setting line spacing also has its complexities.

The baselineskip measurement is the distance between lines of text. It is given as an absolute measurement. For example,

\baselineskip=24pt

or even better:
\setlength{\baselineskip}{24pt}

The difference between the two forms is that setlength will respect any scoping rules that may be in effect when you use the command.

The problem with using baselineskip is that it also affects the distance between section headings, footnotes, and the like. You need to take care that baselineskip is correct for whatever text elements you're formatting. There are, however, LaTeX macro packages, like setspace.sty, which will help you in these circumstances. See section LaTeX extension packages and other resources.

### Document classes.

LaTeX provides document classes which provide standardized formats for documents. They provide environments to format lists, quotations, footnotes, and other text elements. Commonly used document classes are covered in the following sections.

### Articles and reports.

As mentioned above, the article class and the report class are similar. The main differences are that the report class creates a title page by default and begins each section on a new page. Mostly, though, the two document classes are similar.

To create titles, abstracts, and bylines in these document classes, you can type, for example,

\title{The Breeding Habits of Cacti}
\author{John Q. Public}
\abstract{Description of how common desert cacti search
for appropriate watering holes to perform their breeding
rituals.}

in the document preamble. Then, the command
\maketitle

given at the start of the text, will generate either a title page in the report class, or the title and abstract at the top of the first page, in the article class.

Sections can be defined with commands that include the following:

\section
\subsection
\subsubsection

These commands will produce the standard, numbered sections used in technical documents. For unnumbered sections, use
\section*
\subsection*
\subsubsection*

and so on.

LaTeX provides many environments for formatting displayed material. You can include quoted text with the quotation environment.

\begin{quotation}
Start of paragraph to be quoted...

... end of paragraph.
\end{quotation}

For shorter quotes, you can use the quote environment.

To format verse, use the verse environment.

\begin{verse}
Because I could not stop for death\\
He kindly stopped for me
\end{verse}

Notice that you must use the double backslashes to break lines in the correct places. Otherwise, LaTeX fills the lines in a verse environment, just like any other environment.

Lists come in several flavors. To format a bulleted list, the list environment is used:

\begin{list}
\item
This is the first item of the list.
\item
This is the second item of the list...
\item
... and so on.
\end{list}


A numbered list uses the enumerate environment:

\begin{enumerate}
\item
Item No. 1.
\item
Item No. 2.
\item
\dots
\end{enumerate}


A descriptive list uses the description environment.

\begin{description}
\item{Oven} Dirty, needs new burner.
\item{Refrigerator}  Dirty.  Sorry.
\item{Sink and drainboard}  Stained, drippy, cold water faucet.
\end{description}


### Letters.

The letter class uses special definitions to format business letters.

The letter environment takes one argument, the address of the letter's addressee. The address command, which must appear in the document preamble, defines the return address. The signature command defines the sender's name as it appears after the closing.

The LaTeX source of a simple business letter might look like this.

\documentclass[12pt]{letter}
\signature{John Q. Public}
\address{123 Main St.\\Los Angeles, CA.  96005\\Tel: 123/456-7890}
\begin{document}
\begin{letter}{ACME Brick Co.\\100 Ash St.\\San Diego, CA 96403}

With regard to one of your bricks that I found on my living room
carpet surrounded by shards of my broken front window...

(Remainder of the body of the letter.)

\closing{Sincerely,}

\end{letter}
\end{document}

Note that the addresses include double backslashes, which specify where the line breaks should occur.

## 5.3 LaTeX extension packages and other resources.

We mentioned above that using underlining as a form of text emphasis presents special problems. Actually, TeX has no problem underlining text, because it is a convention of mathematical typesetting. In LaTeX, you can underline words with the command:

\underline{text to be underlined}

The problem is that underlining will not break across lines, and, in some circumstances, underlining can be uneven. However, there is a LaTeX macro packagem, ready-made, that makes underlining the default mode of text emphasis. It's called ulem.sty, and is one of the many contributed LaTeX packages that are freely available via the Internet.

To use ulem.sty, include the command

\usepackage{ulem}

in the document preamble.

The LaTeX Catalogue provides one-line descriptions of every LaTeX package available, their names and CTAN paths. For the URL of the most current edition of the Catalogue, see the section Resources for further information.

The packages which are available for LaTeX include:

ifthen

Include conditional statements in your documents.

initials

Defines a font for initial dropped capitals.

sanskrit

Font and preprocessor for producing documents in Sanskrit.

recipe

A LaTeX2e class to typeset recipes.

refman

Variant report and article styles.

To make the path given in the Catalogue into a fully-qualified URL, concatenate the path to the hostname URL and top-level path of the CTAN archive you wish to contact. For example, the top-level CTAN directory of the site ftp.tex.ac.uk is ctan/tex-archive. The complete URL of the directory of the refman package would be:

ftp://ftp.tex.ac.uk/ctan/tex-archive/   +
macros/latex/contrib/supported/refman   =

ftp://ftp.tex.ac.uk/ctan/tex-archive/macros/latex/contrib/supported/refman/

Some packages have more than one file, so only the path to the package's directory is given.

When you have the URL in hand, you can retrieve the package from one of the CTAN archive sites listed in section Appendix A. You can download a complete list of the archive's contents as the file FILES.byname, in the archive's top-level directory. You can also search the archive on line for a keyword with the ftp(1) command

quote site index <keyword>