Mercurial > emacs
comparison man/idlwave.texi @ 69826:84148ade703d
Updated docs for IDLWAVE version 6.0; see idlwave.org. Factor out
blocks not suitable for inclusion with Emacs using PARTOFEMACS variable.
author | J.D. Smith <jdsmith@as.arizona.edu> |
---|---|
date | Thu, 06 Apr 2006 18:56:09 +0000 |
parents | 11b616eddda4 |
children | 7b91d87287ef |
comparison
equal
deleted
inserted
replaced
69825:02e36d4a5f01 | 69826:84148ade703d |
---|---|
7 * IDLWAVE: (idlwave). Major mode and shell for IDL files. | 7 * IDLWAVE: (idlwave). Major mode and shell for IDL files. |
8 @end direntry | 8 @end direntry |
9 @synindex ky cp | 9 @synindex ky cp |
10 @syncodeindex vr cp | 10 @syncodeindex vr cp |
11 @syncodeindex fn cp | 11 @syncodeindex fn cp |
12 @set VERSION 5.5 | 12 @set VERSION 6.0 |
13 @set EDITION 5.5 | 13 @set EDITION 6.0 |
14 @set IDLVERSION 6.1 | 14 @set IDLVERSION 6.2 |
15 @set NSYSROUTINES 1850 | 15 @set NSYSROUTINES 1966 |
16 @set NSYSKEYWORDS 7685 | 16 @set DATE Feb, 2006 |
17 @set DATE March, 2005 | |
18 @set AUTHOR J.D. Smith & Carsten Dominik | 17 @set AUTHOR J.D. Smith & Carsten Dominik |
19 @set AUTHOR-EMAIL jdsmith@@as.arizona.edu | 18 @set AUTHOREMAIL jdsmith@@as.arizona.edu |
20 @set MAINTAINER J.D. Smith | 19 @set MAINTAINER J.D. Smith |
21 @set MAINTAINER-EMAIL jdsmith@@as.arizona.edu | 20 @set MAINTAINEREMAIL jdsmith@@as.arizona.edu |
21 @set PARTOFEMACS | |
22 @set IDLWAVEHOMEPAGE http://idlwave.org/ | |
22 @c %**end of header | 23 @c %**end of header |
23 @finalout | 24 @finalout |
24 | 25 |
25 @ifinfo | 26 @ifinfo |
26 This file documents IDLWAVE, a major mode for editing IDL files with | 27 This file documents IDLWAVE, a major mode for editing IDL files with |
27 Emacs, and interacting with an IDL shell run as a subprocess. | 28 Emacs, and interacting with an IDL shell run as a subprocess. |
28 | 29 |
29 This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE | 30 This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE |
30 @value{VERSION} | 31 @value{VERSION} |
31 | 32 |
32 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, | 33 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, |
33 2005, 2006 Free Software Foundation, Inc. | 34 2006 Free Software Foundation, Inc. |
34 | 35 |
35 Permission is granted to copy, distribute and/or modify this document | 36 Permission is granted to copy, distribute and/or modify this document |
36 under the terms of the GNU Free Documentation License, Version 1.2 or | 37 under the terms of the GNU Free Documentation License, Version 1.2 or |
37 any later version published by the Free Software Foundation; with no | 38 any later version published by the Free Software Foundation; with no |
38 Invariant Sections, with the Front-Cover texts being ``A GNU | 39 Invariant Sections, with the Front-Cover texts being ``A GNU |
58 @author by J.D. Smith & Carsten Dominik | 59 @author by J.D. Smith & Carsten Dominik |
59 @page | 60 @page |
60 This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for | 61 This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for |
61 IDLWAVE version @value{VERSION}, @value{DATE}. | 62 IDLWAVE version @value{VERSION}, @value{DATE}. |
62 @sp 2 | 63 @sp 2 |
63 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, | 64 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, |
64 2005, 2006 Free Software Foundation, Inc. | 65 2006 Free Software Foundation, Inc. |
65 @sp 2 | 66 @sp 2 |
66 @cindex Copyright, of IDLWAVE | 67 @cindex Copyright, of IDLWAVE |
67 Permission is granted to copy, distribute and/or modify this document | 68 Permission is granted to copy, distribute and/or modify this document |
68 under the terms of the GNU Free Documentation License, Version 1.2 or | 69 under the terms of the GNU Free Documentation License, Version 1.2 or |
69 any later version published by the Free Software Foundation; with no | 70 any later version published by the Free Software Foundation; with no |
98 * Introduction:: What IDLWAVE is, and what it is not | 99 * Introduction:: What IDLWAVE is, and what it is not |
99 * IDLWAVE in a Nutshell:: One page quick-start guide | 100 * IDLWAVE in a Nutshell:: One page quick-start guide |
100 * Getting Started:: Tutorial | 101 * Getting Started:: Tutorial |
101 * The IDLWAVE Major Mode:: The mode for editing IDL programs | 102 * The IDLWAVE Major Mode:: The mode for editing IDL programs |
102 * The IDLWAVE Shell:: The mode for running IDL as an inferior program | 103 * The IDLWAVE Shell:: The mode for running IDL as an inferior program |
104 @ifclear PARTOFEMACS | |
105 * Installation:: How to Install or Upgrade | |
106 @end ifclear | |
103 * Acknowledgements:: Who did what | 107 * Acknowledgements:: Who did what |
104 * Sources of Routine Info:: How does IDLWAVE know about routine XYZ | 108 * Sources of Routine Info:: How does IDLWAVE know about routine XYZ |
105 * HTML Help Browser Tips:: | 109 * HTML Help Browser Tips:: |
106 * Configuration Examples:: The user is king | 110 * Configuration Examples:: The user is king |
107 * Windows and MacOS:: What still works, and how | 111 * Windows and MacOS:: What still works, and how |
176 * Breakpoints and Stepping:: | 180 * Breakpoints and Stepping:: |
177 * Compiling Programs:: | 181 * Compiling Programs:: |
178 * Walking the Calling Stack:: | 182 * Walking the Calling Stack:: |
179 * Electric Debug Mode:: | 183 * Electric Debug Mode:: |
180 | 184 |
185 @ifclear PARTOFEMACS | |
186 Installation | |
187 | |
188 * Installing IDLWAVE:: How to install the distribution | |
189 * Installing Online Help:: Where to get the additional files needed | |
190 @end ifclear | |
191 | |
181 Sources of Routine Info | 192 Sources of Routine Info |
182 | 193 |
183 * Routine Definitions:: Where IDL Routines are defined. | 194 * Routine Definitions:: Where IDL Routines are defined. |
184 * Routine Information Sources:: So how does IDLWAVE know about... | 195 * Routine Information Sources:: So how does IDLWAVE know about... |
185 * Catalogs:: | 196 * Catalogs:: |
195 @end menu | 206 @end menu |
196 | 207 |
197 @node Introduction, IDLWAVE in a Nutshell, Top, Top | 208 @node Introduction, IDLWAVE in a Nutshell, Top, Top |
198 @chapter Introduction | 209 @chapter Introduction |
199 @cindex Introduction | 210 @cindex Introduction |
211 @cindex CORBA (Common Object Request Broker Architecture) | |
212 @cindex Interface Definition Language | |
200 @cindex Interactive Data Language | 213 @cindex Interactive Data Language |
201 @cindex cc-mode.el | 214 @cindex cc-mode.el |
202 @cindex @file{idl.el} | 215 @cindex @file{idl.el} |
203 @cindex @file{idl-shell.el} | 216 @cindex @file{idl-shell.el} |
204 @cindex Feature overview | 217 @cindex Feature overview |
205 | 218 |
206 IDLWAVE is a package which supports editing source files written in | 219 IDLWAVE is a package which supports editing source files written in |
207 the Interactive Data Language, and running | 220 the Interactive Data Language (IDL@c |
208 IDL as an inferior shell@footnote{Note that this package has nothing | 221 @ifclear PARTOFEMACS |
209 to do with the Interface Definition Language, part of the Common | 222 @footnote{IDL is a registered |
210 Object Request Broker Architecture (CORBA)}@footnote{IDLWAVE can also | 223 trademark of Research Systems, Inc.}@c |
211 be used for editing source files for the related WAVE/CL language, but | 224 @end ifclear |
212 with only limited support.}. It is a feature-rich replacement for the | 225 ), and running IDL as an inferior shell@footnote{IDLWAVE can also be used |
213 IDLDE development environment included with IDL, and uses the full | 226 for editing source files for the related WAVE/CL language, but with only |
214 power of Emacs to make editing and running IDL programs easier, | 227 limited support.}. It is a feature-rich replacement for the IDLDE |
215 quicker, and more structured. | 228 development environment included with IDL, and uses the full power of |
229 Emacs to make editing and running IDL programs easier, quicker, and more | |
230 structured. | |
216 | 231 |
217 IDLWAVE consists of two main parts: a major mode for editing IDL | 232 IDLWAVE consists of two main parts: a major mode for editing IDL |
218 source files (@code{idlwave-mode}) and a mode for running the IDL | 233 source files (@code{idlwave-mode}) and a mode for running the IDL |
219 program as an inferior shell (@code{idlwave-shell-mode}). Although | 234 program as an inferior shell (@code{idlwave-shell-mode}). Although |
220 one mode can be used without the other, both work together closely to | 235 one mode can be used without the other, both work together closely to |
229 @item | 244 @item |
230 Context-sensitive display of calling sequences and keywords for more | 245 Context-sensitive display of calling sequences and keywords for more |
231 than 1000 native IDL routines, extendible to any additional number of | 246 than 1000 native IDL routines, extendible to any additional number of |
232 local routines, and already available with many pre-scanned libraries. | 247 local routines, and already available with many pre-scanned libraries. |
233 @item | 248 @item |
234 Routine name space conflict search with likelihood-of-use ranking. | |
235 @item | |
236 Fast, context-sensitive online HTML help, or source-header help for | 249 Fast, context-sensitive online HTML help, or source-header help for |
237 undocumented routines. | 250 undocumented routines. |
238 @item | 251 @item |
239 Context sensitive completion of routine names, keywords, system | 252 Context sensitive completion of routine names, keywords, system |
240 variables, class names and much more. | 253 variables, class names and much more. |
243 @item | 256 @item |
244 Automatic corrections to enforce a variety of customizable coding | 257 Automatic corrections to enforce a variety of customizable coding |
245 standards. | 258 standards. |
246 @item | 259 @item |
247 Integrity checks and auto-termination of logical blocks. | 260 Integrity checks and auto-termination of logical blocks. |
261 @item | |
262 Routine name space conflict search with likelihood-of-use ranking. | |
248 @item | 263 @item |
249 Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). | 264 Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). |
250 @item | 265 @item |
251 Documentation support. | 266 Documentation support. |
252 @item | 267 @item |
253 Running IDL as an inferior Shell with history search, command line | 268 Running IDL as an inferior Shell with history search, command line |
254 editing and all the completion and routine info capabilities present in | 269 editing and all the completion and routine info capabilities present in |
255 IDL source buffers. | 270 IDL source buffers. |
271 @item | |
272 Full handling of debugging with breakpoints, with interactive setting | |
273 of break conditions, and easy stepping through code. | |
256 @item | 274 @item |
257 Compilation, execution and interactive single-keystroke debugging of | 275 Compilation, execution and interactive single-keystroke debugging of |
258 programs directly from the source buffer. | 276 programs directly from the source buffer. |
259 @item | 277 @item |
260 Quick, source-guided navigation of the calling stack, with variable | 278 Quick, source-guided navigation of the calling stack, with variable |
309 @multitable @columnfractions .15 .85 | 327 @multitable @columnfractions .15 .85 |
310 @item @key{TAB} | 328 @item @key{TAB} |
311 @tab Indent the current line relative to context. | 329 @tab Indent the current line relative to context. |
312 @item @kbd{C-M-\} | 330 @item @kbd{C-M-\} |
313 @tab Re-indent all lines in the current region. | 331 @tab Re-indent all lines in the current region. |
332 @item @kbd{C-M-q} | |
333 @tab Re-indent all lines in the current routine. | |
314 @item @kbd{C-u @key{TAB}} | 334 @item @kbd{C-u @key{TAB}} |
315 @tab Re-indent all lines in the current statement. | 335 @tab Re-indent all lines in the current statement. |
316 @item @kbd{M-@key{RET}} | 336 @item @kbd{M-@key{RET}} |
317 @tab Start a continuation line, or split the current line at point. | 337 @tab Start a continuation line, splitting the current line at point. |
318 @item @kbd{M-q} | 338 @item @kbd{M-q} |
319 @tab Fill the current comment paragraph. | 339 @tab Fill the current comment paragraph. |
320 @item @kbd{C-c ?} | 340 @item @kbd{C-c ?} |
321 @tab Display calling sequence and keywords for the procedure or function call | 341 @tab Display calling sequence and keywords for the procedure or function call |
322 at point. | 342 at point. |
338 | 358 |
339 @subheading Running the IDLWAVE Shell, Debugging Programs | 359 @subheading Running the IDLWAVE Shell, Debugging Programs |
340 | 360 |
341 @multitable @columnfractions .15 .85 | 361 @multitable @columnfractions .15 .85 |
342 @item @kbd{C-c C-s} | 362 @item @kbd{C-c C-s} |
343 @tab Start IDL as a subprocess and/or switch to the interaction buffer. | 363 @tab Start IDL as a subprocess and/or switch to the shell buffer. |
344 @item @kbd{M-p} | 364 @item @key{Up}, @kbd{M-p} |
345 @tab Cycle back through IDL command history. | 365 @tab Cycle back through IDL command history. |
346 @item @kbd{M-n} | 366 @item @key{Down},@kbd{M-n} |
347 @tab Cycle forward. | 367 @tab Cycle forward. |
348 @item @kbd{@key{TAB}} | 368 @item @kbd{@key{TAB}} |
349 @tab Complete a procedure name, function name or keyword in the shell buffer. | 369 @tab Complete a procedure name, function name or keyword in the shell buffer. |
350 @item @kbd{C-c C-d C-c} | 370 @item @kbd{C-c C-d C-c} |
351 @tab Save and compile the source file in the current buffer. | 371 @tab Save and compile the source file in the current buffer. |
366 @end multitable | 386 @end multitable |
367 | 387 |
368 @subheading Commonly used Settings in @file{.emacs} | 388 @subheading Commonly used Settings in @file{.emacs} |
369 @lisp | 389 @lisp |
370 ;; Change the indentation preferences | 390 ;; Change the indentation preferences |
371 (setq idlwave-main-block-indent 2 ; default 0 | |
372 idlwave-block-indent 2 ; default 4 | |
373 idlwave-end-offset -2) ; default -4 | |
374 ;; Start autoloading routine info after 2 idle seconds | 391 ;; Start autoloading routine info after 2 idle seconds |
375 (setq idlwave-init-rinfo-when-idle-after 2) | 392 (setq idlwave-init-rinfo-when-idle-after 2) |
376 ;; Pad some operators with spaces | 393 ;; Pad operators with spaces |
377 (setq idlwave-do-actions t | 394 (setq idlwave-do-actions t |
378 idlwave-surround-by-blank t) | 395 idlwave-surround-by-blank t) |
379 ;; Syntax Highlighting | 396 ;; Syntax Highlighting |
380 (add-hook 'idlwave-mode-hook 'turn-on-font-lock) | 397 (add-hook 'idlwave-mode-hook 'turn-on-font-lock) |
381 ;; Automatically start the shell when needed | 398 ;; Automatically start the shell when needed |
382 (setq idlwave-shell-automatic-start t) | 399 (setq idlwave-shell-automatic-start t) |
383 ;; Bind debugging commands with CONTROL and SHIFT modifiers | 400 ;; Bind debugging commands with CONTROL and SHIFT modifiers |
384 (setq idlwave-shell-debug-modifiers '(control shift)) | 401 (setq idlwave-shell-debug-modifiers '(control shift)) |
385 @end lisp | 402 @end lisp |
386 | 403 |
387 @ifhtml | 404 @html |
388 <A NAME="TUTORIAL"></A> | 405 <A NAME="TUTORIAL"></A> |
389 @end ifhtml | 406 @end html |
407 | |
390 @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top | 408 @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top |
391 @chapter Getting Started (Tutorial) | 409 @chapter Getting Started (Tutorial) |
392 @cindex Quick-Start | 410 @cindex Quick-Start |
393 @cindex Tutorial | 411 @cindex Tutorial |
394 @cindex Getting Started | 412 @cindex Getting Started |
409 that IDLWAVE has many more capabilities than covered here, which can | 427 that IDLWAVE has many more capabilities than covered here, which can |
410 be discovered by reading the entire manual, or hovering over the | 428 be discovered by reading the entire manual, or hovering over the |
411 shoulder of your nearest IDLWAVE guru for a few days. | 429 shoulder of your nearest IDLWAVE guru for a few days. |
412 | 430 |
413 It is assumed that you have access to Emacs or XEmacs with the full | 431 It is assumed that you have access to Emacs or XEmacs with the full |
414 IDLWAVE package including online help. We also assume that you are | 432 IDLWAVE package including online help@c |
415 familiar with Emacs and can read the nomenclature of key presses in | 433 @ifclear PARTOFEMACS |
416 Emacs (in particular, @kbd{C} stands for @key{CONTROL} and @kbd{M} for | 434 @ (@pxref{Installation})@c |
417 @key{META} (often the @key{ALT} key carries this functionality)). | 435 @end ifclear |
436 . We also assume that you are familiar with Emacs and can read the | |
437 nomenclature of key presses in Emacs (in particular, @kbd{C} stands | |
438 for @key{CONTROL} and @kbd{M} for @key{META} (often the @key{ALT} key | |
439 carries this functionality)). | |
418 | 440 |
419 Open a new source file by typing: | 441 Open a new source file by typing: |
420 | 442 |
421 @example | 443 @example |
422 @kbd{C-x C-f tutorial.pro @key{RET}} | 444 @kbd{C-x C-f tutorial.pro @key{RET}} |
488 there just as well as in a terminal, or the IDLDE. Use the arrow keys | 510 there just as well as in a terminal, or the IDLDE. Use the arrow keys |
489 to cycle through your command history. Are we having fun now? | 511 to cycle through your command history. Are we having fun now? |
490 | 512 |
491 Now go back to the source window and type @kbd{C-c C-d C-c} to compile | 513 Now go back to the source window and type @kbd{C-c C-d C-c} to compile |
492 the program. If you watch the shell buffer, you see that IDLWAVE types | 514 the program. If you watch the shell buffer, you see that IDLWAVE types |
493 @samp{.run tutorial.pro} for you. But the compilation fails because | 515 @samp{.run "tutorial.pro"} for you. But the compilation fails because |
494 there is a comma in the line @samp{years=...}. The line with the error | 516 there is a comma in the line @samp{years=...}. The line with the error |
495 is highlighted and the cursor positioned at the error, so remove the | 517 is highlighted and the cursor positioned at the error, so remove the |
496 comma (you should only need to hit @kbd{Delete}!). Compile again, using | 518 comma (you should only need to hit @kbd{Delete}!). Compile again, using |
497 the same keystrokes as before. Notice that the file is automatically | 519 the same keystrokes as before. Notice that the file is automatically |
498 saved for you. This time everything should work fine, and you should | 520 saved for you. This time everything should work fine, and you should |
546 | 568 |
547 @example | 569 @example |
548 plot_wday,1,4 | 570 plot_wday,1,4 |
549 @end example | 571 @end example |
550 | 572 |
551 Oops, this looks very wrong. All April fool's days cannot be Fridays! | 573 Oops, this looks very wrong. All April Fool's days cannot be Fridays! |
552 We've got a bug in the program, perhaps in the @code{daynr} function. | 574 We've got a bug in the program, perhaps in the @code{daynr} function. |
553 Let's put a breakpoint on the last line there. Position the cursor on | 575 Let's put a breakpoint on the last line there. Position the cursor on |
554 the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a | 576 the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a |
555 breakpoint (as you see in the shell window), and the break line is | 577 breakpoint (as you see in the shell window), and the break line is |
556 indicated. Back to the shell buffer, re-execute the previous command. | 578 indicated. Back to the shell buffer, re-execute the previous command. |
574 sequence of weekdays repeats. | 596 sequence of weekdays repeats. |
575 | 597 |
576 @node Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started | 598 @node Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started |
577 @section Lesson II: Customization | 599 @section Lesson II: Customization |
578 | 600 |
579 Emacs is probably the most customizable piece of software ever | 601 Emacs is probably the most customizable piece of software ever written, |
580 written, and it would be a shame if you did not make use of this and | 602 and it would be a shame if you did not make use of this to adapt IDLWAVE |
581 adapt IDLWAVE to your own preferences. Customizing Emacs or IDLWAVE | 603 to your own preferences. Customizing Emacs or IDLWAVE is accomplished |
582 is accomplished by setting Lisp variables in the @file{.emacs} file in | 604 by setting Lisp variables in the @file{.emacs} file in your home |
583 your home directory --- but do not be dismayed; for the most part, you | 605 directory --- but do not be dismayed; for the most part, you can just |
584 can just copy and work from the examples given here. | 606 copy and work from the examples given here. |
585 | 607 |
586 Let's first use a boolean variable. These are variables which you turn | 608 Let's first use a boolean variable. These are variables which you turn |
587 on or off, much like a checkbox. A value of @samp{t} means on, a value | 609 on or off, much like a checkbox. A value of @samp{t} means on, a value |
588 of @samp{nil} means off. Copy the following line into your | 610 of @samp{nil} means off. Copy the following line into your |
589 @file{.emacs} file, exit and restart Emacs. | 611 @file{.emacs} file, exit and restart Emacs. |
598 @samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this | 620 @samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this |
599 behavior, remove the option again from your @file{.emacs} file and | 621 behavior, remove the option again from your @file{.emacs} file and |
600 restart Emacs. | 622 restart Emacs. |
601 | 623 |
602 You likely have your own indentation preferences for IDL code. For | 624 You likely have your own indentation preferences for IDL code. For |
603 example, some like to indent the main block of an IDL program from the | 625 example, some may prefer to indent the main block of an IDL program |
604 margin and use only 3 spaces as indentation between @code{BEGIN} and | 626 slightly from the margin and use only 3 spaces as indentation between |
605 @code{END}. Try the following lines in @file{.emacs}: | 627 @code{BEGIN} and @code{END}. Try the following lines in @file{.emacs}: |
606 | 628 |
607 @lisp | 629 @lisp |
608 (setq idlwave-main-block-indent 2) | 630 (setq idlwave-main-block-indent 1) |
609 (setq idlwave-block-indent 3) | 631 (setq idlwave-block-indent 3) |
610 (setq idlwave-end-offset -3) | 632 (setq idlwave-end-offset -3) |
611 @end lisp | 633 @end lisp |
612 | 634 |
613 Restart Emacs, and re-indent the program we developed in the first part | 635 Restart Emacs, and re-indent the program we developed in the first part |
808 continuation lines. | 830 continuation lines. |
809 | 831 |
810 @cindex Foreign code, adapting | 832 @cindex Foreign code, adapting |
811 @cindex Indentation, of foreign code | 833 @cindex Indentation, of foreign code |
812 @kindex C-M-\ | 834 @kindex C-M-\ |
813 To re-indent a larger portion of code (e.g. when working with foreign code | 835 To re-indent a larger portion of code (e.g. when working with foreign |
814 written with different conventions), use @kbd{C-M-\} | 836 code written with different conventions), use @kbd{C-M-\} |
815 (@code{indent-region}) after marking the relevant code. Useful marking | 837 (@code{indent-region}) after marking the relevant code. Useful marking |
816 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the | 838 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current |
817 current subprogram). @xref{Actions}, for information how to impose | 839 subprogram). The command @kbd{C-M-q} reindents the entire current |
818 additional formatting conventions on foreign code. | 840 routine. @xref{Actions}, for information how to impose additional |
819 | 841 formatting conventions on foreign code. |
820 @defopt idlwave-main-block-indent (@code{0}) | 842 |
843 @defopt idlwave-main-block-indent (@code{2}) | |
821 Extra indentation for the main block of code. That is the block between | 844 Extra indentation for the main block of code. That is the block between |
822 the FUNCTION/PRO statement and the END statement for that program | 845 the FUNCTION/PRO statement and the END statement for that program |
823 unit. | 846 unit. |
824 @end defopt | 847 @end defopt |
825 | 848 |
826 @defopt idlwave-block-indent (@code{4}) | 849 @defopt idlwave-block-indent (@code{3}) |
827 Extra indentation applied to block lines. If you change this, you | 850 Extra indentation applied to block lines. If you change this, you |
828 probably also want to change @code{idlwave-end-offset}. | 851 probably also want to change @code{idlwave-end-offset}. |
829 @end defopt | 852 @end defopt |
830 | 853 |
831 @defopt idlwave-end-offset (@code{-4}) | 854 @defopt idlwave-end-offset (@code{-3}) |
832 Extra indentation applied to block END lines. A value equal to negative | 855 Extra indentation applied to block END lines. A value equal to negative |
833 @code{idlwave-block-indent} will make END lines line up with the block | 856 @code{idlwave-block-indent} will make END lines line up with the block |
834 BEGIN lines. | 857 BEGIN lines. |
835 @end defopt | 858 @end defopt |
836 | 859 |
882 | 905 |
883 Also, since the indentation level can be somewhat dynamic in continued | 906 Also, since the indentation level can be somewhat dynamic in continued |
884 statements with special continuation indentation, especially if | 907 statements with special continuation indentation, especially if |
885 @code{idlwave-max-extra-continuation-indent} is small, the key | 908 @code{idlwave-max-extra-continuation-indent} is small, the key |
886 @kbd{C-u @key{TAB}} will re-indent all lines in the current statement. | 909 @kbd{C-u @key{TAB}} will re-indent all lines in the current statement. |
887 Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil}, overrides | 910 Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil}, |
888 the @code{idlwave-max-extra-continuation-indent} limit, for | 911 overrides the @code{idlwave-max-extra-continuation-indent} limit, for |
889 parentheses only, forcing them always to line up. | 912 parentheses only, forcing them always to line up. |
890 | 913 |
891 | 914 |
892 @defopt idlwave-continuation-indent (@code{2}) | 915 @defopt idlwave-continuation-indent (@code{2}) |
893 Extra indentation applied to normal continuation lines. | 916 Extra indentation applied to normal continuation lines. |
1252 @defopt idlwave-rinfo-max-source-lines (@code{5}) | 1275 @defopt idlwave-rinfo-max-source-lines (@code{5}) |
1253 Maximum number of source files displayed in the Routine Info window. | 1276 Maximum number of source files displayed in the Routine Info window. |
1254 @end defopt | 1277 @end defopt |
1255 | 1278 |
1256 | 1279 |
1257 @ifhtml | 1280 @html |
1258 <A NAME="ONLINE_HELP"></A> | 1281 <A NAME="ONLINE_HELP"></A> |
1259 @end ifhtml | 1282 @end html |
1260 @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode | 1283 @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode |
1261 @section Online Help | 1284 @section Online Help |
1262 | 1285 |
1263 @cindex Online Help | 1286 @cindex Online Help |
1264 @cindex @file{idlw-help.txt} | 1287 @cindex @file{idlw-help.txt} |
1265 @cindex @file{idlw-help.el} | 1288 @cindex @file{idlw-help.el} |
1266 @cindex Installing online help | 1289 @cindex Installing online help |
1267 @cindex Online Help, Installation | 1290 @cindex Online Help, Installation |
1268 @cindex Speed, of online help | 1291 @cindex Speed, of online help |
1269 | 1292 @cindex XML Help Catalog |
1270 IDLWAVE can display help from an HTML version of the IDL documentation | 1293 |
1271 if it is available. This is @emph{much} faster than using the IDL | 1294 For IDL system routines, extensive documentation is supplied with IDL. |
1272 online help application, because IDLWAVE usually gets you to the right | 1295 IDLWAVE can access the HTML version of this documentation very quickly |
1273 place in the documentation directly --- e.g. a specific keyword of a | 1296 and accurately, based on the local context. This can be @emph{much} |
1274 routine --- without any additional browsing and scrolling. There are | 1297 faster than using the IDL online help application, because IDLWAVE |
1275 a variety of options for displaying the HTML help: see below. Help | 1298 usually gets you to the right place in the documentation directly --- |
1276 for routines without HTML documentation is also available, using the | 1299 e.g. a specific keyword of a routine --- without any additional browsing |
1277 routine documentation header and/or source. | 1300 and scrolling. |
1278 | 1301 |
1279 To make this feature work, you should set | 1302 For this online help to work, an HTML version of the IDL documentation |
1280 @code{idlwave-html-help-location} to the directory name of the | 1303 is required. Beginning with IDL 6.2, HTML documentation is distributed |
1281 directory where the IDL help files are installed. | 1304 directly with IDL, along with an XML-based catalog of routine |
1305 information. By default, IDLWAVE automatically attempts to convert this | |
1306 XML catalog into a format Emacs can more easily understand, and caches | |
1307 this information in your @code{idlwave_config_directory} | |
1308 (@file{~/.idlwave/}, by default). It also re-scans the XML catalog if | |
1309 it is newer than the current cached version. You can force rescan with | |
1310 the menu entry @code{IDLWAVE->Routine Info->Rescan XML Help Catalog}. | |
1311 | |
1312 Before IDL 6.2, the HTML help was not distributed with IDL, and was not | |
1313 part of the standalone IDLWAVE distribution, but had to be downloaded | |
1314 separately. This is no longer necessary: all help and routine | |
1315 information is supplied with IDL versions 6.2 and later. | |
1316 | |
1317 There are a variety of options for displaying the HTML help: see below. | |
1318 Help for routines without HTML documentation is also available, by using | |
1319 the routine documentation header and/or routine source. | |
1282 | 1320 |
1283 @kindex M-? | 1321 @kindex M-? |
1284 In any IDL program (or, as with most IDLWAVE commands, in the IDL | 1322 In any IDL program (or, as with most IDLWAVE commands, in the IDL |
1285 Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with | 1323 Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with |
1286 @kbd{S-Mouse-3} to access context sensitive online help. The following | 1324 @kbd{S-Mouse-3} to access context sensitive online help. The following |
1287 locations are recognized context for help: | 1325 locations are recognized context for help: |
1288 | 1326 |
1289 @cindex Context, for online help | 1327 @cindex Context, for online help |
1290 @multitable @columnfractions .25 .75 | 1328 @multitable @columnfractions .25 .75 |
1291 @item @i{Routine name} | 1329 @item @i{Routine names} |
1292 @tab The name of a routine (function, procedure, method). | 1330 @tab The name of a routine (function, procedure, method). |
1293 @item @i{Keyword Parameter} | 1331 @item @i{Keyword Parameters} |
1294 @tab A keyword parameter of a routine. | 1332 @tab A keyword parameter of a routine. |
1295 @item @i{System Variable} | 1333 @item @i{System Variables} |
1296 @tab System variables like @code{!DPI}. | 1334 @tab System variables like @code{!DPI}. |
1297 @item @i{System Variable Tags} | 1335 @item @i{System Variable Tags} |
1298 @tab System variables tags like @code{!D.X_SIZE}. | 1336 @tab System variables tags like @code{!D.X_SIZE}. |
1299 @item @i{IDL Statement} | 1337 @item @i{IDL Statements} |
1300 @tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. | 1338 @tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. |
1301 @item @i{Class name} | 1339 @item @i{IDL Controls} |
1340 @tab Control structures like @code{FOR}, @code{SWITCH}, etc. | |
1341 @item @i{Class names} | |
1302 @tab A class name in an @code{OBJ_NEW} call. | 1342 @tab A class name in an @code{OBJ_NEW} call. |
1303 @item @i{Class Init} | 1343 @item @i{Class Init Keywords} |
1304 @tab Beyond the class name in an @code{OBJ_NEW} call. | 1344 @tab Beyond the class name in an @code{OBJ_NEW} call. |
1305 @item @i{Executive Command} | 1345 @item @i{Executive Command} |
1306 @tab An executive command like @code{.RUN}. Mostly useful in the shell. | 1346 @tab An executive command like @code{.RUN}. Mostly useful in the shell. |
1307 @item @i{Structure Tags} | 1347 @item @i{Structure Tags} |
1308 @tab Structure tags like @code{state.xsize} | 1348 @tab Structure tags like @code{state.xsize} |
1350 @node Help with HTML Documentation, Help with Source, Online Help, Online Help | 1390 @node Help with HTML Documentation, Help with Source, Online Help, Online Help |
1351 @subsection Help with HTML Documentation | 1391 @subsection Help with HTML Documentation |
1352 @cindex HTML Help | 1392 @cindex HTML Help |
1353 @cindex Help using HTML manuals | 1393 @cindex Help using HTML manuals |
1354 @cindex IDL manual, HTML version | 1394 @cindex IDL manual, HTML version |
1395 @cindex IDL Assistant | |
1355 | 1396 |
1356 Help using the HTML documentation is invoked with the built-in Emacs | 1397 Help using the HTML documentation is invoked with the built-in Emacs |
1357 command @code{browse-url}, which displays the relevant help topic in a | 1398 command @code{browse-url}, which displays the relevant help topic in a |
1358 browser of your choosing. There are many possible browsers to choose | 1399 browser of your choosing. Beginning with version 6.2, IDL comes with |
1400 the help browser @emph{IDL Assistant}, which it uses by default for | |
1401 displaying online help on all supported platforms. This browser | |
1402 offers topical searches, an index, and is also now the default and | |
1403 recommended IDLWAVE help browser. The variable | |
1404 @code{idlwave-help-use-assistant} controls whether this browser is | |
1405 used. Note that, due to limitations in the Assistant, invoking help | |
1406 within IDLWAVE and @code{? topic} within IDL will result in two | |
1407 running copies of Assistant. | |
1408 | |
1409 Aside from the IDL Assistant, there are many possible browsers to choose | |
1359 among, with differing advantages and disadvantages. The variable | 1410 among, with differing advantages and disadvantages. The variable |
1360 @code{idlwave-help-browser-function} controls which browser help is | 1411 @code{idlwave-help-browser-function} controls which browser help is sent |
1361 sent to. This function is used to set the variable | 1412 to (as long as @code{idlwave-help-use-assistant} is not set). This |
1362 @code{browse-url-browser-function} locally for IDLWAVE help only. | 1413 function is used to set the variable @code{browse-url-browser-function} |
1363 Customize this variable to see what choices of browsers your system | 1414 locally for IDLWAVE help only. Customize the latter variable to see |
1364 offers. | 1415 what choices of browsers your system offers. Certain browsers like |
1365 | 1416 @code{w3} (bundled with many versions of Emacs) and @code{w3m} |
1366 Certain browsers like @code{w3} and @code{w3m} | 1417 (@uref{http://emacs-w3m.namazu.org/}) are run within Emacs, and use |
1367 (@uref{http://emacs-w3m.namazu.org/}, the author's help browser of | 1418 Emacs buffers to display the HTML help. This can be convenient, |
1368 choice) are run within Emacs, and use Emacs buffers to display the | 1419 especially on small displays, and images can even be displayed in-line |
1369 HTML help. This can be convenient, especially on small displays, and | 1420 on newer Emacs versions. However, better formatting results are often |
1370 images can even be displayed in-line on new Emacs versions. However, | 1421 achieved with external browsers, like Mozilla. IDLWAVE assumes any |
1371 better formatting results are often achieved with external browsers, | 1422 browser function containing "w3" is displayed in a local buffer. If you |
1372 like Mozilla. IDLWAVE assumes any browser function containing "w3" is | 1423 are using another Emacs-local browser for which this is not true, set |
1373 displayed in a local buffer. If you are using another Emacs-local | 1424 the variable @code{idlwave-help-browser-is-local}. |
1374 browser for which this is not true, set the variable | 1425 |
1375 @code{idlwave-help-browser-is-local}. | 1426 With IDL 6.2 or later, it is important to ensure that the variable |
1376 | 1427 @code{idlwave-system-directory} is set (@pxref{Catalogs}). One easy way |
1377 @emph{N.B. For Windows users}: IDLWAVE can bring up help directly | 1428 to ensure this is to run the IDL Shell (@kbd{C-c C-s}). It will be |
1378 from the Microsoft HTMLHelp documentation supplied with IDL: no | 1429 queried for this directory, and the results will be cached to file for |
1379 additional help files are needed. Be sure to set | 1430 subsequent use. |
1380 @code{idlwave-system-directory} and the help file will be found | |
1381 automatically (or, alternatively, specify its location directly with | |
1382 @code{idlwave-html-help-location}). The variable | |
1383 @code{idlwave-help-use-hh} controls whether HTMLHelp is used, and | |
1384 which application is called to invoke it (@code{HH} is the default). | |
1385 The free helper application @code{KEYHH} | |
1386 (@uref{http://www.keyworks.net/keyhh.htm}) can be used instead, and is | |
1387 preferrable, as it permits loading new help topics into the same help | |
1388 window. @code{KEYHH} must be downloaded and installed separately. | |
1389 | 1431 |
1390 @xref{HTML Help Browser Tips}, for more information on selecting and | 1432 @xref{HTML Help Browser Tips}, for more information on selecting and |
1391 configuring a browser for use with IDL's HTML help system. | 1433 configuring a browser for use with IDL's HTML help system. |
1392 | 1434 |
1393 @defopt idlwave-html-help-location @file{/usr/local/etc} | 1435 @defopt idlwave-html-system-help-location @file{help/online_help} |
1394 The directory where the @file{idl_html_help} dir or @file{idl.chm} | 1436 Relative directory of the system-supplied HTML help directory, |
1395 HTMLHelp files live. | 1437 considered with respect to @code{idlwave-system-directory}. Relevant |
1396 @end defopt | 1438 for IDL 6.2 and greater. Should not change. |
1397 | 1439 @end defopt |
1398 @defopt idlwave-help-use-hh @code{nil} | 1440 |
1399 If set to @code{'hh} or @code{'keyhh}, use Windows native HTMLHelp | 1441 @defopt idlwave-html-help-location @file{/usr/local/etc/} |
1400 with the specified help application. | 1442 The directory where the @file{idl_html_help} HTML directory live. |
1443 Obsolete and ignored for IDL 6.2 and greater | |
1444 (@code{idlwave-html-system-help-location} is used instead). | |
1445 @end defopt | |
1446 | |
1447 @defopt idlwave-help-use-assistant @code{t} | |
1448 If set, use the IDL Assistant if possible for online HTML help, | |
1449 otherwise use the browser function specified in | |
1450 @code{idlwave-help-browser-function}. | |
1401 @end defopt | 1451 @end defopt |
1402 | 1452 |
1403 @defopt idlwave-help-browser-function | 1453 @defopt idlwave-help-browser-function |
1404 The browser function to use to display IDLWAVE HTML help. Should be | 1454 The browser function to use to display IDLWAVE HTML help. Should be |
1405 one of the functions available for setting | 1455 one of the functions available for setting |
1406 @code{browse-url-browser-function}, which see. | 1456 @code{browse-url-browser-function}, which see. |
1407 @end defopt | 1457 @end defopt |
1408 | 1458 |
1409 @defopt idlwave-help-browser-is-local | 1459 @defopt idlwave-help-browser-is-local |
1410 Is the browser selected in @code{idlwave-help-browser-function} run in a | 1460 Is the browser selected in @code{idlwave-help-browser-function} run in a |
1411 local Emacs buffer? Defaults to @code{t} if the function contains | 1461 local Emacs buffer or window? Defaults to @code{t} if the function |
1412 "-w3". | 1462 contains "-w3". |
1413 @end defopt | 1463 @end defopt |
1414 | 1464 |
1415 @defopt idlwave-help-link-face | 1465 @defopt idlwave-help-link-face |
1416 The face for links to IDLWAVE online help. | 1466 The face for links to IDLWAVE online help. |
1417 @end defopt | 1467 @end defopt |
1515 | 1565 |
1516 @kindex M-@key{TAB} | 1566 @kindex M-@key{TAB} |
1517 @kindex C-c C-i | 1567 @kindex C-c C-i |
1518 IDLWAVE offers completion for class names, routine names, keywords, | 1568 IDLWAVE offers completion for class names, routine names, keywords, |
1519 system variables, system variable tags, class structure tags, regular | 1569 system variables, system variable tags, class structure tags, regular |
1520 structure tags and file names. As in many programming modes, | 1570 structure tags and file names. As in many programming modes, completion |
1521 completion is bound to @kbd{M-@key{TAB}} (or @kbd{@key{TAB}} in the | 1571 is bound to @kbd{M-@key{TAB}} (or simply @kbd{@key{TAB}} in the IDLWAVE |
1522 IDLWAVE Shell --- @pxref{Using the Shell}). Completion uses exactly | 1572 Shell --- @pxref{Using the Shell}). Completion uses exactly the same |
1523 the same internal information as routine info, so when necessary | 1573 internal information as routine info, so when necessary (rarely) it can |
1524 (rarely) it can be updated with @kbd{C-c C-i} | 1574 be updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}). |
1525 (@code{idlwave-update-routine-info}). | |
1526 | 1575 |
1527 The completion function is context sensitive and figures out what to | 1576 The completion function is context sensitive and figures out what to |
1528 complete based location of the point. Here are example lines and what | 1577 complete based on the location of the point. Here are example lines and |
1529 @kbd{M-@key{TAB}} would try to complete when the cursor is on the | 1578 what @kbd{M-@key{TAB}} would try to complete when the cursor is on the |
1530 position marked with a @samp{_}: | 1579 position marked with a @samp{_}: |
1531 | 1580 |
1532 @example | 1581 @example |
1533 plo_ @r{Procedure} | 1582 plo_ @r{Procedure} |
1534 x = a_ @r{Function} | 1583 x = a_ @r{Function} |
1535 plot,xra_ @r{Keyword of @code{plot} procedure} | 1584 plot,xra_ @r{Keyword of @code{plot} procedure} |
1536 plot,x,y,/x_ @r{Keyword of @code{plot} procedure} | 1585 plot,x,y,/x_ @r{Keyword of @code{plot} procedure} |
1537 plot,min(_ @r{Keyword of @code{min} function} | 1586 plot,min(_ @r{Keyword of @code{min} function} |
1538 obj -> a_ @r{Object method (procedure)} | 1587 obj -> a_ @r{Object method (procedure)} |
1539 a(2,3) = obj -> a_ @r{Object method (function)} | 1588 a[2,3] = obj -> a_ @r{Object method (function)} |
1540 x = obj_new('IDL_ @r{Class name} | 1589 x = obj_new('IDL_ @r{Class name} |
1541 x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}} | 1590 x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}} |
1542 pro A_ @r{Class name} | 1591 pro A_ @r{Class name} |
1543 pro _ @r{Fill in @code{Class::} of first method in this file} | 1592 pro _ @r{Fill in @code{Class::} of first method in this file} |
1544 !v_ @r{System variable} | 1593 !v_ @r{System variable} |
1653 @subsection Object Method Completion and Class Ambiguity | 1702 @subsection Object Method Completion and Class Ambiguity |
1654 @cindex Object methods | 1703 @cindex Object methods |
1655 @cindex Class ambiguity | 1704 @cindex Class ambiguity |
1656 @cindex @code{self} object, default class | 1705 @cindex @code{self} object, default class |
1657 An object method is not uniquely determined without the object's class. | 1706 An object method is not uniquely determined without the object's class. |
1658 Since the class is almost always omitted in the calling source, IDLWAVE | 1707 Since the class is almost always omitted in the calling source (as |
1659 considers all available methods in all classes as possible method name | 1708 required to obtain the true benefits of object-based programming), |
1660 completions. The combined list of keywords of the current method in | 1709 IDLWAVE considers all available methods in all classes as possible |
1661 @emph{all} known classes which contain that method will be considered | 1710 method name completions. The combined list of keywords of the current |
1662 for keyword completion. In the @file{*Completions*} buffer, the | 1711 method in @emph{all} known classes which contain that method will be |
1663 matching classes will be shown next to each item (see option | 1712 considered for keyword completion. In the @file{*Completions*} buffer, |
1713 the matching classes will be shown next to each item (see option | |
1664 @code{idlwave-completion-show-classes}). As a special case, the class | 1714 @code{idlwave-completion-show-classes}). As a special case, the class |
1665 of an object called @samp{self} is always taken to be the class of the | 1715 of an object called @samp{self} is always taken to be the class of the |
1666 current routine. All classes it inherits from are considered as well | 1716 current routine, when in an IDLWAVE buffer. All inherits classes are |
1667 where appropriate. | 1717 considered as well. |
1668 | 1718 |
1669 @cindex Forcing class query. | 1719 @cindex Forcing class query. |
1670 @cindex Class query, forcing | 1720 @cindex Class query, forcing |
1671 You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u | 1721 You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u |
1672 M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to | 1722 M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to |
1673 narrow down the number of possible completions. The variable | 1723 narrow down the number of possible completions. The variable |
1674 @code{idlwave-query-class} can be configured to make such prompting the | 1724 @code{idlwave-query-class} can be configured to make such prompting the |
1675 default for all methods (not recommended), or selectively for very | 1725 default for all methods (not recommended), or selectively for very |
1676 common methods for which the number of completing keywords would be too | 1726 common methods for which the number of completing keywords would be too |
1677 large (e.g. @code{Init}). | 1727 large (e.g. @code{Init,SetProperty,GetProperty}). |
1678 | 1728 |
1679 @cindex Saving object class on @code{->} | 1729 @cindex Saving object class on @code{->} |
1680 @cindex @code{->} | 1730 @cindex @code{->} |
1681 After you have specified the class for a particular statement (e.g. when | 1731 After you have specified the class for a particular statement (e.g. when |
1682 completing the method), IDLWAVE can remember it for the rest of the | 1732 completing the method), IDLWAVE can remember it for the rest of the |
1683 editing session. Subsequent completions in the same statement | 1733 editing session. Subsequent completions in the same statement |
1684 (e.g. keywords) can then reuse this class information. This works by | 1734 (e.g. keywords) can then reuse this class information. This works by |
1685 placing a text property on the method invocation operator @samp{->}, | 1735 placing a text property on the method invocation operator @samp{->}, |
1686 after which the operator will be shown in a different face. This is not | 1736 after which the operator will be shown in a different face (bold by |
1687 enabled by default --- the variable @code{idlwave-store-inquired-class} | 1737 default). The variable @code{idlwave-store-inquired-class} can be used |
1688 can be used to turn it on. | 1738 to turn it off or on. |
1689 | 1739 |
1690 @defopt idlwave-completion-show-classes (@code{1}) | 1740 @defopt idlwave-completion-show-classes (@code{1}) |
1691 Non-@code{nil} means show up to that many classes in | 1741 Non-@code{nil} means show up to that many classes in |
1692 @file{*Completions*} buffer when completing object methods and | 1742 @file{*Completions*} buffer when completing object methods and |
1693 keywords. | 1743 keywords. |
1699 | 1749 |
1700 @defopt idlwave-query-class (@code{nil}) | 1750 @defopt idlwave-query-class (@code{nil}) |
1701 Association list governing query for object classes during completion. | 1751 Association list governing query for object classes during completion. |
1702 @end defopt | 1752 @end defopt |
1703 | 1753 |
1704 @defopt idlwave-store-inquired-class (@code{nil}) | 1754 @defopt idlwave-store-inquired-class (@code{t}) |
1705 Non-@code{nil} means store class of a method call as text property on | 1755 Non-@code{nil} means store class of a method call as text property on |
1706 @samp{->}. | 1756 @samp{->}. |
1707 @end defopt | 1757 @end defopt |
1708 | 1758 |
1709 @defopt idlwave-class-arrow-face | 1759 @defopt idlwave-class-arrow-face |
1710 Face to highlight object operator arrows @samp{->} which carry a class | 1760 Face to highlight object operator arrows @samp{->} which carry a saved |
1711 text property. | 1761 class text property. |
1712 @end defopt | 1762 @end defopt |
1713 | 1763 |
1714 @node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion | 1764 @node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion |
1715 @subsection Object Method Completion in the Shell | 1765 @subsection Object Method Completion in the Shell |
1716 @cindex Method Completion in Shell | 1766 @cindex Method Completion in Shell |
1720 @code{obj_class()} function). In the Shell, when attempting completion, | 1770 @code{obj_class()} function). In the Shell, when attempting completion, |
1721 routine info, or online help within a method routine, a query is sent to | 1771 routine info, or online help within a method routine, a query is sent to |
1722 determine the class of the object. If this query is successful, the | 1772 determine the class of the object. If this query is successful, the |
1723 class found will be used to select appropriate completions, routine | 1773 class found will be used to select appropriate completions, routine |
1724 info, or help. If unsuccessful, information from all known classes will | 1774 info, or help. If unsuccessful, information from all known classes will |
1725 be used (as in the buffer). Setting the variable | 1775 be used (as in the buffer). |
1726 @code{idlwave-store-inquired-class} can eliminate unnecessary repetitive | |
1727 queries for the object's class, and speed up completion. | |
1728 | 1776 |
1729 @node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion | 1777 @node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion |
1730 @subsection Class and Keyword Inheritance | 1778 @subsection Class and Keyword Inheritance |
1731 @cindex Inheritance, class | 1779 @cindex Inheritance, class |
1732 @cindex Keyword inheritance | 1780 @cindex Keyword inheritance |
1800 (add-hook 'idlwave-load-hook | 1848 (add-hook 'idlwave-load-hook |
1801 (lambda () (require 'idlw-complete-structtag))) | 1849 (lambda () (require 'idlw-complete-structtag))) |
1802 @end lisp | 1850 @end lisp |
1803 | 1851 |
1804 Once enabled, you'll also be able to access online help on the structure | 1852 Once enabled, you'll also be able to access online help on the structure |
1805 tags, using the usual methods (@pxref{Online Help}). | 1853 tags, using the usual methods (@pxref{Online Help}). In addition, |
1854 structure variables in the shell will be queried for tag names, similar | |
1855 to the way object variables in the shell are queried for method names. | |
1856 So, e.g.: | |
1857 | |
1858 @example | |
1859 IDL> st.[Tab] | |
1860 @end example | |
1861 | |
1862 @noindent will complete with all structure fields of the structure | |
1863 @code{st}. | |
1806 | 1864 |
1807 @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode | 1865 @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode |
1808 @section Routine Source | 1866 @section Routine Source |
1809 @cindex Routine source file | 1867 @cindex Routine source file |
1810 @cindex Module source file | 1868 @cindex Module source file |
1815 routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks | 1873 routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks |
1816 for a module name, offering the same default as | 1874 for a module name, offering the same default as |
1817 @code{idlwave-routine-info} would have used, taken from nearby buffer | 1875 @code{idlwave-routine-info} would have used, taken from nearby buffer |
1818 contents. In the minibuffer, specify a complete routine name (including | 1876 contents. In the minibuffer, specify a complete routine name (including |
1819 any class part). IDLWAVE will display the source file in another | 1877 any class part). IDLWAVE will display the source file in another |
1820 window, positioned at the routine in question. You can also visit a | 1878 window, positioned at the routine in question. You can also limit this |
1821 routine in the current buffer, with completion, by using a single prefix | 1879 to a routine in the current buffer only, with completion, and a |
1822 (@kbd{C-u C-c C-v}). | 1880 context-sensitive default, by using a single prefix (@kbd{C-u C-c C-v}) |
1881 or the convenience binding @kbd{C-c C-t}. | |
1823 | 1882 |
1824 @cindex Buffers, killing | 1883 @cindex Buffers, killing |
1825 @cindex Killing autoloaded buffers | 1884 @cindex Killing autoloaded buffers |
1826 Since getting the source of a routine into a buffer is so easy with | 1885 Since getting the source of a routine into a buffer is so easy with |
1827 IDLWAVE, too many buffers visiting different IDL source files are | 1886 IDLWAVE, too many buffers visiting different IDL source files are |
1836 @cindex Routines, resolving | 1895 @cindex Routines, resolving |
1837 | 1896 |
1838 The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve} | 1897 The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve} |
1839 and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL | 1898 and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL |
1840 in order to resolve (compile) it. The default routine to be resolved is | 1899 in order to resolve (compile) it. The default routine to be resolved is |
1841 taken from context, but you get a chance to edit it. | 1900 taken from context, but you get a chance to edit it. Usually this is |
1901 not necessary, since IDL automatically discovers routines on its path. | |
1842 | 1902 |
1843 @code{idlwave-resolve} is one way to get a library module within reach | 1903 @code{idlwave-resolve} is one way to get a library module within reach |
1844 of IDLWAVE's routine info collecting functions. A better way is to | 1904 of IDLWAVE's routine info collecting functions. A better way is to |
1845 keep routine information available in catalogs (@pxref{Catalogs}). | 1905 keep routine information available in catalogs (@pxref{Catalogs}). |
1846 Routine info on modules will then be available without the need to | 1906 Routine info on modules will then be available without the need to |
1981 @tab @code{openw,} | 2041 @tab @code{openw,} |
1982 @item @code{\p} | 2042 @item @code{\p} |
1983 @tab @code{print,} | 2043 @tab @code{print,} |
1984 @item @code{\pt} | 2044 @item @code{\pt} |
1985 @tab @code{plot,} | 2045 @tab @code{plot,} |
2046 @item @code{\pv} | |
2047 @tab @code{ptr_valid()} | |
1986 @item @code{\re} | 2048 @item @code{\re} |
1987 @tab @code{read,} | 2049 @tab @code{read,} |
1988 @item @code{\rf} | 2050 @item @code{\rf} |
1989 @tab @code{readf,} | 2051 @tab @code{readf,} |
1990 @item @code{\rt} | 2052 @item @code{\rt} |
2142 @cindex Operators, padding with spaces | 2204 @cindex Operators, padding with spaces |
2143 @cindex Space, around operators | 2205 @cindex Space, around operators |
2144 | 2206 |
2145 Some operators can be automatically surrounded by spaces. This can | 2207 Some operators can be automatically surrounded by spaces. This can |
2146 happen when the operator is typed, or later when the line is indented. | 2208 happen when the operator is typed, or later when the line is indented. |
2147 IDLWAVE can pad the operators @samp{&}, @samp{<}, @samp{>}, @samp{,}, | 2209 IDLWAVE can pad the operators @samp{<}, @samp{>}, @samp{,}, @samp{=}, |
2148 @samp{=}, and @samp{->}, but this feature is turned off by default. If | 2210 and @samp{->}, as well as the modified assignment operators |
2149 you want to turn it on, customize the variables | 2211 (@samp{AND=}, @samp{OR=}, etc.). This feature is turned off by default. |
2150 @code{idlwave-surround-by-blank} and @code{idlwave-do-actions}. You can | 2212 If you want to turn it on, customize the variables |
2151 also define similar actions for other operators by using the function | 2213 @code{idlwave-surround-by-blank} and @code{idlwave-do-actions} and turn |
2152 @code{idlwave-action-and-binding} in the mode hook. For example, to | 2214 both on. You can also define similar actions for other operators by |
2153 enforce space padding of the @samp{+} and @samp{*} operators, try this | 2215 using the function @code{idlwave-action-and-binding} in the mode hook. |
2154 in @file{.emacs} | 2216 For example, to enforce space padding of the @samp{+} and @samp{*} |
2217 operators (outside of strings and comments, of course), try this in | |
2218 @file{.emacs} | |
2155 | 2219 |
2156 @lisp | 2220 @lisp |
2157 (add-hook 'idlwave-mode-hook | 2221 (add-hook 'idlwave-mode-hook |
2158 (lambda () | 2222 (lambda () |
2159 (setq idlwave-surround-by-blank t) ; Turn this type of actions on | 2223 (setq idlwave-surround-by-blank t) ; Turn this type of actions on |
2160 (idlwave-action-and-binding "*" '(idlwave-surround 1 1)) | 2224 (idlwave-action-and-binding "*" '(idlwave-surround 1 1)) |
2161 (idlwave-action-and-binding "+" '(idlwave-surround 1 1)))) | 2225 (idlwave-action-and-binding "+" '(idlwave-surround 1 1)))) |
2162 @end lisp | 2226 @end lisp |
2163 | 2227 |
2228 Note that the modified assignment operators which begin with a word | |
2229 (@samp{AND=}, @samp{OR=}, @samp{NOT=}, etc.) require a leading space to | |
2230 be recognized (e.g @code{vAND=4} would be intepreted as a variable | |
2231 @code{vAND}). Also note that, since e.g., @code{>} and @code{>=} are | |
2232 both valid operators, it is impossible to surround both by blanks while | |
2233 they are being typed. Similarly with @code{&} and @code{&&}. For | |
2234 these, a compromise is made: the padding is placed on the left, and if | |
2235 the longer operator is keyed in, on the right as well (otherwise you | |
2236 must insert spaces to pad right yourself, or press simply press Tab to | |
2237 repad everything if @code{idlwave-do-actions} is on). | |
2238 | |
2164 @defopt idlwave-surround-by-blank (@code{nil}) | 2239 @defopt idlwave-surround-by-blank (@code{nil}) |
2165 Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil}, | 2240 Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil}, |
2166 @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are | 2241 @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->}, and the |
2242 modified assignment operators (@samp{AND=}, @samp{OR=}, etc.) are | |
2167 surrounded with spaces by @code{idlwave-surround}. | 2243 surrounded with spaces by @code{idlwave-surround}. |
2168 @end defopt | 2244 @end defopt |
2169 | 2245 |
2170 @defopt idlwave-pad-keyword (@code{t}) | 2246 @defopt idlwave-pad-keyword (@code{t}) |
2171 Non-@code{nil} means pad @samp{=} for keywords like assignments. | 2247 Non-@code{nil} means space-pad the @samp{=} in keyword assignments. |
2172 @end defopt | 2248 @end defopt |
2173 | 2249 |
2174 @node Case Changes, , Padding Operators, Actions | 2250 @node Case Changes, , Padding Operators, Actions |
2175 @subsection Case Changes | 2251 @subsection Case Changes |
2176 @cindex Case changes | 2252 @cindex Case changes |
2326 | 2402 |
2327 @defopt idlwave-load-hook | 2403 @defopt idlwave-load-hook |
2328 Normal hook. Executed when @file{idlwave.el} is loaded. | 2404 Normal hook. Executed when @file{idlwave.el} is loaded. |
2329 @end defopt | 2405 @end defopt |
2330 | 2406 |
2331 | 2407 @ifset PARTOFEMACS |
2332 | |
2333 @node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top | 2408 @node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top |
2409 @end ifset | |
2410 | |
2411 @ifclear PARTOFEMACS | |
2412 @node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top | |
2413 @end ifclear | |
2414 | |
2334 @chapter The IDLWAVE Shell | 2415 @chapter The IDLWAVE Shell |
2335 @cindex IDLWAVE shell | 2416 @cindex IDLWAVE shell |
2336 @cindex Major mode, @code{idlwave-shell-mode} | 2417 @cindex Major mode, @code{idlwave-shell-mode} |
2337 @cindex IDL, as Emacs subprocess | 2418 @cindex IDL, as Emacs subprocess |
2338 @cindex Subprocess of Emacs, IDL | 2419 @cindex Subprocess of Emacs, IDL |
2344 program as an inferior process of Emacs, and works closely with the | 2425 program as an inferior process of Emacs, and works closely with the |
2345 IDLWAVE major mode in buffers. It can be used to work with IDL | 2426 IDLWAVE major mode in buffers. It can be used to work with IDL |
2346 interactively, to compile and run IDL programs in Emacs buffers and to | 2427 interactively, to compile and run IDL programs in Emacs buffers and to |
2347 debug these programs. The IDLWAVE shell is built on @file{comint}, an | 2428 debug these programs. The IDLWAVE shell is built on @file{comint}, an |
2348 Emacs packages which handles the communication with the IDL program. | 2429 Emacs packages which handles the communication with the IDL program. |
2349 Unfortunately IDL for Windows does not have command-prompt versions | 2430 Unfortunately, IDL for Windows does not have command-prompt versions and |
2350 and thus do not allow the interaction with Emacs@footnote{Please | 2431 thus do not allow the interaction with Emacs --- so the IDLWAVE shell |
2351 inform the maintainer if you come up with a way to make the IDLWAVE | 2432 currently only works under Unix and MacOSX. |
2352 shell work on these systems.} --- so the IDLWAVE shell currently only | |
2353 works under Unix and MacOSX. | |
2354 | 2433 |
2355 @menu | 2434 @menu |
2356 * Starting the Shell:: How to launch IDL as a subprocess | 2435 * Starting the Shell:: How to launch IDL as a subprocess |
2357 * Using the Shell:: Interactively working with the Shell | 2436 * Using the Shell:: Interactively working with the Shell |
2358 * Commands Sent to the Shell:: | 2437 * Commands Sent to the Shell:: |
2444 @end defopt | 2523 @end defopt |
2445 | 2524 |
2446 @defopt idlwave-shell-use-dedicated-frame (@code{nil}) | 2525 @defopt idlwave-shell-use-dedicated-frame (@code{nil}) |
2447 Non-@code{nil} means IDLWAVE should use a special frame to display the | 2526 Non-@code{nil} means IDLWAVE should use a special frame to display the |
2448 shell buffer. | 2527 shell buffer. |
2528 @end defopt | |
2529 | |
2530 @defopt idlwave-shell-use-dedicated-window (@code{nil}) | |
2531 Non-@code{nil} means use a dedicated window for the shell, taking care | |
2532 not it replace it with other buffers. | |
2449 @end defopt | 2533 @end defopt |
2450 | 2534 |
2451 @defopt idlwave-shell-frame-parameters | 2535 @defopt idlwave-shell-frame-parameters |
2452 The frame parameters for a dedicated idlwave-shell frame. | 2536 The frame parameters for a dedicated idlwave-shell frame. |
2453 @end defopt | 2537 @end defopt |
2537 @item @kbd{C-c C-i} | 2621 @item @kbd{C-c C-i} |
2538 @tab Update routine info from buffers and shell | 2622 @tab Update routine info from buffers and shell |
2539 (@code{idlwave-update-routine-info}) | 2623 (@code{idlwave-update-routine-info}) |
2540 @item @kbd{C-c C-v} | 2624 @item @kbd{C-c C-v} |
2541 @tab Find the source file of a routine (@code{idlwave-find-module}) | 2625 @tab Find the source file of a routine (@code{idlwave-find-module}) |
2626 @item @kbd{C-c C-t} | |
2627 @tab Find the source file of a routine in the currently visited file | |
2628 (@code{idlwave-find-module-this-file}). | |
2542 @item @kbd{C-c =} | 2629 @item @kbd{C-c =} |
2543 @tab Compile a library routine (@code{idlwave-resolve}) | 2630 @tab Compile a library routine (@code{idlwave-resolve}) |
2544 @end multitable | 2631 @end multitable |
2545 | 2632 |
2546 @defopt idlwave-shell-arrows-do-history (@code{t}) | 2633 @defopt idlwave-shell-arrows-do-history (@code{t}) |
2758 stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d | 2845 stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d |
2759 C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled | 2846 C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled |
2760 and re-enabled: @kbd{C-c C-d C-\} | 2847 and re-enabled: @kbd{C-c C-d C-\} |
2761 (@code{idlwave-shell-toggle-enable-current-bp}). | 2848 (@code{idlwave-shell-toggle-enable-current-bp}). |
2762 | 2849 |
2763 | 2850 Breakpoint lines are highlighted or indicated with an icon in the source |
2764 Breakpoint lines are highlighted or indicated with an icon in the | 2851 code (different icons for conditional, after, and other break types). |
2765 source code (different icons for conditional, after, and other break | 2852 Disabled breakpoints are @emph{grayed out} by default. Note that IDL |
2766 types). Disabled breakpoints are @emph{grayed out} by default. Note | 2853 places breakpoints as close as possible on or after the line you |
2767 that IDL places breakpoints as close as possible on or after the line | 2854 specify. IDLWAVE queries the shell for the actual breakpoint location |
2768 you specify. IDLWAVE queries the shell for the actual breakpoint | 2855 which was set, so the exact line you specify may not be marked. You can |
2769 location which was set, so the exact line you specify may not be | 2856 re-sync the breakpoint list and update the display at any time (e.g., if |
2770 marked. You can re-sync the breakpoint list and display at any time | 2857 you add or remove some on the command line) using @kbd{C-c C-d C-l}. |
2771 (e.g., if you add or remove some on the command line) using @kbd{C-c | 2858 |
2772 C-d C-l}. | 2859 In recent IDLWAVE versions, the breakpoint line is highlighted when the |
2860 mouse is moved over it, and a tooltip pops up describing the break | |
2861 details. @kbd{Mouse-3} on the breakpoint line pops up a menu of | |
2862 breakpoint actions, including clearing, disabling, and adding or | |
2863 changing break conditions or ``after'' break count. | |
2773 | 2864 |
2774 Once the program has stopped somewhere, you can step through it. The | 2865 Once the program has stopped somewhere, you can step through it. The |
2775 most important stepping commands are @kbd{C-c C-d C-s} to execute one | 2866 most important stepping commands are @kbd{C-c C-d C-s} to execute one |
2776 line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line, | 2867 line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line, |
2777 treating procedure and function calls as a single step ("step over"); | 2868 treating procedure and function calls as a single step ("step over"); |
2783 | 2874 |
2784 @multitable @columnfractions .23 .77 | 2875 @multitable @columnfractions .23 .77 |
2785 @item @kbd{C-c C-d C-b} | 2876 @item @kbd{C-c C-d C-b} |
2786 @tab Set breakpoint (@code{idlwave-shell-break-here}) | 2877 @tab Set breakpoint (@code{idlwave-shell-break-here}) |
2787 @item @kbd{C-c C-d C-i} | 2878 @item @kbd{C-c C-d C-i} |
2788 @tab Set breakpoint in function named here (@code{idlwave-shell-break-in}) | 2879 @tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) |
2789 @item @kbd{C-c C-d C-d} | 2880 @item @kbd{C-c C-d C-d} |
2790 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) | 2881 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) |
2791 @item @kbd{C-c C-d C-a} | 2882 @item @kbd{C-c C-d C-a} |
2792 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) | 2883 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) |
2793 @item @kbd{C-c C-d [} | 2884 @item @kbd{C-c C-d [} |
2819 @item @kbd{C-c C-d C-down} | 2910 @item @kbd{C-c C-d C-down} |
2820 @tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) | 2911 @tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) |
2821 @end multitable | 2912 @end multitable |
2822 | 2913 |
2823 All of these commands have equivalents in Electric Debug Mode, which | 2914 All of these commands have equivalents in Electric Debug Mode, which |
2824 provides faster access (@pxref{Electric Debug Mode}). | 2915 provides faster single-key access (@pxref{Electric Debug Mode}). |
2916 | |
2917 The line where IDL is currently stopped, at breakpoints, halts, and | |
2918 errors, etc., is marked with a color overlay or arrow, depending on the | |
2919 setting in @code{idlwave-shell-mark-stop-line}. If an overlay face is | |
2920 used to mark the stop line (as it is by default), when stepping through | |
2921 code, the face color is temporarily changed to gray, until IDL completes | |
2922 the next command and moves to the new line. | |
2825 | 2923 |
2826 @defopt idlwave-shell-mark-breakpoints (@code{t}) | 2924 @defopt idlwave-shell-mark-breakpoints (@code{t}) |
2827 Non-@code{nil} means mark breakpoints in the source file buffers. The | 2925 Non-@code{nil} means mark breakpoints in the source file buffers. The |
2828 value indicates the preferred method. Valid values are @code{nil}, | 2926 value indicates the preferred method. Valid values are @code{nil}, |
2829 @code{t}, @code{face}, and @code{glyph}. | 2927 @code{t}, @code{face}, and @code{glyph}. |
2831 | 2929 |
2832 @defopt idlwave-shell-breakpoint-face | 2930 @defopt idlwave-shell-breakpoint-face |
2833 The face for breakpoint lines in the source code if | 2931 The face for breakpoint lines in the source code if |
2834 @code{idlwave-shell-mark-breakpoints} has the value @code{face}. | 2932 @code{idlwave-shell-mark-breakpoints} has the value @code{face}. |
2835 @end defopt | 2933 @end defopt |
2934 | |
2935 @defopt idlwave-shell-breakpoint-popup-menu (@code{t}) | |
2936 Whether to pop-up a menu and present a tooltip description on | |
2937 breakpoint lines. | |
2938 @end defopt | |
2939 | |
2940 @defopt idlwave-shell-mark-stop-line (@code{t}) | |
2941 Non-@code{nil} means mark the source code line where IDL is currently | |
2942 stopped. The value specifies the preferred method. Valid values are | |
2943 @code{nil}, @code{t}, @code{arrow}, and @code{face}. | |
2944 @end defopt | |
2945 | |
2946 @defopt idlwave-shell-overlay-arrow (@code{">"}) | |
2947 The overlay arrow to display at source lines where execution halts, if | |
2948 configured in @code{idlwave-shell-mark-stop-line}. | |
2949 @end defopt | |
2950 | |
2951 @defopt idlwave-shell-stop-line-face | |
2952 The face which highlights the source line where IDL is stopped, if | |
2953 configured in @code{idlwave-shell-mark-stop-line}. | |
2954 @end defopt | |
2955 | |
2836 | 2956 |
2837 @node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs | 2957 @node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs |
2838 @subsection Compiling Programs | 2958 @subsection Compiling Programs |
2839 @cindex Compiling programs | 2959 @cindex Compiling programs |
2840 @cindex Programs, compiling | 2960 @cindex Programs, compiling |
2857 default command line is send to the shell. To edit the default command | 2977 default command line is send to the shell. To edit the default command |
2858 line, call @code{idlwave-shell-execute-default-command-line} with a | 2978 line, call @code{idlwave-shell-execute-default-command-line} with a |
2859 prefix argument: @kbd{C-u C-c C-d C-y}. If no default command line has | 2979 prefix argument: @kbd{C-u C-c C-d C-y}. If no default command line has |
2860 been set (or you give two prefix arguments), the last command on the | 2980 been set (or you give two prefix arguments), the last command on the |
2861 @code{comint} input history is sent. | 2981 @code{comint} input history is sent. |
2862 | |
2863 @defopt idlwave-shell-mark-stop-line (@code{t}) | |
2864 Non-@code{nil} means mark the source code line where IDL is currently | |
2865 stopped. The value specifies the preferred method. Valid values are | |
2866 @code{nil}, @code{t}, @code{arrow}, and @code{face}. | |
2867 @end defopt | |
2868 | |
2869 @defopt idlwave-shell-overlay-arrow (@code{">"}) | |
2870 The overlay arrow to display at source lines where execution halts, if | |
2871 configured in @code{idlwave-shell-mark-stop-line}. | |
2872 @end defopt | |
2873 | |
2874 @defopt idlwave-shell-stop-line-face | |
2875 The face which highlights the source line where IDL is stopped, if | |
2876 configured in @code{idlwave-shell-mark-stop-line}. | |
2877 @end defopt | |
2878 | 2982 |
2879 @node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs | 2983 @node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs |
2880 @subsection Walking the Calling Stack | 2984 @subsection Walking the Calling Stack |
2881 @cindex Calling stack, walking | 2985 @cindex Calling stack, walking |
2882 | 2986 |
2893 will be highlighted. If you continue execution, IDLWAVE will | 2997 will be highlighted. If you continue execution, IDLWAVE will |
2894 automatically return to the current level. @xref{Examining Variables}, | 2998 automatically return to the current level. @xref{Examining Variables}, |
2895 for information how to examine the value of variables and expressions on | 2999 for information how to examine the value of variables and expressions on |
2896 higher calling stack levels. | 3000 higher calling stack levels. |
2897 | 3001 |
2898 @ifhtml | 3002 @html |
2899 <A NAME="EDEBUG"></A> | 3003 <A NAME="EDEBUG"></A> |
2900 @end ifhtml | 3004 @end html |
2901 @node Electric Debug Mode, , Walking the Calling Stack, Debugging IDL Programs | 3005 @node Electric Debug Mode, , Walking the Calling Stack, Debugging IDL Programs |
2902 @subsection Electric Debug Mode | 3006 @subsection Electric Debug Mode |
2903 @cindex Electric Debug Mode | 3007 @cindex Electric Debug Mode |
2904 @cindex @samp{*Debugging*} | 3008 @cindex @samp{*Debugging*} |
2905 | 3009 |
2906 Even with a convenient debug key prefix enabled, repetitive stepping, | 3010 Even with a convenient debug key prefix enabled, repetitive stepping, |
2907 variable examination (@pxref{Examining Variables}), and other | 3011 variable examination (@pxref{Examining Variables}), and other debugging |
2908 debugging activities can be awkward and slow using commands which | 3012 activities can be awkward and slow using commands which require multiple |
2909 require multiple keystrokes. Luckily, there's a better way, inspired | 3013 keystrokes. Luckily, there's a better way, inspired by the lisp e-debug |
2910 by the lisp e-debug mode, and available through the @emph{Electric | 3014 mode, and available through the @emph{Electric Debug Mode}. By default, |
2911 Debug Mode}. By default, as soon as a breakpoint is hit, this minor | 3015 as soon as a breakpoint is hit, this minor mode is enabled. The buffer |
2912 mode is enabled. The buffer showing the line where execution has | 3016 showing the line where execution has halted is switched to Electric |
2913 halted is switched to Electric Debug Mode. This mode is visible as | 3017 Debug Mode. This mode is visible as @samp{*Debugging*} in the mode |
2914 @samp{*Debugging*} in the mode line, and a different face (violet by | 3018 line, and a different face (violet by default, if color is available) |
2915 default, where color is available) for the line stopped at point. The | 3019 for the line stopped at point. The buffer is made read-only and |
2916 buffer is made read-only and single-character bindings for the most | 3020 single-character bindings for the most commonly used debugging commands |
2917 commonly used debugging commands are enabled: | 3021 are enabled. These character commands (a list of which is available |
3022 with @kbd{C-?}) are: | |
2918 | 3023 |
2919 @multitable @columnfractions .2 .8 | 3024 @multitable @columnfractions .2 .8 |
2920 @item @kbd{a} | 3025 @item @kbd{a} |
2921 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) | 3026 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) |
2922 @item @kbd{b} | 3027 @item @kbd{b} |
2923 @tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here}) | 3028 @tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here}) |
2924 @item @kbd{d} | 3029 @item @kbd{d} |
2925 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) | 3030 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) |
3031 @item @kbd{e} | |
3032 @tab Prompt for expression to print (@code{idlwave-shell-clear-current-bp}). | |
2926 @item @kbd{h} | 3033 @item @kbd{h} |
2927 @tab Continue to the line at cursor position (@code{idlwave-shell-to-here}) | 3034 @tab Continue to the line at cursor position (@code{idlwave-shell-to-here}) |
2928 @item @kbd{i} | 3035 @item @kbd{i} |
2929 @tab Set breakpoint in function named here (@code{idlwave-shell-break-in}) | 3036 @tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) |
2930 @item @kbd{[} | 3037 @item @kbd{[} |
2931 @tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp}) | 3038 @tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp}) |
2932 @item @kbd{]} | 3039 @item @kbd{]} |
2933 @tab Go to the next breakpoint in the file | 3040 @tab Go to the next breakpoint in the file |
2934 (@code{idlwave-shell-goto-next-bp}) | 3041 (@code{idlwave-shell-goto-next-bp}) |
2976 @tab Show help on the commands available. | 3083 @tab Show help on the commands available. |
2977 @end multitable | 3084 @end multitable |
2978 | 3085 |
2979 Most single-character electric debug bindings use the final keystroke | 3086 Most single-character electric debug bindings use the final keystroke |
2980 of the equivalent multiple key commands (which are of course also | 3087 of the equivalent multiple key commands (which are of course also |
2981 still available), but some differ (e.g. @kbd{t},@kbd{q},@kbd{x}). | 3088 still available), but some differ (e.g. @kbd{e},@kbd{t},@kbd{q},@kbd{x}). |
2982 Some have additional convenience bindings (like @kbd{@key{SPACE}} for | 3089 Some have additional convenience bindings (like @kbd{@key{SPACE}} for |
2983 stepping). All prefix and other argument options described in this | 3090 stepping). All prefix and other argument options described in this |
2984 section for the commands invoked by electric debug bindings are still | 3091 section for the commands invoked by electric debug bindings are still |
2985 valid. For example, @kbd{C-u b} sets a conditional breakpoint, just | 3092 valid. For example, @kbd{C-u b} sets a conditional breakpoint, just |
2986 as it did with @kbd{C-u C-c C-d C-b}. | 3093 as it did with @kbd{C-u C-c C-d C-b}. |
3012 @code{t} for both breakpoints and errors, this can be | 3119 @code{t} for both breakpoints and errors, this can be |
3013 @code{'breakpoint} (the default) to enable it only at breakpoint | 3120 @code{'breakpoint} (the default) to enable it only at breakpoint |
3014 halts. | 3121 halts. |
3015 @end defopt | 3122 @end defopt |
3016 | 3123 |
3124 @defopt idlwave-shell-electric-stop-color (Violet) | |
3125 Default color of the stopped line overlay when in electric debug mode. | |
3126 @end defopt | |
3127 | |
3128 @defopt idlwave-shell-electric-stop-line-face | |
3129 The face to use for the stopped line. Defaults to a face similar to the | |
3130 modeline, with color @code{idlwave-shell-electric-stop-color}. | |
3131 @end defopt | |
3132 | |
3017 @defopt idlwave-shell-electric-zap-to-file (@code{t}) | 3133 @defopt idlwave-shell-electric-zap-to-file (@code{t}) |
3018 If set, when entering electric debug mode, select the window displaying | 3134 If set, when entering electric debug mode, select the window displaying |
3019 the file where point is stopped. This takes point away from the shell | 3135 the file where point is stopped. This takes point away from the shell |
3020 window, but is useful for immediate stepping, etc. | 3136 window, but is useful for immediate stepping, etc. |
3021 @end defopt | 3137 @end defopt |
3022 | 3138 |
3023 @ifhtml | 3139 @html |
3024 <A NAME="EXAMINE"></A> | 3140 <A NAME="EXAMINE"></A> |
3025 @end ifhtml | 3141 @end html |
3026 @node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell | 3142 @node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell |
3027 @section Examining Variables | 3143 @section Examining Variables |
3028 @cindex @code{PRINT} expressions | 3144 @cindex @code{PRINT} expressions |
3029 @cindex @code{HELP}, on expressions | 3145 @cindex @code{HELP}, on expressions |
3030 @cindex Expressions, printing & help | 3146 @cindex Expressions, printing & help |
3031 @cindex Examining expressions | 3147 @cindex Examining expressions |
3032 @cindex Printing expressions | 3148 @cindex Printing expressions |
3033 @cindex Mouse binding to print expressions | 3149 @cindex Mouse binding to print expressions |
3034 | 3150 |
3035 @kindex C-c C-d C-p | 3151 @kindex C-c C-d C-p |
3036 Do you find yourself repeatedly typing, | 3152 Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)}, |
3037 e.g. @code{print,n_elements(x)}, and similar statements to remind | 3153 and similar statements to remind yourself of the |
3038 yourself of the type/size/structure/value/etc. of variables and | 3154 type/size/structure/value/etc. of variables and expressions in your code |
3039 expressions in your code or at the command line? IDLWAVE has a suite | 3155 or at the command line? IDLWAVE has a suite of special commands to |
3040 of special commands to automate these types of variable or expression | 3156 automate these types of variable or expression examinations. They work |
3041 examinations. They work by sending statements to the shell formatted | 3157 by sending statements to the shell formatted to include the indicated |
3042 to include the indicated expression. | 3158 expression, and can be accessed in several ways. |
3043 | 3159 |
3044 These examination commands can be used in the shell or buffer at any | 3160 These @emph{examine} commands can be used in the shell or buffer at any |
3045 time (as long as the shell is running), and are very useful when | 3161 time (as long as the shell is running), and are very useful when |
3046 execution is stopped in a buffer due to a triggered breakpoint or error, | 3162 execution is stopped in a buffer due to a triggered breakpoint or error, |
3047 or while composing a long command in the IDLWAVE shell. In the latter | 3163 or while composing a long command in the IDLWAVE shell. In the latter |
3048 case, the command is sent to the shell and its output is visible, but | 3164 case, the command is sent to the shell and its output is visible, but |
3049 point remains unmoved in the command being composed --- you can inspect | 3165 point remains unmoved in the command being composed --- you can inspect |
3053 variable, number, or function you see can be examined. | 3169 variable, number, or function you see can be examined. |
3054 | 3170 |
3055 If the variable @code{idlwave-shell-separate-examine-output} is | 3171 If the variable @code{idlwave-shell-separate-examine-output} is |
3056 non-@code{nil} (the default), all examine output will be sent to a | 3172 non-@code{nil} (the default), all examine output will be sent to a |
3057 special @file{*Examine*} buffer, rather than the shell. The output of | 3173 special @file{*Examine*} buffer, rather than the shell. The output of |
3058 prior examine commands is saved. In this buffer @key{c} clears the | 3174 prior examine commands is saved in this buffer. In this buffer @key{c} |
3059 contents, and @key{q} hides the buffer. | 3175 clears the contents, and @key{q} hides the buffer. |
3060 | 3176 |
3061 The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to | 3177 The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to |
3062 print the expression at point, and @kbd{C-c C-d ?}, to invoke help on | 3178 print the expression at point, and @kbd{C-c C-d ?}, to invoke help on |
3063 this expression@footnote{Available as @kbd{p} and @kbd{?} in Electric | 3179 this expression@footnote{Available as @kbd{p} and @kbd{?} in Electric |
3064 Debug Mode (@pxref{Electric Debug Mode})}. The expression at point is | 3180 Debug Mode (@pxref{Electric Debug Mode})}. The expression at point is |
3065 either an array expression or a function call, or the contents of a | 3181 either an array expression or a function call, or the contents of a pair |
3066 pair of parentheses. The selected expression is highlighted, and | 3182 of parentheses. The chosen expression is highlighted, and |
3067 simultaneously the resulting output is highlighted in the shell. | 3183 simultaneously the resulting output is highlighted in the shell or |
3068 Calling the above commands with a prefix argument will use the current | 3184 separate output buffer. Calling the above commands with a prefix |
3069 region as expression instead of using the one at point. Two prefix | 3185 argument will use the current region as expression instead of using the |
3070 arguments (@kbd{C-u C-u C-c C-d C-p}) will prompt for an expression. | 3186 one at point. which can be useful for examining complicated, multi-line |
3187 expressions. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will | |
3188 prompt for an expression to print directly. By default, when invoking | |
3189 print, only an initial portion of long arrays will be printed, up to | |
3190 @code{idlwave-shell-max-print-length}. | |
3071 | 3191 |
3072 For added speed and convenience, there are mouse bindings which allow | 3192 For added speed and convenience, there are mouse bindings which allow |
3073 you to click on expressions and examine their values. Use | 3193 you to click on expressions and examine their values. Use |
3074 @kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke | 3194 @kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke |
3075 help (i.e. you need to hold down @key{META} and @key{CONTROL} while | 3195 help (i.e. you need to hold down @key{META} and @key{CONTROL} while |
3117 @end defopt | 3237 @end defopt |
3118 | 3238 |
3119 @defopt idlwave-shell-separate-examine-output (@code{t}) | 3239 @defopt idlwave-shell-separate-examine-output (@code{t}) |
3120 If non-@code{nil}, re-direct the output of examine commands to a special | 3240 If non-@code{nil}, re-direct the output of examine commands to a special |
3121 @file{*Examine*} buffer, instead of in the shell itself. | 3241 @file{*Examine*} buffer, instead of in the shell itself. |
3242 @end defopt | |
3243 | |
3244 @defopt idlwave-shell-max-print-length (200) | |
3245 The maximum number of leading array entries to print, when examining | |
3246 array expressions. | |
3122 @end defopt | 3247 @end defopt |
3123 | 3248 |
3124 @node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell | 3249 @node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell |
3125 @section Custom Expression Examination | 3250 @section Custom Expression Examination |
3126 @cindex Expressions, custom examination | 3251 @cindex Expressions, custom examination |
3190 examine command strings to send, after all instances of @code{___} | 3315 examine command strings to send, after all instances of @code{___} |
3191 (three underscores) are replaced by the indicated expression. | 3316 (three underscores) are replaced by the indicated expression. |
3192 @end defopt | 3317 @end defopt |
3193 | 3318 |
3194 | 3319 |
3320 @ifclear PARTOFEMACS | |
3321 @node Installation, Acknowledgements, The IDLWAVE Shell, Top | |
3322 @chapter Installation | |
3323 @cindex Installation | |
3324 | |
3325 @menu | |
3326 * Installing IDLWAVE:: How to install the distribution | |
3327 * Installing Online Help:: Where to get the additional files needed | |
3328 @end menu | |
3329 | |
3330 @node Installing IDLWAVE, Installing Online Help, Installation, Installation | |
3331 @section Installing IDLWAVE | |
3332 | |
3333 @cindex FTP site | |
3334 @cindex URL, homepage for IDLWAVE | |
3335 @cindex Homepage for IDLWAVE | |
3336 @cindex IDLWAVE, homepage | |
3337 @cindex XEmacs package IDLWAVE | |
3338 @cindex Emacs, distributed with IDLWAVE | |
3339 IDLWAVE is part of Emacs 21.1 and later. It is also an XEmacs package | |
3340 and can be installed from | |
3341 @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site} | |
3342 with the normal package management system on XEmacs 21. You can also | |
3343 download IDLWAVE and install it yourself from | |
3344 @uref{@value{IDLWAVEHOMEPAGE}, the maintainers webpage}. Follow the | |
3345 instructions in the INSTALL file. | |
3346 | |
3347 @node Installing Online Help, , Installing IDLWAVE, Installation | |
3348 @section Installing Online Help | |
3349 @cindex Installing online help | |
3350 @cindex Online Help, Installation | |
3351 | |
3352 Starting with IDL v6.2, all necessary online help files and routine | |
3353 information are distributed directly with IDL. Nothing additional is | |
3354 required. | |
3355 | |
3356 For version of IDL prior to 6.2 (and IDLWAVE prior to version 6.0), if | |
3357 you want to use the online help display, an additional set of files | |
3358 (HTML versions of the IDL documentation) must be installed. These files | |
3359 can also be downloaded from @uref{@value{IDLWAVEHOMEPAGE}, the | |
3360 maintainers webpage}. You need to place the files somewhere on your | |
3361 system and tell IDLWAVE where they are with: | |
3362 | |
3363 @lisp | |
3364 ; e.g. /usr/local/etc/ | |
3365 (setq idlwave-html-help-location "/path/to/help/dir/") | |
3366 @end lisp | |
3367 | |
3368 @noindent The default location is @file{/usr/local/etc}, and if you | |
3369 install the directory there, you do not need to set this variable. Note | |
3370 that the help package only changes with new versions of the IDL | |
3371 documentation, and need not be updated unless your version of IDL | |
3372 changes. Since the help system is distributed with IDL starting at | |
3373 version 6.2, no new help packages will be created for these versions. | |
3374 | |
3375 @node Acknowledgements, Sources of Routine Info, Installation, Top | |
3376 @end ifclear | |
3377 | |
3378 @ifset PARTOFEMACS | |
3195 @node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top | 3379 @node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top |
3380 @end ifset | |
3381 | |
3196 @chapter Acknowledgements | 3382 @chapter Acknowledgements |
3197 @cindex Acknowledgements | 3383 @cindex Acknowledgements |
3198 @cindex Maintainer, of IDLWAVE | 3384 @cindex Maintainer, of IDLWAVE |
3199 @cindex Authors, of IDLWAVE | 3385 @cindex Authors, of IDLWAVE |
3200 @cindex Contributors, to IDLWAVE | 3386 @cindex Contributors, to IDLWAVE |
3217 manual. | 3403 manual. |
3218 | 3404 |
3219 @item | 3405 @item |
3220 @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current | 3406 @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current |
3221 maintainer, as of version 4.10, helped shape object method completion | 3407 maintainer, as of version 4.10, helped shape object method completion |
3222 and most new features introduced in versions 4.x, and added | 3408 and most new features introduced in versions 4.x, and introduced many |
3223 significant new capabilities for versions 5.x. | 3409 new features for IDLWAVE versions 5.x and 6.x. |
3224 @end itemize | 3410 @end itemize |
3225 | 3411 |
3226 @noindent | 3412 @noindent |
3227 The following people have also contributed to the development of IDLWAVE | 3413 The following people have also contributed to the development of IDLWAVE |
3228 with patches, ideas, bug reports and suggestions. | 3414 with patches, ideas, bug reports and suggestions. |
3261 @item | 3447 @item |
3262 Phil Sterne <sterne__at__dublin.llnl.gov> | 3448 Phil Sterne <sterne__at__dublin.llnl.gov> |
3263 @item | 3449 @item |
3264 Paul Sorenson <aardvark62__at__msn.com> | 3450 Paul Sorenson <aardvark62__at__msn.com> |
3265 @end itemize | 3451 @end itemize |
3452 | |
3453 Doug Dirks was instrumental in providing the crucial IDL XML catalog to | |
3454 support HTML help with IDL v6.2 and later, and Ali Bahrami provided | |
3455 scripts and documentation to interface with the IDL Assistant. | |
3266 | 3456 |
3267 @noindent | 3457 @noindent |
3268 Thanks to everyone! | 3458 Thanks to everyone! |
3269 | 3459 |
3270 @node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top | 3460 @node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top |
3296 @noindent Routines which can be used in an IDL program can be defined in | 3486 @noindent Routines which can be used in an IDL program can be defined in |
3297 several places: | 3487 several places: |
3298 | 3488 |
3299 @enumerate | 3489 @enumerate |
3300 @item | 3490 @item |
3301 @emph{Builtin routines} are defined inside IDL itself. The source | 3491 @emph{Builtin routines} are defined inside IDL itself. The source code |
3302 code of such routines is not available. | 3492 of such routines is not available, but instead are learned about through |
3493 the IDL documentation. | |
3303 @item | 3494 @item |
3304 Routines which are @emph{part of the current program}, are defined in a | 3495 Routines which are @emph{part of the current program}, are defined in a |
3305 file explicitly compiled by the user. This file may or may not be | 3496 file explicitly compiled by the user. This file may or may not be |
3306 located on the IDL search path. | 3497 located on the IDL search path. |
3307 @item | 3498 @item |
3308 @emph{Library routines} are defined in files located on IDL's search | 3499 @emph{Library routines} are defined in files located on IDL's search |
3309 path, and will not need to be manually compiled. When a library routine | 3500 path. When a library routine is called for the first time, IDL will |
3310 is called for the first time, IDL will find the source file and compile | 3501 find the source file and compile it dynamically. A special sub-category |
3311 it dynamically. A special sub-category of library routines are the | 3502 of library routines are the @emph{system routines} distributed with IDL, |
3312 @emph{system routines} distributed with IDL, and usually available in | 3503 and usually available in the @file{lib} subdirectory of the IDL |
3313 the @file{lib} subdirectory of the IDL distribution. | 3504 distribution. |
3314 @item | 3505 @item |
3315 External routines written in other languages (like Fortran or C) can be | 3506 External routines written in other languages (like Fortran or C) can be |
3316 called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, | 3507 called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, |
3317 or included as dynamically loaded modules (DLMs). Currently IDLWAVE | 3508 or included as dynamically loaded modules (DLMs). Currently IDLWAVE |
3318 cannot provide routine info and completion for such external routines. | 3509 cannot provide routine info and completion for such external routines, |
3510 except by querying the Shell for calling information (DLMs only). | |
3319 @end enumerate | 3511 @end enumerate |
3320 | 3512 |
3321 @node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info | 3513 @node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info |
3322 @appendixsec Routine Information Sources | 3514 @appendixsec Routine Information Sources |
3323 @cindex Routine info sources | 3515 @cindex Routine info sources |
3333 @enumerate | 3525 @enumerate |
3334 | 3526 |
3335 @item | 3527 @item |
3336 It has a @emph{builtin list} with information about the routines IDL | 3528 It has a @emph{builtin list} with information about the routines IDL |
3337 ships with. IDLWAVE @value{VERSION} is distributed with a list of | 3529 ships with. IDLWAVE @value{VERSION} is distributed with a list of |
3338 @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords, | 3530 @value{NSYSROUTINES} routines, reflecting IDL version |
3339 reflecting IDL version @value{IDLVERSION}. This list has been created | 3531 @value{IDLVERSION}. As of IDL v6.2, the routine info is distributed |
3340 by scanning the IDL manuals and is stored in the file | 3532 directly with IDL in the form of an XML catalog which IDLWAVE scans. |
3341 @file{idlw-rinfo.el}. @xref{Documentation Scan}, for information on | 3533 Formerly, this list was created by scanning the IDL manuals to produce |
3342 how to regenerate this file for new versions of IDL. | 3534 the file @file{idlw-rinfo.el}. |
3343 | 3535 |
3344 @item | 3536 @item |
3345 It @emph{scans} all @emph{buffers} of the current Emacs session for | 3537 IDLWAVE @emph{scans} all its @emph{buffers} in the current Emacs session |
3346 routine definitions. This is done automatically when routine | 3538 for routine definitions. This is done automatically when routine |
3347 information or completion is first requested by the user. Each new | 3539 information or completion is first requested by the user. Each new |
3348 buffer and each buffer saved after making changes is also scanned. The | 3540 buffer and each buffer saved after making changes is also scanned. The |
3349 command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used | 3541 command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used |
3350 at any time to rescan all buffers. | 3542 at any time to rescan all buffers. |
3351 | 3543 |
3352 @item | 3544 @item |
3353 If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will | 3545 If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will |
3354 @emph{query the shell} for compiled routines and their arguments. This | 3546 @emph{query the shell} for compiled routines and their arguments. This |
3355 happens automatically when routine information or completion is first | 3547 happens automatically when routine information or completion is first |
3356 requested by the user, and each time an Emacs buffer is compiled with | 3548 requested by the user. Each time an Emacs buffer is compiled with |
3357 @kbd{C-c C-d C-c}. Though rarely necessary, the command @kbd{C-c C-i} | 3549 @kbd{C-c C-d C-c}, the routine info for that file is queried. Though |
3358 (@code{idlwave-update-routine-info}) can be used to update the shell | 3550 rarely necessary, the command @kbd{C-c C-i} |
3359 routine data. | 3551 (@code{idlwave-update-routine-info}) can be used to explicitly update |
3360 | 3552 the shell routine data. |
3361 @item | 3553 |
3362 Many popular libraries are distributed with routine information | 3554 @item |
3363 already scanned into @emph{library catalogs} (@pxref{Library | 3555 Many popular libraries are distributed with routine information already |
3364 Catalogs}). These per-directory catalog files can also be built by | 3556 scanned into @emph{library catalogs} (@pxref{Library Catalogs}). These |
3365 the user with the supplied @file{idlwave_catalog} tool. | 3557 per-directory catalog files can also be built by the user with the |
3558 supplied @file{idlwave_catalog} tool. They are automatically discovered | |
3559 by IDLWAVE. | |
3366 | 3560 |
3367 @item | 3561 @item |
3368 IDLWAVE can scan selected directories of source files and store the | 3562 IDLWAVE can scan selected directories of source files and store the |
3369 result in a single @emph{user catalog} file which will be | 3563 result in a single @emph{user catalog} file which will be |
3370 automatically loaded just like @file{idlw-rinfo.el}. @xref{User | 3564 automatically loaded just like @file{idlw-rinfo.el}. @xref{User |
3371 Catalog}, for information on how to scan files in this way. | 3565 Catalog}, for information on how to scan files in this way. |
3372 @end enumerate | 3566 @end enumerate |
3373 | 3567 |
3374 Loading routine and catalog information can be a time consuming process, | 3568 Loading all the routine and catalog information can be a time consuming |
3375 especially over slow networks. Depending on the system and network | 3569 process, especially over slow networks. Depending on the system and |
3376 configuration it could take up to 30 seconds. In order to minimize the | 3570 network configuration it could take up to 30 seconds (though locally on |
3571 fast systems is usually only a few seconds). In order to minimize the | |
3377 wait time upon your first completion or routine info command in a | 3572 wait time upon your first completion or routine info command in a |
3378 session, IDLWAVE uses Emacs idle time to do the initialization in six | 3573 session, IDLWAVE uses Emacs idle time to do the initialization in six |
3379 steps, yielding to user input in between. If this gets into your way, | 3574 steps, yielding to user input in between. If this gets into your way, |
3380 set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero). | 3575 set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero). |
3381 The more routines documented in library and user catalogs, the slower | 3576 The more routines documented in library and user catalogs, the slower |
3397 | 3592 |
3398 @defopt idlwave-auto-routine-info-updates | 3593 @defopt idlwave-auto-routine-info-updates |
3399 Controls under what circumstances routine info is updated automatically. | 3594 Controls under what circumstances routine info is updated automatically. |
3400 @end defopt | 3595 @end defopt |
3401 | 3596 |
3402 @ifhtml | 3597 @html |
3403 <A NAME="CATALOGS"></A> | 3598 <A NAME="CATALOGS"></A> |
3404 @end ifhtml | 3599 @end html |
3405 @node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info | 3600 @node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info |
3406 @appendixsec Catalogs | 3601 @appendixsec Catalogs |
3407 @cindex Catalogs | 3602 @cindex Catalogs |
3408 | 3603 |
3409 @emph{Catalogs} are files containing scanned information on individual | 3604 @emph{Catalogs} are files containing scanned information on individual |
3424 information out automatically, or on-demand (menu @code{Debug->Save Path | 3619 information out automatically, or on-demand (menu @code{Debug->Save Path |
3425 Info}). On systems with no shell from which to discover the path | 3620 Info}). On systems with no shell from which to discover the path |
3426 information (e.g. Windows), a library path must be specified in | 3621 information (e.g. Windows), a library path must be specified in |
3427 @code{idlwave-library-path} to allow library catalogs to be located, and | 3622 @code{idlwave-library-path} to allow library catalogs to be located, and |
3428 to setup directories for user catalog scan (@pxref{User Catalog} for | 3623 to setup directories for user catalog scan (@pxref{User Catalog} for |
3429 more on this variable). | 3624 more on this variable). Note that, before the shell is running, IDLWAVE |
3625 can only know about the IDL search path by consulting the file pointed | |
3626 to by @code{idlwave-path-file} (@file{~/.idlwave/idlpath.el}, by | |
3627 default). If @code{idlwave-auto-write-path} is enabled (which is the | |
3628 default), the paths are written out whenever the IDLWAVE shell is | |
3629 started. | |
3430 | 3630 |
3431 @defopt idlwave-auto-write-path (@code{t}) | 3631 @defopt idlwave-auto-write-path (@code{t}) |
3432 Write out information on the !PATH and !DIR paths from IDL automatically | 3632 Write out information on the !PATH and !DIR paths from IDL automatically |
3433 when they change and when the Shell is closed. These paths are needed | 3633 when they change and when the Shell is closed. These paths are needed |
3434 to locate library catalogs. | 3634 to locate library catalogs. |
3435 @end defopt | 3635 @end defopt |
3436 | 3636 |
3437 @defopt idlwave-library-path | 3637 @defopt idlwave-library-path |
3438 IDL library path for Windows and MacOS. Not needed under Unix/MacOSX. | 3638 IDL library path for Windows and MacOS. Under Unix/MacOSX, will be |
3639 obtained from the Shell when run. | |
3439 @end defopt | 3640 @end defopt |
3440 | 3641 |
3441 @defopt idlwave-system-directory | 3642 @defopt idlwave-system-directory |
3442 The IDL system directory for Windows and MacOS. Not needed under | 3643 The IDL system directory for Windows and MacOS. Also needed for |
3443 Unix/MacOSX (obtained from the Shell). | 3644 locating HTML help and the IDL Assistant for IDL v6.2 and later. Under |
3645 Unix/MacOSX, will be obtained from the Shell and recorded, if run. | |
3444 @end defopt | 3646 @end defopt |
3445 | 3647 |
3446 @defopt idlwave-config-directory (@file{~/.idlwave}) | 3648 @defopt idlwave-config-directory (@file{~/.idlwave}) |
3447 Default path where IDLWAVE saves configuration information and any | 3649 Default path where IDLWAVE saves configuration information, a user |
3448 user catalog. | 3650 catalog (if any), and a cached scan of the XML catalog (IDL v6.2 and |
3651 later). | |
3449 @end defopt | 3652 @end defopt |
3450 | 3653 |
3451 @menu | 3654 @menu |
3452 * Library Catalogs:: | 3655 * Library Catalogs:: |
3453 * User Catalog:: | 3656 * User Catalog:: |
3454 @end menu | 3657 @end menu |
3455 | 3658 |
3456 @ifhtml | 3659 @html |
3457 <A NAME="LIBRARY_CATALOGS"></A> | 3660 <A NAME="LIBRARY_CATALOGS"></A> |
3458 @end ifhtml | 3661 @end html |
3459 @node Library Catalogs, User Catalog, Catalogs, Catalogs | 3662 @node Library Catalogs, User Catalog, Catalogs, Catalogs |
3460 @appendixsubsec Library Catalogs | 3663 @appendixsubsec Library Catalogs |
3461 @cindex @file{.idlwave_catalog} | 3664 @cindex @file{.idlwave_catalog} |
3462 @cindex Library catalogs | 3665 @cindex Library catalogs |
3463 @cindex @code{idlwave_catalog} | 3666 @cindex @code{idlwave_catalog} |
3464 | 3667 |
3465 Library catalogs are files named @file{.idlwave_catalog} stored in | 3668 Library catalogs consist of files named @file{.idlwave_catalog} stored |
3466 directories containing @code{.pro} routine files. They are discovered | 3669 in directories containing @code{.pro} routine files. They are |
3467 on the IDL search path and loaded automatically when routine information | 3670 discovered on the IDL search path and loaded automatically when routine |
3468 is read. Each catalog file documents the routines found in that | 3671 information is read. Each catalog file documents the routines found in |
3469 directory --- one catalog per directory. Every catalog has a library | 3672 that directory --- one catalog per directory. Every catalog has a |
3470 name associated with it (e.g. @emph{AstroLib}). This name will be shown | 3673 library name associated with it (e.g. @emph{AstroLib}). This name will |
3471 briefly when the catalog is found, and in the routine info of routines | 3674 be shown briefly when the catalog is found, and in the routine info of |
3472 it documents. | 3675 routines it documents. |
3473 | 3676 |
3474 Many popular libraries of routines are shipped with IDLWAVE catalog | 3677 Many popular libraries of routines are shipped with IDLWAVE catalog |
3475 files by default, and so will be automatically discovered. Library | 3678 files by default, and so will be automatically discovered. Library |
3476 catalogs are scanned externally to Emacs using a tool provided with | 3679 catalogs are scanned externally to Emacs using a tool provided with |
3477 IDLWAVE. Each catalog can be re-scanned independently of any other. | 3680 IDLWAVE. Each catalog can be re-scanned independently of any other. |
3480 burden of scanning from the user (who may not even know they're using a | 3683 burden of scanning from the user (who may not even know they're using a |
3481 scanned catalog). Since all catalogs are independent, they can be | 3684 scanned catalog). Since all catalogs are independent, they can be |
3482 re-scanned automatically to gather updates, e.g. in a @file{cron} job. | 3685 re-scanned automatically to gather updates, e.g. in a @file{cron} job. |
3483 Scanning is much faster than with the built-in user catalog method. One | 3686 Scanning is much faster than with the built-in user catalog method. One |
3484 minor disadvantage: the entire IDL search path is scanned for catalog | 3687 minor disadvantage: the entire IDL search path is scanned for catalog |
3485 files every time IDLWAVE starts up, which might be slow over a network. | 3688 files every time IDLWAVE starts up, which might be slow if accessing IDL |
3689 routines over a slow network. | |
3486 | 3690 |
3487 A Perl tool to create library catalogs is distributed with IDLWAVE: | 3691 A Perl tool to create library catalogs is distributed with IDLWAVE: |
3488 @code{idlwave_catalog}. It can be called quite simply: | 3692 @code{idlwave_catalog}. It can be called quite simply: |
3489 @example | 3693 @example |
3490 idlwave_catalog MyLib | 3694 idlwave_catalog MyLib |
3491 @end example | 3695 @end example |
3492 | 3696 |
3493 @noindent This would scan all directories recursively beneath the current and | 3697 @noindent This will scan all directories recursively beneath the current and |
3494 populate them with @file{.idlwave_catalog} files, tagging the routines | 3698 populate them with @file{.idlwave_catalog} files, tagging the routines |
3495 found with the name library ``MyLib''. The full usage information: | 3699 found there with the name library ``MyLib''. The full usage |
3700 information: | |
3496 | 3701 |
3497 @example | 3702 @example |
3498 Usage: idlwave_catalog [-l] [-v] [-d] [-s] [-f] [-h] libname | 3703 Usage: idlwave_catalog [-l] [-v] [-d] [-s] [-f] [-h] libname |
3499 libname - Unique name of the catalog (4 or more alphanumeric | 3704 libname - Unique name of the catalog (4 or more alphanumeric |
3500 characters). | 3705 characters). |
3512 To re-load the library catalogs on the IDL path, force a system routine | 3717 To re-load the library catalogs on the IDL path, force a system routine |
3513 info update using a single prefix to @code{idlwave-update-routine-info}: | 3718 info update using a single prefix to @code{idlwave-update-routine-info}: |
3514 @kbd{C-u C-c C-i}. | 3719 @kbd{C-u C-c C-i}. |
3515 | 3720 |
3516 @defopt idlwave-use-library-catalogs (@code{t}) | 3721 @defopt idlwave-use-library-catalogs (@code{t}) |
3517 Whether to search for and load library catalogs. Only disable if | 3722 Whether to search for and load library catalogs. Disable if load |
3518 performance is a problem and the catalogs are not needed. | 3723 performance is a problem and/or the catalogs are not needed. |
3519 @end defopt | 3724 @end defopt |
3520 | 3725 |
3521 @node User Catalog, , Library Catalogs, Catalogs | 3726 @node User Catalog, , Library Catalogs, Catalogs |
3522 @appendixsubsec User Catalog | 3727 @appendixsubsec User Catalog |
3523 @cindex User catalog | 3728 @cindex User catalog |
3558 (setq idlwave-library-path | 3763 (setq idlwave-library-path |
3559 '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs")) | 3764 '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs")) |
3560 (setq idlwave-system-directory "c:/RSI/IDL56/") | 3765 (setq idlwave-system-directory "c:/RSI/IDL56/") |
3561 @end lisp | 3766 @end lisp |
3562 | 3767 |
3563 @noindent Under GNU and UNIX, these values will be automatically gathered from | 3768 @noindent Under GNU/Linux and UNIX, these values will be automatically |
3564 the IDLWAVE shell. | 3769 gathered from the IDLWAVE shell, if run. |
3565 | 3770 |
3566 The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item | 3771 The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item |
3567 @samp{IDLWAVE->Routine Info->Select Catalog Directories} can then be | 3772 @samp{IDLWAVE->Routine Info->Select Catalog Directories}) can then be |
3568 used to create a user catalog. It brings up a widget in which you can | 3773 used to create a user catalog. It brings up a widget in which you can |
3569 select some or all directories on the search path. Directories which | 3774 select some or all directories on the search path. Directories which |
3570 already contain a library catalog are marked with @samp{[LIB]}, and need | 3775 already contain a library catalog are marked with @samp{[LIB]}, and need |
3571 not be scanned (although there is no harm if you do so, other than the | 3776 not be scanned (although there is no harm if you do so, other than the |
3572 additional memory used for the duplication). | 3777 additional memory used for the duplication). |
3640 | 3845 |
3641 @cindex Windows | 3846 @cindex Windows |
3642 @cindex MacOS | 3847 @cindex MacOS |
3643 @cindex IDL variable @code{!DIR} | 3848 @cindex IDL variable @code{!DIR} |
3644 @cindex @code{!DIR}, IDL variable | 3849 @cindex @code{!DIR}, IDL variable |
3645 Users of Windows and MacOS also must set the variable | 3850 Users of Windows and MacOS (not X) also must set the variable |
3646 @code{idlwave-system-directory} to the value of the @code{!DIR} system | 3851 @code{idlwave-system-directory} to the value of the @code{!DIR} system |
3647 variable in IDL. IDLWAVE appends @file{lib} to the value of this | 3852 variable in IDL. IDLWAVE appends @file{lib} to the value of this |
3648 variable and assumes that all files found on that path are system | 3853 variable and assumes that all files found on that path are system |
3649 routines. | 3854 routines. |
3650 | 3855 |
3656 @cindex @file{get_html_rinfo} | 3861 @cindex @file{get_html_rinfo} |
3657 @cindex @file{idlw-rinfo.el} | 3862 @cindex @file{idlw-rinfo.el} |
3658 @cindex Scanning the documentation | 3863 @cindex Scanning the documentation |
3659 @cindex Perl program, to create @file{idlw-rinfo.el} | 3864 @cindex Perl program, to create @file{idlw-rinfo.el} |
3660 | 3865 |
3866 @strong{Starting with version 6.2, IDL is distributed directly with HTML | |
3867 online help, and an XML-based catalog of routine information}. This | |
3868 makes scanning the manuals with the tool @file{get_html_rinfo}, and the | |
3869 @file{idlw-rinfo.el} file it produced, as described here, entirely | |
3870 unnecessary. The information is left here for users wishing to produce | |
3871 a catalog of older IDL versions' help. | |
3872 | |
3873 | |
3661 IDLWAVE derives its knowledge about system routines from the IDL | 3874 IDLWAVE derives its knowledge about system routines from the IDL |
3662 manuals. The file @file{idlw-rinfo.el} contains the routine information | 3875 manuals. The file @file{idlw-rinfo.el} contains the routine information |
3663 for the IDL system routines, and links to relevant sections of the HTML | 3876 for the IDL system routines, and links to relevant sections of the HTML |
3664 documentation. The Online Help feature of IDLWAVE requires HTML | 3877 documentation. The Online Help feature of IDLWAVE requires HTML |
3665 versions of the IDL manuals to be available. | 3878 versions of the IDL manuals to be available; the HTML documentation is |
3879 not distributed with IDLWAVE by default, but must be downloaded | |
3880 separately@c | |
3881 @ifclear PARTOFEMACS | |
3882 @ from @uref{@value{IDLWAVEHOMEPAGE}, the maintainers | |
3883 webpage}@c | |
3884 @end ifclear | |
3885 . | |
3666 | 3886 |
3667 The HTML files and related images can be produced from the | 3887 The HTML files and related images can be produced from the |
3668 @file{idl.chm} HTMLHelp file distributed with IDL using the free | 3888 @file{idl.chm} HTMLHelp file distributed with IDL using the free |
3669 Microsoft HTML Help Workshop. If you are lucky, the maintainer of | 3889 Microsoft HTML Help Workshop. If you are lucky, the maintainer of |
3670 IDLWAVE will always have access to the newest version of IDL and | 3890 IDLWAVE will always have access to the newest version of IDL and provide |
3671 provide updates. The IDLWAVE distribution also contains the Perl | 3891 updates. The IDLWAVE distribution also contains the Perl program |
3672 program @file{get_html_rinfo} which constructs the | 3892 @file{get_html_rinfo} which constructs the @file{idlw-rinfo.el} file by |
3673 @file{idlw-rinfo.el} file by scanning the HTML documents produced from | 3893 scanning the HTML documents produced from the IDL documentation. |
3674 the IDL documentation. Instructions on how to use | 3894 Instructions on how to use @file{get_html_rinfo} are in the program |
3675 @file{get_html_rinfo} are in the program itself. | 3895 itself. |
3676 | 3896 |
3677 @node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top | 3897 @node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top |
3678 @appendix HTML Help Browser Tips | 3898 @appendix HTML Help Browser Tips |
3679 @cindex Browser Tips | 3899 @cindex Browser Tips |
3680 | 3900 |
3681 There are a wide variety of possible browsers to use for displaying | 3901 There are a wide variety of possible browsers to use for displaying |
3682 the online HTML help available with IDLWAVE (starting with version | 3902 the online HTML help available with IDLWAVE (starting with version |
3683 5.0). Since IDLWAVE runs on a many different system types, a single | 3903 5.0). Since IDL v6.2, a single cross-platform HTML help browser, the |
3684 browser configuration is not possible, but choices abound. | 3904 @emph{IDL Assistant} is distributed with IDL. If this help browser is |
3685 | 3905 available, it is the preferred choice, and the default. The variable |
3686 Unfortunately, the HTML manuals decompiled from the original | 3906 @code{idlwave-help-use-assistant}, enabled by default, controls |
3687 source contain formatting structures which Netscape 4.x does not | 3907 whether this help browser is used. If you use the IDL Assistant, the |
3688 handle well, though they are still readable. A much better choice is | 3908 tips here are not relevant. |
3689 Mozilla, or one of the Mozilla-derived browsers such as | 3909 |
3910 Since IDLWAVE runs on a many different system types, a single browser | |
3911 configuration is not possible, but choices abound. On many systems, | |
3912 the default browser configured in @code{browse-url-browser-function}, | |
3913 and hence inherited by default by | |
3914 @code{idlwave-help-browser-function}, is Netscape. Unfortunately, the | |
3915 HTML manuals decompiled from the original source contain formatting | |
3916 structures which Netscape 4.x does not handle well, though they are | |
3917 still readable. A much better choice is Mozilla, or one of the | |
3918 Mozilla-derived browsers such as | |
3690 @uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux), | 3919 @uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux), |
3691 @uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or | 3920 @uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or |
3692 @uref{http://www.mozilla.org/projects/firebird/,Firebird} (all | 3921 @uref{http://www.mozilla.org/projects/firebird/,Firebird} (all |
3693 platforms). Newer versions of Emacs provide a browser-function choice | 3922 platforms). Newer versions of Emacs provide a browser-function choice |
3694 @code{browse-url-gnome-moz} which uses the Gnome-configured browser. | 3923 @code{browse-url-gnome-moz} which uses the Gnome-configured browser. |
3695 | 3924 |
3696 Note that the HTML files decompiled from Microsoft Help sources | 3925 Note that the HTML files decompiled from the help sources contain |
3697 contain specific references to the @samp{Symbol} font, which by default | 3926 specific references to the @samp{Symbol} font, which by default is not |
3698 is not permitted in normal encodings (it's invalid, technically). Though | 3927 permitted in normal encodings (it's invalid, technically). Though it |
3699 it only impacts a few symbols, you can trick Mozilla-based browsers into | 3928 only impacts a few symbols, you can trick Mozilla-based browsers into |
3700 recognizing @samp{Symbol} by following the directions | 3929 recognizing @samp{Symbol} by following the directions |
3701 @uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With this | 3930 @uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With |
3702 fix in place, HTML help pages look almost identical to their PDF | 3931 this fix in place, HTML help pages look almost identical to their PDF |
3703 equivalents (yet can be bookmarked, browsed as history, searched, etc.). | 3932 equivalents (yet can be bookmarked, browsed as history, searched, |
3933 etc.). | |
3704 | 3934 |
3705 @noindent Individual platform recommendations: | 3935 @noindent Individual platform recommendations: |
3706 | 3936 |
3707 @itemize @bullet | 3937 @itemize @bullet |
3708 @item Windows: The native Microsoft HTMLHelp browser is preferred, | |
3709 with even better results using the free | |
3710 @uref{http://www.keyworks.net/keyhh.htm,@code{KEYHH}} program to | |
3711 permit IDL help to be targetted to a single window. To use HTMLHelp, | |
3712 specify @code{idlwave-help-use-hh} as @code{'hh} or @code{'keyhh}. | |
3713 One bonus: since IDL is shipped with the @file{idl.chm} help file, you | |
3714 don't need to download the HTML help package. @xref{Help with HTML | |
3715 Documentation}. | |
3716 @item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser | 3938 @item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser |
3717 and its associated | 3939 and its associated |
3718 @uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode | 3940 @uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode |
3719 provide in-buffer browsing with image display, and excellent speed and | 3941 provide in-buffer browsing with image display, and excellent speed and |
3720 formatting. Both the Emacs mode and the browser itself must be | 3942 formatting. Both the Emacs mode and the browser itself must be |
3905 "print,size(___,/TNAME)")) | 4127 "print,size(___,/TNAME)")) |
3906 (idlwave-shell-define-key-both [f11] (idlwave-shell-examine | 4128 (idlwave-shell-define-key-both [f11] (idlwave-shell-examine |
3907 "help,___,/STRUCTURE")))) | 4129 "help,___,/STRUCTURE")))) |
3908 @end example | 4130 @end example |
3909 | 4131 |
3910 @ifhtml | 4132 @html |
3911 <A NAME="WIN_MAC"></A> | 4133 <A NAME="WIN_MAC"></A> |
3912 @end ifhtml | 4134 @end html |
3913 @node Windows and MacOS, Troubleshooting, Configuration Examples, Top | 4135 @node Windows and MacOS, Troubleshooting, Configuration Examples, Top |
3914 @appendix Windows and MacOS | 4136 @appendix Windows and MacOS |
3915 @cindex Windows | 4137 @cindex Windows |
3916 @cindex MacOS | 4138 @cindex MacOS |
3917 @cindex MacOSX | 4139 @cindex MacOSX |
3918 | 4140 |
3919 IDLWAVE was developed on a UNIX system. However, thanks to the | 4141 IDLWAVE was developed on a UNIX system. However, thanks to the |
3920 portability of Emacs, much of IDLWAVE does also work under different | 4142 portability of Emacs, much of IDLWAVE does also work under different |
3921 operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS. | 4143 operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS. |
3922 | 4144 |
3923 The only real problem is that there is no command-line | 4145 The only real problem is that there is no command-line version of IDL |
3924 version of IDL for Windows or MacOS(<=9) with which IDLWAVE can | 4146 for Windows or MacOS(<=9) with which IDLWAVE can interact. As a |
3925 interact. As a result, the IDLWAVE Shell | 4147 result, the IDLWAVE Shell does not work and you have to rely on IDLDE |
3926 does not work and you have to rely on IDLDE to run and debug your | 4148 to run and debug your programs. However, editing IDL source files |
3927 programs. However, editing IDL source files with Emacs/IDLWAVE works | 4149 with Emacs/IDLWAVE works with all bells and whistles, including |
3928 with all bells and whistles, including routine info, completion and fast | 4150 routine info, completion and fast online help. Only a small amount of |
3929 online help. Only a small amount of additional information must be | 4151 additional information must be specified in your @file{.emacs} file: |
3930 specified in your @file{.emacs} file: the path names which, on a UNIX | 4152 the path names which, on a UNIX system, are automatically gathered by |
3931 system, are automatically gathered by talking to the IDL program. | 4153 talking to the IDL program. |
3932 | 4154 |
3933 Here is an example of the additional configuration needed for a Windows | 4155 Here is an example of the additional configuration needed for a Windows |
3934 system. I am assuming that IDLWAVE has been installed in | 4156 system. I am assuming that IDLWAVE has been installed in |
3935 @w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in | 4157 @w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in |
3936 @w{@samp{C:\RSI\IDL55}}. | 4158 @w{@samp{C:\RSI\IDL62}}. |
3937 | 4159 |
3938 @lisp | 4160 @lisp |
3939 ;; location of the lisp files (needed if IDLWAVE is not part of | 4161 ;; location of the lisp files (only needed if IDLWAVE is not part of |
3940 ;; the X/Emacs installation) | 4162 ;; your default X/Emacs installation) |
3941 (setq load-path (cons "c:/program files/IDLWAVE" load-path)) | 4163 (setq load-path (cons "c:/program files/IDLWAVE" load-path)) |
3942 | 4164 |
3943 ;; The location of the IDL library files, both standard and your own. | 4165 ;; The location of the IDL library directories, both standard, and your own. |
3944 ;; note that the initial "+" expands the path recursively | 4166 ;; note that the initial "+" expands the path recursively |
3945 (setq idlwave-library-path | 4167 (setq idlwave-library-path |
3946 '("+c:/RSI/IDL55/lib/" "+c:/user/me/idllibs" )) | 4168 '("+c:/RSI/IDL55/lib/" "+c:/path/to/my/idllibs" )) |
3947 | 4169 |
3948 ;; location of the IDL system directory (try "print,!DIR") | 4170 ;; location of the IDL system directory (try "print,!DIR") |
3949 (setq idlwave-system-directory "c:/RSI/IDL55/") | 4171 (setq idlwave-system-directory "c:/RSI/IDL62/") |
3950 | 4172 |
3951 ;; specify using the HTMLHelp documentation for online help, with the | |
3952 ;; KEYHH helper routine (Windows only) | |
3953 (setq idlwave-use-hh 'keyhh) | |
3954 | |
3955 ;; file in which to store the user catalog info | |
3956 (setq idlwave-user-catalog-file "c:/IDLWAVE/idlcat.el") | |
3957 @end lisp | 4173 @end lisp |
3958 | 4174 |
3959 @noindent Furthermore, Windows sometimes tries to outsmart you --- make | 4175 @noindent Furthermore, Windows sometimes tries to outsmart you --- make |
3960 sure you check the following things: | 4176 sure you check the following things: |
3961 | 4177 |
3969 | 4185 |
3970 Windows users who'd like to make use of IDLWAVE's context-aware HTML | 4186 Windows users who'd like to make use of IDLWAVE's context-aware HTML |
3971 help can skip the browser and use the HTMLHelp functionality directly. | 4187 help can skip the browser and use the HTMLHelp functionality directly. |
3972 @xref{Help with HTML Documentation}. | 4188 @xref{Help with HTML Documentation}. |
3973 | 4189 |
3974 @ifhtml | 4190 @html |
3975 <A NAME="TROUBLE"></A> | 4191 <A NAME="TROUBLE"></A> |
3976 @end ifhtml | 4192 @end html |
3977 @node Troubleshooting, Index, Windows and MacOS, Top | 4193 @node Troubleshooting, Index, Windows and MacOS, Top |
3978 @appendix Troubleshooting | 4194 @appendix Troubleshooting |
3979 @cindex Troubleshooting | 4195 @cindex Troubleshooting |
3980 | 4196 |
3981 Although IDLWAVE usually installs and works without difficulty, a few | 4197 Although IDLWAVE usually installs and works without difficulty, a few |
3994 @kbd{C-?} lists these shortcuts. Use @kbd{q} to quit the mode, and | 4210 @kbd{C-?} lists these shortcuts. Use @kbd{q} to quit the mode, and |
3995 customize the variable @code{idlwave-shell-automatic-electric-debug} | 4211 customize the variable @code{idlwave-shell-automatic-electric-debug} |
3996 if you prefer not to enter electric debug on breakpoints@dots{} but | 4212 if you prefer not to enter electric debug on breakpoints@dots{} but |
3997 you really should try it before you disable it! You can also | 4213 you really should try it before you disable it! You can also |
3998 customize this variable to enter debug mode when errors are | 4214 customize this variable to enter debug mode when errors are |
3999 encountered too. | 4215 encountered. |
4000 | 4216 |
4001 @item @strong{I get errors like @samp{Searching for program: no such | 4217 @item @strong{I get errors like @samp{Searching for program: no such |
4002 file or directory, idl} when attempting to start the IDL shell.} | 4218 file or directory, idl} when attempting to start the IDL shell.} |
4003 | 4219 |
4004 IDLWAVE needs to know where IDL is in order to run it as a process. | 4220 IDLWAVE needs to know where IDL is in order to run it as a process. |
4018 configuration files (e.g. @file{.cshrc}), but from the file | 4234 configuration files (e.g. @file{.cshrc}), but from the file |
4019 @file{~/.MacOSX/environment.plist}. Either include your path settings | 4235 @file{~/.MacOSX/environment.plist}. Either include your path settings |
4020 there, or start Emacs and IDLWAVE from the shell. | 4236 there, or start Emacs and IDLWAVE from the shell. |
4021 | 4237 |
4022 @item @strong{I get errors like @samp{Symbol's function is void: | 4238 @item @strong{I get errors like @samp{Symbol's function is void: |
4023 overlayp} when trying to start the shell in XEmacs} | 4239 overlayp}} |
4024 | 4240 |
4025 You don't have the @samp{fsf-compat} package installed, which IDLWAVE | 4241 You don't have the @samp{fsf-compat} package installed, which IDLWAVE |
4026 needs to run under XEmacs. Install it and, if necessary, insert | 4242 needs to run under XEmacs. Install it, or find an XEmacs distribution |
4027 @code{(require 'overlay)} in your @file{.emacs}. | 4243 which includes it by default. |
4028 | 4244 |
4029 @item @strong{I'm getting errors like @samp{Symbol's value as variable is void: | 4245 @item @strong{I'm getting errors like @samp{Symbol's value as variable is void: |
4030 cl-builtin-gethash} on completion or routine info.} | 4246 cl-builtin-gethash} on completion or routine info.} |
4031 | 4247 |
4032 This error arises if you upgraded Emacs from 20.x to 21.x without | 4248 This error arises if you upgraded Emacs from 20.x to 21.x without |
4033 re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible | 4249 re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible |
4034 in compiled lisp files. Presumably, you kept the original .elc files in | 4250 in compiled lisp files. Presumably, you kept the original .elc files in |
4035 place, and this is the source of the error. If you recompile (or just | 4251 place, and this is the source of the error. If you recompile (or just |
4036 "make; make install") from source, it should resolve this problem. | 4252 "make; make install") from source, it should resolve this problem. |
4037 Another option is to recompile the @file{idlw*.el} files by hand using | 4253 Another option is to recompile the @file{idlw*.el} files by hand using |
4038 @kbd{M-x byte-compile-file}. | 4254 @kbd{M-x byte-compile-file}. |
4255 @ifclear PARTOFEMACS | |
4256 Why not take the opportunity to grab the | |
4257 latest IDLWAVE version at @uref{@value{IDLWAVEHOMEPAGE}, the | |
4258 maintainers webpage}. | |
4259 @end ifclear | |
4039 | 4260 |
4040 @item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches | 4261 @item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches |
4041 windows on my desktop.} | 4262 windows on my desktop.} |
4042 | 4263 |
4043 Your system is trapping @kbd{M-@key{TAB}} and using it for its own | 4264 Your system is trapping @kbd{M-@key{TAB}} and using it for its own |
4061 } by default). You can do this with the variable | 4282 } by default). You can do this with the variable |
4062 @code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g., | 4283 @code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g., |
4063 in your @file{.emacs}: | 4284 in your @file{.emacs}: |
4064 | 4285 |
4065 @lisp | 4286 @lisp |
4066 (setq idlwave-shell-prompt-pattern "^\\(ENVI\\|IDL\\)> ") | 4287 (setq idlwave-shell-prompt-pattern "^\r? ?\\(ENVI\\|IDL\\)> ") |
4067 @end lisp | 4288 @end lisp |
4068 | 4289 |
4069 @item @strong{Attempts to set breakpoints fail: no breakpoint is | 4290 @item @strong{Attempts to set breakpoints fail: no breakpoint is |
4070 indicated in the IDLWAVE buffer.} | 4291 indicated in the IDLWAVE buffer.} |
4071 | 4292 |
4093 @lisp | 4314 @lisp |
4094 (setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path)) | 4315 (setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path)) |
4095 @end lisp | 4316 @end lisp |
4096 | 4317 |
4097 @noindent You can check on your load-path value using @kbd{C-h v | 4318 @noindent You can check on your load-path value using @kbd{C-h v |
4098 load-path @key{RET}}. | 4319 load-path @key{RET}}, and @kbd{C-h m} in an IDLWAVE buffer should show |
4320 you the version Emacs is using. | |
4099 | 4321 |
4100 @item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.} | 4322 @item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.} |
4101 | 4323 |
4102 Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated | 4324 Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated |
4103 programming mode for CORBA's Interface Definition Language (you should | 4325 programming mode for CORBA's Interface Definition Language (you should |
4115 IDLWAVE collects routine info from various locations (@pxref{Routine | 4337 IDLWAVE collects routine info from various locations (@pxref{Routine |
4116 Information Sources}). Routines in files visited in a buffer or | 4338 Information Sources}). Routines in files visited in a buffer or |
4117 compiled in the shell should be up to date. For other routines, the | 4339 compiled in the shell should be up to date. For other routines, the |
4118 information is only as current as the most recent scan. If you have a | 4340 information is only as current as the most recent scan. If you have a |
4119 rapidly changing set of routines, and you'd like the latest routine | 4341 rapidly changing set of routines, and you'd like the latest routine |
4120 information to be available for it, one powerful technique makes use of | 4342 information to be available for it, one powerful technique is to make |
4121 the library catalog tool, @samp{idlwave_catalog}. Simply add a line to | 4343 use of the library catalog tool, @samp{idlwave_catalog}. Simply add a |
4122 your @samp{cron} file (@samp{crontab -e} will let you edit this on some | 4344 line to your @samp{cron} file (@samp{crontab -e} will let you edit this |
4123 systems), like this: | 4345 on some systems), like this |
4124 | 4346 |
4125 @example | 4347 @example |
4126 45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib) | 4348 45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib) |
4127 @end example | 4349 @end example |
4128 | 4350 |
4129 @noindent where @samp{MyLib} is the name of your library. This will | 4351 @noindent where @samp{MyLib} is the name of your library. This will |
4130 rescan all @file{.pro} files at or below @file{/path/to/myidllib} every | 4352 rescan all @file{.pro} files at or below @file{/path/to/myidllib} every |
4131 week night at 3:45am. You can even scan site-wide libraries with this | 4353 week night at 3:45am. You can even scan site-wide libraries with this |
4132 method, and the most recent information will be available to all users. | 4354 method, and the most recent information will be available to all users. |
4355 Since the scanning is very fast, there is very little impact. | |
4133 | 4356 |
4134 @item @strong{All the Greek-font characters in the HTML help are | 4357 @item @strong{All the Greek-font characters in the HTML help are |
4135 displayed as Latin characters!} | 4358 displayed as Latin characters!} |
4136 | 4359 |
4137 Unfortunately, the HTMLHelp files attempt to switch to | 4360 Unfortunately, the HTMLHelp files RSI provides attempt to switch to |
4138 @samp{Symbol} font to display Greek characters, which is not really an | 4361 @samp{Symbol} font to display Greek characters, which is not really an |
4139 permitted method for doing this in HTML. There is a "workaround" for | 4362 permitted method for doing this in HTML. There is a "workaround" for |
4140 many browsers: @xref{HTML Help Browser Tips}. | 4363 some browsers: @xref{HTML Help Browser Tips}. |
4141 | 4364 |
4142 @item @strong{In the shell, my long commands are truncated at 256 characters!} | 4365 @item @strong{In the shell, my long commands are truncated at 256 characters!} |
4143 | 4366 |
4144 This actually happens when running IDL in an XTerm as well. There are | 4367 This actually happens when running IDL in an XTerm as well. There are |
4145 a couple of work arounds: @code{define_key,/control,'^d'} (e.g. in | 4368 a couple of work arounds: @code{define_key,/control,'^d'} (e.g. in |
4148 @key{C-d} to quit the shell, however. Another possibility is | 4371 @key{C-d} to quit the shell, however. Another possibility is |
4149 @code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a | 4372 @code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a |
4150 memory-bounded limit), but disables the processing of background | 4373 memory-bounded limit), but disables the processing of background |
4151 widget events (those with @code{/NO_BLOCK} passed to @code{XManager}). | 4374 widget events (those with @code{/NO_BLOCK} passed to @code{XManager}). |
4152 | 4375 |
4376 @item @strong{When I invoke IDL HTML help on a routine, the page which | |
4377 is loaded is one page off, e.g. for @code{CONVERT_COORD}, I get | |
4378 @code{CONTOUR}.} | |
4379 | |
4380 You have a mismatch between your help index and the HTML help package | |
4381 you downloaded. You need to ensure you download a ``downgrade kit'' if | |
4382 you are using anything older than the latest HTML help package. A new | |
4383 help package apppears with each IDL release (assuming the documentation | |
4384 is updated). | |
4385 @ifclear PARTOFEMACS | |
4386 See @uref{@value{IDLWAVEHOMEPAGE}, the maintainers | |
4387 webpage} for more. | |
4388 @end ifclear | |
4389 Note that, starting with IDL 6.2, the HTML help and its catalog are | |
4390 distributed with IDL, and so should never be inconsistent. | |
4391 | |
4392 @item @strong{I get errors such as @samp{void-variable | |
4393 browse-url-browser-function} or similar when attempting to load IDLWAVE | |
4394 under XEmacs.} | |
4395 | |
4396 You don't have the @samp{browse-url} (or other required) XEmacs package. | |
4397 Unlike GNU Emacs, XEmacs distributes many packages separately from the | |
4398 main program. IDLWAVE is actually among these, but is not always the | |
4399 most up to date. When installing IDLWAVE as an XEmacs package, it | |
4400 should prompt you for required additional packages. When installing it | |
4401 from source, it won't and you'll get this error. The easiest solution | |
4402 is to install all the packages when you install XEmacs (the so-called | |
4403 @samp{sumo} bundle). The minimum set of XEmacs packages required by | |
4404 IDLWAVE is @samp{fsf-compat, xemacs-base, mail-lib}. | |
4405 | |
4153 @end enumerate | 4406 @end enumerate |
4154 | 4407 |
4155 @node Index, , Troubleshooting, Top | 4408 @node Index, , Troubleshooting, Top |
4156 @unnumbered Index | 4409 @unnumbered Index |
4157 @printindex cp | 4410 @printindex cp |
4158 | 4411 |
4159 @bye | 4412 @bye |
4160 | |
4161 @ignore | |
4162 arch-tag: f1d73958-1423-4127-b8aa-f7b953d64492 | |
4163 @end ignore |