Mercurial > emacs
annotate doc/misc/idlwave.texi @ 101402:c542410b5bda
(Getting Started): Describe $MH.
author | Stephen Eglen <stephen@gnu.org> |
---|---|
date | Fri, 23 Jan 2009 13:51:13 +0000 |
parents | cb5d2387102c |
children | 9bcea07061a8 |
rev | line source |
---|---|
84302 | 1 \input texinfo @c -*-texinfo-*- |
2 @c %**start of header | |
84329
3d431f1997d8
(setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents:
84302
diff
changeset
|
3 @setfilename ../../info/idlwave |
84302 | 4 @settitle IDLWAVE User Manual |
5 @dircategory Emacs | |
6 @direntry | |
7 * IDLWAVE: (idlwave). Major mode and shell for IDL files. | |
8 @end direntry | |
9 @synindex ky cp | |
10 @syncodeindex vr cp | |
11 @syncodeindex fn cp | |
12 @set VERSION 6.1 | |
13 @set EDITION 6.1 | |
14 @set IDLVERSION 6.3 | |
15 @set NSYSROUTINES 4346 | |
16 @set DATE April, 2007 | |
17 @set AUTHOR J.D. Smith & Carsten Dominik | |
18 @set MAINTAINER J.D. Smith | |
19 @c %**end of header | |
20 @finalout | |
21 | |
95932 | 22 @copying |
84302 | 23 This file documents IDLWAVE, a major mode for editing IDL files with |
24 Emacs, and interacting with an IDL shell run as a subprocess. | |
25 | |
26 This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE | |
95932 | 27 @value{VERSION}. |
84302 | 28 |
95874
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
29 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, |
100974 | 30 2007, 2008, 2009 Free Software Foundation, Inc. |
84302 | 31 |
95932 | 32 @quotation |
84302 | 33 Permission is granted to copy, distribute and/or modify this document |
99709
6de181810d0f
Relicense all texi files under FDL 1.3 or later.
Glenn Morris <rgm@gnu.org>
parents:
95932
diff
changeset
|
34 under the terms of the GNU Free Documentation License, Version 1.3 or |
84302 | 35 any later version published by the Free Software Foundation; with no |
95932 | 36 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', |
37 and with the Back-Cover Texts as in (a) below. A copy of the license | |
38 is included in the section entitled ``GNU Free Documentation License''. | |
84302 | 39 |
95874
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
40 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
41 modify this GNU manual. Buying copies from the FSF supports it in |
eafbd7a5c9be
Update Back-Cover Text as per maintain.info.
Glenn Morris <rgm@gnu.org>
parents:
87903
diff
changeset
|
42 developing GNU and promoting software freedom.'' |
95932 | 43 @end quotation |
44 @end copying | |
84302 | 45 |
46 @titlepage | |
47 @title IDLWAVE User Manual | |
48 @subtitle Emacs major mode and shell for IDL | |
49 @subtitle Edition @value{EDITION}, @value{DATE} | |
50 @author by J.D. Smith & Carsten Dominik | |
51 @page | |
95932 | 52 @vskip 0pt plus 1filll |
53 @insertcopying | |
84302 | 54 @end titlepage |
55 @contents | |
56 | |
57 @page | |
58 | |
59 @ifnottex | |
60 | |
61 @node Top, Introduction, (dir), (dir) | |
62 | |
63 IDLWAVE is a package which supports editing source code written in the | |
64 Interactive Data Language (IDL), and running IDL as an inferior shell. | |
65 | |
66 @end ifnottex | |
67 | |
68 @menu | |
69 * Introduction:: What IDLWAVE is, and what it is not | |
70 * IDLWAVE in a Nutshell:: One page quick-start guide | |
71 * Getting Started:: Tutorial | |
72 * The IDLWAVE Major Mode:: The mode for editing IDL programs | |
73 * The IDLWAVE Shell:: The mode for running IDL as an inferior program | |
74 * Acknowledgements:: Who did what | |
75 * Sources of Routine Info:: How does IDLWAVE know about routine XYZ | |
76 * HTML Help Browser Tips:: | |
77 * Configuration Examples:: The user is king | |
78 * Windows and MacOS:: What still works, and how | |
79 * Troubleshooting:: When good computers turn bad | |
80 * GNU Free Documentation License:: The license for this documentation. | |
81 * Index:: Fast access | |
82 | |
83 @detailmenu | |
84 --- The Detailed Node Listing --- | |
85 | |
86 Getting Started (Tutorial) | |
87 | |
88 * Lesson I -- Development Cycle:: | |
89 * Lesson II -- Customization:: | |
90 * Lesson III -- User Catalog:: | |
91 | |
92 The IDLWAVE Major Mode | |
93 | |
94 * Code Formatting:: Making code look nice | |
95 * Routine Info:: Calling Sequence and Keyword List | |
96 * Online Help:: One key press from source to help | |
97 * Completion:: Completing routine names and Keywords | |
98 * Routine Source:: Finding routines, the easy way | |
99 * Resolving Routines:: Force the Shell to compile a routine | |
100 * Code Templates:: Frequent code constructs | |
101 * Abbreviations:: Abbreviations for common commands | |
102 * Actions:: Changing case, Padding, End checking | |
103 * Doc Header:: Inserting a standard header | |
104 * Motion Commands:: Moving through the structure of a program | |
105 * Misc Options:: Things that fit nowhere else | |
106 | |
107 Code Formatting | |
108 | |
109 * Code Indentation:: Reflecting the logical structure | |
110 * Continued Statement Indentation:: | |
111 * Comment Indentation:: Special indentation for comment lines | |
112 * Continuation Lines:: Splitting statements over lines | |
113 * Syntax Highlighting:: Font-lock support | |
114 * Octals and Highlighting:: Why "123 causes problems | |
115 | |
116 Online Help | |
117 | |
118 * Help with HTML Documentation:: | |
119 * Help with Source:: | |
120 | |
121 Completion | |
122 | |
123 * Case of Completed Words:: CaseOFcomPletedWords | |
124 * Object Method Completion and Class Ambiguity:: obj->Method, what? | |
125 * Object Method Completion in the Shell:: | |
126 * Class and Keyword Inheritance:: obj->Method, _EXTRA=e | |
127 * Structure Tag Completion:: Completing state.Tag | |
128 | |
129 Actions | |
130 | |
131 * Block Boundary Check:: Is the END statement correct? | |
132 * Padding Operators:: Enforcing space around `=' etc | |
133 * Case Changes:: Enforcing upper case keywords | |
134 | |
135 The IDLWAVE Shell | |
136 | |
137 * Starting the Shell:: How to launch IDL as a subprocess | |
138 * Using the Shell:: Interactively working with the Shell | |
139 * Commands Sent to the Shell:: | |
140 * Debugging IDL Programs:: | |
141 * Examining Variables:: | |
142 * Custom Expression Examination:: | |
143 | |
144 Debugging IDL Programs | |
145 | |
146 * A Tale of Two Modes:: | |
147 * Debug Key Bindings:: | |
148 * Breakpoints and Stepping:: | |
149 * Compiling Programs:: | |
150 * Walking the Calling Stack:: | |
151 * Electric Debug Mode:: | |
152 | |
153 Sources of Routine Info | |
154 | |
155 * Routine Definitions:: Where IDL Routines are defined. | |
156 * Routine Information Sources:: So how does IDLWAVE know about... | |
157 * Catalogs:: | |
158 * Load-Path Shadows:: Routines defined in several places | |
159 * Documentation Scan:: Scanning the IDL Manuals | |
160 | |
161 Catalogs | |
162 | |
163 * Library Catalogs:: | |
164 * User Catalog:: | |
165 | |
166 @end detailmenu | |
167 @end menu | |
168 | |
169 @node Introduction, IDLWAVE in a Nutshell, Top, Top | |
170 @chapter Introduction | |
171 @cindex Introduction | |
172 @cindex CORBA (Common Object Request Broker Architecture) | |
173 @cindex Interface Definition Language | |
174 @cindex Interactive Data Language | |
175 @cindex cc-mode.el | |
176 @cindex @file{idl.el} | |
177 @cindex @file{idl-shell.el} | |
178 @cindex Feature overview | |
179 | |
180 IDLWAVE is a package which supports editing source files written in | |
181 the Interactive Data Language (IDL), and running IDL as an inferior shell@footnote{IDLWAVE can also be used | |
182 for editing source files for the related WAVE/CL language, but with only | |
183 limited support.}. It is a feature-rich replacement for the IDLDE | |
184 development environment included with IDL, and uses the full power of | |
185 Emacs to make editing and running IDL programs easier, quicker, and more | |
186 structured. | |
187 | |
188 IDLWAVE consists of two main parts: a major mode for editing IDL | |
189 source files (@code{idlwave-mode}) and a mode for running the IDL | |
190 program as an inferior shell (@code{idlwave-shell-mode}). Although | |
191 one mode can be used without the other, both work together closely to | |
192 form a complete development environment. Here is a brief summary of | |
193 what IDLWAVE does: | |
194 | |
195 @itemize @bullet | |
196 @item | |
197 Smart code indentation and automatic-formatting. | |
198 @item | |
199 Three level syntax highlighting support. | |
200 @item | |
201 Context-sensitive display of calling sequences and keywords for more | |
202 than 1000 native IDL routines, extendible to any additional number of | |
203 local routines, and already available with many pre-scanned libraries. | |
204 @item | |
205 Fast, context-sensitive online HTML help, or source-header help for | |
206 undocumented routines. | |
207 @item | |
208 Context sensitive completion of routine names, keywords, system | |
209 variables, class names and much more. | |
210 @item | |
211 Easy insertion of code templates and abbreviations of common constructs. | |
212 @item | |
213 Automatic corrections to enforce a variety of customizable coding | |
214 standards. | |
215 @item | |
216 Integrity checks and auto-termination of logical blocks. | |
217 @item | |
218 Routine name space conflict search with likelihood-of-use ranking. | |
219 @item | |
220 Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). | |
221 @item | |
222 Documentation support. | |
223 @item | |
224 Running IDL as an inferior Shell with history search, command line | |
225 editing and all the completion and routine info capabilities present in | |
226 IDL source buffers. | |
227 @item | |
228 Full handling of debugging with breakpoints, with interactive setting | |
229 of break conditions, and easy stepping through code. | |
230 @item | |
231 Compilation, execution and interactive single-keystroke debugging of | |
232 programs directly from the source buffer. | |
233 @item | |
234 Quick, source-guided navigation of the calling stack, with variable | |
235 inspection, etc. | |
236 @item | |
237 Examining variables and expressions with a mouse click. | |
238 @item | |
239 And much, much more... | |
240 @end itemize | |
241 | |
242 @ifnottex | |
243 @cindex Screenshots | |
244 Here are a number of screenshots showing IDLWAVE in action: | |
245 | |
246 @itemize @bullet | |
247 @item | |
248 @uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer} | |
249 @item | |
250 @uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed} | |
251 @item | |
252 @uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.} | |
253 @item | |
254 @uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed} | |
255 @item | |
256 @uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code | |
257 stopped at a breakpoint} | |
258 @end itemize | |
259 @end ifnottex | |
260 | |
261 IDLWAVE is the distant successor to the @file{idl.el} and | |
262 @file{idl-shell.el} files written by Chris Chase. The modes and files | |
263 had to be renamed because of a name space conflict with CORBA's | |
264 @code{idl-mode}, defined in Emacs in the file @file{cc-mode.el}. | |
265 | |
266 In this manual, each section ends with a list of related user options. | |
267 Don't be confused by the sheer number of options available --- in most | |
268 cases the default settings are just fine. The variables are listed here | |
269 to make sure you know where to look if you want to change anything. For | |
270 a full description of what a particular variable does and how to | |
271 configure it, see the documentation string of that variable (available | |
272 with @kbd{C-h v}). Some configuration examples are also given in the | |
273 appendix. | |
274 | |
275 @node IDLWAVE in a Nutshell, Getting Started, Introduction, Top | |
276 @chapter IDLWAVE in a Nutshell | |
277 @cindex Summary of important commands | |
278 @cindex IDLWAVE in a Nutshell | |
279 @cindex Nutshell, IDLWAVE in a | |
280 | |
281 @subheading Editing IDL Programs | |
282 | |
283 @multitable @columnfractions .15 .85 | |
284 @item @key{TAB} | |
285 @tab Indent the current line relative to context. | |
286 @item @kbd{C-M-\} | |
287 @tab Re-indent all lines in the current region. | |
288 @item @kbd{C-M-q} | |
289 @tab Re-indent all lines in the current routine. | |
290 @item @kbd{C-u @key{TAB}} | |
291 @tab Re-indent all lines in the current statement. | |
292 @item @kbd{M-@key{RET}} | |
293 @tab Start a continuation line, splitting the current line at point. | |
294 @item @kbd{M-;} | |
295 @tab Start new comment at line beginning or after code, or (un)comment | |
296 highlighted region. | |
297 @item @kbd{M-q} | |
298 @tab Fill the current comment paragraph. | |
299 @item @kbd{C-c ?} | |
300 @tab Display calling sequence and keywords for the procedure or function call | |
301 at point. | |
302 @item @kbd{M-?} | |
303 @tab Load context sensitive online help for nearby routine, keyword, etc. | |
304 @item @kbd{M-@key{TAB}} | |
305 @tab Complete a procedure name, function name or keyword in the buffer. | |
306 @item @kbd{C-c C-i} | |
307 @tab Update IDLWAVE's knowledge about functions and procedures. | |
308 @item @kbd{C-c C-v} | |
309 @tab Visit the source code of a procedure/function. | |
310 @item @kbd{C-u C-c C-v} | |
311 @tab Visit the source code of a procedure/function in this buffer. | |
312 @item @kbd{C-c C-h} | |
313 @tab Insert a standard documentation header. | |
314 @item @kbd{C-c @key{RET}} | |
315 @tab Insert a new timestamp and history item in the documentation header. | |
316 @end multitable | |
317 | |
318 @subheading Running the IDLWAVE Shell, Debugging Programs | |
319 | |
320 @multitable @columnfractions .15 .85 | |
321 @item @kbd{C-c C-s} | |
322 @tab Start IDL as a subprocess and/or switch to the shell buffer. | |
323 @item @key{Up}, @kbd{M-p} | |
324 @tab Cycle back through IDL command history. | |
325 @item @key{Down},@kbd{M-n} | |
326 @tab Cycle forward. | |
327 @item @kbd{@key{TAB}} | |
328 @tab Complete a procedure name, function name or keyword in the shell buffer. | |
329 @item @kbd{C-c C-d C-c} | |
330 @tab Save and compile the source file in the current buffer. | |
331 @item @kbd{C-c C-d C-e} | |
332 @tab Compile and run the current region. | |
333 @item @kbd{C-c C-d C-x} | |
334 @tab Go to next syntax error. | |
335 @item @kbd{C-c C-d C-v} | |
336 @tab Switch to electric debug mode. | |
337 @item @kbd{C-c C-d C-b} | |
338 @tab Set a breakpoint at the nearest viable source line. | |
339 @item @kbd{C-c C-d C-d} | |
340 @tab Clear the nearest breakpoint. | |
341 @item @kbd{C-c C-d [} | |
342 @tab Go to the previous breakpoint. | |
343 @item @kbd{C-c C-d ]} | |
344 @tab Go to the next breakpoint. | |
345 @item @kbd{C-c C-d C-p} | |
346 @tab Print the value of the expression near point in IDL. | |
347 @end multitable | |
348 | |
349 @subheading Commonly used Settings in @file{.emacs} | |
350 @lisp | |
351 ;; Change the indentation preferences | |
352 ;; Start autoloading routine info after 2 idle seconds | |
353 (setq idlwave-init-rinfo-when-idle-after 2) | |
354 ;; Pad operators with spaces | |
355 (setq idlwave-do-actions t | |
356 idlwave-surround-by-blank t) | |
357 ;; Syntax Highlighting | |
358 (add-hook 'idlwave-mode-hook 'turn-on-font-lock) | |
359 ;; Automatically start the shell when needed | |
360 (setq idlwave-shell-automatic-start t) | |
361 ;; Bind debugging commands with CONTROL and SHIFT modifiers | |
362 (setq idlwave-shell-debug-modifiers '(control shift)) | |
363 @end lisp | |
364 | |
365 @html | |
366 <A NAME="TUTORIAL"></A> | |
367 @end html | |
368 | |
369 @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top | |
370 @chapter Getting Started (Tutorial) | |
371 @cindex Quick-Start | |
372 @cindex Tutorial | |
373 @cindex Getting Started | |
374 | |
375 @menu | |
376 * Lesson I -- Development Cycle:: | |
377 * Lesson II -- Customization:: | |
378 * Lesson III -- User Catalog:: | |
379 @end menu | |
380 | |
381 @node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started | |
382 @section Lesson I: Development Cycle | |
383 | |
384 The purpose of this tutorial is to guide you through a very basic | |
385 development cycle using IDLWAVE. We will paste a simple program into | |
386 a buffer and use the shell to compile, debug and run it. On the way | |
387 we will use many of the important IDLWAVE commands. Note, however, | |
388 that IDLWAVE has many more capabilities than covered here, which can | |
389 be discovered by reading the entire manual, or hovering over the | |
390 shoulder of your nearest IDLWAVE guru for a few days. | |
391 | |
392 It is assumed that you have access to Emacs or XEmacs with the full | |
393 IDLWAVE package including online help. We also assume that you are | |
394 familiar with Emacs and can read the nomenclature of key presses in | |
395 Emacs (in particular, @kbd{C} stands for @key{CONTROL} and @kbd{M} for | |
396 @key{META} (often the @key{ALT} key carries this functionality)). | |
397 | |
398 Open a new source file by typing: | |
399 | |
400 @example | |
401 @kbd{C-x C-f tutorial.pro @key{RET}} | |
402 @end example | |
403 | |
404 A buffer for this file will pop up, and it should be in IDLWAVE mode, | |
405 indicated in the mode line just below the editing window. Also, the | |
406 menu bar should contain @samp{IDLWAVE}. | |
407 | |
408 Now cut-and-paste the following code, also available as | |
409 @file{tutorial.pro} in the IDLWAVE distribution. | |
410 | |
411 @example | |
412 function daynr,d,m,y | |
413 ;; compute a sequence number for a date | |
414 ;; works 1901-2099. | |
415 if y lt 100 then y = y+1900 | |
416 if m le 2 then delta = 1 else delta = 0 | |
417 m1 = m + delta*12 + 1 | |
418 y1 = y * delta | |
419 return, d + floor(m1*30.6)+floor(y1*365.25)+5 | |
420 end | |
421 | |
422 function weekday,day,month,year | |
423 ;; compute weekday number for date | |
424 nr = daynr(day,month,year) | |
425 return, nr mod 7 | |
426 end | |
427 | |
428 pro plot_wday,day,month | |
429 ;; Plot the weekday of a date in the first 10 years of this century. | |
430 years = 2000,+indgen(10) | |
431 wdays = intarr(10) | |
432 for i=0,n_elements(wdays)-1 do begin | |
433 wdays[i] = weekday(day,month,years[i]) | |
434 end | |
435 plot,years,wdays,YS=2,YT="Wday (0=Sunday)" | |
436 end | |
437 @end example | |
438 | |
439 The indentation probably looks funny, since it's different from the | |
440 settings you use, so use the @key{TAB} key in each line to | |
441 automatically line it up (or, more quickly, @emph{select} the entire | |
442 buffer with @kbd{C-x h}, and indent the whole region with | |
443 @kbd{C-M-\}). Notice how different syntactical elements are | |
444 highlighted in different colors, if you have set up support for | |
445 font-lock. | |
446 | |
447 Let's check out two particular editing features of IDLWAVE. Place the | |
448 cursor after the @code{end} statement of the @code{for} loop and press | |
449 @key{SPC}. IDLWAVE blinks back to the beginning of the block and | |
450 changes the generic @code{end} to the specific @code{endfor} | |
451 automatically (as long as the variable @code{idlwave-expand-generic-end} | |
452 is turned on --- @pxref{Lesson II -- Customization}). Now place the | |
453 cursor in any line you would like to split and press @kbd{M-@key{RET}}. | |
454 The line is split at the cursor position, with the continuation @samp{$} | |
455 and indentation all taken care of. Use @kbd{C-/} to undo the last | |
456 change. | |
457 | |
458 The procedure @code{plot_wday} is supposed to plot the day of the week | |
459 of a given date for the first 10 years of the 21st century. As in | |
460 most code, there are a few bugs, which we are going to use IDLWAVE to | |
461 help us fix. | |
462 | |
463 First, let's launch the IDLWAVE shell. You do this with the command | |
464 @kbd{C-c C-s}. The Emacs window will split or another window will popup | |
465 to display IDL running in a shell interaction buffer. Type a few | |
466 commands like @code{print,!PI} to convince yourself that you can work | |
467 there just as well as in a terminal, or the IDLDE. Use the arrow keys | |
468 to cycle through your command history. Are we having fun now? | |
469 | |
470 Now go back to the source window and type @kbd{C-c C-d C-c} to compile | |
471 the program. If you watch the shell buffer, you see that IDLWAVE types | |
472 @samp{.run "tutorial.pro"} for you. But the compilation fails because | |
473 there is a comma in the line @samp{years=...}. The line with the error | |
474 is highlighted and the cursor positioned at the error, so remove the | |
475 comma (you should only need to hit @kbd{Delete}!). Compile again, using | |
476 the same keystrokes as before. Notice that the file is automatically | |
477 saved for you. This time everything should work fine, and you should | |
478 see the three routines compile. | |
479 | |
480 Now we want to use the command to plot the day of the week on January | |
481 1st. We could type the full command ourselves, but why do that? Go | |
482 back to the shell window, type @samp{plot_} and hit @key{TAB}. After | |
483 a bit of a delay (while IDLWAVE initializes its routine info database, | |
484 if necessary), the window will split to show all procedures it knows | |
485 starting with that string, and @w{@code{plot_wday}} should be one of | |
486 them. Saving the buffer alerted IDLWAVE about this new routine. | |
487 Click with the middle mouse button on @code{plot_wday} and it will be | |
488 copied to the shell buffer, or if you prefer, add @samp{w} to | |
489 @samp{plot_} to make it unambiguous (depending on what other routines | |
490 starting with @samp{plot_} you have installed on your system), hit | |
491 @key{TAB} again, and the full routine name will be completed. Now | |
492 provide the two arguments: | |
493 | |
494 @example | |
495 plot_wday,1,1 | |
496 @end example | |
497 | |
498 @noindent and press @key{RET}. This fails with an error message telling | |
499 you the @code{YT} keyword to plot is ambiguous. What are the allowed | |
500 keywords again? Go back to the source window and put the cursor into | |
501 the `plot' line and press @kbd{C-c ?}. This shows the routine info | |
502 window for the plot routine, which contains a list of keywords, along | |
503 with the argument list. Oh, we wanted @code{YTITLE}. Fix that up. | |
504 Recompile with @kbd{C-c C-d C-c}. Jump back into the shell with | |
505 @kbd{C-c C-s}, press the @key{UP} arrow to recall the previous command | |
506 and execute again. | |
507 | |
508 This time we get a plot, but it is pretty ugly --- the points are all | |
509 connected with a line. Hmm, isn't there a way for @code{plot} to use | |
510 symbols instead? What was that keyword? Position the cursor on the | |
511 plot line after a comma (where you'd normally type a keyword), and hit | |
512 @kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, | |
513 there it is, @code{PSYM}. Middle click to insert it. An @samp{=} | |
514 sign is included for you too. Now what were the values of @code{PSYM} | |
515 supposed to be? With the cursor on or after the keyword, press | |
516 @kbd{M-?} for online help (alternatively, you could have right clicked | |
517 on the colored keyword itself in the completion list). A browser will | |
518 pop up showing the HTML documentation for the @code{PYSM} keyword. | |
519 OK, let's use diamonds=4. Fix this, recompile (you know the command | |
520 by now: @kbd{C-c C-d C-c}), go back to the shell (if it's vanished, | |
521 you know what to do: @kbd{C-c C-s}) and execute again. Now things | |
522 look pretty good. | |
523 | |
524 Let's try a different day --- how about April fool's day? | |
525 | |
526 @example | |
527 plot_wday,1,4 | |
528 @end example | |
529 | |
530 Oops, this looks very wrong. All April Fool's days cannot be Fridays! | |
531 We've got a bug in the program, perhaps in the @code{daynr} function. | |
532 Let's put a breakpoint on the last line there. Position the cursor on | |
533 the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a | |
534 breakpoint (as you see in the shell window), and the break line is | |
535 indicated. Back to the shell buffer, re-execute the previous command. | |
536 IDL stops at the line with the breakpoint. Now hold down the SHIFT | |
537 key and click with the middle mouse button on a few variables there: | |
538 @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't | |
539 the correct type. CONTROL-SHIFT middle-click on it for help. Well, | |
540 it's an integer, so that's not the problem. Aha, @samp{y1} is zero, | |
541 but it should be the year, depending on delta. Shift click | |
542 @samp{delta} to see that it's 0. Below, we see the offending line: | |
543 @samp{y1=y*delta...} the multiplication should have been a minus sign! | |
544 Hit @kbd{q} to exit the debugging mode, and fix the line to read: | |
545 | |
546 @example | |
547 y1 = y - delta | |
548 @end example | |
549 | |
550 Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the | |
551 command. Everything should now work fine. How about those leap years? | |
552 Change the code to plot 100 years and see that every 28 years, the | |
553 sequence of weekdays repeats. | |
554 | |
555 @node Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started | |
556 @section Lesson II: Customization | |
557 | |
558 Emacs is probably the most customizable piece of software ever written, | |
559 and it would be a shame if you did not make use of this to adapt IDLWAVE | |
560 to your own preferences. Customizing Emacs or IDLWAVE is accomplished | |
561 by setting Lisp variables in the @file{.emacs} file in your home | |
562 directory --- but do not be dismayed; for the most part, you can just | |
563 copy and work from the examples given here. | |
564 | |
565 Let's first use a boolean variable. These are variables which you turn | |
566 on or off, much like a checkbox. A value of @samp{t} means on, a value | |
567 of @samp{nil} means off. Copy the following line into your | |
568 @file{.emacs} file, exit and restart Emacs. | |
569 | |
570 @lisp | |
571 (setq idlwave-reserved-word-upcase t) | |
572 @end lisp | |
573 | |
574 When this option is turned on, each reserved word you type into an IDL | |
575 source buffer will be converted to upper case when you press @key{SPC} | |
576 or @key{RET} right after the word. Try it out! @samp{if} changes to | |
577 @samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this | |
578 behavior, remove the option again from your @file{.emacs} file and | |
579 restart Emacs. | |
580 | |
581 You likely have your own indentation preferences for IDL code. For | |
582 example, some may prefer to indent the main block of an IDL program | |
583 slightly from the margin and use only 3 spaces as indentation between | |
584 @code{BEGIN} and @code{END}. Try the following lines in @file{.emacs}: | |
585 | |
586 @lisp | |
587 (setq idlwave-main-block-indent 1) | |
588 (setq idlwave-block-indent 3) | |
589 (setq idlwave-end-offset -3) | |
590 @end lisp | |
591 | |
592 Restart Emacs, and re-indent the program we developed in the first part | |
593 of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may want to keep | |
594 these lines in @file{.emacs}, with values adjusted to your likings. If | |
595 you want to get more information about any of these variables, type, | |
596 e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. To find which | |
597 variables can be customized, look for items marked @samp{User Option:} | |
598 throughout this manual. | |
599 | |
600 If you cannot seem to master this Lisp customization in @file{.emacs}, | |
601 there is another, more user-friendly way to customize all the IDLWAVE | |
602 variables. You can access it through the IDLWAVE menu in one of the | |
603 @file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE | |
604 Group}. Here you'll be presented with all the various variables grouped | |
605 into categories. You can navigate the hierarchy (e.g. @samp{IDLWAVE | |
606 Code Formatting->Idlwave Abbrev And Indent Action->Idlwave Expand | |
607 Generic End} to turn on @code{END} expansion), read about the variables, | |
608 change them, and `Save for Future Sessions'. Few of these variables | |
609 need customization, but you can exercise considerable control over | |
610 IDLWAVE's functionality with them. | |
611 | |
612 You may also find the key bindings used for the debugging commands too | |
613 long and complicated. Often we have heard complaints along the lines | |
614 of, ``Do I really have to go through the finger gymnastics of @kbd{C-c | |
615 C-d C-c} to run a simple command?'' Due to Emacs rules and | |
616 conventions, shorter bindings cannot be set by default, but you can | |
617 easily enable them. First, there is a way to assign all debugging | |
618 commands in a single sweep to another simpler combination. The only | |
619 problem is that we have to use something which Emacs does not need for | |
620 other important commands. One good option is to execute debugging | |
621 commands by holding down @key{CONTROL} and @key{SHIFT} while pressing | |
622 a single character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} | |
623 for compiling the current source file, @kbd{C-S-a} for deleting all | |
624 breakpoints (try it, it's easier). You can enable this with: | |
625 | |
626 @lisp | |
627 (setq idlwave-shell-debug-modifiers '(shift control)) | |
628 @end lisp | |
629 | |
630 @noindent If you have a special keyboard with, for example, a | |
631 @key{SUPER} key, you could even shorten that: | |
632 | |
633 @lisp | |
634 (setq idlwave-shell-debug-modifiers '(super)) | |
635 @end lisp | |
636 | |
637 @noindent to get compilation on @kbd{S-c}. Often, a modifier key like | |
638 @key{SUPER} or @key{HYPER} is bound or can be bound to an otherwise | |
639 unused key on your keyboard --- consult your system documentation. | |
640 | |
641 You can also assign specific commands to keys. This you must do in the | |
642 @emph{mode-hook}, a special function which is run when a new IDLWAVE | |
643 buffer gets set up. The possibilities for key customization are | |
644 endless. Here we set function keys f4-f8 to common debugging commands. | |
645 | |
646 @lisp | |
647 ;; First for the source buffer | |
648 (add-hook 'idlwave-mode-hook | |
649 (lambda () | |
650 (local-set-key [f4] 'idlwave-shell-retall) | |
651 (local-set-key [f5] 'idlwave-shell-break-here) | |
652 (local-set-key [f6] 'idlwave-shell-clear-current-bp) | |
653 (local-set-key [f7] 'idlwave-shell-cont) | |
654 (local-set-key [f8] 'idlwave-shell-clear-all-bp))) | |
655 ;; Then for the shell buffer | |
656 (add-hook 'idlwave-shell-mode-hook | |
657 (lambda () | |
658 (local-set-key [f4] 'idlwave-shell-retall) | |
659 (local-set-key [f5] 'idlwave-shell-break-here) | |
660 (local-set-key [f6] 'idlwave-shell-clear-current-bp) | |
661 (local-set-key [f7] 'idlwave-shell-cont) | |
662 (local-set-key [f8] 'idlwave-shell-clear-all-bp))) | |
663 @end lisp | |
664 | |
665 @node Lesson III -- User Catalog, , Lesson II -- Customization, Getting Started | |
666 @section Lesson III: User and Library Catalogs | |
667 | |
668 We have already used the routine info display in the first part of this | |
669 tutorial. This was the invoked using @kbd{C-c ?}, and displays | |
670 information about the IDL routine near the cursor position. Wouldn't it | |
671 be nice to have the same kind of information available for your own | |
672 routines and for the huge amount of code in major libraries like JHUPL | |
673 or the IDL-Astro library? In many cases, you may already have this | |
674 information. Files named @file{.idlwave_catalog} in library directories | |
675 contain scanned information on the routines in that directory; many | |
676 popular libraries ship with these ``library catalogs'' pre-scanned. | |
677 Users can scan their own routines in one of two ways: either using the | |
678 supplied tool to scan directories and build their own | |
679 @file{.idlwave_catalog} files, or using the built-in method to create a | |
680 single ``user catalog'', which we'll show here. @xref{Catalogs}, for | |
681 more information on choosing which method to use. | |
682 | |
683 To build a user catalog, select @code{Routine Info/Select Catalog | |
684 Directories} from the IDLWAVE entry in the menu bar. If necessary, | |
685 start the shell first with @kbd{C-c C-s} (@pxref{Starting the Shell}). | |
686 IDLWAVE will find out about the IDL @code{!PATH} variable and offer a | |
687 list of directories on the path. Simply select them all (or whichever | |
688 you want --- directories with existing library catalogs will not be | |
689 selected by default) and click on the @samp{Scan&Save} button. Then | |
690 go for a cup of coffee while IDLWAVE collects information for each and | |
691 every IDL routine on your search path. All this information is | |
692 written to the file @file{.idlwave/idlusercat.el} in your home | |
693 directory and will from now on automatically load whenever you use | |
694 IDLWAVE. You may find it necessary to rebuild the catalog on occasion | |
695 as your local libraries change, or build a library catalog for those | |
696 directories instead. Invoke routine info (@kbd{C-c ?}) or completion | |
697 (@kbd{M-@key{TAB}}) on any routine or partial routine name you know to | |
698 be located in the library. E.g., if you have scanned the IDL-Astro | |
699 library: | |
700 | |
701 @example | |
702 a=readf@key{M-@key{TAB}} | |
703 @end example | |
704 | |
705 expands to `readfits('. Then try | |
706 | |
707 @example | |
708 a=readfits(@key{C-c ?} | |
709 @end example | |
710 | |
711 and you get: | |
712 | |
713 @example | |
714 Usage: Result = READFITS(filename, header, heap) | |
715 ... | |
716 @end example | |
717 | |
718 I hope you made it until here. Now you are set to work with IDLWAVE. | |
719 On the way you will want to change other things, and to learn more | |
720 about the possibilities not discussed in this short tutorial. Read | |
721 the manual, look at the documentation strings of interesting variables | |
722 (with @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the | |
723 remaining questions on the newsgroup @code{comp.lang.idl-pvwave}. | |
724 | |
725 @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top | |
726 @chapter The IDLWAVE Major Mode | |
727 @cindex IDLWAVE major mode | |
728 @cindex Major mode, @code{idlwave-mode} | |
729 | |
730 The IDLWAVE major mode supports editing IDL source files. In this | |
731 chapter we describe the main features of the mode and how to customize | |
732 them. | |
733 | |
734 @menu | |
735 * Code Formatting:: Making code look nice | |
736 * Routine Info:: Calling Sequence and Keyword List | |
737 * Online Help:: One key press from source to help | |
738 * Completion:: Completing routine names and Keywords | |
739 * Routine Source:: Finding routines, the easy way | |
740 * Resolving Routines:: Force the Shell to compile a routine | |
741 * Code Templates:: Frequent code constructs | |
742 * Abbreviations:: Abbreviations for common commands | |
743 * Actions:: Changing case, Padding, End checking | |
744 * Doc Header:: Inserting a standard header | |
745 * Motion Commands:: Moving through the structure of a program | |
746 * Misc Options:: Things that fit nowhere else | |
747 @end menu | |
748 | |
749 @node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode | |
750 @section Code Formatting | |
751 @cindex Code formatting | |
752 @cindex Formatting, of code | |
753 | |
754 @menu | |
755 * Code Indentation:: Reflecting the logical structure | |
756 * Continued Statement Indentation:: | |
757 * Comment Indentation:: Special indentation for comment lines | |
758 * Continuation Lines:: Splitting statements over lines | |
759 * Syntax Highlighting:: Font-lock support | |
760 * Octals and Highlighting:: Why "123 causes problems | |
761 @end menu | |
762 | |
763 The IDL language, with its early roots in FORTRAN, modern | |
764 implementation in C, and liberal borrowing of features of many vector | |
765 and other languages along its 25+ year history, has inherited an | |
766 unusual mix of syntax elements. Left to his or her own devices, a | |
767 novice IDL programmer will often conjure code which is very difficult | |
768 to read and impossible to adapt. Much can be gleaned from studying | |
769 available IDL code libraries for coding style pointers, but, due to | |
770 the variety of IDL syntax elements, replicating this style can be | |
771 challenging at best. Luckily, IDLWAVE understands the structure of | |
772 IDL code very well, and takes care of almost all formatting issues for | |
773 you. After configuring it to match your coding standards, you can | |
774 rely on it to help keep your code neat and organized. | |
775 | |
776 | |
777 @node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting | |
778 @subsection Code Indentation | |
779 @cindex Code indentation | |
780 @cindex Indentation | |
781 | |
782 Like all Emacs programming modes, IDLWAVE performs code indentation. | |
783 The @key{TAB} key indents the current line relative to context. | |
784 @key{LFD} insert a newline and indents the new line. The indentation is | |
785 governed by a number of variables. IDLWAVE indents blocks (between | |
786 @code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and | |
787 continuation lines. | |
788 | |
789 @cindex Foreign code, adapting | |
790 @cindex Indentation, of foreign code | |
791 @kindex C-M-\ | |
792 To re-indent a larger portion of code (e.g. when working with foreign | |
793 code written with different conventions), use @kbd{C-M-\} | |
794 (@code{indent-region}) after marking the relevant code. Useful marking | |
795 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current | |
796 subprogram). The command @kbd{C-M-q} reindents the entire current | |
797 routine. @xref{Actions}, for information how to impose additional | |
798 formatting conventions on foreign code. | |
799 | |
800 @defopt idlwave-main-block-indent (@code{2}) | |
801 Extra indentation for the main block of code. That is the block between | |
802 the FUNCTION/PRO statement and the END statement for that program | |
803 unit. | |
804 @end defopt | |
805 | |
806 @defopt idlwave-block-indent (@code{3}) | |
807 Extra indentation applied to block lines. If you change this, you | |
808 probably also want to change @code{idlwave-end-offset}. | |
809 @end defopt | |
810 | |
811 @defopt idlwave-end-offset (@code{-3}) | |
812 Extra indentation applied to block END lines. A value equal to negative | |
813 @code{idlwave-block-indent} will make END lines line up with the block | |
814 BEGIN lines. | |
815 @end defopt | |
816 | |
817 @node Continued Statement Indentation, Comment Indentation, Code Indentation, Code Formatting | |
818 @subsection Continued Statement Indentation | |
819 @cindex Indentation, continued statement | |
820 @cindex Continued statement indentation | |
821 Continuation lines (following a line ending with @code{$}) can receive a | |
822 fixed indentation offset from the main level, but in several situations | |
823 IDLWAVE can use a special form of indentation which aligns continued | |
824 statements more naturally. Special indentation is calculated for | |
825 continued routine definition statements and calls, enclosing parentheses | |
826 (like function calls, structure/class definitions, explicit structures | |
827 or lists, etc.), and continued assignments. An attempt is made to line | |
828 up with the first non-whitespace character after the relevant opening | |
829 punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}). For | |
830 lines without any non-comment characters on the line with the opening | |
831 punctuation, the continued line(s) are aligned just past the | |
832 punctuation. An example: | |
833 | |
834 @example | |
835 function foo, a, b, $ | |
836 c, d | |
837 bar = sin( a + b + $ | |
838 c + d) | |
839 end | |
840 @end example | |
841 @noindent | |
842 | |
843 The only drawback to this special continued statement indentation is | |
844 that it consumes more space, e.g., for long function names or left hand | |
845 sides of an assignment: | |
846 | |
847 @example | |
848 function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $ | |
849 c, d | |
850 @end example | |
851 | |
852 You can instruct IDLWAVE when to avoid using this special continuation | |
853 indentation by setting the variable | |
854 @code{idlwave-max-extra-continuation-indent}, which specifies the | |
855 maximum additional indentation beyond the basic indent to be | |
856 tolerated, otherwise defaulting to a fixed-offset from the enclosing | |
857 indent (the size of which offset is set in | |
858 @code{idlwave-continuation-indent}). As a special case, continuations | |
859 of routine calls without any arguments or keywords will @emph{not} | |
860 align the continued line, under the assumption that you continued | |
861 because you needed the space. | |
862 | |
863 Also, since the indentation level can be somewhat dynamic in continued | |
864 statements with special continuation indentation, especially if | |
865 @code{idlwave-max-extra-continuation-indent} is small, the key | |
866 @kbd{C-u @key{TAB}} will re-indent all lines in the current statement. | |
867 Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil}, | |
868 overrides the @code{idlwave-max-extra-continuation-indent} limit, for | |
869 parentheses only, forcing them always to line up. | |
870 | |
871 | |
872 @defopt idlwave-continuation-indent (@code{2}) | |
873 Extra indentation applied to normal continuation lines. | |
874 @end defopt | |
875 | |
876 @defopt idlwave-max-extra-continuation-indent (@code{20}) | |
877 The maximum additional indentation (over the basic continuation-indent) | |
878 that will be permitted for special continues. To effectively disable | |
879 special continuation indentation, set to @code{0}. To enable it | |
880 constantly, set to a large number (like @code{100}). Note that the | |
881 indentation in a long continued statement never decreases from line to | |
882 line, outside of nested parentheses statements. | |
883 @end defopt | |
884 | |
885 @defopt idlwave-indent-to-open-paren (@code{t}) | |
886 Non-@code{nil} means indent continuation lines to innermost open | |
887 parenthesis, regardless of whether the | |
888 @code{idlwave-max-extra-continuation-indent} limit is satisfied. | |
889 @end defopt | |
890 | |
891 @node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting | |
892 @subsection Comment Indentation | |
893 @cindex Comment indentation | |
894 @cindex Hanging paragraphs | |
895 @cindex Paragraphs, filling | |
896 @cindex Paragraphs, hanging | |
897 | |
898 In IDL, lines starting with a @samp{;} are called @emph{comment lines}. | |
899 Comment lines are indented as follows: | |
900 | |
901 @multitable @columnfractions .1 .90 | |
902 @item @code{;;;} | |
903 @tab The indentation of lines starting with three semicolons remains | |
904 unchanged. | |
905 @item @code{;;} | |
906 @tab Lines starting with two semicolons are indented like the surrounding code. | |
907 @item @code{;} | |
908 @tab Lines starting with a single semicolon are indented to a minimum column. | |
909 @end multitable | |
910 | |
911 @noindent | |
912 The indentation of comments starting in column 0 is never changed. | |
913 | |
914 @defopt idlwave-no-change-comment | |
915 The indentation of a comment starting with this regexp will not be | |
916 changed. | |
917 @end defopt | |
918 | |
919 @defopt idlwave-begin-line-comment | |
920 A comment anchored at the beginning of line. | |
921 @end defopt | |
922 | |
923 @defopt idlwave-code-comment | |
924 A comment that starts with this regexp is indented as if it is a part of | |
925 IDL code. | |
926 @end defopt | |
927 | |
928 @node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting | |
929 @subsection Continuation Lines and Filling | |
930 @cindex Continuation lines | |
931 @cindex Line splitting | |
932 @cindex String splitting | |
933 @cindex Splitting, of lines | |
934 | |
935 @kindex M-@key{RET} | |
936 In IDL, a newline character terminates a statement unless preceded by a | |
937 @samp{$}. If you would like to start a continuation line, use | |
938 @kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}. | |
939 It inserts the continuation character @samp{$}, terminates the line and | |
940 indents the new line. The command @kbd{M-@key{RET}} can also be invoked | |
941 inside a string to split it at that point, in which case the @samp{+} | |
942 concatenation operator is used. | |
943 | |
944 @cindex Filling | |
945 @cindex @code{auto-fill-mode} | |
946 @cindex Hanging paragraphs | |
947 When filling comment paragraphs, IDLWAVE overloads the normal filling | |
948 functions and uses a function which creates the hanging paragraphs | |
949 customary in IDL routine headers. When @code{auto-fill-mode} is turned | |
950 on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If the | |
951 first line of a paragraph contains a match for | |
952 @code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent | |
953 lines are positioned to line up after it, as in the following example. | |
954 | |
955 @example | |
956 @group | |
957 ;================================= | |
958 ; x - an array containing | |
959 ; lots of interesting numbers. | |
960 ; | |
961 ; y - another variable where | |
962 ; a hanging paragraph is used | |
963 ; to describe it. | |
964 ;================================= | |
965 @end group | |
966 @end example | |
967 | |
968 @kindex M-q | |
969 You can also refill a comment at any time paragraph with @kbd{M-q}. | |
970 Comment delimiting lines as in the above example, consisting of one or | |
971 more @samp{;} followed by one or more of the characters @samp{+=-_*}, | |
972 are kept in place, as is. | |
973 | |
974 @defopt idlwave-fill-comment-line-only (@code{t}) | |
975 Non-@code{nil} means auto fill will only operate on comment lines. | |
976 @end defopt | |
977 | |
978 @defopt idlwave-auto-fill-split-string (@code{t}) | |
979 Non-@code{nil} means auto fill will split strings with the IDL @samp{+} | |
980 operator. | |
981 @end defopt | |
982 | |
983 @defopt idlwave-split-line-string (@code{t}) | |
984 Non-@code{nil} means @code{idlwave-split-line} will split strings with | |
985 @samp{+}. | |
986 @end defopt | |
987 | |
988 @defopt idlwave-hanging-indent (@code{t}) | |
989 Non-@code{nil} means comment paragraphs are indented under the hanging | |
990 indent given by @code{idlwave-hang-indent-regexp} match in the first | |
991 line of the paragraph. | |
992 @end defopt | |
993 | |
994 @defopt idlwave-hang-indent-regexp (@code{"- "}) | |
995 Regular expression matching the position of the hanging indent | |
996 in the first line of a comment paragraph. | |
997 @end defopt | |
998 | |
999 @defopt idlwave-use-last-hang-indent (@code{nil}) | |
1000 Non-@code{nil} means use last match on line for | |
1001 @code{idlwave-indent-regexp}. | |
1002 @end defopt | |
1003 | |
1004 @node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting | |
1005 @subsection Syntax Highlighting | |
1006 @cindex Syntax highlighting | |
1007 @cindex Highlighting of syntax | |
1008 @cindex Font lock | |
1009 | |
1010 Highlighting of keywords, comments, strings etc. can be accomplished | |
1011 with @code{font-lock}. If you are using @code{global-font-lock-mode} | |
1012 (in Emacs), or have @code{font-lock} turned on in any other buffer in | |
1013 XEmacs, it should also automatically work in IDLWAVE buffers. If you'd | |
1014 prefer invoking font-lock individually by mode, you can enforce it in | |
1015 @code{idlwave-mode} with the following line in your @file{.emacs}: | |
1016 | |
1017 @lisp | |
1018 (add-hook 'idlwave-mode-hook 'turn-on-font-lock) | |
1019 @end lisp | |
1020 | |
1021 @noindent IDLWAVE supports 3 increasing levels of syntax highlighting. | |
1022 The variable @code{font-lock-maximum-decoration} determines which level | |
1023 is selected. Individual categories of special tokens can be selected | |
1024 for highlighting using the variable | |
1025 @code{idlwave-default-font-lock-items}. | |
1026 | |
1027 @defopt idlwave-default-font-lock-items | |
1028 Items which should be fontified on the default fontification level | |
1029 2. | |
1030 @end defopt | |
1031 | |
1032 @node Octals and Highlighting, , Syntax Highlighting, Code Formatting | |
1033 @subsection Octals and Highlighting | |
1034 @cindex Syntax highlighting, Octals | |
1035 @cindex Highlighting of syntax, Octals | |
1036 | |
1037 A rare syntax highlighting problem results from an extremely unfortunate | |
1038 notation for octal numbers in IDL: @code{"123}. This unpaired quotation | |
1039 mark is very difficult to parse, given that it can be mixed on a single | |
1040 line with any number of strings. Emacs will incorrectly identify this | |
1041 as a string, and the highlighting of following lines of code can be | |
1042 distorted, since the string is never terminated. | |
1043 | |
1044 One solution to this involves terminating the mistakenly identified | |
1045 string yourself by providing a closing quotation mark in a comment: | |
1046 | |
1047 @example | |
1048 string("305B) + $ ;" <--- for font-lock | |
1049 ' is an Angstrom.' | |
1050 @end example | |
1051 | |
1052 @noindent A far better solution is to abandon this notation for octals | |
1053 altogether, and use the more sensible alternative IDL provides: | |
1054 | |
1055 @example | |
1056 string('305'OB) + ' is an Angstrom.' | |
1057 @end example | |
1058 | |
1059 @noindent This simultaneously solves the font-lock problem and is more | |
1060 consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}. | |
1061 | |
1062 @node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode | |
1063 @section Routine Info | |
1064 @cindex Routine info | |
1065 @cindex Updating routine info | |
1066 @cindex Scanning buffers for routine info | |
1067 @cindex Buffers, scanning for routine info | |
1068 @cindex Shell, querying for routine info | |
1069 | |
1070 @kindex C-c C-i | |
1071 IDL comes bundled with more than one thousand procedures, functions | |
1072 and object methods, and large libraries typically contain hundreds or | |
1073 even thousands more (each with a few to tens of keywords and | |
1074 arguments). This large command set can make it difficult to remember | |
1075 the calling sequence and keywords for the routines you use, but | |
1076 IDLWAVE can help. It builds up routine information from a wide | |
1077 variety of sources; IDLWAVE in fact knows far more about the | |
1078 @samp{.pro} routines on your system than IDL itself! It maintains a | |
1079 list of all built-in routines, with calling sequences and | |
1080 keywords@footnote{This list is created by scanning the IDL manuals and | |
1081 might contain (very few) errors. Please report any errors to the | |
1082 maintainer, so that they can be fixed.}. It also scans Emacs buffers | |
1083 for routine definitions, queries the IDLWAVE-Shell for information | |
1084 about routines currently compiled there, and automatically locates | |
1085 library and user-created catalogs. This information is updated | |
1086 automatically, and so should usually be current. To force a global | |
1087 update and refresh the routine information, use @kbd{C-c C-i} | |
1088 (@code{idlwave-update-routine-info}). | |
1089 | |
1090 @kindex C-c ? | |
1091 To display the information about a routine, press @kbd{C-c ?}, which | |
1092 calls the command @code{idlwave-routine-info}. When the current cursor | |
1093 position is on the name or in the argument list of a procedure or | |
1094 function, information will be displayed about the routine. For example, | |
1095 consider the indicated cursor positions in the following line: | |
1096 | |
1097 @example | |
1098 plot,x,alog(x+5*sin(x) + 2), | |
1099 | | | | | | | | | |
1100 1 2 3 4 5 6 7 8 | |
1101 @end example | |
1102 | |
1103 @cindex Default routine, for info and help | |
1104 On positions 1,2 and 8, information about the @samp{plot} procedure will | |
1105 be shown. On positions 3,4, and 7, the @samp{alog} function will be | |
1106 described, while positions 5 and 6 will investigate the @samp{sin} | |
1107 function. | |
1108 | |
1109 When you ask for routine information about an object method, and the | |
1110 method exists in several classes, IDLWAVE queries for the class of the | |
1111 object, unless the class is already known through a text property on the | |
1112 @samp{->} operator (@pxref{Object Method Completion and Class | |
1113 Ambiguity}), or by having been explicitly included in the call | |
1114 (e.g. @code{a->myclass::Foo}). | |
1115 | |
1116 @cindex Calling sequences | |
1117 @cindex Keywords of a routine | |
1118 @cindex Routine source information | |
1119 The description displayed contains the calling sequence, the list of | |
1120 keywords and the source location of this routine. It looks like this: | |
1121 | |
1122 @example | |
1123 Usage: XMANAGER, NAME, ID | |
1124 Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER | |
1125 JUST_REG MODAL NO_BLOCK | |
1126 Source: SystemLib [LCSB] /soft1/idl53/lib/xmanager.pro | |
1127 @end example | |
1128 | |
1129 @cindex Categories, of routines | |
1130 @cindex Load-path shadows | |
1131 @cindex Shadows, load-path | |
1132 @cindex IDL variable @code{!PATH} | |
1133 @cindex @code{!PATH}, IDL variable | |
1134 @cindex IDL variable @code{!DIR} | |
1135 @cindex @code{!DIR}, IDL variable | |
1136 | |
1137 If a definition of this routine exists in several files accessible to | |
1138 IDLWAVE, several @samp{Source} lines will point to the different | |
1139 files. This may indicate that your routine is shadowing a system | |
1140 library routine, which may or may not be what you want | |
1141 (@pxref{Load-Path Shadows}). The information about the calling | |
1142 sequence and keywords is derived from the first source listed. | |
1143 Library routines are available only if you have scanned your local IDL | |
1144 directories or are using pre-scanned libraries (@pxref{Catalogs}). | |
1145 The source entry consists of a @emph{source category}, a set of | |
1146 @emph{flags} and the path to the @emph{source file}. The following | |
1147 default categories exist: | |
1148 | |
1149 @multitable @columnfractions .15 .85 | |
1150 @item @i{System} | |
1151 @tab A system routine of unknown origin. When the system library has | |
1152 been scanned as part of a catalog (@pxref{Catalogs}), this category | |
1153 will automatically split into the next two. | |
1154 @item @i{Builtin} | |
1155 @tab A builtin system routine with no source code available. | |
1156 @item @i{SystemLib} | |
1157 @tab A library system routine in the official lib directory @file{!DIR/lib}. | |
1158 @item @i{Obsolete} | |
1159 @tab A library routine in the official lib directory @file{!DIR/lib/obsolete}. | |
1160 @item @i{Library} | |
1161 @tab A routine in a file on IDL's search path @code{!PATH}. | |
1162 @item @i{Other} | |
1163 @tab Any other routine with a file not known to be on the search path. | |
1164 @item @i{Unresolved} | |
1165 @tab An otherwise unknown routine the shell lists as unresolved | |
1166 (referenced, but not compiled). | |
1167 @end multitable | |
1168 | |
1169 Any routines discovered in library catalogs (@pxref{Library | |
1170 Catalogs}), will display the category assigned during creation, | |
1171 e.g. @samp{NasaLib}. For routines not discovered in this way, you can | |
1172 create additional categories based on the routine's filename using the | |
1173 variable @code{idlwave-special-lib-alist}. | |
1174 | |
1175 @cindex Flags, in routine info | |
1176 @cindex Duplicate routines | |
1177 @cindex Multiply defined routines | |
1178 @cindex Routine definitions, multiple | |
1179 The flags @code{[LCSB]} indicate the source of the information IDLWAVE | |
1180 has regarding the file: from a library catalog (@w{@code{[L---]}}), | |
1181 from a user catalog (@w{@code{[-C--]}}, from the IDL Shell | |
1182 (@w{@code{[--S-]}}) or from an Emacs buffer (@w{@code{[---B]}}). | |
1183 Combinations are possible (a compiled library routine visited in a | |
1184 buffer might read @w{@code{[L-SB]}}). If a file contains multiple | |
1185 definitions of the same routine, the file name will be prefixed with | |
1186 @samp{(Nx)} where @samp{N} is the number of definitions. | |
1187 | |
1188 @cindex Online Help from the routine info buffer | |
1189 @cindex Active text, in routine info | |
1190 @cindex Inserting keywords, from routine info | |
1191 @cindex Source file, access from routine info | |
1192 Some of the text in the @file{*Help*} routine info buffer will be active | |
1193 (it is highlighted when the mouse moves over it). Typically, clicking | |
1194 with the right mouse button invokes online help lookup, and clicking | |
1195 with the middle mouse button inserts keywords or visits files: | |
1196 | |
1197 @multitable @columnfractions 0.15 0.85 | |
1198 @item @i{Usage} | |
1199 @tab If online help is installed, a click with the @emph{right} mouse | |
1200 button on the @i{Usage:} line will access the help for the | |
1201 routine (@pxref{Online Help}). | |
1202 @item @i{Keyword} | |
1203 @tab Online help about keywords is also available with the | |
1204 @emph{right} mouse button. Clicking on a keyword with the @emph{middle} | |
1205 mouse button will insert this keyword in the buffer from where | |
1206 @code{idlwave-routine-info} was called. Holding down @key{SHIFT} while | |
1207 clicking also adds the initial @samp{/}. | |
1208 @item @i{Source} | |
1209 @tab Clicking with the @emph{middle} mouse button on a @samp{Source} line | |
1210 finds the source file of the routine and visits it in another window. | |
1211 Another click on the same line switches back to the buffer from which | |
1212 @kbd{C-c ?} was called. If you use the @emph{right} mouse button, the | |
1213 source will not be visited by a buffer, but displayed in the online help | |
1214 window. | |
1215 @item @i{Classes} | |
1216 @tab The @i{Classes} line is only included in the routine info window if | |
1217 the current class inherits from other classes. You can click with the | |
1218 @emph{middle} mouse button to display routine info about the current | |
1219 method in other classes on the inheritance chain, if such a method | |
1220 exists there. | |
1221 @end multitable | |
1222 | |
1223 @defopt idlwave-resize-routine-help-window (@code{t}) | |
1224 Non-@code{nil} means resize the Routine-info @file{*Help*} window to | |
1225 fit the content. | |
1226 @end defopt | |
1227 | |
1228 @defopt idlwave-special-lib-alist | |
1229 Alist of regular expressions matching special library directories. | |
1230 @end defopt | |
1231 | |
1232 @defopt idlwave-rinfo-max-source-lines (@code{5}) | |
1233 Maximum number of source files displayed in the Routine Info window. | |
1234 @end defopt | |
1235 | |
1236 | |
1237 @html | |
1238 <A NAME="ONLINE_HELP"></A> | |
1239 @end html | |
1240 @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode | |
1241 @section Online Help | |
1242 | |
1243 @cindex Online Help | |
1244 @cindex @file{idlw-help.txt} | |
1245 @cindex @file{idlw-help.el} | |
1246 @cindex Installing online help | |
1247 @cindex Online Help, Installation | |
1248 @cindex Speed, of online help | |
1249 @cindex XML Help Catalog | |
1250 | |
1251 For IDL system routines, extensive documentation is supplied with IDL. | |
1252 IDLWAVE can access the HTML version of this documentation very quickly | |
1253 and accurately, based on the local context. This can be @emph{much} | |
1254 faster than using the IDL online help application, because IDLWAVE | |
1255 usually gets you to the right place in the documentation directly --- | |
1256 e.g. a specific keyword of a routine --- without any additional browsing | |
1257 and scrolling. | |
1258 | |
1259 For this online help to work, an HTML version of the IDL documentation | |
1260 is required. Beginning with IDL 6.2, HTML documentation is distributed | |
1261 directly with IDL, along with an XML-based catalog of routine | |
1262 information. By default, IDLWAVE automatically attempts to convert this | |
1263 XML catalog into a format Emacs can more easily understand, and caches | |
1264 this information in your @code{idlwave_config_directory} | |
1265 (@file{~/.idlwave/}, by default). It also re-scans the XML catalog if | |
1266 it is newer than the current cached version. You can force rescan with | |
1267 the menu entry @code{IDLWAVE->Routine Info->Rescan XML Help Catalog}. | |
1268 | |
1269 Before IDL 6.2, the HTML help was not distributed with IDL, and was not | |
1270 part of the standalone IDLWAVE distribution, but had to be downloaded | |
1271 separately. This is no longer necessary: all help and routine | |
1272 information is supplied with IDL versions 6.2 and later. | |
1273 | |
1274 There are a variety of options for displaying the HTML help: see below. | |
1275 Help for routines without HTML documentation is also available, by using | |
1276 the routine documentation header and/or routine source. | |
1277 | |
1278 @kindex M-? | |
1279 In any IDL program (or, as with most IDLWAVE commands, in the IDL | |
1280 Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with | |
1281 @kbd{S-Mouse-3} to access context sensitive online help. The following | |
1282 locations are recognized context for help: | |
1283 | |
1284 @cindex Context, for online help | |
1285 @multitable @columnfractions .25 .75 | |
1286 @item @i{Routine names} | |
1287 @tab The name of a routine (function, procedure, method). | |
1288 @item @i{Keyword Parameters} | |
1289 @tab A keyword parameter of a routine. | |
1290 @item @i{System Variables} | |
1291 @tab System variables like @code{!DPI}. | |
1292 @item @i{System Variable Tags} | |
1293 @tab System variables tags like @code{!D.X_SIZE}. | |
1294 @item @i{IDL Statements} | |
1295 @tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. | |
1296 @item @i{IDL Controls} | |
1297 @tab Control structures like @code{FOR}, @code{SWITCH}, etc. | |
1298 @item @i{Class names} | |
1299 @tab A class name in an @code{OBJ_NEW} call. | |
1300 @item @i{Class Init Keywords} | |
1301 @tab Beyond the class name in an @code{OBJ_NEW} call. | |
1302 @item @i{Executive Command} | |
1303 @tab An executive command like @code{.RUN}. Mostly useful in the shell. | |
1304 @item @i{Structure Tags} | |
1305 @tab Structure tags like @code{state.xsize} | |
1306 @item @i{Class Tags} | |
1307 @tab Class tags like @code{self.value}. | |
1308 @item @i{Default} | |
1309 @tab The routine that would be selected for routine info display. | |
1310 @end multitable | |
1311 | |
1312 @cindex @code{OBJ_NEW}, special online help | |
1313 Note that the @code{OBJ_NEW} function is special in that the help | |
1314 displayed depends on the cursor position. If the cursor is on the | |
1315 @samp{OBJ_NEW}, this function is described. If it is on the class | |
1316 name inside the quotes, the documentation for the class is pulled up. | |
1317 If the cursor is @emph{after} the class name, anywhere in the argument | |
1318 list, the documentation for the corresponding @code{Init} method and | |
1319 its keywords is targeted. | |
1320 | |
1321 Apart from an IDLWAVE buffer or shell, there are two more places from | |
1322 which online help can be accessed. | |
1323 | |
1324 @itemize @bullet | |
1325 @item | |
1326 Online help for routines and keywords can be accessed through the | |
1327 Routine Info display. Click with @kbd{Mouse-3} on an item to see the | |
1328 corresponding help (@pxref{Routine Info}). | |
1329 @item | |
1330 When using completion and Emacs pops up a @file{*Completions*} buffer | |
1331 with possible completions, clicking with @kbd{Mouse-3} on a completion | |
1332 item invokes help on that item (@pxref{Completion}). Items for which | |
1333 help is available in the online system documentation (vs. just the | |
1334 program source itself) will be emphasized (e.g. colored blue). | |
1335 @end itemize | |
1336 @noindent | |
1337 In both cases, a blue face indicates that the item is documented in | |
1338 the IDL manual, but an attempt will be made to visit non-blue items | |
1339 directly in the originating source file. | |
1340 | |
1341 | |
1342 @menu | |
1343 * Help with HTML Documentation:: | |
1344 * Help with Source:: | |
1345 @end menu | |
1346 | |
1347 @node Help with HTML Documentation, Help with Source, Online Help, Online Help | |
1348 @subsection Help with HTML Documentation | |
1349 @cindex HTML Help | |
1350 @cindex Help using HTML manuals | |
1351 @cindex IDL manual, HTML version | |
1352 @cindex IDL Assistant | |
1353 | |
1354 Help using the HTML documentation is invoked with the built-in Emacs | |
1355 command @code{browse-url}, which displays the relevant help topic in a | |
1356 browser of your choosing. Beginning with version 6.2, IDL comes with | |
1357 the help browser @emph{IDL Assistant}, which it uses by default for | |
1358 displaying online help on all supported platforms. This browser | |
1359 offers topical searches, an index, and is also now the default and | |
1360 recommended IDLWAVE help browser. The variable | |
1361 @code{idlwave-help-use-assistant} controls whether this browser is | |
1362 used. Note that, due to limitations in the Assistant, invoking help | |
1363 within IDLWAVE and @code{? topic} within IDL will result in two | |
1364 running copies of Assistant. | |
1365 | |
1366 Aside from the IDL Assistant, there are many possible browsers to choose | |
1367 among, with differing advantages and disadvantages. The variable | |
1368 @code{idlwave-help-browser-function} controls which browser help is sent | |
1369 to (as long as @code{idlwave-help-use-assistant} is not set). This | |
1370 function is used to set the variable @code{browse-url-browser-function} | |
1371 locally for IDLWAVE help only. Customize the latter variable to see | |
1372 what choices of browsers your system offers. Certain browsers like | |
1373 @code{w3} (bundled with many versions of Emacs) and @code{w3m} | |
1374 (@uref{http://emacs-w3m.namazu.org/}) are run within Emacs, and use | |
1375 Emacs buffers to display the HTML help. This can be convenient, | |
1376 especially on small displays, and images can even be displayed in-line | |
1377 on newer Emacs versions. However, better formatting results are often | |
1378 achieved with external browsers, like Mozilla. IDLWAVE assumes any | |
1379 browser function containing "w3" is displayed in a local buffer. If you | |
1380 are using another Emacs-local browser for which this is not true, set | |
1381 the variable @code{idlwave-help-browser-is-local}. | |
1382 | |
1383 With IDL 6.2 or later, it is important to ensure that the variable | |
1384 @code{idlwave-system-directory} is set (@pxref{Catalogs}). One easy way | |
1385 to ensure this is to run the IDL Shell (@kbd{C-c C-s}). It will be | |
1386 queried for this directory, and the results will be cached to file for | |
1387 subsequent use. | |
1388 | |
1389 @xref{HTML Help Browser Tips}, for more information on selecting and | |
1390 configuring a browser for use with IDL's HTML help system. | |
1391 | |
1392 @defopt idlwave-html-system-help-location @file{help/online_help} | |
1393 Relative directory of the system-supplied HTML help directory, | |
1394 considered with respect to @code{idlwave-system-directory}. Relevant | |
1395 for IDL 6.2 and greater. Should not change. | |
1396 @end defopt | |
1397 | |
1398 @defopt idlwave-html-help-location @file{/usr/local/etc/} | |
1399 The directory where the @file{idl_html_help} HTML directory live. | |
1400 Obsolete and ignored for IDL 6.2 and greater | |
1401 (@code{idlwave-html-system-help-location} is used instead). | |
1402 @end defopt | |
1403 | |
1404 @defopt idlwave-help-use-assistant @code{t} | |
1405 If set, use the IDL Assistant if possible for online HTML help, | |
1406 otherwise use the browser function specified in | |
1407 @code{idlwave-help-browser-function}. | |
1408 @end defopt | |
1409 | |
1410 @defopt idlwave-help-browser-function | |
1411 The browser function to use to display IDLWAVE HTML help. Should be | |
1412 one of the functions available for setting | |
1413 @code{browse-url-browser-function}, which see. | |
1414 @end defopt | |
1415 | |
1416 @defopt idlwave-help-browser-is-local | |
1417 Is the browser selected in @code{idlwave-help-browser-function} run in a | |
1418 local Emacs buffer or window? Defaults to @code{t} if the function | |
1419 contains "-w3". | |
1420 @end defopt | |
1421 | |
1422 @defopt idlwave-help-link-face | |
1423 The face for links to IDLWAVE online help. | |
1424 @end defopt | |
1425 | |
1426 @node Help with Source, , Help with HTML Documentation, Online Help | |
1427 @subsection Help with Source | |
1428 @cindex Help using routine source | |
1429 | |
1430 @cindex Source code, as online help | |
1431 @cindex DocLib header, as online help | |
1432 For routines which are not documented in an HTML manual (for example | |
1433 personal or library routines), the source code itself is used as help | |
1434 text. If the requested information can be found in a (more or less) | |
1435 standard DocLib file header, IDLWAVE shows the header (scrolling down to | |
1436 a keyword, if appropriate). Otherwise the routine definition statement | |
1437 (@code{pro}/@code{function}) is shown. The doclib header sections which | |
1438 are searched for include @samp{NAME} and @samp{KEYWORDS}. Localization | |
1439 support can be added by customizing the @code{idlwave-help-doclib-name} | |
1440 and @code{idlwave-help-doclib-keyword} variables. | |
1441 | |
1442 @cindex Structure tags, in online help | |
1443 @cindex Class tags, in online help | |
1444 Help is also available for class structure tags (@code{self.TAG}), and | |
1445 generic structure tags, if structure tag completion is enabled | |
1446 (@pxref{Structure Tag Completion}). This is implemented by visiting the | |
1447 tag within the class or structure definition source itself. Help is not | |
1448 available on built-in system class tags. | |
1449 | |
1450 The help window is normally displayed in the same frame, but can be | |
1451 popped-up in a separate frame. The following commands can be used to | |
1452 navigate inside the help system for source files: | |
1453 | |
1454 @multitable @columnfractions .15 .85 | |
1455 @item @kbd{@key{SPACE}} | |
1456 @tab Scroll forward one page. | |
1457 @item @kbd{@key{RET}} | |
1458 @tab Scroll forward one line. | |
1459 @item @kbd{@key{DEL}} | |
1460 @tab Scroll back one page. | |
1461 @item @kbd{h} | |
1462 @tab Jump to DocLib Header of the routine whose source is displayed | |
1463 as help. | |
1464 @item @kbd{H} | |
1465 @tab Jump to the first DocLib Header in the file. | |
1466 @item @kbd{.} @r{(Dot)} | |
1467 @tab Jump back and forth between the routine definition (the | |
1468 @code{pro}/@code{function} statement) and the description of the help | |
1469 item in the DocLib header. | |
1470 @item @kbd{F} | |
1471 @tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}. | |
1472 @item @kbd{q} | |
1473 @tab Kill the help window. | |
1474 @end multitable | |
1475 | |
1476 | |
1477 @defopt idlwave-help-use-dedicated-frame (@code{nil}) | |
1478 Non-@code{nil} means use a separate frame for Online Help if possible. | |
1479 @end defopt | |
1480 | |
1481 @defopt idlwave-help-frame-parameters | |
1482 The frame parameters for the special Online Help frame. | |
1483 @end defopt | |
1484 | |
1485 @defopt idlwave-max-popup-menu-items (@code{20}) | |
1486 Maximum number of items per pane in pop-up menus. | |
1487 @end defopt | |
1488 | |
1489 @defopt idlwave-extra-help-function | |
1490 Function to call for help if the normal help fails. | |
1491 @end defopt | |
1492 | |
1493 @defopt idlwave-help-fontify-source-code (@code{nil}) | |
1494 Non-@code{nil} means fontify source code displayed as help. | |
1495 @end defopt | |
1496 | |
1497 @defopt idlwave-help-source-try-header (@code{t}) | |
1498 Non-@code{nil} means try to find help in routine header when | |
1499 displaying source file. | |
1500 @end defopt | |
1501 | |
1502 @defopt idlwave-help-doclib-name (@code{"name"}) | |
1503 The case-insensitive heading word in doclib headers to locate the | |
1504 @emph{name} section. Can be a regexp, e.g. @code{"\\(name\\|nom\\)"}. | |
1505 @end defopt | |
1506 | |
1507 @defopt idlwave-help-doclib-keyword (@code{"KEYWORD"}) | |
1508 The case-insensitive heading word in doclib headers to locate the | |
1509 @emph{keywords} section. Can be a regexp. | |
1510 @end defopt | |
1511 | |
1512 | |
1513 @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode | |
1514 @section Completion | |
1515 @cindex Completion | |
1516 @cindex Keyword completion | |
1517 @cindex Method completion | |
1518 @cindex Object method completion | |
1519 @cindex Class name completion | |
1520 @cindex Function name completion | |
1521 @cindex Procedure name completion | |
1522 | |
1523 @kindex M-@key{TAB} | |
1524 @kindex C-c C-i | |
1525 IDLWAVE offers completion for class names, routine names, keywords, | |
1526 system variables, system variable tags, class structure tags, regular | |
1527 structure tags and file names. As in many programming modes, completion | |
1528 is bound to @kbd{M-@key{TAB}} (or simply @kbd{@key{TAB}} in the IDLWAVE | |
1529 Shell --- @pxref{Using the Shell}). Completion uses exactly the same | |
1530 internal information as routine info, so when necessary (rarely) it can | |
1531 be updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}). | |
1532 | |
1533 The completion function is context sensitive and figures out what to | |
1534 complete based on the location of the point. Here are example lines and | |
1535 what @kbd{M-@key{TAB}} would try to complete when the cursor is on the | |
1536 position marked with a @samp{_}: | |
1537 | |
1538 @example | |
1539 plo_ @r{Procedure} | |
1540 x = a_ @r{Function} | |
1541 plot,xra_ @r{Keyword of @code{plot} procedure} | |
1542 plot,x,y,/x_ @r{Keyword of @code{plot} procedure} | |
1543 plot,min(_ @r{Keyword of @code{min} function} | |
1544 obj -> a_ @r{Object method (procedure)} | |
1545 a[2,3] = obj -> a_ @r{Object method (function)} | |
1546 x = obj_new('IDL_ @r{Class name} | |
1547 x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}} | |
1548 pro A_ @r{Class name} | |
1549 pro _ @r{Fill in @code{Class::} of first method in this file} | |
1550 !v_ @r{System variable} | |
1551 !version.t_ @r{Structure tag of system variable} | |
1552 self.g_ @r{Class structure tag in methods} | |
1553 state.w_ @r{Structure tag, if tag completion enabled} | |
1554 name = 'a_ @r{File name (default inside quotes)} | |
1555 @end example | |
1556 | |
1557 @cindex Completion, ambiguity | |
1558 @cindex Completion, forcing function name | |
1559 The only place where completion is ambiguous is procedure/function | |
1560 @emph{keywords} versus @emph{functions}. After @samp{plot,x,_}, IDLWAVE | |
1561 will always assume a keyword to @samp{plot}. However, a function is | |
1562 also a possible completion here. You can force completion of a function | |
1563 name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}. | |
1564 | |
1565 Giving two prefix arguments (@kbd{C-u C-u M-@key{TAB}}) prompts for a | |
1566 regular expression to search among the commands to be completed. As | |
1567 an example, completing a blank line in this way will allow you to | |
1568 search for a procedure matching a regexp. | |
1569 | |
1570 @cindex Scrolling the @file{*Completions*} window | |
1571 @cindex Completion, scrolling | |
1572 @cindex Completion, Online Help | |
1573 @cindex Online Help in @file{*Completions*} buffer | |
1574 If the list of completions is too long to fit in the | |
1575 @file{*Completions*} window, the window can be scrolled by pressing | |
1576 @kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each | |
1577 possible completion is available by clicking with @kbd{Mouse-3} on the | |
1578 item. Items for which system online help (from the IDL manual) is | |
1579 available will be emphasized (e.g. colored blue). For other items, the | |
1580 corresponding source code or DocLib header will be used as the help | |
1581 text. | |
1582 | |
1583 @cindex Completion, cancelling | |
1584 @cindex Cancelling completion | |
1585 Completion is not a blocking operation --- you are free to continue | |
1586 editing, enter commands, or simply ignore the @file{*Completions*} | |
1587 buffer during a completion operation. If, however, the most recent | |
1588 command was a completion, @kbd{C-g} will remove the buffer and restore | |
1589 the window configuration. You can also remove the buffer at any time | |
1590 with no negative consequences. | |
1591 | |
1592 @defopt idlwave-keyword-completion-adds-equal (@code{t}) | |
1593 Non-@code{nil} means completion automatically adds @samp{=} after | |
1594 completed keywords. | |
1595 @end defopt | |
1596 | |
1597 @defopt idlwave-function-completion-adds-paren (@code{t}) | |
1598 Non-@code{nil} means completion automatically adds @samp{(} after | |
1599 completed function. A value of `2' means also add the closing | |
1600 parenthesis and position the cursor between the two. | |
1601 @end defopt | |
1602 | |
1603 @defopt idlwave-completion-restore-window-configuration (@code{t}) | |
1604 Non-@code{nil} means restore window configuration after successful | |
1605 completion. | |
1606 @end defopt | |
1607 | |
1608 @defopt idlwave-highlight-help-links-in-completion (@code{t}) | |
1609 Non-@code{nil} means highlight completions for which system help is | |
1610 available. | |
1611 @end defopt | |
1612 | |
1613 @menu | |
1614 * Case of Completed Words:: CaseOFcomPletedWords | |
1615 * Object Method Completion and Class Ambiguity:: obj->Method, what? | |
1616 * Object Method Completion in the Shell:: | |
1617 * Class and Keyword Inheritance:: obj->Method, _EXTRA=e | |
1618 * Structure Tag Completion:: Completing state.Tag | |
1619 @end menu | |
1620 | |
1621 @node Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion | |
1622 @subsection Case of Completed Words | |
1623 @cindex Case of completed words | |
1624 @cindex Mixed case completion | |
1625 IDL is a case-insensitive language, so casing is a matter of style | |
1626 only. IDLWAVE helps maintain a consistent casing style for completed | |
1627 items. The case of the completed words is determined by what is | |
1628 already in the buffer. As an exception, when the partial word being | |
1629 completed is all lower case, the completion will be lower case as | |
1630 well. If at least one character is upper case, the string will be | |
1631 completed in upper case or mixed case, depending on the value of the | |
1632 variable @code{idlwave-completion-case}. The default is to use upper | |
1633 case for procedures, functions and keywords, and mixed case for object | |
1634 class names and methods, similar to the conventions in the IDL | |
1635 manuals. For instance, to enable mixed-case completion for routines | |
1636 in addition to classes and methods, you need an entry such as | |
1637 @code{(routine . preserve)} in that variable. To enable total control | |
1638 over the case of completed items, independent of buffer context, set | |
1639 @code{idlwave-completion-force-default-case} to non-@code{nil}. | |
1640 | |
1641 @defopt idlwave-completion-case | |
1642 Association list setting the case (UPPER/lower/Capitalized/MixedCase...) | |
1643 of completed words. | |
1644 @end defopt | |
1645 | |
1646 @defopt idlwave-completion-force-default-case (@code{nil}) | |
1647 Non-@code{nil} means completion will always honor the settings in | |
1648 @code{idlwave-completion-case}. When nil (the default), entirely lower | |
1649 case strings will always be completed to lower case, no matter what the | |
1650 settings in @code{idlwave-completion-case}. | |
1651 @end defopt | |
1652 | |
1653 @defopt idlwave-complete-empty-string-as-lower-case (@code{nil}) | |
1654 Non-@code{nil} means the empty string is considered lower case for | |
1655 completion. | |
1656 @end defopt | |
1657 | |
1658 @node Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion | |
1659 @subsection Object Method Completion and Class Ambiguity | |
1660 @cindex Object methods | |
1661 @cindex Class ambiguity | |
1662 @cindex @code{self} object, default class | |
1663 An object method is not uniquely determined without the object's class. | |
1664 Since the class is almost always omitted in the calling source (as | |
1665 required to obtain the true benefits of object-based programming), | |
1666 IDLWAVE considers all available methods in all classes as possible | |
1667 method name completions. The combined list of keywords of the current | |
1668 method in @emph{all} known classes which contain that method will be | |
1669 considered for keyword completion. In the @file{*Completions*} buffer, | |
1670 the matching classes will be shown next to each item (see option | |
1671 @code{idlwave-completion-show-classes}). As a special case, the class | |
1672 of an object called @samp{self} is always taken to be the class of the | |
1673 current routine, when in an IDLWAVE buffer. All inherits classes are | |
1674 considered as well. | |
1675 | |
1676 @cindex Forcing class query. | |
1677 @cindex Class query, forcing | |
1678 You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u | |
1679 M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to | |
1680 narrow down the number of possible completions. The variable | |
1681 @code{idlwave-query-class} can be configured to make such prompting the | |
1682 default for all methods (not recommended), or selectively for very | |
1683 common methods for which the number of completing keywords would be too | |
1684 large (e.g. @code{Init,SetProperty,GetProperty}). | |
1685 | |
1686 @cindex Saving object class on @code{->} | |
1687 @cindex @code{->} | |
1688 After you have specified the class for a particular statement (e.g. when | |
1689 completing the method), IDLWAVE can remember it for the rest of the | |
1690 editing session. Subsequent completions in the same statement | |
1691 (e.g. keywords) can then reuse this class information. This works by | |
1692 placing a text property on the method invocation operator @samp{->}, | |
1693 after which the operator will be shown in a different face (bold by | |
1694 default). The variable @code{idlwave-store-inquired-class} can be used | |
1695 to turn it off or on. | |
1696 | |
1697 @defopt idlwave-completion-show-classes (@code{1}) | |
1698 Non-@code{nil} means show up to that many classes in | |
1699 @file{*Completions*} buffer when completing object methods and | |
1700 keywords. | |
1701 @end defopt | |
1702 | |
1703 @defopt idlwave-completion-fontify-classes (@code{t}) | |
1704 Non-@code{nil} means fontify the classes in completions buffer. | |
1705 @end defopt | |
1706 | |
1707 @defopt idlwave-query-class (@code{nil}) | |
1708 Association list governing query for object classes during completion. | |
1709 @end defopt | |
1710 | |
1711 @defopt idlwave-store-inquired-class (@code{t}) | |
1712 Non-@code{nil} means store class of a method call as text property on | |
1713 @samp{->}. | |
1714 @end defopt | |
1715 | |
1716 @defopt idlwave-class-arrow-face | |
1717 Face to highlight object operator arrows @samp{->} which carry a saved | |
1718 class text property. | |
1719 @end defopt | |
1720 | |
1721 @node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion | |
1722 @subsection Object Method Completion in the Shell | |
1723 @cindex Method Completion in Shell | |
1724 In the IDLWAVE Shell (@pxref{The IDLWAVE Shell}), objects on which | |
1725 methods are being invoked have a special property: they must exist as | |
1726 variables, and so their class can be determined (for instance, using the | |
1727 @code{obj_class()} function). In the Shell, when attempting completion, | |
1728 routine info, or online help within a method routine, a query is sent to | |
1729 determine the class of the object. If this query is successful, the | |
1730 class found will be used to select appropriate completions, routine | |
1731 info, or help. If unsuccessful, information from all known classes will | |
1732 be used (as in the buffer). | |
1733 | |
1734 @node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion | |
1735 @subsection Class and Keyword Inheritance | |
1736 @cindex Inheritance, class | |
1737 @cindex Keyword inheritance | |
1738 @cindex Inheritance, keyword | |
1739 | |
1740 Class inheritance affects which methods are called in IDL. An object of | |
1741 a class which inherits methods from one or more superclasses can | |
1742 override that method by defining its own method of the same name, extend | |
1743 the method by calling the method(s) of its superclass(es) in its | |
1744 version, or inherit the method directly by making no modifications. | |
1745 IDLWAVE examines class definitions during completion and routine | |
1746 information display, and records all inheritance information it finds. | |
1747 This information is displayed if appropriate with the calling sequence | |
1748 for methods (@pxref{Routine Info}), as long as variable | |
1749 @code{idlwave-support-inheritance} is non-@code{nil}. | |
1750 | |
1751 In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and | |
1752 @code{_REF_EXTRA}) is used hand-in-hand with class inheritance and | |
1753 method overriding. E.g., in a @code{SetProperty} method, this technique | |
1754 allows a single call @code{obj->SetProperty} to set properties up the | |
1755 entire class inheritance chain. This is often referred to as | |
1756 @emph{chaining}, and is characterized by chained method calls like | |
1757 @w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}. | |
1758 | |
1759 IDLWAVE can accommodate this special synergy between class and keyword | |
1760 inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a | |
1761 method's keyword parameters, all keywords of superclass versions of | |
1762 the method being considered can be included in completion. There is | |
1763 of course no guarantee that this type of keyword chaining actually | |
1764 occurs, but for some methods it's a very convenient assumption. The | |
1765 variable @code{idlwave-keyword-class-inheritance} can be used to | |
1766 configure which methods have keyword inheritance treated in this | |
1767 simple, class-driven way. By default, only @code{Init} and | |
1768 @code{(Get|Set)Property} are. The completion buffer will label | |
1769 keywords based on their originating class. | |
1770 | |
1771 @defopt idlwave-support-inheritance (@code{t}) | |
1772 Non-@code{nil} means consider inheritance during completion, online help etc. | |
1773 @end defopt | |
1774 | |
1775 @defopt idlwave-keyword-class-inheritance | |
1776 A list of regular expressions to match methods for which simple | |
1777 class-driven keyword inheritance will be used for Completion. | |
1778 @end defopt | |
1779 | |
1780 @node Structure Tag Completion, , Class and Keyword Inheritance, Completion | |
1781 @subsection Structure Tag Completion | |
1782 @cindex Completion, structure tag | |
1783 @cindex Structure tag completion | |
1784 | |
1785 In many programs, especially those involving widgets, large structures | |
1786 (e.g. the @samp{state} structure) are used to communicate among | |
1787 routines. It is very convenient to be able to complete structure tags, | |
1788 in the same way as for instance variables (tags) of the @samp{self} | |
1789 object (@pxref{Object Method Completion and Class Ambiguity}). Add-in | |
1790 code for structure tag completion is available in the form of a loadable | |
1791 completion module: @file{idlw-complete-structtag.el}. Tag completion in | |
1792 structures is highly ambiguous (much more so than @samp{self} | |
1793 completion), so @code{idlw-complete-structtag} makes an unusual and very | |
1794 specific assumption: the exact same variable name is used to refer to | |
1795 the structure in all parts of the program. This is entirely unenforced | |
1796 by the IDL language, but is a typical convention. If you consistently | |
1797 refer to the same structure with the same variable name | |
1798 (e.g. @samp{state}), structure tags which are read from its definition | |
1799 in the same file can be used for completion. | |
1800 | |
1801 Structure tag completion is not enabled by default. To enable it, | |
1802 simply add the following to your @file{.emacs}: | |
1803 | |
1804 @lisp | |
1805 (add-hook 'idlwave-load-hook | |
1806 (lambda () (require 'idlw-complete-structtag))) | |
1807 @end lisp | |
1808 | |
1809 Once enabled, you'll also be able to access online help on the structure | |
1810 tags, using the usual methods (@pxref{Online Help}). In addition, | |
1811 structure variables in the shell will be queried for tag names, similar | |
1812 to the way object variables in the shell are queried for method names. | |
1813 So, e.g.: | |
1814 | |
1815 @example | |
1816 IDL> st.[Tab] | |
1817 @end example | |
1818 | |
1819 @noindent will complete with all structure fields of the structure | |
1820 @code{st}. | |
1821 | |
1822 @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode | |
1823 @section Routine Source | |
1824 @cindex Routine source file | |
1825 @cindex Module source file | |
1826 @cindex Source file, of a routine | |
1827 @kindex C-c C-v | |
1828 In addition to clicking on a @i{Source:} line in the routine info | |
1829 window, there is another way to quickly visit the source file of a | |
1830 routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks | |
1831 for a module name, offering the same default as | |
1832 @code{idlwave-routine-info} would have used, taken from nearby buffer | |
1833 contents. In the minibuffer, specify a complete routine name (including | |
1834 any class part). IDLWAVE will display the source file in another | |
1835 window, positioned at the routine in question. You can also limit this | |
1836 to a routine in the current buffer only, with completion, and a | |
1837 context-sensitive default, by using a single prefix (@kbd{C-u C-c C-v}) | |
1838 or the convenience binding @kbd{C-c C-t}. | |
1839 | |
1840 @cindex Buffers, killing | |
1841 @cindex Killing autoloaded buffers | |
1842 Since getting the source of a routine into a buffer is so easy with | |
1843 IDLWAVE, too many buffers visiting different IDL source files are | |
1844 sometimes created. The special command @kbd{C-c C-k} | |
1845 (@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove | |
1846 these buffers. | |
1847 | |
1848 @node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode | |
1849 @section Resolving Routines | |
1850 @cindex @code{RESOLVE_ROUTINE} | |
1851 @cindex Compiling library modules | |
1852 @cindex Routines, resolving | |
1853 | |
1854 The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve} | |
1855 and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL | |
1856 in order to resolve (compile) it. The default routine to be resolved is | |
1857 taken from context, but you get a chance to edit it. Usually this is | |
1858 not necessary, since IDL automatically discovers routines on its path. | |
1859 | |
1860 @code{idlwave-resolve} is one way to get a library module within reach | |
1861 of IDLWAVE's routine info collecting functions. A better way is to | |
1862 keep routine information available in catalogs (@pxref{Catalogs}). | |
1863 Routine info on modules will then be available without the need to | |
1864 compile the modules first, and even without a running shell. | |
1865 | |
1866 @xref{Sources of Routine Info}, for more information on the ways IDLWAVE | |
1867 collects data about routines, and how to update this information. | |
1868 | |
1869 @node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode | |
1870 @section Code Templates | |
1871 @cindex Code templates | |
1872 @cindex Templates | |
1873 | |
1874 IDLWAVE can insert IDL code templates into the buffer. For a few | |
1875 templates, this is done with direct key bindings: | |
1876 | |
1877 @multitable @columnfractions .15 .85 | |
1878 @item @kbd{C-c C-c} | |
1879 @tab @code{CASE} statement template | |
1880 @item @kbd{C-c C-f} | |
1881 @tab @code{FOR} loop template | |
1882 @item @kbd{C-c C-r} | |
1883 @tab @code{REPEAT} loop template | |
1884 @item @kbd{C-c C-w} | |
1885 @tab @code{WHILE} loop template | |
1886 @end multitable | |
1887 | |
1888 All code templates are also available as abbreviations | |
1889 (@pxref{Abbreviations}). | |
1890 | |
1891 @node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode | |
1892 @section Abbreviations | |
1893 @cindex Abbreviations | |
1894 | |
1895 Special abbreviations exist to enable rapid entry of commonly used | |
1896 commands. Emacs abbreviations are expanded by typing text into the | |
1897 buffer and pressing @key{SPC} or @key{RET}. The special abbreviations | |
1898 used to insert code templates all start with a @samp{\} (the backslash), | |
1899 or, optionally, any other character set in | |
1900 @code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are | |
1901 only expanded where they should be (i.e., not in a string or comment), | |
1902 and permits the point to be moved after an abbreviation expansion --- | |
1903 very useful for positioning the mark inside of parentheses, etc. | |
1904 | |
1905 Special abbreviations are pre-defined for code templates and other | |
1906 useful items. To visit the full list of abbreviations, use @kbd{M-x | |
1907 idlwave-list-abbrevs}. | |
1908 | |
1909 Template abbreviations: | |
1910 | |
1911 @multitable @columnfractions .15 .85 | |
1912 @item @code{\pr} | |
1913 @tab @code{PROCEDURE} template | |
1914 @item @code{\fu} | |
1915 @tab @code{FUNCTION} template | |
1916 @item @code{\c} | |
1917 @tab @code{CASE} statement template | |
1918 @item @code{\f} | |
1919 @tab @code{FOR} loop template | |
1920 @item @code{\r} | |
1921 @tab @code{REPEAT} loop template | |
1922 @item @code{\w} | |
1923 @tab @code{WHILE} loop template | |
1924 @item @code{\i} | |
1925 @tab @code{IF} statement template | |
1926 @item @code{\elif} | |
1927 @tab @code{IF-ELSE} statement template | |
1928 @end multitable | |
1929 | |
1930 String abbreviations: | |
1931 | |
1932 @multitable @columnfractions .15 .85 | |
1933 @item @code{\ap} | |
1934 @tab @code{arg_present()} | |
1935 @item @code{\b} | |
1936 @tab @code{begin} | |
1937 @item @code{\cb} | |
1938 @tab @code{byte()} | |
1939 @item @code{\cc} | |
1940 @tab @code{complex()} | |
1941 @item @code{\cd} | |
1942 @tab @code{double()} | |
1943 @item @code{\cf} | |
1944 @tab @code{float()} | |
1945 @item @code{\cl} | |
1946 @tab @code{long()} | |
1947 @item @code{\co} | |
1948 @tab @code{common} | |
1949 @item @code{\cs} | |
1950 @tab @code{string()} | |
1951 @item @code{\cx} | |
1952 @tab @code{fix()} | |
1953 @item @code{\e} | |
1954 @tab @code{else} | |
1955 @item @code{\ec} | |
1956 @tab @code{endcase} | |
1957 @item @code{\ee} | |
1958 @tab @code{endelse} | |
1959 @item @code{\ef} | |
1960 @tab @code{endfor} | |
1961 @item @code{\ei} | |
1962 @tab @code{endif else if} | |
1963 @item @code{\el} | |
1964 @tab @code{endif else} | |
1965 @item @code{\en} | |
1966 @tab @code{endif} | |
1967 @item @code{\er} | |
1968 @tab @code{endrep} | |
1969 @item @code{\es} | |
1970 @tab @code{endswitch} | |
1971 @item @code{\ew} | |
1972 @tab @code{endwhile} | |
1973 @item @code{\g} | |
1974 @tab @code{goto,} | |
1975 @item @code{\h} | |
1976 @tab @code{help,} | |
1977 @item @code{\ik} | |
1978 @tab @code{if keyword_set() then} | |
1979 @item @code{\iap} | |
1980 @tab @code{if arg_present() then} | |
1981 @item @code{\ine} | |
1982 @tab @code{if n_elements() eq 0 then} | |
1983 @item @code{\inn} | |
1984 @tab @code{if n_elements() ne 0 then} | |
1985 @item @code{\k} | |
1986 @tab @code{keyword_set()} | |
1987 @item @code{\n} | |
1988 @tab @code{n_elements()} | |
1989 @item @code{\np} | |
1990 @tab @code{n_params()} | |
1991 @item @code{\oi} | |
1992 @tab @code{on_ioerror,} | |
1993 @item @code{\or} | |
1994 @tab @code{openr,} | |
1995 @item @code{\ou} | |
1996 @tab @code{openu,} | |
1997 @item @code{\ow} | |
1998 @tab @code{openw,} | |
1999 @item @code{\p} | |
2000 @tab @code{print,} | |
2001 @item @code{\pt} | |
2002 @tab @code{plot,} | |
2003 @item @code{\pv} | |
2004 @tab @code{ptr_valid()} | |
2005 @item @code{\re} | |
2006 @tab @code{read,} | |
2007 @item @code{\rf} | |
2008 @tab @code{readf,} | |
2009 @item @code{\rt} | |
2010 @tab @code{return} | |
2011 @item @code{\ru} | |
2012 @tab @code{readu,} | |
2013 @item @code{\s} | |
2014 @tab @code{size()} | |
2015 @item @code{\sc} | |
2016 @tab @code{strcompress()} | |
2017 @item @code{\sl} | |
2018 @tab @code{strlowcase()} | |
2019 @item @code{\sm} | |
2020 @tab @code{strmid()} | |
2021 @item @code{\sn} | |
2022 @tab @code{strlen()} | |
2023 @item @code{\sp} | |
2024 @tab @code{strpos()} | |
2025 @item @code{\sr} | |
2026 @tab @code{strtrim()} | |
2027 @item @code{\st} | |
2028 @tab @code{strput()} | |
2029 @item @code{\su} | |
2030 @tab @code{strupcase()} | |
2031 @item @code{\t} | |
2032 @tab @code{then} | |
2033 @item @code{\u} | |
2034 @tab @code{until} | |
2035 @item @code{\wc} | |
2036 @tab @code{widget_control,} | |
2037 @item @code{\wi} | |
2038 @tab @code{widget_info()} | |
2039 @item @code{\wu} | |
2040 @tab @code{writeu,} | |
2041 @end multitable | |
2042 | |
2043 @noindent You can easily add your own abbreviations or override existing | |
2044 abbrevs with @code{define-abbrev} in your mode hook, using the | |
2045 convenience function @code{idlwave-define-abbrev}: | |
2046 | |
2047 @lisp | |
2048 (add-hook 'idlwave-mode-hook | |
2049 (lambda () | |
2050 (idlwave-define-abbrev "wb" "widget_base()" | |
2051 (idlwave-keyword-abbrev 1)) | |
2052 (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN" | |
2053 (idlwave-keyword-abbrev 11)))) | |
2054 @end lisp | |
2055 | |
2056 Notice how the abbreviation (here @emph{wb}) and its expansion | |
2057 (@emph{widget_base()}) are given as arguments, and the single argument to | |
2058 @code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to | |
2059 move the point upon expansion (in this example, to put it between the | |
2060 parentheses). | |
2061 | |
2062 The abbreviations are expanded in upper or lower case, depending upon | |
2063 the variables @code{idlwave-abbrev-change-case} and, for reserved word | |
2064 templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}). | |
2065 | |
2066 @defopt idlwave-abbrev-start-char (@code{"\"}) | |
2067 A single character string used to start abbreviations in abbrev mode. | |
2068 Beware of common characters which might naturally occur in sequence with | |
2069 abbreviation strings. | |
2070 @end defopt | |
2071 | |
2072 @defopt idlwave-abbrev-move (@code{t}) | |
2073 Non-@code{nil} means the abbrev hook can move point, e.g. to end up | |
2074 between the parentheses of a function call. | |
2075 @end defopt | |
2076 | |
2077 @node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode | |
2078 @section Actions | |
2079 @cindex Actions | |
2080 @cindex Coding standards, enforcing | |
2081 | |
2082 @emph{Actions} are special formatting commands which are executed | |
2083 automatically while you write code in order to check the structure of | |
2084 the program or to enforce coding standards. Most actions which have | |
2085 been implemented in IDLWAVE are turned off by default, assuming that the | |
2086 average user wants her code the way she writes it. But if you are a | |
2087 lazy typist and want your code to adhere to certain standards, actions | |
2088 can be helpful. | |
2089 | |
2090 Actions can be applied in three ways: | |
2091 | |
2092 @itemize @bullet | |
2093 @item | |
2094 Some actions are applied directly while typing. For example, pressing | |
2095 @samp{=} can run a check to make sure that this operator is surrounded | |
2096 by spaces and insert these spaces if necessary. Pressing @key{SPC} | |
2097 after a reserved word can call a command to change the word to upper | |
2098 case. | |
2099 @item | |
2100 When a line is re-indented with @key{TAB}, actions can be applied to the | |
2101 entire line. To enable this, the variable @code{idlwave-do-actions} | |
2102 must be non-@code{nil}. | |
2103 @item | |
2104 @cindex Foreign code, adapting | |
2105 @cindex Actions, applied to foreign code | |
2106 Actions can also be applied to a larger piece of code, e.g. to convert | |
2107 foreign code to your own style. To do this, mark the relevant part of | |
2108 the code and execute @kbd{M-x expand-region-abbrevs}. Useful marking | |
2109 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current | |
2110 subprogram). @xref{Code Indentation}, for information how to adjust the | |
2111 indentation of the code. | |
2112 @end itemize | |
2113 | |
2114 @defopt idlwave-do-actions (@code{nil}) | |
2115 Non-@code{nil} means performs actions when indenting. Individual action | |
2116 settings are described below and set separately. | |
2117 @end defopt | |
2118 | |
2119 @menu | |
2120 * Block Boundary Check:: Is the END statement correct? | |
2121 * Padding Operators:: Enforcing space around `=' etc | |
2122 * Case Changes:: Enforcing upper case keywords | |
2123 @end menu | |
2124 | |
2125 @node Block Boundary Check, Padding Operators, Actions, Actions | |
2126 @subsection Block Boundary Check | |
2127 @cindex Block boundary check | |
2128 @cindex @code{END} type checking | |
2129 @cindex @code{END}, automatic insertion | |
2130 @cindex @code{END}, expanding | |
2131 @cindex Block, closing | |
2132 @cindex Closing a block | |
2133 | |
2134 Whenever you type an @code{END} statement, IDLWAVE finds the | |
2135 corresponding start of the block and the cursor blinks back to that | |
2136 location for a second. If you have typed a specific @code{END}, like | |
2137 @code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator | |
2138 does not match the type of block it terminates. | |
2139 | |
2140 Set the variable @code{idlwave-expand-generic-end} in order to have all | |
2141 generic @code{END} statements automatically expanded to the appropriate | |
2142 type. You can also type @kbd{C-c ]} to close the current block by | |
2143 inserting the appropriate @code{END} statement. | |
2144 | |
2145 @defopt idlwave-show-block (@code{t}) | |
2146 Non-@code{nil} means point blinks to block beginning for | |
2147 @code{idlwave-show-begin}. | |
2148 @end defopt | |
2149 | |
2150 @defopt idlwave-expand-generic-end (@code{t}) | |
2151 Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc. | |
2152 @end defopt | |
2153 | |
2154 @defopt idlwave-reindent-end (@code{t}) | |
2155 Non-@code{nil} means re-indent line after END was typed. | |
2156 @end defopt | |
2157 | |
2158 @node Padding Operators, Case Changes, Block Boundary Check, Actions | |
2159 @subsection Padding Operators | |
2160 @cindex Padding operators with spaces | |
2161 @cindex Operators, padding with spaces | |
2162 @cindex Space, around operators | |
2163 | |
2164 Some operators can be automatically surrounded by spaces. This can | |
2165 happen when the operator is typed, or later when the line is indented. | |
2166 IDLWAVE can pad the operators @samp{<}, @samp{>}, @samp{,}, @samp{=}, | |
2167 and @samp{->}, as well as the modified assignment operators | |
2168 (@samp{AND=}, @samp{OR=}, etc.). This feature is turned off by default. | |
2169 If you want to turn it on, customize the variables | |
2170 @code{idlwave-surround-by-blank} and @code{idlwave-do-actions} and turn | |
2171 both on. You can also define similar actions for other operators by | |
2172 using the function @code{idlwave-action-and-binding} in the mode hook. | |
2173 For example, to enforce space padding of the @samp{+} and @samp{*} | |
2174 operators (outside of strings and comments, of course), try this in | |
2175 @file{.emacs} | |
2176 | |
2177 @lisp | |
2178 (add-hook 'idlwave-mode-hook | |
2179 (lambda () | |
2180 (setq idlwave-surround-by-blank t) ; Turn this type of actions on | |
2181 (idlwave-action-and-binding "*" '(idlwave-surround 1 1)) | |
2182 (idlwave-action-and-binding "+" '(idlwave-surround 1 1)))) | |
2183 @end lisp | |
2184 | |
2185 Note that the modified assignment operators which begin with a word | |
2186 (@samp{AND=}, @samp{OR=}, @samp{NOT=}, etc.) require a leading space to | |
2187 be recognized (e.g @code{vAND=4} would be interpreted as a variable | |
2188 @code{vAND}). Also note that, since e.g., @code{>} and @code{>=} are | |
2189 both valid operators, it is impossible to surround both by blanks while | |
2190 they are being typed. Similarly with @code{&} and @code{&&}. For | |
2191 these, a compromise is made: the padding is placed on the left, and if | |
2192 the longer operator is keyed in, on the right as well (otherwise you | |
2193 must insert spaces to pad right yourself, or press simply press Tab to | |
2194 repad everything if @code{idlwave-do-actions} is on). | |
2195 | |
2196 @defopt idlwave-surround-by-blank (@code{nil}) | |
2197 Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil}, | |
2198 @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->}, and the | |
2199 modified assignment operators (@samp{AND=}, @samp{OR=}, etc.) are | |
2200 surrounded with spaces by @code{idlwave-surround}. | |
2201 @end defopt | |
2202 | |
2203 @defopt idlwave-pad-keyword (@code{t}) | |
2204 Non-@code{nil} means space-pad the @samp{=} in keyword assignments. | |
2205 @end defopt | |
2206 | |
2207 @node Case Changes, , Padding Operators, Actions | |
2208 @subsection Case Changes | |
2209 @cindex Case changes | |
2210 @cindex Upcase, enforcing for reserved words | |
2211 @cindex Downcase, enforcing for reserved words | |
2212 | |
2213 Actions can be used to change the case of reserved words or expanded | |
2214 abbreviations by customizing the variables | |
2215 @code{idlwave-abbrev-change-case} and | |
2216 @code{idlwave-reserved-word-upcase}. If you want to change the case of | |
2217 additional words automatically, put something like the following into | |
2218 your @file{.emacs} file: | |
2219 | |
2220 @lisp | |
2221 (add-hook 'idlwave-mode-hook | |
2222 (lambda () | |
2223 ;; Capitalize system vars | |
2224 (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t) | |
2225 ;; Capitalize procedure name | |
2226 (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" | |
2227 '(capitalize-word 1) t) | |
2228 ;; Capitalize common block name | |
2229 (idlwave-action-and-binding "\\<common\\>[ \t]+\\<" | |
2230 '(capitalize-word 1) t))) | |
2231 @end lisp | |
2232 | |
2233 For more information, see the documentation string for the function | |
2234 @code{idlwave-action-and-binding}. For information on controlling the | |
2235 case of routines, keywords, classes, and methods as they are completed, see | |
2236 @ref{Completion}. | |
2237 | |
2238 @defopt idlwave-abbrev-change-case (@code{nil}) | |
2239 Non-@code{nil} means all abbrevs will be forced to either upper or lower | |
2240 case. Valid values are @code{nil}, @code{t}, and @code{down}. | |
2241 @end defopt | |
2242 | |
2243 @defopt idlwave-reserved-word-upcase (@code{nil}) | |
2244 Non-@code{nil} means reserved words will be made upper case via abbrev | |
2245 expansion. | |
2246 @end defopt | |
2247 | |
2248 | |
2249 @node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode | |
2250 @section Documentation Header | |
2251 @cindex Documentation header | |
2252 @cindex DocLib header | |
2253 @cindex Modification timestamp | |
2254 @cindex Header, for file documentation | |
2255 @cindex Timestamp, in doc header. | |
2256 @cindex Changelog, in doc header. | |
2257 | |
2258 @kindex C-c C-h | |
2259 @kindex C-c C-m | |
2260 The command @kbd{C-c C-h} inserts a standard routine header into the | |
2261 buffer, with the usual fields for documentation (a different header can | |
2262 be specified with @code{idlwave-file-header}). One of the keywords is | |
2263 @samp{MODIFICATION HISTORY} under which the changes to a routine can be | |
2264 recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION | |
2265 HISTORY} of the current routine or file and inserts the user name with a | |
2266 timestamp. | |
2267 | |
2268 @defopt idlwave-file-header | |
2269 The doc-header template or a path to a file containing it. | |
2270 @end defopt | |
2271 | |
2272 @defopt idlwave-header-to-beginning-of-file (@code{nil}) | |
2273 Non-@code{nil} means the documentation header will always be at start | |
2274 of file. | |
2275 @end defopt | |
2276 | |
2277 @defopt idlwave-timestamp-hook | |
2278 The hook function used to update the timestamp of a function. | |
2279 @end defopt | |
2280 | |
2281 @defopt idlwave-doc-modifications-keyword | |
2282 The modifications keyword to use with the log documentation commands. | |
2283 @end defopt | |
2284 | |
2285 @defopt idlwave-doclib-start | |
2286 Regexp matching the start of a document library header. | |
2287 @end defopt | |
2288 | |
2289 @defopt idlwave-doclib-end | |
2290 Regexp matching the start of a document library header. | |
2291 @end defopt | |
2292 | |
2293 @node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode | |
2294 @section Motion Commands | |
2295 @cindex Motion commands | |
2296 @cindex Program structure, moving through | |
2297 @cindex Code structure, moving through | |
2298 @cindex @file{Func-menu}, XEmacs package | |
2299 @cindex @file{Imenu}, Emacs package | |
2300 @cindex Function definitions, jumping to | |
2301 @cindex Procedure definitions, jumping to | |
2302 | |
2303 IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages | |
2304 which make it easy to jump to the definitions of functions and | |
2305 procedures in the current file with a pop-up selection. To bind | |
2306 @file{Imenu} to a mouse-press, use in your @file{.emacs}: | |
2307 | |
2308 @lisp | |
2309 (define-key global-map [S-down-mouse-3] 'imenu) | |
2310 @end lisp | |
2311 | |
2312 @cindex @file{Speedbar}, Emacs package | |
2313 | |
2314 In addition, @file{Speedbar} support allows convenient navigation of a | |
2315 source tree of IDL routine files, quickly stepping to routine | |
2316 definitions. See @code{Tools->Display Speedbar}. | |
2317 | |
2318 Several commands allow you to move quickly through the structure of an | |
2319 IDL program: | |
2320 | |
2321 @multitable @columnfractions .15 .85 | |
2322 @item @kbd{C-M-a} | |
2323 @tab Beginning of subprogram | |
2324 @item @kbd{C-M-e} | |
2325 @tab End of subprogram | |
2326 @item @kbd{C-c @{} | |
2327 @tab Beginning of block (stay inside the block) | |
2328 @item @kbd{C-c @}} | |
2329 @tab End of block (stay inside the block) | |
2330 @item @kbd{C-M-n} | |
2331 @tab Forward block (on same level) | |
2332 @item @kbd{C-M-p} | |
2333 @tab Backward block (on same level) | |
2334 @item @kbd{C-M-d} | |
2335 @tab Down block (enters a block) | |
2336 @item @kbd{C-M-u} | |
2337 @tab Backward up block (leaves a block) | |
2338 @item @kbd{C-c C-n} | |
2339 @tab Next Statement | |
2340 @end multitable | |
2341 | |
2342 | |
2343 @node Misc Options, , Motion Commands, The IDLWAVE Major Mode | |
2344 @section Miscellaneous Options | |
2345 @cindex Hooks | |
2346 | |
2347 @defopt idlwave-help-application | |
2348 The external application providing reference help for programming. | |
2349 @end defopt | |
2350 | |
2351 @defopt idlwave-startup-message (@code{t}) | |
2352 Non-@code{nil} means display a startup message when @code{idlwave-mode}' | |
2353 is first called. | |
2354 @end defopt | |
2355 | |
2356 @defopt idlwave-mode-hook | |
2357 Normal hook. Executed when a buffer is put into @code{idlwave-mode}. | |
2358 @end defopt | |
2359 | |
2360 @defopt idlwave-load-hook | |
2361 Normal hook. Executed when @file{idlwave.el} is loaded. | |
2362 @end defopt | |
2363 | |
2364 @node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top | |
2365 @chapter The IDLWAVE Shell | |
2366 @cindex IDLWAVE shell | |
2367 @cindex Major mode, @code{idlwave-shell-mode} | |
2368 @cindex IDL, as Emacs subprocess | |
2369 @cindex Subprocess of Emacs, IDL | |
2370 @cindex Comint, Emacs package | |
2371 @cindex Windows | |
2372 @cindex MacOS | |
2373 | |
2374 The IDLWAVE shell is an Emacs major mode which permits running the IDL | |
2375 program as an inferior process of Emacs, and works closely with the | |
2376 IDLWAVE major mode in buffers. It can be used to work with IDL | |
2377 interactively, to compile and run IDL programs in Emacs buffers and to | |
2378 debug these programs. The IDLWAVE shell is built on @file{comint}, an | |
2379 Emacs packages which handles the communication with the IDL program. | |
2380 Unfortunately, IDL for Windows does not have command-prompt versions and | |
2381 thus do not allow the interaction with Emacs --- so the IDLWAVE shell | |
2382 currently only works under Unix and MacOSX. | |
2383 | |
2384 @menu | |
2385 * Starting the Shell:: How to launch IDL as a subprocess | |
2386 * Using the Shell:: Interactively working with the Shell | |
2387 * Commands Sent to the Shell:: | |
2388 * Debugging IDL Programs:: | |
2389 * Examining Variables:: | |
2390 * Custom Expression Examination:: | |
2391 @end menu | |
2392 | |
2393 @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell | |
2394 @section Starting the Shell | |
2395 @cindex Starting the shell | |
2396 @cindex Shell, starting | |
2397 @cindex Dedicated frame, for shell buffer | |
2398 @cindex Frame, for shell buffer | |
2399 @cindex Subprocess of Emacs, IDL | |
2400 | |
2401 @kindex C-c C-s | |
2402 The IDLWAVE shell can be started with the command @kbd{M-x | |
2403 idlwave-shell}. In @code{idlwave-mode} the function is bound to | |
2404 @kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to | |
2405 interact with the shell. If the shell is already running, @kbd{C-c | |
2406 C-s} will simply switch to the shell buffer. The command @kbd{C-c | |
2407 C-l} (@code{idlwave-shell-recenter-shell-window}) displays the shell | |
2408 window without selecting it. The shell can also be started | |
2409 automatically when another command tries to send a command to it. To | |
2410 enable auto start, set the variable | |
2411 @code{idlwave-shell-automatic-start} to @code{t}. | |
2412 | |
2413 In order to create a separate frame for the IDLWAVE shell buffer, call | |
2414 @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or | |
2415 @kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell | |
2416 window, configure the variable | |
2417 @code{idlwave-shell-use-dedicated-frame}. | |
2418 | |
2419 To launch a quick IDLWAVE shell directly from a shell prompt without | |
2420 an IDLWAVE buffer (e.g., as a replacement for running inside an | |
2421 xterm), define a system alias with the following content: | |
2422 | |
2423 @example | |
2424 emacs -geometry 80x32 -eval "(idlwave-shell 'quick)" | |
2425 @end example | |
2426 | |
2427 Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer | |
2428 the Emacs process to run directly inside the terminal window. | |
2429 | |
2430 @cindex ENVI | |
2431 @cindex IDL> Prompt | |
2432 | |
2433 To use IDLWAVE with ENVI or other custom packages which change the | |
2434 @samp{IDL> } prompt, you must change the | |
2435 @code{idlwave-shell-prompt-pattern}, which defaults to @samp{"^ ?IDL> | |
2436 "}. Normally, you can just replace the @samp{IDL} in this expression | |
2437 with the prompt you see. A suitable pattern which matches the prompt | |
2438 for both ENVI and IDL simultaneously is @samp{"^ ?\\(ENVI\\|IDL\\)> "}. | |
2439 | |
2440 @defopt idlwave-shell-explicit-file-name (@file{idl}) | |
2441 This is the command to run IDL. | |
2442 @end defopt | |
2443 | |
2444 @defopt idlwave-shell-command-line-options | |
2445 A list of command line options for calling the IDL program. | |
2446 @end defopt | |
2447 | |
2448 @defopt idlwave-shell-prompt-pattern | |
2449 Regexp to match IDL prompt at beginning of a line. | |
2450 @end defopt | |
2451 | |
2452 @defopt idlwave-shell-process-name | |
2453 Name to be associated with the IDL process. | |
2454 @end defopt | |
2455 | |
2456 @defopt idlwave-shell-automatic-start (@code{nil}) | |
2457 Non-@code{nil} means attempt to invoke idlwave-shell if not already | |
2458 running. | |
2459 @end defopt | |
2460 | |
2461 @defopt idlwave-shell-initial-commands | |
2462 Initial commands, separated by newlines, to send to IDL. | |
2463 @end defopt | |
2464 | |
2465 @defopt idlwave-shell-save-command-history (@code{t}) | |
2466 Non-@code{nil} means preserve command history between sessions. | |
2467 @end defopt | |
2468 | |
2469 @defopt idlwave-shell-command-history-file (@file{~/.idlwave/.idlwhist}) | |
2470 The file in which the command history of the idlwave shell is saved. | |
2471 Unless it's an absolute path, it goes in | |
2472 @code{idlwave-config-directory}. | |
2473 @end defopt | |
2474 | |
2475 @defopt idlwave-shell-use-dedicated-frame (@code{nil}) | |
2476 Non-@code{nil} means IDLWAVE should use a special frame to display the | |
2477 shell buffer. | |
2478 @end defopt | |
2479 | |
2480 @defopt idlwave-shell-use-dedicated-window (@code{nil}) | |
2481 Non-@code{nil} means use a dedicated window for the shell, taking care | |
2482 not it replace it with other buffers. | |
2483 @end defopt | |
2484 | |
2485 @defopt idlwave-shell-frame-parameters | |
2486 The frame parameters for a dedicated idlwave-shell frame. | |
2487 @end defopt | |
2488 | |
2489 @defopt idlwave-shell-raise-frame (@code{t}) | |
2490 Non-@code{nil} means `idlwave-shell' raises the frame showing the shell | |
2491 window. | |
2492 @end defopt | |
2493 | |
2494 @defopt idlwave-shell-temp-pro-prefix | |
2495 The prefix for temporary IDL files used when compiling regions. | |
2496 @end defopt | |
2497 | |
2498 @cindex Hooks | |
2499 @defopt idlwave-shell-mode-hook | |
2500 Hook for customizing @code{idlwave-shell-mode}. | |
2501 @end defopt | |
2502 | |
2503 @node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell | |
2504 @section Using the Shell | |
2505 @cindex Comint | |
2506 @cindex Shell, basic commands | |
2507 | |
2508 The IDLWAVE shell works in the same fashion as other shell modes in | |
2509 Emacs. It provides command history, command line editing and job | |
2510 control. The @key{UP} and @key{DOWN} arrows cycle through the input | |
2511 history just like in an X terminal@footnote{This is different from | |
2512 normal Emacs/Comint behavior, but more like an xterm. If you prefer the | |
2513 default comint functionality, check the variable | |
2514 @code{idlwave-shell-arrows-do-history}.}. The history is preserved | |
2515 between emacs and IDL sessions. Here is a list of commonly used | |
2516 commands: | |
2517 | |
2518 @multitable @columnfractions .12 .88 | |
2519 @item @key{UP}, @key{M-p} | |
2520 @tab Cycle backwards in input history | |
2521 @item @key{DOWN}, @key{M-n} | |
2522 @tab Cycle forwards in input history | |
2523 @item @kbd{M-r} | |
2524 @tab Previous input matching a regexp | |
2525 @item @kbd{M-s} | |
2526 @tab Next input matching a regexp | |
2527 @item @kbd{return} | |
2528 @tab Send input or copy line to current prompt | |
2529 @item @kbd{C-c C-a} | |
2530 @tab Beginning of line; skip prompt | |
2531 @item @kbd{C-c C-u} | |
2532 @tab Kill input to beginning of line | |
2533 @item @kbd{C-c C-w} | |
2534 @tab Kill word before cursor | |
2535 @item @kbd{C-c C-c} | |
2536 @tab Send ^C | |
2537 @item @kbd{C-c C-z} | |
2538 @tab Send ^Z | |
2539 @item @kbd{C-c C-\} | |
2540 @tab Send ^\ | |
2541 @item @kbd{C-c C-o} | |
2542 @tab Delete last batch of process output | |
2543 @item @kbd{C-c C-r} | |
2544 @tab Show last batch of process output | |
2545 @item @kbd{C-c C-l} | |
2546 @tab List input history | |
2547 @end multitable | |
2548 | |
2549 In addition to these standard @file{comint} commands, | |
2550 @code{idlwave-shell-mode} provides many of the same commands which | |
2551 simplify writing IDL code available in IDLWAVE buffers. This includes | |
2552 abbreviations, online help, and completion. See @ref{Routine Info} and | |
2553 @ref{Online Help} and @ref{Completion} for more information on these | |
2554 commands. | |
2555 | |
2556 @cindex Completion, in the shell | |
2557 @cindex Routine info, in the shell | |
2558 @cindex Online Help, in the shell | |
2559 @multitable @columnfractions .12 .88 | |
2560 @item @kbd{@key{TAB}} | |
2561 @tab Completion of file names (between quotes and after executive | |
2562 commands @samp{.run} and @samp{.compile}), routine names, class names, | |
2563 keywords, system variables, system variable tags etc. | |
2564 (@code{idlwave-shell-complete}). | |
2565 @item @kbd{M-@key{TAB}} | |
2566 @tab Same as @key{TAB} | |
2567 @item @kbd{C-c ?} | |
2568 @tab Routine Info display (@code{idlwave-routine-info}) | |
2569 @item @kbd{M-?} | |
2570 @tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp}) | |
2571 @item @kbd{C-c C-i} | |
2572 @tab Update routine info from buffers and shell | |
2573 (@code{idlwave-update-routine-info}) | |
2574 @item @kbd{C-c C-v} | |
2575 @tab Find the source file of a routine (@code{idlwave-find-module}) | |
2576 @item @kbd{C-c C-t} | |
2577 @tab Find the source file of a routine in the currently visited file | |
2578 (@code{idlwave-find-module-this-file}). | |
2579 @item @kbd{C-c =} | |
2580 @tab Compile a library routine (@code{idlwave-resolve}) | |
2581 @end multitable | |
2582 | |
2583 @defopt idlwave-shell-arrows-do-history (@code{t}) | |
2584 Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command | |
2585 history like xterm. | |
2586 @end defopt | |
2587 | |
2588 @defopt idlwave-shell-comint-settings | |
2589 Alist of special settings for the comint variables in the IDLWAVE Shell. | |
2590 @end defopt | |
2591 | |
2592 @defopt idlwave-shell-file-name-chars | |
2593 The characters allowed in file names, as a string. Used for file name | |
2594 completion. | |
2595 @end defopt | |
2596 | |
2597 @defopt idlwave-shell-graphics-window-size | |
2598 Size of IDL graphics windows popped up by special IDLWAVE command. | |
2599 @end defopt | |
2600 | |
2601 @cindex Input mode | |
2602 @cindex Character input mode (Shell) | |
2603 @cindex Line input mode (Shell) | |
2604 @cindex Magic spells, for input mode | |
2605 @cindex Spells, magic | |
2606 IDLWAVE works in line input mode: You compose a full command line, using | |
2607 all the power Emacs gives you to do this. When you press @key{RET}, the | |
2608 whole line is sent to IDL. Sometimes it is necessary to send single | |
2609 characters (without a newline), for example when an IDL program is | |
2610 waiting for single character input with the @code{GET_KBRD} function. | |
2611 You can send a single character to IDL with the command @kbd{C-c C-x} | |
2612 (@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y} | |
2613 (@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop | |
2614 which accepts characters and immediately sends them to IDL. The loop | |
2615 can be exited with @kbd{C-g}. It terminates also automatically when the | |
2616 current IDL command is finished. Check the documentation of the two | |
2617 variables described below for a way to make IDL programs trigger | |
2618 automatic switches of the input mode. | |
2619 | |
2620 @defopt idlwave-shell-use-input-mode-magic (@code{nil}) | |
2621 Non-@code{nil} means IDLWAVE should check for input mode spells in | |
2622 output. | |
2623 @end defopt | |
2624 | |
2625 @defopt idlwave-shell-input-mode-spells | |
2626 The three regular expressions which match the magic spells for input | |
2627 modes. | |
2628 @end defopt | |
2629 | |
2630 @node Commands Sent to the Shell, Debugging IDL Programs, Using the Shell, The IDLWAVE Shell | |
2631 @section Commands Sent to the Shell | |
2632 @cindex Commands in shell, showing | |
2633 @cindex Showing commands in shell | |
2634 | |
2635 The IDLWAVE buffers and shell interact very closely. In addition to the | |
2636 normal commands you enter at the @code{IDL>} prompt, many other special | |
2637 commands are sent to the shell, sometimes as a direct result of invoking | |
2638 a key command, menu item, or toolbar button, but also automatically, as | |
2639 part of the normal flow of information updates between the buffer and | |
2640 shell. | |
2641 | |
2642 The commands sent include @code{breakpoint}, @code{.step} and other | |
2643 debug commands (@pxref{Debugging IDL Programs}), @code{.run} and other | |
2644 compilation statements (@pxref{Compiling Programs}), examination | |
2645 commands like @code{print} and @code{help} (@pxref{Examining | |
2646 Variables}), and other special purpose commands designed to keep | |
2647 information on the running shell current. | |
2648 | |
2649 By default, much of this background shell input and output is hidden | |
2650 from the user, but this is configurable. The custom variable | |
2651 @code{idlwave-abbrev-show-commands} allows you to configure which | |
2652 commands sent to the shell are shown there. For a related customization | |
2653 for separating the output of @emph{examine} commands, see @ref{Examining | |
2654 Variables}. | |
2655 | |
2656 @defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)}) | |
2657 A list of command types to echo in the shell when sent. Possible values | |
2658 are @code{run} for @code{.run}, @code{.compile} and other run commands, | |
2659 @code{misc} for lesser used commands like @code{window}, | |
2660 @code{retall},@code{close}, etc., @code{breakpoint} for breakpoint | |
2661 setting and clearing commands, and @code{debug} for other debug, | |
2662 stepping, and continue commands. In addition, if the variable is set to | |
2663 the single symbol @code{'everything}, all the copious shell input is | |
2664 displayed (which is probably only useful for debugging purposes). | |
2665 N.B. For hidden commands which produce output by side-effect, that | |
2666 output remains hidden (e.g., stepping through a @code{print} command). | |
2667 As a special case, any error message in the output will be displayed | |
2668 (e.g., stepping to an error). | |
2669 @end defopt | |
2670 | |
2671 @node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell | |
2672 @section Debugging IDL Programs | |
2673 @cindex Debugging | |
2674 @cindex Keybindings for debugging | |
2675 @cindex Toolbar | |
2676 | |
2677 Programs can be compiled, run, and debugged directly from the source | |
2678 buffer in Emacs, walking through arbitrarily deeply nested code, | |
2679 printing expressions and skipping up and down the calling stack along | |
2680 the way. IDLWAVE makes compiling and debugging IDL programs far less | |
2681 cumbersome by providing a full-featured, key/menu/toolbar-driven | |
2682 interface to commands like @code{breakpoint}, @code{.step}, | |
2683 @code{.run}, etc. It can even perform complex debug operations not | |
2684 natively supported by IDL (like continuing to the line at the cursor). | |
2685 | |
2686 The IDLWAVE shell installs key bindings both in the shell buffer and | |
2687 in all IDL code buffers of the current Emacs session, so debug | |
2688 commands work in both places (in the shell, commands operate on the | |
2689 last file compiled). On Emacs versions which support it, a debugging | |
2690 toolbar is also installed. The toolbar display can be toggled with | |
2691 @kbd{C-c C-d C-t} (@code{idlwave-shell-toggle-toolbar}). | |
2692 | |
2693 | |
2694 @defopt idlwave-shell-use-toolbar (@code{t}) | |
2695 Non-@code{nil} means use the debugging toolbar in all IDL related | |
2696 buffers. | |
2697 @end defopt | |
2698 | |
2699 @menu | |
2700 * A Tale of Two Modes:: | |
2701 * Debug Key Bindings:: | |
2702 * Breakpoints and Stepping:: | |
2703 * Compiling Programs:: | |
2704 * Walking the Calling Stack:: | |
2705 * Electric Debug Mode:: | |
2706 @end menu | |
2707 | |
2708 | |
2709 @node A Tale of Two Modes, Debug Key Bindings, Debugging IDL Programs, Debugging IDL Programs | |
2710 @subsection A Tale of Two Modes | |
2711 @cindex Electric Debug Mode | |
2712 @cindex Debugging Interface | |
2713 | |
2714 The many debugging, compiling, and examination commands provided in | |
2715 IDLWAVE are available simultaneously through two different interfaces: | |
2716 the original, multi-key command interface, and the new Electric Debug | |
2717 Mode. The functionality they offer is similar, but the way you interact | |
2718 with them is quite different. The main difference is that, in Electric | |
2719 Debug Mode, the source buffers are made read-only, and single | |
2720 key-strokes are used to step through, examine expressions, set and | |
2721 remove breakpoints, etc. The same variables, prefix arguments, and | |
2722 settings apply to both versions, and both can be used interchangeably. | |
2723 By default, when breakpoints are hit, Electric Debug Mode is enabled. | |
2724 The traditional interface is described first. @xref{Electric Debug | |
2725 Mode}, for more on that mode. Note that electric debug mode can be | |
2726 prevented from activating automatically by customizing the variable | |
2727 @code{idlwave-shell-automatic-electric-debug}. | |
2728 | |
2729 @node Debug Key Bindings, Breakpoints and Stepping, A Tale of Two Modes, Debugging IDL Programs | |
2730 @subsection Debug Key Bindings | |
2731 @kindex C-c C-d | |
2732 @cindex Key bindings | |
2733 | |
2734 The standard debugging key bindings are always available by default on | |
2735 the prefix key @kbd{C-c C-d}, so, for example, setting a breakpoint is | |
2736 done with @kbd{C-c C-d C-b}, and compiling a source file with @kbd{C-c | |
2737 C-d C-c}. You can also easily configure IDLWAVE to use one or more | |
2738 modifier keys not in use by other commands, in lieu of the prefix | |
2739 @kbd{C-c C-d} (though these bindings will typically also be available | |
2740 --- see @code{idlwave-shell-activate-prefix-keybindings}). For | |
2741 example, if you include in @file{.emacs}: | |
2742 | |
2743 @lisp | |
2744 (setq idlwave-shell-debug-modifiers '(control shift)) | |
2745 @end lisp | |
2746 | |
2747 @noindent a breakpoint can then be set by pressing @kbd{b} while holding down | |
2748 @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a | |
2749 source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}, | |
2750 etc. In the remainder of this chapter we will assume that the | |
2751 @kbd{C-c C-d} bindings are active, but each of these bindings will | |
2752 have an equivalent shortcut if modifiers are given in the | |
2753 @code{idlwave-shell-debug-modifiers} variable (@pxref{Lesson II -- | |
2754 Customization}). A much simpler and faster form of debugging for | |
2755 running code is also available by default --- see @ref{Electric Debug | |
2756 Mode}. | |
2757 | |
2758 @defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) | |
2759 The prefix key for the debugging map | |
2760 @code{idlwave-shell-mode-prefix-map}. | |
2761 @end defopt | |
2762 | |
2763 @defopt idlwave-shell-activate-prefix-keybindings (@code{t}) | |
2764 Non-@code{nil} means debug commands will be bound to the prefix | |
2765 key, like @kbd{C-c C-d C-b}. | |
2766 @end defopt | |
2767 | |
2768 @defopt idlwave-shell-debug-modifiers (@code{nil}) | |
2769 List of modifier keys to use for additional, alternative binding of | |
2770 debugging commands in the shell and source buffers. Can be one or | |
2771 more of @code{control}, @code{meta}, @code{super}, @code{hyper}, | |
2772 @code{alt}, and @code{shift}. | |
2773 @end defopt | |
2774 | |
2775 @node Breakpoints and Stepping, Compiling Programs, Debug Key Bindings, Debugging IDL Programs | |
2776 @subsection Breakpoints and Stepping | |
2777 @cindex Breakpoints | |
2778 @cindex Stepping | |
2779 @cindex Execution, controlled | |
2780 | |
2781 @kindex C-c C-d C-b | |
2782 @kindex C-c C-d C-b | |
2783 IDLWAVE helps you set breakpoints and step through code. Setting a | |
2784 breakpoint in the current line of the source buffer is accomplished | |
2785 with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a | |
2786 prefix arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a | |
2787 @code{/ONCE} keyword, meaning that it will be deleted after first use. | |
2788 With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), | |
2789 the breakpoint will only be active the @code{nth} time it is hit. | |
2790 With a single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt | |
2791 for a condition --- an IDL expression to be evaluated and trigger the | |
2792 breakpoint only if true. To clear the breakpoint in the current line, | |
2793 use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When | |
2794 executed from the shell window, the breakpoint where IDL is currently | |
2795 stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d | |
2796 C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled | |
2797 and re-enabled: @kbd{C-c C-d C-\} | |
2798 (@code{idlwave-shell-toggle-enable-current-bp}). | |
2799 | |
2800 Breakpoint lines are highlighted or indicated with an icon in the source | |
2801 code (different icons for conditional, after, and other break types). | |
2802 Disabled breakpoints are @emph{grayed out} by default. Note that IDL | |
2803 places breakpoints as close as possible on or after the line you | |
2804 specify. IDLWAVE queries the shell for the actual breakpoint location | |
2805 which was set, so the exact line you specify may not be marked. You can | |
2806 re-sync the breakpoint list and update the display at any time (e.g., if | |
2807 you add or remove some on the command line) using @kbd{C-c C-d C-l}. | |
2808 | |
2809 In recent IDLWAVE versions, the breakpoint line is highlighted when the | |
2810 mouse is moved over it, and a tooltip pops up describing the break | |
2811 details. @kbd{Mouse-3} on the breakpoint line pops up a menu of | |
2812 breakpoint actions, including clearing, disabling, and adding or | |
2813 changing break conditions or ``after'' break count. | |
2814 | |
2815 Once the program has stopped somewhere, you can step through it. The | |
2816 most important stepping commands are @kbd{C-c C-d C-s} to execute one | |
2817 line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line, | |
2818 treating procedure and function calls as a single step ("step over"); | |
2819 @kbd{C-c C-d C-h} to continue execution to the line at the cursor and | |
2820 @kbd{C-c C-d C-r} to continue execution. @xref{Commands Sent to the | |
2821 Shell}, for information on displaying or hiding the breakpoint and | |
2822 stepping commands the shell receives. Here is a summary of the | |
2823 breakpoint and stepping commands: | |
2824 | |
2825 @multitable @columnfractions .23 .77 | |
2826 @item @kbd{C-c C-d C-b} | |
2827 @tab Set breakpoint (@code{idlwave-shell-break-here}) | |
2828 @item @kbd{C-c C-d C-i} | |
2829 @tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) | |
2830 @item @kbd{C-c C-d C-d} | |
2831 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) | |
2832 @item @kbd{C-c C-d C-a} | |
2833 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) | |
2834 @item @kbd{C-c C-d [} | |
2835 @tab Go to the previous breakpoint (@code{idlwave-shell-goto-previous-bp}) | |
2836 @item @kbd{C-c C-d ]} | |
2837 @tab Go to the next breakpoint (@code{idlwave-shell-goto-next-bp}) | |
2838 @item @kbd{C-c C-d C-\} | |
2839 @tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) | |
2840 @item @kbd{C-c C-d C-j} | |
2841 @tab Set a breakpoint at the beginning of the enclosing routine. | |
2842 @item @kbd{C-c C-d C-s} | |
2843 @tab Step, into function calls (@code{idlwave-shell-step}) | |
2844 @item @kbd{C-c C-d C-n} | |
2845 @tab Step, over function calls (@code{idlwave-shell-stepover}) | |
2846 @item @kbd{C-c C-d C-k} | |
2847 @tab Skip one statement (@code{idlwave-shell-skip}) | |
2848 @item @kbd{C-c C-d C-u} | |
2849 @tab Continue to end of block (@code{idlwave-shell-up}) | |
2850 @item @kbd{C-c C-d C-m} | |
2851 @tab Continue to end of function (@code{idlwave-shell-return}) | |
2852 @item @kbd{C-c C-d C-o} | |
2853 @tab Continue past end of function (@code{idlwave-shell-out}) | |
2854 @item @kbd{C-c C-d C-h} | |
2855 @tab Continue to line at cursor position (@code{idlwave-shell-to-here}) | |
2856 @item @kbd{C-c C-d C-r} | |
2857 @tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) | |
2858 @item @kbd{C-c C-d C-up} | |
2859 @tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) | |
2860 @item @kbd{C-c C-d C-down} | |
2861 @tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) | |
2862 @end multitable | |
2863 | |
2864 All of these commands have equivalents in Electric Debug Mode, which | |
2865 provides faster single-key access (@pxref{Electric Debug Mode}). | |
2866 | |
2867 The line where IDL is currently stopped, at breakpoints, halts, and | |
2868 errors, etc., is marked with a color overlay or arrow, depending on the | |
2869 setting in @code{idlwave-shell-mark-stop-line}. If an overlay face is | |
2870 used to mark the stop line (as it is by default), when stepping through | |
2871 code, the face color is temporarily changed to gray, until IDL completes | |
2872 the next command and moves to the new line. | |
2873 | |
2874 @defopt idlwave-shell-mark-breakpoints (@code{t}) | |
2875 Non-@code{nil} means mark breakpoints in the source file buffers. The | |
2876 value indicates the preferred method. Valid values are @code{nil}, | |
2877 @code{t}, @code{face}, and @code{glyph}. | |
2878 @end defopt | |
2879 | |
2880 @defopt idlwave-shell-breakpoint-face | |
2881 The face for breakpoint lines in the source code if | |
2882 @code{idlwave-shell-mark-breakpoints} has the value @code{face}. | |
2883 @end defopt | |
2884 | |
2885 @defopt idlwave-shell-breakpoint-popup-menu (@code{t}) | |
2886 Whether to pop-up a menu and present a tooltip description on | |
2887 breakpoint lines. | |
2888 @end defopt | |
2889 | |
2890 @defopt idlwave-shell-mark-stop-line (@code{t}) | |
2891 Non-@code{nil} means mark the source code line where IDL is currently | |
2892 stopped. The value specifies the preferred method. Valid values are | |
2893 @code{nil}, @code{t}, @code{arrow}, and @code{face}. | |
2894 @end defopt | |
2895 | |
2896 @defopt idlwave-shell-overlay-arrow (@code{">"}) | |
2897 The overlay arrow to display at source lines where execution halts, if | |
2898 configured in @code{idlwave-shell-mark-stop-line}. | |
2899 @end defopt | |
2900 | |
2901 @defopt idlwave-shell-stop-line-face | |
2902 The face which highlights the source line where IDL is stopped, if | |
2903 configured in @code{idlwave-shell-mark-stop-line}. | |
2904 @end defopt | |
2905 | |
2906 | |
2907 @node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs | |
2908 @subsection Compiling Programs | |
2909 @cindex Compiling programs | |
2910 @cindex Programs, compiling | |
2911 @cindex Default command line, executing | |
2912 @cindex Executing a default command line | |
2913 | |
2914 @kindex C-c C-d C-c | |
2915 In order to compile the current buffer under the IDLWAVE shell, press | |
2916 @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the | |
2917 current buffer and then sends the command @samp{.run path/to/file} to the | |
2918 shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in | |
2919 which case the most recently compiled buffer will be saved and | |
2920 re-compiled. | |
2921 | |
2922 When developing or debugging a program, it is often necessary to execute | |
2923 the same command line many times. A convenient way to do this is | |
2924 @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}). | |
2925 This command first resets IDL from a state of interrupted execution by | |
2926 closing all files and returning to the main interpreter level. Then a | |
2927 default command line is send to the shell. To edit the default command | |
2928 line, call @code{idlwave-shell-execute-default-command-line} with a | |
2929 prefix argument: @kbd{C-u C-c C-d C-y}. If no default command line has | |
2930 been set (or you give two prefix arguments), the last command on the | |
2931 @code{comint} input history is sent. | |
2932 | |
2933 @kindex C-c C-d C-e | |
2934 @cindex Compiling regions | |
2935 For quickly compiling and running the currently marked region as a main | |
2936 level program @kbd{C-c C-d C-e} (@code{idlwave-shell-run-region}) is | |
2937 very useful. A temporary file is created holding the contents of the | |
2938 current region (with @code{END} appended), and run from the shell. | |
2939 | |
2940 @node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs | |
2941 @subsection Walking the Calling Stack | |
2942 @cindex Calling stack, walking | |
2943 | |
2944 While debugging a program, it can be very useful to check the context in | |
2945 which the current routine was called, for instance to help understand | |
2946 the value of the arguments passed. To do so conveniently you need to | |
2947 examine the calling stack. If execution is stopped somewhere deep in a | |
2948 program, you can use the commands @kbd{C-c C-d C-@key{UP}} | |
2949 (@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}} | |
2950 (@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons, | |
2951 to move up or down through the calling stack. The mode line of the | |
2952 shell window will indicate the position within the stack with a label | |
2953 like @samp{[-3:MYPRO]}. The line of IDL code at that stack position | |
2954 will be highlighted. If you continue execution, IDLWAVE will | |
2955 automatically return to the current level. @xref{Examining Variables}, | |
2956 for information how to examine the value of variables and expressions on | |
2957 higher calling stack levels. | |
2958 | |
2959 @html | |
2960 <A NAME="EDEBUG"></A> | |
2961 @end html | |
2962 @node Electric Debug Mode, , Walking the Calling Stack, Debugging IDL Programs | |
2963 @subsection Electric Debug Mode | |
2964 @cindex Electric Debug Mode | |
2965 @cindex @samp{*Debugging*} | |
2966 | |
2967 Even with a convenient debug key prefix enabled, repetitive stepping, | |
2968 variable examination (@pxref{Examining Variables}), and other debugging | |
2969 activities can be awkward and slow using commands which require multiple | |
2970 keystrokes. Luckily, there's a better way, inspired by the lisp e-debug | |
2971 mode, and available through the @emph{Electric Debug Mode}. By default, | |
2972 as soon as a breakpoint is hit, this minor mode is enabled. The buffer | |
2973 showing the line where execution has halted is switched to Electric | |
2974 Debug Mode. This mode is visible as @samp{*Debugging*} in the mode | |
2975 line, and a different face (violet by default, if color is available) | |
2976 for the line stopped at point. The buffer is made read-only and | |
2977 single-character bindings for the most commonly used debugging commands | |
2978 are enabled. These character commands (a list of which is available | |
2979 with @kbd{C-?}) are: | |
2980 | |
2981 @multitable @columnfractions .2 .8 | |
2982 @item @kbd{a} | |
2983 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) | |
2984 @item @kbd{b} | |
2985 @tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here}) | |
2986 @item @kbd{d} | |
2987 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) | |
2988 @item @kbd{e} | |
2989 @tab Prompt for expression to print (@code{idlwave-shell-clear-current-bp}). | |
2990 @item @kbd{h} | |
2991 @tab Continue to the line at cursor position (@code{idlwave-shell-to-here}) | |
2992 @item @kbd{i} | |
2993 @tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) | |
2994 @item @kbd{[} | |
2995 @tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp}) | |
2996 @item @kbd{]} | |
2997 @tab Go to the next breakpoint in the file | |
2998 (@code{idlwave-shell-goto-next-bp}) | |
2999 @item @kbd{\} | |
3000 @tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) | |
3001 @item @kbd{j} | |
3002 @tab Set breakpoint at beginning of enclosing routine (@code{idlwave-shell-break-this-module}) | |
3003 @item @kbd{k} | |
3004 @tab Skip one statement (@code{idlwave-shell-skip}) | |
3005 @item @kbd{m} | |
3006 @tab Continue to end of function (@code{idlwave-shell-return}) | |
3007 @item @kbd{n} | |
3008 @tab Step, over function calls (@code{idlwave-shell-stepover}) | |
3009 @item @kbd{o} | |
3010 @tab Continue past end of function (@code{idlwave-shell-out}) | |
3011 @item @kbd{p} | |
3012 @tab Print expression near point or in region with @kbd{C-u p} (@code{idlwave-shell-print}) | |
3013 @item @kbd{q} | |
3014 @tab End the debugging session and return to the Shell's main level | |
3015 (@code{idlwave-shell-retall}) | |
3016 @item @kbd{r} | |
3017 @tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) | |
3018 @item @kbd{s} or @kbd{@key{SPACE}} | |
3019 @tab Step, into function calls (@code{idlwave-shell-step}) | |
3020 @item @kbd{t} | |
3021 @tab Print a calling-level traceback in the shell | |
3022 @item @kbd{u} | |
3023 @tab Continue to end of block (@code{idlwave-shell-up}) | |
3024 @item @kbd{v} | |
3025 @tab Turn Electric Debug Mode off | |
3026 (@code{idlwave-shell-electric-debug-mode}) | |
3027 @item @kbd{x} | |
3028 @tab Examine expression near point (or in region with @kbd{C-u x}) | |
3029 with shortcut of examine type. | |
3030 @item @kbd{z} | |
3031 @tab Reset IDL (@code{idlwave-shell-reset}) | |
3032 @item @kbd{+} or @kbd{=} | |
3033 @tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) | |
3034 @item @kbd{-} or @kbd{_} | |
3035 @tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) | |
3036 @item @kbd{?} | |
3037 @tab Help on expression near point or in region with @kbd{C-u ?} | |
3038 (@code{idlwave-shell-help-expression}) | |
3039 @item @kbd{C-?} | |
3040 @tab Show help on the commands available. | |
3041 @end multitable | |
3042 | |
3043 Most single-character electric debug bindings use the final keystroke | |
3044 of the equivalent multiple key commands (which are of course also | |
3045 still available), but some differ (e.g. @kbd{e},@kbd{t},@kbd{q},@kbd{x}). | |
3046 Some have additional convenience bindings (like @kbd{@key{SPACE}} for | |
3047 stepping). All prefix and other argument options described in this | |
3048 section for the commands invoked by electric debug bindings are still | |
3049 valid. For example, @kbd{C-u b} sets a conditional breakpoint, just | |
3050 as it did with @kbd{C-u C-c C-d C-b}. | |
3051 | |
3052 You can toggle the electric debug mode at any time in a buffer using | |
3053 @kbd{C-c C-d C-v} (@kbd{v} to turn it off while in the mode), or from | |
3054 the Debug menu. Normally the mode will be enabled and disabled at the | |
3055 appropriate times, but occasionally you might want to edit a file | |
3056 while still debugging it, or switch to the mode for conveniently | |
3057 setting lots of breakpoints. | |
3058 | |
3059 To quickly abandon a debugging session and return to normal editing at | |
3060 the Shell's main level, use @kbd{q} (@code{idlwave-shell-retall}). | |
3061 This disables electric debug mode in all IDLWAVE buffers@footnote{Note | |
3062 that this binding is not symmetric: @kbd{C-c C-d C-q} is bound to | |
3063 @code{idlwave-shell-quit}, which quits your IDL session.}. Help is | |
3064 available for the command shortcuts with @kbd{C-?}. If you find this | |
3065 mode gets in your way, you can keep it from automatically activating | |
3066 by setting the variable @code{idlwave-shell-automatic-electric-debug} | |
3067 to @code{nil}, or @code{'breakpoint}. If you'd like the convenient | |
3068 electric debug shortcuts available also when run-time errors are | |
3069 encountered, set to @code{t}. | |
3070 | |
3071 @defopt idlwave-shell-automatic-electric-debug (@code{'breakpoint}) | |
3072 Whether to enter electric debug mode automatically when a breakpoint | |
3073 or run-time error is encountered, and then disable it in all buffers | |
3074 when the $MAIN$ level is reached (either through normal program | |
3075 execution, or retall). In addition to @code{nil} for never, and | |
3076 @code{t} for both breakpoints and errors, this can be | |
3077 @code{'breakpoint} (the default) to enable it only at breakpoint | |
3078 halts. | |
3079 @end defopt | |
3080 | |
3081 @defopt idlwave-shell-electric-stop-color (Violet) | |
3082 Default color of the stopped line overlay when in electric debug mode. | |
3083 @end defopt | |
3084 | |
3085 @defopt idlwave-shell-electric-stop-line-face | |
3086 The face to use for the stopped line. Defaults to a face similar to the | |
3087 modeline, with color @code{idlwave-shell-electric-stop-color}. | |
3088 @end defopt | |
3089 | |
3090 @defopt idlwave-shell-electric-zap-to-file (@code{t}) | |
3091 If set, when entering electric debug mode, select the window displaying | |
3092 the file where point is stopped. This takes point away from the shell | |
3093 window, but is useful for immediate stepping, etc. | |
3094 @end defopt | |
3095 | |
3096 @html | |
3097 <A NAME="EXAMINE"></A> | |
3098 @end html | |
3099 @node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell | |
3100 @section Examining Variables | |
3101 @cindex @code{PRINT} expressions | |
3102 @cindex @code{HELP}, on expressions | |
3103 @cindex Expressions, printing & help | |
3104 @cindex Examining expressions | |
3105 @cindex Printing expressions | |
3106 @cindex Mouse binding to print expressions | |
3107 | |
3108 @kindex C-c C-d C-p | |
3109 Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)}, | |
3110 and similar statements to remind yourself of the | |
3111 type/size/structure/value/etc. of variables and expressions in your code | |
3112 or at the command line? IDLWAVE has a suite of special commands to | |
3113 automate these types of variable or expression examinations. They work | |
3114 by sending statements to the shell formatted to include the indicated | |
3115 expression, and can be accessed in several ways. | |
3116 | |
3117 These @emph{examine} commands can be used in the shell or buffer at any | |
3118 time (as long as the shell is running), and are very useful when | |
3119 execution is stopped in a buffer due to a triggered breakpoint or error, | |
3120 or while composing a long command in the IDLWAVE shell. In the latter | |
3121 case, the command is sent to the shell and its output is visible, but | |
3122 point remains unmoved in the command being composed --- you can inspect | |
3123 the constituents of a command you're building without interrupting the | |
3124 process of building it! You can even print arbitrary expressions from | |
3125 older input or output further up in the shell window --- any expression, | |
3126 variable, number, or function you see can be examined. | |
3127 | |
3128 If the variable @code{idlwave-shell-separate-examine-output} is | |
3129 non-@code{nil} (the default), all examine output will be sent to a | |
3130 special @file{*Examine*} buffer, rather than the shell. The output of | |
3131 prior examine commands is saved in this buffer. In this buffer @key{c} | |
3132 clears the contents, and @key{q} hides the buffer. | |
3133 | |
3134 The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to | |
3135 print the expression at point, and @kbd{C-c C-d ?}, to invoke help on | |
3136 this expression@footnote{Available as @kbd{p} and @kbd{?} in Electric | |
3137 Debug Mode (@pxref{Electric Debug Mode})}. The expression at point is | |
3138 either an array expression or a function call, or the contents of a pair | |
3139 of parentheses. The chosen expression is highlighted, and | |
3140 simultaneously the resulting output is highlighted in the shell or | |
3141 separate output buffer. Calling the above commands with a prefix | |
3142 argument will use the current region as expression instead of using the | |
3143 one at point. which can be useful for examining complicated, multi-line | |
3144 expressions. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will | |
3145 prompt for an expression to print directly. By default, when invoking | |
3146 print, only an initial portion of long arrays will be printed, up to | |
3147 @code{idlwave-shell-max-print-length}. | |
3148 | |
3149 For added speed and convenience, there are mouse bindings which allow | |
3150 you to click on expressions and examine their values. Use | |
3151 @kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke | |
3152 help (i.e. you need to hold down @key{META} and @key{CONTROL} while | |
3153 clicking with the middle mouse button). If you simply click, the | |
3154 nearest expression will be selected in the same manner as described | |
3155 above. You can also @emph{drag} the mouse in order to highlight | |
3156 exactly the specific expression or sub-expression you want to examine. | |
3157 For custom expression examination, and the powerful customizable | |
3158 pop-up examine selection, @xref{Custom Expression Examination}. | |
3159 | |
3160 @cindex Printing expressions, on calling stack | |
3161 @cindex Restrictions for expression printing | |
3162 The same variable inspection commands work both in the IDL Shell and | |
3163 IDLWAVE buffers, and even for variables at higher levels of the calling | |
3164 stack. For instance, if you're stopped at a breakpoint in a routine, | |
3165 you can examine the values of variables and expressions inside its | |
3166 calling routine, and so on, all the way up through the calling stack. | |
3167 Simply step up the stack, and print variables as you see them | |
3168 (@pxref{Walking the Calling Stack}, for information on stepping back | |
3169 through the calling stack). The following restrictions apply for all | |
3170 levels except the current: | |
3171 | |
3172 @itemize @bullet | |
3173 @item | |
3174 Array expressions must use the @samp{[ ]} index delimiters. Identifiers | |
3175 with a @samp{( )} will be interpreted as function calls. | |
3176 @item | |
3177 @cindex ROUTINE_NAMES, IDL procedure | |
3178 N.B.: printing values of expressions on higher levels of the calling | |
3179 stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, | |
3180 which may or may not be available in future versions of IDL. Caveat | |
3181 Examinor. | |
3182 @end itemize | |
3183 | |
3184 @defopt idlwave-shell-expression-face | |
3185 The face for @code{idlwave-shell-expression-overlay}. | |
3186 Allows you to choose the font, color and other properties for | |
3187 the expression printed by IDL. | |
3188 @end defopt | |
3189 | |
3190 @defopt idlwave-shell-output-face | |
3191 The face for @code{idlwave-shell-output-overlay}. | |
3192 Allows to choose the font, color and other properties for the most | |
3193 recent output of IDL when examining an expression." | |
3194 @end defopt | |
3195 | |
3196 @defopt idlwave-shell-separate-examine-output (@code{t}) | |
3197 If non-@code{nil}, re-direct the output of examine commands to a special | |
3198 @file{*Examine*} buffer, instead of in the shell itself. | |
3199 @end defopt | |
3200 | |
3201 @defopt idlwave-shell-max-print-length (200) | |
3202 The maximum number of leading array entries to print, when examining | |
3203 array expressions. | |
3204 @end defopt | |
3205 | |
3206 @node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell | |
3207 @section Custom Expression Examination | |
3208 @cindex Expressions, custom examination | |
3209 @cindex Custom expression examination | |
3210 | |
3211 The variety of possible variable and expression examination commands is | |
3212 endless (just look, for instance, at the keyword list to | |
3213 @code{widget_info()}). Rather than attempt to include them all, IDLWAVE | |
3214 provides two easy methods to customize your own commands, with a special | |
3215 mouse examine command, and two macros for generating your own examine | |
3216 key and mouse bindings. | |
3217 | |
3218 The most powerful and flexible mouse examine command of all is | |
3219 available on @kbd{C-S-Mouse-2}. Just as for all the other mouse | |
3220 examine commands, it permits click or drag expression selection, but | |
3221 instead of sending hard-coded commands to the shell, it pops-up a | |
3222 customizable selection list of examine functions to choose among, | |
3223 configured with the @code{idlwave-shell-examine-alist} | |
3224 variable@footnote{In Electric Debug Mode (@pxref{Electric Debug | |
3225 Mode}), the key @kbd{x} provides a single-character shortcut interface | |
3226 to the same examine functions for the expression at point or marked by | |
3227 the region.}. This variable is a list of key-value pairs (an | |
3228 @emph{alist} in Emacs parlance), where the key gives a name to be | |
3229 shown for the examine command, and the value is the command strings | |
3230 itself, in which the text @code{___} (three underscores) will be | |
3231 replaced by the selected expression before being sent to the shell. | |
3232 An example might be key @code{Structure Help} with value | |
3233 @code{help,___,/STRUCTURE}. In that case, you'd be prompted with | |
3234 @emph{Structure Help}, which might send something like | |
3235 @code{help,var,/STRUCTURE} to the shell for output. | |
3236 @code{idlwave-shell-examine-alist} comes configured by default with a | |
3237 large list of examine commands, but you can easily customize it to add | |
3238 your own. | |
3239 | |
3240 In addition to configuring the functions available to the pop-up mouse | |
3241 command, you can easily create your own customized bindings to inspect | |
3242 expressions using the two convenience macros | |
3243 @code{idlwave-shell-examine} and @code{idlwave-shell-mouse-examine}. | |
3244 These create keyboard or mouse-based custom inspections of variables, | |
3245 sharing all the same properties of the built-in examine commands. | |
3246 Both functions take a single string argument sharing the syntax of the | |
3247 @code{idlwave-shell-examine-alist} values, e.g.: | |
3248 | |
3249 @lisp | |
3250 (add-hook 'idlwave-shell-mode-hook | |
3251 (lambda () | |
3252 (idlwave-shell-define-key-both [s-down-mouse-2] | |
3253 (idlwave-shell-mouse-examine | |
3254 "print, size(___,/DIMENSIONS)")) | |
3255 (idlwave-shell-define-key-both [f9] (idlwave-shell-examine | |
3256 "print, size(___,/DIMENSIONS)")) | |
3257 (idlwave-shell-define-key-both [f10] (idlwave-shell-examine | |
3258 "print,size(___,/TNAME)")) | |
3259 (idlwave-shell-define-key-both [f11] (idlwave-shell-examine | |
3260 "help,___,/STRUCTURE")))) | |
3261 @end lisp | |
3262 | |
3263 @noindent Now pressing @key{f9}, or middle-mouse dragging with the | |
3264 @key{SUPER} key depressed, will print the dimensions of the nearby or | |
3265 highlighted expression. Pressing @key{f10} will give the type string, | |
3266 and @key{f11} will show the contents of a nearby structure. As you can | |
3267 see, the possibilities are only marginally finite. | |
3268 | |
3269 @defopt idlwave-shell-examine-alist | |
3270 An alist of examine commands in which the keys name the command and | |
3271 are displayed in the selection pop-up, and the values are custom IDL | |
3272 examine command strings to send, after all instances of @code{___} | |
3273 (three underscores) are replaced by the indicated expression. | |
3274 @end defopt | |
3275 | |
3276 @node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top | |
3277 @chapter Acknowledgements | |
3278 @cindex Acknowledgements | |
3279 @cindex Maintainer, of IDLWAVE | |
3280 @cindex Authors, of IDLWAVE | |
3281 @cindex Contributors, to IDLWAVE | |
3282 @cindex Email address, of Maintainer | |
3283 @cindex Thanks | |
3284 | |
3285 @noindent | |
3286 The main contributors to the IDLWAVE package have been: | |
3287 | |
3288 @itemize @minus | |
3289 @item | |
3290 @uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author. | |
3291 Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them | |
3292 for several years. | |
3293 | |
3294 @item | |
3295 @uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge | |
3296 of the package from version 3.0, during which time he overhauled almost | |
3297 everything, modernized IDLWAVE with many new features, and developed the | |
3298 manual. | |
3299 | |
3300 @item | |
3301 @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current | |
3302 maintainer, as of version 4.10, helped shape object method completion | |
3303 and most new features introduced in versions 4.x, and introduced many | |
3304 new features for IDLWAVE versions 5.x and 6.x. | |
3305 @end itemize | |
3306 | |
3307 @noindent | |
3308 The following people have also contributed to the development of IDLWAVE | |
3309 with patches, ideas, bug reports and suggestions. | |
3310 | |
3311 @itemize @minus | |
3312 @item | |
3313 Ulrik Dickow <dickow__at__nbi.dk> | |
3314 @item | |
3315 Eric E. Dors <edors__at__lanl.gov> | |
3316 @item | |
3317 Stein Vidar H. Haugan <s.v.h.haugan__at__astro.uio.no> | |
3318 @item | |
3319 David Huenemoerder <dph__at__space.mit.edu> | |
3320 @item | |
3321 Kevin Ivory <Kevin.Ivory__at__linmpi.mpg.de> | |
3322 @item | |
3323 Dick Jackson <dick__at__d-jackson.com> | |
3324 @item | |
3325 Xuyong Liu <liu__at__stsci.edu> | |
3326 @item | |
3327 Simon Marshall <Simon.Marshall__at__esrin.esa.it> | |
3328 @item | |
3329 Craig Markwardt <craigm__at__cow.physics.wisc.edu> | |
3330 @item | |
3331 Laurent Mugnier <mugnier__at__onera.fr> | |
3332 @item | |
3333 Lubos Pochman <lubos__at__rsinc.com> | |
3334 @item | |
3335 Bob Portmann <portmann__at__al.noaa.gov> | |
3336 @item | |
3337 Patrick M. Ryan <pat__at__jaameri.gsfc.nasa.gov> | |
3338 @item | |
3339 Marty Ryba <ryba__at__ll.mit.edu> | |
3340 @item | |
3341 Phil Williams <williams__at__irc.chmcc.org> | |
3342 @item | |
3343 Phil Sterne <sterne__at__dublin.llnl.gov> | |
3344 @item | |
3345 Paul Sorenson <aardvark62__at__msn.com> | |
3346 @end itemize | |
3347 | |
3348 Doug Dirks was instrumental in providing the crucial IDL XML catalog to | |
3349 support HTML help with IDL v6.2 and later, and Ali Bahrami provided | |
3350 scripts and documentation to interface with the IDL Assistant. | |
3351 | |
3352 @noindent | |
3353 Thanks to everyone! | |
3354 | |
3355 @node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top | |
3356 @appendix Sources of Routine Info | |
3357 | |
3358 @cindex Sources of routine information | |
3359 In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE | |
3360 displays the calling sequence and keywords of routines, and completes | |
3361 routine names and keywords. For these features to work, IDLWAVE must | |
3362 know about the accessible routines. | |
3363 | |
3364 @menu | |
3365 * Routine Definitions:: Where IDL Routines are defined. | |
3366 * Routine Information Sources:: So how does IDLWAVE know about... | |
3367 * Catalogs:: | |
3368 * Load-Path Shadows:: Routines defined in several places | |
3369 * Documentation Scan:: Scanning the IDL Manuals | |
3370 @end menu | |
3371 | |
3372 @node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info | |
3373 @appendixsec Routine Definitions | |
3374 @cindex Routine definitions | |
3375 @cindex IDL variable @code{!PATH} | |
3376 @cindex @code{!PATH}, IDL variable | |
3377 @cindex @code{CALL_EXTERNAL}, IDL routine | |
3378 @cindex @code{LINKIMAGE}, IDL routine | |
3379 @cindex External routines | |
3380 | |
3381 @noindent Routines which can be used in an IDL program can be defined in | |
3382 several places: | |
3383 | |
3384 @enumerate | |
3385 @item | |
3386 @emph{Builtin routines} are defined inside IDL itself. The source code | |
3387 of such routines is not available, but instead are learned about through | |
3388 the IDL documentation. | |
3389 @item | |
3390 Routines which are @emph{part of the current program}, are defined in a | |
3391 file explicitly compiled by the user. This file may or may not be | |
3392 located on the IDL search path. | |
3393 @item | |
3394 @emph{Library routines} are defined in files located on IDL's search | |
3395 path. When a library routine is called for the first time, IDL will | |
3396 find the source file and compile it dynamically. A special sub-category | |
3397 of library routines are the @emph{system routines} distributed with IDL, | |
3398 and usually available in the @file{lib} subdirectory of the IDL | |
3399 distribution. | |
3400 @item | |
3401 External routines written in other languages (like Fortran or C) can be | |
3402 called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, | |
3403 or included as dynamically loaded modules (DLMs). Currently IDLWAVE | |
3404 cannot provide routine info and completion for such external routines, | |
3405 except by querying the Shell for calling information (DLMs only). | |
3406 @end enumerate | |
3407 | |
3408 @node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info | |
3409 @appendixsec Routine Information Sources | |
3410 @cindex Routine info sources | |
3411 @cindex Builtin list of routines | |
3412 @cindex Updating routine info | |
3413 @cindex Scanning buffers for routine info | |
3414 @cindex Buffers, scanning for routine info | |
3415 @cindex Shell, querying for routine info | |
3416 | |
3417 @noindent To maintain the most comprehensive information about all IDL | |
3418 routines on a system, IDLWAVE collects data from many sources: | |
3419 | |
3420 @enumerate | |
3421 | |
3422 @item | |
3423 It has a @emph{builtin list} with information about the routines IDL | |
3424 ships with. IDLWAVE @value{VERSION} is distributed with a list of | |
3425 @value{NSYSROUTINES} routines and object methods, reflecting IDL version | |
3426 @value{IDLVERSION}. As of IDL v6.2, the routine info is distributed | |
3427 directly with IDL in the form of an XML catalog which IDLWAVE scans. | |
3428 Formerly, this list was created by scanning the IDL manuals to produce | |
3429 the file @file{idlw-rinfo.el}. | |
3430 | |
3431 @item | |
3432 IDLWAVE @emph{scans} all its @emph{buffers} in the current Emacs session | |
3433 for routine definitions. This is done automatically when routine | |
3434 information or completion is first requested by the user. Each new | |
3435 buffer and each buffer saved after making changes is also scanned. The | |
3436 command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used | |
3437 at any time to rescan all buffers. | |
3438 | |
3439 @item | |
3440 If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will | |
3441 @emph{query the shell} for compiled routines and their arguments. This | |
3442 happens automatically when routine information or completion is first | |
3443 requested by the user. Each time an Emacs buffer is compiled with | |
3444 @kbd{C-c C-d C-c}, the routine info for that file is queried. Though | |
3445 rarely necessary, the command @kbd{C-c C-i} | |
3446 (@code{idlwave-update-routine-info}) can be used to explicitly update | |
3447 the shell routine data. | |
3448 | |
3449 @item | |
3450 Many popular libraries are distributed with routine information already | |
3451 scanned into @emph{library catalogs} (@pxref{Library Catalogs}). These | |
3452 per-directory catalog files can also be built by the user with the | |
3453 supplied @file{idlwave_catalog} tool. They are automatically discovered | |
3454 by IDLWAVE. | |
3455 | |
3456 @item | |
3457 IDLWAVE can scan selected directories of source files and store the | |
3458 result in a single @emph{user catalog} file which will be | |
3459 automatically loaded just like @file{idlw-rinfo.el}. @xref{User | |
3460 Catalog}, for information on how to scan files in this way. | |
3461 @end enumerate | |
3462 | |
3463 Loading all the routine and catalog information can be a time consuming | |
3464 process, especially over slow networks. Depending on the system and | |
3465 network configuration it could take up to 30 seconds (though locally on | |
3466 fast systems is usually only a few seconds). In order to minimize the | |
3467 wait time upon your first completion or routine info command in a | |
3468 session, IDLWAVE uses Emacs idle time to do the initialization in six | |
3469 steps, yielding to user input in between. If this gets into your way, | |
3470 set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero). | |
3471 The more routines documented in library and user catalogs, the slower | |
3472 the loading will be, so reducing this number can help alleviate any long | |
3473 load times. | |
3474 | |
3475 @defopt idlwave-init-rinfo-when-idle-after (@code{10}) | |
3476 Seconds of idle time before routine info is automatically initialized. | |
3477 @end defopt | |
3478 | |
3479 @defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) | |
3480 Non-@code{nil} means scan all buffers for IDL programs when updating | |
3481 info. | |
3482 @end defopt | |
3483 | |
3484 @defopt idlwave-query-shell-for-routine-info (@code{t}) | |
3485 Non-@code{nil} means query the shell for info about compiled routines. | |
3486 @end defopt | |
3487 | |
3488 @defopt idlwave-auto-routine-info-updates | |
3489 Controls under what circumstances routine info is updated automatically. | |
3490 @end defopt | |
3491 | |
3492 @html | |
3493 <A NAME="CATALOGS"></A> | |
3494 @end html | |
3495 @node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info | |
3496 @appendixsec Catalogs | |
3497 @cindex Catalogs | |
3498 | |
3499 @emph{Catalogs} are files containing scanned information on individual | |
3500 routines, including arguments and keywords, calling sequence, file path, | |
3501 class and procedure vs. function type, etc. They represent a way of | |
3502 extending the internal built-in information available for IDL system | |
3503 routines (@pxref{Routine Info}) to other source collections. | |
3504 | |
3505 Starting with version 5.0, there are two types of catalogs available | |
3506 with IDLWAVE. The traditional @emph{user catalog} and the newer | |
3507 @emph{library catalogs}. Although they can be used interchangeably, the | |
3508 library catalogs are more flexible, and preferred. There are few | |
3509 occasions when a user catalog might be preferred --- read below. Both | |
3510 types of catalogs can coexist without causing problems. | |
3511 | |
3512 To facilitate the catalog systems, IDLWAVE stores information it gathers | |
3513 from the shell about the IDL search paths, and can write this | |
3514 information out automatically, or on-demand (menu @code{Debug->Save Path | |
3515 Info}). On systems with no shell from which to discover the path | |
3516 information (e.g. Windows), a library path must be specified in | |
3517 @code{idlwave-library-path} to allow library catalogs to be located, and | |
3518 to setup directories for user catalog scan (@pxref{User Catalog} for | |
3519 more on this variable). Note that, before the shell is running, IDLWAVE | |
3520 can only know about the IDL search path by consulting the file pointed | |
3521 to by @code{idlwave-path-file} (@file{~/.idlwave/idlpath.el}, by | |
3522 default). If @code{idlwave-auto-write-path} is enabled (which is the | |
3523 default), the paths are written out whenever the IDLWAVE shell is | |
3524 started. | |
3525 | |
3526 @defopt idlwave-auto-write-path (@code{t}) | |
3527 Write out information on the !PATH and !DIR paths from IDL automatically | |
3528 when they change and when the Shell is closed. These paths are needed | |
3529 to locate library catalogs. | |
3530 @end defopt | |
3531 | |
3532 @defopt idlwave-library-path | |
3533 IDL library path for Windows and MacOS. Under Unix/MacOSX, will be | |
3534 obtained from the Shell when run. | |
3535 @end defopt | |
3536 | |
3537 @defopt idlwave-system-directory | |
3538 The IDL system directory for Windows and MacOS. Also needed for | |
3539 locating HTML help and the IDL Assistant for IDL v6.2 and later. Under | |
3540 Unix/MacOSX, will be obtained from the Shell and recorded, if run. | |
3541 @end defopt | |
3542 | |
3543 @defopt idlwave-config-directory (@file{~/.idlwave}) | |
3544 Default path where IDLWAVE saves configuration information, a user | |
3545 catalog (if any), and a cached scan of the XML catalog (IDL v6.2 and | |
3546 later). | |
3547 @end defopt | |
3548 | |
3549 @menu | |
3550 * Library Catalogs:: | |
3551 * User Catalog:: | |
3552 @end menu | |
3553 | |
3554 @html | |
3555 <A NAME="LIBRARY_CATALOGS"></A> | |
3556 @end html | |
3557 @node Library Catalogs, User Catalog, Catalogs, Catalogs | |
3558 @appendixsubsec Library Catalogs | |
3559 @cindex @file{.idlwave_catalog} | |
3560 @cindex Library catalogs | |
3561 @cindex @code{idlwave_catalog} | |
3562 | |
3563 Library catalogs consist of files named @file{.idlwave_catalog} stored | |
3564 in directories containing @code{.pro} routine files. They are | |
3565 discovered on the IDL search path and loaded automatically when routine | |
3566 information is read. Each catalog file documents the routines found in | |
3567 that directory --- one catalog per directory. Every catalog has a | |
3568 library name associated with it (e.g. @emph{AstroLib}). This name will | |
3569 be shown briefly when the catalog is found, and in the routine info of | |
3570 routines it documents. | |
3571 | |
3572 Many popular libraries of routines are shipped with IDLWAVE catalog | |
3573 files by default, and so will be automatically discovered. Library | |
3574 catalogs are scanned externally to Emacs using a tool provided with | |
3575 IDLWAVE. Each catalog can be re-scanned independently of any other. | |
3576 Catalogs can easily be made available system-wide with a common source | |
3577 repository, providing uniform routine information, and lifting the | |
3578 burden of scanning from the user (who may not even know they're using a | |
3579 scanned catalog). Since all catalogs are independent, they can be | |
3580 re-scanned automatically to gather updates, e.g. in a @file{cron} job. | |
3581 Scanning is much faster than with the built-in user catalog method. One | |
3582 minor disadvantage: the entire IDL search path is scanned for catalog | |
3583 files every time IDLWAVE starts up, which might be slow if accessing IDL | |
3584 routines over a slow network. | |
3585 | |
3586 A Perl tool to create library catalogs is distributed with IDLWAVE: | |
3587 @code{idlwave_catalog}. It can be called quite simply: | |
3588 @example | |
3589 idlwave_catalog MyLib | |
3590 @end example | |
3591 | |
3592 @noindent This will scan all directories recursively beneath the current and | |
3593 populate them with @file{.idlwave_catalog} files, tagging the routines | |
3594 found there with the name library ``MyLib''. The full usage | |
3595 information: | |
3596 | |
3597 @example | |
3598 Usage: idlwave_catalog [-l] [-v] [-d] [-s] [-f] [-h] libname | |
3599 libname - Unique name of the catalog (4 or more alphanumeric | |
3600 characters). | |
3601 -l - Scan local directory only, otherwise recursively | |
3602 catalog all directories at or beneath this one. | |
3603 -v - Print verbose information. | |
3604 -d - Instead of scanning, delete all .idlwave_catalog files | |
3605 here or below. | |
3606 -s - Be silent. | |
3607 -f - Force overwriting any catalogs found with a different | |
3608 library name. | |
3609 -h - Print this usage. | |
3610 @end example | |
3611 | |
3612 To re-load the library catalogs on the IDL path, force a system routine | |
3613 info update using a single prefix to @code{idlwave-update-routine-info}: | |
3614 @kbd{C-u C-c C-i}. | |
3615 | |
3616 @defopt idlwave-use-library-catalogs (@code{t}) | |
3617 Whether to search for and load library catalogs. Disable if load | |
3618 performance is a problem and/or the catalogs are not needed. | |
3619 @end defopt | |
3620 | |
3621 @node User Catalog, , Library Catalogs, Catalogs | |
3622 @appendixsubsec User Catalog | |
3623 @cindex User catalog | |
3624 @cindex IDL library routine info | |
3625 @cindex Windows | |
3626 @cindex MacOS | |
3627 @cindex IDL variable @code{!DIR} | |
3628 @cindex @code{!DIR}, IDL variable | |
3629 | |
3630 The user catalog is the old routine catalog system. It is produced | |
3631 within Emacs, and stored in a single file in the user's home directory | |
3632 (@file{.idlwave/idlusercat.el} by default). Although library catalogs | |
3633 are more flexible, there may be reasons to prefer a user catalog | |
3634 instead, including: | |
3635 | |
3636 @itemize @bullet | |
3637 @item The scan is internal to Emacs, so you don't need a working Perl | |
3638 installation, as you do for library catalogs. | |
3639 @item Can be used to scan directories for which the user has no write | |
3640 privileges. | |
3641 @item Easy widget-based path selection. | |
3642 @end itemize | |
3643 | |
3644 However, no routine info is available in the user catalog by default; | |
3645 the user must actively complete a scan. In addition, this type of | |
3646 catalog is all or nothing: if a single routine changes, the entire | |
3647 catalog must be rescanned to update it. Creating the user catalog is | |
3648 also much slower than scanning library catalogs. | |
3649 | |
3650 You can scan any of the directories on the currently known path. Under | |
3651 Windows and MacOS (not OSX), you need to specify the IDL search path in | |
3652 the variable @code{idlwave-library-path}, and the location of the IDL | |
3653 directory (the value of the @code{!DIR} system variable) in the variable | |
3654 @code{idlwave-system-directory}, like this@footnote{The initial @samp{+} | |
3655 leads to recursive expansion of the path, just like in IDL}: | |
3656 | |
3657 @lisp | |
3658 (setq idlwave-library-path | |
3659 '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs")) | |
3660 (setq idlwave-system-directory "c:/RSI/IDL56/") | |
3661 @end lisp | |
3662 | |
3663 @noindent Under GNU/Linux and UNIX, these values will be automatically | |
3664 gathered from the IDLWAVE shell, if run. | |
3665 | |
3666 The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item | |
3667 @samp{IDLWAVE->Routine Info->Select Catalog Directories}) can then be | |
3668 used to create a user catalog. It brings up a widget in which you can | |
3669 select some or all directories on the search path. Directories which | |
3670 already contain a library catalog are marked with @samp{[LIB]}, and need | |
3671 not be scanned (although there is no harm if you do so, other than the | |
3672 additional memory used for the duplication). | |
3673 | |
3674 After selecting directories, click on the @w{@samp{[Scan & Save]}} | |
3675 button in the widget to scan all files in the selected directories and | |
3676 write out the resulting routine information. In order to update the | |
3677 library information using the directory selection, call the command | |
3678 @code{idlwave-update-routine-info} with a double prefix argument: | |
3679 @w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously | |
3680 selected directories, write an updated version of the user catalog file | |
3681 and rebuild IDLWAVE's internal lists. If you give three prefix | |
3682 arguments @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a | |
3683 background job@footnote{Unix systems only, I think.}. You can continue | |
3684 to work, and the library catalog will be re-read when it is ready. If | |
3685 you find you need to update the user catalog often, you should consider | |
3686 building a library catalog for your routines instead (@pxref{Library | |
3687 Catalogs}). | |
3688 | |
3689 @defopt idlwave-special-lib-alist | |
3690 Alist of regular expressions matching special library directories for | |
3691 labeling in routine-info display. | |
3692 @end defopt | |
3693 | |
3694 @node Load-Path Shadows, Documentation Scan, Catalogs, Sources of Routine Info | |
3695 @appendixsec Load-Path Shadows | |
3696 @cindex Load-path shadows | |
3697 @cindex Shadows, load-path | |
3698 @cindex Duplicate routines | |
3699 @cindex Multiply defined routines | |
3700 @cindex Routine definitions, multiple | |
3701 @cindex Application, testing for shadowing | |
3702 @cindex Buffer, testing for shadowing | |
3703 | |
3704 IDLWAVE can compile a list of routines which are (re-)defined in more | |
3705 than one file. Since one definition will hide (shadow) the others | |
3706 depending on which file is compiled first, such multiple definitions are | |
3707 called "load-path shadows". IDLWAVE has several routines to scan for | |
3708 load path shadows. The output is placed into the special buffer | |
3709 @file{*Shadows*}. The format of the output is identical to the source | |
3710 section of the routine info buffer (@pxref{Routine Info}). The | |
3711 different definitions of a routine are ordered by @emph{likelihood of | |
3712 use}. So the first entry will be most likely the one you'll get if an | |
3713 unsuspecting command uses that routine. Before listing shadows, you | |
3714 should make sure that routine info is up-to-date by pressing @kbd{C-c | |
3715 C-i}. Here are the different routines (also available in the Menu | |
3716 @samp{IDLWAVE->Routine Info}): | |
3717 | |
3718 @table @asis | |
3719 @item @kbd{M-x idlwave-list-buffer-load-path-shadows} | |
3720 This commands checks the names of all routines defined in the current | |
3721 buffer for shadowing conflicts with other routines accessible to | |
3722 IDLWAVE. The command also has a key binding: @kbd{C-c C-b} | |
3723 @item @kbd{M-x idlwave-list-shell-load-path-shadows}. | |
3724 Checks all routines compiled under the shell for shadowing. This is | |
3725 very useful when you have written a complete application. Just compile | |
3726 the application, use @code{RESOLVE_ALL} to compile any routines used by | |
3727 your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and | |
3728 then check for shadowing. | |
3729 @item @kbd{M-x idlwave-list-all-load-path-shadows} | |
3730 This command checks all routines accessible to IDLWAVE for conflicts. | |
3731 @end table | |
3732 | |
3733 For these commands to work fully you need to scan the entire load path | |
3734 in either a user or library catalog. Also, IDLWAVE should be able to | |
3735 distinguish between the system library files (normally installed in | |
3736 @file{/usr/local/rsi/idl/lib}) and any site specific or user specific | |
3737 files. Therefore, such local files should not be installed inside the | |
3738 @file{lib} directory of the IDL directory. This is also advisable for | |
3739 many other reasons. | |
3740 | |
3741 @cindex Windows | |
3742 @cindex MacOS | |
3743 @cindex IDL variable @code{!DIR} | |
3744 @cindex @code{!DIR}, IDL variable | |
3745 Users of Windows and MacOS (not X) also must set the variable | |
3746 @code{idlwave-system-directory} to the value of the @code{!DIR} system | |
3747 variable in IDL. IDLWAVE appends @file{lib} to the value of this | |
3748 variable and assumes that all files found on that path are system | |
3749 routines. | |
3750 | |
3751 Another way to find out if a specific routine has multiple definitions | |
3752 on the load path is routine info display (@pxref{Routine Info}). | |
3753 | |
3754 @node Documentation Scan, , Load-Path Shadows, Sources of Routine Info | |
3755 @appendixsec Documentation Scan | |
3756 @cindex @file{get_html_rinfo} | |
3757 @cindex @file{idlw-rinfo.el} | |
3758 @cindex Scanning the documentation | |
3759 @cindex Perl program, to create @file{idlw-rinfo.el} | |
3760 | |
3761 @strong{Starting with version 6.2, IDL is distributed directly with HTML | |
3762 online help, and an XML-based catalog of routine information}. This | |
3763 makes scanning the manuals with the tool @file{get_html_rinfo}, and the | |
3764 @file{idlw-rinfo.el} file it produced, as described here, entirely | |
3765 unnecessary. The information is left here for users wishing to produce | |
3766 a catalog of older IDL versions' help. | |
3767 | |
3768 | |
3769 IDLWAVE derives its knowledge about system routines from the IDL | |
3770 manuals. The file @file{idlw-rinfo.el} contains the routine information | |
3771 for the IDL system routines, and links to relevant sections of the HTML | |
3772 documentation. The Online Help feature of IDLWAVE requires HTML | |
3773 versions of the IDL manuals to be available; the HTML documentation is | |
3774 not distributed with IDLWAVE by default, but must be downloaded | |
3775 separately. | |
3776 | |
3777 The HTML files and related images can be produced from the | |
3778 @file{idl.chm} HTMLHelp file distributed with IDL using the free | |
3779 Microsoft HTML Help Workshop. If you are lucky, the maintainer of | |
3780 IDLWAVE will always have access to the newest version of IDL and provide | |
3781 updates. The IDLWAVE distribution also contains the Perl program | |
3782 @file{get_html_rinfo} which constructs the @file{idlw-rinfo.el} file by | |
3783 scanning the HTML documents produced from the IDL documentation. | |
3784 Instructions on how to use @file{get_html_rinfo} are in the program | |
3785 itself. | |
3786 | |
3787 @node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top | |
3788 @appendix HTML Help Browser Tips | |
3789 @cindex Browser Tips | |
3790 | |
3791 There are a wide variety of possible browsers to use for displaying | |
3792 the online HTML help available with IDLWAVE (starting with version | |
3793 5.0). Since IDL v6.2, a single cross-platform HTML help browser, the | |
3794 @emph{IDL Assistant} is distributed with IDL. If this help browser is | |
3795 available, it is the preferred choice, and the default. The variable | |
3796 @code{idlwave-help-use-assistant}, enabled by default, controls | |
3797 whether this help browser is used. If you use the IDL Assistant, the | |
3798 tips here are not relevant. | |
3799 | |
3800 Since IDLWAVE runs on a many different system types, a single browser | |
3801 configuration is not possible, but choices abound. On many systems, | |
3802 the default browser configured in @code{browse-url-browser-function}, | |
3803 and hence inherited by default by | |
3804 @code{idlwave-help-browser-function}, is Netscape. Unfortunately, the | |
3805 HTML manuals decompiled from the original source contain formatting | |
3806 structures which Netscape 4.x does not handle well, though they are | |
3807 still readable. A much better choice is Mozilla, or one of the | |
3808 Mozilla-derived browsers such as | |
3809 @uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux), | |
3810 @uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or | |
3811 @uref{http://www.mozilla.org/projects/firebird/,Firebird} (all | |
3812 platforms). Newer versions of Emacs provide a browser-function choice | |
3813 @code{browse-url-gnome-moz} which uses the Gnome-configured browser. | |
3814 | |
3815 Note that the HTML files decompiled from the help sources contain | |
3816 specific references to the @samp{Symbol} font, which by default is not | |
3817 permitted in normal encodings (it's invalid, technically). Though it | |
3818 only impacts a few symbols, you can trick Mozilla-based browsers into | |
3819 recognizing @samp{Symbol} by following the directions | |
3820 @uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With | |
3821 this fix in place, HTML help pages look almost identical to their PDF | |
3822 equivalents (yet can be bookmarked, browsed as history, searched, | |
3823 etc.). | |
3824 | |
3825 @noindent Individual platform recommendations: | |
3826 | |
3827 @itemize @bullet | |
3828 @item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser | |
3829 and its associated | |
3830 @uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode | |
3831 provide in-buffer browsing with image display, and excellent speed and | |
3832 formatting. Both the Emacs mode and the browser itself must be | |
3833 downloaded separately. To use this browser, include | |
3834 | |
3835 @lisp | |
3836 (setq idlwave-help-browser-function 'w3m-browse-url) | |
3837 @end lisp | |
3838 | |
3839 in your @file{.emacs}. Setting a few other nice @code{w3m} options | |
3840 cuts down on screen clutter: | |
3841 | |
3842 @lisp | |
3843 (setq w3m-use-tab nil | |
3844 w3m-use-header-line nil | |
3845 w3m-use-toolbar nil) | |
3846 @end lisp | |
3847 | |
3848 If you use a dedicated frame for help, you might want to add the | |
3849 following, to get consistent behavior with the @kbd{q} key: | |
3850 | |
3851 @lisp | |
3852 ;; Close my help window when w3m closes. | |
3853 (defadvice w3m-close-window (after idlwave-close activate) | |
3854 (if (boundp 'idlwave-help-frame) | |
3855 (idlwave-help-quit))) | |
3856 @end lisp | |
3857 | |
3858 Note that you can open the file in an external browser from within | |
3859 @code{w3m} using @kbd{M}. | |
3860 @end itemize | |
3861 | |
3862 @node Configuration Examples, Windows and MacOS, HTML Help Browser Tips, Top | |
3863 @appendix Configuration Examples | |
3864 @cindex Configuration examples | |
3865 @cindex Example configuration | |
3866 @cindex @file{.emacs} | |
3867 @cindex Default settings, of options | |
3868 @cindex Interview, with the maintainer | |
3869 | |
3870 @noindent | |
3871 @b{Question:} You have all these complicated configuration options in | |
3872 your package, but which ones do @emph{you} as the maintainer actually | |
3873 set in your own configuration? | |
3874 | |
3875 @noindent | |
3876 @b{Answer:} Not many, beyond custom key bindings. I set most defaults | |
3877 the way that seems best. However, the default settings do not turn on | |
3878 features which: | |
3879 | |
3880 @itemize @minus | |
3881 @item | |
3882 are not self-evident (i.e. too magic) when used by an unsuspecting user. | |
3883 @item | |
3884 are too intrusive. | |
3885 @item | |
3886 will not work properly on all Emacs installations. | |
3887 @item | |
3888 break with widely used standards. | |
3889 @item | |
3890 use function or other non-standard keys. | |
3891 @item | |
3892 are purely personal customizations, like additional key bindings, and | |
3893 library names. | |
3894 @end itemize | |
3895 | |
3896 @noindent To see what I mean, here is the @emph{entire} configuration | |
3897 the old maintainer had in his @file{.emacs}: | |
3898 | |
3899 @lisp | |
3900 (setq idlwave-shell-debug-modifiers '(control shift) | |
3901 idlwave-store-inquired-class t | |
3902 idlwave-shell-automatic-start t | |
3903 idlwave-main-block-indent 2 | |
3904 idlwave-init-rinfo-when-idle-after 2 | |
3905 idlwave-help-dir "~/lib/emacs/idlwave" | |
3906 idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib") | |
3907 ("/jhuapl/" . "JHUAPL-Lib") | |
3908 ("/dominik/lib/idl/" . "MyLib"))) | |
3909 @end lisp | |
3910 | |
3911 However, if you are an Emacs power-user and want IDLWAVE to work | |
3912 completely differently, you can change almost every aspect of it. Here | |
3913 is an example of a much more extensive configuration of IDLWAVE. The | |
3914 user is King! | |
3915 | |
3916 @example | |
3917 ;;; Settings for IDLWAVE mode | |
3918 | |
3919 (setq idlwave-block-indent 3) ; Indentation settings | |
3920 (setq idlwave-main-block-indent 3) | |
3921 (setq idlwave-end-offset -3) | |
3922 (setq idlwave-continuation-indent 1) | |
3923 (setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" | |
3924 ; anchored at start of line. | |
3925 (setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> | |
3926 (setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' | |
3927 (setq idlwave-expand-generic-end t) ; convert END to ENDIF etc... | |
3928 (setq idlwave-reserved-word-upcase t) ; Make reserved words upper case | |
3929 ; (with abbrevs only) | |
3930 (setq idlwave-abbrev-change-case nil) ; Don't force case of expansions | |
3931 (setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill | |
3932 (setq idlwave-show-block nil) ; Turn off blinking to begin | |
3933 (setq idlwave-abbrev-move t) ; Allow abbrevs to move point | |
3934 (setq idlwave-query-class '((method-default . nil) ; No query for method | |
3935 (keyword-default . nil); or keyword completion | |
3936 ("INIT" . t) ; except for these | |
3937 ("CLEANUP" . t) | |
3938 ("SETPROPERTY" .t) | |
3939 ("GETPROPERTY" .t))) | |
3940 | |
3941 ;; Using w3m for help (must install w3m and emacs-w3m) | |
3942 (autoload 'w3m-browse-url "w3m" "Interface for w3m on Emacs." t) | |
3943 (setq idlwave-help-browser-function 'w3m-browse-url | |
3944 w3m-use-tab nil ; no tabs, location line, or toolbar | |
3945 w3m-use-header-line nil | |
3946 w3m-use-toolbar nil) | |
3947 | |
3948 ;; Close my help window or frame when w3m closes with `q' | |
3949 (defadvice w3m-close-window (after idlwave-close activate) | |
3950 (if (boundp 'idlwave-help-frame) | |
3951 (idlwave-help-quit))) | |
3952 | |
3953 ;; Some setting can only be done from a mode hook. Here is an example: | |
3954 (add-hook 'idlwave-mode-hook | |
3955 (lambda () | |
3956 (setq case-fold-search nil) ; Make searches case sensitive | |
3957 ;; Run other functions here | |
3958 (font-lock-mode 1) ; Turn on font-lock mode | |
3959 (idlwave-auto-fill-mode 0) ; Turn off auto filling | |
3960 (setq idlwave-help-browser-function 'browse-url-w3) | |
3961 | |
3962 ;; Pad with 1 space (if -n is used then make the | |
3963 ;; padding a minimum of n spaces.) The defaults use -1 | |
3964 ;; instead of 1. | |
3965 (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1)) | |
3966 (idlwave-action-and-binding "<" '(idlwave-surround 1 1)) | |
3967 (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-))) | |
3968 (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) | |
3969 | |
3970 ;; Only pad after comma and with exactly 1 space | |
3971 (idlwave-action-and-binding "," '(idlwave-surround nil 1)) | |
3972 (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) | |
3973 | |
3974 ;; Pad only after `->', remove any space before the arrow | |
3975 (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2)) | |
3976 | |
3977 ;; Set some personal bindings | |
3978 ;; (In this case, makes `,' have the normal self-insert behavior.) | |
3979 (local-set-key "," 'self-insert-command) | |
3980 (local-set-key [f5] 'idlwave-shell-break-here) | |
3981 (local-set-key [f6] 'idlwave-shell-clear-current-bp) | |
3982 | |
3983 ;; Create a newline, indenting the original and new line. | |
3984 ;; A similar function that does _not_ reindent the original | |
3985 ;; line is on "\C-j" (The default for emacs programming modes). | |
3986 (local-set-key "\n" 'idlwave-newline) | |
3987 ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. | |
3988 | |
3989 ;; Some personal abbreviations | |
3990 (define-abbrev idlwave-mode-abbrev-table | |
3991 (concat idlwave-abbrev-start-char "wb") "widget_base()" | |
3992 (idlwave-keyword-abbrev 1)) | |
3993 (define-abbrev idlwave-mode-abbrev-table | |
3994 (concat idlwave-abbrev-start-char "on") "obj_new()" | |
3995 (idlwave-keyword-abbrev 1)) | |
3996 )) | |
3997 | |
3998 ;;; Settings for IDLWAVE SHELL mode | |
3999 | |
4000 (setq idlwave-shell-overlay-arrow "=>") ; default is ">" | |
4001 (setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame | |
4002 (setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> " | |
4003 (setq idlwave-shell-explicit-file-name "wave") | |
4004 (setq idlwave-shell-process-name "wave") | |
4005 (setq idlwave-shell-use-toolbar nil) ; No toolbar | |
4006 | |
4007 ;; Most shell interaction settings can be done from the shell-mode-hook. | |
4008 (add-hook 'idlwave-shell-mode-hook | |
4009 (lambda () | |
4010 ;; Set up some custom key and mouse examine commands | |
4011 (idlwave-shell-define-key-both [s-down-mouse-2] | |
4012 (idlwave-shell-mouse-examine | |
4013 "print, size(___,/DIMENSIONS)")) | |
4014 (idlwave-shell-define-key-both [f9] (idlwave-shell-examine | |
4015 "print, size(___,/DIMENSIONS)")) | |
4016 (idlwave-shell-define-key-both [f10] (idlwave-shell-examine | |
4017 "print,size(___,/TNAME)")) | |
4018 (idlwave-shell-define-key-both [f11] (idlwave-shell-examine | |
4019 "help,___,/STRUCTURE")))) | |
4020 @end example | |
4021 | |
4022 @html | |
4023 <A NAME="WIN_MAC"></A> | |
4024 @end html | |
4025 @node Windows and MacOS, Troubleshooting, Configuration Examples, Top | |
4026 @appendix Windows and MacOS | |
4027 @cindex Windows | |
4028 @cindex MacOS | |
4029 @cindex MacOSX | |
4030 | |
4031 IDLWAVE was developed on a UNIX system. However, thanks to the | |
4032 portability of Emacs, much of IDLWAVE does also work under different | |
4033 operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS. | |
4034 | |
4035 The only real problem is that there is no command-line version of IDL | |
4036 for Windows or MacOS(<=9) with which IDLWAVE can interact. As a | |
4037 result, the IDLWAVE Shell does not work and you have to rely on IDLDE | |
4038 to run and debug your programs. However, editing IDL source files | |
4039 with Emacs/IDLWAVE works with all bells and whistles, including | |
4040 routine info, completion and fast online help. Only a small amount of | |
4041 additional information must be specified in your @file{.emacs} file: | |
4042 the path names which, on a UNIX system, are automatically gathered by | |
4043 talking to the IDL program. | |
4044 | |
4045 Here is an example of the additional configuration needed for a Windows | |
4046 system. I am assuming that IDLWAVE has been installed in | |
4047 @w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in | |
4048 @w{@samp{C:\RSI\IDL63}}. | |
4049 | |
4050 @lisp | |
4051 ;; location of the lisp files (only needed if IDLWAVE is not part of | |
4052 ;; your default X/Emacs installation) | |
4053 (setq load-path (cons "c:/program files/IDLWAVE" load-path)) | |
4054 | |
4055 ;; The location of the IDL library directories, both standard, and your own. | |
4056 ;; note that the initial "+" expands the path recursively | |
4057 (setq idlwave-library-path | |
4058 '("+c:/RSI/IDL63/lib/" "+c:/path/to/my/idllibs" )) | |
4059 | |
4060 ;; location of the IDL system directory (try "print,!DIR") | |
4061 (setq idlwave-system-directory "c:/RSI/IDL63/") | |
4062 | |
4063 @end lisp | |
4064 | |
4065 @noindent Furthermore, Windows sometimes tries to outsmart you --- make | |
4066 sure you check the following things: | |
4067 | |
4068 @itemize @bullet | |
4069 @item When you download the IDLWAVE distribution, make sure you save the | |
4070 file under the names @file{idlwave.tar.gz}. | |
4071 @item M-TAB switches among running programs --- use Esc-TAB | |
4072 instead. | |
4073 @item Other issues as yet unnamed... | |
4074 @end itemize | |
4075 | |
4076 Windows users who'd like to make use of IDLWAVE's context-aware HTML | |
4077 help can skip the browser and use the HTMLHelp functionality directly. | |
4078 @xref{Help with HTML Documentation}. | |
4079 | |
4080 @html | |
4081 <A NAME="TROUBLE"></A> | |
4082 @end html | |
4083 @node Troubleshooting, GNU Free Documentation License, Windows and MacOS, Top | |
4084 @appendix Troubleshooting | |
4085 @cindex Troubleshooting | |
4086 | |
4087 Although IDLWAVE usually installs and works without difficulty, a few | |
4088 common problems and their solutions are documented below. | |
4089 | |
4090 @enumerate | |
4091 | |
4092 @item @strong{Whenever an IDL error occurs or a breakpoint is hit, I get | |
4093 errors or strange behavior when I try to type anything into some of my | |
4094 IDLWAVE buffers.} | |
4095 | |
4096 This is a @emph{feature}, not an error. You're in @emph{Electric | |
4097 Debug Mode} (@pxref{Electric Debug Mode}). You should see | |
4098 @code{*Debugging*} in the mode-line. The buffer is read-only and all | |
4099 debugging and examination commands are available as single keystrokes; | |
4100 @kbd{C-?} lists these shortcuts. Use @kbd{q} to quit the mode, and | |
4101 customize the variable @code{idlwave-shell-automatic-electric-debug} | |
4102 if you prefer not to enter electric debug on breakpoints@dots{} but | |
4103 you really should try it before you disable it! You can also | |
4104 customize this variable to enter debug mode when errors are | |
4105 encountered. | |
4106 | |
4107 @item @strong{I get errors like @samp{Searching for program: no such | |
4108 file or directory, idl} when attempting to start the IDL shell.} | |
4109 | |
4110 IDLWAVE needs to know where IDL is in order to run it as a process. | |
4111 By default, it attempts to invoke it simply as @samp{idl}, which | |
4112 presumes such an executable is on your search path. You need to | |
4113 ensure @samp{idl} is on your @samp{$PATH}, or specify the full | |
4114 pathname to the idl program with the variable | |
4115 @code{idlwave-shell-explicit-file-name}. Note that you may need to | |
4116 set your shell search path in two places when running Emacs as an Aqua | |
4117 application with MacOSX; see the next topic. | |
4118 | |
4119 @item @strong{IDLWAVE is disregarding my @samp{IDL_PATH} which I set | |
4120 under MacOSX} | |
4121 | |
4122 If you run Emacs directly as an Aqua application, rather than from the | |
4123 console shell, the environment is set not from your usual shell | |
4124 configuration files (e.g. @file{.cshrc}), but from the file | |
4125 @file{~/.MacOSX/environment.plist}. Either include your path settings | |
4126 there, or start Emacs and IDLWAVE from the shell. | |
4127 | |
4128 @item @strong{I get errors like @samp{Symbol's function is void: | |
4129 overlayp}} | |
4130 | |
4131 You don't have the @samp{fsf-compat} package installed, which IDLWAVE | |
4132 needs to run under XEmacs. Install it, or find an XEmacs distribution | |
4133 which includes it by default. | |
4134 | |
4135 @item @strong{I'm getting errors like @samp{Symbol's value as variable is void: | |
4136 cl-builtin-gethash} on completion or routine info.} | |
4137 | |
4138 This error arises if you upgraded Emacs from 20.x to 21.x without | |
4139 re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible | |
4140 in compiled lisp files. Presumably, you kept the original .elc files in | |
4141 place, and this is the source of the error. If you recompile (or just | |
4142 "make; make install") from source, it should resolve this problem. | |
4143 Another option is to recompile the @file{idlw*.el} files by hand using | |
4144 @kbd{M-x byte-compile-file}. | |
4145 | |
4146 @item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches | |
4147 windows on my desktop.} | |
4148 | |
4149 Your system is trapping @kbd{M-@key{TAB}} and using it for its own | |
4150 nefarious purposes: Emacs never sees the keystrokes. On many Unix | |
4151 systems, you can reconfigure your window manager to use another key | |
4152 sequence for switching among windows. Another option is to use the | |
4153 equivalent sequence @kbd{@key{ESC}-@key{TAB}}. | |
4154 | |
4155 @item @strong{When stopping at breakpoints or errors, IDLWAVE does not | |
4156 seem to highlight the relevant line in the source.} | |
4157 | |
4158 IDLWAVE scans for error and halt messages and highlights the stop | |
4159 location in the correct file. However, if you've changed the system | |
4160 variable @samp{!ERROR_STATE.MSG_PREFIX}, it is unable to parse these | |
4161 message correctly. Don't do that. | |
4162 | |
4163 @item @strong{IDLWAVE doesn't work correctly when using ENVI.} | |
4164 | |
4165 Though IDLWAVE was not written with ENVI in mind, it works just fine | |
4166 with it, as long as you update the prompt it's looking for (@samp{IDL> | |
4167 } by default). You can do this with the variable | |
4168 @code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g., | |
4169 in your @file{.emacs}: | |
4170 | |
4171 @lisp | |
4172 (setq idlwave-shell-prompt-pattern "^\r? ?\\(ENVI\\|IDL\\)> ") | |
4173 @end lisp | |
4174 | |
4175 @item @strong{Attempts to set breakpoints fail: no breakpoint is | |
4176 indicated in the IDLWAVE buffer.} | |
4177 | |
4178 IDL changed its breakpoint reporting format starting with IDLv5.5. The | |
4179 first version of IDLWAVE to support the new format is IDLWAVE v4.10. If | |
4180 you have an older version and are using IDL >v5.5, you need to upgrade, | |
4181 and/or make sure your recent version of IDLWAVE is being found on the | |
4182 Emacs load-path (see the next entry). You can list the version being | |
4183 used with @kbd{C-h v idlwave-mode-version @key{RET}}. | |
4184 | |
4185 @item @strong{I installed a new version of IDLWAVE, but the old | |
4186 version is still being used} or @strong{IDLWAVE works, but when I | |
4187 tried to install the optional modules @file{idlw-roprompt.el} or | |
4188 @file{idlw-complete-structtag}, I get errors like @samp{Cannot open | |
4189 load file}}. | |
4190 | |
4191 The problem is that your Emacs is not finding the version of IDLWAVE you | |
4192 installed. Many Emacsen come with an older bundled copy of IDLWAVE | |
4193 (e.g. v4.7 for Emacs 21.x), which is likely what's being used instead. | |
4194 You need to make sure your Emacs @emph{load-path} contains the directory | |
4195 where IDLWAVE is installed (@file{/usr/local/share/emacs/site-lisp}, by | |
4196 default), @emph{before} Emacs' default search directories. You can | |
4197 accomplish this by putting the following in your @file{.emacs}: | |
4198 | |
4199 @lisp | |
4200 (setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path)) | |
4201 @end lisp | |
4202 | |
4203 @noindent You can check on your load-path value using @kbd{C-h v | |
4204 load-path @key{RET}}, and @kbd{C-h m} in an IDLWAVE buffer should show | |
4205 you the version Emacs is using. | |
4206 | |
4207 @item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.} | |
4208 | |
4209 Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated | |
4210 programming mode for CORBA's Interface Definition Language (you should | |
4211 see @samp{(IDL)}, not @samp{(IDLWAVE)} in the mode-line). One | |
4212 solution: don't name your file @file{.idl}, but rather @file{.pro}. | |
4213 Another solution: make sure @file{.idl} files load IDLWAVE instead of | |
4214 @samp{idl-mode} by adding the following to your @file{.emacs}: | |
4215 | |
4216 @lisp | |
4217 (setcdr (rassoc 'idl-mode auto-mode-alist) 'idlwave-mode) | |
4218 @end lisp | |
4219 | |
4220 @item @strong{The routine info for my local routines is out of date!} | |
4221 | |
4222 IDLWAVE collects routine info from various locations (@pxref{Routine | |
4223 Information Sources}). Routines in files visited in a buffer or | |
4224 compiled in the shell should be up to date. For other routines, the | |
4225 information is only as current as the most recent scan. If you have a | |
4226 rapidly changing set of routines, and you'd like the latest routine | |
4227 information to be available for it, one powerful technique is to make | |
4228 use of the library catalog tool, @samp{idlwave_catalog}. Simply add a | |
4229 line to your @samp{cron} file (@samp{crontab -e} will let you edit this | |
4230 on some systems), like this | |
4231 | |
4232 @example | |
4233 45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib) | |
4234 @end example | |
4235 | |
4236 @noindent where @samp{MyLib} is the name of your library. This will | |
4237 rescan all @file{.pro} files at or below @file{/path/to/myidllib} every | |
4238 week night at 3:45am. You can even scan site-wide libraries with this | |
4239 method, and the most recent information will be available to all users. | |
4240 Since the scanning is very fast, there is very little impact. | |
4241 | |
4242 @item @strong{All the Greek-font characters in the HTML help are | |
4243 displayed as Latin characters!} | |
4244 | |
4245 Unfortunately, the HTMLHelp files RSI provides attempt to switch to | |
4246 @samp{Symbol} font to display Greek characters, which is not really an | |
4247 permitted method for doing this in HTML. There is a "workaround" for | |
4248 some browsers: @xref{HTML Help Browser Tips}. | |
4249 | |
4250 @item @strong{In the shell, my long commands are truncated at 256 characters!} | |
4251 | |
4252 This actually happens when running IDL in an XTerm as well. There are | |
4253 a couple of workarounds: @code{define_key,/control,'^d'} (e.g. in | |
4254 your @file{$IDL_STARTUP} file) will disable the @samp{EOF} character | |
4255 and give you a 512 character limit. You won't be able to use | |
4256 @key{C-d} to quit the shell, however. Another possibility is | |
4257 @code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a | |
4258 memory-bounded limit), but disables the processing of background | |
4259 widget events (those with @code{/NO_BLOCK} passed to @code{XManager}). | |
4260 | |
4261 @item @strong{When I invoke IDL HTML help on a routine, the page which | |
4262 is loaded is one page off, e.g. for @code{CONVERT_COORD}, I get | |
4263 @code{CONTOUR}.} | |
4264 | |
4265 You have a mismatch between your help index and the HTML help package | |
4266 you downloaded. You need to ensure you download a ``downgrade kit'' if | |
4267 you are using anything older than the latest HTML help package. A new | |
4268 help package appears with each IDL release (assuming the documentation | |
4269 is updated). | |
4270 Starting with IDL 6.2, the HTML help and its catalog are | |
4271 distributed with IDL, and so should never be inconsistent. | |
4272 | |
4273 @item @strong{I get errors such as @samp{void-variable | |
4274 browse-url-browser-function} or similar when attempting to load IDLWAVE | |
4275 under XEmacs.} | |
4276 | |
4277 You don't have the @samp{browse-url} (or other required) XEmacs package. | |
4278 Unlike GNU Emacs, XEmacs distributes many packages separately from the | |
4279 main program. IDLWAVE is actually among these, but is not always the | |
4280 most up to date. When installing IDLWAVE as an XEmacs package, it | |
4281 should prompt you for required additional packages. When installing it | |
4282 from source, it won't and you'll get this error. The easiest solution | |
4283 is to install all the packages when you install XEmacs (the so-called | |
4284 @samp{sumo} bundle). The minimum set of XEmacs packages required by | |
4285 IDLWAVE is @samp{fsf-compat, xemacs-base, mail-lib}. | |
4286 | |
4287 @end enumerate | |
4288 | |
4289 @node GNU Free Documentation License, Index, Troubleshooting, Top | |
4290 @appendix GNU Free Documentation License | |
4291 @include doclicense.texi | |
4292 | |
4293 @node Index, , GNU Free Documentation License, Top | |
4294 @unnumbered Index | |
4295 @printindex cp | |
4296 | |
4297 @bye | |
4298 | |
4299 @ignore | |
4300 arch-tag: f1d73958-1423-4127-b8aa-f7b953d64492 | |
4301 @end ignore |