Features

This book is packed with information needed to use LaTeX more productively. It has been designed to enhance, not to replace, basic documentation.

LaTeX is an accessible and effective tool for typesetting written documents. Users at all levels of experience, however, sometimes require help not readily available: techniques for defining new commands, styles for producing tables or graphics, explanations for changing fonts. This book, The LaTeX Companion, is packed with information needed to use LaTeX even more productively. It is a true companion to Leslie Lamport's original user's guide book, LaTeX: A Document Preparation System, now in its second edition, and indeed, it is a valuable complement to any LaTeX introduction. It is designed to enhance, not to replace, your basic documentation.

Coinciding with the publication of The LaTeX Companion is the availability of a revised LaTeX standard LaTeX2e. This new release incorporates important LaTeX developments over the past several years and provides a common basis for all LaTeX enhancements. Some new styles, improved font handling, and a facility to produce PostScript graphics are included in the release. As part of the broad and unique coverage of this book you will find a complete documentation for all these added features. Highlights

• Covers all versions of LaTeX now in use, including LaTeX2e.
• Describes over 150 convenient styles for floats, graphics, tables, and much more.
• Shows how to define new commands and environments.
• Explains the use of PostScript.
• Covers the latest extensions and programs producing pictures, indexes, bibliographies, and advanced mathematics.
• Includes techniques for multi-language support.
• Describes the New Font Selection Scheme.

All three authors have for years been involved in the support and development of LaTeX applications. Michel Goossens and Alexander Samarin, developed ideas for The LaTeX Companion while supporting hundreds of LaTeX users at CERN, and Frank Mittelbach, at the University of Mainz and Electronic Data Systems. The questions most frequently posed to them became the questions answered in this book. Mittelbach is partly responsible for the current maintenance of LaTeX and is the author or coauthor of many widespread LaTeX extension packages, such as AMS-LaTeX, doc, multicol, and the New Font Selection Scheme. He is also the manager, principal architect of the longer-term LaTeX3 project, to which half the royalties from this book are paid.
0201541998B04062001

Sample Chapter(s)

Click below for Sample Chapter related to this title:
chap8new.pdf

Preface

LaTeX is a generic typesetting system that uses TeX as its formatting engine. This companion is a detailed guide through the visible and not-so-visible beauties of LaTeX. As such, it is a comprehensive treatise of those points not fully discussed in Leslie Lamport's LaTeX: A Document Preparation System (henceforth referred to as the LaTeX book) 49. Extensions to basic LaTeX, as described in that book, are discussed, so that the LaTeX book, together with this companion, provide a ready reference to the full functionality of the LaTeX system.

Due to its flexibility, ease of use, and professional typographic quality, LaTeX is presently used in almost all areas of science and the humanities. Unlike many word processors, LaTeX (and its underlying formatting engine TeX) comes free of charge and is not linked to any particular computer architecture or operating system. Since LaTeX source files are plain text files, it is possible to ship them, and the packages referenced, from any computer to any other computer in the world (over electronic networks or via normal mail). The recipient will be able to obtain a final output copy identical to the one generated at the sender's site, independently of the hardware used. Thus members of groups, geographically spread over several sites in different countries, or even on different continents, can now work together in composing complex documents where different parts can be dealt with by different individuals, and then brought together without problems. Moreover, the use of electronic manuscripts has the potential to speed up the publication of papers by publishers.

LaTeX is not difficult to learn and a beginner can benefit from the system after reading through the first few chapters of LamportLeslie Lamport's LaTeX book, the basic reference on LaTeX. After some experience, you will probably have to solve some more advanced problems whose solution cannot be found directly in that book. If you are one of those users who would like to know how LaTeX can be extended to create the nicest documents possible without becoming a (La)TeX guru , then this book is for you.

You will be guided, step by step, through the various important areas of LaTeX and be shown the links that exist between them. The structure of a LaTeX document, the basic formatting tools, and the layout of the page are all dealt with in great detail. A sufficient library of packages in the area of floats, graphics, tables, PostScript, and multi-language support are presented in a convenient way. This book is the first volume to include all of the important LaTeX tools, such as: up-to-date descriptions of version 2 of the New Font Selection Scheme (NFSS2), the AMSLaTeX mathematics extensions, the epic and eepic extensions to LaTeX's picture environment, and the MakeIndex and BibTeX programs for producing and controlling the generation of indices and bibliographic references. Finally, an overview of ways to define new commands and environments, lengths, boxes, general lists, etc., as well as ways of facilitating the handling of these objects, complete the picture.

All three of us have been involved for several years in the support and development of LaTeX applications in various professional environments and countries. We have taught the secrets of LaTeX to many different audiences, and have been listening to the user community by following the discussions in the text processing related news groups and at TeX conferences. This has allowed us to gather a coherent view of a vast collection of subjects, which, we think, you might need one day if you want to fully exploit the richness and strengths of the LaTeX system. Note, however, that this book is not a replacement for, but a companion to, the LaTeX book. You are assumed to have read the first part of that book, and in any case, it should be considered a reference for precise and full description of the LaTeX commands.

To make the presented information even more complete and useful, our readers are kindly invited to send their comments, suggestions, or remarks to any one of the authors. We shall be glad to correct any remaining mistakes or oversights in a future edition, and are open to suggestions for improvements or the inclusion of important developments that we may have overlooked.

LaTeX2e--The New LaTeX Release

Over the years many extensions have been developed for LaTeX with one unfortunate result: incompatible LaTeX formats came into use at different sites. Thus, to process documents from various places, a site maintainer was forced to keep LaTeX (with and without NFSS), SliTeX, AMSLaTeX, and so on. In addition, when looking at a source file it was not always clear what format the document was written for.

To put an end to this unsatisfactory situation a new LaTeX release was announced for fall 1993 that brings all such extensions back under a single format and thus prevents the proliferation of mutually incompatible dialects of LaTeX 2.09. With LaTeX2e the new font selection will be standard and style files like amstex (formerly AMSLaTeX format) or slides (formerly SliTeX format) will become extension packages, all working with the same base format. The introduction of a new release also made it possible to add a small number of often-requested features (like an extended version of #79#>newcommand). All the new possibilities are described in this book, thus allowing you to make full use of the new LaTeX release.

To make it easy to distinguish between old LaTeX 2.09 sources and new sources (making use of new features), the first command in a LaTeX document was changed from \documentstyle to \documentclass, thus enabling the software to automatically detect an old source file and switch to compatibility mode if necessary.

The LaTeX3 Project

LaTeX is presently being rewritten under the coordination of one of the authors (Frank Mittelbach), Chris Rowley and Rainer Schöpf. This endeavor is called the LaTeX3 Project 57. A lot of the functionality described in this book as extensions to basic LaTeX will be available in that system: as part of the kernel, or in one of the extension packages. To help funding, half of the royalties from this book will go directly to the LaTeX3 Project. Therefore, when buying this book, you not only obtain a handy, complete, and up-to-date reference to many important and useful packages available with LaTeX today, but you also actively contribute to making LaTeX more powerful and user-friendly in the future.

How to Read This Book

The titles of the various chapters should convey relatively clearly the subject area addressed in each case. In principle, all chapters can be read more or less independently and, if necessary, pointers are given to where complementary information can be found in other parts of the book.

Chapter 1

gives a short introduction to the LaTeX system.

Chapter 2

discusses generic and document-oriented markup.

Chapter 3

describes LaTeX's basic typesetting commands.

Chapter 4

explains which tools are available to globally define the visual layout of the pages of a document by using pagestyles.

Chapter 5

shows how to assemble material into columns and rows with the extended tabular and array environments, and their multipage equivalents--supertabular and longtable.

Chapter 6

provides a general treatment of floating material.

Chapter 7

discusses in detail LaTeX's New Font Selection Scheme (NFSS2) and presents its various user commands. It is shown how to add new fonts, both in math and text mode.

Chapter 8

reviews the amstex package, which adds many powerful typesetting commands in the field of mathematics.

Chapter 9

looks at the problem of using LaTeX in the multi-language or non-English environment. The babel system and other language-specific packages are described.

Chapter 10

addresses the field of device-independent graphics showing how the epic, eepic and other packages extend the possibilities of LaTeX's basic picture environment.

Chapter 11

shows how the PostScript page description language not only can turn LaTeX into a full-blown graphics utility, but also how it makes it possible, via the NFSS, for a user to choose a font from amongst hundreds of font families, available as PostScript Type 1 outlines.

Chapter 12

tackles the problems associated with preparing an index. The program MakeIndex is described in detail.

Chapter 13

surveys how LaTeX's companion program BibTeX tries to solve problems related to maintaining bibliographic data bases. Various existing bibliographic styles are discussed and the format of the BibTeX language used in the style files is presented in detail, allowing the user to customize an existing style.

Chapter 14

shows how to document LaTeX files using the doc package and its companion program docstrip.

Appendix 1

first reviews how to handle and manipulate the basic LaTeX programming structures. The extensions introduced by the calc package in the field of arithmetic operations, and extended control structures added to LaTeX2e are discussed.

Appendix 2

explains how to get the files described in this book from the various TeX archives or from the TeX Users Groups.

In order to make the examples as independent as possible from basic TeX, extensive use has been made of the packages calc and ifthen, which are described in the appendices A.4 and A.5. You should study the extensions to LaTeX, introduced in these packages, if you want to understand how many of the examples in this book function in detail.

Many examples make use of new features in LaTeX2e; especially font changes for text are all done in LaTeX2e style, i.e.,with the commands shown in table 7.2 on page 171. Abbreviated forms, like {\bf word} are normally not used, since they are style defined commands and may or may not be available for all classes of documents.

While it is certainly possible to make good use of most parts of this book within a LaTeX 2.09 environment (the event of LaTeX2e happened after 90% of the book was finished) we suggest that you upgrade to the new version as soon as possible so that the worldwide community of LaTeX users again speaks a single language. As said above, LaTeX2e is able to identify and process old documents written for LaTeX 2.09. However, packages written or updated for LaTeX2e will not run with the old system.

Typographic Conventions

As explained in the discussion about the links between content and form or generic and layout markup, it is essential that the presentation of the material conveys immediately its function in the framework of the text. Therefore, we present below the typographic conventions used in this book.

LaTeX command and environment names are in monospaced type (for example, #133#>caption, enumerate, \begin{tabular}), while names of package and class files are in sans-serif type (eg. article).

The syntax of LaTeX constructs is presented inside a rectangular box. Command arguments are shown in italic type.

Lines containing examples with LaTeX commands are indented and are typeset in a monospaced type at a size somewhat smaller than that of the main text.

\chapter{Title of the Chapter} \section{Section Title} Some text...

When it is important to show the result of a series of commands, then the input and output are shown side by side as follows:

For large examples, where the input and output cannot be shown conveniently alongside one another, the following layout is used:

Commands to be typed by the user on a computer terminal are shown in monospaced type and are underlined, e.g.,: This is user input.

Using All Those Packages

In this book we describe over 150 packages and options that extend or modify LaTeX's basic possibilities. In order to show their action, we (in principle) have to load them all at the same time. For various reasons that is impractical, if not impossible. Indeed many packages, like program, use up a lot of counters, and TeX only allows a total of 256 counters. Therefore, when you hit this limit you must reduce the number of files you load simultaneously. In the production of this book we used a different strategy: we prepared some of the examples as separate files and included them as Encapsulated PostScript. Moreover, we used the package hackalloc. It redefines the allocation primitive so that all allocation becomes group-local. This means that by loading packages only when they are needed inside a brace group, the counter and length variables will be deallocated when you exit from the group. This procedure, however, can have some side effects, and should only be used with great care. However, we used most of the packages together, with the result that we had to recompile TeX several times during the preparation of this book. One of the log files produced during the last steps of the preparation showed the following summary:

Here is how much of TeX's memory you used:  9692 strings out of 16716  118315 string characters out of 133654  236569 words of memory out of 262141  8131 multiletter control sequences out of 9500  81058 words of font info for 228 fonts, out of 90000 for 255  20 hyphenation exceptions out of 607  34i,23n,41p,509b,1403s stack positions out of 300i,40n,60p,3000b,4000s Output written on companion.dvi (555 pages, 2008780 bytes).

Even when you do not reach a limit of the kind mentioned above, there are other interference effects between different packages. For instance, some extensions such as french make some characters active (i.e.,some characters act as though they were control sequences) . Problems may result when such a character is then encountered in another package. This means that not all of the packages described in this book can be used together. Sometimes you can solve the problem by loading problematic packages as one of the last #161#>usepackage declarations. Also, some packages make the @ character active (eg.amstex), and this can have nasty consequences if you load other packages that use the @ character.

As a rule of thumb, if you observe some odd behavior when you add a package to an existing list of packages, which seemed to work nicely together before, there might be a compatibility problem. Try loading the new file at the end, and if that does not work, take out each of the other files one by one. In this way you might find the file or files that are responsible for the problem.

Introduction

  LaTeX is not just a system for typesetting mathematics. Its applications span the one-page memorandums, business or personal letters, newsletters, articles about exact sciences and developments in the humanities, and full-scale book and reference works on all topics. Nowadays, versions of LaTeX exist for practically every large mainframe, workstation, or personal computer. To better understand why this happened, the first section of this chapter looks back at the origins of TeX and LaTeX, and then asks where to go next. The second section gives an overview of the LaTeX system as a whole. This orientation should help the reader to clearly understand the rôle of the various components and files created by LaTeX. The important difference between generic and visual markup is the subject of the next sections. The advantages of the generic approach are explained in the context of the separation of the content and form of a document, and it is emphasized that documents should be built on the generic principle as much as possible. When, for the sake of clarity, it proves necessary to use visual markup, the latter should be classified into categories whose definitions are grouped at the beginning of the document and then used locally. This practice guarantees consistency and ease of use.

A Short History of TeX and LaTeX

In the Beginning There Was TeX

In May 1977, Donald Knuth of Stanford University [38] started work on a text-processing system which is now known as TeX and metafont [39, 40, 41, 42, 43]. In the foreword of the TeX book [39] Knuth writes: ''TeX is a new typesetting system intended for the creation of beautiful books--and especially for books that contain a lot of mathematics. By preparing a manuscript in TeX format, you will be telling a computer exactly how the manuscript is to be transformed into pages whose typographic quality is comparable to that of the world's finest printers.''

TeX has become popular with thousands of scientists because it can be used for transforming any kind of writing into articles, reports, proposals, books, poetry, and other formats in a way that can be specified completely by the writer through a rich language of commands. The companion program metafont allows the design of typefaces to be used to print the output pages.

TeX is particularly useful when the document contains mathematical formulae or when book-like quality appearance is desired. Moreover, it is a portable system, running on a wide range of computer platforms, from micros to mainframes, and its behavior is identical on all machines, a fact extremely important in the scientific and technical community. Related to this portability is TeX's printing device independence, so that a document can be printed on anything from a CRT screen, a medium-resolution dot matrix or laser printer, to a professional high-resolution phototypesetter.

Because of these qualities, and since it is available free of charge, TeX has become the de facto standard text-processing system in many academic departments and research laboratories, whilst it also gains momentum in the professional publishing world as a printing engine. It is available on every conceivable computer platform, from IBM PC-like personal computers and Macintoshes, via Unix and VMS workstations, to supercomputers like the Cray. In addition, excellent previewers are available that run on most workstations and other graphic displays.

In his foreword to TeX and metafont, New Directions in Typesetting [37] Gordon Bell wrote over ten years ago that ''Don Knuth's Tau Epsilon Chi (TeX) is potentially the most significant invention in typesetting in this century. It introduces a standard language in computer typography and in terms of importance could rank near the introduction of the Gutenberg press.''

Recently, Donald Knuth officially announced that TeX would not undergo any further development [47] in the interest of stability.

Then Leslie Lamport Developed LaTeX

At the beginning of the 1980s, Leslie Lamport started work on a document preparation system called LaTeX, based on the TeX formatter. The system adds a level of abstraction to the plain TeX commands and lets the user concentrate on the structure of a document rather than on formatting details. A few high-level commands allow the user to easily compose most documents. You do not have to worry about typography. Such details are left to the document designer who has the task of providing style files for every application.

LaTeX's functionality, in conjunction with a few auxiliary programs, includes the generation of indices, bibliographies, cross-references, and tables of contents, and the inclusion of figures--features that are lacking in basic TeX.

With LaTeX toward the Year 2000?

Since the number of TeX and especially LaTeX users has grown to many thousands in the last few years, LaTeX has spread into areas for which it is not necessarily optimized (law texts, critical editions of classic authors, poetry, side-by-side multi-language editions, newsletters, to name a few). Recent issues of TUGboat, the journal of the TeX Users Group, have carried a number of articles about the shortcomings of TeX, LaTeX and their associated programs [59, 55, 88, 61, 91].

After a meeting with Leslie Lamport at the 1989 TeX Users Group meeting in Stanford, Frank Mittelbach, Chris Rowley, and Rainer Schöpf started work on a reimplementation and extension of LaTeX, the so-called LaTeX3 Project [57]. The main idea is to build an optimized and efficient kernel with basic commands complemented by various packages that will handle functionality in specific areas (like tables, pictures, and mathematics). The new system will provide a complete reimplementation of the style file user interface, making it easier to develop and maintain one's own styles.

In March 1992 at the German DANTE TeX Users meeting in Hamburg a discussion group, NTS, for ''The New Typesetting System,'' was set up to discuss and coordinate areas where TeX should be extended to provide the functionality needed for creating ''masterpieces of the Publishing Art'' [81].

LaTeX and Its Components

How Does LaTeX Work?

LaTeX reads and writes several files and you should have a clear understanding of their function. Figure 3.1 shows schematically the flow of information in a LaTeX run and presents a list of the various files needed.

The most important file in any LaTeX run is the input source file. It is a plain text file, usually prepared with a text editor, and in general has the extension tex. Files containing structure and layout definitions (extensions cls, sty) are usually stored in some standard directories. LaTeX is distributed with five standard document classes , namely, article, report, book, slides, and letter. These basic document classes can be further customized by specifying one or more class options   or using additional packages  like those described in this book. The dimensions of the characters for fonts used by TeX are called font metrics  and are encoded in tfm files (for TeX font metrics). For each font used in a document there must be a tfm file describing height, depth, and width as well as kerning information for every character. TeX only uses these character boxes in its line-breaking algorithm when composing paragraphs. TeX hyphenates  words automatically using a language-independent trie-algorithm [53]. For each language, a different set of word-breaking hyphenation patterns can be specified when a format (extension fmt) file is generated. The LaTeX format (usually called lplain.fmt or latex.fmt) mainly contains a precompiled image of all LaTeX commands, and the tfm information for the several preloaded fonts. The correspondence between internal font names and external font files is stored in font-definition files (extension fd).

The output from LaTeX is a set of files. One of them (extension dvi) contains a representation of the formatted text where the type and position on the page are specified for each character to be output. These dvi files specify only font names--they do not contain the actual character images. TeX positions its (character) boxes with a resolution better than a thousandth of an inch, so that the output file generated by TeX can be effectively considered device independent, hence the name dvi. To visualize the result the dvi file must be transformed   by a ''DVI driver'' into the desired output format (eg.PostScript).

For every run, LaTeX generates a transcript file that usually has the extension log or lis but may have others (or even none at all), depending on the operating system. This file contains information, most of which also appears on the screen, such as the names of the files read,  the numbers of the pages processed, warning and error messages, and other pertinent data.

Other  LaTeX output files contain information about cross-referencing (extension aux), table of contents (extension toc), list of figures (extension lof), and list of tables (extension lot). They are used in a subsequent LaTeX run to produce particular elements of the document.

    A file with extension idx contains all indexed items. They can be sorted by a program like MakeIndex, which was written by Pehong Chen and Michael Harrison.   MakeIndex reads the idx file that contains the index entries and the corresponding page numbers, sorts these items, unifies them, and writes them as LaTeX input into a file (extension ind). Index style information can be specified in an ist file. Messages created by MakeIndex are written to the ilg file (see chapter 12 for more details).

BibTeX (see chapter 13) is a program written by Oren Patashnik for the preparation of bibliographies. BibTeX handles reference data bases collected in bib files. LaTeX writes information about the references required in a document into its aux file(s); the latter are then read by BibTeX, which generates a sorted bibliography in a bbl file. The bbl file is used by LaTeX in a subsequent run. The kind of sorting and the format of the ''cite keys'' are defined by bibliography styles, specified in bst files. The messages generated by BibTeX are written to a blg transcript file.

  Output Processors (dvi Drivers)

Once the document has been successfully processed by TeX, you will probably want to see the result. Several options are open, namely:

• Generate a high-quality (greater than 1000 dpi) copy on paper. In this case the dvi file is translated into dots on a film via a dedicated driver or PostScript is generated.
• Generate a medium-quality (300 dpi) copy on paper. Different DVI drivers, specific to a given printing device, can be used. More and more often, PostScript is becoming the obvious choice.
• The contents (text and graphics) can be visualized on a computer graphics screen, where utilities like xdvi (on X Window System) can be used. Again, PostScript previewers can use the latter language for looking at the information in the document.
• The contents may be viewable on a ''dumb'' character-only terminal. Graphics cannot be shown in this case, but the text is formatted in columns narrow enough to fit nicely on screen less than 80 columns wide. This kind of documentation is often used for bundling computer program descriptions with the code.

It is clear from the above that the PostScript language plays an important rôle in the process of document visualization.   metafont sources (mf) exist for all Computer Modern and LaTeX fonts, and thus bitmap images (pk) can be generated for any kind of printer. PostScript Type 1 renderings of the Computer Modern, LaTeX, AMS, and Euler fonts also exist and are commercially available from Blue Sky Research and Y&Y. Moreover, Adobe and other type foundries offer a vast choice of fonts, which can be used with LaTeX (see section 11.9). This means that you can decide what is the best (and most pleasing) way to present the information in your document.

The Concept of Generic Markup

What Is Generic Markup?

Originally, markup was the annotation of manuscripts by a copyeditor telling the typesetter how to format the manuscript. It consisted of handwritten notes such as: ''Set this heading in 12-point Helvetica Italic on a 10-point text body, justified on a 22-pica slug with indents of 1 em on the left and none on the right.''

With the introduction of computers, these remarks could be coded electronically using a special coding system. Each phototypesetter had its own proprietary ''language,'' called markup language by analogy with the old manual system. Since many typesetting companies also provided a ''keyboarding'' service, the markup source of the documents to be typeset was always the same and the lack of compatibility was not an issue. When, however, authors and clients of typesetting companies started to type their own manuscripts this situation created problems. They could only do the typing if they knew in advance the markup format of their typesetting vendor. If they typed on their own system, it was likely that the markup format of their document would be incompatible with that of the typesetter.

The situation only got worse when people started using computers for document preparation. As in the case of phototypesetting systems, documents were coded with specific markup commands. These are low-level formatting commands such as ''carriage return,'' ''center the following text,'' and ''go to the next page.'' A document containing the following specific markup (SCRIPT [31]):

.pa ;.sp 2 ;.ce ;.bd
Title of chapter
.sp

\vfill\eject\begingroup\bf\obeylines\vskip 20pt
\hfil TITLE OF CHAPTER
\vskip 10pt\endgroup\bigskip

A movement was started to create a standard markup language, which all typesetting vendors would be persuaded to accept as input. It would be the typesetter's problem to translate this language into the language of their own photocomposition machines. This markup language was a generic markup language. Generic markup means adding information to the text indicating the logical components of a document such as paragraphs, headings, and footnotes. The formatting (visual representation) associated with a component is decoupled from its function (position) in the (hierarchical) structure of the text.

LaTeX is, to a large extent, an example of a ''generic markup language'' (GML). Thanks to the class file mechanism, the visual style of the various document elements are described in a single place outside of the source document itself.

Building on the pioneering GML work by Charles Goldfarb and also taking into account ideas of Brian Reid's Scribe system, the International Organization for Standardization developed the SGML  (Standard Generalized Markup Language) standard (ISO 8879)  published in 1986. SGML  is a markup language for representing documents in an exchangeable format. SGML  is intended ''for publishing in its broadest definition, ranging from single medium conventional publishing to multimedia data base publishing. SGML  can also be used in office document processing when the benefits of human readability and interchange with publishing systems are required.'' [34] For an introduction to SGML , see [27, 92]. SGML  is a meta-language. That is, it specifies the rules by which an infinite variety of markup languages can be created. SGML  should not concern itself with the formatting of marked-up documents, i.e.,there should be no ''layout'' tags in SGML , like ''new page,'' ''new line,'' or ''rule.'' Instead, these layout-oriented features are properties of certain format components. For example, a heading of level 1 may, in a given layout style, be starting a new page, or a rule may be used to separate a heading from the body of a memo.

As a practical typesetting tool, authored by a scientist, LaTeX combines and balances the advantages of high-level generic characteristics à la SGML , with layout specific support. The class file mechanism makes it possible to produce the same source document in different layouts, while enough bells and whistles are available to fine-tune important documents for producing the highest quality.

Advantages of Generic Markup

The use of a consistent layout throughout a document helps the reader understand the various visual clues associated with a given component. It also allows the document to be reused for producing online documentation, or eases the automatic extraction of information via predefined keywords.

One should also bear in mind the fact that typography is a creative skill, requiring a level of experience and craftsmanship that is rarely found in the untrained layman. Therefore the development of a new style is better left to specialist designers, and casual users should restrict themselves mostly to small and consistent modifications of an already existing style. Extreme care should be taken not to upset the subtle visual balance between the various document elements.

Separation of Content and Form

In order to ensure that all logical document elements receive the same typographical treatment throughout the document, you should define new document elements in a generic way in the document preamble. By this means you can be sure that the same presentation will be used everywhere to flag the element in question.

As an example, when writing a reference manual you might want to have every occurrence of a command typeset in a given font, and entered in the index automatically. Or you might choose to put the description of a command with its parameters in a shaded box, always in an identical way. You might even contemplate giving a certain presentation form to your tabular material. Therefore, it is best to define a corresponding style for your tabular environment in the document preamble. Similar considerations apply for lists, headings, and so on. Definitions of (and possible later changes) need only be made in one place in the preamble, and they will propagate automatically to your complete document.

Another advantage of using generic commands is that it is extremely simple to apply a different style just by selecting a different class in the #399#>documentclass or specifying additional options to the #400#>documentclass and #401#>usepackage commands (see section 1.2.

Necessity of Layout Markup

Notwithstanding all the benefits of generic markup, as discussed above, in the final preparation of your document you will sometimes need to overrule the decisions made by TeX.

An example is the representation of data in a tabular environment where the clarity of the layout of the data in the table can contribute substantially to a better understanding of the presentation. Moreover, when the final version of a document is being readied, it frequently occurs that the author has to insert line and page breaks in some strategic places.    

Pitfalls of Layout Markup

As already pointed out, it is not good practice to make certain layout markup decisions inside the text of a document. It is much better to define a new LaTeX environment, like Ctab for a centered tabular environment, if that is what is generally desired. Similarly, local font changes inside an environment should be limited and the generic nature of the use of a given font should be formalized by defining a corresponding specific new environment or command. Otherwise, any change in the presentation of your material results in an enormous amount of manual labor--you have to find and modify every instance of your layout markup.

You should also not misuse generic structural commands to obtain a given visual effect. For example, the sectioning commands like #410#>paragraph should not be used to get the first few words in a paragraph in bold face. Sectioning commands have a structural function inside a document (see section 2.3.1) and using them to customize the local layout might generate some surprises when you switch to a different implementation of the same class structures--like seeing some of your paragraphs getting preceded by numbers! You are better off defining a dedicated command like #412#>Boldtext or #413#>Boldpar to obtain the desired effect.

When to Use Layout Markup

When preparing the final form of a document you will find that it is often necessary to intervene locally at the micro-level to obtain a certain visual effect. Nevertheless it is always preferable to hide as much as possible the layout markup behind the generic markup. You can do this, for example, by building into the generic commands facilities for checking the space left on the page, for calculating the width of certain text strings, and so on.

Table of Contents

1. Introduction.

APPENDICES.