The UK TeX FAQ

Your 469 Questions Answered

version 3.28, date 2014-06-10

June 10, 2014

N OTE

This document is an updated and extended version of the FAQ article that was
published as the December 1994 and 1995, and March 1999 editions of the UK TUG
magazine Baskerville (which weren’t formatted like this).
The article is also available via the World Wide Web.

Contents
Introduction 10
Licence of the FAQ 10
Finding the Files 10
A The Background 11
1 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2 What is TeX? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3 What’s “writing in TeX”? . . . . . . . . . . . . . . . . . . . . . . . 12
4 How should I pronounce “TeX”? . . . . . . . . . . . . . . . . . . . 12
5 What is Metafont? . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6 What is Metapost? . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
7 Things with “TeX” in the name . . . . . . . . . . . . . . . . . . . . 13
8 What is CTAN? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
9 The (CTAN) catalogue . . . . . . . . . . . . . . . . . . . . . . . . . 15
10 How can I be sure it’s really TeX? . . . . . . . . . . . . . . . . . . . 15
11 What is e-TeX? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
12 What is PDFTeX? . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
13 What is LaTeX? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
14 What is LaTeX2e? . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
15 How should I pronounce “LaTeX(2e)”? . . . . . . . . . . . . . . . . . 17
16 Should I use Plain TeX or LaTeX? . . . . . . . . . . . . . . . . . . . 17
17 How does LaTeX relate to Plain TeX? . . . . . . . . . . . . . . . . . 17
18 What is ConTeXt? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
19 What are the AMS packages (AMSTeX, etc.)? . . . . . . . . . . . . 18
20 What is Eplain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
21 What is Texinfo? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
22 Lollipop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
23 If TeX is so good, how come it’s free? . . . . . . . . . . . . . . . . 19
24 What is the future of TeX? . . . . . . . . . . . . . . . . . . . . . . . 19
25 Reading (La)TeX files . . . . . . . . . . . . . . . . . . . . . . . . . 19
26 Why is TeX not a WYSIWYG system? . . . . . . . . . . . . . . . . . 20
27 TeX User Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
B Documentation and Help 21
28 Books relevant to TeX and friends . . . . . . . . . . . . . . . . . . . . 21
29 Books on TeX, Plain TeX and relations . . . . . . . . . . . . . . . . . 21
30 Books on LaTeX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
31 Books on other TeX-related matters . . . . . . . . . . . . . . . . . . 23
32 Books on Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
33 Where to find FAQs . . . . . . . . . . . . . . . . . . . . . . . . . . 24
1
 34 Getting help online . . . . . . . . . . . . . . . . . . . . . . . . . . 24
35 Specialist mailing lists . . . . . . . . . . . . . . . . . . . . . . . . . 25
36 How to ask a question . . . . . . . . . . . . . . . . . . . . . . . . . 25
37 How to make a “minimum example” . . . . . . . . . . . . . . . . . 26
38 Tutorials, etc., for TeX-based systems . . . . . . . . . . . . . . . . . . 27
39 Online introductions: Plain TeX . . . . . . . . . . . . . . . . . . . . . 27
40 Online introductions: LaTeX . . . . . . . . . . . . . . . . . . . . . . 27
41 (La)TeX tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
42 Reference documents . . . . . . . . . . . . . . . . . . . . . . . . . 29
43 WIKI books for TeX and friends . . . . . . . . . . . . . . . . . . . 29
44 Typography tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . 29
45 Freely available (La)TeX books . . . . . . . . . . . . . . . . . . . . 30
46 Documentation of packages . . . . . . . . . . . . . . . . . . . . . . 30
47 Learning to write LaTeX classes and packages . . . . . . . . . . . . . 31
48 LaTeX3 programming . . . . . . . . . . . . . . . . . . . . . . . . . . 31
49 Metafont and Metapost Tutorials . . . . . . . . . . . . . . . . . . . 32
50 BibTeX Documentation . . . . . . . . . . . . . . . . . . . . . . . . 32
51 Where can I find the symbol for . . . . . . . . . . . . . . . . . . . . . 32
52 The PiCTeX manual . . . . . . . . . . . . . . . . . . . . . . . . . . 33
C Bits and pieces of (La)TeX 33
53 What is a DVI file? . . . . . . . . . . . . . . . . . . . . . . . . . . 33
54 What is a DVI driver? . . . . . . . . . . . . . . . . . . . . . . . . . 33
55 What are PK files? . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
56 What are TFM files? . . . . . . . . . . . . . . . . . . . . . . . . . . 34
57 What are virtual fonts? . . . . . . . . . . . . . . . . . . . . . . . . . 34
58 What are (TeX) macros . . . . . . . . . . . . . . . . . . . . . . . . 35
59 \special commands . . . . . . . . . . . . . . . . . . . . . . . . . 35
60 Writing (text) files from TeX . . . . . . . . . . . . . . . . . . . . . 36
61 Spawning programs from (La)TeX: \write18 . . . . . . . . . . . . 36
62 How does hyphenation work in TeX? . . . . . . . . . . . . . . . . . . 37
63 What are LaTeX classes and packages? . . . . . . . . . . . . . . . . . 37
64 What are LaTeX “environments” . . . . . . . . . . . . . . . . . . . 38
65 Documented LaTeX sources (.dtx files) . . . . . . . . . . . . . . . 38
66 What are encodings? . . . . . . . . . . . . . . . . . . . . . . . . . . 39
67 What are the EC fonts? . . . . . . . . . . . . . . . . . . . . . . . . 40
68 Unicode and TeX . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
69 What is the TDS? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
70 What is “Encapsulated PostScript” (“EPS”)? . . . . . . . . . . . . . . 41
71 Adobe font formats . . . . . . . . . . . . . . . . . . . . . . . . . . 42
72 What are “resolutions”? . . . . . . . . . . . . . . . . . . . . . . . . 42
73 What is the “Berry naming scheme”? . . . . . . . . . . . . . . . . . 43
D Acquiring the Software 43
74 Repositories of TeX material . . . . . . . . . . . . . . . . . . . . . 43
75 Ready-built installation files on the archive . . . . . . . . . . . . . . 44
76 What was the CTAN nonfree tree? . . . . . . . . . . . . . . . . . . 44
77 Contributing a file to the archives . . . . . . . . . . . . . . . . . . . 44
78 Finding (La)TeX files . . . . . . . . . . . . . . . . . . . . . . . . . 45
79 Finding new fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
80 The TeX collection . . . . . . . . . . . . . . . . . . . . . . . . . . 46
E TeX Systems 47
81 (La)TeX for different machines . . . . . . . . . . . . . . . . . . . . . 47
82 Unix and GNU Linux systems . . . . . . . . . . . . . . . . . . . . . . 47
83 (Modern) Windows systems . . . . . . . . . . . . . . . . . . . . . . . 47
84 Macintosh systems . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
85 Other systems’ TeX availability . . . . . . . . . . . . . . . . . . . . 48
86 TeX-friendly editors and shells . . . . . . . . . . . . . . . . . . . . 49
87 Commercial TeX implementations . . . . . . . . . . . . . . . . . . 50

2
F DVI Drivers and Previewers 51
88 DVI to PostScript conversion programs . . . . . . . . . . . . . . . . . 51
89 DVI drivers for HP LaserJet . . . . . . . . . . . . . . . . . . . . . . . 51
90 Output to “other” printers . . . . . . . . . . . . . . . . . . . . . . . . 51
91 DVI previewers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
92 Generating bitmaps from DVI . . . . . . . . . . . . . . . . . . . . . . 51
G Support Packages for TeX 52
93 (La)TeX-friendly drawing packages . . . . . . . . . . . . . . . . . . 52
94 TeXCAD, a drawing package for LaTeX . . . . . . . . . . . . . . . 52
95 Spelling checkers for work with TeX . . . . . . . . . . . . . . . . . 52
96 How many words have you written? . . . . . . . . . . . . . . . . . . 53
H Literate programming 54
97 What is Literate Programming? . . . . . . . . . . . . . . . . . . . . 54
98 WEB systems for various languages . . . . . . . . . . . . . . . . . 54
I Format conversions 54
99 Conversion from (La)TeX to plain text . . . . . . . . . . . . . . . . 54
100 Conversion from SGML or HTML to TeX . . . . . . . . . . . . . . 55
101 Conversion from (La)TeX to HTML . . . . . . . . . . . . . . . . . 55
102 Other conversions to and from (La)TeX . . . . . . . . . . . . . . . . 56
103 Using TeX to read SGML or XML directly . . . . . . . . . . . . . . . 57
104 Retrieving (La)TeX from DVI, etc. . . . . . . . . . . . . . . . . . . 58
105 Translating LaTeX to Plain TeX . . . . . . . . . . . . . . . . . . . . 58
J Installing (La)TeX files 58
106 Installing things on a (La)TeX system . . . . . . . . . . . . . . . . . 58
107 Finding packages to install . . . . . . . . . . . . . . . . . . . . . . 59
108 Unpacking LaTeX packages . . . . . . . . . . . . . . . . . . . . . . 59
109 Generating package documentation . . . . . . . . . . . . . . . . . . 59
110 Installing files “where (La)TeX can find them” . . . . . . . . . . . . 60
111 Which tree to use . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
112 Where to install packages . . . . . . . . . . . . . . . . . . . . . . . . 61
113 Tidying up after installation . . . . . . . . . . . . . . . . . . . . . . . 61
114 Shortcuts to installing files . . . . . . . . . . . . . . . . . . . . . . . 62
115 Installation using MiKTeX package manager . . . . . . . . . . . . . 62
116 Installation using TeX Live manager . . . . . . . . . . . . . . . . . 62
117 Installing using ready-built ZIP files . . . . . . . . . . . . . . . . . 62
118 “Temporary” installation of (La)TeX files . . . . . . . . . . . . . . . 63
119 “Private” installations of files . . . . . . . . . . . . . . . . . . . . . 63
120 Installing a new font . . . . . . . . . . . . . . . . . . . . . . . . . . 64
121 Installing a font provided as Metafont source . . . . . . . . . . . . . 64
122 ‘Installing’ a PostScript printer built-in font . . . . . . . . . . . . . 65
123 Preparing a Type 1 font . . . . . . . . . . . . . . . . . . . . . . . . 65
124 Installing a Type 1 font . . . . . . . . . . . . . . . . . . . . . . . . 66
125 Installing the Type 1 versions of the CM fonts . . . . . . . . . . . . 66
K Fonts 67
K.1 Adobe Type 1 (“PostScript”) fonts 67
126 Using Adobe Type 1 fonts with TeX . . . . . . . . . . . . . . . . . . 67
127 Previewing files using Type 1 fonts . . . . . . . . . . . . . . . . . . . 67
128 TeX font metric files for Type 1 fonts . . . . . . . . . . . . . . . . . . 67
129 Deploying Type 1 fonts . . . . . . . . . . . . . . . . . . . . . . . . 68
130 Choice of Type 1 fonts for typesetting Maths . . . . . . . . . . . . . 68
131 Unicode Maths using OpenType fonts . . . . . . . . . . . . . . . . . 74
132 Weird characters in dvips output . . . . . . . . . . . . . . . . . . . . 74
K.2 Macros for using fonts 74
133 Using non-standard fonts in Plain TeX . . . . . . . . . . . . . . . . 74
K.3 Particular font families 75
134 Using the “Concrete” fonts . . . . . . . . . . . . . . . . . . . . . . 75
135 Using the Latin Modern fonts . . . . . . . . . . . . . . . . . . . . . 76
136 Getting ‘free’ fonts not in your distribution . . . . . . . . . . . . . . . 77

3
K.4 Metafont fonts 77
137 Getting Metafont to do what you want . . . . . . . . . . . . . . . . . 77
138 Which font files should be kept . . . . . . . . . . . . . . . . . . . . 78
139 Acquiring bitmap fonts . . . . . . . . . . . . . . . . . . . . . . . . 78
L Hypertext and PDF 79
140 Making PDF documents from (La)TeX . . . . . . . . . . . . . . . . 79
141 Making hypertext documents from TeX . . . . . . . . . . . . . . . . 80
142 The hyperTeX project . . . . . . . . . . . . . . . . . . . . . . . . . 80
143 Quality of PDF from PostScript . . . . . . . . . . . . . . . . . . . . 80
144 The wrong type of fonts in PDF . . . . . . . . . . . . . . . . . . . . . 81
145 Fuzzy fonts because Ghostscript too old . . . . . . . . . . . . . . . . 81
146 Fonts go fuzzy when you switch to T1 . . . . . . . . . . . . . . . . . 81
147 Characters missing from PDF output . . . . . . . . . . . . . . . . . 82
148 Finding ‘8-bit’ Type 1 fonts . . . . . . . . . . . . . . . . . . . . . . 82
149 Replacing Type 3 fonts in PostScript . . . . . . . . . . . . . . . . . 83
150 Hyperref and repeated page numbers . . . . . . . . . . . . . . . . . 83
151 Copy-paste-able/searchable PDF files . . . . . . . . . . . . . . . . . 84
M Graphics 84
152 Importing graphics into (La)TeX documents . . . . . . . . . . . . . 84
153 Imported graphics in dvips . . . . . . . . . . . . . . . . . . . . . . . 85
154 Imported graphics in PDFLaTeX . . . . . . . . . . . . . . . . . . . 86
155 Imported graphics in dvipdfm . . . . . . . . . . . . . . . . . . . . . . 87
156 “Modern” graphics file names . . . . . . . . . . . . . . . . . . . . . . 87
157 Importing graphics from “somewhere else” . . . . . . . . . . . . . . 88
158 Portable imported graphics . . . . . . . . . . . . . . . . . . . . . . 88
159 Repeated graphics in a document . . . . . . . . . . . . . . . . . . . 89
160 Limit the width of imported graphics . . . . . . . . . . . . . . . . . 89
161 Top-aligning imported graphics . . . . . . . . . . . . . . . . . . . . 89
162 Displaying Metapost output in ghostscript . . . . . . . . . . . . . . 90
163 Drawing with TeX . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
164 In-line source for graphics applications . . . . . . . . . . . . . . . . 92
165 Drawing Feynman diagrams in LaTeX . . . . . . . . . . . . . . . . 92
166 Labelling graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
N Bibliographies and citations 94
N.1 Creating bibliographies 94
167 Creating a BibTeX bibliography file . . . . . . . . . . . . . . . . . . 94
168 Creating a bibliography style . . . . . . . . . . . . . . . . . . . . . 95
169 Capitalisation in BibTeX . . . . . . . . . . . . . . . . . . . . . . . 95
170 Accents in bibliographies . . . . . . . . . . . . . . . . . . . . . . . 95
171 ‘String too long’ in BibTeX . . . . . . . . . . . . . . . . . . . . . . 96
172 BibTeX doesn’t understand lists of names . . . . . . . . . . . . . . 96
173 URLs in BibTeX bibliographies . . . . . . . . . . . . . . . . . . . . 96
174 Using BibTeX with Plain TeX . . . . . . . . . . . . . . . . . . . . . . 97
175 Reconstructing .bib files . . . . . . . . . . . . . . . . . . . . . . . . 97
176 BibTeX sorting and name prefixes . . . . . . . . . . . . . . . . . . . . 97
177 ‘Multi-letter’ initials in BibTeX . . . . . . . . . . . . . . . . . . . . 98
N.2 Creating citations 99
178 “Normal” use of BibTeX from LaTeX . . . . . . . . . . . . . . . . 99
179 Choosing a bibliography style . . . . . . . . . . . . . . . . . . . . . 99
180 Separate bibliographies per chapter? . . . . . . . . . . . . . . . . . 100
181 Multiple bibliographies? . . . . . . . . . . . . . . . . . . . . . . . . 100
182 Putting bibliography entries in text . . . . . . . . . . . . . . . . . . . 101
183 Sorting and compressing citations . . . . . . . . . . . . . . . . . . . 102
184 Multiple citations . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
185 References from the bibliography to the citation . . . . . . . . . . . 103
186 Sorting lists of citations . . . . . . . . . . . . . . . . . . . . . . . . 103
187 Reducing spacing in the bibliography . . . . . . . . . . . . . . . . . 103
188 Table of contents rearranges “unsrt” ordering . . . . . . . . . . . . . 104
189 Non-english bibliographies . . . . . . . . . . . . . . . . . . . . . . 104
190 Format of numbers in the bibliography . . . . . . . . . . . . . . . . 105

4
N.3 Manipulating whole bibliographies 105
191 Listing all your BibTeX entries . . . . . . . . . . . . . . . . . . . . 105
192 Making HTML of your Bibliography . . . . . . . . . . . . . . . . . 105
O Adjusting the typesetting 105
O.1 Alternative document classes 105
193 Replacing the standard classes . . . . . . . . . . . . . . . . . . . . . 105
194 Producing presentations (including slides) . . . . . . . . . . . . . . 106
195 Creating posters with LaTeX . . . . . . . . . . . . . . . . . . . . . . 107
196 Formatting a thesis in LaTeX . . . . . . . . . . . . . . . . . . . . . 108
197 Setting papers for journals . . . . . . . . . . . . . . . . . . . . . . . 108
198 A ‘report’ from lots of ‘article’s . . . . . . . . . . . . . . . . . . . . 108
199 Curriculum Vitae (Résumé) . . . . . . . . . . . . . . . . . . . . . . 110
200 Letters and the like . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
201 Other “document font” sizes? . . . . . . . . . . . . . . . . . . . . . . 111
O.2 Document structure 111
202 The style of document titles . . . . . . . . . . . . . . . . . . . . . . . 111
203 The style of section headings . . . . . . . . . . . . . . . . . . . . . 112
204 Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
205 Indent after section headings . . . . . . . . . . . . . . . . . . . . . 113
206 How to create a \subsubsubsection . . . . . . . . . . . . . . . . . 113
207 The style of captions . . . . . . . . . . . . . . . . . . . . . . . . . . 114
208 Alternative head- and footlines in LaTeX . . . . . . . . . . . . . . . 114
209 Wide figures in two-column documents . . . . . . . . . . . . . . . . 115
210 1-column abstract in 2-column document . . . . . . . . . . . . . . . 115
211 Really blank pages between chapters . . . . . . . . . . . . . . . . . 115
212 Balancing columns at the end of a document . . . . . . . . . . . . . 116
213 My section title is too wide for the page header . . . . . . . . . . . . 116
214 Page numbering “hni of hmi” . . . . . . . . . . . . . . . . . . . . . . 117
215 Page numbering by chapter . . . . . . . . . . . . . . . . . . . . . . 118
O.3 Page layout 118
216 The size of printed output . . . . . . . . . . . . . . . . . . . . . . . 118
217 Adobe Reader messing with print size . . . . . . . . . . . . . . . . 118
218 Getting the right paper geometry from (La)TeX . . . . . . . . . . . 118
219 Changing the margins in LaTeX . . . . . . . . . . . . . . . . . . . . 119
220 Packages to set up page designs . . . . . . . . . . . . . . . . . . . . 120
221 How to set up page layout “by hand” . . . . . . . . . . . . . . . . . 120
222 Changing margins “on the fly” . . . . . . . . . . . . . . . . . . . . . 121
223 How to get rid of page numbers . . . . . . . . . . . . . . . . . . . . . 121
224 How to create crop marks . . . . . . . . . . . . . . . . . . . . . . . 122
225 ‘Watermarks’ on every page . . . . . . . . . . . . . . . . . . . . . . 122
226 Typesetting things in landscape orientation . . . . . . . . . . . . . . 123
227 Putting things at fixed positions on the page . . . . . . . . . . . . . 124
228 Preventing page breaks between lines . . . . . . . . . . . . . . . . . 124
229 Parallel setting of text . . . . . . . . . . . . . . . . . . . . . . . . . 125
230 Typesetting epigraphs . . . . . . . . . . . . . . . . . . . . . . . . . 126
O.4 Spacing of characters and lines 127
231 Double-spaced documents in LaTeX . . . . . . . . . . . . . . . . . . 127
232 Changing the space between letters . . . . . . . . . . . . . . . . . . . 127
233 Setting text ragged right . . . . . . . . . . . . . . . . . . . . . . . . . 127
234 Cancelling \ragged commands . . . . . . . . . . . . . . . . . . . . 128
O.5 Typesetting specialities 128
235 Including a file verbatim in LaTeX . . . . . . . . . . . . . . . . . . 128
236 Including line numbers in typeset output . . . . . . . . . . . . . . . 129
237 Code listings in LaTeX . . . . . . . . . . . . . . . . . . . . . . . . 129
238 Typesetting pseudocode in LaTeX . . . . . . . . . . . . . . . . . . . 130
239 Generating an index in (La)TeX . . . . . . . . . . . . . . . . . . . . . 131
240 Typesetting URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
241 Typesetting music in TeX . . . . . . . . . . . . . . . . . . . . . . . 132
242 Zero paragraph indent . . . . . . . . . . . . . . . . . . . . . . . . . 133
243 Big letters at the start of a paragraph . . . . . . . . . . . . . . . . . 134
244 The comma as a decimal separator . . . . . . . . . . . . . . . . . . 134
5
 245 Breaking boxes of text . . . . . . . . . . . . . . . . . . . . . . . . . 134
246 Overstriking characters . . . . . . . . . . . . . . . . . . . . . . . . 135
247 Realistic quotes for verbatim listings . . . . . . . . . . . . . . . . . 135
248 Printing the time . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
249 Redefining counters’ \the-commands . . . . . . . . . . . . . . . . 136
O.6 Tables of contents and indexes 136
250 The format of the Table of Contents, etc. . . . . . . . . . . . . . . . 136
251 Unnumbered sections in the Table of Contents . . . . . . . . . . . . 136
252 Bibliography, index, etc., in TOC . . . . . . . . . . . . . . . . . . . . 137
253 Table of contents, etc., per chapter . . . . . . . . . . . . . . . . . . . 137
254 Multiple indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
O.7 Labels and references 139
255 Referring to things by their name . . . . . . . . . . . . . . . . . . . 139
256 Referring to labels in other documents . . . . . . . . . . . . . . . . 140
P How do I do. . . ? 140
P.1 Mathematics 140
257 Proof environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
258 Theorem bodies printed in a roman font . . . . . . . . . . . . . . . . . 141
259 Defining a new log-like function in LaTeX . . . . . . . . . . . . . . . 141
260 Set specifications and Dirac brackets . . . . . . . . . . . . . . . . . . 141
261 Cancelling terms in maths expressions . . . . . . . . . . . . . . . . 142
262 Adjusting maths font sizes . . . . . . . . . . . . . . . . . . . . . . . 142
263 Ellipses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
264 Sub- and superscript positioning for operators . . . . . . . . . . . . 143
265 Text inside maths . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
266 Re-using an equation . . . . . . . . . . . . . . . . . . . . . . . . . 144
267 Line-breaking in in-line maths . . . . . . . . . . . . . . . . . . . . . 144
268 Numbers for referenced equations only . . . . . . . . . . . . . . . . 145
269 Even subscript height . . . . . . . . . . . . . . . . . . . . . . . . . 145
P.2 Lists 145
270 Fancy enumeration lists . . . . . . . . . . . . . . . . . . . . . . . . 145
271 How to adjust list spacing . . . . . . . . . . . . . . . . . . . . . . . 146
272 Interrupting enumerated lists . . . . . . . . . . . . . . . . . . . . . . 147
P.3 Tables, figures and diagrams 148
273 The design of tables . . . . . . . . . . . . . . . . . . . . . . . . . . 148
274 Fixed-width tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
275 Variable-width columns in tables . . . . . . . . . . . . . . . . . . . 149
276 Spacing lines in tables . . . . . . . . . . . . . . . . . . . . . . . . . 150
277 Tables longer than a single page . . . . . . . . . . . . . . . . . . . . . 151
278 How to alter the alignment of tabular cells . . . . . . . . . . . . . . 152
279 The thickness of rules in LaTeX tables . . . . . . . . . . . . . . . . 152
280 Flowing text around figures . . . . . . . . . . . . . . . . . . . . . . 153
281 Diagonal separation in corner cells of tables . . . . . . . . . . . . . 154
282 How to change a whole row of a table . . . . . . . . . . . . . . . . . 154
283 Merging cells in a column of a table . . . . . . . . . . . . . . . . . 154
P.4 Floating tables, figures, etc. 155
284 Floats on their own on float pages . . . . . . . . . . . . . . . . . . . 155
285 Centring a very wide figure or table . . . . . . . . . . . . . . . . . . 155
286 Placing two-column floats at bottom of page . . . . . . . . . . . . . 156
287 Floats in multicolumn setting . . . . . . . . . . . . . . . . . . . . . 156
288 Facing floats on 2-page spread . . . . . . . . . . . . . . . . . . . . 156
289 Vertical layout of float pages . . . . . . . . . . . . . . . . . . . . . . 157
290 Figure (or table) exactly where I want it . . . . . . . . . . . . . . . . . 157
P.5 Footnotes 158
291 Footnotes in tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
292 Footnotes in LaTeX section headings . . . . . . . . . . . . . . . . . 159
293 Footnotes in captions . . . . . . . . . . . . . . . . . . . . . . . . . 159
294 Footnotes whose texts are identical . . . . . . . . . . . . . . . . . . 160
295 More than one sequence of footnotes . . . . . . . . . . . . . . . . . 160
296 Footnotes numbered “per page” . . . . . . . . . . . . . . . . . . . . . 161
297 Not resetting footnote numbers per chapter . . . . . . . . . . . . . . . 161
6
P.6 Document management 161
298 What’s the name of this file . . . . . . . . . . . . . . . . . . . . . . . 161
299 All the files used by this document . . . . . . . . . . . . . . . . . . 162
300 Marking changed parts of your document . . . . . . . . . . . . . . . 162
301 Conditional compilation and “comments” . . . . . . . . . . . . . . . 163
302 Bits of document from other directories . . . . . . . . . . . . . . . . 165
303 Version control using RCS, CVS or the like . . . . . . . . . . . . . . 166
304 Makefiles for LaTeX documents . . . . . . . . . . . . . . . . . . . . . 167
305 How many pages are there in my document? . . . . . . . . . . . . . . 167
306 Including Plain TeX files in LaTeX . . . . . . . . . . . . . . . . . . 168
P.7 Hyphenation 168
307 My words aren’t being hyphenated . . . . . . . . . . . . . . . . . . 168
308 Weird hyphenation of words . . . . . . . . . . . . . . . . . . . . . . 169
309 (Merely) peculiar hyphenation . . . . . . . . . . . . . . . . . . . . 169
310 Accented words aren’t hyphenated . . . . . . . . . . . . . . . . . . 169
311 Using a new language with Babel . . . . . . . . . . . . . . . . . . . 169
312 Stopping all hyphenation . . . . . . . . . . . . . . . . . . . . . . . 170
313 Preventing hyphenation of a particular word . . . . . . . . . . . . . . 171
314 Hyphenation exceptions . . . . . . . . . . . . . . . . . . . . . . . . 172
P.8 Odds and ends 172
315 Typesetting all those TeX-related logos . . . . . . . . . . . . . . . . 172
316 How to do bold-tt or bold-sc . . . . . . . . . . . . . . . . . . . . . . 173
317 Automatic sizing of minipage . . . . . . . . . . . . . . . . . . . . 173
Q Symbols, etc. 174
318 Using symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
319 Symbols for the number sets . . . . . . . . . . . . . . . . . . . . . . 174
320 Better script fonts for maths . . . . . . . . . . . . . . . . . . . . . . 175
321 Setting bold Greek letters in LaTeX maths . . . . . . . . . . . . . . 176
322 The Principal Value Integral symbol . . . . . . . . . . . . . . . . . . 177
323 How to typeset an underscore character . . . . . . . . . . . . . . . . . 177
324 How to type an ‘@’ sign? . . . . . . . . . . . . . . . . . . . . . . . . 177
325 Typesetting the Euro sign . . . . . . . . . . . . . . . . . . . . . . . . 177
326 How to get copyright, trademark, etc. . . . . . . . . . . . . . . . . . 178
327 Using “old-style” figures . . . . . . . . . . . . . . . . . . . . . . . 179
R Macro programming 179
R.1 “Generic” macros and techniques 179
328 Non-letters in macro names . . . . . . . . . . . . . . . . . . . . . . 179
329 Repeating a command n times . . . . . . . . . . . . . . . . . . . . . 180
330 Repeating something for each ‘thing’ in a set . . . . . . . . . . . . . 182
331 Finding the width of a letter, word, or phrase . . . . . . . . . . . . . 182
332 Patching existing commands . . . . . . . . . . . . . . . . . . . . . 182
333 Comparing the “job name” . . . . . . . . . . . . . . . . . . . . . . 184
334 Is the argument a number? . . . . . . . . . . . . . . . . . . . . . . . 184
335 Defining macros within macros . . . . . . . . . . . . . . . . . . . . 185
336 Spaces in macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
337 How to break the 9-argument limit . . . . . . . . . . . . . . . . . . . 187
338 Key-value input for macros and package options . . . . . . . . . . . . 187
339 Defining characters as macros . . . . . . . . . . . . . . . . . . . . . 189
340 Active characters in command arguments . . . . . . . . . . . . . . . 190
341 Defining a macro from an argument . . . . . . . . . . . . . . . . . . . 191
342 Transcribing LaTeX command definitions . . . . . . . . . . . . . . . 191
343 Detecting that something is empty . . . . . . . . . . . . . . . . . . 192
344 Am I using PDFTeX, XeTeX or LuaTeX? . . . . . . . . . . . . . . 192
345 Subverting a token register . . . . . . . . . . . . . . . . . . . . . . 193
346 Is this command defined? . . . . . . . . . . . . . . . . . . . . . . . 193

7
R.2 LaTeX macro tools and techniques 194
347 Using Plain or primitive commands in LaTeX . . . . . . . . . . . . 194
348 \@ and @ in macro names . . . . . . . . . . . . . . . . . . . . . . . 195
349 What’s the reason for ‘protection’? . . . . . . . . . . . . . . . . . . 195
350 \edef does not work with \protect . . . . . . . . . . . . . . . . . 196
351 The definitions of LaTeX commands . . . . . . . . . . . . . . . . . 196
352 Optional arguments like \section . . . . . . . . . . . . . . . . . . 198
353 More than one optional argument . . . . . . . . . . . . . . . . . . . 198
354 Commands defined with * options . . . . . . . . . . . . . . . . . . 199
355 LaTeX internal “abbreviations”, etc. . . . . . . . . . . . . . . . . . 200
356 Defining LaTeX commands within other commands . . . . . . . . . 200
357 How to print contents of variables? . . . . . . . . . . . . . . . . . . . 201
358 Using labels as counter values . . . . . . . . . . . . . . . . . . . . . . 201
R.3 LaTeX macro programming 201
359 How to change LaTeX’s “fixed names” . . . . . . . . . . . . . . . . . 201
360 Changing the words babel uses . . . . . . . . . . . . . . . . . . . . 202
361 Running equation, figure and table numbering . . . . . . . . . . . . 202
362 Making labels from a counter . . . . . . . . . . . . . . . . . . . . . 203
363 Finding if you’re on an odd or an even page . . . . . . . . . . . . . 203
364 How to change the format of labels . . . . . . . . . . . . . . . . . . 204
365 Adjusting the presentation of section numbers . . . . . . . . . . . . 205
366 There’s a space added after my environment . . . . . . . . . . . . . 205
367 Finding if a label is undefined . . . . . . . . . . . . . . . . . . . . . 205
368 Master and slave counters . . . . . . . . . . . . . . . . . . . . . . . 206
369 Fonts at arbitrary sizes . . . . . . . . . . . . . . . . . . . . . . . . . 206
370 The quality of your LaTeX . . . . . . . . . . . . . . . . . . . . . . . 207
371 Process a CSV file in LaTeX . . . . . . . . . . . . . . . . . . . . . . 207
S Things are Going Wrong. . . 208
S.1 Getting things to fit 208
372 Enlarging TeX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
373 Why can’t I load PiCTeX? . . . . . . . . . . . . . . . . . . . . . . . 208
S.2 Making things stay where you want them 209
374 Moving tables and figures in LaTeX . . . . . . . . . . . . . . . . . . 209
375 Underlined text won’t break . . . . . . . . . . . . . . . . . . . . . . 210
376 Controlling widows and orphans . . . . . . . . . . . . . . . . . . . 210
S.3 Things have “gone away” 211
377 Old LaTeX font references such as \tenrm . . . . . . . . . . . . . . . 211
378 Missing symbol commands . . . . . . . . . . . . . . . . . . . . . . . 211
379 Where are the msx and msy fonts? . . . . . . . . . . . . . . . . . . . . 211
380 Where are the am fonts? . . . . . . . . . . . . . . . . . . . . . . . . . 211
381 What’s happened to initex? . . . . . . . . . . . . . . . . . . . . . . 212
T Why does it do that? 212
T.1 Common errors 212
382 LaTeX gets cross-references wrong . . . . . . . . . . . . . . . . . . 212
383 Start of line goes awry . . . . . . . . . . . . . . . . . . . . . . . . . 213
384 Why doesn’t verbatim work within . . . ? . . . . . . . . . . . . . . . . 213
385 “No line here to end” . . . . . . . . . . . . . . . . . . . . . . . . . 215
386 Extra vertical space in floats . . . . . . . . . . . . . . . . . . . . . . 216
387 Why is my table/figure/. . . not centred? . . . . . . . . . . . . . . . . 216
388 Two-column float numbers out of order . . . . . . . . . . . . . . . . . 217
389 Accents misbehave in tabbing . . . . . . . . . . . . . . . . . . . . . 217
390 Package reports “command already defined” . . . . . . . . . . . . . . 217
391 Why are my sections numbered 0.1 . . . ? . . . . . . . . . . . . . . . 218
392 Link text doesn’t break at end line . . . . . . . . . . . . . . . . . . . 218
393 Page number is wrong at start of page . . . . . . . . . . . . . . . . . 218
394 My brackets don’t match . . . . . . . . . . . . . . . . . . . . . . . 219
395 Characters disappear from figures in PDFTeX . . . . . . . . . . . . 219
396 I asked for “empty”, but the page is numbered . . . . . . . . . . . . 220

8
T.2 Common misunderstandings 220
397 What’s going on in my \include commands? . . . . . . . . . . . . 220
398 Why does it ignore paragraph parameters? . . . . . . . . . . . . . . 220
399 Case-changing oddities . . . . . . . . . . . . . . . . . . . . . . . . . 221
400 Why does LaTeX split footnotes across pages? . . . . . . . . . . . . . 221
401 Getting \marginpar on the right side . . . . . . . . . . . . . . . . . 222
402 Where have my characters gone? . . . . . . . . . . . . . . . . . . . 222
403 “Rerun” messages won’t go away . . . . . . . . . . . . . . . . . . . 222
404 Commands gobble following space . . . . . . . . . . . . . . . . . . 223
405 (La)TeX makes overfull lines . . . . . . . . . . . . . . . . . . . . . 223
406 Maths symbols don’t scale up . . . . . . . . . . . . . . . . . . . . . 225
407 Why doesn’t \linespread work? . . . . . . . . . . . . . . . . . . 225
408 Only one \baselineskip per paragraph . . . . . . . . . . . . . . . 225
409 Numbers too large in table of contents, etc. . . . . . . . . . . . . . . 226
410 Why is the inside margin so narrow? . . . . . . . . . . . . . . . . . 226
T.3 Why shouldn’t I? 227
411 Why use fontenc rather than t1enc? . . . . . . . . . . . . . . . . . . . 227
412 Why bother with inputenc and fontenc? . . . . . . . . . . . . . . . . . 227
413 Why not use eqnarray? . . . . . . . . . . . . . . . . . . . . . . . . . 227
414 Why use \[ . . . \] in place of $$ . . . $$? . . . . . . . . . . . . . . . . 228
415 What’s wrong with \bf, \it, etc.? . . . . . . . . . . . . . . . . . . 228
416 What’s wrong with \newfont? . . . . . . . . . . . . . . . . . . . . 229
U The joy of TeX errors 229
417 How to approach errors . . . . . . . . . . . . . . . . . . . . . . . . 229
418 The structure of TeX error messages . . . . . . . . . . . . . . . . . 230
419 An extra ‘}’?? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
420 Capacity exceeded [semantic nest . . . ] . . . . . . . . . . . . . . . . . 231
421 No room for a new ‘thing’ . . . . . . . . . . . . . . . . . . . . . . . 232
422 epsf gives up after a bit . . . . . . . . . . . . . . . . . . . . . . . . 232
423 Improper \hyphenation will be flushed . . . . . . . . . . . . . . . 233
424 Option clash for package . . . . . . . . . . . . . . . . . . . . . . . 233
425 Option clash for package . . . . . . . . . . . . . . . . . . . . . . . 234
426 “Too many unprocessed floats” . . . . . . . . . . . . . . . . . . . . 235
427 \spacefactor complaints . . . . . . . . . . . . . . . . . . . . . . 235
428 \end occurred inside a group . . . . . . . . . . . . . . . . . . . . . 235
429 “Missing number, treated as zero” . . . . . . . . . . . . . . . . . . . 236
430 “Please type a command or say \end” . . . . . . . . . . . . . . . . 236
431 “Unknown graphics extension” . . . . . . . . . . . . . . . . . . . . . 237
432 “Missing $ inserted” . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
433 Warning: “Font shape . . . not available” . . . . . . . . . . . . . . . 238
434 Unable to read an entire line . . . . . . . . . . . . . . . . . . . . . . 238
435 “Fatal format file error; I’m stymied” . . . . . . . . . . . . . . . . . 239
436 Non-PDF special ignored! . . . . . . . . . . . . . . . . . . . . . . . 239
437 Mismatched mode ljfour and resolution 8000 . . . . . . . . . . . . . 239
438 “Too deeply nested” . . . . . . . . . . . . . . . . . . . . . . . . . . 240
439 Capacity exceeded — input levels . . . . . . . . . . . . . . . . . . . 240
440 PDFTeX destination . . . ignored . . . . . . . . . . . . . . . . . . . . 240
441 Alignment tab changed to \cr . . . . . . . . . . . . . . . . . . . . . . 241
442 Graphics division by zero . . . . . . . . . . . . . . . . . . . . . . . . 241
443 Missing \begin{document} . . . . . . . . . . . . . . . . . . . . . 242
444 \normalsize not defined . . . . . . . . . . . . . . . . . . . . . . . 242
445 Too many math alphabets . . . . . . . . . . . . . . . . . . . . . . . 243
446 Not in outer par mode . . . . . . . . . . . . . . . . . . . . . . . . . 243
447 Perhaps a missing \item? . . . . . . . . . . . . . . . . . . . . . . . 243
448 Illegal parameter number in definition . . . . . . . . . . . . . . . . 244
449 Float(s) lost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
450 Not in outer par mode . . . . . . . . . . . . . . . . . . . . . . . . . 245
451 Token not allowed in PDFDocEncoded string . . . . . . . . . . . . . 245
452 Checksum mismatch in font . . . . . . . . . . . . . . . . . . . . . . 246
453 Entering compatibility mode . . . . . . . . . . . . . . . . . . . . . 246
454 LaTeX won’t include from other directories . . . . . . . . . . . . . 246

9
 455 Support package expl3 too old . . . . . . . . . . . . . . . . . . . . . . 247
V Current TeX-related projects 247
456 The LaTeX project . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
457 Future WWW technologies and (La)TeX . . . . . . . . . . . . . . . 248
458 Making outline fonts from Metafont . . . . . . . . . . . . . . . . . 249
459 The TeX document preparation environment . . . . . . . . . . . . . 249
460 Omega and Aleph . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
461 XeTeX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
462 PDFTeX and LuaTeX . . . . . . . . . . . . . . . . . . . . . . . . . . 251
463 The ANT typesetting system . . . . . . . . . . . . . . . . . . . . . 252
464 The ExTeX project . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
465 Replacing the BibTeX–LaTeX mechanism . . . . . . . . . . . . . . 252
W You’re still stuck? 253
466 You don’t understand the answer . . . . . . . . . . . . . . . . . . . 253
467 Submitting new material for the FAQ . . . . . . . . . . . . . . . . . 253
468 What to do if you find a bug . . . . . . . . . . . . . . . . . . . . . . 254
469 Reporting a LaTeX bug . . . . . . . . . . . . . . . . . . . . . . . . 254
§ § § § § § § § § § § § § § § § § §

Introduction copies, also in the FAQ’s CTAN directory)

are all placed in the public domain.
This is a set of Frequently Asked Ques-
tions (FAQ) for English-speaking users of Finding the Files
TeX. Unless otherwise specified, all files men-
The questions answered here cover a tioned in this FAQ are available from
wide range of topics, but typesetting is- a CTAN archive, or from a mirror of
sues are mostly covered from the view- CTAN — see later discussion of the CTAN
point of a LaTeX user. Some of the ques- archives and how to retrieve files from
tions answered have little relevance to to- them.
day’s users; this is inevitable — it’s easier The reader should also note that the
to add information than it is to decide that first directory name of the path name of
information is no longer needed. The set of every file on CTAN is omitted from what
answered questions is therefore in a state follows, for the simple reason that, while
of slow flux: new questions are answered, it’s always the same (tex-archive/) on
while old questions are deleted . . . but the the main sites, mirror sites often choose
whole process depends on the time avail- something else.
able for FAQ maintenance. To avoid confusion, we also omit the
You may use the FAQ full stop from the end of any sentence
whose last item is a path name (such sen-
• by reading a printed document, tences are rare, and only occur at the end
• by viewing a PDF file, with hyperlinks of paragraphs). Though the path names are
to assist browsing: copies are avail- set in a different font from running text, it’s
able formatted so that they could be not easy to distinguish the font of a single
printed on A4 paper or on North Amer- dot!
ican “letter” paper,
• by using the FAQ’s web interface Origins
(base URL: http://www.tex.ac.
The FAQ was originated by the Committee
uk/faq); this version provides simple
of the UK TeX Users’ Group (UK TUG),
search capabilities, as well as a link
in 1994, as a development of a regular post-
to Google for a more sophisticated
ing to the Usenet newsgroup comp.text.
search restricted to the FAQ itself, or
tex that was maintained for some time by
• via Scott Pakin’s Visual FAQ, which
Bobby Bodenheimer. The first UK version
shows LaTeX constructions with links
was much re-arranged and corrected from
to FAQ explanations of how they may
the original, and little of Bodenheimer’s
be created.
work now remains.
The following people (at least — there
Licence of the FAQ
are almost certainly others whose names
The source of the FAQ, available in the weren’t correctly recorded) have con-
FAQ’s CTAN directory, and its derived rep- tributed help or advice on the development
resentations (currently, the HTML found of the FAQ: William Adams, Donald Ar-
at http://www.tex.ac.uk/faq and PDF seneau, Rosemary Bailey, Barbara Bee-
10
ton, Karl Berry, Giuseppe Bilotta, Charles ner needs to decide what macro format she
Cameron, François Charette, Damian Cu- needs (always assuming someone hasn’t
gley, Martin Garrod, Michael Dewey, already told her she needs to use “fooTeX”.
Michael Downes, Jean-Pierre Drucbert, Learn about the alternatives in answers dis-
David Epstein, Michael Ernst, Thomas cussing common formats: look at writing
Esser, Ulrike Fischer, Bruno Le Floch, Plain TeX, LaTeX or ConTeXt.
Anthony Goreham, Norman Gray, En- If no system has been provided, the be-
rico Gregorio, Werner Grundlingh, Eitan ginner needs to acquire a TeX distribution
Gurari, William Hammond, John Ham- appropriate to their machine. Available op-
mond, John Harper, Gernot Hassenpflug, tions are available via the answer “(La)TeX
Troy Henderson, Hartmut Henkel, Stephan for various machines”; we assume here
Hennig, John Hobby, Morten Høgholm, that the beginner can install things for her-
Berthold Horn, Ian Hutchinson, Werner self, or has access to someone who can.
Icking, William Ingram, David Jansen, Finally, the beginner needs to get
Alan Jeffrey, Regnor Jernsletten, David started in the chosen format. For Plain TeX,
Kastrup, Oleg Katsitadze, Isaac Khabaza, see “Online introductions: TeX”; for La-
Ulrich Klauer, Markus Kohm, Stefan Kot- TeX, see “Online introductions: LaTeX”;
twitz David Kraus, Ryszard Kubiak, Si- and for ConTeXt, the place to start is the
mon Law, Uwe Lück, Daniel Luecking, ConTeXt garden wiki (which is so good the
Aditya Mahajan, Sanjoy Mahajan, Diego present FAQs don’t even try to compete).
Andres Alvarez Marin, Andreas Matthias,
Steve Mayer, Javier Mora, Brooks Moses, 2 What is TeX?
Peter Moulder, Iain Murray, Vilar Camara TeX is a typesetting system written by Don-
Neto, Dick Nickalls, Ted Nieland, Hans ald E. Knuth, who says in the Preface to his
Nordhaug, Pat Rau, Heiko Oberdiek, Piet book on TeX (see books about TeX) that
van Oostrum, Scott Pakin, Oren Patash- it is “intended for the creation of beautiful
nik, Manuel Pégourié-Gonnard, Steve books — and especially for books that con-
Peter, Sebastian Rahtz, Philip Ratcliffe, tain a lot of mathematics”. (If TeX were
Chris Rowley, José Carlos Santos, Walter only good for mathematical books, much
Schmidt, Hans-Peter Schröcker, Joachim of its use nowadays would not happen: it’s
Schrod, Uwe Siart, Maarten Sneep, Axel actually a pretty good general typesetting
Sommerfeldt, Philipp Stephani, James system.)
Szinger, Nicola Talbot, Bob Tennent,
Knuth is Emeritus Professor of the
Tomek Trzeciak, Ulrik Vieth, Mike Vulis,
Art of Computer Programming at Stanford
Chris Walker, Peter Wilson, Joseph Wright,
University in California, USA. Knuth de-
Rick Zaccone, Gregor Zattler and Rein-
veloped the first version of TeX in 1978 to
hard Zierke.
deal with revisions to his series “the Art of
That list does not cover the many peo- Computer Programming”. The idea proved
ple whose ideas were encountered on vari- popular and Knuth produced a second ver-
ous mailing lists, in newsgroups, or (more sion (in 1982) which is the basis of what
recently!) in web forums. Many such peo- we use today.
ple have helped, even if simply to highlight
Knuth developed a system of ‘literate
an area in which FAQ work would be use-
programming’ to write TeX, and he pro-
ful.
vides the literate (WEB) source of TeX
free of charge, together with tools for pro-
cessing the web source into something that
A The Background can be compiled and something that can
be printed; there is (in principle) never any
1 Getting started mystery about what TeX does. Further-
(La)TeX offers a very large number of more, the WEB system provides mecha-
choices, and the beginner has to navigate nisms to port TeX to new operating sys-
through that set before even taking his first tems and computers; and in order that one
steps. The aim here is to guide the be- may have some confidence in the ports,
ginner through a set of answers that may Knuth supplied a test by means of which
help the process. We assume the beginner one may judge the fidelity of a TeX system.
‘knows’ that (La)TeX is for them; if not, TeX and its documents are therefore highly
the discussion “what is TeX” may help. portable.
To start at the very beginning, then, the For the interested programmer, the dis-
beginner may wish to know what all those tribution of TeX has some fascination: it’s
“things with TeX in their name are”. nothing like the way one would construct
Armed with that knowledge, the begin- such a program nowadays, yet it has lasted
11
better than most, and has been ported to sizes of glyphs, for TeX’s benefit, and cre-
many different computer architectures and ates bitmaps that may be used to represent
operating systems — the sorts of attributes the glyphs, for the benefit of programs that
that much modern programming practice will produce printed output as post pro-
aims for. The processed ‘readable’ source cesses after a run of TeX.
of TeX the program may be found in the Metafont’s language for defining fonts
TDS structured version of the distribution. permits the expression of several classes of
Knuth’s source distribution: things: first (of course), the simple geom-
systems/knuth/dist etry of the glyphs; second, the properties
of the print engine for which the output
Knuth’s sources in TDS layout: is intended; and third, ‘meta’-information
macros/latex/contrib/latex- which can distinguish different design
tds/knuth.tds.zip sizes of the same font, or the difference
between two fonts that belong to the same
3 What’s “writing in TeX”?
(or related) families.
TeX is a macro processor, and offers its Knuth (and others) have designed a fair
users a powerful programming capability. range of fonts using Metafont, but font de-
To produce a document, you write macros sign using Metafont is much more of a
and text interleaved with each other. The minority skill (even) than is TeX macro-
macros define an environment in which the writing. What is more, it is a dying art:
text is to be typeset. few new TeX-related fonts are produced
However, the basic TeX engine is using Metafont, nowadays. Indeed, several
pretty basic, and is a pretty difficult beast of the major font families (that originated
to deal with. Recognising this (and not in Metafont designs) are now seldom used
wanting to write the same things at the in any other way than their conversion to
start of every document, himself) Knuth an outline font format.
provided a package of macros for use with
TeX, called Plain TeX; Plain TeX is a use- 6 What is Metapost?
ful minimum set of macros that can be used The Metapost system (by John Hobby)
with TeX, together with some demonstra- implements a picture-drawing language
tion versions of higher-level commands. very much like that of Metafont; the
When people say they’re “writing (or pro- difference is that Metapost outputs vec-
gramming) in TeX”, they usually mean tor graphic files instead of run-length-
they’re programming in Plain TeX. encoded bitmaps; output formats available
are PostScript or SVG Metapost is a power-
4 How should I pronounce “TeX”? ful language for producing figures for doc-
The ‘X’ is “really” the Greek letter Chi uments to be printed on PostScript print-
(χ, in lower case), and is pronounced by ers, either directly or embedded in (La)TeX
English-speakers either a bit like the ‘ch’ in documents. Metapost is able to integrate
the Scots word ‘loch’ ([x] in the IPA) or (at text and mathematics, marked up for use
a pinch, if you can’t do the Greek sound) with TeX, within the graphics. (Knuth tells
like ‘k’. It definitely is not pronounced ‘ks’ us that he uses nothing but Metapost for
(the Greek letter with that sound doesn’t diagrams in text that he is writing.)
look remotely like the Latin alphabet ‘X’). Although PDFLaTeX cannot ordinar-
This curious usage derives from ily handle PostScript graphics, the output
Knuth’s explanation in the TeXbook that of Metapost is sufficiently simple and reg-
the name comes from the Greek word for ular that PDFLaTeX can handle it direct,
‘art’ or ‘craft’ (‘τε χνη’), which is the root using code borrowed from ConTeXt — see
of the English word ‘technology’. Knuth’s graphics in PDFLaTeX.
logo for TeX is merely the uppercase ver- Much of Metapost’s source code was
sion of the first three (Greek) letters of the copied from Metafont’s sources, with
word, jiggled about a bit; we don’t use that Knuth’s permission.
logo (and logos like it) in this FAQ (see A mailing list discussing Metapost is
Typesetting TeX-related logos). available; subscribe via the TUG mailman
interface. The TUG website also hosts
5 What is Metafont? a Metapost summary page, and the tex-
overview document gives you a lot more
Metafont was written by Knuth as a com-
detail (and some explanatory background
panion to TeX; whereas TeX defines the
material).
layout of glyphs on a page, Metafont de-
fines the shapes of the glyphs and the rela- tex-overview.pdf :
tions between them. Metafont details the info/tex-overview
12
7 Things with “TeX” in the name a separate executable such as initex or
New TeX users are often baffled by the as a -ini flag to tex.
myriad terms with “TeX” in the name. The LaTeX (executable: latex) See Books on
goal of this answer is to clarify some of the TeX and its relations, (La)TeX Tuto-
more common such terms. rials, etc., Online introductions: La-
TeX and Specialized (La)TeX tutori-
TeX itself TeX proper is a typesetting als. Note that there have been two ma-
system based on a set of low-level con- jor versions of LaTeX: LaTeX2e refers
trol sequences that instruct TeX how to to the current version of LaTeX while
lay out text on the page. For example, LaTeX 2.09 is the long-since-obsolete
\hskip inserts a given amount of horizon- (since 1994) version (cf. What is La-
tal space into the document, and \font TeX2e? for more information).
makes a given font available in a docu- ConTeXt (executable: texmfstart) See
ment. TeX is fully programmable using an What is ConTeXt?.
integrated macro scripting language that Texinfo (executables: tex, makeinfo)
supports variables, scoping, conditional See What is Texinfo?. makeinfo con-
execution, control flow, and function (re- verts Texinfo documents to HTML,
ally, macro) definitions. See what is TeX? DocBook, Emacs info, XML, and
for some background information on TeX plain text. Tex (or wrappers such as
and some reference documents for pointers texi2dvi and texi2pdf ) produce one
to descriptions of TeX control sequences, of TeX’s usual output formats such
data types, and other key parts of TeX. as DVI or PDF. Because tex loads
the Plain TeX macros, not the Texinfo
TeX macro packages (a.k.a. TeX for- ones, a Texinfo document must begin
mats) Some of TeX’s control sequences with
are tedious to use directly; they are in-
tended primarily as building blocks for \input texinfo
higher-level — and therefore more user- explicitly load the Texinfo macro
friendly — abstractions. For example, package.
there is no way in base TeX to specify Eplain — Extended Plain TeX (executable: eplain)
that a piece of text should be typeset in See What is Eplain?.
a larger font. Instead, one must keep track
of the current size and typeface, load a new Modified tex executables The original
font with the same typeface but a (speci- tex executable was produced in the late
fied) larger size, and tell TeX to use that 1970s (cf. What is TeX?) and consequently
new font until instructed otherwise. For- lacked some features that users have come
tunately, because TeX is programmable, it to expect from today’s software. The fol-
is possible to write a macro that hides this lowing programs address these issues by
complexity behind a simple, new control augmenting the TeX engine with some ad-
sequence. (For example, it is possible to ditional useful features:
define \larger{my text} to typeset “my
text” in at a font size next larger than the PDFTeX (executable: pdftex) TeX,
current one.) which predates the PDF file format
While some users write their own, per- by a decade, outputs files in a TeX-
fectly customized set of macros — which specific format called DVI (cf. What
they then typically reuse across many doc- is a DVI file?). In contrast, PDFTeX
uments — it is far more common to rely can output both DVI and PDF files.
upon a macro package, a collection of TeX In PDF mode, it lets documents ex-
macros written by experts. For the user’s ploit various PDF features such as
convenience, these macro packages are of- hyperlinks, bookmarks, and annota-
ten combined with the base TeX engine tions, PDFTeX additionally supports
into a standalone executable. The follow- two sophisticated micro-typographic
ing are some of that macro packages that features: character protrusion and font
you are likely to encounter: expansion. See What is PDFTeX?.
XeTeX (executable: xetex) XeTeX reads
Plain TeX (executable: tex) See Books UTF-8 encoded Unicode input, and
on TeX and Plain TeX, Online intro- extends TeX’s font support to include
ductions: TeX, Should I use Plain ‘modern’ formats such as TrueType
TeX or LaTeX? and Freely available and OpenType; these extensions to
(La)TeX books. Note that the Plain its capabilities make it well-suited to
TeX executable is called tex; the base multi-lingual texts covering different
TeX engine is generally provided by writing systems. See What is XeTeX?.
13
LuaTeX (executable: luatex) TeX is tions include TeX Live, MiKTeX and Mac-
programmed in its own arcane, in- TeX; older ones include ozTeX, CMacTeX
tegrated, macro-based programming and teTeX. MiKTeX is also available as the
language. LuaTeX adds a second basis of the ProTeXt bundle, distributed on
programming engine using a modern the TeX Live DVD mailing, as well as be-
scripting language, Lua, which is ‘em- ing available online.
bedded’ in a TeX-alike engine; it too Some TeX distributions target a spe-
reads UTF-8 and uses TrueType Open- cific operating system and/or processor
Type fonts. See What is LuaTeX?. architecture; others run on multiple plat-
e-TeX (executable: etex) e-TeX is an ex- forms. Many TeX distributions are free;
tension of TeX’s programming inter- a few require payment. See (La)TeX for
face; as such it’s only indirectly useful different machines for a list of free and
to end users, but it can be valuable shareware TeX distributions and Commer-
to package developers; there is an in- cial TeX implementations for a list of com-
creasing number of macro packages mercial TeX distributions.
that require the use of e-TeX. As well Summary What does it all mean? — the
as existing in etex, e-TeX features are simple lists of objects, alone, offer no help
usually available in the pdftex executa- for the beginner. The FAQ team expects
bles provided in the standard distribu- this answer only to be of use for people
tions; XeTeX and LuaTeX also pro- who are seeking guidance elsewhere (possi-
vide e-TeX’s programming facilities. bly within these FAQs) and coming across
See What is e-TeX?. an unexpected name like “blahTeX”.
(Note: e-TeX, which enhances the The subject matter covered by this an-
TeX engine, is not to be confused with swer is also addressed in a page on the
Eplain, which enhances the Plain TeX TUG site, “the Levels of TeX”.
macro package.)
8 What is CTAN?
Because each of the above derive from The acronym stands for “Comprehensive
a base TeX engine, it is in principle pos- TeX Archive Network”, which more-or-
sible to combine any of them with one of less specifies what it’s for:
the TeX macro packages listed earlier to
• The archives offer a comprehensive
produce ‘extended’ executables. For ex-
collection of TeX resources.
ample, the pdflatex, xelatex and lualatex
• The content is made publicly accessi-
executables each combine LaTeX with an
ble, via the internet.
enhanced TeX engine. Indeed, most (if not
• CTAN is a network of archives, which
all) of the development of ConTeXt is now
strive to stay in step with one another.
using LuaTeX.
Some executables combine the features The basic framework was developed by
of multiple enhanced TeX engines: for ex- a TUG working group set up to resolve
ample, pdftex now (in current distributions) the (then existing) requirement for users
offers both PDFTeX and e-TeX extensions to know on which archive site a particular
into a single executable This executable package might be found.
may be offered with a LaTeX format (as Actual implementation offers three dis-
latex or pdflatex) or with a Plain TeX for- tinct types of host:
mat (as pdftex). (Tex remains with an un- Core archives Which form a small,
adorned TeX executable using Plain TeX, tightly-coupled set of machines,
for people such as Knuth himself, who which perform management functions
want the certainty of the “original”.) as well as serving files;
TeX distributions A TeX distribution Mirror archives Which do no more than
provides a structured collection of TeX- take regular copies of core archives,
related software. Generally, a TeX distribu- and serve them; and
tion includes a set of “core” TeX executa- Archive selector Which is a meta-
bles such as tex and latex; various fonts op- service, which routes requests to an
timized for use with TeX; helper programs apparently “local” mirror (“local” is
such as the BibTeX bibliographic-database determined by an algorithm that uses
formatter, editors, integrated development your net address to determine where
environments, file-format-conversion pro- you are, and then selects a mirror
grams; numerous LaTeX packages; con- that’s close).
figuration tools; and any other goodies the Note that there is nothing to prevent any
distributor chooses to include. archive from supporting other functions,
Commonly encountered TeX distribu- so a CTAN mirror may also operate as a
14
CPAN (Perl) mirror and as a SourceForge The CTAN central database machine
(general free software) mirror, and . . . offers a “Browse CTAN” area, with links
Functions that distinguish core to the list of packages, to a list of ‘topics’
archives are: (with packages that match each topic), and
to a list of authors (with their packages).
• Uploads: users may submit new (or In addition, every CTAN mirror holds
updated) material via the upload redi- a copy of the catalogue, presented as a se-
rector. Significant changes to the ries of web pages; one may scan the files in
archive are reported via the mailing alphabetic order, or use a category-based
list [email protected] index. Such access is not as “sophisticated”
• Weak consistency: changes to the con- as that on the central site, but it served for
tent of the archives are rapidly dis- years before the central site appeared.
tributed to all core archives. (Consis-
tency is ‘weak’ since changes can take The CTAN catalogue (on CTAN):
help/Catalogue
several minutes to propagate.)
• Providing distribution (TeX Live and 10 How can I be sure it’s really TeX?
MiKTeX) support.
• Catalogue maintenance. TeX (and Metafont and Metapost) are
• Mirror monitoring. written in a ‘literate’ programming lan-
guage called Web which is designed to be
Users may make direct contact with the portable across a wide range of computer
CTAN management team. systems. How, then, is a new version of
Users should ordinarily download ma- TeX checked?
terial from CTAN via the archive selector: Of course, any sensible software im-
this uses the mirror monitor’s database, and plementor will have his own suite of tests
uses the caller’s geographical location to to check that his software runs: those who
offer an efficient choice of “sufficiently up- port TeX and its friends to other platforms
to-date” mirror site for you to connect to. do indeed perform such tests.
This procedure has the advantage of dis- Knuth, however, provides a ‘confor-
tributing the load on CTAN mirrors. mance test’ for both TeX (trip) and Meta-
Note that all the download links, given font (trap). He characterises these as ‘tor-
in the web representation of these FAQs, ture tests’: they are designed not to check
are set up to use the mirror selector. the obvious things that ordinary typeset
documents, or font designs, will exercise,
9 The (CTAN) catalogue but rather to explore small alleyways off
Finding stuff on networks used always to the main path through the code of TeX.
be difficult, but in recent years, search en- They are, to the casual reader, pretty in-
gines have become amazingly good at dig- comprehensible!
ging out unconsidered trifles from the myr- Once an implementation of TeX has
iad items of information available on the passed its trip test, or an implementation
net. However, for the (La)TeX user, confu- of Metafont has passed its trap test, then it
sion is added by the tendency to index the may in principle be distributed as a work-
same file at several CTAN mirror sites. ing version. (In practice, any distributor
Further, the (La)TeX user usually would test new versions against “real” doc-
needs the most recent version of a pack- uments or fonts, too; while trip and trap
age; it’s a rare search result that describes test bits of pathways within the program,
itself as obsolete! they don’t actually test for any real world
The CTAN catalogue, several years af- problem.)
ter it was introduced, has developed into a
powerful tool for dealing with these dif- 11 What is e-TeX?
ficulties. It provides an entry for each While Knuth has declared that TeX will
package to be found on CTAN; users may never change in any substantial way, there
search the catalogue for an entry, or they remain things that one might wish had been
may browse its contents, using the cata- done differently, or indeed implemented at
logue’s lists of “categories” of item. all.
The basis of the catalogue is a col- The NTS project set out to produce
lection of small, stylised, articles; each an advanced replacement for TeX, to pro-
shows basic information about a package vide a basis for developing such modifi-
on CTAN, and includes pointers to down- cations: this “New Typesetting System”
load address (on a CTAN mirror), docu- would share Knuth’s aims, but would im-
mentation and home page if any, and re- plement the work in a modern way taking
lated packages. account of the lessons learned with TeX.
15
While a first demonstrator NTS did appear, tenance and development of PDFTeX 1.0
it wasn’t practically useful, and the project (and later) has been in the hands of a group
seems no longer active. of PDFTeX maintainers (which includes
In parallel with its work on NTS itself, Thành); the group has managed to main-
the project developed a set of extensions tain a stable platform for general use.
that can be used with a (“true”) TeX sys- Development of PDFTeX has mostly
tem. Such a modified system is known stopped (only bug fixes, and occasional
as an e-TeX system, and the concept has small development items are processed):
proved widely successful. Indeed, current future development is focused on LuaTeX.
TeX distributions are delivered with most
formats built with an e-TeX-based system 13 What is LaTeX?
(for those who don’t want them, e-TeX’s LaTeX is a TeX macro package, originally
extensions can be disabled, leaving a func- written by Leslie Lamport, that provides
tionally standard TeX system). a document processing system. LaTeX al-
The extensions range from the seem- lows markup to describe the structure of a
ingly simple (increasing the number of document, so that the user need not think
available registers from 256 to 32768) about presentation. By using document
through to extremely subtle programming classes and add-on packages, the same doc-
support. ument can be produced in a variety of dif-
ConTeXt has required e-TeX for its op- ferent layouts.
eration for some time, though development Lamport says that LaTeX “represents a
is now focused on the use of LuaTeX. balance between functionality and ease of
Some LaTeX packages already spec- use”. This shows itself as a continual con-
ify the use of e-TeX. Some such packages flict that leads to the need for such things
may not work at all on a non-e-TeX sys- as FAQs: LaTeX can meet most user re-
tem; others will work, but not as well as quirements, but finding out how is often
on an e-TeX system. The LaTeX team tricky.
has announced that future LaTeX packages
(specifically those from the team, as op- 14 What is LaTeX2e?
posed to those individually contributed) Lamport’s last version of LaTeX (La-
may require e-TeX for optimum perfor- TeX 2.09, last updated in 1992) was super-
mance. seded in 1994 by a new version (LaTeX2e)
e-TeX : systems/e-tex provided by the LaTeX team. LaTeX2e is
now the only readily-available version of
12 What is PDFTeX? LaTeX, and draws together several threads
One can reasonably say that PDFTeX is of LaTeX development from the later days
(today) the main stream of TeX distribu- of LaTeX 2.09. The “e” of the name is (in
tions: most LaTeX and many ConTeXt the official logo) a single-stroke epsilon (ε,
users nowadays use PDFTeX whether they supposedly indicative of no more than a
know it or not (more precisely, they use small change).
PDFTeX extended by e-TeX). So what is LaTeX2e has several enhancements
PDFTeX? over LaTeX 2.09, but they were all rather
PDFTeX is a development of TeX that minor, with a view to continuity and stabil-
is capable of generating typeset PDF out- ity rather than the “big push” that some
put in place of DVI. PDFTeX has other had expected from the team. LaTeX2e
capabilities, most notably in the area of continues to this day to offer a compati-
fine typographic detail (for example, its bility mode in which most files prepared
support for optimising line breaks), but its for use with LaTeX 2.09 will run (albeit
greatest impact to date has been in the area with somewhat reduced performance, and
of PDF output. subject to voluminous complaints in the
PDFTeX started as a topic for Hàn Thế log file). Differences between LaTeX2e
Thành’s Master’s thesis, and seems first to and LaTeX 2.09 are outlined in a series of
have been published in TUGboat 18(4), in ‘guide’ files that are available in every La-
1997 (though it was certainly discussed at TeX distribution (the same directory also
the TUG’96 conference in Russia). contains “news” about each new release of
While the world was making good LaTeX2e).
use of “pre-releases” of PDFTeX, Thành Note that, now, LaTeX2e is “feature
used it as a test-bed for the micro- frozen” (the only allowed changes come
typography which was the prime subject from bug reports); this, too, is in pursuit of
of his Ph.D. research. Since Thành was fi- stability, and is a driving force for many of
nally awarded his Ph.D., day-to-day main- the efforts to contribute LaTeX packages.
16
LaTeX guides and news: involve much reinventing of wheels for ev-
macros/latex/doc ery document. Both languages serve as
convenient aids to make document writ-
15 How should I pronounce ing more pleasant: LaTeX provides many
“LaTeX(2e)”? more items to support ‘common’ require-
Lamport never recommended how one ments of documents.
should pronounce LaTeX, but a lot of peo- As such, LaTeX is close to being a su-
ple pronounce it ‘Lay TeX’ or perhaps perset of Plain TeX, but some Plain TeX
‘Lah TeX’ (with TeX pronounced as the commands don’t work as expected when
program itself; see the rules for TeX). It used in a LaTeX document. Using Plain
is definitely not to be pronounced in the TeX commands in a LaTeX document is an
same way as the rubber-tree gum (which occasional source of bugs: the output is al-
would be ‘lay teks’). most right, but some things are misplaced.
The LaTeX2e logo is supposed to end So, Plain TeX and LaTeX are related
with an ε; nevertheless, most people pro- through a common parent, and are de-
nounce the name as ‘LaTeX-two-ee’. signed for use in similar jobs; program-
ming for one will often not work correctly
16 Should I use Plain TeX or LaTeX? in the other.
There’s no straightforward answer to this
question. Many people swear by Plain 18 What is ConTeXt?
TeX, and produce highly respectable docu- ConTeXt is a macro package created by
ments using it (Knuth is an example of this, Hans Hagen of Pragma-Ade; it started as a
of course). But equally, many people are production tool for Pragma (which is a pub-
happy to let someone else take the design lishing company). ConTeXt is a document-
decisions for them, accepting a small loss production system based, like LaTeX, on
of flexibility in exchange for a saving of the TeX typesetting system. Whereas La-
(mental) effort. TeX insulates the writer from typographi-
The arguments around this topic can cal details, ConTeXt takes a complemen-
provoke huge amounts of noise and heat, tary approach by providing structured inter-
without offering much by way of light; faces for handling typography, including
your best bet may be to find out what those extensive support for colors, backgrounds,
around you are using, and to follow them hyperlinks, presentations, figure-text inte-
in the hope of some support. Later on, you gration, and conditional compilation. It
can always switch your allegiance; don’t gives the user extensive control over for-
bother about it. matting while making it easy to create new
If you are preparing a manuscript for layouts and styles without learning the TeX
a publisher or journal, ask them what macro language. ConTeXt’s unified design
markup they want before you develop your avoids the package clashes that can happen
own; many big publishers have developed with LaTeX.
their own (La)TeX styles for journals and ConTeXt also integrates MetaFun, a su-
books, and insist that authors stick closely perset of Metapost and a powerful system
to their markup. for vector graphics. MetaFun can be used
as a stand-alone system to produce figures,
17 How does LaTeX relate to Plain but its strength lies in enhancing ConTeXt
TeX? documents with accurate graphic elements.
TeX provides a programming language (of ConTeXt allows users to specify for-
sorts), and any document more complex matting commands in English, Dutch, Ger-
than the trivial “hello world” will need man, French, or Italian, and to use differ-
some programming. ent typesetting engines (PDFTeX, XeTeX,
LaTeX and Plain TeX are both li- Aleph and LuaTeX) without changing the
braries written for use with TeX; the user user interface. ConTeXt continues to de-
commands tex and latex invoke TeX-the- velop, often in response to requests from
program with a library incorporated. Li- the user community.
braries that may be loaded in this way are The development of LuaTeX was orig-
known as ‘formats’; when a user “runs” inally driven by ConTeXt, almost from the
Plain TeX or LaTeX, they are running TeX start of its project. Nowadays, ConTeXt it
(the program) with an appropriate format. is distributed in two versions — mark two
The documents are then programmed in (files with extension .mkii) which runs
Plain TeX or LaTeX language. on PDFTeX but is not under active devel-
Plain TeX and LaTeX exist because opment, and mark four (files with exten-
writing your documents in ‘raw’ TeX could sion .mkiv) (which runs on LuaTeX and
17
is where development happens). 20 What is Eplain?
ConTeXt has a large developer com- The Eplain macro package expands on and
munity (though possibly not as large as extends the definitions in Plain TeX. Eplain
that of latex), but those developers who is not intended to provide “generic typeset-
are active seem to have prodigious en- ting capabilities”, as do ConTeXt, LaTeX
ergy. Support is available via a WIKI or Texinfo. Instead, it defines macro tools
site and via the mailing list. A “stan- that should be useful whatever commands
dalone” distribution (a TeX distribution you choose to use when you prepare your
with no macros other than ConTeXt-based manuscript.
ones) is available from http://minimals. For example, Eplain does not have a
contextgarden.net/ — it provides a command \section, which would format
ConTeXt system on any of a number of section headings in an “appropriate” way,
platforms, executing either mark ii or as LaTeX’s \section does. The philoso-
mark iv ConTeXt. phy of Eplain is that some people will al-
Note that CTAN does not hold the pri- ways need or want to go beyond the macro
mary distribution of ConTeXt — poten- designer’s idea of “appropriate”. Canned
tial users should refer to ConTeXt ‘garden’ sets of macros are fine — as long as you
site for details of the current distribution. are willing to accept the resulting output.
CTAN holds a copy of ConTeXt but makes If you don’t like the results, or if you are
no claim about its “up-to-date”ness. Like- trying to match a different format, you may
wise, CTAN holds a few contributed Con- find that Eplain is for you.
TeXt packages, but many more are to be On the other hand, almost everyone
found via the ConTeXt garden. would like capabilities such as cross-
ConTeXt distribution: referencing by labels, so that you don’t
macros/context/current have to put actual page numbers in the
manuscript. The authors of Eplain believe
ConTeXt packages selection: it is the only generally available macro
macros/context/contrib package that does not force its typographic
style on an author, and yet provides these
19 What are the AMS packages capabilities.
(AMSTeX, etc.)? Another useful feature of Eplain is
the ability to create PDF files with hyper-
AMSTeX is a TeX macro package, orig- links. The cross-referencing macros can
inally written by Michael Spivak for the implicitly generate hyperlinks for the cross-
American Mathematical Society (AMS) references, but you can also create explicit
during 1983–1985 and is described in the hyperlinks, both internal (pointing to a des-
book “The Joy of TeX”. It is based on Plain tination within the current document) and
TeX, and provides many features for pro- external (pointing to another local docu-
ducing more professional-looking maths ment or a URL).
formulas with less burden on authors. It Several LaTeX packages provide ca-
pays attention to the finer details of sizing pabilities which Plain TeX users are lack-
and positioning that mathematical publish- ing, most notably text colouring and ro-
ers care about. The aspects covered include tation provided by the graphics bundle
multi-line displayed equations, equation (packages color and graphics). Although
numbering, ellipsis dots, matrices, dou- the graphics bundle provides a Plain TeX
ble accents, multi-line subscripts, syntax “loader” for some of the packages, it is not a
checking (faster processing on initial error- trivial job to pass options to those packages
checking TeX runs), and other things. under Plain TeX, and much of the function-
As LaTeX increased in popularity, au- ality of the packages is accessed through
thors sought to submit papers to the AMS package options. Eplain extends the loader
in LaTeX, so AMSLaTeX was developed. so that options can be passed to the pack-
AMSLaTeX is a collection of LaTeX pack- ages just as they are in LaTeX. The fol-
ages and classes that offer authors most of lowing packages are known to work with
the functionality of AMSTeX. The AMS Eplain: graphics, graphicx, color, autopict
no longer recommends the use of AMS- (LaTeX picture environment), psfrag, and
TeX, and urges its authors to use AMSLa- url.
TeX instead. Eplain documentation is available on-
AMSTeX distribution: macros/amstex line (there’s a PDF copy in the CTAN
package as well), and there’s also a mail-
AMSLaTeX distribution: macros/ ing list — sign up, or browse the list
latex/required/amslatex archives, via http://tug.org/mailman/
18
listinfo/tex-eplain books, which still sell well). He is never-
Eplain distribution: macros/eplain theless apparently happy that others should
earn money by selling TeX-based services
21 What is Texinfo? and products. While several valuable TeX-
Texinfo is a documentation system that related tools and packages are offered sub-
uses one source file to produce both on- ject to restrictions imposed by the GNU
line information and printed output. So General Public Licence (GPL, sometimes
instead of writing two different documents, referred to as ‘Copyleft’), which denies the
one for the on-line help and the other for right to commercial exploitation. TeX it-
a typeset manual, you need write only one self is offered under a pretty permissive
document source file. When the work is re- licence of Knuth’s own.
vised, you need only revise one document. There are commercial versions of TeX
By convention, Texinfo source file names available; for some users, it’s reassuring to
end with a .texi or .texinfo extension. have paid support. What is more, some of
Texinfo is a macro language, some- the commercial implementations have fea-
what similar to LaTeX, but with slightly tures that are not available in free versions.
less expressive power. Its appearance is (The reverse is also true: some free im-
of course rather similar to any TeX-based plementations have features not available
macro language, except that its macros commercially.)
start with @ rather than the \ that’s more This FAQ concentrates on ‘free’ distri-
commonly used in TeX systems. butions of TeX, but we do at least list the
You can write and format Texinfo files major vendors.
into Info files within GNU emacs, and read 24 What is the future of TeX?
them using the emacs Info reader. You can
also format Texinfo files into Info files us- Knuth has declared that he will do no
ing makeinfo and read them using info, so further development of TeX; he will con-
you’re not dependent on emacs. The distri- tinue to fix any bugs that are reported to
bution includes a Perl script, texi2html, that him (though bugs are rare). This decision
will convert Texinfo sources into HTML: was made soon after TeX version 3.0 was
the language is a far better fit to HTML released; at each bug-fix release the ver-
than is LaTeX, so that the breast-beating sion number acquires one more digit, so
agonies of converting LaTeX to HTML are that it tends to the limit π (at the time of
largely avoided. writing, Knuth’s latest release is version
3.1415926). Knuth wants TeX to be frozen
Finally, of course, you can also print
at version π when he dies; thereafter, no
the files, or convert them to PDF using
further changes may be made to Knuth’s
PDFTeX.
source. (A similar rule is applied to Meta-
Texinfo distribution: font; its version number tends to the limit e,
macros/texinfo/texinfo and currently stands at 2.718281.)
22 Lollipop Knuth explains his decision, and ex-
horts us all to respect it, in a paper orig-
A long time ago (in the early 1990s), the inally published in TUGboat 11(4), and
Lollipop TeX format was developed (origi- reprinted in the NTG journal MAPS.
nally to typeset the excellent book TeX by
There are projects (some of them long-
topic). Several people admired the format,
term projects: see, for example, the La-
but no “critical mass” of users appeared,
TeX3 project) to build substantial new
that could have prompted maintenance of
macro packages based on TeX. There are
the format.
also various projects to build a successor
More than 20 years later, a new main- to TeX. The e-TeX extension to TeX itself
tainer appeared: he hopes to build Lollipop arose from such a project (NTS). Another
into an engine for rapid document style de- pair of projects, which have delivered all
velopment. (In addition, he intends to add the results they are likely to deliver, is the
support for right-to-left languages such as related Omega and Aleph. The XeTeX sys-
his own — Persian.) tem is in principle still under development,
We can only hope that, this time, Lol- but is widely used, and the LuaTeX project
lipop will “catch on”! (though not scheduled to produce for some
lollipop: macros/lollipop time) has already delivered a system that in-
creasingly accessible to “ordinary users”.
23 If TeX is so good, how come it’s
free? 25 Reading (La)TeX files
It’s free because Knuth chose to make it so So you’ve been sent an (La)TeX file: what
(he makes money from royalties on his TeX are you going to do with it?
19
 You can, of course, “just read it”, since 26 Why is TeX not a WYSIWYG
it’s a plain text file; the problem is that the system?
markup tags in the document may prove W YSIWYG is a marketing term (“What you
distracting. Most of the time, even TeX see is what you get”) for a particular style
experts will typeset a (La)TeX file before of text processor. W YSIWYG systems are
attempting to read it . . . characterised by two principal claims: that
So you shouldn’t be too concerned if you type what you want to print, and that
you can’t make head nor tail of the file: it what you see on the screen as you type is a
is designed to be read by a (sort of) com- close approximation to how your text will
piler, and compilers don’t have much in finally be printed.
common with human readers. The simple answer to the question is,
A possible next step is to try an on-line of course, that TeX was conceived long
LaTeX editor. There are many of these — before the marketing term, at a time when
a compilation of links may be found in this the marketing imperative wasn’t perceived
blog post as significant. (In fact, it appears that the
first experimental WYSIWYG systems were
Of that long list, the present author has running in commercial labs, near where
only dabbled with WriteLaTeX; it seems Knuth was working on TeX. At the time,
well suited to simple ‘one-shot’ use in this of course, TeX was only available on a
way. mainframe, and getting it to run on the
If no online compiler helps, you need small experimental machines would have
to typeset the document “yourself”. The distracted Knuth from his mission to cre-
good news is that TeX systems are avail- ate a typesetting system that he could use
able, free, for most sorts of computer; the when preparing his books for publication.)
bad news is that you need a pretty com- However, all that was a long time ago:
plete TeX system even to read a single file, why has nothing been done with the “won-
and complete TeX systems are pretty large. der text processor” to make it fit with mod-
TeX is a typesetting system that arose ern perceptions?
from a publishing project (see “what is There are two answers to this. First,
TeX”), and its basic source is available free the simple “things have been done” (but
from its author. However, at its root, it is they’ve not taken over the TeX world);
just a typesetting engine: even to view or to and second, “there are philosophical rea-
print the typeset output, you will need an- sons why the way TeX has developed is
cillary programs. In short, you need a TeX ill-suited to the WYSIWYG style”.
distribution — a collection of TeX-related Indeed, there is a fundamental prob-
programs tailored to your operating sys- lem with applying WYSIWYG techniques
tem: for details of the sorts of things that to TeX: the complexity of TeX makes it
are available, see TeX distributions or com- hard to get the equivalent of TeX’s out-
mercial TeX distributions (for commercial put without actually running TeX over the
distributions). whole of the document being prepared.
A celebrated early system offering
But beware — TeX makes no attempt
“WYSIWYG using TeX” came from the Vor-
to look like the sort of WYSIWYG system
TeX project: a pair of Sun workstations
you’re probably used to (see “why is TeX
worked in tandem, one handling the user
not WYSIWYG”): while many modern ver-
interface while the other beavered away in
sions of TeX have a compile–view cycle
the background typesetting the result. Vor-
that rivals the best commercial word pro-
TeX was quite impressive for its time, but
cessors in its responsiveness, what you
the two workstations combined had hugely
type is usually markup, which typically
less power than the average sub-thousand-
defines a logical (rather than a visual) view
dollar Personal Computer nowadays, and
of what you want typeset.
its code has not proved portable (it never
So there’s a balance between the sim- even made the last ‘great’ TeX version
plicity of the original (marked-up) docu- change, at the turn of the 1990s, to TeX
ment, which can more-or-less be read in version 3).
any editor, and the really rather large in- Lightning Textures (an extension of
vestment needed to install a system to read Blue Sky’s original TeX system for the
a document “as intended”. Macintosh), is sadly no longer available.
Are you “put off” by all this? — re- Thus“Scientific Word” (which can also
member that TeX is good at producing interact with a computer algebra system),
PDF: why not ask the person who sent is the only remaining TeX system that even
the TeX file to send an PDF copy? approximates to WYSIWYG operation.
20
 The issue has of recent years started to TUG’s web site lists its
attract attention from TeX developers, and Technical Working Groups (TWGs).
several interesting projects that address the TUG has a reasonable claim
“TeX document preparation environment” to be considered a world-wide or-
are in progress. ganisation, but there are many na-
All the same, it’s clear that the TeX tional and regional user groups, too;
world has taken a long time to latch onto TUG’s web site maintains a list of
the idea of WYSIWYG. Apart from simple hrefhttp://www.tug.org/lugs.html“Local
arrogance (“we’re better, and have no need User Groups” (LUGs).
to consider the petty doings of the com- Contact TUG itself via http://tug.
mercial word processor market”), there is org/contact LastEdit2013-06-25
a real conceptual difference between the
word processor model of the world and
the model LaTeX and ConTeXt employ — B Documentation and
the idea of “markup”. “Pure” markup ex- Help
presses a logical model of a document,
where every object within the document 28 Books relevant to TeX and friends
is labelled according to what it is rather
than how it should appear: appearance is There are too many books for them all to
deduced from the properties of the type of appear in a single list, so the following an-
object. Properly applied, markup can pro- swers aim to cover “related” books, with
vide valuable assistance when it comes to subject matter as follows:
re-use of documents. • TeX itself and Plain TeX
Established WYSIWYG systems find • LaTeX
the expression of this sort of structured • Books on other TeX-related matters
markup difficult; however, markup is start- • Books on Type
ing to appear in the lists of the commer-
cial world’s requirements, for two rea- These lists only cover books in English:
sons. First, an element of markup helps im- notices of new books, or warnings that
pose style on a document, and commercial books are now out of print are always wel-
users are increasingly obsessed with uni- come. However, these FAQs do not carry
formity of style; and second, the increas- reviews of current published material.
ingly pervasive use of XML-derived doc-
29 Books on TeX, Plain TeX and
ument archival formats demands it. The
relations
same challenges must needs be addressed
by TeX-based document preparation sup- While Knuth’s book is the definitive refer-
port schemes, so we are observing a degree ence for both TeX and Plain TeX, there are
of confluence of the needs of the two com- many books covering these topics:
munities: interesting times may be ahead
The TeXbook by Donald Knuth (Addison-
of us.
Wesley, 1984, ISBN-10 0-201-13447-
27 TeX User Groups 0, paperback ISBN-10 0-201-13448-
9)
There has been a TeX User Group since
very near the time TeX first appeared. That A Beginner’s Book of TeX by Raymond
first group, TUG, is still active and its jour- Seroul and Silvio Levy, (Springer Ver-
nal TUGboat continues in regular publica- lag, 1992, ISBN-10 0-387-97562-4)
tion with articles about TeX, Metafont and TeX by Example: A Beginner’s Guide by
related technologies, and about document Arvind Borde (Academic Press, 1992,
design, processing and production. TUG ISBN-10 0-12-117650-9 — now out
holds a yearly conference, whose proceed- of print)
ings are published in TUGboat. Introduction to TeX by Norbert Schwarz
TUG’s web site is a valuable resource (Addison-Wesley, 1989, ISBN-10 0-
for all sorts of TeX-related matters, such 201-51141-X — now out of print)
as details of TeX software, and lists of TeX
vendors and TeX consultants. Back articles A Plain TeX Primer by Malcolm Clark
from TUGboat are also available. (Oxford University Press, 1993, IS-
Some time ago, TUG established a BNs 0-198-53724-7 (hardback) and 0-
“technical council”, whose task was to over- 198-53784-0 (paperback))
see the development of TeXnical projects. A TeX Primer for Scientists by Stanley
Most such projects nowadays go on their Sawyer and Steven Krantz (CRC
way without any support from TUG, but Press, 1994, ISBN-10 0-849-37159-7)
21
TeX by Topic by Victor Eijkhout LaTeX Beginner’s Guide by Stefan Kot-
(Addison-Wesley, 1992, ISBN-10 0- twitz (Packt Publishing, 2011, ISBN-
201-56882-9 — now out of print, but 10 1847199860, ISBN-13 978-
see online books; you can also now 1847199867)
buy a copy printed, on demand, by The LaTeX Companion by Frank Mittel-
Lulu — see http://www.lulu.com/ bach, Michel Goossens, Johannes
content/2555607) Braams, David Carlisle and Chris
TeX for the Beginner by Wynter Snow Rowley (second edition, Addison-
(Addison-Wesley, 1992, ISBN-10 0- Wesley, 2004, ISBN-10 0-201-36299-
201-54799-6) 6, ISBN-13 978-0-201-36299-2);
TeX for the Impatient by Paul W. Abra- the book as also available as a dig-
hams, Karl Berry and Kathryn A. Har- ital download (in EPUB, MOBI
greaves (Addison-Wesley, 1990, and PDF formats) from http://
ISBN-10 0-201-51375-7 — now out www.informit.com/store/latex-
of print, but see online books) companion-9780133387667

TeX in Practice by Stephan von Bechtol- The LaTeX Graphics Companion:

sheim (Springer Verlag, 1993, 4 vol- Illustrating documents with TeX and
umes, ISBN-10 3-540-97296-X for PostScript by Michel Goossens, Se-
the set, or Vol. 1: ISBN-10 0-387- bastian Rahtz, Frank Mittelbach, De-
97595-0, Vol. 2: ISBN-10 0-387- nis Roegel and Herbert Voß (second
97596-9, Vol. 3: ISBN-10 0-387- edition, Addison-Wesley, 2007, ISBN-
97597-7, and Vol. 4: ISBN-10 0-387- 10 0-321-50892-0, ISBN-13 978-0-
97598-5) 321-50892-8)
TeX: Starting from 1 1 by Michael The LaTeX Web Companion: Integrating
Doob (Springer Verlag, 1993, ISBN- TeX, HTML and XML by Michel
10 3-540-56441-1 — now out of print) Goossens and Sebastian Rahtz
(Addison-Wesley, 1999, ISBN-10 0-
The Joy of TeX by Michael D. Spivak (sec- 201-43311-7)
ond edition, AMS, 1990, ISBN-10 0-
821-82997-1) TeX Unbound: LaTeX and TeX strategies
for fonts, graphics, and more by Alan
The Advanced TeXbook by David Sa- Hoenig (Oxford University Press,
lomon (Springer Verlag, 1995, ISBN- 1998, ISBN-10 0-19-509685-1 hard-
10 0-387-94556-3) back, ISBN-10 0-19-509686-X paper-
A collection of Knuth’s publications about back)
typography is also available: More Math into LaTeX: An Introduction
Digital Typography by Donald Knuth to LaTeX and AMSLaTeX by George
(CSLI and Cambridge University Grätzer (fourth edition Springer Ver-
Press, 1999, ISBN-10 1-57586-011-2, lag, 2007, ISBN-10 978-0-387-32289-
paperback ISBN-10 1-57586-010-4). 6
and in late 2000, a “Millennium Boxed Digital Typography Using LaTeX
Set” of all 5 volumes of Knuth’s “Com- Incorporating some multilingual as-
puters and Typesetting” series (about TeX pects, and use of Omega, by Aposto-
and Metafont) was published by Addison los Syropoulos, Antonis Tsolomitis
Wesley: and Nick Sofroniou (Springer, 2003,
ISBN-10 0-387-95217-9).
Computers & Typesetting, Volumes A–E Boxed Set
First Steps in LaTeX by George Grätzer
by Donald Knuth (Addison-Wesley,
(Birkhäuser, 1999, ISBN-10 0-8176-
2001, ISBN-10 0-201-73416-8).
4132-7)
30 Books on LaTeX LaTeX: Line by Line: Tips and Tech-
LaTeX, a Document Preparation System niques for Document Processing by
by Leslie Lamport (second edition, Antoni Diller (second edition, John
Addison Wesley, 1994, ISBN-10 0- Wiley & Sons, 1999, ISBN-10 0-471-
201-52983-1) 97918-X)
Guide to LaTeX Helmut Kopka and LaTeX for Linux: A Vade Mecum by Ber-
Patrick W. Daly (fourth edition, nice Sacks Lipkin (Springer-Verlag,
Addison-Wesley, 2004, ISBN-10 0- 1999, ISBN-10 0-387-98708-8, sec-
321-17385-6) ond printing)

1 That’s ‘Starting from Square One’

22
Typesetting Mathematics with LaTeX by The Elements of Typographic Style by
Herbert Voß (UIT Cambridge, 2010, Robert Bringhurst (Hartley & Marks,
ISBN-10 978-1-906-86017-2) 1992, ISBN-10 0-88179-033-8)
Typesetting Tables with LaTeX by Her- Finer Points in the Spacing & Arrangement of Type
bert Voß, (UIT Cambridge, 2011, by Geoffrey Dowding (Hartley &
ISBN-10 978-1-906-86025-7) Marks, 1996, ISBN-10 0-88179-119-
9)
PSTricks: Graphics and PostScript for TeX and LaTeX
by Herbert Voß, (UIT Cambridge, The Thames & Hudson Manual of Typography
2011, ISBN-10 978-1-906-86013-4) by Ruari McLean (Thames & Hudson,
1980, ISBN-10 0-500-68022-1)
A sample of George Grätzer’s “Math into The Form of the Book by Jan Tschichold
LaTeX”, in Adobe Acrobat format, and (Lund Humphries, 1991, ISBN-10 0-
example files for the three LaTeX Com- 85331-623-6)
panions, and for Grätzer’s “First Steps in
LaTeX”, are all available on CTAN. Type & Layout by Colin Wheildon
(Strathmore Press, 2006, ISBN-10 1-
Examples for First Steps in LaTeX: 875750-22-3)
info/examples/FirstSteps
The Design of Books by Adrian Wilson
Examples for LaTeX Companion: (Chronicle Books, 1993, ISBN-10 0-
info/examples/tlc2
8118-0304-X)
Examples for LaTeX Graphics Companion: Optical Letter Spacing by David Kinders-
info/examples/lgc
ley and Lida Cardozo Kindersley (The
Examples for LaTeX Web Companion: Cardozo Kindersley Workshop 2001,
info/examples/lwc ISBN-10 1-874426-139)
Sample of Math into LaTeX: There are many catalogues of type
info/mil/mil.pdf specimens but the following books provide
31 Books on other TeX-related a more interesting overall view of types in
matters general and some of their history.
There’s a nicely-presented list of of Alphabets Old & New by Lewis F. Day
“recommended books” to be had on (Senate, 1995, ISBN-10 1-85958-160-
the web: http://www.macrotex.net/ 9)
texbooks/
An Introduction to the History of Printing Types
The list of Metafont books is rather by Geoffrey Dowding (British Library,
short: 1998, UK ISBN-10 0-7123-4563-9;
The Metafontbook by Donald Knuth (Ad- USA ISBN-10 1-884718-44-2)
dison Wesley, 1986, ISBN-10 0-201- The Alphabet Abecedarium by Richard
13445-4, ISBN-10 0-201-52983-1 pa- A. Firmage (David R. Godine, 1993,
perback) ISBN-10 0-87923-998-0)

Alan Hoenig’s ‘TeX Unbound ’ includes The Alphabet and Elements of Lettering
some discussion and examples of using by Frederick Goudy (Dover, 1963,
Metafont. ISBN-10 0-486-20792-7)
A book covering a wide range of topics Anatomy of a Typeface by Alexander
(including installation and maintenance) is: Lawson (David R. Godine, 1990,
ISBN-10 0-87923-338-8)
Making TeX Work by Norman Walsh
(O’Reilly and Associates, Inc, 1994, A Tally of Types by Stanley Morison
ISBN-10 1-56592-051-1) (David R. Godine, 1999, ISBN-10 1-
56792-004-7)
The book is decidedly dated, and is now Counterpunch by Fred Smeijers (Hyphen,
out of print, but a copy is available via 1996, ISBN-10 0-907259-06-5)
sourceforge and on CTAN, and we list it
under “online books”. Treasury of Alphabets and Lettering by
Jan Tschichold (W. W. Norton, 1992,
32 Books on Type ISBN-10 0-393-70197-2)
The following is a partial listing of books A Short History of the Printed Word
on typography in general. Of these, by Warren Chappell and Robert
Bringhurst seems to be the one most of- Bringhurst (Hartley & Marks, 1999,
ten recommended. ISBN-10 0-88179-154-7)
23
 The above lists are limited to books French FAQ:
published in English. Typographic styles help/LaTeX-FAQ-francaise
are somewhat language-dependent, and Sources of this FAQ: help/uk-tex-faq
similarly the ‘interesting’ fonts depend on
the particular writing system involved. Obsolete comp.text.tex FAQ:
obsolete/help/TeX,_LaTeX,
33 Where to find FAQs _etc.:_Frequently_Asked_
Questions_with_Answers
Bobby Bodenheimer’s article, from which
this FAQ was developed, used to be posted The visual FAQ:
(nominally monthly) to newsgroup comp. info/visualFAQ/visualFAQ.pdf
text.tex. The (long obsolete) last posted 34 Getting help online
copy of that article is kept on CTAN for
We assume, here, that you have looked
auld lang syne.
at all relevant FAQ answers you can find,
A version of the present FAQ may be
you’ve looked in any books you have, and
browsed via the World-Wide Web, and its
scanned relevant tutorials. . . and still you
sources are available from CTAN.
don’t know what to do.
This FAQ and others are regularly men- There are two more steps you can take
tioned, on comp.text.tex and elsewhere, before formulating a question to the TeX
in a “pointer FAQ” which is also saved at world at large.
http://tug.org/tex-ptr-faq
First, (if you are seeking a particular
A 2006 innovation from Scott Pakin is package or program), start by looking on
the “visual” LaTeX FAQ. This is a docu- your own system: you might already have
ment with (mostly rubbish) text formatted what you seek — the better TeX distribu-
so as to highlight things we discuss here, tions provide a wide range of supporting
and providing Acrobat hyper-links to the material. The CTAN Catalogue can also
relevant answers in this FAQ on the Web. identify packages that might help: you can
The visual FAQ is provided in PDF format, search it, or you can browse it “by topic”.
on CTAN; it works best using Adobe Ac- Each catalogue entry has a brief descrip-
robat Reader 7 (or later); some features are tion of the package, and links to known
missing with other readers, or with earlier documentation on the net. In fact, a large
versions of Acrobat Reader proportion of CTAN package directories
Another excellent information source, now include documentation, so it’s often
available in English, is the (La)TeX navi- worth looking at the catalogue entry for a
gator. package you’re considering using (where
Both the Francophone TeX user group possible, each package link in the main
Gutenberg and the Czech/Slovak user body of these FAQs has a link to the rele-
group CS-TUG have published translations vant catalogue entry).
of this FAQ, with extensions appropriate Failing that, look to see if anyone has
to their languages. solved the problem before; places where
The Open Directory Project (ODP) people ask are:
maintains a list of sources of (La)TeX
help, including FAQs. View the TeX 1. newsgroup comp.text.tex, whose
area at http://dmoz.org/Computers/ “historical posts” are accessible via
Software/Typesetting/TeX/ Google groups, and
Other non-English FAQs are available 2. the mailing list texhax via its archive,
(off-CTAN): or via the ‘Gmane’ newsgroup gmane.
comp.tex.texhax, which holds a
German Posted regularly to de.comp. very long history of the list. A long
tex, and archived on CTAN; the FAQ shot would be to search the archives
also appears at http://www.dante. of the mailing list’s ancient posts on
de/faq/de-tex-faq/ CTAN, which go back to the days
when it was a digest: in those days,
French A FAQ used to be posted regu- a question asked in one issue would
larly to fr.comp.text.tex, and is only ever be answered in the next one.
archived on CTAN — sadly, that effort
seems to have fallen by the wayside. If the “back question” searches fail, you
must ask the world at large.
Czech See http://www.fi.muni.cz/
So, how do you like to ask questions? —
cstug/csfaq/
the three available mechanisms are:
Resources available on CTAN are: 1. Mailing lists: there are various spe-
Dante FAQ: help/de-tex-faq cialist mailing lists, but the place
24
 for ‘general’ (La)TeX queries is the ens.fr: subscribe to it by sending a mes-
texhax mailing list. Mail to texhax@ sage
tug.org to ask a question, but it’s
probably better to subscribe to the subscribe metafont
list (via http://tug.org/mailman/
to [email protected]
listinfo/texhax) first — not every-
one will answer to you as well as to (Note that there’s also a Metapost-
the list. specific mailing list available via the TUG
2. Newsgroup: to ask a question list server; in fact there’s little danger of be-
on comp.text.tex, you can use coming confused by subscribing to both.)
your own news client (if you have Announcements of TeX-related in-
one), or use the “+ new post” stallations on the CTAN archives are
button on http://groups.google. sent to the mailing list ctan-ann. Sub-
com/group/comp.text.tex. scribe to the list via its MailMan web-site
3. Web forum: alternatives are: the “La- https://lists.dante.de/mailman/
TeX community” site, which offers listinfo/ctan-ann; list archives are
a variety of ‘categories’ to place your available at the same address. The list
query, and the TeX, LaTeX and friends archives may also be browsed via http:
Q&A site (“StackExchange”). //www.mail-archive.com/ctan-ann@
StackExchange has a scheme for vot- dante.de/, and an RSS feed is also avail-
ing on the quality of answers (and able: http://www.mail-archive.com/
hence of those who offer support). [email protected]/maillist.xml
This arrangement is supposed to en- 36 How to ask a question
able you to rank any answers that are
posted. You want help from the community at
StackExchange offers hints about large; you’ve decided where you’re go-
“good behaviour”, which any user ing to ask your question, but how do you
should at least scan before asking for phrase it?
help there. (The hints’ principal aim Excellent “general” advice (how to ask
is to maximise the chance that you get questions of anyone) is contained in Eric
useful advice from the first answer; for Raymond’s article on the topic. Eric’s an
example, it suggests that you supply extremely self-confident person, and this
a minimal example of your problem, comes through in his advice; but his guide-
just as these FAQs do. There are peo- lines are very good, even for us in the un-
ple on the site who can be abrasive self-confident majority. It’s important to
to those asking questions, who seem remember that you don’t have a right to
not to be following the guidelines for advice from the world, but that if you ex-
good behaviour) press yourself well, you will usually find
someone who will be pleased to help.
Do not try mailing the LaTeX project team, So how do you express yourself in the
the maintainers of the TeX Live or MiK- (La)TeX world? There aren’t any compre-
TeX distributions or the maintainers of hensive rules, but a few guidelines may
these FAQs for help; while all these ad- help in the application of your own com-
dresses reach experienced (La)TeX users, mon sense.
no small group can possibly have expertise
in every area of usage so that the “big” lists • Make sure you’re asking the right peo-
and forums are a far better bet. ple. Don’t ask in a TeX forum about
printer device drivers for the Foobar
texhax ‘back copies’: digests/texhax
operating system. Yes, TeX users need
printers, but no, TeX users will typ-
35 Specialist mailing lists
ically not be Foobar systems man-
The previous question, “getting help”, agers.
talked of the two major forums in which Similarly, avoid posing a question in
(La)TeX, Metafont and Metapost are dis- a language that the majority of the
cussed; however, these aren’t the only ones group don’t use: post in Ruritanian
available. to de.comp.text.tex and you may
The TUG web site offers many mailing have a long wait before a German- and
lists other than just texhax via its mail list Ruritanian-speaking TeX expert no-
management page. tices your question.
The French national TeX user group, • If your question is (or may be) TeX-
Gutenberg, offers a Metafont (and, de system-specific, report what system
facto, Metapost) mailing list, metafont@ you’re using, or intend to use: “I
25
 can’t install TeX” is as good as use- The “building up” process starts with a
less, whereas “I’m trying to install basic document structure (for LaTeX, this
the mumbleTeX distribution on the would have \documentclass, \begin
Grobble operating system” gives all {document}, \end{document}) and adds
the context a potential respondent things. First to add is a paragraph or so
might need. Another common situ- around the actual point where the problem
ation where this information is impor- occurs. (It may prove difficult to find the
tant is when you’re having trouble in- actual line that’s provoking the problem. If
stalling something new in your system: the original problem is an error, reviewing
“I want to add the glugtheory package “the structure of TeX errors” may help.)
to my mumbleTeX v12.0 distribution Note that there are things that can go
on the Grobble 2024 operating sys- wrong in one part of the document as a
tem”. result of something in another part: the
• If you need to know how to do some- commonest is problems in the table of con-
thing, make clear what your environ- tents (from something in a section title, or
ment is: “I want to do x in Plain TeX”, whatever), or the list of hsomethingi (from
or “I want to do y in LaTeX running something in a \caption). In such a case,
the boggle class”. If you thought you include the section title or caption (the cap-
knew how, but your attempts are fail- tion probably needs the figure or table
ing, tell us what you’ve tried: “I’ve environment around it, but it doesn’t need
already tried installing the elephant the figure or table itself).
in the minicar directory, and it didn’t If this file you’ve built up shows the
work, even after refreshing the file- problem already, then you’re done. Oth-
name database”. erwise, try adding packages; the optimum
• If something’s going wrong within is a file with only one package in it, but
(La)TeX, pretend you’re submitting a you may find that the guilty package won’t
LaTeX bug report, and try to generate even load properly unless another package
a minimum failing example. If your has been loaded. (Another common case
example needs your local xyzthesis is that package A only fails when package
class, or some other resource not gen- B has been loaded.)
erally available, be sure to include a The “hacking down” route starts with
pointer to how the resource can be ob- your entire document, and removes bits
tained. until the file no longer fails (and then of
• Figures are special, of course. Some- course restores the last thing removed).
times the figure itself is really needed, Don’t forget to hack out any unneces-
but most problems may be demon- sary packages, but mostly, the difficulty
strated with a “figure substitute” in the is choosing what to hack out of the body
form of a \rule{width}{height} of the document; this is the mirror of the
command, for some value of hwidthi problem above, in the “building up” route.
and hheighti. If the (real) figure is
If you’ve added a package (or more
needed, don’t try posting it: far better
than one), add \listfiles to the pream-
to put it on the web somewhere.
ble too: that way, LaTeX will produce a
• Be as succinct as possible. Your
list of the packages you’ve used and their
helpers don’t usually need to know
version numbers. This information may be
why you’re doing something, just what
useful evidence for people trying to help
you’re doing and where the problem
you.
is.
The process of ‘building up’, and to
some extent that of ‘hacking down’, can be
37 How to make a “minimum
helped by stuff available on CTAN:
example”
Our advice on asking questions suggests • the minimal class (part of the LaTeX
that you prepare a “minimum example” distribution) does what its name says:
(also commonly known as a “minimal ex- it provides nothing more than what is
ample”) of failing behaviour, as a sample needed to get LaTeX code going, and
to post with your question. If you have a • the mwe bundle provides a number of
problem in a two hundred page document, images in formats that (La)TeX doc-
it may be unclear how to proceed from uments can use, and a small package
this problem to a succinct demonstration mwe which loads other useful pack-
of your problem. ages (such as blindtext and lipsum,
There are two valid approaches to this both capable of producing dummy text
task: building up, and hacking down. in a document).
26
 What if none of of these cut-down Next comes a selection of “specialised”
derivatives of your document will show (La)TeX tutorials, each of which concen-
your error? Whatever you do, don’t post trates on a single LaTeX topic.
the whole of the document: if you can, it A small selection of reference docu-
may be useful to make a copy available on ments (it would be good to have more) are
the web somewhere: people will probably listed in an answer of their own.
understand if it’s impossible . . . or inadvis- Next comes the (somewhat newer)
able, in the case of something confidential. field of TeX-related WIKIs.
If the whole document is indeed nec- A rather short list gives us a Typogra-
essary, it could be that your error is an phy style tutorial.
overflow of some sort; the best you can do
is to post the code “around” the error, and 39 Online introductions: Plain TeX
(of course) the full text of the error. Michael Doob’s splendid ‘Gentle Introduc-
It may seem that all this work is tion’ to Plain TeX (available on CTAN) has
rather excessive for preparing a simple been stable for a very long time.
post. There are two responses to that, both Another recommendable document is
based on the relative inefficiency of asking D. R. Wilkins’ ‘Getting started with TeX’,
a question on the internet. available on the web at http://www.ntg.
First, preparing a minimum document nl/doc/wilkins/pllong.pdf
very often leads you to the answer, with- Gentle Introduction:
out all the fuss of posting and looking for info/gentle/gentle.pdf
responses.
Second, your prime aim is to get an 40 Online introductions: LaTeX
answer as quickly as possible; a well- A pleasing little document, “Getting some-
prepared example stands a good chance thing out of LaTeX” is designed to give
of attracting an answer “in a single pass”: a feel of LaTeX to someone who’s never
if the person replying to your post finds she used it at all. It’s not a tutorial, merely
needs more information, you have to find helps the user to decide whether to go on
that request, post again, and wait for your to a tutorial, and thence to ‘real’ use of
benefactor to produce a second response. LaTeX.
All things considered, a good example Tobias Oetiker’s ‘(Not so) Short Intro-
file can save you a day, for perhaps half an duction to LaTeX2e’, is regularly updated,
hour’s effort invested. as people suggest better ways of explaining
Much of the above advice, differ- things, etc. The introduction is available
ently phrased, may also be read on the on CTAN, together with translations into a
web at http://www.minimalbeispiel. rather large set of languages.
de/mini-en.html; source of that ar- Peter Flynn’s “Beginner’s LaTeX”
ticle may be found at http://www. (which started life as course material) is
minimalbeispiel.de/, in both German a pleasing read. A complete copy may
and English. be found on CTAN, but it may also be
blindtext.sty : macros/latex/ browsed over the web (http://mirrors.
contrib/blindtext ctan.org/info/beginlatex/html/).
Harvey Greenberg’s ‘Simplified Intro-
lipsum.sty : duction to LaTeX’ was written for a lecture
macros/latex/contrib/lipsum course, and is also available on CTAN (in
minimal.cls: Distributed as part of PostScript only, unfortunately).
macros/latex/base The fourth edition of George Grätzer’s
book “Math into LaTeX” contains a “short
mwe.sty : macros/latex/contrib/mwe course” in LaTeX itself, and that course
has been made publicly available on
38 Tutorials, etc., for TeX-based
CTAN.
systems
Philip Hirschhorn’s “Getting up and
From a situation where every (La)TeX user running with AMSLaTeX” has a brief in-
had to buy a book if she was not to find troduction to LaTeX itself, followed by a
herself groping blindly along, we now have substantial introduction to the use of the
what almost amounts to an embarrassment AMS classes and the amsmath package and
of riches of online documentation. The fol- other things that are potentially of inter-
lowing answers attempt to create lists of est to those writing documents containing
sources “by topic”. mathematics.
First we have introductory manuals, for Edith Hodgen’s LaTeX, a Braindump
Plain TeX and LaTeX. starts you from the ground up — giving a
27
basic tutorial in the use of Linux to get you The sins of LaTeX users: Browse
going (rather a large file. . . ). Its parent site, info/l2tabu for a copy of the
David Friggens’ documentation page is a document in a language that is
useful collection of links in itself. convenient for you
Andy Roberts’ introductory material
is a pleasing short introduction to the use 41 (La)TeX tutorials
of (La)TeX; some of the slides for actual The AMS publishes a “Short Math Guide
tutorials are to be found on the page, as for LaTeX”, which is available (in several
well. formats) via http://www.ams.org/tex/
D. R. Wilkins’ ‘Getting started with La- amslatex.html (the “Additional Docu-
TeX’ also looks good (it appears shorter — mentation” about half-way down the page.
more of a primer — than some of the other Herbert Voß has written an extensive
offerings). guide to mathematics in LaTeX, and a de-
Chris Harrison’s LaTeX tutorial velopment of it has been published as a
presents basic LaTeX in a rather pleas- book.
ing and straightforward way. Two documents written more than ten
Nicola Talbot’s LaTeX for complete years apart about font usage in TeX are
novices does what it claims: the author worth reading: Essential NFSS by Sebas-
teaches LaTeX at the University of East tian Rahtz, and Font selection in LaTeX,
Anglia. The “Novices” tutorial is one of cast in the form of an FAQ, by Walter
several introductory tutorials, which in- Schmidt. A general compendium of font
clude exercises (with solutions). Other information (including the two above) may
tutorials include those for writing the- be found on the TUG web site.
ses/dissertations with LaTeX, and for using TUG India is developing a series
LaTeX in administrative work of online LaTeX tutorials which can be
Engelbert Buxbaum provides the strongly recommended: select single chap-
‘slides’ for his LaTeX course ‘The LaTeX ters at a time from http://www.tug.
document preparation system’; this seems org/tutorials/tugindia — there are
to be a departmental course at his univer- 17 chapters in the series, two of which are
sity. mostly introductory.
Mark van Dongen’s ‘LaTeXand Peter Smith’s “LaTeX for Logicians”
friends’ appeared as he was writing his page covers a rather smaller subject area,
book on the subject (soon to be published). but is similarly comprehensive (mostly
An interesting (and practical) tutorial by links to documents on relevant topics,
about what not to do is l2tabu, or “A list rather than as a monolithic document).
of sins of LaTeX2e users” by Mark Tret- Keith Reckdahl’s “Using Imported
tin, translated into English by Jürgen Fenn. Graphics in LaTeX2e” (epslatex) is an ex-
The tutorial is available from CTAN as a cellent introduction to graphics use. It’s
PDF file (though the source is also avail- available on CTAN, but not in the TeX
able). Live or miktex distributions, for lack of
Beginner’s LaTeX: sources.
info/beginlatex/beginlatex- Stefan Kottwitz manages a web site de-
3.6.pdf voted to the use of the drawing packages
Getting something out of LaTeX: PGF and TikZ, http://www.texample.
net/
info/first-latex-doc
Included is examples catalogue in-
Getting up and running with AMSLaTeX: cludes examples (with output) from the
info/amslatex/primer package documentation as well as code
Slides for LaTeX course: written by the original site maintainer
info/latex-course (Kjell Magne Fauske) and others.
Not so Short Introduction: The compendious PGF/TikZ manual
info/lshort/english (in English, is clear, but is bewildering for some be-
you may browse for sources ginners. The ‘minimal’ introduction has
and other language versions at helped at least the present author.
info/lshort) Vincent Zoonekynd provides a set of
excellent (and graphic) tutorials on the pro-
Simplified LaTeX: info/simplified- gramming of title page styles, chapter head-
latex/simplified-intro.pdf
ing styles and section heading styles. In
Short Course in LaTeX: each file, there is a selection of graphics
info/Math_into_LaTeX- representing an output style, and for each
4/Short_Course.pdf style, the code that produces it is shown.
28
 An invaluable step-by-step setup guide or less) everything you ‘ought to’ remem-
for establishing a “work flow” through ber, for basic LaTeX use. (It’s laid out very
your (La)TeX system, so that output ap- compactly for printing on N. American ‘let-
pears at the correct size and position on ter’; printed on ISO A4, using Adobe Acro-
standard-sized paper, and that the print bat’s “shrink to fit”, it strains aged eyes. . . )
quality is satisfactory, is Mike Shell’s For command organised references to
testflow. The tutorial consists of a large LaTeX, Karl Berry (et al)’s LaTeX ref-
plain text document, and there is a support- erence manual is (to an extent) work in
ing LaTeX file together with correct output, progress, but is generally reliable (source
both in PostScript and PDF, for each of A4 is available on the.archive as well).
and “letter” paper sizes. The complete kit Martin Scharrer’s “List of internal La-
is available on CTAN (distributed with the TeX macros” is a help to those aiming to
author’s macros for papers submitted for write a class or package.
IEEE publications). The issues are also The reference provided by the Emer-
covered in a later FAQ answer. son Center of Emory University), LaTeXe
Documentation of Japanese Ω use ap- help also looks good.
pears in Haruhiko Okumura’s page type- Cheat sheet: info/latexcheat/
setting Japanese with Omega (the parent latexcheat/latexsheet.pdf
page is in Japanese, so out of the scope of
this FAQ list). LaTeX reference manual:
info/latex2e-help-texinfo
Some university departments make
their local documentation available on the LaTeX internal macros: info/macros2e
web. Most straightforwardly, there’s the 43 WIKI books for TeX and friends
simple translation of existing documenta-
tion into HTML, for example the INFO The WIKI concept can be a boon to every-
documentation of the (La)TeX installation, one, if used sensibly. The “general” WIKI
of which a sample is the LaTeX documen- allows anyone to add stuff, or to edit stuff
tation available at http://www.tac.dk/ that someone else has added: while there
cgi-bin/info2www?(latex) is obvious potential for chaos, there is ev-
More ambitiously, some university de- idence that a strong user community can
partments have enthusiastic documenters keep a WIKI under control.
who make public record of their (La)TeX Following the encouraging perfor-
support. For example, Tim Love (of mance of the ConTeXt WIKI, valiant ef-
Cambridge University Engineering De- forts have been made generating “WIKI
partment) maintains his department’s books” for (La)TeX users. Thus we have
pages at http://www-h.eng.cam.ac. (Plain) TeX WIKI book and LaTeX WIKI
uk/help/tpl/textprocessing/
book — both well established. Both are
highly rated as reference sources, and even
Graphics in LaTeX2e: info/epslatex as introductory texts.
testflow : macros/latex/contrib/ 44 Typography tutorials
IEEEtran/testflow
Peter Wilson’s article memdesign has
Herbert Voß’s Maths tutorial: a lengthy introductory section on typo-
info/math/voss/mathmode/ graphic considerations, which is a fine tu-
Mathmode.pdf torial, written by someone who is aware
of the issues as they apply to (La)TeX
42 Reference documents
users. (Memdesign now distributed sep-
For TeX primitive commands a rather nice arately from the manual for his memoir
quick reference booklet, by John W. Ship- class, but was originally part of that man-
man, is available; it’s arranged in the same ual)
way as the TeXbook. By contrast, you can There’s also (at least one) typographic
view David Bausum’s list of TeX primi- style tutorial available on the Web, the
tives alphabetically or arranged by “fam- excellent “Guidelines for Typography in
ily”. Either way, the list has a link for NBCS”. In fact, its parent page is also
each control sequence, that leads you to a worth a read: among other things, it pro-
detailed description, which includes page vides copies of the “guidelines” document
references to the TeXbook. in a wide variety of primary fonts, for com-
There doesn’t seem to be a reference parison purposes. The author is careful to
that takes in Plain TeX as well as the prim- explain that he has no ambition to supplant
itive commands. such excellent books as Bringhurst’s, but
An interesting LaTeX “cheat sheet” is the document (though it does contain its
available from CTAN: it’s a list of (more Rutgers-local matter) is a fine introduction
29
to the issues of producing readable docu- which opens a window showing documen-
ments. tation of the footmisc package. (The win-
memdesign: info/memdesign dow is tailored to the file type, in the way
normal for the system.)
45 Freely available (La)TeX books If texdoc can’t find any documentation,
People have long argued for (La)TeX it may launch a Web browser to look at the
books to be made available on the web, package’s entry in the CTAN catalogue.
and until relatively recently this demand The catalogue has an entry for package
went un-answered. documentation, and most authors respond
The first to appear was Victor Ei- to the CTAN team’s request for documenta-
jkhout’s excellent “TeX by Topic” in 2001 tion of packages, you will more often than
(it had been published by Addison-Wesley, not find documentation that way.
but was long out of print). The book is now On MiKTeX systems, the same func-
available on CTAN; it’s not a beginner’s tion is provided by the mthelp.
tutorial but it’s a fine reference. It’s also Note that the site texdoc.net pro-
available, as a printed copy, via the on-line vides access to the documentation you
publishers Lulu (not quite free, of course, would have if you had a full installation of
but not a bad deal. . . ). TeX Live; on the site you can simply ask
Addison-Wesley have also released for a package (as you would ask texdoc, or
the copyright of “TeX for the Impatient” you can use the site’s index of documenta-
by Paul W. Abrahams, Karl Berry and tion to find what you want. (This is helpful
Kathryn A. Hargreaves, another book for some of us: many people don’t have a
whose unavailability many have lamented. full (La)TeX installation on their mobile
The authors have re-released the book un- phone . . . yet.)
der the GNU Free Documentation Licence, If your luck (as defined above) doesn’t
and it is available from CTAN. hold out, you’ve got to find documentation
Norm Walsh’s “Making TeX Work” by other means. That is, you have to find
(originally published by O’Reilly) is the documentation for yourself. The rest
also available (free) on the Web, at of this answer offers a range of possible
http://makingtexwork.sourceforge. techniques.
net/mtw/; the sources of the Web page
The commonest form of documenta-
are on CTAN. The book was an excellent tion of LaTeX add-ons is within the .dtx
resource in its day, but while it is now file in which the code is distributed (see
somewhat dated, it still has its uses, and is documented LaTeX sources). Such files
a welcome addition to the list of on-line re- are supposedly processable by LaTeX it-
sources. A project to update it is believed self, but there are occasional hiccups on
to be under way. the way to readable documentation. Com-
Making TeX Work: mon problems are that the package itself is
info/makingtexwork/mtw-1.0.1- needed to process its own documentation
html.tar.gz (so must be unpacked before processing),
TeX by Topic: info/texbytopic and that the .dtx file will not in fact pro-
cess with LaTeX. In the latter case, the
TeX for the Impatient: info/impatient .ins file will usually produce a .drv (or
46 Documentation of packages similarly-named) file, which you process
These FAQs regularly suggest packages with LaTeX instead. (Sometimes the pack-
that will “solve” particular problems. In age author even thinks to mention this wrin-
some cases, the answer provides a recipe kle in a package README file.)
for the job. In other cases, or when the Another common form is the separate
solution needs elaborating, how is the poor documentation file; particularly if a pack-
user to find out what to do? age is “conceptually large” (and therefore
If you’re lucky, the package you need needs a lot of documentation), the doc-
is already in your installation. If you’re par- umentation would prove a cumbersome
ticularly lucky, you’re using a distribution extension to the .dtx file. Examples
that gives access to package documenta- of such cases are the memoir class, the
tion and the documentation is available in KOMA-script bundle (whose developers
a form that can easily be shown. take the trouble to produce detailed doc-
On TeX Live-based distributions, help umentation in both German and English),
should be available from the texdoc com- the pgf documentation (which would make
mand, as in: a substantial book in its own right) and
the fancyhdr package (whose documenta-
texdoc footmisc tion derives from a definitive tutorial in a
30
mathematical journal). Even if the docu- a good idea to read some established ones
mentation is not separately identified in a (classes.dtx, for example, is the docu-
README file, it should not be too difficult mented source of the standard classes other
to recognise its existence. than Letter, and may itself be formatted
Documentation within the package it- with LaTeX). Classes that are not part of
self is the third common form. Such docu- the distribution are commonly based on
mentation ordinarily appears in comments ones that are, and start by loading the
at the head of the file, though at least one standard class with \LoadClass — an ex-
eminent author regularly places it after ample of this technique may be seen in
the \endinput command in the package. ltxguide.cls
(This is desirable, since \endinput is a An annotated version of article, as it
‘logical’ end-of-file, and (La)TeX doesn’t appears in classes.dtx, was published
read beyond it: thus such documentation in TUGboat 28(1). The article, by Peter
does not ‘cost’ any package loading time.) Flynn, is a good guide to understanding
The above suggestions cover most pos- classes.dtx
sible ways of finding documentation. If, classes.dtx :
despite your best efforts, you can’t find it macros/latex/base/classes.dtx
in any of the above places, there’s the aw-
clsguide.pdf :
ful possibility that the author didn’t bother
macros/latex/doc/clsguide.pdf
to document his package (on the “if it was
hard to write, it should be hard to use” phi- latex-tds rmfamilycollection:
losophy). Most ordinary mortals will seek macros/latex/contrib/latex-
support from some more experienced user tds
at this stage, though it is possible to pro- ltxguide.cls: macros/latex/base/
ceed in the way that the original author ap- ltxguide.cls
parently expected. . . by reading his code.
LaTeX documentation:
47 Learning to write LaTeX classes macros/latex/doc
and packages source2e.tex : macros/latex/base/
There’s nothing particularly magic about source2e.tex
the commands you use when writing a 48 LaTeX3 programming
package, so you can simply bundle up
As yet, there is no book “Programming in
a set of LaTeX \(re)newcommand and
LaTeX3”, and even if such a thing existed
\(re)newenvironment commands, put
there would be lots of gaps. So there is no
them in a file package.sty and you have
comprehensive support.
a package.
However, there are some ‘resources’:
However, any but the most trivial pack-
age will require rather more sophistica- • The “introduction to LaTeX3 ideas” in
tion. Some details of LaTeX commands the expl3 documentation gives a broad-
for the job are to be found in ‘LaTeX2e brush overview of the concepts.
for class and package writers’ (clsguide, • Joseph Wright has written a short se-
part of the LaTeX documentation distri- ries of blog posts, which may help.
bution). Beyond this, a good knowledge • There is also a complete command ref-
of TeX itself is valuable: thus books such erence in the interface3 document.
as the TeXbook or TeX by topic are rele-
vant. With good TeX knowledge it is pos- The documents are still subject to de-
sible to use the documented source of La- velopment; some of the broader design is-
TeX as reference material (dedicated au- sues are discussed on the LaTeX mailing
thors will acquaint themselves with the list latex-l — you may subscribe to that
source as a matter of course). A com- list by sending a message by sending a
plete set of the documented source of La- message
TeX may be prepared by processing the
‘subscribe latex-l <your
file source2e.tex in the LaTeX distribu-
name>’
tion. Such processing is noticeably tedious,
but Heiko Oberdiek has prepared a well- to [email protected]
linked PDF version, which is in the file
expl3.pdf : macros/latex/contrib/
base.tds.zip of his latex-tds distribu-
l3kernel/expl3.pdf
tion. Individual files in the LaTeX distribu-
tion may be processed separately with La- interface3.pdf :
TeX, like any well-constructed .dtx file. macros/latex/contrib/
Writing good classes is not easy; it’s l3kernel/interface3.pdf
31
49 Metafont and Metapost Tutorials Peter Wilson’s “experiences”: info/
metafont/metafp/metafp.pdf
Apart from Knuth’s book, there seems to
be only one publicly-available tutorial for Vincent Zoonekynd’s examples:
Metafont, by Christophe Grandsire (a copy info/metapost/examples
in PDF form may be downloaded). Geof-
50 BibTeX Documentation
frey Tobin’s Metafont for Beginners (see
using Metafont) describes how the Meta- BibTeX, a program originally designed to
font system works and how to avoid some produce bibliographies in conjunction with
of the potential pitfalls. LaTeX, is explained in Section 4.3 and Ap-
Peter Wilson’s experience of running pendix B of Leslie Lamport’s LaTeX man-
both Metafont and Metapost (the pro- ual. The document “BibTeXing”, in the
grams), Some Experiences in Running BibTeX distribution (look for btxdoc), ex-
Metafont and Metapost (available on pands on the chapter in Lamport’s book.
CTAN) offers the benefit of Peter’s experi- The LaTeX Companion also has informa-
ence (he has designed a number of ‘histor- tion on BibTeX and writing BibTeX style
ical’ fonts using Metafont). For Metafont files. (See LaTeX books for details of both
the article is geared towards testing and in- books.)
stalling new Metafont fonts, while its Meta- The web site “Your BibTeX resource”
post section describes how to use Metapost offers a solid introduction, but doesn’t go
illustrations in LaTeX and PDFLaTeX doc- into very great detail.
uments, with an emphasis on how to use The document “Designing BibTeX
appropriate fonts for any text or mathemat- Styles”, also in the BibTeX distribution
ics. (look for btxhak), explains the postfix
Hans Hagen (of ConTeXt fame) offers stack-based language used to write BibTeX
a Metapost tutorial called MetaFun (which styles (.bst files). The filebtxbst.doc,
admittedly concentrates on the use of Meta- also in the BibTeX distribution, is the tem-
post within ConTeXt). It may be found on plate for the four standard styles (plain,
his company’s ‘manuals’ page. abbrv, alpha, and unsrt); it also contains
their documentation.
Another Metapost tutorial in English
A useful tutorial of the whole pro-
is: http://www.tlhiv.org/MetaPost/
cess of using BibTeX is Nicolas Markey’s
tutorial/ by Urs Oswald. One in
“Tame the BeaST (The B to X of BibTeX)”,
French (listed here because it’s clearly
which may also be found on CTAN. A
enough written that even this author un-
summary and FAQ by Michael Shell and
derstands it), http://pauillac.inria.
David Hoadley, is also to be recommended.
fr/~cheno/metapost/metapost.pdf
by Laurent Chéno. BibTeX distribution:
Urs Oswald’s tutorial uses Troy Hen- biblio/bibtex/base
derson’s tool (http://www.tlhiv.org/ Shell and Hoadley’s FAQ: biblio/
mppreview) for testing little bits of Meta- bibtex/contrib/doc/btxFAQ.pdf
post; it is an invaluable aid to the learner:
Tame the BeaST: info/bibtex/
http://www.tlhiv.org/mppreview
tamethebeast/ttb_en.pdf
A three-part introduction, by Mari
Voipio, was published in TUGboat 4(1) 51 Where can I find the symbol
(Entry-level Metapost: On the grid), TUG- for . . .
boat 4(2) (Entry-level Metapost: Move it!),
There is a wide range of symbols avail-
and TUGboat 4(2) (Entry-level Metapost:
able for use with TeX, most of which are
Color).
not shown (or even mentioned) in (La)TeX
Vincent Zoonekynd’s massive set of ex- books. The Comprehensive LaTeX Sym-
ample Metapost files is available on CTAN; bol List (by Scott Pakin et al.) illustrates
the set includes a Perl script to convert the over 2000 symbols, and details the com-
set to html, and the set may be viewed on mands and the LaTeX packages needed to
the web. While these examples don’t ex- produce them.
actly constitute a “tutorial”, they’re most However, while the symbol list is a
certainly valuable learning material. Urs wonderful resource, it is never easy to find
Oswald presents a similar document, writ- a particular symbol there. A graphical sym-
ten more as a document, and presented in bol search is available on the web. The
PDF. site provides you a scratch area on which
Beginners’ guide: you draw the symbol you’re thinking of,
info/metafont/beginners/ with your mouse; when you’ve finished
metafont-for-beginners.pdf drawing, the classifier tries to match your
32
sketch with symbols it knows about. The C Bits and pieces of
matching process is pretty good, even for
the sketches of a really poor draughtsman
(La)TeX
(such as the present author), and it’s of- 53 What is a DVI file?
ten worth trying more than once. ‘Detex-
ify apps’ are available for both Android ‘DVI’ is supposed to be an acronym for
and iPhone devices, you can use them to DeVice-Independent, meaning that the file
draw the symbol with your fingertip — a may be processed for printing or viewing
less challenging procedure than using your on most kinds of typographic output device
workstation’s mouse, by all accounts! or display.
A DVI file (that is, a file with the type
If you are using Unicode maths in Xe- or extension .dvi) is the main output file
TeX or LuaTeX, your own distribution of “original” TeX (later TeX-like systems,
ought to provide the Unicode maths sym- such as PDFTeX may use other formats).
bol table unimath-symbols.pdf; this A DVI file contains all the information
lists the things available in the commonly- that is needed for printing or previewing,
used mathematics fonts. (If the file isn’t except for the actual bitmaps or outlines of
already available on your system, you can fonts, and any material to be introduced by
download it from CTAN, where it live with means of \special commands. Charac-
the unicode-math package. ters in the DVI file (representing glyphs for
Other questions in this FAQ offer spe- printing or display) appear in an encoding
cific help on kinds of symbols: determined in the document.
Any TeX input file should produce the
same DVI file regardless of which imple-
• Script fonts for mathematics mentation of TeX is used to produce it.
• Fonts for the number sets An DVI file may be processed by a
• Typesetting the principal value inte- DVI driver to produce further output de-
gral signed specifically for a particular printer,
or for output in another format (for distri-
Symbol List: Browse bution), or it may be used by a previewer
info/symbols/comprehensive; for display on a computer screen.
there are processed versions PDF Note that XeTeX (released some time
form for both A4 and letter paper. after PDFTeX) uses an “extended DVI for-
mat” (XDV) to send its output to a close-
Unicode maths symbols: coupled DVI driver, xdvipdfmx.
Distributed as part of The canonical reference for the struc-
macros/latex/contrib/unicode-
ture of a DVI file is the source of Knuth’s
math
program dvitype (whose original purpose,
as its name implies, was to view the con-
tent of a DVI file). A partially complete
52 The PiCTeX manual “standard” for the way they should be pro-
cessed may offer further enlightenment.
PiCTeX is a set of macros by Michael
rmfamilyDVI processing standard :
Wichura for drawing diagrams and pic-
dviware/driv-standard
tures. The macros are freely available;
however, the PiCTeX manual itself is not dvitype: systems/knuth/dist/
free. Unfortunately, TUG is no longer able texware/dvitype.web
to supply copies of the manual (as it once
did), and it is now available only through 54 What is a DVI driver?
Personal TeX Inc, the vendors of PCTeX A DVI driver is a program that takes as
(http://www.pctex.com/). The manual input a DVI file and (usually) produces a
is not available electronically. file in a format that something other than a
TeX-related program can process.
However, there is a summary of
A driver may be designed for produc-
PiCTeX commands available on CTAN,
ing output for printing (e.g., PostScript),
which is a great aide-memoire for those
for later processing (e.g., PostScript for
who basically know the package to start
inclusion in a later document), or for docu-
with.
ment exchange (e.g., PDF).
PiCTeX : graphics/pictex As well as the DVI file, the driver typ-
ically also needs font information. Font
PiCTeX summary : information may be held as bitmaps or as
info/pictex/summary outlines, or simply as a set of pointers into
33
the fonts that a printer itself provides. Each typesetting commands, and the positioning
driver will expect the font information in a information that specifies how everything
particular form. comes together.
For more information on the forms of An early instance of something like
font information, see PK files, TFM files, virtual fonts for TeX was implemented
virtual fonts and Using PostScript fonts by David Fuchs to use an unusual printer.
with TeX. However, for practical purposes for the rest
of us, virtual fonts date from when Knuth
55 What are PK files?
specified a format and wrote some support
PK files (packed raster) are the canonical software, in 1989 (he published an article
form of TeX font bitmaps. The output from in TUGboat at the time; a plain text copy
Metafont includes a generic font (GF) file is available on CTAN).
and the utility gftopk produces a PK file Virtual fonts provide a way of telling
from that. TeX about something more complicated
There are potentially a lot of PK files, than just a one-to-one character mapping.
as one is needed for each font: that is for TeX reads a TFM file of the font, just as
each magnification of each design (point) before, but the DVI processor will read the
size for each weight for each font in each VF and use its content to specify how each
family. glyph is to be processed.
Further, since the PK files for one The virtual font may contain com-
printer do not necessarily work well for mands:
another, the whole set needs to be dupli-
cated for each printer type at a site. • to ‘open’ one or more (real) fonts for
While this menagerie of bitmaps can subsequent use,
(in principle) provide fonts that are closely • to remap a glyph from one of the (real)
matched to the capabilities of each printer, fonts for use in the virtual font,
the size of the collection (and the result- • to build up a more complicated effect
ing difficulty of maintaining it) has been a (using DVI commands).
potent driver to the move towards outline
fonts such as Adobe Type 1 fonts. In practice, the most common use
56 What are TFM files? of virtual fonts is to remap Adobe Type
1 fonts (see font metrics), though there
TFM is an acronym for ‘TeX Font Metrics’; has also been useful useful work build-
TFM files hold information about the sizes ing ‘fake’ maths fonts (by bundling glyphs
of the characters of the font in question, from several fonts into a single virtual
and about ligatures and kerns within that font). Virtual Computer Modern fonts,
font. One TFM file is needed for each font making a Cork encoded font from Knuth’s
used by TeX, that is for each design (point) originals by using remapping and frag-
size for each weight for each family; each ments of DVI for single-glyph ‘accented
TFM file serves for all magnifications of characters’, were the first “Type 1 format”
‘its’ font, so that there are (typically) fewer Cork-encoded Computer Modern fonts
TFM files than there are PK files. TeX, available.
LaTeX, etc., themselves need only know
Virtual fonts are normally created in a
about the sizes of characters and their inter-
single ASCII VPL (Virtual Property List)
actions with each other, but not what char-
file, which includes two sets of informa-
acters look like. By contrast, TFM files are
tion. The vptovf utility will use the VPL
not, in principle, needed by the DVI driver,
file to create the binary TFM and VF files.
which only needs to know about the glyphs
A “how-to” document, explaining how
that each character selects, so as to print or
to generate a VPL, describes the endless
display them.
hours of fun that may be had, doing the job
Note that TrueType and OpenType
by hand. Despite the pleasures to be had,
fonts contain the necessary metrics, so that
the commonest way (nowadays) of gen-
XeTeX and LuaTeX, using such fonts, have
erating an VPL file is to use the fontinst
no need of TFM files. A corollary of this
package, which is described in more de-
is that setting up fonts for use by these
tail PostScript font metrics. Qdtexvpl is
engines is far easier.
another utility for creating ad-hoc virtual
57 What are virtual fonts? fonts (it uses TeX to parse a description
Virtual fonts provide a means of collecting of the virtual font, and qdtexvpl itself pro-
bits and pieces together to make the glyphs cesses the resulting DVI file).
of a font: the bits and pieces may be glyphs fontinst:
from “other” fonts, rules and other “basic” fonts/utilities/fontinst
34
Knuth on virtual fonts: or, in LaTeX speak:
info/knuth/virtual-fonts
\newcommand{\foo}[1]{This is a #1 bar}
Virtual fonts “how to”: ...
info/virtualfontshowto/ \foo{3/4}.
virtualfontshowto.txt
which produces:
qdtexvpl:
fonts/utilities/qdtexvpl This is 3/4 bar.

58 What are (TeX) macros (LaTeX users waltz through life, perhaps?)
You will have noticed that the argu-
TeX is a macro processor: this is a
ments, above, were enclosed in braces
computer-science-y term meaning “text ex-
({...}); this is the normal way of typing
pander” (more or less); TeX typesets text
arguments, though TeX is enormously flex-
as it goes along, but expands each macro it
ible, and you may find all sorts of other
finds. TeX’s macros may include instruc-
ways of passing arguments (if you stick
tions to TeX itself, on top of the simple
with it).
text generation one might expect.
Macro writing can get very compli-
Macros are a good thing, since they
cated, very quickly. If you are a begin-
allow the user to manipulate documents ac-
ner (La)TeX programmer, you are well ad-
cording to context. For example, the macro
vised to read something along the lines of
\TeX is usually defined to produce “TEX”
the TeXbook; once you’re under way, TeX
with the ‘E’ lowered (the original idea was
by Topic is possibly a more satisfactory
Knuth’s), but in these FAQs the default def-
choice. Rather a lot of the answers in these
inition of the macro is overridden, and it
FAQs tell you about various issues of how
simply expands to the letters “TeX”. (You
to write macros.
may not think this a good thing, but the
author of the macros has his reasons – see 59 \special commands
TeX-related logos.) TeX provides the means to express things
Macro names are conventionally built that device drivers can do, but about which
from a \ followed by a sequence of letters, TeX itself knows nothing. For example,
which may be upper or lower case (as in TeX itself knows nothing about how to in-
\TeX, mentioned above). They may also clude PostScript figures into documents, or
be \hany single character i, which al- how to set the colour of printed text; but
lows all sorts of oddities (many built in to some device drivers do.
most TeX macro sets, all the way up from Instructions for such things are intro-
the apparently simple ‘\’ meaning “insert duced to your document by means of
a space here”). \special commands; all that TeX does
Macro programming can be a com- with these commands is to expand their ar-
plicated business, but at their very sim- guments and then pass the command to the
plest they need little introduction — you’ll DVI file. In most cases, there are macro
hardly need to be told that: packages provided (often with the driver)
\def\foo{bar}
that provide a human-friendly interface to
the \special; for example, there’s little
replaces each instance of \foo with the point including a figure if you leave no
text “bar”. The command \def is Plain gap for it in your text, and changing colour
TeX syntax for defining commands; LaTeX proves to be a particularly fraught opera-
offers a macro \newcommand that goes tion that requires real wizardry. LaTeX2e
some way towards protecting users from has standard graphics and colour packages
themselves, but basically does the same that make figure inclusion, rotation and
thing: scaling, and colour typesetting relatively
straightforward, despite the rather daunt-
\newcommand{\foo}{bar}
ing \special commands involved. (Con-
Macros may have “arguments” , which are TeXt provides similar support, though not
used to substitute for marked bits of the by way of packages.)
macro expansion: The allowable arguments of \special
depend on the device driver you’re using.
\def\foo#1{This is a #1 bar} Apart from the examples above, there are
... \special commands in the emTeX drivers
\foo{2/4}. (e.g., dvihplj, dviscr, etc.) that will draw
which produces: lines at arbitrary orientations, and com-
mands in dvitoln03 that permit the page
This is a 2/4 bar. to be set in landscape orientation.
35
 Note that \special behaves rather dif- TeX refers to each open file by a num-
ferently in PDFTeX, since there is no de- ber, not by a file name (although most of
vice driver around. There is a concept of the time we hide this). Originally, TeX
PDF specials, but in most cases \special would write to a file connected to a stream
will provoke a warning when used in PDF- numbered 0–15. More recently, a special
TeX. “stream 18” has been implemented: it is
not writing to a file, but rather tells TeX
60 Writing (text) files from TeX to ask the operating system to do some-
TeX allows you to write to output files thing. To run a command, we put it as
from within your document. The facility the argument to \write18. So to run the
is handy in many circumstances, but it is epstopdf utility on a file with name stored
vital for several of the things LaTeX (and as \epsfilename, we would write:
indeed almost any higher-level TeX-based \write18{epstopdf \epsfilename}
macro package) does for you.
The basic uses of writing to an external When using something like the epstopdf
file are “obvious” — remembering titles of package, the ‘stream’ write operation is
sections for a table of contents, remember- hidden away and you don’t need to worry
ing label names and corresponding section about the exact way it’s done.
or figure numbers, all for a later run of your However, there is a security issue. If
document. However, the “non-obvious” you download some (La)TeX code from
thing is easy to forget: that page numbers, the Internet, can you be sure that there is
in TeX, are slippery beasts, and have to be not some command in it (perhaps in a hid-
captured with some care. The trick is that den way) to do stuff that might be harmful
\write operations are only executed as the to your computer (let’s say: delete every-
page is sent to the DVI or PDF file. Thus, if thing on the hard disk!)? In the face of this
you arrange that your page-number macro problem, both MiKTeX and TeX Live have,
(\thepage, in LaTeX) is not expanded un- for some time, disabled \write18 by de-
til the page is written, then the number fault. To turn the facility on, both distribu-
written is correct, since that time is where tions support an additional argument when
TeX guarantees the page number tallies starting TeX from the command shell:
with the page being sent out. (pdf)(la)tex --shell-escape <file>
Now, there are times when you want to The problem with this is that many people
write something straight away: for exam- use (La)TeX via a graphical editor, so to
ple, to interact with the user. TeX captures use \write18 for a file the editor’s settings
that requirement, too, with the primitive must be changed. Of course, the settings
command \immediate: need restoring after the file is processed:
you
\immediate\write\terminal{I’m waiting...}
defeat the point of the original protec-
tion, that way.
writes a “computer-irritates-user” message, The latest MiKTeX (version 2.9), and
to the terminal. recent TeX Live (from the 2010 release)
Which brings us to the reason for that get around this by having a special “lim-
\terminal. TeX can “\write” up to ited” version of \write18 enabled ‘out of
16 streams simultaneously, and that ar- the box’. The idea is to allow only a pre-set
gument to \write says which is to be list of commands (for example, BibTeX,
used. Macro packages provide the means epstopdf , TeX itself, and so on). Those
of allocating streams for your use: Plain on the list are regarded as safe enough to
TeX provides a macro \newwrite (used allow, whereas anything else (for example
as “\newwrite\streamname”, which sets deleting files) still needs to be authorised
\streamname as the stream number). In by the user. This seems to be a good bal-
fact, \terminal (or its equivalent) is the ance: most people most of the time will not
first output stream ever set up (in most need to worry about \write18 at all, but it
macro packages): it is never attached to will be available for things like epstopdf .
a file, and if TeX is asked to write to any Note that the TeX system may tell you
stream that isn’t attached to a file it will that the mechanism is in use:
send the output to the terminal (and the This is pdfTeX, Version 3.1415926-1.40.11 (TeX Live 201
log). restricted \write18 enabled.

61 Spawning programs from when it starts.

(La)TeX: \write18 epstopdf.sty : Distributed with
The TeX \write primitive instruction is Heiko Oberdiek’s packages
used to write to different file ‘streams’; macros/latex/contrib/oberdiek
36
62 How does hyphenation work in 63 What are LaTeX classes and
TeX? packages?
Everyone knows what hyphenation is: we LaTeX aims to be a general-purpose doc-
see it in most books we read, and (if we’re ument processor. Such an aim could be
alert) will spot occasional ridiculous mis- achieved by a selection of instructions
hyphenation (at one time, British newspa- which would enable users to use TeX prim-
pers were a fertile source). itives, but such a procedure is considered
Hyphenation styles are culturally- too inflexible (and probably too daunting
determined, and the same language may for ordinary users). Thus the designers
be hyphenated differently in different coun- of LaTeX created a model which offered
tries — for example, British and American an abstraction of the design of documents.
styles of hyphenation of English are very Obviously, not all documents can look the
different. As a result, a typesetting system same (even with the defocussed eye of ab-
that is not restricted to a single language at straction), so the model uses classes of
a single locale needs to be able to change document. Base LaTeX offers five classes
its hyphenation rules from time to time. of document: book, report, article and
letter. For each class, LaTeX provides a
TeX uses a pretty good system for hy-
class file; the user arranges to use it via a
phenation (originally designed by Frank
\documentclass command at the top of
Liang — you may view his Ph.D. thesis
the document. So a document starting
online) and while it’s capable of missing
“sensible” hyphenation points, it seldom
\documentclass{article}
selects grossly wrong ones. The algo-
rithm matches candidates for hyphenation may be called “an article document”.
against a set of “hyphenation patterns”. This is a good scheme, but it has a glar-
The candidates for hyphenation must be ing flaw: the actual typographical designs
sequences of letters (or other single char- provided by the LaTeX class files aren’t
acters that TeX may be persuaded to think widely liked. The way around this is to
of as letters). Non-letters interrupt hyphen- refine the class. To refine a class, a pro-
ation; this applies to TeX’s \accent prim- grammer may write a new class file that
itive (as in ‘système’) just as much as the loads an existing class, and then does its
exclamation in‘syst!eme’. own thing with the document design.
(Hyphenation takes place on the char- If the user finds such a refined class, all
acters “sent to the printer”. The problem is well, but if not, the common way is to
with \accent is avoided —in LaTeX — load a package (or several).
by the use of the fontenc package, as dis- The LaTeX distribution, itself, pro-
cussed in “Accented words aren t hyphen- vides rather few package files, but there
ated”.) are lots of them, by a wide variety of au-
Sets of hyphenation patterns are usu- thors, to be found on the archives. Several
ally derived from analysis of a list of valid packages are designed just to adjust the de-
hyphenations (the process of derivation, us- sign of a document — using such packages
ing a tool called patgen, is not ordinarily a achieves what the programmer might have
sport to be played by ordinary mortals). achieved by refining the class.
The patterns for the languages a TeX Other packages provide new facilities:
system is going to deal with may only for example, the graphics package (actu-
be loaded when the system is installed. ally provided as part of any LaTeX distri-
To change the set of hyphenation patterns bution) allows the user to load externally-
recognised by a TeX-based or XeTeX sys- provided graphics into a document, and the
tem, a partial reinstallation is necessary hyperref package enables the user to con-
(note that LuaTeX relaxes this constraint). struct hyper-references within a document.
TeX provides two “user-level” com- On disc, class and package files only
mands for control of hyphenation: appear different by virtue of their name
\language (which selects a hyphenation “extension” — class files are called *.cls
style), and \hyphenation (which gives while package files are called *.sty. Thus
explicit instructions to the hyphenation en- we find that the LaTeX standard article
gine, overriding the effect of the patterns). class is represented on disc by a file called
The ordinary LaTeX user need not article.cls, while the hyperref pack-
worry about \language, since it is very age is represented on disc by a file called
thoroughly managed by the babel package; hyperref.sty.
use of \hyphenation is discussed in the The class vs. package distinction was
context of hyphenation failure. not clear in LaTeX 2.09 — everything was
37
called a style (“document style” or “docu- \begin{fontblock}{\ttfamily}
ment style option”). It doesn’t really matter
that the nomenclature has changed: the im- would produce the same effect as the
portant requirement is to understand what monoblock environment.
other people are talking about. Environments may also have optional
arguments, in much the same way as com-
64 What are LaTeX “environments”
mands:
While TeX makes direct provision for com-
mands, LaTeX adds a concept of “environ- \newenvironment{normaltext}[1][\itshape]%
ment”; environments perform an action on {#1}%
a block (of something or other) rather than {}
than just doing something at one place in
your document. which will ordinarily set its body in italic,
A totally trivial environment could but
change the font in use for a chunk of text,
\begin{normaltext}[\ttfamily]
as
...
\newenvironment{monoblock}% \end{normaltext}
{\ttfamily}%
{} will observe its optional argument, and be-
have the same as the monoblock we started
which defines a monoblock which may be with.
used as Note that an environments argument(s)
\begin{monoblock} (mandatory or optional) are not passed to
some text set in monospace the ‘ \end ’ text of the environment — that
\end{monoblock} is specified as a macro with no arguments,
so that
which will look like:
\newenvironment{normaltext}[1][\itshape]%
some text set in monospace
{#1}%
so it is a particularly simple example. A {\typeout{what was #1, again?}
rather complicated environment is intro-
duced by \begin{document}; it looks produces an error message
simple, but needs all sorts of special
! Illegal parameter number in definition of \endnormalt
TeX code to make it work ‘transparently’;
most environments are more elaborate So, if you need to pass an environment ar-
than monoblock and much simpler than gument to the end-code, you have to wrap
document. it in a macro of its own:
An environment puts its content inside
a TeX group, so that commands used inside \newenvironment{normaltext}[1][Intro]%
the environment don’t ‘leak out’ — the {#1%
monoblock environment, above, restricts \newcommand{\foo}{#1}}%
its effect to its own contents (the stuff be- {\typeout{what was \foo{}, again?}
tween the \begin{monoblock} and \end
{monoblock}), which is just what you 65 Documented LaTeX sources (.dtx
need for this sort of thing. files)
So that’s “simple” environments; the LaTeX2e, and many contributed LaTeX
monoblock, above doesn’t actually gain us macro packages, are written in a literate
much over programming style, with source and docu-
{\ttfamily some text set in monospace} mentation in the same file. This format in
fact originated before the days of the La-
though in fact many useful environments TeX project as one of the “Mainz” series of
are just as simple (to look at). Some, such packages. A documented source file con-
as verbatim, look simple but are actually ventionally has the suffix .dtx, and will
very tricky inside. normally be ‘stripped’ before use with La-
LaTeX also allows arguments to an en- TeX; an installation (.ins) file is normally
vironment: provided, to automate this process of re-
moving comments for speed of loading. If
\newenvironment{fontblock}[1]%
the .ins file is available, you may process
{#1\selectfont}%
it with LaTeX to produce the package (and,
{}
often, auxiliary files).
and use of fontblock as: Output should look something like:
38
 Generating file(s) ./foo.sty so you may want to keep .dtx files else-
where.
Processing file foo.dtx (package) -> An foo.sty
interesting sideline to the story of
File foo.dtx ended by \endinput..dtx files is the docmfp package, which
Lines processed: 2336 extends the model of the doc package to
Comments removed: 1336 Metafont and Metapost, thus permitting
Comments passed: 2 documented distribution of bundles con-
Codelines passed: 972 taining code for Metafont and Metapost
together with related LaTeX code.
The lines “Processing ... ended by
AUC-TeX : support/auctex
\endinput” may be repeated if the .dtx
file provides more than one ‘unpacked’ clsguide.pdf :
file. macros/latex/doc/clsguide.pdf
To read the comments “as a document”, docmfp.sty :
you can run LaTeX on the .dtx file to pro- macros/latex/contrib/docmfp
duce a nicely formatted version of the doc- docstrip.tex : Part of the LaTeX
umented code. (Most LaTeX packages on distribution
CTAN, nowadays, already have PDF of
the result of processing the .dtx file, as DTX tutorial: info/dtxtut
“documentation”.) dtxgen: support/dtxgen
Several packages may be included in makedtx : support/makedtx
one .dtx file, with conditional sections,
and there are facilities for indexes of sty2dtx : support/sty2dtx
macros, etc. All of this mélange is sorted 66 What are encodings?
out by directives in the .ins file; conven-
Let’s start by defining two concepts, the
tional indexing utilities may be necessary
character and the glyph. The character
for “full” output.
is the abstract idea of the ‘atom’ of a lan-
Anyone may write .dtx files; the for- guage or other dialogue: so it might be a
mat is explained in The LaTeX Compan- letter in an alphabetic language, a sylla-
ion, and a tutorial is available from CTAN ble in a syllabic language, or an ideogram
(which comes with skeleton .dtx and in an ideographic language. The glyph is
.ins files).
the mark created on screen or paper which
Composition of .dtx files is supported represents a character. Of course, if read-
in emacs by AUC-TeX. ing is to be possible, there must be some
The (unix-based) script dtxgen gener- agreed relationship between the glyph and
ates a proforma basic .dtx file, which the character, so while the precise shape of
could be useful when starting a new the glyph can be affected by many other
project. factors, such as the capabilities of the writ-
Another route to an .dtx file is to ing medium and the designer’s style, the
write the documentation and the code sepa- essence of the underlying character must
rately, and then to combine them using the be retained.
makedtx system. This technique has par- Whenever a computer has to represent
ticular value in that the documentation file characters, someone has to define the re-
can be used separately to generate HTML lationship between a set of numbers and
output; it is often quite difficult to make La- the characters they represent. This is the
TeX to HTML conversion tools deal with essence of an encoding: it is a mapping be-
.dtx files, since they use an unusual class tween a set of numbers and a set of things
file. to be represented.
The sty2dtx system goes one step fur- TeX of course deals in encoded charac-
ther: it attempts to create a .dtx file from ters all the time: the characters presented
a ‘normal’ .sty file with comments. It to it in its input are encoded, and it emits
works well, in some circumstances, but encoded characters in its DVI or PDF out-
can become confused by comments that put. These encodings have rather different
aspire to “structure” (e.g., tabular material, properties.
as in many older packages’ file headers). The TeX input stream was pretty un-
The .dtx files are not used by LaTeX ruly back in the days when Knuth first im-
after they have been processed to produce plemented the language. Knuth himself
.sty or .cls (or whatever) files. They prepared documents on terminals that pro-
need not be kept with the working system; duced all sorts of odd characters, and as
however, for many packages the .dtx file a result TeX contains some provision for
is the primary source of documentation, translating its input (however encoded) to
39
something regular. Nowadays, the oper- 67 What are the EC fonts?
ating system translates keystrokes into a A font provides a number of glyphs. In
code appropriate for the user’s language: order that the glyphs may be printed, they
the encoding used is usually a national or are encoded, and the encoding is used as
international standard, though some oper- an index into tables within the font. For
ating systems use “code pages” (as defined various reasons, Knuth chose deeply eccen-
by Microsoft). These standards and code tric encodings for his Computer Modern
pages often contain characters that may not family of fonts; in particular, he chose dif-
appear in the TeX system’s input stream. ferent encodings for different fonts, so that
Somehow, these characters have to be dealt the application using the fonts has to re-
with — so an input character like “é” needs member which font of the family it’s using
to be interpreted by TeX in a way that that before selecting a particular glyph.
at least mimics the way it interprets “\’e”.
When TeX version 3 arrived, most of
The TeX output stream is in a some- the drivers for the eccentricity of Knuth’s
what different situation: characters in it encodings went away, and at TUG’s Cork
are to be used to select glyphs from the meeting, an encoding for a set of 256
fonts to be used. Thus the encoding of glyphs, for use in TeX text, was defined.
the output stream is notionally a font en- The intention was that these glyphs should
coding (though the font in question may cover ‘most’ European languages that use
be a virtual one — see virtual font). In Latin alphabets, in the sense of including
principle, a fair bit of what appears in the all accented letters needed. (Knuth’s CMR
output stream could be direct transcription fonts missed things necessary for Icelandic
of what arrived in the input, but the output and Polish, for example, which the Cork
stream also contains the product of com- fonts do have, though even Cork encod-
mands in the input, and translations of the ing’s coverage isn’t complete.) LaTeX
input such as ligatures like fi⇒“fi”. refers to the Cork encoding as T1, and pro-
vides the means to use fonts thus encoded
Font encodings became a hot topic to avoid problems with the interaction of
when the Cork encoding appeared, because accents and hyphenation (see hyphenation
of the possibility of suppressing \accent of accented words).
commands in the output stream (and hence
The first Metafont-fonts to conform
improving the quality of the hyphenation
to the Cork encoding were the EC fonts.
of text in inflected languages, which is
They look CM-like, though their metrics
interrupted by the \accent commands —
differ from CM-font metrics in several ar-
see “how does hyphenation work”). To
eas. They have long been regarded as ‘sta-
take advantage of the diacriticised charac-
ble’ (in the same sense that the CM fonts
ters represented in the fonts, it is necessary
are stable: their metrics are unlikely ever
to arrange that whenever the command se-
to change). Each EC font is, of course,
quence “\’e” has been input (explicitly, or
roughly twice the size of the correspond-
implicitly via the sort of mapping of input
ing CM font, and there are far more of
mentioned above), the character that codes
them than there are CM fonts. The sim-
the position of the “é” glyph is used.
ple number of fonts proved problematic in
Thus we could have the odd arrange- the production of Type 1 versions of the
ment that the diacriticised character in the fonts, but EC or EC-equivalent fonts in
TeX input stream is translated into TeX Type 1 or TrueType form (the latter only
commands that would generate something from commercial suppliers). Free auto-
looking like the input character; this se- traced versions — the CM-super and the
quence of TeX commands is then trans- LGC fonts, and the Latin Modern series
lated back again into a single diacriticised (rather directly generated from Metafont
glyph as the output is created. This is in sources), are available.
fact precisely what the LaTeX packages Note that the Cork encoding doesn’t
inputenc and fontenc do, if operated in tan- cover mathematics (so that no “T1-
dem on (most) characters in the ISO Latin- encoded” font families can not support
1 input encoding and the T1 font encoding. it). If you’re using Computer-Modern-
At first sight, it seems eccentric to have the alike fonts, this doesn’t actually matter:
first package do a thing, and the second pre- your system will have the original Com-
cisely undo it, but it doesn’t always happen puter Modern mathematical fonts (or the
that way: most font encodings can’t match those distributed with the Latin Modern
the corresponding input encoding nearly set), which cover ‘basic’ TeX mathemat-
so well, and the two packages provide the ics; more advanced mathematics are likely
sort of symmetry the LaTeX system needs. to need separate fonts anyway. Suitable
40
mathematics fonts for use with other font represented using “LaTeX standard encod-
families are discussed in “choice of scal- ings”. The separate package ucs provides
able fonts”. wider, but less robust, coverage via an
The EC fonts are distributed with a set inputenc option utf8x. As a general rule,
of ‘Text Companion’ (TC) fonts that pro- you should never use utf8x until you have
vide glyphs for symbols commonly used convinced yourself that utf8 can not do
in text. The TC fonts are encoded accord- the job for you.
ing to the LaTeX TS1 encoding, and are ‘Modern’ TeX-alike applications, Xe-
not necessarily as ‘stable’ are the EC fonts TeX and LuaTeX read their input using
are. Note that modern distributions tend UTF-8 representations of Unicode as stan-
not to distribute the EC fonts in outline for- dard. They also use TrueType or OpenType
mat, but rather to provide Latin Modern for fonts for output; each such font has tables
T1-encoded Computer Modern-style fonts. that tell the application which part(s) of
This can sometimes cause confusion when the Unicode space it covers; the tables en-
users are recompiling old documents. able the engines to decide which font to
The Cork encoding is also imple- use for which character (assuming there is
mented by virtual fonts provided in the any choice at all).
PSNFSS system, for Adobe Type 1 fonts, inputenc.sty : Part of the
and also by most other such fonts that have macros/latex/base distribution
been developed (or otherwise made avail-
ucs.sty : macros/latex/contrib/ucs
able) for use with (La)TeX.
Note that T1 (and other eight-bit font 69 What is the TDS?
encodings) are superseded in the develop- TDS is an acronym for “TeX Directory
ing TeX-family members XeTeX and Lua- Structure”; it specifies a standard way of
TeX, which use Unicode as their base en- organising all the TeX-related files on a
coding, and use Unicode-encoded fonts computer system.
(typically in ttf or otf formats). The Most modern distributions arrange
cm-unicode fonts carry the flag in this their TeX files in conformance with the
arena, along with the Latin Modern set. TDS, using both a ‘distribution’ directory
CM-super fonts: tree and a (set of) ‘local’ directory trees,
fonts/ps-type1/cm-super each containing TeX-related files. The
TDS recommends the name texmf for the
CM-LGC fonts:
name of the root directory (folder) of an hi-
fonts/ps-type1/cm-lgc
erarchy; in practice there are typically sev-
CM unicode fonts: eral such trees, each of which has a name
fonts/cm-unicode that compounds that (e.g., texmf-dist,
texmf-var).
EC and TC fonts: fonts/ec
Files supplied as part of the distribu-
Latin Modern fonts: fonts/lm tion are put into the distribution’s tree, but
the location of the distribution’s hierar-
68 Unicode and TeX chy is system dependent. (On a Unix sys-
Unicode is a character code scheme that tem it might be at /usr/share/texmf or
has the capacity to express the text of the /opt/texmf, or a similar location.)
languages of the world, as well as im- There may be more than one ‘local’ hi-
portant symbols (including mathematics). erarchy in which additional files can be
Any coding scheme that is directly appli- stored. An installation will also typically
cable to TeX may be expressed in single offer a local hierarchy, while each user may
bytes (expressing up to 256 characters); have an individual local hierarchy.
Unicode characters may require several The TDS itself is published as the out-
bytes, and the scheme may express a very put of a TUG Technical Working Group.
large number of characters. You may browse an on-line version of the
For “old-style” applications (TeX or standard, and copies in several other for-
PDFTeX) to deal with Unicode input, the mats (including source) are available on
sequence of bytes to make up Unicode CTAN.
character are processed by a set of macros TDS specification: tds
that deliver a glyph number in an appropri-
ate font. The macros that read these bytes 70 What is “Encapsulated
is complicated, and manifests as utf8 op- PostScript” (“EPS”)?
tion for the LaTeX distribution inputenc PostScript has been for many years a lin-
package; the coverage of that option is gua franca of powerful printers (though
limited to Unicode characters that can be modern high-quality printers now tend to
41
require some constrained form of Adobe ensure that the font is rendered as quickly
Acrobat, instead); since PostScript is also a as possible. (Or rather, as quickly as pos-
powerful graphical programming language, sible with Adobe’s technology at the time
it is commonly used as an output medium the specification was written: the structure
for drawing (and other) packages. could well be different if it were specified
However, since PostScript is such a now.) The format has long been the ba-
powerful language, some rules need to be sis of the digital type-foundry business,
imposed, so that the output drawing may though nowadays most new fonts are re-
be included in a document as a figure with- leased in OpenType format.
out “leaking” (and thereby destroying the In the (La)TeX context, Type 1 fonts
surrounding document, or failing to draw are extremely important. Apart from their
at all). simple availability (there are thousands of
Appendix H of the PostScript Lan- commercial Type 1 text fonts around), the
guage Reference Manual (second and sub- commonest reader for PDF files has long
sequent editions), specifies a set of rules (in effect) insisted on their use (see below).
for PostScript to be used as figures in this Type 3 fonts have a more forgiving
way. The important features are: specification. A wide range of PostScript
operators is permissible, including bitmap
• certain “structured comments” are re- specifiers. Type 3 is therefore the nat-
quired; important ones are the identifi- ural format to be used for programs
cation of the file type, and information such as dvips when they auto-generate
about the “bounding box” of the figure something to represent Metafont-generated
(i.e., the minimum rectangle enclosing fonts in a PostScript file. It’s Adobe
it); Acrobat Viewer’s treatment of bitmap
• some commands are forbidden — for Type 3 fonts that has made direct Meta-
example, a showpage command will font output increasingly unattractive, in
cause the image to disappear, in most recent years. If you have a PDF docu-
TeX-output environments; and ment in which the text looks fuzzy and
• “preview information” is permitted, uneven in Acrobat Reader, ask Reader
for the benefit of things such as word for the File→Document Properties→
processors that don’t have the abil- Fonts ..., and it will likely show some
ity to draw PostScript in their own font or other as “Type 3” (usually with
right — this preview information may encoding “Custom”). The problem has dis-
be in any one of a number of system- appeared with version 6 of Acrobat Reader.
specific formats, and any viewing pro- See PDF quality for a discussion of the
gram may choose to ignore it. issue, and for ways of addressing it.
A PostScript figure that conforms to Type 3 fonts should not entirely be dis-
these rules is said to be in “Encapsulated missed, however. Acrobat Reader’s failure
PostScript” (EPS) format. Most (La)TeX with them is entirely derived from its fail-
packages for including PostScript are ure to use the anti-aliasing techniques com-
structured to use Encapsulated PostScript; mon in TeX-ware. Choose a different set
which of course leads to much hilarity as of PostScript graphical operators, and you
exasperated (La)TeX users struggle to cope can make pleasing Type 3 fonts that don’t
with the output of drawing software whose “annoy” Reader. For example, you may not
authors don’t know the rules. change colour within a Type 1 font glyph,
but there’s no such restriction on a Type 3
71 Adobe font formats font, which opens opportunities for some
Adobe has specified a number of formats startling effects.
for files to represent fonts in PostScript
files; this question doesn’t attempt to be 72 What are “resolutions”?
encyclopaedic, so we only discuss the two “Resolution” is a word that is used with
formats most commonly encountered in little concern for its multiple meanings,
the (La)TeX context, types 1 and 3. In in computer equipment marketing. The
particular, we don’t discuss the OpenType word suggests a measure of what an ob-
format, whose many advantages now be- server (perhaps the human eye) can re-
coming accessible to most (La)TeX users solve; yet we regularly see advertisements
(by means of the widely-used XeTeX and for printers whose resolution is 1200dpi —
the more experimental LuaTeX). far finer than the unaided human eye can
Adobe Type 1 format specifies a means distinguish. The advertisements are talk-
to represent outlines of the glyphs in a font. ing about the precision with which the
The ‘language’ used is closely restricted, to printer can place spots on the printed im-
42
age, which affects the fineness of the repre- system allows rather more freedom to spec-
sentation of fonts, and the accuracy of the ify file names. Sadly, the ISO 9660 stan-
placement of glyphs and other marks on dard for the structure of CD-ROMs has a
the page. similar failing, but that too has been modi-
In fact, there are two sorts of “resolu- fied by various extension mechanisms.)
tion” on the printed page that we need to One area in which these short file
consider for (La)TeX’s purposes: names posed a particular problem was that
of file names for Type 1 fonts. These fonts
• the positioning accuracy, and are distributed by their vendors with pretty
• the quality of the fonts. meaningless short names, and there’s a
natural ambition to change the name to
In the case where (La)TeX output is be- something that identifies the font some-
ing sent direct to a printer, in the printer’s what precisely. Unfortunately, names such
“native” language, it’s plain that the DVI as “BaskervilleMT” are already far beyond
processor must know all such details, and the abilities of the typical feeble file sys-
must take detailed account of both types of tem, and add the specifier of a font shape
resolution. or variant, and the difficulties spiral out
In the case where output is being sent of control. Font companies deal with the
to an intermediate distribution format, that issue by inventing silly names, and pro-
has potential for printing (or displaying) viding a map file to show what the “real”
we know not where, the final translator, names. Thus the Monotype Corporation
that connects to directly to the printer or provides the translations:
display, has the knowledge of the device’s
properties: the DVI processor need not bas_____ BaskervilleMT
know, and should not presume to guess. basb____ BaskervilleMT-Bold
basbi___ BaskervilleMT-BoldItalic
Both PostScript and PDF output are
in this category. While PostScript is used and so on. These names could be used
less frequently for document distribution within (La)TeX programs, except that
nowadays, it is regularly used as the source they are not unique: there’s nothing to
for distillation into PDF; and PDF is the stop Adobe using ‘bas_____’ for their
workhorse of an enormous explosion of Baskerville font.
document distribution. Thus arose the Berry naming scheme.
Therefore, we need DVI processors The basis of the scheme is to encode
that will produce “resolution independent” the meanings of the various parts of the
PostScript or PDF output; of course, the in- file’s specification in an extremely terse
dependence needs to extend to both forms way, so that enough font names can be ex-
of independence outlined above. pressed even in impoverished file name-
Resolution-independence of fonts was spaces. The encoding allocates one char-
for a long time forced upon the world by acter to the font “foundry” (Adobe, Mono-
the feebleness of Adobe’s Acrobat Reader type, and so on), two to the typeface name
at dealing with bitmap files: a sequence (Baskerville, Times Roman, and so on),
of answers starting with one aiming at the one to the weight, shape, and encoding and
quality of PDF from PostScript addresses so on.
the problems that arise. The whole scheme is outlined in the
Resolution-independence of position- fontname distribution, which includes ex-
ing is more troublesome: dvips is some- tensive documentation and a set of tables
what notorious for insisting on positioning of fonts whose names have been systema-
to the accuracy of the declared resolution tised.
of the printer. One commonly-used ap- fontname distribution:
proach is to declare a resolution of 8000 info/fontname
(“better than any device”), and this is rea-
sonably successful though it does have its
problems. D Acquiring the Software
73 What is the “Berry naming 74 Repositories of TeX material
scheme”?
To aid the archiving and retrieval of of TeX-
In the olden days, (La)TeX distributions related files, a TUG working group devel-
were limited by the feebleness of file sys- oped the Comprehensive TeX Archive Net-
tems’ ability to represent long names. (The work (CTAN). Each CTAN site has iden-
MS-DOS file system was a particular bug- tical material, and maintains authoritative
bear: fortunately any current Microsoft versions of its material. These collections
43
are extensive; in particular, almost every- With the advent of the TeX distribu-
thing mentioned in this FAQ is archived at tions, however, people started to realise the
the CTAN sites (see the lists of software at need for such information, to protect those
the end of each answer). who create, distribute or sell the discs that
There are two main CTAN sites (in hold the packages, etc. With the licence
Germany and the UK), but users should information available, the distributors can
ordinarily collect material via the CTAN decide which packages may be distributed.
mirror redirector (which connects you to a The CTAN team decided that it would
mirror that is in some sense “near” to you). be useful for users (and distributors, not to
To access a particular thing through the say package authors) to separate packages
mirror.ctan.org mechanism, simply that were candidates for distribution, and
place the CTAN path after the base URL; those that were in some sense “not free”.
so http://mirror.ctan.org/macros/ Thus was the nonfree tree born.
latex/contrib/footmisc/ will connect From the start, the nonfree tree was
you to the footmisc directory at some controversial: the terms under which a
CTAN mirror. package would be placed on the tree were
For details of how to find files at CTAN hotly contested, and the CTAN team were
sites, see “finding (La)TeX files”. only able slowly to populate the tree. It be-
The TeX user who has no access to came obvious to the team that the project
any sort of network may buy a copy of the would never have been completed.
archive as part of the TeX Live distribution; The CTAN catalogue now records the
nature of the licences of a good proportion
the disc is, necessarily, out of date, but it is
likely to be better than what (if anything) of the packages it describes (though there
came with your operating system. remain several for which the licence is un-
known, which is as good, for the distribu-
75 Ready-built installation files on tors, as a licence forbidding distribution).
the archive Since the catalogue’s coverage of CTAN is
The TDS is a simple structure, and almost good (and slowly improving), the general
all files can be installed simply by putting rule for distributors has become
them in the “right” place, and updating a “if the package is listed in the
single index. (Note, this simple idea typi- catalogue, check there to see
cally doesn’t work for fonts, unless they’re whether you should distribute; if
distributed as Metafont source.) the package is not listed in the cat-
The CTAN network is therefore acquir- alogue, don’t think of distributing
ing “TDS-ZIP” files, which have a built-in it”.
directory structure that matches the TDS.
(The catalogue only has a modest list
These files have to be built, and the CTAN
of licences, but it covers the set used
team has asked that package authors sup-
by packages on CTAN, with a wild-card
ply them (the team will advise, of course,
“other-free” which covers packages that
if the author has trouble). The CTAN team
the CTAN administrators believe to be free
hopes that the extra work involved will con-
even though the authors haven’t used a
tribute to happier lives for package users,
standard licence.)
which in turn must surely help keep the
There is a corollary to the ‘general
TeX community lively and active.
rule’: if you notice something that ought to
At the time of writing, there are rather
be in the distributions, for which there is no
few .tds.zip files (by comparison with
catalogue entry, please let the CTAN team
the huge number of packages that are avail-
([email protected]) know. It may well be
able). As packages are updated, the num-
that the package has simply been missed,
ber of files is steadily increasing, but it
but some aren’t catalogued because there’s
will be a long time before the whole set is
no documentation and the team just doesn’t
covered.
understand the package.
Use of the files is discussed in “in- In the light of the above, the nonfree
stalling using ready-built ZIP files”. tree is being dismantled, and its contents
76 What was the CTAN nonfree moved (or moved back) to the main CTAN
tree? tree. So the answer to the question is,
now, “the nonfree tree was a part of CTAN,
When CTAN was founded, in the 1990s, whose contents are now in the main tree”.
it was unusual to publish the terms un-
der which a TeX-related package was dis- 77 Contributing a file to the archives
tributed (or, at any rate, to publish those You have something to submit to the
terms formally). archive — good news!
44
 Before we even start, here’s a check- find something confusing, ask advice of
list of things to sort out: the CTAN management team
If your package is large, or regularly
1. Licence: in the spirit of TeX, we updated, it may be appropriate to ‘mirror’
hope for free software; in the spirit your contribution direct into CTAN. Mir-
of today’s lawyer-enthralled society, roring is only practical using ftp or rsync,
CTAN provides a list of “standard” so this facility is limited to packages of-
licence statements. Make sure that fered by a server that uses one of those
there’s a formal statement of the li- protocols.
cence of your package, somewhere
in the files you upload; beyond the README.uploads: README.uploads
CTAN installation, your package is a
candidate for inclusion in (La)TeX dis- 78 Finding (La)TeX files
tributions . . . and thereafter, also in Modern TeX distributions contain a huge
operating system distributions . . . and array of various sorts of files, but sooner or
the people who bundle all these things later most people need to find something
up need a clear statement of your in- that’s not in their present system (if nothing
tent. else, because they’ve heard that something
2. Documentation: it’s good for users has been updated).
to be able to browse documentation But how to find the files?
before downloading a package. You Modern distributions (TeX Live and
need at least a plain text README file MiKTeX, at least) provide the means to up-
(exactly that name, upper case and no date your system “over the net”. This is the
.txt extension); in addition a PDF minimum effort route to getting a new file:
file of the package documentation, pre- ‘simply’ find which of the distribution’s
pared for screen reading, is highly de- ‘packages’ holds the file in question, and
sirable. ask the distribution to update itself. The
3. Name: endless confusion is caused mechanisms are different (the two distri-
by name clashes. If your package butions exhibit the signs of evolutionary
has the same name as one already on divergence in their different niches), but
CTAN, or if your package installation neither is difficult — see “using MiKTeX
generates files of the same name as for installing” and “using TeX Live for in-
something in a “normal” distribution, stalling”.
the CTAN team will delay installa- There are packages, though, that aren’t
tion while they check that you’re do- in the distribution you use (or for which
ing the right thing: they may nag you the distribution hasn’t yet been updated to
to change the name, or to negotiate a offer the version you need).
take-over with the author of the orig-
Some sources, such as these FAQ an-
inal package. Browse the archive to
swers, provide links to files: so if you’ve
ensure uniqueness.
learnt about a package here, you should be
The name you choose should also (as
able to retrieve it without too much fuss.
far as possible) be somewhat descrip-
Otherwise, CTAN provides a full-text
tive of what your submission actu-
search, at its ‘central database’ site, as well
ally does; while “descriptiveness” is
as topic- and author-based indexes and a
to some extent in the eye of the be-
link to browse the archive itself.
holder, it’s clear that names such as
mypackage or jiffy aren’t suitable. An alternative way to scan the cata-
logue is to use the catalogue’s “by topic”
You upload via the CTAN upload redirec- index; this is an older mechanism than the
tor (the archive’s main page has a link). topic-based search (above), but is well pre-
The upload page shows what it needs to sented (even though its data has not been
know, and allows you to enter the infor- updated for some time).
mation. The mechanism can only accept In fact, Google, and other search en-
one file per upload: if you had intended gines, can be useful tools. Enter your
to upload lots of files, you need to bundle search keywords, and you may pick up a
them into an ‘archive’ file of some sort; package that the author hasn’t bothered to
acceptable formats are .zip and .tar.gz submit to CTAN.
(most uploads are packed in .zip format). A user of Google can restrict the search
Once you have completed your upload, the to CTAN by entering
redirector assigns it to a member of the
team for processing. site:ctan.org tex-archive
If you can’t use this method, or if you hsearch term(s)i
45
in Google’s “search box”. You can also (‘vanilla’)(La)TeX and dvips combi-
enforce the restriction using Google’s “ad- nation.
vanced search” mechanism; other search • TrueType fonts can be made to work
engines (presumably) have similar facili- with PDFTeX — see Using TrueType
ties. fonts with TeX. . . (a rather dated
Many people avoid the need to go document, dicsussing use with MiK-
over the network at all, for their searches, TeX 1.11).
by downloading the file list that the • TrueType and OpenType fonts are the
archives’ web file searches use. This file, usual sort used by XeTeX and Lu-
FILES.byname, presents a unified listing aTeX; while straightforward use is
of the archive (omitting directory names pretty easy, one is well-advised to use
and cross-links). Its companion FILES. a package such as fontspec to gain ac-
last07days is also useful, to keep an eye cess to the full range of a font’s capa-
on the changes on the archive. Since these bilities.
files are updated only once a day, a nightly
automatic download (using rsync) makes The answer “choice of scalable fonts”
good sense. discusses fonts that are configured for gen-
eral (both textual and mathematical) use
FILES.byname: FILES.byname with (La)TeX. The list of such fonts is suf-
FILES.last07days: ficiently short that they can all be discussed
FILES.last07days in one answer.
fontspec.sty :
79 Finding new fonts
macros/latex/contrib/fontspec
Nowadays, new fonts are seldom devel-
oped by industrious people using Metafont, Metafont font list:
info/metafont-list
but if such do appear, they will nowadays
be distributed in the same way as any other 80 The TeX collection
part of (La)TeX collections. (An historical
If you don’t have access to the Internet,
review of Metafont fonts available is held
there are obvious attractions to TeX collec-
on CTAN as “Metafont font list”.)
tions on a disc. Even those with net access
Nowadays, most new fonts that appear will find large quantities of TeX-related
are only available in some scalable outline files to hand a great convenience.
form, and a large proportion is distributed The TeX collection provides this, to-
under commercial terms. Such fonts will gether with ready-to-run TeX systems for
only make their way to the free distribu- various architectures. The collection is dis-
tions (at least TeX Live and MiKTeX) if tributed on DVD, and contains:
their licensing is such that the distributions
can accept them. Commercial fonts (those • The TeX Live distribution, including
you have to pay for) do not get to distribu- the programs themselves compiled for
tions, though support for some of them is a variety of architectures; TeX Live
held by CTAN. may be run from the DVD or installed
Arranging for a new font to be usable on hard disc.
by (La)TeX is very different, depending on • MacTeX: an easy to install TeX sys-
which type of font it is, and which TeX- tem for MacOS/X, based on TeX Live;
alike engine you are using; roughly speak- this distribution includes a native Mac
ing: installer, the TeXShop front-end and
other Mac-specific tools;
• MetaFont fonts will work without • ProTeXt: an easy to install TeX sys-
much fuss (provided their sources are tem for Windows, based on MiKTeX,
in the correct place in the installation’s based on an ‘active’ document that
tree); TeX-with-dvips, and PDFTeX guides installation; and
are “happy” with them. While a new • A snapshot of CTAN.
font will need ‘generating’ (by run-
ning Metafont, etc.), distributions are A fair number of national TeX User
set up to do that “on the fly” and to Groups, as well as TUG, distribute copies
save the results (for next time). to their members at no extra charge. Some
• Adobe Type 1 fonts can be made to user groups are also able to sell additional
work, after .tfm and (usually) .vf copies: contact your local user group or
files have been created from their TUG.
metric (.afm) files; .map files also You may also download disc images
need to be created. Such fonts will from CTAN; the installation disc, ProTeXt
work with PDFTeX, and with the and MacTeX are all separately available.
46
Beware: they are all pretty large down- close as you’re likely to get to Knuth’s orig-
loads. TeX Live, once installed, may be inal distribution. It is known to work well,
updated online. but the omission of e-TeX and PDFTeX
More details of the collection are avail- will rule it out of many users’ choices.
able from its own web page on the TUG tex-gpc: systems/unix/tex-gpc
site.
texlive: Browse systems/texlive
MacTeX : systems/mac/mactex
texlive installer (Unix):
ProTeXt: systems/win32/protext
systems/texlive/tlnet/
TeX Live install image: install-tl-unx.tar.gz
systems/texlive
83 (Modern) Windows systems
Windows users nowadays have a real
E TeX Systems choice, between two excellent distribu-
tions, MiKTeX and TeX Live. TeX Live
81 (La)TeX for different machines on windows has only in recent years been
We list here the free or shareware packages; a real challenger to the long-established
a later question discusses commercial TeX MiKTeX, and even now MiKTeX has fea-
products. tures that TeX Live lacks. Both are com-
The list is provided in four answers: prehensive distributions, offering all the
established TeX variants (TeX, PDFTeX —
• TeX systems for use with Unix and both with e-TeX variants — as well as Xe-
GNU Linux systems TeX and LuaTeX), together with a wide
• TeX systems for use with Modern range of support tools.
Windows systems Both MiKTeX and TeX Live offer man-
• TeX systems for use with Macintosh agement tools, including the means of
systems keeping an installation “up-to-date”, by re-
• TeX systems for Other sorts of sys- installing packages that have been updated
tems on CTAN (the delay between a package
update appearing, and it being available to
82 Unix and GNU Linux systems the distribution users) can be as short as a
Note that Mac OS/X, though it day (and is never very long).
is also a Unix-based system, has MiKTeX, by Christian Schenk, is the
different options; users should re- longer-established of the pair, and has a
fer to the information in Mac sys- large audience of satisfied users; TeX Live
tems. is the dominant distribution in use in the
world of Unix-like systems, and so its
The TeX distribution of choice, for Windows version may be expected to ap-
Unix systems (including GNU/Linux and peal to those who use both Unix-like and
most other free Unix-like systems) is TeX Windows systems. The latest release of
Live, which is distributed as part of the MiKTeX — version 2.9 — requires Win-
TeX collection. dows XP, or later (so it does not work on
TeX Live may also be installed “over Windows 2000 or earlier).
the network”; a network installer is pro- Both distributions may be used in a
vided, and once you have a system configuration which involves no installa-
(whether installed from the network or in- tion at all. MiKTeX’s “portable” distribu-
stalled off-line from a disc) a manager tion may be unpacked on a memory stick,
(tlmgr) can both keep your installation up- and used on any windows computer with-
to-date and add packages you didn’t install out making any direct use of the hard drive.
at first. The web page TeX Live portable usage de-
TeX Live may be run with no installa- scribes the options for installing TeX Live
tion at all; the web page TeX Live portable on a memory stick, or for using the TeX
usage describes the options for installing Live DVD with no installation at all.
TeX Live on a memory stick for use on an- Both MiKTeX and TeX Live may be
other computer, or for using the TeX Live downloaded and installed, package by
DVD with no installation at all. package, over the net. This is a mam-
TeX-gpc is a “back-to-basics” distri- moth undertaking, only to be undertaken
bution of TeX utilities, only (unlike TeX by those with a good network connection
Live, no ‘tailored’ package bundles are pro- (and a patient disposition!).
vided). It is distributed as source, and com- A ready-to-run copy of the MiKTeX
piles with GNU Pascal, thereby coming as distribution, on DVD may be bought via
47
the MiKTeX web site. MiKTeX may also OzTeX, by Andrew Trevorrow, is
be installed using ProTeXt, on the TeX Col- a shareware version of TeX for the
lection DVD. Macintosh. A DVI previewer and
The TeX Collection DVD also pro- PostScript driver are also included. Oz-
vides an offline installer for TeX Live. TeX is a Carbon app, so will run under
A further (free) option is available Mac OS/X (see http://www.trevorrow.
thanks to the CygWin bundle, which com/oztex/ozosx.html for details), but
presents a Unix-like environment in Win- it is not a current version: it doesn’t even
dows systems (and also provides an X- offer PDFTeX. A mailing list is provided
windows server). The (now obsolete) by TUG: sign up via http://tug.org/
teTeX distribution is provided as part of mailman/listinfo/oztex
the CygWin distribution, but there is a Cyg- Another partly shareware program is
Win build of TeX Live so you can have a CMacTeX, put together by Tom Kiffe.
current TeX system. TeX under CygWin CMacTeX is much closer than OzTeX to
is reputedly somewhat slower than native the Unix TeX model of things (it uses
Win32 implementations such as MiKTeX, dvips, for instance). CMacTeX runs na-
and of course the TeX applications behave tively under Mac OS/X; it includes a port
like Unix-system applications. of a version of Omega.
BaKoMa TeX, by Basil Malyshev, is Further information may be available
a comprehensive (shareware) distribution, in the MacTeX wiki. The MacTeX-on-
which focuses on support of Acrobat. The OS X mailing list is another useful re-
distribution comes with a bunch of Type 1 source for users; subscribe via the list
fonts packaged to work with BaKoMa TeX, home page
which further the focus.
cmactex : systems/mac/cmactex
bakoma: systems/win32/bakoma
mactex : systems/mac/mactex
miktex : systems/win32/miktex;
acquire systems/win32/miktex/ oztex : systems/mac/oztex
setup/setup.exe (also available
85 Other systems’ TeX availability
from the MiKTeX web site), and
read installation instructions from For PCs, running MS-DOS or OS/2, Em-
the MiKTeX installation page TeX (by Eberhard Mattes) offers LaTeX,
BibTeX, previewers, and drivers. It is avail-
Portable miktex :
able as a series of zip archives, with doc-
systems/win32/miktex/
umentation in both German and English.
setup/miktex-portable.exe
Appropriate memory managers for using
protext.exe: emTeX with 386 (and better) processors
systems/win32/protext and under pre-’9x Windows, are included
texlive: Browse systems/texlive in the distribution. (EmTeX can be made
to operate under Windows, but even back
texlive installer (Windows):
when it was “current”, such use wasn’t
systems/texlive/tlnet/
very actively encouraged.)
install-tl.zip
A version of emTeX, packaged to use a
84 Macintosh systems TDS directory structure, is separately avail-
The TeX collection DVD includes Mac- able as an emTeX ‘contribution’. Note that
TeX, which is a Mac-tailored version of neither emTeX itself, nor emTeX-TDS, is
TeX Live; details may be found on the maintained. Users of Microsoft operating
TUG web site. If you don’t have the disc, systems, who want an up-to-date (La)TeX
you can download the distribution from system, need Win32-based systems.
CTAN (but note that it’s pretty big). Mac- For PCs, running MS-DOS, a further
TeX is an instance of TeX Live, and has option is a port of the Web2C 7.0 imple-
a Mac-tailored graphical TeX Live man- mentation, using the GNU djgpp compiler.
ager, so that you can keep your distribution While this package is more recent than em-
up-to-date. TeX, it nevertheless also offers a rather old
Note that installing MacTeX requires instance of (La)TeX.
root privilege. This is a pity, since it of- For VAX systems running OpenVMS,
fers several extras that aren’t available via a TeX distribution is available CTAN, but
a standard TeX Live, which aren’t there- is almost certainly not the latest (it is more
fore available to “ordinary folk” at work. than 10 years old). Whether a version is
For those who don’t have root privilege, even available for current VMS (which typ-
the option is to install using the TeX Live ically runs on Intel 64-bit processors) is not
tlinstall utility. clear, but it seems unlikely.
48
 For the Atari ST and TT, CS-TeX is LaTeX4Jed provides much enhanced
available from CTAN; it’s offered as a set LaTeX support for the jed editor.
of ZOO archives. LaTeX4Jed is similar to AUC-TeX:
Amiga users have the option of a full menus, shortcuts, templates, syntax
implementations of TeX 3.1 (PasTeX) and highlighting, document outline, in-
Metafont 2.7. tegrated debugging, symbol comple-
It’s less likely that hobbyists would be tion, full integration with external pro-
running TOPS-20 machines, but since TeX grams, and more. It was designed with
was originally written on a DEC-10 un- both the beginner and the advanced
der WAITS, the TOPS-20 port is another LaTeX user in mind.
near approach to Knuth’s original envi- The Kile editor that is provided with
ronment. Sources are available by anony- the KDE window manager provides
mous ftp from ftp://ftp.math.utah. GUI “shell-like” facilities, in a similar
edu/pub/tex/pub/web way to the widely-praised Winedt (see
below); details (and downloads) are
Atari TeX: systems/atari/cs-tex
available from the project’s home on
djgpp: systems/msdos/djgpp SourceForge.
emtex : systems/msdos/emtex TUG is sponsoring the development
of a cross-platform editor and shell,
emtexTDS : modelled on the excellent TeXshop for
obsolete/systems/os2/emtex- the Macintosh. The result, TeXworks,
contrib/emtexTDS is recommended: if you’re looking for
OpenVMS : systems/OpenVMS/TEX97_ a (La)TeX development environment,
CTAN.ZIP it may be for you. (It is distributed
with both TeX Live and MiKTeX.)
PasTeX : systems/amiga
A possible alternative is TeXstudio
86 TeX-friendly editors and shells Windows-32 TeXnicCenter is a (free)
TeX-oriented development system,
There are good TeX-writing environments uniting a powerful platform for exe-
and editors for most operating systems; cuting (La)TeX and friends with a con-
some are described below, but this is only figurable editor.
a personal selection: TeXworks (see above) is also available
for Windows systems.
Unix The commonest choices are [X]
Winedt, a shareware package, is also
Emacs or vim, though several others
highly spoken of. It too provides a
are available.
shell for the use of TeX and related
GNU emacs and XEmacs are sup-
programs, as well as a powerful and
ported by the AUC-TeX bundle (avail-
well-configured editor. The editor
able from CTAN). AUC-TeX provides
can generate its output in UTF-8 (to
menu items and control sequences for
some extent), which is useful when
common constructs, checks syntax,
working with XeTeX (and other “next-
lays out markup nicely, lets you call
generation” (La)TeX applications).
TeX and drivers from within the edi-
Both emacs and vim are available in
tor, and everything else like this that
versions for Windows systems.
you can think of. Complex, but very
Macintosh For Mac OS/X users, the free
powerful.
tool of choice appears to be TeXshop,
Vim is also highly configurable (also
which combines an editor and a shell
available for Windows and Macintosh
with a coherent philosophy of dealing
systems). Many plugins are available
with (La)TeX in the OS X environ-
to support the needs of the (La)TeX
ment. TeXShop is distributed as part
user, including syntax highlighting,
of the MacTeX system, and will there-
calling TeX programs, auto-insertion
fore be available out of the box on
and -completion of common (La)TeX
machines on which MacTeX has been
structures, and browsing LaTeX help.
installed.
The scripts auctex.vim and bibtex.
Vim is also available for use on Macin-
vim seem to be the most common rec-
tosh systems.
ommendations.
The commercial Textures provides an
The editor NEdit is also free and pro-
excellent integrated Macintosh envi-
grammable, and is available for Unix
ronment with its own editor. More
systems. An AUC-TeX-alike set of
powerful still (as an editor) is the
extensions for NEdit is available from
shareware Alpha which is extensible
CTAN.
49
 enough to let you perform almost USA
any TeX-related job. It also works Tel: +1 561-966-8400
well with OzTeX. From release 2.2.0 Email: [email protected]
(at least), Textures works under Mac Web: http://www.truetex.
OS/X. com/
OS/2 epmtex offers an OS/2-specific shell.
Source: Mail from Richard Kinch, Au-
Atari, Amiga and NeXT users also have gust 2004.
nice environments. LaTeX users look- pcTeX Long-established: pcTeX32 is a
ing for make-like facilities should review Windows implementation.
the answer on Makefiles for LaTeX docu- Personal TeX Inc
ments. 725 Greenwich Street, Suite
While many (La)TeX-oriented editors 210
can support work on BibTeX files, there San Francisco, CA 94133
are many systems that provide specific USA
“database-like” access to your BibTeX
Tel: 800-808-7906 (within the
files — see “creating a bibliography file”.
USA)
alpha: systems/mac/support/alpha Tel: +1 415-296-7550
auctex : support/auctex Fax: +1 415-296-7501
Email: [email protected]
epmtex : systems/os2/epmtex
Web: http://www.pctex.
LaTeX4Jed : support/jed com/
Nedit LaTeX support: Source: Personal TeX Inc web site,
support/NEdit-LaTeX- December 2004
Extensions PC; Scientific Word Scientific Word and
TeXnicCenter : Scientific Workplace offer a mecha-
systems/win32/TeXnicCenter nism for near-WYSIWYG input of La-
TeX documents; they ship with True-
TeXshell: systems/msdos/texshell
TeX from Kinch (see above). Queries
TeXtelmExtel: within the UK and Ireland should be
systems/msdos/emtex- addressed to Scientific Word Ltd., oth-
contrib/TeXtelmExtel ers should be addressed directly to the
winedt: systems/win32/winedt publisher, MacKichan Software Inc.
87 Commercial TeX implementations Dr Christopher Mabb
Scientific Word Ltd.
There are many commercial implementa-
990 Anlaby Road,
tions of TeX. The first appeared not long
Hull,
after TeX itself appeared.
East Yorkshire,
What follows is probably an incom-
HU4 6AT
plete list. Naturally, no warranty or fitness
UK
for purpose is implied by the inclusion of
any vendor in this list. The source of the Tel: 0845 766 0340 (within the
information is given to provide some clues UK)
to its currency. Fax: 0845 603 9443 (within the
In general, a commercial implementa- UK)
tion will come ‘complete’, that is, with suit- Email: christopher@
able previewers and printer drivers. They sciword.demon.co.uk
normally also have extensive documenta- Web: http://www.sciword.
tion (i.e., not just the TeXbook!) and some demon.co.uk
sort of support service. In some cases this MacKichan Software Inc.
is a toll free number (probably applicable 19307 8th Avenue, Suite C
only within the USA and or Canada), but Poulsbo WA 98370-7370
others also have email, and normal tele- USA
phone and fax support.
Tel: +1 360 394 6033
PC; TrueTeX Runs on all versions of Tel: 877 724 9673 (within the
Windows. USA) Fax: +1 360 394 6039
Email: [email protected]
Richard J. Kinch
Web: http://www.mackichan.
TrueTeX Software
com
7890 Pebble Beach Court
Lake Worth FL 33467 Source: Mail from Christopher Mabb,
50
 August 2007 dviljk : dviware/dviljk
AmigaTeX A full implementation for the
90 Output to “other” printers
Commodore Amiga, including full,
on-screen and printing support for all In the early years of TeX, there were
PostScript graphics and fonts, IFF masses of DVI drivers for any (then) imag-
raster graphics, automatic font gener- inable kind of printer, but the steam seems
ation, and all of the standard macros rather to have gone out of the market for
and utilities. production of drivers for printer-specific
formats. There are several reasons for
Radical Eye Software this, but the primary one is that few for-
PO Box 2081 mats offer the flexibility available through
Stanford, CA 94309 PostScript, and with ghostscript (and its
USA huge range of printer drivers) there is now
Source: Mail from Tom Rokicki, little demand for new printer driver devel-
November 1994 opment.
Thus, it is reasonable to generate
Note that the company Y&Y has gone PostScript, and use ghostscript to send the
out of business, and Y&Y TeX (and sup- resulting PostScript output to the printer
port for it) is therefore no longer avail- you actually have.
able. Users of Y&Y systems may care (If you are using a Unix system of
to use the self-help mailing list that was some sort, it’s generally quite easy to insert
established in 2003; the remaining usable ghostscript into the print spooling process,
content of Y&Y’s web site is available at which makes printing really simple.)
http://www.tug.org/yandy/
91 DVI previewers
EmTeX for PCs running MS-DOS or OS/2,
F DVI Drivers and Pre- MiKTeX and XEmTeX for PCs running
viewers Windows and OzTeX for the Macintosh,
all come with previewers that can be used
88 DVI to PostScript conversion on those platforms. EmTeX’s previewer
programs can also be run under Windows 3.1.
The best public domain DVI to PostScript Commercial PC TeX packages (see
conversion program, which runs under commercial vendors) have good preview-
many operating systems, is Tom Rokicki’s ers for PCs running Windows, or for Mac-
dvips. dvips is written in C and ports eas- intoshes.
ily. All current development is in the con- For Unix systems, there is one ‘canoni-
text of Karl Berry’s kpathsea library, and cal’ viewer, xdvi. Xdvik is a version of xdvi
sources are available from the TeX Live using the web2c libraries; it is now built
repository, and versions are available in all from the same distribution as xdvi. The
TeX distributions that recognise the use of TeX Live distributions for Unix systems
PostScript. include a version of xdvik.
An VMS versions is available as part Alternatives to previewing include
of the CTAN distribution of TeX for VMS. • conversion to ‘similar’ ASCII text (see
A precompiled version to work with converting to ASCII) and using a con-
emTeX is available on CTAN. ventional text viewer to look at that,
MS-DOS and OS/2: • generating a PostScript version of
systems/msdos/dviware/dvips your document and viewing it with a
VMS distribution: systems/OpenVMS/ ghostscript-based previewer (see pre-
TEX97_CTAN.ZIP viewing PostScript files), and
• generating PDF output, and viewing
89 DVI drivers for HP LaserJet that with Acrobat Reader or one of the
The emTeX distribution (see TeX systems) substitutes for that.
contains a driver for the LaserJet, dvihplj.
xdvi: dviware/xdvi
Version 2.10 of the Beebe drivers sup-
ports the LaserJet. These drivers will com- 92 Generating bitmaps from DVI
pile under Unix, VMS, and on the Atari In the last analysis, any DVI driver or pre-
ST and DEC-20s. viewer is generating bitmaps: bitmaps for
For Unix systems, Karl Berry’s dviljk placing tiny dots on paper via a laser- or
uses the same path-searching library as inkjet-printer, or bitmaps for filling some
web2c. portion of your screen. However, it’s usu-
Beebe drivers: dviware/beebe ally difficult to extract any of those bitmaps
51
any way other than by screen capture, G Support Packages for
and the resolution of that is commonly
lamentable.
TeX
93 (La)TeX-friendly drawing
Why would one want separate packages
bitmaps? Most often, the requirement
(X)Fig is a menu driven tool that allows
is for something that can be included in
you to draw objects on the screen of an X
HTML generated from (La)TeX source —
workstation; transfig is a set of tools which
not everything that you can write in
translate the code fig. The list of export for-
(La)TeX can be translated to HTML (at
mats is very long, and includes Metafont
least, portable HTML that may be viewed
and Metapost, Encapsulated PostScript and
in ‘most’ browsers), so the commonest
PDF, as well as combinations that wrap a
avoiding action is to generate a bitmap of
graphics format in a LaTeX import file,
the missing bit. Examples are maths (a
which may include LaTeX commands to
maths extension to the ‘*ML’ family is
place text (compiled by LaTeX itself) as
available but not universally supported by
labels, etc., in the figures.
browsers), and ‘exotic’ typescripts (ones
There’s no explicit port of xfig to win-
that you cannot guarantee your readers
dows (although it is believed to work under
will have available). Other common ex-
cygwin with its X-windows system). How-
amples are generation of sample bitmaps,
ever, the program jfig is thought by many
and generation for insertion into some
to be an acceptable substitute, written in
other application’s display — to insert
Java.
equations into Microsoft PowerPoint, or to
Asymptote is a widely-praised devel-
support the enhanced-emacs setup called
opment of the Metapost language, which
preview-latex.
can draw 2D or 3D diagrams, and can also
label diagrams with LaTeX text; copious
In the past, the commonest way of documentation is available via asymptote’s
generating bitmaps was to generate a web site.
PostScript file of the DVI and then use
asymptote: graphics/asymptote
ghostscript to produce the required bitmap
format (possibly by way of PNM format or xfig : graphics/xfig
something similar). This is an undesirable transfig : graphics/transfig
procedure (it is tedious, involving requires
two or three steps that run slowly) but it 94 TeXCAD, a drawing package for
served for a long time. LaTeX
TeXCAD is a program for the PC which en-
(La)TeX users may now take ad- ables the user to draw diagrams on screen
vantage of two bitmap ‘drivers’. The using a mouse or arrow keys, with an on-
longer-established, dvi2bitmap, will gen- screen menu of available picture-elements.
erate XBM and XPM formats, the long- Its output is code for the LaTeX picture
deprecated GIF format (which is now ob- environment. Optionally, it can be set to
solescent, but has finally been relieved of include lines at all angles using the emTeX
the patent protection of the LZW compres- driver-family (\specials). TeXCAD is
sion it uses), and also the modern (ISO- part of the emTeX distribution.
standardised) PNG format. A Unix port of the program (xtexcad)
has been made.
Dvipng started out as a PNG renderer; emtex : systems/msdos/emtex
from version 1.2 it can also render to the
xtexcad : graphics/xtexcad/
GIF format. It is designed for speed, in en-
xtexcad-2.4.1.tar.gz
vironments that generate large numbers of
PNG files: the README mentions preview- 95 Spelling checkers for work with
latex, LyX, and a few web-oriented environ- TeX
ments. Note that dvipng gives high-quality ‘Traditional’ approaches to the problem (of
output even though its internal operations checking your spelling) were designed to
are optimised for speed. work with a plain text file; in our case,
dvi2bitmap: dviware/dvi2bitmap we have an (La)TeX source. For the user,
this is a simple-to-understand way to do
the job; but for the spell-checker program-
mer, it requires heuristic (and hence fal-
dvipng : dviware/dvipng lible) analysis of (La)TeX macros and so
52
on. The alternative, of viewing the text af- dictionaries (under subdirectory
ter (La)TeX has processed the results, is dict/) that you need.
covered below. excalibur : systems/mac/support/
The user of an shell/editor will usu- excalibur/Excalibur-
ally find it embeds a spelling checker. 4.0.2.sit.hqx
For command-line use, there are several
choices, depending on the system you’re ispell: support/ispell
using. jspell: support/jspell
For Unix, ispell was long the program spelling.sty : macros/luatex/
of choice; it is well integrated with emacs, generic/spelling
and deals with some TeX syntax. However,
it has more-or-less been replaced every- VMS spell: support/vmspell
where, by aspell, which was designed as winedt: systems/win32/winedt
a successor, and certainly performs better
on most metrics; there remains some ques- 96 How many words have you
tion as to its performance with (La)TeX written?
sources. The most recent offering (which One often has to submit a document (e.g.,
is widely used in other open-source soft- a paper or a dissertation) under some sort
ware projects) is Hunspell. Hunspell is of constraint about its size. Sensible peo-
available for other architectures, too; a web ple set a constraint in terms of numbers of
search shows versions available for Win- pages, but there are some that persist in
dows, at least. limiting the numbers of words you type.
For the Macintosh, Excalibur has long A simple solution to the requirement
been used; its distribution comes with dic- can be achieved following a simple obser-
tionaries for several languages. Hunspell vation: the powers that be are unlikely to
(see above) is actually part of OS X from count all the words of a document submit-
version 10.6. ted to them. Therefore, a statistical method
The VMS Pascal program spell makes can be employed: find how many words
special cases of some important features there are on a full page; find how many full
of LaTeX syntax. pages there are in the document (allowing
For MS-DOS, there are several pro- for displays of various sorts, this number
grams. Amspell can be called from within will probably not be an integer); multiply
an editor, and jspell is an extended version the two. However, if the document to be
of ispell. submitted is to determine the success of
An alternative approach takes (La)TeX the rest of one’s life, it takes a brave per-
output, and checks that. A straightforward son to thumb their nose at authority quite
approach is to produce PDF output, and so comprehensively. . .
process it with pdftotext, using any plain The simplest method is to strip out the
text checker on the result (the checkers (La)TeX markup, and to count what’s left.
listed above all work in this rôle). For this On a Unix-like system, this may be done
to work reasonably well, the user should using detex and the built-in wc:
disable hyphenation before making the
detex <filename> | wc -w
PDF output.
The (experimental) LuaTeX/LaTeX The technique is beguilingly simple, but
package spelling goes one step further: it it’s not terribly accurate
uses lua code to extract words while type- The latexcount script does the same
setting is going on, but before hyphenation sort of job, in one “step”; being a perl
is applied. Each word is looked up in a list script, it is in principle rather easily config-
of known bad spellings, and the word high- ured (see documentation inside the script).
lighted if it appears there. In parallel, a text Several editors and shells offer something
file is created, which can be processed by similar.
a ‘normal’ spelling checker to produce a TeXcount goes a long way with heuris-
revised “bad spelling” list. (The package tics for counting, starting from a LaTeX
documentation shows the end result; it in- file; the documentation is comprehensive,
cludes words such as ‘spellling’, which are and you may try the script on-line via the
duly highlighted.) package home page.
4spell: support/4spell However, even quite sophisticated
stripping of (La)TeX markup can never be
amspell: support/amspell
entirely reliable: markup itself may con-
aspell: Browse support/aspell — tribute typeset words, or even consume
choose just those language words that appear in the text.
53
 The wordcount package contains a awk, and C and, while not in the public
Bourne shell (i.e., typically Unix) script for domain, is usable without charge. It is now
running a LaTeX file with a special piece superseded by noweb (also by Norman
of supporting TeX code, and then count- Ramsay) which incorporates the lessons
ing word indications in the log file. This learned in implementing spidery WEB,
is probably as accurate automatic counting and which is a simpler, equally powerful,
as you can get, if it works for you. tool.
detex : support/detex SchemeWEB, by John Ramsdell, is a
Unix filter that translates SchemeWEB into
latexcount.pl: support/ LaTeX source or Scheme source.
latexcount/latexcount.pl APLWEB is a version of WEB for APL.
TeXcount: support/texcount FunnelWeb is a version of WEB that is
wordcount: macros/latex/contrib/
language independent.
wordcount
Other language independent versions
of WEB are nuweb (which is written in
ANSI C).
H Literate programming Tweb is a WEB for Plain TeX macro
files, using noweb.
97 What is Literate Programming? aplweb: web/apl/aplweb
Literate programming is the combination cweb: web/c_cpp/cweb
of documentation and source together in
funnelweb: web/funnelweb
a fashion suited for reading by human be-
ings. In general, literate programs combine fweb: web/fweb
source and documentation in a single file. noweb: web/noweb
Literate programming tools then parse the
nuweb: web/nuweb
file to produce either readable documen-
tation or compilable source. The WEB schemeweb: web/schemeweb
style of literate programming was created spiderweb: web/spiderweb
by D. E. Knuth during the development of
tangle: systems/knuth/dist/web
TeX.
The “documented LaTeX” style of pro- tweb: web/tweb
gramming is regarded by some as a form of weave: systems/knuth/dist/web
literate programming, though it only con-
tains a subset of the constructs Knuth used.
Discussion of literate programming I Format conversions
is conducted in the newsgroup comp.
programming.literate, whose FAQ 99 Conversion from (La)TeX to plain
is stored on CTAN. Another good text
source of information is http://www. The aim here is to emulate the Unix nroff ,
literateprogramming.com/ which formats text as best it can for the
Literate Programming FAQ: help/comp. screen, from the same input as the Unix
programming.literate_FAQ typesetting program troff .
Converting DVI to plain text is the ba-
98 WEB systems for various sis of many of these techniques; some-
languages times the simple conversion provides a
TeX is written in the programming lan- good enough response. Options are:
guage WEB; WEB is a tool to implement
• dvi2tty (one of the earliest),
the concept of “literate programming”.
• crudetype and
Knuth’s original implementation will be
• catdvi, which is capable of generating
in any respectable distribution of TeX, but
Latin-1 (ISO 8859-1) or UTF-8 en-
the sources of the two tools (tangle and
coded output. Catdvi was conceived
weave), together with a manual outlining
as a replacement for dvi2tty, but devel-
the programming techniques, may be had
opment seems to have stopped before
from CTAN.
the authors were willing to declare the
CWEB, by Silvio Levy, is a WEB for
work complete.
C programs.
FWEB, by John Krommes, is a version A common problem is the hyphenation that
for Fortran, Ratfor,C, C++, working with TeX inserts when typesetting something:
LaTeX; it was derived from CWEB. since the output is inevitably viewed us-
Spidery WEB, by Norman Ramsey, ing fonts that don’t match the original, the
supports many languages including Ada, hyphenation usually looks silly.
54
 Ralph Droms provides a txt bundle of and lex; this is hard, in practice, be-
things in support of ASCII generation, but cause of the complexity of SGML.
it doesn’t do a good job with tables and 2. Use a specialist language designed
mathematics. for SGML transformations; the best
Another possibility is to use the LaTeX- known are probably Omnimark and
to-ASCII conversion program, l2a, al- Balise. They are expensive, but pow-
though this is really more of a de-TeXing erful, incorporating SGML query and
program. transformation abilities as well as sim-
The canonical de-TeXing program is ple translation.
detex, which removes all comments and 3. Build a translator on top of an existing
control sequences from its input before SGML parser. By far the best-known
writing it to its output. Its original purpose (and free!) parser is James Clark’s
was to prepare input for a dumb spelling nsgmls, and this produces a much
checker, and it’s only usable for preparing simpler output format, called ESIS,
useful ASCII versions of a document in which can be parsed quite straightfor-
highly restricted circumstances. wardly (one also has the benefit of an
Tex2mail is slightly more than a de- SGML parse against the DTD). Two
TeXer — it’s a Perl script that converts TeX good public domain packages use this
files into plain text files, expanding various method:
mathematical symbols (sums, products, in- • David Megginson’s sgmlspm, writ-
tegrals, sub/superscripts, fractions, square ten in Perl 5.
roots, . . . ) into “ASCII art” that spreads • Joachim Schrod and Christine
over multiple lines if necessary. The result Detig’s STIL, (‘SGML Transforma-
is more readable to human beings than the tions in Lisp’).
flat-style TeX code.
Both of these allow the user to write
Another significant possibility is to use
‘handlers’ for every SGML element,
one of the HTML-generation solutions,
with plenty of access to attributes, enti-
and then to use a browser such as lynx to
ties, and information about the context
dump the resulting HTML as plain text.
within the document tree.
catdvi: dviware/catdvi If these packages don’t meet your
crudetype: dviware/crudetype needs for an average SGML typeset-
ting job, you need the big commercial
detex : support/detex
stuff.
dvi2tty : dviware/dvi2tty
Since HTML is simply an example of
l2a: support/l2a
SGML, we do not need a specific system
tex2mail: support/tex2mail for HTML. However, Nathan Torking-
ton developed html2latex from the HTML
txt: support/txt
parser in NCSA’s Xmosaic package. The
100 Conversion from SGML or program takes an HTML file and gener-
HTML to TeX ates a LaTeX file from it. The conversion
SGML is a very important system for code is subject to NCSA restrictions, but
document storage and interchange, but the whole source is available on CTAN.
it has no formatting features; its com- Michel Goossens and Janne Saarela
panion ISO standard DSSSL (see http: published a very useful summary of
//www.jclark.com/dsssl/) is designed
SGML, and of public domain tools for writ-
for writing transformations and formatting, ing and manipulating it, in TUGboat 16(2).
but this has not yet been widely imple- html2latex source:
mented. Some SGML authoring systems support/html2latex
(e.g., SoftQuad Author/ Editor) have for-
101 Conversion from (La)TeX to
matting abilities, and there are high-end
HTML
specialist SGML typesetting systems (e.g.,
Miles33’s Genera). However, the major- TeX and LaTeX are well suited to pro-
ity of SGML users probably transform the ducing electronically publishable docu-
source to an existing typesetting system ments. However, it is important to re-
when they want to print. TeX is a good can- alize the difference between page layout
didate for this. There are three approaches and functional markup. TeX is capable
to writing a translator: of extremely detailed page layout; HTML
is not, because HTML is a functional
1. Write a free-standing translator in the markup language not a page layout lan-
traditional way, with tools like yacc guage. HTML’s exact rendering is not
55
specified by the document that is published like access to a LaTeX document, as
but is, to some degree, left to the discre- well as the ability to generate mulit-
tion of the browser. If you require your ple output formats (e.g. HTML, Doc-
readers to see an exact replication of what Book, tBook, etc.).
your document looks like to you, then you TeXpider a commercial program from
cannot use HTML and you must use some Micropress, which is described
other publishing format such as PDF. That on http://www.micropress-inc.
is true for any HTML authoring tool. com/webb/wbstart.htm; it uses
TeX’s excellent mathematical capabil- bitmaps for equations.
ities remain a challenge in the business Hevea a compiled program that supports
of conversion to HTML. There are only LaTeX only, and uses the font/table
two generally reliable techniques for gen- technique for equations (indeed its
erating mathematics on the web: creating entire approach is very similar to
bitmaps of bits of typesetting that can’t TtH). It is written in Objective
be translated, and using symbols and table CAML by Luc Maranget. Hevea
constructs. Neither technique is entirely isn’t archived on CTAN; details (in-
satisfactory. Bitmaps lead to a profusion cluding download points) are avail-
of tiny files, are slow to load, and are in- able via http://pauillac.inria.
accessible to those with visual disabilities. fr/~maranget/hevea/
The symbol fonts offer poor coverage of
An interesting set of samples, includ-
mathematics, and their use requires con-
ing conversion of the same text by the
figuration of the browser. The future of
four free programs listed above, is avail-
mathematical browsing may be brighter —
able at http://www.mayer.dial.pipex.
see future Web technologies.
com/samples/example.htm; a linked
For today, possible packages are:
page gives lists of pros and cons, by way
LaTeX2HTML a Perl script package that of comparison.
supports LaTeX only, and gener- The World Wide Web Consortium
ates mathematics (and other “difficult” maintains a list of “filters” to HTML,
things) using bitmaps. The original with sections on (La)TeX and BibTeX —
version was written by Nikos Drakos see http://www.w3.org/Tools/Word_
for Unix systems, but the package now proc_filters.html
sports an illustrious list of co-authors latex2html: Browse
and is also available for Windows sys- support/latex2html
tems. Michel Goossens and Janne
Saarela published a detailed discus- plasTeX : Browse support/plastex
sion of LaTeX2HTML, and how to tai- tex4ht: obsolete/support/TeX4ht/
lor it, in TUGboat 16(2). tex4ht-all.zip (but see
A mailing list for users may be found http://tug.org/tex4ht/)
via http://tug.org/mailman/ tth: support/tth/dist
listinfo/latex2html
TtH a compiled program that supports ei- 102 Other conversions to and from
ther LaTeX or Plain TeX, and uses (La)TeX
the font/table technique for represent- troff Tr2latex, assists in the translation of
ing mathematics. It is written by Ian a troff document into LaTeX 2.09 for-
Hutchinson, using flex. The distribu- mat. It recognises most -ms and -man
tion consists of a single C source (or macros, plus most eqn and some tbl
a compiled executable), which is easy preprocessor commands. Anything
to install and very fast-running. fancier needs to be done by hand. Two
TeX4ht a compiled program that supports style files are provided. There is also
either LaTeX or Plain TeX, by pro- a man page (which converts very well
cessing a DVI file; it uses bitmaps for to LaTeX. . . ). Tr2latex is an enhanced
mathematics, but can also use other version of the earlier troff-to-latex
technologies where appropriate. Writ- (which is no longer available).
ten by Eitan Gurari, it parses the DVI WordPerfect wp2latex is actively main-
file generated when you run (La)TeX tained, and is available either for MS-
over your file with tex4ht’s macros in- DOS or for Unix systems.
cluded. As a result, it’s pretty robust RTF Rtf2tex, by Robert Lupton, is for
against the macros you include in your converting Microsoft’s Rich Text For-
document, and it’s also pretty fast. mat to TeX. There is also a converter
plasTeX a Python-based LaTeX document to LaTeX by Erwin Wechtl, called
processing framework. It gives DOM- rtf2latex. The latest converter, by
56
 Ujwal Sathyam and Scott Prahl, is collection includes a shell script con-
rtf2latex2e which seems rather good, verter from BibTeX to refer format as
though development of it seems to well. The collection is not maintained.
have stalled. PC-Write pcwritex.arc is a print driver
Translation to RTF may be done (for for PC-Write that “prints” a PC-Write
a somewhat constrained set of LaTeX V2.71 document to a TeX-compatible
documents) by TeX2RTF, which can disk file. It was written by Peter Flynn
produce ordinary RTF, Windows Help at University College, Cork, Republic
RTF (as well as HTML, conversion of Ireland.
to HTML). TeX2RTF is supported
Wilfried Hennings’ FAQ, which deals
on various Unix platforms and under
specifically with conversions between TeX-
Windows 3.1
based formats and word processor formats,
Microsoft Word A rudimentary (free)
offers much detail as well as tables that
program for converting MS-Word to
allow quick comparison of features.
LaTeX is wd2latex, which runs on MS-
A group at Ohio State University
DOS; it probably processes the output
(USA) is working on a common document
of an archaic version of MS-Word (the
format based on SGML, with the ambition
program itself was archived in 1991).
that any format could be translated to or
For conversion in the other direction,
from this one. FrameMaker provides “im-
the current preferred free-software
port filters” to aid translation from alien
method is a two-stage process:
formats (presumably including TeX) to
• Convert LaTeX to OpenOffice for- FrameMaker’s own.
mat, using the tex4ht command
excel2latex : support/excel2latex
oolatex;
• open the result in OpenOffice and pcwritex.arc: support/pcwritex
‘save as’ a MS-Word document. refer and tib tools:
(Note that OpenOffice itself is biblio/bibtex/utils/refer-
not on CTAN; see http://www. tools
openoffice.org/, though most rnototex : support/rnototex
linux systems offer it as a ready-to- rtf2latex : support/rtf2latex
install bundle.)
rtf2latex2e: support/rtf2latex2e
tex4ht can also generate OpenOffice
ODT format, which may be used as an rtf2tex : support/rtf2tex
intermediate to producing Word for- tex2rtf : support/tex2rtf
mat files. tex4ht: obsolete/support/TeX4ht/
Word2TeX and TeX2Word are share- tex4ht-all.zip (but see
ware translators from Chikrii Softlab; http://tug.org/tex4ht/)
positive users’ reports have been noted
tr2latex : support/tr2latex
(but not recently).
If cost is a constraint, the best bet is wd2latex : support/wd2latex
probably to use an intermediate for- wp2latex : support/wp2latex
mat such as RTF or HTML. Word Word processor FAQ (source):
outputs and reads both, so in principle help/wp-conv
this route may be useful.
You can also use PDF as an intermedi- 103 Using TeX to read SGML or
ate format: Acrobat Reader for Win- XML directly
dows (version 5.0 and later) will out- ConTeXt (mark IV) can process some
put rather feeble RTF that Word can *ML, to produce typeset output directly.
read. Details of what can (and can not) be done,
Excel Excel2Latex converts an Excel file are discussed in The ConTeXt WIKI. Con-
into a LaTeX tabular environment; TeXt is probably the system of choice
it comes as a .xls file which defines for (La)TeX users who also need to work
some Excel macros to produce output in XML (and friends). (Note that Con-
in a new format. TeXt mark IV requires LuaTeX, and should
runoff Peter Vanroose’s rnototex conver- therefore be regarded as experimental,
sion program is written in VMS Pas- though many people do use it success-
cal. The sources are distributed with a fully).
VAX executable. Older systems also manage, using no
refer/tib There are a few programs for more than (La)TeX macro programming,
converting bibliographic data between to process XML and the like. David
BibTeX and refer/tib formats. The Carlisle’s xmltex is the prime example;
57
it offers a solution for typesetting XML one may convert to (La)TeX using one of
files, and is still in active (though not very the techniques discussed in “converting to
widespread) use. and from (La)TeX”.
One use of a TeX that can typeset XML The result will typically (at best) be
files is as a backend processor for XSL for- poorly marked-up. Problems may also
matting objects, serialized as XML. Se- arise from the oddity of typical TeX font
bastian Rahtz’s PassiveTeX uses xmltex to encodings (notably those of the maths
achieve this end. fonts), which Acrobat doesn’t know how
However, modern usage would pro- to map to its standard Unicode representa-
ceed via XSL or XSLT2 to produce a for- tion.
mattable version. catdvi: dviware/catdvi
Context: macros/context/current crudetype: dviware/crudetype
xmltex : macros/xmltex/base dvi2tty : dviware/dvi2tty
passivetex : macros/xmltex/ xpdf : Browse support/xpdf
contrib/passivetex
105 Translating LaTeX to Plain TeX
104 Retrieving (La)TeX from DVI, Unfortunately, no “general”, simple, auto-
etc. matic process is likely to succeed at this
The job just can’t be done automatically: task. See “How does LaTeX relate to Plain
DVI, PostScript and PDF are “final” for- TeX” for further details.
mats, supposedly not susceptible to fur- Obviously, trivial documents will trans-
ther editing — information about where late in a trivial way. Documents that use
things came from has been discarded. So if even relatively simple things, such as la-
you’ve lost your (La)TeX source (or never bels and references, are likely to cause
had the source of a document you need trouble (Plain TeX doesn’t support labels).
to work on) you’ve a serious job on your While graphics are in principle covered, by
hands. In many circumstances, the best the Plain TeX
strategy is to retype the whole document, Translating a document designed to
but this strategy is to be tempered by con- work with LaTeX into one that will
sideration of the size of the document and work with Plain TeX is likely to amount
the potential typists’ skills. to carefully including (or otherwise re-
implementing) all those parts of LaTeX,
If automatic assistance is necessary, it’s
beyond the provisions of Plain TeX, which
unlikely that any more than text retrieval is
the document uses.
going to be possible; the (La)TeX markup
Some of this work has (in a sense)
that creates the typographic effects of the
been done, in the port of the LaTeX graph-
document needs to be recreated by editing.
ics package to Plain TeX. However, while
If the file you have is in DVI for-
graphics is available, other complicated
mat, many of the techniques for converting
packages (notably hyperref ) are not. The
(La)TeX to ASCII are applicable. Con-
aspiring translator may find the Eplain sys-
sider dvi2tty, crudetype and catdvi. Re-
tem a useful source of code. (In fact, a
member that there are likely to be prob-
light-weight system such as Eplain might
lems finding included material (such as in-
reasonably be adopted as an alternative tar-
cluded PostScript figures, that don’t appear
get of translation, though it undoubtedly
in the DVI file itself), and mathematics is
gives the user more than the “bare mini-
unlikely to convert easily.
mum” that Plain TeX is designed to offer.)
To retrieve text from PostScript files,
the ps2ascii tool (part of the ghostscript The eplain system: macros/eplain
distribution) is available. One could try ’Plain TeX’ graphics:
applying this tool to PostScript derived macros/plain/graphics
from an PDF file using pdf2ps (also from
the ghostscript distribution), or Acrobat
Reader itself; an alternative is pdftotext, J Installing (La)TeX files
which is distributed with xpdf .
Another avenue available to those with 106 Installing things on a (La)TeX
a PDF file they want to process is offered system
by Adobe Acrobat (version 5 or later): you Installing (or replacing) things on your
can tag the PDF file into an estructured (La)TeX system has the potential to be
document, output thence to well-formed rather complicated; the following ques-
XHTML, and import the results into Mi- tions attempt to provide a step-by-step
crosoft Word (2000 or later). From there, approach, starting from the point where
58
you’ve decided what it is that you want to process package.ins with LaTeX, and
install: the files will appear, ready for installation.
Other sorts of provision should ordi-
• You must find the file you need; narily be accompanied by a README file,
• If you are going to install a LaTeX telling you what to do; we list a few exam-
package, you may need to unpack the ple configurations.
distributed files;
Sometimes, a directory comes with a
• It may be necessary to generate some
bunch of .dtx files, but fewer (often only
documentation to read;
one) .ins files (LaTeX itself comes look-
• You need to decide where to install the
ing like this). If there is more than one
files;
.ins file, and in the absence of any instruc-
• You must now install the files; and
tion in the README file, simply process the
finally
.ins file(s) one by one.
• You may need to tidy up after the in-
If you’re missing the package.ins
stallation.
altogether, you need to play around un-
107 Finding packages to install til something works. Some .dtx files
are “self-extracting” — they do without
How did you learn about the package?
an .ins file, and once you’ve processed
If the information came from these
the package.dtx, package.sty has au-
FAQs, you should already have a link to
tomagically appeared. Various other oddi-
the file (there are lists of packages at the
ties may appear, but the archivists aim to
end of each answer). Click on one of the
have README file in every package, which
links associated with the package, and you
should document anything out of the ordi-
can get the package (which may be one file
nary with the distribution.
or several).
If you heard about the file somewhere 109 Generating package
else, it’s possible that the source told documentation
you where to look; if not, try the CTAN
searching facilities, such as http://www. We are faced with a range of “normal” pro-
tex.ac.uk/search/. That (rather sim-
vision, as well as several oddities. One
ple) search engine can return data from a should note that documentation of many
search of the CTAN catalogue (which cov- packages is available on CTAN, with-
ers most useful packages), or data from a out the need of any further effort by the
search of the names of files on the archive. user — such documentation can usually be
Packages come in a variety of differ- browsed in situ.
ent styles of distribution; the very simplest However, if you find a package that
will actually offer just package.sty — in does not offer documentation on the
this case, just download the file and get on archive, or if you need the documentation
with installation. in some other format than the archive of-
You will regularly find that the file you fers, you can usually generate the docu-
want (e.g., foo.sty) is distributed in a La- mentation yourself from what you down-
TeX documented source file foo.dtx; thus load from the archive.
you should search just for foo — foo.sty The standard mechanism, for LaTeX
won’t be visible anywhere on the archive packages, is simply to run LaTeX on the
or in the catalogue. package.dtx file, as you would any ordi-
Since most packages are distributed in nary LaTeX file (i.e., repeatedly until the
this .dtx/.ins way, they usually occupy warnings go away).
their own directory on the archive. Even if A variant is that the unpacking pro-
that directory contains other packages, you cess provides a file package.drv; if such
should download everything in the direc- a thing appears, process it in preference
tory: as often as not, packages grouped in to the package.dtx (it seems that when
this way depend on each other, so that you the documented LaTeX source mechanism
really need the other ones. was first discussed, the .drv mechanism
Having acquired the package distribu- was suggested, but it’s not widely used
tion, “unpacking LaTeX packages” out- nowadays).
lines your next step. Sometimes, the LaTeX run will com-
plain that it can’t find package.ind (the
108 Unpacking LaTeX packages code line index) and/or package.gls (the
As discussed elsewhere, the ‘ordinary’ way list of change records, not as you might
to distribute a LaTeX package is as a pair imagine, a glossary). Both types of file
of files package.dtx and package.ins. are processed with special makeindex style
If you’ve acquired such a pair, you simply files; appropriate commands are:
59
 makeindex -s gind package 111 Which tree to use
makeindex -s gglo -o package.glsIn package.glo
almost all cases, new material that you
install should go into the “local” tree of
This author finds that the second (the
your (La)TeX installation. (A discussion
change record) is generally of limited util-
of reasons not to use the local tree appears
ity when reading package documentation;
below.)
it is, however, valuable if you’re part of the
On a Unix(-alike) system, using TeX
package development team. If you don’t
Live or teTeX, the root directory will
feel you need it, just leave out that step
be named something like /usr/share/
Another common (and reasonable)
texmf-local/ or /usr/local/share/
trick performed by package authors is to
texmf/ You can ask such a system where
provide a separate file package-doc.tex
it believes a local tree should be:
or even simply manual.tex; if the file
package.dtx doesn’t help, simply look kpsewhich -var-value TEXMFLOCAL
around for such alternatives. The files are
the output being the actual path, for exam-
treated in the same way as any “ordinary”
ple (on the workstation this author is using
LaTeX file.
today):
110 Installing files “where (La)TeX /usr/local/share/texmf
can find them”
In a MiKTeX installation, the location
In the past, package documentation used
will in fact typically be something you
always to tell you to put your files “where
specified yourself when you installed MiK-
LaTeX can find them”; this was always un-
TeX in the first place, but you may find you
helpful — if you knew where that was, you
need to create one. The MiKTeX “Settings”
didn’t need telling, but if you didn’t know,
window (Start→Programs→MiKTeX→
you were completely stuck.
Settings) has a tab “Roots”; that tab
It was from this issue that the whole
gives a list of current TDS roots (they’re
idea of the TDS sprang; “where to put”
typically not called texmf-anything). If
questions now come down to “where’s the
there’s not one there with “local” in its
TDS tree?”.
name, create an appropriate one (see be-
We therefore answer the question by
low), and register it using the window’s
considering:
“Add” button.
• what tree to use, and The MiKTeX FAQ suggests that you
• where in the tree to put the files. should create “C:\Local TeX Files”,
which is good if you manage your own
Once we know the answer to both ques- machine, but often not even possible in
tions, and we’ve created any directories corporate, or similar, environments — in
that are needed, we simply copy files to such situations, the user may have no con-
their rightful location. trol over the hard disc of the computer, at
This has done what the old requirement all.
specified: LaTeX (or whatever) can (in So the real criterion is that your local
principle) find the files. However, in order tree should be somewhere that you, rather
that the software will find the files, we need than the system, control. Restrictive sys-
to update an index file. tems often provide a “home directory” for
On a MiKTeX system, open the win- each user, mounted as a network drive; this
dow Start→All Programs→MiKTeX is a natural home for the user’s local tree.
hversioni→Settings, and click on Other (often academic) environments as-
Refresh FNDB. The job may also be done sume the user is going to provide a mem-
in a command window, using the com- ory stick, and will assign it a defined drive
mand: letter — another good candidate location.
Note that the semantics of such a tree are
initexmf --update-fndb indistinguishable from those of a “home”
TEXMF tree.
The MiKTeX documentation gives further
You might not wish to use the ‘local’
details about initexmf.
tree:
On a TeX Live-based system (or
its predecessor teTeX, use the com- • if the package, or whatever, is “per-
mand texhash (or if that’s not available, sonal” (for example, something com-
mktexlsr — they ought to be different mercial that has been licensed to you
names for the same program). alone, or something you’re developing
Having done all this, the new package yourself), it should go in your “home”
will be available for use. TEXMF tree;
60
 • if you know that the package you are In the lists above hformati identifies
installing is a replacement for the copy the format the macros are designed for —
on the TEXMF tree of your (La)TeX it can be things such as plain, generic
distribution; in this case it is reason- (i.e., any format), latex or context (or
able to replace the existing copy in the several less common formats).
TEXMF tree. For fonts, hfonti refers to the font fam-
ily (such as cm for Knuth’s Computer Mod-
If the system is upgraded (or otherwise ern, times for Adobe’s Times Roman).
re-installed), a copy made in the TEXMF The supplier is usually obvious — the sup-
tree will probably be overwritten or deleted. plier “public” is commonly used for free
This may be what you want, but otherwise fonts.
it’s a powerful incentive to use a tree that
The hsyntaxi (for .map and .enc files)
is not “part of the installed system”.
is a categorisation based on the way the
The reason one might place upgrades
files are written; candidates are names of
the distribution’s main tree is to avoid con-
programs such as dvips or pdftex.
fusion. Suppose you were to place the file
“Straight” (La)TeX input can take
on the local tree, and then install a new ver-
other forms than the .sty, .cls or .fd
sion of the distribution — you might have
listed above, too (apart from the ‘obvi-
an effect like:
ous’ .tex). Examples are (the obvious)
• distribution comes with package ver- .tex, .lfd for babel language definitions,
sion n; .sto and .clo for package and class op-
• you install package version n + 1 on tions, .cfg for configuration information,
the local tree; and .def for variants (such as the types of de-
• the updated distribution provides pack- vices graphics drives). The README of
age version n + 2. the package should tell you of any oth-
ers, though sometimes that information is
In such a situation, you could find yourself printed when the package’s comments are
using version n + 1 (from the local tree) af- stripped. All of these files should live to-
ter the new distribution has been installed. gether with the main package files.
If you install in the local tree, the only Note that hfonti may stand for a single
way to avoid such problems is to carefully font or an entire family: for example, files
purge the local tree when installing a new for all of Knuth’s Computer Modern fonts
distribution. This is tedious, if you’re main- are to be found in .../public/cm, with
taining a large installation. various prefixes as appropriate.
112 Where to install packages The font “supplier” public is a sort
of hold-all for “free fonts produced for
We assume here that you have decided
use with (La)TeX”: as well as Knuth’s
what tree to put your files in, after read-
fonts, public’s directory holds fonts de-
ing “choosing a TDS tree”. We will there-
signed by others (originally, but no longer
fore write $TEXMF for it, and you need to
exclusively, in Metafont).
substitute the tree you decided on.
Documentation for each package
The basic idea is to imitate the direc-
should all go, undifferentiated, into a di-
tory structure in your existing tree(s). Here
rectory on the doc/ subtree of the TDS.
are some examples of where various sorts
The layout of the subtree is slightly differ-
of files should go:
ent: doc/latex hosts all LaTeX documen-
.sty, .cls or .fd: $TEXMF/tex/<format>/<package>/
tation directories, but more fundamental
.mf: $TEXMF/fonts/source/<supplier>/<font>/
things are covered, e.g., by doc/etex or
.tfm: $TEXMF/fonts/tfm/<supplier>/<font>/
doc/xetex.
.vf: $TEXMF/fonts/vf/<supplier>/<font>/
.afm: $TEXMF/fonts/afm/<supplier>/<font>/
113 Tidying up after installation
.pfb: $TEXMF/fonts/type1/<supplier>/<font>/
.ttf:
There’s not usually a lot to do after you’ve
$TEXMF/fonts/truetype/<supplier>/<font>/
.otf:
completed the steps above — indeed, if
$TEXMF/fonts/opentype/<supplier>/<font>/
.pool,
you’re
.fmt, .base or .mem: $TEXMF/web2c
merely installed files direct from
the archive, or whatever, there will be pre-
and for modern systems (those distributed
cisely nothing left, by way of debris.
in 2005 or later, using TDS v1.1 layouts):
Things you might care to clean up are:
.map: $TEXMF/fonts/map/<syntax>/<bundle>/
.enc: $TEXMF/fonts/enc/<syntax>/<bundle>/ • the archive file, if you retrieved your
(Map and encoding files went to directories data from the archive as a .zip file, or
under $TEXMF/dvips/, in earlier distribu- the like;
tions.) • the .dtx and .ins files, if you chose
61
 not to install them with the documen- (which of course assumes you know the
tation; and name by which MiKTeX refers to your
• the .aux, .log, .idx, etc., from build- package).
ing the documentation. 116 Installation using TeX Live
manager
A simple way of achieving all this is to
download to a working directory that was TeX Live manager (tlmgr) is, by default, a
created for the purpose, and then to delete shell (or Windows terminal window) com-
that directory and all its contents after mand. There is voluminous documentation
you’ve finished installing. about it from the command
tldoc tlmgr
114 Shortcuts to installing files
but basic operation is pretty straightfor-
There are circumstances in which most of ward. The manager needs to know where
the fuss of installation can be bypassed: to download stuff from; the canonical setup
is
• If you are a MiKTeX user, the MiK-
TeX package management system can tlmgr option repository http://mirror.ctan.org/systems/
usually help; which passes the decision to the mirror se-
• Similarly, if you are a TeX Live user, lector. You can (of course) specify a par-
the TeX Live manager can usually ticular archive or mirror that you “trust”,
help; or even a local disc copy that you keep up-
• The package you want may already to-date (disc space and bandwidth are so
exist as a ZIP file formatted for direct cheap nowadays, that a “home mirror” of
installation. CTAN is a feasible proposition).
To update a single package, use:
115 Installation using MiKTeX
tlmgr update <package>
package manager
Packages for use with MiKTeX are main- To update everything you already have
tained very efficiently by the project man- in your installation, use:
agers (new packages and updates on CTAN tlmgr update --all
ordinarily make their way to the MiKTeX 117 Installing using ready-built ZIP
package repository within a week). Thus it files
makes sense for the MiKTeX user to take
advantage of the system rather than grind- Installing packages, as they (“tradition-
ing through the steps of installation. ally”) appear on CTAN, involves:
MiKTeX maintains a database of pack- • identifying where to put the various
ages it “knows about”, together with files on an TDS tree,
(coded) installation instructions that enable • installing them, and
it to install the packages with minimal user • a few housekeeping operations.
intervention; you can update the database Most people, for most packages, find the
over the internet. first two steps onerous, the last being easy
If MiKTeX does know about a pack- (unless it is forgotten!).
age you need installed, it’s worth using the Ready-built ZIP files — also known as
system: first, open the MiKTeX packages TDS-ZIP files — are designed to lighten
window: click on Start→Programs→ the load of performing the first two steps of
MiKTeX→MiKTeX Options, and select installation: they contain all the files that
the Packages tab. are to be installed for a given package, in
On the tab, there is an Explorer-style their “correct” locations in a TDS tree.
display of packages. Right-click on the To install such a file on a Unix system
root of the tree, “MiKTeX Packages”, and (we assume that you’ll install into the local
select “Search”: enter the name of the TEXMF tree, at $TEXMFLOCAL):
package you’re interested in, and press
cd $TEXMFLOCAL
the “Search” button. If MiKTeX knows
unzip $package.tds.zip
about your package, it will open up the tree
to show you a tick box for your package: On a Windows system that is modern
check that box. enough that it has a built-in ZIP unpacker,
If you prefer a command-line utility, simply double-click on the file, and browse
there’s mpm. Open a command shell, and to where it’s to be unpacked. (We trust
type: that those using earlier versions of Win-
dows will already have experience of using
mpm --install=<package> WinZIP or the like.)
62
 Having unpacked the .zip archive, in Note that in either sort of system, the
most cases the only remaining chore is to change will only affect instances of TeX
update the file indexes — as in normal that are started from the shell where the
installation instructions. However, if the environment variable was set. If you run
package provides a font, you also need to TeX from another window, it will use the
enable the font’s map, which is discussed original input path. To make a change of
in “Installing a Type 1 font” input path that will “stick” for all windows,
set the environment variable in your login
118 “Temporary” installation of
script or profile (or whatever) in a Unix
(La)TeX files
system and log out and in again, or in
Operating systems and applications need autoexec.bat in a Windows system, and
to know where to find files: many files reboot the system.
that they need are “just named” — the While all of the above has talked about
user doesn’t necessarily know where they where TeX finds its macro files, it’s appli-
are, but knows to ask for them. The com- cable to pretty much any sort of file any
monest case, of course, is the commands TeX-related program reads — there are
whose names you type to a shell (yes, even lots of these paths, and of their correspond-
Windows’ “MS-DOS prompt”) are using a ing environment variables. In a web2c-
shell to read what you type: many of the based system, the copious annotations in
commands simply involve loading and ex- the texmf.cnf system configuration file
ecuting a file, and the PATH variable tells help you to learn which path names corre-
the shell where to find those files. spond to which type of file.
Modern TeX implementations come
with a bunch of search paths built in to 119 “Private” installations of files
them. In most circumstances these pathsIt sometimes happens that you need a new
are adequate, but one sometimes needs version of some macro package or font,
to extend them to pick up files in strange
but that the machine you use is main-
places: for example, we may wish to try a
tained by someone who’s unwilling to up-
new bundle of packages before installing
date and won’t give you privileges to do
them ‘properly’. To do this, we need tothe job yourself. A “temporary” instal-
change the relevant path as TeX perceives
lation is sometimes the correct approach,
it. However, we don’t want to throw away
but if there’s the slightest chance that the
TeX’s built-in path (all of a sudden, TeX
installation will be needed on more than
won’t know how to deal with all sorts ofone project, temporary installations aren’t
things). right.
To extend a TeX path, we define an In circumstances where you have
operating system environment variable in
plenty of quota on backed-up media, or
‘path format’, but leaving a gap which TeX
adequate local scratch space, the correct
will fill with its built-in value for the path.
approach is to create a private installation
The commonest case is that we want to of (La)TeX which includes the new stuff
place our extension in front of the path, so
you need; this is the ideal, but is not gener-
that our new things will be chosen in pref-
ally possible.
erence, so we leave our ‘gap to be filled’ at
So, since you can’t install into the pub-
the end of the environment variable. The
lic texmf tree, you have to install into a
syntax is simple (though it depends which
texmf tree of your own; fortunately, the
shell you’re actually using): so on a Unix-
TDS standard allows for this, and mod-
like system, using the bash shell, the job
ern distributions allow you to do it. The
might be done like: most modern distributions refer to the tree
as $TEXMFHOME, but it used to be called
export TEXINPUTS=/tmp:
$HOMETEXMF; so to check that your TeX
while in a Windows system, within a MS- system does indeed support the mechanism
DOS window, it would be: you should start with

set TEXINPUTS=C:/temp; kpsewhich -var-value TEXMFHOME

In either case, we’re asking TeX to load (for example). This will almost invari-
files from the root disc temporary files di- ably return a pointer to a subdirectory
rectory; in the Unix case, the “empty slot” texmf of your home directory; the com-
is designated by putting the path separator monest exception is Macintoshes, using
‘:’ on its own at the end of the line, while MacTeX, where the diretory is convention-
in the Windows case, the technique is the ally Library/texmf in your home direc-
same, but the path separator is ‘;’. tory.
63
 If you can confirm that the technique it should be converted to:
does indeed work, install your new pack-
age (or whatever) in the correct place in a HOMETEXMF = $HOME/texmf
tree based on $HOME/texmf, and generate TEXMF = {$HOMETEXMF,!!$LOCALTEXMF,!!$TEXMFMAIN}
an index of that tree % TEXMF = {!!$LOCALTEXMF,!!$TEXMFMAIN}

texhash $HOME/texmf (retaining the original, as a comment, is

merely an aide-memoir in case you need to
(the argument specifies which tree you are make another change, later). The !! signs
indexing: it’s necessary since you don’t, by tell the file-searching library that it should
hypothesis, have access to the main tree, insist on a texhash-ed directory tree; if you
and texhash without the argument would can count on yourself remembering to run
try to write the main tree. texhash on your new tree every time you
There are two wrinkles to this simple change it, then it’s worth adding the marks
formula: first, the installation you’re using to your tree:
may not define a home TEXMF directory,
and second, there may be some obstruc- TEXMF = {!!$HOMETEXMF,!!$LOCALTEXMF,!!$TEXMFMAIN}
tion to using $HOME/texmf as the default
as this will make (La)TeX find its files
name. In either case, a good solution is
marginally faster.
to have your own texmf.cnf — an idea
Having made all these changes,
that sounds more frightening that it actu-
(La)TeX should “just use” files in your
ally is. The installation’s existing file may
new tree, in preference to anything in the
be located with the command:
main tree — you can use it for updates to
kpsewhich texmf.cnf packages in the main tree, as well as for
installing new versions of things.
Take a copy of the file and put it into a
directory of your own; this could be any di- 120 Installing a new font
rectory, but an obvious choice is the web2c Fonts are really “just another package”,
directory of the tree you want to create, i.e.,
and so should be installed in the same sort
$HOME/texmf/web2c or the like. Make an of way as packages. However, fonts tend
environment variable to point to this direc-to be more complicated than the average
tory: package, and as a result it’s sometimes dif-
ficult to see the overall structure.
TEXMFCNF=$HOME/texmf/web2c
Font files may appear in any of a
export TEXMFCNF
large number of different formats; each
(for a Bourne shell style system), or format has a different function in a TeX
system, and each is stored in a directory
setenv TEXMFCNF $HOME/texmf/web2c its own sub-tree in the installation’s TDS
tree; all these sub-trees have the directory
(for a C-shell style system). Now edit the
$TEXMF/fonts as their root. A sequence
copy of texmf.cnf
of answers, below, describes the installa-
There will be a line in the existing
tion of fonts. Other answers discuss spe-
file that defines the tree where everything
cific font families — for example, “using
searches; the simplest form of the line is:
the concrete fonts”.
TEXMF = !!$TEXMFMAIN 121 Installing a font provided as
but, there are likely to be several alter- Metafont source
native settings behind comment markers Installing Metafont fonts is (by comparison
(“%”), and the person who installed your with other sorts of font) rather pleasingly
system may have left them there. What- simple. Nowadays, they are mostly dis-
ever, you need to modify the line that’s in tributed just as the Metafont source, since
effect: change the above to three lines: modern TeX distributions are able to pro-
duce everything the user needs “on the fly”;
HOMETEXMF = $HOME/texmf however, if the distribution does include
TEXMF = {$HOMETEXMF,!!$TEXMFMAIN} TFM files, install them too, since they save
% TEXMF = !!$TEXMFMAIN a little time and don’t occupy much disc
the important point being that $HOMETEXMF space. Always distrust distributions of PK
must come before whatever was there be- font bitmap files: there’s no way of learn-
fore, inside the braces. For example, if the ing from them what printer they were gen-
original was erated for, and naming schemes under dif-
ferent operating systems are another source
TEXMF = {!!$LOCALTEXMF,!!$TEXMFMAIN} of confusion.
64
 “Where to install files” specifies where it in two chunks: first (in the present an-
the files should go. swer) preparing the font for installation,
Further confusion is introduced by font and second installing a Type 1 font).
families whose authors devise rules for au- Many fonts are supplied in (La)TeX
tomatic generation of Metafont sources for ready form: such fonts need no prepara-
generating fonts at particular sizes; the in- tion, and may be installed immediately.
stallation has to know about the rules, as However, if you purchase a font from
otherwise it cannot generate font files. No a Type foundry (either direct or via one of
general advice is available, but most such the web stores), you are likely to need to
font families are now obsolescent. ‘prepare’ it for use with (La)TeX. The rest
122 ‘Installing’ a PostScript printer of this answer discusses this preparation.
built-in font
• Acquire the font. A very small set
There is a “standard” set of fonts that has of Type 1 fonts is installed in most
appeared in every PostScript printer since PostScript printers you will encounter.
the second generation of the type. These For those few (whose use is covered
fonts (8 families of four text fonts each, by the basic PSNFSS package), you
and three special-purpose fonts) are of don’t need the Type 1 font itself, to be
course widely used, because of their sim- able to print using the font.
ple availability. The set consists of: For all the myriad other Type 1 fonts,
• Times family (4 fonts) to be able to print using the font you
• Palatino family (4 fonts) need the Type 1 file itself. Some of
• New Century Schoolbook family (4 these are available for free (they’ve
fonts) either been donated to the public do-
• Bookman family (4 fonts) main, or were developed as part of
• Helvetica family (4 fonts) a free software project), but the vast
• Avant Garde (4 fonts) majority are commercial products, re-
• Courier family (4 fonts) quiring you to spend real money.
• Utopia family (4 fonts) • Acquire the fonts’ AFM files. AFM
• Zapf Chancery (1 font) files contain information from the font
• Zapf Dingbats (1 font) foundry, about the sizes of the char-
• Symbol (1 font) acters in the font, and how they fit to-
gether. One measure of the quality of
All these fonts are supported, for LaTeX a font-supplier is that they provide the
users, by the psnfss set of metrics and AFM files by default: if the files are
support files in the file lw35nfss.zip on not available, you are unlikely to be
CTAN. Almost any remotely modern TeX able to use the font with (La)TeX.
system will have some version of psnfss • Rename the AFM files and the Type 1
installed, but users should note that the files to match the Berry font naming
most recent version has much improved scheme.
coverage of maths with Times (see package • Generate TeX metric files from the
mathptmx) and with Palatino (see package AFM files. The commonest tool for
mathpazo, as well as a more reliable set of this task is fontinst; the package docu-
font metrics. mentation helps, but other guides are
The archive lw35nfss.zip is laid out available (see below). The simplest
according to the TDS, so in principle, in- possible script to pass to fontinst is:
stallation consists simply of “unzipping”
\latinfamily{xyz}{}
the file at the root of a texmf tree.
\bye
Documentation of the psnfss bundle is
provided in psnfss2e.pdf in the distribu- where xyz is the Berry name of the
tion. font family. This simple script is
adequate for most purposes: its out-
mathpazo.sty : Part of the psnfss
put covers the font family in both T1
bundle
and OT1 font encodings. Neverthe-
mathptmx.sty : Part of the psnfss less, with fancier fonts, more elabo-
bundle rate things are possible with fontinst:
psnfss bundle: see its documentation for details.
macros/latex/required/psnfss Fontinst also generates map files, and
LaTeX font definition (.fd) files.
123 Preparing a Type 1 font
The process of installing a Type 1 font set Having traversed this list, you have a set
is rather convoluted, and we will deal with of font files ready for installation.
65
fontinst.sty : for each font family hfnamei you
fonts/utilities/fontinst are adding to the system. Now gen-
erate revised maps with the shell
Type 1 installation guide:
command
info/Type1fonts/
fontinstallationguide/ initexmf --mkmaps
fontinstallationguide.pdf
This, and other matters, are de-
124 Installing a Type 1 font scribed in MiKTeX “advanced”
documentation.
Once you have a prepared Type 1 font, ei-
ther direct from CTAN or the like, or hav-
ing ‘prepared’ it yourself, you can get on Both processes (preparing and installing
with installation. a font) are very well (and thoroughly)
The procedure is merely an extension described in Philipp Lehman’s guide to
of that for packages, etc., so much of what font installation, which may be found on
follows will be familiar: CTAN.
fontinst.sty :
• Install the files, in your local texmf fonts/utilities/fontinst
tree (the advice about installing non-
standard things applies here, too). The Type 1 installation guide:
following list gives reasonable desti- info/Type1fonts/
nations for the various files related to fontinstallationguide/
a font family hfnamei: fontinstallationguide.pdf
.pfb,
.pfa .../fonts/type1/<foundry>/<fname>
.tfm 125 Installing the Type 1 versions of
.../fonts/tfm/<foundry>/<fname>
.vf the CM fonts
.../fonts/vf/<foundry>/<fname>
.sty,
.fd .../tex/latex/<fname> This is a specialised case of installing a
.map font, but it is almost never necessary —
.../fonts/map/dvips/<foundry>
it’s inconceivable that any (even remotely)
but if you are lucky, you will be recent system will not have the fonts al-
starting from a distribution from ready installed. You can confirm this (near-
CTAN and there is a corresponding inevitable) fact by trying the fonts. On a
.tds.zip file: using this TDS-file system that uses dvips (almost all do), try
saves the bother of deciding where to the sequence:
put your files in the TDS tree.
• Regenerate the file indexes (as de-
scribed in package installation). latex sample2e
• Update the dvips, PDFTeX and other dvips -o sample2e.ps sample2e
maps:
– On any current TeX Live-based sys- at a “command prompt” (shell, in a Unix-
tem, or a teTeX v3.0 system, exe- style system, “DOS box” in a Windows
cute the command system).
updmap-sys --enable Map <fname>.map
If the command works at all, the con-
as root. (If you can use updmap- sole output of the command will include a
sys — do; if not — presumably be- sequence of Type 1 font file names, listed
cause your (La)TeX system was set as <path/cmr10.pfb> and so on; this is
up by someone else — you have dvips telling you it’s copying information
to fall back on plain updmap, but from the Type 1 font, and you need do no
be aware that it’s a potent source more.
of confusion, setting up map setsIf the test has failed, you need to in-
that might be changed behind your
stall your own set of the fonts; the distri-
back.) bution (including all the fonts the AMS
– On a current MiKTeX system, up-
designed and produced themselves) is now
date the system file updmap.cfg,
described as amsfonts. The bundle con-
using the shell command tains metric and map files — all you need
initexmf --edit-config-filetoupdmap
install the fonts.
adding a line at the end: AMS and CM fonts, in Type 1 format:
Map <fname>.map fonts/amsfonts
66
K Fonts 127 Previewing files using Type 1
fonts
K.1 Adobe Type 1 Originally, free TeX previewers were only
(“PostScript”) fonts capable of displaying bitmap (PK) fonts,
but free Type 1 font rendering software has
126 Using Adobe Type 1 fonts with
been available for some time, and many
TeX
previewers now use such facilities.
In order to use any font, TeX needs a met- The alternative, for previewers, is au-
ric file (TFM file). Several sets of metrics tomatic generation of the requisite PK
for common Adobe Type 1 fonts are avail- files (using gsftopk, or similar, behind the
able from the archives; for mechanisms scenes).
for generating new ones, see metrics for In the unlikely event that your pre-
PostScript fonts. You also need the fonts viewer isn’t capable of either, you have
themselves; PostScript printers come with a couple options:
a set of fonts built in, but to extend your
repertoire you usually need to buy from • Convert the DVI file to PostScript and
one of the many commercial font vendors use a PostScript previewer. Some sys-
(see, for example, “choice of fonts”). tems offer this capability as standard,
If you use LaTeX2e, access to your but most people will need to use a
printer’s fonts is offered by the PSNFSS separate previewer such as ghostscript
package; the LaTeX3 project team declare or ghostscript-based viewers such as
that PSNFSS is a “required” part of a (free) gv or (shareware) gsview.
LaTeX distribution, and bug reports may • If you have the PostScript fonts in
be submitted via the LaTeX bugs system. Type 1 format, use ps2pk or gsftopk
PSNFSS gives you a set of packages for (designed for use with the ghostscript
changing the default roman, sans-serif and fonts) to make PK bitmap fonts which
typewriter fonts; e.g., the mathptmx pack- your previewer will understand (a pro-
age will set up Times Roman as the main cess similar to the way some browsers
text font (and introduces mechanisms to fo the job ‘automatically’) This can
typeset mathematics using Times and var- produce adequate results, also suitable
ious more-or-less matching fonts), while for printing with non-PostScript de-
package avant changes the sans-serif fam- vices. (Note: if you purchased the
ily to AvantGarde, and courier changes fonts, it is advisable to check that their
the typewriter font to Courier. To go with licence permits you to convert them,
these packages, you need the font metric for private use, in this way.)
files and font description (.fd) files for
gsftopk : fonts/utilities/gsftopk
each font family you want to use. For
convenience, metrics for the ‘common 35’ gv : Browse support/gv
PostScript fonts found in most PostScript ps2pk : fonts/utilities/ps2pk
printers are provided with PSNFSS, pack-
aged as the “Laserwriter set”. 128 TeX font metric files for Type 1
For older versions of LaTeX there are fonts
various schemes, of which the simplest to
Reputable font vendors such as Adobe sup-
use is probably the PSLaTeX macros dis-
ply metric files for each font, in AFM
tributed with dvips. (Adobe Font Metric) form; these can be
For Plain TeX, you load whatever fonts
converted to TFM (TeX Font Metric) form.
you like; if the encoding of the fonts is not
Most modern distributions have prebuilt
the same as Computer Modern it will be up
metrics which will be more than enough
to you to redefine various macros and ac-
for many people; but you may need to do
cents, or you can use the font re-encoding
the conversion yourself if you have special
mechanisms available in many drivers and
needs or acquire a new font. One important
in ps2pk and afm2tfm. question is the encoding of (Latin charac-
Some common problems encountered ter) fonts; while we all more or less agree
are discussed elsewhere (see problemsabout the position of about 96 characters
with PS fonts). in fonts (the basic ASCII set), the rest of
the (typically) 256 vary. The most obvious
Metrics for the ‘Laserwriter’ set of 35 fonts:
macros/latex/required/psnfss/
problems are with floating accents and spe-
lw35nfss.zip
cial characters such as the ‘pounds sterling’
sign. There are three ways of dealing with
psnfss: this: either you change the TeX macros
macros/latex/required/psnfss which reference the characters (not much
67
fun, and error-prone); or you change the type 1 fonts.
encoding of the font (easier than you might Third, the stretch and shrink between
think); or you use virtual fonts to pretend words is a function of the font metric; it
to TeX that the encoding is the same as it is not specified in AFM files, so different
is used to. LaTeX2e has facilities for deal- converters choose different values. The
ing with fonts in different encodings; read PostScript metrics that come with PSNFSS
the LaTeX Companion for more details. In used to produce quite tight setting, but they
practice, if you do much non-English (but were revised in mid 1995 to produce a com-
Latin script) typesetting, you are strongly promise between American and European
recommended to use the fontenc package practice. Sophisticated users may not find
with option ‘T1’ to select ‘Cork’ encoding. even the new the values to their taste, and
An alternative favoured by some is want to override them. Even the casual
Y&Y’s “private” LY1 encoding, which is user may find more hyphenation or overfull
designed to sit well with “Adobe standard” boxes than Computer Modern produces;
encoded fonts. Basic macro support of but CM is extremely generous.
LY1 is available: note that the “relation 130 Choice of Type 1 fonts for
with Adobe’s encoding” means that the typesetting Maths
LY1 user needs no virtual fonts.
Alan Jeffrey’s fontinst package is an If you are interested in text alone, you can
AFM to TFM converter written in TeX; it in principle use any of the huge numbers
is used to generate the files used by La- of text fonts in Adobe Type 1, TrueType
TeX2e’s PSNFSS package to support use or OpenType formats. The constraint is,
of PostScript fonts. It is a sophisticated of course, that your previewer and printer
package, not for the faint-hearted, but is driver should support such fonts (TeX it-
powerful enough to cope with most needs. self only cares about metrics, not the actual
Much of its power relies on the use of vir- character programs).
tual fonts. If you also need mathematics, then
For slightly simpler problems, Ro- your choice is more limited, in particular
kicki’s afm2tfm, distributed with dvips, is by the demands that TeX makes of maths
fast and efficient; note that the metrics and fonts (for details, see the papers by B.K.P.
styles that come with dvips are not cur- Horn in TUGboat 14(3), or by Thierry
rently LaTeX2e compatible. Bouche in TUGboat 19(2)). There are sev-
For the Macintosh (classic), there is eral options available, which are based on
a program called EdMetrics which does Knuth’s original designs. Others comple-
the job (and more). EdMetrics comes with ment other commercial and free text font
the (commercial) Textures distribution, but designs; one set (MicroPress’s ‘informal
is itself free software, and is available on math’) stands alone.
CTAN. Users should also consider the possibil-
ities of typesetting maths using OpenType
dvips: dviware/dvips fonts.
EdMetrics: systems/mac/textures/ “Free” font families that will support
utilities/EdMetrics.sea.hqx TeX mathematics include:
fontinst: Computer Modern (75 fonts — optical
fonts/utilities/fontinst scaling) Donald E. Knuth
LY1 support: fonts/psfonts/ly1 The CM fonts were originally de-
signed in Metafont, but are also now
129 Deploying Type 1 fonts available in scalable outline form.
For the LaTeX user trying to use the There are commercial as well as pub-
PSNFSS package, three questions may lic domain versions, and there are both
arise. Adobe Type 1 and TrueType versions.
First, you have to declare to the DVI A set of outline versions of the fonts
driver that you are using PostScript fonts; was developed as a commercial ven-
in the case of dvips, this means adding ture by Y&Y and Blue Sky Research;
lines to the psfonts.map file, so that dvips they have since assigned the copyright
will know where the proper fonts are, and to the AMS, and the fonts are now
won’t try to find PK files. If the font isn’t freely available from CTAN. Their
built into the printer, you have to acquire quality is such that they have become
it (which may mean that you need to pur- the de facto standard for Type 1 ver-
chase the font files). sions of the fonts.
Second, your previewer must know AMS fonts (52 fonts, optical scaling) The
what to do with the fonts: see previewing AMS
68
 This set of fonts offers adjuncts to reports have suggested that these are
the CM set, including two sets of less successful, and their use may be
symbol fonts (msam and msbm) and suppressed when loading the fonts’
Euler text fonts. These are not a kpfonts LaTeX support package).
self-standing family, but merit dis- For an example, see http://www.
cussion here (not least because sev- tug.dk/FontCatalogue/kpserif/
eral other families mimic the symbol
MathDesign (3 free families, 3
fonts). Freely-available Type 1 ver-
commercial-based families. . . so far)
sions of the fonts are available on
Paul Pichaureau
CTAN. The eulervm package permits
This set so far offers mathematics
use of the Euler maths alphabet in con-
fonts to match the free fonts Adobe
junction with text fonts that do not pro-
Utopia, URW Garamond and Bit-
vide maths alphabets of their own (for
stream Charter (the text versions of all
instance, Adobe Palatino or Minion).
of which are separately available, on
Mathpazo version 1.003 (5 fonts) Diego CTAN, in Type 1 format), and Adobe
Puga Garamond Pro, Adobe UtopiaStd and
The Pazo Math fonts are a family ITC Charter (which are commercial
of type 1 fonts suitable for typeset- fonts, all available for purchase on
ting maths in combination with the the web). There has been a little com-
Palatino family of text fonts. Four of ment on these fonts, but none from
the five fonts of the distribution are actual users posted to the public fo-
maths alphabets, in upright and italic rums. Users, particularly those who
shapes, medium and bold weights; the are willing to discuss their experi-
fifth font contains a small selection of ences, would obviously be welcome.
“blackboard bold” characters (chosen Browse the CTAN directory and see
for their mathematical significance). which you want: there is a wealth of
Support under LaTeX2e is available documentation and examples.
in PSNFSS; the fonts are licensed un-
For samples of the free vari-
der the GPL, with legalese permitting
ants, see http://www.tug.dk/
the use of the fonts in published docu-
FontCatalogue/charter/ for
ments.
URW Charter, http://www.tug.
Fourier/Utopia (15 fonts) Michel Bovani dk/FontCatalogue/garamond/ for
Fourier is a family built on Adobe URW Garamond and http://www.
Utopia (which has been released for tug.dk/FontCatalogue/utopia-
usage free of charge by Adobe). The md/ for Adobe Utopia.
fonts provide the basic Computer
Belleek (3 fonts) Richard Kinch
Modern set of mathematical symbols,
Belleek is the upshot of Kinch’s
and add many of the AMS mathemati-
thoughts on how Metafont might be
cal symbols (though you are expected
used in the future: they were pub-
to use some from the AMS fonts them-
lished simultaneously as Metafont
selves). There are also several other
source, as Type 1 fonts, and as True-
mathematical and decorative symbols.
Type fonts. The fonts act as “drop-in”
The fonts come with a fourier pack-
replacements for the basic MathTime
age for use with LaTeX; text support
set (as an example of “what might be
of OT1 encoding is not provided —
done”).
you are expected to use T1.
The paper outlining Kinch’s thoughts,
For a sample, see http://www.tug.
proceeding from considerations of the
dk/FontCatalogue/utopia/
‘intellectual’ superiority of Metafont
Fourier/New Century Schoolbook to evaluations of why its adoption is so
Michael Zedler limited and what might be done about
Fouriernc is a configuration using the the problem, is to be found at http:
Fourier fonts in the context of New //truetex.com/belleek.pdf
Century Schoolbook text fonts.
MTPro2 Lite Pubish or Perish (Michael
For a sample, see http://www.tug. Spivak)
dk/FontCatalogue/newcent/ A (functional) subset of the MathTime
KP-fonts The Johannes Kepler project Pro 2 font set, that is made available,
The kp-fonts family provides a com- free, for general use. While it does not
prehensive set of text and maths fonts. offer the full power of the commercial
The set includes replacement fixed- product (see below), it is nevertheless
width and sans fonts (though some a desirable font set.
69
Mathptmx Alan Jeffrey, Walter Schmidt For further details (including
and others. samples) see
This set contains maths italic, symbol, http://www.micropress-inc.
extension, and roman virtual fonts, com/fonts/bamath/bamain.htm
built from Adobe Times, Symbol, CH Math (15 fonts) MicroPress Inc.
Zapf Chancery, and the Computer CH Math is a family of slab
Modern fonts. The resulting mix- serif fonts, designed as a maths
ture is not entirely acceptable, but can companion for Bitstream Charter.
pass in many circumstances. The real (The distribution includes four free
advantage is that the mathptm fonts Bitstream text fonts, in addition
are (effectively) free, and the result- to the 15 hand-hinted MicroPress
ing PostScript files can be freely ex- fonts.) For further details (including
changed. Support under LaTeX2e is samples) see
available in PSNFSS. http://www.micropress-inc.
For a sample, see http://www.tug. com/fonts/chmath/chmain.htm
dk/FontCatalogue/times/ Computer Modern Bright (62 fonts — op-
Computer Modern Bright Free scalable tical scaling) Walter Schmidt
outline versions of these fonts do ex- CM Bright is a family of sans serif
ist; they are covered below together fonts, based on Knuth’s CM fonts.
with their commercial parallels. It comprises the fonts necessary for
URW Classico (4 fonts) LaTeX support mathematical typesetting, including
by Bob Tennent AMS symbols, as well as text and
These are clones of Zapf’s Op- text symbol fonts of various shapes.
tima available from CTAN (for non- The collection comes with its own set
commercial use only). Mathematics of files for use with LaTeX. The CM
support can be provided by using pack- Bright fonts are supplied in Type 1 for-
ages eulervm or sansmath. As a sans- mat by MicroPress, Inc. The hfbright
serif font family, Optima is especially bundle offers free Type 1 fonts for
suitable for presentations. text using the OT1 encoding — the
cm-super fonts provide the fonts in T1
The excellent font catalogue keeps an up- text encoding but don’t support CM
to-date list which describes the fonts by bright mathematics.
giving names and short examples, only.
(At the time of writing — June 2008 — For further details of Micropress’
the list has several that are only scheduled offering (including samples) see
http://www.micropress-inc.
for inclusion here.
com/fonts/brmath/brmain.htm
Another useful document is Stephen
Hartke’s “Free maths font survey”, which Concrete Math (25 fonts — optical scal-
is available on CTAN in both PDF and ing) Ulrik Vieth
HTML formats. The survey covers most of The Concrete Math font set was de-
the fonts mentioned in the font catalogue, rived from the Concrete Roman type-
but also mentions some (such as Belleek faces designed by Knuth. The set pro-
that the catalogue omits. vides a collection of math italics, math
Fonts capable of setting TeX mathe- symbol, and math extension fonts, and
matics, that are available commercially, in- fonts of AMS symbols that fit with the
clude: Concrete set, so that Concrete may be
used as a complete replacement for
BA Math (13 fonts) MicroPress Inc.
Computer Modern. Since Concrete is
BA Math is a family of serif fonts,
considerably darker than CM, the fam-
inspired by the elegant and graph-
ily may particularly attractive for use
ically perfect font design of John
in low-resolution printing or in appli-
Baskerville. BA Math comprises the
cations such as posters or transparen-
fonts necessary for mathematical type-
cies. Concrete Math fonts, as well as
setting (maths italic, math symbols
Concrete Roman fonts, are supplied
and extensions) in normal and bold
in Type 1 format by MicroPress, Inc.
weights. The family also includes all
OT1 and T1 encoded text fonts of vari- For further information (including
ous shapes, as well as fonts with most samples) see
useful glyphs of the TS1 encoding. http://www.micropress-inc.
Macros for using the fonts with Plain com/fonts/ccmath/ccmain.htm
TeX, LaTeX 2.09 and current LaTeX HV Math (14 fonts) MicroPress Inc.
are provided. HV Math is a family of sans serif
70
 fonts, inspired by the Helvetica (TM) Adobe Lucida, LucidaSans and LucidaMath
typeface. HV Math comprises the (12 fonts)
fonts necessary for mathematical type- Lucida and LucidaMath are generally
setting (maths italic, maths symbols considered to be a bit heavy. The three
and extensions) in normal and bold maths fonts contain only the glyphs
weights. The family also includes all in the CM maths italic, symbol, and
OT1 and T1 encoded text fonts of vari- extension fonts. Support for using Lu-
ous shapes, as well as fonts with most cidaMath with TeX is not very good;
useful glyphs of the TS1 encoding. you will need to do some work reen-
Macros for using the fonts with Plain coding fonts etc. (In some sense this
TeX, LaTeX 2.09 and current LaTeX set is the ancestor of the LucidaBright
are provided. Bitmapped copies of the plus LucidaNewMath font set, which
fonts are available free, on CTAN. are not currently available.)
For further details (and samples) MathTime Pro2 Publish or Perish
see (Michael Spivak)
http://www.micropress-inc. This latest instance of the MathTime
com/fonts/hvmath/hvmain.htm family covers all the weights (medium,
Informal Math (7 outline fonts) Micro- bold and heavy) and symbols of pre-
Press Inc. vious versions of MathTime. In addi-
Informal Math is a family of fanciful tion it has a much extended range of
fonts loosely based on the Adobe’s symbols, and many typographic im-
Tekton (TM) family, fonts which imi- provements that make for high-quality
tate handwritten text. Informal Math documents. The fonts are supported
comprises the fonts necessary for under both Plain TeX and LaTeX2e,
mathematical typesetting (maths italic, and are exclusively available for pur-
maths symbols and extensions) in chase from Personal TeX Inc.
normal weight, as well as OT1 en- For further details and sam-
coded text fonts in upright and oblique ples and fliers, see http:
shapes. Macros for using the fonts //www.pctex.com/mtpro2.html
with Plain TeX, LaTeX 2.09 and cur- Minion Pro and MnSymbol Adobe, La-
rent LaTeX are provided. TeX support and packaging by Achim
For further details (including Blumensath et al.
samples) see Minion Pro derives from the widely-
http://www.micropress-inc. available commercial OpenType font
com/fonts/ifmath/ifmain.htm of the same name by Adobe; scripts
Lucida Bright with Lucida New Math are provided to convert relevant
(25 fonts) Chuck Bigelow and Kris parts of it to Adobe Type 1 for-
Holmes mat. The MinionPro package will
Lucida is a family of related fonts set up text and maths support using
including seriffed, sans serif, sans Minion Pro, but a separate (free) font
serif fixed width, calligraphic, black- set MnSymbol greatly extends the
letter, fax, Kris Holmes’ connected symbol coverage.
handwriting font, etc; they’re not as PA Math PA Math is a family of serif
‘spindly’ as Computer Modern, with a fonts loosely based on the Palatino
large x-height, and include a larger set (TM) typeface. PA Math comprises
of maths symbols, operators, relations the fonts necessary for mathematical
and delimiters than CM (over 800 typesetting (maths italics, maths, calli-
instead of 384: among others, it also graphic and oldstyle symbols, and ex-
includes the AMS msam and msbm tensions) in normal and bold weights.
symbol sets). ‘Lucida Bright Expert’ The family also includes all OT1, T1
(14 fonts) adds seriffed fixed width, encoded text fonts of various shapes,
another handwriting font, smallcaps, as well as fonts with the most useful
bold maths, upright ‘maths italic’, etc., glyphs of the TS1 encoding. Macros
to the set. Support under LaTeX is for using the fonts with Plain TeX, La-
available under the auspices of the TeX 2.09 and current LaTeX are pro-
PSNFSS, and pre-built metrics are vided.
also provided. For further details (and samples)
TUG has the right to distribute see
these fonts; the web site “Lucida http://www.micropress-inc.
and TUG” has details. com/fonts/pamath/pamain.htm
71
TM Math (14 fonts) MicroPress Inc. The fonts are licensed under the GPL;
TM Math is a family of serif fonts, in- use in published documents is permit-
spired by the Times (TM) typeface. ted.
TM Math comprises the fonts nec- Newpx by Michael Sharpe from Young
essary for mathematical typesetting Ryu’s pxfonts
(maths italic, maths symbols and ex- This collection is derived from
tensions) in normal and bold weights. pxfonts; the maths fonts metrics have
The family also includes all OT1 been adjusted so that the output is less
and T1 encoded text fonts of various cramped than when pxfonts is used;
shapes, as well as fonts with most the appearance of the output is much
useful glyphs of the TS1 encoding. improved. Two packages are provided,
Macros for using the fonts with Plain newpxtext for using the associated text
TeX, LaTeX 2.09 and current LaTeX fonts, and newpxmath for mathemat-
are provided. Bitmapped copies of the ics.
fonts are available free, on CTAN.
Txfonts set version 3.1 (42 fonts) by
For further details (and samples)
Young Ryu
see
The txfonts set consists of
http://www.micropress-inc.
com/fonts/tmmath/tmmain.htm • virtual text fonts using
Adobe Times (or the URW
Two other font sets should be mentioned,
Nimbus Roman No9 L font that
even though they don’t currently produce
substitutes for Times, which is dis-
satisfactory output — their author is no
tributed as part of the URW “basic
longer working on them, and several prob-
35” collection) with modified plus,
lems have been identified:
equal and slash symbols;
Pxfonts set version 1.0 (26 fonts) by • matching sets of sans serif and
Young Ryu monospace (‘typewriter’) fonts
The pxfonts set consists of (the sans serif set is based on Adobe
Helvetica);
• virtual text fonts using Adobe • maths alphabets using Adobe
Palatino (or its URW replacement, Times, or the URW equivalent
Palladio) with modified plus, equal NimbusRomanNo9;
and slash symbols; • maths fonts of all symbols in
• maths alphabets using Palatino (or the computer modern maths fonts
Palladio; (cmsy, cmmi, cmex and the Greek
• maths fonts of all symbols in letters of cmr)
the computer modern maths fonts • maths fonts of all symbols corre-
(cmsy, cmmi, cmex and the Greek sponding to the AMS fonts (msam
letters of cmr) and msbm);
• maths fonts of all symbols corre- • additional maths fonts of various
sponding to the AMS fonts (msam symbols.
and msbm);
• additional maths fonts of various The text fonts are available in OT1, T1
symbols. and LY1 encodings, and TS encoded
symbols are also available.
The text fonts are available in OT1, T1
The fonts are not perfect; the widths
and LY1 encodings, and TS encoded
assigned to the characters in the .tfm
symbols are also available. The sans
file are wrong for some glyphs; this
serif and monospaced fonts supplied
can cause sequences of characters to
with the txfonts set (see below) may
“look wrong”, or in some cases even to
be used with pxfonts; the txfonts set
overlap; the newtx fonts (noted above)
should be installed whenever pxfonts
aim to reduce these problems.
are. LaTeX, dvips and PDFTeX sup-
port files are included. The fonts are licensed under the GPL;
The fonts are not perfect; the widths use in published documents is permit-
assigned to the characters in the .tfm ted.
file are wrong for some glyphs; this Txfontsb set version 1.00 by Young Ryu
can cause sequences of characters to and Antonis Tsolomitis
“look wrong”, or in some cases even to The txfontsb bundles txfonts, extended
overlap; the newpx fonts (noted above) to provide a Small Caps set, Old-Style
aim to reduce these problems. numbers and Greek text (from the
72
 GNU Freefont set). Documentation Modern and Times Maths fonts to render
is available for this variant, too. TeX documents in Windows without the
Newtx by Michael Sharpe from Young need for additional system software like
Ryu’s txfonts ATM. (When used on a system running
This collection is derived from txfonts; Windows XP or later, TrueTeX can also
the maths fonts metrics have been use Adobe Type 1 fonts.)
adjusted so that the output is less When choosing fonts, your own sys-
cramped than when txfonts is used; the tem environment may not be the only one
appearance of the output is much im- of interest. If you will be sending your
proved. Two packages are provided, finished documents to others for further
newtxtext for using the associated text use, you should consider whether a given
fonts, and newtxmath for mathematics. font format will introduce compatibility
Options are provided to substitute let- problems. Publishers may require True-
ters and symbols from the Libertine Type exclusively because their systems are
set, and from the Garamond exten- Windows-based, or Type 1 exclusively, be-
sion font garamondx (but note that cause their systems are based on the early
garamondx, which is an adaptation of popularity of that format in the publishing
URW Garamond, is not available via industry. Many service bureaus don’t care
TeX Live). as long as you present them with a finished
print file (PostScript or PDF) for their out-
Finally, one must not forget: put device.
CM family collection: Distributed as
Proprietary fonts Various sources.
part of fonts/amsfonts
Since having a high quality font set in
scalable outline form that works with AMS font collection: Distributed as part
TeX can give a publisher a real com- of fonts/amsfonts
petitive advantage, there are some pub- Belleek fonts: fonts/belleek
lishers that have paid (a lot) to have
URW Classico fonts:
such font sets made for them. Unfor-
fonts/urw/classico
tunately, these sets are not available
on the open market, despite the likeli- CM-super collection:
hood that they’re more complete than fonts/ps-type1/cm-super
those that are. eulervm.sty and supporting metrics:
fonts/eulervm
We observe a very limited selection of com-
mercial maths font sets; a Type 1 maths fourier (including metrics and other support for utopia:
font has to be explicitly designed for use fonts/fourier-GUT
with TeX, which is an expensive business, fouriernc: fonts/fouriernc
and is of little appeal in other markets. Fur-
garamondx : fonts/garamondx
thermore, the TeX market for commercial
fonts is minute by comparison with the hfbright collection:
huge sales of other font sets. fonts/ps-type1/hfbright
Text fonts in Type 1 format are avail- hvmath (free bitmapped version):
able from many vendors including Adobe, fonts/micropress/hvmath
Monotype and Bitstream. However, be
kpfonts family: fonts/kpfonts
careful with cheap font “collections”;
many of them dodge copyright restrictions Libertine family: fonts/libertine
by removing (or crippling) parts of the font Lucida Bright/Math metrics:
programs such as hinting. Such behaviour fonts/psfonts/bh/lucida
is both unethical and bad for the consumer.
Lucida PSNFSS support:
The fonts may not render well (or at all,
macros/latex/contrib/psnfssx/
under ATM), may not have the ‘standard’
lucidabr
complement of 228 glyphs, or may not in-
clude metric files (which you need to make MathDesign collection:
TFM files). fonts/mathdesign
TrueType was for a long time the “na- Maths Font Survey: info/Free_Math_
tive” format for Windows, but MicroSoft Font_Survey/en/survey.pdf
joined the development of the OpenType (PDF) or info/Free_Math_Font_
specification, and ‘modern’ windows will Survey/en/survey.html (HTML)
work happily with fonts in either format.
Some TeX implementations such as True- MathTime Pro 2 Lite: fonts/mtp2lite
TeX use TrueType versions of Computer Minion Pro support: fonts/minionpro
73
MnSymbol family: fonts/mnsymbol the fontspec package) does the essential
Newtx fonts: fonts/newtx groundwork.
NimbusRomanNo9 fonts: distributed in Asana-Math font: fonts/Asana-Math
fonts/urw/base35 fontspec.sty :
Palladio fonts: distributed in macros/latex/contrib/fontspec
fonts/urw/base35 lm-math fonts: fonts/lm-math
pxfonts: fonts/pxfonts STIX fonts: fonts/stix
sansmath.sty : unicode-math.sty :
macros/latex/contrib/sansmath macros/latex/contrib/unicode-
tmmath (free bitmapped version): math
fonts/micropress/tmmath tex-gyre-math-pagella font:
txfonts: fonts/txfonts distributed as part of
fonts/tex-gyre-math
URW “35 fonts” collection:
fonts/urw/base35 tex-gyre-math-termes font:
utopia fonts: fonts/utopia
distributed as part of
fonts/tex-gyre-math
131 Unicode Maths using OpenType
XITS fonts: fonts/xits
fonts
The ISO standard Universal Coding 132 Weird characters in dvips output
Scheme (UCS), which is commonly known You’ve innocently generated output, us-
as Unicode, was adopted early by the de- ing dvips, and there are weird transposi-
signers of TrueType (TTF) and OpenType tions in it: for example, the fi ligature
(OTF) fonts. The flexibility of the fonts has appeared as a £ symbol. This is an
offers hope, for the first time, of a uniform unwanted side-effect of the precautions
method for typesetting essentially any lan- outlined in generating PostScript for PDF.
guage. The -G1 switch discussed in that question
TeX users have been eagerly adopt- is appropriate for Knuth’s text fonts, but
ing the fonts, for some time, using XeTeX doesn’t work with text fonts that don’t fol-
(now a rather stable system) and LuaTeX low Knuth’s patterns (such as fonts sup-
(which is, at the time of writing, still being plied by Adobe).
developed). If the problem arises, suppress the -G1
While TeX users were investigating switch: if you were using it explicitly,
the use of these text fonts, ISO was ex- don’t; if you were using -Ppdf, add -G0 to
tending Unicode to provide a means of suppress the implicit switch in the pseudo-
expressing mathematics. As this work printer file.
proceeded, MicroSoft and (separately) a The problem has been corrected in
consortium of publishing companies were dvips v 5.90 (and later versions); it is un-
developing OpenType maths fonts. (Mi- likely ever to recur. . .
crosoft contributed on the development
of the concepts, within the ISO pro- K.2 Macros for using fonts
cess.) MicroSoft’s OpenType Maths font, 133 Using non-standard fonts in
Cambria Math has been available for pur- Plain TeX
chase for some time.
The first free OpenType Maths font to Plain TeX (in accordance with its descrip-
appear was Asana Math, which was even- tion) doesn’t do anything fancy with fonts:
tually followed by the publishers’ consor- it sets up the fonts that Knuth found he
tium’s offer of an interim version of their needed when writing the package, and
font, STIX, which has been redeveloped to leaves you to do the rest.
provide a more usable whole, XITS, by a To use something other than Knuth’s
group of TeX users. default, you can use Knuth’s mechanism,
Other fonts are appearing, including the \font primitive:
TeX Gyre Termes Math (based on Times- \font\foo=nonstdfont
like fonts) and Tex Gyre Pagella Math ...
(based on Palatino-like fonts), and \foo
LM Math extending the OpenType ver- Text set using nonstdfont ...
sion of the Latin Modern font family.
Actually using a unicode maths font is The name you use (nonstdfont, above) is
quite a complicated business, but the La- the name of the .tfm file for the font you
TeX package unicode-math (supported by want.
74
 If you want to use an italic version of for T1.
\foo, you need to use \font again: Ofs seems to be the most thoroughly
thought-through of the alternatives, and
\font\fooi=nonstdfont-italic can select more than one encoding: as well
... as T1 it covers the encoding IL2, which is
\fooi favoured in the Czech Republic and Slo-
Text set using nonstdfont italic... vakia. Ofs also covers mathematical fonts,
allowing you the dubious pleasure of using
This is all very elementary stuff, and serves
fonts such as the pxfonts and txfonts.
for simple use of fonts. However, there are
The pdcmac Plain TeX macro package
wrinkles, the most important of which is
aims to be a complete document prepa-
the matter of font encodings. One almost
ration environment, like Eplain. One of
never sees new fonts that use Knuth’s ec-
its components is a font selection scheme,
centric font encodings — but those encod-
pdcfsel, which is rather simple but ade-
ings are built into Plain TeX, so that some
quately powerful for many uses. The pack-
macros of Plain TeX need to be changed
age doesn’t preload fonts: the user is re-
to use the fonts. LaTeX gets around all
quired to declare the fonts the document
these problems by using a “font selection
is going to use, and the package provides
scheme” — this ‘NFSS’ (‘N’ for ‘new’,
commands to select fonts as they’re needed.
as opposed to what LaTeX 2.09 had) car-
The distribution includes a configuration to
ries around with it separate information
use Adobe ‘standard’ fonts for typesetting
about the fonts you use, so the changes to
text. (Eplain itself seems not to offer a font
encoding-specific commands happen au-
selection scheme.)
tomagically.
The font-change collection takes a
If you only want to use the EC fonts, rather different approach — it supplies
you can in principle use the ec-plain bun- what are (in effect) a series of templates
dle, which gives you a version of Plain that may be included in a document to
TeX which you can run in the same way change font usage. The package’s docu-
that you run Plain TeX using the original mentation shows the effect rather well.
CM fonts, by invoking tex. (Ec-plain also Simply to change font size in a docu-
extends the EC fonts, for reasons which ment (i.e., not changing the default font it-
aren’t immediately clear, but which might self), may be done using the rather straight-
cause problems if you’re hoping to use forward varisize, which offers font sizes
Type 1 versions of the fonts.) ranging from 7 points to 20 points (nom-
The font_selection package provides a inal sizes, all). Font size commands are
sort of halfway house: it provides font face generated when any of the package files
and size, but not family selection. This is loaded, so the 11pt.tex defines a com-
gives you considerable freedom, but leaves mand \elevenpoint; each of the files en-
you stuck with the original CM fonts. It’s sures there’s a “way back”, by defining a
a compact solution, within its restrictions. \tenpoint command.
Other Plain TeX approaches to the
problem (packages plnfss, fontch and ofs) ec-plain: macros/ec-plain
break out of the Plain TeX model, towards font-change:
the sort of font selection provided by Con- macros/plain/contrib/font-
TeXt and LaTeX — font selection that al- change
lows you to change family, as well as size fontch:
and face. The remaining packages all make macros/plain/contrib/fontch
provision for using encodings other than
font_selection: macros/plain/
Knuth’s OT1.
contrib/font_selection
Plnfss has a rather basic set of font fam-
ily details; however, it is capable of using ofs: macros/generic/ofs
font description (.fd) files created for La- pdcmac:
TeX. (This is useful, since most modern macros/plain/contrib/pdcmac
mechanisms for integrating outline fonts plnfss: macros/plain/plnfss
with TeX generate .fd files in their pro-
varisize:
cess.)
macros/plain/contrib/varisize
Fontch has special provision for T1 and
TS1 encodings, which you select by arcane K.3 Particular font families
commands, such as:
134 Using the “Concrete” fonts
\let\LMTone\relax The Concrete Roman fonts were designed
\input fontch.tex by Don Knuth for a book called “Con-
75
crete Mathematics”, which he wrote with CM-Super fonts:
Graham and Patashnik (the Patashnik, of fonts/ps-type1/cm-super
BibTeX fame). Knuth only designed text
concmath.sty :
fonts, since the book used the Euler fonts
macros/latex/contrib/concmath
for mathematics. The book was typeset
using Plain TeX, of course, with addi- Concmath fonts: fonts/concmath
tional macros that may be viewed in a file Concrete fonts: fonts/concrete
gkpmac.tex, which is available on CTAN.
The packages beton, concmath, and euler.sty :
ccfonts are LaTeX packages that change macros/latex/contrib/euler
the default text fonts from Computer Mod- eulervm bundle: fonts/eulervm
ern to Concrete. Packages beton and
gkpmac.tex : systems/knuth/local/
ccfonts also slightly increase the default
lib/gkpmac.tex
value of \baselineskip to account for
the rather heavier weight of the Concrete 135 Using the Latin Modern fonts
fonts. If you wish to use the Euler fonts
for mathematics, as Knuth did, there’s the The lm fonts are an exciting addition to the
euler package which has been developed armoury of the (La)TeX user: high quality
from Knuth’s own Plain TeX-based set: outlines of fonts that were until recently
these macros are currently deprecated (they difficult to obtain, all in a free and rel-
clash with many things, including AM- atively compact package. However, the
SLaTeX). The independently-developed spartan information file that comes with
eulervm bundle is therefore preferred to the fonts remarks “It is presumed that a
the euler package. (Note that installing the potential user knows what to do with all
eulervm bundle involves installing a series these files”. This answer aims to fill in the
of virtual fonts. While most modern dis- requirements: the job is really not terribly
tributions seem to have the requisite files difficult.
installed by default, you may find you have Note that teTeX distributions, from ver-
to install them. If so, see the file readme sion 3.0, already have the lm fonts: all you
in the eulervm distribution.) need do is use them. The fonts may also
A few years after Knuth’s original de- be installed via the package manager, in a
sign, Ulrik Vieth designed the Concrete current MiKTeX system. The remainder of
Math fonts. Packages concmath, and this answer, then, is for people who don’t
ccfonts also change the default math fonts use such systems.
from Computer Modern to Concrete and The font (and related) files appear on
use the Concrete versions of the AMS fonts CTAN as a set of single-entry TDS trees —
(this last behaviour is optional in the case fonts, dvips, tex and doc. The doc sub-
of the concmath package). tree really need not be copied (it’s really
There are no bold Concrete fonts, but a pair of sample files), but copy the other
it is generally accepted that the Computer three into your existing Local $TEXMF tree,
Modern Sans Serif demibold condensed and update the filename database.
fonts are an adequate substitute. If you are Now, incorporate the fonts in the
using concmath or ccfonts and you want to set searched by PDFLaTeX, dvips,
follow this suggestion, then use the pack- dvipdfm/dvipdfmx, your previewers and
age with boldsans class option (in spite Type 1-to-PK conversion programs, by
of the fact that the concmath documenta-
tion calls it sansbold class option). If you • On a teTeX system earlier than ver-
are using beton, add sion 2.0, edit the file $TEXMF/dvips/
config/updmap and insert an abso-
\renewcommand{\bfdefault} lute path for the lm.map just after
{sbc} the line that starts extra_modules="
to the preamble of your document. (and before the closing quotes).
Type 1 versions of the fonts are avail- • On a teTeX version 2.0 (or later), exe-
able. For OT1 encoding, they are available cute the command
from MicroPress. The CM-Super fonts updmap --enable Map lm.map
contain Type 1 versions of the Concrete
fonts in T1 encoding. • On a MiKTeX system earlier than
version 2.2, the “Refresh filename
beton.sty : database” operation, which you per-
macros/latex/contrib/beton formed after installing files, also up-
ccfonts.sty : dates the system’s “PostScript re-
macros/latex/contrib/ccfonts sources database”.
76
 • On a MiKTeX system, version 2.2 their .zip file, install them and update the
or later, update updmap.cfg as de- font maps. It even goes so far as to apolo-
scribed in the MiKTeX online doc- gise for how long it’s taking!
umentation. Then execute the com-
mand initexmf --mkmaps, and the K.4 Metafont fonts
job is done. 137 Getting Metafont to do what you
want
To use the fonts in a LaTeX document,
you should Metafont allows you to create your own
fonts, and most TeX users will never need
\usepackage{lmodern} to use it — modern (La)TeX systems con-
this will make the fonts the default for all tain rather few Metafont fonts of any sig-
three LaTeX font families (“roman”, “sans- nificance, and when Metafont output is
serif” and “typewriter”). You also need needed the font generation is done, auto-
matically, “on the fly”.
\usepackage[T1]{fontenc} If you find you have some special
requirement that the system doesn’t sat-
for text, and isfy, you need to know about Metafont
\usepackage{textcomp} in rather more detail. Metafont, unlike
TeX, requires customisation for each out-
if you want to use any of the TS1-encoding put device: such customisation is con-
symbols. There is no support for using ventionally held in a “mode” associated
fonts according to the OT1 encoding. with the device. Modes are commonly de-
Latin Modern fonts: fonts/lm fined using the mode_def convention de-
scribed on page 94 of The Metafontbook
136 Getting ‘free’ fonts not in your
(see TeX-related books). Your distribution
distribution
should provide a file, conventionally called
Some fonts are free to use, but may not local.mf, containing all the mode_defs
be sold. This creates a dilemma for dis- you will be using. In the unlikely event
tributions: users may want the fonts, but that local.mf doesn’t already exist, Karl
since the distribution is also available on a Berry’s collection of modes (modes.mf) is
DVD for sale, the fonts may not be in the a good starting point (it can be used as
distribtution. a ‘local.mf’ without modification in a
The CTAN archives hold such fonts, to- modern implementation of Metafont). Set-
gether with all the necessary support files, tings for new output devices are added to
but even with the support files ready-made, modes.mf as they become available.
installing a font is a tedious business. Now create a plain base file using mf
For TeX Live users, this dilemma (in “initialisation” mode), plain.mf, and
is solved by the getnonfreefonts script. local.mf:
Download the script installer from http:
//tug.org/fonts/getnonfreefonts/; % mf -ini
the web page tells you how to run the in- This is METAFONT...
staller to get the script, and what fonts are ** plain # you type plain
currently available (output)
Once the script is installed, you can ask *input local # you type this
it what it has available by saying: (output)
*dump # you type this
getnonfreefonts -l Beginning to dump on file plain...
(output)
and you can ask it to install a font (in your
local texmf tree) by: This will create a base file named plain.
base (or something similar; for example, it
getnonfreefonts luximono
will be PLAIN.BAS on MS-DOS systems).
(for example; the printed version of the Move the file to the directory containing
FAQ uses luximono, so that the example the base files on your system, and run
was to hand. . . ). texhash as necessary.
(System adminstrators may use Now you need to make sure Metafont
getnonfreefonts-sys, which will install loads this new base when it starts up. If
the font in the ‘public’ texmf tree, so that Metafont loads the plain base by default
all users of the system may use the new on your system, then you’re ready to go.
font.) Under Unix (using the default TeX Live
The script will download the relevant (and earlier) distributions this does indeed
font files from CTAN, extract them from happen, but we could for instance define
77
 a command plainmf 2 which executes ‘mf appropriate set of parameters, you should
-base=plain’ (or, in more traditional style use them to rebuild the base file that you
‘mf &plain’) which loads the plain base use.
file. Other sources of help are discussed in
The usual way to create a font with our list of Metafont and Metapost Tutori-
Metafont (with an appropriate base file als.
loaded) is to start Metafont’s input with
modes.mf : fonts/modes/modes.mf
the line
138 Which
\mode=<mode name>; mag=<magnification>; font <font
input files should
filebename>
kept
in response to the ‘**’ prompt or on the Metafont produces from its run three files,
Metafont command line. (If <mode name> a metrics (TFM) file, a generic font (GF)
is unknown or omitted, the mode defaults file, and a log file; all of these files have
to ‘proof’ mode and Metafont will produce the same base name as does the input (e.g.,
an output file called <font file name> if the input file was cmr10.mf, the outputs
.2602gf) The <magnification> is a will be cmr10.tfm, cmr10.nnngf (the file
floating point number or a ‘magstep’ name may be mangled if you are using
(magsteps define sizes by stating how an operating system which doesn’t permit
many times you need to multiply a base long file names) and cmr10.log).
size by 1.2, so for a base size of 10, For TeX to use the font, you need a
magstep 1 is 12, magstep 2 is 14.4 If TFM file, so you need to keep that. How-
mag=<magnification> is omitted, then ever, you are likely to generate the same
the default is 1 (magstep 0). For example, font at more than one magnification, and
to generate cmr10 at 12pt for an Epson, each time you do so you’ll (incidentally)
printer you might type generate another TFM file; these files are
all the same, so you only need to keep one
mf \mode=epson; mag=magstep 1; input cmr10
of them.
Note that under Unix the \ and ; charac- To preview or to produce printed out-
ters must usually be quoted or escaped, so put, the DVI processor will need a font
this would typically look something like raster file; this is what the GF file pro-
vides. However, while there used (once
mf ’\mode=epson; mag=magstep 1;upon input cmr10’
a time) to be DVI processors that
If you need a special mode that isn’t in could use GF files, modern processors use
the base, you can put its commands in a packed raster (PK) files (incidentally, PDF-
file (e.g., ln03.mf) and invoke it on the TeX also uses PK files if nothing “better”
fly with the \smode command. For exam- is available, but see fuzzy fonts in PDF).
ple, to create cmr10.300gf for an LN03 Therefore, you need to generate a PK file
printer, using the file from the GF file; the program gftopk does
this for you, and once you’ve done that you
% This is ln03.mf as of 1990/02/27 may throw the GF file away.
% mode_def courtesy of John Sauter The log file should never be needed
proofing:=0; again, unless there was some sort of prob-
fontmaking:=1; lem in the Metafont run, and need not there-
tracingtitles:=0; fore be kept.
pixels_per_inch:=300;
blacker:=0.65; 139 Acquiring bitmap fonts
fillin:=-0.1;
o_correction:=.5; When CTAN was young, most people
would start using TeX with a 300 dots-
(note the absence of the mode_def and per-inch (dpi) laser printer, and sets of
enddef commands), you would type Computer Modern bitmap fonts for this
resolution are available on CTAN. (There
mf \smode="ln03"; input cmr10
are separate sets for write-black and write-
This technique isn’t one you should reg- white printers, as well as sets at 120 dpi
ularly use, but it may prove useful if you and 240 dpi.)
acquire a new printer and want to experi- There used to regular requests that
ment with parameters, or for some other CTAN should hold a wider range of res-
reason are regularly editing the parameters olutions, but they were resisted for two
you’re using. Once you’ve settled on an reasons:

2 On the grounds that a command plain could be misconstrued as a reference to Plain TeX
78
 • The need to decide which printers to fonts/ps-type1/cm-super
generate fonts for. The broad-brush Latin Modern fonts: fonts/lm
approach taken for 300 dpi printers
was (more or less) justified back then,
given the dominance of certain printer L Hypertext and PDF
‘engines’, but nowadays one could not
make any such assumption. 140 Making PDF documents from
• Given the above, it has been near- (La)TeX
impossible to justify the space that There are three general routes to PDF out-
would be required by a huge array of put: Adobe’s original ‘distillation’ route
bitmap fonts. (via PostScript output), direct conversion
of a DVI file, and the use of a direct TeX-
Fortunately, (La)TeX distribution technol-
like PDF generator such as PDFTeX.
ogy has put a stop to these arguments: most
For simple documents (with no hyper-
(if not all) current distributions generate
references), you can either
bitmap fonts as needed, and cache them
for later re-use. The impatient user, who is • process the document in the normal
determined that all bitmap fonts should be way, produce PostScript output and
created once and for all, may be supported distill it;
by scripts such as allcm (distributed with • (on a Windows or Macintosh machine
TeX Live, at least; otherwise such a person with appropriate tools installed) pass
should consult “the use of Metafont)”. the output through a PDFwriter in
If your output is to a PostScript- place of a printer driver. This route
capable device, or if your output is des- is only appropriate for simple docu-
tined to be converted to PDF, you should ments: PDF writers cannot create hy-
switch to using Type 1 versions of the CM perlinks;
fonts. Two free sets are available; the older • process the document with “vanilla”
(bakoma) is somewhat less well produced LaTeX and generate PDF direct from
than the bluesky fonts, which were origi- the DVI using dvipdfm/dvipdfmx; or
nally professionally produced and sold, but • process the document direct to PDF
were then released for general public use with PDFTeX, LuaTeX, or XeTeX.
by their originators Y&Y and Bluesky Re-
search, in association with the AMS and To translate all the LaTeX cross-
other scientific publishers (they are nowa- referencing into Acrobat links, you need
days available under the SIL’s Open Fonts a LaTeX package to redefine the in-
Licence). The two sets contain slightly ternal commands. There are two of
different ranges of fonts, but you are ad- these for LaTeX, both capable of con-
vised to use the bluesky set except when forming to the HyperTeX specification:
bakoma is for some reason absolutely un- Heiko Oberdiek’s hyperref , and Michael
avoidable. In recent years, several other Mehlich’s hyper. (In practice, almost ev-
‘Metafont’ fonts have been converted to eryone uses hyperref ; hyper hasn’t been
Type 1 format; it’s uncommon ever to need updated since 2000.) Hyperref can of-
to generate bitmap fonts for any purpose ten determine how it should generate hy-
other than previewing — see “previewing pertext from its environment, but there is
documents with Type 1 fonts” — if even a wide set of configuration options you
then. can give via \usepackage. The pack-
More modern fonts may be used in age can operate using PDFTeX primi-
place of the Computer Modern set. The tives, the hyperTeX \specials, or DVI
EC fonts and the Latin Modern fonts are driver-specific \special commands. Both
both close relatives with wider ranges of dvips and Y&Y’s DVIPSONE can trans-
glyphs to offer. late the DVI with these \special com-
mands into PostScript acceptable to Dis-
BaKoMa fonts:
tiller, and dvipdfm and dvipdfmx have
fonts/cm/ps-type1/bakoma
\special commands of their own.
Bluesky fonts: Distributed as part of If you use Plain TeX, the Eplain
fonts/amsfonts macros can help you create PDF doc-
CM fonts (write-black printers): uments with hyper-references. It
fonts/cm/pk/pk300.zip can operate using PDFTeX primi-
tives, or \special commands for the
CM fonts (write-white printers): dvipdfm/dvipdfmx DVI drivers.
fonts/cm/pk/pk300w.zip
While there is no free implementation
EC fonts (Type 1 format): of all of Adobe Distiller’s functionality,
79
any but the implausibly old versions of The HyperTeX specification says that
ghostscript provide pretty reliable distil- conformant viewers/translators must rec-
lation (but beware of the problems with ognize the following set of \special com-
dvips output for distillation). mands:
For viewing (and printing) the result-
ing files, Adobe’s Acrobat Reader is avail- href: html:<a href = "href_string">
able for a fair range of platforms; for those name: html:<a name = "name_string">
for which Adobe’s reader is unavailable, end: html:</a>
remotely current versions of ghostscript image: html:<img src = "href_string">
combined with gv or gsview can display base_name: html:<base href = "href_string">
and print PDF files, as can xpdf . The href, name and end commands are
In some circumstances, a ghostscript- used to do the basic hypertext operations
based viewer application is actually prefer- of establishing links between sections of
able to Acrobat Reader. For example, on documents.
Windows Acrobat Reader locks the .pdf Further details are available on http:
file it’s displaying: this makes the tradi- //arXiv.org/hypertex/; there are two
tional (and highly effective) (La)TeX devel- commonly-used implementations of the
opment cycle of “Edit→Process→Preview” specification, a modified xdvi and (recent
become rather clumsy — gsview doesn’t releases of) dvips. Output from the lat-
make the same <mistake. ter may be used in recent releases of
Acrobat Reader: download from ghostscript or Acrobat Distiller.
http://get.adobe.com/reader
143 Quality of PDF from PostScript
dvipdfm : dviware/dvipdfm
Any reasonable PostScript, including any
dvipdfmx : dviware/dvipdfmx output of dvips, may be converted to PDF,
gv : Browse support/gv using (for example) a sufficiently recent
version of ghostscript, Frank Siegert’s
hyper.sty : (shareware) PStill, or Adobe’s (commer-
macros/latex/contrib/hyper cial) Distiller.
hyperref.sty : But, although the job may (almost al-
macros/latex/contrib/hyperref ways) be done, the results are often not
acceptable: the most frequent problem is
141 Making hypertext documents bad presentation of the character glyphs
from TeX that make up the document. The following
If you want on-line hypertext with a answers offer solutions to this (and other)
(La)TeX source, probably on the World problems of bad presentation. Issues cov-
Wide Web, there are four technologies to ered are:
consider:
• Wrong type of fonts used, which is the
• start from (La)TeX, and use one of commonest cause of fuzzy text.
a number of techniques to translate • Ghostscript too old, which can also
(more or less) directly to HTML; result in fuzzy text.
• Start from texinfo source, and use • Switching to font encoding T1 en-
the info viewer, or convert the texinfo coding, which is yet another possible
source to HTML using texi2html; cause of fuzzy text.
• Start from (La)TeX; use PDFTeX, Xe- • Another problem — missing charac-
TeX or LuaTeX to produce PDF, using ters — arises from an aged version of
hyperref to construct hyperlinks. Adobe Distiller.
• Start from (unconventional) (La)TeX • Finally, there’s the common confusion
which use the hyperTeX conventions. that arises from using the dvips con-
figuration file -Ppdf, the weird char-
texinfo: macros/texinfo/texinfo acters.
142 The hyperTeX project It should be noted that Adobe Reader 6
The hyperTeX project extended the func- (released in mid-2003, and later versions)
tionality of all the LaTeX cross-referencing does not exhibit the “fuzziness” that so
commands (including the table of contents) many of the answers below address. This
to produce \special commands which is of course good news: however, it will
are parsed by DVI processors conforming inevitably be a long time before every user
to the HyperTeX guidelines; it provides in the world has this (or later) versions, so
general hypertext links, including those to the remedies below are going to remain for
external documents. some time to come.
80
 The problems are also discussed, dvips: warning: no config file for ‘pdf’
with practical examples, in Mike Shell’s
or something similar, or about failing to
testflow package, which these FAQs rec-
find a font file:
ommend as a “specialised tutorial.
dvips: ! Couldn’t find header file cmr10.pfb
testflow : macros/latex/contrib/
IEEEtran/testflow Either of these failures signals that your
system doesn’t have the fonts in the first
144 The wrong type of fonts in PDF
place.
This is far the commonest problem: the A way of using the fonts that doesn’t in-
symptom is that text in the document looks volve the sophistication of the -Ppdf mech-
“fuzzy”. anism is simply to load maps:
Most people use Adobe Acrobat
dvips -Pcmz -Pamz myfile -o myfile.ps
Reader to view their PDF: Reader is dis-
tributed free of charge, and is widely avail- You may encounter the same warning mes-
able, for all its faults. One of those faults sages as listed above.
is its failure to deal with bitmap fonts (at If your system does not have the fonts,
least, in all versions earlier than version 6, it won’t have the configuration file either;
all of which copies are pretty old, now . . . however, it might have the configuration
but some are occasionally found). file without the fonts. In either case, you
So we don’t want bitmap fonts in our need to install the fonts.
PostScript: with them, characters show up
145 Fuzzy fonts because Ghostscript
in Reader’s display as blurred blobs which
too old
are often not even recognisable as the origi-
nal letter, and are often not properly placed So you’ve done everything the FAQ has
on the line. Nevertheless, even now, most told you that you need, correct fonts prop-
TeX systems have dvips configured to use erly installed and appearing in the dvips
.pk files in its output. Even PDFTeX will output, but still you get fuzzy character
use .pk files if it can see no alternative for output after distilling with ghostscript.
a font in the document it is processing. The problem could arise from too old
Our remedy is to use “Adobe Type 1” a version of ghostscript, which you may
versions of the fonts we need. Since Adobe be using directly, or via a script such as
are in the business of selling Type 1 fonts, ps2pdf (distributed with ghostscript itself),
Reader was of course made to deal with dvipdf , or similar. Though ghostscript was
them really rather well, from the very be- capable of distillation from version 5.50,
ginning. that version could only produce bitmap
Of course, if your document uses noth- Type 3 output of any font other than the
ing but fonts that came from Adobe in fundamental 35 fonts (Times, Helvetica,
the first place — fonts such as Times that etc.). Later versions added ‘complete’ dis-
appear in pretty much every PostScript tillation, but it wasn’t until version 6.50
printer, or such as Adobe Sabon that you that one could rely on it for everyday work.
pay extra for — then there’s no problem. So, if your PDF output still looks fuzzy
But most people use Computer Modern in Acrobat Reader, upgrade ghostscript.
to start with, and even those relative so- The new version should be at least ver-
phisticates who use something as exotic sion 6.50, of course, but it’s usually good
as Sabon often find themselves using odd policy to go to the most recent version (ver-
characters from CM without really intend- sion 8.12 at the time of writing — 2003).
ing to do so. Fortunately, rather good ver- 146 Fonts go fuzzy when you switch
sions of the CM fonts are available from to T1
the AMS (who have them courtesy of Blue You’ve been having problems with hy-
Sky Research and Y&Y). phenation, and someone has suggested
Most modern systems have the fonts that you should use “\usepackage[T1]
installed ready to use; and any system in- {fontenc}” to help sort them out. Sud-
stalled less than 3 years ago has a dvips denly you find that your final PDF has
configuration file ‘pdf’ that signals the use become fuzzy. The problem may arise
of the CM fonts, and also sets a few other whether you are using PostScript output
parameters to improve dvips’ output. Use and then distilling it, or you are using PDF-
this configuration as: TeX for the whole job.
dvips -Ppdf myfile -o myfile.ps In fact, this is the same problem as
most others about the quality of PDF:
This may produce a warning message you’ve abandoned your previous setup us-
about failing to find the configuration file: ing Type 1 versions of the CM fonts, and
81
dvips has inserted Type 3 versions of the 148 Finding ‘8-bit’ Type 1 fonts
EC fonts into your document output. (See Elsewhere, answers to these FAQs recom-
“Adobe font types for details of these font mend that you use an ‘8-bit’ font to permit
types; also, note that the font encoding T1 accentuation of inflected languages, and
has nothing directly to do with the font also recommend the use of Type 1 fonts
format Type 1). to ensure that you get good quality PDF.
However, as noted in 8-bit Type 1 fonts, These recommendations used to be contra-
Type 1 versions of CM-like fonts in T1 dictory: one could not just “switch” from
(or equivalent) encoding are now available, the free CM fonts to free Cork- (or simi-
both as “real” fonts, and as virtual font larly) encoded Type 1 fonts. The first ap-
sets. One solution, therefore, is to use one proach that started to alleviate these prob-
of these alternatives. lems, was the development of virtual fonts
The alternative is to switch font fam- that make a good approach to the Cork en-
ily altogether, to something like Times (as coding (see below). Now, however, we
a no-thought default) or one of the many have “true” Type 1 fonts available: as al-
more pleasing Adobe-encoded fonts. The ways, we have an embarrassment of riches
default action of fontinst, when creating with three free alternatives, and one com-
metrics for such a font, is to create settings mercial and one shareware version.
for both OT1 and T1 encodings, so there’s CM-super is an auto-traced set which
little change in what goes on (at the user encompasses all of the T1 and TS1 encod-
level) even if you have switched to T1 en- ings as well as the T2* series (the family of
coding when using the fonts. encodings that cover languages based on
Cyrillic alphabets). These fonts are pretty
147 Characters missing from PDF easy to install (the installation instructions
output are clear), but they are huge: don’t try to
install them if you’re short of disc space.
If you’re using Acrobat Distiller to cre- CM-LGC is a similar “super-font” set,
ate your PDF output, you may find charac- but of much more modest size; it cov-
ters missing. This may manifest itself as ers T1, TS1 and T2A encodings (as does
messed-up maths equations (missing “−” CM-super, and also covers the LGR encod-
signs, for example), or bits missing from ing (for typesetting Greek, based on Clau-
large symbols. Early versions of Distiller dio Beccari’s Metafont sources). CM-LGC
used to ignore character positions 0–31 manages to be small by going to the op-
and 128–159 of every font: Adobe’s fonts posite extreme from CM-super, which in-
never use such positions, so why should cludes fonts at all the sizes supported by
Distiller? the original EC (a huge range); CM-LGC
Well, the answer to this question is “be- has one font per font shape, getting other
cause Adobe don’t produce all the world’s sizes by scaling. There is an inevitable
fonts” — fonts like Computer Modern loss of quality inherent in this approach,
were around before Adobe came on the but for the disc-space-challenged machine,
scene, and they use positions 0–31. Adobe CM-LGC is an obvious choice.
don’t react to complaints like that in the Tt2001 is a simple scan of the EC and
previous sentence, but they do release new TC fonts, and has some virtues — it’s no-
versions of their programs; and Distiller, ticeably smaller than CM-super while be-
since at least version 4.0, has recognised ing less stark than CM-LGC.
the font positions it used to shun. Latin Modern is produced using the
Meanwhile, TeX users with old ver- program MetaType1. The Latin Modern
sions of Distiller need to deal with their set comes with T1, TS1 LY1 encoded vari-
fonts. Dvips comes to our aid: the switch ants (as well as a variant using the Polish
-G1 (“remap characters”), which moves QX encoding); for the glyph set it cov-
the offending characters out of the way. ers, its outlines seem rather cleaner than
The PDF configuration file (-Ppdf), rec- those of CM-super. Latin Modern is more
ommended above, includes the switch. modest in its disc space demands than is
The switch is not without its problems; CM-super, while not being nearly as stark
pre-2003 versions of dvips will apply it to in its range of design sizes as is CM-LGC —
Adobe fonts as well, causing havoc, but Latin Modern’s fonts are offered in the
fortunately that problem is usually soluble. same set of sizes as the original CM fonts.
However, a document using both CM and It’s hard to argue with the choice: Knuth’s
Adobe-specified fonts is stuck. The only range of sizes has stood the test of time,
real solution is either to upgrade dvips, or and is one of the bases on which the excel-
to spend money to upgrade Distiller. lence of the TeX system rests.
82
 Virtual fonts help us deal with the prob- systems/win32/bakoma/fonts
lem, since they allow us to map “bits of CM-LGC fonts:
DVI file” to single characters in the vir- fonts/ps-type1/cm-lgc
tual font; so we can create an “é” charac-
ter by recreating the DVI commands that CM-super fonts:
would result from the code “\’e”. How- fonts/ps-type1/cm-super
ever, since this involves two characters be- (beware: very large download)
ing selected from a font, the arrangement Latin Modern fonts: fonts/lm
is sufficient to fool Acrobat Reader: you
tt2001 fonts: fonts/ps-type1/tt2001
can’t use the program’s facilities for search-
ing for text that contains inflected charac- zefonts: fonts/zefonts
ters, and if you cut text from a window that
149 Replacing Type 3 fonts in
contains such a character, you’ll find some-
PostScript
thing unexpected (typically the accent and
the ‘base’ characters separated by a space) One often comes across a PostScript file
when you paste the result. However, if you generated by dvips which contains embed-
can live with this difficulty, virtual fonts ded PK fonts; if you try to generate PDF
are a useful and straightforward solution from such a file, the quality will be poor.
to the problem. Of course, the proper solution is to re-
There are two virtual-font offerings of generate the PostScript file, but if neither
CM-based 8-bit fonts — the ae (“almost the sources nor the DVI file are available,
EC”) and zefonts sets; the zefonts set has one must needs resort to some sort of patch-
wider coverage (though the ae set may be ing to replace the bitmap fonts in the file
extended to offer guillemets by use of the by outline fonts.
aeguill package). Neither offers characters The program pkfix (by Heiko Oberdiek)
such as eth and thorn (used in, for exam- will do this patching, for files created by
ple, in Icelandic), but the aecompl package “not too old versions” of dvips: it finds
works with the ae fonts to provide the miss- the fonts to be replaced by examining the
ing characters from the EC fonts (i.e., as PostScript comments dvips has put in the
bitmaps). file. For each font, pkfix puts appropriate
The sole remaining commercial CM- TeX commands in a file, which it then pro-
like 8-bit font comes from Micropress, cesses and runs through dvips (with switch
who offer the complete EC set in Type 1 -Ppdf) to acquire an appropriate copy of
format, as part of their range of outline the font; these copies are then patched back
versions of fonts that were originally dis- into the original file.
tributed in Metafont format. See “commer- If your source file is older than pkfix
cial distributions”. can deal with, there’s still a modicum of
The shareware BaKoMa TeX distribu- hope: pkfix-helper examines the bitmap
tion offers a set of Type 1 EC fonts, as fonts in a document, compares them with
an extra shareware option. (As far as the the metric (.tfm) fonts on your system
present author can tell, these fonts are only and comes to a view of which font might
available to users of BaKoMa TeX: they be which. The program reports on “poor”
are stored in an archive format that seems matches, and there are options for confirm-
not to be publicly available.) ing, or replacing, its guesses. The tech-
Finally, you can use one of the myr- nique (which sounds implausible) is suc-
iad text fonts available in Type 1 format cessful enough to be worth a try.
(with appropriate PSNFSS metrics for T1 A further option is Frank Siegert’s
encoding, or metrics for some other 8-bit (shareware) PStill, which is capable of pro-
encoding such as LY1). However, if you cessing the PostScript it is distilling, and
use someone else’s text font (even some- one option is to replace bitmap fonts in the
thing as simple as Adobe’s Times family) file with Type 1 versions.
you have to find a matching family of math- pkfix : support/pkfix
ematical fonts, which is a non-trivial un-
pkfix-helper :
dertaking — “choice of scalable fonts”.
support/pkfix-helper
ae fonts: fonts/ae
150 Hyperref and repeated page
aecompl.sty : Distributed with
numbers
fonts/ae
The book class (and its friends and rela-
aeguill.sty :
tions) automatically changes the display of
macros/latex/contrib/aeguill
page numbers in the frontmatter of the doc-
BaKoMa fonts: Browse ument to lower-case roman. This is fine
83
for human readers, but if hyperref has been OT1 or T1, your document will be OK for
misconfigured, the existence of pages have almost all ASCII characters, but it’s likely
the same page number can cause problems. that anything “out of the ordinary” will not
Fortunately, the configuration options to be represented properly. (Of course, PDF
make hyperref “do the right thing” are (by generated from XeTeX- or LuaTeX-based
default) set up to avoid problems. formats is going to be OK, since those en-
The two options in question are: gines work in Unicode througout.)
The solution comes from the character-
plainpages=false Make page anchors mapping facilities in the PDF specification:
using the formatted form of the page the file may specify a table of translations
number. With this option, hyperref of characters present in the coding used in
writes different anchors for pages ‘ii’ the file, to a Unicode version of the charac-
and ‘2’. (This is the default value for ters.
the option, which is a good thing. . . ) Packages cmap and mmap both offer
If the option is set ‘true’ hyperref means of generating such tables (mmap
writes page anchors as the arabic form has wider coverage, including the various
of the page number, rather than the maths encodings); both work with PDF-
formatted form that gets printed; this TeX and no other engine. Thus your docu-
is not usually appropriate. ment becomes something like:
pdfpagelabels Set PDF page labels; i.e.,
write the value of \thepage to the \documentclass{article}
PDF file so that Acrobat Reader can \usepackage{mmap} % (or cmap)
display the page number as (say) ‘ii (4 \usepackage[T1]{fontenc}
of 40)’ rather than simply ‘4 of 40’. ... % your other packages
\begin{document}
The two should be used whenever page ... % your actual text
numbering is not just ‘1..n’; they may be
used independently, but usually are not. Unfortunately, the packages only work
The recipe isn’t perfect: it relies on with fonts that are directly encoded, such
\thepage being different for every page in as the default (Computer Modern, i.e.,
the document. A common problem arises cm fonts, and things such as cm-super
when there is an unnumbered title page, or the Latin Modern sets. Fonts like
after which page numbers are reset: the Adobe Times Roman (which are encoded
PDFTeX warning of “duplicate destina- for (La)TeX use via virtual fonts) are not
tions” will happen in this case, regardless amenable to this treatment.
of the options. cmap.sty :
hyperref.sty : macros/latex/contrib/cmap
macros/latex/contrib/hyperref cm-super fonts:
151 Copy-paste-able/searchable PDF fonts/ps-type1/cm-super
files Latin Modern fonts: fonts/lm
PDF files generated from TeX (and mmap.sty :
friends), will by default hold their text in macros/latex/contrib/mmap
the encoding of the original TeX font used
by the document.
When PDF readers, etc., offer copy- M Graphics
paste or searching functions, the operations
take place on the glyph codes used for the 152 Importing graphics into (La)TeX
fonts selected by the document. This is documents
fine, for the simplest documents (in En- Knuth, when designing the current ver-
glish, at least); the problem comes when sion of TeX back in the early 1980s, could
you’re using an inflected language (with discern no “standard” way of expressing
accented letters, or composite glyphs such graphics in documents. He reasoned that
as ‘æ’) — TeX will typically use a non- this state could not persist for ever, but that
standard encoding, and there are likely be it would be foolish for him to define TeX
problems, since PDF readers assume the primitives that allowed the import of graph-
text is presented in Unicode. ical image definitions. He therefore de-
For PDF generated from LaTeX (the ferred the specification of the use of graph-
DVI being converted, by whatever means), ics to the writers of DVI drivers; TeX doc-
or from PDFLaTeX, the character codes uments would control the drivers by means
used in the PDF file are in fact those of the of \special commands (\special com-
document’s font encoding; if you’re using mands).
84
 There is therefore a straightforward many other things. While this is all a con-
way for anyone to import graphics into venience (at some cost of syntax), it is also
their document: read the specification of capable of producing noticeably more ef-
the \special commands your driver uses, ficient PostScript, and some of its combi-
and ‘just’ code them. This is the hair-shirt nations are simply not possible with the
approach: it definitely works, but it’s not graphics package version.
for everyone. The epsfig package provides the same
Over the years, therefore, “graphics in- facilities as graphicx, but via a \psfig
clusion” packages have sprung up; most command (also known as \epsfig), capa-
were designed for inclusion of Encapsu- ble of emulating the behaviour (if not the
lated PostScript graphics (Encapsulated bugs) the old psfig package. Epsfig also
PostScript graphics) — which has become supplies homely support for former users
the lingua franca of graphics inclusion of the epsf package. However, there’s a
over the last decade or so. support issue: if you declare you’re using
Notable examples are the epsf pack- epsfig, any potential mailing list or usenet
age (distributed with dvips) and the psfig helper has to clear out of the equation the
package. (Both of these packages were de- possibility that you’re using “old” epsfig,
signed to work well with both Plain TeX so that support is slower coming than it
and LaTeX 2.09; they are both still avail- would otherwise be.
able.) All such packages were tied to a There is no rational reason to stick with
particular DVI driver (dvips, in the above the old packages, which have never been
two cases), but their code could be config- entirely satisfactory in the LaTeX context.
ured for others. (One irrational reason to leave them be-
The obvious next step was to make hind is that their replacement’s name tends
the code configurable dynamically. The not to imply that it’s exclusively related to
LaTeX standard graphics package and its PostScript graphics. The reasoning also
derivatives made this step: it is strongly excludes epsfig, of course.)
preferred for all current work. A wide variety of detailed techniques
Users of Plain TeX have two options and tricks have been developed over the
allowing them to use graphicx: the miniltx years, and Keith Reckdahl’s epslatex out-
“LaTeX emulator” and the graphicx.tex lines them in compendious detail: this
front-end allow you to load graphicx, and highly recommendable document is avail-
Eplain allows you to load it (using the full able from CTAN. An invaluable review of
LaTeX syntax) direct. the practicalities of exchanging graphics
The graphics package takes a variety between sites, “Graphics for Inclusion in
of “driver options” — package options that Electronic Documents” has been written
select code to generate the commands ap- by Ian Hutchinson; the document isn’t on
propriate to the DVI driver in use. In most CTAN, but may also be browsed on the
cases, your (La)TeX distribution will pro- Web.
vide a graphics.cfg file that will select epsf.tex :
the correct driver for what you’re doing macros/generic/epsf/epsf.tex
(for example, a distribution that provides epsfig.sty : Part of the macros/
both LaTeX and PDFLaTeX will usually latex/required/graphics bundle
provide a configuration file that determines
whether PDFLaTeX is running, and selects epslatex.pdf : info/epslatex
the definitions for it if so). graphics.sty : macros/latex/
The graphics package provides a required/graphics
toolkit of commands (insert graphics, scale
graphicx.sty : Part of the macros/
a box, rotate a box), which may be com-
latex/required/graphics bundle
posed to provide most facilities you need;
the basic command, \includegraphics, miniltx.tex :
takes one optional argument, which speci- macros/plain/graphics
fies the bounding box of the graphics to be psfig.sty : graphics/psfig
included.
The graphicx package uses the fa- 153 Imported graphics in dvips
cilities of of graphics behind a rather Dvips, as originally conceived, can only
more sophisticated command syntax import a single graphics format: encap-
to provide a very powerful version sulated PostScript (.eps files, encapsu-
of the \includegraphics command. lated PostScript). Dvips also deals with
graphicx’s version can combine scaling the slightly eccentric EPS that is created
and rotation, viewporting and clipping, and by Metapost.
85
 Apart from the fact that a depressing The commonest problem users en-
proportion of drawing applications pro- counter, when switching from TeX, is
duce corrupt EPS when asked for such out- that there is no straightforward way to in-
put, this is pretty satisfactory for vector clude EPS files: since PDFTeX is its own
graphics work. “driver”, and since it contains no means of
To include bitmap graphics, you converting PostScript to PDF, there’s no
need some means of converting them to direct way the job can be done.
PostScript; in fact many standard im- The simple solution is to convert the
age manipulators (such as ImageMagick’s EPS to an appropriate PDF file. The
convert) make a good job of creating EPS epstopdf program will do this: it’s avail-
files (but be sure to ask for output at able either as a Windows executable or as
PostScript level 2 or higher). (Unix users a Perl script to run on Unix and other simi-
should beware of xv’s claims: it has a ten- lar systems. A LaTeX package, epstopdf ,
dency to downsample your bitmap to your can be used to generate the requisite PDF
screen resolution.) files “on the fly”; this is convenient, but
Special purpose applications jpeg2ps requires that you suppress one of TeX’s
(which converts JPEG files using security checks: don’t allow its use in files
PostScript level 2 functionality), bmeps from sources you don’t entirely trust.
(which converts both JPEG and PNG files) The package pst-pdf permits other
and a2ping/sam2p (which convert a bewil- things than ‘mere’ graphics files in its ar-
dering array of bitmap formats to EPS or gument. Pst-pdf operates (the authors sug-
PDF files; sam2p is one of the engines that gest) “like BibTeX” — you process your
a2ping uses) are also considered “good file using PDFLaTeX, then use LaTeX,
bets”. dvips and ps2pdf in succession, to pro-
Bmeps comes with patches to produce duce a secondary file to input to your next
your own version of dvips that can cope PDFLaTeX run. (Scripts are provided to
with JPEG and PNG direct, using bmeps’s ease the production of the secondary file.)
conversion library. Dvips, as distributed by A further extension is auto-pst-pdf ,
MiKTeX, comes with those patches built- which generates PDF (essentially) trans-
in, but assuming that capability destroys parently, by spawning a job to process out-
portability, and is only recommendable if put such as pst-pdf uses. If your PDFLa-
you are sure you will never want to share TeX installation doesn’t automatically al-
your document. low it — see spawning a process — then
you need to start PDFLaTeX with:
a2ping : graphics/a2ping

bmeps: Distributed as part of pdflatex -shell-escape <file>

support/dktools
for complete ‘automation’.
jpeg2ps: support/jpeg2ps An alternative solution is to use
purifyeps, a Perl script which uses the
sam2p: graphics/sam2p
good offices of pstoedit and of Metapost
to convert your Encapsulated PostScript
154 Imported graphics in PDFLaTeX
to “Something that looks like the encapsu-
PDFTeX itself has a rather wide range of lated PostScript that comes out of Meta-
formats that it can “natively” incorporate post”, and can therefore be included di-
into its output PDF stream: JPEG (.jpg rectly. Sadly, purifyeps doesn’t work for
files) for photographs and similar images, all .eps files.
PNG files for artificial bitmap images, and Good coverage of the problem is to be
PDF for vector drawings. Old versions of found in Herbert Voß’s PDF support page,
PDFTeX (prior to version 1.10a) supported which is targeted at the use of pstricks in
TIFF (.tif files) format as an alternative PDFLaTeX, and also covers the pstricks-
to PNG files; don’t rely on this facility, specific package pdftricks. A recent alter-
even if you are running an old enough ver- native (not covered in Herbert Voß’s page)
sion of PDFTeX. . . is pdftricks2, which offers similar facilities
In addition to the ‘native’ formats, to pdftricks, but with some useful varia-
the standard PDFLaTeX graphics pack- tions.
age setup causes Hans Hagen’s supp-pdf auto-pst-pdf.sty :
macros to be loaded: these macros are ca- macros/latex/contrib/auto-
pable of translating the output of Metapost pst-pdf
to PDF “on the fly”; thus Metapost out-
put (.mps files) may also be included in epstopdf : Browse support/epstopdf
PDFLaTeX documents. epstopdf.sty : Distributed with
86
 Heiko Oberdiek’s packages explicitly, as an option when loading the
macros/latex/contrib/oberdiek graphicx package: if you are using dvips,
pdftricks.sty : graphics/pdftricks you don’t ordinarily need to specify the
fact, since the default graphics configura-
pdftricks2.sty : tion file (of most distributions) “guesses”
graphics/pdftricks2 the dvips option if you’re using TeX.
pst-pdf.sty : dvipdfm : dviware/dvipdfm
macros/latex/contrib/pst-pdf
dvipdfmx : dviware/dvipdfmx
pstoedit: support/pstoedit
ebb: Distributed as part of
purifyeps: support/purifyeps
dviware/dvipdfm
155 Imported graphics in dvipdfm
Dvipdfm (and dvipdfmx) translates direct 156 “Modern” graphics file names
from DVI to PDF (all other available routes TeX was designed in a world where file
produce PostScript output using dvips and names were very simple indeed, typi-
then convert that to PDF with ghostscript cally strictly limited both in character set
or Acrobat’s Distiller). and length. In modern systems, such re-
Dvipdfm/Dvipdfmx are particularly strictions have largely disappeared, which
flexible applications. They permit the in- leaves TeX rather at odds with its envi-
clusion of bitmap and PDF graphics (as ronment. Particular problems arise with
does PDFTeX), but are also capable of em- spaces in file names, but things like multi-
ploying ghostscript “on the fly” to permit ple period characters can seriously confuse
the inclusion of encapsulated PostScript the graphics package.
(.eps) files by translating them to PDF. In The specification of TeX leaves some
this way, they combine the good qualities leeway for distributions to adopt file ac-
of dvips and of PDFTeX as a means of cess appropriate to their operating system,
processing illustrated documents. but this hasn’t got us very far. Many mod-
Unfortunately, “ordinary” LaTeX can’t ern distributions allow you to specify a file
deduce the bounding box of a binary name as "file name.tex" (for example),
bitmap file (such as JPEG or PNG), so you which helps somewhat, but while this al-
have to specify the bounding box. This lows us to say
may be done explicitly, in the document:
\input "foo bar.tex"
\usepackage[dvipdfm]{graphicx}
... the analogous usage
\includegraphics[bb=0 0 540 405]{photo.jpg}
\includegraphics{"gappy graphics.eps"}
It’s usually not obvious what values to give
the “bb” key, but the program ebb will gen-
using “ordinary” LaTeX causes confu-
erate a file containing the information; the
sion in xdvi and dvips, even though it
above numbers came from an ebb outputworks at compilation time. Sadly, even
file photo.bb: within such quotes, multiple dots give
%%Title: /home/gsm10/photo.jpg \includegraphics difficulties. Note that
%%Creator: ebb Version 0.5.2
\includegraphics{"gappy graphics.pdf"}
%%BoundingBox: 0 0 540 405
%%CreationDate: Mon Mar 8 15:17:47 2004
works in a similar version of PDFTeX.
If such a file is available, you may abbrevi- If you’re using the graphics package,
ate the inclusion code, above, to read: the grffile package will help. The pack-
age offers several options, the simplest of
\usepackage[dvipdfm]{graphicx} which are multidot (allowing more than
... one dot in a file name) and space (allow-
\includegraphics{photo} ing space in a file name). The space op-
tion requires that you’re running on a suffi-
which makes the operation feel as sim-
ciently recent version of PDFTeX, in PDF
ple as does including .eps images in a
mode — and even then it won’t work for
LaTeX file for processing with dvips; the
Metapost files, which are read as TeX in-
graphicx package knows to look for a .bb
put, and therefore use the standard input
file if no bounding box is provided in the
mechanism).
\includegraphics command.
The one place where usage isn’t quite grffile.sty : Distributed as part of
so simple is the need to quote dvipdfm macros/latex/contrib/oberdiek
87
157 Importing graphics from which of course slows things. Further,
“somewhere else” (La)TeX remembers the name of any file
By default, graphics commands like it’s asked to look up, thus effectively losing
\includegraphics look “wherever TeX memory, so that in the limit a document
files are found” for the graphic file they’re that uses a huge number of graphical inputs
being asked to use. This can reduce your could be embarrassed by lack of memory.
flexibility if you choose to hold your graph- (Such “memory starvation” is pretty un-
ics files in a common directory, away from likely with any ordinary document in a
your (La)TeX sources. reasonably modern (La)TeX system, but it
The simplest solution is to patch TeX’s should be borne in mind.)
path, by changing the default path. On If your document is split into a variety
most systems, the default path is taken of directories, and each directory has its as-
from the environment variable TEXINPUTS, sociated graphics, the import package may
if it’s present; you can adapt that to take well be the thing for you; see the discussion
in the path it already has, by setting the of “bits of document in other directories”
variable to (bits of document in other directories).
graphics bundle: macros/latex/
TEXINPUTS=.:<graphics path(s)>:
required/graphics
on a Unix system; on a Windows system
import.sty :
the separator will be “;” rather than “:”.
macros/latex/contrib/import
The “.” is there to ensure that the cur-
rent directory is searched first; the trailing
“:” says “patch in the value of TEXINPUTS 158 Portable imported graphics
from your configuration file, here”. A regular need is a document to be dis-
This method has the merit of efficiency tributed in more than one format: com-
((La)TeX does all of the searches, which monly both PostScript and PDF. The fol-
is quick), but it’s always clumsy and may lowing advice is based on a post by one
prove inconvenient to use in Windows se- with much experience of dealing with the
tups (at least). problem of dealing with EPS graphics in
The alternative is to use the graphics this case.
package command \graphicspath; this
command is of course also available to • Don’t specify a driver when load-
users of the graphicx and the epsfig pack- ing loading whichever version of the
ages. The syntax of \graphicspath’s one graphics package you use. The
argument is slightly odd: it’s a sequence scheme relies on the distribution’s
of paths (typically relative paths), each of ability to decide which driver is going
which is enclosed in braces. A slightly odd to be used: the choice is between dvips
example (slightly modified from one given and PDFTeX, in this case. Be sure to
in the graphics bundle documentation) is: exclude options dvips, pdftex and
dvipdfm (dvipdfm is not used in this
\graphicspath{{eps/}{png/}}
scheme, but the aspirant PDF-maker
which will search for graphics files in sub- may be using it for his output, before
directories eps and png of the directory in switching to the scheme).
which LaTeX is running. (Note that the • Use \includegraphics[...]
trailing “/” is required.) {filename} without specifying the
(Note that some (La)TeX systems will extension (i.e., neither .eps nor
only allow you to use files in the current .pdf).
directory and its sub-directories, for secu- • For every .eps file you will be in-
rity reasons. However, \graphicspath cluding, produce a .pdf version, as
imposes no such restriction: as far as it is described in Graphics in PDFLaTeX.
concerned, you can access files anywhere.) Having done this, you will have two
Be aware that \graphicspath does copies of each graphic (a .eps and a
not affect the operations of graphics .pdf file) in your directory.
macros other than those from the graph- • Use PDFLaTeX (rather than LaTeX–
ics bundle — in particular, those of the dvips–distillation or LaTeX–dvipdfm)
outdated epsf and psfig packages are im- to produce your PDF output.
mune.
The slight disadvantage of the Dvipdfm’s charms are less than attractive
\graphicspath method is inefficiency. here: the document itself needs to be al-
The package will call (La)TeX once for tered from its default (dvips) state, before
each entry in the list to look for a file, dvipdfm will process it.
88
159 Repeated graphics in a document If your PostScript is destined for con-
A logo or “watermark” image, or any other version to PDF, either by a ghostscript-
image that is repeated in your document, based mechanism such as ps2pdf or by (for
has the potential to make the processed ver- example) Acrobat Distiller, the issue isn’t
sion of the document unmanageably large. so pressing, since the distillation mech-
The problem is, that the default mecha- anism will amalgamate graphics objects
nisms of graphics usage add the image at whether or not the PostScript has them
every point it’s to be used, and when pro- amalgamated. PDFTeX does the same
cessed, the image appears in the output file job with graphics, automatically convert-
at each such point. ing multiple uses into references to graph-
Huge PostScript files are embarrassing; ics objects.
explaining why such a file is huge, is more graphicx-psmin.sty : macros/latex/
embarrassing still. contrib/graphicx-psmin
The epslatex graphics tutorial de-
160 Limit the width of imported
scribes a technique for avoiding the prob-
graphics
lem: basically, one converts the image
that’s to be repeated into a PostScript sub- Suppose you have graphics which may or
routine, and load that as a dvips prologue may not be able to fit within the width of
file. In place of the image, you load a file the page; if they will fit, you want to set
(with the same bounding box as the image) them at their natural size, but otherwise
containing no more than an invocation of you want to scale the whole picture so that
the subroutine defined in the prologue. it fits within the page width.
The epslatex technique is tricky, but You do this by delving into the innards
does the job. Trickier still is the neat of the graphics package (which of course
scheme of converting the figure to a needs a little LaTeX internals program-
one-character Adobe Type 3 outline font. ming):
While this technique is for the “real ex- \makeatletter
perts” only (the author of this answer has \def\maxwidth{%
never even tried it), it has potential for the \ifdim\Gin@nat@width>\linewidth
same sort of space saving as the epslatex \linewidth
technique, with greater flexibility in actual \else
use. \Gin@nat@width
More practical is Hendri Adriaens’ \fi
graphicx-psmin; you load this in place of }
graphicx, so rather than: \makeatother
\usepackage[<options>]{graphicx}This defines a “variable” width which
has the properties you want. Replace
you will write:
\linewidth if you have a different con-
straint on the width of the graphic.
\usepackage[<options>]{graphicx-psmin}
Use the command as follows:
and at the start of your document, you
write: \includegraphics[width=\maxwidth]{figure}

161 Top-aligning imported graphics

\loadgraphics[<bb>]{<list of graphics>}
When TeX sets a line of anything, it en-
and each of the graphics in the list is
sures that the base-line of each object in
converted to an “object” for use within
the line is at the same level as the base-line
the resulting PostScript output. (This is,
of the final object. (Apart, of course, from
in essence, an automated version of the
\raisebox commands. . . )
epslatex technique described above.)
Most imported graphics have their
Having loaded the package as above,
base-line set at the bottom of the picture.
whenever you use \includegraphics,
When using packages such as subfig, one
the command checks if the file you’ve
often wants to align figures by their tops.
asked for is one of the graphics in
The following odd little bit of code does
\loadgraphics’ list. If so, the opera-
this:
tion is converted into a call to the “object”
rather than a new copy of the file; the re- \vtop{%
sulting PostScript can of course be much \vskip0pt
smaller. \hbox{%
Note that the package requires a recent \includegraphics{figure}%
dvips, version 5.95b (this version isn’t — }%
yet — widely distributed). }
89
The \vtop primitive sets the base-line of characters disappear, or are wrongly pre-
the resulting object to that of the first “line” sented) the solution is to view the ‘original’
in it; the \vskip creates the illusion of an Metapost output after processing through
empty line, so \vtop makes the very top LaTeX and dvips.
of the box into the base-line. Conditional compilation may be
In cases where the graphics are to be done either by inputting MyFigure.
aligned with text, there is a case for mak- mp indirectly from a simple wrapper
ing the base-line one ex-height below the MyFigureDisplay.mp:
top of the box, as in:
prologues := 2;
\vtop{% input MyFigure
\vskip-1ex
or by issuing a shell command such as
\hbox{%
\includegraphics{figure}% mp ’\prologues:=2; input MyFigure’
}%
} (which will work without the quote marks
if you’re not using a Unix shell).
A more LaTeX-y way of doing the job A suitable LaTeX route would in-
(somewhat inefficiently) uses the calc volve processing MyFigure.tex, which
package: contains:
\usepackage{calc} \documentclass{article}
... \usepackage{graphicx}
\raisebox{1ex-\height}{\includegraphics{figure}}
\begin{document}
\thispagestyle{empty}
(this has the same effect as the text-align
\includegraphics{MyFigure.1}
version, above).
\end{document}
The fact is, you may choose where the
base-line ends up. This answer merely Processing the resulting DVI file with the
shows you sensible choices you might dvips command
make.
dvips -E -o MyFigure.eps MyFigure
162 Displaying Metapost output in
ghostscript would then give a satisfactory Encap-
sulated PostScript file. This procedure
Metapost ordinarily expects its output to be
may be automated using the Perl script
included in some context where the ‘stan-
mps2eps, thus saving a certain amount of
dard’ Metafont fonts (that you’ve speci-
tedium.
fied) are already defined — for example,
The Plain TeX user may use an adap-
as a figure in TeX document. If you’re
tation, by Dan Luecking, of a jiffy of
debugging your Metapost code, you may
Knuth’s. Dan’s version mpsproof.tex will
want to view it in a ghostscript-based (or
work under TeX to produce a DVI file for
some other PostScript) previewer, but note
use with dvips, or under PDFTeX to pro-
that viewers (even ghostscript) don’t or-
duce a PDF file, direct. The output is set
dinarily have the fonts loaded, and you’ll
up to look like a proof sheet.
experience an error such as
A script application, mptopdf , is avail-
Error: /undefined in cmmi10 able in recent (La)TeX distributions: it
seems fairly reliably to produce PDF from
There is provision in Metapost for avoid- Metapost, so may reasonably be consid-
ing this problem: issue the command ered an answer to the question. . .
prologues := 2; at the start of the .mp
mps2eps: support/mps2eps
file.
Unfortunately, the PostScript that mpsproof.tex : Distributed as part
Metapost inserts in its output, following of the Metapost distribution
this command, is incompatible with ordi- graphics/metapost
nary use of the PostScript in inclusions into mptopdf : Part of graphics/metapost/
(La)TeX documents, so it’s best to make contrib/tools/mptopdf
the prologues command optional. Fur-
thermore, Metapost takes a very simple- 163 Drawing with TeX
minded approach to font encoding: since There are many packages to do pictures
TeX font encodings are anything but sim- in (La)TeX itself (rather than importing
ple, encoding of text in diagrams are an- graphics created externally), ranging from
other source of problems. If you’re suf- simple use of LaTeX picture environ-
fering such problems (the symptom is that ment, through enhancements like eepic,
90
to sophisticated (but slow) drawing with see PDFLaTeX graphics) generates
PiCTeX. Depending on your type of draw- PDF files using an auxiliary program,
ing, and setup, here are a few systems you from PSTricks commands (pst-pdf
may consider: also requires a recent installation of
the preview package).
• The picture environment provides
There is a PSTricks mailing list
rather primitive drawing capabilities
([email protected]) which you may
(anything requiring more than linear
join, or you may just browse the list
calculations is excluded, unless a font
archives.
can come to your help). The environ-
• pgf : while pstricks is very power-
ment’s tedious insistence on its own
ful and convenient from ‘traditional’
\unitlength, as the basic measure-
TeX, using it with PDFLaTeX is pretty
ment in a diagram, may be avoided
tiresome: if you simply want the
by use of the picture package, which
graphical capabilities, pgf , together
detects whether a length is quoted as
with its “user-oriented” interface tikz,
a number or as a length, and acts ac-
may be a good bet for you. While
cordingly.
PDF has (in essence) the same graph-
• epic was designed to make use of the
ical capabilities as PostScript, it isn’t
LaTeX picture environment some-
programmable; pgf provides LaTeX
what less agonising; eepic extends it,
commands that will utilise the graph-
and is capable of using tpic \special
ical capabilities of both PostScript
commands to improve printing perfor-
and PDF equally. Pgf has exten-
mance. (If the \specials aren’t avail-
sive mathematical support, which al-
able, the eepicemu will do the busi-
lows it to rival PSTricks’ use of the
ness, far less efficiently.
computation engine within PostScript.
• pict2e; this was advertised in the La-
The pgf manual is enormous, but
TeX manual, but didn’t appear for
a simple introduction which allows
nearly ten years after publication of
the user to get a feel for the ca-
the book! It removes all the petty
pabilities of the system, is avail-
restrictions that surround the use of
able at http://cremeronline.com/
the picture environment. It there-
LaTeX/minimaltikz.pdf
fore suffers only from the rather ec-
• Metapost; you liked Metafont, but
centric drawing language of the envi-
never got to grips with font files? Try
ronment, and is a far more useful tool
Metapost — all the power of Meta-
than the original environment has ever
font, but it generates PostScript fig-
been. (Note that pict2e supersedes
ures; Metapost is nowadays part of
David Carlisle’s stop-gap pspicture.)
most serious (La)TeX distributions.
• PiCTeX is a venerable, and very pow-
Knuth uses it for all his work. . .
erful, system, that draws by placing
Note that you can “embed” Metapost
dots on the page to give the effect of
source in your document (i.e., keep it
a line or curve. While this has the po-
in-line with your LaTeX code).
tential of great power, it is (of course)
• You liked Metafont (or Metapost), but
much slower than any of the other
find the language difficult? Mfpic
established packages. What’s more,
makes up Metafont or Metapost
there are problems with its documen-
code for you using familiar-looking
tation.
(La)TeX macros. Not quite the full
• PSTricks gives you access to the (con-
power of Metafont or Metapost, but a
siderable) power of PostScript via
friendlier interface, and with Metapost
a set of TeX macros, which talk
output the results can be used equally
to PostScript using \special com-
well in either LaTeX or PDFLaTeX.
mands. Since PostScript is itself
• You liked PiCTeX but don’t have
a pretty powerful programming lan-
enough memory or time? Look at the
guage, many astounding things can in
late Eitan Gurari’s dratex: it is just as
principle be achieved using PSTricks
powerful, but is an entirely new im-
(a wide range of contributed pack-
plementation which is not as hard on
ages, ranging from world mapping
memory, is much more readable and
to lens design diagrams, is available).
is (admittedly sparsely) documented
Pstricks’ \specials are by default
at http://www.cse.ohio-state.
specific to dvips, but there is a Pstricks
edu/~gurari/tpf/html/README.
‘driver’ that allow Pstricks to oper-
html, as well as in the author’s book
ate under XeTeX. PDFTeX users may
“TeX and LATeX: Drawing and Lit-
use pst-pdf , which (like epstopdf —
91
 erate Programming”, which remains egplot Allows you to incorporate
available from on-line booksellers. GNUplot instructions in your docu-
ment, for processing outside of LaTeX.
In addition, there are several means The package provides commands that
of generating code for your graphics ap- enable the user to do calculation in
plication (asymptote, gnuplot and Meta- GNUplot, feeding the results into the
post, at least) in-line in your document, and diagram to be drawn.
then have them processed in a command
spawned from your (La)TeX run. For de- gmp Allows you to include the source of
tails, see question. MetaPost diagrams, with parameters
of the diagram passed from the envi-
dratex.sty : graphics/dratex ronment call.
epic.sty :
emp An earlier package providing facili-
macros/latex/contrib/epic
ties similar to those of gmp (gmp’s au-
eepic.sty : thor hopes that his package will sup-
macros/latex/contrib/eepic port the facilities emp, which he be-
eepicemu.sty : lieves is in need of update.)
macros/latex/contrib/eepic mpgraphics Again, allows you to pro-
mfpic: graphics/mfpic gram parameters of Metapost dia-
grams from your LaTeX document,
preview.sty : including the preamble details of the
macros/latex/contrib/preview LaTeX code in any recursive call from
pspicture.sty : macros/latex/ Metapost.
contrib/pspicture
In all cases (other than asymptote), these
pst-pdf.sty : packages require that you can run external
macros/latex/contrib/pst-pdf programs from within your document.
pgf.sty : graphics/pgf/base asymptote.sty : graphics/asymptote
pict2e.sty : egplot.sty :
macros/latex/contrib/pict2e macros/latex/contrib/egplot
pictex.sty : graphics/pictex
emp.sty : macros/latex/contrib/emp
picture.sty : Distributed as part of
gmp.sty : macros/latex/contrib/gmp
macros/latex/contrib/oberdiek
mpgraphics.sty : macros/latex/
pstricks: graphics/pstricks
contrib/mpgraphics
tikz.sty : Distributed as part of
graphics/pgf/base
165 Drawing Feynman diagrams in
LaTeX
164 In-line source for graphics Michael Levine’s feynman bundle for draw-
applications ing the diagrams in LaTeX 2.09 is still
Some of the free-standing graphics applica- available.
tions may also be used (effectively) in-line Thorsten Ohl’s feynmf is designed for
in LaTeX documents; examples are use with current LaTeX, and works in com-
bination with Metafont (or, in its feynmp
asymptote The package asymptote (pro-
incarnation, with Metapost). The feynmf
vided in the asymptote distribution)
or feynmp package reads a description of
defines an environment asy which ar-
the diagram written in TeX, and writes
ranges that its contents are available
out code. Metafont (or Metapost) can
for processing, and will therefore be
then produce a font (or PostScript file) for
typeset (after “enough” runs, in the
use in a subsequent LaTeX run. For new
‘usual’ LaTeX way).
users, who have access to Metapost, the
Basically, you write PostScript version is probably the better
route, for document portability and other
\begin{asy}
reasons.
hasymptote codei Jos Vermaseren’s axodraw is men-
\end{asy}
tioned as an alternative in the documenta-
and then execute tion of feynmf , but it is written entirely in
terms of dvips \special commands, and
latex document is thus rather imperfectly portable.
asy document-*.asy An alternative approach is imple-
latex document mented by Norman Gray’s feyn package.
92
Rather than creating complete diagrams as to produce a small LaTeX file with nothing
postscript images, feyn provides a font (in but the figure inclusion commands. Each
a variety of sizes) containing fragments, of these figure files is then processed to
which you can compose to produce com- PostScript, compiled using the \psfrag
plete diagrams. It offers fairly simple dia- commands, and the resulting output con-
grams which look good in equations, rather verted to PDF again.
than complicated ones more suitable for Pdfrack is written to use the Unix
display in figures. Bourne shell (or equivalent); thus your en-
axodraw : graphics/axodraw vironment needs to be a Unix-based sys-
tem, or some equivalent such as cygwin
feyn font bundle: fonts/feyn under windows. (What is more, pdfrack’s
feynman bundle: macros/latex209/ author is rather disparaging about his pack-
contrib/feynman age; the present author has never tried it.)
feynmf/feynmp bundle: The psfragx package goes one step
macros/latex/contrib/feynmf further than psfrag: it provides a means
whereby you can put the psfrag commands
166 Labelling graphics into the preamble of your EPS file itself.
“Technical” graphics (such as graphs and di- Psfrag has such a command itself, but
agrams) are often labelled with quite com- deprecates it; psfragx has cleaned up the
plex mathematical expressions: there are facility, and provides a script laprint for
few drawing or graphing tools that can do use with Matlab to produce appropriately
such things (the honourable exception be- tagged output. (In principle, other graphics
ing Metapost, which allows you to pro- applications could provide a similar facil-
gram the labels, in (La)TeX, in the middle ity, but apparently none does.)
of specifying your graphic). Emacs users may find the embedded
Placing ‘labels’ on graphics produced editor iTe a useful tool for placing la-
by all those other tools is what we discuss bels: it’s a (La)TeX-oriented graphical ed-
here. (Note that the term “label” should itor written in Emacs Lisp. You create
be liberally interpreted; many of the tech- iteblock environments containing graph-
niques were designed for use when apply- ics and text, and may then invoke iTe to ar-
ing labels to figures, but they may be used range the elements relative to one another.
equally well to draw funny faces on a fig- Another useful approach is overpic,
ure . . . or anything. which overlays a picture environ-
The time-honoured psfrag package can ment on a graphic included by use of
help, if your image is included as an \includegraphics. This treatment lends
(encapsulated) PostScript file. Place an itself to ready placement of texts and the
unique text in your graphic, using the nor- like on top of a graphic. The package can
mal text features of your tool, and you can draw a grid for planning your “attack”; the
ask psfrag to replace the text with arbi- distribution comes with simple examples.
trary (La)TeX material. Psfrag’s “opera- The lpic package is somewhat simi-
tive” command is \psfrag{Orig text} lar to overpic; it defines an environment
{Repl text}, which instructs the system lpic (which places your graphic for you):
to replace the original (“unique”) text with within the environment you may use the
the TeX-typeset replacement text. Op- command \lbl to position LaTeX material
tional arguments permit adjustment of po- at appropriate places over the graphic.
sition, scale and rotation; full details may Pinlabel is another package whose au-
be found in pfgguide in the distribution. thor thought in the same sort of way as that
Since psfrag works in terms of (en- of overpic; the documentation explains in
capsulated) PostScript files, it needs extra detail how to plan your ‘labelling attack’ —
work for use with PDFLaTeX. Two tech- in this case by loading your figure into
niques are available, using pst-pdf package a viewer and taking measurements from
in a mode designed to do this work; and it. (The package discusses direct use of
using pdfrack. ghostscript as well as customised viewers
The Pst-pdf package can support this such as gsview or gv.)
“extra work” usage. In fact, the pst-pdf sup- Pstricks can of course do everything
port package auto-pst-pdf offers a configu- that overpic, lpic or pinlabel can, with all
ration setting precisely for use with psfrag. the flexibility of PostScript programming
If you have the ‘right’ environment that it offers. This capability is exemplified
(see below), you could try the pdfrack by the pst-layout package, which seems to
script bundle. The script aims to cut be a superset of both overpic and lpic.
each figure out of your source, using it Similarly, pgf/ TikZ has all the power
93
needed, but no explicit package has been BibTeX finds what entry types are permis-
released. sible, what fields each entry type has, and
The pstricks web site has a page with how to format the whole entry.
several examples of labelling which will The type specifies the type of docu-
get you started; if pstricks is an option for ment you’re making reference to; it may
you, this route is worth a try. run all the way from things like “Book”
The confident user may, of course, and “Proceedings” (which may even
do the whole job in a picture environ- contain other citations of type “InBook”
ment which itself includes the graphic. I or “InProceedings”) through disserta-
would recommend overpic or the pstricks tion styles like “PhdThesis” to otherwise-
approach, but such things are plainly lit- uncategorisable things such as “Misc”.
tle more than a convenience over what The unique key is something you choose
is achievable with the do-it-yourself ap- yourself: it’s what you use when you want
proach. to cite an entry in the file. People com-
auto-pst-pdf.sty :
monly create a key that combines the (pri-
macros/latex/contrib/auto-
mary) author’s name and the year of pub-
pst-pdf
lication, possibly with a marker to distin-
guish publications in the same year. So,
gv : support/gv for example, the Dyson, Eddington, David-
iTe: support/ite son paper about deflection of starlight ap-
pears in my experimental .bib file as
laprint: Distributed with
Dyson20.1.
macros/latex/contrib/psfragx
So, noting the rules of the style, you
lpic.sty : have ‘simply’ to write a bibliography
macros/latex/contrib/lpic database. Fortunately, there are several
overpic.sty : tools to help in this endeavour:
macros/latex/contrib/overpic • Most of the better (La)TeX-oriented
pdfrack : support/pdfrack editors have “BibTeX modes”.
• If you have an existing
pinlabel.sty :
thebibliography environment, the
macros/latex/contrib/pinlabel
Perl script tex2bib will probably help.
pgf.sty : graphics/pgf/base • There are a number of BibTeX bibli-
psfrag.sty : ography management systems avail-
macros/latex/contrib/psfrag able, some of which permit a graph-
ical user interface to the task. Sadly,
psfragx.sty :
none seems to be available with the
macros/latex/contrib/psfragx
ordinary TeX distributions.
pstricks.sty : graphics/pstricks Tools such as Xbibfile (a graphical user
pst-layout.sty : graphics/
interface), ebib (a database applica-
pstricks/contrib/pst-layout
tion written to run ‘inside’ emacs) and
btOOL (a set of perl tools for building
pst-pdf.sty : BibTeX database handlers) are avail-
macros/latex/contrib/pst-pdf able from CTAN.
Other systems, such as RefDB, Bi-
bORB, BibDesk, pybliographer and
N Bibliographies and ci- the Java-based Bibkeeper and JabRef
tations (which claims to supersede Bibkeeper)
are only available from their develop-
N.1 Creating bibliographies ment sites.
• Some commercial citation-
167 Creating a BibTeX bibliography management systems will export in
file BibTeX format; an example is End-
A BibTeX bibliography file may reason- Note.
ably be compared to a small database, the • Data from on-line citation databases
entries in which are references to litera- may often be translated to BibTeX for-
ture that may be called up by citations in a mat by utilities to be found on CTAN.
document. For example, the Perl script isi2bibtex
Each entry in the bibliography has a will translate citations from ISI “Web
type and a unique key. The bibliography of knowledge” (a subscription service,
is read, by BibTeX, using the details speci- available to UK academics via BIDS).
fied in a bibliography style. From the style, UK academics may translate BIDS
94
 downloads using bids.to.bibtex biblatex.sty :
• Google Scholar provides an “Import macros/latex/contrib/biblatex
into BibTeX” tab for each reference biblatex contributed styles:
it finds for you: that tab gives you a macros/latex/contrib/
page containing a BibTeX entry for biblatex-contrib
the reference.
BibTeX documentation:
bids.to.bibtex : biblio/bibtex/ biblio/bibtex/base
utils/bids/bids.to.bibtex makebst.tex : Distributed with
btOOL: biblio/bibtex/utils/btOOL macros/latex/contrib/custom-
bib
ebib: biblio/bibtex/utils/ebib
169 Capitalisation in BibTeX
isi2bibtex : biblio/bibtex/utils/
The standard BibTeX bibliography styles
isi2bibtex
impose fixed ideas about the capitalisa-
tex2bib: biblio/bibtex/utils/ tion of titles of things in the bibliogra-
tex2bib/tex2bib phy. While this is not unreasonable by
tex2bib.readme: biblio/bibtex/
BibTeX’s lights (the rules come from the
utils/tex2bib/README
Chicago Manual of Style) it can be trou-
blesome, since BibTeX fails to recognise
xbibfile: special uses (such as acronyms, chemical
biblio/bibtex/utils/xbibfile formulae, etc.).
The solution is to enclose the letter
168 Creating a bibliography style
or letters, whose capitalisation BibTeX
It is possible to write your own: the stan- should not touch, in braces, as:
dard bibliography styles are distributed in
a form with many comments, and there is a title = {The {THE} operating system},
description of the language in the BibTeX Sometimes you find BibTeX changing the
distribution (see BibTeX documentation). case of a single letter inappropriately. No
However, it must be admitted that the lan- matter: the technique can be applied to
guage in which BibTeX styles are written single letters, as in:
is pretty obscure, and one would not rec-
ommend anyone who’s not a confident pro- title = {Te{X}niques and tips},
grammer to write their own, though minor If your document design specification re-
changes to an existing style may be within quires a different style of capitalisation,
the grasp of many. you should acquire a bibliography style
If your style isn’t too ‘far out’, you that doesn’t enforce BibTeX’s default rules.
can probably avoid programming it by us- It is definitely not a good idea to enclose
ing the facilities of the custom-bib bundle. an entire title in braces, as in
The bundle contains a file makebst.tex,
which runs you through a text menu to pro- title = {{TeXniques and tips}},
duce a file of instructions, which you can though that does ensure that the capitalisa-
then use to generate your own .bst file. tion is not changed. Your BibTeX database
This technique doesn’t offer entirely new should be a general-purpose thing, not
styles of document, but the custom-bib’s something tuned to the requirements of a
“master BibTeX styles” already offer sig- particular document or bibliography style,
nificantly more than the BibTeX standard or to the way you are thinking today — for
set. example, on a future occasion, you might
An alternative, which is increasingly find yourself using a different BibTeX style
often recommended, to use biblatex. with different capitalisation rules.
Biblatex offers many hooks for adjusting There’s more on the subject in the Bib-
the format of the output of your ‘basic’ TeX documentation.
BibTeX style, and a collection of ‘con-
tributed’ styles have also started to appear. 170 Accents in bibliographies
Note.bowever There are not as many of BibTeX not only has a tendency (by de-
biblatex’s contributed styles as there are for fault) to mess about with the case of letters
BibTeX, and there is no custom-biblatex, in your bibliography, also makes a hash
both of which suggest that beginners’ röle of accent commands: “ma\~nana” comes
models are hard to come by. As a result, be- out as “ma nana” (!). The solution is sim-
ginners should probably resist the tempta- ilar that of the letter case problem: en-
tion to write their own contributed biblatex close the troublesome sequence in braces,
style. as “{\~n}”, in this example.
95
171 ‘String too long’ in BibTeX you will confuse BibTeX, and the output
The BibTeX diagnostic “Warning–you’ve produced will be quite different from what
exceeded 1000, the global-string-size, you had hoped.
for entry foo” usually arises from a very Names should be expressed in one of
large abstract or annotation included in the the forms
database. The diagnostic usually arises First Last
because of an infelicity in the coding of Last, First
abstract.bst, or styles derived from it. Last, Suffix, First
(One doesn’t ordinarily output annotations
in other styles.) and lists of names should be separated with
The solution is to make a copy “and”. For example:
of the style file (or get a clean copy
AUTHOR = {Fred Q. Bloggs, John P. Doe \&
from CTAN — biblio/bibtex/utils/
Another Idiot}
bibtools/abstract.bst), and rename
it (e.g., on a long file-name system, to falls foul of two of the above rules: a syn-
abstract-long.bst). Now edit it: find tactically significant comma appears in an
function output.nonnull and incorrect place, and ‘\&’ is being used as
a name separator. The output of the above
• change its first line (line 60 in the ver-
might be something like:
sion on CTAN) from
{ ’s := John P. Doe \& Another Idiot Fred Q. Bloggs

to because “John P. Doe & Another Idiot has

{ swap$
become the ‘first name’, while “Fred Q.
Bloggs” has become the ‘last name’ of a
Finally, single person. The example should have
• delete the function’s last line, which been written:
just says “s (line 84 in the version on
CTAN). AUTHOR = {Fred Q. Bloggs and John P. Doe and
Another Idiot}
Finally, change your \bibliographystyle
command to refer to the name of the new Some bibliography styles implement
file. clever acrobatics with very long author
This technique applies equally to any lists. You can force truncation by using
bibliography style: the same change can the pseudo-name “others”, which will
be made to any similar output.nonnull usually translate to something like “et al”
function. in the typeset output. So, if Mr. Bloggs
If you’re reluctant to make this sort of wanted to distract attention from his co-
change, the only way forward is to take authors, he would write:
the entry out of the database, so that you AUTHOR = {Fred Q. Bloggs and others}
don’t encounter BibTeX’s limit, but you
may need to retain the entry because it will 173 URLs in BibTeX bibliographies
be included in the typeset document. In There is no citation type for URLs, per
such cases, put the body of the entry in a se, in the standard BibTeX styles, though
separate file: Oren Patashnik (the author of BibTeX) is
@article{long.boring,
believed to be considering developing one
author = "Fred Verbose",
such for use with the long-awaited BibTeX
...
version 1.0.
abstract = "{\input{abstracts/long.tex}}"
The actual information that need be
}
available in a citation of an URL is dis-
cussed at some length in the publicly avail-
In this way, you arrange that all BibTeX able on-line extracts of ISO 690–2; the
has to deal with is the file name, though it techniques below do not satisfy all the re-
will tell TeX (when appropriate) to include quirements of ISO 690–2, but they offer a
all the long text. solution that is at least available to users of
today’s tools.
172 BibTeX doesn’t understand lists Until the new version of BibTeX ar-
of names rives, the simplest technique is to use the
BibTeX has a strict syntax for lists of au- howpublished field of the standard styles’
thors’ (or editors’) names in the BibTeX @misc function. Of course, the strictures
data file; if you write the list of names in about typesetting URLs still apply, so the
a “natural”-seeming way, the chances are entry will look like:
96
 @misc{..., either of the url or hyperref packages de-
..., tects this “%–end-of-line” structure in its
argument, and removes it.
howpublished = "\url{http://...}"
} babelbib bundle: biblio/bibtex/
contrib/babelbib
A possible alternative approach is to use
BibTeX styles other than the standard ones, custom-bib bundle:
that already have URL entry types. Candi- macros/latex/contrib/custom-
dates are: bib

• The natbib styles (plainnat, unsrtnat harvard.sty :

and abbrevnat), which are extensions macros/latex/contrib/harvard
of the standard styles, principally hyperref.sty :
for use with natbib itself. How- macros/latex/contrib/hyperref
ever, they’ve acquired URLs and other natbib styles:
“modern” entries along the way. The macros/latex/contrib/natbib
same author’s custom-bib is also ca-
pable of generating styles that honour url.sty : macros/latex/contrib/url
URL entries. urlbst:
• The babelbib bundle, which offers biblio/bibtex/contrib/urlbst
multilingual bibliographies, similarly
provides a set of standard-style equiv- 174 Using BibTeX with Plain TeX
alents that have URL entries. The file btxmac.tex (which is part of the
• More modern styles such as the Eplain system) contains macros and doc-
harvard package (if the citation styles umentation for using BibTeX with Plain
are otherwise satisfactory for you). TeX, either directly or with Eplain. See the
Harvard bibliography styles all in- use of BibTeX for more information about
clude a “url” field in their specifi- BibTeX itself.
cation; however, the typesetting of- btxmac.tex :
fered is somewhat feeble (though it macros/eplain/tex/btxmac.tex
does recognise and use LaTeX2HTML
macros if they are available, to create eplain system: macros/eplain
hyperlinks). 175 Reconstructing .bib files
You can also acquire new BibTeX styles Perhaps you’ve lost the .bib file you gen-
by use of Norman Gray’s urlbst system, erated your document from, or have been
which is based on a Perl script that edits sent a document without one. Or even,
an existing BibTeX style file to produce a you’ve realised the error of building a sub-
new style. The new style thus generated stantial document without the benefit of
has a webpage entry type, and also offers BibTeX. . .
support for url and lastchecked fields The Perl script, tex2bib makes a rea-
in the other entry types. The Perl script sonable job of regenerating .bib files
comes with a set of converted versions of from thebibliography environments,
the standard bibliography styles. provided that the original (whether auto-
Another possibility is that some matically or manually generated) doesn’t
conventionally-published paper, technical deviate too far from the “standard” styles.
report (or even book) is also available on You are well-advised to check the out-
the Web. In such cases, a useful technique put of the script. While it will not usually
is something like: destroy information, it can quite reason-
ably mislabel it.
@techreport{..., Documentation of the script is to be
..., found in the file tex2bib.readme
note = "Also available as \url{http://...}"
tex2bib: biblio/bibtex/utils/
}
tex2bib/tex2bib
There is good reason to use the url or tex2bib.readme: biblio/bibtex/
hyperref packages in this context: BibTeX utils/tex2bib/README
has a habit of splitting lines it considers
excessively long, and if there are no space 176 BibTeX sorting and name
characters for it to use as ‘natural’ break- prefixes
points, BibTeX will insert a comment (‘%’) BibTeX recognises a bewildering array
character . . . which is an acceptable char- of name prefixes (mostly those deriving
acter in an URL. Any current version of from European language names); it ignores
97
the prefixes when sorting the bibliogra- Note that the “Yu” is the initial, not a
phy — you want “Ludwig van Beethoven” complete name. However, BibTeX’s al-
sorted under “Beethoven”, not under “van”. gorithms will leave you with a citation —
(Lamport made a witty deliberate mistake slightly depending on the bibliographic
with Beethoven’s name, in the first edition style — that reads: “S. Y. Epifanov and A.
of his LaTeX manual.) A. Vigasin, . . . ”. instead of the intended
However, a recurring issue is the de- “S. Yu. Epifanov and A. A. Vigasin, . . . ”.
sire to quote Lord Rayleigh’s publications One solution is to replace each affected
(“Lord” isn’t an acceptable prefix), or initial by a command that prints the correct
names from languages that weren’t con- combination. To keep your bibliography
sidered when BibTeX was designed such portable, you need to add that command
as “al-Wakil” (transcribed from the Ara- to your bibliography with the @preamble
bic). What’s needed is a separate “sort directive:
key”, but BibTeX only allows such a thing
@preamble{ {\providecommand{\BIBYu}{Yu} } }
in citations of items that have no author or
editor.
@article{epifanov1997,
The solution is to embed the sort key
author = {Epifanov, S. {\BIBYu}. and Vigasin, A. A
in the author’s name, but to prevent it from
title = ...
being typeset. Patashnik recommends a
}
command \noopsort (no-output-sortkey),
which is defined and used as follows:If you have many such commands, you
may want to put them in a separate file and
@PREAMBLE{ {\providecommand{\noopsort}[1]{}} }
\input that LaTeX file in a @preamble
...
directive.
@ARTICLE{Rayleigh1,
An alternative is to make the transcrip-
AUTHOR = "{\noopsort{Rayleigh}}{Lord Rayleigh}",
tion look like an accent, from BibTeX’s
...
point of view. For this we need a control
}
sequence that does nothing:
Note that this \noopsort applies to the @article{epifanov1997,
last name in this kind of construct, so an author = {Epifanov, S. {\relax Yu}. and Vigasin, A
author with an Arabic name might be ren- title = ...
dered: }

... Like the solution by generating extra com-

mands, this involves tedious extra typing;
AUTHOR = "Ali {\noopsort{Hadiidii}}{al-Hadiidii}",
... which of the two techniques is preferable
for a given bibliography will be determined
A further use might deal with word order by the names in it. It should be noted that
games, as in the famous Vietnamese name: a preamble that introduces lots of odd com-
mands is usually undesirable if the bibliog-
... raphy is a shared one.
AUTHOR = "\noopsort{Thanh Han The}{Han The Thanh}",
“Compound” initials (for single names
... made up of two or more words) may be
treated in the same way, so one can enter
though that author seems well-acquainted Forster’s rather complicated name as:
with Western confusion about the signifi-
cance of the parts of his name (even to the @article{forster2006,
extent of missing out the accentuation, as author = {Forster, P.M. {\relax de F.} and Collins,
above. . . ). title = ...

177 ‘Multi-letter’ initials in BibTeX The same trick can be played if you’re en-
tering whole names:
If your bibliographic style uses initials +
surname, you may encounter a problem ...
with some transcribed names (for exam- author = {Epifanov, Sasha {\relax Yu}ri and
ple, Russian ones). Consider the following ...
example from the real world:
(though no guarantee, that either of those
@article{epifanov1997, names is right, is offered!) However, if
you’re
author = {Epifanov, S. Yu. and typing the
Vigasin, A. names
A.}, in the “natural”
title = ... (Western) way, with given names first, the
} trick:
98
 ... Don’t try to tell BibTeX anything but the
author file Forster
= {P.M. {\relax de F.} name: sayand
bibtex myfile.aux (be-
... cause you know it’s going to read the .aux
file) and BibTeX will blindly attempt to
doesn’t work — “de F. Forster” is treated process myfile.aux.aux.
as a compound family names. BibTeX will scan the .aux file; it will
find which bibliography style it needs to
N.2 Creating citations use, and will “compile” that style; it will
note the citations; it will find which bibli-
178 “Normal” use of BibTeX from
ography files it needs, and will run through
LaTeX
them matching citations to entries in the
To create a bibliography for your docu- bibliography; and finally it will sort the
ment, you need to perform a sequence of entries that have been cited (if the bibliog-
steps, some of which seem a bit odd. If raphy style specifies that they should be
you choose to use BibTeX, the sequence sorted), and outputs the resulting details to
is: a .bbl file.
First: you need a BibTeX bibliography Fifth: you run LaTeX again. It warns,
file (a .bib file) — see “creating a BibTeX again, that each citation is (still) undefined,
file”. but when it gets to the \bibliography
Second: you must write your LaTeX command, it finds a .bbl file, and reads
document to include a declaration of the it. As it encounters each \bibitem com-
‘style’ of bibliography, citations, and a ref- mand in the file, it notes a definition of the
erence to the bibliography file mentioned citation.
above. So we may have a LaTeX file con- Sixth: you run LaTeX yet again. This
taining: time, it finds values for all the citations,
in its .aux file. Other things being equal,
\bibliographystyle{plain} you’re done. . . until you change the file.
... If, while editing, you change any of
Pooh is heroic~\cite{Milne:1926}. the citations, or add new ones, you need to
... go through the process above from steps 3
Alice struggles~\cite{Carroll:1865}. (first run of LaTeX) to 6, again, before the
... document is once again stable. These four
\bibliography{mybooks} mandatory runs of LaTeX make processing
a document with a bibliography even more
Note: we have bibliography style plain, tiresome than the normal two runs required
above, which is nearly the simplest to resolve labels.
of the lot: a sample text, show- To summarise: processing to resolve ci-
ing the sorts of style choices avail- tations requires: LaTeX; BibTeX; LaTeX;
able, can be found on Ken Turner’s LaTeX.
web site: http://www.cs.stir.ac.uk/
~kjt/software/latex/showbst.html 179 Choosing a bibliography style
Third: you must process the file. A large proportion of people are satis-
fied with one of Patashnik’s original “stan-
latex myfile dard” styles, plain, unsrt, abbrv and alpha.
However, no style in that set supports the
As LaTeX processes the file, the “author-date” citation style that is popular
\bibliographystyle command writes in many fields; but there are a very large
a note of the style to the .aux file; number of contributed styles available, that
each \cite command writes a note of do support the format.
the citation to the .aux file, and the (Note that author-date styles arose be-
\bibliography command writes a note cause the simple and clear citation style
of which .bib file is to be used, to the that plain produces is so awkward in a tra-
.aux file. ditional manuscript preparation scenario.
Note that, at this stage, LaTeX isn’t However, TeX-based document production
“resolving” any of the citations: at every does away with all those difficulties, leav-
\cite command, LaTeX will warn you ing us free once again to use the simple
of the undefined citation, and when the option.)
document finishes, there will be a further Fortunately, help is at hand, on the
warning of undefined references. Web, with this problem:
Fourth: you must run BibTeX:
• a sample text, showing the sorts of
bibtex myfile style choices available, can be found
99
 on Ken Turner’s web site; Some text \cite{this}
• an excellent survey, that lists a huge with citations \cite{that}.
variety of styles, sorted into their nom- \printbibliography
inal topics as well as providing a good \end{refsection}
range of examples, is the Reed Col-
lege “Choosing a BibTeX style”. Then process with LaTeX (of what-
ever flavour) and use biber to pro-
Of course, these pages don’t cover ev- cess the bibliography output. Note
erything; the problem the inquisitive user that \printbibliography can take an
faces, in fact, is to find what the various optional argument heading=bib title
available styles actually do. This is best to provide the bibliography with a
achieved (if the links above don’t help) by (sub)section title.
using xampl.bib from the BibTeX docu-
biber : biblio/biber
mentation distribution: one can get a pretty
good feel for any style one has to hand us- biblatex :
ing this “standard” bibliography. For style macros/latex/contrib/biblatex
my-style.bst, the simple LaTeX document: bibunits.sty :
macros/latex/contrib/bibunits
\documentclass{article}
\begin{document} chapterbib.sty : distributed as part of
\bibliographystyle{my-style} macros/latex/contrib/cite
\nocite{*}
181 Multiple bibliographies?
\bibliography{xampl}
\end{document} If you’re thinking of multiple bibliogra-
phies tied to some part of your document
will produce a representative sample of the (such as the chapters within the document),
citations the style will produce. (Because please see bibliographies per chapter.
xampl.bib is so extreme in some of its “ex- For more than one bibliography, there
amples”, the BibTeX run will also give you are three options.
an interesting selection of BibTeX’s error The multibbl package offers a very
messages. . . ) simple interface: you use a command
xampl.bib: \newbibliography to define a bibliogra-
biblio/bibtex/base/xampl.bib phy “tag”. The package redefines the other
bibliography commands so that each time
180 Separate bibliographies per
you use any one of them, you give it the tag
chapter?
for the bibliography where you want the
A separate bibliography for each ‘chapter’ citations to appear. The \bibliography
of a document can be provided with the command itself also takes a further extra
package chapterbib (which comes with a argument that says what title to use for the
bunch of other good bibliographic things). resulting section or chapter (i.e., it patches
The package allows you a different bibli- \refname and \bibname — \refname
ography for each \included file (i.e., de- and \bibname — in a babel-safe way). So
spite the package’s name, the availability one might write:
of bibliographies is related to the compo-
nent source files of the document rather \usepackage{multibbl}
than to the chapters that logically structure \newbibliography{bk}
the document). \bibliographystyle{bk}{alpha}
The package bibunits ties bibliogra- \newbibliography{art}
phies to logical units within the document: \bibliographystyle{art}{plain}
the package will deal with chapters and ...
sections (as defined by LaTeX itself) and \cite[pp.~23--25]{bk}{milne:pooh-corner}
also defines a bibunit environment so ...
that users can select their own structuring. \cite{art}{einstein:1905}
The biblatex package, with biber, pro- ...
vides a similar facility; enclose the text \bibliography{bk}{book-bib}{References to books}
for which you want a local bibliography \bibliography{art}{art-bib}{References to articles}
in a refsection environment, and place
a \printbibliography command as the (Note that the optional argument of \cite
last thing in that environment: appears before the new tag argument, and
that the \bibliography commands may
\begin{refsection} list more than one .bib file — indeed all
\chapter{First chapter} \bibliography commands may list the
\section{Foo} same set of files.)
100
 The \bibliography data goes into Note the different way of specifying a bib-
files whose names are htag-namei.aux, so liographystyle: if you want a different style
you will need to run for a particular bibliography, you may give
it as an optional argument to the btSect
bibtex bk
environment.
bibtex art
Processing with BibTeX, in this case,
after the first run of LaTeX, to get the cita- uses .aux files whose names are derived
tions in the correct place. from the name of the base document. So
The multibib package allows you to de- in this example you need to say:
fine a series of “additional topics”, each of
which comes with its own series of bibli- bibtex diss1
ography commands. So one might write: bibtex diss2

\usepackage{multibib} There is also a command

\newcites{bk,art}% \btPrintNotCited, which gives the rest
of the content of the database (if nothing
{References from books,%
has been cited from the database, this is
References from articles}
\bibliographystylebk{alpha} equivalent to LaTeX standard \nocite
\bibliographystyleart{plain} {*}).
... However, the real difference from
multibbl and multibib is that selection of
\citebk[pp.~23--25]{milne:pooh-corner}
... what appears in each bibliography section
\citeart{einstein:1905} is determined in bibtopic by what’s in the
... .bib files.
\bibliographybk{book-bib} An entirely different approach is taken
\bibliographyart{art-bib} by the splitbib package. You provide
a category environment, in the pream-
Again, as for multibbl, any
ble of your document, for each category
\bibliography... command may scan
you want a separate citation list for. In
any list of .bib files.
each environment, you list the \cite keys
BibTeX processing with multibib is
that you want listed in each category.
much like that with multibbl; with the
The \bibliography command (or, more
above example, one needs:
precisely, the thebibliography environ-
bibtex bk ment it uses) will sort the keys as requested.
bibtex art (Keys not mentioned in a category appear
in a “misc” category created in the sorting
Note that, unlike multibbl, multibib allows
process.) A code example appears in the
a simple, unmodified bibliography (as well
package documentation (a PDF file in the
as the “topic” ones).
CTAN directory, see the file list, below).
The bibtopic package allows you sep-
arately to cite several different bibliogra- bibtopic.sty :
phies. At the appropriate place in your doc- macros/latex/contrib/bibtopic
ument, you put a sequence of btSect en- multibbl.sty :
vironments (each of which specifies a bib- macros/latex/contrib/multibbl
liography database to scan) to typeset the
multibib.sty :
separate bibliographies. Thus, one might
macros/latex/contrib/multibib
have a file diss.tex containing:
splitbib.sty :
\usepackage{bibtopic}
macros/latex/contrib/splitbib
\bibliographystyle{alpha}
... 182 Putting bibliography entries in
\cite[pp.~23--25]{milne:pooh-corner} text
... This is a common requirement for journals
\cite{einstein:1905} and other publications in the humanities.
... Sometimes the requirement is for the entry
\begin{btSect}{book-bib} to appear in the running text of the doc-
\section{References from books} ument, while other styles require that the
\btPrintCited entry appear in a footnote.
\end{btSect} Options for entries in running text are
\begin{btSect}[plain]{art-bib}
\section{References from articles}• The package bibentry, which puts
\btPrintCited slight restrictions on the format of en-
\end{btSect} try that your .bst file generates, but
101
 is otherwise undemanding of the bib- The cite package sorts the numbers
liography style. and detects consecutive sequences, so cre-
• The package inlinebib, which re- ating “[2–4,6]”. The natbib package,
quires that you use its inlinebib. with the numbers and sort&compress op-
bst. Inlinebib was actually designed tions, will do the same when working
for footnote citations: its expected use with its own numeric bibliography styles
is that you place a citation inline as the (plainnat.bst and unsrtnat.bst).
argument of a \footnote command. The package biblatex has a built-in
• The package jurabib, which was origi- style numeric-comp for its bibliographies.
nally designed for German law doc- biblatex.sty :
uments, and has comprehensive fa- macros/latex/contrib/biblatex
cilities for the manipulation of cita-
tions. The package comes with four cite.sty :
bibliography styles that you may use: macros/latex/contrib/cite
jurabib.bst, jhuman.bst and two hypernat.sty :
Chicago-like ones. macros/latex/contrib/hypernat

Options for entries in footnotes are hyperref.sty :

macros/latex/contrib/hyperref
• The package footbib, and
• Packages jurabib and inlinebib, again. plainnat.bst: Distributed with
macros/latex/contrib/natbib
Note that jurabib does the job using La- unsrtnat.bst: Distributed with
TeX’s standard footnotes, whereas footbib macros/latex/contrib/natbib
creates its own sequence of footnotes.
Therefore, in a document which has other 184 Multiple citations
footnotes, it may be advisable to use A convention sometimes used in physics
jurabib (or of course inlinebib), to avoid journals is to “collapse” a group of related
confusion of footnotes and foot-citations. citations into a single entry in the bibli-
The usebib package offers a ‘toolbox’, ography. BibTeX, by default, can’t cope
which allows the user to place exactly with this arrangement, but the mcite and
what is needed, in the text (that is, rather mciteplus packages deal with the problem.
than a full citation). The package’s com- mcite overloads the \cite command
mand, that does the actual typesetting, is to recognise a “*” at the start of a key, so
\usebibdata{hkey i}{hfield i}; it type-
that citations of the form
sets the field item from the entry key in the
bibliography; the user then formats the en- \cite{paper1,*paper2}
try as desired — obviously one could con-
struct one’s own bibliography, altogether, appear in the document as a single citation,
from this command, but it would quickly and appear arranged appropriately in the
become tedious. bibliography itself. You’re not limited to
collapsing just two references. You can
bibentry.sty : Distributed with
mix “collapsed” references with “ordinary”
macros/latex/contrib/natbib
ones, as in
footbib.sty :
macros/latex/contrib/footbib \cite{paper0,paper1,*paper2,paper3}
inlinebib.sty : biblio/bibtex/
Which will appear in the document as 3 ci-
contrib/inlinebib
tations “[4,7,11]” (say) — citation ‘4’ will
jurabib.sty : refer to paper 0, ‘7’ will refer to a com-
macros/latex/contrib/jurabib bined entry for paper 1 and paper 2, and
usebib.sty : ‘11’ will refer to paper 3.
macros/latex/contrib/usebib You need to make a small change to
the bibliography style (.bst) file you use;
183 Sorting and compressing the mcite package documentation tells you
citations how to do that.
If you give LaTeX \cite{fred,joe,harry,min} Most
, recent versions of REVTeX (ver-
its default commands could give something sion 4.1 and later), in conjunction with re-
like “[2,6,4,3]”; this looks awful. One can cent versions of natbib, already contain
of course get the things in order by rear- support for combined citations and so no
ranging the keys in the \cite command, longer even need mciteplus (but mciteplus
but who wants to do that sort of thing for is more general and will work with many
no more improvement than “[2,3,4,6]”? other class and package combinations).
102
 The mciteplus package adresses many 186 Sorting lists of citations
of the infelicites of mcite. Again, ‘or- BibTeX has a sorting function, and most
dinary’ .bst files will not work with BibTeX styles sort the citation list they pro-
mciteplus, but the package documentation duce; most people find this desirable.
explains how to patch an existing BibTeX However, it is perfectly possible to
style. write a thebibliography environment
The collref package takes a rather dif- that looks as if it came from BibTeX, and
ferent approach to the problem, and will many people do so (in order to save time
work with most (if not all) BibTeX pack- in the short term).
ages. Collref spots common subsets of the The problem arises when
references, so if it sees a sequence thebibliography-writers decide their
citations need to be sorted. A com-
\cite{paper0,paper1,paper2,paper3} mon misapprehension is to insert
... \bibliographystyle{alpha} (or sim-
\cite{some_other_paper,paper1,paper2,and_another}
ilar) and expect the typeset output to be
sorted in some magical way. BibTeX
it will collect paper1 and paper2 as a mul-
doesn’t work that way! — if you write
tiple reference.
thebibliography, you get to sort its con-
collref.sty : tents. BibTeX will only sort the contents of
macros/latex/contrib/collref a thebibliography environment when it
mcite.sty :
creates it, to be inserted from a .bbl file
macros/latex/contrib/mcite
by a \bibliography command.
187 Reducing spacing in the
mciteplus.sty : macros/latex/
bibliography
contrib/mciteplus
Bibliographies are, in fact, implemented as
natbib.sty : lists, so all the confusion about reducing
macros/latex/contrib/natbib list item spacing also applies to bibliogra-
revtex 4.1: phies.
macros/latex/contrib/revtex If the natbib package ‘works’ for you
(it may not if you are using some special-
185 References from the bibliography purpose bibliography style), the solution is
to the citation relatively simple — add
A link (or at least a page reference), from \usepackage{natbib}
the bibliography to the citing command, is \setlength{\bibsep}{0.0pt}
often useful in large documents. to the preamble of your document.
Two packages support this require- The compactbib package has a similar
ment, backref and citeref . Backref is part effect. Its primary purpose is to produce
of the hyperref bundle, and supports hy- two bibliographies, and it seems to pre-
perlinks back to the citing command. clude use of BibTeX (though the package
Citeref is the older, and seems to rely documentation, in the package file itself,
on rather simpler (and therefore possibly isn’t particularly clear).
more stable) code; it produces a list of page Otherwise, one is into unseemly hack-
references, only. It doesn’t interact well ing of something or other. The mdwlist
with other citation packages (for example, package actually does the job, but it
cite), which probably reflects its antiquity doesn’t work here, because it makes
(it’s derived from a LaTeX 2.09 package). a different-named list, while the name
Neither collapses lists of pages (“5, 6, “thebibliography” is built into LaTeX
7” comes out as such, rather than as “5-7”), and BibTeX. Therefore, we need to patch
but neither package repeats the reference to the underlying macro:
a page that holds multiple citations. (The
\let\oldbibliography\thebibliography
failure to collapse lists is of course for-
\renewcommand{\thebibliography}[1]{%
giveable in the case of the hyperref -related
\oldbibliography{#1}%
backref , since the concept of multiple hy-
\setlength{\itemsep}{0pt}%
perlinks from the same anchor is less than
}
appealing.)
backref.sty : Distributed with
The savetrees package performs such a
macros/latex/contrib/hyperref
patch, among a plethora of space-saving
measures: you can, in principle, suppress
citeref.sty : all its other actions, and have it provide
macros/latex/contrib/citeref you a compressed bibliography only.
103
compactbib.sty : using biblatex, which can produce a bibli-
macros/latex/contrib/ ography appropriate to several languages.
compactbib/compactbib.sty However, biblatex is large and has corre-
mdwlist.sty : Distributed as part of
spondingly large documentation (though it
macros/latex/contrib/mdwtools
is well-written and pleasingly typeset), so
its adoption takes time.
natbib.sty : Otherwise, the simplest procedure is
macros/latex/contrib/natbib to provide translations of BibTeX styles
savetrees.sty : macros/latex/ into the required language: the solitary
contrib/savetrees finplain.bst does that for Finnish; oth-
ers one can find are for Danish (dk-bib),
188 Table of contents rearranges French (bib-fr), German (bibgerm), Nor-
“unsrt” ordering wegian (norbib) and Swedish (swebib) bun-
If you’re using the unsrt bibliography style, dles (of which the bib-fr set is the most
you’re expecting that your bibliography extensive). The spain style implements a
will not be sorted, but that the entries will traditional Spanish citation style.
appear in the order that they first appeared These static approaches solve the prob-
in your document. lem, for the languages that have been cov-
However, if you’re unfortunate enough ered by them. Unfortunately, with such
to need a citation in a section title, and you an approach, a lot of work is needed for
also have a table of contents, the citations every language involved. Two routes to
that now appear in the table of contents a solution of the “general” problem are
will upset the “natural” ordering produced available — that offered by babelbib, and
by the unsrt style. Similarly, if you have the custom-bib mechanism for generating
citations in captions, and have a list of fig- styles.
ures (or tables). Babelbib (which is a development of
There’s a pretty simple “manual” the ideas of the bibgerm package) co-
method for dealing with the problem — operates with babel to control the language
when you have the document stable: of presentation of citations (potentially at
the level of individual items). The package
1. Delete the .aux file, and any of .toc, has a built-in set of languages it ‘knows
.lof, .lot files. about’, but the documentation includes in-
2. Run LaTeX. structions on defining commands for other
3. Run BibTeX for the last time. languages. Babelbib comes with its own
4. Run LaTeX often enough that things set of bibliography styles, which could be
are stable again. a restriction if there wasn’t also a link from
Which is indeed simple, but it’s going to custom-bib.
get tedious when you’ve found errors in The makebst menu of custom-bib al-
your “stable” version, often enough. lows you to choose a language for the
The package notoccite avoids the ker- BibTeX style you’re generating (there are
fuffle, and suppresses citations while in the 14 languages to choose; it looks as if
table of contents, or lists of figures, tables spain.bst, mentioned above, was generated
(or other floating things: the code is quite this way). If, however, you opt not to spec-
general). ify a language, you are asked whether you
want the style to interact with babelbib;
notoccite.sty : macros/latex/ if you do so, you’re getting the best of
contrib/notoccite both worlds — formatting freedom from
189 Non-english bibliographies custom-bib and linguistic freedom via the
extensibility of babelbib
Like so much of early (La)TeX software,
BibTeX’s assumptions were firmly rooted babelbib.sty : biblio/bibtex/
in what its author knew well, viz., aca- contrib/babelbib
demic papers in English (particularly those bib-fr bundle:
with a mathematical bent). BibTeX’s stan- biblio/bibtex/contrib/bib-fr
dard styles all address exactly that problem, bibgerm bundle:
leaving the user who writes in another lan- biblio/bibtex/contrib/germbib
guage (or who deal with citations in the
style of other disciplines than maths) to biblatex.sty :
strike out into contributed software. macros/latex/contrib/biblatex
For the user whose language is not En- custom-bib bundle:
glish, there are several alternatives. Pos- macros/latex/contrib/custom-
sibly most straightforward is to switch to bib
104
finplain.bst: biblio/bibtex/ you have to run things), but the lack might
contrib/misc/finplain.bst confuse automatic processors that scan the
norbib bundle: log file to determine whether another run
biblio/bibtex/contrib/norbib is necessary.
A couple of packages are available,
spain: that aim to reduce the impact of \nocite
biblio/bibtex/contrib/spain {*} of a large citation database. Biblist
swebib bundle: was written for use under LaTeX 2.09, but
biblio/bibtex/contrib/swebib seems to work well enough; listbib is more
modern. Both provide their own .bst files.
190 Format of numbers in the
(The impact of large databases was signif-
bibliography
icant in the old days of LaTeX systems
By default, LaTeX makes entries in the with very little free memory; this problem
bibliography look like: is less significant now than it once was.)
[1] Doe, Joe et al. Some journal. biblist.sty : macros/latex209/
2004. contrib/biblist
[2] Doe, Jane et al. Some journal. listbib.sty :
2003. macros/latex/contrib/listbib
while many documents need something 192 Making HTML of your
like: Bibliography
1. Doe, Joe et al. Some journal. A neat solution is offered by the noTeX bib-
2004. liography style. This style produces a .bbl
2. Doe, Jane et al. Some journal. file which is in fact a series of HTML ‘P’
2003. elements of class noTeX, and which may
therefore be included in an HTML file. Pro-
This sort of change may be achieved by vision is made for customising your bibli-
many of the “general” citation packages; ography so that its content when processed
for example, in natbib, it’s as simple as: by noTeX is different from that presented
when it is processed in the ordinary way
\renewcommand{\bibnumfmt}[1]{#1.}
by (La)TeX.
but if you’re not using such a package, the A thorough solution is offered by
following internal LaTeX commands, in bib2xhtml; using it, you make use of one
the preamble of your document, will do of its modified versions of many common
the job: BibTeX styles, and post-process the output
so produced using a perl script.
\makeatletter A more conventional translator is the
\renewcommand*{\@biblabel}[1]{\hfill#1.}
awk script bbl2html, which translates the
\makeatother .bbl file you’ve generated: a sample of
the script’s output may be viewed on the
natbib.sty :
web, at http://rikblok.cjb.net/lib/
macros/latex/contrib/natbib
refs.html
N.3 Manipulating whole bbl2html.awk : biblio/bibtex/
bibliographies utils/misc/bbl2html.awk

191 Listing all your BibTeX entries bib2xhtml:

biblio/bibtex/utils/bib2xhtml
LaTeX and BibTeX co-operate to offer spe-
cial treatment of this requirement. The noTeX.bst: biblio/bibtex/utils/
command \nocite{*} is specially treated, misc/noTeX.bst
and causes BibTeX to generate bibliogra-
phy entries for every entry in each .bib file
listed in your \bibliography statement, O Adjusting the typeset-
so that after a LaTeX–BibTeX–LaTeX se- ting
quence, you have a document with the
whole thing listed. O.1 Alternative document
Note that LaTeX doesn’t produce classes
“Citation ... undefined” or “There
were undefined references” warn- 193 Replacing the standard classes
ings in respect of \nocite{*}. This isn’t People are forever concocting classes that
a problem if you’re running LaTeX “by replace the standard ones: the present au-
hand” (you know exactly how many times thor produced an ukart class that used the
105
sober package, and a few British-specific The ‘classic’ alternatives have been
things (such as appear in the babel pack- seminar and foils (originally known as Foil-
age’s British-english specialisation) in the TeX). Both were originally designed to pro-
1980s, which is still occasionally used. duce output on acetate foils, though subse-
Similar public efforts were available quent work has provided environments in
well back in the days of LaTeX 2.09: a which they can be used with screen projec-
notable example, whose pleasing designs tors (see below).
seem not to have changed much over all The advent of Microsoft PowerPoint
that time, is the ntgclass bundle. Each of (feeble though early versions of it were)
the standard classes is replaced by a selec- has created a demand for “dynamic”
tion of classes, named in Dutch, sometimes slides — images that develop their content
with a single numeric digit attached. So in a more elaborate fashion than by merely
we have classes artikel2, rapport1, boek3 replacing one foil with the next in the way
and brief . These classes are moderately that was the norm when slides, foils and
well documented in English. seminar were designed.
The KOMA-script bundle (classes The prosper class builds on seminar
named scr...) are a strong current contender. to provide dynamic effects and the like; it
They are actively supported and are sub- retains the ability to provide PDF for a pro-
ject to sensitive development; they are jected presentation, or to print foils for a
comprehensive in their coverage of sig- foil-based presentation. The add-on pack-
nificant typesetting issues; they produce age ppr-prv adds “preview” facilities (that
good-looking output and they are well doc- which is commonly called “hand-out print-
umented in both English (scrguien in the ing”). The HA-prosper package, which
distribution) and German (scrguide in the you load with prosper, mends a few bugs,
distribution). and adds several facilities and slide design
The other comparable class is memoir. styles. The (more recent) powerdot class is
This aims to replace book and report designed as a replacement for prosper and
classes directly, and (like KOMA-script) is HA-prosper, co-authored by the author of
comprehensive in its coverage of small is- HA-prosper.
sues. Memoir’s documentation (memman) Beamer is a relatively easy-to-learn,
is very highly spoken of, and its lengthy yet powerful, class that (as its name im-
introductory section is regularly recom- plies) was designed for use with projection
mended as a tutorial on typesetting. displays. It needs the pgf package (for
KOMA-script bundle: graphics support), which in turn requires
macros/latex/contrib/koma- xcolor; while this adds to the tedium of
script installing beamer “from scratch”, both are
good additions to a modern LaTeX instal-
memoir.cls: lation. Beamer has reasonable facilities for
macros/latex/contrib/memoir producing printed copies of slides.
NTGclass bundle: Talk is another highly functional, yet
macros/latex/contrib/ntgclass easy-to-learn class which claims to differ
from the systems mentioned above, such
sober.sty : macros/latex209/ as beamer, in that it doesn’t impose a slide
contrib/misc/sober.sty style on you. You get to specify a bunch of
slide styles, and you can switch from one
194 Producing presentations to the other between slides, as you need.
(including slides) The class itself provides just the one style,
Lamport’s original LaTeX had a separate in the package greybars: the author’s sug-
program (SliTeX) for producing slides; it gestion that users should contribute their
dates from the age when colour effects own has been enthusiastically accepted —
were produced by printing separate slides see (for example) the Beamer Gallery.
in different-coloured inks, and overlaying Lecturer is a generic solution (it works
them, and was just about acceptable back with Plain TeX, LaTeX and ConTeXt mk ii,
then. When LaTeX2e came along, the rea- but not — yet — with ConTeXt mk iv).
son SliTeX had to be a separate program By separating the functionality needed for
went away, and its functionality was sup- a presentation (using TeX for typesetting,
plied by the slides class. While this makes and PDF functions for layering and dy-
life a little easier for system administrators, namic effects) a clear structure emerges.
it does nothing for the inferior functional- While it doesn’t have the range of “themes”
ity of the class: no-one who “knows” uses (presentation styles) of beamer it seems a
slides nowadays. useful alternative candidate.
106
 Present is designed for use with Plain talk.cls:
TeX only; its design is simple, to the ex- macros/latex/contrib/talk
tent that its author hopes that users will texpower :
themselves be able to tune its macros. macros/latex/contrib/texpower
Ppower4 (commonly known as pp4)
xcolor.sty :
is a Java-based support program that will
macros/latex/contrib/xcolor
postprocess PDF, to ‘animate’ the file
at places you’ve marked with commands 195 Creating posters with LaTeX
from one of the pp4 packages. The There is no complete “canned solution” to
commands don’t work on PDF that has creating a poster (as, for example, classes
come from dvips output; they work with like seminar, powerdot and beamer serve
PDF generated by PDFLaTeX, LaTeX, or for creating presentations in a variety of
dvipdfm running on LaTeX output. styles).
Pdfscreen and texpower are add-on The nearest approach to the complete
packages that permit dynamic effects in solution is the sciposter class, which pro-
documents formatted in “more modest” vides the means to produce really rather
classes; pdfscreen will even allow you to good posters according to the author’s re-
plug “presentation effects” into an article- quired style. A complete worked example
class document. is provided with the distribution
A more detailed examination of Otherwise, there is a range of tools,
the alternatives (including examples most of which are based on the a0poster
of code using many of them) may be class, which sets up an appropriately-sized
found at Michael Wiedmann’s fine http: piece of paper, sets font sizes appropriately,
//www.miwie.org/presentations/ and leaves you to your own devices.
presentations.html Having used a0poster, you can of
ConTeXt users will find that much course slog it out, and write all your poster
(if not all) of what they need is already as an unadorned LaTeX document (pre-
in ConTeXt itself; there’s a useful sum- sumably in multiple columns, using the
mary of what’s available, with exam- multicol package), but it’s not really nec-
ples, in http://wiki.contextgarden. essary: the (straightforward) textpos pack-
net/Presentation_Styles age provides a simple way of positioning
beamer.cls: Download all of chunks of text, or tables or figures, on the
macros/latex/contrib/beamer poster page.
More sophisticated is the flowfram
foils.cls: package, whose basic aim in life is flowing
macros/latex/contrib/foiltex text from one box on the page to the next.
greybars.sty : distributed with One of the package’s design aims seems to
macros/latex/contrib/talk have been the production of posters, and a
worked example is provided. The author
HA-prosper.sty :
of flowfram has an experimental tool called
macros/latex/contrib/ha-
JpgfDraw, which allows you to construct
prosper
the outline of frames for use with flowfram.
lecturer.sty : The beamerposter package is added
macros/generic/lecturer to a beamer document to enable the user
seminar.cls:
to work as if in a a0poster class. Thus
macros/latex/contrib/seminar
beamer’s neat provisions for layout may
be used when creating the poster. Docu-
pdfscreen.sty : macros/latex/ mentation of beamerposter is sparse, but
contrib/pdfscreen an example file allows the user to get a grip
pgf.sty : graphics/pgf/base on what’s available.
Despite the relative shortage of tools,
powerdot.cls: there are a fair few web pages that ex-
macros/latex/contrib/powerdot plain the process (mostly in terms of the
pp4: support/ppower4 a0poster route):
ppr-prv.sty : • from Norman Gray, Producing posters
macros/latex/contrib/ppr-prv using LaTeX;
• from Nicola Talbot, Creating technical
present.tex :
posters with LaTeX
macros/plain/contrib/present
• From Rob Clark Advanced LaTeX
prosper.cls: Posters (which has links to code sam-
macros/latex/contrib/prosper ples);
107
 • from Brian Wolven, LaTeX Poster their own web sites, or otherwise available
Macros, Examples, and Accessories only upon application.
(this page also provides macros and Check that the publisher is offering you
other support suggestions); and macros suitable to an environment you can
• from “pjh” Making and printing a use: a few still have no macros for cur-
poster with LaTeX, which covers the rent LaTeX, for example, claiming that La-
specific issue of dealing with Univer- TeX 2.09 is good enough. . .
sity of Florida styled poster (offering Some publishers rekey anything sent
supporting material as necessary), but them anyway, so that it doesn’t really mat-
has hints which are generally useful. ter what macros you use. Others merely
encourage you to use as few extensions of
a0poster.cls: a standard package as possible, so that they
macros/latex/contrib/a0poster will find it easy to transform your paper to
beamer.cls: their own internal form.
macros/latex/contrib/beamer 198 A ‘report’ from lots of ‘article’s
beamerposter.sty : macros/latex/ This is a requirement, for example, if one is
contrib/beamerposter preparing the proceedings of a conference
flowfram.sty : whose papers were submitted in LaTeX.
macros/latex/contrib/flowfram The nearest things to canned solutions
are Peter Wilson’s combine and Federico
multicol.sty : Distributed as part of Garcia’s subfiles classes, but many ap-
macros/latex/required/tools proaches have been proposed. Each of of
sciposter.cls: macros/latex/ the offerings has its own advantages; in par-
contrib/sciposter ticular, several distinctly light-weight solu-
tions (for example, includex and docmute)
textpos.sty :
are available, well-suited to less formal
macros/latex/contrib/textpos
documents.
196 Formatting a thesis in LaTeX Combine defines the means to
Thesis styles are usually very specific to ‘\import’ entire documents, and provides
your University, so it’s usually not prof- means of specifying significant features of
itable to ask around for a package outside the layout of the document, as well as a
your own University. Since many Univer- global table of contents, and so on. The
sities (in their eccentric way) still require complete set of facilities is pretty complex.
double-spaced thesis text, you may also An auxiliary package, combinet, allows
need separately to set up double spacing. use of the \titles and \authors (etc.)
of the \imported documents to appear
If you want to write a new thesis class
in the global table of contents. The basic
of your own, a good place to start is the
structure of a combined document would
University of California style, but remem-
be:
ber that it’s often difficult to produce a the-
sis that both looks good and conforms with \documentclass[...]{combine}
the style that your Univeristy demands. ...
UC thesis style: \begin{document}
macros/latex/contrib/ucthesis ...
<introductory materiel>
197 Setting papers for journals ...
\begin{papers}
Publishers of journals have a wide range
% title and author of first article,
of requirements for the presentation of pa-
% to go the the main ToC
pers, and while many publishers do accept
\coltoctitle{...}
electronic submissions in (La)TeX, they
\coltocauthor{...}
don’t often submit recommended macros
\label{art1}
to public archives.
\import{art1}
Nevertheless, there are considerable
...
numbers of macros of one sort or another
\end{papers}
available on CTAN; searching for your
...
journal name in the CTAN catalogue —
<acknowledgements, etc.>
see searching CTAN) — may well turn
...
up what you’re seeking.
\end{document}
Failing that, you may be well advised
to contact the prospective publisher of your The subfiles class is used in the com-
paper; many publishers have macros on ponent files of a multi-file project, and the
108
corresponding subfiles package is used in The standalone package develops on
the master file; so the structure of the mas- the ideas of docmute; it was designed to
ter file looks like: meet the needs of users who are develop-
ing images from one of the more extreme
\documentclass{<whatever>} new graphics packages (notably pgf/ tikz)
... where the compile time of the graphics is
\usepackage{subfiles} such that separate compilation is very de-
... sirable. Standalone provides a means of
\begin{document} developing the graphics in a convenient
... way, detached from the development of the
\subfile{subfile_name} document as a whole; its value for use in
... multiple documents is clear.
\end{document} The user includes the standalone pack-
age in the main document, and each sub-
while a subfile has the structure: file uses the standalone class. (Standalone
uses article for the “real” work in stand-
\documentclass[mainfile_name]{subfiles}
alone mode, but it may be asked to use
\begin{document}
another).
...
The real difference from the docmute
\end{document}
package is flexibility. In particular, you
Arrangements may be made so that the can ask that the preambles of the included
component files will be typeset using dif- documents be gathered up, so that you can
ferent page format, etc., parameters than construct a good preamble for the master
those used when they are typeset as a part document.
of the main file. A final “compile-together” approach
comes from the subdocs package. The
A more ‘raw’ toolkit is offered by
driver file contains a \subdocuments com-
Matt Swift’s includex and newclude pack-
mand:
ages, both part of the frankenstein bun-
dle. Note that Matt believes includex is \subdocuments[options]
obsolete (though it continues to work for {file1, file2, ...}
this author); furthermore, its replacement, (the optional arguments provide layout
newclude remains “in development”, as it options, such as control over whether
has been since 1999. \clearpage or \cleardoublepage are
Both includex and newclude enable used between the files). Each of the sub-
you to ‘\includedoc’ complete articles files will execute
(in the way that you ‘\include’ chapter
files in an ordinary report). The preamble \usepackage[master]
(everything up to \begin{document}), {subdocs}
and everything after \end{document}, is to declare the name, master , of the call-
ignored by both packages. Thus the pack- ing file; each of the subfiles reads all the
ages don’t “do the whole job” for you, .aux files, so that tables of contents may
though: you need to analyse the package be produced.
use of the individual papers, and ensure A completely different approach is to
that a consistent set is loaded in the pream- use the pdfpages package, and to include
ble of the main report. (Both packages articles submitted in PDF format into a a
require moredefs, which is also part of the PDF document produced by PDFLaTeX.
bundle.) The package defines an \includepdf
A neat (and simple) toolkit is of- command, which takes arguments similar
fered by the docmute package; once to those of the \includegraphics com-
the package is loaded, anything be- mand. With keywords in the optional ar-
tween \documentclass[...]{...} and gument of the command, you can specify
\begin{document} in an \input’ed or which pages you want to be included from
\include’d document is ignored, and the file named, and various details of the
then the input is processed up to \end layout of the included pages.
{document} in the input file. The package
combine.cls:
does nothing about \usepackage (or any-
macros/latex/contrib/combine
thing else) in the preamble of the included
document; it’s up to the user to ensure that combinet.sty :
any packages needed are loaded, and any macros/latex/contrib/combine
other necessary configuration is done, in docmute.sty :
the parent document. macros/latex/contrib/docmute
109
includex.sty : Distributed in the to the FAQ team. Its output certainly looks
“unsupported” part of macros/ good.
latex/contrib/frankenstein There is also a LaTeX 2.09 package
moredefs.sty : Distributed as part
resume, which comes with little but advice
of macros/latex/contrib/ against trying to use it.
frankenstein currvita.sty :
macros/latex/contrib/currvita
newclude.sty : Distributed as part
of macros/latex/contrib/ curve.cls:
frankenstein macros/latex/contrib/curve

pdfpages.sty : europecv.cls:
macros/latex/contrib/pdfpages macros/latex/contrib/europecv

standalone.cls, standalone.sty : moderncv.cls:

macros/latex/contrib/ macros/latex/contrib/moderncv
standalone resume.sty :
subdocs.sty : Distributed as part of obsolete/macros/latex209/
macros/latex/contrib/bezos contrib/resume/resume.sty

subfiles.cls, etc.: vita.cls:

macros/latex/contrib/subfiles macros/latex/contrib/vita

199 Curriculum Vitae (Résumé) 200 Letters and the like

Andrej Brodnik’s class, vita, offers a frame- LaTeX itself provides a letter document
work for producing a curriculum vitae. class, which is widely disliked; the present
The class may be customised both for sub- author long since gave up trying with it.
ject (example class option files support If you nevertheless want to try it, but are
both computer scientists and singers), and irritated by its way of vertically-shifting a
for language (both the options provided are single-page letter, try the following hack:
available for both English and Slovene). \makeatletter
Extensions may be written by creating new \let\@texttop\relax
class option files, or by using macros de- \makeatother
fined in the class to define new entry types,
etc. in the preamble of your file.
Didier Verna’s class, curve, is based Doing-it-yourself is a common strat-
on a model in which the CV is made of a egy; Knuth (for use with Plain TeX, in
set of rubrics (each one dealing with a ma- the TeXbook), and Kopka and Daly (in
jor item that you want to discuss, such as their Guide to LaTeX) offer worked exam-
‘education’, ‘work experience’, etc). The ples. (The latest version of Knuth’s macros
class’s documentation is supported by a appear in his “local library” dump on the
couple of example files, and an emacs archive, which is updated in parallel with
mode is provided. new versions of TeX — so not very of-
Xavier Danaux offers a class moderncv ten. . . )
which supports typesetting modern curric- Nevertheless, there are contributed al-
ula vitarum, both in a classic and in a ca- ternatives — in fact there are an awfully
sual style. It is fairly customizable, allow- large number of them: the following list,
ing you to define your own style by chang- of necessity, makes but a small selection.
ing the colours, the fonts, etc. The largest, most comprehensive, class
The European Commission has recom- is newlfm; the lfm part of the name implies
mended a format for curricula vitarum that the class can create letters, faxes and
within Europe, and Nicola Vitacolonna has memoranda. The documentation is volumi-
developed a class europecv to produce it. nous, and the package seems very flexible.
While (by his own admission) the class Other classes recommended for inclu-
doesn’t solve all problems, it seems well- sion in this FAQ are akletter and isodoc.
thought out and supports all current official The dinbrief class, while recom-
EU languages (together with a few non- mended, is only documented in German.
official languages, such as Catalan, Gali- There are letter classes in each of
cian and Serbian). the excellent KOMA-script (scrlttr2: doc-
The alternative to using a separate class umentation is available in English) and
is to impose a package on one of the stan- ntgclass (brief : documentation in Dutch
dard classes. An example, Axel Reichert’s only) bundles. While these are probably
currvita package, has been recommended good (since the bundles themselves inspire
110
trust) they’ve not been specifically recom- (users should avoid becoming excited
mended by any users. about that. . . ). The package suffers from
akletter.cls: the same problem as does extsizes: the re-
macros/latex/contrib/akletter sulting font sizes are the only feature of
the document that is changed, and the ap-
brief.cls: Distributed as part of
pearance of the resulting document will
macros/latex/contrib/ntgclass
probably not be as good as if the document
dinbrief.cls: class had been designed for use at the size
macros/latex/contrib/dinbrief chosen.
isodoc.cls: Many classes, designed to produce
macros/latex/contrib/isodoc typeset results other than on “ordinary” pa-
per, will have their own font size mecha-
Knuth’s letter.tex: systems/knuth/
nisms and ranges of sizes. This is true,
local/lib/letter.tex
for example, of poster classes (such as
newlfm.cls: a0poster), and of presentation and lectur-
macros/latex/contrib/newlfm ing classes (such as beamer.
scrlttr2.cls: Distributed as part of a0poster.cls:
macros/latex/contrib/koma- macros/latex/contrib/a0poster
script
beamer.cls:
201 Other “document font” sizes? macros/latex/contrib/beamer
The LaTeX standard classes have a concept extsizes bundle:
of a (base) “document font” size; this size macros/latex/contrib/extsizes
is the basis on which other font sizes (those
from \tiny to \Huge) are determined. The KOMA script bundle:
macros/latex/contrib/koma-
classes are designed on the assumption that
script
they won’t be used with sizes other than
the set that LaTeX offers by default (10– memoir.cls:
12pt), but people regularly find they need macros/latex/contrib/memoir
other sizes. The proper response to such scrextend.sty : Distributed as part
a requirement is to produce a new design of macros/latex/contrib/koma-
for the document, but many people don’t script
fancy doing that.
A simple solution is to use the extsizes O.2 Document structure
bundle. This bundle offers “extended” ver-
sions of the article, report, book and letter 202 The style of document titles
classes, at sizes of 8, 9, 14, 17 and 20pt asThe titling package provides a number
well as the standard 10–12pt. Since little of facilities that permit manipulation of
has been done to these classes other than to the appearance of a \maketitle com-
adjust font sizes and things directly relatedmand, the \thanks commands within it,
to them, they may not be optimal — but and so on. The package also defines
they are at least practical. a titlingpage environment, that offers
More satisfactory are the KOMA-script something in between the standard classes’
classes, which are designed to work prop- titlepage option and the titlepage en-
erly with the class option files that come vironment, and is itself somewhat config-
with extsizes, and the memoir class that urable.
has its own options for document font The memoir class includes all the func-
sizes 9pt–12pt, 14pt, 17pt, 20pt, 25pt, 30pt,tionality of the titling package, while the
36pt, 48pt and 60pt. The classes also offer KOMA-script classes have their own range
size setup for any old font size, and the of different titling styles.
scrextend package can extend this facility Finally, the indefatigable Vincent
for use with any class: Zoonekynd supplies examples of how to
program alternative title styles. The web
\usepackage[fontsize=12.3]{scrextend}
page is not useful to users unless they are
will indeed set up the main document font willing to do their own LaTeX program-
to have size 12.3pt with an appropriate ming.
default baselineskip. The package “knows” KOMA script bundle:
about KOMA-script’s default sizes, and for macros/latex/contrib/koma-
eccentric sizes such as the example, it will script
produce a warning:
memoir.cls:
Using fallback calculation to setupmacros/latex/contrib/memoir
font sizes
111
titling.sty : provide programming examples, and ex-
macros/latex/contrib/titling pect users to adapt them to their own La-
TeX use.
203 The style of section headings
anonchap.sty :
Suppose that the editor of your favourite macros/latex/contrib/anonchap
journal has specified that section headings fncychap.sty :
must be centred, in small capitals, and sub- macros/latex/contrib/fncychap
section headings ragged right in italic, but
that you don’t want to get involved in the KOMA script bundle:
sort of programming described in section macros/latex/contrib/koma-
2.2 of The LaTeX Companion (see LaTeX script
books; the programming itself is discussed memoir.cls:
elsewhere in this FAQ). The following macros/latex/contrib/memoir
hack will probably satisfy your editor. De- sectsty.sty :
fine yourself new commands macros/latex/contrib/sectsty

\newcommand{\ssection}[1]{% titlesec.sty :
macros/latex/contrib/titlesec
\section[#1]{\centering\normalfont\scshape #1}}
\newcommand{\ssubsection}[1]{% tocbibind.sty : macros/latex/
\subsection[#1]{\raggedright\normalfont\itshape #1}}
contrib/tocbibind

and then use \ssection and 204 Appendixes

\ssubsection in place of \section and LaTeX provides an exceedingly simple
\subsection. This isn’t perfect: section mechanism for appendixes: the command
numbers remain in bold, and starred forms \appendix switches the document from
need a separate redefinition. generating sections (in article class) or
The titlesec package offers a structured chapters (in report or book classes) to pro-
approach to the problem, based on redefi- ducing appendixes. Section or chapter
nition of the sectioning and chapter com- numbering is restarted and the represen-
mands themselves. This approach allows tation of the counter switches to alphabetic.
it to offer radical adjustment: its options So:
provide (in effect) a toolbox for designing
\section{My inspiration}
your own sectioning commands’ output.
...
The sectsty package provides a more
simply structured set of tools; while it is
\section{Developing the inspiration}
less powerful than is titlesec, it is perhaps
...
preferable for minor adjustments, since
you can use it after having read a smaller
\appendix
proportion of the manual.
\section{How I became inspired}
The fncychap package provides a nice
...
collection of customised chapter heading
designs. The anonchap package provides a would be typeset (in an article document)
simple means of typesetting chapter head- something like:
ings “like section headings” (i.e., without
the “Chapter” part of the heading); the 1 My inspiration
tocbibind package provides the same com- ...
mands, in pursuit of another end.
2 Developing the inspiration
The memoir class includes facilities
that match sectsty and titlesec, as well as ...
a bundle of chapter heading styles (includ- A How I became inspired
ing an anonchap-equivalent). The KOMA- ...
script classes also have sets of tools that
provide equivalent functionality, notably which is quite enough for many ordinary
formatting specifications \partformat, purposes. Note that, once you’ve switched
\chapterformat, \sectionformat, . . . , to typesetting appendixes, LaTeX provides
as well as several useful overall formatting you with no way back — once you’ve had
specifications defined in class options. an appendix, you can no longer have an
Finally, the indefatigable Vincent “ordinary” \section or \chapter.
Zoonekynd supplies examples of how to The appendix provides several ways of
program alternative chapter heading styles elaborating on this simple setup. Straight-
and section heading styles. The web pages forward use of the package allows you to
112
have a separate heading, both in the body There are many other merry things one
of the document and the table of contents; may do with the package; the user is re-
this would be achieved by ferred to the package documentation for
further details.
\usepackage{appendix} The memoir class includes the facili-
... ties of the appendix package. The KOMA-
\appendix script classes offer a \appendixprefix
\appendixpage command for manipulating the appearance
\addappheadtotoc of appendixes.
The \appendixpage command adds a sep- appendix.sty :
arate title “Appendices” above the first ap- macros/latex/contrib/appendix
pendix, and \addappheadtotoc adds a KOMA script bundle:
similar title to the table of contents. These macros/latex/contrib/koma-
simple modifications cover many people’s script
needs about appendixes.
The package also provides an memoir.cls:
appendices environment, which provides macros/latex/contrib/memoir
for fancier use. The environment is best
205 Indent after section headings
controlled by package options; the above
example would be achieved by LaTeX implements a style that doesn’t in-
dent the first paragraph after a section head-
\usepackage[toc,page]{appendix} ing. There are coherent reasons for this,
... but not everyone likes it. The indentfirst
\begin{appendices} package suppresses the mechanism, so that
... the first paragraph is indented.
\end{appendices}
indentfirst.sty : Distributed as part
The great thing that the appendices envi- of macros/latex/required/tools
ronment gives you, is that once the environ- 206 How to create a
ment ends, you can carry on with sections \subsubsubsection
or chapters as before — numbering isn’t
affected by the intervening appendixes. LaTeX’s set of “sections” stops at the level
The package provides another alter- of \subsubsection. This reflects a de-
native way of setting appendixes, as in- sign decision by Lamport — for, after all,
ferior divisions in the document. The who can reasonably want a section with
subappendices environment allows you such huge strings of numbers in front of
to put separate appendixes for a particu- it?
lar section, coded as \subsections, or for In fact, LaTeX standard classes do
a particular chapter, coded as \sections. define “sectioning” levels lower than
So one might write: \subsubsection, but they don’t format
them like sections (they’re not numbered,
\usepackage{appendix} and the text is run-in after the heading).
... These deeply inferior section commands
\section{My inspiration} are \paragraph and \subparagraph;
... you can (if you must) arrange that these
\begin{subappendices} two commands produce numbered head-
\subsection{How I became inspired} ings, so that you can use them as
... \subsubsubsections and lower.
\end{subappendices} The titlesec package provides a sen-
sible set of macros for you to adjust the
\section{Developing the inspiration} definitions of the sectioning macros, and it
... may be used to transform a \paragraph’s
typesetting so that it looks like that of a
Which will produce output something like: \section.

1 My inspiration If you want to program the change

yourself, you’ll find that the com-
... mands (\section all the way down to
1.A How I became inspired \subparagraph) are defined in terms of
... the internal \@startsection command,
which takes 6 arguments. Before attempt-
2 Developing the inspiration ing this sort of work, you are well ad-
... vised to read the LaTeX sources (ltsect.
113
dtx in the LaTeX distribution) and the tex, which is created when you unpack
source of the standard packages (classes. caption.dtx
dtx), or to make use of the LaTeX Note that the previously-recommended
Companion, which discusses the use of package caption2 has now been overtaken
\@startsection for this sort of thing. again by caption; however, caption2 re-
You will note that Lamport didn’t go mains available for use in older documents.
on adding “sub” to the names of sec- caption.sty :
tioning commands, when creating com- macros/latex/contrib/caption
mands for the lowest levels of a doc-
ument. This would seem sensible to capt-of.sty :
any but the most rigorous stickler for macros/latex/contrib/capt-of
symmetry — it would surely challenge ccaption.sty :
pretty much anyone’s reading of the source macros/latex/contrib/ccaption
of a document, if there was a need
to distinguish \subsubsubsection and float.sty :
macros/latex/contrib/float
\subsubsubsubsection
LaTeX source: macros/latex/base KOMA script bundle:
macros/latex/contrib/koma-
titlesec.sty : script
macros/latex/contrib/titlesec
memoir.cls:
207 The style of captions macros/latex/contrib/memoir
Changes to the style of captions may be
made by redefining the commands that 208 Alternative head- and footlines in
produce the caption. So, for example, LaTeX
\fnum@figure (which produces the float The standard LaTeX document classes de-
number for figure floats) may be redefined, fine a small set of ‘page styles’ which
in a package of your own, or between specify head- and footlines for your doc-
\makeatletter–\makeatother: ument (though they can be used for other
purposes, too). The standard set is very
\renewcommand{\fnum@figure}{\textbf{Fig.~\thefigure}}
limited, but LaTeX is capable of much
which will cause the number to be more. The internal LaTeX coding needed
typeset in bold face. (Note that the to change page styles is not particularly
original definition used \figurename — challenging, but there’s no need — there
\figurename.) More elaborate changes are packages that provide useful abstrac-
can be made by patching the \caption tions that match the way we typically think
command, but since there are packages to about these things.
do the job, such changes (which can get The fancyhdr package provides simple
rather tricky) aren’t recommended for or- mechanisms for defining pretty much every
dinary users. head- or footline variation you could want;
The float package provides some con- the directory also contains some documen-
trol of the appearance of captions, though tation and one or two smaller packages.
it’s principally designed for the creation Fancyhdr also deals with the tedious be-
of non-standard floats. The caption and haviour of the standard styles with initial
ccaption (note the double “c”) packages pages, by enabling you to define different
provide a range of different formatting op- page styles for initial and for body pages.
tions. While fancyhdr will work with KOMA-
ccaption also provides ‘continuation’ script classes, an alternative package,
captions and captions that can be placed scrpage2, eases integration with the
outside of float environments. The (very classes. Scrpage2 may also be used as
simple) capt-of package also allows cap- a fancyhdr replacement, providing similar
tions outside a float environment. Note facilities. The KOMA-script classes them-
that care is needed when doing things that selves permit some modest redefinition of
assume the sequence of floats (as in con- head- and footlines, without the use of the
tinuation captions), or potentially mix non- extra package.
floating captions with floating ones. Memoir also contains the functional-
The memoir class includes the facili- ity of fancyhdr, and has several predefined
ties of the ccaption package; the KOMA- styles.
script classes also provide a wide range of Documentation of fancyhdr is dis-
caption-formatting commands. tributed with the package, in a separate
The documentation of caption is file; documentation of scrpage2 is inte-
available by processing a file manual. grated with the scrgui* documentation
114
files that are distributed with the KOMA- \title{Demonstration}
script classes. \author{Me, You\thanks{}}
fancyhdr.sty : \twocolumn[
macros/latex/contrib/fancyhdr ... as above ...
]
KOMA script bundle: {
macros/latex/contrib/koma- \renewcommand{\thefootnote}%
script {\fnsymbol{footnote}}
memoir.cls: \footnotetext[1]{Thanks for nothing}
macros/latex/contrib/memoir }

209 Wide figures in two-column and so on.

documents As an alternative, among other
Floating figures and tables ordinarily come facilities the abstract package pro-
out the same width as the page, but in two- vides a \saythanks command and a
onecolabstract environment which re-
column documents they’re restricted to the
width of the column. This is sometimes move the need to fiddle with the \thanks
not good enough; so there are alternative and footnoting. They can be used like this:
versions of the float environments — in \twocolumn[
two-column documents, figure* provides \maketitle % full width title
a floating page-wide figure (and table* a \begin{onecolabstract} % ditto abstract
page-wide table) which will do the neces- ... text
sary. \end{onecolabstract}
The “*”ed float environments can only ]
appear at the top of a page, or on a whole \saythanks % typeset any \thanks
page — h or b float placement directives
are simply ignored. The memoir class offers all the facilities of
Unfortunately, page-wide equations abstract.
can only be accommodated inside float en- abstract.sty :
vironments. You should include them in macros/latex/contrib/abstract
figure environments, or use the float or
ccaptionpackage to define a new float type. memoir.cls:
macros/latex/contrib/memoir
ccaption.sty :
macros/latex/contrib/ccaption 211 Really blank pages between
float.sty : chapters
macros/latex/contrib/float If you’re using the standard classes, you
need to take special action; the memoir
210 1-column abstract in 2-column class and the Koma-Script classes provide
document their own support for this — see below.
One often requires that the abstract of a Book (by default) and report (with
paper should appear across the entire page, openright class option) ensure that each
even in a two-column paper. The required chapter starts on a right-hand (recto)
trick is: page; they do this by inserting a
\cleardoublepage command between
\documentclass[twocolumn]{article} chapters (rather than a mere \clearpage).
... The empty page thus created gets to have a
\begin{document} normal running header, which some people
... % \author, etc don’t like.
\twocolumn[ The (excellent) fancyhdr man-
\begin{@twocolumnfalse} ual covers this issue, basically ad-
\maketitle vising the creation of a command
\begin{abstract} \clearemptydoublepage:
...
\end{abstract} \let\origdoublepage\cleardoublepage
\end{@twocolumnfalse} \newcommand{\clearemptydoublepage}{%
] \clearpage
{\pagestyle{empty}\origdoublepage}%
Unfortunately, with the above \thanks }
won’t work in the \author list. If you
need such specially-numbered footnotes, The “obvious” thing is then to use this
you can make them like this: command to replace \cleardoublepage
115
in a patched version of the \chapter com- last page of the document typically ends
mand. (Make a package of your own up with columns of different lengths —
containing a copy of the command out such columns are said to be “unbalanced”.
of the class.) This isn’t particularly dif- Many (most?) people don’t like unbal-
ficult, but you can instead simply sub- anced columns.
vert \cleardoublepage (which isn’t of- The simplest solution to the problem
ten used elsewhere): is to use the multicol package in place of
the twocolumn option, as multicol balances
\let\cleardoublepage\clearemptydoublepage
the columns on the final page by default.
Note: this command works because However, the use of multicol does come
\clearemptydoublepage uses a copy at a cost: its special output routine disal-
of \cleardoublepage: instructions on lows the use of in-column floats, though it
macro programming patching techniques does still permit full-width (e.g., figure*
explain the problem and why this is a solu- environment) floats.
tion. As a result, there is a constant push for
The emptypage package does this sort a means of balancing columns at the end
of thing for you; all you need do is load of a twocolumn document. Of course, the
the package, and it does the rest. job can be done manually: \pagebreak
The KOMA-Script replace- inserted at the appropriate place on the last
ments for the book and report page can often produce the right effect, but
classes (scrbook and scrreprt of- this seldom appeals, and if the last page is
fers class options cleardoubleempty, made up of automatically-generated text
cleardoubleplain and cleardoublestandard (for example, bibliography or index) insert-
(using the running page style, as normal) ing the command will be difficult.
that control the appearance of these empty The flushend package offers a solution
pages. The classes also offer do-it-yourself to this problem. It’s a somewhat dangerous
commands \cleardoubleempty (etc.). piece of macro code, which patches one
The memoir class (and the of the most intricate parts of the LaTeX
nextpage package) provide com- kernel without deploying any of the safe-
mands \cleartooddpage and guards discussed in patching commands.
\cleartoevenpage, which both take The package only changes the behaviour at
an optional argument (the first, with end document (its \flushend command
no argument, being an equivalent is enabled by default), and one other com-
of \cleardoublepage). One can mand permits adjustment of the final bal-
achieve ‘special’ effects by putting ance; other packages in the bundle provide
commands in the optional argu- means for insertion of full width material
ment: the \clearemptydoublepage in two-column documents.
we’re after would be achieved by The balance package also patches the
\cleartooddpage[\thispagestyle output routine (somewhat more carefully
{empty}]. The commands will also serve than flushend).
if you want the surreal effect of “This page The user should be aware that any of
intentionally left blank” in the centre of an these packages are liable to become con-
otherwise empty page. fused in the presence of floats: if problems
emptypage.sty : macros/latex/ arise, manual adjustment of the floats in
contrib/emptypage the document is likely to be necessary. It
is this difficulty (what’s required in any in-
fancyhdr.sty :
stance can’t really be expressed in current
macros/latex/contrib/fancyhdr
LaTeX) that led the author of multicol to
memoir.cls: suppress single-column-wide floats.
macros/latex/contrib/memoir
balance.sty : Distributed as part of
nextpage.sty : macros/latex/ macros/latex/contrib/preprint
contrib/misc/nextpage.sty
flushend.sty : Distributed as part of
scrbook.cls, scrrept.cls: Part of macros/latex/contrib/sttools
macros/latex/contrib/koma-
multicol.sty : Distributed as part of
script
macros/latex/required/tools
212 Balancing columns at the end of
a document 213 My section title is too wide for
The twocolumn option of the standard the page header
classes causes LaTeX to set the text of a By default, LaTeX sectioning commands
document in two columns. However, the make the chapter or section title available
116
for use by page headers and the like. Page the optional argument to \section, even
headers operate in a rather constrained if “middling version” is in fact the same
area, and it’s common for titles too be too text as “long version”.)
big to fit: the LaTeX sectioning commands A similar arrangement is necessary
therefore take an optional argument: even for chapters if the class you’re using
is odd enough that it puts a page header on
\section[short title]{full title}
a chapter’s opening page.
If the hshort titlei is present, it is used both Note that the titlesec package manages
for the table of contents and for the page the running heads in a completely different
heading. The usual answer to people who fashion; for example, you can use the op-
complain that their title is too big for the tional argument of sectioning commands
running head is to suggest that they the for page headers, only, by loading the pack-
optional argument. age as:
However, using the same text for the
table of contents as for the running head \usepackage[toctitles]{titlesec}
may also be unsatisfactory: if your chapter
titles are seriously long (like those of a Vic- The package documentation offers other
torian novel), a valid and rational scheme useful techniques in this area.
is to have a shortened table of contents en- The memoir class avoids all the silli-
try, and a really terse entry in the running ness by providing an extra optional argu-
head. ment for chapter and sectioning commands,
One of the problems is the tendency of for example:
page headings to be set in capitals (which
take up more space); so why not set head- \section[middling version][terse version]{verbose versi
ings as written for “ordinary” reading? It’s
not possible to do so with unmodified La- As a result, it is always possible for users
TeX, but the fancyhdr package provides of memoir to tailor the header text to fit,
a command \nouppercase for use in its with very little trouble.
header (and footer) lines to suppress La- fancyhdr.sty :
TeX’s uppercasing tendencies. Classes in macros/latex/contrib/fancyhdr
the KOMA-script bundle don’t uppercase
KOMA script bundle:
in the first place.
macros/latex/contrib/koma-
In fact, the sectioning commands
script
use ‘mark’ commands to pass informa-
tion to the page headers. For example, memoir.cls:
\chapter uses \chaptermark, \section macros/latex/contrib/memoir
uses \sectionmark, and so on. With this
titlesec.sty :
knowledge, one can achieve a three-layer
macros/latex/contrib/titlesec
structure for chapters:
Page numbering “hni of hmi”
214 version}
\chapter[middling version]{verbose
\chaptermark{terse version} Finding the page number of the last page
which should supply the needs of every of a document, from within the document,
taste. is somewhat tricky. The lastpage and zref-
Chapters, however, have it easy: hardly lastpage packages define a label LastPage
any book design puts a page header on a whose number is right (after sufficiently
chapter start page. In the case of sections, many passes through LaTeX, of course).
one has typically to take account of the na- The memoir class also defines a “last page”
ture of the \*mark commands: the thing label.
that goes in the heading is the first mark The documentation of the fancyhdr
on the page (or, failing any mark, the last package spells out exactly how one might
mark on any previous page). As a result actually use this information to produce
the recipe for sections is more tiresome: page numbering as suggested in the ques-
tion.
\section[middling version]{verbose version%
fancyhdr documentation:
\sectionmark{terse version}}
macros/latex/contrib/fancyhdr
\sectionmark{terse version}
lastpage.sty :
(the first \sectionmark deals with the macros/latex/contrib/lastpage
header of the page the \section com-
mand falls on, and the second deal with zref-lastpage: Distributed as part of
subsequent pages; note that here, you need macros/latex/contrib/oberdiek
117
215 Page numbering by chapter An alternative approach is to use the
When I was a young man, a common ar- (excellent) testflow suite, that provides a
rangement for loose bound technical man- detailed outline of the potential problems
uals is to number pages by chapter. (It’s together with a sample document and pro-
quite a good scheme, in those situations: totype outputs.
even if your corrections add a whole page testflow bundle: macros/latex/
to the chapter, the most you have to redis- contrib/IEEEtran/testflow
tribute is that chapter.)
217 Adobe Reader messing with print
The problem, at first sight, seems pretty size
much the same as that in another answer
on running numbers within a chapter, and Printing from Adobe Reader shrinks the
the basic technique is indeed pretty similar. page “to fit” (by default). Unfortunately,
However, tidying-up loose ends, mak- its calculation doesn’t consider the existing
ing sure the page number gets reset to the margins of the document, so that it shrinks
correct value at the start of each chapter, what it believes is your whole page onto
and so on, is slightly more challenging. what it believes is its output page. The ef-
This is why the chappg package was writ- fect typically looks as if your margins have
ten: it does the obvious things, and more. expanded.
Solve this problem by adjusting the
Users have been known to ask for run-
Reader’s default in the print dialogue; un-
ning page numbers within a section, but
fortunately, this dialogue varies from one
this really doesn’t make sense: you need to
version to the next:
run page numbers within document objects
that always start on a fresh page. • Reader version 7:
chappg.sty : Page Scaling (default: “Fit to printer
macros/latex/contrib/chappg margins”) — change to “None”, and
Scale (default 95% of Normal size) —
O.3 Page layout change to “100%”.
• Adobe Reader 6:
216 The size of printed output in the print dialogue, on the “copies
The final product of a (La)TeX run is some- & pages” pane, you’ll find a popup
thing for a person to read. Often, nowa- menu/drop-down list titled “Page Scal-
days, that product will be read “on-screen”, ing” — change to “None”.
but the printed page remains a principal • Windows, Linux Acrobat (Reader)
output form. 5.0:
When we come to print our output, it In the print dialog, make sure the
is important that the output fits on the pa- “Shrink oversized pages to fit” check-
per; in some cases, for the output to “fit” box is unchecked. It may also be
is good enough. However, there are cir- useful to uncheck the “Expand small
cumstances where the actual size of the pages to fit paper size” checkbox as
printed output, on the page, is crucial to well.
the acceptance of the output. (This might
happen when the output is a book to be 218 Getting the right paper geometry
published, or when it’s a dissertation which from (La)TeX
must match the fancies of some bureaucrat If your output is the wrong size, and you’ve
even to be considered.) checked that it’s not due to the ministra-
Sadly, we often find that the printed tions of Adobe Reader, the problem is
output doesn’t conform to our expecta- probably that your (La)TeX system is pro-
tions. . . ducing output that specifies the wrong pa-
The check-list for such problems has per size. Paper sizes can be a pain: they’re
two entries: a forgotten backwater — Knuth seems not
to have considered paper size as something
• Your output is generated via the TeX engine needs to know about. As a
Adobe Reader (or possibly result, there is no DVI command to specify
“Acrobat Reader” — older versions of the paper on which the document should be
the program had the qualified name). printed, which has led a dichotomy where
In this case, it may be that Reader macros shape the text according to the
is willfully changing the size of your needs of the author’s chosen paper size,
output: read Reader antics. and device drivers’ choice happens inde-
• Something in your TeX system is pro- pendently of the macros’ ideas.
ducing the wrong size (or shape) of In practice, one usually finds that
output: read paper geometry. macro packages (such as Plain TeX and
118
LaTeX) assume American “letter” paper for the extension dvipdfmx and xdvipdfmx).
size, by default; and since most distribu- If you’re using PDFLaTeX or XeTeX,
tions nowadays originate in Europe, the load with
drivers usually default to ISO “A4” paper
\usepackage[program-option,...]{geometry}
size.
This is (of course) pretty unsatisfactory. where program-option is pdftex,
Users may select a different paper size for xetex.
their document (current LaTeX offers a The alternative, zwpagelayout requires
range of sizes as options in the standard a driver option:
classes), pretty easily. Nevertheless, the \usepackage[driver=value,...]{zwpagelayout}
user also has to be sure that each time xdvi,
dvips (or whatever) runs, it uses the paper (permissible hvaluesi are pdftex, xetex
size the document was designed for. and dvips; the default value is unknown).
The default paper size for DVI drivers Needless to say, both the “big” classes
may be changed by a distribution manage- (koma-script and memoir) provide their
ment command (texconfig for TeX Live, own ways to get the paper size “right”.
the Options application for MiKTeX), but The typearea package is the Koma-
this still doesn’t provide for people using script distribution’s way of providing page
the “wrong” sort of paper for some reason. layout functionality. Load it with the
A different issue arises for users of pagesize option and it will ensure the cor-
PDFTeX — the PDF format does have the rect paper is selected, for PDF output from
means of expressing paper size and PDF- PDFLaTeX, and for PostScript output from
TeX has system variables \pdfpagewidth LaTeX via dvips.
and \pdfpageheight, that are written into Memoir has the standard classes’
the output PDF file. Unfortunately, most paper-size selections (a4paper,
of the core software predates PDFTeX, so letterpaper and so on), but also per-
not even PDFLaTeX sets the correct values mits the user to choose an arbitrary pa-
into those variables, to match the paper size per size, by setting the length registers
specified in a \documentclass option. \stockheight and \stockwidth. The
The DVI drivers dvips, dvipdfm and commands \fixdvipslayout (for La-
its extensions (dvipdfmx and xdvipdfmx) TeX processing), and \fixpdflayout (for
define \special commands for the doc- PDFLaTeX processing) then instruct the
ument to specify its own paper size; so processor to produce output that specifies
in those cases, as when PDFTeX is being the necessary paper size.
used, the paper size can be programmed by geometry.sty :
the document. Users who wish to, may of macros/latex/contrib/geometry
course consult the manuals of the various memoir.cls:
programs to write the necessary code. macros/latex/contrib/memoir
The geometry and zwpagelayout pack-
typearea.sty : Distributed as part of
ages (whose main business includes defin-
macros/latex/contrib/koma-
ing typeset page areas), also takes notice
script
the size of the paper that the document is
going to be printed on, and can issue the zwpagelayout.sty : macros/latex/
commands necessary to ensure the correct contrib/zwpagelayout
size of paper is used. If geometry is used 219 Changing the margins in LaTeX
when a document is being processed by
Changing the layout of a document’s text
PDFLaTeX, it can set the necessary dimen-
on the page involves several subtleties not
sions “in the output”. If the document is
often realised by the beginner. There are
being processed by LaTeX on a TeX or
interactions between fundamental TeX con-
e-TeX engine, there are package options
straints, constraints related to the design of
which instruct geometry which \special
LaTeX, and good typesetting and design
commands to use. (Note that the options
practice, that mean that any change must
are ignored if you are using PDFLaTeX.)
be very carefully considered, both to en-
So, one resolution of the problem,
sure that it “works” and to ensure that the
when you are using LaTeX, is to add
result is pleasing to the eye.
LaTeX’s defaults sometimes seem ex-
\usepackage[processor-option,...]{geometry}
cessively conservative, but there are sound
Where processor-option tells the pack- reasons behind how Lamport designed the
age what will produce your (PostScript layouts themselves, whatever one may feel
or PDF output — geometry knows about about his overall design. For example, the
dvips and dvipdfm (dvipdfm also serves common request for “one-inch margins all
119
round on A4 paper” is fine for 10- or 12- KOMA script bundle:
pitch typewriters, but not for 10pt (or even macros/latex/contrib/koma-
11pt or 12pt) type because readers find script
such wide, dense, lines difficult to read.
layout.sty : Distributed as part of
There should ideally be no more than 75
macros/latex/required/tools
characters per line (though the constraints
change for two-column text). memoir.cls:
So Lamport’s warning to beginners in macros/latex/contrib/memoir
his section on ‘Customizing the Style’ — typearea.sty : Distributed as part of
“don’t do it” — should not lightly be ig- macros/latex/contrib/koma-
nored. script
This set of FAQs recommends that you
vmargin.sty :
use a package to establish consistent set-
macros/latex/contrib/vmargin
tings of the parameters: the interrelation-
ships are taken care of in the established zwpagelayout.sty : macros/latex/
packages, without you needing to think contrib/zwpagelayout
about them, but remember — the packages
only provide consistent, working, mecha- 221 How to set up page layout “by
nisms: they don’t analyse the quality of hand”
what you propose to do. So you’re eager to do it yourself, notwith-
The following answers deal with the standing the cautions outlined in “changing
ways one may choose to proceed: margins”.
It’s important that you first start by fa-
• Choose which package to use. miliarising yourself with LaTeX’s page lay-
• Find advice on setting up page layout out parameters. For example, see section
by hand. C.5.3 of the LaTeX manual (pp. 181-182),
or corresponding sections in many of the
There is a related question — how to
other good LaTeX manuals (see LaTeX
change the layout temporarily — and
books).
there’s an answer that covers that, too:
LaTeX controls the page layout with
• Change the margins on the fly. a number of parameters, which allow you
to change the distance from the edges of
220 Packages to set up page designs a page to the left and top edges of your
typeset text, the width and height of the
There are two trustworthy tools for ad- text, and the placement of other text on
justing the dimensions and position of the the page. However, they are somewhat
printed material on the page are geometry complex, and it is easy to get their inter-
and the zwpagelayout packages; a very relationships wrong when redefining the
wide range of adjustments of the layout page layout. The layout package defines a
may be relatively straightforwardly pro- \layout command which draws a diagram
grammed with either, and package docu- of your existing page layout, with the di-
mentation is good and comprehensive. mensions (but not their interrelationships)
As is usual, users of the memoir class shown.
have built-in facilities for this task, and Even changing the text height and
users of the KOMA-script classes are rec- width, \textheight and \textwidth, re-
ommended to use an alternative package, quires more care than you might expect:
typearea. In either case it is difficult to the height should be set to fit a whole num-
argue that users should go for geometry: ber of text lines (in terms of multiples of
both alternatives are good. \baselinskip), and the width should be
The documentation both of geometry constrained by the number of characters
and of zwpagelayout is rather overwhelm- per line, as mentioned in “changing mar-
ing, and learning all of of either package’s gins”.
capabilities is likely to be more than you Margins are controlled by two
ever need. The vmargin package is some- parameters: \oddsidemargin and
what simpler to use: it has a canned set \evensidemargin, whose names come
of paper sizes (a superset of that provided from the convention that odd-numbered
in LaTeX2e), provision for custom paper, pages appear on the right-hand side
margin adjustments and provision for two- (‘recto’) of a two-page spread and even-
sided printing. numbered pages on the left-hand side
geometry.sty : (‘verso’). Both parameters actually refer
macros/latex/contrib/geometry to the left-hand margin of the relevant
120
pages; in each case the right-hand mar- The changepage package provides
gin is specified by implication, from the ready-built commands to do the above;
value of \textwidth and the width of the it includes provision for changing the
paper. (In a one-sided document, which shifts applied to your text according to
is the default in many classes, including whether you’re on an odd (recto) or an
the standard article and report classes, even (verso) page of a two-sided document.
\oddsidemargin stands for both.) Changepage’s structure matches that of the
The “origin” (the zero position) memoir class.
on the page is one inch from the top The (earlier) package chngpage pro-
of the paper and one inch from the vides the same facilities, but it uses rather
left side; positive horizontal measure- different syntax. Changepage’s structure
ments extend right across the page, and matches that of the memoir class, and it
positive vertical measurements extend should be used for any new work.
down the page. Thus, the parameters Changing the vertical dimensions of
\evensidemargin, \oddsidemargin a page is more clumsy still: the LaTeX
and \topmargin, should be set to be command \enlargethispage adjusts the
1 inch less than the true margin; for mar- size of the current page by the size of its
gins closer to the left and top edges of the argument. Common uses are
page than 1 inch, the margin parameters
must be set to negative values. \enlargethispage{\baselineskip}

222 Changing margins “on the fly” to make the page one line longer, or
One of the surprises characteristic of TeX \enlargethispage{-\baselineskip}
use is that you cannot change the width
or height of the text within the document, to make the page one line shorter. The
simply by modifying the text size param- process is (to an extent) simplified by the
eters; TeX can’t change the text width on addlines package: its \addlines com-
the fly, and LaTeX only ever looks at text mand takes as argument the number of
height when starting a new page. lines to add to the page (rather than a
So the simple rule is that the pa- length): the package documentation also
rameters should only be changed in the provides a useful analysis of when the com-
preamble of the document, i.e., before the mand may (or may not) be expected to
\begin{document} statement (so before work.
any typesetting has happened. addlines.sty :
To adjust text width within a document macros/latex/contrib/addlines
we define an environment:
changepage.sty : macros/latex/
\newenvironment{changemargin}[2]{% contrib/changepage
\begin{list}{}{%
223 How to get rid of page numbers
\setlength{\topsep}{0pt}%
\setlength{\leftmargin}{#1}%Very occasionally, one wants a document
with no page numbers. For such occa-
\setlength{\rightmargin}{#2}%
sions, the package nopageno will make
\setlength{\listparindent}{\parindent}%
\pagestyle{plain}
\setlength{\itemindent}{\parindent}% have the same effect
as
\setlength{\parsep}{\parskip}% \pagestyle{empty} ; in simple doc-
}% uments, this will suppress all page num-
\item[]}{\end{list}} bering (it will not work, of course, if the
document uses some other pagestyle than
The environment takes two arguments, and plain).
will indent the left and right margins, re- To suppress page numbers from
spectively, by the parameters’ values. Neg- a sequence of pages, you may use
ative values will cause the margins to \pagestyle{empty} at the start of the
be narrowed, so \begin{changemargin} sequence, and restore the original page
{-1cm}{-1cm} narrows the left and right style at the end. Unfortunately, you still
margins by 1 centimetre. have to deal with the page numbers on
Given that TeX can’t do this, how does pages containing a \maketitle, \part
it work? — well, the environment (which or \chapter command, since the standard
is a close relation of the LaTeX quote envi- classes; deal with those separately, as de-
ronment) doesn’t change the text width as scribed below.
far as TeX is concerned: it merely moves To suppress page numbers on a
text around inside the width that TeX be- single page, use \thispagestyle
lieves in. {empty} somewhere within the text of
121
the page. Note that, in the standard KOMA script bundle:
classes, \maketitle and \chapter use macros/latex/contrib/koma-
\thispagestyle internally, so your call script
must be after those commands. memoir.cls:
Unfortunately, \thispagestyle macros/latex/contrib/memoir
doesn’t work for book or report \part
nonumonpart.sty : macros/latex/
commands: they set the page style (as
contrib/nonumonpart
do \chapter commands), but then they
advance to the next page so that you have nopageno.sty :
no opportunity to change the style using macros/latex/contrib/nopageno
\thispagestyle. The present author scrpage2.sty : Distributed as part of
has proposed solving the problem with macros/latex/contrib/koma-
the following “grubby little patch”, on script
comp.text.tex:
224 How to create crop marks
\makeatletter If you’re printing something that’s eventu-
\let\sv@endpart\@endpart ally to be reproduced in significant quanti-
\def\@endpart{\thispagestyle{empty}\sv@endpart}
ties, and bound, it’s conventional to print
\makeatother on paper larger than your target product,
and to place “crop marks” outside the
Fortunately, that patch has now been incor-
printed area. These crop marks are avail-
porated in a small package nonumonpart
able to the production house, for lining up
(a difficult name. . . )
reproduction and trimming machines.
Both the KOMA-script classes and
You can save yourself the (consider-
memoir have separate page styles for the
able) trouble of programming these marks
styles of various “special” pages, so, in a
for yourself by using the package crop,
KOMA class document one might say:
which has facilities to satisfy any con-
ceivable production house. Users of the
\renewcommand*{\titlepagestyle}{empty}
memoir class don’t need the package, since
while memoir will do the job with memoir has its own facilities for program-
ming crop marks.
\aliaspagestyle{title}
crop.sty :
{empty}
macros/latex/contrib/crop
An alternative (in all classes) is to memoir.cls:
use the rather delightful \pagenumbering macros/latex/contrib/memoir
{gobble}; this has the simple effect
that any attempt to print a page num- 225 ‘Watermarks’ on every page
ber produces nothing, so there’s no is- It’s often useful to place some text (such
sue about preventing any part of LaTeX as ‘DRAFT’) in the background of every
from printing the number. However, the page of a document. For LaTeX users, the
\pagenumbering command does have the simplest way to do this uses the draftcopy
side effect that it resets the page number package. This can deal with many types of
(to 1), so it is unlikely to be helpful other DVI processors (in the same way that the
than at the beginning of a document. graphics package does) and knows trans-
The scrpage2 package separates out lations for the word ‘DRAFT’ into a wide
the representation of the page number (it range of languages (though you can choose
typesets the number using the \pagemark your own word, too). Unfortunately, how-
command) from the construction of the ever, the package relies on PostScript spe-
page header and footer; so one can say cials, and will therefore fail if you are view-
ing your document with xdvi, and won’t
\renewcommand*{\pagemark}{} even compile if you’re using PDFLaTeX.
(PDFLaTeX users need one of the other
which will also suppress the printing of the solutions below.)
page number. The wallpaper package builds on eso-
Neither of these “suppress the page pic (see below). Apart from the single-
number” techniques touches the page image backdrops described above (“wall-
style in use; in practice this means they papers”, of course, to this package), the
don’t make sense unless you are using package provides facilities for tiling im-
\pagestyle{plain} ages. All its commands come in pairs: one
fancyhdr.sty : for “general” use, and one applying to the
macros/latex/contrib/fancyhdr current page only.
122
 The draftwatermark package uses the wallpaper.sty : macros/latex/
same author’s everypage package to pro- contrib/wallpaper
vide a simple interface for adding textual
(‘DRAFT’-like) watermarks. 226 Typesetting things in landscape
The xwatermark package provides very orientation
flexible watermarking, with a “modern” It’s often necessary to typeset part of a doc-
(key-value) interface. ument in landscape orientation; to achieve
More elaborate watermarks may be this, one needs not only to change the page
achieved using the eso-pic package, or by dimensions, but also to instruct the output
using everypage (see below). Eso-pic at- device to print the strange page differently.
taches a picture environment to every There are two “ordinary” mechanisms
page as it is shipped out; the user can put for doing two slight variations of landscape
things into that environment: the package typesetting:
provides commands for placing things at
certain useful points (like “text upper left” • If you have a single floating object
or “text centre”) in the picture, but the user that is wider than it is deep, and will
is at liberty to do what he or she likes. only fit on the page in landscape ori-
Eso-pic is, in turn, built upon the pack- entation, use the rotating package;
age atbegshi. That package has the capa- this defines sidewaysfigure and
bility to produce watermarks on top of the sidewaystable environments which
other material on the page; this doesn’t create floats that occupy a whole page.
sound very “watermark-like”, but can Note that rotating has problems in
be useful on pages where the watermark a document that also loads the float
would otherwise be hidden by graphics or package, which recommended in other
the like. The atbegshi command that eso- answers in these FAQs, for example
pic uses is \AtBeginShipoutUpperLeft; that on float placement. The rotfloat
\AtBeginShipoutUpperLeftForeground package loads rotating for you, and
is what’s needed instead to place the mate- smooths the interaction with float.
rial on top of the rest of the content of the • If you have a long sequence of
page. things that need to be typeset in
Everypage allows you to add “some- landscape (perhaps a code listing,
thing” to every page, or to a particular a wide tabbing environment, or a
page; you therefore need to construct your huge table typeset using longtable or
own apparatus for anything complicated. supertabular), use the lscape package
Finally, one can use the pdftk untility; (or pdflscape if you’re generating PDF
with it, the command: output, whether using PDFLaTeX or
dvips and generating PDF from that).
pdftk a.pdf background b.pdf outputBoth c.pdf
packages define an environment
will recreate a.pdf as c.pdf, having used landscape, which clears the current
the first page of b.pdf as background on page and restarts typesetting in land-
every page. If you have a standard back- scape orientation (and clears the page
ground (“DRAFT” or “SECRET”, or what- at the end of the environment before
ever) used in several files, pdftk might well returning to portrait orientation).
be attractive.
Pdftk is available as a command line No currently available package makes di-
tool; it is available in most linux distrit- rect provision for typesetting in both por-
butions, but may be downloaded from its trait and landscape orientation on the same
home site page (it’s not the sort of thing that TeX
is well set-up to do). If such behaviour
atbegshi.sty : Distributed as part of was an absolute necessity, one might use
macros/latex/contrib/oberdiek the techniques described in "flowing text
draftcopy.sty : macros/latex/ around figures", and would rotate the land-
contrib/draftcopy scape portion using the rotation facilities
draftwatermark.sty : macros/latex/ of the graphics package. (Returning from
contrib/draftwatermark landscape to portrait orientation would be
somewhat easier: the portrait part of the
eso-pic.sty :
page would be a bottom float at the end
macros/latex/contrib/eso-pic
of the landscape section, with its content
everypage.sty : macros/latex/ rotated.)
contrib/everypage To set an entire document in landscape
everyshi.sty : Distributed as part of orientation, one might use lscape around
macros/latex/contrib/ms the whole document. A better option is the
123
landscape option of the geometry pack- commands of picture-mode. (Eso-pic re-
age; if you also give it dvips or pdftex quires the services of everyshi, which must
option, geometry also emits the rotation therefore also be available.)
instructions to cause the output to be prop- eso-pic.sty :
erly oriented. The memoir class has the macros/latex/contrib/eso-pic
same facilities, in this respect, as does
geometry. everyshi.sty : Distributed as part of
A word of warning: most current TeX macros/latex/contrib/ms
previewers do not honour rotation requests textpos.sty :
in DVI files. Your best bet is to convert macros/latex/contrib/textpos
your output to PostScript or to PDF, and to
228 Preventing page breaks between
view these ‘final’ forms with an appropri-
lines
ate viewer.
One commonly requires that a block of
geometry.sty :
typeset material be kept on the same page;
macros/latex/contrib/geometry
it turns out to be surprisingly tricky to ar-
graphics.sty : Distributed as part range this.
of macros/latex/required/ LaTeX provides a samepage environ-
graphics ment which claims it does this sort of thing
longtable.sty : Distributed as part of for you. It proceeds by setting infinite
macros/latex/required/tools penalties for all sorts of page-break situ-
ations; but in many situations where you
lscape.sty : Distributed as part
want to prevent a page break, samepage
of macros/latex/required/
doesn’t help. If you’re trying to keep
graphics
running text together, you need to end
memoir.cls: the paragraph inside the environment (see
macros/latex/contrib/memoir preserving paragraph parameters). Also,
pdflscape.sty : Distributed with if the things you are trying to keep to-
Heiko Oberdiek’s packages gether insert their own pagebreak hints,
macros/latex/contrib/oberdiek samepage has no power over them (though
rotating.sty :
list items’ attempts — they suggest page
macros/latex/contrib/rotating
breaks between items — are subverted by
samepage). Naturally, if samepage does
rotfloat.sty : work, it is capable of leaving stuff jutting
macros/latex/contrib/rotfloat out at the bottom of the page.
supertabular.sty : macros/latex/ Another convenient trick is to set all
contrib/supertabular the relevant stuff in a \parbox (or a
minipage if it contains things like verba-
227 Putting things at fixed positions
tim text that may not be used in the argu-
on the page
ment of a \parbox). The resulting box
TeX’s model of the world is (broadly speak- certainly won’t break between pages, but
ing) that the author writes text, and TeX that’s not to say that it will actually do what
and its macros decide how it all fits on the you want it to do: again, the box may be
page. This is not good news for the author left jutting out at the bottom of the page.
who has, from whatever source, a require- Why do neither of these obvious things
ment that certain things go in exactly the work? — Because TeX can’t really dis-
right place on the page. tinguish between infinitely awful things.
There are places on the page, from Samepage will make any possible break
which things may be hung, and two La- point “infinitely bad” and boxes don’t even
TeX packages allow you position things offer the option of breaks, but if the alter-
relative to such points, thus providing a native is the leave an infinitely bad few
means of absolute positioning. centimetres of blank paper at the bottom
The textpos package aids the construc- of the page, TeX will take the line of least
tion of pages from “blobs”, dotted around resistance and do nothing.
over the page (as in a poster); you give it This problem still arises even if you
the location, and it places your typeset box have \raggedbottom in effect: TeX
accordingly. doesn’t notice the value of that until it
The eso-pic defines a “shipout picture” starts actually shipping a page out. One
that covers the page. The user may add approach is to set:
picture-mode commands to this picture,
which of course can include box place- \raggedbottom
ments as well as the other rather stilted \addtolength{\topskip}{0pt plus 10pt}
124
The 10pt offers a hint to the output rou- document and to check for things that have
tine that the column is stretchable; this will the potential to give trouble. In such a
cause TeX to be more tolerant of the need scenario (which has Knuth’s authority be-
to stretch while building the page. If you’re hind it, if one is to believe the rather few
doing this as a temporary measure, cancel words he says on the subject in the TeX-
the change to \topskip by: book) one can decide, case by case, how
to deal with problems at the last proof-
\addtolength{\topskip}{0pt plus-10pt}
reading stage. At this stage, you can
as well as resetting \flushbottom. (Note manually alter page breaking, using either
that the 10pt never actually shows up, be- \pagebreak or \clearpage, or you can
cause it is overwhelmed when the page place a \nopagebreak command to sup-
is shipped out by the stretchability intro- press unfortunate breaks. Otherwise, you
duced by \raggedbottom; however, it can make small adjustments to the page ge-
could well have an effect if \flushbottom ometry, using \enlargethispage. Sup-
was in effect.) posing you have a line or two that stray:
An alternative (which derives from issue the command \enlargethispage
a suggestion by Knuth in the TeXbook) {2\baselineskip} and two lines are
is the package needspace or the memoir added to the page you’re typesetting.
class, which both define a command Whether this looks impossibly awful or en-
\needspace whose argument tells it what tirely acceptable depends on the document
space is needed. If the space isn’t avail- context, but the command remains a useful
able, the current page is cleared, and the item in the armoury.
matter that needs to be kept together will Note that both \pagebreak and
be inserted on the new page. For example, \nopagebreak take an optional number
if 4 lines of text need to be kept together, argument to adjust how the command
the sequence is to be interpreted. Thus \pagebreak
\par [0], the command ‘suggests’ that a page
\needspace{4\baselineskip} break might be worth doing, whereas
% the stuff that must stay together \pagebreak[4] ‘demands’ a page break.
<text generating lines 1-4> Similarly \nopagebreak[0] makes a sug-
% now stuff we don’t mind about gestion, while \nopagebreak[4] is a de-
mand. In both commands, the default value
Yet another trick by Knuth is useful if you of the optional argument is 4.
have a sequence of small blocks of text
that need, individually, to be kept on their memoir.cls:
macros/latex/contrib/memoir
own page. Insert the command \filbreak
before each small block, and the effect is needspace.sty : macros/latex/
achieved. The technique can be used in contrib/needspace
the case of sequences of LaTeX-style sec- 229 Parallel setting of text
tions, by incorporating \filbreak into the
definition of a command (as in patching It’s commonly necessary to present text in
commands). A simple and effective patch two languages ‘together’ on a page, or on a
would be: two-page spread. For this to be satisfactory,
one usually needs some sort of alignment
\let\oldsubsubsection=\subsubsection between the two texts.
\renewcommand{\subsubsection}{% The parallel package satisfies the need,
\filbreak permitting typesetting in two columns (not
\oldsubsubsection necessarily of the same width) on one page,
} or on the two opposing pages of a two-page
While the trick works for consecutive se- spread. Use can be as simple as
quences of blocks, it’s slightly tricky to get \usepackage{parallel}
out of such sequences unless the sequence ...
is interrupted by a forced page break (such \begin{Parallel}{<left-width>}{<right-width}
as \clearpage, which may be introduced \ParallelLText{left-text}
by a \chapter command, or the end of \ParallelRText{right-text}
the document). If the sequence is not inter- \ParallelPar
rupted, the last block is likely to be forced ...
onto a new page, regardless of whether it \end{Parallel}
actually needs it.
If one is willing to accept that not ev- Parallel can get terribly confused with
erything can be accomplished totally auto- colour changes, in PDFTeX; the indefati-
matically, the way to go is to typeset the gable Heiko Oberdiek has a patch for this
125
issue — the pdfcolparallel package, which \epigraph{Oh! My ears and whiskers!}%
maintains separate colour stacks for the {Lewis Carroll}
columns.
The parcolumns package can (in prin- and an epigraphs environment, for entering
ciple) deal with any number of columns: more than one epigraph consecutively, in
the documentation shows its use with three a sort of list introduced by \qitem com-
columns. Usage is rather similar to that of mands:
parallel, though there is of course a “num-
\begin{epigraphs}
ber of columns to specify”:
\qitem{What I tell you three times is true}%
\usepackage{parcolumns} {Lewis Carroll}
... \qitem{Oh listen do, I’m telling you!}%
\begin{parcolumns}[<options>]{3} {A.A. Milne}
\colchunk{<Column 1 text>} \end{epigraphs}
\colchunk{<Column 2 text>}
\colchunk{<Column 3 text>}
The \epigraphhead command enables
\colplacechunks
you to place your epigraph above a chapter
...
header:
\end{parcolumns}
\setlength{\unitlength}{1pt}
The hoptionsi can specify the widths of ...
the columns, whether to place rules be- \chapter{The Social Life of Rabbits}
tween the columns, whether to set the \epigraphhead[<distance>]{%
columns sloppy, etc. Again, there are is- \epigraph{Oh! My ears and whiskers!}%
sues with colours, which are addressed by {Lewis Carroll}%
the pdfcolparcolumns package. }
The ledpar package is distributed with
The hdistancei says how far above the
(and integrated with) the ledmac package.
chapter heading the epigraph is to go; it’s
It provides parallel setting carefully inte-
expressed in terms of the \unitlength
grated with the needs of a scholarly text,
that’s used in the picture environment;
permitting translation, or notes, or both, to
the package’s author recommends 70pt.
be set in parallel with the ‘base’ text of the
The package also offers various tricks
document.
for adjusting the layout of chapter header
ledpar.sty : Distributed with (necessary if you’ve found a hugely long
macros/latex/contrib/ledmac quotation for an \epigraphhead), for
parallel.sty : patching the bibliography, for patching
macros/latex/contrib/parallel \part pages, and so on. (Some of these
suggested patches lead you through writ-
parcolumns.sty : Distributed as part of
ing your own package. . . )
macros/latex/contrib/sauerj
The quotchap package redefines chap-
pdfcolparallel.sty : ter headings (in a moderately striking way),
Distributed as part of and provides an environment savequotes
macros/latex/contrib/oberdiek in which you can provide one (or more)
pdfcolparcolumns.sty : quotations to use as epigraphs. The fa-
pdfcolparcolumns] cilities seem not as flexible as those of
epigraph, but it’s probably easier to use.
230 Typesetting epigraphs The memoir class offers all the fa-
Epigraphs are those neat quotations that cilities of the epigraph package. The
authors put at the start of chapters (or even Koma-script classes have commands
at the end of chapters: Knuth puts things \setchapterpreamble and \dictum to
at the ends of chapters of the TeXbook). provide these facilities.
Typesetting them is a bit of a fiddle, epigraph.sty :
but not impossible to do for yourself. For- macros/latex/contrib/epigraph
tunately, there are two packages that do the
job, to some extent; there are also facili- KOMA script bundle:
ties in the two “big” classes (memoir and macros/latex/contrib/koma-
koma-script. script
The epigraph package defines an memoir.cls:
\epigraph command, for creating a single macros/latex/contrib/memoir
epigraph (as at the top of a chapter):
quotchap.sty :
macros/latex/contrib/quotchap
\chapter{The Social Life of Rabbits}
126
O.4 Spacing of characters and between the letters (otherwise known as
lines the tracking). As a general rule, this is a
very bad idea: it detracts from legibility,
231 Double-spaced documents in which is contrary to the principles of type-
LaTeX setting (any respectable font you might be
A quick and easy way of getting inter- using should already have optimum track-
line space for copy-editing is to change ing built into it).
\baselinestretch — \linespread The great type designer, Eric Gill,
{1.2} (or, equivalently \renewcommand is credited with saying “he who would
{\baselinestretch}{1.2}) may be ad- letterspace lower-case text, would steal
equate. Note that \baselinestretch sheep”. (The attribution is probably apoc-
changes don’t take effect until you select aryphal: others are also credited with the
new font, so make the change in the pream- remark. Stealing sheep was, in the 19th
ble before any font is selected. Don’t try century, a capital offence in Britain.) As
changing \baselineskip: its value is re- the remark suggests, though, letterspacing
set at any size-changing command so that of upper-case text is less awful a crime; the
results will be inconsistent. technique used also to be used for empha-
For preference (and certainly for a pro-
sis of text set in Fraktur (or similar) fonts.
duction document, such as a dissertation or Straightforward macros (usable, in
an article submission), use a line-spacing principle, with any TeX macro package)
package. The only one currently supported may be found in letterspacing (which is
is setspace. Setspace switches off double- the name of the .tex file).
spacing at places where even the most die- A more comprehensive solution is to
hard official would doubt its utility (foot-be found in the soul package (which is op-
notes, figure captions, and so on); it’s very
timised for use with LaTeX, but also works
difficult to do this consistently if you’re ma-
with Plain TeX). Soul also permits hyphen-
nipulating \baselinestretch yourself. ation of letterspaced text; Gill’s view of
(Note: do not be tempted by such an activity is not (even apocryphally)
doublespace — its performance under cur- recorded. (Spacing-out forms part of the
rent LaTeX is at best problematical.) name of soul; the other half is described in
Of course, the real solution (other another question.)
than for private copy editing) is not to Possibly the ‘ultimate’ in this field
use double-spacing at all. Universities, is the microtype, which uses the micro-
in particular, have no excuse for speci- typography capabilities of current PDFTeX
fying double-spacing in submitted disser- to provide a \textls command, which op-
tations: LaTeX is a typesetting system, erates according to parameters declared in
not a typewriter-substitute, and can (prop- a \SetTracking command. Microtype’s
erly used) make single-spaced text even ‘tracking’ facility expands the natural spac-
more easily readable than double-spaced ing of the font itself, rather than insert-
typewritten text. If you have any influ- ing space between characters. Ordinarily,
ence on your university’s system (for ex- letter-spacing will destroy ligatures; how-
ample, through your dissertation supervi- ever, this is wrong for some font styles (for
sor), it may be worth attempting to get the example, fraktur), and the package pro-
rules changed (at least to permit a “well- vides a means of protecting the ligatures in
designed book” format). a letter-spaced text.
Double-spaced submissions are also letterspacing.tex :
commonly required when submitting pa- macros/generic/misc/
pers to conferences or journals. Fortu- letterspacing.tex
nately (judging by the questions from users
in this author’s department), this demand microtype.sty : macros/latex/
is becoming less common. contrib/microtype
Documentation of setspace appears as soul.sty :
TeX comments in the package file itself. macros/latex/contrib/soul
setspace.sty : macros/latex/
contrib/setspace/setspace.sty 233 Setting text ragged right
The trick with typesetting ragged right is
232 Changing the space between to be sure you’ve told the TeX engine
letters “make this paragraph ragged, but never too
A common technique in advertising copy ragged”. The LaTeX \raggedright com-
(and other text whose actual content need mand (and the corresponding flushleft
not actually be read) is to alter the space environment) has a tendency to miss the
127
“never” part, and will often create ridicu- O.5 Typesetting specialities
lously short lines, for some minor benefit 235 Including a file verbatim in
later in the paragraph. The Plain TeX ver- LaTeX
sion of the command doesn’t suffer this
failing, but is rather conservative: it is A good way is to use Rainer Schöpf’s
loath to create too large a gap at the end verbatim package, which provides a com-
of the line, but in some circumstances — mand \verbatiminput that takes a file
such as where hyphenation is suppressed — name as argument:
painfully large gaps may sometimes be re- \usepackage{verbatim}
quired. ...
Martin Schröder’s ragged2e package \verbatiminput{verb.txt}
offers the best of both worlds: it pro-
Another way is to use the alltt envi-
vides raggedness which is built on the
ronment, which requires the alltt pack-
Plain TeX model, but which is easily con-
age. The environment interprets its con-
figurable. It defines easily-remembered
tents ‘mostly’ verbatim, but executes any
command (e.g., \RaggedRight) and envi-
(La)TeX commands it finds:
ronment (e.g., FlushLeft) names that are
simply capitalised transformations of the \usepackage{alltt}
LaTeX kernel originals. The documenta- ...
tion discusses the issues and explains the \begin{alltt}
significance of the various parameters of \input{verb.txt}
ragged2e’s operation. \end{alltt}
ragged2e.sty : Distributed as part of of course, this is little use for inputting
macros/latex/contrib/ms (La)TeX source code. . .
The moreverb package extends the
234 Cancelling \ragged commands verbatim package, providing a listing
LaTeX provides commands \raggedright environment and a \listinginput com-
and \raggedleft, but none to cancel mand, which line-number the text of
their effect. The \centering command the file. The package also has a
is implemented in the same way as the \verbatimtabinput command, that hon-
\ragged* commands, and suffers in the ours TAB characters in the input (the
same way. package’s listing environment and the
The following code (to be inserted in \listinginput command also both hon-
a package of your own, or as internal La- our TAB).
TeX code —internal LaTeX code) defines The sverb package provides verbatim
a command that restores flush justification input (without recourse to the facilities of
at both margins: the verbatim package):
\def\flushboth{% \usepackage{sverb}
\let\\\@normalcr ...
\@rightskip\z@skip \rightskip\@rightskip
\verbinput{verb.txt}
\leftskip\z@skip
The fancyvrb package offers con-
\parindent 1.5em\relax}
figurable implementations of everything
There’s a problem with the setting of verbatim, sverb and moreverb have, and
\parindent in the code: it’s necessary more besides. It is nowadays the package
because both the \ragged commands set of choice for the discerning typesetter of
\parindent to zero, but the setting isn’t a verbatim text, but its wealth of facilities
constant of nature: documents using a stan- makes it a complex beast and study of the
dard LaTeX class with twocolumn option documentation is strongly advised.
will have 1.0em by default, and there’s no The memoir class includes the relevant
knowing what you (or some other class) functionality of the verbatim and moreverb
will have done. packages.
Any but a really old copy of Mar-
alltt.sty : Part of the LaTeX
tin Schröder’s ragged2e package has a
\justifying command to match its ver-
distribution.
sions of the LaTeX ‘ragged’ commands. fancyvrb.sty :
The package also provides a justify en- macros/latex/contrib/fancyvrb
vironment, which permits areas of justified memoir.cls:
text in a larger area which is ragged. macros/latex/contrib/memoir
ragged2e.sty : Distributed as part of moreverb.sty :
macros/latex/contrib/ms macros/latex/contrib/moreverb
128
sverb.sty : Distributed as part of in the typesetting of dissertations by com-
macros/latex/contrib/mdwtools puter science and other students who are
verbatim.sty : Distributed as part of
expected to write programs. Simple ver-
macros/latex/required/tools
batim listings of programs are commonly
useful, as well.
236 Including line numbers in typeset Verbatim listings are dealt with else-
output where, as is the problem of typesetting al-
For general numbering of lines, there are gorithm specifications.
two packages for use with LaTeX, lineno The listings package is widely regarded
(which permits labels attached to individ- as the best bet for formatted output (it is
ual lines of typeset output) and numline. capable of parsing program source, within
(Numline is considered obsolete, but re- the package itself), but there are several
mains available from the archive.) well-established packages that rely on a
Both of these packages play fast and pre-compiler of some sort. You may use
loose with the LaTeX output routine, listings to typeset snippets that you include
which can cause problems: the user should within your source:
beware. . . \usepackage{listings}
If the requirement is for numbering ver- \lstset{language=C}
batim text, moreverb, or fancyvrb (see in- ...
cluding files verbatim) may be used. Class \begin{document}
memoir also provides the necessary facili- \begin{lstlisting}
ties. #include <stdio.h>
One common use of line numbers is in
critical editions of texts, and for this the int main(int argc, char ** argv)
edmac package offers comprehensive sup- {
port; ledmac is a LaTeX port of edmac. printf("Hello world!\n");
The vruler package sidesteps many return 0;
of the problems associated with line- }
numbering, by offering (as its name sug- \end{lstlisting}
gests) a rule that numbers positions on the \end{document}
page. The effect is good, applied to even-
looking text, but is poor in texts that in- or you can have it typeset whole files:
volve breaks such as interpolated mathe-
\usepackage{listings}
matics or figures. Documentation of the
\lstset{language=C}
package, in the package itself, is pretty
...
tough going, though there is an example
\begin{document}
(also inside the package file).
\lstinputlisting{main.c}
edmac: macros/plain/contrib/edmac \end{document}
fancyvrb.sty : These very simple examples may be dec-
macros/latex/contrib/fancyvrb orated in a huge variety of ways, and of
ledmac.sty : course there are other languages in the
macros/latex/contrib/ledmac package’s vocabulary than just C. . .
For a long time, advice on (La)TeX
lineno.sty :
lists seemed to regard listings as the be-all
macros/latex/contrib/lineno
and end-all on this topic. In the last few
memoir.cls: years, viable alternatives have appeared
macros/latex/contrib/memoir Highlight is attractive if you need more
moreverb.sty : than one output format for your program:
macros/latex/contrib/moreverb as well as (La)TeX output, highlight will
produce (X)HTML, RTF and XSL-FO rep-
numline.sty :
resentations of your program listing. The
obsolete/macros/latex/
manual leads you through the details of
contrib/numline/numline.sty
defining a parameter file for a “new” lan-
vruler.sty : guage, as well as the presentation details
macros/latex/contrib/vruler of a language.
The minted package is another al-
237 Code listings in LaTeX ternative that offers the means of cre-
‘Pretty’ code listings are sometimes con- ating new language definitions. It re-
sidered worthwhile by the “ordinary” pro- quires that code be processed using
grammer, but they have a serious place an external (python) script, Pygments.
129
Pygments, in turn, needs a “lexer” that showexpl.sty :
knows the language you want to process; macros/latex/contrib/showexpl
lots of these are available, for the more tgrind : support/tgrind
commonly-used languages, and there is
advice on “rolling your own” on the <a tiny_c2l: support/tiny_c2l
href=’http://pygments.org/docs/lexerdevelopment/’>Pygments
238 Typesetting pseudocode in
site</a> LaTeX
Usage of minted can be as simple as
There is no consensus on the ‘right’ way to
\begin{minted}{hlanguagei} typeset pseudocode. Consequently, there
... are a variety of LaTeX packages to choose
\end{minted} from for producing æsthetically pleasing
pseudocode listings.
which processes the program code dynam-
Pseudocode differs from actual pro-
ically, at typesetting time — though such
gram listings in that it lacks strict syntax
usage is likely to require that separate pro-
and semantics. Also, because pseudocode
cessing be enabled.
is supposed to be a clear expression of
On a rather different path, the pack-
an algorithm it may need to incorporate
age showexpl supports typesetting (La)TeX
mathematical notation, figures, tables, and
code and its typeset output, in parallel
other LaTeX features that do not appear
‘panes’. (Thiscould provide support for
in conventional programming languages.
(La)TeX instruction texts, or for papers in
Typesetting program listings is described
TeX user group publications. The pack-
elsewhere.
age uses listings for its (La)TeX pane, and
You can certainly create your own envi-
typesets the result into a simple box, for
ronment for typesetting pseudocode using,
the other pane.
for example, the tabbing or list envi-
Longer-established, and variously less
ronments — it’s not difficult, but it may
“powerful” systems include:
prove boring. So it’s worth trying the fol-
• The lgrind system is a well- lowing packages, all designed specifically
established pre-compiler, with all for typesetting pseudocode.
the facilities one might need and a The algorithms bundle (which contains
wide repertoire of languages; it is de- packages algorithm and algorithmic, both
rived from the even longer-established of which are needed for ordinary use) has
tgrind, whose output is based on Plain a simple interface and produces fairly nice
TeX. output. It provides primitives for state-
• The tiny_c2l system is slightly more ments, which can contain arbitrary LaTeX
recent: users are again encouraged to commands, comments, and a set of iter-
generate their own driver files for lan- ative and conditional constructs. These
guages it doesn’t already deal with, primitives can easily be redefined to pro-
but its “tiny” name correctly hints that duce different text in the output. However,
it’s not a particularly elaborate system. there is no support for adding new primi-
• The C++2LaTeX system comes with tives. Typesetting the pseudocode itself is
strong recommendations for use with performed in algorithmic; the algorithms
C and C++. package uses the facilities of the float pack-
• An extremely simple system is age to number algorithms sequentially, en-
c2latex, for which you write LaTeX able algorithms to float like figures or ta-
source in your C program comments. bles, and support including a List of Algo-
The program then converts your pro- rithms in a document’s front matter.
gram into a LaTeX document for pro- Packages in the algorithmicx bundle
cessing. The program (implicitly) are similar both in concept and output
claims to be “self-documenting”. form to algorithmic but additionally pro-
vide support for adding new keywords and
c2latex : support/c2latex
altering the formatting. It provides the
C++2LaTeX : algpseudocode package which is (almost)
support/C++2LaTeX-1_1pl1 a drop-in replacement for algorithmic. An-
highlight: support/highlight other package in the bundle, algpascal,
lgrind : support/lgrind
uses Pascal-like keywords, indents differ-
ently from algpseudocode, and puts com-
listings.sty : mand arguments in maths mode instead of
macros/latex/contrib/listings text mode. There is no floating environ-
minted.sty : ment but algorithmicx, like algorithmic,
macros/latex/contrib/minted is compatible with the algorithm package.
130
(There have been reports of difficulty defin- algorithms bundle: macros/latex/
ing new commands to fit with the package; contrib/algorithms
unfortunately, the author is not available to alg.sty : macros/latex/contrib/alg
comment.)
clrscode.sty :
The alg package, like algorithms, of-
macros/latex/contrib/clrscode
fers a floating algorithm environment with
all of the ensuing niceties. alg, however, float.sty :
can caption its floats in a variety of (nat- macros/latex/contrib/float
ural) languages. In addition, alg unlike newalg.sty :
algorithms, makes it easy to add new con- macros/latex/contrib/newalg
structs.
program.sty :
The newalg package has a somewhat
macros/latex/contrib/program
similar interface to algorithms, but its out-
put is designed to mimic the rather pleas- pseudocode.sty : macros/latex/
ant typesetting used in the book “Introduc- contrib/pseudocode
tion to Algorithms” by Corman, Leiserson, 239 Generating an index in (La)TeX
Rivest and Stein. Unfortunately, newalg
does not support a floating environment or Making an index is not trivial; what to in-
any customisation of the output. dex, and how to index it, is difficult to de-
cide, and uniform implementation is diffi-
“Bona fide” use of the style of “Intro-
cult to achieve. You will need to mark all
duction to Algorithms” may be achieved
items to be indexed in your text (typically
with Cormen’s own clrscode: this is the
with \index commands).
package as used in the second edition of
It is not practical to sort a large index
the book.
within TeX, so a post-processing program
Similarly, the style of “Combinatorial
is used to sort the output of one TeX run, to
Algorithms: Generation, Enumeration and
be included into the document at the next
Search” is supported by the pseudocode
run.
package, written by the authors of the book.
The following programs are available:
It has the common ‘Pascal-like’ style, and
has some interesting constructs for what makeindex Comes with most distribu-
one thinks of as Pascal blocks. tions — a good workhorse, but is not
The algorithm2e is of very long stand- well-arranged to deal with other sort
ing, and is widely used and recommended. orders than the canonical ASCII order-
It loads the float package to provide the ing.
option of floating algorithm descriptions, The makeindex documentation is a
but you can always use the “H” option of good source of information on how to
float to have the algorithm appear “where create your own index. Makeindex can
you write it”. be used with some TeX macro pack-
The usage of the program package is a ages other than LaTeX, such as Eplain
little different from that of the other pack- (Eplain), and TeX (whose macros
ages. It typesets programs in maths mode can be used independently with Plain
instead of text mode; and linebreaks are TeX).
significant. program lacks a floating envi- idxtex for LaTeX under VMS; idxtex
ronment but does number algorithms like comes with a glossary-maker glotex.
alg and algorithms. Customisation and texindex(1) A witty little shell-script us-
extension are not supported. Documenta- ing sed and awk; designed for LaTeX
tion of the program package (such as it under Unix.
is) appears in a file program.msg in the texindex(2) The Texinfo system also of-
distribution. fers a program texindex, whose source
None of the above are perfect. The fac- is to be found in the texinfo distribu-
tors that should influence your choice of tion. The ltxindex package provides
package include the output style you prefer, macros that enable LaTeX users to use
how much you need to extend or modify this texindex.
the set of keywords, and whether you re- xindy arose from frustration at the diffi-
quire algorithms to float like figures and culty of making a multi-language ver-
tables. sion of makeindex. It is designed to be
a successor to makeindex, by a team
algorithm2e.sty : macros/latex/
that included the then-current main-
contrib/algorithm2e
tainer of makeindex. It successfully
algorithmicx bundle: macros/latex/ addresses many of makeindex’s short-
contrib/algorithmicx comings, including difficulties with
131
 collation order in different languages, commands (use of \protect) for use
and it is highly flexible. within moving arguments.
Xindy itself will work with Unicode The package ordinarily ignores spaces
(UTF-8) encoded LaTeX input. A sep- in the URL, but unfortunately URLs
arate application (texindy) deals with that contain spaces do exist; to type-
‘standard’ LaTeX source, processes it set them, call the package with the
and passes ‘sanitised’ text to Xindy. obeyspaces option. Two other use-
ful options allow line breaks in the
idxtex : indexing/glo+idxtex URL in places where they are or-
ltxindex.sty : dinarily suppressed to avoid confu-
macros/latex/contrib/ltxindex sion: spaces to allow breaks at spaces
(note, this requires obeyspaces as
makeindex : indexing/makeindex
well, and hyphens to allow breaks af-
makeindex (Macintosh): systems/ ter hyphens. (Note that the package
mac/macmakeindex2.12.sea.hqx never does “ordinary” hyphenation of
texindex (the script): names inside an URL.)
indexing/texindex It is possible to use the url package in
Plain TeX, with the assistance of the
texindex (the program): Distributed miniltx package (which was originally
with macros/texinfo/texinfo developed for using the LaTeX graph-
texsis (system): macros/texsis ics package in Plain TeX). A small
patch is also necessary: the required
texsis (makeindex support):
sequence is therefore:
macros/texsis/index/index.tex
\input miniltx
xindy : indexing/xindy
\expandafter\def\expandafter\+\expandafter{\+}
240 Typesetting URLs \input url.sty

URLs tend to be very long, and con- • The hyperref package, which uses the
tain characters that would naturally pre- typesetting code of url, in a context
vent them being hyphenated even if they where the typeset text forms the an-
weren’t typically set in \ttfamily, ver- chor of a link.
batim. Therefore, without special treat-
The author of this answer prefers the
ment, they often produce wildly overfull
(rather newer) url package (directly or in-
\hboxes, and their typeset representation
directly); both path and url work well with
is awful.
Plain TeX (though of course, the fancy La-
There are three packages that help
TeX facilities of url don’t have much place
solve this problem:
there). (hyperref isn’t available in a ver-
• The path package, which defines a sion for use with Plain TeX.)
\path command. The command de- Note that neither \path (from package
fines each potential break character path) nor \url (from package url) is ro-
as a \discretionary, and offers the bust (in the LaTeX sense). If you need
user the opportunity of specifying a a URL to go in a moving argument, you
personal list of potential break charac- need the command \urldef from the url
ters. Its chief disadvantage is fragility package. So one might write:
in LaTeX moving arguments. The \urldef\faqhome\url{http://www.tex.ac.uk/faq}
Eplain macros — define a similar
\path command. after which, \faqhome is robust.
Path, though it works in simple situa- Documentation of both package path
tions, makes no attempt to work with and package url is in the package files.
LaTeX (it is irremediably fragile). De- hyperref.sty :
spite its long and honourable history, macros/latex/contrib/hyperref
it is no longer recommended for La-
miniltx.tex : Distributed as part of
TeX use.
macros/plain/graphics
• The url package, which defines an
\url command (among others, includ- path.sty : macros/generic/path
ing its own \path command). The url.sty : macros/latex/contrib/url
command gives each potential break
character a maths-mode ‘personality’, 241 Typesetting music in TeX
and then sets the URL itself (in the The current best bet for music typesetting
user’s choice of font) in maths mode. is to use musixtex. Musixtex is a three-
It can produce (LaTeX-style) ‘robust’ pass system that has a TeX-based pass,
132
a processing pass and then a further TeX mainstream, and is no longer maintained.
pass. The middle pass, a program called The current recommended way of doing
musixflx, optimises the spacing and sorts OpusTeX’s job is gregorio, which can in
out slurs and ties. Musixtex is demand- principle feed into a TeX-based document.
ing of TeX resources, and any significant Once Andreas Egler had withdrawn
score requires that typesetting is done us- (his last version of musixtex is preserved
ing e-TeX, whose expanded variable- and on the archive), Daniel Taupin took up the
box-register ranges allow for more of the development, leading to the musixtex used
“parallel” activities that abound in a music today.
score. Of course, musixtex also requires abc2mtex : support/abc2mtex
music fonts; those are available in a sepa-
rate package on the archive. lilyglyphs: macros/luatex/latex/
lilyglyphs
Musixtex requires pretty arcane input;
most people using it actually prepare (less M-Tx : support/m-tx
obscure) input for pmx, whose output is midi2tex : support/midi2tex
TeX input suitable for musixtex.
musictex : macros/musictex
A further preprocessor, M-Tx, allows
preparation of music with lyrics; M-Tx’s musixtex (Taupin’s version):
output is fed into pmx, and thence to macros/musixtex
musixtex. musixtex (Egler’s version): obsolete/
An alternative path to music examples macros/musixtex/egler
within a (La)TeX document is Lilypond.
musixtex fonts:
Lilypond is (at heart) a batch music typeset-
fonts/musixtex-fonts
ting system with plain text input that does
most of its work without TeX. Lilypond’s mutex : macros/mtex
input syntax is less cryptic than is MusiX- pmx : support/pmx
TeX’s, though similar quality is achieved.
The lilypond FAQ mentions programs with 242 Zero paragraph indent
graphical user interfaces, that export lily- The conventional way of typesetting run-
pond output. ning text has no separation between para-
For occasional music references (sharp graphs, and the first line of each paragraph
and flat signs, notes, clefs and so on, there in a block of text indented.
is a (LaTeX) package (with associated font) In contrast, one common convention
called lilyglyphs. This uses lilypond’s fonts for typewritten text was to have no inden-
(which are included in the package), and tation of paragraphs; such a style is often
also provides the means to add stuff from required for “brutalist” publications such
other sources. as technical manuals, and in styles that han-
Another alternative in the production ker after typewritten manuscripts, such as
of music is the ABC notation, which was officially-specified dissertation formats.
developed to notate the traditional music of Anyone can see, after no more than
Western Europe (which can be written on a moment’s thought, that if the paragraph
a single stave), though it can be used much indent is zero, the paragraphs must be sepa-
more widely. A front end to musictex (see rated by blank space: otherwise it is some-
below), abc2mtex, makes ABC typesetting times going to be impossible to see the
possible. breaks between paragraphs.
The program midi2tex can also gener- The simple-minded approach to zero
ate musictex output, from MIDI files. paragraph indentation is thus:
The history of music in TeX goes back \setlength{\parindent}{0pt}
some time; the earliest “working” macros \setlength{\parskip}{\baselineskip}
were MuTeX, by Angelika Schofer and
Andrea Steinbach. MuTeX was very lim- and in the very simplest text, it’s a fine
ited, but it was some time before Daniel solution.
Taupin took up the baton, and developed However, the non-zero \parskip inter-
MusicTeX, which allows the typesetting of feres with lists and the like, and the result
polyphonic and other multiple-stave mu- looks pretty awful. The parskip package
sic; MusicTeX remains available, but is no patches things up to look reasonable; it’s
longer recommended. not perfect, but it deals with most prob-
The first version of MusixTeX was de- lems.
veloped by Andreas Egler, but he with- The Netherlands Users’ Group’s set
drew from the project to work on another of classes includes an article equiva-
package, OpusTeX. That never reached the lent (artikel3) and a report equivalent
133
(rapport3) whose design incorporates zero Therefore, if you need to use commas
paragraph indent and non-zero paragraph as decimal separator, you will probably
skip. welcome macro support. There are two
NTG classes: packages that can help relieve the tedium:
macros/latex/contrib/ntgclass icomma and ziffer.
Icomma ensures that there will be no
parskip.sty :
extra space after a comma, unless you type
macros/latex/contrib/parskip
a space after it (as in f(x, y) — in the ab-
243 Big letters at the start of a sence of the package, you don’t need that
paragraph space), in which case the usual small space
A common style of typesetting, now sel- after the comma appears. Ziffer is specifi-
dom seen except in newspapers, is to start cally targeted at the needs of those typeset-
a paragraph (in books, usually the first of a ting German, but covers the present need,
chapter) with its first letter set large enough as well as providing the double-minus sign
to span several lines. used in German (and other languages) for
This style is known as “dropped capi- the empty ‘cents’ part of an amount of cur-
tals”, or (in French) “lettrines”, and TeX’s rency.
primitive facilities for hanging indentation The numprint package provides a com-
make its (simple) implementation pretty mand \numprint{number} that prints its
straightforward. argument according to settings you give it,
The dropping package does the job sim- or according to settings chosen to match
ply, but has a curious attitude to the calcula- the language you have selected in babel.
tion of the size of the font to be used for the The formatting works equally well in text
big letters. Examples appear in the pack- or maths. The command is very flexible
age documentation, so before you process (it can also group the digits of very ‘long’
the .dtx, the package itself must already numbers), but is inevitably less convenient
be installed. Unfortunately, dropping has than icomma or ziffer if you are typing a
an intimate relation to the set of device lot of numbers.
drivers available in an early version of the icomma.sty : Distributed as part of
LaTeX graphics package, and it cannot be macros/latex/contrib/was
trusted to work with modern offerings such
as PDFTeX or DVIpdfm, let alone such numprint.sty :
macros/latex/contrib/numprint
modernisms as XeTeX. As a result, the
package is widely deprecated, nowadays. ziffer.sty :
The more recent lettrine package is macros/latex/contrib/ziffer
generally more reliable. It has a well-
constructed array of options, and an im- 245 Breaking boxes of text
pressive set of examples adds to the pack- (La)TeX boxes may not be broken, in ordi-
age’s document. nary usage: once you’ve typeset something
dropping : into a box, it will stay there, and the box
macros/latex/contrib/dropping will jut out beyond the side or the bottom
of the page if it doesn’t fit in the typeset
lettrine:
area.
macros/latex/contrib/lettrine
If you want a substantial portion of
244 The comma as a decimal your text to be framed (or coloured), the re-
separator striction imposes a serious restriction. For-
TeX embodies the British/American cul- tunately, there are ways around the prob-
tural convention of using a period as the lem.
separator between the whole number and The framed package provides framed
the decimal fraction part of a decimal num- and shaded environments; both put their
ber. Other cultures use a comma as separa- content into something which looks like
tor, but if you use a comma in maths mode a framed (or coloured) box, but which
you get a small space after it; this space breaks as necessary at page end. The en-
makes a comma that is used as a decimal vironments “lose” footnotes, marginpars
separator look untidy. and head-line entries, and will not work
A simple solution to this problem, in with multicol or other column-balancing
maths mode, is to type 3{,}14 in place of macros. The memoir class includes the
3,14. While such a technique may pro- functionality of the framed package.
duce the right results, it is plainly not a The mdframed package does the same
comfortable way to undertake any but the job, using a different algorithm. The pack-
most trivial amounts of typing numbers. age also provides means of defining ‘pri-
134
vate’ framed environments, whose param- Documentation of ulem is in the pack-
eters are set at definition time, thus sav- age file.
ing considerable effort in documents with pdfcomment.sty : macros/latex/
many framed boxes. Its restrictions seem contrib/pdfcomment
much the same as those of framed; this is
as one would expect, but the list is notice- soul.sty :
ably different in the two packages’ docu- macros/latex/contrib/soul
mentation. ulem.sty :
The boites package provides a macros/latex/contrib/ulem
breakbox environment; examples of its
use may be found in the distribution, and
247 Realistic quotes for verbatim
the package’s README file contains terse
listings
documentation. The environments may be
nested, and may appear inside multicols The cmtt font has “curly” quotes
environments; however, floats, footnotes (‘thus’), which are pleasing on the eye,
and marginpars will be lost. but don’t really tally with what one sees on
For Plain TeX users, the facilities of a modern xterm (which look like `this').
the backgrnd package may be useful; this The appearance of these quotes is crit-
package subverts the output routine to pro- ical in program listings, particularly in
vide vertical bars to mark text, and the those of Unix-like shell scripts. The
macros are clearly marked to show where upquote package modifies the behaviour
coloured backgrounds may be introduced of the verbatim environment so that the
(this requires shade, which is distributed as output is a clearer representation of what
tex macros and device-independent Meta- the user must type.
font for the shading). The author of upquote.sty : macros/latex/
backgrnd claims that the package works contrib/upquote/upquote.sty
with LaTeX 2.09, but there are reasons to
suspect that it may be unstable working 248 Printing the time
with current LaTeX.
TeX has a primitive register that contains
backgrnd.tex : macros/generic/
“the number of minutes since midnight”;
misc/backgrnd.tex
with this knowledge it’s a moderately sim-
boites.sty : ple programming job to print the time
macros/latex/contrib/boites (one that no self-respecting Plain TeX user
framed.sty : would bother with anyone else’s code for).
macros/latex/contrib/framed However, LaTeX provides no primitive
mdframed.sty : for “time”, so the non-programming La-
macros/latex/contrib/mdframed TeX user needs help.
Two packages are available, both pro-
memoir.cls:
viding ranges of ways of printing the date,
macros/latex/contrib/memoir
as well as of the time: this question will
shade.tex : macros/generic/shade concentrate on the time-printing capabil-
246 Overstriking characters ities, and interested users can investigate
the documentation for details about dates.
This may be used, for example, to indicate
The datetime package defines two time-
text deleted in the course of editing. Both
printing functions: \xxivtime (for 24-
the ulem and the soul packages provide the
hour time), \ampmtime (for 12-hour time)
necessary facilities.
and \oclock (for time-as-words, albeit a
Overstriking with an “attached”
slightly eccentric set of words).
comment may be achieved using the
pdfcomment package, to which you can The scrtime package (part of the com-
give optional arguments with all sorts of pendious KOMA-Script bundle) takes a
detail. The comment text is encoded using package option (12h or 24h) to specify
an Adobe ‘annotation’; unfortunately, sup- how times are to be printed. The com-
port for these annotations is not a common mand \thistime then prints the time ap-
feature of PDF viewers, but if you can propriately (though there’s no am or pm
safely assume that your audience will use in 12h mode). The \thistime command
Acrobat Reader, the facility provides that also takes an optional argument, the char-
extra “shine” that business users so love. acter to separate the hours and minutes: the
Overstriking for cancellation in maths default is of course :.
expressions is achieved by a different datetime.sty :
mechanism. macros/latex/contrib/datetime
135
scrtime.sty : Distributed as part of the dotted leaders, respectively. The series
macros/latex/contrib/koma- of commands named \l@xxx , where xxx
script is the name of a sectional heading (such
as chapter or section, . . . ) control the
249 Redefining counters’
layout of the corresponding heading, in-
\the-commands
cluding the space for section numbers. All
Whenever you request a new LaTeX these internal commands may be individ-
counter, LaTeX creates a bunch of behind- ually redefined to give the effect that you
the-scenes commands, as well as defining want.
the counter itself. All that work may be avoided, using
Among other things, \newcounter the package tocloft which provides a set of
{fred} creates a command \thefred , user-level commands that may be used to
which expands to “the value of fred ” change the TOC formatting. Since exactly
when you’re typesetting. the same mechanisms are used for the List
The definition of \thefred should ex- of Figures and List of Tables, the layout
press the value of the counter: it is almost of these sections may be controlled in the
always always a mistake to use the com- same way.
mand to produce anything else. The value The etoc package offers similar flexi-
may reasonably be expressed as an arabic, bility, together with multicolumn tables of
a roman or a greek number, as an alpha- contents and boxes around tables (and the
betic expression, or even as a sequence (or like).
pattern of) symbols. If you need a decision The KOMA-Script classes provides
process on whether to re-define \thefred , an optional variant structure for the ta-
consider what might happen when you do ble of contents, and calculates the space
so. needed for the numbers automatically. The
So, for example, if you want your sec- memoir class includes the functionality of
tion numbers to be terminated by a pe- tocloft.
riod, you could make \thesection ex-
etoc.sty :
pand with a terminating period. However,
macros/latex/contrib/etoc
such a change to \thesection makes the
definition of \thesubsection look dis- KOMA script bundle:
tinctly odd: you are going to find your- macros/latex/contrib/koma-
self redefining things left, right and cen- script
tre. Rather, use the standard techniques
memoir.cls:
for adjusting the presentation of section
macros/latex/contrib/memoir
numbers.
Or, suppose you want the page number tocloft.sty :
to appear at the bottom of each page sur- macros/latex/contrib/tocloft
rounded by dashes (as in “--~nnn~--”).
If you try to achieve this by redefining 251 Unnumbered sections in the
\thepage, problems will arise from the Table of Contents
use of the page number in the table of con- The way the relevant parts of sectioning
tents (each number will have the dashes commands work is exemplified by the way
attached), and \pageref references will the \chapter command uses the counter
be oddly modified. In this case, the change secnumdepth (described in Appendix C
of appearance is best done by redefining of the LaTeX manual):
the page style itself, perhaps using package
fancyhdr. 1. put something in the .aux file, which
will appear in the .toc;
O.6 Tables of contents and 2. if secnumdepth ≥ 0, increase the
indexes counter for the chapter and write it
out.
250 The format of the Table of
3. write the chapter title.
Contents, etc.
The formats of entries in the table of con- Other sectioning commands are similar,
tents (TOC) are controlled by a number but with other values used in the test.
of internal commands (discussed in sec- So a simple way to get headings of
tion 2.3 of The LaTeX Companion. The funny ‘sections’ such as prefaces in the
commands \@pnumwidth, \@tocrmarg table of contents is to use the counter:
and \@dotsep control the space for page
numbers, the indentation of the right-hand \setcounter{secnumdepth}{-1}
margin, and the separation of the dots in \chapter{Preface}
136
Unfortunately, you have to set requirements. The macro to do the
secnumdepth back to its usual value job (\addcontentsline) is fairly simple,
(which is 2 in the standard styles) before but there is always an issue of ensuring
you do any ‘section’ which you want to be that the contents entry quotes the correct
numbered. page. Supposing that our the document
Similar settings are made, automati- is chapter-based (class report or book, for
cally, in the LaTeX book class by the example), the text:
\frontmatter and \backmatter com-
\bibliography{frooble}
mands.
\addcontentsline{toc}{chapter}{Bibliography}
The value of the counter tocdepth
controls which headings will be finally will produce the wrong answer if the bib-
printed in the table of contents; it is nor- liography is more than one page long. In-
mally set in the preamble and is a con- stead, one should say:
stant for the document. The package \cleardoublepage
tocvsec2 package takes the tedium out \addcontentsline{toc}{chapter}{Bibliography}
of changing the secnumdepth and/or the \bibliography{frooble}
tocdepth counter values at any point
in the body of the document; the com- (Note that \cleardoublepage does the
mands (respectively) \setsecnumdepth right thing, even if your document is single-
and \settocdepth make the changes sided — in that case, it’s a synonym for
based on the name of the sectional unit \clearpage). Ensuring that the entry
(chapter, section, etc.). refers to the right place is trickier still in a
The package abstract (see one-column \section -based class.
abstracts) includes an option to add the If you are using hyperref (which will
abstract to the table of contents, while link entries in the table of contents to the
the package tocbibind has options to in- relevant place in the file), a slight adjust-
clude the table of contents itself, the ment is necessary:
bibliography, index, etc., to the table \cleardoublepage
of contents. \phantomsection
The KOMA-Script classes have com- \addcontentsline{toc}{chapter}{Bibliography}
mands \addchap and \addled, which \bibliography{frooble}
work like \chapter and \section but
aren’t numbered. The memoir class in- The extra command (\phantomsection)
corporates the facilities of all three of the gives hyperref something to “hold on to”
abstract, tocbibind and tocvsec2 packages. when making the link.
The common solution, therefore, is to
abstract.sty : use the tocbibind package, which provides
macros/latex/contrib/abstract many facilities to control the way these
KOMA script bundle: entries appear in the table of contents.
macros/latex/contrib/koma- Classes of the KOMA-script bundle
script provide this functionality as a set of class
memoir.cls:
options (e.g., bibtotoc to add the bibliog-
macros/latex/contrib/memoir
raphy to the table of contents); the memoir
class includes tocbibind itself.
tocbibind.sty : macros/latex/
hyperref.sty :
contrib/tocbibind
macros/latex/contrib/hyperref
tocvsec2.sty :
KOMA script bundle:
macros/latex/contrib/tocvsec2
macros/latex/contrib/koma-
252 Bibliography, index, etc., in TOC script
The standard LaTeX classes (and many memoir.cls:
others) use \section* or \chapter* for macros/latex/contrib/memoir
auto-generated parts of the document (the tocbibind.sty : macros/latex/
tables of contents, lists of figures and ta- contrib/tocbibind
bles, the bibliography and the index). As a
result, these items aren’t numbered (which 253 Table of contents, etc., per
most people don’t mind), and (more im- chapter
portantly) they don’t appear in the table of The common style, of a “small” table of
contents. contents for each part, chapter, or even sec-
The correct solution (as always) is tion, is supported by the minitoc package.
to have a class of your own that for- The package also supports mini-lists of ta-
mats your document according to your bles and figures; but, as the documentation
137
observes, mini-bibliographies present a dif- \makeindex{authors}
ferent problem — see bibliographies per ...
chapter. \index{authors}{Eccentric Professor}
The package’s basic scheme is to gen- ...
erate a little .aux file for each chapter, and \index{general}{FAQs}
to process that within the chapter. Simple ...
usage would be: \printindex{general}{General index}
\printindex{authors}{Author index}
\usepackage{minitoc}
... To complete the job, run LaTeX on your
\begin{document} file enough times that labels, etc., are sta-
... ble, and then execute the commands
\dominitoc \tableofcontents
makeindex general
\dominilof \listoffigures
makeindex authors
...
\chapter{blah blah} before running LaTeX again. Note that
\minitoc \mtcskip \minilof the names of the index files to process
... are not necessarily related to the name of
the LaTeX file you’re processing, at all.
though a lot of elaborations are possible
(There’s no documentation that comes with
(for example, you don’t need a \minitoc
the package: what you see above is as good
for every chapter).
as you will get. . . )
Babel doesn’t know about minitoc, but
The multind package doesn’t work
minitoc makes provision for other docu-
with the AMSLaTeX classes, but the AMS
ment languages than English — a wide
provide a substitute, the amsmidx pack-
variety is available. Fortunately, the cur-
age. You use the amsmidx package pretty
rent version of the hyperref package does
much the same as you would multind, but
know about minitoc and treats \minitoc
if things aren’t clear, there is documenta-
tables in the same way as “real” tables of
tion (unlike multind).
contents.
The index package provides a com-
babel.sty : prehensive set of indexing facilities, in-
macros/latex/required/babel cluding a \newindex command that al-
hyperref.sty : lows the definition of new styles of index.
macros/latex/contrib/hyperref \newindex takes a ‘tag’ (for use in index-
ing commands), replacements for the .idx
minitoc.sty :
and .ind file extensions, and a title for
macros/latex/contrib/minitoc
the index when it’s finally printed; it can
254 Multiple indexes also change the item that’s being indexed
LaTeX’s standard indexing capabilities against (for example, one might have an
(those provided by the makeidx package) index of artists referenced by the figure
only provide for one index in your docu- number where their work is shown).
ment; even quite modest documents can be Using index, to create an author index
improved by indexes for separate topics. together with a “normal” index, one would
The multind package provides sim- start with preamble commands:
ple and straightforward multiple indexing. \usepackage{index}
You tag each \makeindex, \index and \makeindex
\printindex command with a file name, \newindex{aut}{adx}{and}{Name Index}
and indexing commands are written to (or
read from) the name with the appropriate which load the package, define a “main”
(.idx or .ind) extension appended. The (original-style) index, and then define an
\printindex command is modified from author index. Then, in the body of the doc-
an old version of the LaTeX 2.09 standard ument, we might find commands like:
so that it doesn’t create its own chapter or
\index[aut]{Another Idiot}
section heading; you therefore decide what
...
names (or sectioning level, even) to use
\index{FAQs}
for the indexes, and \indexname is com-
pletely ignored. Which place an entry in the author index,
To create a “general” and an “authors” and then one in the main index. At the end
index, one might write: of the document, we have two commands:
\usepackage{multind} \printindex
\makeindex{general} \printindex[aut]
138
Which will print the main index and then required/amslatex/amscls
the author index. Supposing this lot imakeidx.sty :
to be in myfile.tex, after enough runs macros/latex/contrib/imakeidx
through LaTeX that labels are stable, exe-
index.sty :
cute the following commands (Unix-style
macros/latex/contrib/index
shell commands shown here, but the prin-
ciple is the same whatever system you’re makeidx.sty : Part of the LaTeX
using): distribution
memoir.cls:
makeindex myfile
macros/latex/contrib/memoir
makeindex myfile.adx -o myfile.and
multind.sty : macros/latex209/
and rerun LaTeX. The makeindex com- contrib/misc/multind.sty
mands process myfile.idx to myfile.
splitidx.sty and splitindex :
ind (the default action), and then myfile.
macros/latex/contrib/
adx to myfile.and, the two files needed
splitindex
as input by the two \printindex com-
mands in myfile.tex. O.7 Labels and references
The splitidx package can operate in the
255 Referring to things by their name
same way as the others: load the package
with the split option, and declare each LaTeX’s labelling mechanism is designed
index with a \newindex command: for the impersonal world of the academic
publication, in which everything has a
\newindex[hindex namei] number: an extension is necessary if we
{hshortcuti} are to record the name of things we’ve la-
and splitidx will generate a file belled. The two packages available extend
\jobname.hshortcuti to receive index
the LaTeX sectioning commands to pro-
entries generated by commands like vide reference by the name of the section.
\sindex[hshortcuti]{hitem i}. As The titleref package is a simple ex-
with the other packages, this method is tension which provides the command
\titleref; it is a stand-alone package —
limited by TeX’s total number of output
files. However, splitindex also comes with don’t use it in a document in which you
a small executable splitindex (available also need to use hyperref .
for a variety of operating systems); if you The byname package is part of the
use this auxiliary program (and don’t use smartref bundle and works well with
split), there’s no limit to the number of
smartref , and works (to an extent) with
indexes. Apart from this trick, splitidx hyperref , but the links it defines are not
supports the same sorts of things as does hyperlinks.
index. An example of use appears in the The memoir class incorporates the
documentation. functionality of titleref , but doesn’t work
The imakeidx package can do a wide with byname (though a search of comp.
text.tex on groups.google.com will
range of things (in particular, it can run
an index-builder — via \write18 com- find a patch to byname to remedy the prob-
mands — so as to simplify business of lem).
making the final copy of a document). The The hyperref bundle includes a pack-
package can also make multiple indexes; it age nameref , which will work standing
can do the job in the conventional (multind) alone (i.e., without hyperref : of course,
way, or by using the external splitindex in this mode its references are not hy-
script provided with the splitindex pack- perlinked). If you load hyperref itself,
age. (This arrangement allows efficient nameref is automatically loaded. Memoir
operation with small numbers of indexes, requires the memhfixc when running with
while retaining the flexibility of permitting hyperref ; following the sequence:
large numbers of indexes without hitting \documentclass[...]{memoir}
the restriction of numbers of active output ...
streams.) \usepackage[...]{hyperref}
The memoir class has its own multiple- \usepackage{memhfixc}
index functionality (as well as its own nameref commands may be used in a
index layout options, which other pack- memoir document.
ages delegate to the index style used by Zref defines a proposed replacement
makeindex). for all of the LaTeX reference mechanisms,
amsmidx.sty : Part of the AMS class and among other things provides name-
distribution macros/latex/ referencing mechanisms:
139
 \usepackage[user,titleref]{zref} \usepackage{xr}
... \externaldocument[V1-]{volume1}
\section{hello}\zlabel{sec:one} ...
The section name is: \ztitleref{sec:one}.
... the introduction to volume1 (\ref{V1-introduction})

(One might hope that something of this To have the facilities of xr working with
sort would be the “way of the future”, but hyperref , you need xr-hyper. For sim-
things move slowly in the LaTeX world: ple hyper-cross-referencing (i.e., to a local
don’t hold your breath.) PDF file you’ve just compiled), write:
Each of titleref , byname and nameref
defines a reference command with the \usepackage{xr-hyper}
same name as the package: \titleref, \usepackage{hyperref}
\byname and \nameref. The nameref \externaldocument[V1-]{volume1}
package also defines a command ...
\byshortnameref, which uses the op- ... the \nameref{V1-introduction})...
tional ‘short’ title argument to the chap-
and the name reference will appear as an
ter and section commands. (Although it
active link to the “introduction” chapter of
comes from the same author, zref doesn’t
volume1.pdf.
define a short-name variant.)
To link to a PDF document on the Web,
byname.sty : Distributed with for which you happen to have the .aux file,
macros/latex/contrib/smartref write:
hyperref.sty :
\usepackage{xr-hyper}
macros/latex/contrib/hyperref
\usepackage{hyperref}
memoir.cls: \externaldocument[V1-]{volume1}[http://mybook.com/volum
macros/latex/contrib/memoir ...
nameref.sty : Distributed with ... the \nameref{V1-introduction})...
macros/latex/contrib/hyperref
Heiko Oberdiek’s experimental zref bun-
smartref.sty :
dle includes a hyper-crossreferencing
macros/latex/contrib/smartref
mechanism using its zref-xr module. Us-
titleref.sty : age is closely modelled on xr and xr-hyper;
macros/latex/contrib/titleref a trivial example (from a comp.text.tex
zref.sty : Distributed as part of posting) is
macros/latex/contrib/oberdiek
\usepackage{zref-xr,zref-user}
256 Referring to labels in other \zexternaldocument*{xr02}
documents ...
When producing a set of inter-related doc- \zref{foo}
uments, you’ll often want to refer to labels
The module provides all the facilities of
in another document of the set; but LaTeX,
the older packages, and can deal both with
of its own accord, doesn’t permit this.
“traditional” LaTeX labels and with zref ’s
So the package xr was written: if you
style of labels.
say
xr.sty : Distributed as part of
\usepackage{xr} macros/latex/required/tools
\externaldocument{volume1}
xr-hyper.sty : Distributed with
will load all the references from volume1 macros/latex/contrib/hyperref
into your present document.
zref bundle: Distributed as part of
But what if the documents both have
macros/latex/contrib/oberdiek
a section labelled “introduction” (likely
enough, after all)? The package provides a
means to transform all the imported labels, P How do I do. . . ?
so you don’t have to change label names
in either document. For example: P.1 Mathematics
\usepackage{xr} 257 Proof environment
\externaldocument[V1-]{volume1}
It was long thought impossible to make a
loads the references from volume1, but proof environment which automatically
prefixes every one with the string V1-. So includes an ‘end-of-proof’ symbol. Some
you would refer to the introduction to vol- proofs end in displayed maths; others do
ume 1 as: not. If the input file contains ...\] \end
140
{proof} then LaTeX finishes off the dis- 259 Defining a new log-like function
played maths and gets ready for a new line in LaTeX
before it reads any instructions connected Use the \mathop command, as in:
with ending the proof, so the code is very
tricky. You can insert the symbol by hand, \newcommand{\diag}{\mathop{\mathrm{diag}}}
but the (apparently) original ‘automatic’ Subscripts and superscripts on \diag
solution came with Paul Taylor’s QED. will be placed below and above the func-
Nowadays, the ntheorem package now tion name, as they are on \lim. If you
solves the problem for LaTeX users: it pro- want your subscripts and superscripts al-
vides an automatic way of signalling the ways placed to the right, do:
end of a proof.
\newcommand{\diag}{\mathop{\mathrm{diag}}\nolimits}
The AMSLaTeX package amsthm also
provides a proof environment that does AMSLaTeX (in its amsopn pack-
the job; though you need to insert a age, which is automatically loaded
\qedhere command if the proof ends with by amsmath) provides a command
a displayed equation: \DeclareMathOperator that takes does
the same job as the first definition above.
\begin{proof} To create our original \diag command,
text... one would say:
\begin{equation*}
maths... \tag*{\qedhere} \DeclareMathOperator{\diag}{diag}
\end{equation*} \DeclareMathOperator* declares the
\end{proof} operator always to have its sub- and su-
perscripts in the “\limits position”.
The \tag*{\qedhere} construction may The amsopn command \operatorname
be used in any of AMSLaTeX’s numbering allows you to introduce ad hoc operators
environments. into your mathematics, so
amsthm.sty : Distributed as part of the
\[ \operatorname{foo}(bar)
AMSLaTeX bundle macros/latex/
\]
required/amslatex
typesets the same as
ntheorem.sty :
macros/latex/contrib/ntheorem \DeclareMathOperator{\foo}{foo}
...
258 Theorem bodies printed in a
\[ \foo(bar) \]
roman font
As with \DeclareMathOperator there’s
If you want to take advantage of the pow-
a starred version \operatorname* for sub-
erful \newtheorem command without the
and superscripts in the limits position.
constraint that the contents of the theorem
(It should be noted that “log-like” was
is in a sloped font (for example, you may
reportedly a joke on Lamport’s part; it is
want to use it to create remarks, examples,
of course clear what was meant.)
proofs, . . . ) then you can use the AMS-
LaTeX amsthm package (which now su- amsopn.sty : Distributed as part of the
persedes the theorem package previously AMSLaTeX distribution macros/
recommended in these answers). Alterna- latex/required/amslatex
tively, the following sets up an environ- 260 Set specifications and Dirac
ment remark whose content is in the de- brackets
fault roman font.
One of the few glaring omissions from
\newtheorem{preremark}{Remark} TeX’s mathematical typesetting capabil-
\newenvironment{remark}% ities is a means of setting separators in
the middle of mathematical expressions.
{\begin{preremark}\upshape}{\end{preremark}}
TeX provides primitives called \left
The ntheorem package provides control of and \right, which can be used to mod-
the fonts used by theorems, directly. ify brackets (of whatever sort) around a
amsthm.sty : Distributed as part mathematical expression, as in: \left(
of macros/latex/required/ <expression> \right) — the size of
amslatex the parentheses is matched to the vertical
extent of the expression.
ntheorem.sty :
However, in all sorts of mathematical
macros/latex/contrib/ntheorem
enterprises one may find oneself needing
theorem.sty : Distributed as part of a \middle command, to be used in expres-
macros/latex/required/tools sions like
141
 sizes).
\left\{ x \in \mathbb{N} \middle| This establishes
x \mbox{ (or re-establishes)
even} \right\}
the maths font sizes to be used when
to specify the set of even natural numbers.
the surrounding text font size is htfsi;
The e-TeX system defines just such a com-
(htsi being the size used for \textfont,
mand, but users of Knuth’s original need
hssi for \scriptfont and hsssi for
some support. Donald Arseneau’s braket
\scriptscriptfont).
package provides commands for set speci-
For example, you might want to use a
fications (as above) and for Dirac brackets
font with a smaller body height than Com-
(and bras and kets). The package uses the
puter Modern, but still prefer CM math to
e-TeX built-in command if it finds itself
any of the alternatives. In this case, you
running under e-TeX.
might use:
braket.sty :
macros/latex/contrib/braket \DeclareMathSizes{10}{9}{7}{5}

261 Cancelling terms in maths to get 9pt maths when the surrounding
expressions body text is (nominal) 10pt.
\DeclareMathSizes may only be
A technique used when explaining the be-
used in the preamble of the document: only
haviour of expressions or equations (of-
one association is available for each text
ten for pedagogical purposes). The cancel
font size for the whole document. The
package provides several variants of can-
default settings are specified in fontdef.
cellation marks (“\”, “/” and “X”), and a
dtx in the latex distribution, and are com-
means of cancelling ‘to’ a particular value.
piled into fontmath.ltx; the arguments
Documentation of cancel is in the pack-
to the command are just numbers (‘pt’ is
age file.
assumed), but some of them are written us-
cancel.sty : ing LaTeX abbreviations for standard font
macros/latex/contrib/cancel sizes. Beware simply copying (parts of)
262 Adjusting maths font sizes the LaTeX definitions — since they con-
tain those internal abbreviations, they need
In Plain TeX, when you introduce a new
to be treated as internal commands.
font size you must also declare what size
fonts are to be used in mathematics with fontdef.dtx :
it. This is done by declaring \textfont, macros/latex/base/fontdef.dtx
\scriptfont and \scriptscriptfont fontmath.ltx : macros/latex/
for the maths families you’re using; all unpacked/fontmath.ltx
such things are described in chapter 17 of
the TeXbook and in other books and tuto- 263 Ellipses
rials that discuss Plain TeX in sufficient Ellipses are commonly required, and La-
detail. TeX natively supplies a fair range (\dots,
In LaTeX, of course, all this stuff is \cdots, \vdots and \ddots). By using
automated: there is a scheme that, for the graphics package, one can change the
each (text) font size, determines what slope of the \ddots command, as in
maths font sizes are to be used. The
$ ... \reflectbox{$\ddots$} ... $
scheme first checks a set of “known”
text sizes, for each of which maths sizes While this works, it is not a recommended
are declared in advance. If the text size way of achieving the desired result (see
isn’t “known”, the script- and scriptscript- below). Moreover, LaTeX’s range is not
font sizes are calculated as fixed ratios adequate to everyone’s requirements, and
of the tex font size. (The values used at least three packages provide extensions
are \defaultscriptratio=0.7, and to the set.
\defaultscriptscriptratio=0.5.) The AMSLaTeX bundle provides a
The fixed-ratio formula is capable of range of “semantically-named” ellipses,
producing inconvenient results (particu- for use in different situations: \dotsb
larly if you are using fonts which LaTeX for use between pairs of binary operators,
believes are only available in a fixed set of \dotsc for use between pairs of commas,
sizes). You may also want to replace La- and so on.
TeX’s ideas altogether, for example by set- The yhmath package defines an
ting maths noticeably larger or smaller than \adots command, which is the analogue
its surrounding text. For this purpose, the of \ddots, sloping forwards rather than
LaTeX command \DeclareMathSizes backwards. The yhmath package comes
{htfsi}{htsi}{hssi}{hsssi} may be with a rather interesting font that extends
used (this is the same command that La- the standard cmex; details are in the docu-
TeX itself uses to define its own set of mentation.
142
 The mathdots package (besides fix- and for “\nolimits placement” in display
ing up the behaviour of (La)TeX \ddots maths, \nolimits:
and \vdots when the font size changes)
provides an “inverse diagonal” ellipsis \[\textstyle\sum_{n=1}^{m} ...\]
\iddots (doing the same job as yhmath’s
will serve. Either of these forms may have
\adots, but better).
effects other than on the operator you’re
Documentation of yhmath appears, pro- considering, but there are still those who
cessed, in the distribution (thus saving you prefer this formulation.
the bother of installing the package be-
Remember, if you’re declaring a spe-
fore being able to read the documentation).
cial operator of your own, the AMSLaTeX
Documentation of mathdots appears at the
functions (that you ought to be using) al-
end the package file itself.
low you to choose how limits are displayed,
amslatex : macros/latex/required/ at definition time.
amslatex (Note that the macro \int normally
graphics.sty : Part of the macros/ has \nolimits built in to its definition.
latex/required/graphics bundle There is an example in the TeXbook to
show how odd \int\limits looks when
mathdots.sty :
typeset.)
macros/generic/mathdots
yhmath: fonts/yhmath
265 Text inside maths
When we type maths in (La)TeX, the let-
264 Sub- and superscript positioning
ters from which we make up ordinary text
for operators
assume a special significance: they all be-
The commonest hand-written style for ex- come single-letter variable names. The let-
pressions is to place the limit expressions ters appear in italics, but it’s not the same
on operators such as \sum and \int phys- sort of italics that you see when you’re typ-
ically above and below the operator. In ing ordinary text: a run of maths letters
(La)TeX, we write these limit expressions (for example “here”) looks oddly “lumpy”
using sub- and superscripts applied to the when compared with the word written in
operator, but they don’t always appear in italic text. The difference is that the italic
the “handwritten” way in TeX’s output. text is kerned to make the letters fit well
The reason is, that when an expres- together, whereas the maths is set to look
sion appears in non-display maths, in as if you’re multiplying h by e by r by e.
running text (and is therefore in TeX The other way things are odd in TeX maths
\textstyle), placing the limits thus could typing is that spaces are ignored: at best
lead to ragged line spacing (and hence we can write single words in this oddly
difficult-to-read text). It is therefore com- lumpy font.
mon (in \textstyle) to place the limits So, if we’re going to have good-
as one would sub- and superscripts of vari- looking text in amongst maths we’re writ-
ables. ing, we have to take special precautions. If
This is not universally satisfactory, so you’re using LaTeX, the following should
the primitive \limits is provided: help.
The simplest is to use \mbox or
$\sum\limits_{n=1}^{m} ...$
\textrm:
which will place the limits right above and
$e = mc^2 \mbox{here we go again}$
below the symbol (and be blowed to the
typography. . . ). The problem is that, with either, the size of
Contrariwise, you may wish to change the text remains firmly at the surrounding
the arrangement of the limits when in text size, so that
\displaystyle. For this purpose, there’s
a corresponding \nolimits: $z = a_{\mbox{other end}}$

\[\sum\nolimits_{n=1}^{m} ...\] can look quite painfully wrong.

The other simple technique, \textrm,
which will place the limits as they would is no more promising:
be in \textstyle.
Alternatively, one can manipulate the $z = a_{\textrm{other end}}$
\textstyle/\displaystyle state of the
mathematics. To get “\limits placement” does the same as \mbox, by default.
in inline maths, (The maths-mode instance of your ro-
man font (\mathrm) gets the size right, but
$\displaystyle\sum_{n=1}^{m} ...$ since it’s intended for use in maths, its
143
spaces get ignored — use \mathrm for up- \begin{flalign}
right roman alphabetic variable names, but && a =& b && \\
not otherwise.) \text{or} && c =& b &&
You can correct these problems with \end{flalign}
size selectors in the text, as:
amsmath.sty : Distributed as part
$z = a_{\mbox{\scriptsize other end}}$
of AMSLaTeX macros/latex/
required/amslatex
which works if your surrounding text is at
default document size, but gives you the amstext.sty : Distributed as part
wrong size otherwise. of AMSLaTeX macros/latex/
The \mbox short cut is (just about) OK required/amslatex
for “occasional” use, but serious mathe- mathtools.sty : Distributed
matics calls for a technique that relieves as part of the mh bundle
the typist of the sort of thought required. macros/latex/contrib/mh
As usual, the AMSLaTeX system provides
what’s necessary — the \text command. 266 Re-using an equation
(The command is actually provided by the To repeat an existing equation, one wants
amstext package, but the “global” amsmath not only to have the same mathematics in
package loads it.) Thus anyone using AM- it, one also wants to re-use the original la-
SLaTeX proper has the command available, bel it had. The amsmath package comes to
so even this author can write: our help, here:
\usepackage{amsmath} \usepackage{amsmath}
... ...
$z = a_{\text{other end}}$ \begin{equation}
a=b
and the text will be at the right size, and in
\label{eq1}
the same font as surrounding text. (The
\end{equation}
amstext package also puts \textrm to
...
rights — but \text is easier to type than
Remember that
\textrm!)
\begin{equation}
AMSLaTeX also makes provision for
a=b
interpolated comments in the middle of
\tag{\ref{eq1}}
one of its multi-line display structures,
\end{equation}
through the \intertext command. For
example:
Here, the second instance of a = b will
\begin{align} be typeset with a copy, made by the \tag
command, of the label of the first instance.
A_1&=N_0(\lambda;\Omega’)-\phi(\lambda;\Omega’),\\
A_2&=\phi(\lambda;\Omega’)-\phi(\lambda;\Omega),\\
amsmath.sty : Distributed as part
\intertext{and} A_3&=\mathcal{N}(\lambda;\omega).
of AMSLaTeX macros/latex/
\end{align} required/amslatex

places the text “and” on a separate line 267 Line-breaking in in-line maths
before the last line of the display. If
TeX, by default, allows you to split a math-
the interjected text is short, or the equa-
ematical expression at the end of the line;
tions themselves are light-weight, you
it allows breaks at relational operators (like
may find that \intertext leaves too
“=”, “<”, etc.) and at binary operators (like
much space. Slightly more modest is
“+”, “-”, etc.). In the case of large expres-
the \shortintertext command from the
sions, this can sometimes be a life-saver.
mathtools package:
However, in the case of simple expres-
\begin{align} sions like a = b + c, a break can be really
a =& b disturbing to the reader, and one would like
\shortintertext{or} to avoid it.
c =& b Fortunately, these breaks are control-
\end{align} lable: there are “penalties” associated with
each type of operator: the penalty says how
To have the text on the same line as the undesirable a break at each point is. De-
second equation, one can use the flalign fault values are:
environment (from amsmath) with lots of
dummy equations (represented by the dou- \relpenalty = 500
ble & signs): \binoppenalty = 700
144
You make the break progressively less at- 269 Even subscript height
tractive by increasing these values. You Other things being equal, TeX will aim
can actually forbid all breaks, everywhere, to position subscripts and superscripts in
by: places that “look good”. Unfortunately, it
only does this for the sub- and superscripts
\relpenalty = 10000
of each atom at a time, so if you have
\binoppenalty = 10000
$ X^{1}_{2} X_{2} $
If you want just to prevent breaks in a sin-
gle expression, write: the second subscript will appear higher,
since the first has moved down to avoid the
{%
superscript; the effect can be noticeably
\relpenalty = 10000
distracting:
\binoppenalty = 10000
$a=b+c$ X21 X2
}
You can avoid the problem, for a single
and the original values will remain undis- instance, by
turbed outside the braces. This is tedious:
there is often value in an alternative ap- $ X^{1}_{2} X^{}_{2} $
proach, in which you say which parts of the
here, the dummy superscript has the requi-
expression may not break whatever hap-
site “pushing down” effect:
pens, and fortunately this is surprisingly
easy. Suppose we want to defer a break X21 X2
until after the equality, we could write:
While this technique does what is nec-
${a+b+c+d} = z+y+x+w$ essary, it is tedious and potentially error-
prone. So, for more than one or two equa-
The braces say “treat this subformula as
tions in a document, the LaTeX user is ad-
one atom” and (in TeX at least) atoms don’t
vised to use the subdepth package, which
get split: not a \binoppenalty change in
forces the lower position for all subscripts.
sight.
subdepth.sty :
268 Numbers for referenced macros/latex/contrib/subdepth
equations only
There are those who consider that papers
P.2 Lists
look untidy with numbers on every equa- 270 Fancy enumeration lists
tion; there is also a school of thought that The enumerate package allows you to con-
claims that there should be numbers every- trol the display of the enumeration counter.
where, in case some reader wants to make The package adds an optional parameter
reference an equation to which the author to the enumerate environment, which is
made no cross-reference. used to specify the layout of the labels.
If you hold to the “only cross- The layout parameter contains an enumer-
referenced” school of thought, you can ation type (‘1’ for arabic numerals, ‘a’ or
(using the \nonumber command on the ‘A’ for alphabetic enumeration, and ‘i’ or
relevant equations, or by using the AM- ‘I’ for Roman numerals), and things to act
SLaTeX unnumbered environments such as decoration of the enumeration. So, for
as equation*) mark those of your equa- example
tions to which you make no reference. In
a long or complex paper, this procedure \usepackage{enumerate}
could well become deeply tedious. ...
Fortunately, help is at hand: the \begin{enumerate}[(a)]
mh bundle’s mathtools package offers \item ... ...
a ‘showonlyrefs’ switch through its \end{enumerate}
\mathtoolsset command; when that’s in
operation, only those equations to which starts a list whose labels run (a), (b), (c),
you make reference will be numbered in . . . ; while
the final output. See the package’s docu-
\usepackage{enumerate}
mentation for details of how to make refer-
...
ences when the switch is in effect.
\begin{enumerate}[I/]
mathtools.sty : Distributed as part of \item ... ...
macros/latex/contrib/mh \end{enumerate}
145
starts a list whose labels run I/, II/, III/, . . . \tightlist (and *-ed versions of them);
The paralist package, whose primary
see section 8.6 of the memoir manual.
purpose is compaction of lists, provides There are packages that provide some
the same facilities for its enumerate-like
control of list spacing, but they seldom
environments. address the separation from surrounding
If you need non-stereotyped designs,
text (defined by \topsep). The expdlist
the enumitem package gives you most of
package, among its many controls of the
the flexibility you might want to design
appearance of description lists, offers
your own. The silly roman example above
a compaction parameter (see the docu-
could be achieved by: mentation); the mdwlist package offers a
\makecompactlist command for users’
\usepackage{enumitem}
own list definitions, and uses it to define
...
compact lists itemize*, enumerate* and
\begin{enumerate}[label=\Roman{*}/]
description*. In fact, you can write
\item ... ...
lists such as these commands define pretty
\end{enumerate}
straightforwardly — for example:
Note that the ‘*’ in the key value stands for \newenvironment{itemize*}%
the list counter at this level. You can also {\begin{itemize}%
manipulate the format of references to list \setlength{\itemsep}{0pt}%
item labels: \setlength{\parskip}{0pt}}%
\usepackage{enumitem} {\end{itemize}}
...
The paralist package provides several ap-
\begin{enumerate}[label=\Roman{*}/, ref=(\roman{*})]
proaches to list compaction:
\item ... ...
\end{enumerate} • its asparaenum environment formats
each item as if it were a paragraph
to make references to the list items format introduced by the enumeration label
appear as (i), (ii), (iii), etc. (which saves space if the item texts
The memoir class includes functions are long);
that match those in the enumerate package, • its compactenum environment is the
and has similar functionality for itemize same sort of compact list as is pro-
lists. vided in expdlist and mdwlist; and
enumerate.sty : Distributed as part of • its inparaenum environment pro-
macros/latex/required/tools duces a list “in the paragraph”, i.e.,
enumitem.sty : with no line break between items,
macros/latex/contrib/enumitem which is a great space-saver if the list
item texts are short.
memoir.cls:
macros/latex/contrib/memoir The package will manipulate its
paralist.sty : enumerate environment labels just like
macros/latex/contrib/paralist the enumerate package does.
Paralist also provides itemize
271 How to adjust list spacing equivalents (asparaitem, etc.), and
Lamport’s book lists various parameters description equivalents (asparadesc,
for the layout of list (things like \topsep, etc.).
\itemsep and \parsep), but fails to men- The multenum package offers a more
tion that they’re set automatically within regular form of paralist’s inparaenum;
the standard (LaTeX-defined) lists. This you define a notional grid on which list
happens because each list executes a com- entries are to appear, and list items will
mand \@listhdepthi (the depth appear- always appear at positions on that grid.
ing as a lower-case roman numeral); what’s The effect is somewhat like that of the
more, the top-level \@listi is usually re- ‘tab’ keys on traditional typewriters; the
set when the font size is changed. As a package was designed for example sheets,
result, it’s rather tricky for the user to con- or lists of answers in the appendices of a
trol list spacing. Of course, the real an- book.
swer is to use a document class designed The expdlist, mdwlist and paralist
with more modest list spacing, but we all packages all offer other facilities for list
know such things are hard to come by. configuration: you should probably not try
The memoir class doesn’t provide more the “do-it-yourself” approaches outlined
compact lists, but offers the user control below if you need one of the packages for
over the list spacing using \firmlist and some other list configuration purpose.
146
 For ultimate flexibility (including ma-
while in the case of description lists, the
nipulation of \topsep), the enumitem
item labels are under the user’s control so
package permits adjustment of list param-
there’s no automatic issue of continuity.
eters using a “key=hvaluei” format. ForFor enumerate lists, the labels are
example, one might write generated automatically, and are context-
sensitive, so the context (in this case, the
\usepackage{enumitem} state of the enumeration counter) needs to
... be preserved.
\begin{enumerate}[topsep=0pt, partopsep=0pt]
The belt-and-braces approach is to re-
\item ... member the state of the enumeration in
\item ... your own counter variable, and then restore
\end{enumerate} it when restarting enumerate:
to suppress all spacing above and below \newcounter{saveenum}
your list, or ...
\usepackage{enumitem} \begin{enumerate}
... ...
\setcounter{saveenum}{\value{enumi}}
\begin{enumerate}[itemsep=2pt,parsep=2pt]
\item ... \end{enumerate}
\item ... <Commentary text>
\end{enumerate} \begin{enumerate}
\setcounter{enumi}{\value{saveenum}}
to set spacing between items and between ...
paragraphs within items. Enumitem also \end{enumerate}
permits manipulation of the label format
in a more “basic” (and therefore more flex- This is reasonable, in small doses. . .
ible) manner than the enumerate package Problems (apart from sheer verbosity)
does. are getting the level right (“should I use
The ultimate in compaction (of every counter enumi, enumii, . . . ”) and remem-
sort) is offered by the savetrees package; bering not to nest the interruptions (i.e., not
compaction of lists is included. The pack- to have a separate list, that is itself inter-
age’s prime purpose is to save space at rupted) in the “commentary text”).
every touch and turn: don’t use it if you’re The mdwlist package defines com-
under any design constraint whatever! mands \suspend and \resume that sim-
plify the process:
enumerate.sty : Distributed as part of
macros/latex/required/tools \begin{enumerate}
enumitem.sty : ...
macros/latex/contrib/enumitem \suspend{enumerate}
<Commentary text>
expdlist.sty :
\resume{enumerate}
macros/latex/contrib/expdlist
...
memoir.cls: \end{enumerate}
macros/latex/contrib/memoir
The package allows an optional name (as
memoir manual: macros/latex/
in \suspend[id]{enumerate}) to allow
contrib/memoir/memman.pdf
you to identify a particular suspension, and
mdwlist.sty : Distributed as part of hence provide a handle for manipulating
macros/latex/contrib/mdwtools nested suspensions.
multenum.sty : If you’re suspending a fancy-
macros/latex/contrib/multenum enumeration list, you need to re-supply
the optional “item label layout” parame-
paralist.sty :
ters required by the enumerate package
macros/latex/contrib/paralist
when resuming the list, whether by the belt-
savetrees.sty : macros/latex/ and-braces approach, or by the mdwlist
contrib/savetrees \resume{enumerate} technique. The
272 Interrupting enumerated lists task is a little tedious in the mdwlist case,
since the optional argument has to be
It’s often convenient to have commentary encapsulated, whole, inside an optional
text, ‘outside’ the list, between successive argument to \resume, which requires use
entries of a list. In the case of itemize of extra braces:
lists this is no problem, since there’s never
anything to distinguish successive items, \begin{enumerate}[\textbf{Item} i]
147
 ... if it were a second paragraph to “outer item
\suspend{enumerate} 2”, which is hardly satisfactory.
<comment> enumerate.sty : Distributed as part of
\resume{enumerate}[{[\textbf{Item} macros/latex/required/tools
i]}]
...
enumitem.sty :
\end{enumerate}
macros/latex/contrib/enumitem
The enumitem package, in its most recent expdlist.sty :
release, will also allow you to resume lists: macros/latex/contrib/expdlist

\begin{enumerate} mdwlist.sty : Distributed as part of

... macros/latex/contrib/mdwtools
\end{enumerate}
P.3 Tables, figures and
<comment>
\begin{enumerate}[resume]
diagrams
... 273 The design of tables
\end{enumerate} In recent years, several authors have ar-
gued that the examples, set out by Lamport
which feels just as “natural” as the
in his LaTeX manual, have cramped au-
mdwtools facility, and has the advantage
thors’ style and have led to extremely poor
of playing well with the other excellent
table design. It is in fact difficult even to
facilities of enumitem.
work out what many of the examples in
Expdlist has a neat way of providing
Lamport’s book “mean”.
for comments, with its \listpart com-
The criticism focuses on the excessive
mand. The command’s argument becomes
use of rules (both horizontal and vertical)
a comment between items of the list:
and on the poor vertical spacing that Lam-
\begin{enumerate} port’s macros offer.
\item item 1 The problem of vertical spacing is
\item item 2 plain for all to see, and is addressed in
\listpart{interpolated comment} several packages — see “spacing of lines
\item item 3 in tables”.
\end{enumerate} The argument about rules is presented
in the excellent essay that prefaces the doc-
This, you will realise, means it doesn’t umentation of Simon Fear’s booktabs pack-
even have to think about suspending or age, which (of course) implements Fear’s
resuming the list, and of course it works scheme for ‘comfortable’ rules. (The same
equally well in any of the list environments rule commands are implemented in the
(thought it’s not actually necessary for any memoir class.)
but enumerate). Lamport’s LaTeX was also inflexibly
Enumitem also allows multi-level sus- wrong in “insisting” that captions should
pension and resumption of lists: come at the bottom of a table. Since a table
\begin{enumerate}
may extend over several pages, traditional
\item outer item 1
typography places the caption at the top
\end{enumerate}
of a table float. The \caption command
<comment>
will get its position wrong (by 10pt) if you
\begin{enumerate}[resume]
simply write:
\item outer item 2 \begin{table}
% nested enumerate \caption{Example table}
\begin{enumerate} \begin{tabular}{...}
\item inner item 1 ...
\end{enumerate} \end{tabular}
<nested comment> \end{table}
% resume nested enumerate The topcapt package solves this problem:
\begin{enumerate}[resume]
\item inner item 2 \usepackage{topcapt}
\end{enumerate} ...
\item outer item 3 \begin{table}
% end outer enumerate \topcaption{Example table}
\end{enumerate} \begin{tabular}{...}
...
However, the ‘nested comment’ interpo- \end{tabular}
lated in the nested enumeration appears as \end{table}
148
The KOMA-script classes provide a sim- \begin{tabular*}{\columnwidth}{@{\extracolsep{\fill}}ll
ilar command \captionabove; they also
have a class option tablecaptionabove The \extracolsep applies to all inter-
which arranges that \caption means column gaps to its right as well; if
\captionabove, in table environments. you don’t want all gaps stretched, add
The caption package may be loaded with \extracolsep{0pt} to cancel the origi-
an option that has the same effect: nal.
The tabularx package defines an extra
\usepackage[tableposition=top]{caption} clpr column specification, X; X columns
or the effect may be established after the behave as p columns which expand to fill
package has been loaded: the space available. If there’s more than
one X column in a table, the spare space is
\usepackage{caption} distributed between them.
\captionsetup[table]{position=above} The tabulary package (by the same au-
thor) provides a way of “balancing” the
(Note that the two “position” options are
space taken by the columns of a table. The
different: actually, “above” and “top” in
package defines column specifications C,
these contexts mean the same thing.)
L, R and J, giving, respectively, centred,
Doing the job yourself is pretty
left, right and fully-justified versions of
easy: topcapt switches the val-
space-sharing columns. The package ex-
ues of the LaTeX2e parameters
amines how long each column would be
\abovecaptionskip (default value 10pt)
“naturally” (i.e., on a piece of paper of
and \belowcaptionskip (default value
unlimited width), and allocates space to
0pt), so:
each column accordingly. There are “san-
\begin{table} ity checks” so that really large entries don’t
\setlength{\abovecaptionskip}{0pt} cause everything else to collapse into noth-
\setlength{\belowcaptionskip}{10pt} ingness (there’s a “maximum width” that
\caption{Example table} any column can exert), and so that tiny
\begin{tabular}{...} entries can’t get smaller than a specified
... minimum. Of course, all this work means
\end{tabular} that the package has to typeset each row
\end{table} several times, so things that leave “side-
effects” (for example, a counter used to
does the job (if the length values are right;
produce a row-number somewhere) are in-
the package and classes are more careful!).
evitably unreliable, and should not even be
booktabs.sty : tried.
macros/latex/contrib/booktabs The ltxtable package combines the fea-
caption.sty : tures of the longtable and tabularx pack-
macros/latex/contrib/caption ages. It’s important to read the documen-
tation, since usage is distinctly odd; the
KOMA script bundle:
distribution contains no more than a file
macros/latex/contrib/koma-
ltxtable.tex, which you should process
script
using LaTeX. Processing will give you a
memoir.cls: .sty file as well as the .dvi or .pdf out-
macros/latex/contrib/memoir put containing the documentation.
topcapt.sty : macros/latex/ ltxtable.sty : Distributed as part of
contrib/misc/topcapt.sty macros/latex/contrib/carlisle
274 Fixed-width tables tabularx.sty : Distributed as part of
There are two basic techniques for making macros/latex/required/tools
fixed-width tables in LaTeX: you can make tabulary.sty :
the gaps between the columns stretch, or macros/latex/contrib/tabulary
you can stretch particular cells in the table.
Basic LaTeX can make the gaps 275 Variable-width columns in tables
stretch: the tabular* environment takes This is a slightly different take on the prob-
an extra argument (before the clpr lay- lem addressed in “fixed-width tables” —
out one) which takes a length specifica- here we have a column whose size we can’t
tion: you can say things like “15cm” or absolutely predict when we design the doc-
“\columnwidth” here. You must also have ument.
an \extracolsep command in the clpr While the basic techniques (the
layout argument, inside an @{} directive. tabularx, tabulary and ltxtable packages)
So, for example, one might have are the same for this problem as for the
149
fixed-width table problem, there’s one ex- Traditional (moving metal type) typog-
tra tool that we can call to our aid, which raphers would adjust the spacing between
may be preferable in some situations. lines of a table by use of a “strut” (a metal
Suppose we have data in one column spacer). A TeX user can do exactly the
which we read from an external source, and same thing: most macro packages define
the source itself isn’t entirely predictable. a \strut command, that defines a space
The data in the column may end up pretty appropriate to the current size of the text;
narrow in every row of the table, or it may placing a \strut command at the end of
be wide enough that the table would run a troublesome row is the simplest solution
over the edge of the page; however, we to the problem — if it works. Other solu-
don’t want to make the column as wide as tions below are LaTeX-specific, but some
possible “just in case”, by defining a fixed may be simply translated to Plain TeX com-
size for the table. We would like the col- mands.
umn to be as small as possible, but have the If your table exhibits a systematic prob-
possibility to spread to a maximum width lem (i.e., every row is wrong by the same
and (if even that width is exceeded) turn amount) use \extrarowheight, which is
into a p-style column. defined by the array package:
The varwidth package, discussed in \usepackage{array}% in the preamble
“automatic sizing of minipages”, provides ...
a solution. If you load it together with the \setlength{\extrarowheight}{length}
LaTeX “required” array package, i.e.: \begin{tabular}{....}
\usepackage{array} To correct a single row whose malad-
\usepackage{varwidth} justment isn’t corrected by a \strut com-
varwidth defines a new column-type “V”, mand, you can define your own, using
which you can use as follows: \rule{0pt}{length} — which is a near
approximation to the command that goes
\begin{tabular}{l V{3.5cm} r} inside a \strut. The bigstrut package de-
foo & blah & bar \\ fines a strut command that you can use for
foo & blah blah & bar \\ this purpose: \bigstrut on its own opens
\end{tabular} up both above and below the current line;
\bigstrut[t] opens up above the line,
when the second column ends up less than
3.5cm wide; or you can use it as follows: \bigstrut[b] opens up below the line.
General solutions are available, how-
\begin{tabular}{l V{3.5cm} r} ever. The tabls package automatically gen-
foo & blah & bar \\ erates an appropriately-sized strut at the
foo & blah blah & bar \\ end of each row. Its disadvantages are that
foo & blah blah blah blah blahit’sblahreally rather slow in operation (since it
& bar \\ gets in the way of everything within tables)
\end{tabular} and its (lack of) compatibility with other
packages.
where the second column will end up no-
The makecell package provides a com-
ticeably wider, and will wrap to a second
mand \gape that may be used to apply
line in the third row.
strut expansion for a single cell of a table:
array.sty : Distributed as part of
\begin{tabular}{lll}
macros/latex/required/tools
... & \gape{cell contents} & ... \\
varwidth.sty : ...
macros/latex/contrib/varwidth \end{tabular}
276 Spacing lines in tables The package’s similar \Gape command
(La)TeX mechanisms for maintaining the provides the same function, but with op-
space between lines (the “leading”) rely on tional arguments that allow you to adjust
TeX’s paragraph builder, which compares the top and bottom adjustment.
the shape of consecutive lines and adjusts To adjust every cell in whole tables,
the space between them. the \setcellgapes{hvaluei} sets the
These mechanisms can’t work in ex- adjustment value (an optional argument
actly the same way when (La)TeX is build- of “t” or “b” restricts adjustment to the
ing a table, because the paragraph builder top or bottom of each cell, respectively).
doesn’t get to see the lines themselves. Having issued \setcellgapes, the com-
As a result, tables sometimes typeset with mand \makegapedcells switches cell
lines uncomfortably close together (or oc- expansion on, and \nomakegapedcells
casionally ridiculously far apart). switches it off again.
150
 The cellspace package does a (possibly whole table at the time it’s doing “final”
inferior) job by defining a new table/array setting, the table is set “uniformly” over
column type “S”, which you apply to each its entire length, with columns matching
column specification. So, for example, on consecutive pages. longtable has a rep-
utation for failing to interwork with other
\begin{tabular}{l l l packages, but it does work with colortbl,
p3cm} and its author has provided the ltxtable
would become package to provide (most of) the facili-
ties of tabularx (see fixed-width tables)
\begin{tabular}{Sl Sl Sl for long tables: beware of its rather cu-
Sp3cm} rious usage constraints — each long table
should be in a file of its own, and included
and so on. This technique shows promise by \LTXtable{width}{file}. Since
of not interfering so much with other pack- longtable’s multiple-page tables can’t pos-
ages, but this author has heard of no reports sibly live inside floats, the package pro-
from the field. vides for captions within the longtable
The booktabs package comes with a environment itself.
thought-provoking essay about how ta- A seeming alternative to ltxtable is
bles should be designed. Since table row- ltablex; but it is outdated and not fully func-
spacing problems most often appear in col- tional. Its worst problem is its strictly lim-
lisions with rules, the author’s thesis, that ited memory capacity (longtable is not so
LaTeX users tend too often to rule their limited, at the cost of much complication
tables, is interesting. The package pro- in its code); ltablex can only deal with rel-
vides rule commands to support the au- atively small tables, it doesn’t seem likely
thor’s scheme, but deals with inter-row that support is available; but its user inter-
spacing too. The most recent release of face is much simpler than ltxtable, so if
booktabs sports compatibility with pack- its restrictions aren’t a problem for you, it
ages such as longtable. may be worth a try.
array.sty : Distributed as part of The supertabular package starts and
macros/latex/required/tools stops a tabular environment for each
bigstrut.sty : page of the table. As a result, each ‘page
macros/latex/contrib/multirow worth’ of the table is compiled indepen-
dently, and the widths of corresponding
booktabs.sty :
columns may differ on successive pages.
macros/latex/contrib/booktabs
However, if the correspondence doesn’t
cellspace.sty : macros/latex/ matter, or if your columns are fixed-width,
contrib/cellspace supertabular has the great advantage of
makecell.sty : doing its job in a single run.
macros/latex/contrib/makecell Both longtable and supertabular allow
definition of head- and footlines for the ta-
tabls.sty :
ble; longtable allows distinction of the first
macros/latex/contrib/tabls
and last head and foot.
277 Tables longer than a single page The xtab package fixes some infelici-
Tables are, by default, set entirely in boxes ties of supertabular, and also provides a
of their own: as a result, they won’t split “last head” facility (though this, of course,
over a page boundary. Sadly, the world destroys supertabular’s advantage of oper-
keeps turning up tables longer than a sin- ating in a single run).
gle page that we need to typeset. The stabular package provides a
For simple tables (whose shape is simple-to-use “extension to tabular” that
highly regular), the simplest solution may allows it to typeset tables that run over the
well be to use the tabbing environment, end of a page; it also has usability exten-
which is slightly tedious to set up, but sions, but doesn’t have the head- and foot-
which doesn’t force the whole alignment line capabilities of the major packages.
onto a single page. Documentation of ltablex is to be
The longtable package builds the found in the package file.
whole table (in chunks), in a first pass, longtable.sty : Distributed as part of
and then uses information it has written macros/latex/required/tools
to the .aux file during later passes to get
ltablex.sty : macros/latex/
the setting “right” (the package ordinarily
contrib/ltablex/ltablex.sty
manages to set tables in just two passes).
Since the package has overview of the ltxtable.sty : Generate by running
151
 macros/latex/contrib/ ... & \PBS\centering blah ... \\
carlisle/ltxtable.tex
or in the preamble as:
stabular.sty : Distributed as part of
\begin{tabular}{...>{\PBS\centering}p{5cm}}
macros/latex/contrib/sttools
supertabular.sty : macros/latex/ array.sty : Distributed as part of
contrib/supertabular macros/latex/required/tools

xtab.sty :
279 The thickness of rules in LaTeX
macros/latex/contrib/xtab
tables
278 How to alter the alignment of The rules in a LaTeX table are by default
tabular cells 0.4pt thick; this is in fact a default built
One often needs to alter the alignment of a in at the lowest level, and applies to all
tabular p (‘paragraph’) cell, but problems rules (including those separating blocks of
at the end of a table row are common. With running text).
a p cell that looks like: Sometimes, however, we look at a table
and find we want the rules to stand out —
... & \centering blah ... \\ perhaps to separate the text from the rest of
one is liable to encounter errors that com- the body text, or to make the sections of the
plain about a “misplaced \noalign” or table stand out from one another. However,
“extra alignment tab”, or the like. The a quick review of any LaTeX manual will
problem is that the command \\ means reveal no technique for making any one
different things in different circumstances: rule stand out, and a little experimentation
the tabular environment switches the shows that it is indeed pretty difficult to
meaning to a value for use in the ta- prevent a change “bleeding” out to affect
ble, and \centering, \raggedright and other rules in the same table.
\raggedleft all change the meaning to If you look at what we have to say
something incompatible. Note that the on the design of tables, elsewhere among
problem only arises in the last cell of a row: these FAQs, and you may sense that the
since each cell is set into a box, its settings design of LaTeX simply skipped the issues
are lost at the & (or \\) that terminates it. surrounding table design: that’s presum-
In the old days, the actual value of \\ ably why there’s no facilities to help you.
that the tabular environment uses was Specifically, the length \arrayrulewidth
only available as an internal command. affects the thickness of the rules (both hor-
Nowadays, the value is a public command, izontal and vertical) within both tabular
and you can in principle use it explicitly: and array environments. If you change
from the default (see above) only as far as
... & \centering blah ... \tabularnewline
\setlength{\arrayrulewidth}{1pt}
(but that’s a rather verbose way of doing
the change is remarkably striking. How-
things).
ever, really quite subtle user level program-
The array package provides a com-
ming proves incapable of changing just
mand \arraybackslash which restores
one rule: it’s necessary to delve into the
\\ to its correct (within table) meaning;
(rather tricky) code of \hline and \cline
the command may be used in array’s “field
themselves.
format” preamble specifications:
Fortunately, this job has already
been done for the community: the
\begin{tabular}{... >{\centering\arraybackslash}p{50mm}}
... booktabs package defines three different
classes of rule (\toprule, \midrule and
The \tabularnewline and \bottomrule), and the package documen-
\arraybackslash commands are (some- tation offers hints on how to use them. You
what) modern additions to LaTeX and are strongly advised to read the documen-
the array package, respectively. In the tation pretty carefully.
unlikely event that neither is available, The memoir class includes the
the user may try the (old) solution which booktabs package, and repeats the doc-
preserves the meaning of \\: umentation in its compendious manual.
\newcommand\PBS[1]{\let\temp=\\%
Note that none of the above mentions
#1%
the issue of the weight of vertical rules
\let\\=\temp
(except in passing). For the reasons, see
}
the documentation of the booktabs pack-
age (again); vertical rules in tables are in
which one uses within a table as: any case even more trickily coded than are
152
horizontal rules, and if their lack of con- with shadow boxes, various MS-DOS
figurability makes them still less attractive, formats, etc.). The command for in-
so much the better for the design of your serting a picture at the start of a para-
document. graph is:
booktabs.sty : \parpic(width,height)(x-off,y-off)[Options][Position
macros/latex/contrib/booktabs Paragraph text
memoir.cls: All parameters except the Picture are
macros/latex/contrib/memoir optional. The picture can be posi-
280 Flowing text around figures tioned left or right, boxed with a rect-
angle, oval, shadowbox, dashed box,
There are several LaTeX packages that pur-
and a caption can be given which will
port to do this, but they all have their limita-
be included in the list of figures.
tions because the TeX machine isn’t really
Unfortunately (for those of us whose
designed to solve this sort of problem. Piet
understanding of German is not good),
van Oostrum has conducted a survey of the
the documentation is in German. Piet
available packages; he recommends:
van Oostrum has written a summary
floatflt floatflt is an improved version in English.
(for LaTeX2e) of floatfig.sty, and
its syntax is: All of the above deal insertions at one or
other margin; they are able to take advan-
\begin{floatingfigure}[options]{width of figure}
tage of the TeX \parshape primitive that
figure contents allows you to adjust the margins of the text
\end{floatingfigure} of a paragraph, by line (Knuth provides
There is a (more or less similar) an example of such use, with text typeset
floatingtable environment. in a circle, half-overlapping the margin,
The tables or figures can be set left or in chapter 14 of the TeXbook). To place
right, or alternating on even/odd pages insertions in the middle of a paragraph re-
in a double-sided document. quires effort of an entirely different sort;
The package works with the the cutwin package does this for you. It re-
multicol package, but doesn’t work quires a set of “part line widths” (two per
well in the neighbourhood of list en- line), and typesets the “cutout” section of
vironments (unless you change your the paragraph line by line. The examples in
LaTeX document). the package documentation look enticing.
wrapfig wrapfig has syntax: Plain TeX users only have one option:
\begin{wrapfigure}[height of figure (which
figflow doesn’t work in LaTeX).
in lines]{l,r,...}[overhang]{width}
figure, caption, etc. Figflow only offers flowed figures at the
\end{wrapfigure} start of the paragraph, but it seems per-
fectly functional. Syntax is
The syntax of the wraptable environ-
ment is similar. \figflow{hwidthi}{hheighti}
The height may be omitted, in which {hfigurei}
case it will be calculated from the size
of the figure; the package will use (the user is responsible for having the di-
the greater of the specified and the ac- mensions correct, and for ensuring the fig-
tual width. The {l,r,etc.} parame- ure fits on the page).
ter may also be specified as i(nside)
cutwin.sty :
or o(utside) for two-sided documents,
macros/latex/contrib/cutwin
and uppercase may be used to indicate
that the picture should float. The over- figflow.tex :
hang allows the figure to be moved macros/plain/contrib/figflow
into the margin. The figure or table
floatflt.sty :
will entered into the list of figures or
macros/latex/contrib/floatflt
tables if you use the \caption com-
mand. picins.sty : macros/latex209/
The environments do not work within contrib/picins
list environments that end before the picins documentation summary:
figure or table has finished, but can be macros/latex209/contrib/
used in a parbox or minipage, and in picins/picins.txt
twocolumn format.
picins Picins is part of a large bundle wrapfig.sty :
that allows inclusion of pictures (e.g., macros/latex/contrib/wrapfig
153
281 Diagonal separation in corner \usepackage{array}
cells of tables \newcolumntype{$}{>{\global\let\currentrowstyle\relax}}
You want to label both the top or bot- \newcolumntype{^}{>{\currentrowstyle}}
tom row and the left- or rightmost column, \newcommand{\rowstyle}[1]{\gdef\currentrowstyle{#1}%
somewhere at the corner of the table where #1\ignorespaces
the row and column meet. A simple way to }
achieve the result is to construct the table
Now, we put ‘$’ before the first column
with an arrangement of rules (and possibly
specifier; and we put ‘^’ before the mod-
\multicolumn entries), to look like:
ifiers of subsequent ones. We then use
----------------- \rowstyle at the start of each row we
x y want to modify:
--------------
\begin{tabular}{|$l|^l|^l|} \hline
1 2 3 4 5
\rowstyle{\bfseries}
-----------------
Heading & Big and & Bold \\ \hline
1
Meek & mild & entry \\
2
Meek & mild & entry \\
3
\rowstyle{\itshape}
4
Strange & and & italic \\
5
Meek & mild & entry \\ \hline
-----------------
\end{tabular}
However, this doesn’t satisfy everyone:
many want the labelling in a single cell The array package works with several
at the top left of the table. It sounds a other tabular-like environments from
simple enough requirement, yet it calls for other packages (for example longtable),
some slightly tricky LaTeX coding. The but unfortunately this trick won’t always
diagbox package does this job for you: it work.
defines a command \diagbox whose two array.sty : Distributed as part of
arguments provide the texts to be used; an macros/latex/required/tools
optional argument may be used for fine
tuning of the result. It draws a picture with 283 Merging cells in a column of a
the two labels on either side of a slanting table
line; the command (and hence the picture) It’s easy to come up with a table design
may be placed in the corner cell, where the that requires a cell that spans several rows.
labelled row and column meet. An example is something where the left-
The diagbox package supersedes most column labels the rest of the table;
slashbox; the older package’s commands this can be done (in simple cases) by using
\slashbox and \backslashbox are pro- diagonal separation in corner cells, but that
vided in a compatible way in the newer technique rather strictly limits what can be
package, to ease transition. used as the content of the cell.
diagbox.sty : The multirow package enables you to
macros/latex/contrib/diagbox construct such multi-row cells, in a very
simple manner. For the simplest possible
slashbox.sty : use, one might write:
macros/latex/contrib/slashbox
\begin{tabular}{|c|c|}
282 How to change a whole row of a
\hline
table
\multirow{4}{*}{Common g text}
Each cell of a table is set in a box, so that & Column g2a\\
a change of font style (or whatever) only & Column g2b \\
lasts to the end of the cell. If one has a & Column g2c \\
many-celled table, or a long one which & Column g2d \\
needs lots of rows emphasising, putting a \hline
font style change command in every cell \end{tabular}
will be impossibly tedious.
With the array package, you can define and multirow will position “Common g
column modifiers which will change the text” at the vertical centre of the space de-
font style for a whole column. However, fined by the other rows. Note that the rows
with a bit of subtlety, one can make such that don’t contain the “multi-row” speci-
modifiers affect rows rather than columns. fication must have empty cells where the
So, we set things up by: multi-row is going to appear.
154
 The “*” may be replaced by a column multirow.sty :
width specification. In this case, the argu- macros/latex/contrib/multirow
ment may contain forced line-breaks:
P.4 Floating tables, figures, etc.
\begin{tabular}{|c|c|}
284 Floats on their own on float pages
\hline
It’s sometimes necessary to force a float
\multirow{4}{25mm}{Common\\g text}
& Column g2a\\ to live on a page by itself. (It’s sometimes
& Column g2b \\ even necessary for every float to live on
& Column g2c \\ a page by itself.) When the float fails to
& Column g2d \\ ‘set’, and waits for the end of a chapter or
\hline of the document, the natural thing to do is
\end{tabular} to declare the float as

A similar effect (with the possibility of a \begin{figure}[p!]

little more sophistication) may be achieved
but the overriding ! modifier has no effect
by putting a smaller table that lines up the
text into a *-declared \multirow. on float page floats; so you have to make
The \multirow command may alsothe float satisfy the parameters. Moving
tables and figures offers some suggestions,
used to write labels vertically down one
but doesn’t solve the one-float-per-page
or other side of a table (with the help of
question.
the graphics or graphicx package, which
provide the \rotatebox command): The ‘obvious’ solution, using the
counter totalnumber (“total number
\begin{tabular}{|l|l|} of floats per page”) doesn’t work:
\hline totalnumber only applies to floats on
‘text’
\multirow{4}{*}{\rotatebox{90}{hi pages (pages containing text as well
there}}
& Column g2a\\ as one or more float). So, to allow
& Column g2b \\ any size float to take a whole page, set
& Column g2c \\ \floatpagefraction really small, and to
& Column g2d \\ ensure that no more than one float occupies
\hline a page, make the separation between floats
\end{tabular} really big:

(which gives text going upwards; use angle \renewcommand\floatpagefraction{.001}

-90 for text going downwards, of course). \makeatletter
To make a \multicolumn multi-row \setlength\@fpsep{\textheight}
“cell” in a table, you have to enclose a \makeatother
\multirow inside a \multicolumn — the
other way around does not work, so: 285 Centring a very wide figure or
table
\begin{tabular}{|c|c|c|}\hline The normal means of centring a figure or
\multicolumn{2}{|c|}{\multirow{2}{ *}{combined
table cells}}
object is to include \centering at
&top right\\ \cline{3-3} the top of the float. This doesn’t help if the
\multicolumn{2}{|c|}{} object is wider than \textwidth — the
&middle right\\ \hline object starts at the left margin and juts
bottom left out into the right margin (which is actu-
&bottom center ally doubly unsatisfactory, since as well as
&bottom right\\ \hline looking bad, the float won’t be placed until
\end{tabular} the next \clearpage or the like.)
Multirow is set up to interact with the You can avoid the problem by rescal-
bigstrut package (which is also discussed ing the figure or table to fit, but this is often
in the answer to spacing lines in tables). not satisfactory, for several reasons.
You use an optional argument to the Otherwise, if the object is wider than
\multirow command to say how many
the printable area of the page, you’ve no
of the rows in the multi-row have been choice other than to rotate it. If, however,
opened up with \bigstrut. the object is just wider than the text block,
The documentation of both multirow you can make it pretend to be the right size
and bigstrut is to be found, as comments, by:
in the package files themselves. \begin{figure}
bigstrut.sty : \noindent
macros/latex/contrib/multirow \makebox[\textwidth]{\includegraphics{my-wide-figure}
155
 \caption{This figure juts out into It’s both
possible to have single-column fig-
margins}
\end{figure} ures and tables with captions, using the
‘[H]’ placement option introduced by the
Note the \noindent: the \makebox starts float package but you might have to fid-
a paragraph, and you really don’t want that dle with the placement because they won’t
indented by \parindent. ‘float’, and exhibit other strange behaviours
286 Placing two-column floats at (such as silently running off the end of the
bottom of page column at the end of the multicols envi-
You specified placement ‘[htbp]’ for your ronment).
full-width figure or table, but they always float.sty :
get placed at the top of the page. . . Well, macros/latex/contrib/float
it is what the documentation says: LaTeX, multicol.sty : Distributed as part of
unadorned, only allows full-width floats at macros/latex/required/tools
the top of a page, or occupying (part of) a
float page. 288 Facing floats on 2-page spread
The stfloats package ameliorates the If a pair of floats need to be forced to form
situation somewhat, and makes LaTeX a 2-page spread (in a book, or whatever),
honour ‘[b]’ placement as well; the the first must lie on the left side of the
dblfloatfix package combines a tidied ver- spread, on an even-numbered page. The
sion of the changes made in stfloats with dpfloat package provides for this: the con-
the float ordering corrections defined in struction to use is:
fixltx2e. \begin{figure}[p]
A particular problem with stfloats and \begin{leftfullpage}
dblfloatfix is that the float will appear, at <left side figure>
its earliest, on the page after it is specified. \end{leftfullpage}
This has two undesirable side-effects: first, \end{figure}
there may be no bottom float on the first \begin{figure}[p]
page of a document, and second, float num- \begin{fullpage}
bers may become “entangled” (particularly <right side figure>
if you’re using dblfloatfix that ensures that \end{fullpage}
the early-specified bottom float is set be- \end{figure}
fore any single column floats).
(The FAQ team doesn’t know of any The construction has no effect on
package that will make LaTeX honour ‘[h]’ documents with class option oneside
placement of double-column floats, but the (twoside is the default for book class).
midfloat package can be pressed into ser- A special case of this requirement
vice to provide something approximating places the caption for a float on the next
the effect it would have.) page. (This is useful if you have a float that
“only just” fits the page.) You can (with
dblfloatfix.sty : macros/latex/ a certain amount of twiddling) make this
contrib/dblfloatfix work with dpfloat, but the fltpage package
midfloat.sty : Distributed as part of is specially designed for the job:
macros/latex/contrib/sttools
\documentclass[twoside]{article}
stfloats.sty : Distributed as part of \usepackage[leftFloats]{fltpage}
macros/latex/contrib/sttools \begin{document}
...
287 Floats in multicolumn setting
\begin{FPfigure}
If you use \includegraphics{my-huge-figure}
\begin{figure} \caption{Whew! That was a big one!}
... \end{FPfigure}
\end{figure} ...
\end{document}
in a multicols environment, the figure
That example should produce a caption
won’t appear. If instead you use
Figure hni (facing page): Whew!
\begin{figure*} ...
...
\end{figure*}
(Note, however, that the package is an old
one, and declares itself to be a beta release,
the figure will stretch right across the page and contains no valid licence statement so
(just the same as a figure* in standard that it is not in TeX Live. It seems to work,
LaTeX’s twocolumn option). but. . . )
156
 A alternative route is the “continued” than one float on the page, the gap between
mechanism of the caption package. The them will expand to twice the space at top
\ContinuedFloat macro makes a small and bottom.
tweak to the next \caption command, so Those who understand this stuff will be
that the command makes no increment to able to play elaborate games, but the com-
the caption number. This does not (of monest requirement, that the floats start at
course) have any effect on actual place- the top of the page, is a simple thing to do:
ment of the float, but it makes the caption
\makeatletter
texts read ‘sensibly’:
\setlength{\@fptop}{0pt}
\begin{table} \makeatother
\caption{A table}
...
Surprisingly, you may find this setting
\end{table}
leaves your floats too high on the page.
...
One can justify a value of 5pt (in place of
0pt) — it’s roughly the difference between
\begin{table}\ContinuedFloat
\topskip and the height of normal (10pt)
\caption{A table (cont.)}
...
text.
\end{table}
Note that this is a “global” setting (best
established in a class file, or at worst in the
which would produce: document preamble); making the change
for a single float page is likely (at the least)
Table 3: A table . . . Table 3: A to be rather tricky.
table (cont.)
290 Figure (or table) exactly where I
caption.sty : want it
macros/latex/contrib/caption
This is of course a contradiction: figure
dpfloat.sty : and table are designed to float, and will
macros/latex/contrib/dpfloat always have the potential to appear away
fltpage.sty : from where you asked for them. There-
macros/latex/contrib/fltpage fore you need something that behaves like
a figure or table environment, except
289 Vertical layout of float pages that it doesn’t allow the figure or table to
By default, LaTeX vertically centres the float.
floats on a float page; the present author The most straightforward way is to use
is not alone in not liking this arrangement. of the float package; it gives you a [H] float
Unfortunately, the control of the position- placement option that prevents floating:
ing is “buried” in LaTeX-internal com-
mands, so some care is needed to change \begin{figure}[H]
the layout. \centering
Float pages use three LaTeX lengths \includegraphics{foo}
(i.e., TeX skips) to define their layout: \caption{caption text}
\label{fig:nonfloat}
\@fptop defines the distance from the top \end{figure}
of the page to the top of the first float,
\@fpsep defines the separation between As the example suggests, such a ‘[H]’ fig-
floats, and ure (or corresponding table) offers all you
\@fpbot defines the distance from the bot- need to cross-reference as well as typeset.
tom of the last float on the page to the (The package here provides the same func-
bottom of the page. tion, but is no longer recommended.)
However, you don’t actually have to
(In fact, the output routine places a skip of use float (or here) since it is, in fact, doing
\@fpsep above each float, so the \@fptop rather little for you. You can place your
skip is always followed by a correction for figure as you please, with a sequence like
that.)
The LaTeX defaults are: \begin{center}
\includegraphics{foo}
\@fptop = 0pt + 1fil \captionof{figure}{caption text}
\@fpsep = 8pt + 2fil \label{fig:nonfloat}
\@fpbot = 0pt + 1fil \end{center}

which relies on the \captionof command

so that the gaps expand to fill the space to place a caption without benefit of an en-
not occupied by floats, but if there is more closing float. That command may be had
157
from the extremely simple-minded pack- The ctable package extends the model
age capt-of or from the highly sophisti- of threeparttable, and also uses the ideas
cated caption package. of the booktabs package. The \ctable
Using either method, you have to deal command does the complete job of setting
with the possibility of the figure or table be- the table, placing the caption, and defin-
ing too large for the page. (Floating objects ing the notes. The “table” may consist of
will float away in this circumstance; “doing diagrams, and a parameter in \ctable’s
it by hand”, like this, you take upon your- optional argument makes the float that is
self the responsibility for avoiding ‘Over- created a “figure” rather than a “table”.
full \vbox ’ errors. If you really want “real” footnotes in
A further problem is the possibility tables, despite the expert advice, you can:
that such “fixed floats” will overtake “real
floats”, so that the numbers of figures will • Use \footnotemark to position the
be out of order: figure 6 could be on page little marker appropriately, and then
12, while figure 5 had floated to page 13. put in \footnotetext commands to
It’s best, therefore, either to stay with float- fill in the text once you’ve closed the
tabular environment. This is de-
ing figures throughout a document, or to
use fixed figures throughout. scribed in Lamport’s book, but it gets
If it’s really impossible to follow messy if there’s more than one foot-
that counsel of perfection, you can note.
use the perpage package’s command • Stick the tabular environment in a
minipage. Footnotes in the table then
\MakeSorted command:
“work”, in the minipage’s style, with
... no extra effort. (This is, in effect,
\usepackage{float} somewhat like table notes, but the
\usepackage{perpage} typeset appearance isn’t designed for
\MakeSorted{figure} the job.)
\MakeSorted{table} • Use tabularx or longtable from the
... LaTeX tools distribution; they’re no-
and the sequence of float numbers is all ticeably less efficient than the standard
correct. tabular environment, but they do al-
low footnotes.
capt-of.sty :
• Use tablefootnote; it provides a com-
macros/latex/contrib/capt-of
mand \tablefootnote, which does
caption.sty : the job without fuss.
macros/latex/contrib/caption • Use footnote, which provides
float.sty : an savenotes which collects all
macros/latex/contrib/float footnotes and emits them at the
here.sty :
end of the environment; thus if
macros/latex/contrib/here
you put your tabular environ-
ment inside a savenotes environ-
perpage.sty : Distributed as part of
ment, the footnotes will appear as
macros/latex/contrib/bigfoot
needed. Alternatively, you may use
P.5 Footnotes \makesavenoteenv{tabular} in
the preamble of your document, and
291 Footnotes in tables tables will all behave as if they were
The standard LaTeX \footnote command inside a savenotes environment.
doesn’t work in tables; the tabular environ- • Use mdwtab from the same bundle;
ment (and its “relations”) traps footnotes, it will handle footnotes as you might
and they can’t escape to the bottom of the expect, and has other facilities to
page. As a result, you get footnote marks increase the beauty of your tables.
in the table, and nothing else. Unfortunately, it may be incompati-
This accords with common typo- ble with other table-related packages,
graphic advice: footnotes and tables are though not those in the standard ‘tools’
reckoned not to mix. bundle.
The solution, if you accept the ad-
vice, is to use “table notes”. The package All the techniques listed will work, to some
threeparttable provides table notes, and extent, whether in a float or in ordinary text.
threeparttablex additionally supports them The author of this FAQ answer doesn’t ac-
in longtables. Threeparttable works hap- tually recommend any of them, believing
pily in ordinary text, or within a table that table notes are the way to go. . .
float. ctable.sty :
158
 macros/latex/contrib/ctable 293 Footnotes in captions
footnote.sty : Distributed as part of Footnotes in captions are especially tricky:
macros/latex/contrib/mdwtools they present problems of their own, on top
of the problems one experiences with foot-
longtable.sty : Distributed as part of
notes in section titles (footnotes migrating
macros/latex/required/tools
to to the list of figures or tables, or appar-
mdwtab.sty : Distributed as part of ently random errors because \footnote is
macros/latex/contrib/mdwtools a fragile command), and with footnotes in
tables (typically, the footnote simply dis-
tablefootnote.sty : macros/latex/ appears). Fortunately, the requirement for
contrib/tablefootnote footnotes in captions is extremely rare: if
threeparttable.sty : macros/latex/ you are experiencing problems, it is worth
contrib/threeparttable reviewing what you are trying to say by
placing this footnote: other options are to
threeparttablex.sty : macros/ place text at the bottom of the float, or to
latex/contrib/threeparttablex place a footnote at the point where you

tabularx.sty : Distributed as part of refer to the float.

macros/latex/required/tools Note that the threeparttable scheme
(see, again, footnotes in tables) also ap-
292 Footnotes in LaTeX section plies to notes in captions, and may very
headings well be preferable to whatever you were
thinking of.
The \footnote command is fragile, so If you are going to proceed:
that simply placing the command in
\section’s arguments isn’t satisfactory. • use an optional argument in your
Using \protect\footnote isn’t a good \caption command, that doesn’t
idea either: the arguments of a section have the footnote in it; this prevents
command are used in the table of contents the footnote appearing in the “List of
and (more dangerously) potentially also in . . . ”, and
page headers. While footnotes will work • put your whole float in a minipage so
in the table of contents, it’s generally not as to keep the footnotes with the float.
thought a “good thing” to have them there;
in the page header, footnotes will simply so we have:
fail. Whatever the desirability of the mat-
ter, there’s no mechanism to suppress the \begin{figure}
footnote in the page header while allowing \begin{minipage}{\textwidth}
it in the table of contents, so the footnote ...
may only appear in the section heading \caption[Compact Routing Example]%
itself. {Compact Routing\footnote{something} Example}
To suppress the footnote in headings \end{minipage}
and table of contents: \end{figure}

• Take advantage of the fact that the So, we make an entry for the List of Fig-
mandatory argument doesn’t ‘move’ ures, which doesn’t hold troublesome com-
if the optional argument is present: mands, such as \footnote.
\section[title]{title\footnote However, as well as all of the above,
{title ftnt}} one also has to deal with the tendency of
• Use the footmisc package, with pack- the \caption command to produce the
age option stable — this modi- footnote’s text twice. For this last prob-
fies footnotes so that they softly and lem, there is no tidy solution this author is
silently vanish away if used in a mov- aware of.
ing argument. With this, you simply If you’re suffering the problem, a
need: well-constructed \caption command in
% in the document preamble a minipage environment within a float (as
\usepackage[stable]{footmisc} in the example above) can produce two
... copies of the footnote body “something”.
% in the body of the document (In fact, the effect only occurs with cap-
\section{title\footnote{title ftnt}} tions that are long enough to require two
lines to be typeset, and so wouldn’t appear
footmisc.sty : with such a short caption as that in the ex-
macros/latex/contrib/footmisc ample above.)
159
 The documentation of the ccaption defined in the footmisc package and in the
package describes a really rather awful memoir class (at least); \footref reduces
work-around for this problem. the above example to:
ccaption.sty : ...\footnote{Text to repeat\label{fn:repeat}}
macros/latex/contrib/ccaption ...
threeparttable.sty : macros/latex/ ...\footref{fn:repeat}
contrib/threeparttable
This is the cleanest simple way of doing the
294 Footnotes whose texts are job. Note that the \label command must
identical be inside the argument of \footnote.
If the same footnote turns up at several The fixfoot package takes away some
places within a document, it’s often inap- of the pain of the matter: you declare foot-
propriate to repeat the footnote in its en- notes you’re going to reuse, typically in
tirety over and over again. We can avoid the preamble of your document, using a
repetition by semi-automatic means, or by \DeclareFixedFoot command, and then
simply labelling footnotes that we know use the command you’ve ‘declared’ in the
we’re going to repeat and then referencing body of the document:
the result. There is no completely auto-
\DeclareFixedFootnote{\rep}{Text to repeat}
matic solution (that detects and suppresses
...
repeats) available.
...\rep{}
If you know you only have one foot-
...\rep{}
note, which you want to repeat, the solu-
tion is simple: merely use the optional ar- The package ensures that the repeated text
gument of \footnotemark to signify the appears at most once per page: it will usu-
repeats: ally take more than one run of LaTeX to
get rid of the repeats.
...\footnote{Repeating note}
... fixfoot.sty :
...\footnotemark[1] macros/latex/contrib/fixfoot
footmisc.sty :
. . . which is very easy, since we know there
macros/latex/contrib/footmisc
will only ever be a footnote number 1. A
similar technique can be used once the foot- memoir.cls:
notes are stable, reusing the number that macros/latex/contrib/memoir
LaTeX has allocated. This can be tiresome, 295 More than one sequence of
though, as any change of typesetting could footnotes
change the relationships of footnote and
repeat: labelling is inevitably better. The need for more than one series of foot-
Simple hand-labelling of footnotes isnotes is common in critical editions (and
possible, using a counter dedicated to the other literary criticism), but occasionally
job: arises in other areas.
Of course, the canonical critical edition
\newcounter{fnnumber} package, edmac, offers the facility, as does
... its LaTeX port, the ledmac package.
...\footnote{Text to repeat}% Multiple ranges of footnotes are of-
\setcounter{fnnumber}{\thefootnote}% fered to LaTeX users by the manyfoot pack-
... age. The package provides a fair array of
...\footnotemark[\thefnnumber] presentation options, as well. Another crit-
ical edition ednotes package is built upon
but this is somewhat tedious. LaTeX’s la- a basis that includes manyfoot, as its mech-
belling mechanism can be summoned to anism for multiple sets of footnotes.
our aid, but there are ugly error messages The bigfoot package also uses
before the \ref is resolved on a second manyfoot as part of its highly sophisti-
run through LaTeX: cated structure of footnote facilities, which
was also designed to support typesetting
...\footnote{Text to repeat\label{fn:repeat}}
... critical editions.
...\footnotemark[\ref{fn:repeat}] bigfoot:
macros/latex/contrib/bigfoot
Alternatively, one may use the \footref
command, which has the advantage of edmac: macros/plain/contrib/edmac
working even when the footnote mark isn’t ednotes:
expressed as a number. The command is macros/latex/contrib/ednotes
160
ledmac: zref-perpage.sty :
macros/latex/contrib/ledmac Distributed as part of zref in
macros/latex/contrib/oberdiek
manyfoot.sty : Distributed as part of
macros/latex/contrib/ncctools 297 Not resetting footnote numbers
per chapter
296 Footnotes numbered “per page” Some classes (for example, book and
The obvious solution is to make the foot- report) set up a different set of footnotes
note number reset whenever the page num- per chapter, by resetting the footnote num-
ber is stepped, using the LaTeX internal ber at the start of the chapter. This is essen-
mechanism. Sadly, the place in the docu- tially the same action as that of equation,
ment where the page number is stepped is figure and table numbers, except that foot-
unpredictable, not (“tidily”) at the end of note numbers don’t get “decorated” with
the printed page; so changing the footnote the chapter number, as happens with those
number only ever works by ‘luck’. other numbers.
As a result, resetting footnotes is in- The solution is the same: use the
evitably a complicated process, using la- chngcntr package; since the numbers
bels of some sort. It’s nevertheless im- aren’t “decorated” you can use the
portant, given the common requirement \counterwithout* variant; the code:
for footnotes marked by symbols (with \counterwithout*{footnote}{chapter}
painfully small symbol sets). There are
four packages that manage it, one way or is all you need
another. chngcntr.sty :
The perpage and zref-perpage pack- macros/latex/contrib/chngcntr
ages provide a general mechanism for re-
setting counters per page, so can obviously P.6 Document management
be used for this task. The interface is pretty 298 What’s the name of this file
simple: \MakePerPage{footnote} (in
One might want this so as to automatically
perpage) or \zmakeperpage{footnote}
generate a page header or footer record-
(in zref-perpage). If you want to restart
ing what file is being processed. It’s not
the counter at something other than 1
easy. . .
(for example to avoid something in
TeX retains what it considers the name
the LaTeX footnote symbol list), you
of the job, only, in the primitive \jobname;
can use: \MakePerPage[2]{footnote}
this is the name of the file first handed to
(in perpage) or \zmakeperpage[2]
TeX, stripped of its directory name and of
{footnote} (in zref-perpage). Note that
any extension (such as .tex). If no file
you can also load zref-perpage
was passed (i.e., you’re using TeX inter-
Perpage is a compact and efficient
actively), \jobname has the value texput
package; zref-perpage, being a zref “mod-
(the name that’s given to .log files in this
ule”, comes with zref ’s general mech-
case).
anism for extending the the \label—
This is fine, for the case of a small doc-
\[page]ref of LaTeX, which can offer
ument, held in a single file; most signifi-
many other useful facilities.
cant documents will be held in a bunch of
The footmisc package provides a va- files, and TeX makes no attempt to keep
riety of means of controlling footnote ap- track of files input to the job. So the user
pearance, among them a package option has to keep track, himself — the only way
perpage that adjusts the numbering per
is to patch the input commands and cause
page; if you’re doing something else odd them to retain details of the file name. This
about footnotes, it means you may only is particularly difficult in the case of Plain
need the one package to achieve your ends. TeX, since the syntax of the \input com-
The footnpag package also does per- mand is so peculiar.
page footnotes (and nothing else). With In the case of LaTeX, the input com-
the competition from perpage, it’s proba- mands have pretty regular syntax, and the
bly not particularly useful any more. simplest patching techniques can be used
footmisc.sty : on them. (Note that latex’s \input com-
macros/latex/contrib/footmisc mand is itself a patch on top of the Plain
TeX command. Our patches apply to the
footnpag.sty :
LaTeX version of the command, which is
macros/latex/contrib/footnpag
used as \input{file})
perpage.sty : Distributed as part It is possible to keep track of the name
macros/latex/contrib/bigfoot of the file currently being processed, but
161
it’s surprisingly difficult (these FAQs of- \input, as:
fered code, for a long time, that just didn’t \input mymacros
work in many cases). mymacros.tex won’t be recorded, and so
The currfile package provides a regular won’t listed by \listfiles — you’ve by-
means of keeping track of the details of the passed the mechanism that records its use.
current file (its name in \currfilename, The snapshot package helps the owner
directory in \currfiledir, as well as the of a LaTeX document obtain a list of the
file ‘base’ name (less its extension) and external dependencies of the document, in
its extension). Currfile does this with the a form that can be embedded at the top
help of a second package, filehook, which of the document. The intended use of the
spots file operations that use \input, package is the creation of archival copies
\InputIfFileExists and \include, as
of documents, but it has application in doc-
well as package and class loading. ument exchange situations too.
The FiNK (“File Name Keeper”) pack- The bundledoc system uses the
age keeps track of the file name and ex- snapshot to produce an archive (e.g.,
tension, in a macro \finkfile. FiNK is .tar.gz or .zip) of the files needed by
now deprecated, in favour of currfile, but your document; it comes with configura-
remains available for use in old documents. tion files for use with TeX Live-Unix and
The FiNK bundle includes a fink.el that \miktex{}. It’s plainly useful when you’re
provides support under emacs with AUC- sending the first copy of a document.
TeX.
The mkjobtexmf finds which files are
currfile.sty : used in a ‘job’, either via the -recorder
macros/latex/contrib/currfile option of TeX, or by using the (Unix) com-
filehook.sty : mand strace to keep an eye on what TeX is
macros/latex/contrib/filehook doing. The files thus found are copied (or
linked) to a directory which may then be
fink.sty : saved for transmission or archiving.
macros/latex/contrib/fink
bundledoc: support/bundledoc
299 All the files used by this
mkjobtexmf : support/mkjobtexmf
document
snapshot.sty :
When you’re sharing a document with
macros/latex/contrib/snapshot
someone else (perhaps as part of a co-
development cycle) it’s as well to arrange 300 Marking changed parts of your
that both correspondents have the same set document
of auxiliary files, as well as the document
One often needs clear indications of how a
in question. Your correspondent obviously
document has changed, but the commonest
needs the same set of files (if you use the
technique, “change bars” (also known as
url package, she has to have url too, for
“revision bars”), requires surprisingly much
example). But suppose you have a bug- trickery of the programmer. The problem
free version of the shinynew package butis that TeX ‘proper’ doesn’t provide the
her copy is still the unstable original; until
programmer with any information about
you both realise what is happening, such a
the “current position” from which a puta-
situation can be very confusing. tive start- or end-point of a bar might be
The simplest solution is the LaTeX calculated. PDFTeX does provide that in-
\listfiles command. This places a list
formation, but no PDFTeX-based change-
of the files used and their version numbers
bar package has been published, that takes
in the log file. If you extract that list and
advantage of that.
transmit it with your file, it can be used asThe simplest package that offers
a check-list in case that problems arise.
change bars is Peter Schmitt’s backgrnd.
Note that \listfiles only reg- tex; this was written as a Plain TeX appli-
isters things that are input by cation that patches the output routine, but
the “standard” LaTeX mechanisms it appears to work at least on simple La-
(\documentclass, \usepackage,
TeX documents. Wise LaTeX users will be
\include, \includegraphics and so
alerted by the information that backgrnd
on). The \input command, as modified patches their output routine, and will watch
by LaTeX and used, with LaTeX syntax, its behaviour very carefully (patching the
as: LaTeX output routine is not something to
\input{mymacros} undertake lightly. . . ).
records file details for mymacros.tex, The longest-established LaTeX-
but if you use TeX primitive syntax for specific solution is the changebar package,
162
which uses \special commands supplied documentation, latexdiff-man.pdf (part of
by the driver you’re using. You need there- the distribution). A rudimentary revision
fore to tell the package which driver to facility is provided by another Perl script,
you’re using (in the same way that you latexrevise, which accepts or rejects all
need to tell the graphics package); the changes. Manual editing of the difference
list of available drivers is pretty wide, but file can be used to accept or reject selected
does not include dvipdfm. The package changes only.
comes with a shell script chbar.sh (for backgrnd.tex : macros/generic/
use on Unix machines) that will compare misc/backgrnd.tex
two documents and generate a third which
changebar.sty : macros/latex/
is marked-up with changebar macros to
contrib/changebar
highlight changes.
The shareware WinEDT editor has changes.sty :
a macro that will generate changebar macros/latex/contrib/changes
(or other) macros to show differences framed.sty :
from an earlier version of your file, macros/latex/contrib/framed
stored in an RCS-controlled repository —
latexdiff, latexrevise:
see http://www.winedt.org/Macros/
support/latexdiff
LaTeX/RCSdiff.php
The vertbars package uses the tech- lineno.sty :
niques of the lineno package (which it macros/latex/contrib/lineno
loads, so the lineno itself must be in- memoir.cls:
stalled); it’s thus the smallest of the pack- macros/latex/contrib/memoir
ages for change bar marking, since it vertbars.sty :
leaves all the trickery to another package. macros/latex/contrib/vertbars
Vertbars defines a vertbar environment
winedt: systems/win32/winedt
to create changebars.
The framed package is another that 301 Conditional compilation and
provides bars as a side-effect of other de- “comments”
sirable functionality: its leftbar envi- While LaTeX (or any other TeX-derived
ronment is simply a stripped-down frame package) isn’t really like a compiler, peo-
(note, though, that the environment makes ple regularly want to do compiler-like
a separate paragraph of its contents, so it is things using it. Common requirements are
best used when the convention is to mark conditional ‘compilation’ and ‘block com-
a whole changed paragraph. ments’, and several LaTeX-specific means
Finally, the memoir class allows to this end are available.
marginal editorial comments, which you The simple \newcommand{\gobble}
can obviously use to delimit areas of [1]{} and \iffalse ... \fi aren’t re-
changed text. ally satisfactory (as a general solution) for
An even more comprehensive way to comments, since the matter being skipped
keep track of changes is employed by some is nevertheless scanned by TeX, not always
word-processors — to produce a document as you would expect. The scanning im-
that embodies both “old” and “new” ver- poses restrictions on what you’re allowed
sions. to skip; this may not be a problem in to-
To this end, the package changes al- day’s job, but could return to bite you to-
lows the user to manually markup changes morrow. For an example of surprises that
of text, such as additions, deletions, or may come to bite you, consider the fol-
replacements. Changed text is shown in lowing example (derived from real user
a different colour; deleted text is crossed experience):
out. The package allows you to define addi-
\iffalse % ignoring this bit
tional authors and their associated colour;
consider what happens if we
it also allows you to define a markup for
use \verb+\iftrue+ -- a surprise
authors or annotations. The documenta-
\fi
tion (very clearly) demonstrates how the
various functions work. The \iftrue is spotted by TeX as it
The Perl script latexdiff may also be scans, ignoring the \verb command; so
used to generate such markup for LaTeX the \iffalse isn’t terminated by the fol-
documents; you feed it the two documents, lowing \fi. Also, \gobble is pretty inef-
and it produces a new LaTeX document ficient at consuming anything non-trivial,
in which the changes are very visible. An since all the matter to be skipped is copied
example of the output is embedded in the to the argument stack before being ignored.
163
 If your requirement is for a doc- (To include all of the document, you write
ument from which whole chapters (or
the like) are missing, consider the La- \includepdf[pages=-]{yoursource.pdf}
TeX \include/\includeonly system. If
omitting the start and end pages in the op-
you ‘\include’ your files (rather than
tional argument.)
\input them — see What’s going on in
If you want flexible facilities for includ-
my \include commands?), LaTeX writes
ing or excluding small portions of a file,
macro traces of what’s going on at the end
consider the comment, version or optional
of each chapter to the .aux file; by using
packages.
\includeonly, you can give LaTeX an
The comment package allows you
exhaustive list of the files that are needed.
to declare areas of a document to be
Files that don’t get \included are skipped
included or excluded; you make these
entirely, but the document processing con-
declarations in the preamble of your
tinues as if they were there, and page, foot-
file. The command \includecomment
note, and other numbers are not disturbed.
{version-name} declares an environ-
Note that you can choose which sections
ment version-name whose content will
you want included interactively, using the
be included in your document, while
askinclude package.
\excludecomment{version-name} de-
A variant on the \includeonly mech-
fines an environment whose content will
anism is offered by the stampinclude pack-
be excluded from the document. The pack-
age, which takes advantage of the PDF-
age uses a method for exclusion that is
TeX \pdffilemoddate command. When pretty robust, and can cope with ill-formed
an \included file is processed in abunches of text (e.g., with unbalanced
LaTeX document, an .aux file is cre-
braces or \if commands).
ated holding data such as page-number (These FAQs employ the comment
ranges and chapter/section numbers. When
package to alter layout between the printed
\stampinclude is included in a document,
(two-column) version and the PDF version
it compares the file system modification
for browsing; there are narrowversion
times for each file and its corresponding
and wideversion for the two versions of
.aux file; the file is only compiled in “this
the file.)
run” of the document if the file is newer
version offers similar facilities to
than its corresponding .aux file. The pack-
comment.sty (i.e., \includeversion
age requires a current PDFTeX, and will
and \excludeversion commands); it’s
also run on LuaTeX if the pdftexcmds pack-
far “lighter weight”, but is less robust (and
age is available (pdftexcmds emulates the
in particular, cannot deal with very large
requisite PDFTeX commands using lua.
areas of text being included/excluded).
Apart from this requirement, stampinclude
A significant development of version,
is a low-maintenace object; include it in
confusingly called versions (i.e., merely
your document and it silently does its job.
a plural of the old package name).
When you want a final version of your doc-
Versions adds a command \markversion
ument, delete all the .aux files, and and
{version-name} which defines an envi-
stampinclude won’t interfere.) ronment that prints the included text, with
The inverse can be done using the
a clear printed mark around it.
excludeonly package: this allows you to ex-
optional defines a command \opt; its
clude a (list of) \included files from your
first argument is an ‘inclusion flag’, and its
document, by means of an \excludeonly
second is text to be included or excluded.
command. Text to be included or excluded must be
If you want to select particular pages
well-formed (nothing mismatched), and
of your document, use Heiko Oberdiek’s
should not be too big — if a large body
pagesel or the selectp packages. You can
of text is needed, \input should be used
do something similar with an existing PDF
in the argument. The documentation (in
document (which you may have compiled
the package file itself) tells you how to
using pdflatex in the first place), using the
declare which sections are to be included:
pdfpages package. The job is then done
this can be done in the document preamble,
with a document looking like: but the documentation also suggests ways
in which it can be done on the command
\documentclass{article} line that invokes LaTeX, or interactively.
\usepackage[final]{pdfpages} And, not least of this style of con-
\begin{document} ditional compilation, verbatim (which
should be available in any distribution) de-
\includepdf[pages=30-40]{yoursource.pdf}
\end{document} fines a comment environment, which en-
164
ables the dedicated user of the source text
which will cause the package to pro-
editor to suppress bits of a LaTeX source
duce a file foobar.tex containing all the
file. The memoir class offers the same en-
figure and table environments, and the
vironment. \chapter and \section commands, from
An interesting variation is the
the document being processed. The new
xcomment package. This defines an envi-
file foobar.tex is generated in the course
ronment whose body is all excluded, apart
of an otherwise ordinary run on the ‘mas-
from environments named in its argument.
ter’ document. The package provides a
So, for example: good number of other facilities, including
(numeric or labelled) ranges of environ-
\begin{xcomment}{figure,table}
ments to extract, and an extract environ-
This text is not included
ment which you can use to create complete
\begin{figure}
ready-to-run LaTeX documents with stuff
This figure is included
you’ve extracted.
\end{figure}
This is not included, either askinclude.sty : Distributed as part of
\begin{table} macros/latex/contrib/oberdiek
This table also included comment.sty :
\end{table} macros/latex/contrib/comment
... excludeonly.sty : macros/latex/
\end{xcomment} contrib/excludeonly
The tagging package offers another extract.sty :
neat set of syntax, which allow the user macros/latex/contrib/extract
to apply “tags” to chunks of text, and to memoir.cls:
include and exclude tagged text, according macros/latex/contrib/memoir
to the tags. For example, the user may ‘use’
optional.sty :
text marked with some tags, and to ‘drop’
macros/latex/contrib/optional
marked with others:
pagesel.sty : Distributed as part of
\usetag{<tag list>} macros/latex/contrib/oberdiek
\droptag{<tag list>}
pdfpages.sty :
(the tag lists consist of comma-separated macros/latex/contrib/pdfpages
single words). selectp.sty :
There are then commands macros/latex/contrib/selectp
\tagged{<tag list>}{<text>} stampinclude.sty :
Distributed as part of
which reproduces the text only if the htag
macros/latex/contrib/oberdiek
listi contains at least one tag listed in the
\usetag comand, and tagging.sty :
macros/latex/contrib/tagging
\untagged{<tag list>}{<text>}
verbatim.sty : Distributed as part of
which only reproduces the text unless the macros/latex/required/tools
htag listi contains none of the tags mention version.sty :
in the \droptag command. macros/latex/contrib/version
Further commands offer an if-then-
versions.sty : macros/latex/
else setup, and specify taggedblock and
contrib/versions/versions.sty
untaggedblock environments that.
Another valuable aspect of the prob- xcomment.sty :
lem is covered by the extract package. The macros/generic/xcomment
package allows you to produce a “partial 302 Bits of document from other
copy” of an existing document: the pack- directories
age was developed to permit production of
A common way of constructing a large doc-
a “book of examples” from a set of lecture
ument is to break it into a set of files (for
notes. The package documentation shows
example, one per chapter) and to keep ev-
the following usage:
erything related to each of these subsidiary
\usepackage[ files in a subdirectory.
active, Unfortunately, TeX doesn’t have a
generate=foobar, changeable “current directory”, so that all
extract-env={figure,table}, files you refer to have to be specified rela-
extract-cmd={chapter,section} tive to the same directory as the main file.
]{extract} Most people find this counter-intuitive.
165
 It may be appropriate to use the chapterfolder.sty : macros/latex/
“path extension” technique used in tempo- contrib/chapterfolder
rary installations to deal with this prob- import.sty :
lem. However, if there several files with macros/latex/contrib/import
the same name in your document, such
as chapter1/fig1.eps and chapter2/ 303 Version control using RCS, CVS
fig1.eps, you’re not giving TeX any hint or the like
If you use RCS, CVS, Subversion, Bazaar
as to which you’re referring to when in the
or Git to maintain your (La)TeX docu-
main chapter file you say \input{sect1};
ments under version control, you may need
while this is readily soluble in the case
some mechanism for including the version
of human-prepared files (just don’t name
details in your document, in such a way
them all the same), automatically produced
files have a way of having repetitiousthat they can be typeset (that is, rather than
just hiding them inside a comment).
names, and changing them is a procedure
prone to error. The most complete solution for RCS
The import package comes to your and CVS is to use the (LaTeX) package rcs,
which allows you to parse and display the
help here: it defines an \import command
contents of RCS keyword fields in an ex-
that accepts a full path name and the name
tremely flexible way. The package rcsinfo
of a file in that directory, and arranges
is simpler, but does most of what you want,
things to “work properly”. So, for example,
if /home/friend/results.tex contains and some people prefer it; it is explicitly
compatible with LaTeX2HTML.
Graph: \includegraphics{picture} If, however, you need a solution which
\input{explanation} works without using external packages, or
then \import{/home/friend/} which will work in Plain TeX, then you
{results} will include both graph and can use the following minimal solution:
explanation as one might hope. A \def\RCS$#1: #2 ${\expandafter\def\csname RCS#1\endcsna
\subimport command does the same \RCS$Revision: 1.47 $ % or any RCS keyword
sort of thing for a subdirectory (a rela- \RCS$Date: 2014/01/28 18:17:23 $
tive path rather than an absolute one), and ...
there are corresponding \includefrom \date{Revision \RCSRevision, \RCSDate}
and \subincludefrom commands.
If you are a user of Subversion, the
The chapterfolder package provides
package svn may be for you. It has explicit
commands to deal with its (fixed) model
cleverness about dealing with dates:
of file inclusion in a document. It pro-
vides commands \cfpart, \cfchapter, \documentclass{hfooi}
\cfsection and \cfsubsection, each of ...
which takes directory and file arguments, \usepackage{svn}
e.g.: \SVNdate $Date$
\author{...}
\cfpart[pt 1]{Part One}{part1}{part} \title{...}
...
which command will issue a ‘normal’ com-
\begin{document}
mand \part[pt 1]{Part One} and then
\maketitle
input the file part1/part.tex, remem-
...
bering that part1/ is now the “current
\end{document}
folder”. There are also commands of the
form \cfpartstar (which corresponds to will (once subversion has committed a
a \part* command). copy of the document) cause \maketitle
Once you’re “in” a chapterfolder- use the date that has been written into the
included document, you may use $Date$ keyword.
\cfinput to input something relative Another alternative for Subversion
to the “current folder”, or you may users is the svninfo package, which has
use \input, using \cfcurrentfolder much the same mechanisms as does svn
to provide a path to the file. (There but with a rather different focus. Svninfo
are also \cfcurrentfolderfigure does the date trick that svn performs (con-
for a figure/ subdirectory and trolled by a package option), and can set
\cfcurrentfolderlistings for a up page foot-lines using package fancyhdr.
listings/ subdirectory.) There isn’t much to choose between the
Documentation of chapterfolder is in two packages: you should read the pack-
French, but the README in the directory is ages’ documentation to see which suits you
in English. best.
166
 An alternative script-based approach Newer still is the Python script try,
to version control has been taken by the which has a similar structure to arara —
vc bundle, that in certain situations might it, too, reads instructions in the document
work more reliably than any of the pack- source.
ages mentioned above. The vc bundle sup- Apparently along the same lines, is Au-
ports Bazaar, Git and Subversion usage toLaTeX. The README of the distribution
and works with both LaTeX and Plain TeX. is actual a Unix-type man-page output, and
Note that vc is the only option that cur- shows great attention to the details of the
rently claims to support Bazaar-controlled document production process.
repositories. The (Ruby) script mk (also, apparently,
Finally, for now, the gitinfo package known as latex_maker) works well with
supports Git-controlled documents. another of the author’s scripts script called
gitinfo.sty : vpp (View and Print PostScript/PDF).
macros/latex/contrib/gitinfo Windows users of the MiKTeX system
may use that system’s texify application.
rcs.sty : macros/latex/contrib/rcs
Texify deals with basic LaTeX features,
rcsinfo.sty : including generating a bibliography and
macros/latex/contrib/rcsinfo an index; it makes no claim to deal with
svn.sty : macros/latex/contrib/svn other things (such as multiple bibliogra-
phies or indexes, or lists of terminology,
svninfo.sty :
etc.), which AutoLaTeX can be configured
macros/latex/contrib/svninfo
to process.
vc: support/vc The texinfo system comes with a simi-
304 Makefiles for LaTeX documents lar utility called texi2dvi, which is capable
of “converting” either LaTeX or texinfo
LaTeX documents are tricky beasts for
files into DVI (or into PDF, using PDF-
building using (Uni*x) make on: the need
TeX).
to instruct LaTeX to run several times for
A later contribution is the bundle
essentially different reasons (for example,
latexmake, which offers a set of make rules
“get the table of contents stable”, “get the la-
that invoke texi2dvi as necessary.
bels stable”, “add the bibliography”, “add
The curious may examine the rules em-
the index”) is actually rather difficult to ex-
ployed to run the present FAQ through La-
press in the ‘ordinary’ sort of dependency
TeX: we don’t present them as a complete
graph that one constructs for make.
solution, but some of the tricks employed
The latex-make package offers help
are surely re-usable.
with this task (far more sophisticated tech-
niques than in the script that builds these arara: support/arara
FAQs); it looks good, but reports of its use AutoLaTeX: support/autolatex
(other than by its author) are scarce. FAQ distribution: help/uk-tex-faq
For a long time, the only make-like
package on CTAN was latexmk, which latexmake: support/latexmake
is a Perl script that analyses your LaTeX latex-make: support/latex-make
source for its dependencies, runs BibTeX latex_make: support/latex_maker
or makeindex as and when it notices that
latexmk : support/latexmk
those programs’ input (parts of the .aux
file, or the .idx file, respectively) has texi2dvi: Distributed as part of
changed, and so on. Latexmk is a fine solu- macros/texinfo/texinfo
tion (and was used in generating printable try : support/try
versions of these FAQs for some time); it vpp: support/view_print_ps_pdf
has recently been upgraded and has many
bells and whistles that allow it to operate as 305 How many pages are there in my
if it were a poor man’s WYSIWYG system. document?
A recent strong contender is arara, Simple documents (those that start at page
written in Java. It is (the documentation 1, and don’t have any breaks in their page
says) based on “rules” and “directives”; its numbering until their last page) present
aim is to determine what to do from ex- no problem to the seeker after this truth.
plicit instructions in the document’s source The number of pages is reported by the
code, rather than secondary sources such lastpage package in its LastPage label.
as log file analysis. Arara is relatively new For more complicated documents
on CTAN, and comes with recommenda- (most obviously, books with frontmatter
tions from many of the great and good of in a different series of page numbers) this
the LaTeX world. simple approach will not do.
167
 The count1to package defines a label plain.sty : Distributed as part of
TotalPages; this is the value of its copy macros/latex/contrib/carlisle
of \count1 (a reserved TeX count register)
at the end of the document. P.7 Hyphenation
Package totpages defines a label 307 My words aren’t being
TotPages, but it also makes the regis- hyphenated
ter it uses available as a LaTeX counter, Let’s assume you’ve selected the right TeX
TotPages, which you can also reference ‘language’ — as explained in “how hyphen-
via \theTotPages. Of course, the counter ation works”, you’re not likely to get the
TotPages is asynchronous in the same correct results typesetting one language us-
way that page numbers are, but snapshots ing the hyphenation rules of another. (Se-
may safely be taken in the output routine. lect the proper language, using babel if
The memoir class defines two counters you’re a LaTeX user. This may reveal that
lastpage and lastsheet, which are set you need another set of hyphenation pat-
(after the first run of a document) to the terns; see “using a new language” for ad-
equivalent of the LastPage label and the vice on how to install it.)
TotalPages labels. So what else can go wrong?
Both count1to and totpages need the
support of the everyshi package. • Since TeX version 3.0, the limits on
how near to either end of a word hy-
count1to.sty : Distributed as part of
phenation may take place have been
macros/latex/contrib/ms
programmable (see “weird hyphen-
everyshi.sty : Distributed as part of ation”), and for some reason the
macros/latex/contrib/ms values in question may have been
lastpage.sty : corrupted in some macros you are
macros/latex/contrib/lastpage using. TeX won’t hyphenate less
than \lefthyphenmin characters af-
memoir.cls: ter the start of a word, nor less than
macros/latex/contrib/memoir \righthyphenmin before the end of a
totpages.sty : word; thus it won’t hyphenate a word
macros/latex/contrib/totpages shorter than the sum of the two min-
ima, at all. For example, since the
306 Including Plain TeX files in minima are 2 and 3 for English, TeX
LaTeX won’t hyphenate a word shorter than
LaTeX, though originally based on Plain 5 letters long, if it believes the word
TeX, does not contain all of Plain TeX’s to be English.
commands. Worse, some Plain TeX com- • TeX won’t hyphenate a word that’s
mand names appear in LaTeX, with differ- already been hyphenated. For ex-
ent semantics. As a result, special mea- ample, the (caricature) English sur-
sures need to be taken to allow general name Smyth-Postlethwaite wouldn’t
Plain TeX documents (or parts of docu- hyphenate, which could be trouble-
ments) to be typeset within LaTeX. some. This is correct English type-
The truly reliable way is to translate the setting style (it may not be correct for
Plain TeX commands, to produce an equiv- other languages), but if needs must,
alent of the original’s semantics. However, you can replace the hyphen in the
this is not practical in many circumstances, name with a \hyph command, defined
and for those occasions, the plain package \def\hyph{-\penalty0\hskip0pt\relax}
will often come to your aid. The package
This is not the sort of thing this FAQ
defines a plain environment, in which a
would ordinarily recommend. . . The
Plain TeX document may be processed:
hyphenat package defines a bundle of
\begin{plain} such commands (for introducing hy-
\input{plain-doc} phenation points at various punctua-
\end{plain} tion characters).
• There may be accent commands in the
The package is known to fail, for exam- word. The causes of and remedies for
ple, with documents that use AMSTeX; no this effect are discussed in accents and
doubt it would also fail if asked to load hyphens.
Eplain. All these things can be overcome • The hyphenation may simply not have
(although it’s not often easy), but the en- been spotted; while TeX’s algorithm
vironment saves a lot of work on many is good, it’s not infallible, and it does
occasions. miss perfectly good hyphenations in
168
 some languages. When this happens, 309 (Merely) peculiar hyphenation
you need to give TeX explicit instruc- You may have found that TeX’s famed auto-
tions on how to hyphenate. matic word-division does not produce the
The \hyphenation command allows you break-points recommended by your dic-
to give explicit instructions. Provided that tionary. This may be because TeX is set
the word will hyphenate at all (that is, it up for American English, whose rules for
is not prevented from hyphenating by any word division (as specified, for example, in
of the other restrictions above), the com- Webster’s Dictionary) are completely dif-
mand will override anything the hyphen- ferent from the British ones (as specified,
ation patterns might dictate. The command for example, in the Oxford Dictionaries).
takes one or more hyphenated words as This problem is being addressed by the
argument — \hyphenation{ana-lysis UK TeX User community (see Baskerville,
pot-able}; note that (as here, for analy- issue 4.4) but an entirely satisfactory so-
sis) you can use the command to overrule lution will take time; the current status is
TeX’s choice of hyphenation (ana-lysis to be found on CTAN (see “using a new
is the British etymological hyphenation; language” for instructions on adding this
some feel the American hyphenation feels new “language”).
‘unfortunate’. . . ). UK patterns: language/
hyphenat.sty : hyphenation/ukhyphen.tex
macros/latex/contrib/hyphenat 310 Accented words aren’t
308 Weird hyphenation of words hyphenated
If your words are being h-yphenated, like TeX’s algorithm for hyphenation gives up
this, with jus-t single letters at the begin- when it encounters an \accent command;
ning or the end of the word, you may have there are good reasons for this, but it means
a version mismatch problem. TeX’s hy- that quality typesetting in non-English lan-
phenation system changed between ver- guages can be difficult.
sion 2.9 and 3.0, and macros written for For TeX macro packages, you can
use with version 2.9 can have this effect avoiding the effect by using an appropri-
with a version 3.0 system. If you are using ately encoded font (for example, a Cork-
Plain TeX, make sure your plain.tex file encoded font — see the EC fonts) which
has a version number which is at least 3.0, contains accented letters as single glyphs.
and rebuild your format. If you are using LaTeX users can achieve this end simply
LaTeX 2.09 your best plan is to upgrade by adding the command
to LaTeX2e. If for some reason you can’t, \usepackage[T1]{fontenc}
the last version of LaTeX 2.09 (released on to the preamble of their document. Other
25 March 1992) is still available (for the encodings (notably LY1, once promoted
time being at least) and ought to solve this by Y&Y inc) may be used in place of T1.
problem. Indeed, most current 8-bit TeX font encod-
If you’re using LaTeX2e, the problem ings will ‘work’ with the relevant sets of
probably arises from your hyphen.cfg hyphenation patterns.
file, which has to be created if you’re using With the advance of XeTeX and Lua-
a multi-lingual version. TeX to the mainstream, a new regime for
A further source of oddity can derive generating hyphenation tables is in place.
from the 1995 release of Cork-encoded For each language, a table is written in Uni-
fonts, which introduced an alternative hy- code, and “8-bit” versions are generated
phen character. The LaTeX2e configura- for use with various LaTeX font encod-
tion files in the font release specified use ings. Original sets of patterns remain on
of the alternative hyphen, and this could CTAN, for use when an older environment
produce odd effects with words contain- is needed.
ing an explicit hyphen. The font configu-
ration files in the December 1995 release 311 Using a new language with Babel
of LaTeX2e do not use the alternative hy- Babel is capable of working with a large
phen character, and therefore removed this range of languages, and a new user often
source of problems; the solution, again, is wants to use a language that her TeX in-
to upgrade your LaTeX. stallation is not set up to employ. Simply
LaTeX 2.09: asking Babel to use the language, with the
obsolete/macros/latex209/ command
distribs/latex209.tar.gz \usepackage[catalan]{babel}
plain.tex : macros/plain/base provokes the warning message
169
 Start→Programs
Package babel Warning: No hyphenation patterns →MiKTeX
were loaded for→
(babel) Maintenance→Create all
the language ‘Catalan’
(babel) I will use the patterns
format files
loaded for \language=0 instead.
The problem is that your TeX system or get a DOS window and run:
doesn’t know how to hyphenate Catalan initexmf --dump
text: you need to tell it how before Babel On a \miktex{} distribution v2.0 or
can do its work properly. To do this, for later, the whole procedure can be
LaTeX installations, one needs to change done via the GUI. To select the new
language.dat (which is part of the Babel language, do:
installation); it will contain a line Start→Programs→MiKTeX 2→
%catalan cahyphen.tex MiKTeX Options, and select the
Languages tab. Select your language
which, if you remove the comment marker,
from the list, press the Apply button,
is supposed to instruct LaTeX to load Cata-
and then the OK button. Then select
lan hyphenation patterns when you tell it
the General tab and press the Update
to build a new format.
Now button.
Unfortunately, in many Babel distri-
Otherwise, edit the language.dat
butions, the line just isn’t right — you
file (as outlined above), and then run:
need to check the name of the file contain-
initexmf --dump
ing the patterns you’re going to use. As
just as for a pre-v2.0 system.
you can see, in the author’s system, the
name is supposed to be cahyphen.tex; Caveat: It is (just) possible that your TeX
however the file actually present on the system may run out of “pattern memory”
system is cahyph.tex — fortunately, the while generating the new format. Most
error should prove little more than an in- TeX implementations have fixed-size ar-
convenience (most of the files are in better rays for storing the details of hyphenation
distributions anyway, but an elusive one patterns, but although their size is ad-
may be found on CTAN; if you have to justable in most modern distributions, actu-
retrieve a new file, ensure that it’s correctly ally changing the size is a fiddle. If you do
installed, for which see installing a new find you’ve run out of memory, it may be
package). worth scanning the list of languages in your
Finally, you need to regenerate the for- language.dat to see whether any could
mats used (in fact, most users of Babel are reasonably be removed.
using it in their LaTeX documents, so re-
babel:
generating the LaTeX-related formats will
macros/latex/required/babel
ordinarily be enough; however, the author
always generates the lot, regardless). hyphenation patterns:
language/hyphenation
teTeX It’s possible to do the whole opera-
tion in one go, by using the texconfig 312 Stopping all hyphenation
command: It may seem an odd thing to want to do
texconfig hyphen latex (after all, one of TeX’s great advertised
which first enters an editor for you to virtues is the quality of its hyphenation) but
edit language.dat, and then regener- it’s sometimes necessary. The real problem
ates the format you specify (latex in is, that the quality of TeX’s output is by de-
this case). fault largely dependent on the presence of
Otherwise, to regenerate all formats, hyphenation; if you want to abandon hy-
do: phenation, something has to give.
fmtutil --all TeX (slightly confusingly) offers four
If you’re willing to think through what possible mechanisms for suppressing hy-
you’re doing (this is not for the faint- phenation (there were only two prior to
hearted), you can select a sequence of the extensions that arrived with TeX ver-
formats and for each one, run: sion 3).
fmtutil --byfmt hformatnamei First, one can set the hyphen-
where formatname is something like ation penalties \hyphenpenalty and
‘latex’, or: \exhyphenpenalty to an ‘infinite’ value
fmtutil --byhyphen hhyphenfilei (that is to say, 10000). This means that all
where hyphenfile is the file speci- hyphenations will sufficiently penalise the
fying hyphenation to the format — line that would contain them, that the hy-
usually language.dat phenation won’t happen. The disadvantage
MiKTeX On a \miktex{} distribution ear- of this method is that TeX will re-evaluate
lier than v2.0, do: any paragraph for which hyphenations
170
might help, which will slow TeX down. The simplest route is to use \sloppy
Second, one can select a language (or its environment version sloppypar),
for which no hyphenation patterns ex- and have TeX stretch what would other-
ist. Some distributions create a language wise be underfull lines to fill the space of-
nohyphenation, and the hyphenat pack- fered, while prematurely wrapping overfull
age uses this technique for its \nohyphens lines and stretching the remainder.
command which sets its argument without The better bet is to set the text ragged
any hyphenation. You can load hyphenat right, and at least get rid of the overfull
with the command lines; this technique is ‘traditional’ (in the
sense that typists have always done it) and
\usepackage[none]{hyphenat} may be expected to appeal to the specifiers
of eccentric document layouts (such as
to prevent any hyphenation in a single- those for dissertations), but for once their
language document. The technique can- sense conforms with typographic style. (Or
not work in a document in which babel at least, style constrained in this curious
controls language selection, since babel way.)
incorporates hyphenation change into its
language change facilities. hyphenat.sty :
macros/latex/contrib/hyphenat
Third, one can set \left- and/or
\righthyphenmin to a sufficiently large 313 Preventing hyphenation of a
value that no hyphenation could possibly particular word
succeed, since the minimum is larger than
It’s quite possible for (any) hyphenation
the length of the longest word TeX is will-
of a particular word to seem “completely
ing to hyphenate (the appropriate value is
wrong”, so that you want to prevent it be-
62).
ing hyphenated.
Fourth, one can suppress hyphenation
If the word occurs in just one place, put
for all text using the current font by the
it in a box:
command
\mbox{oddword}
\hyphenchar\font=-1
(Plain TeX users should use \hbox, and
This isn’t a particularly practical way for take care at the start of paragraphs.) How-
users to suppress hyphenation — the com- ever, boxing the word is not really advis-
mand has to be issued for every font the able unless you are sure it only occurs
document uses — but it’s how LaTeX itself once.
suppresses hyphenation in tt and other If the word occurs commonly, the best
fixed-width fonts. choice is to assert an hyphenation excep-
Which of the techniques you should tion for it:
use depends on what you actually want
to do. If the text whose hyphenation is \hyphenation{oddword}
to be suppressed runs for less than a para-
graph, your only choice is the no-hyphens This hyphenation exception (with no break
language: the language value is preserved points) will be used in preference to what
along with the text (in the same way that TeX’s hyphenation algorithm may come
the current font is); the values for penalties up with.
and hyphen minima active at the end of a In a multilingual document, repeat the
paragraph are used when hyphenation is exception specification for each language
calculated. the word may appear in. So:
Contrariwise, if you are writing a mul- \usepackage[french,english]{babel}
tilanguage document using the babel pack- \selectlanguage{english}
age, you cannot suppress hyphenation \hyphenation{oddword}
throughout using either the no-hyphens lan- \selectlanguage{french}
guage or the hyphen minima: all those val- \hyphenation{oddword}
ues get changed at a babel language switch:
use the penalties instead. (note that babel will select the default lan-
If you simply switch off hyphenation guage for the document — English, in this
for a good bit of text, the output will have case — at \begin{document}.)
a jagged edge (with many lines seriously A particular instance of this require-
overfull), and your (La)TeX run will bom- ment is avoiding the hyphenation of
bard you with warnings about overfull and acronyms; a general rule for those that con-
underfull boxes (that is, really, lines). To coct acronyms seems to be to make the
avoid this you have two options. capital-letter sequence read as near as is
171
possible like a “real” word, but hyphenat- tells us that the hyphenation is “improper”,
ing an acronym often looks silly. The TeX and that it will be “flushed”. But, just as hy-
control \uchyph is designed for suppress- phenation of words is enabled by selecting
ing such behaviour: an 8-bit font encoding, so \hyphenation
commands are rendered proper again by
\uchyph=0 selecting that same 8-bit font encoding.
For the hyphenation patterns provided for
will stop hyphenation of upper-case words.
‘legacy’, the encoding is Cork, so the com-
(Note that Plain TeX syntax is needed here:
plete sequence is:
there’s no LaTeX alternative for setting this
value.) \usepackage[T1]{fontenc}
\usepackage[french]{babel}
314 Hyphenation exceptions
\selectlanguage{french}
While TeX’s hyphenation rules are good, \hyphenation{r\’e-f\’e-rence}
they’re not infallible: you will occasion-
ally find words TeX just gets wrong. So The same sort of performance goes for any
for example, TeX’s default hyphenation language for which 8-bit fonts and corre-
rules (for American English) don’t know sponding hyphenation patterns are avail-
the word “manuscript”, and since it’s a able. Since you have to select both the lan-
long word you may find you need to hy- guage and the font encoding to have your
phenate it. You can “write the hyphenation document typeset correctly, it should not
out” each time you use the word: be a great imposition to do the selections
before setting up hyphenation exceptions.
... man\-u\-script ... Modern TeX variants (principally Xe-
TeX and LuaTeX) use unicode, internally,
Here, each of the \- commands is con- and distributions that offer them also of-
verted to a hyphenated break, if (and only fer UTF-8-encoded patterns; since the hy-
if ) necessary. phenation team do all the work “behind the
That technique can rapidly become te- scenes”, the use of Unicode hyphenation
dious: you’ll probably only accept it if is deceptively similar to what we are used
there are no more than one or two wrongly- to.
hyphenated words in your document. The
alternative is to set up hyphenations in the P.8 Odds and ends
document preamble. To do that, for the 315 Typesetting all those TeX-related
hyphenation above, you would write: logos
\hyphenation{man-u-script} Knuth was making a particular point about
the capabilities of TeX when he defined
and the hyphenation would be set for the the logo. Unfortunately (in some people’s
whole document. Barbara Beeton pub- opinion) he thereby opened floodgates to
lishes articles containing lists of these “hy- give the world a whole range of rather silly
phenation exceptions”, in TUGboat; the ‘bumpy road’ logos for TeX entities such
hyphenation ‘man-u-script’ comes from as AMSTeX, PiCTeX, BibTeX, and so
one of those articles. on, produced in a flurry of different fonts,
What if you have more than one lan- sizes, and baselines — indeed, everything
guage in your document? Simple: select one might hope to cause them to obstruct
the appropriate language, and do the same the reading process. In particular, Lam-
as above: port invented LaTeX (silly enough in itself,
with a raised small ‘A’ and a lowered ‘E’)
\usepackage[french]{babel}
and marketing input from Addison-Wesley
\selectlanguage{french}
led to the even stranger current logo for
\hyphenation{re-cher-cher}
LaTeX2e, which appends a lowered ε.
(nothing clever here: this is the “correct” Sensible users don’t have to follow this
hyphenation of the word, in the current ta- stuff wherever it goes, but, for those who
bles). However, there’s a problem here: insist, a large collection of logos is defined
just as words with accent macros in them in the texnames package (but note that this
won’t break, so an \hyphenation com- set of macros isn’t entirely reliable in La-
mands with accent macros in its argument TeX2e). The Metafont and Metapost logos
will produce an error: can be set in fonts that LaTeX2e knows
about (so that they scale with the surround-
\usepackage[french]{babel} ing text) using the mflogo package; but be
\selectlanguage{french} aware that booby-traps surround the use
\hyphenation{r\’e-f\’e-rence} of the Knuthian font for Metapost (you
172
might get META O T). You needn’t de- tures so that you can use the fonts within
spair, however — most versions of the logo LaTeX.
font distributed nowadays contain the miss- Another alternative is to use the EC
ing letters, and the author himself uses just fonts, which come with bold variants of
‘MetaPost’. the small-caps fonts.
A well-designed set of macros is pro- If you need to use Type 1 fonts, you
vided by package hologo, which defines a can’t proceed with Knuth-style fonts, since
command \hologo, which one uses as (for there are no Type 1 versions of the mf-extra
example) \hologo{pdfLaTeX} for what set. There are, however, Type 1 distribu-
you might get by typing “pdf\LaTeX”, tions of the EC fonts, so you can switch
as well as a capitalised version \Hologo to EC and use them; alternatives are dis-
{pdfLaTeX} for “Pdf\LaTeX”. cussed in 8-bit Type 1 fonts.
The package metalogo deals with a Of course, commercial fixed-width
problem of these myriad logos, that’s often fonts (even the default Courier) almost al-
ignored nowadays: the geometry of char- ways come with a bold variant, so that’s
acters from different fonts is (obviously) not a problem. Furthermore PSNFSS will
different, and they naturally fit together dif- usually provide “faked” small caps fonts,
ferently. The package makes it possible for and has no compunctions about providing
you to adjust the spacing between the the them in a bold form. Courier is (as we
letters of one of these odd logos (even the all know, to our cost) freely available; a
especially weird mirrored “E” in XeTeX). far more presentable monospace font is
For those who don’t wish to acquire LuxiMono, which is also freely available
the ‘proper’ logos, the canonical thing to (monospace text in the typeset version of
do is to say AMS-\TeX{} for AMSTeX, this FAQ uses LuxiMono, with the met-
Pic\TeX{} for PiCTeX, Bib\TeX{} for rics and LaTeX support available on the
BibTeX, and so on. archive.
hologo.sty : Distributed as part of bold-extra.sty :
macros/latex/contrib/oberdiek macros/latex/contrib/bold-
metalogo.sty : extra
macros/latex/contrib/metalogo bold tt and small caps fonts:
mflogo.sty : fonts/cm/mf-extra/bold
macros/latex/contrib/mflogo LuxiMono fonts: fonts/LuxiMono
texnames.sty :
317 Automatic sizing of minipage
info/biblio/texnames.sty
The minipage environment requires you
316 How to do bold-tt or bold-sc to specify the width of the “page” you’re
LaTeX, as delivered, offers no means of going to create. This is sometimes inconve-
handling bold “teletype” or small-caps nient: you would like to occupy less space,
fonts. There’s a practical reason for this if possible, but minipage sets a box that is
(Knuth never designed such fonts), but exactly the width you specified.
there are typographical considerations too The pbox package defines a \pbox
(the “medium weight” cmtt font is al- whose width is exactly that of the
ready pretty bold (by comparison with longest enclosed line, subject to a max-
other fixed-width fonts), and bold small- imum width that you give it. So while
caps is not popular with many professional \parbox{2cm}{Hello\\world!} pro-
typographers). duces a box of width exactly 2cm, \pbox
There’s a set of “extra” Metafont files {2cm}{Hello\\world!} produces one
on CTAN that provide bold versions of whose width is 1.79cm (if one’s using the
both cmtt and cmcsc (the small caps font). default cmr font for the text, at least). The
With modern TeX distributions, one may package also provides a \settominwidth
bring these fonts into use simply by placing [min]{length}{text} (which looks (al-
them in an appropriate place in the texmf most) like the standard \settowidth com-
tree (these are (La)TeX-specific files, so mand), and a \widthofpbox function anal-
the “public” supplier would be an appro- ogous to the \widthof command for use
priate place). Once you’ve rebuilt the file with the calc package.
indexes as necessary, TeX (and friends) The eqparbox package extends pbox’s
will automatically build whatever font files idea, by allowing you to set a series of
they need when you first make reference to boxes, all with the same (minimised) width.
them. There’s a jiffy package bold-extra (Note that it doesn’t accept a limiting max-
that builds the necessary font data struc- imum width parameter.) The package doc-
173
umentation shows the following example cover fonts which duplicate symbols — an
drawn from a joke curriculum vitae: issue which is discussed in “symbol al-
ready defined”. Some font sets (for exam-
\noindent% ple the related set: FdSymbol, MdSymbol
\eqparbox{place}{\textbf{Widgets, andInc.}}
MnSymbol) \hfill
are huge, and the accompa-
\eqparbox{title}{\textbf{Senior nying Widget Designer}}
macros cover so many \hfill
symbols that
\eqparbox{dates}{\textbf{1/95--present}}name clashes are surely a serious problem.
The pifont package (originally de-
... signed to use the Adobe Zapf Dingbats
font) avoids this sort of problem: it re-
\noindent% quires you to know the font position of
\eqparbox{place}{\textbf{Thingamabobs, any symbol Ltd.}} \hfill
you want to use (the documen-
\eqparbox{title}{\textbf{Lead Engineer}} \hfill
tation provides font tables). The basic com-
\eqparbox{dates}{\textbf{9/92--12/94}} mand is \ding{number} for a single sym-
The code makes the three items on each bol; there are commands for other fancier
of the heading lines have exactly the same uses. Pifont also allows you to select other
width, so that the lines as a whole produce fonts, for similar use.
a regular pattern down the page. A com- The yagusylo describes itself as “an
mand \eqboxwidth allows you to use the extended version of pifont, gone techni-
measured width of a group: the documenta- color”. It provides all the facilities of
tion shows how the command may be used pifont, but allows you to create your own
to produce sensible-looking columns that mnemonic names for symbols. Thus, while
mix c-, r- or l-rows, with the equivalent of you can say \yagding[family]{symbol
a p{...} entry, by making the fixed-width number}[colour], you can also define
rows an eqparbox group, and making the symbol names with \defdingname, and
last from a \parbox using the width that’s then use them with \yagding*{symbol
name} (the defined name carries the font
been measured for the group.
The varwidth package defines a family and colour specified in the argu-
varwidth environment which sets the con-
ments of \defdingname).
tent of the box to match a “narrower nat- Yagusylo is somewhat complicated, but
ural width” if it finds one. (You give it its documentation is clear; it is probably
the same parameters as you would give the best tool to use for picking and choos-
minipage: in effect, it is a ‘drop-in’ re-
ing symbols from a variety of font families.
placement.) Varwidth provides its own FdSymbol fonts: fonts/fdsymbol
ragged text command: \narrowragged, MdSymbol fonts: fonts/mdsymbol
which aims to make narrower lines and
MnSymbol fonts: fonts/mnsymbol
to put more text in the last line of the
paragraph (thus producing lines with more pifont.sty : Distributed as part of
nearly equal lengths than typically happens macros/latex/required/psnfss
with \raggedright itself). yagusylo.sty :
The documentation (in the package macros/latex/contrib/yagusylo
file) lists various restrictions and things
still to be done, but the package is already 319 Symbols for the number sets
proving useful for a variety of jobs. Mathematicians commonly use special let-
eqparbox.sty : tering for the real numbers and other stan-
macros/latex/contrib/eqparbox dard number sets. Traditionally these were
typeset in bold. In the ordinary course of
pbox.sty :
events, but mathematicians do not have ac-
macros/latex/contrib/pbox
cess to bold chalk, so they invented special
varwidth.sty : symbols that are now often used for the
macros/latex/contrib/varwidth number sets. Such symbols are known as
“blackboard bold” (or double-stroked) let-
ters; in place of the heavier strokes of a
Q Symbols, etc. bold font, (some) strokes of the letters are
doubled. The minimum useful set is upper-
318 Using symbols case letters ‘I’, ‘N’, ‘R’, ‘Q’ and ‘Z’; some
Most symbol font sets come with a pack- fonts offer a figure ‘1’ (for a unit matrix —
age that defines commands for every sym- not a number set at all).
bol in the font. While this is convenient, A set of blackboard bold capitals is
it can lead to difficulties, particularly with available in the AMS msbm fonts (msbm
name clashes when you load packages that is available at a range of design sizes, with
174
names such as msbm10). The AMS actu- The “lazy person’s” blackboard bold
ally provides a pair of font families (the macros:
other is called msam), which offer a large
number of mathematical symbols to sup- \newcommand{\R}{{\textsf{R}\hspace*{-0.9ex}%
plement those provided in Knuth’s fonts. \rule{0.15ex}{1.5ex}\hspace*{0.9ex}}}
The fonts are available in Type 1 format \newcommand{\N}{{\textsf{N}\hspace*{-1.0ex}%
in modern distributions. Support for us- \rule{0.15ex}{1.3ex}\hspace*{1.0ex}}}
ing the fonts under LaTeX is available in \newcommand{\Q}{{\textsf{Q}\hspace*{-1.1ex}%
packages amssymb and amsfonts. The font \rule{0.15ex}{1.5ex}\hspace*{1.1ex}}}
shape is a rather austere sans, which many \newcommand{\C}{{\textsf{C}\hspace*{-0.9ex}%
people don’t like (though it captures the \rule{0.15ex}{1.3ex}\hspace*{0.9ex}}}
essence of quickly-chalked writing rather
are almost acceptable at normal size if the
well).
surrounding text is cmr10 (the position of
The bbold family is set of blackboard
the vertical bar can be affected by the sur-
bold fonts written in Metafont. This set of-
rounding font). However, they are not part
fers blackboard bold forms of lower-case
of a proper maths font, and do not work
letters; the font source directory also con-
in sub- and superscripts. As we’ve seen,
tains sources for a LaTeX package that en-
there are plenty of alternatives: that mythi-
ables use of the fonts. The fonts are not
cal “lazy” person can inevitably do better
available in Type 1 format.
than the macros, or anything similar us-
The bbm family claims to provide ing capital ‘I’ (which looks even worse!).
‘blackboard’ versions of most of the cm Voluntary (La)TeX effort has redefined the
fonts . . . including the bold and bold- meaning of laziness (in this respect!).
extended series. Again, the fonts are de-
signed in Metafont and are not available AMS support files: Distributed as part
in Type 1 format. LaTeX macro support of fonts/amsfonts
comes from a package by Torsten Hilbrich. AMS symbol fonts: Distributed as part
The doublestroke family comes in just of fonts/amsfonts
roman and sans shapes, at a single weight,
bbm fonts: fonts/cm/bbm
and is available both as Metafont sources
and as Type 1; the font covers the upper- bbm macros:
case latin letters, lowercase ‘h’ and ’k’, and macros/latex/contrib/bbm
the digit ‘1’. bbold fonts: fonts/bbold
A document that shows the bbm, bbold,
blackboard evaluation set:
doublestroke and msbm fonts, so that you
info/symbols/blackboard
can get a feel for their appearance, is avail-
able (CTAN package blackboard). doublestroke fonts:
The boondox font set consists of fonts/doublestroke
Type 1 versions of the STIX mathe- fourier fonts: fonts/fourier-GUT
matics set (the originals are distributed
in OTF format). The set contains a mathpazo fonts: fonts/mathpazo
font ‘BOONDOXDoubleStruck-Regular’ newpx : fonts/newpx
(blackboard bold) (as well as a ‘bold’ ver-
newtx : fonts/newtx
sion of that.
An alternative source of Type 1 fonts pxfonts: fonts/pxfonts
with blackboard bold characters may be txfonts: fonts/txfonts
found in the steadily increasing set of
complete families, both commercial and 320 Better script fonts for maths
free, that have been prepared for use with The font selected by \mathcal is the only
(La)TeX (see choice of outline fonts). Of script font ‘built in’. However, there are
the free sets, the txfonts and pxfonts fam- other useful calligraphic fonts included
ilies both come with replicas of msam with modern TeX distributions.
and msbm, but (as noted elsewhere, there
are other reasons not to use these fonts); Euler The eucal package (part of most
revised versions of the fonts, newtx and sensible TeX distributions; the fonts
newpx are better adjusted. The mathpazo are part of the AMS font set) gives a
family includes a “mathematically signifi- slightly curlier font than the default.
cant” choice of blackboard bold characters, The package changes the font that is
and the fourier fonts contain blackboard selected by \mathcal.
bold upper-case letters, the digit ‘1’, and Type 1 versions of the fonts are avail-
lower-case ‘k’. able in the AMS fonts distribution.
175
mathabx The mathabx bundle provides eucal.sty : Distributed as part of
calligraphic letters (in both upper and fonts/amsfonts
lower case); the fonts were developed euler fonts: Distributed as part of
in MetaFont, but a version in Adobe fonts/amsfonts
Type 1 format is available. The bun-
mathabx as Metafont: fonts/mathabx
dle’s documentation offers a series
of comparisons of its calligraphic set mathabx in Type 1 format:
with Computer Modern’s (both regu- fonts/ps-type1/mathabx
lar mathematical and calligraphic let- mathrsfs.sty : Distributed as part of
ters); the difference are not large. macros/latex/contrib/jknappen
mnsymbol The mnsymbol bundle pro-
mnsymbol fonts: fonts/mnsymbol
vides (among many other symbols)
a set of calligraphic letters, though rsfs fonts: fonts/rsfs
(again) they’re rather similar to the de- rsfso fonts: fonts/rsfso
fault Computer Modern set. Script font examples: info/
RSFS The mathrsfs package uses a really symbols/math/scriptfonts.pdf
fancy script font (the name stands for
“Ralph Smith’s Formal Script”) which TeX Gyre Chorus font family :
is already part of most modern TeX Distributed as part of
distributions (Type 1 versions of the fonts/tex-gyre
font are also provided, courtesy of urwchancal: fonts/urwchancal
Taco Hoekwater). The package cre- URW Chancery L: Distributed as part of
ates a new command \mathscr. fonts/urw/base35
RSFSO The bundle rsfso provides a less
dramatically oblique version of the 321 Setting bold Greek letters in
RSFS fonts; the result proves quite LaTeX maths
pleasing — similar to the effect of The issue here is complicated by the fact
the the (commercial) script font in the that \mathbf (the command for setting
Adobe Mathematical Pi collection. bold text in TeX maths) affects a select
Zapf Chancery is the standard PostScript few mathematical ‘symbols’ (the upper-
calligraphic font. There is no package case Greek letters).
but you can easily make it available In the default configuration, lower-
by means of the command case Greek letters behave differently from
upper-case Greek letters (the lower-case
\DeclareMathAlphabet{\mathscr}{OT1}{pzc}{m}{it}
greek letters are in the maths fonts, while
in your preamble. You may find the the upper-case letters are in the original
font rather too big; if so, you can use (OT1-encoded) text fonts).
a scaled version of it like this: The Plain TeX solution does work, in a
\DeclareFontFamily{OT1}{pzc}{} limited way; you set a maths style, before
you
\DeclareFontShape{OT1}{pzc}{m}{it}{<-> start an equation;
s thus pzcmi7t}{}
[0.900]
*
\DeclareMathAlphabet{\mathscr}{OT1}{pzc}{m}{it}
{\boldmath$\theta$}
Adobe Zapf Chancery (which the does the job, but \boldmath may not be
above examples use) is distributed used in maths mode. As a result, this so-
in any but the most basic PostScript lution requires that you embed single bold
printers. A substantially identical characters in a text box:
font (to the extent that the same met-
rics may be used) is available from $... \mbox{\boldmath$\theta$} ...$
URW, called URW Chancery L: it which then causes problems in super-
is distributed as part of the “URW scripts, etc. With amsmath loaded,
base35” bundle; the urwchancal pack-
age (which includes virtual fonts to $... \text{\boldmath$\theta$} ...$
tweak appearance) provides for its use does the trick (and is less bad in regard to
as a calligraphic font. superscripts, etc), but is an unsatisfactory
The TeX Gyre font family also solution, too.
includes a Chancery replacement, These problems may be addressed by
Chorus; use it with tgchorus (and ig- using a bold mathematics package.
nore the complaints about needing to
change font shape). • The bm package, which is part of the
LaTeX tools distribution, defines a
Examples of the available styles are linked command \bm which may be used any-
from the packages’ catalogue entries. where in maths mode.
176
 • The amsbsy package (which is part There is a problem, though: OT1 text
of AMSLaTeX) defines a command fonts don’t contain an underscore charac-
\boldsymbol, which (though slightly ter, unless they’re in the typewriter version
less comprehensive than \bm) covers of the encoding (used by fixed-width fonts
almost all common cases. such as cmtt). In place of such a charac-
ter, LaTeX (in OT1 encoding) uses a short
All these solutions apply to all mathe-
rule for the command \textunderscore,
matical symbols, not merely Greek letters.
but this poses problems for systems that
bm.sty : Distributed as part of interpret PDF — for example those PDF-
macros/latex/required/tools to-voice systems used by those who find
amsbsy.sty : Distributed as part of reading difficult.
AMSLaTeX macros/latex/ So either you must ensure that your un-
required/amslatex derscore characters only occur in text set in
amsmath.sty : Distributed as part a typewriter font, or you must use a more
of AMSLaTeX macros/latex/ modern encoding, such as T1, which has
required/amslatex the same layout for every font, and thus an
underscore in every font.
322 The Principal Value Integral A stable procedure to achieve this is:
symbol
% (1) choose a font that is available as T1
This symbol (an integral sign, ‘crossed’) % for example:
does not appear in any of the fonts ordinar- \usepackage{lmodern}
ily available to (La)TeX users, but it can
be created by use of the following macros: % (2) specify encoding
\def\Xint#1{\mathchoice \usepackage[T1]{fontenc}
{\XXint\displaystyle\textstyle{#1}}%
{\XXint\textstyle\scriptstyle{#1}}% % (3) load symbol definitions
\usepackage{textcomp}
{\XXint\scriptstyle\scriptscriptstyle{#1}}%
{\XXint\scriptscriptstyle\scriptscriptstyle{#1}}%
which will provide a command
\!\int}
\textunderscore which robustly selects
\def\XXint#1#2#3{{\setbox0=\hbox{$#1{#2#3}{\int}$}
the right character. The underscore pack-
\vcenter{\hbox{$#2#3$}}\kern-.5\wd0}}
age, mentioned above, will use this com-
\def\ddashint{\Xint=}
mand.
\def\dashint{\Xint-}
underscore.sty : macros/latex/
\dashint gives a single-dashed integral contrib/underscore
sign, \ddashint a double-dashed one.
324 How to type an ‘@’ sign?
323 How to typeset an underscore
character Long ago, some packages used to use the
‘@’ sign as a special character, so that
The underscore character ‘_’ is ordinar- special measures were needed to type it.
ily used in TeX to indicate a subscript in While those packages are still in princi-
maths mode; if you type _, on its own, in ple available, few people use them, and
the course of ordinary text, TeX will com- those that do use them have ready access
plain. The “proper” LaTeX command for to rather good documentation.
underscore is \textunderscore, but the Ordinary people (such as the author of
LaTeX 2.09 command \_ is an established this FAQ) need only type ‘@’.
alias. Even so, if you’re writing a docu-
ment which will contain a large number 325 Typesetting the Euro sign
of underscore characters, the prospect of The European currency “Euro” (C) is rep-
typing \_ for every one of them will daunt resented by a symbol of somewhat dubious
most ordinary people. design, but it’s an important currency and
Moderately skilled macro program- (La)TeX users need to typeset it. When the
mers can readily generate a quick hack currency first appeared, typesetting it was a
to permit typing ‘_’ to mean ‘text under- serious problem for (La)TeX users; things
score’ (the answer in “defining characters are easier now (most fonts have some way
as macros” uses this example to illustrate of providing a Euro sign), but this answer
its techniques). However, the code is some- provides a summary of methods “just in
what tricky, and more importantly there case”.
are significant points where it’s easy to Note that the Commission of the Euro-
get it wrong. There is therefore a pack- pean Community at first deemed that the
age underscore which provides a general Euro symbol should always be set in a sans-
solution to this requirement. serif font; fortunately, this eccentric ruling
177
has now been rescinded, and one may ap- bet for use in non-Computer Modern en-
ply best typesetting efforts to making it vironments. They are apparently designed
appear at least slightly “respectable” (typo- to fit with Adobe Times, Helvetica and
graphically). Courier, but can probably fit with a wider
The TS1-encoded TC fonts provided range of modern fonts.
as part of the EC font distribution provide The eurofont package provides a com-
Euro glyphs. The fonts are called Text pendious analysis of the “problem of the
Companion (TC) fonts, and offer the same euro symbol” in its documentation, and of-
range of faces as do the EC fonts them- fers macros for configuring the source of
selves. The textcomp package provides the glyphs to be used; however, it seems
a \texteuro command for accessing the rather large for everyday use.
symbol, which selects a symbol to match The euro-ce bundle is a rather pleas-
the surrounding text. The design of the ing Metafont-only design providing Euro
symbol in the TC fonts is not universally symbols in a number of shapes. The file
loved. . . Nevertheless, use the TC font ver- euro-ce.tex, in the distribution, offers
sion of the symbol if you are producing hints as to how a Plain TeX user might
documents using Knuth’s Computer Mod- make use of the fonts.
ern Fonts. Euro symbols are found in several
The each of the latin9 and latin10 input other places, which we list here for com-
encoding definitions for the inputenc pack- pleteness.
age has a euro character defined (character The marvosym font contains a Euro
position 164, occupied in other ISO Latin symbol (in a number of typographic styles),
character sets by the “currency symbol” ¤, among many other good things; the font is
which ordinary people seldom see except available in both Adobe Type 1 and True-
in character-set listings. . . ). The TC encod- Type formats.
ing file offers the command \texteuro for Other Metafont-based bundles con-
the character; that command is (probably) taining Euro symbols are to be found
only available from the textcomp package. in china2e (whose primary aim is Chi-
Use of the TC encoding character may nese dates and suchlike matters) and the
therefore made via \texteuro or via the eurosym fonts.
Latin-9 or Latin-10 character in ordinary china2e bundle:
text. macros/latex/contrib/china2e
Note that there is a Microsoft code EC fonts: fonts/ec
page position (128), too, and that has
been added to inputenc tables for CP1252 euro fonts: fonts/euro
and CP1257. (There’s another position in euro-ce fonts: fonts/euro-ce
CP858, which has it in place of “dotless eurofont.sty :
i” in CP850; the standardisation of these macros/latex/contrib/eurofont
things remains within Microsoft, so one
can never tell what will come next. . . ) eurosym fonts: fonts/eurosym
Outline fonts which contain nothing marvosym fonts: fonts/marvosym
but Euro symbols are available (free) from textcomp.sty : Part of the LaTeX
Adobe — the file is packaged as a Windows distribution.
self-extracting executable, but it may be
decoded as a .zip format archive on 326 How to get copyright, trademark,
other operating systems. The euro bun- etc.
dle contains metrics, dvips map files, and The “Comprehensive symbol list” (Com-
macros (for Plain TeX and LaTeX), for prehensive symbol list), lists the
using these fonts in documents. LaTeX symbol commands \textcopyright,
users will find two packages in the bun- \textregistered and \texttrademark,
dle: eurosans only offers the sans-serif which are available in TS1-encoded fonts,
version (to conform with the obsolete rul- and which are enabled using the textcomp
ing about sans-serif-only symbols; the package.
package provides the command \euro), In fact, all three commands are en-
whereas europs matches the Euro symbol abled in default LaTeX, but the glyphs
with the surrounding text (providing the you get aren’t terribly beautiful. In par-
command \EUR). To use either package ticular, \textregistered behaves oddly
with the latin9 encoding, you need to de- when included in bold text (for example,
fine \texteuro as an alias for the euro in a section heading), since it is composed
command the package defines. of a small-caps letter, which typically de-
The Adobe fonts are probably the best grades to a regular shape letter when asked
178
to set in a bold font. This means that the lm family offers old-style figures to Open-
glyph becomes a circled “r”, whereas the Type users (see below), but we have no
proper symbol is a circled “R”. stable mapping for lm with old-style dig-
This effect is of course avoided by use its from the Adobe Type 1 versions of the
of textcomp. fonts.
Another problem arises if you want Originally, oldstyle figures were only
\textregistered in a superscript posi- to be found the expert sets of commercial
tion (to look similar to \texttrademark). fonts, but now they are increasingly widely
Using a maths-mode superscript to do this available. An example is Matthew Carter’s
provokes lots of pointless errors: you must Georgia font, which has old-style figures
use as its normal form (the font was created for
inclusion with certain Microsoft products
\textsuperscript{\textregistered}
and is intended for on-screen viewing).
327 Using “old-style” figures OpenType fonts have a pair of axes for
number variations — proportional/tabular
These numbers are also called medieval or
and lining/oldstyle selections are com-
lowercase figures and their use is mostly
monly available. “Full feature access”
font-specific. Terminology is confusing
to OpenType fonts, making such options
since the lining figures (which are now the
available to the (La)TeX user, is already
default) are a relatively recent development
supported by XeTeX using, for example,
(19th century) and before they arrived, old-
the fontspec package. Similar support is
style figures were the norm, even when set-
also in the works for LuaTeX.
ting mathematics. (An example is Thomas
Harriot’s Artis Analyticae Praxis published boondox fonts: fonts/boondox
in 1631). In a typical old style 3, 4, 5, 7 cmolddig fonts: fonts/cmolddig
and 9 have descenders and 6 and 8 ascend eco fonts: fonts/eco
above the x-height; sometimes 2 will also
ascend (this last seems to be a variation fontinst:
fonts/utilities/fontinst
associated with French typography).
LaTeX provides a command fontspec.sty :
\oldstylenums{digits}, which by de- macros/latex/contrib/fontspec
fault uses an old-style set embedded in mathpazo fonts: fonts/mathpazo
Knuth’s ‘math italic’ font. The command
is only sensitive to ‘bold’ of the font style
of surrounding text: glyphs (for this com- R Macro programming
mand) are only available to match the nor-
mal medium and bold (i.e., bold-extended) R.1 “Generic” macros and
weights of the Computer Modern Roman techniques
fonts.
328 Non-letters in macro names
The textcomp package changes
\oldstylenums to use the glyphs in the New LaTeX users are often suprised that
Text Companion fonts (LaTeX TS1 en- macro definitions containing non-letters,
coding) when in text mode, and also such as
makes them available using the macros of \newcommand{\cul8r}{Goodbye!}
the form \text<number>oldstyle, e.g.,
fail to compile. The reason is that the TeX
\textzerooldstyle. (Of course, not all
macro language, unlike most programming
font families can provide this facility.)
languages, allows nothing but letters in
Some font packages (e.g., mathpazo)
macro names.
make old-style figures available and pro-
There are a number of techniques for
vide explicit support for making them the
defining a macro with a name like \cul8r.
default: \usepackage[osf]{mathpazo}
Unfortunately, none of the techniques is
selects a form where digits are always old-
particularly good:
style in text. The fontinst package will
automatically generate “old-style versions” 1. Use \csname. . . \endcsname to de-
of commercial Adobe Type 1 font families fine and invoke the macro:
for which “expert” sets are available. \expandafter\newcommand\csname cul8r\endcsname{Goodb
It’s also possible to make virtual fonts, I said, ‘‘\csname cul8r\endcsname’’.
that offer old-style digits, from existing
font packages. The cmolddig bundle pro- Pro: No unexpected side effects
vides a such a virtual version of Knuth’s Con: So verbose as to be unusable
originals, and the eco or hfoldsty bundles 2. Define a “special-command genera-
both provide versions of the EC fonts. The tor”, and use the resulting commands:
179
 convention is to use “@” within the names
\newcommand{\DefineRemark}[2]{%
of internal
\expandafter\newcommand\csname macros to hide them from the
rmk-#1\endcsname{#2}%
} user and thereby prevent naming conflicts.
To this
\newcommand{\Remark}[1]{\csname end, LaTeX automatically treats
rmk-#1\endcsname}
... “@” as a letter while processing classes and
packages and as a non-letter while process-
\DefineRemark{cul8r}{Goodbye!}
... ing the user’s document. The key to this
\Remark{cul8r} technique is the separation: internally a
non-letter is used for macro names, and
Pro: Straightforward to use, not too
the user doesn’t see anything of it, while
untidy
the status remains “frozen” in all the defi-
Con: It’s hardly doing what we set
nitions created within the class or package.
out to do (experts will see that you
See \@ and @ in macro names for more
are defining a macro, but others
information.
likely won’t)
Note that analogous use of technique 3
3. Convince TeX that “8” is a letter: in this example would give us
\catcode‘8 = 11
\begingroup
\newcommand{\cul8r}{Goodbye!}
\catcode‘8 = 11
I said, ‘‘\cul8r’’.
\gdef\cul8r{Goodbye!}
Pro: \cul8r can be used directly \gdef\later{\cul8r}
Con: Likely to break other uses of “8” \endgroup
(such as numbers or dimensions; I said, ‘‘\later’’.
so \setlength{\paperwidth}
{8in} tells us: which works, but rather defeats the object
of the exercise. (\later has the “frozen”
! Missing number, treated as zero.
catcode for ‘8’, even though the value has
<to be read again>
reverted to normal by the time it’s used;
8
note, also, the use of the primitive com-
As a general rule, changing category mand \gdef, since \newcommand can’t
codes is something to use in extremis, make a macro that’s available outside the
after detailed examination of options. group.)
It is conceivable that such drastic ac- Recommendation: Either choose
tion could be useful for you, but most another mechanism (such as
ordinary users are well advised not \DefineRemark above), or choose another
even to try such a technique. name for your macro, one that contains
4. Define a macro \cul which must al- only ordinary letters. A common approach
ways be followed by “8r”: is to use roman numerals in place of arabic
\def\cul8r{Goodbye!} ones:
I said, ‘‘\cul8r’’.
\newcommand{\culVIIIr}{Goodbye!}
Pro: \cul8r can be used directly
Con #1: Breaks if \cul is followed which rather spoils the intent of the joke
by anything other than “8r”, with implicit in the example \cul8r!
a confusing diagnostic — \cul99
produces: 329 Repeating a command n times
! Use of \cul doesn’t matchTeX itswas not designed as a programming
definition.
<*> \cul9 language, but there are occasions when
9 you want to repeat some part of your doc-
(which would confuse someone ument, just as parts of programs need to
who hadn’t even realised there was run several times. An obvious example is
a definition of \cul in the docu- TeX-based drawing: LaTeX’s picture en-
ment). vironment and pgf (at least) provide repeat
Con #2: Silently redefines existing facilities — they are useful for drawing re-
\cul, if any; as a result, the tech-
peating patterns. As a result, “common”
nique cannot be used to define programming techniques often have to be
both a \cul8r and, say, a \cul123 emulated using obscure macro TeXniques.
macro in the same document. This answer deals with repeating an op-
eration a given number of times; repeating
Technique 3 is in fact commonly used — operations once for each of a set of objects
in a limited form — within most LaTeX is dealt with in the answer repeating “over
packages and within LaTeX itself. The a set”.
180
 Plain TeX itself provides a \loop . . . \thect\
\repeat contruct, which enables you to }
repeat a command (or set of commands).
The syntax is simple enough, but it use of as you can see, the arguments are counter,
TeX conditionals is different enough that starting value and termination condition;
many people find it confusing. an optional argument supplies a step value
(default step is 1).
\newcount\foo The LaTeX picture environment has
\foo=10 a simple command for repeated drawing:
\loop
\message{\the\foo} \multiput(x,y)(xstep,ystep){n}{obj}
\advance \foo -1
\ifnum \foo>0 which places hobji (intended to be a bit of
\repeat picture) hni times at positions (hxi, hyi),
(hxi+hxstepi, hyi+hystepi), (hxi+2hxstepi,
In this slightly tricky code, \loop starts the hyi+2hystepi) and so on, adding the dis-
construct ended by \repeat, but \repeat placement again each time. The command
also “serves as” the \fi to the \ifnum. was designed for use in picture, but it
The loop above prints the numbers from makes no check, and may even be used to
10 down to 1 via TeX \message (i.e., on provide eccentric typesetting in a “regular”
the console output). sentence, such as:
The multido package is also ‘generic’
(usable both in Plain TeX and latex); it Here \multiput(0,0)(1,1){3}{we} are again.
defines a command \multido with three
arguments: with predictable (if not actually desirable)
effect. It may be used with nothing but
\multido{hvariablesi} an iterative calculation in the braced argu-
{hrepetitionsi}{hstuff to ment, in which case its graphical capabili-
repeati} ties have no effect.
When the macro is executing, the hstuff to The pgffor package, which is part of
repeati gets executed hrepetitionsi times; the pgf distribution, also provides itera-
the hvariablesi gives a list of variables that tions to support the needs of graphics. Its
can be used in hstuff i. Each variable is syntax is in the style of common program-
a composite of a command sequence and ming languages:
how it varies; so a variable “\iz=2+4” sets
\usepackage{pgffor}
\iz to 2 first time around, then 6 and 10
\newcommand{\cmd}{-x-}
in the next two iterations, and so on. (The
...
variable \iz is an integer; variables with
\foreach \n in {1,...,4}{\cmd{}}
other initial letters represent different data
types.) typesets “-x--x--x--x-”
Both current LaTeX and (experimen-
The \foreach command has the po-
tal) LaTeX3 have iteration commands for
tential drawback that its repeated unit is
internal use and for package writers; their
executed in a group, so that any calcula-
use is probably not recommendable.
tions done within the loop are lost (unless
The LaTeX distribution package ifthen
their result is made \global); however, it
offers the macro \whiledo:
does not ‘build in’ its graphical origins (as
\newcounter{ct} \multiput does) so its potential outside
... its own graphics environment “home” is
\setcounter{ct}{1} more clear.
\whiledo {\value{ct} < 5}%
forarray.sty :
{%
macros/latex/contrib/forarray
\thect\
\stepcounter {ct}% forloop.sty :
} macros/latex/contrib/forloop

ifthen.sty : Distributed as part of

The forloop package provides nothing
macros/latex/base
but \forloop:
multido.sty :
\newcounter{ct}
macros/generic/multido
...
\forloop{ct}{1}{\value{ct} < 5}%pgffor.sty : Distributed as part of
{% graphics/pgf/base
181
330 Repeating something for each datatool.sty :
‘thing’ in a set macros/latex/contrib/datatool
As another question (repeating something dowith.sty : macros/generic/dowith
a given number of times) explains, TeX etoolbox.sty :
is not explicitly designed for ‘regular’ pro- macros/latex/contrib/etoolbox
gramming operations. As a result, we must
filesdo.sty : Distributed with
resort to arcane tricks to do the seemingly
macros/generic/commado
simple task of repeating an operation. This
answer deals with repeating an operation 331 Finding the width of a letter,
for each of a given set of objects. word, or phrase
The etoolbox package provides itera- Put the word in a box, and measure the
tion over a comma-separated list of items, width of the box. For example,
in its \docsvlist and \forcsvlist com-
mands; they are well-described in the pack- \newdimen\stringwidth
age documentation. The datatool pack- \setbox0=\hbox{hi}
age manages “databases” (of its own defi- \stringwidth=\wd0
nition) and you may iterate over entries Note that if the quantity in the \hbox is
in such a database using the command a phrase, the actual measurement only ap-
\DTLforeach. proximates the width that the phrase will
The forarray package defines its own occupy in running text, since the inter-
“list” and “array” structures, together with word glue can be adjusted in paragraph
commands \ForEach and \ForArray mode.
which enable a command to be executed The same sort of thing is expressed in
for each element in a list or array, respec- LaTeX by:
tively.
The dowith defines a pair of macros \newlength{\gnat}
\DoWith and \StopDoing that process \settowidth{\gnat}{\textbf{small}}
each “thing” between them; a trivial ex- This sets the value of the length command
ample of use is: \gnat to the width of “small” in bold-face
\usepackage{dowith} text.
... 332 Patching existing commands
\begin{document}
In the general case (possibly sticking some-
\newcommand{\foo}[1]{\message{#1+}
thing in the middle of an existing com-
\DoWith\foo a{BBB}c\StopDoing
mand) this is difficult. However, the com-
which produces terminal output: mon requirement, to add some code at the
beginning or the end of an existing com-
a+ BBB+ c+ mand, is conceptually quite easy. Suppose
we want to define a version of a command
so, the macros have found 3 “things”, in- that does some small extension of its origi-
cluding one with braces around it. (The nal definition: we would naturally write:
interpolated spaces come from the primi-
tive \message command.) \renewcommand{\splat}{\mumble\splat}
The only constraint is that all com- However, this would not work: a call to
mands in the enclosed stuff are “expand- \splat would execute \mumble, and then
able” (which means, for example, that you call the redefined \splat again; this is an
may not use commands with optional argu- ‘unterminated recursion’, that will quickly
ments). exhaust TeX’s memory.
From the same stable (as dowith) Fortunately, the TeX primitive \let
comes the package commado, that command comes to our rescue; it allows
provides commands \DoWithCSL (ap- us to take a “snapshot” of the current state
ply a command to each element of of a command, which we can then use in
a comma-separated-variable list) and the redefinition of the command. So:
\DoWithBasesExts (apply a command
to each of a set of files, defined by base \let\OldSmooth\smooth
name and “extension”). Use of these \renewcommand{\smooth}{\mumble\OldSmooth}
\DoWith* macros is also expandable (if effects the required patch, safely. Adding
the command applied to the list elements things at the end of a command works sim-
is itself expandable). ilarly.
commado.sty : If \smooth takes arguments, one must
macros/generic/commado pass them on:
182
 \let\OldSmooth\smooth \def\b{b}
\renewcommand{\smooth}[2]{\mumble\OldSmooth{#1}{#2}}
\patchcmd\b{a}{c}

The situation is more difficult still if we will have a new version of \b defined
\smooth takes an optional argument; the as “abc”.
structure of the command is so complex The ted package is a ‘token list editor’,
that the simple \let command does not and provides a command \substitute
retain the necessary detail. In this case, we which will patch the contents of a macro,
need the letltxmacro package which knows putting the result in a token-list, or (in the
about all sorts of LaTeX commands and form \Substitute*) using the result to
how to replicate them. Suppose we have a (re)define a macro. The following example
command defined as: defines a simple macro, and then changes
its definition:
\newcommand{\rough}[1][\default]{...}
\newcommand{\myfont}%
with an optional argument (substituted {\Large\sffamily\selectfont}
with \default if it’s not present) as well \Substitute*[\renewcommand{\myfont}]{\myfont}%
as an ordinary one. In this case we copy it {\Large\sffamily}{\huge\itshape}
using
The macro’s definition is now:
\LetLtxMacro{\NewRough}{\rough}
\huge\itshape\selectfont
and then repeat the technique we had
above, with one extension: The package also offers a command
\ShowTokens, which shows the content of
\renewcommand{\rough}[1][\newdef]%
its argument, one token to a line, with de-
{\mumble\OldRough[{#1}]{#2}}
tails of the token’s category code, etc. This
is recommended as a debugging tool.
We see here that (for tedious argument-
The etoolbox package (which provides
matching reasons) it is necessary to pro-
user access to e-TeX’s programming fa-
vide braces arround the optional argument
cilities) provides a command \patchcmd
that is being passed on.
which is very similar to \Substitute,
The general case may be achieved in
except that it only replaces a single in-
two ways. First, one can use the LaTeX
stance of the token(s) in its search pat-
command \CheckCommand; this compares
tern. Since not all commands may be
an existing command with the definition
patched in this way, \patchcmd takes
you give it, and issues a warning if two
extra arguments for success and failure
don’t match. Use is therefore:
cases. The package also provides com-
\CheckCommand{\complex}{horiginal mands that prepend (\pretocmd) or ap-
definitioni} pend (\apptocmd) to the definition of a
\renewcommand{\complex}{hnew command. Not all commands may be
definitioni} patched in this way; the package provides
a command \ifpatchable which checks
This technique is obviously somewhat the prerequisites, and checks that the tar-
laborious, but if the original command get command’s body does indeed include
comes from a source that’s liable to change the patch string you propose to use. (The
under the control of someone else, it does command \ifpatchable* omits the test
at least warn you that your patch is in dan- on the patch string.)
ger of going wrong. The regexpatch package deals with
Otherwise, LaTeX users may use one cases that are inaccessible with etoolbox;
of the patchcmd, ted or etoolbox packages. it uses the regular expression (pattern-
The patchcmd package addresses a matching) package l3regex from the La-
slightly simpler task, by restricting the set TeX3 distribution to find the code you need
of commands that you may patch; you to patch. The package also “knows about”
mayn’t patch any command that has an robust commands and about biblatex.
optional argument, though it does deal Finally, we’ll briefly consider a pack-
with the case of commands defined with age that is (just about) usable, but not
\DeclareRobustCommand. The package really recommendable. Patch gives you
defines a \patchcommand command, that an ingenious (and difficult to understand)
takes three arguments: the command to mechanism, and comes as an old-style La-
patch, stuff to stick at the front of its def- TeX documented macro file, which can no
inition, and stuff to stick on the end of its longer be processed to produce formatted
definition. So, after documentation, etc.. Fortunately, the file
183
(patch.doc) may be input directly, and 334 Is the argument a number?
“documentation” may found by reading the TeX’s own lexical analysis doesn’t offer
source of the package. Roughly speaking, the macro programmer terribly much sup-
one gives the command a set of instruc- port: while category codes will distinguish
tions analogous to sed substitutions, and letters (or what TeX currently thinks of
it regenerates the command thus amended. as letters) from everything else, there’s no
Unless you can’t do your job any other support for analysing numbers.
way, patch is best avoided. The simple-minded solution is to com-
etoolbox.sty : pare numeric characters with the characters
macros/latex/contrib/etoolbox of the argument, one by one, by a sequence
of direct tests, and to declare the argument
l3regex.sty : Distributed as part
“not a number” if any character fails all
of macros/latex/contrib/
comparisons:
l3experimental
\ifx1#1
letltxmacro.sty :
\else\ifx2#1
Distributed as part of
...
macros/latex/contrib/oberdiek
\else\ifx9#1
patch.doc: \else\isanumfalse
macros/generic/misc/patch.doc \fi\fi...\fi

patchcommand.sty : which one would then use in a tail-

macros/latex/contrib/patchcmd recursing macro to gobble an argument.
regexpatch.sty : macros/latex/ One could do slightly better by assum-
contrib/regexpatch ing (pretty safely) that the digits’ character
codes are consecutive:
ted.sty : macros/latex/contrib/ted
\ifnum‘#1<‘0 \isanumfalse
333 Comparing the “job name” \else\ifnum‘#1>‘9 \isanumfalse
\fi
The token \jobname amusingly produces \fi
a sequence of characters whose category
code is 12 (‘other’), regardless of what again used in tail-recursion. However,
the characters actually are. Since one in- these forms aren’t very satisfactory: get-
evitably has to compare a macro with the ting the recursion “right” is troublesome
contents of another macro (using \ifx, (it has a tendency to gobble spaces in the
somewhere) one needs to create a macro argument), and in any case TeX itself has
whose expansion looks the same as the ex- mechanisms for reading numbers, and it
pansion of \jobname. We find we can do would be nice to use them.
this with \meaning, if we strip the “\show Donald Arseneau’s cite package offers
command” prefix. the following test for an argument being a
The full command looks like: strictly positive integer:
\def\IsPositive#1{%
\def\StripPrefix#1>{}
TT\fi
\def\jobis#1{FF\fi
\ifcat_\ifnum0<0#1 _\else A\fi
\def\predicate{#1}%
}
\edef\predicate{\expandafter\StripPrefix\meaning\predicate}%
\edef\job{\jobname}% which can be adapted to a test for a non-
\ifx\job\predicate negative integer thus:
}
\def\IsNonNegative{%
And it’s used as: \ifcat_\ifnum9<1#1 _\else A\fi
}
\if\jobis{mainfile}%
\message{YES}% or a test for any integer:
\else \def\gobbleminus#1{\ifx-#1\else#1\fi}
\message{NO}% \def\IsInteger#1{%
\fi TT\fi
\ifcat_\ifnum9<1\gobbleminus#1 _\else A\fi
Note that the command \StripPrefix }
need not be defined if you’re using La-
TeX — there’s already an internal com- but this surely stretches the technique fur-
mand \strip@prefix that you can use. ther than is reasonable.
184
 If we don’t care about the sign, we can thus using TeX’s own integer-parsing code
use TeX to remove the entire number (sign to do the check. It’s a pity that such a mech-
and all) from the input stream, and then anism was never defined (it could be that
look at what’s left: it’s impossible to program within TeX!).
memoir.cls:
\def\testnum#1{\afterassignment\testresult\count255=0#1 \end}
macros/latex/contrib/memoir
\def\testresult#1\end{\ifx\end#1\end\isanumtrue\else\isanumfalse\fi}

(which technique is due to David Kastrup; 335 Defining macros within macros
the trick for avoiding the errors, noted in The way to think of this is that ## gets
an earlier version of this answer, was sug- replaced by # in just the same way that
gested by Andreas Matthias). In a later #1 gets replaced by ‘whatever is the first
thread on the same topic, Michael Downes argument’.
offered:
So if you define a macro:
\def\IsInteger#1{%
TT\fi \newcommand\a[1]{+#1+#1+#1+}
\begingroup \lccode‘\-=‘\0 \lccode‘+=‘\0
or (using the TeX primitive \def):
\lccode‘\1=‘\0 \lccode‘\2=‘\0 \lccode‘\3=‘\0
\lccode‘\4=‘\0 \lccode‘\5=‘\0 \lccode‘\6=‘\0
\def\a#1{+#1+#1+#1+}
\lccode‘\7=‘\0 \lccode‘\8=‘\0 \lccode‘\9=‘\0
\lowercase{\endgroup
and use it as \a{b}, the macro expan-
\expandafter\ifx\expandafter\delimiter
sion produces ‘+b+b+b+’, as most people
\romannumeral0\string#1}\delimiter
would expect.
}
However, if we now replace part of the
which relies on \romannumeral produc- macro:
ing an empty result if its argument is zero.
Sadly, this technique has the unfortunate \newcommand\a[1]{+#1+\newcommand\x[1]{xxx#1}}
property that it accepts simple expressions
such as ‘1+2-3’; this could be solved by an then \a{b} will give us the rather odd
initial \gobbleminus-like construction.
+b+\newcommand{x}[1]
All the complete functions above are
{xxxb}
designed to be used in TeX conditionals
written “naturally” — for example:
so that the new \x ignores its argument.
\if\IsInteger{<subject of test>}% If we use the TeX primitive:
<deal with integer>%
\else \def\a#1{+#1+\def\x #1{xxx#1}}
<deal with non-integer>%
\fi \a{b} will expand to ‘+b+\def\x b{xxxb}’.
This defines \x to be a macro delimited
The LaTeX memoir class has an internal by b, and taking no arguments, which is
command of its own, \checkifinteger surely not what was intended!
{num}, that sets the conditional command Actually, to define \x to take an argu-
\ifinteger according to whether the ar- ment, we need
gument was an integer.
Of course, all this kerfuffle would \newcommand\a[1]{+#1+\newcommand\x[1]{xxx##1}}
be (essentially) void if there was a sim-
ple means of “catching” TeX errors. or, using the TeX primitive definition:
Imagining an error-catching primitive
\ifnoerror, one might write: \def\a#1{+#1+\def\x ##1{xxx##1}}

\def\IsInteger#1{% and \a{b} will expand to

TT%
\ifnoerror +b+\def\x #1{xxx#1}
\tempcount=#1\relax
% carries on if no error because #1 gets replaced by ‘b’ and ## gets
\expandafter\iftrue replaced by #.
\else To nest a definition inside a definition
% here if there was an error inside a definition then you need ####1,
\expandafter\iffalse doubling the number of # signs; and at the
\fi next level you need 8 #s each time, and so
} on.
185
336 Spaces in macros nored, but may be overlooked if the ar-
It’s very easy to write macros that produce gument is well within the 2cm allowed
space in the typeset output where it’s nei- for it
ther desired nor expected. Spaces intro- • after the } closing the mandatory ar-
duced by macros are particularly insidi- gument of \makebox; this space will
ous because they don’t amalgamate with not be ignored
spaces around the macro (unlike consecu- The original author of the macro had been
tive spaces that you type), so your output concerned that the starts of his lines with
can have a single bloated space that proves this macro in them were not at the left
to be made up of two or even more spaces margin, and that the text appearing after
that haven’t amalgamated. And of course, the macro wasn’t always properly aligned.
your output can also have a space where These problems arose from the space at
none was wanted at all. the start of the mandatory argument of
Spaces are produced, inside a macro as \makebox and the space immediately af-
elsewhere, by space or tab characters, or ter the same argument. He had written his
by end-of-line characters. There are two macro in that way to emphasise the mean-
basic rules to remember when writing a ing of its various parts; unfortunately the
macro: first, the rules for ignoring spaces meaning was rather lost in the problems
when you’re typing macros are just the the macro caused.
same as the rules that apply when you’re The principal technique for suppress-
typing ordinary text, and second, rules for ing spaces is the use of % characters: ev-
ignoring spaces do not apply to spaces pro- erything after a % is ignored, even the end
duced while a macro is being obeyed (“ex- of line itself (so that not even the end of
panded”). line can contribute an unwanted space).
Spaces are ignored in vertical mode The secondary technique is to ensure that
(between paragraphs), at the beginning of the end of line is preceded by a command
a line, and after a command name. Since name (since the end of line behaves like a
sequences of spaces are collapsed into one, space, it will be ignored following a com-
it ‘feels as if’ spaces are ignored if they mand name). Thus the above command
follow another space. Space can have syn- would be written (by an experienced pro-
tactic meaning after certain sorts of non- grammer with a similar eye to emphasising
braced arguments (e.g., count and dimen the structure):
variable assignments in Plain TeX) and af-
ter certain control words (e.g., in \hbox \newcommand{\stline}[1]{%
to, so again we have instances where it \bigskip
‘feels as if’ spaces are being ignored when \makebox[2cm]{%
they’re merely working quietly for their \textbf{#1}\relax
living. }%
Consider the following macro, fairly }
faithfully adapted from one that appeared
Care has been taken to ensure that every
on comp.text.tex:
space in the revised definition is ignored,
\newcommand{\stline}[1]{ \bigskip so none appears in the \textbf{#1}
\makebox[2cm]{ output. The revised
} }
definition takes the “belt and braces” ap-
The macro definition contains five spaces: proach, explicitly dealing with every line
ending (although, as noted above, a space
• after the opening { of the macro body; introduced at the end of the first line of the
this space will be ignored, not be- macro would have been ignored in actual
cause “because the macro appears at use of the macro. This is the best tech-
the start of a line”, but rather because nique, in fact — it’s easier to blindly sup-
the macro was designed to operate be- press spaces than to analyse at every point
tween paragraphs whether you actually need to. Three tech-
• after \bigskip; this space will be ig- niques were used to suppress spaces:
nored (while the macro is being de-
fined) because it follows a command • placing a % character at the end of a
name line (as in the 1st, 3rd and 5th lines),
• after the { of the mandatory argument • ending a line ‘naturally’ with a control
of \makebox; even though this space sequence, as in line 2, and
will inevitably appear at the start of an • ending a line with an ‘artificial’ con-
output line, it will not be ignored trol sequence, as in line 4; the control
• after the } closing the argument of sequence in this case (\relax) is a no-
\textbf; this space will not be ig- op in many circumstances (as here),
186
 but this usage is deprecated — a % locationtype=Common grazing land,
character would have been better. date=1995/04/24,
numplants=50,
Beware of the (common) temptation to soiltype=alkaline
place a space before a % character: if you }
do this you might as well omit the % alto-
gether. The merit of such verbosity is that it
In “real life”, of course, the spaces that is self-explanatory: the typist doesn’t
appear in macros are far more cryptic than have to remember that argument twelve
those in the example above. The most com- is soiltype, and so on: the commands
mon spaces arise from unprotected line may be copied from field notes quickly
ends, and this is an error that occasionally and accurately.
appears even in macros written by the most keyval.sty : Distributed as part
accomplished programmers. of macros/latex/required/
337 How to break the 9-argument graphics
limit * faq-mac-prog.tex (q-keyval): tweak
If you think about it, you will realise that words about getoptk
Knuth’s command definition syntax: 338 Key-value input for macros and
\def\blah#1#2 ... #9{<macro body>} package options
When we discussed extending the number
is intrinsically limited to just 9 arguments. of arguments to a macro, we suggested that
There’s no direct way round this: how large numbers of arguments, distinguished
would you express a 10th argument? — only by their position, aren’t very kind to
and ensure that the syntax didn’t gobble the user, and that a package such as keyval
some other valid usage? offers a more attractive user interface. We
If you really must have more than 9 now consider the packages that the macro
arguments, the way to go is: programmer might use, to create such a
\def\blah#1#2 ... #9{% user interface.
\def\ArgI{{#1}}% The simplest key-value processor (for
\def\ArgII{{#2}}% LaTeX, at least) remains keyval; it has a
... command \define@key to declare a key
\def\ArgIX{{#9}}% and a handler to process it, and a macro
\BlahRelay \setkeys to offer values to the handler of
} one or more keys. Thus:
\def\BlahRelay#1#2#3{% \define@key{my}{foo}{Foo is #1\par}
% arguments 1-9 are now in \define@key{my}{bar}[99]{Bar is #1\par}
% \ArgI-\ArgIX ...
% arguments 10-12 are in \setkeys{my}{foo=3,bar}
% #1-#3
<macro body>% will produce output saying:
} Foo is 3
This technique is easily extendible by con- Bar is 99
cert pianists of the TeX keyboard, but is
This has defined two keys ‘foo’ and ‘bar’
really hard to recommend.
in family ‘my’, and then executed them, the
LaTeX users have the small conve-
first with argument ‘3’ and the second with
nience of merely giving a number of
no argument, so that the default value of
arguments in the \newcommand that de-
‘99’ is picked up. In effect, the two calls
fines each part of the relaying mech-
to \define@key are simply defining com-
anism: Knuth’s restriction applies to
mands, as (for example):
\newcommand just as it does to \def. How-
ever, LaTeX users also have the way out \newcommand{\KV@my@foo}[1]{Foo is #1}
of such barbarous command syntax: the
(the definition of \KV@my@bar is similar,
keyval package. With keyval, and a bit of
but trickier). The command \setkeys
programming, one can write really quite so-
phisticated commands, whose invocationknows how to find those commands when
might look like: it needs to process each key — it is easy to
regurgitate the structure of the command
\flowerinstance{species=Primula name,
veris, with family name (‘my’, here) after
family=Primulaceae, the first ‘@’, and the key name after the sec-
location=Coldham’s Common, ond ‘@’. (The ‘KV’ part is fixed, in keyval.)
187
 These simple commands are enough, Keys are organized in a tree that is remi-
in fact, to process the botanical exam- niscent of the Unix fille tree. A typical key
ple offered as replacement for multi- might be, /tikz/coordinate system/x
argument commands in the question men- or just /x. When you specify keys you
tioned above, or the optional arguments can provide the complete path of the key,
of the \includegraphics command of but you usually just provide the name of
the graphicx package. (The last is, in fact, the key (corresponding to the file name
what keyval was designed to do.) without any path) and the path is added
However, we need more if we’re automatically. So a \pgfkeys command
to to have package options in ‘key- might be:
value’ form. Packages like hyperref
\pgfkeys{/my key=hello,/your keys/main key=something\st
have enormously complicated package op-
key name without path=something else}
tions which need key-value processing at
\ProcessOptions time: keyval can’t do and for each key mentioned, the associated
that on its own. code will be executed. . . . and that code is
Heiko Oberdiek’s kvoptions package also set up using \pgfkeys:
comes to our help: it enables the pro- \pgfkeys{/my key/.code=The value is ’#1’.}
grammer to declare class or package
options that operate as key and value after which
pairs. The package defines commands \pgfkeys{/my key=hi!}
\DeclareBoolOption for options whose
value should be either true or false, and will produce just
\DeclareStringOption for all other op- The value is ’hi!’.
tions that have a value. Keys are de-
The manual goes on, showing how to de-
clared using keyval and may remain avail-
fine a key with two arguments, how to pro-
able for use within the document, or
vide default value for a key, and how to
may be ‘cancelled’ to avoid confusion.
define aliases for particular key sequences
If you have loaded kvoptions, the La-
(which are called “styles”). All in all, it
TeX kernel’s \DeclareOption becomes
seems a well thought-out system, offer-
\DeclareVoidOption (it’s an option with
ing a lot of flexibility that isn’t available
no value), and \DeclareOption* be-
with the other keys packages. However,
comes \DeclareDefaultOption.
there seems to be no mechanism for using
Heiko also provides kvsetkeys which
pgfkeys keys as part of the options of an-
is a more robust version of setkeys, with
other package, in the way that kvoptions
some of the rough edges made smoother.
does.
Hendri Adriaens’ xkeyval offers more
The l3kernel programming layer for
flexibility than the original keyval and
LaTeX3 includes the l3keys module. In-
is more robust than the original, too.
spired by pgfkeys, it provides a keyval-
Like kvoptions, the package also has
based method for the programmer to cre-
mechanisms to allow class and pack-
ate keys. As with keyval and derivatives,
age options in key-value form (macros
l3keys uses separate macros for defining
\DeclareOptionX, \ExecuteOptionsX
and setting keys. The package l3keys2e
and \ProcessOptionsX. Pstricks bundle
makes it possible for LaTeX2e class and
packages use a xkeyval derivative called
package options to be processed using
pst-xkey for their own key-value manipula-
l3keys. L3kernel code can be used within
tion.
existing LaTeX2e documents, so l3keys is
The (widely-respected) pgf graphics
also available to the LaTeX2e programmer
package has its own key-value package
‘direct’.
called pgfkeys. The documentation of the
Another key-value system that’s part
package (part of the huge pgf manual, in
of larger set of macros is scrbase, which
part 5, “utilities”) contains a useful compar-
uses the facilities of keyval to build a
ison with other key-value systems; some
larger set of facilities, originally for use
notable differences are:
within the KOMA-script bundle. For
• key organisation: pgfkeys uses a tree English-speaking authors, there are diffi-
structure, while keyval and xkeyval culties from the German-only documenta-
both associate keys with a family; tion; however, from a partial translation
• pgfkeys supports multi-argument key available to the author of this answer, a
code; and summary is possible. The package may
• pgfkeys can support call-backs when build on the facilities either of kyeval or
an unknown key appears (these things of xkeyval, and builds its functionality on
are called handlers. the structure of the ‘key family’. The
188
user may define family ‘members’ and LaTeX define the character “~” as a “non-
keys are defined relative to the members. breakable space”. A character is made de-
(For example, the package scrbase is part finable, or “active”, by setting its category
of the KOMA-script bundle; so its keys code (catcode) to be \active (13):
are all members of the scrbase.sty fam-
\catcode‘\_=\active
ily within the KOMA family. The func-
tion \FamilyProcessOptions allows the Any character could, in principle, be acti-
programmer to decode the options of the vated this way and defined as a macro:
package in terms of the package’s key fam-
ily. Note that there is no special provision \def_{\_}
made for “traditional” package options, as which could be characterised as an over-
in the kvoptions package. simple answer to using underscores. How-
This brief summary was guided by in- ever, you must be wary: whereas people ex-
put from two sources: a draft article for pect an active tilde, other active characters
TUGboat by Joseph Wright, and the partial may be unexpected and interact badly with
translation of the documentation of pack- other macros. Furthermore, by defining an
age scrbase prepared by Philipp Stephani. active character, you preclude the charac-
All the above are (at least) aimed at La- ter’s use for other purposes, and there are
TeX programming; there is one package, few characters “free” to be subverted in
getoptk, aimed at the Plain TeX program- this way.
mer. Getoptk uses syntax inspired by that To define the character “z” as a com-
offered by TeX primitives such as \hrule mand, one would say something like:
and \hbox, so we are offered syntax such
as: \catcode‘\z=\active
\def z{Yawn, I’m tired}%
\begindisplay file {chapter1} literal offset 20pt
and each subsequent “z” in the text would
(taken from the package manual). become a yawn. This would be an as-
There are (we know) people who toundingly bad idea for most documents,
would swear that such syntax is wonderfulbut might have special applications. (Note
(the present author wouldn’t), but the pack-
that, in “\def z”, “z” is no longer inter-
age earns its place as the only stand-alone
preted as a letter; the space is therefore
key-value macros that will work in Plain not necessary — “\defz” would do; we
TeX. choose to retain the space, for what lit-
getoptk.tex : tle clarity we can manage.) Some LaTeX
macros/plain/contrib/getoptk packages facilitate such definitions. For
example, the shortvrb package with its
keyval.sty : Distributed as part
\MakeShortVerb command.
of macros/latex/required/ TeX uses category codes to interpret
graphics
characters as they are read from the in-
kvoptions.sty : Distributed as part of put. Changing a catcode value will not
macros/latex/contrib/oberdiek affect characters that have already been
kvsetkeys.sty : Distributed as part of read. Therefore, it is best if characters
macros/latex/contrib/oberdiek have fixed category codes for the duration
of a document. If catcodes are changed
l3keys.sty : Distributed as part of for particular purposes (the \verb com-
macros/latex/contrib/l3kernel mand does this), then the altered characters
l3keys2e.sty : Distributed as part will not be interpreted properly when they
of macros/latex/contrib/ appear in the argument to another com-
l3packages mand (as, for example, in \verb in com-
mand arguments). An exemplary case is
pgfkeys.sty : Distributed as part of
the doc package, which processes .dtx files
graphics/pgf/base
using the shortvrb package to define |...|
scrbase.sty : Distributed as part of as a shorthand for \verb|...|. But | is
macros/latex/contrib/koma- also used in the preambles of tabular envi-
script ronments, so that tables in .dtx files can
xkeyval.sty : only have vertical line separation between
macros/latex/contrib/xkeyval columns by employing special measures
of some sort.
339 Defining characters as macros Another consequence is that catcode
Single characters can act as macros (de- assignments made in macros often don’t
fined commands), and both Plain TeX and work as expected (Active characters in
189
command arguments). For example, the 340 Active characters in command
definition arguments
\def\mistake{% Occasionally, it’s nice to make one or two
\catcode‘_=\active characters active in the argument of a com-
\def_{\textunderscore\-}% mand, to make it easier for authors to code
} the arguments.
does not work because it attempts to define Active characters can be used safely in
an ordinary _ character: When the macro such situations; but care is needed.
is used, the category change does not apply An example arose while this answer
to the underscore character already in the was being considered: an aspirant macro
macro definition. Instead, one may use: writer posted to comp.text.tex asking
for help to make # and b produce musi-
\begingroup cal sharp and flat signs, respectively, in a
\catcode‘_=\active macro for specifying chords.
\gdef\works{% note the global \gdefThe first problem is that both # and
\catcode‘_=\active b have rather important uses elsewhere in
\def_{\textunderscore\-}% TeX (to say the least!), so that the char-
} acters can only be made active while the
\endgroup command is executing.
The alternative (“tricksy”) way of creating Using the techniques discussed in char-
such an isolated definition depends on the acters as commands, we can define:
curious properties of \lowercase, which
changes characters without altering their \begingroup
catcodes. Since there is always one active \catcode‘\#=\active
character (“~”), we can fool \lowercase \gdef#{$\sharp$}
into patching up a definition without ever \endgroup
explicitly changing a catcode:
and:
\begingroup
\lccode‘\~=‘\_ \begingroup
\lowercase{\endgroup \lccode‘\~=‘\b
\def~{\textunderscore\-}% \lowercase{\endgroup
}% \def~{$\flat$}%
}
The two definitions have the same over-
all effect (the character is defined as a The second problem is one of timing: the
command, but the character does not re- command has to make each character ac-
main active), except that the first defines a tive before its arguments are read: this
\global command. means that the command can’t actually
For active characters to be used only “have” arguments itself, but must be split
in maths mode, it is much better to leave in two. So we write:
the character having its ordinary catcode,
but assign it a special active maths code, as \def\chord{%
with \begingroup
\catcode‘\#=\active
\begingroup
\catcode‘\b=\active
\lccode‘~=‘x
\Xchord
\lowercase{\endgroup
}
\def~{\times}%
\def\Xchord#1{%
}%
\chordfont#1%
\mathcode‘x="8000
\endgroup
The special character does not need to be }
redefined whenever it is made active — the
definition of the command persists even if and we can use the command as \chord
the character’s catcode reverts to its orig- {F#} or \chord{Bb minor}.
inal value; the definition becomes acces- Two features of the coding are impor-
sible again if the character once again be- tant:
comes active.
• \begingroup in \chord opens a
doc.sty : Part of the LaTeX
group that is closed by \endgroup in
distribution macros/latex/base \Xchord; this group limits the change
shortvrb.sty : Part of the LaTeX of category codes, which is the raison
distribution macros/latex/base d’être of the whole exercise.
190
 • Although # is active while \Xchord \def\start#1{\csname start#1\endcsname}
is executed, it’s not active when it’s \def\finish#1{\csname finish#1\endcsname}
being defined, so that the use of #1
doesn’t require any special attention. these ‘races’ could behave a bit like LaTeX
environments.
Note that the technique used in such
macros as \chord, here, is analogous to 342 Transcribing LaTeX command
that used in such commands as \verb; and, definitions
in just the same way as \verb (see \verb At several places in this FAQ, questions
doesn’t work in arguments), \chord won’t are answered in terms of how to program
work inside the argument of another com- a LaTeX macro. Sometimes, these macros
mand (the error messages, if they appear might also help users of Plain TeX or other
at all, will probably be rather odd). packages; this answer attempts to provide a
rough-and-ready guide to transcribing such
341 Defining a macro from an macro definitions for use in other pack-
argument ages.
It’s common to want a command to cre- The reason LaTeX has commands that
ate another command: often one wants the replace \def, is that there’s a general
new command’s name to derive from an ar- philosophy within LaTeX that the user
gument. LaTeX does this all the time: for should be protected from himself: the
example, \newenvironment creates start- user has different commands according to
and end-environment commands whose whether the command to be defined exists
names are derived from the name of the (\renewcommand) or not (\newcommand),
environment command. and if its status proves not as the user ex-
The (seemingly) obvious approach: pected, an error is reported. A third defi-
nition command, \providecommand, only
\def\relay#1#2{\def\#1{#2}} defines if the target is not already defined;
LaTeX has no direct equivalent of \def,
doesn’t work (the TeX engine interprets
which ignores the present state of the com-
it as a rather strange redefinition of \#).
mand. The final command of this sort is
The trick is to use \csname, which is a
\DeclareRobustCommand, which creates
TeX primitive for generating command
a command which is “robust” (i.e., will not
names from random text, together with
expand if subjected to LaTeX “protected
\expandafter. The definition above
expansion”); from the Plain TeX user’s
should read:
point of view, \DeclareRobustCommand
\def\relay#1#2{% should be treated as a non-checking ver-
sion of \newcommand.
\expandafter\def\csname #1\endcsname{#2}%
} LaTeX commands are, by default, de-
fined \long; an optional * between the
With this definition, \relay{blah} \newcommand and its (other) arguments
{bleah} is equivalent to \def\blah specifies that the command is not to be
{bleah}. defined \long. The * is detected by a com-
Note that the definition of \relay mand \@ifstar which uses \futurelet
omits the braces round the ‘command to switch between two branches, and gob-
name’ in the \newcommand it executes. bles the *: LaTeX users are encouraged
This is because they’re not necessary (in to think of the * as part of the command
fact they seldom are), and in this circum- name.
stance they make the macro code slightly LaTeX’s checks for unknown com-
more tedious. mand are done by \ifx comparison of a
The name created need not (of course) \csname construction with \relax; since
be just the argument: the command name argument is the desired
control sequence name, this proves a little
\def\newrace#1#2#3{% long-winded. Since #1 is the requisite ar-
\expandafter\def\csname start#1\endcsname{%
gument, we have:
#2%
}% \expandafter\ifx
\csname\expandafter\@gobble\string#1\endcsname
\expandafter\def\csname finish#1\endcsname{%
#3% \relax
}% ...
}
(\@gobble simply throws away its argu-
With commands ment).
191
 The arguments of a LaTeX command number two of the “around the bend” arti-
are specified by two optional arguments cles by the late lamented Mike Downes.
to the defining command: a count of argu- Around the bend series:
ments (0–9: if the count is 0, the optional info/challenges/aro-bend
count argument may be omitted), and a
default value for the first argument, if the ifmtarg.sty :
defined command’s first argument is to be macros/latex/contrib/ifmtarg
optional. So: memoir.cls:
macros/latex/contrib/memoir
\newcommand\foo{...}
\newcommand\foo[0]{...} 344 Am I using PDFTeX, XeTeX or
\newcommand\foo[1]{...#1...} LuaTeX?
\newcommand\foo[2][boo]{...#1...#2...}
You often need to know what “engine”
your macros are running on (the engine is
In the last case, \foo may be called as
the TeX-derivative or TeX-alike processor
\foo{goodbye}, which is equivalent to
that typesets your document). The reason
\foo[boo]{goodbye} (employing the de-
that you need to know is that the set of
fault value given for the first argument), or
functions available in each engine is dif-
as \foo[hello]{goodbye} (with an ex-
ferent. Thus, for TeX macros to run on
plicit first argument).
any engine, they need to “know” what they
Coding of commands with optional ar-
can and cannot do, which depends on the
guments is exemplified by the coding of
engine in use. Getting the right answer is
the last \foo above:
surprisingly tricky (see below for an elabo-
\def\foo{\futurelet\next\@r@foo}ration of one apparently simple test).
\def\@r@foo{\ifx\next[% There is now a comprehensive set of
\let\next\@x@foo packages that answer the question for you.
\else They all create a TeX conditional com-
\def\next{\@x@foo[boo]}% mand:
\fi
• ifpdf creates a command \ifpdf,
\next
• ifxetex creates a command \ifxetex
}
and
\def\@x@foo[#1]#2{...#1...#2...}
• ifluatex creates a command
343 Detecting that something is \ifluatex.
empty
These TeX commands may be used within
Suppose you need to know that the argu- the LaTeX conditional framework, as (for
ment of your command is empty: that is, example):
to distinguish between \cmd{} and \cmd
{blah}. This is pretty simple: \ifthenelse{\boolean
{pdf}}{hif pdf i}{hif not pdf i}
\def\cmd#1{%
\def\tempa{}% The ifxetex package also provides a
\def\tempb{#1}% command \RequireXeTeX which creates
\ifx\tempa\tempb an error if the code is not running under
<empty case> XeTeX; while the other packages don’t pro-
\else vide such a command, it’s not really diffi-
<non-empty case> cult to write one for yourself.
\fi Now for those who want to do the job
} for themselves: here’s a discussion of do-
ing the job for PDFTeX and \ifpdf —
The case where you want to ignore an ar- the eager programmer can regenerate
gument that consists of nothing but spaces, \ifxetex or \ifluatex in the same fash-
rather than something completely empty, ion. It’s not recommended. . .
is more tricky. It’s solved in the code frag- Suppose you need to test whether your
ment ifmtarg, which defines commands output will be PDF or DVI. The natural
\@ifmtarg and \@ifnotmtarg, which ex- thing is to check whether you have access
amine their first argument, and select (in to some PDFTeX-only primitive; a good
opposite directions) their second or third ar- one to try (not least because it was present
gument. The package’s code also appears in the very first releases of PDFTeX) is
in the LaTeX memoir class. \pdfoutput. So you try
Ifmtarg makes challenging reading;
there’s also a discussion of the issue in \ifx\pdfoutput\undefined
192
 ... % not running PDFTeX 345 Subverting a token register
\else
A common requirement is to “subvert”
... % running PDFTeX
a token register that other macros may
\fi
use. The requirement arises when you
Except that neither branch of this condi- want to add something to a system to-
tional is rock-solid. The first branch can ken register (\output or \every*), but
be misleading, since the “awkward” user know that other macros use the token reg-
could have written: ister, too. (A common requirement is to
work on \everypar, but LaTeX changes
\let\pdfoutput\undefined \everypar at every touch and turn.)
so that your test will falsely choose the The following technique, due to David
first alternative. While this is a theoretical Kastrup, does what you need, and allows
problem, it is unlikely to be a major one. an independent package to play the exact
More important is the user who loads a same game:
package that uses LaTeX-style testing for
the command name’s existence (for exam- \let\mypkg@@everypar\everypar
ple, the LaTeX graphics package, which is \newtoks\mypkg@everypar
useful even to the Plain TeX user). Such a \mypkg@everypar\expandafter{\the\everypar}
package may have gone ahead of you, so \mypkg@@everypar{\mypkgs@ownstuff\the\mypkg@everypar}
the test may need to be elaborated: \def\mypkgs@ownstuff{%
<stuff to do at the start of the token register>%
\ifx\pdfoutput\undefined }
... % not running PDFTeX \let\everypar\mypkg@everypar
\else
\ifx\pdfoutput\relax As you can see, the package (mypkg)
... % not running PDFTeX
\else • creates an alias for the existing “sys-
... % running PDFTeX tem” \everypar (which is frozen into
\fi any surrounding environment, which
\fi will carry on using the original);
• creates a token register to subvert
If you only want to know whether some \everypar and initialises it with the
PDFTeX extension (such as marginal kern- current contents of \everypar;
ing) is present, you can stop at this point: • sets the “old” \everypar to execute
you know as much as you need. its own extra code, as well as the con-
However, if you need to know whether tents of its own token register;
you’re creating PDF output, you also need • defines the macro for the extra code;
to know about the value of \pdfoutput: and
\ifx\pdfoutput\undefined • points the token \everypar at the
... % not running PDFTeX new token register.
\else
and away we go.
\ifx\pdfoutput\relax
... % not running PDFTeX
The form \mypkg@... is (sort of)
\else
blessed for LaTeX package internal names,
% running PDFTeX, with...
which is why this example uses macros of
\ifnum\pdfoutput>0
that form.
... % PDF output
346 Is this command defined?
\else
... % DVI output Macro sets from the earliest days of TeX
\fi programming may be observed to test
\fi whether commands exist by using
\fi
\ifx \command \undefined
ifpdf.sty : Distributed as part hstuff i . . .
Heiko Oberdiek’s bundle
macros/latex/contrib/oberdiek (which of course actually tests that the
ifluatex.sty : Distributed as part
command doesn’t exist). LaTeX program-
of Heiko Oberdiek’s bundle mers can make use of the internal com-
macros/latex/contrib/oberdiek
mand

ifxetex.sty : \@ifundefined{cmd name}

macros/generic/ifxetex {action1}{action2}
193
which executes action1 if the command \ifcsname foo\endcsname
is undefined, and action2 if it is defined \message{\string\foo\space is defined}%
(cmd name is the command name only, \else
omitting the ‘\’ character). \message{no command \string\foo}%
The \@ifundefined command is \fi
based on the sequence
However, after using the LaTeX
\expandafter \ifx \csname cmd name\endcsname \relax
\@ifundefined{foo}. . . , the condition-
als will detect the command as “existing”
which relies on the way \csname works: if
(since it has been \let to \relax); so it
the command doesn’t exist, it simply cre-
is important not to mix mechanisms for
ates it as an alias for \relax.
detecting the state of a command.
So: what is wrong with these tech-
Since most distributions nowadays use
niques?
e-TeX as their base executable for most
Using \undefined blithely assumes
packages, these two primitives may be ex-
that the command is indeed not defined.
pected appear widely in new macro pack-
This isn’t entirely safe; one could make
ages.
the name more improbable, but that may
simply make it more difficult to spot a R.2 LaTeX macro tools and
problem when things go wrong. LaTeX
techniques
programmers who use the technique will
typically employ \@undefined, adding a 347 Using Plain or primitive
single level of obscurity. commands in LaTeX
The \@ifundefined mechanism has It’s well-known that LaTeX commands
the unfortunate property of polluting the tend to be more complex, and to run more
name space: each test that turns out unde- slowly than, any Plain TeX (or primi-
fined adds a name to the set TeX is holding,tive) command that they replace. There
and often all those “\relax” names serve is therefore great temptation not to use
no purpose whatever. Even so (sadly) there LaTeX commands when macro program-
are places in the code of LaTeX where ming. Nevertheless, the general rule is that
the existence of the \relax is relied upon, you should use LaTeX commands, if there
after the test, so we can’t get away from are seeming equivalents. The exception
\@ifundefined altogether. is when you are sure you know the dif-
David Kastrup offers the (rather tricky)ferences between the two commands and
you know that you need the Plain TeX ver-
{\expandafter}\expandafter\ifx \csname cmd name\endcsname\relax ...
sion. So, for example, use \mbox in place
which “creates” the \relax-command in- of \hbox unless you know that the extras
side the group of the first \expandafter, that LaTeX provides in \mbox would cause
therefore forgets it again once the test is trouble in your application. Similarly, use
done. The test is about as good as you can \newcommand (or one of its relatives) un-
do with macros. less you need one of the constructs that
The e-TeX system system comes to our cannot be achieved without the use of \def
help here: it defines two new primitives: (or friends).
As a general rule, any LaTeX text com-
• \ifdefined, which tests whether a mand will start a new paragraph if nec-
thing is defined (the negative of com- essary; this isn’t the case with Plain TeX
paring with \undefined, as it were), commands, a fact which has a potential to
and confuse.
• \ifcsname cmd name\endcsname, The commands \smallskip,
which does the negative of \medskip and \bigskip exist both in
\@ifundefined without the \relax- Plain TeX and LaTeX, but behave slightly
command side-effect. differently: in Plain TeX they terminate
So, in an e-TeX-based system, the follow- the current paragraph, but in LaTeX they
ing two conditional clauses do the same don’t. The command \line is part of
thing: picture mode in LaTeX, whereas it’s de-
fined as “\hbox to \hsize” in Plain
\ifdefined\foo TeX. (There’s no equivalent for users of the
\message{\string\foo\space is Plain TeX command in LaTeX: an equiv-
defined}%
\else alent appears as the internal command
\message{no command \string\foo}% \@@line).
\fi Maths setting shows a case where the
% LaTeX version is essentially equivalent
194
to the TeX primitive commands: the La- {subsection}{2}{0mm}%name, level, indent
TeX \( ... \) does essentially no dif- {-\baselineskip}% beforeskip
ferent to the primitive $ ... $; except {0.5\baselineskip}% afterskip
for checking that you’re not attempting to {\normalfont\normalsize\itshape}}% style
open a maths environment when you’re al- \makeatother
ready in one, or attempting to close one
when you’re not. However, \[ ... \] (That example appears on page 29 of The
has a more significant difference from $$ LaTeX Companion, second edition.)
... $$: the primitive version, used in La- The alternative is to treat all these frag-
TeX, can miss the effect of the class option ments as a package proper, bundling them
fleqn. up into a .sty file and including them
Font handling is, of course, wildly with \usepackage; this way you hide your
different in Plain TeX and LaTeX. LaTeX internal code somewhere that La-
Plain TeX’s font loading command TeX internal code is expected, which often
(\font\foo=hfontnamei) and its LaTeX looks ‘tidier’.
equivalent (\newfont) should be avoided Examples from the Companion:
wherever possible. They are only safe in info/examples/tlc2
the most trivial contexts, and are poten-
349 What’s the reason for
tial sources of great confusion in many cir-
‘protection’?
cumstances. Further discussion of this is-
sue may be found in “What’s wrong with Sometimes LaTeX saves data it will reread
\newfont?”. later. These data are often the argument
of some command; they are the so-called
348 \@ and @ in macro names moving arguments. (‘Moving’ because
Macro names containing @ are internal to data are moved around.) Candidates are
LaTeX, and without special treatment just all arguments that may go into table of
don’t work in ordinary use. A nice exam- contents, list of figures, etc.; namely, data
ple of the problems caused is discussed in that are written to an auxiliary file and read
\@ in vertical mode”. in later. Other places are those data that
The problems users see are caused by might appear in head- or footlines. Section
copying bits of a class (.cls file) or pack- headings and figure captions are the most
age (.sty file) into a document, or by prominent examples; there’s a complete
including a class or package file into a list in Lamport’s book (see TeX-related
LaTeX document by some means other books).
than \documentclass or \usepackage. What’s going on really, behind the
LaTeX defines internal commands whose scenes? The commands in moving argu-
names contain the character @ to avoid ments are normally expanded to their in-
clashes between its internal names and ternal structure during the process of sav-
names that we would normally use in our ing. Sometimes this expansion results in
documents. In order that these commands invalid TeX code, which shows either dur-
may work at all, \documentclass and ing expansion or when the code is pro-
\usepackage play around with the mean- cessed again. Protecting a command, using
ing of @. “\protect\cmd” tells LaTeX to save \cmd
If you’ve included a file some other as \cmd, without expanding it at all.
way (for example, using \input), you can So, what is a ‘fragile command’? —
probably solve the problem by using the it’s a command that expands into illegal
correct command. TeX code during the save process.
If you’re using a fragment of a pack- What is a ‘robust command’? — it’s a
age or class, you may well feel confused: command that expands into legal TeX code
books such as the first edition of the The during the save process.
LaTeX Companion are full of fragments Lamport’s book says in its description
of packages as examples for you to em- of every LaTeX command whether it is
ploy. The second edition of the Companion ‘robust’ or ‘fragile’; it also says that ev-
makes clearer how you should use these ery command with an optional argument is
fragments, and in addition, the code of all fragile. The list isn’t reliable, and neither
the examples is now available on CTAN. is the assertion about optional arguments;
To see the technique in practice, look at the statements may have been true in early
the example below, from file 2-2-7.ltx versions of LaTeX2e but are not any longer
in the Companion examples directory: necessarily so:

\makeatletter • Some fragile commands, such as

\cite, have been made robust in later
\renewcommand\subsection{\@startsection
195
 revisions of LaTeX. 350 \edef does not work with
• Some commands, such as \end and \protect
\nocite, are fragile even though they Robust LaTeX commands are either “nat-
have no optional arguments. urally robust” — meaning that they never
• The “user’s way” of creating a com- need \protect, or “self-protected” —
mand with an optional argument (us- meaning that they have \protect built
ing \newcommand or \newcommand*) in to their definition in some way. Self-
now always creates a robust command protected commands, and fragile com-
(though macros without optional argu- mands with \protection are only robust
ments may still be fragile if they do in a context where the \protect mecha-
things that are themselves fragile). nism is properly handled. The body of an
• There is no reason that a package au- \edef definition doesn’t handle \protect
thor should not also make robust com- properly, since \edef is a TeX primitive
mands with optional arguments as part rather than a LaTeX command.
of the package. This problem is resolved by a LaTeX
• Some robust commands are redefined internal command \protected@edef,
by certain packages to be fragile (the which does the job of \edef while
\cite command commonly suffers keeping the \protect mechanism
this treatment). working. There’s a corresponding
\protected@xdef which does the job
Further, simply “hiding” a fragile com-
of \xdef.
mand in another command, has no effect
Of course, these commands need to be
on fragility. So, if \fred is fragile, and
tended carefully, since they’re internal: see
you write:
’@’ in control sequence names.
\newcommand{\jim}{\fred} 351 The definitions of LaTeX
commands
then \jim is fragile too. There is,
There are several reasons to want to know
however, the \newcommand-replacement
the definitions of LaTeX commands: from
\DeclareRobustCommand, which always
the simplest “idle curiosity”, to the press-
creates a robust command (whether or not
ing need to patch something to make it
it has optional arguments). The syntax of
“work the way you want it”. None of these
\DeclareRobustCommand is substantially
are pure motives, but knowledge and ex-
identical to that of \newcommand, and if
pertise seldom arrive through the purest of
you do the wrapping trick above as:
motives.
\DeclareRobustCommand{\jim}{\fred} Using a TeX executable of some sort,
the simple answer is to try \show, in a run
then \jim is robust. that is taking commands from the terminal:
Finally, we have the makerobust pack-
*\makeatletter
age, which defines \MakeRobustCommand
*\show\protected@edef
to convert a command to be robust. With
> \protected@edef=macro:
the package, the “wrapping” above can
->\let \@@protect \protect
simply be replaced by:
\let \protect \@unexpandable@protect
\afterassignment \restore@protect \edef .
\MakeRobustCommand\fred
(I’ve rearranged the output there, from
Whereafter, \fred is robust. Using the
the rather confused version TeX itself pro-
package may be reasonable if you have
duces.)
lots of fragile commands that you need to
So, what about \@unexpandable@protect?:
use in moving arguments.
In short, the situation is confusing. No- *\show\@unexpandable@protect
one believes this is satisfactory; the LaTeX > \@unexpandable@protect=macro:
team have removed the need for protection ->\noexpand \protect \noexpand .
of some things, but the techniques avail-
able in current LaTeX mean that this is and we’re starting to see how one part
an expensive exercise. It remains a long- of the \protection mechanism works
term aim of the team to remove all need (one can probably fairly safely guess what
for \protection. \restore@protect does).
Many kernel commands are declared
makerobust.sty : Distributed as
robust:
part of Heiko Oberdiek’s bundle
macros/latex/contrib/oberdiek *\show\texttt
196
 > \texttt=macro:
->\protect \texttt . \enditemize:
macro:->\global \advance \@listdepth \m@ne \endtrivlist
so that \show isn’t much help. Define a
command \pshow as shown below, and (Yet again, this is a sanitised version of the
simply execute the command to find its macro definition output, which appears as
definition: a single very wide line for each definition.)
If one has a malleable text editor, the
*\def\pshow#1{{\let\protect\showsame #1}} investigation may be conducted by
*\pshow\texttt examining the file latex.ltx (which is
> \texttt =\long macro: usually to be found, in a TDS system, in
#1->\ifmmode \nfss@text {\ttfamily #1}%tex/latex/base).
directory
\else \hmode@bgroup \text@command {#1}%
In fact, latex.ltx is the product of a
\ttfamily \check@icl #1\check@icr
docstrip process on a large number of .dtx
\expandafter \egroup \fi . files, and you can refer to those instead.
The LaTeX distribution includes a file
Note that the command name that is pro-
source2e.tex, and most systems retain
tected is the ‘base’ command, with a space
it, again in tex/latex/base. Source2e.
appended. This is cryptically visible, in a
tex may be processed to provide a com-
couple of places above. (Again, the output
plete source listing of the LaTeX kernel
has been sanitised.)
(in fact the process isn’t entirely straight-
The command texdef (or latexdef —
forward, but the file produces messages
the same command with a different name)
advising you what to do). The result is a
will do all that for you and return the re-
huge document, with a line-number index
sults slightly more tidily than LaTeX itself
of control sequences the entire kernel and
manages. For example:
a separate index of changes recorded in
$ latexdef texttt each of the files since the LaTeX team took
over.
gives: The printed kernel is a nice thing to
macro:->\protect \texttt
have, but it’s unwieldy and sits on my
shelves, seldom used. One problem is
\texttt :
that the comments are patchy: the different
#1->\ifmmode \nfss@text {\ttfamily #1}%
modules range from well and lucidly doc-
umented, through modules documented
\else \hmode@bgroup \text@command {#1}%
only through an automatic process that con-
\ttfamily \check@icl #1\check@icr
\expandafter \egroup \fi .
verted the documentation of the source of
LaTeX 2.09, to modules that hardly had
(again, the output has been sanitised — any useful documentation even in the La-
but we see that latexdef has useful ‘intelli- TeX 2.09 original.
gence’ in it, as it has spotted and dealt with In fact, each kernel module .dtx file
the \protect.) will process separately through LaTeX, so
With the -s switch, latexdef will give you don’t have to work with the whole
you a source location: of source2e. You can easily determine
which module defines the macro you’re in-
$ latexdef -s texttt terested in: use your “malleable text editor”
% latex.ltx, line 3736: to find the definition in latex.ltx; then
\DeclareTextFontCommand{\texttt}{\ttfamily}
search backwards from that point for a line
though one should note that it doesn’t give that starts %%% From File: — that line
you the detail of the actual coding, merely tells you which .dtx file contains the defi-
the definition’s location. nition you are interested in. Doing this for
\protected@edef, we find:
Environments also surrender their de-
tails to latexdef : %%% From File: ltdefns.dtx

$ latexdef -E itemize When we come to look at it, ltdefns.dtx

proves to contain quite a dissertation on the
\itemize: methods of handling \protection; it also
contains
macro:->\ifnum \@itemdepth >\thr@@ some automatically-converted La-
\@toodeep
TeX 2.09 documentation.
\else \advance \@itemdepth \@ne
And of course,
\edef \@itemitem {labelitem\romannumeral \thethe\@itemdepth}%
kernel isn’t all
of LaTeX: your
\expandafter \list \csname \@itemitem command may be de-
\endcsname
{\def \makelabel ##1{\hss fined
\llap in one of LaTeX’s class or package
{##1}}}%
\fi files. For example, we find a definition of
197
\thebibliography in article, but there’s the “simple” solution to this problem: com-
no article.dtx. Some such files are gen- mand relaying.
erated from parts of the kernel, some from LaTeX allows commands with a single
other files in the distribution. You find optional argument thus:
which by looking at the start of the file: in
article.cls, we find: \newcommand{\blah}[1][Default]{...}

%% This is file ‘article.cls’, You may legally call such a command

%% either with its optional argument present,
generated with the docstrip utility.
%% as \blah[nonDefault] or without, as
%% \blah; in the latter case, the code of \blah
The original source files were:
%% will have an argument of Default.
%% classes.dtx To define a command with two op-
(with options: ‘article’)
tional arguments, we use the relaying tech-
so we need to format classes.dtx to see nique, as follows:
the definition in context.
All these .dtx files are on CTAN as part \newcommand{\blah}[1][Default1]{%
of the main LaTeX distribution. \def\ArgI{{#1}}%
\BlahRelay
LaTeX distribution:
}
macros/latex/base
\newcommand\BlahRelay[1][Default2]{%
texdef,aka latexdef : support/texdef % the first optional argument is now in
352 Optional arguments like % \ArgI
\section % the second is in #1
...%
Optional arguments, in macros defined us-
}
ing \newcommand, don’t quite work like
the optional argument to \section. The Of course, \BlahRelay may have as many
default value of \section’s optional argu- mandatory arguments as are allowed, af-
ment is the value of the mandatory argu- ter allowance for the one taken up with its
ment, but \newcommand requires that you own optional argument — that is, 8.
‘know’ the value of the default beforehand. Variants of \newcommand (and
The requisite trick is to use a macro in friends), with names like \newcommandtwoopt,
the optional argument: are available in the twoopt package. How-
\documentclass{article} ever, if you can, it’s probably better to
\newcommand\thing[2][\DefaultOpt]{% learn to write the commands yourself, just
\def\DefaultOpt{#2}% to see why they’re not even a good idea
optional arg: #1, mandatory arg: from the
#2%programming point of view.
} A command with two optional argu-
\begin{document} ments strains the limit of what’s sensible:
\thing{manda}% #1=#2 obviously you can extend the technique
to provide as many optional arguments
\thing[opti]{manda}% #1="opti" as your fevered imagination can summon.
\end{document} However, see the comments on the use
of the keyval package, in “breaking the
LaTeX itself has a trickier (but less read- 9-argument limit”, which offers an alterna-
ily understandable) method, using a macro tive way forward.
\@dblarg; inside LaTeX, the example If you must, however, consider the
above would have been programmed: optparams or xargs packages. Optparams
\newcommand\thing{\@dblarg\@thing}
provides a \optparams command that you
\newcommand\@thing[2][\@error]{%
use as an intermediate in defining com-
optional arg: #1, mandatory arg: #2%
mands with up to nine optional arguments.
}
The documentation shows examples of
commands with four optional arguments
In that code, \@thing is only ever called (and this from an author who has his own
with an optional and a mandatory argu- key-value package!).
ment; if the default from the \newcommand The xargs package uses a key-value
is invoked, a bug in user code has bitten. . . package (xkeyval) to define the layout of
the optional arguments. Thus
353 More than one optional
argument \usepackage{xargs}
If you’ve already read “breaking the 9- ...
argument limit”. you can probably guess \newcommandx{\foo}[3][1=1, 3=n]{...}
198
defines a command \foo that has an op- (Note that arguments to \mycommandStar
tional first argument (default 1), a manda- and \mycommandNoStar are indepen-
tory second argument, and an optional dent — either can have their own argu-
third argument (default n). ments, unconstrained by the technique
An alternative approach is offered we’re using, unlike the trick described
by Scott Pakin’s newcommand program, above.) The \@ifstar trick is all very
which takes a command name and a defi- well, is fast and efficient, but it requires
nition of a set of command arguments (in that the definition be \makeatletter pro-
a fairly readily-understood language), and tected.
emits (La)TeX macros which enable the A pleasing alternative is the suffix pack-
command to be defined. The command age. This elegant piece of code allows you
requires that a Python interpreter (etc.) be to define variants of your commands:
installed on your computer.
\newcommand\mycommand{normal version}
newcommand.py : support/newcommand \WithSuffix\newcommand\mycommand*{starred version}
optparams.sty : Distributed as part of
The package needs e-LaTeX, but any new
macros/latex/contrib/sauerj
enough distribution defines LaTeX as e-
twoopt.sty : Distributed as part of LaTeX by default. Command arguments
macros/latex/contrib/oberdiek may be specified in the normal way, in both
command definitions (after the “*” in the
xargs.sty :
\WithSuffix version). You can also use
macros/latex/contrib/xargs
the TeX primitive commands, creating a
xkeyval.sty : definition like:
macros/latex/contrib/xkeyval
\WithSuffix\gdef\mycommand*{starred version}
354 Commands defined with * For those of an adventurous disposi-
options tion, a further option is to use the xparse
LaTeX commands commonly have “ver- package from the l3packages distribution.
sions” defined with an asterisk tagged onto The package defines a bunch of commands
their name: for example \newcommand (such as \NewDocumentCommand) which
and \newcommand* (the former defines a are somewhat analagous to \newcommand
\long version of the command). and the like, in LaTeX2e. The big differ-
The simple-minded way for a user to ence is the specification of command argu-
write such a command involves use of the ments; for each argument, you have a set
ifthen package: of choices in the command specification.
So, to create a *-command (in LaTeX2e
style), one might write: *}}%
\newcommand{\mycommand}[1]{\ifthenelse{\equal{#1}{
{\mycommandStar}%
\NewDocumentCommand \foo { s m } {%
{\mycommandNoStar{#1}}%
% #1 is the star indicator
}
% #2 is a mandatory argument
\newcommand{\mycommandStar}{starred version}
...
\newcommand{\mycommandNoStar}[1]{normal version}
}
This does the trick, for sufficiently sim-
The “star indicator” (s) argument appears
ple commands, but it has various tire-as #1 and will take values \BooleanTrue
some failure modes, and it requires (if there was a star) or \BooleanFalse
\mycommandnostar to take an argument. (otherwise); the other (m) argument is a nor-
The LaTeX kernel does a lot of this,
mal TeX-style mandatory argument, and
and has its own command, \@ifstar appears as #2.
(which needs ‘internal command protec- While xparse provides pleasing com-
tion’, cf. mand argument specifications, it is part
of the LaTeX 3 experimental harness.
\makeatletter Simply loading the package to pro-
\newcommand{\mycommand}{% vide \DeclareDocumentCommand “pulls
\@ifstar in” all of the LaTeX3 kernel (a large bunch
\mycommandStar%
of packages) via the expl3 package.
\mycommandNoStar%
\makeatother ifthen.sty : Part of the LaTeX
} distribution
\newcommand{\mycommandStar}{starred
suffix.sty : Distributed as part of
version}
\newcommand{\mycommandNoStar}{normal
macros/latex/contrib/bigfoot
version}
199
xparse.sty : Distributed as part Name Type Value
of macros/latex/contrib/ \m@ne count −1
l3packages \p@ dimen 1pt
expl3.sty : Distributed as part of \z@ dimen 0pt
macros/latex/contrib/l3kernel \z@skip skip 0pt plus 0pt minus 0pt
\@ne defn 1
\tw@ defn 2
\thr@@ defn 3
\sixt@@n defn 16
\@cclv defn 255
\@cclvi defn 256
\@m defn 1000
\@M defn 10000
\@MM defn 20000
\@vpt macro 5
\@vipt macro 6
\@viipt macro 7
\@viiipt macro 8
\@ixpt macro 9
\@xpt macro 10
\@xipt macro 10.95
\@xiipt macro 12
\@xivpt macro 14.4
\@xviipt macro 17.28
\@xxpt macro 20.74
\@xxvpt macro 24.88
\@plus macro “plus”
\@minus macro “minus”
356 Defining LaTeX commands
355 LaTeX internal “abbreviations”, within other commands
etc.
LaTeX command definition is significantly
In the deeps of time, when TeX first hap- different from the TeX primitive form dis-
pened, computers had extremely limited cussed in an earlier question about defini-
memory, and were (by today’s standards) tions within macros.
painfully slow. When LaTeX came along, In most ways, the LaTeX situation is
things weren’t much better, and even when simpler (at least in part because it imposes
LaTeX2e appeared, there was a strong im- more restrictions on the user); however,
perative to save memory space (and to a defining a command within a command
lesser extent) CPU time. still requires some care.
From the very earliest days, Knuth The earlier question said you have to
used shortcut macros to speed things double the # signs in command definitions:
up. LaTeX, over the years, has extended in fact, the same rule holds, except that
Knuth’s list by a substantial amount. An LaTeX already takes care of some of the is-
interesting feature of the “abbreviations” sues, by generating argument lists for you.
is that on paper, they may look longer The basic problem is that:
than the thing they stand for; however, to \newcommand{\abc}[1]{joy, oh #1!%
(La)TeX they feel smaller. . . \newcommand{\ghi}[1]{gloom, oh #1!}%
The table at the end of this answer lists }
the commonest of these “abbreviations”. followed by a call:
It is not complete; as always, if the table
doesn’t help, try the LaTeX source. The \cmdinvoke{abc}{joy}
table lists each abbreviation’s name and typesets “joy, oh joy!”, but defines a
its value, which provide most of what a command \ghi that takes one parameter,
user needs to know. The table also lists which it ignores; \ghi{gloom} will ex-
the abbreviation’s type, which is a trickier pand to “gloom, oh joy!”, which is pre-
concept: if you need to know, the only real sumably not what was expected.
confusion is that the abbreviations labelled And (as you will probably guess, if
‘defn’ are defined using an \xxxxdef com- you’ve read the earlier question) the defini-
mand. tion:
200
 we get:
\newcommand{\abc}[1]{joy, oh #1!%
\newcommand{\ghi}[1]{gloom, oh ##1!}%
\foo is 4.21747mm
}

does what is required, and \ghi{gloom} printlen.sty :

will expand to “gloom, oh gloom!”, what- macros/latex/contrib/printlen
ever the argument to \abc. 358 Using labels as counter values
The doubling is needed whether or not Labels are tempting sources of ‘num-
the enclosing command has an argument, bers’ — their most common use, after
so: all, is simply to typeset a number. How-
\newcommand{\abc}{joy, oh joy!% ever, their seeming simplicity is decep-
\newcommand{\ghi}[1]{gloom, ohtive; the packages babel and hyperref , at
##1!}%
} least, fiddle with the definition of \ref and
\pageref in ways that make
is needed to produce a replica of the \ghi
we defined earlier. \setcounter{foo}{\ref{bar}}

357 How to print contents of (etc.) not work; thus the technique may not
variables? be relied upon.
It is often useful to print out the values The solution is to use the refcount
of variables in the log file or on the termi- package (incidentally, by the author of
nal. Three possible ways to print out the hyperref ). The package provides four com-
contents of \textheight variable are: mands, all similar to:

1. \showthe\textheight \usepackage{refcount}
2. \message{The text height is ...
\the\textheight} \label{bar}
3. \typeout{The text height is ...
\the\textheight} \setcounterref{foo}{bar}

These techniques use the TeX primitives (the other three are \addtocounterref,
\the (which provides the value of a vari- \setcounterpageref and \addtocounterpageref).
able), \showthe (print a variable to the ter- The package also provides a command
minal and the log, on a line of its own), and \getrefnumber{label-name} that may
\message, which interpolates something be used where a ‘number’ value is needed.
into the log. The command \typeout is For example:
LaTeX’s general message output mecha-
... \footnote{foo bar ...\label{foofoot}}
nism.
...
In each case, the variable’s value is
\footnotemark[\getrefnumber{foofoot}]
printed as a number of points.
To typeset the value of \textheight, which gives you a second footnote mark
just \the\textheight is enough, but a reference the the footnote. (There is
more flexible alternative is to use the also a command \getpagerefnumber, of
printlen package. Printlen allows you to course).
choose the units in which you print a vari- The commands could be used by one
able; this is useful, given that the most determined not to use changepage to de-
ordinary people don’t think in points (par- termine whether the current page is odd,
ticularly Knuth’s points, of which there are but it’s probably no more trouble to use the
72.27 to the inch). fully-developed tool in this case.
So, using printlen, we could say: refount.sty : Distributed as part of
\newlength{\foo} macros/latex/contrib/oberdiek
\setlength{\foo}{12pt}
R.3 LaTeX macro
\verb|\foo| is \printlength{\foo}
programming
and get:
359 How to change LaTeX’s “fixed
\foo is 12pt names”
LaTeX document classes define several ty-
while, if we say:
pographic operations that need ‘canned
\newlength{\foo} text’ (text not supplied by the user). In
\setlength{\foo}{12pt} the earliest days of LaTeX 2.09 these bits
\uselengthunit{mm} of text were built in to the body of La-
\verb|foo| is \printlength{\foo}TeX’s macros and were rather difficult to
201
change, but “fixed name” macros were in- \renewcommand{\contentsname}%
troduced for the benefit of those wishing to {Indholdsfortegnelse}
use LaTeX in languages other than English. in the preamble of her document.
For example, the special section produced However, it’s natural for a user of a
by the \tableofcontents command is non-English language to use babel, be-
always called \contentsname (or rather, cause it offers many conveniences and
what \contentsname is defined to mean). typesetting niceties for those preparing
Changing the canned text is now one of documents in those languages. In particu-
the easiest customisations a user can do to lar, when babel is selecting a new language,
LaTeX. it ensures that LaTeX’s symbolic names are
The canned text macros are all of the translated appropriately for the language
form \hthing iname, and changing them in question. Unfortunately, babel’s choice
is simplicity itself. Put: of names isn’t always to everyone’s choice,
\renewcommand{\hthing iname} and there is still a need for a mechanism to
{Res minor} replace the ‘standard’ names.
Whenever a new language is selected,
in the preamble of your document, and the babel resets all the names to the settings
job is done. (However, beware of the babel for that language. In particular, babel se-
package, which requires you to use a differ- lects the document’s main language when
ent mechanism: be sure to check changing \begin{document} is executed, which
babel names if you’re using it.) immediately destroys any changes to these
The names that are defined in the stan- symbolic names made in the prologue of a
dard LaTeX classes (and the makeidx pack- document that uses babel.
age) are listed below. Some of the names Therefore, babel defines a command to
are only defined in a subset of the classes enable users to change the definitions of
(and the letter class has a set of names all the symbolic names, on a per-language ba-
of its own); the list shows the specialisation sis: \addto\captionshlanguagei is the
of each name, where appropriate. thing (hlanguagei being the language op-
\abstractname Abstract tion you gave to babel in the first place).
\alsoname see also (makeidx package)
For example:
\appendixname Appendix
\addto\captionsdanish{%
\bibname Bibliography (report,book)
\renewcommand{\contentsname}%
\ccname cc (letter)
{Indholdsfortegnelse}%
\chaptername Chapter (report,book)
}
\contentsname Contents
\enclname encl (letter) 361 Running equation, figure and
\figurename Figure (for captions) table numbering
\headtoname To (letter) Many LaTeX classes (including the stan-
\indexname Index dard book class) number things per chap-
\listfigurename List of Figures ter; so figures in chapter 1 are numbered
\listtablename List of Tables 1.1, 1.2, and so on. Sometimes this is not
\pagename Page (letter) appropriate for the user’s needs.
\partname Part Short of rewriting the whole class, one
\refname References (article) may use the chngcntr package, which pro-
\seename see (makeidx package)vides commands \counterwithin (which
\tablename Table (for caption) establishes this nested numbering relation-
360 Changing the words babel uses ship) and \counterwithout (which un-
does it).
LaTeX uses symbolic names for many
So if you have figures numbered by
of the automatically-generated text it pro-
chapter as 1.1, 1.2, 2.1, . . . , the command
duces (special-purpose section headings,
captions, etc.). As noted in “LaTeX \counterwithout{figure}{chapter}
fixed names” (which includes a list of the
will convert them to figures 1, 2, 3, . . . .
names themselves), this enables the user
(Note that the command has also removed
to change the names used by the standard
the chapter number from the counter’s def-
classes, which is particularly useful if the
inition.)
document is being prepared in some lan-
More elaborate use could change
guage other than LaTeX’s default English.
things numbered per section to things num-
So, for example, a Danish author may wish
bered per chapter:
that her table of contents was called “Ind-
holdsfortegnelse”, and so would expect to \counterwithout{equation}{section}
place a command \counterwithin{equation}{chapter}
202
(assuming there was a class that did such a \stepcounter{foo} that does this spe-
thing in the first place...) cial case of increasing-by-one.
The chngcntr approach doesn’t involve
There’s an internal LaTeX variable, the
much programming, and the enthusias-
“current label”, that remembers the last ‘la-
tic LaTeX programmer might choose to
bellable’ thing that LaTeX has processed.
try the technique that we had to use be-
You could (if you were to insist) set that
fore the advent of chngcntr. Each of the
value by the relevant TeX command (hav-
packages removefr and remreset defines a
ing taken the necessary precautions to en-
\@removefromreset command, and hav-sure that the internal command worked) —
ing included the package one writes some-
but it’s not necessary. If, instead of ei-
thing like: ther of the stepping methods above, you
say \refstepcounter{foo}, the internal
\makeatletter variable is set to the new value, and (until
\@removefromreset{figure}{chapter}
something else comes along), \label will
\makeatother refer to the counter.
and the automatic renumbering stops. You 363 Finding if you’re on an odd or an
may then need to redefine the way in which even page
the figure number (in this case) is printed:
Another question discusses the issue of get-
\makeatletter ting \marginpar commands to put their
output in the correct margin of two-sided
\renewcommand{\thefigure}{\@arabic\c@figure}
\makeatother documents. This is an example of the gen-
eral problem of knowing where a particular
(remember to do the whole job, for every bit of text lies: the output routine is asyn-
counter you want to manipulate, within chronous, and (La)TeX will usually pro-
\makeatletter . . . \makeatother). cess quite a bit of the “next” page before
This technique, too, may be used to deciding to output any page. As a result,
change where in a multilevel structure a the page counter (known internally in La-
counter is reset. Suppose your class num- TeX as \c@page) is normally only reliable
bers figures as hchapteri.hsectioni.hfigurei, when you’re actually in the output routine.
and you want figures numbered per chap- The solution is to use some version of
ter, try: the \label mechanism to determine which
side of the page you’re on; the value of the
\makeatletter
page counter that appears in a \pageref
\@removefromreset{figure}{section}
command has been inserted in the course
\@addtoreset{figure}{chapter}
of the output routine, and is therefore safe.
\renewcommand{\thefigure}{\thechapter.\@arabic\c@figure}
\makeatother
However, \pageref itself isn’t reli-
able: one might hope that
(the command \@addtoreset is a part of
LaTeX itself). \ifthenelse{\isodd{\pageref{foo}}}{odd}{even}

chngcntr.sty : would do the necessary, but both the babel

macros/latex/contrib/chngcntr and hyperref packages have been known
memoir.cls: to interfere with the output of \pageref;
macros/latex/contrib/memoir be careful!
The changepage package needs to
removefr.tex :
provide this functionality for its own
macros/latex/contrib/
use, and therefore provides a command
fragments/removefr.tex (note,
\checkoddpage; this sets a private-use ‘la-
this is constructed as a “fragment”
bel’, and the page reference part of that
for use within other packages: load
label is then examined (in a hyperref -safe
by \input{removefr})
way) to set a conditional \ifoddpage true
remreset.sty : Distributed as part of if the command was issued on an odd
macros/latex/contrib/carlisle page. (The memoir class has the same com-
mand.) LaTeX users who are unfamiliar
362 Making labels from a counter
with TeX’s \if... commands may use
Suppose we have a LaTeX counter, which the ifthen package:
we’ve defined with \newcounter{foo}.
We can increment the value of the counter \usepackage{ifthen,changepage}
by \addtocounter{foo}{1}, but that’s ...
pretty clunky for an operation that hap- \checkoddpage
pens so often . . . so there’s a command \ifthenelse{\boolean{oddpage}}{<odd page stuff>}{<even
203
 Of course, the ‘label’ contributes to La- so the label appears as \thehcounter i —
TeX’s “Rerun to get cross-references right” what would be used if you asked to typeset
error messages. . . the counter in your text. This isn’t always
The Koma-Script classes have an what you need: for example, if you have
addmargin* environment that also pro- nested enumerated lists with the outer num-
vides the sorts of facilities that the bered and the inner labelled with letters,
changepage offers. Koma-Script’s support- one might expect to want to refer to items
ing command: in the inner list as “2(c)”. (Remember, you
\ifthispageodd{<true>}
can change the structure of list items —
{<false>}
change the structure of list items.) The
change is of course possible by explicit la-
executes different things depending on the belling of the parent and using that label to
page number. construct the typeset result — something
The package ifoddpage is designed to like
provide the same facility; crucially, it can
behave “sensibly” even if you are typeset- \ref{parent-item}(\ref{child-item})
ting for one-side printing only; like the
which would be both tedious and error-
changepage it uses a ‘check’ command
prone. What’s more, it would be unde-
\checkoddpage. The conditional ‘side’
sirable, since you would be constructing
flags are set using (Plain) TeX condition-
a visual representation which is inflexible
als; they are defined locally, so that you can
(you couldn’t change all the references to
minimise their use of TeX workspace —
elements of a list at one fell swoop).
see the package documentation for the
LaTeX in fact has a label-formatting
somewhat tricky sequence involved. In
command built into every label defini-
addition the package provides a command
tion; by default it’s null, but it’s available
\ifoddpageoroneside, which is true on
for the user to program. For any label
odd pages of a two-side document, or on
hcounteri there’s a LaTeX internal com-
all pages of a one-side document. Usage
mand \p@hcounter i; for example, a label
is:
definition on an inner list item is suppos-
\checkoddpage edly done using the command \p@enumii
\ifoddpage {\theenumii}. Unfortunately, the inter-
odd-side text nal workings of this aren’t quite right, and
\else you need to patch the \refstepcounter
even-side text command:
\fi
\renewcommand \refstepcounter[1]{\stepcounter{#1}%
*
The author’s recommended usage (trick-
\protected@edef\@currentlabel{%
ily) includes the whole operation in a box;
\csname p@#1\expandafter\endcsname
this has the advantage that your test will
\csname the#1\endcsname
always work, but the usual disadvantage
}%
that boxes may not split. In common uses,
}
the whole work will be done inside a box
(as, for example, in the case of a float), so With the patch in place you can now, for
the elaborate work proposed by the author example, change the labels on all inner
is not necessary. lists by adding the following code in your
changepage.sty : macros/latex/ preamble:
contrib/changepage
\makeatletter
ifoddpage.sty : macros/latex/ \renewcommand{\p@enumii}[1]{\theenumi(#1)}
contrib/ifoddpage \makeatother
ifthen.sty : Part of the LaTeX
This would make the labels for second-
distribution: macros/latex/base
level enumerated lists appear as “1(a)”
KOMA script bundle: (and so on). The analogous change works
macros/latex/contrib/koma- for any counter that gets used in a \label
script command.
memoir.cls: In fact, the fncylab package does all
macros/latex/contrib/memoir the above (including the patch to LaTeX
364 How to change the format of itself). With the package, the code above
labels is (actually quite efficiently) rendered by
the command:
By default, when a label is created, it takes
on the appearance of the counter labelled, \labelformat{enumii}{\theenumi(#1)}
204
In fact, the above example, which we can version for the section, here) specifies
do in several different ways, has been ren- what to put after a section number, but it
dered obsolete by the appearance of the could be used to put anything after it:
enumitem package, which is discussed in
the answer about decorating enumeration \newcommand*{\adddot@section}{.}
lists. Note that all the command definitions
enumitem.sty : above are dealing in LaTeX internal com-
macros/latex/contrib/enumitem mands, so the above code should be in a
fncylab.sty : package file, for preference.
macros/latex/contrib/fncylab The Koma-script classes have
different commands for specifying
365 Adjusting the presentation of changes to section number presenta-
section numbers tion: \partformat, \chapterformat
The general issues of adjusting the appear- and \othersectionlevelsformat, but
ance of section headings are pretty com- otherwise their facilities are similar to
plex, and are covered in question the style those of “raw” LaTeX.
of section headings. KOMA script bundle:
However, people regularly want merely macros/latex/contrib/koma-
to change the way the section number ap- script
pears in the heading, and some such people
don’t mind writing out a few macros. This 366 There’s a space added after my
answer is for them. environment
The section number is typeset using You’ve written your own environment env,
the LaTeX internal \@seccntformat com- and it works except that a space appears at
mand, which is given the “name” (sec- the start of the first line of typeset text af-
tion, subsection, . . . ) of the heading, as ter \end{env}. This doesn’t happen with
argument. Ordinarily, \@seccntformat similar LaTeX-supplied environments.
merely outputs the section number, and You could impose the restriction that
then a \quad of space: your users always put a “%” sign after the
environment . . . but LaTeX environments
\renewcommand*{\@seccntformat}[1]{% don’t require that, either.
\csname the#1\endcsname\quad The LaTeX environments’ “secret” is
} an internal flag which causes the unwanted
Suppose you want to put a stop after ev- spaces to be ignored. Fortunately, you
ery section (subsection, subsubsection, . . . ) don’t have to use the internal form: since
number, a trivial change may be imple- 1996, LaTeX has had a user command
mented by simple modification of the com- \ignorespacesafterend, which sets the
mand: internal flag.
367 Finding if a label is undefined
\renewcommand*{\@seccntformat}[1]{%
\csname the#1\endcsname.\quad People seem to want to know (at run time)
} if a label is undefined (I don’t actually un-
derstand why, particularly: it’s a transient
However, many people want to modify sec- state, and LaTeX deals with it quite well).
tion numbers, but not subsection numbers, A resolved label is simply a command:
or any of the others. To do this, one must \r@hlabel-namei; determining if the la-
make \@seccntformat switch according bel is set is then simply a matter of de-
to its argument. The following technique tecting if the command exists. The usual
for doing the job is slightly wasteful, but is LaTeX internal way of doing this is to use
efficient enough for a relatively rare opera- the command \@ifundefined:
tion:
\@ifundefined{r@label-name}
\renewcommand*{\@seccntformat}[1]{%{undef-cmds}{def-cmds}
\csname the#1\endcsname
In which, hlabel-namei is exactly what you
\csname adddot@#1\endcsname\quad
} would use in a \label command, and the
remaining two arguments are command
which uses a second-level command to pro- sequences to be used if the label is un-
vide the dot, if it has been defined; oth- defined (hundef-cmdsi) or if it is defined
erwise it merely appends \relax (which (hdef-cmdsi).
does nothing in this context). The defi- Note that any command that in-
nition of the second-level command (the corporates \@ifundefined is naturally
205
fragile, so remember to create it with \counterwithin*{corrollary}{theorem}
\DeclareRobustCommand or to use it
with \protect in a moving argument. will make the corollary counter slave to
If you’re into this game, you may theorem counters. The command without
well not care about LaTeX’s warning its asterisk:
about undefined labels at the end of the \counterwithin{corrollary}{theorem}
document; however, if you are, include
the command \G@refundefinedtrue in will do the same, and also rede-
hundef-cmdsi. fine \thecorollary as htheorem num-
And of course, remember you’re deal- beri.hcorollary numberi, which is a good
ing in internal commands, and pay atten- scheme if you ever want to refer to the
tion to the at-signs. corollaries — there are potentially many
All the above can be avoided by us- “corollary 1” in any document, so it’s as
ing the labelcas package: it provides com- well to tie its number to the counter of
mands that enable you to switch according the theorem it belongs to. This is true
to the state of a single label, or the states of pretty much any such counter-within-
of a list of labels. The package’s definition another; if you’re not using the chngcntr,
is a bit complicated, but the package itself refer to the answer to redefining counters’
is pretty powerful. \the-commands for the necessary tech-
niques.
labelcas.sty :
Note that the technique doesn’t work
macros/latex/contrib/labelcas
if the master counter is page, the num-
368 Master and slave counters ber of the current page. The page counter
It’s common to have things numbered “per is stepped deep inside the output routine,
chapter” (for example, in the standard book which usually gets called some time after
and report classes, figures, tables and foot- the text for the new page has started to ap-
notes are all numbered thus). The process pear: so special techniques are required to
of resetting is done automatically, when deal with that. One special case is dealt
the “master” counter is stepped (when the with elsewhere: footnotes numbered per
\chapter command that starts chapter hni page. One of the techniques described
happens, the chapter counter is stepped, there, using package perpage, may be ap-
and all the dependent counters are set to plied to any counter. The command:
zero).
\MakePerPage{counter}
How would you do that for yourself?
You might want to number algorithms per will cause hcounteri to be reset for each
section, or corollaries per theorem, for ex- page. The package uses a label-like mech-
ample. If you’re defining these things by anism, and may require more than one run
hand, you declare the relationship when of LaTeX to stabilise counter values — La-
you define the counter in the first place: TeX will generate the usual warnings about
labels changing.
\newcounter{new-name}
[master] chngcntr.sty :
macros/latex/contrib/chngcntr
says that every time counter hmasteri is
perpage.sty : Distributed as part
stepped, counter hnew-namei will be reset.
macros/latex/contrib/bigfoot
But what if you have an uncooperative
package, that defines the objects for you, 369 Fonts at arbitrary sizes
but doesn’t provide a programmer inter- Almost all fonts, nowadays, are pro-
face to make the counters behave as you vided with LaTeX control (.fd) files, so
want? the temptation to risk the problems of
The \newcounter command uses a \newfont is usually easy to resist.
LaTeX internal command, and you can However, one temptation remains, aris-
also use it: ing from the way that LaTeX restricts the
\@addtoreset{new-name}
sizes of fonts. In fact, the restriction only
{master}
significantly applies to the default (Com-
puter Modern) and the Cork-encoded (T1)
(but remember that it needs to be between EC fonts, but it is widely considered to
\makeatletter and \makeatother, or in be anomalous, nowadays. In recognition
a package of your own). of this problem, there is a package fix-cm
The chngcntr package encapsulates the which will allow you to use the fonts,
\@addtoreset command into a command within LaTeX, at any size you choose. If
\counterwithin. So: you’re not using scaleable versions of the
206
fonts, most modern distributions will just
However, it’s always difficult to re-
generate an appropriate bitmap for you.
member the things you should not do,
when there are so many things to remember
So, suppose you want to produce a
heading in Computer Modern Roman atthat you really must do: some automation
is useful. . . .
30 points, you might be tempted to write:
The nicely-named nag allows you to
\newfont{\bigfont}{cmr10 at 30pt}
apply a configurable set of checks to your
\begin{center} document, as you run it through LaTeX;
\bigfont Huge text you get messages like:
\end{center}
Package nag Warning: Command \bf is an old LaTeX 2.09 c
which will indeed work, but will actually (nag) Use \bfseries or \textbf instead o
produce a worse result than
(the package provides a demo file which
\usepackage{fix-cm} contains most of the sorts of errors you
... might make — the example is one of them).
\begin{center} While l2tabu and nag alert you to possible
\fontsize{30}{36}\selectfont programming errors, you should not forget
Huge text that they are merely commenting on style;
\end{center} don’t assume that a nag error is going to
Note that the fix-cm package was not dis- damn your code — rather, note the issue
tributed until the December 2003 edition and try to train your fingers not to do the
of LaTeX; if you have an older distribution, same “next time”.
the packages type1cm (for CM fonts) and The lacheck program analyses your
type1ec (for EC fonts) are available. source and comments on it; its view of
Fix-cm doesn’t has one or two omis- what is “bad” is very subjective (the docu-
sions — fonts the LaTeX team did not con- mentation says), but it can be useful.
sider useful, or something; the CM dunhill There’s also a web site TeXidate which
fonts (as CM, but with stretched ascenders) will do a static analysis of your document
and the CM fibonacci font (which is only (unfortunately, you have to paste your doc-
available in 8-point design size) are cer- ument source into a text window). The site
tainly missing. If fix-cm doesn’t do the job,doesn’t seem as comprehensive as nag, but
try the type1xx packages, or the anyfontsize it allows you to download its script, which
package. you can then juggle with to make it more
A further alternative might be to switchdraconian.
to the Latin Modern fonts (which provide a l2tabu: Browse info/l2tabu for a
close simulacrum of the Computer Modern copy of the document in a language
set); these fonts were scaleable from their that is convenient for you
first distribution, and don’t therefore need lacheck : support/lacheck
any such trick as the above.
nag.sty : macros/latex/contrib/nag
anyfontsize.sty : macros/latex/
contrib/anyfontsize 371 Process a CSV file in LaTeX
fix-cm.sty : Distributed as part Comma-separated-variable (CSV) files are
of macros/latex/base (an a common means of interchanging simple
unpacked version is available at data between applications; for example,
macros/latex/unpacked/fix- most spreadsheet applications can provide
cm.sty) files containing tables of numbers with
commas between them. One can envis-
Latin Modern fonts: fonts/lm
age these tables as “LaTeX tables”, and the
type1cm.sty : packages to process them all provide table
macros/latex/contrib/type1cm generation, one way or another.
type1ec.sty : fonts/ps-type1/cm- For rather a long time, the canoni-
super/type1ec.sty (the cal tools for dealing with such files have
package is actually part of the been those provided in the datatool bundle;
fonts/ps-type1/cm-super packages in the bundle allow the user to
distribution, but it works happily in write procedures to process numbers, cur-
the absence of the scaled fonts) rency amounts, names, etc., and to display
them in tables (including pie charts).
370 The quality of your LaTeX The csvsimple does similar tasks. Its
The l2tabu tutorial (mentioned in online processing is controlled by keys estab-
introductions) is undoubtedly a good read. lished via the pgfkeys package, which de-
207
fine how each row of the CSV file is to be the defaults in Knuth’s WEB source; but if
processed. you do need to do so, use a change file to
For usage “nearer to the bone”, modify the values set in module 11, recom-
one might consider the commands pile your TeX and regenerate all format
\docsvlist and \forcsvlist (from the files.
etoolbox package). The first uses the time- Modern implementations allow the
honoured LaTeX technique of changing sizes of the various bits of TeX’s memory
the definition of a \do command; it runs to be changed semi-dynamically. Some
through the list, and processes every item (such as emTeX) allow the memory pa-
of the list as the argument of the \do com- rameters to be changed in command-line
mand; so: switches when TeX is started; most fre-
quently, a configuration file is read which
\begin{itemize} specifies the size of the memory. On
\renewcommand*{\do}[1]{\item #1}web2c-based systems, this file is called
\docsvlist{item1, item2, {item3a, item3b},
texmf.cnf item4}
: see the documentation that
\end{itemize} comes with the distribution for other imple-
mentations. Almost invariably, after such
will convert the elements of a CSV list into
a change, the format files need to be regen-
an itemised list.
erated after changing the memory parame-
The macro \forcsvlist applies a
ters.
function to each element of a CSV list;
this can of course be used to implement 373 Why can’t I load PiCTeX?
\docsvlist, at the cost of a little clarity. PiCTeX is a resource hog; fortunately,
csvsimple.sty : macros/latex/ most modern TeX implementations offer
contrib/csvsimple generous amounts of space, and most mod-
ern computers are pretty fast, so users
datatool bundle:
aren’t too badly affected by its perfor-
macros/latex/contrib/datatool
mance.
etoolbox.sty : However, PiCTeX has the further un-
macros/latex/contrib/etoolbox fortunate tendency to fill up TeX’s fixed-
pgfkeys.sty : Distributed as part of size arrays — notably the array of 256
graphics/pgf/base ‘dimension’ registers. This is a particular
problem when you’re using pictex.sty
with LaTeX and some other packages that
S Things are Going also need dimension registers. When this
happens, you will see the TeX error mes-
Wrong. . . sage:

S.1 Getting things to fit ! No room for a new \dimen.

372 Enlarging TeX There is nothing that can directly be done

about this error: you can’t extend the num-
The TeX error message ‘capacity exceeded’
ber of available \dimen registers without
covers a multitude of problems. What has
extending TeX itself. Omega and e-TeX
been exhausted is listed in brackets after
both do this.
the error message itself, as in:
It’s actually quite practical (with most
! TeX capacity exceeded, sorry modern distributions) to use e-TeX’s ex-
... [main memory size=263001]. set: use package etex
tended register
(which comes with e-TeX distributions)
Most of the time this error can be fixed and the allocation mechanism is altered to
without enlarging TeX. The most common cope with the larger register set: PiCTeX
causes are unmatched braces, extra-long will now load.
lines, and poorly-written macros. Extra- If you’re in some situation where you
long lines are often introduced when files can’t use e-TeX, you need to change
are transferred incorrectly between oper- PiCTeX; unfortunately PiCTeX’s author
ating systems, and line-endings are not is no longer active in the TeX world, so
preserved properly (the tell-tale sign of an one must resort to patching. There are two
extra-long line error is the complaint that solutions available.
the ‘buf_size’ has overflowed). The ConTeXt module m-pictex.tex
If you really need to extend your TeX’s (for Plain TeX and variants) or the corre-
capacity, the proper method depends on sponding LaTeX m-pictex package provide
your installation. There is no need (with an ingenious solution to the problem based
modern TeX implementations) to change on hacking the code of \newdimen itself.
208
 Alternatively, Andreas Schrell’s usually satisfactory, but you can rea-
pictexwd and related packages replace sonably change it (for example, to add
PiCTeX with a version that uses 33 fewer an “h”). Whatever you do, don’t omit
\dimen registers; so use pictexwd in place the “p”: doing so could cause LaTeX
of pictex (either as a LaTeX package, or as to believe that if you can’t have your
a file to read into Plain TeX). figure here, you don’t want it any-
And how does one use PiCTeX anyway, where. (LaTeX does try to avoid being
given that the manual is so hard to come confused in this way. . . )
by? Fortunately for us all, the MathsPic • LaTeX’s own float placement parame-
system may be used to translate a some- ters could be preventing placements
what different language into PiCTeX com- that seem entirely “reasonable” to
mands; and the MathsPic manual is free you — they’re notoriously rather con-
(and part of the distribution). MathsPic servative. To encourage LaTeX not
is available either as a Basic program for to move your figure, you may need to
DOS, or as a Perl program for other sys- loosen its demands. (The most impor-
tems (including Windows, nowadays). tant ones are the ratio of text to float on
etex.sty : a given page, but it’s sensible to have
macros/latex/contrib/etex-pkg a fixed set that changes the whole lot,
to meet every eventuality.)
m-pictex.sty : Distributed as part of
\renewcommand{\topfraction}{.85}
macros/context/current/cont-
\renewcommand{\bottomfraction}{.7}
tmf.zip
\renewcommand{\textfraction}{.15}
m-pictex.tex : Distributed as part of \renewcommand{\floatpagefraction}{.66}
macros/context/current/cont- \renewcommand{\dbltopfraction}{.66}
tmf.zip \renewcommand{\dblfloatpagefraction}{.66}
MathsPic: graphics/mathspic \setcounter{topnumber}{9}
\setcounter{bottomnumber}{9}
pictexwd.sty : Distributed as part of
\setcounter{totalnumber}{20}
graphics/pictex/addon
\setcounter{dbltopnumber}{9}
S.2 Making things stay where The meanings of these parameters
you want them are described on pages 199–200, sec-
374 Moving tables and figures in tion C.9 of the LaTeX manual.
LaTeX • Are there places in your document
where you could ‘naturally’ put a
Tables and figures have a tendency to sur- \clearpage command? If so, do:
prise, by floating away from where they the backlog of floats is cleared af-
were specified to appear. This is in fact ter a \clearpage. (Note that the
perfectly ordinary document design; any \chapter command in the standard
professional typesetting package will float book and report classes implicitly ex-
figures and tables to where they’ll fit with- ecutes \clearpage, so your floats
out violating the certain typographic rules. can’t wander past the end of a chap-
Even if you use the placement specifier ”h” ter.)
(for ‘here’), the figure or table will not be • Try the placeins package: it defines
printed ‘here’ if doing so would break the a \FloatBarrier command beyond
rules; the rules themselves are pretty sim- which floats may not pass. A package
ple, and are given on page 198, section C.9 option allows you to declare that floats
of the LaTeX manual. In the worst case, may not pass a \section command,
LaTeX’s rules can cause the floating items but you can place \FloatBarriers
to pile up to the extent that you get an error wherever you choose.
message saying “Too many unprocessed • If you are bothered by floats appearing
floats”. What follows is a simple checklist at the top of the page (before they are
of things to do to solve these problems (the specified in your text), try the flafter
checklist talks throughout about figures, package, which avoids this problem
but applies equally well to tables, or to by insisting that floats should always
“non-standard” floats defined by the float appear after their definition.
or other packages). • Have a look at the LaTeX2e afterpage
• Do your figures need to float at all? If package. Its documentation gives
not, look at the recommendations for as an example the idea of putting
“non-floating floats” \clearpage after the current page
• Are the placement parameters on your (where it will clear the backlog, but
figures right? The default (“tbp”) is not cause an ugly gap in your text), but
209
 also admits that the package is some- tinue to require underlining of us, so La-
what fragile. Use it as a last resort TeX as distributed defines an \underline
if the other possibilities below don’t command that applies the mathematical
help. ‘underbar’ operation to text. This technique
• If you would actually like great blocks is not entirely satisfactory, however: the
of floats at the end of each of your text gets stuck into a box, and won’t break
chapters, try the morefloats package; at line end.
this allows you to increase the num- Two packages are available that solve
ber of floating inserts that LaTeX can this problem. The ulem package redefines
handle at one time (from its original the \emph command to underline its argu-
value of 18, in LaTeX2e). Note that, ment; the underlined text thus produced
even with e-TeX’s greater supply of behaves as ordinary emphasised text, and
registers, there is still a modest limit will break over the end of a line. (The pack-
on the total number of floating inserts age is capable of other peculiar effects, too:
(e-TeX increases the total number of read its documentation.) The soul package
registers available, but inserts don’t defines an \ul command (after which the
work if they are constructed from reg- package is, in part, named) that underlines
isters in the extended range). running text.
Caveat: if you are using etex to in- Beware of ulem’s default behaviour,
crease the number of registers avail- which is to convert the \emph command
able, you need to “reserve” some in- into an underlining command; this can be
serts for morefloats: something like: avoided by loading the package with:
\usepackage{etex} \usepackage[normalem]{ulem}
\reserveinserts{18}
\usepackage{morefloats} ulem.sty :
macros/latex/contrib/ulem
• If you actually wanted all your figures
to float to the end (e.g., for submitting soul.sty :
a draft copy of a paper), don’t rely on macros/latex/contrib/soul
LaTeX’s mechanism: get the endfloat
376 Controlling widows and orphans
package to do the job for you.
Widows (the last line of a paragraph at the
afterpage.sty : Distributed as part of start of a page) and orphans (the first line
macros/latex/required/tools of paragraph at the end of a page) interrupt
endfloat.sty : the reader’s flow, and are generally consid-
macros/latex/contrib/endfloat ered “bad form”; (La)TeX takes some pre-
cautions to avoid them, but completely au-
etex.sty :
tomatic prevention is often impossible. If
macros/latex/contrib/etex-pkg
you are typesetting your own text, consider
flafter.sty : Part of the LaTeX whether you can bring yourself to change
distribution the wording slightly so that the page break
float.sty :
will fall differently.
macros/latex/contrib/float
The (La)TeX page maker, when
forming a page, takes account of vari-
morefloats.sty : macros/latex/ ables \widowpenalty and \clubpenalty
contrib/morefloats (which relates to orphans!). These penal-
placeins.sty : ties are usually set to the moderate
macros/latex/contrib/placeins value of 150; this offers mild discour-
agement of bad breaks. You can in-
375 Underlined text won’t break crease the values by saying (for example)
Knuth made no provision for underlining \widowpenalty=500; however, vertical
text: he took the view that underlining lists (such as pages are made of) typically
is not a typesetting operation, but rather have rather little stretchability or shrinka-
one that provides emphasis on typewriters, bility, so if the page maker has to balance
which typically offer but one typeface. The the effect of stretching the unstretchable
corresponding technique in typeset text is and being penalised, the penalty will sel-
to switch from upright to italic text (or vice- dom win. Therefore, for typical layouts,
versa): the LaTeX command \emph does there are only two sensible settings for the
just that to its argument. penalties: finite (150 or 500, it doesn’t mat-
Nevertheless, typographically illiterate ter which) to allow widows and orphans,
people (such as those that specify double- and infinite (10000 or greater) to forbid
spaced thesis styles — thesis styles) con- them.
210
 The problem can be avoided by allow- rawfonts package (which is part of the La-
ing the pagemaker to run pages short, by TeX2e distribution).
using the \raggedbottom directive; how-
378 Missing symbol commands
ever, many publishers insist on the default
\flushbottom; it is seldom acceptable to You’re processing an old document, and
introduce stretchability into the vertical list, some symbol commands such as \Box and
except at points (such as section headings) \lhd appear no longer to exist. These
where the document design explicitly per- commands were present in the core of La-
mits it. TeX 2.09, but are not in current LaTeX.
Once you’ve exhausted the automatic They are available in the latexsym package
measures, and have a final draft you want (which is part of the LaTeX distribution),
to “polish”, you should proceed to manual and in the amsfonts package (which is part
measures. To get rid of an orphan is simple: of the AMS distribution, and requires AMS
precede the paragraph with \clearpage symbol fonts).
and the paragraph can’t start in the wrong AMS fonts: fonts/amsfonts
place.
379 Where are the msx and msy fonts?
Getting rid of a widow can be more
tricky. Options are The msx and msy fonts were designed
by the American Mathematical Society
• If the previous page contains a long in the very early days of TeX, for use in
paragraph with a short last line, it typesetting papers for mathematical jour-
may be possible to set it ‘tight’: nals. They were designed using the ‘old’
write \looseness=-1 immediately Metafont, which wasn’t portable and is no
after the last word of the paragraph. longer available; for a long time they were
• If that doesn’t work, adjusting the only available in 300dpi versions which
page size, using \enlargethispage only imperfectly matched modern printers.
{\baselineskip} to ‘add a line’ to The AMS has now redesigned the fonts,
the page, which may have the effect using the current version of Metafont, and
of getting the whole paragraph on one the new versions are called the msa and
page. msb families.
• Reducing the size of the Nevertheless, msx and msy continue to
page by \enlargethispage turn up. There may, of course, still be sites
{-\baselineskip} may produce a that haven’t got around to upgrading; but,
(more-or-less) acceptable “two-line even if everyone upgraded, there would
widow”. still be the problem of old documents that
specify them.
Note that \looseness=1 (which should If you have a .tex source that requests
increase the line length by one) seldom msx and msy, the best technique is to edit
has the right effect — the looser paragraph it so that it requests msa and msb (you only
typically has a one-word final line, which need to change the single letter in the font
doesn’t look much better than the original names).
widow. A partial re-implementation of the
blackboard-bold part of the msy font (cov-
S.3 Things have “gone away” ering C, N, R, S and Z, only) is available in
377 Old LaTeX font references such Type 1 format; if your mathematical needs
as \tenrm only extend that far, the font could be a
good choice.
LaTeX 2.09 defined a large set of com- If you have a DVI file that requests the
mands for access to the fonts that it fonts, there is a package of virtual fonts to
had built in to itself. For example, cmr map the old to the new series.
might appear as \fivrm, \sixrm, \sevrm,
\egtrm, \ninrm, \tenrm, \elvrm, msam & msbm fonts: Distributed as part
\twlrm, \frtnrm, \svtnrm, \twtyrm and of fonts/amsfonts
\twfvrm, according to the size it’s being msym fonts: fonts/msym
typeset at. These commands were never virtual font set:
documented, but certain packages never- fonts/vf-files/msx2msa
theless used them to achieve effects they
needed. 380 Where are the am fonts?
Since the commands weren’t public, One still occasionally comes across a re-
they weren’t included in LaTeX2e; to use quest for the am series of fonts. The ini-
the unconverted LaTeX 2.09 packages un- tials stood for ‘Almost [Computer] Mod-
der LaTeX2e, you need also to include the ern’, and they were the predecessors of the
211
Computer Modern fonts that we all know ported to, so there was a premium on re-
and love (or hate)3 . There’s not a lot one ducing the size of executables. One way
can do with these fonts; they are (as their of doing this was to have a separate ex-
name implies) almost (but not quite) the ecutable, initex, that had things in it that
same as the cm series; if you’re faced with aren’t needed in ordinary document runs —
a document that requests them, the only notably \patterns (which builds hyphen-
reasonable approach is to edit the docu- ation tables), and \dump (which writes out
ment to replace am* font names with cm*. a format).
The appearance of DVI files that re- On modern systems, the size of this
quest them is sufficiently rare that no-one code is insignificant in comparison to the
has undertaken the mammoth task of cre- memory available, and maintaining sepa-
ating a translation of them by means of rate programs has been found sufficiently
virtual fonts. error-prone that free Unix-style system
You therefore have to fool the system distributions have abolished initex and its
into using cm* fonts where the original friends and relations such as inipdftex in
author specified am*. favour of a single executable (that is, just
One option is the font substitutions that tex or pdftex) that will “do what initex (or
many DVI drivers provide via their config- whatever) used to do” if it detects the com-
uration file — specify that every am font mand option “-ini”.
should be replaced by its corresponding The change happened with the advent
cm font. of teTeX version 3.0, which appeared at the
Alternatively, one may try DVI edit- beginning of 2005. At that time, TeX Live
ing — packages dtl (DVI Text Language) was following teTeX, so that year’s TeX
and dviasm (DVI assembler) can both pro- Live distribution would also have dropped
vide round trips from DVI to text and back initex.
to DVI. One therefore edits font names It would appear that the equation is
(throughout the text representation of the somewhat different for the MiKTeX devel-
file) in the middle of that round trip. opers, since that system continues to offer
The DTL text is pretty straightforward, an initex executable.
for this purpose: fontnames are in single
quotes at the end of lines, so:
T Why does it do that?
dv2dt -o hdoc.txti hdoc.dvii
(edit the .txt file) T.1 Common errors
dt2dv -o hedited.dvii
hedited.txti 382 LaTeX gets cross-references
wrong
(you have to compile the C programs for Sometimes, however many times you run
this). LaTeX, the cross-references are just wrong.
Dviasm is a Python script; its output A likely reason is that you have placed the
has font names in a section near the start label before the data for the label was set;
of the document, and then dotted about if the label is recording a \caption com-
through the body, so: mand, the \label command must appear
python dviasm.py -o after the \caption command, or be part
hdoc.txti hdoc.dvii of it. For example:
(edit the .txt file) \begin{figure}
python dviasm.py -o <the illustration itself>
hedited.dvii hedited.txti \caption{My figure}
Both routes seem acceptable ways forward; \label{myfig}
it is a matter of taste which any particular \end{figure}
user may choose (it’s not likely that it will is correct, as is
be necessary very often...).
\begin{figure}
dviasm.py : dviware/dviasm
<the illustration itself>
dtl: dviware/dtl \caption{My figure%
381 What’s happened to initex? \label{myfig}}
\end{figure}
In the beginning, (La)TeX was stretch-
ing the capacity of every system it was whereas, in

3 The fonts acquired their label ‘Almost’ following the realisation that their first implementation in Meta-

font79 still wasn’t quite right; Knuth’s original intention had been that they were the final answer.
212
 \begin{figure} This particular example could be coded
<the illustration itself> (without any problems) in verbatim, but
\label{myfig} the behaviour does confuse people.
\caption{My figure} The problem also appears in maths
\end{figure} mode, in arrays and so on. In this case,
large-scale bracketing of things is not
the label will report the number of the sec- a good idea; the TeX primitive \relax
tion (or whatever) in which the surround- (which does nothing except to block
ing text resides, or the like. searches of this nature) may be used. From
You can, with the same malign effect, another comp.text.tex example:
shield the \caption command from its as-
sociated \label command, by enclosing \begin{eqnarray}
the caption in an environment of its own. [a] &=& b \\
This effect will be seen with: \relax[a] &=& b
\end{eqnarray}
\begin{figure}
<the illustration itself> which is a usage this FAQ would not rec-
\caption{A Figure} ommend, anyway: refer to the reason not
\end{figure} to use eqnarray.
\label{myfig} Note that the amsmath package mod-
ifies the behaviour of \\ in maths. With
where the \label definitely is after the amsmath, the eqnarray example doesn’t
\caption, but because the figure envi-
need any special action (\relax or
ronment closed before the \label com- braces).
mand, the \caption is no longer “visible”.
In summary, the \label must be af- 384 Why doesn’t verbatim work
ter the command that defines it (e.g., within . . . ?
\caption), and if the \caption is inside The LaTeX verbatim commands work by
an environment, the \label must be in changing category codes. Knuth says of
there too. this sort of thing “Some care is needed
383 Start of line goes awry to get the timing right. . . ”, since once the
category code has been assigned to a char-
This answer concerns two sorts of prob- acter, it doesn’t change. So \verb and
lems: errors of the form \begin{verbatim} have to assume that
! Missing number, treated as zero. they are getting the first look at the param-
<to be read again> eter text; if they aren’t, TeX has already
p assigned category codes so that the verba-
<*> [perhaps] tim command doesn’t have a chance. For
example:
and errors where a single asterisk at the
start of a line mysteriously fails to appear \verb+\error+
in the typeset output. will work (typesetting ‘\error’), but if we
Both problems arise because \\ takes define no more than a no-op macro,
optional arguments. The command \\*
means “break the line here, and inhibit \newcommand{\unbrace}[1]{#1}
page break following the line break”; the
command \\[hdimeni] means “break the which simply regurgitates its argument,
line here and add hdimeni extra vertical and use it as:
space afterwards”. \unbrace{\verb+\error+}
The problem arises because \\ looks
for the next non-blank thing; the test it the combinartion will not (it will attempt to
uses ignores the end of the line in your in- execute \error). Other errors one may en-
put text, so that \\ comes to imagine that counter are ‘\verb ended by end of line’,
you were giving it a ‘modifier’. or even the rather more helpful ‘\verb ille-
An obvious solution is to enclose the gal in command argument’. The same sorts
stuff at the start of the new line in braces, of thing happen with \begin{verbatim}
typing: . . . \end{verbatim}:
{\ttfamily \ifthenelse{\boolean{foo}}{%
/* C-language comment\\ \begin{verbatim}
{[perhaps]} this could be done better\\
foobar
{*}/ \end{verbatim}
} }{%
213
 \begin{verbatim} \NewDocumentCommand\cmd{ m v m }{#1 ‘#2’ #3}
barfoo \cmd{Command }|\furble|{ isn’t defined}
\end{verbatim}
} Which gives us:

provokes errors like ‘File ended while Command \furble isn’t defined
scanning use of \@xverbatim’, as \begin
{verbatim} fails to see its matching \end The “m” tag argument specifies a normal
{verbatim}. mandatory argument, and the “v” speci-
This is why the LaTeX book insists fies one of these verbatim arguments. As
that verbatim commands must not appear you see, it’s implanting a \verb-style com-
in the argument of any other command; mand argument in the argument sequence
of an otherwise “normal” sort of command;
they aren’t just fragile, they’re quite unus-
able in any “normal” command parameter, that ‘|’ may be any old character that
regardless of \protection. (The \verb doesn’t conflict with the content of the ar-
command tries hard to detect if you’re mis- gument.
using it; unfortunately, it can’t always do This is pretty neat (even if the verba-
so, and the error message is therefore not tim is in an argument of its own) but the
reliable as an indication of problems.) downside is that xparse pulls in the experi-
mental LaTeX3 programming environment
The first question to ask yourself is: “is
\verb actually necessary?”. (l3kernel) which is pretty big.
Other than the cprotect package, there
• If \texttt{your text} produces are four partial solutions to the problem:
the same result as \verb+your
text+, then there’s no need of \verb • Some packages have macros which
in the first place. are designed to be responsive to ver-
• If you’re using \verb to typeset a batim text in their arguments. For ex-
URL or email address or the like, then ample, the fancyvrb package defines
the \url command from the url will a command \VerbatimFootnotes,
help: it doesn’t suffer from all the which redefines the \footnotetext
problems of \verb, though it’s still command, and hence also the be-
not robust; “typesetting URLs” offers haviour of the \footnote) command,
advice here. in such a way that you can in-
• If you’re putting \verb into the argu- clude \verb commands in its ar-
ment of a boxing command (such as gument. This approach could in
\fbox), consider using the lrbox en- principle be extended to the argu-
vironment: ments of other commands, but it can
clash with other packages: for exam-
\newsavebox{\mybox}
ple, \VerbatimFootnotes interacts
...
poorly with the para option of the
\begin{lrbox}{\mybox}
footmisc package.
\verb!VerbatimStuff!
The memoir class defines its
\end{lrbox}
\footnote command so that it will
\fbox{\usebox{\mybox}}
accept verbatim in its arguments, with-
If you can’t avoid verbatim, the out any supporting package.
\cprotect command (from the package
• The fancyvrb package defines a com-
cprotect) might help. The package man- mand \SaveVerb, with a correspond-
ages to make a macro read a verbatim ar- ing \UseVerb command, that allow
gument in a “sanitised” way by the sim- you to save and then to reuse the con-
ple medium of prefixing the macro with tent of its argument; for details of this
\cprotect:
extremely powerful facility, see the
package documentation.
\cprotect\section{Using \verb|verbatim|} Rather simpler is the verbdef pack-
age, whose \verbdef command de-
The package does work in this simple case, fines a (robust) command which ex-
and deserves consideration in many others pands to the verbatim argument given;
cases; the package documentation gives the newverbs package provides a simi-
more details. lar function as well as several related
Another way out is to use ones.
one of “argument types” of the • In a similar vein, the verbatimbox
\NewDocumentCommand command in the package makes it possible to put ver-
experimental LaTeX3 package xparse: batim material in a box:
214
 \begin{verbbox} doesn’t provide an anonynous file.
some exotic _&$ stuff Macros, to achieve the same effect, are
\end{verbbox} outlined in the documentation of the
\theverbbox verbatim package; the macros use the
the operation typesets exotic stuff into facilities of the package, but the user
an anonymous box, and its contents has to write a mini-package actually
may be retrieved using the command to use them.
\theverbbox. It is clear that it’s in cprotect.sty :
the same mould as the \verbdef com- macros/latex/contrib/cprotect
mand mentioned above; the package
defines other similar commands. fancyvrb.sty :
• The tcolorbox package provides a sim- macros/latex/contrib/fancyvrb
ilar facility l3kernel bundle:
• If you have a single character that macros/latex/contrib/l3kernel
is giving trouble (in its absence you memoir.cls:
could simply use \texttt), con- macros/latex/contrib/memoir
sider using \string. \texttt
{my\string_name} typesets the same newverbs.sty :
as \verb+my_name+, and will work in macros/latex/contrib/newverbs
the argument of a command. It won’t, tcolorbox.sty : macros/latex/
however, work in a moving argument, contrib/tcolorbox
and no amount of \protection will url.sty : macros/latex/contrib/url
make it work in such a case.
A robust alternative is: verbatim.sty :
macros/latex/required/tools
\chardef\us=‘\_
... verbatimbox.sty : macros/latex/
\section{... \texttt{my\us name}}contrib/verbatimbox
Such a definition is ‘naturally’ robust; verbdef.sty :
macros/latex/contrib/verbdef
the construction “hback-ticki\hchar i”
may be used for any troublesome char- xparse.sty : Distributed as part
acter (though it’s plainly not neces- of macros/latex/contrib/
sary for things like percent signs for l3packages
which (La)TeX already provides ro-
385 “No line here to end”
bust macros).
• One may also consider putting verba- The error
tim material in an external file; this is
! LaTeX Error: There’s no line here to end.
somewhat more tedious, but the file
may be reused several times within a
See the LaTeX manual or LaTeX Companion for explanation
single document. The tcolorbox per-
mits this: appears when you give LaTeX a \\ com-
\begin{tcbverbatimwrite}{<file mand at a time when it’s not expecting it;
name>}
... it is a line-breaking command, and is con-
\end{tcbverbatimwrite} fused if LaTeX isn’t building a paragraph
when you give the command. A common
which (as one might guess) writes to case is where you’ve decided you want the
the named file; load the saved contents label of a list item to be on a line of its own,
using \input{<file name>} and written (for example):
A second environment puts your ver-
batim material in an (apparently) \begin{description}
anonymous temporary file: \item[Very long label] \\
\begin{tcbwritetemp}{<file name>} Text...
... \end{description}
\end{tcbverbatimwrite}
The proper solution to the problem is to
In this case, you use the anonymous write a new sort of description environ-
file with the \tcbusetemp macro. ment, that does just what you’re after. (The
(You can change the name used for the LaTeX Companion — see LaTeX Compan-
‘anonymous’ file, if its default proves ion — offers a rather wide selection of
troublesome.) variants of these things.)
The moreverb package provides a A straightforward solution, which
\verbatimwrite command, which avoids the warning, is to write:
215
 \begin{description} material around them. Meanwhile, there
are parameters
\item[Very long label] \leavevmode \\ provided to adjust the spac-
Text... ing between floating environments and
\end{description} their surroundings; so if we have:
which starts a paragraph before forcing a \begin{figure}
break. The expdlist package provides the \begin{center}
same functionality with its \breaklabel \includegraphics{...}
command, and mdwlist provides it via its \caption{...}
\desclabelstyle command. \end{center}
The other common occasion for the \end{figure}
message is when you’re using the center
(or flushleft or flushright) environ- or worse still:
ment, and have decided you need extra \begin{figure}
separation between lines in the environ- \begin{center}
ment: \includegraphics{...}
\end{center}
\begin{center}
\caption{...}
First (heading) line\\
\end{figure}
\\
body of the centred text... unwarranted vertical space is going to ap-
\end{center} pear.
The solution here is plain: use the \\ The solution is to let the float and the
command in the way it’s supposed to be objects in it position themselves, and to
used, to provide more than just a single use “generic” layout commands rather than
line break space. \\ takes an optional ar- their list-based encapsulations.
gument, which specifies how much extra \begin{figure}
space to add; the required effect in the text
\centering
above can be had by saying: \includegraphics{...}
\caption{...}
\begin{center}
\end{figure}
First (heading) line\\[\baselineskip]
body of the centred text... (which even involves less typing).
\end{center} This alternative code will work with
You can use \leavevmode, as above: any LaTeX package. It will not work
with obsolete (pre-LaTeX2e) packages
\begin{center} such as psfig or epsf — see graphics in-
First (heading) line\\ clusion for discussion of the genesis of
\leavevmode\\ \includegraphics.
body of the centred text...
387 Why is my table/figure/. . . not
\end{center}
centred?
but that is just as tiresome to type as \\ You want a float whose contents are cen-
with an optional argument, and can not be tred, but LaTeX ignores your center envi-
recommended. ronment. Most likely, you have written:
expdlist.sty :
\begin{center}
macros/latex/contrib/expdlist
\begin{figure}
mdwlist.sty : Distributed as part of ...
macros/latex/contrib/mdwtools \end{figure}
386 Extra vertical space in floats \end{center}

A common complaint is that extra verti- In this case, LaTeX has “taken the figure
cal space has crept into figure or table away”, and will typeset it at some location
floating environments. More common still it fancies (it does the same with tables)
are users who post code that introduces the only thing we can say (for sure) about
this extra space, and haven’t noticed the the location is that it won’t be inside that
problem! center environment. As a result, the
The trouble arises from the fact that center environment is left with nothing
the center environment (and its siblings to do . . . except to make a mess of your
flushleft and flushright) are actually vertical spacing.
based on LaTeX’s list-handling code; and The solution is the same as that out-
lists always separate themselves from the lined in the same answer, noting that all
216
control of an figure or table needs to be type accented characters you need to use
inside the environment. So the example’s the \a kludge: so \a’{e} inside tabbing
code should be converted to for \’{e} outside, and similarly \a‘ for \‘
and \a= for \=. This whole procedure is
\begin{figure}
of course hideous and error-prone.
\centering
The simplest alternative is to type in an
...
encoding that has the diacriticised charac-
\end{figure}
ters in it, and to use an appropriate encod-
(or something similar for a table). ing definition file in the inputenc package.
So for example, type:
388 Two-column float numbers out of
order \usepackage[latin1]
{inputenc}
When LaTeX can’t place a float immedi-
...
ately, it places it on one of several “de-
\begin{tabbing}
fer” lists. If another float of the same type
...
comes along, and the “defer” list for that
... \> voilà \> ...
type still has something in it, the later float
has to wait for everything earlier in the list. for:
Now, standard LaTeX has differ-
... voilà ...
ent lists for single-column floats, and
double-column floats; this means that and the internal mechanisms of the
single-column figures can overtake double- inputenc package will put the right version
column figures (or vice-versa), and you ob- of the accent command in there.
serve later figures appear in the document A witty reversal of the rôles is intro-
before early ones. The same is true, of duced by the package Tabbing (note the
course, for tables, or for any user-defined capital “T”): it provides a Tabbing envi-
float. ronment which duplicates tabbing, but
The LaTeX team recognise the prob- all the single-character commands become
lem, and provides a package (fixltx2e) to complicated objects. So tabbing’s \> be-
deal with it. Fixltx2e amalgamates the two comes \TAB>, \= becomes \TAB=, and so
defer lists, so that floats don’t get out of on. The above trivial example would there-
order. fore become:
For those who are still running an older
\usepackage{Tabbing}
LaTeX distribution, the package fix2col
...
should serve. This package (also by a mem-
\begin{Tabbing}
ber of the LaTeX team) was the basis of the
... ... \TAB> voil\‘a \TAB> ...
relevant part of fixltx2e. The functionality
has also been included in dblfloatfix, which Tabbing.sty :
also has code to place full-width floats at macros/latex/contrib/Tabbing
[b] placement.
390 Package reports “command
Once you have loaded the package, no
already defined”
more remains to be done: the whole re-
quirement is to patch the output routine; You load a pair of packages, and the second
no extra commands are needed. reports that one of the commands it defines
is already present. For example, both the
dblfloatfix.sty : macros/latex/
txfonts and amsmath define a command
contrib/dblfloatfix
\iint (and \iiint and so on); so
fix2col.sty :
...
macros/latex/contrib/fix2col
\usepackage{txfonts}
fixltx2e.sty : Part of the LaTeX \usepackage{amsmath}
distribution
produces a string of error messages of the
389 Accents misbehave in tabbing form:
So you are constructing a tabbing envi-
! LaTeX Error: Command \iint already defined.
ronment, and you have the need of some
Or name \end... illegal, see p.192 of th
diacriticised text — perhaps something as
simple as \’{e} — and the accent disap- As a general rule, things that amsmath de-
pears because it has been interpreted as a fines, it defines well; however, there is a
tabbing command, and everything goes good case for using the txfonts version of
wrong. \iint — the associated tx fonts have a
This is really a rather ghastly feature double integral symbol that doesn’t need
of the tabbing environment; in order to to be “faked” in the way amsmath does. In
217
the case that you are loading several sym- 392 Link text doesn’t break at end
bol packages, every one of which defines line
the same symbol, you are likely to experi-
When using the hyperref package, you
ence the problem in a big way (\euro is a
make a block of text “active” when you
common victim).
define a hyper-link (when the user clicks
There are similar cases where one pack- on that text, the reader program will divert
age redefines another’s command, but no to the target of the link).
error occurs because the redefining pack-
The hyperref package uses a driver
age doesn’t use \newcommand. Often, in
(in the same way as the graphics package
such a case, you only notice the change be-
does), to determine how to implement all
cause you assume the definition given by
that hyper-stuff.
the first package. The amsmath–txfonts
If you use the driver for dvips out-
packages are just such a pair; txfonts
put (presumably you want to distill the re-
doesn’t provoke errors.
sulting PostScript), limitations in the way
You may deal with the problem by sav-
dvips deals with the \special commands
ing and restoring the command. Macro
mean that hyperref must prevent link an-
programmers may care to do this for them-
chors from breaking at the end of lines.
selves; for the rest of us, there’s the pack-
Other drivers (notably those for PDFTeX
age savesym. The sequence:
and for dvipdfm) don’t suffer from this
\usepackage{savesym} problem.
\usepackage{amsmath} The problem may occur in a number
\savesymbol{iint} of different circumstances. For a couple of
\usepackage{txfonts} them, there are work-arounds:
\restoresymbol{TXF}{iint} First, if you have an URL which is ac-
tive (so that clicking on it will activate your
does the job; restoring the amsmath ver- web browser to “go to” the URL). In this
sion of the command, and making the case hyperref employs the url package to
txfonts version of the command available split up the URL (as described in type-
as \TXFiint. setting URLs), but the dvips driver then
Documentation of savesym doesn’t suppresses the breaks. The way out is
amount to much: the only commands are the breakurl package, which modifies the
\savesymbol and \restoresymbol, as \url command to produce several smaller
noted above. pieces, between each of which a line break
amsmath.sty : Part of macros/latex/ is permitted. Each group of pieces, that
required/amslatex ends up together in one line, is converted
to a single clickable link.
savesym.sty : macros/latex/
contrib/savesym/savesym.sty
Second, if you have a table of contents,
list of figure or tables, or the like, hyperref
txfonts.sty : Part of fonts/txfonts will ordinarily make the titles in the ta-
391 Why are my sections numbered ble of contents, or captions in the lists, ac-
0.1 . . . ? tive. If the title or caption is long, it will
need to break within the table, but the dvips
This happens when your document is us- driver will prevent that. In this case, load
ing the standard book or report class (or hyperref with the option linktocpage,
one similar), and you’ve got a \section and only the page number will be made
before your first \chapter. active.
What happens is, that the class num- Otherwise, if you have a lengthy piece
bers sections as “hchapter noi.hsection of text that you want active, you have at
noi”, and until the first \chapter has present no simple solution: you have to
appeared, the chapter number is 0. (If rewrite your text, or to use a different PDF
you use\chapter*, which doesn’t num- generation mechanism.
ber the chapter it produces, the problem
still arises.) breakurl.sty :
If you’re doing this, it’s possible that macros/latex/contrib/breakurl
the article class is for you; try it and see.
393 Page number is wrong at start of
Otherwise, put a \chapter before your
page
sections, or do away with section num-
bering by using \section* instead. An This is a long story, whose sources are deep
alternative way of avoiding numbering is inside the workings of TeX itself; it all de-
discussed in “unnumbered sections in the rives from the TeX’s striving to generate
table of contents”. the best possible output.
218
 The page number is conventionally Fortunately, TeX’s scanning mecha-
stored in \count0; LaTeX users see this nisms helps us by accepting the syntax
as the counter page, and may typeset its “{]}” to ‘hide’ the closing bracket from
value using \thepage. the scanning mechanism that LaTeX uses.
The number (that is to say, \count0) In practice, the commonest way to use this
is only updated when TeX actually outputs facility is:
a page. TeX only even tries to do this when
it detects a hint that it may be a good thing \section[All {[OK]} now]{All \emph{OK} now.}
to do. From TeX’s point of view, the end
since bracing the bracket on its own “looks
of a paragraph is a good time to consider
odd”.
outputting a page; it will output a page if it
LaTeX has another argument syntax,
has more than a page’s worth of material to
even less regular, where the argument is
output. (Ensuring it always has something
enclosed in parentheses, as in:
in hand makes some optimisations possi-
ble.) As a result, \count0 (\thepage) is \put(1,2){foo}
almost always wrong in the first paragraph
of a page (the exception is where the page (a picture environment command).
number has been “forcibly” changed, ei- This mechanism is also prone to prob-
ther by changing its value directly, or by lems with matching closing parentheses,
breaking the page where TeX wouldn’t nec- but the issue seldom arises since such ar-
essarily have chosen to break). guments rarely contain text. If it were to
LaTeX provides a safe way of referring arise, the same solution (enclosing the con-
to the page number, by using label refer- fused characters in braces) would solve the
ences. So, rather than writing: problem.
Here is page \thepage{}. 395 Characters disappear from
figures in PDFTeX
you should write:
You have a PDF figure, which you want to
Here is page \pageref{here}\label{here}.
use in your PDFLaTeX document. When
(note: no space between the \pageref and you compile the document, PDFTeX com-
the \label, since that could potentially plains about “missing glyphs”, and some
end up as a page-break space itself, which (or all) of the labelling text or symbols in
rather defeats the purpose of the exercise!). the original figure is no longer visible.
What has happened is:
394 My brackets don’t match
(La)TeX has a low-level mechanism for 1. Your figure file (say fig.pdf) has a
matching braces in document text. This font font.pfb embedded in it.
means you can type something like: 2. PDFTeX notes that it has font.pfb
on disc, and loads that in place of the
\section{All \emph{OK} now.} copy in fig.pdf.
3. It turns out that the copy in fig.pdf
and know that the first brace (for the argu-
has glyphs that aren’t in font.pfb on
ment of \section) will be matched with
disc, so that you get errors while com-
the last brace, and the internal pair of
piling and you see that characters are
braces (for the argument of \emph) will
missing when you view the output.
be matched with each other. It’s all very
(PDFTeX can’t know that the fonts
simple.
are different, since they have the same
However, LaTeX has a convention of
name.)
enclosing optional arguments in brackets,
as in: Which is all very undesirable.
\section[OK]{All \emph{OK} now.} PDFTeX does this to keep file sizes
down: suppose you have a document that
These brackets are not matched by loads figures fig1.pdf and fig2.pdf;
TeX mechanisms, despite the superficial both of those use font font.pfb. If PDF-
similarity of their use. As a result, TeX takes no action, there will be two
straightforward-looking usages like: copies of font.pfb in the output. (If your
document also uses the font, there could
\section[All [OK] now]{All \emph{OK} now.}
be three copies.)
aren’t OK at all — the optional argu- A real case is the URW font
ment comes to consist of “All [OK”, and NimbusRomNo9L-Regu (a clone of Times
\section takes the single character “n” Roman), which is available in a version
(of the first “now”) as its argument. with Cyrillic letters, while the version in
219
TeX distributions doesn’t have those let- each included file, and makes a ‘check-
ters. Both versions, as distributed, have the point’ of important parameters (such as
same name. page, figure, table and footnote numbers).
The simple (“quick and dirty”) solution As a direct result, it must clear the current
is to add the command page both before and after the \include
command. (The requirement derives from
\pdfinclusioncopyfonts=1
the difficulties of observing page numbers.)
to the preamble of your document. What’s more, this mechanism doesn’t work
The “real” solution is that one or other if a \include command appears in a file
font should be renamed. In either case, this that was \included itself: LaTeX diag-
would require that you reconfigure some noses this as an error.
program’s (TeX’s or your drawing pack- So, we can now answer the two com-
age’s) font tables — inevitably a tiresome monest questions about \include:
job.
• Why does LaTeX throw a page before
396 I asked for “empty”, but the page and after \include commands?
is numbered Answer: because it has to. If you don’t
If you use \pagestyle{empty} and you like it, replace the \include com-
find some pages are numbered anyway, mand with \input — you won’t be
you are probably encountering one of the able to use \includeonly any more,
style decisions built into the standard La- but you probably don’t need it anyway,
TeX classes: that certain special pages so don’t worry.
should always appear with \pagestyle • Why can’t I nest \included files? —
{plain}, with a page number at the cen- I always used to be able to under La-
tre of the page foot. The special pages in TeX 2.09.
question are those (in article class) contain- Answer: in fact, you couldn’t, even un-
ing a \maketitle, or (in book and report der LaTeX 2.09, but the failure wasn’t
classes) \chapter or \part commands. diagnosed. However, since you were
The simple solution is to reissue the happy with the behaviour under La-
page style after the command, with ef- TeX 2.09, replace the \include com-
fect for a single page, as, for example (in mands with \input commands (with
article): \clearpage as appropriate).

\maketitle 398 Why does it ignore paragraph

\thispagestyle{empty} parameters?
When TeX is laying out text, it doesn’t
or (in book or report)
work from word to word, or from line to
\chapter{foo bar} line; the smallest complete unit it formats
\thispagestyle{empty} is the paragraph. The paragraph is laid
down in a buffer, as it appears, and isn’t
A similar technique doesn’t work for a touched further until the end-paragraph
book or report \part command pages. For marker is processed. It’s at this point that
that, and for other detail, take look at “get- the paragraph parameters have effect; and
ting rid of page numbers”. it’s because of this sequence that one often
T.2 Common makes mistakes that lead to the paragraph
parameters not doing what one would have
misunderstandings
hoped (or expected).
397 What’s going on in my \include Consider the following sequence of La-
commands? TeX:
The original LaTeX provided the
{\raggedright % declaration for ragged text
\include command to address the prob-
Here’s text to be ranged left in our output,
lem of long documents: with the relatively
but it’s the only such paragraph, so we now
slow computers of the time, the compan-
end the group.}
ion \includeonly facility was a boon.
With the vast increase in computer speed,
Here’s more that needn’t be ragged...
\includeonly is less valuable (though
it still has its place in some very large TeX will open a group, and impose
projects). Nevertheless, the facility is re- the ragged-setting parameters within that
tained in current LaTeX, and causes some group; it will then save a couple of sen-
confusion to those who misunderstand it. tences of text and close the group (thus
In order for \includeonly to work, restoring the previous value of the param-
\include makes a separate .aux file for eters that \raggedright set). Then TeX
220
encounters a blank line, which it knows which fixes the latter problem. These com-
to treat as a \par token, so it typesets the mands are used in the standard classes
two sentences; but because the enclosing to produce upper case running heads for
group has now been closed, the parameter chapters and sections.
settings have been lost, and the paragraph Unfortunately \MakeUppercase and
will be typeset normally. \MakeLowercase do not solve the other
The solution is simple: close the para- problems with \uppercase, so for ex-
graph inside the group, so that the setting ample a section title containing \begin
parameters remain in place. An appropri- {tabular} . . . \end{tabular} will pro-
ate way of doing that is to replace the last duce a running head containing \begin
three lines above with: {TABULAR}. The simplest solution to this
problem is using a user-defined command,
end the group.\par} for example:
Here’s more that needn’t be ragged...
\newcommand{\mytable}{\begin{tabular}...
In this way, the paragraph is completed
\end{tabular}}
while \raggedright’s parameters are still
\section{A section title \protect\mytable{}
in force within the enclosing group.
with a table}
Another alternative is to define an en-
vironment that does the appropriate job for Note that \mytable has to be pro-
you. For the above example, LaTeX al- tected, otherwise it will be expanded
ready defines an appropriate one: and made upper case; you can achieve
\begin{flushleft} the same result by declaring it with
Here’s text to be ranged left... \DeclareRobustCommand , in which case
\end{flushleft} the \protect won’t be necessary.
David Carlisle’s textcase pack-
In fact, there are a number of param- age addresses many of these prob-
eters for which TeX only maintains one lems in a transparent way. It defines
value per paragraph. A tiresome one is commands \MakeTextUppercase and
the set of upper case/lower case transla- \MakeTextLowercase which do upper- or
tions, which (oddly enough) constrains lowercase, with the fancier features of the
hyphenation of mutilingual texts. An- LaTeX standard \Make*-commands but
other that regularly creates confusion is without the problems mentioned above.
\baselineskip. Load the package with \usepackage
[overload]{textcase}, and it will rede-
399 Case-changing oddities
fine the LaTeX commands (not the TeX
TeX provides two primitive commands primitive commands \uppercase and
\uppercase and \lowercase to change \lowercase), so that section headings
the case of text; they’re not much used, but and the like don’t produce broken page
are capable creating confusion. headings.
The two commands do not expand
textcase.sty :
the text that is their parameter — the
macros/latex/contrib/textcase
result of \uppercase{abc} is ‘ABC’,
but \uppercase{\abc} is always ‘\abc’, 400 Why does LaTeX split footnotes
whatever the meaning of \abc. The com- across pages?
mands are simply interpreting a table of
equivalences between upper- and lower- LaTeX splits footnotes when it can think
case characters. They have (for example) of nothing better to do. Typically, when
no mathematical sense, and this happens, the footnote mark is at the
bottom of the page, and the complete foot-
\uppercase{About $y=f(x)$} note would overfill the page. LaTeX could
try to salvage this problem by making the
will produce page short of both the footnote and the line
ABOUT $Y=F(X)$ with the footnote mark, but its priorities
told it that splitting the footnote would be
which is probably not what is wanted. preferable.
In addition, \uppercase and As always, the best solution is to
\lowercase do not deal very well with change your text so that the problem
non-American characters, for example doesn’t occur in the first place. Consider
\uppercase{\ae} is the same as \ae. whether the text that bears the footnote
LaTeX provides commands could move earlier in the current page, or
\MakeUppercase and \MakeLowercase on to the next page.
221
 If this isn’t possible, you might like marks stored in the .aux file; the
want to change LaTeX’s perception memoir class does likewise.
of its priorities: they’re controlled memoir.cls:
by \interfootnotelinepenalty — the macros/latex/contrib/memoir
larger it is, the less willing LaTeX is to
split footnotes. mparhack.sty :
macros/latex/contrib/mparhack
Setting
402 Where have my characters gone?
\interfootnotelinepenalty=10000
You’ve typed some apparently reasonable
inhibits split footnotes altogether, which text and processed it, but the result con-
will cause ‘Underfull \vbox’ messages tains no sign of some of the characters you
unless you also specify \raggedbottom. typed. A likely reason is that the font you
The default value of the penalty is 100, selected just doesn’t have a representation
which is rather mild. for the character in question.
For example, if I type “that will be
An alternative technique is to jug-
£44.00” into an ordinary (La)TeX docu-
gle with the actual size of the pages.
ment, or if I select the font rsfs10 (which
\enlargethispage changes the size of
contains uppercase letters only) and type
the current page by its argument (for ex-
pretty much anything, the £ sign, or any
ample, you might say \enlargethispage
lowercase letters or digits will not appear
{\baselineskip} to add a single line to
in the output. There’s no actual error mes-
the page, but you can use any ordinary TeX
sage, either: you have to read the log file,
length such as 15mm or -20pt as argument).
where you’ll find cryptic little messages
Reducing the size of the current page could
like
force the offending text to the next page;
increasing the size of the page may allow Missing character: There is no ^^a3 in font cmr10!
the footnote to be included in its entirety. Missing character: There is no 3 in font rsfs10!
It may be necessary to change the size of
more than one page. (the former demonstrating my TeX’s un-
The fnbreak package detects (and gen- willingness to deal in characters which
erates warnings about) split footnotes. have the eighth bit set, while the rsfs10
example shows that TeX will log the actual
fnbreak.sty : character in error, if it thinks it’s possible).
macros/latex/contrib/fnbreak Somewhat more understandable are the
diagnostics you may get from dvips when
401 Getting \marginpar on the right
using the OT1 and T1 versions of fonts that
side
were supplied in Adobe standard encoding:
In an ideal world, marginal notes would
be in “analogous” places on every page: dvips: Warning: missing glyph ‘Delta’
notes on an even-side page would be in The process that generates the metrics for
the left margin, while those on an odd-side using the fonts generates an instruction
page would be in the right margin. A mo- to dvips to produce these diagnostics, so
ment’s thought shows that a marginal note that their non-appearance in the printed
on the left needs to be typeset differently output is less surprising than it might be.
from a marginal note on the right. The Quite a few glyphs provided in Knuth’s
LaTeX \marginpar command therefore text encodings and in the Cork encoding
takes two arguments in a twoside docu- are not available in the Adobe fonts. In
ments: \marginpar[left text]{right these cases, there is a typeset sign of the
text}. LaTeX uses the “obvious” test to character: dvips produces a black rectangle
get the \marginpars in the correct mar- of whatever size the concocted font file has
gin, but a booby-trap arises because TeX specified.
runs its page maker asynchronously. If a
\marginpar is processed while page n is 403 “Rerun” messages won’t go away
being built, but doesn’t get used until page The LaTeX message “Rerun to get crossref-
n+1, then the \marginpar will turn up on erences right” is supposed to warn the user
the wrong side of the page. This is an in- that the job needs to be processed again,
stance of a general problem: see “finding since labels seem to have changed since
if you’re on an odd or an even page”. the previous run. (LaTeX compares the
The solution to the problem is for labels it has created this time round with
LaTeX to ‘remember’ which side of the what it found from the previous run when
page each \marginpar should be on. The it started; it does this comparison at \end
mparhack package does this, using label- {document}.)
222
 Sometimes, the message won’t go number of extra characters one needs to
away: however often you reprocess your type.
document, LaTeX still tells you that “La- If even that one character is too many,
bel(s) may have changed”. This can some- the package xspace defines a command
times be caused by a broken package: both \xspace that guesses whether there should
footmisc (with the perpage option) and have been a space after it, and if so intro-
hyperref have been known to give trouble, duces that space. So “fred\xspace jim”
in the past: if you are using either, check produces “fred jim”, while “fred\xspace.
you have the latest version, and upgrade if jim” produces “fred. jim”. Which usage
possible. would of course be completely pointless;
However, there is a rare occasion when but you can incorporate \xspace in your
this error can happen as a result of patho- own macros:
logical structure of the document itself.
Suppose you have pages numbered in ro- \usepackage{xspace}
man, and you add a reference to a label on ...
page “ix” (9). The presence of the refer- \newcommand{\restenergy}{\ensuremath{mc^2}\xspace}
ence pushes the thing referred to onto page ...
“x” (10), but since that’s a shorter reference and we find \restenergy available to us...
the label moves back to page “ix” at the The \xspace command must be the last
next run. Such a sequence can obviously thing in your macro definition (as in the ex-
not terminate. ample); it’s not completely foolproof, but
The only solution to this problem is it copes with most obvious situations in
to make a small change to your document running text.
(something as small as adding or deleting The xspace package doesn’t save you
a comma will often be enough). anything if you use it in a macro that ap-
footmisc.sty : pears only once or twice within your docu-
macros/latex/contrib/footmisc ment, and it is not totally foolproof. (The
hyperref.sty : original author of the package wrote it be-
macros/latex/contrib/hyperref cause he had been bitten by lost spaces.
He no longer recommends its use, simply
404 Commands gobble following because of the possibility of error.)
space In any case, be careful with usage of
People are forever surprised that simple \xspace — it changes your input syntax,
commands gobble the space after them: which can be confusing, notably to a col-
this is just the way it is. The effect arises laborating author (particularly if you cre-
from the way TeX works, and Lamport de- ate some commands which use it and some
scribes a solution (place a pair of braces which don’t). No command built into La-
after a command’s invocation) in the de- TeX or into any “standard” class or pack-
scription of LaTeX syntax. Thus the re- age will use \xspace.
quirement is in effect part of the definition xspace.sty : Distributed as part of
of LaTeX. macros/latex/required/tools
These FAQs, for example, is written in
LaTeX for production of a web site. The 405 (La)TeX makes overfull lines
HTML code is generated by a script that When TeX is building a paragraph, it
requires a pair of braces, to make a null can make several attempts to get the line-
argument, as in: breaking right; on each attempt it runs the
same algorithm, but gives it different pa-
\fred{}
rameters. You can affect the way TeX’s
for almost all macro invocations, regard- line breaking works by adjusting the pa-
less of whether the following space is re- rameters: this answer deals with the “tol-
quired: however, these FAQs should not erance” and stretchability parameters. The
itself be regarded as a model of LaTeX other vital ‘parameter’ is the set of hyphen-
style. ations to be applied: see “my words aren’t
Many users find all those braces be- being hyphenated” (and the questions it
come very tedious very quickly, and would references) for advice.
really rather not type them all. If you’re getting an undesired “overfull
An alternative structure, that doesn’t box”, what has happened is that TeX has
violate the design of LaTeX, is to say given up: the parameters you gave it don’t
\fred\ — the \ command is “self termi- allow it to produce a result that doesn’t
nating” (like \\) and you don’t need braces overfill. In this circumstance, Knuth de-
after it. Thus one can reduce to one the cided the best thing to do was to produce a
223
warning, and to allow the user to solve the time, so adding a pass (by chang-
problem. (The alternative, silently to go be- ing \emergencystretch) is less desir-
yond the envelope of “good taste” defined able than suppressing one (by changing
for this run of TeX, would be distasteful \pretolerance). However, it’s unusual
to any discerning typographer.) The user nowadays to find a computer that’s slow
can almost always address the problem by enough that the extra passes are really trou-
rewriting the text that’s provoking the prob- blesome.
lem — but that’s not always possible, and In practice, \pretolerance is rarely
in some cases it’s impossible to solve the used other than to manipulate the use of
problem without adjusting the parameters. hyphenation; Plain TeX and LaTeX both
This answer discusses the approaches one set its value to 100. To suppress the first
might take to resolution of the problem, on scan of paragraphs, set \pretolerance to
the assumption that you’ve got the hyphen- -1.
ation correct. \tolerance is often a good method
The simplest case is where a ‘small’ for adjusting spacing; Plain TeX and La-
word fails to break at the end of a line; TeX both set its value to 200. LaTeX’s
pushing the entire word to a new line isn’t \sloppy command sets it to 9999, as does
going to make much difference, but it the sloppypar environment. This value
might make things just bad enough that is the largest available, this side of in-
TeX won’t do it by default. In such a case finity, and can allow pretty poor-looking
on can try the LaTeX \linebreak com- breaks (this author rarely uses \sloppy
mand: it may solve the problem, and if it “bare”, though he does occasionally use
does, it will save an awful lot of fiddling. sloppypar — that way, the change of
Otherwise, one needs to adjust parameters: \tolerance is confined to the environ-
to do that we need to recap the details of ment). More satisfactory is to make small
TeX’s line breaking mechanisms. changes to \tolerance, incrementally,
TeX’s first attempt at breaking lines and then to look to see how the change
is performed without even trying hy- affects the result; very small increases can
phenation: TeX sets its “tolerance” of often do what’s necessary. Remember that
line breaking oddities to the internal \tolerance is a paragraph parameter, so
value \pretolerance, and sees what you need to ensure it’s actually applied —
happens. If it can’t get an acceptable see “ignoring paragraph parameters”. La-
break, TeX adds the hyphenation points TeX users could use an environment like:
allowed by the current patterns, and
tries again using the internal \tolerance \newenvironment{tolerant}[1]{%
value. If this pass also fails, and \par\tolerance=#1\relax
the internal \emergencystretch value }{%
is positive, TeX will try a pass that al- \par
lows \emergencystretch worth of extra }
stretchability to the spaces in each line.
enclosing entire paragraphs (or set of para-
In principle, therefore, there are
graphs) in it.
three parameters (other than hyphenation)
The value of \emergencystretch is
that you can change: \pretolerance,
added to the assumed stretchability of each
\tolerance and \emergencystretch.
line of a paragraph, in a further run of
Both the tolerance values are simple
the paragraph formatter in case that the
numbers, and should be set by TeX primi-
paragraph can’t be made to look right any
tive count assignment — for example
other way. (The extra scan happens if
\pretolerance=150 \emergencystretch>0pt — if it’s zero
or negative, no gain could be had from re-
For both, an “infinite” tolerance is repre- running the paragraph setter.) The example
sented by the value 10 000, but infinite tol- above set it to 3em; the Computer Modern
erance is rarely appropriate, since it can fonts ordinarily fit three space skips to the
lead to very bad line breaks indeed. em, so the change would allow anything
\emergencystretch is a TeX- up to the equivalent of nine extra spaces in
internal ‘dimen’ register, and can be set as each line. In a line with lots of spaces, this
normal for dimens in Plain TeX; in LaTeX, could be reasonable, but with (say) only
use \setlength — for example: three spaces on the line, each could stretch
\setlength{\emergencystretch}{3em}
to four times its natural width. It is there-
fore clear that \emergencystretch needs
The choice of method has time im- to be treated with a degree of caution.
plications — each of the passes takes More subtle (but more tricky to man-
224
age) are the microtypographic extensions doesn’t change the font, any more than
provided by PDFTeX. Since PDFTeX is does the command \fontsize{size}
the default ‘engine’ for LaTeX and Con- {baselineskip} — you have to follow
TeXt work in all distributions, nowadays, either command with \selectfont. So:
the extensions are available to all. There
are two extensions, margin kerning and \fontsize{10}{12}%
font expansion; margin kerning only af- \selectfont
fects the visual effect of the typeset page,
or:
and has little effect on the ability of the
paragraph setter to “get things right”. Font \linespread{1.2}%
expansion works like a subtler version of \selectfont
the trick that \emergencystretch plays:
PDFTeX ‘knows’ that your current font Of course, a package such as setspace,
may be stretched (or shrunk) to a certain whose job is to manage the baseline, will
extent, and will do that “on the fly” to opti- deal with all this stuff — see “managing
mise the setting of a paragraph. This is a double-spaced documents”. If you want
powerful tool in the armoury of the type- to avoid setspace, beware the behaviour
setter. of linespread changes within a paragraph:
As mentioned above, the microtypo- read “\baselineskip is a paragraph pa-
graphic extensions are tricky beasts to con- rameter”.
trol; however, the microtype package re- setspace.sty : macros/latex/
lieves the user of the tedious work of spec- contrib/setspace/setspace.sty
ifying how to perform margin adjustments
and how much to scale each font . . . for 408 Only one \baselineskip per
the fonts the package knows about; it’s a paragraph
good tool, and users who can take on the
The \baselineskip, which determines
specification of adjustments for yet more
the space between lines, is not (as one
fonts are always welcome.
might hope) a property of a line, but of a
microtype.sty : macros/latex/ paragraph. As a result, in a 10pt (nominal)
contrib/microtype document (with a default \baselineskip
of 12pt), a single character with a larger
406 Maths symbols don’t scale up
size, as:
By default, the “large” maths symbols stay
at the same size regardless of the font {\Huge A}
size of the text of the document. There’s
will be squashed into the paragraph: TeX
good reason for this: the cmex fonts aren’t
will make sure it doesn’t scrape up against
really designed to scale, so that TeX’s
the line above, but won’t give it “room
maths placement algorithms don’t perform
to breathe”, as it does the text at standard
as well as they might when the fonts are
scaled. size; that is, its size (24.88pt) is taken
account of, but its \baselineskip (30pt)
However, this behaviour confounds
isn’t. This problem may be solved by a
user expectations, and can lead to slightly
strut: the name comes from movable metal
odd-looking documents. If you want the
typography, and refers to a spacer that
fonts to scale, despite the warning above,
held the boxes (that contained the metal
use the exscale package — just loading it
is enough. character shapes) apart. Every time you
change font size, LaTeX redefines the com-
exscale.sty : Part of the LaTeX
mand \strut to provide the equivalent of
distribution. a metal-type strut for the size chosen. So
407 Why doesn’t \linespread work? for the example above, we would type
The command \linespread{factor} Paragraph text ...
is supposed to multiply the current {\Huge A\strut}
\baselineskip by hfactori; but, to all ap- ... paragraph continues ...
pearances, it doesn’t.
In fact, the command is equivalent This technique only works for such very
to \renewcommand{\baselinestretch} short intrusions; if you need several lines,
{factor}: written that way, it somehow you should convert your intrusion into a
feels less surprising that the effect isn’t quote environment, since it’s not possible
immediate. The \baselinestretch fac- to provide a \strut command for every
tor is only used when a font is selected; line of the intrusion, in a sensible way, so
a mere change of \baselinestretch proceed by:
225
 \begin{quote} 409 Numbers too large in table of
\Huge A LENGTHY TEXT ... contents, etc.
SHOUTING AT THE READER!
LaTeX constructs the table of contents, list
\end{quote}
of figures, tables, and similar tables, on the
The contrary case: basis of a layout specified in the class. As
Paragraph text ... a result, they do not react to the sizes of
{\footnotesize Extended interjection things in
...them, as they would if a tabular
... into the paragraph.} environment (or something similar) was
... paragraph continues ... used.
This arrangement can provoke prob-
will look wrong, since the 8pt inter- lems, most commonly with deep section
jection will end up set on the 12pt nesting or very large page numbers: the
\baselineskip of the paragraph, rather
numbers in question just don’t fit in the
than its preferred 8.5pt. A \strut here space allowed for them in the class.
is no help: there is no such thing as a “neg-
A separate answer discusses re-
ative strut”, that draws lines together, so
designing the tables — re-designing the
once more, one falls back on the quote to
tables — and techniques from that answer
separate the interjection:
may be employed to make the numbers fit:
Paragraph text ...
\begin{quote} \setlength\cftsectionnumwidth{4em}
\footnotesize Extended interjection ...
... into the paragraph. The same command may be employed
\end{quote} in documents typeset with the memoir
... paragraph continues ... package (by the same author as tocloft).
Memoir has another mechanism for the
The same effect is at work when we
job: \cftsetindents{hkind i}{indent}
have something like:
{numwidth}. Here kind is chapter,
Paragraph text ... section, or whatever; the indent specifies
... paragraph body ends. the ‘margin’ before the entry starts; and
{\footnotesize Comment on the paragraph.}
the width is of the box into which the num-
ber is typeset (so needs to be wide enough
Next paragraph starts... for the largest number, with the necessary
which will set the body of the first para- spacing to separate it from what comes af-
graph on the constricted \baselineskip ter it in the line.
of the \footnotesize comment. Solve memoir.cls:
this problem by ending the initial para- macros/latex/contrib/memoir
graph before starting the comment:
tocloft.sty :
Paragraph text ... macros/latex/contrib/tocloft
... paragraph body ends.
\par\nothtml{\noindent} 410 Why is the inside margin so
narrow?
{\footnotesize Comment on the paragraph.}
If you give the standard classes the
Next paragraph starts...
twoside option, the class sets the margins
(We suggest \noindent to make the com- narrow on the left of odd-numbered pages,
ment look as if it is part of the paragraph it and on the right of even-numbered pages.
discusses; omit \noindent if that is inap- This is often thought to look odd, but it is
propriate.) quite right.
A variation of the previous issue arises The idea is that the typographic urge
from a paragraph whose size is different for symmetry should also apply to mar-
from those around it: gins: if you lay an even numbered page to
{\Large (Extended) IMPORTANT DETAILS the left ...}
of an odd-numbered one, you will
see that you’ve three equal chunks of un-
Main body of text... printed paper: the left margin of the even
page, the right margin of the odd page, and
Again, the problem is solved by ending the the two abutting margins together.
paragraph in the same group as the text
This is all very fine in the abstract, but
with a different size:
in practical book(let) production it only
{\Large (Extended) IMPORTANT DETAILS ...\par}
works “sometimes”.
If your booklet is produced on double-
Main body of text... width paper and stapled, the effect will be
226
good; if your book(let) is produced using a By contrast, the fontenc package gen-
so-called “perfect” binding, the effect will erates the T1 code points from ordinary
again be good. LaTeX commands (e.g., it generates the
However, almost any “quality” book- é character codepoint from the command
binder will need some of your paper to \’e). So, unless you have program-
grab hold of, and a book bound in such a generated T1 input (which is almost
way won’t exhibit the treasured symmetry inconceivable), use \usepackage[T1]
unless you’ve done something about the {fontenc} rather than \usepackage
margin settings. {t1enc}.
The packages recommended in “set-
412 Why bother with inputenc and
ting up margins” mostly have provision
fontenc?
for a “binding offset” or a “binding correc-
The standard input encoding for Western
tion” — search for “binding” in the manu-
als (vmargin doesn’t help, here). Europe (pending the arrival of Unicode)
is ISO 8859–1 (commonly known by the
If you’re doing the job by hand (see
standard’s subtitle ‘Latin-1’). Latin-1 is re-
manual margin setup), the trick is to calcu-
markably close, in the codepoints it covers,
late your page and margin dimensions as
normal, and then: to the (La)TeX T1 encoding.
In this circumstance, why should one
• subtract the binding offset from bother with inputenc and fontenc? Since
\evensidemargin, and they’re pretty exactly mirroring each other,
• add the binding offset to one could do away with both, and use just
\oddsidemargin. t1enc, despite its shortcomings.
which can be achieved by: One doesn’t do this for a variety of
small reasons:
\addtolength{\evensidemargin}{-offset}
Confusion You’ve been happily working
\addtolength{\oddsidemargin}{offset}
in this mode, and for some reason find
(substituting something sensible like “5mm” you’re to switch to writing in German:
for “offset”, above). the effect of using “ß” is somewhat
The above may not be the best you can startling, since T1 and Latin-1 treat
do: you may well choose to change the the codepoint differently.
\textwidth in the presence of the bind-
Compatibility You find yourself needing
ing offset; but the changes do work for to work with a colleague in Eastern
constant \textwidth. Europe: their keyboard is likely to be
T.3 Why shouldn’t I? set to produce Latin-2, so that the sim-
ple mapping doesn’t work.
411 Why use fontenc rather than Traditional LaTeX You lapse and write
t1enc? something like \’{e} rather than typ-
In the very earliest days of LaTeX2e, the ing é; only fontenc has the means to
only way to use the T1 encoding was t1enc; convert this LaTeX sequence into the
with the summer 1994 “production” re- T1 character, so an \accent primitive
lease, the fontenc package appeared, and slips through into the output, and hy-
provided comprehensive support for use of phenation is in danger.
the encoding.
Nevertheless, the t1enc package re- The inputenc–fontenc combination seems
mains (as part of the LaTeX 2.09 compati- slow and cumbersome, but it’s safe.
bility code), but it does very little: it merely 413 Why not use eqnarray?
selects font encoding T1, and leaves to the
user the business of generating the charac- The environment eqnarray is attractive
ter codes required. for the occasional user of mathematics
Generating such character codes could in LaTeX documents: it seems to allow
be a simple matter, if the T1 encoding aligned systems of equations. Indeed it
matched any widely-supported encoding does supply such things, but it makes a
standard, since in that case, one might ex- serious mess of spacing. In the system:
pect one’s keyboard to generate the char- \begin{eqnarray}
acter codes. However, the T1 encoding is a & = & b + c \\
a mix of several standard encodings, and x & = & y - z
includes code points in areas of the table \end{eqnarray}
which standard encodings specifically ex-
clude, so no T1 keyboards have been (or the spacing around the “=” signs is not
ever will be) manufactured. that defined in the metrics for the font
227
from which the glyph comes — it’s proof ; placing the “QED symbol” doesn’t
\arraycolsep, which may be set to some work if it is in $$-displayed maths.
very odd value for reasons associated with There are more subtle effects (espe-
real arrays elsewhere in the document. cially with package amsmath), and the
The user is far better served by the AM- simple rule is “use \[ ... \] (at least)
SLaTeX bundle, which provides an align whenever displayed maths is needed in La-
environment, which is designed with the TeX”.
needs of mathematicians in mind (as op- (Note that the sequence \[ ... \]
posed to the convenience of LaTeX pro- is duplicated by the displaymath environ-
grammers). For this simple case (align ment, which can be said to “look nicer”,
and other AMSLaTeX alignment environ- and actually describes what’s being done.)
ments are capable of far greater things), 415 What’s wrong with \bf, \it,
code as: etc.?
\begin{align} The font-selection commands of La-
a & = b + c \\ TeX 2.09 were \rm, \sf, \tt, \it, \sl,
x & = y - z \em and \bf; they were modal commands,
\end{align} so you used them as:

The matter is discussed in more detail in {\bf Fred} was {\it here\/}.
a PracTeX journal paper by Lars Madsen; with the font change enclosed in a group,
Stefan Kottwitz offers a TeX blog entry so as to limit its effect; note the italic cor-
which includes screen shots of the output, rection command \/ that was necessary at
convincingly demonstrating the problem. the end of a section in italics.
AMSLaTeX : macros/latex/required/ At the release of LaTeX2e in summer
amslatex 1994, these simple commands were dep-
recated, but recognising that their use is
414 Why use \[ . . . \] in place of deeply embedded in the brains of LaTeX
$$ . . . $$? users, the commands themselves remain in
LaTeX defines inline- and display-maths LaTeX, with their LaTeX 2.09 semantics.
commands, apparently duplicating the TeX Those semantics were part of the reason
primitive maths sequences which surround they were deprecated: each \xx overrides
maths commands with single (or pairs of) any other font settings, keeping only the
dollar signs. size. So, for example,
In fact, LaTeX’s inline maths group- {\bf\it Here we are again\/}
ing, \( ... \), has (almost) exactly the
ignores \bf and produces text in italic,
same effect as the TeX primitive version
medium weight (and the italic correction
$... $. (The exception: the LaTeX ver-
has a real effect), whereas
sion checks to ensure you don’t put \( and
\) the wrong way round; this does occa- {\it\bf happy as can be\/}
sionally detect errors. . . .) ignores \it and produces upright text at
Since this is the case, one often finds bold weight (and the italic correction has
LaTeX users, who have some experience nothing to do). The same holds if you mix
of using Plain TeX, merely assuming that LaTeX2e font selections with the old style
LaTeX’s display maths grouping \[ ... commands:
\] may be replaced by the TeX primitive
display maths $$... $$. \textbf{\tt all good friends}
Unfortunately, the assumption is ignores the \textbf that encloses the text,
wrong: some LaTeX code needs to patch and produces typewriter text at medium
display maths, it can only do so by patch- weight.
ing \[ and \] (or their equivalents). Most So why are these commands depre-
obviously, the class option fleqn simply cated? — it is because of confusions such
does not work for equations coded us- as that in the last example. The alternative
ing $$... $$, whether you’re using the (LaTeX2e) commands are discussed in the
standard classes alone, or using package rest of this answer.
amsmath. Also, the \[ and \] construct LaTeX2e’s font commands come in
has code for rationalising vertical spacing two forms: modal commands and text-
in some extreme cases; that code is not block commands. The default set of modal
provided $$... $$, so if you use the commands offers weights \mdseries and
Plain TeX version, you may occasionally \bfseries, shapes \upshape, \itshape,
observe inconsistent vertical spacing. Sim- \scshape and \slshape, and families
ilar behaviour can bite if you are writing a \rmfamily, \sffamily and \ttfamily.
228
A font selection requires a family, a shape 416 What’s wrong with \newfont?
and a series (as well as a size, of course). If all else fails, you can specify a font us-
A few examples ing the LaTeX \newfont command. The
{\bfseries\ttfamily and jolly good font company!}
so specified doesn’t fit into the La-
TeX font selection mechanism, but the
produces bold typewriter text (but note the
technique can be tempting under several
lack of a bold typewriter font in the default
circumstances. The command is merely
Computer Modern fonts), or
the thinnest of wrappers around the \font
{\slshape\sffamily Never mind the primitive, and doesn’t really fit with LaTeX
weather\/}
at all. A simple, but really rather funny, ex-
(note the italic correction needed on
ample of the problems it poses, may be
slanted fonts, too).
seen in:
LaTeX2e’s text block commands take
the first two letters of the modal com- \documentclass[10pt]{article}
mands, and form a \textxx com- \begin{document}
mand from them. Thus \bfseries be- \newfont{\myfont}{cmr17 scaled 2000}
comes \textbf{text}, \itshape be- \myfont
comes \textit{text}, and \ttfamily \LaTeX
becomes \texttt{text}. Block com- \end{document}
mands may be nested, as:
(the reader is encouraged to try this). The
\textit{\textbf{Never mind the rain}}
“A” of \LaTeX pretty much disappears: La-
to produce bold italic text (note that the TeX chooses the size on the “A” according
block commands supply italic corrections to its idea of the font size (10pt), but po-
where necessary), and they be nested with sitions it according to the dimensions of
the LaTeX2e modal commands, too: “\myfont”, which is more than three times
\texttt{\bfseries So long as we’re that size.
together}
Another “\myfont” example arises
for bold typewriter, or from an entirely different source. The mini-
{\slshape \textbf{Whoops! she goes document:
again}\/}

for a bold slanted instance of the current \documentclass{article}

family (note the italic correction applied \begin{document}
at the end of the modal command group, \newfont{\myfont}{ecrm1000}
again). {\myfont voil\‘a}
The new commands (as noted above) \end{document}
override commands of the same type. In
almost all cases, this merely excludes ludi- gives you “German low double quotes”
crous ideas such as “upright slanted” fonts, (under the “a”) in place of the grave ac-
or “teletype roman” fonts. There are a cou- cent. This happens because ecrm1000 is
ple of immediate oddities, though. The in a different font encoding than LaTeX is
first is the conflict between \itshape (or expecting — if you use the LaTeX fontenc
\slshape) and \scshape: while many package to select the EC fonts, all these
claim that an italic small-caps font is ty- tiresome encoding issues are solved for
pographically unsound, such fonts do exist. you, behind the scenes.
Daniel Taupin’s smallcap package enables There does however remain a circum-
use of the instances in the EC fonts, and stance when you will be tempted to use
similar techniques could be brought to bear \newfont — viz., to get a font size that
on many other font sets. The second is the doesn’t fall into the Knuth standard set of
conflict between \upshape and \itshape: sizes: LaTeX (by default) won’t allow you
Knuth actually offers an upright-italic font to use such a size. Don’t despair: see the
which LaTeX uses for the “£” symbol in answer “arbitrary font sizes”.
the default font set. The combination is suf-
ficiently weird that, while there’s a defined
font shape, no default LaTeX commands U The joy of TeX errors
exist; to use the shape, the (eccentric) user
needs LaTeX’s simplest font selection com- 417 How to approach errors
mands: Since TeX is a macroprocessor, its error
messages are often difficult to understand;
{\fontshape{ui}\selectfont Tra la la, di dee}
this is a (seemingly invariant) property of
smallcap.sty : macroprocessors. Knuth makes light of the
macros/latex/contrib/smallcap problem in the TeXbook, suggesting that
229
you acquire the sleuthing skills of a latter- suppresses tracing around some of
day Sherlock Holmes; while this approach the truly verbose parts of LaTeX it-
has a certain romantic charm to it, it’s not self. The package also provides a
good for the ‘production’ user of (La)TeX. \traceoff command (there’s no “off”
This answer (derived, in part, from an arti- command for \tracingall), and a
cle by Sebastian Rahtz in TUGboat 16(4)) package option (logonly) allows you
offers some general guidance in dealing to suppress output to the terminal.
with TeX error reports, and other answers
in this section deal with common (but per- The best advice to those faced with TeX
plexing) errors that you may encounter. errors is not to panic: most of the com-
There’s a long list of “hints” in Sebastian’s mon errors are plain to the eye when you
article, including the following: go back to the source line that TeX tells
you of. If that approach doesn’t work,
• Look at TeX errors; those messages the remaining answers in this section deal
may seem cryptic at first, but they of- with some of the odder error messages you
ten contain a straightforward clue to may encounter. You should not ordinarily
the problem. See the structure of er- need to appeal to the wider public for as-
rors for further details. sistance, but if you do, be sure to report
• Read the .log file; it contains hints to full backtraces (see errorcontextlines
things you may not understand, often above) and so on.
things that have not even presented as trace.sty : Distributed as part of
error messages. macros/latex/required/tools
• Be aware of the amount of context
that TeX gives you. The error mes- 418 The structure of TeX error
sages gives you some bits of TeX code messages
(or of the document itself), that show
TeX’s error messages are reminiscent of
where the error “actually happened”;
the time when TeX itself was conceived
it’s possible to control how much of
(the 1970s): they’re not terribly user-
this ‘context’ TeX actually gives you.
friendly, though they do contain all the in-
LaTeX (nowadays) instructs TeX only
formation that TeX can offer, usually in a
to give you one line of context, but
pretty concise way.
you may tell it otherwise by saying TeX’s error reports all have the same
structure:
\setcounter{errorcontextlines}{999}
in the preamble of your document. (If • An error message
you’re not a confident macro program- • Some ‘context’
mer, don’t be ashamed of cutting that • An error prompt
999 down a bit; some errors will go
on and on, and spotting the differences The error message will relate to the TeX
between those lines can be a signifi- condition that is causing a problem. Sadly,
cant challenge.) in the case of complex macro packages
• As a last resort, tracing can be a use- such as LaTeX, the underlying TeX prob-
ful tool; reading a full (La)TeX trace lem may be superficially difficult to relate
takes a strong constitution, but once to the actual problem in the “higher-level”
you know how, the trace can lead you macros. Many LaTeX-detected problems
quickly to the source of a problem. manifest themselves as ‘generic’ errors,
You need to have read the TeXbook with error text provided by LaTeX itself
(see books about TeX) in some detail, (or by a LaTeX class or package).
fully to understand the trace. The context of the error is a stylised
The command \tracingall sets up representation of what TeX was doing at
maximum tracing; it also sets the out- the point that it detected the error. As noted
put to come to the interactive terminal, in approaching errors, a macro package
which is somewhat of a mixed bless- can tell TeX how much context to display,
ing (since the output tends to be so and the user may need to undo what the
vast — all but the simplest traces are package has done. Each line of context is
best examined in a text editor after the split at the point of the error; if the error
event). actually occurred in a macro called from
The LaTeX trace package (first dis- the present line, the break is at the point
tributed with the 2001 release of La- of the call. (If the called object is defined
TeX) provides more manageable trac- with arguments, the “point of call” is after
ing. Its \traceon command gives all the arguments have been scanned.) For
you what \tracingall offers, but example:
230
\blah and so on The similar (but more sensible):
produces the error report \caption{Energy: \(e=mc^2\)}
! Undefined control sequence.
l.4 \blah is more tiresome, still: there’s no error
and so on when you first run the job . . . but there
while: is on the second pass, when the list of fig-
ures (or tables) is generated, giving:
\newcommand{\blah}[1]{\bleah #1}
\blah{to you}, folks ! LaTeX Error: Bad math environment delimiter.
produces the error report in the \listoffigures processing.
! Undefined control sequence. The solution is usually to use a robust
\blah #1->\bleah command in place of the one you are using,
#1 or to force your command to be robust by
l.5 \blah{to you} prefixing it with \protect, which in the
, folks \section case would show as
If the argument itself is in error, we will
\section{Mumble\protect\footnote{I couldn’t think of an
see things such as
\newcommand{\blah}[1]{#1 to you} However, in both the \section case and
\blah{\bleah}, folks the \caption case, you can separate
producing the moving argument, as in \section
[moving]{static}; this gives us another
! Undefined control sequence.
<argument> \bleah
standard route — simply to omit (or other-
wise sanitise) the fragile command in the
l.5 \blah{\bleah}
moving argument. So, one might rewrite
, folks
the \caption example as:
The prompt accepts single-character \caption[Energy: (Einstein’s equation)]{Energy: \(E=mc^
commands: the list of what’s available may
In practice, inserting mathematics in a
be had by typing ?. One immediately valu-
moving argument has already been ad-
able command is h, which gives you an
dressed in LaTeX2e by the robust com-
expansion of TeXs original précis message,
mand \ensuremath:
sometimes accompanied by a hint on what
to do to work round the problem in the \caption{Energy: \ensuremath{E=mc^2}}
short term. If you simply type ‘return’ (or
whatever else your system uses to signal So: always look for alternatives to the
\protect route.
the end of a line) at the prompt, TeX will
attempt to carry on (often with rather little Footnotes can be even more com-
success). plex; “footnotes in LaTeX section head-
ings” deals specifically with that issue.
419 An extra ‘}’??
420 Capacity exceeded [semantic
You’ve looked at your LaTeX source and nest . . . ]
there’s no sign of a misplaced } on the line
! TeX capacity exceeded, sorry [semantic nest size=100].
in question.
...
Well, no: this is TeX’s cryptic way of
If you really absolutely need more capacity,
hinting that you’ve put a fragile command
you can ask a wizard to enlarge me.
in a moving argument.
For example, \footnote is fragile, Even though TeX suggests (as always)
and if we put that in the moving argumentthat enlargement by a wizard may help,
of a \section command, as this message usually results from a broken
macro or bad parameters to an otherwise
\section{Mumble\footnote{I couldn’t think
working of anything better}}
macro.
we get told The “semantic nest” TeX talks about
is the nesting of boxes within boxes. A
! Argument of \@sect has an extra }. macro can provoke the error pretty
stupid
The same happens with captions (the fol- easily:
lowing is a simplification of a comp.text. \def\silly{\hbox{here’s \silly being executed}}
tex post): \silly
\caption{Energy: \[e=mc^2\]} The extended traceback (see general ad-
vice on errors) does help, though it does
giving us the error message
rather run on. In the case above, the trace-
back consists
! Argument of \@caption has an extra }. of
231
\silly ->\hbox { However, sometimes one just needs
here’s \silly beingmore than TeX can offer, and when this
executed}
followed by 100 instances of happens, you’ve just got to work out a dif-
ferent way of doing things. An example is
\silly ->\hbox {here’s \silly
the difficulty of loading PiCTeX with La-
being executed}
TeX. The more modern drawing package,
The repeated lines are broken at exactly pgf with its higher-level interface TikZ is
the offending macro; of course the loop also a common source of such problems.
need not be as simple as this — if \silly In such cases, it is usually possible
calls \dopy which boxes \silly, the ef- to use the e-TeX extensions (all modern
fect is just the same and alternate lines in distributions provide them). The LaTeX
the traceback are broken at alternate posi- package etex modifies the register alloca-
tions. tion mechanism to make use of e-TeX’s
There are in fact two items being con- extended register sets. Etex is a derivative
sumed when you nest boxes: the other of the Plain TeX macro file etex.src, which
is the grouping level. Whether you ex- is used in building the e-TeX Plain format;
haust your semantic nest or your permitted both files are part of the e-TeX distribution
grouping levels first is controlled entirely and are available in current distributions.
by the relative size of the two different sets It is possible that, even with etex
of buffers in your (La)TeX executable. loaded, you still find yourself running
out of things. Problems can be caused
421 No room for a new ‘thing’
by packages that use large numbers of
The technology available to Knuth at the “inserts” (inserts are combinations of
time TeX was written is said to have been counter, box, dimension and skip reg-
particularly poor at managing dynamic isters, used for storing floats and foot-
storage; as a result much of the storage notes). Morefloats does this, of course
used within TeX is allocated as fixed ar- (naturally enough, allocating new floats),
rays, in the reference implementations. and footnote packages such as manyfoot
Many of these fixed arrays are expandable and bigfoot (which uses manyfoot) can
in modern TeX implementations, but size also give problems. The etex extensions
of the arrays of “registers” is written into allow you to deal with these things: the
the specification as being 256 (usually); command \reserveinserts{n} ensures
this number may not be changed if you there is room for hni more inserts. Hint: by
still wish to call the result TeX (see testing default morefloats adds 18 inserts (though
TeX implementations). it can be instructed to use more), and
If you fill up one of these register ar- manyfoot seems to be happy with 10 re-
rays, you get a TeX error message saying served, but there are ‘hard’ limits that we
cannot program around — the discussion
! No room for a new \<thing>. of running out of floats has more about
this. It is essential that you load etex be-
The \things in question may be
fore any other packages, and reserve any
\count (the object underlying LaTeX’s
extra inserts immediately:
\newcounter command), \skip (the ob-
ject underlying LaTeX’s \newlength \documentclass[...]{...}
command), \box (the object underly- \usepackage{etex}
ing LaTeX’s \newsavebox command), or \reserveinserts{28}
\dimen, \muskip, \toks, \read, \write
or \language (all types of object whose The e-TeX extensions don’t help with
use is “hidden” in LaTeX; the limit on the \read or \write objects (and neither will
number of \read or \write objects is just the etex package), but the morewrites pack-
16). age can provide the illusion of large num-
There is nothing that can directly be bers of \write objects.
done about this error, as you can’t extend morewrites.sty : macros/latex/
the number of available registers without contrib/morewrites
extending TeX itself. Of course e-TeX, Ω
422 epsf gives up after a bit
and LuaTeX all do this, as does MicroPress
Inc’s VTeX. Some copies of the documentation of epsf.
The commonest way to encounter one tex seemed once to suggest that the com-
of these error messages is to have broken mand
macros of some sort, or incorrect usage of \input epsf
macros (an example is discussed in epsf is needed for every figure included. If you
problems). follow this suggestion too literally, you get
232
an error 424 Option clash for package
! No room for a new \read . So you’ve innocently added:
after a while; this is because each time
\usepackage[draft]{foo}
epsf.tex is loaded, it allocates itself a
new file-reading handle to check the figure to your document, and LaTeX responds
for its bounding box, and there just aren’t with
enough of these things (see no room for a
new thing). ! LaTeX Error: Option clash for package foo.
The solution is simple — this is in fact
The error is a complaint about loading
an example of misuse of macros; one only
a package with options, more than once.
need read epsf.tex once, so change
LaTeX complains because it has no means
... of examining the options, rather than be-
\input epsf cause it knows there is a problem. (You
\epsffile{...} may load a package any number of times
... in a document’s preamble, with no options,
\input epsf and LaTeX will ignore every loading re-
\epsffile{...} quest after the first; but you may only sup-
(and so on) with a single ply options when you first load the pack-
\input epsf age.)
somewhere near the start of your document, So perhaps you weren’t entirely inno-
and then decorate your \epsffile state- cent — the error would have occurred on
ments with no more than adjustments of the second line of:
\epsfxsize and so on.
\usepackage[dvips]{graphics}
423 Improper \hyphenation will be \usepackage[draft]{graphics}
flushed
which could quite reasonably (and indeed
For example correctly) have been typed:
! Improper \hyphenation will be flushed.
\’#1->{ \usepackage[dvips,draft]
\accent 19 #1} {graphics}
<*> \hyphenation{Ji-m\’e But if you’ve not made that mistake
-nez} (even with several lines separating the
(in Plain TeX) or \usepackage commands, it’s pretty easy
to spot), the problem could arise from
! Improper \hyphenation will be flushed.
\leavevmode ->\unhbox something else loading the package for
\voidb@x you. How do you find the culprit? The
<*> \hyphenation{Ji-m\’e "h " response to the error message tells you
-nez} which options were loaded each time. Oth-
in LaTeX. erwise, it’s down to the log analysis games
As mentioned in “hyphenation fail- discussed in “How to approach errors”; the
ures”, “words” containing \accent com- trick to remember is that that the process
mands may not be hyphenated. As a result, of loading each file is parenthesised in the
any such word is deemed improper in a log; so if package foo loads graphics, the
\hyphenation command. log will contain something like:
Hyphenation happens as paragraphs (<path>/foo.sty ...
are laid out; by this time, TeX knows what ...
font is used for each glyph; thus it knows (<path>/graphics.sty ...
the encoding being used. So the solution ...)
to the problem is to use a font that con- ...
tains the accented character; doing this this )
“hides” the accent from the hyphenation
mechanisms. (the parentheses for graphics are com-
For LaTeX users, this is quite an easy pletely enclosed in those for foo; the same
task; they select an 8-bit font with the pack- is of course true if your class bar is the
age, as in \usepackage[T1]{fontenc}, culprit, except that the line will start with
and accented-letter commands such as the the path to bar.cls).
\’e in \hyphenation{Ji-m\’e-nez} au- If we’re dealing with a package that
tomatically become the single accented loads the package you are interested in,
character by the time the hyphenation gets you need to ask LaTeX to slip in options
to look at it. when foo loads it. Instead of:
233
 \usepackage{foo} \usepackage[a]{foo}
\usepackage[draft]{graphics} ...
\usepackage{foo}
you would write:

\PassOptionsToPackage LaTeX is happy, as it is with:

{draft}{graphics}
\usepackage{foo} \usepackage[a]{foo}
...
The command \PassOptionsToPackage \usepackage[a]{foo}
tells LaTeX to behave as if its options
were passed, when it finally loads a pack-
since LaTeX can see there’s no conflict (in
age. As you would expect from its name,
fact, the second load does nothing).
\PassOptionsToPackage can deal with a
list of options, just as you would have in Similarly,
the the options brackets of \usepackage.
The problem is more tricky if your doc- \usepackage[a,b]{foo}
ument class loads a package you want op- ...
tions for. In this case, instead of: \usepackage[a]{foo}

\documentclass[...]{bar}
produces no error and does nothing for the
\usepackage[draft]{graphics}
second load.
you would write: However

\PassOptionsToPackage
\usepackage[a]{foo}
{draft}{graphics}
...
\documentclass[...]{bar}
\usepackage[b]{foo}
with \PassOptionsToPackage before the
\documentclass command. produces the error; even if option ‘b’ is an
However, if the foo package or the bar alias for option ‘a’ — LaTeX doesn’t “look
class loads graphics with an option of its inside” the package to check anything like
own that clashes with what you need in that.
some way, you’re stymied. For example: The general rule is: the first load of a
package defines a set of options; if a fur-
\PassOptionsToPackage ther \usepackage or \RequirePackage
{draft}{graphics} also calls for the package, the options on
that call may not extend the set on the first
where the package or class does:
load.
\usepackage[final]{graphics} Fortunately, the error (in that sort of
case) is easily curable once you’ve exam-
sets final after it’s dealt with option you ined the preamble of your document.
passed to it, so your draft will get forgot-
Now, suppose package foo loads bar
ten. In extreme cases, the package might
with option b, and your document says:
generate an error here (graphics doesn’t
go in for that kind of thing, and there’s no
indication that draft has been forgotten). \usepackage{foo}
In such a case, you have to modify the ...
package or class itself (subject to the terms \usepackage[a]{bar}
of its licence). It may prove useful to con-
tact the author: she may have a useful al- or
ternative to suggest.
\usepackage[a]{bar}
425 Option clash for package
...
The error message \usepackage{foo}

! LaTeX Error: Option clash for package footmisc

the error will be detected, even though you
means what it says — your document con- have only explicitly loaded bar once. De-
tains a (potentially) clashing pair of op- bugging such errors is tricky: it may in-
tions; sadly, it is not always obvious how volve reading the logs (to spot which pack-
the error has arisen. ages were called), or the documentation of
If you simply write: package foo.
234
426 “Too many unprocessed floats” Techniques for resolution may in-
volve redefining the floats using the float
If LaTeX responds to a \begin{figure}
package’s [H] float qualifier, but you
or \begin{table} command with the er-
are unlikely to get away without using
ror message
\clearpage from time to time.
! LaTeX Error: Too many unprocessed floats.
float.sty :
macros/latex/contrib/float
See the LaTeX manual or LaTeX Companion for explanation.
morefloats.sty : macros/latex/
contrib/morefloats
your figures (or tables) are not being placed
properly. LaTeX has a limited amount of 427 \spacefactor complaints
storage for ‘floats’ (figures, tables, or floats The errors
you’ve defined yourself with the float pack-
age); if something you have done has pre- ! You can’t use ‘\spacefactor’ in vertical mode.
vented LaTeX from typesetting floats, it \@->\spacefactor
will run out of storage space. \@m
This failure usually occurs in extreme or
cases of floats moving “wrongly”; LaTeX
has found it can’t place a float, and floats ! You can’t use ‘\spacefactor’ in math mode.
of the same type have piled up behind it. \@->\spacefactor
How does this happen? — LaTeX guar- \@m
antees that caption numbers are sequential or simply
in the document, but the caption number
is allocated when the figure (or whatever) ! Improper \spacefactor.
is created, and can’t be changed. Thus, if ...
floats are placed out of order, their caption
bite the LaTeX programmer who uses an
numbers would also appear out of order
internal command without taking “precau-
in the body of the document (and in the
tions”. An internal-style command such as
list of figures, or whatever). As a result,
\@foo has been defined or used in a private
enforcement of the guarantee means that
macro, and it is interpreted as \@, followed
simple failure to place a float means that no
by the ‘text’ foo. (\@ is used, for real, to
subsequent float can be placed; and hence
set up end-of-sentence space in some cir-
(eventually) the error.
cumstances; it uses \spacefactor to do
Techniques for solving the problem are that.)
discussed in the floats question already ref- The problem is discussed in detail in “@
erenced. in macro names”, together with solutions.
An alternative may be to use the
morefloats package. The package will al- 428 \end occurred inside a group
locate more “float skeletons” than LaTeX The actual error we observe is:
does by default; each such skeleton may (\end occurred inside a group at level <n>)
then be used to store a float. Beware that and it tells us that something we started in
even with morefloats, the number you can the document never got finished before we
allocate is limited; even with the etex pack- ended the document itself. The things in-
age (which makes available many more volved (‘groups’) are what TeX uses for re-
registers, etc., than LaTeX does by default; stricting the scope of things: you see them,
e-TeX can create lots more registers, but for example, in the “traditional” font selec-
none of those “beyond the original TeX tion commands: {\it stuff\/} — if the
default” may be used in float skeletons). closing brace is left off such a construct,
Thus, etex may offer some relief, but it can the effect of \it will last to the end of the
not be regarded as a panacea document, and you’ll get the diagnostic.
The error also occurs in a long se- TeX itself doesn’t tell you where your
quence of float environments, with no inter- problem is, but you can often spot it by
vening text. Unless the environments will looking at the typeset output in a pre-
fit “here” (and you’ve allowed them to go viewer. Otherwise, you can usually find
“here”), there will never be a page break, mismatched braces using an intelligent ed-
and so there will never be an opportunity itor (at least emacs and winedt offer this
for LaTeX to reconsider placement. (Of facility). However, groups are not only
course, the floats can’t all fit “here” if the created by matching { with }: other group-
sequence is sufficiently prolonged: once ing commands are discussed elsewhere in
the page fills, LaTeX won’t place any more these FAQs, and are also a potential source
floats, leading to the error. of unclosed group.
235
 \begin{henvironmenti} encloses Two LaTeX-specific errors are com-
the environment’s body in a group, and es- monly aired on the newsgroups.
tablishes its own diagnostic mechanism. If The commonest arises from attempt-
you end the document before closing some ing to use an example from the The LaTeX
other environment, you get the ‘usual’ Companion (first edition), and is exempli-
LaTeX diagnostic fied by the following error text:
! LaTeX Error: \begin{blah} on input ! Missing number,
line 6 ended by treated as zero.
\end{document}.
<to be read again>
which (though it doesn’t tell you which
\relax
file the \begin{blah} was in) is usually
l.21 \begin{Ventry}{Return values}
enough to locate the immediate problem. If
The problem arises because, in its first edi-
you press on past the LaTeX error, you get
tion, the Companion’s examples always
one or more repetitions of the “occurred
assumed that the calc package is loaded:
inside a group” message before LaTeX fi-
this fact is mentioned in the book, but of-
nally exits. The checkend package recog-
ten not noticed. The remedy is to load
nises other unclosed \begin{blob} com-
the calc package in any document using
mands, and generates an “ended by” error
such examples from the Companion. (The
message for each one, rather than produc-
problem does not really arise with the sec-
ing the “occurred inside a group” message,
ond edition; copies of all the examples are
which is sometimes useful (if you remem-
ber to load the package). available on the accompanying CD-ROM,
or on CTAN.)
In the absence of such information
The other problem, which is increas-
from LaTeX, you need to use “traditional”
ingly rare nowadays, arises from miscon-
binary search to find the offending group.
figuration of a system that has been up-
Separate the preamble from the body of
graded from LaTeX 2.09: the document
your file, and process each half on its own
uses the times package, and the error ap-
with the preamble; this tells you which half
pears at \begin{document}. The file
of the file is at fault. Divide again and re-
search paths are wrongly set up, and your
peat. The process needs to be conducted
\usepackage{times} has picked up a La-
with care (it’s obviously possible to split a
TeX 2.09 version of the package, which
correctly-written group by chopping in the
in its turn has invoked another which has
wrong place), but it will usually find the
problem fairly quickly. no equivalent in LaTeX2e. The obvious
solution is to rewrite the paths so that La-
e-TeX (and e-LaTeX — LaTeX run on
TeX 2.09 packages are chosen only as a
e-TeX) gives you further diagnostics after
last resort so that the startlingly simple La-
the traditional infuriating TeX one — it ac-
TeX2e times package will be picked up.
tually keeps the information in a similar
Better still is to replace the whole thing
way to LaTeX:
with something more modern still; cur-
(\end occurred inside a group at level 3)
rent psnfss doesn’t provide a times pack-
age — the alternative mathptmx incorpo-
### semi simple group (level 3) entered at line mathematics,
rates Times-like 6 (\begingroup) and a sans-
### simple group (level 2) entered serif
at line 5 ({)
face based on Helvetica, but scaled to
### simple group (level 1) entered match
at line 4 ({)
Times text rather better.
### bottom level
calc.sty : Distributed as part of
The diagnostic not only tells us where the macros/latex/required/tools
group started, but also the way it started:
Examples for LaTeX Companion:
\begingroup or { (which is an alias of
info/examples/tlc2
\bgroup, and the two are not distinguish-
able at the TeX-engine level). The psnfss bundle:
macros/latex/required/psnfss
checkend.sty : Distributed as part of
macros/latex/contrib/bezos 430 “Please type a command or say
\end”
429 “Missing number, treated as Sometimes, when you are running
zero” (La)TeX, it will abruptly stop and present
In general, this means you’ve tried to as- you with a prompt (by default, just a *
sign something to a count, dimension or character). Many people (including this
skip register that isn’t (in TeX’s view of author) will reflexively hit the ‘return’ key,
things) a number. Usually the problem pretty much immediately, and of course
will become clear using the ordinary tech- this is no help at all — TeX just says:
niques of examining errors. (Please type a command or say ‘\end’)
236
and prompts you again. is to transform the graphics file to a format
What’s happened is that your (La)TeX your driver knows about.
file has finished prematurely, and TeX has If you happen to know that your device
fallen back to a supposed including file, driver deals with the format of your file,
from the terminal. This could have hap- you are probably falling foul of a limita-
pened simply because you’ve omitted the tion of the file name parsing code that the
\bye (Plain TeX), \end{document} (La- graphics package uses. Suppose you want
TeX), or whatever. Other common errors to include a graphics file home.bedroom.
are failure to close the braces round a com- eps using the dvips driver; the package
mand’s argument, or (in LaTeX) failure will conclude that your file’s extension is
to close a verbatim environment: in such .bedroom.eps, and will complain.
cases you’ve already read and accepted an The grffile package deals with the last
error message about encountering end of problem (and others — see the package
file while scanning something. documentation); using the package, you
If the error is indeed because you’ve may write:
forgotten to end your document, you can
\usepackage{graphicx}
insert the missing text: if you’re running
\usepackage{grffile}
Plain TeX, the advice, to “say \end” is
...
good enough: it will kill the run; if you’re
\includegraphics{home.bedroom.eps}
running LaTeX, the argument will be nec-
essary: \end{document}. or you may even write
However, as often as not this isn’t
the problem, and (short of debugging the \includegraphics{home.bedroom}
source of the document before ending)
and graphicx will find a .eps or .pdf (or
brute force is probably necessary. Exces-
whatever) version, according to what ver-
sive force (killing the job that’s running
sion of (La)TeX you’re running.
TeX) is to be avoided: there may well be
If for some reason you can’t use grffile,
evidence in the .log file that will be useful
you have three unsatisfactory alternatives:
in determining what the problem is — so
the aim is to persuade TeX to shut itself • Rename the file — for example home.
down and hence flush all log output to file. bedroom.eps→home-bedroom.eps
If you can persuade TeX to read it, • Mask the first dot in the file name:
an end-of-file indication (control-D under \newcommand*{\DOT}{.}
Unix, control-Z under Windows) will pro- \includegraphics{home\DOT bedroom.eps}
voke TeX to report an error and exit im- • Tell the graphics package what the
mediately. Otherwise you should attempt file is, by means of options to the
to provoke an error dialogue, from which \includegraphics command:
you can exit (using the x ‘command’). An
\includegraphics[type=eps,ext=.eps,read=.eps]{home.bedr
accessible error could well be inserting an
illegal character: what it is will depend on grffile.sty : Distributed as part
what macros you are running. If you can’t of the Oberdiek collection
make that work, try a silly command name macros/latex/contrib/oberdiek
or two.
432 “Missing $ inserted”
431 “Unknown graphics extension” There are certain things that only work in
The LaTeX graphics package deals with maths mode. If your document is not in
several different types of DVI (or other) maths mode and you have an _ or a ^ char-
output drivers; each one of them has a po- acter, TeX (and by inheritance, LaTeX too)
tential to deal with a different selection of will say
graphics formats. The package therefore ! Missing $ inserted
has to be told what graphics file types its as if you couldn’t possibly have misunder-
output driver knows about; this is usually stood the import of what you were typ-
done in the hdriveri.def file correspond- ing, and the only possible interpretation is
ing to the output driver you’re using. that you had committed a typo in failing
The error message arises, then, if to enter maths mode. TeX, therefore, tries
you have a graphics file whose extension to patch things up by inserting the $ you
doesn’t correspond with one your driver ‘forgot’, so that the maths-only object will
knows about. Most often, this is because work; as often as not this will land you in
you’re being optimistic: asking dvips to further confusion.
deal with a .png file, or PDFTeX to deal It’s not just the single-character maths
with a .eps file: the solution in this case sub- and superscript operators: anything
237
that’s built in or declared as a maths opera- LaTeX Font Warning: Font shape ‘OT1/cmr/bx/sc’ undefined
tion, from the simplest lower-case \alpha (Font) using ‘OT1/cmr/bx/n’ instead on input
through the inscrutable \mathchoice Substitutions may also be “silent”; in
primitive, and beyond, will provoke the this case, there is no more than an “infor-
error if misused in text mode. mation” message in the log file. For exam-
LaTeX offers a command ple, if you specify an encoding for which
\ensuremath, which will put you in maths there is no version in the current font fam-
mode for the execution of its argument, ily, the ‘default family for the encoding’
if necessary: so if you want an \alpha is selected. This happens, for example, if
in your running text, say \ensuremath you use command \textbullet, which is
{\alpha}; if the bit of running text some- normally taken from the maths symbols
how transmutes into a bit of mathematics, font, which is in OMS encoding. My test
the \ensuremath will become a no-op, so log contained:
it’s pretty much always safe. LaTeX Font Info: Font shape ‘OMS/cmr/m/n’ in size <10>
(Font) Font shape ‘OMS/cmsy/m/n’ tried instea
433 Warning: “Font shape . . . not
available” In summary, these messages are not so
much error messages, as information mes-
LaTeX’s font selection scheme maintains sages, that tell you what LaTeX has made
tables of the font families it has been told of your text. You should check what the
about. These tables list the font families messages say, but you will ordinarily not
that LaTeX knows about, and the shapes be surprised at their content.
and series in which those font families are
type1cm.sty :
available. In addition, in some cases, the
macros/latex/contrib/type1cm
tables list the sizes at which LaTeX is will-
ing to load fonts from the family. type1ec.sty : fonts/ps-type1/cm-
When you specify a font, using one of super/type1ec.sty
the LaTeX font selection commands, La- 434 Unable to read an entire line
TeX looks for the font (that is, a font that
TeX belongs to the generation of applica-
matches the encoding, family, shape, series
tions written for environments that didn’t
and size that you want) in its tables. If the
offer the sophisticated string and i/o ma-
font isn’t there at the size you want, you
nipulation we nowadays take for granted
will see a message like:
(TeX was written in Pascal, and the orig-
LaTeX Font Warning: Font shape ‘OT1/cmr/m/n’ in sizemade
inal Pascal standard <11.5> not available
no mention of
(Font) size <12> substituted on anything
i/o, so that input line ...most trivial
but the
There will also be a warning like: operations were likely to be unportable).
When you overwhelm TeX’s input
LaTeX Font Warning: Size substitutions with differences
(Font)
mechanism,
up to 0.5pt have occurred.
you get told:
! Unable to read an entire line---bufsize=3000.
after LaTeX has encountered \end
Please ask a wizard to enlarge me.
{document}.
The message tells you that you’ve cho- (for some value of ‘3000’ — the quote
sen a font size that is not in LaTeX’s list was from a comp.text.tex posting by a
of “allowed” sizes for this font; LaTeX has someone who was presumably using an
chosen the nearest font size it knows is al- old TeX).
lowed. In fact, you can tell LaTeX to allow As the message implies, there’s (what
any size: the restrictions come from the TeX thinks of as a) line in your input
days when only bitmap fonts were avail- that’s “too long” (to TeX’s way of think-
able, and they have never applied to fonts ing). Since modern distributions tend to
that come in scaleable form in the first have tens of thousands of bytes of input
place. Nowadays, most of the fonts that buffer, it’s somewhat rare that these mes-
were once bitmap-only are also available sages occur “for real”. Probable culprits
in scaleable (Adobe Type 1) form. If your are:
installation uses scaleable versions of the • A file transferred from another sys-
Computer Modern or European Computer tem, without translating record end-
Modern (EC) fonts, you can tell LaTeX to ings. With the decline of fixed-format
remove the restrictions; use the type1cm or records (on mainframe operating sys-
type1ec package as appropriate. tems) and the increased intelligence of
If the combination of font shape and TeX distributions at recognising other
series isn’t available, LaTeX will usually systems’ explicit record-ending char-
have been told of a fall-back combination acters, this is nowadays rather a rare
that may be used, and will select that: cause of the problem.
238
 • A graphics input file, which a pack- to build only the format that you are
age is examining for its bounding interested in.
box, contains a binary preview section. • On a MiKTeX system, click Start→
Again, sufficiently clever TeX distri- Programs→MiKTeX version→
butions recognise this situation, and MiKTeX Options, and in the options
ignore the previews (which are only of window, click Update now.
interest, if at all, to a TeX previewer).
436 Non-PDF special ignored!
The usual advice is to ignore what TeX This is a PDFTeX error: PDFTeX is
says (i.e., anything about enlarging), and running in PDF output mode, and it
to put the problem right in the source. has encountered a \special command
If the real problem is over-long text (\special). PDFTeX is able to generate
lines, most self-respecting text editors willits own output, and in this mode of opera-
be pleased to automatically split long lines tion has no need of \special commands
(while preserving the “word” structure) so (which allow the user to pass information
that they are nowhere any longer than a to the driver being used to generate output).
given length; so the solution is just to edit Why does this happen? LaTeX users,
the file. nowadays, hardly ever use \special com-
If the problem is a ridiculous preview mands on their own — they employ pack-
section, try using ghostscript to reprocess ages to do the job for them. Some pack-
the file, outputting a “plain .eps” file. ages will generate \special commands
(Ghostscript’s distribution includes a scripthowever they are invoked: pstricks is an
ps2epsi which will regenerate the preview example (it’s very raison d’être is to emit
if necessary.) Users of the shareware pro- PostScript code in a sequence of \special
gram gsview will find buttons to perform commands). Pstricks may be dealt with by
the required transformation of the file be- other means (the pdftricks package offers
ing displayed. a usable technique).
More amenable to correction, but more
435 “Fatal format file error; I’m
confusing, are packages (such as color,
stymied”
graphics and hyperref ) that specify a
(La)TeX applications often fail with this “driver”. These packages have plug-in
error when you’ve been playing with the modules that determine what \special
configuration, or have just installed a new (or other commands) are needed to gen-
version. erate any given effect: the pdftex driver
The format file contains the macros for such packages knows not to gener-
that define the system you want to use: any- ate \special commands. In most cir-
thing from the simplest (Plain TeX) all the cumstances, you can let the system itself
way to the most complicated, such as La- choose which driver you need; in this
TeX or ConTeXt. From the command you case everything will act properly when you
issue, TeX knows which format you want. switch to using PDFLaTeX. If you’ve been
The error message using dvips (and specifying the dvips
Fatal format file error; I’m stymied driver) or dvipdfm (for which you have
means that TeX itself can’t understand the to specify the driver), and decide to try
format you want. Obviously, this could PDFLaTeX, you must remove the dvips
happen if the format file had got corrupted, or dvipdfm driver specification from the
but it usually doesn’t. The commonest package options, and let the system recog-
cause of the message, is that a new bi- nise which driver is needed.
nary has been installed in the system: no pdftricks.sty : graphics/pdftricks
two TeX binaries on the same machine can
pstricks.sty : graphics/pstricks
understand each other’s formats. So the
new version of TeX you have just installed, 437 Mismatched mode ljfour and
won’t understand the format generated by resolution 8000
the one you installed last year. You’re running dvips, and you encounter
Resolve the problem by regenerating a stream of error messages, starting with
the format; of course, this depends on “Mismatched mode”. The mode is the de-
which system you are using. fault used in your installation — it’s set in
the dvips configuration file, and ljfour is
• On a teTeX-based system, run
commonest (since it’s the default in most
fmtutil --all distributions), but not invariable.
or The problem is that dvips has encoun-
fmtutil --byfmt=<format name> tered a font for which it must generate a
239
bitmap (since it can’t find it in Type 1 for- enumerate and itemize (this “knowl-
mat), and there is no proforma available to edge” spells out a requirement for class
provide instructions to give to Metafont. writers, since the class supplies the sets of
So what to do? The number 8000 parameters).
comes from the ‘-Ppdf’ option to dvips, From the above, we can deduce that
which you might have found from the an- there are several ways we can run out
swer “wrong type of fonts” (“wrong type of space: we can have 6 lists (of any
of fonts”). The obvious solution is to sort) nested, and try to start a new one;
switch to the trivial substitute ‘-Pwww’, we can have 4 enumerate environments
which selects the necessary type 1 fonts somewhere among the set of nested lists,
for PDF generation, but nothing else: how- and try to add another one; and we can
ever, this will leave you with undesirable have 4 itemize environments somewhere
bitmap fonts in your PDF file. The “proper” among the set of nested lists, and try to add
solution is to find a way of expressing what another one.
you want to do, using type 1 fonts. What can be done about the problem?
Not much, short of rewriting LaTeX — you
438 “Too deeply nested” really need to rewrite your document in a
This error appears when you start a LaTeX slightly less labyrinthine way.
list. 439 Capacity exceeded — input levels
LaTeX keeps track of the nesting of
The error
one list inside another. There is a set of
list formatting parameters built-in for ap- ! TeX capacity exceeded, sorry [text input levels=15].
plication to each of the list nesting levels; is caused by nesting your input too deeply.
the parameters determine indentation, item You can provoke it with the trivial (Plain
separation, and so on. The list environ- TeX) file input.tex, which contains noth-
ment (the basis for list environments like ing but:
itemize and enumerate) “knows” there \input input
are only 6 of these sets. In the real world, you are unlikely to en-
There are also different label defini- counter the error with a modern TeX distri-
tions for the enumerate and itemize en- bution. TeTeX (used to produce the error
vironments at their own private levels of message above) allows 15 files open for
nesting. Consider this example: TeX input at any one time, which is im-
probably huge for a document generated
\begin{enumerate} by real human beings.
\item first item of first enumerateHowever, for those improbable (or
\begin{itemize} machine-generated) situations, some distri-
\item first item of first itemize butions offer the opportunity to adjust the
\begin{enumerate} parameter max_in_open in a configuration
\item first item of second enumerate
file.
...
\end{enumerate} 440 PDFTeX destination . . . ignored
... The warning:
\end{itemize}
... ! pdfTeX warning (ext4): destination with the same iden
\end{enumerate} (name{page.1}) has been already used, duplicate ignored

In the example, arises because of duplicate page numbers

in your document. The problem is usu-
• the first enumerate has labels as for a ally soluble: see PDF page destinations —
first-level enumerate, and is indented which answer also describes the problem
as for a first-level list; in more detail.
• the first itemize has labels as for a If the identifier in the message is dif-
first level itemize, and is indented as ferent, for example name{figure.1.1},
for a second-level list; and the problem is (often) due to a problem
• the second enumerate has labels as of package interaction. The README in
for a second-level enumerate, and is the hyperref distribution mentions some
indented as for a third-level list. of these issues — for example, equation
and eqnarray as supplied by the amsmath
Now, as well as LaTeX knowing that package; means of working around the
there are 6 sets of parameters for inden- problem are typically supplied there.
tation, it also knows that there are only Some packages are simply incompati-
4 types of labels each, for the environments ble with hyperref , but most work simply by
240
ignoring it. In most cases, therefore, you \begin{tabular}{ll}
should load your package before you load hello & there goodbye\\
hyperref , and hyperref will patch things now
up so that they work, so you can utilise \end{tabular}
your (patched) package after loading both:
(with the second line of the table having
\usepackage{your package} only one cell).
... Rather more difficult to spot is the oc-
\usepackage[opts]{hyperref} currence of the error when you’re using
... alignment instructions in a “p” column:
hcode that uses your packagei \usepackage{array}
For example: ...
\begin{tabular}{l>{\raggedright}p{2in}}
\usepackage{float} % defines
here\newfloat
& we are again \\
... happy & as can be
\usepackage[...]{hyperref} % patches \newfloat
\end{tabular}
...
\newfloat{...}{...}{...} the problem here (as explained in tabular
cell alignment) is that the \raggedright
You should load packages in this order as a command in the column specification has
matter of course, unless the documentation overwritten tabular’s definition of \\, so
of a package says you must load it after that “happy” appears in a new line of the
hyperref . (There are few packages that second column, and the following & ap-
require to be loaded after hyperref: one pears to LaTeX just like the second & in
such is memoir’s “hyperref fixup” package the first example above.
memhfixc.) Get rid of the error in the way de-
If loading your packages in the (seem- scribed in tabular cell alignment — either
ingly) “correct” order doesn’t solve the use \tabularnewline explicitly, or use
problem, you need to seek further help. the \RBS trick described there.
441 Alignment tab changed to \cr The amsmath package adds a further
twist; when typesetting a matrix (the pack-
This is an error you may encounter in La- age provides many matrix environments),
TeX when a tabular environment is be- it has a fixed maximum number of columns
ing processed. “Alignment tabs” are the in a matrix — exceed that maximum, and
& signs that separate the columns of a
the error will appear. By default, the max-
tabular (or array or matrix) environ-
imum is set to 10, but the value is stored
ment; so the error message in counter MaxMatrixCols and may be
! Extra alignment tab has been changed (in
changed tothe same way as any counter):
\cr

could arise from a simple typo, such as: \setcounter{MaxMatrixCols}{20}

array.sty : Distributed as part of

\begin{tabular}{ll}
macros/latex/required/tools
hello & there & jim \\
goodbye & now 442 Graphics division by zero
\end{tabular} While the error
where the second & in the first line of the ! Package graphics Error: Division by 0.
table is more than the two-column ll col-
umn specification can cope with. In this can actually be caused by offering the pack-
case, an extra “l” in that solves the prob- age a figure which claims to have a zero
lem. (If you continue from the error in dimension, it’s more commonly caused by
this case, “jim” will be moved to a row rotation.
of his own.) Another simple typo that can Objects in TeX may have both height
provoke the error is: (the height above the baseline) and depth
(the distance the object goes below the
\begin{tabular}{ll} baseline). If you rotate an object by
hello & there 180 degrees, you convert its height into
goodbye & now depth, and vice versa; if the object started
\end{tabular} with zero depth, you’ve converted it to a
zero-height object.
where the ‘\\’ has been missed from the
Suppose you’re including your graphic
first line of the table. In this case, if you
with a command like:
continue from the error, you will find that
LaTeX has made a table equivalent to: \includegraphics[angle=180,height=5cm]{myfig.eps}
241
In the case that myfig.eps has no depth when your document is being ‘written’ in
to start with, the scaling calculations will Unicode. The Unicode standard defines
produce the division-by-zero error. “Byte Order Marks” (BOM), that reassure
Fortunately, the graphicx package has a program (that reads the document) of the
a keyword totalheight, which allows way the Unicode codes are laid out. Sadly
you to specify the size of the image rela- ordinary LaTeX or PDFLaTeX choke on
tive to the sum of the object’s height and BOMs, and consider them typesetting re-
depth, so quests. The error message you see will
look like:
\includegraphics[angle=180,totalheight=5cm]{myfig.eps}

will resolve the error, and will behave as ! LaTeX Error: Missing \begin{document}.
you might hope. ...
If you’re using the simpler graphics l.1 <?>
package, use the * form of the <?><?>\documentclass{article}
\resizebox command to specify the use
of totalheight:
(Those <?>s are your operating system’s
\resizebox*{!}{5cm}{% representation of an unknown character;
\rotatebox{180}{% on the author’s system it’s a reverse video
\includegraphics{myfig.eps}%
‘?’ sign.)
}% You can spot the BOM by examining
} the bytes; for example, the Unix hexdump
graphics.sty,graphicx.sty : application can help:
Both parts of the macros/latex/
required/graphics bundle $ hexdump -C <file>
00000000 ef bb bf 5c 64 6f 63 75 ...
443 Missing \begin{document}
The preamble of your document is the
stuff before \begin{document}; you put The 5c 64 6f 63 75 are the “\docu” at
\usepackage commands and your own
the start of (the ‘real’ part of) your doc-
macro definitions in there. LaTeX doesn’t ument; the three bytes before it form the
like typesetting anything in the preamble, BOM.
so if you have: How to stop your editor from doing
this to you depends, of course, on the
• typed the odd grumble, editor you use; if you are using GNU
• created a box with \newsavebox and Emacs, you have to change the encoding
put something in it using \sbox (or from utf-8-with-signature to ‘plain’
the like), utf-8; instructions for that are found on
• forgotten to put \begin{document} the “stack overflow” site
into the document, at all, or even
(So far, all instances of this problem
• gave it the wrong file
that the author has seen have afflicted GNU
the error is inevitable and the solution is Emacs users.)
simple — judicious use of comment mark- Fortunately XeTeX and LuaTeX know
ers (‘%’) at the beginning of a line, moving about BOMs and what to do with them, so
things around, providing something that LaTeX using them is “safe”.
was missing . . . or switching to the correct
file.
The error may also occur while read- 444 \normalsize not defined
ing the .aux file from an earlier processing
The LaTeX error:
run on the document; if so, delete the .aux
file and start again from scratch. If the er-
ror recurs, it could well be due to a buggy The font size command \normalsize is not defined:
class or package. there is probably something wrong with the class file.
However, it may be that none of the
above solves the problem. reports something pretty fundamental (doc-
If so, remember that things that appear ument base font size has not been set,
before \documentclass are also problem- something the document class does for
atical: they are inevitably before \begin you). It can, in principle, be a problem
{document}! with the document class, but is more of-
Unfortunately, modern editors are ca- ten caused by the user forgetting to start
pable of putting things there, and prevent- their document with a \documentclass
ing you from seeing them. This can happen command.
242
445 Too many math alphabets \begin{figure}
TeX mathematics is one of its most impres- \includegraphics{foo}
sive features, yet the internal structure of \end{figure}
the mechanism that produces it is painfully \hline
complicated and (in some senses) patheti- \end{tabular}
cally limited. One area of limitation is that a construction that was supposed to put
one is only allowed 16 ”maths alphabets” a frame around the diagram, but doesn’t
LaTeX offers the user quite a lot of work, any more than:
flexibility with allocating maths alphabets,
\framebox{\begin{figure}
but few people use the flexibility directly.
\includegraphics{foo}
Nevertheless, there are many packages that
\end{figure}%
provide symbols, or that manipulate them,
}
which allocate themselves one or more
maths alphabet. The problem is, that the tabular environ-
If you can’t afford to drop any of these ment, and the \framebox command re-
packages, you might be able to consider strain the figure environment from its
switching to use of XeTeX or LuaTeX, natural métier, which is to float around the
which both have 65536 alphabet slots avail- document.
able. (Such a change is best not done The solution is simply not to use the
when under pressure to complete a doc- figure environment here:
ument; other issues, such as font availabil-
\begin{tabular}{|l|}
ity) could make a change impractical.)
\hline
Even if switching is not possible,
\includegraphics{foo}
there’s still hope if you’re using the bm
\hline
package to support bold maths: bm is capa-
\end{tabular}
ble of gobbling alphabets as if there is no
tomorrow. The package defines two lim- What was the float for? — as written in
iter commands: \bmmax (for bold symbols; the first two examples, it serves no useful
default 4) and \hmmax (for heavy symbols, purpose; but perhaps you actually wanted a
if you have them; default 3), which control diagram and its caption framed, in a float.
the number of alphabets to be used. It’s simple to achieve this — just re-
Any reduction of the \xxmax variables verse the order of the environments (or
will slow bm down — but that’s surely bet- of the figure environment and the com-
ter than the document not running at all. So mand):
unless you’re using maths fonts (such as \begin{figure}
Mathtime Plus) that feature a heavy sym- \begin{tabular}{|l|}
bol weight, suppress all use of heavy fami- \hline
lies by \includegraphics{foo}
\newcommand{\hmmax}{0} \caption{A foo}
\hline
(before loading bm), and then steadily re- \end{tabular}
duce the bold families, starting with \end{figure}

\newcommand{\bmmax}{3} The same goes for table environments

(or any other sort of float you’ve defined
(again before loading bm), until (with a bit for yourself) inside tabulars or box com-
of luck) the error goes away. mands; you must get the float environment
bm.sty : Distributed as part of out from inside, one way or another.
macros/latex/required/tools
447 Perhaps a missing \item?
446 Not in outer par mode Sometimes, the error
The error:
Something’s wrong--perhaps a missing \item
! LaTeX Error: Not in outer par actually
mode. means what it says:

comes when some “main” document fea- \begin{itemize}

ture is shut up somewhere it doesn’t like. boo!
The commonest occurrence is when \end{itemize}
the user wants a figure somewhere inside a
table: produces the error, and is plainly in need
of an \item command.
\begin{tabular}{|l|} You can also have the error appear
\hline when at first sight things are correct:
243
 \begin{tabular}{l} Inside the \fbox command, that doesn’t
\begin{enumerate} work, and subsequent macros convince
\item foo\\ themselves that there’s a missing \item
\item bar command.
\end{enumerate} To solve this rather cryptic error, one
\end{tabular} must put the alltt inside a paragraph-
style box. The following modification of
produces the error at the \\. This usage is the above does work:
just wrong; if you want to number the cells
in a table, you have to do it “by hand”: \fbox{%
\begin{minipage}{0.75\textwidth}
\newcounter{tablecell} \begin{alltt}
... hi, there!
\begin{tabular}{l} \end{alltt}
\stepcounter{tablecell} \end{minipage}
\thetablecell. foo\\ }
\stepcounter{tablecell}
The code above produces a box that’s far
\thetablecell. bar
too wide for the text. One may want to use
\end{tabular}
something that allows variable size boxes
This is obviously untidy; a command in place of the minipage environment.
\numbercell defined as: Oddly, although the verbatim envi-
ronment wouldn’t work inside a \fbox
\newcounter{tablecell} command argument (see verbatim in com-
... mand arguments), you get an error that
\newcommand*{\numbercell}{% complains about \item: the environment’s
\stepcounter{tablecell}% internal list bites you before verbatim has
\thetablecell. % ** even had a chance to create its own sort of
} chaos.
could make life easier: Another (seemingly) obvious use of
\fbox also falls foul of this error:
\begin{tabular}{l}
\fbox{\section{Boxy section}}
\numbercell foo\\
\numbercell bar This is a case where you’ve simply got to
\end{tabular} be more subtle; you should either write
your own macros to replace the insides of
Note the deliberate introduction of a LaTeX’s sectioning macros, or look for
space as part of the command, marked some alternative in the packages discussed
with asterisks. Omitted above, the code in “The style of section headings”.
needs to set the counter tablecell to
zero (\setcounter{tablecell}{0}) be- 448 Illegal parameter number in
fore each tabular that uses it. definition
The error also regularly appears when The error message means what it says. In
you would never have thought that a \item the simple case, you’ve attempted a defini-
command might be appropriate. For exam- tion like:
ple, the seemingly innocent: \newcommand{\abc}{joy, oh #1!}
\fbox{% or (using TeX primitive definitions):
\begin{alltt}
\def\abc{joy, oh #1!}
boo!
\end{alltt}% In either of the above, the definition uses an
} argument, but the programmer did not tell
(La)TeX, in advance, that she was going to.
produces the error (the same happens with The fix is simple — \newcommand{\abc}
\mbox in place of \fbox, or with either [1], in the LaTeX case, \def\abc#1 in
of their “big brothers”, \framebox and the basic TeX case.
\makebox). This is because the alltt The more complicated case is exempli-
environment uses a “trivial” list, hidden fied by the attempted definition:
inside its definition. (The itemize envi-
\newcommand{\abc}{joy, oh joy!%
ronment also has this construct inside it-
\newcommand{\ghi}[1]{gloom, oh #1!}%
self, in fact, so \begin{itemize} won’t
}
work inside an \fbox, either.) The list con-
struct wants to happen between paragraphs, will also produce this error, as will its TeX
so it makes a new paragraph of its own. primitive equivalent:
244
 \def\abc{joy, oh joy!% \parbox{25cm}{%
\def\ghi#1{gloom, oh #1!}% \begin{figure}[H]
} ...
\caption{Apparently floating...}
This is because special care is needed when \end{figure}%
defining one macro within the code of an- }
other macro. This is explained elsewhere,
separately for LaTeX definitions and for This example makes little sense as it
TeX primitive definitions stands; however, it is conceivable that sane
449 Float(s) lost uses could be found (for example, using a
package such as algorithm2e to place two
The error algorithms side-by-side).
! LaTeX Error: Float(s) lost. algorithm2e.sty : macros/latex/
contrib/algorithm2e
seldom occurs, but always seems deeply
cryptic when it does appear. float.sty :
The message means what it says: one macros/latex/contrib/float
or more figures, tables, etc., or margin-
pars has not been typeset. (Marginpars 451 Token not allowed in
are treated internally as floats, which is PDFDocEncoded string
how they come to be lumped into this error The package hyperref produces this error
message.) when it doesn’t know how to make some-
The most likely reason is that you thing into a “character” that will go into
placed a float or a \marginpar command one of its PDF entries. For example, the
inside another float or marginpar, or in- (unlikely) sequence
side a minipage environment, a \parbox
or \footnote. Note that the error may be \newcommand{\filled}[2]{%
detected a long way from the problematic #1%
command(s), so the techniques of tracking \hfil
down elusive errors all need to be called #2%
into play. }
This author has also encountered the er- \section{\filled{foo}{bar}}
ror when developing macros that used the
LaTeX internal float mechanisms. Most provokes the error. Hyperref goes on to
people doing that sort of thing are expected tell you:
to be able to work out their own prob-
lems. . . removing ‘\hfil’ on input line ...
450 Not in outer par mode
It’s not surprising: how would you put the
For example: typesetting instruction \hfil into a PDF
bookmark?
*\mbox{\marginpar{foo}}
Hyperref allows you to define an al-
! LaTeX Error: Not in outer par mode. for such things: the command
ternative
\texorpdfstring, which takes two argu-
The error comes when you try to build ments — the first is what is typeset, the
something movable inside a box. Movable second is what is put into the bookmark.
things, in this context, are floating environ- For example, what you would probably
ments (figure and table, for example), like in this case is just a single space in the
and \marginpars. LaTeX simply doesn’t bookmark; if so, the erroneous example
have the mechanisms for floating out of above would become:
boxes. In fact, floats and \marginpars
themselves are built out of boxes, so that \newcommand{\filled}[2]{%
they can’t be nested. #1%
If your error arises from \marginpar, \texorpdfstring{\hfil}{\space}%
you simply have to think of an alternative #2%
way of placing the command; there is no }
slick solution. \section{\filled{foo}{bar}}
If a floating environment is the culprit,
it may be possible to use the “H” placement and with that definition, the example
option, provided (for example) by the float will compile succesfully (hyperref knows
package: about the macro \space).
245
452 Checksum mismatch in font These forms are (as the warning says) La-
When Metafont generates a font it includes TeX 2.09 syntax, and to get rid of the warn-
a checksum in the font bitmap file, and in ing, you must change the command.
the font metrics file (TFM). (La)TeX in- The simple form is easy to deal with:
cludes the checksum from the TFM file in \documentstyle{article}
the DVI file.
When dvips (or other DVI drivers) pro- should become:
cess a DVI file, they compare checksums \documentclass{article}
in the DVI file to those in the bitmap fonts
The complex form is more difficult, since
being used for character images. If the
LaTeX 2.09 “options” conflate two sorts
checksums don’t match, it means the font
of things — options for the class (such as
metric file used by (La)TeX was not gener-
11pt, fleqn), and packages to be loaded.
ated from the same Metafont program that
So:
generated the font.
This commonly occurs when you’re \documentstyle[11pt,verbatim]
processing someone else’s DVI file. {article}
The fonts on your system may also be should become:
at fault: possibilities are that the new TFM
was not installed, or installed in a path after \documentclass[11pt]
an old TFM file, or that you have a personal {article}
cache of bitmaps from an old version of \usepackage{verbatim}
the font. because 11pt happens to be a class option,
In any case, look at the output – the while verbatim is a package.
chances are that it’s perfectly OK, since There’s no simple way to work out
metrics tend not to change, even when the what are class options under LaTeX 2.09;
bitmaps are improved. (Indeed, many font for article, the list includes 10pt, 11pt,
designers — Knuth included — maintain 12pt, draft, fleqn, leqno, twocolumn
the metrics come what may.) and twoside — anything else must be a
If the output does look bad, your only package.
chance is to regenerate things from scratch. Your document may well “just work”
Options include: flushing your bitmap after changes like those above; if not, you
cache, rebuild the TFM file locally, and should think through what you’re trying to
so on. do, and consult documentation on how to
453 Entering compatibility mode do it — there are lots of free tutorials to
help you on your way, if you don’t have
You run your LaTeX job, and it starts by access to a LaTeX manual of any sort.
saying
454 LaTeX won’t include from other
Entering LaTeX 2.09 COMPATIBILITY MODE directories
followed by lines of asterisks and You wanted to \include{../bar/xyz.tex},
!!WARNING!!. but LaTeX says:
This means that the document is not latex: Not writing to ../bar/xyz.aux (openout_any = p).
written in “current” LaTeX syntax, and that ! I can’t write on file ‘../bar/xyz.aux’.
there is no guarantee that all parts of the
document will be formatted correctly. The error comes from TeX’s protection
If the document is someone else’s, and against writing to directories that aren’t de-
you want no more than a copy to read, ig- scendents of the one where your document
nore the error. The document may fail else- resides. (The restriction protects against
where, but as often as not it will provide problems arising from LaTeXing someone
a .dvi or .pdf that’s adequate for most else’s malicious, or merely broken, docu-
purposes. ment. If such a document overwrites some-
If it’s a new document you have just thing you wanted kept, there is obvious
started working on, you have been misled potential for havoc.)
by someone. You have written something Document directory structures that can
like: lead to this problem will look like the fic-
tional mybook:
\documentstyle{article}
./base/mybook.tex
or, more generally: ./preface/Preface.tex
./preface/***
\documentstyle[options] ./chapter1/Intro.tex
{class} ...
246
With such a structure, any document is not available, install from the .tds.zip
directory (other than the one where files available for both packages on CTAN.
mybook.tex lives), seems “up” the tree l3kernel bundle:
from the base directory. (References macros/latex/contrib/l3kernel
to such files will look like \include
{../preface/Preface}: the “..” is the l3packages bundle: macros/latex/
hint.) contrib/l3packages
But why did it want to write at all? —
“what’s going in in my \include” ex-
plains how \include works, among other V Current TeX-related
things by writing an .aux file for every projects
\included file.
Solutions to the problem tend to be 456 The LaTeX project
drastic:
The LaTeX project team (see http://www.
1. Restructure the directories that hold latex-project.org/latex3.html) is a
your document so that the master file small group of volunteers whose aim is to
is at the root of the tree: produce a major new document processing
./mybook.tex system based on the principles pioneered
./mybook/preface/Preface.tex by Leslie Lamport in the current LaTeX.
./mybook/preface/*** The new system is (provisionally) called
./mybook/chapter1/Intro.tex LaTeX3; it will remain freely available and
... it will be fully documented at all levels.
The LaTeX team’s first product (La-
and so on. TeX2e) was delivered in 1994 (it’s now
2. Did you actually need \include? — properly called “LaTeX”, since no other
if not, you can replace \include by version is current).
\input throughout. (This only works
LaTeX2e was intended as a consolida-
if you don’t need \includeonly.)
tion exercise, unifying several sub-variants
3. You could patch your system’s texmf.
of LaTeX while changing nothing whose
cnf — if you know what you’re doing,
change wasn’t absolutely necessary. This
the error message should be enough
has permitted the team to support a single
of a hint; this action is definitely not
version of LaTeX, in parallel with develop-
recommended, and is left to those who
ment of LaTeX3.
can “help themselves” in this respect.
Some of the older discussion papers
455 Support package expl3 too old about directions for LaTeX3 are to be
found on CTAN; other (published) arti-
Some (rather modern) packages are written
cles are to be found on the project web
using the LaTeX3 programming environ-
site (http://www.latex-project.org/
ment. Since LaTeX3 is still under devel-
papers/).
opment, the author cannot reliably guess
what version of LaTeX3 the user has in- Some of the project’s experimental
stalled, and whether that version is ade- code is visible on the net:
quate for the current package. Thus the
• via http://www.latex-project.
package’s code often checks the user’s in-
org/code.html, which points to the
stallation, and complains if it’s older than
project’s SVN repository;
the author’s installation at time of testing.
• via the project’s GitHub mirror;
The error message is:
• from CTAN: snapshots of two ma-
! Support package expl3 too old. jor collections from the code, l3kernel
(supporting LaTeX3 coding conven-
The “additional help” tells you the so- tions in a LaTeX2e environment),
lution: update your LaTeX3 installation. l3packages (a first cut of a “docu-
The relevant things are l3kernel (the pro- ment designer’s interface”) as well as
gramming environment, which contains l3experimental (new stuff that’s still
the expl3 mentioned in the error message) under development).
and l3packages (LaTeX3 constructs such
as command definitions). The packages l3kernel and l3packages pro-
While this sounds a drastic remedy, it vide an “experimental harness” that may
is no longer the major undertaking it once be used as a testbed for LaTeX3 work.
was — if you are using a modern TeX dis- Note that l3kernel introduces a coding
tribution that you installed yourself, ask it structure quite different from earlier La-
to update over the internet; if that choice TeX code; a few hardy authors, who are
247
not members of the project, are neverthe- Conversion of (La)TeX source to
less using it in their development work. XML is already available (through
Anyone may participate in discussions TeX4ht at least), and work contin-
of the future of LaTeX through the mail- ues in that arena. The alternative,
ing list latex-l; some development work authoring in XML (thus producing
(outside the project) is discussed on the list. documents that are immediately Web-
Subscribe to the list by sending a message friendly, if not ready) and using
‘subscribe latex-l <your name>’ to (La)TeX to typeset is also well ad-
[email protected] vanced. One useful technique is trans-
l3experimental bundle: macros/ forming the XML to LaTeX, using an
latex/contrib/l3experimental XSLT stylesheet or code for an XML
library, and then simply using LaTeX;
l3kernel bundle:
alternatively, one may typeset direct
macros/latex/contrib/l3kernel
from the XML source.
LaTeX project publications: Direct representation of mathematics
info/ltx3pub MathML is a standard for representing
l3packages bundle: macros/latex/ maths on the Web; its original version
contrib/l3packages was distinctly limited, but version 2
of MathML has had major browser
457 Future WWW technologies and support since 2002 with richness of
(La)TeX mathematical content for online pur-
An earlier answer (“converting to HTML”) poses approaching that of TeX for
addresses the issue of converting existing print. Browser support for MathML is
(La)TeX documents for viewing on the provided by amaya, the ‘Open Source’
Web as HTML. All the present techniques browser mozilla (and its derivatives
are somewhat flawed: the answer explains including NetScape, Firefox and
why. Galeon) and Internet Explorer when
However, things are changing, with bet- equipped with a suitable plug-in such
ter font availability, cunning HTML pro- as MathPlayer. There’s evidence
gramming and the support for new Web that (La)TeX users are starting to use
standards. such browsers. Some believe that
XHTML+MathML now provides bet-
Font technologies Direct representation
ter online viewing than PDF. Work
of mathematics in browsers has been
to produce XHTML+MathML is well
hampered up to now by the limited
advanced in both the TeX4ht and TtH
range of symbols in the fonts whose
projects for (La)TeX conversion.
availability designers can count on.
The MathJax engine will process the
Some existing (La)TeX to HTML
content of LaTeX \[ . . . \] and \(
converters provide maths symbols by
. . . \) ‘environments’ in an HTML
hitching them to alternate font face
document, to produce mathematical
specifications for standard code points
output that may (for example) be cut-
in a non-standard way. This does noth-
and-pasted into other programs.
ing for the universality of the HTML
Incorporation into your document can
so generated.
be as simple as incorporating:
Now, however, free Unicode-encoded
<script type="text/javascript"
OpenType fonts, with coverage of
src="http://cdn.mathjax.org/mathjax/latest/MathJax.js
mathematical symbols, are starting
</script>
to appear. The much-heralded STIX
fonts are now available on CTAN, into the header of your HTML doc-
and a tweaked version (XITS) and ument, though the MathJax project’s
Asana Math are also available. The site also allows you to download your
STIX project has still not released own copy and install it on one of your
macros for using the fonts, but the servers. MathJax is open source soft-
unicode-math package will do what ware, so you could, in principle, ex-
is necessary under XeTeX and Lua- tend it to do even more eccentric tasks.
TeX, and the fonts can of course be An approach different from (La)TeX
used in browsers. conversion is taken by the GELLMU
XML The core of the range of new Project. Its article XML document
standards is XML, which provides type, which has a markup vocabulary
a framework for better structured close to LaTeX that can be edited us-
markup; limited support for it has al- ing LaTeX-like markup (even though
ready appeared in some browsers. it is not LaTeX — so far), comes
248
 with translators that make both PDF XITS fonts: fonts/xits
(via pdflatex) and XHTML+MathML.
Such an approach avoids the inher- 458 Making outline fonts from
ent limitations of the “traditional” Metafont
(La)TeX translation processes, which TeXtrace, originally developed by Péter Sz-
have traps that can be sprung by unfet-
abó, is a bundle of Unix scripts that use
tered use of (La)TeX markup. Martin Weber’s freeware boundary trac-
Graphics SVG is a standard for graphics ing package autotrace to generate Type 1
representation on the web. While the outline fonts from Metafont bitmap font
natural use is for converting existingoutputs. The result is unlikely ever to
figures, representations of formulas be of the quality of the commercially-
are also possible, in place of the sepa-
produced Type 1 font, but there’s always
rate bitmaps that have been used in the
the FontForge font editor to tidy things.
past (and while we wait for the wider Whatever, there remain fonts which many
deployment of MathML). people find useful and which fail to attract
Browser plug-ins, that deal with SVG the paid experts, and auto-tracing is pro-
are already available (Adobe offer one,
viding a useful service here. Notable sets
for example). More recently, the open of fonts generated using TeXtrace are Péter
source graphics editor Inkscape has Szabó’s own EC/TC font set tt2001 and
appeared, and has been reported to be Vladimir Volovich’s CM-Super set, which
useful for SVG-related work in at least
covers the EC, TC, and the Cyrillic LH
one TeX-related project. Be aware font sets (for details of both of which sets,
that the developers of Inkscape have see “8-bit” type 1 fonts).
no illusions about being able to re- Another system, which arrived slightly
place commercial software, yet. . . later, is mftrace: this is a small Python
Direct use of TeX markup Some time program that does the same job. Mftrace
back, IBM developed a browser plug- may use either autotrace (like TeXtrace)
in called TechExplorer, which would or Peter Selinger’s potrace to produce the
display (La)TeX documents direct in a initial outlines to process. Mftrace is said
browser. Over the years, it developed to be more flexible, and easier to use, than
into a MathML browser plug-in, while is TeXtrace, but both systems are increas-
still retaining its (La)TeX abilities, but
ingly being used to provide Type 1 fonts to
it’s now distributed (free for Linux the public domain.
and Windows platforms) by Integre The MetaType1 system aims to use
Technical Publishing. Metafont font sources, by way of Metapost
The disadvantage of the TechExplorer and a bunch of scripts and so on, to pro-
approach is that it places the onus onduce high-quality Type 1 fonts. The first
the browser user; and however techni- results, the Latin Modern fonts, are now
cally proficient you are, it’s never safe
well-established, and a bunch of existing
to assume too much of your readers. designs have been reworked in MetaType1
An interesting alternative is MathTeX,format.
which sits on your server as a CGI Mf2pt1 is another translator of Meta-
script, and you use it to include yourfont font sources by way of Metapost;
TeX, in your HTML, as if it were an in addition, available, mf2pt1 will use
image: fontforge (if it’s available) to auto-hint the
<img src="/cgi-bin/mathtex.cgi?f(x)=\int\limits_{-\infty}^xe^{-t^2}dt">
result of its conversion. (Mf2pt1 is also
(Mathtex supersedes the author’s ear- written in perl.)
lier mimetex.) MetaType1:
Asana Math fonts: fonts/Asana-Math fonts/utilities/metatype1

GELLMU : support/gellmu mf2pt1: support/mf2pt1

MathTeX : support/mathtex
459 The TeX document preparation
MimeTeX : support/mimetex environment
STIX fonts: fonts/stix
“Why TeX is not WYSIWYG” outlines the
tex4ht: obsolete/support/TeX4ht/ reasons (or excuses) for the huge dispar-
tex4ht-all.zip (but see ity of user interface between “typical” TeX
http://tug.org/tex4ht/) environments and commercial word pro-
unicode-math.sty : cessors.
macros/latex/contrib/unicode- Nowadays, at last, there is a range of
math tools available that try either to bridge or
249
to close the gap. One range modestly fo- correlation between source and previews
cuses on providing the user with a legible in a more direct way: it uses a LaTeX pack-
source document. At the other extreme we age to chop the document source into in-
have TeXmacs, a document processor using teresting fragments (like figures, text or
TeX’s algorithms and fonts for both editor display math) which it runs through La-
display and printing. TeXmacs does not TeX and replaces the source text of those
use the TeX language itself (though among fragments with the corresponding rendered
other formats, LaTeX may be exported and output images. Since it does not know
imported). A bit closer to LaTeX is LyX, about the structure of the images, at the
which has its own editor display and file actual cursor position the source text is dis-
formats as well, but does its print output played while editing rather than the pre-
by exporting to LaTeX. The editor display view. This approach is more or less a
merely resembles the printed output, but hybrid of the source prettifying and fast
you have the possibility of entering arbi- preview approaches since it works in the
trary LaTeX code. If you use constructs source buffer but uses actual previews ren-
that LyX does not understand, it will just dered by LaTeX.
display them as source text marked red, but A more ambitious contender is called
will properly export them. TeXlite. This system is only available on
Since a lot of work is needed to cre- request from its author; it continuously
ate an editor from scratch that actually is updates its screen with the help of a spe-
good at editing (as well as catering for cial version of TeX dumping its state in
TeX), it is perhaps no accident that sev- a compressed format at each page and us-
eral approaches have been implemented ing hooks into TeX’s line breaking mech-
using the extensible emacs editor. The low anism for reformatting paragraphs on the
end of the prettifying range is occupied fly. That way, it can render the output from
by syntax highlighting: marking TeX to- the edited TeX code with interactive speed
kens, comments and other stuff with spe- on-screen, and it offers the possibility of
cial colours. Many free editors (including editing directly in the preview window.
emacs) can cater for TeX in this way. Un- That many of these systems occupy
der Windows, one of the more popular ed- slightly different niches can be seen by
itors with such support is the Shareware comparing the range of the emacs-based
product winedt. Continuing the range of solutions ranging from syntax highlighting
tools prettifying your input, we have the to instant previewing: all of them can be
emacs package x-symbol, which does the activated at the same time without actually
WYSIWYG part of its work by replacing interfering in their respective tasks.
single TeX tokens and accented letter se- The different approaches offer various
quences with appropriate-looking charac- choices differing in the immediacy of their
ters on the screen. response, the screen area they work on
A different type of tool focuses on mak- (source or separate window), degree of cor-
ing update and access to previews of the respondence of the display to the final out-
typeset document more immediate. A re- put, and the balance they strike between
cent addition in several viewers, editors visual aid and visual distraction.
and TeX executables are so-called ‘source preview-latex : Distributed as part of
specials’ for cross-navigation. When TeX support/auctex
compiles a document, it will upon request
texmacs: Browse support/TeXmacs
insert special markers for every input line
into the typeset output. The markers are 460 Omega and Aleph
interpreted by the DVI previewer which Omega (Ω) was developed as an exten-
can be made to let its display track the sion of TeX, to use with multilingual
page corresponding to the editor input po- texts, expressed in a variety of input en-
sition, or to let the editor jump to a source codings. Omega uses 16-bit, Unicode-
line corresponding to a click in the preview encoded, characters. It provides many in-
window. novative concepts, notably including the
An emacs package that combines this “translation process” that takes a charac-
sort of editor movement tracking with auto- ter stream and transforms it according to
matic fast recompilations (through the use various processes that may be internally
of dumped formats) is WhizzyTeX which specified, or be a separate program.
is best used with a previewer by the same While Omega showed a lot of promise
author. at its mid-1990s announcement, progress
Another emacs package called preview- was slow, and development was essentially
latex tries to solve the problem of visual dead by the time that one of the original
250
developers withdrew (taking with him a formed token lists, before they are
bunch of research students). processed in the “stomach” for type-
Before that distressing event, a sep- setting. In this way, a declaration
arate thread of development had started, “Ligatures=TeX” is provided, which
to produce a program called Aleph (ℵ), attaches a map directive to the font
which merged the facilities of e-TeX into that transforms the character combi-
a stable Omega codebase and added other nations (familiar to TeX users) into a
extensions. Aleph also proved an attractive single character; for instance --- is
platform for many people; but its develop- transformed into “—”.
ment, too, has dried up. “Post-processing” features (B)
A presentation at EuroTeX 2006 Characters can be assigned to an “in-
claimed that development of Omega was terchar token class” and it is possible
picking up again, in parallel with research to specify tokens to be added when
into what the (new) developers consider a there is a transition from one class to
rational scheme for supporting TeX-style another. The packages polyglossia,
typesetting. The new system was to be xeCJK and ucharclasses exploit this
known as Omega-2 (Ω2 ), and was to be feature.
designed in a modular fashion so that sup-
port of new facilities (such as use of ad- Otherwise, the process of typesetting is
vanced OpenType fonts) could be added essentially the same as TeX’s. (However
in a relatively straightforward fashion. A some changes have also been made in the
quick web search leads to a recommen- hyphenation stage that may give slightly
dation that potential users consider Lua- different results if the same document is
TeX instead; fortunately, lessons learned compiled with PDFTeX or XeTeX.)
in Aleph project have been carried forward polyglossia.sty : macros/latex/
in the development of LuaTeX. contrib/polyglossia

461 XeTeX xeCJK.sty :

macros/xetex/latex/xecjk
XeTeX, by Jonathan Kew, is a successor to
the shareware TeX/GX program for Mac- ucharclasses.sty : macros/xetex/
intoshes. It was developed as a WEB latex/ucharclasses
‘change file’ applied to the original source 462 PDFTeX and LuaTeX
of TeX; the main changes include:
Elsewhere in these FAQs, we learn that de-
The input stage XeTeX by default reads velopment of PDFTeX is “in essence” com-
Unicode (UTF-8, for instance), al- plete — no new facilities are being devel-
though it’s also capable of interpret- oped at the time of writing. The PDFTeX
ing differently encoded files (for back- team has announced that they have frozen
wards compatibility). Multibyte char- PDFTeX’s specification in its current state
acters are reduced to a single internal (version 1.40.11), and that nothing but bug
character upon reading, so they are corrections will be provided up to the time
considered as a unique entity when of the final release, PDFTeX 1.50.0. (The
tokenization is performed. (So, for ex- interpretation of the statement seems to al-
ample, you can have command names low sensible changes that are beyond any
in cyrillic, if you must, but such a prac- reasonable definition of bug. . . )
tice is not recommended.) As PDFTeX development ran down,
The font management a substantial revi- development of a new system, LuaTeX was
sion has added support for OpenType started. Lua is a interpreter designed to be
and TrueType fonts, delegating some incorporated into other applications. Lu-
parts to third-party libraries. aTeX consists of a TeX-like engine with
The maths font set up XeTeX intro- a lua interpreter ‘embedded’ in it; the lua
duces new primitives for extending interpreter has access to many of the data
the \mathcode and \mathchardef structures used for typesetting, so that the
commands in TeX, allowing the user programmer may also interpolate chunks
to specify characters in the whole Uni- of lua code into their (La)TeX macros, or
code set and in 256 ‘math families’ as ‘call-backs’ for use when the TeX-like
(TeX only has 16, which limits some engine does certain operations.
maths coding techniques). This arrangement offers the prospect
“Post-processing” features (A) XeTeX of a “semi-soft” typesetting engine: it will
links to the teckit library so it can have its basic behaviour, but the user gets
apply a .map file that allows trans- to redefine functionality if an idea occurs —
formation of characters in already there will be no need to persuade the world
251
first, and then find a willing developer to rience of the many existing TeX develop-
work on the sources of of the distribution. ment and extension projects, to develop a
The LuaTeX project is (with mone- new TeX-like system. The system is to be
tary support from various sources) pursu- developed in Java (like the ill-fated NTS
ing avenues that many of the other current project).
projects have in their sights, notably Uni- While ExTeX will implement all of
code character representations and support TeX’s primitives, some may be marked as
for OpenType fonts. The intention is to in- obsolete, and “modern” alternatives pro-
tegrate the extensions pioneered by Aleph. vided (an obvious example is the primi-
Users may also care to view the LuaTeX tive \input command, whose syntax in-
documentation page or the LuaTeX WIKI evitably makes life difficult for users of
TeX Live (2013) holds version 0.76.0 modern operating system file paths). De-
of LuaTeX. This version demonstrates the sirable extensions from e-TeX, PDFTeX
“final functionality”, though the project re- and Ω have been identified.
mains a β -release. Functional stability was Usability will be another focus of the
first declared for version 0.50.0, released work: debugging support and log filtering
near the end of December 2009. mechanisms will please those who have
ConTeXt ‘Mark 4’ can already make long struggled with TeX macros.
use of LuaTeX; much of its code al- ExTeX will accept Unicode input, from
ready appears in two forms — a TeX- the start. In the longer term, drawing prim-
based version (.mkii) and a ‘.mkiv’ ver- itives are to be considered.
sion (new functionality typically only ap-
pears in ‘.mkiv’ form), which uses Lu- 465 Replacing the BibTeX–LaTeX
aTeX extensions (including lua script- mechanism
ing). LaTeX packages that support its use Producing a successor to BibTeX has long
are appearing (some of them providing been a favoured activity among a certain
re-implementations of existing ConTeXt class of TeX-users; the author has seen re-
code). ports of progress (on several projects), over
LaTeX running over LuaTeX (com- the years, but few that claim to be ready
monly known as LuaLaTeX) is not an “of- for “real-world” use.
ficial” entity (yet), but useful packages are Few would deny that BibTeX is ripe
appearing (i.e., the CTAN path macros/ for renewal: as originally conceived, it
luatex/latex holds several items).
was a program for creating bibliographies
LuaTeX snapshot: systems/luatex for technical documents, in English. Peo-
PDFTeX distribution: systems/pdftex ple have contributed mechanisms for a de-
gree of multilingual use (whose techniques
463 The ANT typesetting system are arcane, and quite likely inextensible),
Achim Blumensath’s ANT project aims while an extension (bibtex8) allows use
not to replicate TeX with a different imple- with 8-bit character codes, thus providing
mentation technique, but rather to provide some multilingual capabilities. In addition,
a replacement for TeX which uses TeX-like specialist BibTeX style files are available
typesetting algorithms in a very different for use in non-technical papers.
programming environment. ANT remains BibTeX uses a style language whose
under development, but it is now approach- mechanisms are unfamiliar to most current
ing the status of a usable typesetting sys- programmers: it’s difficult to learn, but
tem. since there are few opportunities to write
ANT’s markup language is immedi- the language, it’s also difficult to become
ately recognisable to the (La)TeX user, fluent (in the way that so many people flu-
but the scheme of implementing design ently write the equally arcane TeX macro
in ANT’s own implementation language language).
(presently OCaml) comes as a pleasant Oren Patashnik (the author of BibTeX)
surprise to the jaded FAQ writer. This ar- summarises the issues as he sees them, in
chitecture holds the promise of a system a TUG conference paper from 2003 that
that avoids a set of serious problems with seems to suggest that we might expect a
TeX’s user interface: those that derive from BibTeX 1.0 . . . which hasn’t (yet) ap-
the design language being the same as the peared.
markup language. In the absence of BibTeX 1.0, what
ANT : systems/ant do we need from the bibliography system
of the future? — simple: a superset of
464 The ExTeX project what BibTeX does (or can be made to do),
The ExTeX project is building on the expe- preferably implementing a simpler style
252
language, and with coherent multilingual style that performs the transformation, so
capabilities. that a LaTeX source containing a \nocite
There are two parts to a bibliography {*} command enables BibTeX to produce
system; processing the database of cita- a usable amsrefs bibliography database.)
tions, and typesetting the results. The ex- Amsrefs is maintained by the AMS as
isting BibTeX system provides a means part of its author support programme,
of processing the database, and there are amsrefs.sty :
macros built into LaTeX, as well as many macros/latex/contrib/amsrefs
LaTeX packages, that process the results.
biber : biblio/biber
Of the direct BibTeX replacements,
only two have been submitted to CTAN: biblatex.sty :
CrossTeX and biber. macros/latex/contrib/biblatex
CrossTeX’s language feels familiar to bibtex8 : biblio/bibtex/8-bit
the existing user of BibTeX, but it’s re- biblatex contributions: macros/latex/
designed in an object-oriented style, and contrib/biblatex-contrib
looks (to a non-user) as if it may well be
adequately flexible. It is said to operate as CrossTeX: biblio/crosstex
a BibTeX replacement.
CrossTeX’s team respond to queries, W You’re still stuck?
and seem well aware of the need for mul-
tilingual support, though it isn’t currently 466 You don’t understand the answer
offered.
While the FAQ maintainers don’t offer a
Biber is intimately associated with the
‘help’ service, they’re very keen that you
LaTeX package biblatex; it is logically a
understand the answers they’ve already
BibTeX replacement, but is also capable
written. They’re (almost) written “in a vac-
of using bibliography databases in its own
uum”, to provide something to cover a set
biblatexml (XML-based) format. Biblatex
of questions that have arisen; it’s always
can also use BibTeX, but biber opens up a
possible that they’re written in a way that
far wider range of possibilities, including
a novice won’t understand them.
full Unicode support.
Which is where you can help the com-
Biblatex is a processor for the output munity. Mail the maintainers to report the
of an application such as biber or BibTeX; answer that you find unclear, and (if you
the style of citations and of the bibliog- can) suggest what we need to clarify. Time
raphy itself (in your document) is deter- permitting (the team is small and all its
mined by the way your biblatex style has members are busy), we’ll try and clarify
been set up, not on some BibTeX-LaTeX the answer. This way, with a bit of luck,
package combination. Biblatex’s structure we can together improve the value of this
thus eliminates the collections of BibTeX resource to the whole community.
styles, at a stroke; it comes with a basic Note that the FAQ development email
set of styles, and details are determined address is not for answering questions:
by options, set at package loading time. it’s for you to suggest which questions
The author, Philipp Lehman, evaluated the we should work on, or new questions we
whole field of bibliography software be- should answer in future editions.
fore starting, and as a result the package Those who simply ask questions at that
provides answers to many of the questions address will be referred to texhax@tug.
asked in the bibliography sections of these org or to comp.text.tex.
FAQs.
Biblatex was released as experimental 467 Submitting new material for the
software, but it’s clear that many users are FAQ
already using it happily; Lehman is respon- The FAQ will never be complete, and we
sive to problem reports, at the moment, but always expect that there will be people out
a de facto set of expert users is already there who know better than we do about
establishing itself. A set of contributed something or other. We always need to be
styles has appeared, which cover some of put right about whatever we’ve got wrong,
the trickier bibliography styles. The road and suggestions for improvements, partic-
map of the project shows that we are now ularly covering areas we’ve missed, are
working on the final beta releases before always needed: mail anything you have to
the “stable” biblatex 1.0. the maintainers
Finally, Amsrefs uses a transformed If you have actual material to submit,
.bib file, which is expressed as LaTeX your contribution is more than ever wel-
macros. (The package provides a BibTeX come. Submission in plain text is entirely
253
acceptable, but if you’re really willing, you package may well answer on-line, but if
may feel free to mark up your submission no-one offers any help, you may stand a
in the form needed for the FAQ itself. The chance if you mail the author (presuming
markup is a strongly-constrained version that you can find an address. . . ).
of LaTeX — the constraints come from If you’ve found a bug in LaTeX 2.09,
the need to translate the marked-up text to or some other such unsupported software,
HTML on the fly (and hence pretty effi- your only real hope is help on-line.
ciently). There is a file markup-syntax Failing all else, you may need to pay
in the FAQ distribution that describes the for help — TUG maintains a register of
structure of the markup, but there’s no TeX consultants. (This of course requires
real substitute for reading at least some that you have the resources — and a press-
of the source (faqbody.tex) of the FAQ ing enough need — to hire someone.)
itself. If you understand Perl, you may
469 Reporting a LaTeX bug
also care to look at the translation code
in texfaq2file and sanitize.pl in the The LaTeX team supports LaTeX, and will
distribution: this isn’t the code actually deal with bona fide bug reports. Note that
used on the Web site, but it’s a close rela- the LaTeX team does not deal with con-
tion and is kept up to date for development tributed packages — just the software that
purposes. is part of the LaTeX distribution itself: La-
TeX and the “required” packages. Further-
FAQ distribution: help/uk-tex-faq more, you need to be slightly careful to
468 What to do if you find a bug produce a bug report that is usable by the
team. The steps are:
For a start, make entirely sure you have 1. Are you still using current LaTeX?
found a bug. Double-check with books Maintenance is only available for suffi-
about TeX, LaTeX, or whatever you’re us- ciently up-to-date versions of LaTeX — if
ing; compare what you’re seeing against your LaTeX is more than two versions out
the other answers above; ask every possi- of date, the bug reporting mechanisms may
ble person you know who has any TeX- reject your report.
related expertise. The reasons for all this 2. Has your bug already been reported?
caution are various. Browse the LaTeX bugs database, to find
If you’ve found a bug in TeX itself, any earlier instance of your bug. In many
you’re a rare animal indeed. Don Knuth cases, the database will list a work-around.
is so sure of the quality of his code that 3. Prepare a “minimum” file that exhibits
he offers real money prizes to finders of the problem. Ideally, such a file should con-
bugs; the cheques he writes are such rare tain no contributed packages — the LaTeX
items that they are seldom cashed. If you team as a whole takes no responsibility for
think you have found a genuine fault in such packages (if they’re supported at all,
TeX itself (or Metafont, or the CM fonts, they’re supported by their authors). The
or the TeXbook), don’t immediately write “minimum” file should be self-sufficient: if
to Knuth, however. He only looks at bugs a member of the team runs it in a clean
infrequently, and even then only after they directory, on a system with no contributed
are agreed as bugs by a small vetting team. packages, it should replicate your problem.
In the first instance, contact Barbara Bee- 4. Run your file through LaTeX: the bug
ton at the AMS ([email protected]), or contact system needs the .log file that this process
TUG. creates.
If you’ve found a bug in LaTeX2e, re- 5. Connect to the latex bugs processing
port it using mechanisms supplied by the web page and enter details of your bug —
LaTeX team. (Please be careful to ensure category, summary and full description,
you’ve got a LaTeX bug, or a bug in one and the two important files (source and
of the “required” packages distributed by log file).
the LaTeX team.) The personal details are not optional:
If you’ve found a bug in a contributed the members of the LaTeX team may need
LaTeX package, the best starting place is to contact to discuss the bug with you, or to
usually to ask in the “usual places for help advise you of a work-around. Your details
on-line, or just possibly one of the spe- will not appear in the public view of the
cialised mailing lists. The author of the database.

254