summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/archive-version/faq-jot-err.tex
blob: 23dd355da045ce35b9b4f6f401e405b1dcc52fd5 (plain)
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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
% $Id: faq-jot-err.tex,v 1.23 2012/11/10 14:25:12 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.

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 (which makes
available many more registers, etc., than \latex{} does by default;
\etex{} can create lots more registers, but none of those ``beyond
the original \TeX{} default'' may be used in float skeletons).  Thus,
\Package{etex} may offer some relief, but it can \emph{not} be
regarded as a panacea

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
command's argument, or (in \LaTeX{}) failure to close a verbatim
environment: in such cases you've already read and accepted an
error message about encountering end of file while scanning something.

If the error is indeed because you've forgotten to end your document,
you can insert the missing text: if you're running \plaintex{}, the
advice, to ``say \csx{end}'' is good enough: it will kill the run; if
you're running \LaTeX{}, the argument will be necessary:
\cmdinvoke{end}{document}.  

However, as often as not this isn't the problem, and (short of
debugging the source of the document before ending) brute force is
probably necessary.  Excessive force (killing the job that's
running \TeX{}) is to be avoided: there may well be evidence in the
\extension{log} file that will be useful in determining what the
problem is~--- so the aim is to persuade \TeX{} to shut itself down
and hence flush all log output to file.

If you can persuade \TeX{} to read it, an end-of-file indication
(control-|D| under Unix, control-|Z| under Windows) will provoke
\TeX{} to report an error and exit immediately.  Otherwise you should
attempt to provoke an error dialogue, from which you can exit (using
the |x| `command').  An accessible error could well be inserting an
illegal character: what it is will depend on what macros you are
running.  If you can't make that work, try a silly command name or
two.

\Question[Q-unkgrfextn]{``Unknown graphics extension''}

The \LaTeX{} graphics package deals with several different types of
\acro{DVI} (or other) output drivers; each one of them has a potential
to deal with a different selection of graphics formats.  The package
therefore has to be told what graphics file types its output driver
knows about; this is usually done in the \meta{driver}\extension{def} file
corresponding to the output driver you're using.

The error message arises, then, if you have a graphics file whose
extension doesn't correspond with one your driver knows about.  Most
often, this is because you're being optimistic: asking
\ProgName{dvips} to deal with a \extension{png} file, or \PDFTeX{} to deal with
a \extension{eps} file: the solution in this case is to transform the graphics
file to a format your driver knows about.

If you happen to \emph{know} that your device driver deals with the
format of your file, you are probably falling foul of a limitation of
the file name parsing code that the graphics package uses.  Suppose
you want to include a graphics file \File{home.bedroom.eps} using the
\ProgName{dvips} driver; the package will conclude that your file's
extension is \extension{bedroom.eps}, and will complain.

The \Package{grffile} package deals with the last problem (and
others~--- see the package documentation); using the package, you may
write:
\begin{quote}
\begin{verbatim}
\usepackage{graphicx}
\usepackage{grffile}
...
\includegraphics{home.bedroom.eps}
\end{verbatim}
\end{quote}
or you may even write
\begin{quote}
\begin{verbatim}
\includegraphics{home.bedroom}
\end{verbatim}
\end{quote}
and \Package{graphicx} will find a \extension{eps} or \extension{pdf}
(or whatever) version, according to what version of \AllTeX{} you're
running.

If for some reason you can't use \Package{grffile}, you have three
unsatisfactory alternatives:
\begin{itemize}
\item Rename the file~--- for example \File{home.bedroom.eps}\arrowhyph{}%
  \File{home-bedroom.eps}
\item Mask the first dot in the file name:
\begin{verbatim}
\newcommand*{\DOT}{.}
\includegraphics{home\DOT bedroom.eps}
\end{verbatim}
\item Tell the graphics package what the file is, by means of options
  to the \csx{includegraphics} command:
\begin{narrowversion}
\begin{verbatim}
\includegraphics[type=eps,ext=.eps,
                 read=.eps]{home.bedroom}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\includegraphics[type=eps,ext=.eps,read=.eps]{home.bedroom}
\end{verbatim}
\end{wideversion}
\end{itemize}
\begin{ctanrefs}
\item[grffile.sty]Distributed as part of the Oberdiek collection
  \CTANref{oberdiek}[grffile]
\end{ctanrefs}

\Question[Q-nodollar]{``Missing \texttt{\$} inserted''}

There are certain things that \emph{only} work in maths mode.  If your
document is not in maths mode and you have an |_| or a |^| character,
\TeX{} (and by inheritance, \LaTeX{} too) will say
\begin{verbatim}
! Missing $ inserted
\end{verbatim}
as if you couldn't possibly have misunderstood the import of what you
were typing, and the only possible interpretation is that you had
committed a typo in failing to enter maths mode.  \TeX{}, therefore,
tries to patch things up by inserting the \texttt{\$} you `forgot', so that
the maths-only object will work; as often as not this will land you in
further confusion.

It's not just the single-character maths sub- and superscript
operators: anything that's built in or declared as a maths operation,
from the simplest lower-case \csx{alpha} through the inscrutable
\csx{mathchoice} primitive, and beyond, will provoke the error if
misused in text mode.

\LaTeX{} offers a command \csx{ensuremath}, which will put you in maths
mode for the execution of its argument, if necessary: so if you want
an \csx{alpha} in your running text, say
\cmdinvoke{ensuremath}{\csx{alpha}}; if the bit of running text somehow
transmutes into a bit of mathematics, the \csx{ensuremath} will become
a no-op, so it's pretty much always safe.

\Question[Q-fontunavail]{Warning: ``Font shape \dots{}\ not available''}

\LaTeX{}'s font selection scheme maintains tables of the font families
it has been told about.  These tables list the font families that
\LaTeX{} knows about, and the shapes and series in which those font
families are available.  In addition, in some cases, the tables list
the sizes at which \LaTeX{} is willing to load fonts from the family.

When you specify a font, using one of the \LaTeX{} font selection
commands, \LaTeX{} looks for the font (that is, a font that matches
the encoding, family, shape, series and size that you want) in its
tables.  If the font isn't there at the size you want, you will see a
message like:
\htmlignore
\begin{dviversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/m/n' in
...                 size <11.5> not available
(Font)              size <12> substituted on
...                 input line ...
\end{verbatim}
(All the message texts in this answer have been wrapped so that they
will fit in the narrow columns of this version of the \acro{FAQ}.  The
continuation marker is |...| at the start of the broken-off portion of
the line.)

\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/m/n' in size <11.5> not available
(Font)              size <12> substituted on input line ...
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/m/n' in size <11.5> not available
(Font)              size <12> substituted on input line ...
\end{verbatim}
\end{htmlversion}
There will also be a warning like:
\htmlignore
\begin{dviversion}
\begin{verbatim}
LaTeX Font Warning: Size substitutions with
...                 differences
(Font)              up to 0.5pt have occurred.
\end{verbatim}
\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
LaTeX Font Warning: Size substitutions with differences
(Font)              up to 0.5pt have occurred.
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
LaTeX Font Warning: Size substitutions with differences
(Font)              up to 0.5pt have occurred.
\end{verbatim}
\end{htmlversion}
after \LaTeX{} has encountered \cmdinvoke{end}{document}.

The message tells you that you've chosen a font size that is not in
\LaTeX{}'s list of ``allowed'' sizes for this font; \LaTeX{} has
chosen the nearest font size it knows is allowed.  In fact, you can
tell \LaTeX{} to allow \emph{any} size: the restrictions come from the
days when only bitmap fonts were available, and they have never
applied to fonts that come in scaleable form in the first place.
Nowadays, most of the fonts that were once bitmap-only are also
available in scaleable (Adobe Type~1) form.  If your installation uses
scaleable versions of the Computer Modern or European Computer Modern
(\acro{EC}) fonts, you can tell \LaTeX{} to remove the restrictions;
use the \Package{type1cm} or \Package{type1ec} package as appropriate.

If the combination of font shape and series isn't available, \LaTeX{}
will usually have been told of a fall-back combination that may be
used, and will select that:
\htmlignore
\begin{dviversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/bx/sc'
...                 undefined
(Font)              using `OT1/cmr/bx/n'
...                 instead on input line 0.
\end{verbatim}
\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/bx/sc' undefined
(Font)              using `OT1/cmr/bx/n' instead on input line 0.
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
LaTeX Font Warning: Font shape `OT1/cmr/bx/sc' undefined
(Font)              using `OT1/cmr/bx/n' instead on input line 0.
\end{verbatim}
\end{htmlversion}

Substitutions may also be ``silent''; in this case, there is no more
than an ``information'' message in the log file.  For example, if you
specify an encoding for which there is no version in the current font
family, the `default family for the encoding' is selected.  This
happens, for example, if you use command \csx{textbullet}, which is
normally taken from the maths symbols font, which is in |OMS|
encoding.  My test log contained:
\htmlignore
\begin{dviversion}
\begin{verbatim}
LaTeX Font Info:    Font shape `OMS/cmr/m/n' in
...                 size <10> not available
(Font)              Font shape `OMS/cmsy/m/n'
...                 tried instead on input
...                 line ...
\end{verbatim}
\end{dviversion}
\begin{pdfversion}
\begin{verbatim}
LaTeX Font Info:    Font shape `OMS/cmr/m/n' in size <10> not available
(Font)              Font shape `OMS/cmsy/m/n' tried instead on input line ...
\end{verbatim}
\end{pdfversion}
\endhtmlignore
\begin{htmlversion}
\begin{verbatim}
LaTeX Font Info:    Font shape `OMS/cmr/m/n' in size <10> not available
(Font)              Font shape `OMS/cmsy/m/n' tried instead on input line ...
\end{verbatim}
\end{htmlversion}

In summary, these messages are not so much error messages, as
information messages, that tell you what \LaTeX{} has made of your
text.  You should check what the messages say, but you will ordinarily
not be surprised at their content.
\begin{ctanrefs}
\item[type1cm.sty]\CTANref{type1cm}
\item[type1ec.sty]\CTANref{type1ec}
\end{ctanrefs}

\Question[Q-buffovl]{Unable to read an entire line}

\TeX{} belongs to the generation of applications written for
environments that didn't offer the sophisticated string and i/o
manipulation we nowadays take for granted (\TeX{} was written in
Pascal, and the original Pascal standard made no mention of i/o, so
that anything but the most trivial operations were likely to be
unportable).

When you overwhelm \TeX{}'s input mechanism, you get told:
\begin{verbatim}
! Unable to read an entire line---bufsize=3000.
    Please ask a wizard to enlarge me.
\end{verbatim}
(for some value of `3000'~--- the quote was from a
\Newsgroup{comp.text.tex} posting by a someone who was presumably
using an old \TeX{}).

As the message implies, there's (what \TeX{} thinks of as a) line in
your input that's ``too long'' (to \TeX{}'s way of thinking).  Since
modern distributions tend to have tens of thousands of bytes of input
buffer, it's somewhat rare that these messages occur ``for real''.
Probable culprits are:
\begin{itemize}
\item A file transferred from another system, without translating
  record endings.  With the decline of fixed-format records (on
  mainframe operating systems) and the increased intelligence of
  \TeX{} distributions at recognising other systems' explicit
  record-ending characters, this is nowadays rather a rare cause of
  the problem.
\item A graphics input file, which a package is examining for its
  bounding box, contains a binary preview section.  Again,
  sufficiently clever \TeX{} distributions recognise this situation,
  and ignore the previews (which are only of interest, if at all, to a
  \TeX{} previewer).
\end{itemize}

The usual advice is to ignore what \TeX{} says (i.e., anything about
enlarging), and to put the problem right in the source. 

If the real problem is over-long text lines, most self-respecting text
editors will be pleased to automatically split long lines (while
preserving the ``word'' structure) so that they are nowhere any longer
than a given length; so the solution is just to edit the file.

If the problem is a ridiculous preview section, try using
\ProgName{ghostscript} to reprocess the file, outputting a ``plain
\extension{eps}'' file.  (\ProgName{Ghostscript} is distributed with a script
\ProgName{ps2epsi} which will regenerate the preview if necessary.)
Users of the shareware program \ProgName{GSview} will find buttons to
perform the required transformation of the file being displayed.
\begin{ctanrefs}
\item[ghostscript]Browse \CTANref{ghostscript}
\item[GSview]Browse \CTANref{gsview}
\end{ctanrefs}

\Question[Q-formatstymy]{``Fatal format file error; I'm stymied''}

\AllTeX{} applications often fail with this error when you've been
playing with the configuration, or have just installed a new version.

The format file contains the macros that define the system you want to
use: anything from the simplest (\plaintex{}) all the way to the most
complicated, such as \LaTeX{} or \CONTeXT{}.  From the command you
issue, \TeX{} knows which format you want.

The error message
\begin{verbatim}
  Fatal format file error; I'm stymied
\end{verbatim}
means that \TeX{} itself can't understand the format you want.
Obviously, this could happen if the format file had got corrupted, but
it usually doesn't.  The commonest cause of the message, is that a new
binary has been installed in the system: no two \TeX{} binaries on the
same machine can
understand each other's formats.  So the new version of \TeX{} you
have just installed, won't understand the format generated by the one
you installed last year.

Resolve the problem by regenerating the format; of course, this
depends on which system you are using.
\begin{itemize}
\item On a te\TeX{}-based system, run
\begin{verbatim}
  fmtutil --all
\end{verbatim}
  or
\begin{verbatim}
  fmtutil --byfmt=<format name>
\end{verbatim}
  to build only the format that you are interested in.
\item On a \miktex{} system, click \texttt{Start}\arrowhyph{}%
\texttt{Programs}\arrowhyph{}%
\texttt{\miktex{} \emph{version}}\arrowhyph{}%
\texttt{\miktex{} Options}, and in the options window, click
  \texttt{Update now}.
\end{itemize}

\Question[Q-nonpdfsp]{Non-\acro{PDF} special ignored!}

This is a \PDFTeX{} error: \PDFTeX{} is running in \acro{PDF} output
%  beware line break at end line
mode, and it has encountered a \nothtml{\csx{special} command (}%
\Qref{\csx{special}}{Q-specials}\latexhtml{)}{ command}.  \PDFTeX{} is
able to generate its own output, and in this mode of operation has no
need of \csx{special} commands (which allow the user to pass
information to the driver being used to generate output).

Why does this happen?  \LaTeX{} users, nowadays, hardly ever use
\csx{special} commands on their own~--- they employ packages to do the
job for them.  Some packages will generate \csx{special} commands
however they are invoked: \Package{pstricks} is an example (it's very
raison d'\^etre is to emit \PS{} code in a sequence of \csx{special}
commands).  \Package{Pstricks} may be dealt with by other means (the
\Package{pdftricks} package offers a usable technique).

More amenable to correction, but more confusing, are packages (such as
\Package{color}, \Package{graphics} and \Package{hyperref}) that
specify a ``driver''.  These packages have plug-in modules that
determine what \csx{special} (or other commands) are needed to generate
any given effect: the \texttt{pdftex} driver for such packages knows not to
generate \csx{special} commands.  In most circumstances, you can let
the system itself choose which driver you need; in this case
everything will act properly when you switch to using \PDFLaTeX{}.  If
you've been using \ProgName{dvips} (and specifying the |dvips| driver)
or \ProgName{dvipdfm} (for which you have to specify the driver), and
decide to try \PDFLaTeX{}, you \emph{must} remove the |dvips| or
|dvipdfm| driver specification from the package options, and let the
system recognise which driver is needed.
\begin{ctanrefs}
\item[pdftricks.sty]\CTANref{pdftricks}
\item[pstricks.sty]\CTANref{pstricks}
\end{ctanrefs}

\Question[Q-8000]{Mismatched mode ljfour and resolution 8000}

You're running \ProgName{dvips}, and you encounter a stream of error
messages, starting with ``\texttt{Mismatched mode}''.  The mode is the
default used in your installation~--- it's set in the \ProgName{dvips}
configuration file, and \texttt{ljfour} is commonest (since it's the
default in most distributions), but not invariable.

The problem is that \ProgName{dvips} has encountered a font for which
it must generate a bitmap (since it can't find it in Type~1 format),
and there is no proforma available to provide instructions to give to
\MF{}.

So what to do?  The number 8000 comes from the `\texttt{-Ppdf}' option
to \ProgName{dvips}, which you might have found from the answer
\nothtml{``wrong type of fonts'' (}% beware % beware line breaks
\Qref{``wrong type of fonts''}{Q-fuzzy-type3}\nothtml{)}.  The obvious
solution is to switch to the trivial substitute `\texttt{-Pwww}',
which selects the necessary type~1 fonts for \acro{PDF} generation,
but nothing else: however, this will leave you with undesirable bitmap
fonts in your \acro{PDF} file.  The ``proper'' solution is to find a
way of expressing what you want to do, using type~1 fonts.

\Question[Q-toodeep]{``Too deeply nested''}

This error appears when you start a \LaTeX{} list.

\LaTeX{} keeps track of the nesting of one list inside another.  There
is a set of list formatting parameters built-in for application to
each of the list nesting levels; the parameters determine indentation,
item separation, and so on.  The \environment{list} environment (the
basis for list environments like \environment{itemize} and
\environment{enumerate}) ``knows'' there are only 6 of these sets.

There are also different label definitions for the
\environment{enumerate} and \environment{itemize} environments at
their own private levels of nesting.  Consider this example:
\begin{quote}
\begin{verbatim}
\begin{enumerate}
\item first item of first enumerate
  \begin{itemize}
  \item first item of first itemize
    \begin{enumerate}
    \item first item of second enumerate
    ...
    \end{enumerate}
  ...
  \end{itemize}
...
\end{enumerate}
\end{verbatim}
\end{quote}
In the example,
\begin{itemize}
\item the first \environment{enumerate} has labels as for a
  first-level \environment{enumerate}, and is indented as for a
  first-level list;
\item the first \environment{itemize} has labels as for a first level
  \environment{itemize}, and is indented as for a second-level list;
  and
\item the second \environment{enumerate} has labels as for a
  second-level \environment{enumerate}, and is indented as for a
  third-level list.
\end{itemize}
Now, as well as \LaTeX{} \emph{knowing} that there are 6~sets of
parameters for indentation, it also \emph{knows} that there are only
4~types of labels each, for the environments \environment{enumerate}
and \environment{itemize} (this ``knowledge'' spells out a requirement
for class writers, since the class supplies the sets of parameters).

From the above, we can deduce that there are several ways we can run
out of space: we can have 6~lists (of any sort) nested, and try to
start a new one; we can have 4~\environment{enumerate} environments
somewhere among the set of nested lists, and try to add another one;
and we can have 4~\environment{itemize} environments somewhere among
the set of nested lists, and try to add another one.

What can be done about the problem?  Not much, short of rewriting
\LaTeX{}~--- you really need to rewrite your document in a slightly
less labyrinthine way.

\Question[Q-inputlev]{Capacity exceeded~--- input levels}

The error
\begin{wideversion}
\begin{verbatim}
! TeX capacity exceeded, sorry [text input levels=15].
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
! TeX capacity exceeded, sorry
                         [text input levels=15].
\end{verbatim}
\end{narrowversion}
is caused by nesting your input too deeply.  You can provoke it with
the trivial (\plaintex{}) file \File{input.tex}, which contains
nothing but: 
\begin{verbatim}
\input input
\end{verbatim}
In the real world, you are unlikely to encounter the error with a
modern \TeX{} distribution.  Te\TeX{} (used to produce the error
message above) allows 15 files open for \TeX{} input at any one time,
which is improbably huge for a document generated by real human
beings.

However, for those improbable (or machine-generated) situations,
some distributions offer the opportunity to adjust the parameter
|max_in_open| in a configuration file.

\Question[Q-hyperdupdest]{\PDFTeX{} destination \dots{}\ ignored}

The warning:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
! pdfTeX warning (ext4): destination with the same identifier
(name{page.1}) has been already used, duplicate ignored
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
! pdfTeX warning (ext4): destination with
  the same identifier (name{page.1}) has
  been already used, duplicate ignored
\end{verbatim}
{\small NB: message text wrapped to fit in the column\par}
\end{narrowversion}
\end{quote}
arises because of duplicate page numbers in your document.  The
problem is usually soluble: see % beware line break
\Qref*[question]{\acro{PDF} page destinations}{Q-pdfpagelabels}~--- which
answer also describes the problem in more detail.

If the identifier in the message is different, for example
\texttt{name\{figure.1.1\}}, the problem is (often) due to a problem of
package interaction.  The \File{README} in the \Package{hyperref}
distribution mentions some of these issues~--- for example,
\environment{equation} and \environment{eqnarray} as supplied by the
\Package{amsmath} package; means of working around the problem are
typically supplied there.

Some packages are simply incompatible with
\Package{hyperref}, but most work simply by ignoring it.  In most
cases, therefore, you should load your package before you load
\Package{hyperref}, and \Package{hyperref} will patch things up so
that they work, so you can utilise your (patched) package \emph{after}
loading both:
\begin{quote}
  \cmdinvoke{usepackage}{\emph{your package}}\\
  \texttt{...}\\
  \cmdinvoke{usepackage}[\emph{opts}]{hyperref}\\
  \texttt{...}\\
  \meta{code that uses your package}
\end{quote}
\begin{wideversion}
For example:
\begin{quote}
\begin{verbatim}
\usepackage{float}          % defines \newfloat
...
\usepackage[...]{hyperref}  % patches \newfloat
...
\newfloat{...}{...}{...}
\end{verbatim}
\end{quote}
\end{wideversion}
\begin{narrowversion}
So, if we need \csx{newfloat}:
\begin{quote}
\cmdinvoke{usepackage}{float}
\end{quote}
will define the command,
\begin{quote}
\cmdinvoke{usepackage}[\emph{opts}]{hyperref}
\end{quote}
will patch it, and now: 
\begin{quote}
\cmdinvoke{newfloat}{...}{...}{...}
\end{quote}
will use the command, patched to create `proper' hyperreferences.
\end{narrowversion}
You should load packages in this order as a matter of course, unless
the documentation of a package says you \emph{must} load it after
\Package{hyperref}.  (There are few packages that require to be
loaded after hyperref: one such is \Class{memoir}'s
``\Package{hyperref} fixup'' package \Package{memhfixc}.)

If loading your packages in the (seemingly) ``correct'' order doesn't
solve the problem, you need to \Qref*{seek further help}{Q-gethelp}.

\Question[Q-altabcr]{Alignment tab changed to \csx{cr}}

This is an error you may encounter in \LaTeX{} when a tabular
environment is being processed.  ``Alignment tabs'' are the
\texttt{\&} signs that separate the columns of a \environment{tabular}
(or \environment{array} or matrix) environment; so the error message
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
! Extra alignment tab has been 
                            changed to \cr
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
! Extra alignment tab has been changed to \cr
\end{verbatim}
\end{wideversion}
\end{quote}
could arise from a simple typo, such as:
\begin{quote}
\begin{verbatim}
\begin{tabular}{ll}
  hello   & there & jim \\
  goodbye & now
\end{tabular}
\end{verbatim}
\end{quote}
where the second \texttt{\&} in the first line of the table is more than the
two-column \texttt{ll} column specification can cope with. In this
case, an extra ``\texttt{l}'' in that solves the problem.  (If you
continue from the error in this case, ``\texttt{jim}'' will be moved
to a row of his own.)  Another simple typo that can provoke the error
is:
\begin{quote}
\begin{verbatim}
\begin{tabular}{ll}
  hello   & there
  goodbye & now
\end{tabular}
\end{verbatim}
\end{quote}
where the `\texttt{\bsbs }' has been missed from the first line of the table.
In this case, if you continue from the error, you will find that
\LaTeX{} has made a table equivalent to:
\begin{quote}
\begin{verbatim}
\begin{tabular}{ll}
  hello   & there goodbye\\
  now
\end{tabular}
\end{verbatim}
\end{quote}
(with the second line of the table having only one cell).

Rather more difficult to spot is the occurrence of the error when
you're using alignment instructions in a ``\texttt{p}'' column:
\begin{quote}
\begin{verbatim}
\usepackage{array}
...
\begin{tabular}{l>{\raggedright}p{2in}}
here & we are again \\
happy & as can be
\end{tabular}
\end{verbatim}
\end{quote}
the problem here (as explained in % ! line break
\Qref[question]{tabular cell alignment}{Q-tabcellalign}) is that the
\csx{raggedright} command in the column specification has overwritten
\environment{tabular}'s definition of \texttt{\bsbs }, so that
``\texttt{happy}'' appears in a new line of the second column, and the
following \texttt{\&} appears to \LaTeX{} just like the second
\texttt{\&} in the first example above.

Get rid of the error in the way described in % ! linebreak
\Qref[question]{tabular cell alignment}{Q-tabcellalign}~--- either use
\csx{tabularnewline} explicitly, or use the \csx{RBS} trick described
there.

The \Package{amsmath} package adds a further twist; when typesetting
a matrix (the package provides many matrix environments), it has a
fixed maximum number of columns in a matrix~--- exceed that maximum,
and the error will appear.  By default, the maximum is set to 10, but
the value is stored in counter \texttt{MaxMatrixCols} and may be
changed (in the same way as any counter):
\begin{quote}
\begin{verbatim}
\setcounter{MaxMatrixCols}{20}
\end{verbatim}
\end{quote}
\begin{ctanrefs}
\item[array.sty]Distributed as part of \CTANref{2etools}[array]
\end{ctanrefs}
\LastEdit{2011-07-06}

\Question[Q-divzero]{Graphics division by zero}

While the error
\begin{quote}
\begin{verbatim}
! Package graphics Error: Division by 0.
\end{verbatim}
\end{quote}
can actually be caused by offering the package a figure which claims
to have a zero dimension, it's more commonly caused by rotation.

Objects in \TeX{} may have both height (the height above the baseline)
and depth (the distance the object goes below the baseline).  If you
rotate an object by 180\,degrees, you convert its height into depth,
and vice versa; if the object started with zero depth, you've
converted it to a zero-height object.

Suppose you're including your graphic with a command like:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\includegraphics[angle=180,height=5cm]{myfig.eps}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\includegraphics[angle=180,%
                height=5cm]{myfig.eps}
\end{verbatim}
\end{narrowversion}
\end{quote}
In the case that \File{myfig.eps} has no depth to start with, the
scaling calculations will produce the division-by-zero error.

Fortunately, the \Package{graphicx} package has a keyword
\pkgoption{totalheight}, which allows you to specify the size of the
image relative to the sum of the object's \pkgoption{height} and
\pkgoption{depth}, so
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\includegraphics[angle=180,totalheight=5cm]{myfig.eps}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\includegraphics[angle=180,%
           totalheight=5cm]{myfig.eps}
\end{verbatim}
\end{narrowversion}
\end{quote}
will resolve the error, and will behave as you might hope.

If you're using the simpler \Package{graphics} package, use the
\texttt{*} form of the \csx{resizebox} command to specify the use of
\pkgoption{totalheight}:
\begin{quote}
\begin{verbatim}
\resizebox*{!}{5cm}{%
  \rotatebox{180}{%
    \includegraphics{myfig.eps}%
  }%
}
\end{verbatim}
\end{quote}
\begin{ctanrefs}
\item[graphics.sty,graphicx.sty]Both parts of the \CTANref{graphics} bundle
\end{ctanrefs}

\Question[Q-missbegdoc]{Missing \csx{begin}\marg{document}}

The \emph{preamble} of your document is the stuff before
\cmdinvoke{begin}{document}; you put \csx{usepackage} commands and
your own macro definitions in there.  \latex{} doesn't like
\emph{typesetting} anything in the preamble, so if you have:
\begin{itemize}
\item typed the odd grumble,
\item created a box with \csx{newsavebox} and put something in it
  using \csx{sbox} (or the like),
\item forgotten to put \cmdinvoke{begin}{document} into the document,
  at all, or even
\item gave it the wrong file
\end{itemize}
the error is inevitable and the solution is simple~--- judicious use
of comment markers (`\texttt{\textpercent{}}') at the beginning of a
line, moving things around, providing something that was
missing~\dots{} or switching to the correct file.

The error may also occur while reading the \extension{aux} file from an
earlier processing run on the document; if so, delete the
\extension{aux} file and start again from scratch.  If the error
recurs, it could well be due to a buggy class or package.

However, it may be that none of the above solves the problem.

If so, remember that things that appear before \csx{documentclass} are
also problematical: they are inevitably before
\cmdinvoke{begin}{document}!

Unfortunately, modern editors are capable of putting things there, and
preventing you from seeing them.  This can happen when your document
is being `written' in \Qref*{Unicode}{Q-unicode}.  The Unicode
standard defines ``Byte Order Marks'' (\acro{BOM}), that reassure a
program (that reads the document) of the way the Unicode codes are
laid out.  Sadly ordinary \latex{} or \pdflatex{} choke on
\acro{BOM}s, and consider them typesetting requests.  The error
message you see will look like:
\begin{quote}
\begin{verbatim}
! LaTeX Error: Missing \begin{document}.
...
l.1 <?>
       <?><?>\documentclass{article}
\end{verbatim}
\end{quote}
(Those \texttt{<?>}s are your operating system's representation of an
unknown character; on the author's system it's a reverse video
`\texttt{?}' sign.)

You can spot the \acro{BOM} by examining the bytes; for example, the
Unix \ProgName{hexdump} application can help:
\begin{quote}
\begin{verbatim}
$ hexdump -C <file>
00000000  ef bb bf 5c 64 6f 63 75 ...
\end{verbatim}
\end{quote}
The \texttt{5c 64 6f 63 75} are the ``\csx{docu}'' at the start of
(the `real' part of) your document; the three bytes before it form the
\acro{BOM}.

How to stop your editor from doing this to you depends, of course, on
the editor you use; if you are using \acro{GNU E}macs, you have to
change the encoding from \texttt{utf-8-with-signature} to `plain'
\texttt{utf-8}; instructions for that are found on
% ! line break
\href{http://stackoverflow.com/questions/3859274/}{the ``stack overflow'' site}

(So far, all instances of this problem that the author has seen have
afflicted \acro{GNU E}macs users.)

Fortunately \xetex{} and \luatex{} know about \acro{BOM}s and what to
do with them, so \latex{} using them is ``safe''.

\Question[Q-normalszmiss]{\csx{normalsize} not defined}

The \LaTeX{} error:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
The font size command \normalsize is not
   defined: there is probably something
   wrong with the class file.
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
The font size command \normalsize is not defined:
there is probably something wrong with the class file.
\end{verbatim}
\end{wideversion}
\end{quote}
is reporting something pretty fundamental (document base font size not
set up).  While this \emph{can}, as the message implies, be due to a
broken class file, the more common cause is that you have simply
forgotten to put a \csx{documentclass} command in your document.

\Question[Q-manymathalph]{Too many math alphabets}

\TeX{} mathematics is one of its most impressive features, yet the
internal structure of the mechanism that produces it is painfully
complicated and (in some senses) pathetically limited.  One area of
limitation is that one is only allowed 16~''maths alphabets''

\LaTeX{} offers the user quite a lot of flexibility with allocating
maths alphabets, but few people use the flexibility directly.
Nevertheless, there are many packages that provide symbols, or that
manipulate them, which allocate themselves one or more maths alphabet.

If you can't afford to drop any of these packages, there's
still hope if you're using the \Package{bm} package to support
\Qref*{bold maths}{Q-boldgreek}: \Package{bm} is capable
of gobbling alphabets as if there is no tomorrow.  The package defines
two limiter commands: \csx{bmmax} (for \emph{bold} symbols; default~4)
and \csx{hmmax} (for \emph{heavy} symbols, if you have them;
default~3), which control the number of alphabets to be used.  

Any reduction of the \csx{\emph{xx}max} variables will slow
\Package{bm} down~--- but that's surely better than the document not
running at all.  So unless you're using maths fonts (such as
\FontName{Mathtime Plus}) that feature a heavy symbol weight, suppress all
use of heavy families by
\begin{quote}
\begin{verbatim}
  \newcommand{\hmmax}{0}
\end{verbatim}
\end{quote}
(before loading \Package{bm}), and then steadily reduce the bold
families, starting with 
\begin{quote}
\begin{verbatim}
  \newcommand{\bmmax}{3}
\end{verbatim}
\end{quote}
(again before loading \Package{bm}), until (with a bit of luck) the
error goes away.
\begin{ctanrefs}
\item[bm.sty]Distributed as part of \CTANref{2etools}[bm]
\end{ctanrefs}

\Question[Q-ouparmd]{Not in outer par mode}

The error:
\begin{quote}
\begin{verbatim}
! LaTeX Error: Not in outer par mode.
\end{verbatim}
\end{quote}
comes when some ``main'' document feature is shut up somewhere it
doesn't like.

The commonest occurrence is when the user wants a figure somewhere
inside a table:
\begin{quote}
\begin{verbatim}
\begin{tabular}{|l|}
  \hline
  \begin{figure}
  \includegraphics{foo}
  \end{figure}
  \hline
\end{tabular}
\end{verbatim}
\end{quote}
a construction that was supposed to put a frame around the diagram,
but doesn't work, any more than:
\begin{quote}
\begin{verbatim}
\framebox{\begin{figure}
  \includegraphics{foo}
  \end{figure}%
}
\end{verbatim}
\end{quote}
The problem is, that the \environment{tabular} environment, and the
\csx{framebox} command restrain the \environment{figure} environment
from its natural m\'etier, which is to float around the document.

The solution is simply not to use the \environment{figure} environment
here:
\begin{quote}
\begin{verbatim}
\begin{tabular}{|l|}
  \hline
  \includegraphics{foo}
  \hline
\end{tabular}
\end{verbatim}
\end{quote}
What was the float for?~--- as written in the first two examples, it
serves no useful purpose; but perhaps you actually wanted a diagram
and its caption framed, in a float.

It's simple to achieve this~--- just reverse the order of the
environments (or of the \environment{figure} environment and the
command):
\begin{quote}
\begin{verbatim}
\begin{figure}
  \begin{tabular}{|l|}
    \hline
    \includegraphics{foo}
    \caption{A foo}
    \hline
  \end{tabular}
\end{figure}
\end{verbatim}
\end{quote}
The same goes for \environment{table} environments (or any other sort
of float you've defined for yourself) inside tabulars or box commands;
you \emph{must} get the float environment out from inside, one way or
another.

\Question[Q-errmissitem]{Perhaps a missing \csx{item}?}

Sometimes, the error
\begin{quote}
\begin{verbatim}
Something's wrong--perhaps a missing \item
\end{verbatim}
\end{quote}
actually means what it says:
\begin{quote}
\begin{verbatim}
\begin{itemize}
  boo!
\end{itemize}
\end{verbatim}
\end{quote}
produces the error, and is plainly in need of an \csx{item} command.

You can also have the error appear when at first sight things are
correct:
\begin{quote}
\begin{verbatim}
\begin{tabular}{l}
  \begin{enumerate}
  \item foo\\
  \item bar
  \end{enumerate}
\end{tabular}
\end{verbatim}
\end{quote}
produces the error at the \texttt{\bsbs }.  This usage is just wrong; if you
want to number the cells in a table, you have to do it ``by hand'':
\begin{quote}
\begin{verbatim}
\newcounter{tablecell}
...
\begin{tabular}{l}
  \stepcounter{tablecell}
  \thetablecell. foo\\
  \stepcounter{tablecell}
  \thetablecell. bar
\end{tabular}
\end{verbatim}
\end{quote}
This is obviously untidy; a command \csx{numbercell} defined as:
\begin{quote}
\begin{verbatim}
\newcounter{tablecell}
...
\newcommand*{\numbercell}{%
  \stepcounter{tablecell}%
  \thetablecell. % **
}
\end{verbatim}
\end{quote}
could make life easier:
\begin{quote}
\begin{verbatim}
\begin{tabular}{l}
  \numbercell foo\\
  \numbercell bar
\end{tabular}
\end{verbatim}
\end{quote}
Note the deliberate introduction of a space as part of the command,
marked with asterisks.  Omitted above, the code needs to set the
counter \ltxcounter{tablecell} to zero
(\cmdinvoke{setcounter}{tablecell}{0}) before each tabular that uses it.

The error also regularly appears when you would never have thought
that a \csx{item} command  might be appropriate.  For example, the
seemingly innocent:
\begin{quote}
\begin{verbatim}
\fbox{%
  \begin{alltt}
    boo!
  \end{alltt}%
}
\end{verbatim}
\end{quote}
produces the error (the same happens with \csx{mbox} in place of
\csx{fbox}, or with either of their ``big brothers'', \csx{framebox} and
\csx{makebox}).  This is because the \environment{alltt} environment
uses a ``trivial'' list, hidden inside its definition.  (The
\environment{itemize} environment also has this construct inside
itself, in fact, so \cmdinvoke{begin}{itemize} won't work inside an
\csx{fbox}, either.)  The list construct wants to happen between
paragraphs, so it makes a new paragraph of its own.  Inside the
\csx{fbox} command, that doesn't work, and subsequent macros convince
themselves that there's a missing \csx{item} command.

To solve this rather cryptic error, one must put the
\environment{alltt} inside a paragraph-style box.  The following
modification of the above \emph{does} work:
\begin{quote}
\begin{verbatim}
\fbox{%
  \begin{minipage}{0.75\textwidth}
    \begin{alltt}
      hi, there!
    \end{alltt}
  \end{minipage}
}
\end{verbatim}
\end{quote}
The code above produces a box that's far too wide for the text.  One
may want to use something that allows % ! line break
\Qref*{variable size boxes}{Q-varwidth} in place of the
\environment{minipage} environment.

Oddly, although the \environment{verbatim} environment wouldn't work
inside a \csx{fbox} command argument (see % ! line break
\Qref[question]{verbatim in command arguments}{Q-verbwithin}), you
get an error that complains about \csx{item}: the environment's
internal list bites you before \environment{verbatim} has even had a
chance to create its own sort of chaos.

Another (seemingly) obvious use of \csx{fbox} also falls foul of this
error:
\begin{quote}
\begin{verbatim}
\fbox{\section{Boxy section}}
\end{verbatim}
\end{quote}
This is a case where you've simply got to be more subtle; you should
either write your own macros to replace the insides of \LaTeX{}'s
sectioning macros, or  look for some alternative in the packages
discussed in % ! line break
``\Qref*[question]{The style of section headings}{Q-secthead}''.

\Question[Q-errparnum]{Illegal parameter number in definition}

The error message means what it says.  In the simple case, you've
attempted a definition like:
\begin{quote}
\begin{verbatim}
\newcommand{\abc}{joy, oh #1!}
\end{verbatim}
\end{quote}
or (using \TeX{} primitive definitions):
\begin{quote}
\begin{verbatim}
\def\abc{joy, oh #1!}
\end{verbatim}
\end{quote}
In either of the above, the definition uses an argument, but the
programmer did not tell \AllTeX{}, in advance, that she was going to.
The fix is simple~--- \cmdinvoke{newcommand}{\csx{abc}}[1], in the
\LaTeX{} case, |\def\abc#1| in the basic \TeX{} case.

The more complicated case is exemplified by the attempted definition:
\begin{quote}
\begin{verbatim}
\newcommand{\abc}{joy, oh joy!%
  \newcommand{\ghi}[1]{gloom, oh #1!}%
}
\end{verbatim}
\end{quote}
will also produce this error, as will its \TeX{} primitive equivalent:
\begin{quote}
\begin{verbatim}
\def\abc{joy, oh joy!%
  \def\ghi#1{gloom, oh #1!}%
}
\end{verbatim}
\end{quote}
This is because special care is needed when defining one macro within
the code of another macro.  This is explained elsewhere, separately
for \Qref*[question]{\LaTeX{} definitions}{Q-ltxhash} and for
\Qref*[question]{\TeX{} primitive definitions}{Q-hash}

\Question[Q-fllost]{Float(s) lost}

The error
\begin{quote}
\begin{verbatim}
! LaTeX Error: Float(s) lost.
\end{verbatim}
\end{quote}
seldom occurs, but always seems deeply cryptic when it \emph{does}
appear.

The message means what it says: one or more figures, tables, etc., or
marginpars has not been typeset.  (Marginpars are treated internally
as floats, which is how they come to be lumped into this error
message.)

The most likely reason is that you placed a float or a \csx{marginpar}
command inside another float or marginpar, or inside a
\environment{minipage} environment, a \csx{parbox} or \csx{footnote}.
Note that the error may be detected a long way from the problematic
command(s), so the techniques of % ! line break
\Qref*{tracking down elusive errors}{Q-erroradvice} all need to be
called into play.

This author has also encountered the error when developing macros that
used the \LaTeX{} internal float mechanisms.  Most people doing that
sort of thing are expected to be able to work out their own problems\dots{}

\Question[Q-texorpdf]{Token not allowed in PDFDocEncoded string}

The package \Package{hyperref} produces this error when it doesn't
know how to make something into a ``character'' that will go into one
of its \acro{PDF} entries.  For example, the (unlikely) sequence
\begin{quote}
\begin{verbatim}
\newcommand{\filled}[2]{%
  #1%
  \hfil
  #2%
}
\section{\filled{foo}{bar}}
\end{verbatim}
\end{quote}
provokes the error.  \Package{Hyperref} goes on to tell you:
\begin{quote}
\begin{verbatim}
removing `\hfil' on input line ...
\end{verbatim}
\end{quote}
It's not surprising: how would \emph{you} put the
typesetting instruction \csx{hfil} into a \acro{PDF} bookmark?

\Package{Hyperref} allows you to define an alternative for such
things: the command \csx{texorpdfstring}, which takes two
arguments~--- the first is what is typeset, the second is what is put
into the bookmark.  For example, what you would probably like in this
case is just a single space in the bookmark; if so, the erroneous
example above would become:
\begin{quote}
\begin{verbatim}
\newcommand{\filled}[2]{%
  #1%
  \texorpdfstring{\hfil}{\space}%
  #2%
}
\section{\filled{foo}{bar}}
\end{verbatim}
\end{quote}
and with that definition, the example will compile succesfully
(\Package{hyperref} knows about the macro \csx{space}).
\LastEdit*{2009-05-29}

\Question[Q-checksum]{Checksum mismatch in font}

When \MF{} generates a font it includes a checksum in the font bitmap
file, and in the font metrics file (\acro{TFM}).  \AllTeX{} includes
the checksum from the \acro{TFM} file in the \acro{DVI} file.

When \ProgName{dvips} (or other \acro{DVI} drivers) process a
\acro{DVI} file, they compare checksums in the \acro{DVI} file to
those in the bitmap fonts being used for character images.  If the
checksums don't match, it means the font metric file used by \AllTeX{}
was not generated from the same \MF{} program that generated the
font.

This commonly occurs when you're processing someone else's \acro{DVI}
file.

The fonts on your system may also be at fault: possibilities are that
the new \acro{TFM} was not installed, or installed in a path after an
old \acro{TFM} file, or that you have a personal cache of bitmaps from
an old version of the font.

In any case, look at the output -- the chances are that it's perfectly
\acro{OK}, since metrics tend not to change, even when the bitmaps are
improved.  (Indeed, many font designers~--- Knuth included~---
maintain the metrics come what may.)

If the output \emph{does} look bad, your only chance is to regenerate
things from scratch.  Options include: flushing your bitmap cache,
rebuild the \acro{TFM} file locally, and so on.

\Question[Q-entercompmode]{Entering compatibility mode}

You run your \LaTeX{} job, and it starts by saying
\begin{quote}
\begin{verbatim}
Entering LaTeX 2.09 COMPATIBILITY MODE
\end{verbatim}
\end{quote}
followed by lines of asterisks and \texttt{!!WARNING!!}.

This means that the document is not written in ``current'' \LaTeX{}
syntax, and that there is no guarantee that all parts of the document
will be formatted correctly.

If the document is someone else's, and you want no more than a copy to
read, ignore the error.  The document may fail elsewhere, but as often
as not it will provide a \extension{dvi} or \extension{pdf} that's
adequate for most purposes.

If it's a new document you have just started working on, you have been
misled by someone.  You have written something like:
\begin{quote}
  \cmdinvoke{documentstyle}{article}
\end{quote}
or, more generally:
\begin{quote}
  \cmdinvoke*{documentstyle}[options]{class}
\end{quote}
These forms are (as the warning says) \LaTeXo{} syntax, and to get rid
of the warning, you must change the command.

The simple form is easy to deal with:
\begin{quote}
  \cmdinvoke{documentstyle}{article}
\end{quote}
should become:
\begin{quote}
  \cmdinvoke{documentclass}{article}
\end{quote}
The complex form is more difficult, since \LaTeXo{} ``options''
conflate two sorts of things~--- options for the class (such as
\pkgoption{11pt}, \pkgoption{fleqn}), and packages to be loaded.
So:
\begin{quote}
  \cmdinvoke{documentstyle}[11pt,verbatim]{article}
\end{quote}
should become:
\begin{quote}
  \cmdinvoke{documentclass}[11pt]{article}\\
  \cmdinvoke{usepackage}{verbatim}
\end{quote}
because \pkgoption{11pt} happens to be a class option, while
\Package{verbatim} is a package.

There's no simple way to work out what are class options under
\LaTeXo{}; for \Class{article}, the list includes \pkgoption{10pt},
\pkgoption{11pt}, \pkgoption{12pt}, \pkgoption{draft},
\pkgoption{fleqn}, \pkgoption{leqno}, \pkgoption{twocolumn} and
\pkgoption{twoside}~--- anything else must be a package.

Your document may well ``just work'' after changes like those above;
if not, you should think through what you're trying to do, and consult
documentation on how to do it~--- there are lots of % ! line break
\Qref*{free tutorials}{Q-tutorials*} to help you on your way, if you
don't have access to a \LaTeX{} manual of any sort.

\Question[Q-includeother]{\latex{} won't include from other directories}

You wanted to \cmdinvoke{include}{../bar/xyz.tex}, but \latex{} says:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
latex: Not writing to ../bar/xyz.aux (openout_any = p).
! I can't write on file `../bar/xyz.aux'.
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
LaTeX: Not writing to ../bar/xyz.aux
                          (openout_any = p).
! I can't write on file `../bar/xyz.aux'.
\end{verbatim}
(The first line of that message is wrapped, here.)
\end{narrowversion}
\end{quote}
The error comes from \tex{}'s protection against writing to
directories that aren't descendents of the one where your document
resides.  (The restriction protects against problems arising from
\latex{}ing someone else's malicious, or merely broken, document.  If
such a document overwrites something you wanted kept, there is obvious
potential for havoc.)

Document directory structures that can lead to this problem will look
like the fictional \File{mybook}:
\begin{quote}
\begin{verbatim}
./base/mybook.tex
./preface/Preface.tex
./preface/***
./chapter1/Intro.tex
...
\end{verbatim}
\end{quote}
With such a structure, any document directory (other than the one
where \File{mybook.tex} lives), seems ``up'' the tree from the
base directory.  (References to such files will look like
\cmdinvoke{include}{../preface/Preface}: the ``\texttt{..}'' is the
hint.)

But why did it want to write at all?~--- % ! line break
``\Qref*{what's going in in my \csx{include}}{Q-include}'' explains
how \csx{include} works, among other things by writing an
\extension{aux} file for every \csx{includ}ed file.

Solutions to the problem tend to be drastic:
\begin{enumerate}
\item Restructure the directories that hold your document so that the
  master file is at the root of the tree:
  \begin{quote}
\begin{verbatim}
./mybook.tex
./mybook/preface/Preface.tex
./mybook/preface/***
./mybook/chapter1/Intro.tex
...
\end{verbatim}
  \end{quote}
  and so on.
\item Did you actually \emph{need} \csx{include}?~--- if not, you can
  replace \csx{include} by \csx{input} throughout.  (This only works
  if you don't need \csx{includeonly}.)
\item You \emph{could} patch your system's \File{texmf.cnf}~--- if you
  know what you're doing, the error message should be enough of a
  hint; this action is definitely not recommended, and is left to
  those who can ``help themselves'' in this respect.
\end{enumerate}
\LastEdit*{2012-02-13}

\Question[Q-expl3-old]{Support package \Package{expl3} too old}

Some (rather modern) packages are written using the % ! line break
\Qref*{\latex{}3 programming environment}{Q-LaTeX3}.  Since \latex{}3
is still under development, the author cannot reliably guess what
version of \latex{}3 the user has installed, and whether that version
is adequate for the current package.  Thus the package's code often
checks the user's installation, and complains if it's older than the
author's installation at time of testing.  The error message is:
\begin{quote}
\begin{verbatim}
! Support package expl3 too old.
\end{verbatim}
\end{quote}
The ``additional help'' tells you the solution: update your \latex{}3
installation.  The relevant things are \Package{l3kernel} (the
programming environment, which contains the \Package{expl3} mentioned
in the error message) and \Package{l3packages} (\latex{}3 constructs
such as command definitions).

While this sounds a drastic remedy, it is no longer the major
undertaking it once was~--- if you are using a modern \tex{}
distribution that you installed yourself, ask it to update over the
internet; if that choice is not available, install from the
\extension{tds.zip} files available for both packages on \ctan{}.
\begin{ctanrefs}
\item[l3kernel \nothtml{\rmfamily}bundle]\CTANref{l3kernel}
\item[l3packages \nothtml{\rmfamily}bundle]\CTANref{l3packages}
\end{ctanrefs}
\LastEdit*{2013-02-20}