summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/plain/pdcmac/pdcfmt2.dtx
blob: 6d8c5c78af241c05020880239ea4b950d6bfefd0 (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
% pdcfmt2.dtx -- documentation & source for pdcfmt2.tex -*-tex-*-
        
%%%@TeX-document-file {
%%% title 	= "PDCFMT2 -- Formatting Macros",
%%% filename 	= "$texmf/doc/plain/pdcmac/pdcfmt2.dtx",
%%% version 	= "$Revision: 2.4 $",
%%% package 	= "pdcmac 1.0",
%%% date 	= "$Date: 1995/04/06 11:55:16 $",
%%% author	= "P. Damian Cugley",
%%% email	= "damian.cugley@comlab.ox.ac.uk",
%%% address	= "Oxford University Computing Laboratory,"
%%%                Parks Road, Oxford  OX1 3QD, UK",
%%% abstract	= "This document describes and is the source code for 
%%%                the TeX definitions file pdcfmt2.tex.
%%%                Running plain TeX on this file produces both the
%%%                definitions file and the printed documentation.",
%%% copyright	= "Copyright (c) 1991-1995 P. Damian Cugley",
%%% copying	= "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.",
%%% notice	= "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.",
%%% notice	= "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.",
%%% codetable	= "USASCII",
%%% dependencies = "pdccode.tex"
%%%}

%{{{ pdcfmt2
%{{{  preamble

\relax
\input pdccode
\document
\rcs$Id: pdcfmt2.dtx,v 2.4 1995/04/06 11:55:16 pdc Exp $\endrcs

\def\example{
    \smallskip\hrule\nobreak\smallskip
    \dimen0=\hsize \advance\dimen0-1pc \divide\dimen0 2
    \halign to \hsize\bgroup\vtop{\tt\def~{\hfil\break} \def\\{\char`\\\relax} \hsize=\dimen0 ##}\tabskip=0pt plus 1fil&
	\vtop{\hsize=\dimen0 ##}\tabskip=0pt\cr
}
\def\endexample{
	\crcr\egroup
    \nobreak\smallskip\hrule\smallskip
}	

\codefile{pdcfmt2.tex}
%}}}  preamble
%{{{  introduction
	
\author{P. Damian Cugley}
\title{PDCFMT2---Formatting Macros}
\section{Introduction}
	
	This document describes |pdcfmt2.tex|, a collection of
	formatting macros for plain \TeX\ documents.  For example, it
	defines commands for making bulleted lists, verbatim text, and
	generic headings.  For longer documents, a higher-level `style
	file' like |pdccmdoc.tex| will define commands to start sections
	and generate a table of contents and so on.

	The definitions file and the printed documentation are both in
	|pdcfmt2.dtx|, a `documented \TeX\ macros' file\footnote*{The
	\LaTeX~2e distribution uses files with the `|dtx|' suffix for
	similar purposes.}  which, when processed by plain \TeX,
	generates a fresh copy of |pdcfmt2.tex| in the current directory
	in addition to the |dvi| file.  This ensures that the printed
	documentation and the code it describes are identical.  The
	|dtx| file uses the macros in |pdccode.tex|.

	The name of the macros file ends in `-|2|' to prevent confusion
	with |pdcfmt.tex| version 1.1.10, with which it is slightly
	incompatible.

%}}}  introduction
%{{{  File identification
\section{File identification}
	
	Nowadays, macro files start with some comments identifying the
	file.

\code
	\|\% pdcfmt2.tex \fileversion~\filedate~-- macros for formatting
	|
	|%%%@TeX-definition-file {
	|%%% filename       = "$texmf/tex/plain/pdcmac/pdcfmt2.tex",
	\|\%\%\% version~~~~~~~~= "\fileversion",
	\|\%\%\% date~~~~~~~~~~~= "\filedate",
	|%%% package        = "pdcmac 1.0",
	|%%% author         = "P. Damian Cugley",
	|%%% email          = "damian.cugley@comlab.ox.ac.uk",
	|%%% address        = "Oxford University Computing Laboratory,
	|%%%                   Parks Road, Oxford  OX1 3QD, UK",
	|%%% codetable      = "USASCII",
	|%%% keywords       = "TeX, plain TeX, macros",
	|%%% supported      = "Maybe",
	|%%% abstract       = "Formatting macros for plain TeX documents.
	|%%%                   This file was generated by running
	\|\%\%\%~~~~~~~~~~~~~~~~~~~plain TeX on \jobname.dtx",
	|%%% copyright      = "Copyright (c) 1991-1995 P. Damian Cugley",
	|%%% copying        = "DO NOT DISTRIBUTE THIS FILE.
	\|\%\%\%~~~~~~~~~~~~~~~~~~~Distribute \jobname.dtx only as part of the
	|%%%                   package it came in.",
	|%%% dependencies   = "",
	|%%% }
	|
	\|\\message\{\fileversion~<pdc \filedate>\}
	|
\endcode

%}}}  getting started
%{{{  internal

\section{Internal definitions}

	Most internal control sequence names will start with `|FMT|'.
	Here are a few miscellaneous definitions used to save a token
	here or there.

	I will often use |\toksa| to create definitions containing
	characters with unusual catcodes.  The idiom is
$$\halign{\indent#\hfil\cr
	|\begingroup| \<assignments> |\toksa={\endgroup|\cr
	\quad\<definitions>\cr
	|} \the\toksa|\cr
}$$ 
 	When |\toksa| is expanded, it closes the group (undoing the
	\<assignments>) but then scans the \<definition> using the
	catcodes set by \<assignments>.  (In extreme cases, the
	definition of |\toksa| might be enclosed in |\uppercase|, to get
	strange characters into a definiton.)

	The advantage of this idiom over using |\gdef| in a group is
	that the definitions need not be global.  Avoiding global
	assignments makes it more likely that the document will be
	embeddable in other documents.

	Using |\toksa| instead of |\toks0| is more robust when using
	|\uppercase|, because digits are be given |\uccode| values by
	|maamac.tex|.
\code
	|\toksdef\toksa=0
	|\chardef\other=12
\endcode
	
%}}}  internal
%{{{  verbatim text

\section{Verbatim text}

	`Verbatim' text means text designed to match the ASCII
	characters in the manuscript file as closely as possible.  It
	kis most often used in computer manuals, where commands typed to
	a computer or the contents of text files are to be presented.
	Within verbatim text, most of \TeX's special characters are
	temporarily disabled.

\subsec{Lists of active chararcters}

	The verbatim text macros need to know if any characters have
	been made special apart from the usual ones.  This command tells
	the verbatim macros that |#1| is an active char; in addition to
	setting its catcode, this makes sure that the character will be
	re-catcoded appropriately when in verbatim mode.  |#1| should be
	a something that will work after `|`|'; usually this means a
	one-character control sequence.
\code
	|\def\declareactivechar#1{%
	|    \toksa\expandafter{\verbatimplains\do#1}%
	|    \edef\verbatimplains{\the\toksa }%
	|    \catcode`#1\active
	|}
\endcode

	Two list macros in the style of |\dospecials| are defined.  The
	first is for characters that must be set to catcode~12, such as
	`|\|', `|{|', `|}|', `|_|', `|$|', `|#|', `|&|', and `|%|'.  The
	other is for a few characters that are given catcode~13, such as
	`|`|', `|'|', `|~|', `|^|' and SP.
\code
	|\def\verbatimplains{\do\\\do\{\do\}\do\_\do\$\do\#\do\&\do\%}
	|\def\verbatimactives{\do\-\do\`\do\'\do\~\do\^\do\ }
\smallbreak
	|\chardef\other=12
\endcode

\subsec{Setting up verbatim mode}

	This is a macro common to various verbatim text modes.  The
	default spacing of whatever font is used, without any
	adjustments of spacefactor for punctuation.  The characters
	`|`|', `|'|', `|~|', and `|^|' are produce slightly lowered
	glyphs.
\code
	|\newtoks\everyverbatim
\smallbreak
	|\bgroup \catcode`\-=13\catcode`\^=13 \catcode`\'=13 \catcode`\`=13 \toksa={\egroup
	|    \def\setupverbatim{%
	|        \frenchspacing
	|        \spaceskip0pt \xspaceskip0pt % use spacing of font
	|        \def\do##1{\catcode\lq##112 }\verbatimplains
	|        \def\do##1{\catcode\lq##1\active }\verbatimactives
	|        \let`\ttlq \let'\ttrq 
	|        \let~\tttilde \let^\ttcircum \let-\ttminus
	|        \the\everyverbatim
	|    }
	|}\the\toksa
\endcode

	Here are the definitions for the munged glyphs.  These are only
	necessary in CM Typewriter; when using a PostScript font,
	different definitions would be necessary.

	The names `rq' and `lq' are based on the use of |\lq| and |\rq|
	in plain \TeX.  An alternative definition for |\ttrq| would be
	|\chardef\ttrq="0D|, producing `{\tt\char"0D }'.
\code
	|\def\ttlq{\lower0.125ex \hbox{\char18 }}
	|\def\ttrq{\lower0.125ex \hbox{\char19 }}
	|\def\tttilde{\lower0.5ex \hbox{\char`\~ }}
	|\def\ttcircum{\lower0.5ex \hbox{\char`\^ }}
	|\def\ttminus{-}
\endcode
	This makes the difference between |`'^~| and
	{\tt`'\char`\^\char`\~}.

	The macro |\ttminus| is included because it is needed for
	PostScript font support.

\subsec{Defining a self-matching character for verbatim text}

	A macro for defining a self-matching verbatim character (I~got
	the idea of a macro for declaring verbatim characters from the
	\LaTeX~2e documentation macros).  |#1| must be a one-character
	control sequence.  If it isn't active already, then
	|\declareactivechar| is applied to it first.
\code
	|\def\defverbatim#1{%
	|    \ifcat\noexpand#1\noexpand~\else \declareactivechar#1 \fi
	|    \begingroup \uccode`\~=`#1 \uppercase{\toksa={\endgroup
	|        \def~{%
	|            \leavevmode
	|            \begingroup \tt \setupverbatim
	|            \catcode`#1\active \let~\endgroup
	|       }%
	|    }}\the\toksa
	|}
\endcode
	Note that there must be a font called |\tt| for it to switch to.
	(The catcode of |#1| is set to 13 after calling |\setupverbatim|
	because |#1| will be included in |\verbatimplains|.)

	Finally, we define vertical bar as the conventional
	self-matching verbatim-mode character.
\code
	|\defverbatim\|
\endcode
	Both |\defverbatim| and |\defineactivechar| have local scope.

\subsec{List a file verbatim}

	This does something similar to the |lines| environment (see
	below), except here an external file is read in verbatim (see
	{\it\TeX book} Appendix~D, Section~3).  The
	|\startlinenumbering| macro may be put in the |\everylisting|
	token register to create a listing with numbered lines.
\code
	|\newtoks\everylisting
\smallbreak
	|\def\listfile#1{
	|    \medskip
	|    \begingroup
	|        \parindent=0pt \parskip=0pt
	|        \def\par{\null\endgraf}\obeylines
	|        \setupverbatim \maketabstab
	|        \tt \the\everylisting  
	|        \input#1 
	|    \endgroup
	|    \medskip\noindent\ignorespaces
	|}
\endcode
	This macro redefines character |^^I| (horizontal tab) to produce
	the equivalent of eight spaces.  This isn't quite the same as
	what HTs are used for with UNIX files, but it works adequately
	if all your tabs are at the start of the line (i.e., if tabs are
	used only for indentation, not to make tables).
\code
	|{\catcode`\^^I=\active
	| \gdef\maketabstab{\catcode`\^^I\active \def^^I{\hskip 4em}}
	|}
\endcode

%}}}  verbatim text
%{{{  everypar
	
\section{Everypar hacks}

\subsec{Parameters}

	The following may be set by higher-level macros to change the
	apearance of the next paragraph.

	If the flag |\ifnoindent| is set, then the indentation of the
	next paragraph will be removed (by deleting the box added by
	\TeX's |\indent| primitive).  Thus |\noindenttrue| works like
	|\noindent|, except that there may be blank lines between
	|\noindenttrue| and the paragraph it affects.
\code
	|\newif\ifnoindent
\endcode
	This flag is reset globally once it has had its effect.

	If the box |\parbox| is non-void, then its value is typeset in
	the left margin of the next paragraph.  (At present this does an
	implicit |\noindenttrue| but later versions may allow the next
	paragraph to be indented.)  The righthand edge of the parbox
	will be distance |\parboxsep| from the left edge of the text
	area.
\code
	|\newbox\parbox	
	|\newdimen\parboxsep \parboxsep=1pc
\endcode

\subsec{Setting \cs{everypar}}
\code
	|\everypar={%
	|    \ifvoid\parbox
	|        \ifnoindent {\setbox0=\lastbox}\global\noindentfalse \fi 
	|    \else
	|        {\setbox0=\lastbox}\global\noindentfalse
	|        \dp\parbox=0pt
	|        \hbox to 0pt{\hss \box\parbox \hskip\parboxsep}%
	|    \fi
	|}	
\endcode
%}}}  everypar
%{{{  environment intrinsics
	
\section{Environment infrastructure}

	An environment is a structure used to typeset textual elements
	consisting of several \TeX\ paragraphs (usually embedded within
	one conceptual paragraph).  It is a concept like \LaTeX\
	environments, but with the syntax changed to be more
	plain-\TeX-like.  

	Since environments have one argument that may span many lines in
	the file we use more verbose brackets than |{|--|}| to make it
	easier to spot where they begin and end.  This is a structure in
	a document looking like this:
    $$
\vbox{\halign{#\hfil\cr
	|\|\<name>\<args>\cr
	\quad\dots\cr
	|\end|\<name>\cr
}}
    $$ 

	A new environment is defined by defining macros called
	|\|\<name> and |\end|\<name>.  Within the |\|\<name> and
	|\end|\<name> macros, calls to |\beginthe| and |\endthe| are
	used to check that environments are nested properly.
\code
	|\def\beginthe#1{%
	|    \begingroup\def\PDCFMTblockname{#1}%
	|}
\smallbreak
	|\def\endthe#1{%
	|    \def\tmp{#1}%
	|    \ifx\tmp\PDCFMTblockname
	|        \endgroup
	|    \else
	|        \errmessage{You should have said \string\endthe{\blockname}}%
	|    \fi
	|}
\endcode
    
\subsec{A generic end-of-environment macro}

	This macro does a |\smallskip| (if there is not already a larger
	skip on the current list), and sets the `noindent' flag so that
	the following \TeX\ paragraph is not indented.  
\code
	|\def\PDCFMTendenv#1{
	|    \smallskip
	|    \endthe{#1}
	|    \global\noindenttrue
	|}  
\endcode

	Where an environment describes text that should be indented,
	usually |\parindent| should be used (for consistency).  If
	|\parindent| is zero we still want to indent the text, and we
	use |\envindent| to describe how much to indent it by.
\code
	|\newdimen\envindent \envindent=1pc
\smallskip
	|\def\PDCFMTindent{%
	|    \ifdim\parindent>0pt
	|        \parindent
	|    \else
	|        \envindent
	|    \fi
	|}
\endcode

%}}} environment intrinsics
%{{{  quotations
	
\section{Quotations}
	
	This is a simple environment, with the left margin indented and
	the first paragraph in the quotetd text not indented.  
\example
	It is ... who said~
	\\quotation~
	\indent Shookum hip rallo dyne.~
	\\endquotation~
	Indeed, it burgle gurgler.
&	
	It is interesting to remember the words of
	Spencone Tipeth, who said
	\smallskip\leftskip\parindent \noindent
	Shookum hip rallo
	dyne.\smallskip\leftskip0pt \noindent Indeed, it burgle gurgler.
\endexample
The token
	register |\everyquotation| might be used to arrange for all
	quotations to be in smaller type with
	$$\hbox{|\everyquotation={\smallfonts}|}$$
\code
	|\newtoks\everyquotation
\smallbreak
	|\def\quotation{
	|    \smallskip
	|    \beginthe{quotation}
	|    \advance\leftskip\PDCFMTindent
	|    \noindenttrue
	|    \the\everyquotation
	|}
\smallbreak
	|\def\endquotation{\PDCFMTendenv{quotation}}
\endcode
	The differences from using |{\narrower|\dots|\par}| (apart from
	how it looks in the source file) include (a)~the right margin
	isn't indented; (b)~it indents by |\envindent| if there is no
	|\parindent| and (c)~it is preceeded and followed by a
	smallskip.
%}}}  quotations
%{{{  textlists (bullets + numbered) 
	
\section{Textlists---bulleted or numbered lists}

	Here's a generic list-of-items environment, used to implemented
	bulleted and numbered lists.  Each item is started with the
	convenient |\\| macro (and so may contain more than one
	paragraph).  It is called a `textlist' to distinguish it from
	other meanings of the word `list'.  Usually textlists will be
	generated with higher-level macros like |\bullets| and
	|\numbered|.

\subsec{A generic textlist environment}

	The token register |\everytextlist| is expanded at the start
	of every textlist.  The level of nesting is recorded in
	|\textlistdepth| (a to-level list is depth~0, a list inside
	that is depth~1, and so on).  The flag |\ifnumbered| controls
	whether items are numbered (using |\numberfordepth|) or
	bulleted (using |\bulletfordepth|).
\code
	|\newtoks\everytextlist
	|\newif\ifnumbered
	|\newcount\textlistdepth  \textlistdepth=-1
	|\newcount\textlistcount
\smallbreak
	|\def\textlist{%
	|    \par 
	|    \beginthe{textlist}
	|    \advance\textlistdepth 1
	|    \textlistcount0
	|    \def\\{
	|        \smallskip\noindent
	|        \advance\textlistcount1
	|        \llap{%
	|            \ifnumbered
	|                \numberfordepth\textlistdepth\textlistcount
	|            \else
	|                \bulletfordepth\textlistdepth
	|            \fi\enspace}%
	|        \ignorespaces
	|    }
	|    \advance\leftskip\PDCFMTindent
	|    \the\everytextlist
	|}
\smallbreak
	|\def\endtextlist{\PDCFMTendenv{textlist}}
\endcode

\subsec{Bulleted lists}

	This describes a bulleted list, where each paragraph is indented
	and preceeded by a mark in the margin.  
\example
	I would like to make...~\\bullets~\\\\ this point; and~\\\\ that
	point~\\endbullets~And so on and so forth.
& I would like to make the following very important and relevant
	itemized points:\smallskip\item{$\bullet$}this point;
	and\smallskip\item{$\bullet$}that
	point\smallskip\noindent And so on and so forth.
\endexample
Bullets environments may
	be nested, in which case different marks are used.  The sign is
	chosen with |\bulletfordepth|.
\code
	|\newtoks\everybullets
\smallbreak
	|\def\bullets{\textlist \numberedfalse \the\everybullets}
	|\let\endbullets=\endtextlist
\smallbreak
	|\def\bulletfordepth#1{%
	|    \ifcase#1 $\bullet$\or --\or $\circ$\else $\cdot$\fi
	|}
\endcode


\subsec{Numbered lists}

	The numbered list is similar.  The style of numbering changes
	with the listing depth; you can change this by redefining
	|\numberfordepth|.
    $$
\centerline{\vbox{\halign{#\hfil&\qquad\hfil# &&\hfil# \cr
	Depth 0&1.&2.&3.&\dots\cr
	Depth 1&(1)&(2)&(3)&\dots\cr
	Depth 2&({\it a\/})&({\it b\/})&({\it c\/})&\dots\cr
	Depth 3+&(i)&(ii)&(iii)&\dots\cr
}}}
    $$ 
 	There is also a token regieter |\everynumbered| for any extra
	customization.  This is read after |\everytextlist|.
\code
	|\newtoks\everynumbered
\smallbreak
	|\def\numbered{\textlist \numberedtrue \the\everynumbered}
	|\let\endnumbered=\endtextlist
\smallbreak
	|\def\numberfordepth#1#2{%
	|    \ifcase#1 \n{\number#2}.\or (\n{\number#2})\or
	|        ({\it\alphabetletter#2\/})\else (\romannumeral#2)\fi
	|}
\endcode
	It turns out that sometimes it is useful to be able to impose a
	format on numbers generated by formatting macros.  For example,
	I~occasionally find it useful to force all numbers to be
	generated in maths mode.  To do this, all numbers generated by
	macros are enclosed in |\n{|--|}|.  By default, |\n| is
	equivalent to |\relax|.
\code
	|\let\n\relax
\endcode

\subsec{Picking a letter of the alphabet}

	This macro behaves as much like the primitives |\number| and
	|\romannumeral| as it can: it expands entirely within \TeX's
	mouth, and so may be used in |\edef|s and the like.  It produces
	|???| or |!!!| if its argument is not in the range 1--26.
	The macro is defined so as to reduce the number of tokesn to be
	skipped  when |#1| is less than 6.
\code
	|\def\alphabetletter#1{%
	|    \ifcase#1 ??? \or a\or b\or c\or d\or e\else 
	|        \xxxalphabetletter#1\fi
	|}
	|\def\xxxalphabetletter#1{%
	|    \ifcase#1 \or\or\or\or\or\or f\or g\or h\or i\or j\or
	|        k\or l\or m\or n\or o\or p\or q\or r\or s\or t\or u\or 
	|        v\or w\or x\or y\or z\else !!!\fi
	|}
\endcode

%}}}  textlists (bullets + numbered)
%{{{  tagged list
	
\section{Tagged lists}

	In other words, description lists.  Each paragraph starts with
	the `tag' set either in the left margin or sticking in to the
	current line if it is too long to fit.  The tag for each
	paragraph is introduced with `|\\|\arg{\<text>}'.

	The maximum width of tag labels (including the 1\thinspace en
	space that goes between label and text) in is stored in
	|\tagmaxwidth|.  If there is not room, then the label is run on
	in to the paragraph and separated from the text by a quad space.
\code
	|\newdimen\tagmaxwidth
\endcode
	As well as giving a new definition to the |\\| macro, the
	|\tagged| command mast choose a value for |\tagmaxwidth|.  If
	there is a large left margin (signalled by giving |\leftmargin|
	a positive value) then tags will go in there; otherwise the text
	will be indented and the amount of indentation used as the
	maximum label width.
\code
	|\newtoks\everytagged
\smallbreak
	|\def\tagged{%
	|    \par
	|    \beginthe{tagged}
	|    \let\\\TAG
	|    \ifdim\leftmargin=0pt 
	|        \tagmaxwidth\PDCFMTindent
	|    \else
	|        \tagmaxwidth\leftmargin
	|    \fi
	|    \the\everytagged
	|    \ifdim\tagmaxwidth>\leftmargin
	|        \leftskip\tagmaxwidth \advance\leftskip-\leftmargin
	|    \fi
	|}
\smallbreak
	|\def\endtagged{\PDCFMTendenv{tagged}}
\endcode
	The adjustment to |\leftmargin| comes after scanning
	|\everytagged| so that it is possible to adjust |\tagmaxwidth|
	inside |\everytagged|.

	Trickery with |\futurelet| and |\aftergroup| (like that used in
	plain \TeX's |\footnote| command) is used to allow catcode
	changes in \<text> to work.  This allows macros that generate
	`verbatim' text to work.
\code
	|\newtoks\everytag
\smallbreak
	|\def\TAG{%
	|    \smallskip\noindent
	|    \setbox0=\hbox\bgroup        % matched by \TAGfinish
	|    \the\everytag\ignorespaces
	|    \futurelet\next\TAGtest
	|}
\smallbreak
	|\def\TAGtest{%
	|    \ifcat\bgroup\noexpand\next
	|        \let\next\TAGgotbrace
	|    \else
	|        \let\next\TAGnobrace
	|    \fi \next
	|}
\smallbreak
	|\def\TAGgotbrace{%
	|    \bgroup\aftergroup\TAGfinish 	
	|    \let\next
	|}
\smallbreak
	|\def\TAGnobrace#1{%
	|    #1\TAGfinish
	|}
\smallbreak
	|\def\TAGfinish{%
	|    \unskip\hskip0.5em\egroup       % matches \TAG
	|    \ifdim \wd0 < \tagmaxwidth
	|        \wd0=\tagmaxwidth
	|        \llap{\box0}%
	|    \else
	|        \hskip-\tagmaxwidth
	|        \unhbox0 \unskip\quad
	|    \fi
	|    \ignorespaces
	|}
\endcode
	It might be interesting to generalize these macros so that new
	macros with an argument scanned this way may be created more
	easily.
%}}}  tagged list
%{{{  lines
	
\section{Lines environment (for program listings etc)}

	In the |lines| environment, each line in the manuscript file
	becomes a new paragraph (i.e., a separate line on the printed
	page).  A |%| at the end of a line may be used to split a file
	line in to several logical lines.  In addition, the |lines|
	environment is bracketed by horizontal rules.  The effect is
	similar to that produced by the |\beginlines|--|\endlines|
	macros in {\it\TeX book} Appendix~E.

\code
	|\newtoks\everylines
\smallbreak
	|\def\lines{
	|    \par
	|    \beginthe{lines}
	|    \nobreak\smallskip\hrule\nobreak\smallskip
	|    \obeylines
	|    \parindent=0pt \parskip=0pt 
	|    \parfillskip=0pt plus 1fil
	|    \the\everylines
	|    \nobreak
	|}
\smallbreak
	|\def\endlines{
	|    \nobreak\smallskip
	|    \endthe{lines}
	|    \hrule\smallskip
	|    \global\noindenttrue
	|}  
\endcode

	For longer listings it may be nice to have the lines numbered
	for later reference.  The following two macros may be put in
	|\everylines| to enable line numbering---the first starts from~1
	in each listing environment, the other continues the numbering
	from where it left off.

	The line number is kept in |\linenumber| (which may be adjusted
	by the user).  Only every 5th line is numbered.  The number of
	lines until the next printed one is held in |\PDCFMTcount|.
	Both these are always set globally (which means lines
	environments cannot be nested!).
\code
	|\newcount\linenumber
	|\newcount\PDCFMTcount
\smallbreak
	|\def\startlinenumbering{%	
	|    \global\linenumber=0 \global\PDCFMTcount=5 
	|    \everypar{\numberthisline}%
	|}
\smallbreak
	|\def\continuelinenumbering{%
	|    \everypar{\numberthisline}%
	|}
\endcode

	The |\numberthisline| macro is invoked at the beginning of every
	paragraph.  It increments |\linenumber|, and writes the line
	number of every fifth line in the right margin.  By default it
	uses the same font as used in subscripts; this can be changed by
	changing the token register |\everylinenum|.
\code
	|\newtoks\everylinenum \everylinenum{\the\scriptfont0 }
\smallbreak
	|\def\numberthisline{%
	|    \strut
	|    \global\advance\linenumber1 \global\advance\PDCFMTcount-1
	|    \ifnum\PDCFMTcount>0 \else
	|	\global\advance\PDCFMTcount 5
	|	\rlap{\the\everylinenum \kern\hsize\kern1em \the\linenumber}%
	|    \fi
	|}%
\endcode

	Within the lines environment it can be useful to indicate where
	lines have been skipped.  This macro also adjusts the
	|\linenumber| macro.
\code
	|\def\linesskipped#1{%
	|    \strut \hskip20pt $\vdots$ \hskip20pt
	|    {\rm(\it #1 lines omitted\rm)}\par
	|    \advance\linenumber#1\relax
	|}
\endcode

%}}}  lines
%{{{  display, table
	
\section{Displays, Tables -- wrapper about \cs{halign}}

	The |display| environment does a generic (meaning not
	necessarily mathematical) display, in a manner similar to the
	|\begindisplay|--|\enddisplay| macros in {\it\TeX book}
	Appendix~E.  As with Knuth's macro, assignments may follow on
	the same line as |\display|, and |\cr| and |&| may be used to
	split the display into rows and columns.
\code
	|\outer\def\display{\obeylines\startdisplay}
	|\bgroup\obeylines \toksa={\egroup %
	|    \def\startdisplay#1^^M{%
	|        \catcode`\^^M=5 $$ #1 % matched by \enddisplay
	|        \displayindent\PDCFMTindent %
	|        \halign\bgroup##\hfil&&\quad##\hfil\cr %
	|    } %
	|}\the\toksa %
\smallbreak
	|\def\enddisplay{\crcr\egroup$$}
\endcode

	The |table| environment is similar, ecept that what follows
	|\table| is an arbitrary |\halign| specification.
\code
	|\def\table{%
	|    $$                  % matching $$ is in \endtable
	|    \displayindent\PDCFMTindent 
	|    \halign \bgroup
	|}
\smallbreak
	|\let\endtable=\enddisplay
\endcode

\notepar
	Both the {\tt table} and {\tt display} environments must go
	within paragraphs.  That is, there should not be blank lines
	before |\table|, or after |\endtable| unless the table ends the
	paragraph.
\endnotepar
%}}}  display, table
%{{{  ebnf
	
\section{(E)BNF}

	BNF is Bakus-Naur Formalism; EBNF is Extended BNF.  The same
	environment does either format.  The style I~happen to like, has
	non-terminal sumbols written like \<this>, and terminal symbols
	enclosed in `--'.  Optional text is enclosed in brackets (I~like
	to put spaces between the brackets and the enclosed text for
	clarity) and repeatable text in braces.

	In the manuscript file, each production is a separate paragraph.
	The macro |\>| goes between the left hand side and right hand
	side of a production; by default, it expands to `$::=$'.
	Alternatives are separated by |\\|; by default this expands to a
	bar `$\mid$'.  If the terminal symbols happen to be keyboard
	characters, use the verbatim text character {\tt\char`\|} which
	adds quotation marks around the text it produces.  For example,
	the following expression
    $$
	\hbox{\<foo>\enspace$::=$\enspace`|f|' `|o|' `|o|' $\mid$
	\<bar> [ \<mumble> `{\bf munge}' ].}
    $$
 	may be produced with
    $$
	\defverbatim\~
	\hbox{~\<foo> \> |f| |o| |o| \\ \<bar> [ \<mumble> `{\bf munge}' ].~}
    $$  
 	Braces are produced with |\{| and |\}|.

\code
	|\newtoks\everybnf
\smallbreak
	|\def\bnf{
	|    \nobreak\smallskip
	|    \beginthe{bnf}
	|    \advance\leftskip2\parindent \parindent=-\parindent 
	|    \parskip0pt plus 1pt
	|    \rightskip=1\rightskip plus 3em
	|    \def\\{$\mid$}
	|    \def\>{\unskip\enspace$::=$\enspace\ignorespaces}
	|    \def|{`\begingroup\tt\setupverbatim\catcode`\|=13
	|            \def|{\endgroup'}}
	|    \def\{{$\lbrace$} \def\}{$\rbrace$}
	|    \the\everybnf
	|}
\smallbreak
	|\def\endbnf{
	|    \smallskip
	|    \endthe{bnf}
	|    \global\noindenttrue
	|}
\endcode

	The macro |\<| is based on the one in Appendix~E of the {\it\TeX
	book}.  For example, |\<foo>| produces `\<foo>'.
\code
	|\def\<#1>{\leavevmode\hbox{$\langle${\it#1\/}$\rangle$}}
\endcode
	The difference is that the name is in italics: \<name> not
	$\langle$name$\rangle$.

\notepar
	This macro is not intened for be used to generate character
	names like Return and Tab; I suggest just saying `Return' and
	`Tab' for these.

	There is a style of RFC-822 email addresses written in the form
	`\/|Damian Cugley <pdc@alleged.co.uk>|'.  I suggest that when
	presenting email addresses in printed documents this be rendered
	as something like `\/{\rm Damian Cugley (|pdc@alleged.co.uk|)}'.
\endnotepar
%}}}  ebnf
%{{{  headings
	
\section{Headings}

	Here are some macros for making headings for sections of a
	document.  There are two styles of layout supported by these
	heading macros: the usual style~$N$, with headings above the
	first paragraph of the section, and the `tab-indexed' style~$T$,
	with headings in the left margin, aligned with the first line of
	the paragraph.


\subsec{The left margin parameter}
	For style~$T$ headings, this is the size of the extra margin at
	the left side of the page (so $({\it hoffset}+1\,{\rm in})-{\it
	leftmargin}$ is the margin between the left edge of headings and
	the edge of the paper).  Set this parameter to $0\pt$ for
	style~$N$.

\code
	|\newdimen\leftmargin
\endcode


\subsec{Headings that don't start a new page}

	This macro is intended to be used by higher-level macro with
	names like |\section|, which take care of numbering section
	headings and so on.
    $$
	\hbox{\tt\cs{doheading}\arg{\<skip>}\arg{\<style>}%
		\arg{\<coda>}\arg{\<text>}}
    $$
 	Where \<skip> is the skip to put before the heading (for
	example, a \<dimendef token> like like |\medskipamount| or
	|\bigskipamount|, or a \<dimen> enclosed in braces); \<style> is
	tokens to insert before the \<text> (such as assignments that
	select the font); \<coda> is tokens that follow the \<text>
	(which might produce a rule under the heading, for example;
	usually this is empty); and \<text> is the text of the heading
	supplied by the user.
\code
	|\newskip\headingtemp
	|\def\doheading#1#2#3#4{
	|    \ifdim\lastskip<#1\relax \removelastskip \vskip#1\relax \fi
	|    \ifdim \leftmargin>0pt
\endcode
	If the left margin is greater than zero then we generaten a
	style~$T$ heading.  This is done by putting the text in
	|\parbox|, which will be used by the |\everypar|.
\code
	|        \global\setbox\parbox=\vtop{%
	|            \hsize=\leftmargin \advance\hsize-\parboxsep
	|            \parindent=0pt
	|            \leftskip=0pt \rightskip=0pt plus 3em
	|            \hyphenpenalty=10000 \exhyphenpenalty=5000
	|            \strut#2#4#3
	|        }
	|    \else
\endcode
	Otherwise we typeset the heading as a separate paragraph.
\code
	|        \begingroup
	|            \parindent=0pt \parfillskip=0pt plus 1fil
	|            \leftskip=0pt \rightskip=0pt plus0.25\hsize 
	|            \hyphenpenalty=10000 \exhyphenpenalty=5000
	|            \strut#2#4#3
	|            \global\headingtemp=\baselineskip
	|            \par
	|        \endgroup
\endcode
	The vertical space between the heading and the following text is
	calculated from the difference in baselineskips between the
	fonts used in the heading and those used in body text, plus $\it
	smallskipamount$.
\code
	|        \advance\headingtemp-\baselineskip 
	|        \ifdim\headingtemp>0pt \nobreak \vskip 1.0\headingtemp \fi
	|        \smallskip
	|        \noindenttrue
	|    \fi
	|}
\endcode

\subsec{Headings that start a new page}

	Major divisions of a book start on a nw page.  The parameters to
	the macro are similar to those for |\doheading|:
    $$
	\hbox{\tt\cs{newpageheading}\arg{\<skip>}\arg{\<style>}%
		\arg{\<coda>}\arg{\<text>}}
    $$
	Where here the \<skip> is the extra space at the top of the page.

\code
	|\def\newpageheading#1#2#3#4{
	|    \vfill\supereject % ensure no insertions still floating
	|    \null\vskip#1\relax
	|    \moveleft\leftmargin\vbox{
	|        \advance\hsize\leftmargin
	|        \parindent=0pt \parfillskip=0pt plus 1fil
	|        \leftskip=0pt \rightskip=0pt plus0.25\hsize 
	|        \hyphenpenalty=10000 \exhyphenpenalty=5000
	|        #2\strut#4#3
	|        \global\headingtemp=\baselineskip
	|        \par
	|    }
	|    \advance\headingtemp-\baselineskip 
	|    \advance\headingtemp\smallskipamount
	|    \vskip \headingtemp 
	|    \noindenttrue
	|    \def\tmp{#4}
	|    \message{*\expandafter\TOCtrim\meaning\tmp.  }
	|}
\endcode
%}}}  headings
%{{{  footnotes
\section{Footnotes}

	We define a new command |\note| that replaces use of the
	|\footnote| command.  This takes one parameter---the text of the
	footnote---and supplies automatically-numbered footnote markers.

	The |\newcount| command implicitly sets the counter to~0.

\code
	|\newcount\notecount
\smallskip
	|\def\note{%
	|    \global\advance\notecount+1
	|    \footnote{\number\notecount}%
	|}
\endcode

	We add a parameter for the indentation of footnote paragraphs.  
\code
	|\newdimen\footnoteparindent
	|\footnoteparindent=\parindent
\endcode

	Now we modify the definition of |\footnote| in plain~\TeX\ (see
	TeXbook p.\thinspace363).  It has the same function as
	plain~\TeX's |\footnote|, but uses extra parameters
	(|\everyfootnote|, |\footnotetextmark|), and handles the case
	${\it parindent}=0\pt$.
\code
	|\newtoks\everyfootnote
\smallbreak
	|\catcode`\@=11			
	|\def\footnote#1{\let\@sf\empty
	|  \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\/\fi
	|  \footnotetextmark{#1}\@sf\vfootnote{#1}}
\smallbreak
	|\def\vfootnote#1{\insert\footins\bgroup % matched by \@foot
	|    \interlinepenalty=\interfootnotelinepenalty
	|    \parindent=\footnoteparindent
	|    \leftskip=0pt 
	|    \the\everyfootnote
	|    \splittopskip=\ht\strutbox \splitmaxdepth=\dp\strutbox
	|    \floatingpenalty=20000
	|    \indent\footstrut
	|    \ifdim\parindent>1em 
	|        \llap{\footnotenotemark{#1}\enspace}%
	|    \else
	|        \footnotenotemark{#1}\enspace
	|    \fi
	|    \futurelet\next\fo@t
	|}
\smallbreak
	|\def\@foot{\smallskip\egroup}
\smallskip
	|\catcode`\@=12
\endcode
	These two parameters control the formatting of the footnote
	marker in the text and in the note itself.  They take one
	parameter, a \<number>.  The default definitions simply use a
	superscript in maths mode.
\code
	|\def\footnotetextmark#1{$^{#1}$}
	|\def\footnotenotemark#1{$^{#1}$}
\endcode
%}}}  footnotes
%{{{  in-paragraph commands

\section{Miscellaneous in-paragraph commands}


\subsec{Writing the current date}

\let\n=\relax
\def\today{\n{\number\day} \monthname\month\ \n{\number\year}}
\def\monthname#1{%
    \ifcase#1\or
        January\or February\or March\or April\or 
        May\or June\or July\or August\or 
        September\or October\or November\or December%
    \fi
}
	
	We define a macro |\today| that prints today's date.  I used to
	have the option of the abbreviated date but decided this was an
	unnecessary complication.  The format `\today' is usual
	in non-American countries, and is recommended by {\it Hart's
	Rules}\footnote*{Horace Hart, {\it Hart's Rules for Compositors
	and Readers at the University Press, Oxford}, 39th~ed.,
	completely revised (Oxford University Press, 1990),
	p.\thinspace19.} and Strunk \&
	White.\footnote\dag{William Strunk jun., and E.~B. White, {\it
	The Elements of Style}, 3rd~ed.\ (Macmillan, 1979),
	p.\thinspace3.  The American format is given first but followed
	by the observation that the day--month--year format is `an
	excellent way to write that date; the figures are separated by a
	word, and are, for that reason, quickly grasped'.}
\code
	|\def\today{\n{\number\day} \monthname\month\ \n{\number\year}}
\smallbreak
	|\def\monthname#1{%
	|    \ifcase#1\or
	|        January\or February\or March\or April\or 
	|        May\or June\or July\or August\or 
	|        September\or October\or November\or December%
	|    \fi
	|}
\endcode
	Redefine the |\monthname| macro if you want different names for
	the months.


\def\isodate{\n{\number\year}--\twodigits\month--\twodigits\day}
\def\twodigits#1{%
    \ifnum#1<10 0\fi \number#1%
}

	Here's a definition for the date in ISO~8601/BS~4795
	format,\footnote\ddag{{\it The Oxford Writers' Dictionary}
	(Oxford University Press, 1990), under `date'.  I~have not read
	the relevant standards.} which puts the year first, giving
	`\isodate':
\code
	|\def\isodate{\n{\number\year}--\twodigits\month--\twodigits\day}
\smallbreak
	|\def\twodigits#1{%
	|    \ifnum#1<10 0\fi \number#1%
	|}
\endcode


\subsec{Raising things}

	The |\flushtop| macro prints its argument in a box raised so
	that the its top is aligned with the top of a letter X in the
	current font.
\code
	|\def\flushtop#1{%
	|    \leavevmode
	|    \begingroup
	|        \setbox0\hbox{#1}\setbox2\hbox{X}%
	|        \dimen0\ht2 \advance\dimen0-\ht0
	|        \raise\dimen0\box0
	|    \endgroup
	|}
\endcode
	This allows us to define a fairly generic version of the \LaTeX\
	logo:
\code
	|\def\La{L\negthinspace\flushtop{a}}
	|\def\LaTeX{\La\TeX}
\endcode
	I have not given a definition for the \LaTeX~2e logo, since
	I~think that `|\LaTeX~2e|' (or `|\LaTeX2e|' if you prefer) is
	adequate, whereas Addison--Wesley think it should be `|\LaTeX|
	|\kern0.05em| |2$| |_{\textstyle| |\varepsilon}| |$|' in regular
	text and something involving bold maths in boldface.  SImilarly,
	I do not include macros for Bib\TeX, Sli\TeX, AMS-\TeX, and so
	on; the |texlogos.sty| file from the Eplain package has
	definitions for these.

\def\superiorletter#1{\flushtop{\the\scriptfont\fam
	\vphantom{t}\smash{#1}}}

	Here's a variation which raises a scriptstyle letter so that
	its {\it x}-height matches the cap-height of the body text,
	thus making `M\superiorletter{\b c\kern0.1ex }Donald' and
	`1\superiorletter{\b a}', `1\superiorletter{\b o}',
	`1\superiorletter{er}', `2\superiorletter{\`eme}',
	`1\superiorletter{st}', `2\superiorletter{nd}',
	`3\superiorletter{rd}' and `659\superiorletter{th}' (which I
	prefer to $659^{\rm th}$).
\code
	|\def\superiorletter#1{%
	|    \flushtop{\the\scriptfont\fam \vphantom{x}\smash{#1}}%
	|}
\smallbreak
	|\def\Mc{M\flushtop{\the\scriptfont\fam \b{c}}}
\endcode


%}}}  in-paragraph commands
\endcodefile
\enddocument
\bye
%}}} pdcfmt2
	
%Local variables:
%fill-prefix: "	"
%fold-folded-p: t
%End: