(map-keymap): Definition deleted.
[emacs.git] / man / idlwave.texi
blob9c8037901716c574c6b3dc7ac7df9a43c7f6c922
1 \input texinfo  @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename ../info/idlwave
4 @settitle IDLWAVE User Manual
5 @synindex ky cp
6 @syncodeindex vr cp
7 @syncodeindex fn cp
8 @set VERSION 4.15
9 @set EDITION 4.15
10 @set IDLVERSION 5.5
11 @set NSYSROUTINES 1324
12 @set NSYSKEYWORDS 6129
13 @set DATE September 2002
14 @set AUTHOR J.D. Smith & Carsten Dominik
15 @set AUTHOR-EMAIL dominik@@astro.uva.nl
16 @set MAINTAINER J.D. Smith
17 @set MAINTAINER-EMAIL jdsmith@@as.arizona.edu
18 @set IDLWAVE-HOMEPAGE http://idlwave.org/
19 @c %**end of header
21 @copying
22 This file documents IDLWAVE, a major mode for editing IDL files with
23 Emacs, and interacting with an IDL shell run as a subprocess.
25 This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE
26 @value{VERSION}
28 Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation,
29 Inc.
31 @quotation
32 Permission is granted to copy, distribute and/or modify this document
33 under the terms of the GNU Free Documentation License, Version 1.1 or
34 any later version published by the Free Software Foundation; with no
35 Invariant Sections, with the Front-Cover texts being ``A GNU
36 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
37 license is included in the section entitled ``GNU Free Documentation
38 License'' in the Emacs manual.
40 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
41 this GNU Manual, like GNU software.  Copies published by the Free
42 Software Foundation raise funds for GNU development.''
44 This document is part of a collection distributed under the GNU Free
45 Documentation License.  If you want to distribute this document
46 separately from the collection, you can do so by adding a copy of the
47 license to the document, as described in section 6 of the license.
48 @end quotation
49 @end copying
51 @dircategory Emacs
52 @direntry
53 * IDLWAVE: (idlwave).   Major mode and shell for IDL files.
54 @end direntry
56 @finalout
58 @titlepage
59 @title IDLWAVE User Manual
60 @subtitle Emacs major mode and shell for IDL
61 @subtitle Edition @value{EDITION}, @value{DATE}
63 @author by Carsten Dominik & J.D. Smith
64 @page
65 This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for
66 IDLWAVE version @value{VERSION}, @value{DATE}.
67 @cindex Copyright, of IDLWAVE
68 @insertcopying
69 @end titlepage
70 @contents
72 @page
74 @ifnottex
76 @node Top, Introduction, (dir), (dir)
78 IDLWAVE is a package which supports editing source for the
79 Interactive Data Language (IDL), and running IDL as an inferior
80 shell.
82 @end ifnottex
84 @menu
85 * Introduction::                What IDLWAVE is and what it's not
86 * IDLWAVE in a Nutshell::       One page quick-start guide
87 * Getting Started::             Tutorial
88 * The IDLWAVE Major Mode::      The mode to edit IDL programs
89 * The IDLWAVE Shell::           The mode to run IDL as an inferior program
90 * Installation::                How to Install or Upgrade
91 * Acknowledgements::            Who did what
92 * Sources of Routine Info::     How does IDLWAVE know about routine XYZ
93 * Configuration Examples::      The user is king...
94 * Windows and MacOS::           What still works, and how
95 * Index::                       Fast access
97 @detailmenu
98  --- The Detailed Node Listing ---
100 Getting Started (Tutorial)
102 * Lesson I -- Development Cycle::
103 * Lesson II -- Customization::
104 * Lesson III -- Library Catalog::
106 The IDLWAVE Major Mode
108 * Code Formatting::             Making code look nice
109 * Routine Info::                Calling Sequence and Keyword List
110 * Online Help::                 One key press from source to help
111 * Completion::                  Completing routine names and Keywords
112 * Routine Source::              Finding routines, the easy way
113 * Resolving Routines::          Force the Shell to compile a routine
114 * Code Templates::              Frequent code constructs
115 * Abbreviations::               Abbreviations for common commands
116 * Actions::                     Changing case, Padding, End checking
117 * Doc Header::                  Inserting a standard header
118 * Motion Commands::             Moving through the structure of a program
119 * Misc Options::                Things that fit nowhere else
121 Code Formatting
123 * Code Indentation::            Reflecting the logical structure
124 * Continued Statement Indentation::
125 * Comment Indentation::         Special indentation for comment lines
126 * Continuation Lines::          Splitting statements over lines
127 * Syntax Highlighting::         Font-lock support
128 * Octals and Highlighting::     Why "123 causes problems
130 Completion
132 * Case of Completed Words::     CaseOFcomPletedWords
133 * Object Method Completion and Class Ambiguity::  obj->Method, what?
134 * Object Method Completion in the Shell::
135 * Class and Keyword Inheritance::  obj->Method, _EXTRA=e
136 * Structure Tag Completion::    Completing state.Tag
138 Actions
140 * Block Boundary Check::        Is the END statement correct?
141 * Padding Operators::           Enforcing space around `=' etc
142 * Case Changes::                Enforcing upper case keywords
144 The IDLWAVE Shell
146 * Starting the Shell::          How to launch IDL as a subprocess
147 * Using the Shell::             Interactively working with the Shell
148 * Commands Sent to the Shell::
149 * Debugging IDL Programs::
150 * Examining Variables::
151 * Custom Expression Examination::
153 Debugging IDL Programs
155 * Debug Key Bindings::
156 * Compiling Programs::
157 * Breakpoints and Stepping::
158 * Walking the Calling Stack::
160 Installation
162 * Installing IDLWAVE::          How to install the distribution
163 * Installing Online Help::      Where to get the additional files needed
164 * Upgrading from idl.el::       Necessary configuration changes
166 Sources of Routine Info
168 * Routine Definitions::         Where IDL Routines are defined.
169 * Routine Information Sources::  So how does IDLWAVE know about...
170 * Library Catalog::             Scanning the Libraries for Routine Info
171 * Load-Path Shadows::           Routines defined in several places
172 * Documentation Scan::          Scanning the IDL Manuals
174 @end detailmenu
175 @end menu
177 @node Introduction, IDLWAVE in a Nutshell, Top, Top
178 @chapter Introduction
179 @cindex Introduction
180 @cindex CORBA (Common Object Request Broker Architecture)
181 @cindex Interface Definition Language
182 @cindex Interactive Data Language
183 @cindex cc-mode.el
184 @cindex @file{idl.el}
185 @cindex @file{idl-shell.el}
186 @cindex Feature overview
188 IDLWAVE is a package which supports editing source files for the
189 Interactive Data Language (IDL@footnote{IDL is a registered trademark of
190 Research Systems, Inc., a Kodak Company}), and for running IDL as an
191 inferior shell@footnote{Note that this package has nothing to do with
192 the Interface Definition Language, part of the Common Object Request
193 Broker Architecture (CORBA)}.  It can also be used for editing source
194 files for the related WAVE/CL language, but with only limited
195 support.
197 IDLWAVE consists of two main parts: a major mode for editing IDL source
198 files files (@code{idlwave-mode}) and a mode for running the IDL program
199 as an inferior shell (@code{idlwave-shell-mode}).  Although one mode can
200 be used without the other, both work together closely to form a complete
201 development environment. Here is a brief summary of what IDLWAVE does:
203 @itemize @bullet
204 @item
205 Code indentation and formatting.
206 @item
207 Three level syntax highlighting support.
208 @item
209 Context-sensitive display of calling sequences and keywords for more
210 than 1000 native IDL routines, extendible to any number of additional
211 routines in your local IDL libraries.
212 @item
213 Routine name space conflict search, likelihood-of-use ranking.
214 @item
215 Fast, context-sensitive online help.
216 @item
217 Context sensitive completion of routine names and keywords.
218 @item
219 Easy insertion of code templates.
220 @item
221 Automatic corrections to enforce a variety of customizable coding
222 standards.
223 @item
224 Integrity checks and auto-termination of logical blocks.
225 @item
226 Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs).
227 @item
228 Documentation support.
229 @item
230 Running IDL as an inferior Shell with history search, command line
231 editing and all the completion and routine info capabilities present in
232 IDL source buffers.
233 @item
234 Compilation, execution and interactive debugging of programs directly
235 from the source buffer.
236 @item
237 Quick, source-guided navigation of the calling stack, with variable
238 inspection, etc.
239 @item
240 Examining variables and expressions with a mouse click.
241 @item
242 And much, much more...
243 @end itemize
245 @ifnottex
246 @cindex Screenshots
247 Here are a number of screenshots showing IDLWAVE in action:
249 @itemize @bullet
250 @item
251 @uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer}
252 @item
253 @uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed}
254 @item
255 @uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.}
256 @item
257 @uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed}
258 @item
259 @uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code
260 stopped at a breakpoint}
261 @end itemize
262 @end ifnottex
264 IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el}
265 files written by Chris Chase.  The modes and files had to be renamed
266 because of a name space conflict with CORBA's @code{idl-mode}, defined in
267 Emacs in the file @file{cc-mode.el}.  If you have been using the old
268 files, check @ref{Upgrading from idl.el} for information on how to
269 switch.
271 In this manual, each section ends with a list of related user options.
272 Don't be confused by the sheer number of options available --- in most
273 cases the default settings are just fine.  The variables are listed here
274 to make sure you know where to look if you want to change anything.  For
275 a full description of what a particular variable does and how to
276 configure it, see the documentation string of that variable (available
277 with @kbd{C-h v}).  Some configuration examples are also given in the
278 appendix.
280 @node IDLWAVE in a Nutshell, Getting Started, Introduction, Top
281 @chapter IDLWAVE in a Nutshell
282 @cindex Summary of important commands
283 @cindex IDLWAVE in a Nutshell
284 @cindex Nutshell, IDLWAVE in a
286 @subheading Editing IDL Programs
288 @multitable @columnfractions .15 .85
289 @item @key{TAB}
290 @tab Indent the current line relative to context.
291 @item @kbd{C-M-\}
292 @tab Re-indent all lines in the current region.
293 @item @kbd{C-u @key{TAB}}
294 @tab Re-indent all lines in the current statement.
295 @item @kbd{M-@key{RET}}
296 @tab Start a continuation line, or split the current line at point.
297 @item @kbd{M-q}
298 @tab Fill the current comment paragraph.
299 @item @kbd{C-c ?}
300 @tab Display calling sequence and keywords for the procedure or function call
301 at point.
302 @item @kbd{M-?}
303 @tab Load context sensitive online help for nearby routine, keyword, etc.
304 @item @kbd{M-@key{TAB}}
305 @tab Complete a procedure name, function name or keyword in the buffer.
306 @item @kbd{C-c C-i}
307 @tab Update IDLWAVE's knowledge about functions and procedures.
308 @item @kbd{C-c C-v}
309 @tab Visit the source code of a procedure/function.
310 @item @kbd{C-c C-h}
311 @tab Insert a standard documentation header.
312 @item @kbd{C-c @key{RET}}
313 @tab Insert a new timestamp and history item in the documentation header.
314 @end multitable
316 @subheading Running the IDLWAVE Shell, Debugging Programs
318 @multitable @columnfractions .15 .85
319 @item @kbd{C-c C-s}
320 @tab Start IDL as a subprocess and/or switch to the interaction buffer.
321 @item @kbd{M-p}
322 @tab Cycle back through IDL command history.
323 @item @kbd{M-n}
324 @tab Cycle forward.
325 @item @kbd{M-@key{TAB}}
326 @tab Complete a procedure name, function name or keyword in the shell buffer.
327 @item @kbd{C-c C-d C-c}
328 @tab Save and compile the source file in the current buffer.
329 @item @kbd{C-c C-d C-x}
330 @tab Goto next syntax error.
331 @item @kbd{C-c C-d C-b}
332 @tab Set a breakpoint at the nearest viable source line.
333 @item @kbd{C-c C-d C-d}
334 @tab Clear the nearest breakpoint.
335 @item @kbd{C-c C-d C-p}
336 @tab Print the value of the expression near point in IDL.
337 @end multitable
339 @subheading Commonly used Settings in @file{.emacs}
340 @lisp
341 ;; Change the indentation preferences
342 (setq idlwave-main-block-indent 2   ; default  0
343       idlwave-block-indent 2        ; default  4
344       idlwave-end-offset -2)        ; default -4
345 ;; Start autoloading routine info after 2 idle seconds
346 (setq idlwave-init-rinfo-when-idle-after 2)
347 ;; Pad some operators with spaces
348 (setq idlwave-do-actions t
349       idlwave-surround-by-blank t)
350 ;; Syntax Highlighting
351 (add-hook 'idlwave-mode-hook 'turn-on-font-lock)
352 ;; Automatically start the shell when needed
353 (setq idlwave-shell-automatic-start t)
354 ;; Bind debugging commands with CONTROL and SHIFT modifiers
355 (setq idlwave-shell-debug-modifiers '(control shift))
356 ;; Specify the online help files' location.
357 (setq idlwave-help-directory "~/.idlwave")
358 @end lisp
360 @ifhtml
361 <A NAME="TUTORIAL"></A>
362 @end ifhtml
363 @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top
364 @chapter Getting Started (Tutorial)
365 @cindex Quick-Start
366 @cindex Tutorial
367 @cindex Getting Started
369 @menu
370 * Lesson I -- Development Cycle::
371 * Lesson II -- Customization::
372 * Lesson III -- Library Catalog::
373 @end menu
375 @node  Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started
376 @section Lesson I: Development Cycle
378 The purpose of this tutorial is to guide you through a very basic
379 development cycle using IDLWAVE.  We will paste a simple program into a
380 buffer and use the shell to compile, debug and run it.  On the way we
381 will use many of the important IDLWAVE commands.  Note however that
382 there are many more capabilities in IDLWAVE than covered here, which can
383 be discovered by reading the entire manual.
385 It is assumed that you have access to Emacs or XEmacs with the full
386 IDLWAVE package including online help (@pxref{Installation}).  We also
387 assume that you are familiar with Emacs and can read the nomenclature of
388 key presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL}
389 and @kbd{M} for @key{META} (often the @key{ALT} key carries this
390 functionality)).
392 Open a new source file by typing:
394 @example
395 @kbd{C-x C-f tutorial.pro @key{RET}}
396 @end example
398 A buffer for this file will pop up, and it should be in IDLWAVE mode, as
399 shown in the mode line just below the editing window.  Also, the menu
400 bar should contain entries @samp{IDLWAVE} and @samp{Debug}.
402 Now cut-and-paste the following code, also available as
403 @file{tutorial.pro} in the IDLWAVE distribution.
405 @example
406 function daynr,d,m,y
407   ;; compute a sequence number for a date
408   ;; works 1901-2099.
409   if y lt 100 then y = y+1900
410   if m le 2 then delta = 1 else delta = 0
411   m1 = m + delta*12 + 1
412   y1 = y * delta
413   return, d + floor(m1*30.6)+floor(y1*365.25)+5
416 function weekday,day,month,year
417   ;; compute weekday number for date
418   nr = daynr(day,month,year)
419   return, nr mod 7
422 pro plot_wday,day,month
423   ;; Plot the weekday of a date in the first 10 years of this century.
424   years = 2000,+indgen(10)
425   wdays = intarr(10)
426   for i=0,n_elements(wdays)-1 do begin
427       wdays[i] =  weekday(day,month,years[i])
428   end
429   plot,years,wdays,YS=2,YT="Wday (0=Sunday)"
431 @end example
433 The indentation probably looks funny, since it's different from the
434 settings you use, so use the @key{TAB} key in each line to automatically
435 line it up (or more quickly @emph{select} the entire buffer with
436 @kbd{C-x h}, and indent the whole region with @kbd{C-M-\}).  Notice how
437 different syntactical elements are highlighted in different colors, if
438 you have set up support for font-lock.
440 Let's check out two particular editing features of IDLWAVE.  Place the
441 cursor after the @code{end} statement of the @code{for} loop and press
442 @key{SPC}.  IDLWAVE blinks back to the beginning of the block and
443 changes the generic @code{end} to the specific @code{endfor}
444 automatically.  Now place the cursor in any line you would like to split
445 and press @kbd{M-@key{RET}}.  The line is split at the cursor position,
446 with the continuation @samp{$} and indentation all taken care of.  Use
447 @kbd{C-/} to undo the last change.
449 The procedure @code{plot_wday} is supposed to plot the weekday of a
450 given date for the first 10 years of the 21st century.  As in most code,
451 there are a few bugs, which we are going to use IDLWAVE to help us fix.
453 First, let's launch the IDLWAVE shell.  You do this with the command
454 @kbd{C-c C-s}.  The Emacs window will split and display IDL running in a
455 shell interaction buffer.  Type a few commands like @code{print,!PI} to
456 convince yourself that you can work there just as well as in a terminal,
457 or the IDLDE.  Use the arrow keys to cycle through your command history.
458 Are we having fun now?
460 Now go back to the source window and type @kbd{C-c C-d C-c} to compile
461 the program.  If you watch the shell buffer, you see that IDLWAVE types
462 @samp{.run tutorial.pro} for you.  But the compilation fails because
463 there is a comma in the line @samp{years=...}.  The line with the error
464 is highlighted and the cursor positioned at the error, so remove the
465 comma (you should only need to hit @kbd{Delete}!).  Compile again, using
466 the same keystrokes as before.  Notice that the file is automatically
467 saved for you.  This time everything should work fine, and you should
468 see the three routines compile.
470 Now we want to use the command to plot the day of the week on January
471 1st.  We could type the full command ourselves, but why do that?  Go
472 back to the shell window, type @samp{plot_} and hit @key{TAB}.  After a
473 bit of a delay (while IDLWAVE initializes its routine info database, if
474 necessary), the window will split to show all procedures it knows
475 starting with that string, and @w{@code{plot_wday}} should be one of
476 them.  Saving the buffer alerted IDLWAVE about this new routine.  Click
477 with the middle mouse button on @code{plot_wday} and it will be copied
478 to the shell buffer, or if you prefer, add @samp{w} to @samp{plot_} to
479 make it unambiguous, hit @key{TAB} again, and the full routine name will
480 be completed.  Now provide the two arguments:
482 @example
483 plot_wday,1,1
484 @end example
486 and press @key{RET}.  This fails with an error message telling you the
487 @code{YT} keyword to plot is ambiguous.  What are the allowed keywords
488 again?  Go back to the source window and put the cursor into the `plot'
489 line, and press @kbd{C-c ?}.  This shows the routine info window for the
490 plot routine, which contains a list of keywords, along with the argument
491 list.  Oh, we wanted @code{YTITLE}.  Fix that up.  Recompile with
492 @kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press
493 the @key{UP} arrow to recall the previous command and execute again.
495 This time we get a plot, but it is pretty ugly --- the points are all
496 connected with a line.  Hmm, isn't there a way for @code{plot} to use
497 symbols instead?  What was that keyword?  Position the cursor on the
498 plot line after a comma (where you'd normally type a keyword), and hit
499 @kbd{M-@key{Tab}}.  A long list of plot's keywords appears.  Aha, there
500 it is, @code{PSYM}.  Middle click to insert it.  An @samp{=} sign is
501 included for you too.  Now what were the values of @code{PSYM} supposed
502 to be?  With the cursor on or after the keyword, press @kbd{M-?} for
503 online help (alternatively, you could have right clicked on the colored
504 keyword itself in the completion list).  The online help window will pop
505 up showing the documentation for the @code{PYSM} keyword.  OK, let's use
506 diamonds=4.  Fix this, recompile (you know the command by now: @kbd{C-c
507 C-d C-c}, go back to the shell (if it's vanished, you know the command
508 to recall it by now: @kbd{C-c C-s}) and execute again.  Now things look
509 pretty good.
511 Let's try a different day --- how about April fool's day?
513 @example
514 plot_wday,1,4
515 @end example
517 Oops, this looks very wrong.  All April fool's days cannot be Fridays!
518 We've got a bug in the program, perhaps in the @code{daynr} function.
519 Let's put a breakpoint on the last line there.  Position the cursor on
520 the @samp{return, d+...} line and press @kbd{C-c C-d C-b}.  IDL sets a
521 breakpoint (as you see in the shell window), and the line is highlighted
522 in some way.  Back to the shell buffer, re-execute the previous command.
523 IDL stops at the line with the breakpoint.  Now hold down the SHIFT key
524 and click with the middle mouse button on a few variables there:
525 @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc.  Maybe @code{d} isn't the
526 correct type.  CONTROL-SHIFT middle-click on it for help.  Well, it's an
527 integer, so that's not the problem.  Aha, @samp{y1} is zero, but it
528 should be the year, depending on delta.  Shift click @samp{delta} to see
529 that it's 0.  Below, we see the offending line: @samp{y1=y*delta...} the
530 multiplication should have been a minus sign!  So fix the line to read:
532 @example
533 y1 = y - delta
534 @end example
536 Now remove all breakpoints: @kbd{C-c C-d C-a}.  Recompile and rerun the
537 command.  Everything should now work fine.  How about those leap years?
538 Change the code to plot 100 years and see that every 28 years, the
539 sequence of weekdays repeats.
541 @node  Lesson II -- Customization, Lesson III -- Library Catalog, Lesson I -- Development Cycle, Getting Started
542 @section Lesson II: Customization
544 Emacs is probably the most customizable piece of software available, and
545 it would be a shame if you did not make use of this and adapt IDLWAVE to
546 your own preferences.  Customizing Emacs or IDLWAVE is accomplished by
547 setting Lisp variables in the @file{.emacs} file in your home directory
548 --- but do not be dismayed; for the most part, you can just copy and work
549 from the examples given here.
551 Let's first use a boolean variable.  These are variables which you turn
552 on or off, much like a checkbox. A value of @samp{t} means on, a value
553 of @samp{nil} means off.  Copy the following line into your
554 @file{.emacs} file, exit and restart Emacs.
556 @lisp
557 (setq idlwave-reserved-word-upcase t)
558 @end lisp
560 When this option is turned on, each reserved word you type into an IDL
561 source buffer will be converted to upper case when you press @key{SPC}
562 or @key{RET} right after the word.  Try it out!  @samp{if} changes to
563 @samp{IF}, @samp{begin} to @samp{BEGIN}.  If you don't like this
564 behavior, remove the option again from your @file{.emacs} file.
566 You likely have your own indentation preferences for IDL code.  For
567 example, some like to indent the main block of an IDL program from the
568 margin, different from the conventions used by RSI, and use only 3
569 spaces as indentation between @code{BEGIN} and @code{END}.  Try the
570 following lines in @file{.emacs}:
572 @lisp
573 (setq idlwave-main-block-indent 2)
574 (setq idlwave-block-indent 3)
575 (setq idlwave-end-offset -3)
576 @end lisp
578 Restart Emacs, and re-indent the program we developed in the first part
579 of this tutorial with @kbd{C-c h} and @kbd{C-M-\}.  You may want to keep
580 these lines in @file{.emacs}, with values adjusted to your likings.  If
581 you want to get more information about any of these variables, type,
582 e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}.  To find which
583 variables can be customized, look for items marked @samp{User Option:}
584 throughout this manual.
586 If you cannot seem to master this Lisp customization in @file{.emacs},
587 there is another, more user-friendly way to customize all the IDLWAVE
588 variables.  You can access it through the IDLWAVE menu in one of the
589 @file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE
590 Group}. Here you'll be presented with all the various variables grouped
591 into categories.  You can navigate the hierarchy (e.g. Idlwave Code
592 Formatting->Idlwave Main Block Indent), read about the variables, change
593 them, and `Save for Future Sessions'.  Few of these variables need
594 customization, but you can exercise considerable control over IDLWAVE's
595 functionality with them.
597 You may also find the key bindings used for the debugging commands too
598 long and complicated.  Often we have heard such complaints, ``Do I
599 really have to type @kbd{C-c C-d C-c} to run a simple command?''  Due to
600 Emacs rules and conventions, shorter bindings cannot be set by default,
601 but you can enable them.  First, there is a way to assign all debugging
602 commands in a single sweep to other combinations.  The only problem is
603 that we have to use something which Emacs does not need for other
604 important commands.  One good option is to execute debugging commands by
605 holding down @key{CONTROL} and @key{SHIFT} while pressing a single
606 character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for
607 compiling the current source file, @kbd{C-S-a} for deleting all
608 breakpoints.  You can enable this with:
610 @lisp
611 (setq idlwave-shell-debug-modifiers '(shift control))
612 @end lisp
614 @noindent If you have a special keyboard with, for example, a
615 @key{HYPER} key, you could even shorten that:
617 @lisp
618 (setq idlwave-shell-debug-modifiers '(hyper))
619 @end lisp
621 @noindent to get compilation on @kbd{H-c}.  Often, a modifier key like
622 @key{HYPER} or @key{SUPER} is bound or can be bound to an otherwise
623 unused key -- consult your system documentation.
625 You can also assign specific commands to keys.  This you must do in the
626 @emph{mode-hook}, a special function which is run when a new buffer gets
627 set up.  Keybindings can only be done when the buffer exists.  The
628 possibilities for key customization are endless.  Here we set function
629 keys f5-f8 to common debugging commands.
631 @lisp
632 ;; First for the source buffer
633 (add-hook 'idlwave-mode-hook
634    (lambda ()
635     (local-set-key [f5] 'idlwave-shell-break-here)
636     (local-set-key [f6] 'idlwave-shell-clear-current-bp)
637     (local-set-key [f7] 'idlwave-shell-cont)
638     (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
639 ;; Then for the shell buffer
640 (add-hook 'idlwave-shell-mode-hook
641    (lambda ()
642     (local-set-key [f5] 'idlwave-shell-break-here)
643     (local-set-key [f6] 'idlwave-shell-clear-current-bp)
644     (local-set-key [f7] 'idlwave-shell-cont)
645     (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
646 @end lisp
648 @node  Lesson III -- Library Catalog,  , Lesson II -- Customization, Getting Started
649 @section Lesson III: Library Catalog
651 We have already used the routine info display in the first part of this
652 tutorial.  This was the key @kbd{C-c ?} which displays information about
653 the IDL routine near the cursor position.  Wouldn't it be nice
654 to have the same available for your own library routines and for the
655 huge amount of code in major extension libraries like JHUPL or the
656 IDL-Astro library?  To do this, you must give IDLWAVE a chance to study
657 these routines first.  We call this @emph{Building the library catalog}.
659 From the IDLWAVE entry in the menu bar, select @code{Routine Info/Select
660 Catalog Directories}.  If necessary, start the shell first with @kbd{C-c
661 C-s} (@pxref{Starting the Shell}).  IDLWAVE will find out about the IDL
662 @code{!PATH} variable and offer a list of directories on the path.
663 Simply select them all (or whichever you want) and click on the
664 @samp{Scan&Save} button.  Then go for a cup of coffee while IDLWAVE
665 collects information for each and every IDL routine on your search path.
666 All this information is written to the file @file{.idlcat} in your home
667 directory and will from now one be automatically loaded whenever you use
668 IDLWAVE.  You may find it necessary to rebuild the catalog on occasion
669 as your local libraries change.  Try to use routine info (@kbd{C-c ?})
670 or completion (@kbd{M-@key{TAB}}) while on any routine or partial routine
671 name you know to be located in the library.  E.g., if you have scanned
672 the IDL-Astro library:
674 @example
675     a=readf@key{M-<TAB>}
676 @end example
679 expands to `readfits('.  Then try
681 @example
682     a=readfits(@key{C-c ?}
683 @end example
685 and you get:
687 @example
688 Usage:    Result = READFITS(filename, header, heap)
690 @end example
692 I hope you made it until here.  Now you are set to work with IDLWAVE.
693 On the way you will want to change other things, and to learn more about
694 the possibilities not discussed in this short tutorial.  Read the
695 manual, look at the documentation strings of interesting variables (with
696 @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining
697 questions on the newsgroup @code{comp.lang.idl-pvwave}.
699 @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top
700 @chapter The IDLWAVE Major Mode
701 @cindex IDLWAVE major mode
702 @cindex Major mode, @code{idlwave-mode}
704 The IDLWAVE major mode supports editing IDL source files.  In this
705 chapter we describe the main features of the mode and how to customize
706 them.
708 @menu
709 * Code Formatting::             Making code look nice
710 * Routine Info::                Calling Sequence and Keyword List
711 * Online Help::                 One key press from source to help
712 * Completion::                  Completing routine names and Keywords
713 * Routine Source::              Finding routines, the easy way
714 * Resolving Routines::          Force the Shell to compile a routine
715 * Code Templates::              Frequent code constructs
716 * Abbreviations::               Abbreviations for common commands
717 * Actions::                     Changing case, Padding, End checking
718 * Doc Header::                  Inserting a standard header
719 * Motion Commands::             Moving through the structure of a program
720 * Misc Options::                Things that fit nowhere else
721 @end menu
723 @node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode
724 @section Code Formatting
725 @cindex Code formatting
726 @cindex Formatting, of code
728 @menu
729 * Code Indentation::            Reflecting the logical structure
730 * Continued Statement Indentation::
731 * Comment Indentation::         Special indentation for comment lines
732 * Continuation Lines::          Splitting statements over lines
733 * Syntax Highlighting::         Font-lock support
734 * Octals and Highlighting::     Why "123 causes problems
735 @end menu
737 The IDL language, with it's early roots in FORTRAN, modern
738 implementation in C, and liberal borrowing of features of many vector
739 languages along its 25+ year history, has inherited an unusual mix of
740 syntax elements.  Left to his or her own devices, a novice IDL
741 programmer will often conjure code which is very difficult to read and
742 impossible to adapt.  Much can be gleaned from studying available IDL
743 code libraries for coding style pointers, but, due to the variety of
744 IDL syntax elements, replicating this style can be challenging at
745 best.  Luckily, IDLWAVE understands the structure of IDL code very
746 well, and takes care of almost all formatting issues for you.  After
747 configuring it to match your coding standards, you can rely on it to
748 help keep your code neat and organized.
750 @cindex Foreign code, adapting
751 @cindex Indentation, of foreign code
752 @kindex C-M-\
753 To re-indent a larger portion of code (e.g. when working with foreign code
754 written with different conventions), use @kbd{C-M-\}
755 (@code{indent-region}) after marking the relevant code.  Useful marking
756 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the
757 current subprogram). @xref{Actions}, for information how to impose
758 additional formatting conventions on foreign code.
760 @node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting
761 @subsection Code Indentation
762 @cindex Code indentation
763 @cindex Indentation
765 Like all Emacs programming modes, IDLWAVE performs code indentation.
766 The @key{TAB} key indents the current line relative to context.
767 @key{LFD} insert a newline and indents the new line.  The indentation is
768 governed by a number of variables.  IDLWAVE indents blocks (between
769 @code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and
770 continuation lines.
772 @defopt idlwave-main-block-indent (@code{0})
773 Extra indentation for the main block of code.  That is the block between
774 the FUNCTION/PRO statement and the END statement for that program
775 unit.
776 @end defopt
778 @defopt idlwave-block-indent (@code{4})
779 Extra indentation applied to block lines.  If you change this, you
780 probably also want to change @code{idlwave-end-offset}.
781 @end defopt
783 @defopt idlwave-end-offset (@code{-4})
784 Extra indentation applied to block END lines.  A value equal to negative
785 @code{idlwave-block-indent} will make END lines line up with the block
786 BEGIN lines.
787 @end defopt
789 @node Continued Statement Indentation, Comment Indentation, Code Indentation, Code Formatting
790 @subsection Continued Statement Indentation
791 @cindex Indentation, continued statement
792 @cindex Continued statement indentation
793 Continuation lines (following a line ending with @code{$}) can receive a
794 fixed indentation offset from the main level, but in several situations
795 IDLWAVE can use a special form of indentation which aligns continued
796 statements more naturally.  Special indentation is calculated for
797 continued routine definition statements and calls, enclosing parentheses
798 (like function calls, structure/class definitions, explicit structures
799 or lists, etc.), and continued assignments.  An attempt is made to line
800 up with the first non-whitespace character after the relevant opening
801 punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}).  For
802 lines without any non-comment characters on the line with the opening
803 punctuation, the continued line(s) are aligned just past the
804 punctuation.  An example:
806 @example
807 function foo, a, b,  $
808               c, d
809   bar =  sin( a + b + $
810               c + d)
812 @end example
813 @noindent
815 The only drawback to this special continued statement indentation is
816 that it consumes more space, e.g., for long function names or left hand
817 sides of an assignment:
819 @example
820 function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $
821                                                             c, d
822 @end example
824 You can instruct IDLWAVE when to avoid using this special continuation
825 indentation by setting the variable
826 @code{idlwave-max-extra-continuation-indent}, which specifies the
827 maximum additional indentation beyond the basic indent to be
828 tolerated, otherwise defaulting to a fixed-offset from the enclosing
829 indent (the size of which offset is set in
830 @code{idlwave-continuation-indent}).  Also, since the indentation
831 level can be somewhat dynamic in continued statements with special
832 continuation indentation, especially if
833 @code{idlwave-max-extra-continuation-indent} is small, the key
834 @kbd{C-u @key{TAB}} will re-indent all lines in the current statement.
835 Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil}, overrides
836 the @code{idlwave-max-extra-continuation-indent} limit, for
837 parentheses only, forcing them always to line up.
840 @defopt idlwave-continuation-indent (@code{2})
841 Extra indentation applied to normal continuation lines.
842 @end defopt
844 @defopt idlwave-max-extra-continuation-indent (@code{20})
845 The maximum additional indentation (over the basic continuation-indent)
846 that will be permitted for special continues.  To effectively disable
847 special continuation indentation, set to @code{0}.  To enable it
848 constantly, set to a large number (like @code{100}).  Note that the
849 indentation in a long continued statement never decreases from line to
850 line, outside of nested parentheses statements.
851 @end defopt
853 @defopt idlwave-indent-to-open-paren (@code{t})
854 Non-@code{nil} means indent continuation lines to innermost open
855 parenthesis, regardless of whether the
856 @code{idlwave-max-extra-continuation-indent} limit is satisfied.
857 @end defopt
859 @node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting
860 @subsection Comment Indentation
861 @cindex Comment indentation
862 @cindex Hanging paragraphs
863 @cindex Paragraphs, filling
864 @cindex Paragraphs, hanging
866 In IDL, lines starting with a @samp{;} are called @emph{comment lines}.
867 Comment lines are indented as follows:
869 @multitable @columnfractions .1 .90
870 @item @code{;;;}
871 @tab The indentation of lines starting with three semicolons remains
872 unchanged.
873 @item @code{;;}
874 @tab Lines starting with two semicolons are indented like the surrounding code.
875 @item @code{;}
876 @tab Lines starting with a single semicolon are indented to a minimum column.
877 @end multitable
879 @noindent
880 The indentation of comments starting in column 0 is never changed.
882 @defopt idlwave-no-change-comment
883 The indentation of a comment starting with this regexp will not be
884 changed.
885 @end defopt
887 @defopt idlwave-begin-line-comment
888 A comment anchored at the beginning of line.
889 @end defopt
891 @defopt idlwave-code-comment
892 A comment that starts with this regexp is indented as if it is a part of
893 IDL code.
894 @end defopt
896 @node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting
897 @subsection Continuation Lines and Filling
898 @cindex Continuation lines
899 @cindex Line splitting
900 @cindex String splitting
901 @cindex Splitting, of lines
903 @kindex M-@key{RET}
904 In IDL, a newline character terminates a statement unless preceded by a
905 @samp{$}.  If you would like to start a continuation line, use
906 @kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}.
907 It inserts the continuation character @samp{$}, terminates the line and
908 indents the new line.  The command @kbd{M-@key{RET}} can also be invoked
909 inside a string to split it at that point, in which case the @samp{+}
910 concatenation operator is used.
912 @cindex Filling
913 @cindex @code{auto-fill-mode}
914 @cindex Hanging paragraphs
915 When filling comment paragraphs, IDLWAVE overloads the normal filling
916 functions and uses a function which creates the hanging paragraphs
917 customary in IDL routine headers.  When @code{auto-fill-mode} is turned
918 on (toggle with @kbd{C-c C-a}), comments will be auto-filled.  If the
919 first line of a paragraph contains a match for
920 @code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent
921 lines are positioned to line up after it, as in the following example.
923 @example
924 @group
925 ;=================================
926 ; x - an array containing
927 ;     lots of interesting numbers.
929 ; y - another variable where
930 ;     a hanging paragraph is used
931 ;     to describe it.
932 ;=================================
933 @end group
934 @end example
936 @kindex M-q
937 You can also refill a comment at any time paragraph with @kbd{M-q}.
938 Comment delimiting lines as in the above example, consisting of one or
939 more @samp{;} followed by one or more of the characters @samp{+=-_*},
940 are kept in place, as is.
942 @defopt idlwave-fill-comment-line-only (@code{t})
943 Non-@code{nil} means auto fill will only operate on comment lines.
944 @end defopt
946 @defopt idlwave-auto-fill-split-string (@code{t})
947 Non-@code{nil} means auto fill will split strings with the IDL @samp{+}
948 operator.
949 @end defopt
951 @defopt idlwave-split-line-string (@code{t})
952 Non-@code{nil} means @code{idlwave-split-line} will split strings with
953 @samp{+}.
954 @end defopt
956 @defopt idlwave-hanging-indent (@code{t})
957 Non-@code{nil} means comment paragraphs are indented under the hanging
958 indent given by @code{idlwave-hang-indent-regexp} match in the first
959 line of the paragraph.
960 @end defopt
962 @defopt idlwave-hang-indent-regexp (@code{"- "})
963 Regular expression matching the position of the hanging indent
964 in the first line of a comment paragraph.
965 @end defopt
967 @defopt idlwave-use-last-hang-indent (@code{nil})
968 Non-@code{nil} means use last match on line for
969 @code{idlwave-indent-regexp}.
970 @end defopt
972 @node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting
973 @subsection Syntax Highlighting
974 @cindex Syntax highlighting
975 @cindex Highlighting of syntax
976 @cindex Font lock
978 Highlighting of keywords, comments, strings etc. can be accomplished
979 with @code{font-lock}.  If you are using @code{global-font-lock-mode}
980 (in Emacs), or have @code{font-lock} turned on in any other buffer in
981 XEmacs, it should also automatically work in IDLWAVE buffers.  If you'd
982 prefer invoking font-lock individually by mode, you can enforce it in
983 @code{idlwave-mode} with the following line in your @file{.emacs}:
985 @lisp
986 (add-hook 'idlwave-mode-hook 'turn-on-font-lock)
987 @end lisp
989 @noindent IDLWAVE supports 3 increasing levels of syntax highlighting.
990 The variable @code{font-lock-maximum-decoration} determines which level
991 is selected.  Individual categories of special tokens can be selected
992 for highlighting using the variable
993 @code{idlwave-default-font-lock-items}.
995 @defopt idlwave-default-font-lock-items
996 Items which should be fontified on the default fontification level
998 @end defopt
1000 @node Octals and Highlighting,  , Syntax Highlighting, Code Formatting
1001 @subsection Octals and Highlighting
1002 @cindex Syntax highlighting, Octals
1003 @cindex Highlighting of syntax, Octals
1005 A rare syntax highlighting problem results from the extremely
1006 unfortunate notation for octal numbers in IDL: @code{"123}.  This
1007 unpaired quotation mark is very difficult to parse, given that it can be
1008 mixed on a single line with any number of strings.  Emacs will
1009 incorrectly identify this as a string, and the highlighting of following
1010 lines of code can be distorted, since the string is never terminated.
1012 One solution to this involves terminating the mistakenly identified
1013 string yourself by providing a closing quotation mark in a comment:
1015 @example
1016   string("305B) + $ ;" <--- for font-lock
1017    ' is an Angstrom.'
1018 @end example
1020 @noindent A far better solution is to abandon this notation for octals
1021 altogether, and use the more sensible alternative IDL provides:
1023 @example
1024    string('305'OB) + ' is an Angstrom.'
1025 @end example
1027 @noindent This simultaneously solves the font-lock problem and is more
1028 consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}.
1030 @node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode
1031 @section Routine Info
1032 @cindex Routine info
1033 @cindex Updating routine info
1034 @cindex Scanning buffers for routine info
1035 @cindex Buffers, scanning for routine info
1036 @cindex Shell, querying for routine info
1038 @kindex C-c C-i
1039 IDL comes bundled with more than one thousand procedures, functions
1040 and object methods, and large libraries typically contain hundreds or
1041 even thousands more (each with a few to tens of keywords and
1042 arguments).  This large command set can make it difficult to remember
1043 the calling sequence and keywords for the routines you use, but
1044 IDLWAVE can help.  It builds up routine information using a wide
1045 variety of sources: IDLWAVE in fact knows far more about the routines
1046 on your system than IDL itself.  It maintains a list of all built-in
1047 routines, with calling sequences and keywords@footnote{This list is
1048 created by scanning the IDL manuals and might contain (very few)
1049 errors.  Please report any errors to the maintainer, so that they can
1050 be fixed.}.  It also scans Emacs buffers and library files for routine
1051 definitions, and queries the IDLWAVE-Shell for information about
1052 routines currently compiled there.  This information is updated
1053 automatically, and so should usually be current.  To force a global
1054 update and refresh the routine information, use @kbd{C-c C-i}
1055 (@code{idlwave-update-routine-info}).
1057 @kindex C-c ?
1058 To display the information about a routine, press @kbd{C-c ?}, which
1059 calls the command @code{idlwave-routine-info}.  When the current cursor
1060 position is on the name or in the argument list of a procedure or
1061 function, information will be displayed about the routine.  For example,
1062 consider the indicated cursor positions in the following line:
1064 @example
1065 plot,x,alog(x+5*sin(x) + 2),
1066   |  |   |   |   |  |  |    |
1067   1  2   3   4   5  6  7    8
1068 @end example
1070 @cindex Default routine, for info and help
1071 On positions 1,2 and 8, information about the @samp{plot} procedure will
1072 be shown.  On positions 3,4, and 7, the @samp{alog} function will be
1073 described, while positions 5 and 6 will investigate the @samp{sin}
1074 function.
1076 When you ask for routine information about an object method, and the
1077 method exists in several classes, IDLWAVE queries for the class of the
1078 object, unless the class is already known through a text property on the
1079 @samp{->} operator (@pxref{Object Method Completion and Class
1080 Ambiguity}), or by having been explicitly included in the call
1081 (e.g. @code{a->myclass::Foo}).
1083 @cindex Calling sequences
1084 @cindex Keywords of a routine
1085 @cindex Routine source information
1086 The description displayed contains the calling sequence, the list of
1087 keywords and the source location of this routine.  It looks like this:
1089 @example
1090 Usage:    XMANAGER, NAME, ID
1091 Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER
1092           JUST_REG MODAL NO_BLOCK
1093 Source:   SystemLib   [CSB] /soft1/idl53/lib/xmanager.pro
1094 @end example
1096 @cindex Categories, of routines
1097 @cindex Load-path shadows
1098 @cindex Shadows, load-path
1099 @cindex IDL variable @code{!PATH}
1100 @cindex @code{!PATH}, IDL variable
1101 @cindex IDL variable @code{!DIR}
1102 @cindex @code{!DIR}, IDL variable
1104 If a definition of this routine exists in several files accessible to
1105 IDLWAVE, several @samp{Source} lines will point to the different files.
1106 This may indicate that your routine is shadowing a library routine,
1107 which may or may not be what you want (@pxref{Load-Path Shadows}).  The
1108 information about the calling sequence and keywords is derived from the
1109 first source listed.  Library routines are supported only if you have
1110 scanned your local IDL libraries (@pxref{Library Catalog}).  The source
1111 entry consists of a @emph{source category}, a set of @emph{flags} and
1112 the path to the @emph{source file}.  The following categories exist:
1114 @multitable @columnfractions .15 .85
1115 @item @i{System}
1116 @tab A system routine of unknown origin.  When the system library has
1117 been scanned (@pxref{Library Catalog}), this category will automatically
1118 split into the next two.
1119 @item @i{Builtin}
1120 @tab A builtin system routine with no source code available.
1121 @item @i{SystemLib}
1122 @tab A library system routine in the official lib directory @file{!DIR/lib}.
1123 @item @i{Obsolete}
1124 @tab A library routine in the official lib directory @file{!DIR/lib/obsolete}.
1125 @item @i{Library}
1126 @tab A routine in a file on IDL's search path @code{!PATH}.
1127 @item @i{Other}
1128 @tab Any other routine with a file not known to be on the search path.
1129 @item @i{Unresolved}
1130 @tab An otherwise unkown routine the shell lists as unresolved
1131 (referenced, but not compiled).
1132 @end multitable
1134 You can create additional categories based on the routine's filepath
1135 with the variable @code{idlwave-special-lib-alist}.  This is useful for
1136 easy discrimination of various libraries, or even versions of the same
1137 library.
1139 @cindex Flags, in routine info
1140 @cindex Duplicate routines
1141 @cindex Multiply defined routines
1142 @cindex Routine definitions, multiple
1143 The flags @code{[CSB]} indicate the source of the information IDLWAVE
1144 has regarding the file: from a library catalog (@w{@code{[C--]}},
1145 @pxref{Library Catalog}), from the IDL Shell (@w{@code{[-S-]}}) or from
1146 an Emacs buffer (@w{@code{[--B]}}).  Combinations are possible (a
1147 compiled library routine visited in a buffer might read
1148 @w{@code{[CSB]}}).  If a file contains multiple definitions of the same
1149 routine, the file name will be prefixed with @samp{(Nx)} where @samp{N}
1150 is the number of definitions.
1152 @cindex Online Help from the routine info buffer
1153 @cindex Active text, in routine info
1154 @cindex Inserting keywords, from routine info
1155 @cindex Source file, access from routine info
1156 Some of the text in the @file{*Help*} routine info buffer will be active
1157 (it is highlighted when the mouse moves over it).  Typically, clicking
1158 with the right mouse button invokes online help lookup, and clicking
1159 with the middle mouse button inserts keywords or visits files:
1161 @multitable @columnfractions 0.15 0.85
1162 @item @i{Usage}
1163 @tab If online help is installed, a click with the @emph{right} mouse
1164 button on the @i{Usage:} line will access the help for the
1165 routine (@pxref{Online Help}).
1166 @item @i{Keyword}
1167 @tab Online help about keywords is also available with the
1168 @emph{right} mouse button.  Clicking on a keyword with the @emph{middle}
1169 mouse button will insert this keyword in the buffer from where
1170 @code{idlwave-routine-info} was called.  Holding down @key{SHIFT} while
1171 clicking also adds the initial @samp{/}.
1172 @item @i{Source}
1173 @tab Clicking with the @emph{middle} mouse button on a @samp{Source} line
1174 finds the source file of the routine and visits it in another window.
1175 Another click on the same line switches back to the buffer from which
1176 @kbd{C-c ?} was called.  If you use the @emph{right} mouse button, the
1177 source will not be visited by a buffer, but displayed in the online help
1178 window.
1179 @item @i{Classes}
1180 @tab The @i{Classes} line is only included in the routine info window if
1181 the current class inherits from other classes.  You can click with the
1182 @emph{middle} mouse button to display routine info about the current
1183 method in other classes on the inheritance chain, if such a method
1184 exists there.
1185 @end multitable
1187 @defopt idlwave-resize-routine-help-window (@code{t})
1188 Non-@code{nil} means resize the Routine-info @file{*Help*} window to
1189 fit the content.
1190 @end defopt
1192 @defopt idlwave-special-lib-alist
1193 Alist of regular expressions matching special library directories.
1194 @end defopt
1196 @defopt idlwave-rinfo-max-source-lines (@code{5})
1197 Maximum number of source files displayed in the Routine Info window.
1198 @end defopt
1201 @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode
1202 @section Online Help
1204 @cindex Online Help
1205 @cindex @file{idlw-help.txt}
1206 @cindex @file{idlw-help.el}
1207 @cindex IDL manual, ASCII version
1208 @cindex Installing online help
1209 @cindex Online Help, Installation
1210 @cindex Speed, of online help
1211 For IDL system routines, RSI provides extensive documentation.  IDLWAVE
1212 can access an ASCII version of this documentation very quickly and
1213 accurately.  This is @emph{much} faster than using the IDL online help
1214 application, because IDLWAVE usually gets you to the right place in the
1215 documentation directly, without any additional browsing and scrolling.
1216 For this online help to work, an ASCII version of the IDL documentation,
1217 which is not part of the standalone IDLWAVE distribution, is required.
1218 The necessary help files can be downloaded from
1219 @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}.  The text
1220 extracted from the PDF files is fine for normal documentation
1221 paragraphs, but graphics and multiline equations will not be well
1222 formatted.  See also @ref{Documentation Scan}.
1224 @cindex Updated online help
1225 @cindex Online help, updates
1226 @cindex @code{<NEW>..</NEW>}
1227 Occasionally RSI releases a synopsis of new features in an IDL release,
1228 without simultaneously updating the documentation files, instead
1229 preferring a @i{What's New} document which describes the changes.  These
1230 updates are incorporated directly into the IDLWAVE online help, and are
1231 delimited in @code{<NEW>..</NEW>} blocks.
1233 @cindex Source code, as online help
1234 @cindex DocLib header, as online help
1235 For routines which are not documented in the IDL manual (for example
1236 personal or library routines), the source code itself is used as help
1237 text.  If the requested information can be found in a (more or less)
1238 standard DocLib file header, IDLWAVE shows the header (scrolling down to
1239 appropriate keyword).  Otherwise the routine definition statement
1240 (@code{pro}/@code{function}) is shown.
1242 @cindex Structure tags, in online help
1243 @cindex Class tags, in online help
1244 Help is also available for class structure tags (@code{self.TAG}), and
1245 generic structure tags, if structure tag completion is enabled
1246 (@pxref{Structure Tag Completion}).  This is implemented by visiting the
1247 tag within the class or structure definition source itself.  Help is not
1248 available on built-in system class tags.
1250 @kindex M-?
1251 In any IDL program (or, as with most IDLWAVE commands, in the IDL
1252 Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with
1253 @kbd{S-Mouse-3} to access context sensitive online help.  The following
1254 locations are recognized context for help:
1256 @cindex Context, for online help
1257 @multitable @columnfractions .25 .75
1258 @item @i{Routine name}
1259 @tab The name of a routine (function, procedure, method).
1260 @item @i{Keyword Parameter}
1261 @tab A keyword parameter of a routine.
1262 @item @i{System Variable}
1263 @tab System variables like @code{!DPI}.
1264 @item @i{IDL Statement}
1265 @tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc.
1266 @item @i{Class name}
1267 @tab A class name in an @code{OBJ_NEW} call.
1268 @item @i{Class Init}
1269 @tab Beyond the class name in an @code{OBJ_NEW} call.
1270 @item @i{Executive Command}
1271 @tab An executive command like @code{.RUN}.  Mostly useful in the shell.
1272 @item @i{Structure Tags}
1273 @tab In structure tags like @code{state.xsize}
1274 @item @i{Structure Tags}
1275 @tab In class tags like @code{self.value}.
1276 @item @i{Default}
1277 @tab The routine that would be selected for routine info display.
1278 @end multitable
1280 @cindex @code{OBJ_NEW}, special online help
1281 Note that the @code{OBJ_NEW} function is special in that the help
1282 displayed depends on the cursor position: If the cursor is on the
1283 @samp{OBJ_NEW}, this function is described.  If it is on the class name
1284 inside the quotes, the documentation for the class is pulled up.  If the
1285 cursor is @emph{after} the class name, anywhere in the argument list,
1286 the documentation for the corresponding @code{Init} method and its
1287 keywords is targeted.
1289 @noindent Apart from source buffers, there are two more places from
1290 which online help can be accessed.
1292 @itemize @bullet
1293 @item
1294 Online help for routines and keywords can be accessed through the
1295 Routine Info display.  Click with @kbd{Mouse-3} on an item to see the
1296 corresponding help (@pxref{Routine Info}).
1297 @item
1298 When using completion and Emacs pops up a @file{*Completions*} buffer
1299 with possible completions, clicking with @kbd{Mouse-3} on a completion
1300 item invokes help on that item (@pxref{Completion}).  Items for which
1301 help is available in the online system documentation (vs. just the
1302 program source itself) will be emphasized (e.g. colored blue).
1303 @end itemize
1304 @noindent
1305 In both cases, a blue face indicates that the item is documented in the
1306 IDL manual, but an attempt will be made to visit non-blue items directly
1307 in the originating source file.
1309 @cindex Help application, key bindings
1310 @cindex Key bindings, in help application
1311 The help window is normally displayed in a separate frame.  The
1312 following commands can be used to navigate inside the help system:
1314 @multitable  @columnfractions .15 .85
1315 @item @kbd{@key{SPACE}}
1316 @tab Scroll forward one page.
1317 @item @kbd{@key{RET}}
1318 @tab Scroll forward one line.
1319 @item @kbd{@key{DEL}}
1320 @tab Scroll back one page.
1321 @item @kbd{n, p}
1322 @tab Browse to the next or previous topic (in physical sequence).
1323 @item @kbd{b, f}
1324 @tab Move back and forward through the help topic history.
1325 @item @kbd{c}
1326 @tab Clear the history.
1327 @item @kbd{Mouse-2}
1328 @tab Follow a link.  Active links are displayed in a different font.
1329 Items under @i{See Also} are active, and classes have links to their
1330 methods and back.
1331 @item @kbd{o}
1332 @tab Open a topic.  The topic can be selected with completion.
1333 @item @kbd{*}
1334 @tab Load the whole help file into Emacs, for global text searches.
1335 @item @kbd{q}
1336 @tab Kill the help window.
1337 @end multitable
1339 @sp 1
1340 @noindent When the help text is a source file, the following commands
1341 are also available:
1343 @multitable  @columnfractions .15 .85
1344 @item @kbd{h}
1345 @tab Jump to DocLib Header of the routine whose source is displayed
1346 as help.
1347 @item @kbd{H}
1348 @tab Jump to the first DocLib Header in the file.
1349 @item @kbd{.} @r{(Dot)}
1350 @tab Jump back and forth between the routine definition (the
1351 @code{pro}/@code{function} statement) and the description of the help
1352 item in the DocLib header.
1353 @item @kbd{F}
1354 @tab Fontify the buffer like source code.  See the variable @code{idlwave-help-fontify-source-code}.
1355 @end multitable
1357 @defopt idlwave-help-directory
1358 The directory where idlw-help.txt and idlw-help.el are stored.
1359 @end defopt
1361 @defopt idlwave-help-use-dedicated-frame (@code{t})
1362 Non-@code{nil} means use a separate frame for Online Help if possible.
1363 @end defopt
1365 @defopt idlwave-help-frame-parameters
1366 The frame parameters for the special Online Help frame.
1367 @end defopt
1369 @defopt idlwave-max-popup-menu-items (@code{20})
1370 Maximum number of items per pane in pop-up menus.
1371 @end defopt
1373 @defopt idlwave-extra-help-function
1374 Function to call for help if the normal help fails.
1375 @end defopt
1377 @defopt idlwave-help-fontify-source-code (@code{nil})
1378 Non-@code{nil} means fontify source code displayed as help.
1379 @end defopt
1381 @defopt idlwave-help-source-try-header (@code{t})
1382 Non-@code{nil} means try to find help in routine header when displaying source
1383 file.
1384 @end defopt
1386 @defopt idlwave-help-link-face
1387 The face for links in IDLWAVE online help.
1388 @end defopt
1390 @defopt idlwave-help-activate-links-aggressively (@code{t})
1391 Non-@code{nil} means make all possible links in help window active.
1392 @end defopt
1394 @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode
1395 @section Completion
1396 @cindex Completion
1397 @cindex Keyword completion
1398 @cindex Method completion
1399 @cindex Object method completion
1400 @cindex Class name completion
1401 @cindex Function name completion
1402 @cindex Procedure name completion
1404 @kindex M-@key{TAB}
1405 @kindex C-c C-i
1406 IDLWAVE offers completion for class names, routine names, keywords,
1407 system variables, class structure tags, regular structure tags and file
1408 names.  As in many programming modes, completion is bound to
1409 @kbd{M-@key{TAB}} (or @kbd{@key{TAB}} in the IDLWAVE Shell ---
1410 @pxref{Using the Shell}).  Completion uses exactly the same internal
1411 information as routine info, so when necessary (rarely) it can be
1412 updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}).
1414 The completion function is context sensitive and figures out what to
1415 complete based location of the point.  Here are example lines and what
1416 @kbd{M-@key{TAB}} would try to complete when the cursor is on the
1417 position marked with a @samp{_}:
1419 @example
1420 plo_                    @r{Procedure}
1421 x = a_                  @r{Function}
1422 plot,xra_               @r{Keyword of @code{plot} procedure}
1423 plot,x,y,/x_            @r{Keyword of @code{plot} procedure}
1424 plot,min(_              @r{Keyword of @code{min} function}
1425 obj -> a_               @r{Object method (procedure)}
1426 a(2,3) = obj -> a_      @r{Object method (function)}
1427 x = obj_new('IDL_       @r{Class name}
1428 x = obj_new('MyCl',a_   @r{Keyword to @code{Init} method in class @code{MyCl}}
1429 pro A_                  @r{Class name}
1430 pro _                   @r{Fill in @code{Class::} of first method in this file}
1431 !v_                     @r{System variable}
1432 !version.t_             @r{Structure tag of system variable}
1433 self.g_                 @r{Class structure tag in methods}
1434 state.w_                @r{Structure tag, if tag completion enabled}
1435 name = 'a_              @r{File name (default inside quotes)}
1436 @end example
1438 @cindex Completion, ambiguity
1439 @cindex Completion, forcing function name
1440 The only place where completion is ambiguous is procedure/function
1441 @emph{keywords} versus @emph{functions}.  After @samp{plot,x,_}, IDLWAVE
1442 will always assume a keyword to @samp{plot}.  However, a function is
1443 also a possible completion here.  You can force completion of a function
1444 name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}.
1446 @cindex Scrolling the @file{*Completions*} window
1447 @cindex Completion, scrolling
1448 @cindex Completion, Online Help
1449 @cindex Online Help in @file{*Completions*} buffer
1450 If the list of completions is too long to fit in the
1451 @file{*Completions*} window, the window can be scrolled by pressing
1452 @kbd{M-@key{TAB}} repeatedly.  Online help (if installed) for each
1453 possible completion is available by clicking with @kbd{Mouse-3} on the
1454 item.  Items for which system online help (from the IDL manual) is
1455 available will be emphasized (e.g. colored blue).  For other items, the
1456 corresponding source code or DocLib header will be used as the help
1457 text.
1459 @cindex Completion, cancelling
1460 @cindex Cancelling completion
1461 Completion is not a blocking operation --- you are free to continue
1462 editing, enter commands, or simply ignore the @file{*Completions*}
1463 buffer during a completion operation.  If, however, the most recent
1464 command was a completion, @kbd{C-g} will remove the buffer and restore
1465 the window configuration.  You can also remove the buffer at any time
1466 with no negative consequences.
1468 @defopt idlwave-keyword-completion-adds-equal (@code{t})
1469 Non-@code{nil} means completion automatically adds @samp{=} after
1470 completed keywords.
1471 @end defopt
1473 @defopt idlwave-function-completion-adds-paren (@code{t})
1474 Non-@code{nil} means completion automatically adds @samp{(} after
1475 completed function.  A value of `2' means also add the closing
1476 parenthesis and position the cursor between the two.
1477 @end defopt
1479 @defopt idlwave-completion-restore-window-configuration (@code{t})
1480 Non-@code{nil} means restore window configuration after successful
1481 completion.
1482 @end defopt
1484 @defopt idlwave-highlight-help-links-in-completion (@code{t})
1485 Non-@code{nil} means highlight completions for which system help is
1486 available.
1487 @end defopt
1489 @menu
1490 * Case of Completed Words::     CaseOFcomPletedWords
1491 * Object Method Completion and Class Ambiguity::  obj->Method, what?
1492 * Object Method Completion in the Shell::
1493 * Class and Keyword Inheritance::  obj->Method, _EXTRA=e
1494 * Structure Tag Completion::    Completing state.Tag
1495 @end menu
1497 @node  Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion
1498 @subsection Case of Completed Words
1499 @cindex Case of completed words
1500 @cindex Mixed case completion
1501 The case of the completed words is determined by what is already in the
1502 buffer.  When the partial word being completed is all lower case, the
1503 completion will be lower case as well.  If at least one character is
1504 upper case, the string will be completed in upper case or mixed case.
1505 The default is to use upper case for procedures, functions and keywords,
1506 and mixed case for object class names and methods, similar to the
1507 conventions in the IDL manuals.  These defaults can be changed with the
1508 variable @code{idlwave-completion-case}.  For instance, to enable
1509 mixed-case completion for routines in addition to classes and methods,
1510 you need an entry such as @code{routine . preserve} in that variable.
1511 To enable total control over the case of completed items, independent of
1512 buffer context, set @code{idlwave-completion-force-default-case} to
1513 non-@code{nil}.
1515 @defopt idlwave-completion-case
1516 Association list setting the case (UPPER/lower/Capitalized/MixedCase...)
1517 of completed words.
1518 @end defopt
1520 @defopt idlwave-completion-force-default-case (@code{nil})
1521 Non-@code{nil} means completion will always honor the settings in
1522 @code{idlwave-completion-case}.  When nil (the default), entirely lower
1523 case strings will always be completed to lower case, no matter what the
1524 settings in @code{idlwave-completion-case}.
1525 @end defopt
1527 @defopt idlwave-complete-empty-string-as-lower-case (@code{nil})
1528 Non-@code{nil} means the empty string is considered lower case for
1529 completion.
1530 @end defopt
1532 @node  Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion
1533 @subsection Object Method Completion and Class Ambiguity
1534 @cindex Object methods
1535 @cindex Class ambiguity
1536 @cindex @code{self} object, default class
1537 An object method is not uniquely determined without the object's class.
1538 Since the class is almost always omitted in the calling source, IDLWAVE
1539 considers all available methods in all classes as possible method name
1540 completions.  The combined list of keywords of the current method in
1541 @emph{all} known classes which contain that method will be considered
1542 for keyword completion.  In the @file{*Completions*} buffer, the
1543 matching classes will be shown next to each item (see option
1544 @code{idlwave-completion-show-classes}).  As a special case, the class
1545 of an object called @samp{self} is always taken to be the class of the
1546 current routine.  All classes it inherits from are considered as well
1547 where appropriate.
1549 @cindex Forcing class query.
1550 @cindex Class query, forcing
1551 You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u
1552 M-@key{TAB}}.  IDLWAVE will then prompt you for the class in order to
1553 narrow down the number of possible completions.  The variable
1554 @code{idlwave-query-class} can be configured to make such prompting the
1555 default for all methods (not recommended), or selectively for very
1556 common methods for which the number of completing keywords would be too
1557 large (e.g. @code{Init}).
1559 @cindex Saving object class on @code{->}
1560 @cindex @code{->}
1561 After you have specified the class for a particular statement (e.g. when
1562 completing the method), IDLWAVE can remember it for the rest of the
1563 editing session.  Subsequent completions in the same statement
1564 (e.g. keywords) can then reuse this class information.  This works by
1565 placing a text property on the method invocation operator @samp{->},
1566 after which the operator will be shown in a different face.  This is not
1567 enabled by default --- the variable @code{idlwave-store-inquired-class}
1568 can be used to turn it on.
1570 @defopt idlwave-completion-show-classes (@code{1})
1571 Non-@code{nil} means show classes in @file{*Completions*} buffer when
1572 completing object methods and keywords.
1573 @end defopt
1575 @defopt idlwave-completion-fontify-classes (@code{t})
1576 Non-@code{nil} means fontify the classes in completions buffer.
1577 @end defopt
1579 @defopt idlwave-query-class (@code{nil})
1580 Association list governing query for object classes during completion.
1581 @end defopt
1583 @defopt idlwave-store-inquired-class (@code{nil})
1584 Non-@code{nil} means store class of a method call as text property on
1585 @samp{->}.
1586 @end defopt
1588 @defopt idlwave-class-arrow-face
1589 Face to highlight object operator arrows @samp{->} which carry a class
1590 text property.
1591 @end defopt
1593 @node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion
1594 @subsection Object Method Completion in the Shell
1595 @cindex Method Completion in Shell
1596 In the IDLWAVE Shell (@pxref{The IDLWAVE Shell}), objects on which
1597 methods are being invoked have a special property: they must exist as
1598 variables, and so their class can be determined (for instance, using the
1599 @code{obj_class()} function).  In the Shell, when attempting completion,
1600 routine info, or online help within a method routine, a query is sent to
1601 determine the class of the object.  If this query is successful, the
1602 class found will be used to select appropriate completions, routine
1603 info, or help.  If unsuccessful, information from all known classes will
1604 be used (as in the buffer).  Setting the variable
1605 @code{idlwave-store-inquired-class} can eliminate unnecessary repetitive
1606 queries for the object's class, and speed up completion.
1608 @node   Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion
1609 @subsection Class and Keyword Inheritance
1610 @cindex Inheritance, class
1611 @cindex Keyword inheritance
1612 @cindex Inheritance, keyword
1614 Class inheritance affects which methods are called in IDL.  An object of
1615 a class which inherits methods from one or more superclasses can
1616 override that method by defining its own method of the same name, extend
1617 the method by calling the method(s) of its superclass(es) in its
1618 version, or inherit the method directly by making no modifications.
1619 IDLWAVE examines class definitions during completion and routine
1620 information display, and records all inheritance information it finds.
1621 This information is displayed if appropriate with the calling sequence
1622 for methods (@pxref{Routine Info}), as long as variable
1623 @code{idlwave-support-inheritance} is non-@code{nil}.
1625 In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and
1626 @code{_REF_EXTRA}) is used hand-in-hand with class inheritance and
1627 method overriding.  E.g., in a @code{SetProperty} method, this technique
1628 allows a single call @code{obj->SetProperty} to set properties up the
1629 entire class inheritance chain.  This is often referred to as
1630 @emph{chaining}, and is characterized by chained method calls like
1631 @w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}.
1633 IDLWAVE can accommodate this special synergy between class and keyword
1634 inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a
1635 method's keyword parameters, all keywords of superclass versions of the
1636 method being considered are included in completion.  There is of course
1637 no guarantee that this type of keyword chaining actually occurrs, but
1638 for some methods it's a very convenient assumption.  The variable
1639 @code{idlwave-keyword-class-inheritance} can be used to configure which
1640 methods have keyword inheritance treated in this simple, class-driven
1641 way.  By default, only @code{Init} and @code{(Get|Set)Property} are.
1642 The completion buffer will label keywords based on their originating
1643 class.
1645 @defopt idlwave-support-inheritance (@code{t})
1646 Non-@code{nil} means consider inheritance during completion, online help etc.
1647 @end defopt
1649 @defopt idlwave-keyword-class-inheritance
1650 A list of regular expressions to match methods for which simple
1651 class-driven keyword inheritance will be used for Completion.
1652 @end defopt
1654 @node    Structure Tag Completion,  , Class and Keyword Inheritance, Completion
1655 @subsection Structure Tag Completion
1656 @cindex Completion, structure tag
1657 @cindex Structure tag completion
1659 In many programs, especially those involving widgets, large structures
1660 (e.g. the @samp{state} structure) are used to communicate among
1661 routines.  It is very convenient to be able to complete structure tags,
1662 in the same way as for instance variables (tags) of the @samp{self}
1663 object (@pxref{Object Method Completion and Class Ambiguity}).  Add-in
1664 code for structure tag completion is available in the form of a loadable
1665 completion module: @file{idlw-complete-structtag.el}.  Tag completion in
1666 structures is highly ambiguous (much more so than @samp{self}
1667 completion), so @code{idlw-complete-structtag} makes an unusual and very
1668 specific assumption: the exact same variable name is used to refer to
1669 the structure in all parts of the program.  This is entirely unenforced
1670 by the IDL language, but is a typical convention.  If you consistently
1671 refer to the same structure with the same variable name
1672 (e.g. @samp{state}), structure tags which are read from its definition
1673 in the same file can be used for completion.
1675 Structure tag completion is not enabled by default.  To enable it,
1676 simply add the following to your @file{.emacs}:
1678 @lisp
1679    (add-hook 'idlwave-load-hook
1680              (lambda () (require 'idlw-complete-structtag)))
1681 @end lisp
1683 Once enabled, you'll also be able to access online help on the structure
1684 tags, using the usual methods (@pxref{Online Help}).
1686 @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode
1687 @section Routine Source
1688 @cindex Routine source file
1689 @cindex Module source file
1690 @cindex Source file, of a routine
1691 @kindex C-c C-v
1692 In addition to clicking on a @i{Source:} line in the routine info
1693 window, there is another way to quickly visit the source file of a
1694 routine.  The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks
1695 for a module name, offering the same default as
1696 @code{idlwave-routine-info} would have used, taken from nearby buffer
1697 contents.  In the minibuffer, specify a complete routine name (including
1698 any class part).  IDLWAVE will display the source file in another
1699 window, positioned at the routine in question.
1701 @cindex Buffers, killing
1702 @cindex Killing autoloaded buffers
1703 Since getting the source of a routine into a buffer is so easy with
1704 IDLWAVE, too many buffers visiting different IDL source files are
1705 sometimes created.  The special command @kbd{C-c C-k}
1706 (@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove
1707 these buffers.
1709 @node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode
1710 @section Resolving Routines
1711 @cindex @code{RESOLVE_ROUTINE}
1712 @cindex Compiling library modules
1713 @cindex Routines, resolving
1715 The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve}
1716 and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL
1717 in order to resolve (compile) it.  The default routine to be resolved is
1718 taken from context, but you get a chance to edit it.
1720 @code{idlwave-resolve} is one way to get a library module within reach
1721 of IDLWAVE's routine info collecting functions.  A better way is to
1722 scan (parts of) the library (@pxref{Library Catalog}).  Routine info on
1723 library modules will then be available without the need to compile the
1724 modules first, and even without a running shell.
1726 @xref{Sources of Routine Info}, for more information on the ways IDLWAVE
1727 collects data about routines, and how to update this information.
1729 @node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode
1730 @section Code Templates
1731 @cindex Code templates
1732 @cindex Templates
1734 IDLWAVE can insert IDL code templates into the buffer.  For a few
1735 templates, this is done with direct key bindings:
1737 @multitable @columnfractions .15 .85
1738 @item @kbd{C-c C-c}
1739 @tab @code{CASE} statement template
1740 @item @kbd{C-c C-f}
1741 @tab @code{FOR} loop template
1742 @item @kbd{C-c C-r}
1743 @tab @code{REPEAT} loop template
1744 @item @kbd{C-c C-w}
1745 @tab @code{WHILE} loop template
1746 @end multitable
1748 All code templates are also available as abbreviations
1749 (@pxref{Abbreviations}).
1751 @node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode
1752 @section Abbreviations
1753 @cindex Abbreviations
1755 Special abbreviations exist to enable rapid entry of commonly used
1756 commands.  Emacs abbreviations are expanded by typing text into the
1757 buffer and pressing @key{SPC} or @key{RET}.  The special abbreviations
1758 used to insert code templates all start with a @samp{\} (the backslash),
1759 or, optionally, any other character set in
1760 @code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are
1761 only expanded where they should be (i.e., not in a string or comment),
1762 and permits the point to be moved after an abbreviation expansion ---
1763 very useful for positioning the mark inside of parentheses, etc.
1765 Special abbreviations are pre-defined for code templates and other
1766 useful items.  To visit the full list of abbreviations, use @kbd{M-x
1767 idlwave-list-abbrevs}.
1769 Template abbreviations:
1771 @multitable @columnfractions .15 .85
1772 @item @code{\pr}
1773 @tab @code{PROCEDURE} template
1774 @item @code{\fu}
1775 @tab @code{FUNCTION} template
1776 @item @code{\c}
1777 @tab @code{CASE} statement template
1778 @item @code{\f}
1779 @tab @code{FOR} loop template
1780 @item @code{\r}
1781 @tab @code{REPEAT} loop template
1782 @item @code{\w}
1783 @tab @code{WHILE} loop template
1784 @item @code{\i}
1785 @tab @code{IF} statement template
1786 @item @code{\elif}
1787 @tab @code{IF-ELSE} statement template
1788 @end multitable
1790 String abbreviations:
1792 @multitable @columnfractions .15 .85
1793 @item @code{\ap}
1794 @tab @code{arg_present()}
1795 @item @code{\b}
1796 @tab @code{begin}
1797 @item @code{\cb}
1798 @tab @code{byte()}
1799 @item @code{\cc}
1800 @tab @code{complex()}
1801 @item @code{\cd}
1802 @tab @code{double()}
1803 @item @code{\cf}
1804 @tab @code{float()}
1805 @item @code{\cl}
1806 @tab @code{long()}
1807 @item @code{\co}
1808 @tab @code{common}
1809 @item @code{\cs}
1810 @tab @code{string()}
1811 @item @code{\cx}
1812 @tab @code{fix()}
1813 @item @code{\e}
1814 @tab @code{else}
1815 @item @code{\ec}
1816 @tab @code{endcase}
1817 @item @code{\ee}
1818 @tab @code{endelse}
1819 @item @code{\ef}
1820 @tab @code{endfor}
1821 @item @code{\ei}
1822 @tab @code{endif else if}
1823 @item @code{\el}
1824 @tab @code{endif else}
1825 @item @code{\en}
1826 @tab @code{endif}
1827 @item @code{\er}
1828 @tab @code{endrep}
1829 @item @code{\es}
1830 @tab @code{endswitch}
1831 @item @code{\ew}
1832 @tab @code{endwhile}
1833 @item @code{\g}
1834 @tab @code{goto,}
1835 @item @code{\h}
1836 @tab @code{help,}
1837 @item @code{\ik}
1838 @tab @code{if keyword_set() then}
1839 @item @code{\iap}
1840 @tab @code{if arg_present() then}
1841 @item @code{\ine}
1842 @tab @code{if n_elements() eq 0 then}
1843 @item @code{\inn}
1844 @tab @code{if n_elements() ne 0 then}
1845 @item @code{\k}
1846 @tab @code{keyword_set()}
1847 @item @code{\n}
1848 @tab @code{n_elements()}
1849 @item @code{\np}
1850 @tab @code{n_params()}
1851 @item @code{\oi}
1852 @tab @code{on_ioerror,}
1853 @item @code{\or}
1854 @tab @code{openr,}
1855 @item @code{\ou}
1856 @tab @code{openu,}
1857 @item @code{\ow}
1858 @tab @code{openw,}
1859 @item @code{\p}
1860 @tab @code{print,}
1861 @item @code{\pt}
1862 @tab @code{plot,}
1863 @item @code{\re}
1864 @tab @code{read,}
1865 @item @code{\rf}
1866 @tab @code{readf,}
1867 @item @code{\rt}
1868 @tab @code{return}
1869 @item @code{\ru}
1870 @tab @code{readu,}
1871 @item @code{\s}
1872 @tab @code{size()}
1873 @item @code{\sc}
1874 @tab @code{strcompress()}
1875 @item @code{\sl}
1876 @tab @code{strlowcase()}
1877 @item @code{\sm}
1878 @tab @code{strmid()}
1879 @item @code{\sn}
1880 @tab @code{strlen()}
1881 @item @code{\sp}
1882 @tab @code{strpos()}
1883 @item @code{\sr}
1884 @tab @code{strtrim()}
1885 @item @code{\st}
1886 @tab @code{strput()}
1887 @item @code{\su}
1888 @tab @code{strupcase()}
1889 @item @code{\t}
1890 @tab @code{then}
1891 @item @code{\u}
1892 @tab @code{until}
1893 @item @code{\wc}
1894 @tab @code{widget_control,}
1895 @item @code{\wi}
1896 @tab @code{widget_info()}
1897 @item @code{\wu}
1898 @tab @code{writeu,}
1899 @end multitable
1901 @noindent You can easily add your own abbreviations or override existing
1902 abbrevs with @code{define-abbrev} in your mode hook, using the
1903 convenience function @code{idlwave-define-abbrev}:
1905 @lisp
1906 (add-hook 'idlwave-mode-hook
1907           (lambda ()
1908             (idlwave-define-abbrev "wb" "widget_base()"
1909                      (idlwave-keyword-abbrev 1))
1910             (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN"
1911                      (idlwave-keyword-abbrev 11))))
1912 @end lisp
1914 Notice how the abbreviation (here @emph{wb}) and its expansion
1915 (@emph{widget_base()}) are given as arguments, and the single argument to
1916 @code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to
1917 move the point upon expansion (in this example, to put it between the
1918 parentheses).
1920 The abbreviations are expanded in upper or lower case, depending upon
1921 the variables @code{idlwave-abbrev-change-case} and, for reserved word
1922 templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}).
1924 @defopt idlwave-abbrev-start-char (@code{"\"})
1925 A single character string used to start abbreviations in abbrev mode.
1926 Beware of common characters which might naturally occur in sequence with
1927 abbreviation strings.
1928 @end defopt
1930 @defopt idlwave-abbrev-move (@code{t})
1931 Non-@code{nil} means the abbrev hook can move point, e.g. to end up
1932 between the parentheses of a function call.
1933 @end defopt
1935 @node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode
1936 @section Actions
1937 @cindex Actions
1938 @cindex Coding standards, enforcing
1940 @emph{Actions} are special formatting commands which are executed
1941 automatically while you write code in order to check the structure of
1942 the program or to enforce coding standards.  Most actions which have
1943 been implemented in IDLWAVE are turned off by default, assuming that the
1944 average user wants her code the way she writes it.  But if you are a
1945 lazy typist and want your code to adhere to certain standards, actions
1946 can be helpful.
1948 Actions can be applied in three ways:
1950 @itemize @bullet
1951 @item
1952 Some actions are applied directly while typing.  For example, pressing
1953 @samp{=} can run a check to make sure that this operator is surrounded
1954 by spaces and insert these spaces if necessary.  Pressing @key{SPC}
1955 after a reserved word can call a command to change the word to upper
1956 case.
1957 @item
1958 When a line is re-indented with @key{TAB}, actions can be applied to the
1959 entire line.  To enable this, the variable @code{idlwave-do-actions}
1960 must be non-@code{nil}.
1961 @item
1962 @cindex Foreign code, adapting
1963 @cindex Actions, applied to foreign code
1964 Actions can also be applied to a larger piece of code, e.g. to convert
1965 foreign code to your own style.  To do this, mark the relevant part of
1966 the code and execute @kbd{M-x expand-region-abbrevs}.  Useful marking
1967 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current
1968 subprogram). @xref{Code Indentation}, for information how to adjust the
1969 indentation of the code.
1970 @end itemize
1972 @defopt idlwave-do-actions (@code{nil})
1973 Non-@code{nil} means performs actions when indenting.
1974 @end defopt
1976 @menu
1977 * Block Boundary Check::        Is the END statement correct?
1978 * Padding Operators::           Enforcing space around `=' etc
1979 * Case Changes::                Enforcing upper case keywords
1980 @end menu
1982 @node Block Boundary Check, Padding Operators, Actions, Actions
1983 @subsection Block Boundary Check
1984 @cindex Block boundary check
1985 @cindex @code{END} type checking
1986 @cindex @code{END}, automatic insertion
1987 @cindex @code{END}, expanding
1988 @cindex Block, closing
1989 @cindex Closing a block
1991 Whenever you type an @code{END} statement, IDLWAVE finds the
1992 corresponding start of the block and the cursor blinks back to that
1993 location for a second.  If you have typed a specific @code{END}, like
1994 @code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator
1995 does not match the type of block it terminates.
1997 Set the variable @code{idlwave-expand-generic-end} in order to have all
1998 generic @code{END} statements automatically expanded to the appropriate
1999 type.  You can also type @kbd{C-c ]} to close the current block by
2000 inserting the appropriate @code{END} statement.
2002 @defopt idlwave-show-block (@code{t})
2003 Non-@code{nil} means point blinks to block beginning for
2004 @code{idlwave-show-begin}.
2005 @end defopt
2007 @defopt idlwave-expand-generic-end (@code{t})
2008 Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc.
2009 @end defopt
2011 @defopt idlwave-reindent-end (@code{t})
2012 Non-@code{nil} means re-indent line after END was typed.
2013 @end defopt
2015 @node Padding Operators, Case Changes, Block Boundary Check, Actions
2016 @subsection Padding Operators
2017 @cindex Padding operators with spaces
2018 @cindex Operators, padding with spaces
2019 @cindex Space, around operators
2021 Some operators can be automatically surrounded by spaces.  This can
2022 happen when the operator is typed, or later when the line is indented.
2023 IDLWAVE can pad the operators @samp{&}, @samp{<}, @samp{>}, @samp{,},
2024 @samp{=}, and @samp{->}, but this feature is turned off by default.  If
2025 you want to turn it on, customize the variables
2026 @code{idlwave-surround-by-blank} and @code{idlwave-do-actions}.  You can
2027 also define similar actions for other operators by using the function
2028 @code{idlwave-action-and-binding} in the mode hook.  For example, to
2029 enforce space padding of the @samp{+} and @samp{*} operators, try this
2030 in @file{.emacs}
2032 @lisp
2033 (add-hook 'idlwave-mode-hook
2034   (lambda ()
2035      (setq idlwave-surround-by-blank t)  ; Turn this type of actions on
2036      (idlwave-action-and-binding "*" '(idlwave-surround 1 1))
2037      (idlwave-action-and-binding "+" '(idlwave-surround 1 1))))
2038 @end lisp
2040 @defopt idlwave-surround-by-blank (@code{nil})
2041 Non-@code{nil} means enable @code{idlwave-surround}.  If non-@code{nil},
2042 @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are
2043 surrounded with spaces by @code{idlwave-surround}.
2044 @end defopt
2046 @defopt idlwave-pad-keyword (@code{t})
2047 Non-@code{nil} means pad @samp{=} for keywords like assignments.
2048 @end defopt
2050 @node Case Changes,  , Padding Operators, Actions
2051 @subsection Case Changes
2052 @cindex Case changes
2053 @cindex Upcase, enforcing for reserved words
2054 @cindex Downcase, enforcing for reserved words
2056 Actions can be used to change the case of reserved words or expanded
2057 abbreviations by customizing the variables
2058 @code{idlwave-abbrev-change-case} and
2059 @code{idlwave-reserved-word-upcase}.  If you want to change the case of
2060 additional words automatically, put something like the following into
2061 your @file{.emacs} file:
2063 @lisp
2064 (add-hook 'idlwave-mode-hook
2065   (lambda ()
2066      ;;  Capitalize system vars
2067      (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t)
2068      ;;  Capitalize procedure name
2069      (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<"
2070                                  '(capitalize-word 1) t)
2071      ;;  Capitalize common block name
2072      (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"
2073                                  '(capitalize-word 1) t)))
2074 @end lisp
2076 For more information, see the documentation string for the function
2077 @code{idlwave-action-and-binding}.  For information on controlling the
2078 case of routines, keywords, classes, and methods as they are completed, see
2079 @ref{Completion}.
2081 @defopt idlwave-abbrev-change-case (@code{nil})
2082 Non-@code{nil} means all abbrevs will be forced to either upper or lower
2083 case.  Legal values are @code{nil}, @code{t}, and @code{down}.
2084 @end defopt
2086 @defopt idlwave-reserved-word-upcase (@code{nil})
2087 Non-@code{nil} means reserved words will be made upper case via abbrev
2088 expansion.
2089 @end defopt
2092 @node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode
2093 @section Documentation Header
2094 @cindex Documentation header
2095 @cindex DocLib header
2096 @cindex Modification timestamp
2097 @cindex Header, for file documentation
2098 @cindex Timestamp, in doc header.
2099 @cindex ChangeLog, in doc header.
2101 @kindex C-c C-h
2102 @kindex C-c C-m
2103 The command @kbd{C-c C-h} inserts a standard routine header into the
2104 buffer, with the usual fields for documentation (a different header can
2105 be specified with @code{idlwave-file-header}).  One of the keywords is
2106 @samp{MODIFICATION HISTORY} under which the changes to a routine can be
2107 recorded.  The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION
2108 HISTORY} of the current routine or file and inserts the user name with a
2109 timestamp.
2111 @defopt idlwave-file-header
2112 The doc-header template or a path to a file containing it.
2113 @end defopt
2115 @defopt idlwave-header-to-beginning-of-file (@code{nil})
2116 Non-@code{nil} means the documentation header will always be at start
2117 of file.
2118 @end defopt
2120 @defopt idlwave-timestamp-hook
2121 The hook function used to update the timestamp of a function.
2122 @end defopt
2124 @defopt idlwave-doc-modifications-keyword
2125 The modifications keyword to use with the log documentation commands.
2126 @end defopt
2128 @defopt idlwave-doclib-start
2129 Regexp matching the start of a document library header.
2130 @end defopt
2132 @defopt idlwave-doclib-end
2133 Regexp matching the start of a document library header.
2134 @end defopt
2136 @node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode
2137 @section Motion Commands
2138 @cindex Motion commands
2139 @cindex Program structure, moving through
2140 @cindex Code structure, moving through
2141 @cindex @file{Func-menu}, XEmacs package
2142 @cindex @file{Imenu}, Emacs package
2143 @cindex Function definitions, jumping to
2144 @cindex Procedure definitions, jumping to
2146 IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages
2147 which make it easy to jump to the definitions of functions and
2148 procedures in the current file with a pop-up selection.  To bind
2149 @file{Imenu} to a mouse-press, use in your @file{.emacs}:
2151 @lisp
2152 (define-key global-map [S-down-mouse-3] 'imenu)
2153 @end lisp
2155 @cindex @file{Speedbar}, Emacs package
2157 In addition, @file{Speedbar} support allows convenient navigation of a
2158 source tree of IDL routine files, quickly stepping to routine
2159 definitions.  See @code{Tools->Display Speedbar}.
2161 Several commands allow you to move quickly through the structure of an
2162 IDL program:
2164 @multitable @columnfractions .15 .85
2165 @item @kbd{C-M-a}
2166 @tab Beginning of subprogram
2167 @item @kbd{C-M-e}
2168 @tab End of subprogram
2169 @item @kbd{C-c @{}
2170 @tab Beginning of block (stay inside the block)
2171 @item @kbd{C-c @}}
2172 @tab End of block (stay inside the block)
2173 @item @kbd{C-M-n}
2174 @tab Forward block (on same level)
2175 @item @kbd{C-M-p}
2176 @tab Backward block (on same level)
2177 @item @kbd{C-M-d}
2178 @tab Down block (enters a block)
2179 @item @kbd{C-M-u}
2180 @tab Backward up block (leaves a block)
2181 @item @kbd{C-c C-n}
2182 @tab Next Statement
2183 @end multitable
2186 @node Misc Options,  , Motion Commands, The IDLWAVE Major Mode
2187 @section Miscellaneous Options
2188 @cindex Hooks
2190 @defopt idlwave-help-application
2191 The external application providing reference help for programming.
2192 @end defopt
2194 @defopt idlwave-startup-message (@code{t})
2195 Non-@code{nil} means display a startup message when @code{idlwave-mode}'
2196 is first called.
2197 @end defopt
2199 @defopt idlwave-mode-hook
2200 Normal hook.  Executed when a buffer is put into @code{idlwave-mode}.
2201 @end defopt
2203 @defopt idlwave-load-hook
2204 Normal hook.  Executed when @file{idlwave.el} is loaded.
2205 @end defopt
2209 @node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top
2210 @chapter The IDLWAVE Shell
2211 @cindex IDLWAVE shell
2212 @cindex Major mode, @code{idlwave-shell-mode}
2213 @cindex IDL, as Emacs subprocess
2214 @cindex Subprocess of Emacs, IDL
2215 @cindex Comint, Emacs package
2216 @cindex Windows
2217 @cindex MacOS
2219 The IDLWAVE shell is an Emacs major mode which permits running the IDL
2220 program as an inferior process of Emacs, and works closely with the
2221 IDLWAVE major mode in buffers.  It can be used to work with IDL
2222 interactively, to compile and run IDL programs in Emacs buffers and to
2223 debug these programs.  The IDLWAVE shell is built upon @file{comint}, an
2224 Emacs packages which handles the communication with the IDL program.
2225 Unfortunately IDL for Windows and MacOS do not have command-prompt
2226 versions and thus do not allow the interaction with
2227 Emacs@footnote{Please inform the maintainer if you come up with a way to
2228 make the IDLWAVE shell work on these systems.} --- so the IDLWAVE shell
2229 currently only works under Unix.
2231 @menu
2232 * Starting the Shell::          How to launch IDL as a subprocess
2233 * Using the Shell::             Interactively working with the Shell
2234 * Commands Sent to the Shell::
2235 * Debugging IDL Programs::
2236 * Examining Variables::
2237 * Custom Expression Examination::
2238 @end menu
2240 @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell
2241 @section Starting the Shell
2242 @cindex Starting the shell
2243 @cindex Shell, starting
2244 @cindex Dedicated frame, for shell buffer
2245 @cindex Frame, for shell buffer
2246 @cindex Subprocess of Emacs, IDL
2248 @kindex C-c C-s
2249 The IDLWAVE shell can be started with the command @kbd{M-x
2250 idlwave-shell}.  In @code{idlwave-mode} the function is bound to
2251 @kbd{C-c C-s}.  It creates a buffer @file{*idl*} which is used to
2252 interact with the shell.  If the shell is already running, @kbd{C-c C-s}
2253 will simple switch to the shell buffer.  The command @kbd{C-c C-l}
2254 (@code{idlwave-shell-recenter-shell-window}) displays the shell window
2255 without selecting it.  The shell can also be started automatically when
2256 another command tries to send a command to it.  To enable auto start,
2257 set the variable @code{idlwave-shell-automatic-start} to @code{t}.
2259 In order to create a separate frame for the IDLWAVE shell buffer, call
2260 @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or
2261 @kbd{C-u C-c C-l}.  If you always want a dedicated frame for the shell
2262 window, configure the variable
2263 @code{idlwave-shell-use-dedicated-frame}.
2265 To launch a quick IDLWAVE shell directly from a shell prompt without an
2266 IDLWAVE buffer (e.g., as a replacement for running inside an xterm),
2267 define an alias with the following content:
2269 @example
2270 emacs -geometry 80x32 -eval "(idlwave-shell 'quick)"
2271 @end example
2273 Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer
2274 the Emacs process to run directly inside the terminal window.
2276 @defopt idlwave-shell-explicit-file-name (@file{idl})
2277 This is the command to run IDL.
2278 @end defopt
2280 @defopt idlwave-shell-command-line-options
2281 A list of command line options for calling the IDL program.
2282 @end defopt
2284 @defopt idlwave-shell-prompt-pattern
2285 Regexp to match IDL prompt at beginning of a line.
2286 @end defopt
2288 @defopt idlwave-shell-process-name
2289 Name to be associated with the IDL process.
2290 @end defopt
2292 @defopt idlwave-shell-automatic-start  (@code{nil})
2293 Non-@code{nil} means attempt to invoke idlwave-shell if not already
2294 running.
2295 @end defopt
2297 @defopt idlwave-shell-initial-commands
2298 Initial commands, separated by newlines, to send to IDL.
2299 @end defopt
2301 @defopt idlwave-shell-save-command-history (@code{t})
2302 Non-@code{nil} means preserve command history between sessions.
2303 @end defopt
2305 @defopt idlwave-shell-command-history-file (@file{~/.idlwhist})
2306 The file in which the command history of the idlwave shell is saved.
2307 @end defopt
2309 @defopt idlwave-shell-use-dedicated-frame (@code{nil})
2310 Non-@code{nil} means IDLWAVE should use a special frame to display
2311 shell buffer.
2312 @end defopt
2314 @defopt idlwave-shell-frame-parameters
2315 The frame parameters for a dedicated idlwave-shell frame.
2316 @end defopt
2318 @defopt idlwave-shell-raise-frame (@code{t})
2319 Non-@code{nil} means `idlwave-shell' raises the frame showing the shell
2320 window.
2321 @end defopt
2323 @defopt idlwave-shell-temp-pro-prefix
2324 The prefix for temporary IDL files used when compiling regions.
2325 @end defopt
2327 @cindex Hooks
2328 @defopt idlwave-shell-mode-hook
2329 Hook for customizing @code{idlwave-shell-mode}.
2330 @end defopt
2332 @node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell
2333 @section Using the Shell
2334 @cindex Comint
2335 @cindex Shell, basic commands
2337 The IDLWAVE shell works in the same fashion as other shell modes in
2338 Emacs.  It provides command history, command line editing and job
2339 control.  The @key{UP} and @key{DOWN} arrows cycle through the input
2340 history just like in an X terminal@footnote{This is different from
2341 normal Emacs/Comint behavior, but more like an xterm.  If you prefer the
2342 default comint functionality, check the variable
2343 @code{idlwave-shell-arrows-do-history}.}.  The history is preserved
2344 between emacs and IDL sessions.  Here is a list of commonly used
2345 commands:
2347 @multitable @columnfractions .12 .88
2348 @item @key{UP}, @key{M-p}
2349 @tab Cycle backwards in input history
2350 @item @key{DOWN}, @key{M-n}
2351 @tab Cycle forwards in input history
2352 @item @kbd{M-r}
2353 @tab Previous input matching a regexp
2354 @item @kbd{M-s}
2355 @tab Next input matching a regexp
2356 @item @kbd{return}
2357 @tab Send input or copy line to current prompt
2358 @item @kbd{C-c C-a}
2359 @tab Beginning of line; skip prompt
2360 @item @kbd{C-c C-u}
2361 @tab Kill input to beginning of line
2362 @item @kbd{C-c C-w}
2363 @tab Kill word before cursor
2364 @item @kbd{C-c C-c}
2365 @tab Send ^C
2366 @item @kbd{C-c C-z}
2367 @tab Send ^Z
2368 @item @kbd{C-c C-\}
2369 @tab Send ^\
2370 @item @kbd{C-c C-o}
2371 @tab Delete last batch of process output
2372 @item @kbd{C-c C-r}
2373 @tab Show last batch of process output
2374 @item @kbd{C-c C-l}
2375 @tab List input history
2376 @end multitable
2378 In addition to these standard @file{comint} commands,
2379 @code{idlwave-shell-mode} provides many of the same commands which
2380 simplify writing IDL code available in IDLWAVE buffers.  This includes
2381 abbreviations, online help, and completion.  See @ref{Routine Info} and
2382 @ref{Online Help} and @ref{Completion} for more information on these
2383 commands.
2385 @cindex Completion, in the shell
2386 @cindex Routine info, in the shell
2387 @cindex Online Help, in the shell
2388 @multitable @columnfractions .12 .88
2389 @item @kbd{@key{TAB}}
2390 @tab  Completion of file names (between quotes and after executive
2391 commands @samp{.run} and @samp{.compile}), routine names, class names,
2392 keywords, system variables, system variable tags etc.
2393 (@code{idlwave-shell-complete}).
2394 @item @kbd{M-@key{TAB}}
2395 @tab Same as @key{TAB}
2396 @item @kbd{C-c ?}
2397 @tab Routine Info display (@code{idlwave-routine-info})
2398 @item @kbd{M-?}
2399 @tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp})
2400 @item @kbd{C-c C-i}
2401 @tab Update routine info from buffers and shell
2402 (@code{idlwave-update-routine-info})
2403 @item @kbd{C-c C-v}
2404 @tab Find the source file of a routine (@code{idlwave-find-module})
2405 @item @kbd{C-c =}
2406 @tab Compile a library routine (@code{idlwave-resolve})
2407 @end multitable
2409 @defopt idlwave-shell-arrows-do-history (@code{t})
2410 Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command
2411 history like xterm.
2412 @end defopt
2414 @defopt idlwave-shell-comint-settings
2415 Alist of special settings for the comint variables in the IDLWAVE Shell.
2416 @end defopt
2418 @defopt idlwave-shell-file-name-chars
2419 The characters allowed in file names, as a string.  Used for file name
2420 completion.
2421 @end defopt
2423 @defopt idlwave-shell-graphics-window-size
2424 Size of IDL graphics windows popped up by special IDLWAVE command.
2425 @end defopt
2427 @cindex Input mode
2428 @cindex Character input mode (Shell)
2429 @cindex Line input mode (Shell)
2430 @cindex Magic spells, for input mode
2431 @cindex Spells, magic
2432 IDLWAVE works in line input mode: You compose a full command line, using
2433 all the power Emacs gives you to do this.  When you press @key{RET}, the
2434 whole line is sent to IDL.  Sometimes it is necessary to send single
2435 characters (without a newline), for example when an IDL program is
2436 waiting for single character input with the @code{GET_KBRD} function.
2437 You can send a single character to IDL with the command @kbd{C-c C-x}
2438 (@code{idlwave-shell-send-char}).  When you press @kbd{C-c C-y}
2439 (@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop
2440 which accepts characters and immediately sends them to IDL.  The loop
2441 can be exited with @kbd{C-g}.  It terminates also automatically when the
2442 current IDL command is finished.  Check the documentation of the two
2443 variables described below for a way to make IDL programs trigger
2444 automatic switches of the input mode.
2446 @defopt idlwave-shell-use-input-mode-magic (@code{nil})
2447 Non-@code{nil} means IDLWAVE should check for input mode spells in
2448 output.
2449 @end defopt
2451 @defopt idlwave-shell-input-mode-spells
2452 The three regular expressions which match the magic spells for input
2453 modes.
2454 @end defopt
2456 @node Commands Sent to the Shell, Debugging IDL Programs, Using the Shell, The IDLWAVE Shell
2457 @section Commands Sent to the Shell
2458 @cindex Commands in shell, showing
2459 @cindex Showing commands in shell
2461 The IDLWAVE buffers and shell interact very closely.  In addition to the
2462 normal commands you enter at the @code{IDL>} prompt, many other special
2463 commands are sent to the shell, sometimes as a direct result of invoking
2464 a key command, menu item, or toolbar button, but also automatically, as
2465 part of the normal flow of information updates between the buffer and
2466 shell.
2468 The commands sent include @code{breakpoint}, @code{.step} and other
2469 debug commands (@pxref{Debugging IDL Programs}), @code{.run} and other
2470 compilation statements (@pxref{Compiling Programs}), examination
2471 commands like @code{print} and @code{help} (@pxref{Examining
2472 Variables}), and other special purpose commands designed to keep
2473 information on the running shell current.
2475 By default, much of this background shell input and output is hidden
2476 from the user, but this is configurable.  The custom variable
2477 @code{idlwave-abbrev-show-commands} allows you to configure which
2478 commands sent to the shell are shown there.  For a related customization
2479 for separating the output of @emph{examine} commands @xref{Examining
2480 Variables}.
2482 @defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)})
2483 A list of command types to echo in the shell when sent.  Possible values
2484 are @code{run} for @code{.run}, @code{.compile} and other run commands,
2485 @code{misc} for lesser used commands like @code{window}, @code{retall},
2486 etc., @code{breakpoint} for breakpoint setting and clearing commands,
2487 and @code{debug} for other debug, stepping, and continue commands.  In
2488 addition, if the variable is set to the single symbol @code{'everything},
2489 all the copious shell input is displayed (which is probably only useful
2490 for debugging purposes).
2491 @end defopt
2493 @node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell
2494 @section Debugging IDL Programs
2495 @cindex Debugging
2496 @cindex Keybindings for debugging
2497 @cindex Toolbar
2499 Programs can be compiled, run, and debugged directly from the source
2500 buffer in Emacs.  IDLWAVE makes compiling and debugging IDL programs
2501 far less cumbersome by providing a full-featured,
2502 key/menu/toolbar-driven interface to commands like @code{breakpoint},
2503 @code{.step}, @code{.run}, etc.
2505 The IDLWAVE shell installs key bindings both in the shell buffer and in
2506 all IDL code buffers of the current Emacs session, so debug commands
2507 work in both places (in the shell, commands operate on the last file
2508 compiled).  On Emacs versions which support this, a debugging toolbar is
2509 also installed.  The display of the toolbar can be toggled with @kbd{C-c
2510 C-d C-t} (@code{idlwave-shell-toggle-toolbar}).
2512 @defopt idlwave-shell-use-toolbar (@code{t})
2513 Non-@code{nil} means use the debugging toolbar in all IDL related
2514 buffers.
2515 @end defopt
2517 @menu
2518 * Debug Key Bindings::
2519 * Compiling Programs::
2520 * Breakpoints and Stepping::
2521 * Walking the Calling Stack::
2522 @end menu
2524 @node Debug Key Bindings, Compiling Programs, Debugging IDL Programs, Debugging IDL Programs
2525 @subsection Debug Key Bindings
2526 @kindex C-c C-d
2527 @cindex Key bindings
2529 The debugging key bindings are by default on the prefix key @kbd{C-c
2530 C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d
2531 C-b}, and compiling a source file with @kbd{C-c C-d C-c}.  If you find
2532 this too much work, you can easily configure IDLWAVE to use one or more
2533 modifier keys not in use by other commands, in lieu of the prefix
2534 @kbd{C-c C-d} (though these bindings will typically also be available
2535 --- see @code{idlwave-shell-activate-prefix-keybindings}).  For example,
2536 if you write in @file{.emacs}:
2538 @lisp
2539 (setq idlwave-shell-debug-modifiers '(control shift))
2540 @end lisp
2542 @noindent a breakpoint can be set by pressing @kbd{b} while holding down
2543 @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}.  Compiling a
2544 source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d},
2545 etc.  In the remainder of this chapter we will assume that the @kbd{C-c
2546 C-d} bindings are active, but each of these bindings will have an
2547 equivalent single-keypress shortcut if modifiers are given in the
2548 @code{idlwave-shell-debug-modifiers} variable (see @pxref{Lesson II --
2549 Customization}).
2551 @defopt idlwave-shell-prefix-key (@kbd{C-c C-d})
2552 The prefix key for the debugging map
2553 @code{idlwave-shell-mode-prefix-map}.
2554 @end defopt
2556 @defopt idlwave-shell-activate-prefix-keybindings (@code{t})
2557 Non-@code{nil} means debug commands will be bound to the prefix
2558 key, like @kbd{C-c C-d C-b}.
2559 @end defopt
2561 @defopt idlwave-shell-debug-modifiers (@code{nil})
2562 List of modifier keys to use for additional binding of debugging
2563 commands in the shell and source buffers.  Can be one or more of
2564 @code{control}, @code{meta}, @code{super}, @code{hyper}, @code{alt}, and
2565 @code{shift}.
2566 @end defopt
2568 @node Compiling Programs, Breakpoints and Stepping, Debug Key Bindings, Debugging IDL Programs
2569 @subsection Compiling Programs
2570 @cindex Compiling programs
2571 @cindex Programs, compiling
2572 @cindex Default command line, executing
2573 @cindex Executing a default command line
2575 @kindex C-c C-d C-c
2576 In order to compile the current buffer under the IDLWAVE shell, press
2577 @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}).  This first saves the
2578 current buffer and then sends the command @samp{.run path/to/file} to the
2579 shell.  You can also execute @kbd{C-c C-d C-c} from the shell buffer, in
2580 which case the most recently compiled buffer will be saved and
2581 re-compiled.
2583 When developing or debugging a program, it is often necessary to execute
2584 the same command line many times.  A convenient way to do this is
2585 @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}).
2586 This command first resets IDL from a state of interrupted execution by
2587 closing all files and returning to the main interpreter level.  Then a
2588 default command line is send to the shell.  To edit the default command
2589 line, call @code{idlwave-shell-execute-default-command-line} with a
2590 prefix argument: @kbd{C-u C-c C-d C-y}.
2592 @defopt idlwave-shell-mark-stop-line (@code{t})
2593 Non-@code{nil} means mark the source code line where IDL is currently
2594 stopped.  The value specifies the preferred method.  Legal values are
2595 @code{nil}, @code{t}, @code{arrow}, and @code{face}.
2596 @end defopt
2598 @defopt idlwave-shell-overlay-arrow (@code{">"})
2599 The overlay arrow to display at source lines where execution halts, if
2600 configured in @code{idlwave-shell-mark-stop-line}.
2601 @end defopt
2603 @defopt idlwave-shell-stop-line-face
2604 The face which highlights the source line where IDL is stopped, if
2605 configured in @code{idlwave-shell-mark-stop-line}.
2606 @end defopt
2608 @node Breakpoints and Stepping, Walking the Calling Stack, Compiling Programs, Debugging IDL Programs
2609 @subsection Breakpoints and Stepping
2610 @cindex Breakpoints
2611 @cindex Stepping
2612 @cindex Execution, controlled
2614 @kindex C-c C-d C-b
2615 @kindex C-c C-d C-b
2616 You can set breakpoints and step through a program with IDLWAVE.
2617 Setting a breakpoint in the current line of the source buffer is done
2618 with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}).  With a prefix
2619 arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a
2620 @code{/ONCE} keyword, meaning that it will be deleted after first use.
2621 With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), the
2622 breakpoint will only be active the @code{nth} time it is hit.  With a
2623 single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt for a
2624 condition --- an IDL expression to be evaulated and trigger the
2625 breakpoint only if true.  To clear the breakpoint in the current line,
2626 use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}).  When executed
2627 from the shell window, the breakpoint where IDL is currently stopped
2628 will be deleted.  To clear all breakpoints, use @kbd{C-c C-d C-a}
2629 (@code{idlwave-clear-all-bp}).  Breakpoint lines are highlighted in the
2630 source code.  Note that IDL places breakpoints as close as possible on
2631 or after the line you specify.  IDLWAVE queries the shell for the actual
2632 breakpoint location which was set, so the exact line you specify may not
2633 be marked.
2635 Once the program has stopped somewhere, you can step through it.  The
2636 most important stepping commands are @kbd{C-c C-d C-s} to execute one
2637 line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line,
2638 treating procedure and function calls as a single step ("step over");
2639 @kbd{C-c C-d C-h} to continue execution to the line at the cursor and
2640 @kbd{C-c C-d C-r} to continue execution.  @xref{Commands Sent to the
2641 Shell}, for information on displaying or hiding the breakpoint and
2642 stepping commands the shell receives.  Here is a summary of the
2643 breakpoint and stepping commands:
2645 @multitable @columnfractions .23 .77
2646 @item @kbd{C-c C-d C-b}
2647 @tab Set breakpoint (@code{idlwave-shell-break-here})
2648 @item @kbd{C-c C-d C-i}
2649 @tab Set breakpoint in function named here (@code{idlwave-shell-break-in})
2650 @item @kbd{C-c C-d C-d}
2651 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp})
2652 @item @kbd{C-c C-d C-a}
2653 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp})
2654 @item @kbd{C-c C-d C-s}
2655 @tab Step, into function calls (@code{idlwave-shell-step})
2656 @item @kbd{C-c C-d C-n}
2657 @tab Step, over function calls (@code{idlwave-shell-stepover})
2658 @item @kbd{C-c C-d C-k}
2659 @tab Skip one statement (@code{idlwave-shell-skip})
2660 @item @kbd{C-c C-d C-u}
2661 @tab Continue to end of block (@code{idlwave-shell-up})
2662 @item @kbd{C-c C-d C-m}
2663 @tab Continue to end of function (@code{idlwave-shell-return})
2664 @item @kbd{C-c C-d C-o}
2665 @tab Continue past end of function (@code{idlwave-shell-out})
2666 @item @kbd{C-c C-d C-h}
2667 @tab Continue to line at cursor position (@code{idlwave-shell-to-here})
2668 @item @kbd{C-c C-d C-r}
2669 @tab Continue execution to next breakpoint (@code{idlwave-shell-cont})
2670 @item @kbd{C-c C-d C-up}
2671 @tab Show higher level in calling stack (@code{idlwave-shell-stack-up})
2672 @item @kbd{C-c C-d C-down}
2673 @tab Show lower level in calling stack (@code{idlwave-shell-stack-down})
2674 @end multitable
2676 @defopt idlwave-shell-mark-breakpoints (@code{t})
2677 Non-@code{nil} means mark breakpoints in the source file buffers.  The
2678 value indicates the preferred method.  Legal values are @code{nil},
2679 @code{t}, @code{face}, and @code{glyph}.
2680 @end defopt
2682 @defopt idlwave-shell-breakpoint-face
2683 The face for breakpoint lines in the source code if
2684 @code{idlwave-shell-mark-breakpoints} has the value @code{face}.
2685 @end defopt
2687 @node Walking the Calling Stack,  , Breakpoints and Stepping, Debugging IDL Programs
2688 @subsection Walking the Calling Stack
2689 @cindex Calling stack, walking
2691 While debugging a program, it can be very useful to check the context in
2692 which the current routine was called, for instance to help understand
2693 the value of the arguments passed.  To do so conveniently you need to
2694 examine the calling stack.  If execution is stopped somewhere deep in a
2695 program, you can use the commands @kbd{C-c C-d C-@key{UP}}
2696 (@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}}
2697 (@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons,
2698 to move up or down through the calling stack.  The mode line of the
2699 shell window will indicate the position within the stack with a label
2700 like @samp{[-3:MYPRO]}.  The line of IDL code at that stack position
2701 will be highlighted.  If you continue execution, IDLWAVE will
2702 automatically return to the current level. @xref{Examining Variables},
2703 for information how to examine the value of variables and expressions on
2704 higher calling stack levels.
2706 @ifhtml
2707 <A NAME="EXAMINE"></A>
2708 @end ifhtml
2709 @node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell
2710 @section Examining Variables
2711 @cindex @code{PRINT} expressions
2712 @cindex @code{HELP}, on expressions
2713 @cindex Expressions, printing
2714 @cindex Expressions, help
2715 @cindex Printing expressions
2716 @cindex Mouse binding to print expressions
2718 @kindex C-c C-d C-p
2719 Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)},
2720 and similar statements to remind yourself of the
2721 type/size/structure/value/etc. of variables and expressions in your code
2722 or at the command line?  IDLWAVE has a suite of special commands to
2723 automate these types of variables or expression examinations.  They work
2724 by sending statements to the shell formatted to include the indicated
2725 expression.
2727 These examination commands can be used in the shell or buffer at any
2728 time (as long as the shell is running), and are very useful when
2729 execution is stopped in a buffer due to a triggered breakpoint or error,
2730 or while composing a long command in the IDLWAVE shell.  In the latter
2731 case, the command is sent to the shell and its output is visible, but
2732 point remains unmoved in the command being composed --- you can inspect
2733 the constituents of a command you're building without interrupting the
2734 process of building it!  You can even print arbitrary expressions from
2735 older input or output further up in the shell window --- any expression,
2736 variable, number, or function you see can be examined.
2738 If the variable @code{idlwave-shell-separate-examine-output} is
2739 non-@code{nil} (the default), all examine output will be sent to a
2740 special @file{*Examine*} buffer, rather than the shell.  The output of
2741 prior examine commands is saved.  In this buffer @key{c} clears the
2742 contents, and @key{q} hides the buffer.
2744 The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to
2745 print the expression at point, and @kbd{C-c C-d ?}, to invoke help on
2746 this expression.  The expression at point is either an array expression
2747 or a function call, or the contents of a pair of parentheses.  The
2748 selected expression is highlighted, and simultaneously the resulting
2749 output is highlighted in the shell.  Calling the above commands with a
2750 prefix argument will prompt for an expression instead of using the one
2751 at point.  Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will use the
2752 current region as expression.
2754 For added speed and convenience, there are mouse bindings which allow
2755 you to click on expressions and examine their values.  Use
2756 @kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke
2757 help (i.e. you need to hold down @key{META} and @key{CONTROL} while
2758 clicking with the middle mouse button).  If you simply click, the
2759 nearest expression will be selected in the same manner as described
2760 above.  You can also @emph{drag} the mouse in order to highlight exactly
2761 a specific expression or sub-expression to be examined.  For custom
2762 expression examination, and the customizable pop-up examine selection,
2763 @xref{Custom Expression Examination}.
2765 @cindex Printing expressions, on calling stack
2766 @cindex Restrictions for expression printing
2767 The same variable inspection commands work both in the IDL Shell and
2768 IDLWAVE buffers, and even for variables at higher levels of the calling
2769 stack.  For instance, if you're stopped at a breakpoint in a routine,
2770 you can examine the values of variables and expressions inside its
2771 calling routine, and so on, all the way up through the calling stack.
2772 Simply step up the stack, and print variables as you see them
2773 (@pxref{Walking the Calling Stack}, for information on stepping back
2774 through the calling stack).  The following restrictions apply for all
2775 levels except the current:
2777 @itemize @bullet
2778 @item
2779 Array expressions must use the @samp{[ ]} index delimiters.  Identifiers
2780 with a @samp{( )} will be interpreted as function calls.
2781 @item
2782 @cindex ROUTINE_NAMES, IDL procedure
2783 N.B.: printing values of expressions on higher levels of the calling
2784 stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES},
2785 which may or may not be available in future versions of IDL.
2786 @end itemize
2788 @defopt idlwave-shell-expression-face
2789 The face for @code{idlwave-shell-expression-overlay}.
2790 Allows you to choose the font, color and other properties for
2791 the expression printed by IDL.
2792 @end defopt
2794 @defopt idlwave-shell-output-face
2795 The face for @code{idlwave-shell-output-overlay}.
2796 Allows to choose the font, color and other properties for the most
2797 recent output of IDL when examining an expression."
2798 @end defopt
2800 @defopt idlwave-shell-separate-examine-output (@code{t})
2801 If non-@code{nil}, re-direct the output of examine commands to a special
2802 @file{*Examine*} buffer, instead of in the shell itself.
2803 @end defopt
2805 @node Custom Expression Examination,  , Examining Variables, The IDLWAVE Shell
2806 @section Custom Expression Examination
2807 @cindex Expressions, custom examination
2808 @cindex Custom expression examination
2810 The variety of possible variable and expression examination commands is
2811 endless (just look, for instance, at the keyword list to
2812 @code{widget_info()}).  Rather than attempt to include them all, IDLWAVE
2813 provides two easy methods to customize your own commands, with a special
2814 mouse examine command, and two macros for generating your own examine
2815 bindings.
2817 The most powerful and flexible mouse examine command is available on
2818 @kbd{C-S-Mouse-2}.  Just as for all the other mouse examine commands, it
2819 permits click or drag expression selection, but instead of sending
2820 hard-coded commands to the shell, it pops-up a customizable selection
2821 list of examine functions to choose among, configured with the
2822 @code{idlwave-shell-examine-alist} variable.  This variable is a list of
2823 key-value pairs (an @emph{alist} in Emacs parlance), where the keys name
2824 the command, and the values are the command strings, in which the text
2825 @code{___} (three underscores) will be replaced by the selected
2826 expression before being sent to the shell.  An example might be key
2827 @code{Structure Help} with value @code{help,___,/STRUCTURE}.
2828 @code{idlwave-shell-examine-alist} comes by default with a large list of
2829 examine commands, but can be easily customized to add more.
2831 In addition to the pop-up mouse command, you can easily create your own
2832 customized bindings to inspect expressions using the two convenience
2833 macros @code{idlwave-shell-inspect} and
2834 @code{idlwave-shell-mouse-inspect}.  These create keyboard or
2835 mouse-based custom inspections of variables, sharing all the same
2836 properties of the built-in examine commands.  Both functions take a
2837 single string argument sharing the syntax of the
2838 @code{idlwave-shell-examine-alist} values, e.g.:
2840 @lisp
2841 (add-hook 'idlwave-shell-mode-hook
2842           (lambda ()
2843             (idlwave-shell-define-key-both [s-down-mouse-2]
2844                                  (idlwave-shell-mouse-examine
2845                                   "print, size(___,/DIMENSIONS)"))
2846             (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
2847                                        "print, size(___,/DIMENSIONS)"))
2848             (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
2849                                         "print,size(___,/TNAME)"))
2850             (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
2851                                         "help,___,/STRUCTURE"))))
2852 @end lisp
2854 @noindent Now pressing @key{f9}, or middle-mouse dragging with the
2855 @key{SUPER} key depressed, will print the dimensions of the nearby or
2856 highlighted expression.  Pressing @key{f10} will give the type string,
2857 and @key{f11} will show the contents of a nearby structure.  As you can
2858 see, the possibilities are only marginally finite.
2860 @defopt idlwave-shell-examine-alist
2861 An alist of examine commands in which the keys name the command and are
2862 displayed in the selection pop-up, and the values are custom IDL examine
2863 command strings to send, after all instances of @code{___} are replaced
2864 by the indicated expression.
2865 @end defopt
2868 @node Installation, Acknowledgements, The IDLWAVE Shell, Top
2869 @chapter Installation
2870 @cindex Installation
2872 @menu
2873 * Installing IDLWAVE::          How to install the distribution
2874 * Installing Online Help::      Where to get the additional files needed
2875 * Upgrading from idl.el::       Necessary configuration changes
2876 @end menu
2878 @node Installing IDLWAVE, Installing Online Help, Installation, Installation
2879 @section Installing IDLWAVE
2881 @cindex FTP site
2882 @cindex URL, homepage for IDLWAVE
2883 @cindex Homepage for IDLWAVE
2884 @cindex IDLWAVE, homepage
2885 @cindex XEmacs package IDLWAVE
2886 @cindex Emacs, distributed with IDLWAVE
2887 @cindex Copyright, of IDL manual
2888 IDLWAVE is part of Emacs 21.1 and later.  It is also an XEmacs package
2889 and can be installed from
2890 @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site}
2891 with the normal package management system on XEmacs 21.  These
2892 pre-installed versions should work out-of-the-box.  However, the files
2893 required for online help are not distributed with XEmacs/Emacs and have
2894 to be installed separately@footnote{Due to copyright reasons, the ASCII
2895 version of the IDL manual cannot be distributed under the GPL.}
2896 (@pxref{Installing Online Help}).
2898 You can also download IDLWAVE and install it yourself from
2899 @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}.  Follow the
2900 instructions in the INSTALL file.
2902 @node Installing Online Help, Upgrading from idl.el, Installing IDLWAVE, Installation
2903 @section Installing Online Help
2904 @cindex Installing online help
2905 @cindex Online Help, Installation
2907 If you want to use the online help display, two additional files (an
2908 ASCII version of the IDL documentation and a topics/code file) must be
2909 installed.  These files can also be downloaded from
2910 @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}.  You need to
2911 place the files somewhere on your system and tell IDLWAVE where they are
2912 with
2914 @lisp
2915 (setq idlwave-help-directory "/path/to/help/files/")
2916 @end lisp
2918 @node Upgrading from idl.el,  , Installing Online Help, Installation
2919 @section Upgrading from the old @b{@file{idl.el}} file
2920 @cindex Upgrading from old @b{@file{idl.el}}
2921 @cindex Renaming old variables
2922 @cindex Old variables, renaming
2923 @kindex M-@key{TAB}
2925 If you have been using the old @file{idl.el} and @file{idl-shell.el}
2926 files and would like to use IDLWAVE, you need to update your
2927 customization in @file{.emacs}.
2929 @enumerate
2930 @item
2931 Change all variable and function prefixes from @samp{idl-} to @samp{idlwave-}.
2932 @item
2933 Remove the now invalid @code{autoload} and @code{auto-mode-alist} forms
2934 pointing to the @file{idl.el} and @file{idl-shell.el} files.  Install
2935 the new autoload forms.
2936 @item
2937 If you have been using the hook function recommended in earlier versions
2938 to get a separate frame for the IDL shell, remove that command from your
2939 @code{idlwave-shell-mode-hook}.  Instead, set the variable
2940 @code{idlwave-shell-use-dedicated-frame} with
2941 @lisp
2942 (setq idlwave-shell-use-dedicated-frame t)
2943 @end lisp
2944 @item
2945 The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character.
2946 Like in many other Emacs modes, @kbd{M-@key{TAB}} now does
2947 completion.  Inserting a TAB has therefore been moved to
2948 @kbd{C-@key{TAB}}.  On a character based terminal you can also use
2949 @kbd{C-c @key{SPC}}.
2950 @end enumerate
2952 @node Acknowledgements, Sources of Routine Info, Installation, Top
2953 @chapter Acknowledgements
2954 @cindex Acknowledgements
2955 @cindex Maintainer, of IDLWAVE
2956 @cindex Authors, of IDLWAVE
2957 @cindex Contributors, to IDLWAVE
2958 @cindex Email address, of Maintainer
2959 @cindex Thanks
2961 @noindent
2962 The main contributors to the IDLWAVE package have been:
2964 @itemize @minus
2965 @item
2966 @uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author.
2967 Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them
2968 for several years.
2970 @item
2971 @uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge
2972 of the package from version 3.0, during which time he overhauled almost
2973 everything, modernized IDLWAVE with many new features, and developed the
2974 manual.
2976 @item
2977 @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current
2978 maintainer, as of version 4.10, helped shape object method completion
2979 and most new features introduced in versions 4.x.
2980 @end itemize
2982 @noindent
2983 The following people have also contributed to the development of IDLWAVE
2984 with patches, ideas, bug reports and suggestions.
2986 @itemize @minus
2987 @item
2988 Ulrik Dickow <dickow@@nbi.dk>
2989 @item
2990 Eric E. Dors <edors@@lanl.gov>
2991 @item
2992 Stein Vidar H. Haugan <s.v.h.haugan@@astro.uio.no>
2993 @item
2994 David Huenemoerder <dph@@space.mit.edu>
2995 @item
2996 Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de>
2997 @item
2998 Dick Jackson <dick@@d-jackson.com>
2999 @item
3000 Xuyong Liu <liu@@stsci.edu>
3001 @item
3002 Simon Marshall <Simon.Marshall@@esrin.esa.it>
3003 @item
3004 Craig Markwardt <craigm@@cow.physics.wisc.edu>
3005 @item
3006 Laurent Mugnier <mugnier@@onera.fr>
3007 @item
3008 Lubos Pochman <lubos@@rsinc.com>
3009 @item
3010 Bob Portmann <portmann@@al.noaa.gov>
3011 @item
3012 Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov>
3013 @item
3014 Marty Ryba <ryba@@ll.mit.edu>
3015 @item
3016 Phil Williams <williams@@irc.chmcc.org>
3017 @item
3018 Phil Sterne <sterne@@dublin.llnl.gov>
3019 @end itemize
3021 @noindent
3022 Thanks to everyone!
3024 @node Sources of Routine Info, Configuration Examples, Acknowledgements, Top
3025 @appendix Sources of Routine Info
3027 @cindex Sources of routine information
3028 In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE
3029 displays the calling sequence and keywords of routines, and completes
3030 routine names and keywords.  For these features to work, IDLWAVE must
3031 know about the accessible routines.
3033 @menu
3034 * Routine Definitions::         Where IDL Routines are defined.
3035 * Routine Information Sources::  So how does IDLWAVE know about...
3036 * Library Catalog::             Scanning the Libraries for Routine Info
3037 * Load-Path Shadows::           Routines defined in several places
3038 * Documentation Scan::          Scanning the IDL Manuals
3039 @end menu
3041 @node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info
3042 @appendixsec Routine Definitions
3043 @cindex Routine definitions
3044 @cindex IDL variable @code{!PATH}
3045 @cindex @code{!PATH}, IDL variable
3046 @cindex @code{CALL_EXTERNAL}, IDL routine
3047 @cindex @code{LINKIMAGE}, IDL routine
3048 @cindex External routines
3050 @noindent Routines which can be used in an IDL program can be defined in
3051 several places:
3053 @enumerate
3054 @item
3055 @emph{Builtin routines} are defined inside IDL itself.  The source
3056 code of such routines is not available.
3057 @item
3058 Routines which are @emph{part of the current program}, are defined in a
3059 file explicitly compiled by the user.  This file may or may not be
3060 located on the IDL search path.
3061 @item
3062 @emph{Library routines} are defined in files located on IDL's search
3063 path, and will not need to be manually compiled.  When a library routine
3064 is called for the first time, IDL will find the source file and compile
3065 it dynamically.  A special sub-category of library routines are the
3066 @emph{system routines} distributed with IDL, and usually available in
3067 the @file{lib} subdirectory of the IDL distribution.
3068 @item
3069 External routines written in other languages (like Fortran or C) can be
3070 called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE},
3071 or included as dynamically loaded modules (DLMs).  Currently IDLWAVE
3072 cannot provide routine info and completion for such external routines.
3073 @end enumerate
3075 @node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info
3076 @appendixsec Routine Information Sources
3077 @cindex Routine info sources
3078 @cindex Builtin list of routines
3079 @cindex Updating routine info
3080 @cindex Scanning buffers for routine info
3081 @cindex Buffers, scanning for routine info
3082 @cindex Shell, querying for routine info
3084 @noindent To maintain the most comprehensive information about all IDL
3085 routines on a system, IDLWAVE collects data from many sources:
3087 @enumerate
3089 @item
3090 It has a @emph{builtin list} with the properties of the builtin IDL
3091 routines.  IDLWAVE @value{VERSION} is distributed with a list of
3092 @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords,
3093 reflecting IDL version @value{IDLVERSION}.  This list has been created
3094 by scanning the IDL manuals and is stored in the file
3095 @file{idlw-rinfo.el}.  @xref{Documentation Scan}, for information on how
3096 to regenerate this file for new versions of IDL.
3098 @item
3099 It @emph{scans} all @emph{buffers} of the current Emacs session for
3100 routine definitions.  This is done automatically when routine
3101 information or completion is first requested by the user.  Each new
3102 buffer and each buffer which is saved after making changes is also
3103 scanned. The command @kbd{C-c C-i} (@code{idlwave-update-routine-info})
3104 can be used at any time to rescan all buffers.
3106 @item
3107 If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will
3108 @emph{query the shell} for compiled routines and their arguments.  This
3109 happens automatically when routine information or completion is first
3110 requested by the user, and each time an Emacs buffer is compiled with
3111 @kbd{C-c C-d C-c}.  Though rarely necessary, the command @kbd{C-c C-i}
3112 (@code{idlwave-update-routine-info}) can be used to update the shell
3113 routine data.
3115 @item
3116 IDLWAVE can scan all or selected library source files and store the
3117 result in a file which will be automatically loaded just like
3118 @file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to
3119 scan library files.
3120 @end enumerate
3122 Loading routine and catalog information is a time consuming process.
3123 Depending on the system and network configuration it can take up to 30
3124 seconds.  In order to minimize the waiting time upon your first
3125 completion or routine info command in a session, IDLWAVE uses Emacs idle
3126 time to do the initialization in 5 steps, yielding to user input in
3127 between.  If this gets into your way, set the variable
3128 @code{idlwave-init-rinfo-when-idle-after} to 0 (zero).
3130 @defopt idlwave-init-rinfo-when-idle-after (@code{10})
3131 Seconds of idle time before routine info is automatically initialized.
3132 @end defopt
3134 @defopt idlwave-scan-all-buffers-for-routine-info (@code{t})
3135 Non-@code{nil} means scan all buffers for IDL programs when updating
3136 info.
3137 @end defopt
3139 @defopt idlwave-query-shell-for-routine-info (@code{t})
3140 Non-@code{nil} means query the shell for info about compiled routines.
3141 @end defopt
3143 @defopt idlwave-auto-routine-info-updates
3144 Controls under what circumstances routine info is updated automatically.
3145 @end defopt
3147 @node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
3148 @appendixsec Library Catalog
3149 @cindex Library scan
3150 @cindex Library catalog
3151 @cindex IDL library routine info
3152 @cindex Windows
3153 @cindex MacOS
3154 @cindex IDL variable @code{!DIR}
3155 @cindex @code{!DIR}, IDL variable
3158 IDLWAVE can extract routine information from library modules and store
3159 that information in a file.  To do this, the variable
3160 @code{idlwave-libinfo-file} needs to contain the path to a file in an
3161 existing directory (the default is @code{"~/.idlcat.el"}).  Since the
3162 file will contain lisp code, its name should end in @file{.el}.  Under
3163 Windows and MacOS, you also need to specify the search path for IDL
3164 library files in the variable @code{idlwave-library-path}, and the
3165 location of the IDL directory (the value of the @code{!DIR} system
3166 variable) in the variable @code{idlwave-system-directory}, like
3167 this@footnote{The initial @samp{+} leads to recursive expansion of the
3168 path, just like in IDL}:
3170 @lisp
3171 (setq idlwave-library-path
3172         '("+c:/RSI/IDL54/lib/" "+c:/user/me/idllibs" ))
3173 (setq idlwave-system-directory "c:/RSI/IDL54/")
3174 @end lisp
3176 @noindent Under GNU and UNIX, these values will be automatically inferred from
3177 an IDLWAVE shell.
3179 The command @kbd{M-x idlwave-create-libinfo-file} can then be used to
3180 scan library files.  It brings up a widget in which you can select some
3181 or all directories on the search path.  If you only want to have routine
3182 and completion info of some libraries, it is sufficient to scan those
3183 directories.  However, if you want IDLWAVE to detect possible name
3184 conflicts with routines defined in other libraries, the whole pass
3185 should be scanned.
3187 After selecting directories, click on the @w{@samp{[Scan & Save]}}
3188 button in the widget to scan all files in the selected directories and
3189 write the resulting routine information into the file
3190 @code{idlwave-libinfo-file}.  In order to update the library information
3191 from the same directories, call the command
3192 @code{idlwave-update-routine-info} with a double prefix argument:
3193 @w{@kbd{C-u C-u C-c C-i}}.  This will rescan files in the previously
3194 selected directories, write an updated version of the libinfo file and
3195 rebuild IDLWAVE's internal lists.  If you give three prefix arguments
3196 @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a background
3197 job@footnote{Unix systems only, I think.}.  You can continue to work,
3198 and the library catalog will be re-read when it is ready.
3200 A note of caution:  Depending on your local installation, the IDL
3201 library can be very large.  Parsing it for routine information will take
3202 time and loading this information into Emacs can require a
3203 significant amount of memory.  However, having this information
3204 available will be a great help.
3206 @defopt idlwave-libinfo-file
3207 File for routine information of the IDL library.
3208 @end defopt
3210 @defopt idlwave-library-path
3211 IDL library path for Windows and MacOS.  Not needed under Unix.
3212 @end defopt
3214 @defopt idlwave-system-directory
3215 The IDL system directory for Windows and MacOS.  Not needed under Unix.
3216 @end defopt
3218 @defopt idlwave-special-lib-alist
3219 Alist of regular expressions matching special library directories.
3220 @end defopt
3222 @node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info
3223 @appendixsec Load-Path Shadows
3224 @cindex Load-path shadows
3225 @cindex Shadows, load-path
3226 @cindex Duplicate routines
3227 @cindex Multiply defined routines
3228 @cindex Routine definitions, multiple
3229 @cindex Application, testing for shadowing
3230 @cindex Buffer, testing for shadowing
3232 IDLWAVE can compile a list of routines which are defined in several
3233 different files.  Since one definition will hide (shadow) the others
3234 depending on which file is compiled first, such multiple definitions are
3235 called "load-path shadows".  IDLWAVE has several routines to scan for
3236 load path shadows.  The output is placed into the special buffer
3237 @file{*Shadows*}.  The format of the output is identical to the source
3238 section of the routine info buffer (@pxref{Routine Info}).  The
3239 different definitions of a routine are listed in the sequence of
3240 @emph{likelihood of use}.  So the first entry will be most likely the
3241 one you'll get if an unsuspecting command uses that routine.  Before
3242 listing shadows, you should make sure that routine info is up-to-date by
3243 pressing @kbd{C-c C-i}.  Here are the different routines:
3245 @table @asis
3246 @item @kbd{M-x idlwave-list-buffer-load-path-shadows}
3247 This commands checks the names of all routines defined in the current
3248 buffer for shadowing conflicts with other routines accessible to
3249 IDLWAVE.  The command also has a key binding: @kbd{C-c C-b}
3250 @item @kbd{M-x idlwave-list-shell-load-path-shadows}.
3251 Checks all routines compiled under the shell for shadowing.  This is
3252 very useful when you have written a complete application.  Just compile
3253 the application, use @code{RESOLVE_ALL} to compile any routines used by
3254 your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and
3255 then check for shadowing.
3256 @item @kbd{M-x idlwave-list-all-load-path-shadows}
3257 This command checks all routines accessible to IDLWAVE for conflicts.
3258 @end table
3260 For these commands to work properly you should have scanned the entire
3261 load path, not just selected directories.  Also, IDLWAVE should be able
3262 to distinguish between the system library files (normally installed in
3263 @file{/usr/local/rsi/idl/lib}) and any site specific or user specific
3264 files.  Therefore, such local files should not be installed inside the
3265 @file{lib} directory of the IDL directory.  This is also advisable for
3266 many other reasons.
3268 @cindex Windows
3269 @cindex MacOS
3270 @cindex IDL variable @code{!DIR}
3271 @cindex @code{!DIR}, IDL variable
3272 Users of Windows and MacOS also must set the variable
3273 @code{idlwave-system-directory} to the value of the @code{!DIR} system
3274 variable in IDL.  IDLWAVE appends @file{lib} to the value of this
3275 variable and assumes that all files found on that path are system
3276 routines.
3278 Another way to find out if a specific routine has multiple definitions
3279 on the load path is routine info display (@pxref{Routine Info}).
3281 @node Documentation Scan,  , Load-Path Shadows, Sources of Routine Info
3282 @appendixsec Documentation Scan
3283 @cindex @file{get_rinfo}
3284 @cindex @file{idlw-rinfo.el}
3285 @cindex @file{idlw-help.txt}
3286 @cindex @file{idlw-help.el}
3287 @cindex Scanning the documentation
3288 @cindex Perl program, to create @file{idlw-rinfo.el}
3290 IDLWAVE derives it knowledge about system routines from the IDL
3291 manuals.  The file @file{idlw-rinfo.el} contains the routine information
3292 for the IDL system routines.  The Online Help feature of IDLWAVE
3293 requires ASCII versions of some IDL manuals to be available in a
3294 specific format (@file{idlw-help.txt}), along with an Emacs-Lisp file
3295 @file{idlw-help.el} with supporting code and pointers to the ASCII file.
3297 All 3 files can be derived from the IDL documentation.  If you are
3298 lucky, the maintainer of IDLWAVE will always have access to the newest
3299 version of IDL and provide updates.  The IDLWAVE distribution also
3300 contains the Perl program @file{get_rinfo} which constructs these files
3301 by scanning selected files from the IDL documentation.  Instructions on
3302 how to use @file{get_rinfo} are in the program itself.
3304 One particularly frustrating situation occurs when a new IDL version is
3305 released without the associated documentation updates.  Instead, a
3306 @emph{What's New} file containing new and updated documentation is
3307 shipped alongside the previous version's reference material.  The
3308 @file{get_rinfo} script can merge this new information into the standard
3309 help text and routine information, as long as it is pre-formatted in a
3310 simple way.  See @file{get_rinfo} for more information.
3312 @node Configuration Examples, Windows and MacOS, Sources of Routine Info, Top
3313 @appendix Configuration Examples
3314 @cindex Configuration examples
3315 @cindex Example configuration
3316 @cindex @file{.emacs}
3317 @cindex Default settings, of options
3318 @cindex Interview, with the maintainer
3320 @noindent
3321 @b{Question:} You have all these complicated configuration options in
3322 your package, but which ones do @emph{you} as the maintainer actually
3323 set in your own configuration?
3325 @noindent
3326 @b{Answer:} Not many, beyond custom key bindings.  I set most defaults
3327 the way that seems best.  However, the default settings do not turn on
3328 features which:
3330 @itemize @minus
3331 @item
3332 are not self-evident (i.e. too magic) when used by an unsuspecting user.
3333 @item
3334 are too intrusive.
3335 @item
3336 will not work properly on all Emacs installations.
3337 @item
3338 break with widely used standards.
3339 @item
3340 use function or other non-standard keys.
3341 @item
3342 are purely personal customizations, like additional key bindings, and
3343 library names.
3344 @end itemize
3346 @noindent To see what I mean, here is the @emph{entire} configuration
3347 the old maintainer had in his @file{.emacs}:
3349 @lisp
3350 (setq idlwave-shell-debug-modifiers '(control shift)
3351       idlwave-store-inquired-class t
3352       idlwave-shell-automatic-start t
3353       idlwave-main-block-indent 2
3354       idlwave-init-rinfo-when-idle-after 2
3355       idlwave-help-dir "~/lib/emacs/idlwave"
3356       idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib")
3357                                   ("/jhuapl/" . "JHUAPL-Lib")
3358                                   ("/dominik/lib/idl/" . "MyLib")))
3359 @end lisp
3361 However, if you are an Emacs power-user and want IDLWAVE to work
3362 completely differently, you can change almost every aspect of it.  Here
3363 is an example of a much more extensive configuration of IDLWAVE.  The
3364 user is King!
3366 @example
3367 ;;; Settings for IDLWAVE mode
3369 (setq idlwave-block-indent 3)           ; Indentation settings
3370 (setq idlwave-main-block-indent 3)
3371 (setq idlwave-end-offset -3)
3372 (setq idlwave-continuation-indent 1)
3373 (setq idlwave-begin-line-comment "^;[^;]")  ; Leave ";" but not ";;"
3374                                             ; anchored at start of line.
3375 (setq idlwave-surround-by-blank t)      ; Turn on padding ops =,<,>
3376 (setq idlwave-pad-keyword nil)          ; Remove spaces for keyword '='
3377 (setq idlwave-expand-generic-end t)     ; convert END to ENDIF etc...
3378 (setq idlwave-reserved-word-upcase t)   ; Make reserved words upper case
3379                                         ; (with abbrevs only)
3380 (setq idlwave-abbrev-change-case nil)   ; Don't force case of expansions
3381 (setq idlwave-hang-indent-regexp ": ")  ; Change from "- " for auto-fill
3382 (setq idlwave-show-block nil)           ; Turn off blinking to begin
3383 (setq idlwave-abbrev-move t)            ; Allow abbrevs to move point
3384 (setq idlwave-query-class '((method-default . nil) ; No query for method
3385                             (keyword-default . nil); or keyword completion
3386                             ("INIT" . t)           ; except for these
3387                             ("CLEANUP" . t)
3388                             ("SETPROPERTY" .t)
3389                             ("GETPROPERTY" .t)))
3391 ;; Some setting can only be done from a mode hook.  Here is an example:
3392 (add-hook 'idlwave-mode-hook
3393   (lambda ()
3394     (setq case-fold-search nil)          ; Make searches case sensitive
3395     ;; Run other functions here
3396     (font-lock-mode 1)                   ; Turn on font-lock mode
3397     (idlwave-auto-fill-mode 0)           ; Turn off auto filling
3399     ;; Pad with 1 space (if -n is used then make the
3400     ;; padding a minimum of n spaces.)  The defaults use -1
3401     ;; instead of 1.
3402     (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1))
3403     (idlwave-action-and-binding "<" '(idlwave-surround 1 1))
3404     (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-)))
3405     (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
3407     ;; Only pad after comma and with exactly 1 space
3408     (idlwave-action-and-binding "," '(idlwave-surround nil 1))
3409     (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
3411     ;; Pad only after `->', remove any space before the arrow
3412     (idlwave-action-and-binding "->"  '(idlwave-surround 0 -1 nil 2))
3414     ;; Set some personal bindings
3415     ;; (In this case, makes `,' have the normal self-insert behavior.)
3416     (local-set-key "," 'self-insert-command)
3417     (local-set-key [f5] 'idlwave-shell-break-here)
3418     (local-set-key [f6] 'idlwave-shell-clear-current-bp)
3420     ;; Create a newline, indenting the original and new line.
3421     ;; A similar function that does _not_ reindent the original
3422     ;; line is on "\C-j" (The default for emacs programming modes).
3423     (local-set-key "\n" 'idlwave-newline)
3424     ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference.
3426     ;; Some personal abbreviations
3427     (define-abbrev idlwave-mode-abbrev-table
3428       (concat idlwave-abbrev-start-char "wb") "widget_base()"
3429       (idlwave-keyword-abbrev 1))
3430     (define-abbrev idlwave-mode-abbrev-table
3431       (concat idlwave-abbrev-start-char "on") "obj_new()"
3432       (idlwave-keyword-abbrev 1))
3433     ))
3435 ;;; Settings for IDLWAVE SHELL mode
3437 (setq idlwave-shell-overlay-arrow "=>")        ; default is ">"
3438 (setq idlwave-shell-use-dedicated-frame t)     ; Make a dedicated frame
3439 (setq idlwave-shell-prompt-pattern "^WAVE> ")  ; default is "^IDL> "
3440 (setq idlwave-shell-explicit-file-name "wave")
3441 (setq idlwave-shell-process-name "wave")
3442 (setq idlwave-shell-use-toolbar nil)           ; No toolbar
3444 ;; Most shell interaction settings can be done from the shell-mode-hook.
3445 (add-hook 'idlwave-shell-mode-hook
3446           (lambda ()
3447             ;; Set up some custom key and mouse examine commands
3448             (idlwave-shell-define-key-both [s-down-mouse-2]
3449                                  (idlwave-shell-mouse-examine
3450                                   "print, size(___,/DIMENSIONS)"))
3451             (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
3452                                        "print, size(___,/DIMENSIONS)"))
3453             (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
3454                                         "print,size(___,/TNAME)"))
3455             (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
3456                                         "help,___,/STRUCTURE"))))
3457 @end example
3459 @ifhtml
3460 <A NAME="WIN_MAC"></A>
3461 @end ifhtml
3462 @node Windows and MacOS, Index, Configuration Examples, Top
3463 @appendix Windows and MacOS
3464 @cindex Windows
3465 @cindex MacOS
3467 IDLWAVE was developed on a UNIX system.  However, due to the portability
3468 of Emacs, much of IDLWAVE does also work under different operating
3469 systems like Windows (with NTEmacs or NTXEmacs) or MacOS.
3471 The only problem really is that RSI does not provide a command-line
3472 version of IDL for Windows or MacOS with which IDLWAVE can
3473 interact@footnote{Call your RSI representative and complain --- it
3474 should be trivial for them to provide one.  And if enough people ask
3475 for it, maybe they will.  The upcoming IDL for Mac OSX is slated to
3476 have a command-line version.}.  Therefore the IDLWAVE Shell does not
3477 work and you have to rely on IDLDE to run and debug your programs.
3478 However, editing IDL source files with Emacs/IDLWAVE works with all
3479 bells and whistles, including routine info, completion and fast online
3480 help.  Only a small amount of additional information must be specified
3481 in your .emacs file: the path names which, on a UNIX system, are
3482 automatically gathered by talking to the IDL program.
3484 Here is an example of the additional configuration needed for a Windows
3485 system.  I am assuming that IDLWAVE has been installed in
3486 @w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in
3487 @w{@samp{C:\RSI\IDL55}}.
3489 @lisp
3490 ;; location of the lisp files (needed if IDLWAVE is not part of
3491 ;; the X/Emacs installation)
3492 (setq load-path (cons "c:/program files/IDLWAVE" load-path))
3494 ;; The location of the IDL library files, both from RSI and your own.
3495 ;; note that the initial "+" expands the path recursively
3496 (setq idlwave-library-path
3497         '("+c:/RSI/IDL55/lib/" "+c:/user/me/idllibs" ))
3499 ;; location of the IDL system directory (try "print,!DIR")
3500 (setq idlwave-system-directory "c:/RSI/IDL55/")
3502 ;; location of the IDLWAVE help files idlw-help.el and idlw-help.txt.
3503 (setq idlwave-help-directory "c:/IDLWAVE")
3505 ;; file in which to store the user catalog info
3506 (setq idlwave-libinfo-file "c:/IDLWAVE/idlcat.el")
3507 @end lisp
3509 @noindent Furthermore, Windows sometimes tries to outsmart you --- make
3510 sure you check the following things:
3512 @itemize @bullet
3513 @item When you download the IDLWAVE distribution, make sure you save the
3514 files under the names @file{idlwave.tar.gz} and
3515 @file{idlwave-help-tar.gz}.
3516 @item Be sure that your software for untarring/ungzipping is @emph{NOT}
3517 doing smart CR/LF conversion (WinZip users will find this in
3518 Options:Configuration:Miscellaneous, change the setting, then re-open
3519 the archive).  This adds one byte per line, throwing off the
3520 byte-counts for the help file lookups and defeating fast online help lookup.
3521 @item M-TAB switches among running programs --- use Esc-TAB
3522 instead.
3523 @item Other issues as yet unnamed...
3524 @end itemize
3527 @node Index,  , Windows and MacOS, Top
3528 @unnumbered Index
3529 @printindex cp
3531 @bye
3533 @ignore
3534    arch-tag: f1d73958-1423-4127-b8aa-f7b953d64492
3535 @end ignore