[ATXA Guide to IATEX - Document Preparation for Beginners and Advanced Users | Third edition ; Helmut Kopka Patrick W. Daly A vv Addison-Wesley ; Harlow, England + Reading, Massac] a aveue coun, CAULOPMa New York - Don Mills, Ontario - Amsterdam - Bonn « Sydney + Singapore Tokyo + Madrid - San Juan + Milan + Mexico City + Seoul » Taipei© Addison Wesley Longman Limited 1999 Addison Wesley Longman Limited Edinburgh Gate Farlow Essex CM202)E England and Associated Companies throughout the World. ‘The rights of Helmut Kopka and Patrick W, Daly to be identified as authors of this Work have been asserted by them in accordance with the Copyright, Designs and Patents Act 1988, All rights reserved. No part of this publication may be reproduced, stored ina retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without either the prior written permission of the publisher or a licence permitting restricted copying in the United Kingdom issued by the Copyright Licensing Agency Ltd, 90 Tottenham Court Road, London WiP9HE, ‘The programs in this book have been included for their instructional value, ‘They have been tested with care but are not guaranteed for any particular purpose, The publisher does not offer any warranties or representations nor does it accept any liabilities with respect to the programs, Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Addison Wesley Longman Limited has made every attempt to supply trademark information about manufacturers and their products mentioned in this book. A list of the trademark designations and their owners appears on page v. Cover designed by Designers & Partners, Oxford ‘Typeset by the authors with the IsTsX Documentation System Printed in Great Britain by Henry Ling Ltd, at the Dorset Press, Dorchester, Dorset First published 1993 Second edition 1995 Third edition 1999 ISBN 0-201.39825-7 British Library Cataloguing in-Publication Da A catalogue record for this book is available from the British Library Library of Congress Catalogffig-in-Publication Data terized typesetting, I. Daly, 98-47054 cPTrademark notices METAFONT™ is a trademark of Addison-Wesley Publishing Company. TaX™, AgyS-TeX™, and AyyS-ISGX™ are trademarks of the American Mathematical Society. Lucida” is a trademark of Bigelow & Holmes. Microsoft®, MS-DOS®, Windows®, Internet Explorer® are registered trademarks of Microsoft Corporation. PostScript®, Acrobat Reader®, Acrobat logo® are registered trademarks and PDF™ a trademark of Adobe Systems Incorporated. UNIX® js a registered trademark in the United States and other countries, licensed exclusively through X/Open Company, Limited. VAX™ and VMS™ are trademarks of Digital Equipment Corporation. IBM® js a registered trademark and techexplorer Hypermedia Browser™ a trademark of International Business Machines Corporation. Netscape™ and Netscape Navigator™ are trademarks of Netscape Communications Corporation. TrueType™ is a trademark and Apple® and Macintosh® are registered trademarks of Apple Computer Inc.Preface Four years after the release of IATpX2¢ and almost as long since the appearance of the second edition of A Guide to FTX, the time is ripe to consider a third edition. How has ITgX changed in this interval? What has to be altered in the book? First of all, ISTIEX 2¢ is now well established as the official version of JsTgX; for this reason the title of this book reverts to the original form used for the first edition. (The second edition was titled A Guide to ATX 2¢ to emphasize that it covered the new IATfX.) Nevertheless, we continue to point out those features that are exclusive to ISTpX 2¢ and which were not available under version 2.09. ISTRX is upgraded every six months. The first few updates to AX 2e saw a number of important changes, but now it has become very stable, at least for standard features at the user level. Improvements and changes occur mostly at deeper levels, or in supporting packages. For example, the number of input encoding tables and graphics drivers has steadily increased. The 256-character DC fonts have now been replaced by their EC equivalents. However, the major change since 1994 is the prevalence of the Internet and World Wide Web; new programs are now available to enable IATsX documents to be ‘put online’. These do not reflect changes to Ja]jX itself but rather to the entire IAT;X environment and its applications. This is now dealt with in Section D.4. Anew edition provides an opportunity to reorganize much material, to change emphasis, and to correct mistakes. In this light, we have decided that the importation of graphics files is no longer an extension for ad- vanced users, but a basic part of ISIEX application. The usage has become standardized; many problems have been identified and solved. Thus a very detailed explanation of the graphics and color packages is now given in Chapter 6 and the emphasis on the IX picture environment has been reduced. The use of PostScript fonts has also become more relevant, to such an extent that Computer Modern fonts are no longer the hallmark of a ATX document. Appendix F (7gX Fonts) has been revised to reflect this. Several example packages in Appendix C (/AIEX programming) have been removed, in particular those dealing with language adaptation and author-year citations. These examples contained far too much TX code viiviii Preface to be appropriate as demonstrations, and their usefulness as packages is questionable considering the widespread availability of the babel and natbib packages. As compensation, a new package is offered for redefin- ing the sectioning commands. It has always been our intention only to describe the standard IAT;X features, and not to elaborate on many of the excellent contributed pack- ages available. This is not because we consider them to be inferior; on the contrary, a large number of them are indispensable and should be part of any standard installation. It is simply that we must limit the material in this book somehow, and these packages are dealt with elsewhere, for example in the 4X Companion (Goosens et al., 1994) and IATsX Graph- ics Companion (Goosens et al. 1997). We have decided to make two exceptions, Many of the ‘tools’ packages mentioned in Section D.3.3 are now described in the main text where their application would be most appropriate. Packages like mult icol, array, longtable should be used in everyday situations, and are by no means exotic. The amsmath and amsfonts packages are the other exception. An overview to these important mathematical tools is now provided in Ap- pendix E and tables of the extra AyyS symbol fonts are given on pages 552- 554. For mathematical typesetting, these additional commands must also be considered indispensable. We feel the changes will make this book even more relevant and appli- cable to the effective production of high-class documents with IATgx. Helmut Kopka and Patrick W. Daly September 1998 Preface to the second edition The great success of Helmut Kopka’s book /7gX, eine Einfiihrung in Ger- many has led to many requests for an English translation, especially from non-German-speaking visitors to our Institute. The standard manual on IsTgX by Leslie Lamport, 4TgX, A Documentation Preparation System, pro- vides a reasonable introduction to this text formatting program, but leaves many open questions about advanced topics and user-defined extensions. Kopka’s book includes many tips and practical examples for solving com- mon problems that are not to be found in the Lamport manual. A straightforward translation of the German book would not be par- ticularly useful, since it contains considerable information on the appli- cation to German texts. For this reason, Patrick W. Daly has undertaken to produce an English version of Kopka’s work, adding the sections on in- ternational and multilingual 47X, and including some applications from his own experience. At the time of the first edition, late 1992, I9TEX was undergoing majorix revisions. Some test versions of the new extensions were described in that book, but were in fact out of date before it appeared. Now the revised and consolidated new IATsX has been released, mid-1994, with many improvements and additions. This second edition of the Guide attempts to present both the classical version (designated 2.09) and the new official standard, named IATgX 2¢. Of course, the emphasis is on the newer version. The entire book has been revised in the light of SIpX2¢, although the basic material in Chapters 2-7 is much the same. The Advanced Features of Chapter 8 now include the New Font Selection Scheme, a list of standard packages, and the slides class (formerly SuTgX, which had an appendix to itself previously). The error messages of Chapter 9 have been extended. Appendix C is totally new, describing the advanced programming features of IKT:X, with useful examples. Finally, Appendix D, on Extensions, has been expanded; it also contains a description of the CTAN network, the electronic source for TgX and its accessories. As for the first edition, it is hoped that this book will be particularly useful to those readers who wish to go beyond the basic features of the ISTgX system but who do not want to venture into the murky depths of the ‘TeX world on which it is all based. The Command Summary and Summary Tables and Figures in Appendix G should become standard reference tools for any ISTX user of any degree of experience. Helmut Kopka and Patrick W. Daly March 1995Contents Preface 1 Introduction 1.1 Text formatting . 1.2 TfX and its offspring 1.3 What's different in WTpX2¢? . oF 1.4 How to use this book ......... 1.5 Basics of a TX file .........- 2 Commands and Environments 2.1 Command names and arguments 2.2 Environments a 2.3. Declarations . 2.4 Lengths... . - 2.5 Special characters . . 2.6 Fragile commands . . 2.7 Exercises . . . 3 Document Layout and oreanleen 3.1 Document class c . 3.2 Pagestyle ....... 3.3 Parts of the document 3.4 Table of contents 3.5 Fine-tuning text... . 3.6 Word division ..... 4 Displayed Text 7 ee 4.2 Centering and indenting . . . 43 Lists....... ee 4.4 Generalized lists . os 4.5 Theorem-like declarations . . 4.6 Tabulator stops 4.7 Boxes . ie 4.8 Tables.xii CONTENTS, 4.9 Printing literal text... 0... ee eee 108 4.10 Footnotes and marginal notes . fe 110, 4.11 Comments within text 11s 5 Mathematical Formulas 5.1 Mathematical environments . . 5.2 Main elements of math mode . 5.3 Mathematical symbols 5.4 Additional elements ..... 5.5 Fine-tuning mathematics . . 5.6 Beyond standard IX 6 Illustrations 151 6.1 Drawing pictures with TEX 151 6.2 The graphics packages .. . 166 6.3 Adding color . . 176 6.4 Floating tables and - 179 7 User Customization 189 7.1 Counters . 189 7.2. Lengths. ae 192 7.3. User-defined commands oo 193 7.4 User-defined environments . é 204 7.5 Some comments on user-defined structures 7 209 8 Advanced Features Processing parts of a document Including TEX commands in IATEX . . . Intext references ..........-- MakeIndex—a keyword processor . . The New Font Selection Scheme (NFSS) . Typing special symbols directly. . . . Alternatives for special symbols . . . 8.8 Additional standard files . . . 8.9 The various I4TjX files... ..- s fe fe co 8.10 Presentation material (SUTX) . 6... ee ee 9 Error Messages 257 9.1 Basic structure of error messages . . 257 9.2 Some sample errors ......- 266 9.3. List of ISIEX error messages 272 9.4. ‘TKX error messages 282 9.5 Warnings......... 288 9.6 Search for subtle errors . 294CONTENTS Appendices A Letters a AQ A3 The ISTgX letter class A house letter style A model letter customization . . . B Bibliographic Databases Bl B.2 B3 The BrTRX program ... 1... ee ect eee eee Creating a bibliographic database Bis TX extensions C LATEX Programming cl C2 C3 C4 C5 Class and package files . . ce ISX programming commands . . Sample packages . Changing edt text . Installing fonts with NFSS D LATEX Extensions D1 D2 D3 D4 DS D6 International KIX . ISTX and PostScript Further ITpX accessories . . . . JTgX and the World Wide Web . Installing ISX Sources for I4T;X files . E Math Extensions with AqyS-KT—X El E2 E3 E4 ES Obtaining the AyjfS packages . Invoking AgyS-X ae Standard features of AgyS-KKIEX . . Further AgyS-FXT;X packages The Ay fonts F TEX Fonts Pe F2 F3 B4 BS Font metrics and bitmaps . Computer Modern fonts . . An overview of METAFONT . Extended character sets for TgX 3. 0. PostScript fonts » 331 388 297 297 302 305 311 311 313 323 327 327 343 351 » 353 363 363 374 375 397 401 405 406 ». 406 . + 407 . 429 432 435, 435 .. 436 .. 445 .. 447 » 452xiv CONTENTS, G Command Summary 459 G.1 Brief description of the ATX commands . . . 459 G.2 Summary tables and figures .... . 548 G.3 Invalid Plain TX commands 558 Bibliography S61 Index 563 List of Tables 8.1 The NFSS encoding schemes ......-.....--+2005 234 8.2 The NFSS series attributes... 6... 06... eee eee ee 234 8.3 Attributes of the Computer Modern fonts . . = eae 8.4 Input coding schemes for inputenc package......... 238 8.5 Alternative commands for special symbols ........-- 239 D.1 The psnfss packages and theirfonts ............- 375 F.1 Computer Modern text fonts .........------ -- 439 F.2 Root names of the 35 standard PostScript fonts . . . 453 F3 Encoding suffixes... 6... ee eee eee eee 454 G.1 Font attribute commands 548 G.2 Math alphabet commands. . . 548 G.3 Font sizes . 548 G4 WTEX 2.09 font declarations . 548 G.S_ Dimensions . : 549 G6 Accents .... . 549 G.7 Special letters from other a : 549 G.8 Special symbols . . . . a 549 G.9 Command symbols . . 549 G.10 Greek letters... ... oo 549 G.11 Binary operation symbols . . . 550 G.12 Relational symbols ......- 550 G.13 Negated relational symbols . . 550 G.14 Brackets... . 26... 0000+ 550 le OW 551 G.16 Miscellaneous symbols o bea G.17 Mathematical symbols in two s sizes .. 551 G.18 Function names G.19 Math accents . . G.20 AgyS arrows . . G.21 yy binary operation symbolsG.22 AgyS Greek and Hebrew letters G.23 Agy$ delimiters... . . G.24 Ags relational symbols G.25 AgyS negated relational symbols : G.26 Miscellaneous AyyS symbols . LIST OF FIGURES List of Figures 3.1 3.2 41 DA D2 D.3 D4 Gl G.2 G3 Page layout parameters . Sample title page ..... The list parameters Example of TpX4ht and techexplorer output . Output produced by pafT;X with the hyperref package . « oe . 401 Sample display with the WinEdt editor . Partial directory tree of CTAN servers . . Single column page format .. . . Double column page format . . . Format of the list environment . xv 553 553 553 554 554 35 37 fe] 393 397 555 556 557Introduction Text formatting The electronic processing of text, one of the most common functions of computers today, consists essentially of four stages: 1. the text is entered into the computer for storage and later correc- tions, extensions, deletions; 2. the input text is formatted into lines of equal length and pages of a certain size; 3. the output text is displayed on the computer monitor screen; 4. the final output is sent to a printer. Many word processing systems handle all four functions together in one package so that the user is not aware of this division of labor. Furthermore, stages 3 and 4 are actually one and the same: sending the results of the formatting to an output device, which is in one case a monitor, in the other, a printer. A text formatting program, such as T,X, is only concerned with the second stage. Any text editor program may be used to enter and modify the input text. If you have an editor with which you are familiar and comfortable, then you may use it. A word processor program is not al- ways appropriate for this purpose because it normally adds many unseen control characters, It may very well be that ‘what you see is what you get” with a word processor, but what you see is not necessarily what you've got. The text that is produced with the editor as input for the formatting program must also contain special commands or instructions, but these are written with normal characters that are not hidden. To some extent, the instruction set for a formatter is much like a markup language, indi- cating where paragraphs, sections, chapters, etc. begin without explicitly1.2 1.2.1 Chapter J. Introduction formatting them in the text itself. How these instructions are to be inter- preted during formatting depends on the layout that is chosen. The same text may be formatted quite differently if another layout is selected. A formatter can be much more. In fact TX is also a powerful program- ming language that allows knowledgeable users to write code for all sorts of additional features. KTpX itself is just such a set of complex macros. Furthermore, anyone can program extra extensions to IXTEX, or make use of public ones that have been contributed by other programmers. The ca- pabilities of TX and IAjX are by no means limited to those of the original package. The last stage of text processing with a formatter is to send the results to an output device, either a printer or the computer monitor or a file. The programs that accomplish this are called drivers; they translate the encoded output of the formatter program into the specific instructions for the particular printers that the user has at hand. This means that for each type of printer, one has to have the corresponding driver program. . TeX and its offspring The most powerful formatting program for producing book quality text of scientific and technical works is that of Donald E. Knuth (Knuth, 1984, 1986a, 1986b, 1986c, 1986d). The program is called TgX, which is a rendering in capitals of the Greek letters Tex. For this reason the last letter is pronounced not as an x, but as the ch in Scottish loch or German ach, or as the Spanish j or Russian kh. The name is meant to emphasize that the printing of mathematical texts is an integral part of the program and not a cumbersome add-on. In addition to TX, the same author has developed a further program called METAFONT for the production of character fonts. The standard TeX program package contains 75 fonts in various design sizes, each of which is also available in up to eight magnification steps. All these fonts were produced with the program METAFONT. With additional applications, further character fonts have been created, such as for Cyrillic and even Japanese, with which texts in these alphabets can be printed in book quality. The TeX program The basic TX program only understands a set of very primitive com- mands that are adequate for the simplest of typesetting operations and programming functions. However, it does allow more complex, higher- Jevel commands to be defined in terms of the primitive ones. In this way, a more user-friendly environment can be constructed out of the low-level building blocks.1.2.2 1.2.3 1.2. TeX and its offspring 3 During a processing run, the program first reads in a so-called format file which contains the definitions of the higher-level commands in terms of the primitive ones, and which also contains the hyphenation patterns for word division. Only then does it read in the source file containing the actual text to be processed, including formatting commands that are predefined in the format file. Creating new formats is something that should be left to very knowl- edgeable programmers. The definitions are written to a source file which is then processed with a special version of the TX program called initex. It stores the new format file in a compact manner so that it can be read in quickly by the regular TX program. Although the normal user will almost never write such a format, he or she may be presented with a new format source file that will need to be installed with initex. For example, this is just what must be done to upgrade to the FT;X format every six months, as described in Section D.5.2. Plain Tex Knuth has provided a basic format named Plain 7jX to interact with TeX at its simplest level. This is such a fundamental part of word processing with ‘TEX that one tends to forget the distinction between the actual processing program 7X and this particular format. Most people who claim to ‘work only with ]X’ really mean that they only work with Plain TX. Plain }jX is also the basis of every other format, something that only reinforces the impression that T_X and Plain TpX are one and the same. UTEX The emphasis of Plain TX is still very much at the typesetter’s level, rather than the author's. Furthermore, the exploitation of all its poten- tial demands considerable experience with programming techniques. Its application thus remains the exclusive domain of typographic and pro- gramming professionals. For this reason, the American computer scientist Leslie Lamport has developed the IX format (Lamport, 1985), which provides a set of higher-level commands for the production of complex documents. With it, even the user with no knowledge of typesetting or programming is in a position to take extensive advantage of the possibilities offered by TEX, and to be able to produce a variety of text outputs in book quality within a few days, if not hours. This is especially true for the production of complex tables and mathematical formulas. 1s]KX is very much more a markup language than the original Plain T;X, on which it is based. It contains provisions for automatic running heads, sectioning, tables of contents, cross-referencing, equation numbering,1.2.4 1.2.5 Chapter 1. Introduction citations, floating tables and figures, without the author having to know just how these are to be formatted. The layout information is stored in additional class files which are referred to but not included in the input text. The layouts may be accepted as they are. Since its introduction in the mid-1980s, JATgX has been periodically updated and revised, like all software products. For many years the version number was fixed at 2.09 and the revisions were only identified by their dates. The last major update occurred on December 1, 1991, with some minor corrections up to March 25, 1992, at which point ITEX 2.09 became frozen. TEX 2 The enormous popularity of IsF;X and its expansion into fields for which it was not originally intended, together with improvements in computer technology, especially dealing with cheap but powerful laser printers, have created a diversity of formats bearing the IATX label. In an ef- fort to re-establish a genuine, improved standard, the IATEX3 Project was set up in 1989 by Leslie Lamport, Frank Mittelbach, Chris Rowley, and Rainer Schépf. Their goal is to construct an optimized and efficient set of basic commands complemented by various packages to add specific functionality as needed. As the name of the project implies, its aim is to achieve a version 3 for JATEX. However, since that is the long-term goal, a first step towards it has been the release of ISTEX 2¢ in mid-1994 together with the publication of the second edition of Lamport’s basic manual (Lamport, 1994) and of an additional book (Goosens et al., 1994) describing many of the extension packages available and I4TX programming in the new system. A more recent third book (Goosens et al., 1997) deals with the inclusion of graphics and color, two weak points in the early days. I4]pX 2¢ is now the standard version, pending the appearance of the promised T¢X3 at some future date. TeX on various computers ‘TX and LX were originally designed to run on central mainframe com- puters, in the days before there were such things as graphics monitors, mice, and joysticks. The underlying TX formatting program is meant to be called from a command line, not by mouse clicks from some graphics interface. Today this may be considered old-fashioned, but it has led to ‘TeX being one of the most stable and portable programs in the computer world, since it is not rigidly bound to any particular computer or operating system. Modern workstations and powerful personal computers, or PCs, are the standard tools for computing now, far exceeding the performance1.3. What's different in AT—EX2¢? Ly of those early giants. Many TgX installations are available that succeed in integrating file editing, processing, previewing, and printing in a near WYSIWYG (‘what-you-see-is-what-you-get’) manner. Some of these are listed in Section D.5.1 on page 397. One extremely useful output driver available with workstations and PCs is a screen previewer, which displays the output on the graphics monitor. Such a previewer was once a luxury but today is an indispensable tool for preparing IAT;X documents. Especially for complicated tables or mathematical formulas, the ability to check the results quickly after a trial change is essential. Fast, convenient previewers are vital in order to compete with WYSIWYG text processors. On a mainframe computer, there is an operator responsible for the installation and maintenance of the TsX program and its accessories. However, the user of a workstation or PC must take on the role of computer manager as well, meaning that he or she must learn something more about the setting up of both TX and 4X than was previously necessary. Or, as is more often the case, somebody must be found who will do this for them. This person is normally referred to as the local 7X guru. On the other hand, there are many excellent ready-to-run TX installa- tions for most computer types (Section D.5.1). Everything in this book about writing IATEX text files applies equally well to all computer types. It is this portability that makes I4TgX such a useful tool for scientific publishing. What's different in ATEX2 for IAT.X 2.09, or LaTex2e <1998/06/01> for ISTX 2e. Your dates may differ from these. Alternatively, try processing a ISTX file with \documentclass on the first line. If you receive the error message ! Undefined command sequence \documentclass then you do not have ISX 2e. Upgrades to IATEX Since IATgX 2¢ was first released on June 1, 1994, upgrades have been issued every June and December, consisting not only of improved internal coding, but also of additional features. This means that it is not sufficient to state that a document has been written for IS1X2¢, but rather one must specify the necessary version it requires as well as the date when it was written. In this book, any commands that were not present in the first official release are so indicated, along with their release date, both in the main text and in the command summary of Appendix G. Itis possible to declare in a document file the earliest possible version date needed to be able to process all the features it employs. This is done by placing an identification command near the beginning (Section C.2.1). For the first release, this would be \NeedsTeXFormat{LaTeX2e}[1994/06/01] The date must be numerical, in exactly the format shown above, as year/month/day, including slashes and zeros. If a file with this com- mand is processed by an earlier version of ISI;X, a warning message is printed. How to use this book This Guide is meant to be a mixture of textbook and reference manual. It explains all the basic elements of ISX, especially those of the current standard IsI,X 2¢, restricting itself as much as possible to what is in the standard distribution. Compared to Lamport (1985, 1994), it goes into more detail at times, offers more examples and exercises, and describes many ‘tricks’ based on the authors’ experiences. Unlike The [ATX Com- panion (Goosens et al., 1994), it does not describe the many additional1.4.1 Chapter 1. Introduction packages available outside the standard distribution, since these may not always be easily obtainable for all readers. Exceptions are the tools collection of packages, graphics inclusion, use of color, and AyyS-AKX. This book is designed for XTgX users who have little or no experience with computers. It contains no information about computers or system- dependent activities such as logging on, calling the editor, or using the editor. There is considerable repetition in the text, especially within the first half, so that the reader, having learned a brief definition of some expres- sion, is not expected to have fully mastered it when it reappears a few pages later. Nevertheless, the user should become familiar right from the beginning with the basic elements described in Sections 2.1-2.4. In the description of command syntax, typewriter type is used to indicate those parts that must be entered exactly as given, while italic is reserved for those parts that are variable or for the text itself. For example, the command to produce tables is presented as follows: \begin{tabular}{col_form} lines \end{tabular} The parts in typewriter type are obligatory, while col.form stands for the definition of the column format that must be inserted here. The allowed values and their combinations are given in the detailed descriptions of the commands. In the above example, lines stands for the line entries in the table and are thus part of the text itself. Sections of text that are printed in a smaller typeface together with the boxed exclamation mark at the left are meant as an extension to the basic description. They may be skipped over on a first reading. This information presents deeper insight into the workings of I4T;X than is necessary for everyday usage, but which is invaluable for creating more refined control over the output. Distinguishing TEX2¢ from version 2.09 Since IAI:X 2¢ is now the current standard, all the descriptions of syntax and functions given here will conform to it, However, we are aware that some users are still working with version 2.09, either because they lack the possibility of upgrading, or because they do not have the inclination to change. This book must also serve these clients. For this reason, those commands that are specific to, or have been extended under, &I;X 2¢ are marked with the symbol (26 sections of text that apply strictly to BTEX 2.09 are marked with = Since IXI5X 2¢ is downward compatible with f1gX 2.09, it should not be necessary to mark any command as belonging only to the older version. Nevertheless, some commands have been retained strictly for compatibi ity reasons (such as \bf and \rm) and are discouraged in KXIEX 2¢, while in XX 2.09 they are indispensable. Similarly, any [2.09] 9]5 15.1 1.5.2 1.5. Basics of a TEX file Ww Basics of a lATgX file Text and commands A ISIKX file contains the input text that is to be processed to produce the printed output. Splitting the text up into lines of equal width, formatting it into paragraphs, and breaking it into pages with page numbers and running heads are all functions of the processing program and not of the input text itself. For example, words in the input text are strings of letters terminated by some non-letter, such as punctuation, blanks, or carriage returns; whereas punctuation marks will be transferred to the output, blanks and carriage returns merely indicate a gap between words. Multiple blanks in the input, or blanks at the beginning of a line, have no effect on the interword spacing in the output. Similarly, a new paragraph is indicated in the input text by an empty line; multiple empty lines have the same effect as a single one. In the output, the paragraph may be formatted either by indentation of the first line, or by extra interline spacing, but this is not affected in any way by the number of blank lines or extra spaces in the input. The input file contains more than just text, however; it is also in- terspersed with commands that control the formatting. If is therefore necessary for the author to be able to recognize what is text and what is acommand. Commands consist either of certain single characters that cannot be used as text characters, or of words preceded immediately by a special character, the backslash \. Structure of a TEX document In every IS1jX file there must be a preamble and a body. The preamble is a collection of commands that specify the global processing parameters for the following text, such as the paper format, the height and width of the text, the form of the output page with its pagination and automatic page heads and footlines. As a minimum, the preamble must contain the command \documentclass to specify the document's overall processing type. This is normally the first command in the preamble. If there are no other commands in the preamble, IsT5X selects standard values for the line width, margins, paragraph spacing, page height and width, and much more. In the original version, these specifications are tai- lored to the American norms. For European applications, built-in options exist to alter the text height and width to the A4 standard. Furthermore, there are language-specific packages to translate certain headings such as ‘Chapter’ and ‘Abstract’.1.5.3 Chapter 1. Introduction The preamble ends with \begin{document}. Everything that follows this command is interpreted as body. It consists of the actual text mixed with additional commands. In centrast to those in the preamble, these commands have only a local effect, meaning they apply only to a part of the text, such as indentation, equations, temporary change of font, and so on. The body ends with the command \end{document}. This is normally the end of the file as well. The general syntax of a IIx file is as follows: 2] \documentclass [options] {class} Further global commands and specifications \begin{document} Text mixed with additional commands of local effect \end{document} The possible options and classes that may appear in the \documentclass command are presented in Section 3.1.1. For I4]5X 2.09, or for compatibility with it under XIEX 2¢, the initial command \documentclass must be replaced by \documentstyle. Thus the general syntax would appear as follows in version 2.09: 2.09 \documentsty1e[options] {class} \begin{document} \end{document} At a computing center, information about the available ISTX classes and packages is described in a so-called Local Guide. This should also include how the ISTX program is to be run, as well as what output devices are installed, such as printer, microfilm, plotters, etc., and how they are to be implemented. The device drivers may also recognize options to produce the output in various discrete magnifications. KTEX processing modes (This section is marked with a boxed exclamation mark and is printed in a smaller typeface, For the meaning of this, see the end of Section 1.4 on page 10.) During processing, IsTjX is always in one of three modes: 1. paragraph mode, 2. math mode, 3. LR, or left-to-right mode. The paragraph mode is the normal processing mode in which ISX treats the input text as a sequence of words and sentences to be broken up (automatically) into lines, paragraphs, and pages.1.5.4 1.5. Basics of a UTGX file 13 IST,X switches to math mode when it encounters certain commands that tell it that the following text represents a formula. In math mode, blanks are ignored. The two texts is and is are both interpreted as the product of i and s and appear as is. [XIX switches back to paragraph mode when it encounters the corresponding command that the formula is completed. LR mode is similar to paragraph mode: KI;X treats the text input from left to right as a string of words that cannot be split up by a line break. \¥5X will be in this mode when, for example, normal text is to appear embedded within a formula, or with a special command \mbox{short text} that forces short text to be printed on one line. Understanding and recognizing the processing modes is important since some commands are allowed only in certain modes or their effects are different depending on the mode. In the following we will refer to paragraph and LR modes as text mode to the extent that their properties are identical. This is to distinguish them from math mode, which is normally quite different. Producing a TeX document ‘The creation of a KIX document from text input to printer output is a three-stage process. First a text file is created (or corrected) using the computer editor. This text file consists of the actual text mixed with ATX commands. The full name of the text file consists of a root name plus the extension .tex (for example, sample. tex). The operating system of the computer usually puts additional limitations on the choice of file name, such as the maximum number of characters in the name and extension, or the exclusion of special characters. For example, if the root name is limited to eight characters, finances .tex is an allowed name, but financial .tex is not. The text file is then processed by I4TgX. As explained in Section 1.2.1, this means running the TxX program with the IST5X format. Most instal- lations have a special shorthand command, called latex, to accomplish this, followed by the name of the text file, with or without the extension -tex. For example, if the name of the text file is sample. tex, one would start the IST;X processing with the call latex sample During the processing, the terminal monitor displays the page numbers together with possible warnings and error messages. Chapter 9 deals with the interpretation of these error messages and their consequences. After SI¢X has finished processing, it creates a new file with the selected root name and the extension .dvi. In the above example, this would be sample.dvi.Chapter 1. Introduction This .dvi (device-independent) file contains the formatted text along with information about the required character fonts, but in a form that is independent of the characteristics of the printer to be used. Such a device-independent file is called a metafile. Finally the information in the .dvi metafile has to be converted to a form that can be output on the chosen printer by means of a so-called printer driver that is specific for that printer type. The call to the driver contains only the root name of the file, just like the IATpX call, that is, without the ending .dvi. After processing with the printer driver, another file is created with the selected root name and an extension specifying the printer type. For example, if the output is to go to a LaserJet printer, the driver might be called as dvilj sample which either produces a file sample.1j or sends the output directly to the printer. Other drivers exist for letter-quality dot-matrix printers as well as for PostScript. However, it is not the purpose of this book to describe the DVI drivers, since there are a great many available, with different names and extra features, such as printing only certain pages or printing them in reverse order. A computing center will have the important drivers installed for the output devices available. A summary of these calls and further information should be available in a TX or I4TEX Local Guide that is accessible to all system users. The best source of information, however, is often other experienced users, the gurus mentioned previously.Commands and Environments 21 The text that is to be the input to a JAIEX processing run must be prepared with a text editor (any one will do) in a file with the extension .tex. The contents of this file are printable characters only—there are no invisible characters or commands hiding behind the screen. However, commands are still necessary to issue instructions to IXTEX. These commands are visible in the input text but will not appear in their literal form in the output. It is therefore vital to know how commands are distinguished from text that is to be printed, and, of course, how they function. Command names and arguments A command is an instruction to XIX to do something special, like print some symbol or text not available to the restricted character set used in the input file, or to change the current typeface or other formatting properties. There are three types of command names: the single characters # $ & ~ _ * % { }allhave special meanings that are explained later in this chapter; the backslash character \ plus a single non-letter character; for example \§ to print the § sign; all the special characters listed above have a corresponding two-character command to print them literally; the backslash character \ plus a sequence of letters, ending with the first non-letter; for example, \large to switch to a larger typeface. Many commands operate on some short piece of text, which then appears as an argument in curly braces following the command name. For example, \emph{stress} is given to print the word stress in an emphasized typeface (here italic) as stress. Such arguments are said to be mandatory because they must always be given. 1516 Chapter 2. Commands and Environments Other commands take optional arguments, which are normally em- ployed to modify the effects of the command somehow. The optional commands appear in square braces. In this book we present the general syntax of commands as \commandname[ optional.argument] { mandatory_argument} where typewriter characters must be typed exactly as illustrated and italic text indicates something that must be substituted for. Optional arguments are put into square brackets [ ] and the mandatory ones into curly braces { }. A command may have several optional arguments, each one in its set of brackets in the specified sequence. If none of the optional arguments is used, the square brackets may be omitted. Any number of blanks may appear between the command name and the arguments. Some commands have several mandatory arguments. Each one must be put into a { } pair and their sequence must be maintained as given in the command description. For example, \rule [lift] {width} {height} produces a black rectangle of size width and height, raised by an amount lift above the current baseline. A rectangle of width 10 mm and height 3 mm sitting on the baseline is made with \rule{10mm}{3mm}. The optional argument lift is not given here. The arguments must appear in the order specified by the syntax and may not be interchanged. Some commands have a so-called *-form in addition to their normal appearance. A * is added to their name to modify their functionality slightly. For example, the \section command has a *-form \section* which, unlike the regular form, does not print an automatic section num- ber. For each such command, the difference between the normal and *-form will be explained in the description of the individual commands. Command names end before the first character that is not a letter. If there are optional or mandatory arguments following the command name, then it ends before the [ or { bracket, since these characters are not letters. Many commands, however, possess no arguments and are composed of only a name, such as the command \LaTeX which produces the ISIgX logo. If such a command is followed by a punctuation mark, such as comma or period, it is obvious where the command ends. If it is followed by a normal word, the blank between the command name and the next word is interpreted as the command terminator: The \LaTeX logo results in ‘The IsTpXlogo’, that is, the blank was seen only as the end of the command and not as spacing between two words. This is a result of the special rules for blanks, described in Section 2.5.1. In order to insert a space after a command that consists only of aname, either an empty structure {} or a space command (\ and blank) must be placed after the command. The proper way to produce ‘The I4}X logo’ is to type either The \LaTeX{} logo or The \LaTeX\ logo. Alternatively,2.2 2.2. Environments 17 the command itself may be put into curly braces, as The {\TeX} logo, which also produces the correct output with the inserted blank: ‘The Tex logo’. Incidentally, the IAT:X 2¢ logo is produced with \LaTeXe. Can the reader see why this logo command cannot be named \LaTeX2e? Environments An environment is initiated with the command \begin{ environment} and is terminated by \end{environment}. An environment has the effect that the text within it is treated dif- ferently according to the environment parameters. It is possible to alter (temporarily) certain processing features, such as indentation, line width, typeface, and much more. The changes apply only within the environ- ment. For example, with the quote environment, previous text \begin{quote} text] \smal1 text2 \bfseries text3 \end{quote} following text the left and right margins are increased relative to those of the previous and following texts. In the example, this applies to the three texts text], text2, and text3. After text] comes the command \sma11, which has the effect of setting the next text in a smaller typeface. After text2, there is an additional command \bfseries to switch to bold face type. Both these commands only remain effective up to the \end{quote}. The three texts within the quote environment are indented on both sides relative to the previous and following texts. The text] appears in the normal typeface, the same one as outside the environment. The text2 and text3 appear in a smaller typeface, and text3 furthermore appears in bold face. After the end of the quote environment, the subsequent text appears in the same typeface that was in effect beforehand. Most command names may also be used as environment names. In this case the command name is used without the preceding \. For example, the command \em switches to an emphatic typeface, usually italic, and the corresponding environment \begin{em} will set all the text in italic until \end {em} is reached. An environment without a name can be simulated by bracketing with a{...} pair, The effect of any command within it ends with the closing curly brace. The user can even create his or her own environments, as described in Section 7.4.