diff options
Diffstat (limited to 'Master/texmf-dist/source/plain/pdcmac/pdcsty.dtx')
-rw-r--r-- | Master/texmf-dist/source/plain/pdcmac/pdcsty.dtx | 1153 |
1 files changed, 1153 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/plain/pdcmac/pdcsty.dtx b/Master/texmf-dist/source/plain/pdcmac/pdcsty.dtx new file mode 100644 index 00000000000..58c5ac76808 --- /dev/null +++ b/Master/texmf-dist/source/plain/pdcmac/pdcsty.dtx @@ -0,0 +1,1153 @@ +% 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: |