%^^A* legal notices
% \iffalse
%
%   This program is part of the Frankenstein bundle for LaTeX.  
%
%   Copyright 1995-2001 Matt Swift <swift@alum.mit.edu>.
%
%   This file contains both the code and documentation for the
%   compsci LaTeX package.  It will work ONLY if it is placed in a
%   proper directory.  Files called README, INSTALL, compsci.tex
%   and compsci.ins should have also been distributed to you
%   with this file.  See them for more information on how to typeset
%   the documentation with LaTeX and how to generate a version of this
%   file that will work faster than this one.
%
%   This program is free software; you may redistribute it and/or
%   modify it under the conditions of the LaTeX Project Public
%   License, either version 1.2 or (at your option) any later version.
%   The latest version of this license is in
%   http://www.latex-project.org/lppl.txt, and version 1.2 or later is
%   part of all distributions of LaTeX version 1999/12/01 or later.
%
%   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
%   LaTeX Project Public License for more details.
%
% \fi  
%
%^^A* checks
%
%^^A NOTE:  The character table, with two %'s, will get written to all files.
%% \CharacterTable
%%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
% \CheckSum{620}
%
% \begin{abstract}
%   \package{Compsci} is useful whenever writing about programming, but
%   especially when writing about \TeX{} and especially when used as a supplement
%   to the \class{ltxdoc} class to document \LaTeX{} macros in a literate
%   programming style with \ext{dtx} files.
% \end{abstract}
% \tableofcontents
%
% \part{Discussion}
%
% \section{Textual elements}
%
% \DescribeMacro{\env}
%   \cs\env\marg{environment name} typesets the name of a \LaTeX{} environment.
%    For example, the \env{enumerate} environment.
% \todo{Add \cs\bib how about?}
%
% \DescribeMacro{\bst}
%   \cs\bst\marg{bibstyle name} typesets the name of a \BibTeX{} bibliography
%   style.  For example, the \bst{achicago} bibstyle.
%
% \DescribeMacro{\package}
%   \cs\package\marg{package name} typesets the name of a \LaTeX{} package.
%   For example, the \package{compsci} package.
%
% \DescribeMacro{\class}
%   \cs\class\marg{class name} typesets the name of a \LaTeX{} class. For
%   example, the \class{letter} class.
%
% \DescribeMacro{\file} 
%   \cs\file\marg{file name} typesets the name of a disk file.
%   For example, the file \file{Makefile.in}.
%   \todo{Should I use url.sty's \cs\path command for this?}
%
% \DescribeMacro{\ext}
%   \cs\ext\marg{extension} typesets the name of a disk file extension.  For
%   example, the extension \ext{dvi}.  The argument should not include the dot
%   that separates the root name from the extension.  The dot can be inserted
%   by the macro if you want it.
%
% \DescribeMacro{\caveat}
% \DescribeEnv{warning}
%   \cs\caveat\marg{warning text} typesets warning paragraphs.
%   You can also enclose the \meta{warning text} in a \env{warning}
%   environment.  Using the \env{warning} environment is necessary if the
%   \meta{warning text} is to include \code{|...|}s, a \env{codeexample}
%   environment or other ``verbatim'' constructs.
%
%   \caveat{This is an example \cs\caveat or \env{warning} environment.}
%   
% \DescribeMacro\todo
% \DescribeEnv{todoenv}
%   The \cs\todo\marg{text} command and the \env{todoenv} environment are
%   analogous to \cs\caveat and \env{warning}, but they typeset paragraphs of a
%   task ``to do''.
%
%   \todo{This is an example \cs\todo or \env{todoenv} environment.}
%
% \DescribeMacro{\code}
% \DescribeMacro{\code*}
% \DeleteShortVerb{\|}
% \DescribeMacro{|...|}
%   \cs\code\marg{verbatim text} and \code{|}\meta{verbatim text}\code{|}
%   typeset short pieces of code verbatim.  For example,
%   \code+|{{+\code{@#%$^\|} looks like      ^^A $}} for emacs
%^^A  Dang tricky to give a tricky example!
%   \begingroup
%     \def~{\char`\\}%
%     \makeatother
%     \catcode`\[=1\catcode`\]=2\catcode`\{=12\relax
%     \catcode`\#=12
%     \catcode`\+=14 +
%     \catcode`\$=12 +
%     \catcode`\^=12 +
%     \catcode`\%=12 \fbox[\ttfamily {{@#%$^~]\endgroup.        ^^A for emacs $
%
%   Instead of matching curly braces, any two identical characters, even a
%   space, may be used to contain the \meta{verbatim} after the \cs\code
%   command.
%
%   \todo{Implement \cname{code*}.  Like \cname{verb*}, \cname{code*} marks
%   spaces explicitly.  This is not an example todo, this is a real one for the
%   \package{compsci} package!}
% \MakeShortVerb{\|}
%
% \DescribeMacro{\typeset}
%    \cs\typeset\marg{text} typesets \meta{text} in a normal way, but indicates
%    by boxing that the contents are an example of how some piece of code
%    actually appears.  For example, \code{this} looks like \typeset{this} when
%    typeset.
%
% \DescribeEnv{typesetexample}
%   These example environments may be used to present a piece of source code
%   and what it looks like when typeset.  The \env{typesetexample} environment
%   typesets its contents like \cs\typeset except they are set off in their own
%   indented block element instead of being boxed. 
%
%   \begin{typesetexample}
%     This is an example of the \env{typesetexample} environment.
%   \end{typesetexample}
%
% \DescribeEnv{codeexample}
% \DescribeEnv{codeexample*}
% \DescribeEnv{codeexamplex}
% \DescribeEnv{codeexamplex*}
%   The \env{codeexample} and
%   \env{codeexample*} environments are similar analogs of \cs\code and
%   \cname{code*}.  The \env{codeexamplex} environment is like the
%   \env{codeexample} environment except that |\|, |{|, |}| have their usual
%   meanings. Inside the argument, \cs\\ produces a typeset backslash.  
%   \begin{codeexample}
%   This is a \env{codeexample} environment: \(\int e^x\,dx\)  {}{{{!#@$%^&\
%   There is a percent sign in the source after the $.
%   \end{codeexample}
%
%   \begin{codeexample*}
%   This is a \env{codexample*} environment: \(\int e^x\,dx\)  {}{{{!#@$%^&\
%   Someday I would like to get rid of the leading spaces in a line.
%   \end{codeexample*}
%
%   \begin{codeexamplex}
%   This is a \env{codeexamplex} environment:  \(\int e^x\,dx\)  {}{{{}}}!#@$%^&\\
%   The earlier examples had three unmatched open-braces which had to be
%   closed in this environment.  Also the backslash had to be doubled.
%   Percent signs get ignored---a BUG.
%   \end{codeexamplex}
%
%   \begin{warning}
%     The \env{codeexamplex} environment ideally should ignore \code{%}s in the
%     first column and print all others.  The best I can do for the moment is
%     to ignore \emph{all} \code{%}s.
%   \end{warning}
%
% \DescribeEnv{bothexample}
% \DescribeEnv{bothexample*}
%   The \env{bothexample} and \env{bothexample*} environments typeset their
%   contents two times, side by side.  The left side is set like either a
%   \env{codeexample} or \env{codeexample*} environment, and the right side is
%   set like a \env{typesetexample} environment.
%
%   I find setting a line width of 65 characters in your editor helps keep
%   this kind of example from bleeding to the right.
%
%   \begin{bothexample}
%     This is one part of a \env{bothexample} environment: 
%     \(\int e^x\,dx\)  \fbox{jub-jub} \par
%     The contents must not contain any \LaTeX{} errors.
%
%     There is an annoying \% plus three explicit spaces at the beginning of
%     the first part.  They are a bug!  Also notice also the missing percent 
%     sign after the backslash after ``annoying''---another bug that affects
%     the verbatim part only.
%   \end{bothexample}
% 
% \DescribeEnv{splitexample}
% \DescribeEnv{splitexample*}
%   The \env{splitexample} environment takes an argument which is used on the
%   right side (the typeset side) of an element that looks like
%   \env{bothexample}.  The contents of the environment are set on the left
%   side.  This is a way to cheat, making the right side something other than
%   the strict tyepsetting of what's on the left.
%  
%   \begin{warning}
%     The \env{splitexample} and \env{bothexample} environments \emph{execute}
%     example code.  The example code is executed in a group, but be careful
%     with global assignments, and with assignments that might screw up the
%     example environment itself before the group ends.  Notice that
%     \cs\setcounter is global.
%   \end{warning}
%
%   The \env{bothexample} and \env{splitexample} environments use an auxiliary
%   file with extension \ext{vrb}, but a second pass with \LaTeX{} is not
%   necessary.
% 
%   \todo {Implement \env{splitexample} and \env{splitexample*}.}
%
%   \todo {Get the \env{bothexample} sub-environments side by side!  Right now
%   they are sequential.  I recommend keeping line length inside this
%   environment less than 40, however, in case the side-by-side presentation is
%   ever possible.  I have not followed this advice myself.}
%
%   \todo {Implement \env{codeexamplex*}.}
%
%   \caveat{The \env{bothexample} environment is working nicely now, but I have
%   not even touched the other complicated verbatim-like environments, so they
%   might be broken.}
%
% \DescribeMacro{\url}
% \DescribeMacro{\email}
% \DescribeMacro{\path}
% \DescribeMacro{\file}
%   The \package{compsci} package uses the \package{url} package by Donald
%   Arseneau to handle the typesetting of URLs, email addresses, and filesystem
%   paths.  See that package for details of how line breaks are handled within
%   these elements.  
%
% \DescribeMacro{\option}
%   \cs\option\marg{option name} typesets the name of a package or class
%   option.  For example, the \option{landscape} option.
%
% \DescribeMacro{\program}
%   \cs\program\marg{program name} typesets the name of a computer program.
%   For example the \program{xdvi} program.  See also \cs\newprogram below.
%
% \DescribeMacro{\lips}
%   The \package{compsci} package uses the \package{lips} package, so you can
%   use the \cs\lips command for text ellipses.  My love is like a red red rose
%   \lips.
%
% \DescribeMacro{\book}
%   The \package{compsci} package uses the \package{titles} package, so several
%   commands like \cs\book are available.
%
% \section{Referring to commands}
%
% \DeleteShortVerb{\|}
% \DescribeMacro{\cs}
% \DescribeMacro{\cmd}
%   \cs\cs\marg{command sequence} typesets a command sequence, such as the one
%   that starts this sentence.  \cs\cmd does the same thing.  For example,
%   \code{\cs\foo} looks like \typeset{\cs\foo}.  When writing, e.g.,
%   \code{\cs\foo} the following spacing is automatically handled.  The result
%   doesn't look different from using the \code{|...|} or \cs\code syntax, but
%   the markup allows the parsing of the macro name itself for some future
%   purpose such as indexing.  
%
%  \MakeShortVerb{\|}
%
%   \begin{warning}
%     You cannot say \code{\cs\foo@bar} when |@| is not a letter (category code
%     11), you must say \code{\cs{\foo@bar}} or \code{\cname{foo@bar}} instead.
%
%     Nor can you say \code{\cs\par}.  It trips on \cname{text@command}.
%
%     Nor can you say \code{\cs\iffoo}.  Use \code{\cname{iffoo}} instead.
%   \end{warning}
%
% \DescribeMacro{\cname}
%   \cs\cname\marg{command name} is like \cs\cs but its argument is evaluated
%   and prefixed with a backslash character.    For example, writing 
%   |\cname{@tfor}| gives you \typeset{\cname{@tfor}}. 
%
% \DescribeMacro{\marg}
% \DescribeMacro{\oarg}
%   \cs\marg\marg{mandatory argument} typesets a mandatory argument, and
%   \cs\oarg\marg{optional argument} typesets an optional argument.  For
%   example, These macros are defined with \cs\meta, so you can use |\\| for a
%   typeset backslash.
%   \begin{bothexample}
%     \cs\GobbleMOM\marg{first arg}\oarg{optional second arg}\marg{third arg}
%   \end{bothexample}
%
% \DescribeMacro{\meta}
%   \cs\meta\marg{text} refers to a syntactic placeholder.  You would use this
%   for example to talk about one of the arguments of a command you've
%   introduced, like \meta{text} above, which can contain normal text but is
%   broken across lines only at spaces.  Within the argument |\\| is a typeset
%   backslash.
%
% \section{Miscellaneous}
%
% \DescribeMacro{\newprogram}
%   The \package{compsci} package uses the \package{abbrevs} package to define
%   the |Program| category of abbreviation.  Use
%   \cs\newprogram\marg{\\csname}\marg{initial expansion}\oarg{subsequent
%   expansion} to define a new abbreviation \marg{\\csname} for a program.
%
% \DescribeMacro{\ProcessDTXFile}
%   \cs\ProcessDTXFile can be used by a documentation driver file of the kind
%   you might be inclined to make using the \package{doc} package.  Its purpose
%   is to be able to load a package up to a certain point so that just
%   descriptive information can be read without reading in the whole file.
%   \cs\ProcessDTXFile\marg{filename} defines the variable
%   \cs\JusTLoaDInformatioN and inputs the file \meta{filename}.  To be useful,
%   the file must have a statement that branches on whether
%   \cs\JusTLoaDInformatioN is defined.  For an example of its use, see the
%   present package.
%
% \DescribeMacro{\MaybeBibliography}
% 
%  Sorry, you will need to look at the source below.
%
% \DescribeMacro{\AddToCheckSum}
%   \cs\AddToCheckSum\marg{number} simply adds \meta{number} globally to the
%   checksum counter implemented in the \package{doc} package.    This macro
%   finds applications when the sources of a package are spread over one or
%   more files such as configuration files or files concatenated by a
%   \program{Make} process.  For an example of its use, see the present package.
%
% \DescribeMacro{\BibTeX}
%   The \BibTeX{} logo is provided if it isn't already defined.
%
% \StopEventually{}
%
% \part{Implementation}
%
% \section{Version control}
%
%  \begin{macro}{\fileinfo}
%  \begin{macro}{\DoXUsepackagE}
%  \begin{macro}{\HaveECitationS}
%  \begin{macro}{\fileversion}
%  \begin{macro}{\filedate}
%  \begin{macro}{\docdate}
%  \begin{macro}{\PPOptArg}
% These definitions must be the first ones in the file.
%    \begin{macrocode}
\def\fileinfo{macros for writing about macros (Frankenstein's conscience)}
\def\DoXPackageS {}
\def\fileversion{v1.2}
\def\filedate{2001/08/31}
\def\docdate{2001/08/31}
\edef\PPOptArg {%
  \filedate\space \fileversion\space \fileinfo
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
% If we're loading this file from a \cs\ProcessDTXFile command (see the
% \package{compsci} package), then \cs\JusTLoaDInformatioN will be defined;
% othewise we assume it is not (that's why the FunkY NamE).
% 
% If we're loading from \cs\ProcessDTXFile, we want to load the packages listed
% in \cs\DoXPackageS (needed to typeset the documentation for this file) and
% then bail out.  Otherwise, we're using this file in a normal way as a
% package, so do nothing.  \cs\DoXPackageS, if there are any, are declared in
% the \ext{dtx} file, and, if you're reading the typeset documentation of this
% package, would appear just above.  (It's OK to call \cs\usepackage with an
% empty argument or \cs\relax, by the way.)
%    \begin{macrocode}
\makeatletter% A special comment to help create bst files.  Don't change!
\@ifundefined{JusTLoaDInformatioN} {%
  }{% ELSE (we know the compsci package is already loaded, too)
  \UndefineCS\JusTLoaDInformatioN
  \SaveDoXVarS
  \eExpand\csname DoXPackageS\endcsname\In {%use \csname in case it's undefined
    \usepackage{#1}%
  }%
  \RestoreDoXVarS
  \makeatother
  \endinput
}% A special comment to help create bst files.  Don't change!
%    \end{macrocode}
%
% Now we check for \LaTeX2e and declare the LaTeX package.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{compsci}[\PPOptArg]
%    \end{macrocode}^^A special comment to help create bst files.  Don't change!
%
% ^^A NOTE: We have to compensate for the above backslashes, which are not
% ^^A       actually in the .dtx file the author works on, by adding to the
% ^^A       CheckSum.
%%
% \AddToCheckSum{17}^^A `dtx-update-checksum' automatically handles this.
% \AddToCheckSum{7}^^A The half a macrocode env. at the top is missed, however...
% \AddToCheckSum{10}^^A ... and so are the 5 \defs from the .dtx file 
%                   ^^A     that precede it.
% \IfCitations {%
%   \AddToCheckSum{2}^^A When \initelyHavECitationS is defined in
% }                  ^^A the .dtx file, we need 2 more in the CheckSum.
% 
%
% \section{Requirements and context}
%
% ^^A FIX do check and set boolean for being inside \Doc thing etc. have to
% ^^A branch on all verbatim-like stuff.
%    \begin{macrocode}
\RequirePackage{abbrevs,alltt,lips,moredefs,relsize,shortvrb,%
                slemph,titles,url,verbatim}
%    \end{macrocode}
%
% \section{Hyperlatex option}
% Handle \option{hyperlatex} option here.  \todo{Should this inherit globally?}
% Long URLs are so common and screw up LaTeX in the middle of a paragraph that
% a good scheme seems to be to relegate them to footnotes.  Make option/switch
% for footnotes and inline.
%
% Actually, when it's a footnote, there's almost never going to be a linebreak,
% unless the url is longer than the textwidth of the footnote...so |\textt{}|
% is probably going to be fine.
%
% Could also use \code{\marginpar{\smaller\url{#1}}}---definitely would have to
% use \cs\url not \cs\textt there.
%
% We undefine \cs\code and \cs\file immediately because we want
% \package{compsci}'s versions not \package{hyperlatex}'s.
%    \begin{macrocode}
\DeclareOption{hyperlatex} {%
  \FrankenInfo{compsci}{hyperlatex}
  \UndefineCS\code
  \UndefineCS\file
  \AtEndOfPackage {
%    \UndefineCS\code  hunh?????
    \DeleteShortVerb{\|}
    \newlet\cs@url\url
    \renewcommand*\url [1][] {%
      \def\sc@t@a{#1}%
      \ifx\sc@t@a\ShortEmpty
        \let\sc@t@a\cs@url
      \else
        \defcommand\sc@t@a [1] {%
          #1\footnote{See \texttt{##1}.}%
        }%
      \fi
      \sc@t@a
    }
    \renewcommand*\email [1][] {%
      \def\sc@t@a{#1}%
      \ifx\sc@t@a\ShortEmpty
        \expandafter\cs@email
      \else
        #1 \expandafter\cs@email
      \fi
    }
  }
}
\ProcessOptions
%    \end{macrocode}
% \todo{Alternative ways to handle things}
%    \begin{macrocode}
%%
%    \def\sc@t@a {%
%       #1%
%       \begingroup
%         \def\UrlLeft {( see}%
%         \def\UrlRight {)}%
%         \Url
%     }%
%%
%    \def\sc@t@a {%
%       #1%
%       \begingroup
%         \def\UrlLeft{\footnote\bgroup}%
%         \def\UrlRight {.\egroup}%
%         See \Url
%     }%
%    \end{macrocode}
%
% \section{Textual elements}
%
% \DeleteShortVerb{\|}
% \begin{macro}{\code}
% \begin{macro}{|...|}
% \begin{macro}{\url@ttnobreakstyle}
%   We use the \package{url} package to implement \cs\code and the
%   \package{shortvrb} package to implement \code{|...|}.  There are no
%   linebreaks in either.  See the respective packages for considerations of
%   robustness.
%
% \todo {summarize robustness considerations here.}
%    \begin{macrocode}
\MakeShortVerb{\|} 
\newcommand*\code {%
  \begingroup
    \urlstyle{ttnobreak}%
    \Url
}
\newcommand\url@ttnobreakstyle {%
  \def\UrlFont     {\ttfamily}%
  \def\UrlSpecials {\do\ {\ }}%
  \def\UrlOrds     {\do\*\do\-}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \MakeShortVerb{\|}
%
% \begin{environment}{codeexample}
% \begin{environment}{codeexample*}
%   What I'm doing here is defining \env{codeexample} and \env{codeexample*} to
%   be just like the \package{doc} package's \env{verbatim} and
%   \env{verbatim*}.  That is, they ignore |%| 
%   characters at the beginning of lines.
%    \begin{macrocode}
\begingroup
  \catcode `|=0
  \catcode `[=1
  \catcode `]=2
  \catcode`\{=12
  \catcode`\}=12
  \catcode`\\=12
  |gdef|@xverbatim#1\end{codeexample}[#1|end[codeexample]]
  |gdef|@sxverbatim#1\end{codeexample*}[#1|end[codeexample*]]
|endgroup
\newcommand\codeexample {%
  \@beginparpenalty
  \predisplaypenalty
  \@docverbatim
  \MacroFont
  \frenchspacing
  \@vobeyspaces
  \@xverbatim
}
\NewName{codeexample*} {} {%
  \@beginparpenalty
  \predisplaypenalty
  \@docverbatim
  \MacroFont
  \@sxverbatim
}
\newcommand\@docverbatim {%
  \trivlist
  \item[]%
  \if@minipage\else
    \vskip\parskip
  \fi
  \leftskip\@totalleftmargin
  \rightskip\z@
  \parindent\z@
  \parfillskip\@flushglue
  \parskip\z@
  \@@par
  \@tempswafalse
  \def\par {%
    \if@tempswa
      \hbox{}%
    \fi
    \@tempswatrue
    \@@par
    \penalty\interlinepenalty
    \check@percent
  }%
  \obeylines
  \let\do\do@noligs
  \verbatim@nolig@list
  \let\do\@makeother
  \dospecials
}
%    \end{macrocode}
% \end{environment}
% \end{environment}
%
% \begin{macro}{\MakePercentIgnore}
% \begin{macro}{\MakePercentComment}
%    These are defined in the \package{doc} package, which may be loaded.
%    \begin{macrocode}
\requirecommand*\MakePercentIgnore{\catcode`\%9\relax}
\requirecommand*\MakePercentComment{\catcode`\%14\relax}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{environment}{codeexamplex}
%   The \env{codeexamplex} environment ideally should ignore |%|s in the
%   first column and print all others.  The best I can do for the moment is to
%   ignore |%|s. \todo{use verbatim-write trick}
%    \begin{macrocode}
\newenvironment{codeexamplex} {%
    \alltt
    \def\\{\char`\\}%
    \MakePercentIgnore\relax
  }{%
  \endalltt
}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{typesetexample}
%   The \env{typesetexample} environment is simple, it's just the \env{quote} environment.
%    \begin{macrocode}
\newenvironment{typesetexample} {%
    \quote
  }{%
  \endquote
}
%    \end{macrocode}
% \end{environment}
%
%   To implement the \env{bothexample} environments we write out the contents
%   of the environment and read them in twice, typesetting them differently
%   each time.  The \env{verbatimwrite} environment comes from the
%   \package{moreverb} package.  Reading the text twice seems unavoidable
%   because we want to read them with different catcodes each time.
%
%   \todo {Figure whether the tab stuff here is going is a help or a
%   hindrance.}
%
% \begin{macro}{\verbatim@out}
% \begin{macro}{\end@cs@verbatim@write}
% \begin{macro}{\cs@verbatim@write}
% \begin{macro}{\verbtab@oktrue}
% \begin{macro}{\verbtab@okfalse}
% \begin{macro}{\ifverbtab@ok}
% \begin{macro}{\if@cs@first@line@}
% \begin{macro}{\@cs@first@line@true}
% \begin{macro}{\@cs@first@line@false}
% \begin{macro}{\cs@verbatim@input}
%    \begin{macrocode}
\newwrite \verbatim@out
\DefName{end@cs@verbatim@write} {} {%
  \immediate\closeout\verbatim@out
  \@esphack
}
\defcommand\cs@verbatim@write [1] {%
  \@bsphack
  \immediate\openout \verbatim@out #1
  \let\do\@makeother\dospecials
  \catcode`\^^M\active \catcode`\^^I=12
  \def\verbatim@processline {%
    \if@cs@using@doc@
      \immediate\write\verbatim@out{\expandafter\GobbleM\the\verbatim@line}%
    \else
      \immediate\write\verbatim@out{\the\verbatim@line}%
    \fi
  }%
  \verbatim@start
}
\newboolean{verbtab@ok}
\newboolean{@cs@first@line@}
\ReserveCS\cs@verbatim@input
\@cs@first@line@true
{\catcode`\~=\active \lccode`\~=`\^^M \lccode`\N=`\N
  \lowercase{%
    \gdef\cs@verbatim@input #1{%
      \begingroup
        \@verbatim\frenchspacing\@vobeyspaces
        \def\verbatim@addtoline##1~{%
          \verbatim@line\expandafter{\the\verbatim@line##1}%
        }%
        \openin\verbatim@in@stream=#1
        \ifeof\verbatim@in@stream
          \FrankenError{compsci}
            {Can't find file #1!}\@eha
        \else
          \verbtab@oktrue
          \verbatim@line {}%
          \def\verbtab@prev@line{PREVINIT~}%
          \loop
            \read\verbatim@in@stream to \verbtab@line
            \ifeof\verbatim@in@stream
              \verbtab@okfalse
            \else
%              \DTypeout{My line is: [\meaning\verbtab@line]}%
              \if@cs@first@line@
%                \DTypeout{I'm avoiding printing: [\meaning\verbtab@prev@line]}%
                \@cs@first@line@false
              \else
%                \DTypeout{I'll print: [\meaning\verbtab@prev@line]}%
                \expandafter\verbatim@addtoline\verbtab@prev@line
                \the\verbatim@line
                \par
                \verbatim@line {}%
              \fi
              \let\verbtab@prev@line\verbtab@line
            \fi
          \ifverbtab@ok \repeat
          \closein\verbatim@in@stream
        \fi
        \endtrivlist
      \endgroup
      \@doendpe
    }%               \gdef
  }%                \lowercase
}%                  catcodes
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{environment}{bothexample}
% \begin{environment}{bothexample*}
%   The first \cs\begingroup\lips{}\cs\endgroup I think is necessary to contain
%   the verbatim activity.  The second is necessary so that activity in the
%   example environment does not effect anything outside it.  Of course global
%   activity will, so be careful!  The \cs\minipage effects the second
%   group. [Hmm, I don't see a ``second'' group\lips.]
%    \begin{macrocode}
\newboolean{@cs@using@doc@}
\newenvironment{bothexample} {%
    \@ifundefined{ver@doc.sty} {%
        \@cs@using@doc@false
      }{% ELSE
      \@cs@using@doc@true
    }
    \par
    \begingroup
     \cs@verbatim@write{\jobname.vrb}
  }{%
  \end@cs@verbatim@write
  \cs@verbatim@input{\jobname.vrb}%
  \endgroup
  \par\noindent{\sffamily\larger LOOKS LIKE:}%
  \par\smallskip
  \noindent\fbox{%
    \minipage{\textwidth}
      \MakePercentComment
      \input{\jobname.vrb}%
    \endminipage
  }%
  \par\medskip
}
%    \end{macrocode}
% \end{environment}
% \end{environment}
%
% \begin{environment}{splitexample}
% \begin{environment}{splitexample*}
%   We can't use |#1| in the end-environment part, so we write it out.  Again
%   we have the problem of |%|s.  
%   \caveat{This is broken!}  ^^A FIX
%   ^^A FIX:  keep this in step with developments in the presentation of the
%   ^^A       botheexample stuff.
%    \begin{macrocode}
% \newenvironment{gogog}[1]
%   {\verbatimwrite{\jobname.vrb}#1}
%   {\endverbatimwrite}
\newenvironment{splitexample} [1] {%
  \cs@verbatim@write{\jobname.vrb}
    #1
  \end@cs@verbatim@write
  \codeexample
  }{%
  \endcodeexample
  \par\smallskip
  \noindent\fbox{%
    \minipage{\textwidth}
    \input{\jobname.vrb}%
    \endminipage
  }%
  \par\medskip
}  
%    \end{macrocode}
% \end{environment}
% \end{environment}
%
% \begin{macro}{\caveat}
% \begin{environment}{warning}
% \begin{macro}{\cs@caveat}
% \begin{macro}{\todo}
% \begin{environment}{todoenv}
% \begin{macro}{\cs@todo}
%   \mbox{}
%    \begin{macrocode}
\newcommand\caveat [1] {%
  \cs@caveat
  #1%
  \endgroup
  \par
}
\newenvironment{warning} {%
    \cs@caveat
  }{%
  \endgroup
  \par
}
\newcommand\cs@caveat {%
  \par
  \begingroup
    \em {\bfseries Warning:}\space
}
\newcommand\todo [1] {%
  \cs@todo
    #1%
  \endgroup
  \par
}
\newenvironment{todoenv} {%
    \cs@todo
  }{%
  \endgroup
  \par
}
\newcommand\cs@todo {%
  \par
  \begingroup
    \em {\bfseries To do:}\space
}
%    \end{macrocode}
% \end{macro}
% \end{environment}
% \end{macro}
% \end{macro}
% \end{environment}
% \end{macro}
%
% \begin{macro}{\program}
% \begin{macro}{\bst}
% \begin{macro}{\class}
% \begin{macro}{\env}
% \begin{macro}{\ext}
% \begin{macro}{\file}
% \begin{macro}{\option}
% \begin{macro}{\package}
% \begin{macro}{\cat}
% \begin{macro}{\typeset}
%   Abstract markup of terms and objects.
%    \begin{macrocode}
\NewTextFontCommand \program \TMFontProgram % generic name of computer program
\NewTextFontCommand \bst     \ttfamily      % name of BibTeX bibliography style
\NewTextFontCommand \class   \slshape       % name of LaTeX class
\NewTextFontCommand \env     \ttfamily      % name of environment
\NewTextFontCommand \ext     \ttfamily      % name of file extension
\NewTextFontCommand \option  \ttfamily      % name of package or class option
\NewTextFontCommand \package \slshape       % name of LaTeX package
\NewTextFontCommand \cat     \sffamily      % name of a category
\newlet             \typeset \fbox          % text as it appears when typeset
\newlet             \file    \path          % name of disk file
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\email}
% \begin{macro}{\cs@email@nobrace}
% \begin{macro}{\cs@email}
% The \option{hyperlatex} option will change \cs\email at the end of this
% package.
%    \begin{macrocode}
\newcommand\cs@email {%
  \begingroup
    \def\UrlLeft{<}%
    \def\UrlRight{>}%
    \urlstyle{tt}%
    \Url
}
\newcommand\cs@email@nobrace {%
  \begingroup
%    \def\UrlLeft{<}%
%    \def\UrlRight{>}%
    \urlstyle{tt}%
    \Url
}
\newcommand\email{\cs@email}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
% \section{Referring to commands}
%
% \begin{macro}{\meta}
% \begin{macro}{\m@ta}
% \begin{macro}{\do@space}
% \begin{macro}{\sp@ce}
% \begin{macro}{\sp@@ce}
%   Here I redefine \cs\meta to include a \cs\normalfont right at the beginning
%   inside a group, since the command was working strangely when \cs\ttfamily
%   was in effect.  Also, I redefine |\\| to be a typeset backslash.
%    \begin{macrocode}
\begingroup
\obeyspaces%
\catcode`\^^M\active%
\gdef\meta{\begingroup\let\\\textbackslash\normalfont\obeyspaces\catcode`\^^M\active%
\let^^M\do@space\let \do@space%
\def\-{\egroup\discretionary{-}{}{}\hbox\bgroup\itshape}%
\m@ta}%
\endgroup
%    \end{macrocode}
% These are simply from the \package{doc} package.
%    \begin{macrocode}
\defcommand\m@ta [1] {%
  \leavevmode
  \hbox\bgroup$\langle$\itshape#1\/$\rangle$\egroup
  \endgroup
}
\def\do@space {%
  \egroup
  \space
  \hbox\bgroup\itshape\futurelet\next\sp@ce
}
\def\sp@ce {%
  \ifx\next\do@space
    \expandafter\sp@@ce
  \fi
}
\defcommand\sp@@ce [1] {%
  \futurelet\next\sp@ce
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\marg}
% \begin{macro}{\oarg}
%   These use \cs\meta and are therefore slightly different than their
%   counterparts in \class{ltxdoc}.  A tiny bit of breakability is added at the
%   beginning.
%    \begin{macrocode}
\defcommand*\marg [1] {%
  \penalty 9999%
  {\ttfamily\char`\{\meta{#1}\char`\}}%
}
\defcommand*\oarg [1] {%
  \penalty 9999%
  {\ttfamily[\meta{#1}]}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\cname}
% \begin{macro}{\cmd}
% \begin{macro}{\cs}
%   For referring to a \LaTeX{} macro.  The code is a mix from the
%   \class{ltxdoc} class and the \package{abbrevs} package.  There is no need
%   to check for \cs\nocorr commands inside the argument so we skip
%   \cs{\text@command}.  We might conceivably be in a typewriter slanted, so we
%   do check for italic corrections.  We don't handle the case of calling this
%   in math mode (see the definition of \cs\DeclareTextFontCommand in the
%   kernel).
%
%   We handle the cases of |\cmd{\foo}| and \cmd\foo differently.  The latter
%   needs logic to determine the following space, whereas the former does not.
%   They both need italic corrections.
%    \begin{macrocode}
\NewRobustCommand*\cname [1] {%
  \expandafter\code\expandafter{\bslash#1}%
}
\DeclareRobustCommand*\cmd {%
  \leavevmode
  \@ifnextchar \bgroup
      \cs@cmd@grouped
    \cs@cmd@ungrouped
}
\newcommand\cs@cmd@grouped [1] {%
  \begingroup
    \maybe@ic
    \code{#1}%
    \aftergroup\maybe@ic
  \endgroup
}
\newcommand\cs@cmd@ungrouped [1] {%
  \begingroup
    \maybe@ic
    \code{#1}%
    \aftergroup\maybe@ic@space
  \endgroup
}
\let\cs\cmd
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \section{Miscellaneous}
%
% \begin{macro}{\partname}
% \begin{macro}{\ProcessDTXFile}
% \begin{macro}{\IfJustLoadInformation}
% \begin{macro}{\JusTLoaDInformatioN}
% \begin{macro}{\IfCitations}
% \begin{macro}{\initelyHavECitationS}
% \begin{macro}{\SaveDoXVarS}
% \begin{macro}{\RestoreDoXVarS}
% \begin{macro}{\RestorECitationS}
% \begin{macro}{\AddToCheckSum}
%   See the version control section above and all throughout the \Frankenstein
%   bundle for examples of when you might want to use these commands.
%%
% ^^A FIX Add ltxdoc check for addtochecksum?
%    \begin{macrocode}
\def\partname {%
  Part%
}
%    \end{macrocode}
% We make sure it's OK to use \cs\def\DoXPackageS multiple times.  You might
% need to call packages with options.
%    \begin{macrocode}
\newcommand*\ProcessDTXFile [1] {%
  \def\filename {#1}%
  \def\JusTLoaDInformatioN {}%
  \UndefineCS\initelyHavECitationS
  \input{#1}%
  \UndefineCS\JusTLoaDInformatioN % not necessary in my usage, but safe 
}
\newcommand*\IfCitations [1] {%
  \@ifundefined{initelyHavECitationS} {%
    }{% ELSE
    #1\relax
  }%
}
\newcommand*\IfJustLoadInformation [1] {%
  \@ifundefined{JusTLoaDInformatioN} {%
    }{% ELSE
    #1\relax
  }%
}
\newcommand*\SaveDoXVarS {%
  \SaveCS\fileinfo \SaveCS\fileversion
  \SaveCS\filedate \SaveCS\docdate
  \SaveCS\DoXPackageS
  \def\RestorECitationS {%
    \UndefineCS\initelyHavECitationS
  }%
  \IfCitations {%
    \let\RestorECitationS\relax
  }%
}
\newcommand*\RestoreDoXVarS {%
  \RestoreCS\fileinfo \RestoreCS\fileversion
  \RestoreCS\filedate \RestoreCS\docdate
  \RestoreCS\DoXPackageS
  \RestorECitationS
}
\newcommand*\AddToCheckSum [1] {%
  \global\advance\check@sum #1%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\newprogram}
% \begin{macro}{\TMFontProgram}
% \begin{macro}{\TMHookProgram}
% \begin{macro}{\TMResetProgram}
%   Provide for program abbreviations.
%    \begin{macrocode}
\NewAbbrevCategory{Program}
\NewUserAbbrevDefiner{\newprogram}{Program}
\def\TMFontProgram {%
  \relsize{-1}\ttfamily
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
%  \begin{macro}{\BibTeX}
% The \BibTeX{} logo.
%    \begin{macrocode}
\providecommand\BibTeX {%
  {\rmfamily B\kern-.05em{\scshape i\kern-.025em b}\kern-.08em
    T\kern-.1667em\raisebox{-.7ex}{E}\kern-.125emX}%
}
%    \end{macrocode}
%  \end{macro}
%
% \part{Configuration}
%
% Other things are deferred to a configuration file.
%    \begin{macrocode}
\InputIfFileExists{compsci.cfg}{}{}
%    \end{macrocode}
%
%  The contents of the distributed configuration file are below.
%
% \InputIfFileExists{compsci.cfg}{}{}
%
% \Finale
