summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/tcldoc/tclldoc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/tcldoc/tclldoc.dtx')
-rw-r--r--Master/texmf-dist/source/latex/tcldoc/tclldoc.dtx4065
1 files changed, 4065 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/tcldoc/tclldoc.dtx b/Master/texmf-dist/source/latex/tcldoc/tclldoc.dtx
new file mode 100644
index 00000000000..6106dcce36f
--- /dev/null
+++ b/Master/texmf-dist/source/latex/tcldoc/tclldoc.dtx
@@ -0,0 +1,4065 @@
+% \CheckSum{1849}
+%
+% \title{The \package{tclldoc} package and class}
+% \author{Lars Hellstr\"om^^A
+% \thanks{E-mail: \texttt{Lars.Hellstrom@math.umu.se}}
+% \emph{et al.}}
+% \date{2003/07/19}
+% \maketitle
+%
+% \iffalse
+%
+%<class|pkg>\NeedsTeXFormat{LaTeX2e}
+%<class>\ProvidesClass{tclldoc}
+%<compclass>\ProvidesClass{tcldoc}
+%<pkg>\ProvidesPackage{tclldoc}
+%<comppkg>\ProvidesPackage{tcldoc}
+%<class|pkg|compclass|comppkg> [2003/04/05 v2.40
+%<class|pkg> Tcl documentation
+%<compclass|comppkg> tclldoc compatibility
+%<class|compclass> class]
+%<pkg|comppkg> 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}%
+}{}
+\@ifundefined{instance}{%
+ \newenvironment{instance}[2]{%
+ \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\/$\}$}}
+
+\makeatletter
+\newcommand{\swtpc}{%
+ \sbox\z@{ }%
+ \expandafter\makebox \expandafter[\the\wd\z@]%
+ {\textperiodcentered}%
+}
+\makeatother
+
+\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{tclldoc.dtx}
+\PrintChanges
+\PrintIndex
+\end{document}
+%</driver>
+%
+% \fi
+%
+% \begin{abstract}
+% The \package{tclldoc} 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{tclldoc}
+% 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{tclldoc} package builds on the \package{doc},
+% \package{xdoc}~\cite{xdoc}, and \package{docindex}~\cite{docindex}
+% packages.
+%
+% Note: The \package{tclldoc} package and class used to be called
+% \package{tcldoc}, but it turned out that there already existed a
+% Perl~(!!)\ script \Tcl Doc that has a similar function. Therefore I
+% added an extra `\textsf{l}'---which stands for both \LaTeX\ and
+% Literate---to avoid confusing the community of \Tcl\ programmers.
+% For compatibility, a package and a class named \package{tcldoc} are
+% installed with \package{tclldoc}, but they shouldn't be used for
+% new documents.
+% \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{tclldoc} 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{tclldoc} 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{tclldoc} 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{tclldoc} 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}), the
+% \package{shortvrb} package (\texttt{shortvrb.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 has not 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 are
+% called the \emph{preamble} and those at 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 (such as the UNIX core) 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}
+% Similarly to begin the file by the three standard lines
+%\begin{verbatim}
+%#! /bin/sh
+%#\
+%exec tclsh "$0" ${1+"$@"}
+%\end{verbatim}
+% (for an explanation see~\cite{execMagic})---which on UNIX allow the file
+% to function both as a \Tcl\ script and a shell script which terminates
+% the shell and runs \texttt{tclsh} on the script instead---you can use
+% the command
+%\begin{verbatim}
+%\edef\defaultpreamble{%
+% \MetaPrefix! /bin/sh^^J%
+% \MetaPrefix\string\^^J%
+% exec tclsh "$0" ${1+"$@"}^^J%
+% \defaultpreamble
+%}
+%\end{verbatim}
+% The full explanation of these commands is however far beyond this
+% introduction.\footnote{Those who want to fully understand them should
+% read \emph{The \TeX book}~\cite{TeXbook}, in particular Chapter~8.}
+%
+% In summary, a \package{docstrip} installation script for extracting a
+% file \texttt{foo.tcl} from \texttt{foo.dtx}, using \Tcl\ style
+% comments, inserting a BSD-style license notice in the preamble, and
+% beginning with the line |# -*-Tcl-*-| could look as follows:
+%\begin{verbatim}
+%\input docstrip.tex
+%
+%\edef\MetaPrefix{\string#}
+%
+%\preamble
+%
+%Copyright (c) <YEAR>, <OWNER>
+%All rights reserved.
+%
+%Redistribution and use in source and binary forms, with or without
+%modification, are permitted provided that the following conditions
+%are met:
+%* Redistributions of source code must retain the above copyright
+%notice, this list of conditions and the following disclaimer.
+%* Redistributions in binary form must reproduce the above
+%copyright notice, this list of conditions and the following
+%disclaimer in the documentation and/or other materials provided
+%with the distribution.
+%
+%THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+%"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+%LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+%FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+%COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+%INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+%BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+%LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+%CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+%LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+%ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+%POSSIBILITY OF SUCH DAMAGE.
+%
+%\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')
+%#
+%# Copyright (c) <YEAR>, <OWNER>
+%# All rights reserved.
+%#
+%# Redistribution and use in source and binary forms, with or without
+%# modification, are permitted provided that the following conditions
+%# are met:
+%# * Redistributions of source code must retain the above copyright
+%# notice, this list of conditions and the following disclaimer.
+%# * Redistributions in binary form must reproduce the above
+%# copyright notice, this list of conditions and the following
+%# disclaimer in the documentation and/or other materials provided
+%# with the distribution.
+%#
+%# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+%# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+%# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+%# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+%# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+%# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+%# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+%# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+%# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+%# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+%# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+%# POSSIBILITY OF SUCH DAMAGE.
+%#
+%\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{tclldoc}
+%\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{tclldoc}
+%\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{tclldoc} class sets the
+% \texttt{StandardModuleDepth} counter to 1, which means that the
+% |\AltMacroFont| is used when the modules are nested 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}
+% 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{tclldoc} 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} \iffalse
+%</example>
+% \fi
+% or even
+%\begin{verbatim}
+% \begin{tcl}\TclInput{myscript.tcl}\end{tcl}
+%\end{verbatim}
+% anywhere in a \package{tclldoc} document. This works since the
+% \texttt{tcl} environment is in command mode right after the initial
+% |\begin{tcl}|, and the |\end{tcl}| needs not be the first command on a
+% command mode line.
+%
+%
+% \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. The command \DescribeMacro{\buildname}
+% |\buildname| is used by the commands and environments described here to
+% construct 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.
+%
+% A case which deserves special treatment is that of options of
+% commands and for that there is the \DescribeMacro{\describeopt}
+% |\describeopt| command. The syntax of this command is
+% \begin{quote}
+% |\describeopt|*\oarg{namespace}\marg{command}\oarg{type}^^A
+% \marg{option}
+% \end{quote}
+% where \meta{command} is the command whose option is being described
+% and \meta{option} is the name of the option. \meta{namespace} is the
+% namespace of the \meta{command} and defaults to the global namespace.
+% \meta{type} is the type of the command and defaults to |proc| for
+% procedure. The \meta{namespace}, \meta{command}, and \meta{type} are
+% (currently) only used in the index entry that is generated. Options
+% for procedures will be put as subentries of the main procedure entry.
+% For built-in commands it might be more appropriate to use |command| as
+% \meta{type}, e.g.
+% \begin{quote}
+% |\describeopt{lsort}[command]{-real}|
+% \end{quote}
+% will put ``\texttt{-real} option'' in the margin and in the index as
+% a subentry of ``\texttt{lsort} (command), global namespace''. The |*|
+% is optional---including it will supress the marginal note normally
+% generated by this command.
+%
+% Since \Tcl\ is often used together with C, it might be useful to
+% also have something similar to the \texttt{proc} environment for C
+% things. This is what the \DescribeEnv{Cfunction}\texttt{Cfunction},
+% \DescribeEnv{Cvariable}\texttt{Cvariable}, and \DescribeEnv{Ctype}
+% \texttt{Ctype} environments are for. These take as their only
+% argument the name of the identifier that is defined, e.g.
+%\begin{verbatim}
+% \begin{Cfunction}{main}
+%\end{verbatim}
+% Since there seems to be several schools on how C code should be
+% formatted when typeset, the formatting of identifiers passed to these
+% environments is configurable. The three commands
+% \DescribeMacro{\Cfunctionidentifier}|\Cfunctionidentifier|,
+% \DescribeMacro{\Cvariableidentifier}|\Cvariableidentifier|, and
+% \DescribeMacro{\Ctypeidentifier}|\Ctypeidentifier| handle all
+% typesetting of identifiers; each takes as its only argument the
+% identifier (as a harmless string) to typeset. The default is to set
+% the argument in italic; this is what CWEB does.
+%
+% If you are using the \texttt{C}\dots\ environments for identifiers
+% whose names contain underscores (\_), you may want to pass the
+% \describeoption{notrawchar}\texttt{notrawchar} to \package{tclldoc}
+% (it is really an option of the \package{xdoc} package and will be
+% passed on to that automatically). This option addresses a problem
+% with \texttt{OT1}-encoded fonts that may cause underscores to display
+% as a quite different character (the \texttt{cmtt} typewriter fonts are
+% however not affected by this problem).
+%
+%
+%
+% \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{regblock}^^A
+% \texttt{regblock} environment. The syntax of this environment is
+% \begin{quote}
+% |\begin{regblock}|\oarg{modifier}\quad\dots\quad |\end{regblock}|
+% \end{quote}
+% If \texttt{regblock} 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{regblock}
+% 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{regblock}[\regstar]|elseif| \word{expression}"\\
+% \verb"|then|\regopt\ \word{script}\end{regblock}"\\
+% \verb"\begin{regblock}[\regopt]|else| \word{script}\end{regblock}"
+% \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}
+% In versions of \package{tclldoc} before 2.40, the \texttt{regblock}
+% environment used to be called \DescribeEnv{regexp}\texttt{regexp}.
+% That other name is still supported, but should be avoided in new
+% documents.
+%
+% The final regular expression construction that is supported is that
+% of branches of a regular expression. A \texttt{regblock} 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{regblock} environment. The
+% |\regalt| command may only be used inside a \texttt{regblock}
+% 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{regblock}[\regstar]|-nocase|\regalt"\\
+% \verb"|-indices|\end{regblock} |--|\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
+% corresponds to parts of words or to several 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|'. In the
+% command |label .a -text "Hello there!"|, the last two arguments could
+% be summarised as an \meta{option}, but not as an \word{option}.
+%
+%
+% \subsection{Non-ASCII characters}
+%
+% One problem, which is only going to be more common in the future, is
+% how to deal with non-ASCII characters in scripts. The main problem
+% here lies not on the output side, as \LaTeX\ is actually pretty good
+% at producing a requested character as long as it is available in some
+% font, but on the input side. \LaTeX\ can handle input in most 8-bit
+% encodings, but in order for that to work the file must contain an
+% |\inputencoding| command which tells \LaTeX\ which encoding is being
+% used. As transporting a file from one platform to another most likely
+% changes the encoding, but not the argument of |\inputencoding|, this
+% method is rather fragile. Certainly there is room for improvements
+% but the world of 8-bit encodings is generally such a mess anyway that
+% it probably isn't worth the effort.
+%
+% A more progressive approach is to decide that all source code is in
+% Unicode (more precisely in UTF-8). The main arguments for this are:
+% (i)~\Tcl\ uses Unicode internally, (ii)~it is equally foreign on
+% all platforms and can be treated as binary data rather than ``extended
+% ASCII'' text, and (iii)~since it isn't converted, there is no loss of
+% data. Interestingly enough, \emph{it is possible to use UTF-8 ``out of
+% the box'' today!} Using the \package{ucs} package~\cite{ucs-package}
+% allows \LaTeX\ to interpret UTF-8 input and this works just as well
+% for the \Tcl\ code in a \texttt{tcl} environment as for the normal
+% \LaTeX\ text outside it. If \package{docstrip} is run on a \LaTeX\
+% format\footnote{Or, in some implementations, the \TeX\ program gets a
+% suitable option.} that preserves characters whose most significant
+% bit is set\footnote{Rather than converting them to
+% \texttt{\^{}\^{}}-sequences, which is the default.} then the non-ASCII
+% characters are simply copied verbatim and it makes no difference that
+% they may occupy more than one byte of data. Alternatively one can run
+% \package{docstrip} on Omega and (with a little extra work) get the
+% ability to have the \Tcl\ code translated to some other encoding as
+% the files are being generated!\footnote{At least in theory; I have to
+% admit I haven't actually tested the \package{docstrip} part of it.}
+%
+% But although the above paragraph describes the way to go in the long
+% run, there are some matters which make this approach slightly
+% unfeasible in the near future. This is of course my own subjective
+% opinion, but I find that two good reasons not to start using Unicode
+% throughout quite yet are that (i)~my favourite text editor doesn't
+% support Unicode (yet) and (ii)~even if I do start using it, there
+% wouldn't be that much people around who could make sense of such files
+% if I were to send it to them. Therefore I \emph{intend} to implement,
+% but as yet haven't, a kind of intermediate format where non-ASCII
+% Unicode characters are encoded using only ASCII characters plus an
+% extra escape character. The basic idea is simply that any string
+% `\meta{escape}\meta{hex digits}\meta{escape}' should be interpreted as
+% the Unicode character \texttt{U+}\meta{hex digits}, so that arbitrary
+% Unicode characters can be encoded using a character set that only
+% comprises ASCII plus one extra \meta{escape} character. Supposing that
+% this \meta{escape} character is the centered dot `\textperiodcentered',
+% I could then encode my name as
+% \begin{quote}
+% \texttt{Lars Hellstr\swtpc 00f6\swtpc m}
+% \end{quote}
+% whereas the centered dot itself would be \texttt{\swtpc 00b7\swtpc}.
+% The idea is that the file itself should contain the declaration of
+% which character is used as this Unicode escape, so that a change due
+% to translation from one 8-bit encoding to another will identically
+% alter both declaration and use of the escape character, thereby
+% preserving the internal logic of the file.
+%
+% The weak point with this scheme is that \package{docstrip} would have
+% to translate the escape sequences to proper characters when it
+% generates files. Implementing that under \TeX\ is highly non-trivial.
+% It can be done with a reasonable effort under Omega, but it still
+% requires hacking \package{docstrip}. The really interesting approach
+% would however be to implement it in a port of \package{docstrip} to
+% \Tcl, as that would remove the need to have \TeX\ to install the files.
+% Porting \package{docstrip} to \Tcl\ is by the way a project of mine
+% which I unfortunately haven't spent much time on, but if it is to be
+% of any use to have the Unicode escape format described above
+% implemented in \package{tclldoc} then I will have to make some
+% progress with it.
+%
+% \medskip
+%
+% One rather recent advancement in this direction is the code in
+% \texttt{sourcedtx.tcl}, which can be generated from the file
+% \texttt{sourcedtx.dtx} that is distributed with \package{tclldoc} as
+% an example. This implements a \Tcl\ command |dtx::source| that makes
+% it possible to source \Tcl\ code in a \texttt{.dtx} file without
+% docstripping it to a file first. This code does currently not bother
+% about encodings, but that is easy enough to add.
+%
+% \medskip
+%
+% Finally, a few notes on the old mechanism for non-ASCII characters
+% that is included in the \package{tcldoc} compatibility class. It
+% cooperates with the \package{rtkinenc} package~\cite{rtkinenc}, when
+% that has been loaded, in order to detect when an input character isn't
+% avaiable in any active font encoding. Rather than raising an error and
+% printing nothing it these cases, missing characters are written as the
+% corresponding |\x|\meta{hh} backslash sequence in a slightly different
+% font than the rest of the text. A problem here is however that most
+% input encodings contain a few characters which are interpreted as
+% \emph{math} character by \LaTeX. When such a character appears on a
+% code line it makes \TeX\ switch to math mode and things generally get
+% quite messy afterwards.
+%
+% The cure for this is to redeclare these input characters to \LaTeX\
+% so that they work as intended in text mode, but that does take some
+% lines of code. The \package{tcldoc} class does contain the
+% declarations needed for the \texttt{applemac} input encoding; passing
+% it the \describeoption{macinputenc}\texttt{macinputenc} option will
+% load the \package{rtkinenc} package, the \texttt{applemac} (macRoman)
+% input encoding, the \texttt{TS1} output encoding, and make the
+% necessary redeclarations to allow all input characters to work in
+% text. As nothing is provided for any other input encoding however,
+% this solution never was a good solution. The \texttt{macinputenc}
+% should be considered as unsupported as of \package{tclldoc} v\,2.30.
+%
+%
+%
+% \subsection{Options and customisation}
+%
+% The \package{tclldoc} package does not have any options of its own, but
+% all options passed to it are passed on to the \package{xdoc} package.
+% The \package{tclldoc} class accepts all options that the standard
+% \LaTeX\ document class \package{article} accepts, with the exception
+% of \texttt{a5paper}.
+%
+% Like the \package{ltxdoc} class, the \package{tclldoc} class will look
+% for a special configuration file \texttt{tclldoc.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 you use a \texttt{tclldoc.cfg} file to customise the
+% \package{tclldoc} 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{tclldoc} 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{tclldoc}
+% 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{tclldoc.cfg} is executed when
+% the \package{tclldoc} 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{times} package, use the command
+%\begin{verbatim}
+%\AtEndOfClass{\usepackage{times}}
+%\end{verbatim}
+% Using |\AtEndOfClass| like this delays the command until it may be
+% executed.
+%
+%
+% \subsection{Miscellanea}
+%
+% For writing ``\Tcl'', the \package{tclldoc} 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.)
+%
+% Between the namespace and the tail part of a qualified name, the
+% \package{tclldoc} package commands naturally put the name\-space
+% separator `|::|'. This text is stored in the macro
+% \DescribeMacro{\namespaceseparator}|\namespaceseparator|, which can be
+% redefined using the |\Declare|\-|Robust|\-|Command| command. This is
+% mainly useful for modifying how this separator behaves with respect to
+% line breaking; the default behaviour is that a line break can occur
+% between the colons.
+%
+% Another configurable piece of text is stored in the
+% \DescribeMacro{\namespacephrase}|\namespacephrase| macro. This
+% contains word `namespace' as that appears in index entries, e.g.~in
+% the last word of
+% \begin{quote}
+% \texttt{platform} (var.), \texttt{alpha} name\-space
+% \end{quote}
+% It is often convenient to replace this by something shorter. The
+% redefinition
+% \begin{quote}
+% |\renewcommand{\namespacephrase}{\textsc{ns}}|
+% \end{quote}
+% turns the above into
+% \begin{quote}
+% \texttt{platform} (var.), \texttt{alpha} \textsc{ns}
+% \end{quote}
+% Note however that either |\namespacephrase| itself or its expansion
+% must be robust.
+%
+%
+% \section{Acknowledgements}
+%
+% The \package{tclldoc} 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{tclldoc}.
+%
+%
+%
+% \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;
+% \textsc{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;
+% \textsc{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}, 2000;
+% \textsc{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, 2001;
+% \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
+% \texttt{latex}\slash \texttt{exptl}\slash \texttt{xdoc}\slash
+% \texttt{xdoc2.dtx}.
+% \bibitem{docindex}
+% Lars Hellstr\"om:
+% \textit{The \package{docindex} package}, 2001;
+% \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
+% \texttt{latex}\slash \texttt{exptl}\slash \texttt{xdoc}\slash
+% \texttt{docindex.dtx}.
+% \bibitem{TeXbook}
+% Donald E.\ Knuth, Duane Bibby (illustrations):
+% \textit{The \TeX book}, Ad\-di\-son--Wes\-ley, 1984;
+% ISBN~0-201-13448-9 and~0-201-13447-0.
+% \bibitem{docstrip}
+% Frank Mittelbach, Denys Duchier, Johannes Braams, Marcin
+% Woli\'nski, and Mark Wooding: \textit{The \textsf{DocStrip}
+% program}, The \LaTeX3 Project;
+% \textsc{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;
+% \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
+% \texttt{latex}\slash \texttt{base}\slash \texttt{doc.dtx}.
+% \bibitem{execMagic}
+% ``Tom'', Donal Fellows, Larry Virden, Richard Suchenwirth:
+% \textit{exec magic}, The \Tcl'ers Wiki page \textbf{812};
+% \textsc{http}:/\slash \texttt{mini.net}\slash \texttt{tcl}\slash
+% \texttt{812.html}.
+% \bibitem{ucs-package}
+% Dominique~P.~G.~Unruh:
+% \textit{\texttt{ucs.sty} - Unicode Support}, 2000;
+% \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
+% \texttt{latex}\slash \texttt{contrib}\slash
+% \texttt{supported}\slash \texttt{unicode}/.
+% \end{thebibliography}
+% \begin{flushleft}\footnotesize
+% The ``\textsc{ctan}:'' above is short for ``any of the servers
+% in the Comprehensive \TeX\ Archive Network (or mirror thereof)''.
+% 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{tclldoc} package}
+%
+% The |\NeedsTeXFormat| and |\ProvidesPackage| commands for the
+% \package{tclldoc} package appear at the top of \texttt{tclldoc.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) and the \package{docindex} (or rather the
+% \LaTeXe\ version \package{docidx2e}) package.
+% \SortIndex{docindex package}{\package{docindex} package}
+%
+% \changes{v\,2.23}{2001/07/21}{Added message about using
+% docindex.ist. (LH)}
+% \begin{macrocode}
+%<*pkg>
+\RequirePackageWithOptions{xdoc2}[2001/11/03]
+\RequirePackage{docidx2e}
+\AtEndDocument{%
+ \typeout{********************************}%
+ \typeout{* Use docindex.ist when\@spaces\@spaces*}%
+ \typeout{* sorting .idx and .glo files. *}%
+ \typeout{********************************}%
+}%
+% \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{tclldoc} 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 the |\TD@nesting@stack| stack. 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@
+ \def\TD@nesting@stack{\TD@nesting@level}%
+ \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. |\TD@command| must
+% appear before the |\futurelet| so that the following character
+% won't get tokenized with incorrect catcodes.
+% \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{tclldoc} 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|).
+% \changes{v\,2.20}{2001/03/12}{Moved \cs{TD@normal} previously in
+% \cs{TD@pm@module} to here. This means \package{docstrip} guard are
+% now read in normal mode rather than command mode. This change
+% was made because of grouping problems that occured on non-block
+% guard lines. Also added local redefinition of \PrintChar{13} to
+% prevent that guard lines are concatenated with the following
+% line. (LH)}
+% \DoNotIndex{\^}
+% \begin{macrocode}
+\begingroup
+ \catcode`<=\active
+ \catcode`\^^I=\catcode`\^^M \endlinechar=`\^^I \relax
+ \catcode`\^^M=\active
+ \gdef\TD@ch@angle{%
+ \ifx <\next
+ \TD@normal
+ \global\advance \c@codelineno \@ne
+ \TD@begin@tclpar
+ \def^^M{\TD@active@CR}%
+ \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}%
+ \ifnum \guard@level<\c@StandardModuleDepth \else
+ \AltMacroFont
+ \fi
+ \TD@count@indent
+ }
+\endgroup
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\TD@star@module}
+% \changes{v\,2.20}{2001/03/12}{Removed \cs{TD@end@tclpar}. (LH)}
+% \changes{v\,2.22}{2001/06/13}{Reinserted \cs{TD@end@tclpar} and
+% added \cs{TD@command}; this solves a problem with grouping that
+% prevented a font change from getting effect. (LH)}
+% \begin{macro}{\TD@slash@module}
+% \changes{v\,2.20}{2001/03/12}{Removed \cs{TD@end@tclpar}. (LH)}
+% \changes{v\,2.22}{2001/06/13}{Same change as in
+% \cs{TD@star@module}. (LH)}
+% 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.
+% \DoNotIndex{\>}
+% \begin{macrocode}
+\begingroup
+ \catcode`\>=\active
+ \gdef\TD@star@module#1>{%
+ \Module{#1}%
+ \TD@end@tclpar
+ \TD@command
+ \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
+ \TD@command
+ \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{tclldoc}{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{tclldoc}{\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}
+%
+% In order to have guard lines processed correctly, the first test
+% below really must be for |\TD@active@CR| rather than for an
+% active |^^M|.
+% \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@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.
+% \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}
+%
+% \begin{macro}{\TD@active@braceleft}
+% \begin{macro}{\TD@active@braceright}
+% \begin{macro}{\TD@nesting@stack}
+% \changes{v\,2.14}{2001/01/19}{Nesting stack added to cope with code
+% (brace-delimited strings) where brackets aren't properly balanced.
+% (LH)}
+% The |\TD@active@braceleft| and |\TD@active@braceright| work very
+% much like their \texttt{bracket} counterparts, but they also push
+% and pop the current nesting level on and off the |\TD@nesting@stack|
+% macro. The reason for doing this is that brackets aren't always
+% properly balanced in \Tcl\ code, which may result in a
+% |\TD@nesting@level| value which does not mirror how the code really
+% will be interpreted. Braces must however be properly balanced, and
+% therefore it is always right to restore the value of
+% |\TD@nesting@level| that was in force before a brace group began
+% when it is ended.
+%
+% The |\TD@nesting@stack| macro is a \meta{nesting stack}, which is
+% one of the following two things
+% \begin{quote}
+% |\TD@nesting@level|
+% \meta{number}|\def\TD@nesting@stack{|\meta{nesting stack}|}|
+% \end{quote}
+% This means a value is popped off the stack by doing
+% \begin{quote}
+% |\TD@nesting@level=\TD@nesting@stack|
+% \end{quote}
+% and |\TD@nesting@level| is unchanged if the stack is empty.
+% \DoNotIndex{\[,\]}
+% \DoNotIndexHarmless{\PrintChar{`\{}}
+% \DoNotIndexHarmless{\PrintChar{`\}}}
+% \begin{macrocode}
+\begingroup
+ \catcode`\{=12 \catcode`\}=12
+ \catcode`\[=1 \catcode`\]=2
+ \gdef\TD@active@braceleft[{%
+ \expandafter\def \expandafter\TD@nesting@stack \expandafter[%
+ \the\expandafter\TD@nesting@level
+ \expandafter\def \expandafter\TD@nesting@stack
+ \expandafter[\TD@nesting@stack]%
+ ]%
+ \advance\TD@nesting@level\@ne
+ ]
+ \gdef\TD@active@braceright[}%
+ \advance\TD@nesting@level\m@ne
+ \TD@nesting@level=\TD@nesting@stack
+ ]
+\endgroup
+\def\TD@nesting@stack{\TD@nesting@level}
+% \end{macrocode}
+% \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)}
+% \changes{v\,2.33}{2001/12/12}{Made list environments not indent
+% line numbers per default, but providing a way for the user to
+% change this. (LH)}
+% Line numbers are inserted using |\everypar|.
+% \begin{macrocode}
+ \ifcodeline@index
+ \everypar={\llap{%
+ \PrintCodelineNo\ \hskip\codelineindentfactor\@totalleftmargin
+ }}%
+ \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}{\codelineindentfactor}
+% The |\codelineindentfactor| macro specifies by which fraction of
+% |\@totalleftmargin| that the list environment indentation of
+% codeline numbers will be countered. |0| means that the numbers will
+% be indented, |1| or empty (the default) that they will not be
+% indented. |0.5| would mean that the effective indentation is half
+% that of other material.
+% \begin{macrocode}
+\let\codelineindentfactor\@empty
+% \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{tclldoc}{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{tclldoc}{%
+ 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{tclldoc}{%
+ \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@convert@colons}
+% 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. |\TD@convert@colons| replaces all
+% |::| substrings in the namespace by |\namespaceseparator|s.
+% \changes{v\,2.33}{2001/12/12}{Converting \texttt{::} in namespace
+% names. (LH)}
+% \begin{macrocode}
+\newcommand\setnamespace[1]{%
+ \MakeHarmless\TD@namespace{#1}%
+ \protected@edef\TD@namespace{%
+ \expandafter\TD@convert@colons \TD@namespace ::\relax
+ }
+}
+% \end{macrocode}
+% \begin{macrocode}
+\def\TD@convert@colons#1::#2{%
+ #1%
+ \ifx \relax#2\else
+ \noexpand\namespaceseparator
+ \TD@convert@colons #2%
+ \fi
+}
+% \end{macrocode}
+% \end{macro}\end{macro}
+%
+% \begin{macro}{\TD@namespace}
+% 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}
+%
+% \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}{\namespaceseparator}
+% \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}
+%
+% \begin{macro}{\namespacephrase}
+% The |\namespacephrase| macro stores the phrase that will be used
+% for `namespace' in indices and the like. It is meant to be
+% redefinable. The contents must be robust.
+% \changes{v\,2.25}{2001/08/14}{Macro added. (LH)}
+% \begin{macrocode}
+\providecommand*\namespacephrase{name\-space}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{instance}{docindex}{index}
+% \changes{v\,2.21}{2001/03/26}{Modified as per the v\,1.00 change to
+% \package{docindex}. (LH)}
+% The \texttt{index} instance of template type \texttt{docindex}
+% (defined by the \package{docindex} package) is redefined to allow
+% name and namespace levels to be joined.
+% \begin{macrocode}
+\@ifpackagewith{docidx2e}{usedocindexps}{%
+ \@namedef{TP@I{}{docindex}{index}}#1#2{%
+ \begingroup
+ \@letinstance\DI@indexitem@i{indexitem}{fixed-r1a}%
+ \@letinstance\DI@indexitem@ii{indexitem}{aloneaccept2}%
+ \@letinstance\DI@indexitem@iii{indexitem}{fixed3}%
+ \columnsep=10pt%
+ \parskip=0pt plus 1pt%
+ \def\DI@letter@skip{10pt plus 2pt minus 3pt}%
+ \def\DI@letter@format##1{%
+ \par
+ \hb@xt@\hsize{\hfil\textbf{##1}\hfil}%
+ \nopagebreak
+ }%
+ \def\+{-}%
+ \IfFileExists{\jobname.ind}{%
+ \ifnum \c@IndexColumns>\@ne
+ \begin{multicols}{\c@IndexColumns}[#1][\IndexMin]%
+ \else
+ \enough@room{\IndexMin}%
+ #1\par
+ \addvspace\multicolsep
+ \fi
+ \pagestyle{docindex}%
+ \small
+ \@nobreakfalse
+ \DI@ind@setup
+ \input{\jobname.ind}%
+ \DI@item@nojoin
+ \thispagestyle{docindex}
+ \ifnum \c@IndexColumns>\@ne
+ \end{multicols}%
+ \else
+ \enough@room\postmulticols
+ \addvspace\multicolsep
+ \fi
+ \normalsize #2\par
+ }{\typeout{No file \jobname.ind.}}%
+ \endgroup
+ }
+}{%
+ \@namedef{TP@I{}{docindex}{index}}#1#2{%
+ \begingroup
+ \@letinstance\DI@indexitem@i{indexitem}{fixed-r1a}%
+ \@letinstance\DI@indexitem@ii{indexitem}{aloneaccept2}%
+ \@letinstance\DI@indexitem@iii{indexitem}{fixed3}%
+ \columnsep=10pt%
+ \parskip=0pt plus 1pt%
+ \def\DI@letter@skip{10pt plus 2pt minus 3pt}%
+ \def\DI@letter@format##1{%
+ \par
+ \hb@xt@\hsize{\hfil\textbf{##1}\hfil}%
+ \nopagebreak
+ }%
+ \def\+{-}%
+ \IfFileExists{\jobname.ind}{%
+ \ifnum \c@IndexColumns>\@ne
+ \begin{multicols}{\c@IndexColumns}[#1][\IndexMin]%
+ \else
+ \enough@room{\IndexMin}%
+ #1\par
+ \addvspace\multicolsep
+ \fi
+ \small
+ \@nobreakfalse
+ \DI@ind@setup
+ \input{\jobname.ind}%
+ \DI@item@nojoin
+ \ifnum \c@IndexColumns>\@ne
+ \end{multicols}%
+ \else
+ \enough@room\postmulticols
+ \addvspace\multicolsep
+ \fi
+ \normalsize #2\par
+ }{\typeout{No file \jobname.ind.}}%
+ \endgroup
+ }
+}
+% \end{macrocode}
+% \end{instance}
+%
+%
+%
+% \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{macrocode}
+\MetaNormalfont
+% \end{macrocode}
+% \changes{v\,2.32}{2001/11/30}{Added \cs{MetaNormalfont} as a global
+% declaration and removed it from the commands that did this locally.
+% There were simply so many places where it should have been
+% otherwise that the resulting code would have looked rudiculous.
+% (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.
+% \changes{v\,2.14}{2001/01/12}{Corrected grabbing of the third
+% argument of the \texttt{arrayvar} environment: it should be an
+% oarg, not a harmless oarg. (LH)}
+% \begin{macrocode}
+\NewMacroEnvironment*{arrayvar}{%
+ \XD@grab@harmless@oarg\XD@grab@harmless\relax\XD@grab@oarg
+}{3}%
+ {\XDParToMargin{\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\@empty\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{%
+ \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)}
+% \changes{v\,2.20}{2001/03/03}{Putting namespace on the second
+% level. (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{%
+ \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}%
+ \endgroup
+ \IndexEntry{%
+ \ifx \NoValue#2\@empty
+ \LevelSorted{\@gtempa}{%
+ \texttt{#3}%
+ \ifx \NoValue#1\@empty \else\space(#1)\fi
+ }%
+ \else
+ \LevelSorted{\@gtempa}{%
+ \texttt{#3}\ifx \NoValue#1\@empty \else\space(#1)\fi
+ }%
+ \ifx $#2$%
+ \LevelSorted{ }{global \namespacephrase}%
+ \else
+ \LevelSorted{#2}{\texttt{#2} \namespacephrase}%
+ \fi
+ \fi
+ }{usage}{\thepage}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\describeopt}
+% \changes{v\,2.24}{2001/08/11}{Command added. (LH)}
+% \changes{v\,2.31}{2001/11/03}{Star-form added. (LH)}
+% The |\describeopt| macro is a |\describe|\dots\ command for options
+% of commands. The syntax is
+% \begin{quote}
+% |\describeopt|*\oarg{namespace}\marg{command}\oarg{type}^^A
+% \marg{option}
+% \end{quote}
+% where \meta{command} is the name of the command and \meta{option} is
+% the name of the option. \meta{namespace} is the namespace of the
+% \meta{command}, if that is not the global namespace. \meta{type} is
+% the type description for the command, if different from `proc'.
+% The |*| form of this command does not print a marginal note: it
+% only makes an index entry.
+% \begin{macrocode}
+\NewDescribeCommand{\describeopt}{%
+ \XD@grab@sarg{*}\XD@grab@harmless@oarg\XD@grab@harmless{}%
+ \XD@grab@oarg\XD@grab@harmless{}%
+}{5}{%
+ \ifx \BooleanFalse#1%
+ \GenericDescribePrint{%
+ \MacroFont #5\ \normalfont option%
+ }%
+ \fi
+ \begingroup
+ \def\meta##1{(##1)}%
+ \unrestored@protected@xdef\@gtempa{#3}%
+ \endgroup
+ \IndexEntry{%
+ \LevelSorted{\@gtempa}{%
+ \texttt{#3} (\ifx \NoValue#4\@empty proc\else #4\fi)%
+ }%
+ \ifx \NoValue#2\@empty
+ \LevelSorted{ }{global \namespacephrase}%
+ \else
+ \LevelSorted{#2}{\texttt{#2} \namespacephrase}%
+ \fi
+ \LevelSorted{#5}{\texttt{#5} option}%
+ }{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)}
+% \changes{v\,2.20}{2001/03/03}{Putting namespace on the second
+% level. (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 \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}{\texttt{#2} (#3)}%
+ \ifx \NoValue#1\@empty
+ \ifx \@empty\TD@namespace
+ \LevelSorted{ }{global \namespacephrase}%
+ \else
+ \LevelSorted{\TD@namespace}%
+ {\texttt{\TD@namespace} \namespacephrase}%
+ \fi
+ \else
+ \ifx $#1$%
+ \LevelSorted{ }{global \namespacephrase}%
+ \else
+ \LevelSorted{#1}{\texttt{#1} \namespacephrase}%
+ \fi
+ \fi
+ #4%
+ }%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{environment}{Cfunction}
+% \changes{v\,2.40}{2003/04/05}{Environment added. (LH)}
+% \begin{environment}{Cvariable}
+% \changes{v\,2.40}{2003/04/05}{Environment added. (LH)}
+% \begin{environment}{Ctype}
+% \changes{v\,2.40}{2003/04/05}{Environment added. (LH)}
+% The \texttt{Cfunction}, \texttt{Cvariable}, and \texttt{Ctype}
+% environments are for making a marginal heading, index entry, etc.\@
+% for a C function, variable, or type respectively. They all take as
+% their single argument the name of the thing that will be defined.
+% \begin{macrocode}
+\NewMacroEnvironment*{Cfunction}{\XD@grab@harmless\relax}{1}%
+ {\XDParToMargin{\small\Cfunctionidentifier{#1} (C~function)}}%
+ {\XDMainIndex{%
+ \LevelSorted{#1}{\Cfunctionidentifier{#1} (C~function)}%
+ }}%
+ {{#1}{\Cfunctionidentifier{#1} C~function}}
+ {}%
+\NewMacroEnvironment*{Cvariable}{\XD@grab@harmless\relax}{1}%
+ {\XDParToMargin{\small\Cvariableidentifier{#1} (C~variable)}}%
+ {\XDMainIndex{%
+ \LevelSorted{#1}{\Cvariableidentifier{#1} (C~variable)}%
+ }}%
+ {{#1}{\Cvariableidentifier{#1} C~variable}}
+ {}%
+\NewMacroEnvironment*{Ctype}{\XD@grab@harmless\relax}{1}%
+ {\XDParToMargin{\small\Ctypeidentifier{#1} (C~type)}}%
+ {\XDMainIndex{%
+ \LevelSorted{#1}{\Ctypeidentifier{#1} (C~type)}%
+ }}%
+ {{#1}{\Ctypeidentifier{#1} C~type}}
+ {}%
+% \end{macrocode}
+% \end{environment}\end{environment}\end{environment}
+%
+% \begin{macro}{\Cfunctionidentifier}
+% \changes{v\,2.40}{2003/04/05}{Macro added. (LH)}
+% \begin{macro}{\Cvariableidentifier}
+% \changes{v\,2.40}{2003/04/05}{Macro added. (LH)}
+% \begin{macro}{\Ctypeidentifier}
+% \changes{v\,2.40}{2003/04/05}{Macro added. (LH)}
+% These macros are used by \texttt{Cfunction}, \texttt{Cvariable}, and
+% \texttt{Ctype} to format the identifiers of C functions, variables,
+% and types respectively; the syntax is e.g.
+% \begin{quote}
+% |\Cfunctionidentifier|\marg{function name}
+% \end{quote}
+% They default to typeset them in an italic font---this is what CWEB
+% uses---but it is meant to be configurable.
+% \begin{macrocode}
+\newcommand*{\Cfunctionidentifier}[1]{\textit{#1}}
+\newcommand*{\Cvariableidentifier}[1]{\textit{#1}}
+\newcommand*{\Ctypeidentifier}[1]{\textit{#1}}
+% \end{macrocode}
+% \end{macro}\end{macro}\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{regblock} environment, then these things should be put as
+% the \meta{modifier} in
+% \begin{quote}
+% |\begin{regblock}|\oarg{modifier}\\
+% | |\textellipsis\\
+% |\end{regblock}|
+% \end{quote}
+% In particular, they should \emph{not} be put after the
+% |\end{regblock}|, 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}{regblock}
+% The \texttt{regblock} 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{regblock} 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{regblock} environment. This makes it possible to nest
+% \texttt{regblock} 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{regblock}
+% 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.
+%
+% \changes{v\,2.40}{2003/04/05}{Renamed the \texttt{regexp}
+% environment to \texttt{regblock}. A \texttt{regexp} environment
+% is provided for compatibility. (LH)}
+% \begin{macrocode}
+\newenvironment{regblock}[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{environment}{regexp}
+% This is an alias to the \texttt{regblock} environment, provided for
+% compatibility.
+% \begin{macrocode}
+\newenvironment{regexp}{\regblock}{\endregblock}
+% \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{regblock} 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{regblock} environment however, the |\regalt| command does by
+% default only produce an error message. The ``real'' definition is
+% kept in |\TD@regalt| and the \texttt{regblock} environment locally
+% redefines |\regalt|.
+% \begin{macrocode}
+\newcommand\regalt{%
+ \PackageError{tclldoc}{%
+ Lonely \protect\regalt--perhaps a missing regblock 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{regblock} 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{tclldoc} class}
+%
+% \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{tclldoc} class.
+% \begin{macrocode}
+%<*class>
+\DeclareOption{a5paper}{%
+ \ClassError{tclldoc}{The a5paper option is not supported}\@eha
+}
+\DeclareOption{olddocinclude}{%
+ \ClassError{tclldoc}{The olddocinclude option is not supported}\@eha
+}
+% \end{macrocode}
+% \end{option}\end{option}
+%
+% \begin{option}{notrawchar}
+% The \texttt{notrawchar} option is passed on to the
+% \package{tclldoc} package (which will pass it on to the
+% \package{xdoc} package).
+% \changes{v\,2.40}{2003/04/05}{Added processing of this option; it
+% wouldn't take if it was simply given as a global option. (LH)}
+% \begin{macrocode}
+\DeclareOption{notrawchar}{%
+ \PassOptionsToPackage{notrawchar}{tclldoc}%
+}
+% \end{macrocode}
+% \end{option}
+%
+%
+% \begin{macrocode}
+\DeclareOption*{%
+ \PassOptionsToClass{\CurrentOption}{article}}
+% \end{macrocode}
+%
+%
+%
+% Input a local configuration file, if it exists.
+% \begin{macrocode}
+\InputIfFileExists{tclldoc.cfg}
+ {\typeout{*************************************^^J%
+ * Local config file tclldoc.cfg used^^J%
+ *************************************}}
+ {}
+% \end{macrocode}
+%
+%
+%
+% \begin{macrocode}
+\ProcessOptions\relax
+% \end{macrocode}
+%
+% \subsection{Loading the base class}
+%
+% \begin{macrocode}
+\LoadClass{article}
+% \end{macrocode}
+%
+%
+% \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{tclldoc} package}
+%
+% \begin{macrocode}
+\RequirePackage[dolayout]{tclldoc}
+% \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{tclldoc} 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}
+%</class>
+% \end{macrocode}
+%
+%
+% \section{The \package{tcldoc} compatibility package and class}
+%
+% \changes{v\,2.30}{2001/09/02}{Renamed the package and class to
+% \package{tclldoc} to prevent confusion with the \Tcl Doc Perl
+% script. Added files \texttt{tcldoc.sty} and \texttt{tcldoc.cls}
+% for compatibility. Moved code related to the \texttt{macinputenc}
+% option to \texttt{tcldoc.cls}; this option is now unsupported.
+% (LH)}
+%
+% \subsection{Pre-options definitions}
+%
+% \begin{macro}{\if@rtkinenc@}
+% Switch. True iff the \package{rtkinenc} package should be loaded.
+% It starts out false.
+% \begin{macrocode}
+%<*compclass>
+\newif\if@rtkinenc@
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{Option declarations and processing}
+%
+% \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}{tclldoc}}
+% \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 package or class}
+%
+% \begin{macrocode}
+\LoadClass{tclldoc}
+%</compclass>
+%<comppkg>\LoadPackageWithOptions{tclldoc}
+% \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{macro}{\InputModeCode}
+% \begin{macro}{\SetUnavailableAction}
+% \begin{macro}{\DeclareInputMath}
+% \begin{macro}{\RIE@undefined}
+% The \package{tclldoc} package calls some commands defined by the
+% \package{rtkinenc} package, but since \package{rtkinenc} is not
+% required by the \package{tclldoc} package, the \package{tclldoc}
+% 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{tclldoc}
+% 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{macrocode}
+%<*compclass>
+\if@rtkinenc@
+ \RequirePackage{rtkinenc}
+% \end{macrocode}
+%
+% \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}
+ \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{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)}}
+%</compclass>
+% \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
+