← Back to branch summary

~ubuntu-branches/ubuntu/karmic/axiom/karmic

« back to all changes in this revision

Viewing changes to src/hyper/pages/HTXLinkPage4.ht

  • Committer: Bazaar Package Importer
  • Author(s):
  • Date: 2005-02-21 17:08:37 UTC
  • mfrom: (1.2.1 upstream) (2.1.1 hoary)
  • Revision ID: james.westby@ubuntu.com-20050221170837-34vm4j33v4t9hsk4
Tags: 20050201-1
http://bugs.debian.org/295000
* New upstream release
* Bug fix: "axiom graphics missing?", thanks to Daniel Lakeland (Closes:
  #277692).
* Bug fix: "axiom: Feb 2005 release for sarge would be nice", thanks to
  Balbir Thomas (Closes: #295000).

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/hyper/pages/HTXLinkPage4.ht
 
1
\begin{page}{HTXLinkPage4}{Linking to Lisp}
 
2
\centerline{\fbox{{\tt \thispage}}}\newline
 
3
\begin{scroll}
 
4
 
 
5
Another feature of the \Language{}\hspace{2}--\HyperName{}
 
6
link is the ability to execute {\it Lisp}
 
7
code at a click of a button.
 
8
There are two things one can do.
 
9
 
 
10
The first is to cause the evaluation
 
11
of a {\it Lisp} form and ignore (as far as \HyperName{}
 
12
is concerned) its value. The evaluation of the function
 
13
might have an effect however on your \Language{} session.
 
14
 
 
15
The command for this is
 
16
\horizontalline
 
17
\centerline{ {\tt \\lispcommand\{{\it text}\}\{{\it Lisp form}\}}}
 
18
\horizontalline
 
19
 
 
20
Here is an example. We will first define a {\it Lisp} function
 
21
and then execute it.  Notice that the \HyperName{}
 
22
special characters must be escaped (this is on top
 
23
of {\it Lisp} escaping conventions).
 
24
 
 
25
 
 
26
\beginImportant
 
27
\begin{paste}{HTXLinkPage4xPaste1}{HTXLinkPage4xPatch1}
 
28
\pastebutton{HTXLinkPage4xPaste1}{Interpret}
 
29
\newline
 
30
{\tt \\lispcommand\{Definition\}\{(defun HTXTESTFUNCTION ()}\newline
 
31
{\tt  (print "Hello from HyperDoc \\\\\\\\ \\\% \\\{ \\\}"))\}} \newline
 
32
{\tt \\newline}\newline
 
33
{\tt \\lispcommand\{Execution\}\{(HTXTESTFUNCTION)\}} \newline
 
34
\end{paste}
 
35
\endImportant
 
36
 
 
37
Your command will be executed as soon as
 
38
\Language{} completes any computation it might be
 
39
carrying out.
 
40
 
 
41
 
 
42
%\axiomcommand{)lisp (defun f () (pprint "hello"))}
 
43
%\lispcommand{f}{(|f|)}
 
44
 
 
45
 
 
46
The second thing you can do is quite powerful. It allows you
 
47
to delegate to a {\it Lisp} function
 
48
the {\it dynamic} creation of a page. This is used
 
49
in \Browse{} to present
 
50
the \Language{} Library in a hypertext form.
 
51
 
 
52
The command to use is a lot like the {\tt link} commands
 
53
you encountered \downlink{earlier}{HTXLinkPage1} and comes in three flavours.
 
54
\centerline{{\tt \\lispwindowlink\{{\it trigger}\}\{{\it Lisp form}\}}}
 
55
\centerline{{\tt \\lispdownlink\{{\it trigger}\}\{{\it Lisp form}\}}}
 
56
\centerline{{\tt \\lispmemolink\{{\it trigger}\}\{{\it Lisp form}\}}}
 
57
 
 
58
The difference between the three versions is the same as before.
 
59
When such a link is activated, \HyperName{} issues the
 
60
{\it Lisp form} to \Language{} and waits for a full
 
61
page definition. An important point to note is that
 
62
\HyperName{} does {\it not} use
 
63
the value of the {\it Lisp form} but, instead, it
 
64
depends on its {\it side-effects}.
 
65
What {\it must} happen during evaluation
 
66
of the form is enough evaluations of a special {\it Lisp}
 
67
function called {\bf issueHT} to define a page.
 
68
The argument of {\bf issueHT} is a string
 
69
containing \HyperName{} text. Perhaps an example will clarify
 
70
matters.
 
71
 
 
72
First we will define a {\it Lisp} function that accepts
 
73
a string argument and calls {\bf issueHT} a few times.
 
74
The strings that are passed to {\bf issueHT} construct
 
75
a \HyperName{} page that would just contain our
 
76
original argument centered roughly on the page.
 
77
Then we write the {\tt \\lisplink} with a call to
 
78
the function. Finally, we execute a {\it Lisp}
 
79
command that just pretty--prints the function's definition.
 
80
 
 
81
 
 
82
 
 
83
\beginImportant
 
84
\begin{paste}{HTXLinkPage4xPaste2}{HTXLinkPage4xPatch2}
 
85
\pastebutton{HTXLinkPage4xPaste2}{Interpret}
 
86
\newline
 
87
{\tt \\lispcommand\{Definition\}\{(defun HTXTESTPAGE (x) (|issueHT|}\newline
 
88
{\tt  "\\\\\\\\begin\\\{page\\\}\\\{LispTestPage\\\}\\\{Lisp Test Page\\\}}\newline
 
89
{\tt  \\\\\\\\vspace\\\{150\\\} \\\\\\\\centerline\\\{") (|issueHT| x) (|issueHT|}\newline
 
90
{\tt  "\\\} \\\\\\\\end\\\{page\\\}" ) ) \}}\newline
 
91
{\tt \\newline}\newline
 
92
{\tt \\lispwindowlink\{Link to it\}\{(HTXTESTPAGE "Hi there")\}}\newline
 
93
{\tt \\newline}\newline
 
94
{\tt \\lispcommand\{Show Lisp definition\}\{(pprint (symbol-function 'HTXTESTPAGE))\}}\newline
 
95
\end{paste}
 
96
\endImportant
 
97
 
 
98
The {\tt '\\\{'} and {\tt '\\\}'} is required to escape
 
99
\HyperName{}'s special characters {\tt '\{'} and {\tt  '\}'}.
 
100
The {\tt '\\\\\\\\'} has the following rationale.
 
101
We need to send to \HyperName{} (from {\it Lisp}) the sequence
 
102
{\tt \\begin}. But {\tt '\\'} is a special {\it Lisp}
 
103
character. Therefore the {\it Lisp} string must be
 
104
{\tt '\\\\begin'}. But to specify this
 
105
in \HyperName{} we need to escape the two {\tt '\\'}.
 
106
Therefore, we write {\tt '\\\\\\\\begin'}.
 
107
 
 
108
 
 
109
The definition of {\tt HTXTESTPAGE} would have been written in {\it Lisp}
 
110
as follows.
 
111
\begin{verbatim}
 
112
(defun HTXTESTPAGE (X)
 
113
   (|issueHT|
 
114
      "\\begin{page}{LispTestPage}{Lisp Test Page} \\vspace{200} \\centerline{")
 
115
   (|issueHT| X)
 
116
   (|issueHT| "} \\end{page}"))
 
117
\end{verbatim}
 
118
 
 
119
 
 
120
 
 
121
You should not execute {\tt HTXTESTPAGE} in the
 
122
{\it Lisp} environment manually. It is meant to
 
123
be executed {\it only} in response to a
 
124
\HyperName{} request.
 
125
 
 
126
Can you pop-up a named page from {\it Lisp} regardless of
 
127
user action? Yes --- use {\it Lisp} function {\bf linkToHTPage}
 
128
with the page name as a string argument. Click on the
 
129
{\tt \\axiomcommand} below. Then, in your \Language{}
 
130
session, you can repeat it if you like.
 
131
 
 
132
\beginImportant
 
133
\begin{paste}{HTXLinkPage4xPaste3}{HTXLinkPage4xPatch3}
 
134
\pastebutton{HTXLinkPage4xPaste3}{Interpret}
 
135
\newline
 
136
{\tt \\axiomcommand\{)lisp (|linkToHTPage| "RootPage")\}}
 
137
\end{paste}
 
138
\endImportant
 
139
 
 
140
You can also pop-up a {\it dynamic} page regardless of user action.
 
141
To do this, make sure you evaluate the {\it Lisp form}
 
142
{\bf (|startHTPage| 50)} before using {\bf issueHT}.
 
143
The example below requires the {\tt HTXTESTPAGE} function
 
144
to be defined in {\it Lisp} so you should make sure
 
145
you have executed the command above that defines it.
 
146
 
 
147
\beginImportant
 
148
\begin{paste}{HTXLinkPage4xPaste4}{HTXLinkPage4xPatch4}
 
149
\pastebutton{HTXLinkPage4xPaste4}{Interpret}
 
150
\newline
 
151
{\tt \\axiomcommand\{)lisp (progn (|startHTPage| 50)(HTXTESTPAGE "Immediately"))\}}
 
152
\end{paste}
 
153
\endImportant
 
154
 
 
155
Now, the most important use of this facility
 
156
so far has been in the \Browse{} and Basic Commands components of
 
157
\HyperName{}. Instead of giving you details of the various
 
158
\Browse{} {\it Lisp} functions, a few macros are defined in
 
159
\centerline{{\bf \$AXIOM/doc/hypertex/pages/util.ht}}
 
160
 
 
161
The most important defined macros are
 
162
\beginImportant
 
163
\table{
 
164
{ {\tt \\axiomType\{{\it constructor}\}} }
 
165
{ {\tt \\axiomOp\{{\it operation}\}} }
 
166
{ {\tt \\axiomOpFrom\{{\it operation }\}\{{\it constructor}\}}}
 
167
}
 
168
\endImportant
 
169
 
 
170
Here are some examples of their use.
 
171
\beginImportant
 
172
\begin{paste}{HTXLinkPage4xPaste5}{HTXLinkPage4xPatch5}
 
173
\pastebutton{HTXLinkPage4xPaste5}{Interpret}
 
174
\newline
 
175
{\tt \\axiomType\{Expression Integer\}}\newline
 
176
{\tt \newline}\newline
 
177
{\tt \\axiomType\{Expression\}}\newline
 
178
{\tt \newline}\newline
 
179
{\tt \\axiomType\{EXPR\}}\newline
 
180
{\tt \newline}\newline
 
181
{\tt \\axiomOp\{reduce\}}\newline
 
182
{\tt \newline}\newline
 
183
{\tt \\axiomOp\{as*\}}\newline
 
184
{\tt \newline}\newline
 
185
{\tt \\axiomOpFrom\{reduce\}\{Expression\}}\newline
 
186
\end{paste}
 
187
\endImportant
 
188
 
 
189
The macro {\tt \\axiomType} brings up the \Browse{}
 
190
constructor page for the constructor specified.
 
191
You can specify a full name, or an abbreviation
 
192
or just the top level name.
 
193
The macro {\tt \\axiomOp} brings up a list of operations
 
194
matching the argument.
 
195
The macro {\tt \\axiomOpFrom} shows documentation
 
196
about the specified operation whose origin is
 
197
constructor. No wildcard in the operation name
 
198
or type abbreviation is
 
199
allowed here.  You should also specify just the top level type.
 
200
 
 
201
 
 
202
 
 
203
 
 
204
 
 
205
 
 
206
 
 
207
\end{scroll}
 
208
\beginmenu
 
209
\menulink{Next -- Linking to Unix}{HTXLinkPage5}
 
210
\endmenu
 
211
 
 
212
\end{page}
 
213
\begin{patch}{HTXLinkPage4xPatch1}
 
214
\begin{paste}{HTXLinkPage4xPaste1A}{HTXLinkPage4xPatch1A}
 
215
\pastebutton{HTXLinkPage4xPaste1A}{Source}
 
216
\newline
 
217
\lispcommand{Definition}{(defun HTXTESTFUNCTION ()
 
218
(print "Hello from HyperDoc \\\\ \% \{ \}"))}
 
219
\newline
 
220
\lispcommand{Execution}{(HTXTESTFUNCTION)}
 
221
\end{paste}
 
222
\end{patch}
 
223
\begin{patch}{HTXLinkPage4xPatch1A}
 
224
\begin{paste}{HTXLinkPage4xPaste1B}{HTXLinkPage4xPatch1}
 
225
\pastebutton{HTXLinkPage4xPaste1B}{Interpret}
 
226
\newline
 
227
{\tt \\lispcommand\{Definition\}\{(defun HTXTESTFUNCTION () (print "Hello from HyperDoc \\\\\\\\ \\\% \\\{ \\\}"))\}} \newline
 
228
{\tt \\newline}\newline
 
229
{\tt \\lispcommand\{Execution\}\{(HTXTESTFUNCTION)\}} \newline
 
230
\end{paste}
 
231
\end{patch}
 
232
 
 
233
\begin{patch}{HTXLinkPage4xPatch2}
 
234
\begin{paste}{HTXLinkPage4xPaste2A}{HTXLinkPage4xPatch2A}
 
235
\pastebutton{HTXLinkPage4xPaste2A}{Source}
 
236
\newline
 
237
\lispcommand{Definition}{(defun HTXTESTPAGE (x) (|issueHT|
 
238
"\\\\begin\{page\}\{LispTestPage\}\{Lisp Test Page\}
 
239
\\\\vspace\{150\} \\\\centerline\{") (|issueHT| x) (|issueHT|
 
240
"\} \\\\end\{page\}" ) ) }
 
241
\newline
 
242
\lispwindowlink{Link to it}{(HTXTESTPAGE "Hi there")}
 
243
\newline
 
244
\lispcommand{Show Lisp definition}{(pprint (symbol-function 'HTXTESTPAGE))}
 
245
\end{paste}
 
246
\end{patch}
 
247
\begin{patch}{HTXLinkPage4xPatch2A}
 
248
\begin{paste}{HTXLinkPage4xPaste2B}{HTXLinkPage4xPatch2}
 
249
\pastebutton{HTXLinkPage4xPaste2B}{Interpret}
 
250
\newline
 
251
{\tt \\lispcommand\{Definition\}\{(defun HTXTESTPAGE (x) (|issueHT|}\newline
 
252
{\tt  "\\\\\\\\begin\\\{page\\\}\\\{LispTestPage\\\}\\\{Lisp Test Page\\\}}\newline
 
253
{\tt  \\\\\\\\vspace\\\{150\\\} \\\\\\\\centerline\\\{") (|issueHT| x) (|issueHT|}\newline
 
254
{\tt  "\\\} \\\\\\\\end\\\{page\\\}" ) ) \}}\newline
 
255
{\tt \\newline}\newline
 
256
{\tt \\lispwindowlink\{Link to it\}\{(HTXTESTPAGE "Hi there")\}}\newline
 
257
{\tt \\newline}\newline
 
258
{\tt \\lispcommand\{Show Lisp definition\}\{(pprint (symbol-function 'HTXTESTPAGE))\}}\newline
 
259
\end{paste}
 
260
\end{patch}
 
261
 
 
262
 
 
263
\begin{patch}{HTXLinkPage4xPatch3}
 
264
\begin{paste}{HTXLinkPage4xPaste3A}{HTXLinkPage4xPatch3A}
 
265
\pastebutton{HTXLinkPage4xPaste3A}{Source}
 
266
\newline
 
267
\axiomcommand{)lisp (|linkToHTPage| "RootPage")}
 
268
\end{paste}
 
269
\end{patch}
 
270
\begin{patch}{HTXLinkPage4xPatch3A}
 
271
\begin{paste}{HTXLinkPage4xPaste3B}{HTXLinkPage4xPatch3}
 
272
\pastebutton{HTXLinkPage4xPaste3B}{Interpret}
 
273
\newline
 
274
{\tt \\axiomcommand\{)lisp (|linkToHTPage| "RootPage")\}}
 
275
\end{paste}
 
276
\end{patch}
 
277
 
 
278
\begin{patch}{HTXLinkPage4xPatch4}
 
279
\begin{paste}{HTXLinkPage4xPaste4A}{HTXLinkPage4xPatch4A}
 
280
\pastebutton{HTXLinkPage4xPaste4A}{Source}
 
281
\newline
 
282
\axiomcommand{)lisp (progn (|startHTPage| 50)(HTXTESTPAGE "Immediately"))}
 
283
\end{paste}
 
284
\end{patch}
 
285
\begin{patch}{HTXLinkPage4xPatch4A}
 
286
\begin{paste}{HTXLinkPage4xPaste4B}{HTXLinkPage4xPatch4}
 
287
\pastebutton{HTXLinkPage4xPaste4B}{Interpret}
 
288
\newline
 
289
{\tt \\axiomcommand\{)lisp (progn (|startHTPage| 50)(HTXTESTPAGE "Immediately"))\}}
 
290
\end{paste}
 
291
\end{patch}
 
292
 
 
293
 
 
294
\begin{patch}{HTXLinkPage4xPatch5}
 
295
\begin{paste}{HTXLinkPage4xPaste5A}{HTXLinkPage4xPatch5A}
 
296
\pastebutton{HTXLinkPage4xPaste5A}{Source}
 
297
\newline
 
298
\axiomType{Expression Integer}
 
299
\newline
 
300
\axiomType{Expression}
 
301
\newline
 
302
\axiomType{EXPR}
 
303
\newline
 
304
\axiomOp{reduce}
 
305
\newline
 
306
\axiomOp{as*}
 
307
\newline
 
308
\axiomOpFrom{reduce}{Expression}
 
309
\end{paste}
 
310
\end{patch}
 
311
\begin{patch}{HTXLinkPage4xPatch5A}
 
312
\begin{paste}{HTXLinkPage4xPaste5B}{HTXLinkPage4xPatch5}
 
313
\pastebutton{HTXLinkPage4xPaste5B}{Interpret}
 
314
\newline
 
315
{\tt \\axiomType\{Expression Integer\}}\newline
 
316
{\tt \newline}\newline
 
317
{\tt \\axiomType\{Expression\}}\newline
 
318
{\tt \newline}\newline
 
319
{\tt \\axiomType\{EXPR\}}\newline
 
320
{\tt \newline}\newline
 
321
{\tt \\axiomOp\{reduce\}}\newline
 
322
{\tt \newline}\newline
 
323
{\tt \\axiomOp\{as*\}}\newline
 
324
{\tt \newline}\newline
 
325
{\tt \\axiomOpFrom\{reduce\}\{Expression\}}\newline
 
326
\end{paste}
 
327
\end{patch}
 
328