comparison lisp/hyperbole/DEMO @ 24:4103f0995bd7 r19-15b95

Import from CVS: tag r19-15b95
author cvs
date Mon, 13 Aug 2007 08:51:03 +0200
parents 376386a54a3c
children 131b0175ea99
comparison
equal deleted inserted replaced
23:0edd3412f124 24:4103f0995bd7
1 * Overview 1 * Overview
2
3 InfoDock Associates, the developer of Hyperbole and InfoDock (an industrial
4 quality turn-key version of XEmacs), sells high quality commercial support,
5 training, books and custom package development for InfoDock, XEmacs or GNU
6 Emacs on a variety of platforms. Contact us at <info@infodock.com> or visit
7 our web site at http://www.infodock.com.
8
9 ------------------
2 10
3 This file demonstrates simple usage of the basic Hyperbole button-action 11 This file demonstrates simple usage of the basic Hyperbole button-action
4 types and shows how Hyperbole can support a style of self-documenting, 12 types and shows how Hyperbole can support a style of self-documenting,
5 interactive files. See the glossary in the Hyperbole Manual, 13 interactive files. See the glossary in the Hyperbole Manual,
6 "(hyperbole.info)Glossary", if terms used here are unfamiliar to you. 14 "(hyperbole.info)Glossary", if terms used here are unfamiliar to you.
21 29
22 This button prints the <(factorial)> of 5 in the minibuffer when activated 30 This button prints the <(factorial)> of 5 in the minibuffer when activated
23 with the Action Key. (Once you have Hyperbole installed, just press the 31 with the Action Key. (Once you have Hyperbole installed, just press the
24 Action Key on the word, <(factorial)>.) If you instead press the Assist Key, 32 Action Key on the word, <(factorial)>.) If you instead press the Assist Key,
25 you get help for the preceding button. The help provides a summary report of 33 you get help for the preceding button. The help provides a summary report of
26 the button. You will see that it utilizes the 'eval-elisp' action type. You 34 the button. You will see that it utilizes the `eval-elisp' action type. You
27 can also see who created it. Try it. 35 can also see who created it. Try it.
28 36
29 Note that the create-time and mod-time are displayed using your own 37 Note that the create-time and mod-time are displayed using your own
30 timezone but they are stored as universal times. So if you work with 38 timezone but they are stored as universal times. So if you work with
31 people at other sites, you can mix their buttons with your own within 39 people at other sites, you can mix their buttons with your own within
123 131
124 A <(shell command)> button can do many things, such as display the length of 132 A <(shell command)> button can do many things, such as display the length of
125 this file. While such commands are executing, you can perform other 133 this file. While such commands are executing, you can perform other
126 operations. If you create a button that runs a shell command which 134 operations. If you create a button that runs a shell command which
127 displays its own window system window, i.e. a window outside of Emacs, use 135 displays its own window system window, i.e. a window outside of Emacs, use
128 'exec-window-cmd' rather than 'exec-shell-cmd' as its action type. 136 `exec-window-cmd' rather than `exec-shell-cmd' as its action type.
129 137
130 You can link to files such as your <(.login)> file. Or directories, 138 You can link to files such as your <(.login)> file. Or directories,
131 like the <(tmp directory)>. When creating file links, if the file you 139 like the <(tmp directory)>. When creating file links, if the file you
132 are linking to is loaded in a buffer, you are prompted as to whether you 140 are linking to is loaded in a buffer, you are prompted as to whether you
133 want the link to jump to the present point in that buffer. If so, the 141 want the link to jump to the present point in that buffer. If so, the
134 link will always jump there, so position point within the referent file 142 link will always jump there, so position point within the referent file
135 to take advantage of this feature. Note how a separate window is used 143 to take advantage of this feature. Note how a separate window is used
136 when you activate file link buttons. Most basic Hyperbole action types 144 when you activate file link buttons. Most basic Hyperbole action types
137 display their results in this manner. 145 display their results in this manner.
138 146
139 You can make a button an alias for another by using the 'link-to-ebut' 147 You can make a button an alias for another by using the `link-to-ebut'
140 action type. This <(factorial alias)> button does whatever the earlier 148 action type. This <(factorial alias)> button does whatever the earlier
141 <(factorial)> button does. 149 <(factorial)> button does.
142 150
143 The 'link-to-mail' action type allows you to reference mail messages 151 The `link-to-mail' action type allows you to reference mail messages
144 that you have stored away. We can't demonstrate it here since we don't 152 that you have stored away. We can't demonstrate it here since we don't
145 have the mail messages that you do. 153 have the mail messages that you do.
146 154
147 Hyperbole buttons may also be embedded within mail messages. Even 155 Hyperbole buttons may also be embedded within mail messages. Even
148 buttons copied into mail replies can work: 156 buttons copied into mail replies can work:
167 175
168 ** Implicit Path Links 176 ** Implicit Path Links
169 177
170 Any doubly quoted pathname acts as an implicit button that either displays the 178 Any doubly quoted pathname acts as an implicit button that either displays the
171 referenced path within a buffer, passes it to an external viewer program, or 179 referenced path within a buffer, passes it to an external viewer program, or
172 runs a function that operates upon the path. These are 'pathname' implicit 180 runs a function that operates upon the path. These are `pathname' implicit
173 buttons. For example, activate "README". 181 buttons. For example, activate "README".
174 182
175 Most pathnames simply link to the files that they name and so are simply 183 Most pathnames simply link to the files that they name and so are simply
176 displayed for editing. The variable 'hpath:suffixes' is a list of filename 184 displayed for editing. The variable `hpath:suffixes' is a list of filename
177 suffix strings that are added to or removed from pathnames when searching for 185 suffix strings that are added to or removed from pathnames when searching for
178 a match. "So if "README.gz" existed, the pathname button "README" would 186 a match. "So if "README.gz" existed, the pathname button "README" would
179 display it. If you use the Emacs "crypt.el" package, then compressed files 187 display it. If you use the Emacs "crypt.el" package, then compressed files
180 will be uncompressed before they are displayed. Activate "README.gz" and 188 will be uncompressed before they are displayed. Activate "README.gz" and
181 you'll see that the README file is displayed as desired. 189 you'll see that the README file is displayed as desired.
182 190
183 The variable 'hpath:display-alist' contains pairs of pathname expressions and 191 The variable `hpath:display-alist' contains pairs of pathname expressions and
184 edit functions. When a pathname matches an expression, the associated edit 192 edit functions. When a pathname matches an expression, the associated edit
185 function is invoked upon the pathname. 193 function is invoked upon the pathname.
186 194
187 The variable 'hpath:find-alist' determines the file suffixes which should be 195 The variable `hpath:find-alist' determines the file suffixes which should be
188 viewed with external programs. It also specifies the associated viewer 196 viewed with external programs. It also specifies the associated viewer
189 program for each different window system under which Hyperbole may be run. 197 program for each different window system under which Hyperbole may be run.
190 See its documentation for more details. Under the X window system, for 198 See its documentation for more details. Under the X window system, for
191 example, if you have the 'xv' program, all of the following file formats may 199 example, if you have the `xv' program, all of the following file formats may
192 be displayed as images: gif, tiff, xbm, pm, pbm, and jpeg. 200 be displayed as images: gif, tiff, xbm, pm, pbm, and jpeg.
193 201
194 Several prefix characters may be attached to pathnames to indicate that 202 Several prefix characters may be attached to pathnames to indicate that
195 a different action should be taken when the button is activated. 203 a different action should be taken when the button is activated.
196 An exclamation point prefix indicates that the full pathname should be run 204 An exclamation point prefix indicates that the full pathname should be run
203 If you use the ange-ftp or efs add-on to GNU Emacs, such remote pathnames 211 If you use the ange-ftp or efs add-on to GNU Emacs, such remote pathnames
204 will work as well. (The latest version of ange-ftp may always be obtained 212 will work as well. (The latest version of ange-ftp may always be obtained
205 via anonymous ftp to: 213 via anonymous ftp to:
206 "/anonymous@alpha.gnu.ai.mit.edu:ange-ftp/ange-ftp.tar.gz"). 214 "/anonymous@alpha.gnu.ai.mit.edu:ange-ftp/ange-ftp.tar.gz").
207 215
208 Once you have *loaded* the ange-ftp or the efs package (or you use a 216 Once you have *loaded* the ange-ftp or the efs package (or you use a version
209 version of Emacs 19 which autoloads ange-ftp), if you are on the 217 of Emacs 19 which autoloads ange-ftp), if you are on the Internet, you can
210 Internet, you can click on any of the following to browse the contents 218 click on any of the following to browse the contents of the Hyperbole
211 of the Hyperbole distribution at the XEmacs Archive (limit the amount 219 distribution at the University of Illinois at Urbana (limit the amount
212 you do this so as not to deny others access to the archive): 220 you do this so as not to deny others access to the archive):
213 221
214 "/anonymous@ftp.xemacs.org:pub/infodock/" 222 "/anonymous@ftp.xemacs.org:pub/infodock/"
215 /anonymous@128.174.252.16:/pub/infodock/ 223 /anonymous@128.174.252.16:/pub/infodock/
216 /ftp.xemacs.org:pub/infodock/ 224 /ftp.xemacs.org:pub/infodock/
223 231
224 "ftp://ftp.xemacs.org/pub/infodock/ 232 "ftp://ftp.xemacs.org/pub/infodock/
225 233
226 234
227 GNU Info (filename)node references such as "(hyperbole.info)Glossary" or 235 GNU Info (filename)node references such as "(hyperbole.info)Glossary" or
228 "(emacs)Glossary", work similarly, thanks to the 'Info-node' button type. 236 "(emacs)Glossary", work similarly, thanks to the `Info-node' button type.
229 Try one of the Glossary buttons above. 237 Try one of the Glossary buttons above.
230 238
231 If you want to quickly learn how to create explicit buttons, see 239 If you want to quickly learn how to create explicit buttons, see
232 "(hyperbole.info)Drags" and "(hyperbole.info)Menus". 240 "(hyperbole.info)Drags" and "(hyperbole.info)Menus".
233 241
248 256
249 Now suppose you want to browse through a number of files within the 257 Now suppose you want to browse through a number of files within the
250 Hyperbole distribution. You could use the Emacs dired subsystem, 258 Hyperbole distribution. You could use the Emacs dired subsystem,
251 "(emacs)Dired", but a faster way is to note that files named MANIFEST 259 "(emacs)Dired", but a faster way is to note that files named MANIFEST
252 and DIR are used to summarize the files in a directory, so we can use 260 and DIR are used to summarize the files in a directory, so we can use
253 each of their entries as an implicit button (of 'dir-summary' type) to 261 each of their entries as an implicit button (of `dir-summary' type) to
254 take us to the file. 262 take us to the file.
255 263
256 Let's look at "MANIFEST". Now click anywhere within a line in the MANIFEST 264 Let's look at "MANIFEST". Now click anywhere within a line in the MANIFEST
257 file and you see that it is displayed as expected. (Remember to use the 265 file and you see that it is displayed as expected. (Remember to use the
258 Hyperbole history command to return here.) You can get help on these buttons 266 Hyperbole history command to return here.) You can get help on these buttons
268 URLs (universal resource locators) from within any buffer just as you would 276 URLs (universal resource locators) from within any buffer just as you would
269 any other implicit button, once you do some initial setup. 277 any other implicit button, once you do some initial setup.
270 278
271 First you must ensure that you load the Hyperbole library that supports URL 279 First you must ensure that you load the Hyperbole library that supports URL
272 viewing. Either your "hsite.el" file should require hsys-w3 as part of 280 viewing. Either your "hsite.el" file should require hsys-w3 as part of
273 'hibtypes:begin-load-hook' or you should move point after the following line 281 `hibtypes:begin-load-hook' or you should move point after the following line
274 and hit {C-x C-e} to evaluate it. 282 and hit {C-x C-e} to evaluate it.
275 283
276 (progn (require 'w3) (require 'hsys-w3)) 284 (progn (require 'w3) (require 'hsys-w3))
277 285
278 Now try using the Action Key on: 286 Now try using the Action Key on:
279 287
280 "http://www.ncsa.uiuc.edu" 288 "http://www.infodock.com"
281 289
282 ** Grep, Occurrence, Debugger and Compiler Error Buttons, and Cscope Analyzer 290 ** Grep, Occurrence, Debugger and Compiler Error Buttons, and Cscope Analyzer
283 Lines 291 Lines
284 292
285 The output of 'grep -n', the UNIX line pattern matcher, can be 293 The output of `grep -n', the UNIX line pattern matcher, can be
286 activated as buttons that jump to each matched line within its source 294 activated as buttons that jump to each matched line within its source
287 file; use {M-x grep RET}. 295 file; use {M-x grep RET}.
288 296
289 Compiler error messages also serve as implicit buttons that jump to 297 Compiler error messages also serve as implicit buttons that jump to
290 associated source lines; use {M-x compile RET}. GDB, DBX or XDB stack frames 298 associated source lines; use {M-x compile RET}. GDB, DBX or XDB stack frames
329 337
330 @loc> #<buffer *scratch*> 338 @loc> #<buffer *scratch*>
331 339
332 If you click on the buffer name, the buffer will be displayed just as a 340 If you click on the buffer name, the buffer will be displayed just as a
333 file buffer would. This type of implicit button is called a 341 file buffer would. This type of implicit button is called a
334 'hyp-source' button. 342 `hyp-source' button.
335 343
336 You can also activate any explicit buttons shown in a help buffer. 344 You can also activate any explicit buttons shown in a help buffer.
337 345
338 ** UNIX Man Apropos Buttons 346 ** UNIX Man Apropos Buttons
339 347
340 Below are some lines output by the UNIX 'apropos' command (with a little 348 Below are some lines output by the UNIX `apropos' command (with a little
341 touchup for display purposes). A button activation anywhere within such 349 touchup for display purposes). A button activation anywhere within such
342 a line recognizes the line as an apropos entry and tries to display the 350 a line recognizes the line as an apropos entry and tries to display the
343 man page for the entry. Try it. (If you happen to use the 'superman' 351 man page for the entry. Try it. (If you happen to use the `superman'
344 package which fetches man pages in the background, you'll have to wait 352 package which fetches man pages in the background, you'll have to wait
345 for the next version of superman which removes incompatibilities with 353 for the next version of superman which removes incompatibilities with
346 the standard man page fetch command before you can use these 354 the standard man page fetch command before you can use these
347 'man-apropos' implicit buttons.) 355 `man-apropos' implicit buttons.)
348 356
349 grep, egrep, fgrep (1V) - search a file for a string or regular expression 357 grep, egrep, fgrep (1V) - search a file for a string or regular expression
350 rm, rmdir (1) - remove (unlink) files or directories 358 rm, rmdir (1) - remove (unlink) files or directories
351 touch (1V) - update the access and modification times of a file 359 touch (1V) - update the access and modification times of a file
352 cat (1V) - concatenate and display 360 cat (1V) - concatenate and display
355 363
356 If you are on the Internet and you have the ange-ftp or efs remote file 364 If you are on the Internet and you have the ange-ftp or efs remote file
357 handling package for GNU Emacs, you can retrieve and browse RFC documents 365 handling package for GNU Emacs, you can retrieve and browse RFC documents
358 used in Internet standard-making. Simply use the Action Key on an RFC 366 used in Internet standard-making. Simply use the Action Key on an RFC
359 document identifier, like RFC-822. Rfc822 and rfc 822 work as well. The 367 document identifier, like RFC-822. Rfc822 and rfc 822 work as well. The
360 'rfc' implicit button type provides this service. The 'hpath:rfc' variable 368 `rfc' implicit button type provides this service. The `hpath:rfc' variable
361 specifies the location from which to retrieve RFCs. 369 specifies the location from which to retrieve RFCs.
362 370
363 Once you have retrieved an RFC, an Action Key press most anywhere within a 371 Once you have retrieved an RFC, an Action Key press most anywhere within a
364 line typically will produce a table of contents summary of the RFC (via the 372 line typically will produce a table of contents summary of the RFC (via the
365 'rfc-toc' implicit button type). An Action Key press on any of the table of 373 `rfc-toc' implicit button type). An Action Key press on any of the table of
366 contents lines then displays that section, for easy random access browsing. 374 contents lines then displays that section, for easy random access browsing.
367 375
368 ** Site-specific Online Library Document IDs 376 ** Site-specific Online Library Document IDs
369 377
370 Hyperbole offers a powerful, yet easy to use facility for building online 378 Hyperbole offers a powerful, yet easy to use facility for building online
371 libraries through the use of the 'doc-id' implicit button type. A document id 379 libraries through the use of the `doc-id' implicit button type. A document id
372 is used just like a reference citation in traditional publications but 380 is used just like a reference citation in traditional publications but
373 it actually links to the document that it references and the card catalog 381 it actually links to the document that it references and the card catalog
374 (index) entry for the document. One can easily pass around doc ids to point 382 (index) entry for the document. One can easily pass around doc ids to point
375 people to appropriate documents. For example, a mail message in response to 383 people to appropriate documents. For example, a mail message in response to
376 a question might say, "See [Emacs-001] for examples of what Emacs can do." 384 a question might say, "See [Emacs-001] for examples of what Emacs can do."
412 420
413 Here is an example. Depress the Action Key somewhere within this paragraph 421 Here is an example. Depress the Action Key somewhere within this paragraph
414 and while holding it down, depress the Assist Key. Then release the keys in 422 and while holding it down, depress the Assist Key. Then release the keys in
415 any order and the help display will pop up. It explains that there was no 423 any order and the help display will pop up. It explains that there was no
416 particular matching Smart Key context, so a default operation is performed 424 particular matching Smart Key context, so a default operation is performed
417 (the value of the variable 'action-key-default-function' determines the 425 (the value of the variable `action-key-default-function' determines the
418 operation performed). 426 operation performed).
419 427
420 ** Scrolling to the Beginning and End of Buffers 428 ** Scrolling to the Beginning and End of Buffers
421 429
422 A left to right horizontal drag of the Action Key of 5 or more characters 430 A left to right horizontal drag of the Action Key of 5 or more characters