Mercurial > hg > xemacs-beta
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 |