summaryrefslogtreecommitdiff
path: root/macros/plain/contrib/pdcmac/pdccode.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/plain/contrib/pdcmac/pdccode.dtx
Initial commit
Diffstat (limited to 'macros/plain/contrib/pdcmac/pdccode.dtx')
-rw-r--r--macros/plain/contrib/pdcmac/pdccode.dtx881
1 files changed, 881 insertions, 0 deletions
diff --git a/macros/plain/contrib/pdcmac/pdccode.dtx b/macros/plain/contrib/pdcmac/pdccode.dtx
new file mode 100644
index 0000000000..e9b996dba6
--- /dev/null
+++ b/macros/plain/contrib/pdcmac/pdccode.dtx
@@ -0,0 +1,881 @@
+% 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: