summaryrefslogtreecommitdiff
path: root/macros/plain/contrib/pdcmac/pdcfmt2.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/plain/contrib/pdcmac/pdcfmt2.dtx')
-rw-r--r--macros/plain/contrib/pdcmac/pdcfmt2.dtx1194
1 files changed, 1194 insertions, 0 deletions
diff --git a/macros/plain/contrib/pdcmac/pdcfmt2.dtx b/macros/plain/contrib/pdcmac/pdcfmt2.dtx
new file mode 100644
index 0000000000..918a960d64
--- /dev/null
+++ b/macros/plain/contrib/pdcmac/pdcfmt2.dtx
@@ -0,0 +1,1194 @@
+% pdcfmt2.dtx -- documentation & source for pdcfmt2.tex -*-tex-*-
+
+%%%@TeX-document-file {
+%%% title = "PDCFMT2 -- Formatting Macros",
+%%% filename = "$texmf/doc/plain/pdcmac/pdcfmt2.dtx",
+%%% version = "$Revision: 2.4 $",
+%%% package = "pdcmac 1.0",
+%%% date = "$Date: 1995/04/06 11:55:16 $",
+%%% author = "P. Damian Cugley",
+%%% email = "damian.cugley@comlab.ox.ac.uk",
+%%% address = "Oxford University Computing Laboratory,"
+%%% Parks Road, Oxford OX1 3QD, UK",
+%%% abstract = "This document describes and is the source code for
+%%% the TeX definitions file pdcfmt2.tex.
+%%% Running plain TeX on this file produces both the
+%%% definitions file and the printed documentation.",
+%%% copyright = "Copyright (c) 1991-1995 P. Damian Cugley",
+%%% copying = "This program is free software; you can redistribute
+%%% it and/or modify it under the terms of the GNU
+%%% General Public License as published by the Free
+%%% Software Foundation; either version 2 of the License,
+%%% or (at your option) any later version.",
+%%% notice = "This program is distributed in the hope that it will
+%%% be useful, but WITHOUT ANY WARRANTY; without even the
+%%% implied warranty of MERCHANTABILITY or FITNESS FOR A
+%%% PARTICULAR PURPOSE. See the GNU General Public
+%%% License for more details.",
+%%% notice = "You should have received a copy of the GNU General
+%%% Public License along with this program; if not, write
+%%% to the Free Software Foundation, Inc., 675 Mass Ave,
+%%% Cambridge, MA 02139, USA.",
+%%% codetable = "USASCII",
+%%% dependencies = "pdccode.tex"
+%%%}
+
+%{{{ pdcfmt2
+%{{{ preamble
+
+\relax
+\input pdccode
+\document
+\rcs$Id: pdcfmt2.dtx,v 2.4 1995/04/06 11:55:16 pdc Exp $\endrcs
+
+\def\example{
+ \smallskip\hrule\nobreak\smallskip
+ \dimen0=\hsize \advance\dimen0-1pc \divide\dimen0 2
+ \halign to \hsize\bgroup\vtop{\tt\def~{\hfil\break} \def\\{\char`\\\relax} \hsize=\dimen0 ##}\tabskip=0pt plus 1fil&
+ \vtop{\hsize=\dimen0 ##}\tabskip=0pt\cr
+}
+\def\endexample{
+ \crcr\egroup
+ \nobreak\smallskip\hrule\smallskip
+}
+
+\codefile{pdcfmt2.tex}
+%}}} preamble
+%{{{ introduction
+
+\author{P. Damian Cugley}
+\title{PDCFMT2---Formatting Macros}
+\section{Introduction}
+
+ This document describes |pdcfmt2.tex|, a collection of
+ formatting macros for plain \TeX\ documents. For example, it
+ defines commands for making bulleted lists, verbatim text, and
+ generic headings. For longer documents, a higher-level `style
+ file' like |pdccmdoc.tex| will define commands to start sections
+ and generate a table of contents and so on.
+
+ The definitions file and the printed documentation are both in
+ |pdcfmt2.dtx|, a `documented \TeX\ macros' file\footnote*{The
+ \LaTeX~2e distribution uses files with the `|dtx|' suffix for
+ similar purposes.} which, when processed by plain \TeX,
+ generates a fresh copy of |pdcfmt2.tex| in the current directory
+ in addition to the |dvi| file. This ensures that the printed
+ documentation and the code it describes are identical. The
+ |dtx| file uses the macros in |pdccode.tex|.
+
+ The name of the macros file ends in `-|2|' to prevent confusion
+ with |pdcfmt.tex| version 1.1.10, with which it is slightly
+ incompatible.
+
+%}}} introduction
+%{{{ File identification
+\section{File identification}
+
+ Nowadays, macro files start with some comments identifying the
+ file.
+
+\code
+ \|\% pdcfmt2.tex \fileversion~\filedate~-- macros for formatting
+ |
+ |%%%@TeX-definition-file {
+ |%%% filename = "$texmf/tex/plain/pdcmac/pdcfmt2.tex",
+ \|\%\%\% version~~~~~~~~= "\fileversion",
+ \|\%\%\% date~~~~~~~~~~~= "\filedate",
+ |%%% package = "pdcmac 1.0",
+ |%%% author = "P. Damian Cugley",
+ |%%% email = "damian.cugley@comlab.ox.ac.uk",
+ |%%% address = "Oxford University Computing Laboratory,
+ |%%% Parks Road, Oxford OX1 3QD, UK",
+ |%%% codetable = "USASCII",
+ |%%% keywords = "TeX, plain TeX, macros",
+ |%%% supported = "Maybe",
+ |%%% abstract = "Formatting macros for plain TeX documents.
+ |%%% This file was generated by running
+ \|\%\%\%~~~~~~~~~~~~~~~~~~~plain TeX on \jobname.dtx",
+ |%%% copyright = "Copyright (c) 1991-1995 P. Damian Cugley",
+ |%%% copying = "DO NOT DISTRIBUTE THIS FILE.
+ \|\%\%\%~~~~~~~~~~~~~~~~~~~Distribute \jobname.dtx only as part of the
+ |%%% package it came in.",
+ |%%% dependencies = "",
+ |%%% }
+ |
+ \|\\message\{\fileversion~<pdc \filedate>\}
+ |
+\endcode
+
+%}}} getting started
+%{{{ internal
+
+\section{Internal definitions}
+
+ Most internal control sequence names will start with `|FMT|'.
+ Here are a few miscellaneous definitions used to save a token
+ here or there.
+
+ I will often use |\toksa| to create definitions containing
+ characters with unusual catcodes. The idiom is
+$$\halign{\indent#\hfil\cr
+ |\begingroup| \<assignments> |\toksa={\endgroup|\cr
+ \quad\<definitions>\cr
+ |} \the\toksa|\cr
+}$$
+ When |\toksa| is expanded, it closes the group (undoing the
+ \<assignments>) but then scans the \<definition> using the
+ catcodes set by \<assignments>. (In extreme cases, the
+ definition of |\toksa| might be enclosed in |\uppercase|, to get
+ strange characters into a definiton.)
+
+ The advantage of this idiom over using |\gdef| in a group is
+ that the definitions need not be global. Avoiding global
+ assignments makes it more likely that the document will be
+ embeddable in other documents.
+
+ Using |\toksa| instead of |\toks0| is more robust when using
+ |\uppercase|, because digits are be given |\uccode| values by
+ |maamac.tex|.
+\code
+ |\toksdef\toksa=0
+ |\chardef\other=12
+\endcode
+
+%}}} internal
+%{{{ verbatim text
+
+\section{Verbatim text}
+
+ `Verbatim' text means text designed to match the ASCII
+ characters in the manuscript file as closely as possible. It
+ kis most often used in computer manuals, where commands typed to
+ a computer or the contents of text files are to be presented.
+ Within verbatim text, most of \TeX's special characters are
+ temporarily disabled.
+
+\subsec{Lists of active chararcters}
+
+ The verbatim text macros need to know if any characters have
+ been made special apart from the usual ones. This command tells
+ the verbatim macros that |#1| is an active char; in addition to
+ setting its catcode, this makes sure that the character will be
+ re-catcoded appropriately when in verbatim mode. |#1| should be
+ a something that will work after `|`|'; usually this means a
+ one-character control sequence.
+\code
+ |\def\declareactivechar#1{%
+ | \toksa\expandafter{\verbatimplains\do#1}%
+ | \edef\verbatimplains{\the\toksa }%
+ | \catcode`#1\active
+ |}
+\endcode
+
+ Two list macros in the style of |\dospecials| are defined. The
+ first is for characters that must be set to catcode~12, such as
+ `|\|', `|{|', `|}|', `|_|', `|$|', `|#|', `|&|', and `|%|'. The
+ other is for a few characters that are given catcode~13, such as
+ `|`|', `|'|', `|~|', `|^|' and SP.
+\code
+ |\def\verbatimplains{\do\\\do\{\do\}\do\_\do\$\do\#\do\&\do\%}
+ |\def\verbatimactives{\do\-\do\`\do\'\do\~\do\^\do\ }
+\smallbreak
+ |\chardef\other=12
+\endcode
+
+\subsec{Setting up verbatim mode}
+
+ This is a macro common to various verbatim text modes. The
+ default spacing of whatever font is used, without any
+ adjustments of spacefactor for punctuation. The characters
+ `|`|', `|'|', `|~|', and `|^|' are produce slightly lowered
+ glyphs.
+\code
+ |\newtoks\everyverbatim
+\smallbreak
+ |\bgroup \catcode`\-=13\catcode`\^=13 \catcode`\'=13 \catcode`\`=13 \toksa={\egroup
+ | \def\setupverbatim{%
+ | \frenchspacing
+ | \spaceskip0pt \xspaceskip0pt % use spacing of font
+ | \def\do##1{\catcode\lq##112 }\verbatimplains
+ | \def\do##1{\catcode\lq##1\active }\verbatimactives
+ | \let`\ttlq \let'\ttrq
+ | \let~\tttilde \let^\ttcircum \let-\ttminus
+ | \the\everyverbatim
+ | }
+ |}\the\toksa
+\endcode
+
+ Here are the definitions for the munged glyphs. These are only
+ necessary in CM Typewriter; when using a PostScript font,
+ different definitions would be necessary.
+
+ The names `rq' and `lq' are based on the use of |\lq| and |\rq|
+ in plain \TeX. An alternative definition for |\ttrq| would be
+ |\chardef\ttrq="0D|, producing `{\tt\char"0D }'.
+\code
+ |\def\ttlq{\lower0.125ex \hbox{\char18 }}
+ |\def\ttrq{\lower0.125ex \hbox{\char19 }}
+ |\def\tttilde{\lower0.5ex \hbox{\char`\~ }}
+ |\def\ttcircum{\lower0.5ex \hbox{\char`\^ }}
+ |\def\ttminus{-}
+\endcode
+ This makes the difference between |`'^~| and
+ {\tt`'\char`\^\char`\~}.
+
+ The macro |\ttminus| is included because it is needed for
+ PostScript font support.
+
+\subsec{Defining a self-matching character for verbatim text}
+
+ A macro for defining a self-matching verbatim character (I~got
+ the idea of a macro for declaring verbatim characters from the
+ \LaTeX~2e documentation macros). |#1| must be a one-character
+ control sequence. If it isn't active already, then
+ |\declareactivechar| is applied to it first.
+\code
+ |\def\defverbatim#1{%
+ | \ifcat\noexpand#1\noexpand~\else \declareactivechar#1 \fi
+ | \begingroup \uccode`\~=`#1 \uppercase{\toksa={\endgroup
+ | \def~{%
+ | \leavevmode
+ | \begingroup \tt \setupverbatim
+ | \catcode`#1\active \let~\endgroup
+ | }%
+ | }}\the\toksa
+ |}
+\endcode
+ Note that there must be a font called |\tt| for it to switch to.
+ (The catcode of |#1| is set to 13 after calling |\setupverbatim|
+ because |#1| will be included in |\verbatimplains|.)
+
+ Finally, we define vertical bar as the conventional
+ self-matching verbatim-mode character.
+\code
+ |\defverbatim\|
+\endcode
+ Both |\defverbatim| and |\defineactivechar| have local scope.
+
+\subsec{List a file verbatim}
+
+ This does something similar to the |lines| environment (see
+ below), except here an external file is read in verbatim (see
+ {\it\TeX book} Appendix~D, Section~3). The
+ |\startlinenumbering| macro may be put in the |\everylisting|
+ token register to create a listing with numbered lines.
+\code
+ |\newtoks\everylisting
+\smallbreak
+ |\def\listfile#1{
+ | \medskip
+ | \begingroup
+ | \parindent=0pt \parskip=0pt
+ | \def\par{\null\endgraf}\obeylines
+ | \setupverbatim \maketabstab
+ | \tt \the\everylisting
+ | \input#1
+ | \endgroup
+ | \medskip\noindent\ignorespaces
+ |}
+\endcode
+ This macro redefines character |^^I| (horizontal tab) to produce
+ the equivalent of eight spaces. This isn't quite the same as
+ what HTs are used for with UNIX files, but it works adequately
+ if all your tabs are at the start of the line (i.e., if tabs are
+ used only for indentation, not to make tables).
+\code
+ |{\catcode`\^^I=\active
+ | \gdef\maketabstab{\catcode`\^^I\active \def^^I{\hskip 4em}}
+ |}
+\endcode
+
+%}}} verbatim text
+%{{{ everypar
+
+\section{Everypar hacks}
+
+\subsec{Parameters}
+
+ The following may be set by higher-level macros to change the
+ apearance of the next paragraph.
+
+ If the flag |\ifnoindent| is set, then the indentation of the
+ next paragraph will be removed (by deleting the box added by
+ \TeX's |\indent| primitive). Thus |\noindenttrue| works like
+ |\noindent|, except that there may be blank lines between
+ |\noindenttrue| and the paragraph it affects.
+\code
+ |\newif\ifnoindent
+\endcode
+ This flag is reset globally once it has had its effect.
+
+ If the box |\parbox| is non-void, then its value is typeset in
+ the left margin of the next paragraph. (At present this does an
+ implicit |\noindenttrue| but later versions may allow the next
+ paragraph to be indented.) The righthand edge of the parbox
+ will be distance |\parboxsep| from the left edge of the text
+ area.
+\code
+ |\newbox\parbox
+ |\newdimen\parboxsep \parboxsep=1pc
+\endcode
+
+\subsec{Setting \cs{everypar}}
+\code
+ |\everypar={%
+ | \ifvoid\parbox
+ | \ifnoindent {\setbox0=\lastbox}\global\noindentfalse \fi
+ | \else
+ | {\setbox0=\lastbox}\global\noindentfalse
+ | \dp\parbox=0pt
+ | \hbox to 0pt{\hss \box\parbox \hskip\parboxsep}%
+ | \fi
+ |}
+\endcode
+%}}} everypar
+%{{{ environment intrinsics
+
+\section{Environment infrastructure}
+
+ An environment is a structure used to typeset textual elements
+ consisting of several \TeX\ paragraphs (usually embedded within
+ one conceptual paragraph). It is a concept like \LaTeX\
+ environments, but with the syntax changed to be more
+ plain-\TeX-like.
+
+ Since environments have one argument that may span many lines in
+ the file we use more verbose brackets than |{|--|}| to make it
+ easier to spot where they begin and end. This is a structure in
+ a document looking like this:
+ $$
+\vbox{\halign{#\hfil\cr
+ |\|\<name>\<args>\cr
+ \quad\dots\cr
+ |\end|\<name>\cr
+}}
+ $$
+
+ A new environment is defined by defining macros called
+ |\|\<name> and |\end|\<name>. Within the |\|\<name> and
+ |\end|\<name> macros, calls to |\beginthe| and |\endthe| are
+ used to check that environments are nested properly.
+\code
+ |\def\beginthe#1{%
+ | \begingroup\def\PDCFMTblockname{#1}%
+ |}
+\smallbreak
+ |\def\endthe#1{%
+ | \def\tmp{#1}%
+ | \ifx\tmp\PDCFMTblockname
+ | \endgroup
+ | \else
+ | \errmessage{You should have said \string\endthe{\blockname}}%
+ | \fi
+ |}
+\endcode
+
+\subsec{A generic end-of-environment macro}
+
+ This macro does a |\smallskip| (if there is not already a larger
+ skip on the current list), and sets the `noindent' flag so that
+ the following \TeX\ paragraph is not indented.
+\code
+ |\def\PDCFMTendenv#1{
+ | \smallskip
+ | \endthe{#1}
+ | \global\noindenttrue
+ |}
+\endcode
+
+ Where an environment describes text that should be indented,
+ usually |\parindent| should be used (for consistency). If
+ |\parindent| is zero we still want to indent the text, and we
+ use |\envindent| to describe how much to indent it by.
+\code
+ |\newdimen\envindent \envindent=1pc
+\smallskip
+ |\def\PDCFMTindent{%
+ | \ifdim\parindent>0pt
+ | \parindent
+ | \else
+ | \envindent
+ | \fi
+ |}
+\endcode
+
+%}}} environment intrinsics
+%{{{ quotations
+
+\section{Quotations}
+
+ This is a simple environment, with the left margin indented and
+ the first paragraph in the quotetd text not indented.
+\example
+ It is ... who said~
+ \\quotation~
+ \indent Shookum hip rallo dyne.~
+ \\endquotation~
+ Indeed, it burgle gurgler.
+&
+ It is interesting to remember the words of
+ Spencone Tipeth, who said
+ \smallskip\leftskip\parindent \noindent
+ Shookum hip rallo
+ dyne.\smallskip\leftskip0pt \noindent Indeed, it burgle gurgler.
+\endexample
+The token
+ register |\everyquotation| might be used to arrange for all
+ quotations to be in smaller type with
+ $$\hbox{|\everyquotation={\smallfonts}|}$$
+\code
+ |\newtoks\everyquotation
+\smallbreak
+ |\def\quotation{
+ | \smallskip
+ | \beginthe{quotation}
+ | \advance\leftskip\PDCFMTindent
+ | \noindenttrue
+ | \the\everyquotation
+ |}
+\smallbreak
+ |\def\endquotation{\PDCFMTendenv{quotation}}
+\endcode
+ The differences from using |{\narrower|\dots|\par}| (apart from
+ how it looks in the source file) include (a)~the right margin
+ isn't indented; (b)~it indents by |\envindent| if there is no
+ |\parindent| and (c)~it is preceeded and followed by a
+ smallskip.
+%}}} quotations
+%{{{ textlists (bullets + numbered)
+
+\section{Textlists---bulleted or numbered lists}
+
+ Here's a generic list-of-items environment, used to implemented
+ bulleted and numbered lists. Each item is started with the
+ convenient |\\| macro (and so may contain more than one
+ paragraph). It is called a `textlist' to distinguish it from
+ other meanings of the word `list'. Usually textlists will be
+ generated with higher-level macros like |\bullets| and
+ |\numbered|.
+
+\subsec{A generic textlist environment}
+
+ The token register |\everytextlist| is expanded at the start
+ of every textlist. The level of nesting is recorded in
+ |\textlistdepth| (a to-level list is depth~0, a list inside
+ that is depth~1, and so on). The flag |\ifnumbered| controls
+ whether items are numbered (using |\numberfordepth|) or
+ bulleted (using |\bulletfordepth|).
+\code
+ |\newtoks\everytextlist
+ |\newif\ifnumbered
+ |\newcount\textlistdepth \textlistdepth=-1
+ |\newcount\textlistcount
+\smallbreak
+ |\def\textlist{%
+ | \par
+ | \beginthe{textlist}
+ | \advance\textlistdepth 1
+ | \textlistcount0
+ | \def\\{
+ | \smallskip\noindent
+ | \advance\textlistcount1
+ | \llap{%
+ | \ifnumbered
+ | \numberfordepth\textlistdepth\textlistcount
+ | \else
+ | \bulletfordepth\textlistdepth
+ | \fi\enspace}%
+ | \ignorespaces
+ | }
+ | \advance\leftskip\PDCFMTindent
+ | \the\everytextlist
+ |}
+\smallbreak
+ |\def\endtextlist{\PDCFMTendenv{textlist}}
+\endcode
+
+\subsec{Bulleted lists}
+
+ This describes a bulleted list, where each paragraph is indented
+ and preceeded by a mark in the margin.
+\example
+ I would like to make...~\\bullets~\\\\ this point; and~\\\\ that
+ point~\\endbullets~And so on and so forth.
+& I would like to make the following very important and relevant
+ itemized points:\smallskip\item{$\bullet$}this point;
+ and\smallskip\item{$\bullet$}that
+ point\smallskip\noindent And so on and so forth.
+\endexample
+Bullets environments may
+ be nested, in which case different marks are used. The sign is
+ chosen with |\bulletfordepth|.
+\code
+ |\newtoks\everybullets
+\smallbreak
+ |\def\bullets{\textlist \numberedfalse \the\everybullets}
+ |\let\endbullets=\endtextlist
+\smallbreak
+ |\def\bulletfordepth#1{%
+ | \ifcase#1 $\bullet$\or --\or $\circ$\else $\cdot$\fi
+ |}
+\endcode
+
+
+\subsec{Numbered lists}
+
+ The numbered list is similar. The style of numbering changes
+ with the listing depth; you can change this by redefining
+ |\numberfordepth|.
+ $$
+\centerline{\vbox{\halign{#\hfil&\qquad\hfil# &&\hfil# \cr
+ Depth 0&1.&2.&3.&\dots\cr
+ Depth 1&(1)&(2)&(3)&\dots\cr
+ Depth 2&({\it a\/})&({\it b\/})&({\it c\/})&\dots\cr
+ Depth 3+&(i)&(ii)&(iii)&\dots\cr
+}}}
+ $$
+ There is also a token regieter |\everynumbered| for any extra
+ customization. This is read after |\everytextlist|.
+\code
+ |\newtoks\everynumbered
+\smallbreak
+ |\def\numbered{\textlist \numberedtrue \the\everynumbered}
+ |\let\endnumbered=\endtextlist
+\smallbreak
+ |\def\numberfordepth#1#2{%
+ | \ifcase#1 \n{\number#2}.\or (\n{\number#2})\or
+ | ({\it\alphabetletter#2\/})\else (\romannumeral#2)\fi
+ |}
+\endcode
+ It turns out that sometimes it is useful to be able to impose a
+ format on numbers generated by formatting macros. For example,
+ I~occasionally find it useful to force all numbers to be
+ generated in maths mode. To do this, all numbers generated by
+ macros are enclosed in |\n{|--|}|. By default, |\n| is
+ equivalent to |\relax|.
+\code
+ |\let\n\relax
+\endcode
+
+\subsec{Picking a letter of the alphabet}
+
+ This macro behaves as much like the primitives |\number| and
+ |\romannumeral| as it can: it expands entirely within \TeX's
+ mouth, and so may be used in |\edef|s and the like. It produces
+ |???| or |!!!| if its argument is not in the range 1--26.
+ The macro is defined so as to reduce the number of tokesn to be
+ skipped when |#1| is less than 6.
+\code
+ |\def\alphabetletter#1{%
+ | \ifcase#1 ??? \or a\or b\or c\or d\or e\else
+ | \xxxalphabetletter#1\fi
+ |}
+ |\def\xxxalphabetletter#1{%
+ | \ifcase#1 \or\or\or\or\or\or f\or g\or h\or i\or j\or
+ | k\or l\or m\or n\or o\or p\or q\or r\or s\or t\or u\or
+ | v\or w\or x\or y\or z\else !!!\fi
+ |}
+\endcode
+
+%}}} textlists (bullets + numbered)
+%{{{ tagged list
+
+\section{Tagged lists}
+
+ In other words, description lists. Each paragraph starts with
+ the `tag' set either in the left margin or sticking in to the
+ current line if it is too long to fit. The tag for each
+ paragraph is introduced with `|\\|\arg{\<text>}'.
+
+ The maximum width of tag labels (including the 1\thinspace en
+ space that goes between label and text) in is stored in
+ |\tagmaxwidth|. If there is not room, then the label is run on
+ in to the paragraph and separated from the text by a quad space.
+\code
+ |\newdimen\tagmaxwidth
+\endcode
+ As well as giving a new definition to the |\\| macro, the
+ |\tagged| command mast choose a value for |\tagmaxwidth|. If
+ there is a large left margin (signalled by giving |\leftmargin|
+ a positive value) then tags will go in there; otherwise the text
+ will be indented and the amount of indentation used as the
+ maximum label width.
+\code
+ |\newtoks\everytagged
+\smallbreak
+ |\def\tagged{%
+ | \par
+ | \beginthe{tagged}
+ | \let\\\TAG
+ | \ifdim\leftmargin=0pt
+ | \tagmaxwidth\PDCFMTindent
+ | \else
+ | \tagmaxwidth\leftmargin
+ | \fi
+ | \the\everytagged
+ | \ifdim\tagmaxwidth>\leftmargin
+ | \leftskip\tagmaxwidth \advance\leftskip-\leftmargin
+ | \fi
+ |}
+\smallbreak
+ |\def\endtagged{\PDCFMTendenv{tagged}}
+\endcode
+ The adjustment to |\leftmargin| comes after scanning
+ |\everytagged| so that it is possible to adjust |\tagmaxwidth|
+ inside |\everytagged|.
+
+ Trickery with |\futurelet| and |\aftergroup| (like that used in
+ plain \TeX's |\footnote| command) is used to allow catcode
+ changes in \<text> to work. This allows macros that generate
+ `verbatim' text to work.
+\code
+ |\newtoks\everytag
+\smallbreak
+ |\def\TAG{%
+ | \smallskip\noindent
+ | \setbox0=\hbox\bgroup % matched by \TAGfinish
+ | \the\everytag\ignorespaces
+ | \futurelet\next\TAGtest
+ |}
+\smallbreak
+ |\def\TAGtest{%
+ | \ifcat\bgroup\noexpand\next
+ | \let\next\TAGgotbrace
+ | \else
+ | \let\next\TAGnobrace
+ | \fi \next
+ |}
+\smallbreak
+ |\def\TAGgotbrace{%
+ | \bgroup\aftergroup\TAGfinish
+ | \let\next
+ |}
+\smallbreak
+ |\def\TAGnobrace#1{%
+ | #1\TAGfinish
+ |}
+\smallbreak
+ |\def\TAGfinish{%
+ | \unskip\hskip0.5em\egroup % matches \TAG
+ | \ifdim \wd0 < \tagmaxwidth
+ | \wd0=\tagmaxwidth
+ | \llap{\box0}%
+ | \else
+ | \hskip-\tagmaxwidth
+ | \unhbox0 \unskip\quad
+ | \fi
+ | \ignorespaces
+ |}
+\endcode
+ It might be interesting to generalize these macros so that new
+ macros with an argument scanned this way may be created more
+ easily.
+%}}} tagged list
+%{{{ lines
+
+\section{Lines environment (for program listings etc)}
+
+ In the |lines| environment, each line in the manuscript file
+ becomes a new paragraph (i.e., a separate line on the printed
+ page). A |%| at the end of a line may be used to split a file
+ line in to several logical lines. In addition, the |lines|
+ environment is bracketed by horizontal rules. The effect is
+ similar to that produced by the |\beginlines|--|\endlines|
+ macros in {\it\TeX book} Appendix~E.
+
+\code
+ |\newtoks\everylines
+\smallbreak
+ |\def\lines{
+ | \par
+ | \beginthe{lines}
+ | \nobreak\smallskip\hrule\nobreak\smallskip
+ | \obeylines
+ | \parindent=0pt \parskip=0pt
+ | \parfillskip=0pt plus 1fil
+ | \the\everylines
+ | \nobreak
+ |}
+\smallbreak
+ |\def\endlines{
+ | \nobreak\smallskip
+ | \endthe{lines}
+ | \hrule\smallskip
+ | \global\noindenttrue
+ |}
+\endcode
+
+ For longer listings it may be nice to have the lines numbered
+ for later reference. The following two macros may be put in
+ |\everylines| to enable line numbering---the first starts from~1
+ in each listing environment, the other continues the numbering
+ from where it left off.
+
+ The line number is kept in |\linenumber| (which may be adjusted
+ by the user). Only every 5th line is numbered. The number of
+ lines until the next printed one is held in |\PDCFMTcount|.
+ Both these are always set globally (which means lines
+ environments cannot be nested!).
+\code
+ |\newcount\linenumber
+ |\newcount\PDCFMTcount
+\smallbreak
+ |\def\startlinenumbering{%
+ | \global\linenumber=0 \global\PDCFMTcount=5
+ | \everypar{\numberthisline}%
+ |}
+\smallbreak
+ |\def\continuelinenumbering{%
+ | \everypar{\numberthisline}%
+ |}
+\endcode
+
+ The |\numberthisline| macro is invoked at the beginning of every
+ paragraph. It increments |\linenumber|, and writes the line
+ number of every fifth line in the right margin. By default it
+ uses the same font as used in subscripts; this can be changed by
+ changing the token register |\everylinenum|.
+\code
+ |\newtoks\everylinenum \everylinenum{\the\scriptfont0 }
+\smallbreak
+ |\def\numberthisline{%
+ | \strut
+ | \global\advance\linenumber1 \global\advance\PDCFMTcount-1
+ | \ifnum\PDCFMTcount>0 \else
+ | \global\advance\PDCFMTcount 5
+ | \rlap{\the\everylinenum \kern\hsize\kern1em \the\linenumber}%
+ | \fi
+ |}%
+\endcode
+
+ Within the lines environment it can be useful to indicate where
+ lines have been skipped. This macro also adjusts the
+ |\linenumber| macro.
+\code
+ |\def\linesskipped#1{%
+ | \strut \hskip20pt $\vdots$ \hskip20pt
+ | {\rm(\it #1 lines omitted\rm)}\par
+ | \advance\linenumber#1\relax
+ |}
+\endcode
+
+%}}} lines
+%{{{ display, table
+
+\section{Displays, Tables -- wrapper about \cs{halign}}
+
+ The |display| environment does a generic (meaning not
+ necessarily mathematical) display, in a manner similar to the
+ |\begindisplay|--|\enddisplay| macros in {\it\TeX book}
+ Appendix~E. As with Knuth's macro, assignments may follow on
+ the same line as |\display|, and |\cr| and |&| may be used to
+ split the display into rows and columns.
+\code
+ |\outer\def\display{\obeylines\startdisplay}
+ |\bgroup\obeylines \toksa={\egroup %
+ | \def\startdisplay#1^^M{%
+ | \catcode`\^^M=5 $$ #1 % matched by \enddisplay
+ | \displayindent\PDCFMTindent %
+ | \halign\bgroup##\hfil&&\quad##\hfil\cr %
+ | } %
+ |}\the\toksa %
+\smallbreak
+ |\def\enddisplay{\crcr\egroup$$}
+\endcode
+
+ The |table| environment is similar, ecept that what follows
+ |\table| is an arbitrary |\halign| specification.
+\code
+ |\def\table{%
+ | $$ % matching $$ is in \endtable
+ | \displayindent\PDCFMTindent
+ | \halign \bgroup
+ |}
+\smallbreak
+ |\let\endtable=\enddisplay
+\endcode
+
+\notepar
+ Both the {\tt table} and {\tt display} environments must go
+ within paragraphs. That is, there should not be blank lines
+ before |\table|, or after |\endtable| unless the table ends the
+ paragraph.
+\endnotepar
+%}}} display, table
+%{{{ ebnf
+
+\section{(E)BNF}
+
+ BNF is Bakus-Naur Formalism; EBNF is Extended BNF. The same
+ environment does either format. The style I~happen to like, has
+ non-terminal sumbols written like \<this>, and terminal symbols
+ enclosed in `--'. Optional text is enclosed in brackets (I~like
+ to put spaces between the brackets and the enclosed text for
+ clarity) and repeatable text in braces.
+
+ In the manuscript file, each production is a separate paragraph.
+ The macro |\>| goes between the left hand side and right hand
+ side of a production; by default, it expands to `$::=$'.
+ Alternatives are separated by |\\|; by default this expands to a
+ bar `$\mid$'. If the terminal symbols happen to be keyboard
+ characters, use the verbatim text character {\tt\char`\|} which
+ adds quotation marks around the text it produces. For example,
+ the following expression
+ $$
+ \hbox{\<foo>\enspace$::=$\enspace`|f|' `|o|' `|o|' $\mid$
+ \<bar> [ \<mumble> `{\bf munge}' ].}
+ $$
+ may be produced with
+ $$
+ \defverbatim\~
+ \hbox{~\<foo> \> |f| |o| |o| \\ \<bar> [ \<mumble> `{\bf munge}' ].~}
+ $$
+ Braces are produced with |\{| and |\}|.
+
+\code
+ |\newtoks\everybnf
+\smallbreak
+ |\def\bnf{
+ | \nobreak\smallskip
+ | \beginthe{bnf}
+ | \advance\leftskip2\parindent \parindent=-\parindent
+ | \parskip0pt plus 1pt
+ | \rightskip=1\rightskip plus 3em
+ | \def\\{$\mid$}
+ | \def\>{\unskip\enspace$::=$\enspace\ignorespaces}
+ | \def|{`\begingroup\tt\setupverbatim\catcode`\|=13
+ | \def|{\endgroup'}}
+ | \def\{{$\lbrace$} \def\}{$\rbrace$}
+ | \the\everybnf
+ |}
+\smallbreak
+ |\def\endbnf{
+ | \smallskip
+ | \endthe{bnf}
+ | \global\noindenttrue
+ |}
+\endcode
+
+ The macro |\<| is based on the one in Appendix~E of the {\it\TeX
+ book}. For example, |\<foo>| produces `\<foo>'.
+\code
+ |\def\<#1>{\leavevmode\hbox{$\langle${\it#1\/}$\rangle$}}
+\endcode
+ The difference is that the name is in italics: \<name> not
+ $\langle$name$\rangle$.
+
+\notepar
+ This macro is not intened for be used to generate character
+ names like Return and Tab; I suggest just saying `Return' and
+ `Tab' for these.
+
+ There is a style of RFC-822 email addresses written in the form
+ `\/|Damian Cugley <pdc@alleged.co.uk>|'. I suggest that when
+ presenting email addresses in printed documents this be rendered
+ as something like `\/{\rm Damian Cugley (|pdc@alleged.co.uk|)}'.
+\endnotepar
+%}}} ebnf
+%{{{ headings
+
+\section{Headings}
+
+ Here are some macros for making headings for sections of a
+ document. There are two styles of layout supported by these
+ heading macros: the usual style~$N$, with headings above the
+ first paragraph of the section, and the `tab-indexed' style~$T$,
+ with headings in the left margin, aligned with the first line of
+ the paragraph.
+
+
+\subsec{The left margin parameter}
+ For style~$T$ headings, this is the size of the extra margin at
+ the left side of the page (so $({\it hoffset}+1\,{\rm in})-{\it
+ leftmargin}$ is the margin between the left edge of headings and
+ the edge of the paper). Set this parameter to $0\pt$ for
+ style~$N$.
+
+\code
+ |\newdimen\leftmargin
+\endcode
+
+
+\subsec{Headings that don't start a new page}
+
+ This macro is intended to be used by higher-level macro with
+ names like |\section|, which take care of numbering section
+ headings and so on.
+ $$
+ \hbox{\tt\cs{doheading}\arg{\<skip>}\arg{\<style>}%
+ \arg{\<coda>}\arg{\<text>}}
+ $$
+ Where \<skip> is the skip to put before the heading (for
+ example, a \<dimendef token> like like |\medskipamount| or
+ |\bigskipamount|, or a \<dimen> enclosed in braces); \<style> is
+ tokens to insert before the \<text> (such as assignments that
+ select the font); \<coda> is tokens that follow the \<text>
+ (which might produce a rule under the heading, for example;
+ usually this is empty); and \<text> is the text of the heading
+ supplied by the user.
+\code
+ |\newskip\headingtemp
+ |\def\doheading#1#2#3#4{
+ | \ifdim\lastskip<#1\relax \removelastskip \vskip#1\relax \fi
+ | \ifdim \leftmargin>0pt
+\endcode
+ If the left margin is greater than zero then we generaten a
+ style~$T$ heading. This is done by putting the text in
+ |\parbox|, which will be used by the |\everypar|.
+\code
+ | \global\setbox\parbox=\vtop{%
+ | \hsize=\leftmargin \advance\hsize-\parboxsep
+ | \parindent=0pt
+ | \leftskip=0pt \rightskip=0pt plus 3em
+ | \hyphenpenalty=10000 \exhyphenpenalty=5000
+ | \strut#2#4#3
+ | }
+ | \else
+\endcode
+ Otherwise we typeset the heading as a separate paragraph.
+\code
+ | \begingroup
+ | \parindent=0pt \parfillskip=0pt plus 1fil
+ | \leftskip=0pt \rightskip=0pt plus0.25\hsize
+ | \hyphenpenalty=10000 \exhyphenpenalty=5000
+ | \strut#2#4#3
+ | \global\headingtemp=\baselineskip
+ | \par
+ | \endgroup
+\endcode
+ The vertical space between the heading and the following text is
+ calculated from the difference in baselineskips between the
+ fonts used in the heading and those used in body text, plus $\it
+ smallskipamount$.
+\code
+ | \advance\headingtemp-\baselineskip
+ | \ifdim\headingtemp>0pt \nobreak \vskip 1.0\headingtemp \fi
+ | \smallskip
+ | \noindenttrue
+ | \fi
+ |}
+\endcode
+
+\subsec{Headings that start a new page}
+
+ Major divisions of a book start on a nw page. The parameters to
+ the macro are similar to those for |\doheading|:
+ $$
+ \hbox{\tt\cs{newpageheading}\arg{\<skip>}\arg{\<style>}%
+ \arg{\<coda>}\arg{\<text>}}
+ $$
+ Where here the \<skip> is the extra space at the top of the page.
+
+\code
+ |\def\newpageheading#1#2#3#4{
+ | \vfill\supereject % ensure no insertions still floating
+ | \null\vskip#1\relax
+ | \moveleft\leftmargin\vbox{
+ | \advance\hsize\leftmargin
+ | \parindent=0pt \parfillskip=0pt plus 1fil
+ | \leftskip=0pt \rightskip=0pt plus0.25\hsize
+ | \hyphenpenalty=10000 \exhyphenpenalty=5000
+ | #2\strut#4#3
+ | \global\headingtemp=\baselineskip
+ | \par
+ | }
+ | \advance\headingtemp-\baselineskip
+ | \advance\headingtemp\smallskipamount
+ | \vskip \headingtemp
+ | \noindenttrue
+ | \def\tmp{#4}
+ | \message{*\expandafter\TOCtrim\meaning\tmp. }
+ |}
+\endcode
+%}}} headings
+%{{{ footnotes
+\section{Footnotes}
+
+ We define a new command |\note| that replaces use of the
+ |\footnote| command. This takes one parameter---the text of the
+ footnote---and supplies automatically-numbered footnote markers.
+
+ The |\newcount| command implicitly sets the counter to~0.
+
+\code
+ |\newcount\notecount
+\smallskip
+ |\def\note{%
+ | \global\advance\notecount+1
+ | \footnote{\number\notecount}%
+ |}
+\endcode
+
+ We add a parameter for the indentation of footnote paragraphs.
+\code
+ |\newdimen\footnoteparindent
+ |\footnoteparindent=\parindent
+\endcode
+
+ Now we modify the definition of |\footnote| in plain~\TeX\ (see
+ TeXbook p.\thinspace363). It has the same function as
+ plain~\TeX's |\footnote|, but uses extra parameters
+ (|\everyfootnote|, |\footnotetextmark|), and handles the case
+ ${\it parindent}=0\pt$.
+\code
+ |\newtoks\everyfootnote
+\smallbreak
+ |\catcode`\@=11
+ |\def\footnote#1{\let\@sf\empty
+ | \ifhmode\edef\@sf{\spacefactor\the\spacefactor}\/\fi
+ | \footnotetextmark{#1}\@sf\vfootnote{#1}}
+\smallbreak
+ |\def\vfootnote#1{\insert\footins\bgroup % matched by \@foot
+ | \interlinepenalty=\interfootnotelinepenalty
+ | \parindent=\footnoteparindent
+ | \leftskip=0pt
+ | \the\everyfootnote
+ | \splittopskip=\ht\strutbox \splitmaxdepth=\dp\strutbox
+ | \floatingpenalty=20000
+ | \indent\footstrut
+ | \ifdim\parindent>1em
+ | \llap{\footnotenotemark{#1}\enspace}%
+ | \else
+ | \footnotenotemark{#1}\enspace
+ | \fi
+ | \futurelet\next\fo@t
+ |}
+\smallbreak
+ |\def\@foot{\smallskip\egroup}
+\smallskip
+ |\catcode`\@=12
+\endcode
+ These two parameters control the formatting of the footnote
+ marker in the text and in the note itself. They take one
+ parameter, a \<number>. The default definitions simply use a
+ superscript in maths mode.
+\code
+ |\def\footnotetextmark#1{$^{#1}$}
+ |\def\footnotenotemark#1{$^{#1}$}
+\endcode
+%}}} footnotes
+%{{{ in-paragraph commands
+
+\section{Miscellaneous in-paragraph commands}
+
+
+\subsec{Writing the current date}
+
+\let\n=\relax
+\def\today{\n{\number\day} \monthname\month\ \n{\number\year}}
+\def\monthname#1{%
+ \ifcase#1\or
+ January\or February\or March\or April\or
+ May\or June\or July\or August\or
+ September\or October\or November\or December%
+ \fi
+}
+
+ We define a macro |\today| that prints today's date. I used to
+ have the option of the abbreviated date but decided this was an
+ unnecessary complication. The format `\today' is usual
+ in non-American countries, and is recommended by {\it Hart's
+ Rules}\footnote*{Horace Hart, {\it Hart's Rules for Compositors
+ and Readers at the University Press, Oxford}, 39th~ed.,
+ completely revised (Oxford University Press, 1990),
+ p.\thinspace19.} and Strunk \&
+ White.\footnote\dag{William Strunk jun., and E.~B. White, {\it
+ The Elements of Style}, 3rd~ed.\ (Macmillan, 1979),
+ p.\thinspace3. The American format is given first but followed
+ by the observation that the day--month--year format is `an
+ excellent way to write that date; the figures are separated by a
+ word, and are, for that reason, quickly grasped'.}
+\code
+ |\def\today{\n{\number\day} \monthname\month\ \n{\number\year}}
+\smallbreak
+ |\def\monthname#1{%
+ | \ifcase#1\or
+ | January\or February\or March\or April\or
+ | May\or June\or July\or August\or
+ | September\or October\or November\or December%
+ | \fi
+ |}
+\endcode
+ Redefine the |\monthname| macro if you want different names for
+ the months.
+
+
+\def\isodate{\n{\number\year}--\twodigits\month--\twodigits\day}
+\def\twodigits#1{%
+ \ifnum#1<10 0\fi \number#1%
+}
+
+ Here's a definition for the date in ISO~8601/BS~4795
+ format,\footnote\ddag{{\it The Oxford Writers' Dictionary}
+ (Oxford University Press, 1990), under `date'. I~have not read
+ the relevant standards.} which puts the year first, giving
+ `\isodate':
+\code
+ |\def\isodate{\n{\number\year}--\twodigits\month--\twodigits\day}
+\smallbreak
+ |\def\twodigits#1{%
+ | \ifnum#1<10 0\fi \number#1%
+ |}
+\endcode
+
+
+\subsec{Raising things}
+
+ The |\flushtop| macro prints its argument in a box raised so
+ that the its top is aligned with the top of a letter X in the
+ current font.
+\code
+ |\def\flushtop#1{%
+ | \leavevmode
+ | \begingroup
+ | \setbox0\hbox{#1}\setbox2\hbox{X}%
+ | \dimen0\ht2 \advance\dimen0-\ht0
+ | \raise\dimen0\box0
+ | \endgroup
+ |}
+\endcode
+ This allows us to define a fairly generic version of the \LaTeX\
+ logo:
+\code
+ |\def\La{L\negthinspace\flushtop{a}}
+ |\def\LaTeX{\La\TeX}
+\endcode
+ I have not given a definition for the \LaTeX~2e logo, since
+ I~think that `|\LaTeX~2e|' (or `|\LaTeX2e|' if you prefer) is
+ adequate, whereas Addison--Wesley think it should be `|\LaTeX|
+ |\kern0.05em| |2$| |_{\textstyle| |\varepsilon}| |$|' in regular
+ text and something involving bold maths in boldface. SImilarly,
+ I do not include macros for Bib\TeX, Sli\TeX, AMS-\TeX, and so
+ on; the |texlogos.sty| file from the Eplain package has
+ definitions for these.
+
+\def\superiorletter#1{\flushtop{\the\scriptfont\fam
+ \vphantom{t}\smash{#1}}}
+
+ Here's a variation which raises a scriptstyle letter so that
+ its {\it x}-height matches the cap-height of the body text,
+ thus making `M\superiorletter{\b c\kern0.1ex }Donald' and
+ `1\superiorletter{\b a}', `1\superiorletter{\b o}',
+ `1\superiorletter{er}', `2\superiorletter{\`eme}',
+ `1\superiorletter{st}', `2\superiorletter{nd}',
+ `3\superiorletter{rd}' and `659\superiorletter{th}' (which I
+ prefer to $659^{\rm th}$).
+\code
+ |\def\superiorletter#1{%
+ | \flushtop{\the\scriptfont\fam \vphantom{x}\smash{#1}}%
+ |}
+\smallbreak
+ |\def\Mc{M\flushtop{\the\scriptfont\fam \b{c}}}
+\endcode
+
+
+%}}} in-paragraph commands
+\endcodefile
+\enddocument
+\bye
+%}}} pdcfmt2
+
+%Local variables:
+%fill-prefix: " "
+%fold-folded-p: t
+%End: