Making TeX Work

Preface

TeX is a tool for creating professional quality, typeset pages of any kind. It is particularly good, perhaps unsurpassed, at typesetting mathematics; as a result, it is widely used in scientific writing. Some of its other features, like its ability to handle multiple languages in the same document and the fact that the content of a document (chapters, sections, equations, tables, figures, etc.) can be separated from its form (typeface, size, spacing, indentation, etc.) are making TeX more common outside of scientific and academic circles.

Designed by Donald Knuth in the late 1970s, more than a decade of refinement has gone into the program called “TeX” today. The resulting system produces publication-quality output while maintaining portability across an extremely wide range of platforms.

Remarkably, TeX is free. This fact, probably as much as any other, has contributed to the development of a complete “TeX system” by literally thousands of volunteers. TeX, the program, forms the core of this environment and is now supported by hundreds of tools.

Why Read This Book?

This book is for anyone who uses TeX. Novices will need at least one other reference, because this book does not describe the nuts and bolts of writing documents with TeX in any great detail.

If you are new to TeX, there is much to learn. There are many books that describe how to use TeX. However, the focus of this book is mostly at a higher level. After digesting Chapter 1, Chapter 1, you should be able to proceed through the rest of the book without much difficulty even if you have never seen TeX before. So, if you are a system administrator interested in learning enough about these programs to install and test them for your users, you should be all set. If you are interested in learning how to write documents with TeX, this book will be helpful, but it will not be wholly sufficient.

Why do you need this book at all? Although many individual components of the TeX system are well documented, there has never before been a complete reference to the whole system. This book surveys the entire world of TeX software and helps you see how the various pieces are related.

A functioning TeX system is really a large collection of programs that interact in subtle ways to produce a document that, when formatted by TeX, prints the output you want. All the different interactions that take place ultimately result in less work for you, the writer, even though it may seem like more work at first. Heck, it may be more work at first, but in the long run, the savings are tremendous.

Many books about TeX refer the reader to a “local guide” for more information about previewing and printing documents and what facilities exist for incorporating special material into documents (like special fonts and pictures and figures). In reality, very few local guides exist.

The TeX environment is now mature and stable enough to support a more “global guide.” That is what this book attempts to be. It goes into detail about previewing and printing, about incorporating other fonts, about adding pictures and figures to your documents, and about many other things overlooked by other books.

Because fonts play a ubiquitous role in typesetting, this book is also about MetaFont, the tool that Donald Knuth designed for creating fonts.

Scope of This Book

Here's how the book is laid out.

Part I: Part I.

Chapter 1, Chapter 1. If you don't know anything about TeX at all, this chapter will help you get started. If you're a system adminstrator charged with the task of installing and maintaining TeX tools, you'll get enough information to do the job.

Chapter 2, Chapter 2. An overview of some environments that can make working with TeX documents easier. It describes some editors that “understand” TeX, how to integrate TeX into a “programmer's editor,” spellchecking, revision control, and other aspects of TeXnical editing.

Chapter 3, Chapter 3. The mechanics of running TeX, the program. It discusses what things TeX needs to be able to run, how to start TeX, command-line options, leaving TeX, and recovery from errors.

Chapter 4, Chapter 4. Overview of TeX macro packages. This chapter describes how to make a format file, the major general-purpose writing packages, some special-purpose writing packages, how to make slides for presentations, and how to handle color in TeX.

Part II: Part II.

Chapter 5, Chapter 5. This chapter explores the issues that need to be addressed when using fonts. Many of these issues are not particularly TeX-related, but TeX is very flexible, and it's important to understand the tradeoffs that must be made. This chapter also examines some TeX-specific issues: font selection, files that TeX needs, automatic font generation, and virtual fonts.

Chapter 6, Chapter 6. How many ways are there to include pictures and figures in a TeX document? Lots and lots of ways. This chapter examines them all.

Chapter 7, Chapter 7. TeX is well qualified to do international typesetting. This chapter looks at the issues that are involved: representing international symbols in your input file, what TeX produces, getting the right fonts, multiple languages in the same document, and macro packages and style files that solve some of these problems. Some strategies for dealing with very difficult languages (like Japanese and Arabic) are also explored.

Chapter 8, Chapter 8. What goes in has to come out. This chapter tells the what, where, why, and how of printing your documents.

Chapter 9, Chapter 9. Save paper; preview your documents before you print them.

Chapter 10, Chapter 10. Online documentation is becoming increasingly popular. This chapter explores different ways that both typeset and online documentation can be produced from the same set of input files.

Chapter 11, Chapter 11. Sometimes it is necessary or desirable to create a special version of a standard TeX font. Maybe you really need the standard 10pt font at 11.3pt. This chapter will tell you how to work with existing MetaFont fonts. It won't tell you how to create your own fonts; that's a whole different story.

Chapter 12, Chapter 12. Maintaining a bibliographic database can be a great timesaver. This chapter looks at the BibTeX program and other tools for building and using bibliographic databases. It also discusses the creation of indexes and glossaries.

Part III: Part III.

Chapter 13, Chapter 13. Many TeX environments are freely available. This chapter describes public domain, free, and shareware versions of TeX.

Chapter 14, Chapter 14. A large, complex system like TeX can be overwhelming (although I hope less so after you read this book ;-). One of the advantages of selecting a commercial implementation of TeX is that some form of customer support is usually provided. Still other commercial implementations offer features not found in any free releases. This chapter describes several commercial TeX releases.

Chapter 15, Chapter 15. Many issues discussed in this book apply equally to all platforms, including the Macintosh platform, but the Mac has its own special set of features. This chapter looks at some versions of TeX and other tools designed specifically for use on the Mac.

Chapter 16, Chapter 16. This chapter lists many of the the utilities available in the CTAN archives and provides a brief description of what they do.

Appendix A, Appendix A. Lots of files can be identified by their extensions. This appendix lists the extensions that are most often seen in conjunction with TeX and describes what the associated files contain.

Appendix B, Appendix B. Examples of many MetaFont fonts available from the CTAN archives.

Appendix C, Appendix C. A complete list of the resources described in this book.

Appendix D, Appendix D. This appendix contains examples (scripts, batch files, programs) that seemed too long to place in the running text.

Bibliography. Where I learned what I know. Also, where you can look for more information about specific topics.

Conventions Used in This Book

The following typographic conventions are used in this book:

Italic

is used for filenames, directories, user commands, program names, and macro packages (except where the distinctive logo type is used). Sometimes italics are used in the traditional way for emphasis of new ideas and important concepts.

Typewriter

is used for program examples, FTP sites, TeX control sequences, and little bits of TeX syntax that appear in running text (for example, typewriter text in a reference to the LaTeX picture environment is a clue that LaTeX literally uses the word “picture” to identify this environment).

\bf Typewriter Bold

is used in examples to show the user's actual input at the terminal.

\it Typewriter Italic

identifies text that requires a context-specific substitution. For example, filename in an example would be replaced by some particular filename.

Footnotes

are used for parenthetical remarks. Sometimes, lies are spoken to simplify the discussion, and the footnotes restore the lie to the truth. (And sometimes they don't ;-)

Filename extensions, like “.tex” in book.tex, are shown in uppercase letters when referring to a particular type of file. For example, a TeX Font Metric or TFM file would be somefile.tfm. The actual extension of the file may be different (upper or lowercase, longer or shorter) depending on your operating environment.

When the shell prompt is shown in an example, it is shown as a dollar sign, \$. You should imagine that this is your system's prompt, which might otherwise be <!--, C>, --> [C:\], or a dialog box.

When spaces are important in an example, the “{ }” character is used to emphasize the spaces. Effective, isn't it?

In some places, I refer to specific keys that you should press. When it's important that I mean pressing particular keys and not typing something, I emphasize the keys. For instance, an example that includes Enter means that you should literally press the Enter or Return key. The sequence Ctrl-D means that you should press and hold the “Control” and “d” keys simultaneously. Control-key combinations aren't case sensitive, so you needn't press the shift key.

How to Get TeX

TeX and the other programs mentioned in this book are available from a number of places. It's impossible to list all of the places where you might find any given tool, but there is one place where you will almost certainly find every tool: the Comprehensive TeX Archive Network (CTAN).

This network is a fully-mirrored anonymous FTP hierarchy in three countries. Always use the FTP site that is geographically closest to you. The following table lists the current members of CTAN as of July, 1993:

Table 1.

You may also access the CTAN archives by electronic mail if you do not have FTP access. For up-to-date instructions about the mail server, send the single-line message help to [e-mail].

Where Are the Files?

Every CTAN mirror site has the same well-organized directory structure. The top-level directory also contains a complete catalog of current files organized by name, date, and size. The catalogs are named FILES.byname, FILES.bydate, and FILES.bysize, respectively, in the top level directory. The top-level directory contains the following subdirectories:

<table>
<title></title>
<tgroup cols="1">
<colspec align="left">
<colspec align="left">
<thead>
<row>
  <entry>Directory</entry>
  <entry>Description of Contents </entry>
</row>
</thead>
<tbody>
<row>
  <entry>tools</entry>
  <entry>Archiving tools (<command>unzip</command>, <command>tar</command>, <command>compress</command>, etc.) </entry>
</row>
<row>
  <entry>biblio</entry>
  <entry>Tools for maintaining bibliographic databases </entry>
</row>
<row>
  <entry>digests</entry>
  <entry>Electronic digests (&TeX;hax, UK&TeX;, etc.)</entry>
</row>
<row>
  <entry>info</entry>
  <entry>Free documentation, many good guides </entry>
</row>
<row>
  <entry>dviware</entry>
  <entry>Printing and previewing software </entry>
</row>
<row>
  <entry>fonts</entry>
  <entry>Fonts for &TeX; </entry>
</row>
<row>
  <entry>graphics</entry>

<entry>Software for working with pictures and figures </entry>
</row>
<row>
  <entry>help</entry>
  <entry>Online help files, etc. </entry>
</row>
<row>
  <entry>indexing</entry>
  <entry>Indexing and glossary building tools </entry>
</row>
<row>
  <entry>language</entry>
  <entry>Multi-national language support </entry>
</row>
<row>
  <entry>macros</entry>
  <entry>Macro packages and style files </entry>
</row>
<row>
  <entry>misc</entry>
  <entry>Stuff that doesn't fit in any other category </entry>
</row>
<row>
  <entry>support</entry>
  <entry>Tools for running and supporting &TeX;</entry>
</row>
<row>
  <entry>systems</entry>
  <entry>OS-specific programs and files</entry>
</row>
<row>
  <entry>web</entry>
  <entry>Sources for &TeX; programs (in &Web;) </entry>
</row>
</tbody>
</tgroup>
</table>

The archives at ftp.shsu.edu and ftp.tex.ac.uk also support gopher access to the archives. The UK gopher supports indexed access to the archives. A World Wide Web (hypertext) interface to the archives is available from:

http://jasper.ora.com/ctan.html

This interface includes brief descriptions of many packages and the ability to perform keyword and date searches.

Getting Software Without FTP

The electronic alternatives to FTP, described in the section “the section called “Getting Examples From This Book”” of this chapter are also viable alternatives for getting software from the CTAN archives.

In addition, there are a number of ways to get distributions through nonelectronic channels. The names and addresses of these sources are listed in Appendix C, Appendix C.

You can get many of the popular TeX distributions on diskette from the TeX Users Group (TUG). Emacs, Ghostscript, and other packages by the Free Software Foundation (FSF) are available on tape directly from the FSF. You may also find large bulletin board systems that support TeX (for example, Channel1 in Cambridge, MA)

Getting Examples From This Book

All of the substantial code fragments and programs printed in this book are available online. The examples in this book are all in Perl, a language for easily manipulating text, files, and processes. I decided to use Perl simply because it is available for every platform discussed in this book. It is the only “universal” scripting language that will work under MS-DOS, OS/2, unix, and the Macintosh. All of the scripts in this book can be converted to a different scripting language (the various unix shells or something like 4DOS's extended batch language for MS-DOS and OS/2) if you prefer. I've tried to write the Perl scripts in a straightforward way so that any given task won't be too difficult.

The examples are available electronically in a number of ways: by FTP, FTPMAIL, BITFTP, and UUCP. The cheapest, fastest, and easiest ways are listed first. If you read from the top down, the first one that works is probably the best. Use FTP if you are directly on the Internet. Use FTPMAIL if you are not on the Internet but can send and receive electronic mail to Internet sites (this includes CompuServe users). Use BITFTP if you send electronic mail via BITNET. Use UUCP if none of the above work.

Note

The examples were prepared using a unix system. If you are running unix, you can use them without modification. If you are running on another platform, you may need to modify these examples to correct the end-of-line markers. For example, whereas under unix every line ends with a line feed character (the carriage return is implicit), under DOS every line must end with explicit carriage return and line feed characters.

FTP

To use FTP, you need a machine with direct access to the Internet. A sample session is shown below.

\${\bf ftp ftp.uu.net} Connected to ftp.uu.net.
220 ftp.UU.NET FTP server (Version 6.34 Oct 22 14:32:01 1992) ready.
Name (ftp.uu.net:prefect): {\bf anonymous}
331 Guest login ok, send e-mail address as password.
Password:{\bf [e-mail]} \  \  \  {\rm\it\small (use your user name and host here)}
230 Guest login ok, access restrictions apply.
ftp>{\bf cd /published/oreilly/nutshell/maketexwork}
250 CWD command successful.
ftp>{\bf get README}
200 PORT command successful.
150 Opening ASCII mode data connection for README (xxxx bytes).
226 Transfer complete.
local: README remote: README xxxx bytes received in xxx seconds (xxx Kbytes/s)
ftp>{\bf binary} \  \  {\rm\it\small (select binary mode for compressed files)}
200 Type set to I.
{\rm\it\small  \ (Repeat get commands for the other files.}
{\rm\it\small  \  They are listed in the README file.)}
ftp>{\bf quit} 221 Goodbye.
\$

FTPMAIL

FTPMAIL is a mail server available to anyone who can send electronic mail to, and receive it from, Internet sites. This includes most workstations that have an email connection to the outside world and CompuServe users. You do not need to be directly on the Internet.

Send mail to [e-mail]. In the message body, give the name of the anonymous FTP host and the FTP commands you want to run. The server will run anonymous FTP for you and mail the files back to you. To get a complete help file, send a message with no subject and the single word help in the body. The following is an example mail session that should get you the examples. This command sends you a listing of the files in the selected directory and the requested example files. The listing is useful if there's a later version of the examples you're interested in.

\${\bf mail [e-mail]}
Subject: {\bf{}reply [e-mail]} \  \ {\rm\it\small (where you want files mailed)}
{\bf{}connect ftp.uu.net}
{\bf{}chdir /published/oreilly/nutshell/maketexwork}
{\bf{}dir}
{\bf{}get README}
{\bf{}quit}

A signature at the end of the message is acceptable as long as it appears after quit.

BITFTP

BITFTP is a mail server for BITNET users. You send it electronic mail messages requesting files, and it sends you back the files by electronic mail. BITFTP currently serves only users who send it mail from nodes that are directly on BITNET, EARN, or NetNorth. BITFTP is a public service of Princeton University.

To use BITFTP, send mail containing your FTP commands to BITFTP@PUCC. For a complete help file, send HELP as the message body.

The following is the message body you should send to BITFTP:

FTP ftp.uu.net NETDATA USER anonymous PASSyour Internet e-mail address      {\rm\it\small (not your BITNET address)}
CD /published/oreilly/nutshell/maketexwork DIR GET README QUIT

Questions about BITFTP can be directed to MAINT@PUCC on BITNET.

UUCP

UUCP is standard on virtually all unix systems and is available for IBM-compatible PCs and Apple Macintoshes. The examples are available by UUCP via modem from UUNET; UUNET's connect-time charges apply. You can get the examples from UUNET whether you have an account or not. If you or your company has an account with UUNET, you will have a system with a direct UUCP connection to UUNET. Find that system, and type (as one line):

\$ uucp uunet\! /published/oreilly/nutshell/maketexwork/README \
\  \ yourhost\! /yourname/

The README file should appear some time later (up to a day or more) in the directory /usr/spool/uucppublic/yourname. If you don't have an account, but would like one so that you can get electronic mail, contact UUNET at 703-204-8000.

If you don't have a UUNET account, you can set up a UUCP connection to UUNET in the United States using the phone number 1-900-468-7727. As of this writing, the cost is 50 cents per minute. The charges will appear on your next telephone bill. The login name is uucp with no password. Your entry may vary depending on your UUCP configuration.

Gopher

If you are on the Internet, you can use the gopher facility to learn about online access to examples through the O'Reilly Online Information Resource. Access gopher.ora.com as appropriate from your site.

Versions of TeX

The most recent versions of TeX and MetaFont are version 3.1415 and version 2.71, respectively. Version 3 of TeX introduced several new features designed to improve support for non-English languages (including the use of 8-bit input and some refinements to hyphenation control). If you use an older version of TeX, you should upgrade.

Donald Knuth has specified that TeX's version number converges to $π$, therefore version 3.1415 is only the fourth minor revision after version 3. The next minor revision will be version 3.14159. Similarly, MetaFont's version number converges to $e$ (2.7182818284$...$).

Implementations and Platforms

The interface that TeX presents to the writer is very consistent. Most of the examples described in this book are applicable to every single implementation of TeX. However, TeX is not a closed system. It is possible to step outside of TeX to incorporate special elements into your document or take advantage of the special features of a particular environment. These extensions can dramatically restrict the portability of your documents.

Many of the topics covered in this book offer alternatives in those areas that are less portable. Therefore, it is natural to ask what implementations are really covered.

Before outlining which implementations are covered, let me suggest that this book will be useful even if you are using an implementation not “officially” covered here. The reality of the situation is this: many, many tools have been ported with TeX. Many of the tools mentioned in this book are available on platforms that are not specifically discussed. Time and equipment constraints prevented Amiga, Atari, NeXT, VMS, and Windows NT implementations of TeX from being specifically addressed in this edition of the book.

UNIX

unix is probably the most common TeX platform. The emphasis in this book is on unix workstations running X11, producing output for PostScript and HP LaserJet printers.

Linux and other personal computer implementations of unix are not addressed specifically; however, with the successful port of X11 to Linux, I'm confident that every unix tool here can be, or has been, ported to Linux (and probably other PC unix environments).

The only implementation of the TeX program for unix considered in any detail is the free implementation distributed in web2c. This distribution is described in the section called “the section called “Web2C”” in Chapter 13, Chapter 13. Most of the other unix tools discussed here are also free.

MS-DOS

With very few exceptions, the tools in this book are available under MS-DOS. Because PCs are very popular, a lot of effort has gone into porting unix tools to MS-DOS. Some packages, however, require a 386SX (or more powerful) processor. For the most part, I focus on PCs running MS-DOS only; however, Microsoft Windows and DesqView are not entirely ignored.

There are quite a few options when it comes to selecting an implementation of the TeX program under MS-DOS. Several free implementations are discussed as well as some commercial implementations. For more information about these implementations, consult Chapter 13, Chapter 13, and Chapter 14, Chapter 14.

OS/2

In this book, OS/2 is treated primarily as a superset of MS-DOS. When possible, I look at OS/2-specific versions of each utility, but rely on MS-DOS as a fall-back.

Extensions to emTeX for OS/2 are explored, as are editing environments such as epm. The multi-threaded nature of OS/2 allows more complete porting of unix tools. When better ports are available for OS/2, they are discussed.

Macintosh

The Macintosh is very different from the systems described above. Chapter 15, Chapter 15, discusses the Macintosh environment in detail.

There are four implementations of TeX for the Macintosh. Three are freely available, and one is commercial: CMacTeX is free, OzTeX and DirectTeX are shareware, and Textures is a commercial package from Blue Sky Research.

We'd Like to Hear From You

We have tested and verified all of the information in this book to the best of our ability, but you may find that features have changed (or even that we have made mistakes!). Please let us know about any errors you find, as well as your suggestions for future editions, by writing:

O'Reilly & Associates, Inc.

103 Morris Street, Suite A

Sebastopol, CA 95472

1-800-998-9938 (in the US or Canada)

1-707-829-0515 (international/local)

1-707-829-0104 (FAX)

You can also send us messages electronically. To be put on the mailing list or request a catalog, send email to:

[e-mail]	(via the Internet)
uunet!ora!nuts	(via UUCP)

To ask technical questions or comment on the book, send email to:

[e-mail] (via the Internet)

Acknowledgments

This book would not exist if I had not received support and encouragement from my friends and colleagues, near and far. I owe the deepest debt of gratitude to my wife, Deborah, for patience, understanding, and support as I progressed through what is easily the most all-consuming task I have ever undertaken.

The earliest draft of this book came about because my advisor at the University of Massachusetts, Eliot Moss, allowed me to tinker with the TeX installation in the Object Systems Lab and was always able to suggest ways to make it better. My friends and colleages at UMass, Amer Diwan, Darko Stefanovi\'c, Dave Yates, Eric Brown, Erich Nahum, Jody Daniels, Joe McCarthy, Ken Magnani, Rick Hudson, and Tony Hosking, asked all the hard questions and didn't seem to mind when I used them as guinea pigs for my latest idea.

I'm indebted also to Eberhard Mattes, Geoffrey Tobin, George D. Greenwade, Peter Schmitt, Sebastian Rahtz, and Tomas Rokicki, who provided technical review comments on the materials presented here. Jim Breen and Ken Lunde offered invaluable feedback on Chapter 7.

And I'd like to thank a lot of people at O'Reilly for their help and enthusiasm; in particular, my editor, Debby Russell, offered advice, helpful criticism, and support beyond the call of duty (Debby keyed most of the index for this book as production deadlines drew near and other arrangements fell through); Chris Tong organized the raw entries into a usable index; Lenny Muellner, Donna Woonteiler, and Sheryl Avruch allowed me to work on the book when it wasn't technically my job; Stephen Spainhour copyedited it into English with the help of Leslie Chalmers and Kismet McDonough (Stephen offered helpful suggestions along the way, too); Jennifer Niederst helped me get the design right; and Chris Reilly created the figures and screen dumps. I enjoyed working with everyone at O'Reilly so much that I left UMass and joined the production department myself ;-).

Several companies provided review copies of their software while I was writing this book. I would like to thank ArborText, Blue Sky Research, Borland International, The Kinch Computer Company, LaserGo, Personal TeX, TCI Software Research, and Y&Y, for their generosity.

Finally, I'd like to thank the entire Internet TeX community. Countless thousands of questions and answers on the Net refined my understanding of how TeX works and what it can do.