The LaTEX Companion
Third Edition – Part I & Part IIThis eBook is a compilation of Part I and Part II of The LATEXCompanion, Third Edition. To navigate to a specific page, click thelinks in the text or enter the part number, a hyphen, and the page
number — e.g., II-39 for page 39 in the second part.
Detailed information about the production of this eBook is
given in the Production Notes on page →II 983.

Addison-Wesley Series on
Tools and Techniques for Computer TypesettingThis series focuses on tools and techniques needed for computer typesetting and information processing with traditional and new media. Books in the series address the practicalneeds of both users and system developers. Initial titles comprise handy references for
LaTEX users; forthcoming works will expand that core. Ultimately, the series will coverother typesetting and information processing systems, as well, especially insofar as thosesystems offer unique value to the scientific and technical community. The series goal is toenhance your ability to produce, maintain, manipulate, or reuse articles, papers, reports,
proposals, books, and other documents with professional quality.
Ideas for this series should be directed to frank.mittelbach@latex-project.org.
Send all other feedback to the publisher at informit.com/about/contact_us or via
email to community@informit.com.

Series Editor
Frank Mittelbach
Technical Lead, LATEX Project, Germany

Editorial Board
Jacques André

Peter Flynn

Irisa/Inria-Rennes,

University College, Cork,

Chris Rowley
Open University, UK (Ret.)France (Ret.)

Ireland (Ret.)

William Robertson

Barbara Beeton

Matthew Hardy

The University of Adelaide,

Editor, TUGboat, USA

Adobe, USA

Australia

David Brailsford

Leslie Lamport

Steven Simske

University of Nottingham, UK

Microsoft, USA

Colorado State University, USA

Series Titles
Guide to LATEX, Fourth Edition by Helmut Kopka and Patrick W. Daly
The LATEX Companion, Third Edition by Frank Mittelbach, with Ulrike Fischer and contributions
by Javier Bezos, Johannes Braams, and Joseph Wright
The LATEX Graphics Companion, Second Edition by Michel Goossens, Frank Mittelbach,Sebastian Rahtz, Denis Roegel, and Herbert Voß
Reprinted 2022 by Lehmanns Media, Berlin
The LATEX Web Companion by Michel Goossens and Sebastian Rahtz
Also from Addison-Wesley and New Riders:
LATEX: A Document Preparation System, Second Edition by Leslie LamportComputers & Typesetting, Volumes A–E by Donald E. Knuth
The Type Project Book: Typographic projects to sharpen your creative skills & diversify your portfolio
by Nigel French and Hugh D’Andrade

Cover illustration by Lonny Garris/Shutterstock
Photos of Sebastian Rahtz courtesy of the TEX Users GroupBook design by Frank Mittelbach
Typeset with LaTEX in Lucida Bright at 8.47pt/11.72pt
Many of the designations used by manufacturers and sellers to distinguish their products
are claimed as trademarks. Where those designations appear in this book, and the
publisher was aware of a trademark claim, the designations have been printed with initial
capital letters or in all capitals.
The authors and publisher have taken care in the preparation of this book, but make no
expressed or implied warranty of any kind and assume no responsibility for errors oromissions. No liability is assumed for incidental or consequential damages in connection
with or arising out of the use of the information or programs contained herein.
For information about buying this title in bulk quantities, or for special sales opportunities,
please contact our corporate sales department at corpsales@pearsoned.com or(800)382–3419.
For government sales inquiries, please contact governmentsales@pearsoned.com. For
questions about sales outside the United States, please contact intlcs@pearson.com.
Visit us on the Web: informit.com/aw
Library of Congress Control Number: 2022947208
Copyright © 2023 by Pearson Education, Inc.
All rights reserved. This publication is protected by copyright, and permission must be
obtained from the publisher prior to any prohibited reproduction, storage in a retrieval
system, or transmission in any form or by any means, electronic, mechanical,
photocopying, recording, or likewise. For information regarding permissions, request
forms and the appropriate contacts within the Pearson Education Global Rights &Permissions Department, please visit www.pearson.com/permissions/.
The foregoing notwithstanding, the examples contained in this book are madeavailable under the LaTEX Project Public License (for information on the LPPL, see
https://www.latex-project.org/lppl).
The examples can be downloaded from https://ctan.org/pkg/tlc3-examples.
Part I:

Print ISBN-13:

978-0-13-465894-0

Part II:

Print ISBN-13:

978-0-201-36300-5Part I+II (bundled):
Print ISBN-13:

978-0-13-816648-9

Part I+II (combined) digital:ePub ISBN-13:
uPDF ISBN-13:
First digital release, 2023

978-0-13-816652-6
978-0-13-816657-1

A TeX Haiku\expandafter\def\csname def\endcsname{\message{farewell}}\bye
SPQR
at the poetry competition
TUG conference,
Vancouver, 1999

I dedicate this edition to all my friends in the TEX world and in particular
to the memory of my good friend Sebastian P. Q. Rahtz (1955–2016),
with whom I spent many happy hours discussing parenting, literature,
LaTEX and other important aspects of life [146].

C H A P T E R

1Introduction
1.1 A brief history (of nearly half a century) . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Today’s systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3 Working with this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

LaTEX is not just a system for typesetting mathematics. Its applications span one-page
memoranda, business and personal letters, newsletters, articles, and books covering
the whole range of the sciences and humanities . . . right up to full-scale expository
texts and reference works on all topics. Versions of LaTEX now exist for practically every
type of computer and operating system. This book provides a wealth of information
about its many present-day uses but first provides some background information.
The first section of this chapter looks back at the origins and subsequent development of LaTEX.1 The second section gives an overview of the file types used by atypical current LaTEX system and the rôle played by each. Finally, the chapter offerssome guidance on how to use the book.

1.1 A brief history (of nearly half a century)
In May 1977, Donald Knuth of Stanford University [95] started work on the textIn the Beginning . . .
processing system that is now known as “TEX and METAFONT” [84–88]. In theforeword of The TE Xbook [84], Knuth writes: “TEX [is] a new typesetting system
intended for the creation of beautiful books — and especially for books that containa lot of mathematics. By preparing a manuscript in TEX format, you are tellinga computer exactly how the manuscript is to be transformed into pages whose
typographic quality is comparable to that of the world’s finest printers.”
1 A more personal account can be found in The LAT X legacy: 2.09 and all that [176].

E

1

INTRODUCTION

In 1979, Gordon Bell wrote in a foreword to an earlier book, TE X and METAFONT,New Directions in Typesetting [82]: “Don Knuth’s Tau Epsilon Chi (TEX) is potentiallythe 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.”
In the early 1990s, Donald Knuth produced an updated version and also officiallyannounced that TEX would not undergo any further development [96, 97] in theinterest of stability. Perhaps unsurprisingly, the 1990s saw a flowering of experimental
projects that extended TEX in various directions; many of these are coming to fruitionin the early 21st century, making it an exciting time to be involved in automatedtypography.
The development of TEX from its birth as one of Don’s “personal productivity
tools” (created simply to ensure the rapid completion and typographic quality of histhen-current work on The Art of Computer Programming) [90] was largely influenced
and nourished by the American Mathematical Society on behalf of U.S. researchmathematicians.
While Don was developing TEX, in the early 1980s, Leslie Lamport started work
. . . and Lamport saw
onthe
document preparation system now called LaTEX, which used TEX’s typesettingthat it was Good.
engine and macro system to implement a declarative document description language
based on that of a system called Scribe by Brian Reid [168]. The appeal of such asystem is that a few high-level LaTEX declarations, or commands, allow the user toeasily compose a large range of documents without having to worry much about theirtypographical appearance. In principle at least, the details of the layout can be left forthe document designer to specify elsewhere.
The second edition of LATEX: A Document Preparation System [106] begins asfollows: “LaTEX is a system for typesetting documents. Its first widely available version,
mysteriously numbered 2.09, appeared in 1985.” This release of a stable and welldocumented LaTEX led directly to the rapid spread of TEX-based document processing
beyond the community of North American mathematicians.
LaTEX was the first widely used language for describing the logical structure ofa large range of documents and hence introducing the philosophy of logical design,
as used in Scribe. The central tenet of “logical design” is that the author should
be concerned only with the logical content of his or her work and not its visualappearance. Back then, LaTEX was described variously as “TEX for the masses” and“Scribe liberated from inflexible formatting control”. Its use spread very rapidly during
the next decade. By 1994 Leslie could write, “LaTEX is now extremely popular in thescientific and academic communities, and it is used extensively in industry”. But thatlevel of ubiquity looks quite small when compared with the present day when it has
become, for many professionals on every continent, a workhorse whose presence is
as unremarkable and essential as the workstation on which it is used.
The worldwide availability of LaTEX quickly increased international interest in
Going global
TEX and in its use for typesetting a range of languages. LaTEX 2.09 was (deliberately)
not globalized, but it was globalizable; moreover, it came with documentation worthtranslating because of its clear structure and straightforward style. Two pivotal
conferences (Exeter UK, 1988, and Karlsruhe Germany, 1989) established clearly thewidespread adoption of LaTEX in Europe and led directly to International LaTEX [180]

2

1.1

A brief history (of nearly half a century)and to work led by Johannes Braams [23] on more general support for using a wide
variety of languages and switching between them (see Chapter 13).
Note that in the context of typography, the word language does not refer exclusively to the variety of natural languages and dialects across the universe; it also has
a wider meaning. For typography, “language” covers a lot more than just the choice of“characters that make up words”, as many important distinctions derive from othercultural differences that affect traditions of written communication. Thus, importanttypographic differences are not necessarily in line with national groupings but rather
arise from different types of documents and distinct publishing communities.
Another important contribution to the reach of LaTEX was the pioneering work of
The Next Generation
Frank Mittelbach and Rainer Schöpf on a complete replacement for LaTEX’s interface
to font resources, the New Font Selection Scheme (NFSS) (see Chapter 9). They werealso heavily involved in the production of the AMS-LaTEX system that added advanced
mathematical typesetting capabilities to LaTEX (see Chapter 11).
As a reward1 for all their efforts, which included a steady stream of bug reports(and fixes) for Leslie, by 1989 Frank and Rainer “were allowed” to take over the maintenance and further development of LaTEX. One of their first acts was to consolidate
International LaTEX as part of the kernel2 of the system, “according to the standard
developed in Europe”. Very soon version 2.09 was formally frozen, and although thechange-log entries continued for a few months into 1992, plans for its demise as asupported system were already far advanced as something new was badly needed.
The worldwide success of LaTEX had by the early 1990s led in a sense to too much
Too much of adevelopment activity: under the hood of Leslie’s “family sedan” many TEXnicians had Good ThingTM
been laboring to add such goodies as super-charged, turbo-injection, multivalved
engines and much “look-no-thought” automation. Thus, the announcement in 1994 of
the new standard LaTEX, christened LaTEX 2ε , explains its existence in the following way:
Over the years many extensions have been developed for LaTEX. Thisis, of course, a sure sign of its continuing popularity but it has had one
unfortunate result: incompatible LaTEX formats came into use at different
sites. Thus, to process documents from various places, a site maintainer wasforced to keep LaTEX (with and without NFSS), SLITEX, AMS-LaTEX, and so on.
In addition, when looking at a source file it was not always clear for which
format the document was written.
To put an end to this unsatisfactory situation a new release of LaTEX wasproduced. It brings all such extensions back under a single format and thus
prevents the proliferation of mutually incompatible dialects of LaTEX 2.09.
The development of this “New Standard LaTEX” and its maintenance system wasStandard LATEX
started in 1993 by the LaTEX Project Team [148], which soon comprised the author (LAT X 2 )E εof this book, Rainer Schöpf, Chris Rowley, Johannes Braams, Michael Downes (1958–
2003), David Carlisle, Alan Jeffrey, and Denys Duchier, with some encouragement andgentle bullying from Leslie. Although the major changes to the basic LaTEX system(the kernel) and the standard document classes (styles in 2.09) were completed by
1 Pronounced “punishment”.
2 Kernel here means the core, or center, of the system.

3

1

INTRODUCTION

1994, substantial extra support for colored typography, generic graphics, and finepositioning control were added later, largely by David Carlisle. Access to fonts forthe new system incorporated work by Mark Purtill on extensions of NFSS to bettersupport variable font encodings and scalable fonts [30–32].
At this point in the story the first edition of the LATEX Companion was written,
1994 — The firstwhich
helped a lot in making many important packages known to a wide audience
edition of the LATEX
andasa side effect helped shape a standard corpus of LaTEX packages expected to beCompanion
available on any installation across the world.
Although the original goal for this LaTEX 2ε was consolidation of the wide range of
Towards the 21stincompatible models carrying the LaTEX marquee, what emerged was a substantiallycentury
more powerful system with both a robust mechanism (via LaTEX packages) for extension
and, importantly, a solid technical support and maintenance system. This provides
robustness via standardization and maintainability of both the code base and the
support systems. The core of this system remains the current standard LaTEX systemthat is described in this book. It has fulfilled most of the goals for “a new LaTEX for the
21st Century”, as they were envisaged back in 1989 [151, 153].
The specific claims of the current system are “. . . better support for fonts, graphics and color; actively maintained by the LaTEX Project Team”. The details of how
these goals were achieved, and the resulting subsystems that enabled the claims tobe substantially attained, form a revealing study in distributed software support:
the core work was done in at least five countries and, as is illustrated by the bugs
database [108], the total number of active contributors to the technical support effort
remains high.
Although the LaTEX kernel suffered a little from feature creep in the late 1990s,
The package system
the package system together with the clear development guidelines and the legal
framework of the LaTEX Project Public License (LPPL) [111, 132] have enabled LaTEX toremain almost completely stable while supporting a wide range of extensions. These
have largely been provided by a similarly wide range of people who have, as the
project team are happy to acknowledge and the online catalogue [197] bears witness,enhanced the available functionality in a vast panoply of areas.
All major developments of the base system have been listed in the regular issues
Development workof LATEX News [107]. At the turn of the century, development work by the LaTEX Project
Team focused on the following areas: supporting multi-language documents [130]; a“Designer Interface for LaTEX” [141]; major enhancements to the output routine [131];
improved handling of inter-paragraph formatting; and the complex front-matter
requirements of journal articles. Back then prototype code had been made available(see [140]), but the work has otherwise been kept separate from LaTEX — partly because
it was executing simply too slowly on the available hardware.
One thing the project team steadfastly refused to do at that time was to unnecNo new features at
essarily“enhance” the kernel by providing additional features as part of it, thereby
the kernel level . . .
avoiding the trap into which LaTEX 2.09 fell in the early 1990s: the disintegration into
incompatible dialects where documents written at one site could not be successfully
processed at another site. In this discussion it should not be forgotten that LaTEX
serves not only to produce high-quality documents but also to enable collaborationand exchange by providing a lingua franca for various research communities.

4

1.1

A brief history (of nearly half a century)

With LaTEX 2ε , documents written in 19961 can still be run with today’s LaTEX. In
the opposite direction, new documents run on older kernel releases if the additional
packages used are brought up-to-date — a task that, in contrast to updating the
LaTEX kernel software, is easily manageable even for users working in a multiuser
environment (e.g., in a university or company setting).
But a stable kernel is not identical to a standstill in software development; of. . . but no standstillequally crucial importance to the continuing relevance and popularity of LaTEX is thediverse collection of contributed packages building on this stable base. The successof the package system for nonkernel extensions is demonstrated by the enthusiasmof these contributors — many thanks to all of them! As can be easily appreciated byvisiting the highly accessible and stable Comprehensive TEX Archive Network (seeAppendix C) or by reading this book (where more than 250 of these “Good Guys”2are listed on page →II 967), this has supported the existence of an enormous treasure
trove of LaTEX packages and related software.
The provision of services, tools, and systems-level support for such a highly
The back office
distributed maintenance and development system was itself a major intellectual
challenge, because many standard working methods and software tools for thesetasks assume that your colleagues are in the next room, not the next continent (andin the early days of the development, e-mail and FTP were the only reliable meansof communication). The technical inventiveness and the personalities of everyone
involved were both essential to creating this example of the friendly face of open
software maintenance, but Alan Jeffrey and Rainer Schöpf deserve special mention
for “fixing everything”.
A vital part of this system that is barely visible to most people is the regression
testing system with its vast suite of test files [129]. It was initially devised and set
up by Frank and Rainer with Daniel Flipo; it has proved its worth countless times
in the never-ending battle of the bugs. Over the years it has seen many refinements,
cumulating in a complete rewrite as part of l3build [147], which we describe in
Section 17.3 on page →II 606.
In 2004, i.e., roughly a decade after its first edition, the second edition of the LATEX
2004 — The second
Companion was published. Due to the popularity of LaTEX 2ε and its extended features edition of the LAT X
E
for developers, new important packages had emerged, and LaTEX had reached out into Companion
new domains. While the advice given in the first edition remained largely valid (lastnot least because of the long-term backward compatibility paradigm of LaTEX), we
ended up rewriting 90% of the original content and added about 600 pages to accountfor new developments. As before, the second edition helped a lot in standardizing theuse, and this way the interoperability, of LaTEX across the world.
Some members of the LaTEX Project Team have built on the team’s experience to
Researchextend their individual research work in document science beyond the current LaTEX
structures and paradigms. Some examples of their work up to now can be found
1 The time between 1994 and 1996 was a consolidation time for LaT X 2 , with major fixes andE εenhancements being made until the system was thoroughly stable. In fact, with some minor alterations
in pagination or font usage, it is usually possible to reprocess even documents from the eighties (i.e.,
written for LaTEX 2.09) or make them reusable with little effort.
2 Unfortunately, this is nearly the literal truth: you need a keen eye to spot the few ladies listed.

5

1

INTRODUCTION

in the following references: [33, 35–37, 133–135, 138, 149, 175, 177]. An important
spin-off from the research work was the provision of some interfaces and extensions
that are immediately usable with standard LaTEX.
The decision to keep the core of the standard LaTEX system stable and essentially. . . and into theunchanging
had two major advantages over any other approach to support fully
futureautomated document processing. First, the system already efficiently provided highquality formatting of a large range of elements in very complex documents of arbitrary
size. Second, it was robust in both use and maintenance and hence offered thepotential to remain in widespread use for at least a further 15 years.1 In the second
edition of this book we wrote on this topic:
As more such functionality is added, it will become necessary to assess
the likelihood that merely extending LaTEX in this way will provide a more
powerful, yet still robust and maintainable, system. This is not the place
to speculate further about the future of LaTEX but we can be sure that it
will continue to develop and to expand its areas of influence whether intraditional publishing or in electronic systems for education and commerce.
This reassessment became necessary in the second decade of the new century, when it
became obvious that this position was gradually getting unsustainable, because more
and more areas in which people were looking for solutions could not be adequately
addressed with a model of a fixed kernel and all developments outsourced to the
package level. Examples are the move to Unicode in basically all operating systems andthe growing pressure to produce “accessible” documents that conform to standards
such as PDF/UA (Portable Document Format/Universal Accessibility).
Thus, in 2015, the LaTEX Project Team changed its policy and restarted kernel
An important development.
To retain the best of both worlds this was accompanied by developing a
policy change
rollback/roll-forward functionality for the kernel and packages (that care to implementit). This allows a current LaTEX format to roll back to an earlier point in time in orderto process old documents that rely on interfaces that have been changed since thenor to process documents that explicitly worked around bugs (and so expect them tobe there) that have been fixed in the meantime.
The first action of the team was to retire the fixltx2e package and instead include
the accumulated fixes it contained directly in the format and to officially support LaTEX
when using the Unicode engines XETEX and LuaTEX. A big step forward happened in2018 when LaTEX switched its default input encoding to UTF-8. This change provedthat the policy change was the right thing to do and that the preparatory work (e.g.,
providing rollback) allows executing even major changes without disruption in its userbase in order to keep LaTEX relevant and useful. A good indicator for the renewed andincreased activity are the regular LaTEX newsletters [107] accompanying each release,which grew bulkier and again appeared semi-annually.

Reassessment time

1 One of the authors of the second edition had publicly staked a modest amount of beer on T X
Eremaining in general use (at least by mathematicians) until at least 2010. He should have made alarger bet, given that this is now 2022 and LaTEX is healthy and in fact growing its user base due to its
many unsurpassed qualities.

6

1.1

A brief history (of nearly half a century)

The event of providing the mythical LaTEX3 had long become a standing joke as
And where is the“two years from ‘now’ — with ‘now’ a moving target”. The reason was that the concepts mythical LAT X3?
E
and ideas for LaTEX3 have been simply a decade or more too early, and while the team
implemented a fully working version already in 1990, it was simply too slow to beusable with the then available computing power. Thus, we gave up pursuing it andinstead concentrated on offering LaTEX 2ε , which then went public in 1994.
But ideas and concepts were never forgotten by the team, and especially its newer
members (who joined in this century) pushed them back to the forefront and improved
them dramatically. As a result, the code was eventually publicly made available as the
expl3 package. It was then picked up by a number of enthusiastic package developers
and used as the basis for their new packages. For example, if you use acro, breqn,
fontspec, siunitx, unicode-math, or xparse, to name a few, you use “LaTEX3” under thehood; a recent count shows more than 200 such packages or classes as part of TEX Live.
So in 2019 the LaTEX Project Team made two wide-ranging decisions: there will
not be a separate LaTEX3 that is being developed alongside LaTEX 2ε (as was originallyplanned). Instead, we will modernize the current LaTEX gradually from the inside, using
the new rollback mechanism and “development” formats as a safety net to ensure that. . . well it got merged
there is no disruption of service for our user base. As a first step on this journey, the into the kernel inL3 programming layer and the LaTEX3 document-level command declarations (formerly 2020
known as expl3 and xparse) were made an integral part of LaTEX on February 2, 2020.
Thus, more or less exactly 30 years after its conception, LaTEX3 became a reality forevery LaTEX user — even though few will have immediately noticed.
The importance of this step is that it allows the team to modernize other parts of
The foundation layer
the kernel and develop new functionality entirely based on the L3 programming layer, for modernization
which offers many features not available with legacy LaTEX programming constructs.
For example, the new Hook Management System for LaTEX, which is a cornerstone formodernizing and transforming the existing LaTEX, is entirely written using the new L3
programming layer, and other parts will follow suit.
As already mentioned, there is a steadily increasing interest in the production
Today’s challenge:of “tagged” PDF documents that are “accessible”, in the sense that they contain infor- structured andmation to assist screen reading software, etc., and, more formally, that they adhere accessible output isto the PDF/UA (Portable Document Format/Universal Accessibility) standard [190], needed
explained further in [47]. In many disciplines this is starting to become a requirement
when applying for grants or when publishing results.
At the moment, all methods of producing such “accessible PDFs”, including
the use of LaTEX, require extensive manual labor in preparing the source or in postprocessing the PDF (maybe even at both stages); and these labors often have to berepeated after making even minimal changes to the (LaTEX or other) source. Thisis a huge pity, because LaTEX should in theory be well positioned to do this work
automatically, given that its source is already well-structured.
The production of tagged (i.e., structured) PDF documents is not only importantin order to comply to accessibility standards. It also opens possibilities to reuse datafrom such PDFs, because it allows other applications to correctly identify the structure
inside the output document and this way extract or manipulate parts of the content —workflows that become increasingly important in the digital world.

7

1

INTRODUCTION

The LaTEX Project Team has for some years been well aware that these new usages
are not adequately supported by the current system architecture of LaTEX 2ε and thatmajor work in this area is therefore urgently needed to ensure that LaTEX remains
an important and relevant document source format. However, the amount of workrequired to make such major changes to the LaTEX system architecture is enormousand definitely way beyond the limited resources of a small team of volunteers working
in their spare time (or maybe just about possible, but only given a very long — andmost likely too long — period of time).
At the TEX Users Group conference 2019 in Palo Alto the team’s previously pesA multi-year simistic
outlook on this subject became cautiously optimistic, because of discussions
project to shape
the future of LATEX with senior executives from Adobe about the possibility of producing structured PDF
from LaTEX source without the need for the usual requirement of considerable manual
post-processing. As a result of these discussions, towards the end of 2019 the teamproduced an extended feasibility study for the project, aimed primarily at Adobe
engineers and decision-makers. This study [144] describes in some detail the various
tasks that constitute the project and their interdependencies. It also contains a projectplan covering how, and in what order, these tasks should be tackled both to achieve
the final goal and, at the same time, to provide intermediate concrete results that are
relevant to user communities (both LaTEX and PDF); these intermediate results will help
in obtaining feedback that is essential to the successful completion of later tasks.
This multi-year project found the approval of Adobe, which then committed tofinancially and otherwise supporting this endeavor [150]. Unfortunately — thanks
to the COVID-19 pandemic — the start got delayed, but since the end of 2020, thisexciting project is now well under way. First results from this project that are alreadyin existence (such as the new hook management system and the alignment of thehyperref package with the LaTEX kernel) are already described in this book. Other parts
are obviously still vaporware at this point. Fortunately, none is expected to renderany documentation or suggestion made in this book obsolete — after all, the project
goal is to enable tagging of existing documents, simply by reprocessing with minor
configuration changes as outlined in the “Spoiler alert” Section 2.1.1 on page 23.

1.2 Today’s systems
When we wrote the second edition of The LATEX Companion (i.e., 2003–2004), standard
LaTEX was (officially) supported only on 8-bit engines, e.g., pdfTEX. Around the sametime, the first version of the Unicode engine XETEX and (somewhat later, in 2007) the
first beta version of LuaTEX appeared, and there were soon unofficial support files
that helped people running LaTEX on these Unicode engines as well.
When LuaTEX reached version 1.0, the LaTEX Project Team used the opportunityand officially took on LaTEX support for all three engines that included, for example,
running the release regression test suite with its roughly 1000 tests against all three
engines. Besides these three engines (which are covered in this book), there are further
ones, such as pTEX and upTEX for Japanese, where the LaTEX adjustments for the engine
are maintained by the respective user groups.

8

C H A P T E R

2The Structure of a LATEXDocument
2.1 The overall structure of a source file . . . . . . . . . . . . . . . . . . . . . . . . 22
2.2 Sectioning commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.3 Table of contents structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
2.4 Managing references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
2.5 Document source management. . . . . . . . . . . . . . . . . . . . . . . . . . . 108

One of the ideas behind LaTEX is the separation between layout and structure (as far
as possible), which allows the user to concentrate on content rather than having toworry about layout issues [106]. This chapter explains how this general principle is
implemented in LaTEX.
The first section of this chapter shows how document class files, packages,
options, and preamble commands can affect the structure and layout of a document.
The logical subdivisions of a document are then discussed in general, before
explaining in more detail how sectioning commands and their arguments define ahierarchical structure, how they generate numbers for titles, and how they produce
running heads and feet. This is followed by discussing a few useful packages thatallow you to customize different aspects of the layout of sectional units or to provide
your own definitions.
In Section 2.3 we take a closer look at the design of table of contents structuresand how it can be influenced or extended.
This is followed by a section discussing important packages that support you
in providing cross-references that remain correct, even if you change parts of yourdocument. These packages can automatically insert appropriate phrases (varioref,
cleveref, nameref), can help you manage your label keys (showkeys and refcheck),or support you in providing references to external documents (xr) or hyperlinks ingeneral (hyperref).
The final section introduces packages and programs that support you in archiving
documents or managing them when you work jointly with others on some document.

2

THE STRUCTURE OF A LATEX DOCUMENT

2.1 The overall structure of a source file
You can use LaTEX for several purposes, such as writing an article or a book or producing presentations. Clearly, documents for different purposes may need different
logical structures, i.e., different commands and environments. We say that a document
belongs to a class of documents having the same general structure (but not necessarily
the same typographical appearance). You specify the class to which your document
belongs by starting your LaTEX file with a \documentclass command, where themandatory parameter specifies the name of the document class. The document classdefines the available logical commands and environments (for example, \chapter
in the report class) as well as a default formatting for those elements. An optional
argument allows you to modify the formatting of those elements by supplying a listof class options. For example, 11pt is an option recognized by most document classes
that instructs LaTEX to choose eleven point as the basic document type size.
Many LaTEX commands described in this book are not specific to a single class but
can be used with several classes. A collection of such commands is called a package,and you inform LaTEX about your use of certain packages in the document by placing
one or more \usepackage commands after \documentclass .
Just like the \documentclass declaration, \usepackage has a mandatory argument consisting of the name of the package and an optional argument that cancontain a list of package options that modify the behavior of the package.1
The document classes and the packages reside in external files with the extensions.cls and .sty , respectively. Code for options is sometimes stored in external files(in the case of class files with the extension .clo ) but is normally directly specified
in the class or package file (see Appendix A for information on declaring options inclasses and packages). However, in the case of options, the file name can differ fromthe option name. For example, the option 11pt is related to size11.clo when usedin the article class and to bk11.clo inside the book class.
Commands placed between \documentclass and \begin{document} are in
The document
the so-called document preamble. All style parameters must be defined in thispreamblepreamble, either in package or class files or directly in the document before the\begin{document} command, which sets the values for some of the global parameters. A typical document preamble could look similar to the following:\documentclass[twocolumn,a4paper]{article}\usepackage{multicol}\usepackage[ngerman,french]{babel}\addtolength\textheight{3\baselineskip}\begin{document}This document preamble defines that the class of the document is article and that thelayout is influenced by the formatting request twocolumn (typeset in two columns)
and the option a4paper (print on A4 paper). The first \usepackage declaration
1 These commands also have a second optional argument that is intended for cases where a specificrelease of a package or a document class is required. This is discussed in Section 2.5.5 on page 114.

22

2.1

The overall structure of a source fileinforms LaTEX that this document contains commands and structures provided by the
package multicol. In addition, the babel package with the options ngerman (support
for German language) and french (support for French language) is loaded. Finally,
the default height of the text body was enlarged by three lines for this document.
Generally, nonstandard LaTEX package files contain modifications, extensions, or
improvements1 with respect to standard LaTEX, while commands in the preamble
define changes for the current document. Thus, to modify the layout of a document,
you have several possibilities:• Change the standard settings for parameters in a class file with options definedfor that class.
• Add one or more packages to your document and make use of them.
• Change the standard settings for parameters in a package file with options definedfor that package.
• Write your own local packages containing special parameter settings and loadthem with \usepackage after the package or class they are supposed to modify(as explained in the next section).
• Make final adjustments inside the preamble.
If you want to get deeper into LaTEX’s internals, you can, of course, define your own
general-purpose packages that can be manipulated with options. You find additional
information on this topic in Appendix A.

2.1.1 Spoiler alert — The \DocumentMetadata command
When LaTEX changed from LaTEX2.09 to LaTEX 2ε around 1994, the overall document
structure was slightly changed to automatically distinguish old from new documents (to switch to compatibility mode, if necessary). LaTEX 2ε documents start with\documentclass as described above, while LaTEX2.09 documents started with thecommand \documentstyle , and \usepackage was unavailable.
Now, roughly a quarter century later, there is another major shift under way
during which LaTEX is being modernized to support accessible PDF/UA (Portable
Document Format/Universal Accessibility) and other functionality that is importantfor it to remain useful; see the discussion in Section 1.1 on page 7. This time around,the functionality change is essentially upward compatible, and old documents can beeasily reprocessed using the new features. Thus, instead of dividing documents into
two classes (old and new) by changing the first command, you can now indicate thatyou want to use the new functionality by adding a \DocumentMetadata declarationin front of \documentclass while leaving the rest of the document unchanged.
1 Many of these packages have become de facto standards and are described in this book. This
does not mean, however, that packages that are not described here are necessarily less importantor useful, of inferior quality, or should not be used. We merely concentrated on a few of the moreestablished ones; for others, we chose to explain what functionality is possible in a given area.

23

2

THE STRUCTURE OF A LATEX DOCUMENT\DocumentMetadata{key/value list }This declaration should be the first command in a document; i.e., if present, it shouldcome before \documentclass . It expects a key/value list as its argument in which
you specify “metadata” about the document that guides the production of the final
output, e.g., should it adhere to a certain standard, should it be a tagged PDF, what
is its author, title, and keywords that are shown in the metadata of the resulting PDF,
etc. All these “metadata” are stored so that packages and users can access the data
in a consistent way.
For example, the key pdfversion allows you to set the PDF version. With the key
pdfstandard it is possible to require a standard such as A-2b . If that is specified,
it directs LaTEX to embed an appropriate color profile and set up verification tests
that packages like hyperref can use to suppress actions not allowed in this standard.
A further example is the backend key that allows you to specify a backend, e.g.,
dvipdfmx or dvisvg , which is useful in cases where the correct backend cannot be
detected automatically.
At the time of writing this book the details about which other keys are going tobe supported are still open (the whole exercise is a multi-year project [150] after all),but what we can say is that already now you can use this future interface to enable
some new functionality. For example, just adding\DocumentMetadata{}\documentclass{article}...
\begin{document}% (or any other class)% with preamble as previouslyis enough to load the new support code for managing PDF output, and this enables packages, such as hyperref, to provide features otherwise not available; see
Section 2.4.6 on page 96 for details.

2.1.2 Processing of options of the document class and packages
You can think of options to the document class or to packages as a simple way to adjust some of the properties of the whole document (when used in \documentclass)or of properties of individual packages (if specified in \usepackage ). More fine-grain
control is usually also possible through declarations and setup commands that are
defined by a class or package file and are available for use once that file is loaded.
You can specify options in a \usepackage command only if these options are
explicitly declared by the package. Otherwise, you receive an error message, informing
you that your specified option is unknown to the package in question. Options tothe \documentclass are handled slightly differently. If a specified option is notdeclared by the class, it is assumed to be a “global option”.
All options given to \documentclass (whether declared or global) are automatically passed as class options to all \usepackage declarations. Thus, if a package
file loaded with a \usepackage declaration recognizes (i.e., declares) some of theclass options, it can take appropriate actions. If not, the class options are ignored
while processing that package. Because all options have to be defined inside the classor package file, their actions are under the control of the class or package (an action24

C H A P T E R

3Basic Formatting Tools— Paragraph Level
3.1 Shaping your paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
3.2 Dealing with special characters . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
3.3 Generated or specially formatted text . . . . . . . . . . . . . . . . . . . . . . 154
3.4 Various ways of highlighting and quoting text. . . . . . . . . . . . . . . . . 177
3.5 Footnotes, endnotes, and marginals . . . . . . . . . . . . . . . . . . . . . . . 204
3.6 Support for document development. . . . . . . . . . . . . . . . . . . . . . . . 237

The way information is presented visually can influence, to a large extent, the message
as it is understood by the reader. Therefore, it is important that you use the best
possible tools available to convey the precise meaning of your words. It must, however,be emphasized that visual presentation forms should aid the reader in understanding
the text and should not distract his or her attention. For this reason, visual consistency
and uniform conventions for the visual clues are a must, and the way given structuralelements are highlighted should be the same throughout a document. This constraint
is most easily implemented by defining a specific command or environment for eachdocument element that has to be treated specially and by grouping these commands
and environments in a package file or in the document preamble. By using exclusively
these commands, you can be sure of a consistent presentation form.
In this chapter we look at such tools, starting at the micro level; larger structures
are covered in Chapter 4. The first section covers different aspects of paragraphformatting, such as producing large initial letters at the start of a paragraph, modifying
paragraph justification, altering the vertical spacing between lines of a paragraph,and similar topics. This is followed by a look at handling special characters such as
ellipses, dashes, underscores, or spaces.

3BASIC FORMATTING TOOLS — PARAGRAPH LEVEL

In the third section we discuss generated or specially formatted text, i.e., countervalues represented as ordinals or cardinals, fractions formatted for use in runningtext, and in particular the acro package for consistently managing acronyms andabbreviations. A special focus is given to scientific notation provided by the siunitx
package, which forms the last and rather lengthy topic of this section.
The fourth section then covers various way of highlighting and quoting text. This
includes a number of generally useful packages as well as some more specialized
ones that are occasionally useful.
Section 3.5 deals with the different kind of “notes”, such as footnotes, marginal
notes, and endnotes, and explains how they can be customized to conform to different
styles, if necessary. In the final section we take a quick look at different helper
packages for document development, e.g., how to add different kind of notes, copyediting marks, or change bars to your documents.

3.1 Shaping your paragraphs
For formatting paragraphs LaTEX deploys the algorithms already built into the TEXParagraph
program, which by default produce justified paragraphs. In other words, spaces
justification in TE X
and LATEX between words are slightly stretched or shortened to produce lines of equal length.

TEX achieves this outcome with an algorithm that attempts to find an optimal solution
for a whole paragraph, using the current settings of about 20 internal parameters.
They include aspects such as trying to produce visually compatible lines, such that atight line is not followed by one very loosely typeset, or considering several hyphensin a row as a sign of bad quality. The interactions between these parameters are very
subtle, and even experts find it difficult to predict the results when tweaking them.
Because the standard settings are suitable for nearly all applications, we describe
only some of the parameters in this book. Appendix B.4.3 discusses how to trace
the algorithm. If you are interested in delving further into the matter of automaticparagraph breaking, refer to The TE Xbook [84, chap.14], which describes the algorithm
in great detail, or to the very interesting article by Michael Plass and Donald Knuth on
the subject, which is reprinted in Digital Typography [99].
The downside of the global optimizing approach of TEX, which you will encounter
Downside sooneror later, is that making small changes, like correcting a typo near the end of aof global
paragraph,
can have drastic and surprising effects, as it might affect the line breaking
optimizationof the whole paragraph. It is possible, and not even unlikely, that, for example, theremoval of a word might actually result in making a paragraph one line longer.
This behavior can be very annoying if you are near the end of an important project(like the third edition of this book) and a correction wreaks havoc on your alreadymanually adjusted page breaks. In such a situation it is best to place \linebreakor \pagebreak commands into strategic places to force TEX to choose a solutionthat it would normally consider inferior. To be able to later get rid of such manual
corrections you can easily define your own commands, such as\newcommand\CElinebreak{\linebreak}rather than using the standard LaTEX commands directly. This helps you to distinguish

120

3.1

Shaping your paragraphs

the layout adjustments for a particular version from other usages of the originalcommands — a method successfully used in the preparation of this book.
Interword spacing
The interword spacing in a justified paragraph (the white space between individual
words) is controlled by several TEX parameters — the most important ones are\tolerance and \emergencystretch . By setting them suitably for your document
you can prevent most or all of the “Overfull box” messages without any manualline breaks. The \tolerance command is a means for setting how much theinterword space in a paragraph is allowed to diverge from its optimum value.1
This command is a TEX (not LaTEX) counter, and therefore it has an uncommon
assignment syntax — for example, \tolerance=500 . Lower values make TEX
try harder to stay near the optimum; higher values allow for loose typesetting.
The default value is often 200. When TEX is unable to stay in the given tolerance,
you will find overfull boxes in your output (i.e., lines sticking out into the margin like this).
Enlarging the value of \tolerance means that TEX also considers poorer but hopefully still acceptable line breaks, instead of turning the problem over to you
for manual intervention. Sensible values are between 50 and 9999. Do not use~ Careful with
10000 or higher, because that allows TEX to produce a single arbitrarily bad line
TE X’s idea about
(like
this
one) infinitely bad
to keep the rest of the paragraph perfect. If you really need fully automatedline breaking, it is better to set the length parameter \emergencystretch to a
positive value. If TEX cannot break a paragraph without producing overfull boxes (dueto the setting of \tolerance ) and \emergencystretch is positive, it adds thislength as stretchable space to every line, thereby accepting line-breaking solutions
that have been rejected before. You may get some underfull box messages because all
the lines are now set in a loose measure, but this result will still look better than asingle horrible line in the middle of an otherwise perfectly typeset paragraph.
LaTEX has two predefined commands influencing the above parameters: \fussy ,which is the default, and \sloppy , which allows for relatively bad lines. The \sloppy
command is automatically applied by LaTEX in some situations (e.g., when typesetting\marginpar arguments or p columns in a tabular environment) where perfect line
breaking is seldom possible due to the narrow measure. It uses a \tolerance of9999 together with an \emergencystretch of 3em.
Unjustified text
While the theory on producing high-quality justified text is well understood (eventhough surprisingly few typesetting systems other than TEX use algorithms that can
produce high quality other than by chance), the same cannot be said for the situation
when unjustified text is being requested. This may sound strange at first hearing. Afterall, why should it be difficult to break a paragraph into lines of different length? The
answer lies in the fact that we do not have quantifiable quality measures that allow us
to easily determine whether a certain breaking is good or bad. In comparison to its
1 The optimum is font defined; see Section 9.8.1 on page 745.

121

3

BASIC FORMATTING TOOLS — PARAGRAPH LEVEL

work with justified text, TEX does a very poor job when asked to produce unjustified
paragraphs. Thus, to obtain the highest quality we have to be prepared to help TEX
far more often by adding explicit line breaks in strategic places. A good introduction
to the problems in this area is given in an article by Paul Stiff (1949–2011) [183].
The main type of unjustified text is the one in which lines are set flush left but areunjustified at the right. For this arrangement LaTEX offers the environment flushleft .
It typesets all text in its scope “flush left” by adding very stretchable white space at
the right of each line; that is, it sets the internal parameter \rightskip to 0pt plus
1fil . This setting often produces very ragged-looking paragraphs because it makes
all lines equally good independent of the amount of text they contain. In addition,
hyphenation is essentially disabled because a hyphen adds to the “badness” of a line
and, because there is nothing to counteract it, TEX’s paragraph-breaking algorithm
normally chooses line breaks that avoid hyphenated words.

“The LATEX document preparation system isa special version of Donald Knuth’s TEX
program. TEX is a sophisticated program
designed to produce high-quality
typesetting, especially for mathematical
text.”\begin{flushleft}‘‘The \LaTeX{} document preparation system isa special version of Donald Knuth’s \TeX{}
program. \TeX{} is a sophisticated program
designed to produce high-quality typesetting,especially for mathematical text.’’\end{flushleft}

In summary, LaTEX’s flushleft environment is not particularly well suited tocontinuous unjustified text, which should vary at the right-hand boundary only to acertain extent and where appropriate should use hyphenation (see ragged2e in thenext section for alternatives). Nevertheless, it can be useful to place individual objects,
like a graphic, flush left to the margin, especially because this environment adds space
above and below itself in the same way as list environments do.
Another important restriction is the fact that the settings chosen by this environment have no universal effect, because some environments (e.g., minipage ortabular ) and commands (e.g., \parbox , \footnote , and \caption ) restore thealignment of paragraphs to full justification. That is, they set the \rightskip lengthparameter to 0pt and thus cancel the stretchable space at the right line endings. A
way to automatically deal with this problem is provided by the package ragged2e.
Other ways of typesetting paragraphs are flush right and centered, with theflushright and center environments, respectively. In these cases the line breaks
are usually indicated with the \\ command, whereas for ragged-right text (theflushleft environment discussed above) you can let LaTEX do the line breaking
itself (if you are happy with the resulting quality).
The three environments discussed in this section work by changing declarations
that control how TEX typesets paragraphs. These declarations are also available as
LaTEX commands, as shown in the following table of correspondence:
environment:command:122

center\centering

flushleft\raggedrightflushright\raggedleft

3-1-1

C H A P T E R

4Basic Formatting Tools— Larger Structures
4.1 Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
4.2 Simulating typed text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
4.3 Lines and columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
4.4 Generating sample texts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

While the previous chapter was concerned with micro-typography, this chapter now
looks at commands and environments for formatting larger chunks of text.
Typesetting lists is the subject of the first part. We start with a discussion of thevarious parameters and commands controlling the standard LaTEX lists, enumerate ,itemize , and description , followed by a brief look at LaTEX’s generic list capabilities. Then, the important enumitem package is discussed, which we recommend as abasis for many documents. The production of horizontally oriented lists is coveredby the tasks package, the concept of “headed lists” is exemplified with the amsthm
and thmtools packages and typed-checklist, helps you write and maintain check listsof various kinds. Together these should satisfy the structure and layout requirements
of most readers.
The second part then explains how to simulate “verbatim” text. In particular, wetake a detailed look at the powerful packages fancyvrb and listings.
The third part presents packages that deal with line numbering (lineno); handlingof columns, such as parallel text in two columns (paracol); or solving the problem of
producing multiple columns with multicol.
At the end we take a brief look at packages for generating sample texts. They
are useful for testing layouts or for reporting bugs when you are asked to produce aso-called Minimal Working Example (MWE) to show your problem.

4BASIC FORMATTING TOOLS — LARGER STRUCTURES

4.1 Lists
Lists are very important LaTEX constructs and are used to build many of LaTEX’s displaylike environments. LaTEX’s three standard list environments and the generic list environment are discussed in the first two sections, where we also show how they can becustomized.
Section 4.1.3 starting on page 261 provides an in-depth discussion of the package
enumitem, which introduces a number of new list structures and offers comprehensive methods to customize them, as well as the standard lists.
It is followed by a discussion of “headed lists”, such as theorems and exercises.
Finally, Sections 4.1.6 and 4.1.7 cover two packages for tasks and check lists.

4.1.1 Using and modifying the standard lists
It is relatively easy to customize the three standard LaTEX list environments itemize ,enumerate , and description , and the next three sections look at each of theseenvironments in turn. Changes to the default definitions of these environments either
can be made globally by redefining certain list-defining parameters in the document
preamble or can be kept local.
Customizing the itemize list environment
For a simple unnumbered itemize list, the labels are defined by the commands
shown in Table 4.1 on the facing page. To create a list with different-looking labels,
you can redefine the label-generating command(s). You can make that change local forone list, as in the example below, or you can make it global by putting the redefinitionin the document preamble. The following simple list is a standard itemize list witha marker from the PostScript Zapf Dingbats font (see Section 10.13.1 on page →II 113)
for the first-level labels:☞ Text of the first item in thelist.
☞ Text of the first paragraph inthe second item of the list.
The second paragraph of theitem.
☞ Text of the third item.

\usepackage{pifont}\newenvironment{myitemize}{\renewcommand\labelitemi{\ding{43}}\begin{itemize}}{\end{itemize}}\begin{myitemize}\item Text of the first item in the list.
\item Text of the first paragraph in the second
item of the list.
The second paragraph of the item.
\item Text of the third item.
\end{myitemize}

The \labelitemfont command (which defaults to \normalfont ) is intended
to alter the font for all labels in one go. This is especially useful if the body font forthe document is altered and its symbols are less suitable to be used as labels; see also
the discussion on page 697.

254

4-1-1

4.1

First Level
Second Level
Third Level
Fourth Level

CommandDefault Definition\labelitemi\labelitemii\labelitemiii\labelitemiv\labelitemfont\textbullet\labelitemfont\bfseries \textendash\labelitemfont\textasteriskcentered\labelitemfont\textperiodcentered

Lists

Representation

•
–

∗
·

Table 4.1: Commands controlling an itemize list environment

Customizing the enumerate list environment
LaTEX’s enumerated (numbered) list environment enumerate is characterized by thecommands and representation forms shown in Table 4.2 on the next page. The firstrow shows the names of the counter used for numbering the four possible levels of
the list. The second and third rows are the commands giving the representation of thecounters and their default definition in the standard LaTEX class files. Rows four, five,and six contain the commands, the default definition, and an example of the actual
enumeration string printed by the list.
A reference to a numbered list element is constructed using the \theenumi ,\theenumii , and similar commands, prefixed by the internal commands \p@enumi ,\p@enumii , etc., respectively. The last three rows in Table 4.2 on the following
page show these commands, their default definition, and an example of the representation of such references. It is important to consider the definitions of both therepresentation and reference-building commands to get the references correct.
We can now create several kinds of numbered description lists simply by applying
what we have just learned.
Our first example redefines the first- and second-level counters to use capitalroman digits and Latin characters. The visual representation should be the value ofthe counter followed by a dot, so we can use the default value from Table 4.2 on thenext page for \labelenumi .

I. Introduction
A. Applications
Motivation for research
B. Organization
Structure of the report
II. Literature Survey
4-1-2

q1=I q2=IA q3=IB q4=II\renewcommand\theenumi{\Roman{enumi}}\renewcommand\theenumii{\Alph{enumii}}\renewcommand\labelenumii {\theenumii.}\begin{enumerate}\item \textbf{Introduction}\label{q1}\begin{enumerate}\item \textbf{Applications}\label{q2} \\Motivation for research\item \textbf{Organization}\label{q3} \\Structure of the report\end{enumerate}\item \textbf{Literature Survey} \label{q4}\end{enumerate}
q1=\ref{q1} q2=\ref{q2} q3=\ref{q3} q4=\ref{q4}

255

4

BASIC FORMATTING TOOLS — LARGER STRUCTURESFirst Level

Second Level

Third Level

Counter enumi

enumiienumiii\theenumii\theenumiii
Default Definition \arabic{enumi} \alph{enumii} \roman{enumiii}
Label Field \labelenumi\labelenumii \labelenumiii
Default Form \theenumi.
(\theenumii) \theenumiii.
Representation \theenumi

Numbering Example 1., 2.

(a), (b)i., ii.

Fourth Levelenumiv\theenumiv\Alph{enumiv}\labelenumiv\theenumiv.
A., B.

Reference representation
Prefix \p@enumi
Default Definition {}\p@enumii\theenumi\p@enumiii\p@enumiv\theenumi(\theenumii) \p@enumiii\theenumiii

Reference Example 1, 2

1a, 2b1(a)i, 2(b)ii

1(a)iA, 2(b)iiB

Table 4.2: Commands controlling an enumerate list environment

After these redefinitions we get funny-looking references; to correct this we haveto adjust the definition of the prefix command \p@enumii . For example, to get areference like “I–A” instead of “IA” as in the previous example, we could do\makeatletter \renewcommand\p@enumii{\theenumi--} \makeatotherbecause the reference is typeset by executing \p@enumii followed by \theenumii .
To simplify this LaTEX offers the command \labelformat (see page 77) to alter the
representation, i.e.,\labelformat{enumii}{\theenumi--#1}
to achieve the same effect. You can also decorate an enumerate field by adding
something to the label field and its reference representation. In the example below,
we have chosen for the first-level list elements the section sign (§) as a prefix and a
period as a suffix (omitted in references).

§1. item of list
§2. item of list
w1=§1 w2=§2\renewcommand\labelenumi{\S\theenumi.} \labelformat{enumi}{\S#1}\begin{enumerate}\item \label{w1} item of list \item \label{w2} item of list\end{enumerate}
w1=\ref{w1} w2=\ref{w2}

You might even want to select different markers for consecutive labels. For
instance, in the following example, characters from the PostScript font ZapfDingbats
are used. In this case there is no straightforward way to automatically make the \refcommands produce the correct references. Instead of \theenumi simply producing
the representation of the enumi counter, we define it to calculate from the countervalue which symbol to select.

256

4-1-3

C H A P T E R

5The Layout of the Page
5.1 Geometrical dimensions of the layout . . . . . . . . . . . . . . . . . . . . . . 366
5.2 Changing the layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
5.3 Dynamic page data: page numbers and marks. . . . . . . . . . . . . . . . . 385
5.4 Page styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
5.5 Page decorations and watermarks . . . . . . . . . . . . . . . . . . . . . . . . . 409
5.6 Visual formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414
5.7 Doing layout with class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

In this chapter we see how to specify different page layouts. Often a single document
requires several different page layouts. For instance, the layout of the first page of achapter, which carries the chapter title, is generally different from that of the otherpages in that chapter.
We first introduce LaTEX’s dimensional parameters that influence the page layout
and describe ways to change them and visualize their values. This is followed by an
in-depth discussion of the packages typearea and geometry, both of which provide
sophisticated ways to implement page layout specifications.
The third section deals with the LaTEX concepts used to provide data for running
headers and footers. This section includes a description of the new mark mechanism
introduced in LaTEX in 2022.
This is followed by a section that explains how to format such elements, including
many examples deploying the fancyhdr package and others.
The fifth section then introduces commands that help in situations when the text
does not fit into the layout and manual intervention is required. This includes advice
and tools for manual pagination, which is sometimes necessary to avoid widows andorphans, avoid excessive white space, etc.
The chapter concludes with a brief look at two generic classes that go a long way
toward providing almost full control over the page layout specification process.

5

THE LAYOUT OF THE PAGE

5.1 Geometrical dimensions of the layout
The text of a document usually occupies a rectangular area on the paper — the socalled type area or body. Above the text there might be a running header and below ita running footer. They can consist of one or more lines containing the page number;
information about the current chapter, section, time, and date; and possibly othermarkers. If they are visually heavy and closely tied to the text, then these elements are
considered part of the type area; this is often the case for running headers, especiallywhen underlined. Otherwise, they are considered to belong to the top or bottom
margins. This distinction is important when interpreting size specifications.
The fields to the left and the right of the body are also called margins. Usually
they are left blank, but small pieces of text such as remarks or annotations — so-called
marginal notes — can appear there.
In general one talks about the inner and outer margins. For two-sided printing,inner refers to the middle margins — that is, the left margin on recto (odd-numbered)pages and the right margin on verso (even-numbered) ones. For one-sided printing,inner always indicates the left margin. In a book spread, odd-numbered pages arethose on the right-hand side.1
The size, shape, and position of these fields and margins on the output medium(paper or screen) and the contents of the running headers and footers are collectively
called a page layout.
The standard LaTEX document classes allow document formatting for recto–verso(two-sided) printing. Two-sided layouts can be either asymmetrical or symmetrical (theLaTEX default). In the latter case the type areas of recto and verso pages are positioned
in such a way that they overlap if one holds a sheet to the light. Also, marginal notes
are usually swapped between left/right pages.
The dimensional parameters controlling the page layout are described and shown
schematically in Figure 5.1 on the facing page.2 The default values of these parameters
depend on the paper size. To ease the adjustments necessary to print on different
paper sizes, the LaTEX class files support a number of options that set those parameters
to the physical size of the requested paper as well as adjust the other parameters(e.g., \textheight ) that depend on them.
Table 5.1 on page 368 shows the paper size options known to standard LaTEX
classes together with the corresponding page dimensions. Table 5.2 on page 369
presents the page layout parameter values for the letterpaper paper size option,
the default when no explicit option is selected. They are identical for the threestandard LaTEX document classes (article, book, and report). If a different paper size
option is selected, the values may change. Thus, to print on A4 paper, you can simply
specify \documentclass[a4paper]{article} .
Additional or different options may be available for other classes. Nevertheless,there seems to be little point in providing, say, an a0paper option for the book classthat would produce incredibly wide text lines.
1 This assumes left-to-right typesetting, e.g., for Arabic or Hebrew the situation is reversed.
2 The graphical presentation was produced with the layout package, described in Section 5.2.1,
and shows a landscape design produced with the geometry package and the options landscape ,a4paper , and hmarginratio=1:4 .

366

5.1
4

i

5

?

?

Geometrical dimensions of the layouti? Header

6
i

2

6
6
i

6

6

?

6

i

Body

7

i
- 

9

Margin
Notes


i
-

3




i

8

i

i -

10

-

11

?
 1i- 6
1
3
5
7
9
11
5-1-1

?
Footerone inch + \hoffset\oddsidemargin = -36pt\headheight = 12pt
\textheight = 294pt\marginparsep = 11pt
\footskip = 30pt
\hoffset = 0pt\paperwidth = 597pt

2
4
6
8
10

one inch + \voffset\topmargin = -58pt\headsep = 25pt
\textwidth = 418pt\marginparwidth = 121pt\marginparpush = 5pt (not shown)\voffset = 0pt\paperheight = 421pt

The dashed lines represent the reference point for TEX(\hoffset + 1 inch) and (\voffset + 1 inch) fromthe top and left of the page.
\paperheight Height of the paper to print on.
\paperwidth Width of the paper to print on.
\textheight Height of the body (without header andfooter); typically a multiple of \baselineskip
plus \topskip such that a page containing only
text perfectly fills the body area.
\textwidth Width of the body.
\columnsep Width of space between columns of text
in multicolumn mode.
\columnseprule Width of a vertical line separating
the two adjacent columns in multicolumn output(default 0pt, i.e., no visible rule).
\columnwidth Width of a single column in multicolumn mode. Calculated by LaTEX from \textwidthand \columnsep as appropriate.
\linewidth Width of the current text line. Usuallyequals \columnwidth but might get different values in environments that change the margins.

\evensidemargin For two-sided printing, the extra
space added at the left of even-numbered pages.

\oddsidemargin For two-sided printing, the extra
space added at the left of odd-numbered pages;
otherwise the extra space added at the left of all
pages.

\footskip Vertical distance separating the baselineof the last line of text and the baseline of thefooter.

\headheight Height of the header.
\headsep Vertical separation between header andbody.

\topmargin Extra vertical space added at the top of
the header.

\marginparpush Minimal vertical space between two
successive marginal notes (not shown in the figure).

\marginparsep Horizontal space between body andmarginal notes.

\marginparwidth Width of marginal notes.

Figure 5.1: Page layout parameters and visualization
367

5

THE LAYOUT OF THE PAGE

letterpaper
legalpaper
executivepaper
a4papera5paperb5paper

8 1/2 ×11

8 1/2 ×inches14

inches7 1/4 × 10 1/2

inches≈ 8 1/4 × 11 3/4

inches210 × 297mm

≈ 5 7/8 × 8 1/4

inches148 × 210

mm

9 7/8

inches176 × 250

mm

≈7

×

Table 5.1: Standard paper size options in LATEXMost of the layout parameters in LaTEX class files are specified in terms of the physical page size. Thus, they automatically change when \paperwidth or \paperheightis modified via one of the paper size options. Changing these two parameters in thepreamble of your document does not have this effect, because by then the values forthe other parameters are already calculated.
Standard-conforming Device Independent File Format (DVI) drivers place theOne-inch default
referencepoint for TEX one inch down and to the right of the upper-left corner of themargins
paper. These one-inch offsets are called driver margins.1 The reference point can beshifted by redefining the lengths \hoffset and \voffset . By default, their values
are zero. In general, the values of these parameters should never be changed. They
provide, however, a convenient way to shift the complete page image (body, header,footer, and marginal notes) on the output plane without disturbing the layout. The
driver margins are inherited from TEX and are not needed in LaTEX’s parameterizationof the page layout. A change to \topmargin shifts the complete text vertically, whilechanges to \oddsidemargin and \evensidemargin shift it horizontally.
To make sure that the reference point is properly positioned, you can run the test
file testpage.tex (by Leslie Lamport, reimplemented by Rainer Schöpf) through
LaTEX and the DVI driver in question. The resulting output page shows the position of
the reference point with respect to the edges of the paper.

5.2 Changing the layout
When you want to redefine the value of one or more page layout parameters, the\setlength and \addtolength commands should be used. It is important to keep

Change in mind that changes to the geometrical page layout parameters should be made only
parameters onlyin the preamble in class or package files and/or in the preamble (i.e., before the \begin{document}command). Although changing them mid-document is not absolutely impossible,
it most likely produces havoc, due to the inner workings of TEX, which involve a
number of subtle dependencies and timing problems. For example, if you changethe \textwidth , you might find that the running header of the previous page ischanged.
1 These one-inch offsets are the reason why some of the values in Figure 5.1 are negative.

368

C H A P T E R

6Tabular Material
6.1 Standard LATEX environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.2 array — Extending the tabular environments. . . . . . . . . . . . . . . . .
6.3 Calculating column widths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.4 Multipage tabular material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.5 Color in tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.6 Customizing table rules and spacing . . . . . . . . . . . . . . . . . . . . . . .
6.7 Other extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.8 Footnotes in tabular material . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6.9 keyvaltable — Separating table data and formatting . . . . . . . . . . . . .
6.10 tabularray — Late breaking news . . . . . . . . . . . . . . . . . . . . . . . . .

432
437
446
456
466
467
476
491
494
504

Data is often most efficiently presented in tabular form. TEX uses powerful primitives
for arranging material in rows and columns. Because they implement only a low-level,
formatting-oriented functionality, several macro packages have been developed thatbuild on those primitives to provide a higher-level command language and a moreuser-friendly interface. In Standard LaTEX, two types of environments for constructing
tables are provided. Most commonly the tabular environment or its math-mode
equivalent, the array environment, is used. However, in some circumstances thetabbing environment might prove useful.
Tables typically form large units of the document that must be allowed to “float”
Tables contained
so that the document may be paginated correctly. The environments described in this within floating
chapter are principally concerned with the table layout. To achieve correct pagination environments
they are often used within the table environment described in Chapter 7. Exceptions
are the environments for multipage tables described in Section 6.4, which should
never be used in conjunction with the LaTEX float mechanism. Be careful, however,not to confuse the tabular environment with the table environment. The former
allows material to be aligned in columns, while the latter is a logical document

6

TABULAR MATERIAL

element identifying its contents as belonging together and allowing the material to befloated jointly. In particular, one table environment can contain several tabular
environments.
After taking a quick look at the tabbing environment, this chapter describes
the extensions to LaTEX’s basic tabular and array environments provided by thearray package. This package offers increased functionality, especially in terms of amore flexible positioning of paragraph material, a better control of inter-column andinter-row spacing, and the possibility of defining new preamble specifiers. Several
packages build on the primitives provided by the array package to provide specificextra functionality. By combining the features in these packages, you are able toconstruct complex tables in a simple way. For example, the tabularx and tabulary
packages provide extra column types that allow table column widths to be calculated
automatically.
Standard LaTEX tabular environments do not produce tables that may be broken
over a page. We give several examples of multipage tables using the supertabular ,longtable , and xltabular environments provided by the similarly named packages. We then briefly look at the use of color in tables and at several packages that give
finer control over rules, and the spacing around rules, in tables. Next, we discuss table
entries spanning multiple rows, created via the multirow package, and packages thatprovide new column specifiers for special occasions, such as dcolumn and fcolumn,
which provide mechanisms for aligning columns of figures on a decimal point.
We also discuss the use of footnotes in tables. The threeparttable package provides a convenient mechanism to have table notes and captions combined with atabular layout.
The final section discusses the very interesting keyvaltable package that offers
a completely different approach to inputting table data. In many cases it is superior
to the traditional methods. It makes use of the other packages, e.g., xltabular, as its
backend and so understanding their concepts and mechanisms is nevertheless useful.
Mathematically oriented readers should consult the chapter on advanced mathematics, especially Section 11.2 on page →II 131, which discusses the alignment
structures for equations.

6.1 Standard LATEX environments
Standard LaTEX has two families of environments that allow material to be lined
up in columns — namely, the tabbing environment and the tabular and arrayenvironments. The main differences between the two kinds of environments are:
• The tabbing environment is not as general as the tabular environment. It canbe typeset only as a separate paragraph, whereas a tabular environment can beplaced anywhere in the text or inside mathematics.
• The tabbing environment can be broken between pages, whereas the standard
tabular environment cannot.
• With the tabbing environment the user must specify the position of each tab

432

6.1

Standard LATEX environments

stop explicitly. With the tabular environment LaTEX can automatically determine
the width of the columns.
• Multiple tabbing environments cannot be nested, whereas tabular environments can, thus allowing complex alignments to be realized.

6.1.1 Using the tabbing environment
This section deals with some of the lesser-known features of the tabbing environment. First, it must be realized that formatting is under the complete control of
the user. Somewhat unexpectedly, when moving to a given tab stop, you always end
up at the exact horizontal position where it was defined, independently of where
the current point is. As a consequence, the current point can move backward andoverwrite previous text. The scope of declarations within rows is usually limited to
the region between tab stops, e.g., \bfseries and \itshape in the next example
stop at the next \> or \\ , respectively.
Be aware that the usual LaTEX commands for making accents, \’ , \‘ , and \= , are
Alternative names
redefined inside the tabbing environment. The accents are available by typing \a’ , for accent\a‘ , and \a= instead (or by using accented characters directly). The \- command, commands
which normally signals a possible hyphenation point, is also redefined, but thisconsideration is not so important because the lines in a tabbing environment arenever broken.
If the command \’ is used between two tab stops, then all text to the left of itis placed into the previous tab region and typeset flush right against the previous
tab stop (only separated by a distance of \tabbingsep ). The default value for\tabbingsep is set equal to \labelsep , which in turn is usually 5pt. To set text
flush right to the right margin you can use \‘ . The effect of both commands is shown
below in the next example.
There exist a few common ways to define tab stops — that is, using a line to be
typeset or explicitly specifying a skip to the next tab stop. The \kill command may
be used to terminate a line that is only used to set tab stops: the line itself is not
typeset. The following example demonstrates this and shows the redefinition of tab
stops on the fourth line.

6-1-1

one
one

two
two

one

again one éè

new tab pos. two
one
two

three fourthreeflushed rightsame pos.
////// overprint
three four\begin{tabbing}First Real Tab Stop \= Second \= Third \=\kill
one \> two \> three \> four\\
\bfseries one \> \itshape two\\[5mm]one \> again one \’ \a’{e}\a‘{e}\> three \‘ flushed right \\[5mm]new tab pos. \= two \> same pos.
\> //////
overprint \\one \> two \> three \> four\\\end{tabbing}If you use the above accent commands within the definition of a command that
may be used inside a tabbing environment, you must use the \a. . . forms because

433

6

TABULAR MATERIAL

the standard accent commands such as \’ are interpreted as tabbing commands,
as shown below. Fortunately, LaTEX now accepts UTF-8 input so that you can use theaccented letter directly, instead of entering them as 7-bit input.

Tab one Tab two Tab three
7-bitcaf e (bad) café
UTF-8 caféor café\newcommand\badcafe{caf\’e (bad)}\newcommand\goodcafe{caf\a’e}\newcommand\greatcafe{café}\begin{tabbing} Tab one \= Tab two \= Tab three\\
7-bit \> \badcafe\> \goodcafe \\UTF-8 \> \greatcafe \> or café\end{tabbing}

6-1-2

The tabbing environment is most useful for aligning information into columns
whose widths are constant and known. The following example is from Table A.1 on
page →II 652:

pc Pica = 12pt
cc Cicero = 12dd
cm Centimeter = 10mm

\newcommand\lenrule[1]{\makebox[#1]{%\rule{.4pt}{4pt}\hrulefill\rule{.4pt}{4pt}}}\begin{tabbing}
dd\quad \= \hspace{.55\linewidth} \= \killpc \> Pica = 12pt\> \lenrule{1pc} \\cc \> Cicero = 12dd\> \lenrule{1cc} \\cm \> Centimeter = 10mm \> \lenrule{1cm} \\\end{tabbing}

6-1-3

6.1.2 tabto — An alternative way to tab stops
As an alternative to the standard tabbing environment Donald Arseneau developed
the tabto package that offers a set of commands for moving to tab positions that canbe used within normal text, list environments, etc., without the need to be confined ina special environment.

\tabto{length}\tabto*{length}

The \tabto command moves to a position length away from the left margin (where
list indentations count as part of the margin). If the text on the current line is alreadypast the desired position, the command starts a new line and then moves to the rightpoint. In contrast, \tabto* always stays in the current line and performs backspacing
if we are past the desired target point; that is, it may result in overprinting of text.
In the next example “T1” and “T2” are placed at tab positions reachable in thecurrent line, while both “T3” and “T4” jump to the next line because in each case weare already past the target position. Note that “T5” ends up before “T4” due to thefact that we used \tabto* here.

Lorem ipsum dolor sit amet, consectetuer
adipiscing elit.
T1
T2
T3 Ut purus elit, vestibulum ut, placerat ac, adipiscing vitae, felis.
T5
T4

434

\usepackage{lipsum,tabto}\lipsum[1][1] \tabto{3cm}T1 \tabto{4cm}T2\tabto{3cm}T3 \lipsum[1][2] \tabto{4cm}T4\tabto*{2cm}T5

6-1-4

C H A P T E R

7Mastering Floats
7.1 An overview of LATEX’s float concepts . . . . . . . . . . . . . . . . . . . . . . .
7.2 Float placement control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.3 Extensions to LATEX’s float concept . . . . . . . . . . . . . . . . . . . . . . . . .
7.4 Controlling the float caption . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7.5 Key/value approaches for floats and subfloats. . . . . . . . . . . . . . . . .

506
519
528
538
560

Documents would be easier to read if all the material that belonged together was neversplit between pages. However, this is often technically impossible, and TEX, by default,
splits textual material between two pages to avoid partially filled pages. Nevertheless,when this outcome is not desired (as with figures and tables), the material must be“floated” to a convenient place, such as the bottom or the top of the current or next
page, to prevent half-empty pages.
This chapter shows how “large chunks” of material can be kept conveniently on
the same or a nearby page by using a float object. We begin by introducing the general
concepts through which LaTEX handles float objects and the parameters that define
how LaTEX typesets its basic figure and table float environments and describe someof the packages that make it easy to control float placement (Section 7.2).
We then continue by explaining how you can define and use your own floating environments (Section 7.3.1) or, conversely, how captioning commands can beused to enter information into the list of figures and tables for nonfloating material (Section 7.3.2). Then methods for rotating the content of a float are described(Section 7.3.3). It is often visually pleasing to include a “picture” inside a paragraph,with the text wrapping around it. Some package authors have tried their hand on thisdifficult topic, and in Section 7.3.4 we look at one of them in some detail.
The fourth section addresses the problem of customizing captions. There is arecognized need to be able to typeset the description of the contents of figures andtables in many different ways. This includes specifying subfigures and subtables, eachwith its own caption and label, inside a larger float.

7

MASTERING FLOATS

In the final section of this chapter we then look at two recent packages that offer amodern key/value approach to the float topic and attempt to bridge the gaps between
the different packages introduced in the earlier sections. While both attempt to be
fairly comprehensive, they have a different focus, which is why we describe both toenable you to make an educated decision based on the requirements of the job.
Many float-related packages have been developed over the years, unfortunately
often with incompatible concepts and syntax, so there is no point discussing them all
here. In fact, the packages that we describe often feature quite a few more commands
than we are able to illustrate. Our aim is to enable you to make an educated choice
and to show how a certain function can be obtained in a given framework. In eachcase consulting the original documentation will introduce you to the full possibilities
of a given package.

7.1 An overview of LATEX’s float concepts
Floats are often problematic in the present version of LaTEX, because the system wasdeveloped at a time when documents contained considerably less graphical material
than they do today. Placing floats (tables and figures) works relatively well as longas the space they occupy is not too large compared with the space taken up by the
text. If a lot of floating material is present, however, then it is often the case that allmaterial from a certain point onward floats to the end of the chapter or document
unless you make some adjustments on the level of individual floats.
You can also try to fine-tune the float style parameters for a given document
but often a combination of both configuration and local adjustments is necessary toachieve the desired typesetting results.
The present section explains the background and behavior of LaTEX’s float algorithm and explains where and how you can manipulate it to serve your needs. We startwith defining the terminology and then discuss the algorithm and its configuration
possibilities. The section finishes with a look at the consequences resulting from thedesign choices made in the algorithm and how they affect the processing of yourdocuments.

7.1.1 LATEX float terminology
In this section we define the terminology used throughout the present chapter.
Float classes
Each float in LaTEX belongs to a class often referred to as its type. By default, LaTEX
knows about two classes, viz., figure and table. Further classes can be added by adocument class or by packages; this is discussed in Section 7.3.1 on page 529. The
class a float belongs to influences certain aspects of the float positioning, such as its
default placement specification (if not overridden on the float itself).
One important property of the float placement algorithm is that LaTEX neverviolates the order of placement within a class of floats. For example, if you have

506

7.1

An overview of LATEX’s float concepts

Figure 1, Table 1, Figure 2 in a document, then Figure 1 is always placed before
Figure 2. However, Table 1 (belonging to a different float class) is placed independently
and hence can appear before, after, or between the figures.
Some of the extension packages discussed in Section 7.3 make no provisions toensure this basic property, and one has to visually watch out for possible misorderings.
Where this can happen, it is explicitly remarked upon in the text.
Float areas
LaTEX knows about two float areas within a column where it can place floats: the top
area and the bottom area of the column. In two-column layout, it also knows about a
top area spanning the two columns. There is no bottom area for page-wide floats in
two-column mode.
In addition, LaTEX can make float columns and float pages, i.e., columns or pages
that contain only floats. Finally, LaTEX can place floats in-line into the text (but only if
so directed on the individual float).
Float placement specifiers
To direct a float to be placed into one of these areas, a float placement specifier canbe provided as an optional argument to the float. If no such optional argument isgiven, then a default placement specifier is used (which depends on the float class asmentioned above but usually allows the float to be placed in all areas if not subject toother restrictions).
A float placement specifier can consist of the following characters in any order:! indicates that some of the restrictions that normally apply should be ignored(discussed later)

h
t
b
p

indicates that the float is allowed to be placed in-line (“here”)
indicates that the float is allowed to go into a top area
indicates that the float is allowed to go into a bottom area
indicates that the float is allowed to go on a float page or column area

The order in which these characters are put in the optional argument does not
influence how the algorithm tries to place the float! The precise order is discussed on
page 509. This is one of the common misunderstandings, for instance when people
think that bt means that the bottom area should be tried first. Also note that if a
letter is not present, then the corresponding area is not tried at all.
Float algorithm parameters
There are about 20 parameters that influence the placement; for a detailed discussion
see page 510. They define• how many floats can go into a certain area,• how big an area can become,

507

7

MASTERING FLOATS• how much text there has to be on a page (in other words, how much the top
and bottom areas can occupy) and• how much space is inserted– between consecutive floats in an area, and– between the area and the text above or below.

Float reference points (aka call-outs)
A point in the document that references the float (e.g., “see Figure X”) is called a“call-out”, and the float body should be placed close to the (main) call-out, because
its placement in the document affects the placement of the float in the output anddetermines when LaTEX sees the float for the first time. It is important to understandthat if a float is placed in the middle of a paragraph, the reference point for thealgorithm is the next line break, or page break, in the paragraph that follows theactual placement in the source.
For technical and practical reasons it is usually best to place all floats between
paragraphs (i.e., after the paragraph with the call-out), even if that makes the call-out
and reference point slightly disagree.

7.1.2 Basic behavioral rules of LATEX’s float mechanism
With this knowledge, we are now ready to delve into the algorithm’s behavior. First
we have to understand that all of LaTEX’s typesetting algorithms are designed to avoid
any sort of backtracking. This means that LaTEX reads through the document source,
formats what it finds, and (more or less) immediately typesets it. The reasons for thisdesign choice were to limit complexity (which is still quite high) and also to maintainreasonable speed (remember that this is from the early eighties).
For floats, this means that the algorithm is greedy; i.e., the moment it encounters
a float, it immediately tries to place it and, if it succeeds, it never changes its decision.
This means that it may choose a solution that could be deemed inferior in light ofdata received later.
For example, if a figure is allowed to go to the top or bottom area, LaTEX may
decide to place this figure in the top area. If this figure is followed by two tables thatare allowed to go only to the top, these tables may not fit anymore. A solution that
could have worked in this case (but was not tried) would have been to place the figurein the bottom area and the two tables in the top area.

The basic sequence when placing floats
Here is the basic sequence the algorithm runs through:• If a float is encountered in the source document, LaTEX attempts to place it
immediately according to its rules (detailed later);• if this succeeds, the float is placed, and that decision is never changed;508

C H A P T E R

8Graphics Generation andManipulation
8.1 LATEX’s image loading support . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2 Manipulating graphical objects in LATEX . . . . . . . . . . . . . . . . . . . . . .
8.3 Producing (fairly) portable line graphics . . . . . . . . . . . . . . . . . . . . .
8.4 Flexible boxes for multiple purposes . . . . . . . . . . . . . . . . . . . . . . .
8.5 tikz — A general-purpose graphics system . . . . . . . . . . . . . . . . . . .

576
587
602
614
631

TEX probably has the best algorithms for formatting paragraphs and building pages
from them. But in this era of ever-increasing information exchange, most publications
do not limit themselves to text — the importance of graphical material has growntremendously. TEX by itself does not address this area, as it deals only with positioning(glyph) boxes on pages. Knuth, however, provided a hook for implementing “features”
that are not available in the basic language, via the \special command. The latter
command does not affect the output page being formatted,1 but TEX will put thematerial, specified as an argument to the \special command, literally at the current
point in the output, e.g., the .dvi file. The program that displays or prints that output
then has to interpret the received information and load the graphic or execute theappropriate graphic operation. Engines that can directly produce Portable Document
Format (PDF) offer other primitives to add raw data to the PDF output, but conceptually
the process is the same: it is the backend that has to deal with the graphics.
The main problem with this approach was that different backends provide different methods and interfaces so that any TEX source file that used \special directly
became nonportable, working only with specific output devices or printers.
1 In certain situations the \special command may change the formatting because it can produce
an additional breakpoint or generate an extra space — thus not a perfect approach.

8

GRAPHICS GENERATION AND MANIPULATIONThis problem was largely resolved with LaTEX 2ε , which provided a generalized
driver-independent interface to include external graphic material and to scale androtate LaTEX boxes.1 This interface is the subject of Section 8.1. It exists in the formof two implementations: the graphics package offers a simple interface, while thegraphicx package provides a convenient key/value interface with additional features.
Free-standing scaling and rotation and other manipulations are the subjects of Section 8.2.
A similar abstraction for line graphics was announced at the same time, but it
took more than a decade until it was finally implemented. This and some applications
thereof are discussed in Section 8.3. This section also talks about special graphic
languages and as one useful application thereof generating QR codes with LaTEX.
Section 8.4 is then devoted to tcolorbox, a very comprehensive package for
producing boxed material.
We conclude the chapter by taking a brief look at the powerful tikz package.
There is no way we can do justice to this package, which builds a universe of its own —one could easily devote a whole book to it. Thus, all we try here is to give you an
introduction to its basics and give a few teasers to show what it is capable of, but
direct you to its documentation (more than a thousand pages) if you get hooked.

8.1 LATEX’s image loading support
Since the introduction of LaTEX 2ε in 1994, LaTEX has offered a uniform syntax forincluding every kind of graphics file that can be handled by the different drivers. In
addition, all kinds of graphic operations (such as resizing and rotating) as well as
color support are available.
These features are not part of the LaTEX kernel but rather are provided by thestandard, fully supported color, graphics, and graphicx extension packages. As the
TEX program does not have any direct methods for graphic manipulation, the packages
have to rely on features supplied by the “driver” used to print the Device Independent
File Format (DVI) file or by the features of the extended engines pdfTEX, XETEX, or
LuaTEX that can produce PDF output directly. Unfortunately, not all drivers or PDF
engines support the same features, and even the internal method of accessing these
extensions varies among them. Consequently, all of these packages take options suchas dvips or pdftex to specify which external driver or engine is being used. Throughthis method, any unavoidable device-dependent information is localized in a single
place, the preamble of the document. However, each TEX distribution when installed
sets up suitable detection methods and defaults (e.g., if the program pdflatex is used,then most likely the correct driver option is pdftex ), so in practice most documentscompile correctly without the need to specify any such option.
The packages graphics and graphicx can both be used to scale, rotate, and reflect
LaTEX material or to include graphics files prepared with other programs. The difference
between the two is that graphics uses a combination of macros with a “standard” or
TEX-like syntax, while the “extended” or “enhanced” graphicx package presents a key/
1 A generalized package for color is also available; see the LAT X Manual [106] for more details.

E

576

8.1

LATEX’s image loading support

value type of interface for specifying optional parameters to the \includegraphics
and \rotatebox commands.

8.1.1 Options for graphics and graphicx
When using LaTEX’s graphics packages, the necessary space for the typeset material after performing a file inclusion or applying some geometric transformation is reservedon the output page. It is, however, the task of the device driver (e.g., dvips, dvipdfmx,
pdftex, etc.) to perform the actual inclusion or transformation in question and toshow the correct result. Because different drivers require different code to carry out
an action like rotation, one has to specify the target driver as an option to the graphics
packages — for example, option dvips if you use one of the graphics packages withTom Rokicki’s dvips program, or option pdftex if the graphics packages are usedwith the pdfTEX engine.
Fortunately, however, the package is usually capable of figuring out the correct
driver automatically, in particular when generating a PDF with pdfTEX, XETEX, or LuaTEX.
In all other cases it assumes dvips, which is often, but not always, correct. Only inthe latter case does one need to explicitly provide a driver option. The full list of
supported drivers (and their restrictions, if any) is listed in the graphics package
documentation if you ever run into a case where the default does not work.
In addition to the driver options, the packages support some options controllingwhich features are enabled (or disabled):

draft Suppress all “special” features, such as including external graphics files in the
final output. The layout of the page is not affected, because LaTEX still reads
the size information concerning the bounding box of the external material.
This option is of particular interest when a document is under development
and you do not want to download the (often huge) graphics files each time
you work on it. When draft mode is activated, the picture is replaced by abox of the correct size containing the name of the external file.

final The opposite of draft . This option can be useful when, for instance, “draft”
mode was specified as a global option with the \documentclass command(e.g., for showing overfull boxes), but you do not want to suppress the graphics
as well.

hiresbb In PostScript graphics look for bounding box comments that are of theform %%HiResBoundingBox (which typically have real values) instead of thestandard %%BoundingBox (which must have integer values).
Of lesser importance these days are options that disable features because ofrestrictions in the output driver. With hiderotate you prevent showing rotatedmaterial (for instance, when the previewer cannot rotate material and produces error
messages), and hidescale does the same for scaled material.
With the graphicx package, these options are also available locally as keys forindividual \includegraphics commands.

577

8

GRAPHICS GENERATION AND MANIPULATION

8.1.2 The \includegraphics syntax in the graphics package
With the graphics package, an image file can be included by using the following
command:\includegraphics*[llx,lly ][urx,ury ]{file}
If the [urx,ury ] argument is present, it specifies the coordinates of upper-right cornerof the image as a pair of TEX dimensions. The default units are big (PostScript) points;
thus, [1in,1in] and [72,72] are equivalent. If only one optional argument is given,
the lower-left corner of the image is assumed to be located at [0,0] . Otherwise,[llx,lly ] specifies the coordinates of that point. Without optional arguments, the sizeof the graphic is determined by reading the external file (containing the graphics itself
or a description thereof; see below).
The starred form of the \includegraphics command “clips” the graphics
image to the size of the specified bounding box. In the normal form (without the * ),any part of the image that falls outside the specified bounding box overprints thesurrounding text.
The examples in the current and next sections all use a small graphic showing
the LaTEX hummingbird logo. It is a small PDF graphic with a width of 100pt and aheight of 80pt. Being a typical .pdf graphic, the lower-left coordinate of its boundingbox is at 0 0 , and the top-right corner is at [98,76] in big points (bp ), which means
it is slightly wider than high.
In the examples we always embed the \includegraphics command in an\fbox (with a blue frame and zero \fboxsep ) to show the space that LaTEX reserves
for the included image. In addition, the baseline is indicated by the horizontal rules
produced by the \HR command, defined as an abbreviation for \rule{1em}{0.4pt}.
The first example shows the inclusion of the latex-logo.pdf graphic at its
natural size. We have omitted the file extension, but the graphics is found neverthelessby searching for the file, adding supported extensions one after another until a matchis made.1\usepackage{graphics,color}\newcommand\HR{\rule{1em}{0.4pt}}\newcommand\bluefbox[1]{\textcolor{blue}{\setlength\fboxsep{0pt}%\fbox{\textcolor{black}{#1}}}}

L

R

L\HR\bluefbox{\includegraphics{latex-logo}}\HR R

Next, we specify a box that corresponds to a part of the picture (and an area
outside it) so that some parts fall outside its boundaries, overlaying the material
1 The advantage is that your document may work with different device drivers supporting distinct

graphics formats, if you supply both formats together with your document. The disadvantage is thatyou make LaTEX work harder in trying to find a suitable graphics file.

578

8-1-1

C H A P T E R

9Font Selection and
Encodings
9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.2 Understanding font characteristics . . . . . . . . . . . . . . . . . . . . . . . .
9.3 Using fonts in text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.4 Using fonts in math. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.5 Standard LATEX font support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.6 fontspec — Font selection for Unicode engines . . . . . . . . . . . . . . . .
9.7 The low-level NFSS interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.8 Setting up new fonts for NFSS . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.9 LATEX’s encoding models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

648
652
658
676
683
705
730
740
754

In this chapter we describe the font selection and encoding models of LaTEX, known
as NFSS (New Font Selection Scheme) and the packages and commands to deal withencoding issues. Given that NFSS was first introduced about thirty years ago, it is, ofcourse, no longer really new. The last decade, however, showed a number of exciting
new developments, so this chapter, compared to the one in the previous edition of
the book, nevertheless contains a lot of new and changed material.
We start with a short introduction to the history of font usage in different TEX
engines. This is then followed by a section discussing font characteristics in generaland introducing the major attributes used in LaTEX for orthogonal font switching.
We then describe the use of the high-level interface — that is, the commands a user
normally has to deal with. This includes commands used in normal text (Section 9.3),
special features for use in mathematical formulae (Section 9.4), and an overview
of basic support packages for NFSS — those being distributed together with LaTEX(Section 9.5).
Section 9.6 is solely devoted to the details of the fontspec package, the frontend
to NFSS for use in the Unicode engines XETEX and LuaTEX.

9

FONT SELECTION AND ENCODINGSThe final sections then describe the low-level interfaces that are useful whendefining complex new commands and that are important when new fonts are to bemade available in LaTEX. Here you find low-level commands for changing individual fontattributes (Section 9.7), commands for setting up new fonts with LaTEX (Section 9.8),
and a discussion of LaTEX’s encoding models for text and math (Section 9.9).

9.1 Introduction
9.1.1 The history of LATEX’s font selection scheme (NFSS)
When TEX was developed in 1979, only a dozen fonts were set up for use with theprogram. This situation had not greatly changed five years later, when LaTEX was firstreleased. It was thus quite natural that LaTEX’s font selection scheme followed the plain
TEX concept with the addition of size-changing commands that allowed typesetting inten predefined sizes.
As a result, LaTEX’s font selection was far from general because the font commands
were not changing font attributes but exchanged one font with another one. For
instance, when, say, the now obsolete command \bf was used inside emphasized
text, the result was not a bold italic font, as normally desired, but rather a plain
roman bold font. Furthermore, the original release had another major drawback: thecorrespondence tables between font commands and fonts were hardwired into LaTEX
so that replacing the default fonts was a difficult, if not impossible, task.
Since that time low-priced laser printers became available, and simultaneously
a large number of font families from PostScript and other font formats appeared.
But, unfortunately, because of the LaTEX font selection model, there was no easyand standard method for integrating these new fonts into LaTEX — typesetting withLaTEX meant typesetting in Computer Modern on almost all installations. Of course,
individual fonts could be loaded, but they would not work with the size commands
nor were they otherwise integrated, so it was extremely complicated to typeset awhole document in a different font family.
This unsatisfactory situation was finally resolved in 1989 with the release of
the New Font Selection Scheme (NFSS) [152] written by Frank Mittelbach and Rainer
Schöpf, which became widely known after it was successfully used in AMS-LaTEX(see Chapter 11). This system contains a generic concept for varying font attributes
individually and for integrating new font families easily into an existing LaTEX system.
The concept is based on five attributes that can be defined independently to accessdifferent fonts, font characteristics, or font families. To implement it, some of the
LaTEX commands were redefined, and some new commands were added.
In 1994 NFSS became the official standard in the then newly released LaTEX 2ε . It
has now been in worldwide use for more than thirty years, proving the code to bestable, successful, and most importantly flexible enough to support further advances
in font technology and use.
However, in the last decade new requirements appeared that were not easily
supported with the original NFSS design and so some extensions in the form of
additional support packages appeared.

648

9.1

Introduction

For pdfTEX two important ones have been mweights by Bob Tennent and fontaxes
by Andreas Bühmann and Michael Ummels, both extending the attribute handlingof NFSS. Neither package is intended for direct usage but normally used within fontsupport packages, such as those discussed in Chapter 10. In 2020 a large portion of
their functionality has been integrated into NFSS so that it is now generally available.
The situation for Unicode engines is different. With the fontspec package by Will
Robertson a new frontend for font loading is offered for use in XETEX and LuaTEX. This
frontend allows one to access all kind of font features available with OpenType or
TrueType fonts. It then generates the necessary information for NFSS on the fly — thus
under the hood NFSS is still the font selection machinery. The package is discussed indetail in Section 9.6.

9.1.2 Input and output handling in TEX systems over the years
When TEX was originally developed in 1979, computers used 7-bits to encode input
characters, which allows for a direct representation of a maximum of 128 characters,i.e., Latin upper and lowercase base characters, digits, and a few symbols. Any othercharacter had to be represented in the form of a command or a sequence of commands;e.g., \ss for ß or \^\j for ȷ̂, etc.
This certainly allowed inputting text in most Latin-based languages (though alTE X79 largely
ready a bit inconvenient) where the need for using commands in the input is still restricted to English
infrequent. Already then there were problems; e.g., hyphenation would not work
for words containing diacritics. However, that approach clearly failed for languages
with a totally different set of characters, where essentially every character would be
represented by a command if we assume that the input can represent only ASCII characters directly. For example, the Russian text for “on the next page” (на следующей
странице) would have to be written as\cyrn\cyra\ \cyrs\cyrl\cyre\cyrd\cyru\cyryu\cyrshch\cyre\cyrishrt\ \cyrs\cyrt\cyrr\cyra\cyrn\cyri\cyrc\cyre
Clearly, no one wants to type text like this on a regular basis.
Fonts in TEX79 used 7-bits as well, i.e., contained a maximum of 128 glyphs
and for text fonts the glyph positions matched the ASCII code used at input. In
other words, there was a one-to-one correspondence between the number encoding acharacter on input and the number representing the glyph position in the fonts. For
example, the seven bits 1000001 (decimal 65) in a file were interpreted by an editor as
the character A and when processed by TEX the program fetched the glyph in position
65 in the current font, which then happened to be “A”. For the class of documentsthat just need basic Latin characters this worked well and was very fast.
The 8-bit days
Computers then evolved and started to use 8-bits for encoding data. With it TEX
The 8-bit operating
evolved too and supported 8-bit input and fonts (TEX82 and later TEX3.0). However, systems
there was now a problem: different computers used different “code pages”; that is,

649

9

FONT SELECTION AND ENCODINGSThe input encoding
concept

The output encoding
concept

they interpreted the bytes in input files in different ways depending on the operating
system’s regional settings or other criteria. Thus, while the lower 128 bytes wereusually identical, in many code pages the upper half varied greatly, making dataexchange difficult, if not outright impossible.
There was nothing inside a file that would explicitly tell how to interpret the
8-bit numbers inside. Thus, suddenly files written on one computer got partiallyscrambled when processed on a different one unless you knew (and could tell theprocessing software) under which assumption — that is, under which code page — thefile was written.
In LaTEX 2ε this problem was resolved by introducing the package inputenc thatallows one to explicitly state under which input encoding the remainder of the fileshould be interpreted by LaTEX. It effectively added the missing information about thefile encoding to the source so that LaTEX could use it even when running under anoperating system that would normally use a different code page.
The inputenc package works by interpreting the 8-bit numbers present in the file
(representing the characters) and mapping them to an “internal LaTEX representation”,
which uniquely (albeit on a somewhat ad hoc basis) covers all characters representablein LaTEX. For further processing, such as writing to some auxiliary file, LaTEX exclusively
uses this internal representation, thereby avoiding any possible misinterpretation.
And there was (and unfortunately is) a second problem: TEX still assumes bydefault that input characters can be directly mapped to corresponding font slots.
As a consequence, developing 8-bit fonts that use all possible slots would requiredifferent fonts for different code pages. For example, if your keyboard contained a key
for the Euro symbol (€) and your computer used the Windows code page cp-1252 ,then pressing this key generated the code 80 while it generated 164 if your computer
happened to use the code page ISO-889-15 . Thus, if such codes define the glyph
position in the fonts, then we need different fonts in each case, one with the Eurosymbol in slot 80 and another where it is in 164.
So the inputenc package solves half of the problem, because once applied itcorrectly interprets the bytes in the input file and LaTEX then sees the command\texteuro in both cases. But then LaTEX needs to know which slot \texteuro has
to access to fetch the glyph (and possibly even from which font).
All this is achieved in LaTEX through the concept of output encodings, which
map the LaTEX internal character representations to appropriate glyph positions or toglyph-building actions depending on the actual glyphs available in the font used fortypesetting. This is where the fontenc package comes into play that was introduced
at the same time as inputenc. Each font usable with LaTEX is supposed to implement a
specific “named” font encoding, and with fontenc you tell LaTEX where to find glyphs
in such font encodings.
The Unicode days
The next level of evolution was the introduction of Unicode-based operating systems.
They use UTF-8, which is a variable-length encoding that represents Unicode charactersin one to four octets. In this case the TEX ecosystem only partially followed. The
original program, as maintained by Donald Knuth (TEX3), as well as the variant pdfTEX

650

The LaTEX Companion
Third Edition – Part II
Frank Mittelbach
LATEX Project, Mainz, Germany

Ulrike Fischer
LAT X Project, Bonn, Germany
EWith contributions by
Javier Bezos, Johannes Braams, and Joseph Wright

Boston • Columbus • New York • San Francisco • Amsterdam • Cape Town
Dubai • London • Madrid • Milan • Munich • Paris • Montreal • Toronto • Delhi • Mexico CitySão Paulo • Sydney • Hong Kong • Seoul • Singapore • Taipei • Tokyo

This picture of Sebastian was taken 2007 in Cinque Terre.

I dedicate this edition to all my friends in the TEX world and in particular
to the memory of my good friend Sebastian Rahtz (1955–2016),
with whom I spent many happy hours discussing parenting, literature,
LaTEX, and other important aspects of life [146].

C H A P T E R

10Text and Symbol Fonts
10.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
10.2 Samples of larger font families . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
10.3 Humanist (Oldstyle) serif fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
10.4 Garalde (Oldstyle) serif fonts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
10.5 Transitional/Neoclassical serif fonts. . . . . . . . . . . . . . . . . . . . . . . . 46
10.6 Didone (Modern) serif fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
10.7 Slab serif (Egyptian) fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
10.8 Sans serif fonts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
10.9 Monospaced (typewriter) fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
10.10 Historical and other fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
10.11 Fonts supporting Latin and polytonic Greek. . . . . . . . . . . . . . . . . 106
10.12 Fonts supporting Latin and Cyrillic . . . . . . . . . . . . . . . . . . . . . . . 110
10.13 The LATEX world of symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

When we wrote the first edition of the LATEX Companion in 1994, the section on
available text fonts for LaTEX was a few pages long and listed a handful of font families.
Not because they were best in class, but because that was all that was available
including those of a somewhat dubious quality. Basically when typesetting with TEX
in those days, one could use any font as long as it was called Computer Modern.
A decade later the situation finally started to change, and it was in theory possible
to use any font available in Type 1 format [1] — but only after somewhat extensive
work preparing the necessary support files needed by TEX, in particular the font metricfiles (.tfm ) and usually virtual font files (.vf ) that reencoded the fonts to put theglyphs into the positions expected by the TEX engine. Providing these was not magic,
especially after the appearance of the fontinst program1 by Alan Jeffrey, Rowland
1 This is actually a T X file that, when processed and given the right configuration data, producedEthe necessary helper files in human-readable format. In a further step those had to be converted byexternal programs to the binary format used by TEX.

10

TEXT AND SYMBOL FONTS

McDonnell, and Lars Hellström, but it took time and effort (even if necessary only
once per font) and a good understanding of the underlying mechanisms. Thus, thenumber of available text fonts for use with TEX compared to other programs remained
severely restricted. The second edition of the book again covered all that was freely
available for LaTEX users, which amounted to fewer than two dozen font families. Of
course, the CTAN archive already then contained some further support packages fora few commercial fonts. They were not included because the packages were uselessunless you owned the particular family.
But with the third edition I faced a problem. With Unicode engines you can use
essentially any freely or commercially available font by simply specifying it in the
fontspec setup of your document. But also for the pdfTEX engine, font support exploded due to two factors: first the number of freely available fonts on the Web in
either Type 1 [1], TrueType [8], or OpenType [127] format grew enormously, andsecond a few individuals like Marc Penninga, the author of autoinst, and Bob Tennent,
Michael Sharpe, and a few others1 took the time to prepare configuration files for
Marc’s autoinst program and with the necessary further adjustments and documentation produced packages that made a huge number of those freely usable fonts
available to the LaTEX community at large.
My initial thought was to select only a few of the high-quality free fonts andlargely ignore the rest — with just a mention that you find more possibilities in yourTEX installation and on CTAN. But while working through all the font packages on
CTAN to make a selection, I realized how difficult it is to hunt for them and that most
likely any family not described in an overview remains unnoticed by the majorityof users. Furthermore, while in the early days most free fonts were of a somewhat
dubious quality, that too has now changed quite impressively for the better.
So in the end I decided to continue the tradition of offering a fairly comprehensive overview2 about today’s freely available fonts for LaTEX so that you can makean informed selection by just skimming this chapter and comparing the different
possibilities and only then look further at the package documentation of the fonts you
have chosen. You may also want to take a look at the online font catalogue maintained
by Palle Jørgensen [77].

10.1 Overview
All fonts described in this chapter are freely available and with a few exceptions are

General fontincluded in the major TEX distributions such as TEX Live or MiKTEX so that you canavailability

start using them directly. We made two exceptions and also included the commerciallyavailable Cambria fonts as well as the Lucida font families that we use in this book.
The Cambria fonts, while under a proprietary license, ship as part of Windows and

1 All package authors are acknowledged next to their work and listed in the index. There are too
many to enumerate here. However, Bob and Michael are the ones who produced the major part of thework, which I think deserves an explicit acknowledgment.
2 For the first time restricted to only high-quality or otherwise (for some reason) interesting fonts.
A heartfelt thanks to Adam Twardoch who helped me a lot with his knowledge and expertise to selectthe high-quality fonts from the huge number of freely available fonts today.

2

10.1

Overview

Office products and are therefore widely available without the need for buying an
additional license. They offer excellent math support and for that alone are worth acloser look. The Lucida families are sold by the TEX Users Group (TUG) at a special
price for members of TUG and several other user groups.1
In the open source world, “free” is a widely debated word, and some fonts are justnot “free enough” to be included in free software distributions, because their license
is somewhat restrictive, typically either forbidding modifications of the fonts (which
is most likely not any issue for the readers of this book) or disallowing commercial
usage. The latter refers to actions such as selling them or distributing them as part ofa commercial system — none of the licenses of the fonts we cover prohibit the freeuse of the fonts even if the result, say, a book like this, is then sold. Thus, this should
not pose a problem either, but of course, you should be aware that fonts you needto install “manually” have a special license, and you better check what it says if you
intend to do anything with it other than simply typesetting your texts.
Omitting high-quality fonts because of license restrictions (even if very minor) isa sensible approach, as it means that the users of the distribution can rely on the factthat everything contained is covered by one of the major free licenses and that there
are no restrictions on use and only well-known ones on modification; e.g., most LaTEX
software uses the LaTEX Project Public License (LPPL), GNU Public License (GPL), or any
other of the few major open source licenses.
But of course, it puts an additional burden on the user, as they have to manually install the fonts (besides checking the license requirements). Fortunately,
there is an easy way to integrate such font packages into your installation. At
the TEX Users Group website a script by Reinhard Kotucha is provided. It is a
simple matter of downloading the install-getnonfreefonts installer from https://www.tug.org/fonts/getnonfreefonts/ and processing it on the commandline (in a Windows, macOS, or Linux terminal window) using
texlua install-getnonfreefonts

As this is a Lua program and texlua is part of the standard distributions, this works
on any operating system, provided your user has write access to the distribution
directories. After this you have the program getnonfreefonts available on your system,
and you can invoke it with lines such as
getnonfreefonts --sys --help
getnonfreefonts --sys --lsfonts
getnonfreefonts --sys luximono
getnonfreefonts --sys --all# see the help info or# list all available fonts or# (re)install a fonts package or# (re)install all available fonts

The line first displays the program usage information and the available options;the second gives you an overview about the currently supported fonts and their
1 The set includes matching serif, sans serif, and typewriter families; a full set of fonts for use
in math; and several specialized fonts; see Table 10.11 on page 22 for an overview. They can beused with all TEX engines if both Type 1 and OpenType versions are ordered, which you can do athttps://tug.org/store/lucida/order.html.

310TEXT AND SYMBOL FONTS

state on your installation; the third installs or reinstalls such a font (or more if you
add additional font names); and the final one installs or updates all supported font
packages (which are eleven in total at the moment). Instead of --sys , you can use--user , in which case the installation is done in the user’s TEX tree instead of thesystem-wide one. However, except in a few special cases, this is the wrong thing todo, so please read https://tug.org/texlive/scripts-sys-user.html first if
you are considering using --user , because of its possibly undesirable side effects.

10.1.1 Notes on the font samples
All font families in this chapter are exhibited using the same example text to allow foreasy comparison and at the same time to show many details and possible limitationsof the fonts. The standard setup uses the following text:
Palatino 10pt/12.4pt(qpl) TeX Gyre PagellaWith a price of £148, almost anything can be found Floating In
Fields. — ¿But aren’t Kafka’s Schloß & Æsop’s Œuvres often naïve
vis-à-vis the dæmonic phœnix’s official rôle in fluffy soufflés?

In the margin we show the common name of the font (Palatino), the font size and theleading used (10/12.4pt), the NFSS family name to refer to it in parentheses (qpl), andfinally with gray background the OpenType or TrueType name to use with Unicode
engines (TeX Gyre Pagella). Depending on the length of the font names, this may be
split differently over up to four lines.
The text is not typeset justified but slightly ragged right (still allowing hyphenation as one can see in a few of the later samples; e.g., on page 34). This is done sothat the word spaces are not (or only minimally) altered from their default width.
Most examples are set in 10/12pt, which is the default in most document classes, butsometimes we use a larger leading and/or a smaller or larger font size to account for
the look and feel of the family.
The example text attempts to show different aspects of the font while still being
concise (otherwise this chapter would be even longer). It contains some bold text,
some bold and nonbold Small Capitals, a slanted word, and a few words in italics.
Above, these words are all typeset in blue. In the real samples they would be in black,unless the corresponding shape or series either is not available or is faked.
For instance, most families do not have both an italic and an oblique/slanted
shape. Sometimes it is missing, but quite often the oblique shape is really just an
alias for italics (or vice versa), which is fairly easy to see if you look at the shape of
the “a” in “naïve” and “official” and compare it to “can” in the first line. Regardless ofwhether the slanted or italic shape is missing or aliased, it is shown in blue.
The bold text is normally shown in blue only if the series is missing altogether; theexception is the Concrete family where it is faked (by aliasing it to the bold typefaceof a different font family, which is a somewhat questionable approach).
When the Small Caps text is shown in blue, half of the time it is because there
is simply no such shape in the family and in the other half because the small capitals
are faked using a scaled-down version of the uppercase letters. As explained on

4

C H A P T E R

11Higher Mathematics
11.1 Introduction to amsmath and mathtools . . . . . . . . . . . . . . . . . . . .
11.2 Display and alignment structures for equations . . . . . . . . . . . . . . .
11.3 Matrix-like environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.4 Compound structures and decorations . . . . . . . . . . . . . . . . . . . . .
11.5 Variable symbol commands . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.6 Words in mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.7 Fine-tuning the mathematical layout . . . . . . . . . . . . . . . . . . . . . .
11.8 Symbols in formulas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

128
131
153
163
180
191
194
208

Basic LaTEX offers excellent mathematical typesetting capabilities for straightforward
documents. However, when complex displayed equations or more advanced mathematical constructs are heavily used, something more is needed. Although it is possible
to define new commands or environments to ease the burden of typing in formulas,this is not the best solution. The American Mathematical Society (AMS) provides amajor package, amsmath, which makes the preparation of mathematical documents
much less time-consuming and more consistent.1 It forms the core of a collection of
packages known as AMS-LaTEX [5] and is the major subject of this chapter. A usefulbook by George Grätzer [59] also covers these packages in detail.
This chapter describes briefly, and provides examples of, a substantial numberof the many features of these packages as well as a few closely related packages; italso gives a few pointers to other relevant packages. In addition, it provides someessential background on mathematical typesetting with TEX. Thus, it covers some ofstandard LaTEX’s features for mathematical typesetting and layout and contains some
general hints on how to typeset mathematical formulas, though these are not themain aims of this chapter. It is also definitely not a comprehensive manual of goodpractice for typesetting mathematics with LaTEX. Indeed, many of the examples are
1 This package has its foundations in the macro-level extensions to T X known as A

E

MS-TEX.

11

HIGHER MATHEMATICS

offered purely for illustration purposes and, therefore, present neither good design
nor good mathematics nor necessarily good LaTEX coding.
Advice on how to typeset mathematics according to late 20th century U.S. practice
can be found in Ellen Swanson’s Math into Type [187]. Many details concerning how to
implement this advice using TEX or, equally, standard LaTEX appear in Chapters 16–18
of Donald Knuth’s The TE Xbook [84].
To use the majority of the material described in this chapter, you need to load atleast the amsmath or mathtools package in the preamble of your document. If otherpackages are needed, they are clearly marked in the examples. Detailed installation
and usage documentation is included with the individual packages.

11.1 Introduction to amsmath and mathtools

Thanks toa great guy!

Available package
options

The AMS-LaTEX project commenced in 1987, and three years later AMS-LaTEX version 1.0 was released. This was the original conversion to LaTEX of the mathematicalcapabilities in Michael Spivak’s AMS-TEX by Frank Mittelbach and Rainer Schöpf,
working as consultants to the American Mathematical Society, with assistance fromMichael Downes (1958–2003) of the AMS technical staff. In 1994, further work wasdone with David Jones. This work was coordinated by Michael Downes, and the packages have throughout been supported and much enhanced under his direction andthe patronage of the AMS.1 Initially AMS-LaTEX was a separate format, which is thereason for the separate name, but at some point, when computers got faster andfaster, the functionality was moved to the package amsmath, which could be loaded
into standard LaTEX, and the support for a separate format was dropped. Thus, thesedays speaking of AMS-LaTEX simply refers to amsmath or the AMS document classes
that evolved from that project.
In 2016 the AMS passed maintenance and control of amsmath and some of its
accompanying packages back to the LaTEX Project Team, because its math capabilities
are a core functionality of LaTEX.2
Michael Downes (1958–2003) would have been the author of this chapter when
we wrote the second edition of this book had he not died in spring 2003. Much of thechapter is based on the documentation he prepared for AMS-LaTEX; thus, what you
are reading is a particular and heartfelt tribute by its current author to the life andwork of a dear friend and colleague with whom we shared many coding adventures in
the uncharted backwaters of TEX.
A few options are recognized by the amsmath package. Most of these affectonly detailed positioning of the “limits” on various types of mathematical operators(Section 11.4.4) or that of equation tags (Section 11.2.4).
1 Some material in this chapter is reprinted from the documentation that was distributed with
AMS-LaTEX (with permission from the American Mathematical Society).
2 However, the American Mathematical Society retained maintenance and support of the AMS fonts
and the document classes amsart, amsbook, and amsproc; thus, any issue or inquiries concerningthese classes or font packages have to be taken up with their technical stuff and not the LaTEX Project
Team.

128

11.1

Introduction to amsmath and mathtools

The following three options are often supplied as global document options, seton the \documentclass command. They are, however, also recognized when theamsmath package is loaded with the \usepackage command.

reqno(default)

leqno

Place equation numbers (tags) on the left.1

fleqn

Position equations at a fixed indent from the left margin rather than centered in the text column.

Place equation numbers (tags) on the right.

For historical reasons some components of the amsmath package exist as separate
Available
packages so that they can be loaded on their own — a feature that was essential when subpackages
computer memory was tight and just loading a large package like amsmath was taking
considerable time. These days the advice is to always load amsmath and not try to
determine what is needed and what is not.
amsopnProvides \DeclareMathOperator for defining new operator names such
as \Ker and \esssup .

amstext Provides the \text command for typesetting a fragment of text in thecorrect type size.
The following packages, providing functionality additional to that in amsmath, Extension packages
must be loaded explicitly; they are listed here for completeness.
amscd

Defines some commands for easing the generation of commutative diagrams
by introducing the CD environment (see Section 11.3.5 on page 159). Thereis no support for diagonal arrows.

amsthm Provides a method to declare theorem-like structures and offers a proof
environment. It is discussed in Section 4.1.4 on page →I 281.
amsxtra Provides certain odds and ends that are needed for historical compatibility, such as \fracwithdelims , \accentedsymbol , and commands for
placing accents as superscripts.
upref

Makes \ref print cross-reference numbers in an upright/roman font regardless of context.

The principal documentation for these packages is the User’s Guide for theamsmath Package (Version 2.1) [5], which is part of the LaTEX distribution.
The amsmath package is very comprehensive and provides most of what is needed
mathtools — A
when attempting serious mathematical typesetting. It is, however, rather static; i.e., drop-in replacement
it has not seen a lot additions (or fixes) since its initial development in the nineties. for amsmath
Because of this, several smaller packages, some of which we discuss in this chapter,
have been developed to add one or the other missing feature. In addition, there is
1 When using one of the AMS document classes, the default is leqno .

129

11

HIGHER MATHEMATICSThe AMS-LATEX
document classes

The AMSfonts
collection

also the mathtools package by Morten Høgholm now maintained by Lars Madsen thathas been explicitly developed to offer a replacement for amsmath. It provides allfeatures of amsmath (including the support for all of its package options), augments
it with several new features, and fixes a number of known bugs in amsmath. We give
examples of its extended functionality in the appropriate places, and if you intend touse any of this, you should load mathtools in place of amsmath.
As already mentioned, the three document classes amsart, amsproc, and amsbook
from the original AMS-LaTEX collection are still maintained by the American Mathematical Society. They correspond to LaTEX’s article, proc, and book, respectively, andare designed to be used in the preparation of manuscripts for submission to the AMS.
However, given that they are part of every LaTEX distribution, nothing prohibits theiruse for other purposes. In fact, they are often used as the base class for other journals
instead of the standard LaTEX classes.
With these class files the amsmath package is automatically loaded so that you
can start your document simply with \documentclass{amsart} . These classes are
not covered in this book because they provide an interface similar to that provided by
the LaTEX standard classes; refer to [4] for details of their use.
Some of the material in this chapter refers to another collection of packages
from the American Mathematical Society, namely, the AMSfonts distribution. These
packages, listed below, set up various fonts and commands for use in mathematicalformulas.
amsfonts Defines the \mathfrak and \mathbb commands and sets up the fonts
msam (extra math symbols A), msbm (extra math symbols B and blackboard bold),eufm (Euler Fraktur), extra sizes of cmmib (bold math italic and bold lowercase
Greek), and cmbsy (bold math symbols and bold script) for use in mathematics.
amssymb Defines the names of the mathematical symbols available with the
AMSfonts collection. These commands are discussed in Section 11.8. The package
automatically loads the amsfonts package.
eufrak Sets up the fonts for the Euler Fraktur letters (\mathfrak ), as discussed in
Section 12.3.3. This alphabet is also available from the amsfonts package.
eucal Makes \mathcal use the Euler script instead of the usual Computer Modern
script letters; see Section 12.3.3 for details.

The above packages and fonts are maintained by the American Mathematical Society,and the principal piece of documentation for both is the User’s Guide to AMSFonts
Documentation is  Version 2.2d [2]. However, the distribution is now in version 3, while the documentation
somewhat dated,
is still describing version 2.2d. Though most of it is still accurate and relevant, there isbut still relevant one area where the guide talks about METAFONT (bitmapped) versus Type 1 (outline)
fonts that you need to ignore. These days only the Type 1 fonts are distributed, so thispart is giving incorrect advice. In particular, the psamsfonts option described there
should no longer be used, because it is no longer recognized by all of the packages
and produces either a warning or an error.

130

C H A P T E R

12Fonts in formulas
12.1 The world of (Latin) math alphabets . . . . . . . . . . . . . . . . . . . . . . .
12.2 Making it bold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.3 Traditional math font setup through packages. . . . . . . . . . . . . . . .
12.4 unicode-math — Using Unicode math fonts . . . . . . . . . . . . . . . . . .
12.5 A visual comparison of different math setups . . . . . . . . . . . . . . . .

226
235
238
253
261

For most symbols in a formula, the font used for a glyph cannot be changed by a fontdeclaration as it can be in text. Indeed, there is no concept of, for example, an italicplus sign or a small capital less than sign.
One exception involves the letters of the Latin alphabet, whose appearance canbe altered by the use of math alphabet identifier commands such as \mathcal . The
commands provided by standard LaTEX for this purpose are discussed in Section 9.4;
in the first section of this chapter we introduce a few more and discuss their use insome detail.
Another exception relates to the use of bold versions of arbitrary symbols to
produce distinct symbols with new meanings. This potentially doubles the number ofsymbols available, as boldness can be a recognizable attribute of a glyph for nearly
every shape: depending on the font family, even “<” is noticeably different from “<”.
Although there is a \mathbf command, the concept of a math alphabet identifier
cannot be extended to cover bold symbols — better solutions are the topic of thesecond section.
To change the overall appearance of the mathematics in a document, the best
approach is to replace all the fonts used to typeset formulas. This is usually done in
the preamble of a document by loading a (set of) suitable packages, such as those
discussed in Section 12.3 starting on page 238.
In the world of text fonts (Chapter 10) there is a clear separation between fonts
suitable only for use with pdfTEX and fonts for exclusive use in Unicode engines.
Fonts for pdfTEX are available as 8-bit fonts, encoded in OT1 , T1 , or some other 8-bit

12

FONTS IN FORMULAS

font encoding from Table 9.18 on page →I 737 and typically available as Type-1 or
METAFONT fonts. In contrast, OpenType or TrueType fonts are usable only withXETEX or LuaTEX and are encoded in the TU font encoding.1,2
For symbol fonts this is not the case, at least in one direction: it is easily possible
to use an 8-bit symbol font, e.g., MarVoSym, originally designed for use with pdfTEX,
with one of the Unicode engines.
Given that formulas largely consist of fixed symbols together with a few alphabetical characters and that there have not been (many) Unicode fonts dedicated tomathematics (i.e., fonts that contain the mathematical symbols in their appropriate
Unicode slots), it should come as no surprise that the Unicode engines have been
designed to work with traditional TEX math fonts.
This has changed in recent years, and while developing OpenType Math fonts(compared to Text fonts) remains a niche market, there are now a number of fonts
available that make it interesting to provide a LaTEX math setup that directly uses such
fonts. Such a setup is available with the unicode-math package by Will Robertson, andwe will describe it in Section 12.4 on page 253.
In the final section of this chapter, starting at page 261, we showcase the effects
of extensive changes to documents on a sample page of mathematics, made with justa few keystrokes. It uses the same input material typeset with both Computer Modern
Math fonts (the default in LaTEX) and nearly 50 other font family setups for text andmathematics. All of the fonts used are readily available and, except for Lucida fonts,
provided free of charge.

12.1 The world of (Latin) math alphabets
It is easily possible to add additional new math alphabets for use in formulas. While
this can be done using arbitrary command names, by convention \mathcal (a calligraphic alphabet), \mathscr (a script alphabet), \mathfrak (a fraktur alphabet), and\mathbb (a double-stroke also known as blackboard bold alphabet) are normally used
as command names. Out of the box only \mathcal is available; for the others you
have to add a suitable package (e.g., mathalpha) in the preamble or make a declaration
manually using \DeclareMathAlphabet .
By loading the amsfonts (or the amssymb) package, both the Euler Fraktur alphabet by Hermann Zapf (\mathfrak ) and a blackboard bold alphabet3 (\mathbb )become available.

∀n ∈ N : Mn ≤ A\usepackage{amsfonts}$ \forall n \in \mathbb{N} : \mathfrak{M}_n \leq \mathfrak{A} $1 While it is possible to load 8-bit text fonts in Unicode engines, this is not a good idea because
correct hyphenation depends on using the appropriate font encoding, which means that words withdiacritics come out wrong if a legacy font encoding such as T1 is used.
2 If text fonts are usable with all engines (and many are), then this is because somebody generated
Type-1 fonts from Unicode fonts (restricting them to 8-bit and the appropriate encoding) or thatsomebody built an OpenType font from existing 8-bit sources.
3 Not much is known about the origin of this alphabet. Research in old archives (thanks to Nelson
Beebe, Barbara Beeton, and Ulrik Vieth for digging) produced no conclusive results.

226

12-1-1

12.1

The world of (Latin) math alphabets

If you also want to use upright Euler Script, you can load the eucal package thatThe Euler Script fontis also part of the amsfonts distribution. Loaded without options, it replaces the by Hermann Zapf
default \mathcal , but if loaded with the option mathscr , as done below, it becomes
accessible as \mathscr , and \mathcal remains free for a different alphabet:

ABCDEFGHIJ KLMN OPQRST UVWX YZ
12-1-2ABCDEFGHIJKLMNOPQRSTUVWXYZ\usepackage[mathscr]{eucal}\[ \mathcal{ABCDEFGHIJKLMNOPQRSTUVWXYZ} \]\[ \mathscr{ABCDEFGHIJKLMNOPQRSTUVWXYZ} \]If you prefer a geometric hollowed-out blackboard bold font in \mathbb , you
A double-stroke font
can load, for example, the bboldx package that provides support for a font designed by Alan Jeffrey
by Alan Jeffrey. One interesting aspect of this font is that it contains many moreglyphs than the usual (Uppercase) alphabet?!, which even allows you to use it
outside formulas by accessing it as \usefont{U}{bboldx}{m}{n} as we did here.
Michael Sharpe added an additional thin and a bold face to the original font and madeit available through the package bboldx.

N = {0, 1, 2, 3, . . .}ABCDEFGHIJKLMNOPQRSTUVWXYZ
12-1-3abcdefghijklmnopqrstuvwxyz\usepackage[light]{bboldx}\[ \mathbb{N}=\{\mathbfbb{0},1,2,3,\ldots\} \]\[ \mathbb {ABCDEFGHIJKLMNOPQRSTUVWXYZ}\]\[ \mathbfbb{abcdefghijklmnopqrstuvwxyz}\]

By default the medium series is offered as \mathbb , while \mathbfbb selects
the bold series. If you load the package with the option light , you get the thin andmedium series with the two commands instead. Alternatively, you can use bfbb ,which forces the package to use the bold series for \mathbf as if bold were theregular weight. You can also easily scale the alphabet slightly to make it fit with otherglyphs in your formulas by using the option scale .
By default the other available characters in the font, such as the Greek lettersor the special braces or brackets, are not available in math. If you want those in aformula, you can load the package with the option bbsymbols . However, note thatusing that option means that the font is declared as a symbol font, and as discussed
in Section 9.4.1 on page →I 681, this means you are reducing your options to use
other math fonts in your document. Therefore, do this only if you really intend to use
any of the extra symbols.

12-1-4\usepackage[bbsymbols,scale=0.9]{bboldx} \usepackage{amsmath}$ \mathbfbb{0} \neq \mathbb{1} \neq \mathbfbb{1} $0 ̸= 1 ̸= 1
\begin{align*} \mathbb{G} = \bbLbrack \bbLparen \bbLangle& \bbalpha, \bbbeta, \bbgamma, \bbdelta, \dots,\bbomega \\G = [(<α, β, γ, δ, . . . , ω& \bbGamma, \bbDelta, \bbTheta, \bbLambda, \dots,\bbOmegaΓ, ∆, Θ, Λ, . . . , Ω>)] < G\bbRangle \bbRparen \bbRbrack < \mathbfbb{G} \end{align*}
A serifed double stroke alphabet based on the Courier clone of URW in regular
A double-stroke fontand bold is provided through the dsserif package by Michael Sharpe. It offers lower by Michael Sharpe
and uppercase Latin characters as well as digits and makes them available as \mathbb

227

12

FONTS IN FORMULAS

and \mathbfbb . As usual, scale can be used to adjust the font size to other lettersin the formulas.

N = {0, 1, 2, 3, . . .}ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz\usepackage{dsserif}\[ \mathbb{N}=\{\mathbfbb{0},1,2,3,\ldots\} \]\[ \mathbb {ABCDEFGHIJKLMNOPQRSTUVWXYZ}\]\[ \mathbfbb{abcdefghijklmnopqrstuvwxyz}\]

12-1-5

The DS font designed by Olaf Kummer is a double stroke font that is based on the

A double-stroke fontComputer Modern font shapes and thus works well in formulas done with Computer
by Olaf Kummer

Modern or Latin Modern math fonts. Besides the usual uppercase alphabet, the fontsupports four additional characters: a variant form for the uppercase A (accessed bytyping a lowercase a), lowercase h and k, and the digit 1. Trying anything else resultsin missing glyph warnings.
The package makes the alphabet available through the command \mathds andnot through \mathbb . If you prefer the latter, you can alternatively set it up with thehelp of the mathalpha package or by using \DeclareCommandCopy .

ABCDEFGHIJKLMNOPQRSTUVWXYZ
a

h k

1

\usepackage{dsfont}\[ \mathds{ABCDEFGHIJKLMNOPQRSTUVWXYZ} \]\[ \mathds{a \quad h \quad k \quad 1} \]12-1-6

A nice feature of the package is that it alternatively offers you a matching Sans
double stroke font, which is useful if your formulas are typeset with sans serif fonts,
e.g., when making slides.

ABCDEFGHIJKLMNOPQRSTUVWXYZ
a

h

k

1

\usepackage[sans]{dsfont}\[ \mathds{ABCDEFGHIJKLMNOPQRSTUVWXYZ} \]\[ \mathds{a \quad h \quad k \quad 1} \]12-1-7

As an example of small-scale changes to the mathematical typesetting, those

Setting up math 
who prefer a visually distinct blackboard bold alphabet can load a different one, foralphabets with

\DeclareMathAlphabet example, the one contained in the PX fonts. The necessary declaration is done with

\DeclareMathAlphabet , which is described in Section 9.4.1. In the example we firstload the amsfonts package and then overwrite its definition of \mathbb .

{n, m ∈ N | Nn,m }\usepackage{amsfonts} \DeclareMathAlphabet\mathbb{U}{px-ds}{m}{n}$ \lbrace n,m \in \mathbb{N} \mid \mathfrak{N}_{n,m} \rbrace $The previous example shows how to include arbitrary alphabets from your LaTEX
distribution as math alphabets, with the crucial part being the arguments of the\DeclareMathAlphabet declaration. Although getting these right may appear to bea tricky matter, it is not so difficult once you know where to look. Fonts suitable forinclusion need to have an .fd file of the form ⟨enc⟩⟨name⟩.fd , where the ⟨name⟩is the font family name, often abbreviated — see the discussion on NFSS font family
naming conventions on page 6. Chapter 10 covers more than one hundred high-quality
font families and the necessary information to use them.

228

12-1-8

C H A P T E R

13Localizing documents
13.1 TEX and non–English languages . . . . . . . . . . . . . . . . . . . . . . . . . .
13.2 The babel user interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.3 User commands provided by language options . . . . . . . . . . . . . . .
13.4 Support for Cyrillic and Greek . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.5 Complex scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.6 Tailoring babel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13.7 Other approaches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

297
301
308
324
330
332
341

This chapter starts with a short introduction to the technical problems that must be
solved if you want to use LaTEX with a non–English language. Most of the remaining
part of the chapter discusses the babel system, which provides a convenient way
to generate documents in different languages. We look in particular at how we cantypeset documents in French, Russian, and Greek, as the typesetting of those languages illustrates various aspects of the things one has to deal with in a non–English
environment. We also say a few words about how to handle other languages, suchas Arabic, Japanese, or Hindi, which are written with the so-called “complex scripts”.
Section 13.6 explains how to tailor the language styles to fit your needs in somecommon cases.

13.1 TEX and non–English languages
Due to its popularity in the academic world, TEX spread rapidly throughout the world
and is now used not only with the languages based on the Latin alphabet, but alsowith languages using non–Latin alphabetic scripts, such as Russian, Greek, Arabic,
Persian, Hebrew, Thai, Vietnamese, Malayalam, or Marathi. Implementations also exist
for Chinese and Japanese (which use Kanji-based ideographic scripts) and Korean(which uses syllable blocks).

13

LOCALIZING DOCUMENTS

With the introduction of 8-bit TEX and METAFONT, which were officially released
by Donald Knuth in March 1990, the problems of multilingual support could be moreeasily addressed for the first time. Nevertheless, by themselves, these versions did notsolve all the problems associated with providing a convenient environment for using
LaTEX with multiple and/or non–English languages, which were eventually addressedwith the advent of Unicode engines like XETEX and LuaTEX.
To achieve this goal, TEX and its companion programs should be made truly
international, and the following points should be addressed:
1. Adjust all programs to the particular language(s):• Handle properly fonts containing national symbols, which includes setting
up the so-called Unicode fonts where necessary and appropriate [67],• Define line breaking and justification rules, which in Western languages
means generating patterns for the hyphenation algorithm,• Support typesetting in different directions.
2. Provide a translation for the language-dependent strings, create national layouts
for the standard documents, and provide TEX or Lua code to treat the languagedependent typesetting rules automatically [130].
3. Support processing of multilingual documents (more than one language in thesame document) and work in international environments (one language perdocument, but a choice between several possibilities). For instance, the sortingof indexes and bibliographic references should be performed in accordancewith a given language’s alphabet and collating sequence; see the discussion on
upmendex in Section 14.3 and biber in Section 15.2.2.
At the same time, you should be able to conveniently edit, view, and print yourdocuments using any given character set, and LaTEX should be able to successfully
process files created in this way. Encoding problems were ultimately solved with
Unicode, which can encode not only the alphabetic languages but also ideographic
scripts like Chinese or Japanese.
LaTEX uses by default the encoding known as UTF-8, which has been universally
adopted in the computing and publishing worlds. There still exist other character
encoding schemes, but their use is declining, because with them it is difficult for
documents to be reproducible in different environments, issues of standardization
become important, and it is necessary to know the encoding in which a document was
produced if not UTF-8. For such legacy encodings LaTEX offers the inputenc package,
described in Section 9.9.3 on page →I 758, but it is recommended to avoid it and use
the default (UTF-8) for new documents.1
To adapt LaTEX to different languages, several approaches have been followed. The
first to appear was to use dedicated packages, which very often were incompatible,
1 A few packages, including some babel languages, have not been yet updated for the current

default encoding and may display a warning like “No input encoding specified” or similar. It can beusually ignored.

298

13.1

TEX and non–English languages

thus making a multilingual document almost impossible. A second step was theintroduction of babel, which eased the standardization and development of TEXrelated software adapted to different languages. The aim was to produce for eachlanguage or group of languages a package that would facilitate typesetting, with details
about fonts, input conventions, hyphenation patterns, a LaTEX option file compatible
with the babel concept (see Section 13.1.3), possibly a preprocessor, and, of course,
documentation in English and the target language. Still, because each language takes
its own solutions, interoperation remains problematic, and a new approach, based ona core providing the basic behavior with descriptive .ini files, is being developed at
the time of this writing, although it has reached a very advanced stage.
In some languages, particularly East Asian ones, there is another approach,namely, extending the TEX program to suit the needs of a particular family of languages. For example, upTEX adds features for vertical writing and deals with otherfacets of typesetting Japanese.
Besides XETEX and LuaTEX, there have been other extensions to the TEX programattempting to improve the TEX multilingual support, like mlTEX, EncTEX, or Omega.
The latter, by Yannis Haralambous and John Plaice, incorporated a sophisticatedbidi algorithm, which has become part of LuaTEX, and provided a mechanism toperform text transformations, which has inspired what in babel are called transforms(transliterations is an example).

13.1.1 Language-related aspects of typesetting
When thinking about supporting typesetting documents in languages other thanEnglish, a number of aspects that need to be dealt with come to mind.
First and foremost is the fact that other languages have different rules forline breaking, something that TEX accommodates in Western languages through its
support for multiple hyphenation patterns. In some languages, however, certain letter
combinations change when they appear at a hyphenation point.
Unicode engines

TEX does not support this capability “out of the box”, but LuaTEX can beextended to apply nonstandard hyphenation rules — a feature exploited bybabel when using this engine. Scripts like Thai, Japanese, or Amharic follow
some specific rules, which require XETEX and LuaTEX.
Some languages need different sets of characters to be properly typeset. Thisissue can vary from the need for additional “accented letters” (as is the case withmany European languages) to the need for a completely different alphabet (as is thecase with languages using the Cyrillic or Greek alphabet).
Unicode engines

When non–European languages need to be supported, the typesetting direction
might be different as well (such as right to left for Arabic and Hebrew texts), or
so many characters might be needed (as is the case with the Kanji script, forinstance) that traditional TEX’s standard mechanisms cannot deal with them —in that case XETEX or LuaTEX is required.

299

13

LOCALIZING DOCUMENTS

A more “subtle” problem turns up when we look at the standard documentclasses that each LaTEX distribution supplies, because they were designed for the
Anglo-American situation. A specific example where this preference interferes withsupporting other languages is the start of a chapter. For some languages it is notenough to just translate the word “Chapter”; the order of the word and the denomination of the chapter needs to be changed as well, solely on the basis of grammaticalrules. Where the English reader expects to see “Chapter 1”, the Hungarian reader
expects to see “1. fejezet”.

13.1.2 Culture-related aspects of typesetting
An even thornier problem when faced with the need to support typesetting of many
languages is the fact that typesetting rules differ, even between countries that use
the same language. For instance, hyphenation rules differ between British English andAmerican English. Translations of English words might vary between countries, justas they do for the German spoken in Germany and the German spoken (and written)
in Austria.
Typographic rules may differ between countries, too. No worldwide standard
tells us how nested lists should be typeset; on the contrary, their appearance may
differ for different languages or countries or even printing houses. With these aspects
we enter the somewhat fuzzy area comprising the boundary between the language
aspects of typesetting and the cultural aspects of typesetting. It is not clear where thatboundary lies. When implementing support for typesetting documents written in a
specific language, this difference needs to be taken into account. The language-related
aspects can be supported on a general level, but the cultural aspects are more often
than not better (or more easily) handled by creating specific document classes.

13.1.3 babel — LATEX speaks multiple languages
The LaTEX distribution contains a few standard document classes that are used bymost users. These classes (article, report, book, and letter) have a certain American
look and feel, which not everyone likes. Moreover, the language-dependent strings,
such as “Chapter” and “Table of Contents” (see Table 13.2 on page 305 for a list ofcommands holding language-dependent strings), come out in English by default.
The babel package, originally developed by Johannes Braams [23] and now maintained and developed further by Javier Bezos [19], provides a set of options that allows
the user to choose the language or language(s) in which the document is typeset. It
has the following basic characteristics:• Multiple languages can be used simultaneously.
• The list of hyphenation patterns to be loaded when the LaTEX format is generated
can be defined via an external file.
• Translations for the language-dependent strings and commands for facilitatingtext input are provided for more than 60 languages (a selection of them is listed
in Table 13.1 on the facing page).

300

C H A P T E R

14Index Generation
14.1 Syntax of the index entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.2 MakeIndex — A program to sort and format indexes . . . . . . . . . . . .
14.3 upmendex — A Unicode-aware indexing program . . . . . . . . . . . . . .
14.4 xindy, xindex — Two other indexing programs . . . . . . . . . . . . . . .
14.5 Enhancing the index with LATEX features . . . . . . . . . . . . . . . . . . . .

345
350
364
370
371

To find a topic of interest in a large document, book, or reference work, you usuallyturn to the table of contents or, more often, to the index. Therefore, an index is a very
important part of a document, and most users’ entry point to a source of information
is precisely through a pointer in the index. You should, therefore, plan an index anddevelop it along with the main text [40]. For reasons of consistency, it is beneficial,with the technique discussed below, to use special commands in the text to always
print a given keyword in the same way in the text and the index throughout the whole
document.
This chapter first reviews the basic indexing commands provided by standard
LaTEX and explains which tools are available to help you build a well-thought-out index.
The LATEX Manual does not contain a lot of information about the syntax of the \index
entries. However, several articles in TUGboat deal with the question of generating an
index with TEX or LaTEX. The syntax described in Section 14.1 is the one recognized by
MakeIndex [39, 105] and the other indexing programs we discuss: upmendex, xindy,
and xindex.
Section 14.2 describes how the MakeIndex processor is used. The interpretationof the input file and the format of the output file are controlled by style parameters.
Section 14.2.4 lists these parameters and gives several simple examples to show howchanging them influences the typeset result.
Section 14.3 presents upmendex, an Unicode-aware extension to MakeIndex. It ispreferable to use this program whenever you have non–English documents or otherspecial demands, such as the production of technical indexes.

14

INDEX GENERATIONtex① A raw index (.idx file) is generated
by running LaTEX.

LaTEX

①

② The raw index, together with some
optional style information (.istfile in the case of MakeIndex or
upmendex), is used as input to theindex processor, which creates analphabetized index (.ind file) and atranscript (.ilg file).

idx
Index Program②

tex③ The index (.ind file) is read by LaTEX
to give the final typeset result.

LaTEX

③

ist

ind
ilg

Figure 14.1: The sequential flow of index processing and the various
auxiliary files used by LaTEX and an external index processor, e.g., MakeIndex

In Section 14.4 we briefly discuss two further alternatives that you may comeacross. The final section describes several LaTEX packages to enhance the index and tocreate multiple indexes such as those in the book you are reading.
∗∗∗

The process of generating an index is shown schematically in Figure 14.1. The
steps for generating an index with LaTEX and MakeIndex are illustrated in this figure.
The same flow is used with other index processors; only the configuration of theprocessors is done differently in some cases, i.e., not with .ist style files.
Figure 14.2 on the next page shows, with an example, the various steps involvedin transforming an input file into a typeset index. It also shows, in somewhat moredetail, which files are involved in the index-generating process. Figure 14.2(a) showssome occurrences of index commands (\index ) in the document source, with corresponding pages listed on the left. Figure 14.2(b) shows a raw index .idx file generatedby LaTEX. File extensions may differ when using multiple indexes or glossaries. Afterrunning the .idx file through the index processor, it becomes an alphabetized index.ind file with LaTEX commands specifying a particular output format [Figure 14.2(c)].
The typeset result after formatting with LaTEX is shown in Figure 14.2(d).
LaTEX and MakeIndex (or upmendex or xindex), when employed together, use
several markup conventions to help you control the precise format of the output. The
xindy program has a MakeIndex compatibility mode that supports the same format.
In Section 14.1, which describes the format of the \index command, we always use
the default settings.

344

14.1

Page vi:
Page 5:
Page 6:
Page 7:
Page 11:
Page 17:
Page 26:
Page 32:\index{animal}\index{animal}\index{animal}\index{animal}\index{animalism|see{animal}}\index{animal@\emph{animal}}\index{mammal|textbf}\index{animal!mammal!cat}\index{animal!insect}\indexentry{animal}{vi}\indexentry{animal}{5}\indexentry{animal}{6}\indexentry{animal}{7}\indexentry{animalism|see{animal}}{11}\indexentry{animal@\emph{animal}}{17}\indexentry{mammal|textbf}{17}\indexentry{animal!mammal!cat}{26}\indexentry{animal!insect}{32}(b) The .idx file(a) The input file\begin{theindex}\item animal, vi, 5-7\subitem insect, 32\subitem mammal\subsubitem cat, 26\item \emph{animal}, 17\item animalism, \see{animal}{11}\indexspace\item mammal, \textbf{17}\end{theindex}

Syntax of the index entries

animal, vi, 5–7
insect, 32
mammalcat, 26
animal, 17
animalism, see animal
mammal, 17(c) The .ind file(d) The typeset output

Figure 14.2: Stepwise development of index processing

14.1 Syntax of the index entries
This section describes the default syntax used to generate index entries with LaTEX andeither MakeIndex or one of the other programs described in this chapter. Different
levels of complexity are introduced progressively, showing, for each case, the input
file and the generated typeset output.
Figures 14.3 and 14.4 on page 353 show the input and generated output of a small
LaTEX document, where various simple possibilities of the \index command are shown,
together with the result of including the showidx package (see Section 14.5.2). To makethe index entries consistent in these figures (see Section 14.1.7), the commands \Comand \Prog were defined and used. The index-generating environment theindex has
been redefined to get the output on one page (Section 14.5.1 explains how this can bedone).
After introducing the necessary \index commands in the document, we want toGenerating the raw
generate the index to be included once again in the LaTEX document on a subsequent index
run. If the main file of a document is main.tex , for example, then the followingchanges should be made to that file:• Include the makeidx package with a \usepackage command.
• Put a \makeindex command in the document preamble.

345

14

INDEX GENERATION• Put a \printindex command where the index is to appear — usually at the end,
right before the \end{document} command.
You then run LaTEX on the entire document, causing it to generate the filemain.idx , which we shall call the .idx file.

14.1.1 Simple index entries
Each \index command causes LaTEX to write an entry in the .idx file. The following
example shows some simple \index commands, together with the index entries thatthey produce. The page number refers to the page containing the text where the\index command appears. As shown in the example below, duplicate commands on
the same page (such as \index{stylistic} on page 23) produce only one “23” inthe index.
style, 14style , 16
style, iii, 12
style , 15style file, 34
styles, 12
Stylist, xi
stylist, 34
stylistic, 23

Page iii:
Page xi:
Page 12:Page 14:
Page 15:
Page 16:
Page 23:
Page 34:\index{style}\index{Stylist}\index{style}\index{styles}\index{ style}\index{style }\index{ style }\index{stylistic}\index{stylistic}\index{style file}\index{stylist}

Pay particular attention to the way spaces are handled in this example. Spaces

Spaces 
inside \index commands are written literally to the output .idx file and, by default,
can be harmful

are treated as ordinary characters by MakeIndex, which places them in front of allletters. In the example above, look at the style entries on pages 14 and 16. The
leading spaces are placed at the beginning of the index and on two different lines
because the trailing blank on page 16 lengthens the string by one character. We end
up with four different entries for the same term, an effect that was probably notdesired.
It is therefore important to eliminate such spurious spaces from the \index
commands when you use MakeIndex. Alternatively, you can specify the -c option
when running the index processor. This option suppresses the effect of leading andtrailing blanks (see Sections 14.2.2 and 14.3.1). We recommend always using thisoption; it should really have been the default.
Another frequently encountered error occurs when the same English word isInconsistent spelledinconsistently with initial lowercase and uppercase letters (as with Stylist
spelling
on page xi in the preceding example), leading to two different index entries.
Of course, this behavior is wanted in languages like German, where “Arm” (arm)and “arm” (poor) are really two completely different words.1 In English, such spurious
double entries should normally be eliminated.
1 As the joke goes: “Besser arm dran als Arm ab” (better poor than without an arm).

346

C H A P T E R

15Bibliography Generation
15.1 The standard LATEX bibliography environment. . . . . . . . . . . . . . . . .
15.2 The biber and BIBTEX programs . . . . . . . . . . . . . . . . . . . . . . . . . .
15.3 The BIBTEX database format . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.4 Using BIBTEX or biber to produce the bibliography. . . . . . . . . . . . . .
15.5 On-line bibliographies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.6 Bibliography database management tools . . . . . . . . . . . . . . . . . . .
15.7 Formatting the bibliography with styles . . . . . . . . . . . . . . . . . . . .

376
378
380
409
413
414
418

While a table of contents (see Section 2.3) and an index (discussed in Chapter 14)
make it easier to navigate through a book, the presence of bibliographic references
should allow you to verify the sources and to probe further subjects you consider
interesting. To make this possible, the references should be precise and lead to therelevant work with a minimum of effort.
There exist many ways to format bibliographies, and different fields of scholarly
activities have developed very precise rules in this area. An interesting overview of
Anglo-Saxon practices can be found in the chapter on bibliographies in The Chicago
Manual of Style [40]. Normally, authors must follow the rules laid out by their publisher. Therefore, one of the more important tasks when submitting a book or anarticle for publication is to generate the bibliographic reference list according to thoserules.
Traditional ways of composing such lists by hand, without the systematic help ofcomputers, are plagued with the following problems:• Citations and references, particularly in a document with contributions frommany authors, are hard to make consistent. Difficulties arise, such as variationsin the use of full forenames versus abbreviations (with or without periods);
italicization or quoting of titles; spelling “ed.”, “Ed.”, or “Editor”; and the various
forms of journal volume number.

15

BIBLIOGRAPHY GENERATION• A bibliography laid out in one style (e.g., alphabetic by author and year) is
extremely hard to convert to another (e.g., numeric citation order) if requested bya publisher.
• It is difficult to maintain one large database of bibliographic references that canbe reused in different documents.
In the present chapter we concentrate on the formatting of reference lists andbibliographies, and we discuss possibilities for managing collections of bibliographic
references in databases. The chapter is heavily based on the BIBTEX program, writtenby Oren Patashnik, and the biber program written by François Charette and now
maintained by Philip Kime, which both integrate well with LaTEX. In Chapter 16 we arethen mainly concerned with the citation of sources within the text.
We start by showing how a bibliography can be created manually in LaTEX. Because
the standard environment is also used in the output of most BIBTEX styles, thisprepares the ground for the BIBTEX workflow. We then introduce the two programs.
This is followed by a detailed introduction to the database format1 used to specify
bibliographical data in a suitable form for processing with BIBTEX or biber. We continue
with a description of how to produce bibliographic input files for LaTEX from these
databases.
Instead of collecting your own bibliographical data, there is also the possibility ofdrawing information from various online sources that offer such data in BIBTEX format.
Some of them are introduced in Section 15.5.
Having collected data for BIBTEX databases, the next natural step is to look fortools that help in managing such databases. Section 15.6 offers tools of various flavors
for this task, ranging from command-line utilities to GUI-based programs for various
platforms.
Finally, in Section 15.7 we return to the task of typesetting a bibliography anddiscuss how different BIBTEX and biblatex styles can be used to produce different
bibliography layouts from the same input. Because there may not be a suitable style
for a particular set of layout requirements available, Section 15.7.2 discusses how to
generate customized styles using the custom-bib package without the need for any
BIBTEX style programming. How to create or adapt styles for biblatex is discussed in
Chapter 16 where we review that package in detail.

15.1 The standard LATEX bibliography environment
The standard LaTEX environment for generating a list of references or a bibliography
is called thebibliography . It is not defined by LaTEX itself but by the documentclass, so the layout can vary. In its default implementation in the standard classes,
it automatically generates an appropriate heading and implements a vertical list
structure in which every publication is represented as a separate item. It also creates
1 Due to its origin, the format is commonly referred to as the BIBT X database format, even if usedEwith biber. Thus, if you read “BIBTEX database format” in the remainder of this chapter, it refers to
the format usable by either of the programs.

376

15.1

The standard LATEX bibliography environment

for every item a label to allow referencing it in the document. The thebibliographyenvironment can be created manually, but it is also used in the output of most BIBTEX
styles. It is not used by the biblatex package, which typesets bibliographies with its
own command, \printbibliography .
The different traditions regarding how such sources are then referred to in adocument and how to produce such citations with LaTEX is the topic of Chapter 16;
here citation commands are mentioned only as far as necessary to understand how
they affect the bibliography.

\begin{thebibliography}{widest-label }\bibitem[label1]{cite-key1} bibliographic information\bibitem[label2]{cite-key2} bibliographic information...
\end{thebibliography}
The widest-label argument is used to determine the right amount of indentation
for individual items. If the works are numbered sequentially, for example, it should
contain the number of items.
Individual publications are introduced with a \bibitem command. Its mandatory
argument is a unique cross-reference cite-key that is used to refer to this publicationin the text of the document. For this purpose LaTEX offers the \cite command, whichtakes such a cite-key as its argument. Its precise syntax is described in Section 16.2.1
on page 475.
The optional argument defines the textual representation that is used in the citation and as the label in the list. If this argument is not specified, the publications arenumbered with arabic numerals by default. Within a bibliographic entry the command\newblock may be used to separate major blocks of information. Depending on thelayout produced by the document class, it may result in a normal space, may result insome extra space, or might start a new line.
The text of the heading is produced — depending on the class — by either thecommand \bibname or \refname . A language package, such as babel, localizes suchcommands and changes to them should be done by using the methods described in
Chapter 13.

[1], [GOO97]
References[1] Goossens, M., S. Rahtz, and F. Mittelbach (1997). The LATEX Graphics Companion: Illustrating Documents with TEX
and PostScript. Reading, MA, USA: Addison-Wesley Longman.
15-1-1[GOO97] Goossens, M., B. User, J. Doe(1997). Ambiguous citations.

\cite{LGC97}, \cite{GUD97}\begin{thebibliography}{2}\bibitem{LGC97} Goossens, M., S.~Rahtz,
and F.~Mittelbach (1997).
\newblock \emph{The \LaTeX{} Graphics Companion:
Illustrating Documents with \TeX{} andPostScript}. \newblock Reading, MA, USA:Ad\-di\-son-Wes\-ley Longman.
\bibitem[GOO97]{GUD97} Goossens, M., B.~User,
J.~Doe (1997). \newblock Ambiguous citations.
\end{thebibliography}

377

15

BIBLIOGRAPHY GENERATION

Order by firstcitation done
manually

Handling therequirement to use athebibliographyenvironment
explicitly

Producing a large bibliography manually in this way is clearly a tedious anddifficult task, and the result is normally not reusable, because nearly all journals
and publishers have their own house styles with different formatting requirements.
For this reason it is generally better to use programs, such as BIBTEX or biber, thatgenerate ready-to-use LaTEX input from a database of bibliographical information. Thisis discussed in the next section.
Note that the references are typeset and numbered in the order in which they
appear in the bibliography. Thus, if you produce the bibliography manually, numberingand sorting the entries into the correct order becomes your task, which is especiallydifficult if they should be ordered by first reference in the text instead of alphabetically.
In contrast, when using BIBTEX or biber, either order can be achieved automatically.
Some journals provide templates in which you are required to provide the reference list as explicit \bibitems in a thebibliography environment. When generating the bibliography with BIBTEX, this can be easily achieved by copying thefinal .bbl content into your document before submitting. However, when using
biblatex/biber, this is not possible. In this case, the biblatex2bibitem package by
Nikolai Avdeev can be of some help. Its usage is simple: load the package and issue\printbibitembibliography at the end of the document. This then typesets at
this point a source representation of the thebibliography environment, which
can be copied and pasted from the PDF into the source file intended for the journal.
However, please note that when using the engine pdfTEX, you need to ensure that yourdocument uses \usepackage[T1]{fontenc} so that you get real accented characters into the output — with the default OT1 encoding, cut and paste goes horribly
wrong otherwise.
Copying from a PDF is not fool-proof even then, and the result should be checked
for faulty characters and missing spaces. But it can save you from having to manually
retype a possibly lengthy reference list.

15.2 The biber and BIBTEX programs
The BIBTEX program was designed by Oren Patashnik to provide a flexible solution to
the problem of automatically generating bibliography lists conforming to different
layout styles. It automatically detects the citation requests in a LaTEX document (byscanning its .aux file or files), selects the needed bibliographical information fromone or more specified databases, and formats it according to a specified layout style.
Its output is a file containing the bibliography listing as LaTEX code that is automaticallyloaded and used by LaTEX on the following run. Section 15.4 on page 409 discusses theinterface between the two programs in some detail.
At the time of this book’s writing BIBTEX was available as version 0.99d , but if you
look into the second edition of this book (a decade back), you find that it already talks
about version 0.99c . Version 0.99a probably dates back to 1986. In other words,
the program has been kept stable for a very long period of time. As a consequence,
the BIBTEX database format is very well established in the LaTEX world (and in fact evenfar beyond), with many people having numerous citation entries collected over the378

C H A P T E R

16Managing Citations
16.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.2 The number-only system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.3 The author-date system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.4 The author-number system. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.5 The author-title system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.6 The verbose system. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.7 biblatex — One ring to rule them all . . . . . . . . . . . . . . . . . . . . . . .
16.8 Multiple bibliographies in one document . . . . . . . . . . . . . . . . . . .

469
473
487
502
507
537
541
569

16.1 Introduction
Citations are cross-references to bibliographical information outside the current
document, such as to publications containing further information on a subject andsource information about used quotations. It is certainly not necessary to backeverything by a reference, but background information for controversial statements,
acknowledgments of other work, and source information for used material should
always be given.
The previous chapter showed numerous ways to compile bibliographies andreference lists. They can be prepared manually, if necessary, but usually they areautomatically generated from a database containing bibliographic information. This
chapter now introduces the many presentation forms of bibliographical sources, and it
reviews different traditions regarding how such sources are referred to in a document.
We start the chapter with a short introduction to the major citation schemes incommon use. Armed with this knowledge we then plunge into a detailed discussionof how LaTEX supports the different citation schemes. At the time we wrote the firstedition of this book, LaTEX basically supported only the “number-only” system. Nearly
three decades later, the situation has changed radically. Today, all major citation
schemes are well supported by extension packages.

16

MANAGING CITATIONS

We end this chapter by discussing packages that can deal with multiple bibliographies in one document. This is not difficult if the reference lists are preparedmanually or if biblatex together with biber is used, but it poses some challenges if
you want to interact with BIBTEX, as well.

16.1.1 Bibliographical reference schemes

The number-onlysystemNumerical by firstcitation

The author-date
system470

There are five common methods of referring to sources: the “number-only”, “authordate” (or “author-year”), “author-number”, “author-title”, and “verbose” systems. The
last two of these are often used in books on humanities and jurisdiction; the second
appears mainly in science and social science works. The other two are less often used,although the first is quite common within the LaTEX world, because it has been actively
promoted by Leslie Lamport and originally was the only form of citation supported
by LaTEX. Outside the LaTEX world, a variation of it, called “numeric by first citation”, isquite popular as well.
In the number-only system, publications are sequentially numbered in the bibliography. Citations in the text refer to these numbers, which are usually surroundedby brackets or parentheses. Sometimes raised numbers are used instead.
One argument against this system — put forward, for example, in The Chicago
Manual of Style [40] — is that it raises the costs of publication, because a late addition
or deletion of a reference may require renumbering and consequently costly (anderror-prone) changes to many pages throughout the manuscript. With automaticcross-referencing facilities as provided by LaTEX, this argument no longer holds true.
In fact, the number-only system is the default system provided with LaTEX.
In a slight variation, known as “alpha” style, citations comprise the author’s nameand the year of the publication. Thus, the bibliographic label and the citation may
look like “[Knu86]”. This is still fairly compact compared with an author-date or
author-title style and has the advantage that one can often deduce the reference fromthe context.
A fairly popular form of the number-only system numbers the publications
sequentially by their first citation in the text (and presents them in that order in the
bibliography). This is fairly easy to provide with either standard LaTEX or biblatex.
However, in that case it is important to avoid that references in the table of contents
mess up the expected order; see Section 16.2.3 for advice on this.
In the author-date system (often referred to as the Harvard system after one of its
better known typographical variants), references to sources are also given directly inthe text. They show the author’s name (or names) and the year of the publication. The
full citation is given in a list of references or a bibliography. If the author publishedmore than one work in a given year, that year is suffixed with lowercase letters (e.g.,
2001a, 2001b).
There have been many attempts over the years to provide author-date citation
support for LaTEX. With the natbib package (discussed in Section 16.3.2), the jurabib
package (discussed in Section 16.5.1) and the biblatex package (discussed in Section 16.7 and 16.3.3), there are now three very flexible and general solutions available.

16.1

Introduction

It should be possible for a reader to look up a cited reference in the bibliography
lists. In all citation schemes that use author or editor names, the bibliography list
therefore should normally be sorted alphabetically by these names. This can require
special care if some of the names contain accented chars or are written in a non–Latin
script; see Section 15.3.3 for some advice. The sorting should follow the rules of themain language of the document. This is easy to achieve with biblatex, because biber
contains the necessary Unicode libraries, but with BIBTEX it can be necessary to add
sort keys to some entries to guide the sorting.
Care must also be taken to get unique citation “labels”, which allow identifying~ Watch out
the reference without ambiguity. For example, a work by three or more authors isfor ambiguous
usually referred to by using the name of the first author followed by et al. Especially citations
with the author-date system, this may lead to ambiguous citations if different groupsof authors with the same main author published in the same year. This problem canbe seen in the following example:\usepackage{chicago} \bibliographystyle{chicago}
Entries with multiple authors can be problematical, e.g., \shortcite{TLC94},\shortcite{LGC97} and \shortcite{test97} or worse \shortcite{TLC94,LGC97,test97}.
\bibliography{tlc,tlc-ex}

Entries with multiple authors can be problematical, e.g., (Goossens et al. 1994),(Goossens et al. 1997) and (Goossens et al. 1997) or worse (Goossens et al. 1994;
Goossens et al. 1997; Goossens et al. 1997).
References
Goossens, M., F. Mittelbach, and A. Samarin (1994). The LATEX Companion.
Tools and Techniques for Computer Typesetting. Reading, MA, USA: Addison-Wesley Longman.
Goossens, M., S. Rahtz, and F. Mittelbach (1997). The LATEX Graphics Companion: Illustrating Documents with TEX and PostScript. Tools and Techniques
for Computer Typesetting. Reading, MA, USA: Addison-Wesley Longman.
16-1-1Goossens, M., B. User, J. Doe, et al. (1997). Ambiguous citations. Submitted to
the IBM J. Res. Dev.
In the above example the bibliography is produced from the sample BIBTEX
databases tlc.bib and tlc-ex.bib that we introduced in the previous chapter
in Figure 15.1 on pages 382–383 and Figure 15.2 on page 391. Those databases arealso used in most examples throughout this chapter. Above we applied the BIBTEX
style chicago and its accompanying support package to it, a style that aims to implement a bibliography and reference layout as suggested by The Chicago Manual of
Style [40].
One way to resolve such ambiguous citations is to use more or all author names
in such a case, although that approach can lead to lengthy citations and is not feasible
if the number of identical authors exceeds a certain limit. Another solution is to

471

16

MANAGING CITATIONS

append a, b, and so on, to the year, even though the citations are actually for different
author groups. This strategy is, for example, advocated in [28]. If the bibliography iscompiled manually, as outlined in Section 15.1, this result can be easily achieved.
When using BIBTEX, you have to use a BIBTEX style file that recognizes these casesand provides the right data automatically. For example, the style chicago cannot be
used in this case, but all BIBTEX styles produced with custom-bib (see Section 15.7.2)
offer this feature:

Entries with multiple authors might be problematical, e.g., Goossens \usepackage{natbib}
et al. [1997a] and Goossens et al. [1997b] or even Goossens et al. \bibliographystyle{abbrvnat}[1997a,b]. But then they might not.
References
M. Goossens, S. Rahtz, and F. Mittelbach. The LATEX Graphics Companion: Illustrating Documents with TEX and PostScript. Tools andTechniques for Computer Typesetting. Addison-Wesley Longman,
Reading, MA, USA, 1997a. ISBN 0-201-85469-4.
M. Goossens, B. User, J. Doe, et al. Ambiguous citations. Submitted
to the IBM J. Res. Dev., 1997b.

Entries with multiple
authors might
be problematical,
e.g., \cite{LGC97} and\cite{test97} or even\cite{LGC97,test97}.
But then they might not.
\bibliography{tlc,tlc-ex}

16-1-2

When using biblatex with biber, the citations are almost1 always unambiguousfrom the start. The package adds, if needed, initials, given names, more authors, oran extra year marker. The behavior can be fine-tuned with the options uniquelist ,uniquename , maxnames , maxcitenames , and maxbibnames . The settings in thenext example force short author lists and automatically append letters to the year ifneeded. Details on the customization possibilities of the biblatex package are coveredin Section 16.7 starting on page 541.

Entries with multiple authors might be problematical, e.g., Goossens et al. 1997b and Goossens etal. 1997a or even Goossens et al. 1997b; Goossens
et al. 1997a. But then they might not.

\usepackage[style=authoryear,
uniquelist=false,maxnames=1]{biblatex}\addbibresource{tlc.bib}\addbibresource{tlc-ex.bib}
Entries with multiple authors might beproblematical, e.g., \cite{LGC97} and\cite{test97} or even \cite{LGC97,test97}.
But then they might not.

16-1-3

With just \usepackage[style=authoryear]{biblatex} it would have produced the far lengthier result instead:

Entries with multiple authors might be problematical, e.g., Goossens,
Rahtz, and Mittelbach 1997 and Goossens, User, Doe, et al. 1997 or even
Goossens, Rahtz, and Mittelbach 1997; Goossens, User, Doe, et al. 1997.
But then they might not.
1 It can fail if two references have identical authors and title and an author-title style is used.

472

16-1-4

C H A P T E R

17

LATEX Package
Documentation Tools
17.1 doc — Documenting LATEX and other code . . . . . . . . . . . . . . . . . . . 584
17.2 docstrip.tex — Producing ready-to-run code. . . . . . . . . . . . . . . . . . 599
17.3 l3build — A versatile development environment . . . . . . . . . . . . . . . 606
17.4 Making use of version control tools . . . . . . . . . . . . . . . . . . . . . . . 615

In this chapter we describe the doc system, a method to document LaTEX macros andenvironments. A large proportion of the LaTEX code available is documented using
its conventions and support tools. The underlying principle is that LaTEX code andcomments are mixed in the same file and that the documentation or the stripped
package file or files are obtained from the latter in a standard way. In this chapter
we explain the structure that these files should have and show how, together withthe program docstrip, you can build self-installing procedures for distributing your
LaTEX packages and generating the associated documentation. The chapter also helps
you understand the code written by others, install it with ease, and produce thedocumentation for it (not necessarily in that order).
The third section then introduces the l3build program, which offers a flexible development environment. It supports a package developer in all important steps: codeand documentation development, testing, and all aspects of the release management
including upload to CTAN. It is the workflow environment used by the LaTEX Project
Team for the code that they manage.
We end the chapter with a section on version control systems and explain how
to extract and use their information with LaTEX. Applying version control methods isdefinitely useful for any larger documentation project, but in fact is advisable for any
document that goes through a number of “revisions”.

17

LATEX PACKAGE DOCUMENTATION TOOLS

17.1 doc — Documenting LATEX and other code
The idea of integrated documentation was first employed by Donald Knuth when hedeveloped the TEX program using the WEB system, which combines Pascal-like meta
source code and documentation. Thanks to his approach, it was particularly easy toport TEX and its companion programs to practically any computer platform in theworld.
Subsequently, authors of LaTEX packages started to realize the importance of
documenting their LaTEX code. Many now distribute their LaTEX macros using theframework defined with the doc package (by Frank Mittelbach) and its associateddocstrip utility (originally by Frank Mittelbach with later contributions by Johannes
Braams, Denys Duchier, Marcin Woliński, and Mark Wooding).
The doc package was written roughly 30 years ago (version 1 appeared in 1988,
predating LaTEX 2ε ). Since then it has been extensively used to document the LaTEX
kernel and most of the packages that are available on today’s LaTEX distributions. The
core code of version 2 has existed since 1998, and that version was distributed withLaTEX until 2022. At the TUG conference in Rio 2018 the author sketched out plans
for a version 3 to improve it in several respects, but given it is so widely used, anychange would need to be very light-weight, basically adding hyperlink support andadding a way to provide additional doc elements (not just macros and environments),
with full compatibility to support all the existing uses.1
Both systems together allow LaTEX code and documentation to be held in thesame TEX source file. The obvious advantage is that a sequence of complex TEX
instructions becomes easier to understand with the help of comments inside the file.
In addition, updates are more straightforward because only a single source file needs
to be changed.
The doc package provides a set of commands and establishes some conventions
that allow specially prepared source files to contain both code and its documentationintermixed with each other. This is discussed in Sections 17.1.1 to 17.1.3.
To produce the documentation you need a driver (file) that loads the doc package
and then interprets the source file. In its simplest form the driver for the documentation is an external file. However, the driver is more commonly made part of the source
file so that all you have to do to produce the documentation is to run the source filethrough LaTEX. The possibilities are discussed in detail in Section 17.1.4.
To produce a ready-to-run version of your code you need to first process thesource package with docstrip (see Section 17.2). This step is usually implicitly done
by providing an .ins file that is run through LaTEX. The most important commands
and concepts are discussed in the next sections. Tables 17.1 to 17.5 on pages 595–597
provide an overview of all doc user commands. Further details on any of them can befound in the documented source doc.dtx of the doc package, which can also serve
as a prime (though somewhat aged) example of the doc system.
1 If I restarted from scratch, I would do a lot of things differently now, and in fact several otherpeople have tried to come up with better solutions. However, as the saying goes, a bad standard
is better than none, so doc has prevailed, and changing it now in incompatible ways would bea nonstarter. Some of the ideas for the extensions have been borrowed from Didier Verna’s DoX
package, even though I did not use the document-level interfaces.

584

17.1 doc — Documenting LATEX and other code

17.1.1 General conventions for the source file
A LaTEX file to be used with the doc system consists of documentation parts intermixed
with code parts. Every line of a documentation part starts with a percent sign (%) in
the first column. It can contain arbitrary TEX or LaTEX commands, but the % charactercannot be used as a comment character. User comments are created by using the ^^A
character or, if you prefer, the ^^X character instead. Longer text blocks can be turned
into comments by surrounding them with %\iffalse . . . %\fi . All other parts of thefile are called code parts. They contain the code described in the documentation parts.
Depending on how the code parts are structured, it is possible to use such afile directly with LaTEX, although these days this is seldom done. Instead, docstrip is
typically used to produce the production files. If the former approach is taken, LaTEX
bypasses the documentation parts at high speed and pastes the macro definitions
together, even if they are split into several code parts.
On the other hand, if you want to produce the documentation of the macros, thenthe code parts should be typeset verbatim. This is achieved by surrounding theseparts by the macrocode environment.

%␣␣␣␣\begin{macrocode}⟨one or more lines of code⟩%␣␣␣␣\end{macrocode}
It is mandatory that you put exactly four spaces between the % character and\end{macrocode} and no space between \end and its argument. The reason isthat when LaTEX is processing the macrocode environment, it is actually looking forthat particular string and not for the command \end with the argument macrocode .
Inside a code part all TEX commands are allowed. Even the percent sign can beused to suppress unwanted spaces at the ends of lines.
If you prefer, you can use the macrocode* instead of the macrocode environment. It produces the same results except that spaces are displayed as ␣ characterswhen the documentation is printed.

17.1.2 Describing new macros and environments
Most packages contain commands and environments to be employed by users intheir documents. To provide a short manual describing their features, a number of
constructs are offered by the doc package.

\DescribeMacro[keys]{\cmd1 ,. . . }\Describe⟨element⟩[keys]{entry1 ,. . . }The \DescribeMacro command takes one argument containing a comma-separated
list of command names, which are shown in the margin, and for which special (usage)
index entries are generated, for example,% \DescribeMacro{\DocInput,\IndexInput}% Finally the \meta{input commands} part ...

585

17

LATEX PACKAGE DOCUMENTATION TOOLSIn the optional argument you can specify either noindex or noprint to suppress
indexing or printing for that particular instance. Using both would be possible too,
but pointless because then the command would do nothing.
A similar command, \DescribeEnv , can be used to indicate that at this point
one or more LaTEX environments are being explained, and if you declare additional doc
elements, e.g., ⟨element⟩, then \Describe⟨element⟩ becomes available too.

\begin{macro}[keys]{\cmd1 ,. . . ,\cmdn }\begin{environment}[keys]{env1 ,. . . ,envn }To describe the definition of one or more commands, you use the macro environment.
It takes one mandatory argument: a comma-separated list of the new commands. This
argument is also used to print the names in the margin and to produce appropriate
index entries. The index entries for usage (produced by \Describe... ) and for
definition are different, which allows for easy reference. Here is an example takenfrom the sources of the doc package itself:% \begin{macro}{\check@angle}%
Before looking ahead for the |<| the |%| is gobbled by the%argument here.
%\begin{macrocode}\def\check@angle#1{\futurelet\next\ch@angle}%\end{macrocode}% \end{macro}
The optional keys argument lets you suppress indexing or printing of the command
names in the margin, through specifying either noindex or noprint for that particular instance. If any such setting is made on the environment level, it overwrites
whatever default was given when the doc element was defined or when the package
was loaded.
By default the commands listed in the mandatory argument of the macro environment are not allowed to be declared with \outer (which is a plain TEX concept notofficially supported by LaTEX). However, should you really want to document such acommand, you can do so by specifying the key outer in the optional keys argument.
Another environment, with the unimaginative name environment , documents
the code of environments. It works like the macro environment but expects the nameor names of environments as its argument.
These two (macro and environment ) are the doc elements supported out of thebox by the package. How to define further elements is covered in Section 17.1.6 on
page 592.

\MakeShortVerb{\c }\MakeShortVerb*{\c }\DeleteShortVerb{\c }When you have to quote a lot of material verbatim, such as command names, it isawkward to always have to type \verb+. . . + . Therefore, the doc package provides anabbreviation mechanism that allows you to pick a character c, which you plan to use

586

A P P E N D I XALATEX Overview
for Preamble, Package,and Class Writers
A.1 Linking markup and formatting . . . . . . . . . . . . . . . . . . . . . . . . . . 622
A.2 Counters and length expressions . . . . . . . . . . . . . . . . . . . . . . . . . 646
A.3 Page markup — Boxes and rules . . . . . . . . . . . . . . . . . . . . . . . . . . 660
A.4 LATEX’s hook management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671
A.5 Control structure extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685
A.6 Package and class file structure . . . . . . . . . . . . . . . . . . . . . . . . . . 693

This appendix gives an overview of the basic programming concepts underlying the
LaTEX formatter. We explain how to define new commands and environments, including
those with optional arguments and other specialized input syntax. We discuss how
LaTEX handles counters and their representation; we also introduce horizontal andvertical space parameters and explain how they are handled.
The third section reviews the important subject of LaTEX boxes and their use. A
good understanding of this topic is very important to fully appreciate and exploit the
information presented in this book.
In the fourth section we then take a deeper look at LaTEX’s new hook managementthat was introduced in 2020. The fifth section is devoted to two package files, calc
and ifthen, that make calculations and building control structures with LaTEX easier.
They have been used in many examples of LaTEX code throughout this book.
Finally, we describe in detail the LaTEX interfaces that allow you to define yourown packages and class files.

A

LATEX OVERVIEW FOR PREAMBLE, PACKAGE, AND CLASS WRITERS

A.1 Linking markup and formattingThis section reviews the syntax for defining commands and environments with LaTEX.
It is important that you exclusively use the LaTEX constructs described below, rather
than the lower-level TEX commands. Then, not only are you able to take advantage of
LaTEX’s consistency checking, but your commands are also portable, (probably) without
modification, to future versions of LaTEX.
LaTEX offers three major ways to define commands and environments. Simple
commands can be defined with \newcommand and \newenvironment that havebeen available for several decades. These are discussed first.
More recently the \NewDocumentCommand and \NewDocumentEnvironment
declarations were added to LaTEX. They allow you to easily define commands andenvironments with a richer argument structure, not only involving a single optional argument, but also those with multiple optional arguments, special argument delimiters,
and much more. This is discussed in Section A.1.4 on page 632.
Finally, there are low-level methods of TEX, through \def , \let , and similarcommands, and, of course, all the declarations from the L3 programming layer(formerly known as expl3), e.g., \cs_new:Npn and many more. None of that iscovered in this book because these constructs should be used only for low-level
programming, and their discussion would easily fill a book by itself.

A.1.1 Command and environment names
In current LaTEX, whether used with pdfTEX or with one of the Unicode engines, it ispossible to enter accented characters and other non–ASCII symbols directly into thesource, so it would seem reasonable to expect that such characters could also be usedin command and environment names (e.g., \größer ). However, this is not the case —LaTEX multicharacter command names should be built from basic ASCII letters (i.e.,a. . . z and A. . . Z ).1 This means that \vspace* is actually not a command by itself;
rather, it is the command \vspace followed by the modifier * . Technically, you could
write \vspace␣* (as the space is ignored) or even put the * on the next line of yourdocument.2
On the other hand, names of environments are different. In this case the * is part
Environmentsof the name, and spaces preceding it are not ignored. Thus, when writing something
like \begin{figure␣*} , the space would become part of the name, and this istherefore not recognized as the start of a figure* environment. This is due to
implementation details and seems to indicate that with environment names some
additional ASCII characters work. For example:
Commands\newenvironment{foo.bar:baz␣with␣space}{}{}
However, this is not true in general because, depending on additional packages being
1 Strictly speaking this is not true, as T X can be configured to support other configurations. ThereE
are, however, valid reasons why this is not being done for standard LaTEX. Some of these reasons are
discussed in Section 9.9 describing LaTEX’s encoding model.
2 It is bad style to use this in your documents, but there is unfortunately no way to prevent it.

622

A.1

Linking markup and formatting

loaded, such environment names may no longer be recognized or may produce strange
errors. Thus, it is best not to explore that implementation (mis)feature and instead torely on officially supported names — those containing only lowercase and uppercase
letters and the star character.
Strictly speaking, \cite and \label keys have (or had) the same kind of restricCitation andtion. Nevertheless, it has become common practice to use keys containing colons label keys
(e.g., sec:cmds ) so that most packages provided extra support to allow for at least
the colon character in such keys. Around 2020, when LaTEX moved to UTF-8 as its
default input, that restriction was lifted as part of the necessary rewrite so that now
most characters outside the ASCII range can be safely used in label keys. However,characters used in LaTEX’s syntax (e.g., $ , _ , or # ) can never be used in names, whether
they are keys, counters, environments, or multicharacter command names.
With single-character command names, the situation is different again: any (single)
Control symbols
character can be used. Symbols that are not “letters” cannot participate in multiletter
command names, e.g., \foo$bar would be interpreted as the command \foo followed by the start of a math formula (signaled by $ ) followed by the (math) charactersb , a , and r . Any following text is then also typeset in math mode. However, such
symbols can appear directly after the backslash and form a so-called control symbol;
e.g., \$ is perfectly valid.
In contrast to multiletter commands, such control symbols do not ignore spaces
after them, because that is what is normally desired in situations like 30\% or cut \&paste . Note, however, that something like \S would not be a control symbol but amultiletter command, consisting of a name with only a single letter and thus spaces
are ignored after it, as shown in the following example:

A-1-1$ 100 is different from $100. You
have to write $100 to avoid the space!
But §1.2 and §1.2 give the same spacing.

\$ 100 is different from \textdollar 100.
You have to write \$100 to avoid the space!
But \S 1.2 and \S1.2 give the same spacing.

Categories of LATEX commands
LaTEX commands (i.e., those constructs starting with a backslash) are classified into
three basic categories: document-level commands, package and class writer commands, and internal “kernel” commands.
• Document-level commands, such as \section , \emph , and \sum , usually have Document-levelcommands(reasonably) short names, by convention all in lowercase.
• Class and package writer commands, by convention, have longer mixed-caseClass and package
names, such as \InputIfFileExists and \RequirePackage . Some of them writer commands
can be usefully applied in the document source, but many stop working after\begin{document} has been processed, producing an error message if you try.
• Traditionally most of the internal commands used in the LaTEX implementation,
Internal LATEX
such as \@tempcnta , \@ifnextchar , and \z@ , contain @ in their name. This commands
effectively prevents these names from being used in documents for user-definedcommands. However, it also means that they cannot appear in a document, evenin the preamble, without taking special precautions.

623

A

LATEX OVERVIEW FOR PREAMBLE, PACKAGE, AND CLASS WRITERS

Modern internal commands use the L3 programming layer where commands use“_” and “:” as part of their names, which makes them also (deliberately) unusable
in documents.
As a few of the examples in this book demonstrate, it is sometimes necessary tohave such bits of “internal code” in the preamble. The commands \makeatletter
Careful and \makeatother make this easy to do; the difficult bit is to remember to add
with internal
commands! them — failure to do so can result in some strange errors. For an example of theiruse, see page →I 210. Note that package and class files should never contain thesecommands: \makeatletter is not needed because this is always set up when reading
such files, and the use of \makeatother would prematurely stop this behavior,causing all kinds of havoc. For modern L3 programming layer code (expl3), there are\ExplSyntaxOn and \ExplSyntaxOff that serve the same purpose.
Unfortunately, for historical reasons the distinction between these categories is
The distinction
often
blurred. For example, \hbox is an internal command that should preferably be
between internal
used
only
in the LaTEX kernel, because it does not deal properly with color changes inand publiccommands its argument, whereas \m@ne is the constant -1 and would have been better named\MinusOne back then.
Nevertheless, this rule of thumb is still useful: if a command has @ in its name,then it is not part of the supported LaTEX language — and its behavior may change infuture releases! Any such command should be used with great care. On the other hand,
mixed-case commands or those described in the LATEX Manual [106] are guaranteed tobe supported in future releases of LaTEX.
In the L3 programming layer there is much more standardization. Command
names follow a predictable pattern, and what is supported and usable elsewhere iswell defined: any name starting with \__ is private and should not be used outside
its module; all others are officially part of the programming layer. Similarly, private(local) variables start with \l__ , whereas public ones have only one underscore, etc.

A.1.2 Defining simple commands
It is often advantageous to define new commands (e.g., for representing repetitive
input strings or recurring combinations of commands). Here we describe how do thisfor simple cases, where the new commands take at most one optional argument. Thisis the method introduced with LaTEX 2ε in 1994. How to define commands with more
complex argument structures is shown in Section A.1.4.
Complexity comes with a price tag in terms of processing speed: so for “simple”
tasks we recommend simple tools, i.e., the declarations discussed here. However,already when defining commands with one optional argument, you should consider
using the declarations discussed later.

\newcommand{cmd }[narg]{command definition}
A new command is defined using the \newcommand declaration. The number ofarguments is in the range 0 ≤ narg ≤ 9. If your new command has no arguments,

624

A P P E N D I X

BTracing and Resolving
Problems
B.1 Error messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B.2 Dying with memory exceeded . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B.3 Warnings and informational messages . . . . . . . . . . . . . . . . . . . . . .
B.4 TEX and LATEX commands for tracing . . . . . . . . . . . . . . . . . . . . . . . .

712
744
749
765

In an ideal world all documents you produced would compile without problems andgive high-quality output as intended. If you are that lucky, there will be no need for
you to consult this appendix, ever. However, if you run into a problem of some kind,the material in this appendix should help you to resolve your problem easily.
We start with an alphabetical list of all error messages, those after which LaTEX
stops and asks for advice. “All” in this context means all LaTEX kernel errors (theirtext starts with LaTeX Error: or LaTeX ⟨module⟩ Error), practically all TEX errors(i.e., those directly produced by the underlying engine), and errors from the packages
amsmath, babel, calc, color, fontenc, graphics, graphicx, and inputenc. Errors reported
by other packages — those that identify themselves as! Package ⟨package⟩ Error: ⟨error text⟩
where ⟨package⟩ is not one of the above — are not included. For such errors you
should refer to the package description elsewhere in the book or consult the original
package documentation.
But even if there are no real errors that stop the processing, warning and information messages might be shown on the terminal or in the transcript file. They aretreated in Section B.3, where you will find all LaTEX core messages and all relevant TEX
messages that may need your attention, together with an explanation of their possible
causes and suggestions on how to deal with them.

B

TRACING AND RESOLVING PROBLEMS

The final section deals with tools for tracing problems in case the error or warning
information itself is not sufficient or does not exist. We will explore ways to display
command definitions and register values and then take a look at diagnosing andsolving page-breaking problems. This is followed by suggestions for identifying andsolving paragraph-breaking problems and includes a brief look at two LuaTEX-only
packages for dealing with hyphenation issues. We finish with a description of the
trace package, which helps in thoroughly tracing command execution, if your own
definitions or those of others produce unexpected results.
Some of the material in this appendix can be considered “low-level” TEX, something that, to the author’s knowledge, has never been described in any other LaTEX
book. It is, however, often important information. Directing the reader to books like
The TE Xbook does not really help, because most of the advice given in books aboutplain TEX is not applicable to LaTEX or produces subtle errors when used. We therefore
try to be as self-contained as possible by offering all relevant information about theunderlying TEX engine as far as it makes sense within the LaTEX context.

B.1 Error messages
When LaTEX stops to display an error message, it also shows a line number indicating
how far it got in the document source. However, because of memory considerationsin the design of TEX itself, it does not directly show to which file this source line
number belongs. For simple documents this is not a problem, but if your documentis split over many files, you may have to carefully look at the terminal output or thetranscript file to identify the file LaTEX is currently working on when the error occurs.1
Whenever LaTEX starts reading a file, it displays a “(” character that is immediately
Finding the source
followedby the file name. Once LaTEX has finished reading the file, it displays theline of an error
matching “)” character. In addition, whenever it starts preparing to output a page,
it displays a “[” character followed by the current page number. Thus, if you see
something like(./trial.tex [1] (./ch-1.tex [2] [3] (./table-1.tex [4] [5]) [6]! Undefined control sequence.
<argument> A \textss{Test}
l.235 \section{A \textss{Test}}\label{sec:test}?
you can deduce that the error happened inside an argument of some command(<argument> ) and was detected when LaTEX gathered material for page 7. It got as far
as reading most of line 235 in the file ch-1.tex . In this example the error is readily
1 A useful little helper for this is the structuredlog package. Once loaded, it uses the file hooks
to identify the start and end of file-reading actions in the .log with lines such as “== (LEVEL 2
START) table-1.tex” and corresponding STOP lines. Thus, to find out where some error has occured
you only have to search backwards for the string “(LEVEL” and if that is a START line you are done;otherwise, you have to search further for the START line with the next lower level number.

712

B.1

Error messages

visible in the source line: \textsf was misspelled as \textss inside the argument
to the \section command. In some cases, however, the relationship between error
and source line is blurred or even nonexistent.
For example, if you define \renewcommand\thepart{\Alp{part}} , then the
typo appears only when you use the \part command that executes your definition.
In that case you get! Undefined control sequence.
\thepart ->\Alp{part}
l.167 \part{Test}
In this particular case the actual error is not on line 167 and most likely not even in
the current file — the \part command merely happens to call the faulty definition of\thepart .
Sometimes an error is detected by LaTEX while it is preparing a new page. Because
this is an asynchronous operation, the source line listed in the error message is ofno value whatsoever. So if you do not understand how the error should be related tothe source line, you may well be right — there is, indeed, no relationship. Here is an
example:! Undefined control sequence.
\thepage ->\romen{page}
l.33 T
his is a sample text to fill the page.
One way to obtain additional information about an error (or information about
how LaTEX intends to deal with it) is to press the key h in response to the ? that follows
the error message. If used with a TEX error such as the one above, we get? h
The control sequence at the end of the top lineof your error message was never \def’ed. If you have
misspelled it (e.g., ‘\hobx’), type ‘I’ and the correctspelling (e.g., ‘I\hbox’). Otherwise just continue,and I’ll forget about whatever was undefined.
You probably already see the problem with advice coming directly from the TEX
engine: you may have to translate it, because it often talks about commands thatare not necessarily adequate for LaTEX documents (e.g., for \def you should read\newcommand or \NewDocumentCommand ). With real LaTEX errors this is not the case,though here you sometimes get advice that is also not really helpful:You’re in trouble here. Try typing <return> to proceed.
If that doesn’t work, type X <return> to quit.
Well, thank you very much; we already knew that! Typing h ⟨return⟩ is, however, worth
a try, because there are many messages with more detailed advice.

713

B

TRACING AND RESOLVING PROBLEMS

Another way to get additional information about an encountered error is to set the

Displaying the stackcounter errorcontextlines to a large positive value. In that case LaTEX lists the stack ofof partiallythe current macro executions:
expanded macros
1
2
3
4
5
6

! Undefined control sequence.
\thepage ->\romen{page}\@oddfoot ->\reset@font \hfil \thepage\hfil\@outputpage ...lor \hb@xt@ \textwidth {\@thefoot7}\color@endbox }}\globa...

89\@opcol ...lumn \@outputdblcol \else \@outputpage

10
11<output> ...specialoutput \else \@makecol \@opcol

12
13
14
15
16

<to be read again>\fi \global \@mparbotto...
\@startcolumn \@whilesw...

Tl.33 T
his is a sample text to fill the page.

You read this bottom up: LaTEX has seen the T (lines 15 and 16) but wants to read it again
later (<to be read again> , lines 13 and 14) because it switched to the output routine(<output> ). There it got as far as executing the command \@opcol (lines 11 and 12),which in turn got as far as calling \@outputpage (lines 9 and 10), which was executing\@thefoot (lines 6 and 7). Line 4 is a bit curious because it refers to \@oddfoot rather than\@thefoot as one would expect (\@thefoot expands to \@oddfoot , so it is immediately
fully expanded and not put onto the stack of partially expanded macros). Inside \@oddfoot
we got as far as calling \thepage , which in turn expanded to \romen (lines 2 and 3), which
is finally flagged as an undefined command (line 1).
Fortunately, in most cases it is sufficient only to display the error message and thesource line. This is why LaTEX’s default value for errorcontextlines is -1 , which means
not showing any intermediate context.

Errors can occur when LaTEX is doing expansions rather than typesetting. This is

Error a problematical time, because in that mode TEX is not able to do any assignments,
during expansion

which is a prerequisite to display LaTEX error or warning messages with useful help
texts. It is also difficult to stop the expansion in time when an error condition is
identified without stopping it when there is no error condition. Nevertheless, withsome gymnastics it is possible to produce reasonable error messages (as long as you
ignore the help text that you get by typing h in response to the error). The trick usedby LaTEX is to produce a low-level TEX error, but to do this in a way that it nearly looks
like a normal LaTEX error.

! Use of \??? doesn’t match its definition.
<argument> \???
! LaTeX cmd Error: Required argument missing for \foo.
l. ... }714

A P P E N D I XCGoing beyond
C.1 Learn LATEX — A LATEX online course for beginners . . . . . . . . . . . . . . . 784
C.2 Finding information available on your computer . . . . . . . . . . . . . . . 785
C.3 Accessing online information and getting help . . . . . . . . . . . . . . . . 787
C.4 Getting all those TEX files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
C.5 Giving back to the community . . . . . . . . . . . . . . . . . . . . . . . . . . . 792

While we certainly hope that your questions have been answered in this book, weknow that this cannot be the case for all questions. This appendix tries to help in that
unfortunate case.
The first section deals with the fundamental problem that our book (despite being
rather large) is not meant for beginners. To make good use of it, you already needsome basic knowledge of LaTEX. If this is missing, then there is a great online course toteach you the foundations.
For questions related to specific packages discussed in the book, it can be helpful
to read the original documentation provided with the package. Appendix C.2 suggests
ways to find that documentation on your system.
Appendix C.3 then shares how to find online information to research questions
that you may have, and how to interact with people in the TEX community when you
experience problems.
This is followed in C.4 by explaining how best to obtain LaTEX packages that are
missing on your installation. It also gives a brief overview of TEX distributions and
LaTEX services in the cloud.
The final section talks about the community itself and how you can join it tomake a difference and keep the ship afloat.

C

GOING BEYOND

C.1 Learn LATEX — A LATEX online course for beginners
If you are new to LaTEX and picked up this book hoping that it also covers the LaTEX

Worry-freebasics (which it understandably does not, if you look at the current page number) or
experimentation ina browser if you need to refresh your memory on the basics, we recommend that you take a

Available in several
languages

18 lessons to get
you going. . . more on each
topic

Recommend this to
new users

784

look at the Learn LaTEX website at https://learnlatex.org , which offers a great
online course, teaching you the fundamentals and allowing you to experiment withLaTEX online — even without installing the system locally.
The Learn LaTEX project was born out of the desire to provide any easy-to-accessapproach for LaTEX beginners. The site has been designed and implemented by members of the LaTEX Project Team, primarily by David Carlisle and Joseph Wright, as well
as a larger group of volunteers who helped shape the content and did a marvelous
job of translating it to several languages so that the full course is now available in
Catalan, English, Español, French, German, Marathi, Portuguese, and Vietnamese —and, who knows — soon perhaps additional languages.
The curriculum consists of eighteen easy-to-consume lessons with interactive
examples and exercises that can be processed and modified (!) in the browser, covering
the basics that you need to get started with LaTEX and that underpin all the information
provided in the current book. The central idea of the site is to get people started with
one of the most common LaTEX tasks: write some academic document such as an article
or report. The topics start with simple LaTEX structure, cover things such as including
images or building tables, and move on to longer documents and bibliographies.
Typesetting mathematics is clearly a core LaTEX strength, but here the course remains
deliberately lightweight and touches on only a few concepts; it is enough to get you
going but certainly not enough to write a complex math paper — the thoughts beingthat details like those covered in Chapter 11 are better mastered in a second step.
Each lesson comes with an extra “More on this topic” page that can be bypassed
when working through the course for the first time but that offers additional details if
you are interested in a particular topic. For example, the lesson on tables focuses on
the array package as the fundamental extension to LaTEX’s basic tabular environment
and explains the main concepts such as the different kinds of column specifiers, how
to add rules, and how to merge cells. The “More on this topic” page then goes intostyling columns with the help of specifiers, manipulating space between columns, or
producing customized rules and much more.
Being closely linked with the LaTEX Project Team that maintains and develops
LaTEX for you, the site is expected to stay up-to-date (in contrast to many other sites
sprinkled across the Internet that have been set up with good intentions, but whichthen sadly declined in quality over the years). By offering a couple of ways to process
the examples online (or off-line because the examples are plain text that is easily
copied) and by presenting the course in several languages, it provides a low-barrier
introduction to learning LaTEX. As it stands, it is a great resource for starting withLaTEX, and even if you personally have no need for it at your level of experience, it may
be good to take a look and see how it functions. There may be a need to convince acolleague or friend to take the first steps with LaTEX, and this site may just convince
them that LaTEX is not too hard to learn and worth the trouble — and for the rest there
are books like the one you are currently holding in your hands.

C.2

Finding information available on your computer

C.2 Finding information available on your computer
When you want to use a LaTEX package, it would be nice if you could study the
documentation without having to remember where the relevant files are located onyour TEX system. Two important command-line tools exist to help you in your search:kpsewhich and texdoc. The first is most important if you want to study code, while
the second helps you to easily find available documentation in your distribution.

C.2.1 kpsewhich — Find files the way TEX does

When TEX loads files (at least those loaded with \input or similar), it uses a special
search library named kpathsea by Karl Berry that determines where to look and which
file to load in case there is more than one with the same name.
The file name loaded is written into the .log file so you can find out what wasloaded there, but this is not necessarily the most convenient way given that the transcript file contains a lot of other information. It also would not help if you ask yourself
the question “which array.sty would LaTEX load if I use \usepackage{array} ?”unless you first make a test file, run it through LaTEX, and then look at the transcript.
To help with this, the library is also available as the standalone command-line
tool kpsewhich. In most cases it is enough to pass it the name of the file you areinterested in, e.g., kpsewhich array.sty , and it responds with the full path for thefile:/usr/local/texlive/2022/texmf-dist/tex/latex/tools/array.sty
You can load it into your editor if you want to look at the code. You can also call
kpsewhich with the option -all , in which case it returns/usr/local/texlive/2022/texmf-dist/tex/latex/tools/array.sty/usr/local/texlive/2022/texmf-dist/tex/latex-dev/tools/array.styi.e., all files with that name that it knows about.
You may wonder when (if ever) the other files are used by LaTEX. The answer is it
depends on the program name used for running LaTEX. For example, if you use any ofthe development formats, e.g., pdflatex-dev, the array package from the latex-dev
directory is used, because the search library has different search rules based on the
program that is initiating the search. To mimic that with kpsewhich, pass it the option-progname=⟨prog⟩, and you get the result that would be returned to ⟨prog⟩ for the
search:kpsewhich -progname=pdflatex-dev array.sty

would return/usr/local/texlive/2022/texmf-dist/tex/latex-dev/tools/array.styi.e., the package version for the next LaTEX release.

785

C

GOING BEYOND

If you want to find out where the LaTEX format file resides that is used by LaTEX,
it is not enough to just specify the name of the format file. You also have to tell
kpsewhich which engine is loading it, using the option -engine=⟨engine⟩. Possible
engine names are pdftex, xetex, or luahbtex. Together with the -all option, this is agreat help if you receive a “Mismatched LaTeX support files” error; see page 730.
The program offers several other options; a list can be obtained with -help ,but most of them are needed only for developers who set up a TEX distribution.
The one that may be of interest occasionally is -debug=32 . This produces detailed
tracing output about how kpsewhich does its search and where it looks, which canbe helpful if LaTEX seems to be unable to find a file that you know is on your system.
The -debug option can be given other numeric values to show other aspects of its
behavior. For details on that and other features of TEX’s search library, take a look at
the documentation with texdoc kpathsea .

C.2.2 texdoc — A command-line interface to local TEX information

Opening the best
result for viewing

Getting a list of“good” results tochoose fromGetting a list of“all” results

786

The texdoc program has a long history: it started out as a Unix shell script developedin the early nineties by Thomas Esser. The first Lua-based version was then written
by Frank Küster with contributions by Reinhard Kotucha. It offered some operating
system independence, because Lua, through LuaTEX, is available with any TEX (decent)distribution without the need to install separate programs.
Today’s greatly enhanced version is developed and maintained by ManuelPégourié-Gonnard and ASAKURA Takuto and the TEX Live team.
Initially you had to know the exact name of the documentation except for the
file extension, so it was quite similar to kpsewhich in that regard. The current implementation, however, has a much more general search mechanism that accounts
for the fact that many developers use schemes such as package-doc.pdf , package-manual.pdf , etc., for their documentation. It also has an alias mechanism
through which individual documentation files can be associated with some keyword(s)people are likely to search for. For example, the file interface3.pdf (the interface
documentation for the L3 programming layer) is one of the results if you search for
expl3 . This is managed through a configuration file that is part of the TEX distribution and regularly updated. You can also have your own configuration file as explainedin the program documentation.
Most of the time all you have to do is to pass texdoc the name of a package as
an argument, e.g., texdoc fewerfloatpages , and it replies by opening the (whatit thinks) best result in a suitable viewer for you; in this case it would open the file
fewerfloatpages-doc.pdf .
If this turns out not to be the documentation you have been looking for, your next
possibility is to use it with the option -l . If you do that, it replies with a list of “useful”
documentation files based on your input, and you can then choose one of them to beopened. For example, texdoc -l array would return five results: the official package
documentation, the (possibly updated) version in the LaTEX development release, as
well as a French translation of the package documentation.
If that is still not what you want, you can use -s instead. In that case texdoc
returns all files it has found, even those that it considered to be a bad match. For

Bibliography[1] Adobe Systems Incorporated. Adobe Type 1 Font Format. Addison-Wesley,
Reading, MA, USA, 1990. ISBN 0-201-57044-0.
The “black” book contains the specifications for Adobe’s Type 1 font format and describes how
to create a Type 1 font program. It explains the specifics of the Type 1 syntax (a subset of
PostScript), including information on the structure of font programs, ways to specify computer
outlines, and the contents of the various font dictionaries. It also covers encryption, subroutines,
and hints.
https://adobe-type-tools.github.io/font-tech-notes/pdfs/T1_SPEC.pdf[2] American Mathematical Society. User’s Guide to AMSFonts Version 2.2d.
Providence, Rhode Island, 2002.
This document describes AMSFonts, the American Mathematical Society’s collection of fonts ofsymbols and several alphabets.
https://www.ctan.org/pkg/amsfonts[3] ———. Using the amsthm Package (Version 2.20.3). Providence, Rhode Island,
2017.
The amsthm package provides an enhanced version of LaTEX’s \newtheorem command for defining
theorem-like environments, recognizing \theoremstyle specifications and providing a proof
environment.
https://www.ams.org/arc/tex/amscls/amsthdoc.pdf[4] ———. AMS Author Handbook (website). Providence, Rhode Island, 2021.
Entry point to documentation and support packages for preparing articles and books for publication with the American Mathematical Society.

https://www.ams.org/arc/handbook/index.html[5] American Mathematical Society and LaTEX Project. User’s Guide for theamsmath Package (Version 2.1), 2020.
The amsmath package, developed by the American Mathematical Society, provides many additional features for mathematical typesetting. It is now maintained by the LaTEX Project team.
Locally available via: texdoc amsmath[6] American Psychological Association. Publication Manual of the American
Psychological Association. APA, 7th edition, 2020.
The official style guide of the American Psychological Association (APA) for the preparation ofmanuscripts for publication, as well as for writing student papers, dissertations, and theses.

https://apastyle.apa.org/

BIBLIOGRAPHY[7] Anonymous. “‘thanks’ note (footnote) placed below right column even though
there is enough space on the left”. StackExchange, 2012.
An example of a question on a strange footnote placement by LaTEX. The answers explains someof the reasons why this can happen.
https://tex.stackexchange.com/questions/43294[8] Apple Inc. “TrueType Reference Manual”, 2019.
Apple’s reference manual for the TrueType font format.

https://developer.apple.com/fonts/TrueType-Reference-Manual[9] Donald Arseneau. url.sty—Version 3.4, 2016.
Documentation provided by Robin Fairbairns (1947–2022).

Locally available via:

texdoc url[10] Michael Barr. A new diagram package, 2016.
A rewrite of Michael Barr’s original diagram package to act as a front end to Rose’s xypic; see [55,
Chapter 7]. It offers a general arrow-drawing function; various common diagram shapes, such as
squares, triangles, cubes, and 3 × 3 diagrams; small 2-arrows that can be placed anywhere in a
diagram; and access to all of xypic’s features.
Locally available via: texdoc diagxy[11] Claudio Beccari and Apostolos Syropoulos. “New Greek fonts and the greek
option of the babel package”. TUGboat, 19(4):419–425, 1998.
Describes a new complete set of Greek fonts and their use in connection with babel’s greek
extension.
https://tug.org/TUGboat/tb19-4/tb61becc.pdf[12] Nelson Beebe. “Bibliography prettyprinting and syntax checking”. TUGboat,
14(4):395–419, 1993.
This article describes three software tools for BIBTEX support: a prettyprinter, syntax checker, andlexical analyzer for BIBTEX files; collectively called bibclean.

https://tug.org/TUGboat/tb14-4/tb41beebe.pdf[13] Barbara Beeton. “Mathematical symbols and Cyrillic fonts ready for distribution”. TUGboat, 6(2):59–63, 1985.
The announcement of the first general release by the American Mathematical Society of the Euler
series fonts.
https://tug.org/TUGboat/tb06-2/tb11beet.pdf[14] Alexander Berdnikov, Olga Lapko, Mikhail Kolodin, Andrew Janishevsky, andAlexei Burykin. “Cyrillic encodings for LaTEX 2ε multi-language documents”.
TUGboat, 19(4):403–416, 1998.
A description of four encodings designed to support Cyrillic writing systems for the multilanguage mode of LaTEX 2ε . The “raw” X2 encoding is a Cyrillic glyph container that allows one toinsert into LaTEX 2ε documents text fragments written in any of the languages using a modern
Cyrillic writing scheme. The T2A , T2B , and T2C encodings are genuine LaTEX 2ε encodings that
may be used in a multi-language setting together with other language encodings.

https://tug.org/TUGboat/tb19-4/tb61berd.pdf[15] Jens Berger. “The jurabib Package”, 2017.
Manual for the jurabib package, translated to English by Maarten Wisse.
Locally available via:

texdoc jurabib[16] Karl Berry. “Filenames for fonts”. TUGboat, 11(4):517–520, 1990.
This article describes the consistent, rational scheme for font file names that was used for atleast the next 15 years. Each name consists of up to eight characters (specifying the foundry,
typeface name, weight, variant, expansion characteristics, and design size) that identify each font
file in a unique way.
https://tug.org/TUGboat/tb11-4/tb30berry.pdf
The latest version of this scheme is available at: https://tug.org/fontname/html/[17] Javier Bezos. The accents Package, 2019.
Miscellaneous tools for mathematical accents: to create faked accents from non-accent symbols,
to group accents, and to place accents below glyphs.
Locally available via: texdoc accents796

BIBLIOGRAPHY[18] ———. Customizing lists with the enumitem package, 2019.
Extended and customizable list environments.

Locally available via:

texdoc enumitem[19] Javier Bezos and Johannes Braams. Babel — Localization and internationalization — TEX, pdfTEX, XETEX, LuaTEX, 2023.
The official user manual for Babel, describing how to use it with different flavors of TEX. A second
part covers the complete source code documentation.
Locally available via: texdoc babel[20] Charles Bigelow. “Oh, oh, zero!” TUGboat, 34(2):168–181, 2013.
A survey of attempts to make “O”, “0”, and similar look-alike characters distinguishable inhistorical and modern typography.

https://tug.org/TUGboat/tb34-2/tb107bigelow-zero.pdf[21] ———. “About the DK versions of Lucida”. TUGboat, 36(3):191–199, 2015.
A description of the design of the Lucida DK fonts and their history, developed as a response to[98].
https://tug.org/TUGboat/tb36-3/tb114bigelow.pdf[22] The Bluebook: A Uniform System of Citation. The Harvard Law Review
Association, Cambridge, MA, 21st edition, 2020. ISBN 978-0-578-66615-0.
The Bluebook contains three major parts: part 1 details general standards of citation and style
to be used in legal writing; part 2 presents specific rules of citation for cases, statutes, books,
periodicals, foreign materials, and international materials; and part 3 consists of a series of tables
showing, among other things, which authority to cite and how to abbreviate properly.
Can be ordered at: https://www.legalbluebook.com[23] Johannes Braams. “Babel, a multilingual style-option system for use withLaTEX’s standard document styles”. TUGboat, 12(2):291–301, 1991.
The babel package was originally a collection of document-style options to support different
languages. An update was published in TUGboat, 14(1):60–62, April 1993.

https://tug.org/TUGboat/tb12-2/tb32braa.pdf
https://tug.org/TUGboat/tb14-1/tb38braa.pdf[24] Peter Breitenlohner et al. “The eTEX manual (version 2)”, 1998.
The current manual for the eTEX system, which extends the capabilities of TEX while retaining
compatibility. While the eTEX engine is considered obsolete these days, its extensions have been
implemented in all major modern systems and LaTEX expects them to be available. Thus, thedocumentation remains relevant.
Locally available via: texdoc etex[25] Robert Bringhurst. The elements of typographic style (20th Anniversary
edition). Hartley & Marks Publishers, Point Roberts, WA, USA, and Vancouver,
BC, Canada, 4th edition, 2013. ISBN 0-88179-212-8 (hardcover).
A very well-written book on typography with a focus on the proper use of typefaces.

[26] ———. Palatino — The Natural History of a Typeface. David R. Godine,
Publisher, Boston, 2016. ISBN 978-1-56792-572-2.
Palatino is one of the most widely used typefaces today. Designed by Hermann Zapf (1918–2015),
it has been used as a model for many other typefaces. This book discusses its evolution andhistory and is a fascinating read if you are interested in type design.

[27] Bureau International des Poids et Mesures. SI Brochure: The International
System of Units (SI), 9th edition, 2019.
The 9th edition of the brochure explaining and promoting the International System of Units (SI) —the preferred system of units for science, technology, industry and trade. Available in English
and French.
https://www.bipm.org/en/publications/si-brochure/797

BIBLIOGRAPHY[28] Judith Butcher, Caroline Drake, and Maureen Leach. Butcher’s Copy-editing:
The Cambridge Handbook for Editors, Copy-editors and Proofreaders. Cambridge University Press, New York, forth edition, 2006. ISBN 0-521-40074-0.
A reference guide for all those involved in the process of preparing typescripts and illustrations
for printing and publication. The book covers all aspects of the editorial process, from the basics
of how to mark a typescript for the designer and the typesetter, through the ground rules ofhouse style and consistency, to how to read and correct proofs.

[29] Florian Cajori. A History of Mathematical Notations. Dover Publications, New
York, 1993. ISBN 978-0-486-67766-8.
This classic book on mathematical notations, originally published in two volumes in 1928–1929,
devotes a full chapter to several numeral systems from antiquity, including Greek.

[30] David Carlisle. “A LaTEX tour, Part 1: The basic distribution”. TUGboat,17(1):67–73, 1996.
A “guided tour” around the files in the basic LaTEX distribution. File names and paths relate to thefile hierarchy of the CTAN archives.
https://tug.org/TUGboat/tb17-1/tb50carl.pdf[31] ———. “A LaTEX tour, Part 2: The tools and graphics distributions”. TUGboat,17(3):321–326, 1996.
A “guided tour” around the “tools” and “graphics” packages. Note that The Manual [106] assumes
that at least the graphics distribution is available with standard LaTEX.

https://tug.org/TUGboat/tb17-3/tb52carl.pdf[32] ———. “A LaTEX tour, Part 3: mfnfss, psnfss and babel”. TUGboat, 18(1):48–55,
1997.
A “guided tour” through three more distributions that are part of the standard LaTEX system. The
mfnfss distribution provides LaTEX support for some popular METAFONT-produced fonts that
do not otherwise have any LaTEX interface. The psnfss distribution consists of LaTEX packages giving
access to PostScript fonts. The babel distribution provides LaTEX with multilingual capabilities.

https://tug.org/TUGboat/tb18-1/tb54carl.pdf[33] ———. “xmltex: A non validating (and not 100% conforming) namespaceaware XML parser implemented in TEX”. TUGboat, 21(3):193–199, 2000.
xmltex is a an XML parser and typesetter implemented in TEX, which by default uses the LaTEX
kernel to provide typesetting functionality. https://tug.org/TUGboat/tb21-3/tb68carl.pdf[34] David Carlisle, editor. Mathematical Markup Language (MathML) Version 4.0.
W3C, 1st edition, 2023.
This is the draft specification for a new version of the Mathematical Markup Language; the current
version is 3.0 [35]. MathML4 extensions primarily relate to improving accessibility, with new
attributes for improving audio rendering.
https://www.w3.org/TR/mathml4/[35] David Carlisle, Patrick Ion, and Robert Miner, editors. Mathematical Markup
Language (MathML) Version 3.0. W3C, 2nd edition, 2014.
This is the current specification defining the Mathematical Markup Language; the upcoming
version will be [34]. MathML is an XML vocabulary for mathematics, designed for use in browsers
and as a communication language between computer algebra systems. The goal of MathML is toenable mathematics to be served, received, and processed on the World Wide Web, just as HTMLhas enabled this functionality for text.
https://www.w3.org/TR/MathML3/[36] David Carlisle, Patrick Ion, Robert Miner, and Nico Poppelier, editors. Mathematical Markup Language (MathML) Version 2.0. W3C, 2nd edition, 2003.
This is the previous version of the MathML standard [35].

798https://www.w3.org/TR/MathML2/

Index of Commands
and Concepts

This title somewhat hides the fact that everything (for both volumes) except for namesof people is in this one long comprehensive index. To make it easier to use, the entries
are distinguished by their “type”, and this is often indicated by one of the following“type words” at the beginning of the main entry or a subentry:
attribute, BIBTEX/biber command, BIBTEX entry type, BIBTEX field, BIBTEX style,boolean, counter, document class, env., file, file extension, folio style, fontencoding, hook, key/option, keyword, key, language, length, library, mathaccent, math symbol, option, package, page style, program, rigid length,
syntax, text accent, text symbol, text/math symbol, TEX counter, or value.
Most “type words” should be fairly self-explanatory, but a few need some explanation
to help you find the entries you are looking for.
‘option’ and ‘keyoption’ Both type words indicate that the keyword can be usedin the optional argument of \usepackage . If the option accepts a value, it ismarked as a ‘keyoption’ and otherwise as a classic ‘option’. Most packages with‘keyoptions’ also offer configuration commands that can be used in the preamble
or in the document body — see also next types.
‘key’ and ‘value’ Many modern LaTEX packages implement a key/value syntax (i.e.,⟨key1 ⟩ = ⟨value1 ⟩,⟨key2 ⟩ = ⟨value⟩, . . . ) as part of the optional argument to\usepackage , in arguments of commands or environments, or both. Keywords
that can appear to the left of the equal sign are indicated by the type word ‘key’ (oras type ‘keyoption’ if allowed in \usepackage), those that can appear to the right~ type words
used in the index

INDEX OF COMMANDS AND CONCEPTS

as ‘value’. Sometimes keywords can appear on either side, depending on context,
in which case they are indexed according to their use on the particular page.1‘syntax’ Keywords and strings marked with ‘syntax’ can appear in arguments ofcommands but are not part of a key/value pair.
‘counter’ and ‘TEX counter’ Names marked as ‘counter’ are LaTEX counters and arealtered with \setcounter , etc., while ‘TEX counters’ start with a backslash anduse a low-level method for modification.
‘length’ and ‘rigid length’ A ‘length’ register can take values with a plus and minus
component, i.e., can stretch or shrink. In contrast, a ‘rigid length’ stores only afixed value. Most lengths in LaTEX are flexible, i.e., not rigid.
‘text symbol’, ‘math symbol’, and ‘text/math symbol’ A command is classified asa ‘text symbol’ if it typesets a glyph for use in text, whereas a ‘math symbol’ canbe used only in math mode and produces an error elsewhere. A few symbols areallowed everywhere and are therefore of type ‘text/math symbol’.
In most cases, the actual symbol is also shown in the index entry to help you
find the symbol you are looking for more easily (the command names are notalways obvious). Note, however, that the glyph shown is only an approximationof reality — in your document it may come out differently depending on the fonts
you use.
no type word indication The absence of an explicit “type word” means that the“type” is either a core LaTEX command or simply a concept.
If a particular index entry is defined or used in a special way by a package, thenRelation  this is indicated by adding the package name (in parentheses) to an entry or subentry.
to packages or
If package aaa builds upon or extends package bbb, we indicate this with (aaa/bbb).
programs There is one “virtual” package name, tlc, which indicates commands introduced only

for illustrative purposes in this book. Again, you may see (tlc/bbb), if appropriate.
The index contains all entries for both volumes. To which pages the references
Interpreting  point is indicated by →I (for part one) and →II (for part two). To save space, thesepage referencesindicators are given only once in each entry. An italic page number indicates that thecommand or concept is demonstrated in an example on that page. When there areseveral page numbers listed, blue boldface indicates a page containing important
information about an entry, such as a definition or basic usage. However, bold is(normally) not used for concept entries, when all entries are of equal importance, or
when there is only one page reference.
When looking for the position of an entry in the index, you need to realize that
Sorting  both of the characters \ and . are ignored when they come at the start of a commandwithin the index
or file extension. Other syntax entries starting with a period are listed in the Symbols
section. Otherwise, the index entries are sorted in ASCII order, and the running header
gives you an indication where you are in the index. For the rather lengthy Symbols
section at the beginning of the index, this is unfortunately of little help because only
a few people would know the symbol order in the ASCII encoding. We therefore show
the order of symbols in the margin on those pages.
1 This explains why you might find the same keyword under both type words, but given that one isusually interested only in one type of usage, this distinction is made. This distinction also exhibits
the fact that different packages use the same keywords in different ways — an unfortunate side effectof the long history of LaTEX package development by independent developers.

818

(Symbols)

Symbols( syntax! math symbol !, →II 213! syntax, →I 453, 507, 509f., 516(BIBTEX|biber), →II 401(MakeIndex |upmendex), →II 357\(, →II 195
error using, →II 718(ifthen), →II 693(soul), →I 195(⟨coord⟩) syntax (tikz), →I 633, 634–646(⟨expr⟩) syntax(fp expr), →II 659(int expr), →II 659) math symbol ), →II 190, 223) syntax(BIBTEX|biber), →II 401(MakeIndex |upmendex), →II 357\), →II 195
error using, →II 718(ifthen), →II 693(soul), →I 195* (asterisk) as error message, →II 717* math symbol ∗, →II 215* syntax, →I 436, 447, 454f., →II 672(fp expr), →II 658, 659(int expr), →II 659(length expr), →I 447(abraces), →II 185(array), →I 439(askinclude), →I 30(biblatex), →II 563(bigdelim), →II 159(calc), →I 370, →II 687, 688, 690, 692(docstrip), →II 591(enumitem), →I 272, 273(fontspec), →I 709(hhline), →I 470(listings), →I 324, 325(microtype), →I 135(multirow), →I 477(snotez), →I 236(tasks), →I 291, 292(tikz), →I 637(typed-checklist), →I 295* value (babel), →II 331f.

(cmd/env decl), →II 634, 638ff.
error using, →II 728
with b argument, →II 642(fp expr), →II 658(MakeIndex |upmendex),→II 347, 348, 349, 355f., 357, 360(abraces), →II 185(array), →I 439, 442, 443, 453, 495(askinclude), →I 30(babel), shorthand character, →II 312, 313(docstrip), →II 591(enumitem), →I 271f., 274(xcolor), →I 17, 102f., 105, 147, 227, 239, 312, 501f.,
596f., 599, 615, 619, 627, 629ff., 641, 645,
→II 175, 645\!, →II 184, 205, 676(tipa), →II 126!= syntax (fp expr), →II 658!‘ syntax, →I 193, 196, 757(fontspec), →I 720, 721!⟨waypoint⟩! syntax (tikz), →I 635" syntax, →I 669, 670
wrong usage in quotes, →I 179(BIBTEX|biber), →II 381, 401(MakeIndex |upmendex), →II 348, 349, 357, 360(babel), shorthand character,→II 310, 311, 312, 330, 354, 360(pifont), →II 114¨ , →I 747, 762, 765, 768, →II 360\" text accent □"" syntax (babel), →II 312"’ syntax (babel), →II 303, 311"- syntax (babel), →II 305, 312"< syntax (babel), →II 311"= syntax (babel), →II 305, 312"> syntax (babel), →II 311"⟨accented letter⟩ syntax (babel), →II 323"⟨letter⟩ syntax(babel), →II 310, 311, 323(yfonts), →II 105"⟨math⟩" syntax (tikz-cd), →II 161, 162"~ syntax (babel), →II 312"‘ syntax (babel), →II 303, 311"| syntax (babel), →II 311’ syntax, →I 669, →II 114(BIBTEX|biber), →II 401(abraces), →II 185, 188(babel), shorthand character, →II 319, 330(tikz-cd), →II 162, 163´ , →I 434, 769, →II 126\’ text accent □redefined in tabbing, →I 433, 434\’, definition for tabbing, →I 433’’ syntax, →I 179(fontspec), →I 721( math symbol (, →II 190, 223\*(doc), →II 596(tipa), →II 126*2 syntax (snotez), →I 236*⟨letter⟩ syntax (yfonts), →II 105+ math symbol +, →II 215+ syntax(cmd/env decl), →II 634, 641, 642, 735
error using, →II 728(fp expr), →II 658, 659(int expr), →II 659(length expr), →I 447(calc), →I 257, 370, 373, 401, →II 632, 661, 666, 687(docstrip), →II 591(fontspec), →I 723

819

!
"
’
(
)
*
+
’
.
/
:
;
<
=
>
?
@
[
#
%
&
$
_
\
^
~
{
}
␣
]
‘
|

(Symbols)

!
"
’
(
)
*
+
’
.
/
:
;
<
=
>
?
@
[
#
%
&
$
_
\
^
~
{
}
␣
]
‘
|

+ syntax (cont.)-- syntax, →I 149, 150, 757(hvfloat), →I 560, 565, 566(keyvaltable), →I 504(tikz), →I 634(tlc/dcolumn), →I 484\+, error using, →II 741+( syntax (int expr), →II 659+(⟨coord⟩) syntax (tikz), →I 635, 637f.
++(⟨coord⟩) syntax (tikz), →I 635, 637, 640f.
+- syntax (siunitx), →I 168+0pt syntax (tikz), →I 634+x syntax (chmod), →II 616, math symbol ,, →II 223, syntax(BIBTEX|biber), →II 381, 401(abraces), →II 185, 186, 188(fcolumn), →I 489f.
(siunitx), →I 168, 170, 173(tlc/dcolumn), →I 482ff.
\,, →I 210, 406, 485, 488,
→II 157, 184, 186, 204f., 210, 261, 475, 762
in math, →II 135f., 147, 155f., 159, 164, 168, 181,, syntax (cleveref), →I 87- hyphen, →I 149f.
nonbreaking, →I 150, 199- math symbol −, →II 215- syntax, →I 149f.
(fp expr), →II 658, 659(int expr), →II 659(length expr), →I 447(askinclude), →I 30(calc), →II 667, 670, 687, 688ff.
(dashundergaps), →I 191(docstrip), →II 591(fontspec), →I 722, 723(hhline), →I 470, 471(typed-checklist), →I 295\-, →I 150, 443, 446, →II 312, 774, 776
error using, →II 741
in tabbing, →I 433(soul), →I 194, 195(ulem), →I 189, 190-( syntax (int expr), →II 659-* syntax, →I 702-+ syntax (siunitx), →I 168\-/ (extdash), →I 150-> syntax (tikz), →I 635, 637f., 640, 641f., 644-Inf syntax, →II 6, 9
-L option (MakeIndex), →II 355, 364-LF syntax, →I 702, →II 6, 7, 10-M option (bibtex8), →II 407-NoValue- syntax, →II 633ff., 639, 640ff.
-OsF syntax, →I 700, 702, →II 6, 10-Sup syntax, →II 6, 9
-T option (MakeIndex), →II 355, 364-TLF syntax, →I 702, →II 6, 7
-TOsF syntax, →I 702, →II 6(Lua), →II 607(fontspec), →I 720, 721(tikz), →I 634f., 636, 637–644, 645f.
\-- (extdash), →I 150--- syntax, →I 149, 150f., 193, 669, 757(fontspec), →I 720, 721\--- (extdash), →I 150, 151--backend option (checkcites), →II 414--cmd-tex option (mkjobtexmf), →I 114--config option (bundledoc), →I 113--copy option (mkjobtexmf), →I 114--destdir option (mkjobtexmf), →I 114--engine option (l3build), →II 607, 611--exclude option (bundledoc), →I 112--file option (l3build), →II 612--flat option (mkjobtexmf), →I 114--force-copy option (mkjobtexmf), →I 114--full option (l3build), →II 608--help option(biber), →II 380(mkjobtexmf), →I 114--include option (bundledoc), →I 112, 113--input-encoding option (biber), →II 399--jobname option (mkjobtexmf), →I 114--keepdirs option (bundledoc), →I 113--localonly option (bundledoc), →I 112f.
--match option (git), →II 617--message option (l3build), →II 612--min-crossrefs option (BIBTEX), →II 407--min_crossrefs option (bibtex8), →II 407--mincrossrefs option (biber), →II 407--output-align option (biber), →II 380, 418--output-field-replace option (biber), →II 380--output-fieldcase option (biber), →II 380--output-file option (biber), →II 380--output-format option (biber), →II 417--output-resolve option (biber), →II 405--output-safechars option (biber), →II 399--sys syntax (getnonfreefonts), →II 4--texname option (mkjobtexmf), →I 114--tool option (biber), →II 380, 399, 405, 418--user syntax (getnonfreefonts), →II 4--validate-datamodel option (biber), →II 418--verbose option(bundledoc), →I 112(mkjobtexmf), →I 114-all option (kpsewhich), →II 730, 785, 786-c option (MakeIndex |upmendex), →II 346, 351, 363, 364-d option (upmendex), →II 364, 365-debug option (kpsewhich), →II 786-e option (l3build), →II 607, 611-engine option (kpsewhich), →II 730, 786-f option (upmendex), →II 364, 365-g option(MakeIndex), →II 354, 363(upmendex), Japanese specific, →II 363f., 365-help option (kpsewhich), →II 786

820

PeopleAbbink, Mike, →II 30, 96
Abbott, Peter, →II 789
Achilles, Alf-Christian, →II 413
Adriaens, Hendri, →I 275
Aguilar-Sierra, Alejandro, →II 379
Alessi, Robert, →II 63, 341
Aluthge, Dilum, →II 458
André, Jacques, →I ii
Arseneau, Donald, →I 30, 125, 146,
152, 189, 198, 214, 405,
407, 434, 467, 492, 524,
536, 675,→II 157, 173, 189, 207,
478, 483, 485, 571, 796
ASAKURA, Takuto, →II 786
Ashton, James, →II 372
Avdeev, Nikolai, →II 378, 456
Ball, Alex, →II 444, 452
Barr, Michael, →II 160, 796
Barroca, Leonor, →I 534
Baskerville, John (1706–1775),→II 47
Basso, Pierre, →II 578
Beccari, Claudio, →I 454,
→II 328, 796
Beebe, Nelson, →I xli, →II 226,
413ff., 417, 419, 796
Beeton, Barbara, →I ii, →II 226, 796
Beffara, Emmanuel, →I 286Belaïche, Vincent, →I 154, →II 814

Benguiat, Ed, →II 49, 69
Benton, Morris Fuller (1872–1948),→II 35, 54, 61, 81
Berdnikov, Alexander, →II 324, 796
Berger, Jens, →II 507, 796
Berner, Conrad, →II 41
Berry, Karl, →II 785, 796, 813
Berthold, Hermann, →II 53
Beyene, Berhanu, →II 341
Bezos, Javier, →I xli, 26, 40, 59,
261, →II 177, 300, 796f.
Bigelow, Charles, →I 302,
→II 15, 21, 24, 53, 89, 92,
95, 278, 797
Bitouzé, Denis, →II 461
Bodoni, Giambattista (1740–1813),→II 60f.
Bonislawsky, Brian J., →II 99
Bosma, Jelle, →II 49
Bossert, Lukas C.,→II 446, 452ff., 457
Böttcher, Stephan, →I 334
Bovani, Michel, →II 59, 119, 283
Braams, Johannes, →I xli, 3, 251,
371, 374, 456, →II 300,
584, 600, 797, 810, 975
Brailsford, David, →I ii
Braun, Ingram, →II 446
Breger, Herbert, →II 813
Breitenlohner, Peter (1940–2015),→II 797
Bringhurst, Robert,→I 188f., 216, →II 797
Brodowski, Dominik, →II 465
Brooks, Moses, →II 802
Budyta, Małgorzata, →II 77, 79
Bühmann, Andreas, →I 649, 669
Burykin, Alexei, →II 796
Butcher, Judith, →II 798
Caignaert, Christophe, →II 17f., 267
Callegari, Sergio, →I 409
Camps, Jean-Baptiste, →II 453
Carlisle, David, →I 3f., 40, 94ff.,
153, 178, 275, 377, 384,
396, 437, 448, 450, 459,
466, 470, 481, 525, 532,
603, 676,→II 157, 235, 600, 689,
784, 792, 798f., 809f.
Carnase, Tom, →II 69
Carroll, Lewis (1832–1898), →I 428
Carter, Matthew, →II 50
Caslon, William (1692–1766),→II 51
Casteleyn, Jean Pierre, →I 646,
→II 799
Cereda, Paulo, →I 628f., 645,
→II 414, 651
Chang, Bettina, →II 799

PEOPLE

Charette, François,→II 376, 379, 803
Chase, Brian, →II 445
Chen, Pehong, →II 799
Chou, Yukai, →I 284
Clawson, James, →II 443
Cochran, Steven, →I 546, 551
Coleman, Jack, →I 363
Corff, Oliver, →II 341
Cosell, Bernie, →I 675
Covington, Michael, →I 302
Cubitt, Toby, →I 86
Cummings, Melbourne, →I xxxvii
Dachian, Serguei, →II 341
Dahlmann, Carsten Ace, →II 455
Dair, Carl (1912–1967), →II 799
Dalalyan, Arnak, →II 341
Daly, Patrick, →I ii, 27,→II 426, 490, 537, 806
Daniel, Marco, →I 286, 614, →II 458
del Peral, Juan Pablo, →II 11
Descartes, René (1595–1650),→II vii
Di Cosmo, Roberto, →II 464
Didot, Firmin (1764–1836),→II 42, 60, 62, 107
Dirac, Paul, →II 173
Domanov, Oleg, →II 441
Dorj, Dorjpalam, →II 341
Dossena, Riccardo, →II 220
Douros, George, →II 42
Downes, Michael (1958–2003),→I 3, 111, 281, →II 128,
133, 146, 180, 799
Drucbert, Jean-Pierre (1947–2009),→I 95
Drümmer, Olaf, →II 799
du Carrois, Ralph, →II 14
Duchier, Denys, →I 3,→II 584, 600, 810
Duffner, Georg, →II 41, 265
Duggan, Angus, →I 302
Dunn, Brian, →I 56, 567, →II 984
Dziedzic, Łukasz, →II 80
Eckermann, Matthias, →I 339
Eggers Sørensen, Claus, →II 64
Eijkhout, Victor, →I 30, →II 800

968

El Morabity, Mohamed, →II 27, 80
Els, Danie, →I 471, →II 178
Esbati, Arash, →II 70, 86, 90
Esser, Thomas, →II 786
Evans, Richard, →II 374
Fairbairns, Robin (1947–2022),→I 138, 210, 387,
→II 787, 790, 796
Farář, Pavel, →II 13, 32
Fear, Simon, →I 471
Fernández, José Alberto, →II 574
Feuersänger, Christian, →I 637
Fine, Michael, →I 251
Fischer, Ulrike, →I xli, →II 651, 810
Flipo, Daniel, →I 5, 141,
→II 17f., 267
Flynn, Peter, →I ii
Fournier, Pierre-Simon, →II 35, 50Franz, Melchior, →I 192, 411
Frutiger, Adrian (1928–2015),→II 87, 89, 91
Fuenzalida, Rodrigo,→II 47, 61, 81, 86
FUJITA, Shinsaku, →I 612, →II 800
FUKUI, Rei, →II 125, 800
Fussner, David, →II 440
Gama, Natanael, →II 98
Garamond, Claude (1499–1561),→II 38, 41f., 265
Gardzielewski, Zygfryd, →II 100
Gäßlein, Hubert, →I 603
Gatti, Héctor, →II 70, 86
Gaulle, Bernard (1946–2007),→II 341
Gaultney, Victor, →II 45
Gelderman, Maarten, →II 800
Gesang, Philipp, →I 706
Gibbons, Jeremy, →II 209
Gill, Eric (1882–1940), →II 70, 75
Gladkikh, Ivan, →II 73
Goel, Anil K., →I 463
Goldberg, Jeffrey, →I 386, 525
Goossens, Michel, →I xl,→II 800f., 810
Gordon, Peter, →I xxxviif., xli,
→II vi, 974
Göttlinger, Merlin, →II 458

Goudy, Frederic (1865–1947),→I 191
Graham, Ronald, →II 801
Grahn, Alexander, →I 107
Granjon, Robert (1513–1589),→II 42
Grätzer, George, →II 127, 801
Gray, Norman, →II 390
Greenwade, George (1956–2003),→II 789, 801
Gregorio, Enrico, →I 95, 362,
→II 414Grewe, Richard, →I 293, 494
Grießhammer, Frank, →II 35
Grundlingh, Werner, →II 185
Gundlach, Patrick, →II 775
Gurari, Eitan (1947–2009), →II 801
Hagen, Karl, →I 361
Hailperin, Max, →I 387
Hakobian, Vardan, →II 341
Hansen, Thorsten, →II 574, 580
Hanslow, Paul, →II 57
Happel, Patrick, →I 361
Haralambous, Yannis, →I 652,
→II 104, 299, 802, 812
Harcombe, Keiran, →I 688
Harders, Harald, →II 240, 372, 390
Hardy, Matthew, →I ii
Harendal, Hirwen,→II 39, 48, 75, 82, 87, 118
Harrison, Keith, →I xliv, →II 374
Harrison, Michael, →II 799
Hart, Horace (1840–1916), →II 802
Hefferon, Jim, →I 286, →II 790
Heinz, Carsten, →I 323, →II 802
Hellström, Lars, →II 2, 803
Helminck, Aloysius, →II 251
Helvensteijn, Michiel, →II 189
Hendrickson, Anders, →I 612
Henel, Yvon, →I 40
Henestrosa, Cristobal, →II 15
Henlich, Thomas, →II 117
Heslin, Peter, →I 148
Hoffmann, Jobst, →I 323, →II 802
Hofstra, Silke, →II 35, 86
Hoftich, Michal, →II 442, 984
Høgholm, Morten, →I 164, →II 130,
146, 174, 799, 802

PEOPLE

Holmes, Kris, →I 302,
→II 15, 21, 95, 278
Hosny, Khaled, →I 706, →II 19, 45,
94, 275, 280, 813
Hudson, John, →II 57
Hufflen, Jean-Michel, →II 802
Hughes, Chelsea, →I 226
Hunt, Paul D., →II 35
Huỳnh, Kỳ-Anh, →II 164
Impallari, Pablo, →II 33, 47, 51, 61,
70, 81, 86
Ion, Patrick, →II 798
Jabri, Youssef, →II 323, 341
Jackowski, Bogusław,→I 686, 688, 746, →II 271,
273, 275, 280, 284, 288
Janishevsky, Andrew, →II 324, 796
Jeffrey, Alan, →I 3, 5,→II 1, 209, 227, 234, 803
Jensen, Frank, →II 239, 241, 687
Johnston, Edward, →II 70
Jones, David, →II 128, 372, 499
Jørgensen, Palle, →II 2, 803
Jurriens, Theo, →I 456
Just, Jérémy, →II 788
Kant, Immanuel (1724–1804),→I 363
Kastrup, David,→I 212, 218, 220, 459
Katsoulidis, Takis, →II 39, 61f.
Kehr, Roger, →II 370
Kelkel, Thomas, →II 775
Kemper, Thorsten, →II 452
Kempson, Niel, →II 379, 571
Kettler, Howard (1919–1999),→II 91
Khalighi, Vafa, →II 332, 686
Khodulev, Andrey, →II 326
Kielhorn, Axel, →II 116
Kime, Philip, →II 376, 435, 439, 803
Kimura, David, →II 15
Kirsch, Daniel, →II 113
Kleber, Josef, →I 250
Kleinod, Ekkart, →I 245
Klever, Jan, →I 38

Knappen, Jörg, →I 685, 694,
→II 803
Knuth, Donald, →I ii, xxxvii, 1f.,
120, 126, 202, 212, 332,
421, 650, 653, 680, 684,
705, 737, →II 24, 60, 65,
125, 128, 219f., 229, 243,
253, 287f., 298, 407, 584,
793, 801, 803ff., 816
Kobayashi, Akira, →II 71
Kohm, Markus, →I 56, 234, 375,
429, →II 805
Kolodin, Mikhail, →II 324, 796
Kopka, Helmut (1932–2009),→I ii, →II 806
Kopp, Oliver, →II 458
Korolkova, Alexandra, →II 31, 96
Kosch, Sebastian, →II 40, 263
Kotucha, Reinhard, →II 3, 786
Kryukov, Alexey, →II 56, 62f.
Krüger, Marcel, →I 194, →II 120
Kudlek, Manfred, →II 341
Kummer, Olaf, →II 228, 341
Küster, Frank, →II 786
Kuznetsova, Lyubov, →II 53
Kwok, Conrad, →I 608
Lagally, Klaus, →II 341, 806
Lamport, Leslie, →I ii, xxxvii, xxxix,
2, 211, 298, 368, 389,
456, →II vi, 372, 470,
689, 789, 806, 813, 973
Lamy, Jean-François, →I 374
Lapko, Olga, →II 326, 796
LaTEX Project Team, →I xl, 3–8, 96,
103, 115, 645, →II 128,
131, 324, 583, 606,
608f., 632, 686, 784,
787, 789, 802, 806f.,
810, 812, 973, 975f.
Lavagnino, John, →I 228, →II 813
Lavva, Boris, →II 341
Lawrence, Steve, →II 413
Le Bailly, Jacques, →II 40
Le Floch, Bruno, →II 734, 980
Lehman, Philipp, →I 179,
→II 435, 541, 803, 807
Leichter, Jerry, →I 474, 476
Lemberg, Werner, →II 324, 341, 807

Levien, Raph, →II 92
Levy, Silvio, →II 328, 807
Liang, Franklin, →II 807
Lickert, Knut, →I 363
Lingnau, Anselm, →I 529
Liu, Leo, →I 479
Longborough, Brent (1944–2021),→I 30, →II 616
Loreti, Maurizio, →II 119
Lubalin, Herb, →II 69
Lück, Uwe (1962–2020), →I 334
Luecking, Dan, →II 182
Lyles, Jim, →II 12
Lyu, Jianrui, →I 504, →II 807
Maag, Dalton, →II 82
Madsen, Lars, →I 430, 492,
→II 130, 172, 174
Manutius, Aldus (1449–1515),→II 38Marini, Igino, →II 99
Markey, Nicolas, →II 16, 808
Matas, Sol, →II 65
Matteson, Steve, →II 26, 49, 57, 68
May, Wolfgang, →I 281
McCauley, James Darrell, →I 525
McDonnell, Rowland, →II 2, 803
McInerney, Matt, →II 86
McLean, Ruari, →II 808
McPherson, Kent, →I 371
Medina Arellano, Gonzalo, →I 147
Menke, Henri, →I 632
Merciadri, Luca, →I 190, 407
Metzinger, Jochen, →II 341
Midtiby, Henrik Skov, →I 237
Miedinger, Max (1910–1980), →II 76
Miklavec, Mojca, →II 338
Milde, Günter, →II 328
Miller, D. Benjamin, →II 42, 265
Mills, Ross, →II 57
Miner, Robert (1968–2011), →II 798
Mittelbach, Frank,→I 3, 79, 138, 190, 210,
228, 283, 351, 424, 437,
512, 648, 728, →II 128,
238, 584, 599, 799ff.,
808–811, 813, 973
Mondal, Agnibho, →II 445
Monday, Bold, →II 30

969

PEOPLE

Monty Python, →II 651
Moore, Ross, →II 801
Morison, Stanley (1889–1967),→II 55
Motygin, Oleg V., →I 94
Muhafara, Dario Manuel, →II 84
Münch, Martin, →I 202, 216, 386f.
Nahil, Julie, →I xliv
NAKASHIMA, Hiroshi,→I 339, 469, →II 811
Neugebauer, Gerd, →II 578
Neukam, Frank, →I 375, 429
Newlyn, Miles, →II 73
Nguyen, Nhung, →II 81
Nicholas, Robin, →II 49
Niederberger, Clemens,→I 156, 188, 217, 228, 235,
289, →II 467, 811f.
Niepraschk, Rolf,→I 463, 593, 603, →II 460
Nikoltchev, Botio, →II 80
NOBUYA, Tanaka, →II 800
Noirel, Josselin, →I 474
Nordhoff, Sebastian, →II 461
Nowacki, Janusz Marian(1951–2020),→I 686, 688, →II 47, 73, 77,
79, 101, 284, 293, 295
Oberdiek, Heiko, →I 30, 96, 104,
114, 195, 384, 602,
→II 206, 211, 217, 221,
304, 686, 812
Oleinik, Phelype, →I 361, →II 651
Olthof, Edgar, →I 487
Oostrum, Pieter van,
→I 398, 476, →II 158
Orlandini, Mauro, →I 614
Pakin, Scott, →I 112, 301, 384, 614,
→II 113, 209, 468, 668,
787, 812
Pandey, Anshuman, →II 341
Panov, Andrey V., →II 58
Pardo, Octavio, →II 41
Pardoin, Octavio, →II 265
Parsloe, Andrew, →II 170
Partl, Hubert, →I 138

970

Patashnik, Oren, →II 376, 378, 406,
801, 812
Peev, Stefan, →II 59
Pégourié-Gonnard, Manuel, →II 786
Peischl, Marei, →I 123
Penninga, Marc, →II 2
Perry, David J., →II 37
Phemister, Alexander (1829–1894),→II 48
Pianowski, Piotr, →II 271, 273, 275,
280, 288
Pilgrim, Mark, →I 362
Plaice, John, →I 652, →II 299, 812
Plancarte, Raul, →II 15
Plass, Michael, →I 120, →II 805
Podar, Sunil, →I 608, →II 812
Poll, Philipp H., →II 19, 94, 275
Półtawski, Adam, →II 46
Poore, Geoffrey, →I 303
Poppelier, Nico, →I 374, →II 798
Puga, Diego, →II 251, 268
Purtill, Mark, →I 4
Purton, David, →II 445
Raab, Susanne (samcarter),→I 645, →II 651
Rahtz, Sebastian (1955–2016),→I vii, 93, 96, 534, 592,
688, 694,→II iii, 113, 800ff., 812
Ratighan, Daniel, →II 72
Raymond, Eric, →II 788
Rees, Clea F., →I 145, →II 118
Reid, Brian, →I 2, →II 812
Reutenauer, Arthur, →II 337
Rhead, David, →I xxxix, xlii, →II 489
Robertson, Christian, →II 34
Robertson, Will, →I ii, 371, 417,
419, 649, 706, 719,
→II 146, 207, 226, 253, 600,
686, 799, 810, 813, 976
Rogers, Bruce (1870–1957), →II 37
Roh, Štěpán, →II 13
Rokicki, Tom, →I 577
Romer, Linus, →II 103
Roncaglia, Federico, →II 73
Rose, Kristoffer (1965–2016),→II 160

Rouquette, Maïeul, →I 212,
→II 461–464, 813
Rowley, Chris, →I ii, 3, 212,
→II 799, 809ff., 813
Rozhenko, Alexander,→I 150, 220f.
Ryan, George, →II 119
Ryu, Young, →II 243f., 248, 268
Samarin, Alexander, →I xl, →II 801
samcarter, synonym; find me
elsewhere in this index
Sanfelippo, Ana, →II 100
Saudrais, Eddie, →II 169
Sauer, Jonathan, →I 339
Scharrer, Martin, →I 299, 595,
→II 617, 619, 686, 813
Schedler, Andreas, →I 281
Schlicht, Robert, →I 127, →II 814
Schmidt, Walter (1960–2021),→I 686, 688,
→II 12, 66, 95, 104,
238–241, 243, 251, 290
Schnier, Thorsten, →II 489
Scholderer, Victor (1880–1971),→II 75, 290
Schöpf, Rainer, →I 3, 5, 301, 368,
648, →II 128, 790, 811
Schrod, Joachim, →II 370, 415, 814
Schröder, Martin, →I 70, 123
Schubert, Elke, →I 614
Schwan, Tobias, →II 466, 536
Schwarz, Norbert, →I 685
Schwarz, Ulrich, →I 284
Sgouros, Tom, →I 233
Sharpe, Michael, →II 2, 20, 29, 38,
40, 44, 47f., 50, 56, 58f.,
83f., 90, 92f., 227, 230,
232, 234, 243f., 249,
252, 263, 265, 268, 271,
274f., 280, 283, 287, 295
Shchukin, Anatolii, →II 53
Shipunov, Alexey, →I 468
Shub, Daniel E., →II 462
Sievers, Martin, →II 460
Simonson, Mark, →II 90
Simske, Steven, →I ii
Slimbach, Robert, →II 40, 58, 283
Smith, Ralph, →II 229

PEOPLE

Sommerfeldt, Axel, →I 116, 525,
529, 535, 540, 551
Sorkin, Eben, →II 25
Spenceley, Kim, →I xli, xliv
Spiekermann, Erik, →I 191,
→II 14, 74, 92, 814
Spitzmüller, Jürgen, →II 455, 467
Spivak, Michael (1940–2020),→II 128
Stacey, Andrew, →I 643, →II 814
Stanley, Paul, →II 467
Steffmann, Dieter, →I 145
Stiff, Paul (1949–2011), →I 122,
→II 814
Stoffel, Augusto, →II 161
Straub, Pablo, →I 30
Strecker, Stefan, →II 460
Strzelczyk, Piotr, →II 271, 273, 275,
280, 288
Sturm, Thomas, →I 614, →II 814
Sullivan, Wayne, →II 813
Sutor, Robert, →II 801
Swanson, Ellen, →II 128, 814
Swift, Matt, →I 675
Syropoulos, Apostolos, →I 688,
→II 271, 328, 341, 796
TAKUJI, Tanaka, →II 364
Talbot, Nicola, →I 154, →II 315, 814
Tantau, Till, →I 632, →II 814
Tennent, Bob, →I 649, →II 2, 7, 11,
14ff., 20, 26f., 30, 34, 37,
39–42, 47, 51, 57, 59,
61f., 64f., 69–72, 75,
81f., 84, 87, 98ff., 252
Thalmann, Christian, →II 41
Thành, Hàn Thế, →I 126, 688,
→II 801f., 814

Thorup, Kresten, →II 687
Tinnefeld, Karsten, →I 38
Tkadlec, Josef, →I 603
Tobin, Geoffrey, →I 140
Tolušis, Sigitas, →I 514
Tschichold, Jan (1902–1974),→II 40Tsolomitis, Antonis, →I 688,
→II 60, 106, 287
Tuominen, Teo, →II 35
Twardoch, Adam, →I xlii, →II 2, 80
Ulanovsky, Julieta, →II 83
Ulrich, Stefan, →I 233, →II 578
UMEKI, Hideo, →I 377, →II 815
Ummels, Michael, →I 649, 669
Umpeleva, Olga, →II 31
Valbusa, Ivan, →II 466
Valiente Feruglio, Gabriel, →II 815
van Oostrum, Pieter, →II 812
Van Zandt, Timothy,→I 30, 297, 303, 614
Vane, Harriet, →I 612
Varela, Gabriela, →II 15
Varoquaux, Gaël, →II 44
Velthuis, Frans, →II 341
Verna, Didier, →I 242, →II 584, 815
Veytsman, Boris, →I 30, →II 455
Vieth, Ulrik, →II 226, 238, 288
Vogel, Martin, →II 117
Volovich, Vladimir, →I 685,
→II 53, 324
Voß, Herbert, →I 303, 463, 560,
708, →II 13, 20, 370, 453,
459f., 466, 536, 815
Waldi, Roland, →II 116

Waßenhoven, Dominik,→II 460, 464, 536
Weh, Tobias, →II 453
Wemheuer, Moritz, →II 437f., 803
Wette, Karl, →I 334
Whitmore, Ben, →II 37
Williams, Graham, →II 815
Williams, Peter, →II 489
Williamson, Hugh, →II 816
Wilson, Alexander (??–1784),→II 42, 107
Wilson, Peter, →I 27f., 34, 39, 55f.,
212, 251, 371, 407, 419,
430, →II 372, 813, 816
Wimsey, Lord Peter, →I 612
Wisse, Maarten, →II 796
Wolczko, Mario, →I 374
Woliński, Marcin, →II 584, 600, 810
Wooding, Mark, →II 584, 600, 810
Wright, Joseph, →I xli, 167, 179,
→II 456–459, 784, 807,
816, 976
Wujastyk, Dominik, →I 212, →II 813
Xue, Ruini, →II 454
YATO, Takayuki, →I 609, →II 686
Yefimov, Vladimir, →II 31
Zapf, Hermann (1918–2015),→I 127,→II 17, 46, 62, 65, 71, 102,
226f., 230, 232f., 240,
268, 288, 797, 805, 816
Zeng, Xiangdong,→II 15, 74, 265, 290
Zhao, Yuansheng, →II 265
Zhenzhen, Hu, →II 441
Ziegler, Justin, →II 816

971

Biographies

Frank Mittelbach
Frank’s interest in the automated formatting of complex documents in general, andin LaTEX in particular, goes back to his university days and has always been a majorinterest, perhaps a vocation, and throughout his IT career certainly a “second job”.
He studied mathematics and computer science at the Johannes Gutenberg University, Mainz, and afterwards joined
EDS, Electronic Data Systems, initially working in a newly
formed group for document processing using TEX and othertools and later on in the system management division.
At the TEX Users Group (TUG) conference at Stanford
University in 1989, he gave a talk about the (many) problems
Stanford, 1989 . . .
with LaTEX 2.09, which led to him and a small team (known
as the LaTEX Project Team) to take on the responsibility for the further development
and maintenance of LaTEX from its original author Leslie Lamport.1 In the capacity oftechnical lead of this project, he has overseen the original major release of LaTEX 2εin 1994 and the 36 (as of this writing) subsequent releases of this software. Right
now he and the team are working on the important multi-year project to make LaTEX
automatically produce tagged PDF and conform to accessibility standards.
When EDS was bought by HP he joined the global Enterprise Service Management
division and eventually worked there as the European lead architect. In 2015 Frank
ended his IT-industry career to fully concentrate on research in automated typesetting
and Open Source software development, in particular on the future development of
the LaTEX typesetting system.
1 The history is briefly discussed in Section 1.1 of this edition; for a listing of all LaT X Project teamE
members through the years see https://latex-project.org/about/team/.

BIOGRAPHIESFrank is author or coauthor of many and varied LaTEX extension packages, such as
AMS-LaTEX, doc, multicol, and NFSS: the New Font Selection Scheme. His publication ofmany technical papers on LaTEX and on general research
results in automated formatting brought him in contact with Peter Gordon from Addison-Wesley. Peterand Frank inaugurated the book series Tools and Techniques for Computer Typesetting (TTCT), with Frankas series editor. The LATEX Companion (1994) was thefirst book of this series, which now includes titles thatcover LaTEX in all its facets.
. . . and three decades later
He is on the board of the International Gutenberg
Society, an international association for the study of the history and development ofprinting technology and font-oriented media, where he focuses on the more recent
period. He is also involved in the print production of the society and in general enjoys
designing and typesetting high-quality documents using computers but also using
traditional letterpress. One of his plans after finishing TLC3 is to typeset a book on
Japanese authored by Peter Gordon. When not involved with typographical questions
or programming Frank enjoys reading (though the books better be of high quality incontent and form), listening to or playing music (he is an amateur bass player), andwinning or losing board games, these days often collaborative ones.
He and his wife Christel live in the Gutenberg city of Mainz; their three grown-up
sons have left by now for new pastures.

Ulrike Fischer
Ulrike Fischer studied mathematics at the University of Bonn.
She wrote her thesis in a rather arcane branch called model
theory with an Atari text processor called Signum but did
not like to have to place lots of sub and superscripts witha mouse. So when seeing an example LaTEX document, she
directly ordered the floppy discs and never looked back.
Quite early she got interested in the internal handlingof fonts and in chess typesetting as she wanted to print thebulletins of chess competitions she organized in her club.
With the help of the first edition of the LATEX Companion, shewrote the chessfss package, which allows users to choose between various chess fonts,
and other chess-related packages.
After university, she moved with her husband to Siegburg and later to Mönchengladbach and worked as an assistant for a deputy of the state parliament of North
Rhine-Westphalia. She found her way into the LaTEX groups on the Internet and enjoyedanswering questions and debugging errors. She also helped her father who after hisretirement as a professor for computer science wrote with LaTEX a number of books
about Salvador Dalí’s illustrations of the Divine Comedy. So when her job ended aftera lost election, she decided to try something new and to work as a LaTEX consultant.

974

BIOGRAPHIESHer interest in fonts continued over the years and led her to accept the job ofmaintaining luaotfload. Talks about accessibility and tagged PDF at Dante and TUG
meetings induced her to work on the tagpdf package and to present it to LaTEX teammembers at a workshop at the TUG meeting in Rio de Janeiro. Both together got her
an invite to join the team in 2018. She had already had many online contacts with theteam members in Usenet groups and chats as well as in person — she met Frank thefirst time at a Dante meeting in Heidelberg, where she talked about how to misusebiblatex as an address database, and he showed her how to eat some Japanese dish —and so accepted without hesitation. She now lives with her husband Gert in Bonn.

Javier Bezos
Javier Bezos is passionate about typography, science, language, and writing systems, as well as about computer programming. A curious person and self-taught by nature, hisinterests are broad, and he has worked in fields like book andjournal publishing, design, radio, and classical music. He is anhonorary member of the Unión de Correctores, the Spanish
professional association of copyeditors.
As a computer programmer, he has developed systems
for both LaTEX and InDesign, including tools for technical documentation, automatic
typesetting and copyediting, XML, and localization. It is this last facet that he develops
most actively as a member of the LaTEX Project Team.
Javier has participated as an author on several style manuals and published thebook Tipografía y notaciones científicas. He is currently working at FundéuRAE, afoundation linked to the Royal Spanish Academy.
Hiking, reading old science books, and watching classic movies are some of his
hobbies.

Johannes Braams
Johannes Braams studied electronic engineering at the Technical University in Enschede, the Netherlands. His master’s thesis
was on video coding, based on a model of the human visualsystem. During his research at the dr. Neher Laboratories in
1984, he came into contact with LaTEX for the first time. He
was a founding board member of the Dutch-speaking TeX
User Group (NTG) in 1988 and participated in developing
support for typesetting Dutch documents. He started workon developing the babel system for multilingual typesetting following the Karlsruhe
EuroTEX conference in 1989.
Since its inception at the EuroTEX conference in Cork in 1990, he has been amember of the LaTEX Project Team. Johannes still maintains a couple of LaTEX extension

975

BIOGRAPHIES

packages such as the ntgclass family of document classes and the supertabular andchangebar packages.
After his studies, Johannes continued to work for the Dutch PTT, which latercame to be known as KPN until 2014, mostly as an IT project manager. In 2015 hestarted a new career as a consultant on cybersecurity for industrial automation andcontrol systems, first at the Software Improvement Group in Amsterdam; then in2017 he joined Royal HaskoningDHV, a Dutch engineering firm that operates globally.
He works on security by design in industrial installations. Johannes is now a board
member of the Dutch chapter of (ISC)2 . He lives with his wife in Den Ham; their twosons both graduated from the University Twente in Enschede.

Joseph Wright
Joseph Wright is a synthetic chemist who studied for his degree
at the University of Leicester before moving to the Universityof Cambridge for his PhD. He first heard of LaTEX in about 2001
but did not start using it until writing a final report on his firstresearch assistant position at the University of Southampton
in 2004.
Joseph transitioned from being a user to a developer
most obviously when he answered a “simple” question on thecomp.text.tex newsgroup asking for a fix to the SIunits package in 2007. It soon turned out that this was the tip of a much larger task: writing atruly comprehensive units package: siunitx.
Joseph became involved with the LaTEX Project Team’s work after Will Robertson
asked him what he thought of the experimental ideas in expl3. Joseph liked them,so he used expl3 to develop the second version of siunitx and raised lots of questions
about how things worked. His questions and suggestions led to an invite to join theteam.
As well as writing (LA)TEX code, Joseph is one of the moderators on the TEX/LaTEX
StackExchange site. He’s one of two moderators who’ve been in place from the very
start of the site, helping to ensure there’s always been a welcoming approach with theaim of helping end users solve their (LA)TEX problems.

976

Production Notes

This book was typeset using the LaTEX document processing system (which it describes)
together with substantial help from some of the extension packages covered herein,and considerable extra ad hoc LaTEX programming effort. We used the base LaTEX release
dated 2022-11-01, pdfTEX as the main TEX engine, and LuaTEX for examples that involved OpenType fonts. All packages have been taken from the 2022 TEX Live distribution to ensure that the examples show what you will get when you run them yourself.1
The text body fonts used are Lucida Bright and Lucida Sans (Bigelow/Holmes) at
Body fonts
8.47pt/11.72pt. These font families can be used at rather small sizes, which can beseen by the fact that the monospaced font we matched them with is Latin Modern
Typewriter (TEX Gyre foundry) at 10.36pt. This particular combination was chosen
to get a reasonable amount of material on each page and to optically balance theappearance of the typewriter font so that it is distinguishable but without too big
a contrast.
The text in the examples mostly uses TEX Gyre’s Times Roman (tgtermes) with
Example fonts
its Helvetica (tgheros) for sans serif. For the mathematical material in the examples
we stayed with the now classic Computer Modern math fonts, so the symbols willappear familiar to the majority of mathematics users. Of course, examples intended
to demonstrate the use of other fonts are exceptions.
Package usage in the book
If you count the examples as part of the book, then every package described in thisThe LATEX packages
edition has also been used in it. This is a bit of a red herring, though, because the used to produce theexamples are typeset as separate documents and the results are then included in the book . . .
book as PDF (Portable Document Format) images. However, many of the packages
1 Well, at least initially — sometimes, though seldom, packages change in incompatible ways.

PRODUCTION NOTES

have been deployed for real to produce this edition, and for the interested reader we
now list the most important ones and why they have been used.
To help in producing the explanatory text we used acro for acronyms, resetting. . . for the main
their
use count on a per-chapter basis. Thus, for most acronyms you see the firsttext . . .
use in a chapter being displayed in its full form, e.g., as “Comprehensive TEX Archive
Network (CTAN)”. For quotation marks, commands from the csquotes package havebeen used throughout.
Heavy use was made of \vref and friends from the varioref package. We often. . . for generatingrefer
to examples or sections “on the facing page”, “previous”, “next” or “below”,
references . . .
etc., and in all such cases these are generated texts and not hardwired in the source.
Otherwise, the layout process would have been a nightmare, requiring extensive
amounts of textual adjustments whenever material moved from one page to the next
and vice versa. Of course, using varioref in a book of this size is bound to produce an
impossible document as explained on page →I 85. And indeed, it happened a handfulof times that the generated text got split across two pages, rendering the wrong resultin all cases. Initially, we changed the errors to warnings and ignored them, and thenresolved the issues during the final pagination by adjusting the surrounding text
(either rewriting parts or adding some strategic line or page breaks).
Since the second edition of The LATEX Companion we used “hanging punctuation”. . . applying opticaltotypesetthe paragraphs. In the last edition, this typographical icing was basically proalignment and font1
expansion . . . duced manually, but this time we have been fortunate to simply apply the microtype
package. This package was also used to add some light expansion/suppression using
the hz-algorithm, which, in my opinion noticeably improved the overall look and feelof the paragraphs. For comparison, look at this paragraph and compare it with therepeat below (where both features are turned off).

Since the second edition of The LATEX Companion we used “hanging punctua
. . . or not . . .



tion”
to typeset the paragraphs. In the last edition, this typographical icing was(a repeat) basically
produced manually, but this time we have been fortunate to simply1 ap
2
ply the microtype package. This package was also used to add some light expan

sion/suppression using the hz-algorithm, which, in my opinion noticeably improved





the overall look and feel of the paragraphs. Compare this to the previous paragraph(which has both features turned on) — which do you prefer?
The core design for the book dates back to the first edition and therefore chapter. . . chapter headings,
headings,
list environments, etc., have been defined using the basic mechanisms oflists, and runningaheaders . . . L TEX rather than using support packages because those were not available back then.
For the running headers and the page numbers the fancyhdr package was used.
To produce the various tables in the book, array and tabularx (for the extended. . . making tables . . .
syntax) were put to good use and on nearly every table we applied commands fromthe booktabs package for the formal rules. The few multipage tables have been
generated with longtable and in some places we used multicol to produce a table-likeappearance.
1 We had to define our own configuration file, though, because the microtype package has nopresets for the commercial Lucida Bright fonts and the default settings, while more or less adequate,
were not totally satisfactory. Thus, we applied the advice given in Section 3.1.3.
2 The paragraph now breaks differently and the margins are no longer optically aligned.

978

PRODUCTION NOTESGraphics have been included with the help of graphicx and in a few places we. . . showing graphics
used overpic to add some arrows or other data to the image. The captions have been and examples . . .
styled with the caption package; other float-related packages were not necessary as thebook requirements have been fairly light. Producing the examples, showing input andoutput side by side, was more elaborate and involved the use of the fancyvrb package
and a fair amount of programming. The general approach we used is explained in
Section 4.2.4 on page →I 315.
The boxes showing information that is only relevant for Unicode engines or that . . . displaying
detail differences between the BIBTEX and biblatex approach have been designed using informational
boxes . . .
tcolorbox, which in turn uses tikz.
For the bibliography we used BIBTEX with a number-only style that was designed. . . producing thewith the help of custom-bib, and natbib was used for the citations. Because this bibliography . . .
edition was split in two parts, each part got its own bibliography; this was achieved
with the bibunits package.
The book uses several separate indexes (even though only two are shown in the. . . the different
final product). To generate the raw data for them we made use of the index package indexes . . .
and the sorting was done with MakeIndex. However, due to the complexity of the index(the colored page numbers, etc.) it was necessary to use pre- and post-processing by
scripts to produce the final form of the index files. These were then typeset using anenhanced version of the multicol package to add the continuation lines — somethingthat perhaps one day can be turned into a proper package. The “Commands andConcepts” index is a mixture of commands, environments, and other LaTEX elements,
but also includes concept entries. The latter were produced by typesetting a version of
the book with line numbers and giving that to the indexer, who produced “conceptualindex entries” that were then added to the source files for the book so that pagination
changes would not invalidate the index entries. This was a major testament to thequality of the lineno package, as it worked “straight out of the box”.
In anticipation of a PDF and ebook version of the third edition, we already used
. . . and interactive
both the bookmark and the hyperref package. Even though this does not show in the PDF features
printed form of the book it helped us tremendously during its preparation, because
all internal references have been active links, allowing us to quickly jump from one
place to another in the draft PDF document. Furthermore, all internal notes we madewere enhanced to generate bookmarks so that the bookmark pane of the PDF reader
gave us a quick overview of all the tasks still to do and text still to write.
Packages that should have been used for the book . . .
You might be surprised that some heavily recommended packages, such as enumitem. . . but have notor geometry, are missing. The reason is simply that the fundamental design decisions,e.g., the page layout or the design of the headings, lists, etc., have been retained acrossall editions and when the first edition was typeset in 1994 those packages that can
now make your life easier were not yet available, and thus the necessary code had tobe handcrafted. Altering that setup was only done when improvements or changes
were necessary; e.g., the titletoc package was added when we introduced the partial
TOCs below the chapter headings. But in a new project such packages would havebeen used from the start.

979

PRODUCTION NOTES

Packages supporting the production
This book loads more than 140 .sty files (not counting those loaded in the examples),Running out of files
which is way beyond what is needed in typical documents. Several of these packages
to write toColor woes

Task management

Where are myerrors?

Controlling thesourceTracking file usage

open their own write streams, and this is a rather limited resource in TEX (only 16
can be open at the same time). As a result the book died when processing the list of
figures because that tried to open one stream too many. Fortunately, there is a remedy
with Bruno Le Floch’s morewrites package. It comes with a cost, though, because it
needs additional processing time, but the important point is that it enables you toprocess a document of such complexity!
The printing process for the book required two colors: black and some kind ofblue as a spot color. For this, we used the packages xcolor and colorspace, but it is nota simple task to ensure that the final document does not contain color instructions in
CMYK (or RGB) because some packages include hardwired color specifications using
such models. As a result we had to do some patching or avoid using color in a few
examples in order to not upset the final production process. This is clearly an area
where LaTEX could be improved to make life easier.
To keep track of all the open tasks that needed resolving, we used the todonotes
package and defined a few commands similar to those shown in Example A-1-17 on
page 645, except that we also added a bookmark for each task using the bookmark
package. At one point this showed several hundred entries, but now as I write thistext it is thankfully down to a handful of remaining tasks.
Loading the structuredlog package enabled us to quickly identify in which source
file an error occurred — not that we ever had any.1 The footnote in Appendix B.1 on
page 712 explains how to make use of this package.
Using a source control approach is beneficial for nearly every project — for acomplex one like this book, it is essential. It enables you and your co-authors to workwithout stepping on each other’s toes; if something breaks, you have a history thathelps you identify and resolve problems; and, last but not least, it simplifies project
data synchronization across different devices and locations. For the second edition
we used SVN; for this edition it was Git, and the package gitinfo2 was deployed towrite source branch and date information at the bottom of every page (outside thefinal printing area).
Another tool we used regularly was mkjobtexmf. With its help we collected all
files used during compilation in a separate tree, which was also placed under source
control. This way, any updates to standard packages, font files, etc., could be easily
tracked, which again helped a lot if something went awry.
The production cycle

The production of this book required a custom class and, as outlined above, many
additional package files. It also needed a complex “make” process using a collection of“shell scripts” controlled by a “Makefile”. One of the major tasks these accomplished
1 Joke — of course, we did. All kinds of errors occurred, from simple typos to subtle package

incompatibilities that resulted in talking to the developers after identifying the root cause of the
problem.

980

PRODUCTION NOTES

was to ensure that the typeset output of each and every example really is producedby the accompanying example input. This “make” process worked as follows:• When first processing a chapter, LaTEX generated a source document file for each Generating
example. These are the one-and-a-half-thousand “example files” you will find on examples
CTAN at https://ctan.org/pkg/tlc3-examples .
• The make process then ran each of these “example files” through LaTEX (alsocalling BIBTEX, biber, or whatever else was needed) as often as was necessary to
produce the final form of the typeset output.
The resulting PDF file was post-processed with pdfcrop to drop all whitespace on the outside (making the PDF pages only as big as the visible output) and,if necessary, to split it into separate pages using pdfseparate.
• The next time LaTEX was run on that chapter, each of these PDF output files was
automatically placed in its position in the book, next to (or near) the example
input. The process was not complete even then because the horizontal positioningof some elements, in particular the examples, depends on whether they are ona verso or recto (the technique from Example A-5-7 on page 692 was used inthis case). Thus, at least one or two additional runs were needed before all the
cross-references were correctly resolved and LaTEX finally found the right way toplace the examples correctly into the margins.
Due to the example-generating complexity — together with the use of varioref
altering the generated text based on distance to the referenced object — the bookrequired not the usual two or three but in fact six complete runs before LaTEX stopped
asking for “Rerun to get cross-references right”. Even on a fast iMac from 2021 with an
M1 chip, that meant a half-hour wait — and this is not counting the generation of the1540 examples. Those required another two-and-a-half hours1 so that it took a totalof three hours of computer-processing time to produce the typeset book from scratch.
The layout effort
That was about as far as automation of the process could take us. Because of the many
Manual labor fromlarge examples that could neither be broken nor treated as floating material, getting page 1 to 2000
good page breaks turned out to be a major challenge. For this and other reasons,getting to the final layout of the book was fairly labor intensive and even required
minor rewriting (on maybe 10% of the pages) in order to avoid bad line breaks or page
breaks (e.g., paragraphs ending with a single-word line or a distracting hyphenation ata page break). Spreads were allowed to run one line long or one line short if necessary,and in several cases the layout and contents of the examples were manually adjusted
to allow decent page breaks.
A great help in this final layout process was the package widows-and-orphans,
Giving widows andwhich told us the pages that contained widows, orphans, or hyphenations across page orphans a new homeboundaries. We then applied one of the suggestions from Section 5.6.6 on page →I 422,
often adding an explicit page break in some strategic place or sometimes rewriting a
1 The main factor here is the file I/O cost. Each example has to be run several times, and each time,
TEX has to start and load all packages and fonts, over and over again.

981

PRODUCTION NOTES

paragraph to make it longer or shorter (after all, we are the authors and can change
the text for aesthetic reasons). In a few places, no fix seemed reasonable, in whichcase we accepted an orphan or widow and marked the place with \WaOignorenext.
In total, 1.5% of the pages were treated like this.
Here are a few approximate statistics from this page layout process: 24 long
Some pagination
spreads,
41 short spreads, 51 compressed pages (using \enlargethispage*) comstatistics
bined with forced page breaks. This is noticeably less than in the previous editionand one of the reasons is that this time we made ample use of TEX’s \looseness
functionality: we ran 125 paragraphs one line shorter than normal and 17 paragraphs
one line longer than is optimal in TEX’s eyes.
We added 501 forced page breaks in total, which means 25% of all pages havea forced premature ending — usually to avoid half-empty pages later due to a larger
example showing up in the wrong place. While I think the results are satisfactory,getting this right was rather time consuming and difficult — here it really hurts that
TEX has a global paragraph optimizer but generates its pagination with a simple
greedy algorithm. While this gives reasonable results with most documents it totally
breaks down in those that contain larger unbreakable parts such as this book.1
Searching across the final sources, there are about 1200 adjustments to thevertical spacing2 and 100 other manual adjustments (other than rewriting or altering
the examples). For the latter I do not have any reliable data, but from my recollection
I would guess that about a quarter (i.e., 400) of the examples have been adjusted tobetter blend into the page flow.
In several places in the book we have given the advice to leave any layout work
A final 
until
the very last minute, and on the whole we followed our advice to the letter withword of advice
this book. For example, all pagination work was delayed until the copy editor had
worked through all chapters and marked up all the mistakes we made (well, hopefullyall) — it took me a while to convince her not to mark up ugly-looking page breaks,
because they were deliberate. Given that changing a single letter in a paragraph may
result in total reflow (and possibly a different number of lines) this saved me a lot of
unnecessary work.
However, in one case I diverged from that principle. When I started to write thissection, I realized that the chosen typewriter font seemed to be a tiny bit too large
compared to the Lucida body fonts. I therefore decided to scale it down by one percent.
Given that this is only used for individual words, I expected a few changes but not
much. To my dismay I ended up with more than fifty pages where the pagination
was totally broken, e.g., paragraphs getting shorter or longer, lines overflowing to thenext page, etc. It took me a full day to repair the damage. So again, take this advice
seriously and only work on pagination adjustments when you are 100% done with thetext and all your other layout choices have been made — easier said than done, I know!
1 I had secretly hoped that the research results outlined in [134, 135, 138] could already be applied
to the production of this book, which would have saved me perhaps a month worth of effort.
Unfortunately, turning the prototype into a fully working production system proved to be more
complicated than I had bargained for. Thus, in the end I buried the idea and produced the layout theold-fashioned way.
2 These adjustments are partially due to deficiencies in parameter setup for the custom class.
However, by the time I realized this, several chapters had already been paginated and changing theclass setup would have invalidated those. Thus, it seemed simpler to live with the imperfection.

982

PRODUCTION NOTESPDF and ePub production
As you know, we had to split the third edition — due to its size — into two physical
The PDF for printing
books. However, both parts were produced with a single LaTEX source to make it easier the edition
for LaTEX (and us) to automatically resolve cross-references across the parts and to
generate a consolidated index with entries for the whole edition. This index was
included at the end of each physical part to make it easier for our readers to workwith the two books.
The tables of contents lists were tailored for each part: they show the sectionsof the current part in detail, but only give a chapter-level overview of the other part.
Similarly, the bibliographies at the end of each part only show entries that have acitation in that part. The few books and articles that are referenced in both parts
therefore appear twice in the complete print edition. This way the resulting PDF only
needed to be split in the middle and sent to the printer.
However, in that form the PDF is unsuitable as a digital product or as a basis for
producing an ePub of the complete edition, because it contains a duplicated index,
two separate bibliographies, and no consolidated front matter, e.g., no complete tableof contents or list of figures.
Thus, for the digital version we augmented the LaTEX sources so that by flipping a The PDF for digital
switch a slightly different PDF is produced. The differences between the print version consumption
and the digital version are as follows:• In the digital version the front matter of Part I contains a consolidated table ofcontents for both parts and the partial table of contents in Part II was dropped.
The same applies to the list of figures and the list of tables.
• The bibliographies from both parts were combined and placed at the end ofPart II. Of course, this alters the citation labels within the edition, and that may
result in a slightly different paragraph formatting in one or the other place (dueto differently sized labels), but great care was taken to not affect the overallpagination. Thus, if you own both the print and the digital edition they show thesame material on pages with the same page number.
• The bibliography change also required me to regenerate two examples: 3-4-17
on page →I 189 and 4-1-44 on page →I 288, because they both refer to entries inthe bibliography. These examples therefore differ slightly between the print andthe digital versions.
• The preface of Part II was shortened because it repeated the “How to work withthe book” section, which is not needed twice in the digital version.
• For the same reason the index for the complete edition at the end of Part I was
dropped and only the complete index in Part II was kept. This index of the digital
version should be more or less identical to the one in the print version, e.g., you
can use the digital index and then look up the page in the printed book. However,given that we dropped one section from the preface that contained index entries,
the index in the printed book has a few more page references.
• This section about PDF and ebook production only appears in the digital version.

983

PRODUCTION NOTESNavigating
the PDF

Producing theePub version

984

In all other respects the print and the digital versions have been kept identical,
e.g., the page numbers are restarted in Part II, so that most page numbers appear
twice. This way they are at most three digits wide and it remains possible to correctlycite pages from the edition, regardless of somebody owning the digital or the printversion (with the execption of pages from the front or the back matter).
Most PDF viewers allow you to select pages by entering, for example, II-39. Thus,
if somebody tells you to have a look at the nice Accanthis font on page 39 in Part IIand you want to look this up in the PDF version, this is a simple way to reach that
page. Of course, in the ePub version page numbers are of no real help, except that if
used in the text they contain a link that you can click on to jump to the correct placein the edition. In the ePub you have to navigate using the book marks if you want to
get to a specific section — a possibility that, of course, exists in the PDF as well.
This altered PDF is what you get as one of the digital products, and it is also
the one that was used as a basis for producing the ePub version by a company
specializing in such work. There are in fact tools in the LaTEX world, such as tex4ht by
Michal Hoftich or lwarp by Brian Dunn that assist you in a direct conversion of LaTEX
sources to HTML or ePub, but the LATEX Companion is so complicated that we did not
attempted to use the direct route. Maybe that is going to change in a future edition,
when LaTEX is fully capable of automatically producing a tagged PDF.