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