summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/examplep/eurotex_2005_examplep.tex
blob: e6052aca4db466c0c6eff43819eac22f7215569c (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
%
% eurotex_2005_examplep.tex
% by pts@fazekas.hu at Thu Nov 11 20:44:25 CET 2004
% -- Wed Jan 12 00:42:06 CET 2005
%
% Dat: this is the supposed final version of the article, without corrections
% Dat: required houses.{eps,pdf} pexaminipage.{eps,pdf} shorthyp_t1xtts.{eps,pdf}
% Dat: auxilary files: eurotex_2005_examplep.bib ttt.tex
% OK:  eliminate Overfull \hbox{}es
% OK:  submit to CTAN
%

\documentclass[a4paper]{article}
\usepackage[latin2]{inputenc}% Dat: because of `á' etc.; also ÷
\usepackage{t1enc}
\usepackage{booktabs}
\usepackage{graphicx}% Dat: after Babel
\usepackage{mflogo}

% Dat: for \documentclass[a4paper]{article}
\special{\string!\expandafter\expandafter\csname @gobble\endcsname
  \string\%xdvi.dvo: -expert -s 6 -xoffset -1.54cm -yoffset -1.54cm
  -paper 12.8cmx23cm} % -xoffset 7mm -yoffset 13mm -paper 385ptx576pt}

\title{Verbatim phrases and listings in {\LaTeX}}
\author{P\'eter Szab\'o $\langle$\texttt{pts@fazekas.hu}$\rangle$
\thanks{Thanks to Ferenc Wettl for the fruitful long discussion about the
line syntax of the \texttt{code} environment, and also for reviewing the
article.}
\\[3pt]%\par\smallskip
\normalsize Budapest University of Technology and Ecomomics,\\[-3pt]
\normalsize Department of Analysis,\\[-3pt]
\normalsize M\H{u}egyetem rakpart 3--9.,\\[-3pt]
\normalsize Budapest, Hungary H-1111}
\date{2004-11-11}

\def\verbatizee#1{\begingroup\ttfamily
   \toks0{#1}\edef\next{\the\toks0}%
   %\dimen0=\the\fontdimen2\font % Dat: disable spaces, `=' is required here
   \dimen0\fontdimen2\font % Dat: disable spaces, `=' is required here
   %\showthe\dimen0
   \fontdimen2\font=0pt
   {\expandafter\stripit\meaning\next}% Dat: grouping to keep \dimen0
   \unskip % Dat: strip final space, possibly after command
   \fontdimen2\font=\dimen0
   %\showthe\dimen0
   \endgroup}
\def\next{}
\expandafter\def\expandafter\stripit\meaning\next{}

%** So \verb+÷+ works.
\DeclareInputText{247}{\ensuremath{\div}}

\belowcaptionskip0pt

\begin{document}

\maketitle

\begin{abstract}

  The \textsf{examplep} package written by the author recently provides
  sophisticated features for typesetting verbatim source code listings,
  including the display of the source code and its compiled \LaTeX{} or
  \textsf{METAPOST} output side-by-side, with automatic width detection and
  enabled page breaks (in the source), without the need for specifying the
  source twice. Special care is taken so section, page and footnote numbers
  do not interfere with the main document. For typesetting short verbatim
  phrases, a replacement for the \verb+\verb+ command is also provided
  in the package, which can be used inside tables and moving arguments such as
  footnotes and section titles. The listings package is used for syntax
  highlighting.

  The article reviews the design decisions
  made during the package development and also presents some interesting
  implementation internals. \textsf{examplep} is compared to standard
  \LaTeX{} packages such as \textsf{listings}, \textsf{ltxdoc},
  \textsf{sverb} and \textsf{moreverb}. The new \textsf{codep} package and
  its accomanying \textsf{Perl} script,
  which provide a convenient interface to the \textsf{examplep} package for
  authors of manuals, is also presented. With \textsf{codep} it is possible
  to generate the source code, the \LaTeX{} or \textsf{METAPOST} output and
  the compilable example file onto the CD from a single source embedded
  into the appropriate place of the \texttt{.tex} document file.
%%%WF A CD-re irasnak semmi koze a lenyeghez, sajnos a dolgozat
%%%   hatralevo reszeben is folyton CD-file es egyebekrol szolsz, de
%%%   valojaban csak arrol van szo, hogy kulon file-ba irjuk a
%%%   futtathato kodot (amit aztan a web-re, CD-re, DVD-re... lehet tenni).
%% -- kellett neki nevet adni, ez lett
\end{abstract}


\section{Terminology}

\begin{description}

\item[verbatim text] A visually distinguishable textual part of the
   document (usually typeset with a monospaced, or typewriter font) that is
   allowed to contain the full ASCII character set. Verbatim text is often
   used to typeset parts of program source files, including \TeX{} source.
   Verbatim text must be marked up (i.e.\ surrounded)
   in the source of the \LaTeX{}
   document, so backslash and other control characters are typeset verbatim
   instead of being interpreted as commands or special \LaTeX{} characters.

%%%WF a kovetkezo 2 def nem pontos, nem biztos, hogy paragrafusok kozt
%%%   van a kiemelt verbatim. Sorban? vagy sorok kozt van? 
%% -- lehetne még pontosítani, de szerintem ebbõl rögtön lehet tudni, mire
%%    gondolok
\item[inline verbatim] A verbatim text passage inside a paragraph
   or table cell.

\item[display verbatim] is a vertical verbatim text block between
   paragraphs.

\item[side-by-side display]
   When typesetting program source in a display verbatim, it is often
   desirable to show the output of the program as well. This is especially
   useful when teaching scripting languages, so the reader can see the
   command and its effect side-by-side in a quick glance. For \TeX{} or
   \textsf{METAPOST} sources and EPS and PDF source files it is also useful to
   see the source and the typeset result side-by-side.

\item[Source and Sample]
   Side-by-side displays can be divided to \emph{Source} and \emph{Sample},
   the latter being program output or typeset material.

\item[CD-files]
   Files accompanying a book, usually on a CD or DVD shipped with the book,
   or avalable for download on the home page of the book. These
   files usually contain some of the display verbatim material in the book,
   so readers do not have to retype them.

\end{description}

\section{Special characters in the \LaTeX{} source}

The special meaning of the input characters in the source file must be
disabled in verbatim mode -- except for the character(s) that delimit the end
of the verbatim text. The following characters have to be dealt with:

\begin{description}

\item[ASCII symbols] The ligatures have to be disabled, especially \verb+?`+ $\to$
\texttt{?`} etc. The safest way is to make both characters of such a ligature
active, and %then
defining \verb+\def?{\relax\string?\relax}+
and \verb+\def`{\relax\string`+\allowbreak\verb+\relax}+. \hskip0pt
minus3.3pt\relax \textsf{examplep} issues similar
definitions covering all such ligatures in the OT1- and T1-encoded CM fonts.

\item[ASCII letters] Most verbatim fonts don't contain the ``fi'' or similar
ligatures, so \textsf{examplep} takes no care to disable them.

\item[special \TeX{} source symbols] To disable the special meaning of the symbols
\verb+\+
\verb-{-
\verb-}-
\verb+$+ %%%$
\verb+%+
\verb+^+
\verb+&+
\verb+_+,
\textsf{examplep} redefines their \verb+\catcode+ for display verbatim.
However, catcode changes are not always appriopriate for inline verbatim,
so \textsf{examplep} provides \verb+\÷+ (see below) which doesn't change
catcodes at all.

\item[other ASCII punctuation] Some of these characters (%
\verb+[+
\verb+]+
\verb+;+
\verb+'+
\verb+,+
\verb+.+
\verb+/+
\verb+~+
\verb+!+
\verb+@+
\verb+*+
\verb+(+
\verb+)+
\verb-+-
\verb-|-
\verb-:-
\verb-"-
\verb-<-
\verb->-
\verb-?-
\verb+`+
\verb+-+
\verb+=+) may be active, for example, \verb+~+ is ÷\nobreakspace÷,
\verb+`+ is a Babel shorthand (e.g.\ in the Hungarian language module,
\textsf{magyar.ldf}); \verb+"+ is a Babel shorthand (e.g\ in the German
language module); \verb+?+, \verb+!+, \verb+:+ and \verb+;+ are activated
(e.g.\ by the French language module), and other characters may be activated,
too. So \textsf{examplep} sets the catcode of all characters in the range
$33\ldots126$ to other (12). This includes all ASCII punctuation, letter and
digit characters.

\item[double carets] For example, the letter
``J'' can be input as its ASCII code in hex,
prefixed by double carets: \verb+^^4a+. However, in verbatim mode we want the
4 characters, not the letter {J}. There is no problem in inline verbatim
mode, because \verb+^+ loses its special meaning once its catcode is changed.
However, when the verbatim material is written to a file or to the terminal,
\TeX{} may change ``unprintable'' characters to escapes prefixed by \verb+^^+.
These changes must be reverted when reading the file back. See Subsection
\ref{tcx} for more.

\item[high characters] Input characters in the range $128\ldots255$ are
usually activated by the \textsf{inputenc} package, and they know how to
typeset themselves -- so \textsf{examplep} leaves the catcode of such
characters intact. However, in some modes, \textsf{examplep} has already
changed all catcodes to 12 and 10 (with \verb+\meaning+), so it has to change
the catcodes of such high codes back to 13 (active).

\end{description}

\section{Features of \textsf{examplep}}

These are the most important, unique features:

\begin{itemize}

\item layout of side-by-side display may depend on maximum Source width
\item automatic hyphenation of inline verbatim. The text is divided into
  words and punctuation symbols (based on catcodes). For words, the normal
  \TeX{} hyphenation patterns apply, and it is allowed to break the line on
  both sides of a punctuation symbol.
\item customizable isolation of page, section etc.\ numbers in the Sample
      and the host document with the \texttt{PexaMiniPage} environment
\item besides the outer level, inline verbatim (when properly escaped inside
      \verb+\Q+ or \verb+\÷+) works safely inside macro arguments, section
      titles, footnotes, table cells and index entries
\item generated CD-files with automatic page and chapter number
\item writing verbatim data to CD-files with a \textsf{Perl} script; exact,
      binary reproduction of verbatim text is guaranteed
\item ability to write different material to Source, Sample and CD-files
\item the accents \verb+\H+ and \verb+\.+ work as expected with monospaced
      fonts in the OT1 encoding. By default, \verb+\texttt{\H o}+ produces
      \hbox to0pt{\verb+}+\hss}\verb+o+ in OT1 encoding, because such
      typewriter fonts (such as \textit{cmtt10}) have those accents 
%%%WF repaced
      replaced
      by ASCII symbols. \textsf{examplep} solves the problem by getting the
      accent from the \textit{cmr} font family.

\end{itemize}

\noindent Some other features:

\begin{itemize}

\item side-by-side display of the Source and the Sample
\item between-word hypenation of inline verbatim
\item customizable left and right indentation of display verbatim
\item specifying inline verbatim with nested braces (\verb+\PVerb+,
  \verb+\Q+) or terminating character (\verb+\PVerb+, \verb+÷+, \verb+\÷+)
\item automatic line breaks with hyphenation in display verbatim
\item the discretionary hyphen (\verb+\hyphenchar+) of verbatim text is
      different from the one in normal text
\item line numbering in display verbatim
\item writing to temporary files only if needed
\item reading back contents of any file in display verbatim
%\item writing verbatim data to temporary files (\verb+^+\relax\verb+^+ab, .tcx)
% Dat: not a feature: automatic \textsf{METAPOST} processing, see the \texttt{eempost} package
\item inline verbatim with a single character ($\div$) and its escaped
      version (\textbackslash$\div$ and \verb+\Q+)
\item automatic \verb+\indent+\allowbreak/\allowbreak\verb+\noindent+,
      based on empty line above \verb+\begin{...}+
\item ISO Latin accented input character support in all modes (also present
      in \verb+\verb+)
\item support for syntax highlighting with the \textsf{listings} package
      \cite{listings}
%%%WF a (\cite{...}) kicserelendo \cite{...} -re az EGESZ DOLGOZATBAN, 
%%%   nem kell kerek zarojel, ott van mar a szogletes
%% -- javítva
\item emits a tab as eight spaces in normal mode, but tabs are supported
      properly with \texttt{ttlistings=yes} and \texttt{ttlistings=showtabs}
\item simple side-by-side display emulation without temporary files,
      using \texttt{src\allowbreak style=leftboth} or \texttt{srcstyle=leftleft}

\end{itemize}


\subsection{Escaped mode of inline verbatim locations}\label{escaped}

For compatibility reasons, \textsf{examplep} doesn't change the original
%%%WF ÷\verb+ and ÷\verb*+ 
\verb+\verb+ and \verb+\verb*+
%%%
commands in any way, but defines its own commands:
\verb+\PVerb+, \verb+\PVerbH+, \verb+\PVerbInner+,
\verb+\PVerbOpt+, \verb+\Q+, \verb+÷+ and \verb+\÷+. Most of the
\verb+\PVerb+\ldots{}
commands are historical. For new documents, only the use of
\verb+\PVerbOpt+, \verb+\Q+, \verb+÷+ and \verb+\÷+ is recommended. Some of
these commands have to be activated with package load options:
\verb+\usepackage[Q=yes,div=yes,bsdiv=yes]{examplep}+. The reason why
\verb+÷+ was introduced is that it is a high Latin-1 (and Latin-2) character
available on the Hungarian keyboard, which is usually not used in \LaTeX{}
documents (in fact, \verb+$\div$+ is used instead). Inline verbatim sources
with such a character are compact, and they can contain all ASCII symbols.

\begin{table}
\caption{Contexts and features of inline verbatim commands}\label{contexts}
\vskip\abovecaptionskip
\small
\noindent\hfil\begin{tabular}{@{}llllll@{}}\toprule
                  & outer& argument& tablular& elsewhere& escaped \\\midrule
\verb+\verb+      & +    & $-$$^1$ & +       & $-$$^1$  & no      \\
\verb+\PVerbOpt+  & +    & +$^2$   & +       & $-$      & no \\
\verb+÷+          & +    & +$^2$   & $-$     & +$^2$    & no \\
\verb+\÷+         & +    & +       & +       & +        & yes \\
\verb+\Q+         & +    & +       & +       & +        & yes \\
\bottomrule
\end{tabular}
\par\smallskip
$^1$sometimes displays the proper error message\par
$^2$inner mode only (spaces compressed or lost, \verb+%+ is comment etc.)
\end{table}

\textsf{examplep} supports inline verbatim text at the outer level,
inside macro arguments, in table cells and elsewhere (in section titles, in
footnotes and in index entries), see also in Table \ref{contexts}.
The reason why some of these cases are treated differently
is that catcode changes must be timed correctly so that the proper catcodes
are active by the time \TeX{} reads the verbatim text from the input file for
the first time. (Please note that section titles and index entries are also
written to and read back from auxilary files.)

This is quite hard to accomplish in several cases (because \TeX{}'s mouth
gathers macro arguments at high speed, a way before \TeX{}'s stomach could
change the catcodes), so \textsf{examplep} provides the commands \verb+÷+
and \verb+\Q+, which do not change catcodes at all, so they work everywhere.
Each special (say, not alphanumeric) character of the source text of these
commands must be prefixed by a backslash, so \TeX's eyes will see it as a
controls sequence token. The backslashes are retained when the construct is
written to auxilary files, but they get removed upon typesetting. Letters,
when prefixed by a backslash, get special meaning, for example \verb+\V+
denotes a visible space. For example, The construct
\verb+\÷\\\}÷+ is seen by \TeX's eyes as
\verb+\÷+$_{13}$\allowbreak
\verb+\\+$_{13}$\allowbreak
\verb+\}+$_{13}$\allowbreak
\verb+÷+$_{13}$, and its gets typeset as \verb+\}+ (by running the command
\verb+\÷+). Please note that the construct is properly nested, because all
braces are inside control sequence names. The same result (\verb+\}+) can be
achieved with \verb+\Q{\\\}}+. Both constructs are safe, because they can be
freely moved to anywhere in the source file. However, for compatibility
reasons, \verb+\Q+ is recommended, because its execution doesn't rely on the
current catcode of the terminating \verb+÷+ of \verb+\÷+. A more complicated
example: \verb+``\Q{\\\V X\ }''+ gets typeset as ``\verb*+\ X+\verb+ +''.
In escaped mode, \verb+\V+ dentoes a visible, unbreakable space,
\verb+\S+ and \verb*+\ + denote default space (affected by the
\texttt{pverb-space=} option), \verb+\B+ allows a line break there with a
discreationary hyphen (affected by the \texttt{pverb-linebreak=} option),
and \verb+\n+ flushes left and starts a new line.

The \verb+\PVerb+ macros can detect whether they have been invoked from
within a macro argument. If so, they do not insist on catcode changes, but
they emit all the tokens that has been seen by \TeX's eyes. (Spaces are
already compressed now, and everything after \verb+%+
is ignored etc., so this is not purely verbatim anymore.) However, this works
only if the macro argument is properly nested with respect to braces, and it
is delimited by braces (not a terminator character).

Please note that there might be problems with verbatim material in index
entries processed by \textsf{makeindex} if characters
\verb+"+, \verb+@+, \verb+!+ and \verb+|+ are not quoted properly with
\verb+"+. This is a generic \textsf{makeindex} issue. The quoting must be
applied even inside verbatim material.

\subsection{Horizontal alignment of the Source lines}\label{srcstyle}

The \texttt{verbatim} environment of standard \LaTeX{} reads the whole
verbatim text into a macro argument, thus limiting the length of the verbatim
material to the available main memory. This is enough for about 3400
80-character lines. The \textsf{verbatim}, \textsf{moreverb},
\textsf{listings} and
% Dat: moreverb pkg uses verbatim pkg
\textsf{examplep} packages parse the input line-by-line, so there is no such
limit. However, with \textsf{examplep}, additional memory is required for
aligned mode, which limits the maximum number of lines to about 2200
(32 pages) when the average line width is 80 characters. Please note that
the maximums mentioned here may be lower if more packages are loaded; in
another situatian the maximum number of lines was 375. As a reference,
a plain \verb+\halign+ with all lines having
\verb+(9999)\hfil\cr+ only could accomodate about 5000 lines when no packages
were loaded. The
maximum memory can be increased by increasing the \verb+extra_mem_bot+
variable in \textsf{texmf.cnf} or in the environment.
%As a reference measurement.
%%%WF mi itt ez az utso mondat?
%% -- tényleg hülyeség, hihúzva

There are two display modes used for display verbatim: paragraph and aligned
(see the \verb+\pexa@show@pars+ and \verb+\pexa@show@halign+ macros,
respectively, in the source). Aligned mode is used when multiple columns
(such as line numbers and text) have to be aligned horizontally. Aligned mode
uses the \TeX{} \verb+\halign+ primitive to do the alignment, and this
primitive reads the whole construct into memory before typesetting it (in
order to be able to calculate the column widths). The other one,
paragraph mode, is used when
horizontal alignment is not needed and side-by-side display is not used. In
paragraph mode, each line is typeset as a seperate paragraph, so the length
of the verbatim text is only limited by the available disk space to hold the
resulting DVI file. \textsf{examplep} chooses the mode automatically: for
side-by-side display it always chooses aligned mode (so it can measure the
width of the Source before typesetting it), otherwise, if the
\texttt{srcstyle=} makes it possible, it chooses paragraph mode, otherwise
it chooses aligned mode. See Figure \ref{fig:srcstyle} for details about
Source styles.

\begin{figure}\small
{\relax\normalsize \parindent1em
 \advance\leftskip\parindent %\advance\rightskip\parindent % Dat: automatic for \hsize
 \advance\hsize-2\parindent
 \parindent0pt
\texttt{srcstyle=left} \emph{PAF}\par
\leavevmode\hbox to0pt{\hss\scriptsize9}\texttt{srcstyle=leftnumhang} \emph{PAF}\par
{\scriptsize9}\texttt{srcstyle=leftnum} \emph{PAF}\par
\leavevmode{\scriptsize\phantom99}\texttt{srcstyle=leftnumcol} \emph{AF} when the last page number has 2 digits\par
\hfil\texttt{srcstyle=center} \emph{PAF}\par
\hfill\texttt{srcstyle=right} \emph{PAF}\par
\texttt{srcstyle=paralign}\hfill\emph{PF}\hfill with\hfill \texttt{source-par-align=justjust}\par
\strut\texttt{srcstyle=leftboth}\ \vrule\ srcstyle=leftboth \emph{A}\par
\leavevmode{\scriptsize\phantom99}\strut\texttt{srcstyle=leftbothnumcol}\ \vrule\ srcstyle=leftbothnumcol \emph{A}\par
\strut\texttt{srcstyle=leftleft}\ \vrule\ anything \emph{A}\par
%%%WF eleg zavaros egy tablazat, es harom sorban a | utani dolgok is
%%%   erthetetlenek
%% -- mivel nincs jobb ötletem, marad ez
% Imp: boxed?
}
\medskip
\emph{P:} works in paragraph mode\\
\emph{A:} works in aligned mode\\
\emph{F:} works when Source is read back from file
\caption{The effect of the \texttt{srcstyle=} option}\label{fig:srcstyle}
\end{figure}

Please note that the Source styles \texttt{leftboth} and
\texttt{leftbothnumcol} display each line twice, as Source and as Sample,
too. This is different from regular side-by-side display, because lines of
the Source and Sample here are forcibly aligned, and this solution doesn't
use a temporary file. The source style \texttt{leftleft} is similar, but it
lefts the author specify different Source and Sample for the same line (they
should be separated by \verb+&+ in the source).


\subsection{Display verbatim isolation}\label{pexaminipage}

The \texttt{PexaMinipage} environment is provided, which is similar to the
%%%WF bulilt-in 
built-in
%%%
\texttt{minipage} environment, but provides better isolation of the
Sample from the container document, because it saves and restores section,
page, equiation (etc.) numbers and also marks (section titles in
page headers).
Labels (for \verb+\label+, \verb+\ref+ etc.) are not isolated, because many
packages use them in a non-standard way.
See Figure \ref{fig:pexaminipage} for an example.

\begin{figure}\small
\noindent\hfil\hbox to0pt{\hss\includegraphics{pexaminipage}\hss}
\caption{Display verbatim isolation with the \texttt{PexaMinipage} environment}%
\label{fig:pexaminipage}
\end{figure}

The environment also
cancels vertical skips (including \verb+\belowdisplayskip+) at the bottom
of its contents. For space conservation, \verb+\abovedisplayskip+ above the
very first displayed equation is also canceled. To vaid this, put
\verb+\everydisplay{}+ before the formula. The environment starts with
\verb+\noindent+, but subsequent paragraphs are indented.


\subsection{Feature comparison}

Although there are several \LaTeX{} packages providing display and/or inline
verbatim environments for \LaTeX{}, \textsf{examplep} has some important
unique features not found in other packages (see the beginning of this
section for details). The author has tried the following packages before
deciding to write \textsf{examplep}:

\begin{description}

\item[\normalfont\textsf{verbatim}]
  Although the \texttt{verbatim} environment is built-in into \LaTeX{}, its
  most important limitation is that it eats up \TeX{} memory when typesetting
  very long verbatim material (of several hundred or thousand lines). The
  \textsf{verbatim} package fixes this, and provides the
  \verb+\verbatiminput+ command (similar to the \verb+\PexaShowSource+
  command of \textsf{examplep}) and the \texttt{comment} environment (similar
  to \texttt{PIgnore} in \textsf{examplep}).

\item[\normalfont\textsf{moreverb}]
  This package extends the \textsf{verbatim} package with additional
  features: proper handling of tabulators (also accessible from
  \textsf{examplep} with the \textsf{listings} interface), line numbering
  (also available in \textsf{examplep} with much more customization),
  verbatim surrounded by a frame (this is not available in \textsf{examplep},
  but it works with \textsf{listings}, with page breaks allowed), the
  \texttt{verbatimwrite} environment writes its contents to a file (similar
  to the \texttt{WFile} environment in \textsf{examplep}).

\item[\normalfont\textsf{sverb}]
  It provides display verbatim with tabulators and long environments, and it
  can read and write text from files. It also has a side-by-side environment
  (\texttt{demo}) with fancy frames.
  The \textsf{verbfwr} package (part of the \textsf{examplep} distribution)
  was derived from parts of this package.
  
\item[\normalfont\textsf{syntax}]
  This package is written by the author of \textsf{sverb}. It provides
  generic and customizable inline verbatim support and it also has powerful
  features to typeset BNF-like grammars and syntax diagrams. It is documented
  that no attempt is made to make the constructs work inside macro arguments
  or section titles.

\item[\normalfont\textsf{alltt}]
  This standard \LaTeX{} package defines the \texttt{alltt} environment in
  which the characters \verb+\ { }+ retain their original meaning, so it is
  possible to do some manual formatting in the verbatim text.

\item[\normalfont\textsf{fancyvrb}] \cite{fancyvrb}
  This is extremely configurable verbatim package provides inline
  verbatim even in footnotes, display verbatim even with side-by-side, line
  numbers on any side, all
  kinds of francy frames even with page breaks, text formatting and
  writing and reading from files; and very long diplay verbatim text.
  Options can be specified any time within the argument of the \verb+\fvset+
  command. The original \texttt{verbatim} environment is not modified,
  but a new one, \texttt{Verbatim} is defined. Setting the background color
  is not possible.

  This package is not actively developed. Version 2.7 (dated
  2000/03/21) is part of te\TeX{}. Oddly enough, the newest version on CTAN
  is 2.6, which a file timestamp in 2004, but it dated 1998/07/17).

\item[\normalfont\textsf{fvrb-ex}]
  This package is part of the \textsf{fancyvrb} distribution and uses the
  \textsf{fancyvrb} package. It provides a
  side-by-side display verbatim environment (\texttt{SideBy\allowbreak SideExample}). A
  page break is not allowed in the Source after the Sample. % Dat: tested
  The \texttt{xrightmargin} option has to be specified manually (e.g.\,%
  \texttt{xrightmargin\allowbreak=3cm}. The first two
  characters of each line in the environment are ignored.

\item[\normalfont\textsf{ltxdoc}]
  The most important features of \textsf{examplep} inspired by the \LaTeX{}
  documentation package are display verbatim line numbering with
  \texttt{srcstyle=left\allowbreak num} and inline verbatim started with \verb+÷+.
  The \textsf{ltxdoc} package typesets everything between two \verb+|+
  characters as inline verbatim. This is not supported by \textsf{examplep}
  to avoid making an ASCII character active.

\item[\normalfont\textsf{listings}] \cite{listings}
  The most important layout elements of this sophisticated, highly
  customizable, actively developed package missing from
  \textsf{examplep} are: background color, frames (with page breaks allowed),
  syntax highlighting and proper tabulator support. Except for the background
  color and frames, these features can be used from \textsf{examplep} with
  its interface to \textsf{listings}, see in Subsection \ref{listings}.
  Use \verb+\lstset{columns=fullflexible,lang+\allowbreak\verb+uage=C,back+\allowbreak\verb+groundcolor=\color{red},frame=trBL}+
  to try these features. \textsf{listings} also provides inline verbatim
  mode (with syntax highlighting), in the character-delimited argument of the
  command \verb+\lstinline+;\,unfortunately, spaces at line breaks (with
  option \texttt{breaklines}) are rendered in an inconsistent way, and line
  breaks do not work well with background color.

  \textsf{listings} has an important weak point: it cannot typeset ISO Latin
  accented characters with the \textsf{inputenc} package;
  the way described in the manual doesn't work as expected: it puts the
  accented characters to the wrong place in the line. This problem,
  however, is solved when \textsf{listings} is invoked from
  \textsf{examplep}. See more about listings in Subsection \ref{listings}.

%%%WF  This package is actively developed.
%%%    ezt mar emlitetted a bekezdes elejen
\end{description}

\section{Customization}\label{customization}

The operation of \textsf{examplep} can be customized with options as
$\langle$key$\rangle${}$=${}$\langle$value$\rangle$ pairs. Global options, which affect all subsequent commands within
the current block, can be specified as package load options
(\verb+\usepackage[+\ldots\verb+]{examplep}+) or as argument of the \verb+\PexaDefaults+
command. \LaTeX{} doesn't allow complicated option values (such as values
containing some expandable macros, for example after \texttt{linenumberformat=})
to be specified in the \verb+\usepackage+
line -- use \verb+\PexaDefaults+ in such cases.
Many commands and environment accept local options, which affect
only that construct.

All options have default values, which are indicated below right after the
option name. If the option has a fixed set of possible values, all of them
are mentioned, and they are prefixed by \texttt{=}. The defaults have been
chosen so the \texttt{PSource} environment matches the builtin
\texttt{verbatim} environment as closely as possible. Note that the original
environment is not overridden before the \texttt{verbatimenv=yes} is
specified.

\begin{description}
\makeatletter % Dat: for \verbatizee{\z@}

\item[\verbatizee{Q=unchanged}]
  To enable \verb+\Q+, use \texttt{=yes} instead of the default.
\item[\verbatizee{abreak=unchanged}]
  To enable \verb+\abreak+, use \texttt{=yes} instead of the default.
\item[\verbatizee{addvspace-bottom={\vskip\z@skip\addvspace}}]
  \hskip0pt plus4pt
  Specifies the command to add vertical space below display verbantim. The default works
  fine, but e.g.\ packages maintaining the baseline grid might want to
  change it.
\item[\verbatizee{addvspace-top=\addvspace}]
  Command to add vertical space above display verbantim. The default works
  fine, but for example, packages maintaining the baseline grid might want to
  change it.
\item[\verbatizee{allowbreak=yes}]
  Use \texttt{=no} to disable page breaks in the Source of display verbatim.
\item[\verbatizee{allowshrink=yes}]
  The default will shrink the Sample horizontally if the
  Source is too wide. Use \texttt{=no} to disable this.
  Use \texttt{=force} to enable shrinking of Source, and with
  \texttt{srcstyle=leftleft} or \texttt{srcstyle=leftboth}, also enable
  shrinking of the Source if it is narrow.
\item[\verbatizee{baseline-grid=no}]
  Use \texttt{=yes} to adjust the height of the Sample to be an integer
  multiply of \verb+\baselineskip+ (with \texttt{yalign=u} and
  \texttt{yalign=v}).
\item[\verbatizee{boxstyle=p}] Controls how the Sample is boxed. Capital
  letters are not allowed for side-by-side display. By default (\texttt{=p}),
  a \texttt{PexaMinipage} environment is put inside a \verb+\vtop+. Use
  \texttt{=h} to put a \verb+\hbox+ only, \texttt{=v} to put a \verb+\vtop+
  only, \texttt{=V} to put a \verb+\vbox+ only,
  \texttt{=m} to put a \texttt{minipage} environment inside a \verb+\vtop+, 
  \texttt{=M} to put a \texttt{minipage} environment inside a \verb+\vbox+, 
  \texttt{=P} to put a \texttt{PexaMinipage} environment inside a \verb+\vbox+,
  \texttt{=G} to add \verb+\begingroup+ and \verb+\endgroup+ only.
  The default is recommended for most cases, because the \verb+\vtop+
  provides proper alignment with the Source, and the \texttt{PexaMinipage}
  environment provides isolation (of page and section numbers etc.) from the
  main document.
\item[\verbatizee{bsdiv=unchanged}]
  To enable \verb+\÷+, use \texttt{=yes} instead of the default.
\item[\verbatizee{div=unchanged}]
  To enable \verb+÷+, use \texttt{=yes} instead of the default.
\item[\verbatizee{firstlinenum=1}]
  Specifies the number of the first line of a numbered Source listing.
  Useful with \texttt{srcstyle=leftnumcol} and \texttt{srcstyle=leftnumhang}.
\item[\verbatizee{linenumberformat={{...}}}]
  %\item[\verbatizee{linenumberformat={{\normalfont\rmfamily\scriptsize\number-\pexa@@cntb}\pexa@default@linenumbersep}}]
  Commands to display a line number and the separator in a numbered Source
  listing. See the default value in \texttt{examplep.sty}.
\item[\verbatizee{linenumbersep={}}]
  Commands to display the separator in a numbered Source listing.
\item[\verbatizee{listings=no}]
  Use \texttt{=yes} to display each Source line with the \textsf{listings}
  package. Specify options (to be executed in \verb+\lstset+), separated by
  commas in the argument. Read more about the options in the documentation of
  the \textsf{listings} package. For example, \verb+listings=yes+ and
  \verb+listings={}+ uses \textsf{listings} with default options (no syntax
  highlighting), and \verb+listings={language=+\allowbreak\verb+C,showtabs}+ enables syntax
  highlighting for C language and enables visible tabulators. See
  Subsection \ref{listings} for more information.
\item[\verbatizee{listings-verbatimfont=pexavf}]
  Set the font to be used in the Source when \texttt{listings=} is active. See
  \texttt{source-verbatimfont=} for the possible values.
\item[\verbatizee{mp-equation-reset=yes}]
  Use \texttt{=no} to make the main document and the Samples inside
  \texttt{PexaMinipage} share the same equation counter.
\item[\verbatizee{mp-varioref-reset=no}]
  Use \texttt{=yes} to make the internal counter \texttt{vrcnt} of the
  \textsf{varioref} package to be reset for each Sample inside
  \texttt{PexaMinipage}. This option doesn't affect the final output, and
  \textsf{varioref} expects this counter not to be reset, so it is not
  recommended to change the default.
\item[\texttt{noligs=some}]
  By default, only those ligatures are disabled whose second character is one
  of \verb+`+ \verb+'+ \verb+,+ \verb+-+ \verb+<+ \verb+>+. Use
  \texttt{=kernel} to get the same effect, but using the \LaTeX{} built-in
  \verb+\@noligs+. Use \verb+=most+ to get all ligatures with either the
  first or the second character having code between 32 and 127 and catcode
  12. Please note that ligatures in inline verbatim mode are disabled anyway,
  because \verb+\allowbreak+ is inserted between characters of catcode 12,
  depending on the value of \texttt{pverb-linebreak=}.
\item[\verbatizee{pexaminipage-setuphook={}}]
  Extra commands to run when starting the \texttt{Pexa\allowbreak MiniPage} environment,
  just after the environment has finished its own initialization.
\item[\verbatizee{pverb-hash=full}]
  Use \texttt{=half} to make \verb+\PVerb+ convert \verb+##+ to \verb+#+.
  The command \verb+\PVerbH+ is the same as \verb+\PVerb+ but
  forces \texttt{=half}. This is required when \verb+\PVerb+ or \verb+÷+ is
  used inside a macro argument. For example, \verb+\textit{÷#÷}+ yields
  the error message \textit{Illegal parameter number in definition of
  \string\reserved@a}, but \verb+\textit{\PVerbH{##}}+ works fine. The error
  message is a general \LaTeX{} kernel limitation, for example
  \verb+\textit{\@gobb+\allowbreak\verb+le{#}}+ doesn't work either.
\item[\verbatizee{pverb-hyphenchar=hyphen}]
  By default, the minus character (ASCII code 45) is used to for automatic word
  hyphenation in inline verbatim. Use \texttt{=char'30} to have character
  with code 24; see also Subsection \ref{char'30}. Use \texttt{=none} to
  disable word hyphenation (by setting \verb+\hyphenchar+ to $-1$).
  Use \texttt{=unchanged} to get the hyphenchar from
  the font (the \textit{cmtt} and \texttt{ectt} fonts have word hyphenation
  disabled). Please note that hyphenation around symbols is affected
  the \texttt{pverb-linebreak=} option, not this one.
\item[\verbatizee{pverb-leftbreakmin=2}]
  Specifies the minimum number of characters in inline verbatim after which it
  is allowed to break the line (with \texttt{pverb-linebreak\allowbreak=}). Values
  allowed are $0$, $1$ and $2$, but $0$ usually doesn't make sense.
\item[\verbatizee{pverb-linebreak=char}]
  By default, \verb+\PexaAllowBreak+ is inserted around symbols in inline
  verbatim, so a line break (with a discreationary hyphen affected by
  \texttt{pverb-linebreakchar=}) is allowed there. Use \texttt{=yes} to insert
  \verb+\allowbreak+ instead, which allows a line break without
  discretionaries. Use \texttt{=no} to disable line breaks around symbols in
  inline verbatim. The option \texttt{pverb-hyphenchar=} affects
  intra-word hyphenation in inline verbatim, not this one.
\item[\verbatizee{pverb-linebreakchar={$\lnot$}}]
  Specifies the discreationary hyphen to be used in \verb+\PexaAllowBreak+.
  See also \texttt{pverb-linebreak=}.
\item[\verbatizee{pverb-space=invbreak}]
  By default, spaces in inline verbatim are invisible, variable width (as
  allowed by the font, see also \texttt{pverb-stretchshrink=})
  and breakable (i.e.\ a space can be replaced by a line
  break if necessary). Use \texttt{=invdisc} to get an invisible, variable
  width space which becomes visible (\verb*+ +) when it is broken at the end
  of the line. Use \texttt{=invfixbreak} to get an invisible, fixed width and
  breakable space. Use \texttt{=invnobreak} to get an visible, variable width
  and unbreakable space. Use \texttt{=visnobreak} to get a visible, fixed
  width and unbreakable space. Use \texttt{=visbreak} to get a visible, fixed
  width space with line breaks allowed on both sides. Use
  \texttt{=invbreakleft} to get a visible, variable width space with infinite
  stretchablility if the line is broken there (this may have strange effect
  on other line breaks in the paragraph, so please try to avoid it).
  The built-in \verb+\verb*+ command uses
  \texttt{source-space=visnobreak}.
\item[\verbatizee{pverb-stretchshrink=yes}]
  By default, spaces in inline verbatim are forced to be stretchable and
  shrinkable (by \verb+\quad+${}/9$). Use \texttt{=no} to disable
  stretchability and shrinkability. Use \texttt{=unchanged} to keep the
  settings in the font. Note that \verb+\fontdimen+$3$ and
  \verb+\fontdimen+$4$ are changed by this option, and the changes are local
  to inline verbatim mode.
\item[\verbatizee{pverb-verbatimfont=pexavf}]
  Set the font to be used in inline verbatim mode. See
  \texttt{source-verbatimfont=} for the possible values.
\item[\verbatizee{samplewidth=.5\PexaWidth}]
  Specifies the maximum width of the Sample in side-by-side display as a
  \TeX{} dimension. The actual Sample can become actually narrower (see
  \texttt{allowshrink=}. The dimensions \verb+\hsize+, \verb+\linewidth+ and
  \verb+\PexaWidth+ can be used. (Our \LaTeX{} book used
  \verb+sample+\allowbreak\verb+width=.45\PexaWidth+.) \verb+\leftskip+ and \verb+\rightskip+
  do not affect this option. \verb+\hsize+ can be used, which is the total
  width available (including the extra margins added by surrounding list
  environments), \verb+\linewidth+ is \verb+\hsize+ widtout the extra margins
  produced by lists, and \verb+\PexaWidth+ is the total width of the Source,
  the separator (see \texttt{vrule=}) and the Sample.
\item[\verbatizee{source-par-align=left}]
  Specifies the alignment of Source lines when \texttt{srcsty\allowbreak le=paralign} is
  active. Use \texttt{=left} (default), \texttt{=right} or \texttt{=center} to
  specified flush-left, flush-right or centered alignment, respectively. Use
  \texttt{=justi\allowbreak fy} to have the last line flush-left and the previous line
  justified (please note that each Source line is mapped to a single
  paragraph, so the paragraph will have more than 1 line only if the source
  line is too long). Use \texttt{=justjust} to have all lines justified.
  Use \texttt{=unchanged} to keep the alignment of the enclosing block.
\item[\verbatizee{source-sepwidth=\tabcolsep}]
  Specifies the horizontal distance between the Source and the Sample.
  See also \texttt{vrule=}.
\item[\verbatizee{source-space=invfixbreak}]
  Specifies how to typeset spaces of the Source. See \texttt{pverb-space=}
  for the possible values. The built-in \texttt{verbatim*} environment uses
  \texttt{source-space=visnobreak}.
\item[\verbatizee{source-verbatimfont=pexavf}]
  Sets the font to be used for the Source when \texttt{listings=} is not
  active (see also \texttt{listings-verbatimfont=} for
  \texttt{listings\allowbreak=}).
  Give
  \texttt{=ttfamily} to use \verb+\ttfamily+,
  \texttt{=pexavf} to use \verb+\pexa@@verbatim+\allowbreak\verb+font+ (which defaults to
  \verb+\verbatim@font+),
  \texttt{=latexvf} to use \verb+\verbatim@+\allowbreak\verb+font+ (which defaults to \verb+\normalfont\ttfamily+),
  \texttt{=unchanged} to keep the current font,
  or \texttt{=normalfont} to use \verb+\normalfont+.
\item[\verbatizee{srcstyle=left}]
  Specifies the horizontal alignment of the Source lines. See more in
  Subsection \ref{srcstyle} and Figure \ref{fig:srcstyle}.
\item[\verbatizee{ttlistings=}\normalfont\ (no default)] % Dat: $\varnothing$
  Shorthand of \texttt{listings-verbatimfont=ttfamily,\allowbreak listings=}.
\item[\verbatizee{url=unchanged}]
  To enable \verb+\url+, use \texttt{=yes} instead of the default. The
  \verb+\url+ will be defined as \verb+\def\url{\PVerbOpt{}}+. This has the
  disadvantage that inside \verb+\textit+ etc.\ it cannot typeset URLs having
  a single \verb+#+ (see \texttt{pverb-hash=} for more), but the \textsf{url}
  package has the same limitation. A quick fix: use \verb+\itshape+ instead
  of \verb+\textit+ etc.
\item[\verbatizee{usewidth=skipwidth}]
  Specifies which horizontal part of the main text should be used in a
  display verbatim. By default, left and right margins introduced by list
  environments (such as \texttt{itemize}) and \verb+\leftskip+ and
  \verb+\rightskip+ are respected. Use \texttt{=linewidth} to ignore
  \verb+\leftskip+ and \verb+\rightskip+ but respect list environments. Use
  \texttt{=hsize} to use the whole width of main text. Note that this option
  affects the calculation of \verb+\PexaWidth+.
\item[\verbatizee{vextrabotdepth=\z@}]
  Dimension to add to the depth of the display verbatim with
  \texttt{yalign=v}. The default works
  fine, but for example, packages maintaining the baseline grid might want to
  change it for each instance.
\item[\verbatizee{vextravskip=\z@}]
  Amount of vertical space to be added above display verbantim with
  \texttt{yalign=v}. The default works
  fine, but for example, packages maintaining the baseline grid might want to
  change it for each instance.
\item[\verbatizee{vsmallht=1pt}]
  Specifies Sample height threshold for \texttt{yalign=v}. If the Sample is
  lower than this (or sample a higher than the 1st line of the Source plus
  \verb+\vextravskip+ --
  typical for \verb+\includegraphics+), its top will be aligned to the top of
  the Source, otherwise
  its top baseline (with \verb+\vtop+) will be aligned to the top baseline of
  the Source. 
\item[\verbatizee{xalign=l}]
  Specifies horizontal alignment (\texttt{=l} for left, \texttt{=r} for
  right) of the Sample box (and the separator) within its allocated width for
  side-by-side display. Please note that \texttt{=r} works only
  with \texttt{boxstyle=h}, because all other box sizes use their
  full allocated width.
\item[\verbatizee{xindent=deeppre}]
  Specifies additional horizontal indentation in display verbatim mode. Use
%%%WF  \texttt{=nonoe} 
  \texttt{=none}
%%%
  to get no extra indentation. Use \texttt{=narrower} to get
  \verb+\narrower+ (both \verb+\leftskip+ and \verb+\rightskip+ are decreased
  by \verb+\parindent+).
  Use \texttt{=deeper} to move one level deeper in the list environment
  hierarchy and get that indentation.
%%%WF na most akkor mi a default? a deeper vagy a deeppre?
  Use \texttt{=deeppre} (default) to move one level deeper, but don't change
  indentation (this is useful with \texttt{yindent=deeper} --
  otherwise it is equivalent to \texttt{=none}). % Dat: really??
  Use \texttt{=deepright} to set both left and right indentation from
  the left indentation of \texttt{=deeper}.
\item[\verbatizee{yalign=u}]
  Specifies vertical alignment in side-by-side display. By default, the top
  of the bounding boxes of the Source and the Sample is aligned, which looks
  nice if the Sample is an image, but doesn't align properly if the Sample is
  text with a font of similar size to the Source.  Use \texttt{=b} to align
  the topmost baselines of the Sample and the Source. This looks nice if the
  Sample is text, but it is ugly if the Sample is an image higher than
  \verb+\baselineskip+. The use of \texttt{=v} is recommended, which decides
  between \texttt{=b} and \texttt{=u} based on the height of the Sample (see
  \texttt{vsmallht=} for the details).
\item[\verbatizee{yindent=deeper}]
  Specifies the vertical space separating display verbatim from the
  surrounding text. Use \texttt{=none} no have no extra vertical space, the
  display verbatim appears to be a new paragraph as far as
  \verb+\baselineskip+ and \verb+\vskip+s are concerned. Use \texttt{=deeper}
  (default) to move one level deeper in the list environment hierarchy
  (and use the \verb+\parsep+ and \verb+\partopsep+ etc.\ specified there).
  It is recommended to have \texttt{yindent=deeper} and
  \texttt{xindent=deeppre} together, so there is no extra horizontal
  indentation.
\item[\verbatizee{verbatimenv=unchanged}]
  Use \texttt{=yes}
  to change the implementation of the \texttt{verba\allowbreak tim} and \texttt{verbatim*}
  environments to use the \texttt{PSource} environment.
\item[\verbatizee{vrule=rule}]
  By default, the Source and the Sample are separated with a vertical rule
  of width \verb+\arrayrulewidth+ in the middle of a horizontal space
  specified by \texttt{source-sepwidth=}. Use \texttt{=skip} to omit the rule
  but keep the space. Use \texttt{=none} to have no separator at all.

\end{description}

The other packages (\textsf{codep} and \textsf{verbfwr}) shipped with
\textsf{examplep} do not have load options.


\subsection{Interface to the \textsf{listings} package}\label{listings}

The \textsf{listings} package \cite{listings} provides advanced typographic for display
verbatim, including proper typesetting of tabulators and syntax highlighting
for more than a hundred languages. \textsf{examplep} doesn't try to
reimplement these features, but it supports calling the \textsf{listings}
package to typeset the Source lines in display verbatim. The surroundings
(line numbers, vertical separation, horizontal margins and the Sample) are
not effected, only the Source line contents are passed to \textsf{listings}.
This implies that the border and the background color support provided by the
\textsf{listings} package doesn't work with \textsf{examplep}. To use the
interface, the \textsf{listings} package must be loaded, and either the
\textsf{listings=} or the \textsf{ttlistings=} options of \textsf{examplep}
has to be active when the Source is typeset. Additional options
can be specified to \textsf{listings} in the argument of \verb+\lstset+ at
any time. The interface has been tested
with the \textsf{listings} package dated 2000/08/23 and 2004/09/07.

\textsf{examplep} treats tabulators (ASCII code 9) as 8 spaces. This is
acceptable at the beginning of the line, but it may be incorrect elsewhere.
To get tabs right, specify the \verb+ttlistings=yes+, or, to be more precise,
the \verb+ttlistings={tabsize+\allowbreak\verb+=8}+ option to \textsf{examplep}. It is also
possible to have visible tabulators: specify, for example,
\verb+ttlistings={tabsize=8,showtabs}+. In our tests \textsf{listings} failed
to detect the width of a character of a fixed width font, so
\textsf{examplep} enforces character width using the natural width of the
space each time it calls \textsf{listings}. This workaround made the
\texttt{showtabs} \textsf{listings} option work properly.
See the documentation of the
\textsf{listings} package for options that affect the typesetting of
Source line contents. See an example of using \textsf{listings} from
\textsf{examplep} on page \pageref{pag:use-listings}.

\textsf{listings} supports fixed width characters with a variable with fonts.
However, this support seems to be broken when used with \textsf{examplep}, so
the \texttt{columns=full\allowbreak flexible} \textsf{listings} option is enforced so
proportional fonts will look proportional. Although the
\textsf{listings} package claims that it has accented letter support, this
didn't work well with the single-character accented letters input using
the \textsf{inputenc} package (those characters were positioned to a wrong
place inside the line, possibly because \textsf{listings} has failed to
recognise that \verb+\lst@UseLostSpace\lst@+\allowbreak\verb+PrintToken+ has to be inserted
in front of the accented character into its internal token list).
\textsf{examplep} contains a work-around to this problem, with the following
limitations: multibyte input encodings such as UTF-8 are not supported (will
print strange error message); accented characters may not be part of keyword
names in syntax highlighting; accented characters are shown as \verb+^^+ hex
escapes in aligned mode (see in Subsection \ref{srcstyle}), so they don't
work with \verb+\PexaShowBoth+.

\textsf{listings}, when called from \textsf{examplep}, failed to break
ligatures such as \verb+`?+ and \verb+<<+. This has the side effect that
guillemots would be typeset instead of bitwise right shift in C language
sources. \textsf{examplep} modifies
the \verb+\lst@FillOutputBox@+ macro so it will add a \verb+\relax+ between
each character displayed -- so all ligatures are broken. (This approach is
quite differrent from the way \LaTeX{} disables a few ligatures
with \verb+\@noligs+; \verb+\pexa@noligs+ is similar to \verb+\@noligs+ in
this respect.)

It is possible to customize the \textsf{listings} package so it typesets some
strings differently. For example, with the
\verb+literate={<=}{{$\leq$}}1+ \textsf{listings} option, all occurences of
\verb+<=+ (even those inside strings of the target programming language)
are typeset as $\leq$. There are no problems when using this feature from
within \textsf{examplep}. It is also possible for strings and comments in the
syntax-highlighted Source to span multiple lines -- \textsf{listings} takes
care to remember its internal state between lines.


\section{Commands and environments}

The arguments between brackets (\verb+[+ and \verb+]+) are optional: either
the the argument and the brackets are all missing all all present. The
arguments named ``options'' is a comma-separated list of local customization
options, defined in Section \ref{customization}. The \texttt{\{}$^+$ notation
in front of an argument means that the argument can be delimited by braces
(thus it must be properly nested), or with any symbol in
\verb+\dospecials+ (%
\verb+\+ \verb+$+ \verb+&+ \verb+#+ \verb+^+ \verb+_+ \verb+%+
\verb+~+) %%%WF $
or in \verb+\pexa@cverb@donormals+ (%
\verb+`+ \verb+!+ \verb+@+ \verb+*+ \verb+-+ \verb-+- \verb+=+ \verb+|+
\verb+:+ \verb+;+ \verb+'+ \verb+"+ \verb+,+ \verb+.+ \verb+/+ \verb+?+
\verb+<+ \verb+>+ \verb+(+ \verb+)+ \verb+[+ \verb+]+).

\begin{description}

\def\cearg #1{{\normalfont\texttt{\{}$\langle  $\relax#1\relax$\rangle$\texttt{\}}}}
\def\verarg#1{{\normalfont\texttt{\{}$^+\langle$\relax#1\relax$\rangle$\texttt{\}}}}
\def\delarg#1{{\normalfont           $\langle  $\relax#1\relax$\rangle           $}}
\def\optarg#1{{\normalfont[$\langle$\relax#1\relax$\rangle$]}}

\item[\verbatizee{\PVerb}\optarg{options}\verarg{verbatimtext}]
  Typesets its argument in inline verbatim mode. Similar to the \LaTeX{}
  \verb+\verb+ macro, but respects the options. The use of \verb+[]+ is
  recommended instead of omitting the options altogether, because \verb+[]+
  will ensure that the proper catcode changes are in effect even for the
  first verbatim character.
  This command is robust.
\item[\verbatizee{\PVerbH}\verarg{verbatimtext}]
  Shorthand for \verb+\PVerb[pverb-hash=half]+\ \hskip0pt plus2pt
  (extra options cannot be specified).
  This command is robust.
\item[\verbatizee{\PVerbInner\PVerb}\ldots]
  Forces the \verb+\PVerb+\ldots{} command immediately following it to work
  in inner mode, thus compressing spaces, respecting comment characters etc.
  Because of how \TeX{} works, it is impossible to go the other way round,
  and force outer mode, because it is too late change catcodes -- the
  argument has already been tokenized in inner mode.
  This command is robust.
\item[\verbatizee{\PVerbOpt}\cearg{options}\verarg{verbatimtext}]
  Equivalent to \verb+\PVerb+, but uses a different syntax.
  For example, \verb+\item[\PVerb[pverb-space=visbreak]{xy+\allowbreak\verb+}]+ doesn't work
  because of the nested \verb+[+. Use this instead:
  \verb+\item[\PVerb+\allowbreak\verb+Opt{pverb-space=+\allowbreak\verb+visbreak}{xy}]+,
  \hskip0pt plus4pt or \hskip0pt plus4pt 
  \verb+\item[{\PVerb[pverb-space=+\allowbreak\verb+visbreak]{xy}}]+.
  This command is robust.
\item[\verbatizee{\Q}\cearg{verbatimtext}]
  Similar to \verb+\PVerb+, but its argument must be escaped
  (see in Subsection \ref{escaped}), and it can be used in section titles etc.
  Must be enabled with \texttt{Q=yes}.
  This command is robust.
\item[$\div$\delarg{verbatimtext}$\div$]
  Similar to \verb+\PVerb+, but it can be used in section titles etc. (but not
  int \texttt{tabular}) (see in Subsection \ref{escaped}).
  Must be enabled with \texttt{div=yes}.
  This command is robust.
\item[\textbackslash$\div$\delarg{verbatimtext}$\div$]
  Equivalent to \verb+\Q+, but the argument delimiter is different.
  Similar to \verb+\PVerb+, but its argument must be escaped
  (see in Subsection \ref{escaped}), and it can be used in section titles etc.
  Must be enabled with \texttt{bsdiv=yes}.
  This command is robust.
\item[\verbatizee{\url}\cearg{url}]
  Must be enabled with \texttt{url=yes}.
  This command is robust.
%%%WF  az eleme jelet NE HASZNALD, osszesen 3-szor szerepel, irj
%%%    valamit, hogy pl.: (after laoding verbfwr package)
%%%    vagy valami hasonlot
%% -- javítva
\item[\verbatizee{\begin{WFile}}\cearg{filename}] (defined in the \textsf{verbfwr} package)
  Writes its contents verbatim to the specified file.
  \TeX{} \texttt{.tcx} and line ending transformations apply, so it is
  possible that accented letters will be converted to \verb+^^+hex according
  to the input encoding.
\item[\verbatizee{\begin{WAux}}] (defined in the \textsf{verbfwr} package)
  Writes its contents verbatim into the current \texttt{.aux} file.
  \TeX{} \texttt{.tcx} and line ending transformations apply, so it is
  possible that accented letters will be converted to \verb+^^+hex according
  to the input encoding.
\item[\verbatizee{\begin{PWSource}}\optarg{options}]
  Comination of \verb+\begin{WSource}+ and \verb+\PexaShow+\allowbreak\verb+Source+.
  It is recommended to have a \verb+[]+ even if there are no
  options, so the very first token of the contents will be read with proper
  catcodes.
\item[\verbatizee{\begin{WBoth}}]
  Writes its contents to the Source and the Sample temporary file. It is
  a combination of \texttt{WSample} and \texttt{WSample}.
\item[\verbatizee{\begin{WSample}}]
  Writes its contents to the Sample temporary file (\texttt{pexa-sam.\allowbreak tex}),
  to be typeset by a subsequent \verb+\PexaShowSample+ or
  \verb+\PexaShowBoth+.
  The line must end at \verb+\end{WSample}+ because of technical reasons.
\item[\verbatizee{\begin{WSource}}]
  Writes its contents to the Source temporary file (\texttt{pexa-src.\allowbreak tex}),
  to be typeset by a subsequent \verb+\PexaShowSource+ or
  \verb+\PexaShowBoth+. It is similar to
  \verb+\begin{verbwrite}+ in the \texttt{sverb} package
  and the \verb+\begin{+\allowbreak\verb+filecontents}+ \LaTeX{} built-in environment.
  The line must end at \verb+\end{+\allowbreak\verb+WSource}+ because of technical reasons.
\item[\verbatizee{\begin{PIgnore}}]
  Ignores everything up to \verb+\end{PIgnore}+. The environment closer must
  be at the end of its line. Similar to the \texttt{comment} environment in
  some other packages.
\item[\verbatizee{\begin{PSource}}\optarg{options}]
  Typesets its contents in display verbatim. Similar to the \LaTeX{}
  \verb+\begin{verbatim}+ environment, but respects the customization
  options. It is recommended to have a \verb+[]+ even if there are no
  options, so the very first token of the contents will be read with proper
  catcodes. This environment is similar to \texttt{PWSource}, but it doesn't
  create a temporary file, so it is faster, \texttt{srcstyle=leftboth} (etc.)
  can be used, and there is no ambiguity between \verb+^^e1+ and
  \texttt{\'a} (etc., see more in Subsection \ref{tcx}). Page breaks are
  allowed between each Source line. (The implementation of this environment
  is fairly complex compared to \texttt{PWSource}.)
\item[\verbatizee{\begin{verbatim}}]
  Equivalent to \verb+\begin{PSource}[]+.
  Must be enabled with \texttt{verbatimenv=yes}.
\item[\verbatizee{\begin{verbatim*}}]
  Equivalent to \verb+\begin{PSource}[source-space=visbrea+\allowbreak\verb+k]+.
  Must be enabled with \texttt{verbatimenv=yes}.
\item[\verbatizee{\begin{PexaMinipage}}\optarg{vbox-type}\cearg{width}]
  Similar to the \LaTeX{} \texttt{minipage} environment (and
  accepts the same arguments), but 
  isolates (concerning section numbers etc.) of its contents from the main
  document more thoroughly. See Subsection \ref{pexaminipage} for
  details of isolation.
\item[\verbatizee{\PexaShowBoth}\cearg{options}]
  Typeets the Source and the Sample side-by-side in display verbatim mode.
  The Source comes from the temporary file written by the last
  \texttt{WSource} or \texttt{WBoth} environment, and
  the Sample comes from the temporary file written by the last
  \texttt{WSample} or \texttt{WBoth} environment.
  By default, a vertical separator line is drawn between the Source and the
  Sample, and page breaks are allowed in the Source after the end of
  Sample.
  It can be called multiple times with different options for the same file.
%\item[\verbatizee{\PexaShowBothMany}]% Dat: for internal use
\item[\verbatizee{\PexaShowSample}\cearg{options}]
  Typesets the Sample (written by\,the\,last
  \texttt{WSample} or \texttt{WBoth} environment) in display mode.
  It can be called multiple times with different options for the same file.
%\item[\verbatizee{\PexaShowSampleMany}]% Dat: for internal use
\item[\verbatizee{\PexaShowSource}\cearg{options}]
  Equivalent to \verb+\PexaInputSource+ with the file written by the last
  \texttt{WSource} or \texttt{WBoth} environment.
  It can be called multiple times with different options for the same file.
%\item[\verbatizee{\PexaShowSourceMany}]% Dat: for internal use
\item[\verbatizee{\PexaInputSource}\cearg{filename}\cearg{options}]
  Typesets the contents of the specified file as Source in display verbatim
  mode.
% \item[\verbatizee{\PexaAddlastskip}] (not used anymore, see comment in lb.sty)
\item[\verbatizee{\begin{code}}] (defined in the \texttt{codep} package)
  Typesets its contents side-by-side and also marks its contents to be dumped
  to the CD. By default, each line is emitted to all 
%%%WF  thre 
  three
%%%
  streams, but lines
  with special prefixes will go into the Source, Sample or CD-file stream
  only. See Section \ref{code} for details.
\item[\verbatizee{\PexaAllowBreak}]
  Allows a line break here with a discreationary specified
  in the option \texttt{pverb-linebreakchar=} inserted.
\item[\verbatizee{\abreak}]
  A robust command which
  inserts \verb+\PexaAllowBreak+ when the font \verb+{\ttdefault}{m}{n}+
  is active; inserts \verb+\allowbreak+ otherwise.
  Must be enabled with \texttt{abreak=yes}.

\end{description}

\section{Writing examples with the \textsf{codep} package}\label{code}

Textbooks and manuals tend to have many display verbatim examples. The
examples are usually code snippets which can be further processed by a
compiler or another program.
Sometimes minor modifications, such as adding the proper header or trailer,
are necessary before the code snippet can be processed. It is customary to
put all code snippets in the book onto the CD accompanying the book. The
\texttt{code} environment of the \textsf{codep} package (part of the
\textsf{examplep} distribution) generates CD-files automatically.

Three streams are generated from the contents of each \texttt{code}
%%%WF environemnt: 
environment:
%%%
the Source, the Sample and the CD-file streams. Most parts of
these streams are identical. The Sample usually differs from the Source
because the code snippet has to be typeset specially in the book (for
example, \verb+\includegraphics+ has to be used to typeset an EPS file whose
Source is displayed). The CD-file differs from Source because additional
header and footer may be required (such as \verb+\begin{document}+ etc.),
which are omitted from the book to conserve space.

The \texttt{code} environment reads the code snippet line-by-line. The type
of the line is specified in first two characters. Lines having the default
type are written to all 3 streams, and special line types exist to write to a
specific stream only. The \texttt{code} environment writes the Source and
Sample streams to temporary files, and upon the end of the environment, it
calls \verb+\PexaShowBoth+ (or \verb+\PexaShowSource+, if the Sample stream
is empty) to typeset the example. The CD-file stream is not written to a file
by \TeX{}, but the file name and starting line number of the \texttt{code}
environment is reported in the \texttt{.aux} file. A \textsf{Perl} script
(\textsf{wrfiles.pl}, part of the \textsf{examplep} distribution) has to be
called later to the actual generaton of CD-files. It will examine the
\texttt{.aux} files, extract the CD-file stream from the \texttt{.tex} files,
and dump these streams to individual files in the \texttt{CDfiles} directory.
The file names can be specified in the \texttt{code} enviroment, and the
environment can generate file names based on chapter and page numbers (so the
reader will know from the file name where to read more about the example).
The same file name is never generated again.

The \textsf{code} package was used in our recent \LaTeX{} textbook \cite{lakk}
to typeset its examples. Most of the examples were written in \LaTeX{}, but
many 
%%%WF of of 
of
%%%
them were \textsf{METAPOST} sources, and some of them were others
(e.g.\ configuration files, shell scripts or EPS files). Because of the huge
amount of \LaTeX{} examples, special features were added to make them easy
and convenient to input for the author. For example,
\begin{verbatim}
\begin{code}
t \usepackage{url}
  URL:
  \\\url{http://foo.org/~user/}
\end{code}
\end{verbatim}
is displayed as (depending on the \textsf{examplep} options)
\par\medskip
\noindent\begin{tabular}{@{}l@{}l@{}l@{}}
{\scriptsize1}\verb+%^\usepackage{url}+&\ \vrule\ \null&URL:\\
{\scriptsize2}\verb+URL:+&\ \vrule\ \null&\verb+http//foo.org/~user/+\\
{\scriptsize3}\verb+\\\url{http//foo.org/~user/}+&&\\
\end{tabular}
\par\medskip\par
As seen above, examples are quite convenient to input, and \textsf{examplep}
takes care of typesetting side-by-side, determining width of the Source,
allowing page breaks, putting margins and \verb+\vskip+s right, adding the rule the
separate the Source and the Sample, adding line numbers, generating file name
for CD-file and writing the CD-file with header and footer.

With \textsf{codep} it is easy to fulfill the following quality criterias:
the Sample must be consistent with the Source (i.e.\ if the Source is
changed during editing to book, the Sample should change automatically); the
CD-file must be consistent with the Source; the CD-file must be directly
compilable with \LaTeX{} (so a header and a footer have to be added). When
the deadline of finishing the book approaches, there might not be enough time
left to ensure these manually, so a package such as \textsf{codep} is very
useful in this situation.

\subsection{Example files on the CD}\label{codewritereasons}

The following CD-file is generated from the code snippet above:
\begin{verbatim}
\documentclass{article}

\usepackage[latin2]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[magyar]{babel}
\usepackage{url}

\begin{document}

URL:
\\\url{http://foo.org/~user/}

\end{document}
\end{verbatim}

The \texttt{CodeDefaultD}, \texttt{CodeDefaultL}, \texttt{CodeDefaultB} and
\texttt{CodeDefaultE} environments can be used in the preamble to customize
the default header and footer generated into the CD-file. For example:
\begin{verbatim}
\begin{CodeDefaultD}
\documentclass[10pt]{article}
\end{CodeDefaultD}
\begin{CodeDefaultL}
\usepackage[latin2]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[english]{babel}
\end{CodeDefaultL}
\end{verbatim}

Although \TeX{} is able to write to external files with \verb+\textsfrite+, there
were several reasons for using an external program (a \textsf{Perl} script) to
extract the source snippets from the document sources:
%
\begin{itemize}

\item with \verb+\write+ the file always ends at end-of-line
\item \verb+\write+ forces \texttt{.tex} if no extension is specified
\item \verb+\write+ removes whitespace from end-of-line
\item \verb+\write+ translates accented letters to hat-escapes
      (e.g.\ \texttt{á} to \verb+^+\verb+^e1+) unless
      compiled with \texttt{latex --translate-file cp8bit.tcx}
      (\texttt{--translate-file il2-t1.tcx} makes \texttt{\H{o}} in DVI
      incorrect). There is the same problem when emitting UTF-8 text.
\item it is impossible to distinguish missing files from empty files,
      so accidental file overwrites are hard to prevent
\item it is too late to verbatize if the verbatim text is inside
      braced macro arguments

\end{itemize}
%
The only limitations of this solution are: is not possible to \verb+\input+
or \verb+\include+ a subfile, and then use the \texttt{code} environment in
the referrer file; the subfile has to be included with
\verb+\include{...}+ or \verb+\input{...}+ (with braces); 
and the subfile must have extension \texttt{.tex}.
The first one is usually not a problem, since referrer files themselves do not
typeset text, they only include subfiles. See Subsection
\ref{codeimpl} for implementation details.


\subsection{\texttt{\textbackslash begin\{code\}} invocation}

The input syntax of the \texttt{code} environment has been designed so that
typing the most common examples (short \LaTeX{} code snippets) is simple and
straightforward, but the author can have full control over all three streams
if he wants to. The contents of the environment is divided into lines. The
first two characters of each line specify the line type and the rest is the
line data.
% Lines with type \verb+% + are ignored.
The first character of the line type is usually a lowercase
ASCII letter or a punctuation symbol. Line types belong to classes, which are
denoted by capital ASCII letters. The order of the classes in the environment
is significant, but the order of the individual types or lines within the
class is irrelevant. Some classes have default lines, which are used
only if the class is omitted from the environment. The default lines make it
possible to have default CD-file header and trailer. The clases, in proper
order with allowed types in parentheses), are:
%
\begin{description}

\item[F (f, f!, v, v!)] specify the file name.

%    G |   |                         |ide visz egy F-beli parancs

\item[D (d)] the \verb+\documentclass+ line, default uses article

%%%WF kicsit fura, hogy a magyar a default, valami megjegyzessel itt
%%%enyhiteni kellene, pl hogy ez hogy irhato folul...
%% -- javítva
\item[L (l)] the preamble specific to the natural language, defaults for
  Hungarian \textsf{babel}, Latin-2 \textsf{inputenc}, T1 \textsf{fontenc}.
  Use the \texttt{CodeDefaultL} environment to override.

\item[P (p$\equiv$0, t)] the preamble with the \verb+\usepackage+ lines

\item[B (b)] \verb+\begin{document}+

\item[C (<$\equiv$c, >$\equiv$o, \textvisiblespace$\equiv$2, w, s, x, \%)] the document contents

\item[E (e)] \verb+\end{document}+

%    Z |   |                         |ide visz az \end{code}

\end{description}
%
The meaning of the complicated types are:
%
\begin{description}

\item[f] Accepts a file name with extension. The use of \verb+_+ in the name
  is not recommended. The extension (e.g.\ \texttt{.tex}) is mandatory. The
  chapter and page numbers will be prepended to the file name (only the
  page number for document classes without chapters), for example
  \texttt{f foo.mp} may become \texttt{2\textunderscore 63\textunderscore foo.mp} in chapter 2, on page 63.

\item[v] Like \texttt{f}, but removes the default lines from classes
  D, L, P, B and E. This is ideal for emitting non-\LaTeX{} examples.

\item[f!] Like \texttt{f}, but don't prepend numbers to the file name.

\item[v!] Like \texttt{v}, but don't prepend numbers to the file name.

\item[p$\equiv$0] Writes only to the preamble of the CD-file.

\item[t] Writes to CD-file, appends line prefixed by \verb+%^+
  to Source. Useful to indicate in the book that a package is needed.
  Example: \verb*+t \usepackage{url}+.

\item[<$\equiv$c] Writes to Source and CD-file.
\item[>] Writes only to Sample.
\item[x] Writes to Sample and CD-file.
\item[\textvisiblespace$\equiv$2] Writes %%%WF only 
         to Source, CD-file and Sample.
\item[w] Writes only to CD-file.
\item[s] Writes only to Source.
\item[\%] Comment, ignored.

\end{description}

The \texttt{code} environment omits the Sample part from the book if the
Sample is empty,
and it omits the whole display verbatim environment (but still writes to
CD-files) if both the Sample and Source are empty.

\subsection{An example with METAPOST code}

If the \textsf{eempost} package is also loaded, the following code can be
used to typeset a simple, syntax-highlighted \MP{} source and its output:
\begin{verbatim}
{\PexaDefaults{listings={language=metapost}}\begin{code}
v house.mp
> \begin{EempDef}{house.1}{}{}
w beginfig(1)
  u:=18bp; picture V; V:=image(
    draw unitsquare scaled u xscaled 2;
    fill (0,u)--(2u,u)--(u,1.5u)--cycle
      withcolor red);
  draw V rotated 10;
  draw V shifted (3u,0);
w endfig; end
> \end{EempDef}
> \leavevmode\EempUseFig{house.1}{0}{0}
% ^^^ Dat: \leavevmode to get the Overfull \hbox warning
\end{code}
} % Dat: nothing allowed after \end{code} in its line
\end{verbatim}
%
If \textsf{eempost} is not loaded, the following code should be used instead:
%
\begin{verbatim}
{\PexaDefaults{listings={language=metapost}}\begin{code}
v house.mp
> \begin{WFile}{house.mp}
x beginfig(2)
  u:=18bp; picture V; V:=image(
    draw unitsquare scaled u xscaled 2;
    fill (0,u)--(2u,u)--(u,1.5u)--cycle
      withcolor red);
  draw V rotated 10;
  draw V shifted (3u,0);
x endfig; end
> \end{WFile}
> \leavevmode\includemps{house.2}
\end{code}
}
\end{verbatim}
The \verb+\includemps+ command should be defined in the preamble as:
\begin{verbatim}
\usepackage{graphicx}
\DeclareGraphicsRule{*}{mps}{*}{}
\makeatletter
\@ifundefined{Ginclude@eps}{}{\def\Ginclude@mps{\Ginclude@eps}}
\def\includemps{\@ifnextchar[\includempsb{\includempsb[]}}
\def\includempsb[#1]#2{\includempsc{#1}#2\@nil}
\def\includempsc#1#2.#3\@nil{%
  \IfFileExists{#2.#3}{\includegraphics[#1]{#2.#3}}{
  \GenericWarning{}{Please run: mpost #2^^J\@gobble}}}
\makeatother
\end{verbatim}
This should work with both \textsf{dvips} and \textsf{pdflatex}. The typeset
output looks like this:\label{pag:use-listings}
\par\medskip
\noindent\begin{tabular}{@{}l@{}l@{}l@{}}
{\scriptsize1}u:=18\textbf{bp}; \textbf{picture} V; V:=\textbf{image}(          &\ \vrule\ \null&\\
{\scriptsize2}\ \ \textbf{draw} \textbf{unitsquare} \textbf{scaled} u \textbf{xscaled} 2;&\ \vrule\ \null&\\
{\scriptsize3}\ \ \textbf{fill} (0,u)$-${}$-$(2u,u)$-${}$-$(u,1.5u)$-${}$-$\textbf{cycle}&\ \vrule\ \null&
  \setbox0\hbox{\includegraphics{houses}}\ht0=0pt \box0 \\
{\scriptsize4}\ \ \ \ \textbf{withcolor} \textbf{red});		     &          &\\
{\scriptsize5}\textbf{draw} V \textbf{rotated} 10;		     &          &\\
{\scriptsize6}\textbf{draw} V \textbf{shifted} (3u,0);		     &          &\\
\end{tabular}
\par\medskip\par


\section{Some implementation details}

\subsection{Starting from poor man's inline verbatim}

The following macro, derived from a macro in the \texttt{.dtx} documentation
of David Kastrup's \textsf{binhex} package \cite{binhex},
typesets its argument in inline verbatim mode:
%
\begin{verbatim}
{\catcode\string`>12 \gdef\stripprefix#1>{}}
\def\verbatize#1{{\ttfamily
   \toks0{#1}\edef\next{\the\toks0}% Dat: make # OK
   \fontdimen2\font=0pt % Dat: hide spaces
   \expandafter\stripprefix\meaning\next
   \unskip % Dat: strip final space, possibly after command
   \fontdimen2\font=\dimen0}}% Dat: reset global change
\end{verbatim}
%
This demonstration show how useful the \TeX{} primitives \verb+\string+ and
\verb+\meaning+ are. Both of them convert tokens to characters with catcode
12 (other) or 10 (space). Token lists with spaces are hard to post-process by
\TeX{} macros, because \TeX{} macro expansion ignores spaces before
undelimited macro arguments. But it is possible to write a macro which
converts spaces to anything with catcode 12, for example the \verb+\sca+
macro below does this:
%
\begin{verbatim}
\begingroup\catcode\string``12 \lccode```\%\lowercase{\endgroup
  \def\scc#1 {\ifx\hfuzz#1\else#1`\expandafter\scc\fi}}
\def\scb#1#2{\scc#2\hfuzz#1} \def\sca{\scb{ }}
% try with: \message{\sca{foo  bar }}
\end{verbatim}
%
It is possible to change \verb+%+
in the definition above to anything, including a space: the replacement
character will have catcode 12. After such a conversion, the text to be
emitted can be easily processed to add \TeX{} macros, change catcodes back to
13 for ISO Latin high accented characters, replace spaces with appropriate
constructs, insert \verb+\allowbreak+ to the right places to enable line
breaks etc. The \verb+\PVerb+ macro, when invoked in inner mode (i.e.\ read
inside a macro argument) works this way, and respects the options specified
by the author.

\subsection{Hex escapes with output translation}\label{tcx}

The \TeX{} primitives \verb+\write+, \verb+\message+ and \verb+\errmessage+
may escape some characters when printing them. By default, \TeX{} changes the
code ranges 0--31 and 127--255 (the codes outside the printable ASCII range),
escaping such codes with a \verb+^^+: for example,
the tabulator (code 9) becomes \verb+^^I+, and characters having a high code
in the font (not the input) encoding are dumped in hexadecimal, for example
\texttt{\H{o}} (having code 174 in T1 encoding) becomes \texttt{^^ae}.
(This behaviour depends on the default \texttt{.tcx} file the \TeX{}
distribution uses. No translation occurs with \textsf{cp8bit.tcx}.
To spot the difference, run
\verb+tex -translate-file cp8bit "\messa+\allowbreak\verb+ge{^^I^^1f+\allowbreak\verb+á}\end"+, and then change
\texttt{cp8bit} to \texttt{.missing.}, and run again.)
The transformation is lossy: %, for example % e.g.\
both
\verb+\message{+\texttt{\H{o}}\verb+}+ and
\verb+\message{\string^^ae}+ yield the same result: \verb+^^ae+. Escaping the caret
as \verb+^^5e+ doesn't help either, because the \TeX{} unescapes carets
recursively when reading back the written file. Since ISO Latin
accented characters are
more often needed in verbatim environments than double carets,
\textsf{examplep} does the necessary unescaping when it reads the file back.
% Dat: doesn't work The back-transformation works with UTF-8, too, because it is timed properly.
The back-transformation doesn't work with UTF-8, because the 2nd byte is not
decoded by the time the first one is being executed.
The unescaping would be done by \TeX{} itself if the caret had its original
catcode 7, but that would imply that the non-escaping, verbatim carets
wouldn't work.

The unescaping is implemented in a straighforward, but ugly way in the
\verb+\pexa@dohex@low+\ldots{} macros. The caret escapes are parsed in a
huge \verb+\if+%\ldots
\verb+\else+\allowbreak\verb+\if+ construct nested in 40 levels, and once
the hexadecimal code is available and converted to upper case, the
\verb|\lccode`+="|$\langle$code$\rangle$\verb*|\lowercase{+}| construct is
used to insert the appropriate character with catcode 12 (\verb+~+ is
used instead of \verb|+| to get an active character, catcode 13). The
construct is not expandable, but it works because it is used for typesetting.
The caret is made active and defined to execute \verb+\pexa@dohex+, so each
caret in the file will get unescped.

\subsection{Disabling ligatures}

The only way to disable a ligature in \TeX{} is to insert a nonexpandable
tokens into the input stream between the characters forming the ligature.
For example, \verb+f{}i+ or \verb+f\relax i+ can be used to get ``f{}i''
instead of ``fi''. The most important ligatures (in addition to ligature
letters) to be disabled in verbatim mode are:
\verb+<<+ \verb+>>+ \verb+?`+ \verb+!`+ \verb+,,+ \verb+``+ \verb+''+
\verb+--+ and \verb+---+. This can be accomplised by inserting a \verb+\relax+
token in front of each \verb+`+ \verb+'+ \verb+,+ \verb+-+ \verb+<+
and \verb+>+. The \verb+\pexa@noligs@some+ command of \textsf{examplep} does
exactly this, for example, it defines
\verb+{\lccode`~`<13 \gdef~{\relax+\allowbreak\verb+\string~}}+. The definition
slightly different from the one of the \verb+\@noligs+ command in the
\LaTeX{} kernel: \verb+\def<{\leavevmode\kern\z@\char`\<}+; but the effect is
the same.  The \verb+\pexa@noligs@most+ command, on the other hand, makes
all characters with category code 12 in the range 32\ldots127 active, and
adds \verb+\relax+ to both sides. This change doesn't affect ASCII or
accented letters, but usually there are no ligatures with letters in
typewriter fonts. See also the \texttt{noligs=} load option.

\subsection{Detecting inner/outer brace in inline verbatim mode}

The \verb+\PVerb+ commands work differently based on whether they are inside
a macro argument or not. More precisely, they detect whether they are able
to change the catcode of the following token. If so, they are in outer mode
(i.e.\ outside a macro argument), so they change all the other catcodes as
well, so consecutive spaces and comment characters will be included in
verbatim, too. Otherwise, they are in inner mode, their argument is already
read and tokenized by \TeX{}'s eyes, so changing catcodes is pointless.

The auto-detection works this way: the catcode of all the special characters
(as enumerated in \verb+\dospecials+; including braces) is changed to 3
(math-shift). Then the next token is read into \verb+\reserved@a+ with
\verb*+\afterassignment\pexa@+\allowbreak\verb+cverb@gottoken\let\reserved@a= +. No tokens are
ignored this way, not even spaces. The \verb+\pexa@cverb@gottoken+ macro then
examines the catcode of the character in
\verb+\reserved@a+, and if it is 3, it continues in
outer mode, otherwise it continues in inner mode. In inner mode, the next
token is forced to be an open-brace, because verbatim material with braces
not nested cannot be read into inner mode anyway (\TeX{} would print an error
message when it is trying to find the end of the macro argument containing
the \verb+\PVerb+ construct).

Another common trick is used when parsing the argument in outer mode when it
is delimited by braces. Normally a \TeX{} macro expansion
(using the definition \verb+\def\pexa@cverb@outerc#1{...}+) can read an
argument that is in braces, but in our case the very first opening brace has
been already read (by \verb+\let+ above), so we have to insert it back:
\verb+\catcode`\{1 \catcode`\}2 \ex+\allowbreak\verb+pandafter\pexa@cverb@outerc\expandafter{\iffalse}\fi+.
The \verb+\iffalse+\allowbreak\verb+}\fi+ here is needed for making the definition properly
nested.

\subsection{Inline verbatim in section titles}

The \TeX{} command \verb+\write+, \verb+\message+ and \verb+\edef+ fully
expand their arguments, and similar expansion is enforced by the
\verb+\markboth+ built-in \LaTeX{} macro for section titles and page
headings. Therefore macros in section titles have to be protected so their
expansion is delayed until the section title is typeset. \LaTeX{} offers
\verb+\protect+ for this: if the macro control sequence is preceded by
\verb+\protect+, its expansion is properly delayed; the expansion of the
argument has to be delayed manually in a similar way. Some macros have
\verb+\protect+ion included; they are called ``robust''. If the definition a
macro starts with \verb+\DeclareRobustCommand+ instead of \verb+\newcommand+,
the macro is defined to be robust (and its body can be retrieved by looking
at the control sequence with a space added, e.g.\
\verb*+\expandafter\show\csname sqrt \endcsname+).

\verb+\protect+ can have three definitions depending on what time it is
processed: it is \verb+\string+ in a \verb+\typeout+ or a \LaTeX{} error or
warning message (try \verb+\typeout{\meaning\protect}+);
it is \verb+\noexpand\protect\noexpand+ when
\verb+\write+ing to a file (most commonly the \texttt{.aux} file); otherwise
it is just \verb+\relax+ ($\equiv{}$\verb+\@typeset@protect+; try
\verb+\pagestyle{headings}\section{\meaning\pro+\allowbreak\verb+tect}+ and spot the difference
between the main text, the section title and the \texttt{.aux} file).

The \verb+\÷+ and \verb+\Q+ inline verbatim commands are made robust, so they
can be used in macro arguments. In fact, they are extra-robust, since they
take care of protecting their arguments when being written to a file by
\LaTeX{}. Protecting here means adding \verb+\noexpand+ in front of each
token in the argument. The token parsing is easy since the argument -- by the
nature of these commands -- may not contain braces or spaces. The
implementation looks like this.
%
\begin{verbatim}
\long\def\÷#1÷{\Q{#1}}
\long\def\Q{\ifx\protect\@typeset@protect\expandafter\@gobble\fi
  \@thirdofthree\@firstoftwo\displayit\protectit}
\def\displayit#1{...}
\def\protectit#1{\noexpand\÷\protectnext#1÷}
\long\def\protectnext#1{\noexpand#1%
  \ifx#1÷\else\expandafter\protectnext\fi}
\end{verbatim}
%
The first trick is in the body of \verb+\Q+: the argument is passed to
either \verb+\displayit+ or \verb+\protectit+, depending on the current value
of \verb+\protect+. If the condition is true, \verb+\@gobble+ is called,
which removes \verb+\@thirdofthree+, so \verb+\@firstoftwo+ will choose
\verb+\displayit+ (otherwise, \verb+\@thirdofthree+ chooses
\verb+\protectit+).
The second, more classical trick is the r\^ole of
\verb+\expandafter+ in the definition of \verb+\protectnext+: it makes the
\verb+\fi+ token disappear, so the tail-recursive call to \verb+\protectnext+
will grab the next token into \verb+#1+ instead of \verb+\fi+ itself.


\subsection{Special hyphenchar in inline verbatim}\label{char'30}

When inline verbatim is hyphenated, care has to be taken to make the
discretionary hyphen different from a regular, verbatim hyphen. (There is a
similar problem with spaces disappearing when the line is broken; to avoid
this, try setting the option \texttt{pverb-space=visbreak} or
\texttt{pverb-space=invdisc}.) \TeX{} auto-hyphenation takes the
discretionary hyphen from the \verb+\hyphenchar+ of the font. So the solution
is adding a new glyph to the verbatim font, changing the font encoding
vector to include the glyph, and then setting \verb+\hyphenchar+.

We have chosen character position 24 (per-thousand sign) of the T1 encoding to
be replaced by a soft hyphen (\includegraphics[scale=0.009]{shorthyp_t1xtts}),
which is deliberately narrower than all the other characters, so the
reader immediately sees its function. For example:
``\texttt{foo\includegraphics[scale=0.009]{shorthyp_t1xtts}\break bar}''.
We have drawn the glyph in \textsf{Fontforge}, saved the data to PFB,
converted it to human-readable format with the command
\texttt{type1fix.pl shorthyp.pfb gsx: shorthyp.gsx}, extracted the human
readable glyph definition (\verb+/short+\allowbreak\verb+hyp { ... }+) from the output.
We have changed the \texttt{/FontName} and
injected the glyph to original font with the following command:
%
\begin{verbatim}
perl -x -S type1fix.pl --set-leniv=0 --dump-spaces=no --pack \
  --dump-bars --dump-stde --dump-ends=no --debug-warnings \
  --chk-insize=no --set-uniqueid=random --set-fontname=t1xtts \
  --set-glyph="/shorthyp { 50 354 hsbw 315 vmoveto -17 vlineto 0
  -8 0 -8 6 -4 rrcurveto 4 -6 8 0 5 0 rrcurveto 195 hlineto -124
  vlineto -11 0 -21 15 vhcurveto 2 0 3 1 2 1 rrcurveto 10 2 1 12
  0 12 rrcurveto 0 8 -1 8 0 5 rrcurveto 130 vlineto 0 5 1 7 0 7
  rrcurveto 0 12 -2 11 -11 3 rrcurveto -5 1 -6 0 -5 0 rrcurveto
  -12 0 -12 -1 -10 0 rrcurveto -98 hlineto -16 0 -19 2 -17 0
  rrcurveto -32 -6 -3 -24 hvcurveto closepath endchar} def" \
  t1xtt.pfb pfb: t1xtt-shorthyp.pfb
\end{verbatim}
%
We have changed six lines in \textsf{tex256.enc} to match the glyph names
in the font (e.g. \texttt{/endash} $\to$ \texttt{/rangedash}), and we have
changed position 24 to \texttt{/shorthyp}. We have also changed the name of
the encoding in the beginning of the file. We have inserted the following
line to the PostScript font map files (e.g.\ \textsf{psfonts.map}), without
the line break:
%
%   into psfonts.map:
%   ul9r8r LuxiMono "TeXBase1-shorthypEncoding ReEncodeFont" <8r-shorthyp.enc <ul9r8a-shorthyp.pfb
\begin{verbatim}
t1xtts t1xtts "TeX256-shorthypEncoding ReEncodeFont"
  <tex256-shorthyp.enc <t1xtt-shorthyp.pfb
\end{verbatim}
%
We have
also added a new TFM file based on the old one. We have dumped the old one
with \texttt{tftopl -charcode-format=octal t1xtt.tfm}, modified the
width (\texttt{CHARWD}) of character 24 (\texttt{CHARACTER O 30}), and saved
the modifications with \texttt{pltotf modified.pl t1xtts.tfm}.
We've added the \LaTeX{} font map file \textsf{t1xtts.fd} with the following
content:
%
\begin{verbatim}
\DeclareFontFamily{T1}{xtts}{\hyphenchar\font\m@ne}
\DeclareFontShape {T1}{xtts}{m}{n}{<->t1xtts}
\end{verbatim}
%
The \verb+\hyphenchar+ settings above disables automatic word hyphenation, so
words inside \verb+\texttt+ etc.\ won't be accidentally hyphenated. We have
copied all the files above to the appropriate directories and we have run
\textsf{mktexlsr} to update the file list. We have included some options in
\verb+\PexaDefaults+ line in the document preamble:
  \texttt{pverb-hyphenchar=char'30} (for automatic word hyphenation)
  \texttt{pverb-linebreak=char},
  \texttt{pverb-linebreakchar=}\verb*+{\string\char'30 }+ (insert\-ed around symbols).
We have also defined
\verb+\def\pexa@verbatimfont{\normal+\allowbreak\verb+font\fontfamily{xtts}\selectfont}+,
and we have made sure that the T1 encoding is in use
(\verb+\usepackage{t1enc}+).

The overall effect of these modifications was that \textsf{examplep} now used
our glyph for automatic word hyphenation and as discreationary hyphen around
symbols in inline verbatim mode. The demonstrations above shows that it is
quite complicated to change a single glyph in a \LaTeX{} font. It is hoped
that the situtation will improve with \TeX's successors.


\subsection{Passing information about the CD-files to \textsf{wrfiles.pl}}\label{codeimpl}

\textsf{wrfiles.pl} is used to extract the CD-files from the \LaTeX{} sources
of a book. The reasons why an external program is used instead of \TeX{}'s
built-in \verb+\write+ command are described in Subsection
\ref{codewritereasons}.

The file names and environment start line numbers are passed to
\textsf{wrfiles.pl} in the \texttt{.aux} file(s). For example, the line
\verb+\@gobble{code:foo.tex:156:2_pic3.+\allowbreak\verb+mp}+ is a declaration that there is a
\texttt{code} environment starting at line 156 in the file \texttt{foo.tex}.
\textsf{wrfiles.pl} understands such declarations, and it also understands
lines like \verb+\@input{foo1.aux}+, so dumping works even if the document is
separated to several \verb+\include+d source files. The declaration above is
ignored by \LaTeX{} when it reads back the \texttt{.aux} file (because
\verb+\@gobble+ gobbles its argument).

Although the \verb+\inputlineno+ primitive is mentioned twice in the
\TeX{}book \cite{texbook}, its -- rather straightforward -- purpose is not
documented there. But the real problem is that \TeX{} doesn't remember the
name of the file being read. \verb+\jobname+ contains the name of the
top-level \texttt{.tex} file, so it doesn't work when that file
\verb+\include+s or \verb+\input+s subfiles containing \texttt{code}. The
\textsf{codep} package thus modifies the \verb+\InputIfFileExists+ command to
save the file name to the macro \verb+\codep@code@@inputfile+ if the
extension is \texttt{.tex}. (The other most common extension after the preamble is
\texttt{.fd}: such a file is loaded each time a \LaTeX{} font that has not
been used yet is selected.) The implicit limitation here that \texttt{code}
won't work unless the extension of the file included is \texttt{.tex}.
Hooking \verb+\InputIfFileExists+ affects \verb+\include{...}+ and
\verb+\input{...}+, but not not \verb*+\input ...+, \verb+\documentclass+ or
\verb+\usepackage+. This is not a problem if the author remember that he has
to use braces around the file name.

Since there is no hook for \verb+\endinput+ (and some packages rely on that
\verb+\endinput+ is an expandable primitive), it is not possible to set up a
stack of names of files being read. Thus, if file $A$ has included file $B$,
an after that \texttt{code} environment placed in $A$ will not work, because
the declaration line read by \textsf{wrfiles.pl} will contain the name of $B$
instead of $A$. This is not a serious limitation, becase files including
other files usually don't typeset text by themselves after the inclusion.

The primary reason why \textsf{wrfiles.pl} needs the \texttt{.aux}
file is that it has to embed the page and chapter numbers into the file
names. Although \textsf{wrfiles.pl} could find the source file with the
\texttt{code} environments by trying to match line numbers with all source
files in the current directory, we have decided to make it fail when the file
name is not emitted properly into the declaration, so it is sure that the
examples in the book and on the CD are consistent.


\section{Future work}

The most important features to be added and other improvement possibilites:

\begin{itemize}

%\item func-tion better hyphenation point in \verb+\Q+ than functi-on
\item a better approach towards automatic hyphenation of inline verbatim,
      after studies in typography
\item allow wider sample if source is small enough
\item why doesn't \verb+\selectlanguage+ work inside
  \verb+\begin{PSource}[srcstyle=+\allowbreak\verb+leftboth]+
\item \verb+\PVerb{foo}+ mustn't insert ``$\lnot$'' if foo is at end-of-line
\item \verb+\PVerb{...}+ inner unnested braces (\verb+\futurelet+?)
\item differentiated \verb+\penalty+ values in \verb+\PVerb+
\item paragraph mode should work with side-by-side displays (of course,
      measuring the width of the Source has still to be done in aligned mode)
\item ASCII tabulator (9) characters aren't supported properly, they are just
  converted to spaces. The width of the tab character should depend on its
  horizontal position in the line. (With \texttt{listings=}, the results are
  already correct.)
\item framing and background color support to display verbatim
\item accented characters should work with \textsf{listings} and
      \verb+\PexaShowBoth+. The original catcode of \verb+^+ should be kept
      so \TeX{} itself would parse the hex escapes.
\item an interface to \verb+\lstinline+ in \textsf{listings}, with line
      breaks allowed
\end{itemize}

\section{Conclusion}

\textsf{examplep}, as it is now, is a highly customizable \LaTeX{} package
that provides both inline and display verbatim mode with several advanced
features, many of which are not available in any other packages. The
\textsf{code} environment is also provided which can typeset both the Source
and the Sample column of a side-by-side display verbatim from the same
\LaTeX{} source stream, furthermore it can emit the stand-alone working
version of the Source into a CD-file. These features make the \textsf{code}
environment especially useful for sofware textbook and manual authoring. The
whole \textsf{examplep} distribution is under the GNU GPL, and it is freely
available from CTAN. An earlier version of the packages was used to typeset
all the examples in a 770-page introductionary book about \LaTeX{}.

\textsf{examplep} is not complete. Some important features are not
implemented yet and the package has not been tested thoroughly. Some parts of
the code are really ugly, partially because it has not been polished up after
writing, and partially because the architecture of \TeX{} and \LaTeX{}
doesn't provide an elegant way to address the problem. For example, active
characters are overloaded: they are used by \textsf{inputenc}, \textsf{babel}
(shorthands) and \textsf{listings} (syntax highlighting) for different
purposes -- these packages have to make extra effort to cooperate with each
other. We hope that \TeX's successors will improve these
conditions, and the core system will provide a generic way to tokenize
verbatim text instead of changing catcodes.

\iffalse
\bibliographystyle{plain}
\bibliography{eurotex_2005_examplep}
\else
\begin{thebibliography}{1}

\bibitem{listings}
Carsten Heinz.
\newblock {\em The \textsf{Listings} Package}, 7~September 2004.
\newblock \\CTAN:\texttt{macros/latex/contrib/listings/listings-1.3.dtx}.

\bibitem{binhex}
David Kastrup.
\newblock {\em The \texttt{binhex.tex} package for expansible conversion into
  binary-based number systems}, 2001.
\newblock \\CTAN:\texttt{macros/generic/kastrup/binhex.dtx}.

\bibitem{texbook}
Donald~E. Knuth.
\newblock {\em The {{\TeX}book}}.
\newblock Addison--Wesley, 1984.

\bibitem{lakk}
Ferenc Wettl, Gyula Mayer, and P\'eter Szab\'o.
\newblock {\em {\LaTeX} k\'ezik\"onyv}.
\newblock Panem, Budapest, 2004.

\bibitem{fancyvrb}
Timothy~Van Zandt, Denis Girou, and Sebastian Rahtz.
\newblock {\em The `\textsf{fancyvrb}' package. Fancy Verbatims in \LaTeX{}},
  1998.
\newblock \\CTAN:\texttt{macros/latex/contrib/fancyvrb/fancyvrb.dtx}.

\end{thebibliography}
\fi

\end{document}