Debian Codegraph @

texmf-dist/source/latex/tcldoc/tclldoc.dtx

raw
1 % \CheckSum{1849}
2 %
3 % \title{The \package{tclldoc} package and class}
4 % \author{Lars Hellstr\"om^^A
5 % \thanks{E-mail: \texttt{[email protected]}}
6 % \emph{et al.}}
7 % \date{2003/07/19}
8 % \maketitle
9 %
10 % \iffalse
11 %
12 %<class|pkg>\NeedsTeXFormat{LaTeX2e}
13 %<class>\ProvidesClass{tclldoc}
14 %<compclass>\ProvidesClass{tcldoc}
15 %<pkg>\ProvidesPackage{tclldoc}
16 %<comppkg>\ProvidesPackage{tcldoc}
17 %<class|pkg|compclass|comppkg> [2003/04/05 v2.40
18 %<class|pkg> Tcl documentation
19 %<compclass|comppkg> tclldoc compatibility
20 %<class|compclass> class]
21 %<pkg|comppkg> package]
22 %
23 %<*driver>
24 \documentclass{ltxdoc}
25 \usepackage{amsmath}
26 \IfFileExists{xdoc2.sty}{\usepackage[dolayout]{xdoc2}[2000/11/18]}{}
27
28 \makeatletter
29 \@ifpackageloaded{xdoc2}{}{%
30 \@ifpackagelater{doc}{2000/05/20}{}{%
31 \let\XD@fragile@meta=\meta
32 \def\meta{%
33 \ifx \protect\@typeset@protect
34 \expandafter\futurelet \expandafter\@let@token
35 \expandafter\XD@fragile@meta
36 \else
37 \noexpand\meta
38 \fi
39 }%
40 }%
41 }
42 \@ifundefined{option}{%
43 \newenvironment{option}[1]{%
44 \trivlist
45 \if@inlabel\else \macro@cnt=\z@ \fi
46 \item[]\ignorespaces
47 }{\endtrivlist}%
48 }{}
49 \@ifundefined{instance}{%
50 \newenvironment{instance}[2]{%
51 \trivlist
52 \if@inlabel\else \macro@cnt=\z@ \fi
53 \item[]\ignorespaces
54 }{\endtrivlist}%
55 }{}
56 \makeatother
57
58 \DeclareRobustCommand\package[1]{\textsf{#1}}
59 \DeclareRobustCommand\Tcl{T\kern-0.1em cl}
60 \DeclareRobustCommand\word[1]{\mbox{$\{$\itshape#1\/$\}$}}
61
62 \makeatletter
63 \newcommand{\swtpc}{%
64 \sbox\z@{ }%
65 \expandafter\makebox \expandafter[\the\wd\z@]%
66 {\textperiodcentered}%
67 }
68 \makeatother
69
70 \providecommand*\describeoption[1]{\marginpar{\texttt{#1} option}}
71 \providecommand*\PrintChar[1]{\char#1\relax}
72 \providecommand*{\DoNotIndexHarmless}[1]{}
73 \providecommand*{\DoNotIndexBy}[1]{}
74 \DoNotIndexBy{@}
75 \DoNotIndexBy{@@}
76 \DoNotIndexBy{TD@}
77 \newenvironment{isyntax}{%
78 \list{}{%
79 \setlength\parsep{0pt plus 1pt}%
80 \setlength\listparindent{-1em}%
81 \setlength\itemindent{\listparindent}%
82 \addtolength\leftmargin{1em}%
83 }%
84 \item\relax \rightskip=1.0\rightskip plus 5cm
85 }{\endlist}
86
87 \setcounter{IndexColumns}{2}
88 \hfuzz=10pt
89 \expandafter\def \expandafter\GlossaryParms \expandafter{%
90 \GlossaryParms \hbadness=10000
91 }
92
93 \CodelineIndex
94 \EnableCrossrefs
95 \RecordChanges
96
97 \begin{document}
98 \DocInput{tclldoc.dtx}
99 \PrintChanges
100 \PrintIndex
101 \end{document}
102 %</driver>
103 %
104 % \fi
105 %
106 % \begin{abstract}
107 % The \package{tclldoc} package defines a couple of environments and
108 % macros for documenting \Tcl\ source code in \texttt{.dtx}-style
109 % documented source files, much like what the \package{doc}
110 % package~\cite{doc} does for \TeX\ source code. The \package{tclldoc}
111 % class is analogous to the \package{ltxdoc} document
112 % class~\cite{ltxdoc}---it loads the package to gain the basic
113 % functionality and changes some layout parameters to values that
114 % are better suited for documented source than those set by the
115 % standard \package{article} document class.
116 %
117 % The \package{tclldoc} package builds on the \package{doc},
118 % \package{xdoc}~\cite{xdoc}, and \package{docindex}~\cite{docindex}
119 % packages.
120 %
121 % Note: The \package{tclldoc} package and class used to be called
122 % \package{tcldoc}, but it turned out that there already existed a
123 % Perl~(!!)\ script \Tcl Doc that has a similar function. Therefore I
124 % added an extra `\textsf{l}'---which stands for both \LaTeX\ and
125 % Literate---to avoid confusing the community of \Tcl\ programmers.
126 % For compatibility, a package and a class named \package{tcldoc} are
127 % installed with \package{tclldoc}, but they shouldn't be used for
128 % new documents.
129 % \end{abstract}
130 %
131 % \tableofcontents
132 %
133 % \DoNotIndex{\advance,\begingroup,\bgroup,\big,\Big,\bigg,\Bigg,\box}
134 % \DoNotIndex{\catcode,\char,\chardef,\cleaders,\color@begingroup}
135 % \DoNotIndex{\color@endgroup,\copy,\csname,\DeclareOption}
136 % \DoNotIndex{\DeclareRobustCommand,\DeclareTextCommand}
137 % \DoNotIndex{\DeclareTextSymbol,\def,\discretionary,\divide,\do}
138 % \DoNotIndex{\edef,\egroup,\else,\@empty,\endcsname,\endgroup}
139 % \DoNotIndex{\expandafter,\fi,\@firstoftwo,\font,\fontdimen}
140 % \DoNotIndex{\futurelet,\gdef,\global,\@gobble,\hb@xt@,\hbox}
141 % \DoNotIndex{\hfill,\if,\ifcase,\ifcat,\ifmmode,\ifnum,\ifvbox}
142 % \DoNotIndex{\ifvmode,\ifvoid,\ifx,\ignorespaces,\immediate,\indent}
143 % \DoNotIndex{\input,\@@input,\InputIfFileExists,\IfFileExists}
144 % \DoNotIndex{\item,\kern,\language,\lastbox,\lastpenalty,\lastskip}
145 % \DoNotIndex{\lccode,\leavevmode,\let,\llap,\LoadClass,\lowercase}
146 % \DoNotIndex{\m@ne,\m@th,\@makeother,\mathord,\mkern,\multiply}
147 % \DoNotIndex{\@ne,\newbox,\newcommand,\newcount,\NewDescribeCommand}
148 % \DoNotIndex{\newenvironment,\newif,\NewMacroEnvironment,\nfss@text}
149 % \DoNotIndex{\noexpand,\normalfont,\null,\number,\or,\p@,\@@par}
150 % \DoNotIndex{\parshape,\PassOptionsToClass,\PassOptionsToPackage}
151 % \DoNotIndex{\penalty,\@plus,\predisplaypenalty,\prevdepth,\prevgraf}
152 % \DoNotIndex{\ProcessOptions,\protect,\protected@edef}
153 % \DoNotIndex{\providecommand,\ProvideTextCommandDefault,\relax}
154 % \DoNotIndex{\RequirePackage,\RequirePackageWithOptions,\rightarrow}
155 % \DoNotIndex{\sbox,\selectfont,\setbox,\skewchar,\space,\string}
156 % \DoNotIndex{\TextSymbolUnavailable,\texttt,\the,\tracingparagraphs}
157 % \DoNotIndex{\ttfamily,\tw@,\typeout,\unhbox,\unpenalty,\unskip}
158 % \DoNotIndex{\unrestored@protected@xdef,\unskip,\unvbox,\vadjust}
159 % \DoNotIndex{\vbox,\vert,\vrule,\vskip,\wd,\write,\xdef,\z@,\z@skip}
160 %
161 % \section{Introduction}
162 % \label{Sec:Introduction}
163 %
164 % This introduction is meant to be comprehensible even for readers
165 % unfamiliar with writing \texttt{.dtx} files and using the \package{doc}
166 % package. Readers who are experienced with this will probably want to
167 % skip right to the next section.
168 %
169 % A \texttt{.dtx} file has a dual nature. On one hand it is a container
170 % for some lines of code---it could be a program, a macro package, a
171 % configuration file for some program, merely a part of any of the
172 % aforementioned, or even arbitrary combinations of the above---and on
173 % the other hand it is a \LaTeX\ document which documents this code. One
174 % important advantage with this arrangement is that one can keep all the
175 % pieces of a project that has to do with a specific task at one place;
176 % experience has shown that this greatly furthers really keeping all
177 % parts of a project up to date with each other.
178 %
179 % Slightly simplified, one can say that a \texttt{.dtx} file contains
180 % three kinds of lines. A \emph{code line} is a line that doesn't begin
181 % with a `|%|' character; such lines can be extracted (copied) using the
182 % \package{docstrip} program~\cite{docstrip}. A \emph{guard line} is a
183 % line that begins with the two characters `|%<|'; guards are used to
184 % structure the set of code lines so that \package{docstrip} can extract
185 % different code lines to different generated files. A \emph{comment
186 % line}, finally, is a line that begins with a `|%|' character that is
187 % not immediately followed by a `|<|' character. The comment lines are
188 % ignored by \package{docstrip}, but are part of (and usually make up
189 % most of) the \LaTeX\ document in the \texttt{.dtx} file.
190 %
191 %
192 % \subsection{Special conventions and basic features in a \texttt{.dtx}
193 % \LaTeX\ document}
194 %
195 % An important difference between normal \LaTeX\ documents and
196 % \texttt{.dtx} \LaTeX\ documents is that the percent character `|%|'
197 % doesn't start a comment in the latter; in fact it is usually ignored.
198 % This allows \LaTeX\ to see and typeset the text in the comment lines
199 % of a \texttt{.dtx} file. Hence if one wants to include the sentence
200 % ``Your hovercraft is full of eels!'', which in a normal \LaTeX\
201 % document could have been written as the line\iffalse
202 %<*example>
203 % \fi
204 %\begin{verbatim}
205 %Your hovercraft is full of eels!
206 %\end{verbatim}
207 % one would instead write the line as
208 %\begin{verbatim}
209 %% Your hovercraft is full of eels!
210 %\end{verbatim}
211 % in a \texttt{.dtx} document. The space after the |%| is not
212 % necessary, but most \texttt{.dtx} documents you see include
213 % it---probably because the ``comment out \TeX\ code'' action of most
214 % text editors consists of inserting a percent \emph{and} a space at
215 % the beginning of each line.
216 %
217 % The code lines present the opposite problem, as they usually
218 % shouldn't be treated as normal \LaTeX\ code although the normal \LaTeX\
219 % reading conventions would make them the entire document. The usual way
220 % around this is to surround each group of code lines with two comment
221 % lines that begin and end an environment in which the code lines get
222 % typeset verbatim. The \package{tclldoc} package provides the \texttt{tcl}
223 % environment for this purpose, so the code lines
224 %\begin{verbatim}
225 %proc factorial {n} {
226 % set result 1
227 % for {set i 1} {$i<=$n} {incr i} {
228 % set result [expr {$result * $i}]
229 % }
230 % return $result
231 %}
232 %\end{verbatim}
233 % could be included in a \texttt{.dtx} document as the lines
234 %\begin{verbatim}
235 %% \begin{tcl}
236 %proc factorial {n} {
237 % set result 1
238 % for {set i 1} {$i<=$n} {incr i} {
239 % set result [expr {$result * $i}]
240 % }
241 % return $result
242 %}
243 %% \end{tcl}
244 %\end{verbatim}
245 % When typeset, this will look as
246 % \begin{macrocode}
247 proc factorial {n} {
248 set result 1
249 for {set i 1} {$i<=$n} {incr i} {
250 set result [expr {$result * $i}]
251 }
252 return $result
253 }
254 % \end{macrocode}
255 % The tiny numbers at the beginning of each line enumerate the code lines.
256 % Index references to code usually specify such code line numbers, but
257 % the enumeration can be switched off.
258 %
259 % In mathematical papers, the statements of e.g.\ theorems are usually
260 % made inside a \texttt{theorem} (or whatever) environment which
261 % provides certain text formatting, a heading, and a position in the
262 % document that can be referenced from other parts of it. In \texttt{.dtx}
263 % documents one usually does something similar for each named piece of
264 % code: macros, environments, templates, etc. In particular, the
265 % \package{tclldoc} package provides two environments \texttt{proc} (for
266 % procedures) and \texttt{variable} (for variables).
267 % Figure~\ref{Fig:procex} contains an example of how \texttt{proc}
268 % might be used in describing a procedure for computing the greatest
269 % common divisor of two integers.
270 %
271 % \begin{figure}
272 %
273 % \begin{trivlist}
274 % \item[]\leavevmode\llap{\texttt{gcd} (proc)\kern\marginparsep}^^A
275 % The |gcd| procedure takes two arguments $a$ and $b$ which must be
276 % integers and returns their greatest common divisor $\gcd(a,b)$,
277 % which is computed using Euclid's algorithm. As a special case,
278 % $\gcd(0,0)$ is considered to be $0$, so formally |gcd $a $b|
279 % computes $\lvert a \rvert \wedge \lvert b \rvert$, where $\wedge$
280 % denotes the meet operation in the divisor lattice of non-negative
281 % integers.
282 % \begin{macrocode}
283 proc gcd {a b} {
284 set a [expr {abs($a)}]
285 set b [expr {abs($b)}]
286 while {$b>0} {
287 set r [expr {$a%$b}]
288 set a $b
289 set b $r
290 }
291 return $a
292 }
293 % \end{macrocode}
294 % \end{trivlist}
295 %
296 % \begin{center}
297 % (a) A typeset procedure with description
298 % \end{center}
299 %
300 %\begin{verbatim}
301 %% \begin{proc}{gcd}
302 %% The |gcd| procedure takes two arguments $a$ and $b$ which must be
303 %% integers and returns their greatest common divisor $\gcd(a,b)$,
304 %% which is computed using Euclid's algorithm. As a special case,
305 %% $\gcd(0,0)$ is considered to be $0$, so formally |gcd $a $b|
306 %% computes $\lvert a \rvert \wedge \lvert b \rvert$, where $\wedge$
307 %% denotes the meet operation in the divisor lattice of non-negative
308 %% integers.
309 %% \begin{tcl}
310 %proc gcd {a b} {
311 % set a [expr {abs($a)}]
312 % set b [expr {abs($b)}]
313 % while {$b>0} {
314 % set r [expr {$a%$b}]
315 % set a $b
316 % set b $r
317 % }
318 % return $a
319 %}
320 %% \end{tcl}
321 %% \end{proc}
322 %\end{verbatim}
323 %
324 % \begin{center}
325 % (b) The code for the example in (a)
326 % \end{center}
327 %
328 % \caption{An example of the \texttt{proc} environment}
329 % \label{Fig:procex}
330 % \end{figure}
331 %
332 % What does the \texttt{proc} environment do more precisely? First
333 % there's the marginal heading which can be seen in Figure~^^A
334 % \ref{Fig:procex}. Such headings make it easier to find the procedure in
335 % the typeset form of the document. Then the \texttt{proc} environment
336 % makes an index entry which tells you where the procedure is defined,
337 % and finally it stores the procedure name in a variable so that
338 % subsequent |\changes|\footnote{The \cs{changes} command is defined by
339 % the \package{doc} package~\cite{doc}. It is used for adding entries
340 % to a global list of changes for code in the \texttt{.dtx} document.}
341 % commands know to what the change that they are recording was made.
342 %
343 % The \texttt{variable} environment does the same things except that it
344 % writes ``(var.)'' rather than ``(proc)''. This environment wasn't used
345 % for describing the three local variables |a|, |b|, and |r| in the
346 % example; this is since there is no point in referring to these
347 % variables from elsewhere in the program. Instead the \texttt{variable}
348 % environment is primarily meant for global variables (although it could
349 % also be useful for local variables that are meant to be accessed using
350 % |upvar| or |uplevel|), and as such it can often be of great help, since
351 % the description of a global variable can otherwise be hard to find,
352 % especially with languages like \Tcl\ where variables don't have to be
353 % declared and thus have no natural ``home'' in the code.
354 %
355 % Another noteworthy feature in the example is the use of vertical
356 % bar `\verb+|+' characters to delimit short pieces of verbatim \Tcl\
357 % code in the comment lines. It is often necessary for the explanation
358 % to include short examples of code in the documentation, and the
359 % standard \LaTeX\ |\verb| command is exactly what one would need for
360 % this. As such code sections are rather frequent however, it has become
361 % the custom to use a single character for both starting and ending such
362 % a piece of code. The \package{tclldoc} document class defines \verb+|+
363 % as a shorthand for \verb+\tclverb|+, where |\tclverb| is a variant of
364 % |\verb| which has been designed specifically for \Tcl\ code.
365 %
366 % The above description was meant to give a basic understanding of how
367 % \Tcl\ code and documentation thereof can be mixed in a \texttt{.dtx}
368 % file, it neither explains all the environments and commands that
369 % the \package{tclldoc} package provides, nor mentions all the
370 % features of the environments that were described. That information can
371 % instead be found in Section~\ref{Sec:Manual} of this paper. It should
372 % also be mentioned that the \package{doc} package~\cite{doc} defines
373 % several commands and environments that may be of use for describing
374 % code, and it is well worth getting acquainted with the features of
375 % that package as well (although parts of its documentation has become
376 % rather archaic).
377 %
378 %
379 % \subsection{Guards and \package{docstrip} installation scripts}
380 %
381 % The central command in a \package{docstrip} installation script is
382 % |\generate|, since this is the command which actually causes code to
383 % be extracted. |\generate|'s syntax is
384 % \begin{quote}
385 % |\generate|\marg{files}
386 % \end{quote}
387 % where \meta{files} consists of one or several |\file| commands, each
388 % of which has the syntax
389 % \begin{quote}
390 % |\file|\marg{output}\marg{sources}
391 % \end{quote}
392 % where \meta{output} is a filename and \meta{sources} consists of one
393 % or several |\from| commands, each of which has the syntax
394 % \begin{quote}
395 % |\from|\marg{input}\marg{options}
396 % \end{quote}
397 % where, finally, \meta{input} is a filename and \meta{options} is a
398 % comma-separated list of alphanumerical strings. Thus a |\generate|
399 % command might look like
400 %\begin{verbatim}
401 % \generate{\file{p1.sty}{\from{s1.dtx}{foo,bar}}
402 % \file{p2.sty}{\from{s2.dtx}{baz}
403 % \from{s3.dtx}{baz}}
404 % \file{p3.sty}{\from{s1.dtx}{zip}
405 % \from{s2.dtx}{zap}}
406 % }
407 %\end{verbatim}
408 % The meaning of this command is
409 % \begin{quote}
410 % Generate the three files \texttt{p1.sty}, \texttt{p2.sty}, and
411 % \texttt{p3.sty}. Extract the code for \texttt{p1.sty} from
412 % \texttt{s1.dtx} with options \texttt{foo} and \texttt{bar}, extract
413 % the code for \texttt{p2.sty} from \texttt{s2.dtx} with option
414 % \texttt{baz} and \texttt{s3.dtx} (the code from \texttt{s2.dtx}
415 % will be put before the code from \texttt{s3.dtx}) with option
416 % \texttt{baz}, and finally extract the code for \texttt{p3.sty} from
417 % \texttt{s1.dtx} with option \texttt{zip} and \texttt{s2.dtx} with
418 % option \texttt{zap}.
419 % \end{quote}
420 % The \emph{options} are used to control which parts of the source files
421 % should be extracted to which generated file. A source file can
422 % contain a number of \emph{modules}, and at the beginning of each
423 % module \package{docstrip} decides, for each output file separately,
424 % whether the code lines in that module should be extracted to the
425 % output file. The beginning of a module is marked by a guard line which
426 % has the syntax
427 % \begin{quote}
428 % |%<*|\meta{expression}|>|
429 % \end{quote}
430 % and the end by a corresponding
431 % \begin{quote}
432 % |%</|\meta{expression}|>|
433 % \end{quote}
434 % guard line. In their simplest form, the \meta{expression}s are names
435 % of options, and in that case the code lines in the module are only
436 % extracted if that option appears in the \meta{options} for that
437 % combination of input file and output file. The \meta{expression}s can
438 % however be arbitrarily complicated boolean expressions;
439 % see~\cite{docstrip} for more information.
440 % Modules may nest inside each other, and in that case the code lines in
441 % an inner module can only be included if all surrounding modules are
442 % being included. It is checked that matching |*| and |/| guard lines
443 % contain the same (as strings) \meta{expression}, and case is
444 % significant in the names of options.
445 %
446 % One application of modules which has already been mentioned is to
447 % bundle code for several different generated files in the same
448 % \texttt{.dtx} file---one example of this is the file
449 % \texttt{doc.dtx} (part of the \LaTeX\ base distribution) which
450 % contains both the \package{doc} package (\texttt{doc.sty}), the
451 % \package{shortvrb} package (\texttt{shortvrb.sty}), and two
452 % \package{makeindex} style files (\texttt{gglo.ist} and
453 % \texttt{gind.ist}). Another application is to keep variant sections
454 % of code---such as special code for debugging or gathering
455 % statistics---in the \texttt{.dtx} source file for a program without
456 % thereby making it a part of the normal form of that program. It is
457 % quite possible to use \package{docstrip} as a simple pre-processor
458 % for languages whose compiler\slash interpreter has not got one built
459 % in.
460 %
461 % There are many other commands available in a \package{docstrip}
462 % installation script beside those listed above, but those are well
463 % described in the \package{docstrip} manual~\cite{docstrip} and need
464 % little attention here. Instead I'm going to finish this subsection
465 % with a quick guide to the particular difficulties one faces when using
466 % \package{docstrip} to extract \Tcl\ code, and how to overcome them.
467 %
468 % The main problem is that \package{docstrip} insert a few comment lines
469 % at the beginning and end of each file it generates. This is a good
470 % thing, because a file consisting entirely of extracted code lines
471 % would normally be completely void of commentary and quite
472 % unintelligible for the casual user. These few comment lines explain
473 % that the file was generated by \package{docstrip} from other files
474 % (which contain the documentation of the code), lists those files,
475 % and normally also contains a copyright (or more commonly some kind of
476 % copyleft) notice. The problem lies in that comments look different in
477 % different languages, and as the default is to write \TeX\ style
478 % comments, one must tell \package{docstrip} to write \Tcl\ style
479 % comments. This can be done through the command
480 %\begin{verbatim}
481 %\edef\MetaPrefix{\string#}
482 %\end{verbatim}
483 % which tells \package{docstrip} to begin each inserted comment line
484 % with the character `|#|'.
485 %
486 % The comment lines inserted at the beginning of a generated file are
487 % called the \emph{preamble} and those at the end the \emph{postamble}.
488 % To set the preamble, one writes
489 % \begin{trivlist}
490 % \item |\preamble|\\
491 % \meta{preamble lines}\\
492 % |\endpreamble|
493 % \end{trivlist}
494 % and correspondingly to set the postamble
495 % \begin{trivlist}
496 % \item |\postamble|\\
497 % \meta{postamble lines}\\
498 % |\endpostamble|
499 % \end{trivlist}
500 % The \meta{preamble lines} and \meta{postamble lines} can be any number
501 % of lines (including zero). Unlike the text in source files, the text in
502 % these preamble and postamble lines is not read verbatim, so things in
503 % these lines which have special meaning to \TeX\ (such as control
504 % sequences) will be treated as such; the only exception is that spaces
505 % and newlines are preserved (instead of concatenated to single spaces
506 % as they normally would). It is important that the preamble and
507 % postamble \emph{are} set after |\MetaPrefix| is changed, because each
508 % line specified between |\preamble| and |\endpreamble| or |\postamble|
509 % and |\endpostamble| respectively will be prefixed by the current value
510 % of |\MetaPrefix|.
511 %
512 % Finally, some programs (such as the UNIX core) assign special meaning
513 % to the first line of a file, so one might want to control what gets
514 % put there. Merely using |\preamble| doesn't achieve this, because the
515 % \meta{preamble lines} specified that way are put after the lines
516 % saying ``this is a generated file \textellipsis''. You can however
517 % add things to the preamble by explicitly setting the macro
518 % |\defaultpreamble|, which is where \package{docstrip} stores the
519 % preamble. To make the first line a comment which simply contains the
520 % text `|-*-Tcl-*-|', you could give the command
521 %\begin{verbatim}
522 %\edef\defaultpreamble{\MetaPrefix\space -*-Tcl-*-^^J\defaultpreamble}
523 %\end{verbatim}
524 % Similarly to begin the file by the three standard lines
525 %\begin{verbatim}
526 %#! /bin/sh
527 %#\
528 %exec tclsh "$0" ${1+"$@"}
529 %\end{verbatim}
530 % (for an explanation see~\cite{execMagic})---which on UNIX allow the file
531 % to function both as a \Tcl\ script and a shell script which terminates
532 % the shell and runs \texttt{tclsh} on the script instead---you can use
533 % the command
534 %\begin{verbatim}
535 %\edef\defaultpreamble{%
536 % \MetaPrefix! /bin/sh^^J%
537 % \MetaPrefix\string\^^J%
538 % exec tclsh "$0" ${1+"$@"}^^J%
539 % \defaultpreamble
540 %}
541 %\end{verbatim}
542 % The full explanation of these commands is however far beyond this
543 % introduction.\footnote{Those who want to fully understand them should
544 % read \emph{The \TeX book}~\cite{TeXbook}, in particular Chapter~8.}
545 %
546 % In summary, a \package{docstrip} installation script for extracting a
547 % file \texttt{foo.tcl} from \texttt{foo.dtx}, using \Tcl\ style
548 % comments, inserting a BSD-style license notice in the preamble, and
549 % beginning with the line |# -*-Tcl-*-| could look as follows:
550 %\begin{verbatim}
551 %\input docstrip.tex
552 %
553 %\edef\MetaPrefix{\string#}
554 %
555 %\preamble
556 %
557 %Copyright (c) <YEAR>, <OWNER>
558 %All rights reserved.
559 %
560 %Redistribution and use in source and binary forms, with or without
561 %modification, are permitted provided that the following conditions
562 %are met:
563 %* Redistributions of source code must retain the above copyright
564 %notice, this list of conditions and the following disclaimer.
565 %* Redistributions in binary form must reproduce the above
566 %copyright notice, this list of conditions and the following
567 %disclaimer in the documentation and/or other materials provided
568 %with the distribution.
569 %
570 %THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
571 %"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
572 %LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
573 %FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
574 %COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
575 %INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
576 %BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
577 %LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
578 %CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
579 %LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
580 %ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
581 %POSSIBILITY OF SUCH DAMAGE.
582 %
583 %\endpreamble
584 %
585 %\postamble
586 %\endpostamble
587 %
588 %\edef\defaultpreamble{\MetaPrefix\space -*-Tcl-*-^^J\defaultpreamble}
589 %
590 %\generate{\file{foo.tcl}{\from{foo.dtx}{bar}}}
591 %
592 %\end
593 %\end{verbatim}
594 %
595 % The generated file \texttt{foo.tcl} will contain
596 %\begin{verbatim}
597 %# -*-Tcl-*-
598 %#
599 %# This is file `foo.tcl',
600 %# generated with the docstrip utility.
601 %#
602 %# The original source files were:
603 %#
604 %# foo.dtx (with options: `bar')
605 %#
606 %# Copyright (c) <YEAR>, <OWNER>
607 %# All rights reserved.
608 %#
609 %# Redistribution and use in source and binary forms, with or without
610 %# modification, are permitted provided that the following conditions
611 %# are met:
612 %# * Redistributions of source code must retain the above copyright
613 %# notice, this list of conditions and the following disclaimer.
614 %# * Redistributions in binary form must reproduce the above
615 %# copyright notice, this list of conditions and the following
616 %# disclaimer in the documentation and/or other materials provided
617 %# with the distribution.
618 %#
619 %# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
620 %# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
621 %# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
622 %# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
623 %# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
624 %# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
625 %# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
626 %# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
627 %# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
628 %# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
629 %# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
630 %# POSSIBILITY OF SUCH DAMAGE.
631 %#
632 %\end{verbatim}
633 % \meta{lines extracted from \texttt{foo.dtx}}
634 %\begin{verbatim}
635 %#
636 %#
637 %# End of file `foo.tcl'.
638 %\end{verbatim}
639 %
640 %
641 %
642 % \subsection{The structure of the \LaTeX\ document}
643 %
644 % All this has been about the local appearance of a \texttt{.dtx} file,
645 % but what about the overall structure? There are several points to
646 % raise about that as well.
647 %
648 % The first is that \LaTeX\ to begin with treat \texttt{.dtx} documents
649 % just like any other document---a `|%|' starts a comment and only lines
650 % \emph{not} beginning with a `|%|' contain anything that \LaTeX\ can
651 % see. Somehow \LaTeX\ must be instructed to start applying the special
652 % reading rules that were described above. This is the job of the
653 % so-called \emph{driver}, which (for a file \texttt{myfile.dtx}) in its
654 % simplest form can look like
655 %\begin{verbatim}
656 %\documentclass{tclldoc}
657 %\begin{document}
658 %\DocInput{myfile.dtx}
659 %\end{document}
660 %\end{verbatim}
661 % The important command here is |\DocInput|, because that is what tells
662 % \LaTeX\ to apply the special \texttt{.dtx} reading rules. More
663 % precisely it means ``Start ignoring `|%|' characters in the text you
664 % read, input the file \texttt{myfile.dtx}, and when you're done return
665 % to treating `|%|' characters as before.''
666 %
667 % The driver is usually put in the very first stretch of code lines in
668 % the \texttt{.dtx} file. This means that \LaTeX, when ordered to typeset
669 % the \texttt{.dtx} file, will start to read along, possibly ignoring
670 % hundreds of lines beginning with `|%|' because they are comments. Then
671 % it encounters the driver, and after the |\documentclass| and
672 % |\begin{document}| commands it executes the |\DocInput|. This will
673 % cause it to not ignore lines beginning with `|%|', so when it starts
674 % reading the file again it will see all the lines it skipped the first
675 % time through. The file will be read to end, after which \LaTeX\
676 % returns to the command after the |\DocInput|. As that command happens
677 % to be |\end{document}|, it finishes the typeset document and stops.
678 % This stop prevents it from seeing and interpreting as \LaTeX\ commands
679 % the remaining code lines in the file.
680 %
681 % The second time through the driver shouldn't be interpreted as
682 % \LaTeX\ commands, since for example the |\documentclass| command may
683 % only be used once in a \LaTeX\ document. One way of achieving this is
684 % to put an |\iffalse| command right before the driver and a |\fi|
685 % command right after it. This says to \LaTeX\ that the driver code is
686 % conditional material, and since the condition evaluates to false
687 % (|\iffalse| always evaluates to false), this conditional material
688 % should be skipped. Thus the first few lines of \texttt{myfile.dtx}
689 % typically might be
690 %\begin{verbatim}
691 %% \iffalse
692 %%<*driver>
693 %\documentclass{tclldoc}
694 %\begin{document}
695 %\DocInput{myfile.dtx}
696 %\end{document}
697 %%</driver>
698 %% \fi
699 %\end{verbatim}
700 % The \texttt{driver} guard lines are there to stop \package{docstrip}
701 % from including the driver code in the generated files.
702 %
703 % After the driver comes the actual \LaTeX\ document. The document
704 % usually consists of two parts, where the first part is a manual for
705 % the \emph{usage} of the code defined in the file, and the second part
706 % contains the actual \emph{implementation} (documented code). The idea
707 % is that most people are (at least the first time) quite content with
708 % learning how to use something, so one should make it simple for them
709 % to find that information.\footnote{One needn't take this as an absolute
710 % rule---I for one haven't written all my packages that way---but
711 % structuring the document like this generally makes it more accessible.}
712 % To further this approach one puts the command |\StopEventually| at the
713 % start of the implementation part and the command |\Finale| at the end
714 % of it. Normally |\StopEventually| doesn't make itself felt, but if one
715 % previously has given the command |\OnlyDescription| then rest of the
716 % file will not be read; this can be used to produce a ``manual only''
717 % version of the documentation. |\StopEventually| takes one argument and
718 % the code in this argument is executed at the |\Finale| (if the
719 % implementation part is being included) or immediately (if the
720 % implementation part isn't being included). Thus this argument is the
721 % place to put things that should appear at the very end of the
722 % document.
723 %
724 % The \texttt{tcl}, \texttt{proc}, and \texttt{variable} environments
725 % described above all typically appear in the implementation part of the
726 % document.
727 %
728 %
729 % \section{Usage of commands and environments}
730 % \label{Sec:Manual}
731 %
732 %
733 % \subsection{The actual source code}
734 %
735 % The \DescribeEnv{tcl}\texttt{tcl} environment is used for wrapping up
736 % a group of code lines which contain \Tcl\ code. Lines inside this
737 % environment which begin with a percent character are called
738 % \emph{command} lines and can contain \LaTeX\ commands which get
739 % executed, whereas lines that do not begin with a percent character are
740 % called \emph{normal} lines and get typeset verbatim (or nearly
741 % verbatim). Lines that begin with |%<| (\package{docstrip} guard lines)
742 % do however constitute a special case, as the guard expression will get
743 % typeset as in \package{doc}'s \texttt{macrocode} environment and the
744 % remainder of the line will get processed in command mode if it is a
745 % |*| or |/| guard, but in normal mode if the guard line was of any other
746 % type.
747 %
748 % The \texttt{tcl} environment uses the same general formatting
749 % parameters as \package{doc}'s \texttt{macrocode} environment. In
750 % particular this means that the text on a normal line is typeset in
751 % |\MacroFont| (by default the same thing as \cs{normalfont}\penalty0
752 % \cs{ttfamily}\penalty0\cs{small}) or |\AltMacroFont| (by default the same
753 % thing as \cs{normalfont}\penalty0\cs{ttfamily}\penalty0\cs{itshape}^^A
754 % \penalty0\cs{small}) depending on the current \package{docstrip} module
755 % nesting level. The \package{tclldoc} class sets the
756 % \texttt{StandardModuleDepth} counter to 1, which means that the
757 % |\AltMacroFont| is used when the modules are nested two levels deep or
758 % more.
759 %
760 % If a normal line is too long to fit on one line then the \texttt{tcl}
761 % environment will try to break it. Legal breakpoints are spaces which
762 % could be replaced by a backslash and a newline without changing the
763 % meaning of the command; thus most spaces are legal breakpoints. When a
764 % line is broken at a space like this, the space is replaced by a
765 % backslash so that the line is still ``syntactically correct''. The
766 % opposite happens to lines which actually end with an escaped newline;
767 % such lines are concatenated with the following line and are treated as
768 % one long line. This is so that a sequence of breakpoints can be chosen
769 % which is optimal for the actual line width of the document (as opposed
770 % to the line width used in the text file, which can be something quite
771 % different). For example
772 %\begin{verbatim}
773 %% \begin{tcl}
774 %lsearch -exact\
775 % [concat $a [lrange $b $first end] c d e f]\
776 % [lindex $g $h]
777 %% \end{tcl}
778 %\end{verbatim}
779 % could be typeset as any of the code examples in
780 % Figure~\ref{Fig:Radbrytning}, depending on how wide a line is.
781 % \begin{figure}
782 % \begin{center}
783 % \small
784 % \(\left\lvert
785 % \begin{minipage}{350pt}
786 % \begin{flushleft}
787 % |lsearch -exact [concat $a [lrange $b $first end] c d e f]|^^A
788 % | [lindex $g $h]|
789 % \end{flushleft}
790 % \end{minipage}
791 % \right\rvert\)
792 %
793 % \smallskip
794 %
795 % \(\left\lvert
796 % \begin{minipage}{298pt}
797 % \begin{flushright}
798 % \noindent |lsearch -exact [concat $a [lrange $b $first|^^A
799 % | end] c d e f]|\textbackslash\hfill\vadjust{}\\
800 % |[lindex $g $h]|
801 % \end{flushright}
802 % \end{minipage}
803 % \right\rvert\)
804 %
805 % \smallskip
806 %
807 % \(\left\lvert
808 % \begin{minipage}{241pt}
809 % \begin{flushright}
810 % \noindent |lsearch -exact|\textbackslash\hfill\vadjust{}\\
811 % |[concat $a [lrange $b $first end] c d e f]|\textbackslash\\
812 % |[lindex $g $h]|
813 % \end{flushright}
814 % \end{minipage}
815 % \right\rvert\)
816 %
817 % \smallskip
818 %
819 % \(\left\lvert
820 % \begin{minipage}{184pt}
821 % \begin{flushright}
822 % \noindent |lsearch -exact [concat $a|\textbackslash\hfill
823 % \vadjust{}\\
824 % |[lrange $b $first end] c d e f]|\textbackslash\\
825 % |[lindex $g $h]|
826 % \end{flushright}
827 % \end{minipage}
828 % \right\rvert\)
829 % \end{center}
830 %
831 % \caption{The same \Tcl\ code, set in different linewidths}
832 % \label{Fig:Radbrytning}
833 % \end{figure}
834 % The environment tries to put the linebreaks at the lowest possible
835 % nesting (of braces and brackets) level; I believe this gives the best
836 % readability.\footnote{When I first started programming in \Tcl\ I
837 % used a completely different method for breaking long lines in the
838 % code---I mainly implemented the current method because it was
839 % simple to program---but I was quite surprised by how readable it made
840 % the code.} There is however a way to override this automatic choice
841 % of breakpoints: if a normal line which ends with an escaped newline is
842 % followed by a command line (even a command line that doesn't contain
843 % any commands) then it will not be concatenated with the next normal
844 % line.
845 %
846 % There are a couple of restrictions on the code in command lines. First
847 % of all it is not allowed to start a new paragraph (there will be an
848 % error message). Secondly a command may not be broken across several
849 % lines---all the arguments must appear on the same line as the
850 % control sequence. Thirdly some characters have other catcodes than
851 % in normal \LaTeX, so it is not certain that all commands work. Some
852 % commands that do work and may be useful are:
853 % \begin{itemize}
854 % \item Vertical space commands (|\smallskip|, |\medskip|, etc.)
855 % The command line `|% \medskip|' is more to type than a blank
856 % normal line, but it looks slightly better.
857 % \item Indexing commands (|\index|, |\IndexEntry|,\footnote{This
858 % command is defined by the \package{xdoc} package~\cite{xdoc}.}
859 % etc.)
860 % \item The \cs{TclInput} and |\settabsize| commands (see below).
861 % \end{itemize}
862 % And of course the |\end{tcl}| command works in a command line, since
863 % that is how one ends a \texttt{tcl} environment.
864 %
865 % Besides the \texttt{tcl} environment there is also a
866 % \DescribeEnv{tcl*}\texttt{tcl*} environment which is different from
867 % \texttt{tcl} only in that spaces and tabs are typeset as special
868 % visible space `\textvisiblespace' and visible tab
869 % `\makebox[6\fontdimen2\font]{\( - \mkern-7mu
870 % \cleaders\hbox{$\mkern-2mu - \mkern-2mu$}\hfill \mkern-7mu
871 % \mathord\rightarrow \mkern-1mu \vrule \mkern1mu\)}' characters. This
872 % can be useful for pieces of code where the exact number of spaces in
873 % a sequence is significant, such as code for writing tables that align.
874 %
875 % For shorter pieces of \Tcl\ code, e.g.\ examples, there's the
876 % \DescribeMacro{\tclverb}|\tclverb| command. |\tclverb| is very similar
877 % to the standard \LaTeX\ command |\verb|, but there are two differences.
878 % The first is that text typeset by |\tclverb| can contain breakpoints
879 % at whitespace; these behave just as in the \texttt{tcl} environment.
880 % The second is that the verbatim text that follows |\tclverb| may contain
881 % newlines, provided that these newlines are escaped by a backslash. Like
882 % a \Tcl\ interpreter, |\tclverb| ignores whitespace following an escaped
883 % newline. Unlike a \Tcl\ interpreter, |\tclverb| also ignores one percent
884 % character before the ignored whitespace, if it is the first character
885 % on the following line. Thus
886 %\begin{verbatim}
887 %% \tclverb|append a $b| is much more efficient than \tclverb|set a\
888 %% $a$b| if \tclverb|$a| is long.
889 %\end{verbatim}
890 % is perfectly legal, and the escaped newline between |a| and |$a$b| is
891 % treated just like the space between |set| and |a|. Like |\verb|, the
892 % |\tclverb| command has a starred form \DescribeMacro{\tclverb*}^^A
893 % |\tclverb*| which also typesets spaces and tabs as visible characters.
894 %
895 %
896 % The \DescribeMacro{\MakeShortTclverb}|\MakeShortTclverb| command works
897 % just like the \package{doc}\slash\package{shortvrb} command
898 % |\MakeShortVerb|, except that it makes the active character a shorthand
899 % reference for |\tclverb|\textellipsis\ instead of |\verb|\textellipsis.
900 % Use |\DeleteShortVerb| to undo the effect of a |\MakeShortTclverb|. The
901 % \package{tclldoc} class executes the command
902 % \begin{quote}
903 % \verb"\MakeShortTclverb{\|}"
904 % \end{quote}
905 % which makes \verb"|" a shorthand for \verb"\tclverb|".
906 %
907 % Since there is no universally accepted standard for the size
908 % (equivalent number of spaces) of a tab, there is a command
909 % \DescribeMacro{\settabsize}|\settabsize| for changing this.
910 % |\settabsize| takes as its only argument the new tab size, which must
911 % be an integer in the range 2--255. The default value is 8.
912 % |\settabsize| makes a local assignment to the tab size. The tab size
913 % can be changed inside a \texttt{tcl} (or \texttt{tcl*}) environment.
914 %
915 % There is also a command \DescribeMacro{\TclInput}|\TclInput| which
916 % is used for typesetting ``raw'' (not in \texttt{.dtx} format) \Tcl\ code
917 % files. |\TclInput| is meant to be used on a \emph{command} line of a
918 % \texttt{tcl} or \texttt{tcl*} environment, and it efficiently makes
919 % things look as if the |\TclInput| command had been replaced by the
920 % inputted file in its entirety (preceded by a newline, and followed
921 % by a percent and a space). |\TclInput| takes as its only argument the
922 % name of the file to input.
923 %
924 % To typeset the file \texttt{myscript.tcl} one would write
925 %\begin{verbatim}
926 %% \begin{tcl}
927 %% \TclInput{myscript.tcl}
928 %% \end{tcl}
929 %\end{verbatim} \iffalse
930 %</example>
931 % \fi
932 % or even
933 %\begin{verbatim}
934 % \begin{tcl}\TclInput{myscript.tcl}\end{tcl}
935 %\end{verbatim}
936 % anywhere in a \package{tclldoc} document. This works since the
937 % \texttt{tcl} environment is in command mode right after the initial
938 % |\begin{tcl}|, and the |\end{tcl}| needs not be the first command on a
939 % command mode line.
940 %
941 %
942 % \subsection{Markup of named things}
943 %
944 % The two environments \DescribeEnv{proc}\texttt{proc} and
945 % \DescribeEnv{variable}\texttt{variable}, which are analogues of
946 % \package{doc}'s \texttt{macro} environment, for procedures and
947 % variables respectively have already been mentioned in
948 % Section~\ref{Sec:Introduction}. In addition to those there are two
949 % environments \DescribeEnv{arrayentry}\texttt{arrayentry} and
950 % \DescribeEnv{arrayvar}\texttt{arrayvar} which are meant for entries
951 % in array variables and array variables as a whole. The complete
952 % syntaxes of these environments are
953 % \begin{quote}
954 % |\begin{proc}|\oarg{namespace}\marg{proc name}\\
955 % \vadjust{}\quad$\vdots$\\
956 % |\end{proc}|
957 %
958 % |\begin{variable}|\oarg{namespace}\marg{variable name}\\
959 % \vadjust{}\quad$\vdots$\\
960 % \quad|\end{variable}|
961 %
962 % |\begin{arrayentry}|\oarg{namespace}\marg{array name}^^A
963 % \marg{entry name}\\
964 % \vadjust{}\quad$\vdots$\\
965 % |\end{arrayentry}|
966 %
967 % |\begin{arrayvar}|\oarg{namespace}\marg{array name}^^A
968 % \oarg{index-des}\\
969 % \vadjust{}\quad$\vdots$\\
970 % |\end{arrayvar}|
971 % \end{quote}
972 % The \meta{proc name}, \meta{variable name}, and \meta{array name}
973 % arguments are quite evidently the names of the procedure, variable,
974 % and array respectively. The \meta{namespace} argument can be to
975 % specify the namespace part of a qualified name; having the name split
976 % like this makes it easier to treat the namespace differently from the
977 % rest of the qualified name. The command \DescribeMacro{\buildname}
978 % |\buildname| is used by the commands and environments described here to
979 % construct a qualified name from a namespace and a name.
980 % If there is no \meta{namespace} argument then the namespace used will
981 % be the default namespace. The default namespace is set using the
982 % \DescribeMacro{\setnamespace}|\setnamespace| command, which takes the
983 % namespace name as its only argument. The default namespace at the
984 % beginning of the document is the global namespace, whose name is the
985 % empty string.
986 %
987 % The \texttt{arrayentry} environment is intended for certain
988 % distinguished entries in an array, such as entries inserted to
989 % make the boundary cases of an algorithm work correctly and entries
990 % which have a special meaning to the program. Not all arrays contain
991 % such special entries, but when they do it is a good practice
992 % to explain them explicitly. The \meta{index-des} argument of the
993 % \texttt{arrayvar} environment can be used to specify what is used as
994 % index into the array; the text in this argument will appear both in
995 % the margin and in the index, but note that \meta{index-des} is a
996 % moving argument. There is little difference between the
997 % \texttt{variable} and \texttt{arrayvar} environments when the
998 % \meta{index-des} argument of the latter isn't used, but the index
999 % entries they make behave differently with respect to
1000 % \texttt{arrayentry} index entries. An \texttt{arrayentry} index entry
1001 % will be put as a subentry of the corresponding \texttt{arrayvar}
1002 % entry, whereas a \texttt{variable} entry would appear separately.
1003 %
1004 % The above environments usually only appear in the implementation part
1005 % of a \texttt{.dtx} file. For the usage part there is a command
1006 % \DescribeMacro{\describestring}|\describestring| which produces
1007 % marginal headings and index entries. The syntax of |\describestring|
1008 % is
1009 % \begin{quote}
1010 % |\describestring|\oarg{type}\oarg{namespace}\marg{text}
1011 % \end{quote}
1012 % The \meta{text} is the string for which a heading and index entry will
1013 % be made, whereas the \meta{type} (if given) is put after the text.
1014 % If the \meta{namespace} is given then the thing described is supposed
1015 % to be the name of something namespace-relative (like a procedure or
1016 % global variable) and in this case the complete name is formed by
1017 % passing \meta{namespace} and \meta{text} to |\buildname|. If
1018 % \meta{type} is \texttt{proc}, \texttt{var.}, or \texttt{array} and a
1019 % namespace is given then the index entry made will fit that made by
1020 % a corresponding \texttt{proc}, \texttt{variable}, or
1021 % \texttt{arrayvar} respectively environment. The \meta{type} argument
1022 % is, in \LaTeX\ terminology, moving.
1023 %
1024 % The \meta{text} and \meta{namespace} arguments can contain arbitrary
1025 % characters and most characters can be entered verbatim. Amongst the
1026 % exceptions are `|%|', `|\|', `|{|', and `|}|', which instead can be
1027 % entered as
1028 % |\PrintChar|\discretionary{}{}{}|{`\%}|,
1029 % |\PrintChar|\discretionary{}{}{}|{`\\}|,
1030 % |\PrintChar|\discretionary{}{}{}|{`\{}|, and
1031 % |\PrintChar|\discretionary{}{}{}|{`\}}| respectively. See the
1032 % \package{xdoc} package~\cite{xdoc} documentation for an explanation of
1033 % the |\PrintChar| command. The \meta{text} argument can also contain
1034 % ``variant'' parts made using the \DescribeMacro{\meta}|\meta| command.
1035 % As an example,
1036 % \begin{quote}
1037 % |\describestring[array]{\meta{mode}modeVars}|
1038 % \end{quote}
1039 % puts the text
1040 % \begin{quote}
1041 % \meta{mode}|modeVars| (array)
1042 % \end{quote}
1043 % in the margin and index. The arguments of such |\meta| commands are
1044 % moving.
1045 %
1046 % A case which deserves special treatment is that of options of
1047 % commands and for that there is the \DescribeMacro{\describeopt}
1048 % |\describeopt| command. The syntax of this command is
1049 % \begin{quote}
1050 % |\describeopt|*\oarg{namespace}\marg{command}\oarg{type}^^A
1051 % \marg{option}
1052 % \end{quote}
1053 % where \meta{command} is the command whose option is being described
1054 % and \meta{option} is the name of the option. \meta{namespace} is the
1055 % namespace of the \meta{command} and defaults to the global namespace.
1056 % \meta{type} is the type of the command and defaults to |proc| for
1057 % procedure. The \meta{namespace}, \meta{command}, and \meta{type} are
1058 % (currently) only used in the index entry that is generated. Options
1059 % for procedures will be put as subentries of the main procedure entry.
1060 % For built-in commands it might be more appropriate to use |command| as
1061 % \meta{type}, e.g.
1062 % \begin{quote}
1063 % |\describeopt{lsort}[command]{-real}|
1064 % \end{quote}
1065 % will put ``\texttt{-real} option'' in the margin and in the index as
1066 % a subentry of ``\texttt{lsort} (command), global namespace''. The |*|
1067 % is optional---including it will supress the marginal note normally
1068 % generated by this command.
1069 %
1070 % Since \Tcl\ is often used together with C, it might be useful to
1071 % also have something similar to the \texttt{proc} environment for C
1072 % things. This is what the \DescribeEnv{Cfunction}\texttt{Cfunction},
1073 % \DescribeEnv{Cvariable}\texttt{Cvariable}, and \DescribeEnv{Ctype}
1074 % \texttt{Ctype} environments are for. These take as their only
1075 % argument the name of the identifier that is defined, e.g.
1076 %\begin{verbatim}
1077 % \begin{Cfunction}{main}
1078 %\end{verbatim}
1079 % Since there seems to be several schools on how C code should be
1080 % formatted when typeset, the formatting of identifiers passed to these
1081 % environments is configurable. The three commands
1082 % \DescribeMacro{\Cfunctionidentifier}|\Cfunctionidentifier|,
1083 % \DescribeMacro{\Cvariableidentifier}|\Cvariableidentifier|, and
1084 % \DescribeMacro{\Ctypeidentifier}|\Ctypeidentifier| handle all
1085 % typesetting of identifiers; each takes as its only argument the
1086 % identifier (as a harmless string) to typeset. The default is to set
1087 % the argument in italic; this is what CWEB does.
1088 %
1089 % If you are using the \texttt{C}\dots\ environments for identifiers
1090 % whose names contain underscores (\_), you may want to pass the
1091 % \describeoption{notrawchar}\texttt{notrawchar} to \package{tclldoc}
1092 % (it is really an option of the \package{xdoc} package and will be
1093 % passed on to that automatically). This option addresses a problem
1094 % with \texttt{OT1}-encoded fonts that may cause underscores to display
1095 % as a quite different character (the \texttt{cmtt} typewriter fonts are
1096 % however not affected by this problem).
1097 %
1098 %
1099 %
1100 % \subsection{Describing command syntaxes}
1101 %
1102 % One important part of documentation is to describe the syntaxes of
1103 % commands. The previous subsection contains examples of the conventions
1104 % for this that has been developed for \LaTeX\
1105 % commands---mandatory arguments are denoted as `\marg{argument}' and
1106 % optional arguments are denoted as `\oarg{argument}'. These two classes
1107 % suffice rather well for \LaTeX\ commands, but the syntaxes of \Tcl\
1108 % commands are not seldom much more complex. Therefore a more powerful
1109 % form of syntax specification is called for, and one which is close at
1110 % hand is that used in regular expressions since it is already part of
1111 % the \Tcl\ language anyway.
1112 %
1113 % \DescribeMacro\regopt
1114 % \DescribeMacro\regstar
1115 % \DescribeMacro\regplus
1116 % The simplest commands available are the modifiers |\regopt|,
1117 % |\regstar|, and |\regplus|, which correspond to the |?|,
1118 % |*|, and |+| metacharacters in a regular expression; using |\regopt|
1119 % after a term says that it is optional, |\regstar| says that the term
1120 % can be repeated an arbitrary number of times (including zero), and
1121 % |\regplus| says that the term occurs at least once. The typeset
1122 % results of these commands are $^?$, $^*$, and $^+$ respectively
1123 % (recall that exponents are sometimes used to denote repetition).
1124 %
1125 % The terminals in the expression are best made using |\tclverb| (for
1126 % ``fixed'' material, e.g.\ procedure names) and
1127 % \DescribeMacro{\word}|\word| (for variable material, e.g.\
1128 % arguments). The syntax of |\word| is
1129 % \begin{quote}
1130 % |\word|\marg{text}
1131 % \end{quote}
1132 % and e.g.\ |\word{script}| gets typeset as
1133 % \begin{quote}
1134 % \word{script}
1135 % \end{quote}
1136 % Using these, one can for example specify the syntaxes of the \Tcl\
1137 % commands |append| and |catch| through
1138 % \begin{quote}
1139 % \verb"|append| \word{var-name} \word{value}\regplus"\\
1140 % \verb"|catch| \word{script} \word{var-name}\regopt"
1141 % \end{quote}
1142 % (recall that `\verb"|"' is a shorthand for `\verb"\tclverb|"'). These
1143 % get typeset as
1144 % \begin{quote}
1145 % |append| \word{var-name} \word{value}\(^+\)\\
1146 % |catch| \word{script} \word{var-name}\(^?\)
1147 % \end{quote}
1148 %
1149 % Terms in regular expressions can also consist of parenthesised
1150 % subexpressions, which are made using the \DescribeEnv{regblock}^^A
1151 % \texttt{regblock} environment. The syntax of this environment is
1152 % \begin{quote}
1153 % |\begin{regblock}|\oarg{modifier}\quad\dots\quad |\end{regblock}|
1154 % \end{quote}
1155 % If \texttt{regblock} environments are nested then the parentheses of
1156 % the outer environment will grow to be larger than those of the inner
1157 % environment. A side-effect of this is that the \texttt{regblock}
1158 % environment wants to know if a modifier will be applied to it, since
1159 % the amount by which the modifier should be raised in this case depends
1160 % on the size of the parenthesis before it, and this is what the
1161 % \meta{modifier} optional argument is for. \LaTeX\ does not provide
1162 % for arguments at the |\end| of an environment, so it has to be placed
1163 % at the |\begin|. Using these elements, the syntax of |if| can be
1164 % specified through
1165 % \begin{quote}
1166 % \verb"|if| \word{expression} |then|\regopt\ \word{script}"\\
1167 % \verb"\begin{regblock}[\regstar]|elseif| \word{expression}"\\
1168 % \verb"|then|\regopt\ \word{script}\end{regblock}"\\
1169 % \verb"\begin{regblock}[\regopt]|else| \word{script}\end{regblock}"
1170 % \end{quote}
1171 % which typesets as
1172 % \begin{isyntax}
1173 % |if| \word{expression} |then|\(^?\) \word{script} \(\bigl(\)^^A
1174 % |elseif| \word{expression} |then|\(^?\) \word{script}\(\bigr)^*\)
1175 % \(\bigl(\)|else|~\word{script}\(\bigr)^?\)
1176 % \end{isyntax}
1177 % In versions of \package{tclldoc} before 2.40, the \texttt{regblock}
1178 % environment used to be called \DescribeEnv{regexp}\texttt{regexp}.
1179 % That other name is still supported, but should be avoided in new
1180 % documents.
1181 %
1182 % The final regular expression construction that is supported is that
1183 % of branches of a regular expression. A \texttt{regblock} environment
1184 % consist of one or several branches that are separated by
1185 % \DescribeMacro{\regalt}|\regalt| commands. Visually the |\regalt|
1186 % command gets typeset as a vertical bar that has the same size as the
1187 % parentheses of the surrounding \texttt{regblock} environment. The
1188 % |\regalt| command may only be used inside a \texttt{regblock}
1189 % environment.
1190 % An example of the use of |\regalt| is the following specification of
1191 % the syntax of \Tcl's |regexp| command:
1192 % \begin{quote}
1193 % \verb"|regexp| \begin{regblock}[\regstar]|-nocase|\regalt"\\
1194 % \verb"|-indices|\end{regblock} |--|\regopt \word{regular expression}"\\
1195 % \verb"\word{string} \word{var-name}\regstar"
1196 % \end{quote}
1197 % which typesets as
1198 % \begin{isyntax}
1199 % |regexp| \((\)|-nocase|~\(\mid\) |-indices|\()^*\) |--|\(^?\)
1200 % \word{regular expression} \word{string} \word{var-name}\(^*\)
1201 % \end{isyntax}
1202 %
1203 % Finally a note about the relationship between the |\word| command and
1204 % \package{doc}'s |\meta| command. Whereas the argument of |\word| is
1205 % encapsulated in braces (and thus ought to be a separate word for a
1206 % \Tcl\ interpreter), the argument of |\meta| is encapsulated in angle
1207 % brackets. The idea is that |\word| should be used for things which are
1208 % separate words to \Tcl, whereas |\meta| should be used for things which
1209 % corresponds to parts of words or to several words. Thus in the command
1210 % |set b Z${a}Y|, the second word |b| would be a `\word{var-name}' and
1211 % the third word |Z${a}Y| would be a `|Z|\meta{string}|Y|'. In the
1212 % command |label .a -text "Hello there!"|, the last two arguments could
1213 % be summarised as an \meta{option}, but not as an \word{option}.
1214 %
1215 %
1216 % \subsection{Non-ASCII characters}
1217 %
1218 % One problem, which is only going to be more common in the future, is
1219 % how to deal with non-ASCII characters in scripts. The main problem
1220 % here lies not on the output side, as \LaTeX\ is actually pretty good
1221 % at producing a requested character as long as it is available in some
1222 % font, but on the input side. \LaTeX\ can handle input in most 8-bit
1223 % encodings, but in order for that to work the file must contain an
1224 % |\inputencoding| command which tells \LaTeX\ which encoding is being
1225 % used. As transporting a file from one platform to another most likely
1226 % changes the encoding, but not the argument of |\inputencoding|, this
1227 % method is rather fragile. Certainly there is room for improvements
1228 % but the world of 8-bit encodings is generally such a mess anyway that
1229 % it probably isn't worth the effort.
1230 %
1231 % A more progressive approach is to decide that all source code is in
1232 % Unicode (more precisely in UTF-8). The main arguments for this are:
1233 % (i)~\Tcl\ uses Unicode internally, (ii)~it is equally foreign on
1234 % all platforms and can be treated as binary data rather than ``extended
1235 % ASCII'' text, and (iii)~since it isn't converted, there is no loss of
1236 % data. Interestingly enough, \emph{it is possible to use UTF-8 ``out of
1237 % the box'' today!} Using the \package{ucs} package~\cite{ucs-package}
1238 % allows \LaTeX\ to interpret UTF-8 input and this works just as well
1239 % for the \Tcl\ code in a \texttt{tcl} environment as for the normal
1240 % \LaTeX\ text outside it. If \package{docstrip} is run on a \LaTeX\
1241 % format\footnote{Or, in some implementations, the \TeX\ program gets a
1242 % suitable option.} that preserves characters whose most significant
1243 % bit is set\footnote{Rather than converting them to
1244 % \texttt{\^{}\^{}}-sequences, which is the default.} then the non-ASCII
1245 % characters are simply copied verbatim and it makes no difference that
1246 % they may occupy more than one byte of data. Alternatively one can run
1247 % \package{docstrip} on Omega and (with a little extra work) get the
1248 % ability to have the \Tcl\ code translated to some other encoding as
1249 % the files are being generated!\footnote{At least in theory; I have to
1250 % admit I haven't actually tested the \package{docstrip} part of it.}
1251 %
1252 % But although the above paragraph describes the way to go in the long
1253 % run, there are some matters which make this approach slightly
1254 % unfeasible in the near future. This is of course my own subjective
1255 % opinion, but I find that two good reasons not to start using Unicode
1256 % throughout quite yet are that (i)~my favourite text editor doesn't
1257 % support Unicode (yet) and (ii)~even if I do start using it, there
1258 % wouldn't be that much people around who could make sense of such files
1259 % if I were to send it to them. Therefore I \emph{intend} to implement,
1260 % but as yet haven't, a kind of intermediate format where non-ASCII
1261 % Unicode characters are encoded using only ASCII characters plus an
1262 % extra escape character. The basic idea is simply that any string
1263 % `\meta{escape}\meta{hex digits}\meta{escape}' should be interpreted as
1264 % the Unicode character \texttt{U+}\meta{hex digits}, so that arbitrary
1265 % Unicode characters can be encoded using a character set that only
1266 % comprises ASCII plus one extra \meta{escape} character. Supposing that
1267 % this \meta{escape} character is the centered dot `\textperiodcentered',
1268 % I could then encode my name as
1269 % \begin{quote}
1270 % \texttt{Lars Hellstr\swtpc 00f6\swtpc m}
1271 % \end{quote}
1272 % whereas the centered dot itself would be \texttt{\swtpc 00b7\swtpc}.
1273 % The idea is that the file itself should contain the declaration of
1274 % which character is used as this Unicode escape, so that a change due
1275 % to translation from one 8-bit encoding to another will identically
1276 % alter both declaration and use of the escape character, thereby
1277 % preserving the internal logic of the file.
1278 %
1279 % The weak point with this scheme is that \package{docstrip} would have
1280 % to translate the escape sequences to proper characters when it
1281 % generates files. Implementing that under \TeX\ is highly non-trivial.
1282 % It can be done with a reasonable effort under Omega, but it still
1283 % requires hacking \package{docstrip}. The really interesting approach
1284 % would however be to implement it in a port of \package{docstrip} to
1285 % \Tcl, as that would remove the need to have \TeX\ to install the files.
1286 % Porting \package{docstrip} to \Tcl\ is by the way a project of mine
1287 % which I unfortunately haven't spent much time on, but if it is to be
1288 % of any use to have the Unicode escape format described above
1289 % implemented in \package{tclldoc} then I will have to make some
1290 % progress with it.
1291 %
1292 % \medskip
1293 %
1294 % One rather recent advancement in this direction is the code in
1295 % \texttt{sourcedtx.tcl}, which can be generated from the file
1296 % \texttt{sourcedtx.dtx} that is distributed with \package{tclldoc} as
1297 % an example. This implements a \Tcl\ command |dtx::source| that makes
1298 % it possible to source \Tcl\ code in a \texttt{.dtx} file without
1299 % docstripping it to a file first. This code does currently not bother
1300 % about encodings, but that is easy enough to add.
1301 %
1302 % \medskip
1303 %
1304 % Finally, a few notes on the old mechanism for non-ASCII characters
1305 % that is included in the \package{tcldoc} compatibility class. It
1306 % cooperates with the \package{rtkinenc} package~\cite{rtkinenc}, when
1307 % that has been loaded, in order to detect when an input character isn't
1308 % avaiable in any active font encoding. Rather than raising an error and
1309 % printing nothing it these cases, missing characters are written as the
1310 % corresponding |\x|\meta{hh} backslash sequence in a slightly different
1311 % font than the rest of the text. A problem here is however that most
1312 % input encodings contain a few characters which are interpreted as
1313 % \emph{math} character by \LaTeX. When such a character appears on a
1314 % code line it makes \TeX\ switch to math mode and things generally get
1315 % quite messy afterwards.
1316 %
1317 % The cure for this is to redeclare these input characters to \LaTeX\
1318 % so that they work as intended in text mode, but that does take some
1319 % lines of code. The \package{tcldoc} class does contain the
1320 % declarations needed for the \texttt{applemac} input encoding; passing
1321 % it the \describeoption{macinputenc}\texttt{macinputenc} option will
1322 % load the \package{rtkinenc} package, the \texttt{applemac} (macRoman)
1323 % input encoding, the \texttt{TS1} output encoding, and make the
1324 % necessary redeclarations to allow all input characters to work in
1325 % text. As nothing is provided for any other input encoding however,
1326 % this solution never was a good solution. The \texttt{macinputenc}
1327 % should be considered as unsupported as of \package{tclldoc} v\,2.30.
1328 %
1329 %
1330 %
1331 % \subsection{Options and customisation}
1332 %
1333 % The \package{tclldoc} package does not have any options of its own, but
1334 % all options passed to it are passed on to the \package{xdoc} package.
1335 % The \package{tclldoc} class accepts all options that the standard
1336 % \LaTeX\ document class \package{article} accepts, with the exception
1337 % of \texttt{a5paper}.
1338 %
1339 % Like the \package{ltxdoc} class, the \package{tclldoc} class will look
1340 % for a special configuration file \texttt{tclldoc.cfg} and input that
1341 % file if it exists. This file can be used to declare extra options for
1342 % the class, have certain options always given, etc. Section~2 of
1343 % \texttt{ltxdoc.dtx}~\cite{ltxdoc} is a good introduction to how such
1344 % configuration files can be used with \texttt{.dtx} sources in general.
1345 %
1346 % When you use a \texttt{tclldoc.cfg} file to customise the
1347 % \package{tclldoc} document class, you affect how all documents using
1348 % that class will be typeset in your particular \TeX\ installation. It
1349 % is \emph{not} something you have to do, but it can
1350 % make \package{tclldoc} documents work better with the printers, paper
1351 % formats, fonts, etc.\ that are available in your installation. It
1352 % will usually cause line and page breaks to occur at other places than
1353 % they would do if typeset using an uncustomised \package{tclldoc}
1354 % class, so the typographical quality of the document can be decreased,
1355 % but it is uncommon to find an \texttt{.dtx} document whose author
1356 % have given these matters much attention anyway. Hence the typographic
1357 % arguments against customisation are weak.
1358 %
1359 % A common form of customisation is to use additional packages, since
1360 % various kinds of document-wide font selection is often done by
1361 % packages. Due to that the code in \texttt{tclldoc.cfg} is executed when
1362 % the \package{tclldoc} class does its option processing, at which time
1363 % \LaTeX\ does not allow loading packages, such customisation is not
1364 % straightforward. There is a way around that however; to load e.g.\ the
1365 % \package{times} package, use the command
1366 %\begin{verbatim}
1367 %\AtEndOfClass{\usepackage{times}}
1368 %\end{verbatim}
1369 % Using |\AtEndOfClass| like this delays the command until it may be
1370 % executed.
1371 %
1372 %
1373 % \subsection{Miscellanea}
1374 %
1375 % For writing ``\Tcl'', the \package{tclldoc} package defines the command
1376 % \DescribeMacro{\Tcllogo}|\Tcllogo|, which for most fonts look slightly
1377 % better than simply typing |Tcl|. (|\Tcllogo| becomes \Tcl, whereas
1378 % |Tcl| becomes Tcl.)
1379 %
1380 % Between the namespace and the tail part of a qualified name, the
1381 % \package{tclldoc} package commands naturally put the name\-space
1382 % separator `|::|'. This text is stored in the macro
1383 % \DescribeMacro{\namespaceseparator}|\namespaceseparator|, which can be
1384 % redefined using the |\Declare|\-|Robust|\-|Command| command. This is
1385 % mainly useful for modifying how this separator behaves with respect to
1386 % line breaking; the default behaviour is that a line break can occur
1387 % between the colons.
1388 %
1389 % Another configurable piece of text is stored in the
1390 % \DescribeMacro{\namespacephrase}|\namespacephrase| macro. This
1391 % contains word `namespace' as that appears in index entries, e.g.~in
1392 % the last word of
1393 % \begin{quote}
1394 % \texttt{platform} (var.), \texttt{alpha} name\-space
1395 % \end{quote}
1396 % It is often convenient to replace this by something shorter. The
1397 % redefinition
1398 % \begin{quote}
1399 % |\renewcommand{\namespacephrase}{\textsc{ns}}|
1400 % \end{quote}
1401 % turns the above into
1402 % \begin{quote}
1403 % \texttt{platform} (var.), \texttt{alpha} \textsc{ns}
1404 % \end{quote}
1405 % Note however that either |\namespacephrase| itself or its expansion
1406 % must be robust.
1407 %
1408 %
1409 % \section{Acknowledgements}
1410 %
1411 % The \package{tclldoc} document class and \LaTeX\ package were
1412 % constructed starting from three other sources: (i)~the \package{ltxdoc}
1413 % document class~\cite{ltxdoc} by David Carlisle,
1414 % (ii)~the \package{doc} package~\cite{doc} by Frank Mittelbach,
1415 % B.~Hamilton Kelly, Andrew Mills, Dave Love, and Joachim Schrod, and
1416 % (iii)~my own \package{pasdoc} document class. Hence the `et al.'\ in
1417 % the author field above. This complicated heritage in the code is
1418 % mirrored by the documented source---there are paragraphs below that
1419 % are rather about one of (i)--(iii), than about \package{tclldoc}.
1420 %
1421 %
1422 %
1423 % \StopEventually{
1424 % \begin{thebibliography}{9}
1425 % \bibitem{ltoutenc}
1426 % Johannes Braams, David Carlisle, Alan Jeffrey, Frank
1427 % Mittelbach, Chris Rowley, and Rainer Sch\"opf:
1428 % \textit{ltoutenc.dtx}, The \LaTeX3 Project;
1429 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
1430 % \texttt{latex}\slash \texttt{base}\slash \texttt{ltoutenc.dtx}.
1431 % \bibitem{ltxdoc}
1432 % David Carlisle:
1433 % \textit{The file \texttt{ltxdoc.dtx} for use with \LaTeXe},
1434 % The \LaTeX3 Project;
1435 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
1436 % \texttt{latex}\slash \texttt{base}\slash \texttt{ltxdoc.dtx}.
1437 % \bibitem{rtkinenc}
1438 % Lars Hellstr\"om:
1439 % \textit{The \package{rtkinenc} package}, 2000;
1440 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
1441 % \texttt{latex}\slash \texttt{contrib}\slash
1442 % \texttt{supported}\slash \texttt{rtkinenc}\slash
1443 % \texttt{rtkinenc.dtx}.
1444 % \bibitem{xdoc}
1445 % Lars Hellstr\"om:
1446 % \textit{The \package{xdoc} package --- experimental
1447 % reimplementations of features from \package{doc},
1448 % second~prototype}, 2000, 2001;
1449 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
1450 % \texttt{latex}\slash \texttt{exptl}\slash \texttt{xdoc}\slash
1451 % \texttt{xdoc2.dtx}.
1452 % \bibitem{docindex}
1453 % Lars Hellstr\"om:
1454 % \textit{The \package{docindex} package}, 2001;
1455 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
1456 % \texttt{latex}\slash \texttt{exptl}\slash \texttt{xdoc}\slash
1457 % \texttt{docindex.dtx}.
1458 % \bibitem{TeXbook}
1459 % Donald E.\ Knuth, Duane Bibby (illustrations):
1460 % \textit{The \TeX book}, Ad\-di\-son--Wes\-ley, 1984;
1461 % ISBN~0-201-13448-9 and~0-201-13447-0.
1462 % \bibitem{docstrip}
1463 % Frank Mittelbach, Denys Duchier, Johannes Braams, Marcin
1464 % Woli\'nski, and Mark Wooding: \textit{The \textsf{DocStrip}
1465 % program}, The \LaTeX3 Project;
1466 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
1467 % \texttt{latex}\slash \texttt{base}\slash \texttt{docstrip.dtx}.
1468 % \bibitem{doc}
1469 % Frank Mittelbach, B.~Hamilton Kelly, Andrew Mills, Dave Love, and
1470 % Joachim \mbox{Schrod}: \textit{The \package{doc} and
1471 % \package{shortvrb} Packages}, The \LaTeX3 Project;
1472 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
1473 % \texttt{latex}\slash \texttt{base}\slash \texttt{doc.dtx}.
1474 % \bibitem{execMagic}
1475 % ``Tom'', Donal Fellows, Larry Virden, Richard Suchenwirth:
1476 % \textit{exec magic}, The \Tcl'ers Wiki page \textbf{812};
1477 % \textsc{http}:/\slash \texttt{mini.net}\slash \texttt{tcl}\slash
1478 % \texttt{812.html}.
1479 % \bibitem{ucs-package}
1480 % Dominique~P.~G.~Unruh:
1481 % \textit{\texttt{ucs.sty} - Unicode Support}, 2000;
1482 % \textsc{ctan}:\discretionary{}{}{\thinspace}\texttt{macros}\slash
1483 % \texttt{latex}\slash \texttt{contrib}\slash
1484 % \texttt{supported}\slash \texttt{unicode}/.
1485 % \end{thebibliography}
1486 % \begin{flushleft}\footnotesize
1487 % The ``\textsc{ctan}:'' above is short for ``any of the servers
1488 % in the Comprehensive \TeX\ Archive Network (or mirror thereof)''.
1489 % You get a working URL if you replace this by e.g.\
1490 % ``\texttt{ftp://ftp.tex.ac.uk/tex-archive/}''.%
1491 % \end{flushleft}
1492 % }
1493 %
1494 %
1495 % \changes{v\,1.90}{2000/01/02}{Took a copy of \texttt{pasdoc.dtx} and
1496 % started modifying it into \texttt{tcldoc.dtx}. (LH)}
1497 %
1498 % \section{Initial stuff in the \package{tclldoc} package}
1499 %
1500 % The |\NeedsTeXFormat| and |\ProvidesPackage| commands for the
1501 % \package{tclldoc} package appear at the top of \texttt{tclldoc.dtx} (not
1502 % shown in the typeset document). Apart from that the only initial
1503 % action required is to load the \package{xdoc} package (and thereby
1504 % the \package{doc} package) and the \package{docindex} (or rather the
1505 % \LaTeXe\ version \package{docidx2e}) package.
1506 % \SortIndex{docindex package}{\package{docindex} package}
1507 %
1508 % \changes{v\,2.23}{2001/07/21}{Added message about using
1509 % docindex.ist. (LH)}
1510 % \begin{macrocode}
1511 %<*pkg>
1512 \RequirePackageWithOptions{xdoc2}[2001/11/03]
1513 \RequirePackage{docidx2e}
1514 \AtEndDocument{%
1515 \typeout{********************************}%
1516 \typeout{* Use docindex.ist when\@spaces\@spaces*}%
1517 \typeout{* sorting .idx and .glo files. *}%
1518 \typeout{********************************}%
1519 }%
1520 % \end{macrocode}
1521 %
1522 %
1523 % \section{Verbatim typesetting of \Tcl\ code}
1524 %
1525 % \changes{v\,2.10}{2000/10/03}{Major overhaul of the \texttt{tcl}
1526 % environment, to make it possible to assign different penalties to
1527 % different breakpoints. (LH)}
1528 %
1529 % The main feature in the \package{tclldoc} package is the \texttt{tcl}
1530 % environment, which typesets embedded code in a way more adapted to
1531 % \Tcl\ code than what the \texttt{macrocode} environment does.
1532 %
1533 %
1534 % \subsection{Beginning of line processing}
1535 %
1536 % The organization of the text in \emph{lines} is crucial for its
1537 % interpretation by the \texttt{tcl} environment. In particular the
1538 % following features rely on being at the beginning of a line:
1539 % \begin{itemize}
1540 % \item indentation of \Tcl\ code,
1541 % \item invoking command mode,
1542 % \item recognizing \package{docstrip} guards.
1543 % \end{itemize}
1544 %
1545 % \begin{macro}{\TD@percent@token}
1546 % A control sequence |\let| to a |%|$_{12}$, mainly for use in |\ifx|
1547 % comparisons.
1548 % \DoNotIndex{\%}
1549 % \begin{macrocode}
1550 \begingroup
1551 \catcode`\%=12
1552 \global\let\TD@percent@token=%
1553 \endgroup
1554 % \end{macrocode}
1555 % \end{macro}
1556 %
1557 % \begin{macro}{\TD@start@n@line}
1558 % \begin{macro}{\TD@start@n@line@}
1559 % \begin{macro}{\TD@start@n@line@i}
1560 % The macro |\TD@start@n@line| is used at the beginning of every line.
1561 % The macro first clears the |\TD@line@indent| and |\TD@nesting@level|
1562 % registers and the |\TD@nesting@stack| stack. Then it checks if the
1563 % next character is a percent. If it is then this is a command line.
1564 % If it isn't then it is a normal line and it is time to start a
1565 % codeline paragraph and count the character indentation.
1566 %
1567 % |\TD@|\-|start@|\-|n@|\-|line@| is the macro which actually does
1568 % these things; |\TD@|\-|start@|\-|n@|\-|line| is usually |\let| to
1569 % |\TD@|\-|start@|\-|n@|\-|line@|. When a file is being |\TclInput|ed
1570 % however, |\TD@|\-|start@|\-|n@|\-|line| is |\let| to
1571 % |\TD@|\-|start@|\-|n@|\-|line@i| which peeks at the next token
1572 % before calling |\TD@|\-|start@|\-|n@|\-|line@|. If it didn't,
1573 % |\TD@|\-|start@|\-|n@|\-|line@| would have a problem at the end of
1574 % the file, since the end of a file counts as being |\outer|.
1575 % \begin{macrocode}
1576 \def\TD@start@n@line@#1{%
1577 \global\TD@line@indent=\z@
1578 \TD@nesting@level=\z@
1579 \def\TD@nesting@stack{\TD@nesting@level}%
1580 \ifx #1\TD@percent@token
1581 \expandafter\TD@module
1582 \else
1583 \global\advance \c@codelineno \@ne
1584 \TD@begin@tclpar
1585 \expandafter\TD@count@indent \expandafter#1%
1586 \fi
1587 }
1588 % \end{macrocode}
1589 % \begin{macrocode}
1590 \let\TD@start@n@line=\TD@start@n@line@
1591 \def\TD@start@n@line@i{\futurelet\next\TD@start@n@line@}
1592 % \end{macrocode}
1593 % \end{macro}\end{macro}\end{macro}
1594 %
1595 %
1596 % \begin{macro}{\TD@count@indent}
1597 % The purpose of the |\TD@count@indent| macro is to compute the
1598 % indentation of the current line. It grabs the next character, and
1599 % as long as that is a space or tab it will just increment
1600 % |\TD@line@indent| accordingly and continue with the next character.
1601 % |!| and |"| are used to make space and tab respectively with
1602 % suitable catcode.
1603 % \DoNotIndex{\!,\",\ ,\^}
1604 % \begin{macrocode}
1605 \begingroup
1606 \catcode`\!=\active
1607 \catcode`\"=\active
1608 \lccode`\!=`\ %
1609 \lccode`\"=`\^^I%
1610 \lowercase{%
1611 \endgroup
1612 \def\TD@count@indent#1{%
1613 \ifx !#1%
1614 \global\advance \TD@line@indent \@ne
1615 \expandafter\TD@count@indent
1616 \else \ifx "#1%
1617 \global\divide \TD@line@indent \TD@tab@size
1618 \global\advance \TD@line@indent \@ne
1619 \global\multiply \TD@line@indent \TD@tab@size
1620 \expandafter\expandafter \expandafter\TD@count@indent
1621 \else
1622 \TD@setup@parshape
1623 \expandafter\expandafter \expandafter#1%
1624 \fi\fi
1625 }%
1626 }
1627 % \end{macrocode}
1628 % \end{macro}
1629 %
1630 %
1631 % \begin{macro}{\TD@module}
1632 % When command mode has been properly established it is time to
1633 % check if the next character is |<|, in which case the following
1634 % \package{docstrip} guard must be processed. |\TD@command| must
1635 % appear before the |\futurelet| so that the following character
1636 % won't get tokenized with incorrect catcodes.
1637 % \changes{v\,2.13}{2000/12/20}{Always check whether the current line
1638 % is a guard line, since the \texttt{\PrintChar{\number`\<}} in
1639 % the guard would otherwise start a new paragraph, which is an
1640 % error. (LH)}
1641 % \begin{macrocode}
1642 \def\TD@module{%
1643 \TD@command
1644 \futurelet\next
1645 \TD@ch@angle
1646 }
1647 % \end{macrocode}
1648 % \end{macro}
1649 %
1650 %
1651 % \begin{macro}{\TD@ch@angle}
1652 % The module checking in \package{tclldoc} takes advantage of the
1653 % macros for this in \package{doc}---|\ch@plus@etc| is a \package{doc}
1654 % macro. |<| is active because it is in the nolig list
1655 % (|\verbatim@|\-|nolig@|\-|list|).
1656 % \changes{v\,2.20}{2001/03/12}{Moved \cs{TD@normal} previously in
1657 % \cs{TD@pm@module} to here. This means \package{docstrip} guard are
1658 % now read in normal mode rather than command mode. This change
1659 % was made because of grouping problems that occured on non-block
1660 % guard lines. Also added local redefinition of \PrintChar{13} to
1661 % prevent that guard lines are concatenated with the following
1662 % line. (LH)}
1663 % \DoNotIndex{\^}
1664 % \begin{macrocode}
1665 \begingroup
1666 \catcode`<=\active
1667 \catcode`\^^I=\catcode`\^^M \endlinechar=`\^^I \relax
1668 \catcode`\^^M=\active
1669 \gdef\TD@ch@angle{%
1670 \ifx <\next
1671 \TD@normal
1672 \global\advance \c@codelineno \@ne
1673 \TD@begin@tclpar
1674 \def^^M{\TD@active@CR}%
1675 \expandafter\futurelet \expandafter\next
1676 \expandafter\ch@plus@etc
1677 \fi
1678 }
1679 \endgroup
1680 % \end{macrocode}
1681 % \end{macro}
1682 %
1683 % \begin{macro}{\TD@pm@module}
1684 % The |\TD@pm@module| macro is used instead of \package{doc}'s
1685 % |\pm@module| when in the \texttt{tcl} environment. This is necessary
1686 % since the paragraph man\oe uvres of the \texttt{tcl} environment would
1687 % not work right with \package{doc}'s |\pm@module|.
1688 %
1689 % If we're not dealing with a block directive (|*| or |/|), i.e.,
1690 % it's a single special line, we set everything up to the next |>|
1691 % appropriately, return to normal mode, possibly change font, and
1692 % start counting indentation spaces.
1693 % \DoNotIndex{\>}
1694 % \begin{macrocode}
1695 \begingroup
1696 \catcode`\>=\active
1697 \gdef\TD@pm@module#1>{%
1698 \Module{#1}%
1699 \ifnum \guard@level<\c@StandardModuleDepth \else
1700 \AltMacroFont
1701 \fi
1702 \TD@count@indent
1703 }
1704 \endgroup
1705 % \end{macrocode}
1706 % \end{macro}
1707 %
1708 %
1709 % \begin{macro}{\TD@star@module}
1710 % \changes{v\,2.20}{2001/03/12}{Removed \cs{TD@end@tclpar}. (LH)}
1711 % \changes{v\,2.22}{2001/06/13}{Reinserted \cs{TD@end@tclpar} and
1712 % added \cs{TD@command}; this solves a problem with grouping that
1713 % prevented a font change from getting effect. (LH)}
1714 % \begin{macro}{\TD@slash@module}
1715 % \changes{v\,2.20}{2001/03/12}{Removed \cs{TD@end@tclpar}. (LH)}
1716 % \changes{v\,2.22}{2001/06/13}{Same change as in
1717 % \cs{TD@star@module}. (LH)}
1718 % The |\TD@star@module| and |\TD@slash@module| macros are, like
1719 % |\TD@pm@module|, used instead of \package{doc}'s |\star@module| and
1720 % |\slash@module| respectively when in the \texttt{tcl} environment.
1721 % \DoNotIndex{\>}
1722 % \begin{macrocode}
1723 \begingroup
1724 \catcode`\>=\active
1725 \gdef\TD@star@module#1>{%
1726 \Module{#1}%
1727 \TD@end@tclpar
1728 \TD@command
1729 \global\advance \guard@level \@ne
1730 \ifnum \c@StandardModuleDepth<\guard@level
1731 \global\let\macro@font=\AltMacroFont
1732 \macro@font
1733 \fi
1734 }
1735 \gdef\TD@slash@module#1>{%
1736 \Module{#1}%
1737 \TD@end@tclpar
1738 \TD@command
1739 \global\advance \guard@level \m@ne
1740 \ifnum \guard@level=\c@StandardModuleDepth
1741 \global\let\macro@font\MacroFont
1742 \macro@font
1743 \fi
1744 }
1745 \endgroup
1746 % \end{macrocode}
1747 % \end{macro}\end{macro}
1748 %
1749 %
1750 % \begin{macro}{\TD@gobble@whitespace}
1751 % This macro gobbles all normal mode spaces and tabs following it.
1752 % \begin{macrocode}
1753 \def\TD@gobble@whitespace#1{%
1754 \if \ifx #1\TD@active@space
1755 0%
1756 \else
1757 \ifx #1\TD@active@tab 0\else 1\fi
1758 \fi 0%
1759 \expandafter\TD@gobble@whitespace
1760 \else
1761 \expandafter#1%
1762 \fi
1763 }
1764 % \end{macrocode}
1765 % \end{macro}
1766 %
1767 %
1768 %
1769 % \subsection{Typographical elements}
1770 %
1771 % This subsection contains definitions of the typographical
1772 % elements---special symbols and the like--that are used in the
1773 % \texttt{tcl} and \texttt{tcl*} environments.
1774 %
1775 %
1776 % \begin{macro}{\TD@typography}
1777 % \begin{macro}{\TD@nontcl@font}
1778 % The |\TD@typography| macro does all the typographic set-up that is
1779 % common to the \texttt{tcl} environment, the \texttt{tcl*}
1780 % environment, and the |\tclverb| command.
1781 %
1782 % The |\TD@nontcl@font| macro selects an ``escape'' font for \Tcl\
1783 % material. This font is used for various kinds of escape codes that
1784 % are typeset instead of some character---either because the
1785 % character is not available, or because the line needs to be broken.
1786 % The escape font will have the same font family (and same encoding)
1787 % as the text surrounding the \texttt{tcl} environment or |\tclverb|
1788 % command. Therefore |\TD@nontcl@font| must be defined before the
1789 % \Tcl\ material font is selected. I don't think it is necessary to
1790 % use |\protected@edef| below, but it can't hurt either.
1791 % \begin{macrocode}
1792 \def\TD@typography{%
1793 \protected@edef\TD@nontcl@font{%
1794 \noexpand\fontencoding{\cf@encoding}%
1795 \noexpand\fontfamily{\f@family}\noexpand\selectfont
1796 }%
1797 % \end{macrocode}
1798 % The most frequent escape symbol is the single backslash used for
1799 % escaping the end of lines, and this is stored in the
1800 % |\TD@backslash@box| box.
1801 %
1802 % The following code have to do with how characters outside
1803 % visible ASCII are typeset when they appear in the \texttt{tcl} or
1804 % \texttt{tcl*} environment. The commands are defined by the
1805 % \package{rtkinenc} package.
1806 % \begin{macrocode}
1807 \InputModeCode
1808 \SetUnavailableAction{\leavevmode{%
1809 \TD@nontcl@font\textbackslash x\TypesetHexNumber{##1}%
1810 }}%
1811 \DeclareInputMath{0}{\RIE@undefined{0}}%
1812 \DeclareInputMath{12}{\RIE@undefined{12}}%
1813 }
1814 % \end{macrocode}
1815 % \end{macro}\end{macro}
1816 %
1817 % \begin{macro}{\TD@typeset@space}
1818 % This macro typesets a space, as it should be in the \texttt{tcl}
1819 % environment (and other places too). It generates a kern, not glue, so
1820 % that it can be used in a |\discretionary|.
1821 % \begin{macrocode}
1822 \def\TD@typeset@space{\kern\fontdimen\tw@\font}
1823 % \end{macrocode}
1824 % \end{macro}
1825 %
1826 % \begin{macro}{\TD@discretionary@space}
1827 % This is the macro which offers all the breakpoints in |\tclverb|
1828 % code. The name comes from the fact that all the breakpoints are
1829 % discretionaries which appear to be spaces when not broken. When
1830 % they are broken, they are backslashes. To give some visual hint
1831 % that these backslashes need not be backslashes in the source, they
1832 % are typeset in the same font family (and same encoding) as the
1833 % text surrounding the \texttt{tcl} environment.
1834 % \begin{macrocode}
1835 \def\TD@discretionary@space{%
1836 \discretionary{\copy\TD@backslash@box}{}{\TD@typeset@space}%
1837 }%
1838 % \end{macrocode}
1839 % \end{macro}
1840 %
1841 % \begin{macro}{\TD@breakable@space}
1842 % The valid breakpoints inside \texttt{tcl} and \texttt{tcl*}
1843 % environments are made in the |\TD@|\-|breakable@|\-|space| macro.
1844 % This macro contributes an |\hbox| (which contains a
1845 % |\TD@typeset@space|), a penalty, and an empty |\vadjust| to the
1846 % current horizontal list. If a line break is made at the penalty,
1847 % the |\hbox| will later be removed and replaced by a non-macro font
1848 % backslash (from |\TD@backslash@box|). The |\vadjust| is there to
1849 % prevent that any discardable items disappears after the breakpoint.
1850 % \begin{macrocode}
1851 \def\TD@breakable@space{%
1852 \hbox{\TD@typeset@space}%
1853 \TD@nesting@penalty
1854 \vadjust{}%
1855 }
1856 % \end{macrocode}
1857 % \end{macro}
1858 %
1859 % \begin{macro}{\TD@typeset@tab}
1860 % This is an unbreakable space whose width equals that of
1861 % |\TD@tab@size| spaces.
1862 % \begin{macrocode}
1863 \def\TD@typeset@tab{\kern\TD@tab@size\fontdimen\tw@\font}
1864 % \end{macrocode}
1865 % \end{macro}
1866 %
1867 % \begin{macro}{\TD@visible@whitespace}
1868 % The |\TD@visible@whitespace| macro locally redefines the macros
1869 % which typesets spaces and tabs to make visible symbols. The visible
1870 % tab is roughly a |\rightarrowfill| and a |\vrule|, but a difference
1871 % is that the minuses that form the extensible ``tail'' to the
1872 % |\rightarrow| are not smashed. Not doing that gives the |\vrule| a
1873 % suitable height, but I had rather expected the nominal height of
1874 % the |\rightarrow| to be larger \textellipsis\ It's yet another
1875 % mysterious math font feature, I suppose.
1876 %
1877 % \begin{macrocode}
1878 \def\TD@visible@whitespace{%
1879 \def\TD@typeset@space{\char32 }%
1880 \def\TD@typeset@tab{%
1881 \hb@xt@\TD@tab@size\fontdimen\tw@\font{%
1882 $\m@th-\mkern-7mu%
1883 \cleaders\hbox{$\mkern-2mu-\mkern-2mu$}\hfill
1884 \mkern-7mu\mathord\rightarrow\mkern-1mu\vrule\mkern1mu$%
1885 }%
1886 }%
1887 }
1888 % \end{macrocode}
1889 % \end{macro}
1890 %
1891 %
1892 % \subsection{Catcodes and active characters}
1893 %
1894 % Like any \texttt{verbatim}-like environment, the \texttt{tcl}
1895 % environment does some rather extensive alterations of catcodes. This
1896 % is handled by the three macros |\TD@general|, |\TD@normal|, and
1897 % |\TD@command|. Set-up that is common for both modes is made by
1898 % |\TD@general| when the \texttt{tcl} environment is entered.
1899 % Mode-dependent set-up is made by |\TD@normal| and |\TD@command|
1900 % whenever a mode switch occurs.
1901 %
1902 % \begin{macro}{\TD@let@active}
1903 % One technicality here is that all of these routines need to set the
1904 % definition of some active character, and this character is often not
1905 % active with normal \LaTeX\ catcodes. To overcome this difficulty,
1906 % there is a macro |\TD@let@active| which takes two arguments: a
1907 % control sequence with a single character name, and an arbitrary
1908 % control sequence. The active character with the same name as the
1909 % first control sequence is |\let| locally to the second control
1910 % sequence.
1911 % \begin{macrocode}
1912 \begingroup
1913 \catcode\z@=\active
1914 \gdef\TD@let@active#1{%
1915 \begingroup
1916 \lccode\z@=`#1%
1917 \lowercase{%
1918 \endgroup
1919 \let^^@%
1920 }%
1921 }%
1922 \endgroup
1923 % \end{macrocode}
1924 % \end{macro}
1925 %
1926 %
1927 % \begin{macro}{\TD@general}
1928 % The |\TD@general| macro does the initial set-ups that are common for
1929 % both modes of the \texttt{tcl} environment and for the |\tclverb|
1930 % command. These include definitions of various active characters and
1931 % |\catcode| assignments.
1932 %
1933 % \DoNotIndex{\^,\ ,\\,\[,\]}
1934 % \DoNotIndexHarmless{\PrintChar{`\{}}
1935 % \DoNotIndexHarmless{\PrintChar{`\}}}
1936 % \begin{macrocode}
1937 \def\TD@general{%
1938 \let\do\do@noligs
1939 \verbatim@nolig@list
1940 \let\do\@makeother
1941 \dospecials
1942 \catcode`\^^M=\active
1943 \TD@let@active\^^I\TD@active@tab
1944 \TD@let@active\^^M\TD@active@CR
1945 \TD@let@active\ \TD@active@space
1946 \TD@let@active\\\TD@active@backslash
1947 \TD@let@active\{\TD@active@braceleft
1948 \TD@let@active\}\TD@active@braceright
1949 \TD@let@active\[\TD@active@bracketleft
1950 \TD@let@active\]\TD@active@bracketright
1951 }
1952 % \end{macrocode}
1953 % \end{macro}
1954 %
1955 %
1956 % \begin{macro}{\TD@normal}
1957 % This macro sets up the normal mode, changing everything that is
1958 % different in any of the other modes. Note that the catcodes in
1959 % normal mode are such that no character is a space. This makes it
1960 % possible for macros used in normal mode to look ahead by simply
1961 % grabbing the next character in an undelimited argument.
1962 % \DoNotIndex{\^,\ ,\\,\[,\]}
1963 % \DoNotIndexHarmless{\PrintChar{`\{}}
1964 % \DoNotIndexHarmless{\PrintChar{`\}}}
1965 % \begin{macrocode}
1966 \def\TD@normal{%
1967 \catcode`\^^I=\active
1968 \catcode`\ =\active
1969 \catcode`\\=\active
1970 \catcode`\{=\active
1971 \catcode`\}=\active
1972 \catcode`\[=\active
1973 \catcode`\]=\active
1974 }
1975 % \end{macrocode}
1976 % \end{macro}
1977 %
1978 % \begin{macro}{\TD@command}
1979 % This macro switches from normal mode to command mode.
1980 % \DoNotIndex{\^,\ ,\\,\[,\]}
1981 % \DoNotIndexHarmless{\PrintChar{`\{}}
1982 % \DoNotIndexHarmless{\PrintChar{`\}}}
1983 % \begin{macrocode}
1984 \def\TD@command{%
1985 \catcode`\^^I=10%
1986 \catcode`\ =10%
1987 \catcode`\[=12%
1988 \catcode`\]=12%
1989 \catcode`\\=\z@
1990 \catcode`\{=\@ne
1991 \catcode`\}=\tw@
1992 }
1993 % \end{macrocode}
1994 % \end{macro}
1995 %
1996 %
1997 % \begin{macro}{\TD@active@space}
1998 % \begin{macro}{\TD@active@space@}
1999 % This macro is used for spaces in normal mode. Its main problem is
2000 % to determine whether it is followed by more whitespace or not. If it
2001 % is, then it is an unbreakable space. If it isn't, then it is a
2002 % breakable space.
2003 % \begin{macrocode}
2004 \def\TD@active@space#1{%
2005 \ifx #1\TD@active@backslash
2006 \expandafter\TD@active@space@
2007 \else
2008 \ifx #1\TD@active@space
2009 \TD@typeset@space
2010 \else\ifx #1\TD@active@tab
2011 \TD@typeset@space
2012 \else
2013 \TD@breakable@space
2014 \fi\fi
2015 \expandafter#1%
2016 \fi
2017 }
2018 % \end{macrocode}
2019 % The special case to look out for is that the next character is a
2020 % backslash which escapes a newline.
2021 % \begin{macrocode}
2022 \def\TD@active@space@#1{%
2023 \ifx #1\TD@active@CR
2024 \TD@typeset@space
2025 \else
2026 \TD@breakable@space
2027 \fi
2028 \TD@active@backslash #1%
2029 }
2030 % \end{macrocode}
2031 % \end{macro}\end{macro}
2032 %
2033 % \begin{macro}{\TD@active@tab}
2034 % The |\TD@active@tab| macro is what the active character tab is
2035 % |\let| to inside the \texttt{tcl} and \texttt{tcl*} environments.
2036 % \begin{macrocode}
2037 \def\TD@active@tab{\TD@typeset@tab}
2038 % \end{macrocode}
2039 % \end{macro}
2040 %
2041 % \begin{macro}{\TD@active@CR}
2042 % This macro is called at the end of a line. The |\catcode| tests the
2043 % current mode.
2044 % \DoNotIndex{\\}
2045 % \begin{macrocode}
2046 \def\TD@active@CR{%
2047 \ifnum \catcode`\\=\z@
2048 \ifvmode\else
2049 \PackageError{tclldoc}{Horizontal material on command line}\@ehc
2050 \@@par
2051 \fi
2052 \TD@normal
2053 \else
2054 \TD@end@tclpar
2055 \fi
2056 \TD@start@n@line
2057 }
2058 % \end{macrocode}
2059 % \end{macro}
2060 %
2061 % \begin{macro}{\TD@active@CRv}
2062 % This is what |\tclverb| defines the |^^M| active character as
2063 % being. Cf.\ the standard \LaTeX\ macro |\verb@eol@error|.
2064 % \begin{macrocode}
2065 \def\TD@active@CRv{%
2066 \verb@egroup
2067 \PackageError{tclldoc}{\protect\tclverb\space ended by end of line}%
2068 \@ehc
2069 }
2070 % \end{macrocode}
2071 % \end{macro}
2072 %
2073 %
2074 % \begin{macro}{\TD@active@backslash}
2075 % \changes{v\,2.10}{2000/10/08}{First checking if next character is
2076 % active, and only expands the macro containing the detailed tests
2077 % if it is. (LH)}
2078 % \begin{macro}{\TD@active@backslash@}
2079 % \begin{macro}{\TD@active@backslash@v}
2080 % |\TD@active@backslash| is used for backslashes in normal mode. Its
2081 % main problem is to determine whether the backslash is escaping
2082 % something (which would normally be treated specially by the
2083 % environment) or not. The primary test for this is whether the
2084 % argument grabbed is an active character, and if it is then
2085 % processing continues (in |\TD@active@backslash@|) to determine what
2086 % should be done.
2087 % \begin{macrocode}
2088 \def\TD@active@backslash#1{%
2089 \ifcat \noexpand#1\noexpand~%
2090 \expandafter\TD@active@backslash@
2091 \else
2092 \@backslashchar
2093 \fi
2094 #1%
2095 }
2096 % \end{macrocode}
2097 %
2098 % In order to have guard lines processed correctly, the first test
2099 % below really must be for |\TD@active@CR| rather than for an
2100 % active |^^M|.
2101 % \changes{v\,2.11}{2000/11/06}{Escaped spaces are no longer breakable.
2102 % (LH)}
2103 % \begin{macrocode}
2104 \def\TD@active@backslash@#1{%
2105 \ifcase
2106 \ifx #1\TD@active@CR 0%
2107 \else\ifx #1\TD@active@backslash 1%
2108 \else\ifx #1\TD@active@braceleft 2%
2109 \else\ifx #1\TD@active@braceright 2%
2110 \else\ifx #1\TD@active@bracketleft 2%
2111 \else\ifx #1\TD@active@bracketright 2%
2112 \else\ifx #1\TD@active@space 3%
2113 \else 4\fi\fi\fi\fi\fi\fi\fi
2114 \space
2115 \expandafter\TD@active@backslash@i
2116 \or
2117 \@backslashchar\@backslashchar
2118 \or
2119 \@backslashchar \string#1%
2120 \or
2121 \@backslashchar \TD@typeset@space
2122 \else
2123 \@backslashchar
2124 \expandafter#1%
2125 \fi
2126 }
2127 % \end{macrocode}
2128 % Escaped newlines that are followed by command mode lines are not
2129 % converted to discretionary spaces.
2130 % \begin{macrocode}
2131 \def\TD@active@backslash@i#1{%
2132 \ifx #1\TD@percent@token
2133 \copy\TD@backslash@box
2134 \expandafter\TD@active@CR
2135 \else
2136 \TD@breakable@space
2137 \global\advance \c@codelineno \@ne
2138 \expandafter\TD@gobble@whitespace
2139 \fi
2140 #1%
2141 }
2142 % \end{macrocode}
2143 % The |\tclverb| command uses |\TD@active|\-|@backslash@v| instead of
2144 % |\TD|\-|@active|\-|@backslash@i|, since it is intended for use on
2145 % lines that may begin with |%|.
2146 % \begin{macrocode}
2147 \def\TD@active@backslash@v#1{%
2148 \TD@discretionary@space
2149 \ifx #1\TD@percent@token
2150 \expandafter\@firstoftwo
2151 \fi
2152 \TD@gobble@whitespace #1%
2153 }
2154 % \end{macrocode}
2155 % \end{macro}\end{macro}\end{macro}
2156 %
2157 %
2158 % \begin{macro}{\TD@active@bracketleft}
2159 % \begin{macro}{\TD@active@bracketright}
2160 % These macros mainly typeset the corresponding characters, but they
2161 % also increase or decrease the |\TD@nesting@level| count by one.
2162 % \begin{macrocode}
2163 \def\TD@active@bracketleft{[\advance\TD@nesting@level\@ne}
2164 \def\TD@active@bracketright{]\advance\TD@nesting@level\m@ne}
2165 % \end{macrocode}
2166 % \end{macro}\end{macro}
2167 %
2168 % \begin{macro}{\TD@active@braceleft}
2169 % \begin{macro}{\TD@active@braceright}
2170 % \begin{macro}{\TD@nesting@stack}
2171 % \changes{v\,2.14}{2001/01/19}{Nesting stack added to cope with code
2172 % (brace-delimited strings) where brackets aren't properly balanced.
2173 % (LH)}
2174 % The |\TD@active@braceleft| and |\TD@active@braceright| work very
2175 % much like their \texttt{bracket} counterparts, but they also push
2176 % and pop the current nesting level on and off the |\TD@nesting@stack|
2177 % macro. The reason for doing this is that brackets aren't always
2178 % properly balanced in \Tcl\ code, which may result in a
2179 % |\TD@nesting@level| value which does not mirror how the code really
2180 % will be interpreted. Braces must however be properly balanced, and
2181 % therefore it is always right to restore the value of
2182 % |\TD@nesting@level| that was in force before a brace group began
2183 % when it is ended.
2184 %
2185 % The |\TD@nesting@stack| macro is a \meta{nesting stack}, which is
2186 % one of the following two things
2187 % \begin{quote}
2188 % |\TD@nesting@level|
2189 % \meta{number}|\def\TD@nesting@stack{|\meta{nesting stack}|}|
2190 % \end{quote}
2191 % This means a value is popped off the stack by doing
2192 % \begin{quote}
2193 % |\TD@nesting@level=\TD@nesting@stack|
2194 % \end{quote}
2195 % and |\TD@nesting@level| is unchanged if the stack is empty.
2196 % \DoNotIndex{\[,\]}
2197 % \DoNotIndexHarmless{\PrintChar{`\{}}
2198 % \DoNotIndexHarmless{\PrintChar{`\}}}
2199 % \begin{macrocode}
2200 \begingroup
2201 \catcode`\{=12 \catcode`\}=12
2202 \catcode`\[=1 \catcode`\]=2
2203 \gdef\TD@active@braceleft[{%
2204 \expandafter\def \expandafter\TD@nesting@stack \expandafter[%
2205 \the\expandafter\TD@nesting@level
2206 \expandafter\def \expandafter\TD@nesting@stack
2207 \expandafter[\TD@nesting@stack]%
2208 ]%
2209 \advance\TD@nesting@level\@ne
2210 ]
2211 \gdef\TD@active@braceright[}%
2212 \advance\TD@nesting@level\m@ne
2213 \TD@nesting@level=\TD@nesting@stack
2214 ]
2215 \endgroup
2216 \def\TD@nesting@stack{\TD@nesting@level}
2217 % \end{macrocode}
2218 % \end{macro}\end{macro}\end{macro}
2219 %
2220 %
2221 %
2222 % \subsection{Paragraph formatting}
2223 %
2224 % This subsection contains definitions of control sequences that are
2225 % mainly related to the formatting of paragraphs.
2226 %
2227 % The new implementation of the \texttt{tcl} and \texttt{tcl*}
2228 % environments is based on inserting the ``discretionary'' backslashes
2229 % at the linebreaks \emph{after} the paragraph has been broken.
2230 % Doing this involves reboxing every line in the paragraph, and in this
2231 % process the line adjustments are changed as well.
2232 %
2233 % \begin{macro}{\TD@backslash@box}
2234 % The |\TD@backslash@box| box register is set to a backslash in the
2235 % special |\TD@nontcl@font| at the beginning of each \texttt{tcl} and
2236 % \texttt{tcl*} environment. These backslashes are used to denote
2237 % ``backslash escaping newline''. The primary reason for keeping this
2238 % glyph in a box is not that this might be slightly faster to
2239 % typeset, but to have the \emph{width} of it easily accessible.
2240 % \begin{macrocode}
2241 \newbox\TD@backslash@box
2242 % \end{macrocode}
2243 % \end{macro}
2244 %
2245 % \begin{macro}{\TD@nesting@level}
2246 % \begin{macro}{\TD@nesting@penalty}
2247 % |\TD@nesting@level| is a count register which keeps track of how
2248 % many brace\slash bracket groups surrounds the current position in
2249 % the line. It is cleared to zero at the beginning of each paragraph.
2250 % \begin{macrocode}
2251 \newcount\TD@nesting@level
2252 % \end{macrocode}
2253 % |\TD@nesting@penalty| makes a |\penalty| whose value should depend
2254 % on the nesting level (the deeper the nest, the larger the penalty).
2255 % It may also adjust the value of |\linepenalty| to counter that
2256 % the nesting level has become negative. This is typically needed for
2257 % lines which say things like ``|} else {|''. The default definition is
2258 % to make the nesting penalty $100$ times the nesting level and to
2259 % make the |\linepenalty| equal to
2260 % \(10 - \min\{0,\mbox{least penalty}\}\).
2261 % \begin{macrocode}
2262 \def\TD@nesting@penalty{%
2263 \penalty \the\TD@nesting@level 00\relax
2264 \ifnum \lastpenalty<-\linepenalty
2265 \linepenalty=10%
2266 \advance \linepenalty -\lastpenalty
2267 \fi
2268 }
2269 % \end{macrocode}
2270 % I doubt that this is necessarily the best algorithm for computing
2271 % these penalties, so if you are really thorough about your
2272 % typography you may well want to experiment with other definitions of
2273 % |\TD@nesting@penalty|. In case you should then find something which
2274 % works even better then I'm interested to learn about it.
2275 % \end{macro}\end{macro}
2276 %
2277 % \begin{macro}{\TD@reformat@lines}
2278 % The |\TD@reformat@lines| macro calls itself recursively to reformat
2279 % all lines on the current vertical list. The first line will remain
2280 % flush left, but all other lines will be reset flush right. The
2281 % visible material on the last line will be left as it is, but the
2282 % last box in all other lines will be replaced by a non-macro font
2283 % backslash.
2284 %
2285 % It is very important that the current vertical list is not the main
2286 % vertical list.
2287 % It is assumed that the current vertical list consists of a sequence
2288 % of \meta{box}, \meta{penalty}, \meta{glue}, with an extra glue item
2289 % at the top of the list. It is OK if some penalty or glue item is
2290 % missing. In case the list contains other material as well the line
2291 % reformatting may be stopped prematurely, but there is a trick that
2292 % allows one to put arbitrary material between the lines of the
2293 % reformatted paragraph: rather than doing e.g.
2294 % \begin{quote}
2295 % |\mark|\marg{text}
2296 % \end{quote}
2297 % in the paragraph, do
2298 % \begin{quote}
2299 % |\vadjust{\vbox{\mark{|\meta{text}|}}}|
2300 % \end{quote}
2301 % The |\vbox| will be recognised by the paragraph reformatting
2302 % mechanism as a container for vertical mode material that appears
2303 % between the lines of the paragraph, so it will simply be unboxed.
2304 % \changes{v\,2.12}{2000/11/11}{\cs{vbox} containers for vertical
2305 % material are allowed between the lines of a reformatted
2306 % paragraph. (LH)}
2307 %
2308 % Each line's horizontal list ends with
2309 % \begin{itemize}
2310 % \item a box (which contains the space that is to be replaced by a
2311 % backslash),
2312 % \item a penalty (at which the paragraph was broken), and
2313 % \item a glue item (the |\rightskip|).
2314 % \end{itemize}
2315 %
2316 % A tricky feature in the implementation is that the
2317 % |\bgroup|--|\egroup| nesting will be off by one. The |\bgroup| at
2318 % the beginning of a |\TD@reformat@line| will be matched by the
2319 % |\egroup| at the end of the |\TD@reformat@line| that the first one
2320 % calls!
2321 % \begin{macrocode}
2322 \def\TD@reformat@lines{%
2323 \bgroup
2324 \unskip
2325 \count@=\lastpenalty \unpenalty
2326 \setbox\z@=\lastbox
2327 \ifvoid\z@
2328 % \end{macrocode}
2329 % The recursion had already descended down to the last line of the
2330 % paragraph, and it is now time to reformat it.
2331 % \begin{macrocode}
2332 \egroup
2333 \prevdepth=\TD@prevdepth
2334 \hbox{%
2335 \unhbox\z@
2336 \unskip \unpenalty
2337 \setbox\z@=\lastbox
2338 \copy\TD@backslash@box
2339 }%
2340 \else
2341 % \end{macrocode}
2342 % Else there may be another line, and the |\TD@reformat@lines| recursion
2343 % must continue to descend. Upon return the box currently in box
2344 % register zero must be reformatted as a non-first line (flush
2345 % right) and it cannot be the last line in the paragraph, so it is
2346 % always correct to replace the last box by a backslash.
2347 % \begin{macrocode}
2348 \TD@reformat@lines
2349 \ifvbox\z@ \unvbox\z@ \else
2350 \hb@xt@\dimen@{%
2351 \hfill
2352 \unhbox\z@
2353 \unskip \unpenalty
2354 \setbox\z@=\lastbox
2355 \copy\TD@backslash@box
2356 }%
2357 \fi
2358 \fi
2359 \ifnum \count@=\z@ \else \penalty\count@ \fi
2360 \egroup
2361 }
2362 % \end{macrocode}
2363 % \end{macro}
2364 %
2365 % \begin{macro}{\TD@reformat@par}
2366 % The |\TD@reformat@par| macro reformats all lines (they're supposed
2367 % to constitute a paragraph, but that isn't so important) in the
2368 % current vertical list. The restrictions of |\TD@reformat@lines| on
2369 % what may appear in the list apply and there must be at least two
2370 % lines in the list. |\dimen@| is used to hold the desired width of
2371 % reformatted paragraphs.
2372 %
2373 % More precisely |\TD@reformat@par| takes care of the last line of
2374 % the paragraph and the possible |\vbox| containers for vertical
2375 % material that may follow it. Everything in the paragraph that comes
2376 % before the last line is handled by |\TD@reformat@lines|.
2377 % \changes{v\,2.12}{2000/11/11}{\cs{vbox} containers for vertical
2378 % material are allowed after the last line of a reformatted
2379 % paragraph. (LH)}
2380 % \begin{macrocode}
2381 \def\TD@reformat@par{%
2382 \unskip
2383 \count@=\lastpenalty \unpenalty
2384 \setbox\z@=\lastbox
2385 \ifvbox\z@
2386 \bgroup
2387 \TD@reformat@par
2388 \egroup
2389 \unvbox\z@
2390 \else\ifnum \prevgraf>\@ne
2391 \dimen@=\@totalleftmargin
2392 \advance \dimen@ \linewidth
2393 \bgroup
2394 \unskip
2395 \count@=\lastpenalty \unpenalty
2396 \setbox\z@=\lastbox
2397 \TD@reformat@lines
2398 \hb@xt@\dimen@{\hfill \unhbox\z@ \unskip}%
2399 \else
2400 \unskip
2401 \prevdepth=\TD@prevdepth
2402 \box\z@
2403 \fi\fi
2404 \ifnum \count@=\z@ \else \penalty\count@ \fi
2405 }
2406 % \end{macrocode}
2407 % \end{macro}
2408 %
2409 % \begin{macro}{\TD@prevdepth}
2410 % |\TD@prevdepth| is a macro which is used for storing the value of
2411 % |\prevdepth| at times where \TeX\ modifies the primitive in unwanted
2412 % ways. It should always be set globally.
2413 % \end{macro}
2414 %
2415 %
2416 % \begin{macro}{\TD@begin@tclpar}
2417 % The |\TD@begin@tclpar| macro is called when a paragraph in a
2418 % \texttt{tcl} or \texttt{tcl*} environment is about to start. It
2419 % takes care of setting up things so that the paragraph can later be
2420 % reformatted using |\TD@reformat@par|, but it also has to make sure
2421 % that this reformatting doesn't affect the way the paragraph blends
2422 % in with vertical material before and after it.
2423 %
2424 % Reformatting requires that the paragraph is first built in
2425 % restricted vertical mode, i.e., it has to be built in an explicit
2426 % |\vbox|. A problem with this is however that it changes the value of
2427 % |\prevdepth|, which must therefore be explicitly restored.
2428 % \begin{macrocode}
2429 \def\TD@begin@tclpar{%
2430 \xdef\TD@prevdepth{\the\prevdepth}%
2431 \setbox\z@=\vbox\bgroup
2432 \color@begingroup
2433 \prevdepth=\TD@prevdepth
2434 \indent
2435 }
2436 % \end{macrocode}
2437 % \end{macro}
2438 %
2439 % \begin{macro}{\TD@end@tclpar}
2440 % The |\TD@end@tclpar| macro ends a paragraph begun by
2441 % |\TD@begin@tclpar|, reformats it (|\TD@reformat@par|), and
2442 % contributes it to the surrounding vertical list. The |\begingroup|
2443 % and |\endgroup| are there to sort things out in case the recursion
2444 % in |\TD@reformat@par| fails to match as intended. The second
2445 % |\@@par| sees to that the page builder is exercised (without it,
2446 % several pages may go onto the main vertical list without anything
2447 % being shipped out).
2448 % \begin{macrocode}
2449 \def\TD@end@tclpar{%
2450 \@@par
2451 \begingroup
2452 \skip@=\lastskip
2453 \TD@reformat@par
2454 \vskip\skip@
2455 \endgroup
2456 \xdef\TD@prevdepth{\the\prevdepth}%
2457 \color@endgroup
2458 \egroup
2459 \unvbox\z@
2460 \prevdepth=\TD@prevdepth
2461 \@@par
2462 }
2463 % \end{macrocode}
2464 % \end{macro}
2465 %
2466 %
2467 % \begin{macro}{\TD@line@indent}
2468 % |\TD@line@indent| is a |\count| register holding the indentation of
2469 % the current line, in number of spaces. |\TD@line@indent| should
2470 % always be assigned globally.
2471 % \begin{macrocode}
2472 \newcount\TD@line@indent
2473 % \end{macrocode}
2474 % \end{macro}
2475 %
2476 % \begin{macro}{\TD@par@setup}
2477 % This macro sets up various paragraph formatting parameters for the
2478 % normal mode. It mainly consists of code from |\macro@code| of
2479 % \package{doc}.
2480 % \begin{macrocode}
2481 \def\TD@par@setup{%
2482 % \end{macrocode}
2483 %
2484 % In theory a \texttt{tcl} environment should consist of a
2485 % \texttt{trivlist} environment, but the empty space before and after
2486 % the environment should not be too large.
2487 % \begin{macrocode}
2488 \topsep\MacrocodeTopsep
2489 % \end{macrocode}
2490 %
2491 % The next parameter we set is |\@beginparpenalty|, in order
2492 % to prevent a page break before such an environment.
2493 % \begin{macrocode}
2494 \@beginparpenalty\predisplaypenalty
2495 % \end{macrocode}
2496 %
2497 % We then start a |\trivlist|, set |\parskip| back to
2498 % zero and start an empty |\item|.
2499 % \changes{ \package{doc} v\,1.9b}{1993/12/03}{Forcing any label
2500 % from macro env.}
2501 % \begin{macrocode}
2502 \if@inlabel\leavevmode\fi
2503 \trivlist
2504 \parskip\z@skip
2505 \item[]%
2506 % \end{macrocode}
2507 % However, the \texttt{trivlist} environment is only started to make
2508 % standard \LaTeX\ happy (and to have the various list-related
2509 % measurements properly calculated). Everything below will instead
2510 % by done with \TeX\ primitives.
2511 % \changes{ \package{pasdoc} v\,1.31}{1999/09/02}{\cs{parshape}
2512 % assignment added. (LH)}
2513 % \changes{v\,2.10}{2000/10/08}{\cs{parshape} assignment removed (now
2514 % done in \cs{TD@begin@tclpar}). (LH)}
2515 %
2516 % It is important that the change to a special font does not take
2517 % place before the above |\item|, otherwise a change to
2518 % |\baselineskip| will affect the paragraph above.
2519 % \begin{macrocode}
2520 \macro@font
2521 \frenchspacing
2522 % \end{macrocode}
2523 %
2524 % \leavevmode
2525 % \changes{v\,2.12}{2000/11/11}{Assignment to \cs{TD@backslash@box}
2526 % moved from \cs{TD@typography} to here, so that the size will be
2527 % right. (LH)}^^A
2528 % One escape symbol that is particularly common is a single
2529 % backslash, and this is stored in the |\TD@backslash@box| box. As
2530 % some encodings (e.g.\ \texttt{OT1}) does not contain a backslash,
2531 % these escape backslashes are made with |\textbackslash|, rather
2532 % than an explicit character.
2533 % \begin{macrocode}
2534 \sbox\TD@backslash@box{\TD@nontcl@font\textbackslash}%
2535 % \end{macrocode}
2536 %
2537 % The |\rightskip| is given a generous stretchability of |\linewidth|
2538 % so that it doesn't matter too much if the lengths of lines in the
2539 % paragraph varies. Decreasing this value would make the nesting in
2540 % the code less important.
2541 % \begin{macrocode}
2542 \parindent=\@totalleftmargin
2543 \advance \parindent \MacroIndent
2544 \leftskip=\z@skip
2545 \rightskip=\z@ \@plus \linewidth\relax
2546 % \end{macrocode}
2547 % The next two lines are from the definition of the
2548 % \texttt{macrocode} environment, and I (LH) have no idea what they are
2549 % good for, but I suppose I can keep them, at least for now.
2550 % \begin{macrocode}
2551 \global\@newlistfalse
2552 \global\@minipagefalse
2553 % \end{macrocode}
2554 % \changes{ \package{pasdoc} v\,1.31}{1999/09/02}{Made list
2555 % environments indent line numbers. (LH)}
2556 % \changes{v\,2.33}{2001/12/12}{Made list environments not indent
2557 % line numbers per default, but providing a way for the user to
2558 % change this. (LH)}
2559 % Line numbers are inserted using |\everypar|.
2560 % \begin{macrocode}
2561 \ifcodeline@index
2562 \everypar={\llap{%
2563 \PrintCodelineNo\ \hskip\codelineindentfactor\@totalleftmargin
2564 }}%
2565 \else
2566 \everypar={}%
2567 \fi
2568 % \end{macrocode}
2569 %
2570 % These commands replace \package{doc}'s final module processing
2571 % macros with macros that work in the \texttt{tcl} environment.
2572 % \begin{macrocode}
2573 \let\pm@module=\TD@pm@module
2574 \let\star@module=\TD@star@module
2575 \let\slash@module=\TD@slash@module
2576 }
2577 % \end{macrocode}
2578 % \end{macro}
2579 %
2580 % \begin{macro}{\codelineindentfactor}
2581 % The |\codelineindentfactor| macro specifies by which fraction of
2582 % |\@totalleftmargin| that the list environment indentation of
2583 % codeline numbers will be countered. |0| means that the numbers will
2584 % be indented, |1| or empty (the default) that they will not be
2585 % indented. |0.5| would mean that the effective indentation is half
2586 % that of other material.
2587 % \begin{macrocode}
2588 \let\codelineindentfactor\@empty
2589 % \end{macrocode}
2590 % \end{macro}
2591 %
2592 % \begin{macro}{\TD@setup@parshape}
2593 % This macro sets the shape of the current paragraph, primarily based
2594 % on the value in |\TD@line@indent|, and makes the final indentation
2595 % of the first line. By the time it gets called, there usually already
2596 % is some material (|\indent|, codeline number, and possibly a
2597 % \package{docstrip} guard) in the paragraph horizontal list.
2598 %
2599 % The basic area in which the paragraph material is to be put has a
2600 % left margin at |\@totalleftmargin|${}+{}$|\MacroIndent| and a right
2601 % margin at |\@totalleftmargin|${}+{}$|\linewidth| (in both cases the
2602 % position is that much to the right of the left edge of the galley).
2603 % The printed codeline number (if there is one) will be put to the
2604 % left of the left margin, but all other material is indented at least
2605 % the width of another |\TD@line@indent| spaces. In the first line
2606 % that will be done through an explicit kern, but in subsequent lines
2607 % it will instead be done through a |\parshape| assignment. On these
2608 % subsequent lines, there will be an additional indentation of\/
2609 % $1\,\mathrm{em}$ to mark the continuation.
2610 %
2611 % When the paragraph is broken, the right margin will be moved to the
2612 % right by the width of a space minus the width of the
2613 % |\TD@backslash@box|. The reason for this is that the paragraph will
2614 % be broken with spaces (from |\TD@breakable@space|) at the end of
2615 % lines, but that these spaces will later be replaced by the
2616 % backslash in |\TD@backslash@box|. As that doesn't happen in the
2617 % very last line of the paragraph however, something special must be
2618 % done there. The option chosen is to give the |\parfillskip| a
2619 % nonzero natural width.
2620 %
2621 % The length |\@totalleftmargin|${}+{}$|\MacroIndent| is put in
2622 % |\parindent| at the beginning of the environment.
2623 % \begin{macrocode}
2624 \def\TD@setup@parshape{%
2625 \parfillskip=\fontdimen\tw@\font \@plus 1fil%
2626 \advance \parfillskip -\wd\TD@backslash@box
2627 \dimen@=\MacroIndent
2628 \advance \dimen@ \TD@line@indent\fontdimen\tw@\font
2629 \advance \dimen@ 1em%
2630 \dimen@ii=\linewidth
2631 \advance \dimen@ii -\dimen@
2632 \dimen4=\linewidth
2633 \advance \dimen@ \@totalleftmargin
2634 \advance \dimen4 \@totalleftmargin
2635 \advance \dimen@ii -\parfillskip
2636 \advance \dimen4 -\parfillskip
2637 \parshape \tw@ \z@ \dimen4 \dimen@ \dimen@ii
2638 % \end{macrocode}
2639 % Then one just needs one more kern to indent the first line
2640 % properly.
2641 % \begin{macrocode}
2642 \kern \TD@line@indent\fontdimen\tw@\font
2643 }
2644 % \end{macrocode}
2645 % \end{macro}
2646 %
2647 % \begin{macro}{\TD@trace@pardimen}
2648 % This macro is for tracing dimens that are of interest for paragraph
2649 % breaking. Its call syntax is
2650 % \begin{quote}
2651 % |\TD@trace@pardimen|\marg{text}\marg{dimen}
2652 % \end{quote}
2653 % where \meta{text} will be written to the log file to identify the
2654 % dimension, and \meta{dimen} is the dimen register in question (it
2655 % can be anything that can appear after |\the|).
2656 %
2657 % To reduce the amount of text written, this macro only does anything
2658 % if the \TeX\ parameter |\tracingparagraphs| is positive.
2659 % \begin{macrocode}
2660 %<*partrace>
2661 \def\TD@trace@pardimen#1#2{%
2662 \ifnum \tracingparagraphs>\z@
2663 \immediate\write\m@ne{#1 \the#2}%
2664 \fi
2665 }
2666 %</partrace>
2667 % \end{macrocode}
2668 % \changes{ \package{pasdoc} v\,1.21}{1999/08/15}{Added macro and
2669 % some calls of it. All of those are however surrounded by
2670 % \texttt{partrace} guards. (LH)}
2671 % \end{macro}
2672 %
2673 %
2674 %
2675 % \subsection{User interface}
2676 %
2677 % This subsection defines the actual environment and the
2678 % commands and parameters intended to be user-definable.
2679 %
2680 %
2681 % \begin{macro}{\settabsize}
2682 % \changes{v\,2.12}{2000/11/09}{New command for setting the tab size.
2683 % (LH)}
2684 % \begin{macro}{\TD@tab@size}
2685 % \changes{v\,2.12}{2000/11/09}{New name for \cs{c@tabSize}; no longer a
2686 % count register. (LH)}
2687 % The |\TD@tab@size| control sequence stores (as a |\chardef| token)
2688 % the number of spaces that are equivalent to one tab; the default
2689 % value is 8. To set this number, one uses the command |\settabsize|,
2690 % which has the syntax
2691 % \begin{quote}
2692 % |\settabsize|\marg{new size}
2693 % \end{quote}
2694 % The effect of |\settabsize| is local.
2695 % \begin{macrocode}
2696 \newcommand*\settabsize[1]{\chardef\TD@tab@size=#1\relax}
2697 \settabsize{8}
2698 % \end{macrocode}
2699 % \end{macro}\end{macro}
2700 %
2701 %
2702 % \begin{environment}{tcl}
2703 % \begin{environment}{tcl*}
2704 % This is some kind of a definition. There are aspects of the
2705 % interaction with \texttt{trivlist} that I (LH) don't understand,
2706 % but it appears to work.
2707 % \begin{macrocode}
2708 \newenvironment{tcl}{%
2709 \TD@general
2710 \TD@typography
2711 \TD@par@setup
2712 \TD@command
2713 }{%
2714 \global\@inlabelfalse
2715 \endtrivlist
2716 }
2717 % \end{macrocode}
2718 % \begin{macrocode}
2719 \newenvironment{tcl*}{%
2720 \TD@visible@whitespace
2721 \TD@general
2722 \TD@typography
2723 \TD@par@setup
2724 \TD@command
2725 }{%
2726 \global\@inlabelfalse
2727 \endtrivlist
2728 }
2729 % \end{macrocode}
2730 % \end{environment}\end{environment}
2731 %
2732 % \begin{macro}{\tclverb}
2733 % \begin{macro}{\TD@verb}
2734 % The |\tclverb| macro is for typesetting short passages of \Tcl\ code
2735 % which one does not want to have a special paragraph for. It is
2736 % similar to the standard \LaTeX\ command |\verb|, but it has a couple
2737 % of extra features. One is that spaces that are not followed by more
2738 % whitespace are discretionary breakpoints, just as in the \texttt{tcl}
2739 % environment. Another is that a newline can be escaped by putting a
2740 % backslash at the end of an input line. Such an escaped newline will
2741 % count as a space, and whitespace at the beginning of the line
2742 % following it will be ignored. A percent character immediately
2743 % following an escaped newline will also be ignored.
2744 %
2745 % |\tclverb| has a |*| form |\tclverb*|, which is analogous to the
2746 % standard \LaTeX\ |\verb*|, i.e., spaces are typeset using ``visible
2747 % space'' symbols.
2748 % \begin{macrocode}
2749 \newcommand\tclverb{%
2750 \relax\ifmmode\hbox\else\leavevmode\null\fi
2751 \bgroup
2752 \@ifstar{\TD@visible@whitespace\TD@verb}\TD@verb
2753 }
2754 % \end{macrocode}
2755 % \DoNotIndex{\ ,\^,\\}
2756 % \begin{macrocode}
2757 \def\TD@verb{%
2758 \let\TD@active@backslash@i=\TD@active@backslash@v
2759 \let\TD@active@CR=\TD@active@CRv
2760 \let\TD@breakable@space=\TD@discretionary@space
2761 \TD@general
2762 \catcode`\^^I=\active
2763 \catcode`\ =\active
2764 \catcode`\\=\active
2765 \TD@typography
2766 \verbatim@font
2767 \sbox\TD@backslash@box{\TD@nontcl@font\textbackslash}%
2768 \@sverb
2769 }
2770 % \end{macrocode}
2771 % \end{macro}\end{macro}
2772 %
2773 %
2774 % \begin{macro}{\TclInput}
2775 % The |\TclInput| macro is very much like the standard \LaTeX\
2776 % |\input|, but it is intended to be used in command mode, for
2777 % inputting \Tcl\ files that have not been marked up. |\input| would
2778 % work in this case, but there would be errors at the first and last
2779 % lines of the |\input|ted file.
2780 % \begin{macrocode}
2781 \newcommand\TclInput[1]{%
2782 \IfFileExists{#1}{%
2783 \@addtofilelist{#1}%
2784 \begingroup
2785 \TD@normal
2786 \let\TD@start@n@line=\TD@start@n@line@i
2787 \expandafter\TD@start@n@line
2788 \@@input\@filef@und\TD@percent@token
2789 \endgroup
2790 }{\PackageError{tclldoc}{No file #1}\@eha}%
2791 }
2792 % \end{macrocode}
2793 % \end{macro}
2794 %
2795 % \begin{macro}{\MakeShortTclverb}
2796 % This definition follows \package{doc}'s |\MakeShortVerb| pretty
2797 % close.
2798 % \DoNotIndex{\~}
2799 % \begin{macrocode}
2800 \newcommand\MakeShortTclverb[1]{%
2801 \expandafter\ifx \csname cc\string#1\endcsname\relax
2802 \PackageInfo{tclldoc}{%
2803 Made \expandafter\@gobble\string#1 a short %
2804 reference for \string\tclverb}%
2805 \add@special{#1}%
2806 \expandafter\xdef \csname cc\string#1\endcsname{\the\catcode`#1}%
2807 \begingroup
2808 \lccode`\~=`#1%
2809 \lowercase{%
2810 \global\expandafter\let
2811 \csname ac\string#1\endcsname ~%
2812 \gdef~{\tclverb~}}%
2813 \endgroup
2814 \global\catcode`#1\active
2815 \else
2816 \PackageInfo{tclldoc}{%
2817 \expandafter\@gobble\string#1 already a short verb %
2818 reference}%
2819 \fi
2820 }
2821 % \end{macrocode}
2822 % \end{macro}
2823 %
2824 %
2825 % \section{Miscellaneous markup features}
2826 %
2827 % \subsection{Namespaces}
2828 %
2829 % \changes{v\,2.10}{2000/10/13}{Added namespace support. (LH)}
2830 %
2831 % \begin{macro}{\setnamespace}
2832 % \begin{macro}{\TD@convert@colons}
2833 % Since it is common that many identifiers in the same namespace are
2834 % defined in sequence, one can specify a default namespace to use for
2835 % all commands where no explicit namespace is given. This is done
2836 % using the |\setnamespace| command, whose syntax is
2837 % \begin{quote}
2838 % |\setnamespace|\marg{namespace}
2839 % \end{quote}
2840 % This converts the \meta{namespace} to a harmless character string
2841 % and locally assigns it to the |\TD@namespace| macro, which stores
2842 % the current default namespace. |\TD@convert@colons| replaces all
2843 % |::| substrings in the namespace by |\namespaceseparator|s.
2844 % \changes{v\,2.33}{2001/12/12}{Converting \texttt{::} in namespace
2845 % names. (LH)}
2846 % \begin{macrocode}
2847 \newcommand\setnamespace[1]{%
2848 \MakeHarmless\TD@namespace{#1}%
2849 \protected@edef\TD@namespace{%
2850 \expandafter\TD@convert@colons \TD@namespace ::\relax
2851 }
2852 }
2853 % \end{macrocode}
2854 % \begin{macrocode}
2855 \def\TD@convert@colons#1::#2{%
2856 #1%
2857 \ifx \relax#2\else
2858 \noexpand\namespaceseparator
2859 \TD@convert@colons #2%
2860 \fi
2861 }
2862 % \end{macrocode}
2863 % \end{macro}\end{macro}
2864 %
2865 % \begin{macro}{\TD@namespace}
2866 % At the beginning of a document, the default namespace is the global
2867 % namespace, which is represented by the empty string.
2868 % \begin{macrocode}
2869 \let\TD@namespace\@empty
2870 % \end{macrocode}
2871 % \end{macro}
2872 %
2873 % \begin{macro}{\buildname}
2874 % \changes{v\,2.13}{2000/12/16}{Added \cs{@empty} after test for
2875 % \cs{NoValue}, so that it works for empty arguments. (LH)}
2876 % \begin{macro}{\namespaceseparator}
2877 % \changes{v\,2.12}{2000/11/25}{Command added. (LH)}
2878 % The |\buildname| macro builds a qualified name from a namespace and
2879 % a name tail. It has the syntax
2880 % \begin{quote}
2881 % |\buildname|\marg{namespace}\marg{name}
2882 % \end{quote}
2883 % where \meta{name} is a harmless character sequence and
2884 % \meta{namespace} is a harmless character sequence or the token
2885 % |\NoValue|. If \meta{namespace} is |\NoValue| then the default
2886 % namespace is used. |\buildname| does all processing at expand-time.
2887 %
2888 % If the namespace is the empty string (the global namespace) then
2889 % \meta{name} is returned without a `|::|' prefix; this is for the
2890 % sake of compatibility with pre-v\,8 \Tcl s.
2891 % \begin{macrocode}
2892 \newcommand\buildname[2]{%
2893 \ifx \NoValue#1\@empty
2894 \ifx \@empty\TD@namespace \else
2895 \TD@namespace\namespaceseparator
2896 \fi
2897 \else
2898 \ifx $#1$\else #1\namespaceseparator \fi
2899 \fi
2900 #2%
2901 }
2902 % \end{macrocode}
2903 % The |\namespaceseparator| command typesets a namespace separator. By
2904 % default it is two colons separated by a penalty, but the user may
2905 % redefine it.
2906 % \begin{macrocode}
2907 \DeclareRobustCommand\namespaceseparator{:\penalty\hyphenpenalty:}
2908 % \end{macrocode}
2909 % \end{macro}\end{macro}
2910 %
2911 % \begin{macro}{\namespacephrase}
2912 % The |\namespacephrase| macro stores the phrase that will be used
2913 % for `namespace' in indices and the like. It is meant to be
2914 % redefinable. The contents must be robust.
2915 % \changes{v\,2.25}{2001/08/14}{Macro added. (LH)}
2916 % \begin{macrocode}
2917 \providecommand*\namespacephrase{name\-space}
2918 % \end{macrocode}
2919 % \end{macro}
2920 %
2921 % \begin{instance}{docindex}{index}
2922 % \changes{v\,2.21}{2001/03/26}{Modified as per the v\,1.00 change to
2923 % \package{docindex}. (LH)}
2924 % The \texttt{index} instance of template type \texttt{docindex}
2925 % (defined by the \package{docindex} package) is redefined to allow
2926 % name and namespace levels to be joined.
2927 % \begin{macrocode}
2928 \@ifpackagewith{docidx2e}{usedocindexps}{%
2929 \@namedef{TP@I{}{docindex}{index}}#1#2{%
2930 \begingroup
2931 \@letinstance\DI@indexitem@i{indexitem}{fixed-r1a}%
2932 \@letinstance\DI@indexitem@ii{indexitem}{aloneaccept2}%
2933 \@letinstance\DI@indexitem@iii{indexitem}{fixed3}%
2934 \columnsep=10pt%
2935 \parskip=0pt plus 1pt%
2936 \def\DI@letter@skip{10pt plus 2pt minus 3pt}%
2937 \def\DI@letter@format##1{%
2938 \par
2939 \hb@xt@\hsize{\hfil\textbf{##1}\hfil}%
2940 \nopagebreak
2941 }%
2942 \def\+{-}%
2943 \IfFileExists{\jobname.ind}{%
2944 \ifnum \c@IndexColumns>\@ne
2945 \begin{multicols}{\c@IndexColumns}[#1][\IndexMin]%
2946 \else
2947 \enough@room{\IndexMin}%
2948 #1\par
2949 \addvspace\multicolsep
2950 \fi
2951 \pagestyle{docindex}%
2952 \small
2953 \@nobreakfalse
2954 \DI@ind@setup
2955 \input{\jobname.ind}%
2956 \DI@item@nojoin
2957 \thispagestyle{docindex}
2958 \ifnum \c@IndexColumns>\@ne
2959 \end{multicols}%
2960 \else
2961 \enough@room\postmulticols
2962 \addvspace\multicolsep
2963 \fi
2964 \normalsize #2\par
2965 }{\typeout{No file \jobname.ind.}}%
2966 \endgroup
2967 }
2968 }{%
2969 \@namedef{TP@I{}{docindex}{index}}#1#2{%
2970 \begingroup
2971 \@letinstance\DI@indexitem@i{indexitem}{fixed-r1a}%
2972 \@letinstance\DI@indexitem@ii{indexitem}{aloneaccept2}%
2973 \@letinstance\DI@indexitem@iii{indexitem}{fixed3}%
2974 \columnsep=10pt%
2975 \parskip=0pt plus 1pt%
2976 \def\DI@letter@skip{10pt plus 2pt minus 3pt}%
2977 \def\DI@letter@format##1{%
2978 \par
2979 \hb@xt@\hsize{\hfil\textbf{##1}\hfil}%
2980 \nopagebreak
2981 }%
2982 \def\+{-}%
2983 \IfFileExists{\jobname.ind}{%
2984 \ifnum \c@IndexColumns>\@ne
2985 \begin{multicols}{\c@IndexColumns}[#1][\IndexMin]%
2986 \else
2987 \enough@room{\IndexMin}%
2988 #1\par
2989 \addvspace\multicolsep
2990 \fi
2991 \small
2992 \@nobreakfalse
2993 \DI@ind@setup
2994 \input{\jobname.ind}%
2995 \DI@item@nojoin
2996 \ifnum \c@IndexColumns>\@ne
2997 \end{multicols}%
2998 \else
2999 \enough@room\postmulticols
3000 \addvspace\multicolsep
3001 \fi
3002 \normalsize #2\par
3003 }{\typeout{No file \jobname.ind.}}%
3004 \endgroup
3005 }
3006 }
3007 % \end{macrocode}
3008 % \end{instance}
3009 %
3010 %
3011 %
3012 % \subsection{\texttt{macro}-like environments}
3013 %
3014 % This subsection contains the definitions of a couple of environments
3015 % which, like \package{doc}'s \texttt{macro}, are for marking up the
3016 % document (what is defined and where). These environments are defined
3017 % using the |\New|\-|Macro|\-|Environment| command of the \package{xdoc2}
3018 % package.
3019 % \changes{ \package{pasdoc} v\,1.40}{1999/12/05}{\texttt{macro}-like
3020 % environments redefined. (LH)}
3021 % \changes{v\,2.00}{2000/07/17}{\texttt{macro}-like environments are
3022 % defined using the \cs{NewMacroEnvironment} command. The
3023 % \cs{TD@identifier}, \cs{SpecialMainTclIndex}, and
3024 % \cs{PrintTclName} macros were removed. (LH)}
3025 % \changes{v\,2.12}{2000/11/26}{Using starred form of
3026 % \cs{NewMacroEnvironment} for the \texttt{variable}, \texttt{proc},
3027 % \texttt{arrayvar}, and \texttt{arrayentry} environments, so that
3028 % the marginal headings can be broken. (LH)}
3029 %
3030 % \begin{macrocode}
3031 \MetaNormalfont
3032 % \end{macrocode}
3033 % \changes{v\,2.32}{2001/11/30}{Added \cs{MetaNormalfont} as a global
3034 % declaration and removed it from the commands that did this locally.
3035 % There were simply so many places where it should have been
3036 % otherwise that the resulting code would have looked rudiculous.
3037 % (LH)}
3038 %
3039 % \begin{environment}{variable}
3040 % The \texttt{variable} environment has the syntax
3041 % \begin{quote}
3042 % |\begin{variable}|\oarg{namespace}\marg{variable}
3043 % \end{quote}
3044 % It makes a marginal heading, index entry, etc.\@ for the
3045 % \meta{variable} variable in the \meta{namespace} namespace
3046 % (if specified, otherwise in the default namespace).
3047 % \begin{macrocode}
3048 \NewMacroEnvironment*{variable}%
3049 {\XD@grab@harmless@oarg\XD@grab@harmless\relax}{2}%
3050 {\XDParToMargin{\MacroFont\buildname{#1}{#2} \normalfont (var.)}}%
3051 {\TD@main@index{#1}{#2}{var.}{}}%
3052 {{\buildname{#1}{#2}}{\texttt{\buildname{#1}{#2}} variable}}
3053 {}%
3054 % \end{macrocode}
3055 % \end{environment}
3056 %
3057 % \begin{environment}{proc}
3058 % The \texttt{proc} environment has the syntax
3059 % \begin{quote}
3060 % |\begin{proc}|\oarg{namespace}\marg{proc}
3061 % \end{quote}
3062 % It makes a marginal heading, index entry, etc.\@ for the \meta{proc}
3063 % procedure in the \meta{namespace} namespace (if specified, otherwise
3064 % in the default namespace).
3065 % \begin{macrocode}
3066 \NewMacroEnvironment*{proc}%
3067 {\XD@grab@harmless@oarg\XD@grab@harmless\relax}{2}%
3068 {\XDParToMargin{\MacroFont\buildname{#1}{#2} \normalfont (proc)}}%
3069 {\TD@main@index{#1}{#2}{proc}{}}%
3070 {{\buildname{#1}{#2}}{\texttt{\buildname{#1}{#2}} proc}}
3071 {}%
3072 % \end{macrocode}
3073 % \end{environment}
3074 %
3075 % \begin{environment}{arrayvar}
3076 % \changes{v\,2.00}{2000/07/17}{Environment added. (LH)}
3077 % \changes{v\,2.12}{2000/11/09}{Made last argument optional. (LH)}
3078 % \changes{v\,2.13}{2000/12/15}{Not using \cs{meta} for the
3079 % \meta{index-des} argument. (LH)}
3080 % \begin{environment}{arrayentry}
3081 % \changes{v\,2.02}{2000/08/21}{Environment added. (LH)}
3082 % The \texttt{arrayvar} and \texttt{arrayentry} environments are for
3083 % array variables; \texttt{arrayvar} is for the array as a whole,
3084 % whereas \texttt{arrayentry} is for individual entries in the array
3085 % that (for some reason) are important enough to warrant special
3086 % attention. The respective syntaxes are
3087 % \begin{quote}
3088 % |\begin{arrayvar}|\oarg{namespace}\marg{array}\oarg{index-des}\\
3089 % |\begin{arrayentry}|\oarg{namespace}\marg{array}\marg{entry}
3090 % \end{quote}
3091 % Here \meta{array} is the name of an array variable, \meta{entry} is
3092 % the name of an entry, and \meta{index-des} is a short piece of text
3093 % (seldom more than one word) which describes what is used as indices
3094 % into that array.
3095 % \changes{v\,2.14}{2001/01/12}{Corrected grabbing of the third
3096 % argument of the \texttt{arrayvar} environment: it should be an
3097 % oarg, not a harmless oarg. (LH)}
3098 % \begin{macrocode}
3099 \NewMacroEnvironment*{arrayvar}{%
3100 \XD@grab@harmless@oarg\XD@grab@harmless\relax\XD@grab@oarg
3101 }{3}%
3102 {\XDParToMargin{\MacroFont \buildname{#1}{#2}%
3103 \ifx \NoValue#3%
3104 \space\normalfont (array)%
3105 \else
3106 \penalty\hyphenpenalty(\mbox{\meta@font@select#3})%
3107 \fi
3108 }}%
3109 {\TD@main@index{#1}{#2}{array}{%
3110 \ifx \NoValue#3\@empty\else
3111 \LevelSorted{#3}{\protect\mbox{\textit{#3}} entries}%
3112 \fi
3113 }}%
3114 {{\buildname{#1}{#2}}{\texttt{\buildname{#1}{#2}} array}}
3115 {}%
3116 % \end{macrocode}
3117 % \begin{macrocode}
3118 \NewMacroEnvironment*{arrayentry}{%
3119 \XD@grab@harmless@oarg\XD@grab@harmless\relax\XD@grab@harmless\relax
3120 }{3}%
3121 {\XDParToMargin{%
3122 \MacroFont \buildname{#1}{#2}%
3123 \penalty\hyphenpenalty(#3)%
3124 }}%
3125 {\TD@main@index{#1}{#2}{array}{\LevelSorted{#3}{\texttt{#3}}}}%
3126 {{\buildname{#1}{#2}(#3)}{\texttt{\buildname{#1}{#2}(#3)}}}
3127 {}%
3128 % \end{macrocode}
3129 % \end{environment}\end{environment}
3130 %
3131 % \begin{macro}{\describestring}
3132 % \changes{v\,2.01}{2000/08/12}{Command added. (LH)}
3133 % \changes{v\,2.12}{2000/11/21}{Optional argument added. (LH)}
3134 % \changes{v\,2.13}{2000/12/16}{Second optional argument added. (LH)}
3135 % \changes{v\,2.20}{2001/03/03}{Putting namespace on the second
3136 % level. (LH)}
3137 % The |\describestring| command has the syntax
3138 % \begin{quote}
3139 % |\describestring|\oarg{type}\oarg{namespace}\marg{string}
3140 % \end{quote}
3141 % It is similar to \package{xdoc}'s own |\describe|\-|cs|\-|family|
3142 % command, but it has a couple of extra features which are connected
3143 % to the optional arguments and it doesn't prepend a backslash to
3144 % the name of the thing being described. When the \meta{type} argument
3145 % is present, it is taken as a ``type declaration'' of the
3146 % \meta{string} being described and `(\meta{type})' will be put as a
3147 % suffix to the \meta{string}. When the \oarg{namespace} argument is
3148 % present it means that the string being described is really the name
3149 % of something (e.g.\ a procedure or variable) which exists in a
3150 % namespace, and the complete name is formed by passing both
3151 % \meta{namespace} and \meta{string} as arguments to |\buildname|.
3152 % Note that an empty \meta{namespace} argument is not quite the
3153 % same thing as no \meta{namespace} argument.
3154 % \begin{macrocode}
3155 \NewDescribeCommand{\describestring}{%
3156 \XD@grab@oarg\XD@grab@harmless@oarg\XD@grab@harmless{}%
3157 }{3}{%
3158 \GenericDescribePrint{%
3159 \MacroFont
3160 \ifx \NoValue#2\@empty
3161 #3%
3162 \else
3163 \buildname{#2}{#3}%
3164 \fi
3165 \ifx \NoValue#1\@empty \else\ \normalfont(#1)\fi
3166 }%
3167 \begingroup
3168 \def\meta##1{(##1)}%
3169 \unrestored@protected@xdef\@gtempa{#3}%
3170 \endgroup
3171 \IndexEntry{%
3172 \ifx \NoValue#2\@empty
3173 \LevelSorted{\@gtempa}{%
3174 \texttt{#3}%
3175 \ifx \NoValue#1\@empty \else\space(#1)\fi
3176 }%
3177 \else
3178 \LevelSorted{\@gtempa}{%
3179 \texttt{#3}\ifx \NoValue#1\@empty \else\space(#1)\fi
3180 }%
3181 \ifx $#2$%
3182 \LevelSorted{ }{global \namespacephrase}%
3183 \else
3184 \LevelSorted{#2}{\texttt{#2} \namespacephrase}%
3185 \fi
3186 \fi
3187 }{usage}{\thepage}%
3188 }
3189 % \end{macrocode}
3190 % \end{macro}
3191 %
3192 % \begin{macro}{\describeopt}
3193 % \changes{v\,2.24}{2001/08/11}{Command added. (LH)}
3194 % \changes{v\,2.31}{2001/11/03}{Star-form added. (LH)}
3195 % The |\describeopt| macro is a |\describe|\dots\ command for options
3196 % of commands. The syntax is
3197 % \begin{quote}
3198 % |\describeopt|*\oarg{namespace}\marg{command}\oarg{type}^^A
3199 % \marg{option}
3200 % \end{quote}
3201 % where \meta{command} is the name of the command and \meta{option} is
3202 % the name of the option. \meta{namespace} is the namespace of the
3203 % \meta{command}, if that is not the global namespace. \meta{type} is
3204 % the type description for the command, if different from `proc'.
3205 % The |*| form of this command does not print a marginal note: it
3206 % only makes an index entry.
3207 % \begin{macrocode}
3208 \NewDescribeCommand{\describeopt}{%
3209 \XD@grab@sarg{*}\XD@grab@harmless@oarg\XD@grab@harmless{}%
3210 \XD@grab@oarg\XD@grab@harmless{}%
3211 }{5}{%
3212 \ifx \BooleanFalse#1%
3213 \GenericDescribePrint{%
3214 \MacroFont #5\ \normalfont option%
3215 }%
3216 \fi
3217 \begingroup
3218 \def\meta##1{(##1)}%
3219 \unrestored@protected@xdef\@gtempa{#3}%
3220 \endgroup
3221 \IndexEntry{%
3222 \LevelSorted{\@gtempa}{%
3223 \texttt{#3} (\ifx \NoValue#4\@empty proc\else #4\fi)%
3224 }%
3225 \ifx \NoValue#2\@empty
3226 \LevelSorted{ }{global \namespacephrase}%
3227 \else
3228 \LevelSorted{#2}{\texttt{#2} \namespacephrase}%
3229 \fi
3230 \LevelSorted{#5}{\texttt{#5} option}%
3231 }{usage}{\thepage}%
3232 }
3233 % \end{macrocode}
3234 % \end{macro}
3235 %
3236 % \begin{macro}{\TD@main@index}
3237 % \changes{v\,2.10}{2000/10/14}{Generalized macro. (LH)}
3238 % \changes{v\,2.12}{2000/11/25}{Sorting by base name first, not by
3239 % namespace first. (LH)}
3240 % \changes{v\,2.20}{2001/03/03}{Putting namespace on the second
3241 % level. (LH)}
3242 % The |\TD@main@index| macro has the syntax
3243 % \begin{quote}
3244 % |\TD@main@index|\marg{namespace}\marg{name}\marg{type}^^A
3245 % \marg{extra}
3246 % \end{quote}
3247 % It makes a \texttt{main} index entry. The top level of this entry
3248 % is like an entry for the \meta{name} object of type \meta{type} in
3249 % the \meta{namespace} namespace. The entry may have one or more
3250 % sublevels\footnote{But no more than one extra level is recommended,
3251 % as \package{makeindex} can handle at most three levels.} specified
3252 % in the \meta{extra}; these are then made using explicit
3253 % |\LevelSame| or |\LevelSorted| commands. \meta{name} and
3254 % \meta{namespace} are as for the |\buildname| macro, whereas
3255 % \meta{type} is a description, e.g. `\texttt{proc}', that gets
3256 % appended to the printed text of the entry's top level.
3257 % \begin{macrocode}
3258 \def\TD@main@index#1#2#3#4{%
3259 \XDMainIndex{%
3260 \LevelSorted{#2}{\texttt{#2} (#3)}%
3261 \ifx \NoValue#1\@empty
3262 \ifx \@empty\TD@namespace
3263 \LevelSorted{ }{global \namespacephrase}%
3264 \else
3265 \LevelSorted{\TD@namespace}%
3266 {\texttt{\TD@namespace} \namespacephrase}%
3267 \fi
3268 \else
3269 \ifx $#1$%
3270 \LevelSorted{ }{global \namespacephrase}%
3271 \else
3272 \LevelSorted{#1}{\texttt{#1} \namespacephrase}%
3273 \fi
3274 \fi
3275 #4%
3276 }%
3277 }
3278 % \end{macrocode}
3279 % \end{macro}
3280 %
3281 % \begin{environment}{Cfunction}
3282 % \changes{v\,2.40}{2003/04/05}{Environment added. (LH)}
3283 % \begin{environment}{Cvariable}
3284 % \changes{v\,2.40}{2003/04/05}{Environment added. (LH)}
3285 % \begin{environment}{Ctype}
3286 % \changes{v\,2.40}{2003/04/05}{Environment added. (LH)}
3287 % The \texttt{Cfunction}, \texttt{Cvariable}, and \texttt{Ctype}
3288 % environments are for making a marginal heading, index entry, etc.\@
3289 % for a C function, variable, or type respectively. They all take as
3290 % their single argument the name of the thing that will be defined.
3291 % \begin{macrocode}
3292 \NewMacroEnvironment*{Cfunction}{\XD@grab@harmless\relax}{1}%
3293 {\XDParToMargin{\small\Cfunctionidentifier{#1} (C~function)}}%
3294 {\XDMainIndex{%
3295 \LevelSorted{#1}{\Cfunctionidentifier{#1} (C~function)}%
3296 }}%
3297 {{#1}{\Cfunctionidentifier{#1} C~function}}
3298 {}%
3299 \NewMacroEnvironment*{Cvariable}{\XD@grab@harmless\relax}{1}%
3300 {\XDParToMargin{\small\Cvariableidentifier{#1} (C~variable)}}%
3301 {\XDMainIndex{%
3302 \LevelSorted{#1}{\Cvariableidentifier{#1} (C~variable)}%
3303 }}%
3304 {{#1}{\Cvariableidentifier{#1} C~variable}}
3305 {}%
3306 \NewMacroEnvironment*{Ctype}{\XD@grab@harmless\relax}{1}%
3307 {\XDParToMargin{\small\Ctypeidentifier{#1} (C~type)}}%
3308 {\XDMainIndex{%
3309 \LevelSorted{#1}{\Ctypeidentifier{#1} (C~type)}%
3310 }}%
3311 {{#1}{\Ctypeidentifier{#1} C~type}}
3312 {}%
3313 % \end{macrocode}
3314 % \end{environment}\end{environment}\end{environment}
3315 %
3316 % \begin{macro}{\Cfunctionidentifier}
3317 % \changes{v\,2.40}{2003/04/05}{Macro added. (LH)}
3318 % \begin{macro}{\Cvariableidentifier}
3319 % \changes{v\,2.40}{2003/04/05}{Macro added. (LH)}
3320 % \begin{macro}{\Ctypeidentifier}
3321 % \changes{v\,2.40}{2003/04/05}{Macro added. (LH)}
3322 % These macros are used by \texttt{Cfunction}, \texttt{Cvariable}, and
3323 % \texttt{Ctype} to format the identifiers of C functions, variables,
3324 % and types respectively; the syntax is e.g.
3325 % \begin{quote}
3326 % |\Cfunctionidentifier|\marg{function name}
3327 % \end{quote}
3328 % They default to typeset them in an italic font---this is what CWEB
3329 % uses---but it is meant to be configurable.
3330 % \begin{macrocode}
3331 \newcommand*{\Cfunctionidentifier}[1]{\textit{#1}}
3332 \newcommand*{\Cvariableidentifier}[1]{\textit{#1}}
3333 \newcommand*{\Ctypeidentifier}[1]{\textit{#1}}
3334 % \end{macrocode}
3335 % \end{macro}\end{macro}\end{macro}
3336 %
3337 %
3338 % \subsection{Regular expressions and friends}
3339 %
3340 % I have noticed that when one is describing the syntax of some \Tcl\
3341 % command\slash procedure, one often ends up writing argument lists with
3342 % lots of optional, repeated, or variant parts. In general one can of
3343 % course specify these using BNF syntax diagrams, but whereas occurrences
3344 % of the three syntactic constructions mentioned above are plenty,
3345 % there are much fewer occurrences of for example nesting. Since
3346 % furthermore even the simplest optional or repeated element
3347 % requires an extra syntactic term to be defined, it becomes interesting
3348 % to search for an alternative way of specifying these constructions.
3349 % One that is close at hand is that of regular expressions, as that is
3350 % anyway a part of the \Tcl\ language.
3351 %
3352 % \begin{macro}{\regstar}
3353 % \begin{macro}{\regplus}
3354 % \begin{macro}{\regopt}
3355 % These commands are used to modify the meaning of another syntactic
3356 % element. |\regstar| puts a star $^*$ on something, meaning it is
3357 % repeated zero or more times. |\regplus| puts a plus $^+$ on
3358 % something, meaning it is repeated one or more times. |\regopt| puts
3359 % a question mark $^?$ on something, meaning it is optional. Normally
3360 % these commands are simply put right after what they should modify,
3361 % but if the ``something'' is a regular expression block, i.e., a
3362 % \texttt{regblock} environment, then these things should be put as
3363 % the \meta{modifier} in
3364 % \begin{quote}
3365 % |\begin{regblock}|\oarg{modifier}\\
3366 % | |\textellipsis\\
3367 % |\end{regblock}|
3368 % \end{quote}
3369 % In particular, they should \emph{not} be put after the
3370 % |\end{regblock}|, as that may impair the placement of the exponent.
3371 % \begin{macrocode}
3372 \newcommand\regstar{\ensuremath{^*}}
3373 \newcommand\regplus{\ensuremath{^+}}
3374 \newcommand\regopt{\ensuremath{^?}}
3375 % \end{macrocode}
3376 % \end{macro}\end{macro}\end{macro}
3377 %
3378 % \begin{macro}{\TD@delim@size}
3379 % \begin{macro}{\TD@delim@size@G}
3380 % These control sequences are used in determining what size the
3381 % delimiters (parentheses) around a regular expression block should
3382 % have. The values specify what should be the least size of a
3383 % delimiter that bracket a piece of text, and are interpreted as
3384 % follows: \(0={}\)normal size, \(1={}\)|\big| size, \(2={}\)|\Big|
3385 % size, \(3={}\)|\bigg| size, and $4$ and above is |\Bigg| size.
3386 %
3387 % |\TD@delim@size@G| is a macro which is always set globally and
3388 % which keeps track of the delimiter size at the innermost level.
3389 % |\TD@delim@size| is a |\count| register that is assigned locally
3390 % and is used for keeping track of delimiter sizes at all other
3391 % levels. Commands like |\word|, which contribute a delimiter to some
3392 % piece of text, should set |\TD@delim@size@G|.
3393 % \begin{macrocode}
3394 \newcount\TD@delim@size
3395 \gdef\TD@delim@size@G{0}
3396 % \end{macrocode}
3397 % \end{macro}\end{macro}
3398 %
3399 % \begin{environment}{regblock}
3400 % The \texttt{regblock} environment embarks upon a rather tricky scheme
3401 % of boxing and unboxing to determine the proper delimiter size. The
3402 % basic idea is that the contents of the environment are first typeset
3403 % in an \texttt{lrbox} environment, and |\TD@delim@size@G| is set to
3404 % its proper value. Then the left delimiter is set at this size, the
3405 % saved box is unboxed, and finally the right delimiter is set. All
3406 % through the process, the value of |\TD@delim@size@G| at the
3407 % beginning of the \texttt{regblock} environment has been saved in
3408 % |\TD@delim@size| and at the end |\TD@delim@size@G| is set to the
3409 % maximum of its old value and one plus its value inside the
3410 % \texttt{regblock} environment. This makes it possible to nest
3411 % \texttt{regblock} environments.
3412 %
3413 % It is not quite that easy, though. A regular expression can consist
3414 % of several branches, which must be separated by vertical bars.
3415 % These bars should be the same size as the delimiters around the
3416 % regular expression, and hence the bars cannot be typeset before
3417 % every branch has been typeset. Therefore the \texttt{regblock}
3418 % environment starts an extra horizontal list (the |\hbox|) for the
3419 % sole purpose of storing the branches that have already been typeset
3420 % (and \emph{only} these). Each branch is put on the list as a box.
3421 % When all branches have been typeset, they are first removed from the
3422 % list (by |\TD@join@branches|), and then they are inserted again, but
3423 % this time they are unboxed and separated by suitable delimiters.
3424 % Finally the |\hbox| is ended and almost immediately unboxed.
3425 %
3426 % \changes{v\,2.40}{2003/04/05}{Renamed the \texttt{regexp}
3427 % environment to \texttt{regblock}. A \texttt{regexp} environment
3428 % is provided for compatibility. (LH)}
3429 % \begin{macrocode}
3430 \newenvironment{regblock}[1][]{%
3431 \leavevmode
3432 \def\TD@modifier{#1}%
3433 \TD@delim@size=\TD@delim@size@G
3434 \let\regalt=\TD@regalt
3435 \setbox\z@=\hbox\bgroup
3436 \TD@delim@size=\z@
3437 \begin{lrbox}{\z@}%
3438 \gdef\TD@delim@size@G{0}%
3439 \ignorespaces
3440 }{%
3441 \end{lrbox}%
3442 \ifnum \TD@delim@size@G>\TD@delim@size
3443 \TD@delim@size=\TD@delim@size@G\relax
3444 \fi
3445 {\TD@join@branches}%
3446 \unhbox\z@
3447 $\TD@size@delimiter)\TD@modifier$%
3448 \advance \TD@delim@size \@ne
3449 \xdef\TD@delim@size@G{\the\TD@delim@size}%
3450 \egroup
3451 \ifnum \TD@delim@size@G<\TD@delim@size
3452 \xdef\TD@delim@size@G{\the\TD@delim@size}%
3453 \fi
3454 \unhbox\z@
3455 }
3456 % \end{macrocode}
3457 % \end{environment}
3458 %
3459 % \begin{environment}{regexp}
3460 % This is an alias to the \texttt{regblock} environment, provided for
3461 % compatibility.
3462 % \begin{macrocode}
3463 \newenvironment{regexp}{\regblock}{\endregblock}
3464 % \end{macrocode}
3465 % \end{environment}
3466 %
3467 % \begin{macro}{\TD@join@branches}
3468 % \changes{v\,2.12}{2000/11/13}{Made penalty for linebreak after
3469 % \cs{regalt} depend on the delimiter size. (LH)}
3470 % The |\TD@join@branches| macro uses |\lastbox| to retrieve all boxes
3471 % in the current horizontal list, and unboxes them. Between the
3472 % unboxed boxes it puts a |\vert| delimiter, and before the first it
3473 % puts a left parenthesis. Both will be the current delimiter size.
3474 % \begin{macrocode}
3475 \def\TD@join@branches{%
3476 \setbox\z@=\lastbox
3477 \ifvoid\z@
3478 $\TD@size@delimiter($%
3479 \else
3480 {\TD@join@branches}%
3481 \unhbox\z@
3482 ~$\TD@size@delimiter\vert$%
3483 \count@=\TD@delim@size
3484 \advance \count@ \@ne
3485 \multiply \count@ -\@lowpenalty
3486 \penalty\count@\ %
3487 \fi
3488 }
3489 % \end{macrocode}
3490 % \end{macro}
3491 %
3492 % \begin{macro}{\regalt}
3493 % \begin{macro}{\TD@regalt}
3494 % The |\regalt| command is used in a \texttt{regblock} environment
3495 % to separate two branches. It ends an \texttt{lrbox} environment,
3496 % puts the box collected in the surrounding horizontal list (which
3497 % was begun by the |\hbox| in |\lrbox|), and begins a new
3498 % \texttt{lrbox} environment. As this would not make sense outside a
3499 % \texttt{regblock} environment however, the |\regalt| command does by
3500 % default only produce an error message. The ``real'' definition is
3501 % kept in |\TD@regalt| and the \texttt{regblock} environment locally
3502 % redefines |\regalt|.
3503 % \begin{macrocode}
3504 \newcommand\regalt{%
3505 \PackageError{tclldoc}{%
3506 Lonely \protect\regalt--perhaps a missing regblock environment%
3507 }\@eha
3508 }
3509 \def\TD@regalt{%
3510 \end{lrbox}%
3511 \box\z@
3512 \ifnum \TD@delim@size@G>\TD@delim@size
3513 \TD@delim@size=\TD@delim@size@G\relax
3514 \fi
3515 \begin{lrbox}{\z@}%
3516 \gdef\TD@delim@size@G{0}%
3517 }
3518 % \end{macrocode}
3519 % \end{macro}\end{macro}
3520 %
3521 % \begin{macro}{\TD@size@delimiter}
3522 % This macro expands to nothing, |\big|, |\Big|, |\bigg|, or |\Bigg|
3523 % depending on the value of |\TD@delim@size|.
3524 % \begin{macrocode}
3525 \def\TD@size@delimiter{%
3526 \ifcase\TD@delim@size
3527 \or \expandafter\big \or \expandafter\Big \or
3528 \expandafter\bigg \else \expandafter\Bigg
3529 \fi
3530 }
3531 % \end{macrocode}
3532 % \end{macro}
3533 %
3534 % \begin{macro}{\word}
3535 % \changes{v\,2.10}{2000/10/13}{Reimplemented like the new \cs{meta}.
3536 % (LH)}
3537 % \changes{v\,2.12}{2000/11/21}{Using braces instead of angle brackets.
3538 % (LH)}
3539 % This command works like |\meta|, but the argument is enclosed in
3540 % braces rather than angle brackets and it communicates with the
3541 % \texttt{regblock} environment (the braces count as a smallest-size
3542 % delimiter). Something marked out using |\word| rather than |\meta|
3543 % is meant to always denote a separate \Tcl\ word.
3544 % \begin{macrocode}
3545 \DeclareRobustCommand\word[1]{%
3546 \leavevmode
3547 \ifmmode \expandafter \nfss@text \fi
3548 {%
3549 $\{$%
3550 \meta@font@select
3551 \edef\meta@hyphen@restore
3552 {\hyphenchar\the\font\the\hyphenchar\font}%
3553 \hyphenchar\font\m@ne
3554 \language\l@nohyphenation
3555 #1\/%
3556 \meta@hyphen@restore
3557 $\}$%
3558 }%
3559 \ifnum \TD@delim@size@G<\@ne \gdef\TD@delim@size@G{1}\fi
3560 }
3561 % \end{macrocode}
3562 % \end{macro}
3563 %
3564 %
3565 % \subsection{Logos}
3566 %
3567 % \begin{macro}{\Tcllogo}
3568 % \changes{v\,2.03}{2000/09/15}{Macro added. (LH)}
3569 % The |\Tcllogo| command makes a \Tcl\ ``logo'', which simply consists
3570 % of the three letters `T', `c', and `l' in the current font. The only
3571 % special thing about it is that there is a kern between the `T' and
3572 % the `c', since most fonts doesn't have that kern. No work has been
3573 % put into tuning the kern, but the size is about right. As a
3574 % comparison the kern between `T' and `o' in \texttt{cmr10} is
3575 % $-0.083334\,\mathrm{em}$.
3576 % \begin{macrocode}
3577 \DeclareRobustCommand\Tcllogo{T\kern-0.1em cl}
3578 %</pkg>
3579 % \end{macrocode}
3580 % \end{macro}
3581 %
3582 % \changes{v\,2.03}{2000/09/15}{\cs{DescribeResource} command removed.
3583 % Just in case anyone is interested in using it, I have included it as
3584 % a code example in the source for the \package{xdoc} package. (LH)}
3585 %
3586 %
3587 % \section{The \package{tclldoc} class}
3588 %
3589 % \subsection{Option declarations and processing}
3590 %
3591 % \begin{option}{a5paper}
3592 % \begin{option}{olddocinclude}
3593 % The \texttt{a5paper} (to the \package{article} document class) and
3594 % the \texttt{olddocinclude} (to the \package{xdoc} package) are not
3595 % supported for the \package{tclldoc} class.
3596 % \begin{macrocode}
3597 %<*class>
3598 \DeclareOption{a5paper}{%
3599 \ClassError{tclldoc}{The a5paper option is not supported}\@eha
3600 }
3601 \DeclareOption{olddocinclude}{%
3602 \ClassError{tclldoc}{The olddocinclude option is not supported}\@eha
3603 }
3604 % \end{macrocode}
3605 % \end{option}\end{option}
3606 %
3607 % \begin{option}{notrawchar}
3608 % The \texttt{notrawchar} option is passed on to the
3609 % \package{tclldoc} package (which will pass it on to the
3610 % \package{xdoc} package).
3611 % \changes{v\,2.40}{2003/04/05}{Added processing of this option; it
3612 % wouldn't take if it was simply given as a global option. (LH)}
3613 % \begin{macrocode}
3614 \DeclareOption{notrawchar}{%
3615 \PassOptionsToPackage{notrawchar}{tclldoc}%
3616 }
3617 % \end{macrocode}
3618 % \end{option}
3619 %
3620 %
3621 % \begin{macrocode}
3622 \DeclareOption*{%
3623 \PassOptionsToClass{\CurrentOption}{article}}
3624 % \end{macrocode}
3625 %
3626 %
3627 %
3628 % Input a local configuration file, if it exists.
3629 % \begin{macrocode}
3630 \InputIfFileExists{tclldoc.cfg}
3631 {\typeout{*************************************^^J%
3632 * Local config file tclldoc.cfg used^^J%
3633 *************************************}}
3634 {}
3635 % \end{macrocode}
3636 %
3637 %
3638 %
3639 % \begin{macrocode}
3640 \ProcessOptions\relax
3641 % \end{macrocode}
3642 %
3643 % \subsection{Loading the base class}
3644 %
3645 % \begin{macrocode}
3646 \LoadClass{article}
3647 % \end{macrocode}
3648 %
3649 %
3650 % \subsection{The layout}
3651 %
3652 % Increase the text width slightly so that with the standard fonts
3653 % 72 columns of code may appear in a |macrocode| environment.
3654 % \changes{ \package{ltxdoc} v\,2.0c}{1994/03/15}{Set \cs{textwidth}.}
3655 % \begin{macrocode}
3656 \setlength{\textwidth}{355pt}
3657 % \end{macrocode}
3658 %
3659 % Increase the marginpar width slightly, for long command names.
3660 % And increase the left margin by a similar amount
3661 % \changes{ \package{ltxdoc} v\,2.0l}
3662 % {1994/05/25}{Increase \cs{marginparwidth}}
3663 % \changes{ \package{ltxdoc} v\,2.0q}{1995/11/28}
3664 % {Increase \cs{marginparwidth} and page margin.}
3665 % \begin{macrocode}
3666 \addtolength\oddsidemargin{20pt}
3667 \addtolength\evensidemargin{20pt}
3668 % \end{macrocode}
3669 %
3670 %
3671 % Change some defaults for list formatting. In particular, continue to
3672 % indent paragraphs in |\list| environments and don't put extra space
3673 % between them.
3674 % \changes{ \package{pasdoc} v\,1.30}{1999/08/31}{Modifying the list
3675 % formatting. (LH)}
3676 %
3677 % \begin{macro}{\TD@list}
3678 % \begin{macro}{\@listi}
3679 % \begin{macro}{\@listI}
3680 % \begin{macro}{\@listii}
3681 % \begin{macro}{\@listiii}
3682 % \begin{macro}{\@listiv}
3683 % \begin{macro}{\@listv}
3684 % \begin{macro}{\@listvi}
3685 % \begin{macrocode}
3686 \def\@tempa#1{%
3687 \expandafter\def \expandafter#1\expandafter{#1\TD@list}%
3688 }
3689 \def\TD@list{%
3690 \advance \itemsep \parsep
3691 \parsep=\z@\@plus\p@\relax
3692 \advance \itemsep -\parsep
3693 \listparindent=1em\relax
3694 }
3695 \@tempa\@listi
3696 \let\@listI\@listi
3697 \@tempa\@listii
3698 \@tempa\@listiii
3699 \@tempa\@listiv
3700 \@tempa\@listv
3701 \@tempa\@listvi
3702 % \end{macrocode}
3703 % \end{macro}\end{macro}\end{macro}\end{macro}\end{macro}\end{macro}
3704 % \end{macro}\end{macro}
3705 %
3706 %
3707 % \subsection{Loading the \package{tclldoc} package}
3708 %
3709 % \begin{macrocode}
3710 \RequirePackage[dolayout]{tclldoc}
3711 % \end{macrocode}
3712 %
3713 % \begingroup
3714 % Make \verb+|+ be a `short verb' character, but not in the document
3715 % preamble, where an active character may interfere with packages that
3716 % are loaded.
3717 % \DoNotIndex{\|}
3718 % \begin{macrocode}
3719 \AtBeginDocument{\MakeShortTclverb{\|}}
3720 % \end{macrocode}
3721 % \endgroup
3722 %
3723 % As \texttt{.dtx} documents tend to have a lot of monospaced material,
3724 % set up some \texttt{cmtt} substitutions to occur silently.
3725 % \changes{ \package{ltxdoc} v\,2.0p}{1995/11/02}{Add font substitutions}
3726 % \begin{macrocode}
3727 \DeclareFontShape{OT1}{cmtt}{bx}{n}{<-> ssub * cmtt/m/n}{}
3728 \DeclareFontFamily{OMS}{cmtt}{\skewchar\font'60}
3729 \DeclareFontShape{OMS}{cmtt}{m}{n}{<-> ssub * cmsy/m/n}{}
3730 \DeclareFontShape{OMS}{cmtt}{bx}{n}{<-> ssub * cmsy/b/n}{}
3731 % \end{macrocode}
3732 % This substitution is in the standard fd file, but not silent.
3733 % \begin{macrocode}
3734 \DeclareFontShape{OT1}{cmss}{m}{it}{<->ssub*cmss/m/sl}{}
3735 % \end{macrocode}
3736 %
3737 %
3738 % \subsection{More layout}
3739 %
3740 % \changes{v\,2.12}{2000/11/26}{Setting \cs{marginparwidth} so that the
3741 % outer edge of the marginpar is $1\,\mathrm{cm}$ from the paper
3742 % edge. (LH)}
3743 % \changes{v\,2.12}{2000/11/27}{Rearranged code so that
3744 % the \cs{marginparwidth} is set after \package{tclldoc} has been
3745 % loaded; otherwise \package{doc} might overwrite it! (LH)}
3746 % \begin{macrocode}
3747 \setlength\marginparwidth{\evensidemargin}
3748 \addtolength\marginparwidth{1in}
3749 \addtolength\marginparwidth{-\marginparsep}
3750 \addtolength\marginparwidth{-1cm}
3751 % \end{macrocode}
3752 %
3753 %
3754 % \begin{macrocode}
3755 \CodelineNumbered
3756 \DisableCrossrefs
3757 % \end{macrocode}
3758 %
3759 % \begin{macrocode}
3760 \setcounter{StandardModuleDepth}{1}
3761 %</class>
3762 % \end{macrocode}
3763 %
3764 %
3765 % \section{The \package{tcldoc} compatibility package and class}
3766 %
3767 % \changes{v\,2.30}{2001/09/02}{Renamed the package and class to
3768 % \package{tclldoc} to prevent confusion with the \Tcl Doc Perl
3769 % script. Added files \texttt{tcldoc.sty} and \texttt{tcldoc.cls}
3770 % for compatibility. Moved code related to the \texttt{macinputenc}
3771 % option to \texttt{tcldoc.cls}; this option is now unsupported.
3772 % (LH)}
3773 %
3774 % \subsection{Pre-options definitions}
3775 %
3776 % \begin{macro}{\if@rtkinenc@}
3777 % Switch. True iff the \package{rtkinenc} package should be loaded.
3778 % It starts out false.
3779 % \begin{macrocode}
3780 %<*compclass>
3781 \newif\if@rtkinenc@
3782 % \end{macrocode}
3783 % \end{macro}
3784 %
3785 %
3786 % \subsection{Option declarations and processing}
3787 %
3788 % \begin{option}{macinputenc}
3789 % The \texttt{macinputenc} option enables some special code for
3790 % supporting the typesetting of \Tcl\ code written for the Macintosh
3791 % input encoding (cf.\ the \texttt{applemac} option to the
3792 % \package{inputenc} package).
3793 % \begin{macrocode}
3794 \DeclareOption{macinputenc}{%
3795 \PassOptionsToPackage{applemac}{rtkinenc}%
3796 \@rtkinenc@true
3797 }
3798 % \end{macrocode}
3799 % \end{option}
3800 %
3801 %
3802 % \begin{macrocode}
3803 \DeclareOption*{%
3804 \PassOptionsToClass{\CurrentOption}{tclldoc}}
3805 % \end{macrocode}
3806 %
3807 %
3808 %
3809 % Input a local configuration file, if it exists.
3810 % \begin{macrocode}
3811 \InputIfFileExists{tcldoc.cfg}
3812 {\typeout{*************************************^^J%
3813 * Local config file tcldoc.cfg used^^J%
3814 *************************************}}
3815 {}
3816 % \end{macrocode}
3817 %
3818 %
3819 %
3820 % \begin{macrocode}
3821 \ProcessOptions\relax
3822 % \end{macrocode}
3823 %
3824 % \subsection{Loading the base package or class}
3825 %
3826 % \begin{macrocode}
3827 \LoadClass{tclldoc}
3828 %</compclass>
3829 %<comppkg>\LoadPackageWithOptions{tclldoc}
3830 % \end{macrocode}
3831 %
3832 %
3833 % \subsection{Input encoding and font representations}
3834 %
3835 % There are some rather tricky issues concerning interpretation of the
3836 % input in \Tcl\ code. If the |\MacroFont| font contains a character that
3837 % correctly represents a character in the input, then that character is
3838 % obviously what one would like to appear in the typeset output. If no
3839 % font in the entire \TeX\ system contains a character that looks like
3840 % the one in the input, then just as obviously must one examine whether
3841 % there exists some other method of specifying that character. In the
3842 % case of \Tcl\ code, a suitable method seems to be to typeset the
3843 % equivalent |\x|\meta{dd} escape sequence instead. It is for the
3844 % purpose of being able to detect these cases that the
3845 % \package{tcldoc} class (if the user so requests) loads the
3846 % \package{rtkinenc} package, rather than the standard \LaTeX\
3847 % \package{inputenc} package.
3848 %
3849 % The problem of determining for each input character which method of
3850 % representation that should be used---single character or escape
3851 % sequence---does not have a unique solution. Therefore the default
3852 % set-up is to not define any special fakes at all, which means the
3853 % escape sequence method will be chosen in the doubtful cases. There are
3854 % also a couple of options for the \package{tcldoc} class that define
3855 % all (or nearly all) possible fakes---the difference between them lie
3856 % in which fonts are assumed to be present in the system. A user who
3857 % does not like any of these predefined options also has the option of
3858 % putting the corresponding |\Declare|\-|Text|\-|Default|\textellipsis
3859 % \ commands directly into the \texttt{tcldoc.cfg} file.
3860 %
3861 % \begin{macro}{\InputModeCode}
3862 % \begin{macro}{\SetUnavailableAction}
3863 % \begin{macro}{\DeclareInputMath}
3864 % \begin{macro}{\RIE@undefined}
3865 % The \package{tclldoc} package calls some commands defined by the
3866 % \package{rtkinenc} package, but since \package{rtkinenc} is not
3867 % required by the \package{tclldoc} package, the \package{tclldoc}
3868 % package must provide its own definitions, even though these can be
3869 % no-ops. Definition of these commands is delayed until
3870 % |\begin|\nolinebreak[1]|{document}| to avoid problems if the user
3871 % loads the \package{rtkinenc} package after the \package{tclldoc}
3872 % package.
3873 % \begin{macrocode}
3874 %<*pkg>
3875 \AtBeginDocument{%
3876 \providecommand*\InputModeCode{}%
3877 \providecommand*\SetUnavailableAction[1]{}%
3878 \providecommand*\DeclareInputMath[2]{}%
3879 \providecommand*\RIE@undefined[1]{\@inpenc@undefined}%
3880 }
3881 %</pkg>
3882 % \end{macrocode}
3883 % \end{macro}\end{macro}\end{macro}\end{macro}
3884 %
3885 % \begin{macrocode}
3886 %<*compclass>
3887 \if@rtkinenc@
3888 \RequirePackage{rtkinenc}
3889 % \end{macrocode}
3890 %
3891 % \begin{macro}{\.}
3892 % \begin{macro}{\H}
3893 % \begin{macro}{\textemdash}
3894 % \begin{macro}{\textendash}
3895 % \begin{macro}{\textexclamdown}
3896 % \begin{macro}{\textquestiondown}
3897 % \begin{macro}{\textquotedblleft}
3898 % The following text commands are defined by \texttt{OT1enc.def}, but
3899 % their definitions will not work for \texttt{OT1}-encoded typewriter
3900 % fonts. Therefore they are redefined, either so that they work
3901 % anyway (|\textexclamdown| and |\textquestiondown|) or so that they
3902 % call |\TextSymbolUnavailable| when \package{rtkinenc} is in code
3903 % mode. This should make things work for the best in most
3904 % reasonable situations.
3905 %
3906 % It could be noted here that the definitions below for |\.| and |\H|
3907 % does not quite behave as if the commands had not been defined at
3908 % all (I'm assuming that \package{rtkinenc} is in code mode here); an
3909 % undefined command would leave its argument to be typeset, but the
3910 % definitions below will swallow it in those cases.
3911 % \begin{macrocode}
3912 \DeclareTextCommand{\.}{OT1}[1]{%
3913 \IfInputModeCode{\TextSymbolUnavailable\.}%
3914 {\add@accent{95}{#1}}%
3915 }
3916 \DeclareTextCommand{\H}{OT1}[1]{%
3917 \IfInputModeCode{\TextSymbolUnavailable\H}%
3918 {\add@accent{125}{#1}}%
3919 }
3920 \DeclareTextCommand{\textemdash}{OT1}{%
3921 \IfInputModeCode{\TextSymbolUnavailable\textemdash}{\char 124 }%
3922 }
3923 \DeclareTextCommand{\textendash}{OT1}{%
3924 \IfInputModeCode{\TextSymbolUnavailable\textendash}{\char 123 }%
3925 }
3926 \DeclareTextCommand{\textexclamdown}{OT1}{!`}
3927 \DeclareTextCommand{\textquestiondown}{OT1}{?`}
3928 \DeclareTextCommand{\textquotedblleft}{OT1}{%
3929 \IfInputModeCode{\TextSymbolUnavailable\textquotedblleft}%
3930 {\char 92 }%
3931 }
3932 % \end{macrocode}
3933 % \end{macro}\end{macro}\end{macro}\end{macro}\end{macro}\end{macro}
3934 % \end{macro}
3935 %
3936 % Several of the definitions in \texttt{applemac.def} can be improved.
3937 % Most of it is about seeing to that all characters have a proper text
3938 % mode definition, so that their unavailability can be trapped.
3939 %
3940 % \begin{macrocode}
3941 \def\@tempa{applemac}
3942 \ifx \@tempa\RIE@encoding
3943 \DeclareInputBoth{173}{\textneq}{\neq}
3944 \DeclareInputBoth{176}{\textinfty}{\infty}
3945 \DeclareInputBoth{177}{\textpm}{\pm}
3946 \DeclareInputBoth{178}{\textleq}{\leq}
3947 \DeclareInputBoth{179}{\textgeq}{\geq}
3948 \DeclareInputBoth{181}{\textmu}{\mu}
3949 \DeclareInputBoth{182}{\textpartial}{\partial}
3950 \DeclareInputBoth{183}{\textSigma}{\Sigma}
3951 \DeclareInputBoth{184}{\textPi}{\Pi}
3952 \DeclareInputBoth{185}{\textpi}{\pi}
3953 \DeclareInputBoth{186}{\textint}{\int}
3954 \DeclareInputBoth{189}{\textohm}{\Omega}
3955 \DeclareInputBoth{194}{\textlnot}{\lnot}
3956 \DeclareInputBoth{195}{\textsurd}{\surd}
3957 \DeclareInputBoth{197}{\textapprox}{\approx}
3958 \DeclareInputBoth{198}{\textDelta}{\Delta}
3959 \DeclareInputBoth{214}{\textdiv}{\div}
3960 \DeclareInputBoth{215}{\textdiamond}{\diamond}
3961 \DeclareInputBoth{218}{\textfractionsolidus}{/}
3962 % \end{macrocode}
3963 %
3964 % Several of the above text commands are not defined in the \LaTeX\
3965 % kernel. Therefore one must either define them in some encoding, or
3966 % define a default for them, to make them proper text commands. If they
3967 % are not then their unavailability cannot be trapped. |\textapplelogo|
3968 % appears in \texttt{applemac.def}.
3969 % \begin{macrocode}
3970 \ProvideTextCommandDefault{\textneq}{%
3971 \TextSymbolUnavailable\textneq
3972 }
3973 \ProvideTextCommandDefault{\textapplelogo}{%
3974 \TextSymbolUnavailable\textapplelogo
3975 }
3976 \DeclareTextSymbol{\textinfty}{OMS}{49}
3977 \DeclareTextSymbol{\textpm}{OMS}{6}
3978 \DeclareTextSymbol{\textleq}{OMS}{20}
3979 \DeclareTextSymbol{\textgeq}{OMS}{21}
3980 % \DeclareTextSymbol{\textmu}{TS1}{181}
3981 \DeclareTextSymbol{\textpartial}{OML}{64}
3982 \DeclareTextSymbol{\textSigma}{OT1}{6}
3983 \DeclareTextSymbol{\textPi}{OT1}{5}
3984 \DeclareTextSymbol{\textpi}{OML}{25}
3985 \DeclareTextSymbol{\textint}{OMS}{115}
3986 \DeclareTextSymbol{\textohm}{OT1}{10} % Kind of \textOmega
3987 % \DeclareTextSymbol{\textlnot}{TS1}{172}
3988 % \DeclareTextSymbol{\textsurd}{TS1}{187}
3989 \DeclareTextSymbol{\textapprox}{OMS}{25}
3990 \DeclareTextSymbol{\textDelta}{OT1}{1}
3991 % \DeclareTextSymbol{\textdiv}{TS1}{246}
3992 \DeclareTextSymbol{\textdiamond}{OMS}{5}
3993 % \DeclareTextSymbol{\textfractionsolidus}{TS1}{47}
3994 \input{TS1enc.def}
3995 \fi
3996 \fi
3997 % \end{macrocode}
3998 % \begin{macrocode}
3999 \let\if@rtkinenc@=\@undefined
4000 \let\@rtkinenc@true=\@undefined
4001 \let\@rtkinenc@false=\@undefined
4002 % \end{macrocode}
4003 % The |@rtkinenc@| switch isn't needed any more, so it might just as
4004 % well be undefined.
4005 %
4006 %
4007 % \subsection{Useful abbreviations}
4008 % \changes{v\,2.10}{2000/10/11}{\LaTeX\ abbreviation commands from
4009 % \package{ltxdoc} commented out. (LH)}
4010 %
4011 % The commands currently found in this section are inherited from the
4012 % \package{ltxdoc} package, but as they aren't of much use with \Tcl,
4013 % they have been commented out.
4014 %
4015 % |\cmd{\foo}| Prints |\foo| verbatim. It may be used inside moving
4016 % arguments. |\cs{foo}| also prints |\foo|, for those who prefer that
4017 % syntax. (This second form may even be used when |\foo| is |\outer|).
4018 % \begin{macro}{\cmd}
4019 % \begin{macro}{\cs}
4020 % \DoNotIndex{\\}
4021 % \begin{macrocode}
4022 % \def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}}
4023 % \def\cmd@to@cs#1#2{\char\number`#2\relax}
4024 % \DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}}
4025 % \end{macrocode}
4026 % \end{macro}
4027 % \end{macro}
4028 %
4029 % \begin{macro}{\marg}
4030 % |\marg{text}| prints \marg{text}, `mandatory argument'.
4031 % \DoNotIndexHarmless{\PrintChar{`\{}}
4032 % \DoNotIndexHarmless{\PrintChar{`\}}}
4033 % \begin{macrocode}
4034 % \providecommand\marg[1]{%
4035 % {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}}
4036 % \end{macrocode}
4037 % \end{macro}
4038 %
4039 % \begin{macro}{\oarg}
4040 % |\oarg{text}| prints \oarg{text}, `optional argument'.
4041 % \begin{macrocode}
4042 % \providecommand\oarg[1]{%
4043 % {\ttfamily[}\meta{#1}{\ttfamily]}}
4044 % \end{macrocode}
4045 % \end{macro}
4046 %
4047 % \begin{macro}{\parg}
4048 % |\parg{te,xt}| prints \parg{te,xt}, `picture mode argument'.
4049 % \begin{macrocode}
4050 % \providecommand\parg[1]{%
4051 % {\ttfamily(}\meta{#1}{\ttfamily)}}
4052 %</compclass>
4053 % \end{macrocode}
4054 % \end{macro}
4055 %
4056 %
4057 %
4058 %
4059 % \changes{v\,2.00}{2000/07/17}{Section with \cs{DocInclude} removed,
4060 % since that is defined by \package{xdoc}. (LH)}
4061 %
4062 % \Finale
4063 %
4064 \endinput
4065