Mercurial > hg > xemacs-beta

comparison lisp/hyperbole/DEMO @ 70:131b0175ea99 r20-0b30

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