path: root/Master/texmf-dist/source/latex/tcldoc/tcldoc.dtx

% \CheckSum{1549}
%
% \title{The \package{tcldoc} package and class}
% \author{Lars Hellstr\"om^^A
%    \thanks{E-mail: \texttt{Lars.Hellstrom@math.umu.se}}
%    \emph{et al.}}
% \date{2001/01/04}
% \maketitle
% 
% \iffalse
%
%<class|pkg>\NeedsTeXFormat{LaTeX2e}
%<class>\ProvidesClass{tcldoc}
%<pkg>\ProvidesPackage{tcldoc}
%<class|pkg>         [2000/12/20 v2.13 Tcl documentation 
%<class>              class]
%<pkg>              package]
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{amsmath}
\IfFileExists{xdoc2.sty}{\usepackage[dolayout]{xdoc2}[2000/11/18]}{}

\makeatletter
\@ifpackageloaded{xdoc2}{}{%
   \@ifpackagelater{doc}{2000/05/20}{}{%
      \let\XD@fragile@meta=\meta
      \def\meta{%
         \ifx \protect\@typeset@protect
            \expandafter\futurelet \expandafter\@let@token
               \expandafter\XD@fragile@meta
         \else
            \noexpand\meta
         \fi
      }%
   }%
}
\@ifundefined{option}{%
   \newenvironment{option}[1]{%
      \trivlist
      \if@inlabel\else \macro@cnt=\z@ \fi
      \item[]\ignorespaces
   }{\endtrivlist}%
}{}
\makeatother

\DeclareRobustCommand\package[1]{\textsf{#1}}
\DeclareRobustCommand\Tcl{T\kern-0.1em cl}
\DeclareRobustCommand\word[1]{\mbox{$\{$\itshape#1\/$\}$}}

\providecommand*\describeoption[1]{\marginpar{\texttt{#1} option}}
\providecommand*\PrintChar[1]{\char#1\relax}
\providecommand*{\DoNotIndexHarmless}[1]{}
\providecommand*{\DoNotIndexBy}[1]{}
\DoNotIndexBy{@}
\DoNotIndexBy{@@}
\DoNotIndexBy{TD@}
\newenvironment{isyntax}{%
   \list{}{%
      \setlength\parsep{0pt plus 1pt}%
      \setlength\listparindent{-1em}%
      \setlength\itemindent{\listparindent}%
      \addtolength\leftmargin{1em}%
   }%
   \item\relax \rightskip=1.0\rightskip plus 5cm
}{\endlist}

\setcounter{IndexColumns}{2}
\hfuzz=10pt
\expandafter\def \expandafter\GlossaryParms \expandafter{%
   \GlossaryParms \hbadness=10000
}

\CodelineIndex
% \EnableCrossrefs
% \RecordChanges

\begin{document}
\DocInput{tcldoc.dtx}
\PrintChanges
\PrintIndex
\end{document}
%</driver>
%
% \fi
%
% \begin{abstract}
%   The \package{tcldoc} package defines a couple of environments and 
%   macros for documenting \Tcl\ source code in \texttt{.dtx}-style 
%   documented source files, much like what the \package{doc} 
%   package~\cite{doc} does for \TeX\ source code. The \package{tcldoc} 
%   class is analogous to the \package{ltxdoc} document 
%   class~\cite{ltxdoc}---it loads the package to gain the basic 
%   functionality and changes some layout parameters to values that 
%   are better suited for documented source than those set by the 
%   standard \package{article} document class.
%   
%   The \package{tcldoc} package builds on the \package{doc} and 
%   \package{xdoc}~\cite{xdoc} packages.
% \end{abstract}
% 
% \tableofcontents
% 
% \DoNotIndex{\advance,\begingroup,\bgroup,\big,\Big,\bigg,\Bigg,\box}
% \DoNotIndex{\catcode,\char,\chardef,\cleaders,\color@begingroup}
% \DoNotIndex{\color@endgroup,\copy,\csname,\DeclareOption}
% \DoNotIndex{\DeclareRobustCommand,\DeclareTextCommand}
% \DoNotIndex{\DeclareTextSymbol,\def,\discretionary,\divide,\do}
% \DoNotIndex{\edef,\egroup,\else,\@empty,\endcsname,\endgroup}
% \DoNotIndex{\expandafter,\fi,\@firstoftwo,\font,\fontdimen}
% \DoNotIndex{\futurelet,\gdef,\global,\@gobble,\hb@xt@,\hbox}
% \DoNotIndex{\hfill,\if,\ifcase,\ifcat,\ifmmode,\ifnum,\ifvbox}
% \DoNotIndex{\ifvmode,\ifvoid,\ifx,\ignorespaces,\immediate,\indent}
% \DoNotIndex{\input,\@@input,\InputIfFileExists,\IfFileExists}
% \DoNotIndex{\item,\kern,\language,\lastbox,\lastpenalty,\lastskip}
% \DoNotIndex{\lccode,\leavevmode,\let,\llap,\LoadClass,\lowercase}
% \DoNotIndex{\m@ne,\m@th,\@makeother,\mathord,\mkern,\multiply}
% \DoNotIndex{\@ne,\newbox,\newcommand,\newcount,\NewDescribeCommand}
% \DoNotIndex{\newenvironment,\newif,\NewMacroEnvironment,\nfss@text}
% \DoNotIndex{\noexpand,\normalfont,\null,\number,\or,\p@,\@@par}
% \DoNotIndex{\parshape,\PassOptionsToClass,\PassOptionsToPackage}
% \DoNotIndex{\penalty,\@plus,\predisplaypenalty,\prevdepth,\prevgraf}
% \DoNotIndex{\ProcessOptions,\protect,\protected@edef}
% \DoNotIndex{\providecommand,\ProvideTextCommandDefault,\relax}
% \DoNotIndex{\RequirePackage,\RequirePackageWithOptions,\rightarrow}
% \DoNotIndex{\sbox,\selectfont,\setbox,\skewchar,\space,\string}
% \DoNotIndex{\TextSymbolUnavailable,\texttt,\the,\tracingparagraphs}
% \DoNotIndex{\ttfamily,\tw@,\typeout,\unhbox,\unpenalty,\unskip}
% \DoNotIndex{\unrestored@protected@xdef,\unskip,\unvbox,\vadjust}
% \DoNotIndex{\vbox,\vert,\vrule,\vskip,\wd,\write,\xdef,\z@,\z@skip}
% 
% \section{Introduction}
% \label{Sec:Introduction}
% 
% This introduction is meant to be comprehensible even for readers 
% unfamiliar with writing \texttt{.dtx} files and using the \package{doc} 
% package. Readers who are experienced with this will probably want to 
% skip right to the next section.
% 
% A \texttt{.dtx} file has a dual nature. On one hand it is a container 
% for some lines of code---it could be a program, a macro package, a 
% configuration file for some program, merely a part of any of the 
% aforementioned, or even arbitrary combinations of the above---and on 
% the other hand it is a \LaTeX\ document which documents this code. One 
% important advantage with this arrangement is that one can keep all the 
% pieces of a project that has to do with a specific task at one place; 
% experience has shown that this greatly furthers really keeping all 
% parts of a project up to date with each other.
% 
% Slightly simplified, one can say that a \texttt{.dtx} file contains 
% three kinds of lines. A \emph{code line} is a line that doesn't begin 
% with a `|%|' character; such lines can be extracted (copied) using the 
% \package{docstrip} program~\cite{docstrip}. A \emph{guard line} is a 
% line that begins with the two characters `|%<|'; guards are used to 
% structure the set of code lines so that \package{docstrip} can extract 
% different code lines to different generated files. A \emph{comment 
% line}, finally, is a line that begins with a `|%|' character that is 
% not immediately followed by a `|<|' character. The comment lines are 
% ignored by \package{docstrip}, but are part of (and usually make up 
% most of) the \LaTeX\ document in the \texttt{.dtx} file.
% 
% 
% \subsection{Special conventions and basic features in a \texttt{.dtx} 
%   \LaTeX\ document}
% 
% An important difference between normal \LaTeX\ documents and 
% \texttt{.dtx} \LaTeX\ documents is that the percent character `|%|' 
% doesn't start a comment in the latter; in fact it is usually ignored. 
% This allows \LaTeX\ to see and typeset the text in the comment lines 
% of a \texttt{.dtx} file. Hence if one wants to include the sentence 
% ``Your hovercraft is full of eels!'', which in a normal \LaTeX\ 
% document could have been written as the line\iffalse
%<*example>
% \fi
%\begin{verbatim}
%Your hovercraft is full of eels!
%\end{verbatim}
% one would instead write the line as
%\begin{verbatim}
%% Your hovercraft is full of eels!
%\end{verbatim}
% in a \texttt{.dtx} document. The space after the |%| is not 
% necessary, but most \texttt{.dtx} documents you see include 
% it---probably because the ``comment out \TeX\ code'' action of most 
% text editors consists of inserting a percent \emph{and} a space at 
% the beginning of each line.
% 
% The code lines present the opposite problem, as they usually 
% shouldn't be treated as normal \LaTeX\ code although the normal \LaTeX\ 
% reading conventions would make them the entire document. The usual way 
% around this is to surround each group of code lines with two comment 
% lines that begin and end an environment in which the code lines get 
% typeset verbatim. The \package{tcldoc} package provides the \texttt{tcl} 
% environment for this purpose, so the code lines
%\begin{verbatim}
%proc factorial {n} {
%   set result 1
%   for {set i 1} {$i<=$n} {incr i} {
%      set result [expr {$result * $i}]
%   }
%   return $result
%}
%\end{verbatim}
% could be included in a \texttt{.dtx} document as the lines
%\begin{verbatim}
%% \begin{tcl}
%proc factorial {n} {
%   set result 1
%   for {set i 1} {$i<=$n} {incr i} {
%      set result [expr {$result * $i}]
%   }
%   return $result
%}
%% \end{tcl}
%\end{verbatim}
% When typeset, this will look as
%    \begin{macrocode}
proc factorial {n} {
   set result 1
   for {set i 1} {$i<=$n} {incr i} {
      set result [expr {$result * $i}]
   }
   return $result
}
%    \end{macrocode}
% The tiny numbers at the beginning of each line enumerate the code lines. 
% Index references to code usually specify such code line numbers, but 
% the enumeration can be switched off.
% 
% In mathematical papers, the statements of e.g.\ theorems are usually 
% made inside a \texttt{theorem} (or whatever) environment which 
% provides certain text formatting, a heading, and a position in the 
% document that can be referenced from other parts of it. In \texttt{.dtx} 
% documents one usually does something similar for each named piece of 
% code: macros, environments, templates, etc. In particular, the 
% \package{tcldoc} package provides two environments \texttt{proc} (for 
% procedures) and \texttt{variable} (for variables). 
% Figure~\ref{Fig:procex} contains an example of how \texttt{proc} 
% might be used in describing a procedure for computing the greatest 
% common divisor of two integers.
% 
% \begin{figure}
% 
% \begin{trivlist}
%   \item[]\leavevmode\llap{\texttt{gcd} (proc)\kern\marginparsep}^^A
%   The |gcd| procedure takes two arguments $a$ and $b$ which must be 
%   integers and returns their greatest common divisor $\gcd(a,b)$, 
%   which is computed using Euclid's algorithm. As a special case, 
%   $\gcd(0,0)$ is considered to be $0$, so formally |gcd $a $b| 
%   computes $\lvert a \rvert \wedge \lvert b \rvert$, where $\wedge$ 
%   denotes the meet operation in the divisor lattice of non-negative 
%   integers.
%    \begin{macrocode}
proc gcd {a b} {
   set a [expr {abs($a)}]
   set b [expr {abs($b)}]
   while {$b>0} {
      set r [expr {$a%$b}]
      set a $b
      set b $r
   }
   return $a
}
%    \end{macrocode}
% \end{trivlist}
% 
% \begin{center}
%   (a) A typeset procedure with description
% \end{center}  
% 
%\begin{verbatim}
%% \begin{proc}{gcd}
%%   The |gcd| procedure takes two arguments $a$ and $b$ which must be 
%%   integers and returns their greatest common divisor $\gcd(a,b)$, 
%%   which is computed using Euclid's algorithm. As a special case, 
%%   $\gcd(0,0)$ is considered to be $0$, so formally |gcd $a $b| 
%%   computes $\lvert a \rvert \wedge \lvert b \rvert$, where $\wedge$ 
%%   denotes the meet operation in the divisor lattice of non-negative 
%%   integers.
%%   \begin{tcl}
%proc gcd {a b} {
%   set a [expr {abs($a)}]
%   set b [expr {abs($b)}]
%   while {$b>0} {
%      set r [expr {$a%$b}]
%      set a $b
%      set b $r
%   }
%   return $a
%}
%%   \end{tcl}
%% \end{proc}
%\end{verbatim}
% 
% \begin{center}
%   (b) The code for the example in (a)
% \end{center}  
% 
% \caption{An example of the \texttt{proc} environment}
% \label{Fig:procex}
% \end{figure}
% 
% What does the \texttt{proc} environment do more precisely? First 
% there's the marginal heading which can be seen in Figure~^^A
% \ref{Fig:procex}. Such headings make it easier to find the procedure in 
% the typeset form of the document. Then the \texttt{proc} environment 
% makes an index entry which tells you where the procedure is defined, 
% and finally it stores the procedure name in a variable so that 
% subsequent |\changes|\footnote{The \cs{changes} command is defined by 
% the \package{doc} package~\cite{doc}. It is used for adding entries 
% to a global list of changes for code in the \texttt{.dtx} document.} 
% commands know to what the change that they are recording was made.
% 
% The \texttt{variable} environment does the same things except that it 
% writes ``(var.)'' rather than ``(proc)''. This environment wasn't used 
% for describing the three local variables |a|, |b|, and |r| in the 
% example; this is since there is no point in referring to these 
% variables from elsewhere in the program. Instead the \texttt{variable} 
% environment is primarily meant for global variables (although it could 
% also be useful for local variables that are meant to be accessed using 
% |upvar| or |uplevel|), and as such it can often be of great help, since 
% the description of a global variable can otherwise be hard to find, 
% especially with languages like \Tcl\ where variables don't have to be 
% declared and thus have no natural ``home'' in the code.
% 
% Another noteworthy feature in the example is the use of vertical 
% bar `\verb+|+' characters to delimit short pieces of verbatim \Tcl\ 
% code in the comment lines. It is often necessary for the explanation 
% to include short examples of code in the documentation, and the 
% standard \LaTeX\ |\verb| command is exactly what one would need for 
% this. As such code sections are rather frequent however, it has become 
% the custom to use a single character for both starting and ending such 
% a piece of code. The \package{tcldoc} document class defines \verb+|+ 
% as a shorthand for \verb+\tclverb|+, where |\tclverb| is a variant of 
% |\verb| which has been designed specifically for \Tcl\ code.
% 
% The above description was meant to give a basic understanding of how 
% \Tcl\ code and documentation thereof can be mixed in a \texttt{.dtx} 
% file, it neither explains all the environments and commands that 
% the \package{tcldoc} package provides, nor mentions all the 
% features of the environments that were described. That information can 
% instead be found in Section~\ref{Sec:Manual} of this paper. It should 
% also be mentioned that the \package{doc} package~\cite{doc} defines 
% several commands and environments that may be of use for describing 
% code, and it is well worth getting acquainted with the features of 
% that package as well (although parts of its documentation has become 
% rather archaic).
% 
% 
% \subsection{Guards and \package{docstrip} installation scripts}
% 
% The central command in a \package{docstrip} installation script is 
% |\generate|, since this is the command which actually causes code to 
% be extracted. |\generate|'s syntax is
% \begin{quote}
%   |\generate|\marg{files}
% \end{quote}
% where \meta{files} consists of one or several |\file| commands, each 
% of which has the syntax
% \begin{quote}
%   |\file|\marg{output}\marg{sources}
% \end{quote}
% where \meta{output} is a filename and \meta{sources} consists of one 
% or several |\from| commands, each of which has the syntax
% \begin{quote}
%   |\from|\marg{input}\marg{options}
% \end{quote}
% where, finally, \meta{input} is a filename and \meta{options} is a 
% comma-separated list of alphanumerical strings. Thus a |\generate| 
% command might look like
%\begin{verbatim}
%    \generate{\file{p1.sty}{\from{s1.dtx}{foo,bar}}
%              \file{p2.sty}{\from{s2.dtx}{baz}
%                            \from{s3.dtx}{baz}}
%              \file{p3.sty}{\from{s1.dtx}{zip}
%                            \from{s2.dtx}{zap}}
%             }
%\end{verbatim}
% The meaning of this command is
% \begin{quote}
%   Generate the three files \texttt{p1.sty}, \texttt{p2.sty}, and 
%   \texttt{p3.sty}. Extract the code for \texttt{p1.sty} from 
%   \texttt{s1.dtx} with options \texttt{foo} and \texttt{bar}, extract 
%   the code for \texttt{p2.sty} from \texttt{s2.dtx} with option 
%   \texttt{baz} and \texttt{s3.dtx} (the code from \texttt{s2.dtx} 
%   will be put before the code from \texttt{s3.dtx}) with option 
%   \texttt{baz}, and finally extract the code for \texttt{p3.sty} from 
%   \texttt{s1.dtx} with option \texttt{zip} and \texttt{s2.dtx} with 
%   option \texttt{zap}.
% \end{quote}
% The \emph{options} are used to control which parts of the source files 
% should be extracted to which generated file. A source file can 
% contain a number of \emph{modules}, and at the beginning of each 
% module \package{docstrip} decides, for each output file separately, 
% whether the code lines in that module should be extracted to the 
% output file. The beginning of a module is marked by a guard line which 
% has the syntax
% \begin{quote}
%   |%<*|\meta{expression}|>|
% \end{quote}
% and the end by a corresponding
% \begin{quote}
%   |%</|\meta{expression}|>|
% \end{quote}
% guard line. In their simplest form, the \meta{expression}s are names 
% of options, and in that case the code lines in the module are only 
% extracted if that option appears in the \meta{options} for that 
% combination of input file and output file. The \meta{expression}s can 
% however be arbitrarily complicated boolean expressions; 
% see~\cite{docstrip} for more information.
% Modules may nest inside each other, and in that case the code lines in 
% an inner module can only be included if all surrounding modules are 
% being included. It is checked that matching |*| and |/| guard lines 
% contain the same (as strings) \meta{expression}, and case is 
% significant in the names of options.
% 
% One application of modules which has already been mentioned is to 
% bundle code for several different generated files in the same 
% \texttt{.dtx} file---one example of this is the file 
% \texttt{doc.dtx} (part of the \LaTeX\ base distribution) which 
% contains both the \package{doc} package (\texttt{doc.sty}) and two 
% \package{makeindex} style files (\texttt{gglo.ist} and 
% \texttt{gind.ist}). Another application is to keep variant sections 
% of code---such as special code for debugging or gathering 
% statistics---in the \texttt{.dtx} source file for a program without 
% thereby making it a part of the normal form of that program. It is 
% quite possible to use \package{docstrip} as a simple pre-processor 
% for languages whose compiler\slash interpreter haven't got one built 
% in.
% 
% There are many other commands available in a \package{docstrip} 
% installation script beside those listed above, but those are well 
% described in the \package{docstrip} manual~\cite{docstrip} and need 
% little attention here. Instead I'm going to finish this subsection 
% with a quick guide to the particular difficulties one faces when using 
% \package{docstrip} to extract \Tcl\ code, and how to overcome them.
% 
% The main problem is that \package{docstrip} insert a few comment lines 
% at the beginning and end of each file it generates. This is a good 
% thing, because a file consisting entirely of extracted code lines 
% would normally be completely void of commentary and quite 
% unintelligible for the casual user. These few comment lines explain 
% that the file was generated by \package{docstrip} from other files 
% (which contain the documentation of the code), lists those files, 
% and normally also contains a copyright (or more commonly some kind of 
% copyleft) notice. The problem lies in that comments look different in 
% different languages, and as the default is to write \TeX\ style 
% comments, one must tell \package{docstrip} to write \Tcl\ style 
% comments. This can be done through the command
%\begin{verbatim}
%\edef\MetaPrefix{\string#}
%\end{verbatim}
% which tells \package{docstrip} to begin each inserted comment line 
% with the character `|#|'.
% 
% The comment lines inserted at the beginning of a generated file is 
% called the \emph{preamble} and those of the end the \emph{postamble}.
% To set the preamble, one writes
% \begin{trivlist}
% \item |\preamble|\\
% \meta{preamble lines}\\
% |\endpreamble|
% \end{trivlist}
% and correspondingly to set the postamble
% \begin{trivlist}
% \item |\postamble|\\
% \meta{postamble lines}\\
% |\endpostamble|
% \end{trivlist}
% The \meta{preamble lines} and \meta{postamble lines} can be any number 
% of lines (including zero). Unlike the text in source files, the text in 
% these preamble and postamble lines is not read verbatim, so things in 
% these lines which have special meaning to \TeX\ (such as control 
% sequences) will be treated as such; the only exception is that spaces 
% and newlines are preserved (instead of concatenated to single spaces 
% as they normally would). It is important that the preamble and 
% postamble \emph{are} set after |\MetaPrefix| is changed, because each 
% line specified between |\preamble| and |\endpreamble| or |\postamble| 
% and |\endpostamble| respectively will be prefixed by the current value 
% of |\MetaPrefix|.
% 
% Finally, some programs assign special meaning to the first line of a 
% file, so one might want to control what gets put there. Merely using 
% |\preamble| doesn't achieve this, because the \meta{preamble lines} 
% specified that way are put after the lines saying ``this is a 
% generated file \textellipsis''. You can however add things to the 
% preamble by explicitly setting the macro |\defaultpreamble|, which is 
% where \package{docstrip} stores the preamble. To make the first line 
% a comment which simply contains the text `|-*-Tcl-*-|', you could give 
% the command
%\begin{verbatim}
%\edef\defaultpreamble{\MetaPrefix\space -*-Tcl-*-^^J\defaultpreamble}
%\end{verbatim}
% but an explanation of this is a bit beyond this introduction.
% 
% In summary, a \package{docstrip} installation script for extracting a 
% file \texttt{foo.tcl} from \texttt{foo.dtx}, using \Tcl\ style 
% comments, inserting a GPL copyleft notice in the preamble, and 
% beginning with the line |# -*-Tcl-*-| could look as follows:
%\begin{verbatim}
%\input docstrip.tex
%
%\edef\MetaPrefix{\string#}
%
%\preamble
%
%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.
%See the file "license.terms" for information on usage and 
%redistribution of this file, and for a DISCLAIMER OF ALL 
%WARRANTIES.
%
%\endpreamble
%
%\postamble
%\endpostamble
%
%\edef\defaultpreamble{\MetaPrefix\space -*-Tcl-*-^^J\defaultpreamble}
%
%\generate{\file{foo.tcl}{\from{foo.dtx}{bar}}}
%
%\end
%\end{verbatim}
% 
% The generated file \texttt{foo.tcl} will contain
%\begin{verbatim}
%# -*-Tcl-*-
%#
%# This is file `foo.tcl',
%# generated with the docstrip utility.
%#
%# The original source files were:
%#
%# foo.dtx  (with options: `bar')
%# 
%# 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.
%# See the file "license.terms" for information on usage and
%# redistribution of this file, and for a DISCLAIMER OF ALL
%# WARRANTIES.
%# 
%\end{verbatim}
% \meta{lines extracted from \texttt{foo.dtx}}
%\begin{verbatim}
%# 
%#
%# End of file `foo.tcl'.
%\end{verbatim}
% 
% 
% 
% \subsection{The structure of the \LaTeX\ document}
% 
% All this has been about the local appearance of a \texttt{.dtx} file, 
% but what about the overall structure? There are several points to 
% raise about that as well.
% 
% The first is that \LaTeX\ to begin with treat \texttt{.dtx} documents 
% just like any other document---a `|%|' starts a comment and only lines 
% \emph{not} beginning with a `|%|' contain anything that \LaTeX\ can 
% see. Somehow \LaTeX\ must be instructed to start applying the special 
% reading rules that were described above. This is the job of the 
% so-called \emph{driver}, which (for a file \texttt{myfile.dtx}) in its 
% simplest form can look like
%\begin{verbatim}
%\documentclass{tcldoc}
%\begin{document}
%\DocInput{myfile.dtx}
%\end{document}
%\end{verbatim}
% The important command here is |\DocInput|, because that is what tells 
% \LaTeX\ to apply the special \texttt{.dtx} reading rules. More 
% precisely it means ``Start ignoring `|%|' characters in the text you 
% read, input the file \texttt{myfile.dtx}, and when you're done return 
% to treating `|%|' characters as before.''
% 
% The driver is usually put in the very first stretch of code lines in 
% the \texttt{.dtx} file. This means that \LaTeX, when ordered to typeset 
% the \texttt{.dtx} file, will start to read along, possibly ignoring 
% hundreds of lines beginning with `|%|' because they are comments. Then 
% it encounters the driver, and after the |\documentclass| and 
% |\begin{document}| commands it executes the |\DocInput|. This will 
% cause it to not ignore lines beginning with `|%|', so when it starts 
% reading the file again it will see all the lines it skipped the first 
% time through. The file will be read to end, after which \LaTeX\ 
% returns to the command after the |\DocInput|. As that command happens 
% to be |\end{document}|, it finishes the typeset document and stops. 
% This stop prevents it from seeing and interpreting as \LaTeX\ commands 
% the remaining code lines in the file.
% 
% The second time through the driver shouldn't be interpreted as 
% \LaTeX\ commands, since for example the |\documentclass| command may 
% only be used once in a \LaTeX\ document. One way of achieving this is 
% to put an |\iffalse| command right before the driver and a |\fi| 
% command right after it. This says to \LaTeX\ that the driver code is 
% conditional material, and since the condition evaluates to false 
% (|\iffalse| always evaluates to false), this conditional material 
% should be skipped. Thus the first few lines of \texttt{myfile.dtx} 
% typically might be
%\begin{verbatim}
%% \iffalse
%%<*driver>
%\documentclass{tcldoc}
%\begin{document}
%\DocInput{myfile.dtx}
%\end{document}
%%</driver>
%% \fi
%\end{verbatim}
% The \texttt{driver} guard lines are there to stop \package{docstrip} 
% from including the driver code in the generated files.
% 
% After the driver comes the actual \LaTeX\ document. The document 
% usually consists of two parts, where the first part is a manual for 
% the \emph{usage} of the code defined in the file, and the second part 
% contains the actual \emph{implementation} (documented code). The idea 
% is that most people are (at least the first time) quite content with 
% learning how to use something, so one should make it simple for them 
% to find that information.\footnote{One needn't take this as an absolute 
% rule---I for one haven't written all my packages that way---but 
% structuring the document like this generally makes it more accessible.} 
% To further this approach one puts the command |\StopEventually| at the 
% start of the implementation part and the command |\Finale| at the end 
% of it. Normally |\StopEventually| doesn't make itself felt, but if one 
% previously has given the command |\OnlyDescription| then rest of the 
% file will not be read; this can be used to produce a ``manual only'' 
% version of the documentation. |\StopEventually| takes one argument and 
% the code in this argument is executed at the |\Finale| (if the 
% implementation part is being included) or immediately (if the 
% implementation part isn't being included). Thus this argument is the 
% place to put things that should appear at the very end of the 
% document.
% 
% The \texttt{tcl}, \texttt{proc}, and \texttt{variable} environments 
% described above all typically appear in the implementation part of the 
% document.
% 
% 
% \section{Usage of commands and environments}
% \label{Sec:Manual}
%
% 
% \subsection{The actual source code}
% 
% The \DescribeEnv{tcl}\texttt{tcl} environment is used for wrapping up 
% a group of code lines which contain \Tcl\ code. Lines inside this 
% environment which begin with a percent character are called 
% \emph{command} lines and can contain \LaTeX\ commands which get 
% executed, whereas lines that do not begin with a percent character are 
% called \emph{normal} lines and get typeset verbatim (or nearly 
% verbatim). Lines that begin with |%<| (\package{docstrip} guard lines) 
% do however constitute a special case, as the guard expression will get 
% typeset as in \package{doc}'s \texttt{macrocode} environment and the 
% remainder of the line will get processed in command mode if it is a 
% |*| or |/| guard, but in normal mode if the guard line was of any other 
% type.
% 
% The \texttt{tcl} environment uses the same general formatting 
% parameters as \package{doc}'s \texttt{macrocode} environment. In 
% particular this means that the text on a normal line is typeset in 
% |\MacroFont| (by default the same thing as \cs{normalfont}\penalty0
% \cs{ttfamily}\penalty0\cs{small}) or |\AltMacroFont| (by default the same 
% thing as \cs{normalfont}\penalty0\cs{ttfamily}\penalty0\cs{itshape}^^A
% \penalty0\cs{small}) depending on the current \package{docstrip} module 
% nesting level. The \package{tcldoc} class sets the 
% \texttt{StandardModuleDepth} counter to 1, which means that the 
% |\AltMacroFont| is used when the modules two levels deep or more.
% 
% If a normal line is too long to fit on one line then the \texttt{tcl} 
% environment will try to break it. Legal breakpoints are spaces which 
% could be replaced by a backslash and a newline without changing the 
% meaning of the command; thus most spaces are legal breakpoints. When a 
% line is broken at a space like this, the space is replaced by a 
% backslash so that the line is still ``syntactically correct''. The 
% opposite happens to lines which actually end with an escaped newline; 
% such lines are concatenated with the following line and are treated as 
% one long line. This is so that a sequence of breakpoints can be chosen 
% which is optimal for the actual line width of the document (as opposed 
% to the line width used in the text file, which can be something quite 
% different). For example 
%\begin{verbatim}
%% \begin{tcl}
%lsearch -exact\
%   [concat $a [lrange $b $first end] c d e f]\
%   [lindex $g $h]
%% \end{tcl}
%\end{verbatim}\iffalse
%</example>
% \fi
% could be typeset as any of the code examples in 
% Figure~\ref{Fig:Radbrytning}, depending on how wide a line is.
% \begin{figure}
%   \begin{center}
%     \small
%     \(\left\lvert
%     \begin{minipage}{350pt}
%       \begin{flushleft}
%         |lsearch -exact [concat $a [lrange $b $first end] c d e f]|^^A
%         | [lindex $g $h]|
%       \end{flushleft}
%     \end{minipage}
%     \right\rvert\)
%     
%     \smallskip
%     
%     \(\left\lvert
%     \begin{minipage}{298pt}
%       \begin{flushright}
%         \noindent |lsearch -exact [concat $a [lrange $b $first|^^A
%         | end] c d e f]|\textbackslash\hfill\vadjust{}\\
%         |[lindex $g $h]|
%       \end{flushright}
%     \end{minipage}
%     \right\rvert\)
%     
%     \smallskip
%     
%     \(\left\lvert
%     \begin{minipage}{241pt}
%       \begin{flushright}
%         \noindent |lsearch -exact|\textbackslash\hfill\vadjust{}\\
%         |[concat $a [lrange $b $first end] c d e f]|\textbackslash\\
%         |[lindex $g $h]|
%       \end{flushright}
%     \end{minipage}
%     \right\rvert\)
%     
%     \smallskip
%     
%     \(\left\lvert
%     \begin{minipage}{184pt}
%       \begin{flushright}
%         \noindent |lsearch -exact [concat $a|\textbackslash\hfill
%         \vadjust{}\\
%         |[lrange $b $first end] c d e f]|\textbackslash\\
%         |[lindex $g $h]|
%       \end{flushright}
%     \end{minipage}
%     \right\rvert\)
%   \end{center}
%   
%   \caption{The same \Tcl\ code, set in different linewidths}
%   \label{Fig:Radbrytning}
% \end{figure}
% The environment tries to put the linebreaks at the lowest possible 
% nesting (of braces and brackets) level; I believe this gives the best 
% readability.\footnote{When I first started programming in \Tcl\ I 
% used a completely different method for breaking long lines in the 
% code---I mainly implemented the current method because it was 
% simple to program---but I was quite surprised by how readable it made 
% the code.} There is however a way to override this automatic choice 
% of breakpoints: if a normal line which ends with an escaped newline is 
% followed by a command line (even a command line that doesn't contain 
% any commands) then it will not be concatenated with the next normal 
% line.
% 
% There are a couple of restrictions on the code in command lines. First 
% of all it is not allowed to start a new paragraph (there will be an 
% error message). Secondly a command may not be broken across several 
% lines---all the arguments must appear on the same line as the 
% control sequence. Thirdly some characters have other catcodes than 
% in normal \LaTeX, so it is not certain that all commands work. Some 
% commands that do work and may be useful are:
% \begin{itemize}
%   \item Vertical space commands (|\smallskip|, |\medskip|, etc.) 
%     The command line `|% \medskip|' is more to type than a blank 
%     normal line, but it looks slightly better.
%   \item Indexing commands (|\index|, |\IndexEntry|,\footnote{This  
%     command is defined by the \package{xdoc} package~\cite{xdoc}.} 
%     etc.)
%   \item The \cs{TclInput} and |\settabsize| commands (see below).
% \end{itemize}
% And of course the |\end{tcl}| command works in a command line, since 
% that is how one ends a \texttt{tcl} environment.
% 
% Besides the \texttt{tcl} environment there is also a 
% \DescribeEnv{tcl*}\texttt{tcl*} environment which is different from 
% \texttt{tcl} only in that spaces and tabs are typeset as special 
% visible space `\textvisiblespace' and visible tab 
% `\makebox[6\fontdimen2\font]{\( - \mkern-7mu 
% \cleaders\hbox{$\mkern-2mu - \mkern-2mu$}\hfill \mkern-7mu 
% \mathord\rightarrow \mkern-1mu \vrule \mkern1mu\)}' characters. This 
% can be useful for pieces of code where the exact number of spaces in 
% a sequence is significant, such as code for writing tables that align.
% 
% For shorter pieces of \Tcl\ code, e.g.\ examples, there's the 
% \DescribeMacro{\tclverb}|\tclverb| command. |\tclverb| is very similar 
% to the standard \LaTeX\ command |\verb|, but there are two differences. 
% The first is that text typeset by |\tclverb| can contain breakpoints 
% at whitespace; these behave just as in the \texttt{tcl} environment. 
% The second is that the verbatim text that follows |\tclverb| may contain 
% newlines, provided that these newlines are escaped by a backslash. Like 
% a \Tcl\ interpreter, |\tclverb| ignores whitespace following an escaped 
% newline. Unlike a \Tcl\ interpreter, |\tclverb| also ignores one percent 
% character before the ignored whitespace, if it is the first character 
% on the following line. Thus
%\begin{verbatim}
%% \tclverb|append a $b| is much more efficient than \tclverb|set a\
%% $a$b| if \tclverb|$a| is long.
%\end{verbatim}
% is perfectly legal, and the escaped newline between |a| and |$a$b| is 
% treated just like the space between |set| and |a|. Like |\verb|, the 
% |\tclverb| command has a starred form \DescribeMacro{\tclverb*}^^A
% |\tclverb*| which also typesets spaces and tabs as visible characters.
% 
% 
% The \DescribeMacro{\MakeShortTclverb}|\MakeShortTclverb| command works 
% just like the \package{doc}\slash\package{shortvrb} command 
% |\MakeShortVerb|, except that it makes the active character a shorthand 
% reference for |\tclverb|\textellipsis\ instead of |\verb|\textellipsis. 
% Use |\DeleteShortVerb| to undo the effect of a |\MakeShortTclverb|. The 
% \package{tcldoc} class executes the command
% \begin{quote}
%   \verb"\MakeShortTclverb{\|}"
% \end{quote}
% which makes \verb"|" a shorthand for \verb"\tclverb|".
% 
% Since there is no universally accepted standard for the size 
% (equivalent number of spaces) of a tab, there is a command 
% \DescribeMacro{\settabsize}|\settabsize| for changing this. 
% |\settabsize| takes as its only argument the new tab size, which must 
% be an integer in the range 2--255. The default value is 8. 
% |\settabsize| makes a local assignment to the tab size. The tab size 
% can be changed inside a \texttt{tcl} (or \texttt{tcl*}) environment.
% 
% There is also a command \DescribeMacro{\TclInput}|\TclInput| which 
% is used for typesetting ``raw'' (not in \texttt{.dtx} format) \Tcl\ code 
% files. |\TclInput| is meant to be used on a \emph{command} line of a 
% \texttt{tcl} or \texttt{tcl*} environment, and it efficiently makes 
% things look as if the |\TclInput| command had been replaced by the 
% inputted file in its entirety (preceded by a newline, and followed 
% by a percent and a space). |\TclInput| takes as its only argument the 
% name of the file to input.
% 
% To typeset the file \texttt{myscript.tcl} one would write
%\begin{verbatim}
%% \begin{tcl}
%% \TclInput{myscript.tcl}
%% \end{tcl}
%\end{verbatim}
% or even
%\begin{verbatim}
%   \begin{tcl}\TclInput{myscript.tcl}\end{tcl}
%\end{verbatim}
% anywhere in a \package{tcldoc} document. This works since the 
% \texttt{tcl} environment is in command mode right after the initial 
% |\begin{tcl}|, and the |\end{tcl}| need not be the first command on a 
% command mode line.
% 
% Finally, if the \package{rtkinenc} package~\cite{rtkinenc} is being 
% used then the verbatim code environments and commands described above 
% are to some extent able to catch errors that would otherwise occur 
% because the fonts in use do not contain all characters in the input 
% encoding. Rather than printing nothing, missing characters will be 
% written as the corresponding |\x|\meta{hh} backslash sequence in a 
% slightly different font than the rest of the text. This provides an 
% unambiguous representation regardless of input encoding.
% 
% 
% \subsection{Markup of named things}
%
% The two environments \DescribeEnv{proc}\texttt{proc} and
% \DescribeEnv{variable}\texttt{variable}, which are analogues of 
% \package{doc}'s \texttt{macro} environment, for procedures and 
% variables respectively have already been mentioned in 
% Section~\ref{Sec:Introduction}. In addition to those there are two 
% environments \DescribeEnv{arrayentry}\texttt{arrayentry} and 
% \DescribeEnv{arrayvar}\texttt{arrayvar} which are meant for entries 
% in array variables and array variables as a whole. The complete 
% syntaxes of these environments are
% \begin{quote}
%   |\begin{proc}|\oarg{namespace}\marg{proc name}\\
%   \vadjust{}\quad$\vdots$\\
%   |\end{proc}|
%   
%   |\begin{variable}|\oarg{namespace}\marg{variable name}\\
%   \vadjust{}\quad$\vdots$\\
%   \quad|\end{variable}|
%   
%   |\begin{arrayentry}|\oarg{namespace}\marg{array name}^^A
%   \marg{entry name}\\
%   \vadjust{}\quad$\vdots$\\
%   |\end{arrayentry}|
%   
%   |\begin{arrayvar}|\oarg{namespace}\marg{array name}^^A
%   \oarg{index-des}\\
%   \vadjust{}\quad$\vdots$\\
%   |\end{arrayvar}|
% \end{quote}
% The \meta{proc name}, \meta{variable name}, and \meta{array name} 
% arguments are quite evidently the names of the procedure, variable, 
% and array respectively. The \meta{namespace} argument can be to 
% specify the namespace part of a qualified name; having the name split 
% like this makes it easier to treat the namespace differently from the 
% rest of the qualified name.\footnote{By redefining \cs{TD@main@index} 
% one can for example make the index sorted first by name, and then by 
% namespace.} The command \DescribeMacro{\buildname}|\buildname| 
% constructs a qualified name from a namespace and a name. If there is 
% no \meta{namespace} argument then the namespace used will be the 
% default namespace. The default namespace is set using the 
% \DescribeMacro{\setnamespace}|\setnamespace| command, which takes the 
% namespace name as its only argument. The default namespace at the 
% beginning of the document is the global namespace, whose name is the 
% empty string.
% 
% The \texttt{arrayentry} environment is intended for certain 
% distinguished entries in an array, such as entries inserted to 
% make the boundary cases of an algorithm work correctly and entries 
% which have a special meaning to the program. Not all arrays contain 
% such special entries, but when they do it is a good practice 
% to explain them explicitly. The \meta{index-des} argument of the 
% \texttt{arrayvar} environment can be used to specify what is used as 
% index into the array; the text in this argument will appear both in 
% the margin and in the index, but note that \meta{index-des} is a 
% moving argument. There is little difference between the 
% \texttt{variable} and \texttt{arrayvar} environments when the 
% \meta{index-des} argument of the latter isn't used, but the index 
% entries they make behave differently with respect to 
% \texttt{arrayentry} index entries. An \texttt{arrayentry} index entry 
% will be put as a subentry of the corresponding \texttt{arrayvar} 
% entry, whereas a \texttt{variable} entry would appear separately. 
% 
% The above environments usually only appear in the implementation part 
% of a \texttt{.dtx} file. For the usage part there is a command 
% \DescribeMacro{\describestring}|\describestring| which produces 
% marginal headings and index entries. The syntax of |\describestring| 
% is
% \begin{quote}
%   |\describestring|\oarg{type}\oarg{namespace}\marg{text}
% \end{quote}
% The \meta{text} is the string for which a heading and index entry will 
% be made, whereas the \meta{type} (if given) is put after the text. 
% If the \meta{namespace} is given then the thing described is supposed 
% to be the name of something namespace-relative (like a procedure or 
% global variable) and in this case the complete name is formed by 
% passing \meta{namespace} and \meta{text} to |\buildname|. If 
% \meta{type} is \texttt{proc}, \texttt{var.}, or \texttt{array} and a 
% namespace is given then the index entry made will fit that made by 
% a corresponding \texttt{proc}, \texttt{variable}, or 
% \texttt{arrayvar} respectively environment. The \meta{type} argument 
% is, in \LaTeX\ terminology, moving.
% 
% The \meta{text} and \meta{namespace} arguments can contain arbitrary 
% characters and most characters can be entered verbatim. Amongst the 
% exceptions are `|%|', `|\|', `|{|', and `|}|', which instead can be 
% entered as 
% |\PrintChar|\discretionary{}{}{}|{`\%}|, 
% |\PrintChar|\discretionary{}{}{}|{`\\}|,
% |\PrintChar|\discretionary{}{}{}|{`\{}|, and
% |\PrintChar|\discretionary{}{}{}|{`\}}| respectively. See the 
% \package{xdoc} package~\cite{xdoc} documentation for an explanation of 
% the |\PrintChar| command. The \meta{text} argument can also contain 
% ``variant'' parts made using the \DescribeMacro{\meta}|\meta| command. 
% As an example, 
% \begin{quote}
%   |\describestring[array]{\meta{mode}modeVars}|
% \end{quote}
% puts the text
% \begin{quote}
%   \meta{mode}|modeVars| (array)
% \end{quote}
% in the margin and index. The arguments of such |\meta| commands are 
% moving.
% 
% 
% \subsection{Describing command syntaxes}
% 
% One important part of documentation is to describe the syntaxes of 
% commands. The previous subsection contains examples of the conventions 
% for this that has been developed for \LaTeX\ 
% commands---mandatory arguments are denoted as `\marg{argument}' and 
% optional arguments are denoted as `\oarg{argument}'. These two classes 
% suffice rather well for \LaTeX\ commands, but the syntaxes of \Tcl\ 
% commands are not seldom much more complex. Therefore a more powerful 
% form of syntax specification is called for, and one which is close at 
% hand is that used in regular expressions since it is already part of 
% the \Tcl\ language anyway.
% 
% \DescribeMacro\regopt
% \DescribeMacro\regstar
% \DescribeMacro\regplus
% The simplest commands available are the modifiers |\regopt|, 
% |\regstar|, and |\regplus|, which correspond to the |?|, 
% |*|, and |+| metacharacters in a regular expression; using |\regopt| 
% after a term says that it is optional, |\regstar| says that the term 
% can be repeated an arbitrary number of times (including zero), and 
% |\regplus| says that the term occurs at least once. The typeset 
% results of these commands are $^?$, $^*$, and $^+$ respectively 
% (recall that exponents are sometimes used to denote repetition).
% 
% The terminals in the expression are best made using |\tclverb| (for 
% ``fixed'' material, e.g.\ procedure names) and 
% \DescribeMacro{\word}|\word| (for variable material, e.g.\ 
% arguments). The syntax of |\word| is
% \begin{quote}
%   |\word|\marg{text}
% \end{quote}
% and e.g.\ |\word{script}| gets typeset as
% \begin{quote}
%   \word{script}
% \end{quote}
% Using these, one can for example specify the syntaxes of the \Tcl\ 
% commands |append| and |catch| through
% \begin{quote}
%   \verb"|append| \word{var-name} \word{value}\regplus"\\
%   \verb"|catch| \word{script} \word{var-name}\regopt"
% \end{quote}
% (recall that `\verb"|"' is a shorthand for `\verb"\tclverb|"'). These 
% get typeset as
% \begin{quote}
%   |append| \word{var-name} \word{value}\(^+\)\\
%   |catch| \word{script} \word{var-name}\(^?\)
% \end{quote}
% 
% Terms in regular expressions can also consist of parenthesised 
% subexpressions, which are made using the \DescribeEnv{regexp}^^A
% \texttt{regexp} environment. The syntax of this environment is
% \begin{quote}
%   |\begin{regexp}|\oarg{modifier}\quad\dots\quad |\end{regexp}|
% \end{quote}
% If \texttt{regexp} environments are nested then the parentheses of 
% the outer environment will grow to be larger than those of the inner 
% environment. A side-effect of this is that the \texttt{regexp} 
% environment wants to know if a modifier will be applied to it, since 
% the amount by which the modifier should be raised in this case depends 
% on the size of the parenthesis before it, and this is what the 
% \meta{modifier} optional argument is for. \LaTeX\ does not provide 
% for arguments at the |\end| of an environment, so it has to be placed 
% at the |\begin|. Using these elements, the syntax of |if| can be 
% specified through
% \begin{quote}
%   \verb"|if| \word{expression} |then|\regopt\ \word{script}"\\
%   \verb"\begin{regexp}[\regstar]|elseif| \word{expression}"\\
%   \verb"|then|\regopt\ \word{script}\end{regexp}"\\
%   \verb"\begin{regexp}[\regopt]|else| \word{script}\end{regexp}"
% \end{quote}
% which typesets as
% \begin{isyntax}
%   |if| \word{expression} |then|\(^?\) \word{script} \(\bigl(\)^^A
%   |elseif| \word{expression} |then|\(^?\) \word{script}\(\bigr)^*\) 
%   \(\bigl(\)|else|~\word{script}\(\bigr)^?\)
% \end{isyntax}
% 
% The final regular expression construction that is supported is that 
% of branches of a regular expression. A \texttt{regexp} environment 
% consist of one or several branches that are separated by 
% \DescribeMacro{\regalt}|\regalt| commands. Visually the |\regalt| 
% command gets typeset as a vertical bar that has the same size as the 
% parentheses of the surrounding \texttt{regexp} environment. The 
% |\regalt| command may only be used inside a \texttt{regexp} environment.
% An example of the use of |\regalt| is the following specification of 
% the syntax of \Tcl's |regexp| command:
% \begin{quote}
%   \verb"|regexp| \begin{regexp}[\regstar]|-nocase|\regalt"\\
%   \verb"|-indices|\end{regexp} |--|\regopt \word{regular expression}"\\
%   \verb"\word{string} \word{var-name}\regstar"
% \end{quote}
% which typesets as
% \begin{isyntax}
%   |regexp| \((\)|-nocase|~\(\mid\) |-indices|\()^*\) |--|\(^?\) 
%   \word{regular expression} \word{string} \word{var-name}\(^*\)
% \end{isyntax}
% 
% Finally a note about the relationship between the |\word| command and 
% \package{doc}'s |\meta| command. Whereas the argument of |\word| is 
% encapsulated in braces (and thus ought to be a separate word for a 
% \Tcl\ interpreter), the argument of |\meta| is encapsulated in angle 
% brackets. The idea is that |\word| should be used for things which are 
% separate words to \Tcl, whereas |\meta| should be used for things which 
% are merely part of words. Thus in the command |set b Z${a}Y|, the second 
% word |b| would be a `\word{var-name}' and the third word |Z${a}Y| would 
% be a `|Z|\meta{string}|Y|'. 
% 
% 
% 
% \subsection{Options and customisation}
% 
% The \package{tcldoc} package does not have any options, but all 
% options passed to it are passed on to the \package{xdoc} package. 
% The \package{tcldoc} class accepts all options that the standard 
% \LaTeX\ document class \package{article} accepts, with the exception 
% of \texttt{a5paper}.
% 
% In addition, the \package{tcldoc} class also accepts the option 
% \describeoption{macinputenc}\texttt{macinputenc}, which causes a lot 
% of things to be set up so that input characters from outside 7-bit 
% ASCII can be interpreted according to the Macintosh character set.
% 
% Like the \package{ltxdoc} class, the \package{tcldoc} class will look 
% for a special configuration file \texttt{tcldoc.cfg} and input that 
% file if it exists. This file can be used to declare extra options for 
% the class, have certain options always given, etc. Section~2 of 
% \texttt{ltxdoc.dtx}~\cite{ltxdoc} is a good introduction to how such 
% configuration files can be used with \texttt{.dtx} sources in general.
% 
% When customising the \package{tcldoc} document class, you affect how 
% all documents using that class will be typeset in your particular \TeX\ 
% installation. It is \emph{not} something you have to do, but it can 
% make \package{tcldoc} documents work better with the printers, paper 
% formats, fonts, etc.\ that are available in your installation. It 
% will usually cause line and page breaks to occur at other places than 
% they would do if typeset using an uncustomised \package{tcldoc} 
% class, so the typographical quality of the document can be decreased, 
% but it is uncommon to find an \texttt{.dtx} document whose author 
% have given these matters much attention anyway. Hence the typographic 
% arguments against customisation are weak.
% 
% A common form of customisation is to use additional packages, since 
% various kinds of document-wide font selection is often done by 
% packages. Due to that the code in \texttt{tcldoc.cfg} is executed when 
% the \package{tcldoc} class does its option processing, at which time 
% \LaTeX\ does not allow loading packages, such customisation is not 
% straightforward. There is a way around that however; to load e.g.\ the 
% \package{textcomp} package, use the command
%\begin{verbatim}
%\AtEndOfClass{\usepackage{textcomp}}
%\end{verbatim}
% Using |\AtEndOfClass| like this delays the command until it may be 
% executed.
% 
% Finally, and in particular if you are typesetting documents that use 
% the \texttt{macinputenc} option, you can put code that define 
% ``fakes'' for various text commands in the \texttt{tcldoc.cfg} file. 
% For example, the `diamond' character in the Macintosh encoding is not 
% available in any of the standard \LaTeX\ text fonts, and therefore the 
% \texttt{tcl} environment will typeset this character as the escape 
% code `\textbackslash xd7'. There is a diamond character in the math 
% fonts however, and you can make the \texttt{tcl} environment use that 
% character instead by adding the commands
%\begin{verbatim}
%\DeclareTextSymbol{\textdiamond}{OMS}{5}
%\DeclareTextSymbolDefault{\textdiamond}{OMS}
%\end{verbatim}
% to you \texttt{tcldoc.cfg} file. Note however, that this kind of 
% configuration is \emph{advanced} \LaTeX, and you should probably 
% familiarise yourself with the contents of the file 
% \texttt{ltoutenc.dtx}~\cite{ltoutenc} before attempting to design 
% anything along these lines yourself.
%
% 
% \subsection{Miscellanea}
% 
% For writing ``\Tcl'', the \package{tcldoc} package defines the command 
% \DescribeMacro{\Tcllogo}|\Tcllogo|, which for most fonts look slightly 
% better than simply typing |Tcl|. (|\Tcllogo| becomes \Tcl, whereas 
% |Tcl| becomes Tcl.)
% 
%
% \section{Acknowledgements}
% 
% The \package{tcldoc} document class and \LaTeX\ package were 
% constructed starting from three other sources: (i)~the \package{ltxdoc} 
% document class~\cite{ltxdoc} by David Carlisle, 
% (ii)~the \package{doc} package~\cite{doc} by Frank Mittelbach, 
% B.~Hamilton Kelly, Andrew Mills, Dave Love, and Joachim Schrod, and 
% (iii)~my own \package{pasdoc} document class. Hence the `et al.'\ in 
% the author field above. This complicated heritage in the code is 
% mirrored by the documented source---there are paragraphs below that 
% are rather about one of (i)--(iii), than about \package{tcldoc}.
% 
% 
% 
% \StopEventually{
%   \begin{thebibliography}{9}
%   \bibitem{ltoutenc}
%     Johannes Braams, David Carlisle, Alan Jeffrey, Frank 
%     Mittelbach, Chris Rowley, and Rainer Sch\"opf:
%     \textit{ltoutenc.dtx}, The \LaTeX3 Project; 
%     CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash 
%     \texttt{latex}\slash \texttt{base}\slash \texttt{ltoutenc.dtx}.
%   \bibitem{ltxdoc}
%     David Carlisle:
%     \textit{The file \texttt{ltxdoc.dtx} for use with \LaTeXe},
%     The \LaTeX3 Project; 
%     CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash 
%     \texttt{latex}\slash \texttt{base}\slash \texttt{ltxdoc.dtx}.
%   \bibitem{rtkinenc}
%     Lars Hellstr\"om:
%     \textit{The \package{rtkinenc} package};
%     CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash 
%     \texttt{latex}\slash \texttt{contrib}\slash 
%     \texttt{supported}\slash \texttt{rtkinenc}\slash 
%     \texttt{rtkinenc.dtx}.
%   \bibitem{xdoc}
%     Lars Hellstr\"om:
%     \textit{The \package{xdoc} package --- experimental 
%       reimplementations of features from \package{doc}, 
%       second~prototype}, 2000;
%     CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash
%     \texttt{latex}\slash \texttt{exptl}\slash \texttt{xdoc}\slash
%     \texttt{xdoc2.dtx}.
%   \bibitem{docstrip}
%     Frank Mittelbach, Denys Duchier, Johannes Braams, Marcin 
%     Woli\'nski, and Mark Wooding: \textit{The \textsf{DocStrip} 
%     program},  The \LaTeX3 Project; 
%     CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash 
%     \texttt{latex}\slash \texttt{base}\slash \texttt{docstrip.dtx}.
%   \bibitem{doc}
%     Frank Mittelbach, B.~Hamilton Kelly, Andrew Mills, Dave Love, and 
%     Joachim \mbox{Schrod}: \textit{The \package{doc} and 
%     \package{shortvrb} Packages}, The \LaTeX3 Project;
%     CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash 
%     \texttt{latex}\slash \texttt{base}\slash \texttt{doc.dtx}.
%   \end{thebibliography}
%   \begin{flushleft}\footnotesize
%     The ``CTAN:'' above is short for ``any of the servers in the 
%     Comprehensive \TeX\ Archive Network (or any of their mirrors)''. 
%     You get a working URL if you replace this by e.g.\ 
%     ``\texttt{ftp://ftp.tex.ac.uk/tex-archive/}''.%
%   \end{flushleft}
% }
% 
%
% \changes{v\,1.90}{2000/01/02}{Took a copy of \texttt{pasdoc.dtx} and 
%    started modifying it into \texttt{tcldoc.dtx}. (LH)}
%
% \section{Initial stuff in the \package{tcldoc} package}
% 
% The |\NeedsTeXFormat| and |\ProvidesPackage| commands for the 
% \package{tcldoc} package appear at the top of \texttt{tcldoc.dtx} (not 
% shown in the typeset document). Apart from that the only initial 
% action required is to load the \package{xdoc} package (and thereby 
% the \package{doc} package).
%
%    \begin{macrocode}
%<*pkg>
\RequirePackageWithOptions{xdoc2}[2000/11/26]
%    \end{macrocode}
% 
% 
% \section{Verbatim typesetting of \Tcl\ code}
% 
% \changes{v\,2.10}{2000/10/03}{Major overhaul of the \texttt{tcl} 
%    environment, to make it possible to assign different penalties to 
%    different breakpoints. (LH)}
% 
% The main feature in the \package{tcldoc} package is the \texttt{tcl} 
% environment, which typesets embedded code in a way more adapted to 
% \Tcl\ code than what the \texttt{macrocode} environment does.
% 
% 
% \subsection{Beginning of line processing}
% 
% The organization of the text in \emph{lines} is crucial for its 
% interpretation by the \texttt{tcl} environment. In particular the 
% following features rely on being at the beginning of a line:
% \begin{itemize}
%   \item indentation of \Tcl\ code,
%   \item invoking command mode,
%   \item recognizing \package{docstrip} guards.
% \end{itemize}
% 
% \begin{macro}{\TD@percent@token}
%   A control sequence |\let| to a |%|$_{12}$, mainly for use in |\ifx| 
%   comparisons.
%   \DoNotIndex{\%}
%    \begin{macrocode}
\begingroup
   \catcode`\%=12
   \global\let\TD@percent@token=%
\endgroup
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@start@n@line}
% \begin{macro}{\TD@start@n@line@}
% \begin{macro}{\TD@start@n@line@i}
%   The macro |\TD@start@n@line| is used at the beginning of every line. 
%   The macro first clears the |\TD@line@indent| and |\TD@nesting@level| 
%   registers and then it checks if the next character is a percent. If 
%   it is then this is a command line. If it isn't then it is a normal 
%   line and it is time to start a codeline paragraph and count the 
%   character indentation.
%   
%   |\TD@|\-|start@|\-|n@|\-|line@| is the macro which actually does 
%   these things; |\TD@|\-|start@|\-|n@|\-|line| is usually |\let| to 
%   |\TD@|\-|start@|\-|n@|\-|line@|. When a file is being |\TclInput|ed 
%   however, |\TD@|\-|start@|\-|n@|\-|line| is |\let| to 
%   |\TD@|\-|start@|\-|n@|\-|line@i| which peeks at the next token 
%   before calling |\TD@|\-|start@|\-|n@|\-|line@|. If it didn't, 
%   |\TD@|\-|start@|\-|n@|\-|line@| would have a problem at the end of 
%   the file, since the end of a file counts as being |\outer|.
%    \begin{macrocode}
\def\TD@start@n@line@#1{%
   \global\TD@line@indent=\z@
   \TD@nesting@level=\z@
   \ifx #1\TD@percent@token
      \expandafter\TD@module
   \else
      \global\advance \c@codelineno \@ne
      \TD@begin@tclpar
      \expandafter\TD@count@indent \expandafter#1%
   \fi
}
%    \end{macrocode}
%    \begin{macrocode}
\let\TD@start@n@line=\TD@start@n@line@
\def\TD@start@n@line@i{\futurelet\next\TD@start@n@line@}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
% 
% 
% \begin{macro}{\TD@count@indent}
%   The purpose of the |\TD@count@indent| macro is to compute the 
%   indentation of the current line. It grabs the next character, and 
%   as long as that is a space or tab it will just increment 
%   |\TD@line@indent| accordingly and continue with the next character. 
%   |!| and |"| are used to make space and tab respectively with 
%   suitable catcode.
%   \DoNotIndex{\!,\",\ ,\^}
%    \begin{macrocode}
\begingroup
   \catcode`\!=\active
   \catcode`\"=\active
   \lccode`\!=`\ %
   \lccode`\"=`\^^I%
   \lowercase{%
\endgroup
   \def\TD@count@indent#1{%
      \ifx !#1%
         \global\advance \TD@line@indent \@ne
         \expandafter\TD@count@indent
      \else \ifx "#1%
            \global\divide \TD@line@indent \TD@tab@size
            \global\advance \TD@line@indent \@ne
            \global\multiply \TD@line@indent \TD@tab@size
            \expandafter\expandafter \expandafter\TD@count@indent
         \else
            \TD@setup@parshape
            \expandafter\expandafter \expandafter#1%
      \fi\fi
   }%
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\TD@module}
%   When command mode has been properly established it is time to 
%   check if the next character is |<|, in which case the following 
%   \package{docstrip} guard must be processed.
%   \changes{v\,2.13}{2000/12/20}{Always check whether the current line 
%      is a guard line, since the \texttt{\PrintChar{\number`\<}} in 
%      the guard would otherwise start a new paragraph, which is an 
%      error. (LH)}
%    \begin{macrocode}
\def\TD@module{%
   \TD@command
   \futurelet\next
   \TD@ch@angle
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\TD@ch@angle}
%   The module checking in \package{tcldoc} takes advantage of the 
%   macros for this in \package{doc}---|\ch@plus@etc| is a \package{doc} 
%   macro. |<| is active because it is in the nolig list 
%   (|\verbatim@|\-|nolig@|\-|list|).
%    \begin{macrocode}
\begingroup
   \catcode`<=\active
   \gdef\TD@ch@angle{%
      \ifx <\next
         \global\advance \c@codelineno \@ne
         \TD@begin@tclpar
         \expandafter\futurelet \expandafter\next
         \expandafter\ch@plus@etc
      \fi
   }
\endgroup
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@pm@module}
%   The |\TD@pm@module| macro is used instead of \package{doc}'s 
%   |\pm@module| when in the \texttt{tcl} environment. This is necessary 
%   since the paragraph man\oe uvres of the \texttt{tcl} environment would 
%   not work right with \package{doc}'s |\pm@module|.
%   
%   If we're not dealing with a block directive (|*| or |/|), i.e., 
%   it's a single special line, we set everything up to the next |>| 
%   appropriately, return to normal mode, possibly change font, and 
%   start counting indentation spaces.
%   \DoNotIndex{\>}
%    \begin{macrocode}
\begingroup
   \catcode`\>=\active
   \gdef\TD@pm@module#1>{%
      \Module{#1}%
      \TD@normal
      \ifnum \guard@level<\c@StandardModuleDepth \else
         \AltMacroFont
      \fi
      \TD@count@indent
   }
\endgroup
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\TD@star@module}
% \begin{macro}{\TD@slash@module}
%   The |\TD@star@module| and |\TD@slash@module| macros are, like 
%   |\TD@pm@module|, used instead of \package{doc}'s |\star@module| and 
%   |\slash@module| respectively when in the \texttt{tcl} environment. 
%   The only difference is that the |\TD@|\textellipsis\ macros also end 
%   the paragraph started in |\TD@ch@angle|, but without that 
%   difference, the module guard would incorrectly be reported as 
%   ``horizontal material on command line''.
%   \DoNotIndex{\>}
%    \begin{macrocode}
\begingroup
   \catcode`\>=\active
   \gdef\TD@star@module#1>{%
      \Module{#1}\TD@end@tclpar
      \global\advance \guard@level \@ne
      \ifnum \c@StandardModuleDepth<\guard@level
         \global\let\macro@font=\AltMacroFont 
         \macro@font
      \fi
   }
   \gdef\TD@slash@module#1>{%
      \Module{#1}\TD@end@tclpar
      \global\advance \guard@level \m@ne
      \ifnum \guard@level=\c@StandardModuleDepth
         \global\let\macro@font\MacroFont
         \macro@font
      \fi
   }
\endgroup
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% 
% \begin{macro}{\TD@gobble@whitespace}
%   This macro gobbles all normal mode spaces and tabs following it.
%    \begin{macrocode}
\def\TD@gobble@whitespace#1{%
   \if \ifx #1\TD@active@space 
          0%
       \else
          \ifx #1\TD@active@tab 0\else 1\fi
       \fi 0%
      \expandafter\TD@gobble@whitespace
   \else
      \expandafter#1%
   \fi
}
%    \end{macrocode}
% \end{macro}
% 
% 
% 
% \subsection{Typographical elements}
% 
% This subsection contains definitions of the typographical 
% elements---special symbols and the like--that are used in the 
% \texttt{tcl} and \texttt{tcl*} environments.
% 
% 
% \begin{macro}{\TD@typography}
% \begin{macro}{\TD@nontcl@font}
%   The |\TD@typography| macro does all the typographic set-up that is 
%   common to the \texttt{tcl} environment, the \texttt{tcl*} 
%   environment, and the |\tclverb| command.
%   
%   The |\TD@nontcl@font| macro selects an ``escape'' font for \Tcl\ 
%   material. This font is used for various kinds of escape codes that 
%   are typeset instead of some character---either because the 
%   character is not available, or because the line needs to be broken. 
%   The escape font will have the same font family (and same encoding) 
%   as the text surrounding the \texttt{tcl} environment or |\tclverb| 
%   command. Therefore |\TD@nontcl@font| must be defined before the 
%   \Tcl\ material font is selected. I don't think it is necessary to 
%   use |\protected@edef| below, but it can't hurt either.
%    \begin{macrocode}
\def\TD@typography{%
   \protected@edef\TD@nontcl@font{%
      \noexpand\fontencoding{\cf@encoding}%
      \noexpand\fontfamily{\f@family}\noexpand\selectfont
   }%
%    \end{macrocode}
%   The most frequent escape symbol is the single backslash used for 
%   escaping the end of lines, and this is stored in the 
%   |\TD@backslash@box| box.
%   
%   The following code have to do with how characters outside 
%   visible ASCII are typeset when they appear in the \texttt{tcl} or 
%   \texttt{tcl*} environment. The commands are defined by the 
%   \package{rtkinenc} package.
%    \begin{macrocode}
   \InputModeCode
   \SetUnavailableAction{\leavevmode{%
      \TD@nontcl@font\textbackslash x\TypesetHexNumber{##1}%
   }}%
   \DeclareInputMath{0}{\RIE@undefined{0}}%
   \DeclareInputMath{12}{\RIE@undefined{12}}%
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\TD@typeset@space}
%   This macro typesets a space, as it should be in the \texttt{tcl} 
%   environment (and other places too). It generates a kern, not glue, so 
%   that it can be used in a |\discretionary|.
%    \begin{macrocode}
\def\TD@typeset@space{\kern\fontdimen\tw@\font}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@discretionary@space}
%   This is the macro which offers all the breakpoints in |\tclverb| 
%   code. The name comes from the fact that all the breakpoints are 
%   discretionaries which appear to be spaces when not broken. When 
%   they are broken, they are backslashes. To give some visual hint 
%   that these backslashes need not be backslashes in the source, they 
%   are typeset in the same font family (and same encoding) as the 
%   text surrounding the \texttt{tcl} environment. 
%    \begin{macrocode}
\def\TD@discretionary@space{%
   \discretionary{\copy\TD@backslash@box}{}{\TD@typeset@space}%
}%
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@breakable@space}
%   The valid breakpoints inside  \texttt{tcl} and \texttt{tcl*} 
%   environments are made in the |\TD@|\-|breakable@|\-|space| macro. 
%   This macro contributes an |\hbox| (which contains a 
%   |\TD@typeset@space|), a penalty, and an empty |\vadjust| to the 
%   current horizontal list. If a line break is made at the penalty, 
%   the |\hbox| will later be removed and replaced by a non-macro font 
%   backslash (from |\TD@backslash@box|). The |\vadjust| is there to 
%   prevent that any discardable items disappears after the breakpoint.
%    \begin{macrocode}
\def\TD@breakable@space{%
   \hbox{\TD@typeset@space}%
   \TD@nesting@penalty
   \vadjust{}%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@typeset@tab}
%   This is an unbreakable space whose width equals that of 
%   |\TD@tab@size| spaces.
%    \begin{macrocode}
\def\TD@typeset@tab{\kern\TD@tab@size\fontdimen\tw@\font}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@visible@whitespace}
%   The |\TD@visible@whitespace| macro locally redefines the macros 
%   which typesets spaces and tabs to make visible symbols. The visible 
%   tab is roughly a |\rightarrowfill| and a |\vrule|, but a difference 
%   is that the minuses that form the extensible ``tail'' to the 
%   |\rightarrow| are not smashed. Not doing that gives the |\vrule| a 
%   suitable height, but I had rather expected the nominal height of 
%   the |\rightarrow| to be larger \textellipsis\ It's yet another 
%   mysterious math font feature, I suppose.
%   
%    \begin{macrocode}
\def\TD@visible@whitespace{%
   \def\TD@typeset@space{\char32 }%
   \def\TD@typeset@tab{%
      \hb@xt@\TD@tab@size\fontdimen\tw@\font{%
         $\m@th-\mkern-7mu%
         \cleaders\hbox{$\mkern-2mu-\mkern-2mu$}\hfill
         \mkern-7mu\mathord\rightarrow\mkern-1mu\vrule\mkern1mu$%
      }%
   }%
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{Catcodes and active characters}
% 
% Like any \texttt{verbatim}-like environment, the \texttt{tcl} 
% environment does some rather extensive alterations of catcodes. This 
% is handled by the three macros |\TD@general|, |\TD@normal|, and 
% |\TD@command|. Set-up that is common for both modes is made by 
% |\TD@general| when the \texttt{tcl} environment is entered. 
% Mode-dependent set-up is made by |\TD@normal| and |\TD@command| 
% whenever a mode switch occurs.
% 
% \begin{macro}{\TD@let@active}
%   One technicality here is that all of these routines need to set the 
%   definition of some active character, and this character is often not 
%   active with normal \LaTeX\ catcodes. To overcome this difficulty, 
%   there is a macro |\TD@let@active| which takes two arguments: a 
%   control sequence with a single character name, and an arbitrary 
%   control sequence. The active character with the same name as the 
%   first control sequence is |\let| locally to the second control 
%   sequence.
%    \begin{macrocode}
\begingroup
   \catcode\z@=\active
   \gdef\TD@let@active#1{%
      \begingroup
         \lccode\z@=`#1%
         \lowercase{%
      \endgroup
         \let^^@%
      }%
   }%
\endgroup
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\TD@general}
%   The |\TD@general| macro does the initial set-ups that are common for 
%   both modes of the \texttt{tcl} environment and for the |\tclverb| 
%   command. These include definitions of various active characters and 
%   |\catcode| assignments.
%   
%   \DoNotIndex{\^,\ ,\\,\[,\]}
%   \DoNotIndexHarmless{\PrintChar{`\{}}
%   \DoNotIndexHarmless{\PrintChar{`\}}}
%    \begin{macrocode}
\def\TD@general{%
   \let\do\do@noligs
   \verbatim@nolig@list
   \let\do\@makeother
   \dospecials
   \catcode`\^^M=\active
   \TD@let@active\^^I\TD@active@tab
   \TD@let@active\^^M\TD@active@CR
   \TD@let@active\ \TD@active@space
   \TD@let@active\\\TD@active@backslash
   \TD@let@active\{\TD@active@braceleft
   \TD@let@active\}\TD@active@braceright
   \TD@let@active\[\TD@active@bracketleft
   \TD@let@active\]\TD@active@bracketright
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\TD@normal}
%   This macro sets up the normal mode, changing everything that is 
%   different in any of the other modes. Note that the catcodes in 
%   normal mode are such that no character is a space. This makes it 
%   possible for macros used in normal mode to look ahead by simply 
%   grabbing the next character in an undelimited argument.
%   \DoNotIndex{\^,\ ,\\,\[,\]}
%   \DoNotIndexHarmless{\PrintChar{`\{}}
%   \DoNotIndexHarmless{\PrintChar{`\}}}
%    \begin{macrocode}
\def\TD@normal{%
   \catcode`\^^I=\active
   \catcode`\ =\active
   \catcode`\\=\active
   \catcode`\{=\active
   \catcode`\}=\active
   \catcode`\[=\active
   \catcode`\]=\active
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@command}
%   This macro switches from normal mode to command mode.
%   \DoNotIndex{\^,\ ,\\,\[,\]}
%   \DoNotIndexHarmless{\PrintChar{`\{}}
%   \DoNotIndexHarmless{\PrintChar{`\}}}
%    \begin{macrocode}
\def\TD@command{%
   \catcode`\^^I=10%
   \catcode`\ =10%
   \catcode`\[=12%
   \catcode`\]=12%
   \catcode`\\=\z@
   \catcode`\{=\@ne
   \catcode`\}=\tw@
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\TD@active@space}
% \begin{macro}{\TD@active@space@}
%   This macro is used for spaces in normal mode. Its main problem is 
%   to determine whether it is followed by more whitespace or not. If it 
%   is, then it is an unbreakable space. If it isn't, then it is a 
%   breakable space.
%    \begin{macrocode}
\def\TD@active@space#1{%
   \ifx #1\TD@active@backslash
      \expandafter\TD@active@space@
   \else
      \ifx #1\TD@active@space
         \TD@typeset@space
      \else\ifx #1\TD@active@tab
         \TD@typeset@space
      \else
         \TD@breakable@space
      \fi\fi
      \expandafter#1%
   \fi
}
%    \end{macrocode}
%   The special case to look out for is that the next character is a 
%   backslash which escapes a newline.
%    \begin{macrocode}
\def\TD@active@space@#1{%
   \ifx #1\TD@active@CR
      \TD@typeset@space
   \else
      \TD@breakable@space
   \fi
   \TD@active@backslash #1%
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\TD@active@tab}
%   The |\TD@active@tab| macro is what the active character tab is 
%   |\let| to inside the \texttt{tcl} and \texttt{tcl*} environments.
%    \begin{macrocode}
\def\TD@active@tab{\TD@typeset@tab}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@active@CR}
%   This macro is called at the end of a line. The |\catcode| tests the 
%   current mode.
%   \DoNotIndex{\\}
%    \begin{macrocode}
\def\TD@active@CR{%
   \ifnum \catcode`\\=\z@
      \ifvmode\else
         \PackageError{tcldoc}{Horizontal material on command line}\@ehc
         \@@par
      \fi
      \TD@normal
   \else
      \TD@end@tclpar
   \fi
   \TD@start@n@line
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@active@CRv}
%   This is what |\tclverb| defines the |^^M| active character as 
%   being. Cf.\ the standard \LaTeX\ macro |\verb@eol@error|.
%    \begin{macrocode}
\def\TD@active@CRv{%
   \verb@egroup
   \PackageError{tcldoc}{\protect\tclverb\space ended by end of line}%
     \@ehc
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\TD@active@backslash}
%   \changes{v\,2.10}{2000/10/08}{First checking if next character is 
%      active, and only expands the macro containing the detailed tests 
%      if it is. (LH)}
% \begin{macro}{\TD@active@backslash@}
% \begin{macro}{\TD@active@backslash@v}
%   |\TD@active@backslash| is used for backslashes in normal mode. Its 
%   main problem is to determine whether the backslash is escaping 
%   something (which would normally be treated specially by the 
%   environment) or not. The primary test for this is whether the 
%   argument grabbed is an active character, and if it is then 
%   processing continues (in |\TD@active@backslash@|) to determine what 
%   should be done.
%    \begin{macrocode}
\def\TD@active@backslash#1{%
   \ifcat \noexpand#1\noexpand~%
      \expandafter\TD@active@backslash@
   \else
      \@backslashchar
   \fi
   #1%
}
%    \end{macrocode}
%   
%   \changes{v\,2.11}{2000/11/06}{Escaped spaces are no longer breakable. 
%      (LH)}
%    \begin{macrocode}
\def\TD@active@backslash@#1{%
   \ifcase
      \ifx #1\TD@active@CR 0%
      \else\ifx #1\TD@active@backslash 1%
      \else\ifx #1\TD@active@braceleft 2%
      \else\ifx #1\TD@active@braceright 2%
      \else\ifx #1\TD@active@bracketleft 2%
      \else\ifx #1\TD@active@bracketright 2%
      \else\ifx #1\TD@active@space 3%
      \else 4\fi\fi\fi\fi\fi\fi\fi
   \space
      \expandafter\TD@active@backslash@i
   \or
      \@backslashchar\@backslashchar
   \or
      \@backslashchar \string#1%
   \or
      \@backslashchar \TD@typeset@space
   \else
      \@backslashchar
      \expandafter#1%
   \fi
}
%    \end{macrocode}
%   Escaped newlines that are followed by command mode lines are not 
%   converted to discretionary spaces.
%    \begin{macrocode}
\def\TD@active@backslash@i#1{%
   \ifx #1\TD@percent@token
      \copy\TD@backslash@box
      \expandafter\TD@active@CR
   \else
      \TD@breakable@space
      \global\advance \c@codelineno \@ne
      \expandafter\TD@gobble@whitespace
   \fi
   #1%
}
%    \end{macrocode}
%   The |\tclverb| command uses |\TD@active|\-|@backslash@v| instead of
%   |\TD|\-|@active|\-|@backslash@i|, since it is intended for use on 
%   lines that may begin with |%|.
%    \begin{macrocode}
\def\TD@active@backslash@v#1{%
   \TD@discretionary@space
   \ifx #1\TD@percent@token
      \expandafter\@firstoftwo
   \fi
   \TD@gobble@whitespace #1%
}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
% 
% 
% \begin{macro}{\TD@active@braceleft}
% \begin{macro}{\TD@active@braceright}
% \begin{macro}{\TD@active@bracketleft}
% \begin{macro}{\TD@active@bracketright}
%   These macros mainly typeset the corresponding characters, but they 
%   also increase or decrease the |\TD@nesting@level| count by one.
%   \DoNotIndex{\[,\]}
%   \DoNotIndexHarmless{\PrintChar{`\{}}
%   \DoNotIndexHarmless{\PrintChar{`\}}}
%    \begin{macrocode}
\begingroup
   \catcode`\{=12 \catcode`\}=12 
   \catcode`\[=1 \catcode`\]=2
   \gdef\TD@active@braceleft[{\advance\TD@nesting@level\@ne]
   \gdef\TD@active@braceright[}\advance\TD@nesting@level\m@ne]
\endgroup
%    \end{macrocode}
%    \begin{macrocode}
\def\TD@active@bracketleft{[\advance\TD@nesting@level\@ne}
\def\TD@active@bracketright{]\advance\TD@nesting@level\m@ne}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}
% 
% 
% 
% \subsection{Paragraph formatting}
% 
% This subsection contains definitions of control sequences that are 
% mainly related to the formatting of paragraphs.
% 
% The new implementation of the \texttt{tcl} and \texttt{tcl*} 
% environments is based on inserting the ``discretionary'' backslashes 
% at the linebreaks \emph{after} the paragraph has been broken. 
% Doing this involves reboxing every line in the paragraph, and in this 
% process the line adjustments are changed as well.
% 
% \begin{macro}{\TD@backslash@box}
%   The |\TD@backslash@box| box register is set to a backslash in the 
%   special |\TD@nontcl@font| at the beginning of each \texttt{tcl} and 
%   \texttt{tcl*} environment. These backslashes are used to denote 
%   ``backslash escaping newline''. The primary reason for keeping this 
%   glyph in a box is not that this might be slightly faster to 
%   typeset, but to have the \emph{width} of it easily accessible.
%    \begin{macrocode}
\newbox\TD@backslash@box
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@nesting@level}
% \begin{macro}{\TD@nesting@penalty}
%   |\TD@nesting@level| is a count register which keeps track of how 
%   many brace\slash bracket groups surrounds the current position in 
%   the line. It is cleared to zero at the beginning of each paragraph.
%    \begin{macrocode}
\newcount\TD@nesting@level
%    \end{macrocode}
%   |\TD@nesting@penalty| makes a |\penalty| whose value should depend 
%   on the nesting level (the deeper the nest, the larger the penalty). 
%   It may also adjust the value of |\linepenalty| to counter that 
%   the nesting level has become negative. This is typically needed for 
%   lines which say things like ``|} else {|''. The default definition is 
%   to make the nesting penalty $100$ times the nesting level and to 
%   make the |\linepenalty| equal to 
%   \(10 - \min\{0,\mbox{least penalty}\}\).
%    \begin{macrocode}
\def\TD@nesting@penalty{%
   \penalty \the\TD@nesting@level 00\relax
   \ifnum \lastpenalty<-\linepenalty
      \linepenalty=10%
      \advance \linepenalty -\lastpenalty
   \fi
}
%    \end{macrocode}
%   I doubt that this is necessarily the best algorithm for computing 
%   these penalties, so if you are really thorough about your 
%   typography you may well want to experiment with other definitions of 
%   |\TD@nesting@penalty|. In case you should then find something which 
%   works even better then I'm interested to learn about it.
% \end{macro}\end{macro}
% 
% \begin{macro}{\TD@reformat@lines}
%   The |\TD@reformat@lines| macro calls itself recursively to reformat 
%   all lines on the current vertical list. The first line will remain 
%   flush left, but all other lines will be reset flush right. The 
%   visible material on the last line will be left as it is, but the 
%   last box in all other lines will be replaced by a non-macro font 
%   backslash.
%   
%   It is very important that the current vertical list is not the main 
%   vertical list. 
%   It is assumed that the current vertical list consists of a sequence 
%   of \meta{box}, \meta{penalty}, \meta{glue}, with an extra glue item
%   at the top of the list. It is OK if some penalty or glue item is 
%   missing. In case the list contains other material as well the line 
%   reformatting may be stopped prematurely, but there is a trick that 
%   allows one to put arbitrary material between the lines of the 
%   reformatted paragraph: rather than doing e.g.
%   \begin{quote}
%     |\mark|\marg{text}
%   \end{quote}
%   in the paragraph, do
%   \begin{quote}
%     |\vadjust{\vbox{\mark{|\meta{text}|}}}|
%   \end{quote}
%   The |\vbox| will be recognised by the paragraph reformatting 
%   mechanism as a container for vertical mode material that appears 
%   between the lines of the paragraph, so it will simply be unboxed.
%   \changes{v\,2.12}{2000/11/11}{\cs{vbox} containers for vertical 
%      material are allowed between the lines of a reformatted 
%      paragraph. (LH)}
%   
%   Each line's horizontal list ends with
%   \begin{itemize}
%     \item a box (which contains the space that is to be replaced by a 
%       backslash),
%     \item a penalty (at which the paragraph was broken), and
%     \item a glue item (the |\rightskip|).
%   \end{itemize}
%   
%   A tricky feature in the implementation is that the 
%   |\bgroup|--|\egroup| nesting will be off by one. The |\bgroup| at 
%   the beginning of a |\TD@reformat@line| will be matched by the 
%   |\egroup| at the end of the |\TD@reformat@line| that the first one 
%   calls!
%    \begin{macrocode}
\def\TD@reformat@lines{%
   \bgroup
   \unskip
   \count@=\lastpenalty  \unpenalty
   \setbox\z@=\lastbox
   \ifvoid\z@
%    \end{macrocode}
%   The recursion had already descended down to the last line of the 
%   paragraph, and it is now time to reformat it.
%    \begin{macrocode}
      \egroup
      \prevdepth=\TD@prevdepth
      \hbox{%
         \unhbox\z@ 
         \unskip \unpenalty
         \setbox\z@=\lastbox
         \copy\TD@backslash@box
      }%
   \else
%    \end{macrocode}
%   Else there may be another line, and the |\TD@reformat@lines| recursion 
%   must continue to descend. Upon return the box currently in box 
%   register zero must be reformatted as a non-first line (flush 
%   right) and it cannot be the last line in the paragraph, so it is 
%   always correct to replace the last box by a backslash.
%    \begin{macrocode}
      \TD@reformat@lines
      \ifvbox\z@ \unvbox\z@ \else
         \hb@xt@\dimen@{%
            \hfill
            \unhbox\z@
            \unskip \unpenalty
            \setbox\z@=\lastbox
            \copy\TD@backslash@box
         }%
      \fi
   \fi
   \ifnum \count@=\z@ \else \penalty\count@ \fi
   \egroup
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@reformat@par}
%   The |\TD@reformat@par| macro reformats all lines (they're supposed 
%   to constitute a paragraph, but that isn't so important) in the 
%   current vertical list. The restrictions of |\TD@reformat@lines| on 
%   what may appear in the list apply and there must be at least two 
%   lines in the list. |\dimen@| is used to hold the desired width of 
%   reformatted paragraphs.
%   
%   More precisely |\TD@reformat@par| takes care of the last line of 
%   the paragraph and the possible |\vbox| containers for vertical 
%   material that may follow it. Everything in the paragraph that comes 
%   before the last line is handled by |\TD@reformat@lines|.
%   \changes{v\,2.12}{2000/11/11}{\cs{vbox} containers for vertical 
%      material are allowed after the last line of a reformatted 
%      paragraph. (LH)}
%    \begin{macrocode}
\def\TD@reformat@par{%
   \unskip
   \count@=\lastpenalty  \unpenalty
   \setbox\z@=\lastbox
   \ifvbox\z@
      \bgroup
      \TD@reformat@par
      \egroup
      \unvbox\z@
   \else\ifnum \prevgraf>\@ne
      \dimen@=\@totalleftmargin
      \advance \dimen@ \linewidth
      \bgroup
      \unskip
      \count@=\lastpenalty  \unpenalty
      \setbox\z@=\lastbox
      \TD@reformat@lines
      \hb@xt@\dimen@{\hfill \unhbox\z@ \unskip}%
   \else
      \unskip
      \prevdepth=\TD@prevdepth
      \box\z@
   \fi\fi
   \ifnum \count@=\z@ \else \penalty\count@ \fi
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@prevdepth}
%   |\TD@prevdepth| is a macro which is used for storing the value of 
%   |\prevdepth| at times where \TeX\ modifies the primitive in unwanted 
%   ways. It should always be set globally.
% \end{macro}
% 
% 
% \begin{macro}{\TD@begin@tclpar}
%   The |\TD@begin@tclpar| macro is called when a paragraph in a 
%   \texttt{tcl} or \texttt{tcl*} environment is about to start. It 
%   takes care of setting up things so that the paragraph can later be 
%   reformatted using |\TD@reformat@par|, but it also has to make sure 
%   that this reformatting doesn't affect the way the paragraph blends 
%   in with vertical material before and after it.
%   
%   Reformatting requires that the paragraph is first built in 
%   restricted vertical mode, i.e., it has to be built in an explicit 
%   |\vbox|. A problem with this is however that it changes the value of 
%   |\prevdepth|, which must therefore be explicitly restored.
%    \begin{macrocode}
\def\TD@begin@tclpar{%
   \xdef\TD@prevdepth{\the\prevdepth}%
   \setbox\z@=\vbox\bgroup
      \color@begingroup
      \prevdepth=\TD@prevdepth
      \indent
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@end@tclpar}
%   The |\TD@end@tclpar| macro ends a paragraph begun by 
%   |\TD@begin@tclpar|, reformats it (|\TD@reformat@par|), and 
%   contributes it to the surrounding vertical list. The |\begingroup| 
%   and |\endgroup| are there to sort things out in case the recursion 
%   in |\TD@reformat@par| fails to match as intended. The second 
%   |\@@par| sees to that the page builder is exercised (without it, 
%   several pages may go onto the main vertical list without anything 
%   being shipped out). 
%    \begin{macrocode}
\def\TD@end@tclpar{%
      \@@par
      \begingroup
         \skip@=\lastskip
         \TD@reformat@par
         \vskip\skip@
      \endgroup
      \xdef\TD@prevdepth{\the\prevdepth}%
      \color@endgroup
   \egroup
   \unvbox\z@
   \prevdepth=\TD@prevdepth
   \@@par
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\TD@line@indent}
%   |\TD@line@indent| is a |\count| register holding the indentation of 
%   the current line, in number of spaces. |\TD@line@indent| should 
%   always be assigned globally.
%    \begin{macrocode}
\newcount\TD@line@indent
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@par@setup}
%   This macro sets up various paragraph formatting parameters for the 
%   normal mode. It mainly consists of code from |\macro@code| of 
%   \package{doc}.
%    \begin{macrocode}
\def\TD@par@setup{%
%    \end{macrocode}
%   
%   In theory a \texttt{tcl} environment should consist of a 
%   \texttt{trivlist} environment, but the empty space before and after 
%   the environment should not be too large.
%    \begin{macrocode}
   \topsep\MacrocodeTopsep
%    \end{macrocode}
%   
%   The next parameter we set is |\@beginparpenalty|, in order
%   to prevent a page break before such an environment.
%    \begin{macrocode}
   \@beginparpenalty\predisplaypenalty
%    \end{macrocode}
%   
%   We then start a |\trivlist|, set |\parskip| back to
%   zero and start an empty |\item|.
%   \changes{ \package{doc} v\,1.9b}{1993/12/03}{Forcing any label 
%      from macro env.}
%    \begin{macrocode}
   \if@inlabel\leavevmode\fi
   \trivlist 
   \parskip\z@skip
   \item[]%
%    \end{macrocode}
%   However, the \texttt{trivlist} environment is only started to make 
%   standard \LaTeX\ happy (and to have the various list-related 
%   measurements properly calculated). Everything below will instead 
%   by done with \TeX\ primitives.
%   \changes{ \package{pasdoc} v\,1.31}{1999/09/02}{\cs{parshape} 
%     assignment added. (LH)}
%   \changes{v\,2.10}{2000/10/08}{\cs{parshape} assignment removed (now 
%      done in \cs{TD@begin@tclpar}). (LH)}
%   
%   It is important that the change to a special font does not take 
%   place before the above |\item|, otherwise a change to 
%   |\baselineskip| will affect the paragraph above.
%    \begin{macrocode}
   \macro@font
   \frenchspacing
%    \end{macrocode}
%   
%   \leavevmode
%   \changes{v\,2.12}{2000/11/11}{Assignment to \cs{TD@backslash@box} 
%      moved from \cs{TD@typography} to here, so that the size will be 
%      right. (LH)}^^A
%   One escape symbol that is particularly common is a single 
%   backslash, and this is stored in the |\TD@backslash@box| box. As 
%   some encodings (e.g.\ \texttt{OT1}) does not contain a backslash, 
%   these escape backslashes are made with |\textbackslash|, rather 
%   than an explicit character.
%    \begin{macrocode}
   \sbox\TD@backslash@box{\TD@nontcl@font\textbackslash}%
%    \end{macrocode}
%    
%   The |\rightskip| is given a generous stretchability of |\linewidth| 
%   so that it doesn't matter too much if the lengths of lines in the 
%   paragraph varies. Decreasing this value would make the nesting in 
%   the code less important.
%    \begin{macrocode}
   \parindent=\@totalleftmargin
   \advance \parindent \MacroIndent
   \leftskip=\z@skip
   \rightskip=\z@ \@plus \linewidth\relax
%    \end{macrocode}
%   The next two lines are from the definition of the 
%   \texttt{macrocode} environment, and I (LH) have no idea what they are 
%   good for, but I suppose I can keep them, at least for now.
%    \begin{macrocode}
   \global\@newlistfalse
   \global\@minipagefalse
%    \end{macrocode}
%   \changes{ \package{pasdoc} v\,1.31}{1999/09/02}{Made list 
%      environments indent line numbers. (LH)}
%   Line numbers are inserted using |\everypar|.
%    \begin{macrocode}
   \ifcodeline@index
      \everypar={\llap{\PrintCodelineNo\ }}%
   \else
      \everypar={}%
   \fi
%    \end{macrocode}
%   
%   These commands replace \package{doc}'s final module processing 
%   macros with macros that work in the \texttt{tcl} environment.
%    \begin{macrocode}
   \let\pm@module=\TD@pm@module
   \let\star@module=\TD@star@module
   \let\slash@module=\TD@slash@module
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@setup@parshape}
%   This macro sets the shape of the current paragraph, primarily based 
%   on the value in |\TD@line@indent|, and makes the final indentation 
%   of the first line. By the time it gets called, there usually already 
%   is some material (|\indent|, codeline number, and possibly a 
%   \package{docstrip} guard) in the paragraph horizontal list.
%   
%   The basic area in which the paragraph material is to be put has a 
%   left margin at |\@totalleftmargin|${}+{}$|\MacroIndent| and a right 
%   margin at |\@totalleftmargin|${}+{}$|\linewidth| (in both cases the 
%   position is that much to the right of the left edge of the galley). 
%   The printed codeline number (if there is one) will be put to the 
%   left of the left margin, but all other material is indented at least 
%   the width of another |\TD@line@indent| spaces. In the first line 
%   that will be done through an explicit kern, but in subsequent lines 
%   it will instead be done through a |\parshape| assignment. On these 
%   subsequent lines, there will be an additional indentation of\/ 
%   $1\,\mathrm{em}$ to mark the continuation.
%   
%   When the paragraph is broken, the right margin will be moved to the 
%   right by the width of a space minus the width of the 
%   |\TD@backslash@box|. The reason for this is that the paragraph will 
%   be broken with spaces (from |\TD@breakable@space|) at the end of 
%   lines, but that these spaces will later be replaced by the 
%   backslash in |\TD@backslash@box|. As that doesn't happen in the 
%   very last line of the paragraph however, something special must be 
%   done there. The option chosen is to give the |\parfillskip| a 
%   nonzero natural width.
%   
%   The length |\@totalleftmargin|${}+{}$|\MacroIndent| is put in 
%   |\parindent| at the beginning of the environment.
%    \begin{macrocode}
\def\TD@setup@parshape{%
   \parfillskip=\fontdimen\tw@\font \@plus 1fil%
   \advance \parfillskip -\wd\TD@backslash@box
   \dimen@=\MacroIndent
   \advance \dimen@ \TD@line@indent\fontdimen\tw@\font
   \advance \dimen@ 1em%
   \dimen@ii=\linewidth
   \advance \dimen@ii -\dimen@
   \dimen4=\linewidth
   \advance \dimen@ \@totalleftmargin
   \advance \dimen4 \@totalleftmargin
   \advance \dimen@ii -\parfillskip
   \advance \dimen4 -\parfillskip
   \parshape \tw@ \z@ \dimen4 \dimen@ \dimen@ii
%    \end{macrocode}
%   Then one just needs one more kern to indent the first line 
%   properly.
%    \begin{macrocode}
   \kern \TD@line@indent\fontdimen\tw@\font
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@trace@pardimen}
%   This macro is for tracing dimens that are of interest for paragraph 
%   breaking. Its call syntax is
%   \begin{quote}
%     |\TD@trace@pardimen|\marg{text}\marg{dimen}
%   \end{quote}
%   where \meta{text} will be written to the log file to identify the 
%   dimension, and \meta{dimen} is the dimen register in question (it 
%   can be anything that can appear after |\the|).
%   
%   To reduce the amount of text written, this macro only does anything 
%   if the \TeX\ parameter |\tracingparagraphs| is positive.
%    \begin{macrocode}
%<*partrace>
\def\TD@trace@pardimen#1#2{%
   \ifnum \tracingparagraphs>\z@
      \immediate\write\m@ne{#1 \the#2}%
   \fi
}
%</partrace>
%    \end{macrocode}
%   \changes{ \package{pasdoc} v\,1.21}{1999/08/15}{Added macro and 
%      some calls of it. All of those are however surrounded by 
%      \texttt{partrace} guards. (LH)}
% \end{macro}
% 
% 
% 
% \subsection{User interface}
% 
% This subsection defines the actual environment and the 
% commands and parameters intended to be user-definable.
% 
% 
% \begin{macro}{\settabsize}
%   \changes{v\,2.12}{2000/11/09}{New command for setting the tab size. 
%      (LH)}
% \begin{macro}{\TD@tab@size}
%   \changes{v\,2.12}{2000/11/09}{New name for \cs{c@tabSize}; no longer a 
%      count register. (LH)}
%   The |\TD@tab@size| control sequence stores (as a |\chardef| token) 
%   the number of spaces that are equivalent to one tab; the default 
%   value is 8. To set this number, one uses the command |\settabsize|, 
%   which has the syntax
%   \begin{quote}
%     |\settabsize|\marg{new size}
%   \end{quote}
%   The effect of |\settabsize| is local.
%    \begin{macrocode}
\newcommand*\settabsize[1]{\chardef\TD@tab@size=#1\relax}
\settabsize{8}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% 
% \begin{environment}{tcl}
% \begin{environment}{tcl*}
%   This is some kind of a definition. There are aspects of the 
%   interaction with \texttt{trivlist} that I (LH) don't understand, 
%   but it appears to work.
%    \begin{macrocode}
\newenvironment{tcl}{%
   \TD@general
   \TD@typography
   \TD@par@setup
   \TD@command
}{%
   \global\@inlabelfalse
   \endtrivlist
}
%    \end{macrocode}
%    \begin{macrocode}
\newenvironment{tcl*}{%
   \TD@visible@whitespace
   \TD@general
   \TD@typography
   \TD@par@setup
   \TD@command
}{%
   \global\@inlabelfalse
   \endtrivlist
}
%    \end{macrocode}
% \end{environment}\end{environment}
% 
% \begin{macro}{\tclverb}
% \begin{macro}{\TD@verb}
%   The |\tclverb| macro is for typesetting short passages of \Tcl\ code 
%   which one does not want to have a special paragraph for. It is 
%   similar to the standard \LaTeX\ command |\verb|, but it has a couple 
%   of extra features. One is that spaces that are not followed by more 
%   whitespace are discretionary breakpoints, just as in the \texttt{tcl} 
%   environment. Another is that a newline can be escaped by putting a 
%   backslash at the end of an input line. Such an escaped newline will 
%   count as a space, and whitespace at the beginning of the line 
%   following it will be ignored. A percent character immediately 
%   following an escaped newline will also be ignored.
%   
%   |\tclverb| has a |*| form |\tclverb*|, which is analogous to the 
%   standard \LaTeX\ |\verb*|, i.e., spaces are typeset using ``visible 
%   space'' symbols.
%    \begin{macrocode}
\newcommand\tclverb{%
   \relax\ifmmode\hbox\else\leavevmode\null\fi
   \bgroup
   \@ifstar{\TD@visible@whitespace\TD@verb}\TD@verb
}
%    \end{macrocode}
%  \DoNotIndex{\ ,\^,\\}
%    \begin{macrocode}
\def\TD@verb{%
   \let\TD@active@backslash@i=\TD@active@backslash@v
   \let\TD@active@CR=\TD@active@CRv
   \let\TD@breakable@space=\TD@discretionary@space
   \TD@general
   \catcode`\^^I=\active
   \catcode`\ =\active
   \catcode`\\=\active
   \TD@typography
   \verbatim@font
   \sbox\TD@backslash@box{\TD@nontcl@font\textbackslash}%
   \@sverb
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% 
% \begin{macro}{\TclInput}
%   The |\TclInput| macro is very much like the standard \LaTeX\ 
%   |\input|, but it is intended to be used in command mode, for 
%   inputting \Tcl\ files that have not been marked up. |\input| would 
%   work in this case, but there would be errors at the first and last 
%   lines of the |\input|ted file.
%    \begin{macrocode}
\newcommand\TclInput[1]{%
   \IfFileExists{#1}{%
      \@addtofilelist{#1}%
      \begingroup
         \TD@normal
         \let\TD@start@n@line=\TD@start@n@line@i
         \expandafter\TD@start@n@line
         \@@input\@filef@und\TD@percent@token
      \endgroup
   }{\PackageError{tcldoc}{No file #1}\@eha}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\MakeShortTclverb}
%   This definition follows \package{doc}'s |\MakeShortVerb| pretty 
%   close.
%   \DoNotIndex{\~}
%    \begin{macrocode}
\newcommand\MakeShortTclverb[1]{%
   \expandafter\ifx \csname cc\string#1\endcsname\relax
      \PackageInfo{tcldoc}{%
         Made \expandafter\@gobble\string#1 a short %
         reference for \string\tclverb}%
      \add@special{#1}%
      \expandafter\xdef \csname cc\string#1\endcsname{\the\catcode`#1}%
      \begingroup
         \lccode`\~=`#1%
         \lowercase{%
         \global\expandafter\let
            \csname ac\string#1\endcsname ~%
         \gdef~{\tclverb~}}%
      \endgroup
      \global\catcode`#1\active
   \else
      \PackageInfo{tcldoc}{%
         \expandafter\@gobble\string#1 already a short verb %
         reference}%
   \fi
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \section{Miscellaneous markup features}
% 
% \subsection{Namespaces}
% 
% \changes{v\,2.10}{2000/10/13}{Added namespace support. (LH)}
% 
% \begin{macro}{\setnamespace}
% \begin{macro}{\TD@namespace}
%   Since it is common that many identifiers in the same namespace are 
%   defined in sequence, one can specify a default namespace to use for 
%   all commands where no explicit namespace is given. This is done 
%   using the |\setnamespace| command, whose syntax is
%   \begin{quote}
%     |\setnamespace|\marg{namespace}
%   \end{quote}
%   This converts the \meta{namespace} to a harmless character string 
%   and locally assigns it to the |\TD@namespace| macro, which stores 
%   the current default namespace.
%    \begin{macrocode}
\newcommand\setnamespace[1]{\MakeHarmless\TD@namespace{#1}}
%    \end{macrocode}
%   At the beginning of a document, the default namespace is the global 
%   namespace, which is represented by the empty string.
%    \begin{macrocode}
\let\TD@namespace\@empty
%    \end{macrocode}
% \end{macro}\end{macro}
%   
% \begin{macro}{\buildname}
%   \changes{v\,2.13}{2000/12/16}{Added \cs{@empty} after test for 
%      \cs{NoValue}, so that it works for empty arguments. (LH)}
% \begin{macro}{\namespacesepator}
%   \changes{v\,2.12}{2000/11/25}{Command added. (LH)}
%   The |\buildname| macro builds a qualified name from a namespace and 
%   a name tail. It has the syntax
%   \begin{quote}
%     |\buildname|\marg{namespace}\marg{name}
%   \end{quote}
%   where \meta{name} is a harmless character sequence and 
%   \meta{namespace} is a harmless character sequence or the token 
%   |\NoValue|. If \meta{namespace} is |\NoValue| then the default 
%   namespace is used. |\buildname| does all processing at expand-time.
%   
%   If the namespace is the empty string (the global namespace) then 
%   \meta{name} is returned without a `|::|' prefix; this is for the 
%   sake of compatibility with pre-v\,8 \Tcl s.
%    \begin{macrocode}
\newcommand\buildname[2]{%
   \ifx \NoValue#1\@empty
      \ifx \@empty\TD@namespace \else 
         \TD@namespace\namespaceseparator 
      \fi
   \else
      \ifx $#1$\else #1\namespaceseparator \fi
   \fi
   #2%
}
%    \end{macrocode}
%   The |\namespaceseparator| command typesets a namespace separator. By 
%   default it is two colons separated by a penalty, but the user may 
%   redefine it.
%    \begin{macrocode}
\DeclareRobustCommand\namespaceseparator{:\penalty\hyphenpenalty:}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% 
% \subsection{\texttt{macro}-like environments}
% 
% This subsection contains the definitions of a couple of environments 
% which, like \package{doc}'s \texttt{macro}, are for marking up the 
% document (what is defined and where). These environments are defined 
% using the |\New|\-|Macro|\-|Environment| command of the \package{xdoc2} 
% package.
% \changes{ \package{pasdoc} v\,1.40}{1999/12/05}{\texttt{macro}-like 
%    environments redefined. (LH)}
% \changes{v\,2.00}{2000/07/17}{\texttt{macro}-like environments are 
%    defined using the \cs{NewMacroEnvironment} command. The 
%    \cs{TD@identifier}, \cs{SpecialMainTclIndex}, and 
%    \cs{PrintTclName} macros were removed. (LH)}
% \changes{v\,2.12}{2000/11/26}{Using starred form of 
%    \cs{NewMacroEnvironment} for the \texttt{variable}, \texttt{proc}, 
%    \texttt{arrayvar}, and \texttt{arrayentry} environments, so that 
%    the marginal headings can be broken. (LH)}
% 
%   
% \begin{environment}{variable}
%   The \texttt{variable} environment has the syntax
%   \begin{quote}
%     |\begin{variable}|\oarg{namespace}\marg{variable}
%   \end{quote}
%   It makes a marginal heading, index entry, etc.\@ for the 
%   \meta{variable} variable in the \meta{namespace} namespace 
%   (if specified, otherwise in the default namespace).
%    \begin{macrocode}
\NewMacroEnvironment*{variable}%
   {\XD@grab@harmless@oarg\XD@grab@harmless\relax}{2}%
   {\XDParToMargin{\MacroFont\buildname{#1}{#2} \normalfont (var.)}}%
   {\TD@main@index{#1}{#2}{var.}{}}%
   {{\buildname{#1}{#2}}{\texttt{\buildname{#1}{#2}} variable}}
   {}%
%    \end{macrocode}
% \end{environment}
% 
% \begin{environment}{proc}
%   The \texttt{proc} environment has the syntax
%   \begin{quote}
%     |\begin{proc}|\oarg{namespace}\marg{proc}
%   \end{quote}
%   It makes a marginal heading, index entry, etc.\@ for the \meta{proc} 
%   procedure in the \meta{namespace} namespace (if specified, otherwise 
%   in the default namespace).
%    \begin{macrocode}
\NewMacroEnvironment*{proc}%
   {\XD@grab@harmless@oarg\XD@grab@harmless\relax}{2}%
   {\XDParToMargin{\MacroFont\buildname{#1}{#2} \normalfont (proc)}}%
   {\TD@main@index{#1}{#2}{proc}{}}%
   {{\buildname{#1}{#2}}{\texttt{\buildname{#1}{#2}} proc}}
   {}%
%    \end{macrocode}
% \end{environment}
% 
% \begin{environment}{arrayvar}
%   \changes{v\,2.00}{2000/07/17}{Environment added. (LH)}
%   \changes{v\,2.12}{2000/11/09}{Made last argument optional. (LH)}
%   \changes{v\,2.13}{2000/12/15}{Not using \cs{meta} for the 
%      \meta{index-des} argument. (LH)}
% \begin{environment}{arrayentry}
%   \changes{v\,2.02}{2000/08/21}{Environment added. (LH)}
%   The \texttt{arrayvar} and \texttt{arrayentry} environments are for 
%   array variables; \texttt{arrayvar} is for the array as a whole, 
%   whereas \texttt{arrayentry} is for individual entries in the array 
%   that (for some reason) are important enough to warrant special 
%   attention. The respective syntaxes are
%   \begin{quote}
%     |\begin{arrayvar}|\oarg{namespace}\marg{array}\oarg{index-des}\\
%     |\begin{arrayentry}|\oarg{namespace}\marg{array}\marg{entry}
%   \end{quote}
%   Here \meta{array} is the name of an array variable, \meta{entry} is 
%   the name of an entry, and \meta{index-des} is a short piece of text 
%   (seldom more than one word) which describes what is used as indices 
%   into that array.
%    \begin{macrocode}
\NewMacroEnvironment*{arrayvar}{%
   \XD@grab@harmless@oarg\XD@grab@harmless\relax\XD@grab@harmless@oarg
}{3}%
   {\XDParToMargin{\MetaNormalfont\MacroFont \buildname{#1}{#2}%
      \ifx \NoValue#3%
         \space\normalfont (array)%
      \else
         \penalty\hyphenpenalty(\mbox{\meta@font@select#3})%
      \fi
   }}%
   {\TD@main@index{#1}{#2}{array}{%
      \ifx \NoValue#3\else
         \LevelSorted{#3}{\protect\mbox{\textit{#3}} entries}%
      \fi
   }}%
   {{\buildname{#1}{#2}}{\texttt{\buildname{#1}{#2}} array}}
   {}%
%    \end{macrocode}
%    \begin{macrocode}
\NewMacroEnvironment*{arrayentry}{%
   \XD@grab@harmless@oarg\XD@grab@harmless\relax\XD@grab@harmless\relax
}{3}%
   {\XDParToMargin{%
      \MetaNormalfont\MacroFont \buildname{#1}{#2}%
      \penalty\hyphenpenalty(#3)%
   }}%
   {\TD@main@index{#1}{#2}{array}{\LevelSorted{#3}{\texttt{#3}}}}%
   {{\buildname{#1}{#2}(#3)}{\texttt{\buildname{#1}{#2}(#3)}}}
   {}%
%    \end{macrocode}
% \end{environment}\end{environment}
% 
% \begin{macro}{\describestring}
%   \changes{v\,2.01}{2000/08/12}{Command added. (LH)}
%   \changes{v\,2.12}{2000/11/21}{Optional argument added. (LH)}
%   \changes{v\,2.13}{2000/12/16}{Second optional argument added. (LH)}
%   The |\describestring| command has the syntax
%   \begin{quote}
%     |\describestring|\oarg{type}\oarg{namespace}\marg{string}
%   \end{quote}
%   It is similar to \package{xdoc}'s own |\describe|\-|cs|\-|family| 
%   command, but it has a couple of extra features which are connected 
%   to the optional arguments and it doesn't prepend a backslash to 
%   the name of the thing being described. When the \meta{type} argument 
%   is present, it is taken as a ``type declaration'' of the 
%   \meta{string} being described and `(\meta{type})' will be put as a 
%   suffix to the \meta{string}. When the \oarg{namespace} argument is 
%   present it means that the string being described is really the name 
%   of something (e.g.\ a procedure or variable) which exists in a 
%   namespace, and the complete name is formed by passing both 
%   \meta{namespace} and \meta{string} as arguments to |\buildname|. 
%   Note that an empty \meta{namespace} argument is not quite the 
%   same thing as no \meta{namespace} argument.
%    \begin{macrocode}
\NewDescribeCommand{\describestring}{%
   \XD@grab@oarg\XD@grab@harmless@oarg\XD@grab@harmless{}%
}{3}{%
   \GenericDescribePrint{%
      \MetaNormalfont\MacroFont
      \ifx \NoValue#2\@empty
         #3%
      \else
         \buildname{#2}{#3}%
      \fi
      \ifx \NoValue#1\@empty \else\ \normalfont(#1)\fi
   }%
   \begingroup
      \def\meta##1{(##1)}%
      \unrestored@protected@xdef\@gtempa{%
         #3\ifx \NoValue#2\@empty \else\ifx $#2$\else, #2\fi\fi
      }%
   \endgroup
   \IndexEntry{%
      \LevelSorted{\@gtempa}{%
         \texttt{%
            \ifx \NoValue#2\@empty
               \protect\MetaNormalfont#3%
            \else
               \buildname{#2}{#3}%
            \fi
         }%
         \ifx \NoValue#1\@empty \else\space(#1)\fi
      }%
   }{usage}{\thepage}%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\TD@main@index}
%   \changes{v\,2.10}{2000/10/14}{Generalized macro. (LH)}
%   \changes{v\,2.12}{2000/11/25}{Sorting by base name first, not by 
%      namespace first. (LH)}
%   The |\TD@main@index| macro has the syntax
%   \begin{quote}
%     |\TD@main@index|\marg{namespace}\marg{name}\marg{type}^^A
%        \marg{extra}
%   \end{quote}
%   It makes a \texttt{main} index entry. The top level of this entry 
%   is like an entry for the \meta{name} object of type \meta{type} in 
%   the \meta{namespace} namespace. The entry may have one or more 
%   sublevels\footnote{But no more than one extra level is recommended, 
%   as this macro is intended to be redefinable to make a two-level 
%   entry by default and \package{makeindex} can handle at most three 
%   levels.} specified in the \meta{extra}; these are then made using 
%   explicit |\LevelSame| or |\LevelSorted| commands. \meta{name} and 
%   \meta{namespace} are as for the |\buildname| macro, whereas 
%   \meta{type} is a description, e.g. `\texttt{proc}', that gets 
%   appended to the printed text of the entry's top level.
%    \begin{macrocode}
\def\TD@main@index#1#2#3#4{%
   \XDMainIndex{%
      \LevelSorted{%
         #2%
         \ifx \NoValue#1%
            \ifx \@empty\TD@namespace \else , \TD@namespace\fi
         \else
             \ifx $#1$\else , #1\fi
         \fi
      }{\texttt{\buildname{#1}{#2}} (#3)}%
      #4%
   }%
}
%    \end{macrocode}
% \end{macro}
% 
%
% \subsection{Regular expressions and friends}
% 
% I have noticed that when one is describing the syntax of some \Tcl\ 
% command\slash procedure, one often ends up writing argument lists with 
% lots of optional, repeated, or variant parts. In general one can of 
% course specify these using BNF syntax diagrams, but whereas occurrences 
% of the three syntactic constructions mentioned above are plenty, 
% there are much fewer occurrences of for example nesting. Since 
% furthermore even the simplest optional or repeated element 
% requires an extra syntactic term to be defined, it becomes interesting 
% to search for an alternative way of specifying these constructions. 
% One that is close at hand is that of regular expressions, as that is 
% anyway a part of the \Tcl\ language.
% 
% \begin{macro}{\regstar}
% \begin{macro}{\regplus}
% \begin{macro}{\regopt}
%   These commands are used to modify the meaning of another syntactic 
%   element. |\regstar| puts a star $^*$ on something, meaning it is 
%   repeated zero or more times. |\regplus| puts a plus $^+$ on 
%   something, meaning it is repeated one or more times. |\regopt| puts 
%   a question mark $^?$ on something, meaning it is optional. Normally 
%   these commands are simply put right after what they should modify, 
%   but if the ``something'' is a regular expression block, i.e., a 
%   \texttt{regexp} environment, then these things should be put as the 
%   \meta{modifier} in
%   \begin{quote}
%     |\begin{regexp}|\oarg{modifier}\\
%     |  |\textellipsis\\
%     |\end{regexp}|
%   \end{quote}
%   In particular, they should \emph{not} be put after the 
%   |\end{regexp}|, as that may impair the placement of the exponent.
%    \begin{macrocode}
\newcommand\regstar{\ensuremath{^*}}
\newcommand\regplus{\ensuremath{^+}}
\newcommand\regopt{\ensuremath{^?}}
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}
% 
% \begin{macro}{\TD@delim@size}
% \begin{macro}{\TD@delim@size@G}
%   These control sequences are used in determining what size the 
%   delimiters (parentheses) around a regular expression block should 
%   have. The values specify what should be the least size of a 
%   delimiter that bracket a piece of text, and are interpreted as 
%   follows: \(0={}\)normal size, \(1={}\)|\big| size, \(2={}\)|\Big| 
%   size, \(3={}\)|\bigg| size, and $4$ and above is |\Bigg| size.
%   
%   |\TD@delim@size@G| is a macro which is always set globally and 
%   which keeps track of the delimiter size at the innermost level. 
%   |\TD@delim@size| is a |\count| register that is assigned locally 
%   and is used for keeping track of delimiter sizes at all other 
%   levels. Commands like |\word|, which contribute a delimiter to some 
%   piece of text, should set |\TD@delim@size@G|.
%    \begin{macrocode}
\newcount\TD@delim@size
\gdef\TD@delim@size@G{0}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{environment}{regexp}
%   The \texttt{regexp} environment embarks upon a rather tricky scheme 
%   of boxing and unboxing to determine the proper delimiter size. The 
%   basic idea is that the contents of the environment are first typeset 
%   in an \texttt{lrbox} environment, and |\TD@delim@size@G| is set to 
%   its proper value. Then the left delimiter is set at this size, the 
%   saved box is unboxed, and finally the right delimiter is set. All 
%   through the process, the value of |\TD@delim@size@G| at the 
%   beginning of the \texttt{regexp} environment has been saved in 
%   |\TD@delim@size| and at the end |\TD@delim@size@G| is set to the 
%   maximum of its old value and one plus its value inside the 
%   \texttt{regexp} environment. This makes it possible to nest 
%   \texttt{regexp} environments.
%   
%   It is not quite that easy, though. A regular expression can consist 
%   of several branches, which must be separated by vertical bars. 
%   These bars should be the same size as the delimiters around the 
%   regular expression, and hence the bars cannot be typeset before 
%   every branch has been typeset. Therefore the \texttt{regexp} 
%   environment starts an extra horizontal list (the |\hbox|) for the 
%   sole purpose of storing the branches that have already been typeset 
%   (and \emph{only} these). Each branch is put on the list as a box. 
%   When all branches have been typeset, they are first removed from the 
%   list (by |\TD@join@branches|), and then they are inserted again, but 
%   this time they are unboxed and separated by suitable delimiters. 
%   Finally the |\hbox| is ended and almost immediately unboxed.
%   
%    \begin{macrocode}
\newenvironment{regexp}[1][]{%
   \leavevmode
   \def\TD@modifier{#1}%
   \TD@delim@size=\TD@delim@size@G
   \let\regalt=\TD@regalt
   \setbox\z@=\hbox\bgroup
      \TD@delim@size=\z@
      \begin{lrbox}{\z@}%
         \gdef\TD@delim@size@G{0}%
         \ignorespaces
}{%
      \end{lrbox}%
      \ifnum \TD@delim@size@G>\TD@delim@size
         \TD@delim@size=\TD@delim@size@G\relax
      \fi
      {\TD@join@branches}%
      \unhbox\z@
      $\TD@size@delimiter)\TD@modifier$%
      \advance \TD@delim@size \@ne
      \xdef\TD@delim@size@G{\the\TD@delim@size}%
   \egroup
   \ifnum \TD@delim@size@G<\TD@delim@size
      \xdef\TD@delim@size@G{\the\TD@delim@size}%
   \fi
   \unhbox\z@
}
%    \end{macrocode}
% \end{environment}
% 
% \begin{macro}{\TD@join@branches}
%   \changes{v\,2.12}{2000/11/13}{Made penalty for linebreak after 
%      \cs{regalt} depend on the delimiter size. (LH)}
%   The |\TD@join@branches| macro uses |\lastbox| to retrieve all boxes 
%   in the current horizontal list, and unboxes them. Between the 
%   unboxed boxes it puts a |\vert| delimiter, and before the first it 
%   puts a left parenthesis. Both will be the current delimiter size.
%    \begin{macrocode}
\def\TD@join@branches{%
   \setbox\z@=\lastbox
   \ifvoid\z@
      $\TD@size@delimiter($%
   \else
      {\TD@join@branches}%
      \unhbox\z@
      ~$\TD@size@delimiter\vert$%
      \count@=\TD@delim@size
      \advance \count@ \@ne
      \multiply \count@ -\@lowpenalty
      \penalty\count@\ %
   \fi
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\regalt}
% \begin{macro}{\TD@regalt}
%   The |\regalt| command is used in a \texttt{regexp} environment 
%   to separate two branches. It ends an \texttt{lrbox} environment, 
%   puts the box collected in the surrounding horizontal list (which 
%   was begun by the |\hbox| in |\lrbox|), and begins a new 
%   \texttt{lrbox} environment. As this would not make sense outside a 
%   \texttt{regexp} environment however, the |\regalt| command does by 
%   default only produce an error message. The ``real'' definition is 
%   kept in |\TD@regalt| and the \texttt{regexp} environment locally 
%   redefines |\regalt|.
%    \begin{macrocode}
\newcommand\regalt{%
   \PackageError{tcldoc}{%
      Lonely \protect\regalt--perhaps a missing regexp environment%
   }\@eha
}
\def\TD@regalt{%
   \end{lrbox}%
   \box\z@
   \ifnum \TD@delim@size@G>\TD@delim@size
      \TD@delim@size=\TD@delim@size@G\relax
   \fi
   \begin{lrbox}{\z@}%
   \gdef\TD@delim@size@G{0}%
}
%    \end{macrocode}
% \end{macro}\end{macro}
% 
% \begin{macro}{\TD@size@delimiter}
%   This macro expands to nothing, |\big|, |\Big|, |\bigg|, or |\Bigg| 
%   depending on the value of |\TD@delim@size|.
%    \begin{macrocode}
\def\TD@size@delimiter{%
   \ifcase\TD@delim@size
      \or \expandafter\big \or \expandafter\Big \or
      \expandafter\bigg \else \expandafter\Bigg
   \fi
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\word}
%   \changes{v\,2.10}{2000/10/13}{Reimplemented like the new \cs{meta}. 
%      (LH)}
%   \changes{v\,2.12}{2000/11/21}{Using braces instead of angle brackets. 
%      (LH)}
%   This command works like |\meta|, but the argument is enclosed in 
%   braces rather than angle brackets and it communicates with the 
%   \texttt{regexp} environment (the braces count as a smallest-size 
%   delimiter). Something marked out using |\word| rather than |\meta| 
%   is meant to always denote a separate \Tcl\ word.
%    \begin{macrocode}
\DeclareRobustCommand\word[1]{%
   \leavevmode
   \ifmmode \expandafter \nfss@text \fi
   {%
      $\{$%
      \meta@font@select
      \edef\meta@hyphen@restore
         {\hyphenchar\the\font\the\hyphenchar\font}%
      \hyphenchar\font\m@ne
      \language\l@nohyphenation
      #1\/%
      \meta@hyphen@restore
      $\}$%
   }%
   \ifnum \TD@delim@size@G<\@ne \gdef\TD@delim@size@G{1}\fi
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{Logos}
% 
% \begin{macro}{\Tcllogo}
%   \changes{v\,2.03}{2000/09/15}{Macro added. (LH)}
%   The |\Tcllogo| command makes a \Tcl\ ``logo'', which simply consists 
%   of the three letters `T', `c', and `l' in the current font. The only 
%   special thing about it is that there is a kern between the `T' and 
%   the `c', since most fonts doesn't have that kern. No work has been 
%   put into tuning the kern, but the size is about right. As a 
%   comparison the kern between `T' and `o' in \texttt{cmr10} is 
%   $-0.083334\,\mathrm{em}$.
%    \begin{macrocode}
\DeclareRobustCommand\Tcllogo{T\kern-0.1em cl}
%</pkg>
%    \end{macrocode}
% \end{macro}
%  
% \changes{v\,2.03}{2000/09/15}{\cs{DescribeResource} command removed. 
%    Just in case anyone is interested in using it, I have included it as 
%    a code example in the source for the \package{xdoc} package. (LH)}
%  
% 
% \section{The \package{tcldoc} class}
% 
% \subsection{Pre-options definitions}
% 
% \begin{macro}{\if@rtkinenc@}
%   Switch. True iff the \package{rtkinenc} package should be loaded. 
%   It starts out false.
%    \begin{macrocode}
%<*class>
\newif\if@rtkinenc@
%    \end{macrocode}
% \end{macro}
% 
% 
% \subsection{Option declarations and processing}
% 
% \begin{option}{a5paper}
% \begin{option}{olddocinclude}
%   The \texttt{a5paper} (to the \package{article} document class) and 
%   the \texttt{olddocinclude} (to the \package{xdoc} package) are not 
%   supported for the \package{tcldoc} class.
%    \begin{macrocode}
\DeclareOption{a5paper}{%
   \ClassError{tcldoc}{The a5paper option is not supported}\@eha
}
\DeclareOption{olddocinclude}{%
   \ClassError{tcldoc}{The olddocinclude option is not supported}\@eha
}
%    \end{macrocode}
% \end{option}\end{option}
% 
% \begin{option}{macinputenc}
%   The \texttt{macinputenc} option enables some special code for 
%   supporting the typesetting of \Tcl\ code written for the Macintosh 
%   input encoding (cf.\ the \texttt{applemac} option to the 
%   \package{inputenc} package).
%    \begin{macrocode}
\DeclareOption{macinputenc}{%
   \PassOptionsToPackage{applemac}{rtkinenc}%
   \@rtkinenc@true
}
%    \end{macrocode}
% \end{option}
% 
%
%    \begin{macrocode}
\DeclareOption*{%
    \PassOptionsToClass{\CurrentOption}{article}}
%    \end{macrocode}
% 
% 
% 
% Input a local configuration file, if it exists.
%    \begin{macrocode}
\InputIfFileExists{tcldoc.cfg}
           {\typeout{*************************************^^J%
                     * Local config file tcldoc.cfg used^^J%
                     *************************************}}
           {}
%    \end{macrocode}
%    
%
%
%    \begin{macrocode}
\ProcessOptions\relax
%    \end{macrocode}
%
% \subsection{Loading the base class}
% 
%    \begin{macrocode}
\LoadClass{article}
%    \end{macrocode}
% 
% 
% \subsection{Input encoding and font representations}
% 
% There are some rather tricky issues concerning interpretation of the 
% input in \Tcl\ code. If the |\MacroFont| font contains a character that 
% correctly represents a character in the input, then that character is 
% obviously what one would like to appear in the typeset output. If no 
% font in the entire \TeX\ system contains a character that looks like 
% the one in the input, then just as obviously must one examine whether 
% there exists some other method of specifying that character. In the 
% case of \Tcl\ code, a suitable method seems to be to typeset the 
% equivalent |\x|\meta{dd} escape sequence instead. It is for the 
% purpose of being able to detect these cases that the \package{tcldoc} 
% class (if the user so requests) loads the \package{rtkinenc} package, 
% rather than the standard \LaTeX\ \package{inputenc} package.
% 
% The problem of determining for each input character which method of 
% representation that should be used---single character or escape 
% sequence---does not have a unique solution. Therefore the default 
% set-up is to not define any special fakes at all, which means the 
% escape sequence method will be chosen in the doubtful cases. There are 
% also a couple of options for the \package{tcldoc} class that define 
% all (or nearly all) possible fakes---the difference between them lie 
% in which fonts are assumed to be present in the system. A user who 
% does not like any of these predefined options also has the option of 
% putting the corresponding |\Declare|\-|Text|\-|Default|\textellipsis
% \ commands directly into the \texttt{tcldoc.cfg} file.
% 
%    \begin{macrocode}
\if@rtkinenc@
   \RequirePackage{rtkinenc}
%</class>
%    \end{macrocode}
% 
% \begin{macro}{\InputModeCode}
% \begin{macro}{\SetUnavailableAction}
% \begin{macro}{\DeclareInputMath}
% \begin{macro}{\RIE@undefined}
%   The \package{tcldoc} package uses some commands defined by the 
%   \package{rtkinenc} package, but since \package{rtkinenc} is not 
%   required by the \package{tcldoc} package, the \package{tcldoc} 
%   package must provide its own definitions, even though these can be 
%   no-ops. Definition of these commands is delayed until 
%   |\begin|\nolinebreak[1]|{document}| to avoid problems if the user 
%   loads the \package{rtkinenc} package after the \package{tcldoc} 
%   package.
%    \begin{macrocode}
%<*pkg>
\AtBeginDocument{%
   \providecommand*\InputModeCode{}%
   \providecommand*\SetUnavailableAction[1]{}%
   \providecommand*\DeclareInputMath[2]{}%
   \providecommand*\RIE@undefined[1]{\@inpenc@undefined}%
}
%</pkg>
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}
% 
% \begin{macro}{\.}
% \begin{macro}{\H}
% \begin{macro}{\textemdash}
% \begin{macro}{\textendash}
% \begin{macro}{\textexclamdown}
% \begin{macro}{\textquestiondown}
% \begin{macro}{\textquotedblleft}
%   The following text commands are defined by \texttt{OT1enc.def}, but 
%   their definitions will not work for \texttt{OT1}-encoded typewriter 
%   fonts. Therefore they are redefined, either so that they work 
%   anyway (|\textexclamdown| and |\textquestiondown|) or so that they 
%   call |\TextSymbolUnavailable| when \package{rtkinenc} is in code 
%   mode. This should make things work for the best in most 
%   reasonable situations.
%   
%   It could be noted here that the definitions below for |\.| and |\H| 
%   does not quite behave as if the commands had not been defined at 
%   all (I'm assuming that \package{rtkinenc} is in code mode here); an 
%   undefined command would leave its argument to be typeset, but the 
%   definitions below will swallow it in those cases.
%    \begin{macrocode}
%<*class>
   \DeclareTextCommand{\.}{OT1}[1]{%
      \IfInputModeCode{\TextSymbolUnavailable\.}%
         {\add@accent{95}{#1}}%
   }
   \DeclareTextCommand{\H}{OT1}[1]{%
      \IfInputModeCode{\TextSymbolUnavailable\H}%
         {\add@accent{125}{#1}}%
   }
   \DeclareTextCommand{\textemdash}{OT1}{%
      \IfInputModeCode{\TextSymbolUnavailable\textemdash}{\char 124 }%
   }
   \DeclareTextCommand{\textendash}{OT1}{%
      \IfInputModeCode{\TextSymbolUnavailable\textendash}{\char 123 }%
   }
   \DeclareTextCommand{\textexclamdown}{OT1}{!`}
   \DeclareTextCommand{\textquestiondown}{OT1}{?`}
   \DeclareTextCommand{\textquotedblleft}{OT1}{%
      \IfInputModeCode{\TextSymbolUnavailable\textquotedblleft}%
         {\char 92 }%
   }
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}\end{macro}\end{macro}
% \end{macro}
% 
% Several of the definitions in \texttt{applemac.def} can be improved. 
% Most of it is about seeing to that all characters have a proper text 
% mode definition, so that their unavailability can be trapped.
% 
%    \begin{macrocode}
   \def\@tempa{applemac}
   \ifx \@tempa\RIE@encoding
      \DeclareInputBoth{173}{\textneq}{\neq}
      \DeclareInputBoth{176}{\textinfty}{\infty}
      \DeclareInputBoth{177}{\textpm}{\pm}
      \DeclareInputBoth{178}{\textleq}{\leq}
      \DeclareInputBoth{179}{\textgeq}{\geq}
      \DeclareInputBoth{181}{\textmu}{\mu}
      \DeclareInputBoth{182}{\textpartial}{\partial}
      \DeclareInputBoth{183}{\textSigma}{\Sigma}
      \DeclareInputBoth{184}{\textPi}{\Pi}
      \DeclareInputBoth{185}{\textpi}{\pi}
      \DeclareInputBoth{186}{\textint}{\int}
      \DeclareInputBoth{189}{\textohm}{\Omega}
      \DeclareInputBoth{194}{\textlnot}{\lnot}
      \DeclareInputBoth{195}{\textsurd}{\surd}
      \DeclareInputBoth{197}{\textapprox}{\approx}
      \DeclareInputBoth{198}{\textDelta}{\Delta}
      \DeclareInputBoth{214}{\textdiv}{\div}
      \DeclareInputBoth{215}{\textdiamond}{\diamond}
      \DeclareInputBoth{218}{\textfractionsolidus}{/}
%    \end{macrocode}
% 
% Several of the above text commands are not defined in the \LaTeX\ 
% kernel. Therefore one must either define them in some encoding, or 
% define a default for them, to make them proper text commands. If they 
% are not then their unavailability cannot be trapped. |\textapplelogo| 
% appears in \texttt{applemac.def}.
%    \begin{macrocode}
      \ProvideTextCommandDefault{\textneq}{%
         \TextSymbolUnavailable\textneq
      }
      \ProvideTextCommandDefault{\textapplelogo}{%
         \TextSymbolUnavailable\textapplelogo
      }
      \DeclareTextSymbol{\textinfty}{OMS}{49}
      \DeclareTextSymbol{\textpm}{OMS}{6}
      \DeclareTextSymbol{\textleq}{OMS}{20}
      \DeclareTextSymbol{\textgeq}{OMS}{21}
%       \DeclareTextSymbol{\textmu}{TS1}{181}
      \DeclareTextSymbol{\textpartial}{OML}{64}
      \DeclareTextSymbol{\textSigma}{OT1}{6}
      \DeclareTextSymbol{\textPi}{OT1}{5}
      \DeclareTextSymbol{\textpi}{OML}{25}
      \DeclareTextSymbol{\textint}{OMS}{115}
      \DeclareTextSymbol{\textohm}{OT1}{10} % Kind of \textOmega
%       \DeclareTextSymbol{\textlnot}{TS1}{172}
%       \DeclareTextSymbol{\textsurd}{TS1}{187}
      \DeclareTextSymbol{\textapprox}{OMS}{25}
      \DeclareTextSymbol{\textDelta}{OT1}{1}
%       \DeclareTextSymbol{\textdiv}{TS1}{246}
      \DeclareTextSymbol{\textdiamond}{OMS}{5}
%       \DeclareTextSymbol{\textfractionsolidus}{TS1}{47}
      \input{TS1enc.def}
   \fi
\fi
%    \end{macrocode}
%    \begin{macrocode}
\let\if@rtkinenc@=\@undefined
\let\@rtkinenc@true=\@undefined
\let\@rtkinenc@false=\@undefined
%    \end{macrocode}
% The |@rtkinenc@| switch isn't needed any more, so it might just as 
% well be undefined.
% 
% 
% \subsection{The layout}
%
% Increase the text width slightly so that with the standard fonts
% 72 columns of code may appear in a |macrocode| environment.
% \changes{ \package{ltxdoc} v\,2.0c}{1994/03/15}{Set \cs{textwidth}.}
%    \begin{macrocode}
\setlength{\textwidth}{355pt}
%    \end{macrocode}
%
% Increase the marginpar width slightly, for long command names.
% And increase the left margin by a similar amount
% \changes{ \package{ltxdoc} v\,2.0l}
%      {1994/05/25}{Increase \cs{marginparwidth}}
% \changes{ \package{ltxdoc} v\,2.0q}{1995/11/28}
%      {Increase \cs{marginparwidth} and page margin.}
%    \begin{macrocode}
\addtolength\oddsidemargin{20pt}
\addtolength\evensidemargin{20pt}
%    \end{macrocode}
%
% 
% Change some defaults for list formatting. In particular, continue to 
% indent paragraphs in |\list| environments and don't put extra space 
% between them.
% \changes{ \package{pasdoc} v\,1.30}{1999/08/31}{Modifying the list 
%    formatting. (LH)}
% 
% \begin{macro}{\TD@list}
% \begin{macro}{\@listi}
% \begin{macro}{\@listI}
% \begin{macro}{\@listii}
% \begin{macro}{\@listiii}
% \begin{macro}{\@listiv}
% \begin{macro}{\@listv}
% \begin{macro}{\@listvi}
%    \begin{macrocode}
\def\@tempa#1{%
   \expandafter\def \expandafter#1\expandafter{#1\TD@list}%
}
\def\TD@list{%
   \advance \itemsep \parsep
   \parsep=\z@\@plus\p@\relax
   \advance \itemsep -\parsep
   \listparindent=1em\relax
}
\@tempa\@listi
\let\@listI\@listi
\@tempa\@listii
\@tempa\@listiii
\@tempa\@listiv
\@tempa\@listv
\@tempa\@listvi
%    \end{macrocode}
% \end{macro}\end{macro}\end{macro}\end{macro}\end{macro}\end{macro}
% \end{macro}\end{macro}
% 
%
% \subsection{Loading the \package{tcldoc} package}
% 
%    \begin{macrocode}
\RequirePackage[dolayout]{tcldoc}
%    \end{macrocode}
% 
% \begingroup
% Make \verb+|+ be a `short verb' character, but not in the document
% preamble, where an active character may interfere with packages that
% are loaded.
% \DoNotIndex{\|}
%    \begin{macrocode}
\AtBeginDocument{\MakeShortTclverb{\|}}
%    \end{macrocode}
% \endgroup
%
% As \texttt{.dtx} documents tend to have a lot of monospaced material,
% set up some \texttt{cmtt} substitutions to occur silently.
% \changes{ \package{ltxdoc} v\,2.0p}{1995/11/02}{Add font substitutions}
%    \begin{macrocode}
\DeclareFontShape{OT1}{cmtt}{bx}{n}{<-> ssub * cmtt/m/n}{}
\DeclareFontFamily{OMS}{cmtt}{\skewchar\font'60}
\DeclareFontShape{OMS}{cmtt}{m}{n}{<-> ssub * cmsy/m/n}{}
\DeclareFontShape{OMS}{cmtt}{bx}{n}{<-> ssub * cmsy/b/n}{}
%    \end{macrocode}
% This substitution is in the standard fd file, but not silent.
%    \begin{macrocode}
\DeclareFontShape{OT1}{cmss}{m}{it}{<->ssub*cmss/m/sl}{}
%    \end{macrocode}
%
% 
% \subsection{More layout}
% 
% \changes{v\,2.12}{2000/11/26}{Setting \cs{marginparwidth} so that the 
%    outer edge of the marginpar is $1\,\mathrm{cm}$ from the paper 
%    edge. (LH)}
% \changes{v\,2.12}{2000/11/27}{Rearranged code so that 
%    the \cs{marginparwidth} is set after \package{tcldoc} has been 
%    loaded; otherwise \package{doc} might overwrite it! (LH)}
%    \begin{macrocode}
\setlength\marginparwidth{\evensidemargin}
\addtolength\marginparwidth{1in}
\addtolength\marginparwidth{-\marginparsep}
\addtolength\marginparwidth{-1cm}
%    \end{macrocode}
% 
% 
%    \begin{macrocode}
\CodelineNumbered
\DisableCrossrefs
%    \end{macrocode}
%
%    \begin{macrocode}
\setcounter{StandardModuleDepth}{1}
%    \end{macrocode}
%
%
% \subsection{Useful abbreviations}
% \changes{v\,2.10}{2000/10/11}{\LaTeX\ abbreviation commands from 
%    \package{ltxdoc} commented out. (LH)}
% 
% The commands currently found in this section are inherited from the 
% \package{ltxdoc} package, but as they aren't of much use with \Tcl, 
% they have been commented out.
% 
% |\cmd{\foo}| Prints |\foo| verbatim. It may be used inside moving
% arguments. |\cs{foo}| also prints |\foo|, for those who prefer that
% syntax. (This second form may even be used when |\foo| is |\outer|).
% \begin{macro}{\cmd}
% \begin{macro}{\cs}
%   \DoNotIndex{\\}
%    \begin{macrocode}
% \def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}}
% \def\cmd@to@cs#1#2{\char\number`#2\relax}
% \DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\marg}
%    |\marg{text}| prints \marg{text}, `mandatory argument'.
%    \DoNotIndexHarmless{\PrintChar{`\{}}
%    \DoNotIndexHarmless{\PrintChar{`\}}}
%    \begin{macrocode}
% \providecommand\marg[1]{%
%   {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\oarg}
%    |\oarg{text}| prints \oarg{text}, `optional argument'.
%    \begin{macrocode}
% \providecommand\oarg[1]{%
%   {\ttfamily[}\meta{#1}{\ttfamily]}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\parg}
%    |\parg{te,xt}| prints \parg{te,xt}, `picture mode argument'.
%    \begin{macrocode}
% \providecommand\parg[1]{%
%   {\ttfamily(}\meta{#1}{\ttfamily)}}
%</class>
%    \end{macrocode}
% \end{macro}
%
%
% 
% 
% \changes{v\,2.00}{2000/07/17}{Section with \cs{DocInclude} removed, 
%    since that is defined by \package{xdoc}. (LH)}
% 
% \Finale
%
\endinput