This repository was archived by the owner on Sep 27, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathfaq-jot-err.tex
2474 lines (2248 loc) · 88.8 KB
/
faq-jot-err.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
% $Id: faq-jot-err.tex,v 1.25 2014/01/28 18:17:36 rf10 Exp rf10 $
\section{The joy of \TeX{} errors}
\Question[Q-erroradvice]{How to approach errors}
Since \TeX{} is a macroprocessor, its error messages are often
difficult to understand; this is a (seemingly invariant) property of
macroprocessors. Knuth makes light of the problem in the \TeX{}book,
suggesting that you acquire the sleuthing skills of a latter-day
Sherlock Holmes; while this approach has a certain romantic charm to
it, it's not good for the `production' user of \AllTeX{}. This
answer (derived, in part, from an article by Sebastian Rahtz in
\TUGboat{} 16(4)) offers some general guidance in dealing with \TeX{}
error reports, and other answers in this section deal with common (but
perplexing) errors that you may encounter. There's a long list of
``hints'' in Sebastian's article, including the following:
\begin{itemize}
\item Look at \TeX{} errors; those messages may seem cryptic at first,
but they often contain a straightforward clue to the problem. See
\Qref[question]{the structure of errors}{Q-errstruct} for further
details.
\item Read the \extension{log} file; it contains hints to things you may
not understand, often things that have not even presented as error
messages.
\item Be aware of the amount of context that \TeX{} gives you. The
error messages gives you some bits of \TeX{} code (or of the
document itself), that show where the error ``actually happened'';
it's possible to control how much of this `context' \TeX{} actually
gives you. \LaTeX{} (nowadays) instructs \TeX{} only to give you
one line of context, but you may tell it otherwise by saying
\begin{quote}
\begin{verbatim}
\setcounter{errorcontextlines}{999}
\end{verbatim}
\end{quote}
in the preamble of your document. (If you're not a confident macro
programmer, don't be ashamed of cutting that 999 down a bit; some
errors will go on and \emph{on}, and spotting the differences
between those lines can be a significant challenge.)
\item As a last resort, tracing can be a useful tool; reading a full
\AllTeX{} trace takes a strong constitution, but once you know how,
the trace can lead you quickly to the source of a problem. You need
to have read the \TeX{}book (see
% beware line break
\Qref[question]{books about \TeX{}}{Q-tex-books}) in some detail, fully
to understand the trace.
The command \csx{tracingall} sets up maximum tracing; it also sets
the output to come to the interactive terminal, which is somewhat of
a mixed blessing (since the output tends to be so vast~--- all but
the simplest traces are best examined in a text editor after the event).
The \LaTeX{} \Package{trace} package (first distributed with the
2001 release of \LaTeX{}) provides more manageable tracing. Its
\csx{traceon} command gives you what \csx{tracingall} offers, but
suppresses tracing around some of the truly verbose parts of
\LaTeX{} itself. The package also provides a \csx{traceoff}
command (there's no ``off'' command for \csx{tracingall}), and a
package option (|logonly|) allows you to suppress output to the
terminal.
\end{itemize}
The best advice to those faced with \TeX{} errors is not to panic:
most of the common errors are plain to the eye when you go back to the
source line that \TeX{} tells you of. If that approach doesn't work,
the remaining answers in this section deal with some of the odder
error messages you may encounter. You should not ordinarily need to
appeal to the \Qref*[question]{wider public}{Q-gethelp}
for assistance, but if you do, be sure to
report full backtraces (see |errorcontextlines| above) and so on.
\begin{ctanrefs}
\item[trace.sty]Distributed as part of \CTANref{2etools}[trace]
\end{ctanrefs}
\LastEdit{2011-06-01}
\Question[Q-errstruct]{The structure of \TeX{} error messages}
\TeX{}'s error messages are reminiscent of the time when \TeX{} itself
was conceived (the 1970s): they're not terribly user-friendly, though
they do contain all the information that \TeX{} can offer, usually in
a pretty concise way.
\TeX{}'s error reports all have the same structure:
\begin{itemize}
\item An error message
\item Some `context'
\item An error prompt
\end{itemize}
The error message will relate to the \emph{\TeX{}} condition that is
causing a problem. Sadly, in the case of complex macro packages such
as \LaTeX{}, the underlying \TeX{} problem may be superficially
difficult to relate to the actual problem in the ``higher-level''
macros. Many \LaTeX{}-detected problems manifest themselves as
`generic' errors, with error text provided by \LaTeX{} itself (or by a
\LaTeX{} class or package).
The context of the error is a stylised representation of what \TeX{}
was doing at the point that it detected the error. As noted in
\Qref[question]{approaching errors}{Q-erroradvice}, a macro package
can tell \TeX{} how much context to display, and the user may need to
undo what the package has done. Each line of context is split at the
point of the error; if the error \emph{actually} occurred in a macro
called from the present line, the break is at the point of the call.
(If the called object is defined with arguments, the ``point of call''
is after all the arguments have been scanned.) For example:
\begin{verbatim}
\blah and so on
\end{verbatim}
produces the error report
\begin{verbatim}
! Undefined control sequence.
l.4 \blah
and so on
\end{verbatim}
while:
\begin{verbatim}
\newcommand{\blah}[1]{\bleah #1}
\blah{to you}, folks
\end{verbatim}
produces the error report
\begin{verbatim}
! Undefined control sequence.
\blah #1->\bleah
#1
l.5 \blah{to you}
, folks
\end{verbatim}
If the argument itself is in error, we will see things such as
\begin{verbatim}
\newcommand{\blah}[1]{#1 to you}
\blah{\bleah}, folks
\end{verbatim}
producing
\begin{verbatim}
! Undefined control sequence.
<argument> \bleah
l.5 \blah{\bleah}
, folks
\end{verbatim}
The prompt accepts single-character commands: the list of what's
available may be had by typing |?|\@. One immediately valuable
command is |h|, which gives you an expansion of \TeX{}s original
pr\'ecis message, sometimes accompanied by a hint on what to do to
work round the problem in the short term. If you simply type `return'
(or whatever else your system uses to signal the end of a line) at the
prompt, \TeX{} will attempt to carry on (often with rather little
success).
\Question[Q-extrabrace]{An extra `\texttt{\cbracesymbol{}}'??}
\keywords{caption heading}
You've looked at your \LaTeX{} source and there's no sign of a misplaced
\texttt{\cbracesymbol{}} on the line in question.
Well, no: this is \TeX{}'s cryptic way of hinting that you've put a
\begin{wideversion} % hyper
\Qref{fragile command}{Q-protect} in a moving argument.
\end{wideversion}
\begin{narrowversion}
fragile command in a moving argument (\Qref{}{Q-protect}).
\end{narrowversion}
For example, \csx{footnote} is fragile, and if we put that in the
moving argument of a \csx{section} command, as
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\section{Mumble\footnote{%
I couldn't think of anything better}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\section{Mumble\footnote{I couldn't think of anything better}}
\end{verbatim}
\end{wideversion}
\end{quote}
we get told
\begin{quote}
\begin{verbatim}
! Argument of \@sect has an extra }.
\end{verbatim}
\end{quote}
The same happens with captions (the following is a simplification of a
\Newsgroup{comp.text.tex} post):
\begin{quote}
\begin{verbatim}
\caption{Energy: \[e=mc^2\]}
\end{verbatim}
\end{quote}
giving us the error message
\begin{quote}
\begin{verbatim}
! Argument of \@caption has an extra }.
\end{verbatim}
\end{quote}
The similar (but more sensible):
\begin{quote}
\begin{verbatim}
\caption{Energy: \(e=mc^2\)}
\end{verbatim}
\end{quote}
is more tiresome, still: there's no error when you first run the
job~\dots{} but there is on the second pass, when the list of figures
(or tables) is generated, giving:
\begin{quote}
\begin{verbatim}
! LaTeX Error: Bad math environment delimiter.
\end{verbatim}
\end{quote}
in the \csx{listoffigures} processing.
The solution is usually to use a robust command in place of the one
you are using, or to force your command to be robust by prefixing it
with \csx{protect}, which in the \csx{section} case would show as
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\section{Mumble\protect\footnote{%
I couldn't think of anything better}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\section{Mumble\protect\footnote{I couldn't think of anything better}}
\end{verbatim}
\end{wideversion}
\end{quote}
However, in both the \csx{section} case and the \csx{caption} case,
you can separate the moving argument, as in
\cmdinvoke*{section}[moving]{static}; this gives us another standard
route~--- simply to omit (or otherwise sanitise) the fragile command
in the moving argument. So, one might rewrite the \csx{caption}
example as:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\caption[Energy: (Einstein's equation)]%
{Energy: \(E=mc^2\)}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\caption[Energy: (Einstein's equation)]{Energy: \(E=mc^2\)}
\end{verbatim}
\end{wideversion}
\end{quote}
In practice, inserting mathematics in a moving argument has already
been addressed in \LaTeXe{} by the robust command \csx{ensuremath}:
\begin{quote}
\begin{verbatim}
\caption{Energy: \ensuremath{E=mc^2}}
\end{verbatim}
\end{quote}
So: always look for alternatives to the \csx{protect} route.
Footnotes can be even more complex; % ! line break
``\Qref*[question]{footnotes in \LaTeX{} section headings}{Q-ftnsect}''
deals specifically with that issue.
\LastEdit{2012-02-09}
\Question[Q-semanticnest]{Capacity exceeded [semantic nest\,\dots{}]}
\begin{narrowversion}
\begin{verbatim}
! TeX capacity exceeded, sorry [semantic nest
size=100].
...
If you really absolutely need more capacity,
you can ask a wizard to enlarge me.
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
! TeX capacity exceeded, sorry [semantic nest size=100].
...
If you really absolutely need more capacity,
you can ask a wizard to enlarge me.
\end{verbatim}
\end{wideversion}
Even though \TeX{} suggests (as always) that enlargement by a wizard
may help, this message usually results from a broken macro or bad
parameters to an otherwise working macro.
The ``semantic nest'' \TeX{} talks about is the nesting
of boxes within boxes. A stupid macro can provoke the error pretty
easily:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\def\silly{\hbox{here's \silly
being executed}}
\silly
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\def\silly{\hbox{here's \silly being executed}}
\silly
\end{verbatim}
\end{wideversion}
\end{quote}
The extended traceback
% beware of filling this line...
(see \Qref{\emph{general advice} on errors}{Q-erroradvice})
\emph{does} help, though it does rather run on. In the case above,
the traceback consists of
\begin{verbatim}
\silly ->\hbox {
here's \silly being executed}
\end{verbatim}
followed by 100 instances of
\begin{verbatim}
\silly ->\hbox {here's \silly
being executed}
\end{verbatim}
The repeated lines are broken at exactly the offending macro; of
course the loop need not be as simple as this~--- if \csx{silly} calls
\csx{dopy} which boxes \csx{silly}, the effect is just the same and
alternate lines in the traceback are broken at alternate positions.
There are in fact two items being consumed when you nest boxes: the
other is the grouping level. Whether you exhaust your % !line wrap
\emph{semantic nest} or your permitted \emph{grouping levels} first is
controlled entirely by the relative size of the two different sets of
buffers in your \AllTeX{} executable.
\Question[Q-noroom]{No room for a new `\emph{thing}'}
The technology available to Knuth at the time \TeX{} was written is
said to have been particularly poor at managing dynamic storage; as a
result much of the storage used within \TeX{} is allocated as fixed
arrays, in the reference implementations. Many of these fixed arrays
are expandable in modern \TeX{} implementations, but size of the
arrays of ``registers'' is written into the specification as being 256
(usually); this number may not be changed if you still wish to call
the result \TeX{}
%% beware line wrap
(see \Qref[question]{testing \TeX{} implementations}{Q-triptrap}).
If you fill up one of these register arrays, you get a \TeX{} error
message saying
\begin{quote}
\begin{verbatim}
! No room for a new \<thing>.
\end{verbatim}
\end{quote}
The \csx{thing}s in question may be \csx{count} (the object underlying
\LaTeX{}'s \csx{newcounter} command), \csx{skip} (the object underlying
\LaTeX{}'s \csx{newlength} command), \csx{box} (the object underlying
\LaTeX{}'s \csx{newsavebox} command), or \csx{dimen}, \csx{muskip},
\csx{toks}, \csx{read}, \csx{write} or \csx{language} (all types of object
whose use is ``hidden'' in \LaTeX{}; the limit on the number of
\csx{read} or \csx{write} objects is just 16).
There is nothing that can directly be done about this error, as you can't
extend the number of available registers without extending \TeX{}
itself.
\begin{htmlversion}
Of course, \Qref{\eTeX{}}{Q-etex}, \Qref{Omega}{Q-omegaleph} and
\Qref{\LuaTeX{}}{Q-luatex}
\end{htmlversion}
\htmlignore
% beware line wrap here
Of course \Qref[question]{\eTeX{}}{Q-etex},
\Qref[question]{\ensuremath{\Omega}}{Q-omegaleph} and
\Qref[question]{\LuaTeX{}}{Q-luatex}
\endhtmlignore
all do this, as does \Qref*{MicroPress Inc's V\TeX{}}{Q-commercial}.
The commonest way to encounter one of these error messages is to have
broken macros of some sort, or incorrect usage of macros (an example
is discussed in \Qref[question]{epsf problems}{Q-epsf}).
However, sometimes one just \emph{needs} more than \TeX{} can offer,
and when this happens, you've just got to work out a different way of
doing things. An example is the % beware line wrap
\Qref*{difficulty of loading \PiCTeX{} with \LaTeX{}}{Q-usepictex}.
The more modern drawing package, \Package{pgf} with its higher-level
interface \Package{TikZ} is also a common source of such problems.
In such cases, it is usually possible to use the
\Qref*{\eTeX{}}{Q-etex} extensions (all modern distributions provide
them). The \LaTeX{} package \Package{etex} modifies the register allocation
mechanism to make use of \eTeX{}'s extended register sets.
\Package{Etex} is a
derivative of the \plaintex{} macro file \Package{etex.src}, which is
used in building the \eTeX{} Plain format; both files are part of the
\eTeX{} distribution and are available in current distributions.
It is possible that, even with \Package{etex} loaded, you still find
yourself running out of things. Problems can be caused by packages
that use large numbers of ``inserts'' (inserts are combinations of
counter, box, dimension and skip registers, used for storing floats
and footnotes). \Package{Morefloats} does this, of course (naturally enough,
allocating new floats), and footnote packages such as
\Package{manyfoot} and \Package{bigfoot} (which uses \Package{manyfoot})
can also give problems. The \Package{etex} extensions allow you to deal with
these things: the command \cmdinvoke*{reserveinserts}{n} ensures there
is room for \meta{n} more inserts. Hint: by default
\Package{morefloats} adds 18 inserts (though it can be instructed to
use more), and \Package{manyfoot} seems to be happy with 10 reserved,
but there are `hard' limits that we cannot program around~--- the
discussion of \Qref*{running out of floats}{Q-tmupfl} has more about this.
It is essential that you load \Package{etex} before any other
packages, and reserve any extra inserts immediately:
\begin{quote}
\begin{verbatim}
\documentclass[...]{...}
\usepackage{etex}
\reserveinserts{28}
\end{verbatim}
\end{quote}
The \eTeX{} extensions don't help with \csx{read} or \csx{write}
objects (and neither will the \Package{etex} package), but the
\Package{morewrites} package can provide the \emph{illusion} of large
numbers of \csx{write} objects.
\begin{ctanrefs}
\item[morewrites.sty]\CTANref{morewrites}
\end{ctanrefs}
\Question[Q-epsf]{\texttt{epsf} gives up after a bit}
Some copies of the documentation of \File{epsf.tex} seemed once to
suggest that the command
\begin{verbatim}
\input epsf
\end{verbatim}
is needed for every figure included. If you follow this suggestion
too literally, you get an error
\begin{verbatim}
! No room for a new \read .
\end{verbatim}
after a while; this is because each time \File{epsf.tex} is loaded, it
allocates itself a \emph{new} file-reading handle to check the figure
for its bounding box, and there just aren't enough of these things
(see \Qref[question]{no room for a new thing}{Q-noroom}).
The solution is simple~--- this is in fact an example of misuse of
macros; one only need read \File{epsf.tex} once, so change
\begin{verbatim}
...
\input epsf
\epsffile{...}
...
\input epsf
\epsffile{...}
\end{verbatim}
(and so on) with a single
\begin{verbatim}
\input epsf
\end{verbatim}
somewhere near the start of your document, and then decorate your
\csx{epsffile} statements with no more than adjustments of
\csx{epsfxsize} and so on.
\Question[Q-badhyph]{Improper \csx{hyphenation} will be flushed}
For example
\begin{verbatim}
! Improper \hyphenation will be flushed.
\'#1->{
\accent 19 #1}
<*> \hyphenation{Ji-m\'e
-nez}
\end{verbatim}
(in \plaintex{}) or
\begin{verbatim}
! Improper \hyphenation will be flushed.
\leavevmode ->\unhbox
\voidb@x
<*> \hyphenation{Ji-m\'e
-nez}
\end{verbatim}
in \LaTeX{}.
As mentioned in
\begin{flatversion}
\Qref[question]{hyphenation failures}{Q-nohyph},
\end{flatversion}
\begin{hyperversion}
``\Qref[question]{hyphenation failures}{Q-nohyph}'',
\end{hyperversion}
``words'' containing \csx{accent} commands may not be hyphenated. As
a result, any such word is deemed improper in a \csx{hyphenation}
command.
Hyphenation happens as paragraphs are laid out; by this time, \TeX{}
knows what font is used for each glyph; thus it knows the encoding
being used. So the solution to the problem is to use a font that
contains the accented character; doing this this ``hides'' the accent
from the hyphenation mechanisms.
For \LaTeX{} users, this is quite an easy task; they select an 8-bit
font with the package, as in \cmdinvoke{usepackage}[T1]{fontenc}, and
accented-letter commands such as the \csx{'}\texttt{e} in
\cmdinvoke{hyphenation}{Ji-m\csx{'}e-nez} automatically become the
single accented character by the time the hyphenation gets to look at
it.
\Question[Q-optionclash]{Option clash for package}
So you've innocently added:
\begin{quote}
\cmdinvoke{usepackage}[draft]{foo}
\end{quote}
to your document, and \LaTeX{} responds with
\begin{quote}
\begin{wideversion}
\begin{verbatim}
! LaTeX Error: Option clash for package foo.
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
! LaTeX Error: Option clash for package foo.
\end{verbatim}
\end{narrowversion}
\end{quote}
The error is a complaint about loading a package % ! line break
\emph{with options}, more than once. \LaTeX{} complains because it
has no means of examining the options, rather than because it
\emph{knows} there is a problem. (You may load a package any number
of times in a document's preamble, with no options, and \LaTeX{} will
ignore every loading request after the first; but you may only supply
options when you first load the package.)
So perhaps you weren't entirely innocent~--- the error would have
occurred on the second line of:
\begin{quote}
\cmdinvoke{usepackage}[dvips]{graphics}\\
\cmdinvoke{usepackage}[draft]{graphics}
\end{quote}
which could quite reasonably (and indeed correctly) have been typed:
\begin{quote}
\cmdinvoke{usepackage}[dvips,draft]{graphics}
\end{quote}
But if you've not made that mistake (even with several lines
separating the \csx{usepackage} commands, it's pretty easy to spot),
the problem could arise from something else loading the package for
you. How do you find the culprit? The "\texttt{h}" response to the
error message tells you which options were loaded each time.
Otherwise, it's down to the log analysis games discussed in % ! line break
``\Qref*{How to approach errors}{Q-erroradvice}''; the trick to remember
is that that the process of loading each file is parenthesised in the
log; so if package \Package{foo} loads \Package{graphics}, the log
will contain something like:
\begin{quote}
\begin{verbatim}
(<path>/foo.sty ...
...
(<path>/graphics.sty ...
...)
...
)
\end{verbatim}
\end{quote}
(the parentheses for \Package{graphics} are completely enclosed in
those for \Package{foo}; the same is of course true if your class
\Class{bar} is the culprit, except that the line will start with the
path to \texttt{bar.cls}).
If we're dealing with a package that loads the package you are
interested in, you need to ask \LaTeX{} to slip in options when
\Package{foo} loads it. Instead of:
\begin{quote}
\cmdinvoke{usepackage}{foo}\\
\cmdinvoke{usepackage}[draft]{graphics}
\end{quote}
you would write:
\begin{quote}
\cmdinvoke{PassOptionsToPackage}{draft}{graphics}\\
\cmdinvoke{usepackage}{foo}
\end{quote}
The command \csx{PassOptionsToPackage} tells \LaTeX{} to behave as if
its options were passed, when it finally loads a package. As you would
expect from its name, \csx{PassOptionsToPackage} can deal with a list
of options, just as you would have in the the options brackets of
\csx{usepackage}.
The problem is more tricky if your document class loads a package you
want options for. In this case, instead of:
\begin{quote}
\cmdinvoke{documentclass}[...]{bar}\\
\cmdinvoke{usepackage}[draft]{graphics}
\end{quote}
you would write:
\begin{quote}
\cmdinvoke{PassOptionsToPackage}{draft}{graphics}\\
\cmdinvoke{documentclass}[...]{bar}
\end{quote}
with \csx{PassOptionsToPackage} \emph{before} the \csx{documentclass}
command.
However, if the \Package{foo} package or the \Class{bar} class loads
\Package{graphics} with an option of its own that clashes with
what you need in some way, you're stymied. For example:
\begin{quote}
\cmdinvoke{PassOptionsToPackage}{draft}{graphics}
\end{quote}
where the package or class does:
\begin{quote}
\cmdinvoke{usepackage}[final]{graphics}
\end{quote}
sets \pkgoption{final} \emph{after} it's dealt with option you passed to
it, so your \pkgoption{draft} will get forgotten. In extreme cases,
the package might generate an error here (\Package{graphics} doesn't
go in for that kind of thing, and there's no indication that
\pkgoption{draft} has been forgotten).
In such a case, you have to modify the package or class itself
(subject to the terms of its licence). It may prove useful to contact
the author: she may have a useful alternative to suggest.
\Question[Q-optclash]{Option clash for package}
The error message
\begin{quote}
\begin{verbatim}
! LaTeX Error: Option clash for package footmisc
\end{verbatim}
\end{quote}
means what it says~--- your document contains a (potentially) clashing
pair of options; sadly, it is not always obvious how the error has
arisen.
If you simply write:
\begin{quote}
\begin{verbatim}
\usepackage[a]{foo}
...
\usepackage{foo}
\end{verbatim}
\end{quote}
\LaTeX{} is happy, as it is with:
\begin{quote}
\begin{verbatim}
\usepackage[a]{foo}
...
\usepackage[a]{foo}
\end{verbatim}
\end{quote}
since \LaTeX{} can see there's no conflict (in fact, the second load
does nothing).
Similarly,
\begin{quote}
\begin{verbatim}
\usepackage[a,b]{foo}
...
\usepackage[a]{foo}
\end{verbatim}
\end{quote}
produces no error and does nothing for the second load.
However
\begin{quote}
\begin{verbatim}
\usepackage[a]{foo}
...
\usepackage[b]{foo}
\end{verbatim}
\end{quote}
produces the error; even if option `\pkgoption{b}' is an alias for
option `\pkgoption{a}'~--- \LaTeX{} doesn't ``look inside'' the package
to check anything like that.
The general rule is: the first load of a package defines a set of
options; if a further \csx{usepackage} or \csx{RequirePackage} also
calls for the package, the options on that call may not extend the set
on the first load.
Fortunately, the error (in that sort of case) is easily curable
once you've examined the preamble of your document.
Now, suppose package \Package{foo} loads \Package{bar} with option
\pkgoption{b}, and your document says:
\begin{quote}
\begin{verbatim}
\usepackage{foo}
...
\usepackage[a]{bar}
\end{verbatim}
\end{quote}
or
\begin{quote}
\begin{verbatim}
\usepackage[a]{bar}
...
\usepackage{foo}
\end{verbatim}
\end{quote}
the error will be detected, even though you have only explicitly
loaded \Package{bar} once. Debugging such errors is tricky: it may
involve reading the logs (to spot which packages were called), or the
documentation of package \Package{foo}.
\Question[Q-tmupfl]{``Too many unprocessed floats''}
If \LaTeX{} responds to a \cmdinvoke{begin}{figure} or
\cmdinvoke{begin}{table} command with the error message
\begin{quote}
\begin{wideversion}
\begin{verbatim}
! LaTeX Error: Too many unprocessed floats.
See the LaTeX manual or LaTeX Companion for explanation.
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
! LaTeX Error: Too many unprocessed floats.
See the LaTeX manual or LaTeX Companion
... for explanation.
\end{verbatim}
\end{narrowversion}
\end{quote}
your figures (or tables) are not being placed properly. \LaTeX{}
has a limited amount of storage for `floats' (figures, tables, or
floats you've defined yourself with the \Package{float} package); if
something you have done has prevented \LaTeX{} from typesetting
floats, it will run out of storage space.
This failure usually occurs in extreme cases of % ! line break
\Qref*{floats moving ``wrongly''}{Q-floats};
\LaTeX{} has found it can't place a float, and floats of the same type
have piled up behind it.
How does this happen?~--- \LaTeX{} guarantees that caption numbers are
sequential in the document, but the caption number is allocated when
the figure (or whatever) is created, and can't be changed. Thus, if
floats are placed out of order, their caption numbers would also
appear out of order in the body of the document (and in the list of
figures, or whatever). As a result, enforcement of the guarantee
means that simple failure to place a float means that no subsequent
float can be placed; and hence (eventually) the error.
Techniques for solving the problem are discussed in the % ! line break
\Qref*{floats question}{Q-floats} already referenced.
For \LaTeX{} releases prior to 2015, an
alternative \emph{may} be to use the \Package{morefloats} package.
The package will allocate more ``float skeletons'' than \LaTeX{}
does by default; each such skeleton may then be used to store a
float. Beware that even with \Package{morefloats}, the number you can
allocate is limited; even with the \Package{etex} package.
\LaTeX{} releases from 2015 onwards have an \csx{extrafloats}
command which (assuming an \eTeX{} format is being used) will
allow many more float boxes to be allocated (the upper limit
being several thousand, rather more than can reasonably handled
in tex macro lists.) Also the default number of floats that may be stored
has been increased from 18 to 52.
The error also occurs in a long sequence of float environments, with
no intervening text. Unless the environments will fit ``here'' (and
you've allowed them to go ``here''), there will never be a page break,
and so there will never be an opportunity for \LaTeX{} to reconsider
placement. Of course, the floats can't all fit ``here'' if the
sequence is sufficiently prolonged: once the page fills, \LaTeX{}
won't place any more floats, leading to the error.
Techniques for resolution may involve redefining the floats using the
\Package{float} package's \texttt{[H]} float qualifier, but you are unlikely
to get away without using \csx{clearpage} from time to time.
\begin{ctanrefs}
\item[float.sty]\CTANref{float}
\item[morefloats.sty]\CTANref{morefloats}
\end{ctanrefs}
\Question[Q-atvert]{\csx{spacefactor} complaints}
The errors
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
! You can't use `\spacefactor' in
... vertical mode.
\@->\spacefactor
\@m
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
! You can't use `\spacefactor' in vertical mode.
\@->\spacefactor
\@m
\end{verbatim}
\end{wideversion}
\end{quote}
or
\begin{quote}
\begin{verbatim}
! You can't use `\spacefactor' in math mode.
\@->\spacefactor
\@m
\end{verbatim}
\end{quote}
or simply
\begin{quote}
\begin{verbatim}
! Improper \spacefactor.
...
\end{verbatim}
\end{quote}
bite the \LaTeX{} programmer who uses an internal command without
taking ``precautions''. An internal-style command such as \csx{@foo}
has been defined or used in a private macro, and it is interpreted as
\csx{@}, followed by the `text' \texttt{foo}. (\csx{@} is used, for
real, to set up end-of-sentence space in some circumstances; it uses
\csx{spacefactor} to do that.)
The problem is discussed in detail in
% beware line wrap
``\Qref*[question]{\texttt{@} in macro names}{Q-atsigns}'',
together with solutions.
\Question[Q-endingroup]{\csx{end} occurred inside a group}
The actual error we observe is:
\nothtml{\noindent}%
|(\end occurred inside a group at level <|\texttt{\emph{n}}|>)|
\nothtml{\noindent}%
and it tells us that something we started in the document never got
finished before we ended the document itself. The things involved
(`groups') are what \TeX{} uses for restricting the scope of things:
you see them, for example, in the ``traditional'' font selection
commands: |{\it stuff\/}|~--- if the closing brace is left off such a
construct, the effect of \csx{it} will last to the end of the document,
and you'll get the diagnostic.
\TeX{} itself doesn't tell you where your problem is, but you can
often spot it by looking at the typeset output in a previewer.
Otherwise, you can usually find mismatched braces using an intelligent
editor (at least \ProgName{emacs} and \ProgName{winedt} offer this facility).
However, groups are not \emph{only} created by matching
\texttt{\obracesymbol{}} with \texttt{\cbracesymbol{}}:
other grouping commands are discussed elsewhere in these \acro{FAQ}s,
and are also a potential source of unclosed group.
\cmdinvoke{begin}{\meta{environment}} encloses the environment's body
in a group, and establishes its own diagnostic mechanism. If you end
the document before closing some other environment, you get the
`usual' \LaTeX{} diagnostic
\htmlignore
\begin{dviversion}
\begin{verbatim}
! LaTeX Error: \begin{blah} on input line 6
ended by \end{document}.
\end{verbatim}
\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
! LaTeX Error: \begin{blah} on input line 6 ended by \end{document}.
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
! LaTeX Error: \begin{blah} on input line 6 ended by \end{document}.
\end{verbatim}
\end{htmlversion}
which (though it doesn't tell you which \emph{file} the
\cmdinvoke{begin}{blah} was in) is usually enough to locate the
immediate problem. If you press on past the \LaTeX{} error, you get
one or more repetitions of the ``occurred inside a group'' message
before \LaTeX{} finally exits. The \Package{checkend} package
recognises other unclosed \cmdinvoke{begin}{blob} commands, and
generates an ``ended by'' error message for each one, rather than
producing the ``occurred inside a group'' message, which is sometimes
useful (if you remember to load the package).
In the absence of such information from \LaTeX{}, you need to use
``traditional'' binary search to find the offending group. Separate
the preamble from the body of your file, and process each half on its
own with the preamble; this tells you which half of the file is at
fault. Divide again and repeat. The process needs to be conducted
with care (it's obviously possible to split a correctly-written group
by chopping in the wrong place), but it will usually find the problem
fairly quickly.
\eTeX{} (and \elatex{}~--- \LaTeX{} run on \eTeX{}) gives you
further diagnostics after the traditional infuriating \TeX{} one~--- it
actually keeps the information in a similar way to \LaTeX{}:
\htmlignore
\begin{dviversion}
\begin{verbatim}
(\end occurred inside a group at level 3)
### semi simple group (level 3) entered
at line 6 (\begingroup)
### simple group (level 2) entered at line 5 ({)
### simple group (level 1) entered at line 4 ({)
### bottom level
\end{verbatim}
\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
(\end occurred inside a group at level 3)
### semi simple group (level 3) entered at line 6 (\begingroup)
### simple group (level 2) entered at line 5 ({)
### simple group (level 1) entered at line 4 ({)
### bottom level
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
(\end occurred inside a group at level 3)
### semi simple group (level 3) entered at line 6 (\begingroup)
### simple group (level 2) entered at line 5 ({)
### simple group (level 1) entered at line 4 ({)
### bottom level
\end{verbatim}
\end{htmlversion}
The diagnostic not only tells us where the group started, but also the
\emph{way} it started: \csx{begingroup} or |{| (which is an alias of
\csx{bgroup}, and the two are not distinguishable at the \TeX{}-engine
level).
\begin{ctanrefs}
\item[checkend.sty]Distributed as part of \CTANref{bezos}[checkend]
\end{ctanrefs}
\Question[Q-nonum]{``Missing number, treated as zero''}
In general, this means you've tried to assign something to a count,
dimension or skip register that isn't (in \TeX{}'s view of things) a
number. Usually the problem will become clear using the
\Qref*{ordinary techniques of examining errors}{Q-erroradvice}.
Two \LaTeX{}-specific errors are commonly aired on the newsgroups.
The commonest arises from attempting to use an example from the
\Qref*{\emph{The \LaTeX{} Companion} (first edition)}{Q-latex-books}, and is
exemplified by the following error text:
\begin{verbatim}
! Missing number, treated as zero.
<to be read again>
\relax
l.21 \begin{Ventry}{Return values}
\end{verbatim}
The problem arises because, in its first edition, the
\emph{Companion}'s examples always assumed that the \Package{calc}
package is loaded: this fact is mentioned in the book, but often not
noticed. The remedy is to load the \Package{calc} package in any
document using such examples from the \emph{Companion}. (The problem
does not really arise with the second edition; copies of all the
examples are available on the accompanying \CDROM{}, or on
\acro{CTAN}.)
The other problem, which is increasingly rare nowadays, arises from
misconfiguration of a system that has been upgraded from \LaTeXo{}:
the document uses the \Package{times} package, and the error appears
at \cmdinvoke{begin}{document}. The file search paths are wrongly set
up, and your \cmdinvoke{usepackage}{times} has picked up a \LaTeXo{}
version of the package, which in its turn has invoked another which
has no equivalent in \LaTeXe{}. The obvious solution is to rewrite
the paths so that \LaTeXo{} packages are chosen only as a last resort
so that the startlingly simple \LaTeXe{} \Package{times} package will
be picked up. Better still is to replace the whole thing with
something more modern still; current \Package{psnfss} doesn't provide
a \Package{times} package~--- the alternative \Package{mathptmx}
incorporates \FontName{Times}-like mathematics, and a sans-serif face
based on \FontName{Helvetica}, but scaled to match \FontName{Times}
text rather better.
\begin{ctanrefs}
\item[calc.sty]Distributed as part of \CTANref{2etools}[calc]
\item[\nothtml{\rmfamily}Examples for \nothtml{\upshape}\LaTeX{} Companion]\CTANref{tlc2}
\item[The psnfss bundle]\CTANref{psnfss}
\end{ctanrefs}
\LastEdit{2011-06-01}
\Question[Q-typend]{``Please type a command or say \csx{end}''}
Sometimes, when you are running \AllTeX{}, it will abruptly stop and
present you with a prompt (by default, just a |*| character). Many
people (including this author) will reflexively hit the `return'
key, pretty much immediately, and of course this is no help at all~---
\TeX{} just says:
\begin{verbatim}
(Please type a command or say `\end')
\end{verbatim}
and prompts you again.
What's happened is that your \AllTeX{} file has finished prematurely,
and \TeX{} has fallen back to a supposed including file, from the
terminal. This could have happened simply because you've omitted
the \csx{bye} (\plaintex{}), \cmdinvoke{end}{document} (\LaTeX{}), or
whatever. Other common errors are failure to close the braces round a