Mercurial > emacs
comparison man/idlwave.texi @ 26960:733eba22afe2
TeXInfo documentation of the IDLWAVE mode and shell
author | Carsten Dominik <dominik@science.uva.nl> |
---|---|
date | Mon, 20 Dec 1999 11:18:31 +0000 |
parents | |
children | eb645a473bf8 |
comparison
equal
deleted
inserted
replaced
26959:40d1a10917b8 | 26960:733eba22afe2 |
---|---|
1 \input texinfo @c -*-texinfo-*- | |
2 @c %**start of header | |
3 @setfilename ../info/idlwave | |
4 @settitle IDLWAVE User Manual | |
5 @dircategory Editors | |
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 | |
12 @set VERSION 3.11 | |
13 @set EDITION 1.7 | |
14 @set IDLVERSION 5.3 | |
15 @set NSYSROUTINES 1226 | |
16 @set NSYSKEYWORDS 5230 | |
17 @set DATE December 1999 | |
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 | |
22 @c %**end of header | |
23 @finalout | |
24 | |
25 @ifinfo | |
26 This file documents IDLWAVE, a major mode for editing IDL and | |
27 WAVE/CL files with Emacs. It also implements a shell for running IDL as | |
28 a subprocess.@refill | |
29 | |
30 This is edition @value{EDITION} of the IDLWAVE User Manual for | |
31 IDLWAVE @value{VERSION}@refill | |
32 | |
33 Copyright (c) 1999 Free Software Foundation, Inc. | |
34 | |
35 Permission is granted to make and distribute verbatim | |
36 copies of this manual provided the copyright notice and | |
37 this permission notice are preserved on all copies. | |
38 | |
39 @ignore | |
40 Permission is granted to process this file through TeX | |
41 and print the results, provided the printed document | |
42 carries a copying permission notice identical to this | |
43 one except for the removal of this paragraph (this | |
44 paragraph not being relevant to the printed manual). | |
45 | |
46 @end ignore | |
47 Permission is granted to copy and distribute modified | |
48 versions of this manual under the conditions for | |
49 verbatim copying, provided that the entire resulting | |
50 derived work is distributed under the terms of a permission | |
51 notice identical to this one. | |
52 | |
53 Permission is granted to copy and distribute | |
54 translations of this manual into another language, | |
55 under the above conditions for modified versions, | |
56 except that this permission notice may be stated in a | |
57 translation approved by the Free Software Foundation. | |
58 @end ifinfo | |
59 | |
60 @titlepage | |
61 @title IDLWAVE User Manual | |
62 @subtitle Major Emacs mode and shell for IDL and WAVE/CL files | |
63 @subtitle Edition @value{EDITION}, @value{DATE} | |
64 | |
65 @author by Carsten Dominik | |
66 @page | |
67 Copyright @copyright{} 1999 Free Software Foundation, Inc. | |
68 | |
69 @sp 2 | |
70 This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for | |
71 IDLWAVE version @value{VERSION}, @value{DATE}.@refill | |
72 | |
73 @sp 2 | |
74 | |
75 Permission is granted to make and distribute verbatim | |
76 copies of this manual provided the copyright notice and | |
77 this permission notice are preserved on all copies. | |
78 | |
79 Permission is granted to copy and distribute modified | |
80 versions of this manual under the conditions for | |
81 verbatim copying, provided that the entire resulting | |
82 derive work is distributed under the terms of a permission | |
83 notice identical to this one. | |
84 | |
85 Permission is granted to copy and distribute | |
86 translations of this manual into another language, | |
87 under the above conditions for modified versions, | |
88 except that this permission notice may be stated in a | |
89 translation approved by the Free Software Foundation. | |
90 | |
91 @end titlepage | |
92 @page | |
93 | |
94 @ifinfo | |
95 @node Top, Introduction, (dir), (dir) | |
96 | |
97 IDLWAVE is a package to support editing command files for the | |
98 Interactive Data Language (IDL), and for running IDL as an inferior | |
99 shell. @refill | |
100 | |
101 @end ifinfo | |
102 | |
103 @menu | |
104 * Introduction:: What IDLWAVE is and what not | |
105 * IDLWAVE in a Nutshell:: One page quick-start guide | |
106 * The IDLWAVE Major Mode:: The mode to edit IDL programs | |
107 * The IDLWAVE Shell:: The mode to run IDL as inferior program | |
108 * Installation:: How to Install or Upgrade | |
109 * Acknowledgement:: Who helped | |
110 * Sources of Routine Info:: How does IDLWAVE know about routine XYZ | |
111 * Configuration Examples:: The user is king... | |
112 * Index:: Fast access | |
113 | |
114 @detailmenu | |
115 | |
116 --- The Detailed Node Listing --- | |
117 | |
118 The IDLWAVE Major Mode | |
119 | |
120 * Code Formatting:: Making code look nice | |
121 * Routine Info:: Calling Sequences and Keywords | |
122 * Completion:: Completing routine names and Keywords | |
123 * Code Templates:: Abbreviations for frequent constructs | |
124 * Actions:: Changing case, Padding, End checking | |
125 * Doc Header:: Inserting a standard header | |
126 * Motion Commands:: Moving through the structure of a program | |
127 * Misc Options:: Things that fit nowhere else | |
128 | |
129 Code Formatting | |
130 | |
131 * Code Indentation:: Reflecting the logical structure | |
132 * Comment Indentation:: Special indentation for comment lines | |
133 * Continuation Lines:: Splitting statements over lines | |
134 * Syntax Highlighting:: Font-lock support | |
135 | |
136 Actions | |
137 | |
138 * Block Boundary Check:: Is the END correct | |
139 * Padding Operators:: Enforcing space around `=' etc | |
140 * Case Changes:: Enforcing upper case keywords | |
141 | |
142 The IDLWAVE Shell | |
143 | |
144 * Starting the Shell:: How to launch IDL as a subprocess | |
145 * Using the Shell:: Interactively working with the Shell | |
146 * Debugging IDL Programs:: Compilation/Debugging | |
147 | |
148 Debugging IDL Programs | |
149 | |
150 * Compiling Programs:: Compiling buffers under the shell | |
151 * Breakpoints and Stepping:: Deciding where to stop and look | |
152 * Examining Variables:: What is the value now? | |
153 | |
154 Installation | |
155 | |
156 * Installing IDLWAVE:: How to install the distribution | |
157 * Upgrading from idl.el:: Necessary configuration changes | |
158 | |
159 Sources of Routine Info | |
160 | |
161 * Routine Definitions:: Where IDL Routines are defined. | |
162 * Routine Information Sources:: So how does IDLWAVE know about... | |
163 * Library Scan:: Scanning the Libraries for Routine Info | |
164 * Updating idlwave-rinfo.el:: Scanning the Reference Manual | |
165 @end detailmenu | |
166 @end menu | |
167 | |
168 @node Introduction, IDLWAVE in a Nutshell, Top, Top | |
169 @chapter Introduction | |
170 @cindex Introduction | |
171 @cindex CORBA (Common Object Request Broker Architecture) | |
172 @cindex cc-mode.el | |
173 @cindex Feature overview | |
174 | |
175 IDLWAVE is a package to support editing command files for the | |
176 Interactive Data Language (IDL), and for running IDL as an inferior | |
177 shell. It also can be used for WAVE/CL command files, but the support | |
178 for these is limited. Note that this package has nothing to do with the | |
179 Interface Definition Language as part of the Common Object Request | |
180 Broker Architecture (CORBA). | |
181 | |
182 IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el} | |
183 files written by Chris Chase. The modes and files had to be renamed | |
184 because of a name space conflict with CORBAs @code{idl-mode}, defined in | |
185 Emacs in the file @file{cc-mode.el}. If you have been using the old | |
186 files, check @ref{Upgrading from idl.el} for information on how to | |
187 switch. | |
188 | |
189 IDLWAVE consists of two parts: A major mode for editing command files | |
190 (@code{idlwave-mode}) and a mode to allow running the IDL program as an | |
191 inferior shell (@code{idlwave-shell-mode}). Both modes work closely | |
192 together and form a complete development environment.@refill | |
193 | |
194 Here is a brief summary of what IDLWAVE does. | |
195 | |
196 @itemize @bullet | |
197 @item | |
198 Code indentation and formatting. | |
199 @item | |
200 Font-lock support on three levels. | |
201 @item | |
202 Display of calling sequence and keywords of more than 1000 IDL | |
203 routines. | |
204 @item | |
205 Context sensitive completion of routine names and keywords. | |
206 @item | |
207 Insertion of code templates. | |
208 @item | |
209 Actions to enforce coding standards during typing. | |
210 @item | |
211 Block structure check. | |
212 @item | |
213 Documentation support. | |
214 @item | |
215 Running IDL as inferior process. | |
216 @item | |
217 Shell with history search, command line editing and completion. | |
218 @item | |
219 Compilation, execution and debugging of programs directly from the source | |
220 buffer. | |
221 @item | |
222 Examining expressions with a mouse click. | |
223 @end itemize | |
224 | |
225 @ifnottex | |
226 @cindex Screenshots | |
227 Here are a number of screenshots showing IDLWAVE in action. | |
228 @itemize @bullet | |
229 @item | |
230 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/font-lock.gif, | |
231 XEmacs 21.1 with formatted and fontified code} | |
232 @item | |
233 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/rinfo.gif, | |
234 XEmacs 21.1 displaying routine info} | |
235 @item | |
236 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/complete.gif, | |
237 XEmacs 21.1 completing a keyword} | |
238 @item | |
239 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/shell.gif, | |
240 XEmacs 21.1 with debugging toolbar; execution stopped at a breakpoint} | |
241 @end itemize | |
242 @end ifnottex | |
243 | |
244 In this manual, each section contains a list of user options related to | |
245 the subject. Don't be confused by the shear number of options available | |
246 -- in most cases the default settings are just fine. The variables are | |
247 listed here to make sure you know where to look if you want to change | |
248 things. For a full description of what a particular variable does and | |
249 how to configure it, see the documentation string of that variable. | |
250 Some configuration examples are also given in the appendix. | |
251 | |
252 @node IDLWAVE in a Nutshell, The IDLWAVE Major Mode, Introduction, Top | |
253 @chapter IDLWAVE in a Nutshell | |
254 @cindex Quick-Start | |
255 @cindex Getting Started | |
256 @cindex IDLWAVE in a Nutshell | |
257 @cindex Nutshell, IDLWAVE in a | |
258 | |
259 If you are in a hurry, here is some quick-start information. | |
260 | |
261 @subheading Editing IDL Programs | |
262 | |
263 @multitable @columnfractions .15 .85 | |
264 @item @key{TAB} | |
265 @tab Indent the current line relative to context. | |
266 @item @kbd{M-C-\} | |
267 @tab Re-indent all lines in the current region. | |
268 @item @kbd{M-@key{RET}} | |
269 @tab Start a continuation line. Or split the current line at point. | |
270 @item @kbd{M-q} | |
271 @tab Fill the current comment paragraph. | |
272 @item @kbd{C-c ?} | |
273 @tab Display calling sequence, keywords of the procedure/function call | |
274 at point. | |
275 @item @kbd{M-@key{TAB}} | |
276 @tab Complete a procedure name, function name or keyword in the buffer. | |
277 @item @kbd{C-c C-i} | |
278 @tab Update IDLWAVE's knowledge about functions and procedures. | |
279 @item @kbd{C-c C-v} | |
280 @tab Find the source code of a procedure/function. | |
281 @item @kbd{C-c C-h} | |
282 @tab Insert a standard documentation header. | |
283 @item @kbd{C-c C-m} | |
284 @tab Insert a new timestamp and history item in the documentation header. | |
285 @end multitable | |
286 | |
287 @subheading Running the IDLWAVE Shell, Debugging Programs | |
288 | |
289 @multitable @columnfractions .15 .85 | |
290 @item @kbd{C-c C-s} | |
291 @tab Start IDL as a subprocess and/or switch to the interaction buffer. | |
292 @item @kbd{C-u C-c C-s} | |
293 @tab Start the shell in a separate frame. | |
294 @item @kbd{M-p} | |
295 @tab Cycle back through IDL command history matching command line input. | |
296 @item @kbd{M-n} | |
297 @tab Cycle forward. | |
298 @item @kbd{M-@key{TAB}} | |
299 @tab Complete a procedure name, function name or keyword in the shell buffer. | |
300 @item @kbd{C-c C-d C-c} | |
301 @tab Save and compile the source file in the current buffer. | |
302 @item @kbd{C-c C-d C-x} | |
303 @tab Goto next syntax error. | |
304 @item @kbd{C-c C-d C-b} | |
305 @tab Set a breakpoint at the current source line. | |
306 @item @kbd{C-c C-d C-d} | |
307 @tab Clear the current breakpoint. | |
308 @item @kbd{C-c C-d C-p} | |
309 @tab Ask IDL to print the value of the expression near point. | |
310 @end multitable | |
311 | |
312 @subheading Commonly used Settings in @file{.emacs} | |
313 @lisp | |
314 ;; Change the indentation preferences | |
315 (setq idlwave-main-block-indent 2 ; default 0 | |
316 idlwave-block-indent 2 ; default 4 | |
317 idlwave-end-offset -2) ; default -4 | |
318 | |
319 ;; Syntax Highlighting | |
320 (add-hook 'idlwave-mode-hook 'turn-on-font-lock) | |
321 ;; Automatically expand END to ENDIF, ENDELSE, ... | |
322 (setq idlwave-expand-generic-end t) | |
323 | |
324 ;; Automatically start the shell when needed | |
325 (setq idlwave-shell-automatic-start t) | |
326 ;; Always use a separate frame for the shell buffer | |
327 (setq idlwave-shell-use-dedicated-frame t) | |
328 | |
329 ;; Specify a file where library info can be stored. | |
330 (setq idlwave-libinfo-file "~/idlinfo.el") | |
331 @end lisp | |
332 | |
333 @node The IDLWAVE Major Mode, The IDLWAVE Shell, IDLWAVE in a Nutshell, Top | |
334 @chapter The IDLWAVE Major Mode | |
335 @cindex IDLWAVE major mode | |
336 @cindex Major mode, @code{idlwave-mode} | |
337 | |
338 The IDLWAVE major mode supports editing IDL and WAVE/CL command files. | |
339 In this chapter we describe the main features of the mode and how to | |
340 customize them. | |
341 | |
342 @menu | |
343 * Code Formatting:: Making code look nice | |
344 * Routine Info:: Calling Sequences and Keywords | |
345 * Completion:: Completing routine names and Keywords | |
346 * Code Templates:: Abbreviations for frequent constructs | |
347 * Actions:: Changing case, Padding, End checking | |
348 * Doc Header:: Inserting a standard header | |
349 * Motion Commands:: Moving through the structure of a program | |
350 * Misc Options:: Things that fit nowhere else | |
351 @end menu | |
352 | |
353 @node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode | |
354 @section Code Formatting | |
355 @cindex Code formatting | |
356 @cindex Formatting, of code | |
357 | |
358 @menu | |
359 * Code Indentation:: Reflecting the logical structure | |
360 * Comment Indentation:: Special indentation for comment lines | |
361 * Continuation Lines:: Splitting statements over lines | |
362 * Syntax Highlighting:: Font-lock support | |
363 @end menu | |
364 | |
365 @node Code Indentation, Comment Indentation, Code Formatting, Code Formatting | |
366 @subsection Code Indentation | |
367 @cindex Code indentation | |
368 @cindex Indentation | |
369 | |
370 Like all Emacs programming modes, IDLWAVE performs code indentation. | |
371 The @key{TAB} key indents the current line relative to context. | |
372 @key{LFD} insert a newline and indents the new line. The indentation is | |
373 governed by a number of variables. | |
374 | |
375 @cindex Foreign code, adapting | |
376 @cindex Indentation, of foreign code | |
377 To re-indent a larger portion of code (e.g. when working with foreign code | |
378 written with different conventions), use @kbd{M-C-\} | |
379 (@code{indent-region}) after marking the relevant code. Useful marking | |
380 commands are @kbd{C-x h} (the entire file) or @kbd{M-C-h} (the | |
381 current subprogram). @xref{Actions}, for information how to impose | |
382 additional formatting conventions on foreign code. | |
383 | |
384 @defopt idlwave-main-block-indent (@code{0}) | |
385 Extra indentation for the main block of code. That is the block between | |
386 the FUNCTION/PRO statement and the END statement for that program | |
387 unit.@refill | |
388 @end defopt | |
389 | |
390 @defopt idlwave-block-indent (@code{4}) | |
391 Extra indentation applied to block lines. If you change this, you | |
392 probably also want to change @code{idlwave-end-offset}.@refill | |
393 @end defopt | |
394 | |
395 @defopt idlwave-end-offset (@code{-4}) | |
396 Extra indentation applied to block END lines. A value equal to negative | |
397 @code{idlwave-block-indent} will make END lines line up with the block | |
398 BEGIN lines.@refill | |
399 @end defopt | |
400 | |
401 @defopt idlwave-continuation-indent (@code{2}) | |
402 Extra indentation applied to continuation lines and insided unbalanced | |
403 parenthesis.@refill | |
404 @end defopt | |
405 | |
406 @node Comment Indentation, Continuation Lines, Code Indentation, Code Formatting | |
407 @subsection Comment Indentation | |
408 @cindex Comment indentation | |
409 @cindex Hanging paragraphs | |
410 @cindex Paragraphs, filling | |
411 @cindex Paragraphs, hanging | |
412 | |
413 In IDL, lines starting with a @samp{;} are called @emph{comment lines}. | |
414 Comment lines are indented as follows: | |
415 | |
416 @multitable @columnfractions .1 .90 | |
417 @item @code{;;;} | |
418 @tab The indentation of lines starting with three semicolons remains | |
419 unchanged. | |
420 @item @code{;;} | |
421 @tab Lines starting with two semicolons are indented like the surrounding code. | |
422 @item @code{;} | |
423 @tab Lines starting with a single semicolon are indent to a minimum column. | |
424 @end multitable | |
425 | |
426 The indentation of comments starting in column 0 is never changed. | |
427 | |
428 @defopt idlwave-no-change-comment | |
429 The indentation of a comment that starts with this regular | |
430 expression will not be changed. | |
431 @end defopt | |
432 | |
433 @defopt idlwave-begin-line-comment | |
434 A comment anchored at the beginning of line. A comment matched by this | |
435 regular expression will not have its indentation changed.@refill | |
436 @end defopt | |
437 | |
438 @defopt idlwave-code-comment | |
439 A comment that starts with this regular expression on a line by itself | |
440 is indented as if it is a part of IDL code.@refill | |
441 @end defopt | |
442 | |
443 @node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting | |
444 @subsection Continuation Lines and Filling | |
445 @cindex Continuation lines | |
446 @cindex Line splitting | |
447 @cindex Splitting, of lines | |
448 @cindex Filling | |
449 @cindex @code{auto-fill-mode} | |
450 @cindex Hanging paragraphs | |
451 | |
452 In IDL, a newline character terminates a statement unless preceded by a | |
453 @samp{$}. If you would like to start a continuation line, use | |
454 @kbd{M-@key{RET}} which calls the command @code{idlwave-split-line}. It | |
455 inserts a @samp{$} to indicate that the following line is a continuation | |
456 of the current line, terminates the line with a newline and indents the | |
457 new line. The command @kbd{M-@key{RET}} can also be used in the middle | |
458 of a line to split the line at that point. When used inside a long | |
459 string constant, the string is split with the @samp{+} concatenation | |
460 operator. You could even use @code{auto-fill-mode} to automatically | |
461 break code lines into several lines while you type. For this, set the | |
462 variable @code{idlwave-fill-comment-line-only} to @code{nil} and turn on | |
463 @code{auto-fill-mode}. @code{auto-fill-mode} can be toggled with | |
464 @kbd{C-c C-a}. | |
465 | |
466 When filling comment paragraphs, IDLWAVE overloads the normal filling | |
467 functions and uses a function which creates hanging paragraphs as they | |
468 are customary in the IDL routine headers. When @code{auto-fill-mode} is | |
469 turned on, comments will be auto-filled. If the first line of a | |
470 paragraph is matched by @code{idlwave-hang-indent-regexp}, subsequent | |
471 lines are indented to after the position of this match, as in the | |
472 following example. | |
473 | |
474 @example | |
475 ; INPUTS | |
476 ; x - an array containing | |
477 ; lots of interesting numbers. | |
478 ; | |
479 ; y - another variable where | |
480 ; a hanging paragraph is used | |
481 ; to describe it. | |
482 @end example | |
483 | |
484 You also refill a comment paragraph with @kbd{M-q}. | |
485 | |
486 @defopt idlwave-fill-comment-line-only (@code{t}) | |
487 Non-@code{nil} means auto fill will only operate on comment lines. | |
488 @end defopt | |
489 | |
490 @defopt idlwave-auto-fill-split-string (@code{t}) | |
491 Non-@code{nil} means auto fill will split strings with the IDL @samp{+} | |
492 operator. | |
493 @end defopt | |
494 | |
495 @defopt idlwave-split-line-string (@code{t}) | |
496 Non-@code{nil} means @code{idlwave-split-line} will split strings with | |
497 @samp{+}. | |
498 @end defopt | |
499 | |
500 @defopt idlwave-hanging-indent | |
501 Non-@code{nil} means comment paragraphs are indented under the hanging | |
502 indent given by @code{idlwave-hang-indent-regexp} match in the first | |
503 line of the paragraph.@refill | |
504 @end defopt | |
505 | |
506 @defopt idlwave-hang-indent-regexp | |
507 Regular expression matching the position of the hanging indent | |
508 in the first line of a comment paragraph.@refill | |
509 @end defopt | |
510 | |
511 @defopt idlwave-use-last-hang-indent (@code{nil}) | |
512 Non-@code{nil} means use last match on line for | |
513 @code{idlwave-indent-regexp}.@refill | |
514 @end defopt | |
515 | |
516 @node Syntax Highlighting, , Continuation Lines, Code Formatting | |
517 @subsection Syntax Highlighting | |
518 @cindex Syntax highlighting | |
519 @cindex Font lock | |
520 | |
521 Highlighting of keywords, comments, strings etc. can be accomplished | |
522 with @code{font-lock}. To enable @code{font-lock} for IDL files, place | |
523 the following line into your @file{.emacs} (see | |
524 @ref{Configuration Examples})@refill | |
525 | |
526 @lisp | |
527 (add-hook 'idlwave-mode-hook 'turn-on-font-lock) | |
528 @end lisp | |
529 | |
530 IDLWAVE supports 3 levels of syntax highlighting. The variable | |
531 @code{font-lock-maximum-decoration} determines which level is selected. | |
532 | |
533 @defopt idlwave-default-font-lock-items | |
534 Items which should be fontified on the default fontification level | |
535 2.@refill | |
536 @end defopt | |
537 | |
538 @node Routine Info, Completion, Code Formatting, The IDLWAVE Major Mode | |
539 @section Routine Info | |
540 @cindex Routine info | |
541 | |
542 IDL defines more than one thousand procedures, functions and object | |
543 methods. This large command set makes it difficult to remember the | |
544 calling sequence and keywords of a command. IDLWAVE contains a list of | |
545 all builtin routines with calling sequences and keywords@footnote{This | |
546 list was created by scanning the IDL manual and might contain (very few) | |
547 errors. Please report any detected errors to the maintainer, so that | |
548 they can be fixed.}. It also scans Emacs buffers and library files for | |
549 routine definitions and queries the IDLWAVE-Shell for the properties of | |
550 modules currently compiled under the shell. When you have edited a | |
551 buffer or compiled additional routines under the shell, use @kbd{C-c | |
552 C-i} (@code{idlwave-update-routine-info}) to update IDLWAVE's idea about | |
553 these routines.@refill | |
554 | |
555 To display the information about a routine, press @kbd{C-c ?} which | |
556 calls the command @code{idlwave-routine-info}. When the current cursor | |
557 position is on the name or in the argument list of a procedure or | |
558 function, information will be displayed about the routine. For example, | |
559 consider the cursor positions in the following line | |
560 | |
561 @example | |
562 plot,x,alog(x+5*sin(x) + 2), | |
563 1 2 3 4 5 6 7 8 | |
564 @end example | |
565 | |
566 @cindex Object methods | |
567 On positions 1,2 and 8, information about the @samp{plot} procedure will | |
568 be shown. On positions 3,4, and 7, the @samp{alog} function will be | |
569 described, while positions 5 and 6 will select the @samp{sin} function. | |
570 When you ask for routine information about an object method, and the | |
571 method exists in several classes, IDLWAVE queries for the class of the | |
572 object. | |
573 | |
574 @cindex Calling sequences | |
575 @cindex Keywords of a routine | |
576 The description displayed contains the calling sequence, the list of | |
577 keywords and the origin of this information (@emph{system routine}, | |
578 @emph{library routine}, @emph{Emacs buffer}, or @emph{compiled | |
579 module}). It looks like this: | |
580 | |
581 @example | |
582 Usage: MAP_PROJ_INFO, iproj | |
583 Keywords: CIRCLE CURRENT CYLINDRICAL NAME UV_LIMITS WIDTH | |
584 Origin: buffer visiting /soft1/idl/lib/map_set.pro | |
585 @end example | |
586 | |
587 Some of the text in the @file{*Help*} buffer will be active (it | |
588 highlights when you move the mouse over it). Clicking with the middle | |
589 mouse button on any of the active fields will try to find the source file of | |
590 the routine and display it in another window. Another click on the same | |
591 line will switch back to the buffer from which @kbd{C-c ?} was | |
592 called. Clicking with the right mouse button on an active field will | |
593 search the IDL online help for this item.@refill | |
594 | |
595 @cindex Routine source file | |
596 @cindex Module source file | |
597 Another way to find the source file of a routine is the command @kbd{C-c | |
598 C-v} (@code{idlwave-find-module}). It asks for a module name, offering | |
599 the same default as @code{idlwave-routine-info} would have used. In the | |
600 minibuffer, specify a complete routine name (including the class part). | |
601 IDLWAVE will display the source file in another window.@refill | |
602 | |
603 @cindex @code{RESOLVE_ROUTINE} | |
604 @cindex Compiling library modules | |
605 @cindex Routines, resolving | |
606 @cindex Online help, for IDL routines | |
607 The two other commands that work with the routine at point need a | |
608 running IDLWAVE shell. The key sequence @kbd{M-?} calls the command | |
609 @code{idlwave-routine-info-from-idlhelp}. This sends the command line | |
610 @samp{ONLINE_HELP, '@var{routine_name}'} to IDL in order to display the | |
611 documentation of the routine in the IDL online documentation. The key | |
612 sequence @kbd{C-c =} calls the command @code{idlwave-resolve} and sends | |
613 the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL in order to | |
614 resolve (compile) it. | |
615 | |
616 @code{idlwave-resolve} is one way to get a library module within reach | |
617 of IDLWAVE's routine info collecting functions. A better way is to | |
618 prescan (parts of) the library (@pxref{Library Scan}). Routine info on | |
619 library modules will then be available without the need to compile the | |
620 modules first, and even without a running shell. | |
621 | |
622 @xref{Sources of Routine Info}, for in-depth information where IDLWAVE | |
623 collects data about routines, and how to update this information. | |
624 | |
625 @defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) | |
626 Non-@code{nil} means, scan all buffers for IDL programs when updating | |
627 info. When this variable is @code{nil}, it only parses the current | |
628 buffer.@refill | |
629 @end defopt | |
630 | |
631 @defopt idlwave-query-shell-for-routine-info (@code{t}) | |
632 Non-@code{nil} means query the shell for info about compiled routines. | |
633 @end defopt | |
634 | |
635 @defopt idlwave-resize-routine-help-window (@code{t}) | |
636 Non-@code{nil} means, resize the Routine-info @file{*Help*} window to | |
637 fit the content.@refill | |
638 @end defopt | |
639 | |
640 | |
641 @node Completion, Code Templates, Routine Info, The IDLWAVE Major Mode | |
642 @section Completion | |
643 @cindex Completion | |
644 | |
645 IDLWAVE offers completion for routine names and keywords. As in many | |
646 programming modes, completion is bound to @kbd{M-@key{TAB}}. | |
647 Completion uses the same internal information as routine info, | |
648 so in order to update IDLWAVE's idea about your own routines after you | |
649 have edited or compiled them, press @kbd{C-c C-i} | |
650 (@code{idlwave-update-routine-info}).@refill | |
651 | |
652 The completion function is context sensitive and figures out what to | |
653 complete at point. Here are example lines and what @kbd{M-@key{TAB}} | |
654 would try to complete when the cursor is on the position marked with a | |
655 @samp{*}. | |
656 | |
657 @example | |
658 plo* @r{Procedure} | |
659 x = a* @r{Function} | |
660 plot,xra* @r{Keyword of @code{plot} procedure} | |
661 plot,x,y,/x* @r{Keyword of @code{plot} procedure} | |
662 plot,min(* @r{Keyword of @code{min} function} | |
663 obj -> a* @r{Object method (procedure)} | |
664 a(2,3) = obj -> a* @r{Object method (function)} | |
665 x = obj_new('IDL* @r{Class name} | |
666 x = obj_new('MyCl',a* @r{Keyword to @code{Init} method in class @code{MyCl}} | |
667 @end example | |
668 | |
669 @cindex Scrolling the @file{*Completions*} window | |
670 @cindex Completion, scrolling | |
671 If the list of completions is too long to fit in the | |
672 @file{*Completions*} window, the window can be scrolled by pressing | |
673 @kbd{M-@key{TAB}} repeatedly.@refill | |
674 | |
675 @cindex Case of completed words | |
676 The case of the completed words is determined by what is already in the | |
677 buffer. When the partial word being completed is all lower case, the | |
678 completion will be lower case as well. If at least one character is | |
679 upper case, the string will be completed in upper case or mixed case. | |
680 The default is to use upper case for procedures, functions and keywords, | |
681 and mixed case for object class names and methods, similar to the | |
682 conventions in the IDL manuals. These defaults can be changed with the | |
683 variable @code{idlwave-completion-case}.@refill | |
684 | |
685 @defopt idlwave-completion-case | |
686 Association list setting the case (UPPER/lower/Capitalized/...) of completed | |
687 words.@refill | |
688 @end defopt | |
689 | |
690 @defopt idlwave-completion-force-default-case (@code{nil}) | |
691 Non-@code{nil} means, completion will always honor the settings in | |
692 @code{idlwave-completion-case}. When nil (the default), lower case | |
693 strings will be completed to lower case. | |
694 @end defopt | |
695 | |
696 @defopt idlwave-complete-empty-string-as-lower-case (@code{nil}) | |
697 Non-@code{nil} means, the empty string is considered lower case for | |
698 completion.@refill | |
699 @end defopt | |
700 | |
701 @defopt idlwave-keyword-completion-adds-equal (@code{t}) | |
702 Non-@code{nil} means, completion automatically adds @samp{=} after | |
703 completed keywords.@refill | |
704 @end defopt | |
705 | |
706 @defopt idlwave-function-completion-adds-paren (@code{t}) | |
707 Non-@code{nil} means, completion automatically adds @samp{(} after | |
708 completed function. A value of `2' means, also add the closing | |
709 parenthesis and position cursor between the two.@refill | |
710 @end defopt | |
711 | |
712 @defopt idlwave-completion-restore-window-configuration (@code{t}) | |
713 Non-@code{nil} means, restore window configuration after successful | |
714 completion.@refill | |
715 @end defopt | |
716 | |
717 @subsubheading Object Method Completion and Class Ambiguity | |
718 @cindex Object methods | |
719 @cindex Class ambiguity | |
720 An object method is not uniquely determined without the object's class. | |
721 Since the class part is usually omitted in the source code, IDLWAVE | |
722 considers all available methods in all classes as possible completions | |
723 of an object method name. For keywords, the combined keywords of the | |
724 current method in all available classes will be considered. In the | |
725 @file{*Completions*} buffer, the classes allowed for each completion | |
726 will be shown next to the item (see option | |
727 @code{idlwave-completion-show-classes}).@refill | |
728 | |
729 You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u | |
730 M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to | |
731 narrow down the number of possible completions. The variable | |
732 @code{idlwave-query-class} can be configured to make this behavior the | |
733 default (not really recommended). After you have specified the class | |
734 for a particular statement (e.g. when completing the method), IDLWAVE | |
735 can remember it for the rest of the editing session. Subsequent | |
736 completions in the same statement (e.g. keywords) can then reuse this | |
737 class information. Remembering the class works by placing a text | |
738 property in the object operator @samp{->}. This is not enabled by | |
739 default - the variable @code{idlwave-store-inquired-class} can be used | |
740 to turn it on.@refill | |
741 | |
742 @defopt idlwave-completion-show-classes (@code{t}) | |
743 Non-@code{nil} means, show classes in @file{*Completions*} buffer when | |
744 completing object methods and keywords.@refill | |
745 @end defopt | |
746 | |
747 @defopt idlwave-completion-fontify-classes (@code{t}) | |
748 Non-@code{nil} means, fontify the classes in completions buffer. | |
749 @end defopt | |
750 | |
751 @defopt idlwave-query-class (@code{nil}) | |
752 Association list governing query for object classes during completion.@refill | |
753 @end defopt | |
754 | |
755 @defopt idlwave-store-inquired-class (@code{nil}) | |
756 Non-@code{nil} means, store class of a method call as text property on | |
757 @samp{->}.@refill | |
758 @end defopt | |
759 | |
760 @defopt idlwave-class-arrow-face | |
761 Face to highlight object operator arrows @samp{->} which carry a class | |
762 property.@refill | |
763 @end defopt | |
764 | |
765 @node Code Templates, Actions, Completion, The IDLWAVE Major Mode | |
766 @section Code Templates | |
767 @cindex Code templates | |
768 @cindex Abbreviations | |
769 @cindex Templates | |
770 | |
771 IDLWAVE can insert IDL code templates into the buffer. For a few | |
772 templates, this is done with direct keybindings: | |
773 | |
774 @multitable @columnfractions .15 .85 | |
775 @item @kbd{C-c C-c} | |
776 @tab @code{CASE} statement template | |
777 @item @kbd{C-c C-f} | |
778 @tab @code{FOR} loop template | |
779 @item @kbd{C-c C-r} | |
780 @tab @code{REPEAT} loop template | |
781 @item @kbd{C-c C-w} | |
782 @tab @code{WHILE} loop template | |
783 @end multitable | |
784 | |
785 Otherwise, special abbreviations are used. Emacs abbreviations are | |
786 expanded by typing text into the buffer and pressing @key{SPC} or | |
787 @key{RET}. The special abbreviations used to insert code templates all | |
788 start with a @samp{\} (the backslash). Here are a few examples of | |
789 predefined abbreviations. For a full list, use @kbd{M-x | |
790 idlwave-list-abbrevs}. | |
791 | |
792 @multitable @columnfractions .15 .85 | |
793 @item @code{\pr} | |
794 @tab @code{PROCEDURE} template | |
795 @item @code{\fu} | |
796 @tab @code{FUNCTION} template | |
797 @item @code{\c} | |
798 @tab @code{CASE} statement template | |
799 @item @code{\f} | |
800 @tab @code{FOR} loop template | |
801 @item @code{\r} | |
802 @tab @code{REPEAT} loop template | |
803 @item @code{\w} | |
804 @tab @code{WHILE} loop template | |
805 @item @code{\i} | |
806 @tab @code{IF} statement template | |
807 @item @code{\elif} | |
808 @tab @code{IF-ELSE} statement template | |
809 @item @code{\b} | |
810 @tab @code{BEGIN} | |
811 @end multitable | |
812 | |
813 @defopt idlwave-abbrev-start-char | |
814 A single character string used to start abbreviations in abbrev | |
815 mode.@refill | |
816 @end defopt | |
817 | |
818 @defopt idlwave-abbrev-move (@code{t}) | |
819 Non-@code{nil} means the abbrev hook can move point, e.g. to end up | |
820 between the parenthesis of a function call. | |
821 @end defopt | |
822 | |
823 @node Actions, Doc Header, Code Templates, The IDLWAVE Major Mode | |
824 @section Actions | |
825 @cindex Actions | |
826 @cindex Coding standards, enforcing | |
827 | |
828 @emph{Actions} are special commands which are executed automatically | |
829 while you write code in order to check the structure of the program or | |
830 to enforce coding standards. Most actions which have been implemented | |
831 in IDLWAVE are turned off by default, assuming that the average user | |
832 wants her code the way she writes it. But if you are a lazy typist and | |
833 want your code to adhere to certain standards, they can be | |
834 helpful.@refill | |
835 | |
836 Action can be applied in three ways: | |
837 @itemize @bullet | |
838 @item | |
839 Some actions are applied directly while typing. For example, pressing | |
840 @samp{=} can run a check to make sure that this operator is surrounded | |
841 by spaces and insert these spaces if necessary. Pressing @key{SPC} | |
842 after a reserved word can call a command to change the word to upper | |
843 case.@refill | |
844 @item | |
845 When a line is re-indented with @key{TAB}, actions can be applied to the | |
846 entire line. To enable this, the variable @code{idlwave-do-actions} | |
847 must be non-@code{nil}.@refill | |
848 @item | |
849 @cindex Foreign code, adapting | |
850 @cindex Actions, applied to foreign code | |
851 Action can also be applied to a larger piece of code, e.g. in order to | |
852 convert foreign code to your own style. To do this, mark the relevant | |
853 part of the code and execute @kbd{M-x expand-region-abbrevs}. Useful | |
854 marking commands are @kbd{C-x h} (the entire file) or @kbd{M-C-h} (the | |
855 current subprogram). @xref{Code Indentation}, for information how to | |
856 ajust the indentation of the code.@refill | |
857 @end itemize | |
858 | |
859 @defopt idlwave-do-actions (@code{nil}) | |
860 Non-@code{nil} means performs actions when indenting. | |
861 @end defopt | |
862 | |
863 @menu | |
864 * Block Boundary Check:: Is the END correct | |
865 * Padding Operators:: Enforcing space around `=' etc | |
866 * Case Changes:: Enforcing upper case keywords | |
867 @end menu | |
868 | |
869 @node Block Boundary Check, Padding Operators, Actions, Actions | |
870 @subsection Block Boundary Check | |
871 @cindex Block boundary check | |
872 @cindex @code{END} type checking | |
873 @cindex @code{END}, automatic insertion | |
874 @cindex Block, closing | |
875 @cindex Closing a block | |
876 | |
877 Whenever you type an @code{END} statement, IDLWAVE finds the | |
878 corresponding start of the block and the cursor blinks back to that | |
879 location for a second. If you have typed a specific @code{END}, like | |
880 @code{ENDIF} or @code{ENDCASE}, you get a warning if that kind of END | |
881 does not match the type of block it terminates.@refill | |
882 | |
883 Set the variable @code{idlwave-expand-generic-end} in order to have all | |
884 generic @code{END} statements automatically expanded to a specific type. | |
885 You can also type @kbd{C-c ]} to close the current block by inserting | |
886 the appropriate @code{END} statement.@refill | |
887 | |
888 @defopt idlwave-show-block (@code{t}) | |
889 Non-@code{nil} means point blinks to block beginning for | |
890 @code{idlwave-show-begin}.@refill | |
891 @end defopt | |
892 | |
893 @defopt idlwave-expand-generic-end (@code{nil}) | |
894 Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc. | |
895 @end defopt | |
896 | |
897 @node Padding Operators, Case Changes, Block Boundary Check, Actions | |
898 @subsection Padding Operators | |
899 @cindex Padding operators with spaces | |
900 @cindex Operators, padding with spaces | |
901 | |
902 Some operators can be automatically surrounded by spaces. This can | |
903 happen when the operator is typed, or also later when the line is | |
904 indented. IDLWAVE contains this setting for the operators @samp{&}, | |
905 @samp{<}, @samp{>}, @samp{,}, @samp{=}, but the feature is turned off by | |
906 default. If you want to turn it on, customize the variable | |
907 @code{idlwave-surround-by-blank}. You can also define similar actions | |
908 for other operators by using the function | |
909 @code{idlwave-action-and-binding} in the mode hook. For example, to | |
910 enforce space padding of the @samp{+} and @samp{*} operators, try this | |
911 in @file{.emacs} | |
912 | |
913 @lisp | |
914 (add-hook 'idlwave-mode-hook | |
915 (lambda () | |
916 (setq idlwave-surround-by-blank t) ; Turn this type of actions on | |
917 (idlwave-action-and-binding "*" '(idlwave-surround 1 1)) | |
918 (idlwave-action-and-binding "+" '(idlwave-surround 1 1)))) | |
919 @end lisp | |
920 | |
921 @defopt idlwave-surround-by-blank (@code{nil}) | |
922 Non-@code{nil} means, enable @code{idlwave-surround}. If non-nil, | |
923 @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,} are surrounded with | |
924 spaces by @code{idlwave-surround}. | |
925 @end defopt | |
926 | |
927 @defopt idlwave-pad-keyword (@code{t}) | |
928 Non-@code{nil} means pad @samp{=} for keywords like assignments.@refill | |
929 @end defopt | |
930 | |
931 @node Case Changes, , Padding Operators, Actions | |
932 @subsection Case Changes | |
933 @cindex Case changes | |
934 | |
935 Actions can be used to change the case of reserved words or expanded | |
936 abbreviations by customizing the variables | |
937 @code{idlwave-abbrev-change-case} and | |
938 @code{idlwave-reserved-word-upcase}. If you want to change the case of | |
939 additional words automatically, put something like the following into | |
940 your @file{.emacs} file:@refill | |
941 | |
942 @lisp | |
943 (add-hook 'idlwave-mode-hook | |
944 (lambda () | |
945 ;; Capitalize system vars | |
946 (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t) | |
947 ;; Capitalize procedure name | |
948 (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" | |
949 '(capitalize-word 1) t) | |
950 ;; Capitalize common block name | |
951 (idlwave-action-and-binding "\\<common\\>[ \t]+\\<" | |
952 '(capitalize-word 1) t))) | |
953 @end lisp | |
954 | |
955 For more information, see the documentation string for the function | |
956 @code{idlwave-action-and-binding}. | |
957 | |
958 @defopt idlwave-abbrev-change-case (@code{nil}) | |
959 Non-@code{nil} means all abbrevs will be forced to either upper or lower | |
960 case. Legal values are @code{nil}, @code{t}, and @code{down}. | |
961 @end defopt | |
962 | |
963 @defopt idlwave-reserved-word-upcase (@code{nil}) | |
964 Non-@code{nil} means, reserved words will be made upper case via abbrev | |
965 expansion. | |
966 @end defopt | |
967 | |
968 | |
969 @node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode | |
970 @section Documentation Header | |
971 @cindex Documentation header | |
972 @cindex Modification timestamp | |
973 @cindex Header, for file documentation | |
974 @cindex Timestamp, in doc header. | |
975 @cindex Changelog, in doc header. | |
976 | |
977 The command @kbd{C-c C-h} inserts a standard routine header into the | |
978 buffer, with the usual fields for documentation. One of the keywords is | |
979 @samp{MODIFICATION HISTORY} under which the changes to a routine can be | |
980 recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION | |
981 HISTORY} of the current routine or file and inserts the user | |
982 name with a timestamp. | |
983 | |
984 @defopt idlwave-file-header | |
985 The doc-header template or a path to a file containing it. | |
986 @end defopt | |
987 | |
988 @defopt idlwave-timestamp-hook | |
989 The hook function used to update the timestamp of a function. | |
990 @end defopt | |
991 | |
992 @defopt idlwave-doc-modifications-keyword | |
993 The modifications keyword to use with the log documentation commands. | |
994 @end defopt | |
995 | |
996 @defopt idlwave-doclib-start | |
997 Regexp matching the start of a document library header. | |
998 @end defopt | |
999 | |
1000 @defopt idlwave-doclib-end | |
1001 Regexp matching the start of a document library header. | |
1002 @end defopt | |
1003 | |
1004 @node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode | |
1005 @section Motion Commands | |
1006 @cindex Motion commands | |
1007 @cindex Program structure, moving through | |
1008 @cindex Code structure, moving through | |
1009 | |
1010 Several commands allow to move quickly through the structure of an IDL | |
1011 program. These are | |
1012 | |
1013 @multitable @columnfractions .15 .85 | |
1014 @item @kbd{C-M-a} | |
1015 @tab Beginning of subprogram | |
1016 @item @kbd{C-M-e} | |
1017 @tab End of subprogram | |
1018 @item @kbd{C-c @{} | |
1019 @tab Beginning of block (stay inside the block) | |
1020 @item @kbd{C-c @}} | |
1021 @tab End of block (stay inside the block) | |
1022 @item @kbd{M-C-n} | |
1023 @tab Forward block (on same level) | |
1024 @item @kbd{M-C-p} | |
1025 @tab Backward block (on same level) | |
1026 @item @kbd{M-C-d} | |
1027 @tab Down block (enters a block) | |
1028 @item @kbd{M-C-u} | |
1029 @tab Backward up block (leaves a block) | |
1030 @item @kbd{C-c C-n} | |
1031 @tab Next Statement | |
1032 @end multitable | |
1033 | |
1034 | |
1035 @node Misc Options, , Motion Commands, The IDLWAVE Major Mode | |
1036 @section Miscellaneous Options | |
1037 | |
1038 @defopt idlwave-help-application | |
1039 The external application providing reference help for programming. | |
1040 @end defopt | |
1041 | |
1042 @defopt idlwave-startup-message (@code{t}) | |
1043 Non-@code{nil} means display a startup message when @code{idlwave-mode}' | |
1044 is first called. | |
1045 @end defopt | |
1046 | |
1047 @defopt idlwave-mode-hook | |
1048 Normal hook. Executed when a buffer is put into @code{idlwave-mode}. | |
1049 @end defopt | |
1050 | |
1051 @defopt idlwave-load-hook | |
1052 Normal hook. Executed when @file{idlwave.el} is loaded. | |
1053 @end defopt | |
1054 | |
1055 | |
1056 | |
1057 | |
1058 | |
1059 | |
1060 | |
1061 | |
1062 | |
1063 | |
1064 | |
1065 | |
1066 | |
1067 | |
1068 | |
1069 | |
1070 @node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top | |
1071 @chapter The IDLWAVE Shell | |
1072 @cindex IDLWAVE shell | |
1073 @cindex Major mode, @code{idlwave-shell-mode} | |
1074 | |
1075 The IDLWAVE shell is an Emacs major mode which allows to run the IDL | |
1076 program as an inferior process of Emacs. It can be used to work with | |
1077 IDL interactively, to compile and run IDL programs in Emacs buffers and | |
1078 to debug these programs. The IDLWAVE shell uses @file{comint}, an Emacs | |
1079 packages which handles the communication with the IDL program. | |
1080 Unfortunately IDL for Windows and MacOS does not allow the interaction | |
1081 with Emacs@footnote{Please inform the maintainer if you come up with a way | |
1082 to make the IDLWAVE shell work on these systems.} - so the IDLWAVE shell | |
1083 only works under Unix.@refill | |
1084 | |
1085 @menu | |
1086 * Starting the Shell:: How to launch IDL as a subprocess | |
1087 * Using the Shell:: Interactively working with the Shell | |
1088 * Debugging IDL Programs:: Compilation/Debugging | |
1089 @end menu | |
1090 | |
1091 @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell | |
1092 @section Starting the Shell | |
1093 @cindex Starting the shell | |
1094 @cindex Shell, starting | |
1095 @cindex Dedicated frame, for shell buffer | |
1096 @cindex Frame, for shell buffer | |
1097 | |
1098 The IDLWAVE shell can be started with the command @kbd{M-x | |
1099 idlwave-shell}. In @code{idlwave-mode} the function is bound to | |
1100 @kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to | |
1101 interact with the shell. If the shell is already running, @kbd{C-c C-s} | |
1102 will simple switch to the shell buffer. The command @kbd{C-c C-l} | |
1103 (@code{idlwave-shell-recenter-shell-window}) displays the | |
1104 shell window without selecting it.@refill | |
1105 | |
1106 In order to create a separate frame for the IDLWAVE shell buffer, call | |
1107 @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or | |
1108 @kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell | |
1109 window, configure the variable | |
1110 @code{idlwave-shell-use-dedicated-frame}.@refill | |
1111 | |
1112 The shell can also be started automatically when another command tries | |
1113 to send a command to it. To enable auto start, set the variable | |
1114 @code{idlwave-shell-automatic-start} to @code{t}.@refill | |
1115 | |
1116 @defopt idlwave-shell-explicit-file-name | |
1117 This is the command to run IDL. | |
1118 @end defopt | |
1119 | |
1120 @defopt idlwave-shell-command-line-options | |
1121 A list of command line options for calling the IDL program. | |
1122 @end defopt | |
1123 | |
1124 @defopt idlwave-shell-prompt-pattern | |
1125 Regexp to match IDL prompt at beginning of a line. | |
1126 @end defopt | |
1127 | |
1128 @defopt idlwave-shell-process-name | |
1129 Name to be associated with the IDL process. | |
1130 @end defopt | |
1131 | |
1132 @defopt idlwave-shell-automatic-start | |
1133 Non-@code{nil} means attempt to invoke idlwave-shell if not already | |
1134 running. | |
1135 @end defopt | |
1136 | |
1137 @defopt idlwave-shell-initial-commands | |
1138 Initial commands, separated by newlines, to send to IDL. | |
1139 @end defopt | |
1140 | |
1141 @defopt idlwave-shell-use-dedicated-frame (@code{nil}) | |
1142 Non-@code{nil} means, IDLWAVE should use a special frame to display | |
1143 shell buffer. | |
1144 @end defopt | |
1145 | |
1146 @defopt idlwave-shell-frame-parameters | |
1147 The frame parameters for a dedicated idlwave-shell frame. | |
1148 @end defopt | |
1149 | |
1150 @defopt idlwave-shell-temp-pro-prefix | |
1151 The prefix for temporary IDL files used when compiling regions.@refill | |
1152 @end defopt | |
1153 | |
1154 @defopt idlwave-shell-mode-hook | |
1155 Hook for customizing @code{idlwave-shell-mode}. | |
1156 @end defopt | |
1157 | |
1158 @node Using the Shell, Debugging IDL Programs, Starting the Shell, The IDLWAVE Shell | |
1159 @section Using the Shell | |
1160 @cindex comint | |
1161 @cindex Shell, basic commands | |
1162 | |
1163 The IDLWAVE shell works in the same fashion as other shell modes in | |
1164 Emacs. It provides command history, command line editing and job | |
1165 control. Here is a list of commonly used commands, see the Emacs | |
1166 documentation on @file{comint} for additional information.@refill | |
1167 | |
1168 @multitable @columnfractions .12 .88 | |
1169 @item @kbd{M-p} | |
1170 @tab Cycle backwards in input history matching input | |
1171 @item @kbd{M-n} | |
1172 @tab Cycle forwards | |
1173 @item @kbd{M-r} | |
1174 @tab Previous input matching a regexp | |
1175 @item @kbd{M-s} | |
1176 @tab Next input that matches a regexp | |
1177 @item @kbd{return} | |
1178 @tab Send input or copy line to current prompt | |
1179 @item @kbd{C-c C-a} | |
1180 @tab Beginning of line; skip prompt | |
1181 @item @kbd{C-c C-u} | |
1182 @tab Kill input to beginning of line | |
1183 @item @kbd{C-c C-w} | |
1184 @tab Kill word before cursor | |
1185 @item @kbd{C-c C-c} | |
1186 @tab Send ^C | |
1187 @item @kbd{C-c C-z} | |
1188 @tab Send ^Z | |
1189 @item @kbd{C-c C-\} | |
1190 @tab Send ^\ | |
1191 @item @kbd{C-c C-o} | |
1192 @tab Delete last batch of process output | |
1193 @item @kbd{C-c C-r} | |
1194 @tab Show last batch of process output | |
1195 @item @kbd{C-c C-l} | |
1196 @tab List input history | |
1197 @end multitable | |
1198 | |
1199 In addition to these standard @file{comint} commands, | |
1200 @code{idlwave-shell-mode} has some bindings which correspond to similar | |
1201 commands in @code{idlwave-mode}. See @ref{Routine Info} and | |
1202 @ref{Completion} for more information on these commands.@refill | |
1203 | |
1204 @cindex Completion in the shell | |
1205 @cindex Routine info in the shell | |
1206 @multitable @columnfractions .12 .88 | |
1207 @item @kbd{@key{TAB}} | |
1208 @tab Completion of file names, routine names and keywords | |
1209 (@code{idlwave-shell-complete})@refill | |
1210 @item @kbd{M-@key{TAB}} | |
1211 @tab Same as @key{TAB} | |
1212 @item @kbd{C-c ?} | |
1213 @tab Routine Info display (@code{idlwave-routine-info}) | |
1214 @item @kbd{M-?} | |
1215 @tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp}) | |
1216 @item @kbd{C-c C-i} | |
1217 @tab Update routine info from buffers and shell | |
1218 (@code{idlwave-update-routine-info}) | |
1219 @item @kbd{C-c C-v} | |
1220 @tab Find the source file of a routine (@code{idlwave-find-module}) | |
1221 @item @kbd{C-c =} | |
1222 @tab Compile a library routine (@code{idlwave-resolve}) | |
1223 @end multitable | |
1224 | |
1225 @defopt idlwave-shell-file-name-chars | |
1226 The characters allowed in file names, as a string. Used for file name | |
1227 completion.@refill | |
1228 @end defopt | |
1229 | |
1230 @node Debugging IDL Programs, , Using the Shell, The IDLWAVE Shell | |
1231 @section Debugging IDL Programs | |
1232 @cindex Debugging | |
1233 @cindex Keybindings for debugging | |
1234 @cindex Toolbar | |
1235 | |
1236 Programs can be compiled, run, and debugged directly from the source | |
1237 buffer in Emacs. The IDLWAVE shell installs keybindings both in the | |
1238 shell buffer and in all IDL code buffers of the current Emacs session. | |
1239 On Emacs versions which support this, it also installs a debugging | |
1240 toolbar. The display of the toolbar can be toggled with @kbd{C-c C-d | |
1241 C-t} (@code{idlwave-shell-toggle-toolbar}).@refill | |
1242 | |
1243 The debugging keybindings are by default on the prefix key @kbd{C-c | |
1244 C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d | |
1245 C-b}. If you find this too much work and your ALT key is still | |
1246 available, turn on the variable | |
1247 @code{idlwave-shell-activate-alt-keybindings} in order to get breakpoint | |
1248 setting on @kbd{A-b}. In the remainder of this chapter we will assume | |
1249 that the @kbd{C-c C-d} bindings are active. | |
1250 | |
1251 @defopt idlwave-shell-prefix-key | |
1252 The prefix key for the debugging map | |
1253 @code{idlwave-shell-mode-prefix-map}.@refill | |
1254 @end defopt | |
1255 | |
1256 @defopt idlwave-shell-activate-prefix-keybindings (@code{t}) | |
1257 Non-@code{nil} means, debug commands will be bound to the prefix | |
1258 key, like @kbd{C-c C-d C-b}. | |
1259 @end defopt | |
1260 | |
1261 @defopt idlwave-shell-activate-alt-keybindings (@code{nil}) | |
1262 Non-@code{nil} means, debug commands will be bound to alternate | |
1263 keys, like @kbd{A-b}. | |
1264 @end defopt | |
1265 | |
1266 @defopt idlwave-shell-use-toolbar (@code{t}) | |
1267 Non-@code{nil} means, use the debugging toolbar in all IDL related | |
1268 buffers.@refill | |
1269 @end defopt | |
1270 | |
1271 | |
1272 @menu | |
1273 * Compiling Programs:: Compiling buffers under the shell | |
1274 * Breakpoints and Stepping:: Deciding where to stop and look | |
1275 * Examining Variables:: What is the value now? | |
1276 @end menu | |
1277 | |
1278 @node Compiling Programs, Breakpoints and Stepping, Debugging IDL Programs, Debugging IDL Programs | |
1279 @subsection Compiling Programs | |
1280 @cindex Compiling programs | |
1281 @cindex Programs, compiling | |
1282 @cindex Default command line, executing | |
1283 @cindex Executing a default command line | |
1284 | |
1285 In order to compile the current buffer under the IDLWAVE shell, press | |
1286 @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the | |
1287 current buffer and then send the command @samp{.run path/to/file} to the | |
1288 shell. You can laso execute @kbd{C-c C-d C-c} from the shell buffer, in | |
1289 which case the most recently compiled buffer will be saved and | |
1290 re-compiled. | |
1291 | |
1292 When developing or debugging a program, it is often necessary to execute | |
1293 the same command line many times. A convenient way to do this is | |
1294 @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}). | |
1295 This command first resets IDL from a state of interrupted execution by | |
1296 closing all files and returning to the main interpreter level. Then a | |
1297 default command line is send to the shell. To edit the default command | |
1298 line, call @code{idlwave-shell-execute-default-command-line} with a | |
1299 prefix argument: @kbd{C-u C-c C-d C-y}.@refill | |
1300 | |
1301 @defopt idlwave-shell-mark-stop-line (@code{t}) | |
1302 Non-@code{nil} means, mark the source code line where IDL is currently | |
1303 stopped. The value decides about the preferred method. Legal values | |
1304 are @code{nil}, @code{t}, @code{arrow}, and @code{face}.@refill | |
1305 @end defopt | |
1306 | |
1307 @defopt idlwave-shell-overlay-arrow | |
1308 The overlay arrow to display at source lines where execution | |
1309 halts.@refill | |
1310 @end defopt | |
1311 | |
1312 @defopt idlwave-shell-stop-line-face | |
1313 The face which highlights the source line where IDL is | |
1314 stopped.@refill | |
1315 @end defopt | |
1316 | |
1317 @node Breakpoints and Stepping, Examining Variables, Compiling Programs, Debugging IDL Programs | |
1318 @subsection Breakpoints and Stepping | |
1319 @cindex Breakpoints | |
1320 @cindex Stepping | |
1321 | |
1322 You can set breakpoints and step through a program with IDLWAVE. | |
1323 Setting a breakpoint in the current line of the source buffer is done | |
1324 with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a prefix | |
1325 arg of 1, the breakpoint gets a @code{/ONCE} keyword, meaning that it | |
1326 will be deleted after first use. With a numeric prefix greater than | |
1327 one, the breakpoint will only be active the @code{nth} time it is hit. | |
1328 To clear the breakpoint in the current line, use @kbd{C-c C-d C-d} | |
1329 (@code{idlwave-clear-current-bp}). To clear all breakpoints, use | |
1330 @kbd{C-c C-d C-a} (@code{idlwave-clear-all-bp}). Breakpoint lines are | |
1331 highlighted in the source code.@refill | |
1332 | |
1333 Once the program has stopped somewhere, you can step through it. Here | |
1334 is a summary of the breakpoint and stepping commands: | |
1335 | |
1336 @multitable @columnfractions .2 .8 | |
1337 @item @kbd{C-c C-d C-b} | |
1338 @tab Set breakpoint (@code{idlwave-shell-break-here}) | |
1339 @item @kbd{C-c C-d C-i} | |
1340 @tab Set breakpoint in function named here (@code{idlwave-shell-break-in}) | |
1341 @item @kbd{C-c C-d C-d} | |
1342 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) | |
1343 @item @kbd{C-c C-d C-a} | |
1344 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) | |
1345 @item @kbd{C-c C-d C-s} | |
1346 @tab Step, into function calls (@code{idlwave-shell-step}) | |
1347 @item @kbd{C-c C-d C-n} | |
1348 @tab Step, over function calls (@code{idlwave-shell-stepover}) | |
1349 @item @kbd{C-c C-d C-k} | |
1350 @tab Skip one statement (@code{idlwave-shell-skip}) | |
1351 @item @kbd{C-c C-d C-u} | |
1352 @tab Continue to end of block (@code{idlwave-shell-up}) | |
1353 @item @kbd{C-c C-d C-m} | |
1354 @tab Continue to end of function (@code{idlwave-shell-return}) | |
1355 @item @kbd{C-c C-d C-o} | |
1356 @tab Continue past end of function (@code{idlwave-shell-out}) | |
1357 @item @kbd{C-c C-d C-h} | |
1358 @tab Continue to line at cursor position (@code{idlwave-shell-to-here}) | |
1359 @item @kbd{C-c C-d C-r} | |
1360 @tab Continue execution to next breakpoint (@code{idlwave-shell-cont}) | |
1361 @item @kbd{C-c C-d C-up} | |
1362 @tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) | |
1363 @item @kbd{C-c C-d C-down} | |
1364 @tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) | |
1365 @end multitable | |
1366 | |
1367 @defopt idlwave-shell-mark-breakpoints (@code{t}) | |
1368 Non-@code{nil} means, mark breakpoints in the source file buffers. The | |
1369 value indicates the preferred method. Legal values are @code{nil}, | |
1370 @code{t}, @code{face}, and @code{glyph}. | |
1371 @end defopt | |
1372 | |
1373 @defopt idlwave-shell-breakpoint-face | |
1374 The face for breakpoint lines in the source code if | |
1375 @code{idlwave-shell-mark-breakpoints} has the value @code{face}.@refill | |
1376 @end defopt | |
1377 | |
1378 @node Examining Variables, , Breakpoints and Stepping, Debugging IDL Programs | |
1379 @subsection Examining Variables | |
1380 @cindex @code{PRINT} expressions | |
1381 @cindex @code{HELP}, on expressions | |
1382 @cindex Expressions, printing | |
1383 @cindex Expressions, help | |
1384 @cindex Mouse binding to print expressions | |
1385 | |
1386 When execution is stopped you can examine the values of variables. The | |
1387 command @kbd{C-c C-d C-p} prints the expression at point in the shell | |
1388 buffer, while @kbd{C-c C-d ?} shows help on this expression. The | |
1389 expression at point is an array expression or a function call, or the | |
1390 contents of a pair of parenthesis. The selected expression becomes | |
1391 highlighted in the source code for a short time. | |
1392 | |
1393 I find it very convenient to bind these functions to a mouse event, so | |
1394 that simply clicking on an expression prints its value. Here is a way | |
1395 to do this with XEmacs: | |
1396 | |
1397 @lisp | |
1398 (add-hook 'idlwave-shell-mode-hook | |
1399 (lambda() | |
1400 (define-key idlwave-mode-map [(shift button1)] | |
1401 'idlwave-shell-mouse-print) | |
1402 (define-key idlwave-mode-map [(shift button2)] | |
1403 'idlwave-shell-mouse-help))) | |
1404 @end lisp | |
1405 | |
1406 @defopt idlwave-shell-expression-face | |
1407 The face for @code{idlwave-shell-expression-overlay}. | |
1408 Allows you to choose the font, color and other properties for | |
1409 the expression printed by IDL. | |
1410 @end defopt | |
1411 | |
1412 | |
1413 @node Installation, Acknowledgement, The IDLWAVE Shell, Top | |
1414 @chapter Installation | |
1415 @cindex Installation | |
1416 @cindex FTP site | |
1417 @cindex URL, homepage for IDLWAVE | |
1418 @cindex Homepage for IDLWAVE | |
1419 | |
1420 @menu | |
1421 * Installing IDLWAVE:: How to install the distribution | |
1422 * Upgrading from idl.el:: Necessary configuration changes | |
1423 @end menu | |
1424 | |
1425 @node Installing IDLWAVE, Upgrading from idl.el, Installation, Installation | |
1426 @section Installing IDLWAVE | |
1427 | |
1428 IDLWAVE is part of Emacs 21.1 and later. It is also@footnote{or will be | |
1429 soon} an XEmacs packages and can be installed from | |
1430 @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site} | |
1431 with the normal package management system on XEmacs 21.@refill | |
1432 | |
1433 You can also download IDLWAVE and install it yourself from | |
1434 @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave, the maintainers | |
1435 webpage}. Follow the instructions in the INSTALL file.@refill | |
1436 | |
1437 @node Upgrading from idl.el, , Installing IDLWAVE, Installation | |
1438 @section Upgrading from the old @b{@file{idl.el}} file | |
1439 @cindex Upgrading from old @b{@file{idl.el}} | |
1440 @cindex Renaming old variables | |
1441 @cindex Old variables, renaming | |
1442 | |
1443 If you have been using the old @file{idl.el} and @file{idl-shell.el} | |
1444 files and would like to use IDLWAVE, you need to update your | |
1445 customization in @file{.emacs}. | |
1446 | |
1447 @enumerate | |
1448 @item | |
1449 Change all variable and function prefixes from @samp{idl-} to @samp{idlwave-}. | |
1450 @item | |
1451 Remove the now invalid @code{autoload} and @code{auto-mode-alist} forms | |
1452 pointing to the @file{idl.el} and @file{idl-shell.el} files. | |
1453 @item | |
1454 If you have been using the hook function recommended in earlier versions | |
1455 to get a separate frame for the IDL shell, remove that command from your | |
1456 @code{idlwave-shell-mode-hook}. Instead, set the variable | |
1457 @code{idlwave-shell-use-dedicated-frame} with | |
1458 @lisp | |
1459 (setq idlwave-shell-use-dedicated-frame t) | |
1460 @end lisp | |
1461 @end enumerate | |
1462 | |
1463 @node Acknowledgement, Sources of Routine Info, Installation, Top | |
1464 @chapter Acknowledgement | |
1465 @cindex Acknowledgement | |
1466 @cindex Thanks | |
1467 | |
1468 @file{idl.el} and @file{idl-shell.el} were written by | |
1469 @uref{mailto:chase@@att.com, Chris Chase}. The package | |
1470 was extended and renamed to IDLWAVE by the current maintainer | |
1471 @uref{mailto:dominik@@strw.leidenuniv.nl, Carsten Dominik}. | |
1472 | |
1473 Thanks to the following people who have contributed to the development | |
1474 of IDLWAVE with patches, ideas, bug reports and suggestions. | |
1475 | |
1476 @itemize @minus | |
1477 @item | |
1478 Ulrik Dickow <dickow@@nbi.dk> | |
1479 @item | |
1480 Eric E. Dors <edors@@lanl.gov> | |
1481 @item | |
1482 Stein Vidar H. Haugan <s.v.h.haugan@@astro.uio.no> | |
1483 @item | |
1484 David Huenemoerder <dph@@space.mit.edu> | |
1485 @item | |
1486 Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de> | |
1487 @item | |
1488 Xuyong Liu <liu@@stsci.edu> | |
1489 @item | |
1490 Simon Marshall <Simon.Marshall@@esrin.esa.it> | |
1491 @item | |
1492 Laurent Mugnier <mugnier@@onera.fr> | |
1493 @item | |
1494 Lubos Pochman <lubos@@rsinc.com> | |
1495 @item | |
1496 Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov> | |
1497 @item | |
1498 Marty Ryba <ryba@@ll.mit.edu> | |
1499 @item | |
1500 Phil Williams <williams@@irc.chmcc.org> | |
1501 @item | |
1502 J.D. Smith <jdsmith@@astrosun.tn.cornell.edu> | |
1503 @item | |
1504 Phil Sterne <sterne@@dublin.llnl.gov> | |
1505 @end itemize | |
1506 | |
1507 @node Sources of Routine Info, Configuration Examples, Acknowledgement, Top | |
1508 @appendix Sources of Routine Info | |
1509 | |
1510 In @ref{Routine Info} and @ref{Completion} it was shown how IDLWAVE | |
1511 displays the calling sequence and keywords of routines, and how it | |
1512 completes routine names and keywords. For these features to work, | |
1513 IDLWAVE must know about the accessible routines. | |
1514 | |
1515 @menu | |
1516 * Routine Definitions:: Where IDL Routines are defined. | |
1517 * Routine Information Sources:: So how does IDLWAVE know about... | |
1518 * Library Scan:: Scanning the Libraries for Routine Info | |
1519 * Updating idlwave-rinfo.el:: Scanning the IDL Manuals | |
1520 @end menu | |
1521 | |
1522 @node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info | |
1523 @section Routine Definitions | |
1524 @cindex Routine definitions | |
1525 | |
1526 Routines which can be used in an IDL program can be defined in several | |
1527 places: | |
1528 | |
1529 @enumerate | |
1530 @item | |
1531 @emph{System routines} are defined inside IDL itself. The source | |
1532 code of such routines is not accessible to the user.@refill | |
1533 @item | |
1534 Routines @emph{part of the current program} are defined in a file which | |
1535 is explicitly compiled by the user. This file may be located on the IDL | |
1536 search path, but this is not certain.@refill | |
1537 @item | |
1538 @emph{Library routines} are defined in special files which are located | |
1539 somewhere on IDL's search path. When a library routine is called for | |
1540 the first time, IDL will find the source file and compile it | |
1541 dynamically.@refill | |
1542 @item | |
1543 External routines written in other languages (like Fortran or C) can be | |
1544 called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, | |
1545 or included as dynamically loaded modules (DLMs). Currently IDLWAVE | |
1546 cannot provide routine info and completion for external | |
1547 routines.@refill | |
1548 @end enumerate | |
1549 | |
1550 @node Routine Information Sources, Library Scan, Routine Definitions, Sources of Routine Info | |
1551 @section Routine Information Sources | |
1552 @cindex Routine info sources | |
1553 | |
1554 In oder to know about as many routines as possible, IDLWAVE will do the | |
1555 following to collect information:@refill | |
1556 | |
1557 @enumerate | |
1558 | |
1559 @item | |
1560 It has a @emph{builtin list} with the properties of the builtin IDL | |
1561 routines. IDLWAVE @value{VERSION} is distributed with a list of | |
1562 @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords, | |
1563 reflecting IDL version @value{IDLVERSION}. This list has been created | |
1564 by scanning the IDL manuals and is stored in the file | |
1565 @file{idlwave-rinfo.el}. @xref{Updating idlwave-rinfo.el}, for | |
1566 information how to regenerate this file for new versions of IDL.@refill | |
1567 | |
1568 @item | |
1569 It @emph{scans} all @emph{buffers} of the current Emacs session for | |
1570 routine definitions. This is done automatically when routine | |
1571 information or completion is first requested by the user. The command | |
1572 @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used at any | |
1573 time to rescan all buffers.@refill | |
1574 | |
1575 @item | |
1576 If you have an IDLWAVE-Shell running as inferior process of the current | |
1577 Emacs session, IDLWAVE will @emph{query the shell} for compiled routines | |
1578 and their arguments. This happens automatically when routine | |
1579 information or completion is first requested by the user. The command | |
1580 @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used to ask | |
1581 the shell again at any time.@refill | |
1582 | |
1583 @item | |
1584 IDLWAVE can scan all or selected library files and store the result in a | |
1585 file which will be automatically loaded just like | |
1586 @file{idlwave-rinfo.el}. @xref{Library Scan}, for information how to | |
1587 scan library files.@refill | |
1588 @end enumerate | |
1589 | |
1590 @defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) | |
1591 Non-@code{nil} means, scan all buffers for IDL programs when updating | |
1592 info. When this variable is @code{nil}, it only parses the current | |
1593 buffer.@refill | |
1594 @end defopt | |
1595 | |
1596 @defopt idlwave-query-shell-for-routine-info (@code{t}) | |
1597 Non-@code{nil} means query the shell for info about compiled routines. | |
1598 @end defopt | |
1599 | |
1600 | |
1601 @node Library Scan, Updating idlwave-rinfo.el, Routine Information Sources, Sources of Routine Info | |
1602 @section Library Scan | |
1603 @cindex Library scan | |
1604 @cindex IDL library routine info | |
1605 | |
1606 IDLWAVE can extract routine information from library modules and store | |
1607 that information in a file. To do this, the variable | |
1608 @code{idlwave-libinfo-file} needs to contain the path to a file in an | |
1609 existing directory (e.g. @code{"~/idlwave_libinfo.el"}). Since the file | |
1610 will contain lisp code, it should end in @file{.el}. Under Windows and | |
1611 MacOS, you also need to specify the search path for IDL library files in | |
1612 the variable @code{idlwave-library-path}. Under UNIX, this path will | |
1613 be automatically inferred from an IDLWAVE shell.@refill | |
1614 | |
1615 The command @kbd{M-x idlwave-create-libinfo-file} can then be used to | |
1616 scan library files. It brings up a widget in which you can select some | |
1617 or all directories on the search path. Pressing the @w{@samp{[Scan & Save]}} | |
1618 button in the widget will scan all files in the selected directories and | |
1619 write the resulting routine information into the file | |
1620 @code{idlwave-libinfo-file}. In order to update the library information | |
1621 from the same directories, call the command | |
1622 @code{idlwave-update-routine-info} with a double prefix argument: | |
1623 @kbd{C-u C-u C-c C-i}. This will rescan files in the previously | |
1624 selected directories, write an updated version of the libinfo file and | |
1625 rebuild IDLWAVEs internal lists.@refill | |
1626 | |
1627 A note of caution: Depending on your local installation, the IDL | |
1628 library can be very large. Parsing it for routine information will take | |
1629 time and loading this information into Emacs can require a | |
1630 significant amount of memory.@refill | |
1631 | |
1632 A routine which is both in the library listing and compiled under the | |
1633 shell will show up twice in the @file{*Completions*} listing. This is | |
1634 usually not a serious problem. However, if you have scanned the part of | |
1635 the library relevant for you, and if you are not compiling files which | |
1636 are not on the library search path, the information about compiled | |
1637 routines is in fact unnecessary. In this case, you can turn of the | |
1638 shell query for compiled routines with the variable | |
1639 @code{idlwave-query-shell-for-routine-info}.@refill | |
1640 | |
1641 @defopt idlwave-libinfo-file | |
1642 File for routine information of the IDL library. | |
1643 @end defopt | |
1644 | |
1645 @defopt idlwave-library-path | |
1646 IDL library path for Windows and MacOS. Not needed under Unix. | |
1647 @end defopt | |
1648 | |
1649 | |
1650 @node Updating idlwave-rinfo.el, , Library Scan, Sources of Routine Info | |
1651 @section Updating @file{idlwave-rinfo.el} | |
1652 @cindex @file{get_rinfo} | |
1653 @cindex @file{idlwave.rinfo.el} | |
1654 @cindex Perl program, to create @file{idlwave.rinfo.el} | |
1655 | |
1656 The file @file{idlwave-rinfo.el} contains the routine information for | |
1657 the routines build into IDL. This constant depends upon the version of | |
1658 IDL. If you are lucky, the maintainer of IDLWAVE will always have | |
1659 access to the newest version of IDL and provide updates of | |
1660 @file{idlwave-rinfo.el} reflecting the currently released version of | |
1661 IDL. The IDLWAVE package also contains a Perl program @file{get_rinfo} | |
1662 which constructs this file by scanning selected files from the IDL | |
1663 documentation. The program needs @file{pdftotext} by Derek B. Noonburg. | |
1664 Instructions on how to use @file{get_rinfo} are in the program | |
1665 itself.@refill | |
1666 | |
1667 @node Configuration Examples, Index, Sources of Routine Info, Top | |
1668 @appendix Configuration Examples | |
1669 @cindex Configuration examples | |
1670 @cindex Example configuration | |
1671 | |
1672 @noindent | |
1673 @b{Question:} So now you have all these complicated configuration | |
1674 options in your package, but which ones do @emph{you} as the maintainer | |
1675 actually set in your own configuration? | |
1676 | |
1677 @noindent | |
1678 @b{Answer:} Hardly any. As the maintainer, I set the default of all | |
1679 options to what I think is best. However, I do not turn on features by | |
1680 default which | |
1681 @itemize @minus | |
1682 @item | |
1683 are not self-evident (i.e. too magic) when used by an unsuspecting user | |
1684 @item | |
1685 are too intrusive | |
1686 @item | |
1687 will not work properly on all Emacs installations out there | |
1688 @item | |
1689 break with what I think are widely used standards. | |
1690 @end itemize | |
1691 | |
1692 @noindent To see what I mean, here is the entire configuration I have in | |
1693 my @file{.emacs}: | |
1694 | |
1695 @lisp | |
1696 (setq idlwave-shell-activate-alt-keybindings t | |
1697 idlwave-expand-generic-end t | |
1698 idlwave-store-inquired-class t | |
1699 idlwave-shell-automatic-start t | |
1700 idlwave-libinfo-file "~/lib/idl/libinfo.el" | |
1701 idlwave-main-block-indent 2) | |
1702 (add-hook 'idlwave-shell-mode-hook | |
1703 (lambda() | |
1704 (define-key idlwave-mode-map [(shift button1)] | |
1705 'idlwave-shell-mouse-print) | |
1706 (define-key idlwave-mode-map [(shift button2)] | |
1707 'idlwave-shell-mouse-help))) | |
1708 @end lisp | |
1709 | |
1710 However, if you are an Emacs power-user and want IDLWAVE to work | |
1711 completely differently, the options allow you to change almost every | |
1712 aspect of it. Here is an example of a much more extensive configuration | |
1713 of IDLWAVE. To say it again - this is not what I recommend, but the | |
1714 user is King!@refill | |
1715 | |
1716 @example | |
1717 ;;; Settings for IDLWAVE mode | |
1718 | |
1719 (setq idlwave-block-indent 3) ; Indentation settings | |
1720 (setq idlwave-main-block-indent 3) | |
1721 (setq idlwave-end-offset -3) | |
1722 (setq idlwave-continuation-indent 1) | |
1723 (setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" | |
1724 ; anchored at start of line. | |
1725 (setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> | |
1726 (setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' | |
1727 (setq idlwave-expand-generic-end t) ; convert END to ENDIF etc... | |
1728 (setq idlwave-reserved-word-upcase t) ; Make reserved words upper case | |
1729 ; (with abbrevs only) | |
1730 (setq idlwave-abbrev-change-case nil) ; Don't force case of expansions | |
1731 (setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill | |
1732 (setq idlwave-show-block nil) ; Turn off blinking to begin | |
1733 (setq idlwave-abbrev-move t) ; Allow abbrevs to move point | |
1734 | |
1735 ;; Some setting can only be done from a mode hook. Here is an example: | |
1736 | |
1737 (add-hook 'idlwave-mode-hook | |
1738 (lambda () | |
1739 (setq abbrev-mode 1) ; Turn on abbrevs (-1 for off) | |
1740 (setq case-fold-search nil) ; Make searches case sensitive | |
1741 ;; Run other functions here | |
1742 (font-lock-mode 1) ; Turn on font-lock mode | |
1743 (idlwave-auto-fill-mode 0) ; Turn off auto filling | |
1744 ;; | |
1745 ;; Pad with with 1 space (if -n is used then make the | |
1746 ;; padding a minimum of n spaces.) The defaults use -1 | |
1747 ;; instead of 1. | |
1748 (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1)) | |
1749 (idlwave-action-and-binding "<" '(idlwave-surround 1 1)) | |
1750 (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-))) | |
1751 (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) | |
1752 ;; | |
1753 ;; Only pad after comma and with exactly 1 space | |
1754 (idlwave-action-and-binding "," '(idlwave-surround nil 1)) | |
1755 ;; | |
1756 ;; Set some personal bindings | |
1757 ;; (In this case, makes `,' have the normal self-insert behavior.) | |
1758 (local-set-key "," 'self-insert-command) | |
1759 ;; Create a newline, indenting the original and new line. | |
1760 ;; A similar function that does _not_ reindent the original | |
1761 ;; line is on "\C-j" (The default for emacs programming modes). | |
1762 (local-set-key "\n" 'idlwave-newline) | |
1763 ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. | |
1764 )) | |
1765 | |
1766 ;;; Settings for IDLWAVE SHELL mode | |
1767 | |
1768 (setq idlwave-shell-overlay-arrow "=>") ; default is ">" | |
1769 (setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame | |
1770 (setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> " | |
1771 (setq idlwave-shell-explicit-file-name "wave") | |
1772 (setq idlwave-shell-process-name "wave") | |
1773 (setq idlwave-shell-use-dedicated-frame t) ; Shell on separate frame | |
1774 (setq idlwave-shell-use-toolbar nil) ; No toolbar | |
1775 @end example | |
1776 | |
1777 @node Index, , Configuration Examples, Top | |
1778 @unnumbered Index | |
1779 @printindex cp | |
1780 | |
1781 @summarycontents | |
1782 @contents | |
1783 @bye | |
1784 |