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