summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/plain/pdcmac/pdccode.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/plain/pdcmac/pdccode.dtx')
-rw-r--r--Master/texmf-dist/source/plain/pdcmac/pdccode.dtx881
1 files changed, 0 insertions, 881 deletions
diff --git a/Master/texmf-dist/source/plain/pdcmac/pdccode.dtx b/Master/texmf-dist/source/plain/pdcmac/pdccode.dtx
deleted file mode 100644
index 2261d583f4e..00000000000
--- a/Master/texmf-dist/source/plain/pdcmac/pdccode.dtx
+++ /dev/null
@@ -1,881 +0,0 @@
-% pdccode.dtx -- documentation & source for pdccode.tex -*-tex-*-
-
-%%%@TeX-document-file {
-%%% title = "PDCCODE -- Documented TeX Macros",
-%%% filename = "$texmf/doc/plain/pdcmac/pdccode.dtx",
-%%% version = "$Revision: 1.6 $",
-%%% package = "pdcmac 1.0",
-%%% date = "$Date: 1995/03/30 16:08:32 $",
-%%% 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 pdccode.tex.
-%%% Running plain TeX on this file produces both a copy of 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"
-%%%}
-
-%{{{ pdccode
-%{{{ preamble
-
-\relax
-\input pdccode
-\document
-\rcs$Id: pdccode.dtx,v 1.6 1995/03/30 16:08:32 pdc Exp $\endrcs
-
-\codefile{tmp.tex}
-
-\defverbatim\"
-
-%}}} preamble
-%{{{ introduction
-
-\author{P. Damian Cugley}
-\title{PDCCODE---Documented \TeX\ Macros}
-\section{Introduction}
-
- PDCCODE is a simpler and less featureful system than the
- \LaTeX~2e Docstrip package, but uses the same file suffix
- `|dtx|'. Lines between |\code| and |\endcode| markers are
- written to a file (set with the |\codefile| command), as well as
- being printed `verbatim' in document. Thus one \TeX\ pass
- generates both the macro file(s) and a |dvi| file.
-
- This document---generated from |pdccode.dtx|---is a |dtx| file
- for PDCCODE itself, the file of macros used by my |dtx| files.
- It cannot be used to generate |pdccode.tex| directly (\TeX\
- might choke halfway through overwriting |pdccode.tex| with a new
- version, leaving no |pdccode.tex| to generate |pdccode.tex|
- with). Instead it produces its copy as `|tmp.tex|', and
- `|tmp.tex|' can be compared to the supplied |pdccode.tex|.
-
-\subsec{How to read this document}
-
- The |dtx| files are programs (in \TeX's macro language) that
- generate new programs (the macro files that will be used in
- documents). The macros described in {\it this} file are used
- when generating macro files. So, for example, the |\rcs| and
- |\fileversion| macros used to extract identification information
- from the |dtx| file are not defined in any of the generated
- macro files.
-
-\subsec{Background}
-
- For some time I~have been using a collection of macro files to
- typeset various types of document with \TeX. After using them
- in Malvern\footnote*{Malvern is a sanserif font family
- implemented in METAFONT. The current version is release $1.2$.}
- releases I have discovered that they had been merged with the
- Unix\TeX\ macros directory. Originally I~had never intended
- that these files be used by anyone but me---they were full of
- hacks and messy code and definitions I~don't use anymore. Since
- then I~thought of tidying up the macros enough that I'm not
- embarassed by them, but the task of doing this {\it and}
- documenting their use was daunting.
-
- After installing \LaTeX~2e on my new computer, I~decided to have
- a go at adapting the idea of `documented \TeX\ macros' files to
- plain \TeX. This way I~could clean up the macros and document
- them in a systematic fashion.
-
- The \LaTeX\ Docstrip/Doc-option approach evolved through several
- different models and so is a complex format. Docstrip (a
- program written in \TeX's macro language) was used to strip
- comments from |doc| files making |sty| files, and the \LaTeX\
- Doc-option separately extracted \LaTeX\ code from comments in
- |doc| files to make printed documentation. Both Doc and
- Docstrip required the user to type in file names whenever they
- ran---which made them useless for batch processing. So separate
- driver files (with suffixes |drv| and |ins|) were added to
- distributions. Finally, the |doc| files, which used to be
- usable as |sty| files (just a little slower because of the
- comments) were have been changed to be documents instead (making
- |drv| files redundant, once the |ltxdoc.cfg| configuration file
- was added to the conventions) and given a new suffix |dtx|.
-
- The system I~use---called PDCCODE---is simpler and faster, but
- omits indexes, special change-log commands, and all the features
- that come with \LaTeX\ formatting. It doesn't have Docstrip's
- {\it options}\/ feature, which allows several largely-similar
- files to be generated from the same source.\footnote\dag{I do
- have an experimental version |pdccode2.tex| which does this but
- I~am not particularly happy with it yet.} It doesn't print
- statistics at the end, or do checksums, or even print comforting
- lines of asterisks and percent signs in the log file.
-
- My |dtx| files use a single macro file |pdccode.tex| which
- defines a `code mode' where lines are written to the macro file
- as well as appearing in the printed documentation. One pass
- generates both the macro file and the documentation in |dvi|
- form. The |pdccode.tex| file also includes enough layout
- commands to typeset the comments.
-%}}}
-%{{{ using pdccode
-\section{Summary of using PDCCODE}
-
- These commands are explained in more detail below.
-
-\subsec{A skeleton code file}
-
- A code file using |pdccode.tex| will look something like this:
-$$\it
-\halign{\indent#\hfil\cr
- "%" name "--" one line description\cr
-\noalign{\smallskip}
- "%%%@TeX-document-file {"\cr
- header comments for the document\cr
- "%%%}"\cr
-\noalign{\smallskip}
- "\relax"\cr
- "\input pdccode"\cr
- "\document"\cr
- "\rcs$" RCS identification string "$\endrcs"\cr
- "\codefile{" file name "}"\cr
- "\author{" author name "}"\cr
- "\title{" title for the document "}"\cr
-\noalign{\smallbreak}
- "\section{Introduction}"\cr
- introduction\cr
-\noalign{\smallbreak}
- "\section{File identification}"\cr
- "\code"\cr
- " \|\% " file name "\fileversion~\filedate~--" one line desc\cr
- " |"\cr
- " |%%%@TeX-definition-file {"\cr
- " " header comments for macro file\cr
- " |%%%}"\cr
- " |"\cr
- " \|\\message\{\fileversion~<\fileauthor~\filedate>\}"\cr
- " |"\cr
- "\endcode"\cr
-\noalign{\smallbreak}%
- definitions and commentary\cr
-\noalign{\smallbreak}%
- "\endcodefile"\cr
- "\enddocument"\cr
- "\bye"\cr
-}$$
-
-\subsec{Commands in code sections}
-
- Code sections start with |\code| and end with |\endcode|. Before
- the first |\code| you must do |\codefile{|\<file name>|}| to
- specify the file.
-
- Vertical mode material may be used between lines (e.g.,
- |\smallbreaks|). Unexpanded code lines are introduced with "|",
- expanded lines with "\|". In expanded lines, use "\{", "\}",
- "\\", "\%", "\~" for those characters, "~" for a single space.
-
-\subsec{Commands in commentary}
-
- Most of the commentary will be typeset using the conventions of
- plain \TeX.
-
- |\author{|\<text>|}| (must precede |\title|)
-
- |\title{|\<heading>|}|
-
- |\section{|\<heading>|}|
-
- |\subsec{|\<heading>|}|
-
- |\noindenttrue|
-
- |\footnote|
-
- |\defverbatim|\<one-character control sequence>
-
- |$|\<number>|\mm$| |$|\<number>|\em$| |$|\<number>|\pt$|
- |$|\<number>|\inch$|
-
- |\<|\<name>|>| |\cs{|\<name>|}|
- |\arg{|\<argument name>|}|
-
- |\TeX| |\LaTeX| |\LaTeX~2e|
-
- |\notepar| \<paragraph> |\endnotepar|
-
-
-%}}} using pdccode
-%{{{ file identification
-\section{File identification}
-
- Nowadays, macro files start with some comments identifying the
- file.
-\code \catcode`\"=12
- \|\% pdccode.tex \fileversion~\filedate~-- self-documenting TeX macros
- |
- |%%%@TeX-definition-file {
- |%%% filename = "$texmf/tex/plain/pdcmac/pdccode.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 = "Macros for documented TeX macros (DTX files).
- |%%% 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
-%}}} file id
-
-\bigskip\noindent
- We start by making a nickname for a scratch register. This is
- |\toks@| in plain \TeX; this definition gives it a name I~can
- use without catcode hackery.
-\code
- |\toksdef\toksa=0
-\endcode
-
-%{{{ rcs support
-
-\section{RCS Support}
-
- RCS (Revision Control System) is a free source code control
- system which is available from the Free Software Foundation.
- It inserts keyword-value pairs enclosed in dollar signs into the
- source code. This command extracts the file's version, date,
- author and locker (if there is one). It is used like this:
-$$\centerline{\vbox{\tt\def~{\char32 \ignorespaces}
- \halign{#\hfil\cr
- \cs{rcs}\$Id:~\<name>,v~\<version>~\<date>~\<ignored>\quad\cr
- \hfill~\<author>~\<ignored>~{\rm[}\<locker>~{\rm]}\$\cs{endrcs}\cr
-}}} $$
- The \<locker> field is non-empty iff the file is `locked'
- (meaning it has been edited and the changes are not checked in
- yet). The |\filename| macro is defined, even though it will
- almost certainly be identical to |\jobname|.
-\code
- |\def\rcs#1: #2,v #3 #4 #5 #6 #7 #8$#9\endrcs{
- | \def\filename{#2}
- | \def\fileversion{#3}
- | \def\filedate{#4}
- | \def\fileauthor{#6}
- | \def\filelocker{#8}
- |}
-\endcode
-
-%}}} rcs support
-%{{{ verbatim text
-\section{Verbatim text}
-
- Verbatim text is text that is printed identically to the
- characters in the manuscript file. In the code sections, a
- vertical bar is used to make lines for the code file. In the
- documentation, the vertical bar is used as a self-matching
- verbatim mode character.
-
- These definitions should be the same as the corresponding code
- in |pdcfmt2.dtx|.
-
-\subsec{Lists of active characters}
-
- 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\ }
-\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 `|^|' produce slightly lowered glyphs.
-\code
- |\newtoks\everyverbatim
-\smallbreak
- |\bgroup \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
- | \the\everyverbatim
- | }
- |}\the\toksa
-\endcode
-
- Here are the definitions for the munged glyphs. These are only
- necessary in CM-Typewriter-like fonts; using something
- like Courier, these definitions could probably be omitted.
-
- 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=13|, producing `{\tt\char13 }'.
-\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`\^ }}
-\endcode
- This makes the difference between |`'^~| and
- {\tt`'\char`\^\char`\~}.\footnote*{It turns out that on some
- \TeX\ systems, the CMTT font has been hacked to have an
- ASCII-style reverse-apostrohe-cum-grave-accent as character~96
- and a matching apostrophe-cum-acute-accent as charcter~39,
- thereby correcting the defects that my definitions of |\ttlq|
- and |\ttrq| address. But such modified fonts are
- nonstandard---they should {\it not} be called CMTT---and should
- be replaced.}
-
-\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\|
-\smallbreak
- |\hyphenchar\tentt=-1
-\endcode
- Both |\defverbatim| and |\defineactivechar| have local scope.
-
-%}}} verbatim text
-%{{{ code sections
-%{{{ intro
-\section{Code sections}
-
- The markers |\code| \dots |\endcode| mark code to be written to
- the definition file. Each line starts with either "|" or "\|"
- and finishes with the end of the line in the manuscript file.
-
- Lines that start with "|" are written out as-is; no macro
- expansion is allowed. This is how the vast majority of lines
- are done.
-
- Lines starting "\|" are expanded. This is so that things like
- the current version ID (extracted from the RCS identification
- line or set with |\def|) may be included in the code file.
- Within such an expanded line, the following macros are defined:
- $$\halign{\indent#\hfil&&\quad#\hfil\cr
- |\%|& |%|& per cent sign&
- |\{|& |{|& left brace&
- |\}|& |}|& right brace\cr
- |\\|& |\|& backslash&
- |~|& \tt\char32 & space&
- |\~|& |~|& tilde\cr
- }
- $$
- (This list is probably incomplete.)
-%}}} intro
-%{{{ code file name
-
-\subsec{Setting the codefile name}
-
- Before the first code section, the |\codefile{|\<file name>|}|
- command specifies the code file. The last code section should
- be followed by |\endcodefile|. Only one code file may be open
- at a time.
-\code
- |\newwrite\CODEwrite
-\smallbreak
- |\def\codefile#1{
- | \ifeof\CODEwrite\else \endcodefile \fi
- | \def\thecodefile{#1} \openout\CODEwrite=#1
- |}
-\smallbreak
- |\def\endcodefile{
- | \message{Code written on \thecodefile.}
- | \closeout\CODEwrite
- |}
-\endcode
-%}}} code file name
-%{{{ code sections
-
-\subsec{Code sections}
-
- Switching to `code mode' is easy, because most of the work is
- really done by the "|" and "\|" commands.
-
-\code
- |\def\code{
- | \smallskip
- | \begingroup
- | \let|\CODEline \let\|\CODElinex
- | \let\{=\CODElb \let\}=\CODErb \let\\=\CODEbslash
- | \def~{ } \let\~\CODEtilde
- | \the\everycode
- | \obeylines
- |}
-\smallbreak
- |\def\endcode{
- | \smallbreak
- | \endgroup
- |}
-\endcode
-%}}} code sections
-%{{{ code lines
-\subsec{Code lines}
-
- This is the definition for unexpanded code lines.
-\code
- |\def\CODEline{%
- | \begingroup % matched by \CODElinei
- | \setupverbatim \catcode`\|\other
- | \CODElinei
- |}
-\endcode
-
- In |\CODElinei|, We must redefine the characters (such as |`|)
- that are active within verbatim text to expand to their
- catcode-12 equivalents when they are written to the code file
- currectly.
-
- Since one of these is |^|, we temporarily give |@| the meaning
- of |^| so that we may safely change the catcode of |^|.
-\code
- |\begingroup\catcode`\'=\active \catcode`\`=\active
- | \catcode\lq\@=\catcode\lq\^ \catcode\lq\^=\active
- | \catcode\lq\@@M=\active \toksa={\endgroup %
- | \def\CODElinei#1@@M{%
- | \begingroup\let`\lq \let'\rq %
- | \let^\CODEcircum \let~ \CODEtilde%
- | \edef\tmp{#1}%
- | \write\CODEwrite\expandafter{\tmp}%
- | \endgroup %
- | \indent\the\everycodeline #1\par %
- | \endgroup % matches \CODEline
- | }%
- |}\the\toksa
-\endcode
-
- The definition for |\CODElinex| (expanded code lines) is much
- simpler:
-\code
- |\begingroup\catcode`\^^M=13 \toksa={\endgroup %
- | \def\CODElinex#1^^M{%
- | \edef\tmp{\write\CODEwrite{#1}}\tmp %
- | {\indent\the\everycodeline #1\par}%
- | }%
- |} \the\toksa
-\endcode
-%}}} code lines
-%{{{ catcode hacks
-\subsec{Macros for making category-12 characters}
-
- For characters that are active in verbatim mode (like |`|), or
- which must be specially generated in expanded code lines (such
- as braces generated with {\tt\cs{\char123 }}), we have a
- `|\CODE|-' macro that generates an explicit character token with
- catcode~12.
-
-\code
- |\begingroup\catcode`\/=0 \catcode`\\=\other /toksa={/endgroup
- | /def/CODEbslash{\}
- |}/the/toksa
-\smallbreak
- |\begingroup\catcode`\^=\other \toksa={\endgroup
- | \def\CODEcircum{^}
- |}\the\toksa
-\smallbreak
- |\begingroup\catcode`\~=\other \toksa={\endgroup
- | \def\CODEtilde{~}
- |}\the\toksa
-\smallbreak
- |\begingroup\catcode`\%=\other \toksa={\endgroup
- | \def\%{%}
- |}\the\toksa
-\smallbreak
- |\begingroup\catcode`\~=\other \toksa={\endgroup
- | \def\CODEtilde{~}
- |}\the\toksa
-\smallbreak
- |\begingroup\catcode`\[=1 \catcode`\]=2
- | \catcode`\{=\other \catcode`\}=\other
- | \toksa=[\endgroup
- | \def\CODElb[{] \def\CODErb[}]
- |]\the\toksa
-\endcode
-%}}} catcode hacks
-%{{{ customization
-\subsec{Customization}
-
- The token list register |\everycode| is expanded at the start of
- every code section, the token list register |\everycodeline| at
- the start of every code line. The default definitions select
- typewriter font for the code listings, with each line numbered.
-\code
- |\newtoks\everycode
- |\newtoks\everycodeline
-\smallbreak
- |\everycode{\tt \baselineskip=0.8\baselineskip \lineskiplimit=0pt }
-\smallbreak
- |\newcount\lineno
- |\everycodeline{\llap{$ \global\advance\lineno1
- | \scriptstyle\the\lineno $\enspace}%
- | \mark\expandafter{\the\lineno}}
-\endcode
-%}}} customization
-%}}} code sections
-%{{{ formating
-%{{{ intro
-\section{Layout}
-
- The PDCCODE macros include enough basic formatting commands to
- make a simple document---since this file needs to be
- self-contained. The formatting is fairly primitive, so that
- |pdccode.tex| will not be excessively long.
-
- The text is set in the default plain \TeX\ fonts: 10-point
- Computer Modern Roman. Titles are in CM Sans Serif Bold
- Extended, headings in CMSS Demibold Condensed, and subheadings
- in CMSS Italic: all of these are standard fonts which should be
- available on all \TeX\ systems.
-
- The line width is wide enough that code lines do not need to be
- printed in a reduced font (which looks silly).
-
- the first tokenm of a document is |\relax| and everything except
- the initial |\input| and final |\bye| in the document is
- enclosed in |\document|\dots|\enddocument|. This is so that
- documents using the PDCCODE conventions can be embedded within a
- another document which by redefining these tokens.
-\code
- |\let\document\relax \let\enddocument\relax
-\endcode
-
- I have to set some \TeX~3 parameters because we don't seem to
- have definitions for them in the local version of |plain.tex|.
-\code
- |\lefthyphenmin=3 \righthyphenmin=2 \errorcontextlines10000
-\endcode
-
-%}}} intro
-%{{{ layout
-\subsec{Layout}
-
- The text width is wide enough for 72-character code lines.
-\code
- |\parindent=2em \hsize=36\fontdimen6\tentt \advance\hsize\parindent
-\endcode
- A largish left margin is used set---perhaps readers will find it
- useful for writing comments.
-\code
- |\hoffset=210mm \advance\hoffset-\hsize \advance\hoffset-25mm
- |\newdimen\leftmargin \leftmargin=\hoffset \advance\leftmargin-25mm
- |\advance\hoffset-1in
-\endcode
-
- The vertical margins are set so that if the file is formatted
- for A4 ($297\mm$) paper and fed into a driver which thinks it is
- formatted for American Letter ($11\inch$) paper no information
- will be lost. We allow for $7\mm$ unprintable area at the edges
- of paper (this is reasonable for a laser printer), and for the
- headline being $24\pt + 6\pt - 10\pt = 20\pt$ above the top of
- the text. (The $6\pt$ allows for the height of the headline,
- which is in 7-pt type.)
-\code
- |\voffset=297mm \advance\voffset-11in
- |\advance\voffset7mm \advance\voffset20pt
- |\vsize=297mm \advance\vsize-2\voffset \advance\vsize-2\baselineskip
- |\advance\voffset-1in
-\endcode
-
- We use ragged-right (ranged-left) printing. (Readability
- studies have indicated that ragged-right printing is, if
- anything, easier to read than with both sides aligned.) To do
- this we remove the stretch and shrink components of the font we
- use, and make the right margin stretchable.
-\code
- |\def\do#1{\fontdimen3#1=0pt \fontdimen4#1=0pt }
- |\do\tenrm \do\tenit \do\tenbf
-\smallbreak
- |\rightskip=0pt plus 2em minus 2pt \adjdemerits=0 \tolerance=500
- |\parfillskip=0pt plus 0.8\hsize
-\endcode
-%}}} layout
-%{{{ title and headline
-\subsec{Title and headline}
-
- The author and title info are printed at the top of the first
- page---in lieu of a separate title page---and the title goes in
- the headline of subsequent pages, followed by the version ID and
- date as extracted from the RCS identification string. If the
- file locker is non-empty (i.e., the file is being edited), an
- `e' is appended to the version ID in the headline.
-\code
- |\def\author#1{\def\theauthor{#1}} \author{P. Damian Cugley}
-\smallbreak
- |\font\titlefont=cmssbx10 scaled \magstep3
-\smallbreak
- |\def\title#1{
- | \vglue2\baselineskip
- | \begingroup \parindent-\leftmargin \hyphenpenalty10000 \titlefont
- | #1\smallskip
- | \endgroup
- | \leftline{Version \fileversion,
- | last changed \fileauthor\space \mungedate\filedate}
- | \ifx\filelocker\empty\else
- | \leftline{Edited by \filelocker\unskip\ \today}
- | \fi
- | \medskip
- | \hrule \vskip1pt \hrule \vskip1pt \hrule \vskip1pt \hrule
- | \medskip
- | \rightline{\theauthor}
- | \bigskip
- | \headline{\hfil\global\headline{%
- | \sevenbf \hskip-\leftmargin \themarks \hfil #1
- | \fileversion
- | \ifx\filelocker\empty
- | \space\mungedate\filedate
- | \else
- | e\space\today
- | \fi
- | }}
- |}
-\smallbreak
- |\def\themarks{%
- | \ifx\firstmark\empty\else
- | \firstmark
- | \ifx\firstmark\botmark \else --\botmark \fi
- | \fi
- |}
-\endcode
-
- Some macros for printing the date. The |\mungedate| macro
- converts from RCS's format (using slashes) to ISO format (using
- short dashes).
-\code
- |\def\today{\mungedate{\number\year/\twodigits\month/\twodigits\day}}
- |\def\twodigits#1{\ifnum#1<10 0\fi \number#1}
- |\def\mungedate#1{$ \textfont0=\font \mathcode`/="7B #1 $}
-\endcode
-
-%}}} title and author
-%{{{ sectioning
-\subsec{Sectioning}
-
- The sectioning commands do no more than generate numbered
- headings---there are no tables of contents or marks required.
-\code
- |\font\secfont=cmssdc10 at 12pt
- |\font\subsecfont=cmssi10
-\smallbreak
- |\newcount\seccount
- |\newcount\subseccount
-\smallbreak
- |\def\section#1{%
- | \advance\seccount1 \subseccount=0
- | \bigbreak
- | \begingroup
- | \secfont \hyphenpenalty=10000 \tolerance=1000
- | \rightskip=0pt plus 2em
- | \noindent\llap{\number\seccount.\enspace}#1
- | \medskip
- | \endgroup
- | \noindenttrue
- |}
-\smallbreak
- |\def\subsec#1{%
- | \advance\subseccount1
- | \medbreak
- | \begingroup
- | \subsecfont \hyphenpenalty=10000 \tolerance=1000
- | \rightskip=0pt plus 2em
- | \noindent\llap{\number\seccount.%
- | \number\subseccount.\enspace}#1
- | \nobreak\smallskip
- | \endgroup
- | \noindenttrue
- |}
-\endcode
-
- Here's a simple hack to remove the indentation of the first
- paragraph following a section heading.
-\code
- |\newif\ifnoindent
-\smallbreak
- |\everypar{%
- | \ifnoindent
- | {\setbox0=\lastbox}\global\noindentfalse
- | \fi
- |}
-\endcode
-
-%}}} sectioning
-%{{{ footnotes
-\subsec{Footnotes}
-
- Plain \TeX's footnote command is adjusted to use a new parameter
- to specify the value of |\rightskip| in footnotes.\footnote*{The
- default definition sets |\rightskip| to $0\pt$, which is
- moderately disastrous given that spaces cannot stretch or
- shrink.} It was the trickiness involved in changing definitions
- like this that persuaded me to not use `|@|' characters in macro
- files.
-\code
- |\newskip\footnoterightskip \footnoterightskip=\rightskip
-\smallbreak
- |\catcode`@=11
- |\def\vfootnote#1{\insert\footins\bgroup
- | \interlinepenalty\interfootnotelinepenalty
- | \splittopskip\ht\strutbox % top baseline for broken footnotes
- | \splitmaxdepth\dp\strutbox \floatingpenalty\@MM
- | \leftskip\z@skip \rightskip\footnoterightskip
- | \spaceskip\z@skip \xspaceskip\z@skip \rm
- | \textindent{#1}\footstrut\futurelet\next\fo@t}
- |\catcode`@=11
-\endcode
- This definition is a drop-in replacement for the one in {\it\TeX
- book} Appendix~B (p.\thinspace363 in my copy).
-
-%}}} footnotes
-%{{{ abbrevs
-\subsec{Miscellaneous abbreviations}
-
- The |\<| macro for writing the names of syntactic entities (as
- \<foo>) is like in {\it\TeX book} Appendix~E. The |\cs| macro
- prints a control sequence name; I use this where the easier
- dodge of writing "|\foo|" won't work (e.g., in the argument to
- another macro). Similarly |\arg| places its argument in
- typewriter-style braces. The |\pt| macro works in maths mode.
-\code
- |\def\<#1>{\leavevmode\hbox{$\langle$\it#1\/$\rangle$}}
- |\def\cs#1{\leavevmode\hbox{\tt\char`\\#1}}
- |\def\arg#1{\leavevmode\hbox{{\tt\char`\{}#1{\tt\char`\}}}}
- |\def\pt{\,{\rm pt}} \def\em{\,{\rm em}} \def\mm{\,{\rm mm}}
- |\def\inch{''}
-\endcode
-
- To make a version of the \LaTeX\ logo that should work
- acceptably with a range of fonts ({\it\LaTeX}, {\bf\LaTeX},
- {\subsecfont\LaTeX}), I~first define a macro for raising letters
- until they are flush with the prevailing cap height. I also
- loosen up the `{\it\TeX}\/' logo (so that it also works with
- sanserif fonts) and make it set the spacefactor to 1000 (to
- override \TeX's assumption that a full stop following a capital
- $X$ isn't the end of a sentence).
-\code
- |\def\flushtop#1{%
- | \leavevmode
- | \begingroup
- | \setbox0=\hbox{#1}\setbox2=\hbox{X}%
- | \dimen0=\ht2 \advance\dimen0-\ht0
- | \raise\dimen0 \box0
- | \endgroup
- |}
-\smallbreak
- |\def\TeX{T\kern-0.1em \lower0.5ex \hbox{E}X\spacefactor1000 }
- |\def\LaTeX{L\kern-0.1em \flushtop{a}\TeX}
-\endcode
-
- Occasional paragraphs are written in italics and marked with
- `note'.
-\notepar
- The command says `notepar' not just `note' because in my macro
- files I~use \/|\note| for numbered footnotes (\/{\rm \TeX book},
- Exercise~15.12).\footnote*{Footnotes in |dtx| files are produced
- with the plain |\footnote| command.}
-
- Notes may occasionally be more than one paragraph long.
-\endnotepar
-\code
- |\def\notepar{
- | \smallskip
- | \begingroup
- | \leftskip2\parindent \advance\rightskip\parindent minus \parindent
- | \noindent\kern-\parindent{\bf Note}\quad\it
- | \ignorespaces
- |}
-\smallbreak
- |\def\endnotepar{
- | \smallbreak
- | \endgroup
- |}
-\endcode
-%}}} abbrevs
-%}}} formatting
-
-\bigskip\noindent
- The file is finished with an |\endinput| command; this can be
- used by other prgorams to check that this file hasn't been
- truncated by \TeX\ coming to a halt part-way through processing
- the |dtx| file.
-\code
- |\endinput
-\endcode
-\endcodefile
-\enddocument
-\bye
-%}}} pdccode
-
-%Local variables:
-%fill-prefix: " "
-%fold-folded-p: t
-%End: