diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/tcldoc')
16 files changed, 0 insertions, 13051 deletions
diff --git a/Master/texmf-dist/source/latex/tcldoc/dtxload.dtx b/Master/texmf-dist/source/latex/tcldoc/dtxload.dtx deleted file mode 100644 index f68a0ca3a8b..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/dtxload.dtx +++ /dev/null @@ -1,1256 +0,0 @@ -% -% -% \iffalse Meta-comment -% -%<*driver> -\documentclass{tcldoc} - -\DeclareRobustCommand{\package}[1]{\textsf{#1}} -\newcommand{\Alpha}{\textit{Alpha}} -\newcommand{\AlphaTk}{\textit{Alphatk}} - -\PageIndex -\setcounter{IndexColumns}{2} -\CodelineNumbered -\RecordChanges -\IndexPrologue{\section*{Index}\markboth{Index}{Index}% - Numbers written in italic refer to the page where - the corresponding entry is described; numbers underlined refer - to the definition; numbers in roman refer to the pages where - the entry is used.} -\expandafter\def \expandafter\GlossaryParms \expandafter{\GlossaryParms - \hbadness=10000\emergencystretch=2cm} - -\begin{document} -\DocInput{dtxload.dtx} -\PrintChanges -\PrintIndex -\end{document} -%</driver> -% \fi -% -% \title{\package{dtxload} --- loading \Tcllogo\ code directly from -% \texttt{.dtx} source files} -% \author{Lars Hellstr\"om^^A -% \thanks{E-mail: \texttt{Lars.Hellstrom@math.umu.se}}} -% \date{December 20, 2000} -% \maketitle -% -% \begin{abstract} -% \package{dtxload} is a feature for the text editor \Alpha. It -% implements a command for loading a piece of \Tcllogo\ code directly -% from a \texttt{.dtx} file. -% \end{abstract} -% -% \tableofcontents -% -% \section{Usage} -% -% \subsection{About \Alpha} -% -% About \Alpha\ itself, the \Alpha~v\,7.3 manual says the following: -% \begin{quotation} -% \Alpha\ is a very powerful, multi-purpose text editor. -% \Alpha\ is multi-modal, which means it switches between different -% modes depending on which type of document you are editing. Everybody -% who has used Emacs knows about this concept. The idea with different -% modes is to change \Alpha's behaviour depending on which kind of text -% you're editing. For example if you're programming in C$^{++}$ or -% editing a \LaTeX\ document you want different features. -% -% \Alpha\ is very customizable. Much of \Alpha's functionality is -% implemented in `packages' or `extensions'. [\dots] -% \Alpha\ uses Dr.~Ousterhout's \emph{Tool Command Language} (\Tcllogo) as -% an extension language. Many of the functions bound to keystrokes, -% as well as many of the functions in the menus, are written in \Tcllogo. -% All the `packages' or `extensions' just mentioned are all written -% in \Tcllogo. Anybody who wants can write new packages for \Alpha! -% -% Of course, you don't have to learn \Tcllogo\ to use \Alpha. You can -% have lots of use of \Alpha\ without knowing anything about \Tcllogo. -% But if you want to become a real power user, you should consider -% trying it out. Then the possibilities of customizing \Alpha\ are -% unlimited. -% \end{quotation} -% Originally \Alpha\ only existed on the \mbox{MacOS} platform, but -% recently the program was rewritten in Tk.\footnote{Tk is an extension of -% \Tcllogo\ which includes GUI support.} In that form (which is called -% \AlphaTk), \Alpha\ can be run on any platform for which there exists -% a port of Tk! -% -% \medskip -% -% There are also some \Alpha-related URLs which should be mentioned. -% \Alpha's official home page is~\cite{AlphaHome}, but it is currently -% rather out-of-date. More recent information can be found on -% e.g.~\cite{DocScriptingAlpha}, which also has links to many other -% \Alpha-related sites. The home page for \AlphaTk\ is~\cite{Alphatk}. -% -% -% -% \subsection{Installation} -% -% To install \package{dtxload} as an \Alpha\ feature, you first \LaTeX\ -% the file \texttt{dtxload.ins}---this will generate a file -% \texttt{dtxload.tcl}, which contains the \Tcllogo\ code for the -% package in a form that \Alpha\ understands. Then follow the normal -% procedure for installing an \Alpha\ package, i.e., open -% \texttt{dtxload.tcl}\footnote{Which should be somewhere outside -% \Alpha's directory subtree.} in \Alpha---this will trigger the -% automatic installation dialog for the package and you proceed as -% usual. -% -% -% \subsection{Loading \Tcllogo\ code} -% \label{Ssec:Loading} -% -% To load (evaluate) a piece of \Tcllogo\ code in a \texttt{.dtx} -% document, simply select that code and press \marginpar{Loading code: -% \textsf{Cmd--L}}Command--L. The commands are evaluated one by one and -% the result of each command will be shown at the current log destination -% (by default the status line, but that can be changed). In case one of -% the commands return with an error, that error will be shown as well, -% evaluation of further commands is cancelled, and the insertion point is -% moved to the beginning of the erroneous command. Furthermore the mark -% will be left at the end of the selection, so that the part of the -% original selection which has not yet been successfully evaluated can -% easily be reselected using the \textsf{Mark Hilite} command. -% -% Loading \Tcllogo\ code does not necessary mean all text in the -% selection will be evaluated; only extractable code will be passed on -% to the \Tcllogo\ interpreter. There are several factors which affect -% whether a piece of text is extractable code or not, but the foremost -% is that text on \package{docstrip} comment lines (i.e., lines which -% begin by a `|%|' that is not immediately followed by a `|<|') is -% \emph{not} extractable code. Secondly, if the selection contains a -% \package{docstrip} guard line which marks the start of a module then -% \package{dtxload} will ask you whether you want the code in that -% module to be loaded. If you answer no, it naturally won't be. -% -% Thus far the factors which may restrict which text is extractable -% code correspond exactly to what the \package{docstrip} -% program~\cite{docstrip} might do when generating a file of extracted -% code, but \package{dtxload} has two additional mechanisms which may -% categorize text as ``not extractable code''. Both are however -% controlled by preferences in the \Alpha\ \TeX\ mode, so they can be -% switched off if you don't like them. -% The first is the \describestring[var.][]{onlyLoadDtxFiles} -% \textsf{Only Load Dtx Files} preference, which when on restricts -% loading to files with suffix \texttt{.dtx}. For \TeX\ files with other -% suffixes I suspect that Command--L is pressed more often by accident -% than because there actually is some \Tcllogo\ code that should be -% loaded \textellipsis\space The second mechanism is controlled by the -% \describestring[var.][]{onlyLoadTclEnvs} \textsf{Only Load Tcl Envs} -% preference, which when on adds the restriction that extractable code -% must appear inside a \texttt{tcl} or \texttt{tcl*} environment -% (defined by the \package{tcldoc} \LaTeX\ package~\cite{tcldoc}). This -% is primarily useful when a \texttt{.dtx} file contains both \Tcllogo\ -% code in \texttt{tcl} environments and code in some other language in -% e.g.\ \texttt{macrocode} environments, since if the preference had been -% off then \package{dtxload} would stop at the \package{docstrip} guard -% that must appear at the beginning of each non-\Tcllogo\ code section -% and ask whether the code should be included, whereas if it is on then -% \package{dtxload} doesn't even have to ask whether the code in the -% \texttt{macrocode} environments should be loaded. -% -% \medskip -% -% As an example of how the load \Tcllogo\ code command works, consider -% the following code: -% \DontCheckModules\iffalse -%<*example> -%<<EXAMPLE -% \fi\begin{macrocode} -% Text text text text text -% \begin{tcl} -set a A -%<*andB> -append a B -%</andB> -append a C -%<*andD> -append a D -%</andB> -expr $a -string length $a -% \end{tcl} -% text text text. -% \end{macrocode}\iffalse -%EXAMPLE -%</example> -% \fi \CheckModules -% If lines 1--7 above are selected and Command--L is pressed, -% \package{dtxload} will display the message ``\texttt{Tcl eval OK}'' on -% the status line and the following information will have been added to -% the log.\footnote{This shows the window log format, but there are -% other formats. Furthermore the `\texttt{<}' and `\texttt{>}' will -% actually be guillemets in \Alpha\ (but not in \AlphaTk).} -% \begin{trivlist}\item\small -% |<dtxload> set a A|\\ -% |A|\\[\medskipamount] -% |<dtxload> append a B|\\ -% |AB|\\[\medskipamount] -% |<dtxload> append a C|\\ -% |ABC| -% \end{trivlist} -% The |<dtxload>| lines show the commands that were evaluated and the -% lines after these contain the respective results of these commands. -% Before the |append a B| command is evaluated, \package{dtxload} will -% stop and ask -% \begin{quote} -% \textsf{Should \textless andB\textgreater\ modules be included?} -% \end{quote} -% In the case above the answer given was `Yes'; if it had been `No' then -% the |append a B| command would neither be logged nor evaluated, and -% the result of the |append a C| command would have been |AC|. -% -% If one continues by selecting lines 9--12 and pressing Command--L -% then \package{dtxload} will display the message ``\texttt{Tcl eval -% error}'' on the status line, the insertion point will be moved to the -% beginning of line 11, and the following information will be found in -% the log: -% \begin{trivlist}\item\small -% |<dtxload> append a D|\\ -% |ABCD|\\[\medskipamount] -% |<dtxload> expr $a|\\ -% |Error: syntax error in expression "ABCD"| -% \end{trivlist} -% If then line 11 is changed to |expr {$a}| and lines 11--12 are again -% selected (e.g. using \textsf{Mark Hilite}) and loaded then -% \package{dtxload} will log: -% \begin{trivlist}\item\small -% |<dtxload> expr {$a}|\\ -% |ABCD|\\[\medskipamount] -% |<dtxload> string length $a|\\ -% |4| -% \end{trivlist} -% -% Finally, if lines 3--12 are selected and loaded then these are the -% questions \package{dtxload} will ask: -% \begin{itemize} -% \item \textsf{Should \textless andB\textgreater\ modules be included?} -% (Possible answers are `Yes' and `No'.) -% \item \textsf{Should \textless andD\textgreater\ modules be included?} -% (Possible answers are `Yes' and `No'.) -% \item \textsf{Module nesting error: \textless*andD\textgreater\ -% module ended by \textless/andB\textgreater. For which -% guards should the positions be pushed?} -% (Possible answers are `None', `Start', `End', and `Both'.) -% \end{itemize} -% In the last case, \package{dtxload} has noticed that the guard -% expressions that began (\textsf{andD}) and ended (\textsf{andB}) a -% module are not equal (which is an error). Answering `Both' here will -% push the positions of (the beginning of) both guard lines (8 and 10) onto -% the bookmark stack so that they can easily be jumped to and corrected -% later, but \package{dtxload} will continue evaluating the rest of the -% selection after you answer. -% -% -% \subsection{Selecting log destination} -% -% At startup, \package{dtxload} is logging results on the status line, -% i.e., after a command has been evaluated it either displays the message -% \begin{quote} -% \texttt{Tcl eval OK:\ }\meta{result} -% \end{quote} -% or -% \begin{quote} -% \texttt{Tcl eval error:\ }\meta{error message} -% \end{quote} -% depending on whether the command returned an error or not. The -% evaluation log can however be sent to a window instead. -% -% To set the destination for the log, one uses the procedure -% \describestring[proc][dtxload]{logdest}|dtxload::logdest|. To set the -% log destination to the window \word{win}, one gives the command -% \begin{quote} -% |dtxload::logdest window| \word{win} -% \end{quote} -% When the log destination is a window, the log shows the commands -% that were evaluated as well as their result. If there is no window -% named \word{win} then it is created. A slight -% variation on this is the command -% \begin{quote} -% |dtxload::logdest shell| \word{win} -% \end{quote} -% which makes the \word{win} window a \Alpha\ \Tcllogo\ shell window if -% it has to create it. When the log destination is a shell window, the -% commands that are executed will be saved on the history list as well -% as inserted in the window. -% -% A short form which may be convenient is -% \begin{quote} -% |dtxload::logdest here| -% \end{quote} -% which simply makes the current window the log destination. Finally, -% the log destination is reset to the status line after the command -% \begin{quote} -% |dtxload::logdest status| -% \end{quote} -% Evaluation will also be logged on the status line if the log -% destination window is closed. -% -% -% \subsection{Other features and surprises} -% -% If nothing is selected when Command--L is pressed, \package{dtxload} -% will continue as if all text was selected. -% -% Like \Alpha's \Tcllogo\ shell, \package{dtxload} can send the commands -% to evaluate to a remote \Tcllogo\ interpreter rather than \Alpha's -% built-in interpreter. In both cases the choice of target interpreter is -% controlled by the global \Alpha\ variable -% \describestring[var.][]{evaluateRemotely}|evaluateRemotely|. The -% easiest way of changing this variable is via the \Tcllogo-tk submenu -% of \Alpha's \Tcllogo\ menu. -% -% If the \textsf{Only Load Tcl Envs} preference is on and lines 4--6 in -% the code example of Subsection~\ref{Ssec:Loading} are loaded then -% \package{dtxload} will simply display the message -% \begin{quote} -% \texttt{No extractable code found.} -% \end{quote} -% The reason for this is that the first character of the selection is -% a |%|; when the first character in the interval to load is a percent -% character then \package{dtxload} will guess that this position is not -% in a \texttt{tcl} or \texttt{tcl*} environment, and therefore it won't -% try to extract any code until it has seen a comment line that contains -% |\begin{tcl}| or |\begin{tcl*}|. You can always avoid making a -% \package{docstrip} guard the first thing in the selection to load. -% -% -% -% \StopEventually{ -% \begin{thebibliography}{9} -% \bibitem{Alphatk} -% Vince Darley: \textit{Alphatk} ({\small WWW} page), -% \texttt{http}://\texttt{www.santafe.edu}\slash -% \texttt{\~{}vince}\slash \texttt{alphatk}\slash -% \texttt{about.html} -% \bibitem{DocScriptingAlpha} -% Donavan Hall: \textit{Alpha} ({\small WWW} page), -% \texttt{http}://\texttt{magnet.fsu.edu}\slash -% \texttt{\~{}hall}\slash\texttt{docscripting}\slash -% \texttt{alpha}/. -% \bibitem{tcldoc} -% Lars Hellstr\"om: -% \textit{The \package{tcldoc} package and class}, -% \texttt{ftp}:/\slash\texttt{ftp.tex.ac.uk}\slash -% \texttt{tex-archive}\slash \texttt{macros}\slash -% \texttt{latex}\slash \texttt{contrib}\slash -% \texttt{supported}\slash \texttt{tcldoc.dtx}. -% \bibitem{AlphaHome} -% Pete Keleher: \textit{Alpha Home Page} ({\small WWW} page), -% \texttt{http}://\texttt{alpha.olm.net}/. -% \bibitem{docstrip} -% Frank Mittelbach, Denys Duchier, Johannes Braams, Marcin -% Woli\'nski, and Mark Wooding: \textit{The \textsf{DocStrip} -% program}, The \LaTeX3 Project; -% \texttt{ftp}:/\slash\texttt{ftp.tex.ac.uk}\slash -% \texttt{tex-archive}\slash \texttt{macros}\slash -% \texttt{latex}\slash \texttt{base}\slash \texttt{docstrip.dtx}. -% \end{thebibliography} -% } -% -% \section{Implementation} -% -% -% \subsection{Interface to \Alpha} -% -% The package begins with an |alpha::feature| command to declare itself -% to \Alpha. As it is hardly useful outside the \texttt{TeX} mode, it -% declares itself as being specific to that mode. -% \begin{tcl} -%<*tcl> -alpha::feature dtxload 1.1 {TeX} { -% \end{tcl} -% -% \begin{variable}{onlyLoadDtxFiles} -% \begin{variable}{onlyLoadTclEnvs} -% Next comes the initialization script for the feature, which -% declares the two preference variables used by \package{dtxload}. -% Both variables are flags. |onlyLoadDtxFiles| is |1| if loading of -% code is restricted to files with suffix \texttt{.dtx} and |0| if -% there is no restriction. |onlyLoadTclEnvs| is |1| if only code -% surrounded by a \texttt{tcl} or \texttt{tcl*} environment is loaded -% and |0| if there is no such restriction. Both preferences are by -% default |1|. -% \begin{tcl} - # When set, the Load Tcl Code command will be disabled in - # TeX files whose suffix is not dtx. - newPref flag onlyLoadDtxFiles 1 TeX - # When set, the Load Tcl Code command will only extract code - # from code lines in tcl and tcl* environments. - newPref flag onlyLoadTclEnvs 1 TeX -% \end{tcl} -% \end{variable}\end{variable} -% \begin{variable}{loadTclCode} -% The initialization script also declares a keybinding preference (to -% the |dtxload::load| procedure), which is used for -% \package{dtxload}'s only command. The default value is Command--L -% and the binding is specific to the \texttt{TeX} mode. -% \begin{tcl} - # This is the key binding for dtxload's Load Tcl Code command. - newPref binding loadTclCode <O/L TeX "" dtxload::load TeX -% \end{tcl} -% \end{variable} -% -% After the initialization script comes the activation and deactivation -% scripts (which, if I understood things correctly, are called when -% switching between modes), but these need not contain anything for -% \package{dtxload}. Instead the arguments of |alpha::feature| continue -% with the uninstallation procedure -% \begin{tcl} -} "" "" uninstall {this-file} \ -% \end{tcl} -% the maintainer specification (|\x9a| is \texttt{\"{o}}) -% \begin{tcl} - maintainer {"Lars Hellstr\x9am" Lars.Hellstrom@math.umu.se} \ -% \end{tcl} -% and a short help text -% \begin{tcl} - help {The dtxload package implements a command for loading - Tcl code that is embedded in a .dtx file without docstripping - the file first. For more help, LaTeX the file dtxload.dtx.} -% \end{tcl} -% It is possible that the help should rather be |file dtxload.dtx|, but -% then this file would have to be installed somewhere that \Alpha\ -% would find it. I haven't studied the matter. -% -% Next the |dtxload| namespace is declared to \Tcllogo. -% \begin{tcl} -namespace eval dtxload {} -% \end{tcl} -% \setnamespace{dtxload} -% -% -% \subsection{Code extraction} -% -% -% The code extraction algorithm of \package{dtxload} lack a few of the -% features of proper \package{docstrip}, but I don't think any of them -% are essential for the kind of work \package{dtxload} is designed for. -% The differences to \package{docstrip} are: -% \begin{itemize} -% \item The values of guard expressions are not determined from a -% base set of options, instead the user is inquired for the value of -% each guard expression. -% \item Extraction of \package{docstrip} verbatim mode lines is not -% supported, but it isn't needed for \Tcllogo\ code either. -% \item Metacomments aren't extracted, but they hardly contain any -% code of interest to the \Tcllogo\ interpreter anyway. -% \item \package{dtxload} may scan the comment lines for certain -% known markup elements (beginning and end of \texttt{tcl} and -% \texttt{tcl*} environments) and choose to enable or disable -% extraction based on that. -% \end{itemize} -% \package{dtxload} does however act on the guard modifiers and it also -% looks for errors in the syntax of guards. -% -% \begin{variable}{module_stack} -% \begin{variable}{next_module_idx} -% The |dtxload::module_stack| variable is keeps track of how modules -% are nested around the currently considered line. The variable is a -% stack implemented as a list in which the last element corresponds to -% the innermost module. Each element in this list is itself a list -% with the structure -% \begin{quote} -% \word{expression} \word{start pos.} \word{previous}\regopt -% \end{quote} -% The \word{expression} is the guard expression, as a string. The -% \word{start pos.} is the position in the file where the module -% started. Finally, the \word{previous} is a boolean value which -% records the inclusion status (value of |dtxload::module_included|) -% that was in force before the module was entered. -% -% The |dtxload::next_module_idx| variable holds the index in the -% |dtxload:|\penalty\hyphenpenalty|:module_stack| list of the next -% module whose expression has not yet been evaluated; it is equal to -% |llength ${dtxload::module_stack}| if all module expressions have -% been evaluated. Those elements in the |dtxload::module_stack| list -% which have index $\geq$ |dtxload::next_module_idx| do not have a -% \word{previous} element. -% \end{variable}\end{variable} -% -% \begin{arrayvar}{known_expressions}[expression] -% The |dtxload::known_expressions| array records the values of all -% known expressions, i.e., those expressions about whose values the -% user has been inquired. The entries are either |0| (for ``don't -% include'') or |1| (for ``include''). -% \end{arrayvar} -% -% \begin{proc}{eval_guard} -% The |dtxload::eval_guard| procedure takes the string that is a guard -% expression as argument. It returns |1| if the expression evaluates -% to true and |0| if it evaluates to false. -% -% If the expression has an entry in the |dtxload::known_expressions| -% array then the |dtxload::eval_guard| procedure returns that value, -% and if it does not the user is inquired for the value. -% \begin{tcl} -proc dtxload::eval_guard {e} { - global dtxload::known_expressions - if {![info exists dtxload::known_expressions($e)]} then { - set dtxload::known_expressions($e)\ - [expr {"yes" ==\ - "[askyesno "Should <$e> modules be included?"]"}] - } - set dtxload::known_expressions($e) -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{push_module} -% The |dtxload::push_module| procedure pushes a block module onto the -% module stack, but it does not modify the value of -% |dtxload::module_included|. The syntax of |dtxload::push_module| is -% \begin{quote} -% |dtxload::push_module| \word{expression} \word{position} -% \end{quote} -% where \word{expression} is the expression string and -% \word{position} is the position where the guard begins. -% \begin{tcl} -proc dtxload::push_module {e p} { - global dtxload::module_stack - lappend dtxload::module_stack [list $e $p] -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{pop_module} -% The |dtxload::pop_module| procedure pops a block module off the -% module stack and checks that the modules are properly nested. Its -% syntax is -% \begin{quote} -% |dtxload::pop_module| \word{expression} \word{position} -% \end{quote} -% where \word{expression} is the expression string of the module to -% pop and \word{position} is the position where the (end of module) -% guard begins. -% -% If the module nesting is incorrect then the user is presented with -% a dialog with buttons for pushing the positions of the incorrect -% modules. It is not an error if the module stack is empty, since it -% is perfectly reasonable that the beginning of the code to evaluate -% is in the middle of a module. -% \begin{tcl} -proc dtxload::pop_module {e p} { - global dtxload::module_stack dtxload::module_included\ - dtxload::next_module_idx - set len [llength ${dtxload::module_stack}] - if {$len==0} then {return} - set L [lindex ${dtxload::module_stack} [expr {$len-1}]] - if {[lindex $L 0] != $e} then { - switch [buttonAlert "Module nesting error: <*[lindex $L 0]>\ - module ended by </$e>. For which guards should the positions\ - be pushed?" None Start End Both]\ - { - Start {dtxload::push_bookmarks [lindex $L 1]} - End {dtxload::push_bookmarks $p} - Both {dtxload::push_bookmarks [lindex $L 1] $p} - } - } - set dtxload::module_stack\ - [lreplace ${dtxload::module_stack} end end] - if {$len>=${dtxload::next_module_idx}} then { - incr dtxload::next_module_idx -1 - } - if {[llength $L]>2} then { - set dtxload::module_included [lindex $L 2] - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{push_bookmarks} -% The |dtxload::push_bookmarks| procedure pushes one or several -% positions in the current window onto the bookmarks stack. The -% arguments are the positions to push. -% \begin{tcl} -proc dtxload::push_bookmarks {args} { - global markStack markName - foreach pos $args { - set name mark$markName - incr markName - createTMark $name $pos - set fileName [win::Current] - set markStack [linsert $markStack 0 [list $fileName $name]] - } -} -% \end{tcl} -% \end{proc} -% -% \begin{variable}{module_included} -% \begin{variable}{in_tcl_env} -% The |dtxload::module_included| variable keeps track of whether the -% current position is in an included module. It is |1| if the current -% position should be included and |0| if it shouldn't. -% The |dtxload::in_tcl_env| variable is used for keeping track of -% what markup context surrounds the currently considered line in the -% file. It is set to |1| when a |\begin{tcl}| or |\begin{tcl*}| is -% scanned, and set to |0| when a |\end{tcl}| or |\end{tcl*}| is scanned. -% \end{variable}\end{variable} -% -% \begin{proc}{update_included} -% Simply pushing a module onto the module stack does not update the -% |dtxload:|\penalty\hyphenpenalty|:module_included| variable; that is -% instead done by the |dtxload::update_included| procedure, which -% should be called right before the value of |dtxload::module_included| -% is used. The reason for this arrangement is that it avoids evaluating -% guard expressions whose values do not matter. -% -% |dtxload::update_included| has no arguments. -% \begin{tcl} -proc dtxload::update_included {} { - global dtxload::module_included dtxload::module_stack\ - dtxload::next_module_idx - while {${dtxload::module_included} &&\ - ${dtxload::next_module_idx}<[llength ${dtxload::module_stack}]}\ - { - set L [lindex ${dtxload::module_stack} ${dtxload::next_module_idx}] - lappend L ${dtxload::module_included} - set dtxload::module_stack [lreplace ${dtxload::module_stack}\ - ${dtxload::next_module_idx} ${dtxload::next_module_idx} $L] - incr dtxload::next_module_idx - set dtxload::module_included [dtxload::eval_guard [lindex $L 0]] - } -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}{extract_line} -% The |dtxload::extract_line| procedure steps forward in the file one -% line at a time until it has found a codeline that can be extracted or -% it reaches the end of the part of the file from which code is to be -% extracted. Its syntax is -% \begin{quote} -% |dtxload::extract_line| \word{startpos} \word{endpos} -% \end{quote} -% Here \word{startpos} is the position at which it should start to -% look for an extractable code line, and \word{endpos} is the -% position at which the search should stop if no such line is found. -% \word{startpos} is assumed to be at the beginning of a line (for -% identification of code, comment, and guard line purposes) but no -% test for this is made. -% -% The return value of |dtxload::extract_line| is a list with the -% structure -% \begin{quote} -% \word{nextpos} \word{line}\regopt\ \word{foundpos}\regopt -% \end{quote} -% \word{nextpos} is the first position in the file after the part that -% was searched. \word{line} is the extracted codeline and -% \word{foundpos} is the position at which it began, but these two items -% are missing if there was no more codeline. -% -% The overall structure of |dtxload::extract_line| is a loop -% which steps through the lines until it reaches the |endpos|. When a -% line to extract is actually found the procedure returns from within -% the loop using the |return| command. The local variable |pos| -% stores the current position, and |pos2| stores the position of the -% beginning of the next line. -% \begin{tcl} -proc dtxload::extract_line {startpos endpos} { - global dtxload::in_tcl_env onlyLoadTclEnvs dtxload::module_included - for {set pos $startpos} {[pos::compare {$pos<$endpos}]}\ - {set pos $pos2} { -% \end{tcl} -% Inside the loop, the next line is extracted and stored in the local -% variable |line|. Then |switch| is used for classifying the line and -% taking appropriate actions. -% \begin{tcl} - set pos2 [nextLineStart $pos] - if {$pos2>$endpos} then {set pos2 $endpos} - set line [getText $pos $pos2] - switch -regexp -- $line { -% \end{tcl} -% \changes{v\,1.0}{2000/10/15}{Corrected regular expressions; only -% percents on the beginning of a line are significant. (LH)} -% \changes{v\,1.1}{2000/12/03}{Guard lines will affect code extraction. -% (LH)} -% \changes{v\,1.1}{2000/12/18}{The code extraction procedures can -% now handle \package{docstrip} verbatim mode guards, provided -% they do not appear in a block of extractable code. (LH)} -% Lines that begin with |%<<| are \package{docstrip} guard lines that -% start verbatim mode. Extracting code from such lines is currently -% not supported by \package{dtxload}, so if such a guard is ever -% encountered the extraction is stopped, but \package{dtxload} can -% skip verbatim sections from which it shouldn't extract code. -% \begin{tcl} - {^%<<} { - if {!$onlyLoadTclEnvs || ${dtxload::in_tcl_env}} then { - dtxload::update_included - if {${dtxload::module_included}} then { - alertnote "docstrip verbatim mode guard line\ - encountered. Verbatim mode extraction is\ - currently not supported, so I stop here." - goto $pos - return [list $endpos] - } - } -% \end{tcl} -% The part of the guard line which comes after the |%<<| is called an -% end-tag. Verbatim mode ends with the next line which consists of a -% percent character followed by this end-tag, and therefore all lines -% up to and including that one are skipped. A technical matter here -% is that spaces at the end of the line does not count (\TeX\ cannot -% see them), but spaces inside the end-tag do count! -% \begin{tcl} - set endtag %[string trimright [string trimright\ - [string range $line 3 end] \n\r] \ ] - while {[string trimright [string trimright $line \n\r] \ ]\ - != $endtag} { - set pos $pos2 - if {[pos::compare {$pos>=$endpos}]}\ - then {return [list $pos]} - set pos2 [nextLineStart $pos] - if {$pos2>$endpos} then {set pos2 $endpos} - set line [getText $pos $pos2] - } - } -% \end{tcl} -% Lines that begin with |%<*| or |%</| are \package{docstrip} guard -% lines that delimit block modules, but they do not contain any code -% themselves. The module is pushed onto or popped off the module stack -% when the guard line is encountered, but evaluating it is deferred -% until the first extractable code line. -% \begin{tcl} - {^%<[*/]} { - if {![regexp {^%<(\*|/)([^>]+)>} $line foo modifier\ - expression]}\ - then { - if {"[askyesno "Malformed guard line \"$line\"\ - encountered. Push position?"]"=="yes"}\ -% - then {dtxload::push_bookmarks $pos} - } elseif {$modifier=="*"} then { - dtxload::push_module $expression $pos - } else { - dtxload::pop_module $expression $pos - } - } -% \end{tcl} -% -% Other lines that begin with |%<| are also \package{docstrip} -% guard lines, but in these cases the lines (i) contain some code -% and (ii) the guard only affect the code on that line. There must be -% a |>| somewhere on the line, and the part of the line after the |>| -% is code that \package{docstrip} can extract. -% \begin{tcl} - {^%<} { - if {![regexp {^%<(-|\+|)([^>]+)>(.*)$} $line\ - foo modifier expression code]}\ - then { - if {"[askyesno "Malformed guard line \"$line\"\ - encountered. Push position?"]"=="yes"}\ -% - then {dtxload::push_bookmarks $pos} - } elseif {!$onlyLoadTclEnvs || ${dtxload::in_tcl_env}} then { - dtxload::update_included - if {${dtxload::module_included}} then { - if {[dtxload::eval_guard $expression] !=\ - ($modifier=="-")}\ - then {return [list $pos2 $code $pos]} - } - } - } -% \end{tcl} -% Remaining lines that begin with |%| are considered comment lines, -% but they could technically be metacomment lines (begin with |%%|) or -% a line that \package{docstrip} would process in verbatim mode. In -% both these cases \package{docstrip} would copy the line, but as there -% is little point in using these \package{docstrip} features for lines -% that the \Tcllogo\ interpreter would miss, \package{dtxload} ignores -% those subtleties. -% \begin{tcl} - {^%} { - while {[regexp -indices {\\(begin|end) *{tcl\*?}} $line\ - match type]} { - set dtxload::in_tcl_env\ - [expr {"[eval string range \$line $type]"=="begin"}] - set line [string range $line\ - [expr {[lindex $match 1]+1}] end] - } - } -% \end{tcl} -% Finally, all lines that do not begin with a |%| are code lines. -% \begin{tcl} - default { - if {!$onlyLoadTclEnvs || ${dtxload::in_tcl_env}} then { - dtxload::update_included - if {${dtxload::module_included}}\ -% - then {return [list $pos2 $line $pos]} - } - } - } - } - list $endpos -} -% \end{tcl} -% \end{proc} -% -% -% -% \subsection{Evaluating the code} -% -% The code in this subsection is based on the \Alpha\ procedures -% |Alpha::evaluate| and |tcltk::evaluate|, but |dtxload::evaluate| -% tries to return a bit more information. -% -% \begin{proc}{evaluate} -% The |dtxload::evaluate| procedure takes a script as argument and -% evaluates it in the global variable context. Any errors that occur -% are caught. The returned value is a list with the structure -% \begin{quote} -% \word{code} \word{message} -% \begin{regexp}[\regopt]\word{errorInfo} -% \word{errorCode}\end{regexp} -% \end{quote} -% \word{code} is the \Tcllogo\ return code, as returned by |catch| -% when evaluating the script. \word{message} is the value returned by -% the script; it is an error message if an error occurred. -% \word{errorInfo} is the value that the global variable |errorInfo| -% got after the script was evaluated and \word{errorCode} is the -% corresponding value of |errorCode|. -% -% When the \Alpha\ global variable |evaluateRemotely| is |0| the -% evaluation is carried out by \Alpha\ itself, but when -% |evaluateRemotely| is |1| the script is instead sent to a separate -% \Tcllogo\ shell for evaluation. The current implementation does not -% return the values of the |errorInfo| and |errorCode| variables in -% that case, which is why they may be absent from the return value of -% |dtxload::evaluate|. -% \changes{v\,1.0}{2000/10/17}{Moved \texttt{history} interaction to -% \texttt{dtxload::shell\_log}. (LH)} -% \changes{v\,1.1}{2000/12/05}{Added code for remote evaluation. (LH)} -% \begin{tcl} -proc dtxload::evaluate {t} { - global errorInfo errorCode evaluateRemotely tcl_platform - if {!$evaluateRemotely} then { - if {[set code [catch {uplevel \#0 $t} msg]] == 1} then { -% \end{tcl} -% If there was an error, the last part of the value of |errorInfo| -% will be due to the |uplevel| command. As that command was not -% requested by the user, it would be confusing and it is therefore -% best to remove it. -% \begin{tcl} - set L [split $errorInfo \n] - set errorInfo [join [lrange $L 0 [expr {[llength $L] - 4}]] \n] - } - list $code $msg $errorInfo $errorCode - } elseif {$tcl_platform(platform) == "macintosh"} then { -% \end{tcl} -% On the \mbox{MacOS} platform, the script is sent to a remote -% \Tcllogo\ shell via AppleEvents. -% \begin{tcl} - global tclshSig - app::ensureRunning $tclshSig - list [catch { - aebuild::result -t 30000 '${tclshSig}' misc dosc ----\ - [aebuild::TEXT $t] - } res]\ - $res - } else { -% \end{tcl} -% On the other platforms I don't really know what should be done. The -% following code is based on that in |tcltk::evaluate|, but I haven't -% been able to test it (help, please?). -% \begin{tcl} - global tclshInterp - if {![info exists tclshInterp]} { - if {[catch {tcltk::findTclshInterp}]} { - return [list 1 "No shell selected"] - } - } - if {$tcl_platform(platform) == "windows"} { - if {[dde services Tk $tclshInterp] == ""} { - alertnote "The remote shell has died, please select a new one." - unset tclshInterp - return [dtxload::evaluate $t] - } - list [catch {dde execute Tk $tclshInterp $t} res] $res - } else { - list [catch {send $tclshInterp $t} res] $res - } - } -} -% \end{tcl} -% \end{proc} -% -% -% \subsection{Logging} -% -% The code in this subsection is based on the \Alpha\ procedures -% |Shel::carriageReturn| and |Alpha::evaluate|, but many details had to -% be changed because, amongst other things, the window to which text is -% written is not the frontmost one. -% -% \begin{proc}{message_log} -% The |dtxload::message_log| procedure handles logging a script -% evaluation on the status line. It takes one argument, which is the -% script to evaluate, and returns a boolean value that specifies whether -% an error occurred (|0| is no error, |1| is that there was an error). -% -% Since the status line is rather limited in size there isn't very -% much that can be logged on it. |dtxload::message_log| simply displays -% the result or error that occurred. -% \begin{tcl} -proc dtxload::message_log {script} { - set res [dtxload::evaluate $script] - if {[lindex $res 0]==1} then { - message "Tcl eval error: [lindex $res 1]" - expr 1 - } else { - if {[string length [lindex $res 1]] == 0} then { - message "Tcl eval OK." - } else { - message "Tcl eval OK: [lindex $res 1]" - } - expr 0 - } -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}{window_log} -% \changes{v\,1.1}{2000/12/05}{Renamed procedure (old name was -% \texttt{dtxload:\discretionary{}{}{}:shell\_log}). (LH)} -% \begin{variable}{log_window_name} -% \changes{v\,1.1}{2000/12/05}{Renamed variable (old name was -% \texttt{dtxload:\discretionary{}{}{}:shell\_window\_name}). (LH)} -% The |dtxload::window_log| procedure handles logging a script -% evaluation in a window, which must be open when this procedure is -% called. It takes one argument, which is the script to evaluate, and -% returns a boolean value that specifies whether an error occurred -% (|0| is no error, |1| is that there was an error). -% -% When it is set the |dtxload::log_window_name| variable holds the -% name of the window which is used in logging, and when it isn't set -% this means that logging should be in the status line. Initially it -% is unset. -% \begin{tcl} -if {[info exists dtxload::log_window_name]} then { - unset dtxload::log_window_name -} -% \end{tcl} -% \end{variable} -% -% If the log window has mode |Shel| then the |script| is recorded in -% the history list, but since the shells have trouble handling history -% items that contain more than one line, all newlines in the recorded -% script will be replaced by semicolons. This \emph{can} change the -% meaning of the script, but hopefully that happens so rarely that one -% can live with it. -% \changes{v\,1.0}{2000/11/01}{Scripts added to the history list are -% converted to one-liners. (LH)} -% \begin{tcl} -proc dtxload::window_log {script} { - upvar #0 dtxload::log_window_name win - global win::Modes Shel::startPrompt Shel::endPrompt - if {[set win::Modes($win)] == "Shel"} then { - global Shel::histnum - regsub -all \n [string trimright $script] " ; " text - history add $text - set Shel::histnum [history nextid] - } -% \end{tcl} -% -% Next the script is inserted into (at the end of) the log window. -% The lines on which logged scripts are written are marked out using -% a special \package{dtxload} prompt, which is constructed as -% \begin{quote} -% |"${Shel::startPrompt}dtxload${Shel::endPrompt} "| -% \end{quote} -% If the log window mode is |Shel| and the last thing in the window -% is the current prompt for the window, then that prompt is replaced -% by the \package{dtxload} prompt, otherwise a newline followed by a -% \package{dtxload} prompt will be appended to the window. The result -% of a logged script is put on the line after the last line of the -% script. -% \begin{tcl} - set pos [maxPos -w $win] - select -w $win $pos $pos - set dtxprompt "${Shel::startPrompt}dtxload${Shel::endPrompt} " - if {[set win::Modes($win)] != "Shel"} then { - insertText -w $win \r$dtxprompt - } else { - set stdprompt [Alpha::Prompt] - set pos2 [pos::math $pos - [string length $stdprompt]] - if {[getText -w $win $pos2 $pos] != $stdprompt} then { - insertText -w $win \r$dtxprompt - } else { - replaceText -w $win $pos2 $pos $dtxprompt - refresh - } - } -% \end{tcl} -% There currently is a bug (it is fixed in \Alpha~8) in -% |replaceText| which causes it to always draw in the current window. -% The |refresh| restores the proper window contents. -% \changes{v\,1.0}{2000/10/16}{\texttt{refresh} inserted to overcome -% \texttt{replaceText} bug. (LH)} -% -% Inserting the actual script text is basically an |insertText|, but -% before the script is inserted all newlines in it (except the last) -% are replaced by newlines followed by a \package{dtxload} prompt. -% Since |dtxload::load| converts all newlines to linefeeds, it is -% sufficient to replace linefeeds. It seems that newlines in \Alpha\ -% are always carriage returns (regardless of the window's ``platform'' -% attribute), and I assume that the \package{dtxload} prompt doesn't -% contain any regexp metacharacter. -% \changes{v\,1.0}{2000/10/16}{Assuming newlines in the script to log -% are linefeeds. (LH)} -% \begin{tcl} - regsub -all \n [string trimright $script] \r$dtxprompt text - insertText -w $win "$text\r" -% \end{tcl} -% After the script has been logged, it is time to evaluate it and log -% the result. -% \begin{tcl} - set res [dtxload::evaluate $script] - if {[lindex $res 0]==1} then { - insertText -w $win "Error: [lindex $res 1]\r" - if {[llength $res]>2} then { - global errorInfo - set errorInfo [lindex $res 2] - } - message "Tcl eval error" - } else { - if {[string length [lindex $res 1]]>0}\ - then {insertText -w $win "[lindex $res 1]\r"} - message "Tcl eval OK" - } -% \end{tcl} -% If the window has mode |Shel| then the window's current prompt is -% inserted. It is necessary to call |Alpha::Prompt| again because -% evaluating the script might have changed the prompt. Then the return -% value is finally computed. -% \begin{tcl} - if {[set win::Modes($win)] == "Shel"}\ - then {insertText -w $win [Alpha::Prompt]} - expr {[lindex $res 0]==1} -} -% \end{tcl} -% \end{proc} -% -% -% -% -% \subsection{Putting it all together} -% -% \begin{proc}{load} -% The |dtxload::load| procedure implements the \package{dtxload} user -% command---it extracts and evaluates the code in the current -% selection (if something is selected) or the entire front window (if -% nothing is selected). The evaluation is logged a window or on the -% status line depending on the current value of -% |dtxload::log_window_name|. -% -% Code is extracted and evaluated one command (or as close as one gets) -% at a time. In case an error occurs the loading is stopped and the -% insertion point is moved to the beginning of the problematic script, -% whereas the mark is put at the end of the code to load. This way a -% simple \textsf{Mark Hilite} will select the part of the code that -% remains to be loaded. -% -% The very first thing |dtxload::load| does is to check whether it is -% allowed to load any code in this window. -% \begin{tcl} -proc dtxload::load {} { - global onlyLoadDtxFiles - if {$onlyLoadDtxFiles && ![string match *.dtx [win::CurrentTail]]}\ - then { - message "Not a .dtx file." - return - } -% \end{tcl} -% Then the interval from which code should be extracted is -% determined. -% \begin{tcl} - set startpos [getPos] - set endpos [selEnd] - if {[pos::compare {$startpos == $endpos}]} then { - set startpos [minPos] - set endpos [maxPos] - } -% \end{tcl} -% Next it is determined what logging method should be used. The name -% of the procedure gets stored in the local variable |log|. -% \begin{tcl} - global dtxload::log_window_name - if { - [info exists dtxload::log_window_name] && - [lsearch -exact [winNames] ${dtxload::log_window_name}]!=-1 - } then {set log dtxload::window_log}\ - else {set log dtxload::message_log} -% \end{tcl} -% After that a couple of extraction-related variables are initialized. -% The idea behind how the |dtxload::in_tcl_env| variable is set is that -% if one is loading a short piece of code inside a \texttt{tcl} -% environment then the first line probably doesn't start with a |%|, -% whereas if one is loading an entire file (and thus starts in -% non-\texttt{tcl}-environment) the first character quite likely is a -% |%|. -% \begin{tcl} - global dtxload::in_tcl_env dtxload::module_stack\ - dtxload::next_module_idx dtxload::module_included - set dtxload::in_tcl_env\ - [expr {[getText $startpos [pos::math {$startpos+1}]] != "%"}] - set dtxload::module_stack {} - set dtxload::next_module_idx 0 - set dtxload::module_included 1 -% \end{tcl} -% The last piece of initialization concerns the |script| local -% variable, in which the extracted lines are collected until they -% make up an entire command. The |escaped| variable is a boolean -% which is true when the newline at the end of the last line of -% |script| was escaped. The |spos| variable stores the position at -% which the command currently being collected began, but it is -% initialized to |none| here to help distinguishing the case that no -% extractable code was found. -% \begin{tcl} - set script "" - set escaped 0 - set spos none - while {[pos::compare $startpos < $endpos]} { - set extract [dtxload::extract_line $startpos $endpos] - if {[llength $extract]>1} then { -% \end{tcl} -% When a line of code has been extracted, it must be appended to -% |script|. This isn't as easy as one might imagine, because \Tcllogo\ -% code being |source|d (which is what loading must function as) is fed -% through a few more conversion steps than code being |eval|ed. In -% particular all escaped newlines are converted to spaces and all -% other newlines are converted to linefeeds, so that must be done -% explicitly. A newline is considered to be escaped if is is preceded -% by an odd number of backslashes, and if it is then the last backslash -% and the newline are replaced by a single space. If the last line of -% |script| ended by an escaped newline then the script is considered -% incomplete and more code will be collected before evaluation is -% attempted. Evaluation of |script| is also conditioned by that |info\ -% complete $script| returns |1|. -% \changes{v\,1.0}{2000/10/16}{Converting nonescaped newlines to -% linefeeds, since \Tcllogo\ doesn't consider carriage returns to -% be command separators. (LH)} -% \begin{tcl} - if {[string length $script]==0} then { - set spos [lindex $extract 2] - } - set line [lindex $extract 1] - if {$escaped} then {set line [string trimleft $line]} - set escaped [regsub -all\ - "((^|\[^\\\\\])(\\\\\\\\)*)\\\\(\r|\n|\r\n)$" $line {\1 } line] - if {!$escaped} then {regsub "\r\n?\$" $line \n line} - append script $line - if {!$escaped && [info complete $script]} then { - if {[$log $script]} then { - select $spos $endpos - markHilite - return - } else { - set script "" - } - } - } elseif {$spos=="none"} then { - message "No extractable code found." - } - set startpos [lindex $extract 0] - } -% \end{tcl} -% If the |script| variable isn't empty, then try to evaluate whatever -% is in it before returning. If not even that causes an error the -% |dtxload:|\penalty\hyphenpenalty|:known_expressions| array is unset -% so that one can use other options for the next piece of code loaded. -% \begin{tcl} - if {[string length $script]>0 && [$log $script]} then { - select $spos $endpos - markHilite - } else { - global dtxload::known_expressions - if {[info exists dtxload::known_expressions]}\ - then {unset dtxload::known_expressions} - } -} -% \end{tcl} -% \end{proc} -% -% -% \subsection{Setting the log destination} -% -% \begin{proc}{logdest} -% \changes{v\,1.0}{2000/10/16}{Procedure added. (LH)} -% \changes{v\,1.1}{2000/12/07}{Procedure renamed from -% \texttt{dtxload::redirect} and the syntax was changed. (LH)} -% The log destination is set using the |dtxload::logdest| procedure. -% The general syntax for this procedure is -% \begin{quote} -% |dtxload::logdest| \word{keyword} \word{window name}\regopt -% \end{quote} -% where the \word{keyword} (mainly) specifies the type of log -% destination and \word{window name} is the name of the target -% window (ignored for some \word{keyword}s). -% \begin{tcl} -proc dtxload::logdest {type {win "dtxload log"}} { - global dtxload::log_window_name - switch -exact -- $type { -% \end{tcl} -% The first form of |dtxload::logdest| has the syntax -% \begin{quote} -% |dtxload::logdest status| -% \end{quote} -% It makes the status line the log destination. -% \begin{tcl} - status { - if {[info exists dtxload::log_window_name]}\ - then {unset dtxload::log_window_name} - } -% \end{tcl} -% The second form has the syntax -% \begin{quote} -% |dtxload::logdest here| -% \end{quote} -% It makes the current window the log destination, regardless of what -% may already be in it or which mode it has. -% \begin{tcl} - here {set dtxload::log_window_name [win::CurrentTail]} -% \end{tcl} -% The third form has the syntax -% \begin{quote} -% |dtxload::logdest window| \word{window name} -% \end{quote} -% It sets the log destination to the window named \word{window name}, -% regardless of what may already be in it or which mode it has. If -% the window does not already exist it is created. -% \begin{tcl} - window { - if {[lsearch -exact [winNames] $win] == -1} then { - new -n $win -shell 1 -text "This is a dtxload log window.\r" - } - set dtxload::log_window_name $win - } -% \end{tcl} -% The fourth and final form has the syntax -% \begin{quote} -% |dtxload::logdest shell| \word{window name} -% \end{quote} -% It calls |Shel::start| to open a \Tcllogo\ shell window and sets the -% log destination to that window. -% \begin{tcl} - shell { - Shel::start "Alpha" $win\ - "This is a dtxload log window (and Alpha Tcl shell).\r" - set dtxload::log_window_name $win - } - } -} -%</tcl> -% \end{tcl} -% \end{proc} -% -% -% \Finale -% -\endinput diff --git a/Master/texmf-dist/source/latex/tcldoc/dtxload.ins b/Master/texmf-dist/source/latex/tcldoc/dtxload.ins deleted file mode 100644 index 4e33fb87512..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/dtxload.ins +++ /dev/null @@ -1,54 +0,0 @@ -% dtxload.ins --- DOCSTRIP installation script for dtxload. -\input docstrip - -% Redefine the \MetaPrefix; it should be something which starts a -% until-end-of-line comment: -\edef\MetaPrefix{\string#\string#} - - -% Redefine the file preamble and postamble; this is necessary because -% otherwise the old \metaPrefix is inserted at the beginning of these -% lines. -\preamble - -This file may be distributed and/or modified under the conditions -of the LaTeX Project Public License, either version 1.2 of this -license or (at your option) any later version. The latest version -of this license is in - http://www.latex-project.org/lppl.txt -and version 1.2 or later is part of all distributions of LaTeX -version 1999/12/01 or later. - -This file may only be distributed together with a copy of the source -file from which it was generated. You may distribute that source file -without this generated file. - -\endpreamble - -\postamble -\endpostamble - -% Add a (auto-install) line at the top of the preamble, so that -% Alpha will auto-install it. -\edef\defaultpreamble{% - \MetaPrefix\space (auto-install)^^J% - \defaultpreamble -} - -% Actually make dtxload.tcl: -\generate{\file{dtxload.tcl}{\from{dtxload.dtx}{tcl}}} - - -\Msg{} -\Msg{**********************************************} -\Msg{*} -\Msg{* To complete installation,} -\Msg{* have Alpha open the file dtxload.tcl} -\Msg{* somewhere outside Alpha's folder hierarchy.} -\Msg{*} -\Msg{**********************************************} -\Msg{} - - -\end - diff --git a/Master/texmf-dist/source/latex/tcldoc/dtxload.tcl b/Master/texmf-dist/source/latex/tcldoc/dtxload.tcl deleted file mode 100644 index af26546a774..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/dtxload.tcl +++ /dev/null @@ -1,361 +0,0 @@ -## (auto-install) -## -## This is file `dtxload.tcl', -## generated with the docstrip utility. -## -## The original source files were: -## -## dtxload.dtx (with options: `tcl') -## -## This file may be distributed and/or modified under the conditions -## of the LaTeX Project Public License, either version 1.2 of this -## license or (at your option) any later version. The latest version -## of this license is in -## http://www.latex-project.org/lppl.txt -## and version 1.2 or later is part of all distributions of LaTeX -## version 1999/12/01 or later. -## -## This file may only be distributed together with a copy of the source -## file from which it was generated. You may distribute that source file -## without this generated file. -## -alpha::feature dtxload 1.1 {TeX} { - # When set, the Load Tcl Code command will be disabled in - # TeX files whose suffix is not dtx. - newPref flag onlyLoadDtxFiles 1 TeX - # When set, the Load Tcl Code command will only extract code - # from code lines in tcl and tcl* environments. - newPref flag onlyLoadTclEnvs 1 TeX - # This is the key binding for dtxload's Load Tcl Code command. - newPref binding loadTclCode <O/L TeX "" dtxload::load TeX -} "" "" uninstall {this-file} \ - maintainer {"Lars Hellstr\x9am" Lars.Hellstrom@math.umu.se} \ - help {The dtxload package implements a command for loading - Tcl code that is embedded in a .dtx file without docstripping - the file first. For more help, LaTeX the file dtxload.dtx.} -namespace eval dtxload {} -proc dtxload::eval_guard {e} { - global dtxload::known_expressions - if {![info exists dtxload::known_expressions($e)]} then { - set dtxload::known_expressions($e)\ - [expr {"yes" ==\ - "[askyesno "Should <$e> modules be included?"]"}] - } - set dtxload::known_expressions($e) -} -proc dtxload::push_module {e p} { - global dtxload::module_stack - lappend dtxload::module_stack [list $e $p] -} -proc dtxload::pop_module {e p} { - global dtxload::module_stack dtxload::module_included\ - dtxload::next_module_idx - set len [llength ${dtxload::module_stack}] - if {$len==0} then {return} - set L [lindex ${dtxload::module_stack} [expr {$len-1}]] - if {[lindex $L 0] != $e} then { - switch [buttonAlert "Module nesting error: <*[lindex $L 0]>\ - module ended by </$e>. For which guards should the positions\ - be pushed?" None Start End Both]\ - { - Start {dtxload::push_bookmarks [lindex $L 1]} - End {dtxload::push_bookmarks $p} - Both {dtxload::push_bookmarks [lindex $L 1] $p} - } - } - set dtxload::module_stack\ - [lreplace ${dtxload::module_stack} end end] - if {$len>=${dtxload::next_module_idx}} then { - incr dtxload::next_module_idx -1 - } - if {[llength $L]>2} then { - set dtxload::module_included [lindex $L 2] - } -} -proc dtxload::push_bookmarks {args} { - global markStack markName - foreach pos $args { - set name mark$markName - incr markName - createTMark $name $pos - set fileName [win::Current] - set markStack [linsert $markStack 0 [list $fileName $name]] - } -} -proc dtxload::update_included {} { - global dtxload::module_included dtxload::module_stack\ - dtxload::next_module_idx - while {${dtxload::module_included} &&\ - ${dtxload::next_module_idx}<[llength ${dtxload::module_stack}]}\ - { - set L [lindex ${dtxload::module_stack} ${dtxload::next_module_idx}] - lappend L ${dtxload::module_included} - set dtxload::module_stack [lreplace ${dtxload::module_stack}\ - ${dtxload::next_module_idx} ${dtxload::next_module_idx} $L] - incr dtxload::next_module_idx - set dtxload::module_included [dtxload::eval_guard [lindex $L 0]] - } -} -proc dtxload::extract_line {startpos endpos} { - global dtxload::in_tcl_env onlyLoadTclEnvs dtxload::module_included - for {set pos $startpos} {[pos::compare {$pos<$endpos}]}\ - {set pos $pos2} { - set pos2 [nextLineStart $pos] - if {$pos2>$endpos} then {set pos2 $endpos} - set line [getText $pos $pos2] - switch -regexp -- $line { - {^%<<} { - if {!$onlyLoadTclEnvs || ${dtxload::in_tcl_env}} then { - dtxload::update_included - if {${dtxload::module_included}} then { - alertnote "docstrip verbatim mode guard line\ - encountered. Verbatim mode extraction is\ - currently not supported, so I stop here." - goto $pos - return [list $endpos] - } - } - set endtag %[string trimright [string trimright\ - [string range $line 3 end] \n\r] \ ] - while {[string trimright [string trimright $line \n\r] \ ]\ - != $endtag} { - set pos $pos2 - if {[pos::compare {$pos>=$endpos}]}\ - then {return [list $pos]} - set pos2 [nextLineStart $pos] - if {$pos2>$endpos} then {set pos2 $endpos} - set line [getText $pos $pos2] - } - } - {^%<[*/]} { - if {![regexp {^%<(\*|/)([^>]+)>} $line foo modifier\ - expression]}\ - then { - if {"[askyesno "Malformed guard line \"$line\"\ - encountered. Push position?"]"=="yes"}\ - then {dtxload::push_bookmarks $pos} - } elseif {$modifier=="*"} then { - dtxload::push_module $expression $pos - } else { - dtxload::pop_module $expression $pos - } - } - {^%<} { - if {![regexp {^%<(-|\+|)([^>]+)>(.*)$} $line\ - foo modifier expression code]}\ - then { - if {"[askyesno "Malformed guard line \"$line\"\ - encountered. Push position?"]"=="yes"}\ - then {dtxload::push_bookmarks $pos} - } elseif {!$onlyLoadTclEnvs || ${dtxload::in_tcl_env}} then { - dtxload::update_included - if {${dtxload::module_included}} then { - if {[dtxload::eval_guard $expression] !=\ - ($modifier=="-")}\ - then {return [list $pos2 $code $pos]} - } - } - } - {^%} { - while {[regexp -indices {\\(begin|end) *{tcl\*?}} $line\ - match type]} { - set dtxload::in_tcl_env\ - [expr {"[eval string range \$line $type]"=="begin"}] - set line [string range $line\ - [expr {[lindex $match 1]+1}] end] - } - } - default { - if {!$onlyLoadTclEnvs || ${dtxload::in_tcl_env}} then { - dtxload::update_included - if {${dtxload::module_included}}\ - then {return [list $pos2 $line $pos]} - } - } - } - } - list $endpos -} -proc dtxload::evaluate {t} { - global errorInfo errorCode evaluateRemotely tcl_platform - if {!$evaluateRemotely} then { - if {[set code [catch {uplevel \#0 $t} msg]] == 1} then { - set L [split $errorInfo \n] - set errorInfo [join [lrange $L 0 [expr {[llength $L] - 4}]] \n] - } - list $code $msg $errorInfo $errorCode - } elseif {$tcl_platform(platform) == "macintosh"} then { - global tclshSig - app::ensureRunning $tclshSig - list [catch { - aebuild::result -t 30000 '${tclshSig}' misc dosc ----\ - [aebuild::TEXT $t] - } res]\ - $res - } else { - global tclshInterp - if {![info exists tclshInterp]} { - if {[catch {tcltk::findTclshInterp}]} { - return [list 1 "No shell selected"] - } - } - if {$tcl_platform(platform) == "windows"} { - if {[dde services Tk $tclshInterp] == ""} { - alertnote "The remote shell has died, please select a new one." - unset tclshInterp - return [dtxload::evaluate $t] - } - list [catch {dde execute Tk $tclshInterp $t} res] $res - } else { - list [catch {send $tclshInterp $t} res] $res - } - } -} -proc dtxload::message_log {script} { - set res [dtxload::evaluate $script] - if {[lindex $res 0]==1} then { - message "Tcl eval error: [lindex $res 1]" - expr 1 - } else { - if {[string length [lindex $res 1]] == 0} then { - message "Tcl eval OK." - } else { - message "Tcl eval OK: [lindex $res 1]" - } - expr 0 - } -} -if {[info exists dtxload::log_window_name]} then { - unset dtxload::log_window_name -} -proc dtxload::window_log {script} { - upvar #0 dtxload::log_window_name win - global win::Modes Shel::startPrompt Shel::endPrompt - if {[set win::Modes($win)] == "Shel"} then { - global Shel::histnum - regsub -all \n [string trimright $script] " ; " text - history add $text - set Shel::histnum [history nextid] - } - set pos [maxPos -w $win] - select -w $win $pos $pos - set dtxprompt "${Shel::startPrompt}dtxload${Shel::endPrompt} " - if {[set win::Modes($win)] != "Shel"} then { - insertText -w $win \r$dtxprompt - } else { - set stdprompt [Alpha::Prompt] - set pos2 [pos::math $pos - [string length $stdprompt]] - if {[getText -w $win $pos2 $pos] != $stdprompt} then { - insertText -w $win \r$dtxprompt - } else { - replaceText -w $win $pos2 $pos $dtxprompt - refresh - } - } - regsub -all \n [string trimright $script] \r$dtxprompt text - insertText -w $win "$text\r" - set res [dtxload::evaluate $script] - if {[lindex $res 0]==1} then { - insertText -w $win "Error: [lindex $res 1]\r" - if {[llength $res]>2} then { - global errorInfo - set errorInfo [lindex $res 2] - } - message "Tcl eval error" - } else { - if {[string length [lindex $res 1]]>0}\ - then {insertText -w $win "[lindex $res 1]\r"} - message "Tcl eval OK" - } - if {[set win::Modes($win)] == "Shel"}\ - then {insertText -w $win [Alpha::Prompt]} - expr {[lindex $res 0]==1} -} -proc dtxload::load {} { - global onlyLoadDtxFiles - if {$onlyLoadDtxFiles && ![string match *.dtx [win::CurrentTail]]}\ - then { - message "Not a .dtx file." - return - } - set startpos [getPos] - set endpos [selEnd] - if {[pos::compare {$startpos == $endpos}]} then { - set startpos [minPos] - set endpos [maxPos] - } - global dtxload::log_window_name - if { - [info exists dtxload::log_window_name] && - [lsearch -exact [winNames] ${dtxload::log_window_name}]!=-1 - } then {set log dtxload::window_log}\ - else {set log dtxload::message_log} - global dtxload::in_tcl_env dtxload::module_stack\ - dtxload::next_module_idx dtxload::module_included - set dtxload::in_tcl_env\ - [expr {[getText $startpos [pos::math {$startpos+1}]] != "%"}] - set dtxload::module_stack {} - set dtxload::next_module_idx 0 - set dtxload::module_included 1 - set script "" - set escaped 0 - set spos none - while {[pos::compare $startpos < $endpos]} { - set extract [dtxload::extract_line $startpos $endpos] - if {[llength $extract]>1} then { - if {[string length $script]==0} then { - set spos [lindex $extract 2] - } - set line [lindex $extract 1] - if {$escaped} then {set line [string trimleft $line]} - set escaped [regsub -all\ - "((^|\[^\\\\\])(\\\\\\\\)*)\\\\(\r|\n|\r\n)$" $line {\1 } line] - if {!$escaped} then {regsub "\r\n?\$" $line \n line} - append script $line - if {!$escaped && [info complete $script]} then { - if {[$log $script]} then { - select $spos $endpos - markHilite - return - } else { - set script "" - } - } - } elseif {$spos=="none"} then { - message "No extractable code found." - } - set startpos [lindex $extract 0] - } - if {[string length $script]>0 && [$log $script]} then { - select $spos $endpos - markHilite - } else { - global dtxload::known_expressions - if {[info exists dtxload::known_expressions]}\ - then {unset dtxload::known_expressions} - } -} -proc dtxload::logdest {type {win "dtxload log"}} { - global dtxload::log_window_name - switch -exact -- $type { - status { - if {[info exists dtxload::log_window_name]}\ - then {unset dtxload::log_window_name} - } - here {set dtxload::log_window_name [win::CurrentTail]} - window { - if {[lsearch -exact [winNames] $win] == -1} then { - new -n $win -shell 1 -text "This is a dtxload log window.\r" - } - set dtxload::log_window_name $win - } - shell { - Shel::start "Alpha" $win\ - "This is a dtxload log window (and Alpha Tcl shell).\r" - set dtxload::log_window_name $win - } - } -} -## -## -## End of file `dtxload.tcl'. diff --git a/Master/texmf-dist/source/latex/tcldoc/examples/README.txt b/Master/texmf-dist/source/latex/tcldoc/examples/README.txt deleted file mode 100644 index 2d3d8abe5da..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/examples/README.txt +++ /dev/null @@ -1,40 +0,0 @@ -README for the parsetcl and writepdf packages: -============================================== - -The parsetcl package implements basic parsing -of Tcl scripts, and is written completely in -Tcl. To generate parsetcl.tcl, run LaTeX on -parsetcl.ins. To typeset the documentation, -run LaTeX on parsetcl.dtx. To see an example -of what it does, you can try the following -commands in a Tcl shell: - - source parsetcl.tcl - auto_load parray - set tree [parsetcl::simple_parse_script [info body parray]] - parsetcl::format_tree $tree {} { } - -The tree variable will be set to a parser tree -for the body of the parray procedure. The last -command reformats this tree (mostly replacing -whitespace between list elements) to make the -structure more visible. - - -The writepdf package is written completely in -Tcl and provides basic commands for writing -well-formed PDF files. To generate writepdf.tcl, -run LaTeX on pdf.ins. To typeset the -documentation, run LaTeX on pdf.dtx. To see an -example of what it does, you can try the following -commands in a Tcl shell: - - source writepdf.tcl - source hellopdf.tcl - -This will generate a file hello.pdf that contains -a single page with the two words "Hello world!". - - -Lars Hellström, -20 July 2003 diff --git a/Master/texmf-dist/source/latex/tcldoc/examples/parsetcl.dtx b/Master/texmf-dist/source/latex/tcldoc/examples/parsetcl.dtx deleted file mode 100644 index 22609d6fa4e..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/examples/parsetcl.dtx +++ /dev/null @@ -1,1155 +0,0 @@ -% -% \iffalse -%<*driver> -\documentclass{tclldoc} - -\newcommand{\ParseTcl}{Parse\Tcllogo} -\providecommand{\href}[2]{#2} - -\begin{document} -\DocInput{parsetcl.dtx} -\end{document} -%</driver> -% \fi -% -% -% \title{\ParseTcl\ --- a parser for \Tcllogo\ code} -% \author{Lars Hellstr\"om} -% -% \maketitle -% -% -% \begin{abstract} -% \ParseTcl\ is a \Tcllogo\ package for parsing \Tcllogo\ code. -% It is written completely in \Tcllogo, and make heavy use of some -% new additions in \Tcllogo\,8.4. -% \end{abstract} -% -% \begin{tcl} -%<*pkg> -namespace eval parsetcl {} -package require Tcl 8.4 -package provide parsetcl 0.1 -% \end{tcl} -% \setnamespace{parsetcl} -% -% \tableofcontents -% -% \section{Parser results} -% -% The values returned by the parser are conceptually rooted trees, but -% technically the return values are lists. The general format of a -% subtree is -% \begin{quote} -% \word{type} \word{interval} \word{text} \word{subtree}\regstar -% \end{quote} -% where there is one \word{subtree} for each component that remains if -% the root of the subtree under consideration is deleted. The -% \word{type} specifies what kind of construction the subtree -% corresponds to. The \word{interval} is a list with the structure -% \begin{quote} -% \word{first} \word{last} -% \end{quote} -% where \word{first} and \word{last} are integers; the indices into -% the input string of the first and last respectively character that -% corresponds to this part of the parser tree. The \word{text} is, -% depending on the \word{type}, either empty or the explicit string -% that corresponds to this subtree. -% -% The \word{type}s are generally two-character strings, where the first -% letter specifies a major category and the second letter an exact type -% within that category, but this system is not enforced by any code. -% \begin{description} -% \item[Null types] -% The \emph{null} types all begin with an |N|. These correspond to -% information which isn't part of the script proper, but still is -% useful to include in the parse result. It is generally possible -% to add or remove subtrees of this type without changing the -% meaning of the reconstruction of the script. -% \begin{enumerate} -% \item[\texttt{Nc}] \describestring[subtree type]{Nc} -% This type is for comments, and it normally appears only in -% places where one would expect a command subtree. The -% \word{interval} includes the |#| beginning the comment, but not -% the newline ending it. The \word{text} is the text in the -% comment (initial |#| not included). -% \item[\texttt{Ne}] \describestring[subtree type]{Ne} -% This type is for syntax errors; rather than stopping at every -% error, the parser routines will try to recover as best they can, -% and an error item will be inserted in the parser tree. This -% type of item generally appears as a \word{subtree} of whatever -% was being parsed when the error was detected. The \word{text} is -% a human-readable error message. The \word{interval} specifies -% the erroneous characters; if the error is that some character(s) -% is missing then the end of the interval is the index of the -% character before that which is missing, and the start of the -% interval is the character after that which is missing. -% \item[\texttt{Np}] \describestring[subtree type]{Np} -% This type is merely a placeholder; both the \word{interval} and -% the \word{text} are empty strings. It is used when there was -% nothing to return, but call syntax requires that a subtree is -% returned. If some call returns an item of this type then it -% usually means that its caller also has reached the end of -% whatever that was parsing. -% \end{enumerate} -% -% \item[Literate types] -% The literate, or verbatim, types all begin with an |L|. Words (of -% a command) where no variable or command substitution will happen -% usually belong in this category. There are three types of -% literates: \describestring[subtree type]{Lb}|Lb|s are delimited by -% braces and \describestring[subtree type]{Lq}|Lq|s are delimited by -% quotes, whereas \describestring[subtree type]{Lr}|Lr|s have no -% particular delimiters. In each case, the \word{text} is the string -% that this interval of the input gets parsed into. -% -% Backslash--newline substitution is silently performed, but other -% types of substitution will result in that the item is considered -% to consist of one or more parts, each of which will be -% represented as a separate \word{subtree}. The delimiting quotes -% of an |Lq| is never included in the \word{interval} of any -% \word{subtree}. An |Lb| never has any \word{subtree}s due to -% substitution, since it can only be subject to backslash--newline -% substitution, but it may have |Ne| subtrees. -% -% \item[Merge types] -% The merge types all begin with an |M|. They are similar to the -% literate types, but are used for intervals of the input for which -% the \emph{text} cannot be completely determined. -% \describestring[subtree type]{Mq}|Mq|s are delimited by quotes, -% whereas \describestring[subtree type]{Mr}|Mr|s have no particular -% delimiters. The \word{text} is set to an empty string. There is -% always at least one \word{subtree}. -% -% \item[Substitution types] -% The substitution types all begin with an |S|. As the name -% indicates, they are used for intervals of the input that will be -% substituted by a \Tcllogo\ parser. -% \begin{enumerate} -% \item[\texttt{Sb}] \describestring[subtree type]{Sb} -% This type is for backslash substitution. The \word{text} is -% the character produced by this substitution. There is always -% an |Lr| subtree for the text following the initial backslash. -% \item[\texttt{Sv}] \describestring[subtree type]{Sv} -% This type is for scalar variable substitution. The -% \word{text} is empty, and there is one \word{subtree} for the -% name of the variable being substituted. The type of this -% subtree is either |Lr| or |Lb|, depending on whether the name -% is surrounded by braces or not. -% \item[\texttt{Sa}] \describestring[subtree type]{Sa} -% This type is for array variable substitution. The -% \word{text} is empty, and there are two \word{subtree}s: one -% for the name of the array (always an |Lr|) and one for the -% index into the array (either an |Lr| or an |Mr|). -% \item[\texttt{Sc}] \describestring[subtree type]{Sc} -% This type is for command substitution. The \word{text} is -% empty, and there is one \word{subtree} for each command in -% the script. -% \end{enumerate} -% -% \item[The command type] -% The \describestring[subtree type]{Cd}|Cd| type is for complete -% commands. The \word{text} is empty, and each word in the command -% has its own \word{subtree} (naturally, these are in the order of -% the words in the command). -% -% \item[Root types] -% The root types are used for the root in a parser tree, but they -% may also appear as proper subtrees if the parser is invoked -% recursively. This is for example what one does with the body -% argument of the |while| command: technically it is a string just -% like any other string, but it makes most sense to parse that -% string as a script and replace the original literate item by the -% entire tree generated by parsing this string. -% -% The root types all begin with an |R|. They are -% \begin{enumerate} -% \item[\texttt{Rs}] \describestring[subtree type]{Rs} -% This type is for script parsing. The \word{text} is usually -% empty, and each \word{subtree} is a command of the script. -% \item[\texttt{Rx}] \describestring[subtree type]{Rx} -% This type is for |expr| expression parsing. -% \end{enumerate} -% -% \end{description} -% -% \subsection{Some examples} -% -% The script -% \begin{quote} -% |set a "b\nc"| -% \end{quote} -% will be parsed as the list -%\begin{verbatim} -% Rs {0 11} {} \ -% {Cd {0 11} {} -% {Lr {0 2} set} -% {Lr {4 4} a} -% {Lq {6 11} b\nc -% {Lr {7 7} b} -% {Sb {8 9} \n {Lr {9 9} n}} -% {Lr {10 10} c} -% } -% } -%\end{verbatim} -% NB: This is not the canonical string representation, but one that was -% chosen for clarity of exposition. The |parsetcl::format_tree| -% procedure can be used to reformat a parser tree with indentation as -% shown above. -% -% -% \section{Basic script parsing} -% -% Basic script parsing makes a purely syntactic parsing of a script. It -% does not make any assumptions about the meaning of the commands used -% in the script, and hence it will not try to parse as scripts any -% argument of a commands (not even the byte-compiled commands). -% -% The parsing relies on a set of procedures which parses the next item -% of a particular sort, and returns the corresponding parse subtree. -% These procedures can call each other recursively in complicated ways, -% following the actual structure of the script that is being parsed. -% The general syntax for calling such a procedure is -% \begin{quote} -% \word{proc name} \word{string} \word{index-var-name} -% \word{extra}\regstar -% \end{quote} -% where \word{string} is the string from which something should be -% parsed and \word{index-var-name} is the name of a variable in the -% local context of the caller which holds the index of the first -% character that hasn't been parsed yet (or possibly the last character -% that has been parsed, it may depend on what is most convenient for -% that particular procedure). There are two reasons for using this -% set-up. One is that the calling procedure usually needs to continue -% parsing the string after the part that it made a recursive call to -% have parsed, and for that purpose this variable provides a convenient -% method of returning the value. The other reason is one of efficiency: -% If the script as a whole is passed as an argument to all procedures -% that are involved in the parsing process, as opposed to passing only -% the part that hasn't been parsed yet, then the need to copy the data -% decreases drastically. -% -% -% \subsection{Commands and scripts} -% -% \begin{proc}{flush_whitespace} -% The |flush_whitespace| procedure advances the index past a -% whitespace sequence. The syntax is -% \begin{quote} -% |parsetcl::flush_whitespace| \word{script} \word{index-var-name} -% \word{cmdsep} -% \end{quote} -% where \word{cmdsep} is |1| if command separators (newlines and -% semicolons) should be flushed as well, but |0| if they should be -% treated separately. The return value is the number of characters -% that were flushed. -% \begin{tcl} -proc parsetcl::flush_whitespace {script index_var cmdsep} { - upvar 1 $index_var index - if {[ - if {$cmdsep} then { - regexp -start $index -- {\A([ \t-\r;]|\\\n)+} $script match - } else { - regexp -start $index -- {\A([ \t\v\f\r]|\\\n)+} $script match - } - ]} then { - incr index [string length $match] - return [string length $match] - } else { - return 0 - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{parse_command} -% The |parse_command| procedure parses the next command, returning a -% |Cd|, |Nc|, or |Np| item to its caller. The syntax is -% \begin{quote} -% |parsetcl::parse_command| \word{script} \word{index-var-name} -% \word{nested} -% \end{quote} -% The \word{nested} argument is |1| if the context is that of command -% substitution (in which case |]| acts as command terminator), and |0| -% otherwise. Upon return, the index variable generally points to the -% character that terminates the command. -% -% The procedure skips past any whitespace or command separators in front -% of the actual command. -% \begin{tcl} -proc parsetcl::parse_command {script index_var nested} { - upvar 1 $index_var index -% \end{tcl} -% The first step is to scan past the whitespace in front of the -% command. -% \begin{tcl} - flush_whitespace $script index 1 -% \end{tcl} -% Then there are two ``not a command'' cases to take care of: there -% might be a comment or the command sequence might have ended. In the -% former case, the extent of the comment is determined and a -% corresponding |Nc| item is returned. Backslash--newline -% substitution adds a bit complexity to the problem of finding the end -% of the comment, since an escaped newline may be part of the comment, -% although a backslash is only escaping if it isn't itself escaped. -% \begin{tcl} - switch -- "[string index $script $index]$nested" {#0} - {#1} { - regexp -start $index -indices -- {\A#([^\n\\]|\\.)*(\\$)?}\ - $script interval - incr index - regsub -all -- {\\\n[ \t]*}\ - [string range $script $index [lindex $interval 1]]\ - { } text - set index [expr {[lindex $interval 1] + 1}] - return [list Nc $interval $text] - } 0 - 1 - \]1 { -% \end{tcl} -% In the latter case, an |Np| item is returned. It happens if -% |$index| is past the last character in the string, but also if -% |$index| is at a right bracket and the command is \word{nested}. -% \begin{tcl} - return [list Np "" ""] - } -% \end{tcl} -% But if we get this far, then there is a command to parse. One only -% has to parse all the words. -% \begin{tcl} - set res [list Cd [list $index ""] ""] - set next [parse_word $script index $nested] - while {[lindex $next 0] ne "Np"} { - lappend res $next - set next [parse_word $script index $nested] - } - lset res 1 1 [lindex $res end 1 1] - return $res -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{basic_parse_script} -% The |basic_parse_script| procedure parses a script (that is to say, a -% sequence of commands) and returns the corresponding |Rs| item. -% The syntax is -% \begin{quote} -% |parsetcl::basic_parse_script| \word{script} -% \end{quote} -% \begin{tcl} -proc parsetcl::basic_parse_script {script} { - set index 0 - set res [list Rs [list $index ""] ""] - while {[lindex [set next [parse_command $script index 0]] 0] ne "Np"} { - lappend res $next - } - incr index -1 - lset res 1 1 $index - return $res -} -% \end{tcl} -% \end{proc} -% -% -% \subsection{Parsing words} -% -% \begin{proc}{parse_word} -% The |parse_word| procedure parses the next command word, returning -% an |Lb|, |Lq|, |Lr|, |Mq|, |Mr|, or |Np| item to its caller. The -% syntax is -% \begin{quote} -% |parsetcl::parse_word| \word{script} \word{index-var-name} -% \word{nested} -% \end{quote} -% The \word{nested} argument is |1| if the context is that of command -% substitution (in which case |]| acts as command terminator), and |0| -% otherwise. It is assumed that the index variable points to the first -% character of the word when this procedure is called. Upon return, -% the index variable points to the first none-whitespace character -% (or command separator) after the word that was parsed. -% -% Most of the actual work is done by the helper procedures -% |parse_raw_word|, |parse_quoted_word|, and |parse_braced_word|. -% \begin{tcl} -proc parsetcl::parse_word {script index_var nested} { - upvar 1 $index_var index - switch -- [string index $script $index] \{ { - parse_braced_word $script index $nested - } \" { - parse_quoted_word $script index $nested - } "" - \; - \n { - list Np "" "" - } \] { - if {$nested} then { - list Np "" "" - } else { - parse_raw_word $script index $nested - } - } default { - parse_raw_word $script index $nested - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{parse_braced_word} -% The |parse_braced_word| procedure parses a brace-delimited word and -% returns the corresponding |Lb| item to its caller. The syntax is -% \begin{quote} -% |parsetcl::parse_braced_word| \word{script} \word{index-var-name} -% \word{nested} -% \end{quote} -% where the arguments and call conventions are as for |parse_word|. -% In case the braced word is followed by some non-whitespace -% characters, then this will be interpreted as though a space was -% missing after the brace. A corresponding |Ne| subtree will be -% attached to the |Lb| item returned, and the index variable will be -% pointed to that none-whitespace character after the brace. -% \begin{tcl} -proc parsetcl::parse_braced_word {script index_var nested} { - upvar 1 $index_var index - set res [list Lb [list $index ""]] - set depth 1 - set text "" - incr index - while {$depth>0} { -% \end{tcl} -% Each iteration of this loop takes care of one non-trivial character -% combination and whatever piece of trivial material that preceeds -% it. Braces which are not escaped obviously constitute non-trivial -% material (because they change the nesting depth), but escaped -% newlines are also non-trivial (because they are subject to -% substitution). -% \begin{tcl} - regexp -start $index -- {\A([^{}\\]|\\[^\n])*} $script match - append text $match - incr index [string length $match] - switch -- [string index $script $index] \{ { - incr depth - incr index - } \} { - incr depth -1 - incr index - } \\ { - if {[regexp -start $index -- {\A\\\n[ \t]*} $script match]}\ - then { - incr index [string length $match] - append text { } - } else { -% \end{tcl} -% In this (rather curious) case, the \word{script} ended with an -% escaping backslash, but there is nothing to escape. This is -% interpreted as just the backslash. However, there will be an error -% since the braces apparently haven't been properly balanced. -% \begin{tcl} - append text \\ - break - } - } "" { - break - } - } - if {$depth>0} then { - lset res 1 1 $index - lappend res $text [list Ne [list "" $index] {missing close-brace}] - lset res 3 1 0 [incr index] - return $res - } - lset res 1 1 [expr {$index - 1}] - lappend res $text -% \end{tcl} -% What remains now is to check that there aren't any stray characters -% following the close-brace. If there is whitespace to flush then -% everything is alright. Things are also alright if the next character -% is a command terminator or we're at the end of the string. -% \begin{tcl} - if {[flush_whitespace $script index 0]} then {return $res} - switch -- [string index $script $index] \n - \; - {} { - return $res - } \] { - if {$nested} then {return $res} - } -% \end{tcl} -% But if that is not the case then there is an error, and an |Ne| item -% should be appended to |res|. The exact appearence of this item does -% however depend on how the parser attempts to recover from the error, -% and that is not immediately obvious. The \Tcllogo\ parser makes no -% attempt to recover---and can therefore report the error as ``extra -% characters after close-brace''---but the best way to recover rather -% seems to be to assume that a space is missing. That is why the -% following error message is non-standard. -% \begin{tcl} - lappend res [list Ne [list $index [expr {$index - 1}]]\ - {missing space after close-brace}] - return $res -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{parse_quoted_word} -% The |parse_quoted_word| procedure parses a quote-delimited word and -% returns the corresponding |Lq| or |Mq| item to its caller. The -% syntax is -% \begin{quote} -% |parsetcl::parse_quoted_word| \word{script} \word{index-var-name} -% \word{nested} -% \end{quote} -% where the arguments and call conventions are as for |parse_word|. -% In case the quoted word is followed by some non-whitespace -% characters, then this will be interpreted as though a space was -% missing after the last quote. A corresponding |Ne| subtree will -% be be put last in the |Lq| or |Mq| item returned, and the index -% variable will be pointed to that none-whitespace character after -% the quote. -% \begin{tcl} -proc parsetcl::parse_quoted_word {script index_var nested} { - upvar 1 $index_var index - set res [list Lq [list $index ""] ""] - set text "" - incr index - while {1} { -% \end{tcl} -% Each iteration of this loop adds one subtree to |res| and the -% corresponding literate material to |text|. If some substitution -% happens which does not produce literate material then the |Lq| -% in |res| is changed to an |Mq|. -% \begin{tcl} - switch -- [string index $script $index] \\ { - lappend res [parse_backslash $script index] - append text [lindex $res end 2] - } \$ { - lappend res [parse_dollar $script index] - lset res 0 Mq - } \[ { - lappend res [parse_bracket $script index] - lset res 0 Mq - } \" { - incr index - break - } "" { - lappend res [list Ne [list $index [expr {$index - 1}]]\ - {missing close-quote}] - break - } default { - regexp -start $index -- {[^\\$\["]*} $script match - set t $index - incr index [string length $match] - lappend res [list Lr [list $t [expr {$index - 1}]] $match] - append text $match - } - } - lset res 1 1 [expr {$index - 1}] - if {[lindex $res 0] eq "Lq"} then { - lset res 2 $text -% \end{tcl} -% An |Lq| item that has precisely one subtree that furthermore is of -% type |Lr| can do without that subtree, since all the interesting -% information is in the |text|. -% \begin{tcl} - if {[llength $res] == 4 && [lindex $res 3 0] eq "Lr"} then { - set res [lrange $res 0 2] - } - } -% \end{tcl} -% What remains now is to check that there aren't any stray characters -% following the close-quote. If there is whitespace to flush then -% everything is alright. Things are also alright if the next character -% is a command terminator or we're at the end of the string. -% \begin{tcl} - if {[flush_whitespace $script index 0]} then {return $res} - switch -- [string index $script $index] \n - \; - {} { - return $res - } \] { - if {$nested} then {return $res} - } -% \end{tcl} -% But if that is not the case then there is an error, and an |Ne| item -% should be appended to |res|. As with characters after close-quotes, -% it is assumed that a space is missing. -% \begin{tcl} - lappend res [list Ne [list $index [expr {$index - 1}]]\ - {missing space after close-quote}] - return $res -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{parse_raw_word} -% The |parse_raw_word| procedure parses a whitespace-delimited word -% of a command and returns the corresponding |Lr| or |Mr| item to its -% caller. The syntax is -% \begin{quote} -% |parsetcl::parse_raw_word| \word{script} \word{index-var-name} -% \word{nested} -% \end{quote} -% where the arguments and call conventions are as for |parse_word|. -% \begin{tcl} -proc parsetcl::parse_raw_word {script index_var nested} { - upvar 1 $index_var index - set res [list] - set type Lr - set interval [list $index] - set text "" - while {1} { -% \end{tcl} -% Each iteration of this loop adds one subtree to |res| and the -% corresponding literate material to |text|. If some substitution -% happens which does not produce literate material then |type| is set -% to an |Mr|. -% \begin{tcl} - switch -- [string index $script $index] \\ { - if {[string index $script [expr {$index+1}]] eq "\n"} then { - break - } - lappend res [parse_backslash $script index] - append text [lindex $res end 2] - continue - } \$ { - lappend res [parse_dollar $script index] - set type Mr - continue - } \[ { - lappend res [parse_bracket $script index] - set type Mr - continue - } \t - \n - \v - \f - \r - " " - \; - "" { - break - } - if {$nested} then { - if {![ - regexp -start $index -- {\A[^\\$\[\]\t-\r ;]+} $script match - ]} then {break} - } else { - regexp -start $index -- {\A[^\\$\[\t-\r ;]+} $script match - } - set t $index - incr index [string length $match] - lappend res [list Lr [list $t [expr {$index - 1}]] $match] - append text $match - } -% \end{tcl} -% In case there is only a single element in |res| then that will be -% the result. -% \begin{tcl} - if {[llength $res]==1} then { - set res [lindex $res 0] - } else { - lappend interval [expr {$index - 1}] - if {$type ne "Lr"} then {set text ""} - set res [linsert $res 0 $type $interval $text] - } - flush_whitespace $script index 0 - return $res -} -% \end{tcl} -% \end{proc} -% -% -% \subsection{Parsing substitutions} -% -% \begin{proc}{parse_backslash} -% The |parse_backslash| procedure parses a backslash sequence and -% returns the corresponding |Sb| item. The syntax is -% \begin{quote} -% |parsetcl::parse_backslash| \word{script} \word{index-var-name} -% \end{quote} -% and it is assumed that the index character in \word{script} is the -% initial backslash in the sequence. Upon return, the index character -% is the first character after the backslash sequence. -% \begin{tcl} -proc parsetcl::parse_backslash {script index_var} { - upvar 1 $index_var index - set start $index - incr index - set ch [string index $script $index] - set res [list Lr [list $index $index] $ch] - switch -- $ch a { - set res [list Sb [list $start $index] \a $res] - } b { - set res [list Sb [list $start $index] \b $res] - } f { - set res [list Sb [list $start $index] \f $res] - } n { - set res [list Sb [list $start $index] \n $res] - } r { - set res [list Sb [list $start $index] \r $res] - } t { - set res [list Sb [list $start $index] \t $res] - } v { - set res [list Sb [list $start $index] \v $res] - } x { - if {[regexp -start [expr {$index + 1}] -- {\A[0-9A-Fa-f]+}\ - $script match]} then { - scan [string range $match end-1 end] %x code - incr index [string length $match] - lset res 1 1 $index - lset res 2 "x$match" - set res [list Sb [list $start $index]\ - [format %c $code] $res] - } else { - set res [list Sb [list $start $index] x $res] - } - } u { - if {[regexp -start [expr {$index + 1}] -- {\A[0-9A-Fa-f]{1,4}}\ - $script match]} then { - scan $match %x code - incr index [string length $match] - lset res 1 1 $index - lset res 2 "u$match" - set res [list Sb [list $start $index]\ - [format %c $code] $res] - } else { - set res [list Sb [list $start $index] u $res] - } - } \n { - regexp -start [expr {$index + 1}] -- {\A[ \t]*} $script match - incr index [string length $match] - lset res 1 1 $index - lset res 2 "\n$match" - set res [list Sb [list $start $index] " " $res] - } "" { - return [list Sb [list $start $start] \\] - } default { - if {[regexp -start $index -- {\A[0-7]{1,3}} $script match]} then { - scan $match %o code - incr index [expr {[string length $match]-1}] - lset res 1 1 $index - lset res 2 $match - set res [list Sb [list $start $index] [format %c $code] $res] - } else { - set res [list Sb [list $start $index] $ch $res] - } - - } - incr index - return $res -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{parse_bracket} -% The |parse_bracket| procedure parses one pair of command -% substitution brackets and returns the corresponding |Sc| item. -% The syntax is -% \begin{quote} -% |parsetcl::parse_bracket| \word{script} \word{index-var-name} -% \end{quote} -% and it is assumed that the index character in \word{script} is the -% initial bracket in the sequence. Upon return, the index character -% is the first character after the close-bracket. -% \begin{tcl} -proc parsetcl::parse_bracket {script index_var} { - upvar 1 $index_var index - set res [list Sc [list $index ""] ""] - incr index - while {[lindex [set next [parse_command $script index 1]] 0] ne "Np"} { - lappend res $next - } - if {[string index $script $index] eq "\]"} then { - lset res 1 1 $index - incr index - return $res - } else { - lappend res [list Ne [list $index [expr {$index-1}]]\ - {missing close-bracket}] - lset res 1 1 [expr {$index-1}] - return $res - } -} -% \end{tcl} -% \end{proc} -% -% \begin{variable}{varname_RE} -% The |varname_RE| is the regular expression used with |$| -% substitution for grabbing the name of the variable. -% \begin{tcl} -set parsetcl::varname_RE {\A(\w|::)+} -% \end{tcl} -% The reason for factoring this out into a variable is that -% \Tcllogo\ isn't using the natural (Unicode) definition of an -% alphanumeric character here, but relies on a locale-dependent -% C~library function to perform this test. They generally agree on -% ASCII characters, but outside that one probably cannot rely on that -% the test produces sensible results. Hence if a script needs to be -% parsed where some non-Unicode behaviour of this library function is -% significant, then you might need to change the above regexp. -% -% There is a \Tcllogo\ bug report~\cite{Letter-bug} on the matter, -% and hopefully there will be no need to ever change this regexp -% once that has been resolved. -% \end{variable} -% -% \begin{proc}{parse_dollar} -% The |parse_dollar| procedure parses one |$|-sequence and returns -% the corresponding |Sv|, |Sa|, or |Lr| item. The syntax is -% \begin{quote} -% |parsetcl::parse_dollar| \word{script} \word{index-var-name} -% \end{quote} -% and it is assumed that the index character in \word{script} is the -% initial |$| in the sequence. Upon return, the index character -% is the first character after the parsed sequence. -% \begin{tcl} -proc parsetcl::parse_dollar {script index_var} { - upvar 1 $index_var index - set res [list "" [list $index ""] ""] - incr index -% \end{tcl} -% If the first character after the |$| is a left brace, then the -% variable is scalar and its name is terminated by the next right -% brace. Note that braces do not nest in this case. -% \begin{tcl} - if {[string index $script $index] eq "\{"} then { - lset res 0 Sv - set end [string first \} $script $index] - if {$end<0} then { - set end [expr {[string length $script] - 1}] - lappend res [list Lb [list $index $end]\ - [string range $script [expr {$index + 1}] end]]\ - [list Ne [list [expr {$end+1}] $end]\ - {missing close-brace for variable name}] - } else { - lappend res [list Lb [list $index $end]\ - [string range $script [expr {$index + 1}] [expr {$end-1}]]] - } - lset res 1 1 $end - set index [expr {$end + 1}] - return $res - } -% \end{tcl} -% Otherwise see if there is something which can be interpreted as an -% alphanumeric variable name. First treat the case when there isn't; -% in that case the |$| is just a literate |$| and it is returned as an -% |Lr| iterm. Then treat the case that the variable is scalar. -% \begin{tcl} - variable varname_RE - if {![regexp -start $index -- $varname_RE $script match]} then { - if {[string index $script $index] eq "("} then { - set match "" - } else { - return [list Lr [list [lindex $res 1 0] [lindex $res 1 0]] \$] - } - } - set t $index - incr index [string length $match] - lappend res [list Lr [list $t [expr {$index-1}]] $match] - if {[string index $script $index] ne "("} then { - lset res 0 Sv - lset res 1 1 [lindex $res 3 1 1] - return $res - } -% \end{tcl} -% What remains is to treat the case of an array variable. This is -% very much like |parse_quoted_word|, but it is the right parenthesis -% rather than |"| that acts as terminator. -% \begin{tcl} - lset res 0 Sa - incr index - set subres [list Lr [list $index ""] ""] - lappend res "" - set text "" - while {1} { -% \end{tcl} -% Each iteration of this loop adds one subtree to |subres| and the -% corresponding literate material to |text|. If some substitution -% happens which does not produce literate material then the |Lr| -% in |subres| is changed to an |Mr|. -% \begin{tcl} - switch -- [string index $script $index] \\ { - lappend subres [parse_backslash $script index] - append text [lindex $subres end 2] - } \$ { - lappend subres [parse_dollar $script index] - lset subres 0 Mr - } \[ { - lappend subres [parse_bracket $script index] - lset subres 0 Mr - } ) { - lset subres 1 1 [expr {$index - 1}] - break - } "" { - lappend res\ - [list Ne [list $index [incr index -1]] {missing )}] - lset subres 1 1 $index - break - } default { - regexp -start $index -- {[^\\$\[)]*} $script match - set t $index - incr index [string length $match] - lappend subres [list Lr [list $t [expr {$index - 1}]] $match] - append text $match - } - } - if {[lindex $subres 0] eq "Lr"} then {lset subres 2 $text} - if {[llength $subres] == 4} then {set subres [lindex $subres 3]} - lset res 1 1 $index - incr index - lset res 4 $subres - return $res -} -% \end{tcl} -% \end{proc} -% -% -% -% \section{Some utility procdures} -% -% \subsection{Viewing parser trees} -% -% It is useful to have a surveyable presentation of parser trees. An -% easy step towards this would be to ensure that nesting depth is -% mirrored in the indentation. -% -% \begin{proc}{format_tree} -% The |format_tree| procedure takes a parser tree, a base indentation -% (string of whitespace), and an indentation step (string of whitespace) -% as argument. It returns a string that is list-wise equivalent to -% |[list]| of the original tree, but has indentation mirroring the -% nesting depth. -% \begin{tcl} -proc parsetcl::format_tree {tree base step} { - set res $base - append res \{ [lrange $tree 0 1] { } -% \end{tcl} -% The following is a trick to make a list element string -% representation for the \word{text} that does not contain any sort -% of newline: making the element unbalanced with respect to braces -% forces escape-quoting also for newlines. -% \begin{tcl} - if {[regexp {[\n\r]} [lindex $tree 2]]} then { - append res [string range [list "[lindex $tree 2]\{"] 0 end-2] - } else { - append res [lrange $tree 2 2] - } - if {[llength $tree]<=3} then { - append res \} - return $res - } elseif {[llength $tree] == 4 &&\ - [string match {S[bv]} [lindex $tree 0]]} then { -% \end{tcl} -% This is a slight optimization: |Sb| and |Sv| trees look better on -% one line than on three. -% \begin{tcl} - append res " " [format_tree [lindex $tree 3] "" ""] \} - return $res - } - append res \n - foreach subtree [lrange $tree 3 end] { - append res [format_tree $subtree $base$step $step] \n - } - append res $base \} -} -% \end{tcl} -% \end{proc} -% -% -% \subsection{Offsetting intervals} -% -% \begin{proc}{offset_intervals} -% This procedure modifies a \word{tree} by adding \word{offset} to -% all endpoints of each interval in that tree, and returns the -% modified tree. The syntax is -% \begin{quote} -% |parsetcl::offset_intervals| \word{tree} \word{offset} -% \end{quote} -% \begin{tcl} -proc parsetcl::offset_intervals {tree offset} { - set res [lrange $tree 0 2] - foreach i {0 1} { - lset res 1 $i [expr {[lindex $res 1 $i] + $offset}] - } - foreach subtree [lrange $tree 3 end] { - lappend res [offset_intervals $subtree $offset] - } - return $res -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{reparse_Lb_as_script} -% The |reparse_Lb_as_script| procedure replaces an |Lb| node from an -% existing parser tree with the |Rs| node produced by parsing the text -% between the braces as a script. The syntax is -% \begin{quote} -% |parsetcl::reparse_Lb_as_script| \word{tree-var} \word{node-index} -% \word{parsed string} -% \end{quote} -% where \word{tree-var} is the name in the caller's local context of -% the variable in which the tree to substitute is stored and -% \word{node-index} is the index list of the node to replace. The -% procedure returns |2| if the node was an |Lb| node, |1| if is was -% an |Lr| or |Lq| node, and |0| if the node was not of any of these -% types. In the last case, the tree is not modified. In the case that -% |1| is returned, the node has been substituted, but the intervals -% may be slightly off since the string to parse was taken from the -% \word{text} part of the substituted node. The normal case is that |2| -% is returned, and in this case the intervals unambiguously refer to -% positions in the \word{parsed string}. -% \begin{tcl} -proc parsetcl::reparse_Lb_as_script {tree_var index parsed} { - upvar 1 $tree_var tree - set node [lindex $tree $index] - switch -- [lindex $node 0] Lb - Lr - Lq { - set base [expr {[lindex $node 1 0] + 1}] - if {[lindex $node 0] eq "Lb"} then { - set script [string range $parsed $base\ - [expr {[lindex $node 1 1] - 1}]] - } else { - set script [lindex $node 2] - } - lset tree $index\ - [offset_intervals [basic_parse_script $script] $base] - if {[lindex $node 0] eq "Lb"} then { - return 2 - } else { - return 1 - } - } default { - return 0 - } -} -% \end{tcl} -% \end{proc} - - -% -% -% \subsection{Traversing parser trees} -% -% \begin{proc}{walk_tree} -% The |walk_tree| procedure has the syntax -% \begin{quote} -% |parsetcl::walk_tree| \word{tree-var} \word{index-var} -% \begin{regblock}[\regplus]\word{type-pattern} -% \word{body}\end{regblock} -% \end{quote} -% It walks through each node in the tree stored in the -% \word{tree-var} in the order that they appear in the string, i.e., -% first the root of a tree, then it walks through each subtree in -% sequence. When visiting a node, the type of the node is -% regexp-matched against the \word{type-pattern}s, and the first -% matching \word{body} is evaluated (entirely using |switch -regexp|) -% in the local context of the caller. While walking, the procedure is -% updating the \word{index-var} variable so that it always contains -% the index list specifying the current node in the tree. -% -% It is OK to modify the tree while walking through it, provided that -% the index list of the current node remains valid throughout. It is -% particular possible to change the contents of the current node (add -% or remove children) without messing things up. -% -% There is no particular return value from this procedure. -% \begin{tcl} -proc parsetcl::walk_tree {tree_var index_var args} { - upvar 1 $tree_var tree $index_var idxL - set idxL [list] - set i 0 - while {$i>=0} { - if {$i==0} then { - uplevel 1 [list switch -regexp --\ - [lindex [lindex $tree $idxL] 0] $args] - set i 3 - } elseif {$i < [llength [lindex $tree $idxL]]} then { - lappend idxL $i - set i 0 - } elseif {[llength $idxL]} then { - set i [lindex $idxL end] - set idxL [lrange $idxL 0 end-1] - incr i - } else { - set i -1 - } - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{simple_parse_script} -% The |simple_parse_script| procedure is similar to -% |basic_parse_script|, but it tries to recognise some common control -% structures (|if|, |for|, etc.) and reparses those arguments that -% (for standard command definitions) are scripts. The syntax is -% \begin{quote} -% |parsetcl::simple_parse_script| \word{script} -% \end{quote} -% and it returns the parsed script. -% \begin{tcl} -proc parsetcl::simple_parse_script {script} { - set tree [parsetcl::basic_parse_script $script] - walk_tree tree indices Cd { - switch -- [lindex [lindex $tree $indices] 3 2] if { - for {set i 3} {$i < [llength [lindex $tree $indices]]}\ - {incr i} { - switch -- [lindex [lindex $tree $indices] $i 2]\ - if - elseif { - incr i; continue - } then - else { - incr i - } - parsetcl::reparse_Lb_as_script tree\ - [linsert $indices end $i] $script - } - } while { - parsetcl::reparse_Lb_as_script tree [linsert $indices end 5]\ - $script - } for { - parsetcl::reparse_Lb_as_script tree [linsert $indices end 4]\ - $script - parsetcl::reparse_Lb_as_script tree [linsert $indices end 6]\ - $script - parsetcl::reparse_Lb_as_script tree [linsert $indices end 7]\ - $script - } foreach { - parsetcl::reparse_Lb_as_script tree [linsert $indices end end]\ - $script - } catch { - parsetcl::reparse_Lb_as_script tree [linsert $indices end 4]\ - $script - } proc { - parsetcl::reparse_Lb_as_script tree [linsert $indices end 6]\ - $script - } - } - return $tree -} -% \end{tcl} -% \end{proc} -% -% \section{Parsing expressions} -% -% This hasn't been implemented yet. -% -% -% \section{Advanced script parsing} -% -% Most of the meaning of a \Tcllogo\ script depends on its commands -% rather than being given by the syntax---there is e.g. nothing in the -% general syntax that makes the last argument of a |foreach| command -% more likely to contain a script than any of the other arguments---and -% therefore any higher level parsing of \Tcllogo\ scripts must employ a -% table of commands -% -% This hasn't been implemented yet. -% -% -% \section{Script reconstruction} -% -% This hasn't been implemented yet, but the parser trees contain -% the necessary information. Applications of script reconstruction -% includes writing a |proc|-like command that inlines code in the body -% argument before the procedure is created. -% -% -% \begin{thebibliography}{9} -% \bibitem{Letter-bug} -% Kevin B. Kenny and Jeffrey Hobbs: -% \textit{Dollar-substitution and non-Latin-1}, -% \Tcllogo~project bug \#408568 (2001, still open April~2003); -% \href{https://sourceforge.net/tracker/^^A -% ?func=detail&aid=408568&group_id=10894&atid=110894}^^A -% {\textsc{https}:/\slash \texttt{sourceforge.net}\slash -% \texttt{tracker}\slash -% \texttt{?func=detail\&}\penalty\exhyphenpenalty -% \texttt{aid=408568\&}\penalty\exhyphenpenalty -% \texttt{group\_id=10894\&}\penalty\exhyphenpenalty -% \texttt{atid=110894}.} -% -% \end{thebibliography} -% -\endinput
\ No newline at end of file diff --git a/Master/texmf-dist/source/latex/tcldoc/examples/parsetcl.ins b/Master/texmf-dist/source/latex/tcldoc/examples/parsetcl.ins deleted file mode 100644 index 645dc77f8a8..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/examples/parsetcl.ins +++ /dev/null @@ -1,54 +0,0 @@ -% parsetcl.ins --- DOCSTRIP installation script for parsetcl. -\input docstrip - -% Redefine the \MetaPrefix; it should be something which starts a -% until-end-of-line comment: -\edef\MetaPrefix{\string#\string#} - - -% Redefine the file preamble and postamble; this is necessary because -% otherwise the old \metaPrefix is inserted at the beginning of these -% lines. -\preamble - -In other words: - *************************************** - * This Source is not the True Source. * - *************************************** -The True Source is parsetcl.dtx in - http://ftp.ctan.org/tex-archive/macros/latex/contrib/tclldoc/examples - -It is preferred that you apply the distribution and modification -conditions of the LaTeX Project Public License (LPPL) for this file, -but you may alternatively choose to apply BSD/Tcl-style license -conditions (either is OK). The latest version of the LPPL is in - http://www.latex-project.org/lppl.txt -and version 1.2 or later is part of all distributions of LaTeX -version 1999/12/01 or later. - -\endpreamble - -\postamble -\endpostamble - - -% Actually make the files: -\generate{ - \file{parsetcl.tcl}{\from{parsetcl.dtx}{pkg}} -} - - -\Msg{} -\Msg{************************************************} -\Msg{*} -\Msg{* To complete installation,} -\Msg{* place parsetcl.tcl in a Tcl library directory} -\Msg{* and run pkg_mkIndex to rebuild the package} -\Msg{* index.} -\Msg{*} -\Msg{************************************************} -\Msg{} - - -\end - diff --git a/Master/texmf-dist/source/latex/tcldoc/examples/pdf.dtx b/Master/texmf-dist/source/latex/tcldoc/examples/pdf.dtx deleted file mode 100644 index 249a28ee6c3..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/examples/pdf.dtx +++ /dev/null @@ -1,796 +0,0 @@ -% -% \iffalse -%<*driver> -\documentclass{tclldoc} -\PageIndex\CodelineNumbered -\IndexPrologue{% - \section*{Index}% - All numbers in this index are page numbers. - Underlined entries refer to places where the item in - question is defined.% -} -\setcounter{IndexColumns}{2} -\begin{document} -\DocInput{pdf.dtx} -\end{document} -%</driver> -% \fi -% -% \title{A simple PDF writer in \Tcllogo} -% \author{Lars Hellstr\"om} -% \maketitle -% -% \begin{abstract} -% This file contains some basic routines that allow a \Tcllogo\ -% script to write PDF files. -% \end{abstract} -% -% \tableofcontents -% -% \section{PDF files and objects} -% -% A Portable Document Format (PDF) file is, when compared with for example -% a PostScript file or HTML file, a rather disorganised document. This -% is because at the basic level, a PDF file is a heap rather than a -% text; it \emph{can} be ``disorganised'' since its logical structure -% is based on cross-referencing rather than on sequentiality. The first -% step is therefore to provide support for writing well-formed heaps. -% -% \changes{0.0}{2003/01/02}{Initial version. (LH)} -% -% \begin{tcl} -%<*pkg> -package require Tcl 8.1 -package provide writepdf 0.1 -namespace eval pdf {} -% \end{tcl} -% \setnamespace{pdf} -% -% -% \subsection{Building objects} -% -% The independent units in a PDF file are called objects. An -% \emph{object} is essentially a value (which includes a type). The -% procedures below construct strings of PDF code that encode objects of -% various types. The strings returned are generally such that one must -% insert whitespace between two such strings if the data is to be -% properly encoded. The strings may contain newlines if some building -% routine thinks the lines should otherwise be too long. -% -% \begin{proc}{boolean_obj} -% The |boolean_obj| procedure returns a boolean object, corresponding -% to the string passed as its only argument. Most of it is about -% parsing this string: \texttt{true}, \texttt{yes}, \texttt{on}, and -% nonzero numbers are interpreted as boolean true, whereas -% \texttt{false}, \texttt{no}, \texttt{off}, and the zero number is -% interpreted as boolean false. The matching is case-insensitive. -% \begin{tcl} -proc pdf::boolean_obj {value} { - switch -nocase -- $value { - true - yes - on {return true} - false - no - off {return false} - default { - if {$value} then {return true} else {return false} - } - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{int_obj} -% The |int_obj| procedure returns the PDF object corresponding to -% the integer supplied as argument. -% \begin{tcl} -proc pdf::int_obj {value} {format %d $value} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{real_obj} -% \begin{variable}{precision} -% The |real_obj| procedure returns the PDF object corresponding to -% the real number supplied as argument. The syntax is -% \begin{quote} -% |pdf::real_obj| \word{value} \word{precision}\regopt -% \end{quote} -% where \word{precision} is the number of decimals that will be -% included in the object. If omitted, the value of the |precision| -% variable is used, and that defaults to $3$. -% \begin{tcl} -set pdf::precision 3 -proc pdf::real_obj {value {precision -1}} { - if {$precision<0} then { - unset precision - variable precision - } - format %.[format %d $precision]f $value -} -% \end{tcl} -% \end{variable}\end{proc} -% -% \begin{proc}{string_obj} -% The |string_obj| procedure returns the PDF string object -% corresponding to the argument. Backslashes and parentheses are -% escaped. Control characters are converted to escape sequences. -% Characters with character code above 255 cause an error to be -% thrown (PDF strings correspond more to \Tcllogo\ byte arrays than to -% general strings). If the string produced is longer than 100 -% characters, then backslash--newline sequences are inserted in -% suitable places. -% \begin{tcl} -proc pdf::string_obj {str} { - if {[regexp "\[^\n\r -\xff\]" $str]} then { - set estr [string map [list \\ \\\\ ( \\( ) \\) \r \\r \n \\n] $str] - set str "(" - set len 1 - foreach ch [split $estr {}] { - scan $ch %c code - if {$code==92} then { - append str \\ - incr len - continue - } elseif {$code<32} then { - append str "\\[format %03o $code]" - incr len 4 - } elseif {$code<256} then { - append str $ch - incr len - } else { - error "Bad character $ch [format (U+%04x) $code]\ - in PDF string." - } - if {$len > 100} then { - append str \\\n - set len 0 - } - } - append str ")" - } else { - set L [list] - while {[string length $str]>=100} { - lappend L [string map [list \\ \\\\ ( \\( ) \\) \r \\r \n \\n]\ - [string range $str 0 99]] - set str [string range $str 100 end] - } - if {[string length $str]} then { - lappend L\ - [string map [list \\ \\\\ ( \\( ) \\) \r \\r \n \\n] $str] - } - set str ([join $L \\\n]) - } - return $str -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{hexstring_obj} -% The |hexstring_obj| procedure returns the PDF string object, -% encoded as hexadecimal digits, that corresponds to the argument. -% If the string is longer than 31 characters then it will be broken -% on several lines. -% \begin{tcl} -proc pdf::hexstring_obj {str} { - set hstr "<" - set len 1 - foreach ch [split $str {}] { - scan $ch %c code - if {$len>=63} then { - append hstr \n - set len 0 - } - if {$code<256} then { - append hstr [format %02x $code] - incr len 2 - } else { - error "Bad character $ch [format (U+%04x) $code]\ - in PDF string." - } - } - append hstr ">" -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{text_obj} -% The |text_obj| procedure returns the PDF string object, encoded as -% hexadecimal digits, that corresponds to the argument string. This is -% meant to be used for \emph{text strings} -% (see~\cite[Ssec.~4.4.1]{PDFspec}), which are \Tcllogo-style strings -% rather than byte arrays. Text strings may contain general Unicode -% characters, although they will then be encoded using UTF-16BE. -% -% The implementation constructs the 8-bit and 16-bits encodings of the -% string in parallel, and only when it is done will it decide which to -% return. -% \begin{tcl} -proc pdf::text_obj {str} { - set hstr "<" - set ustr "<FEFF" - set lenh 1 - set lenu 5 - set eight_ok 1 - foreach {chh chl} [split [encoding convertto unicode $str] {}] { - scan $chh %c codeh - scan $chl %c codel - if {$lenu>=62} then { - append ustr \n - set lenu 0 - } - append ustr [format %02x%02x $codeh $codel] - incr lenu 4 - if {$codeh>0} then {set eight_ok 0} - if {!$eight_ok} then {continue} - if {$lenh>=63} then { - append hstr \n - set lenh 0 - } - append hstr [format %02x $codel] - incr lenh 2 - } - append hstr ">" - append ustr ">" - if {$eight_ok && ![string match {<feff*} $hstr]} then { - return $hstr - } else { - return $ustr - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{name_obj} -% The |name_obj| procedure returns the PDF name object corresponding -% to its argument. It is useful mainly for names with strange -% characters in them (such as spaces), but most names (e.g.\ dictionary -% keys) appearing in PDF files do not require any quoting and can -% therefore just as well be written as explicit PDF code. -% \begin{tcl} -proc pdf::name_obj {str} { - if {[string length $str]>126} then { - error "String too long to be a PDF name." - } - set res / - foreach ch [split $str {}] { - switch -glob -- $ch { - ( - ) - < - > - \\[ - \\] - \{ - \} - / - % - # { - scan $ch %c code - append res [format #%02x $code] - } - [!-~] {append res $ch} - default { - scan $ch %c code - append res [format #%02x $code] - } - } - } - return $res -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{array_obj} -% The |array_obj| procedure builds an array object of the objects it -% is given as arguments. The syntax is -% \begin{quote} -% |pdf::array_obj| \word{object}\regstar -% \end{quote} -% Newlines are inserted between the objects if it does not appear as -% if the object would fit on a single (100 character) line. -% \begin{tcl} -proc pdf::array_obj {args} { - set res \[ - set len 1 - foreach item $args { - if {[string length $item] + $len >= 100} then { - append res \n - set len 0 - } elseif {[string length $res]>1} then { - append res " " - incr len - } - append res $item - incr len [string length $item] - } - if {$len >= 100} then { - append res \n - } - append res \] -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{dict_obj} -% The |dict_obj| procedure builds a dictionary object from its -% arguments. The syntax is -% \begin{quote} -% |pdf::dict_obj| -% \begin{regexp}[\regstar]\word{key} \word{value}\end{regexp} -% \end{quote} -% where each \word{key} must be a name object and each \word{value} -% must be an object. It is checked that the number of elements is -% correct and that the keys begin with a slash. -% \begin{tcl} -proc pdf::dict_obj {args} { - if {[llength $args] % 2 != 0} then { - error "Not the same number of keys and values." - } - set res "<<\n" - foreach {key value} $args { - if {![string match {/*} $key]} then { - error "'$key' isn't a name object." - } - if {[string length $key] + [string length $value]>99} then { - append res $key \n $value \n - } else { - append res $key { } $value \n - } - } - append res ">>" -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{null_obj} -% The |null_obj| procedure returns a null object. It has no arguments. -% \begin{tcl} -proc pdf::null_obj {} {return null} -% \end{tcl} -% \end{proc} -% -% -% Objects can also be \emph{streams}, but those have a special relation -% to the file structure and are therefore best treated in conjunction -% with that. In particular, streams cannot be used as arguments of -% |array_obj| or |dict_obj|. The arguments of these procedures can -% however be \emph{indirect references} to objects of any type, but -% these too are best treated in the context of the basic PDF file -% structure. -% -% -% \subsection{File structure} -% -% The body of a PDF file consists of a sequence of \emph{indirect -% objects}, which are mainly a sort of declarations: a pair of integers -% are associated with an object value. Since any composite object can -% (and in several cases must) contain a reference to any indirect object, -% this makes it possible to build up arbitrary data structures. It is -% however also a complication, since it requires that there is a -% mechanism for allocating these numbers. -% -% \begin{arrayvar}{file\meta{fnum}} -% Every file that \Tcllogo\ opens gets a unique identifier which is -% used in calls to |puts| and such. This identifier is also used as -% the name of an array in the |pdf| namespace, in which the -% procedures below store all auxiliary information they need to create -% a proper PDF file. -% \end{arrayvar} -% -% \begin{arrayentry}{file\meta{fnum}}{!\meta{reference label}} -% \begin{arrayentry}{file\meta{fnum}}{last_object_num} -% In this API, references to indirect objects can be arbitrary -% strings, called \emph{reference labels}. The correspondence to the -% object numbers actually found in the file is given by the -% \texttt{!}\meta{reference label} entries in the array of the file in -% question. The entries in this array are lists with the structure -% \begin{quote} -% \word{object number} \word{generation number} \word{file -% position}\regopt -% \end{quote} -% where the \word{file position} is present only if the indirect -% object in question has been written to file already. The -% \word{object number} is the number of the object referred to. The -% \word{generation number} is currently always zero; it appears that -% it can only be nonzero for files that have incrementally updated, -% and this API only supports creating a file from scratch. The -% \word{file position} is the position in the file of the beginning -% of the indirect object begin referred to. -% -% The |last_object_num| entry in the array holds the most recently -% allocated object number. It is incremented whenever a new reference -% label is encountered. -% \end{arrayentry}\end{arrayentry} -% -% \begin{proc}{obj_ref} -% The |obj_ref| procedure returns PDF code for an indirect reference -% to an object. The syntax is -% \begin{quote} -% |pdf::obj_ref| \word{file} \word{reference label} -% \end{quote} -% where \word{file} is the indentifier of the PDF file in question. -% If the \word{reference label} has not been encountered before for -% this particular file, then a new object number is allocated for it. -% \begin{tcl} -proc pdf::obj_ref {F label} { - upvar #0 [namespace current]::$F A - if {![info exists A(!$label)]} then { - incr A(last_object_num) - set A(!$label) [list $A(last_object_num) 0] - } - format {%d %d R} [lindex $A(!$label) 0] [lindex $A(!$label) 1] -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{begin_stream} -% \begin{proc}{end_stream} -% The |begin_stream| and |end_stream| procedures delimit the creation -% of a \emph{stream object}. Between two such commands, it is possible -% to write arbitrary text (usually page descriptors or some sort of -% embedded data) to the PDF file and have it inserted correctly into -% the file as the data stored in the stream object. -% -% The syntax for |begin_stream| is -% \begin{quote} -% |pdf::begin_stream| \word{file} \word{reference label} -% \begin{regexp}[\regstar]\word{key} \word{value}\end{regexp} -% \end{quote} -% where \word{file} of course is the file to write to and -% \word{reference label} is the string that should be used to -% reference this object. Each stream consists of one dictionary part -% and one data part, where the primary task of the dictionary part is -% to specify how the data part should be interpreted. The most -% important element in the dictionary is the \texttt{/Length} key and -% its value---these are inserted by the |begin_stream| and -% |end_stream| commands, so one needs not worry about those---but if -% for example the data part is encoded in some special way (for -% example, it might be compressed) then it is necessary to include -% additional elements in the dictionary. This is what the \word{key} -% and \word{value} arguments are for. -% -% \begin{arrayentry}{file\meta{fnum}}{current_stream} -% The |current_stream| entry in a PDF file array is set if and only -% if the current position in that file is inside a stream. It is -% not possible to begin a new stream when this entry is set. The -% value of this entry is a list with the structure -% \begin{quote} -% \word{reference label} \word{start} -% \end{quote} -% where \word{reference label} is the reference label of the stream -% and \word{start} is the position in the file of the first byte in -% the stream data. Both of these are needed at |end_stream| to -% record the length of the stream data. -% \end{arrayentry} -% -% \begin{arrayentry}{file\meta{fnum}}{?\meta{reference label}} -% This kind of entry is used for indirect objects that are lengths -% of the stream whose reference label is the \meta{reference label}. -% They have the same syntax as their |!| ordinary counterparts. -% \end{arrayentry} -% -% \begin{tcl} -proc pdf::begin_stream {F label args} { - upvar #0 [namespace current]::$F A - if {[info exists A(current_stream)]} then { - error "There is already a stream ([lindex $A(current_stream) 0])\ - being written to in this file." - } - if {![info exists A(!$label)]} then { - incr A(last_object_num) - set A(!$label) [list $A(last_object_num) 0] - } - set A(?$label) [list [incr A(last_object_num)] 0] - lappend A(!$label) [tell $F] - puts $F\ - [format {%d %d obj} [lindex $A(!$label) 0] [lindex $A(!$label) 1]] - puts $F [eval\ - [list dict_obj /Length [format {%d 0 R} $A(last_object_num)]]\ - $args] - puts $F stream - set A(current_stream) [list $label [tell $F]] -} -% \end{tcl} -% -% The |end_stream| procedure takes the target file as its only argument. -% It finishes off the stream as necessary. It also evaluates -% everything that has been placed in the backlog of the file. -% -% \begin{arrayentry}{file\meta{fnum}}{backlog} -% It is not possible to output a new indirect object when a stream -% is being written to, but it can still be at such a time that the -% need for such an object is discovered. The |backlog| entry -% provides a way around that limitation---this entry is a script -% that is evaluated (and cleared) at the end of every |end_stream|, -% hence commands can be delayed by appending them to this script, -% instead of evaluating them immediately. -% -% New commands are appended to the |backlog|, and must be preceeded -% by a command separator. -% \end{arrayentry} -% -% \begin{tcl} -proc pdf::end_stream {F} { - upvar #0 [namespace current]::$F A - if {![info exists A(current_stream)]} then { - error "There is no stream to end." - } - set length [expr {[tell $F] - [lindex $A(current_stream) 1]}] - set label [lindex $A(current_stream) 0] - unset A(current_stream) - puts $F "endstream endobj" - lappend A(?$label) [tell $F] - puts $F [format {%d %d obj %d endobj} [lindex $A(?$label) 0]\ - [lindex $A(?$label) 1] $length] - eval "set A(backlog) {}; $A(backlog)" -} -% \end{tcl} -% \end{proc}\end{proc} -% -% \begin{proc}{put_obj} -% The |put_obj| procedure writes a direct object to a PDF file. The -% syntax is -% \begin{quote} -% |pdf::put_obj| \word{file} \word{reference label} \word{object} -% \end{quote} -% \begin{tcl} -proc pdf::put_obj {F label obj} { - upvar #0 [namespace current]::$F A - if {[info exists A(current_stream)]} then { - append A(backlog) \n [list put_obj $F $label $obj] - return - } - if {![info exists A(!$label)]} then { - incr A(last_object_num) - set A(!$label) [list $A(last_object_num) 0] - } - lappend A(!$label) [tell $F] - puts $F\ - [format {%d %d obj} [lindex $A(!$label) 0] [lindex $A(!$label) 1]] - puts $F $obj - puts $F endobj -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{rewrite_pdf} -% The |rewrite_pdf| procedure opens a new PDF file for writing and -% initialises the associated data structures. The syntax is -% \begin{quote} -% |pdf::rewrite_pdf| \word{file name} \meta{options} -% \end{quote} -% and the return value is the identifier of the file opened. The -% \word{file name} is of course the name of that file. The -% \meta{options} is zero or more of -% \begin{quote} -% |-permissions| \word{integer}\\ -% |-header| \word{string} -% \end{quote} -% The permissions are the default permissions for the file in question. -% If this is not specified, then no such value is specified to |open|, -% The header is a string that will be put first in the file (as header). -% It defaults to -% \begin{quote} -% \texttt{\%PDF-1.3}\\ -% \texttt{\%\r{a}\"a\"o} -% \end{quote} -% where the first line is a standard header line, and the second line -% is there to help some software understand that the file should be -% treated as a binary file. \textbf{Note} that no newline is inserted -% after this string; be sure to include it in the string if necessary. -% \begin{tcl} -proc pdf::rewrite_pdf {name args} { - set Opt(-header) %PDF-1.3\n%\xe5\xe4\xf6\n - array set Opt $args - if {[info exists Opt(-permissions)]} then { - set F [open $name w $Opt(-permissions)] - } else { - set F [open $name w] - } - fconfigure $F -translation binary - puts -nonewline $F $Opt(-header) - upvar #0 [namespace current]::$F A - array unset A - set A(last_object_num) 0 - set A(backlog) "" - return $F -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}{close_pdf} -% The |close_pdf| procedure performs the non-trivial task of finishing -% off the PDF file and closing it. The syntax is -% \begin{quote} -% |pdf::close_pdf| \word{file} \word{catalog label} -% \begin{regexp}[\regstar]\word{key} \word{value}\end{regexp} -% \end{quote} -% and the return value is a report detailing any problems -% encountered (such as objects that are referred to but never -% defined). This is a report rather than an error, because there is -% in many cases no sharp distinction. If the return value is -% non-empty, then there is probably a bug in your program that needs -% to be fixed. -% -% The \word{file} is the identifier of the file to write. The -% \word{catalog label} is the reference label of the Catalog object -% in the document. The remaining arguments can be used to insert -% additional information (such as a reference to the Info dictionary -% of the document) in the trailer dictionary. -% -% \begin{tcl} -proc pdf::close_pdf {F label args} { - upvar #0 [namespace current]::$F A - set reportL [list] -% \end{tcl} -% The first step is to compile the cross-reference table of the -% document. I originally made one subsection for each range of defined -% indirect objects, giving the mandatory free entry \#0 a separate -% subsection, but for some reason Adobe software didn't like that at -% all.\footnote{Whether this means Adobe isn't following their own -% standard I leave to others to decide. Neither GhostScript nor -% Quartz (the PDF-based graphics system in Mac~OS~X) seemed to have -% any problems with this arrangement.} Hence the current -% implementation is to make a cross-reference table with only one -% subsection, with an explicit free entry for every missing item. -% -% \changes{0.1}{2003/02/24}{Changed cross-reference section to avoid -% what is probably a bug in Adobe PDF readers. (LH)} -% -% The |xrA| array constructed below is a prototype for the -% cross-reference section. It is indexed by object number and the -% entries have the list structure -% \begin{quote} -% \word{file position} \word{generation number} \word{type} -% \end{quote} -% Just as in a PDF file, the \word{type} is either \texttt{f} or -% \texttt{n} depending on whether the entry is ``free'' or -% ``in use''. The \word{file position} and \word{generation number} -% are however not padded with zeros, and the \word{file position} is -% initially an empty string in the ``free'' entries. -% -% This first round simply collects the information and detects -% collisions. -% \begin{tcl} - set xrA(0) [list "" 65535 f] - foreach lbl [array names A {[!?]*}] { - set idx [lindex $A($lbl) 0] - set ent [list [lindex $A($lbl) 2] [lindex $A($lbl) 1] n] - if {[llength $A($lbl)]<3} then { - lappend reportL "There is no indirect object with label:\ - [string range $lbl 1 end]" - set ent [replace $ent 2 2 f] - } elseif {[llength $A($lbl)]>3} then { - lappend reportL "Multiple indirect objects for label\ - [string range $lbl 1 end]; at\ - [join [lrange $A($lbl) 2 end]]." - } - if {![info exists xrA($idx)]} then { - set xrA($idx) $ent - } elseif {[lindex $xrA($idx) 2]=="f" && [lindex $ent 2]=="n"}\ - then { - lappend reportL "This shouldn't happen:\ - There are several reference labels for\ - indirect object $idx. Using that with label:\ - [string range $lbl 1 end]" - set xrA($idx) $ent - } else { - lappend reportL "This shouldn't happen:\ - There are several reference labels for\ - indirect object $idx. Ignoring that with label:\ - [string range $lbl 1 end]" - } - } -% \end{tcl} -% The second round makes sure that there is a contiguous sequence of -% reference numbers and constructs the linked list of free entries. -% \begin{tcl} - set last_free 0 - set maxidx [lindex [lsort -integer -decreasing [array names xrA]] 0] - for {set n $maxidx} {$n>=0} {incr n -1} { - if {![info exists xrA($n)]} then { - set xrA($n) [list "" 0 f] - lappend reportL "This shouldn't happen:\ - Object number $n was allocated, but not\ - assigned a reference label." - } - if {[lindex $xrA($n) 2]=="f"} then { - set xrA($n) [lreplace $xrA($n) 0 0 $last_free] - set last_free $n - } - } -% \end{tcl} -% Now the cross-reference section can be written to file. -% \begin{tcl} - set startxref [tell $F] - puts $F xref - puts $F [format {%d %d} 0 [expr {$maxidx + 1}]] - for {set n 0} {$n<=$maxidx} {incr n} { - puts $F [eval [list format {%010d %05d %1s }] $xrA($n)] - } -% \end{tcl} -% Having completed the cross-reference table, the second step is -% to write the trailer. -% \begin{tcl} - puts $F trailer - if {[info exists A(!$label)]} then { - lappend args /Root [format {%d %d R} [lindex $A(!$label) 0]\ - [lindex $A(!$label) 1]] - } else { - lappend reportL "ERROR: The document does not have a catalog."\ - "There is no indirect object with label: $label" - } - lappend args /Size [array size xrA] - puts $F [eval [list dict_obj] $args] - puts $F "startxref\n${startxref}\n%%EOF" -% \end{tcl} -% The final step is to close the file and compile the report. -% \begin{tcl} - close $F - join $reportL \n -} -%</pkg> -% \end{tcl} -% \end{proc} -% -% -% \subsection{Hello World} -% -% The code below creates a PDF file matching the basic ``Hello World'' -% example \cite[Sec.~A.2]{PDFspec}. -% -% \begin{tcl} -%<*example1> -set F [pdf::rewrite_pdf hello.pdf] -pdf::put_obj $F "The catalog" [pdf::dict_obj\ -% - /Type /Catalog\ -% - /Pages [pdf::obj_ref $F "The pages"]\ -% - /Outlines [pdf::obj_ref $F "The outlines"]] -pdf::put_obj $F "The outlines"\ - [pdf::dict_obj /Type /Outlines /Count [pdf::int_obj 0]] -pdf::put_obj $F "The pages" [pdf::dict_obj\ -% - /Type /Pages\ -% - /Count [pdf::int_obj 1]\ -% - /Kids [pdf::array_obj [pdf::obj_ref $F "Page 1"]]] -pdf::put_obj $F "Page 1" [pdf::dict_obj\ -% - /Type /Page\ -% - /Parent [pdf::obj_ref $F "The pages"]\ -% - /Resources [pdf::dict_obj\ -% - /Font [pdf::dict_obj /F1 [pdf::obj_ref $F "Helvetica"]]\ -% - /ProcSet [pdf::obj_ref $F "The procs"]]\ -% - /MediaBox [pdf::array_obj [pdf::int_obj 0] [pdf::int_obj 0]\ - [pdf::int_obj 612] [pdf::int_obj 792]]\ -% - /Contents [pdf::obj_ref $F "Page 1 contents"]] -pdf::begin_stream $F "Page 1 contents" -puts $F {BT} -puts $F {/F1 24 Tf} -puts $F {100 100 Td (Hello World) Tj} -puts $F {ET} -pdf::end_stream $F -pdf::put_obj $F "The procs" [pdf::array_obj /PDF /Text] -pdf::put_obj $F "Helvetica" [pdf::dict_obj\ - /Type /Font /Subtype /Type1\ - /Name /F1 /BaseFont /Helvetica /Encoding /MacRomanEncoding] -pdf::close_pdf $F "The catalog" -%</example1> -% \end{tcl} -% -% -% \begin{thebibliography}{9} -% \bibitem{PDFspec} -% Adobe Systems Incorporated: -% \textit{Portable Document Format Reference Manual}, -% version~1.3 (second edition), Addison--Wesley, 1999; -% ISBN 0-201-61588-6; -% \textsc{http:}/\slash \texttt{partners.adobe.com}\slash -% \texttt{asn}\slash \texttt{developer}\slash \texttt{acrosdk}\slash -% \texttt{docs}\slash \texttt{filefmtspecs}\slash -% \texttt{PDFReference13.pdf}. -% \emph{Note:} There is now a version~1.4 of this specification. -% \end{thebibliography} -% -% \PrintIndex -% -% -\endinput
\ No newline at end of file diff --git a/Master/texmf-dist/source/latex/tcldoc/examples/pdf.ins b/Master/texmf-dist/source/latex/tcldoc/examples/pdf.ins deleted file mode 100644 index 00bea9f775e..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/examples/pdf.ins +++ /dev/null @@ -1,55 +0,0 @@ -% pdf.ins --- DOCSTRIP installation script for writepdf. -\input docstrip - -% Redefine the \MetaPrefix; it should be something which starts a -% until-end-of-line comment: -\edef\MetaPrefix{\string#\string#} - - -% Redefine the file preamble and postamble; this is necessary because -% otherwise the old \metaPrefix is inserted at the beginning of these -% lines. -\preamble - -In other words: - *************************************** - * This Source is not the True Source. * - *************************************** -The True Source is pdf.dtx in - http://ftp.ctan.org/tex-archive/macros/latex/contrib/tclldoc/examples - -It is preferred that you apply the distribution and modification -conditions of the LaTeX Project Public License (LPPL) for this file, -but you may alternatively choose to apply BSD/Tcl-style license -conditions (either is OK). The latest version of the LPPL is in - http://www.latex-project.org/lppl.txt -and version 1.2 or later is part of all distributions of LaTeX -version 1999/12/01 or later. - -\endpreamble - -\postamble -\endpostamble - - -% Actually make the files: -\generate{ - \file{writepdf.tcl}{\from{pdf.dtx}{pkg}} - \file{hellopdf.tcl}{\from{pdf.dtx}{example1}} -} - - -\Msg{} -\Msg{************************************************} -\Msg{*} -\Msg{* To complete installation,} -\Msg{* place pdfwrite.tcl in a Tcl library directory} -\Msg{* and run pkg_mkIndex to rebuild the package} -\Msg{* index.} -\Msg{*} -\Msg{************************************************} -\Msg{} - - -\end - diff --git a/Master/texmf-dist/source/latex/tcldoc/pstokens.dtx b/Master/texmf-dist/source/latex/tcldoc/pstokens.dtx deleted file mode 100644 index 26f2a71e28b..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/pstokens.dtx +++ /dev/null @@ -1,979 +0,0 @@ -% -% \iffalse -%<*driver> -\documentclass{tcldoc} - -\usepackage{array} - - -% Logos: -% -\DeclareFontFamily{U}{logo}{} -\DeclareFontShape{U}{logo}{m}{n}{ - <-9> logo8 - <9-10> logo9 - <10-> logo10 -}{} -\DeclareFontShape{U}{logo}{bx}{n}{<-> logobf10}{} -\DeclareFontShape{U}{logo}{b}{n}{<-> ssub * logo/bx/n}{} -\DeclareFontShape{U}{logo}{m}{sl}{<-> logosl10}{} -\DeclareFontShape{U}{logo}{m}{it}{<-> ssub * logo/m/sl}{} - -% \DeclareRobustCommand\META{{% -% \fontencoding{U}\fontfamily{logo}\selectfont META% -% }} -\DeclareRobustCommand\MF{% - {\fontencoding{U}\fontfamily{logo}\selectfont META}\-% - {\fontencoding{U}\fontfamily{logo}\selectfont FONT}% -} -\DeclareRobustCommand\MP{% - {\fontencoding{U}\fontfamily{logo}\selectfont META}\-% - {\fontencoding{U}\fontfamily{logo}\selectfont POST}% -} -\DeclareRobustCommand\PS{PostScript} -\DeclareRobustCommand\TOne{Type~1} -\DeclareRobustCommand\package[1]{\textsf{#1}} - - -% Useful environments: -% -% \begin{environment}{isyntax} -% |isyntax| is for ``informal'' syntax specifications, such as -% \begin{quote} -% A \meta{varchar command} can be one of\\ -% \begin{quote} -% |\vartop|\marg{glyph}\\ -% |\varmid|\marg{glyph}\\ -% |\varbot|\marg{glyph}\\ -% |\varrep|\marg{glyph} -% \end{quote} -% \end{quote} -% The implementation is based on that of the \texttt{verse} -% environment.It usually works just as fine with \texttt{quote}, but -% \texttt{isyntax} handles breaking long lines better (and more -% elegantly). -% \changes{1.37}{2000/05/14}{Increased \cs{rightskip} stretchability -% and added setting of \cs{linepenalty}. (LH)} -% \begin{macrocode} -\makeatletter -\newenvironment{isyntax}{% - \let\\\@centercr - \list{}{% - \itemsep \z@ - \itemindent -1.5em% - \listparindent \itemindent - \advance \leftmargin 1.5em% - }% - \advance \rightskip \z@\@plus0.7\linewidth \relax - \linepenalty=100\relax - \item\relax -}{\endlist} -\makeatother -% \end{macrocode} -% \end{environment} - - -% Tabular notes: -\makeatletter -\newcommand\tabnotemark[1]{% - \leavevmode - \ifhmode\edef\@x@sf{\the\spacefactor}\nobreak\fi - \hbox{\@textsuperscript{% - \normalfont\itshape - \count@=#1\relax\@alph\count@ - }}% - \ifhmode\spacefactor\@x@sf\fi - \relax -} -\newenvironment{tabnotes}{% - \list{\the\c@mpfootnote}{% - \usecounter{mpfootnote}% - \def\makelabel##1{\hfil\tabnotemark{##1}}% - \normalfont\footnotesize - \setlength\leftmargin{0pt}% - \setlength\labelsep{0pt}% - \setlength\labelwidth{1.8em}% - \setlength\itemindent{\labelwidth}% - \setlength\listparindent{1em}% - \setlength\parsep{0pt plus 1pt}% - \setlength\itemsep{\parsep}% - \setlength\topsep{\footnotesep}% - }% -}{\endlist} -\makeatother - - -\CodelineIndex - -\title{\texttt{pstokens.dtx}} -\author{Lars Hellstr\"om} -\date{Work in progress} -\begin{document} -\maketitle - -\DocInput{pstokens.dtx} - -\end{document} -%</driver> -% \fi -% -% \begin{abstract} -% \package{pstokens} is a collection of utility routines for -% \Tcllogo\ programs that need to view a file as a sequence of -% \PS\ tokens rather than as a sequence of characters or lines. -% \end{abstract} -% -% -% \setnamespace{pstokens} -% -% First of all, the \texttt{pstokens} namespace must be defined. -% \begin{tcl} -namespace eval pstokens {} -% \end{tcl} -% -% \section{Reading and writing tokens} -% -% This section contains the routines for reading a text file as a -% sequence of tokens (tokenizing) and writing a sequence of tokens -% to a text file (detokenizing). -% -% -% \subsection{Data structures for tokens} -% -% A \emph{token} is a \Tcllogo\ list with the format -% \begin{quote} -% \word{type} \word{data}\regstar -% \end{quote} -% The interpretation of the \word{data} depends on what the \word{type} -% is, as specified below. Some of the token types only occur internally -% in the tokenizer and some others have no meaning to a \PS\ interpreter, -% but this organisation seems to be the most convenient here. -% -% A primary goal for the format of tokens is that if a sequence of -% tokens are read from one file and written to another then the only -% things that may have changed should be the whitespace between the -% tokens, not the tokens themselves. Therefore the tokenizer generally -% avoids interpreting the tokens any more than necessary; -% interpretation of tokens is instead handled in the next section. -% -% The token types that occur in \package{pstokens} are -% \begin{description} -% \item[\texttt{number}, \texttt{radixnumber}] -% \describestring[token type]{number} -% \describestring[token type]{radixnumber} -% A number (integer or real), and radix number, respectively. There -% is one \word{data} item, which contains the string that -% represented the number in the tokenized text. -% \item[\texttt{string}, \texttt{hexstring}, \texttt{base-85}] -% \describestring[token type]{string} -% \describestring[token type]{hexstring} -% \describestring[token type]{base-85} -% A parenthesis-delimited string, hexadecimal string, and ASCII -% base-85 string, respectively. There is one \word{data} item, -% which contains the string (minus delimiters) that represented -% the string in the tokenized text. -% \item[\texttt{executable}, \texttt{literal}, \texttt{immediate}] -% \describestring[token type]{executable} -% \describestring[token type]{literal} -% \describestring[token type]{immediate} -% An executable (normal), literal, and immediately evaluated name -% respectively. There is one \word{data} item, which simply contains -% the name as a \Tcllogo\ string, not including any initial slashes. -% \item[\texttt{procedure}] -% \describestring[token type]{procedure} -% An executionable array. The data is simply the sequence of tokens -% in the array. -% \item[\texttt{comment}] -% \describestring[token type]{comment} -% This is not a \PS\ token at all, but a representation of a -% comment. The reason comments are tokenized is that they often -% contain interesting information (especially structured comments). -% The structure of this kind of token is -% \begin{quote} -% |comment| \word{head} \word{tail} -% \end{quote} -% The \word{head} is the part of the line which is after the |%| -% that started the comment and before the first whitespace character -% after it. The \word{tail} is the rest of the line (including the -% whitespace character, if there is one). Any of \word{head} and -% \word{tail} may be empty. The structured comment -% \begin{quote} -% |%%Pages: 2| -% \end{quote} -% would have \word{head} equal to \verb*"%Pages:" and \word{tail} -% equal to \verb*" 2". -% \item[\texttt{eof}] -% \describestring[token type]{eof} -% This is a pseudotoken which denotes that the end of the file was -% reached while looking for the next token. There structure is -% \begin{quote} -% |eof| \word{token}\regopt -% \end{quote} -% If the \word{token} is present then it is a composite token which -% was being read when the file unexpectedly ended. It is an error -% if the \word{token} is present. -% \item[\texttt{special}] -% \describestring[token type]{special} -% This token type can be used to extend the token type syntax -% without having to change the actual routines for reading and -% writing tokens. The structure of a |special| token is -% \begin{quote} -% |special| \word{token} \word{extra data}\regstar -% \end{quote} -% If a |special| token gets sent to the token writer then it will be -% treated as the token \word{token} (which usually has another -% type), but other routines may treat it differently based on the -% information in the \word{extra data}. -% \item[\texttt{error}] -% \describestring[token type]{error} -% A token of this type is returned from the tokenizer whenever it -% encounters anything which is syntactically incorrect. The -% general structure of this kind of token is -% \begin{quote} -% |error| \word{error type} \word{data}\regstar -% \end{quote} -% where the \word{error type} more precisely specifies the error. -% So far, the following error types are used -% \begin{quote} -% |error| |extra| \word{string} \word{line no.}\\ -% |error| |missing| \word{string} \word{line no.}\\ -% |error| |missing/extra| \word{m-string} \word{e-string} -% \word{line no.} -% \end{quote} -% |extra| means that there is an occurence of \word{string} which -% shouldn't have been there, whereas |missing| means that there -% should have been a \word{string} there, but isn't. |missing/extra| -% is the combination that there either should have been an -% \word{m-string} there, but isn't, or there is an \word{e-string} -% there, but there shouldn't be. -% \word{line no.} is the line on which the error was encountered. -% \end{description} -% -% -% \subsection{Reading tokens} -% -% \begin{arrayvar}{input_line}[file-id] -% \begin{arrayvar}{input_line_no}[file-id] -% Since the |gets| procedure always reads an entire line (which -% usually contain several tokens) each time it is used, it is -% necessary to store the most recently read line somewhere. This is -% the purpose of the |input_line| array, which is indexed by the file -% id. In general, text is removed from the entires in |input_line| as -% it is tokenized. -% -% The |input_line_no| array stores the number of the line in the -% corresponding |input_line| entry. The first line in a file has -% number one. -% \end{arrayvar}\end{arrayvar} -% -% \begin{proc}{open_input} -% \begin{proc}{close_input} -% These procedures are wrappers around \Tcllogo's |open| and |close| -% procedures respectively which additionally initialize and unset the -% relevant entry of the |input_line| and |input_line_no| arrays. Thus -% their syntaxes are -% \begin{quote} -% |pstokens::open_input| \word{file-name} \word{access}\regopt\ -% \word{permissions}\regopt\\ -% |pstokens::close_input| \word{file-id} -% \end{quote} -% and they return the same things as |open| and |close| respectively. -% -% A possible development of tokenizer is to implement filtered input, -% in which case more support data structures would have to be -% initialized, but then the |open_input| and |close_input| procedures -% would be redefined to cope with this. -% \begin{tcl} -%<*tokenio> -proc pstokens::open_input {args} { - set res [eval open $args] - global pstokens::input_line pstokens::input_line_no - set pstokens::input_line($res) "" - set pstokens::input_line_no($res) 0 - return $res -} -% \medskip -proc pstokens::close_input {file_id} { - global pstokens::input_line pstokens::input_line_no - unset pstokens::input_line($file_id) - unset pstokens::input_line_no($file_id) - close $file_id -} -% \end{tcl} -% \end{proc}\end{proc} -% -% The tokenizer has a couple of extra internal token types for things -% which later become parts of other tokens. -% \begin{description} -% \item[\texttt{beginproc}, \texttt{endproc}] -% \describestring[token type]{beginproc} -% \describestring[token type]{endproc} -% These are the |{| and |}| at the beginning and end respectively of -% a \PS\ procedure. There is no \word{data}. -% \item[\texttt{beginstring}, \texttt{beginhex}, \texttt{beginbase85}] -% \describestring[token type]{beginstring} -% \describestring[token type]{beginhex} -% \describestring[token type]{beginbase85} -% These token types are the |(|, |<|, and |<~| at the beginning of -% a \PS\ literal, hex, and base-85 string respectively. There is no -% \word{data}. -% \end{description} -% -% -% \begin{proc}{get_primitive_token} -% The |get_primitive_token| procedure returns the next primitive -% token in the input file. It takes the file id of the source to read -% from as its only argument. -% -% A \emph{primitive token} is a smallest syntactic unit in the \PS\ -% file. Smallest syntactic units are characterized by that the -% insertion of a space anywhere in them changes its meaning. One -% exception is however the left parenthesis characters; it is -% convenient to include |(| among the primitive tokens even though -% inserting a space after it will change the meaning of -% the corresponding token. -% -% The first step in |get_primitive_token| is to read ahead until some -% non-whitespace (or the end of the file) is encountered. -% \begin{tcl} -proc pstokens::get_primitive_token {file} { - global pstokens::input_line pstokens::input_line_no - set pstokens::input_line($file)\ - [string trimleft [set pstokens::input_line($file)] \t\n\f\r\ ] - while {[string length [set pstokens::input_line($file)]]==0} { - if {[gets $file pstokens::input_line($file)]==-1} then { - return {eof} - } - incr pstokens::input_line_no($file) - set pstokens::input_line($file)\ - [string trimleft [set pstokens::input_line($file)] \t\n\f\r\ ] - } -% \end{tcl} -% The second step is to isolate the part of the text that constitutes -% the next token. This is done using regular expressions, but as these -% get rather complicated it seems best to explain how they are -% constructed. The ASCII characters null (|\x00|), tab (|\x09|), line -% feed (|\x0a|), form feed (|\x0c|), carriage return (|\x0d|), and -% space (|\x20|) count as whitespace and delimit tokens, but null is -% currently ignored because \Tcllogo\ before v\,8 cannot keep them in -% strings anyway. The ASCII characters |(|, |)|, |<|, |>|, |[|, |]|, -% |{|, |}|, |/|, and |%| also delimit tokens, and therefore the -% regular expression for a \PS\ name is -% \begin{quote} -% |(/?/?)([^][()<>{}/%|\meta{tab}\meta{LF}\meta{FF}\meta{CR}^^A -% \verb*" ]+)|//?" -% \end{quote} -% (Note that the first right bracket above does not end a character -% range, but is part of the list of characters which are exculded -% from it. Also note that |/| and |//| are valid \PS\ tokens.) -% The number of initial slashes determine whether the name is -% \texttt{executable}, \texttt{literal}, or \texttt{immediate}. -% -% The executable tokens are however somewhat tricky, because the above -% regular expression will also match all numbers. An \emph{integer} is -% any token which matches the regular expression \verb"[+-]?[0-9]+", -% whereas a \emph{real number} is anything else which matches the -% regular expression -% \begin{quote} -% \verb"[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)([eE][+-]?[0-9]+)?" -% \end{quote} -% and a \emph{radix number} is anything which matches the regular -% expression\footnote{Actually there is also the restriction that -% none of the characters after the \texttt{\#} may represent a digit -% greater than or equal to the decimal number before the \texttt{\#}, -% but I'm ignoring that, for now.} -% \begin{quote} -% |[0-9][0-9]?#[0-9A-Za-z]+| -% \end{quote} -% \begin{tcl} - if {[regexp "^(/?/?)(\[^\]\[()<>\{\}/%\t\n\f\r\ \]+)|^//?"\ - [set pstokens::input_line($file)] tokenstr slashes name]}\ - then { - if {[regexp\ - {^[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)([eE][+-]?[0-9]+)?$}\ - $tokenstr]}\ - then { - set token [list number $tokenstr] - } elseif {[regexp {^[0-9][0-9]?#[0-9A-Za-z]+$} $tokenstr]} then { - set token [list radixnumber $tokenstr] - } else { - if {"$tokenstr"=="/" || "$tokenstr"=="//"}\ - then {set slashes $tokenstr} - set token [list [lindex {executable literal immediate}\ - [string length $slashes]] $name] - } - }\ -% \end{tcl} -% There are also a couple of primitive tokens which consist of -% non-whitespace delimiting characters, namely -% \begin{quote} -% |{|, |}|, |<|, |<~|, |<<|, |>>|, |[|, |]|, |(|, -% \end{quote} -% The right parenthesis and greater than characters does not appear in -% the list because they may not appear outside a string. Finally -% there are the comments, which have the regular expression -% \begin{quote} -% |^%([^|\meta{tab}\meta{LF}\meta{FF}\meta{CR}\verb*" ]*)(.*)$" -% \end{quote} -% Here the first parenthesis is the head of the comment and the second -% is the tail. -% \begin{tcl} - else { - switch -regexp -- [set pstokens::input_line($file)] { - ^\{ {set token beginproc ; set tokenstr \{} - ^\} {set token endproc ; set tokenstr \}} - ^\\\[ {set token {executable [} ; set tokenstr \[} - ^\\\] {set token {executable ]} ; set tokenstr \]} - ^< {set token beginhex ; set tokenstr <} - ^<~ {set token beginbase85 ; set tokenstr <~} - ^<< {set token {executable <<} ; set tokenstr <<} - ^>> {set token {executable >>} ; set tokenstr >>} - ^\\( {set token beginstring ; set tokenstr (} - ^% { - regexp "^%(\[^\t\n\f\r\ \]*)(.*)\$"\ - [set pstokens::input_line($file)] tokenstr head tail - set token [list comment $head $tail] - } - default { -% \end{tcl} -% But if none of the above matched the next character must be -% erroneous. -% \begin{tcl} - set tokenstr\ - [string index [set pstokens::input_line($file)] 0] - set token [list error extra $tokenstr\ - [set pstokens::input_line_no($file)] ] - } - } - } - set pstokens::input_line($file)\ - [string range [set pstokens::input_line($file)]\ - [string length $tokenstr] end] - return $token -} -% \end{tcl} -% -% \end{proc} -% -% \begin{proc}{get_string} -% The |get_string| procedure reads a \PS\ literal string and converts -% it to a \texttt{string} token, which it returns. The only argument -% is the file id of the input file. It is assumed that the next thing -% on the input file line is the character after the left parenthesis -% that started the string. -% -% The only conversion of the data that |get_string| performs is that -% escaped newlines are skipped and non-escaped newlines are replaced -% by |\n| escapes. If the end-of-file is encountered while reading a -% string then the necessary number of right parentheses are added to -% the string and the resulting string token is built into an |eof| -% token, which is returned. -% -% The local variable |level| keeps track of the parenthesis nesting -% level, the local variable |data| is the string read so far, and the -% local variable is a flag which is |1| if the next character should -% be escaped and |0| otherwise. -% \begin{tcl} -proc pstokens::get_string {file} { - upvar #0 pstokens::input_line line - global pstokens::input_line_no - set level 1 - set data "" - set escaped 0 - while {$level>0} { - while {$level>0 && [string length $line($file)]>0} { - set c [string index $line($file) 0] - if {$escaped} then { - append data $c - set escaped 0 - } else { - switch -exact -- $c { - ( {incr level ; append data $c} - ) { - incr level -1 - if {$level>0} then {append data $c} - } - \\ {set escaped 1 ; append data $c} - default {append data $c} - } - } - set line($file) [string range $line($file) 1 end] - } - if {$level>0} then { - if {!$escaped} then {append data \\n} - set escaped 0 - if {[gets $file line($file)]==-1} then { - while {$level>1} {append data ) ; incr level -1} - return [list eof [list string $data]] - } - incr pstokens::input_line_no($file) - } - } - list string $data -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}{get_hexstring} -% The |get_hexstring| procedure reads a \PS\ hexadecimal string and -% converts it to a \texttt{hexstring} token, which it returns. The -% only argument is the file id of the input file. It is assumed that -% the next thing on the input file line is the character after the -% less than character that started the string. -% -% The only conversion of the data that |get_hexstring| performs is that -% embedded whitespace is removed. If a character which is neither -% whitespace, a hexadecimal digit, or the closing |>| is encountered -% then an \texttt{error} token is returned and the text read is put -% back into the |input_line| buffert (followed by an |>| which is -% inserted to terminate the string. If the end-of-file is -% encountered while reading a string then what has been read so far -% is returned as a hexstring token built into an |eof| token. -% \begin{tcl} -proc pstokens::get_hexstring {file} { - upvar #0 pstokens::input_line line - global pstokens::input_line_no - set data "" - while 1 { - while {[string length $line($file)]==0} { - if {[gets $file line($file)]==-1} then { - return [list eof [list hexstring $data]] - } - incr pstokens::input_line_no($file) - } - set c [string index $line($file) 0] - set line($file) [string range $line($file) 1 end] - switch -regexp -- $c { - {[0-9a-fA-F]} {append data $c} - \[\t\n\f\r\ \] {} - > {break} - default { - set line($file) <$data>$c$line($file) - return [list error missing/extra > $c\ - [set pstokens::input_line_no($file)]] - } - } - } - list hexstring $data -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}{get_base85string} -% The |get_base85string| procedure reads a \PS\ base-85 string and -% converts it to a \texttt{base-85} token, which it returns. The -% only argument is the file id of the input file. It is assumed that -% the next thing on the input file line is the character after the -% |<~| characters that started the string. -% -% The only conversion of the data that |get_base85string| performs is -% that embedded whitespace is removed. If a character which is neither -% whitespace, a base-85 digit, the letter |z|, or the closing |~| is -% encountered then an \texttt{error} token is returned and the text -% read is put back into the |input_line| buffert (followed by a |~>| -% that terminates the string). If the end-of-file is encountered while -% reading a string then what has been read so far is returned as a -% base-85 string token built into an |eof| token. -% \begin{tcl} -proc pstokens::get_base85string {file} { - upvar #0 pstokens::input_line line pstokens::input_line_no line_no - set data "" - while 1 { - while {[string length $line($file)]==0} { - if {[gets $file line($file)]==-1} then { - return [list eof [list base-85 $data]] - } - incr line_no($file) - } - set c [string index $line($file) 0] - set line($file) [string range $line($file) 1 end] - switch -regexp -- $c { - {[!-uz]} {append data $c} - \[\t\n\f\r\ \] {} - ~ {break} - default { - set line($file) <~$data~>$c$line($file) - return [list error missing/extra ~> $c $line_no($file)] - } - } - } -% \end{tcl} -% If the character after the closing |~| is not a |>| then the entire -% string is put back in the |input_line| buffert and a |missing| error -% is issued. -% \begin{tcl} - if {[string length $line($file)]>0 &&\ - "[string index $line($file) 0]"==">"} then { - set line($file) [string range $line($file) 1 end] - list base-85 $data - } else { - set line($file) <~$data~>$line($file) - list error missing > $line_no($file) - } -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}{get_token} -% \begin{proc}{get_token_rek} -% The |get_token| procedure has the syntax -% \begin{quote} -% |pstokens::get_token| \word{file-id} -% \end{quote} -% and returns the next \PS\ token in the \word{file-id} file. -% -% Most of the work is however done by the |get_token_rek| procedure, -% which is a recursive form of |get_token|. |get_token_rek| handles -% converting the various |begin|\textellipsis\ token types to their -% complete forms, and it calls itself recursively to get the tokens -% that form a procedure. |get_token| only checks that there are no -% lone |endproc| tokens. -% \begin{tcl} -proc pstokens::get_token {file} { - set token [pstokens::get_token_rek $file] - if {"[lindex $token 0]" == "endproc"} then { - global pstokens::input_line_no - set token [list error extra \} [set pstokens::input_line_no($file)]] - } - return $token -} -% \medskip -proc pstokens::get_token_rek {file} { - set token [pstokens::get_primitive_token $file] - switch -exact [lindex $token 0] { - beginproc { - set token {procedure} - while {"[lindex [set token2 [pstokens::get_token_rek $file]] 0]"\ - != "endproc" && "[lindex $token2 0]" != "eof"} { - lappend token $token2 - } - if {"[lindex $token2 0]" == "eof"} then { - if {[llength $token2]>1} then { - lappend token [lindex $token2 1] - } - set token [list eof $token] - } - } - beginstring {set token [pstokens::get_string $file]} - beginhex {set token [pstokens::get_hexstring $file]} - beginbase85 {set token [pstokens::get_base85string $file]} - } - return $token -} -% \end{tcl} -% -% These procedures, and in particular |get_token_rek|, could be made -% more intelligent when it comes to handling errors that occur inside -% procedures. Currently they just embed the |error| token in the -% procedure. -% \end{proc}\end{proc} -% -% -% \subsection{Writing tokens} -% -% Writing tokens is simpler than reading them; the only real -% complication is that the length of lines must be bounded. In order to -% achieve this, data is written linewise to the file (much like the way -% it is read). -% -% \begin{arrayvar}{output_line}[file-id] -% The |output_line| array stores each output line until it is -% actually written to file. Like with the |input_line| array, each -% active output file has its own entry in this array. -% \end{arrayvar} -% -% \begin{proc}{flush_line} -% The |flush_line| procedure has the syntax -% \begin{quote} -% |pstokens::flush_line| \word{file-id} \word{physical}\regopt -% \end{quote} -% It flushes buffered data that is to be written to the file with id -% \word{file-id}. The \word{physical} argument controls whether the -% data actually should be physically written to file (when |1|) or -% merely flushed from the |output_line| array (when |0|). The default -% is |0|. Calling |flush_line| starts a new line in the output file -% unless the |output_line| entry is empty. -% \begin{tcl} -proc pstokens::flush_line {fileid {physical 0}} { - global pstokens::output_line - if {[string length [set pstokens::output_line($fileid)]]>0} then { - puts $fileid [set pstokens::output_line($fileid)] - set pstokens::output_line($fileid) "" - } - if {$physical} then {flush $fileid} -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{open_output} -% \begin{proc}{close_output} -% These procedures are wrappers around \Tcllogo's |open| and |close| -% procedures respectively which additionally initialize and unset the -% relevant entry of the |output_line|. Thus their syntaxes are -% \begin{quote} -% |pstokens::open_output| \word{file-name} \word{access}\regopt\ -% \word{permissions}\regopt\\ -% |pstokens::close_output| \word{file-id} -% \end{quote} -% and they return the same things as |open| and |close| respectively. -% Note however that unlike the case with |open|, the \word{access} -% argument of |open_output| defaults to |w|. -% -% A possible development of the routines for writing tokens would be -% to support output channels other than files. In that case more -% support data structures would have to be initialized, but then the -% |open_output| and |close_output| procedures would be redefined to -% cope with this. -% \begin{tcl} -proc pstokens::open_output {name {access w} args} { - set res [eval open \$name \$access $args] - global pstokens::output_line - set pstokens::output_line($res) "" - return $res -} -% \medskip -proc pstokens::close_output {file_id} { - pstokens::flush_line $file_id 1 - close $file_id - global pstokens::output_line - unset pstokens::output_line($file_id) -} -% \end{tcl} -% \end{proc}\end{proc} -% -% \begin{variable}{wrap_length} -% The |wrap_length| variable stores the maximal number of characters -% that may appear on a single output line. The same value applies for -% all output files. -% \begin{tcl} -set pstokens::wrap_length 72 -% \end{tcl} -% \end{variable} -% -% \begin{proc}{put_word} -% The |put_word| procedure has the syntax -% \begin{quote} -% |pstokens::put_word| \word{file-id} \word{string} -% \end{quote} -% It writes \meta{string} to the file with id \word{file-id}, -% preceeded by a whitespace character if the current line is -% nonempty. The whitespace character is usually a space, but it -% will be a newline if the length of what has already been written -% to the current line is too large to also fit the \word{string} -% within the length specified by the |wrap_length| variable. -% \begin{tcl} -proc pstokens::put_word {file str} { - global pstokens::output_line pstokens::wrap_length - set l [string length [set pstokens::output_line($file)]] - if {$l==0} then { - set pstokens::output_line($file) $str - } elseif {$l + [string length $str] < ${pstokens::wrap_length}}\ - then { - append pstokens::output_line($file) " $str" - } else { - puts $file [set pstokens::output_line($file)] - set pstokens::output_line($file) $str - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{put_breakable} -% The |put_breakable| procedure has the syntax -% \begin{quote} -% |pstokens::put_breakable| \word{file-id} -% \word{prefix} \word{text} \word{suffix} -% \end{quote} -% It writes \meta{prefix}\meta{text}\meta{suffix} to the file with -% id \word{file-id} and inserts whitspace (newlines) into the -% \meta{text} in such a way that the |wrap_length| linewidth isn't -% exceeded. This is primarily useful for hexadecimal and base-85 -% strings. -% \begin{tcl} -proc pstokens::put_breakable {file prefix text suffix} { - upvar #0 pstokens::output_line line pstokens::wrap_length wrap - if {[string length $line($file)] + [string length $prefix] +\ - [string length $text] + [string length $suffix] < $wrap} then { - append line($file) " $prefix$text$suffix" - } else { - pstokens::flush_line $file - set line($file) $prefix - while {[string length $line($file)] + [string length $text] +\ - [string length $suffix] < $wrap} { - set t [expr {$wrap -[string length $line($file)]}] - append line($file) [string range $text 0 [expr {$t-1}]] - set text [string range $text $t end] - pstokens::flush_line $file - } - append line($file) $text$suffix - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{put_string} -% The |put_string| procedure has the syntax -% \begin{quote} -% |pstokens::put_string| \word{file-id} \word{text} -% \end{quote} -% It writes |(|\meta{text}|)| to the file with id \word{file-id} and -% inserts backslash+newline items into the \meta{text} in such a way -% that the |wrap_length| linewidth isn't exceeded and the -% tokenization of the string is unaffected. -% -% The only places where it is unsafe to insert a backslash+newline is -% inside an escape squence. A position can only be inside such a -% sequence if the part of the \meta{text} which is before it gets a -% match against the regular expression -% \begin{quote} -% \verb"(^|[^\])(\\\\)*(\\[0-7]?[0-7]?)$" -% \end{quote} -% and in this case the position between the second and third -% parenthesis is safe. -% \begin{tcl} -proc pstokens::put_string {file text} { - upvar #0 pstokens::output_line line pstokens::wrap_length wrap - if {[string length $line($file)] + [string length $text] + 2 <\ - $wrap} then { - append line($file) " ($text)" - } else { - pstokens::flush_line $file - set line($file) ( - while {[string length $line($file)] + [string length $text] +\ - 1 < $wrap} { - set t [expr {$wrap -[string length $line($file)]}] - set s [string range $text 0 [expr {$t-1}]] - if {[regexp {(^|[^\])(\\\\)*(\\[0-7]?[0-7]?)$} $s\ - foo bar baz escape]}\ - then { - incr t -[string length $escape] - set s [string range $text [expr {$t-1}]] - } - append line($file) $s - set text [string range $text $t end] - pstokens::flush_line $file - } - append line($file) $text) - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{put_token} -% The |put_token| procedure has the syntax -% \begin{quote} -% |pstokens::put_token| \word{file-id} \word{token} -% \end{quote} -% It writes the \PS\ token \word{token} to the file with id -% \word{file-id}. -% \begin{tcl} -proc pstokens::put_token {file token} { - switch [lindex $token 0] { - number - - radixnumber - - executable {pstokens::put_word $file [lindex $token 1]} - literal {pstokens::put_word $file /[lindex $token 1]} - immediate {pstokens::put_word $file //[lindex $token 1]} - string {pstokens::put_string $file [lindex $token 1]} - comment { - pstokens::flush_line $file 0 - puts $file %[lindex $token 1][lindex $token 2] - } - special {pstoken::put_token $file [lindex $token 1]} - procedure { - pstokens::put_word $file \{ - foreach subtok [lrange $token 1 end] { - pstokens::put_token $file $subtok - } - pstokens::put_word $file \} - } - hexstring {pstokens::put_breakable $file < [lindex $token 1] >} - base-85 {pstokens::put_breakable $file <~ [lindex $token 1] ~>} - eof { - if {[llength $token]>1} then { - pstokens::put_token $file [lindex $token 1] - } - pstokens::terminal_print "Token unexpectedly terminated by\ - end of file." - } - error { - pstokens::terminal_print "Error token intercepted at put:\ - [switch [lindex $token 1] { - extra {expr {"extra [lindex $token 2] at input line\ - [lindex $token 3]"}} - missing {expr {"missing [lindex $token 2] at input\ - line [lindex $token 3]"}} - missing/extra {expr {"missing [lindex $token 2], or\ - extra [lindex $token 3], at input line\ - [lindex $token 4]"}} - default {expr {"!!!-unimplemented error-!!!"}} - }]." - } - default { - pstokens::terminal_print\ - "Token of unknown type encountered: $token" - } - } -} -% \end{tcl} -% \end{proc} - - -% \begin{tcl} -%</tokenio> -% \end{tcl} -% -% \section{Token stream editing} -% -% This section I still have ToDo. -% -% -% \begin{thebibliography}{99} -% -% \bibitem{PSman} -% Adobe Systems Incorporated: -% \textit{\PS\ language reference manual, 3rd ed.}, -% Addison--Wesley, 1999; ISBN 0-201-37922-8; -% http:/\slash\texttt{partners.adobe.com}\slash -% \texttt{asn}\slash\texttt{developer}\slash\texttt{PDFS}\slash -% \texttt{TN}\slash\texttt{PLRM.pdf}. -% -% \bibitem{MPinTUG} -% John D.\ Hobby: \textit{A \MF-like System with \PS\ output}, -% TUGboat \textbf{10} (4) (1989), 505--512. -% %^^A 2 or 4 ? Hobby's bibliography says 2, but Bebee's -% %^^A tugboat.bib says 4. -% %^^A @article{Hobby89a, -% %^^A author = {John D. Hobby}, -% %^^A title = {A {METAFONT}-like System with PostScript Output}, -% %^^A journal = {{TUG}boat}, -% %^^A volume = {10}, -% %^^A number = {2}, -% %^^A pages = {505--512}, -% %^^A year = {1989} -% %^^A } -% \bibitem{MPman} -% John D.\ Hobby: \textit{A User's Manual for \MP}, -% AT\&T Bell Laboratories Computing Science Technical Report no.~162 -% (1992); -% \textit{see} http:/\slash \texttt{cm.bell-labs.com}\slash -% \texttt{who}\slash\texttt{hobby}\slash\texttt{MetaPost.html}. -% %^^A @techreport{Hobby92, -% %^^A title = {A User's manual for {MetaPost}}, -% %^^A author = {John D. Hobby}, -% %^^A institution = {AT\&T Bell Laboratories}, -% %^^A address = {Murray Hill, New Jersey}, -% %^^A type = {Computing Science Technical Report}, -% %^^A number = {no.~162}, -% %^^A year = {1992} -% %^^A } -% -% \end{thebibliography} -% -% -% \Finale -% -\endinput diff --git a/Master/texmf-dist/source/latex/tcldoc/tcldoc.dtx b/Master/texmf-dist/source/latex/tcldoc/tcldoc.dtx deleted file mode 100644 index ce2114822b4..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/tcldoc.dtx +++ /dev/null @@ -1,3402 +0,0 @@ -% \CheckSum{1549} -% -% \title{The \package{tcldoc} package and class} -% \author{Lars Hellstr\"om^^A -% \thanks{E-mail: \texttt{Lars.Hellstrom@math.umu.se}} -% \emph{et al.}} -% \date{2001/01/04} -% \maketitle -% -% \iffalse -% -%<class|pkg>\NeedsTeXFormat{LaTeX2e} -%<class>\ProvidesClass{tcldoc} -%<pkg>\ProvidesPackage{tcldoc} -%<class|pkg> [2000/12/20 v2.13 Tcl documentation -%<class> class] -%<pkg> package] -% -%<*driver> -\documentclass{ltxdoc} -\usepackage{amsmath} -\IfFileExists{xdoc2.sty}{\usepackage[dolayout]{xdoc2}[2000/11/18]}{} - -\makeatletter -\@ifpackageloaded{xdoc2}{}{% - \@ifpackagelater{doc}{2000/05/20}{}{% - \let\XD@fragile@meta=\meta - \def\meta{% - \ifx \protect\@typeset@protect - \expandafter\futurelet \expandafter\@let@token - \expandafter\XD@fragile@meta - \else - \noexpand\meta - \fi - }% - }% -} -\@ifundefined{option}{% - \newenvironment{option}[1]{% - \trivlist - \if@inlabel\else \macro@cnt=\z@ \fi - \item[]\ignorespaces - }{\endtrivlist}% -}{} -\makeatother - -\DeclareRobustCommand\package[1]{\textsf{#1}} -\DeclareRobustCommand\Tcl{T\kern-0.1em cl} -\DeclareRobustCommand\word[1]{\mbox{$\{$\itshape#1\/$\}$}} - -\providecommand*\describeoption[1]{\marginpar{\texttt{#1} option}} -\providecommand*\PrintChar[1]{\char#1\relax} -\providecommand*{\DoNotIndexHarmless}[1]{} -\providecommand*{\DoNotIndexBy}[1]{} -\DoNotIndexBy{@} -\DoNotIndexBy{@@} -\DoNotIndexBy{TD@} -\newenvironment{isyntax}{% - \list{}{% - \setlength\parsep{0pt plus 1pt}% - \setlength\listparindent{-1em}% - \setlength\itemindent{\listparindent}% - \addtolength\leftmargin{1em}% - }% - \item\relax \rightskip=1.0\rightskip plus 5cm -}{\endlist} - -\setcounter{IndexColumns}{2} -\hfuzz=10pt -\expandafter\def \expandafter\GlossaryParms \expandafter{% - \GlossaryParms \hbadness=10000 -} - -\CodelineIndex -% \EnableCrossrefs -% \RecordChanges - -\begin{document} -\DocInput{tcldoc.dtx} -\PrintChanges -\PrintIndex -\end{document} -%</driver> -% -% \fi -% -% \begin{abstract} -% The \package{tcldoc} package defines a couple of environments and -% macros for documenting \Tcl\ source code in \texttt{.dtx}-style -% documented source files, much like what the \package{doc} -% package~\cite{doc} does for \TeX\ source code. The \package{tcldoc} -% class is analogous to the \package{ltxdoc} document -% class~\cite{ltxdoc}---it loads the package to gain the basic -% functionality and changes some layout parameters to values that -% are better suited for documented source than those set by the -% standard \package{article} document class. -% -% The \package{tcldoc} package builds on the \package{doc} and -% \package{xdoc}~\cite{xdoc} packages. -% \end{abstract} -% -% \tableofcontents -% -% \DoNotIndex{\advance,\begingroup,\bgroup,\big,\Big,\bigg,\Bigg,\box} -% \DoNotIndex{\catcode,\char,\chardef,\cleaders,\color@begingroup} -% \DoNotIndex{\color@endgroup,\copy,\csname,\DeclareOption} -% \DoNotIndex{\DeclareRobustCommand,\DeclareTextCommand} -% \DoNotIndex{\DeclareTextSymbol,\def,\discretionary,\divide,\do} -% \DoNotIndex{\edef,\egroup,\else,\@empty,\endcsname,\endgroup} -% \DoNotIndex{\expandafter,\fi,\@firstoftwo,\font,\fontdimen} -% \DoNotIndex{\futurelet,\gdef,\global,\@gobble,\hb@xt@,\hbox} -% \DoNotIndex{\hfill,\if,\ifcase,\ifcat,\ifmmode,\ifnum,\ifvbox} -% \DoNotIndex{\ifvmode,\ifvoid,\ifx,\ignorespaces,\immediate,\indent} -% \DoNotIndex{\input,\@@input,\InputIfFileExists,\IfFileExists} -% \DoNotIndex{\item,\kern,\language,\lastbox,\lastpenalty,\lastskip} -% \DoNotIndex{\lccode,\leavevmode,\let,\llap,\LoadClass,\lowercase} -% \DoNotIndex{\m@ne,\m@th,\@makeother,\mathord,\mkern,\multiply} -% \DoNotIndex{\@ne,\newbox,\newcommand,\newcount,\NewDescribeCommand} -% \DoNotIndex{\newenvironment,\newif,\NewMacroEnvironment,\nfss@text} -% \DoNotIndex{\noexpand,\normalfont,\null,\number,\or,\p@,\@@par} -% \DoNotIndex{\parshape,\PassOptionsToClass,\PassOptionsToPackage} -% \DoNotIndex{\penalty,\@plus,\predisplaypenalty,\prevdepth,\prevgraf} -% \DoNotIndex{\ProcessOptions,\protect,\protected@edef} -% \DoNotIndex{\providecommand,\ProvideTextCommandDefault,\relax} -% \DoNotIndex{\RequirePackage,\RequirePackageWithOptions,\rightarrow} -% \DoNotIndex{\sbox,\selectfont,\setbox,\skewchar,\space,\string} -% \DoNotIndex{\TextSymbolUnavailable,\texttt,\the,\tracingparagraphs} -% \DoNotIndex{\ttfamily,\tw@,\typeout,\unhbox,\unpenalty,\unskip} -% \DoNotIndex{\unrestored@protected@xdef,\unskip,\unvbox,\vadjust} -% \DoNotIndex{\vbox,\vert,\vrule,\vskip,\wd,\write,\xdef,\z@,\z@skip} -% -% \section{Introduction} -% \label{Sec:Introduction} -% -% This introduction is meant to be comprehensible even for readers -% unfamiliar with writing \texttt{.dtx} files and using the \package{doc} -% package. Readers who are experienced with this will probably want to -% skip right to the next section. -% -% A \texttt{.dtx} file has a dual nature. On one hand it is a container -% for some lines of code---it could be a program, a macro package, a -% configuration file for some program, merely a part of any of the -% aforementioned, or even arbitrary combinations of the above---and on -% the other hand it is a \LaTeX\ document which documents this code. One -% important advantage with this arrangement is that one can keep all the -% pieces of a project that has to do with a specific task at one place; -% experience has shown that this greatly furthers really keeping all -% parts of a project up to date with each other. -% -% Slightly simplified, one can say that a \texttt{.dtx} file contains -% three kinds of lines. A \emph{code line} is a line that doesn't begin -% with a `|%|' character; such lines can be extracted (copied) using the -% \package{docstrip} program~\cite{docstrip}. A \emph{guard line} is a -% line that begins with the two characters `|%<|'; guards are used to -% structure the set of code lines so that \package{docstrip} can extract -% different code lines to different generated files. A \emph{comment -% line}, finally, is a line that begins with a `|%|' character that is -% not immediately followed by a `|<|' character. The comment lines are -% ignored by \package{docstrip}, but are part of (and usually make up -% most of) the \LaTeX\ document in the \texttt{.dtx} file. -% -% -% \subsection{Special conventions and basic features in a \texttt{.dtx} -% \LaTeX\ document} -% -% An important difference between normal \LaTeX\ documents and -% \texttt{.dtx} \LaTeX\ documents is that the percent character `|%|' -% doesn't start a comment in the latter; in fact it is usually ignored. -% This allows \LaTeX\ to see and typeset the text in the comment lines -% of a \texttt{.dtx} file. Hence if one wants to include the sentence -% ``Your hovercraft is full of eels!'', which in a normal \LaTeX\ -% document could have been written as the line\iffalse -%<*example> -% \fi -%\begin{verbatim} -%Your hovercraft is full of eels! -%\end{verbatim} -% one would instead write the line as -%\begin{verbatim} -%% Your hovercraft is full of eels! -%\end{verbatim} -% in a \texttt{.dtx} document. The space after the |%| is not -% necessary, but most \texttt{.dtx} documents you see include -% it---probably because the ``comment out \TeX\ code'' action of most -% text editors consists of inserting a percent \emph{and} a space at -% the beginning of each line. -% -% The code lines present the opposite problem, as they usually -% shouldn't be treated as normal \LaTeX\ code although the normal \LaTeX\ -% reading conventions would make them the entire document. The usual way -% around this is to surround each group of code lines with two comment -% lines that begin and end an environment in which the code lines get -% typeset verbatim. The \package{tcldoc} package provides the \texttt{tcl} -% environment for this purpose, so the code lines -%\begin{verbatim} -%proc factorial {n} { -% set result 1 -% for {set i 1} {$i<=$n} {incr i} { -% set result [expr {$result * $i}] -% } -% return $result -%} -%\end{verbatim} -% could be included in a \texttt{.dtx} document as the lines -%\begin{verbatim} -%% \begin{tcl} -%proc factorial {n} { -% set result 1 -% for {set i 1} {$i<=$n} {incr i} { -% set result [expr {$result * $i}] -% } -% return $result -%} -%% \end{tcl} -%\end{verbatim} -% When typeset, this will look as -% \begin{macrocode} -proc factorial {n} { - set result 1 - for {set i 1} {$i<=$n} {incr i} { - set result [expr {$result * $i}] - } - return $result -} -% \end{macrocode} -% The tiny numbers at the beginning of each line enumerate the code lines. -% Index references to code usually specify such code line numbers, but -% the enumeration can be switched off. -% -% In mathematical papers, the statements of e.g.\ theorems are usually -% made inside a \texttt{theorem} (or whatever) environment which -% provides certain text formatting, a heading, and a position in the -% document that can be referenced from other parts of it. In \texttt{.dtx} -% documents one usually does something similar for each named piece of -% code: macros, environments, templates, etc. In particular, the -% \package{tcldoc} package provides two environments \texttt{proc} (for -% procedures) and \texttt{variable} (for variables). -% Figure~\ref{Fig:procex} contains an example of how \texttt{proc} -% might be used in describing a procedure for computing the greatest -% common divisor of two integers. -% -% \begin{figure} -% -% \begin{trivlist} -% \item[]\leavevmode\llap{\texttt{gcd} (proc)\kern\marginparsep}^^A -% The |gcd| procedure takes two arguments $a$ and $b$ which must be -% integers and returns their greatest common divisor $\gcd(a,b)$, -% which is computed using Euclid's algorithm. As a special case, -% $\gcd(0,0)$ is considered to be $0$, so formally |gcd $a $b| -% computes $\lvert a \rvert \wedge \lvert b \rvert$, where $\wedge$ -% denotes the meet operation in the divisor lattice of non-negative -% integers. -% \begin{macrocode} -proc gcd {a b} { - set a [expr {abs($a)}] - set b [expr {abs($b)}] - while {$b>0} { - set r [expr {$a%$b}] - set a $b - set b $r - } - return $a -} -% \end{macrocode} -% \end{trivlist} -% -% \begin{center} -% (a) A typeset procedure with description -% \end{center} -% -%\begin{verbatim} -%% \begin{proc}{gcd} -%% The |gcd| procedure takes two arguments $a$ and $b$ which must be -%% integers and returns their greatest common divisor $\gcd(a,b)$, -%% which is computed using Euclid's algorithm. As a special case, -%% $\gcd(0,0)$ is considered to be $0$, so formally |gcd $a $b| -%% computes $\lvert a \rvert \wedge \lvert b \rvert$, where $\wedge$ -%% denotes the meet operation in the divisor lattice of non-negative -%% integers. -%% \begin{tcl} -%proc gcd {a b} { -% set a [expr {abs($a)}] -% set b [expr {abs($b)}] -% while {$b>0} { -% set r [expr {$a%$b}] -% set a $b -% set b $r -% } -% return $a -%} -%% \end{tcl} -%% \end{proc} -%\end{verbatim} -% -% \begin{center} -% (b) The code for the example in (a) -% \end{center} -% -% \caption{An example of the \texttt{proc} environment} -% \label{Fig:procex} -% \end{figure} -% -% What does the \texttt{proc} environment do more precisely? First -% there's the marginal heading which can be seen in Figure~^^A -% \ref{Fig:procex}. Such headings make it easier to find the procedure in -% the typeset form of the document. Then the \texttt{proc} environment -% makes an index entry which tells you where the procedure is defined, -% and finally it stores the procedure name in a variable so that -% subsequent |\changes|\footnote{The \cs{changes} command is defined by -% the \package{doc} package~\cite{doc}. It is used for adding entries -% to a global list of changes for code in the \texttt{.dtx} document.} -% commands know to what the change that they are recording was made. -% -% The \texttt{variable} environment does the same things except that it -% writes ``(var.)'' rather than ``(proc)''. This environment wasn't used -% for describing the three local variables |a|, |b|, and |r| in the -% example; this is since there is no point in referring to these -% variables from elsewhere in the program. Instead the \texttt{variable} -% environment is primarily meant for global variables (although it could -% also be useful for local variables that are meant to be accessed using -% |upvar| or |uplevel|), and as such it can often be of great help, since -% the description of a global variable can otherwise be hard to find, -% especially with languages like \Tcl\ where variables don't have to be -% declared and thus have no natural ``home'' in the code. -% -% Another noteworthy feature in the example is the use of vertical -% bar `\verb+|+' characters to delimit short pieces of verbatim \Tcl\ -% code in the comment lines. It is often necessary for the explanation -% to include short examples of code in the documentation, and the -% standard \LaTeX\ |\verb| command is exactly what one would need for -% this. As such code sections are rather frequent however, it has become -% the custom to use a single character for both starting and ending such -% a piece of code. The \package{tcldoc} document class defines \verb+|+ -% as a shorthand for \verb+\tclverb|+, where |\tclverb| is a variant of -% |\verb| which has been designed specifically for \Tcl\ code. -% -% The above description was meant to give a basic understanding of how -% \Tcl\ code and documentation thereof can be mixed in a \texttt{.dtx} -% file, it neither explains all the environments and commands that -% the \package{tcldoc} package provides, nor mentions all the -% features of the environments that were described. That information can -% instead be found in Section~\ref{Sec:Manual} of this paper. It should -% also be mentioned that the \package{doc} package~\cite{doc} defines -% several commands and environments that may be of use for describing -% code, and it is well worth getting acquainted with the features of -% that package as well (although parts of its documentation has become -% rather archaic). -% -% -% \subsection{Guards and \package{docstrip} installation scripts} -% -% The central command in a \package{docstrip} installation script is -% |\generate|, since this is the command which actually causes code to -% be extracted. |\generate|'s syntax is -% \begin{quote} -% |\generate|\marg{files} -% \end{quote} -% where \meta{files} consists of one or several |\file| commands, each -% of which has the syntax -% \begin{quote} -% |\file|\marg{output}\marg{sources} -% \end{quote} -% where \meta{output} is a filename and \meta{sources} consists of one -% or several |\from| commands, each of which has the syntax -% \begin{quote} -% |\from|\marg{input}\marg{options} -% \end{quote} -% where, finally, \meta{input} is a filename and \meta{options} is a -% comma-separated list of alphanumerical strings. Thus a |\generate| -% command might look like -%\begin{verbatim} -% \generate{\file{p1.sty}{\from{s1.dtx}{foo,bar}} -% \file{p2.sty}{\from{s2.dtx}{baz} -% \from{s3.dtx}{baz}} -% \file{p3.sty}{\from{s1.dtx}{zip} -% \from{s2.dtx}{zap}} -% } -%\end{verbatim} -% The meaning of this command is -% \begin{quote} -% Generate the three files \texttt{p1.sty}, \texttt{p2.sty}, and -% \texttt{p3.sty}. Extract the code for \texttt{p1.sty} from -% \texttt{s1.dtx} with options \texttt{foo} and \texttt{bar}, extract -% the code for \texttt{p2.sty} from \texttt{s2.dtx} with option -% \texttt{baz} and \texttt{s3.dtx} (the code from \texttt{s2.dtx} -% will be put before the code from \texttt{s3.dtx}) with option -% \texttt{baz}, and finally extract the code for \texttt{p3.sty} from -% \texttt{s1.dtx} with option \texttt{zip} and \texttt{s2.dtx} with -% option \texttt{zap}. -% \end{quote} -% The \emph{options} are used to control which parts of the source files -% should be extracted to which generated file. A source file can -% contain a number of \emph{modules}, and at the beginning of each -% module \package{docstrip} decides, for each output file separately, -% whether the code lines in that module should be extracted to the -% output file. The beginning of a module is marked by a guard line which -% has the syntax -% \begin{quote} -% |%<*|\meta{expression}|>| -% \end{quote} -% and the end by a corresponding -% \begin{quote} -% |%</|\meta{expression}|>| -% \end{quote} -% guard line. In their simplest form, the \meta{expression}s are names -% of options, and in that case the code lines in the module are only -% extracted if that option appears in the \meta{options} for that -% combination of input file and output file. The \meta{expression}s can -% however be arbitrarily complicated boolean expressions; -% see~\cite{docstrip} for more information. -% Modules may nest inside each other, and in that case the code lines in -% an inner module can only be included if all surrounding modules are -% being included. It is checked that matching |*| and |/| guard lines -% contain the same (as strings) \meta{expression}, and case is -% significant in the names of options. -% -% One application of modules which has already been mentioned is to -% bundle code for several different generated files in the same -% \texttt{.dtx} file---one example of this is the file -% \texttt{doc.dtx} (part of the \LaTeX\ base distribution) which -% contains both the \package{doc} package (\texttt{doc.sty}) and two -% \package{makeindex} style files (\texttt{gglo.ist} and -% \texttt{gind.ist}). Another application is to keep variant sections -% of code---such as special code for debugging or gathering -% statistics---in the \texttt{.dtx} source file for a program without -% thereby making it a part of the normal form of that program. It is -% quite possible to use \package{docstrip} as a simple pre-processor -% for languages whose compiler\slash interpreter haven't got one built -% in. -% -% There are many other commands available in a \package{docstrip} -% installation script beside those listed above, but those are well -% described in the \package{docstrip} manual~\cite{docstrip} and need -% little attention here. Instead I'm going to finish this subsection -% with a quick guide to the particular difficulties one faces when using -% \package{docstrip} to extract \Tcl\ code, and how to overcome them. -% -% The main problem is that \package{docstrip} insert a few comment lines -% at the beginning and end of each file it generates. This is a good -% thing, because a file consisting entirely of extracted code lines -% would normally be completely void of commentary and quite -% unintelligible for the casual user. These few comment lines explain -% that the file was generated by \package{docstrip} from other files -% (which contain the documentation of the code), lists those files, -% and normally also contains a copyright (or more commonly some kind of -% copyleft) notice. The problem lies in that comments look different in -% different languages, and as the default is to write \TeX\ style -% comments, one must tell \package{docstrip} to write \Tcl\ style -% comments. This can be done through the command -%\begin{verbatim} -%\edef\MetaPrefix{\string#} -%\end{verbatim} -% which tells \package{docstrip} to begin each inserted comment line -% with the character `|#|'. -% -% The comment lines inserted at the beginning of a generated file is -% called the \emph{preamble} and those of the end the \emph{postamble}. -% To set the preamble, one writes -% \begin{trivlist} -% \item |\preamble|\\ -% \meta{preamble lines}\\ -% |\endpreamble| -% \end{trivlist} -% and correspondingly to set the postamble -% \begin{trivlist} -% \item |\postamble|\\ -% \meta{postamble lines}\\ -% |\endpostamble| -% \end{trivlist} -% The \meta{preamble lines} and \meta{postamble lines} can be any number -% of lines (including zero). Unlike the text in source files, the text in -% these preamble and postamble lines is not read verbatim, so things in -% these lines which have special meaning to \TeX\ (such as control -% sequences) will be treated as such; the only exception is that spaces -% and newlines are preserved (instead of concatenated to single spaces -% as they normally would). It is important that the preamble and -% postamble \emph{are} set after |\MetaPrefix| is changed, because each -% line specified between |\preamble| and |\endpreamble| or |\postamble| -% and |\endpostamble| respectively will be prefixed by the current value -% of |\MetaPrefix|. -% -% Finally, some programs assign special meaning to the first line of a -% file, so one might want to control what gets put there. Merely using -% |\preamble| doesn't achieve this, because the \meta{preamble lines} -% specified that way are put after the lines saying ``this is a -% generated file \textellipsis''. You can however add things to the -% preamble by explicitly setting the macro |\defaultpreamble|, which is -% where \package{docstrip} stores the preamble. To make the first line -% a comment which simply contains the text `|-*-Tcl-*-|', you could give -% the command -%\begin{verbatim} -%\edef\defaultpreamble{\MetaPrefix\space -*-Tcl-*-^^J\defaultpreamble} -%\end{verbatim} -% but an explanation of this is a bit beyond this introduction. -% -% In summary, a \package{docstrip} installation script for extracting a -% file \texttt{foo.tcl} from \texttt{foo.dtx}, using \Tcl\ style -% comments, inserting a GPL copyleft notice in the preamble, and -% beginning with the line |# -*-Tcl-*-| could look as follows: -%\begin{verbatim} -%\input docstrip.tex -% -%\edef\MetaPrefix{\string#} -% -%\preamble -% -%This program is free software; you can redistribute it and/or modify -%it under the terms of the GNU General Public License as published by -%the Free Software Foundation; either version 2 of the License, or -%(at your option) any later version. -% -%This program is distributed in the hope that it will be useful, -%but WITHOUT ANY WARRANTY; without even the implied warranty of -%MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -%GNU General Public License for more details. -% -%You should have received a copy of the GNU General Public License -%along with this program; if not, write to the Free Software -%Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -%See the file "license.terms" for information on usage and -%redistribution of this file, and for a DISCLAIMER OF ALL -%WARRANTIES. -% -%\endpreamble -% -%\postamble -%\endpostamble -% -%\edef\defaultpreamble{\MetaPrefix\space -*-Tcl-*-^^J\defaultpreamble} -% -%\generate{\file{foo.tcl}{\from{foo.dtx}{bar}}} -% -%\end -%\end{verbatim} -% -% The generated file \texttt{foo.tcl} will contain -%\begin{verbatim} -%# -*-Tcl-*- -%# -%# This is file `foo.tcl', -%# generated with the docstrip utility. -%# -%# The original source files were: -%# -%# foo.dtx (with options: `bar') -%# -%# This program is free software; you can redistribute it and/or modify -%# it under the terms of the GNU General Public License as published by -%# the Free Software Foundation; either version 2 of the License, or -%# (at your option) any later version. -%# -%# This program is distributed in the hope that it will be useful, -%# but WITHOUT ANY WARRANTY; without even the implied warranty of -%# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -%# GNU General Public License for more details. -%# -%# You should have received a copy of the GNU General Public License -%# along with this program; if not, write to the Free Software -%# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -%# See the file "license.terms" for information on usage and -%# redistribution of this file, and for a DISCLAIMER OF ALL -%# WARRANTIES. -%# -%\end{verbatim} -% \meta{lines extracted from \texttt{foo.dtx}} -%\begin{verbatim} -%# -%# -%# End of file `foo.tcl'. -%\end{verbatim} -% -% -% -% \subsection{The structure of the \LaTeX\ document} -% -% All this has been about the local appearance of a \texttt{.dtx} file, -% but what about the overall structure? There are several points to -% raise about that as well. -% -% The first is that \LaTeX\ to begin with treat \texttt{.dtx} documents -% just like any other document---a `|%|' starts a comment and only lines -% \emph{not} beginning with a `|%|' contain anything that \LaTeX\ can -% see. Somehow \LaTeX\ must be instructed to start applying the special -% reading rules that were described above. This is the job of the -% so-called \emph{driver}, which (for a file \texttt{myfile.dtx}) in its -% simplest form can look like -%\begin{verbatim} -%\documentclass{tcldoc} -%\begin{document} -%\DocInput{myfile.dtx} -%\end{document} -%\end{verbatim} -% The important command here is |\DocInput|, because that is what tells -% \LaTeX\ to apply the special \texttt{.dtx} reading rules. More -% precisely it means ``Start ignoring `|%|' characters in the text you -% read, input the file \texttt{myfile.dtx}, and when you're done return -% to treating `|%|' characters as before.'' -% -% The driver is usually put in the very first stretch of code lines in -% the \texttt{.dtx} file. This means that \LaTeX, when ordered to typeset -% the \texttt{.dtx} file, will start to read along, possibly ignoring -% hundreds of lines beginning with `|%|' because they are comments. Then -% it encounters the driver, and after the |\documentclass| and -% |\begin{document}| commands it executes the |\DocInput|. This will -% cause it to not ignore lines beginning with `|%|', so when it starts -% reading the file again it will see all the lines it skipped the first -% time through. The file will be read to end, after which \LaTeX\ -% returns to the command after the |\DocInput|. As that command happens -% to be |\end{document}|, it finishes the typeset document and stops. -% This stop prevents it from seeing and interpreting as \LaTeX\ commands -% the remaining code lines in the file. -% -% The second time through the driver shouldn't be interpreted as -% \LaTeX\ commands, since for example the |\documentclass| command may -% only be used once in a \LaTeX\ document. One way of achieving this is -% to put an |\iffalse| command right before the driver and a |\fi| -% command right after it. This says to \LaTeX\ that the driver code is -% conditional material, and since the condition evaluates to false -% (|\iffalse| always evaluates to false), this conditional material -% should be skipped. Thus the first few lines of \texttt{myfile.dtx} -% typically might be -%\begin{verbatim} -%% \iffalse -%%<*driver> -%\documentclass{tcldoc} -%\begin{document} -%\DocInput{myfile.dtx} -%\end{document} -%%</driver> -%% \fi -%\end{verbatim} -% The \texttt{driver} guard lines are there to stop \package{docstrip} -% from including the driver code in the generated files. -% -% After the driver comes the actual \LaTeX\ document. The document -% usually consists of two parts, where the first part is a manual for -% the \emph{usage} of the code defined in the file, and the second part -% contains the actual \emph{implementation} (documented code). The idea -% is that most people are (at least the first time) quite content with -% learning how to use something, so one should make it simple for them -% to find that information.\footnote{One needn't take this as an absolute -% rule---I for one haven't written all my packages that way---but -% structuring the document like this generally makes it more accessible.} -% To further this approach one puts the command |\StopEventually| at the -% start of the implementation part and the command |\Finale| at the end -% of it. Normally |\StopEventually| doesn't make itself felt, but if one -% previously has given the command |\OnlyDescription| then rest of the -% file will not be read; this can be used to produce a ``manual only'' -% version of the documentation. |\StopEventually| takes one argument and -% the code in this argument is executed at the |\Finale| (if the -% implementation part is being included) or immediately (if the -% implementation part isn't being included). Thus this argument is the -% place to put things that should appear at the very end of the -% document. -% -% The \texttt{tcl}, \texttt{proc}, and \texttt{variable} environments -% described above all typically appear in the implementation part of the -% document. -% -% -% \section{Usage of commands and environments} -% \label{Sec:Manual} -% -% -% \subsection{The actual source code} -% -% The \DescribeEnv{tcl}\texttt{tcl} environment is used for wrapping up -% a group of code lines which contain \Tcl\ code. Lines inside this -% environment which begin with a percent character are called -% \emph{command} lines and can contain \LaTeX\ commands which get -% executed, whereas lines that do not begin with a percent character are -% called \emph{normal} lines and get typeset verbatim (or nearly -% verbatim). Lines that begin with |%<| (\package{docstrip} guard lines) -% do however constitute a special case, as the guard expression will get -% typeset as in \package{doc}'s \texttt{macrocode} environment and the -% remainder of the line will get processed in command mode if it is a -% |*| or |/| guard, but in normal mode if the guard line was of any other -% type. -% -% The \texttt{tcl} environment uses the same general formatting -% parameters as \package{doc}'s \texttt{macrocode} environment. In -% particular this means that the text on a normal line is typeset in -% |\MacroFont| (by default the same thing as \cs{normalfont}\penalty0 -% \cs{ttfamily}\penalty0\cs{small}) or |\AltMacroFont| (by default the same -% thing as \cs{normalfont}\penalty0\cs{ttfamily}\penalty0\cs{itshape}^^A -% \penalty0\cs{small}) depending on the current \package{docstrip} module -% nesting level. The \package{tcldoc} class sets the -% \texttt{StandardModuleDepth} counter to 1, which means that the -% |\AltMacroFont| is used when the modules two levels deep or more. -% -% If a normal line is too long to fit on one line then the \texttt{tcl} -% environment will try to break it. Legal breakpoints are spaces which -% could be replaced by a backslash and a newline without changing the -% meaning of the command; thus most spaces are legal breakpoints. When a -% line is broken at a space like this, the space is replaced by a -% backslash so that the line is still ``syntactically correct''. The -% opposite happens to lines which actually end with an escaped newline; -% such lines are concatenated with the following line and are treated as -% one long line. This is so that a sequence of breakpoints can be chosen -% which is optimal for the actual line width of the document (as opposed -% to the line width used in the text file, which can be something quite -% different). For example -%\begin{verbatim} -%% \begin{tcl} -%lsearch -exact\ -% [concat $a [lrange $b $first end] c d e f]\ -% [lindex $g $h] -%% \end{tcl} -%\end{verbatim}\iffalse -%</example> -% \fi -% could be typeset as any of the code examples in -% Figure~\ref{Fig:Radbrytning}, depending on how wide a line is. -% \begin{figure} -% \begin{center} -% \small -% \(\left\lvert -% \begin{minipage}{350pt} -% \begin{flushleft} -% |lsearch -exact [concat $a [lrange $b $first end] c d e f]|^^A -% | [lindex $g $h]| -% \end{flushleft} -% \end{minipage} -% \right\rvert\) -% -% \smallskip -% -% \(\left\lvert -% \begin{minipage}{298pt} -% \begin{flushright} -% \noindent |lsearch -exact [concat $a [lrange $b $first|^^A -% | end] c d e f]|\textbackslash\hfill\vadjust{}\\ -% |[lindex $g $h]| -% \end{flushright} -% \end{minipage} -% \right\rvert\) -% -% \smallskip -% -% \(\left\lvert -% \begin{minipage}{241pt} -% \begin{flushright} -% \noindent |lsearch -exact|\textbackslash\hfill\vadjust{}\\ -% |[concat $a [lrange $b $first end] c d e f]|\textbackslash\\ -% |[lindex $g $h]| -% \end{flushright} -% \end{minipage} -% \right\rvert\) -% -% \smallskip -% -% \(\left\lvert -% \begin{minipage}{184pt} -% \begin{flushright} -% \noindent |lsearch -exact [concat $a|\textbackslash\hfill -% \vadjust{}\\ -% |[lrange $b $first end] c d e f]|\textbackslash\\ -% |[lindex $g $h]| -% \end{flushright} -% \end{minipage} -% \right\rvert\) -% \end{center} -% -% \caption{The same \Tcl\ code, set in different linewidths} -% \label{Fig:Radbrytning} -% \end{figure} -% The environment tries to put the linebreaks at the lowest possible -% nesting (of braces and brackets) level; I believe this gives the best -% readability.\footnote{When I first started programming in \Tcl\ I -% used a completely different method for breaking long lines in the -% code---I mainly implemented the current method because it was -% simple to program---but I was quite surprised by how readable it made -% the code.} There is however a way to override this automatic choice -% of breakpoints: if a normal line which ends with an escaped newline is -% followed by a command line (even a command line that doesn't contain -% any commands) then it will not be concatenated with the next normal -% line. -% -% There are a couple of restrictions on the code in command lines. First -% of all it is not allowed to start a new paragraph (there will be an -% error message). Secondly a command may not be broken across several -% lines---all the arguments must appear on the same line as the -% control sequence. Thirdly some characters have other catcodes than -% in normal \LaTeX, so it is not certain that all commands work. Some -% commands that do work and may be useful are: -% \begin{itemize} -% \item Vertical space commands (|\smallskip|, |\medskip|, etc.) -% The command line `|% \medskip|' is more to type than a blank -% normal line, but it looks slightly better. -% \item Indexing commands (|\index|, |\IndexEntry|,\footnote{This -% command is defined by the \package{xdoc} package~\cite{xdoc}.} -% etc.) -% \item The \cs{TclInput} and |\settabsize| commands (see below). -% \end{itemize} -% And of course the |\end{tcl}| command works in a command line, since -% that is how one ends a \texttt{tcl} environment. -% -% Besides the \texttt{tcl} environment there is also a -% \DescribeEnv{tcl*}\texttt{tcl*} environment which is different from -% \texttt{tcl} only in that spaces and tabs are typeset as special -% visible space `\textvisiblespace' and visible tab -% `\makebox[6\fontdimen2\font]{\( - \mkern-7mu -% \cleaders\hbox{$\mkern-2mu - \mkern-2mu$}\hfill \mkern-7mu -% \mathord\rightarrow \mkern-1mu \vrule \mkern1mu\)}' characters. This -% can be useful for pieces of code where the exact number of spaces in -% a sequence is significant, such as code for writing tables that align. -% -% For shorter pieces of \Tcl\ code, e.g.\ examples, there's the -% \DescribeMacro{\tclverb}|\tclverb| command. |\tclverb| is very similar -% to the standard \LaTeX\ command |\verb|, but there are two differences. -% The first is that text typeset by |\tclverb| can contain breakpoints -% at whitespace; these behave just as in the \texttt{tcl} environment. -% The second is that the verbatim text that follows |\tclverb| may contain -% newlines, provided that these newlines are escaped by a backslash. Like -% a \Tcl\ interpreter, |\tclverb| ignores whitespace following an escaped -% newline. Unlike a \Tcl\ interpreter, |\tclverb| also ignores one percent -% character before the ignored whitespace, if it is the first character -% on the following line. Thus -%\begin{verbatim} -%% \tclverb|append a $b| is much more efficient than \tclverb|set a\ -%% $a$b| if \tclverb|$a| is long. -%\end{verbatim} -% is perfectly legal, and the escaped newline between |a| and |$a$b| is -% treated just like the space between |set| and |a|. Like |\verb|, the -% |\tclverb| command has a starred form \DescribeMacro{\tclverb*}^^A -% |\tclverb*| which also typesets spaces and tabs as visible characters. -% -% -% The \DescribeMacro{\MakeShortTclverb}|\MakeShortTclverb| command works -% just like the \package{doc}\slash\package{shortvrb} command -% |\MakeShortVerb|, except that it makes the active character a shorthand -% reference for |\tclverb|\textellipsis\ instead of |\verb|\textellipsis. -% Use |\DeleteShortVerb| to undo the effect of a |\MakeShortTclverb|. The -% \package{tcldoc} class executes the command -% \begin{quote} -% \verb"\MakeShortTclverb{\|}" -% \end{quote} -% which makes \verb"|" a shorthand for \verb"\tclverb|". -% -% Since there is no universally accepted standard for the size -% (equivalent number of spaces) of a tab, there is a command -% \DescribeMacro{\settabsize}|\settabsize| for changing this. -% |\settabsize| takes as its only argument the new tab size, which must -% be an integer in the range 2--255. The default value is 8. -% |\settabsize| makes a local assignment to the tab size. The tab size -% can be changed inside a \texttt{tcl} (or \texttt{tcl*}) environment. -% -% There is also a command \DescribeMacro{\TclInput}|\TclInput| which -% is used for typesetting ``raw'' (not in \texttt{.dtx} format) \Tcl\ code -% files. |\TclInput| is meant to be used on a \emph{command} line of a -% \texttt{tcl} or \texttt{tcl*} environment, and it efficiently makes -% things look as if the |\TclInput| command had been replaced by the -% inputted file in its entirety (preceded by a newline, and followed -% by a percent and a space). |\TclInput| takes as its only argument the -% name of the file to input. -% -% To typeset the file \texttt{myscript.tcl} one would write -%\begin{verbatim} -%% \begin{tcl} -%% \TclInput{myscript.tcl} -%% \end{tcl} -%\end{verbatim} -% or even -%\begin{verbatim} -% \begin{tcl}\TclInput{myscript.tcl}\end{tcl} -%\end{verbatim} -% anywhere in a \package{tcldoc} document. This works since the -% \texttt{tcl} environment is in command mode right after the initial -% |\begin{tcl}|, and the |\end{tcl}| need not be the first command on a -% command mode line. -% -% Finally, if the \package{rtkinenc} package~\cite{rtkinenc} is being -% used then the verbatim code environments and commands described above -% are to some extent able to catch errors that would otherwise occur -% because the fonts in use do not contain all characters in the input -% encoding. Rather than printing nothing, missing characters will be -% written as the corresponding |\x|\meta{hh} backslash sequence in a -% slightly different font than the rest of the text. This provides an -% unambiguous representation regardless of input encoding. -% -% -% \subsection{Markup of named things} -% -% The two environments \DescribeEnv{proc}\texttt{proc} and -% \DescribeEnv{variable}\texttt{variable}, which are analogues of -% \package{doc}'s \texttt{macro} environment, for procedures and -% variables respectively have already been mentioned in -% Section~\ref{Sec:Introduction}. In addition to those there are two -% environments \DescribeEnv{arrayentry}\texttt{arrayentry} and -% \DescribeEnv{arrayvar}\texttt{arrayvar} which are meant for entries -% in array variables and array variables as a whole. The complete -% syntaxes of these environments are -% \begin{quote} -% |\begin{proc}|\oarg{namespace}\marg{proc name}\\ -% \vadjust{}\quad$\vdots$\\ -% |\end{proc}| -% -% |\begin{variable}|\oarg{namespace}\marg{variable name}\\ -% \vadjust{}\quad$\vdots$\\ -% \quad|\end{variable}| -% -% |\begin{arrayentry}|\oarg{namespace}\marg{array name}^^A -% \marg{entry name}\\ -% \vadjust{}\quad$\vdots$\\ -% |\end{arrayentry}| -% -% |\begin{arrayvar}|\oarg{namespace}\marg{array name}^^A -% \oarg{index-des}\\ -% \vadjust{}\quad$\vdots$\\ -% |\end{arrayvar}| -% \end{quote} -% The \meta{proc name}, \meta{variable name}, and \meta{array name} -% arguments are quite evidently the names of the procedure, variable, -% and array respectively. The \meta{namespace} argument can be to -% specify the namespace part of a qualified name; having the name split -% like this makes it easier to treat the namespace differently from the -% rest of the qualified name.\footnote{By redefining \cs{TD@main@index} -% one can for example make the index sorted first by name, and then by -% namespace.} The command \DescribeMacro{\buildname}|\buildname| -% constructs a qualified name from a namespace and a name. If there is -% no \meta{namespace} argument then the namespace used will be the -% default namespace. The default namespace is set using the -% \DescribeMacro{\setnamespace}|\setnamespace| command, which takes the -% namespace name as its only argument. The default namespace at the -% beginning of the document is the global namespace, whose name is the -% empty string. -% -% The \texttt{arrayentry} environment is intended for certain -% distinguished entries in an array, such as entries inserted to -% make the boundary cases of an algorithm work correctly and entries -% which have a special meaning to the program. Not all arrays contain -% such special entries, but when they do it is a good practice -% to explain them explicitly. The \meta{index-des} argument of the -% \texttt{arrayvar} environment can be used to specify what is used as -% index into the array; the text in this argument will appear both in -% the margin and in the index, but note that \meta{index-des} is a -% moving argument. There is little difference between the -% \texttt{variable} and \texttt{arrayvar} environments when the -% \meta{index-des} argument of the latter isn't used, but the index -% entries they make behave differently with respect to -% \texttt{arrayentry} index entries. An \texttt{arrayentry} index entry -% will be put as a subentry of the corresponding \texttt{arrayvar} -% entry, whereas a \texttt{variable} entry would appear separately. -% -% The above environments usually only appear in the implementation part -% of a \texttt{.dtx} file. For the usage part there is a command -% \DescribeMacro{\describestring}|\describestring| which produces -% marginal headings and index entries. The syntax of |\describestring| -% is -% \begin{quote} -% |\describestring|\oarg{type}\oarg{namespace}\marg{text} -% \end{quote} -% The \meta{text} is the string for which a heading and index entry will -% be made, whereas the \meta{type} (if given) is put after the text. -% If the \meta{namespace} is given then the thing described is supposed -% to be the name of something namespace-relative (like a procedure or -% global variable) and in this case the complete name is formed by -% passing \meta{namespace} and \meta{text} to |\buildname|. If -% \meta{type} is \texttt{proc}, \texttt{var.}, or \texttt{array} and a -% namespace is given then the index entry made will fit that made by -% a corresponding \texttt{proc}, \texttt{variable}, or -% \texttt{arrayvar} respectively environment. The \meta{type} argument -% is, in \LaTeX\ terminology, moving. -% -% The \meta{text} and \meta{namespace} arguments can contain arbitrary -% characters and most characters can be entered verbatim. Amongst the -% exceptions are `|%|', `|\|', `|{|', and `|}|', which instead can be -% entered as -% |\PrintChar|\discretionary{}{}{}|{`\%}|, -% |\PrintChar|\discretionary{}{}{}|{`\\}|, -% |\PrintChar|\discretionary{}{}{}|{`\{}|, and -% |\PrintChar|\discretionary{}{}{}|{`\}}| respectively. See the -% \package{xdoc} package~\cite{xdoc} documentation for an explanation of -% the |\PrintChar| command. The \meta{text} argument can also contain -% ``variant'' parts made using the \DescribeMacro{\meta}|\meta| command. -% As an example, -% \begin{quote} -% |\describestring[array]{\meta{mode}modeVars}| -% \end{quote} -% puts the text -% \begin{quote} -% \meta{mode}|modeVars| (array) -% \end{quote} -% in the margin and index. The arguments of such |\meta| commands are -% moving. -% -% -% \subsection{Describing command syntaxes} -% -% One important part of documentation is to describe the syntaxes of -% commands. The previous subsection contains examples of the conventions -% for this that has been developed for \LaTeX\ -% commands---mandatory arguments are denoted as `\marg{argument}' and -% optional arguments are denoted as `\oarg{argument}'. These two classes -% suffice rather well for \LaTeX\ commands, but the syntaxes of \Tcl\ -% commands are not seldom much more complex. Therefore a more powerful -% form of syntax specification is called for, and one which is close at -% hand is that used in regular expressions since it is already part of -% the \Tcl\ language anyway. -% -% \DescribeMacro\regopt -% \DescribeMacro\regstar -% \DescribeMacro\regplus -% The simplest commands available are the modifiers |\regopt|, -% |\regstar|, and |\regplus|, which correspond to the |?|, -% |*|, and |+| metacharacters in a regular expression; using |\regopt| -% after a term says that it is optional, |\regstar| says that the term -% can be repeated an arbitrary number of times (including zero), and -% |\regplus| says that the term occurs at least once. The typeset -% results of these commands are $^?$, $^*$, and $^+$ respectively -% (recall that exponents are sometimes used to denote repetition). -% -% The terminals in the expression are best made using |\tclverb| (for -% ``fixed'' material, e.g.\ procedure names) and -% \DescribeMacro{\word}|\word| (for variable material, e.g.\ -% arguments). The syntax of |\word| is -% \begin{quote} -% |\word|\marg{text} -% \end{quote} -% and e.g.\ |\word{script}| gets typeset as -% \begin{quote} -% \word{script} -% \end{quote} -% Using these, one can for example specify the syntaxes of the \Tcl\ -% commands |append| and |catch| through -% \begin{quote} -% \verb"|append| \word{var-name} \word{value}\regplus"\\ -% \verb"|catch| \word{script} \word{var-name}\regopt" -% \end{quote} -% (recall that `\verb"|"' is a shorthand for `\verb"\tclverb|"'). These -% get typeset as -% \begin{quote} -% |append| \word{var-name} \word{value}\(^+\)\\ -% |catch| \word{script} \word{var-name}\(^?\) -% \end{quote} -% -% Terms in regular expressions can also consist of parenthesised -% subexpressions, which are made using the \DescribeEnv{regexp}^^A -% \texttt{regexp} environment. The syntax of this environment is -% \begin{quote} -% |\begin{regexp}|\oarg{modifier}\quad\dots\quad |\end{regexp}| -% \end{quote} -% If \texttt{regexp} environments are nested then the parentheses of -% the outer environment will grow to be larger than those of the inner -% environment. A side-effect of this is that the \texttt{regexp} -% environment wants to know if a modifier will be applied to it, since -% the amount by which the modifier should be raised in this case depends -% on the size of the parenthesis before it, and this is what the -% \meta{modifier} optional argument is for. \LaTeX\ does not provide -% for arguments at the |\end| of an environment, so it has to be placed -% at the |\begin|. Using these elements, the syntax of |if| can be -% specified through -% \begin{quote} -% \verb"|if| \word{expression} |then|\regopt\ \word{script}"\\ -% \verb"\begin{regexp}[\regstar]|elseif| \word{expression}"\\ -% \verb"|then|\regopt\ \word{script}\end{regexp}"\\ -% \verb"\begin{regexp}[\regopt]|else| \word{script}\end{regexp}" -% \end{quote} -% which typesets as -% \begin{isyntax} -% |if| \word{expression} |then|\(^?\) \word{script} \(\bigl(\)^^A -% |elseif| \word{expression} |then|\(^?\) \word{script}\(\bigr)^*\) -% \(\bigl(\)|else|~\word{script}\(\bigr)^?\) -% \end{isyntax} -% -% The final regular expression construction that is supported is that -% of branches of a regular expression. A \texttt{regexp} environment -% consist of one or several branches that are separated by -% \DescribeMacro{\regalt}|\regalt| commands. Visually the |\regalt| -% command gets typeset as a vertical bar that has the same size as the -% parentheses of the surrounding \texttt{regexp} environment. The -% |\regalt| command may only be used inside a \texttt{regexp} environment. -% An example of the use of |\regalt| is the following specification of -% the syntax of \Tcl's |regexp| command: -% \begin{quote} -% \verb"|regexp| \begin{regexp}[\regstar]|-nocase|\regalt"\\ -% \verb"|-indices|\end{regexp} |--|\regopt \word{regular expression}"\\ -% \verb"\word{string} \word{var-name}\regstar" -% \end{quote} -% which typesets as -% \begin{isyntax} -% |regexp| \((\)|-nocase|~\(\mid\) |-indices|\()^*\) |--|\(^?\) -% \word{regular expression} \word{string} \word{var-name}\(^*\) -% \end{isyntax} -% -% Finally a note about the relationship between the |\word| command and -% \package{doc}'s |\meta| command. Whereas the argument of |\word| is -% encapsulated in braces (and thus ought to be a separate word for a -% \Tcl\ interpreter), the argument of |\meta| is encapsulated in angle -% brackets. The idea is that |\word| should be used for things which are -% separate words to \Tcl, whereas |\meta| should be used for things which -% are merely part of words. Thus in the command |set b Z${a}Y|, the second -% word |b| would be a `\word{var-name}' and the third word |Z${a}Y| would -% be a `|Z|\meta{string}|Y|'. -% -% -% -% \subsection{Options and customisation} -% -% The \package{tcldoc} package does not have any options, but all -% options passed to it are passed on to the \package{xdoc} package. -% The \package{tcldoc} class accepts all options that the standard -% \LaTeX\ document class \package{article} accepts, with the exception -% of \texttt{a5paper}. -% -% In addition, the \package{tcldoc} class also accepts the option -% \describeoption{macinputenc}\texttt{macinputenc}, which causes a lot -% of things to be set up so that input characters from outside 7-bit -% ASCII can be interpreted according to the Macintosh character set. -% -% Like the \package{ltxdoc} class, the \package{tcldoc} class will look -% for a special configuration file \texttt{tcldoc.cfg} and input that -% file if it exists. This file can be used to declare extra options for -% the class, have certain options always given, etc. Section~2 of -% \texttt{ltxdoc.dtx}~\cite{ltxdoc} is a good introduction to how such -% configuration files can be used with \texttt{.dtx} sources in general. -% -% When customising the \package{tcldoc} document class, you affect how -% all documents using that class will be typeset in your particular \TeX\ -% installation. It is \emph{not} something you have to do, but it can -% make \package{tcldoc} documents work better with the printers, paper -% formats, fonts, etc.\ that are available in your installation. It -% will usually cause line and page breaks to occur at other places than -% they would do if typeset using an uncustomised \package{tcldoc} -% class, so the typographical quality of the document can be decreased, -% but it is uncommon to find an \texttt{.dtx} document whose author -% have given these matters much attention anyway. Hence the typographic -% arguments against customisation are weak. -% -% A common form of customisation is to use additional packages, since -% various kinds of document-wide font selection is often done by -% packages. Due to that the code in \texttt{tcldoc.cfg} is executed when -% the \package{tcldoc} class does its option processing, at which time -% \LaTeX\ does not allow loading packages, such customisation is not -% straightforward. There is a way around that however; to load e.g.\ the -% \package{textcomp} package, use the command -%\begin{verbatim} -%\AtEndOfClass{\usepackage{textcomp}} -%\end{verbatim} -% Using |\AtEndOfClass| like this delays the command until it may be -% executed. -% -% Finally, and in particular if you are typesetting documents that use -% the \texttt{macinputenc} option, you can put code that define -% ``fakes'' for various text commands in the \texttt{tcldoc.cfg} file. -% For example, the `diamond' character in the Macintosh encoding is not -% available in any of the standard \LaTeX\ text fonts, and therefore the -% \texttt{tcl} environment will typeset this character as the escape -% code `\textbackslash xd7'. There is a diamond character in the math -% fonts however, and you can make the \texttt{tcl} environment use that -% character instead by adding the commands -%\begin{verbatim} -%\DeclareTextSymbol{\textdiamond}{OMS}{5} -%\DeclareTextSymbolDefault{\textdiamond}{OMS} -%\end{verbatim} -% to you \texttt{tcldoc.cfg} file. Note however, that this kind of -% configuration is \emph{advanced} \LaTeX, and you should probably -% familiarise yourself with the contents of the file -% \texttt{ltoutenc.dtx}~\cite{ltoutenc} before attempting to design -% anything along these lines yourself. -% -% -% \subsection{Miscellanea} -% -% For writing ``\Tcl'', the \package{tcldoc} package defines the command -% \DescribeMacro{\Tcllogo}|\Tcllogo|, which for most fonts look slightly -% better than simply typing |Tcl|. (|\Tcllogo| becomes \Tcl, whereas -% |Tcl| becomes Tcl.) -% -% -% \section{Acknowledgements} -% -% The \package{tcldoc} document class and \LaTeX\ package were -% constructed starting from three other sources: (i)~the \package{ltxdoc} -% document class~\cite{ltxdoc} by David Carlisle, -% (ii)~the \package{doc} package~\cite{doc} by Frank Mittelbach, -% B.~Hamilton Kelly, Andrew Mills, Dave Love, and Joachim Schrod, and -% (iii)~my own \package{pasdoc} document class. Hence the `et al.'\ in -% the author field above. This complicated heritage in the code is -% mirrored by the documented source---there are paragraphs below that -% are rather about one of (i)--(iii), than about \package{tcldoc}. -% -% -% -% \StopEventually{ -% \begin{thebibliography}{9} -% \bibitem{ltoutenc} -% Johannes Braams, David Carlisle, Alan Jeffrey, Frank -% Mittelbach, Chris Rowley, and Rainer Sch\"opf: -% \textit{ltoutenc.dtx}, The \LaTeX3 Project; -% CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash -% \texttt{latex}\slash \texttt{base}\slash \texttt{ltoutenc.dtx}. -% \bibitem{ltxdoc} -% David Carlisle: -% \textit{The file \texttt{ltxdoc.dtx} for use with \LaTeXe}, -% The \LaTeX3 Project; -% CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash -% \texttt{latex}\slash \texttt{base}\slash \texttt{ltxdoc.dtx}. -% \bibitem{rtkinenc} -% Lars Hellstr\"om: -% \textit{The \package{rtkinenc} package}; -% CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash -% \texttt{latex}\slash \texttt{contrib}\slash -% \texttt{supported}\slash \texttt{rtkinenc}\slash -% \texttt{rtkinenc.dtx}. -% \bibitem{xdoc} -% Lars Hellstr\"om: -% \textit{The \package{xdoc} package --- experimental -% reimplementations of features from \package{doc}, -% second~prototype}, 2000; -% CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash -% \texttt{latex}\slash \texttt{exptl}\slash \texttt{xdoc}\slash -% \texttt{xdoc2.dtx}. -% \bibitem{docstrip} -% Frank Mittelbach, Denys Duchier, Johannes Braams, Marcin -% Woli\'nski, and Mark Wooding: \textit{The \textsf{DocStrip} -% program}, The \LaTeX3 Project; -% CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash -% \texttt{latex}\slash \texttt{base}\slash \texttt{docstrip.dtx}. -% \bibitem{doc} -% Frank Mittelbach, B.~Hamilton Kelly, Andrew Mills, Dave Love, and -% Joachim \mbox{Schrod}: \textit{The \package{doc} and -% \package{shortvrb} Packages}, The \LaTeX3 Project; -% CTAN:\discretionary{}{}{\thinspace}\texttt{macros}\slash -% \texttt{latex}\slash \texttt{base}\slash \texttt{doc.dtx}. -% \end{thebibliography} -% \begin{flushleft}\footnotesize -% The ``CTAN:'' above is short for ``any of the servers in the -% Comprehensive \TeX\ Archive Network (or any of their mirrors)''. -% You get a working URL if you replace this by e.g.\ -% ``\texttt{ftp://ftp.tex.ac.uk/tex-archive/}''.% -% \end{flushleft} -% } -% -% -% \changes{v\,1.90}{2000/01/02}{Took a copy of \texttt{pasdoc.dtx} and -% started modifying it into \texttt{tcldoc.dtx}. (LH)} -% -% \section{Initial stuff in the \package{tcldoc} package} -% -% The |\NeedsTeXFormat| and |\ProvidesPackage| commands for the -% \package{tcldoc} package appear at the top of \texttt{tcldoc.dtx} (not -% shown in the typeset document). Apart from that the only initial -% action required is to load the \package{xdoc} package (and thereby -% the \package{doc} package). -% -% \begin{macrocode} -%<*pkg> -\RequirePackageWithOptions{xdoc2}[2000/11/26] -% \end{macrocode} -% -% -% \section{Verbatim typesetting of \Tcl\ code} -% -% \changes{v\,2.10}{2000/10/03}{Major overhaul of the \texttt{tcl} -% environment, to make it possible to assign different penalties to -% different breakpoints. (LH)} -% -% The main feature in the \package{tcldoc} package is the \texttt{tcl} -% environment, which typesets embedded code in a way more adapted to -% \Tcl\ code than what the \texttt{macrocode} environment does. -% -% -% \subsection{Beginning of line processing} -% -% The organization of the text in \emph{lines} is crucial for its -% interpretation by the \texttt{tcl} environment. In particular the -% following features rely on being at the beginning of a line: -% \begin{itemize} -% \item indentation of \Tcl\ code, -% \item invoking command mode, -% \item recognizing \package{docstrip} guards. -% \end{itemize} -% -% \begin{macro}{\TD@percent@token} -% A control sequence |\let| to a |%|$_{12}$, mainly for use in |\ifx| -% comparisons. -% \DoNotIndex{\%} -% \begin{macrocode} -\begingroup - \catcode`\%=12 - \global\let\TD@percent@token=% -\endgroup -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@start@n@line} -% \begin{macro}{\TD@start@n@line@} -% \begin{macro}{\TD@start@n@line@i} -% The macro |\TD@start@n@line| is used at the beginning of every line. -% The macro first clears the |\TD@line@indent| and |\TD@nesting@level| -% registers and then it checks if the next character is a percent. If -% it is then this is a command line. If it isn't then it is a normal -% line and it is time to start a codeline paragraph and count the -% character indentation. -% -% |\TD@|\-|start@|\-|n@|\-|line@| is the macro which actually does -% these things; |\TD@|\-|start@|\-|n@|\-|line| is usually |\let| to -% |\TD@|\-|start@|\-|n@|\-|line@|. When a file is being |\TclInput|ed -% however, |\TD@|\-|start@|\-|n@|\-|line| is |\let| to -% |\TD@|\-|start@|\-|n@|\-|line@i| which peeks at the next token -% before calling |\TD@|\-|start@|\-|n@|\-|line@|. If it didn't, -% |\TD@|\-|start@|\-|n@|\-|line@| would have a problem at the end of -% the file, since the end of a file counts as being |\outer|. -% \begin{macrocode} -\def\TD@start@n@line@#1{% - \global\TD@line@indent=\z@ - \TD@nesting@level=\z@ - \ifx #1\TD@percent@token - \expandafter\TD@module - \else - \global\advance \c@codelineno \@ne - \TD@begin@tclpar - \expandafter\TD@count@indent \expandafter#1% - \fi -} -% \end{macrocode} -% \begin{macrocode} -\let\TD@start@n@line=\TD@start@n@line@ -\def\TD@start@n@line@i{\futurelet\next\TD@start@n@line@} -% \end{macrocode} -% \end{macro}\end{macro}\end{macro} -% -% -% \begin{macro}{\TD@count@indent} -% The purpose of the |\TD@count@indent| macro is to compute the -% indentation of the current line. It grabs the next character, and -% as long as that is a space or tab it will just increment -% |\TD@line@indent| accordingly and continue with the next character. -% |!| and |"| are used to make space and tab respectively with -% suitable catcode. -% \DoNotIndex{\!,\",\ ,\^} -% \begin{macrocode} -\begingroup - \catcode`\!=\active - \catcode`\"=\active - \lccode`\!=`\ % - \lccode`\"=`\^^I% - \lowercase{% -\endgroup - \def\TD@count@indent#1{% - \ifx !#1% - \global\advance \TD@line@indent \@ne - \expandafter\TD@count@indent - \else \ifx "#1% - \global\divide \TD@line@indent \TD@tab@size - \global\advance \TD@line@indent \@ne - \global\multiply \TD@line@indent \TD@tab@size - \expandafter\expandafter \expandafter\TD@count@indent - \else - \TD@setup@parshape - \expandafter\expandafter \expandafter#1% - \fi\fi - }% -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TD@module} -% When command mode has been properly established it is time to -% check if the next character is |<|, in which case the following -% \package{docstrip} guard must be processed. -% \changes{v\,2.13}{2000/12/20}{Always check whether the current line -% is a guard line, since the \texttt{\PrintChar{\number`\<}} in -% the guard would otherwise start a new paragraph, which is an -% error. (LH)} -% \begin{macrocode} -\def\TD@module{% - \TD@command - \futurelet\next - \TD@ch@angle -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TD@ch@angle} -% The module checking in \package{tcldoc} takes advantage of the -% macros for this in \package{doc}---|\ch@plus@etc| is a \package{doc} -% macro. |<| is active because it is in the nolig list -% (|\verbatim@|\-|nolig@|\-|list|). -% \begin{macrocode} -\begingroup - \catcode`<=\active - \gdef\TD@ch@angle{% - \ifx <\next - \global\advance \c@codelineno \@ne - \TD@begin@tclpar - \expandafter\futurelet \expandafter\next - \expandafter\ch@plus@etc - \fi - } -\endgroup -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@pm@module} -% The |\TD@pm@module| macro is used instead of \package{doc}'s -% |\pm@module| when in the \texttt{tcl} environment. This is necessary -% since the paragraph man\oe uvres of the \texttt{tcl} environment would -% not work right with \package{doc}'s |\pm@module|. -% -% If we're not dealing with a block directive (|*| or |/|), i.e., -% it's a single special line, we set everything up to the next |>| -% appropriately, return to normal mode, possibly change font, and -% start counting indentation spaces. -% \DoNotIndex{\>} -% \begin{macrocode} -\begingroup - \catcode`\>=\active - \gdef\TD@pm@module#1>{% - \Module{#1}% - \TD@normal - \ifnum \guard@level<\c@StandardModuleDepth \else - \AltMacroFont - \fi - \TD@count@indent - } -\endgroup -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TD@star@module} -% \begin{macro}{\TD@slash@module} -% The |\TD@star@module| and |\TD@slash@module| macros are, like -% |\TD@pm@module|, used instead of \package{doc}'s |\star@module| and -% |\slash@module| respectively when in the \texttt{tcl} environment. -% The only difference is that the |\TD@|\textellipsis\ macros also end -% the paragraph started in |\TD@ch@angle|, but without that -% difference, the module guard would incorrectly be reported as -% ``horizontal material on command line''. -% \DoNotIndex{\>} -% \begin{macrocode} -\begingroup - \catcode`\>=\active - \gdef\TD@star@module#1>{% - \Module{#1}\TD@end@tclpar - \global\advance \guard@level \@ne - \ifnum \c@StandardModuleDepth<\guard@level - \global\let\macro@font=\AltMacroFont - \macro@font - \fi - } - \gdef\TD@slash@module#1>{% - \Module{#1}\TD@end@tclpar - \global\advance \guard@level \m@ne - \ifnum \guard@level=\c@StandardModuleDepth - \global\let\macro@font\MacroFont - \macro@font - \fi - } -\endgroup -% \end{macrocode} -% \end{macro}\end{macro} -% -% -% \begin{macro}{\TD@gobble@whitespace} -% This macro gobbles all normal mode spaces and tabs following it. -% \begin{macrocode} -\def\TD@gobble@whitespace#1{% - \if \ifx #1\TD@active@space - 0% - \else - \ifx #1\TD@active@tab 0\else 1\fi - \fi 0% - \expandafter\TD@gobble@whitespace - \else - \expandafter#1% - \fi -} -% \end{macrocode} -% \end{macro} -% -% -% -% \subsection{Typographical elements} -% -% This subsection contains definitions of the typographical -% elements---special symbols and the like--that are used in the -% \texttt{tcl} and \texttt{tcl*} environments. -% -% -% \begin{macro}{\TD@typography} -% \begin{macro}{\TD@nontcl@font} -% The |\TD@typography| macro does all the typographic set-up that is -% common to the \texttt{tcl} environment, the \texttt{tcl*} -% environment, and the |\tclverb| command. -% -% The |\TD@nontcl@font| macro selects an ``escape'' font for \Tcl\ -% material. This font is used for various kinds of escape codes that -% are typeset instead of some character---either because the -% character is not available, or because the line needs to be broken. -% The escape font will have the same font family (and same encoding) -% as the text surrounding the \texttt{tcl} environment or |\tclverb| -% command. Therefore |\TD@nontcl@font| must be defined before the -% \Tcl\ material font is selected. I don't think it is necessary to -% use |\protected@edef| below, but it can't hurt either. -% \begin{macrocode} -\def\TD@typography{% - \protected@edef\TD@nontcl@font{% - \noexpand\fontencoding{\cf@encoding}% - \noexpand\fontfamily{\f@family}\noexpand\selectfont - }% -% \end{macrocode} -% The most frequent escape symbol is the single backslash used for -% escaping the end of lines, and this is stored in the -% |\TD@backslash@box| box. -% -% The following code have to do with how characters outside -% visible ASCII are typeset when they appear in the \texttt{tcl} or -% \texttt{tcl*} environment. The commands are defined by the -% \package{rtkinenc} package. -% \begin{macrocode} - \InputModeCode - \SetUnavailableAction{\leavevmode{% - \TD@nontcl@font\textbackslash x\TypesetHexNumber{##1}% - }}% - \DeclareInputMath{0}{\RIE@undefined{0}}% - \DeclareInputMath{12}{\RIE@undefined{12}}% -} -% \end{macrocode} -% \end{macro}\end{macro} -% -% \begin{macro}{\TD@typeset@space} -% This macro typesets a space, as it should be in the \texttt{tcl} -% environment (and other places too). It generates a kern, not glue, so -% that it can be used in a |\discretionary|. -% \begin{macrocode} -\def\TD@typeset@space{\kern\fontdimen\tw@\font} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@discretionary@space} -% This is the macro which offers all the breakpoints in |\tclverb| -% code. The name comes from the fact that all the breakpoints are -% discretionaries which appear to be spaces when not broken. When -% they are broken, they are backslashes. To give some visual hint -% that these backslashes need not be backslashes in the source, they -% are typeset in the same font family (and same encoding) as the -% text surrounding the \texttt{tcl} environment. -% \begin{macrocode} -\def\TD@discretionary@space{% - \discretionary{\copy\TD@backslash@box}{}{\TD@typeset@space}% -}% -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@breakable@space} -% The valid breakpoints inside \texttt{tcl} and \texttt{tcl*} -% environments are made in the |\TD@|\-|breakable@|\-|space| macro. -% This macro contributes an |\hbox| (which contains a -% |\TD@typeset@space|), a penalty, and an empty |\vadjust| to the -% current horizontal list. If a line break is made at the penalty, -% the |\hbox| will later be removed and replaced by a non-macro font -% backslash (from |\TD@backslash@box|). The |\vadjust| is there to -% prevent that any discardable items disappears after the breakpoint. -% \begin{macrocode} -\def\TD@breakable@space{% - \hbox{\TD@typeset@space}% - \TD@nesting@penalty - \vadjust{}% -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@typeset@tab} -% This is an unbreakable space whose width equals that of -% |\TD@tab@size| spaces. -% \begin{macrocode} -\def\TD@typeset@tab{\kern\TD@tab@size\fontdimen\tw@\font} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@visible@whitespace} -% The |\TD@visible@whitespace| macro locally redefines the macros -% which typesets spaces and tabs to make visible symbols. The visible -% tab is roughly a |\rightarrowfill| and a |\vrule|, but a difference -% is that the minuses that form the extensible ``tail'' to the -% |\rightarrow| are not smashed. Not doing that gives the |\vrule| a -% suitable height, but I had rather expected the nominal height of -% the |\rightarrow| to be larger \textellipsis\ It's yet another -% mysterious math font feature, I suppose. -% -% \begin{macrocode} -\def\TD@visible@whitespace{% - \def\TD@typeset@space{\char32 }% - \def\TD@typeset@tab{% - \hb@xt@\TD@tab@size\fontdimen\tw@\font{% - $\m@th-\mkern-7mu% - \cleaders\hbox{$\mkern-2mu-\mkern-2mu$}\hfill - \mkern-7mu\mathord\rightarrow\mkern-1mu\vrule\mkern1mu$% - }% - }% -} -% \end{macrocode} -% \end{macro} -% -% -% \subsection{Catcodes and active characters} -% -% Like any \texttt{verbatim}-like environment, the \texttt{tcl} -% environment does some rather extensive alterations of catcodes. This -% is handled by the three macros |\TD@general|, |\TD@normal|, and -% |\TD@command|. Set-up that is common for both modes is made by -% |\TD@general| when the \texttt{tcl} environment is entered. -% Mode-dependent set-up is made by |\TD@normal| and |\TD@command| -% whenever a mode switch occurs. -% -% \begin{macro}{\TD@let@active} -% One technicality here is that all of these routines need to set the -% definition of some active character, and this character is often not -% active with normal \LaTeX\ catcodes. To overcome this difficulty, -% there is a macro |\TD@let@active| which takes two arguments: a -% control sequence with a single character name, and an arbitrary -% control sequence. The active character with the same name as the -% first control sequence is |\let| locally to the second control -% sequence. -% \begin{macrocode} -\begingroup - \catcode\z@=\active - \gdef\TD@let@active#1{% - \begingroup - \lccode\z@=`#1% - \lowercase{% - \endgroup - \let^^@% - }% - }% -\endgroup -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TD@general} -% The |\TD@general| macro does the initial set-ups that are common for -% both modes of the \texttt{tcl} environment and for the |\tclverb| -% command. These include definitions of various active characters and -% |\catcode| assignments. -% -% \DoNotIndex{\^,\ ,\\,\[,\]} -% \DoNotIndexHarmless{\PrintChar{`\{}} -% \DoNotIndexHarmless{\PrintChar{`\}}} -% \begin{macrocode} -\def\TD@general{% - \let\do\do@noligs - \verbatim@nolig@list - \let\do\@makeother - \dospecials - \catcode`\^^M=\active - \TD@let@active\^^I\TD@active@tab - \TD@let@active\^^M\TD@active@CR - \TD@let@active\ \TD@active@space - \TD@let@active\\\TD@active@backslash - \TD@let@active\{\TD@active@braceleft - \TD@let@active\}\TD@active@braceright - \TD@let@active\[\TD@active@bracketleft - \TD@let@active\]\TD@active@bracketright -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TD@normal} -% This macro sets up the normal mode, changing everything that is -% different in any of the other modes. Note that the catcodes in -% normal mode are such that no character is a space. This makes it -% possible for macros used in normal mode to look ahead by simply -% grabbing the next character in an undelimited argument. -% \DoNotIndex{\^,\ ,\\,\[,\]} -% \DoNotIndexHarmless{\PrintChar{`\{}} -% \DoNotIndexHarmless{\PrintChar{`\}}} -% \begin{macrocode} -\def\TD@normal{% - \catcode`\^^I=\active - \catcode`\ =\active - \catcode`\\=\active - \catcode`\{=\active - \catcode`\}=\active - \catcode`\[=\active - \catcode`\]=\active -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@command} -% This macro switches from normal mode to command mode. -% \DoNotIndex{\^,\ ,\\,\[,\]} -% \DoNotIndexHarmless{\PrintChar{`\{}} -% \DoNotIndexHarmless{\PrintChar{`\}}} -% \begin{macrocode} -\def\TD@command{% - \catcode`\^^I=10% - \catcode`\ =10% - \catcode`\[=12% - \catcode`\]=12% - \catcode`\\=\z@ - \catcode`\{=\@ne - \catcode`\}=\tw@ -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TD@active@space} -% \begin{macro}{\TD@active@space@} -% This macro is used for spaces in normal mode. Its main problem is -% to determine whether it is followed by more whitespace or not. If it -% is, then it is an unbreakable space. If it isn't, then it is a -% breakable space. -% \begin{macrocode} -\def\TD@active@space#1{% - \ifx #1\TD@active@backslash - \expandafter\TD@active@space@ - \else - \ifx #1\TD@active@space - \TD@typeset@space - \else\ifx #1\TD@active@tab - \TD@typeset@space - \else - \TD@breakable@space - \fi\fi - \expandafter#1% - \fi -} -% \end{macrocode} -% The special case to look out for is that the next character is a -% backslash which escapes a newline. -% \begin{macrocode} -\def\TD@active@space@#1{% - \ifx #1\TD@active@CR - \TD@typeset@space - \else - \TD@breakable@space - \fi - \TD@active@backslash #1% -} -% \end{macrocode} -% \end{macro}\end{macro} -% -% \begin{macro}{\TD@active@tab} -% The |\TD@active@tab| macro is what the active character tab is -% |\let| to inside the \texttt{tcl} and \texttt{tcl*} environments. -% \begin{macrocode} -\def\TD@active@tab{\TD@typeset@tab} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@active@CR} -% This macro is called at the end of a line. The |\catcode| tests the -% current mode. -% \DoNotIndex{\\} -% \begin{macrocode} -\def\TD@active@CR{% - \ifnum \catcode`\\=\z@ - \ifvmode\else - \PackageError{tcldoc}{Horizontal material on command line}\@ehc - \@@par - \fi - \TD@normal - \else - \TD@end@tclpar - \fi - \TD@start@n@line -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@active@CRv} -% This is what |\tclverb| defines the |^^M| active character as -% being. Cf.\ the standard \LaTeX\ macro |\verb@eol@error|. -% \begin{macrocode} -\def\TD@active@CRv{% - \verb@egroup - \PackageError{tcldoc}{\protect\tclverb\space ended by end of line}% - \@ehc -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TD@active@backslash} -% \changes{v\,2.10}{2000/10/08}{First checking if next character is -% active, and only expands the macro containing the detailed tests -% if it is. (LH)} -% \begin{macro}{\TD@active@backslash@} -% \begin{macro}{\TD@active@backslash@v} -% |\TD@active@backslash| is used for backslashes in normal mode. Its -% main problem is to determine whether the backslash is escaping -% something (which would normally be treated specially by the -% environment) or not. The primary test for this is whether the -% argument grabbed is an active character, and if it is then -% processing continues (in |\TD@active@backslash@|) to determine what -% should be done. -% \begin{macrocode} -\def\TD@active@backslash#1{% - \ifcat \noexpand#1\noexpand~% - \expandafter\TD@active@backslash@ - \else - \@backslashchar - \fi - #1% -} -% \end{macrocode} -% -% \changes{v\,2.11}{2000/11/06}{Escaped spaces are no longer breakable. -% (LH)} -% \begin{macrocode} -\def\TD@active@backslash@#1{% - \ifcase - \ifx #1\TD@active@CR 0% - \else\ifx #1\TD@active@backslash 1% - \else\ifx #1\TD@active@braceleft 2% - \else\ifx #1\TD@active@braceright 2% - \else\ifx #1\TD@active@bracketleft 2% - \else\ifx #1\TD@active@bracketright 2% - \else\ifx #1\TD@active@space 3% - \else 4\fi\fi\fi\fi\fi\fi\fi - \space - \expandafter\TD@active@backslash@i - \or - \@backslashchar\@backslashchar - \or - \@backslashchar \string#1% - \or - \@backslashchar \TD@typeset@space - \else - \@backslashchar - \expandafter#1% - \fi -} -% \end{macrocode} -% Escaped newlines that are followed by command mode lines are not -% converted to discretionary spaces. -% \begin{macrocode} -\def\TD@active@backslash@i#1{% - \ifx #1\TD@percent@token - \copy\TD@backslash@box - \expandafter\TD@active@CR - \else - \TD@breakable@space - \global\advance \c@codelineno \@ne - \expandafter\TD@gobble@whitespace - \fi - #1% -} -% \end{macrocode} -% The |\tclverb| command uses |\TD@active|\-|@backslash@v| instead of -% |\TD|\-|@active|\-|@backslash@i|, since it is intended for use on -% lines that may begin with |%|. -% \begin{macrocode} -\def\TD@active@backslash@v#1{% - \TD@discretionary@space - \ifx #1\TD@percent@token - \expandafter\@firstoftwo - \fi - \TD@gobble@whitespace #1% -} -% \end{macrocode} -% \end{macro}\end{macro}\end{macro} -% -% -% \begin{macro}{\TD@active@braceleft} -% \begin{macro}{\TD@active@braceright} -% \begin{macro}{\TD@active@bracketleft} -% \begin{macro}{\TD@active@bracketright} -% These macros mainly typeset the corresponding characters, but they -% also increase or decrease the |\TD@nesting@level| count by one. -% \DoNotIndex{\[,\]} -% \DoNotIndexHarmless{\PrintChar{`\{}} -% \DoNotIndexHarmless{\PrintChar{`\}}} -% \begin{macrocode} -\begingroup - \catcode`\{=12 \catcode`\}=12 - \catcode`\[=1 \catcode`\]=2 - \gdef\TD@active@braceleft[{\advance\TD@nesting@level\@ne] - \gdef\TD@active@braceright[}\advance\TD@nesting@level\m@ne] -\endgroup -% \end{macrocode} -% \begin{macrocode} -\def\TD@active@bracketleft{[\advance\TD@nesting@level\@ne} -\def\TD@active@bracketright{]\advance\TD@nesting@level\m@ne} -% \end{macrocode} -% \end{macro}\end{macro}\end{macro}\end{macro} -% -% -% -% \subsection{Paragraph formatting} -% -% This subsection contains definitions of control sequences that are -% mainly related to the formatting of paragraphs. -% -% The new implementation of the \texttt{tcl} and \texttt{tcl*} -% environments is based on inserting the ``discretionary'' backslashes -% at the linebreaks \emph{after} the paragraph has been broken. -% Doing this involves reboxing every line in the paragraph, and in this -% process the line adjustments are changed as well. -% -% \begin{macro}{\TD@backslash@box} -% The |\TD@backslash@box| box register is set to a backslash in the -% special |\TD@nontcl@font| at the beginning of each \texttt{tcl} and -% \texttt{tcl*} environment. These backslashes are used to denote -% ``backslash escaping newline''. The primary reason for keeping this -% glyph in a box is not that this might be slightly faster to -% typeset, but to have the \emph{width} of it easily accessible. -% \begin{macrocode} -\newbox\TD@backslash@box -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@nesting@level} -% \begin{macro}{\TD@nesting@penalty} -% |\TD@nesting@level| is a count register which keeps track of how -% many brace\slash bracket groups surrounds the current position in -% the line. It is cleared to zero at the beginning of each paragraph. -% \begin{macrocode} -\newcount\TD@nesting@level -% \end{macrocode} -% |\TD@nesting@penalty| makes a |\penalty| whose value should depend -% on the nesting level (the deeper the nest, the larger the penalty). -% It may also adjust the value of |\linepenalty| to counter that -% the nesting level has become negative. This is typically needed for -% lines which say things like ``|} else {|''. The default definition is -% to make the nesting penalty $100$ times the nesting level and to -% make the |\linepenalty| equal to -% \(10 - \min\{0,\mbox{least penalty}\}\). -% \begin{macrocode} -\def\TD@nesting@penalty{% - \penalty \the\TD@nesting@level 00\relax - \ifnum \lastpenalty<-\linepenalty - \linepenalty=10% - \advance \linepenalty -\lastpenalty - \fi -} -% \end{macrocode} -% I doubt that this is necessarily the best algorithm for computing -% these penalties, so if you are really thorough about your -% typography you may well want to experiment with other definitions of -% |\TD@nesting@penalty|. In case you should then find something which -% works even better then I'm interested to learn about it. -% \end{macro}\end{macro} -% -% \begin{macro}{\TD@reformat@lines} -% The |\TD@reformat@lines| macro calls itself recursively to reformat -% all lines on the current vertical list. The first line will remain -% flush left, but all other lines will be reset flush right. The -% visible material on the last line will be left as it is, but the -% last box in all other lines will be replaced by a non-macro font -% backslash. -% -% It is very important that the current vertical list is not the main -% vertical list. -% It is assumed that the current vertical list consists of a sequence -% of \meta{box}, \meta{penalty}, \meta{glue}, with an extra glue item -% at the top of the list. It is OK if some penalty or glue item is -% missing. In case the list contains other material as well the line -% reformatting may be stopped prematurely, but there is a trick that -% allows one to put arbitrary material between the lines of the -% reformatted paragraph: rather than doing e.g. -% \begin{quote} -% |\mark|\marg{text} -% \end{quote} -% in the paragraph, do -% \begin{quote} -% |\vadjust{\vbox{\mark{|\meta{text}|}}}| -% \end{quote} -% The |\vbox| will be recognised by the paragraph reformatting -% mechanism as a container for vertical mode material that appears -% between the lines of the paragraph, so it will simply be unboxed. -% \changes{v\,2.12}{2000/11/11}{\cs{vbox} containers for vertical -% material are allowed between the lines of a reformatted -% paragraph. (LH)} -% -% Each line's horizontal list ends with -% \begin{itemize} -% \item a box (which contains the space that is to be replaced by a -% backslash), -% \item a penalty (at which the paragraph was broken), and -% \item a glue item (the |\rightskip|). -% \end{itemize} -% -% A tricky feature in the implementation is that the -% |\bgroup|--|\egroup| nesting will be off by one. The |\bgroup| at -% the beginning of a |\TD@reformat@line| will be matched by the -% |\egroup| at the end of the |\TD@reformat@line| that the first one -% calls! -% \begin{macrocode} -\def\TD@reformat@lines{% - \bgroup - \unskip - \count@=\lastpenalty \unpenalty - \setbox\z@=\lastbox - \ifvoid\z@ -% \end{macrocode} -% The recursion had already descended down to the last line of the -% paragraph, and it is now time to reformat it. -% \begin{macrocode} - \egroup - \prevdepth=\TD@prevdepth - \hbox{% - \unhbox\z@ - \unskip \unpenalty - \setbox\z@=\lastbox - \copy\TD@backslash@box - }% - \else -% \end{macrocode} -% Else there may be another line, and the |\TD@reformat@lines| recursion -% must continue to descend. Upon return the box currently in box -% register zero must be reformatted as a non-first line (flush -% right) and it cannot be the last line in the paragraph, so it is -% always correct to replace the last box by a backslash. -% \begin{macrocode} - \TD@reformat@lines - \ifvbox\z@ \unvbox\z@ \else - \hb@xt@\dimen@{% - \hfill - \unhbox\z@ - \unskip \unpenalty - \setbox\z@=\lastbox - \copy\TD@backslash@box - }% - \fi - \fi - \ifnum \count@=\z@ \else \penalty\count@ \fi - \egroup -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@reformat@par} -% The |\TD@reformat@par| macro reformats all lines (they're supposed -% to constitute a paragraph, but that isn't so important) in the -% current vertical list. The restrictions of |\TD@reformat@lines| on -% what may appear in the list apply and there must be at least two -% lines in the list. |\dimen@| is used to hold the desired width of -% reformatted paragraphs. -% -% More precisely |\TD@reformat@par| takes care of the last line of -% the paragraph and the possible |\vbox| containers for vertical -% material that may follow it. Everything in the paragraph that comes -% before the last line is handled by |\TD@reformat@lines|. -% \changes{v\,2.12}{2000/11/11}{\cs{vbox} containers for vertical -% material are allowed after the last line of a reformatted -% paragraph. (LH)} -% \begin{macrocode} -\def\TD@reformat@par{% - \unskip - \count@=\lastpenalty \unpenalty - \setbox\z@=\lastbox - \ifvbox\z@ - \bgroup - \TD@reformat@par - \egroup - \unvbox\z@ - \else\ifnum \prevgraf>\@ne - \dimen@=\@totalleftmargin - \advance \dimen@ \linewidth - \bgroup - \unskip - \count@=\lastpenalty \unpenalty - \setbox\z@=\lastbox - \TD@reformat@lines - \hb@xt@\dimen@{\hfill \unhbox\z@ \unskip}% - \else - \unskip - \prevdepth=\TD@prevdepth - \box\z@ - \fi\fi - \ifnum \count@=\z@ \else \penalty\count@ \fi -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@prevdepth} -% |\TD@prevdepth| is a macro which is used for storing the value of -% |\prevdepth| at times where \TeX\ modifies the primitive in unwanted -% ways. It should always be set globally. -% \end{macro} -% -% -% \begin{macro}{\TD@begin@tclpar} -% The |\TD@begin@tclpar| macro is called when a paragraph in a -% \texttt{tcl} or \texttt{tcl*} environment is about to start. It -% takes care of setting up things so that the paragraph can later be -% reformatted using |\TD@reformat@par|, but it also has to make sure -% that this reformatting doesn't affect the way the paragraph blends -% in with vertical material before and after it. -% -% Reformatting requires that the paragraph is first built in -% restricted vertical mode, i.e., it has to be built in an explicit -% |\vbox|. A problem with this is however that it changes the value of -% |\prevdepth|, which must therefore be explicitly restored. -% \begin{macrocode} -\def\TD@begin@tclpar{% - \xdef\TD@prevdepth{\the\prevdepth}% - \setbox\z@=\vbox\bgroup - \color@begingroup - \prevdepth=\TD@prevdepth - \indent -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@end@tclpar} -% The |\TD@end@tclpar| macro ends a paragraph begun by -% |\TD@begin@tclpar|, reformats it (|\TD@reformat@par|), and -% contributes it to the surrounding vertical list. The |\begingroup| -% and |\endgroup| are there to sort things out in case the recursion -% in |\TD@reformat@par| fails to match as intended. The second -% |\@@par| sees to that the page builder is exercised (without it, -% several pages may go onto the main vertical list without anything -% being shipped out). -% \begin{macrocode} -\def\TD@end@tclpar{% - \@@par - \begingroup - \skip@=\lastskip - \TD@reformat@par - \vskip\skip@ - \endgroup - \xdef\TD@prevdepth{\the\prevdepth}% - \color@endgroup - \egroup - \unvbox\z@ - \prevdepth=\TD@prevdepth - \@@par -} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\TD@line@indent} -% |\TD@line@indent| is a |\count| register holding the indentation of -% the current line, in number of spaces. |\TD@line@indent| should -% always be assigned globally. -% \begin{macrocode} -\newcount\TD@line@indent -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@par@setup} -% This macro sets up various paragraph formatting parameters for the -% normal mode. It mainly consists of code from |\macro@code| of -% \package{doc}. -% \begin{macrocode} -\def\TD@par@setup{% -% \end{macrocode} -% -% In theory a \texttt{tcl} environment should consist of a -% \texttt{trivlist} environment, but the empty space before and after -% the environment should not be too large. -% \begin{macrocode} - \topsep\MacrocodeTopsep -% \end{macrocode} -% -% The next parameter we set is |\@beginparpenalty|, in order -% to prevent a page break before such an environment. -% \begin{macrocode} - \@beginparpenalty\predisplaypenalty -% \end{macrocode} -% -% We then start a |\trivlist|, set |\parskip| back to -% zero and start an empty |\item|. -% \changes{ \package{doc} v\,1.9b}{1993/12/03}{Forcing any label -% from macro env.} -% \begin{macrocode} - \if@inlabel\leavevmode\fi - \trivlist - \parskip\z@skip - \item[]% -% \end{macrocode} -% However, the \texttt{trivlist} environment is only started to make -% standard \LaTeX\ happy (and to have the various list-related -% measurements properly calculated). Everything below will instead -% by done with \TeX\ primitives. -% \changes{ \package{pasdoc} v\,1.31}{1999/09/02}{\cs{parshape} -% assignment added. (LH)} -% \changes{v\,2.10}{2000/10/08}{\cs{parshape} assignment removed (now -% done in \cs{TD@begin@tclpar}). (LH)} -% -% It is important that the change to a special font does not take -% place before the above |\item|, otherwise a change to -% |\baselineskip| will affect the paragraph above. -% \begin{macrocode} - \macro@font - \frenchspacing -% \end{macrocode} -% -% \leavevmode -% \changes{v\,2.12}{2000/11/11}{Assignment to \cs{TD@backslash@box} -% moved from \cs{TD@typography} to here, so that the size will be -% right. (LH)}^^A -% One escape symbol that is particularly common is a single -% backslash, and this is stored in the |\TD@backslash@box| box. As -% some encodings (e.g.\ \texttt{OT1}) does not contain a backslash, -% these escape backslashes are made with |\textbackslash|, rather -% than an explicit character. -% \begin{macrocode} - \sbox\TD@backslash@box{\TD@nontcl@font\textbackslash}% -% \end{macrocode} -% -% The |\rightskip| is given a generous stretchability of |\linewidth| -% so that it doesn't matter too much if the lengths of lines in the -% paragraph varies. Decreasing this value would make the nesting in -% the code less important. -% \begin{macrocode} - \parindent=\@totalleftmargin - \advance \parindent \MacroIndent - \leftskip=\z@skip - \rightskip=\z@ \@plus \linewidth\relax -% \end{macrocode} -% The next two lines are from the definition of the -% \texttt{macrocode} environment, and I (LH) have no idea what they are -% good for, but I suppose I can keep them, at least for now. -% \begin{macrocode} - \global\@newlistfalse - \global\@minipagefalse -% \end{macrocode} -% \changes{ \package{pasdoc} v\,1.31}{1999/09/02}{Made list -% environments indent line numbers. (LH)} -% Line numbers are inserted using |\everypar|. -% \begin{macrocode} - \ifcodeline@index - \everypar={\llap{\PrintCodelineNo\ }}% - \else - \everypar={}% - \fi -% \end{macrocode} -% -% These commands replace \package{doc}'s final module processing -% macros with macros that work in the \texttt{tcl} environment. -% \begin{macrocode} - \let\pm@module=\TD@pm@module - \let\star@module=\TD@star@module - \let\slash@module=\TD@slash@module -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@setup@parshape} -% This macro sets the shape of the current paragraph, primarily based -% on the value in |\TD@line@indent|, and makes the final indentation -% of the first line. By the time it gets called, there usually already -% is some material (|\indent|, codeline number, and possibly a -% \package{docstrip} guard) in the paragraph horizontal list. -% -% The basic area in which the paragraph material is to be put has a -% left margin at |\@totalleftmargin|${}+{}$|\MacroIndent| and a right -% margin at |\@totalleftmargin|${}+{}$|\linewidth| (in both cases the -% position is that much to the right of the left edge of the galley). -% The printed codeline number (if there is one) will be put to the -% left of the left margin, but all other material is indented at least -% the width of another |\TD@line@indent| spaces. In the first line -% that will be done through an explicit kern, but in subsequent lines -% it will instead be done through a |\parshape| assignment. On these -% subsequent lines, there will be an additional indentation of\/ -% $1\,\mathrm{em}$ to mark the continuation. -% -% When the paragraph is broken, the right margin will be moved to the -% right by the width of a space minus the width of the -% |\TD@backslash@box|. The reason for this is that the paragraph will -% be broken with spaces (from |\TD@breakable@space|) at the end of -% lines, but that these spaces will later be replaced by the -% backslash in |\TD@backslash@box|. As that doesn't happen in the -% very last line of the paragraph however, something special must be -% done there. The option chosen is to give the |\parfillskip| a -% nonzero natural width. -% -% The length |\@totalleftmargin|${}+{}$|\MacroIndent| is put in -% |\parindent| at the beginning of the environment. -% \begin{macrocode} -\def\TD@setup@parshape{% - \parfillskip=\fontdimen\tw@\font \@plus 1fil% - \advance \parfillskip -\wd\TD@backslash@box - \dimen@=\MacroIndent - \advance \dimen@ \TD@line@indent\fontdimen\tw@\font - \advance \dimen@ 1em% - \dimen@ii=\linewidth - \advance \dimen@ii -\dimen@ - \dimen4=\linewidth - \advance \dimen@ \@totalleftmargin - \advance \dimen4 \@totalleftmargin - \advance \dimen@ii -\parfillskip - \advance \dimen4 -\parfillskip - \parshape \tw@ \z@ \dimen4 \dimen@ \dimen@ii -% \end{macrocode} -% Then one just needs one more kern to indent the first line -% properly. -% \begin{macrocode} - \kern \TD@line@indent\fontdimen\tw@\font -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@trace@pardimen} -% This macro is for tracing dimens that are of interest for paragraph -% breaking. Its call syntax is -% \begin{quote} -% |\TD@trace@pardimen|\marg{text}\marg{dimen} -% \end{quote} -% where \meta{text} will be written to the log file to identify the -% dimension, and \meta{dimen} is the dimen register in question (it -% can be anything that can appear after |\the|). -% -% To reduce the amount of text written, this macro only does anything -% if the \TeX\ parameter |\tracingparagraphs| is positive. -% \begin{macrocode} -%<*partrace> -\def\TD@trace@pardimen#1#2{% - \ifnum \tracingparagraphs>\z@ - \immediate\write\m@ne{#1 \the#2}% - \fi -} -%</partrace> -% \end{macrocode} -% \changes{ \package{pasdoc} v\,1.21}{1999/08/15}{Added macro and -% some calls of it. All of those are however surrounded by -% \texttt{partrace} guards. (LH)} -% \end{macro} -% -% -% -% \subsection{User interface} -% -% This subsection defines the actual environment and the -% commands and parameters intended to be user-definable. -% -% -% \begin{macro}{\settabsize} -% \changes{v\,2.12}{2000/11/09}{New command for setting the tab size. -% (LH)} -% \begin{macro}{\TD@tab@size} -% \changes{v\,2.12}{2000/11/09}{New name for \cs{c@tabSize}; no longer a -% count register. (LH)} -% The |\TD@tab@size| control sequence stores (as a |\chardef| token) -% the number of spaces that are equivalent to one tab; the default -% value is 8. To set this number, one uses the command |\settabsize|, -% which has the syntax -% \begin{quote} -% |\settabsize|\marg{new size} -% \end{quote} -% The effect of |\settabsize| is local. -% \begin{macrocode} -\newcommand*\settabsize[1]{\chardef\TD@tab@size=#1\relax} -\settabsize{8} -% \end{macrocode} -% \end{macro}\end{macro} -% -% -% \begin{environment}{tcl} -% \begin{environment}{tcl*} -% This is some kind of a definition. There are aspects of the -% interaction with \texttt{trivlist} that I (LH) don't understand, -% but it appears to work. -% \begin{macrocode} -\newenvironment{tcl}{% - \TD@general - \TD@typography - \TD@par@setup - \TD@command -}{% - \global\@inlabelfalse - \endtrivlist -} -% \end{macrocode} -% \begin{macrocode} -\newenvironment{tcl*}{% - \TD@visible@whitespace - \TD@general - \TD@typography - \TD@par@setup - \TD@command -}{% - \global\@inlabelfalse - \endtrivlist -} -% \end{macrocode} -% \end{environment}\end{environment} -% -% \begin{macro}{\tclverb} -% \begin{macro}{\TD@verb} -% The |\tclverb| macro is for typesetting short passages of \Tcl\ code -% which one does not want to have a special paragraph for. It is -% similar to the standard \LaTeX\ command |\verb|, but it has a couple -% of extra features. One is that spaces that are not followed by more -% whitespace are discretionary breakpoints, just as in the \texttt{tcl} -% environment. Another is that a newline can be escaped by putting a -% backslash at the end of an input line. Such an escaped newline will -% count as a space, and whitespace at the beginning of the line -% following it will be ignored. A percent character immediately -% following an escaped newline will also be ignored. -% -% |\tclverb| has a |*| form |\tclverb*|, which is analogous to the -% standard \LaTeX\ |\verb*|, i.e., spaces are typeset using ``visible -% space'' symbols. -% \begin{macrocode} -\newcommand\tclverb{% - \relax\ifmmode\hbox\else\leavevmode\null\fi - \bgroup - \@ifstar{\TD@visible@whitespace\TD@verb}\TD@verb -} -% \end{macrocode} -% \DoNotIndex{\ ,\^,\\} -% \begin{macrocode} -\def\TD@verb{% - \let\TD@active@backslash@i=\TD@active@backslash@v - \let\TD@active@CR=\TD@active@CRv - \let\TD@breakable@space=\TD@discretionary@space - \TD@general - \catcode`\^^I=\active - \catcode`\ =\active - \catcode`\\=\active - \TD@typography - \verbatim@font - \sbox\TD@backslash@box{\TD@nontcl@font\textbackslash}% - \@sverb -} -% \end{macrocode} -% \end{macro}\end{macro} -% -% -% \begin{macro}{\TclInput} -% The |\TclInput| macro is very much like the standard \LaTeX\ -% |\input|, but it is intended to be used in command mode, for -% inputting \Tcl\ files that have not been marked up. |\input| would -% work in this case, but there would be errors at the first and last -% lines of the |\input|ted file. -% \begin{macrocode} -\newcommand\TclInput[1]{% - \IfFileExists{#1}{% - \@addtofilelist{#1}% - \begingroup - \TD@normal - \let\TD@start@n@line=\TD@start@n@line@i - \expandafter\TD@start@n@line - \@@input\@filef@und\TD@percent@token - \endgroup - }{\PackageError{tcldoc}{No file #1}\@eha}% -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\MakeShortTclverb} -% This definition follows \package{doc}'s |\MakeShortVerb| pretty -% close. -% \DoNotIndex{\~} -% \begin{macrocode} -\newcommand\MakeShortTclverb[1]{% - \expandafter\ifx \csname cc\string#1\endcsname\relax - \PackageInfo{tcldoc}{% - Made \expandafter\@gobble\string#1 a short % - reference for \string\tclverb}% - \add@special{#1}% - \expandafter\xdef \csname cc\string#1\endcsname{\the\catcode`#1}% - \begingroup - \lccode`\~=`#1% - \lowercase{% - \global\expandafter\let - \csname ac\string#1\endcsname ~% - \gdef~{\tclverb~}}% - \endgroup - \global\catcode`#1\active - \else - \PackageInfo{tcldoc}{% - \expandafter\@gobble\string#1 already a short verb % - reference}% - \fi -} -% \end{macrocode} -% \end{macro} -% -% -% \section{Miscellaneous markup features} -% -% \subsection{Namespaces} -% -% \changes{v\,2.10}{2000/10/13}{Added namespace support. (LH)} -% -% \begin{macro}{\setnamespace} -% \begin{macro}{\TD@namespace} -% Since it is common that many identifiers in the same namespace are -% defined in sequence, one can specify a default namespace to use for -% all commands where no explicit namespace is given. This is done -% using the |\setnamespace| command, whose syntax is -% \begin{quote} -% |\setnamespace|\marg{namespace} -% \end{quote} -% This converts the \meta{namespace} to a harmless character string -% and locally assigns it to the |\TD@namespace| macro, which stores -% the current default namespace. -% \begin{macrocode} -\newcommand\setnamespace[1]{\MakeHarmless\TD@namespace{#1}} -% \end{macrocode} -% At the beginning of a document, the default namespace is the global -% namespace, which is represented by the empty string. -% \begin{macrocode} -\let\TD@namespace\@empty -% \end{macrocode} -% \end{macro}\end{macro} -% -% \begin{macro}{\buildname} -% \changes{v\,2.13}{2000/12/16}{Added \cs{@empty} after test for -% \cs{NoValue}, so that it works for empty arguments. (LH)} -% \begin{macro}{\namespacesepator} -% \changes{v\,2.12}{2000/11/25}{Command added. (LH)} -% The |\buildname| macro builds a qualified name from a namespace and -% a name tail. It has the syntax -% \begin{quote} -% |\buildname|\marg{namespace}\marg{name} -% \end{quote} -% where \meta{name} is a harmless character sequence and -% \meta{namespace} is a harmless character sequence or the token -% |\NoValue|. If \meta{namespace} is |\NoValue| then the default -% namespace is used. |\buildname| does all processing at expand-time. -% -% If the namespace is the empty string (the global namespace) then -% \meta{name} is returned without a `|::|' prefix; this is for the -% sake of compatibility with pre-v\,8 \Tcl s. -% \begin{macrocode} -\newcommand\buildname[2]{% - \ifx \NoValue#1\@empty - \ifx \@empty\TD@namespace \else - \TD@namespace\namespaceseparator - \fi - \else - \ifx $#1$\else #1\namespaceseparator \fi - \fi - #2% -} -% \end{macrocode} -% The |\namespaceseparator| command typesets a namespace separator. By -% default it is two colons separated by a penalty, but the user may -% redefine it. -% \begin{macrocode} -\DeclareRobustCommand\namespaceseparator{:\penalty\hyphenpenalty:} -% \end{macrocode} -% \end{macro}\end{macro} -% -% -% \subsection{\texttt{macro}-like environments} -% -% This subsection contains the definitions of a couple of environments -% which, like \package{doc}'s \texttt{macro}, are for marking up the -% document (what is defined and where). These environments are defined -% using the |\New|\-|Macro|\-|Environment| command of the \package{xdoc2} -% package. -% \changes{ \package{pasdoc} v\,1.40}{1999/12/05}{\texttt{macro}-like -% environments redefined. (LH)} -% \changes{v\,2.00}{2000/07/17}{\texttt{macro}-like environments are -% defined using the \cs{NewMacroEnvironment} command. The -% \cs{TD@identifier}, \cs{SpecialMainTclIndex}, and -% \cs{PrintTclName} macros were removed. (LH)} -% \changes{v\,2.12}{2000/11/26}{Using starred form of -% \cs{NewMacroEnvironment} for the \texttt{variable}, \texttt{proc}, -% \texttt{arrayvar}, and \texttt{arrayentry} environments, so that -% the marginal headings can be broken. (LH)} -% -% -% \begin{environment}{variable} -% The \texttt{variable} environment has the syntax -% \begin{quote} -% |\begin{variable}|\oarg{namespace}\marg{variable} -% \end{quote} -% It makes a marginal heading, index entry, etc.\@ for the -% \meta{variable} variable in the \meta{namespace} namespace -% (if specified, otherwise in the default namespace). -% \begin{macrocode} -\NewMacroEnvironment*{variable}% - {\XD@grab@harmless@oarg\XD@grab@harmless\relax}{2}% - {\XDParToMargin{\MacroFont\buildname{#1}{#2} \normalfont (var.)}}% - {\TD@main@index{#1}{#2}{var.}{}}% - {{\buildname{#1}{#2}}{\texttt{\buildname{#1}{#2}} variable}} - {}% -% \end{macrocode} -% \end{environment} -% -% \begin{environment}{proc} -% The \texttt{proc} environment has the syntax -% \begin{quote} -% |\begin{proc}|\oarg{namespace}\marg{proc} -% \end{quote} -% It makes a marginal heading, index entry, etc.\@ for the \meta{proc} -% procedure in the \meta{namespace} namespace (if specified, otherwise -% in the default namespace). -% \begin{macrocode} -\NewMacroEnvironment*{proc}% - {\XD@grab@harmless@oarg\XD@grab@harmless\relax}{2}% - {\XDParToMargin{\MacroFont\buildname{#1}{#2} \normalfont (proc)}}% - {\TD@main@index{#1}{#2}{proc}{}}% - {{\buildname{#1}{#2}}{\texttt{\buildname{#1}{#2}} proc}} - {}% -% \end{macrocode} -% \end{environment} -% -% \begin{environment}{arrayvar} -% \changes{v\,2.00}{2000/07/17}{Environment added. (LH)} -% \changes{v\,2.12}{2000/11/09}{Made last argument optional. (LH)} -% \changes{v\,2.13}{2000/12/15}{Not using \cs{meta} for the -% \meta{index-des} argument. (LH)} -% \begin{environment}{arrayentry} -% \changes{v\,2.02}{2000/08/21}{Environment added. (LH)} -% The \texttt{arrayvar} and \texttt{arrayentry} environments are for -% array variables; \texttt{arrayvar} is for the array as a whole, -% whereas \texttt{arrayentry} is for individual entries in the array -% that (for some reason) are important enough to warrant special -% attention. The respective syntaxes are -% \begin{quote} -% |\begin{arrayvar}|\oarg{namespace}\marg{array}\oarg{index-des}\\ -% |\begin{arrayentry}|\oarg{namespace}\marg{array}\marg{entry} -% \end{quote} -% Here \meta{array} is the name of an array variable, \meta{entry} is -% the name of an entry, and \meta{index-des} is a short piece of text -% (seldom more than one word) which describes what is used as indices -% into that array. -% \begin{macrocode} -\NewMacroEnvironment*{arrayvar}{% - \XD@grab@harmless@oarg\XD@grab@harmless\relax\XD@grab@harmless@oarg -}{3}% - {\XDParToMargin{\MetaNormalfont\MacroFont \buildname{#1}{#2}% - \ifx \NoValue#3% - \space\normalfont (array)% - \else - \penalty\hyphenpenalty(\mbox{\meta@font@select#3})% - \fi - }}% - {\TD@main@index{#1}{#2}{array}{% - \ifx \NoValue#3\else - \LevelSorted{#3}{\protect\mbox{\textit{#3}} entries}% - \fi - }}% - {{\buildname{#1}{#2}}{\texttt{\buildname{#1}{#2}} array}} - {}% -% \end{macrocode} -% \begin{macrocode} -\NewMacroEnvironment*{arrayentry}{% - \XD@grab@harmless@oarg\XD@grab@harmless\relax\XD@grab@harmless\relax -}{3}% - {\XDParToMargin{% - \MetaNormalfont\MacroFont \buildname{#1}{#2}% - \penalty\hyphenpenalty(#3)% - }}% - {\TD@main@index{#1}{#2}{array}{\LevelSorted{#3}{\texttt{#3}}}}% - {{\buildname{#1}{#2}(#3)}{\texttt{\buildname{#1}{#2}(#3)}}} - {}% -% \end{macrocode} -% \end{environment}\end{environment} -% -% \begin{macro}{\describestring} -% \changes{v\,2.01}{2000/08/12}{Command added. (LH)} -% \changes{v\,2.12}{2000/11/21}{Optional argument added. (LH)} -% \changes{v\,2.13}{2000/12/16}{Second optional argument added. (LH)} -% The |\describestring| command has the syntax -% \begin{quote} -% |\describestring|\oarg{type}\oarg{namespace}\marg{string} -% \end{quote} -% It is similar to \package{xdoc}'s own |\describe|\-|cs|\-|family| -% command, but it has a couple of extra features which are connected -% to the optional arguments and it doesn't prepend a backslash to -% the name of the thing being described. When the \meta{type} argument -% is present, it is taken as a ``type declaration'' of the -% \meta{string} being described and `(\meta{type})' will be put as a -% suffix to the \meta{string}. When the \oarg{namespace} argument is -% present it means that the string being described is really the name -% of something (e.g.\ a procedure or variable) which exists in a -% namespace, and the complete name is formed by passing both -% \meta{namespace} and \meta{string} as arguments to |\buildname|. -% Note that an empty \meta{namespace} argument is not quite the -% same thing as no \meta{namespace} argument. -% \begin{macrocode} -\NewDescribeCommand{\describestring}{% - \XD@grab@oarg\XD@grab@harmless@oarg\XD@grab@harmless{}% -}{3}{% - \GenericDescribePrint{% - \MetaNormalfont\MacroFont - \ifx \NoValue#2\@empty - #3% - \else - \buildname{#2}{#3}% - \fi - \ifx \NoValue#1\@empty \else\ \normalfont(#1)\fi - }% - \begingroup - \def\meta##1{(##1)}% - \unrestored@protected@xdef\@gtempa{% - #3\ifx \NoValue#2\@empty \else\ifx $#2$\else, #2\fi\fi - }% - \endgroup - \IndexEntry{% - \LevelSorted{\@gtempa}{% - \texttt{% - \ifx \NoValue#2\@empty - \protect\MetaNormalfont#3% - \else - \buildname{#2}{#3}% - \fi - }% - \ifx \NoValue#1\@empty \else\space(#1)\fi - }% - }{usage}{\thepage}% -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\TD@main@index} -% \changes{v\,2.10}{2000/10/14}{Generalized macro. (LH)} -% \changes{v\,2.12}{2000/11/25}{Sorting by base name first, not by -% namespace first. (LH)} -% The |\TD@main@index| macro has the syntax -% \begin{quote} -% |\TD@main@index|\marg{namespace}\marg{name}\marg{type}^^A -% \marg{extra} -% \end{quote} -% It makes a \texttt{main} index entry. The top level of this entry -% is like an entry for the \meta{name} object of type \meta{type} in -% the \meta{namespace} namespace. The entry may have one or more -% sublevels\footnote{But no more than one extra level is recommended, -% as this macro is intended to be redefinable to make a two-level -% entry by default and \package{makeindex} can handle at most three -% levels.} specified in the \meta{extra}; these are then made using -% explicit |\LevelSame| or |\LevelSorted| commands. \meta{name} and -% \meta{namespace} are as for the |\buildname| macro, whereas -% \meta{type} is a description, e.g. `\texttt{proc}', that gets -% appended to the printed text of the entry's top level. -% \begin{macrocode} -\def\TD@main@index#1#2#3#4{% - \XDMainIndex{% - \LevelSorted{% - #2% - \ifx \NoValue#1% - \ifx \@empty\TD@namespace \else , \TD@namespace\fi - \else - \ifx $#1$\else , #1\fi - \fi - }{\texttt{\buildname{#1}{#2}} (#3)}% - #4% - }% -} -% \end{macrocode} -% \end{macro} -% -% -% \subsection{Regular expressions and friends} -% -% I have noticed that when one is describing the syntax of some \Tcl\ -% command\slash procedure, one often ends up writing argument lists with -% lots of optional, repeated, or variant parts. In general one can of -% course specify these using BNF syntax diagrams, but whereas occurrences -% of the three syntactic constructions mentioned above are plenty, -% there are much fewer occurrences of for example nesting. Since -% furthermore even the simplest optional or repeated element -% requires an extra syntactic term to be defined, it becomes interesting -% to search for an alternative way of specifying these constructions. -% One that is close at hand is that of regular expressions, as that is -% anyway a part of the \Tcl\ language. -% -% \begin{macro}{\regstar} -% \begin{macro}{\regplus} -% \begin{macro}{\regopt} -% These commands are used to modify the meaning of another syntactic -% element. |\regstar| puts a star $^*$ on something, meaning it is -% repeated zero or more times. |\regplus| puts a plus $^+$ on -% something, meaning it is repeated one or more times. |\regopt| puts -% a question mark $^?$ on something, meaning it is optional. Normally -% these commands are simply put right after what they should modify, -% but if the ``something'' is a regular expression block, i.e., a -% \texttt{regexp} environment, then these things should be put as the -% \meta{modifier} in -% \begin{quote} -% |\begin{regexp}|\oarg{modifier}\\ -% | |\textellipsis\\ -% |\end{regexp}| -% \end{quote} -% In particular, they should \emph{not} be put after the -% |\end{regexp}|, as that may impair the placement of the exponent. -% \begin{macrocode} -\newcommand\regstar{\ensuremath{^*}} -\newcommand\regplus{\ensuremath{^+}} -\newcommand\regopt{\ensuremath{^?}} -% \end{macrocode} -% \end{macro}\end{macro}\end{macro} -% -% \begin{macro}{\TD@delim@size} -% \begin{macro}{\TD@delim@size@G} -% These control sequences are used in determining what size the -% delimiters (parentheses) around a regular expression block should -% have. The values specify what should be the least size of a -% delimiter that bracket a piece of text, and are interpreted as -% follows: \(0={}\)normal size, \(1={}\)|\big| size, \(2={}\)|\Big| -% size, \(3={}\)|\bigg| size, and $4$ and above is |\Bigg| size. -% -% |\TD@delim@size@G| is a macro which is always set globally and -% which keeps track of the delimiter size at the innermost level. -% |\TD@delim@size| is a |\count| register that is assigned locally -% and is used for keeping track of delimiter sizes at all other -% levels. Commands like |\word|, which contribute a delimiter to some -% piece of text, should set |\TD@delim@size@G|. -% \begin{macrocode} -\newcount\TD@delim@size -\gdef\TD@delim@size@G{0} -% \end{macrocode} -% \end{macro}\end{macro} -% -% \begin{environment}{regexp} -% The \texttt{regexp} environment embarks upon a rather tricky scheme -% of boxing and unboxing to determine the proper delimiter size. The -% basic idea is that the contents of the environment are first typeset -% in an \texttt{lrbox} environment, and |\TD@delim@size@G| is set to -% its proper value. Then the left delimiter is set at this size, the -% saved box is unboxed, and finally the right delimiter is set. All -% through the process, the value of |\TD@delim@size@G| at the -% beginning of the \texttt{regexp} environment has been saved in -% |\TD@delim@size| and at the end |\TD@delim@size@G| is set to the -% maximum of its old value and one plus its value inside the -% \texttt{regexp} environment. This makes it possible to nest -% \texttt{regexp} environments. -% -% It is not quite that easy, though. A regular expression can consist -% of several branches, which must be separated by vertical bars. -% These bars should be the same size as the delimiters around the -% regular expression, and hence the bars cannot be typeset before -% every branch has been typeset. Therefore the \texttt{regexp} -% environment starts an extra horizontal list (the |\hbox|) for the -% sole purpose of storing the branches that have already been typeset -% (and \emph{only} these). Each branch is put on the list as a box. -% When all branches have been typeset, they are first removed from the -% list (by |\TD@join@branches|), and then they are inserted again, but -% this time they are unboxed and separated by suitable delimiters. -% Finally the |\hbox| is ended and almost immediately unboxed. -% -% \begin{macrocode} -\newenvironment{regexp}[1][]{% - \leavevmode - \def\TD@modifier{#1}% - \TD@delim@size=\TD@delim@size@G - \let\regalt=\TD@regalt - \setbox\z@=\hbox\bgroup - \TD@delim@size=\z@ - \begin{lrbox}{\z@}% - \gdef\TD@delim@size@G{0}% - \ignorespaces -}{% - \end{lrbox}% - \ifnum \TD@delim@size@G>\TD@delim@size - \TD@delim@size=\TD@delim@size@G\relax - \fi - {\TD@join@branches}% - \unhbox\z@ - $\TD@size@delimiter)\TD@modifier$% - \advance \TD@delim@size \@ne - \xdef\TD@delim@size@G{\the\TD@delim@size}% - \egroup - \ifnum \TD@delim@size@G<\TD@delim@size - \xdef\TD@delim@size@G{\the\TD@delim@size}% - \fi - \unhbox\z@ -} -% \end{macrocode} -% \end{environment} -% -% \begin{macro}{\TD@join@branches} -% \changes{v\,2.12}{2000/11/13}{Made penalty for linebreak after -% \cs{regalt} depend on the delimiter size. (LH)} -% The |\TD@join@branches| macro uses |\lastbox| to retrieve all boxes -% in the current horizontal list, and unboxes them. Between the -% unboxed boxes it puts a |\vert| delimiter, and before the first it -% puts a left parenthesis. Both will be the current delimiter size. -% \begin{macrocode} -\def\TD@join@branches{% - \setbox\z@=\lastbox - \ifvoid\z@ - $\TD@size@delimiter($% - \else - {\TD@join@branches}% - \unhbox\z@ - ~$\TD@size@delimiter\vert$% - \count@=\TD@delim@size - \advance \count@ \@ne - \multiply \count@ -\@lowpenalty - \penalty\count@\ % - \fi -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\regalt} -% \begin{macro}{\TD@regalt} -% The |\regalt| command is used in a \texttt{regexp} environment -% to separate two branches. It ends an \texttt{lrbox} environment, -% puts the box collected in the surrounding horizontal list (which -% was begun by the |\hbox| in |\lrbox|), and begins a new -% \texttt{lrbox} environment. As this would not make sense outside a -% \texttt{regexp} environment however, the |\regalt| command does by -% default only produce an error message. The ``real'' definition is -% kept in |\TD@regalt| and the \texttt{regexp} environment locally -% redefines |\regalt|. -% \begin{macrocode} -\newcommand\regalt{% - \PackageError{tcldoc}{% - Lonely \protect\regalt--perhaps a missing regexp environment% - }\@eha -} -\def\TD@regalt{% - \end{lrbox}% - \box\z@ - \ifnum \TD@delim@size@G>\TD@delim@size - \TD@delim@size=\TD@delim@size@G\relax - \fi - \begin{lrbox}{\z@}% - \gdef\TD@delim@size@G{0}% -} -% \end{macrocode} -% \end{macro}\end{macro} -% -% \begin{macro}{\TD@size@delimiter} -% This macro expands to nothing, |\big|, |\Big|, |\bigg|, or |\Bigg| -% depending on the value of |\TD@delim@size|. -% \begin{macrocode} -\def\TD@size@delimiter{% - \ifcase\TD@delim@size - \or \expandafter\big \or \expandafter\Big \or - \expandafter\bigg \else \expandafter\Bigg - \fi -} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\word} -% \changes{v\,2.10}{2000/10/13}{Reimplemented like the new \cs{meta}. -% (LH)} -% \changes{v\,2.12}{2000/11/21}{Using braces instead of angle brackets. -% (LH)} -% This command works like |\meta|, but the argument is enclosed in -% braces rather than angle brackets and it communicates with the -% \texttt{regexp} environment (the braces count as a smallest-size -% delimiter). Something marked out using |\word| rather than |\meta| -% is meant to always denote a separate \Tcl\ word. -% \begin{macrocode} -\DeclareRobustCommand\word[1]{% - \leavevmode - \ifmmode \expandafter \nfss@text \fi - {% - $\{$% - \meta@font@select - \edef\meta@hyphen@restore - {\hyphenchar\the\font\the\hyphenchar\font}% - \hyphenchar\font\m@ne - \language\l@nohyphenation - #1\/% - \meta@hyphen@restore - $\}$% - }% - \ifnum \TD@delim@size@G<\@ne \gdef\TD@delim@size@G{1}\fi -} -% \end{macrocode} -% \end{macro} -% -% -% \subsection{Logos} -% -% \begin{macro}{\Tcllogo} -% \changes{v\,2.03}{2000/09/15}{Macro added. (LH)} -% The |\Tcllogo| command makes a \Tcl\ ``logo'', which simply consists -% of the three letters `T', `c', and `l' in the current font. The only -% special thing about it is that there is a kern between the `T' and -% the `c', since most fonts doesn't have that kern. No work has been -% put into tuning the kern, but the size is about right. As a -% comparison the kern between `T' and `o' in \texttt{cmr10} is -% $-0.083334\,\mathrm{em}$. -% \begin{macrocode} -\DeclareRobustCommand\Tcllogo{T\kern-0.1em cl} -%</pkg> -% \end{macrocode} -% \end{macro} -% -% \changes{v\,2.03}{2000/09/15}{\cs{DescribeResource} command removed. -% Just in case anyone is interested in using it, I have included it as -% a code example in the source for the \package{xdoc} package. (LH)} -% -% -% \section{The \package{tcldoc} class} -% -% \subsection{Pre-options definitions} -% -% \begin{macro}{\if@rtkinenc@} -% Switch. True iff the \package{rtkinenc} package should be loaded. -% It starts out false. -% \begin{macrocode} -%<*class> -\newif\if@rtkinenc@ -% \end{macrocode} -% \end{macro} -% -% -% \subsection{Option declarations and processing} -% -% \begin{option}{a5paper} -% \begin{option}{olddocinclude} -% The \texttt{a5paper} (to the \package{article} document class) and -% the \texttt{olddocinclude} (to the \package{xdoc} package) are not -% supported for the \package{tcldoc} class. -% \begin{macrocode} -\DeclareOption{a5paper}{% - \ClassError{tcldoc}{The a5paper option is not supported}\@eha -} -\DeclareOption{olddocinclude}{% - \ClassError{tcldoc}{The olddocinclude option is not supported}\@eha -} -% \end{macrocode} -% \end{option}\end{option} -% -% \begin{option}{macinputenc} -% The \texttt{macinputenc} option enables some special code for -% supporting the typesetting of \Tcl\ code written for the Macintosh -% input encoding (cf.\ the \texttt{applemac} option to the -% \package{inputenc} package). -% \begin{macrocode} -\DeclareOption{macinputenc}{% - \PassOptionsToPackage{applemac}{rtkinenc}% - \@rtkinenc@true -} -% \end{macrocode} -% \end{option} -% -% -% \begin{macrocode} -\DeclareOption*{% - \PassOptionsToClass{\CurrentOption}{article}} -% \end{macrocode} -% -% -% -% Input a local configuration file, if it exists. -% \begin{macrocode} -\InputIfFileExists{tcldoc.cfg} - {\typeout{*************************************^^J% - * Local config file tcldoc.cfg used^^J% - *************************************}} - {} -% \end{macrocode} -% -% -% -% \begin{macrocode} -\ProcessOptions\relax -% \end{macrocode} -% -% \subsection{Loading the base class} -% -% \begin{macrocode} -\LoadClass{article} -% \end{macrocode} -% -% -% \subsection{Input encoding and font representations} -% -% There are some rather tricky issues concerning interpretation of the -% input in \Tcl\ code. If the |\MacroFont| font contains a character that -% correctly represents a character in the input, then that character is -% obviously what one would like to appear in the typeset output. If no -% font in the entire \TeX\ system contains a character that looks like -% the one in the input, then just as obviously must one examine whether -% there exists some other method of specifying that character. In the -% case of \Tcl\ code, a suitable method seems to be to typeset the -% equivalent |\x|\meta{dd} escape sequence instead. It is for the -% purpose of being able to detect these cases that the \package{tcldoc} -% class (if the user so requests) loads the \package{rtkinenc} package, -% rather than the standard \LaTeX\ \package{inputenc} package. -% -% The problem of determining for each input character which method of -% representation that should be used---single character or escape -% sequence---does not have a unique solution. Therefore the default -% set-up is to not define any special fakes at all, which means the -% escape sequence method will be chosen in the doubtful cases. There are -% also a couple of options for the \package{tcldoc} class that define -% all (or nearly all) possible fakes---the difference between them lie -% in which fonts are assumed to be present in the system. A user who -% does not like any of these predefined options also has the option of -% putting the corresponding |\Declare|\-|Text|\-|Default|\textellipsis -% \ commands directly into the \texttt{tcldoc.cfg} file. -% -% \begin{macrocode} -\if@rtkinenc@ - \RequirePackage{rtkinenc} -%</class> -% \end{macrocode} -% -% \begin{macro}{\InputModeCode} -% \begin{macro}{\SetUnavailableAction} -% \begin{macro}{\DeclareInputMath} -% \begin{macro}{\RIE@undefined} -% The \package{tcldoc} package uses some commands defined by the -% \package{rtkinenc} package, but since \package{rtkinenc} is not -% required by the \package{tcldoc} package, the \package{tcldoc} -% package must provide its own definitions, even though these can be -% no-ops. Definition of these commands is delayed until -% |\begin|\nolinebreak[1]|{document}| to avoid problems if the user -% loads the \package{rtkinenc} package after the \package{tcldoc} -% package. -% \begin{macrocode} -%<*pkg> -\AtBeginDocument{% - \providecommand*\InputModeCode{}% - \providecommand*\SetUnavailableAction[1]{}% - \providecommand*\DeclareInputMath[2]{}% - \providecommand*\RIE@undefined[1]{\@inpenc@undefined}% -} -%</pkg> -% \end{macrocode} -% \end{macro}\end{macro}\end{macro}\end{macro} -% -% \begin{macro}{\.} -% \begin{macro}{\H} -% \begin{macro}{\textemdash} -% \begin{macro}{\textendash} -% \begin{macro}{\textexclamdown} -% \begin{macro}{\textquestiondown} -% \begin{macro}{\textquotedblleft} -% The following text commands are defined by \texttt{OT1enc.def}, but -% their definitions will not work for \texttt{OT1}-encoded typewriter -% fonts. Therefore they are redefined, either so that they work -% anyway (|\textexclamdown| and |\textquestiondown|) or so that they -% call |\TextSymbolUnavailable| when \package{rtkinenc} is in code -% mode. This should make things work for the best in most -% reasonable situations. -% -% It could be noted here that the definitions below for |\.| and |\H| -% does not quite behave as if the commands had not been defined at -% all (I'm assuming that \package{rtkinenc} is in code mode here); an -% undefined command would leave its argument to be typeset, but the -% definitions below will swallow it in those cases. -% \begin{macrocode} -%<*class> - \DeclareTextCommand{\.}{OT1}[1]{% - \IfInputModeCode{\TextSymbolUnavailable\.}% - {\add@accent{95}{#1}}% - } - \DeclareTextCommand{\H}{OT1}[1]{% - \IfInputModeCode{\TextSymbolUnavailable\H}% - {\add@accent{125}{#1}}% - } - \DeclareTextCommand{\textemdash}{OT1}{% - \IfInputModeCode{\TextSymbolUnavailable\textemdash}{\char 124 }% - } - \DeclareTextCommand{\textendash}{OT1}{% - \IfInputModeCode{\TextSymbolUnavailable\textendash}{\char 123 }% - } - \DeclareTextCommand{\textexclamdown}{OT1}{!`} - \DeclareTextCommand{\textquestiondown}{OT1}{?`} - \DeclareTextCommand{\textquotedblleft}{OT1}{% - \IfInputModeCode{\TextSymbolUnavailable\textquotedblleft}% - {\char 92 }% - } -% \end{macrocode} -% \end{macro}\end{macro}\end{macro}\end{macro}\end{macro}\end{macro} -% \end{macro} -% -% Several of the definitions in \texttt{applemac.def} can be improved. -% Most of it is about seeing to that all characters have a proper text -% mode definition, so that their unavailability can be trapped. -% -% \begin{macrocode} - \def\@tempa{applemac} - \ifx \@tempa\RIE@encoding - \DeclareInputBoth{173}{\textneq}{\neq} - \DeclareInputBoth{176}{\textinfty}{\infty} - \DeclareInputBoth{177}{\textpm}{\pm} - \DeclareInputBoth{178}{\textleq}{\leq} - \DeclareInputBoth{179}{\textgeq}{\geq} - \DeclareInputBoth{181}{\textmu}{\mu} - \DeclareInputBoth{182}{\textpartial}{\partial} - \DeclareInputBoth{183}{\textSigma}{\Sigma} - \DeclareInputBoth{184}{\textPi}{\Pi} - \DeclareInputBoth{185}{\textpi}{\pi} - \DeclareInputBoth{186}{\textint}{\int} - \DeclareInputBoth{189}{\textohm}{\Omega} - \DeclareInputBoth{194}{\textlnot}{\lnot} - \DeclareInputBoth{195}{\textsurd}{\surd} - \DeclareInputBoth{197}{\textapprox}{\approx} - \DeclareInputBoth{198}{\textDelta}{\Delta} - \DeclareInputBoth{214}{\textdiv}{\div} - \DeclareInputBoth{215}{\textdiamond}{\diamond} - \DeclareInputBoth{218}{\textfractionsolidus}{/} -% \end{macrocode} -% -% Several of the above text commands are not defined in the \LaTeX\ -% kernel. Therefore one must either define them in some encoding, or -% define a default for them, to make them proper text commands. If they -% are not then their unavailability cannot be trapped. |\textapplelogo| -% appears in \texttt{applemac.def}. -% \begin{macrocode} - \ProvideTextCommandDefault{\textneq}{% - \TextSymbolUnavailable\textneq - } - \ProvideTextCommandDefault{\textapplelogo}{% - \TextSymbolUnavailable\textapplelogo - } - \DeclareTextSymbol{\textinfty}{OMS}{49} - \DeclareTextSymbol{\textpm}{OMS}{6} - \DeclareTextSymbol{\textleq}{OMS}{20} - \DeclareTextSymbol{\textgeq}{OMS}{21} -% \DeclareTextSymbol{\textmu}{TS1}{181} - \DeclareTextSymbol{\textpartial}{OML}{64} - \DeclareTextSymbol{\textSigma}{OT1}{6} - \DeclareTextSymbol{\textPi}{OT1}{5} - \DeclareTextSymbol{\textpi}{OML}{25} - \DeclareTextSymbol{\textint}{OMS}{115} - \DeclareTextSymbol{\textohm}{OT1}{10} % Kind of \textOmega -% \DeclareTextSymbol{\textlnot}{TS1}{172} -% \DeclareTextSymbol{\textsurd}{TS1}{187} - \DeclareTextSymbol{\textapprox}{OMS}{25} - \DeclareTextSymbol{\textDelta}{OT1}{1} -% \DeclareTextSymbol{\textdiv}{TS1}{246} - \DeclareTextSymbol{\textdiamond}{OMS}{5} -% \DeclareTextSymbol{\textfractionsolidus}{TS1}{47} - \input{TS1enc.def} - \fi -\fi -% \end{macrocode} -% \begin{macrocode} -\let\if@rtkinenc@=\@undefined -\let\@rtkinenc@true=\@undefined -\let\@rtkinenc@false=\@undefined -% \end{macrocode} -% The |@rtkinenc@| switch isn't needed any more, so it might just as -% well be undefined. -% -% -% \subsection{The layout} -% -% Increase the text width slightly so that with the standard fonts -% 72 columns of code may appear in a |macrocode| environment. -% \changes{ \package{ltxdoc} v\,2.0c}{1994/03/15}{Set \cs{textwidth}.} -% \begin{macrocode} -\setlength{\textwidth}{355pt} -% \end{macrocode} -% -% Increase the marginpar width slightly, for long command names. -% And increase the left margin by a similar amount -% \changes{ \package{ltxdoc} v\,2.0l} -% {1994/05/25}{Increase \cs{marginparwidth}} -% \changes{ \package{ltxdoc} v\,2.0q}{1995/11/28} -% {Increase \cs{marginparwidth} and page margin.} -% \begin{macrocode} -\addtolength\oddsidemargin{20pt} -\addtolength\evensidemargin{20pt} -% \end{macrocode} -% -% -% Change some defaults for list formatting. In particular, continue to -% indent paragraphs in |\list| environments and don't put extra space -% between them. -% \changes{ \package{pasdoc} v\,1.30}{1999/08/31}{Modifying the list -% formatting. (LH)} -% -% \begin{macro}{\TD@list} -% \begin{macro}{\@listi} -% \begin{macro}{\@listI} -% \begin{macro}{\@listii} -% \begin{macro}{\@listiii} -% \begin{macro}{\@listiv} -% \begin{macro}{\@listv} -% \begin{macro}{\@listvi} -% \begin{macrocode} -\def\@tempa#1{% - \expandafter\def \expandafter#1\expandafter{#1\TD@list}% -} -\def\TD@list{% - \advance \itemsep \parsep - \parsep=\z@\@plus\p@\relax - \advance \itemsep -\parsep - \listparindent=1em\relax -} -\@tempa\@listi -\let\@listI\@listi -\@tempa\@listii -\@tempa\@listiii -\@tempa\@listiv -\@tempa\@listv -\@tempa\@listvi -% \end{macrocode} -% \end{macro}\end{macro}\end{macro}\end{macro}\end{macro}\end{macro} -% \end{macro}\end{macro} -% -% -% \subsection{Loading the \package{tcldoc} package} -% -% \begin{macrocode} -\RequirePackage[dolayout]{tcldoc} -% \end{macrocode} -% -% \begingroup -% Make \verb+|+ be a `short verb' character, but not in the document -% preamble, where an active character may interfere with packages that -% are loaded. -% \DoNotIndex{\|} -% \begin{macrocode} -\AtBeginDocument{\MakeShortTclverb{\|}} -% \end{macrocode} -% \endgroup -% -% As \texttt{.dtx} documents tend to have a lot of monospaced material, -% set up some \texttt{cmtt} substitutions to occur silently. -% \changes{ \package{ltxdoc} v\,2.0p}{1995/11/02}{Add font substitutions} -% \begin{macrocode} -\DeclareFontShape{OT1}{cmtt}{bx}{n}{<-> ssub * cmtt/m/n}{} -\DeclareFontFamily{OMS}{cmtt}{\skewchar\font'60} -\DeclareFontShape{OMS}{cmtt}{m}{n}{<-> ssub * cmsy/m/n}{} -\DeclareFontShape{OMS}{cmtt}{bx}{n}{<-> ssub * cmsy/b/n}{} -% \end{macrocode} -% This substitution is in the standard fd file, but not silent. -% \begin{macrocode} -\DeclareFontShape{OT1}{cmss}{m}{it}{<->ssub*cmss/m/sl}{} -% \end{macrocode} -% -% -% \subsection{More layout} -% -% \changes{v\,2.12}{2000/11/26}{Setting \cs{marginparwidth} so that the -% outer edge of the marginpar is $1\,\mathrm{cm}$ from the paper -% edge. (LH)} -% \changes{v\,2.12}{2000/11/27}{Rearranged code so that -% the \cs{marginparwidth} is set after \package{tcldoc} has been -% loaded; otherwise \package{doc} might overwrite it! (LH)} -% \begin{macrocode} -\setlength\marginparwidth{\evensidemargin} -\addtolength\marginparwidth{1in} -\addtolength\marginparwidth{-\marginparsep} -\addtolength\marginparwidth{-1cm} -% \end{macrocode} -% -% -% \begin{macrocode} -\CodelineNumbered -\DisableCrossrefs -% \end{macrocode} -% -% \begin{macrocode} -\setcounter{StandardModuleDepth}{1} -% \end{macrocode} -% -% -% \subsection{Useful abbreviations} -% \changes{v\,2.10}{2000/10/11}{\LaTeX\ abbreviation commands from -% \package{ltxdoc} commented out. (LH)} -% -% The commands currently found in this section are inherited from the -% \package{ltxdoc} package, but as they aren't of much use with \Tcl, -% they have been commented out. -% -% |\cmd{\foo}| Prints |\foo| verbatim. It may be used inside moving -% arguments. |\cs{foo}| also prints |\foo|, for those who prefer that -% syntax. (This second form may even be used when |\foo| is |\outer|). -% \begin{macro}{\cmd} -% \begin{macro}{\cs} -% \DoNotIndex{\\} -% \begin{macrocode} -% \def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}} -% \def\cmd@to@cs#1#2{\char\number`#2\relax} -% \DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}} -% \end{macrocode} -% \end{macro} -% \end{macro} -% -% \begin{macro}{\marg} -% |\marg{text}| prints \marg{text}, `mandatory argument'. -% \DoNotIndexHarmless{\PrintChar{`\{}} -% \DoNotIndexHarmless{\PrintChar{`\}}} -% \begin{macrocode} -% \providecommand\marg[1]{% -% {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\oarg} -% |\oarg{text}| prints \oarg{text}, `optional argument'. -% \begin{macrocode} -% \providecommand\oarg[1]{% -% {\ttfamily[}\meta{#1}{\ttfamily]}} -% \end{macrocode} -% \end{macro} -% -% \begin{macro}{\parg} -% |\parg{te,xt}| prints \parg{te,xt}, `picture mode argument'. -% \begin{macrocode} -% \providecommand\parg[1]{% -% {\ttfamily(}\meta{#1}{\ttfamily)}} -%</class> -% \end{macrocode} -% \end{macro} -% -% -% -% -% \changes{v\,2.00}{2000/07/17}{Section with \cs{DocInclude} removed, -% since that is defined by \package{xdoc}. (LH)} -% -% \Finale -% -\endinput - diff --git a/Master/texmf-dist/source/latex/tcldoc/tcldoc.ins b/Master/texmf-dist/source/latex/tcldoc/tcldoc.ins deleted file mode 100644 index f4ae5b3c944..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/tcldoc.ins +++ /dev/null @@ -1,45 +0,0 @@ -% This file is the docstrip installation script for the tcldoc package. -% -% It may be distributed under the conditions of the LaTeX -% Project Public License, either version 1.2 of this license or -% (at your option) any later version. The latest version of this -% license is in -% http://www.latex-project.org/lppl.txt -% and version 1.2 or later is part of all distributions of LaTeX -% version 1999/12/01 or later. -% -% Copyright 2000 Lars Hellstr\"om - -\input docstrip.tex - -\preamble - -This file may be distributed and/or modified under the conditions -of the LaTeX Project Public License, either version 1.2 of this -license or (at your option) any later version. The latest version -of this license is in - http://www.latex-project.org/lppl.txt -and version 1.2 or later is part of all distributions of LaTeX -version 1999/12/01 or later. - -This file may only be distributed together with a copy of the source -file from which it was generated. You may distribute that source file -without this generated file. - -\endpreamble - -\usedir{tex/latex/misc} - -\keepsilent - -\generate{% - \file{tcldoc.cls}{% - \from{tcldoc.dtx}{class} - }% - \file{tcldoc.sty}{% - \from{tcldoc.dtx}{pkg} - }% -} - -\endbatchfile -\endinput diff --git a/Master/texmf-dist/source/latex/tcldoc/tools/README.txt b/Master/texmf-dist/source/latex/tcldoc/tools/README.txt deleted file mode 100644 index c8fd744afd8..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/tools/README.txt +++ /dev/null @@ -1,46 +0,0 @@ -README for eemenu and sourcetcl: -===================================== - -eemenu is a package for the Alpha/Alphatk text -editors. Among other things, it implements -a command that makes it possible to evaluate -all Tcl code in an open .dtx file window with -a single keypress. For more information, run -LaTeX on eemenu.dtx. - -Running LaTeX on eemenu.ins generates the two -files - eemenu.tcl - eefor7menu.tcl -Both implement the same commands, but eemenu.tcl -requires version 8 of the AlphaTcl library, -whereas eefor7menu.tcl requires version 7.5 or -7.6 of that library. - -See http://alphatcl.sourceforge.net/ and the -links there for more information about the -Alpha/Alphatk text editors. - - - -sourcedtx implements a Tcl command dtx::source -that one can use to source Tcl code directly from -a .dtx file. To generate sourcetcl.tcl, run LaTeX -on sourcetcl.ins. To typeset the documentation, -run LaTeX on sourcetcl.dtx. To see an example of -what it does, you can try the following commands -in a Tcl shell: - - source sourcedtx.tcl - dtx::source ../examples/pdf.dtx {pkg example1} - -(It assumes the tclldoc/examples directory is a -sibling of the current directory.) This should -generate a file hello.pdf in the current -directory, which contains a single page with the -two words "Hello world!". - - - -Lars Hellström, -20 July 2003 diff --git a/Master/texmf-dist/source/latex/tcldoc/tools/eemenu.dtx b/Master/texmf-dist/source/latex/tcldoc/tools/eemenu.dtx deleted file mode 100644 index d2383b7c1e0..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/tools/eemenu.dtx +++ /dev/null @@ -1,4477 +0,0 @@ -% -% \iffalse -%<*driver> -\documentclass[a4paper]{tclldoc} - -\newcommand{\eemenu}{\textsf{EE} menu} -\DeclareRobustCommand\Alpha{\textit{Alpha}} -\DeclareRobustCommand\AlphaEight{\textit{Alpha\,8}} -\DeclareRobustCommand\AlphaTk{\textit{Alphatk}} -\DeclareRobustCommand\AlphaTcl{\textit{Alpha\Tcllogo}} -\DeclareRobustCommand\TclAE{\Tcllogo\AE} -\DeclareRobustCommand\package[1]{\textsf{#1}} - -\providecommand{\href}[2]{#2} - -\usepackage{xdoc2} -\newenvironment{details}[1]{% - \description - \def\commandmethod{#1}% -}{\enddescription} -\makeatletter -\newcommand{\detailitem}{% - \XD@grab@arguments{\@detailitem}{\XD@grab@harmless\relax}% -} -\def\@detailitem#1{% - \item[\texttt{#1}% - \IndexEntry{\LevelSame{\commandmethod\ method}% - \LevelSorted{#1}{\texttt{#1} detail}% - }{main}{\TheXDIndexNumber}% - ]% -} -\makeatother - -% \addtolength{\marginparwidth}{0.7cm} - -\CodelineIndex -\setcounter{IndexColumns}{2} - -\begin{document} -\DocInput{eemenu.dtx} -\PrintIndex -\end{document} -%</driver> -% \fi -% -% \title{The \eemenu} -% \author{Lars Hellstr\"om} -% \date{17 July 2003} -% \maketitle -% -% -% \begin{abstract} -% The \eemenu\ package for the \Alpha\ family of text editors provides -% commands for sending small pieces of code from a source file window -% to various interpreters. It can handle multiple languages and -% multiple source file formats. -% \end{abstract} -% -% \tableofcontents -% -% -% \section{Introduction} -% -% When writing code for an interpreted language, it is a great -% convenience to be able to test arbitrary pieces of code by sending -% them to a relevant interpreter and examining the results. Many of -% \Alpha's modes provide such functionality, but not always with the -% full generality one would need. Furthermore these features are usually -% tied to the specific mode and thus become much less convenient if code -% in several different languages are mixed in the same file. The -% \eemenu\ provides a general mechanism for constructing new commands -% of this kind, thereby making it possible to better tailor them for the -% case at hand. -% -% -% \subsection{Using an \eemenu\ command} -% -% The basic usage is straightforward: you select a piece of text and -% invoke one of the \eemenu\ commands. This will \emph{extract} -% the part of that selection which is code and send it to the relevant -% interpreter, where it will be \emph{evaluated}. (Indeed, the \textsf{EE} -% in \eemenu\ is for ``extract and evaluate''.) You will also get -% a \emph{report} (by default a message on the status line) about the -% result of the command. This is all quite similar to how the -% \textsf{Evaluate} command in the \Tcllogo\ menu works, but it is much -% more general. -% -% Two very natural questions at this point are of course ``How does it -% know what part of the selection is `code'?'' and ``How does it know -% which the `relevant interpreter' is?''. The answer to both these -% questions is that this information is built into the particular command -% you invoke. Just as the standard \textsf{Evaluate} command has its -% definition of what `code' is (the entire selection is code) and which -% the `relevant interpreter' is (\Alpha's internal \Tcllogo\ -% interpreter), each \eemenu\ command has built-in definitions of -% these things. The difference is that with \textsf{Evaluate} you would -% have to do some programming to change these things, whereas with the -% \eemenu\ commands you don't, since there is a multitude of ways in -% which each part of the exatract-and-evaluate process can be configured. -% -% To begin with, each \eemenu\ command consists of four pieces which -% are quite independent of each other. When the \emph{extract} piece is -% called it looks at the selection and returns the next line of code in -% it, or says that there are no more code lines that can be extracted. -% What happens to the extracted lines of code is of no concern to the -% extractor. The \emph{evaluate} piece takes a list of lines and sends -% them to an interpreter (internal or external). It also compiles a -% sort of report on the result of the evaluation, based on the reply -% (if there was any) that it recieves from the interpreter. This is -% then given to the \emph{reporter}, which displays the report (or more -% often, for brevity, the central part of the report) to the user. The -% fourth piece is called the \emph{completeness test} and determines -% whether a list of code lines constitute a unit that can be evaluated. -% -% The way it goes is that lines are extracted until the completeness -% test says OK, then the lines are sent for evaluation and the report on -% evaluation is sent to the reporter, after which the whole thing starts -% again and lines are extracted until the form a new complete unit, -% which is then evaluated, and so on. The \eemenu\ command doesn't stop -% until all code lines in the selection have been extracted or evaluation -% reports an error. -% If there is an error in evaluation then the report will say so, and -% futhermore the cursor will be moved to the beginning of the first -% line in the code unit that failed to evaluate correctly. Furthermore -% the pin will be moved to the end of the selection, so that a simple -% \textsf{Hilite} will reselect the part of the original selection that -% still has not been successfully evaluated. If there wasn't any -% selection to start with then the extractor behaves as if the entire -% file was selected. -% -% -% \subsection{Editing and invoking \eemenu\ commands} -% -% Each of the four pieces of what a command does are handled by a -% \emph{method}. There are extraction methods, completeness test -% methods, evaluation methods, and report methods, all of which can be -% combined arbitrarily to make up a new \eemenu\ command. This is done -% in the \textsf{Edit Commands} dialog, which is brought up by -% choosing that item in the \textsf{EE} menu. -% -% The \textsf{Edit Commands} dialog has one page for each \eemenu\ -% command that is defined. At the bottom of the dialog there is a row -% of four buttons \textsf{New}, \textsf{Duplicate}, \textsf{Rename}, and -% \textsf{Delete} which add, remove, or rename \eemenu\ commands. Above -% those are four pop-up menus, in which one chooses which four methods -% the command should consist of. Above these are four other items which -% control how the command is invoked. -% -% There are two ways of invoking an \eemenu\ command. One possibility -% is to choose it directly in the \textsf{EE} menu, although it is not -% necessarily the case that all commands are available there. Whether a -% command is available is controlled through the \textsf{Put in menu} -% item on the \textsf{Edit Commands} dialog page of that command. The -% other possibility of invoking a command is through a key binding, and -% that is controlled through the three remaining items \textsf{Active}, -% \textsf{Command keybinding}, and \textsf{Binding mode} in the -% \textsf{Edit Commands} dialog. The \textsf{Command keybinding} item -% controls which key binding one should use for a command. The -% \textsf{Binding mode} item is used to specify a mode for this -% binding; a binding without mode will be global. Finally, a command is -% said to be \emph{active} if there is a key binding to it. The -% \textsf{Active} item controls whether the command should be active by -% default (at startup). -% -% For temporary activation and deactivation of commands, one should -% instead use the \textsf{Active Commands} submenu of the \textsf{EE} -% menu. This submenu lists all \eemenu\ commands. Those that are -% currently active have a check mark next to them, and selecting an item -% in this menu toggles activation state of that command. If two commands -% have the same binding then activating one will deactivate the other. -% -% Besides the items mentioned above, the \textsf{Edit Commands} dialog -% also has a \textsf{Details} button in the lower left corner. This -% button is very important, since it brings up a subdialog that shows -% all the method-specific settings. The methods and their details are -% described below, but it should be observed here that it is to a large -% extent these detail settings that decide, amogst other things, what -% text should count as extractable code and which interpreter should -% evaluate the code. To get back from the details subdialog to the main -% \textsf{Edit Commands} dialog, one presses the \textsf{Back} button. -% The details subdialog is logically a part (which is normally hidden) -% of the main \textsf{Edit Commands} dialog. Changes to items in the -% dialog, whether those appear in the main dialog or in the subdialog, -% are kept if one presses \textsf{OK} in the main dialog and forgotten -% if one presses the \textsf{Cancel} button. -% -% -% \subsection{Extraction methods and their details} -% -% The default extraction method is the \textsf{Raw} method. It -% considers the entire selection to be extractable code and has no -% detail settings. -% -% The \textsf{Regexp} extraction method uses line-oriented regular -% expressions to decide what is extractable code. This extraction -% process works in two steps. First the lines in the selection are -% tested against a filter, and those lines that passes are considered to -% contain code. The filter works in one of three modes: \texttt{off} -% (all lines pass), \texttt{grep} (only those lines that match a -% specific regular expression passes), and \texttt{anti-grep} (only -% those lines that \emph{don't} match a specific regular expression -% passes). The filter mode and the regular expression used in the -% filter are the two detail settings that affect the filter. -% The second step in \textsf{Regexp} extraction is to feed each line -% that passes the filter through |regsub|. This can be used to remove -% from the lines some piece of text that is markup rather than part of -% the code. Both the search and the replace regular expressions in this -% step are detail settings of the \textsf{Regexp} extraction method. -% -% The \textsf{Docstrip} extraction method, finally, emulates what the -% \textsf{docstrip} program\footnote{\textsf{docstrip} is part of the -% standard \LaTeX\ distribution.} would do with the selection. It -% recognises all kinds of guards and processes them correctly, but it -% does not attempt to evaluate the guard expressions---instead it will -% ask the user whether modules guarded by a given expression should be -% included whenever it needs to know this. The values assigned to the -% guard expressions will be forgotten each time the entire selection -% is evaluated without error. Unlike \textsf{docstrip} the program, -% \textsf{Docstrip} the extraction method will not include lines -% beginning with |%%| in what is extracted, since those anyway only -% contains comments. -% -% Besides the filtering that \textsf{docstrip} the program would do, -% \textsf{Docstrip} the extraction method has two extra filtering -% mechanisms that are designed mainly to prevent user errors. The first -% is that extraction will only take place if the file name matches one -% listed in the \textsf{File patterns} detail. The default pattern is -% \texttt{*.dtx} which is usually what one wants, but changing it to -% \texttt{*} will let anything through. The second mechanism, which is -% off by default, sees to that code lines will only be considered for -% extraction if they appear to be in an environment for code lines -% (such as \texttt{macrocode}). This is useful if you in places tend to -% leave a few lines of documentation not commented out during -% development. To activate this mechanism, check the \textsf{Filter by -% environments} detail. The \textsf{Source environments} detail is the -% list of environments that are OK to extract from. -% -% As an example of how this works, consider a file that looks as -% follows: -% \DontCheckModules\iffalse -%<*example> -%<<EXAMPLE -% \fi\begin{macrocode} -% Text text text text text -% \begin{tcl} -set a A -%<*andB> -append a B -%</andB> -append a C -%<*andD> -append a D -%</andB> -expr $a -string length $a -% \end{tcl} -% text text text. -% \end{macrocode}\iffalse -%EXAMPLE -%</example> -% \fi \CheckModules -% If lines 1--7 above are selected and the \textsf{dtx -\textgreater\ -% internal Tcl} command is invoked (the \eemenu\ by default binds this -% to \textsf{Cmd--L}), then three messages will flash by on the -% status line, the last (and therefore the lasting) of which is the -% message \texttt{Tcl eval OK: ABC}. If using instead a command that -% uses the \textsf{Log Window} report method, then in addition to this -% one would have the following lines added to the log window: -% \begin{trivlist}\item\small -% |% set a A|\\ -% |A|\\[\smallskipamount] -% |% append a B|\\ -% |AB|\\[\smallskipamount] -% |% append a C|\\ -% |ABC| -% \end{trivlist} -% The |%| lines show the commands that were evaluated and the -% lines after these contain the respective results of these commands. -% Before the |append a B| command is evaluated, \Alpha\ will stop and -% ask -% \begin{quote} -% \textsf{Should \textless andB\textgreater\ modules be included?} -% \end{quote} -% In the case above the answer given was `Yes'; if it had been `No' then -% the |append a B| command would neither be logged nor evaluated, and -% the result of the |append a C| command would have been |AC|. -% -% If one continues by selecting lines 9--12 and invokes the same -% command again then the status line will settle for the message -% ``\texttt{Tcl\ eval\ error:\ syntax\ error\ in\ expression\ "ABCD"}'', -% the insertion point will be moved to the beginning of line 11, and -% the following information will be found in the log: -% \begin{trivlist}\item\small -% |% append a D|\\ -% |ABCD|\\[\smallskipamount] -% |% expr $a|\\ -% |Error: syntax error in expression "ABCD"|\\ -% |Error info:|\\ -% |syntax error in expression "ABCD"|\\ -% | while executing|\\ -% |"expr $a"| -% \end{trivlist} -% If then line 11 is changed to |expr {$a}|, lines 11--12 are again -% selected (e.g. using \textsf{Mark Hilite}), and the command is invoked -% then logged material will be: -% \begin{trivlist}\item\small -% |% expr {$a}|\\ -% |ABCD|\\[\smallskipamount] -% |% string length $a|\\ -% |4| -% \end{trivlist} -% -% Finally, if lines 3--12 are selected and the command is invoked then -% the user will be asked the following questions: -% \begin{itemize} -% \item \textsf{Should \textless andB\textgreater\ modules be included?} -% (Possible answers are `Yes' and `No'.) -% \item \textsf{Should \textless andD\textgreater\ modules be included?} -% (Possible answers are `Yes' and `No'.) -% \item \textsf{Module nesting error: \textless*andD\textgreater\ -% module ended by \textless/andB\textgreater. For which -% guards should the positions be pushed?} -% (Possible answers are `None', `Start', `End', and `Both'.) -% \end{itemize} -% In the last case, the extraction method has noticed that the guard -% expressions that began (\textsf{andD}) and ended (\textsf{andB}) a -% module are not equal (which is an error). Answering `Both' here will -% push the positions of (the beginning of) both guard lines (8 and 10) onto -% the bookmark stack so that they can easily be jumped to and corrected -% later. After this, the \eemenu\ command will continue as if nothing had -% happened. -% -% -% \subsection{Completeness tests} -% -% The three completeness tests that come with \eemenu\ are -% \textsf{\Tcllogo\ Info Complete}, \textsf{Entire Selection}, and -% \textsf{Every Line}. The first of these uses the |info complete| -% command in \Alpha's built-in \Tcllogo\ interpreter test whether the -% list of lines extracted so far constitute a complete \Tcllogo\ -% script. \textsf{Entire Selection} and \textsf{Every Line} don't look -% at the extracted lines at all however; instead the \textsf{Entire -% Selection} test waits until the entire selection has been extracted -% before it says it does constitute a complete unit, whereas -% \textsf{Every Line} thinks every line is a complete unit. None of -% these methods have any details. -% -% -% \subsection{Evaluation methods} -% -% The list of available evaluation methods depends very much on the -% current platform. The basic \eemenu\ package contains code for four -% methods named \textsf{Internal Tcl}, \textsf{Do Script AE}, \textsf{Tk -% Send}, and \textsf{Windoze DDE}, but only those for which the -% underlying command can be found in the interpreter are actually -% defined. The effect is usually that only two methods are available: -% the \textsf{Internal Tcl} method and one method which depends on the -% platform. -% -% The \textsf{Internal Tcl} method joins the lines of code with -% linefeeds and passes the resulting string to \Alpha's internal -% \Tcllogo\ interpreter for evaluation (at the global level). Errors -% are caught and reported with a complete |errorInfo|. There are no -% details for this method. -% -% The \textsf{Do Script AE} method sends a \texttt{dosc} AppleEvent with -% the code to evaluate; hence it is only available on Mac~OS. The target -% application for this event is one of the detail settings. The `Wait -% for reply' detail setting controls whether the AppleEvent requests a -% reply (not all target applications will provide one). If no reply is -% requested then the report will only tell how many lines were sent. -% If a reply is requested then that reply will be the report. Finally, -% there are three detail settings that control how the list of lines -% are converted to the string put in the \texttt{dosc} AppleEvent. The -% lines can be joined using either of the following four strings: line -% feed, carriage return, carriage return plus line feed, or just a -% single space. It is also possible to specify a prefix and a suffix, -% which are strings put before and after the extracted code that should -% be evaluated. -% -% The \textsf{Tk Send} method uses the Tk |send| command to communicate -% with the target interpreter; hence it is probably only useful with -% \AlphaTk\ in an X-windows environment (typically on some Unix platform). -% Most of the details work as for the \textsf{Do Script AE} method, but -% there is a difference in how the target is identified. One detail -% setting is the string used for identifying the target, but since the -% names of targets for |send| are made unique on each server, there is -% a chance that the intended target has not got the expected name. In -% that case, a mechanism called `aliasing' will be invoked. It usually -% displays a list of the available targets (which includes the option to -% start a new Wish process) for the user to choose from, and the target -% detail setting will then be considered to be an \emph{alias} for the -% actual name of that target. If the alias behaviour is to ``Ask once'' -% then this choice will be remembered as long as \Alpha\ is running, but -% if it is to ``Ask each time'' then it will only work for this invocation -% of the \eemenu\ command. The behaviour can also be to fail, in which -% case the command stops as for an error without presenting the user with -% a list of available targets. -% -% The \textsf{Windoze DDE} method uses Dynamic Data Exchange to communicate -% with the target interpreter; hence it is probably only useful with -% \AlphaTk\ on the Windows platform. Most of the details work as for the -% \textsf{Tk Send} method, but there are a few extra details that have -% to do with how the target is identified. The target is identified with -% two details called \textsf{Service} and \textsf{Target}. For sending -% commands to a \Tcllogo\ interpreter it seems like the \textsf{Service} -% should be \texttt{TclEval} and the \textsf{Target} is assigned as the -% \textsf{Target} for the \textsf{Tk Send} method, but the \Tcllogo\ -% manual seems to suggest that the normal case is that the -% \textsf{Service} is the name of an application and the -% \textsf{Target} the name of a document open in that application (I -% haven't had any chance to try it out in practice). Aliasing works as -% for the \textsf{Tk Send} method, but since the target isn't -% necessarily a \Tcllogo sh or Wish in this case, the actual command for -% launching the new target must be configurable as well. This is the -% purpose of the \textsf{Launch command} detail, whose value is a piece -% of \Tcllogo\ code that \Alpha\ evaluates at the global level whenever -% the user requests that a new target is launched. It is typically an -% |exec| command. -% -% I am well aware that there are interpreters for which neither of these -% methods may be appropriate. The method concept has however deliberately -% been designed so that separate \AlphaTcl\ extensions can define new -% methods that are just as easily available as the built-in ones. I -% recommend that anyone who finds the available methods insufficient -% tries to work out how one might otherwise communicate with the target -% interpreter, so that the capabilities of \eemenu\ can be extended. One -% particular possibility that should be explored is to (on Unix) hook up -% interpreters as `slaves' of \Alpha\ (seizing control of -% \texttt{stdin}, \texttt{stdout}, and \texttt{stderr}), so that the -% target interpreter thinks it is getting text typed at an interactive -% prompt. Since one would typically not want to start a new such `slave' -% for each time an \eemenu\ command is invoked, it would probably be -% necessary to add some functionality for managing slaves to the -% \eemenu. -% -% -% \subsection{Report methods} -% -% The default report method is \textsf{Status Line}, which shows the -% most recent evaluation result on the status line. This is often -% sufficient when all you're interested in is whether there was an -% error or not. -% -% The \textsf{Log Window} report method creates a detailed log of the -% commands evaluated and the results returned. This can be useful for -% example when one is trying to debug a complex mathematical calculation -% with several intermediate results. The first two details of this -% method---\textsf{Window name} and \textsf{Window mode}---refer to the -% window used to log the results. The logged text is inserted at the -% end of this window. If no window with the specified name exists, then -% a new one with mode \textsf{Window mode} and the shell flag set is -% opened. The other details---\textsf{Prompt} and -% \textsf{Antiprompt}---are text strings that are prepended to the -% lines inserted into the log window. The \textsf{Prompt} is prepended -% to extracted code lines, whereas the \textsf{Antiprompt} is prepended -% to result lines. -% -% -% \subsection{Writing new methods} -% -% A method consists of a couple of procedures which reside in a child -% namespace of the \texttt{eemenu} namespace. Declaring a new method -% simply amounts to writing these procedures and defining the detail -% settings for the method. The general relation between method names and -% namespace names is explained in Subsection~\ref{Ssec:Namespaces}. It -% is suggested that one uses the \texttt{eemenu}\namespaceseparator -% \texttt{define\_detail} command of Subsection~\ref{Ssec:CmdDialogs} -% for defining detail settings. Different kinds of methods need to -% provide different procedures for the main executive to call. The -% interfaces used are described in the beginnings of -% Sections~\ref{Sec:Extraction}--\ref{Sec:Report}. -% -% -% -% -% \section{Main menu functionality} -% -% The rest of this paper describes the implementation of \eemenu\ and -% its methods. The information here is useful mainly for those who want -% to extend \eemenu\ by writing additional methods for it or otherwise -% modify the code, but it could of course be of interest also for -% advanced users. -% -% -% \subsection{Initialization} -% -% \changes{v\,0.1}{2001/12/15}{Renamed package from \textsf{Eval~Menu} -% to \textsf{EE~Menu}. (LH)} -% \changes{v\,0.3}{2003/04/02}{Updated code for \AlphaTcl\,8. (LH)} -% \changes{v\,0.3.1}{2003/07/19}{Added help. (LH)} -% -% \begin{tcl} -%<*pkg> -alpha::menu eeMenu 0.3.1 global "EE" { - auto_load eemenu::main -} { - eemenu::init_bindings - eemenu::build_menu -} { - eval eemenu::deactivate [array names eemenu::cmdA] -} requirements { -%<atcl7> alpha::package require AlphaTcl 7.5b1 -%<!atcl7> alpha::package require AlphaTcl 8.0d1 -} uninstall {this-file} help { - The EE menu provides commands for sending small pieces of code - from a source file window to various interpreters. It can handle - multiple languages and multiple source file formats. - - The commands are built by combining four simple pieces called - methods. The choice of methods and parameters for methods to - use in a command is completely configurable through a dialog. - It is also possible to write extensions that define additional - methods and provide these through the same easy interface. - - See the file eemenu.dtx for the full documentation. -} maintainer\ -%<atcl7> [list "Lars Hellstr[text::Ascii 154 1]m" Lars.Hellstrom@math.umu.se] -%<!atcl7> [list "Lars Hellstr\u00f6m" Lars.Hellstrom@math.umu.se] -namespace eval eemenu {} -% \end{tcl} -% \setnamespace{eemenu} -% -% -% \subsection{Methods and namespaces} -% \label{Ssec:Namespaces} -% -% Each method for doing something is put in its own namespace, which -% must be a child of the |eemenu| namespace. -% -% \begin{proc}{Prettify} -% \begin{proc}{Unprettify} -% In dialogs and preferences, method names are kept in ``prettified'' -% form, similar to that used in most of \Alpha's menus. Since the -% preference values must be restored to ``unpretty'' form before they -% can be used, \eemenu\ has two procedures of its own that handle -% these conversions, although the conversion is almost always the same -% as the conversion that the standard |quote::Prettify| procedure -% would make. The syntaxes are -% \begin{quote} -% |eemenu::Prettify| \word{unpretty string}\\ -% |eemenu::Unprettify| \word{pretty string} -% \end{quote} -% \begin{tcl} -proc eemenu::Prettify str { - set a [string toupper [string index $str 0]] - regsub -all {([^A-Z])([A-Z])} [string range $str 1 end] {\1 \2} b - regsub -all {((La|Bib|Oz|CMac) )?Te X} $a$b {\2TeX } a - return $a -} -proc eemenu::Unprettify str { - regsub -all { } $str {} a - return "[string tolower [string index $a 0]][string range $a 1 end]" -} -% \end{tcl} -% For these procedures to be inverses of each other, unpretty strings -% must begin with a lower case letter and not contain any spaces. -% \end{proc}\end{proc} -% -% \begin{arrayvar}{extract}[method] -% \begin{arrayvar}{complete}[method] -% \begin{arrayvar}{evaluate}[method] -% \begin{arrayvar}{report}[method] -% A method declares itself by setting its entry in the |extract|, -% |complete|, |evaluate|, or |report| respectively array. The -% entries in these arrays are lists of dialog item names, more -% precisely the names of those setting details that are relevant for -% the method in question. The indices into these arrays are unpretty -% method names. -% \end{arrayvar}\end{arrayvar}\end{arrayvar}\end{arrayvar} -% -% Most method types employ a model with distinct ``begin'', ``iterate'', -% and ``end'' procedures that the main executive calls. For each command -% and method, the ``begin'' is called first once, then the ``iterate'' -% may be called any number of times, and last the ``end'' is called once. -% The details to use for the method are only provided in the call to -% ``begin'' as that procedure is expected to store the relevant data -% into variables private to the method (residing in its namespace). In -% most cases, the actual code being evaluated is only handled by the -% ``iterate'' procedure, and only the ``end'' procedure gets to know -% how it all turned out. -% -% In many methods, some of these procedures do nothing at all. This is -% then because there is nothing that needs to be done for that particular -% method. -% -% \begin{proc}{multiupvar} -% The |multiupvar| procedure does |upvar #0| for a number of -% variables, prepending the namespace of the caller to each of the -% \word{other-var} arguments of |upvar|. The syntax is -% \begin{quote} -% |eemenu::multiupvar| \word{my-var}\regplus -% \end{quote} -% \changes{v\,0.2}{2002/12/26}{Corrected a minor bug: one must look -% at the first element in the list that info level returns. (LH)} -% \begin{tcl} -%<*!atcl7> -proc eemenu::multiupvar {args} { - foreach var $args {uplevel 1 [list variable $var]} -} -%</!atcl7> -%<*atcl7> -proc eemenu::multiupvar {args} { - if {[info level]>1} then { - set ns [lindex [info level -1] 0] - set t [string last :: $ns] - if {$t<0} then {set ns {}} else { - set ns [string range $ns 0 [expr {$t+1}]] - } - } else {set ns {}} - set t 1 - set call [list upvar #0] - foreach var $args {lappend call ${ns}${var} $var} - uplevel 1 $call -} -%</atcl7> -% \end{tcl} -% \end{proc} -% -% -% \subsection{The main executive} -% -% \begin{arrayvar}{cmdA}[command name] -% The |cmdA| array stores all definitions of \eemenu\ commands. The -% indices into the array are the command names. The entries are -% key--value lists which contain the settings for the command. -% -% The \describestring[key]{active}|active|, -% \describestring[key]{binding}|binding|, and -% \describestring[key]{mode}|mode| keys have to do with the key -% binding for this command. If |active| is |1| then the binding should -% be made upon startup. |binding| is the actual binding to use. |mode| -% is the mode for which the binding should be made; if this is -% |<none>| then the binding should be global. -% -% The \describestring[key]{in_menu}|in_menu| key controls whether -% this command should appear as a command in the main \textsf{EE} -% menu. -% -% The \describestring[key]{extractor}|extractor|, -% \describestring[key]{complete}|complete|, -% \describestring[key]{evaluator}|evaluator|, and -% \describestring[key]{reporter}|reporter| keys store the particular -% methods that are used by the command. The values are prettified -% method names. For each of these keys there is also an \dots|_extra| -% key whose value is the key--value list of detail settings for that -% method. The exact names are \describestring[key]{extract_extra} -% |extract_extra|, \describestring[key]{complete_extra} -% |complete_extra|, \describestring[key]{eval_extra}|eval_extra|, and -% \describestring[key]{report_extra}|report_extra|. -% -% If the |cmdA| array isn't set then it will be initialised in -% Section~\ref{Sec:DefCmdA}. -% \end{arrayvar} -% -% -% -% \begin{proc}{main} -% The |main| procedure is meant to be called from key binding scripts -% and menu procs to actually carry out an \eemenu\ command. The -% syntax is -% \begin{quote} -% |eemenu::main| \word{command name} \meta{selection-args} -% \end{quote} -% The \word{command name} is the name of the \eemenu\ command. The -% \meta{selection-args} can be used to specify what the command -% should extract from; they are passed straight on to the extraction -% method |start| procedure. -% -% If there was an error during the execution of the command then |main| -% terminates with an error. There is no particular result from this -% procedure. -% -% The first part of |main| calls the begin procedures of the methods -% used. -% \begin{tcl} -proc eemenu::main {command args} { - global eemenu::cmdA - if {![info exists eemenu::cmdA($command)]} then { - error "Command '$command' undefined." - } - array set CMD [set eemenu::cmdA($command)] -% \smallskip - set extract [eemenu::Unprettify $CMD(extractor)] - set cmpl [eemenu::Unprettify $CMD(complete)] - set eval [eemenu::Unprettify $CMD(evaluator)] - set report [eemenu::Unprettify $CMD(reporter)] -% \smallskip - set win\ - [eval [list eemenu::${extract}::start $CMD(extract_extra)] $args] - upvar #0 eemenu::${cmpl}::complete complete - eemenu::${report}::log_open $CMD(report_extra) $win -% \end{tcl} -% The main part of |main| is the following loop over extracted lines. -% The |res| variable stores the last result returned by the evaluation -% method. The |safe| variable is a boolean for whether the current -% position should be considered safe. The |lines| variable contains -% the lines extracted but not yet evaluated. The |at_end| variable is -% |0| until the end of the extractable portion of the code has been -% encountered. -% \begin{tcl} - set res [eemenu::${eval}::begin $CMD(eval_extra) $win] - eval [list eemenu::${report}::log_result] $res - set lines [list] - set safe 1 - while {![lindex $res 0]} { -% \end{tcl} -% First extract the next line of code and append it to |lines|. -% \begin{tcl} - set at_end [catch {eemenu::${extract}::next $safe} line] - if {$at_end == 1} then { - global errorInfo - return -code error -errorinfo $errorInfo - } elseif {$at_end == 0} then { - lappend lines $line - } elseif {![llength $lines]} then {break} -% \end{tcl} -% Secondly check if there is a complete block of code in |lines|. -% \begin{tcl} - set safe [expr $complete] - if {$at_end && !$safe} then { - set safe [expr {![dialog::yesno -y No -n Yes\ - "The last [llength $lines] lines do not appear to be a\ - complete block of code. Evaluate anyway?"]}] - if {!$safe} then { - set res [list 1 "" ""] - break - } - } -% \end{tcl} -% Finally log code, evaluate it, and log the result. This should -% happen when |lines| contains a complete block of code. If there is -% no error in evaluating the code then the current position will be -% safe at the next iteration of the loop, and if there is an error -% then the loop will not be iterated anyway. Hence the use of |safe| -% is correct. -% \begin{tcl} - if {$safe} then { - eemenu::${report}::log_code $lines - set res [eemenu::${eval}::item $lines] - eval [list eemenu::${report}::log_result] $res - set lines [list] - } - } -% \end{tcl} -% If an error has already been detected then it doesn't matter if -% |end| evaluates without error, but it could also be that no error -% results are returned before |end|. -% \begin{tcl} - if {[lindex $res 0]} then { - eval [list eemenu::${report}::log_result] [eemenu::${eval}::end] - } else { - set res [eemenu::${eval}::end] - eval [list eemenu::${report}::log_result] $res - } - eemenu::${extract}::finish [lindex $res 0] - eemenu::${report}::log_close -} -% \end{tcl} -% \end{proc} -% -% -% \subsection{The key bindings} -% -% There is a small system for managing the \eemenu\ key bindings. There -% are two reasons for this: deactivating a command should only unbind a -% binding if that binding is really currently used for that command, -% and the \textsf{Active~Commands} submenu should match the actual -% bindings. -% -% \begin{proc}{binding_index} -% The |binding_index| procedure makes an index into the |binding| array. -% The syntax is -% \begin{quote} -% |eemenu::binding_index| \word{mode} \word{binding} -% \end{quote} -% Both an empty string and |<none>| as \word{mode} are interpreted as -% ``global''. -% \begin{tcl} -proc eemenu::binding_index {mode binding} { - if {"<none>"==$mode} then {set mode ""} - set mode [string range "[string trim $mode] " 0 3] - return "$mode$binding" -} -% \end{tcl} -% \end{proc} -% -% \begin{arrayvar}{binding} -% The |binding| array is used to keep track of which command is -% currently using a particular binding. The entries in this array are -% command names. The indices have the form -% \begin{quote} -% \meta{mode}\meta{binding} -% \end{quote} -% where \meta{mode} is the mode and \meta{binding} is the menu-style -% code for the binding. \meta{mode} is padded on the right with -% spaces to exactly four characters. The \meta{mode} for global -% bindings is four spaces. -% \end{arrayvar} -% -% \begin{proc}{init_bindings} -% The |init_bindings| procedure initialises the |binding| array and -% the actual key bindings to match the data in the |cmdA| array. It -% should be called when the menu is activated, but before the menu -% itself is built. -% \begin{tcl} -proc eemenu::init_bindings {} { - eemenu::multiupvar cmdA binding - foreach cmd [array names cmdA] { -% \end{tcl} -% Only commands that are active needs to be considered. -% \begin{tcl} - array set A $cmdA($cmd) - if {!$A(active)} then {continue} -% \end{tcl} -% The state of the binding must also be determined. It could be that -% some other \textsf{EE~Menu} command is using the same binding, in -% which case the user should be informed of this. -% \begin{tcl} - set idx [eemenu::binding_index $A(mode) $A(binding)] - if {[info exists binding($idx)] &&\ - ![dialog::yesno "To activate '$cmd', I must first deativate\ - '$binding($idx)'. Proceed?"]}\ -% - then {continue} -% \end{tcl} -% Now the binding can be made for the command. -% \begin{tcl} - set binding($idx) $cmd - set call [keys::bindKey $A(binding)] - lappend call [list eemenu::main $cmd] - if {[string compare "<none>" $A(mode)]} then {lappend call $A(mode)} - eval $call - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{deactivate} -% The |deactivate| procedure has the syntax -% \begin{quote} -% |eemenu::deactivate| \word{\eemenu\ command}\regplus -% \end{quote} -% It deactivates the bindings for all commands listed as arguments -% and updates the \textsf{Active Commands} submenu accordingly. -% \begin{tcl} -proc eemenu::deactivate {args} { - eemenu::multiupvar binding cmdA - foreach cmd $args { -% \end{tcl} -% First make sure the binding is actually active. -% \begin{tcl} - array set A $cmdA($cmd) - set idx [eemenu::binding_index $A(mode) $A(binding)] - if {![info exists binding($idx)] ||\ - [string compare $binding($idx) $cmd]} then {continue} -% \end{tcl} -% Then unset everything that has to do with it. -% \begin{tcl} - unset binding($idx) - set call [keys::unbindKey $A(binding)] - lappend call "" - if {[string compare "<none>" $A(mode)]} then {lappend call $A(mode)} - eval $call - markMenuItem -m "Active Commands" $cmd off - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{activate} -% The |activate| procedure activates the bindings for the \eemenu\ -% commands listed as arguments. It has the syntax -% \begin{quote} -% |eemenu::activate| \word{noisy} \word{\eemenu\ command}\regplus -% \end{quote} -% The procedure notices and handles the case that the binding for an -% already active command coincides with that of some command to -% activate, usually by deactivating the active command. The \word{noisy} -% argument controls how it will behave in this. If \word{noisy} is |0| -% then it will merely show a list of deactivations on the status bar, -% but if it is |1| then it will put up a dialog and ask first. -% \begin{tcl} -proc eemenu::activate {noisy args} { - eemenu::multiupvar binding cmdA - set deactiveL [list] - foreach cmd $args { -% \end{tcl} -% First determine the state of the binding. -% \begin{tcl} - array set A $cmdA($cmd) - set idx [eemenu::binding_index $A(mode) $A(binding)] - if {[info exists binding($idx)]} then { - if {![string compare $binding($idx) $cmd]} then {continue} -% \end{tcl} -% In this case the binding is being used by some other command. -% Should that be deactivated? -% \begin{tcl} - if {$noisy && ![dialog::yesno "To activate '$cmd', I must\ - first deativate '$binding($idx)'. Proceed?"]} then {continue} -% \end{tcl} -% Here we know it should. Deactivation can be simplified since the -% binding will anyway be overwritten later. -% \begin{tcl} - lappend deactiveL $binding($idx) - markMenuItem -m "Active Commands" $binding($idx) off - } -% \end{tcl} -% Now activate the binding, as was the original intention. -% \begin{tcl} - set binding($idx) $cmd - set call [keys::bindKey $A(binding)] - lappend call [list eemenu::main $cmd] - if {[string compare "<none>" $A(mode)]} then {lappend call $A(mode)} - eval $call - markMenuItem -m "Active Commands" $binding($idx) on\ - [text::Ascii 18 1] - } - if {!$noisy && [llength $deactiveL]} then { - status::msg "Deactivated commands: [join $deactiveL ", "]" - } -} -% \end{tcl} -% \end{proc} -% -% -% \subsection{Building and handling the menu} -% -% \begin{proc}{build_menu} -% The |build_menu| procedure builds the menu. It is called when the -% menu is initially created and whenever some command settings have -% been edited. -% \begin{tcl} -proc eemenu::build_menu {} { - eemenu::multiupvar cmdA binding - set items [list "Edit Commands[text::Ascii 201 1]"] - if {[array size cmdA] > 0} then { -%<atcl7> set cmdL [lsort -ignore [array names cmdA]] -%<!atcl7> set cmdL [lsort -dictionary [array names cmdA]] - lappend items [list Menu -n "Active Commands" -m\ - -p eemenu::menu_proc $cmdL] - lappend items "(-)" - foreach cmd $cmdL { - array set A $cmdA($cmd) - if {$A(in_menu)} then {lappend items $cmd} - } - } - global eeMenu - Menu -n $eeMenu -m -p eemenu::menu_proc $items - if {[array size cmdA]} then { - foreach idx [array names binding] { - markMenuItem -m "Active Commands" $binding($idx) on\ - [text::Ascii 18 1] - } - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{menu_proc} -% The |menu_proc| handles selection of items in the \emph{EE} menu and -% its submenu. The syntax is the standard -% \begin{quote} -% |eemenu::menu_proc| \word{menu} \word{item} -% \end{quote} -% \begin{tcl} -proc eemenu::menu_proc {menu item} { - global eeMenu - eemenu::multiupvar cmdA binding - switch -- $menu $eeMenu { - switch -- $item "Edit Commands" { - eemenu::edit_commands - } default { - eemenu::main $item - } - } "Active Commands" { - array set A $cmdA($item) - set idx [eemenu::binding_index $A(mode) $A(binding)] - if {[info exists binding($idx)] &&\ - ![string compare $binding($idx) $item]} then { - eemenu::deactivate $item - } else { - eemenu::activate 1 $item - } - } -} -% \end{tcl} -% \end{proc} -% -% -% \subsection{The command dialogs} -% \label{Ssec:CmdDialogs} -% -% The dialog for editing command settings has two levels. On the top -% level, the dialog has one page per command. This dialog allows one to -% select methods, but does not show any detail settings for the methods. -% The other level has one page for each method type (or less) and shows -% only the detail settings for that method. -% -% \begin{arrayvar}{detail_typeA} -% \begin{arrayvar}{detail_helpA} -% \begin{arrayvar}{detail_keyA} -% The |detail_typeA| and |detail_helpA| arrays define the items in the -% setting details dialog. They are sent as arguments to -% |dialog::handle|, and thus the indices have the form -% \meta{page}|,|\meta{name}. The \meta{page} is either |Extract| -% for the extraction method page, |Complete| for the completion -% method page, |Evaluate| for the evaulation method page, or |Report| -% for the report method page. The |detail_keyA| array gives the keys -% associated with the items. -% \end{arrayvar}\end{arrayvar}\end{arrayvar} -% -% \begin{arrayvar}{detail_defaultA} -% The |detail_defaultA| array is indexed by the name of a detail page -% (|Extract|, |Complete|, |Evaluate|, or |Report|). The entries are -% key--value lists that constitute suggested defaults for the -% \dots|_extra| items in the main dialog. -% \begin{tcl} -array set eemenu::detail_defaultA\ - {Extract {} Complete {} Evaluate {} Report {}} -% \end{tcl} -% \end{arrayvar} -% -% \begin{proc}{define_detail} -% The |define_detail| procedure is a helper to simplify the definition -% of items in the detail dialogs by handling internally all the odd -% variable names that are involved. The syntax is -% \begin{quote} -% |eemenu::define_detail| \word{page} \word{name} \word{key} -% \word{type} \word{value}\regopt\ \word{help}\regopt -% \end{quote} -% \word{page} and \word{name} specify the item. \word{key}, -% \word{type}, \word{value}, and \word{help} are what will be stored -% into the arrays. The return value is precisely \word{name}, so that -% one can put that in the |extract|, |complete|, |evaluate|, or -% |report| array in the same command as the item is defined. -% -% It is OK to define the same item several times, provided that the -% definitions are equal (or different only in the \word{value}s or -% in that one has a \word{help} and the other doesn't), but it is an -% error if they are different. -% \begin{tcl} -proc eemenu::define_detail {page name key type {val ""} {help ""}} { - upvar #0 eemenu::detail_typeA typeA eemenu::detail_helpA helpA\ - eemenu::detail_keyA keyA eemenu::detail_defaultA valA - set error "" - set idx "$page,$name" - if {![info exists keyA($idx)]} then { - set keyA($idx) $key - } elseif {"$key" != "$keyA($idx)"} then { - append error " Different keys: '$keyA($idx)' and '$key'." - } - if {![info exists typeA($idx)]} then { - set typeA($idx) $type - } elseif {"$type" != "$typeA($idx)"} then { - append error " Different types: '$typeA($idx)' and '$type'." - } - if {[string length $val]} then { - if {[info exists valA($page)]} then {array set A $valA($page)} - if {![info exists A($key)] || ![string length $A($key)]} then { - set A($key) $val - set valA($page) [array get A] - } - } - if {[string length $help]} then { - if {![info exists helpA($idx)]} then { - set helpA($idx) $help - } elseif {"$help" != "$helpA($idx)"} then { - append error " Different help texts: '$helpA($idx)' and '$help'." - } - } - if {[string length $error]} then { - dialog::alert "The detail setting '$name' for '$page' methods\ - has conficting definitions.$error This is an error that should - be fixed; for now, the second definition will be ignored." - } - return $name -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}{edit_commands} -% The |edit_commands| procedure puts up a dialog that lets the user -% edit the command settings. It takes no arguments and returns nothing. -% \begin{tcl} -proc eemenu::edit_commands {} { - global eemenu::extract eemenu::complete eemenu::evaluate\ - eemenu::report -% \end{tcl} -% The first thing to do is to determine the layout for command pages. -% \begin{tcl} - set layout [list] - lappend layout [list active flag Active "Is the binding active?"] - lappend layout [list binding binding "Command keybinding"] - lappend layout [list mode mode "Binding mode"] - lappend layout [list in_menu flag "Put in menu"] -% \smallskip -%<*atcl7> - set M [list] - foreach method [lsort -ignore [array names eemenu::extract]] { - lappend M [eemenu::Prettify $method] - } - lappend layout [list extractor [list menu $M] "Extraction method"] - lappend layout [list extract_extra [list hidden keyval] extract_extra] -% \smallskip - set M [list] - foreach method [lsort -ignore [array names eemenu::complete]] { - lappend M [eemenu::Prettify $method] - } - lappend layout [list complete [list menu $M] "Completion test"] - lappend layout [list complete_extra [list hidden keyval] complete_extra] -% \smallskip - set M [list] - foreach method [lsort -ignore [array names eemenu::evaluate]] { - lappend M [eemenu::Prettify $method] - } - lappend layout [list evaluator [list menu $M] "Evaluation method"] - lappend layout [list eval_extra [list hidden keyval] eval_extra] -% \smallskip - set M [list] - foreach method [lsort -ignore [array names eemenu::report]] { - lappend M [eemenu::Prettify $method] - } - lappend layout [list reporter [list menu $M] "Report method"] - lappend layout [list report_extra [list hidden keyval] report_extra] -%</atcl7> -%<*!atcl7> - set M [list] - foreach method [lsort -dictionary [array names eemenu::extract]] { - lappend M [eemenu::Prettify $method] - } - lappend layout [list extractor [list menu $M] "Extraction method"] - lappend layout [list extract_extra [list hidden keyval] extract_extra] -% \smallskip - set M [list] - foreach method [lsort -dictionary [array names eemenu::complete]] { - lappend M [eemenu::Prettify $method] - } - lappend layout [list complete [list menu $M] "Completion test"] - lappend layout [list complete_extra [list hidden keyval] complete_extra] -% \smallskip - set M [list] - foreach method [lsort -dictionary [array names eemenu::evaluate]] { - lappend M [eemenu::Prettify $method] - } - lappend layout [list evaluator [list menu $M] "Evaluation method"] - lappend layout [list eval_extra [list hidden keyval] eval_extra] -% \smallskip - set M [list] - foreach method [lsort -dictionary [array names eemenu::report]] { - lappend M [eemenu::Prettify $method] - } - lappend layout [list reporter [list menu $M] "Report method"] - lappend layout [list report_extra [list hidden keyval] report_extra] -%</!atcl7> -% \end{tcl} -% Then the call to |dialog::make_paged| can be constructed (in the -% |call| variable), but as it is convenient to do that in order, the -% page arguments (which are the easiest) will be constructed last. -% \begin{tcl} - global dialog::ellipsis - if {![info exists dialog::ellipsis]} then {auto_load dialog::make_paged} - set call [list dialog::make_paged] - set buttons [list] - lappend buttons "New${dialog::ellipsis}" "Add new command"\ - {eemenu::add_command ""} - lappend buttons "Duplicate${dialog::ellipsis}"\ - "Duplicate this command" {eemenu::add_command $currentpage} - lappend buttons "Rename${dialog::ellipsis}"\ - "Rename this command" {eemenu::rename_command} - lappend buttons "Delete${dialog::ellipsis}"\ - "Delete this command" { - if {[dialog::yesno "Are you sure you want to\ - delete '$currentpage'?"]} { - set pages [dialog::delete_pages $pages\ - [list $currentpage] delta_pages] - } - } - lappend buttons "Details${dialog::ellipsis}"\ - "Setting details for this command" { - eemenu::command_details $dial $currentpage - } - lappend call -addbuttons $buttons -changeditems mods\ - -alpha7pagelimit 2 -% \end{tcl} -% Finally the page arguments to |dialog::make_paged| can be appended -% and the actuall call made. -% \begin{tcl} - global eemenu::cmdA -%<atcl7> foreach cmd [lsort -ignore [array names eemenu::cmdA]] { -%<!atcl7> foreach cmd [lsort -dictionary [array names eemenu::cmdA]] { - lappend call [list $cmd [set eemenu::cmdA($cmd)] $layout] - } - set res [eval $call] -% \end{tcl} -% If |make_paged| terminates with an error (the user pressed -% \textsf{Cancel}) then processing of this procedure should stop here. -% Thus the |eval| above is quite in order. -% -% After that, the settings should be updated. The first step is to -% deactivate those commands whose activation state, binding, or mode -% has changed, since that has to be done before the old settings -% are cleared. -% \begin{tcl} - set call [list eemenu::deactivate] - newforeach {cmd keys} $mods { - if {[lsearch -regexp $keys {^(active|binding|mode)$}]>=0 &&\ - [info exists eemenu::cmdA($cmd)]} then { - lappend call $cmd - } - } - if {[llength $call]>1} then {eval $call} -% \end{tcl} -% Now the new settings can replace the old. -% \begin{tcl} - unset eemenu::cmdA - array set eemenu::cmdA $res -% \end{tcl} -% Then what remains is (i) to inform \Alpha\ that the changed command -% settings need to be saved, (ii) to make bindings for those commands -% that are active, and (iii) to add or remove items from the menu. -% \begin{tcl} - set call [list eemenu::activate 0] - set build_menu 0 -%<atcl7> newforeach {cmd keys} $mods { -%<!atcl7> foreach {cmd keys} $mods { - prefs::modified eemenu::cmdA($cmd) - if {![info exists eemenu::cmdA($cmd)]}\ - then {set build_menu 1; continue} - array set A [set eemenu::cmdA($cmd)] - if {$A(active) &&\ - [lsearch -regexp $keys {^(active|binding|mode)$}]>=0}\ - then {lappend call $cmd} - if {[lsearch -exact $keys in_menu]>=0} then {set build_menu 1} - } - if {[llength $call]>2} then {eval $call} - if {$build_menu} then {eemenu::build_menu} -} -% \end{tcl} -% The conditions used above rely to some extent on the fact that -% \emph{all} items on a dialog page that is added or deleted count as -% having been changed. -% \end{proc} -% -% \begin{proc}{add_command} -% The |add_command| procedure is called by a button script to add a -% new command page to the dialog. The syntax is -% \begin{quote} -% |eemenu::add_command| \word{template} -% \end{quote} -% where \word{template} is the name of a command whose settings should -% be copied, or an empty string if the default settings should be used. -% \begin{tcl} -proc eemenu::add_command {templ} { - set name [getline "Name of new command"] - if {![string length $name]} then {return} -%<atcl7> newforeach {page items} [uplevel 1 {set pages}] { -%<!atcl7> foreach {page items} [uplevel 1 {set pages}] { - if {![string compare $page $name]} then { - alternote "That name is already in use!" - return - } - } -% \end{tcl} -% By default, make new commands inactive and don't put them in the -% menu. This is to avoid silly errors in case the user wants to do -% a ``backup'' of a command. -% \begin{tcl} - set keyvals [list active 0 in_menu 0] - if {[string length $templ]} then { - set dial [uplevel 1 {set dial}] - set cpage [uplevel 1 {set currentpage}] -%<atcl7> newforeach {key item}\ -%<!atcl7> foreach {key item}\ - {binding {Command keybinding} mode {Binding mode} - extractor {Extraction method} extract_extra extract_extra - complete {Completion test} complete_extra complete_extra - evaluator {Evaluation method} eval_extra eval_extra - reporter {Report method} report_extra report_extra} { - lappend keyvals $key [dialog::valGet $dial "${cpage},${item}"] - } - } else { - lappend keyvals binding "" mode "" extractor "Raw" - upvar #0 eemenu::detail_defaultA defaultA - lappend keyvals extract_extra $defaultA(Extract) - lappend keyvals complete "Entire Selection" complete_extra\ - $defaultA(Complete) - lappend keyvals evaluator "Internal Tcl" eval_extra\ - $defaultA(Evaluate) - lappend keyvals reporter "Status Line" report_extra $defaultA(Report) - } - uplevel 1 [list dialog::add_page $name $keyvals [uplevel 2 set layout]] - uplevel 1 [list set currentpage $name] -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{rename_command} -% The |rename_command| procedure is called by a button script to rename -% an existing command. There are no arguments. -% \begin{tcl} -proc eemenu::rename_command {} { - upvar 1 currentpage cpage dial dial - set name [getline "New name for command '$cpage'"] - if {![string length $name]} then {return} -%<atcl7> newforeach {page items} [uplevel 1 {set pages}] { -%<!atcl7> foreach {page items} [uplevel 1 {set pages}] { - if {![string compare $page $name]} then { - alternote "That name is already in use!" - return - } - } -% \end{tcl} -% Technically, the page with the old name is deleted and a new page -% with the new name is added. The keyvals have to saved to a list in -% between. -% \begin{tcl} - set keyvals [list] -%<atcl7> newforeach {key item} {active Active in_menu {Put in menu}\ -%<!atcl7> foreach {key item} {active Active in_menu {Put in menu}\ - binding {Command keybinding} mode {Binding mode}\ - extractor {Extraction method} extract_extra extract_extra\ - complete {Completion test} complete_extra complete_extra\ - evaluator {Evaluation method} eval_extra eval_extra\ - reporter {Report method} report_extra report_extra} { - lappend keyvals $key [dialog::valGet $dial "${cpage},${item}"] - } - uplevel 1 { - set pages [dialog::delete_pages $pages [list $currentpage]\ - delta_pages] - } - uplevel 1 [list dialog::add_page $name $keyvals [uplevel 2 set layout]] - set cpage $name -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{command_details} -% The |command_details| procedure is called by a button script to let -% the user see and edit the details of a command. The syntax is -% \begin{quote} -% |eemenu::command_details| \word{dialog ref.} \word{command} -% \end{quote} -% The \word{dialog ref.} is the reference to pass on to -% |dialog::valGet| and the like, as that is the only way to access the -% data that should be shown in the dialog. The \word{command} is the -% name of the command whose details should be shown, which is also the -% \meta{page} part of the array index that |dialog::valGet| needs. -% -% Most of this procedure consists of moving data from the data -% structures of one dialog to those of another, and back again. More -% precisely, data is taken from the \dots|_extra| items in the main -% dialog and put (using |array set|) into the local arrays |A1|, |A2|, -% |A3|, and |A4|. Then those entries in these arrays which correspond -% to details for the current set of methods are stored as dialog item -% values for |dial2|. At the end, those |dial2| items values that were -% changed are copied back to the corresponding |A| array, and then -% these arrays are put back (using |array get|) into the corresponding -% \dots|_extra| items in the main dialog. -% -% At the same time as the data are copied from the main dialog to the -% details dialog, the list of pages and items in the latter is being -% built. The information about this is taken from the |extract|, -% |complete|, |evaluate|, and |report| arrays. -% \begin{tcl} -proc eemenu::command_details {dial command} { - global eemenu::detail_typeA eemenu::detail_helpA\ - eemenu::detail_keyA eemenu::extract eemenu::complete\ - eemenu::evaluate eemenu::report - set pages [list] - set dial2 [dialog::create] -% \end{tcl} -% Exactly the same processing is done for all four pages of the -% details dialog, but since the location of the source data varies a -% bit irregularly between the pages, it is easiest to make a table of -% which variables and indices should be used. There is one line per -% page in the |newforeach| below. -% \begin{tcl} -%<atcl7> newforeach {which page layoutarr data arr} { -%<!atcl7> foreach {which page layoutarr data arr} { - {Extraction method} Extract eemenu::extract extract_extra A1 - {Completion test} Complete eemenu::complete complete_extra A2 - {Evaluation method} Evaluate eemenu::evaluate eval_extra A3 - {Report method} Report eemenu::report report_extra A4 - } { - set method [eemenu::Unprettify\ - [dialog::valGet $dial ${command},${which}]] - set L [set ${layoutarr}($method)] - if {[llength $L]} then { - lappend pages $page $L - array set $arr [dialog::valGet $dial ${command},${data}] - foreach l $L { - set v [set eemenu::detail_keyA($page,$l)] - if {[info exists ${arr}($v)]} then { - dialog::valSet $dial2 "$page,$l" [set ${arr}($v)] - } else { -% \end{tcl} -% It turns out \AlphaEight\ doesn't like an empty string as value for -% a checkbox, so the value is explicitly set to |0| for flags. -% \changes{v\,0.3}{2003/04/11}{Added special default for flag items. -% A similar fix should be put in the dialogs code. (LH)} -% \begin{tcl} - switch -- [set eemenu::detail_typeA($page,$l)] flag { - dialog::valSet $dial2 "$page,$l" 0 - } default { - dialog::valSet $dial2 "$page,$l" "" - } - } - } - } - } -% \smallskip - if {![llength $pages]} then { - dialog::alert "There are no details for these methods." - dialog::cleanup $dial2 - return - } - dialog::handle $pages eemenu::detail_typeA $dial2\ - eemenu::detail_helpA page [list]\ - [list [list "Back" "Return to overall dialog" ""] right first] -% \smallskip - set L [dialog::changed_items $dial2] - foreach item $L { - switch -glob $item { - Extract,* {set arr A1} - Complete,* {set arr A2} - Evaluate,* {set arr A3} - Report,* {set arr A4} - } - set ${arr}([set eemenu::detail_keyA($item)])\ - [dialog::valGet $dial2 $item] - } -%<atcl7> newforeach {page data arr} { -%<!atcl7> foreach {page data arr} { - Extract extract_extra A1 - Complete complete_extra A2 - Evaluate eval_extra A3 - Report report_extra A4 - } { - if {[lsearch -glob $L "${page},*"] >= 0} then { - dialog::valChanged $dial "${command},${data}" [array get $arr] - } - } - dialog::cleanup $dial2 -} -% \end{tcl} -% \end{proc} -% -% -% \subsection{\texttt{dialogsNew} patch} -% -% In the testing stage, I discovered that the |edit_commands| procedure -% managed to overstress \Alpha7's |dialog| command almost without -% trying. It is probably the large number of popup menus that is causing -% trouble, but regardless of the cause, I found that I couldn't use this -% dialog if it tried to show more than two commands. -% -% The \textsf{Edit Filesets} command faces a similar limitation and to -% work around that there is a separate \textsf{Edit A Fileset} command. -% As I didn't feel that much like reconstructing the \textsf{Edit -% Commands} dialog however, I instead redesigned |dialog::make_paged| -% so that \emph{it} automatically splits the dialog when there are too -% many pages in it. The redesigned |make_paged| will however probably -% not make it into Alpha\Tcllogo\ before v\,7.6d3 and at the moment -% that seems like a bit restrictive to me. Hence \emph{EE~Menu} will -% patch the \texttt{dialogsNew} code if this change hasn't already -% been incorporated. -% -% \begin{tcl} -%<*dialogspatch&atcl7> -if {![llength [info commands dialog::make_paged]]} then { - auto_load dialog::make_paged -} -if {![regexp -- -alpha7pagelimit [info body dialog::make_paged]]} then { -% \end{tcl} -% The following is copied from \texttt{dialogsNew.dtx} v\,1.4. -% -% \setnamespace{dialog} -% -% \begin{proc}{make_paged} -% The |make_paged| procedure is similar to the |make| procedure, but -% its argument argument structure is slightly different, its return -% value is very different, and it does have a couple of features that -% |make| doesn't (such as adding or removing pages or items in a -% dialog). The basic syntax is the same -% \begin{quote} -% |dialog::make_paged| \meta{option}\regstar\ \word{page}\regplus -% \end{quote} -% but here each \word{page} is a list with the structure -% \begin{quote} -% \word{page name} \word{key--value list} \word{item list} -% \end{quote} -% and each \word{item list} in turn is a list of items, each of with -% are themselves lists and have the structure -% \begin{quote} -% \word{key} \word{type} \word{name} \word{help}\regopt -% \end{quote} -% The return value is a list with the structure -% \begin{quote} -% \begin{regexp}[\regplus]\word{page name} -% \word{key--value list}\end{regexp} -% \end{quote} -% and in both cases the \word{key--value list} has the format of a -% list returned by |array get|, i.e., -% \begin{quote} -% \begin{regexp}[\regstar]\word{key} \word{value}\end{regexp} -% \end{quote} -% -% Rather than (as with |make|) including the value of an item in its -% \word{item} list, that list contains a \word{key} which references -% a value stored in the \word{key--value list} of that page. The idea -% with this is that the input and output formats for values should be -% the same, so that the caller has little overhead in converting from -% one data format to another. The \word{key--value list} format is -% furthermore flexible in that is completely insensitive to changes -% that add, remove, or rearrange items within a page. Extra -% key--value pairs in the input are ignored and an empty string is -% substituted as value for pairs that are missing. -% -% The \meta{option}s understood by |make_paged| are -% \begin{quote} -% |-ok| \word{OK button title}\\ -% |-cancel| \word{cancel button title}\\ -% |-title| \word{dialog window title}\\ -% |-defaultpage| \word{name of default page}\\ -% |-addbuttons| \word{button list}\\ -% |-width| \word{dialog window width}\\ -% |-alpha7pagelimit| \word{maximal number of pages}\\ -% |-debug| \word{debug level}\\ -% |-changedpages| \word{var-name}\\ -% |-changeditems| \word{var-name} -% \end{quote} -% Those that are common with |make| work exactly the same. The -% |-changedpages| option specifies that the caller wants to know on -% which pages something was changed. The \word{var-name} is the name -% of a variable in the caller's local context which will be set to -% the list of (names of) pages where some item value was changed. The -% |-changeditems| option is similar, but here the variable will be set -% to a list with the structure -% \begin{quote} -% \begin{regexp}[\regstar]\word{page name} -% \word{key list}\end{regexp} -% \end{quote} -% where the \word{key list}s are lists of the \emph{keys} of items on -% that page whose values were changed. -% -% \begin{tcl} -proc dialog::make_paged {args} { -% \end{tcl} -% -% |make_paged| largely has the same local variables as |make|, but -% there are some additions. The major arrays are -% \begin{description} -% \item[\texttt{pageA}] -% The index into this array is the name of a page. An entry -% contains the list of names of items on that page. -% \item[\texttt{typeA}] -% The index into this array has the form -% \meta{page}|,|\meta{item}, where \meta{page} is the name of a -% page and \meta{item} is the name of an item on that page. An -% entry contains the type of that item. -% \item[\texttt{keyA}] -% The index has the same form as in the |typeA| array. An entry -% contains the \word{key} for that item. -% \item[\texttt{helpA}] -% The index has the same form as in the |typeA| array. An entry -% contains the help text for that entry, but an item needs not -% have an entry in this array (it can be left unset). -% \end{description} -% There are a couple of additional scalar variables that are of -% interest. -% \begin{description} -% \item[\texttt{retCode}, \texttt{retVal}] -% When the |retCode| variable is set, the dialog is logically -% closed and the procedure returns. If the variable is set to |0| -% then |make| executes a normal return and the returned value will -% be the list of item values. If the variable is set to anything -% else then that will used for the |-code| option of |return| and -% the returned value will be taken from the |retVal| variable, -% which must then be initalised. -% \item[\texttt{dial}] -% This contains the reference string to use with |valGet|, -% |valSet|, and friends when accessing the values of items in -% the dialog. -% \item[\texttt{currentpage}] -% This contains the name of the current page in the dialog. -% \item[\texttt{delta\_pages}] -% This is the list of all pages which have been added to or -% deleted from the dialog since it was called. The |add_page| and -% |delete_page| procedures both directly access this list. It is -% needed to get the information for the |-changedpages| and -% |-changeditems| correct. -% \item[\texttt{pages}] -% This is a list of pages and items to show in the dialog. It is -% similar to the result of |array get pageA|, but the order of -% pages is as specified in the call and hidden pages are not -% included. -% \item[\texttt{opts(-addbuttons)}] -% This is \word{button list} specified by the caller. Button -% scripts can modify this list to change the text on their button. -% \item[\texttt{state}] -% This is initialized to |0| before the first time the dialog is -% shown and then the procedure leaves it alone. Button scripts may -% change it to keep track of what ``state'' (mostly: which -% items\slash pages are currently hidden) the dialog is in. -% \item[\texttt{splitstate}] -% This is the dialog splitting state and works as for -% |dialog::make|. -% \item[\texttt{optionL}] -% The list of additional options to pass to |dialog::handle|. -% \end{description} -% -% The first part of |dialog::make_paged| processes the arguments. -% \begin{tcl} - set opts(-ok) OK - set opts(-cancel) Cancel - set opts(-title) "" - set opts(-width) 400 - set opts(-debug) 0 - getOpts {-title -defaultpage -ok -cancel -addbuttons -width -debug\ - -alpha7pagelimit -changedpages -changeditems} - set dial [dialog::create] -% \end{tcl} -% The page arguments are interpreted by the |add_page| procedure. -% Since these pages aren't new in the sense that is relevant for the -% |delta_pages| list, that variable is reset afterwards. The -% |splitstate| variable is implicitly updated by |add_page|. -% \begin{tcl} - set pages [list] - set delta_pages [list] - if {[info exists opts(-alpha7pagelimit)] && [info tclversion]<8.0}\ - then { - set splitstate below - } else { - set splitstate off - } - foreach pagearg $args { - eval [list dialog::add_page] $pagearg - } - set delta_pages [list] - if {$splitstate=="page"} then {set splitstate menu} - if {[info exists opts(-defaultpage)]} then { - set currentpage $opts(-defaultpage) - } else { - set currentpage [lindex $pages 0] - } - set optionL [list -width $opts(-width) -title $opts(-title)] - set main_buttons [list\ -% - [list $opts(-ok) "Click here to use the current settings."\ - {set retCode 0}\ -% - $opts(-cancel) "Click here to discard any\ - changes you've made to the settings."\ - {set retCode 1; set retVal "cancel"}]\ -% - first right] - set view_button [list [list {View dialog page}\ - {Click here to see the items on this page.}\ - {set splitstate page}]] - set back_button [list [list "Back"\ - {Click here to go back to the pages menu.}\ - {set splitstate menu}] first right] -% \end{tcl} -% -% The second part is the loop which lets the user edit the settings. -% \begin{tcl} - set state 0 - while {![info exists retCode]} { - switch -exact -- $splitstate off - below { - if {[info exists opts(-addbuttons)]} then { - set script [dialog::handle $pages typeA $dial helpA\ - currentpage $optionL [list $opts(-addbuttons)]\ - $main_buttons] - } else { - set script [dialog::handle $pages typeA $dial helpA\ - currentpage $optionL $main_buttons] - } - } menu { - set altpages [list] - set n 1 - foreach item $pages { - if {$n} then { - lappend altpages $item - set n 0 - } else { - lappend altpages {} - set n 1 - } - } - set script [dialog::handle $altpages typeA $dial helpA\ - currentpage $optionL $view_button $main_buttons] - } page { -% \end{tcl} -% This is a small test to make sure that the value of |currentpage| -% is valid. If it isn't then one should return to the |menu| state. -% \begin{tcl} - if {![info exists pageA($currentpage)]} then { - set splitstate menu - continue - } - set altpages [list $currentpage $pageA($currentpage)] - if {[info exists opts(-addbuttons)]} then { - set script [dialog::handle $altpages typeA $dial helpA\ - currentpage $optionL [list $opts(-addbuttons)]\ - $back_button] - } else { - set script [dialog::handle $altpages typeA $dial helpA\ - currentpage $optionL $back_button] - } - } - if {[catch $script err]} then { -% \end{tcl} -% The rest of this loop is simply for gracefully handling errors that -% occur when button scripts are evaluated. -% \begin{tcl} - global errorInfo - set errinfo $errorInfo - if {$opts(-debug)} then { - tclLog "Error in button script '$script'" - tclLog $err - } - dialog::cleanup $dial - return -code 1 -errorinfo $errinfo\ - "Error '$err' when evaluating button script." - } - } -% \end{tcl} -% -% The third part is as in |make| responsible for constructing the result -% to return (at normal returns). Unlike the case with |make|, the -% return value covers only the items currently in |pages|. This -% part is also responsible for constructing the lists of changed -% pages and items. Two important variables in this are |cS| and |cA|. -% |cS| is an array which is used to test whether a certain item has -% been changed (via |valChanged|), but the only thing that matters is -% whether an entry has been set or not. |cA| is an array indexed by -% page name, whereas the entries are lists of keys of items on that -% page which have been changed. -% \begin{tcl} - if {$retCode==0} then { - set retVal [list] - global dialog::mute_types - foreach page $delta_pages { - foreach name $pageA($page) { - lappend cA($page) $keyA($page,$name) - } - } - foreach item [dialog::changed_items $dial] {set cS($item) ""} - newforeach {page items} $pages { - set res [list] - foreach name $items { - set T "$page,$name" - if {[lsearch -exact ${dialog::mute_types}\ - [lindex $typeA($T) 0]] < 0} then { - lappend res $keyA($T) [dialog::valGet $dial $T] - if {[info exists cS($T)]} then { - lunion cA($page) $keyA($T) - } - } - } - lappend retVal $page $res - } - if {[info exists opts(-changedpages)]} then { - upvar 1 $opts(-changedpages) cp - set cp [array names cA] - } - if {[info exists opts(-changeditems)]} then { - upvar 1 $opts(-changeditems) ci - set ci [array get cA] - } - } - dialog::cleanup $dial - return -code $retCode $retVal -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{add_page} -% The |add_page| procedure can be called from within the |make_paged| -% procedure to add a new page to the dialog. The syntax is -% \begin{quote} -% |dialog::add_page| \word{page name} \word{key--value list} -% \word{item list} \word{position}\regopt -% \end{quote} -% Here the \word{page name}, \word{key--value list}, and \word{item -% list} coincide with those parts of a \word{page} argument of -% |make_paged|. -% -% |add_page| works by modifying the arrays |typeA|, |keyA|, |helpA|, -% and |pageA|, the lists |pages| and |delta_pages|, and the variable -% |splitstate| in the caller's local context. It also uses the value -% in the |dial| variable there as an argument to |valSet| and the -% |opts| array to access the |-alpha7pagelimit| value. All of these -% variables are assumed to function as they do in the |make_paged| -% procedure. -% -% The \word{position} argument can be used to specify where in the -% |pages| list that the new page should be inserted. It defaults to -% |end|, which puts the new page last. Otherwise the argument should -% be numeric: |0| means put first, |1| means put second, |2| means put -% third, etc. -% -% If |splitstate| is |below| and the number of pages equals (or is -% greater than) the |-alpha7pagelimit| then the |splitstate| is -% changed to |page|. If |splitstate| is |menu| then it is also -% changed to |page|. -% \begin{tcl} -proc dialog::add_page {page keyvalL itemsL {pos end}} { - upvar pageA pageA typeA typeA helpA helpA keyA keyA\ - dial dial pages pages delta_pages delta_pages\ - splitstate splitstate opts opts - array set local $keyvalL - set pageA($page) [list] - lunion delta_pages $page - foreach item $itemsL { - set key [lindex $item 0] - set name [lindex $item 2] - set keyA($page,$name) $key - if {[info exists local($key)]} then { - dialog::valSet $dial $page,$name $local($key) - } else { - dialog::valSet $dial $page,$name "" - } - set typeA($page,$name) [lindex $item 1] - if {[llength $item]>3} then { - set helpA($page,$name) [lindex $item 3] - } - lappend pageA($page) $name - } - if {$pos!="end"} then { - set pages [linsert $pages [expr {2*$pos}] $page $pageA($page)] - } else { - lappend pages $page $pageA($page) - } - if {$splitstate=="menu" || ($splitstate=="below" &&\ - [llength $pages]>2*$opts(-alpha7pagelimit))} then { - set splitstate page - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{delete_pages} -% In one sense, this procedure does the opposite of |add_page|, but -% it can be used to achieve different effects as well. Basically it -% takes a list of page names and items, in the format for the first -% argument of |handle|, and returns the same list with some pages -% removed. The syntax is -% \begin{quote} -% |dialog::delete_pages| \word{pages} \word{delete-list} -% \word{deleted-var}\regopt -% \end{quote} -% where the \word{delete-list} is the list of names of pages to -% remove. \word{deleted-var} is, if it is given, the name of a -% variable in the caller's local context containing a list of page -% names. The deleted pages are then unioned with this list. The most -% common value for \word{deleted-var} is |delta_pages|. -% -% If there is a \word{deleted-var} argument then this procedure might -% also modify the |splitstate| variable in the caller's local -% context. A value of |page| is changed to |menu| or |below| depending -% on how meny pages are returned and the value of -% |opts(-alpha7pagelimit)| in the caller's local context. (Both these -% variables must exist if |delete_pages| is called with a -% \word{deleted-var} argument.) -% \begin{tcl} -proc dialog::delete_pages {pages deleteL {deletedvar {}}} { - set res [list] - if {[string length $deletedvar]} then {upvar 1 $deletedvar diffL} - newforeach {page items} $pages { - if {[lsearch -exact $deleteL $page] == -1} then { - lappend res $page $items - } else { - lunion diffL $page - } - } - if {[string length $deletedvar]} then { - upvar splitstate state opts(-alpha7pagelimit) limit - switch -exact -- $state page - menu { - if {[llength $res]<=2*$limit} then { - set state below - } else { - set state menu - } - } - } - return $res -} -% \end{tcl} -% \end{proc} -% -% -% \begin{tcl} -} -%</dialogspatch&atcl7> -% \end{tcl} -% \setnamespace{eemenu} -% -% -% \section{Extraction methods} -% \label{Sec:Extraction} -% -% The extraction method is mainly a source of input for an \eemenu\ -% command, but it is also responsible for providing some feedback to the -% user in the event that an error occurs. This feedback should take the -% simple form of positioning the cursor at the beginning of the first -% piece of code that could not be evaluated successfully. Extraction -% methods are therefore expected to constantly keep track of the -% position where the cursor should be put if an error occurs: this is -% called the \emph{safe} position. As no other part of an \eemenu\ -% cares about positions, these are regarded as internal matters for -% the extraction mathod. The feedback from the main executive is -% restricted to answers to the simple questions ``Is the current position -% safe?'' and ``Did an error occur?'' -% -% Extractions are begun by a call to the -% \describestring[proc][eemenu::\meta{method}]{start}|start| -% procedure, which has the syntax -% \begin{quote} -% |eemenu::|\meta{method}|::start| \word{settings} -% \word{window}\regopt\ -% \begin{regexp}[\regopt]\word{start} \word{end}\end{regexp} -% \end{quote} -% The \word{settings} is the |extract_extra| list of the command, and -% contain the settings that should be used until the next call to -% |start|. This list may contain key--value pairs for details not used -% by the current method (but which presumably are used by others), and -% it needs not contain key--value pairs for every detail that the -% current method uses. Therefore the method should provide defaults -% when necessary. -% -% The \word{window} is the name of the window from which code should be -% extracted. If this is omitted then the extraction should default to -% using the current window. The \word{start} and \word{end} are -% positions of the beginning and end respectively of the interval from -% which code should be extracted, but they are normally not used. When -% these are omitted then the method may do whatever seems reasonable, -% but the following algorith is recommended: -% \begin{itemize} -% \item If there is a selection in the window, then substitute the -% position of its beginning for \word{start} and the position of its -% end for \word{end}. -% \item Otherwise do the entire window, i.e., let \word{start} be the -% |minPos| and \word{end} be the |maxPos|. -% \end{itemize} -% The main reason that \word{start} and \word{end} at all exist as -% arguments is that this simplifies testing and debugging, but it also -% enables virtual methods to make their own decisions about from where -% the code should be extracted. -% -% The |start| procedure returns the file name (complete path, no count) -% of the source window. This is passed on to the begin procedures of -% other methods, but most of them ignore it anyway. If something is -% wrong with the arguments supplied to it then |start| terminates with -% an error. -% -% To actually extract a line, the main executive calls the -% \describestring[proc][eemenu::\meta{method}]{next}|next| procedure, -% which has the syntax -% \begin{quote} -% |eemenu::|\meta{method}|::next| \word{is safe} -% \end{quote} -% This procedure returns the next extractable code line, or terminates -% with return code 9 if there is no more line. -% \changes{v\,0.2}{2002/12/26}{Throwing abort instead of error, since -% it otherwise catches too many real errors. (LH)} -% The \word{is safe} argument is |1| if the current position should be -% considered safe and |0| otherwise. -% -% Extraction is terminated by a call to the -% \describestring[proc][eemenu::\meta{method}]{finish}|finish| -% procedure. This has the syntax -% \begin{quote} -% |eemenu::|\meta{method}|::finish| \word{error?} -% \end{quote} -% where the \word{error?} argument is |1| if there was an error in -% evaluation and |0| otherwise. This procedure does not return any data. -% -% -% \subsection{Some position utilities} -% -% \textit{\textbf{Note:} The procedures in this subsection were probably -% not a good idea to start with, so they are no longer included by -% default.} For the historically interested reader, it may be remarked -% that the code below predates the addition in \AlphaTcl\,7.6 of |-w| -% options to most standard position procedures. -% -% Extraction procedures should generally not assume that the window from -% which code is being extracted is the current window. The reason for -% this is that if \Alpha\ is evaulating internally then the extracted -% code may bring some other window to front or, more commonly, create a -% new window (which will by default go on top of all others). This is -% kind of tricky since many of \Alpha's commands for working with -% positions implicitly assume that the positions are in the current -% window, but it can be delt with by storing positions are a pair -% |{|\word{row} \word{column}|}| instead, as the |rowColToPos| command -% which converts this to a standard position does accept a window -% argument. -% -% Handling explicitly such positions is however more work that it -% should be, so here follows some generic utility procs to deal with -% positions specified as lists with the structure -% \begin{quote} -% \word{window} \word{row} \word{column} \word{standard pos}\regopt -% \end{quote} -% Here, \word{window} is a full window name (as returned by the -% |win::Current| procedure), whereas \word{row} and \word{column} -% are integers. The optional \word{standard pos} element is the standard -% position (that which should be used in calls to \Alpha\ primitives) if -% it has been computed by a call to |rowColToPos|. If it has not been -% computed then this element should not be present in the list. -% -% For \AlphaTk, there isn't much point in a distinction between the -% ``standard'' and row--column position formats as standard -% positions there are composed from a row and a column anyway. -% -% These procedures are put in the -% \describestring[namespace]{pos}|pos| namespace, as there is nothing -% in them that is specific to \eemenu. -% \begin{tcl} -%<*rowcol> -namespace eval pos {} -% \end{tcl} -% \setnamespace{pos} -% -% \begin{proc}{incr_row} -% \begin{proc}{incr_col} -% The |incr_row| and |incr_col| procedures increment the row and -% column respectively component of a position list. Their syntaxes are -% \begin{quote} -% |pos::incr_row| \word{pos-var} \word{row increment}\\ -% |pos::incr_col| \word{pos-var} \word{column increment} -% \end{quote} -% Incrementing the column can not cause the row to be incremented. -% Incrementing the row sets the column to |0|. The minimal column -% value is |0| and the minimal row value is |1|. There are no -% maximums in either. -% \begin{tcl} -proc pos::incr_row {var diff} { - upvar 1 $var V - set t [expr {[lindex $V 1] + $diff}] - if {$t<1} then { - set V [list [lindex $V 0] 1 0] - } else { - set V [list [lindex $V 0] $t 0] - } -} -proc pos::incr_col {var diff} { - upvar 1 $var V - set t [expr {[lindex $V 2] + $diff}] - set V [lrange $V 0 1] - if {$t<0} then {lappend V 0} else {lappend V $t} -} -% \end{tcl} -% \end{proc}\end{proc} -% -% \begin{proc}{get_standard} -% The |get_standard| procedure returns the standard position -% corresponding the row--column position stored in a variable. It has -% the syntax -% \begin{quote} -% |pos::get_standard| \word{pos-var} -% \end{quote} -% \begin{tcl} -proc pos::get_standard {var} { - upvar 1 $var V - if {[llength $V]<4} then { - lappend V [eval [list rowColToPos -w] $V] - } - return [lindex $V 3] -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{polyset} -% The |polyset| procedure is used to convert a list of standard -% positions in a certain window to row--column form and store those -% in variables, also given as a list. The syntax is -% \begin{quote} -% |pos::polyset| \word{window} \word{var-list} \word{pos-list} -% \end{quote} -% If there are more elements in the \word{var-list} than in the -% \word{pos-list} then the remaining elements will not be set. -% -% The reason this procedure works on lists is that \Alpha\ cannot -% (or at least will not) determine the row and column for a position -% unless that is in the current window. Therefore this procedure might -% have to temporarily bring some other window to front to do its stuff. -% \begin{tcl} -proc pos::polyset {win varL posL} { - if {$win != [win::Current]} then { - set top [win::Current] - bringToFront $win - } - set N [llength $varL] - if {$N > [llength $posL]} then {set N [llength $posL]} - for {set n 0} {$n < $N} {incr n} { - upvar 1 [lindex $varL $n] V - set V [concat [list $win]\ - [posToRowCol [lindex $posL $n]] [lindex $posL $n]] - } - if {[info exists top]} then {bringToFront $top} -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{RC_compare} -% The |RC_compare| procedure can be used to compare two row--column -% positions. The syntax is -% \begin{quote} -% |pos::RC_compare| \word{first pos} \word{second pos} -% \end{quote} -% and the result is as for |string compare|. It is an error if the -% \word{window} elements of the two arguments are different. -% \begin{tcl} -proc pos::RC_compare {a b} { - if {"[lindex $a 0]" != "[lindex $b 0]"} then { - error "Not the same <window>." - } - if {[lindex $a 1] < [lindex $b 1]} then { - return -1 - } elseif {[lindex $a 1] > [lindex $b 1]} then { - return 1 - } elseif {[lindex $a 2] < [lindex $b 2]} then { - return -1 - } elseif {[lindex $a 2] > [lindex $b 2]} then { - return 1 - } else { - return 0 - } -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}[eemenu]{get_extract_positions} -% The |get_extract_positions| procedure interprets the three optional -% arguments for a |start| procedure and sets two specified variables -% in the caller's local context to the row--column positions -% corresponding to the beginning and the end respectively of interval -% from which code should be extracted. The syntax is -% \begin{quote} -% |eemenu::get_extract_positions| \word{start-var} \word{end-var} -% \word{window}\regopt\ -% \begin{regexp}[\regopt]\word{start} \word{end}\end{regexp} -% \end{quote} -% This procedure returns the complete window name (including count). -% \begin{tcl} -proc eemenu::get_extract_positions {startvar endvar {win ""}\ - {startpos ""} {endpos ""}} { - if {![string length $win]} then {set win [win::Current]} - if {![string length $startpos]} then { - set startpos [getPos -w $win] - set endpos [selEnd -w $win] - if {[pos::compare $startpos == $endpos]} then { - set startpos [minPos] - set endpos [maxPos -w $win] - } - } - uplevel 1 [list pos::polyset $win [list $startvar $endvar]\ - [list $startpos $endpos]] - return $win -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}[eemenu]{get_text} -% The |get_text| procedure is mainly a wrapper around the |getText| -% command. The syntax is -% \begin{quote} -% |eemenu::get_text| \word{start-var} \word{end-var} -% \end{quote} -% where \word{start-var} and \word{end-var} are names of variables -% in the caller's local context of row--column positions. The return -% value is the text between those positions. -% \begin{tcl} -proc eemenu::get_text {startvar endvar} { - upvar 1 $startvar S $endvar E - if {"[lindex $S 0]" != "[lindex $E 0]"} then { - error "Not the same <window>." - } - getText -w [lindex $S 0] [pos::get_standard S] [pos::get_standard E] -} -%</rowcol> -% \end{tcl} -% \end{proc} -% -% -% -% -% \subsection{Raw extraction} -% -% \begin{arrayentry}[eemenu]{extract}{raw} -% Raw extraction has no details. -% \begin{tcl} -set eemenu::extract(raw) [list] -namespace eval eemenu::raw {} -% \end{tcl} -% \end{arrayentry} -% \setnamespace{eemenu::raw} -% -% \subsubsection{Row--column based extraction} -% -% This was my original implementation of raw extraction. Unfortunately -% it seems that |rowColToPos| is rather slow in \AlphaEight. Hence -% there is an alternative implementation below. -% -% \begin{proc}{start} -% \begin{variable}{cur_pos} -% \begin{variable}{safe_pos} -% \begin{variable}{end_pos} -% As this |start| procedure has no details to deal with, it only -% has to initialize the three position variables |cur_pos| (current -% position), |safe_pos| (most recent safe position), and |end_pos| -% (the end position). -% \begin{tcl} -%<*rowcol> -proc eemenu::raw::start {details args} { - eemenu::multiupvar cur_pos safe_pos end_pos - set win\ - [eval [list eemenu::get_extract_positions cur_pos end_pos] $args] - set safe_pos $cur_pos - return [win::StripCount $win] -} -% \end{tcl} -% \end{variable}\end{variable}\end{variable}\end{proc} -% -% -% \begin{proc}{next} -% The |next| procedure is also as simple as it can possibly be. The -% only nontrivial thing about it is that it removes carriage returns -% and linefeeds at the end of the text returned by -% |eemenu::get_text|. -% \begin{tcl} -proc eemenu::raw::next {at_safe} { - eemenu::multiupvar cur_pos safe_pos end_pos - if {[pos::RC_compare $cur_pos $end_pos]>=0} then {return -code 9 "Done"} - set this $cur_pos - if {$at_safe} then {set safe_pos $this} - pos::incr_row cur_pos 1 - if {[pos::RC_compare $cur_pos $end_pos]>0} then { - set cur_pos $end_pos - } - string trimright [eemenu::get_text this cur_pos] "\n\r" -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{finish} -% The |finish| procedure is slightly trickier that it has to be. -% Rather than doing a |goto| to the safe position, it does a |select| -% followed by a |markHilite|, with the end position as end, so that -% the mark will be at the end. -% \begin{tcl} -proc eemenu::raw::finish {was_error} { - if {!$was_error} then {return} - eemenu::multiupvar safe_pos end_pos - bringToFront [lindex $safe_pos 0] - select [pos::get_standard safe_pos] [pos::get_standard end_pos] - markHilite -} -%</rowcol> -% \end{tcl} -% \end{proc} -% -% -% \subsubsection{Queued extraction} -% -% This alternative implementation of the \textsf{raw} method is based on -% extracting a bit more than one would usually need and store the -% surplus in a queue of lines that haven't been extracted yet. -% -% \begin{variable}{line_queue} -% \begin{variable}{window} -% \begin{variable}{cur_pos} -% \begin{variable}{from_pos} -% \begin{variable}{safe_pos} -% \begin{variable}{end_pos} -% The |window| variable holds the name of the window from which text -% is being extracted. -% The |line_queue| variable is the text that has been gotten from the -% window but not yet been properly extracted, split into lines. The -% last line is incomplete and thus text must be added to the queue -% whenever it has length less than two. -% -% The |cur_pos| variable is the standard position of the beginning of -% the first line in |line_queue|. The |from_pos| variable is the -% first position after the last piece of data in |line_queue|. The -% |safe_pos| is the last position reported to be safe and the |end_pos| -% is the position at which extraction should stop. -% \end{variable}\end{variable}\end{variable}\end{variable}\end{variable} -% \end{variable} -% -% \begin{proc}{start} -% As this |start| procedure has no details to deal with, it only -% has to initialize the six above variables. -% \changes{v\,0.3}{2003/05/28}{Storing the tail of the file name, not -% the whole path. This avoids unnecessary file system accesses. (LH) -% Cf. bug 919.} -% \changes{v\,0.3.1}{2003/07/19}{Using complete paths in \AlphaTk, due -% to bug~1026. (LH)} -% \begin{tcl} -%<*!rowcol> -proc eemenu::raw::start {details {win ""} {startpos ""} {endpos ""}} { - eemenu::multiupvar line_queue window cur_pos from_pos safe_pos end_pos - global alpha::platform - if {![string length $win]} then {set win [win::Current]} - switch -- ${alpha::platform} alpha { - set win_tail [file tail $win] - } default { - set win_tail $win - } - if {![string length $startpos]} then { - set startpos [getPos -w $win_tail] - set endpos [selEnd -w $win_tail] - if {[pos::compare $startpos == $endpos]} then { - set startpos [minPos] - set endpos [maxPos -w $win_tail] - } - } - set line_queue [list ""] - set window $win_tail - set cur_pos $startpos - set from_pos $startpos - set safe_pos $startpos - set end_pos $endpos - return [win::StripCount $win] -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}{next} -% The |next| procedure first retrieves data from the window (if -% necessary) and then it extracts the first line from the queue. Data -% beyond the |end_pos| are never read into the queue. -% -% There are two versions of this procedure to account for the new -% addition of a |-w| option to |pos::compare| and |pos::math|. -% \changes{v\,0.1.2}{2002/12/26}{Fixed a bug concerning pos::compare, -% where string compare syntax was used. (LH, who is sure he has -% fixed this bug before.)} -% \begin{tcl} -%<*atcl7> -if {[alpha::package vsatisfies -loose\ - [alpha::package versions AlphaTcl] 7.6d2]} then { -%</atcl7> - proc eemenu::raw::next {at_safe} { - eemenu::multiupvar line_queue window cur_pos from_pos safe_pos\ - end_pos - if {[llength $line_queue] < 2} then { - if {[pos::compare -w $window $cur_pos >= $end_pos]} then { - return -code 9 "Done" - } - set next_pos [pos::math -w $window $from_pos + 1024] - if {[pos::compare -w $window $next_pos >= $end_pos]} then { - set next_pos $end_pos - } - set text [lindex $line_queue end] - append text [getText -w $window $from_pos $next_pos] - set line_queue [split $text "\n\r"] - set from_pos $next_pos - } - if {$at_safe} then {set safe_pos $cur_pos} - set line [lindex $line_queue 0] - set line_queue [lreplace $line_queue 0 0] - set cur_pos\ - [pos::math -w $window $cur_pos + [expr {[string length $line]+1}]] - set line - } -%<*atcl7> -} else { - proc eemenu::raw::next {at_safe} { - eemenu::multiupvar line_queue window cur_pos from_pos safe_pos end_pos - if {[llength $line_queue] < 2} then { - if {[pos::compare $cur_pos >= $end_pos]} then { - return -code 9 "Done" - } - set next_pos [pos::math $from_pos + 1024] - if {[pos::compare $next_pos >= $end_pos]} then { - set next_pos $end_pos - } - set text [lindex $line_queue end] - append text [getText -w $window $from_pos $next_pos] - set line_queue [split $text "\n\r"] - set from_pos $next_pos - } - if {$at_safe} then {set safe_pos $cur_pos} - set line [lindex $line_queue 0] - set line_queue [lreplace $line_queue 0 0] - set cur_pos [pos::math $cur_pos + [expr {[string length $line]+1}]] - set line - } -} -%</atcl7> -% \end{tcl} -% \end{proc} -% -% \begin{proc}{finish} -% This |finish| procedure clears the |line_queue|. It should usually -% be empty already, but better safe than sorry! -% \begin{tcl} -proc eemenu::raw::finish {was_error} { - eemenu::multiupvar line_queue window safe_pos end_pos - set line_queue [list] - if {!$was_error} then {return} - bringToFront $window - select $safe_pos $end_pos - markHilite -} -%</!rowcol> -% \end{tcl} -% \end{proc} -% -% -% \subsection{Regexp extraction} -% -% Regular expression extraction adds two features to what the raw -% extraction does. One is the filter---only lines meeting a certain -% condition are extracted, the others are skipped---and the other is the -% substitution---each line returned is first fed through a |regsub|. -% It would of course be possible to implement this from scratch, but it -% is more instructive (and slightly shorter) to base it on the |raw| -% method. -% -% \begin{arrayentry}[eemenu]{extract}{regexp} -% Regular expression extraction has four detail settings. -% \begin{tcl} -set eemenu::extract(regexp) [list\ -% \end{tcl} -% The first -% two are used in a ``filter'' that selects which lines will be -% extracted: -% \begin{details}{Extraction} -% \detailitem{filter_mode} -% This is the mode of operation for the filter. There are three -% possible values: |off| (no filtering, all lines are extracted), -% |grep| (only lines matching the |filterRE| regular expression -% are extracted), and |anti-grep| (only lines \emph{not} matching -% the |filterRE| regular expression are extracted). -% \begin{tcl} - [eemenu::define_detail Extract "Filter mode"\ - filter_mode [list menu [list off grep anti-grep]] off]\ -% \end{tcl} -% \detailitem{filterRE} -% This is the regular expression for the filter -% \begin{tcl} - [eemenu::define_detail Extract "Filter regular expression"\ - filterRE var]\ -% \end{tcl} -% \end{details} -% The last two are used in a straightforward |regsub| that is applied -% to each extracted line before it is returned to the main executive. -% \begin{details}{Extraction} -% \detailitem{searchRE} -% This is the regular expression searched for in the line. -% \begin{tcl} - [eemenu::define_detail Extract "Search (regexp):" searchRE var]\ -% \end{tcl} -% \detailitem{replaceRE} -% This is the regular expression for the replacement. -% \begin{tcl} - [eemenu::define_detail Extract "Replace (regexp):" replaceRE var]] -% \end{tcl} -% \end{details} -% \end{arrayentry} -% \begin{tcl} -namespace eval eemenu::regexp {} -% \end{tcl} -% \setnamespace{eemenu::regexp} -% -% \begin{proc}{start} -% \begin{arrayvar}{detA} -% This |start| procedure stores its details in the |D| array and calls -% the |evalmemu::raw::start| procedure to handle everything else. -% Note how it provides defaults for the detail settings it -% unconditionally uses, in case these are not present in the -% \word{details}. -% \begin{tcl} -proc eemenu::regexp::start {details args} { - global eemenu::regexp::detA - array set eemenu::regexp::detA\ - {filter_mode off searchRE {} replaceRE {}} - array set eemenu::regexp::detA $details - eval [list eemenu::raw::start $details] $args -} -% \end{tcl} -% \end{arrayvar}\end{proc} -% -% \begin{proc}{next} -% The |next| procedure starts with a loop that continues until it -% finds a line that passes the filter. -% \begin{tcl} -proc eemenu::regexp::next {at_safe} { - upvar #0 eemenu::regexp::detA D - while {1} { - set line [eemenu::raw::next $at_safe] - switch -- $D(filter_mode) { - off {break} - grep {if {[regexp -- $D(filterRE) $line]} then {break}} - anti-grep { - if {![regexp -- $D(filterRE) $line]} then {break} - } - } - } -% \end{tcl} -% Then it applies the |regsub| to the line. -% \begin{tcl} - regsub -all -- $D(searchRE) $line $D(replaceRE) line - return $line -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{finish} -% The |finish| procedure simply calls its equivalent for the |raw| -% method. -% \begin{tcl} -proc eemenu::regexp::finish {err} {eemenu::raw::finish $err} -% \end{tcl} -% \end{proc} -% -% -% -% \subsection{Docstrip extraction} -% -% Docstrip extraction is a descendant of the extraction mechanisms from -% the \textsf{dtxload} package. -% -% -% \begin{arrayentry}[eemenu]{extract}{docstrip} -% There are three detail settings for |docstrip| extraction. -% \begin{tcl} -set eemenu::extract(docstrip) [list\ -% \end{tcl} -% \begin{details}{Extraction} -% \detailitem{filePatL} -% This is a list of file patterns that the file name is tested -% against using |string match|. If none of them fits then -% extraction is stopped before is begins. -% \begin{tcl} - [eemenu::define_detail Extract "File patterns" filePatL var\ - "*.dtx" "List of glob-style file patterns the window must match"]\ -% \end{tcl} -% \detailitem{lookAtEnvs} -% If this is checked then extraction will be further conditioned -% by that the code line is in one of the environements listed in -% the next setting. I find this very convenient, since I often -% forget to comment out some lines here and there in the file. -% \begin{tcl} - [eemenu::define_detail Extract "Filter by environments"\ - lookAtEnvs flag 0]\ -% \end{tcl} -% \detailitem{sourceEnvsL} -% The list of environments from which code may be extracted. -% \begin{tcl} - [eemenu::define_detail Extract "Source environments"\ - sourceEnvsL var {tcl tcl*}]] -% \end{tcl} -% \end{details} -% \end{arrayentry} -% \begin{tcl} -namespace eval eemenu::docstrip {} -% \end{tcl} -% \setnamespace{eemenu::docstrip} -% -% \begin{variable}{cur_pos} -% \begin{variable}{safe_pos} -% \begin{variable}{end_pos} -% The |cur_pos|, |safe_pos|, and |end_pos| variables are as for the -% |raw| mathod. A special case is however that |safe_pos| will never -% be inside a verbatim section, even if it is safe there, since the -% extraction wouldn't remember that is was inside a verbatim section -% if it was restarted. Therefore the \word{is safe} argument to |next| -% will be ignored in verbatim sections. -% -% These variables are only used by the \Module{rowcol} variant. -% \end{variable}\end{variable}\end{variable} -% -% \begin{variable}{module_included} -% \begin{variable}{in_code_env} -% \begin{variable}{in_verbatim} -% The |module_included| variable keeps track of whether the current -% position is in an included module. It is |1| if the current -% position should be included and |0| if it shouldn't. -% The |in_code_env| variable is used for keeping track of the markup -% context of the currently considered line in the file when the -% |lookAtEnvs| setting is on. |in_code_env| is set to |1| when a -% |\begin{|\meta{env}|}| for an \meta{env} in the |sourceEnvsL| is -% scanned, and set to |0| when an |\end{|\meta{env}|}| is scanned. -% The |in_verbatim| variable is |1| when the current position is in -% a \textsf{docstrip} verbatim module and |0| (which is the normal -% case) otherwise. -% \end{variable}\end{variable}\end{variable} -% -% \begin{variable}{module_stack} -% \begin{variable}{next_module_idx} -% The |module_stack| variable is keeps track of how modules -% are nested around the currently considered line. The variable is a -% stack implemented as a list in which the last element corresponds to -% the innermost module. Each element in this list is itself a list -% with the structure -% \begin{quote} -% \word{expression} \word{start pos.} \word{previous}\regopt -% \end{quote} -% The \word{expression} is the guard expression, as a string. The -% \word{start pos.} is the (row--column) position in the file where -% the module started. -% Finally, the \word{previous} is a boolean value which -% records the inclusion status (value of |module_included|) -% that was in force before the module was entered. -% -% The |next_module_idx| variable holds the index in the -% |module_stack| list of the next module whose expression has not yet -% been evaluated; it is equal to |llength ${module_stack}| if all -% module expressions have been evaluated. Those elements in the -% |module_stack| list which have index $\geq$ |next_module_idx| do -% not have a \word{previous} element. -% \end{variable}\end{variable} -% -% -% \begin{proc}{start} -% The |docstrip| extraction |start| procedure is by far the most -% complicated, due to the many mechanisms it must initialize. -% \begin{tcl} -proc eemenu::docstrip::start {details args} { - eemenu::multiupvar detA module_included module_stack\ - next_module_idx in_code_env in_verbatim -% \end{tcl} -% First there are the position variables -% \begin{tcl} -%<*rowcol> - eemenu::multiupvar cur_pos safe_pos end_pos - set win [win::StripCount\ - [eval [list eemenu::get_extract_positions cur_pos end_pos] $args]] - set safe_pos $cur_pos -%</rowcol> -%<*!rowcol> - set win [eval [list eemenu::raw::start $details] $args] -%</!rowcol> -% \end{tcl} -% and secondly the setting details -% \begin{tcl} - array set detA {filePatL *.dtx lookAtEnvs 0} - array set detA $details -% \end{tcl} -% Then the method must check whether the detail setting permit -% extracting from this window. If not, the procedure raises an error -% (which isn't caught by |eemenu::main|). -% \begin{tcl} - set ok 0 - foreach pat $detA(filePatL) { - if {[string match $pat $win]} then {set ok 1; break} - } - if {!$ok} then { - status::msg "Can't extract from that window. Must be\ - [join $detA(filePatL) " or "]." - return -code 9 "Bad window name" - } -% \end{tcl} -% Now that it has been established that extraction will take place, -% the various variables defining the ``state of \textsf{dostrip}'' -% must be initialised. Four of them have standard values at start and -% present no problem. -% \begin{tcl} - set module_included 1 - set in_verbatim 0 - set module_stack [list] - set next_module_idx 0 -% \end{tcl} -% The |in_code_env| variable is however another matter, as the -% reasonable value for it depends very much on what characters follow -% the start position. The special value |-1| for |in_code_env| means -% ``change to |0| or |1| as appropriate when you get the first line''. -% \begin{tcl} - if {!$detA(lookAtEnvs)} then { - set in_code_env 1 - } else { -%<*rowcol> - set t_pos $cur_pos - pos::incr_col t_pos 2 - switch -regexp -- [eemenu::get_text cur_pos t_pos] { - ^%< {set in_code_env 1} - ^% {set in_code_env 0} - default {set in_code_env 1} - } -%</rowcol> -%<!rowcol> set in_code_env -1 - set detA(envsRE) {\\(begin|end) *\{(} - foreach env $detA(sourceEnvsL) { - append detA(envsRE) [quote::Regfind $env] "|" - } - append detA(envsRE) ")\}(.*)\$" - } - return $win -} -% \end{tcl} -% \end{proc} -% -% \begin{arrayentry}{detA}{envsRE} -% The |envsRE| entry in the |detA| array is used for storing the -% regular expression that is used when searching for code environment -% markup in comment lines. -% \end{arrayentry} -% -% Next comes a couple of utility procs that are called from the |next| -% procedure. -% -% \begin{arrayvar}{known}[expression] -% The |known| array records the values of all known expressions, -% i.e., those expressions about whose values the user has been -% inquired. The entries are either |0| (for ``don't include'') or -% |1| (for ``include''). Note that this array is not initialised by -% the |start| procedure---instead is cleared by the |finish| -% procedure if no error occurred. -% \end{arrayvar} -% -% \begin{proc}{eval_guard} -% The |eval_guard| procedure takes the string that is a guard -% expression as argument. It returns |1| if the expression evaluates -% to true and |0| if it evaluates to false. -% -% If the expression has an entry in the |known| array then the -% |eval_guard| procedure returns that value, and if it does not the -% user is inquired for the value. -% \begin{tcl} -proc eemenu::docstrip::eval_guard {e} { - global eemenu::docstrip::known - if {![info exists eemenu::docstrip::known($e)]} then { - set eemenu::docstrip::known($e)\ - [dialog::yesno "Should <$e> modules be included?"] - } - set eemenu::docstrip::known($e) -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}{push_module} -% The |push_module| procedure pushes a block module onto the -% module stack, but it does not modify the value of -% |module_included|. The syntax is -% \begin{quote} -% |eemenu::docstrip::push_module| \word{expression} \word{position} -% \end{quote} -% where \word{expression} is the expression string and -% \word{position} is the position (row--column or standard, depending -% on which kind of positions are being used) where the guard begins. -% \begin{tcl} -proc eemenu::docstrip::push_module {e p} { - global eemenu::docstrip::module_stack - lappend eemenu::docstrip::module_stack [list $e $p] -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{pop_module} -% The |pop_module| procedure pops a block module off the module -% stack and checks that the modules are properly nested. Its -% syntax is -% \begin{quote} -% |eemenu::docstrip::pop_module| \word{expression} \word{position} -% \end{quote} -% where \word{expression} is the expression string of the module to -% pop and \word{position} is the position (row--column or standard, -% depending on which kind of positions are being used) where the -% end of module guard begins. -% -% If the module nesting is incorrect then the user is presented with -% a dialog with buttons for pushing the positions of the incorrect -% modules. It is not an error if the module stack is empty, since it -% is perfectly reasonable that the beginning of the code to evaluate -% is in the middle of a module. -% -% \changes{ \textsf{dtxload} v\,1.11}{2001/05/11}{Corrected ugly bug -% which messed up the value of \texttt{next\_module\_idx}. (LH)} -% \begin{tcl} -proc eemenu::docstrip::pop_module {e p} { - eemenu::multiupvar module_stack module_included next_module_idx - set len [llength $module_stack] - if {$len==0} then {return} - set L [lindex $module_stack [expr {$len-1}]] - if {[lindex $L 0] != $e} then { - switch [buttonAlert "Module nesting error: <*[lindex $L 0]>\ - module ended by </$e>. For which guards should the positions\ - be pushed?" None Start End Both]\ - { - Start {eemenu::docstrip::push_bookmarks [lindex $L 1]} - End {eemenu::docstrip::push_bookmarks $p} - Both {eemenu::docstrip::push_bookmarks [lindex $L 1] $p} - } - } - set module_stack [lreplace $module_stack end end] - if {$len<=$next_module_idx} then { - set next_module_idx [llength $module_stack] - } - if {[llength $L]>2} then { - set module_included [lindex $L 2] - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{push_bookmarks} -% The |push_bookmarks| procedure pushes one or several positions -% (row--column or standard, depending on which kind of positions are -% being used) onto the bookmarks stack. The arguments are the -% positions to push. -% \changes{v\,0.3}{2003/05/28}{Changed some \texttt{win::Current} to -% \texttt{win::CurrentTail}. This avoids unnecessary file system -% accesses. (LH) Cf. bug 919.} -% \begin{tcl} -proc eemenu::docstrip::push_bookmarks {args} { - global markStack markName -%<!rowcol> upvar #0 eemenu::raw::window win - set topWin [win::CurrentTail] - foreach pos $args { - set name mark$markName - incr markName -%<*rowcol> - set win [lindex $pos 0] - if {"[win::CurrentTail]" != "$win"} then {bringToFront $win} - createTMark $name [pos::get_standard pos] - set fileName [win::Current] - set markStack [linsert $markStack 0\ - [list $fileName $name [pos::get_standard pos]]] -%</rowcol> -%<*!rowcol> - if {[string compare [win::CurrentTail] $win]}\ - then {bringToFront $win} - createTMark $name $pos - set fileName [win::Current] - set markStack [linsert $markStack 0 [list $fileName $name $pos]] -%</!rowcol> - } - if {[string compare [win::CurrentTail] $topWin]}\ - then {bringToFront $topWin} -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{update_included} -% Simply pushing a module onto the module stack does not update the -% |module_included| variable; that is instead done by the -% |update_included| procedure, which should be called right before the -% value of |module_included| is used. The reason for this arrangement -% is that it avoids evaluating guard expressions whose values do not -% matter. -% -% |update_included| has no arguments. -% \begin{tcl} -proc eemenu::docstrip::update_included {} { - eemenu::multiupvar module_stack module_included next_module_idx - while {$module_included && $next_module_idx<[llength $module_stack]} { - set L [lindex $module_stack $next_module_idx] - lappend L $module_included - set module_stack\ - [lreplace $module_stack $next_module_idx $next_module_idx $L] - incr next_module_idx - set module_included [eemenu::docstrip::eval_guard [lindex $L 0]] - } -} -% \end{tcl} -% \end{proc} -% -% \begin{variable}{end_verb_line} -% The |end_verb_line| variable stores the line which terminates -% verbatim mode. It is only initialised when verbatim mode is begun. -% \end{variable} -% -% \begin{proc}{next} -% The overall structure of the |next| procedure is that of an endless -% loop, from which the code |break|s out when it has found an -% extractable line. Should this loop run into the |end_pos| it -% terminates instead with a |return -code 9|. The local variable -% |next_pos| stores the position of the beginning of the next line. -% \begin{tcl} -proc eemenu::docstrip::next {is_safe} { - eemenu::multiupvar detA module_included in_code_env\ - in_verbatim module_stack next_module_idx end_verb_line -%<*rowcol> - eemenu::multiupvar cur_pos safe_pos end_pos - set next_pos $cur_pos -%</rowcol> -%<!rowcol> upvar #0 eemenu::raw::cur_pos raw_cur_pos - while {1} { -%<*rowcol> - pos::incr_row next_pos 1 - if {[pos::RC_compare $next_pos $end_pos]>0} then { - set next_pos $end_pos - } - if {[pos::RC_compare $cur_pos $next_pos]>=0} then { - return -code 9 "Done" - } -% \end{tcl} -% No matter what state the extraction process is in, it will need to -% look at the current line, so it is extracted and put in the |line| -% variable. Spaces at end of the line are ignored for compatibility -% with the \TeX\ \package{docstrip} (\TeX\ throws away spaces at the -% end of a line as part of the reading process, so \package{docstrip} -% cannot see them). -% \begin{tcl} - set line [string trimright [eemenu::get_text cur_pos next_pos]\ - "\r\n "] -%</rowcol> -% \end{tcl} -% In the standard positions implementation, getting text from the -% window is instead done by calling |eemenu::raw::next|. The position -% at the beginning of the line (the value of |eemenu::raw::cur_pos| -% before the call to |eemenu::raw::next|) is saved since it might be -% needed for making bookmarks later. -% \begin{tcl} -%<*!rowcol> - set cur_pos $raw_cur_pos - set line [eemenu::raw::next [expr {$is_safe && !$in_verbatim}]] - set line [string trimright $line "\r\n "] - if {$in_code_env<0} then { - switch -glob -- $line { - %<* {set in_code_env 1} - %* {set in_code_env 0} - default {set in_code_env 1} - } - } -%</!rowcol> -% \end{tcl} -% Verbatim mode is pretty simple. Either a line is an extractable -% code line or it is the end of verbatim mode guard. -% \begin{tcl} - if {$in_verbatim} then { - if {![string compare $line $end_verb_line]} then { - set in_verbatim 0 - } elseif {$module_included && $in_code_env} then { - break - } - } else { -% \end{tcl} -% In non-verbatim mode, lines are classified based on the first few -% characters of the line. -% \begin{tcl} - switch -glob -- $line { -% \end{tcl} -% Lines that begin with |%<<| are \package{docstrip} guard lines that -% start verbatim mode. The part of the guard line which comes after -% the |%<<| is called an end-tag. Verbatim mode ends with the next line -% which consists of a percent character followed by this end-tag -% \begin{tcl} - %<<* { - eemenu::docstrip::update_included -%<*rowcol> - if {$module_included && $in_code_env && $is_safe} then { - set safe_pos $cur_pos - } -%</rowcol> - set in_verbatim 1 - set end_verb_line "%[string range $line 3 end]" - } -% \end{tcl} -% Lines that begin with |%<*| or |%</| are \package{docstrip} guard -% lines that delimit block modules, but they do not contain any code -% themselves. The module is pushed onto or popped off the module stack -% when the guard line is encountered, but evaluating the guard -% expression is deferred until its value is needed. -% \begin{tcl} - %<[*/]* { - if {![regexp {^%<(\*|/)([^>]+)>} $line foo modifier\ - expression]}\ - then { - if {[dialog::yesno "Malformed guard line '$line'\ - encountered. Push position?"]}\ -% - then {eemenu::docstrip::push_bookmarks $cur_pos} - } elseif {$modifier=="*"} then { - eemenu::docstrip::push_module $expression $cur_pos - } else { - eemenu::docstrip::pop_module $expression $cur_pos - } - } -% \end{tcl} -% Other lines that begin with |%<| are also \package{docstrip} -% guard lines, but in these cases the guard is followed by some code -% and the guard only affects the code on that particular line. There -% must be a |>| somewhere on the line, and the part of the line after -% the |>| is code that \package{docstrip} can extract. -% \begin{tcl} - %<* { - if {![regexp {^%<(-|\+|)([^>]+)>(.*)$} $line\ - foo modifier expression code]}\ - then { - if {[dialog::yesno "Malformed guard line '$line'\ - encountered. Push position?"]}\ - then {eemenu::docstrip::push_bookmarks $cur_pos} - } elseif {$in_code_env} then { - eemenu::docstrip::update_included - if {$module_included &&\ - [eemenu::docstrip::eval_guard $expression] !=\ - ($modifier=="-")} then { - set line $code - break - } - } - } -% \end{tcl} -% Remaining lines that begin with |%| are considered comment lines, -% but they could technically be metacomment lines (begin with |%%|). -% In that case \package{docstrip} would copy the line, but as there -% is little point in using this \package{docstrip} features for -% lines that the \Tcllogo\ interpreter would be interested in, -% the |docstrip| extraction method ignores that subtlety. Comment -% lines are ignored unless the |lookAtEnvs| details is |1|, in which -% case they are scanned for code environment markup. -% \begin{tcl} - %* { - while {$detA(lookAtEnvs) &&\ - [regexp -- $detA(envsRE) $line foo type env line]} { - set in_code_env [expr {"$type"=="begin"}] - } - } -% \end{tcl} -% Finally, all lines that do not begin with a |%| are code lines. -% \begin{tcl} - default { - if {$in_code_env} then { - eemenu::docstrip::update_included - if {$module_included} then {break} - } - } - } - } -% \end{tcl} -% That ends the large |switch| command and the large |if|. Now all -% that remains in the loop is to update |cur_pos|. -% \begin{tcl} -%<rowcol> set cur_pos $next_pos - } -% \end{tcl} -% Whenever the procedure gets past the loop, the line that has been -% extracted is in |line| and the only thing that remains is to update -% the positions. -% \begin{tcl} -%<*rowcol> - if {$is_safe && !$in_verbatim} then {set safe_pos $cur_pos} - set cur_pos $next_pos -%</rowcol> - return $line -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{finish} -% In addition to the |raw| method |finish| procedure, this |finish| -% also unsets the |known| array when there wasn't an error. -% \begin{tcl} -proc eemenu::docstrip::finish {was_error} { -%<!rowcol> eemenu::raw::finish $was_error - if {$was_error} then { -%<*rowcol> - eemenu::multiupvar safe_pos end_pos - bringToFront [lindex $safe_pos 0] - select [pos::get_standard safe_pos] [pos::get_standard end_pos] - markHilite -%</rowcol> - } else { - global eemenu::docstrip::known - catch {unset eemenu::docstrip::known} - } -} -% \end{tcl} -% \end{proc} -% -% -% \section{Completeness tests} -% -% \setnamespace{eemenu} -% -% Unlike the other method types, completion methods are not implemented -% as procedures that can be called, but as an expression string stored -% in a global variable. The string in question is called -% \describestring[var.][eemenu::\meta{method}]{complete}|complete| -% and it will be evaluated as an \emph{expression} in the local context -% of the |main| procedure. The reason for this different set-up is that -% these methods are usually much simpler to handle that way. -% -% Completion methods are expected to get their data from the following -% variables: -% \begin{description} -% \item[\texttt{lines}] -% A list of the lines that have been extracted by not yet evaluated. -% This is (at least in theory) what the completion method is testing -% for being complete. -% \item[\texttt{at\_end}] -% A boolean. It is |0| if the extraction has not yet reached the -% end, and then it is set to |1|. -% \item[\texttt{CMD(complete\_extra)}] -% The key--value list of detail settings for completion methods. -% None of the methods currently implemented have any detail settings. -% \end{description} -% -% \begin{arrayentry}{complete}{entireSelection} -% \setnamespace{eemenu::entireSelection} -% \begin{variable}{complete} -% The |entireSelection| method says `No' until the entire selection -% has been extracted, then `Yes'. It has no detail settings. -% \begin{tcl} -set eemenu::complete(entireSelection) [list] -namespace eval eemenu::entireSelection {} -set eemenu::entireSelection::complete {$at_end} -% \end{tcl} -% \end{variable}\end{arrayentry} -% -% \begin{arrayentry}{complete}{everyLine} -% \setnamespace{eemenu::everyLine} -% \begin{variable}{complete} -% The |everyLine| method says `Yes' after every line. -% \begin{tcl} -set eemenu::complete(everyLine) [list] -namespace eval eemenu::everyLine {} -set eemenu::everyLine::complete {1} -% \end{tcl} -% \end{variable}\end{arrayentry} -% -% \begin{arrayentry}{complete}{tclInfoComplete} -% \setnamespace{eemenu::tclInfoComplete} -% \begin{variable}{complete} -% The |tclInfoComplete| method is the only one (defined so far) which -% actually cares to look at what has been extracted. It calls the -% |info complete| of \Alpha's \Tcllogo\ interpreter. -% \begin{tcl} -set eemenu::complete(tclInfoComplete) [list] -namespace eval eemenu::tclInfoComplete {} -set eemenu::tclInfoComplete::complete\ - {[info complete [join $lines \n]\n]} -% \end{tcl} -% \end{variable}\end{arrayentry} -% -% -% \section{Evaluation methods} -% -% The evaluation\slash execution method is what actually does anything -% (all the other methods just move data around). From an input\slash -% output perspective it takes the input from the extraction method and -% generates the output that the report method should handle. Like -% extraction methods, evaluation methods must declare three procedures -% for |main| to call. These are: |begin|, |item|, and |end|. All of -% these procedures return a \emph{result list}, which has the structure -% \begin{quote} -% \word{error?} \word{passing} \word{permanent} -% \end{quote} -% \word{error?} is a boolean that the main executive interprets to see -% if there was an error. It is |0| when there wasn't an error. -% \word{passing} and \word{permanent} are result strings. \word{passing} -% should be suitable for output channels where new results replace old, -% whereas \word{permanent} should be suitable for output channels where -% the results are appended to each other. If the \word{passing} string -% is empty then there is no reason to have it replace a previous -% \word{passing} string. If the \word{permanent} string is nonempty -% then it must end with a newline character. -% -% The \describestring[proc][eemenu::\meta{method}]{begin}|begin| -% procedure is called to initialize the evaluation process. It has the -% syntax -% \begin{quote} -% |eemenu::|\meta{method}|::begin| \word{details} \word{source} -% \end{quote} -% where the \word{details} is the key--value list of setting details -% and \word{source} is the source window name as returned by the -% extraction method |start| procedure. If the result of |begin| has a -% nonzero \word{error?} then the corresponding |end| procedure will not -% be called. -% -% The \describestring[proc][eemenu::\meta{method}]{item}|item| -% procedure recieves a bunch of code to evaluate. It has the syntax -% \begin{quote} -% |eemenu::|\meta{method}|::item| \word{lines} -% \end{quote} -% where \word{lines} is the list of lines of code to evaluate. The -% \describestring[proc][eemenu::\meta{method}]{end}|end| procedure is -% called when no more lines of code will be sent for evaluation. |end| -% takes no arguments. -% -% It is not necessarily in the call to |item| that the code gets -% evaluated. The obvious alternative is that |item| simply stores the -% code somewhere, for example by writing it to a temporary file, and -% that it is the call to |end| that actually causes the code to be -% evaluated. This is an important reason why all the procedures have the -% same format for returned data. -% -% -% -% \subsection{Internal evaluation} -% -% The |internalTcl| evaluation method sends the code to \Alpha's internal -% \Tcllogo\ interpreter and evaluates it there. -% -% \begin{arrayentry}[eemenu]{evaluate}{internalTcl} -% There are no details for this method. -% \begin{tcl} -set eemenu::evaluate(internalTcl) [list] -% \end{tcl} -% \end{arrayentry} -% \begin{tcl} -namespace eval eemenu::internalTcl {} -% \end{tcl} -% \setnamespace{eemenu::internalTcl} -% -% \begin{proc}{begin} -% \begin{proc}{end} -% Neither the |begin| nor the |end| procedure does anything. -% \begin{tcl} -proc eemenu::internalTcl::begin {details source} { - list 0 "" "" -} -proc eemenu::internalTcl::end {} {list 0 "" ""} -% \end{tcl} -% \end{proc}\end{proc} -% -% \begin{proc}{item} -% The |item| procedure actually evaluates the code and suitably -% formats the result. -% \begin{tcl} -proc eemenu::internalTcl::item {lines} { - set code [catch [list uplevel #0 [join $lines \n]] res] - if {$code == 1} then { -% \end{tcl} -% If there was an error, the last part of the value of |errorInfo| -% will be due to the |uplevel| command. As that command was not -% requested by the user, it would be confusing and it is therefore -% best to remove it. -% \begin{tcl} - global errorInfo - set L [split $errorInfo \n] - set L [lrange $L 0 [expr {[llength $L] - 4}]] - list 1 "Tcl eval error: $res"\ - "Error: $res\nError info:\n[join $L \n]\n" -% \end{tcl} -% When there wasn't an error, a distinction is made between the case -% of an empty string result (very common, e.g.\ from |proc|) and that -% of a nonempty string result. This might seem inconsistent, but in -% practice it looks much better. -% \begin{tcl} - } elseif {[string length $res]} then { - list 0 "Tcl eval OK: $res" "$res\n" - } else { - list 0 "Tcl eval OK." "" - } -} -% \end{tcl} -% \end{proc} -% -% -% -% \subsection{DoScript AppleEvent evaluation} -% -% The |doScriptAE| evaluation method sends a |dosc| AppleEvent to some -% external application, to have the script evaluated that way. Of -% course, this only works if \TclAE\ is available, so this method is -% only defined if that is the case. -% \begin{tcl} -%<atcl7>if {[llength [info commands tclAE::send]]} then { -%<!atcl7>if {![catch {package require tclAE}]} then { -% \end{tcl} -% -% \begin{arrayentry}[eemenu]{evaluate}{doScriptAE} -% The details for the |doScriptAE| method roughly fall into three -% categories: what is the target application, how should the -% extracted lines be combined to a script, and what about a reply? -% \begin{tcl} -set eemenu::evaluate(doScriptAE) [list\ -% \end{tcl} -% \begin{details}{Evaluate} -% \detailitem{targetApp} -% This is the appspec of the target application. -% \begin{tcl} - [eemenu::define_detail Evaluate "Target application"\ - targetApp appspec]\ -% \end{tcl} -% \detailitem{joinString} -% The extracted lines is a list, but the script to send should be -% a string, so they will have to be joined somehow. This item -% offers a choice between some common forms of whitespace. -% \begin{tcl} - [eemenu::define_detail Evaluate "Join lines using"\ - joinString [list menuindex [list Lf Cr CrLf Space]] 1]\ -% \end{tcl} -% \detailitem{prefix} -% This will be prepended to the script sent. It can for example be -% used to add some command that takes care of the result. -% \begin{tcl} - [eemenu::define_detail Evaluate "Prefix" prefix var]\ -% \end{tcl} -% \detailitem{suffix} -% This will be appended to the script sent. -% \begin{tcl} - [eemenu::define_detail Evaluate "Suffix" suffix var]\ -% \end{tcl} -% \detailitem{replyQ} -% This flag controls whether the method should request a reply to -% the AE sent. -% \begin{tcl} - [eemenu::define_detail Evaluate "Wait for reply" replyQ flag]] -% \end{tcl} -% \end{details} -% \end{arrayentry} -% \begin{tcl} -namespace eval eemenu::doScriptAE {} -% \end{tcl} -% \setnamespace{eemenu::doScriptAE} -% -% -% \begin{arrayvar}{A} -% The |doScriptAE| method keeps its detail settings, and some derived -% quantities, in the |A| array. Those are all the global variables it -% has. -% \end{arrayvar} -% -% -% \begin{proc}{begin} -% The main task of this |begin| procedure is to make sure that the -% target application is running. -% \begin{tcl} -proc eemenu::doScriptAE::begin {details source} { - upvar #0 eemenu::doScriptAE::A A - array set A {prefix {} suffix {} joinString 1 targetApp {} replyQ 0} - array set A $details -% \end{tcl} -% The |targetApp| is either a quoted application signature or a full -% path name. Exactly what will have to be done gets affected by this. -% \begin{tcl} - if {[regexp {'(....)'} $A(targetApp) foo sig]} then { - set err [catch {app::ensureRunning $sig} passing] - if {$err == 1} then {set permanent $passing} else { - set permanent "" - set A(app) $A(targetApp) - } - } else { - set tail [file tail $A(targetApp)] -%<*atcl7> - if {[info tclversion]<8.0} then { - set running\ - [regexp "\{\"[quote::Regfind $tail]\" \"" [processes]] - } else { -%</atcl7> - set running 0 - foreach pr [processes] { - if {![string compare $tail [lindex $pr 0]]} then { - set running 1 - break - } - } -%<atcl7> } - set err 0 - set permanent "" - set A(app) $tail - if {$running} then { - set passing "App is running." - } elseif {![catch {launch $A(targetApp)} passing]} then { - set passing "Launched '$A(targetApp)'" - } else { - set err 1 - if {![file exists $A(targetApp)]} then { - set passing "File '$A(targetApp)' not found." - } - set permanent $passing - unset A(app) - } - } -% \end{tcl} -% The |joinString| is also decoded. -% \begin{tcl} - set A(joinString) [lindex [list \n \r \r\n " "] $A(joinString)] - return [list $err $passing $permanent] -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{item} -% The |item| procedure is mainly about formatting data on its way -% back and forth. -% \begin{tcl} -proc eemenu::doScriptAE::item {lines} { - upvar #0 eemenu::doScriptAE::A A - set script "$A(prefix)[join $lines $A(joinString)]$A(suffix)" - if {$A(replyQ)} then { - if {[catch {tclAE::build::resultData -t 30000 $A(app) misc dosc\ - ---- [tclAE::build::TEXT $script]} res]} then { - list 1 "Error: $res" "Error: $res\n" - } elseif {[string length $res]} then { - list 0 $res "$res\n" - } else { - list 0 "Eval OK." "" - } - } else { - tclAE::send $A(app) misc dosc ---- [tclAE::build::TEXT $script] - list 0 "Sent [llength $lines] lines." "" - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{end} -% The |end| procedure does nothing -% \begin{tcl} -proc eemenu::doScriptAE::end {} {list 0 "" ""} -% \end{tcl} -% \end{proc} -% -% This ends the |if| begun at the top of this subsection. -% \begin{tcl} -} -% \end{tcl} -% -% -% \subsection{\texttt{send} evaluation} -% -% The \texttt{send} command can be used to communicate with other Tk -% applications via an X-windows server. This is a bit restrictive, but -% it is anyway what \AlphaTk\ uses for remote execution of \Tcllogo\ -% code, so I suppose it is what we've got. Right now this method is -% defined whenever the |send| command exists, but it is not uncommon -% that the definition of |send| merely provides communication between -% different interpreters in the same application. -% \begin{tcl} -if {[llength [info commands send]] && [info tclversion]>=8.0} then { -% \end{tcl} -% -% \begin{arrayentry}[eemenu]{evaluate}{tkSend} -% Many details for the |doScriptAE| method have natural counterparts -% for the |tkSend| method, the main difference lies in the -% identification of the target. Whereas \TclAE\ uses static -% information (creator code or file name) to identify the target, the -% name used by the |send| command is in principle dynamic. The -% relevant identifier may change between different times that an -% \textsf{EE~menu} command is used. This is handled by providing a -% fallback for unknown targets. -% \begin{tcl} -set eemenu::evaluate(tkSend) [list\ -% \end{tcl} -% \begin{details}{Evaluate} -% \detailitem{target} -% This is a string that identifies the target. -% \begin{tcl} - [eemenu::define_detail Evaluate "Target" target var]\ -% \end{tcl} -% \detailitem{aliasing} -% This detail controls how the |tkSend| method should behave when -% |begin| is called but the specified target isn't available. -% ``Ask each time'' means present the user with a list of available -% targets each time |begin| is called, and use what the user -% selected there. ``Ask once'' is similar, but the choice will be -% remembered as an \emph{alias} for the specified target (until -% \Alpha\ is quited or the alias target no longer is available). -% ``Fail'' means fail immediately. -% \begin{tcl} - [eemenu::define_detail Evaluate "Alias behaviour"\ - aliasing [list menu [list "Ask once" "Ask each time" "Fail"]]\ - "Ask once" "The thing to do when the target is unavailable."]\ -% \end{tcl} -% \detailitem{joinString} -% The extracted lines is a list, but the script to send should be -% a string, so they will have to be joined somehow. This item -% offers a choice between some common forms of whitespace. -% \begin{tcl} - [eemenu::define_detail Evaluate "Join lines using"\ - joinString [list menuindex [list Lf Cr CrLf Space]] 0]\ -% \end{tcl} -% \detailitem{prefix} -% This will be prepended to the script sent. It can for example be -% used to add some command that takes care of the result. -% \begin{tcl} - [eemenu::define_detail Evaluate "Prefix" prefix var]\ -% \end{tcl} -% \detailitem{suffix} -% This will be appended to the script sent. -% \begin{tcl} - [eemenu::define_detail Evaluate "Suffix" suffix var]\ -% \end{tcl} -% \detailitem{replyQ} -% This flag controls whether the method should wait for the -% remote shell to return a result. -% \begin{tcl} - [eemenu::define_detail Evaluate "Wait for reply" replyQ flag 1]] -% \end{tcl} -% \end{details} -% \end{arrayentry} -% \begin{tcl} -namespace eval eemenu::tkSend {} -% \end{tcl} -% \setnamespace{eemenu::tkSend} -% -% \begin{arrayvar}{alias} -% The |alias| array is used to keep track of which targets are treated -% as aliases for other targets. The index is a value of the -% \texttt{target} detail, the entry value is what it should be -% replaced by. -% \end{arrayvar} -% -% \begin{variable}{last_target} -% The |last_target| variable contains the name of the most recently -% selected target. This is so that the relevant |listpick| dialog -% can ``remember'' the user's preference in this respect. -% \begin{tcl} -set eemenu::tkSend::last_target {} -% \end{tcl} -% \end{variable} -% -% \begin{arrayvar}{A} -% The |tkSend| method keeps its detail settings, and some derived -% quantities, in the |A| array for convenience of access. -% \end{arrayvar} -% -% -% \begin{proc}{begin} -% The main task of this |begin| procedure is to verify that the target -% is available. -% \begin{tcl} -proc eemenu::tkSend::begin {details source} { - eemenu::multiupvar A alias last_target - array set A {prefix {} suffix {} joinString 1 target {} replyQ 1\ - aliasing "Ask once"} - array set A $details -% \end{tcl} -% The treatment of aliases depend on the |aliasing| setting. If it is -% \texttt{Ask once} then an alias will be used even if a target with -% the given name is available. The rationale for this is that the user -% has specified that the commands should be sent to that application. -% \begin{tcl} - set T [lsort -dictionary [winfo interps]] - switch -- $A(aliasing) "Ask each time" { - if {[lsearch -exact $T $A(target)]>=0} then { - set target $A(target) - } - } "Fail" { - if {[lsearch -exact $T $A(target)]>=0} then { - set target $A(target) - } else { - set passing "Target '$A(target)' unavailable." - return [list 1 $passing $passing] - } - } default { - set target $A(target) - if {[info exists alias($target)]} then { - set target $alias($target) - } - if {[lsearch -exact $T $target]<0} then {unset target} - } -% \end{tcl} -% If the local |target| variable is not set at this point then it is -% time to ask the user. -% \begin{tcl} - if {![info exists target]} then { - if {[catch {listpick -p "Target '$A(target)' unavailable.\ - Please pick a new one." -L [list $last_target]\ - [linsert $T end "------------------" "Launch new shell"]}\ - target]} then { - return [list 1 "Canceled" ""] - } - switch -exact -- $target\ - "------------------" - "Launch new shell" { - set before [clock seconds] - app::launchElseTryThese [uplevel #0 {set tclshSigs}] tclshSig\ - {Please locate the remote Tcl application} - while {![string compare $T\ - [lsort -dictionary [winfo interps]]] &&\ - [clock seconds] - $before < 60} {update} - set T2 [lsort -dictionary [winfo interps]] - if {![string compare $T $T2]} then { - return [list 1 {Timed out; no new shell started within\ - 60 seconds.} ""] - } - foreach target $T2 t $T { - if {[string compare $target $t]} then {break} - } - set passing "Launched new shell '$target'." - } default { - set passing "Sending code to '$target'." - } -% \end{tcl} -% The last |foreach| above locates the first |target| in |$T2| which -% is not in |$T|. This |foreach| is the reason this code requires -% \Tcllogo\,8. -% -% Now the target should be stored in the necessary variables. -% \begin{tcl} - set last_target $target - if {![string compare $A(aliasing) "Ask once"]} then { - set alias($A(target)) $target - } - } else { - set passing "Sending code to '$target'." - } - set A(target) $target -% \end{tcl} -% The |joinString| is also decoded. -% \begin{tcl} - set A(joinString) [lindex [list \n \r \r\n " "] $A(joinString)] - return [list 0 $passing ""] -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{item} -% The |item| procedure is mainly about formatting data on its way -% back and forth. -% \begin{tcl} -proc eemenu::tkSend::item {lines} { - upvar #0 eemenu::tkSend::A A - set script "$A(prefix)[join $lines $A(joinString)]$A(suffix)" - if {$A(replyQ)} then { - if {[catch {send $A(target) $script} res]} then { - list 1 "Error: $res" "Error: $res\n" - } elseif {[string length $res]} then { - list 0 "Eval OK: $res" "$res\n" - } else { - list 0 "Eval OK." "" - } - } else { - send -async $A(target) $script - list 0 "Sent [llength $lines] lines." "" - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{end} -% The |end| procedure does nothing -% \begin{tcl} -proc eemenu::tkSend::end {} {list 0 "" ""} -% \end{tcl} -% \end{proc} -% -% This ends the |if| begun at the top of this subsection. -% \begin{tcl} -} -% \end{tcl} -% -% \subsubsection*{Test code} -% -% The code below fakes definitions of |send| and |winfo interps| using -% \Tcllogo\AE\ and |processes| for the purpose of testing the above code. -% \begin{tcl} -%<*sendtest> -proc send {target cmd args} { - set sync 1 - if {![string compare $target -async]} then { - set sync 0 - set target $cmd - set cmd [lindex $args 0] - } - set cmd [tclAE::build::TEXT $cmd] - if {$sync} then { - tclAE::build::resultData -t 30000 $target misc dosc ---- $cmd - } else { - tclAE::send $target misc dosc ---- $cmd - } -} -proc winfo {subcmd args} { - if {[string compare $subcmd "interps"]} then { - error "Unimplemented winfo subcommand: $subcmd" - } - set res [list] - global tclshSigs - foreach pr [processes] { - if {[lsearch -exact $tclshSigs [lindex $pr 1]]>=0} then { - lappend res [file tail [lindex $pr 0]] - } - } - return $res -} -%</sendtest> -% \end{tcl} -% -% -% \subsection{\texttt{dde} evaluation} -% -% Dynamic Data Exchange (\texttt{dde}) is, as I understand it, the -% Windoze equivalent of AppleEvents, although the events sent have much -% less structure. The machinery needed here is quite similar to that -% for \texttt{send} evaluation, but there are a few extra details that -% can be set. -% \changes{v\,0.1.1}{2002/07/21}{Renamed the \textsf{Dde} method to -% \textsf{Windoze DDE}. (LH)} -% -% \begin{tcl} -if {[llength [info commands dde]] && [info tclversion]>=8.0} then { -% \end{tcl} -% -% \begin{arrayentry}[eemenu]{evaluate}{windozeDDE} -% The details for the |windozeDDE| method constitute a superset of those for -% the |tkSend| method. -% \begin{tcl} -set eemenu::evaluate(windozeDDE) [list\ -% \end{tcl} -% \begin{details}{Evaluate} -% \detailitem{service} -% This is a string that specifies the service to use. -% \begin{tcl} - [eemenu::define_detail Evaluate "Service" service var "TclEval"]\ -% \end{tcl} -% \detailitem{target} -% This is a string that identifies the target application, or as -% it appears to be called, the ``topic''. -% \begin{tcl} - [eemenu::define_detail Evaluate "Target" target var]\ -% \end{tcl} -% \detailitem{aliasing} -% This detail controls how the |windozeDDE| method should behave when -% |begin| is called but the specified target isn't available. -% ``Ask each time'' means present the user with a list of available -% targets each time |begin| is called, and use what the user -% selected there. ``Ask once'' is similar, but the choice will be -% remembered as an \emph{alias} for the specified target (until -% \Alpha\ is quited or the alias target no longer is available). -% ``Fail'' means fail immediately. -% \begin{tcl} - [eemenu::define_detail Evaluate "Alias behaviour"\ - aliasing [list menu [list "Ask once" "Ask each time" "Fail"]]\ - "Ask once" "The thing to do when the target is unavailable."]\ -% \end{tcl} -% \detailitem{launchCmd} -% This is a \Tcllogo\ command which, when executed by \Alpha, -% should launch an application that provides a new target for -% the given service. The command is evaluated at a global level. -% If it is an empty string, then no option for launching will be -% presented in the target selection dialog. -% \begin{tcl} - [eemenu::define_detail Evaluate "Launch command" launchCmd var2]\ -% \end{tcl} -% \detailitem{joinString} -% The extracted lines is a list, but the script to send should be -% a string, so they will have to be joined somehow. This item -% offers a choice between some common forms of whitespace. -% \begin{tcl} - [eemenu::define_detail Evaluate "Join lines using"\ - joinString [list menuindex [list Lf Cr CrLf Space]] 2]\ -% \end{tcl} -% \detailitem{prefix} -% This will be prepended to the script sent. It can for example be -% used to add some command that takes care of the result. -% \begin{tcl} - [eemenu::define_detail Evaluate "Prefix" prefix var]\ -% \end{tcl} -% \detailitem{suffix} -% This will be appended to the script sent. -% \begin{tcl} - [eemenu::define_detail Evaluate "Suffix" suffix var]\ -% \end{tcl} -% \detailitem{request} -% This is the name of the item to request as result from the -% evaluation. If it is an empty string then no request is made. -% \begin{tcl} - [eemenu::define_detail Evaluate "Requested data" request var]] -% \end{tcl} -% \end{details} -% \end{arrayentry} -% \begin{tcl} -namespace eval eemenu::windozeDDE {} -% \end{tcl} -% \setnamespace{eemenu::windozeDDE} -% -% \begin{arrayvar}{alias} -% The |alias| array is used to keep track of which targets are treated -% as aliases for other targets. The index is a value of the -% \texttt{target} detail, the entry value is what it should be -% replaced by. -% \end{arrayvar} -% -% \begin{variable}{last_target} -% The |last_target| variable contains the name of the most recently -% selected target. This is so that the relevant |listpick| dialog -% can ``remember'' the user's preference in this respect. -% \begin{tcl} -set eemenu::windozeDDE::last_target {} -% \end{tcl} -% \end{variable} -% -% \begin{arrayvar}{A} -% The |windozeDDE| method keeps its detail settings, and some derived -% quantities, in the |A| array for convenience of access. -% \end{arrayvar} -% -% -% \begin{proc}{begin} -% The main task of this |begin| procedure is to verify that the target -% is available. -% \begin{tcl} -proc eemenu::windozeDDE::begin {details source} { - eemenu::multiupvar A alias last_target - array set A {service {} target {} aliasing "Ask once" launchCmd {}\ - prefix {} suffix {} joinString 2 request {}} - array set A $details - if {![string length $A(service)]} then { - return [list 1 "No service has been specified." ""] - } -% \end{tcl} -% The treatment of aliases depend on the |aliasing| setting. If it is -% \texttt{Ask once} then an alias will be used even if a target with -% the given name is available. The rationale for this is that the user -% has specified that the commands should be sent to that application. -% \begin{tcl} - set T [list] - foreach st [dde services $A(service) {}] {lappend T [lindex $st 1]} - set T [lsort -dictionary $T] - switch -- $A(aliasing) "Ask each time" { - if {[lsearch -exact $T $A(target)]>=0} then { - set target $A(target) - } - } "Fail" { - if {[lsearch -exact $T $A(target)]>=0} then { - set target $A(target) - } else { - set passing "Target '$A(target)' unavailable." - return [list 1 $passing $passing] - } - } default { - set target $A(target) - if {[info exists alias($target)]} then { - set target $alias($target) - } - if {[lsearch -exact $T $target]<0} then {unset target} - } -% \end{tcl} -% If the local |target| variable is not set at this point then it is -% time to ask the user. -% \begin{tcl} - if {![info exists target]} then { - set T2 $T - if {[string length $A(launchCmd)]} then { - if {[llength $T2]} then {lappend T2 "------------------"} - lappend T2 "Launch another" - } - if {![llength $T2]} then { - return [list 1 "No '$A(service)' targets are, or could be\ - made, available." ""] - } - if {[catch {listpick -p "Target '$A(target)' unavailable.\ - Please pick a new one." -L [list $last_target] $T2}\ - target]} then { - return [list 1 "Canceled" ""] - } - switch -exact -- $target\ - "------------------" - "Launch another" { - set before [clock seconds] - uplevel #0 $A(launchCmd) - set target {} - while {[clock seconds] - $before < 60 &&\ - ![string length $target]} { - foreach st [dde services $A(service) {}] { - if {[lsearch -exact $T [lindex $st 1]]<0} then { - set target [lindex $st 1] - break - } - } - update - } - if {![string length $target]} then { - return [list 1 {Timed out; no new target launched within\ - 60 seconds.} ""] - } - set passing "Launched new shell '$target'." - } default { - set passing "Sending code to '$target'." - } -% \end{tcl} -% The last |foreach| above locates the first |target| in |$T2| which -% is not in |$T|. This |foreach| is the reason this code requires -% \Tcllogo\,8. -% -% Now the target should be stored in the necessary variables. -% \begin{tcl} - set last_target $target - if {![string compare $A(aliasing) "Ask once"]} then { - set alias($A(target)) $target - } - } else { - set passing "Sending code to '$target'." - } - set A(target) $target -% \end{tcl} -% The |joinString| is also decoded. -% \begin{tcl} - set A(joinString) [lindex [list \n \r \r\n " "] $A(joinString)] - return [list 0 $passing ""] -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{item} -% The |item| procedure is mainly about formatting data on its way -% back and forth. -% \begin{tcl} -proc eemenu::windozeDDE::item {lines} { - upvar #0 eemenu::windozeDDE::A A - set script "$A(prefix)[join $lines $A(joinString)]$A(suffix)" - if {[catch {dde execute $A(service) $A(target) $script} res]} then { - list 1 "dde error: $res" "$res\n" - } elseif {![string length $A(request)]} then { - list 0 "Sent [llength $lines] lines." "" - } else { - if {[catch {dde request $A(service) $A(target) $A(request)} res]}\ - then { - list 1 "dde error: $res" "dde error: $res\n" - } elseif {[string length $res]} then { - list 0 $res "$res\n" - } else { - list 0 "Eval OK." "" - } - } -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{end} -% The |end| procedure does nothing -% \begin{tcl} -proc eemenu::windozeDDE::end {} {list 0 "" ""} -% \end{tcl} -% \end{proc} -% -% This ends the |if| begun at the top of this subsection. -% \begin{tcl} -} -% \end{tcl} -% -% \subsubsection*{Test code} -% -% The code below fakes a definition of |dde| using |interp|. -% \begin{tcl} -%<*ddetest> -proc dde {subcmd args} { - switch -- $subcmd servername { - error "dde servername is not implemented." - } execute { - if {[llength $args] != 3} then { - error "Wrong number of arguments for dde execute." - } - if {"TclEval" != [lindex $args 0]} then { - error "Unknown servername: [lindex $args 0]" - } - interp eval [lindex $args 1] [lindex $args 2] - } poke { - if {[llength $args] != 4} then { - error "Wrong number of arguments for dde poke." - } - if {"TclEval" != [lindex $args 0]} then { - error "Unknown servername: [lindex $args 0]" - } - interp eval [lindex $args 1]\ - [list set [lindex $args 2] [lindex $args 3]] - } request { - if {[llength $args] != 3} then { - error "Wrong number of arguments for dde request." - } - if {"TclEval" != [lindex $args 0]} then { - error "Unknown servername: [lindex $args 0]" - } - interp eval [lindex $args 1] [list set [lindex $args 2]] - } services { - if {[llength $args] != 2} then { - error "Wrong number of arguments for dde services." - } - set server [lindex $args 0] - if {[string length $server] && $server != "TclEval"} then { - return "" - } - set topic [lindex $args 1] - if {![string length $topic]} then { - set res [list] - foreach slave [interp slaves] { - lappend res [list TclEval $slave] - } - return $res - } elseif {[interp exists $topic]} then { - return [list [list TclEval $topic]] - } else { - return "" - } - } default { - error "Unimplemented subcommand: $subcmd" - } -} -%</ddetest> -% \end{tcl} -% -% -% \section{Report methods} -% \label{Sec:Report} -% -% The report method takes care of sending output to the user. Like -% extraction and evaluation methods there is one `begin' procedure -% |log_open| and one `end' procedure |log_close| for each method, but -% there are actually two `iterate' procedures. This is because the -% extracted code is logged using |log_code| \emph{before} it is -% evaluated, whereas the result is only known after the code has been -% evaluated and is then logged using |log_result|. -% -% The \describestring[proc][eemenu::\meta{method}]{log_open}|log_open| -% procedure has the syntax -% \begin{quote} -% |eemenu::|\meta{method}|::log_open| \word{details} \word{source} -% \end{quote} -% where the \word{details} is the key--value list of setting details -% and \word{source} is the source window name as returned by the -% extraction method |start| procedure. There is no result from this -% procedure, but if there is something wrong with its argument then it -% may stop the \eemenu\ command by returning with an error. -% -% The reason the \word{source} argument is provided is that some report -% methods might want to make some aspect of their output, such as for -% example a window title or log file name, dependent on the input source. -% Neither the |statusLine| nor the |logWindow| method do this, though. -% -% The \describestring[proc][eemenu::\meta{method}]{log_code}|log_code| -% procedure has the syntax -% \begin{quote} -% |eemenu::|\meta{method}|::log_code| \word{lines} -% \end{quote} -% where \word{lines} is the list of lines that will be sent to the -% evaluation method. The -% \describestring[proc][eemenu::\meta{method}]{log_result}|log_result| -% procedure has the syntax -% \begin{quote} -% |eemenu::|\meta{method}|::log_result| \word{error?} -% \word{passing result} \word{permanent result} -% \end{quote} -% where the \word{error?} is |1| if there was an evaluation error and -% |0| otherwise. The \word{passing result} is a result string that -% describes the current state of the evaluation process; it is meant -% to be replaced by the next \word{passing result} the next time -% |log_result| is called. By constrast the \word{permanent result} is -% meant to be accumulated for each call to |log_result|. Whether a -% report method uses one or the other (or both) depends on which makes -% most sense for the output channels it employs. If the \word{passing -% result} string is empty then it should not replace a previous -% \word{passing result} string. If the \word{permanent} string is -% nonempty then it must end with a newline character. -% -% The \describestring[proc][eemenu::\meta{method}]{log_close}|log_close| -% procedure is responsible for cleaning up after the method, but only -% to the extent that this is necessary. If |log_open| opened a file then -% |log_close| should close it, but if |log_open| merely opened a window -% then |log_close| should most likely not close it since the user will -% want to see what is written in that window. The syntax is simply -% \begin{quote} -% |eemenu::|\meta{method}|::log_close| -% \end{quote} -% and there is no result from the procedure. -% -% -% -% \subsection{Status line reports} -% -% The |statusLine| method shows the \word{passing result}s on the -% status line, but does nothing else. -% -% \setnamespace{eemenu::statusLine} -% \begin{arrayentry}[eemenu]{report}{statusLine} -% There are no details settings for this method. -% \begin{tcl} -namespace eval eemenu::statusLine {} -set eemenu::report(statusLine) [list] -% \end{tcl} -% \end{arrayentry} -% -% \begin{proc}{log_open} -% \begin{proc}{log_close} -% \begin{proc}{log_code} -% \begin{proc}{log_result} -% Only the |log_result| procedure needs to do anything. -% \begin{tcl} -proc eemenu::statusLine::log_open {details source} {} -proc eemenu::statusLine::log_close {} {} -proc eemenu::statusLine::log_code {lines} {} -proc eemenu::statusLine::log_result {was_err passing permanent} { - if {[string length $passing]} then {status::msg $passing} -} -% \end{tcl} -% \end{proc}\end{proc}\end{proc}\end{proc} -% -% -% \subsection{Log window reports} -% -% The |logWindow| method opens a particular window and inserts -% everything that is logged there. -% -% \begin{arrayentry}[eemenu]{report}{logWindow} -% There are three detail settings for |logWindow| reports. -% \begin{tcl} -set eemenu::report(logWindow) [list\ -% \end{tcl} -% \begin{details}{Report} -% \detailitem{winName} -% This is the name of the log window. -% \begin{tcl} - [eemenu::define_detail Report "Window name" winName var "Log"]\ -% \end{tcl} -% \detailitem{winMode} -% This is the mode to use for the log window. -% \begin{tcl} - [eemenu::define_detail Report "Window mode" winMode mode "Text"]\ -% \end{tcl} -% \detailitem{prompt} -% This is a ``prompt'' string that will be put at the beginning of -% each code line. -% \begin{tcl} - [eemenu::define_detail Report "Prompt" prompt var\ - "[text::Ascii 200 1] "]\ -% \end{tcl} -% \detailitem{antiprompt} -% This is a string that will be put at the beginning of each line -% that is not a code line. -% \begin{tcl} - [eemenu::define_detail Report "Antiprompt" antiprompt var ""]] -% \end{tcl} -% \end{details} -% \end{arrayentry} -% \begin{tcl} -namespace eval eemenu::logWindow {} -% \end{tcl} -% \setnamespace{eemenu::logWindow} -% -% \begin{arrayvar}{A} -% The |logWindow| method keeps its detail settings in the |A| -% array. Those are all the global variables it has. -% \end{arrayvar} -% -% \begin{proc}{log_open} -% This procedure opens the log window (if it isn't open already) -% and positions the cursor at the end of the window. This is -% assumed to be at the beginning of a line. -% \begin{tcl} -proc eemenu::logWindow::log_open {details source} { - upvar #0 eemenu::logWindow::A A - array set A {winName {Log window} prompt {} antiprompt {}} - array set A $details - set win $A(winName) - if {[lsearch -exact [winNames] $win] == -1} then { - set call [list new -n $win -shell 1] - if {[mode::exists $A(winMode)]} then {lappend call -m $A(winMode)} - eval $call - } - set t [maxPos -w $win] - select -w $win $t $t -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{log_code} -% The |log_code| procedure inserts the lines at the current position -% in the file. This will be at the end of the file, unless the -% evaluation modifies this. -% \begin{tcl} -proc eemenu::logWindow::log_code {lines} { - upvar #0 eemenu::logWindow::A A - insertText -w $A(winName) "$A(prompt)[join $lines "\n$A(prompt)"]\n" -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{log_result} -% The |log_result| procedure inserts the \word{permanent result} at -% the current position in the file. If the |antiprompt| is -% nonempty then the result is first broken into lines and then -% reassembled, however. It also displays the \word{passing result} on -% the status line (this has to be done last, since |insertText| -% clears the status line). -% \begin{tcl} -proc eemenu::logWindow::log_result {was_err passing permanent} { - if {[string length $permanent]} then { - upvar #0 eemenu::logWindow::A A - if {[string length $A(antiprompt)]} then { - set L [lreplace [split $permanent \n\r] end end] - set permanent "[join $L "\n$A(antiprompt)"]\n" - } - insertText -w $A(winName) "$A(antiprompt)$permanent" - } - if {[string length $passing]} then {status::msg $passing} -} -% \end{tcl} -% \end{proc} -% -% \begin{proc}{log_close} -% This procedure does nothing. -% \begin{tcl} -proc eemenu::logWindow::log_close {} {} -% \end{tcl} -% \end{proc} -% -% -% \section{Default command definitions} -% \label{Sec:DefCmdA} -% -% This section contains some examples of \eemenu\ commands and -% it also provides defaults for the |cmdA| array. -% -% \setnamespace{eemenu} -% -% \begin{arrayvar}{cmdA} -% If this array is already set then there is no need to source the -% rest of the file. -% \begin{tcl} -if {[info exists eemenu::cmdA]} then {return} -% \end{tcl} -% \end{arrayvar} -% -% -% \begin{arrayentry}{cmdA}{dtx -> internal Tcl} -% This is the command that corresponds most closely to that provided -% by the old \textsf{dtxload} package. -% \begin{tcl} -set {eemenu::cmdA(dtx -> internal Tcl)} [list\ -% \end{tcl} -% By default the command is active and bound to \textsf{Cmd--L} in -% \TeX\ mode, but it is not put in the menu. -% \begin{tcl} - active 1 binding /L<O mode TeX\ - in_menu 0\ -% \end{tcl} -% The extraction method is docstripping. Only code in \texttt{.dtx} -% files that is furthermore in a \texttt{tcl} or \texttt{tcl*} -% environment is kept. Again, these are the defaults in the -% \textsf{dtxload} package. -% \begin{tcl} - extractor Docstrip extract_extra [list\ - filePatL *.dtx sourceEnvsL {tcl tcl*} lookAtEnvs 1\ - ]\ -% \end{tcl} -% The command uses |info complete| to test if it has got a complete -% command, sends the extracted code to \Alpha's internal \Tcllogo\ -% interpreter, and logs the result on the status line. -% \begin{tcl} - complete "Tcl Info Complete" complete_extra {}\ -% - evaluator "Internal Tcl" eval_extra {}\ -% - reporter "Status Line" report_extra {}\ -% -] -% \end{tcl} -% Of course, this default setting needs to be saved. -% \begin{tcl} -prefs::modified {eemenu::cmdA(dtx -> internal Tcl)} -% \end{tcl} -% \end{arrayentry} -% -% -% \begin{arrayentry}{cmdA}{dtx -> remote Tcl} -% This is a command that I have lately found to be increasingly useful. -% The functionality was provided in the \textsf{dtxload} package, but -% it was always slightly awkward as it was not a distinct command. -% Instead the |evaluateRemotely| variable was used as a selector -% between this and the previous command. -% -% Since these two commands are anyway quite similar, I'll copy -% settings from the above, only changing those that are different. -% \begin{tcl} -catch {unset A} -array set A [set {eemenu::cmdA(dtx -> internal Tcl)}] -% \end{tcl} -% Since keys combinations are sort of in short supply, this command -% is by default inactive but has the same binding and mode as its -% \textsf{internal~Tcl} counterpart. This means that if one of these -% commands is activated then the other is automatically deactivated -% and so it is anyway easy to switch between them. I also put this -% remote \Tcllogo\ command in the menu. -% \begin{tcl} -set A(active) 0 -set A(in_menu) 1 -% \end{tcl} -% -% Communication with remote interpreters is a messy business, due to -% the many technical details one has do deal with. It is also very -% platform-dependent. The Mac\,OS settings are however not too -% complicated, much thanks to \TclAE. -% \changes{v\,0.3}{2003/06/01}{Corrected condition used for selecting -% remote evaluation method. (LH)} -% \begin{tcl} -if {[info exists eemenu::evaluate(doScriptAE)]} then { - set A(evaluator) "Do Script AE" - set A(eval_extra)\ - [list targetApp '${tclshSig}' joinString 0 replyQ 1] -} \ -% \end{tcl} -% -% The Windoze settings are the most complicated. One reason for this -% is that |dde execute| does not return the result of the script, so -% that a separate call is needed for this. -% \begin{tcl} -elseif {[info exists eemenu::evaluate(windozeDDE)]} then { - set A(evaluator) "Windoze DDE" - set A(eval_extra) [list\ -% - service TclEval target Tcl_1 launchCmd\ - {exec $tclshSig [file join $HOME Tools winRemoteShell.tcl] &}\ -% - joinString 0 prefix "catch \{" suffix "\} alpha_result"\ - request alpha_result] -} \ -% \end{tcl} -% -% Finally, there are the settings for |send|, which are used on all -% other platforms. -% \begin{tcl} -else { - set A(evaluator) "Tk Send" - set A(eval_extra) [list target wish joinString 0 replyQ 1] -} -% \end{tcl} -% Then all that remains is to store the settings into the |cmdA| array. -% \begin{tcl} -set {eemenu::cmdA(dtx -> remote Tcl)} [array get A] -prefs::modified {eemenu::cmdA(dtx -> remote Tcl)} -unset A -% \end{tcl} -% \end{arrayentry} -% -% \begin{arrayentry}{cmdA}{Tcl example in AIDA} -% AIDA probably isn't that well known, but in brief it is an -% experimental source format for \Alpha\ documentation, which can -% be converted to plain text, \LaTeX, HTML, and some other formats too. -% Verbatim text lines (as needed for code examples) can of course be -% included expressed in AIDA; the required markup is mainly that each -% such line begins with the two characters \verb"(|". Such code can -% easily be extracted using the regexp extractor. -% -% This code is no longer included, since AIDA isn't much used anymore. -% \begin{tcl} -%<*aidacode> -set {eemenu::cmdA(Tcl example in AIDA)} [list\ -% - extractor Regexp extract_extra [list\ -% \end{tcl} -% The filter should get the lines matching the expression, i.e., it -% should work in \texttt{grep} mode, and the characters that are -% matched should be removed. -% \begin{tcl} - filter_mode grep filterRE {^\(\|} searchRE {^\(\|} replaceRE {}]\ -% \end{tcl} -% Evaluation is internally in \Alpha, and the completion test can use -% |info complete|. -% \begin{tcl} - complete "Tcl Info Complete" complete_extra {}\ -% - evaluator "Internal Tcl" eval_extra {}\ -% \end{tcl} -% Then there's the matter of how to report the result. Since that -% hasn't been used yet, it seems a good idea to try to use a log -% window here. -% \begin{tcl} - reporter "Log Window" report_extra {winName {AIDA example log}\ - winMode Tcl prompt {% } antiprompt {}}\ -% \end{tcl} -% Finally there's the matter of the binding and the menu. There isn't -% anything new here, except that the binding is only made active if -% \texttt{AIDA} mode is installed (since modes not installed will -% sometimes be interpreted as |<none>|, i.e., global). -% \begin{tcl} - active [mode::exists AIDA] binding /L<O mode AIDA in_menu 1] -prefs::modified {eemenu::cmdA(Tcl example in AIDA)} -%</aidacode> -% \end{tcl} -% \end{arrayentry} -% -% \begin{arrayentry}{cmdA}{Tcl Wiki} -% When editing a page on the \Tcllogo'ers Wiki~\cite{TclWiki} or the -% \AlphaTcl\ Wiki~\cite{AlphaTclWiki}, one occasionally finds the need -% to test some piece of \Tcllogo\ code on that page. This is down to a -% single keypress with the following command, that extracts lines of -% verbatim text from a Wiki page and feeds them to the internal -% interpreter. -% -% The syntax of verbatim lines on the \Tcllogo'ers Wiki is -% basically ``any line that starts with a space'', but unfortunately -% there are a few exceptions. The equivalents of \LaTeX\ \verb|\item|s -% for \texttt{itemize} or \texttt{enumerate} are coded as lines that -% begin with three spaces, a \texttt{*} or \meta{digit}\texttt{.} -% respectively, and another space. The equivalents of \LaTeX\ -% \verb|\item|s for \texttt{description} are coded as lines that -% begin with \emph{at least} three spaces, some other characters, a -% colon, and another three spaces (exactly). It is possible to write a -% regular expression to filter out such lines. -% \begin{tcl} -set {eemenu::cmdA(Tcl Wiki)} [list\ -% - extractor Regexp extract_extra [list\ -% \end{tcl} -% The filter works in \texttt{anti-grep} mode, and has to filter out -% four different types of non-code lines. There is however no need -% for further substitutions on the code lines. -% \begin{tcl} - filter_mode anti-grep searchRE {} replaceRE {}\ - filterRE {^[^ ]|^ (\*|[0-9]\.) |^ .+: [^ ]} ]\ -% \end{tcl} -% Evaluation is internally in \Alpha, and the completion test can use -% |info complete|. -% \begin{tcl} - complete "Tcl Info Complete" complete_extra {}\ -% - evaluator "Internal Tcl" eval_extra {}\ -% \end{tcl} -% Then there's the matter of how to report the result. Since that -% hasn't been used yet, it seems a good idea to try to use a log -% window here. -% \begin{tcl} - reporter "Log Window" report_extra {winName {Wiki code log}\ - winMode Tcl prompt {% } antiprompt {}}\ -% \end{tcl} -% Finally there's the matter of the binding and the menu. There isn't -% anything new here, except that the binding is only made active if -% \texttt{Wiki} mode is installed (since modes not installed will -% sometimes be interpreted as |<none>|, i.e., global). -% \begin{tcl} - mode Wiki active [mode::exists Wiki] binding /L<O in_menu 1] -prefs::modified {eemenu::cmdA(Tcl Wiki)} -% \end{tcl} -% \end{arrayentry} -% -% Finally, let's try something which isn't \Tcllogo. -% -% \begin{arrayentry}{cmdA}{Mathematica} -% It is a fairly small modification to make a command which sends -% DoScript AEs to Mathematica instead of Wish. There's probably a way -% to do this using |dde| too, but I don't know what that could be. -% -% Since Mathematica code presumably concerns rather mathematical -% problems, the comments to the code is likely to contain fairly -% advanced mathematical formulae. This makes the \texttt{.dtx} -% format an interesting choice for source format, and hence I choose -% to use docstripping as extraction method. As there is no special -% environment for Mathematica code, the source environments are the -% generic \texttt{macrocode} and \texttt{macrocode*}. -% \begin{tcl} -set eemenu::cmdA(Mathematica) [list\ -% - extractor Docstrip extract_extra [list\ - filePatL *.dtx sourceEnvsL {macrocode macrocode*} lookAtEnvs 1\ - ]\ -% \end{tcl} -% The extracted code is sent in a DoScript AppleEvent to the -% Mathematica kernel. Unfortunately the kernel doesn't seem to -% produce any result, so we'll have to leave it at that. Since there -% is no convenient way of testing whether something is a complete -% command in this case, all code from the entire selection is sent in -% one event. -% \begin{tcl} - evaluator "Do Script AE" eval_extra\ - [list targetApp 'Math' joinString 1 replyQ 0]\ -% - complete "Entire Selection" complete_extra {}\ -% - reporter "Status Line" report_extra {}\ -% \end{tcl} -% The binding and menu settings are the same as for the remote -% \Tcllogo\ command. -% \begin{tcl} - active 0 binding /L<O mode TeX in_menu 0] -% \end{tcl} -% Of course, this default setting needs to be saved. -% \begin{tcl} -prefs::modified {eemenu::cmdA(Mathematica)} -% \end{tcl} -% \end{arrayentry} -% -% -% \begin{thebibliography}{9} -% \bibitem{TclWiki} -% The \Tcllogo'ers Wiki, -% \href{http://purl.org/tcl/wiki/}{\textsc{http:}/\slash -% \texttt{purl.org}\slash \texttt{tcl}\slash \texttt{wiki}/} -% \bibitem{AlphaTclWiki} -% \AlphaTcl\ Wiki, \href{http://alphatcl.sourceforge.net/wikit/} -% {\textsc{http:}/\slash \texttt{alphatcl.sourceforge.net}\slash -% \texttt{wikit}/} -% \end{thebibliography} -% -% -\endinput
\ No newline at end of file diff --git a/Master/texmf-dist/source/latex/tcldoc/tools/eemenu.ins b/Master/texmf-dist/source/latex/tcldoc/tools/eemenu.ins deleted file mode 100644 index 6b28dcfde27..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/tools/eemenu.ins +++ /dev/null @@ -1,66 +0,0 @@ -% eemenu.ins --- DOCSTRIP installation script for eemenu. -\input docstrip - -% Redefine the \MetaPrefix; it should be something which starts a -% until-end-of-line comment: -\edef\MetaPrefix{\string#\string#} - - -% Redefine the file preamble and postamble; this is necessary because -% otherwise the old \metaPrefix is inserted at the beginning of these -% lines. -\preamble - -This file may be distributed and/or modified under the conditions -of the LaTeX Project Public License, either version 1.2 of this -license or (at your option) any later version. The latest version -of this license is in - http://www.latex-project.org/lppl.txt -and version 1.2 or later is part of all distributions of LaTeX -version 1999/12/01 or later. - -This file may only be distributed together with a copy of the source -file from which it was generated. You may distribute that source file -without this generated file. - -You may alternatively distribute, use, and modify this files under -the conditions of a BSD-style license. In so doing, you should -however note that -************************************** -* This Source is not the True Source * -************************************** -the true source is the file from which this one was generated. - -\endpreamble - -\postamble -\endpostamble - -% Add a (auto-install) line at the top of the preamble, so that -% Alpha will auto-install it. -\edef\defaultpreamble{% - \MetaPrefix\space (auto-install)^^J% - \defaultpreamble -} - -% Actually make eemenu.tcl: -\generate{ - \file{eemenu.tcl}{\from{eemenu.dtx}{pkg}} - \file{eefor7menu.tcl}{\from{eemenu.dtx}{pkg,atcl7,dialogspatch}} -} - - -\Msg{} -\Msg{*********************************************} -\Msg{*} -\Msg{* To complete installation, have Alpha open} -\Msg{* the file eemenu.tcl somewhere outside the} -\Msg{* Alpha folder hierarchy. You may also have} -\Msg{* to rebuild Alpha's Tcl and Package indices} -\Msg{* (Alpha normally does this automatically).} -\Msg{*} -\Msg{*********************************************} -\Msg{} - - -\end diff --git a/Master/texmf-dist/source/latex/tcldoc/tools/sourcedtx.dtx b/Master/texmf-dist/source/latex/tcldoc/tools/sourcedtx.dtx deleted file mode 100644 index 3b024427ab6..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/tools/sourcedtx.dtx +++ /dev/null @@ -1,234 +0,0 @@ -% -% \iffalse -%<*driver> -\documentclass{tclldoc} -\begin{document} -\DocInput{sourcedtx.dtx} -\end{document} -%</driver> -% \fi -% -% \title{The \textsf{sourcedtx} package} -% \author{Lars Hellstr\"om} -% \date{18 July 2003} -% \maketitle -% -% \begin{abstract} -% The \textsf{sourcedtx} package provides a \Tcllogo\ command -% |dtx::source| that makes it possible to |source| \Tcllogo\ code -% from a \textsf{doc}-style \texttt{.dtx} file without docstripping -% it first. -% \end{abstract} -% -% -% \begin{tcl} -%<*pkg> -namespace eval dtx {} -% \end{tcl} -% \setnamespace{dtx} -% -% \begin{proc}{strip_string} -% The |strip_string| procedure does the actual docstripping for -% |source_dtx|. The syntax is -% \begin{quote} -% |dtx::strip_string| \word{text} \word{option list} -% \word{meta prefix}\regopt\ \word{interaction}\regopt -% \end{quote} -% where \word{text} is the string to docstrip and \word{option list} -% is the list of options to use. The \word{meta prefix} (by default -% two percent signs) is the string to use for the \textsc{docstrip} -% parameter \verb|\MetaPrefix|. The \word{interation} (by default 1) -% is a flag for the ``interaction'' level to use. |0| means error -% messages are simply written to |stderr|, whereas |1| means an error -% will be raised. (It is possible that \word{interaction} will be -% extended to a ``flag word'' where each bit controls some aspect of -% the interaction.) -% -% When errors are raised, the |errorCode| is set to a list with the -% format -% \begin{quote} -% |DOCSTRIP| \word{situation} \word{lineno} -% \end{quote} -% where \word{lineno} is the line number (starting at one) of the line -% where the error was detected. The \word{situation}s are described -% below, at the positions in the code where they can occur. -% -% \begin{tcl} -proc dtx::strip_string {text options {metaprefix %%} {interaction 1}} { -% \end{tcl} -% The |O| array has entires for precisely the specified options, so -% that an opion can be tested using |info exists|. -% \begin{tcl} - foreach option $options {set O($option) ""} -% \end{tcl} -% |stripped| is where the text that passes docstripping is collected. -% \begin{tcl} - set stripped "" -% \end{tcl} -% |block_stack| is the list of modules inside which the current line -% lies. |offlevel| is the number of modules that must be exited -% before code lines should once again be included. |verbatim| is a -% flag for whether verbatim mode is in force. -% \begin{tcl} - set block_stack [list] - set offlevel 0 - set verbatim 0 -% \end{tcl} -% |lineno| is the input line number counter, for use in error -% messages. -% \begin{tcl} - set lineno 1 -% \end{tcl} -% Here starts the main loop over lines in the \word{text}. It -% constitutes the majority of the procedure and is split in two -% parts. The smaller part handles lines in verbatim mode (unusual), -% the large part handles lines in normal mode (with comment lines, -% code lines, guard lines, and so on). -% \begin{tcl} - foreach line [split $text \n] { - if {$verbatim} then { - if {$line eq $endverbline} then { - set verbatim 0 - } elseif {!$offlevel} then { - append stripped $line \n - } - } else { - switch -glob -- $line %%* { - if {!$offlevel} then { - append stripped $metaprefix\ - [string range $line 2 end] \n - } - } %<<* { - set endverbline "%[string range $line 3 end]" - set verbatim 1 - } %<* { - if {[regexp -- {^%<([*/+-]?)([^>]*)>(.*)$} $line ""\ - modifier expression line]} then { -% \end{tcl} -% There is a well-formed guard line. First the expression is -% evaluated, by converting it to an |expr| expression. -% \begin{tcl} - regsub -all -- {\\|\{|\}|\$|\[|\]| |;} $expression\ - {\\&} E - regsub -all -- {,} $E {|} E - regsub -all -- {[^()|&!]+} $E {[info exists O(&)]} E - set val [expr $E] - switch -exact -- $modifier * { - lappend block_stack $expression - if {$offlevel || !$val} then {incr offlevel} - } / { - if {![llength $block_stack]} then { -% \end{tcl} -% In this case there was no open block for this guard to end. That -% is a \describestring[error situation]{SPURIOUS}|SPURIOUS| -% \word{situation}. -% \begin{tcl} - if {$interaction} then { - error "Spurious end block </$expression>\ - ignored." ""\ - [list DOCSTRIP SPURIOUS $lineno] - } else { - puts stderr "docstrip: Spurious end\ - block </$expression> ignored on line\ - $lineno." - } - } else { - if {[string compare $expression\ - [lindex $block_stack end]]} then { -% \end{tcl} -% In this case the expression of the block being closed does not match -% the expression on the block on top of the stack. That is a -% \describestring[error situation]{MISMATCH}|MISMATCH| -% \word{situation}. \textsc{docstrip} by default raises an error and -% recovers by treating this situation as a typo. -% \begin{tcl} - if {$interaction} then { - error "Found </$expression> instead of\ - </[lindex $block_stack end]>." ""\ - [list DOCSTRIP MISMATCH $lineno] - } - puts stderr "docstrip:\ - Found </$expression> instead of\ - </[lindex $block_stack end]> on line\ - $lineno." - } -% \end{tcl} -% All that error processing makes it easy to lose track, but the -% following two lines are what does the real work for an end of block -% guard: pop a block off the stack and decrement the |offlevel|. -% \begin{tcl} - if {$offlevel} then {incr offlevel -1} - set block_stack [lreplace $block_stack end end] - } - } - { - if {!$offlevel && !$val} then { - append stripped $line \n - } - } default { - if {!$offlevel && $val} then { - append stripped $line \n - } - } - } else { -% \end{tcl} -% In this case the line looks like a guard line, but there is no |>| -% terminating the guard expression. This is a -% \describestring[error situation]{BADGUARD}|BADGUARD| -% \word{situation}. -% \begin{tcl} - if {$interaction} then { - error "Malformed guard on line $lineno." ""\ - [list DOCSTRIP BADGUARD $lineno] - } else { - puts stderr "docstrip: Malformed guard\ - on line $lineno:" - puts stderr $line - } - } - } %* {}\ -% \end{tcl} -% With comment lines, nothing is done. A line being the exact string -% |\endinput| terminates the stripping. -% \begin{tcl} - {\\endinput} { - break - } default { -% \end{tcl} -% Other lines are code lines. These are included or not, depending on -% the |offlevel|. -% \begin{tcl} - if {!$offlevel} then {append stripped $line \n} - } - } - incr lineno - } - return $stripped -} -% \end{tcl} -% \end{proc} -% -% -% \begin{proc}{source} -% This procedure behaves as a docstripping |source| command: it reads -% a file, docstrips its contents in memory, and evaluates the result -% as a \Tcllogo\ script in the context of the caller. The syntax is -% \begin{quote} -% |dtx::source| \word{dtx-file} \word{options} -% \end{quote} -% where \word{dtx-file} is the file name and \word{options} is the -% list of options. -% \begin{tcl} -proc dtx::source {name options} { - set F [open $name r] - set text [read $F] - close $F - uplevel 1 [dtx::strip_string $text $options #] -} -%</pkg> -% \end{tcl} -% \end{proc} -% -% -\endinput - -
\ No newline at end of file diff --git a/Master/texmf-dist/source/latex/tcldoc/tools/sourcedtx.ins b/Master/texmf-dist/source/latex/tcldoc/tools/sourcedtx.ins deleted file mode 100644 index f26acf7ee73..00000000000 --- a/Master/texmf-dist/source/latex/tcldoc/tools/sourcedtx.ins +++ /dev/null @@ -1,31 +0,0 @@ -% sourcedtx.ins --- DOCSTRIP installation script for sourcedtx.tcl. -\input docstrip - -% Redefine the \MetaPrefix; it should be something which starts a -% until-end-of-line comment: -\edef\MetaPrefix{\string#\string#} - - -% Redefine the file preamble and postamble; this is necessary because -% otherwise the old \metaPrefix is inserted at the beginning of these -% lines. -\preamble - -This file is put in the public domain. Note however that -************************************** -* This Source is not the True Source * -************************************** -the true source is the file from which this one was generated. - -\endpreamble - -\postamble -\endpostamble - -% Actually make sourcedtx.tcl: -\generate{ - \file{sourcedtx.tcl}{\from{sourcedtx.dtx}{pkg}} -} - - -\end |