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