summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Pod/LaTeX.pm
blob: f4b1aaf97b9668f64e614a03ea5d5d5c169f4702 (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
package Pod::LaTeX;

=head1 NAME

Pod::LaTeX - Convert Pod data to formatted Latex

=head1 SYNOPSIS

  use Pod::LaTeX;
  my $parser = Pod::LaTeX->new ( );

  $parser->parse_from_filehandle;

  $parser->parse_from_file ('file.pod', 'file.tex');

=head1 DESCRIPTION

C<Pod::LaTeX> is a module to convert documentation in the Pod format
into Latex. The L<B<pod2latex>|pod2latex> X<pod2latex> command uses
this module for translation.

C<Pod::LaTeX> is a derived class from L<Pod::Select|Pod::Select>.

=cut


use strict;
require Pod::ParseUtils;
use base qw/ Pod::Select /;

# use Data::Dumper; # for debugging
use Carp;

use vars qw/ $VERSION %HTML_Escapes @LatexSections /;

$VERSION = '0.60';

# Definitions of =headN -> latex mapping
@LatexSections = (qw/
		  chapter
		  section
		  subsection
		  subsubsection
		  paragraph
		  subparagraph
		  /);

# Standard escape sequences converted to Latex.
# The Unicode name of each character is given in the comments.
# Complete LaTeX set added by Peter Acklam.

%HTML_Escapes = (
     'sol'    => '\textfractionsolidus{}',  # xxx - or should it be just '/'
     'verbar' => '|',

     # The stuff below is based on the information available at
     # http://www.w3.org/TR/html401/sgml/entities.html

     # All characters in the range 0xA0-0xFF of the ISO 8859-1 character set.
     # Several of these characters require the `textcomp' LaTeX package.
     'nbsp'   => q|~|,                     # 0xA0 - no-break space = non-breaking space
     'iexcl'  => q|\textexclamdown{}|,     # 0xA1 - inverted exclamation mark
     'cent'   => q|\textcent{}|,           # 0xA2 - cent sign
     'pound'  => q|\textsterling{}|,       # 0xA3 - pound sign
     'curren' => q|\textcurrency{}|,       # 0xA4 - currency sign
     'yen'    => q|\textyen{}|,            # 0xA5 - yen sign = yuan sign
     'brvbar' => q|\textbrokenbar{}|,      # 0xA6 - broken bar = broken vertical bar
     'sect'   => q|\textsection{}|,        # 0xA7 - section sign
     'uml'    => q|\textasciidieresis{}|,  # 0xA8 - diaeresis = spacing diaeresis
     'copy'   => q|\textcopyright{}|,      # 0xA9 - copyright sign
     'ordf'   => q|\textordfeminine{}|,    # 0xAA - feminine ordinal indicator
     'laquo'  => q|\guillemotleft{}|,      # 0xAB - left-pointing double angle quotation mark = left pointing guillemet
     'not'    => q|\textlnot{}|,           # 0xAC - not sign
     'shy'    => q|\-|,                    # 0xAD - soft hyphen = discretionary hyphen
     'reg'    => q|\textregistered{}|,     # 0xAE - registered sign = registered trade mark sign
     'macr'   => q|\textasciimacron{}|,    # 0xAF - macron = spacing macron = overline = APL overbar
     'deg'    => q|\textdegree{}|,         # 0xB0 - degree sign
     'plusmn' => q|\textpm{}|,             # 0xB1 - plus-minus sign = plus-or-minus sign
     'sup2'   => q|\texttwosuperior{}|,    # 0xB2 - superscript two = superscript digit two = squared
     'sup3'   => q|\textthreesuperior{}|,  # 0xB3 - superscript three = superscript digit three = cubed
     'acute'  => q|\textasciiacute{}|,     # 0xB4 - acute accent = spacing acute
     'micro'  => q|\textmu{}|,             # 0xB5 - micro sign
     'para'   => q|\textparagraph{}|,      # 0xB6 - pilcrow sign = paragraph sign
     'middot' => q|\textperiodcentered{}|, # 0xB7 - middle dot = Georgian comma = Greek middle dot
     'cedil'  => q|\c{}|,                  # 0xB8 - cedilla = spacing cedilla
     'sup1'   => q|\textonesuperior{}|,    # 0xB9 - superscript one = superscript digit one
     'ordm'   => q|\textordmasculine{}|,   # 0xBA - masculine ordinal indicator
     'raquo'  => q|\guillemotright{}|,     # 0xBB - right-pointing double angle quotation mark = right pointing guillemet
     'frac14' => q|\textonequarter{}|,     # 0xBC - vulgar fraction one quarter = fraction one quarter
     'frac12' => q|\textonehalf{}|,        # 0xBD - vulgar fraction one half = fraction one half
     'frac34' => q|\textthreequarters{}|,  # 0xBE - vulgar fraction three quarters = fraction three quarters
     'iquest' => q|\textquestiondown{}|,   # 0xBF - inverted question mark = turned question mark
     'Agrave' => q|\`A|,                   # 0xC0 - latin capital letter A with grave = latin capital letter A grave
     'Aacute' => q|\'A|,             # 0xC1 - latin capital letter A with acute
     'Acirc'  => q|\^A|,             # 0xC2 - latin capital letter A with circumflex
     'Atilde' => q|\~A|,             # 0xC3 - latin capital letter A with tilde
     'Auml'   => q|\"A|,             # 0xC4 - latin capital letter A with diaeresis
     'Aring'  => q|\AA{}|,           # 0xC5 - latin capital letter A with ring above = latin capital letter A ring
     'AElig'  => q|\AE{}|,           # 0xC6 - latin capital letter AE = latin capital ligature AE
     'Ccedil' => q|\c{C}|,           # 0xC7 - latin capital letter C with cedilla
     'Egrave' => q|\`E|,             # 0xC8 - latin capital letter E with grave
     'Eacute' => q|\'E|,             # 0xC9 - latin capital letter E with acute
     'Ecirc'  => q|\^E|,             # 0xCA - latin capital letter E with circumflex
     'Euml'   => q|\"E|,             # 0xCB - latin capital letter E with diaeresis
     'Igrave' => q|\`I|,             # 0xCC - latin capital letter I with grave
     'Iacute' => q|\'I|,             # 0xCD - latin capital letter I with acute
     'Icirc'  => q|\^I|,             # 0xCE - latin capital letter I with circumflex
     'Iuml'   => q|\"I|,             # 0xCF - latin capital letter I with diaeresis
     'ETH'    => q|\DH{}|,           # 0xD0 - latin capital letter ETH
     'Ntilde' => q|\~N|,             # 0xD1 - latin capital letter N with tilde
     'Ograve' => q|\`O|,             # 0xD2 - latin capital letter O with grave
     'Oacute' => q|\'O|,             # 0xD3 - latin capital letter O with acute
     'Ocirc'  => q|\^O|,             # 0xD4 - latin capital letter O with circumflex
     'Otilde' => q|\~O|,             # 0xD5 - latin capital letter O with tilde
     'Ouml'   => q|\"O|,             # 0xD6 - latin capital letter O with diaeresis
     'times'  => q|\texttimes{}|,    # 0xD7 - multiplication sign
     'Oslash' => q|\O{}|,            # 0xD8 - latin capital letter O with stroke = latin capital letter O slash
     'Ugrave' => q|\`U|,             # 0xD9 - latin capital letter U with grave
     'Uacute' => q|\'U|,             # 0xDA - latin capital letter U with acute
     'Ucirc'  => q|\^U|,             # 0xDB - latin capital letter U with circumflex
     'Uuml'   => q|\"U|,             # 0xDC - latin capital letter U with diaeresis
     'Yacute' => q|\'Y|,             # 0xDD - latin capital letter Y with acute
     'THORN'  => q|\TH{}|,           # 0xDE - latin capital letter THORN
     'szlig'  => q|\ss{}|,           # 0xDF - latin small letter sharp s = ess-zed
     'agrave' => q|\`a|,             # 0xE0 - latin small letter a with grave = latin small letter a grave
     'aacute' => q|\'a|,             # 0xE1 - latin small letter a with acute
     'acirc'  => q|\^a|,             # 0xE2 - latin small letter a with circumflex
     'atilde' => q|\~a|,             # 0xE3 - latin small letter a with tilde
     'auml'   => q|\"a|,             # 0xE4 - latin small letter a with diaeresis
     'aring'  => q|\aa{}|,           # 0xE5 - latin small letter a with ring above = latin small letter a ring
     'aelig'  => q|\ae{}|,           # 0xE6 - latin small letter ae = latin small ligature ae
     'ccedil' => q|\c{c}|,           # 0xE7 - latin small letter c with cedilla
     'egrave' => q|\`e|,             # 0xE8 - latin small letter e with grave
     'eacute' => q|\'e|,             # 0xE9 - latin small letter e with acute
     'ecirc'  => q|\^e|,             # 0xEA - latin small letter e with circumflex
     'euml'   => q|\"e|,             # 0xEB - latin small letter e with diaeresis
     'igrave' => q|\`i|,             # 0xEC - latin small letter i with grave
     'iacute' => q|\'i|,             # 0xED - latin small letter i with acute
     'icirc'  => q|\^i|,             # 0xEE - latin small letter i with circumflex
     'iuml'   => q|\"i|,             # 0xEF - latin small letter i with diaeresis
     'eth'    => q|\dh{}|,           # 0xF0 - latin small letter eth
     'ntilde' => q|\~n|,             # 0xF1 - latin small letter n with tilde
     'ograve' => q|\`o|,             # 0xF2 - latin small letter o with grave
     'oacute' => q|\'o|,             # 0xF3 - latin small letter o with acute
     'ocirc'  => q|\^o|,             # 0xF4 - latin small letter o with circumflex
     'otilde' => q|\~o|,             # 0xF5 - latin small letter o with tilde
     'ouml'   => q|\"o|,             # 0xF6 - latin small letter o with diaeresis
     'divide' => q|\textdiv{}|,      # 0xF7 - division sign
     'oslash' => q|\o{}|,            # 0xF8 - latin small letter o with stroke, = latin small letter o slash
     'ugrave' => q|\`u|,             # 0xF9 - latin small letter u with grave
     'uacute' => q|\'u|,             # 0xFA - latin small letter u with acute
     'ucirc'  => q|\^u|,             # 0xFB - latin small letter u with circumflex
     'uuml'   => q|\"u|,             # 0xFC - latin small letter u with diaeresis
     'yacute' => q|\'y|,             # 0xFD - latin small letter y with acute
     'thorn'  => q|\th{}|,           # 0xFE - latin small letter thorn
     'yuml'   => q|\"y|,             # 0xFF - latin small letter y with diaeresis

     # Latin Extended-B
     'fnof'   => q|\textflorin{}|,   # latin small f with hook = function = florin

     # Greek
     'Alpha'    => q|$\mathrm{A}$|,      # greek capital letter alpha
     'Beta'     => q|$\mathrm{B}$|,      # greek capital letter beta
     'Gamma'    => q|$\Gamma$|,          # greek capital letter gamma
     'Delta'    => q|$\Delta$|,          # greek capital letter delta
     'Epsilon'  => q|$\mathrm{E}$|,      # greek capital letter epsilon
     'Zeta'     => q|$\mathrm{Z}$|,      # greek capital letter zeta
     'Eta'      => q|$\mathrm{H}$|,      # greek capital letter eta
     'Theta'    => q|$\Theta$|,          # greek capital letter theta
     'Iota'     => q|$\mathrm{I}$|,      # greek capital letter iota
     'Kappa'    => q|$\mathrm{K}$|,      # greek capital letter kappa
     'Lambda'   => q|$\Lambda$|,         # greek capital letter lambda
     'Mu'       => q|$\mathrm{M}$|,      # greek capital letter mu
     'Nu'       => q|$\mathrm{N}$|,      # greek capital letter nu
     'Xi'       => q|$\Xi$|,             # greek capital letter xi
     'Omicron'  => q|$\mathrm{O}$|,      # greek capital letter omicron
     'Pi'       => q|$\Pi$|,             # greek capital letter pi
     'Rho'      => q|$\mathrm{R}$|,      # greek capital letter rho
     'Sigma'    => q|$\Sigma$|,          # greek capital letter sigma
     'Tau'      => q|$\mathrm{T}$|,      # greek capital letter tau
     'Upsilon'  => q|$\Upsilon$|,        # greek capital letter upsilon
     'Phi'      => q|$\Phi$|,            # greek capital letter phi
     'Chi'      => q|$\mathrm{X}$|,      # greek capital letter chi
     'Psi'      => q|$\Psi$|,            # greek capital letter psi
     'Omega'    => q|$\Omega$|,          # greek capital letter omega

     'alpha'    => q|$\alpha$|,          # greek small letter alpha
     'beta'     => q|$\beta$|,           # greek small letter beta
     'gamma'    => q|$\gamma$|,          # greek small letter gamma
     'delta'    => q|$\delta$|,          # greek small letter delta
     'epsilon'  => q|$\epsilon$|,        # greek small letter epsilon
     'zeta'     => q|$\zeta$|,           # greek small letter zeta
     'eta'      => q|$\eta$|,            # greek small letter eta
     'theta'    => q|$\theta$|,          # greek small letter theta
     'iota'     => q|$\iota$|,           # greek small letter iota
     'kappa'    => q|$\kappa$|,          # greek small letter kappa
     'lambda'   => q|$\lambda$|,         # greek small letter lambda
     'mu'       => q|$\mu$|,             # greek small letter mu
     'nu'       => q|$\nu$|,             # greek small letter nu
     'xi'       => q|$\xi$|,             # greek small letter xi
     'omicron'  => q|$o$|,               # greek small letter omicron
     'pi'       => q|$\pi$|,             # greek small letter pi
     'rho'      => q|$\rho$|,            # greek small letter rho
#    'sigmaf'   => q||,                  # greek small letter final sigma
     'sigma'    => q|$\sigma$|,          # greek small letter sigma
     'tau'      => q|$\tau$|,            # greek small letter tau
     'upsilon'  => q|$\upsilon$|,        # greek small letter upsilon
     'phi'      => q|$\phi$|,            # greek small letter phi
     'chi'      => q|$\chi$|,            # greek small letter chi
     'psi'      => q|$\psi$|,            # greek small letter psi
     'omega'    => q|$\omega$|,          # greek small letter omega
#    'thetasym' => q||,                  # greek small letter theta symbol
#    'upsih'    => q||,                  # greek upsilon with hook symbol
#    'piv'      => q||,                  # greek pi symbol

     # General Punctuation
     'bull'     => q|\textbullet{}|,     # bullet = black small circle
     # bullet is NOT the same as bullet operator
     'hellip'   => q|\textellipsis{}|,           # horizontal ellipsis = three dot leader
     'prime'    => q|\textquotesingle{}|,        # prime = minutes = feet
     'Prime'    => q|\textquotedbl{}|,           # double prime = seconds = inches
     'oline'    => q|\textasciimacron{}|,        # overline = spacing overscore
     'frasl'    => q|\textfractionsolidus{}|,    # fraction slash

     # Letterlike Symbols
     'weierp'   => q|$\wp$|,                     # script capital P = power set = Weierstrass p
     'image'    => q|$\Re$|,                     # blackletter capital I = imaginary part
     'real'     => q|$\Im$|,                     # blackletter capital R = real part symbol
     'trade'    => q|\texttrademark{}|,          # trade mark sign
#    'alefsym'  => q||,                          # alef symbol = first transfinite cardinal
     # alef symbol is NOT the same as hebrew letter alef, although the same
     # glyph could be used to depict both characters

     # Arrows
     'larr'     => q|\textleftarrow{}|,          # leftwards arrow
     'uarr'     => q|\textuparrow{}|,            # upwards arrow
     'rarr'     => q|\textrightarrow{}|,         # rightwards arrow
     'darr'     => q|\textdownarrow{}|,          # downwards arrow
     'harr'     => q|$\leftrightarrow$|,         # left right arrow
#    'crarr'    => q||,                          # downwards arrow with corner leftwards = carriage return
     'lArr'     => q|$\Leftarrow$|,              # leftwards double arrow
     # ISO 10646 does not say that lArr is the same as the 'is implied by'
     # arrow but also does not have any other character for that function. So
     # lArr can be used for 'is implied by' as ISOtech suggests
     'uArr'     => q|$\Uparrow$|,                # upwards double arrow
     'rArr'     => q|$\Rightarrow$|,             # rightwards double arrow
     # ISO 10646 does not say this is the 'implies' character but does not
     # have another character with this function so ? rArr can be used for
     # 'implies' as ISOtech suggests
     'dArr'     => q|$\Downarrow$|,              # downwards double arrow
     'hArr'     => q|$\Leftrightarrow$|,         # left right double arrow

     # Mathematical Operators.
     # Some of these require the `amssymb' package.
     'forall'   => q|$\forall$|,                 # for all
     'part'     => q|$\partial$|,                # partial differential
     'exist'    => q|$\exists$|,                 # there exists
     'empty'    => q|$\emptyset$|,               # empty set = null set = diameter
     'nabla'    => q|$\nabla$|,                  # nabla = backward difference
     'isin'     => q|$\in$|,                     # element of
     'notin'    => q|$\notin$|,                  # not an element of
     'ni'       => q|$\ni$|,                     # contains as member
     'prod'     => q|$\prod$|,                   # n-ary product = product sign
     # prod is NOT the same character as 'greek capital letter pi' though the
     # same glyph might be used for both
     'sum'      => q|$\sum$|,                    # n-ary summation
     # sum is NOT the same character as 'greek capital letter sigma' though
     # the same glyph might be used for both
     'minus'    => q|$-$|,                       # minus sign
     'lowast'   => q|$\ast$|,                    # asterisk operator
     'radic'    => q|$\surd$|,                   # square root = radical sign
     'prop'     => q|$\propto$|,                 # proportional to
     'infin'    => q|$\infty$|,                  # infinity
     'ang'      => q|$\angle$|,                  # angle
     'and'      => q|$\wedge$|,                  # logical and = wedge
     'or'       => q|$\vee$|,                    # logical or = vee
     'cap'      => q|$\cap$|,                    # intersection = cap
     'cup'      => q|$\cup$|,                    # union = cup
     'int'      => q|$\int$|,                    # integral
     'there4'   => q|$\therefore$|,              # therefore
     'sim'      => q|$\sim$|,                    # tilde operator = varies with = similar to
     # tilde operator is NOT the same character as the tilde
     'cong'     => q|$\cong$|,                   # approximately equal to
     'asymp'    => q|$\asymp$|,                  # almost equal to = asymptotic to
     'ne'       => q|$\neq$|,                    # not equal to
     'equiv'    => q|$\equiv$|,                  # identical to
     'le'       => q|$\leq$|,                    # less-than or equal to
     'ge'       => q|$\geq$|,                    # greater-than or equal to
     'sub'      => q|$\subset$|,                 # subset of
     'sup'      => q|$\supset$|,                 # superset of
     # note that nsup, 'not a superset of' is not covered by the Symbol font
     # encoding and is not included.
     'nsub'     => q|$\not\subset$|,             # not a subset of
     'sube'     => q|$\subseteq$|,               # subset of or equal to
     'supe'     => q|$\supseteq$|,               # superset of or equal to
     'oplus'    => q|$\oplus$|,                  # circled plus = direct sum
     'otimes'   => q|$\otimes$|,                 # circled times = vector product
     'perp'     => q|$\perp$|,                   # up tack = orthogonal to = perpendicular
     'sdot'     => q|$\cdot$|,                   # dot operator
     # dot operator is NOT the same character as middle dot

     # Miscellaneous Technical
     'lceil'    => q|$\lceil$|,                  # left ceiling = apl upstile
     'rceil'    => q|$\rceil$|,                  # right ceiling
     'lfloor'   => q|$\lfloor$|,                 # left floor = apl downstile
     'rfloor'   => q|$\rfloor$|,                 # right floor
     'lang'     => q|$\langle$|,                 # left-pointing angle bracket = bra
     # lang is NOT the same character as 'less than' or 'single left-pointing
     # angle quotation mark'
     'rang'     => q|$\rangle$|,                 # right-pointing angle bracket = ket
     # rang is NOT the same character as 'greater than' or 'single
     # right-pointing angle quotation mark'

     # Geometric Shapes
     'loz'      => q|$\lozenge$|,                # lozenge

     # Miscellaneous Symbols
     'spades'   => q|$\spadesuit$|,              # black spade suit
     'clubs'    => q|$\clubsuit$|,               # black club suit = shamrock
     'hearts'   => q|$\heartsuit$|,              # black heart suit = valentine
     'diams'    => q|$\diamondsuit$|,            # black diamond suit

     # C0 Controls and Basic Latin
     'quot'     => q|"|,                         # quotation mark = APL quote ["]
     'amp'      => q|\&|,                        # ampersand
     'lt'       => q|<|,                         # less-than sign
     'gt'       => q|>|,                         # greater-than sign
     'OElig'    => q|\OE{}|,                     # latin capital ligature OE
     'oelig'    => q|\oe{}|,                     # latin small ligature oe
     'Scaron'   => q|\v{S}|,                     # latin capital letter S with caron
     'scaron'   => q|\v{s}|,                     # latin small letter s with caron
     'Yuml'     => q|\"Y|,                       # latin capital letter Y with diaeresis
     'circ'     => q|\textasciicircum{}|,        # modifier letter circumflex accent
     'tilde'    => q|\textasciitilde{}|,         # small tilde
     'ensp'     => q|\phantom{n}|,               # en space
     'emsp'     => q|\hspace{1em}|,              # em space
     'thinsp'   => q|\,|,                        # thin space
     'zwnj'     => q|{}|,                        # zero width non-joiner
#    'zwj'      => q||,                          # zero width joiner
#    'lrm'      => q||,                          # left-to-right mark
#    'rlm'      => q||,                          # right-to-left mark
     'ndash'    => q|--|,                        # en dash
     'mdash'    => q|---|,                       # em dash
     'lsquo'    => q|\textquoteleft{}|,          # left single quotation mark
     'rsquo'    => q|\textquoteright{}|,         # right single quotation mark
     'sbquo'    => q|\quotesinglbase{}|,         # single low-9 quotation mark
     'ldquo'    => q|\textquotedblleft{}|,       # left double quotation mark
     'rdquo'    => q|\textquotedblright{}|,      # right double quotation mark
     'bdquo'    => q|\quotedblbase{}|,           # double low-9 quotation mark
     'dagger'   => q|\textdagger{}|,             # dagger
     'Dagger'   => q|\textdaggerdbl{}|,          # double dagger
     'permil'   => q|\textperthousand{}|,        # per mille sign
     'lsaquo'   => q|\guilsinglleft{}|,          # single left-pointing angle quotation mark
     'rsaquo'   => q|\guilsinglright{}|,         # single right-pointing angle quotation mark
     'euro'     => q|\texteuro{}|,               # euro sign
);

=head1 OBJECT METHODS

The following methods are provided in this module. Methods inherited
from C<Pod::Select> are not described in the public interface.

=over 4

=begin __PRIVATE__

=item C<initialize>

Initialise the object. This method is subclassed from C<Pod::Parser>.
The base class method is invoked. This method defines the default
behaviour of the object unless overridden by supplying arguments to
the constructor. 

Internal settings are defaulted as well as the public instance data.
Internal hash values are accessed directly (rather than through
a method) and start with an underscore.

This method should not be invoked by the user directly.

=end __PRIVATE__

=cut



#   - An array for nested lists

# Arguments have already been read by this point

sub initialize {
  my $self = shift;

  # print Dumper($self);

  # Internals
  $self->{_Lists} = [];             # For nested lists
  $self->{_suppress_all_para}  = 0; # For =begin blocks
  $self->{_dont_modify_any_para}=0; # For =begin blocks
  $self->{_CURRENT_HEAD1}   = '';   # Name of current HEAD1 section

  # Options - only initialise if not already set

  # Cause the '=head1 NAME' field to be treated specially
  # The contents of the NAME paragraph will be converted
  # to a section title. All subsequent =head1 will be converted
  # to =head2 and down. Will not affect =head1's prior to NAME 
  # Assumes:  'Module - purpose' format
  # Also creates a purpose field
  # The name is used for Labeling of the subsequent subsections
  $self->{ReplaceNAMEwithSection} = 0
    unless exists $self->{ReplaceNAMEwithSection};
  $self->{AddPreamble}      = 1    # make full latex document
    unless exists $self->{AddPreamble};
  $self->{StartWithNewPage} = 0    # Start new page for pod section
    unless exists $self->{StartWithNewPage};
  $self->{TableOfContents}  = 0    # Add table of contents
    unless exists $self->{TableOfContents};  # only relevant if AddPreamble=1
   $self->{AddPostamble}     = 1          # Add closing latex code at end
    unless exists $self->{AddPostamble}; #  effectively end{document} and index
  $self->{MakeIndex}        = 1         # Add index (only relevant AddPostamble
    unless exists $self->{MakeIndex};   # and AddPreamble)

  $self->{UniqueLabels}     = 1          # Use label unique for each pod
    unless exists $self->{UniqueLabels}; # either based on the filename
                                         # or supplied

  # Control the level of =head1. default is \section
  # 
  $self->{Head1Level}     = 1   # Offset in latex sections
    unless exists $self->{Head1Level}; # 0 is chapter, 2 is subsection

  # Control at which level numbering of sections is turned off
  # ie subsection becomes subsection*
  # The numbering is relative to the latex sectioning commands
  # and is independent of Pod heading level
  # default is to number \section but not \subsection
  $self->{LevelNoNum} = 2
    unless exists $self->{LevelNoNum};

  # Label to be used as prefix to all internal section names
  # If not defined will attempt to derive it from the filename
  # This can not happen when running parse_from_filehandle though
  # hence the ability to set the label externally
  # The label could then be Pod::Parser_DESCRIPTION or somesuch

  $self->{Label}            = undef # label to be used as prefix
    unless exists $self->{Label};   # to all internal section names

  # These allow the caller to add arbitrary latex code to
  # start and end of document. AddPreamble and AddPostamble are ignored
  # if these are set.
  # Also MakeIndex and TableOfContents are also ignored.
  $self->{UserPreamble}     = undef # User supplied start (AddPreamble =1)
    unless exists $self->{Label};
  $self->{UserPostamble}    = undef # Use supplied end    (AddPostamble=1)
    unless exists $self->{Label};

  # Run base initialize
  $self->SUPER::initialize;

}

=back

=head2 Data Accessors

The following methods are provided for accessing instance data. These
methods should be used for accessing configuration parameters rather
than assuming the object is a hash.

Default values can be supplied by using these names as keys to a hash
of arguments when using the C<new()> constructor.

=over 4

=item B<AddPreamble>

Logical to control whether a C<latex> preamble is to be written.
If true, a valid C<latex> preamble is written before the pod data is written.
This is similar to:

  \documentclass{article}
  \usepackage[T1]{fontenc}
  \usepackage{textcomp}
  \begin{document}

but will be more complicated if table of contents and indexing are required.
Can be used to set or retrieve the current value.

  $add = $parser->AddPreamble();
  $parser->AddPreamble(1);

If used in conjunction with C<AddPostamble> a full latex document will
be written that could be immediately processed by C<latex>.

For some pod escapes it may be necessary to include the amsmath
package. This is not yet added to the preamble automatically.

=cut

sub AddPreamble {
   my $self = shift;
   if (@_) {
     $self->{AddPreamble} = shift;
   }
   return $self->{AddPreamble};
}

=item B<AddPostamble>

Logical to control whether a standard C<latex> ending is written to the output
file after the document has been processed.
In its simplest form this is simply:

  \end{document}

but can be more complicated if a index is required.
Can be used to set or retrieve the current value.

  $add = $parser->AddPostamble();
  $parser->AddPostamble(1);

If used in conjunction with C<AddPreaamble> a full latex document will
be written that could be immediately processed by C<latex>.

=cut

sub AddPostamble {
   my $self = shift;
   if (@_) {
     $self->{AddPostamble} = shift;
   }
   return $self->{AddPostamble};
}

=item B<Head1Level>

The C<latex> sectioning level that should be used to correspond to
a pod C<=head1> directive. This can be used, for example, to turn
a C<=head1> into a C<latex> C<subsection>. This should hold a number
corresponding to the required position in an array containing the
following elements:

 [0] chapter
 [1] section
 [2] subsection
 [3] subsubsection
 [4] paragraph
 [5] subparagraph

Can be used to set or retrieve the current value:

  $parser->Head1Level(2);
  $sect = $parser->Head1Level;

Setting this number too high can result in sections that may not be reproducible
in the expected way. For example, setting this to 4 would imply that C<=head3>
do not have a corresponding C<latex> section (C<=head1> would correspond to
a C<paragraph>).

A check is made to ensure that the supplied value is an integer in the
range 0 to 5.

Default is for a value of 1 (i.e. a C<section>).

=cut

sub Head1Level {
   my $self = shift;
   if (@_) {
     my $arg = shift;
     if ($arg =~ /^\d$/ && $arg <= $#LatexSections) {
       $self->{Head1Level} = $arg;
     } else {
       carp "Head1Level supplied ($arg) must be integer in range 0 to ".$#LatexSections . "- Ignoring\n";
     }
   }
   return $self->{Head1Level};
}

=item B<Label>

This is the label that is prefixed to all C<latex> label and index
entries to make them unique. In general, pods have similarly titled
sections (NAME, DESCRIPTION etc) and a C<latex> label will be multiply
defined if more than one pod document is to be included in a single
C<latex> file. To overcome this, this label is prefixed to a label
whenever a label is required (joined with an underscore) or to an
index entry (joined by an exclamation mark which is the normal index
separator). For example, C<\label{text}> becomes C<\label{Label_text}>.

Can be used to set or retrieve the current value:

  $label = $parser->Label;
  $parser->Label($label);

This label is only used if C<UniqueLabels> is true.
Its value is set automatically from the C<NAME> field
if C<ReplaceNAMEwithSection> is true. If this is not the case
it must be set manually before starting the parse.

Default value is C<undef>.

=cut

sub Label {
   my $self = shift;
   if (@_) {
     $self->{Label} = shift;
   }
   return $self->{Label};
}

=item B<LevelNoNum>

Control the point at which C<latex> section numbering is turned off.
For example, this can be used to make sure that C<latex> sections
are numbered but subsections are not.

Can be used to set or retrieve the current value:

  $lev = $parser->LevelNoNum;
  $parser->LevelNoNum(2);

The argument must be an integer between 0 and 5 and is the same as the
number described in C<Head1Level> method description. The number has
nothing to do with the pod heading number, only the C<latex> sectioning.

Default is 2. (i.e. C<latex> subsections are written as C<subsection*>
but sections are numbered).

=cut

sub LevelNoNum {
   my $self = shift;
   if (@_) {
     $self->{LevelNoNum} = shift;
   }
   return $self->{LevelNoNum};
}

=item B<MakeIndex>

Controls whether C<latex> commands for creating an index are to be inserted
into the preamble and postamble

  $makeindex = $parser->MakeIndex;
  $parser->MakeIndex(0);

Irrelevant if both C<AddPreamble> and C<AddPostamble> are false (or equivalently,
C<UserPreamble> and C<UserPostamble> are set).

Default is for an index to be created.

=cut

sub MakeIndex {
   my $self = shift;
   if (@_) {
     $self->{MakeIndex} = shift;
   }
   return $self->{MakeIndex};
}

=item B<ReplaceNAMEwithSection>

This controls whether the C<NAME> section in the pod is to be translated
literally or converted to a slightly modified output where the section
name is the pod name rather than "NAME".

If true, the pod segment

  =head1 NAME

  pod::name - purpose

  =head1 SYNOPSIS

is converted to the C<latex>

  \section{pod::name\label{pod_name}\index{pod::name}}

  Purpose

  \subsection*{SYNOPSIS\label{pod_name_SYNOPSIS}%
               \index{pod::name!SYNOPSIS}}

(dependent on the value of C<Head1Level> and C<LevelNoNum>). Note that
subsequent C<head1> directives translate to subsections rather than
sections and that the labels and index now include the pod name (dependent
on the value of C<UniqueLabels>).

The C<Label> is set from the pod name regardless of any current value
of C<Label>.

  $mod = $parser->ReplaceNAMEwithSection;
  $parser->ReplaceNAMEwithSection(0);

Default is to translate the pod literally.

=cut

sub ReplaceNAMEwithSection {
   my $self = shift;
   if (@_) {
     $self->{ReplaceNAMEwithSection} = shift;
   }
   return $self->{ReplaceNAMEwithSection};
}

=item B<StartWithNewPage>

If true, each pod translation will begin with a C<latex>
C<\clearpage>.

  $parser->StartWithNewPage(1);
  $newpage = $parser->StartWithNewPage;

Default is false.

=cut

sub StartWithNewPage {
   my $self = shift;
   if (@_) {
     $self->{StartWithNewPage} = shift;
   }
   return $self->{StartWithNewPage};
}

=item B<TableOfContents>

If true, a table of contents will be created.
Irrelevant if C<AddPreamble> is false or C<UserPreamble>
is set.

  $toc = $parser->TableOfContents;
  $parser->TableOfContents(1);

Default is false.

=cut

sub TableOfContents {
   my $self = shift;
   if (@_) {
     $self->{TableOfContents} = shift;
   }
   return $self->{TableOfContents};
}

=item B<UniqueLabels>

If true, the translator will attempt to make sure that
each C<latex> label or index entry will be uniquely identified
by prefixing the contents of C<Label>. This allows
multiple documents to be combined without clashing 
common labels such as C<DESCRIPTION> and C<SYNOPSIS>

  $parser->UniqueLabels(1);
  $unq = $parser->UniqueLabels;

Default is true.

=cut

sub UniqueLabels {
   my $self = shift;
   if (@_) {
     $self->{UniqueLabels} = shift;
   }
   return $self->{UniqueLabels};
}

=item B<UserPreamble>

User supplied C<latex> preamble. Added before the pod translation
data. 

If set, the contents will be prepended to the output file before the translated 
data regardless of the value of C<AddPreamble>.
C<MakeIndex> and C<TableOfContents> will also be ignored.

=cut

sub UserPreamble {
   my $self = shift;
   if (@_) {
     $self->{UserPreamble} = shift;
   }
   return $self->{UserPreamble};
}

=item B<UserPostamble>

User supplied C<latex> postamble. Added after the pod translation
data. 

If set, the contents will be prepended to the output file after the translated 
data regardless of the value of C<AddPostamble>.
C<MakeIndex> will also be ignored.

=cut

sub UserPostamble {
   my $self = shift;
   if (@_) {
     $self->{UserPostamble} = shift;
   }
   return $self->{UserPostamble};
}

=begin __PRIVATE__

=item B<Lists>

Contains details of the currently active lists.
  The array contains C<Pod::List> objects. A new C<Pod::List>
object is created each time a list is encountered and it is
pushed onto this stack. When the list context ends, it 
is popped from the stack. The array will be empty if no
lists are active.

Returns array of list information in list context
Returns array ref in scalar context

=cut



sub lists {
  my $self = shift;
  return @{ $self->{_Lists} } if wantarray();
  return $self->{_Lists};
}

=end __PRIVATE__

=back

=begin __PRIVATE__

=head2 Subclassed methods

The following methods override methods provided in the C<Pod::Select>
base class. See C<Pod::Parser> and C<Pod::Select> for more information
on what these methods require.

=over 4

=cut

######### END ACCESSORS ###################

# Opening pod

=item B<begin_pod>

Writes the C<latex> preamble if requested. Only writes something
if AddPreamble is true. Writes a standard header unless a UserPreamble
is defined.

=cut

sub begin_pod {
  my $self = shift;

  # Get the pod identification
  # This should really come from the '=head1 NAME' paragraph

  my $infile = $self->input_file;
  my $class = ref($self);
  my $date = gmtime(time);

  # Comment message to say where this came from
  my $comment = << "__TEX_COMMENT__";
%%  Latex generated from POD in document $infile
%%  Using the perl module $class
%%  Converted on $date
__TEX_COMMENT__

  # Write the preamble
  # If the caller has supplied one then we just use that

  my $preamble = '';

  if ($self->AddPreamble) {

    if (defined $self->UserPreamble) {

      $preamble = $self->UserPreamble;

      # Add the description of where this came from
      $preamble .=  "\n$comment\n%%  Preamble supplied by user.\n\n";

    } else {

      # Write our own preamble

      # Code to initialise index making
      # Use an array so that we can prepend comment if required
      my @makeidx = (
		     '\usepackage{makeidx}',
		     '\makeindex',
		    );

      unless ($self->MakeIndex) {
	foreach (@makeidx) {
	  $_ = '%% ' . $_;
	}
      }
      my $makeindex = join("\n",@makeidx) . "\n";

      # Table of contents
      my $tableofcontents = '\tableofcontents';

      $tableofcontents = '%% ' . $tableofcontents
	unless $self->TableOfContents;

      # Roll our own
      $preamble = << "__TEX_HEADER__";
\\documentclass{article}
\\usepackage[T1]{fontenc}
\\usepackage{textcomp}

$comment

$makeindex

\\begin{document}

$tableofcontents

__TEX_HEADER__

    }
  }

  # Write the header (blank if none)
  $self->_output($preamble);

  # Start on new page if requested
  $self->_output("\\clearpage\n") if $self->StartWithNewPage;

}


=item B<end_pod>

Write the closing C<latex> code. Only writes something if AddPostamble
is true. Writes a standard header unless a UserPostamble is defined.

=cut

sub end_pod {
  my $self = shift;

  # End string
  my $end = '';

  # Use the user version of the postamble if defined
  if ($self->AddPostamble) {

    if (defined $self->UserPostamble) {
      $end = $self->UserPostamble;

    } else {

      # Check for index
      my $makeindex = '\printindex';

      $makeindex = '%% '. $makeindex  unless $self->MakeIndex;

      $end = "$makeindex\n\n\\end{document}\n";
    }
  }

  $self->_output($end);

}

=item B<command>

Process basic pod commands.

=cut

sub command {
  my $self = shift;
  my ($command, $paragraph, $line_num, $parobj) = @_;

  # return if we dont care
  return if $command eq 'pod';

  # Store a copy of the raw text in case we are in a =for
  # block and need to preserve the existing latex
  my $rawpara = $paragraph;

  # Do the latex escapes
  $paragraph = $self->_replace_special_chars($paragraph);

  # Interpolate pod sequences in paragraph
  $paragraph = $self->interpolate($paragraph, $line_num);
  $paragraph =~ s/\s+$//;

  # Replace characters that can only be done after 
  # interpolation of interior sequences
  $paragraph = $self->_replace_special_chars_late($paragraph);

  # Now run the command
  if ($command eq 'over') {

    $self->begin_list($paragraph, $line_num);

  } elsif ($command eq 'item') {

    $self->add_item($paragraph, $line_num);

  } elsif ($command eq 'back') {

    $self->end_list($line_num);

  } elsif ($command eq 'head1') {

    # Store the name of the section
    $self->{_CURRENT_HEAD1} = $paragraph;

    # Print it
    $self->head(1, $paragraph, $parobj);

  } elsif ($command eq 'head2') {

    $self->head(2, $paragraph, $parobj);

  } elsif ($command eq 'head3') {

    $self->head(3, $paragraph, $parobj);

  } elsif ($command eq 'head4') {

    $self->head(4, $paragraph, $parobj);

  } elsif ($command eq 'head5') {

    $self->head(5, $paragraph, $parobj);

  } elsif ($command eq 'head6') {

    $self->head(6, $paragraph, $parobj);

  } elsif ($command eq 'begin') {

    # pass through if latex
    if ($paragraph =~ /^latex/i) {
      # Make sure that subsequent paragraphs are not modfied before printing
      $self->{_dont_modify_any_para} = 1;

    } else {
      # Suppress all subsequent paragraphs unless 
      # it is explicitly intended for latex
      $self->{_suppress_all_para} = 1;
    }

  } elsif ($command eq 'for') {

    # =for latex
    #   some latex

    # With =for we will get the text for the full paragraph
    # as well as the format name.
    # We do not get an additional paragraph later on. The next
    # paragraph is not governed by the =for

    # The first line contains the format and the rest is the
    # raw code.
    my ($format, $chunk) = split(/\n/, $rawpara, 2);

    # If we have got some latex code print it out immediately
    # unmodified. Else do nothing.
    if ($format =~ /^latex/i) {
      # Make sure that next paragraph is not modfied before printing
      $self->_output( $chunk );

    }

  } elsif ($command eq 'end') {

    # Reset suppression
    $self->{_suppress_all_para} = 0;
    $self->{_dont_modify_any_para} = 0;

  } elsif ($command eq 'pod') {

    # Do nothing

  } else {
    carp "Command $command not recognised at line $line_num\n";
  }

}

=item B<verbatim>

Verbatim text

=cut

sub verbatim {
  my $self = shift;
  my ($paragraph, $line_num, $parobj) = @_;

  # Expand paragraph unless in =begin block
  if ($self->{_dont_modify_any_para}) {
    # Just print as is
    $self->_output($paragraph);

  } else {

    return if $paragraph =~ /^\s+$/;

    # Clean trailing space
    $paragraph =~ s/\s+$//;

    # Clean tabs. Routine taken from Tabs.pm
    # by David Muir Sharnoff muir@idiom.com,
    # slightly modified by hsmyers@sdragons.com 10/22/01
    my @l = split("\n",$paragraph);
    foreach (@l) {
      1 while s/(^|\n)([^\t\n]*)(\t+)/
	$1. $2 . (" " x 
		  (8 * length($3)
		   - (length($2) % 8)))
	  /sex;
    }
    $paragraph = join("\n",@l);
    # End of change.



    $self->_output('\begin{verbatim}' . "\n$paragraph\n". '\end{verbatim}'."\n");
  }
}

=item B<textblock>

Plain text paragraph.

=cut

sub textblock {
  my $self = shift;
  my ($paragraph, $line_num, $parobj) = @_;

  # print Dumper($self);

  # Expand paragraph unless in =begin block
  if ($self->{_dont_modify_any_para}) {
    # Just print as is
    $self->_output($paragraph);

    return;
  }


  # Escape latex special characters
  $paragraph = $self->_replace_special_chars($paragraph);

  # Interpolate interior sequences
  my $expansion = $self->interpolate($paragraph, $line_num);
  $expansion =~ s/\s+$//;

  # Escape special characters that can not be done earlier
  $expansion = $self->_replace_special_chars_late($expansion);

  # If we are replacing 'head1 NAME' with a section
  # we need to look in the paragraph and rewrite things
  # Need to make sure this is called only on the first paragraph
  # following 'head1 NAME' and not on subsequent paragraphs that may be
  # present.
  if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection()) {

    # Strip white space from start and end
    $paragraph =~ s/^\s+//;
    $paragraph =~ s/\s$//;

    # Split the string into 2 parts
    my ($name, $purpose) = split(/\s+-\s+/, $expansion,2);

    # Now prevent this from triggering until a new head1 NAME is set
    $self->{_CURRENT_HEAD1} = '_NAME';

    # Might want to clear the Label() before doing this (CHECK)

    # Print the heading
    $self->head(1, $name, $parobj);

    # Set the labeling in case we want unique names later
    $self->Label( $self->_create_label( $name, 1 ) );

    # Raise the Head1Level by one so that subsequent =head1 appear
    # as subsections of the main name section unless we are already
    # at maximum [Head1Level() could check this itself - CHECK]
    $self->Head1Level( $self->Head1Level() + 1)
      unless $self->Head1Level == $#LatexSections;

    # Now write out the new latex paragraph
    $purpose = ucfirst($purpose);
    $self->_output("\n\n$purpose\n\n");

  } else {
    # Just write the output
    $self->_output("\n\n$expansion\n\n");
  }

}

=item B<interior_sequence>

Interior sequence expansion

=cut

sub interior_sequence {
  my $self = shift;

  my ($seq_command, $seq_argument, $pod_seq) = @_;

  if ($seq_command eq 'B') {
    return "\\textbf{$seq_argument}";

  } elsif ($seq_command eq 'I') {
    return "\\textit{$seq_argument}";

  } elsif ($seq_command eq 'E') {

    # If it is simply a number
    if ($seq_argument =~ /^\d+$/) {
      return chr($seq_argument);
    # Look up escape in hash table
    } elsif (exists $HTML_Escapes{$seq_argument}) {
      return $HTML_Escapes{$seq_argument};

    } else {
      my ($file, $line) = $pod_seq->file_line();
      warn "Escape sequence $seq_argument not recognised at line $line of file $file\n";
      return;
    }

  } elsif ($seq_command eq 'Z') {

    # Zero width space
    return '{}';

  } elsif ($seq_command eq 'C') {
    return "\\texttt{$seq_argument}";

  } elsif ($seq_command eq 'F') {
    return "\\emph{$seq_argument}";

  } elsif ($seq_command eq 'S') {
    # non breakable spaces
    my $nbsp = '~';

    $seq_argument =~ s/\s/$nbsp/g;
    return $seq_argument;

  } elsif ($seq_command eq 'L') {
    my $link = new Pod::Hyperlink($seq_argument);

    # undef on failure
    unless (defined $link) {
      carp $@;
      return;
    }

    # Handle internal links differently
    my $type = $link->type;
    my $page = $link->page;

    if ($type eq 'section' && $page eq '') {
      # Use internal latex reference 
      my $node = $link->node;

      # Convert to a label
      $node = $self->_create_label($node);

      return "\\S\\ref{$node}";

    } else {
      # Use default markup for external references
      # (although Starlink would use \xlabel)
      my $markup = $link->markup;
      my ($file, $line) = $pod_seq->file_line();

      return $self->interpolate($link->markup, $line);
    }



  } elsif ($seq_command eq 'P') {
    # Special markup for Pod::Hyperlink
    # Replace :: with / - but not sure if I want to do this
    # any more.
    my $link = $seq_argument;
    $link =~ s|::|/|g;

    my $ref = "\\emph{$seq_argument}";
    return $ref;

  } elsif ($seq_command eq 'Q') {
    # Special markup for Pod::Hyperlink
    return "\\textsf{$seq_argument}";

  } elsif ($seq_command eq 'X') {
    # Index entries

    # use \index command
    # I will let '!' go through for now
    # not sure how sub categories are handled in X<>
    my $index = $self->_create_index($seq_argument);
    return "\\index{$index}\n";

  } else {
    carp "Unknown sequence $seq_command<$seq_argument>";
  }

}

=back

=head2 List Methods

Methods used to handle lists.

=over 4

=item B<begin_list>

Called when a new list is found (via the C<over> directive).
Creates a new C<Pod::List> object and stores it on the 
list stack.

  $parser->begin_list($indent, $line_num);

=cut

sub begin_list {
  my $self = shift;
  my $indent = shift;
  my $line_num = shift;

  # Indicate that a list should be started for the next item
  # need to do this to work out the type of list
  push ( @{$self->lists}, new Pod::List(-indent => $indent, 
					-start => $line_num,
					-file => $self->input_file,
				       )	 
       );

}

=item B<end_list>

Called when the end of a list is found (the C<back> directive).
Pops the C<Pod::List> object off the stack of lists and writes
the C<latex> code required to close a list.

  $parser->end_list($line_num);

=cut

sub end_list {
  my $self = shift;
  my $line_num = shift;

  unless (defined $self->lists->[-1]) {
    my $file = $self->input_file;
    warn "No list is active at line $line_num (file=$file). Missing =over?\n";
    return;
  }

  # What to write depends on list type
  my $type = $self->lists->[-1]->type;

  # Don't write anything if the list type is not set
  # iomplying that a list was created but no entries were
  # placed in it (eg because of a =begin/=end combination)
  $self->_output("\\end{$type}\n")
    if (defined $type && length($type) > 0);
  
  # Clear list
  pop(@{ $self->lists});

}

=item B<add_item>

Add items to the list. The first time an item is encountered 
(determined from the state of the current C<Pod::List> object)
the type of list is determined (ordered, unnumbered or description)
and the relevant latex code issued.

  $parser->add_item($paragraph, $line_num);

=cut

sub add_item {
  my $self = shift;
  my $paragraph = shift;
  my $line_num = shift;

  unless (defined $self->lists->[-1]) {
    my $file = $self->input_file;
    warn "List has already ended by line $line_num of file $file. Missing =over?\n";
    # Replace special chars
#    $paragraph = $self->_replace_special_chars($paragraph);
    $self->_output("$paragraph\n\n");
    return;
  }

  # If paragraphs printing is turned off via =begin/=end or whatever
  # simply return immediately
  return if $self->{_suppress_all_para};

  # Check to see whether we are starting a new lists
  if (scalar($self->lists->[-1]->item) == 0) {

    # Examine the paragraph to determine what type of list
    # we have
    $paragraph =~ s/\s+$//;
    $paragraph =~ s/^\s+//;

    my $type;
    if (substr($paragraph, 0,1) eq '*') {
      $type = 'itemize';
    } elsif ($paragraph =~ /^\d/) {
      $type = 'enumerate';
    } else {
      $type = 'description';
    }
    $self->lists->[-1]->type($type);

    $self->_output("\\begin{$type}\n");

  }

  my $type = $self->lists->[-1]->type;

  if ($type eq 'description') {
    # Handle long items - long items do not wrap
    # If the string is longer than 40 characters we split
    # it into a real item header and some bold text.
    my $maxlen = 40;
    my ($hunk1, $hunk2) = $self->_split_delimited( $paragraph, $maxlen );

    # Print the first hunk
    $self->_output("\n\\item[{$hunk1}] ");

    # and the second hunk if it is defined
    if ($hunk2) {
      $self->_output("\\textbf{$hunk2}");
    } else {
      # Not there so make sure we have a new line
      $self->_output("\\mbox{}");
    }

  } else {
    # If the item was '* Something' or '\d+ something' we still need to write
    # out the something. Also allow 1) and 1.
    my $extra_info = $paragraph;
    $extra_info =~ s/^(\*|\d+[\.\)]?)\s*//;
    $self->_output("\n\\item $extra_info");
  }

  # Store the item name in the object. Required so that 
  # we can tell if the list is new or not
  $self->lists->[-1]->item($paragraph);

}

=back

=head2 Methods for headings

=over 4

=item B<head>

Print a heading of the required level.

  $parser->head($level, $paragraph, $parobj);

The first argument is the pod heading level. The second argument
is the contents of the heading. The 3rd argument is a Pod::Paragraph
object so that the line number can be extracted.

=cut

sub head {
  my $self = shift;
  my $num = shift;
  my $paragraph = shift;
  my $parobj = shift;

  # If we are replace 'head1 NAME' with a section
  # we return immediately if we get it
  return 
    if ($self->{_CURRENT_HEAD1} =~ /^NAME/i && $self->ReplaceNAMEwithSection());

  # Create a label
  my $label = $self->_create_label($paragraph);

  # Create an index entry
  my $index = $self->_create_index($paragraph);

  # Work out position in the above array taking into account
  # that =head1 is equivalent to $self->Head1Level

  my $level = $self->Head1Level() - 1 + $num;

  # Warn if heading to large
  if ($num > $#LatexSections) {
    my $line = $parobj->file_line;
    my $file = $self->input_file;
    warn "Heading level too large ($level) for LaTeX at line $line of file $file\n";
    $level = $#LatexSections;
  }

  # Check to see whether section should be unnumbered
  my $star = ($level >= $self->LevelNoNum ? '*' : '');

  # Section
  $self->_output("\\" .$LatexSections[$level] .$star ."{$paragraph\\label{".$label ."}\\index{".$index."}}\n");

}


=back

=end __PRIVATE__

=begin __PRIVATE__

=head2 Internal methods

Internal routines are described in this section. They do not form part of the
public interface. All private methods start with an underscore.

=over 4

=item B<_output>

Output text to the output filehandle. This method must be always be called
to output parsed text.

   $parser->_output($text);

Does not write anything if a =begin is active that should be
ignored.

=cut

sub _output { 
  my $self = shift;
  my $text = shift;

  print { $self->output_handle } $text
    unless $self->{_suppress_all_para};

}


=item B<_replace_special_chars>

Subroutine to replace characters that are special in C<latex>
with the escaped forms

  $escaped = $parser->_replace_special_chars($paragraph);

Need to call this routine before interior_sequences are munged but not
if verbatim. It must be called before interpolation of interior
sequences so that curly brackets and special latex characters inserted
during interpolation are not themselves escaped. This means that < and
> can not be modified here since the text still contains interior
sequences.

Special characters and the C<latex> equivalents are:

  }     \}
  {     \{
  _     \_
  $     \$
  %     \%
  &     \&
  \     $\backslash$
  ^     \^{}
  ~     \~{}
  #     \#

=cut

sub _replace_special_chars {
  my $self = shift;
  my $paragraph = shift;

  # Replace a \ with $\backslash$
  # This is made more complicated because the dollars will be escaped
  # by the subsequent replacement. Easiest to add \backslash 
  # now and then add the dollars
  $paragraph =~ s/\\/\\backslash/g;

  # Must be done after escape of \ since this command adds latex escapes
  # Replace characters that can be escaped
  $paragraph =~ s/([\$\#&%_{}])/\\$1/g;

  # Replace ^ characters with \^{} so that $^F works okay
  $paragraph =~ s/(\^)/\\$1\{\}/g;

  # Replace tilde (~) with \texttt{\~{}}
  $paragraph =~ s/~/\\texttt\{\\~\{\}\}/g;

  # Now add the dollars around each \backslash
  $paragraph =~ s/(\\backslash)/\$$1\$/g;

  # Convert ------ to -{}-{}-{}-{}-{}-
  $paragraph =~ s/-(?=-)/-{}/g;

  return $paragraph;
}

=item B<_replace_special_chars_late>

Replace special characters that can not be replaced before interior
sequence interpolation. See C<_replace_special_chars> for a routine
to replace special characters prior to interpolation of interior
sequences.

Does the following transformation:

  <   $<$
  >   $>$
  |   $|$


=cut

sub _replace_special_chars_late {
  my $self = shift;
  my $paragraph = shift;

  # < and >
  $paragraph =~ s/(<|>)/\$$1\$/g;

  # Replace | with $|$
  $paragraph =~ s'\|'$|$'g;


  return $paragraph;
}


=item B<_create_label>

Return a string that can be used as an internal reference
in a C<latex> document (i.e. accepted by the C<\label> command)

 $label = $parser->_create_label($string)

If UniqueLabels is true returns a label prefixed by Label()
This can be suppressed with an optional second argument.

 $label = $parser->_create_label($string, $suppress);

If a second argument is supplied (of any value including undef)
the Label() is never prefixed. This means that this routine can
be called to create a Label() without prefixing a previous setting.

=cut

sub _create_label {
  my $self = shift;
  my $paragraph = shift;
  my $suppress = (@_ ? 1 : 0 );

  # Remove latex commands
  $paragraph = $self->_clean_latex_commands($paragraph);

  # Remove non alphanumerics from the label and replace with underscores
  # want to protect '-' though so use negated character classes 
  $paragraph =~ s/[^-:\w]/_/g;

  # Multiple underscores will look unsightly so remove repeats
  # This will also have the advantage of tidying up the end and
  # start of string
  $paragraph =~ s/_+/_/g;

  # If required need to make sure that the label is unique
  # since it is possible to have multiple pods in a single
  # document
  if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
    $paragraph = $self->Label() .'_'. $paragraph;
  }

  return $paragraph;
}


=item B<_create_index>

Similar to C<_create_label> except an index entry is created.
If C<UniqueLabels> is true, the index entry is prefixed by 
the current C<Label> and an exclamation mark.

  $ind = $parser->_create_index($paragraph);

An exclamation mark is used by C<makeindex> to generate 
sub-entries in an index.

=cut

sub _create_index {
  my $self = shift;
  my $paragraph = shift;
  my $suppress = (@_ ? 1 : 0 );

  # Remove latex commands
  $paragraph = $self->_clean_latex_commands($paragraph);

  # If required need to make sure that the index entry is unique
  # since it is possible to have multiple pods in a single
  # document
  if (!$suppress && $self->UniqueLabels() && defined $self->Label) {
    $paragraph = $self->Label() .'!'. $paragraph;
  }

  # Need to replace _ with space
  $paragraph =~ s/_/ /g;

  return $paragraph;

}

=item B<_clean_latex_commands>

Removes latex commands from text. The latex command is assumed to be of the
form C<\command{ text }>. "C<text>" is retained

  $clean = $parser->_clean_latex_commands($text);

=cut

sub _clean_latex_commands {
  my $self = shift;
  my $paragraph = shift;

  # Remove latex commands of the form \text{ }
  # and replace with the contents of the { }
  # need to make this non-greedy so that it can handle
  #  "\text{a} and \text2{b}"
  # without converting it to
  #  "a} and \text2{b"
  # This match will still get into trouble if \} is present 
  # This is not vital since the subsequent replacement of non-alphanumeric
  # characters will tidy it up anyway
  $paragraph =~ s/\\\w+{(.*?)}/$1/g;

  return $paragraph
}

=item B<_split_delimited>

Split the supplied string into two parts at approximately the
specified word boundary. Special care is made to make sure that it
does not split in the middle of some curly brackets.

e.g. "this text is \textbf{very bold}" would not be split into
"this text is \textbf{very" and " bold".

  ($hunk1, $hunk2) = $self->_split_delimited( $para, $length);

The length indicates the maximum length of hunk1.

=cut

# initially Supplied by hsmyers@sdragons.com
# 10/25/01, utility to split \hbox
# busting lines. Reformatted by TimJ to match module style.
sub _split_delimited {
  my $self = shift;
  my $input = shift;
  my $limit = shift;

  # Return immediately if already small
  return ($input, '') if length($input) < $limit;

  my @output;
  my $s = '';
  my $t = '';
  my $depth = 0;
  my $token;

  $input =~ s/\n/ /gm;
  $input .= ' ';
  foreach ( split ( //, $input ) ) {
    $token .= $_;
    if (/\{/) {
      $depth++;
    } elsif ( /}/ ) {
      $depth--;
    } elsif ( / / and $depth == 0) {
      push @output, $token if ( $token and $token ne ' ' );
      $token = '';
    }
  }

  foreach  (@output) {
    if (length($s) < $limit) {
      $s .= $_;
    } else {
      $t .= $_;
    }
  }

  # Tidy up
  $s =~ s/\s+$//;
  $t =~ s/\s+$//;
  return ($s,$t);
}

=back

=end __PRIVATE__

=head1 NOTES

Compatible with C<latex2e> only. Can not be used with C<latex> v2.09
or earlier.

A subclass of C<Pod::Select> so that specific pod sections can be
converted to C<latex> by using the C<select> method.

Some HTML escapes are missing and many have not been tested.

=head1 SEE ALSO

L<Pod::Parser>, L<Pod::Select>, L<pod2latex>, L<Pod::Simple>.

=head1 AUTHORS

Tim Jenness E<lt>tjenness@cpan.orgE<gt>

Bug fixes and improvements have been received from: Simon Cozens
E<lt>simon@cozens.netE<gt>, Mark A. Hershberger
E<lt>mah@everybody.orgE<gt>, Marcel Grunauer
E<lt>marcel@codewerk.comE<gt>, Hugh S Myers
E<lt>hsmyers@sdragons.comE<gt>, Peter J Acklam
E<lt>jacklam@math.uio.noE<gt>, Sudhi Herle E<lt>sudhi@herle.netE<gt>,
Ariel Scolnicov E<lt>ariels@compugen.co.ilE<gt>,
Adriano Rodrigues Ferreira E<lt>ferreira@triang.com.brE<gt>,
R. de Vries E<lt>r.de.vries@dutchspace.nlE<gt> and
Dave Mitchell E<lt>davem@iabyn.comE<gt>.

=head1 COPYRIGHT

Copyright (C) 2011 Tim Jenness.
Copyright (C) 2000-2004 Tim Jenness. All Rights Reserved.

This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=begin __PRIVATE__

=head1 REVISION

$Id$

=end __PRIVATE__

=cut

1;