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