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