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