Commit | Line | Data |
---|---|---|
797c8ebc CD |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
66f236e9 | 3 | @setfilename ../info/idlwave |
797c8ebc | 4 | @settitle IDLWAVE User Manual |
66f236e9 | 5 | @dircategory Emacs |
797c8ebc CD |
6 | @direntry |
7 | * IDLWAVE: (idlwave). Major mode and shell for IDL and WAVE/CL files. | |
8 | @end direntry | |
9 | @synindex ky cp | |
10 | @syncodeindex vr cp | |
11 | @syncodeindex fn cp | |
aea44e56 CD |
12 | @set VERSION 4.7 |
13 | @set EDITION 4.7 | |
14 | @set IDLVERSION 5.4 | |
15 | @set NSYSROUTINES 1287 | |
16 | @set NSYSKEYWORDS 5724 | |
17 | @set DATE December 2000 | |
797c8ebc CD |
18 | @set AUTHOR Carsten Dominik |
19 | @set AUTHOR-EMAIL dominik@@astro.uva.nl | |
20 | @set MAINTAINER Carsten Dominik | |
21 | @set MAINTAINER-EMAIL dominik@@astro.uva.nl | |
a8e833f3 | 22 | @set IDLWAVE-HOMEPAGE http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave |
797c8ebc CD |
23 | @c %**end of header |
24 | @finalout | |
25 | ||
26 | @ifinfo | |
27 | This file documents IDLWAVE, a major mode for editing IDL and | |
28 | WAVE/CL files with Emacs. It also implements a shell for running IDL as | |
a8e833f3 | 29 | a subprocess. |
797c8ebc CD |
30 | |
31 | This is edition @value{EDITION} of the IDLWAVE User Manual for | |
a8e833f3 | 32 | IDLWAVE @value{VERSION} |
797c8ebc | 33 | |
b409f09b GM |
34 | Copyright (c) 1999, 2000, 2001 Free Software Foundation, Inc. |
35 | ||
36 | Permission is granted to copy, distribute and/or modify this document | |
37 | under the terms of the GNU Free Documentation License, Version 1.1 or | |
38 | any later version published by the Free Software Foundation; with no | |
39 | Invariant Sections, with the Front-Cover texts being ``A GNU | |
40 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
41 | license is included in the section entitled ``GNU Free Documentation | |
42 | License'' in the Emacs manual. | |
43 | ||
44 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify | |
45 | this GNU Manual, like GNU software. Copies published by the Free | |
46 | Software Foundation raise funds for GNU development.'' | |
47 | ||
48 | This document is part of a collection distributed under the GNU Free | |
49 | Documentation License. If you want to distribute this document | |
50 | separately from the collection, you can do so by adding a copy of the | |
51 | license to the document, as described in section 6 of the license. | |
797c8ebc CD |
52 | @end ifinfo |
53 | ||
54 | @titlepage | |
55 | @title IDLWAVE User Manual | |
56 | @subtitle Major Emacs mode and shell for IDL and WAVE/CL files | |
57 | @subtitle Edition @value{EDITION}, @value{DATE} | |
58 | ||
59 | @author by Carsten Dominik | |
60 | @page | |
797c8ebc | 61 | This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for |
a8e833f3 | 62 | IDLWAVE version @value{VERSION}, @value{DATE}. |
797c8ebc | 63 | @sp 2 |
b409f09b GM |
64 | Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc. |
65 | @sp 2 | |
a8e833f3 | 66 | @cindex Copyright, of IDLWAVE |
797c8ebc | 67 | |
b409f09b GM |
68 | Permission is granted to copy, distribute and/or modify this document |
69 | under the terms of the GNU Free Documentation License, Version 1.1 or | |
70 | any later version published by the Free Software Foundation; with no | |
71 | Invariant Sections, with the Front-Cover texts being ``A GNU | |
72 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
73 | license is included in the section entitled ``GNU Free Documentation | |
74 | License'' in the Emacs manual. | |
75 | ||
76 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify | |
77 | this GNU Manual, like GNU software. Copies published by the Free | |
78 | Software Foundation raise funds for GNU development.'' | |
79 | ||
80 | This document is part of a collection distributed under the GNU Free | |
81 | Documentation License. If you want to distribute this document | |
82 | separately from the collection, you can do so by adding a copy of the | |
83 | license to the document, as described in section 6 of the license. | |
797c8ebc | 84 | @end titlepage |
a8e833f3 CD |
85 | @contents |
86 | ||
797c8ebc CD |
87 | @page |
88 | ||
a8e833f3 CD |
89 | @ifnottex |
90 | ||
797c8ebc CD |
91 | @node Top, Introduction, (dir), (dir) |
92 | ||
93 | IDLWAVE is a package to support editing command files for the | |
94 | Interactive Data Language (IDL), and for running IDL as an inferior | |
a8e833f3 | 95 | shell. |
797c8ebc | 96 | |
a8e833f3 | 97 | @end ifnottex |
797c8ebc CD |
98 | |
99 | @menu | |
100 | * Introduction:: What IDLWAVE is and what not | |
101 | * IDLWAVE in a Nutshell:: One page quick-start guide | |
aea44e56 | 102 | * Getting Started:: Tutorial |
797c8ebc CD |
103 | * The IDLWAVE Major Mode:: The mode to edit IDL programs |
104 | * The IDLWAVE Shell:: The mode to run IDL as inferior program | |
105 | * Installation:: How to Install or Upgrade | |
106 | * Acknowledgement:: Who helped | |
107 | * Sources of Routine Info:: How does IDLWAVE know about routine XYZ | |
108 | * Configuration Examples:: The user is king... | |
109 | * Index:: Fast access | |
110 | ||
a8e833f3 | 111 | @detailmenu --- The Detailed Node Listing --- |
797c8ebc CD |
112 | |
113 | The IDLWAVE Major Mode | |
114 | ||
115 | * Code Formatting:: Making code look nice | |
a8e833f3 CD |
116 | * Routine Info:: Calling Sequence and Keyword List |
117 | * Online Help:: One key press from source to help | |
797c8ebc | 118 | * Completion:: Completing routine names and Keywords |
a8e833f3 CD |
119 | * Routine Source:: How to visit the source file of routine XYZ |
120 | * Resolving Routines:: Force the Shell to compile a routine | |
797c8ebc CD |
121 | * Code Templates:: Abbreviations for frequent constructs |
122 | * Actions:: Changing case, Padding, End checking | |
123 | * Doc Header:: Inserting a standard header | |
124 | * Motion Commands:: Moving through the structure of a program | |
125 | * Misc Options:: Things that fit nowhere else | |
126 | ||
127 | Code Formatting | |
128 | ||
129 | * Code Indentation:: Reflecting the logical structure | |
130 | * Comment Indentation:: Special indentation for comment lines | |
131 | * Continuation Lines:: Splitting statements over lines | |
132 | * Syntax Highlighting:: Font-lock support | |
133 | ||
134 | Actions | |
135 | ||
136 | * Block Boundary Check:: Is the END correct | |
137 | * Padding Operators:: Enforcing space around `=' etc | |
138 | * Case Changes:: Enforcing upper case keywords | |
139 | ||
140 | The IDLWAVE Shell | |
141 | ||
142 | * Starting the Shell:: How to launch IDL as a subprocess | |
143 | * Using the Shell:: Interactively working with the Shell | |
144 | * Debugging IDL Programs:: Compilation/Debugging | |
145 | ||
146 | Debugging IDL Programs | |
147 | ||
148 | * Compiling Programs:: Compiling buffers under the shell | |
149 | * Breakpoints and Stepping:: Deciding where to stop and look | |
150 | * Examining Variables:: What is the value now? | |
151 | ||
152 | Installation | |
153 | ||
154 | * Installing IDLWAVE:: How to install the distribution | |
a8e833f3 | 155 | * Installing Online Help:: Where to get the additional files needed |
797c8ebc CD |
156 | * Upgrading from idl.el:: Necessary configuration changes |
157 | ||
158 | Sources of Routine Info | |
159 | ||
160 | * Routine Definitions:: Where IDL Routines are defined. | |
a8e833f3 | 161 | * Routine Information Sources:: So how does IDLWAVE know about... |
aea44e56 | 162 | * Library Catalog:: Scanning the Libraries for Routine Info |
a8e833f3 CD |
163 | * Load-Path Shadows:: Routines defined in several places |
164 | * Documentation Scan:: Scanning the IDL Manuals | |
165 | ||
797c8ebc CD |
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) | |
a8e833f3 CD |
173 | @cindex Interface Definition Language |
174 | @cindex Interactive Data Language | |
797c8ebc | 175 | @cindex cc-mode.el |
a8e833f3 CD |
176 | @cindex @file{idl.el} |
177 | @cindex @file{idl-shell.el} | |
797c8ebc CD |
178 | @cindex Feature overview |
179 | ||
180 | IDLWAVE is a package to support editing command files for the | |
181 | Interactive Data Language (IDL), and for running IDL as an inferior | |
182 | shell. It also can be used for WAVE/CL command files, but the support | |
183 | for these is limited. Note that this package has nothing to do with the | |
184 | Interface Definition Language as part of the Common Object Request | |
185 | Broker Architecture (CORBA). | |
186 | ||
187 | IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el} | |
188 | files written by Chris Chase. The modes and files had to be renamed | |
189 | because of a name space conflict with CORBAs @code{idl-mode}, defined in | |
190 | Emacs in the file @file{cc-mode.el}. If you have been using the old | |
191 | files, check @ref{Upgrading from idl.el} for information on how to | |
192 | switch. | |
193 | ||
194 | IDLWAVE consists of two parts: A major mode for editing command files | |
195 | (@code{idlwave-mode}) and a mode to allow running the IDL program as an | |
196 | inferior shell (@code{idlwave-shell-mode}). Both modes work closely | |
a8e833f3 | 197 | together and form a complete development environment. |
797c8ebc CD |
198 | |
199 | Here is a brief summary of what IDLWAVE does. | |
200 | ||
201 | @itemize @bullet | |
202 | @item | |
203 | Code indentation and formatting. | |
204 | @item | |
205 | Font-lock support on three levels. | |
206 | @item | |
207 | Display of calling sequence and keywords of more than 1000 IDL | |
c23bc7a4 | 208 | routines and any routines in your local IDL library. |
a8e833f3 CD |
209 | @item |
210 | Name space conflict search. | |
211 | @item | |
212 | Fast context-sensitive online help. | |
797c8ebc CD |
213 | @item |
214 | Context sensitive completion of routine names and keywords. | |
215 | @item | |
216 | Insertion of code templates. | |
217 | @item | |
218 | Actions to enforce coding standards during typing. | |
219 | @item | |
220 | Block structure check. | |
221 | @item | |
a8e833f3 CD |
222 | Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). |
223 | @item | |
797c8ebc CD |
224 | Documentation support. |
225 | @item | |
226 | Running IDL as inferior process. | |
227 | @item | |
228 | Shell with history search, command line editing and completion. | |
229 | @item | |
230 | Compilation, execution and debugging of programs directly from the source | |
231 | buffer. | |
232 | @item | |
233 | Examining expressions with a mouse click. | |
234 | @end itemize | |
235 | ||
236 | @ifnottex | |
237 | @cindex Screenshots | |
238 | Here are a number of screenshots showing IDLWAVE in action. | |
a8e833f3 | 239 | |
797c8ebc CD |
240 | @itemize @bullet |
241 | @item | |
242 | @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/font-lock.gif, | |
243 | XEmacs 21.1 with formatted and fontified code} | |
244 | @item | |
245 | @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/rinfo.gif, | |
246 | XEmacs 21.1 displaying routine info} | |
247 | @item | |
248 | @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/complete.gif, | |
249 | XEmacs 21.1 completing a keyword} | |
250 | @item | |
251 | @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/shell.gif, | |
252 | XEmacs 21.1 with debugging toolbar; execution stopped at a breakpoint} | |
253 | @end itemize | |
254 | @end ifnottex | |
255 | ||
256 | In this manual, each section contains a list of user options related to | |
257 | the subject. Don't be confused by the shear number of options available | |
258 | -- in most cases the default settings are just fine. The variables are | |
259 | listed here to make sure you know where to look if you want to change | |
260 | things. For a full description of what a particular variable does and | |
261 | how to configure it, see the documentation string of that variable. | |
262 | Some configuration examples are also given in the appendix. | |
263 | ||
aea44e56 | 264 | @node IDLWAVE in a Nutshell, Getting Started, Introduction, Top |
797c8ebc | 265 | @chapter IDLWAVE in a Nutshell |
a8e833f3 | 266 | @cindex Summary of important commands |
797c8ebc CD |
267 | @cindex IDLWAVE in a Nutshell |
268 | @cindex Nutshell, IDLWAVE in a | |
269 | ||
797c8ebc CD |
270 | @subheading Editing IDL Programs |
271 | ||
272 | @multitable @columnfractions .15 .85 | |
273 | @item @key{TAB} | |
274 | @tab Indent the current line relative to context. | |
275 | @item @kbd{M-C-\} | |
276 | @tab Re-indent all lines in the current region. | |
277 | @item @kbd{M-@key{RET}} | |
278 | @tab Start a continuation line. Or split the current line at point. | |
279 | @item @kbd{M-q} | |
280 | @tab Fill the current comment paragraph. | |
281 | @item @kbd{C-c ?} | |
282 | @tab Display calling sequence, keywords of the procedure/function call | |
283 | at point. | |
a8e833f3 CD |
284 | @item @kbd{M-?} |
285 | @tab Context sensitive online help. | |
797c8ebc CD |
286 | @item @kbd{M-@key{TAB}} |
287 | @tab Complete a procedure name, function name or keyword in the buffer. | |
288 | @item @kbd{C-c C-i} | |
289 | @tab Update IDLWAVE's knowledge about functions and procedures. | |
290 | @item @kbd{C-c C-v} | |
291 | @tab Find the source code of a procedure/function. | |
292 | @item @kbd{C-c C-h} | |
293 | @tab Insert a standard documentation header. | |
294 | @item @kbd{C-c C-m} | |
295 | @tab Insert a new timestamp and history item in the documentation header. | |
296 | @end multitable | |
297 | ||
298 | @subheading Running the IDLWAVE Shell, Debugging Programs | |
299 | ||
300 | @multitable @columnfractions .15 .85 | |
301 | @item @kbd{C-c C-s} | |
302 | @tab Start IDL as a subprocess and/or switch to the interaction buffer. | |
797c8ebc CD |
303 | @item @kbd{M-p} |
304 | @tab Cycle back through IDL command history matching command line input. | |
305 | @item @kbd{M-n} | |
306 | @tab Cycle forward. | |
307 | @item @kbd{M-@key{TAB}} | |
308 | @tab Complete a procedure name, function name or keyword in the shell buffer. | |
309 | @item @kbd{C-c C-d C-c} | |
310 | @tab Save and compile the source file in the current buffer. | |
311 | @item @kbd{C-c C-d C-x} | |
312 | @tab Goto next syntax error. | |
313 | @item @kbd{C-c C-d C-b} | |
314 | @tab Set a breakpoint at the current source line. | |
315 | @item @kbd{C-c C-d C-d} | |
316 | @tab Clear the current breakpoint. | |
317 | @item @kbd{C-c C-d C-p} | |
318 | @tab Ask IDL to print the value of the expression near point. | |
319 | @end multitable | |
320 | ||
321 | @subheading Commonly used Settings in @file{.emacs} | |
322 | @lisp | |
323 | ;; Change the indentation preferences | |
324 | (setq idlwave-main-block-indent 2 ; default 0 | |
325 | idlwave-block-indent 2 ; default 4 | |
326 | idlwave-end-offset -2) ; default -4 | |
ea442c62 CD |
327 | ;; Pad some operators with spaces |
328 | (setq idlwave-do-actions t | |
329 | idlwave-surround-by-blank t) | |
ea442c62 CD |
330 | ;; Syntax Highlighting |
331 | (add-hook 'idlwave-mode-hook 'turn-on-font-lock) | |
aea44e56 CD |
332 | ;; Automatically start the shell when needed |
333 | (setq idlwave-shell-automatic-start t) | |
334 | ;; Bind debugging commands with CONTROL and SHIFT modifiers | |
335 | (setq idlwave-shell-debug-modifiers '(control shift)) | |
a8e833f3 CD |
336 | ;; Where are the online help files? |
337 | (setq idlwave-help-directory "~/.idlwave") | |
797c8ebc CD |
338 | @end lisp |
339 | ||
aea44e56 CD |
340 | @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top |
341 | @chapter Getting Started (Tutorial) | |
342 | @cindex Quick-Start | |
343 | @cindex Tutorial | |
344 | @cindex Getting Started | |
345 | ||
346 | @section Lession I: Development Cycle | |
347 | ||
348 | The purpose of this tutorial is to guide you through a very basic | |
349 | development cycle with IDLWAVE. We will type a simple program into a | |
350 | buffer and use the shell to compile, debug and run this program. On the | |
351 | way we will use the most important commands in IDLWAVE. Note | |
352 | however that there is much more funtionality available in IDLWAVE than | |
353 | we cover here, and it will pay off greatly if eventually you go further | |
354 | and read the whole manual. | |
355 | ||
356 | I assume that you have access to Emacs or XEmacs with the full IDLWAVE | |
357 | package including online help (@pxref{Installation}). I also assume | |
358 | that you are familiar with Emacs and can read the nomenclature of key | |
359 | presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL} and | |
360 | @kbd{M} for @key{META} (often the @key{ALT} key carries this | |
361 | functionality)). | |
362 | ||
363 | Open a new source file by typing | |
364 | ||
365 | @example | |
366 | @kbd{C-x C-f tutorial.pro @key{RET}} | |
367 | @end example | |
368 | ||
369 | A buffer for this file will pop up, and it should be in IDLWAVE mode. | |
370 | You can see this by looking at the mode line, just below the editing | |
371 | window. Also, the menu bar should contain entries @samp{IDLWAVE} and | |
372 | @samp{Debug}. | |
373 | ||
374 | Now cut-and-paste the following program, also available as | |
375 | @file{tutorial.pro} in the IDLWAVE distribution. | |
376 | ||
377 | @example | |
378 | function daynr,d,m,y | |
379 | ;; compute a sequence number for a date | |
380 | ;; works 1901-2099. | |
381 | if y lt 100 then y = y+1900 | |
382 | if m le 2 then delta = 1 else delta = 0 | |
383 | m1 = m + delta*12 + 1 | |
384 | y1 = y * delta | |
385 | return, d + floor(m1*30.6)+floor(y1*365.25)+5 | |
386 | end | |
387 | ||
388 | function weekday,day,month,year | |
389 | ;; compute weekday number for date | |
390 | nr = daynr(day,month,year) | |
391 | return, nr mod 7 | |
392 | end | |
393 | ||
394 | pro plot_wday,day,month | |
395 | ;; Plot the weekday of a date in the first 10 years of this century. | |
396 | years = 2000,+indgen(10) | |
397 | wdays = intarr(10) | |
398 | for i=0,n_elements(wdays)-1 do begin | |
399 | wdays[i] = weekday(day,month,years[i]) | |
400 | end | |
401 | plot,years,wdays,YS=2,YT="Wday (0=sunday)" | |
402 | end | |
403 | @end example | |
404 | ||
405 | The indentation probably looks funny, since it's different from the | |
406 | settings you use, so use the @key{TAB} key in each line to automatically | |
407 | line it up (or more quickly @emph{select} the entire buffer with | |
408 | @kbd{C-x h} followed by @kbd{M-C-\}). Notice how different syntactical | |
409 | elements are highlighted in different colors, if you have set up support | |
410 | for font-lock. | |
411 | ||
412 | Let's check out two particular editing features of IDLWAVE. Place the | |
413 | cursor after the @code{end} statement of the @code{for} loop and press | |
414 | @key{SPC}. IDLWAVE blinks back to the beginning of the block and | |
415 | changes the generic @code{end} to the specific @code{endfor} | |
416 | automatically. Now place the cursor in any line you would like to split | |
417 | into two and press @kbd{M-@key{RET}}. The line is split at the cursor | |
418 | position, with the continuation @samp{$} and indentation all taken care | |
419 | of. Use @kbd{C-/} to undo the last change. | |
420 | ||
421 | The procedure @code{plot_wday} is supposed to plot the weekday of a given | |
422 | date for the first 10 years of the 21st century. I have put in a few | |
423 | bugs which we are going to fix now. | |
424 | ||
425 | First, let's launch the IDLWAVE shell. You do this with the command | |
426 | @kbd{C-c C-s}. The Emacs window will split and display IDL running in a | |
427 | shell interaction buffer. Type a few commands like @code{print,!PI} to | |
428 | convince yourself that you can work there like in an xterminal, or the | |
429 | IDLDE. Use the arrow keys to cycle through your command history. Are | |
430 | we having fun now? | |
431 | ||
432 | Now go back to the source window and type @kbd{C-c C-d C-c} to compile | |
433 | the program. If you watch the shell buffer, you see that IDLWAVE types | |
434 | @samp{.run tutorial.pro} for you. But the compilation fails because | |
435 | there is a comma in the line @samp{years=...}. The line with the error | |
436 | is highlighted and the cursor positioned at the error, so remove the | |
437 | comma (you should only need to hit Delete!). Compile again, using the | |
438 | same keystrokes as before. Notice that the file is saved for you. This | |
439 | time everything should work fine, and you should see the three routines | |
440 | compile. | |
441 | ||
442 | Now we want to use the command to plot the weekdays for January 1st. We | |
443 | could type the full command ourselves, but why do that? Go back to the | |
444 | shell window, type @samp{plot_} and hit @key{TAB}. After a bit of a | |
445 | delay (while IDLWAVE initializes its routine info database), the window | |
446 | will split to show all procedures it knows starting with that string, | |
447 | and @w{@code{plot_wday}} should be one of them. Saving the buffer was | |
448 | enough to tell IDLWAVE about this new routine. Click with the middle | |
449 | mouse button on @code{plot_wday} and it will be copied to the shell | |
450 | buffer, or if you prefer, add @samp{w} to @samp{plot_} to make it | |
451 | unambiguous, hit @key{TAB}, and the full routine name will be completed. | |
452 | Now provide the two arguments: | |
453 | ||
454 | @example | |
455 | plot_wday,1,1 | |
456 | @end example | |
457 | ||
458 | ||
459 | and press @key{RET}. This fails with an error message telling you the | |
460 | @code{YT} keyword to plot is ambiguous. What are the allowed keywords | |
461 | again? Go back to the source window and put the cursor into the `plot' | |
462 | line, and press @kbd{C-c ?}. This pops up the routine info window for | |
463 | the plot routine, which contains a list of keywords, and the argument | |
464 | list. Oh, we wanted @code{YTITLE}. Fix that up. Recompile with | |
465 | @kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press | |
466 | the @key{UP} arrow to recall the previous command and execute again. | |
467 | ||
468 | This time we get a plot, but it is pretty ugly -- the points are all | |
469 | connected with a line. Hmm, isn't there a way for @code{plot} to use | |
470 | symbols instead? What was that keyword? Position the cursor on the | |
471 | plot line after a comma (where you'd normally type a keyword), and hit | |
472 | @kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, there | |
473 | it is, @code{PSYM}. Middle click to insert it. An @samp{=} sign is | |
474 | included for you too. Now what were the values of @code{PSYM} supposed | |
475 | to be? With the cursor on or after the keyword, press @kbd{M-?} for | |
476 | online help (alternatively, you could have right clicked on the colored | |
477 | keyword itself in the completion list). The online help window will pop | |
478 | up showing the documentation for the @code{PYSM} keyword. Ok, let's use | |
479 | diamonds=4. Fix this, recompile (you know the command by now: @kbd{C-c | |
480 | C-d C-c}, go back to the shell (if it's vanished, you know the command | |
481 | to recall it by now: @kbd{C-c C-s}) and execute again. Now things look | |
482 | pretty good. | |
483 | ||
484 | Lets try a different day - how about April fool's day? | |
485 | ||
486 | @example | |
487 | plot_wday,1,4 | |
488 | @end example | |
489 | ||
490 | Oops, this looks very wrong. All April fool's days cannot be | |
491 | Fridays! We've got a bug in the program, perhaps in the @code{daynr} | |
492 | function. Lets put a breakpoint on the last line there. Position the | |
493 | cursor on the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. | |
494 | IDL sets a breakpoint (as you see in the shell window), and the line is | |
495 | highlighted in some way. Back to the shell buffer, re-execute the | |
496 | previous command. IDL stops at the line with the breakpoint. Now hold | |
497 | down the SHIFT key and click with the middle mouse button on a few | |
498 | variables there: @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe | |
499 | @code{d} isn't the correct type. CONTROL-SHIFT middle-click on it for | |
500 | help. Well, it's an integer, so that's not the problem. Aha, @samp{y1} | |
501 | is zero, but it should be the year, depending on delta. Shift click | |
502 | @samp{delta} to see that it's 0. Below, we see the offending line: | |
503 | @samp{y1=y*delta...} the multiplication should have been a minus sign! | |
504 | So fix the line to | |
505 | ||
506 | @example | |
507 | y1 = y - delta | |
508 | @end example | |
509 | ||
510 | Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the | |
511 | command. Everything should now work fine. How about those leap years? | |
512 | Change the code to plot 100 years and see that every 28 years, the | |
513 | sequence of weekdays repeats. | |
514 | ||
515 | @section Lession II: Customization | |
516 | ||
517 | Emacs is probably the most customizable piece of software available, and | |
518 | it would be a shame if you did not make use of this and adapt IDLWAVE to | |
519 | your own preferences. Customizing Emacs or IDLWAVE means that you have | |
520 | to set Lisp variables in the @file{.emacs} file in your home directory. | |
521 | This looks scary to many people because of all the parenthesis. | |
522 | However, you can just cut and paste the examples given here and work | |
523 | from there. | |
524 | ||
525 | Lets first use a boolean variable. These are variables which you turn | |
526 | on or off, much like a checkbox. A value of @samp{t} means on, a | |
527 | value of @samp{nil} means off. Copy the following line into your | |
528 | @file{.emacs} file, exit and restart Emacs. | |
529 | ||
530 | @lisp | |
531 | (setq idlwave-reserved-word-upcase t) | |
532 | @end lisp | |
533 | ||
534 | When this option is turned on, each reserved word you type into an IDL | |
535 | source buffer will be converted to upper case when you press @key{SPC} | |
536 | or @key{RET} right after the word. Try it out! @samp{if} changes to | |
537 | @samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this | |
538 | behavior, remove the option again from your @file{.emacs} file. | |
539 | ||
540 | Now I bet you have your own indentation preferences for IDL code. For | |
541 | example, I like to indent the main block of an IDL program a bit, | |
542 | different from the conventions used by RSI. Also, I'd like to use only | |
543 | 3 spaces as indentation between @code{BEGIN} and @code{END}. Try the | |
544 | following lines in @file{.emacs} | |
545 | ||
546 | @lisp | |
547 | (setq idlwave-main-block-indent 2) | |
548 | (setq idlwave-block-indent 3) | |
549 | (setq idlwave-end-offset -3) | |
550 | @end lisp | |
551 | ||
552 | Restart Emacs, take the program we developed in the first part of this | |
553 | tutorial and re-indent it with @kbd{C-c h} and @kbd{M-C-\}. You | |
554 | probably want to keep these lines in @file{.emacs}, with values adjusted | |
555 | to your likings. If you want to get more information about any of these | |
556 | variables, type, e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. | |
557 | To find which variables can be customized, look for items marked | |
558 | @samp{User Option:} in the manual. | |
559 | ||
560 | If you cannot wrap your head around this Lisp stuff, there is another, | |
561 | more user-friendly way to customize all the IDLWAVE variables. You can | |
562 | access it through the IDLWAVE menu in one of the @file{.pro} buffers, | |
563 | option @code{Customize->Browse IDLWAVE Group}. Here you'll be presented | |
564 | with all the various variables grouped into categories. You can | |
565 | navigate the hierarchy (e.g. Idlwave Code Formatting->Idlwave Main Block | |
566 | Indent), read about the variables, change them, and `Save for Future | |
567 | Sessions'. Few of these variables need customization, but you can | |
568 | exercise considerable control over IDLWAVE's functionality with them. | |
569 | ||
570 | Many people I talk to find the key bindings used for the debugging | |
571 | commands too long and complicated. Do I always have to type @kbd{C-c | |
572 | C-d C-c} to get a single simple command? Due to Emacs rules and | |
573 | conventions I cannot make better bindings by default, but you can. | |
574 | First, there is a way to assign all debugging commands in a single sweep | |
575 | to other combinations. The only problem is that we have to use | |
576 | something which Emacs does not need for other important commands. A | |
577 | good option is to execute debugging commands by holding down | |
578 | @key{CONTROL} and @key{SHIFT} while pressing a single character: | |
579 | @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for compiling the | |
580 | current source file, @kbd{C-S-a} for deleting all breakpoints. You can | |
581 | have this with | |
582 | ||
583 | @lisp | |
584 | (setq idlwave-shell-debug-modifiers '(shift control)) | |
585 | @end lisp | |
586 | ||
587 | If you have a special keyboard with for example a @key{HYPER} key, you | |
588 | could use | |
589 | ||
590 | @lisp | |
591 | (setq idlwave-shell-debug-modifiers '(hyper)) | |
592 | @end lisp | |
593 | ||
594 | instead to get compilation on @kbd{H-c}. | |
595 | ||
596 | You can also assign specific commands to function keys. This you must | |
597 | do in the @emph{mode-hook}, a special function which is run when a new | |
598 | buffer gets set up. Keybindings can only be done when the buffer | |
599 | exists. The possibilities for key customization are endless. Here we | |
600 | set function keys f5-f8 to common debugging commands. | |
601 | ||
602 | @lisp | |
603 | ;; First for the source buffer | |
604 | (add-hook 'idlwave-mode-hook | |
605 | (lambda () | |
606 | (local-set-key [f5] 'idlwave-shell-break-here) | |
607 | (local-set-key [f6] 'idlwave-shell-clear-current-bp) | |
608 | (local-set-key [f7] 'idlwave-shell-cont) | |
609 | (local-set-key [f8] 'idlwave-shell-clear-all-bp))) | |
610 | ;; Then for the shell buffer | |
611 | (add-hook 'idlwave-shell-mode-hook | |
612 | (lambda () | |
613 | (local-set-key [f5] 'idlwave-shell-break-here) | |
614 | (local-set-key [f6] 'idlwave-shell-clear-current-bp) | |
615 | (local-set-key [f7] 'idlwave-shell-cont) | |
616 | (local-set-key [f8] 'idlwave-shell-clear-all-bp))) | |
617 | @end lisp | |
618 | ||
619 | @section Lession III: Library Catalog | |
620 | ||
621 | We have already used the routine info display in the first part of this | |
622 | tutorial. This was the key @kbd{C-c ?} which displays information about | |
623 | the IDL routine near the cursor position. Wouldn't it be nice | |
624 | to have the same available for your own library routines and for the | |
625 | huge amount of code in major extension libraries like JHUPL or the | |
626 | IDL-Astro library? To do this, you must give IDLWAVE a chance to study | |
627 | these routines first. We call this @emph{Building the library catalog}. | |
628 | ||
629 | From the IDLWAVE entry in the menu bar, select @code{Routine Info/Select | |
630 | Catalog Directories}. If necessary, start the shell first with @kbd{C-c | |
631 | C-s} (@pxref{Starting the Shell}). IDLWAVE will find out about the IDL | |
632 | @code{!PATH} variable and offer a list of directories on the path. | |
633 | Simply select them all (or whichever you want) and click on the | |
634 | @samp{Scan&Save} button. Then go for a cup of coffee while IDLWAVE | |
635 | collects information for each and every IDL routine on your search path. | |
636 | All this information is written to the file @file{.idlcat} in your home | |
637 | directory and will from now one be automatically loaded whenever you use | |
638 | IDLWAVE. Try to use routine info (@kbd{C-c ?}) or completion | |
639 | (@kbd{M-<TAB>}) while on any routine or partial routine name you know to | |
640 | be located in the library. E.g., if you have scanned the IDL-Astro | |
641 | library: | |
642 | ||
643 | @example | |
644 | a=readf@key{M-<TAB>} | |
645 | @end example | |
646 | ||
647 | ||
648 | expands to `readfits('. Then try | |
649 | ||
650 | @example | |
651 | a=readfits(@key{C-c ?} | |
652 | @end example | |
653 | ||
654 | and you get: | |
655 | ||
656 | @example | |
657 | Usage: Result = READFITS(filename, header, heap) | |
658 | ... | |
659 | @end example | |
660 | ||
661 | I hope you made it until here. Now you are set to work with IDLWAVE. | |
662 | On the way you will want to change other things, and to learn more about | |
663 | the possibilities not discussed in this short tutorial. Read the | |
664 | manual, look at the documentation strings of interesting variables (with | |
665 | @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining | |
666 | questions on @code{comp.lang.idl-pvwave}. | |
667 | ||
668 | @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top | |
797c8ebc CD |
669 | @chapter The IDLWAVE Major Mode |
670 | @cindex IDLWAVE major mode | |
671 | @cindex Major mode, @code{idlwave-mode} | |
672 | ||
673 | The IDLWAVE major mode supports editing IDL and WAVE/CL command files. | |
674 | In this chapter we describe the main features of the mode and how to | |
675 | customize them. | |
676 | ||
677 | @menu | |
678 | * Code Formatting:: Making code look nice | |
a8e833f3 CD |
679 | * Routine Info:: Calling Sequence and Keyword List |
680 | * Online Help:: One key press from source to help | |
797c8ebc | 681 | * Completion:: Completing routine names and Keywords |
a8e833f3 CD |
682 | * Routine Source:: How to visit the source file of routine XYZ |
683 | * Resolving Routines:: Force the Shell to compile a routine | |
797c8ebc CD |
684 | * Code Templates:: Abbreviations for frequent constructs |
685 | * Actions:: Changing case, Padding, End checking | |
686 | * Doc Header:: Inserting a standard header | |
687 | * Motion Commands:: Moving through the structure of a program | |
688 | * Misc Options:: Things that fit nowhere else | |
689 | @end menu | |
690 | ||
691 | @node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode | |
692 | @section Code Formatting | |
693 | @cindex Code formatting | |
694 | @cindex Formatting, of code | |
695 | ||
696 | @menu | |
697 | * Code Indentation:: Reflecting the logical structure | |
698 | * Comment Indentation:: Special indentation for comment lines | |
699 | * Continuation Lines:: Splitting statements over lines | |
700 | * Syntax Highlighting:: Font-lock support | |
701 | @end menu | |
702 | ||
703 | @node Code Indentation, Comment Indentation, Code Formatting, Code Formatting | |
704 | @subsection Code Indentation | |
705 | @cindex Code indentation | |
706 | @cindex Indentation | |
707 | ||
708 | Like all Emacs programming modes, IDLWAVE performs code indentation. | |
709 | The @key{TAB} key indents the current line relative to context. | |
710 | @key{LFD} insert a newline and indents the new line. The indentation is | |
711 | governed by a number of variables. | |
712 | ||
713 | @cindex Foreign code, adapting | |
714 | @cindex Indentation, of foreign code | |
a8e833f3 | 715 | @kindex M-C-\ |
797c8ebc CD |
716 | To re-indent a larger portion of code (e.g. when working with foreign code |
717 | written with different conventions), use @kbd{M-C-\} | |
718 | (@code{indent-region}) after marking the relevant code. Useful marking | |
719 | commands are @kbd{C-x h} (the entire file) or @kbd{M-C-h} (the | |
720 | current subprogram). @xref{Actions}, for information how to impose | |
721 | additional formatting conventions on foreign code. | |
722 | ||
723 | @defopt idlwave-main-block-indent (@code{0}) | |
724 | Extra indentation for the main block of code. That is the block between | |
725 | the FUNCTION/PRO statement and the END statement for that program | |
a8e833f3 | 726 | unit. |
797c8ebc CD |
727 | @end defopt |
728 | ||
a8e833f3 | 729 | @defopt idlwave-block-indent (@code{5}) |
797c8ebc | 730 | Extra indentation applied to block lines. If you change this, you |
a8e833f3 | 731 | probably also want to change @code{idlwave-end-offset}. |
797c8ebc CD |
732 | @end defopt |
733 | ||
734 | @defopt idlwave-end-offset (@code{-4}) | |
735 | Extra indentation applied to block END lines. A value equal to negative | |
736 | @code{idlwave-block-indent} will make END lines line up with the block | |
a8e833f3 | 737 | BEGIN lines. |
797c8ebc CD |
738 | @end defopt |
739 | ||
740 | @defopt idlwave-continuation-indent (@code{2}) | |
a8e833f3 CD |
741 | Extra indentation applied to continuation lines and inside unbalanced |
742 | parenthesis. | |
797c8ebc CD |
743 | @end defopt |
744 | ||
745 | @node Comment Indentation, Continuation Lines, Code Indentation, Code Formatting | |
746 | @subsection Comment Indentation | |
747 | @cindex Comment indentation | |
748 | @cindex Hanging paragraphs | |
749 | @cindex Paragraphs, filling | |
750 | @cindex Paragraphs, hanging | |
751 | ||
752 | In IDL, lines starting with a @samp{;} are called @emph{comment lines}. | |
753 | Comment lines are indented as follows: | |
754 | ||
755 | @multitable @columnfractions .1 .90 | |
756 | @item @code{;;;} | |
757 | @tab The indentation of lines starting with three semicolons remains | |
758 | unchanged. | |
759 | @item @code{;;} | |
760 | @tab Lines starting with two semicolons are indented like the surrounding code. | |
761 | @item @code{;} | |
762 | @tab Lines starting with a single semicolon are indent to a minimum column. | |
763 | @end multitable | |
764 | ||
a8e833f3 | 765 | @noindent |
797c8ebc CD |
766 | The indentation of comments starting in column 0 is never changed. |
767 | ||
768 | @defopt idlwave-no-change-comment | |
a8e833f3 | 769 | The indentation of a comment starting with this regexp will not be changed. |
797c8ebc CD |
770 | @end defopt |
771 | ||
772 | @defopt idlwave-begin-line-comment | |
a8e833f3 | 773 | A comment anchored at the beginning of line. |
797c8ebc CD |
774 | @end defopt |
775 | ||
776 | @defopt idlwave-code-comment | |
a8e833f3 CD |
777 | A comment that starts with this regexp is indented as if it is a part of |
778 | IDL code. | |
797c8ebc CD |
779 | @end defopt |
780 | ||
781 | @node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting | |
782 | @subsection Continuation Lines and Filling | |
783 | @cindex Continuation lines | |
784 | @cindex Line splitting | |
a8e833f3 | 785 | @cindex String splitting |
797c8ebc | 786 | @cindex Splitting, of lines |
797c8ebc | 787 | |
a8e833f3 | 788 | @kindex M-@key{RET} |
797c8ebc CD |
789 | In IDL, a newline character terminates a statement unless preceded by a |
790 | @samp{$}. If you would like to start a continuation line, use | |
791 | @kbd{M-@key{RET}} which calls the command @code{idlwave-split-line}. It | |
792 | inserts a @samp{$} to indicate that the following line is a continuation | |
793 | of the current line, terminates the line with a newline and indents the | |
794 | new line. The command @kbd{M-@key{RET}} can also be used in the middle | |
795 | of a line to split the line at that point. When used inside a long | |
796 | string constant, the string is split with the @samp{+} concatenation | |
a8e833f3 | 797 | operator. |
797c8ebc | 798 | |
a8e833f3 CD |
799 | @cindex Filling |
800 | @cindex @code{auto-fill-mode} | |
801 | @cindex Hanging paragraphs | |
797c8ebc CD |
802 | When filling comment paragraphs, IDLWAVE overloads the normal filling |
803 | functions and uses a function which creates hanging paragraphs as they | |
804 | are customary in the IDL routine headers. When @code{auto-fill-mode} is | |
a8e833f3 CD |
805 | turned on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If |
806 | the first line of a paragraph is matched by | |
807 | @code{idlwave-hang-indent-regexp}, subsequent lines are indented to | |
808 | after the position of this match, as in the following example. | |
797c8ebc CD |
809 | |
810 | @example | |
a8e833f3 | 811 | ; INPUTS: |
797c8ebc CD |
812 | ; x - an array containing |
813 | ; lots of interesting numbers. | |
814 | ; | |
815 | ; y - another variable where | |
816 | ; a hanging paragraph is used | |
817 | ; to describe it. | |
818 | @end example | |
819 | ||
a8e833f3 | 820 | @kindex M-q |
797c8ebc CD |
821 | You also refill a comment paragraph with @kbd{M-q}. |
822 | ||
823 | @defopt idlwave-fill-comment-line-only (@code{t}) | |
824 | Non-@code{nil} means auto fill will only operate on comment lines. | |
825 | @end defopt | |
826 | ||
827 | @defopt idlwave-auto-fill-split-string (@code{t}) | |
828 | Non-@code{nil} means auto fill will split strings with the IDL @samp{+} | |
829 | operator. | |
830 | @end defopt | |
831 | ||
832 | @defopt idlwave-split-line-string (@code{t}) | |
833 | Non-@code{nil} means @code{idlwave-split-line} will split strings with | |
834 | @samp{+}. | |
835 | @end defopt | |
836 | ||
a8e833f3 | 837 | @defopt idlwave-hanging-indent (@code{t}) |
797c8ebc CD |
838 | Non-@code{nil} means comment paragraphs are indented under the hanging |
839 | indent given by @code{idlwave-hang-indent-regexp} match in the first | |
a8e833f3 | 840 | line of the paragraph. |
797c8ebc CD |
841 | @end defopt |
842 | ||
843 | @defopt idlwave-hang-indent-regexp | |
844 | Regular expression matching the position of the hanging indent | |
a8e833f3 | 845 | in the first line of a comment paragraph. |
797c8ebc CD |
846 | @end defopt |
847 | ||
848 | @defopt idlwave-use-last-hang-indent (@code{nil}) | |
849 | Non-@code{nil} means use last match on line for | |
a8e833f3 | 850 | @code{idlwave-indent-regexp}. |
797c8ebc CD |
851 | @end defopt |
852 | ||
853 | @node Syntax Highlighting, , Continuation Lines, Code Formatting | |
854 | @subsection Syntax Highlighting | |
855 | @cindex Syntax highlighting | |
a8e833f3 | 856 | @cindex Highlighting of syntax |
797c8ebc CD |
857 | @cindex Font lock |
858 | ||
859 | Highlighting of keywords, comments, strings etc. can be accomplished | |
a8e833f3 CD |
860 | with @code{font-lock}. If you are using @code{global-font-lock-mode} |
861 | (on Emacs), or have @code{font-lock} turned on in any other buffer in | |
862 | XEmacs, it should also automatically work in IDLWAVE buffers. If not, | |
863 | you can enforce it with the following line in your @file{.emacs} | |
797c8ebc CD |
864 | |
865 | @lisp | |
866 | (add-hook 'idlwave-mode-hook 'turn-on-font-lock) | |
867 | @end lisp | |
868 | ||
869 | IDLWAVE supports 3 levels of syntax highlighting. The variable | |
870 | @code{font-lock-maximum-decoration} determines which level is selected. | |
871 | ||
872 | @defopt idlwave-default-font-lock-items | |
873 | Items which should be fontified on the default fontification level | |
a8e833f3 | 874 | 2. |
797c8ebc CD |
875 | @end defopt |
876 | ||
a8e833f3 | 877 | @node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode |
797c8ebc CD |
878 | @section Routine Info |
879 | @cindex Routine info | |
a8e833f3 CD |
880 | @cindex Updating routine info |
881 | @cindex Scanning buffers for routine info | |
882 | @cindex Buffers, scanning for routine info | |
883 | @cindex Shell, querying for routine info | |
797c8ebc | 884 | |
a8e833f3 | 885 | @kindex C-c C-i |
797c8ebc CD |
886 | IDL defines more than one thousand procedures, functions and object |
887 | methods. This large command set makes it difficult to remember the | |
888 | calling sequence and keywords of a command. IDLWAVE contains a list of | |
889 | all builtin routines with calling sequences and keywords@footnote{This | |
890 | list was created by scanning the IDL manual and might contain (very few) | |
891 | errors. Please report any detected errors to the maintainer, so that | |
892 | they can be fixed.}. It also scans Emacs buffers and library files for | |
893 | routine definitions and queries the IDLWAVE-Shell for the properties of | |
a8e833f3 CD |
894 | modules currently compiled under the shell. This information is updated |
895 | automatically. If you think the information is not up-to-date, use | |
896 | @kbd{C-c C-i} (@code{idlwave-update-routine-info}) to enforce a global | |
897 | update. | |
797c8ebc | 898 | |
a8e833f3 | 899 | @kindex C-c ? |
797c8ebc CD |
900 | To display the information about a routine, press @kbd{C-c ?} which |
901 | calls the command @code{idlwave-routine-info}. When the current cursor | |
902 | position is on the name or in the argument list of a procedure or | |
903 | function, information will be displayed about the routine. For example, | |
904 | consider the cursor positions in the following line | |
905 | ||
906 | @example | |
907 | plot,x,alog(x+5*sin(x) + 2), | |
908 | 1 2 3 4 5 6 7 8 | |
909 | @end example | |
910 | ||
a8e833f3 | 911 | @cindex Default routine, for info and help |
797c8ebc CD |
912 | On positions 1,2 and 8, information about the @samp{plot} procedure will |
913 | be shown. On positions 3,4, and 7, the @samp{alog} function will be | |
914 | described, while positions 5 and 6 will select the @samp{sin} function. | |
915 | When you ask for routine information about an object method, and the | |
916 | method exists in several classes, IDLWAVE queries for the class of the | |
917 | object. | |
918 | ||
919 | @cindex Calling sequences | |
920 | @cindex Keywords of a routine | |
a8e833f3 | 921 | @cindex Routine source information |
797c8ebc | 922 | The description displayed contains the calling sequence, the list of |
a8e833f3 | 923 | keywords and the source location of this routine. It looks like this: |
797c8ebc CD |
924 | |
925 | @example | |
a8e833f3 CD |
926 | Usage: XMANAGER, NAME, ID |
927 | Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER | |
928 | JUST_REG MODAL NO_BLOCK | |
929 | Source: SystemLib [CSB] /soft1/idl53/lib/xmanager.pro | |
797c8ebc CD |
930 | @end example |
931 | ||
a8e833f3 CD |
932 | @cindex Categories, of routines |
933 | @cindex Load-path shadows | |
934 | @cindex Shadows, load-path | |
935 | @cindex IDL variable @code{!PATH} | |
936 | @cindex @code{!PATH}, IDL variable | |
937 | @cindex IDL variable @code{!DIR} | |
938 | @cindex @code{!DIR}, IDL variable | |
939 | ||
940 | If a definition of this routine exists in several files accessible to | |
941 | IDLWAVE, several @samp{Source} lines will point to the different files. | |
942 | This may indicate that your routine is shadowing a library routine, | |
943 | which may or may not be what you want (@pxref{Load-Path Shadows}). The | |
944 | information about the calling sequence and the keywords is derived from | |
945 | the first source listed. Library routines can only be supported if you | |
aea44e56 | 946 | have scanned the local IDL library (@pxref{Library Catalog}). The source |
a8e833f3 CD |
947 | entry consists of a @emph{source category}, a set of @emph{flags} and |
948 | the path to the @emph{source file}. The following categories | |
949 | exist: | |
950 | ||
951 | @multitable @columnfractions .15 .85 | |
952 | @item @i{System} | |
953 | @tab A system routine, but we do not know if it is @i{Builtin} or | |
954 | @i{SystemLib}. When the system library has bee scanned | |
aea44e56 | 955 | (@pxref{Library Catalog}), this category will automatically split into the |
a8e833f3 CD |
956 | next two. |
957 | @item @i{Builtin} | |
958 | @tab A builtin routine with no source code available. | |
959 | @item @i{SystemLib} | |
960 | @tab A library routine in the official lib directory @file{!DIR/lib}. | |
961 | @item @i{Obsolete} | |
962 | @tab A library routine in the official lib directory @file{!DIR/lib/obsolete}. | |
963 | @item @i{Library} | |
964 | @tab A file on IDL's search path @code{!PATH}. | |
965 | @item @i{Other} | |
966 | @tab Any other file not known to be on the search path. | |
967 | @item @i{Unresolved} | |
968 | @tab The shell lists this routine as unresolved. | |
969 | @end multitable | |
970 | ||
971 | You can define additional categories based on the file name and path | |
972 | with the variable @code{idlwave-special-lib-alist}. | |
973 | ||
974 | @cindex Flags, in routine info | |
975 | @cindex Duplicate routines | |
976 | @cindex Multiply defined routines | |
977 | @cindex Routine definitions, multiple | |
978 | The flags @code{[CSB]} indicate if the file is known to IDLWAVE from the | |
aea44e56 | 979 | library catalog (@w{@code{[C--]}}, @pxref{Library Catalog}), from the Shell |
a8e833f3 CD |
980 | (@w{@code{[-S-]}}) or from an Emacs buffer (@w{@code{[--B]}}). |
981 | Combinations are possible. If a file contains multiple definitions of | |
982 | the same routine, the file name will be prefixed with @samp{(Nx)} where | |
983 | @samp{N} is the number of definitions. | |
984 | ||
985 | @cindex Online Help from the routine info buffer | |
986 | @cindex Active text, in routine info | |
987 | @cindex Inserting keywords, from routine info | |
988 | @cindex Source file, access from routine info | |
797c8ebc | 989 | Some of the text in the @file{*Help*} buffer will be active (it |
a8e833f3 CD |
990 | highlights when you move the mouse over it). Clicking on these items |
991 | will have the following effects: | |
992 | ||
993 | @multitable @columnfractions 0.15 0.85 | |
994 | @item @i{Usage} | |
995 | @tab If online help is installed, a click with the @emph{right} mouse | |
996 | button on the @i{Usage:} line will access the help for the | |
997 | routine (@pxref{Online Help}). | |
998 | @item @i{Keyword} | |
999 | @tab Online help about keywords is also available with the | |
1000 | @emph{right} mouse button. Clicking on a keyword with the @emph{middle} | |
1001 | mouse button will insert this keyword in the buffer from where | |
1002 | @code{idlwave-routine-info} was called. Holding down @key{SHIFT} while | |
1003 | clicking also adds the initial @samp{/}. | |
1004 | @item @i{Source} | |
1005 | @tab Clicking with the @emph{middle} mouse button on a @samp{Source} line | |
1006 | finds the source file of the routine and visits it in another window. | |
1007 | Another click on the same line switches back to the buffer from which | |
1008 | @kbd{C-c ?} was called. If you use the @emph{right} mouse button, the | |
1009 | source will not be visited by a buffer, but displayed in the online help | |
1010 | window. | |
aea44e56 CD |
1011 | @item @i{Classes} |
1012 | @tab The @i{Classes} line is only included in the routine info window if | |
1013 | the current class inherits from other classes. You can click with the | |
1014 | @emph{middle} mouse button to display routine info about the current | |
1015 | method in other classes on the inheritance chain. | |
a8e833f3 | 1016 | @end multitable |
797c8ebc | 1017 | |
a8e833f3 CD |
1018 | @defopt idlwave-resize-routine-help-window (@code{t}) |
1019 | Non-@code{nil} means, resize the Routine-info @file{*Help*} window to | |
1020 | fit the content. | |
1021 | @end defopt | |
797c8ebc | 1022 | |
a8e833f3 CD |
1023 | @defopt idlwave-special-lib-alist |
1024 | Alist of regular expressions matching special library directories. | |
1025 | @end defopt | |
797c8ebc | 1026 | |
a8e833f3 CD |
1027 | @defopt idlwave-rinfo-max-source-lines (@code{5}) |
1028 | Maximum number of source files displayed in the Routine Info window. | |
1029 | @end defopt | |
797c8ebc | 1030 | |
a8e833f3 | 1031 | @page |
797c8ebc | 1032 | |
a8e833f3 CD |
1033 | @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode |
1034 | @section Online Help | |
1035 | ||
1036 | @cindex Online Help | |
1037 | @cindex @file{idlw-help.txt} | |
1038 | @cindex @file{idlw-help.el} | |
1039 | @cindex IDL manual, ASCII version | |
1040 | @cindex Installing online help | |
1041 | @cindex Online Help, Installation | |
1042 | @cindex Speed, of online help | |
1043 | For IDL system routines, RSI provides extensive documentation. IDLWAVE | |
1044 | can access an ASCII version of this documentation very quickly and | |
1045 | accurately. This is @emph{much} faster than using the IDL online help | |
1046 | application, also because usually IDLWAVE gets you to the right place in | |
1047 | the docs directly, without additional browsing and scrolling. For this | |
1048 | online help to work, you need an ASCII version of the IDL documentation | |
1049 | which is not part of the standard IDLWAVE distribution. The required | |
1050 | files can be downloaded from @uref{@value{IDLWAVE-HOMEPAGE}, the | |
1051 | maintainers webpage}. As the text is extracted from PDF files, the | |
1052 | formatting of the help text is good for normal text, but graphics and | |
1053 | multiline equations will not be well represented. See also | |
1054 | @ref{Documentation Scan}. | |
1055 | ||
1056 | @cindex Source code, as online help | |
1057 | @cindex DocLib header, as online help | |
1058 | For routines which are not documented in the IDL manual (for example | |
1059 | your own routines), the source code is used as help text. If the | |
1060 | requested information can be found in a (more or less) standard DocLib | |
1061 | file header, IDLWAVE shows the header. Otherwise the routine definition | |
1062 | statement (@code{pro}/@code{function}) is shown. | |
1063 | ||
1064 | @kindex M-? | |
1065 | In any IDL program, press @kbd{M-?} (@code{idlwave-context-help}) or | |
80d7cf55 | 1066 | click with @kbd{S-Mouse-3} to access context sensitive online help. The |
a8e833f3 CD |
1067 | following locations are recognized as context: |
1068 | ||
1069 | @cindex Context, for online help | |
1070 | @multitable @columnfractions .25 .75 | |
1071 | @item @i{Routine name} | |
1072 | @tab The name of a routine (function, procedure, method). | |
1073 | @item @i{Keyword Parameter} | |
1074 | @tab Keyword parameter of a routine. | |
1075 | @item @i{System Variable} | |
1076 | @tab System variable like @code{!DPI}. | |
1077 | @item @i{IDL Statement} | |
1078 | @tab Like @code{PRO}, @code{REPEAT}, or @code{COMPILE_OPT}. | |
1079 | @item @i{Class name} | |
1080 | @tab Class name in @code{OBJ_NEW} call. | |
1081 | @item @i{Executive Command} | |
1082 | @tab Executive command like @code{.RUN}. Mostly useful in the shell. | |
1083 | @item @i{Default} | |
1084 | @tab The routine that would be selected for routine info display. | |
1085 | @end multitable | |
1086 | ||
1087 | @cindex @code{OBJ_NEW}, special online help | |
1088 | Note that the @code{OBJ_NEW} function is special in that the help | |
1089 | displayed depends on the cursor position: If the cursor is on the | |
1090 | @samp{OBJ_NEW}, this function is described. If it is on the class name | |
1091 | inside the quotes, the documentation for the class is pulled up. If the | |
1092 | cursor is @emph{after} the class name, anywhere in the argument list, | |
1093 | the documentation for the corresponding @code{Init} method and its | |
1094 | keywords is targeted. | |
1095 | ||
1096 | @noindent Apart from source buffers, there are two more places from | |
1097 | which online help can be accessed. | |
1098 | ||
1099 | @itemize @bullet | |
1100 | @item | |
1101 | Online help for routines and keywords can be accessed through the | |
80d7cf55 | 1102 | Routine Info display. Click with @kbd{Mouse-3} on an item to see the |
a8e833f3 CD |
1103 | corresponding help (@pxref{Routine Info}). |
1104 | @item | |
1105 | When using completion and Emacs pops up a window with possible | |
80d7cf55 | 1106 | completions, clicking with @kbd{Mouse-3} on a completion item invokes |
a8e833f3 CD |
1107 | help on that item (@pxref{Completion}). |
1108 | @end itemize | |
1109 | @noindent | |
1110 | In both cases, a blue face indicates that the item is documented in the | |
1111 | IDL manual. | |
1112 | ||
1113 | @page | |
1114 | ||
1115 | @cindex Help application, keybindings | |
1116 | @cindex Keybindings, in help application | |
1117 | The help window is normally displayed in a separate frame. The | |
1118 | following commands can be used to navigate inside the help system. | |
1119 | ||
1120 | @multitable @columnfractions .15 .85 | |
1121 | @item @kbd{@key{SPACE}} | |
1122 | @tab Scroll forward one page. | |
1123 | @item @kbd{@key{RET}} | |
1124 | @tab Scroll forward one line. | |
1125 | @item @kbd{@key{DEL}} | |
1126 | @tab Scroll back one page. | |
1127 | @item @kbd{n, p} | |
1128 | @tab Browse to the next or previous topic (in physical sequence). | |
1129 | @item @kbd{b, f} | |
1130 | @tab Move back and forward through the help topic history. | |
1131 | @item @kbd{c} | |
1132 | @tab Clear the history. | |
80d7cf55 | 1133 | @item @kbd{Mouse-2} |
a8e833f3 CD |
1134 | @tab Follow a link. Active links are displayed in a different font. |
1135 | Items under @i{See Also} are active, and classes have links to their | |
1136 | methods and back. | |
1137 | @item @kbd{o} | |
1138 | @tab Open a topic. The topic can be selected with completion. | |
1139 | @item @kbd{*} | |
1140 | @tab Load the whole help file into Emacs, for global text searches. | |
1141 | @item @kbd{q} | |
1142 | @tab Kill the help window. | |
1143 | @end multitable | |
1144 | ||
1145 | @sp 1 | |
1146 | @noindent When the help text is a source file, the following commands | |
1147 | are also available. | |
1148 | @multitable @columnfractions .15 .85 | |
1149 | @item @kbd{h} | |
1150 | @tab Jump to DocLib Header of the routine whose source is displayed | |
1151 | as help. | |
1152 | @item @kbd{H} | |
1153 | @tab Jump to the first DocLib Header in the file. | |
1154 | @item @kbd{.} @r{(Dot)} | |
1155 | @tab Jump back and forth between the routine definition (the | |
1156 | @code{pro}/@code{function} statement) and the description of the help | |
1157 | item in the DocLib header. | |
1158 | @item @kbd{F} | |
1159 | @tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}. | |
1160 | @end multitable | |
1161 | ||
1162 | @defopt idlwave-help-directory | |
1163 | The directory where idlw-help.txt and idlw-help.el are stored. | |
797c8ebc CD |
1164 | @end defopt |
1165 | ||
a8e833f3 CD |
1166 | @defopt idlwave-help-use-dedicated-frame (@code{t}) |
1167 | Non-nil means, use a separate frame for Online Help if possible. | |
797c8ebc CD |
1168 | @end defopt |
1169 | ||
a8e833f3 CD |
1170 | @defopt idlwave-help-frame-parameters |
1171 | The frame parameters for the special Online Help frame. | |
1172 | @end defopt | |
1173 | ||
1174 | @defopt idlwave-max-popup-menu-items (@code{20}) | |
1175 | Maximum number of items per pane in popup menus. | |
1176 | @end defopt | |
1177 | ||
1178 | @defopt idlwave-extra-help-function | |
1179 | Function to call for help if the normal help fails. | |
797c8ebc CD |
1180 | @end defopt |
1181 | ||
a8e833f3 CD |
1182 | @defopt idlwave-help-fontify-source-code (@code{nil}) |
1183 | Non-nil means, fontify source code displayed as help. | |
1184 | @end defopt | |
797c8ebc | 1185 | |
a8e833f3 CD |
1186 | @defopt idlwave-help-source-try-header (@code{t}) |
1187 | Non-nil means, try to find help in routine header when displaying source | |
1188 | file. | |
1189 | @end defopt | |
1190 | ||
1191 | @defopt idlwave-help-link-face | |
1192 | The face for links to IDLWAVE online help. | |
1193 | @end defopt | |
1194 | ||
aea44e56 CD |
1195 | @defopt idlwave-help-activate-links-agressively (@code{t}) |
1196 | Non-@code{nil} means, make all possible links in help window active. | |
1197 | @end defopt | |
1198 | ||
a8e833f3 | 1199 | @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode |
797c8ebc CD |
1200 | @section Completion |
1201 | @cindex Completion | |
a8e833f3 CD |
1202 | @cindex Keyword completion |
1203 | @cindex Method completion | |
1204 | @cindex Object method completion | |
1205 | @cindex Class name completion | |
1206 | @cindex Function name completion | |
1207 | @cindex Procedure name completion | |
1208 | ||
1209 | @kindex M-@key{TAB} | |
1210 | @kindex C-c C-i | |
1211 | IDLWAVE offers completion for class names, routine names and keywords. | |
1212 | As in many programming modes, completion is bound to @kbd{M-@key{TAB}}. | |
1213 | Completion uses the same internal information as routine info, so when | |
1214 | necessary it can be updated with @kbd{C-c C-i} | |
1215 | (@code{idlwave-update-routine-info}). | |
797c8ebc CD |
1216 | |
1217 | The completion function is context sensitive and figures out what to | |
1218 | complete at point. Here are example lines and what @kbd{M-@key{TAB}} | |
1219 | would try to complete when the cursor is on the position marked with a | |
1220 | @samp{*}. | |
1221 | ||
1222 | @example | |
1223 | plo* @r{Procedure} | |
1224 | x = a* @r{Function} | |
1225 | plot,xra* @r{Keyword of @code{plot} procedure} | |
1226 | plot,x,y,/x* @r{Keyword of @code{plot} procedure} | |
1227 | plot,min(* @r{Keyword of @code{min} function} | |
1228 | obj -> a* @r{Object method (procedure)} | |
1229 | a(2,3) = obj -> a* @r{Object method (function)} | |
1230 | x = obj_new('IDL* @r{Class name} | |
1231 | x = obj_new('MyCl',a* @r{Keyword to @code{Init} method in class @code{MyCl}} | |
a8e833f3 CD |
1232 | pro A* @r{Class name} |
1233 | pro * @r{Fill in @code{Class::} of first method in this file} | |
aea44e56 CD |
1234 | !v* @r{System variable} |
1235 | !version.t* @r{Structure tag of system variable} | |
1236 | self.g* @r{Class structure tag in methods} | |
797c8ebc CD |
1237 | @end example |
1238 | ||
1239 | @cindex Scrolling the @file{*Completions*} window | |
1240 | @cindex Completion, scrolling | |
a8e833f3 CD |
1241 | @cindex Completion, Online Help |
1242 | @cindex Online Help in @file{*Completions*} buffer | |
797c8ebc CD |
1243 | If the list of completions is too long to fit in the |
1244 | @file{*Completions*} window, the window can be scrolled by pressing | |
a8e833f3 | 1245 | @kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each |
80d7cf55 | 1246 | possible completion is available by clicking with @kbd{Mouse-3} on the |
a8e833f3 CD |
1247 | item. Items for which system online help (from the IDL manual) is |
1248 | available will be displayed in a different font. For other items, the | |
1249 | corresponding source code or DocLib header is available as help text. | |
797c8ebc CD |
1250 | |
1251 | @cindex Case of completed words | |
a8e833f3 | 1252 | @cindex Mixed case completion |
797c8ebc CD |
1253 | The case of the completed words is determined by what is already in the |
1254 | buffer. When the partial word being completed is all lower case, the | |
1255 | completion will be lower case as well. If at least one character is | |
1256 | upper case, the string will be completed in upper case or mixed case. | |
1257 | The default is to use upper case for procedures, functions and keywords, | |
1258 | and mixed case for object class names and methods, similar to the | |
1259 | conventions in the IDL manuals. These defaults can be changed with the | |
a8e833f3 | 1260 | variable @code{idlwave-completion-case}. |
797c8ebc CD |
1261 | |
1262 | @defopt idlwave-completion-case | |
1263 | Association list setting the case (UPPER/lower/Capitalized/...) of completed | |
a8e833f3 | 1264 | words. |
797c8ebc CD |
1265 | @end defopt |
1266 | ||
1267 | @defopt idlwave-completion-force-default-case (@code{nil}) | |
1268 | Non-@code{nil} means, completion will always honor the settings in | |
1269 | @code{idlwave-completion-case}. When nil (the default), lower case | |
1270 | strings will be completed to lower case. | |
1271 | @end defopt | |
1272 | ||
1273 | @defopt idlwave-complete-empty-string-as-lower-case (@code{nil}) | |
1274 | Non-@code{nil} means, the empty string is considered lower case for | |
a8e833f3 | 1275 | completion. |
797c8ebc CD |
1276 | @end defopt |
1277 | ||
1278 | @defopt idlwave-keyword-completion-adds-equal (@code{t}) | |
1279 | Non-@code{nil} means, completion automatically adds @samp{=} after | |
a8e833f3 | 1280 | completed keywords. |
797c8ebc CD |
1281 | @end defopt |
1282 | ||
1283 | @defopt idlwave-function-completion-adds-paren (@code{t}) | |
1284 | Non-@code{nil} means, completion automatically adds @samp{(} after | |
1285 | completed function. A value of `2' means, also add the closing | |
a8e833f3 | 1286 | parenthesis and position cursor between the two. |
797c8ebc CD |
1287 | @end defopt |
1288 | ||
1289 | @defopt idlwave-completion-restore-window-configuration (@code{t}) | |
1290 | Non-@code{nil} means, restore window configuration after successful | |
a8e833f3 CD |
1291 | completion. |
1292 | @end defopt | |
1293 | ||
1294 | @defopt idlwave-highlight-help-links-in-completion (@code{t}) | |
1295 | Non-nil means, highlight completions for which system help is available. | |
797c8ebc CD |
1296 | @end defopt |
1297 | ||
1298 | @subsubheading Object Method Completion and Class Ambiguity | |
1299 | @cindex Object methods | |
1300 | @cindex Class ambiguity | |
a8e833f3 | 1301 | @cindex @code{self} object, default class |
797c8ebc CD |
1302 | An object method is not uniquely determined without the object's class. |
1303 | Since the class part is usually omitted in the source code, IDLWAVE | |
1304 | considers all available methods in all classes as possible completions | |
1305 | of an object method name. For keywords, the combined keywords of the | |
1306 | current method in all available classes will be considered. In the | |
1307 | @file{*Completions*} buffer, the classes allowed for each completion | |
1308 | will be shown next to the item (see option | |
a8e833f3 CD |
1309 | @code{idlwave-completion-show-classes}). As a special case, the class |
1310 | of an object called @samp{self} object is always the class of the | |
aea44e56 CD |
1311 | current routine. All classes it inherits from are considered as well |
1312 | where appropriate. | |
797c8ebc | 1313 | |
a8e833f3 CD |
1314 | @cindex Forcing class query. |
1315 | @cindex Class query, forcing | |
797c8ebc CD |
1316 | You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u |
1317 | M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to | |
1318 | narrow down the number of possible completions. The variable | |
1319 | @code{idlwave-query-class} can be configured to make this behavior the | |
a8e833f3 | 1320 | default (not recommended). After you have specified the class |
797c8ebc CD |
1321 | for a particular statement (e.g. when completing the method), IDLWAVE |
1322 | can remember it for the rest of the editing session. Subsequent | |
1323 | completions in the same statement (e.g. keywords) can then reuse this | |
1324 | class information. Remembering the class works by placing a text | |
1325 | property in the object operator @samp{->}. This is not enabled by | |
1326 | default - the variable @code{idlwave-store-inquired-class} can be used | |
a8e833f3 | 1327 | to turn it on. |
797c8ebc | 1328 | |
aea44e56 CD |
1329 | @defopt idlwave-support-inheritance (@code{t}) |
1330 | Non-@code{nil} means, treat inheritance with completion, online help etc. | |
1331 | @end defopt | |
1332 | ||
ea442c62 | 1333 | @defopt idlwave-completion-show-classes (@code{1}) |
797c8ebc | 1334 | Non-@code{nil} means, show classes in @file{*Completions*} buffer when |
a8e833f3 | 1335 | completing object methods and keywords. |
797c8ebc CD |
1336 | @end defopt |
1337 | ||
1338 | @defopt idlwave-completion-fontify-classes (@code{t}) | |
1339 | Non-@code{nil} means, fontify the classes in completions buffer. | |
1340 | @end defopt | |
1341 | ||
1342 | @defopt idlwave-query-class (@code{nil}) | |
a8e833f3 | 1343 | Association list governing query for object classes during completion. |
797c8ebc CD |
1344 | @end defopt |
1345 | ||
1346 | @defopt idlwave-store-inquired-class (@code{nil}) | |
1347 | Non-@code{nil} means, store class of a method call as text property on | |
a8e833f3 | 1348 | @samp{->}. |
797c8ebc CD |
1349 | @end defopt |
1350 | ||
1351 | @defopt idlwave-class-arrow-face | |
1352 | Face to highlight object operator arrows @samp{->} which carry a class | |
a8e833f3 | 1353 | text property. |
797c8ebc CD |
1354 | @end defopt |
1355 | ||
a8e833f3 CD |
1356 | @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode |
1357 | ||
1358 | @section Routine Source | |
1359 | @cindex Routine source file | |
1360 | @cindex Module source file | |
1361 | @cindex Source file, of a routine | |
1362 | @kindex C-c C-v | |
1363 | Apart from clicking on a @i{Source:} line in the routine info window, | |
1364 | there is also another way to find the source file of a routine. The | |
1365 | command @kbd{C-c C-v} (@code{idlwave-find-module}) asks for a module | |
1366 | name, offering the same default as @code{idlwave-routine-info} would | |
1367 | have used. In the minibuffer, specify a complete routine name | |
1368 | (including the class part). IDLWAVE will display the source file in | |
1369 | another window. | |
1370 | ||
1371 | @cindex Buffers, killing | |
1372 | @cindex Killing autoloaded buffers | |
1373 | Since getting the source of a routine into a buffer is so easy with | |
1374 | IDLWAVE, too many buffers visiting different IDL source files are | |
1375 | sometimes created. The special command @kbd{C-c C-k} | |
1376 | (@code{idlwave-kill-autoloaded-buffers}) can be used to remove these | |
1377 | buffers. | |
1378 | ||
1379 | @node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode | |
1380 | @section Resolving Routines | |
1381 | @cindex @code{RESOLVE_ROUTINE} | |
1382 | @cindex Compiling library modules | |
1383 | @cindex Routines, resolving | |
1384 | ||
1385 | The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve} | |
1386 | and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL | |
1387 | in order to resolve (compile) it. The default routine to be resolved is | |
1388 | taken from context, but you get a chance to edit it. | |
1389 | ||
1390 | @code{idlwave-resolve} is one way to get a library module within reach | |
1391 | of IDLWAVE's routine info collecting functions. A better way is to | |
aea44e56 | 1392 | scan (parts of) the library (@pxref{Library Catalog}). Routine info on |
a8e833f3 CD |
1393 | library modules will then be available without the need to compile the |
1394 | modules first, and even without a running shell. | |
1395 | ||
1396 | @xref{Sources of Routine Info}, for in-depth information where IDLWAVE | |
1397 | collects data about routines, and how to update this information. | |
1398 | ||
1399 | ||
1400 | @node Code Templates, Actions, Resolving Routines, The IDLWAVE Major Mode | |
797c8ebc CD |
1401 | @section Code Templates |
1402 | @cindex Code templates | |
1403 | @cindex Abbreviations | |
1404 | @cindex Templates | |
1405 | ||
1406 | IDLWAVE can insert IDL code templates into the buffer. For a few | |
1407 | templates, this is done with direct keybindings: | |
1408 | ||
1409 | @multitable @columnfractions .15 .85 | |
1410 | @item @kbd{C-c C-c} | |
1411 | @tab @code{CASE} statement template | |
1412 | @item @kbd{C-c C-f} | |
1413 | @tab @code{FOR} loop template | |
1414 | @item @kbd{C-c C-r} | |
1415 | @tab @code{REPEAT} loop template | |
1416 | @item @kbd{C-c C-w} | |
1417 | @tab @code{WHILE} loop template | |
1418 | @end multitable | |
1419 | ||
1420 | Otherwise, special abbreviations are used. Emacs abbreviations are | |
1421 | expanded by typing text into the buffer and pressing @key{SPC} or | |
1422 | @key{RET}. The special abbreviations used to insert code templates all | |
1423 | start with a @samp{\} (the backslash). Here are a few examples of | |
ea442c62 | 1424 | predefined abbreviations. For a full list, use @kbd{M-x |
797c8ebc CD |
1425 | idlwave-list-abbrevs}. |
1426 | ||
1427 | @multitable @columnfractions .15 .85 | |
1428 | @item @code{\pr} | |
1429 | @tab @code{PROCEDURE} template | |
1430 | @item @code{\fu} | |
1431 | @tab @code{FUNCTION} template | |
1432 | @item @code{\c} | |
1433 | @tab @code{CASE} statement template | |
1434 | @item @code{\f} | |
1435 | @tab @code{FOR} loop template | |
1436 | @item @code{\r} | |
1437 | @tab @code{REPEAT} loop template | |
1438 | @item @code{\w} | |
1439 | @tab @code{WHILE} loop template | |
1440 | @item @code{\i} | |
1441 | @tab @code{IF} statement template | |
1442 | @item @code{\elif} | |
1443 | @tab @code{IF-ELSE} statement template | |
1444 | @item @code{\b} | |
1445 | @tab @code{BEGIN} | |
1446 | @end multitable | |
ea442c62 CD |
1447 | |
1448 | The templates are expanded in upper or lower case, depending upon the | |
1449 | variables @code{idlwave-abbrev-change-case} and | |
a8e833f3 | 1450 | @code{idlwave-reserved-word-upcase}. |
ea442c62 | 1451 | |
aea44e56 | 1452 | @defopt idlwave-abbrev-start-char (@code{"\"}) |
797c8ebc | 1453 | A single character string used to start abbreviations in abbrev |
a8e833f3 | 1454 | mode. |
797c8ebc CD |
1455 | @end defopt |
1456 | ||
1457 | @defopt idlwave-abbrev-move (@code{t}) | |
1458 | Non-@code{nil} means the abbrev hook can move point, e.g. to end up | |
1459 | between the parenthesis of a function call. | |
1460 | @end defopt | |
1461 | ||
1462 | @node Actions, Doc Header, Code Templates, The IDLWAVE Major Mode | |
1463 | @section Actions | |
1464 | @cindex Actions | |
1465 | @cindex Coding standards, enforcing | |
1466 | ||
1467 | @emph{Actions} are special commands which are executed automatically | |
1468 | while you write code in order to check the structure of the program or | |
1469 | to enforce coding standards. Most actions which have been implemented | |
1470 | in IDLWAVE are turned off by default, assuming that the average user | |
1471 | wants her code the way she writes it. But if you are a lazy typist and | |
1472 | want your code to adhere to certain standards, they can be | |
a8e833f3 | 1473 | helpful. |
797c8ebc CD |
1474 | |
1475 | Action can be applied in three ways: | |
a8e833f3 | 1476 | |
797c8ebc CD |
1477 | @itemize @bullet |
1478 | @item | |
1479 | Some actions are applied directly while typing. For example, pressing | |
1480 | @samp{=} can run a check to make sure that this operator is surrounded | |
1481 | by spaces and insert these spaces if necessary. Pressing @key{SPC} | |
1482 | after a reserved word can call a command to change the word to upper | |
a8e833f3 | 1483 | case. |
797c8ebc CD |
1484 | @item |
1485 | When a line is re-indented with @key{TAB}, actions can be applied to the | |
1486 | entire line. To enable this, the variable @code{idlwave-do-actions} | |
a8e833f3 | 1487 | must be non-@code{nil}. |
797c8ebc CD |
1488 | @item |
1489 | @cindex Foreign code, adapting | |
1490 | @cindex Actions, applied to foreign code | |
1491 | Action can also be applied to a larger piece of code, e.g. in order to | |
1492 | convert foreign code to your own style. To do this, mark the relevant | |
1493 | part of the code and execute @kbd{M-x expand-region-abbrevs}. Useful | |
1494 | marking commands are @kbd{C-x h} (the entire file) or @kbd{M-C-h} (the | |
1495 | current subprogram). @xref{Code Indentation}, for information how to | |
a8e833f3 | 1496 | adjust the indentation of the code. |
797c8ebc CD |
1497 | @end itemize |
1498 | ||
1499 | @defopt idlwave-do-actions (@code{nil}) | |
1500 | Non-@code{nil} means performs actions when indenting. | |
1501 | @end defopt | |
1502 | ||
1503 | @menu | |
1504 | * Block Boundary Check:: Is the END correct | |
1505 | * Padding Operators:: Enforcing space around `=' etc | |
1506 | * Case Changes:: Enforcing upper case keywords | |
1507 | @end menu | |
1508 | ||
1509 | @node Block Boundary Check, Padding Operators, Actions, Actions | |
1510 | @subsection Block Boundary Check | |
1511 | @cindex Block boundary check | |
1512 | @cindex @code{END} type checking | |
1513 | @cindex @code{END}, automatic insertion | |
a8e833f3 | 1514 | @cindex @code{END}, expanding |
797c8ebc CD |
1515 | @cindex Block, closing |
1516 | @cindex Closing a block | |
1517 | ||
1518 | Whenever you type an @code{END} statement, IDLWAVE finds the | |
1519 | corresponding start of the block and the cursor blinks back to that | |
1520 | location for a second. If you have typed a specific @code{END}, like | |
1521 | @code{ENDIF} or @code{ENDCASE}, you get a warning if that kind of END | |
a8e833f3 | 1522 | does not match the type of block it terminates. |
797c8ebc CD |
1523 | |
1524 | Set the variable @code{idlwave-expand-generic-end} in order to have all | |
1525 | generic @code{END} statements automatically expanded to a specific type. | |
1526 | You can also type @kbd{C-c ]} to close the current block by inserting | |
a8e833f3 | 1527 | the appropriate @code{END} statement. |
797c8ebc CD |
1528 | |
1529 | @defopt idlwave-show-block (@code{t}) | |
1530 | Non-@code{nil} means point blinks to block beginning for | |
a8e833f3 | 1531 | @code{idlwave-show-begin}. |
797c8ebc CD |
1532 | @end defopt |
1533 | ||
aea44e56 | 1534 | @defopt idlwave-expand-generic-end (@code{t}) |
797c8ebc CD |
1535 | Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc. |
1536 | @end defopt | |
1537 | ||
a8e833f3 CD |
1538 | @defopt idlwave-reindent-end (@code{t}) |
1539 | Non-nil means re-indent line after END was typed. | |
1540 | @end defopt | |
1541 | ||
797c8ebc CD |
1542 | @node Padding Operators, Case Changes, Block Boundary Check, Actions |
1543 | @subsection Padding Operators | |
1544 | @cindex Padding operators with spaces | |
1545 | @cindex Operators, padding with spaces | |
a8e833f3 | 1546 | @cindex Space, around operators |
797c8ebc CD |
1547 | |
1548 | Some operators can be automatically surrounded by spaces. This can | |
1549 | happen when the operator is typed, or also later when the line is | |
1550 | indented. IDLWAVE contains this setting for the operators @samp{&}, | |
a8e833f3 | 1551 | @samp{<}, @samp{>}, @samp{,}, @samp{=}, and @samp{->}@footnote{Operators |
ea442c62 CD |
1552 | longer than one character can only be padded during line indentation.}, |
1553 | but the feature is turned off by default. If you want to turn it on, | |
1554 | customize the variables @code{idlwave-surround-by-blank} and | |
1555 | @code{idlwave-do-actions}. You can also define similar actions for | |
1556 | other operators by using the function @code{idlwave-action-and-binding} | |
1557 | in the mode hook. For example, to enforce space padding of the @samp{+} | |
a8e833f3 | 1558 | and @samp{*} operators, try this in @file{.emacs} |
797c8ebc CD |
1559 | |
1560 | @lisp | |
1561 | (add-hook 'idlwave-mode-hook | |
1562 | (lambda () | |
1563 | (setq idlwave-surround-by-blank t) ; Turn this type of actions on | |
1564 | (idlwave-action-and-binding "*" '(idlwave-surround 1 1)) | |
1565 | (idlwave-action-and-binding "+" '(idlwave-surround 1 1)))) | |
1566 | @end lisp | |
1567 | ||
1568 | @defopt idlwave-surround-by-blank (@code{nil}) | |
1569 | Non-@code{nil} means, enable @code{idlwave-surround}. If non-nil, | |
ea442c62 | 1570 | @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are |
a8e833f3 | 1571 | surrounded with spaces by @code{idlwave-surround}. |
797c8ebc CD |
1572 | @end defopt |
1573 | ||
1574 | @defopt idlwave-pad-keyword (@code{t}) | |
a8e833f3 | 1575 | Non-@code{nil} means pad @samp{=} for keywords like assignments. |
797c8ebc CD |
1576 | @end defopt |
1577 | ||
1578 | @node Case Changes, , Padding Operators, Actions | |
1579 | @subsection Case Changes | |
1580 | @cindex Case changes | |
a8e833f3 CD |
1581 | @cindex Upcase, enforcing for reserved words |
1582 | @cindex Downcase, enforcing for reserved words | |
797c8ebc CD |
1583 | |
1584 | Actions can be used to change the case of reserved words or expanded | |
1585 | abbreviations by customizing the variables | |
1586 | @code{idlwave-abbrev-change-case} and | |
1587 | @code{idlwave-reserved-word-upcase}. If you want to change the case of | |
1588 | additional words automatically, put something like the following into | |
a8e833f3 | 1589 | your @file{.emacs} file: |
797c8ebc CD |
1590 | |
1591 | @lisp | |
1592 | (add-hook 'idlwave-mode-hook | |
1593 | (lambda () | |
1594 | ;; Capitalize system vars | |
1595 | (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t) | |
1596 | ;; Capitalize procedure name | |
1597 | (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" | |
1598 | '(capitalize-word 1) t) | |
1599 | ;; Capitalize common block name | |
1600 | (idlwave-action-and-binding "\\<common\\>[ \t]+\\<" | |
1601 | '(capitalize-word 1) t))) | |
1602 | @end lisp | |
1603 | ||
1604 | For more information, see the documentation string for the function | |
1605 | @code{idlwave-action-and-binding}. | |
1606 | ||
1607 | @defopt idlwave-abbrev-change-case (@code{nil}) | |
1608 | Non-@code{nil} means all abbrevs will be forced to either upper or lower | |
1609 | case. Legal values are @code{nil}, @code{t}, and @code{down}. | |
1610 | @end defopt | |
1611 | ||
1612 | @defopt idlwave-reserved-word-upcase (@code{nil}) | |
1613 | Non-@code{nil} means, reserved words will be made upper case via abbrev | |
1614 | expansion. | |
1615 | @end defopt | |
1616 | ||
1617 | ||
1618 | @node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode | |
1619 | @section Documentation Header | |
1620 | @cindex Documentation header | |
a8e833f3 | 1621 | @cindex DocLib header |
797c8ebc CD |
1622 | @cindex Modification timestamp |
1623 | @cindex Header, for file documentation | |
1624 | @cindex Timestamp, in doc header. | |
1625 | @cindex Changelog, in doc header. | |
1626 | ||
a8e833f3 CD |
1627 | @kindex C-c C-h |
1628 | @kindex C-c C-m | |
797c8ebc CD |
1629 | The command @kbd{C-c C-h} inserts a standard routine header into the |
1630 | buffer, with the usual fields for documentation. One of the keywords is | |
1631 | @samp{MODIFICATION HISTORY} under which the changes to a routine can be | |
1632 | recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION | |
1633 | HISTORY} of the current routine or file and inserts the user | |
1634 | name with a timestamp. | |
1635 | ||
1636 | @defopt idlwave-file-header | |
1637 | The doc-header template or a path to a file containing it. | |
1638 | @end defopt | |
1639 | ||
1640 | @defopt idlwave-timestamp-hook | |
1641 | The hook function used to update the timestamp of a function. | |
1642 | @end defopt | |
1643 | ||
1644 | @defopt idlwave-doc-modifications-keyword | |
1645 | The modifications keyword to use with the log documentation commands. | |
1646 | @end defopt | |
1647 | ||
1648 | @defopt idlwave-doclib-start | |
1649 | Regexp matching the start of a document library header. | |
1650 | @end defopt | |
1651 | ||
1652 | @defopt idlwave-doclib-end | |
1653 | Regexp matching the start of a document library header. | |
1654 | @end defopt | |
1655 | ||
1656 | @node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode | |
1657 | @section Motion Commands | |
1658 | @cindex Motion commands | |
1659 | @cindex Program structure, moving through | |
1660 | @cindex Code structure, moving through | |
a8e833f3 CD |
1661 | @cindex @file{Func-menu}, XEmacs package |
1662 | @cindex @file{Imenu}, Emacs package | |
1663 | @cindex Function definitions, jumping to | |
1664 | @cindex Procedure definitions, jumping to | |
1665 | ||
1666 | IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages | |
1667 | which make it easy to jump to the definitions of functions and | |
1668 | procedures in the current file. | |
797c8ebc CD |
1669 | |
1670 | Several commands allow to move quickly through the structure of an IDL | |
1671 | program. These are | |
1672 | ||
1673 | @multitable @columnfractions .15 .85 | |
1674 | @item @kbd{C-M-a} | |
1675 | @tab Beginning of subprogram | |
1676 | @item @kbd{C-M-e} | |
1677 | @tab End of subprogram | |
1678 | @item @kbd{C-c @{} | |
1679 | @tab Beginning of block (stay inside the block) | |
1680 | @item @kbd{C-c @}} | |
1681 | @tab End of block (stay inside the block) | |
1682 | @item @kbd{M-C-n} | |
1683 | @tab Forward block (on same level) | |
1684 | @item @kbd{M-C-p} | |
1685 | @tab Backward block (on same level) | |
1686 | @item @kbd{M-C-d} | |
1687 | @tab Down block (enters a block) | |
1688 | @item @kbd{M-C-u} | |
1689 | @tab Backward up block (leaves a block) | |
1690 | @item @kbd{C-c C-n} | |
1691 | @tab Next Statement | |
1692 | @end multitable | |
1693 | ||
1694 | ||
1695 | @node Misc Options, , Motion Commands, The IDLWAVE Major Mode | |
1696 | @section Miscellaneous Options | |
a8e833f3 | 1697 | @cindex Hooks |
797c8ebc CD |
1698 | |
1699 | @defopt idlwave-help-application | |
1700 | The external application providing reference help for programming. | |
1701 | @end defopt | |
1702 | ||
1703 | @defopt idlwave-startup-message (@code{t}) | |
1704 | Non-@code{nil} means display a startup message when @code{idlwave-mode}' | |
1705 | is first called. | |
1706 | @end defopt | |
1707 | ||
1708 | @defopt idlwave-mode-hook | |
1709 | Normal hook. Executed when a buffer is put into @code{idlwave-mode}. | |
1710 | @end defopt | |
1711 | ||
1712 | @defopt idlwave-load-hook | |
1713 | Normal hook. Executed when @file{idlwave.el} is loaded. | |
1714 | @end defopt | |
1715 | ||
1716 | ||
1717 | ||
1718 | ||
1719 | ||
1720 | ||
1721 | ||
1722 | ||
1723 | ||
1724 | ||
1725 | ||
1726 | ||
1727 | ||
1728 | ||
1729 | ||
1730 | ||
1731 | @node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top | |
1732 | @chapter The IDLWAVE Shell | |
1733 | @cindex IDLWAVE shell | |
1734 | @cindex Major mode, @code{idlwave-shell-mode} | |
a8e833f3 CD |
1735 | @cindex IDL, as Emacs subprocess |
1736 | @cindex Subprocess of Emacs, IDL | |
1737 | @cindex Comint, Emacs package | |
1738 | @cindex Windows | |
1739 | @cindex MacOS | |
1740 | @cindex Unix | |
797c8ebc CD |
1741 | |
1742 | The IDLWAVE shell is an Emacs major mode which allows to run the IDL | |
1743 | program as an inferior process of Emacs. It can be used to work with | |
1744 | IDL interactively, to compile and run IDL programs in Emacs buffers and | |
1745 | to debug these programs. The IDLWAVE shell uses @file{comint}, an Emacs | |
1746 | packages which handles the communication with the IDL program. | |
1747 | Unfortunately IDL for Windows and MacOS does not allow the interaction | |
1748 | with Emacs@footnote{Please inform the maintainer if you come up with a way | |
1749 | to make the IDLWAVE shell work on these systems.} - so the IDLWAVE shell | |
a8e833f3 | 1750 | only works under Unix. |
797c8ebc CD |
1751 | |
1752 | @menu | |
1753 | * Starting the Shell:: How to launch IDL as a subprocess | |
1754 | * Using the Shell:: Interactively working with the Shell | |
1755 | * Debugging IDL Programs:: Compilation/Debugging | |
1756 | @end menu | |
1757 | ||
1758 | @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell | |
1759 | @section Starting the Shell | |
1760 | @cindex Starting the shell | |
1761 | @cindex Shell, starting | |
1762 | @cindex Dedicated frame, for shell buffer | |
1763 | @cindex Frame, for shell buffer | |
a8e833f3 | 1764 | @cindex Subprocess of Emacs, IDL |
797c8ebc | 1765 | |
a8e833f3 | 1766 | @kindex C-c C-s |
797c8ebc CD |
1767 | The IDLWAVE shell can be started with the command @kbd{M-x |
1768 | idlwave-shell}. In @code{idlwave-mode} the function is bound to | |
1769 | @kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to | |
1770 | interact with the shell. If the shell is already running, @kbd{C-c C-s} | |
1771 | will simple switch to the shell buffer. The command @kbd{C-c C-l} | |
1772 | (@code{idlwave-shell-recenter-shell-window}) displays the | |
a8e833f3 | 1773 | shell window without selecting it. |
797c8ebc CD |
1774 | |
1775 | In order to create a separate frame for the IDLWAVE shell buffer, call | |
1776 | @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or | |
1777 | @kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell | |
1778 | window, configure the variable | |
a8e833f3 | 1779 | @code{idlwave-shell-use-dedicated-frame}. |
797c8ebc CD |
1780 | |
1781 | The shell can also be started automatically when another command tries | |
1782 | to send a command to it. To enable auto start, set the variable | |
a8e833f3 | 1783 | @code{idlwave-shell-automatic-start} to @code{t}. |
797c8ebc CD |
1784 | |
1785 | @defopt idlwave-shell-explicit-file-name | |
1786 | This is the command to run IDL. | |
1787 | @end defopt | |
1788 | ||
1789 | @defopt idlwave-shell-command-line-options | |
1790 | A list of command line options for calling the IDL program. | |
1791 | @end defopt | |
1792 | ||
1793 | @defopt idlwave-shell-prompt-pattern | |
1794 | Regexp to match IDL prompt at beginning of a line. | |
1795 | @end defopt | |
1796 | ||
1797 | @defopt idlwave-shell-process-name | |
1798 | Name to be associated with the IDL process. | |
1799 | @end defopt | |
1800 | ||
1801 | @defopt idlwave-shell-automatic-start | |
1802 | Non-@code{nil} means attempt to invoke idlwave-shell if not already | |
1803 | running. | |
1804 | @end defopt | |
1805 | ||
1806 | @defopt idlwave-shell-initial-commands | |
1807 | Initial commands, separated by newlines, to send to IDL. | |
1808 | @end defopt | |
1809 | ||
1810 | @defopt idlwave-shell-use-dedicated-frame (@code{nil}) | |
1811 | Non-@code{nil} means, IDLWAVE should use a special frame to display | |
1812 | shell buffer. | |
1813 | @end defopt | |
1814 | ||
1815 | @defopt idlwave-shell-frame-parameters | |
1816 | The frame parameters for a dedicated idlwave-shell frame. | |
1817 | @end defopt | |
1818 | ||
1819 | @defopt idlwave-shell-temp-pro-prefix | |
a8e833f3 | 1820 | The prefix for temporary IDL files used when compiling regions. |
797c8ebc CD |
1821 | @end defopt |
1822 | ||
a8e833f3 | 1823 | @cindex Hooks |
797c8ebc CD |
1824 | @defopt idlwave-shell-mode-hook |
1825 | Hook for customizing @code{idlwave-shell-mode}. | |
1826 | @end defopt | |
1827 | ||
1828 | @node Using the Shell, Debugging IDL Programs, Starting the Shell, The IDLWAVE Shell | |
1829 | @section Using the Shell | |
a8e833f3 | 1830 | @cindex Comint |
797c8ebc CD |
1831 | @cindex Shell, basic commands |
1832 | ||
1833 | The IDLWAVE shell works in the same fashion as other shell modes in | |
1834 | Emacs. It provides command history, command line editing and job | |
aea44e56 CD |
1835 | control. The @key{UP} and @key{DOWN} arrows cycle through the input |
1836 | history just like in an X terminal@footnote{This is different from | |
1837 | normal Emacs/Comint behavior, but more like an xterm. If you prefer the | |
1838 | default comint functionality, check the variable | |
1839 | @code{idlwave-shell-arrows-do-history}.}. Here is a list of | |
1840 | commonly used commands. | |
797c8ebc CD |
1841 | |
1842 | @multitable @columnfractions .12 .88 | |
aea44e56 CD |
1843 | @item @key{UP} |
1844 | @tab Cycle backwards in input history | |
1845 | @item @key{DOWN} | |
1846 | @tab Cycle forwards in input history | |
797c8ebc | 1847 | @item @kbd{M-p} |
aea44e56 | 1848 | @tab Cycle backwards in input history @emph{matching input} |
797c8ebc | 1849 | @item @kbd{M-n} |
aea44e56 | 1850 | @tab Cycle forwards in input history @emph{matching input} |
797c8ebc CD |
1851 | @item @kbd{M-r} |
1852 | @tab Previous input matching a regexp | |
1853 | @item @kbd{M-s} | |
1854 | @tab Next input that matches a regexp | |
1855 | @item @kbd{return} | |
1856 | @tab Send input or copy line to current prompt | |
1857 | @item @kbd{C-c C-a} | |
1858 | @tab Beginning of line; skip prompt | |
1859 | @item @kbd{C-c C-u} | |
1860 | @tab Kill input to beginning of line | |
1861 | @item @kbd{C-c C-w} | |
1862 | @tab Kill word before cursor | |
1863 | @item @kbd{C-c C-c} | |
1864 | @tab Send ^C | |
1865 | @item @kbd{C-c C-z} | |
1866 | @tab Send ^Z | |
1867 | @item @kbd{C-c C-\} | |
1868 | @tab Send ^\ | |
1869 | @item @kbd{C-c C-o} | |
1870 | @tab Delete last batch of process output | |
1871 | @item @kbd{C-c C-r} | |
1872 | @tab Show last batch of process output | |
1873 | @item @kbd{C-c C-l} | |
1874 | @tab List input history | |
1875 | @end multitable | |
1876 | ||
1877 | In addition to these standard @file{comint} commands, | |
a8e833f3 CD |
1878 | @code{idlwave-shell-mode} provides many of the commands which simplify |
1879 | writing IDL code, including abbreviations, online help, and completion. | |
1880 | See @ref{Routine Info} and @ref{Online Help} and @ref{Completion} for more | |
1881 | information on these commands. | |
1882 | ||
1883 | @cindex Completion, in the shell | |
1884 | @cindex Routine info, in the shell | |
1885 | @cindex Online Help, in the shell | |
797c8ebc CD |
1886 | @multitable @columnfractions .12 .88 |
1887 | @item @kbd{@key{TAB}} | |
1888 | @tab Completion of file names, routine names and keywords | |
a8e833f3 | 1889 | (@code{idlwave-shell-complete}) |
797c8ebc CD |
1890 | @item @kbd{M-@key{TAB}} |
1891 | @tab Same as @key{TAB} | |
1892 | @item @kbd{C-c ?} | |
1893 | @tab Routine Info display (@code{idlwave-routine-info}) | |
1894 | @item @kbd{M-?} | |
1895 | @tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp}) | |
1896 | @item @kbd{C-c C-i} | |
1897 | @tab Update routine info from buffers and shell | |
1898 | (@code{idlwave-update-routine-info}) | |
1899 | @item @kbd{C-c C-v} | |
1900 | @tab Find the source file of a routine (@code{idlwave-find-module}) | |
1901 | @item @kbd{C-c =} | |
1902 | @tab Compile a library routine (@code{idlwave-resolve}) | |
1903 | @end multitable | |
1904 | ||
aea44e56 CD |
1905 | @defopt idlwave-shell-arrows-do-history (@code{t}) |
1906 | Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command | |
1907 | history like xterm. | |
1908 | @end defopt | |
1909 | ||
797c8ebc CD |
1910 | @defopt idlwave-shell-file-name-chars |
1911 | The characters allowed in file names, as a string. Used for file name | |
a8e833f3 CD |
1912 | completion. |
1913 | @end defopt | |
1914 | ||
aea44e56 CD |
1915 | @defopt idlwave-shell-graphics-window-size |
1916 | Size of IDL graphics windows popped up by special IDLWAVE command. | |
1917 | @end defopt | |
1918 | ||
a8e833f3 CD |
1919 | @cindex Input mode |
1920 | @cindex Character input mode (Shell) | |
1921 | @cindex Line input mode (Shell) | |
1922 | @cindex Magic spells, for input mode | |
1923 | @cindex Spells, magic | |
1924 | IDLWAVE works in line input mode: You compose a full command line, using | |
1925 | all the power Emacs gives you to do this. When you press @key{RET}, the | |
1926 | whole line is sent to IDL. Sometimes it is necessary to send single | |
1927 | characters (without a newline), for example when an IDL program is | |
1928 | waiting for single character input with the @code{GET_KBRD} function. | |
1929 | You can send a single character to IDL with the command @kbd{C-c C-x} | |
1930 | (@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y} | |
1931 | (@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop | |
1932 | which accepts characters and immediately sends them to IDL. The loop | |
1933 | can be exited with @kbd{C-g}. It terminates also automatically when the | |
1934 | current IDL command is finished. Check the documentation of the two | |
1935 | variables described below for a way to make IDL programs trigger | |
1936 | automatic switches of the input mode. | |
1937 | ||
1938 | @defopt idlwave-shell-use-input-mode-magic (@code{nil}) | |
1939 | Non-nil means, IDLWAVE should check for input mode spells in output. | |
1940 | @end defopt | |
1941 | ||
1942 | @defopt idlwave-shell-input-mode-spells | |
1943 | The three regular expressions which match the magic spells for input | |
1944 | modes. | |
797c8ebc CD |
1945 | @end defopt |
1946 | ||
1947 | @node Debugging IDL Programs, , Using the Shell, The IDLWAVE Shell | |
1948 | @section Debugging IDL Programs | |
1949 | @cindex Debugging | |
1950 | @cindex Keybindings for debugging | |
1951 | @cindex Toolbar | |
1952 | ||
a8e833f3 | 1953 | @kindex C-c C-d |
797c8ebc CD |
1954 | Programs can be compiled, run, and debugged directly from the source |
1955 | buffer in Emacs. The IDLWAVE shell installs keybindings both in the | |
1956 | shell buffer and in all IDL code buffers of the current Emacs session. | |
1957 | On Emacs versions which support this, it also installs a debugging | |
1958 | toolbar. The display of the toolbar can be toggled with @kbd{C-c C-d | |
a8e833f3 | 1959 | C-t} (@code{idlwave-shell-toggle-toolbar}). |
797c8ebc CD |
1960 | |
1961 | The debugging keybindings are by default on the prefix key @kbd{C-c | |
1962 | C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d | |
aea44e56 CD |
1963 | C-b}, compiling a source file with @kbd{C-c C-d C-c}. If you find this |
1964 | too much work you can choose a combination of modifier keys which is not | |
1965 | used by other commands. For example, if you write in @file{.emacs} | |
1966 | ||
1967 | @lisp | |
1968 | (setq idlwave-shell-debug-modifiers '(control shift)) | |
1969 | @end lisp | |
1970 | ||
1971 | a breakpoint can be set by pressing @kbd{b} while holding down | |
1972 | @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a | |
1973 | source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d} | |
1974 | etc. In the remainder of this chapter we will assume that the @kbd{C-c | |
1975 | C-d} bindings are active, but each of these bindings will have an | |
1976 | equivalent single-keypress shortcut with the modifiers given in the | |
1977 | @code{idlwave-shell-debug-modifiers} variable. | |
797c8ebc | 1978 | |
a8e833f3 | 1979 | @defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) |
797c8ebc | 1980 | The prefix key for the debugging map |
a8e833f3 | 1981 | @code{idlwave-shell-mode-prefix-map}. |
797c8ebc CD |
1982 | @end defopt |
1983 | ||
1984 | @defopt idlwave-shell-activate-prefix-keybindings (@code{t}) | |
1985 | Non-@code{nil} means, debug commands will be bound to the prefix | |
1986 | key, like @kbd{C-c C-d C-b}. | |
1987 | @end defopt | |
1988 | ||
aea44e56 CD |
1989 | @defopt idlwave-shell-debug-modifiers (@code{nil}) |
1990 | List of modifier keys to use for binding debugging commands in the shell | |
1991 | and in source buffers. | |
797c8ebc CD |
1992 | @end defopt |
1993 | ||
1994 | @defopt idlwave-shell-use-toolbar (@code{t}) | |
1995 | Non-@code{nil} means, use the debugging toolbar in all IDL related | |
a8e833f3 | 1996 | buffers. |
797c8ebc CD |
1997 | @end defopt |
1998 | ||
1999 | ||
2000 | @menu | |
2001 | * Compiling Programs:: Compiling buffers under the shell | |
2002 | * Breakpoints and Stepping:: Deciding where to stop and look | |
2003 | * Examining Variables:: What is the value now? | |
2004 | @end menu | |
2005 | ||
2006 | @node Compiling Programs, Breakpoints and Stepping, Debugging IDL Programs, Debugging IDL Programs | |
2007 | @subsection Compiling Programs | |
2008 | @cindex Compiling programs | |
2009 | @cindex Programs, compiling | |
2010 | @cindex Default command line, executing | |
2011 | @cindex Executing a default command line | |
2012 | ||
a8e833f3 | 2013 | @kindex C-c C-d C-c |
797c8ebc CD |
2014 | In order to compile the current buffer under the IDLWAVE shell, press |
2015 | @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the | |
2016 | current buffer and then send the command @samp{.run path/to/file} to the | |
a8e833f3 | 2017 | shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in |
797c8ebc CD |
2018 | which case the most recently compiled buffer will be saved and |
2019 | re-compiled. | |
2020 | ||
2021 | When developing or debugging a program, it is often necessary to execute | |
2022 | the same command line many times. A convenient way to do this is | |
2023 | @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}). | |
2024 | This command first resets IDL from a state of interrupted execution by | |
2025 | closing all files and returning to the main interpreter level. Then a | |
2026 | default command line is send to the shell. To edit the default command | |
2027 | line, call @code{idlwave-shell-execute-default-command-line} with a | |
a8e833f3 | 2028 | prefix argument: @kbd{C-u C-c C-d C-y}. |
797c8ebc CD |
2029 | |
2030 | @defopt idlwave-shell-mark-stop-line (@code{t}) | |
2031 | Non-@code{nil} means, mark the source code line where IDL is currently | |
2032 | stopped. The value decides about the preferred method. Legal values | |
a8e833f3 | 2033 | are @code{nil}, @code{t}, @code{arrow}, and @code{face}. |
797c8ebc CD |
2034 | @end defopt |
2035 | ||
a8e833f3 | 2036 | @defopt idlwave-shell-overlay-arrow (@code{">"}) |
797c8ebc | 2037 | The overlay arrow to display at source lines where execution |
a8e833f3 | 2038 | halts. |
797c8ebc CD |
2039 | @end defopt |
2040 | ||
2041 | @defopt idlwave-shell-stop-line-face | |
2042 | The face which highlights the source line where IDL is | |
a8e833f3 | 2043 | stopped. |
797c8ebc CD |
2044 | @end defopt |
2045 | ||
05a1abfc | 2046 | @node Breakpoints and Stepping, Examining Variables, Compiling Programs, Debugging IDL Programs |
797c8ebc CD |
2047 | @subsection Breakpoints and Stepping |
2048 | @cindex Breakpoints | |
2049 | @cindex Stepping | |
a8e833f3 | 2050 | @cindex Execution, controlled |
797c8ebc | 2051 | |
a8e833f3 CD |
2052 | @kindex C-c C-d C-b |
2053 | @kindex C-c C-d C-b | |
797c8ebc CD |
2054 | You can set breakpoints and step through a program with IDLWAVE. |
2055 | Setting a breakpoint in the current line of the source buffer is done | |
2056 | with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a prefix | |
05a1abfc CD |
2057 | arg of 1, the breakpoint gets a @code{/ONCE} keyword, meaning that it |
2058 | will be deleted after first use. With a numeric prefix greater than | |
2059 | one, the breakpoint will only be active the @code{nth} time it is hit. | |
2060 | To clear the breakpoint in the current line, use @kbd{C-c C-d C-d} | |
2061 | (@code{idlwave-clear-current-bp}). To clear all breakpoints, use | |
2062 | @kbd{C-c C-d C-a} (@code{idlwave-clear-all-bp}). Breakpoint lines are | |
2063 | highlighted in the source code. | |
2064 | ||
2065 | Once the program has stopped somewhere, you can step through it. Here | |
2066 | is a summary of the breakpoint and stepping commands: | |
797c8ebc | 2067 | |
a8e833f3 | 2068 | @multitable @columnfractions .23 .77 |
797c8ebc CD |
2069 | @item @kbd{C-c C-d C-b} |
2070 | @tab Set breakpoint (@code{idlwave-shell-break-here}) | |
2071 | @item @kbd{C-c C-d C-i} | |
2072 | @tab Set breakpoint in function named here (@code{idlwave-shell-break-in}) | |
2073 | @item @kbd{C-c C-d C-d} | |
2074 | @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) | |
2075 | @item @kbd{C-c C-d C-a} | |
2076 | @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) | |
2077 | @item @kbd{C-c C-d C-s} | |
2078 | @tab Step, into function calls (@code{idlwave-shell-step}) | |
2079 | @item @kbd{C-c C-d C-n} | |
2080 | @tab Step, over function calls (@code{idlwave-shell-stepover}) | |
2081 | @item @kbd{C-c C-d C-k} | |
2082 | @tab Skip one statement (@code{idlwave-shell-skip}) | |
2083 | @item @kbd{C-c C-d C-u} | |
2084 | @tab Continue to end of block (@code{idlwave-shell-up}) | |
2085 | @item @kbd{C-c C-d C-m} | |
2086 | @tab Continue to end of function (@code{idlwave-shell-return}) | |
2087 | @item @kbd{C-c C-d C-o} | |
2088 | @tab Continue past end of function (@code{idlwave-shell-out}) | |
2089 | @item @kbd{C-c C-d C-h} | |
2090 | @tab Continue to line at cursor position (@code{idlwave-shell-to-here}) | |
2091 | @item @kbd{C-c C-d C-r} | |
2092 | @tab Continue execution to next breakpoint (@code{idlwave-shell-cont}) | |
2093 | @item @kbd{C-c C-d C-up} | |
2094 | @tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) | |
2095 | @item @kbd{C-c C-d C-down} | |
2096 | @tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) | |
2097 | @end multitable | |
2098 | ||
2099 | @defopt idlwave-shell-mark-breakpoints (@code{t}) | |
2100 | Non-@code{nil} means, mark breakpoints in the source file buffers. The | |
2101 | value indicates the preferred method. Legal values are @code{nil}, | |
2102 | @code{t}, @code{face}, and @code{glyph}. | |
2103 | @end defopt | |
2104 | ||
2105 | @defopt idlwave-shell-breakpoint-face | |
2106 | The face for breakpoint lines in the source code if | |
a8e833f3 | 2107 | @code{idlwave-shell-mark-breakpoints} has the value @code{face}. |
797c8ebc CD |
2108 | @end defopt |
2109 | ||
05a1abfc | 2110 | @node Examining Variables, , Breakpoints and Stepping, Debugging IDL Programs |
797c8ebc CD |
2111 | @subsection Examining Variables |
2112 | @cindex @code{PRINT} expressions | |
2113 | @cindex @code{HELP}, on expressions | |
2114 | @cindex Expressions, printing | |
2115 | @cindex Expressions, help | |
2116 | @cindex Mouse binding to print expressions | |
2117 | ||
a8e833f3 | 2118 | @kindex C-c C-d C-p |
797c8ebc | 2119 | When execution is stopped you can examine the values of variables. The |
ea442c62 CD |
2120 | command @kbd{C-c C-d C-p} prints the expression at point, while @kbd{C-c |
2121 | C-d ?} shows help on this expression. The expression at point is an | |
2122 | array expression or a function call, or the contents of a pair of | |
2123 | parenthesis. The selected expression becomes highlighted in the source | |
2124 | code for a short time. Calling the above commands with a prefix | |
2125 | argument will prompt for an expression instead of using the one at | |
2126 | point. | |
797c8ebc | 2127 | |
a8e833f3 | 2128 | It is very convenient to click with the mouse on expressions to retrieve |
80d7cf55 RS |
2129 | their value. Expression printing is also bound to @kbd{S-Mouse-2} and |
2130 | expression help to @kbd{C-S-Mouse-2}. I.e. you need to hold down | |
05a1abfc | 2131 | @key{SHIFT} and @key{CONTROL} while clicking with the mouse. |
797c8ebc | 2132 | |
05a1abfc | 2133 | @cindex Calling stack, motion |
a8e833f3 CD |
2134 | @cindex Printing expressions, on calling stack |
2135 | @cindex Restrictions for expression printing | |
ea442c62 CD |
2136 | Printing of expressions also works on higher levels of the calling |
2137 | stack. This means that you can examine the values of variables and | |
2138 | expressions inside the routine which called the current routine etc. | |
05a1abfc CD |
2139 | Use the commands @kbd{C-c C-d C-@key{UP}} |
2140 | (@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}} | |
2141 | (@code{idlwave-shell-stack-down}) or the corresponding toolbar buttons | |
2142 | to move through the calling stack. The mode line of the shell window | |
2143 | will indicate the routine and the calling stack level which define the | |
2144 | context for printing expressions. The following restrictions apply for | |
2145 | all levels except the current: | |
ea442c62 CD |
2146 | |
2147 | @itemize @bullet | |
2148 | @item | |
2149 | Array expressions must use the @samp{[ ]} index delimiters. Identifiers | |
2150 | with a @samp{( )} will be interpreted as function calls. | |
2151 | @item | |
ea442c62 CD |
2152 | @cindex ROUTINE_NAMES, IDL procedure |
2153 | Printing values of expressions on higher levels of the calling stack | |
2154 | uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, which may | |
2155 | or may not be available in future versions of IDL. | |
2156 | @end itemize | |
2157 | ||
797c8ebc CD |
2158 | @defopt idlwave-shell-expression-face |
2159 | The face for @code{idlwave-shell-expression-overlay}. | |
2160 | Allows you to choose the font, color and other properties for | |
2161 | the expression printed by IDL. | |
2162 | @end defopt | |
2163 | ||
ea442c62 CD |
2164 | @defopt idlwave-shell-print-expression-function (@code{nil}) |
2165 | A function to handle special display of evaluated expressions. | |
2166 | @end defopt | |
797c8ebc CD |
2167 | |
2168 | @node Installation, Acknowledgement, The IDLWAVE Shell, Top | |
2169 | @chapter Installation | |
2170 | @cindex Installation | |
797c8ebc CD |
2171 | |
2172 | @menu | |
2173 | * Installing IDLWAVE:: How to install the distribution | |
a8e833f3 | 2174 | * Installing Online Help:: Where to get the additional files needed |
797c8ebc CD |
2175 | * Upgrading from idl.el:: Necessary configuration changes |
2176 | @end menu | |
2177 | ||
a8e833f3 | 2178 | @node Installing IDLWAVE, Installing Online Help, Installation, Installation |
797c8ebc CD |
2179 | @section Installing IDLWAVE |
2180 | ||
a8e833f3 CD |
2181 | @cindex FTP site |
2182 | @cindex URL, homepage for IDLWAVE | |
2183 | @cindex Homepage for IDLWAVE | |
2184 | @cindex IDLWAVE, homepage | |
2185 | @cindex XEmacs package IDLWAVE | |
2186 | @cindex Emacs, distributed with IDLWAVE | |
2187 | @cindex Copyright, of IDL manual | |
2188 | IDLWAVE is part of Emacs 21.1 and later. It is also an XEmacs package | |
ea442c62 | 2189 | and can be installed from |
797c8ebc | 2190 | @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site} |
a8e833f3 CD |
2191 | with the normal package management system on XEmacs 21. These |
2192 | pre-installed versions should work out-of-the-box. However, the files | |
2193 | needed for online help are not distributed with XEmacs/Emacs and have to | |
2194 | be installed separately@footnote{Due to copyright reasons, the ASCII | |
2195 | version of the IDL manual cannot be distributed under the GPL.} | |
2196 | (@pxref{Installing Online Help}). | |
797c8ebc CD |
2197 | |
2198 | You can also download IDLWAVE and install it yourself from | |
a8e833f3 CD |
2199 | @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. Follow the |
2200 | instructions in the INSTALL file. | |
2201 | ||
2202 | @node Installing Online Help, Upgrading from idl.el , Installing IDLWAVE, Installation | |
2203 | @section Installing Online Help | |
2204 | @cindex Installing online help | |
2205 | @cindex Online Help, Installation | |
797c8ebc | 2206 | |
a8e833f3 CD |
2207 | If you want to use the online help display, two additional files (an |
2208 | ASCII version of the IDL documentation and a topics/code file) must be | |
2209 | installed. These files can also be downloaded from | |
2210 | @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. You need to | |
2211 | place the files somewhere on your system and tell IDLWAVE where they are | |
2212 | with | |
2213 | ||
2214 | @lisp | |
2215 | (setq idlwave-help-directory "/path/to/help/files/") | |
2216 | @end lisp | |
2217 | ||
2218 | @node Upgrading from idl.el, , Installing Online Help, Installation | |
797c8ebc CD |
2219 | @section Upgrading from the old @b{@file{idl.el}} file |
2220 | @cindex Upgrading from old @b{@file{idl.el}} | |
2221 | @cindex Renaming old variables | |
2222 | @cindex Old variables, renaming | |
a8e833f3 | 2223 | @kindex M-@key{TAB} |
797c8ebc CD |
2224 | |
2225 | If you have been using the old @file{idl.el} and @file{idl-shell.el} | |
2226 | files and would like to use IDLWAVE, you need to update your | |
2227 | customization in @file{.emacs}. | |
2228 | ||
2229 | @enumerate | |
2230 | @item | |
2231 | Change all variable and function prefixes from @samp{idl-} to @samp{idlwave-}. | |
2232 | @item | |
2233 | Remove the now invalid @code{autoload} and @code{auto-mode-alist} forms | |
a8e833f3 CD |
2234 | pointing to the @file{idl.el} and @file{idl-shell.el} files. Install |
2235 | the new autoload forms. | |
797c8ebc CD |
2236 | @item |
2237 | If you have been using the hook function recommended in earlier versions | |
2238 | to get a separate frame for the IDL shell, remove that command from your | |
2239 | @code{idlwave-shell-mode-hook}. Instead, set the variable | |
2240 | @code{idlwave-shell-use-dedicated-frame} with | |
2241 | @lisp | |
2242 | (setq idlwave-shell-use-dedicated-frame t) | |
2243 | @end lisp | |
ea442c62 | 2244 | @item |
a8e833f3 | 2245 | The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character. |
647b4a32 | 2246 | Like in many other Emacs modes, @kbd{M-@key{TAB}} now does |
a8e833f3 CD |
2247 | completion. Inserting a TAB has therefore been moved to |
2248 | @kbd{C-@key{TAB}}. On a character based terminal you can also use | |
2249 | @kbd{C-c @key{SPC}}. | |
797c8ebc CD |
2250 | @end enumerate |
2251 | ||
2252 | @node Acknowledgement, Sources of Routine Info, Installation, Top | |
2253 | @chapter Acknowledgement | |
2254 | @cindex Acknowledgement | |
a8e833f3 CD |
2255 | @cindex Maintainer, of IDLWAVE |
2256 | @cindex Authors, of IDLWAVE | |
2257 | @cindex Contributors, to IDLWAVE | |
2258 | @cindex Email address, of Maintainer | |
797c8ebc CD |
2259 | @cindex Thanks |
2260 | ||
a8e833f3 CD |
2261 | @noindent |
2262 | The main contributors to the IDLWAVE package have been: | |
797c8ebc | 2263 | |
a8e833f3 CD |
2264 | @itemize @minus |
2265 | @item | |
aea44e56 CD |
2266 | @uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author. |
2267 | Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them | |
2268 | for several years. | |
a8e833f3 CD |
2269 | |
2270 | @item | |
aea44e56 CD |
2271 | @uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}}, current author |
2272 | and maintainer. I have been in charge of the package since version | |
2273 | 3.0. I am also responsible for the manual. | |
a8e833f3 CD |
2274 | |
2275 | @item | |
2276 | @uref{mailto:jdsmith@@astrosun.tn.cornell.edu, @b{J.D. Smith}} has | |
2277 | shaped Object method completion and most new features in version 4.0 | |
2278 | with his ideas, bug reports, and patient explanations of IDL internals. | |
2279 | @end itemize | |
2280 | ||
2281 | @noindent | |
2282 | The following people have also contributed to the development of IDLWAVE | |
2283 | with patches, ideas, bug reports and suggestions. | |
797c8ebc CD |
2284 | |
2285 | @itemize @minus | |
2286 | @item | |
2287 | Ulrik Dickow <dickow@@nbi.dk> | |
2288 | @item | |
2289 | Eric E. Dors <edors@@lanl.gov> | |
2290 | @item | |
2291 | Stein Vidar H. Haugan <s.v.h.haugan@@astro.uio.no> | |
2292 | @item | |
2293 | David Huenemoerder <dph@@space.mit.edu> | |
2294 | @item | |
2295 | Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de> | |
2296 | @item | |
2297 | Xuyong Liu <liu@@stsci.edu> | |
2298 | @item | |
2299 | Simon Marshall <Simon.Marshall@@esrin.esa.it> | |
2300 | @item | |
aea44e56 CD |
2301 | Craig Markwardt <craigm@@cow.physics.wisc.edu> |
2302 | @item | |
797c8ebc CD |
2303 | Laurent Mugnier <mugnier@@onera.fr> |
2304 | @item | |
2305 | Lubos Pochman <lubos@@rsinc.com> | |
2306 | @item | |
2307 | Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov> | |
2308 | @item | |
2309 | Marty Ryba <ryba@@ll.mit.edu> | |
2310 | @item | |
2311 | Phil Williams <williams@@irc.chmcc.org> | |
2312 | @item | |
797c8ebc CD |
2313 | Phil Sterne <sterne@@dublin.llnl.gov> |
2314 | @end itemize | |
2315 | ||
a8e833f3 CD |
2316 | @noindent |
2317 | Thanks to everyone! | |
2318 | ||
797c8ebc CD |
2319 | @node Sources of Routine Info, Configuration Examples, Acknowledgement, Top |
2320 | @appendix Sources of Routine Info | |
2321 | ||
a8e833f3 | 2322 | @cindex Sources of routine information |
797c8ebc CD |
2323 | In @ref{Routine Info} and @ref{Completion} it was shown how IDLWAVE |
2324 | displays the calling sequence and keywords of routines, and how it | |
2325 | completes routine names and keywords. For these features to work, | |
2326 | IDLWAVE must know about the accessible routines. | |
2327 | ||
2328 | @menu | |
2329 | * Routine Definitions:: Where IDL Routines are defined. | |
a8e833f3 | 2330 | * Routine Information Sources:: So how does IDLWAVE know about... |
aea44e56 | 2331 | * Library Catalog:: Scanning the Libraries for Routine Info |
a8e833f3 CD |
2332 | * Load-Path Shadows:: Routines defined in several places |
2333 | * Documentation Scan:: Scanning the IDL Manuals | |
797c8ebc CD |
2334 | @end menu |
2335 | ||
2336 | @node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info | |
2337 | @section Routine Definitions | |
2338 | @cindex Routine definitions | |
a8e833f3 CD |
2339 | @cindex IDL variable @code{!PATH} |
2340 | @cindex @code{!PATH}, IDL variable | |
2341 | @cindex @code{CALL_EXTERNAL}, IDL routine | |
2342 | @cindex @code{LINKIMAGE}, IDL routine | |
2343 | @cindex External routines | |
797c8ebc CD |
2344 | |
2345 | Routines which can be used in an IDL program can be defined in several | |
2346 | places: | |
2347 | ||
2348 | @enumerate | |
2349 | @item | |
a8e833f3 CD |
2350 | @emph{Builtin routines} are defined inside IDL itself. The source |
2351 | code of such routines is not accessible to the user. | |
797c8ebc CD |
2352 | @item |
2353 | Routines @emph{part of the current program} are defined in a file which | |
a8e833f3 CD |
2354 | is explicitly compiled by the user. This file may or may not be located |
2355 | on the IDL search path. | |
797c8ebc CD |
2356 | @item |
2357 | @emph{Library routines} are defined in special files which are located | |
2358 | somewhere on IDL's search path. When a library routine is called for | |
2359 | the first time, IDL will find the source file and compile it | |
a8e833f3 | 2360 | dynamically. |
797c8ebc CD |
2361 | @item |
2362 | External routines written in other languages (like Fortran or C) can be | |
2363 | called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, | |
2364 | or included as dynamically loaded modules (DLMs). Currently IDLWAVE | |
2365 | cannot provide routine info and completion for external | |
a8e833f3 | 2366 | routines. |
797c8ebc CD |
2367 | @end enumerate |
2368 | ||
aea44e56 | 2369 | @node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info |
797c8ebc CD |
2370 | @section Routine Information Sources |
2371 | @cindex Routine info sources | |
a8e833f3 CD |
2372 | @cindex Builtin list of routines |
2373 | @cindex Updating routine info | |
2374 | @cindex Scanning buffers for routine info | |
2375 | @cindex Buffers, scanning for routine info | |
2376 | @cindex Shell, querying for routine info | |
797c8ebc CD |
2377 | |
2378 | In oder to know about as many routines as possible, IDLWAVE will do the | |
a8e833f3 | 2379 | following to collect information: |
797c8ebc CD |
2380 | |
2381 | @enumerate | |
2382 | ||
2383 | @item | |
2384 | It has a @emph{builtin list} with the properties of the builtin IDL | |
2385 | routines. IDLWAVE @value{VERSION} is distributed with a list of | |
2386 | @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords, | |
2387 | reflecting IDL version @value{IDLVERSION}. This list has been created | |
2388 | by scanning the IDL manuals and is stored in the file | |
a8e833f3 CD |
2389 | @file{idlw-rinfo.el}. @xref{Documentation Scan}, for |
2390 | information how to regenerate this file for new versions of IDL. | |
797c8ebc | 2391 | |
a8e833f3 | 2392 | @item |
797c8ebc CD |
2393 | It @emph{scans} all @emph{buffers} of the current Emacs session for |
2394 | routine definitions. This is done automatically when routine | |
a8e833f3 CD |
2395 | information or completion is first requested by the user. Each new |
2396 | buffer and each buffer which is saved after making changes is also | |
2397 | scanned. The command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) | |
2398 | can be used at any time to rescan all buffers. | |
797c8ebc CD |
2399 | |
2400 | @item | |
2401 | If you have an IDLWAVE-Shell running as inferior process of the current | |
2402 | Emacs session, IDLWAVE will @emph{query the shell} for compiled routines | |
2403 | and their arguments. This happens automatically when routine | |
a8e833f3 CD |
2404 | information or completion is first requested by the user, and each time |
2405 | an Emacs buffer is compiled with @kbd{C-c C-d C-c}. The command | |
797c8ebc | 2406 | @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used to ask |
a8e833f3 | 2407 | the shell again at any time. |
797c8ebc CD |
2408 | |
2409 | @item | |
2410 | IDLWAVE can scan all or selected library files and store the result in a | |
2411 | file which will be automatically loaded just like | |
aea44e56 | 2412 | @file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to |
a8e833f3 | 2413 | scan library files. |
797c8ebc CD |
2414 | @end enumerate |
2415 | ||
2416 | @defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) | |
2417 | Non-@code{nil} means, scan all buffers for IDL programs when updating | |
a8e833f3 | 2418 | info. |
797c8ebc CD |
2419 | @end defopt |
2420 | ||
2421 | @defopt idlwave-query-shell-for-routine-info (@code{t}) | |
2422 | Non-@code{nil} means query the shell for info about compiled routines. | |
2423 | @end defopt | |
2424 | ||
a8e833f3 CD |
2425 | @defopt idlwave-auto-routine-info-updates |
2426 | Controls under what circumstances routine info is updated automatically. | |
2427 | @end defopt | |
797c8ebc | 2428 | |
aea44e56 CD |
2429 | @node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info |
2430 | @section Library Catalog | |
797c8ebc | 2431 | @cindex Library scan |
aea44e56 | 2432 | @cindex Library catalog |
797c8ebc | 2433 | @cindex IDL library routine info |
a8e833f3 CD |
2434 | @cindex Windows |
2435 | @cindex MacOS | |
2436 | @cindex Unix | |
2437 | @cindex IDL variable @code{!DIR} | |
2438 | @cindex @code{!DIR}, IDL variable | |
2439 | ||
797c8ebc CD |
2440 | |
2441 | IDLWAVE can extract routine information from library modules and store | |
2442 | that information in a file. To do this, the variable | |
2443 | @code{idlwave-libinfo-file} needs to contain the path to a file in an | |
a8e833f3 CD |
2444 | existing directory (the default is @code{"~/.idlcat.el"}). Since the |
2445 | file will contain lisp code, its name should end in @file{.el}. Under | |
2446 | Windows and MacOS, you also need to specify the search path for IDL | |
2447 | library files in the variable @code{idlwave-library-path}, and the | |
2448 | location of the IDL directory (the value of the @code{!DIR} system | |
2449 | variable) in the variable @code{idlwave-system-directory}. Under UNIX, | |
2450 | these values will be automatically inferred from an IDLWAVE | |
2451 | shell. | |
797c8ebc CD |
2452 | |
2453 | The command @kbd{M-x idlwave-create-libinfo-file} can then be used to | |
2454 | scan library files. It brings up a widget in which you can select some | |
a8e833f3 CD |
2455 | or all directories on the search path. If you only want to have routine |
2456 | and completion info of some libraries, it is sufficient to scan those | |
2457 | directories. However, if you want IDLWAVE to detect possible name | |
2458 | conflicts with routines defined in other libraries, the whole pass | |
2459 | should be scanned. | |
2460 | ||
2461 | After selecting directories, click on the @w{@samp{[Scan & Save]}} | |
2462 | button in the widget to scan all files in the selected directories and | |
797c8ebc CD |
2463 | write the resulting routine information into the file |
2464 | @code{idlwave-libinfo-file}. In order to update the library information | |
2465 | from the same directories, call the command | |
2466 | @code{idlwave-update-routine-info} with a double prefix argument: | |
a8e833f3 | 2467 | @w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously |
797c8ebc | 2468 | selected directories, write an updated version of the libinfo file and |
a8e833f3 | 2469 | rebuild IDLWAVEs internal lists. |
797c8ebc CD |
2470 | |
2471 | A note of caution: Depending on your local installation, the IDL | |
2472 | library can be very large. Parsing it for routine information will take | |
2473 | time and loading this information into Emacs can require a | |
a8e833f3 CD |
2474 | significant amount of memory. However, having this information |
2475 | available will be a great help. | |
797c8ebc CD |
2476 | |
2477 | @defopt idlwave-libinfo-file | |
2478 | File for routine information of the IDL library. | |
2479 | @end defopt | |
2480 | ||
2481 | @defopt idlwave-library-path | |
2482 | IDL library path for Windows and MacOS. Not needed under Unix. | |
2483 | @end defopt | |
2484 | ||
a8e833f3 CD |
2485 | @defopt idlwave-system-directory |
2486 | The IDL system directory for Windows and MacOS. Not needed under UNIX. | |
2487 | @end defopt | |
2488 | ||
2489 | @defopt idlwave-special-lib-alist | |
2490 | Alist of regular expressions matching special library directories. | |
2491 | @end defopt | |
2492 | ||
aea44e56 | 2493 | @node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info |
a8e833f3 CD |
2494 | @section Load-Path Shadows |
2495 | @cindex Load-path shadows | |
2496 | @cindex Shadows, load-path | |
2497 | @cindex Duplicate routines | |
2498 | @cindex Multiply defined routines | |
2499 | @cindex Routine definitions, multiple | |
2500 | @cindex Application, testing for shadowing | |
2501 | @cindex Buffer, testing for shadowing | |
2502 | ||
2503 | IDLWAVE can compile a list of routines which are defined in several | |
2504 | different files. Since one definition will hide (shadow) the others | |
2505 | depending on which file is compiled first, such multiple definitions are | |
2506 | called "load-path shadows". IDLWAVE has several routines to scan for | |
aea44e56 | 2507 | load path shadows. The output is placed into the special buffer |
a8e833f3 | 2508 | @file{*Shadows*}. The format of the output is identical to the source |
aea44e56 CD |
2509 | section of the routine info buffer (@pxref{Routine Info}). The |
2510 | different definitions of a routine are listed in the sequence of | |
2511 | @emph{likelyhood of use}. So the first entry will be most likely the | |
2512 | one you'll get if an unsuspecting command uses that routine. Before | |
2513 | listing shadows, you should make sure that routine info is up-to-date by | |
2514 | pressing @kbd{C-c C-i}. Here are the different routines: | |
a8e833f3 CD |
2515 | |
2516 | @table @asis | |
2517 | @item @kbd{M-x idlwave-list-buffer-load-path-shadows} | |
2518 | This commands checks the names of all routines defined in the current | |
2519 | buffer for shadowing conflicts with other routines accessible to | |
2520 | IDLWAVE. The command also has a key binding: @kbd{C-c C-b} | |
2521 | @item @kbd{M-x idlwave-list-shell-load-path-shadows}. | |
2522 | Checks all routines compiled under the shell for shadowing. This is | |
2523 | very useful when you have written a complete application. Just compile | |
2524 | the application, use @code{RESOLVE_ALL} to compile any routines used by | |
2525 | your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and | |
2526 | then check for shadowing. | |
2527 | @item @kbd{M-x idlwave-list-all-load-path-shadows} | |
aea44e56 | 2528 | This command checks all routines accessible to IDLWAVE for conflicts. |
a8e833f3 CD |
2529 | @end table |
2530 | ||
2531 | For these commands to work properly you should have scanned the entire | |
2532 | load path, not just selected directories. Also, IDLWAVE should be able to | |
2533 | distinguish between the system library files (normally installed in | |
2534 | @file{/usr/local/rsi/idl/lib}) and any site specific or user specific | |
2535 | files. Therefore, such local files should not be installed | |
2536 | inside the @file{lib} directory of the IDL directory. This is of course | |
2537 | also advisable for many other reasons. | |
2538 | ||
2539 | @cindex Windows | |
2540 | @cindex MacOS | |
2541 | @cindex IDL variable @code{!DIR} | |
2542 | @cindex @code{!DIR}, IDL variable | |
2543 | Users of Windows and MacOS also must set the variable | |
2544 | @code{idlwave-system-directory} to the value of the @code{!DIR} system | |
2545 | variable in IDL. IDLWAVE appends @file{lib} to the value of this | |
2546 | variable and assumes that all files found on that path are system | |
2547 | routines. | |
2548 | ||
2549 | Another way to find out if a specific routine has multiple definitions | |
2550 | on the load path is routine info display (@pxref{Routine Info}). | |
2551 | ||
2552 | @node Documentation Scan, , Load-Path Shadows, Sources of Routine Info | |
2553 | @section Documentation Scan | |
797c8ebc | 2554 | @cindex @file{get_rinfo} |
c142ce81 | 2555 | @cindex @file{idlw-rinfo.el} |
a8e833f3 CD |
2556 | @cindex @file{idlw-help.txt} |
2557 | @cindex @file{idlw-help.el} | |
2558 | @cindex Scanning the documentation | |
c142ce81 | 2559 | @cindex Perl program, to create @file{idlw-rinfo.el} |
797c8ebc | 2560 | |
a8e833f3 CD |
2561 | IDLWAVE derives it knowledge about system routines from the IDL |
2562 | manuals. The file @file{idlw-rinfo.el} contains the routine information | |
2563 | for the IDL system routines. The Online Help feature of IDLWAVE | |
2564 | requires ASCII versions of some IDL manuals to be available in a | |
2565 | specific format (@file{idlw-help.txt}), along with an Emacs-Lisp file | |
2566 | @file{idlw-help.el} with supporting code and pointers to the ASCII file. | |
2567 | ||
2568 | All 3 files can be derived from the IDL documentation. If you are | |
2569 | lucky, the maintainer of IDLWAVE will always have access to the newest | |
2570 | version of IDL and provide updates. The IDLWAVE distribution also | |
2571 | contains the Perl program @file{get_rinfo} which constructs these files | |
2572 | by scanning selected files from the IDL documentation. Instructions on | |
2573 | how to use @file{get_rinfo} are in the program itself. | |
797c8ebc CD |
2574 | |
2575 | @node Configuration Examples, Index, Sources of Routine Info, Top | |
2576 | @appendix Configuration Examples | |
2577 | @cindex Configuration examples | |
2578 | @cindex Example configuration | |
a8e833f3 CD |
2579 | @cindex @file{.emacs} |
2580 | @cindex Default settings, of options | |
2581 | @cindex Interview, with the maintainer | |
797c8ebc CD |
2582 | |
2583 | @noindent | |
2584 | @b{Question:} So now you have all these complicated configuration | |
2585 | options in your package, but which ones do @emph{you} as the maintainer | |
2586 | actually set in your own configuration? | |
2587 | ||
2588 | @noindent | |
ea442c62 CD |
2589 | @b{Answer:} Hardly any. As the maintainer, I set the default of most |
2590 | options to what I think is best. However, the default settings do not | |
2591 | turn on features which | |
a8e833f3 | 2592 | |
797c8ebc CD |
2593 | @itemize @minus |
2594 | @item | |
2595 | are not self-evident (i.e. too magic) when used by an unsuspecting user | |
2596 | @item | |
2597 | are too intrusive | |
2598 | @item | |
2599 | will not work properly on all Emacs installations out there | |
2600 | @item | |
a8e833f3 | 2601 | break with widely used standards. |
797c8ebc CD |
2602 | @end itemize |
2603 | ||
ea442c62 CD |
2604 | @noindent To see what I mean, here is the @emph{entire} configuration I |
2605 | have in my @file{.emacs}: | |
797c8ebc CD |
2606 | |
2607 | @lisp | |
aea44e56 | 2608 | (setq idlwave-shell-debug-modifiers '(control shift) |
797c8ebc CD |
2609 | idlwave-store-inquired-class t |
2610 | idlwave-shell-automatic-start t | |
a8e833f3 CD |
2611 | idlwave-main-block-indent 2 |
2612 | idlwave-help-dir "~/lib/emacs/idlwave" | |
2613 | idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib") | |
2614 | ("/jhuapl/" . "JHUAPL-Lib") | |
2615 | ("/dominik/lib/idl/" . "MyLib"))) | |
797c8ebc CD |
2616 | @end lisp |
2617 | ||
2618 | However, if you are an Emacs power-user and want IDLWAVE to work | |
2619 | completely differently, the options allow you to change almost every | |
2620 | aspect of it. Here is an example of a much more extensive configuration | |
2621 | of IDLWAVE. To say it again - this is not what I recommend, but the | |
a8e833f3 | 2622 | user is King! |
797c8ebc CD |
2623 | |
2624 | @example | |
2625 | ;;; Settings for IDLWAVE mode | |
2626 | ||
2627 | (setq idlwave-block-indent 3) ; Indentation settings | |
2628 | (setq idlwave-main-block-indent 3) | |
2629 | (setq idlwave-end-offset -3) | |
2630 | (setq idlwave-continuation-indent 1) | |
2631 | (setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" | |
2632 | ; anchored at start of line. | |
2633 | (setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> | |
2634 | (setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' | |
2635 | (setq idlwave-expand-generic-end t) ; convert END to ENDIF etc... | |
2636 | (setq idlwave-reserved-word-upcase t) ; Make reserved words upper case | |
2637 | ; (with abbrevs only) | |
2638 | (setq idlwave-abbrev-change-case nil) ; Don't force case of expansions | |
2639 | (setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill | |
2640 | (setq idlwave-show-block nil) ; Turn off blinking to begin | |
2641 | (setq idlwave-abbrev-move t) ; Allow abbrevs to move point | |
2642 | ||
2643 | ;; Some setting can only be done from a mode hook. Here is an example: | |
2644 | ||
2645 | (add-hook 'idlwave-mode-hook | |
2646 | (lambda () | |
2647 | (setq abbrev-mode 1) ; Turn on abbrevs (-1 for off) | |
2648 | (setq case-fold-search nil) ; Make searches case sensitive | |
2649 | ;; Run other functions here | |
2650 | (font-lock-mode 1) ; Turn on font-lock mode | |
2651 | (idlwave-auto-fill-mode 0) ; Turn off auto filling | |
2652 | ;; | |
c23bc7a4 | 2653 | ;; Pad with 1 space (if -n is used then make the |
797c8ebc CD |
2654 | ;; padding a minimum of n spaces.) The defaults use -1 |
2655 | ;; instead of 1. | |
2656 | (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1)) | |
2657 | (idlwave-action-and-binding "<" '(idlwave-surround 1 1)) | |
2658 | (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-))) | |
2659 | (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) | |
2660 | ;; | |
2661 | ;; Only pad after comma and with exactly 1 space | |
2662 | (idlwave-action-and-binding "," '(idlwave-surround nil 1)) | |
ea442c62 | 2663 | (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) |
797c8ebc | 2664 | ;; |
ea442c62 CD |
2665 | ;; Pad only after `->', remove any space before the arrow |
2666 | (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2)) | |
2667 | ;;; | |
797c8ebc CD |
2668 | ;; Set some personal bindings |
2669 | ;; (In this case, makes `,' have the normal self-insert behavior.) | |
2670 | (local-set-key "," 'self-insert-command) | |
2671 | ;; Create a newline, indenting the original and new line. | |
2672 | ;; A similar function that does _not_ reindent the original | |
2673 | ;; line is on "\C-j" (The default for emacs programming modes). | |
2674 | (local-set-key "\n" 'idlwave-newline) | |
2675 | ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. | |
2676 | )) | |
2677 | ||
2678 | ;;; Settings for IDLWAVE SHELL mode | |
2679 | ||
2680 | (setq idlwave-shell-overlay-arrow "=>") ; default is ">" | |
2681 | (setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame | |
2682 | (setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> " | |
2683 | (setq idlwave-shell-explicit-file-name "wave") | |
2684 | (setq idlwave-shell-process-name "wave") | |
797c8ebc CD |
2685 | (setq idlwave-shell-use-toolbar nil) ; No toolbar |
2686 | @end example | |
2687 | ||
2688 | @node Index, , Configuration Examples, Top | |
2689 | @unnumbered Index | |
2690 | @printindex cp | |
2691 | ||
797c8ebc CD |
2692 | @bye |
2693 |