\begin{page}{HTXLinkPage3}{Active\ \Language{} commands}
\centerline{\fbox{{\tt \thispage}}}\newline
\begin{scroll}

This section explains how to include \Language{}
commands in your page. The commands we will
introduce are actually {\it macros} that are defined
in
\centerline{{\bf \env{AXIOM}/doc/hypertex/pages/util.ht}}
This means that you can use them only if you include
this file in your \HyperName{} database.

The first command to learn is
\horizontalline
{\tt \\axiomcommand\{ {\it command }{\tt \ \\free\{}{\it var1 var2 ...}{\tt \}\ \\bound\{}{\it var}{\tt \}\ \}} }
\horizontalline


The {\tt \\free\{\}} and {\tt \\bound\{\}} directives are optional.
We will come to them in a minute. The {\it command} above is the
text of the \Language{} command. Only single line commands are allowed
here.
This text will be displayed in the reserved AxiomFont logical
font.  The area of the text will be active and clicking on it
will attempt to send the command to \Language{} for evaluation.
A new \Language{} interpreter window (and \Language{} frame)
will be created if this was the first \Language{} command
activated in the current page. If not, the command will be sent
to the already opened \Language{} interpreter window for the current page.
Note that it {\it is} necessary to escape special
\HyperName{} characters with the {\tt '\\'} backslash character.
The exceptions are the characters {\tt \[\]}; they do not
need to be escaped in this context.

\beginImportant
\begin{paste}{HTXLinkPage3xPaste1}{HTXLinkPage3xPatch1}
\pastebutton{HTXLinkPage3xPaste1}{Interpret}
\newline
{\tt \\axiomcommand\{ l:=brace[1,2,3] ; length:=\\\# l ; m:=[1,2]\}}
\end{paste}
\endImportant


The optional {\tt \\free\{\}} and {\tt \\bound\{\}} directives
provide dependency control. The reader of a \HyperName{}
page is not forced to click on the commands in the
order in which in they appear on the page.  If the
correct {\tt \\free\{\}} and {\tt \\bound\{\}}
specifications are made, clicking on a command
will result in execution of all those other
commands that should be executed before it.
This will {\it only} happen the first time the command is
clicked.

So, how are the dependencies specified?
The arguments of the {\tt \\free\{\}} directive must
be space-separated words (labels). The argument of {\tt \\bound\{\}}
must be a single (unique for the page) label. Each label in the {\tt \\free\{\}} list
must exist as an argument to one (and only one) {\tt \\bound\{\}} directive
somewhere in the current page.
When the command is activated, \HyperName{} will look
in the {\tt \\free\{\}} list and check each label.
For each label, it will find the command that specifies that label
in its {\tt \\bound\{\}} directive and
execute it if it has not been already executed.
The order of labels in the {\tt \\free\{\}} directive list
is respected. \HyperName{} will follow all
dependency links recursively.

Here is  an example.
Clicking on the third command will automatically
execute all of them in the correct sequence.
Note that in this case the order of labels in the last
line is immaterial since {\tt v2} explicitly depends on {\tt v1}.

\beginImportant
\begin{paste}{HTXLinkPage3xPaste2}{HTXLinkPage3xPatch2}
\pastebutton{HTXLinkPage3xPaste2}{Interpret}
\newline
{\tt \\axiomcommand\{a:=1;d:=4 \\bound\{v1\}\}}\newline
{\tt \\newline}\newline
{\tt \\axiomcommand\{b:=a+3 \\free\{v1\} \\bound\{v2\}\}}\newline
{\tt \\newline}\newline
{\tt \\axiomcommand\{c:=b+d \\free\{v1 v2\} \\bound\{v3\}\}}\newline
\end{paste}
\endImportant

The second command deals with multi-line \Language{}
code. This is the command to use for execution of
an \Language{} {\it pile}. It is a {\it group}
command. The proper syntax for it is as follows:
\horizontalline
{\tt \\begin\{spadsrc\}\ [\\free\{{\it var1 var2} ...\}\ \\bound\{{\it var}\}]}
\newline
.
\newline
.
\newline
{\tt \\end\{spadsrc\}}
\horizontalline

Again, the {\tt \\free} and {\tt \\bound} directives are
optional. If they are specified (in exactly the same way
as {\tt \\axiomcommand}), they must be enclosed in
square brackets {\tt []}.
The lines between the {\tt \\begin} and {\tt \\end}
contain the \Language{} statements. Indentation
will be respected. \HyperName{} will
actually save this part in a temporary file
and instruct \Language{} to read the file
with the {\tt )read} system command.

Here is an example. The execution of the following
fragment is dependent on the {\tt v3} label.
Make sure that previous commands are active (and
hence the label {\tt v3} is "visible") before
trying to execute it. If the label {\tt v3}
is not seen in the page, \HyperName{} will
print an error message on standard output
and ignore the dependency.


\beginImportant
\begin{paste}{HTXLinkPage3xPaste3}{HTXLinkPage3xPatch3}
\pastebutton{HTXLinkPage3xPaste3}{Interpret}
\newline
{\tt \\begin\{spadsrc\}\ [\\free\{v3\}\ \\bound\{v4\}]}\newline
{\tt f\ x\ ==}\newline
{\tt \ \ \ x+c}\newline
{\tt f\ 3}\newline
{\tt \\end\{spadsrc\}}
\end{paste}
\endImportant

There is, in fact, more that one can do
with \Language{} commands. In pages elsewhere
in the system, \Language{} commands appear next
to button like this \ \MenuDotBitmap{}.
Clicking on this button, one can see the output
for that command. The output has been
pre-computed and is also stored in
\HyperName{} files. This is done using
{\it patch} and {\it paste}.
It is the same mechanism that
is used to alternatively display
\HyperName{} source and interpreted
result in this and other pages.
It is explained \downlink{later on}{HTXAdvPage5}.


\end{scroll}
\beginmenu
\menulink{Next -- Linking to Lisp}{HTXLinkPage4}
\endmenu

\end{page}
\begin{patch}{HTXLinkPage3xPatch1}
\begin{paste}{HTXLinkPage3xPaste1A}{HTXLinkPage3xPatch1A}
\pastebutton{HTXLinkPage3xPaste1A}{Source}
\newline
\axiomcommand{ l:=brace[1,2,3] ; length:=\# l ; m:=[1,2]}
\end{paste}
\end{patch}
\begin{patch}{HTXLinkPage3xPatch1A}
\begin{paste}{HTXLinkPage3xPaste1B}{HTXLinkPage3xPatch1}
\pastebutton{HTXLinkPage3xPaste1B}{Interpret}
\newline
{\tt \\axiomcommand\{ l:=brace[1,2,3] ; length:=\\\# l ; m:=[1,2]\}}
\end{paste}
\end{patch}

\begin{patch}{HTXLinkPage3xPatch2}
\begin{paste}{HTXLinkPage3xPaste2A}{HTXLinkPage3xPatch2A}
\pastebutton{HTXLinkPage3xPaste2A}{Source}
\newline
\axiomcommand{a:=1;d:=4 \bound{v1}}
\newline
\axiomcommand{b:=a+3 \free{v1} \bound{v2}}
\newline
\axiomcommand{c:=b+d \free{v1 v2} \bound{v3}}
\end{paste}
\end{patch}
\begin{patch}{HTXLinkPage3xPatch2A}
\begin{paste}{HTXLinkPage3xPaste2B}{HTXLinkPage3xPatch2}
\pastebutton{HTXLinkPage3xPaste2B}{Interpret}
\newline
{\tt \\axiomcommand\{a:=1;d:=4 \\bound\{v1\}\}}\newline
{\tt \\newline}\newline
{\tt \\axiomcommand\{b:=a+3 \\free\{v1\} \\bound\{v2\}\}}\newline
{\tt \\newline}\newline
{\tt \\axiomcommand\{c:=b+d \\free\{v1 v2\} \\bound\{v3\}\}}\newline
\end{paste}
\end{patch}


\begin{patch}{HTXLinkPage3xPatch3}
\begin{paste}{HTXLinkPage3xPaste3A}{HTXLinkPage3xPatch3A}
\pastebutton{HTXLinkPage3xPaste3A}{Source}
\newline
\begin{spadsrc} [\free{v3} \bound{v4}]
f x ==
   x+c
f 3
\end{spadsrc}
\end{paste}
\end{patch}
\begin{patch}{HTXLinkPage3xPatch3A}
\begin{paste}{HTXLinkPage3xPaste3B}{HTXLinkPage3xPatch3}
\pastebutton{HTXLinkPage3xPaste3B}{Interpret}
\newline
{\tt \\begin\{spadsrc\}\ [\\free\{v3\}\ \\bound\{v4\}]}\newline
{\tt f\ x\ ==}\newline
{\tt \ \ \ x+c}\newline
{\tt f\ 3}\newline
{\tt \\end\{spadsrc\}}
\end{paste}
\end{patch}