summaryrefslogtreecommitdiff
path: root/macros/plain/contrib/pdcmac/pdcguide.tex
blob: cc79b69f67c00a3590f90f2f0c0683fe218a77cd (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
% pdcguide.dtx -- user guide for PDCMAC -- Time-stamp: <pdc 1995-04-06>	
	
%%%@TeX-document-file {
%%% title 	= "The PDCMAC Package",
%%% filename 	= "$texmf/doc/plain/pdcmac/pdcguide.dtx",
%%% version 	= "$Revision$",
%%% package 	= "pdcmac 1.0",
%%% date 	= "$Date$",
%%% author	= "P. Damian Cugley",
%%% email	= "damian.cugley@comlab.ox.ac.uk",
%%% address	= "Oxford University Computing Laboratory,"
%%%                Parks Road, Oxford  OX1 3QD, UK",
%%% abstract	= "A brief user guide for the PDCMAC package.",
%%% copyright	= "Copyright (c) 1995 P. Damian Cugley",
%%% codetable	= "USASCII",
%%% dependencies = "pdccmlft.tex, pdcmacvn.tex, ..."
%%%}

%{{{ pdcguide 
%{{{  preamble

\errorcontextlines10000

\ifx\usepsfonts!
    \def\bodyfontname{pplr} \def\bodyttfontname{phvr} 
    \def\headingttfontname{phvro}
    \input pdcpsdoc
    \mathcode`.=\gbdecimal \mathcode`/="202F
\else
    \input pdccmdoc  \mathcode`.="0201 \mathcode`/="213D
\fi

\input pdcmacvn
\majorheadline{PDCMAC Release $\pdcmacversion$} \twosidedtrue
\noheadlinetrue 
    
\def\n#1{$ \textfont0=\font \mathcode`i=`i \mathcode`v=`v \mathcode`x=`x #1 $}

\def\plainslash{/} \declareactivechar\/ \let/\plainslash
\def\texmf#1#2{{\tt\let/=\slash%  $ for matching
	\$texmf/#1%
	\def\tmp{#2}\ifx\tmp\empty \plainslash \else /#2\fi}}
\def\url#1#2#3{{\tt#1:\penalty\exhyphenpenalty
	\plainslash\plainslash \let/=\slash #2%
	\def\tmp{#3}\ifx\tmp\empty \plainslash \else /#3\fi}}

\newcount\tablecount \tablecount2
\def\newtableid{\global\advance\tablecount1 \number\tablecount}

%}}}  preamble
%{{{  intro
\section{What is this thing you Earth people call PDCMAC?}
%{{{   intro
\subsec{Introduction}
		
	PDCMAC is collection of \TeX\ definition files (macro files)
	which may be useful for setting documents using plain \TeX\
	(`plain' here meaning \TeX\ formats following similar
	conventions to those of Appendix~B of the {\it\TeX book}, as
	opposed to more complex formats like \LaTeX).  This package is
	much less powerful than \LaTeX~2e; it is intended to be a
	simpler solution to simpler requirements.  Because it is less
	complex, the macro code should be more readily adapted by other
	\TeX\ hackers.

	The package includes a font-selection system, an output routine,
	general formatting macros, and `style files' which input the
	other files and set the format for documents.

	The name `PDCMAC' is pronounced `{\it p-d-c}-mac'.  In file
	names where case matters it is always written in all-lower-case.
	The fairly consistent use of a `|pdc|-' or `|ma|-' prefix in
	this and other names is intended to prevent these files clashing
	with files from other packages.  (The `|ma|-' files are part of
	the Malvern package.)
%}}}   intro
%{{{   conventions
\subsec{Conventions in this guide}

	Contents and names of computer files, and commands to be typed
	literally are printed in {\tt this distinctive font}.
	Placeholders to be filled in with real file names etc.~are
	written in {\it this italic font}.
	
%}}}   conventions
%{{{   copying
	
\subsec{Copying}
	The PDCMAC files are copyright \copyright\ 1990--1995 P. Damian
	Cugley.  They may be used in documents, and distributed as a
	complete package as per the GNU General Public Licence
	(reproduced at the end of this document).

	The |tex| files generated by the |dtx| files are like `object
	files'; you should not distribute them without their source
	files (the |dtx| files).

	Do not modify the generated |tex| files; if you must modify the
	macros, do this by editing the |dtx| files and running them
	through \TeX\ again.  If you must distribute modified versions
	(instead of persuading me to modify my copies), help reduce the
	proliferation of incompatible versions by doing the following:
\bullets
	\\describe the modifications clearly in the printed
	documentation;

	\\say who modifed them in the header comments in the definition
	files, and change the version identifier;

	\\use a different name for the modifed definition files.
\endbullets
	The last point is so that documents using the unmodified
	versions can coexist with the ones using modified ones.


	
%}}}  copying
%{{{   feedback
	
\subsec{Feedback}
	I am very interested to hear from people who find a use for this
	package.  Please send comments and suggestions, or reports of
	bugs, to the address above.  If you find PDCMAC useful or
	amusing, please send me a pretty postcard.  Thanks.

%}}}  feedback
%}}}  intro
%{{{  unpack install
\section{Unpacking and installing the files}
%{{{   unpack

\subsec{Unpacking}

	Two common formats for archives are 
\bullets
\\	(on Unix) 
	|tar| files, compressed using GNU |zip| (|gzip|), and
\\	(on MS-DOS) PKZIP-style archives.
\endbullets
	Compressed tarfiles will have names like |pdcmac-1.0.tar.gz| or
	|pdcmac10.tgz| (the latter form is required by ISO-9660\note{ISO
	9660 is the standard for CD-ROM file systems.  Its file names
	are like MS-DOS file names: a sequence of 8-letter components
	followed by a `|.|' and three-letter suffix.  ISO~9660 names use
	capital letters, but on case-sensitive operating systems these
	are usually transliterated to lower-case.}  file systems).
	Unpack the package with something like
\display \defverbatim\"
	"zcat pdcmac10.tgz | tar -xf -"
\enddisplay
	This generates a new directory called |pdcmac-1.0|.

	PKZIP archives unpack files into the current directory, so they
	are unpacked like this:
\display 
	|md pdcmac|\cr
	|cd pdcmac|\cr
	|unzip a:\pdcmac10.zip|\cr
\enddisplay
	assuming the zipfile is so named.

	There is a list of the files in the release in the appendix.
%}}}   unpack
%{{{   compile
	
\subsec{Generating the macro files}

	The macro files are packaged with their documentation in
	|dtx|\note{The \LaTeX~2e distribution uses the file name suffix
	|dtx| for files with a similar function.  Unlike the \LaTeX\
	system, the |dtx| files for PDCMAC produce the printed
	documentation and unpack the macro files themselves using a
	single macro file |pdccode.tex| and a single run through plain
	\TeX; there are no |drv| or |ins| files.}  files; run plain
	\TeX\ on each of the |dtx| files in turn to generate the macro
	files and the printed documentation.  The resulting definition
	files have almost no comments in them; instead you must read the
	|dtx| files or the printed documentation.

	The macro files are written in the current working directory.
	They are identical to the code lines in the printed
	documentation (they are generated from the same text in the
	|dtx| files).

	There is a file |pdcmondo.tex| which reads all of the |dtx|
	files in turn except |pdcsty.dtx| and produces one large (70+
	pages) document as well as all their macro files.  This is most
	useful if you want to make a printed listing rather than keeping
	|dvi| files for reading online.

%}}}   compile
%{{{   install
\subsec{Installing the files}

	The definition (|tex|) files belong in a directory where \TeX\
	can find them.  In the new soon-to-be-standardized file name
	conventions TWG-TDS~$0.61$\note{The TUG Working Group on a \TeX\
	Directory Structure, {\it A Directory Structure for
	Implementation-Independent \TeX\ Files} Version~$0.61$
	(\url{ftp}{ftp.th-darmstadt.de/pub/tex/TDS-compliant/draft}{twg-tds.dvi},
	10~February 1995).} this is the directory
	\texmf{tex/plain/pdcmac}{}.  On older systems, the files go with
	all the other macro files.

	With TWG-TDS~$0.61$ the documentation goes in
	\texmf{doc/plain/pdcmac}{}.  If you do not have a directory for
	documentation, the documentation files might as well go in the
	\TeX\ inputs directory as well.
%}}}   install
%{{{   configure
	
\subsec{Configuration on Unix systems}

	There is a |configure| script and makefile template included,
	which allows the process of unpacking to be run automatically on
	Unix systems.\note{The configuration system is based on the GNU
	Coding Standards, but was written by hand rather than using
	Autoconf.}  The remainder of this section assumes you are
	installing PDCMAC on a Unix system.

\subsec{Run\-ning |configure|}

	Start by running a Bourne Shell on the |configure| script, by
	typing `|sh configure|'.  This examines your file system and
	attempts to guess suitable directories in which to put macro and
	documentation files.  The |configure| script understands options
	listed in Table~1.

\midinsert
\noindent{\bf Table 1}\quad  Options for |configure|.  Other
	options are ignored.\smallskip
\moveleft\leftmargin\vbox{
    \def\,{{\rm,}}
    \def\\#1\, #2&{\vbox to \ht\strutbox{\hbox{$
	\left.
	\vcenter{\ialign{\strut##\hfil\cr#1 \cr#2 \cr}}
	\right\rbrace
	$}\vss}&}
    \halign to \bodywd{\tt#\hfil\tabskip=0pt plus 1fil&
		\vtop{\noindent#\smallskip}\tabskip=0pt\cr
\noalign{\hrule height 1pt \vskip1.5\jot}%
\it Option&\omit\it Meaning\hfil\cr
\noalign{\vskip1\jot \hrule \vskip1.5\jot}%
	\ttminus h\, \ttminus \ttminus help&
		Print a summary of options\cr
	\ttminus n\, \ttminus \ttminus no\ttminus create&
		Create |config.status| but don't run it to make |makefile|.\cr
	\\\ttminus t$dir$\, \ttminus \ttminus texmf=$dir$&
		Says where to find a \TeX\ directory hierarchy.  For example,
		`|-t|\allowbreak|/usr/texmf|' or `|-t|\allowbreak|/usr/local/lib/tex3.14/tex|'.  The
		|configure| script will often guess correctly without this
		option.\cr
	\\\ttminus p$dir$\, \ttminus \ttminus prefix=$dir$&
		Specifies the parent of the \TeX\ directory, for example,
		`|-p/usr|' or `|-p/usr/local/lib|'.  This is for compatability
		with the GNU coding standards.\cr
	\\\ttminus wtds\, \ttminus \ttminus with\ttminus tds& Specify that the \TeX\ directory uses some
		approximation to the TWG-TDS $0.61$ file name
		conventions.  This should not be necessary as
		|configure| will usually guess correctly.
	\cr
\noalign{\vskip\jot \hrule height 1pt}%
}    }
\endinsert

	The configuration process creates a script |config.status| which
	records the configuration; running |config.status| generates a
	file |makefile|\note{Usually a makefile is called |Makefile|,
	but I~wanted to make the package proof against file name munging
	from being copied onto MS-DOS discs.}  from the template
	|makefile.in|.

	The |config.status| script has one option |-r| (or |--recheck|),
	which re-runs |configure| with the same arguments as were used
	to generate |config.status|; any options following |-r| are
	passed to |configure|.  

%}}}   configure
%{{{   make
	
\subsec{Running |make|}

	Now you can use the |make| command to unpack and install all the
	files.  Do `|make|' to generate all the definition files and
	documentation.  Then `|make install|' to copy the macros into
	\TeX's macros directory and the documentation into \TeX's
	documentation area (assuming there is one).  The standard
	targets which the makefile understands are listed in Table~2.

\midinsert
\noindent{\bf Table 2}\quad  Conventional targets defined in |makefile|.\smallskip
\moveleft\leftmargin\vbox{
    \def\,{{\rm,}}
    \def\\#1\, #2&{\vbox to \ht\strutbox{\hbox{$
	\left.
	\vcenter{\ialign{\strut##\hfil\cr#1 \cr#2 \cr}}
	\right\rbrace
	$}\vss}&}
    \halign to \bodywd{\tt make #\hfil\tabskip=0pt plus 1fil&
		\vtop{\noindent\strut#\strut\smallskip}\tabskip=0pt\cr
\noalign{\hrule height 1pt \vskip1.5\jot}%
\omit\it Command&\omit\it Meaning\hfil\cr
\noalign{\vskip1\jot \hrule \vskip1.5\jot}%
    all&
	Generate all the definitions files and |dvi| files\cr
    install&
	Generate the definition files and copy them in to \TeX's
	macro area.  Also copy the |dvi| files into \TeX's documentation
	area, if possible.\cr
    uninstall&
	Delete all the files that `|make install|' would install.\cr
    mostlyclean& Delete some files but not as many as `|make clean|'.\cr
    clean& Delete files from the current directory that are normally
	created by `|make all|'.  Don't delete files that could be built
	using the makefile but which come with the distribution.\cr
    distclean& Delete some more files, including those made by
	configuration.  If you have unpacked the files and generated the
	macro files without creating any other files, this should leave
	only the files in the distribution.\cr
    realclean& Delete files deleted `|make distclean|' and any others
	that can be rebuilt using the makefile.\cr
    TAGS& Generate a tags table file for Emacs.\cr
    dist& Make a tarfile and zipfile for the package.\cr
\noalign{\vskip\jot \hrule height 1pt}%
}    }
\endinsert
%}}}   make
%}}}  unpack install
%{{{  using
	
\section{Using PDCMAC style files for your documents}

	Normally a document will start by reading one of the style
	files, which in turn load the various definition files.  The
	style files are intended to be more-or-less compatible with each
	other.  I have arbitrarily divided the style files into
	`leaflets' and `docs'.
%{{{   leaflets

\subsec{Leaflet styles}

	A leaflet is only a few pages, so does not need a table of
	contents or division into large units.  There is still a
	|\section| command, but it is designed for smaller divisions
	than the |\section| command used in `docs' (in a leaflet,
	|\section| produces a heading with prominence similar to that
	produced by |\subsec| in a doc).
	
	A leaflet-style document has no front matter, and so should
	start with some sort of heading for the title.
\lines \it
	|\input pdccmlft|
	|\majorheadline{| title |} \noheadlinetrue|
	\quad commands to generate the title at the top of the first page
\smallskip
	\quad text of the document, perhaps using |\section| commands
\smallskip
	|\bye|
\endlines
%}}}   leaflets
%{{{   docs
	
\subsec{Doc styles}

	A doc is something larger than a leaflet but smaller than a
	book.  It has a table of contents and numbered sections and
	subsections, with section titles being reproduced in the
	headline.  There is no provision for cross-references and
	automatic bibliography (which require an |aux| file and at least
	two passes through \TeX).  

	Sections may be grouped into larger divisions I have called
	\dfn{part}s.  Parts are numbered independently of sections, in
	upper-case roman numerals.  (There is no special reason for not
	numbering sections within parts; I~just prefer to have fewer
	levels of numbering, so we get `\S$12.6$' instead of
	`Subsection~$4.1.6$'.)

\lines\it
	|\input pdccmdoc|
	|\part{| title |}|  ---or--- |\majorheadline{| title |}|
	|\section{| title |}|
	\quad contents of section
\smallbreak
	more sections
\smallbreak
	|\frontmatter|
	\quad front matter
	|\endfrontmatter|
	|\bye|
\endlines
	
\subsec{Front matter}

	The front matter of the document---the title page, preface,
	forword, etc.---must be printed {\it last}, with the table of
	contents at the end of the front matter; this is so that the
	table of contents may be accumulated during the \TeX ing of the
	file.\note{It has a benefit for people reading the document with
	a browser: page~1 of the document is the first page of the DVI
	file, which makes selecting a given page easy, and the table of
	contents is at the very end, so the browser's `go to last page'
	command can be used to find the table of contents quickly.}
     	The front matter starts with |\frontmatter| and may contain
	|\section| commands.  Such sections will be unnumbered and will
	not appear in the table of contents.
	
	For a short document, a separate title page is probably
	excessive, and an abstract may be preferable to a preface.  In
	this case the first page after |\frontmatter| could have the
	title of the document (with author etc.)\ followed by an
	abstract, any copyright information (or other small print), and
	the contents (generated by |\endfrontmatter|).  In other words,
	something like this:
\lines\it
	|\frontmatter|
	\quad commands to print the title, etc.
	\quad|\abstract|
	\qquad the text of the abstract
	\quad|\endabstract|
	\quad copyright information, etc.
	|\endfrontmatter|
\endlines
 	For a longer document, there will be a separate title page and
	perhaps a preface.
\lines\it
	|\frontmatter|
	\quad|\titlepage|
	\qquad commands to print the title, etc.
	\quad|\splittitlepage|
	\qquad print copyright information, etc.
	\quad|\endtitlepage|
	\quad|\section{Preface}|
	\qquad text of preface, etc.
	|\endfrontmatter|
\endlines
 	The macro |\splittitlepage| marks the division between the title
	page (title recto, page~i) and the back of the title page (title
	verso, page~ii), which is where copyright information goes.
	When formatting for one-sided printing, the copyright
	information belongs on the title recto, because the title verso
	will be blank, so |\splittitle| instead does |\vfill|.
%}}}   docs
%{{{   new syms
\subsec{New symbols}

	Several new symbols common to Malvern~A and PostScript fonts are
	added (listed in Table~3).  Approximations built from other
	glyphs are available in Computer Modern documents.


\def\chartable#1{%
    \midinsert
	\leftline{{\bf Table \newtableid}\quad #1}\smallskip
	\def\cs##1{\hbox to \gridwd{\hbox to2em{\csname##1\endcsname\hfil} 
		{\tt\char`\\##1}\hfil}}
	\def\mcs##1{\hbox to \gridwd{\hbox to2em{$\csname##1\endcsname$\hfil} 
		{\tt\char`\\##1}\hfil}}
	\def\mch##1{\hbox to \gridwd{\hbox to2em{$##1$\hfil} 
		{\tt##1}\hfil}}
	\moveleft\leftmargin\vbox\bgroup
	    \hrule\medskip
	    \halign\bgroup ##\hfil&& \hskip\colsep##\hfil\cr
}
\def\endchartable{
	    \egroup
            \smallskip\hrule
	\egroup
    \endinsert
}

\chartable{New symbols}
	\cs{cents}&	\cs{pounds}& \cs{yen}&		\cs{florin}\cr
	\cs{currency}& 	\cs{lguillemet}& \cs{rguillemet}& \cs{gbdecimal}\cr
	\cs{permille}&	\cs{registered}& \cs{orda}& 	\cs{ordo}\cr
	\cs{S}&		\cs{P}&		\cs{dag}&	\cs{ddag}\cr
\endchartable

	The symbols in the last row are `new' in the sense that they
	will change according to the current font when using Malvern or
	PostScript fonts.

	
	The maths symbols in Table~4 will be in the current |\rm| font
	(fam~0) in PostScript documents.
\begingroup\catcode`_=12 \catcode`\|=12
\chartable{Maths symbols taken from Adobe's latin character set}
	\mch{<}&	\mch{>}&	\mcs{_}&	\mch{|}\cr
	\mcs{backslash}& \mcs{setminus}& \mcs{sim}&	\mcs{mid}\cr
	\mcs{bullet}	&\mcs{lbrace}&	\mcs{rbrace}\cr
\endchartable
\endgroup
	
%}}}   new syms
%}}}  using

\section{Appendix}	
%{{{  tagged-table intrinsics

\def\taggedtable#1#2#3{
    \medskip
    \noindent{\bf Table \newtableid}\quad#1
    \medskip
    \moveleft\leftmargin\vbox{\hsize=\bodywd
	\hrule height 1pt  \medskip
	\line{\it\strut\hbox to \leftmargin{#2\hfil}{\it #3}\hfil}
	\smallskip \hrule
    }
    \tagged \everytag{\tt}
}
\def\endtaggedtable{
    \endtagged
    \removelastskip \medskip \hrule height 1pt \bigskip
}

%}}}  tagged-table intrisnics
%{{{  file types
\subsec{File suffixes}

	In this document, `a |foo| file' refers to a file of the type
	conventionally given a name ending in `-|.foo|' (using lower
	case because \TeX\ file names are always given in lower case).
	This table lists some conventional file name suffixes used for
	files in this package.

\taggedtable{File suffixes used in this package}{\hbox to
	\gridwd{Suffix\hfil Origin}}{Meaning}
\def\\#1#2{\TAG{\hbox to \gridwd{\tt#1\hfil\rm#2}}}
\\{1}{Unix}
	Manual page for a program, in |nroff| format.
\\{def}{\LaTeX~2e}
	Definitions used by macro files but not expected to be referred
	to directly in user documents.
\\{dtx}{\LaTeX~2e}
	Documented \TeX\ macros---a file which combines macro
	definitions with their printed documentation.
\\{eps}{Adobe}
	An EPSF (Encapsulated PostScript Format) file.
\\{fig}{Fig}
	A picture file in Fig's undocumented format.
\\{fnt}{PDCMAC}
	Font list---a list of fonts used in a document, generated by the
	PDCFSEL macros.
%\\{idx}{\LaTeX~$2.09$}
%	Unsorted index file.  (The lamentable convention of using |idx|
%	and |ind|, both standing for `index' but representing different
%	stages in the index-generation process, is for compatibility
%	with \LaTeX.)
\\{in}{GNU}
	Template for a configuration file---when using the |configure|
	script, the file |foo| is generated from the template |foo.in|.
\\{tex}{\TeX}
	(1)~A plain \TeX\ document. (2)~A plain \TeX\ definition file.
\\{tgz}{GNU}
	A Unix |tar| archive, compressed with GNU |zip|.  (Same as
	|tar.gz|.)
\\{txt}{traditional}
	Plain ASCII text, readable on the terminal.
\\{zip}{?PKZIP}
	An MS-DOS PKZIP archive.
\endtaggedtable
	
%}}}  file types
%{{{  file list
	
\subsec{List of files}

	Here is a list of files supplied with the package.  A list of
	the files generated from these---the definition files, used in
	documents---form the next section.

	All the names are chosen so that they may be copied onto, say,
	an ISO~9660\note{See note~1 on page 2.} or MS-DOS file system and
	back to a sensible file system without the names being changed.

\taggedtable{Files supplied in the package.}{File}{Contents}
\\{00readme.txt}
	Brief description of the package.

\\{configure}
	A shell script used to automatically configure the makefile for
	Unix systems.  (This is an unavoidable exception to the rule
	that names are ISO-9660-compatible.)

\\{copying.tex}
	A copy of the GNU General Public Licence, in \TeX able form.

\\{copying.txt}
	A copy of the GNU General Public Licence.

\\{dtxtags}
	Shellscript for making tag files in |etags|(1) format.

\\{dtxtags.1}
	A Unix manual entry for |dtxtags|.\note{This (and three more
	shellscripts used in the makefile) are not intended to be
	installed anywhere, but I~included manual pages just in case
	they are---or in case the installer is curious as to what these
	scripts do.}

\\{fig2epsf}
	A Unix shellscript that converts figures from Fig's format into
	Encapsulated PostScript Format (EPSF) version~$3.0$ files.  It
	uses |fig2dev| (from the TransFig package) to do most of the
	work.  (It munges the PostScript code produced by |fig2dev|
	2.1.4.1 so that it will print and will work with Ghostview.)

\\{fig2epsf.1}
	A Unix manual page for |fig2epsf|.  

\\{install.txt}
	Installation hints.

\\{makefile.in}
	Template from which the configuration process generates a
	makefile, used by Unix's |make| command to automate compilation
	and installation.  Should be called |Makefile.in| but that's not
	ISO-9660-compliant.

\\{magrmac.dtx}
	Documentation for Malvern Greek macros.  This replaces the file
	|magrmac.tex| included in Malvern release~$1.2$.

\\{magrman.tex}
	Brief user manual for |magrmac.tex|.  This replaces the version
	distributed with Malvern~$1.2$.  It requires some Malvern~G
	fonts.

\\{oput01.eps oput02.eps}
	Diagrams for |pdcoput5.dtx|.\note{The second edition of the {\it
	PostScript Language Reference Manual} says these should be called
	`-|.epsf|', but such names are not ISO-9660-compliant, so I~have
	switched to `-|.eps|'.}

\\{oput01.fig oput02.fig}
	Source code for the above figures (Fig format).

\\{pdcadobe.dtx}
	Source code and documentation for |pdcadobe.tex|.

\\{pdccode.dtx}
	Source code and documentation for |pdccode.tex|.

\\{pdccode.tex}
	Macros used by |dtx| files.  This file has to be included
	because |pdccode.dtx| can't be \TeX ed without it.

\\{pdccode2.tex}
	An experimental variation allowing multiple simultaneous
	code files.

\\{pdcfmt2.dtx}
	Source code and documentation for formatting macros.

\\{pdcfsel.dtx}
	Source code and documentation for font selection macros.

\\{pdcguide.dvi}
	A copy of the user guide, already run through \TeX.

\\{pdcguide.tex}
	This user guide for PDCMAC.

\\{pdcl1maa.dtx}
	Source code and documentation for |pdcl1maa.tex|.

\\{pdcmacvn.tex}
	Version number for the whole package.

\\{pdcmisc.dtx}
	Source code and documentation for some small macro files.

\\{pdcmondo.tex}
	Makes a combined listing of all the |dtx| files (except
	|pdcsty.dtx|).

\\{pdcoput5.dtx}
	Source code and documentation for an output routine.

\\{pdcsty.dtx}
	Source code and documentation for style files (|pdccmdoc.tex|,
	|ma55doc.tex|, etc.).

\\{pinstall}
	A Unix shellscript that substitutes for the |install| command on
	systems which don't have GNU |install|.\note{I am not going to
	bother trying to make a makefile that will work with all the
	different versions of |install|, since there is no easy way to
	tell them apart and they are mutually incompatible.}

\\{pinstall.1}
	A Unix manual page for |pinstall|.

\\{pmkdir}
	A Unix shellscript used to create a directory.  Unlike plain
	|mkdir|, it creates parent directories of the specified
	directory if they do not exist.  This would be called
	|pmkdirhier| but that name is not ISO-9660-compliant.

\\{pmkdir.1}
	A Unix manual page for |pmkdir|.

\\{version.txt}
	List of the version identifiers of the |dtx| files and the
	shellscripts that come with the package.
\endtaggedtable

%}}}  file list
%{{{  macro files
	
\subsec{List of definition files}

	The following files are the ones that are intended to go in the
	\TeX\ inputs area and to be used in documents.  Here a
	\dfn{macro file} is simply a file of \TeX\ definitions; a
	\dfn{style file} is a higher-level definition file that
	specifies most of the things that affect the style of a document
	(layout, fonts, macros, etc.).  Style files start by reading a
	bunch of macro files.

\taggedtable{Files generated from the |dtx| files.}{File}{Contents}
\\{ma55doc.tex}
	Style file for short documents with Malvern~55 as the text font.
	A table of contents and page headlines are generated
	automatically.

\\{ma55lft.tex}
	Style file for very short documents with Malvern~55 as the text
	font. `Leaflet'-class documents have no table of contents.  

\\{magrmac.tex}
	Macros for typesetting in Greek with Malvern fonts (or any font
	with the Malvern~G encoding).  There is a brief user's guide in
	|magrman.tex|.

\\{pdcadobe.tex}
	Support for fonts with the Adobe Standard Roman and Adobe Symbol
	repertoires\note{The \dfn{repertoire} of an encoding scheme is
	the set of characters/glyphs it includes.  Since PostScript
	fonts may be easily re-encoded, repertoire is more significant
	then the actual encoding.} in the |dvi| file, and ISO~8859--1
	(Latin-1) conventions in the manuscript file.  The output
	encoding actually used is that variation on \TeX\ Text generated
	by the |afm2tfm| that comes with DVIPS.  Newer \TeX\ systems
	should instead use PostScript fonts with (a subset of) the 1990
	Cork encoding.\note{Variously called `DC', `EC', `T1', and
	`\TeX\ Extended Text---Latin', and described in {\it TUGboat}
	10\#4.}  This file actually combines two functions: (1)~making
	the various symbols availabe via commands like |\pounds| and
	(2)~making Latin-1 characters in the manuscript produce
	corresponding characters in the output.  Described in
	|pdcadobe.dtx|.


\\{pdccmdoc.tex}
	Style file for short documents with Computer Modern Roman as the
	text font.  A table of contents and page headlines are generated
	automatically.

\\{pdccmlft.tex}
	Style file for very short documents with Computer Modern Roman
	as the text font.  `Leaflet'-class documents have no table of
	contents.

\\{pdcfmt2.tex}
	Macros for formatting text---bulleted and numbered lists, syntax
	descriptions, verbatim text, headings, etc.  Most of
	the facilities used by the style files come from this file.

\\{pdcfsel.tex}	
	Macros for selecting fonts.  Fonts are organized into
	\dfn{fontset}s (selected with macros with names like
	|\bodyfonts|) in which fonts are selected with nicknames like
	|\it|, |\bf| (specified at the start of the document using
	template macros).

\\{pdchyex.tex}
	Some random British English hyphenation exceptions (developed
	while I~was using American English hyphenation paterns).  You
	may not want to use this.  Described in |pdcmisc.dtx|.

\\{pdcimth.tex}
	Make letters in maths formulas come out in text italic instead
	of math italic.  Useful if the body font isn't CMR, or if
	multiple-letter identifiers are used.  Described in
	|pdcmisc.dtx|.

\\{pdcl1maa.tex}
	Support for documents with using the ISO~8859--1 (Latin-1)
	character set in the manuscript file and fonts with Malvern~A
	encoding in the |dvi| file.  Described in |pdcl1maa.dtx|.

\\{pdccmsub.tex}
	Define some Malvern~A and PostScript glyphs (like \yen,
	\registered) by overprinting CM glyphs.  Described in
	|pdcmisc.dtx|.

\\{pdcmigr.tex}
	Make Greek capitals in maths mode use math italic (fam~1)
	letters instead of letters from the roman font.  Especially
	useful when there are no Greek caps in the roman font.
	Described in |pdcmisc.dtx|.
\endtaggedtable
%}}}  macro files
%{{{  old files
\subsec{Obselete files}
	
	The following macro files were included with the Malvern~$1.0$
	distribution, but were not intended to be installed.
	Nevertheless they appear to have been copied into some older
	versions of the Unix\TeX\ distribution.  They are obselete, and
	their successors have new names (intended to reduce the chance
	of accidental clashes).  I'd appreciate people removing them
	from their \TeX\ systems.
\display
	|formac.tex|&
	|parmac.tex|&
	|utils.tex|&
	|ssoutput.tex|\cr
	|ldfonts.tex|&
	|malvern.tex|&
	|cmdoc.tex|\cr
\enddisplay
	The following documents are similarly obselete and should not be
	in the macros directory anyway.
\display
	|aboutmalvern.tex|&
	|latexfmv.tex|\cr
\enddisplay
	The following macro files have the new-style names, but are
	superseded by PDCMAC~$1.0$ files.  You are not required to
	remove then if you have documents using them.  Fortunately, they
	appear not to have been absorbed by the Unix\TeX\ distribution
	anyway.
\display
	|pdcfmt.tex|&
	|pdcpars.tex|&
	|pdcutil.tex|&
	|pdcoput.tex|\cr
\enddisplay
	The new versions will have the major number of their version ID
	appended to their names (e.g., |pdcfmt2.tex|), and this way new
	and old versions may coexist, allowing older documents to still
	be processed by \TeX.  The functionality of |pdcpars.tex| and
	|pdcfmt.tex| have been taken over by |pdcfmt2.tex|.
	

%}}}  old files
%{{{  gpl
	
\rigidbalancepartialpage{\bigskip}

\begingroup \notefonts \setncolumns2 \everypage{} \leftmargin=0pt
    \advance\textlistdepth2 \let\section=\subsec
    \input copying.tex
    \rigidbalancepartialpage{\bigskip}
\endgroup

	
%}}}  gpl
	
\frontmatter
%{{{  an absurd logo

\ifx\asyfam\UNDEFINED
%{{{   CMSSDC logo

\moveleft\leftmargin\vbox{

\font\titlefont=cmssdc10 at 24pt

\leftline{\titlefont P D C M A C\quad User Guide}

\bigskip	
} % end of vbox
%}}}
\else
%{{{   PostScript logo

\moveleft\leftmargin\vbox{\hsize=\bodywd
	\font\thefont=pplr at 120pt
	\input rotate

	\line{\thefont
	    \setbox0=\hbox{\lower0.975ex\hbox{pd}}\dp0=1ex \ht0=0pt \rotu0%
	    c%
	    \setbox0=\hbox{\lower0.95ex\hbox{vw}}\dp0=1ex \ht0=0pt \rotu0%
	    c\hfil
	}
}
\medskip	
\leftline{\font\thotherfont=pplri at 60pt \thotherfont
	\kern-0.1em USER GUIDE}
\bigskip

%}}}   PostScript logo
\fi	
%}}}  an absurd logo
%{{{  titlepage

\halign{#\hfil\cr
	\headingfonts Edition 1 for Release 
		$\textfont0=\font \pdcmacversion$\cr
\noalign{\medskip}%
	P. Damian Cugley\cr
\noalign{\smallskip}%
	Oxford University Computing Laboratory\cr
	Parks Road\cr
	Oxford \sc{OX2~7HN}\cr
	UK\cr
\noalign{\smallskip}%
	|damian.cugley@comlab.ox.ac.uk|\cr
}

\bigskip
\abstract
	PDCMAC is a collection of macro files intended to be useful with
	\TeX\ formats with similar conventions to those described in the
	{\it\TeX book}.  This document describes how to unpack the files
	and use them in \TeX\ documents.
\endabstract

\bigskip
	
\global\setbox\botbox\vbox{\hsize=\bodywd \prevdepth=0pt
\noindent
	{\it PDCMAC User Guide}.  \copyright~1995 P. Damian Cugley.  All
	rights reserved.  Verbatim copies of this document (including
	this copyright message) may be freely distributed.  This edition
	first published March 1995.
}

\let\section=\subsec
%}}}  title page
\endfrontmatter	

\bye
%}}}
%Local Variables:
%fill-prefix: "	"
%fold-folded-p: t
%End: