| 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 |
|