% pdcsty -- documentation and source code for several style files -*-tex-*-
%%%@TeX-document-file {
%%% title = "Damian's random style files",
%%% filename = "$texmf/doc/plain/pdcmac/pdcsty.dtx",
%%% version = "$Revision: 1.2 $",
%%% package = "pdcmac 1.0",
%%% date = "$Date: 1995/03/30 16:12:17 $",
%%% 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 style files pdccmdoc.tex, ma55doc.tex,
%%% etc. and definitioon files pdcdoc1.tex and pdclft1.tex.
%%% Running plain TeX on this file produces both the
%%% definitions files 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 = "pdccode2.tex"
%%%}
%{{{ pdcsty.dtx
%{{{ preamble
\input pdccode2
\rcs$Id: pdcsty.dtx,v 1.2 1995/03/30 16:12:17 pdc Exp $\endrcs
\everycode{\tt \baselineskip=0.8\baselineskip \lineskiplimit=0pt }
\newcount\lineno
\everycodeline{\llap{$ \global\advance\lineno1
\scriptstyle\the\lineno $\enspace}}
\codefile{cmX}{pdccmlft.tex} \codefile{cmT}{pdccmdoc.tex}
\codefile{maX}{ma55lft.tex} \codefile{maT}{ma55doc.tex}
\codefile{psX}{pdcpslft.tex} \codefile{psT}{pdcpsdoc.tex}
\codefile{X}{pdclft.def} \codefile{T}{pdcdoc.def}
\def\maonly{\global\maXtrue \global\maTtrue
\global\cmXfalse \global\cmTfalse
\global\psXfalse \global\psTfalse
\global\Xfalse \global\Tfalse
\banner{Malvern}}
\def\cmonly{\global\maXfalse \global\maTfalse
\global\cmXtrue \global\cmTtrue
\global\psXfalse \global\psTfalse
\global\Xfalse \global\Tfalse
\banner{Computer Modern}}
\def\psonly{\global\maXfalse \global\maTfalse
\global\cmXfalse \global\cmTfalse
\global\psXtrue \global\psTtrue
\global\Xfalse \global\Tfalse
\banner{PostScript fonts}}
\def\styonly {\global\maXtrue \global\maTtrue
\global\cmXtrue \global\cmTtrue
\global\psXtrue \global\psTtrue
\global\Xfalse \global\Tfalse
\banner{Style files}}
\def\Tstyonly{\global\maXfalse \global\maTtrue
\global\cmXfalse \global\cmTtrue
\global\psXfalse \global\psTtrue
\global\Xfalse \global\Tfalse
\banner{Doc style files}}
\def\Xstyonly{\global\maXtrue \global\maTfalse
\global\cmXtrue \global\cmTfalse
\global\psXtrue \global\psTfalse
\global\Xfalse \global\Tfalse
\banner{Lft style files}}
\def\Tonly {\global\maXfalse \global\maTfalse
\global\cmXfalse \global\cmTfalse
\global\psXfalse \global\psTfalse
\global\Xfalse \global\Ttrue
\banner{Sectioning macros for Docs}}
\def\Xonly {\global\maXfalse \global\maTfalse
\global\cmXfalse \global\cmTfalse
\global\psXfalse \global\psTfalse
\global\Xtrue \global\Tfalse
\banner{Sectioning macros for Lfts}}
\def\banner#1{
\par
\line{%
\vrule height 1ex width 0.2ex
\leaders\vrule height 1ex depth -0.8ex \hskip2em
\enspace{\it \strut #1\/}\enspace
\leaders\vrule height 1ex depth -0.8ex \hfil
}
}
\def\onlyone#1{
\allfilesfalse \global\csname#1true\endcsname
\banner{{\tt\csname filename#1\endcsname}}
}
\def\onlytwo#1#2{
\allfilesfalse \global\csname#1true\endcsname
\global\csname#2true\endcsname
\banner{{\tt\csname filename#1\endcsname},
{\tt\csname filename#2\endcsname}}
}
\def\common{
\par
\allfilesfalse \global\Xtrue \global\Ttrue
\closebanner
}
\def\closebanner{
\line{%
\vrule height 1.8ex depth -0.5ex width 0.2ex
\leaders\vrule height 0.7ex depth -0.5ex \hfil
}
}
%}}} preamble
%{{{ introduction
\null\vskip2\baselineskip\hrule\bigskip
\leftline{Style files for the pdc- macros \fileversion\space(\filedate)}
\bigskip\hrule\bigskip
\headline{\hfil\global\headline={\hfil
\sevenbf Style files for the pdc- macros
\fileversion\space(\filedate)}}
\section{Introduction}
\subsec{About the style files}
This document describes a family of plain \TeX\ style files for
typesetting documents which are short enough not to need any
fancy indexing or cross-references, but long enough to want
numbered section headings and a table of contents.
A {\it style file} in this context means a definitions file that
specifies the formatting of for a document: layout, choice of
fonts, instructions for how to format lists, and so on. The
style files use the macros defined in other definition files to
supply most of the features they need. The document only needs
one `|\input|' command to set up most of the commands it needs.
\subsec{No cross-references}
Omitting cross-references is important because it means we can
avoid having documents that have to be run through \TeX\ more
than once (the first time to generate a raw index or
cross-reference file, the second to incorporate the references
into the document). This greatly simplifies the macros.
So that the table of contents may be generated automatically
without requiring a second pass, it is printed {\it last\/} in
the file. It follows that the table of contents belongs at the
end of the front matter of the document (on pages numbered in
roman numerals), immediately before page~1. It is easiest if
all the front matter is printed last. After the end of the
document proper, put the front matter enclosed in |\frontmatter|
\dots |\endfrontmatter|; this automatically switches to page
numbering in roman numerals, and puts the table of contents at
the end.
The file |pdccmdoc.tex| does documents using the Computer Modern
fonts. There is a variant called |pdccmlft.tex| intended for
`leaflets' that are even shorter than the `docs' produced with
|pdccmdoc.tex|. Leaflets have no front matter section, no table
of contents, and section headings are much less prominent---they
should only be a few pages long at most. The Malvern versions
are called |ma55doc.tex| and |ma55lft.tex|.
\subsec{About this document}
The file that generates this printed documentation, |pdcsty.dtx|
is a `documented \TeX' file. As well as briefly describing what
the macros are for and how they work, it includes a complete
listing of their definitions. The text of the definitions is
also written to files in the current directory, generating fresh
copies of the style files. This way this documentation and the
files it describes are guaranteed to match.
The lines of all definitions are numbered continuously, even
though only a subset of all the definition lines will go in each
file.
%}}} introduction
%{{{ starting up
\section{Starting up}
\subsec{File identification}
Nowadays, macro files start with some comments identifying the
file, for the benefit of people wondering what the file is for.
The macro file otherwise has no other comments, in the hope that
this will let \TeX\ read it in faster. (It should be possible
for the identification comments to go {\it after} an |\endinput|
at the close of the file, but the convention is to have them at
the start.)
The following segment is common to the style files and the
definiton files.
\code
\|\% \filename~\fileversion~\filedate~-- macros for short documents
\smallbreak
|%%%@TeX-definition-file {
\|\%\%\% filename~~~~~~~= "\filename",
\|\%\%\% 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, style file",
|%%% supported = "Maybe",
\cmonly |%%% abstract = "Top-level macro file for documents set in
|%%% Computer Modern fonts.
\maonly |%%% abstract = "Top-level macro file for documents set in
|%%% Malvern 55, 56 and 75 fonts.
\onlytwo{X}{T}
|%%% abstract = "Sectioning macros for style files.
\allfilestrue\closebanner
|%%% This macro 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.",
\onlytwo{X}{T}
|%%% dependencies = ""
\cmonly |%%% dependencies = "pdcfmt2.tex, pdcfsel.tex, pdchyex.tex,
|%%% pdcimth.tex, pdccmsub.tex, pdcmigr.tex,
\maonly |%%% dependencies = "maamac.tex, pdcfmt2.tex, pdcfsel.tex,
|%%% pdchyex.tex, pdcimth.tex, pdcmigr.tex,
\psonly |%%% dependencies = "pdcadobe.tex, pdcfmt2.tex, pdcfsel.tex,
|%%% pdchyex.tex, pdcimth.tex, pdcmigr.tex,
\Tstyonly
|%%% pdcoput5.tex, pdcdoc.def",
\Xstyonly
|%%% pdcoput5.tex, pdclft.def",
\allfilestrue\closebanner
|%%%}
|
\|\\message\{\fileversion~<\fileauthor~\filedate>\}
|
\endcode
This is followed immediately by a list of the macro files
included by this format:
\code
\styonly
|\input pdcimth
|\input pdcmigr
|\input pdcfmt2
|\input pdchyex
|\input pdcoput5
|\input pdcfsel
\cmonly
|\input pdccmsub
\maonly
|\input maamac
\psonly
|\input pdcadobe
\common
\endcode
%}}} starting up
%{{{ layout
\section{Layout}
\subsec{Paper sizes}
The section defining the paper size is at the very top of the
file to make it easy for someone adapting the macros to American
Letter size paper to find them.
Nevertheless, we set the top and bottom margins to be large
enough that even if it is printed on American paper, nothing
important will be cut off. This requires decent-sized margins
at the top and bottom of pages (since the end of the page that
will be lost depends on whether the printer driver has its real
origin at top-left or bottom-left). The edge of the printing
area is guessed at as being $7\,{\rm mm}$ from the edge of the
paper.
\code
|\topmg=297mm \advance\topmg-11in \advance\topmg7mm
|\botmg=\topmg
|\advance\topmg\ht\strutbox \advance\topmg\headlineskip
|\ifdim \topmg<20mm \topmg=20mm \fi
|\ifdim \botmg<27mm \botmg=27mm \fi
\smallbreak
|\setpaper{210mm}{297mm}
\endcode
The document has `tab-index' headings, that is, headings go in a
wide left margin to the left of the body text. The underlying
structure is a grid is 4~cells wide, with the text spanning
across the rightmost 3~cells. Definitions in the fonts section
below specify that the text will be set ragged-right.
\code
|\setnkgrid{4}{3}
|\colrule=0pt
|\leftmargin=\gridwd \advance\leftmargin\colsep
\endcode
The output routine's |\leftbox| is set at the start of each page
to make space for the left margin.
\code
|\everypage={\ifdim\leftmargin>0pt
| \setbox\leftbox=\hbox to \gridwd{}\fi}
\endcode
While we're here, we customize some of the environments supplied
by pdcFMT2:
\code
|\everyfootnote={\notefonts}
|\everylinenum={\smallfonts}
\maonly
|\def\footnotetextmark#1{{\rmsy#1}}
|\def\footnotenotemark#1{{\rmsy#1}}
\common
|\everylinenum={\smallfonts}
|\everytag={\bf}
\endcode
%}}} layout
%{{{ fonts
\section{Fonts}
This section describes the fonts available in the document.
We introduce extra nicknames |\bi| for bold italic (used for the
first mention of new techical terms), |\mf| for the METAFONT
logo, |\mfi| for the METAFONT logo in italic (Something of an
affectation) and |\ttb| for an `emphasized' typewriter (usually
it is best if this is slanted, not bold).
\code
\styonly
|\autoloadfonts
\endcode
The style files differ because of encoding schemes more than
because of the particular fonts. For example, a style for Times
Roman will work for Palatino too,if we change the names of the
fonts used. To do this, a macro |\basefontname| may be defined
before the style file is read in; if it isn't defined it is
given a default value.
%{{{ cmr
\subsec{Fonts for Computer Modern documents}
\cmonly
We use Computer Modern Sans Serif for the headings in CM
documents. I have not put much effort into making formulas
work in headings.
\code
|\def\STYheadingT{%
| \m{rm}{cmss}\m{mi}{cmmi}\m{sy}{cmsy}%
| \f{it}{cmssi}\f{tt}{cmtt}\f{mf}{logo}\f{mfi}{logosl}%
|}
\smallbreak
|\font\headingrm=cmss17 \font\headingit=cmssi17
|\fontset{subheading}\STYheadingT{10 scaled 1200}{14pt}
| {small}{tiny}
|\fontset{heading}\STYheadingT{10 scaled 1728}{20pt}
| {subheading}{small}
\endcode
We use Computer Modern for body text.
\code
|\def\STYbodyT{\m{rm}{cmr}\m{it}{cmti}%
| \m{bf}{cmbx}\@\f{bi}{cmbxti10}%
| \m{mi}{cmmi}\m{sy}{cmsy}%
| \@\f{mf}{logo10}\@\f{mfi}{logosl10}%
| \f{tt}{cmtt}\@\f{ttb}{cmsltt10}%
|}
\smallbreak
|\font\tinytt=cmtt8 at 7pt
|\font\bodysy=cmsy10 at 12pt
\endcode
%}}} cmr
%{{{ malvern
\subsec{Fonts for Malvern documents}
\maonly
Headings are in Malvern~75. The maths fonts are scaled for
expediency; I~do not make much effort to make formulas work in
headings.
\code
|\def\STYheadingT{%
| \m{rm}{ma75a}\@\m{mi}{cmmi10}\@\m{sy}{cmsy10}%
| \f{it}{ma76a}\@\f{tt}{cmtt10}\@\f{mf}{logo10}\@\f{mfi}{logosl10}%
|}
\smallbreak
|\fontset{subheading}\STYheadingT{12}{14pt}{subheading}{subheading}
|\fontset{heading}\STYheadingT{18}{20pt}{subheading}{subheading}
\endcode
We use Malvern~55 for body text. The supplementary font with
encoding~B is added, with font nickname |\rmsy|.
\code
|\newfam\rmsyfam
\smallbreak
|\def\STYbodyT{%
| \m{rm}{ma55a}\f{rmsy}{ma55b}\m{it}{ma56a}%
| \m{bf}{ma75a}\f{bi}{ma76a}%
| \m{mi}{cmmi}\m{sy}{cmsy}%
| \@\f{mf}{logo10}\@\f{mfi}{logosl10}%
| \f{tt}{cmtt}\f{tb}{cmsltt}%
|}
\endcode
% The main problem with defining the body fonts is that the
% $x$-height of Malvern is larger then Computer Modern. This makes
% in necessary to load the maths fonts at a larger size to match.
% (A better solution might be to make a parameter file for
% Computer Modern so that maths fonts may be generated with
% compatible proportions.)
%\code
% |\loadfont\bodytt{cmtt10 scaled \magstep2}
% |\loadfont\notett{cmtt10 scaled \magstep1}
% |\loadfont\smalltt{cmtt10 scaled \magstephalf}
% |\loadfont\bodytb{cmsltt10 scaled \magstep2}
% |\loadfont\smalltb{cmsltt10 scaled \magstep1}
% |\loadfont\notetb{cmsltt10 scaled \magstephalf}
%\endcode
There is no point using |\loadfont| on the maths symbol fonts,
since they have to be loaded anyway the first time |\bodyfonts|
is called.
\code
|\font\bodymi=cmmi10 scaled \magstep2
|\font\bodysy=cmsy10 scaled \magstep2
|\font\notemi=cmmi10 scaled \magstep1
|\font\notesy=cmsy10 scaled \magstep1
|\font\smallmi=cmmi10 scaled \magstephalf
|\font\smallsy=cmsy10 scaled \magstephalf
\endcode
%}}} malvern
%{{{ PostScript
\subsec{Fonts for Times documents}
\psonly
The big problem with PostScript fonts is what they are called;
I~shall be assuming that Fontname~$1.6$\footnote*{Karl Berry,
{\it File Names for \TeX\ Fonts} $1.6$ ({\tt
ftp:\penalty\exhyphenpenalty //ftp.umb.edu\slash pub\slash
tex\slash fontname/}).} applies: fonts with |afm2tfm|'s
variation on the \TeX\ Text encoding are called |ptmr| and fonts
with Adobe's StandardRoman encoding are called |ptmr0| (rather
than |rptmr|).
This macro attempts to make it possible to guess the standard
name for the italic variant of a given font.
|\KBcanonical{|\<tentative font name>|}| takes a font name which
is formed from an upright name optionally followed by `|i|'
representing an italic variation. It returns the corresponding
standard name. For example, |ptmri| is left unchanged, but
|phvri| is changed to |phvro| and |phvrrni| is changed to
|phvron|.
\code
|\def\KBcanonical#1{%
| \expcs\ifx{KB#1}\relax #1\else\csname KB#1\endcsname \fi
|}
\smallbreak
|\ifx\KBadobe\UNDEFINED \def\KBadobe#1{\KBcanonical{#10}} \fi
|\def\KBit#1{\KBcanonical{#1i}}
|\def\KBbi#1{\KBbf{#1i}}
|\def\KBbf#1{\expandafter\KBbfx#1.}
|\def\KBbfx#1#2#3#4#5.{\KBcanonical{#1#2#3b#5}}
\smallbreak
|\def\KBpagbr{pagdr} \def\KBpagbri{pagdro}
|\def\KBpbkbr{pbkdr} \def\KBpbkbri{pbkdri}
|\def\KBpagri{pagro} \def\KBpagbi{pagbo}
|\def\KBphvri{phvro} \def\KBphvbi{phvbo}
|\def\KBpcrri{pcrro} \def\KBpcrbi{pcrbo}
|\def\KBphvrrni{phvron} \def\KBphvbrni{phvbon}
|\def\KBphvrrn0{phvr0n} \def\KBphvbrn0{phvb0n}
|\def\KBphvrrni0{phvro0n} \def\KBphvbrni0{phvbo0n}
\endcode
Headings are in Helvetica. The maths fonts are scaled for
expediency; I~do not make much effort to make formulas work in
headings.
\code
|\ifx\headingfontname\UNDEFINED \def\headingfontname{phvr} \fi
|\ifx\headingttfontname\UNDEFINED \def\headingttfontname{pcrb} \fi
\smallbreak
|\def\STYheadingT{%
| \@\f{rm}{\headingfontname}\@\m{mi}{cmmi10}\@\m{sy}{cmsy10}%
| \@\f{asy}{psyr}%
| \@\f{it}{\KBit\headingfontname}%
| \@\f{tt}{\headingttfontname}\@\f{mf}{logo10}\@\f{mfi}{logosl10}%
|}
\smallbreak
|\loadfont\bodysy{cmsy10 at 12pt}
\smallbreak
|\fontset{subheading}\STYheadingT{12}{14pt}{subheading}{subheading}
|\fontset{heading}\STYheadingT{18}{20pt}{subheading}{subheading}
\endcode
We use Times Roman by default for body text, and Courier for
typewriter text. Adobe's Symbol font is included, with font
nickname |\asy|; a family called |\asyfam| has already been
created by |pdcadobe.tex|.
\code
|\ifx\bodyfontname\UNDEFINED \def\bodyfontname{ptmr} \fi
|\ifx\bodyttfontname\UNDEFINED \def\bodyttfontname{pcrr} \fi
\smallbreak
|\def\STYbodyT{%
| \@\m{rm}{\bodyfontname}\@\m{it}{\KBit\bodyfontname}%
| \@\m{bf}{\KBbf\bodyfontname}\@\f{bi}{\KBbi\bodyfontname}%
| \@\m{asy}{psyr}\m{mi}{cmmi}\m{sy}{cmsy}%
| \@\f{mf}{logo10}\@\f{mfi}{logosl10}%
| \@\f{tt}{\bodyttfontname}\@\f{tb}{\KBit\bodyttfontname}%
|}
\endcode
Finally the alphabet-switching commands defined for Malvern
fonts are given dummy definitions.
\code
|\let\sc=\relax \let\mc=\relax \let\csc=\relax
\endcode
%}}} malvern
\common
\subsec{Definitions common to all formats}
\code
\styonly
|\fontset{tiny}\STYbodyT{7}{9pt}{tiny}{tiny}
|\fontset{small}\STYbodyT{9}{11pt}{tiny}{tiny}
|\fontset{note}\STYbodyT{10}{12pt}{tiny}{tiny}
|\fontset{body}\STYbodyT{12}{14pt}{small}{tiny}
\endcode
The text is set left-justified (ragged-right). To make this
work, the fontdimens that control word spacing are set to force
interword spaces to all be the same width.
\code
|\def\everyloadfont#1#2{\fontdimen3#1=0pt \fontdimen4#1=0pt}
|\rightskip=0pt plus 2em \tolerance=1000
\smallbreak
|\bodyfonts
|{\tt \hyphenchar\font=-1 }
\common
\endcode
%}}} fonts
%{{{ minimal section headings
\section{Simple sectioning}
\onlyone{X}
A `leaflet' is divided into short sections, which may contain
subsections (but usually will not). There may well be more than
one section on a page.
The section number is held in two count registers, and printed
(enclosed in |\n{|\dots|}|) with the macro |\thesecno|:
\code
|\newcount\secno \newcount\subsecno
\smallbreak
|\def\thesecno{%
| \n{%
| \number\secno
| \ifnum\subsecno>0
| .\number\subsecno
| \fi
| }%
|}
\endcode
The section and subsection commands are implemented
straightforwardly with macros from |pdcfmt2.tex|, since there is
no need for marks or fiddling with table-of-contents files.
\code
|\def\section{
| \global\advance\secno1 \global\subsecno0
| \doheading\medskipamount{\subheadingfonts\thesecno\enspace}{}
|}
\smallbreak
|\def\subsec{
| \global\advance\subsecno1
| \doheading\smallskipamount{\bodyfonts\thesecno\enspace}{}
|}
\endcode
The page header includes only the title of the file, which the
user sets with the command |\majorheadline{|\<text>|}|
\code
|\newtoks\majorheadline
|\expandafter\majorheadline
| \expandafter{\expandafter\uppercase\expandafter{\jobname}}
\endcode
All those |\expandafter|s are to get the initial value in upper
case.
The flag |noheadline| signals that the headline is to be omitted
on this page (e.g., the title page). The |twosided| flag is set
for two-sided binding.
\code
|\newif\ifnoheadline \newif\iftwosided
\smallbreak
|\headline{%
| \ifnoheadline
| \hfil
| \else\iftwosided
| \ifodd\pageno
| \hfil \the\majorheadline \quad{\bf\folio}%
| \else
| {\bf\folio}\quad \the\majorheadline\hfil
| \fi
| \else
| \hfil \the\majorheadline \quad{\bf\folio}%
| \fi\fi
|}
\smallbreak
|\footline{%
| \ifnoheadline
| \global\noheadlinefalse
| \hfil{\bf\folio}\hfil
| \else
| \hfil
| \fi
|}
\endcode
%}}} minimal section headings
%{{{ sectioning
\section{Sectioning in PDCCMDOC documents}
\onlyone{T}
Now a document is divided into {\it sections}, which are further
divided into so-called {\it subsecs} and {\it subsubsecs}.
(Division into subsubsecs should be done sparingly.)
The sections may be grouped into {\it parts}---or, to look at it
another way, parts are a larger division of the document than
sections, but sections are not numbered within part numbers.
Each |\part| command should be almost immediately followed by
|\section|.
\subsec{Macros for section numbers}
The part and section numbers are kept in \TeX\ number registers,
with corresponding `|\the|-' macros to print the value
formatted.
\code
|\newcount\partno
\smallbreak
|\def\thepartno{%
| \ifcase\partno O\or I\or II\or III\or IV\or V\else
| \expandafter\uppercase\expandafter{\romannumeral\partno}%
| \fi
|}
\endcode
Formatted section and subsec numbers are generated by one macro
|\thesecno|. It automatically omits (sub)subsec numbers if they
are zero. The whole number is enclosed in |\n{|\dots|}| so that
the formatting of numbers may be customized.
\code
|\newcount\secno \newcount\subsecno \newcount\subsubsecno
\smallbreak
|\def\thesecno{%
| \n{%
| \number\secno
| \ifnum\subsecno>0
| .\number\subsecno
| \ifnum\subsubsecno>0
| .\number\subsubsecno
| \fi
| \fi
| }%
|}
\endcode
\subsec{Parts}
The |\part| macro takes one argument, the title. It sets a
token register |\majorheadline| which is printed on the left
page of two-sided documents.
The |\majorheadline{|\<text>|}| command may be used immediately
after a |\part| command if the part title is not suitable to go
in the headline. This should also be used at the start of the
document to the title of the document, if division into parts is
not used.
\code
|\newtoks\majorheadline
|\expandafter\majorheadline
| \expandafter{\expandafter\uppercase\expandafter{\jobname}}
\smallbreak
|\def\part#1{%
| \global\advance\partno1
| \newpageheading{2\baselineskip}{\headingfonts}
| {}{\thepartno.\quad#1}
| \TOCwrite\TOCentrypart{\thepartno}{#1}
|}
\endcode
\subsec{Section headings}
Section headings will start on a new page if the current page is
almost finished. The section heading is set across the full
width of the page, including the margin usually used for
tab-indexed headings.
To force the next section to start a new page, do
|\sectionpenalty-10000| immediately before it.
\code
|\newcount\sectionpenalty
\smallbreak
|\def\sectionheading#1{
| \par
| \vskip 0pt plus 0.3\vsize
| \penalty\sectionpenalty \sectionpenalty-200
| \vskip 1\bigskipamount plus -0.3\vsize
| \begingroup \advance\leftskip-\leftmargin
| \parskip=0pt \parindent=0pt
| \hyphenpenalty=10000 \exhyphenpenalty=500
| \interlinepenalty=100
| \headingfonts \nointerlineskip
| \hbox{\hskip-\leftmargin
| \vrule height 2pt depth 0pt width \leftmargin
| \vrule height 2pt depth 0pt width \hsize}
% | \nobreak\medskip
| #1\par
| \nobreak\smallskip
| \endgroup
| \global\noindenttrue
|}
\endcode
As well as generating a heading, the section macro generates
marks used for the page headings and a TOC entry. The marks are
of the form in a way similar to that discussed in Chapter~23 of
the {\it\TeX book}. More precisely, a mark is placed on either
side of the section heading of the form
$$\hbox{\tt\arg{\<rhs>}\arg{\<lhs>}}$$ where \<rhs> is the section
number that belongs on the right-hand page, reflecting the
situation at the bottom of the page, whereas \<lhs> is what
belongs on following left-hand pages.
\code
|\newtoks\sectiontoks
|\newif\ifsecno \secnotrue
\smallbreak
|\def\section#1{
| \ifsecno
| \global\advance\secno1 \global\subsecno0 \global\subsubsecno0
| \fi
| \toks0={#1}
| \mark{{\the\sectiontoks}{\ifsecno\S\thesecno\space\fi\the\toks0 }}
| \edef\tmp{\ifsecno\noexpand\S\the\secno\space\fi}
| \global\sectiontoks\expandafter{\tmp#1}
| \sectionheading{\ifsecno\thesecno\quad\fi #1}
| \mark{{\the\sectiontoks}{\the\sectiontoks}}
| \TOCwrite\TOCentrysection{\ifsecno\thesecno\fi}{#1}
|}
\endcode
Subsecs and subsubsecs use the |\doheading| macro defined in
|pdcfmt.tex|. They do not appear in page headings, but may
appear in the TOC.
\code
|\def\subsec#1{%
| \ifsecno \global\advance\subsecno1 \global\subsubsecno0 \fi
| \doheading\medskipamount{\subheadingfonts}{}
| {\ifsecno\thesecno\quad\fi#1}
| \TOCwrite\TOCentrysubsec{\ifsecno\thesecno\fi}{#1}
|}
\smallbreak
|\def\subsubsec#1{%
| \ifsecno \global\advance\subsubsecno+1 \fi
| \doheading\smallskipamount{\rm}{}{\ifsecno\thesecno\quad\fi#1}
| \TOCwrite\TOCentrysubsubsec{\ifsecno\thesecno\fi}{#1}
|}
\endcode
The headline and footline are controlled by two flags. The
command |\noheadlinetrue| suppresses the headline for this page
(e.g., a title page). The |twosided| flag says whether the
document should be formatted for two-sided printing.
\code
|\newif\ifnoheadline
|\newif\iftwosided
\smallbreak
|\footline={%
| \ifnoheadline
| \global\noheadlinefalse
| \hfil\bodyfonts\n\folio\hfil
| \else
| \hfil
| \fi
|}
\endcode
The headline varies according to whether it is a one-sided page,
a left-hand page or a right-hand page. On a one-sided page, it
has the major headline (part or document title) at the left, and
the section title of the {\it first} section on the page on the
right with the folio. On a left-hand page, there is the folio
and the major headline, and on a right-hand page there is the
section title for the {\it last} section on the page, and the
folio.
\code
|\headline={%
| \ifnoheadline
| \hfil
| \else
| \bodyfonts
| \iftwosided
| \ifodd\pageno
| \hfil
| \expandafter\firstoftwo\botmark\quad
| {\bf\n\folio}%
| \else
| {\bf\n\folio}\quad
| \the\majorheadline
| \hfil
| \fi
| \else
| \the\majorheadline
| \hfil
| \expandafter\secondoftwo\topmark\quad
| {\bf\n\folio}%
| \fi
| \fi
|}
\smallbreak
|\def\firstoftwo#1#2{#1}
|\def\secondoftwo#1{}
\endcode
%}}} sectioning
%{{{ table of contents
\section{Table of contents intrinsics}
This section defines the macros used to generate a table of
contents. The entries are written to a file \<jobname>|.toc| in
the current directory. At the end of the manuscript this files
is closed and then read to generate the table of contents.
Macros special to the TOC-generating section have names starting
with `|\TOC|-'.
\code
|\newwrite\TOCfile
|\openout\TOCfile=\jobname.toc
\endcode
Entries in the TOC file are of the form
$$\hbox{\tt\cs{TOCentry}\<foo>\arg{\<secno>}\arg{\<title>}\arg{\<folio>}}$$
where |\TOCentry|\<foo> is a csname, \<secno> is some
automatically-generated section number like `|1.2|', \<title> is
the section title as supplied by the user, and \<folio> is the
folio for this page, in arabic or lower-case roman numeral form.
They are generated with calls to |\TOCwrite| like this
$$\hbox{\tt\cs{TOCwrite}\cs{TOCentry}\<foo>\arg{\<secno>}\arg{\<title>}}$$
The \<secno> is evaluated when |\TOCwrite| is called, whereas
the \<title> is carefully written without being expanded so that
its expansion happens when the TOC file is read in. The
\<folio> is automatically appended when it is written.
\code
|\def\TOCwrite#1#2#3{%
| \begingroup\def\n{\string\n}
| \def\tmp{#3}%
| \edef\tmp{\string#1{#2}{\expandafter\TOCtrim\meaning\tmp}}
| \write\TOCfile\expandafter{\tmp{\folio}}\endgroup
|}
\smallbreak
|\def\TOCtrim#1:->{}
\endcode
Now we define all the `|\TOCentry|-' macros.
\code
|\def\TOCentrypart#1#2#3{
| \smallskip
| \dimen0=\hsize \advance\dimen0\leftmargin
| \moveleft\leftmargin\hbox to\dimen0{\strut\bf #1. #2\hfil}
| \smallskip
|}
\smallbreak
|\def\TOCentrysection#1#2#3{
| \smallskip\noindent\llap{#1\kern1pc}%
| {\bf \ignorespaces #2\quad\rm \n{#3}}\par
|}
\smallbreak
|\def\TOCentrysubsec#1#2#3{
| \ifvmode \noindent \else \quad \fi
| {#1}~{\ignorespaces #2}
|}
\smallbreak
|\def\TOCentrysubsubsec#1#2#3{}
\endcode
%}}} table of contents
%{{{ front matter
\section{Printing the front matter}
The front matter of the document---the title page, preface,
forword, etc.---must be printed {\it last}, with the table of
contents at the end of the front matter; this is so that the
table of contents may be accumulated during the \TeX ing of the
file.\footnote*{It has a benefit for people reading the document
with a browser: page~1 of the document is the first page of the
DVI file, which makes selecting a given page easy, and the table
of contents is at the very end, so the browsers `go to last
page' command can be used to find the table of contents
quickly.}
The front matter starts with the command |\frontmatter| and may
contain |\section| commands. Such sections will be unnumbered
and will not appear in the table of contents.
For a short document, a separate title page is probably
excessive, and an abstract may be preferable to a preface. In
this case the first page after |\frontmatter| could have the
title of the document (with author etc.)\ followed by an
abstract, any copyright information (or other small print), and
the contents (generated by |\endfrontmatter|). In other words,
something like this:
$$\halign{\indent#\hfil\cr
|\frontmatter|\cr
\quad\it commands to print the title, etc.\cr
\quad|\abstract|\cr
\qquad\it the text of the abstract\cr
\quad|\endabstract|\cr
\quad\it copyright information, etc.\cr
|\endfrontmatter|\cr
}$$
For a longer document, there will be a separate title page and
perhaps a preface.
$$\halign{\indent#\hfil\cr
|\frontmatter|\cr
\quad|\titlepage|\cr
\qquad\it commands to print the title, etc.\cr
\quad|\splittitlepage|\cr
\qquad\it print copyright information, etc.\cr
\quad|\endtitlepage|\cr
\quad|\section{Preface}|\cr
\qquad\it text of preface, etc.\cr
|\endfrontmatter|\cr
}$$
The macro |\splittitlepage| marks the division between the title
page (title recto, page~i) and the back of the title page (title
verso, page~ii), which is where copyright information goes. On
a one-sided document, the copyright information belongs on the
title recto, because the title verso will be blank, so
|\splittitle| instead does |\vfill|.
Setting |\pageno| nagative makes it print in roman numerals.
Calling |\secnofalse| suppresses section numbering. The first
page has no headline.
\code
|\def\frontmatter{
| \write\TOCfile{\string\endinput}
| \write\TOCfile{\folio}
| \closeout\TOCfile
| \vfill\supereject
| \ifvoid\partialpage\else \null\vfill\eject \fi
| \beginthe{frontmatter}
| \pageno=-1 \secnofalse \noheadlinetrue
| \def\TOCwrite##1##2##3{}
|}
\endcode
The front matter is finshed off with the contents list,
generated by |\endfrontmatter|. This reads the TOC file, which
was closed at the end of the last page of the body of the
document.
\code
|\def\endfrontmatter{
| \section{Contents}
| \input\jobname.toc
| \vfill\supereject
| \endthe{frontmatter}
|}
\endcode
Here's macros for generating the titlepage---it shoul;d enclose
commands to generate the title, author and publisher information
for the document. If it is used, it goes immediately after
|\frontmatter|, so that the title page is page~i.
\code
|\def\titlepage{
| \vfill\eject
| \beginthe{titlepage}
| \noheadlinetrue
| \def\splittitlepage{
| \iftwosided \vfill\eject\null\vfill \else \vfill \fi
| }
|}
\smallbreak
|\def\endtitlepage{
| \eject
| \endthe{titlepage}
|}
\endcode
This |abstract| environment doesn't do anything fancy.
\code
|\def\abstract{
| \smallskip
| \beginthe{abstract}
| \setbox\parbox\hbox to \gridwd{\subheadingfonts Abstract\hfil}
| \noindenttrue \bodyfonts
|}
\smallbreak
|\def\endabstract{
| \smallskip
| \endthe{abstract}
|}
\endcode
%}}} front matter
This concludes the code that is included only in documents with TOC.
\common
%{{{ abbreviations
\section{abbrevs}
The definitions of |\pt| and |\mm| work only in maths mode.
\code
|\def\pt{\,{\rm pt}}
|\def\mm{\,{\rm mm}}
\smallbreak
|\def\MF{{\ifdim\fontdimen1\font>0pt \mfi \else \mf \fi META}\-%
| {\ifdim\fontdimen1\font>0pt \mfi \else \mf \fi FONT}}
|\def\MSDOS{\leavevmode\hbox{MS-DOS}}
\endcode
\subsec{Program names with small caps}
Some program names use small capitals in their names. For
normal fonts there is no point trying to duplicate this, since
small capitals aren't common to all fonts. But small capitals
come `for free' with Malvern, so we might as well use them. The
following definitions apply to Malvern~A fonts.
\code
\maonly
|\def\PS{\csc{PostScript}}
|\def\La{L\negthinspace\flushtop{\char"C1 }}
\cmonly
|\def\PS{PostScript}
\common
\endcode
\font\sf=cmss10
Here's a redefinition of |\TeX|. This adds a spacefactor 1000
to the end (so that \TeX\ doesn't apply its usual heuristic that
a full stop following a capoital {\it X} isn't a sentence end).
It also loosens up the logo, producing `\TeX' rather than the
usual `T\negthinspace\lower0.5ex\hbox{E}\kern-0.125emX'. This
design is more forgiving of changes in font (for example, in
sanserif it makes `{\sf\TeX}' instead of `{\sf
T\negthinspace\lower0.5ex\hbox{E}\kern-0.125emX}').
\code
|\def\TeX{T\kern-0.1em\lower0.5ex\hbox{E}X\spacefactor1000 }
\endcode
The macro |\dfn{...}| formats a defining instance of a word or
phrase (usually used the first time a new technical term is
introduced). When generating an index with a command |\index|,
this also adds the phrase to the index.
\code
|\begingroup\catcode`\|=12 \toks0={\endgroup
| \def\dfn#1{\ifx\index\UNDEFINED\else\index{#1|INDdfn}\fi{\bi #1}}
|} \the\toks0
\endcode
Here's a hack for using email-style emphasis using
`asterisking'. Text enclosed in matching asterisks is
emphasized.
\code
|\declareactivechar\* \def*#1*{{\it#1\/}}
\endcode
\begingroup\defverbatim\~
When documenting computer progams it is useful to be able to
present dialogues between the user and the computer, with the
user's commands distinguished by a slightly different font.
Here we define ~\|~\<text>~|~ so that it behaves like
~|~\<text>~|~ except that |\ttb| is used instead of |\tt|. In
maths mode it is still equivalent to |\Vert|.
\code
|\def\|{%
| \relax\ifmmode
| \Vert
| \else
| \begingroup
| \ttb \setupverbatim
| \catcode`\|=13 \let|\endgroup
| \fi
|}
\endcode
\endgroup
%}}} abbreviations
%{{{ postamble
\section{Finally}
The definitions common to all style files are read last, so that
they can take account of changes to |\baselineskip|.
\code
\Tstyonly
|\input pdcdoc.def
\Xstyonly
|\input pdclft.def
\common
\endcode
And, at last, a file {\tt\<filename>.cfg} is read, if it exists.
\code
|\def\inputifexists#1{%
| \openin15=#1
| \ifeof15 \else \input #1 \fi
| \closein15
|}
\styonly
\|\\inputifexists\{\filenamesanssuffix.cfg\}
\common
\endcode
\endcodefile{cmX} \endcodefile{cmT} \endcodefile{maX} \endcodefile{maT}
\endcodefile{psX} \endcodefile{psT} \endcodefile{X} \endcodefile{T}
\bye
%}}} postamble
%}}} pdccmcode.dtx
%Local variables:
%fold-folded-p: t
%fill-prefix: " "
%End: