Grabbed from: http://eksl-www.cs.umass.edu/tex/readme.html [2000­09­18]

EKSL LaTex Guide

This document covers the following topics in somewhat rambling order:

Running LaTex

What is LaTeX and how do you run it? You should certainly read Leslie Lamport's manual (there are many copies around the EKSL), but that manual often refers to a mythical "local guide." You may think of this document as a kind of "local guide." In addition, before you run LaTeX you should see this CSCF document which explains how to set up your Unix environment correctly.

LaTeX is a program that takes an ascii text file that includes LaTeX commands like \section, and produces what's called a "dvi" file. "dvi" stands for "device independent" and it's a description of where the letters and rectangular blobs of ink are to go on the page. This is then translated into the language understood by various printers, such as ln03 or PostScript. In this department, almost every printer is a PostScript printer, so you almost always do the following. 

latex foo.tex
dvips foo.dvi
lpr foo.ps
If you're using BibTeX to do your bibliography, you have to add a few more steps. The first pass through latex writes out (to the .aux file) all the \cite information and the bibliography database files you want searched. Running BibTeX then looks up those citations and writes a .bbl file. Running latex again reads in the .bbl file to create the bibliography. However, the reference numbers of those new entries have to be propagated back to the places in the text where your \cite commands are, which requires a final run of latex. So the complete process is: 
latex foo
bibtex foo
latex foo
latex foo
dvips foo
lpr foo.ps
(The extensions are usually optional, since all the programs except lpr know what kind of file they are looking for.) All these steps are necessary if you are starting from scratch. Usually, you've run many drafts through latex and so most of the information has propagated to the right places. LaTeX will warn you if there are citations that are still unknown. The procedure is the same if you are doing an index, except you run the makeindex program instead of the BibTeX program.

Previewing

If you want to preview your document, there are two options: xdvi and ghostview.

xdvi is a program that reads the .dvi file and displays it on your X server (your terminal). One thing that's nice is that it will re-read your .dvi file when it changes, so if you are doing a number of drafts and previewing, you can save time by "suspending" xdvi while editing instead of killing it. That is, make it a background process and just turn it into an icon while you edit your file and re-run latex. Here's the procedure: 

latex foo
xdvi foo.dvi &   
<view foo and then click the button to iconize the window>
<edit foo.tex>
latex foo
A word about PostScript (PS) figures. When you put a PS figure in your document, LaTeX doesn't do anything with it except to pass the buck to dvips. When dvips reads the .dvi file, it finds the little messages left by LaTeX and reads in the appropriate PS file or puts in the PS code or whatever. Consequently, older versions of xdvi didn't show any PS figures you might have; they just showed as whitespace. Newer versions of xdvi will usually run GhostScript to read in PS files, so pictures can also be viewed, but this doesn't always work. If you want to see what the final document will really look like, you have to use ghostview.

Ghostview is a program that executes PS code and displays it on your terminal. Obviously, you have to have run dvips to use it. Therefore, the procedure is 

latex foo
dvips foo
ghostview foo.ps
Ghostview can be made to re-read the .ps file, so you can play the same backgrounding trick that we can with xdvi. Ghostview is slower to use than xdvi, so I usually use xdvi.

Printing

Finally, you'll want to print your .ps file. The unix command is lpr. If you don't specify a printer name, it'll go to the printer that is the value of your PRINTER environment value, so most people set that up to be "joshua," "woper," or even "eksllw." (The last printer is EKSL's laser writer in 309.) To make it go to a non-default printer, specify the printer with capital "P": 
lpr -Pwoper foo.ps
You can specify many flags here. A useful one is -K2, which prints two-sided. (On woper; other printers can't handle two-sided printing.) If you are sending the file to an unfamiliar printer, you can use the "psprint" command, which gives you a menu of the department's printers.

RCF has packaged up a lot of the preceding procedures into shell files called latex.sh (for 2.09) and latex2e.sh (for 2e). If you run these on a tex file, they will run latex and then give you menus for re-running latex, running xdvi, running BibTeX, running dvips, and running psprint. It can be very convenient. The only disadvantage is that you can't play the backgrounding tricks I described.

Spell Checking

An important tool for writing is a spelling checker; even excellent spellers make typing mistakes. If you want a batch of the mistakes, you can do the following Unix incantation: 

cat foo.tex | ispell -lt | sort | uniq | more
Personally, I prefer the Emacs interface to ispell, which allows you to build up a file-specific dictionary of acceptable words. These words are written into the .tex file, but commented out so that LaTeX won't see them. Here's an excerpt from a paper of mine: 
% LocalWords:  subst TCL arity cl butlast cdr TSP SPARCstation hereon
To use ispell, you have to put one or two things into your .emacs file. (Actually, I'm not absolutely sure these are necessary, but ispell works for me.) Here's my ispell initialization stuff: 
(setq ispell-program-name "/exp/rcf/share/bin/ispell")

;;; This defeats the incorrect regexp for skipping TIB entries.
(setq ispell-check-tib t)
The necessity of the second thing is strange, but Emacs ispell has a regular expression used for skipping stuff that isn't supposed to be spell-checked, and when I discovered ispell erroneously skipping large chunks of a file one time, I was able to get it to behave by setting this variable.

Once these variables are set, you can just say M-x ispell-buffer (or select "spell" from the "edit" menu). You can spell check a single word with M-$. It takes a moment the first time to run ispell, since it has to start up a process, but after that, it's nearly instantaneous. For those of you who use Emacs to read mail or news, there is the command M-x ispell-message. The ispell commands are: 

DIGIT: Replace the word with a digit offered in the *Choices* buffer.
SPC:   Accept word this time.
`i':   Accept word and insert into private dictionary.
`a':   Accept word for this session.
`A':   Accept word and place in `buffer-local dictionary'.
`r':   Replace word with typed-in value.  Rechecked.
`R':   Replace word with typed-in value. Query-replaced in buffer. Rechecked.
`?':   Show these commands.
`x':   Exit spelling buffer.  Move cursor to original point.
`X':   Exit spelling buffer.  Leaves cursor at the current point, and permits
        the aborted check to be completed later.
`q':   Quit spelling session (Kills ispell process).
`l':   Look up typed-in replacement in alternate dictionary.  Wildcards okay.
`u':   Like `i', but the word is lower-cased first.
`m':   Like `i', but allows one to include dictionary completion information.
`C-l':  redraws screen
`C-r':  recursive edit
`C-z':  suspend emacs or iconify frame
You can get that listing at any time in emacs by C-h d ispell-help.

One cool command is "A," which adds the offending word to the list of acceptable words at the bottom of your file, as I explained above. If you always want a word to be acceptable (your name, for example), you can put it in your private dictionary with the "i" command. Your private dictionary is ~/.ispell_words.

There is an ispell-region command if you just want to check a portion of your file. I have found it convenient to implement an Emacs command that runs ispell from your current location (point) to the end of the buffer. You can do this too by putting the following into your .emacs file: 

(defun ispell-rest ()
  "Invokes ispell from current point to end of buffer."
  (interactive)
  (ispell-region (point) (point-max)))
This can be invoked as a M-x command. I decided to bind this to C-M-$, too, which is done by the following horror. (If anyone knows a better way, please tell me.) 
(global-set-key '[12582948] 'ispell-rest) ; C-M-$

Style Files

We now switch topics to things that you do within latex, particularly customizing it by use of style files.

What is a "style file"? The idea of LaTeX is "structured markup," where the document uses abstract terms like "section" and something else decides that the visual expression of "section" means skipping half an inch, incrementing the section counter to number the section, setting the section number and heading in large bold, and so forth. This "something else" is the style file. Thus, LaTeX reads "article.sty" and "art10.sty" to know how to typeset 10 point articles. Journals and publishing houses often produce their own style files.

LaTeX works as layers of macros on top of the primitives of the TeX language. Therefore, it's also a weird kind of programming language. People have extended LaTeX to do useful things and they package up their programs into things called "style" files. A good example of this is "cite.sty" by Donald Arseneau. By default, the \cite command can produce [18,13,15,14]. Among other things, cite.sty arranges for such groups of citations to appear as [13--15,18]; that is, they are sorted into increasing order and sequences of citations are elided. Pretty cool.

How do you use a style file? It depends on whether you are using LaTeX 2.09 or LaTeX2e, which is a newer version of LaTeX put out by the LaTeX3 team. In 2.09, you put their names in the square brackets of the documentstyle command: 

\documentstyle[artadj,10pt,cite,sda]{article}
In 2e, style files are called packages, and you load them via the \usepackage command: 
\documentclass[10pt]{article}
\usepackage{artadj,cite,sda}
(There is a reason for this change; ask me if you want to know.)

There are dozens of useful packages (style files) described in the LaTeX Companion, a book that EKSL owns a copy of. See Peggy Weston to look at it.

Setting Up

When LaTeX runs and it sees a package or style file that you want to load, it searches for it in your TEXINPUTS path. RCF has kindly defined a number of shell files to initialize all the myriad TeX-related shell variables. You load the one you want as part of your login procedure. I use the bash shell, so my .bashrc file contains the following line: 
source /exp/rcf/common/tex-6.1/SETUP-YOUR-ENVIRONMENT.bash
You would substitute a different file and use a different syntax for loading the file depending on what shell you use. Talk to Westy, me, or RCF if you have trouble. By the way, I use 2e. If you use 2.09, you would find the RCF's setup files in a different directory: 
source /exp/rcf/common/tex/SETUP-YOUR-ENVIRONMENT.bash
This defines TEXINPUTS to look in the RCF directories of LaTeX stuff.

Now, suppose you want to load a style file that RCF doesn't provide? You would want to have the TEXINPUTS path include a directory of your own. Again, the following syntax depends on what shell you use, but here's what I do: 

source /exp/rcf/common/tex-6.1/SETUP-YOUR-ENVIRONMENT.bash
TEXINPUTS=.:~eksl/tex/inputs:~eksl/tex/pstricks/inputs:$TEXINPUTS
BIBINPUTS=.:~eksl/tex/bib:$BIBINPUTS
The leading "." tells TeX to always look in my current directory first. Then it will look in two EKSL group directories, and finally in whatever directories RCF has specified (the current value of $TEXINPUTS). The directories where BibTeX looks have been similarly modified. These modifications should work correctly whether you use 2e or 2.09; they do for me.

Personal Style Files

Now we've defined the paths so that LaTeX will search a directory where we can put our own style files. For example, I have a style file where I put all sorts of random stuff; it goes by my initials, "sda.sty." Why have I put it in EKSL's group directory of style files? Mainly, so that Peggy Weston (or anyone else) can LaTeX my files. You're on your honor not to edit my personal style file, but you are welcome to look through it for useful stuff or inspirations. No warranties expressed or implied, your mileage may vary, etc., etc. For the same reasons, you are encouraged to put your own style files in this directory: 
~eksl/tex/inputs/
Another way we can all share and help one another is bibliographic information. I've put all my BibTeX entries in a single long file, "sda.bib," in the EKSL bibliography directory. EKSL's group bibliography files are in that directory, namely: 
~eksl/tex/bib/
Please add your own BibTeX database files to this directory, because this lets others easily copy references that you have.

EKSL Style Files

Where do other style files in the EKSL tex inputs directory come from and what do they do? First, there's the "pstricks" directory. This is a large group of related style files written by Timothy Van Zandt that allow you to do various cool stuff like rotating text or putting boxes around verbatim text. It comes with documentation (in ~eksl/tex/pstricks/doc/). In the main EKSL tex inputs directory, there are a bunch of style files. The EKSL files are a hodgepodge of macros written over the years, but there are some useful nuggets. There is an index file in that directory describing them (~eksl/tex/inputs/INDEX.text). Many style files have documentation in them, so you can read them for more information. Also, many are documented in the LaTeX Companion, except, obviously, for those written at UMass.

More Style Files

There are many, many more packages and style files implemented. RCF has many of them in directories that are already on the TEXINPUTS path, so you don't even have to go to any effort to use them. Look in the LaTeX Companion for solutions to LaTeX problems; the Companion will often say that the solution is implemented in a package, and you can just try it to see if we have it. Another way to see if we have a particular package, say foo.sty is: 
find /exp/rcf/common/tex-6.1/inputs/ -name foo.sty -print
If it's there and you use 2e, you can use it.

You might also look in the ~eksl/tex/examples/ directory to see examples of letters, articles, tech reports and so forth.

Some of these style files may be specific to either 2e or 2.09. The only way to tell for sure is try them.

LaTex Versions

With all this talk of 2.09 and 2e, what's the difference and which LaTeX should you use? LaTeX2e is an improvement of 2.09. Internally, it has cleaned up some of the macro definitions, allowed more parameterization and so forth. These differences, however, are minor. Most of the work went into fonts, particularly font selection. You may have heard about the New Font Selection Scheme (NFSS) that was implemented a few years ago for LaTeX, and quickly superseded by NFSS2; 2e incorporates those changes. I honestly don't know or understand most of the details of NFSS, but my understanding is that LaTeX's Old Font Selection Scheme (OFSS) had hardwired most of the fonts, tying users to the Computer Modern Family. OFSS even made it hard to select really large sizes, which is why SliTeX had to exist, since it pre-selected the large font sizes that are used with slides. With NFSS, I'm told it's easier to select other fonts, so that slides is now just a LaTeX package and SliTeX is obsolete. Font attributes are also more "orthogonal": in 2.09 \large\bf would get you a large bold font, but \bf\large would get you a normal weight large font, because the \large would "override" the \bf; in 2e, either ordering gets you a large bold font. Also, in 2.09 \bf\it would get you a normal weight italic, while 2e will give you a bold-italic font if it can find one.

It's also possible to select PostScript fonts (using the psnfss package, I think). So, if you've always wanted to use LaTeX and the Palantino font, you can. I've never done this, since I've so far been pretty happy with the Computer Modern fonts, but someday I hope to check it out.

One caveat: 2e, in trying to be smarter about fonts, is also more informative. It'll tell you, for example, that it can't find a bold tt font and it's substituting normal weight tt. 2.09 would simply have made the substitution and not told you a thing. Thus, it'll seem like 2e is doing worse than 2.09, because you're getting more warnings, but that's merely an illusion.

Unless you're playing with fonts, 2.09 and 2e are pretty much the same. 2e has a "compatibility mode" which runs 2.09 LaTeX files unchanged; therefore, you give up nothing by using 2e. You get to use some new commands like \emph, which replaces \em. (See, with \em, you were supposed to add an italic correction (\/) to the end of the emphasized text, so that the spacing is correct: {\em like this\/}, but the \emph command takes care of that for you, \emph{like this}.) Using 2e also lets you take advantage of new packages as they are being developed; few people are developing packages for 2.09, and no one is developing packages that are incompatible with 2e. Personally, I use 2e, but make your own decision; I'm not going to be responsible.

LaTeX2e is documented in the new edition of Lamport; EKSL owns a copy of this.

LaTex FTP Sites

I mentioned packages that are being developed. Where do these come from? Most of them come from CTAN, the Comprehensive TeX Archive Network. These are three sites (and mirrors) that are repositories of TeX- and LaTeX-related stuff, including fonts, programs (such as dvips, makeindex, and bibtex as well as tex and latex), and packages. The three major sites are 
ftp.shsu.edu (US)
ftp.dante.de (Germany)
ftp.tex.ac.uk (England)
There are numerous mirror sites. You can find a list by fingering ctan_us@ftp.shsu.edu

The FAQ is in the directory tex-archive/help

The "quote site index " command will search all over the archive to find "" for you. So if you read about "fancybox.sty" in the LaTeX Companion and want to get it, just type 

ftp> quote site index fancybox.sty
and it'll tell you where it is. Of course, we already have fancybox.sty, but you get the idea. Put it in the EKSL inputs directory so that we can all use it. It would be really nice to update the index document, too, to describe what the new package does.

One small warning. Package implementers are starting to use a documentation system that is combined with the package in a .dtx file. Thus, you might have to look for "here.dtx" instead of "here.sty." A .dtx file can be used just like a .sty file, but if you run it through latex by itself: 

latex here.dtx
it will produce nicely typeset documentation. I don't know whether .dtx files will be correctly processed by 2.09; I've always used 2e and not had any trouble.

As always, if you have any problems, you can contact me, and I'll try to help.

Last Update: 3/21/95

Scott D. Anderson anderson@cs.umass.edu