diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/tcldoc/dtxload.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/tcldoc/dtxload.dtx | 1256 |
1 files changed, 1256 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/tcldoc/dtxload.dtx b/Master/texmf-dist/source/latex/tcldoc/dtxload.dtx new file mode 100644 index 00000000000..f68a0ca3a8b --- /dev/null +++ b/Master/texmf-dist/source/latex/tcldoc/dtxload.dtx @@ -0,0 +1,1256 @@ +% +% +% \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 |