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