%^^A* copyright
% \iffalse
%
%   This program is part of the Frankenstein bundle for LaTeX2e.
%
%   Copyright (C) 1995, 1996 Matt Swift <swift@bu.edu>
%
%   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.
%
%   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.
%
%   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.
%
%      NOTE:  I am willing to specially license this code.
%             Please simply contact me with your proposal.
%
%^^A   NOTE:  \DocInput will start reading after this \fi:
% \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{436}
%
% \begin{abstract}
%   The \package{compsci} package provides \LaTeX{} macros for writing about
%   \LaTeX{} macros.  Most often this package will be used to supplement the
%   \class{ltxdoc} class, but it can be used with other classes.
%
%   In this initial version, there are a few cosmetic bugs, some minor bugs,
%   and some features break if you are not using the \class{ltxdoc} class.
% \end{abstract}
%
% \part{Discussion}
%
% \section{Textual elements}
%
% \DescribeMacro{\word}
%   \cs\word\marg{word} is used to typeset a word referred to as a word.  For
%   example, \word{Elephant} is such a silly word.
%
% \DescribeMacro{\term}
%    \cs\term\marg{technical term} typesets the a techincal term in a different
%    font.  You might want to use this where a techincal term is first used, or
%    defined.  For example, This sort of thing is called a \term{blibnil}.
%
% \DescribeMacro{\defn}
%   \cs\defn\marg{definition} typesets a definition, perhaps of a technical
%   term.  We may describe a \term{blibnil} as \defn{a slibnil with three
%   arms}.
%
% \DescribeMacro{\env}
%   \cs\env\marg{environment name} typesets the name of a \LaTeX{} environment.
%    For example, the \env{enumerate} environment.
%
% \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}.
%
% \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 a 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{|}
%   typesets short pieces of code verbatim.  Instead of matching curly braces,
%   any character may be used to contain the \meta{verbatim} after the \cs\code
%   command.  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 $
%
%   \todo{Implement \cname{code*}.  Like \cname{verb*}, \cname{code*} marks
%   spaces explicitly.}  ^^A FIX
% \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}
%     Example of \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\)  {}{{{!#@$%^&\^^A for emacs $
%   There is a percent sign in the source after the $.^^A for emacs $
%   \end{codeexample}
%
%   \begin{codeexample*}
%   This is a \env{codexample*} environment: \(\int e^x\,dx\)  {}{{{!#@$%^&\^^A for emacs $
%   Someday I would like to get rid of the the leading spaces in a line.
%   \end{codeexample*}
%
%   \begin{codeexamplex}
%   This is a \env{codeexamplex} environment:  \(\int e^x\,dx\)  {}{{{}}}!#@$%^&\\^^A for emacs $
%   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 \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.
%
%   \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}
%
%   \begin{warning}
%     The |%| character is entirely ignored inside \env{bothexample} environments.
%     Don't count on them.  This is a bug.
%   \end{warning}  ^^A FIX
%
%   The \env{bothexample} and \env{splitexample} environments use an auxiliary
%   file with extension \ext{vrb}, but a second pass with \LaTeX{} is not
%   necessary.
% 
%   \begin{todoenv}
%     Get the annoying initial \verb*|%   | out of
%     the beginning of \env{bothexample}.
%   \end{todoenv} ^^A FIX
% 
%   \todo {Implement \env{splitexample} and \env{splitexample*}.} ^^A FIX
%
%   \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 {Get these environments to ignore leading spaces on a line, and
%          handle \emph{all} percent signs properly.} ^^A FIX
%
%   \todo {Implement \env{codeexamplex*}.} ^^A FIX
%
% \DescribeMacro{\url}
% \DescribeMacro{\email}
% \DescribeMacro{\path}
%   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.  
%
%   \begin{todoenv}
%     Surround an |email| with |<| and |>|.
%   \end{todoenv}  ^^A FIX
%
% \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{\booktitle}
%   The \package{compsci} package uses the \package{titles} package, so several
%   commands like \cs\booktitle 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
%   for 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, 
%   \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.
%
% \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{\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}{\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\DoXNeeDME{}
\def\fileversion{v0.92 (beta)}
\def\filedate{1996/10/04}
\def\docdate{1996/10/04}
\edef\PPOptArg {%
  \filedate\space \fileversion\space \fileinfo
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
% Stop right here if we're just loading the file's information, and don't want
% to load this code for typesetting its documentation (only makes sense for
% certain packages).  The |JuStLaAdInFoRmAtIoN| flag will be set by the
% documentation driver; the |DoXNeeDME| flag will be set in the
% \ext{dtx} file, and will appear above if it's set.
%    \begin{macrocode}
\makeatletter
\@ifundefined{JuStLoAdInFoRmAtIoN} {%
  }{% ELSE
  \@ifundefined{DoXNeeDME} {%
    }{% ELSE
    \UndefineCS\JuStLoAdInFoRmAtIoN
    \usepackage{compsci}%
  }
  \makeatother
  \endinput
}
%    \end{macrocode}
%
% Now we check for \LaTeX2e and declare the package.
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{compsci}[\PPOptArg]
%    \end{macrocode}
%
% ^^A NOTE: We have to compensate for the above backslashes, which are not
% ^^A actually in the doctex file I work on.
%%
% \AddToCheckSum{26}
% 
% \makeatletter
%   \@ifundefined{DoXNeeDME} {} {\AddToCheckSum{2}}
% \makeatother
% 
%
% \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,moreverb,relsize,shortvrb,%
                slemph,titles,url,verbatim}
\@ifclassloaded{ltxdoc}{%
  }{% ELSE
\MonsterWarning{compsci}
  {You may encounter errors with this version of the compsci package \MessageBreak
   since you are not using the ltxdoc class. \MessageBreak
   This will be fixed in a future version.}%
}
%    \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.}  ^^A FIX
%    \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{warning}
%   All the verbatim-like environments below are hacked and queer.  I have been
%   meaning to become a \env{verbatim} expert for a long time, but I am not
%   even close yet.
%
%   What needs to be done is to create the equivalent of \cname{@docverbatim}
%   above but using the new \package{verbatim} package.  Then both the
%   \env{codeexamplex} environment and the \env{bothexample} environments could
%   use this when writing out the \ext{vrb} file of their contents.  Then we
%   can treat all the |%|s in the \ext{vrb} file the same, that is either
%   print or obey them.
% \end{warning}
%
% \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{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.
%    \begin{macrocode}
\newenvironment{codeexamplex} {%
    \alltt
    \def\\{\char`\\}\catcode`\%=9\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}{\@verbatimtabinput}
%   First we want to redefine \cname{@verbatimtabinput} so that it ignores
%   |%|s.  Once again, we should like to print |%|s that are not in the first
%   column, but this implementation ignores them all. ^^A FIX
%    \begin{macrocode}
{\catcode`\~=\active \lccode`\~=`\^^M \lccode`\N=`\N
 \lowercase{%
  \gdef\@verbatimtabinput[#1]#2{\begingroup
     \do@verbatimtab{#1}{%
       \@verbatim\frenchspacing\@vobeyspaces\@vobeytabs}%
     \def\verbatim@addtoline##1~{%
        \verbatim@line\expandafter{\the\verbatim@line##1}}%
     \openin\verbatim@in@stream=#2
     \ifeof\verbatim@in@stream\typeout{No file #2.}\else
       \verbtab@oktrue
       \catcode`\%=9
       \loop
          \read\verbatim@in@stream to \verbtab@line
          \ifeof\verbatim@in@stream\verbtab@okfalse\else
             \expandafter\verbatim@addtoline\verbtab@line
             \verbatim@processline
             \verbatim@startline
          \fi
       \ifverbtab@ok\repeat
       \closein\verbatim@in@stream\fi
     \endtrivlist\endgroup\@doendpe}}}
%    \end{macrocode}
% \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.
%    \begin{macrocode}
\newenvironment{bothexample} {%
    \par
    \begingroup
    \verbatimwrite{\jobname.vrb}%
  }{%
  \endverbatimwrite
  \verbatimtabinput{\jobname.vrb}%
  \endgroup
  \par
%    \end{macrocode}
% We compensate here for the extra line caused by the final newline above.
%    \begin{macrocode}
  \addvspace{-\baselineskip}%
  \noindent{\sffamily\large LOOKS LIKE:}%
  \par\smallskip
  \noindent\fbox{%
    \minipage{\textwidth}
    \DocInput{\jobname.vrb}%  ^^A FIX DocInput not defined
    \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] {%
  \gogog{#1}\endgogog
  \codeexample
  }{%
  \endcodeexample
  \par\smallskip
  \noindent\fbox{%
    \minipage{\textwidth}
    \catcode`\%=9
    \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}{\word}
% \begin{macro}{\term}
% \begin{macro}{\defn}
% \begin{macro}{\env}
% \begin{macro}{\option}
% \begin{macro}{\package}
% \begin{macro}{\program}
% \begin{macro}{\class}
% \begin{macro}{\file}
% \begin{macro}{\bst}
% \begin{macro}{\ext}
% \begin{macro}{\email}
% \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 \cat     \sffamily      % name of a category
\NewTextFontCommand \class   \slshape       % name of LaTeX class
\newlet             \defn    \textslswitch  % definition
\requirecommand     \email   {\url}         % email address
\NewTextFontCommand \env     \ttfamily      % name of environment
\NewTextFontCommand \ext     \ttfamily      % name of file extension
\requirecommand     \file    {\url}         % name of disk file
\NewTextFontCommand \option  \ttfamily      % name of package or class option
\NewTextFontCommand \package \slshape       % name of LaTeX package
\newlet             \term    \textslswitch  % technical term
\newlet             \typeset \fbox          % text as it appears when typeset
\newlet             \word    \textitswitch  % refer to a word as a word
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \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\def\\{\char`\\}\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}
\DeclareRobustCommand*\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}{\AddToCheckSum}
%   See the version control section above for an example of when you might want
%   to use these commands.  
%%
% ^^A FIX Add ltxdoc check for addtochecksum?
%    \begin{macrocode}
\def\partname {%
  Part%
}
\newcommand*\ProcessDTXFile [1] {%
  \InitCS\JuStLoAdInFoRmAtIoN
  \def\filename {#1}%
  \UndefineCS\DoXNeeDME
  \input{#1}%
  \UndefineCS\JuStLoAdInFoRmAtIoN
}
\newcommand*\AddToCheckSum [1] {%
  \global\advance\check@sum #1%
}
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%  \end{macro}
%
% \begin{macro}{\newprogram}
% \begin{macro}{\TMFontProgram}
% \begin{macro}{\TMHookProgram}
% \begin{macro}{\TMResetProgram}
%   Provide for program abbreviations.
%    \begin{macrocode}
\TMNewCategory{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}
%
% \section{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