source: Backup NB/Talks/MEMPHYSetal/LAGUNA/EU I3/PhysicsLatex/revtex4/revtex4/src/ltxdocext.dtx @ 416

% \iffalse &pdflatex ltxdoc klootch
% ltxdocext.dtx: package to extend the ltxdoc class of standard LaTeX
% Copyright (c) 1999 Arthur Ogawa
%
% Disclaimer
%   This file is distributed WITHOUT ANY WARRANTY;
%   without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
% ReadMe
%   For the documentation and more detailed instructions for
%   installation, typeset this document with \LaTeX.
% \fi
% \CheckSum{938}
%% \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         \~}%
%
% \iffalse ltxdoc klootch
%%%  @LaTeX-file{
%%%     filename        = "ltxdocext.dtx",
%%%     version         = "0.0a0",
%%%     date            = "1999/06/04",
%%%     time            = "11:23:00 GMT",
%%%     checksum        = "929",
%%%     author          = "Arthur Ogawa (mailto:ogawa@teleport.com)",
%%%     copyright       = "Copyright (C) 1999 Arthur Ogawa,
%%%                        all rights reserved.  Copying of this file is
%%%                        authorized only if either:
%%%                        (1) you make absolutely no changes to your copy,
%%%                        including name; OR
%%%                        (2) if you do make changes, you first rename it
%%%                        to some other name.",
%%%     address         = "Arthur Ogawa,
%%%                        USA",
%%%     telephone       = "",
%%%     FAX             = "",
%%%     email           = "ogawa@teleport.com",
%%%     codetable       = "ISO/ASCII",
%%%     keywords        = "latex, ltxdoc",
%%%     supported       = "yes",
%%%     abstract        = "extensions to the ltxdoc class",
%%%     docstring       = "The checksum field above generated by ltxdoc",
%%%  }
% \fi
%
% \iffalse ltxdoc klootch
% The following references the \file{00readme.txt} file,
% which contains basic information about this package.
% The contents of this file are generated when
% you typeset the programmer's documentation.
% Search on "{filecontents*}{00readme.txt}" to locate it.
% \fi\input{00readme.txt}%
%
% \subsection{Bill of Materials}
%
% Following is a list of the files in this distribution arranged
% according to provenance.
%
% \subsubsection{Primary Source}%
% One single file generates all.
%\begin{verbatim}
%ltxdocext.dtx
%\end{verbatim}
%
% \subsubsection{Generated by \texttt{latex ltxdocext.dtx}}%
% Typesetting the source file under \LaTeX\
% generates the readme and the installer.
%\begin{verbatim}
%00readme.txt   ltxdocext.ins
%\end{verbatim}
%
% \subsubsection{Generated by \texttt{tex ltxdocext.ins}}%
% Typesetting the installer generates
% the package files.
%\begin{verbatim}
%ltxdocext.sty    acrofont.sty
%\end{verbatim}
%
% \subsubsection{Documentation}%
% The following are the online documentation:
% \begin{verbatim}
%ltxdocext.pdf
% \end{verbatim}
%
% \subsubsection{Auxiliary}%
% The following are auxiliary files generated
% in the course of running \LaTeX:
% \begin{verbatim}
%ltxdocext.aux ltxdocext.idx ltxdocext.ind ltxdocext.log ltxdocext.toc
% \end{verbatim}
%
% \section{Code common to all modules}%
%
% The following may look a bit klootchy, but we
% want to require only one place in this file
% where the version number is stated,
% and we also want to ensure that the version
% number is embedded into every generated file.
%
% Now we declare that
% these files can only be used with \LaTeXe.
% An appropriate message is displayed if
% a different \TeX{} format is used.
%    \begin{macrocode}
%<*doc|extensions|fonts>
\NeedsTeXFormat{LaTeX2e}[1995/12/01]%
%</doc|extensions|fonts>
%    \end{macrocode}
% As desired, the following modules all
% take common version information:
%    \begin{macrocode}
%<extensions>\ProvidesFile{ltxdocext.sty}%
%<fonts>\ProvidesFile{acrofont.sty}%
%<*doc>
\expandafter\ProvidesFile\expandafter{\jobname.dtx}%
%</doc>
%    \end{macrocode}
%
% The following line contains, for once and for all,
% the version and date information.
% By various means, this information is reproduced
% consistently in all generated files and in the
% typeset documentation.
%    \begin{macrocode}
 [1999/06/04 0.0a0 ltxdoc extensions package]% \fileversion
%    \end{macrocode}
%
%
% \section{The driver module \texttt{doc}}
%
% This module, consisting of the present section,
% typesets the programmer's documentation,
% generating the \file{.ins} installer and \file{00readme.txt} as required.
%
% Because the only uncommented-out lines of code at the beginning of
% this file constitute the \file{doc} module itself,
% we can simply typeset the \file{.dtx} file directly,
% and there is thus rarely any need to
% generate the ``doc'' {\sc docstrip} module.
% Module delimiters are nonetheless required so that
% this code does not find its way into the other modules.
%
% The \enve{document} command concludes the typesetting run.
%
%    \begin{macrocode}
%<*doc>
%    \end{macrocode}
%
% \subsection{Stubs for \file{ltxdocext.sty} and \file{acrofont.sty}}
%
% This \env{filecontents} environment generates stub files
% \file{ltxdocext.sty} and \file{acrofont.sty}.
% Stubs are needed because the documentation for this package 
% requires them and they might not yet be present.
%
% A real version of these files will be generated 
% when you typeset \file{ltxdocext.ins}, at which point
% the stub file will be overwritten (you will have to give {\sc docstrip} 
% permission to do this).
%    \begin{macrocode}
\begin{filecontents}{ltxdocext.sty}
% Stub version of ltxdocext.sty
\end{filecontents}
\begin{filecontents}{acrofont.sty}
% Stub version of acrofont.sty
\end{filecontents}
%    \end{macrocode}
%
% \subsection{The Preamble}
% The programmers documentation is formatted
% with the \classname{ltxdoc} class with local customizations,
% and with the usual code line indexing.
%    \begin{macrocode}
\documentclass[draft]{ltxdoc}
\RequirePackage{ltxdocext}%
\RequirePackage{acrofont}%
\CodelineIndex\EnableCrossrefs
%    \end{macrocode}
%
% \subsubsection{Docstrip and info directives}
%    We use so many {\sc docstrip} modules that we set the
%    \texttt{StandardModuleDepth} counter to 1.
%    \begin{macrocode}
\setcounter{StandardModuleDepth}{1}
%    \end{macrocode}
%    The following command retrieves the date and version information
%    from this file.
%    \begin{macrocode}
\expandafter\GetFileInfo\expandafter{\jobname.dtx}%
%    \end{macrocode}
%
%
% \subsection{The installer file}
%
% The installer \file{ltxdocext.ins} appears here.
% If you have retrieved the standard distribution of this package,
% the installer file is already on your filesystem.
% If you are bootstrapping,
% the first typesetting of the \file{.dtx} file
% will cause the installer to be generated.
%
% The following modules are used to direct
% {\sc docstrip} in generating the external files:
% \begin{center}
% \begin{tabular}{lll}
%   \textbf{Module}&\textbf{File}&\textbf{Description}\\
%   doc       &\file{ltxdocext.drv}&driver for programmer's documantation\\
%   extensions&\file{ltxdocext.sty}&ltxdoc extensions package\\
%   fonts     &\file{acrofont.sty} &package to use only Acrobat fonts
% \end{tabular}
% \end{center}
%
%    \begin{macrocode}
\begin{filecontents}{ltxdocext.ins}
%% This file will generate documentation and runtime files
%% from ltxdocext.dtx when run through LaTeX or TeX.
\input docstrip
\preamble

This is a generated file;
altering it directly is inadvisable;
instead, modify the original source file.
See the URL in the file 00readme.txt.

Copyright notice.

   These files are distributed
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

\endpreamble
\keepsilent
  \generate{%
   \file{ltxdocext.drv}{\from{ltxdocext.dtx}{doc}}%
   \file{ltxdocext.sty}{\from{ltxdocext.dtx}{extensions}}%
   \file{acrofont.sty}{\from{ltxdocext.dtx}{fonts}}%
  }%
\ifToplevel{
\Msg{***********************************************************}
\Msg{*}
\Msg{* To finish the installation, please move}
\Msg{*    ltxdocext.sty}
\Msg{* into a directory searched by TeX.}
\Msg{*}
\Msg{* To produce the user documentation,
       run ltxdocext.tex through LaTeX.}
\Msg{*}
\Msg{* To produce the programmer documentation,
       run ltxdocext.dtx through LaTeX.}
\Msg{*}
\Msg{* Happy TeXing}
\Msg{***********************************************************}
}
\endbatchfile
\end{filecontents}
%    \end{macrocode}
% Note that, because all of the files generated by the installer
% are part of the standard distribution, it will
% be necessary to run the installer only when bootstrapping
% (or, of course, during development).
% Note, too, that it is rare to generate the \file{doc}
% module because it suffices to simply typeset the \file{.dtx} file itself.
%
% \subsection{The ``Read Me'' File}
% As promised above, here is the contents of the
% ``Read Me'' file. That file serves a double purpose,
% since it also constitutes the beginining of the
% programmer's documentation. What better thing, after
% all, to have appear at the beginning of the
% typeset documentation?
%
% A good discussion of how to write a ReadMe file can be found in
% Engst, Tonya, ``Writing a ReadMe File? Read This''
% \emph{MacTech} October 1998, p. 58.
%
% Note the appearance of the
% \cmd\StopEventually\ command, which marks the
% dividing line between the user documentation
% and the programmer documentation.
%
% The usual user will not be asked to
% do a full build, not to speak
% of the bootstrap.
% Instructions for carrying these processes
% begin the programmer's manual.
%
%    \begin{macrocode}
\begin{filecontents*}{00readme.txt}
\title{%
 Extensions to the \classname{ltxdoc} class%
 \thanks{%
  This file has version number \fileversion,
  last revised \filedate.%
  % For version number and date, search on "\fileversion" in the .dtx file,
  % or see the end of the 00readme.txt file.
 }%
}%

\author{%
Arthur Ogawa (\texttt{mailto:ogawa@teleport.com}),
\fileversion\\Copyright (C) 1999 Arthur Ogawa
}%
\maketitle

This file embodies the \classname{ltxdocext} package,
the implementation and its user documentation.

The distribution point for this work is
\url{ftp://ftp.teleport.com/users/ogawa/macros/latex/contrib/supported/ltxdocext...},
which contains fully unpacked, prebuilt runtime files and documentation.

To use this document class, you must have a working
\TeX\ installation equipped with \LaTeXe\ 
and possibly pdftex and Adobe Acrobat Reader or equivalent.

To install, retrieve the distribution,
unpack it into a directory on the target computer,
and move the files \file{ltxdocext.sty} and \file{acrofont.sty}
into a location in your filesystem where they will be found by \LaTeX.

If you will be using the \classname{acrofont} package, you must
also install the virtual fonts
\file{zpsynocmrv}, \file{zptmnocmr},
\file{zptmnocmrm}, and \file{zpzcnocmry}.
The corresponding \file{.tfm}, \file{.vf}, and \file{.vpl}
files are part of this distribution.

To use, read the user documentation \file{ltxdocext.pdf}.
The \file{.dtx} file, \file{ltxdocext.dtx}, constitutes
in itself an instance of use of the \classname{ltxdocext}
package and the \classname{acrofont} package.

\tableofcontents

\section{Processing Instructions}

The package files \file{ltxdocext.sty} and \file{acrofont.sty}
are generated from this file, \file{ltxdocext.dtx},
via the {\sc docstrip} facility of \LaTeX
via |tex ltxdocext.ins|.
The typeset documentation that you are now reading is generated from
the same file by typesetting it with \LaTeX\ or pdftex
via |latex ltxdocext.dtx| or |pdflatex ltxdocext.dtx|.

\subsection{Build Instructions}

You may bootstrap this suite of files solely from \file{ltxdocext.dtx}.
Prepare by installing \LaTeXe\ (and either tex or pdftex) on your computer,
then carry out the following steps:
\begin{enumerate}
\item
Within an otherwise empty directory,
typeset \file{ltxdocext.dtx} with \LaTeX\ or pdflatex;
you will obtain the typeset documentation you are now reading,
along with
the installer \file{ltxdocext.ins},
and the file \file{00readme.txt}.
\item
Now typeset \file{ltxdocext.ins},
thereby generating the package file \file{ltxdocext.sty},
and the package file \file{acrofont.sty}.
Make sure that {\sc docstrip} receives permission
to overwrite existing versions of these packages.
\item
Install \classname{ltxdocext.sty} and \classname{acrofont.sty}
by moving them to a location
in your filesystem where they will be found by \LaTeX.
\item
Now complete the typesetting of the documentation by 
retypesetting \file{ltxdocext.dtx}.
Note: you will have to run \LaTeX\ twice, then \file{makeindex}, then
\LaTeX\ again in order to obtain a valid index and table of contents.
\end{enumerate}
\end{filecontents*}
%    \end{macrocode}
%
% \subsection{The Document Body}
%
% Here is the document body, containing only a
% \cmd\DocInput\ directive---referring to this very file.
% This very cute self-reference is a common \classname{ltxdoc} idiom.
%    \begin{macrocode}
\begin{document}%
\expandafter\DocInput\expandafter{\jobname.dtx}%
% ^^A\PrintChanges
\end{document}
%    \end{macrocode}
%
%    \begin{macrocode}
%</doc>
%    \end{macrocode}
%
% \section{Using the \classname{ltxdoc} and \classname{acrofont} packages}%
% These packages are an adjunct to the 
% standard \LaTeX\ \classname{ltxdoc} class and may be 
% simply invoked as follows:
%\begin{verbatim}
%\documentclass[draft]{ltxdoc}
%\RequirePackage{ltxdocext}%
%\RequirePackage{acrofont}%
%\CodelineIndex\EnableCrossrefs
%\end{verbatim}
%
% Your document should simply cleave to the standards of the
% \classname{ltxdoc} class, with extensions and alterations as noted.
%
% \subsection{Extensions to the \classname{ltxdoc} class}%
%
% \subsubsection{Extensions to the \env{verbatim} environment and \cs{verb} command}%
%
% The delimiters \verb$<<$ and \verb$>>$ within the scope of the verbatim environment
% or within the argument of the \cmd\verb\ command produce
% italics surrounded by angle brackets.
% This typographic convention usually indicates 
% \emph{metalanguage}, i.e., a placeholder.
%
% To obtain the angle bracket character per se, 
% double the character, viz., ``\verb$the delimiter \verb+<<<<+$''.
%
% \subsubsection{The -\texttt{matter} Commands Work}
% The sectioning commands \cmd\frontmatter, \cmd\mainmatter, and \cmd\backmatter
% of the standard \LaTeX\ \classname{book} class are operative in the
% \classname{ltxdoc} class.
%
% \subsubsection{The \cs{GetFileInfo} command}\label{sec:GetFileInfo}
% You can use the \cmd\GetFileInfo\ command to extract 
% the date, version, and file info of a file which has registered itself
% via the \cmd\ProvidesFile\ or \cmd\ProvidesClass\ command 
% (employing the optional argument thereto).
% 
% For instance, if your document contains the following:
%\begin{verbatim}
%\RequirePackage{ltxdocext}%
%\GetFileInfo{ltxdocext.sty}%
%\end{verbatim}
% then the following control sequence names will have 
% a value corresponding to that package's \cmd\ProvidesFile\
% command: 
% \cmd\filedate: the file's date,
% \cmd\fileversion: the file's version, and
% \cmd\fileinfo: the file's info.
%
% \subsubsection{Self-Indexing Commands}%
% Certain commands automatically produce an index entry
% (or several related entries) according to the meaning.
%
% \begin{unnumtable}
% \begin{tabular}{ll}
% meta-text         &\cmd\m\arg{text}\\
% command           &\cmd\cmd\cmd\csname\\
% environment name  &\cmd\env\arg{name}\\
% \cmd\begin\verb`{foo}`&\cmd\envb\arg{foo}\\
% \cmd\end\verb`{foo}`  &\cmd\enve\arg{foo}\\
% argument          &\cmd\arg\arg{name}\\
% optional          &\cmd\oarg\arg{name}\\
% filename          &\cmd\file\arg{name}\\
% url               &\cmd\url\arg{name}\\
% document class    &\cmd\classname\arg{name}\\
% document substyle &\cmd\substyle\arg{name}\\
% class option      &\cmd\classoption\arg{name}
% \end{tabular}
% \end{unnumtable}
%
% \subsubsection{Unnumbered Tables}%
%
% When your documentation requires the use of an unnumbered table,
% use the \env{unnumtable} environment:
% \begin{verbatim}
%\begin{unnumtable}
%\begin{tabular}{ll}
%<table rows>
%\end{tabular}
%\end{unnumtable}
% \end{verbatim}
%
% \subsubsection{Structuring Tables}%
% The commands \cmd\toprule, \cmd\colrule, and \cmd\botrule
% allow you to mark the beginning of the column heads
% the beginning of the table body, and the end of
% the table body, respectively.
% In context, 
% \begin{verbatim}
%\begin{tabular}{ll}
%\toprule
%<table head rows>
%\colrule
%<table rows>
%\botrule
%\end{tabular}
% \end{verbatim}
%
% \subsubsection{A Sectioning Command Below \cs{subsection}}%
% The \cmd\subsubsection\ command is defined.
%
%
% \subsection{Alterations to the \classname{ltxdoc} class}%
% The following involve no new markup, but they 
% do change the appearance of your formatted documentation:
% \begin{enumerate}
% \item
% Using the \classname{acrofont} package causes your 
% document to be formatted using the standard 
% Acrobat fonts to the greatest extent possible.
% This means that for most documents, Computer Modern
% is not used at all.
% Math that unavoidable must use CM still exists, however.
% \item
% An index will be produced at the end of the document
% without your needing to explicitly mark it up, and
% it will have an entry in the TOC.
% \item
% The \env{quote} environment has a slightly smaller left margin.
% \item
% Array columns are set tight by default.
% \item
% A host of \cmd\DoNotIndex\ directives are invoked.
% I intend this list to grow to encompass 
% even more commands. Send me your suggestions.
% \end{enumerate}
%
%
%
%\StopEventually{}
%
% \section{Extensions to the ltxdoc class}
% The \file{extensions} {\sc docstrip} module comprises the 
% package \classname{ltxdocext.sty}, which provides extensions
% to the standard \LaTeX\ \classname{ltxdoc} class.
%
% \subsection{Beginning of the \file{extensions} {\sc docstrip} module}
%    \begin{macrocode}
%<*extensions>
\def\class@name{ltxdocext}%
\expandafter\PackageInfo\expandafter{\class@name}{%
 An extension to the \protect\LaTeXe\space ltxdoc class
 by A. Ogawa (ogawa@teleport.com)%
}%
%    \end{macrocode}
%
% \subsection{Incorporate \classname{ltxguide.cls} extensions}
%
% Code extracted from \classname{ltxguide.cls}, by Alan Jeffrey.
% ``This code stolen from \classname{ltxguide.cls}:
% Some hacks with verbatim... NB: this would be better done with the
% verbatim package, but this document has to run on any \LaTeX
% installation.''
%    \begin{macrocode}
\RequirePackage{verbatim}%
\let\o@verbatim\verbatim
\def\verbatim{%
  \ifhmode\unskip\par\fi
% \nopagebreak              % Overridden by list penalty
  \ifx\@currsize\normalsize
     \small
  \fi
  \o@verbatim
}%
%    \end{macrocode}
%
% Here we extend the font-setting command to include making \texttt{<>} active
% (i.e., adjusting the input encoding).
%    \begin{macrocode}
\renewcommand \verbatim@font {%
  \normalfont \ttfamily
  \catcode`\<=\active
  \catcode`\>=\active
}%
%    \end{macrocode}
%
% Make \verb$|...|$ a synonym for \cmd\verb\verb$|...|$.
%    \begin{macrocode}
\RequirePackage{shortvrb}
\AtBeginDocument{%
 \MakeShortVerb{\|}%
}%
%    \end{macrocode}
%
% Make active bracket characters produce italics surrounded by angle brackets
% (used in \env{verbatim} and \cmd\verb).
% \verb|<<| produces a less-than, and \verb|>>| produces a greater-than.
%    \begin{macrocode}
\begingroup
  \catcode`\<=\active
  \catcode`\>=\active
  \gdef<{\@ifnextchar<\@lt\@meta}
  \gdef>{\@ifnextchar>\@gt\@gtr@err}
  \gdef\@meta#1>{\m{#1}}
  \gdef\@lt<{\char`\<}
  \gdef\@gt>{\char`\>}
\endgroup
\def\@gtr@err{%
   \ClassError{ltxguide}{%
      Isolated \protect>%
   }{%
      In this document class, \protect<...\protect>
      is used to indicate a parameter.\MessageBreak
      I've just found a \protect> on its own.
      Perhaps you meant to type \protect>\protect>?
   }%
}
\def\verbatim@nolig@list{\do\`\do\,\do\'\do\-}
%    \end{macrocode}
% End of code stolen from \file{ltxguide.cls}. Thanks, Alan.
%
% Add functionality from doc.dtx:
% (code stolen from doc.dtx):
%    \begin{macrocode}
\def\GetFileInfo#1{%
  \def\filename{#1}%
  \def\@tempb##1 ##2 ##3\relax##4\relax{%
    \def\filedate{##1}%
    \def\fileversion{##2}%
    \def\fileinfo{##3}}%
  \edef\@tempa{\csname ver@#1\endcsname}%
  \expandafter\@tempb\@tempa\relax? ? \relax\relax}
%    \end{macrocode}
% (end of code stolen from doc.dtx. Thanks FMi.)
%
% Various forms of self-indexing commands:
%    \begin{macrocode}
\DeclareRobustCommand{\m}[1]{%
 \meta{#1}%
 \index{#1=\string\meta{#1} placeholder}\index{placeholder>#1=\string\meta{#1}}%
}%
\DeclareRobustCommand\meta[1]{%
 \mbox{\LANGLE\itshape#1\/\RANGLE}%
}%
\def\LANGLE{$\langle$}%
\def\RANGLE{$\rangle$}%
\DeclareRobustCommand{\arg}[1]{%
 {\ttfamily\string{}\meta{#1}{\ttfamily\string}}%
 \index{#1=\string\ttt{#1}, argument}\index{argument>#1=\string\ttt{#1}}%
}%
\let\oarg\undefined
\DeclareRobustCommand{\oarg}[1]{%
 {\ttfamily[%]
  }\meta{#1}{\ttfamily%[
 ]}%
 \index{#1=\string\ttt{#1}, optional argument}%
 \index{argument, optional>#1=\string\ttt{#1}}%
}%
\DeclareRobustCommand\cmd{\begingroup\makeatletter\@cmd}%
\def\@cmd#1{%
 \endgroup
 \cs{\expandafter\cmd@to@cs\string#1}%
 \expandafter\cmd@to@index\string#1\@nil
}%
\def\cmd@to@cs#1#2{\char\number`#2\relax}%
\def\cmd@to@index#1#2\@nil{%
 \index{#2=\string\cmd#1#2}%\index{command>#2=\string\cmd#1#2}%
}%
\DeclareRobustCommand\cs[1]{{\ttfamily\char`\\#1}}%
\def\scmd#1{%
 \cs{\expandafter\cmd@to@cs\string#1}%
 \expandafter\scmd@to@index\string#1\@nil
}%
\def\scmd@to@index#1#2\@nil#3{%
 \index{\string$#3=\string\cmd#1#2---#3}%
%\index{command>\string$#3=\string\cmd#1#2---#3}%
}%
\DeclareRobustCommand\env{\name@idx{environment}}%
\DeclareRobustCommand\envb[1]{%
 {\ttfamily\string\begin\string{}\env{#1}{\ttfamily\string}}%
}%
\DeclareRobustCommand\enve[1]{{\ttfamily\string\end\string{}\env{#1}{\ttfamily\string}}}%
\DeclareRobustCommand*{\file}[1]{%
 {\ttfamily#1}%
 \index{#1=\string\ttt{#1}}\index{file>#1=\string\ttt{#1}}%
}%
\DeclareRobustCommand\substyle{\name@idx{document substyle}}%
\DeclareRobustCommand\classoption{\name@idx{document class option}}%
\DeclareRobustCommand\classname{\name@idx{document class}}%
\def\name@idx#1#2{%
 {\ttfamily#2}%
 \index{#2\space#1=\string\ttt{#2}\space#1}\index{#1>#2=\string\ttt{#2}}%
}%
\DeclareRobustCommand\url@ltxdocext{\begingroup\catcode`\/\active\catcode`\.\active\catcode`\:\active\@url}%
\AtBeginDocument{%
 \ifx\url\undefined\let\url\url@ltxdocext\fi
}%
\def\@url#1{%
 \url@break{\ttfamily#1}%
 \url@char\edef\@tempa{#1=\string\url{#1}}%
 \expandafter\index\expandafter{\@tempa}%
 \expandafter\index\expandafter{\expandafter u\expandafter r\expandafter l\expandafter >\@tempa}%
 \endgroup
}%
{\catcode`\:\active\aftergroup\def\aftergroup:}{\active@colon}%
\def\colon@break{\colon@char\allowbreak}%
\def\colon@char{:}%
{\catcode`\/\active\aftergroup\def\aftergroup/}{\active@slash}%
\def\slash@break{\slash@char\allowbreak}%
\def\slash@char{/}%
{\catcode`\.\active\aftergroup\def\aftergroup.}{\active@dot}%
\def\dot@break{\dot@char\allowbreak}%
\def\dot@char{.}%
\def\url@break{\let\active@slash\slash@break\let\active@dot\dot@break\let\active@colon\colon@break}%
\def\url@char{\let\active@slash\slash@char\let\active@dot\dot@char\let\active@colon\colon@char}%
%    \end{macrocode}
%
% \subsection{Changes to the base class of the ltxdoc class}
% Modify \env{theindex} environment so that it produces a TOC entry
%    \begin{macrocode}
\renewenvironment{theindex}
               {\if@twocolumn
                  \@restonecolfalse
                \else
                  \@restonecoltrue
                \fi
                \columnseprule \z@
                \columnsep 35\p@
\def\see##1##2{\textit{See} ##1}%
\def\seealso##1##2{\textit{See also} ##1}%
\def\cmd##1{\cs{\expandafter\cmd@to@cs\string##1}}%
\def\@url##1{\url@break\ttt{##1}\endgroup}%
\def\ttt##1{{\ttfamily##1}}%
\mathchardef\save@secnumdepth\c@secnumdepth
\c@secnumdepth\m@ne
                \twocolumn[\section{\indexname}]%
%               \@mkboth{\MakeUppercase\indexname}%
%                       {\MakeUppercase\indexname}%
\c@secnumdepth\save@secnumdepth
                \thispagestyle{plain}\parindent\z@
                \parskip\z@ \@plus .3\p@\relax
                \let\item\@idxitem}
               {\if@restonecol\onecolumn\else\clearpage\fi}
\renewenvironment{quote}
               {\list{}{%
                \leftmargin1em\relax
                \rightmargin\leftmargin
                }%
                \item\relax}
               {\endlist}
%    \end{macrocode}
%
% \subsection{Extensions to the base class of \classname{ltxdoc.cls}}
%
% Matter commands from \classname{book.cls}
%    \begin{macrocode}
\newif\if@mainmatter
\newif\if@openright
\@openrighttrue
\DeclareRobustCommand\frontmatter{%
  \cleartorecto
  \@mainmatterfalse
  \pagenumbering{roman}%
}%
\DeclareRobustCommand\mainmatter{%
  \cleartorecto
  \@mainmattertrue
  \pagenumbering{arabic}%
}%
\DeclareRobustCommand\backmatter{%
  \if@openright
    \cleartorecto
  \else
    \clearpage
  \fi
  \@mainmatterfalse
}%
\ifx\undefined\cleartorecto
 \def\cleartorecto{\cleardoublepage}%
\fi
%    \end{macrocode}
%
% Unnumbered tables
%
% \begin{environment}{unnumtable}
% An unnumbered table does not float.
%    \begin{macrocode}
\def\@to{to}%
\newenvironment{unnumtable}{%
 \par
 \addpenalty\predisplaypenalty
 \addvspace\abovedisplayskip
 \hbox\@to\hsize\bgroup\hfil\ignorespaces
  \let\@Hline\@empty
}{%
 \unskip\hfil\egroup
 \penalty\postdisplaypenalty
 \vskip\belowdisplayskip
 \aftergroup\ignorespaces
 \@endpetrue
}%
%    \end{macrocode}
% \end{environment}
%
% Emulate \cmd\toprule\ and friends
%    \begin{macrocode}
\newcommand\toprule{\hline\hline}%
\newcommand\colrule{\\\hline}%
\newcommand\botrule{\\\hline\hline}%
%    \end{macrocode}
%
% Define sectioning command below \cmd\subsubsection.
%    \begin{macrocode}
\DeclareRobustCommand\subsubsubsection{%
 \@startsection{subsubsection}{4}%
  {\z@}{-15\p@\@plus-5\p@\@minus-2\p@}%
  {5\p@}{\normalfont\normalsize\itshape}%
}%
%    \end{macrocode}
%
% \subsection{In lieu of \file{ltxdoc.cfg}}
%    We don't want everything to appear in the index
%    \begin{macrocode}
\DoNotIndex{\',\.,\@M,\@@input,\@Alph,\@alph,\@addtoreset,\@arabic}
\DoNotIndex{\@badmath,\@centercr,\@cite}
\DoNotIndex{\@dotsep,\@empty,\@float,\@gobble,\@gobbletwo,\@ignoretrue}
\DoNotIndex{\@input,\@ixpt,\@m,\@minus,\@mkboth}
\DoNotIndex{\@ne,\@nil,\@nomath,\@plus,\roman,\@set@topoint}
\DoNotIndex{\@tempboxa,\@tempcnta,\@tempdima,\@tempdimb}
\DoNotIndex{\@tempswafalse,\@tempswatrue,\@viipt,\@viiipt,\@vipt}
\DoNotIndex{\@vpt,\@warning,\@xiipt,\@xipt,\@xivpt,\@xpt,\@xviipt}
\DoNotIndex{\@xxpt,\@xxvpt,\\,\ ,\addpenalty,\addtolength,\addvspace}
\DoNotIndex{\advance,\ast,\begin,\begingroup,\bfseries,\bgroup,\box}
\DoNotIndex{\bullet}
\DoNotIndex{\cdot,\cite,\CodelineIndex,\cr,\day,\DeclareOption}
\DoNotIndex{\def,\DisableCrossrefs,\divide,\DocInput,\documentclass}
\DoNotIndex{\DoNotIndex,\egroup,\ifdim,\else,\fi,\em,\endtrivlist}
\DoNotIndex{\EnableCrossrefs,\end,\end@dblfloat,\end@float,\endgroup}
\DoNotIndex{\endlist,\everycr,\everypar,\ExecuteOptions,\expandafter}
\DoNotIndex{\fbox}
\DoNotIndex{\filedate,\filename,\fileversion,\fontsize,\framebox,\gdef}
\DoNotIndex{\global,\halign,\hangindent,\hbox,\hfil,\hfill,\hrule}
\DoNotIndex{\hsize,\hskip,\hspace,\hss,\if@tempswa,\ifcase,\or,\fi,\fi}
\DoNotIndex{\ifhmode,\ifvmode,\ifnum,\iftrue,\ifx,\fi,\fi,\fi,\fi,\fi}
\DoNotIndex{\input}
\DoNotIndex{\jobname,\kern,\leavevmode,\let,\leftmark}
\DoNotIndex{\list,\llap,\long,\m@ne,\m@th,\mark,\markboth,\markright}
\DoNotIndex{\month,\newcommand,\newcounter,\newenvironment}
\DoNotIndex{\NeedsTeXFormat,\newdimen}
\DoNotIndex{\newlength,\newpage,\nobreak,\noindent,\null,\number}
\DoNotIndex{\numberline,\OldMakeindex,\OnlyDescription,\p@}
\DoNotIndex{\pagestyle,\par,\paragraph,\paragraphmark,\parfillskip}
\DoNotIndex{\penalty,\PrintChanges,\PrintIndex,\ProcessOptions}
\DoNotIndex{\protect,\ProvidesClass,\raggedbottom,\raggedright}
\DoNotIndex{\refstepcounter,\relax,\renewcommand}
\DoNotIndex{\rightmargin,\rightmark,\rightskip,\rlap,\rmfamily}
\DoNotIndex{\secdef,\selectfont,\setbox,\setcounter,\setlength}
\DoNotIndex{\settowidth,\sfcode,\skip,\sloppy,\slshape,\space}
\DoNotIndex{\symbol,\the,\trivlist,\typeout,\tw@,\undefined,\uppercase}
\DoNotIndex{\usecounter,\usefont,\usepackage,\vfil,\vfill,\viiipt}
\DoNotIndex{\viipt,\vipt,\vskip,\vspace}
\DoNotIndex{\wd,\xiipt,\year,\z@}
\DoNotIndex{\next}
%    \end{macrocode}
%
% Direct \classname{ltxdoc} to produce an index.
%    \begin{macrocode}
\AtEndDocument{\PrintIndex}%
%    \end{macrocode}
%
% \subsection{Extension to \LaTeX's \env{filecontents} Environment}
% We want to
% coax the version number into \env{filecontents}-generated files.
% Note that we expect \cmd\fileversion\ and \cmd\filedate\ to
% hold the needed information. For this to be the case,
% your document should execute the \cmd\GetFileInfo\ command
% (as documented in section~\ref{sec:GetFileInfo}) before
% any instances of \env{filecontents}.
%    \begin{macrocode}
\makeatletter
\def\endfilecontents{%
 \immediate\write\reserved@c{%
  \string\iffalse\space ltxdoc klootch^^J%
  \ifx\undefined\fileversion\else
  \ifx\undefined\filedate\else
  This file has version number \fileversion, last revised \filedate.%
  \fi\fi
  \string\fi
 }%
 \immediate\closeout\reserved@c
 \def\T##1##2##3{%
  \ifx##1\@undefined\else
    \@latex@warning@no@line{##2 has been converted to Blank ##3e}%
  \fi
 }%
 \T\L{Form Feed}{Lin}%
 \T\I{Tab}{Spac}%
 \immediate\write\@unused{}%
}%
\expandafter\let\csname endfilecontents*\endcsname\endfilecontents
\makeatother
%    \end{macrocode}
%
% Alter formatting in arrays; set them tight.
%    \begin{macrocode}
\setlength\arraycolsep{0pt}%
%    \end{macrocode}
%
% \subsection{End of the \file{extensions} {\sc docstrip} module}
% Here ends the module.
%    \begin{macrocode}
%</extensions>
%    \end{macrocode}
%
%
% \section{Font Package for Acrobat Compatability}%
% The package \classname{acrofont}
% substitutes Acrobat-standard fonts for Computer Modern where possible,
% even in math mode.
% Documents typeset with this package in effect will require as little
% downloaded font data as possible, but will not be exemplars of
% fine math typesetting.
%
% \subsection{Beginning of the \file{fonts} {\sc docstrip} module}
% The document class module comprises this and the next
% four sections.
% \begin{macro}{\class@base}
% We define in exactly one spot the base class.
% Typically that class will be one of \classname{book},
% \classname{article}, or \classname{report}.
% The base class effectively defines the use and the markup scheme
% of the class of documents to be handled by this class.
%
% This class is a variant of the standard \LaTeX\ book class:
% \url{ftp://ctan.tug.org/tex-archive/macros/latex/unpacked}.
%    \begin{macrocode}
%<*fonts>
\def\class@name{ltxdocext}%
\expandafter\ClassInfo\expandafter{\class@name}{%
 Written for \protect\LaTeXe\space
 by A. Ogawa (ogawa@teleport.com)%
}%
%    \end{macrocode}
% \end{macro}
%
% \subsection{Variants on psfonts packages}%
% The following uses \file{times.sty} from \url{/packages/psnfss/psfonts.dtx}
%    \begin{macrocode}
\RequirePackage{times}%
%    \end{macrocode}
%
% The following uses \file{mathptm.sty} from \url{/packages/psnfss/psfonts.dtx}
%    \begin{macrocode}
\RequirePackage{mathptm}%
%    \end{macrocode}
%
% The following is a customization of \file{ot1ptmcm.fd}.
% The virtual font referred to here \file{zptmnocmr} is 
% a variant of Sebastian Rahtz's \file{zptmcmr}, but with
% even more glyphs moved from CM to Acrobat-standard fonts.
%    \begin{macrocode}
\DeclareFontFamily{OT1}{ptmcm}{}
\DeclareFontShape{OT1}{ptmcm}{m}{n}{
   <-> zptmnocmr
}{}
\DeclareFontShape{OT1}{ptmcm}{l}{n}{<->ssub * ptmnocm/m/n}{}
%    \end{macrocode}
%
% The following is a customization of \file{omlptmcm.fd}
% The virtual font referred to here \file{zptmnocmrm} is 
% a variant of Sebastian Rahtz's \file{zptmcmrm}, but with
% even more glyphs moved from CM to Acrobat-standard fonts.
%    \begin{macrocode}
\DeclareFontFamily{OML}{ptmcm}{\skewchar \font =127}
\DeclareFontShape{OML}{ptmcm}{m}{it}{
   <-> zptmnocmrm
}{}
\DeclareFontShape{OML}{ptmcm}{l}{it}{<->ssub * ptmcm/m/it}{}
\DeclareFontShape{OML}{ptmcm}{m}{sl}{<->ssub * ptmcm/m/it}{}
\DeclareFontShape{OML}{ptmcm}{l}{sl}{<->ssub * ptmcm/m/sl}{}
%    \end{macrocode}
%
% The following is a customization of \file{omspzccm.fd}
% The virtual font referred to here \file{zpzcnocmry} is 
% a variant of Sebastian Rahtz's \file{zpzccmry}, but with
% even more glyphs moved from CM to Acrobat-standard fonts.
%    \begin{macrocode}
\DeclareFontFamily{OMS}{pzccm}{}
\DeclareFontShape{OMS}{pzccm}{m}{n}{
   <-> zpzcnocmry
}{}% cmsy10 Symbol Zapf Chancery Medium-Italic Times-Roman
\DeclareFontShape{OMS}{pzccm}{l}{n}{<->ssub * pzccm/m/n}{}
%    \end{macrocode}
%
% The following is a customization of \file{omxpsycm.fd}
% The virtual font referred to here \file{zpsynocmrv} is 
% a variant of Sebastian Rahtz's \file{zpsycmrv}, but with
% even more glyphs moved from CM to Acrobat-standard fonts.
%    \begin{macrocode}
\DeclareFontFamily{OMX}{psycm}{}
\DeclareFontShape{OMX}{psycm}{m}{n}{
   <-> zpsynocmrv
}{}
\DeclareFontShape{OMX}{psycm}{l}{n}{<->ssub * psycm/m/n}{}
%
\DeclareFontEncoding{8r}{}{}% from file: 8renc.def
\DeclareFontFamily{8r}{cmr}{\hyphenchar\font45 }% from file: 8rcmr.fd
\DeclareFontShape{8r}{cmr}{m}{n}{
 <-> cmr10
}{}
%    \end{macrocode}
%
% \subsection{Font definition files}%
%
% The following forces \LaTeX\ to do now what it would do anyway:
% load the `font definition' information for the fonts that we
% use. In this way, we prepare for faster processing through
% the \cmd\dump\ of a preformatted macro package that will not
% need to read in any packages or font definitions from disk.
%    \begin{macrocode}
\input{8rphv.fd}%
\input{8rptm.fd}%
\input{ot1phv.fd}%
\input{ot1ptm.fd}%
\input{t1ptm.fd}%
%    \end{macrocode}
%
% \subsection{More math substitutions}%
%
% The following definitions arrange to get certain glyphs from the
% text font instead of out of math pi fonts.
% In particular, the copyright and registered symbols
% are single glyphs instead of composites involving
% the big circle from the \file{cmsy} font.
%    \begin{macrocode}
 \def\eightRChar#1{{\def\encodingdefault{8r}\fontencoding\encodingdefault\selectfont\char"#1}}%
 \def\LANGLE{$<$}%{\eightRChar{8B}}%
 \def\RANGLE{$>$}%{\eightRChar{9B}}%
%\def\ASTER{\eightRChar{2A}}%
%\def\DAGGER{\eightRChar{86}}%
%\def\DDAGGER{\eightRChar{87}}%
 \def\BULLET{\eightRChar{95}}%
%\def\SECTION{\eightRChar{A7}}%
%\def\PARAGRAPH{\eightRChar{B6}}%
 \def\VERTBAR{\eightRChar{7C}}%
 \def\COPYRIGHT{\eightRChar{A9}}%
 \def\REGISTERED{\eightRChar{AE}}%
%    \end{macrocode}
%
%    \begin{macrocode}
 \def\textbar{\VERTBAR}%
 \def\textbullet{\BULLET}%
 \def\textcopyright{\COPYRIGHT}%
 \def\textregistered{\REGISTERED}%
%    \end{macrocode}
%
% I have removed \cmd\ensuremath\ from the following definition, and
% all commands like \cmd\mathsection have been converted to
% e.g., \cmd\textsection.
%    \begin{macrocode}
\def\@makefnmark{\@thefnmark}%
\def\@fnsymbol#1{{\ifcase#1\or *\or \dagger\or \ddagger\or
   \textsection\or \textparagraph\or \|\or **\or \dagger\dagger
   \or \ddagger\ddagger \else\@ctrerr\fi}}
%    \end{macrocode}
%
% \subsection{End of the \file{fonts} {\sc docstrip} module}
% Here ends the module.
%    \begin{macrocode}
%</fonts>
%    \end{macrocode}
%
%
% \section{Programming Conventions}%
% In writing the above code, I cleave to certain conventions, noted
% here.
% My goal in explaining them is to encourage others maintaining this
% body of code to consider following them as well.
% The benefits are twofold:
% Some of the coding conventions aim to avoid programming pitfalls;
% following them reduces maintenance costs.
% Others make the code easier to read; following these eases the
% process of understanding how the code works.
%
% And, for my part, I prefer to read code of this type.
%
% \subsection{Whitespace Conventions}%
% Exactly where code lines break and indent, and where additional
% whitespace is inserted is explained here.
% \begin{itemize}
% \item
% Each new macro definition or register assignment begins a new line.
% Therefore, \cmd\def, \cmd\newcommand, and their ilk will start in column
% 1.
% \item
% Code is indented one space for each level of nesting within braces
% \verb|{}|.
% \item
% Likewise, if possible, for \cmd\if\dots and matching \cmd\fi.
% \item
% However, the closing brace or \cmd\fi\ is outdented by one so that it
% falls
% at the same level of indentation as its matching brace or \cmd\if,
% and it appears alone on its line.
% \item
% Use of the |tab| character is deprecated
% (tabs are not standardized across all applications and operating
% systems).
% \item
% Lines of code are limited to 72 characters.
% I follow this convention mostly to ease the transmission of files
% via email (a deprecated practice) and to accomodate people with
% small monitors.
% But \classname{ltxdoc} output looks better with the shorter lines, too.
% \item
% Extraneous whitespace is avoided by using the comment character |%|.
% In most cases, if falling at the end of a line of code,
% a brace will be immediately followed by a comment character,
% as will the macro parameter |#1| and any one-letter control sequence,
% like |\\|.
% \end{itemize}
% These conventions taken together are illustrated by the following:
% \begin{verbatim}
%\def\prepdef#1#2{%
% \@ifxundefined#1{\toks@{}}{\toks@\expandafter{#1}}%
% \toks@ii{#2}%
% \edef#1{\the\toks@ii\the\toks@}%
%}%
% \end{verbatim}
% In the above, the definition of \cmd\prepdef\ would not fit on a single
% line,
% and required breaking. The first and last lines have matching braces,
% and are a the same level of indentation, with the last line containing
% a single brace.
%
% Each of the three intervening lines has balanced braces and is
% indented by one space. Each line that would otherwise end in a single
% brace character is terminated by a comment character.
%
% Some coders rely on the fact that a space character seen by \TeX's
% scanner while in vertical mode is a no-op.
% Be that as it may, I eliminate them unless actually intentional.
%
% \subsection{Conventions For Procedures}%
% Here are some of my preferences when writing procedures:
% \begin{itemize}
%
% \item
% I dislike defining a macro within another macro, especially when the
% pattern part is non-nil.
% You know, you are not saving much space in |mem| when you do this,
% right?
% You do save space in the hash table and the string pool, though.
% On the other hand, we are not dealing with small \TeX\ engines
% anymore; Team \LaTeX\ has made sure of this.
%
% \item
% If two or more macros have very similar replacement parts, consider
% layering.
%
% \item
% Macros may perform parsing, may maintain tokens or registers, or may
% set type (produce marks). I try to avoid combining the three functions
% in a single macro.
%
% \item
% When a procedure both does assignments and sets type, I try to have a
% clean separations between the two activities. Try to avoid:
% \begin{verbatim}
% \vskip10pt
% \parindent=0pt
% \leavevmode
% \end{verbatim}
%
% \item
% The Boolean calculus (cf. \cmd\@ifx)
% is very useful and produces code that executes nicely.
% Using it also helps avoid your having to debug problems where
% \cmd\if\dots\ and \cmd\fi\ are not properly balanced
% (a nightmare in case you didn't already experience it).
%
% \end{itemize}
%
% \subsection{Conventions For \LaTeX}%
% Team \LaTeX\ make certain recommendations in \file{clsguide.tex}.
% Ones that I particularly pay attention to are:
% \begin{itemize}
%
% \item
% For the sake of ``color safety'',
% use \cmd\sbox\ rather than \cmd\setbox, \cmd\mbox\ rather than \cmd\hbox, and
% \cmd\parbox\ or \env{minipage} rather than \cmd\vbox.
%
% \item
% Use \cmd\newcommand\ and \cmd\newenvironment\ to declare user-level commands
% and environments. Avoid the idiom \cmd\def\cmd\foo, \cmd\def\cmd\endfoo\ to define
% an environment.
% Ideally, all user-level markup could be extracted from the
% document class by grepping on \cmd\newcommand\ and \cmd\newenvironment.
%
% \item
% Prefer to use \cmd\setlength\ to assign registers.
%
% \end{itemize}
% I cannot help but notice that much of the code of \LaTeX\ itself fails
% to comply with many of the coding recommendations of Team \LaTeX.
%
%
% \Finale
% %Here ends the programmer's documentation.
% \endinput
%
\endinput