summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/mdwtools/sverb.dtx
blob: df12c8c1df8d4c6ece552390277f499f449957d4 (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
% \begin{meta-comment}
%
% $Id: sverb.dtx,v 1.3 1996/11/19 21:01:18 mdw Exp $
%
% Verbatim typesetting done properly (ahem)
%
% (c) 1996 Mark Wooding
%
%----- Revision history -----------------------------------------------------
%
% $Log: sverb.dtx,v $
% Revision 1.3  1996/11/19 21:01:18  mdw
% Entered into RCS
%
%
% \end{meta-comment}
%
% \begin{meta-comment} <general public licence>
%%
%% sverb package -- handling of verbatim text
%% Copyright (c) 1996 Mark Wooding
%%
%% This program is free software; you can redistribute it and/or modify
%% it under the terms of the GNU General Public License as published by
%% the Free Software Foundation; either version 2 of the License, or
%% (at your option) any later version.
%%
%% This program is distributed in the hope that it will be useful,
%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%% GNU General Public License for more details.
%%
%% You should have received a copy of the GNU General Public License
%% along with this program; if not, write to the Free Software
%% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%%
% \end{meta-comment}
%
% \begin{meta-comment} <Package preamble>
%<+package>\NeedsTeXFormat{LaTeX2e}
%<+package>\ProvidesPackage{sverb}
%<+package>                [1996/05/08 1.3 Verbatim typesetting]
% \end{meta-comment}
%
% \CheckSum{651}
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%%
%
% \begin{meta-comment}
%
%<*driver>
\input{mdwtools}
\describespackage{sverb}
\mdwdoc
%</driver>
%
% \end{meta-comment}
%
% \section{User guide}
%
% The \package{sverb} package provides some useful commands and environments
% for doing things with verbatim text.  I prefer this code to the standard
% \package{verbatim} package (by Rainer Sch\"opf et al.)\ although I'm
% biased.
%
% The package was written to fulfil a particular purpose: I wanted to be able
% to typeset ARM assembler code, 77~columns wide, on A5~paper, with the
% fields separated by \textit{tab} characters.  It's grown up fairly
% organically from that, and I've tidied it when I've seen the code get too
% ugly.
%
% The current features are:
%
% \begin{itemize}
%
% \item A `listing' environment which typesets verbatim text nicely.
%
% \item A command to read verbatim text from an external file.
%
% \item Support for arbitrary-sized chunks of text without overflowing \TeX's
%       memory.
%
% \item Support for \textit{tab} characters in the verbatim text.
%
% \item An environment for typesetting demonstrations of \LaTeX\ markup.
%
% \item It all works correctly with the \package{doc} system for documenting
%       \LaTeX\ packages.
%
% \item A fairly hairy but quite powerful programmer interface to the yukky
%       bits of the package.
%
% \end{itemize}
%
% The interface is described in its own section, so that more timid readers
% can avoid it.  That said, some of the stuff in this section gets rather
% technical.
%
% Note that this package doesn't even try to do anything with short bits of
% verbatim text (as handled by the |\verb:...:| command).  I have a separate
% package (\package{syntax}) which does all sorts of horrible things along
% those lines.
%
% \subsection{The \env{listing} environment}
%
% \DescribeEnv{listing}
% The main method for typesetting verbatim text is the \env{listing}
% environment.  This works pretty much the same as the standard
% \env{verbatim} environment, with some exceptions, which are described
% below.
%
% So that you know exactly what you're getting, here are the rules by which
% \package{sverb} decides what the verbatim text actually is:
%
% \begin{itemize}
%
% \item If there's any text, other than spaces, on the same line as the
%       `|\begin{listing}|', then the contents of the environment begins
%       immediately after the closing brace (with all leading spaces
%       preserved).  Otherwise, the text begins on the following line.
%
% \item If there is any text, other than spaces, before the
%       `|\end{listing}|', but on the same line, this is considered to be the
%       last line of the text; otherwise the text is presumed to have ended
%       at the end of the previous line.
%
% \item Any text following the |\end{listing}| on the same line is thrown
%       away.  There are good reasons for this, but they're technical.
%       Essentially there's nothing I can do about it.
%
% \end{itemize}
%
% \begin{figure}
% \begin{demo}[w]{The \env{listing} environment}
%\dots in the following code:
%
%\begin{listing}
%init            MOV     R0,#200         ;Version 2.00 please
%                LDR     R1,=&4B534154   ;Magic number (`TASK')
%                ADR     R2,appName      ;Find application name
%                SWI     Wimp_Initialise ;Register as a WIMP task
%\end{listing}
%
%The next step is to \dots
% \end{demo}
% \end{figure}
%
% Tab characters are supported within the environment: tab stops are set
% every eighth column, although this can be modified.
%
% \subsubsection{Configuring the \env{listing} environment}
%
% The text size used in the \env{listing} environment is set by the
% |\listingsize| command.  By default, this is set to |\small|, although you
% can redefine it in the document preamble, or it can be set in the document
% class.
%
% The amount by which the listing text is indented is controlled by the
% |\listingindent| length parameter.  This is a fixed length, whose default
% value is 1\,em.
%
% \subsubsection{Choosing a different end-text}
%
% \DescribeEnv{listing*}
% The \env{listing} environment is terminated by the exact character sequence
% `|\end{listing}|'.  This isn't too much of a problem, unless you want to
% include this string in the text.  This is achieved by the \env{listing$*$}
% environment, which allows you to specify the end-text to find as an
% argument.
%
% For example:
%
% \begin{demo}{The \env{listing$*$} environment}
%Type a listing as follows:
%
%\begin{listing*}{<end-listing*>}
%\begin{listing}
%This is a listing.  Yes.
%\end{listing}
%<end-listing*>
%\end{demo}
%
% Don't include `special' characters in your chosen end-text unless you know
% what you're doing.
%
% \subsection{Writing text to a file}
%
% \DescribeEnv{verbwrite}
% You can write verbatim text to a file using the \env{verbwrite}
% environment.  The syntax is fairly straightforward:
%
% \begin{quote}
% \syntax{"\\begin{verbwrite}{"<file-name>"}" \dots "\\end{verbwrite}"}
% \end{quote}
%
% The text of the environment is written to the named file.  The rules about
% where the text actually starts and ends are the same as for the
% \env{listing} environment.
%
% There is also a $*$-variant, like \env{listing$*$}, which allows you to
% choose the end-text.  The end-text is the first argument, the filename
% comes second.
%
% There is a restriction on the characters you can write to the file: they
% must all be considered `printable' by \TeX; otherwise they will be read
% back in as `\syntax{"^^"<chars>}' which isn't too good.  Unfortunately,
% this includes tab characters, so you can't write them.\footnote{^^A
%   Well, not without doing serious surgery on \TeX\ itself, anyway. }
%
% \iffalse [Example time...  Ho hum.  There is evilness here.] \fi
%\begin{verbwrite*}{<end-write>}{wrdemo1.tmp}
%\begin{verbwrite}{wrdemo.tmp}
%This is some text written to
%a file near the beginning of
%the file.
%\end{verbwrite}
%<end-write>
%
% For example: \verbinput{wrdemo1.tmp}
%
% \input{wrdemo1.tmp} \iffalse [Now build the file ;-) ] \fi
%
% \subsection{The \cmd\verbinput\ command}
%
% \DescribeMacro{\verbinput}
% You can input a pre-prepared text file exactly as it is in the input using
% the |\verbinput| command.  The filename is given as an argument.  For
% example:
%
% \begin{demo}{The \cmd\verbinput\ command}
%\verbinput{wrdemo.tmp}
% \end{demo}
%
% \subsection{The \env{demo} environment}
%
% Package authors need to document their packages, and it's common to want
% to display examples showing the original text and the output side-by-side
% (or, when space doesn't permit this, one above the other).  Both the
% \LaTeX\ book and \textit{The \LaTeX\ Companion} contain such examples.
%
% The \env{demo} environment allows such displays to be created easily.  The
% syntax of the environment is as follows:
%
% \begin{quote}
% \syntax{"\\begin{demo}["<shape>"]{"<title>"}" \dots "\\end{demo}"}
% \end{quote}
%
% The optional \synt{shape} argument can be either `|w|' (wide), or `|n|'
% (narrow).  A `wide' shape places the input and output one above the other,
% while the `narrow' shape puts them side-by-side.  The default shape is
% `narrow'.  An attractive border is drawn around the display to finish it
% off nicely.
%
% An example:
%
%\begin{demo*}{<end-demo>}[w]{The \env{demo} environment}
%\begin{demo}{From the \textit{\TeX book}}
%\[ \sum_{p\;\rm prime}
%   f(p) = \int_{t>1}
%      f(t)\,{\rm d}\pi(t) \]
%\end{demo}
%<end-demo>
%
% \DescribeEnv{demo*}
% As with the other environments created by this package, there's a
% $*$-variant which takes the end-text as an argument.
%
%
% \section{Programmer interface}
%
% This section describes the publicly available routines provided by the
% \package{sverb} package.  Routines not described here are libable to be
% changed or even removed without warning, so don't use them.
%
% \subsection{Environment hooks}
%
% Each of the environments created here works in the same way.  For each
% environment \env{foo}, there's a main command responsible for doing the
% work, called |\sv@foo|.  This is given all the arguments of the normal
% environment, and two more:
%
% \begin{itemize}
%
% \item The `end-text' to search for, which marks the end of the environment.
%
% \item Some actions to perform after the text has been read and processed.
%       This allows the calling macro to do some extra actions, like closing
%       boxes, etc.
%
% \end{itemize}
%
% All the environments do is call the main command with appropriate
% arguments.
%
% \subsection{Reading the verbatim text}
%
% \DescribeMacro{\sv@read}
% The main scanning routine is |\sv@read|.  It is called with three
% arguments:
%
% \begin{itemize}
%
% \item The end-text marking the end of the environment.
%
% \item The name of a macro (which must be a single token) which is called
%       with a line of text as its single argument.  This is given each
%       line of text which is read from the environment in turn.
%
% \item A macro, or other sort of action, which is to be done when the text
%       has been read and processed.
%
% \end{itemize}
%
% The macro |\sv@read| assumes that the caller has already made some
% provision for removing the category codes of the following text, by either
% calling |\@verbatim| or using the construction
% \begin{listing}
%\let\do=\@makeother
%\dospecials
% \end{listing}
%
% \DescribeMacro{\sv@safespc}
% Note that any space characters you read using |\sv@read| will be catcoded
% as |\active|.  Normally this is OK because |\obeyspaces| (or
% |\@vobeyspaces|) will be in effect.  If you're doing something more exotic,
% like writing text to a file or building a command string, you can call
% |\sv@safespc| which defines the active-space character to be a normal
% whitespace-space when expanded.
%
% \implementation
%
% \section{Implementation}
%
% This section defines several macros and environments which allow verbatim
% typing, with a high degree of configurability.  OK, so this sort of
% thing's been done so often before that it isn't true, but I don't really
% care.
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% \subsection{Simple things}
%
% To help us build funny macros which involve strange and different category
% codes, I'll write some simple macros which I can use while building my
% complicated and clever ones.
%
% \begin{macro}{\@cspecials}
%
% This macro is used to assist the definition of some of the environments.
% It makes `|\|', `|{|' and `|}|' into `other' characters, and replaces them
% with `\verb"|"', `|<|' and `|>|' respectively.  Note that `|[|' and `|]|'
% aren't used, because they make defining commands which take optional
% arguments awkward.  Note that we open a group here.  This should be closed
% using \verb"|endgroup" at the end of the special section.
%
%    \begin{macrocode}
\def\@cspecials{%
  \begingroup%
  \catcode`|0%
  \catcode`<1%
  \catcode`>2%
  \catcode`\{12%
  \catcode`\}12%
  \catcode`\\12%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sv@startlisting}
%
% This macro sets everything up nicely for a \env{listing}-type verbatim
% environment.
%
%    \begin{macrocode}
\def\sv@startlisting{%
  \def\par{\@@par\penalty\interlinepenalty}%
  \@@par%
  \leftskip\@totalleftmargin%
  \obeylines%
  \@noligs%
  \let\do\@makeother\dospecials%
  \verbatim@font%
  \frenchspacing%
  \@vobeyspaces%
  \settabwidth%
  \catcode9\active%
  \lccode`\~9\lowercase{\let~\sv@vtab}%
  \lccode`\~13\lowercase{\let~\vinput@cr}%
  \interlinepenalty500%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsection{Tab character handling}
%
% One of the things we want to do here is handle tab characters properly.
% (Here, `properly' means `moving to the next column which is a multiple of
% eight', the way these things were always meant to.)
%
% \begin{macro}{\settabwidth}
%
% The tabs used by our tabbed verbatim environments are set up by this
% routine.  It sets the tab width parameter |\svtab| to 8 times the width
% of a |\tt| space.  If you really want, you can redefine this macro.
%
%    \begin{macrocode}
\newdimen\svtab
\def\settabwidth{\setbox\z@\hbox{\texttt{\space}}\svtab8\wd\z@}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sv@vtab}
%
% Here we handle tabs inside verbatim environments.  We expect each line to
% be typeset as a box, using something like
%
% \begin{listing}
%\setbox0\hbox{#1}
%\leavevmode
%\box0
%\par
% \end{listing}
%
% The idea is that you make tab active, and set it to this macro.  We stop
% the current box, stretch it to the right width, and start another one
% straight after, so nobody know the difference.  The code here is straight
% from Appendix~D of \textit{The \TeX book}.
%
%    \begin{macrocode}
\def\sv@vtab{%
  \hfill\egroup%
  \@tempdima\wd\z@%
  \divide\@tempdima\svtab%
  \multiply\@tempdima\svtab%
  \advance\@tempdima\svtab%
  \wd\z@\@tempdima%
  \leavevmode\box\z@%
  \setbox\z@\hbox\bgroup%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\verbinput}
%
% We allow input from a file, by the |\verbinput| command.  We display the
% text pretty much the same as the \env{listing} environment below.
%
% We set tab and return active, and get them to do appropriate things.  This
% isn't actually all that hard.
%
%    \begin{macrocode}
\def\verbinput#1{%
  \begin{listinglist}%
  \listingsize%
  \sv@startlisting%
  \setbox\z@\hbox\bgroup%
  \input{#1}%
  \sv@stripspc%
  \egroup%
  \ifdim\wd\z@=\z@%
    \ifhmode\par\fi%
  \else%
    \leavevmode\box\z@\par%
  \fi%
  \end{listinglist}%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\vinput@cr}
%
% This macro handles return characters while inputting text in |\verbinput|.
% We just output our current box, and start another.
%
%    \begin{macrocode}
\def\vinput@cr{%
  \egroup%
  \leavevmode\box\z@%
  \par%
  \setbox\z@\hbox\bgroup%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsection{Reading verbatim text}
%
% The traditional way of reading verbatim text is to use a delimited
% argument, as described in the \textit{\TeX book}.  This works well-ish if
% the text isn't very long.  A better solution would be to pick out the text
% line-by-line and process it like that.  So this is what we do.
%
% \begin{macro}{\matcher}
%
% For long verbatim environments, we need to be able to find the end text.
% This is rather tricky.  The solution here is rather horrible.  The
% environment picks out each line of the text at a time, as an argument, and
% tests to see if it contains the text we're after.  We do the test in a
% particularly yukky way: we add the actual target text to the end of the
% line, and inspect the text following the match to see if the match is at
% the end.
%
% The |\matcher| macro creates a `matcher' which will test strings to see if
% they contain something interesting.
%
% To create a matcher, say
% \syntax{"\\matcher{"<cmd-name>"}{"<target>"}{"<process-cmd>"}"}.  The
% command \synt{cmd-name} accepts a line of text as an argument and calls
% the \synt{process-cmd} with the text of the line before the match, or the
% whole lot.  It also sets |\@ifmatched| appropriately.
%
% (Having spent ages coming up with this cruft myself, I found some very
% similar, but slightly better, code in Appendix~D.  So I've changed mine to
% match Donald's.  Anyway, credit where it's due: cheers Don.)
%
%    \begin{macrocode}
\newif\if@matched
\def\matcher#1#2#3{%
  \expandafter\def\csname\string#1$match\endcsname##1#2##2##3\end{%
    \ifx##2\relax%
      \@matchedfalse%
    \else%
      \@matchedtrue%
    \fi%
    #3{##1}%
  }%
  \expandafter\def\expandafter#1\expandafter##\expandafter1\expandafter{%
    \csname\string#1$match\endcsname##1#2\relax\end%
  }%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sv@stripspc}
%
% This macro strips any trailing glue in the current horizontal list.  This
% is fairly simple, actually: we just loop while glue is the last item.  It's
% slightly complicated by penalties which \TeX\ puts into the list between
% the glue items, but we just remove them too.
%
%    \begin{macrocode}
\def\sv@stripspc{%
  \unpenalty%
  \ifdim\lastskip=\z@\else%
    \unskip\expandafter\sv@stripspc%
  \fi%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sv@percent}
%
% This macro strips a single leading percent character if there is one, and
% if the \env{doc} package is loaded.  We store the possibly stripped text in
% |\@tempa|.
%
%    \begin{macrocode}
\begingroup
\catcode`\%=12
\gdef\sv@percent#1#2\relax
    {\ifx\check@percent\@@undefined
                     \ifx#1\relax\def\@tempa{}\else
                         \def\@tempa{#1#2}\fi\else
                     \ifx#1\relax\def\@tempa{}\else
                         \ifx#1%\def\@tempa{#2}\else
                             \def\@tempa{#1#2}\fi\fi\fi}
\endgroup
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\@isspaces}
%
% We want to avoid writing the first and last lines of the environment to the
% file if there's nothing in them.  To do this, we need to know whether a
% piece of text contains only space characters.  This macro does this, in a
% rather nasty way.  See the other macros below for details of how this
% works.
%
% We define |\sv@safespc| at the same time: this makes space active and
% expand to a space character which is not active.  Neat, huh?
%
%    \begin{macrocode}
\lccode`\~32
\lccode`\!32
\lowercase{%
  \def\@isspaces#1{%
    \ifx#1\relax%
      \def\@tempb{\@tempswafalse}%
    \else\ifx#1~%
      \let\@tempb\@isspaces%
    \else%
      \def\@tempb##1\relax{}%
    \fi\fi%
    \@tempb%
  }
  \def\sv@safespc{%
    \catcode32\active%
    \def~{ }%
  }
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sv@read}
%
% This macro does the main job of reading a chunk of verbatim text.  You call
% it like this:
%
% \begin{quote}
% \syntax{"\\sv@read{"<end-text>"}{"<process-line-proc>"}{"<end-proc>"}"}
% \end{quote}
%
% The \synt{end-text} is the text to find at the end of the `environment': we
% stop when we find it.
%
% The \synt{process-line-proc} is a macro which is passed as an argument each
% line which we read from the text.
%
% The \synt{end-proc} is a macro to call once we've finished reading all of
% the text.  This can tidy up an environment or close a file or whatever.
%
% We read the text by picking out newlines using a delimited macro.  We have
% to be a little clever, because newlines are active in verbatim text.
%
% We will also strip `|%|' signs off the beginning if the \package{doc}
% package is here (\package{doc} tries to play with \LaTeX's verbatim stuff,
% and doesn't understand the way we do things).
%
%    \begin{macrocode}
\def\sv@read#1#2#3{%
%    \end{macrocode}
%
% This code does all sorts of evil things, so I'll start by opening a group.
%
%    \begin{macrocode}
  \begingroup%
%    \end{macrocode}
%
% So that I can spot the end-text, I'll create a matcher macro.
%
%    \begin{macrocode}
  \matcher\@match{#1}\sv@read@ii%
%    \end{macrocode}
%
% So that I can identify line ends, I'll make them active.  I'll also make
% spaces active so that they can expand to whatever they ought to expand
% to (spaces in files, or funny \verb*" " characters or whatever.
%
%    \begin{macrocode}
  \catcode13\active%
  \catcode32\active%
%    \end{macrocode}
%
% I'll use the |\if@tempswa| flag to tell me whether I ought to output the
% current line.  This is a little messy, so I'll describe it later.  I'll
% initialise it to false because this is the correct thing to do.
%
%    \begin{macrocode}
  \@tempswafalse%
%    \end{macrocode}
%
% Most of the job is done by two submacros.  I'll define them in terms of
% my current arguments (to save lots of token munging).  The first just
% extracts the next line (which ends at the next newline character) and
% tries to match it.
%
%    \begin{macrocode}
  \lccode`\~13\lowercase{%
    \def\sv@read@i##1~{\@match{##1}}%
  }%
%    \end{macrocode}
%
% The results of the match get passed here, along with the text of the
% line up to the matched text.
%
%    \begin{macrocode}
  \def\sv@read@ii##1{%
%    \end{macrocode}
%
% The first job to do is to maybe strip off percent signs from the beginning,
% to keep \package{doc} happy.
%
%    \begin{macrocode}
    \sv@percent##1\relax\relax%
%    \end{macrocode}
%
% Now I need to decide whether I ought to output this line.  The method goes
% like this: if this is the first line (|\if@tempswa| is false) or the last
% (|\if@matched| is true), \emph{and} the text consists only of spaces, then
% I'll ignore it.
%
% The first thing to do is to notice the last line -- if |\if@matched| is
% true, then I'll make |\if@tempswa| false to make the first-line and
% last-line cases work the same way.
%
%    \begin{macrocode}
    \if@matched\@tempswafalse\fi%
%    \end{macrocode}
%
% Now if this is the first or last line, I'll examine it for spaces.  This
% is done in a separate macro.  It will set |\if@tempswa| false if the
% text contains only spaces.
%
%    \begin{macrocode}
    \if@tempswa\else\@tempswatrue\expandafter\@isspaces\@tempa\relax\fi%
%    \end{macrocode}
%
% Now, if |\if@tempswa| is still true, perform the \<process-line-proc> on
% the line of text.  I'll provide a group, so that it doesn't upset me
% too much.
%
%    \begin{macrocode}
    \if@tempswa%
      \begingroup%
      \expandafter#2\expandafter{\@tempa}%
      \endgroup%
    \fi%
%    \end{macrocode}
%
% The next line won't be the first one, so I'll set the flag true in
% readiness.
%
%    \begin{macrocode}
    \@tempswatrue%
%    \end{macrocode}
%
% Now, if that wasn't the last line, go round again; otherwise end the group
% I started ages ago, and do the user's \<end-proc>.
%
%    \begin{macrocode}
    \if@matched\def\@tempa{\endgroup#3}\else\let\@tempa\sv@read@i\fi%
    \@tempa%
  }%
%    \end{macrocode}
%
% Now to start the thing up.  I'll read the first line.
%
%    \begin{macrocode}
  \sv@read@i%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sv@readenv}
%
% This macro works out an appropriate end-text for the current environment.
% If you say \syntax{"\\sv@readenv{"<macro-name>"}"}, it will expand do
% \begin{listinglist} \listingsize \synshorts
% <macro-name>"{\\"$_{12}$"end{"$_{12}$<current-env-name>"}"$_{12}$"}"^^A
%		"{\\end{"<current-env-name>"}}"
% \end{listinglist}
% Easy, no?
%
% This is all done with mirrors.  No, err\dots\ it's done with
% |\expandafter|.
%
%    \begin{macrocode}
\begingroup
\lccode`\<=`\{
\lccode`\>=`\}
\lccode`\|=`\\
\lowercase{\endgroup
\def\sv@readenv#1{%
  \expandafter\expandafter\expandafter%
    #1\expandafter\sv@readenv@i\@currenvir\@@%
}
\def\sv@readenv@i#1\@@{{|end<#1>}{\end{#1}}}
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sv@verbline}
%
% This macro typesets a line in a verbatim way, so you can construct a real
% verbatim environment from it.  It's a bit tricky in the way that it catches
% the last line.  Don't worry about this: it's easy really.  Note the
% |\relax| after the |\par| -- this is because \package{doc} tries to do
% clever things with |\par| to strip `|%|' signs out.
%
%    \begin{macrocode}
\def\sv@verbline#1{%
  \setbox\z@\hbox{#1\sv@stripspc}%
  \ifdim\wd\z@=\z@%
    \if@matched\ifhmode\par\relax\fi\else\leavevmode\par\relax\fi%
  \else%
    \leavevmode\box\z@\par\relax%
  \fi%
}
%    \end{macrocode}
%
% \end{macro}
%
% \subsection{Listing environments}
%
% The \env{listing} environment is our equivalent of the standard
% \env{verbatim} environment.  We do some slightly cleverer things, though,
% to make sure (for example) that even text which contains |\end{listing}|
% can be typeset.
%
% \begin{macro}{\listinglist}
% \begin{environment}{listinglist}
%
% This defines the layout for the \env{listing} environment.  It starts a
% list with the appropriate shape.  It's also made into an environment, so
% that the end-paragraph-environment bits work correctly.
%
% The |\listingindent| length parameter sets up the indentation of the
% listings.  If there's a |\parindent| setting, I'll line listings up with
% that; otherwise I'll just choose something which looks right.
%
%    \begin{macrocode}
\newdimen\listingindent
\AtBeginDocument{%
  \ifdim\parindent=\z@\listingindent1em\else\listingindent\parindent\fi%
}
%    \end{macrocode}
%
% Now to define a size hook for the environment.  This is fairly simple
% stuff.
%
%    \begin{macrocode}
\ifx\listingsize\@@undefined
  \let\listingsize\small
\fi
%    \end{macrocode}
%
% Now to define the environment itself.  Suppress the indentation if we're
% first thing on a new list item, so that the listing lines up with
% everything else.
%
%    \begin{macrocode}
\def\listinglist{%
  \list{}{%
    \if@inlabel%
      \leftmargin\z@%
    \else%
      \leftmargin\listingindent%
    \fi%
    \rightmargin\z@%
    \labelwidth\z@%
    \labelsep\z@%
    \itemindent\z@%
    \listparindent\z@%
    \let\makelabel\relax%
    \parsep\z@skip%
  }%
  \parfillskip\@flushglue%
  \item\relax%
}
\let\endlistinglist\endlist
%    \end{macrocode}
%
% \end{environment}
% \end{macro}
%
% \begin{environment}{listing}
%
% The \env{listing} environment is the only real verbatim-like environment we
% create will all this kit, although it does the job very nicely.
%
% The environment indents its contents slightly, unlike \env{verbatim}, and
% uses a smaller typeface in an attempt to fit 77-column text on an A5~page.
% There is also a $*$-variant, which allows you to specify the terminating
% text.  This enables you to include absolutely any text in the environment,
% including |\end{listing}|.
%
% First, we must define the |\listing| command.
%
%    \begin{macrocode}
\def\listing{%
  \listinglist%
  \listingsize%
  \sv@readenv\sv@listing%
}
%    \end{macrocode}
%
% Now we define the |\@listing| command, which does most of the work.  We
% base the \env{listing} environment on a \env{list}.
%
%    \begin{macrocode}
\def\sv@listing#1#2{%
  \sv@startlisting%
  \sv@read{#1}\sv@verbline{\endlistinglist#2}%
}
%    \end{macrocode}
%
% Now we define the starred version.  The command name needs to include the
% `|*|' character, so we must use |\csname|.  There's some hacking here to
% allow us to read the name using the appropriate catcodes for otherwise
% normal characters: \LaTeX\ activates some characters and makes them typeset
% themselves to suppress some ligaturing.
%
%    \begin{macrocode}
\expandafter\def\csname listing*\endcsname{%
  \listinglist%
  \listingsize%
  \begingroup%
  \@noligs%
  \def\@tempa##1{\endgroup\sv@listing{##1}{\end{listing*}}}%
  \@tempa%
}
%    \end{macrocode}
%
% \end{environment}
%
% \begin{environment}{ignore}
%
% The \env{ignore} environment entirely ignores its contents.  Anything at
% all may be put into the environment: it is discarded utterly.
%
% We define some macros for defining ignoring environments, because this can
% be useful for version control, possibly.
%
%    \begin{macrocode}
\def\sv@ignore#1#2{%
  \@bsphack%
  \let\do\@makeother\dospecials%
  \sv@read{#1}\@gobble{\@esphack#2}%
}
\def\ignore{\sv@readenv\sv@ignore}
\def\ignoreenv#1{%
  \expandafter\let\csname #1\endcsname\ignore%
}
\def\unignoreenv#1{%
  \expandafter\def\csname #1\endcsname{\endgroup}%
  \expandafter\def\csname end#1\endcsname%
      {\begingroup\def\@currenvir{#1}}%
}
%    \end{macrocode}
%
% \end{environment}
%
% \subsection{The \env{verbwrite} environment}
%
% The \env{verbwrite} environment allows text to be written to a file in a
% verbatim way.  Note that tab characters don't work, because \TeX\ refuses
% to be nice.
%
% \begin{macro}{\sv@write}
%
% As seems to be traditional now, we first define a general hookable macro
% which allows a caller to specify the end-text and what to do afterwards.
%
%    \begin{macrocode}
\newwrite\sv@writefile
\def\sv@write#1#2{%
  \begingroup%
  \@bsphack%
  \let\do\@makeother\dospecials%
  \sv@safespc%
  \sv@read{#1}\sv@writeline{\sv@endwrite#2}%
}
\def\sv@writeline#1{%
  \immediate\write\sv@writefile{#1}%
}
\def\sv@endwrite{%
  \@esphack%
  \endgroup%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{environment}{verbwrite}
%
% Now we can define the actual environment.  We define a $*$-variant which
% allows the user to specify the end-text, just to make sure.
%
%    \begin{macrocode}
\def\verbwrite#1{%
  \immediate\openout\sv@writefile#1\relax%
  \sv@readenv\sv@write%
}
\def\endverbwrite{\immediate\closeout\sv@writefile}
\expandafter\def\csname verbwrite*\endcsname#1#2{%
  \immediate\openout\sv@writefile#2\relax%
  \sv@write{#1}{\immediate\closeout\sv@writefile\end{verbwrite*}}%
}
%    \end{macrocode}
%
% \end{environment}
%
% \subsection{The \env{demo} environment}
%
% By way of tying all of this together, I present an environment for
% displaying demonstrations of \LaTeX\ markup.  We read the contents of the
% environment, write it to a temporary file, and read it back twice,
% typesetting it the first time and displaying it verbatim the second time.
%
% \begin{macro}{\sv@demoname}
%
% This macro expands to the filename to use for the temporary data.  To
% allow the package documentation to demonstrate the \env{demo} environment
% itself, we need to keep a nesting count.  This avoids too much hackery,
% which unfortunately appears to plague all of my \TeX\ code.
%
%    \begin{macrocode}
\newcount\sv@nestcount
\def\sv@demoname{demo\number\sv@nestcount.tmp}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{macro}{\sv@demo}
%
% As for listing, we do all the business through a private macro.  This is
% good because it means we can leave the main macro readable.  The argument
% is the end-text to spot.
%
%    \begin{macrocode}
\def\sv@demo#1#2{%
  \@ifnextchar[{\sv@demo@i{#1}{#2}}{\sv@demo@i{#1}{#2}[n]}%
}
\def\sv@demo@i#1#2[#3]#4{%
  \advance\sv@nestcount by\@ne%
  \immediate\openout\sv@writefile\sv@demoname\relax%
  \sv@write{#1}{%
    \immediate\closeout\sv@writefile%
    \sv@dodemo{#2}{#3}{#4}%
  }%
}
%    \end{macrocode}
%
% \end{macro}
%
% \begin{environment}{demo}
%
% This is the real environment.  We provide \env{demo$*$} too, to allow the
% user to choose the end-text.
%
%    \begin{macrocode}
\def\demo{\sv@readenv\sv@demo}
\expandafter\def\csname demo*\endcsname#1{\sv@demo{#1}{\end{demo*}}}
%    \end{macrocode}
%
% \end{environment}
%
% \begin{macro}{\sv@dodemo}
%
% First, let's define some common bits of code in the stuff below.  The
% minipages used to typeset the material has some clever stuff to avoid
% strange spacing in the output.
%
%    \begin{macrocode}
\def\sv@demosmp{%
  \begin{minipage}[t]{\@tempdima}%
  \vskip8\p@%
  \hrule\@height\z@%
  \raggedright%
  \vbox\bgroup%
}
\def\sv@demoemp{%
    \par\unpenalty\unskip%
  \egroup%
  \vskip8\p@%
  \hrule\@height\z@%
  \end{minipage}%
}
%    \end{macrocode}
%
% This is the macro which actually typesets the demonstration.
%
%    \begin{macrocode}
\def\sv@dodemo#1#2#3{%
%    \end{macrocode}
%
% Now work out some values.  We set |\hsize| to the line width leaving 2\,em
% of space on either side.  The size of the minipages is calculated depending
% on the shape of the demonstration.  This is all fairly simple.
%
%    \begin{macrocode}
  \begingroup%
  \@tempdima\linewidth%
  \advance\@tempdima-2em%
  \hsize\@tempdima%
  \if#2w%
    \advance\@tempdima-2em%
  \else%
    \advance\@tempdima-3em%
    \divide\@tempdima2%
  \fi%
%    \end{macrocode}
%
% Now we open a big vertical box, and put in a header to mark off the
% demonstration.
%
%    \begin{macrocode}
  \par%
  \setbox\z@\hbox{\strut\enspace#3\enspace\strut}%
  \@tempdimb.5\dp\z@%
  \advance\@tempdimb-.5\ht\z@%
  \ht\z@\@tempdimb\dp\z@\@tempdimb%
  \noindent\hskip1em\vtop{%
    \hb@xt@\hsize{%
      \hrulefill%
      \raise\@tempdimb\box\z@%
      \hrulefill%
    }%
    \nointerlineskip%
    \hb@xt@\hsize{\vrule\@height5\p@\hfil\vrule\@height5\p@}%
    \nointerlineskip%
%    \end{macrocode}
%
% Now we insert the output text in the first minipage.  I'll force `|%|'
% to be a comment character, in case something like \package{doc} has had its
% wicked way.
%
%    \begin{macrocode}
    \vskip-\parskip%
    \noindent\hbox{}\hskip1em%
    \sv@demosmp%
    \catcode`\%14\relax%
    \input{\sv@demoname}%
    \sv@demoemp%
%    \end{macrocode}
%
% Insert some kind of separation between the two.  In `wide' format, we start
% a new line, and put a ruleoff between the two.  In `narrow' format, we just
% leave some space.
%
%    \begin{macrocode}
    \if#2w%
      \vskip8\p@\hrule\vskip8\p@%
      \noindent\hbox{}%
    \fi%
    \hskip1em%
%    \end{macrocode}
%
% Now we put the verbatim copy of the text in the other minipage.
%
%    \begin{macrocode}
    \sv@demosmp%
    \listingindent\z@%
    \verbinput\sv@demoname%
    \sv@demoemp%
    \par%
    \nointerlineskip%
    \hb@xt@\hsize{\vrule\@height5\p@\hfil\vrule\@height5\p@}%
    \hrule%
  }%
  \endgroup%
  \par%
  \vskip\baselineskip%
  #1%
}
%    \end{macrocode}
%
% \end{macro}
%
% That's all there is.  Have fun.
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \hfill Mark Wooding, \today
%
% \Finale
%
\endinput