path: root/macros/plain/contrib/pdcmac/pdcguide.tex

% 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: