/[emacs]/emacs/man/idlwave.texi
ViewVC logotype

Diff of /emacs/man/idlwave.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.18.4.3 by miles, Thu Nov 4 13:12:15 2004 UTC revision 1.18.4.4 by miles, Wed Dec 8 23:31:45 2004 UTC
# Line 1  Line 1 
1  \input texinfo  @c -*-texinfo-*-  \input texinfo  @c -*-texinfo-*-
2  @c %**start of header  @c %**start of header
3  @setfilename ../info/idlwave  @setfilename idlwave
4  @settitle IDLWAVE User Manual  @settitle IDLWAVE User Manual
5    @dircategory Emacs
6    @direntry
7    * IDLWAVE: (idlwave).   Major mode and shell for IDL files.
8    @end direntry
9  @synindex ky cp  @synindex ky cp
10  @syncodeindex vr cp  @syncodeindex vr cp
11  @syncodeindex fn cp  @syncodeindex fn cp
12  @set VERSION 4.15  @set VERSION 5.5
13  @set EDITION 4.15  @set EDITION 5.5
14  @set IDLVERSION 5.5  @set IDLVERSION 6.1
15  @set NSYSROUTINES 1324  @set NSYSROUTINES 1850
16  @set NSYSKEYWORDS 6129  @set NSYSKEYWORDS 7685
17  @set DATE September 2002  @set DATE November, 2004
18  @set AUTHOR J.D. Smith & Carsten Dominik  @set AUTHOR J.D. Smith & Carsten Dominik
19  @set AUTHOR-EMAIL dominik@@astro.uva.nl  @set AUTHOR-EMAIL jdsmith@@as.arizona.edu
20  @set MAINTAINER J.D. Smith  @set MAINTAINER J.D. Smith
21  @set MAINTAINER-EMAIL jdsmith@@as.arizona.edu  @set MAINTAINER-EMAIL jdsmith@@as.arizona.edu
22  @set IDLWAVE-HOMEPAGE http://idlwave.org/  @set IDLWAVE-HOMEPAGE http://idlwave.org/
23  @c %**end of header  @c %**end of header
24    @finalout
25    
26  @copying  @ifinfo
27  This file documents IDLWAVE, a major mode for editing IDL files with  This file documents IDLWAVE, a major mode for editing IDL files with
28  Emacs, and interacting with an IDL shell run as a subprocess.  Emacs, and interacting with an IDL shell run as a subprocess.
29    
30  This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE  This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE
31  @value{VERSION}  @value{VERSION}
32    
33  Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation,  Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 Free Software
34  Inc.  Foundation, Inc.
35    
 @quotation  
36  Permission is granted to copy, distribute and/or modify this document  Permission is granted to copy, distribute and/or modify this document
37  under the terms of the GNU Free Documentation License, Version 1.1 or  under the terms of the GNU Free Documentation License, Version 1.1 or
38  any later version published by the Free Software Foundation; with no  any later version published by the Free Software Foundation; with no
# Line 45  This document is part of a collection di Line 49  This document is part of a collection di
49  Documentation License.  If you want to distribute this document  Documentation License.  If you want to distribute this document
50  separately from the collection, you can do so by adding a copy of the  separately from the collection, you can do so by adding a copy of the
51  license to the document, as described in section 6 of the license.  license to the document, as described in section 6 of the license.
52  @end quotation  @end ifinfo
 @end copying  
   
 @dircategory Emacs  
 @direntry  
 * IDLWAVE: (idlwave).   Major mode and shell for IDL files.  
 @end direntry  
   
 @finalout  
53    
54  @titlepage  @titlepage
55  @title IDLWAVE User Manual  @title IDLWAVE User Manual
56  @subtitle Emacs major mode and shell for IDL  @subtitle Emacs major mode and shell for IDL
57  @subtitle Edition @value{EDITION}, @value{DATE}  @subtitle Edition @value{EDITION}, @value{DATE}
58    
59  @author by Carsten Dominik & J.D. Smith  @author by J.D. Smith & Carsten Dominik
60  @page  @page
61  This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for  This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for
62  IDLWAVE version @value{VERSION}, @value{DATE}.  IDLWAVE version @value{VERSION}, @value{DATE}.
63    @sp 2
64    Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 Free Software
65    Foundation, Inc.
66    @sp 2
67  @cindex Copyright, of IDLWAVE  @cindex Copyright, of IDLWAVE
68  @insertcopying  Permission is granted to copy, distribute and/or modify this document
69    under the terms of the GNU Free Documentation License, Version 1.1 or
70    any later version published by the Free Software Foundation; with no
71    Invariant Sections, with the Front-Cover texts being ``A GNU
72    Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the
73    license is included in the section entitled ``GNU Free Documentation
74    License'' in the Emacs manual.
75    
76    (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
77    this GNU Manual, like GNU software.  Copies published by the Free
78    Software Foundation raise funds for GNU development.''
79    
80    This document is part of a collection distributed under the GNU Free
81    Documentation License.  If you want to distribute this document
82    separately from the collection, you can do so by adding a copy of the
83    license to the document, as described in section 6 of the license.
84  @end titlepage  @end titlepage
85  @contents  @contents
86    
# Line 75  IDLWAVE version @value{VERSION}, @value{ Line 90  IDLWAVE version @value{VERSION}, @value{
90    
91  @node Top, Introduction, (dir), (dir)  @node Top, Introduction, (dir), (dir)
92    
93  IDLWAVE is a package which supports editing source for the  IDLWAVE is a package which supports editing source code written in the
94  Interactive Data Language (IDL), and running IDL as an inferior  Interactive Data Language (IDL), and running IDL as an inferior shell.
 shell.  
95    
96  @end ifnottex  @end ifnottex
97    
98  @menu  @menu
99  * Introduction::                What IDLWAVE is and what it's not  * Introduction::                What IDLWAVE is, and what it is not
100  * IDLWAVE in a Nutshell::       One page quick-start guide  * IDLWAVE in a Nutshell::       One page quick-start guide
101  * Getting Started::             Tutorial  * Getting Started::             Tutorial
102  * The IDLWAVE Major Mode::      The mode to edit IDL programs  * The IDLWAVE Major Mode::      The mode for editing IDL programs
103  * The IDLWAVE Shell::           The mode to run IDL as an inferior program  * The IDLWAVE Shell::           The mode for running IDL as an inferior program
104  * Installation::                How to Install or Upgrade  * Installation::                How to Install or Upgrade              
105  * Acknowledgements::            Who did what  * Acknowledgements::            Who did what
106  * Sources of Routine Info::     How does IDLWAVE know about routine XYZ  * Sources of Routine Info::     How does IDLWAVE know about routine XYZ    
107  * Configuration Examples::      The user is king...  * HTML Help Browser Tips::      
108    * Configuration Examples::      The user is king
109  * Windows and MacOS::           What still works, and how  * Windows and MacOS::           What still works, and how
110    * Troubleshooting::             When good computers turn bad
111  * Index::                       Fast access  * Index::                       Fast access
112    
113  @detailmenu  @detailmenu
# Line 99  shell. Line 115  shell.
115    
116  Getting Started (Tutorial)  Getting Started (Tutorial)
117    
118  * Lesson I -- Development Cycle::  * Lesson I -- Development Cycle::  
119  * Lesson II -- Customization::  * Lesson II -- Customization::  
120  * Lesson III -- Library Catalog::  * Lesson III -- User Catalog::  
121    
122  The IDLWAVE Major Mode  The IDLWAVE Major Mode
123    
# Line 121  The IDLWAVE Major Mode Line 137  The IDLWAVE Major Mode
137  Code Formatting  Code Formatting
138    
139  * Code Indentation::            Reflecting the logical structure  * Code Indentation::            Reflecting the logical structure
140  * Continued Statement Indentation::  * Continued Statement Indentation::  
141  * Comment Indentation::         Special indentation for comment lines  * Comment Indentation::         Special indentation for comment lines
142  * Continuation Lines::          Splitting statements over lines  * Continuation Lines::          Splitting statements over lines
143  * Syntax Highlighting::         Font-lock support  * Syntax Highlighting::         Font-lock support
144  * Octals and Highlighting::     Why "123 causes problems  * Octals and Highlighting::     Why "123 causes problems
145    
146    Online Help
147    
148    * Help with HTML Documentation::  
149    * Help with Source::            
150    
151  Completion  Completion
152    
153  * Case of Completed Words::     CaseOFcomPletedWords  * Case of Completed Words::     CaseOFcomPletedWords
154  * Object Method Completion and Class Ambiguity::  obj->Method, what?  * Object Method Completion and Class Ambiguity::  obj->Method, what?
155  * Object Method Completion in the Shell::  * Object Method Completion in the Shell::  
156  * Class and Keyword Inheritance::  obj->Method, _EXTRA=e  * Class and Keyword Inheritance::  obj->Method, _EXTRA=e
157  * Structure Tag Completion::    Completing state.Tag  * Structure Tag Completion::    Completing state.Tag
158    
# Line 145  The IDLWAVE Shell Line 166  The IDLWAVE Shell
166    
167  * Starting the Shell::          How to launch IDL as a subprocess  * Starting the Shell::          How to launch IDL as a subprocess
168  * Using the Shell::             Interactively working with the Shell  * Using the Shell::             Interactively working with the Shell
169  * Commands Sent to the Shell::  * Commands Sent to the Shell::  
170  * Debugging IDL Programs::  * Debugging IDL Programs::      
171  * Examining Variables::  * Examining Variables::        
172  * Custom Expression Examination::  * Custom Expression Examination::  
173    
174  Debugging IDL Programs  Debugging IDL Programs
175    
176  * Debug Key Bindings::  * A Tale of Two Modes::        
177  * Compiling Programs::  * Debug Key Bindings::          
178  * Breakpoints and Stepping::  * Breakpoints and Stepping::    
179  * Walking the Calling Stack::  * Compiling Programs::          
180    * Walking the Calling Stack::  
181    * Electric Debug Mode::        
182    
183  Installation  Installation
184    
185  * Installing IDLWAVE::          How to install the distribution  * Installing IDLWAVE::          How to install the distribution
186  * Installing Online Help::      Where to get the additional files needed  * Installing Online Help::      Where to get the additional files needed
 * Upgrading from idl.el::       Necessary configuration changes  
187    
188  Sources of Routine Info  Sources of Routine Info
189    
190  * Routine Definitions::         Where IDL Routines are defined.  * Routine Definitions::         Where IDL Routines are defined.
191  * Routine Information Sources::  So how does IDLWAVE know about...  * Routine Information Sources::  So how does IDLWAVE know about...
192  * Library Catalog::             Scanning the Libraries for Routine Info  * Catalogs::                    
193  * Load-Path Shadows::           Routines defined in several places  * Load-Path Shadows::           Routines defined in several places
194  * Documentation Scan::          Scanning the IDL Manuals  * Documentation Scan::          Scanning the IDL Manuals
195    
196    Catalogs
197    
198    * Library Catalogs::            
199    * User Catalog::                
200    
201  @end detailmenu  @end detailmenu
202  @end menu  @end menu
203    
# Line 185  Sources of Routine Info Line 212  Sources of Routine Info
212  @cindex @file{idl-shell.el}  @cindex @file{idl-shell.el}
213  @cindex Feature overview  @cindex Feature overview
214    
215  IDLWAVE is a package which supports editing source files for the  IDLWAVE is a package which supports editing source files written in
216  Interactive Data Language (IDL@footnote{IDL is a registered trademark of  the Interactive Data Language (IDL@footnote{IDL is a registered
217  Research Systems, Inc., a Kodak Company}), and for running IDL as an  trademark of Research Systems, Inc., a Kodak Company}), and running
218  inferior shell@footnote{Note that this package has nothing to do with  IDL as an inferior shell@footnote{Note that this package has nothing
219  the Interface Definition Language, part of the Common Object Request  to do with the Interface Definition Language, part of the Common
220  Broker Architecture (CORBA)}.  It can also be used for editing source  Object Request Broker Architecture (CORBA)}@footnote{IDLWAVE can also
221  files for the related WAVE/CL language, but with only limited  be used for editing source files for the related WAVE/CL language, but
222  support.  with only limited support.}.  It is a feature-rich replacement for the
223    IDLDE development environment bundled with IDL, and uses the full
224  IDLWAVE consists of two main parts: a major mode for editing IDL source  power of Emacs to make editing and running IDL programs easier,
225  files files (@code{idlwave-mode}) and a mode for running the IDL program  quicker, and more structured.
226  as an inferior shell (@code{idlwave-shell-mode}).  Although one mode can  
227  be used without the other, both work together closely to form a complete  IDLWAVE consists of two main parts: a major mode for editing IDL
228  development environment. Here is a brief summary of what IDLWAVE does:  source files (@code{idlwave-mode}) and a mode for running the IDL
229    program as an inferior shell (@code{idlwave-shell-mode}).  Although
230    one mode can be used without the other, both work together closely to
231    form a complete development environment. Here is a brief summary of
232    what IDLWAVE does:
233    
234  @itemize @bullet  @itemize @bullet
235  @item  @item
236  Code indentation and formatting.  Smart code indentation and automatic-formatting.
237  @item  @item
238  Three level syntax highlighting support.  Three level syntax highlighting support.
239  @item  @item
240  Context-sensitive display of calling sequences and keywords for more  Context-sensitive display of calling sequences and keywords for more
241  than 1000 native IDL routines, extendible to any number of additional  than 1000 native IDL routines, extendible to any additional number of
242  routines in your local IDL libraries.  local routines, and already available with many pre-scanned libraries.
243  @item  @item
244  Routine name space conflict search, likelihood-of-use ranking.  Routine name space conflict search with likelihood-of-use ranking.
245  @item  @item
246  Fast, context-sensitive online help.  Fast, context-sensitive online HTML help, or source-header help for
247    undocumented routines.
248  @item  @item
249  Context sensitive completion of routine names and keywords.  Context sensitive completion of routine names, keywords, system
250    variables, class names and much more.
251  @item  @item
252  Easy insertion of code templates.  Easy insertion of code templates and abbreviations of common constructs.
253  @item  @item
254  Automatic corrections to enforce a variety of customizable coding  Automatic corrections to enforce a variety of customizable coding
255  standards.  standards.
# Line 231  Running IDL as an inferior Shell with hi Line 264  Running IDL as an inferior Shell with hi
264  editing and all the completion and routine info capabilities present in  editing and all the completion and routine info capabilities present in
265  IDL source buffers.  IDL source buffers.
266  @item  @item
267  Compilation, execution and interactive debugging of programs directly  Compilation, execution and interactive single-keystroke debugging of
268  from the source buffer.  programs directly from the source buffer.
269  @item  @item
270  Quick, source-guided navigation of the calling stack, with variable  Quick, source-guided navigation of the calling stack, with variable
271  inspection, etc.  inspection, etc.
# Line 261  stopped at a breakpoint} Line 294  stopped at a breakpoint}
294  @end itemize  @end itemize
295  @end ifnottex  @end ifnottex
296    
297  IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el}  IDLWAVE is the distant successor to the @file{idl.el} and
298  files written by Chris Chase.  The modes and files had to be renamed  @file{idl-shell.el} files written by Chris Chase.  The modes and files
299  because of a name space conflict with CORBA's @code{idl-mode}, defined in  had to be renamed because of a name space conflict with CORBA's
300  Emacs in the file @file{cc-mode.el}.  If you have been using the old  @code{idl-mode}, defined in Emacs in the file @file{cc-mode.el}.
 files, check @ref{Upgrading from idl.el} for information on how to  
 switch.  
301    
302  In this manual, each section ends with a list of related user options.  In this manual, each section ends with a list of related user options.
303  Don't be confused by the sheer number of options available --- in most  Don't be confused by the sheer number of options available --- in most
# Line 307  at point. Line 338  at point.
338  @tab Update IDLWAVE's knowledge about functions and procedures.  @tab Update IDLWAVE's knowledge about functions and procedures.
339  @item @kbd{C-c C-v}  @item @kbd{C-c C-v}
340  @tab Visit the source code of a procedure/function.  @tab Visit the source code of a procedure/function.
341    @item @kbd{C-u C-c C-v}
342    @tab Visit the source code of a procedure/function in this buffer.
343  @item @kbd{C-c C-h}  @item @kbd{C-c C-h}
344  @tab Insert a standard documentation header.  @tab Insert a standard documentation header.
345  @item @kbd{C-c @key{RET}}  @item @kbd{C-c @key{RET}}
# Line 322  at point. Line 355  at point.
355  @tab Cycle back through IDL command history.  @tab Cycle back through IDL command history.
356  @item @kbd{M-n}  @item @kbd{M-n}
357  @tab Cycle forward.  @tab Cycle forward.
358  @item @kbd{M-@key{TAB}}  @item @kbd{@key{TAB}}
359  @tab Complete a procedure name, function name or keyword in the shell buffer.  @tab Complete a procedure name, function name or keyword in the shell buffer.
360  @item @kbd{C-c C-d C-c}  @item @kbd{C-c C-d C-c}
361  @tab Save and compile the source file in the current buffer.  @tab Save and compile the source file in the current buffer.
362  @item @kbd{C-c C-d C-x}  @item @kbd{C-c C-d C-x}
363  @tab Goto next syntax error.  @tab Go to next syntax error.
364    @item @kbd{C-c C-d C-v}
365    @tab Switch to electric debug mode.
366  @item @kbd{C-c C-d C-b}  @item @kbd{C-c C-d C-b}
367  @tab Set a breakpoint at the nearest viable source line.  @tab Set a breakpoint at the nearest viable source line.
368  @item @kbd{C-c C-d C-d}  @item @kbd{C-c C-d C-d}
369  @tab Clear the nearest breakpoint.  @tab Clear the nearest breakpoint.
370    @item @kbd{C-c C-d [}
371    @tab Go to the previous breakpoint.
372    @item @kbd{C-c C-d ]}
373    @tab Go to the next breakpoint.
374  @item @kbd{C-c C-d C-p}  @item @kbd{C-c C-d C-p}
375  @tab Print the value of the expression near point in IDL.  @tab Print the value of the expression near point in IDL.
376  @end multitable  @end multitable
# Line 353  at point. Line 392  at point.
392  (setq idlwave-shell-automatic-start t)  (setq idlwave-shell-automatic-start t)
393  ;; Bind debugging commands with CONTROL and SHIFT modifiers  ;; Bind debugging commands with CONTROL and SHIFT modifiers
394  (setq idlwave-shell-debug-modifiers '(control shift))  (setq idlwave-shell-debug-modifiers '(control shift))
 ;; Specify the online help files' location.  
 (setq idlwave-help-directory "~/.idlwave")  
395  @end lisp  @end lisp
396    
397  @ifhtml  @ifhtml
# Line 367  at point. Line 404  at point.
404  @cindex Getting Started  @cindex Getting Started
405    
406  @menu  @menu
407  * Lesson I -- Development Cycle::  * Lesson I -- Development Cycle::  
408  * Lesson II -- Customization::  * Lesson II -- Customization::  
409  * Lesson III -- Library Catalog::  * Lesson III -- User Catalog::  
410  @end menu  @end menu
411    
412  @node  Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started  @node  Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started
413  @section Lesson I: Development Cycle  @section Lesson I: Development Cycle
414    
415  The purpose of this tutorial is to guide you through a very basic  The purpose of this tutorial is to guide you through a very basic
416  development cycle using IDLWAVE.  We will paste a simple program into a  development cycle using IDLWAVE.  We will paste a simple program into
417  buffer and use the shell to compile, debug and run it.  On the way we  a buffer and use the shell to compile, debug and run it.  On the way
418  will use many of the important IDLWAVE commands.  Note however that  we will use many of the important IDLWAVE commands.  Note, however,
419  there are many more capabilities in IDLWAVE than covered here, which can  that IDLWAVE has many more capabilities than covered here, which can
420  be discovered by reading the entire manual.  be discovered by reading the entire manual, or hovering over the
421    shoulder of your nearest IDLWAVE guru for a few days.
422    
423  It is assumed that you have access to Emacs or XEmacs with the full  It is assumed that you have access to Emacs or XEmacs with the full
424  IDLWAVE package including online help (@pxref{Installation}).  We also  IDLWAVE package including online help (@pxref{Installation}).  We also
# Line 395  Open a new source file by typing: Line 433  Open a new source file by typing:
433  @kbd{C-x C-f tutorial.pro @key{RET}}  @kbd{C-x C-f tutorial.pro @key{RET}}
434  @end example  @end example
435    
436  A buffer for this file will pop up, and it should be in IDLWAVE mode, as  A buffer for this file will pop up, and it should be in IDLWAVE mode,
437  shown in the mode line just below the editing window.  Also, the menu  indicated in the mode line just below the editing window.  Also, the
438  bar should contain entries @samp{IDLWAVE} and @samp{Debug}.  menu bar should contain @samp{IDLWAVE}.
439    
440  Now cut-and-paste the following code, also available as  Now cut-and-paste the following code, also available as
441  @file{tutorial.pro} in the IDLWAVE distribution.  @file{tutorial.pro} in the IDLWAVE distribution.
# Line 412  function daynr,d,m,y Line 450  function daynr,d,m,y
450    y1 = y * delta    y1 = y * delta
451    return, d + floor(m1*30.6)+floor(y1*365.25)+5    return, d + floor(m1*30.6)+floor(y1*365.25)+5
452  end  end
453        
454  function weekday,day,month,year  function weekday,day,month,year
455    ;; compute weekday number for date    ;; compute weekday number for date
456    nr = daynr(day,month,year)    nr = daynr(day,month,year)
457    return, nr mod 7    return, nr mod 7
458  end  end
459        
460  pro plot_wday,day,month  pro plot_wday,day,month
461    ;; Plot the weekday of a date in the first 10 years of this century.    ;; Plot the weekday of a date in the first 10 years of this century.
462    years = 2000,+indgen(10)    years = 2000,+indgen(10)
# Line 431  end Line 469  end
469  @end example  @end example
470    
471  The indentation probably looks funny, since it's different from the  The indentation probably looks funny, since it's different from the
472  settings you use, so use the @key{TAB} key in each line to automatically  settings you use, so use the @key{TAB} key in each line to
473  line it up (or more quickly @emph{select} the entire buffer with  automatically line it up (or, more quickly, @emph{select} the entire
474  @kbd{C-x h}, and indent the whole region with @kbd{C-M-\}).  Notice how  buffer with @kbd{C-x h}, and indent the whole region with
475  different syntactical elements are highlighted in different colors, if  @kbd{C-M-\}).  Notice how different syntactical elements are
476  you have set up support for font-lock.  highlighted in different colors, if you have set up support for
477    font-lock.
478    
479  Let's check out two particular editing features of IDLWAVE.  Place the  Let's check out two particular editing features of IDLWAVE.  Place the
480  cursor after the @code{end} statement of the @code{for} loop and press  cursor after the @code{end} statement of the @code{for} loop and press
481  @key{SPC}.  IDLWAVE blinks back to the beginning of the block and  @key{SPC}.  IDLWAVE blinks back to the beginning of the block and
482  changes the generic @code{end} to the specific @code{endfor}  changes the generic @code{end} to the specific @code{endfor}
483  automatically.  Now place the cursor in any line you would like to split  automatically (as long as the variable @code{idlwave-expand-generic-end}
484  and press @kbd{M-@key{RET}}.  The line is split at the cursor position,  is turned on --- @pxref{Lesson II -- Customization}).  Now place the
485  with the continuation @samp{$} and indentation all taken care of.  Use  cursor in any line you would like to split and press @kbd{M-@key{RET}}.
486  @kbd{C-/} to undo the last change.  The line is split at the cursor position, with the continuation @samp{$}
487    and indentation all taken care of.  Use @kbd{C-/} to undo the last
488  The procedure @code{plot_wday} is supposed to plot the weekday of a  change.
489  given date for the first 10 years of the 21st century.  As in most code,  
490  there are a few bugs, which we are going to use IDLWAVE to help us fix.  The procedure @code{plot_wday} is supposed to plot the day of the week
491    of a given date for the first 10 years of the 21st century.  As in
492    most code, there are a few bugs, which we are going to use IDLWAVE to
493    help us fix.
494    
495  First, let's launch the IDLWAVE shell.  You do this with the command  First, let's launch the IDLWAVE shell.  You do this with the command
496  @kbd{C-c C-s}.  The Emacs window will split and display IDL running in a  @kbd{C-c C-s}.  The Emacs window will split or another window will popup
497  shell interaction buffer.  Type a few commands like @code{print,!PI} to  to display IDL running in a shell interaction buffer.  Type a few
498  convince yourself that you can work there just as well as in a terminal,  commands like @code{print,!PI} to convince yourself that you can work
499  or the IDLDE.  Use the arrow keys to cycle through your command history.  there just as well as in a terminal, or the IDLDE.  Use the arrow keys
500  Are we having fun now?  to cycle through your command history.  Are we having fun now?
501    
502  Now go back to the source window and type @kbd{C-c C-d C-c} to compile  Now go back to the source window and type @kbd{C-c C-d C-c} to compile
503  the program.  If you watch the shell buffer, you see that IDLWAVE types  the program.  If you watch the shell buffer, you see that IDLWAVE types
# Line 469  see the three routines compile. Line 511  see the three routines compile.
511    
512  Now we want to use the command to plot the day of the week on January  Now we want to use the command to plot the day of the week on January
513  1st.  We could type the full command ourselves, but why do that?  Go  1st.  We could type the full command ourselves, but why do that?  Go
514  back to the shell window, type @samp{plot_} and hit @key{TAB}.  After a  back to the shell window, type @samp{plot_} and hit @key{TAB}.  After
515  bit of a delay (while IDLWAVE initializes its routine info database, if  a bit of a delay (while IDLWAVE initializes its routine info database,
516  necessary), the window will split to show all procedures it knows  if necessary), the window will split to show all procedures it knows
517  starting with that string, and @w{@code{plot_wday}} should be one of  starting with that string, and @w{@code{plot_wday}} should be one of
518  them.  Saving the buffer alerted IDLWAVE about this new routine.  Click  them.  Saving the buffer alerted IDLWAVE about this new routine.
519  with the middle mouse button on @code{plot_wday} and it will be copied  Click with the middle mouse button on @code{plot_wday} and it will be
520  to the shell buffer, or if you prefer, add @samp{w} to @samp{plot_} to  copied to the shell buffer, or if you prefer, add @samp{w} to
521  make it unambiguous, hit @key{TAB} again, and the full routine name will  @samp{plot_} to make it unambiguous (depending on what other routines
522  be completed.  Now provide the two arguments:  starting with @samp{plot_} you have installed on your system), hit
523    @key{TAB} again, and the full routine name will be completed.  Now
524    provide the two arguments:
525    
526  @example  @example
527  plot_wday,1,1  plot_wday,1,1
528  @end example  @end example
529    
530  and press @key{RET}.  This fails with an error message telling you the  @noindent and press @key{RET}.  This fails with an error message telling
531  @code{YT} keyword to plot is ambiguous.  What are the allowed keywords  you the @code{YT} keyword to plot is ambiguous.  What are the allowed
532  again?  Go back to the source window and put the cursor into the `plot'  keywords again?  Go back to the source window and put the cursor into
533  line, and press @kbd{C-c ?}.  This shows the routine info window for the  the `plot' line and press @kbd{C-c ?}.  This shows the routine info
534  plot routine, which contains a list of keywords, along with the argument  window for the plot routine, which contains a list of keywords, along
535  list.  Oh, we wanted @code{YTITLE}.  Fix that up.  Recompile with  with the argument list.  Oh, we wanted @code{YTITLE}.  Fix that up.
536  @kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press  Recompile with @kbd{C-c C-d C-c}. Jump back into the shell with
537  the @key{UP} arrow to recall the previous command and execute again.  @kbd{C-c C-s}, press the @key{UP} arrow to recall the previous command
538    and execute again.
539    
540  This time we get a plot, but it is pretty ugly --- the points are all  This time we get a plot, but it is pretty ugly --- the points are all
541  connected with a line.  Hmm, isn't there a way for @code{plot} to use  connected with a line.  Hmm, isn't there a way for @code{plot} to use
542  symbols instead?  What was that keyword?  Position the cursor on the  symbols instead?  What was that keyword?  Position the cursor on the
543  plot line after a comma (where you'd normally type a keyword), and hit  plot line after a comma (where you'd normally type a keyword), and hit
544  @kbd{M-@key{Tab}}.  A long list of plot's keywords appears.  Aha, there  @kbd{M-@key{Tab}}.  A long list of plot's keywords appears.  Aha,
545  it is, @code{PSYM}.  Middle click to insert it.  An @samp{=} sign is  there it is, @code{PSYM}.  Middle click to insert it.  An @samp{=}
546  included for you too.  Now what were the values of @code{PSYM} supposed  sign is included for you too.  Now what were the values of @code{PSYM}
547  to be?  With the cursor on or after the keyword, press @kbd{M-?} for  supposed to be?  With the cursor on or after the keyword, press
548  online help (alternatively, you could have right clicked on the colored  @kbd{M-?} for online help (alternatively, you could have right clicked
549  keyword itself in the completion list).  The online help window will pop  on the colored keyword itself in the completion list).  A browser will
550  up showing the documentation for the @code{PYSM} keyword.  OK, let's use  pop up showing the HTML documentation for the @code{PYSM} keyword.
551  diamonds=4.  Fix this, recompile (you know the command by now: @kbd{C-c  OK, let's use diamonds=4.  Fix this, recompile (you know the command
552  C-d C-c}, go back to the shell (if it's vanished, you know the command  by now: @kbd{C-c C-d C-c}), go back to the shell (if it's vanished,
553  to recall it by now: @kbd{C-c C-s}) and execute again.  Now things look  you know what to do: @kbd{C-c C-s}) and execute again.  Now things
554  pretty good.  look pretty good.
555    
556  Let's try a different day --- how about April fool's day?  Let's try a different day --- how about April fool's day?
557    
# Line 518  Oops, this looks very wrong.  All April Line 563  Oops, this looks very wrong.  All April
563  We've got a bug in the program, perhaps in the @code{daynr} function.  We've got a bug in the program, perhaps in the @code{daynr} function.
564  Let's put a breakpoint on the last line there.  Position the cursor on  Let's put a breakpoint on the last line there.  Position the cursor on
565  the @samp{return, d+...} line and press @kbd{C-c C-d C-b}.  IDL sets a  the @samp{return, d+...} line and press @kbd{C-c C-d C-b}.  IDL sets a
566  breakpoint (as you see in the shell window), and the line is highlighted  breakpoint (as you see in the shell window), and the break line is
567  in some way.  Back to the shell buffer, re-execute the previous command.  indicated.  Back to the shell buffer, re-execute the previous command.
568  IDL stops at the line with the breakpoint.  Now hold down the SHIFT key  IDL stops at the line with the breakpoint.  Now hold down the SHIFT
569  and click with the middle mouse button on a few variables there:  key and click with the middle mouse button on a few variables there:
570  @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc.  Maybe @code{d} isn't the  @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc.  Maybe @code{d} isn't
571  correct type.  CONTROL-SHIFT middle-click on it for help.  Well, it's an  the correct type.  CONTROL-SHIFT middle-click on it for help.  Well,
572  integer, so that's not the problem.  Aha, @samp{y1} is zero, but it  it's an integer, so that's not the problem.  Aha, @samp{y1} is zero,
573  should be the year, depending on delta.  Shift click @samp{delta} to see  but it should be the year, depending on delta.  Shift click
574  that it's 0.  Below, we see the offending line: @samp{y1=y*delta...} the  @samp{delta} to see that it's 0.  Below, we see the offending line:
575  multiplication should have been a minus sign!  So fix the line to read:  @samp{y1=y*delta...} the multiplication should have been a minus sign!
576    Hit @kbd{q} to exit the debugging mode, and fix the line to read:
577    
578  @example  @example
579  y1 = y - delta  y1 = y - delta
# Line 538  command.  Everything should now work fin Line 584  command.  Everything should now work fin
584  Change the code to plot 100 years and see that every 28 years, the  Change the code to plot 100 years and see that every 28 years, the
585  sequence of weekdays repeats.  sequence of weekdays repeats.
586    
587  @node  Lesson II -- Customization, Lesson III -- Library Catalog, Lesson I -- Development Cycle, Getting Started  @node  Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started
588  @section Lesson II: Customization  @section Lesson II: Customization
589    
590  Emacs is probably the most customizable piece of software available, and  Emacs is probably the most customizable piece of software ever
591  it would be a shame if you did not make use of this and adapt IDLWAVE to  written, and it would be a shame if you did not make use of this and
592  your own preferences.  Customizing Emacs or IDLWAVE is accomplished by  adapt IDLWAVE to your own preferences.  Customizing Emacs or IDLWAVE
593  setting Lisp variables in the @file{.emacs} file in your home directory  is accomplished by setting Lisp variables in the @file{.emacs} file in
594  --- but do not be dismayed; for the most part, you can just copy and work  your home directory --- but do not be dismayed; for the most part, you
595  from the examples given here.  can just copy and work from the examples given here.
596    
597  Let's first use a boolean variable.  These are variables which you turn  Let's first use a boolean variable.  These are variables which you turn
598  on or off, much like a checkbox. A value of @samp{t} means on, a value  on or off, much like a checkbox. A value of @samp{t} means on, a value
# Line 561  When this option is turned on, each rese Line 607  When this option is turned on, each rese
607  source buffer will be converted to upper case when you press @key{SPC}  source buffer will be converted to upper case when you press @key{SPC}
608  or @key{RET} right after the word.  Try it out!  @samp{if} changes to  or @key{RET} right after the word.  Try it out!  @samp{if} changes to
609  @samp{IF}, @samp{begin} to @samp{BEGIN}.  If you don't like this  @samp{IF}, @samp{begin} to @samp{BEGIN}.  If you don't like this
610  behavior, remove the option again from your @file{.emacs} file.  behavior, remove the option again from your @file{.emacs} file and
611    restart Emacs.
612    
613  You likely have your own indentation preferences for IDL code.  For  You likely have your own indentation preferences for IDL code.  For
614  example, some like to indent the main block of an IDL program from the  example, some like to indent the main block of an IDL program from the
# Line 588  there is another, more user-friendly way Line 635  there is another, more user-friendly way
635  variables.  You can access it through the IDLWAVE menu in one of the  variables.  You can access it through the IDLWAVE menu in one of the
636  @file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE  @file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE
637  Group}. Here you'll be presented with all the various variables grouped  Group}. Here you'll be presented with all the various variables grouped
638  into categories.  You can navigate the hierarchy (e.g. Idlwave Code  into categories.  You can navigate the hierarchy (e.g. @samp{IDLWAVE
639  Formatting->Idlwave Main Block Indent), read about the variables, change  Code Formatting->Idlwave Abbrev And Indent Action->Idlwave Expand
640  them, and `Save for Future Sessions'.  Few of these variables need  Generic End} to turn on @code{END} expansion), read about the variables,
641  customization, but you can exercise considerable control over IDLWAVE's  change them, and `Save for Future Sessions'.  Few of these variables
642  functionality with them.  need customization, but you can exercise considerable control over
643    IDLWAVE's functionality with them.
644    
645  You may also find the key bindings used for the debugging commands too  You may also find the key bindings used for the debugging commands too
646  long and complicated.  Often we have heard such complaints, ``Do I  long and complicated.  Often we have heard complaints along the lines
647  really have to type @kbd{C-c C-d C-c} to run a simple command?''  Due to  of, ``Do I really have to go through the finger gymnastics of @kbd{C-c
648  Emacs rules and conventions, shorter bindings cannot be set by default,  C-d C-c} to run a simple command?''  Due to Emacs rules and
649  but you can enable them.  First, there is a way to assign all debugging  conventions, shorter bindings cannot be set by default, but you can
650  commands in a single sweep to other combinations.  The only problem is  easily enable them.  First, there is a way to assign all debugging
651  that we have to use something which Emacs does not need for other  commands in a single sweep to another simpler combination.  The only
652  important commands.  One good option is to execute debugging commands by  problem is that we have to use something which Emacs does not need for
653  holding down @key{CONTROL} and @key{SHIFT} while pressing a single  other important commands.  One good option is to execute debugging
654  character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for  commands by holding down @key{CONTROL} and @key{SHIFT} while pressing
655  compiling the current source file, @kbd{C-S-a} for deleting all  a single character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c}
656  breakpoints.  You can enable this with:  for compiling the current source file, @kbd{C-S-a} for deleting all
657    breakpoints (try it, it's easier).  You can enable this with:
658    
659  @lisp  @lisp
660  (setq idlwave-shell-debug-modifiers '(shift control))  (setq idlwave-shell-debug-modifiers '(shift control))
661  @end lisp  @end lisp
662    
663  @noindent If you have a special keyboard with, for example, a  @noindent If you have a special keyboard with, for example, a
664  @key{HYPER} key, you could even shorten that:  @key{SUPER} key, you could even shorten that:
665    
666  @lisp  @lisp
667  (setq idlwave-shell-debug-modifiers '(hyper))  (setq idlwave-shell-debug-modifiers '(super))
668  @end lisp  @end lisp
669    
670  @noindent to get compilation on @kbd{H-c}.  Often, a modifier key like  @noindent to get compilation on @kbd{S-c}.  Often, a modifier key like
671  @key{HYPER} or @key{SUPER} is bound or can be bound to an otherwise  @key{SUPER} or @key{HYPER} is bound or can be bound to an otherwise
672  unused key -- consult your system documentation.  unused key on your keyboard --- consult your system documentation.
673    
674  You can also assign specific commands to keys.  This you must do in the  You can also assign specific commands to keys.  This you must do in the
675  @emph{mode-hook}, a special function which is run when a new buffer gets  @emph{mode-hook}, a special function which is run when a new IDLWAVE
676  set up.  Keybindings can only be done when the buffer exists.  The  buffer gets set up.  The possibilities for key customization are
677  possibilities for key customization are endless.  Here we set function  endless.  Here we set function keys f4-f8 to common debugging commands.
 keys f5-f8 to common debugging commands.  
678    
679  @lisp  @lisp
680  ;; First for the source buffer  ;; First for the source buffer
681  (add-hook 'idlwave-mode-hook  (add-hook 'idlwave-mode-hook
682     (lambda ()     (lambda ()
683        (local-set-key [f4] 'idlwave-shell-retall)
684      (local-set-key [f5] 'idlwave-shell-break-here)      (local-set-key [f5] 'idlwave-shell-break-here)
685      (local-set-key [f6] 'idlwave-shell-clear-current-bp)      (local-set-key [f6] 'idlwave-shell-clear-current-bp)
686      (local-set-key [f7] 'idlwave-shell-cont)      (local-set-key [f7] 'idlwave-shell-cont)
# Line 639  keys f5-f8 to common debugging commands. Line 688  keys f5-f8 to common debugging commands.
688  ;; Then for the shell buffer  ;; Then for the shell buffer
689  (add-hook 'idlwave-shell-mode-hook  (add-hook 'idlwave-shell-mode-hook
690     (lambda ()     (lambda ()
691        (local-set-key [f4] 'idlwave-shell-retall)
692      (local-set-key [f5] 'idlwave-shell-break-here)      (local-set-key [f5] 'idlwave-shell-break-here)
693      (local-set-key [f6] 'idlwave-shell-clear-current-bp)      (local-set-key [f6] 'idlwave-shell-clear-current-bp)
694      (local-set-key [f7] 'idlwave-shell-cont)      (local-set-key [f7] 'idlwave-shell-cont)
695      (local-set-key [f8] 'idlwave-shell-clear-all-bp)))      (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
696  @end lisp  @end lisp
697    
698  @node  Lesson III -- Library Catalog,  , Lesson II -- Customization, Getting Started  @node  Lesson III -- User Catalog,  , Lesson II -- Customization, Getting Started
699  @section Lesson III: Library Catalog  @section Lesson III: User and Library Catalogs
700    
701  We have already used the routine info display in the first part of this  We have already used the routine info display in the first part of this
702  tutorial.  This was the key @kbd{C-c ?} which displays information about  tutorial.  This was the invoked using @kbd{C-c ?}, and displays
703  the IDL routine near the cursor position.  Wouldn't it be nice  information about the IDL routine near the cursor position.  Wouldn't it
704  to have the same available for your own library routines and for the  be nice to have the same kind of information available for your own
705  huge amount of code in major extension libraries like JHUPL or the  routines and for the huge amount of code in major libraries like JHUPL
706  IDL-Astro library?  To do this, you must give IDLWAVE a chance to study  or the IDL-Astro library?  In many cases, you may already have this
707  these routines first.  We call this @emph{Building the library catalog}.  information.  Files named @file{.idlwave_catalog} in library directories
708    contain scanned information on the routines in that directory; many
709  From the IDLWAVE entry in the menu bar, select @code{Routine Info/Select  popular libraries ship with these ``library catalogs'' pre-scanned.
710  Catalog Directories}.  If necessary, start the shell first with @kbd{C-c  Users can scan their own routines in one of two ways: either using the
711  C-s} (@pxref{Starting the Shell}).  IDLWAVE will find out about the IDL  supplied tool to scan directories and build their own
712  @code{!PATH} variable and offer a list of directories on the path.  @file{.idlwave_catalog} files, or using the built-in method to create a
713  Simply select them all (or whichever you want) and click on the  single ``user catalog'', which we'll show here.  @xref{Catalogs}, for
714  @samp{Scan&Save} button.  Then go for a cup of coffee while IDLWAVE  more information on choosing which method to use.
715  collects information for each and every IDL routine on your search path.  
716  All this information is written to the file @file{.idlcat} in your home  To build a user catalog, select @code{Routine Info/Select Catalog
717  directory and will from now one be automatically loaded whenever you use  Directories} from the IDLWAVE entry in the menu bar.  If necessary,
718    start the shell first with @kbd{C-c C-s} (@pxref{Starting the Shell}).
719    IDLWAVE will find out about the IDL @code{!PATH} variable and offer a
720    list of directories on the path.  Simply select them all (or whichever
721    you want --- directories with existing library catalogs will not be
722    selected by default) and click on the @samp{Scan&Save} button.  Then
723    go for a cup of coffee while IDLWAVE collects information for each and
724    every IDL routine on your search path.  All this information is
725    written to the file @file{.idlwave/idlusercat.el} in your home
726    directory and will from now on automatically load whenever you use
727  IDLWAVE.  You may find it necessary to rebuild the catalog on occasion  IDLWAVE.  You may find it necessary to rebuild the catalog on occasion
728  as your local libraries change.  Try to use routine info (@kbd{C-c ?})  as your local libraries change, or build a library catalog for those
729  or completion (@kbd{M-@key{TAB}}) while on any routine or partial routine  directories instead.  Invoke routine info (@kbd{C-c ?}) or completion
730  name you know to be located in the library.  E.g., if you have scanned  (@kbd{M-@key{TAB}}) on any routine or partial routine name you know to
731  the IDL-Astro library:  be located in the library.  E.g., if you have scanned the IDL-Astro
732    library:
733    
734  @example  @example
735      a=readf@key{M-<TAB>}      a=readf@key{M-@key{TAB}}
736  @end example  @end example
737    
   
738  expands to `readfits('.  Then try  expands to `readfits('.  Then try
739    
740  @example  @example
# Line 690  Usage:    Result = READFITS(filename, he Line 749  Usage:    Result = READFITS(filename, he
749  @end example  @end example
750    
751  I hope you made it until here.  Now you are set to work with IDLWAVE.  I hope you made it until here.  Now you are set to work with IDLWAVE.
752  On the way you will want to change other things, and to learn more about  On the way you will want to change other things, and to learn more
753  the possibilities not discussed in this short tutorial.  Read the  about the possibilities not discussed in this short tutorial.  Read
754  manual, look at the documentation strings of interesting variables (with  the manual, look at the documentation strings of interesting variables
755  @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining  (with @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the
756  questions on the newsgroup @code{comp.lang.idl-pvwave}.  remaining questions on the newsgroup @code{comp.lang.idl-pvwave}.
757    
758  @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top  @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top
759  @chapter The IDLWAVE Major Mode  @chapter The IDLWAVE Major Mode
# Line 727  them. Line 786  them.
786    
787  @menu  @menu
788  * Code Indentation::            Reflecting the logical structure  * Code Indentation::            Reflecting the logical structure
789  * Continued Statement Indentation::  * Continued Statement Indentation::  
790  * Comment Indentation::         Special indentation for comment lines  * Comment Indentation::         Special indentation for comment lines
791  * Continuation Lines::          Splitting statements over lines  * Continuation Lines::          Splitting statements over lines
792  * Syntax Highlighting::         Font-lock support  * Syntax Highlighting::         Font-lock support
793  * Octals and Highlighting::     Why "123 causes problems  * Octals and Highlighting::     Why "123 causes problems
794  @end menu  @end menu
795    
796  The IDL language, with it's early roots in FORTRAN, modern  The IDL language, with its early roots in FORTRAN, modern
797  implementation in C, and liberal borrowing of features of many vector  implementation in C, and liberal borrowing of features of many vector
798  languages along its 25+ year history, has inherited an unusual mix of  and other languages along its 25+ year history, has inherited an
799  syntax elements.  Left to his or her own devices, a novice IDL  unusual mix of syntax elements.  Left to his or her own devices, a
800  programmer will often conjure code which is very difficult to read and  novice IDL programmer will often conjure code which is very difficult
801  impossible to adapt.  Much can be gleaned from studying available IDL  to read and impossible to adapt.  Much can be gleaned from studying
802  code libraries for coding style pointers, but, due to the variety of  available IDL code libraries for coding style pointers, but, due to
803  IDL syntax elements, replicating this style can be challenging at  the variety of IDL syntax elements, replicating this style can be
804  best.  Luckily, IDLWAVE understands the structure of IDL code very  challenging at best.  Luckily, IDLWAVE understands the structure of
805  well, and takes care of almost all formatting issues for you.  After  IDL code very well, and takes care of almost all formatting issues for
806  configuring it to match your coding standards, you can rely on it to  you.  After configuring it to match your coding standards, you can
807  help keep your code neat and organized.  rely on it to help keep your code neat and organized.
808    
 @cindex Foreign code, adapting  
 @cindex Indentation, of foreign code  
 @kindex C-M-\  
 To re-indent a larger portion of code (e.g. when working with foreign code  
 written with different conventions), use @kbd{C-M-\}  
 (@code{indent-region}) after marking the relevant code.  Useful marking  
 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the  
 current subprogram). @xref{Actions}, for information how to impose  
 additional formatting conventions on foreign code.  
809    
810  @node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting  @node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting
811  @subsection Code Indentation  @subsection Code Indentation
# Line 769  governed by a number of variables.  IDLW Line 819  governed by a number of variables.  IDLW
819  @code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and  @code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and
820  continuation lines.  continuation lines.
821    
822  @defopt idlwave-main-block-indent (@code{0})  @cindex Foreign code, adapting
823    @cindex Indentation, of foreign code
824    @kindex C-M-\
825    To re-indent a larger portion of code (e.g. when working with foreign code
826    written with different conventions), use @kbd{C-M-\}
827    (@code{indent-region}) after marking the relevant code.  Useful marking
828    commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the
829    current subprogram). @xref{Actions}, for information how to impose
830    additional formatting conventions on foreign code.
831    
832    @defopt idlwave-main-block-indent (@code{0})
833  Extra indentation for the main block of code.  That is the block between  Extra indentation for the main block of code.  That is the block between
834  the FUNCTION/PRO statement and the END statement for that program  the FUNCTION/PRO statement and the END statement for that program
835  unit.  unit.
# Line 827  indentation by setting the variable Line 887  indentation by setting the variable
887  maximum additional indentation beyond the basic indent to be  maximum additional indentation beyond the basic indent to be
888  tolerated, otherwise defaulting to a fixed-offset from the enclosing  tolerated, otherwise defaulting to a fixed-offset from the enclosing
889  indent (the size of which offset is set in  indent (the size of which offset is set in
890  @code{idlwave-continuation-indent}).  Also, since the indentation  @code{idlwave-continuation-indent}).  As a special case, continuations
891  level can be somewhat dynamic in continued statements with special  of routine calls without any arguments or keywords will @emph{not}
892  continuation indentation, especially if  align the continued line, under the assumption that you continued
893    because you needed the space.
894    
895    Also, since the indentation level can be somewhat dynamic in continued
896    statements with special continuation indentation, especially if
897  @code{idlwave-max-extra-continuation-indent} is small, the key  @code{idlwave-max-extra-continuation-indent} is small, the key
898  @kbd{C-u @key{TAB}} will re-indent all lines in the current statement.  @kbd{C-u @key{TAB}} will re-indent all lines in the current statement.
899  Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil}, overrides  Note that @code{idlwave-indent-to-open-paren}, if non-nil, overrides
900  the @code{idlwave-max-extra-continuation-indent} limit, for  the @code{idlwave-max-extra-continuation-indent} limit, for
901  parentheses only, forcing them always to line up.  parentheses only, forcing them always to line up.
902    
# Line 966  in the first line of a comment paragraph Line 1030  in the first line of a comment paragraph
1030    
1031  @defopt idlwave-use-last-hang-indent (@code{nil})  @defopt idlwave-use-last-hang-indent (@code{nil})
1032  Non-@code{nil} means use last match on line for  Non-@code{nil} means use last match on line for
1033  @code{idlwave-indent-regexp}.  @code{idlwave-indent-regexp}.
1034  @end defopt  @end defopt
1035    
1036  @node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting  @node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting
# Line 994  for highlighting using the variable Line 1058  for highlighting using the variable
1058    
1059  @defopt idlwave-default-font-lock-items  @defopt idlwave-default-font-lock-items
1060  Items which should be fontified on the default fontification level  Items which should be fontified on the default fontification level
1061  2.  2.
1062  @end defopt  @end defopt
1063    
1064  @node Octals and Highlighting,  , Syntax Highlighting, Code Formatting  @node Octals and Highlighting,  , Syntax Highlighting, Code Formatting
# Line 1002  Items which should be fontified on the d Line 1066  Items which should be fontified on the d
1066  @cindex Syntax highlighting, Octals  @cindex Syntax highlighting, Octals
1067  @cindex Highlighting of syntax, Octals  @cindex Highlighting of syntax, Octals
1068    
1069  A rare syntax highlighting problem results from the extremely  A rare syntax highlighting problem results from an extremely unfortunate
1070  unfortunate notation for octal numbers in IDL: @code{"123}.  This  notation for octal numbers in IDL: @code{"123}.  This unpaired quotation
1071  unpaired quotation mark is very difficult to parse, given that it can be  mark is very difficult to parse, given that it can be mixed on a single
1072  mixed on a single line with any number of strings.  Emacs will  line with any number of strings.  Emacs will incorrectly identify this
1073  incorrectly identify this as a string, and the highlighting of following  as a string, and the highlighting of following lines of code can be
1074  lines of code can be distorted, since the string is never terminated.  distorted, since the string is never terminated.
1075    
1076  One solution to this involves terminating the mistakenly identified  One solution to this involves terminating the mistakenly identified
1077  string yourself by providing a closing quotation mark in a comment:  string yourself by providing a closing quotation mark in a comment:
# Line 1041  and object methods, and large libraries Line 1105  and object methods, and large libraries
1105  even thousands more (each with a few to tens of keywords and  even thousands more (each with a few to tens of keywords and
1106  arguments).  This large command set can make it difficult to remember  arguments).  This large command set can make it difficult to remember
1107  the calling sequence and keywords for the routines you use, but  the calling sequence and keywords for the routines you use, but
1108  IDLWAVE can help.  It builds up routine information using a wide  IDLWAVE can help.  It builds up routine information from a wide
1109  variety of sources: IDLWAVE in fact knows far more about the routines  variety of sources; IDLWAVE in fact knows far more about the
1110  on your system than IDL itself.  It maintains a list of all built-in  @samp{.pro} routines on your system than IDL itself!  It maintains a
1111  routines, with calling sequences and keywords@footnote{This list is  list of all built-in routines, with calling sequences and
1112  created by scanning the IDL manuals and might contain (very few)  keywords@footnote{This list is created by scanning the IDL manuals and
1113  errors.  Please report any errors to the maintainer, so that they can  might contain (very few) errors.  Please report any errors to the
1114  be fixed.}.  It also scans Emacs buffers and library files for routine  maintainer, so that they can be fixed.}.  It also scans Emacs buffers
1115  definitions, and queries the IDLWAVE-Shell for information about  for routine definitions, queries the IDLWAVE-Shell for information
1116  routines currently compiled there.  This information is updated  about routines currently compiled there, and automatically locates
1117    library and user-created catalogs.  This information is updated
1118  automatically, and so should usually be current.  To force a global  automatically, and so should usually be current.  To force a global
1119  update and refresh the routine information, use @kbd{C-c C-i}  update and refresh the routine information, use @kbd{C-c C-i}
1120  (@code{idlwave-update-routine-info}).  (@code{idlwave-update-routine-info}).
# Line 1071  plot,x,alog(x+5*sin(x) + 2), Line 1136  plot,x,alog(x+5*sin(x) + 2),
1136  On positions 1,2 and 8, information about the @samp{plot} procedure will  On positions 1,2 and 8, information about the @samp{plot} procedure will
1137  be shown.  On positions 3,4, and 7, the @samp{alog} function will be  be shown.  On positions 3,4, and 7, the @samp{alog} function will be
1138  described, while positions 5 and 6 will investigate the @samp{sin}  described, while positions 5 and 6 will investigate the @samp{sin}
1139  function.  function.  
1140    
1141  When you ask for routine information about an object method, and the  When you ask for routine information about an object method, and the
1142  method exists in several classes, IDLWAVE queries for the class of the  method exists in several classes, IDLWAVE queries for the class of the
1143  object, unless the class is already known through a text property on the  object, unless the class is already known through a text property on the
1144  @samp{->} operator (@pxref{Object Method Completion and Class  @samp{->} operator (@pxref{Object Method Completion and Class
1145  Ambiguity}), or by having been explicitly included in the call  Ambiguity}), or by having been explicity included in the call
1146  (e.g. @code{a->myclass::Foo}).  (e.g. @code{a->myclass::Foo}).
1147    
1148  @cindex Calling sequences  @cindex Calling sequences
# Line 1090  keywords and the source location of this Line 1155  keywords and the source location of this
1155  Usage:    XMANAGER, NAME, ID  Usage:    XMANAGER, NAME, ID
1156  Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER  Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER
1157            JUST_REG MODAL NO_BLOCK            JUST_REG MODAL NO_BLOCK
1158  Source:   SystemLib   [CSB] /soft1/idl53/lib/xmanager.pro  Source:   SystemLib   [LCSB] /soft1/idl53/lib/xmanager.pro
1159  @end example  @end example
1160    
1161  @cindex Categories, of routines  @cindex Categories, of routines
# Line 1102  Source:   SystemLib   [CSB] /soft1/idl53 Line 1167  Source:   SystemLib   [CSB] /soft1/idl53
1167  @cindex @code{!DIR}, IDL variable  @cindex @code{!DIR}, IDL variable
1168    
1169  If a definition of this routine exists in several files accessible to  If a definition of this routine exists in several files accessible to
1170  IDLWAVE, several @samp{Source} lines will point to the different files.  IDLWAVE, several @samp{Source} lines will point to the different
1171  This may indicate that your routine is shadowing a library routine,  files.  This may indicate that your routine is shadowing a system
1172  which may or may not be what you want (@pxref{Load-Path Shadows}).  The  library routine, which may or may not be what you want
1173  information about the calling sequence and keywords is derived from the  (@pxref{Load-Path Shadows}).  The information about the calling
1174  first source listed.  Library routines are supported only if you have  sequence and keywords is derived from the first source listed.
1175  scanned your local IDL libraries (@pxref{Library Catalog}).  The source  Library routines are available only if you have scanned your local IDL
1176  entry consists of a @emph{source category}, a set of @emph{flags} and  directories or are using pre-scanned libraries (@pxref{Catalogs}).
1177  the path to the @emph{source file}.  The following categories exist:  The source entry consists of a @emph{source category}, a set of
1178    @emph{flags} and the path to the @emph{source file}.  The following
1179    default categories exist:
1180    
1181  @multitable @columnfractions .15 .85  @multitable @columnfractions .15 .85
1182  @item @i{System}  @item @i{System}
1183  @tab A system routine of unknown origin.  When the system library has  @tab A system routine of unknown origin.  When the system library has
1184  been scanned (@pxref{Library Catalog}), this category will automatically  been scanned as part of a catalog (@pxref{Catalogs}), this category
1185  split into the next two.  will automatically split into the next two.
1186  @item @i{Builtin}  @item @i{Builtin}
1187  @tab A builtin system routine with no source code available.  @tab A builtin system routine with no source code available.
1188  @item @i{SystemLib}  @item @i{SystemLib}
# Line 1127  split into the next two. Line 1194  split into the next two.
1194  @item @i{Other}  @item @i{Other}
1195  @tab Any other routine with a file not known to be on the search path.  @tab Any other routine with a file not known to be on the search path.
1196  @item @i{Unresolved}  @item @i{Unresolved}
1197  @tab An otherwise unkown routine the shell lists as unresolved  @tab An otherwise unkown routine the shell lists as unresolved
1198  (referenced, but not compiled).  (referenced, but not compiled).
1199  @end multitable  @end multitable
1200    
1201  You can create additional categories based on the routine's filepath  Any routines discovered in library catalogs (@pxref{Library
1202  with the variable @code{idlwave-special-lib-alist}.  This is useful for  Catalogs}), will display the category assigned during creation,
1203  easy discrimination of various libraries, or even versions of the same  e.g. @samp{NasaLib}.  For routines not discovered in this way, you can
1204  library.  create additional categories based on the routine's filename using the
1205    variable @code{idlwave-special-lib-alist}.
1206    
1207  @cindex Flags, in routine info  @cindex Flags, in routine info
1208  @cindex Duplicate routines  @cindex Duplicate routines
1209  @cindex Multiply defined routines  @cindex Multiply defined routines
1210  @cindex Routine definitions, multiple  @cindex Routine definitions, multiple
1211  The flags @code{[CSB]} indicate the source of the information IDLWAVE  The flags @code{[LCSB]} indicate the source of the information IDLWAVE
1212  has regarding the file: from a library catalog (@w{@code{[C--]}},  has regarding the file: from a library catalog (@w{@code{[L---]}}),
1213  @pxref{Library Catalog}), from the IDL Shell (@w{@code{[-S-]}}) or from  from a user catalog (@w{@code{[-C--]}}, from the IDL Shell
1214  an Emacs buffer (@w{@code{[--B]}}).  Combinations are possible (a  (@w{@code{[--S-]}}) or from an Emacs buffer (@w{@code{[---B]}}).
1215  compiled library routine visited in a buffer might read  Combinations are possible (a compiled library routine visited in a
1216  @w{@code{[CSB]}}).  If a file contains multiple definitions of the same  buffer might read @w{@code{[L-SB]}}).  If a file contains multiple
1217  routine, the file name will be prefixed with @samp{(Nx)} where @samp{N}  definitions of the same routine, the file name will be prefixed with
1218  is the number of definitions.  @samp{(Nx)} where @samp{N} is the number of definitions.
1219    
1220  @cindex Online Help from the routine info buffer  @cindex Online Help from the routine info buffer
1221  @cindex Active text, in routine info  @cindex Active text, in routine info
# Line 1162  with the middle mouse button inserts key Line 1230  with the middle mouse button inserts key
1230  @item @i{Usage}  @item @i{Usage}
1231  @tab If online help is installed, a click with the @emph{right} mouse  @tab If online help is installed, a click with the @emph{right} mouse
1232  button on the @i{Usage:} line will access the help for the  button on the @i{Usage:} line will access the help for the
1233  routine (@pxref{Online Help}).  routine (@pxref{Online Help}).  
1234  @item @i{Keyword}  @item @i{Keyword}
1235  @tab Online help about keywords is also available with the  @tab Online help about keywords is also available with the
1236  @emph{right} mouse button.  Clicking on a keyword with the @emph{middle}  @emph{right} mouse button.  Clicking on a keyword with the @emph{middle}
# Line 1198  Maximum number of source files displayed Line 1266  Maximum number of source files displayed
1266  @end defopt  @end defopt
1267    
1268    
1269    @ifhtml
1270    <A NAME="ONLINE_HELP"></A>
1271    @end ifhtml
1272  @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode  @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode
1273  @section Online Help  @section Online Help
1274    
1275  @cindex Online Help  @cindex Online Help
1276  @cindex @file{idlw-help.txt}  @cindex @file{idlw-help.txt}
1277  @cindex @file{idlw-help.el}  @cindex @file{idlw-help.el}
 @cindex IDL manual, ASCII version  
1278  @cindex Installing online help  @cindex Installing online help
1279  @cindex Online Help, Installation  @cindex Online Help, Installation
1280  @cindex Speed, of online help  @cindex Speed, of online help
 For IDL system routines, RSI provides extensive documentation.  IDLWAVE  
 can access an ASCII version of this documentation very quickly and  
 accurately.  This is @emph{much} faster than using the IDL online help  
 application, because IDLWAVE usually gets you to the right place in the  
 documentation directly, without any additional browsing and scrolling.  
 For this online help to work, an ASCII version of the IDL documentation,  
 which is not part of the standalone IDLWAVE distribution, is required.  
 The necessary help files can be downloaded from  
 @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}.  The text  
 extracted from the PDF files is fine for normal documentation  
 paragraphs, but graphics and multiline equations will not be well  
 formatted.  See also @ref{Documentation Scan}.  
   
 @cindex Updated online help  
 @cindex Online help, updates  
 @cindex @code{<NEW>..</NEW>}  
 Occasionally RSI releases a synopsis of new features in an IDL release,  
 without simultaneously updating the documentation files, instead  
 preferring a @i{What's New} document which describes the changes.  These  
 updates are incorporated directly into the IDLWAVE online help, and are  
 delimited in @code{<NEW>..</NEW>} blocks.  
   
 @cindex Source code, as online help  
 @cindex DocLib header, as online help  
 For routines which are not documented in the IDL manual (for example  
 personal or library routines), the source code itself is used as help  
 text.  If the requested information can be found in a (more or less)  
 standard DocLib file header, IDLWAVE shows the header (scrolling down to  
 appropriate keyword).  Otherwise the routine definition statement  
 (@code{pro}/@code{function}) is shown.  
1281    
1282  @cindex Structure tags, in online help  For IDL system routines, RSI provides extensive documentation.
1283  @cindex Class tags, in online help  IDLWAVE can access an HTML version of this documentation very quickly
1284  Help is also available for class structure tags (@code{self.TAG}), and  and accurately.  This is @emph{much} faster than using the IDL online
1285  generic structure tags, if structure tag completion is enabled  help application, because IDLWAVE usually gets you to the right place
1286  (@pxref{Structure Tag Completion}).  This is implemented by visiting the  in the documentation directly --- e.g. a specific keyword of a routine
1287  tag within the class or structure definition source itself.  Help is not  --- without any additional browsing and scrolling.  For this online
1288  available on built-in system class tags.  help to work, an HTML version of the IDL documentation, which is not
1289    part of the standalone IDLWAVE distribution, is required.  The
1290    necessary files can be downloaded from @uref{@value{IDLWAVE-HOMEPAGE},
1291    the maintainers webpage}.  There are a variety of options for
1292    displaying the HTML help: see below.  Help for routines without HTML
1293    documentation is also available, using the routine documentation
1294    header and/or source.
1295    
1296  @kindex M-?  @kindex M-?
1297  In any IDL program (or, as with most IDLWAVE commands, in the IDL  In any IDL program (or, as with most IDLWAVE commands, in the IDL
# Line 1261  locations are recognized context for hel Line 1307  locations are recognized context for hel
1307  @tab A keyword parameter of a routine.  @tab A keyword parameter of a routine.
1308  @item @i{System Variable}  @item @i{System Variable}
1309  @tab System variables like @code{!DPI}.  @tab System variables like @code{!DPI}.
1310    @item @i{System Variable Tags}
1311    @tab System variables tags like @code{!D.X_SIZE}.
1312  @item @i{IDL Statement}  @item @i{IDL Statement}
1313  @tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc.  @tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc.
1314  @item @i{Class name}  @item @i{Class name}
# Line 1270  locations are recognized context for hel Line 1318  locations are recognized context for hel
1318  @item @i{Executive Command}  @item @i{Executive Command}
1319  @tab An executive command like @code{.RUN}.  Mostly useful in the shell.  @tab An executive command like @code{.RUN}.  Mostly useful in the shell.
1320  @item @i{Structure Tags}  @item @i{Structure Tags}
1321  @tab In structure tags like @code{state.xsize}  @tab Structure tags like @code{state.xsize}
1322  @item @i{Structure Tags}  @item @i{Class Tags}
1323  @tab In class tags like @code{self.value}.  @tab Class tags like @code{self.value}.
1324  @item @i{Default}  @item @i{Default}
1325  @tab The routine that would be selected for routine info display.  @tab The routine that would be selected for routine info display.
1326  @end multitable  @end multitable
1327    
1328  @cindex @code{OBJ_NEW}, special online help  @cindex @code{OBJ_NEW}, special online help
1329  Note that the @code{OBJ_NEW} function is special in that the help  Note that the @code{OBJ_NEW} function is special in that the help
1330  displayed depends on the cursor position: If the cursor is on the  displayed depends on the cursor position.  If the cursor is on the
1331  @samp{OBJ_NEW}, this function is described.  If it is on the class name  @samp{OBJ_NEW}, this function is described.  If it is on the class
1332  inside the quotes, the documentation for the class is pulled up.  If the  name inside the quotes, the documentation for the class is pulled up.
1333  cursor is @emph{after} the class name, anywhere in the argument list,  If the cursor is @emph{after} the class name, anywhere in the argument
1334  the documentation for the corresponding @code{Init} method and its  list, the documentation for the corresponding @code{Init} method and
1335  keywords is targeted.  its keywords is targeted.
1336    
1337  @noindent Apart from source buffers, there are two more places from  Apart from an IDLWAVE buffer or shell, there are two more places from
1338  which online help can be accessed.  which online help can be accessed.
1339    
1340  @itemize @bullet  @itemize @bullet
# Line 1302  help is available in the online system d Line 1350  help is available in the online system d
1350  program source itself) will be emphasized (e.g. colored blue).  program source itself) will be emphasized (e.g. colored blue).
1351  @end itemize  @end itemize
1352  @noindent  @noindent
1353  In both cases, a blue face indicates that the item is documented in the  In both cases, a blue face indicates that the item is documented in
1354  IDL manual, but an attempt will be made to visit non-blue items directly  the IDL manual, but an attempt will be made to visit non-blue items
1355  in the originating source file.  directly in the originating source file.
1356    
1357  @cindex Help application, key bindings  
1358  @cindex Key bindings, in help application  @menu
1359  The help window is normally displayed in a separate frame.  The  * Help with HTML Documentation::  
1360  following commands can be used to navigate inside the help system:  * Help with Source::            
1361    @end menu
1362    
1363    @node Help with HTML Documentation, Help with Source, Online Help, Online Help
1364    @subsection Help with HTML Documentation
1365    @cindex HTML Help
1366    @cindex Help using HTML manuals
1367    @cindex IDL manual, HTML version
1368    
1369    Help using the HTML documentation is invoked with the built-in Emacs
1370    command @code{browse-url}, which displays the relevant help topic in a
1371    browser of your choosing.  There are many possible browsers to choose
1372    among, with differing advantages and disadvantages.  The variable
1373    @code{idlwave-help-browser-function} controls which browser help is
1374    sent to.  This function is used to set the variable
1375    @code{browse-url-browser-function} locally for IDLWAVE help only.
1376    Customize this variable to see what choices of browsers your system
1377    offers.
1378    
1379    Certain browsers like @code{w3} (bundled with many versions of Emacs)
1380    and @code{w3m} (@uref{http://emacs-w3m.namazu.org/}, the author's help
1381    browser of choice) are run within Emacs, and use Emacs buffers to
1382    display the HTML help.  This can be convenient, especially on small
1383    displays, and images can even be displayed in-line on new Emacs
1384    versions.  However, better formatting results are often achieved with
1385    external browsers, like Mozilla.  IDLWAVE assumes any browser function
1386    containing "w3" is displayed in a local buffer.  If you are using
1387    another Emacs-local browser for which this is not true, set the
1388    variable @code{idlwave-help-browser-is-local}.
1389    
1390    @emph{N.B. For Windows users}: IDLWAVE can bring up RSI help directly
1391    in the Microsoft HTMLHelp documentation supplied with IDL: no
1392    additional help files are needed.  Be sure to set
1393    @code{idlwave-system-directory} and the help file will be found
1394    automatically (or, alternatively, specify its location directly with
1395    @code{idlwave-html-help-location}).  The variable
1396    @code{idlwave-help-use-hh} controls whether HTMLHelp is used, and
1397    which application is called to invoke it (@code{HH} is the default).
1398    The free helper application @code{KEYHH}
1399    (@uref{http://www.keyworks.net/keyhh.htm}) can be used instead, and is
1400    preferrable, as it permits loading new help topics into the same help
1401    window.  @code{KEYHH} must be downloaded and installed separately.
1402    
1403    @xref{HTML Help Browser Tips}, for more information on selecting and
1404    configuring a browser for use with IDL's HTML help system.
1405    
1406    @defopt idlwave-html-help-location @file{/usr/local/etc}
1407    The directory where the @file{idl_html_help} dir or @file{idl.chm}
1408    HTMLHelp files live.
1409    @end defopt
1410    
1411    @defopt idlwave-help-use-hh @code{nil}
1412    If set to @code{'hh} or @code{'keyhh}, use Windows native HTMLHelp
1413    with the specified help application.
1414    @end defopt
1415    
1416    @defopt idlwave-help-browser-function
1417    The browser function to use to display IDLWAVE HTML help.  Should be
1418    one of the functions available for setting
1419    @code{browse-url-browser-function}, which see.
1420    @end defopt
1421    
1422    @defopt idlwave-help-browser-is-local
1423    Is the browser selected in @code{idlwave-help-browser-function} run in a
1424    local Emacs buffer?  Defaults to @code{t} if the function contains
1425    "-w3".
1426    @end defopt
1427    
1428    @defopt idlwave-help-link-face
1429    The face for links to IDLWAVE online help.
1430    @end defopt
1431    
1432    @node Help with Source,  , Help with HTML Documentation, Online Help
1433    @subsection Help with Source
1434    @cindex Help using routine source
1435    
1436    @cindex Source code, as online help
1437    @cindex DocLib header, as online help
1438    For routines which are not documented in an HTML manual (for example
1439    personal or library routines), the source code itself is used as help
1440    text.  If the requested information can be found in a (more or less)
1441    standard DocLib file header, IDLWAVE shows the header (scrolling down to
1442    a keyword, if appropriate).  Otherwise the routine definition statement
1443    (@code{pro}/@code{function}) is shown.  The doclib header sections which
1444    are searched for include @samp{NAME} and @samp{KEYWORDS}.  Localization
1445    support can be added by customizing the @code{idlwave-help-doclib-name}
1446    and @code{idlwave-help-doclib-keyword} variables.
1447    
1448    @cindex Structure tags, in online help
1449    @cindex Class tags, in online help
1450    Help is also available for class structure tags (@code{self.TAG}), and
1451    generic structure tags, if structure tag completion is enabled
1452    (@pxref{Structure Tag Completion}).  This is implemented by visiting the
1453    tag within the class or structure definition source itself.  Help is not
1454    available on built-in system class tags.
1455    
1456    The help window is normally displayed in the same frame, but can be
1457    popped-up in a separate frame.  The following commands can be used to
1458    navigate inside the help system for source files:
1459    
1460  @multitable  @columnfractions .15 .85  @multitable  @columnfractions .15 .85
1461  @item @kbd{@key{SPACE}}  @item @kbd{@key{SPACE}}
# Line 1318  following commands can be used to naviga Line 1464  following commands can be used to naviga
1464  @tab Scroll forward one line.  @tab Scroll forward one line.
1465  @item @kbd{@key{DEL}}  @item @kbd{@key{DEL}}
1466  @tab Scroll back one page.  @tab Scroll back one page.
 @item @kbd{n, p}  
 @tab Browse to the next or previous topic (in physical sequence).  
 @item @kbd{b, f}  
 @tab Move back and forward through the help topic history.  
 @item @kbd{c}  
 @tab Clear the history.  
 @item @kbd{Mouse-2}  
 @tab Follow a link.  Active links are displayed in a different font.  
 Items under @i{See Also} are active, and classes have links to their  
 methods and back.  
 @item @kbd{o}  
 @tab Open a topic.  The topic can be selected with completion.  
 @item @kbd{*}  
 @tab Load the whole help file into Emacs, for global text searches.  
 @item @kbd{q}  
 @tab Kill the help window.  
 @end multitable  
   
 @sp 1  
 @noindent When the help text is a source file, the following commands  
 are also available:  
   
 @multitable  @columnfractions .15 .85  
1467  @item @kbd{h}  @item @kbd{h}
1468  @tab Jump to DocLib Header of the routine whose source is displayed  @tab Jump to DocLib Header of the routine whose source is displayed
1469  as help.  as help.
# Line 1352  as help. Line 1475  as help.
1475  item in the DocLib header.  item in the DocLib header.
1476  @item @kbd{F}  @item @kbd{F}
1477  @tab Fontify the buffer like source code.  See the variable @code{idlwave-help-fontify-source-code}.  @tab Fontify the buffer like source code.  See the variable @code{idlwave-help-fontify-source-code}.
1478    @item @kbd{q}
1479    @tab Kill the help window.
1480  @end multitable  @end multitable
1481    
 @defopt idlwave-help-directory  
 The directory where idlw-help.txt and idlw-help.el are stored.  
 @end defopt  
1482    
1483  @defopt idlwave-help-use-dedicated-frame (@code{t})  @defopt idlwave-help-use-dedicated-frame (@code{nil})
1484  Non-@code{nil} means use a separate frame for Online Help if possible.  Non-@code{nil} means use a separate frame for Online Help if possible.
1485  @end defopt  @end defopt
1486    
# Line 1379  Non-@code{nil} means fontify source code Line 1501  Non-@code{nil} means fontify source code
1501  @end defopt  @end defopt
1502    
1503  @defopt idlwave-help-source-try-header (@code{t})  @defopt idlwave-help-source-try-header (@code{t})
1504  Non-@code{nil} means try to find help in routine header when displaying source  Non-@code{nil} means try to find help in routine header when
1505  file.  displaying source file.
1506  @end defopt  @end defopt
1507    
1508  @defopt idlwave-help-link-face  @defopt idlwave-help-doclib-name (@code{"name"})
1509  The face for links in IDLWAVE online help.  The case-insensitive heading word in doclib headers to locate the
1510    @emph{name} section.  Can be a regexp, e.g. @code{"\\(name\\|nom\\)"}.
1511  @end defopt  @end defopt
1512    
1513  @defopt idlwave-help-activate-links-aggressively (@code{t})  @defopt idlwave-help-doclib-keyword (@code{"KEYWORD"})
1514  Non-@code{nil} means make all possible links in help window active.  The case-insensitive heading word in doclib headers to locate the
1515    @emph{keywords} section.  Can be a regexp.
1516  @end defopt  @end defopt
1517    
1518    
1519  @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode  @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode
1520  @section Completion  @section Completion
1521  @cindex Completion  @cindex Completion
# Line 1404  Non-@code{nil} means make all possible l Line 1529  Non-@code{nil} means make all possible l
1529  @kindex M-@key{TAB}  @kindex M-@key{TAB}
1530  @kindex C-c C-i  @kindex C-c C-i
1531  IDLWAVE offers completion for class names, routine names, keywords,  IDLWAVE offers completion for class names, routine names, keywords,
1532  system variables, class structure tags, regular structure tags and file  system variables, system variable tags, class structure tags, regular
1533  names.  As in many programming modes, completion is bound to  structure tags and file names.  As in many programming modes,
1534  @kbd{M-@key{TAB}} (or @kbd{@key{TAB}} in the IDLWAVE Shell ---  completion is bound to @kbd{M-@key{TAB}} (or @kbd{@key{TAB}} in the
1535  @pxref{Using the Shell}).  Completion uses exactly the same internal  IDLWAVE Shell --- @pxref{Using the Shell}).  Completion uses exactly
1536  information as routine info, so when necessary (rarely) it can be  the same internal information as routine info, so when necessary
1537  updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}).  (rarely) it can be updated with @kbd{C-c C-i}
1538    (@code{idlwave-update-routine-info}).
1539    
1540  The completion function is context sensitive and figures out what to  The completion function is context sensitive and figures out what to
1541  complete based location of the point.  Here are example lines and what  complete based location of the point.  Here are example lines and what
# Line 1443  will always assume a keyword to @samp{pl Line 1569  will always assume a keyword to @samp{pl
1569  also a possible completion here.  You can force completion of a function  also a possible completion here.  You can force completion of a function
1570  name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}.  name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}.
1571    
1572    Giving two prefix arguments (@kbd{C-u C-u M-@key{TAB}}) prompts for a
1573    regular expression to search among the commands to be completed.  As
1574    an example, completing a blank line in this way will allow you to
1575    search for a procedure matching a regexp.
1576    
1577  @cindex Scrolling the @file{*Completions*} window  @cindex Scrolling the @file{*Completions*} window
1578  @cindex Completion, scrolling  @cindex Completion, scrolling
1579  @cindex Completion, Online Help  @cindex Completion, Online Help
# Line 1489  available. Line 1620  available.
1620  @menu  @menu
1621  * Case of Completed Words::     CaseOFcomPletedWords  * Case of Completed Words::     CaseOFcomPletedWords
1622  * Object Method Completion and Class Ambiguity::  obj->Method, what?  * Object Method Completion and Class Ambiguity::  obj->Method, what?
1623  * Object Method Completion in the Shell::  * Object Method Completion in the Shell::  
1624  * Class and Keyword Inheritance::  obj->Method, _EXTRA=e  * Class and Keyword Inheritance::  obj->Method, _EXTRA=e
1625  * Structure Tag Completion::    Completing state.Tag  * Structure Tag Completion::    Completing state.Tag
1626  @end menu  @end menu
# Line 1498  available. Line 1629  available.
1629  @subsection Case of Completed Words  @subsection Case of Completed Words
1630  @cindex Case of completed words  @cindex Case of completed words
1631  @cindex Mixed case completion  @cindex Mixed case completion
1632  The case of the completed words is determined by what is already in the  IDL is a case-insensitive language, so casing is a matter of style
1633  buffer.  When the partial word being completed is all lower case, the  only.  IDLWAVE helps maintain a consistent casing style for completed
1634  completion will be lower case as well.  If at least one character is  items.  The case of the completed words is determined by what is
1635  upper case, the string will be completed in upper case or mixed case.  already in the buffer.  As an exception, when the partial word being
1636  The default is to use upper case for procedures, functions and keywords,  completed is all lower case, the completion will be lower case as
1637  and mixed case for object class names and methods, similar to the  well.  If at least one character is upper case, the string will be
1638  conventions in the IDL manuals.  These defaults can be changed with the  completed in upper case or mixed case, depending on the value of the
1639  variable @code{idlwave-completion-case}.  For instance, to enable  variable @code{idlwave-completion-case}.  The default is to use upper
1640  mixed-case completion for routines in addition to classes and methods,  case for procedures, functions and keywords, and mixed case for object
1641  you need an entry such as @code{routine . preserve} in that variable.  class names and methods, similar to the conventions in the IDL
1642  To enable total control over the case of completed items, independent of  manuals.  For instance, to enable mixed-case completion for routines
1643  buffer context, set @code{idlwave-completion-force-default-case} to  in addition to classes and methods, you need an entry such as
1644  non-@code{nil}.  @code{(routine . preserve)} in that variable.  To enable total control
1645    over the case of completed items, independent of buffer context, set
1646    @code{idlwave-completion-force-default-case} to non-@code{nil}.
1647    
1648  @defopt idlwave-completion-case  @defopt idlwave-completion-case
1649  Association list setting the case (UPPER/lower/Capitalized/MixedCase...)  Association list setting the case (UPPER/lower/Capitalized/MixedCase...)
# Line 1554  narrow down the number of possible compl Line 1687  narrow down the number of possible compl
1687  @code{idlwave-query-class} can be configured to make such prompting the  @code{idlwave-query-class} can be configured to make such prompting the
1688  default for all methods (not recommended), or selectively for very  default for all methods (not recommended), or selectively for very
1689  common methods for which the number of completing keywords would be too  common methods for which the number of completing keywords would be too
1690  large (e.g. @code{Init}).  large (e.g. @code{Init}).  
1691    
1692  @cindex Saving object class on @code{->}  @cindex Saving object class on @code{->}
1693  @cindex @code{->}  @cindex @code{->}
# Line 1568  enabled by default --- the variable @cod Line 1701  enabled by default --- the variable @cod
1701  can be used to turn it on.  can be used to turn it on.
1702    
1703  @defopt idlwave-completion-show-classes (@code{1})  @defopt idlwave-completion-show-classes (@code{1})
1704  Non-@code{nil} means show classes in @file{*Completions*} buffer when  Non-@code{nil} means show up to that many classes in
1705  completing object methods and keywords.  @file{*Completions*} buffer when completing object methods and
1706    keywords.
1707  @end defopt  @end defopt
1708    
1709  @defopt idlwave-completion-fontify-classes (@code{t})  @defopt idlwave-completion-fontify-classes (@code{t})
# Line 1630  entire class inheritance chain.  This is Line 1764  entire class inheritance chain.  This is
1764  @emph{chaining}, and is characterized by chained method calls like  @emph{chaining}, and is characterized by chained method calls like
1765  @w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}.  @w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}.
1766    
1767  IDLWAVE can accommodate this special synergy between class and keyword  IDLWAVE can accomodate this special synergy between class and keyword
1768  inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a  inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a
1769  method's keyword parameters, all keywords of superclass versions of the  method's keyword parameters, all keywords of superclass versions of
1770  method being considered are included in completion.  There is of course  the method being considered can be included in completion.  There is
1771  no guarantee that this type of keyword chaining actually occurrs, but  of course no guarantee that this type of keyword chaining actually
1772  for some methods it's a very convenient assumption.  The variable  occurrs, but for some methods it's a very convenient assumption.  The
1773  @code{idlwave-keyword-class-inheritance} can be used to configure which  variable @code{idlwave-keyword-class-inheritance} can be used to
1774  methods have keyword inheritance treated in this simple, class-driven  configure which methods have keyword inheritance treated in this
1775  way.  By default, only @code{Init} and @code{(Get|Set)Property} are.  simple, class-driven way.  By default, only @code{Init} and
1776  The completion buffer will label keywords based on their originating  @code{(Get|Set)Property} are.  The completion buffer will label
1777  class.  keywords based on their originating class.
1778    
1779  @defopt idlwave-support-inheritance (@code{t})  @defopt idlwave-support-inheritance (@code{t})
1780  Non-@code{nil} means consider inheritance during completion, online help etc.  Non-@code{nil} means consider inheritance during completion, online help etc.
1781  @end defopt  @end defopt
1782    
1783  @defopt idlwave-keyword-class-inheritance  @defopt idlwave-keyword-class-inheritance
1784  A list of regular expressions to match methods for which simple  A list of regular expressions to match methods for which simple
1785  class-driven keyword inheritance will be used for Completion.  class-driven keyword inheritance will be used for Completion.
1786  @end defopt  @end defopt
# Line 1676  Structure tag completion is not enabled Line 1810  Structure tag completion is not enabled
1810  simply add the following to your @file{.emacs}:  simply add the following to your @file{.emacs}:
1811    
1812  @lisp  @lisp
1813     (add-hook 'idlwave-load-hook     (add-hook 'idlwave-load-hook
1814               (lambda () (require 'idlw-complete-structtag)))               (lambda () (require 'idlw-complete-structtag)))
1815  @end lisp  @end lisp
1816    
# Line 1696  for a module name, offering the same def Line 1830  for a module name, offering the same def
1830  @code{idlwave-routine-info} would have used, taken from nearby buffer  @code{idlwave-routine-info} would have used, taken from nearby buffer
1831  contents.  In the minibuffer, specify a complete routine name (including  contents.  In the minibuffer, specify a complete routine name (including
1832  any class part).  IDLWAVE will display the source file in another  any class part).  IDLWAVE will display the source file in another
1833  window, positioned at the routine in question.  window, positioned at the routine in question.  You can also visit a
1834    routine in the current buffer, with completion, by using a single prefix
1835    (@kbd{C-u C-c C-v}).
1836    
1837  @cindex Buffers, killing  @cindex Buffers, killing
1838  @cindex Killing autoloaded buffers  @cindex Killing autoloaded buffers
# Line 1719  taken from context, but you get a chance Line 1855  taken from context, but you get a chance
1855    
1856  @code{idlwave-resolve} is one way to get a library module within reach  @code{idlwave-resolve} is one way to get a library module within reach
1857  of IDLWAVE's routine info collecting functions.  A better way is to  of IDLWAVE's routine info collecting functions.  A better way is to
1858  scan (parts of) the library (@pxref{Library Catalog}).  Routine info on  keep routine information available in catalogs (@pxref{Catalogs}).
1859  library modules will then be available without the need to compile the  Routine info on modules will then be available without the need to
1860  modules first, and even without a running shell.  compile the modules first, and even without a running shell.
1861    
1862  @xref{Sources of Routine Info}, for more information on the ways IDLWAVE  @xref{Sources of Routine Info}, for more information on the ways IDLWAVE
1863  collects data about routines, and how to update this information.  collects data about routines, and how to update this information.
# Line 1970  indentation of the code. Line 2106  indentation of the code.
2106  @end itemize  @end itemize
2107    
2108  @defopt idlwave-do-actions (@code{nil})  @defopt idlwave-do-actions (@code{nil})
2109  Non-@code{nil} means performs actions when indenting.  Non-@code{nil} means performs actions when indenting.  Individual action
2110    settings are described below and set separately.
2111  @end defopt  @end defopt
2112    
2113  @menu  @menu
# Line 2069  your @file{.emacs} file: Line 2206  your @file{.emacs} file:
2206       (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<"       (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<"
2207                                   '(capitalize-word 1) t)                                   '(capitalize-word 1) t)
2208       ;;  Capitalize common block name       ;;  Capitalize common block name
2209       (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"       (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"
2210                                   '(capitalize-word 1) t)))                                   '(capitalize-word 1) t)))
2211  @end lisp  @end lisp
2212    
# Line 2096  expansion. Line 2233  expansion.
2233  @cindex Modification timestamp  @cindex Modification timestamp
2234  @cindex Header, for file documentation  @cindex Header, for file documentation
2235  @cindex Timestamp, in doc header.  @cindex Timestamp, in doc header.
2236  @cindex ChangeLog, in doc header.  @cindex Changelog, in doc header.
2237    
2238  @kindex C-c C-h  @kindex C-c C-h
2239  @kindex C-c C-m  @kindex C-c C-m
# Line 2220  The IDLWAVE shell is an Emacs major mode Line 2357  The IDLWAVE shell is an Emacs major mode
2357  program as an inferior process of Emacs, and works closely with the  program as an inferior process of Emacs, and works closely with the
2358  IDLWAVE major mode in buffers.  It can be used to work with IDL  IDLWAVE major mode in buffers.  It can be used to work with IDL
2359  interactively, to compile and run IDL programs in Emacs buffers and to  interactively, to compile and run IDL programs in Emacs buffers and to
2360  debug these programs.  The IDLWAVE shell is built upon @file{comint}, an  debug these programs.  The IDLWAVE shell is built on @file{comint}, an
2361  Emacs packages which handles the communication with the IDL program.  Emacs packages which handles the communication with the IDL program.
2362  Unfortunately IDL for Windows and MacOS do not have command-prompt  Unfortunately IDL for Windows does not have command-prompt versions
2363  versions and thus do not allow the interaction with  and thus do not allow the interaction with Emacs@footnote{Please
2364  Emacs@footnote{Please inform the maintainer if you come up with a way to  inform the maintainer if you come up with a way to make the IDLWAVE
2365  make the IDLWAVE shell work on these systems.} --- so the IDLWAVE shell  shell work on these systems.} --- so the IDLWAVE shell currently only
2366  currently only works under Unix.  works under Unix and MacOSX.
2367    
2368  @menu  @menu
2369  * Starting the Shell::          How to launch IDL as a subprocess  * Starting the Shell::          How to launch IDL as a subprocess
2370  * Using the Shell::             Interactively working with the Shell  * Using the Shell::             Interactively working with the Shell
2371  * Commands Sent to the Shell::  * Commands Sent to the Shell::  
2372  * Debugging IDL Programs::  * Debugging IDL Programs::      
2373  * Examining Variables::  * Examining Variables::        
2374  * Custom Expression Examination::  * Custom Expression Examination::  
2375  @end menu  @end menu
2376    
2377  @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell  @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell
# Line 2249  currently only works under Unix. Line 2386  currently only works under Unix.
2386  The IDLWAVE shell can be started with the command @kbd{M-x  The IDLWAVE shell can be started with the command @kbd{M-x
2387  idlwave-shell}.  In @code{idlwave-mode} the function is bound to  idlwave-shell}.  In @code{idlwave-mode} the function is bound to
2388  @kbd{C-c C-s}.  It creates a buffer @file{*idl*} which is used to  @kbd{C-c C-s}.  It creates a buffer @file{*idl*} which is used to
2389  interact with the shell.  If the shell is already running, @kbd{C-c C-s}  interact with the shell.  If the shell is already running, @kbd{C-c
2390  will simple switch to the shell buffer.  The command @kbd{C-c C-l}  C-s} will simply switch to the shell buffer.  The command @kbd{C-c
2391  (@code{idlwave-shell-recenter-shell-window}) displays the shell window  C-l} (@code{idlwave-shell-recenter-shell-window}) displays the shell
2392  without selecting it.  The shell can also be started automatically when  window without selecting it.  The shell can also be started
2393  another command tries to send a command to it.  To enable auto start,  automatically when another command tries to send a command to it.  To
2394  set the variable @code{idlwave-shell-automatic-start} to @code{t}.  enable auto start, set the variable
2395    @code{idlwave-shell-automatic-start} to @code{t}.
2396    
2397  In order to create a separate frame for the IDLWAVE shell buffer, call  In order to create a separate frame for the IDLWAVE shell buffer, call
2398  @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or  @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or
2399  @kbd{C-u C-c C-l}.  If you always want a dedicated frame for the shell  @kbd{C-u C-c C-l}.  If you always want a dedicated frame for the shell
2400  window, configure the variable  window, configure the variable
2401  @code{idlwave-shell-use-dedicated-frame}.  @code{idlwave-shell-use-dedicated-frame}.
2402    
2403  To launch a quick IDLWAVE shell directly from a shell prompt without an  To launch a quick IDLWAVE shell directly from a shell prompt without
2404  IDLWAVE buffer (e.g., as a replacement for running inside an xterm),  an IDLWAVE buffer (e.g., as a replacement for running inside an
2405  define an alias with the following content:  xterm), define a system alias with the following content:
2406    
2407  @example  @example
2408  emacs -geometry 80x32 -eval "(idlwave-shell 'quick)"  emacs -geometry 80x32 -eval "(idlwave-shell 'quick)"
# Line 2273  emacs -geometry 80x32 -eval "(idlwave-sh Line 2411  emacs -geometry 80x32 -eval "(idlwave-sh
2411  Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer  Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer
2412  the Emacs process to run directly inside the terminal window.  the Emacs process to run directly inside the terminal window.
2413    
2414    @cindex ENVI
2415    @cindex IDL> Prompt
2416    
2417    To use IDLWAVE with ENVI or other custom packages which change the
2418    @samp{IDL> } prompt, you must change the
2419    @code{idlwave-shell-prompt-pattern}, which defaults to @samp{"^ ?IDL>
2420    "}.  Normally, you can just replace the @samp{IDL} in this expression
2421    with the prompt you see.  A suitable pattern which matches the prompt
2422    for both ENVI and IDL simultaneously is @samp{"^ ?\\(ENVI\\|IDL\\)> "}.
2423    
2424  @defopt idlwave-shell-explicit-file-name (@file{idl})  @defopt idlwave-shell-explicit-file-name (@file{idl})
2425  This is the command to run IDL.  This is the command to run IDL.
2426  @end defopt  @end defopt
# Line 2302  Initial commands, separated by newlines, Line 2450  Initial commands, separated by newlines,
2450  Non-@code{nil} means preserve command history between sessions.  Non-@code{nil} means preserve command history between sessions.
2451  @end defopt  @end defopt
2452    
2453  @defopt idlwave-shell-command-history-file (@file{~/.idlwhist})  @defopt idlwave-shell-command-history-file (@file{~/.idlwave/.idlwhist})
2454  The file in which the command history of the idlwave shell is saved.  The file in which the command history of the idlwave shell is saved.
2455    Unless it's an absolute path, it goes in
2456    @code{idlwave-config-directory}.
2457  @end defopt  @end defopt
2458      
2459  @defopt idlwave-shell-use-dedicated-frame (@code{nil})  @defopt idlwave-shell-use-dedicated-frame (@code{nil})
2460  Non-@code{nil} means IDLWAVE should use a special frame to display  Non-@code{nil} means IDLWAVE should use a special frame to display the
2461  shell buffer.  shell buffer.
2462  @end defopt  @end defopt
2463    
# Line 2476  By default, much of this background shel Line 2626  By default, much of this background shel
2626  from the user, but this is configurable.  The custom variable  from the user, but this is configurable.  The custom variable
2627  @code{idlwave-abbrev-show-commands} allows you to configure which  @code{idlwave-abbrev-show-commands} allows you to configure which
2628  commands sent to the shell are shown there.  For a related customization  commands sent to the shell are shown there.  For a related customization
2629  for separating the output of @emph{examine} commands @xref{Examining  for separating the output of @emph{examine} commands, see @ref{Examining
2630  Variables}.  Variables}.
2631    
2632  @defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)})  @defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)})
2633  A list of command types to echo in the shell when sent.  Possible values  A list of command types to echo in the shell when sent.  Possible values
2634  are @code{run} for @code{.run}, @code{.compile} and other run commands,  are @code{run} for @code{.run}, @code{.compile} and other run commands,
2635  @code{misc} for lesser used commands like @code{window}, @code{retall},  @code{misc} for lesser used commands like @code{window},
2636  etc., @code{breakpoint} for breakpoint setting and clearing commands,  @code{retall},@code{close}, etc., @code{breakpoint} for breakpoint
2637  and @code{debug} for other debug, stepping, and continue commands.  In  setting and clearing commands, and @code{debug} for other debug,
2638  addition, if the variable is set to the single symbol @code{'everything},  stepping, and continue commands.  In addition, if the variable is set to
2639  all the copious shell input is displayed (which is probably only useful  the single symbol @code{'everything}, all the copious shell input is
2640  for debugging purposes).  displayed (which is probably only useful for debugging purposes).
2641    N.B. For hidden commands which produce output by side-effect, that
2642    output remains hidden (e.g., stepping through a @code{print} command).
2643    As a special case, any error message in the output will be displayed
2644    (e.g., stepping to an error).
2645  @end defopt  @end defopt
2646    
2647  @node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell  @node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell
# Line 2497  for debugging purposes). Line 2651  for debugging purposes).
2651  @cindex Toolbar  @cindex Toolbar
2652    
2653  Programs can be compiled, run, and debugged directly from the source  Programs can be compiled, run, and debugged directly from the source
2654  buffer in Emacs.  IDLWAVE makes compiling and debugging IDL programs  buffer in Emacs, walking through arbitrarily deeply nested code,
2655  far less cumbersome by providing a full-featured,  printing expressions and skipping up and down the calling stack along
2656  key/menu/toolbar-driven interface to commands like @code{breakpoint},  the way.  IDLWAVE makes compiling and debugging IDL programs far less
2657  @code{.step}, @code{.run}, etc.  cumbersome by providing a full-featured, key/menu/toolbar-driven
2658    interface to commands like @code{breakpoint}, @code{.step},
2659  The IDLWAVE shell installs key bindings both in the shell buffer and in  @code{.run}, etc.  It can even perform complex debug operations not
2660  all IDL code buffers of the current Emacs session, so debug commands  natively supported by IDL (like continuing to the line at the cursor).
2661  work in both places (in the shell, commands operate on the last file  
2662  compiled).  On Emacs versions which support this, a debugging toolbar is  The IDLWAVE shell installs key bindings both in the shell buffer and
2663  also installed.  The display of the toolbar can be toggled with @kbd{C-c  in all IDL code buffers of the current Emacs session, so debug
2664  C-d C-t} (@code{idlwave-shell-toggle-toolbar}).  commands work in both places (in the shell, commands operate on the
2665    last file compiled).  On Emacs versions which support it, a debugging
2666    toolbar is also installed.  The toolbar display can be toggled with
2667    @kbd{C-c C-d C-t} (@code{idlwave-shell-toggle-toolbar}).
2668    
2669    
2670  @defopt idlwave-shell-use-toolbar (@code{t})  @defopt idlwave-shell-use-toolbar (@code{t})
2671  Non-@code{nil} means use the debugging toolbar in all IDL related  Non-@code{nil} means use the debugging toolbar in all IDL related
# Line 2515  buffers. Line 2673  buffers.
2673  @end defopt  @end defopt
2674    
2675  @menu  @menu
2676  * Debug Key Bindings::  * A Tale of Two Modes::        
2677  * Compiling Programs::  * Debug Key Bindings::          
2678  * Breakpoints and Stepping::  * Breakpoints and Stepping::    
2679  * Walking the Calling Stack::  * Compiling Programs::          
2680    * Walking the Calling Stack::  
2681    * Electric Debug Mode::        
2682  @end menu  @end menu
2683    
2684  @node Debug Key Bindings, Compiling Programs, Debugging IDL Programs, Debugging IDL Programs  
2685    @node A Tale of Two Modes, Debug Key Bindings, Debugging IDL Programs, Debugging IDL Programs
2686    @subsection A Tale of Two Modes
2687    @cindex Electric Debug Mode
2688    @cindex Debugging Interface
2689    
2690    The many debugging, compiling, and examination commands provided in
2691    IDLWAVE are available simultaneously through two different interfaces:
2692    the original, multi-key command interface, and the new Electric Debug
2693    Mode.  The functionality they offer is similar, but the way you
2694    interact with them is quite different.  The main difference is that,
2695    in Electric Debug Mode, the source buffers are made read-only, and
2696    single key-strokes are used to step through, examine expressions, set
2697    and remove breakpoints, etc.  The same variables, prefix arguments,
2698    and settings apply to both versions, and both can be used
2699    interchangeably.  By default, when breakpoints are hit, Electric Debug
2700    Mode is enabled.  The traditional interface is described first.
2701    @xref{Electric Debug Mode}, for more on that mode.
2702    
2703    
2704    @sp 1
2705    @noindent @strong{Note that electric debug mode can be prevented from
2706    activating automatically by customizing the variable
2707    @code{idlwave-shell-automatic-electric-debug}.}
2708    
2709    @node Debug Key Bindings, Breakpoints and Stepping, A Tale of Two Modes, Debugging IDL Programs
2710  @subsection Debug Key Bindings  @subsection Debug Key Bindings
2711  @kindex C-c C-d  @kindex C-c C-d
2712  @cindex Key bindings  @cindex Key bindings
2713    
2714  The debugging key bindings are by default on the prefix key @kbd{C-c  The standard debugging key bindings are always available by default on
2715  C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d  the prefix key @kbd{C-c C-d}, so, for example, setting a breakpoint is
2716  C-b}, and compiling a source file with @kbd{C-c C-d C-c}.  If you find  done with @kbd{C-c C-d C-b}, and compiling a source file with @kbd{C-c
2717  this too much work, you can easily configure IDLWAVE to use one or more  C-d C-c}.  You can also easily configure IDLWAVE to use one or more
2718  modifier keys not in use by other commands, in lieu of the prefix  modifier keys not in use by other commands, in lieu of the prefix
2719  @kbd{C-c C-d} (though these bindings will typically also be available  @kbd{C-c C-d} (though these bindings will typically also be available
2720  --- see @code{idlwave-shell-activate-prefix-keybindings}).  For example,  --- see @code{idlwave-shell-activate-prefix-keybindings}).  For
2721  if you write in @file{.emacs}:  example, if you include in @file{.emacs}:
2722    
2723  @lisp  @lisp
2724  (setq idlwave-shell-debug-modifiers '(control shift))  (setq idlwave-shell-debug-modifiers '(control shift))
2725  @end lisp  @end lisp
2726    
2727  @noindent a breakpoint can be set by pressing @kbd{b} while holding down  @noindent a breakpoint can then be set by pressing @kbd{b} while holding down
2728  @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}.  Compiling a  @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}.  Compiling a
2729  source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d},  source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d},
2730  etc.  In the remainder of this chapter we will assume that the @kbd{C-c  etc.  In the remainder of this chapter we will assume that the
2731  C-d} bindings are active, but each of these bindings will have an  @kbd{C-c C-d} bindings are active, but each of these bindings will
2732  equivalent single-keypress shortcut if modifiers are given in the  have an equivalent shortcut if modifiers are given in the
2733  @code{idlwave-shell-debug-modifiers} variable (see @pxref{Lesson II --  @code{idlwave-shell-debug-modifiers} variable (@pxref{Lesson II --
2734  Customization}).  Customization}).  A much simpler and faster form of debugging for
2735    running code is also available by default --- see @ref{Electric Debug
2736    Mode}.
2737    
2738  @defopt idlwave-shell-prefix-key (@kbd{C-c C-d})  @defopt idlwave-shell-prefix-key (@kbd{C-c C-d})
2739  The prefix key for the debugging map  The prefix key for the debugging map
# Line 2559  key, like @kbd{C-c C-d C-b}. Line 2746  key, like @kbd{C-c C-d C-b}.
2746  @end defopt  @end defopt
2747    
2748  @defopt idlwave-shell-debug-modifiers (@code{nil})  @defopt idlwave-shell-debug-modifiers (@code{nil})
2749  List of modifier keys to use for additional binding of debugging  List of modifier keys to use for additional, alternative binding of
2750  commands in the shell and source buffers.  Can be one or more of  debugging commands in the shell and source buffers.  Can be one or
2751  @code{control}, @code{meta}, @code{super}, @code{hyper}, @code{alt}, and  more of @code{control}, @code{meta}, @code{super}, @code{hyper},
2752  @code{shift}.  @code{alt}, and @code{shift}.
 @end defopt  
   
 @node Compiling Programs, Breakpoints and Stepping, Debug Key Bindings, Debugging IDL Programs  
 @subsection Compiling Programs  
 @cindex Compiling programs  
 @cindex Programs, compiling  
 @cindex Default command line, executing  
 @cindex Executing a default command line  
   
 @kindex C-c C-d C-c  
 In order to compile the current buffer under the IDLWAVE shell, press  
 @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}).  This first saves the  
 current buffer and then sends the command @samp{.run path/to/file} to the  
 shell.  You can also execute @kbd{C-c C-d C-c} from the shell buffer, in  
 which case the most recently compiled buffer will be saved and  
 re-compiled.  
   
 When developing or debugging a program, it is often necessary to execute  
 the same command line many times.  A convenient way to do this is  
 @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}).  
 This command first resets IDL from a state of interrupted execution by  
 closing all files and returning to the main interpreter level.  Then a  
 default command line is send to the shell.  To edit the default command  
 line, call @code{idlwave-shell-execute-default-command-line} with a  
 prefix argument: @kbd{C-u C-c C-d C-y}.  
   
 @defopt idlwave-shell-mark-stop-line (@code{t})  
 Non-@code{nil} means mark the source code line where IDL is currently  
 stopped.  The value specifies the preferred method.  Legal values are  
 @code{nil}, @code{t}, @code{arrow}, and @code{face}.  
 @end defopt  
   
 @defopt idlwave-shell-overlay-arrow (@code{">"})  
 The overlay arrow to display at source lines where execution halts, if  
 configured in @code{idlwave-shell-mark-stop-line}.  
 @end defopt  
   
 @defopt idlwave-shell-stop-line-face  
 The face which highlights the source line where IDL is stopped, if  
 configured in @code{idlwave-shell-mark-stop-line}.  
2753  @end defopt  @end defopt
2754    
2755  @node Breakpoints and Stepping, Walking the Calling Stack, Compiling Programs, Debugging IDL Programs  @node Breakpoints and Stepping, Compiling Programs, Debug Key Bindings, Debugging IDL Programs
2756  @subsection Breakpoints and Stepping  @subsection Breakpoints and Stepping
2757  @cindex Breakpoints  @cindex Breakpoints
2758  @cindex Stepping  @cindex Stepping
# Line 2613  configured in @code{idlwave-shell-mark-s Line 2760  configured in @code{idlwave-shell-mark-s
2760    
2761  @kindex C-c C-d C-b  @kindex C-c C-d C-b
2762  @kindex C-c C-d C-b  @kindex C-c C-d C-b
2763  You can set breakpoints and step through a program with IDLWAVE.  IDLWAVE helps you set breakpoints and step through code.  Setting a
2764  Setting a breakpoint in the current line of the source buffer is done  breakpoint in the current line of the source buffer is accomplished
2765  with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}).  With a prefix  with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}).  With a
2766  arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a  prefix arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a
2767  @code{/ONCE} keyword, meaning that it will be deleted after first use.  @code{/ONCE} keyword, meaning that it will be deleted after first use.
2768  With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), the  With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}),
2769  breakpoint will only be active the @code{nth} time it is hit.  With a  the breakpoint will only be active the @code{nth} time it is hit.
2770  single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt for a  With a single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt
2771  condition --- an IDL expression to be evaulated and trigger the  for a condition --- an IDL expression to be evaulated and trigger the
2772  breakpoint only if true.  To clear the breakpoint in the current line,  breakpoint only if true.  To clear the breakpoint in the current line,
2773  use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}).  When executed  use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}).  When
2774  from the shell window, the breakpoint where IDL is currently stopped  executed from the shell window, the breakpoint where IDL is currently
2775  will be deleted.  To clear all breakpoints, use @kbd{C-c C-d C-a}  stopped will be deleted.  To clear all breakpoints, use @kbd{C-c C-d
2776  (@code{idlwave-clear-all-bp}).  Breakpoint lines are highlighted in the  C-a} (@code{idlwave-clear-all-bp}).  Breakpoints can also be disabled
2777  source code.  Note that IDL places breakpoints as close as possible on  and re-enabled: @kbd{C-c C-d C-\}
2778  or after the line you specify.  IDLWAVE queries the shell for the actual  (@code{idlwave-shell-toggle-enable-current-bp}).  
2779  breakpoint location which was set, so the exact line you specify may not  
2780  be marked.  
2781    Breakpoint lines are highlighted or indicated with an icon in the
2782    source code (different icons for conditional, after, and other break
2783    types).  Disabled breakpoints are @emph{grayed out} by default.  Note
2784    that IDL places breakpoints as close as possible on or after the line
2785    you specify.  IDLWAVE queries the shell for the actual breakpoint
2786    location which was set, so the exact line you specify may not be
2787    marked.  You can re-sync the breakpoint list and display at any time
2788    (e.g., if you add or remove some on the command line) using @kbd{C-c
2789    C-d C-l}.
2790    
2791  Once the program has stopped somewhere, you can step through it.  The  Once the program has stopped somewhere, you can step through it.  The
2792  most important stepping commands are @kbd{C-c C-d C-s} to execute one  most important stepping commands are @kbd{C-c C-d C-s} to execute one
# Line 2651  breakpoint and stepping commands: Line 2807  breakpoint and stepping commands:
2807  @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp})  @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp})
2808  @item @kbd{C-c C-d C-a}  @item @kbd{C-c C-d C-a}
2809  @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp})  @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp})
2810    @item @kbd{C-c C-d [}
2811    @tab Go to the previous breakpoint (@code{idlwave-shell-goto-previous-bp})
2812    @item @kbd{C-c C-d ]}
2813    @tab Go to the next breakpoint (@code{idlwave-shell-goto-next-bp})
2814    @item @kbd{C-c C-d C-\}
2815    @tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp})
2816    @item @kbd{C-c C-d C-j}
2817    @tab Set a breakpoint at the beginning of the enclosing routine.
2818  @item @kbd{C-c C-d C-s}  @item @kbd{C-c C-d C-s}
2819  @tab Step, into function calls (@code{idlwave-shell-step})  @tab Step, into function calls (@code{idlwave-shell-step})
2820  @item @kbd{C-c C-d C-n}  @item @kbd{C-c C-d C-n}
# Line 2666  breakpoint and stepping commands: Line 2830  breakpoint and stepping commands:
2830  @item @kbd{C-c C-d C-h}  @item @kbd{C-c C-d C-h}
2831  @tab Continue to line at cursor position (@code{idlwave-shell-to-here})  @tab Continue to line at cursor position (@code{idlwave-shell-to-here})
2832  @item @kbd{C-c C-d C-r}  @item @kbd{C-c C-d C-r}
2833  @tab Continue execution to next breakpoint (@code{idlwave-shell-cont})  @tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont})
2834  @item @kbd{C-c C-d C-up}  @item @kbd{C-c C-d C-up}
2835  @tab Show higher level in calling stack (@code{idlwave-shell-stack-up})  @tab Show higher level in calling stack (@code{idlwave-shell-stack-up})
2836  @item @kbd{C-c C-d C-down}  @item @kbd{C-c C-d C-down}
2837  @tab Show lower level in calling stack (@code{idlwave-shell-stack-down})  @tab Show lower level in calling stack (@code{idlwave-shell-stack-down})
2838  @end multitable  @end multitable
2839    
2840    All of these commands have equivalents in Electric Debug Mode, which
2841    provides faster access (@pxref{Electric Debug Mode}).
2842    
2843  @defopt idlwave-shell-mark-breakpoints (@code{t})  @defopt idlwave-shell-mark-breakpoints (@code{t})
2844  Non-@code{nil} means mark breakpoints in the source file buffers.  The  Non-@code{nil} means mark breakpoints in the source file buffers.  The
2845  value indicates the preferred method.  Legal values are @code{nil},  value indicates the preferred method.  Legal values are @code{nil},
# Line 2684  The face for breakpoint lines in the sou Line 2851  The face for breakpoint lines in the sou
2851  @code{idlwave-shell-mark-breakpoints} has the value @code{face}.  @code{idlwave-shell-mark-breakpoints} has the value @code{face}.
2852  @end defopt  @end defopt
2853    
2854  @node Walking the Calling Stack,  , Breakpoints and Stepping, Debugging IDL Programs  @node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs
2855    @subsection Compiling Programs
2856    @cindex Compiling programs
2857    @cindex Programs, compiling
2858    @cindex Default command line, executing
2859    @cindex Executing a default command line
2860    
2861    @kindex C-c C-d C-c
2862    In order to compile the current buffer under the IDLWAVE shell, press
2863    @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}).  This first saves the
2864    current buffer and then sends the command @samp{.run path/to/file} to the
2865    shell.  You can also execute @kbd{C-c C-d C-c} from the shell buffer, in
2866    which case the most recently compiled buffer will be saved and
2867    re-compiled.
2868    
2869    When developing or debugging a program, it is often necessary to execute
2870    the same command line many times.  A convenient way to do this is
2871    @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}).
2872    This command first resets IDL from a state of interrupted execution by
2873    closing all files and returning to the main interpreter level.  Then a
2874    default command line is send to the shell.  To edit the default command
2875    line, call @code{idlwave-shell-execute-default-command-line} with a
2876    prefix argument: @kbd{C-u C-c C-d C-y}.  If no default command line has
2877    been set (or you give two prefix arguments), the last command on the
2878    @code{comint} input history is sent.
2879    
2880    @defopt idlwave-shell-mark-stop-line (@code{t})
2881    Non-@code{nil} means mark the source code line where IDL is currently
2882    stopped.  The value specifies the preferred method.  Legal values are
2883    @code{nil}, @code{t}, @code{arrow}, and @code{face}.
2884    @end defopt
2885    
2886    @defopt idlwave-shell-overlay-arrow (@code{">"})
2887    The overlay arrow to display at source lines where execution halts, if
2888    configured in @code{idlwave-shell-mark-stop-line}.
2889    @end defopt
2890    
2891    @defopt idlwave-shell-stop-line-face
2892    The face which highlights the source line where IDL is stopped, if
2893    configured in @code{idlwave-shell-mark-stop-line}.
2894    @end defopt
2895    
2896    @node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs
2897  @subsection Walking the Calling Stack  @subsection Walking the Calling Stack
2898  @cindex Calling stack, walking  @cindex Calling stack, walking
2899    
# Line 2704  for information how to examine the value Line 2913  for information how to examine the value
2913  higher calling stack levels.  higher calling stack levels.
2914    
2915  @ifhtml  @ifhtml
2916    <A NAME="EDEBUG"></A>
2917    @end ifhtml
2918    @node Electric Debug Mode,  , Walking the Calling Stack, Debugging IDL Programs
2919    @subsection Electric Debug Mode
2920    @cindex Electric Debug Mode
2921    @cindex @samp{*Debugging*}
2922    
2923    Even with a convenient debug key prefix enabled, repetitive stepping,
2924    variable examination (@pxref{Examining Variables}), and other
2925    debugging activities can be awkward and slow using commands which
2926    require multiple keystrokes.  Luckily, there's a better way, inspired
2927    by the lisp e-debug mode, and available through the @emph{Electric
2928    Debug Mode}.  By default, as soon as a breakpoint is hit, this minor
2929    mode is enabled.  The buffer showing the line where execution has
2930    halted is switched to Electric Debug Mode.  This mode is visible as
2931    @samp{*Debugging*} in the mode line, and a different face (violet by
2932    default, where color is available) for the line stopped at point.  The
2933    buffer is made read-only and single-character bindings for the most
2934    commonly used debugging commands are enabled:
2935    
2936    @multitable @columnfractions .2 .8
2937    @item @kbd{a}
2938    @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp})
2939    @item @kbd{b}
2940    @tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here})
2941    @item @kbd{d}
2942    @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp})
2943    @item @kbd{h}
2944    @tab Continue to the line at cursor position (@code{idlwave-shell-to-here})
2945    @item @kbd{i}
2946    @tab Set breakpoint in function named here (@code{idlwave-shell-break-in})
2947    @item @kbd{[}
2948    @tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp})
2949    @item @kbd{]}
2950    @tab Go to the next breakpoint in the file
2951    (@code{idlwave-shell-goto-next-bp})
2952    @item @kbd{\}
2953    @tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp})
2954    @item @kbd{j}
2955    @tab Set breakpoint at beginning of enclosing routine (@code{idlwave-shell-break-this-module})
2956    @item @kbd{k}
2957    @tab Skip one statement (@code{idlwave-shell-skip})
2958    @item @kbd{m}
2959    @tab Continue to end of function (@code{idlwave-shell-return})
2960    @item @kbd{n}
2961    @tab Step, over function calls (@code{idlwave-shell-stepover})
2962    @item @kbd{o}
2963    @tab Continue past end of function (@code{idlwave-shell-out})
2964    @item @kbd{p}
2965    @tab Print expression near point or in region with @kbd{C-u p} (@code{idlwave-shell-print})
2966    @item @kbd{q}
2967    @tab End the debugging session and return to the Shell's main level
2968    (@code{idlwave-shell-retall})
2969    @item @kbd{r}
2970    @tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont})
2971    @item @kbd{s} or @kbd{@key{SPACE}}
2972    @tab Step, into function calls (@code{idlwave-shell-step})
2973    @item @kbd{t}
2974    @tab Print a calling-level traceback in the shell
2975    @item @kbd{u}
2976    @tab Continue to end of block (@code{idlwave-shell-up})
2977    @item @kbd{v}
2978    @tab Turn Electric Debug Mode off
2979    (@code{idlwave-shell-electric-debug-mode})
2980    @item @kbd{x}
2981    @tab Examine expression near point (or in region with @kbd{C-u x})
2982    with shortcut of examine type.
2983    @item @kbd{z}
2984    @tab Reset IDL (@code{idlwave-shell-reset})
2985    @item @kbd{+} or @kbd{=}
2986    @tab Show higher level in calling stack (@code{idlwave-shell-stack-up})
2987    @item @kbd{-} or @kbd{_}
2988    @tab Show lower level in calling stack (@code{idlwave-shell-stack-down})
2989    @item @kbd{?}
2990    @tab Help on expression near point or in region with @kbd{C-u ?}
2991    (@code{idlwave-shell-help-expression})
2992    @item @kbd{C-?}
2993    @tab Show help on the commands available.
2994    @end multitable
2995    
2996    Most single-character electric debug bindings use the final keystroke
2997    of the equivalent multiple key commands (which are of course also
2998    still available), but some differ (e.g. @kbd{t},@kbd{q},@kbd{x}).
2999    Some have additional convenience bindings (like @kbd{@key{SPACE}} for
3000    stepping).  All prefix and other argument options described in this
3001    section for the commands invoked by electric debug bindings are still
3002    valid.  For example, @kbd{C-u b} sets a conditional breakpoint, just
3003    as it did with @kbd{C-u C-c C-d C-b}.
3004    
3005    You can toggle the electric debug mode at any time in a buffer using
3006    @kbd{C-c C-d C-v} (@kbd{v} to turn it off while in the mode), or from
3007    the Debug menu.  Normally the mode will be enabled and disabled at the
3008    appropriate times, but occassionally you might want to edit a file
3009    while still debugging it, or switch to the mode for conveniently
3010    setting lots of breakpoints.
3011    
3012    To quickly abandon a debugging session and return to normal editing at
3013    the Shell's main level, use @kbd{q} (@code{idlwave-shell-retall}).
3014    This disables electric debug mode in all IDLWAVE buffers@footnote{Note
3015    that this binding is not symmetric: @kbd{C-c C-d C-q} is bound to
3016    @code{idlwave-shell-quit}, which quits your IDL session.}.  Help is
3017    available for the command shortcuts with @kbd{C-?}.  If you find this
3018    mode gets in your way, you can keep it from automatically activating
3019    by setting the variable @code{idlwave-shell-automatic-electric-debug}
3020    to @code{nil}, or @code{'breakpoint}.  If you'd like the convenient
3021    electric debug shortcuts available also when run-time errors are
3022    encountered, set to @code{t}.
3023    
3024    @defopt idlwave-shell-automatic-electric-debug (@code{'breakpoint})
3025    Whether to enter electric debug mode automatically when a breakpoint
3026    or run-time error is encountered, and then disable it in all buffers
3027    when the $MAIN$ level is reached (either through normal program
3028    execution, or retall).  In addition to @code{nil} for never, and
3029    @code{t} for both breakpoints and errors, this can be
3030    @code{'breakpoint} (the default) to enable it only at breakpoint
3031    halts.
3032    @end defopt
3033    
3034    @defopt idlwave-shell-electric-zap-to-file (@code{t})
3035    If set, when entering electric debug mode, select the window displaying
3036    the file where point is stopped.  This takes point away from the shell
3037    window, but is useful for immediate stepping, etc.
3038    @end defopt
3039    
3040    @ifhtml
3041  <A NAME="EXAMINE"></A>  <A NAME="EXAMINE"></A>
3042  @end ifhtml  @end ifhtml
3043  @node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell  @node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell
3044  @section Examining Variables  @section Examining Variables
3045  @cindex @code{PRINT} expressions  @cindex @code{PRINT} expressions
3046  @cindex @code{HELP}, on expressions  @cindex @code{HELP}, on expressions
3047  @cindex Expressions, printing  @cindex Expressions, printing & help
3048  @cindex Expressions, help  @cindex Examining expressions
3049  @cindex Printing expressions  @cindex Printing expressions
3050  @cindex Mouse binding to print expressions  @cindex Mouse binding to print expressions
3051    
3052  @kindex C-c C-d C-p  @kindex C-c C-d C-p
3053  Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)},  Do you find yourself repeatedly typing,
3054  and similar statements to remind yourself of the  e.g. @code{print,n_elements(x)}, and similar statements to remind
3055  type/size/structure/value/etc. of variables and expressions in your code  yourself of the type/size/structure/value/etc. of variables and
3056  or at the command line?  IDLWAVE has a suite of special commands to  expressions in your code or at the command line?  IDLWAVE has a suite
3057  automate these types of variables or expression examinations.  They work  of special commands to automate these types of variable or expression
3058  by sending statements to the shell formatted to include the indicated  examinations.  They work by sending statements to the shell formatted
3059  expression.  to include the indicated expression.
3060    
3061  These examination commands can be used in the shell or buffer at any  These examination commands can be used in the shell or buffer at any
3062  time (as long as the shell is running), and are very useful when  time (as long as the shell is running), and are very useful when
# Line 2730  execution is stopped in a buffer due to Line 3064  execution is stopped in a buffer due to
3064  or while composing a long command in the IDLWAVE shell.  In the latter  or while composing a long command in the IDLWAVE shell.  In the latter
3065  case, the command is sent to the shell and its output is visible, but  case, the command is sent to the shell and its output is visible, but
3066  point remains unmoved in the command being composed --- you can inspect  point remains unmoved in the command being composed --- you can inspect
3067  the constituents of a command you're building without interrupting the  the contituents of a command you're building without interrupting the
3068  process of building it!  You can even print arbitrary expressions from  process of building it!  You can even print arbitrary expressions from
3069  older input or output further up in the shell window --- any expression,  older input or output further up in the shell window --- any expression,
3070  variable, number, or function you see can be examined.  variable, number, or function you see can be examined.
# Line 2743  contents, and @key{q} hides the buffer. Line 3077  contents, and @key{q} hides the buffer.
3077    
3078  The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to  The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to
3079  print the expression at point, and @kbd{C-c C-d ?}, to invoke help on  print the expression at point, and @kbd{C-c C-d ?}, to invoke help on
3080  this expression.  The expression at point is either an array expression  this expression@footnote{Available as @kbd{p} and @kbd{?} in Electric
3081  or a function call, or the contents of a pair of parentheses.  The  Debug Mode (@pxref{Electric Debug Mode})}.  The expression at point is
3082  selected expression is highlighted, and simultaneously the resulting  either an array expression or a function call, or the contents of a
3083  output is highlighted in the shell.  Calling the above commands with a  pair of parentheses.  The selected expression is highlighted, and
3084  prefix argument will prompt for an expression instead of using the one  simultaneously the resulting output is highlighted in the shell.
3085  at point.  Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will use the  Calling the above commands with a prefix argument will use the current
3086  current region as expression.  region as expression instead of using the one at point.  Two prefix
3087    arguments (@kbd{C-u C-u C-c C-d C-p}) will prompt for an expression.
3088    
3089  For added speed and convenience, there are mouse bindings which allow  For added speed and convenience, there are mouse bindings which allow
3090  you to click on expressions and examine their values.  Use  you to click on expressions and examine their values.  Use
# Line 2757  you to click on expressions and examine Line 3092  you to click on expressions and examine
3092  help (i.e. you need to hold down @key{META} and @key{CONTROL} while  help (i.e. you need to hold down @key{META} and @key{CONTROL} while
3093  clicking with the middle mouse button).  If you simply click, the  clicking with the middle mouse button).  If you simply click, the
3094  nearest expression will be selected in the same manner as described  nearest expression will be selected in the same manner as described
3095  above.  You can also @emph{drag} the mouse in order to highlight exactly  above.  You can also @emph{drag} the mouse in order to highlight
3096  a specific expression or sub-expression to be examined.  For custom  exactly the specific expression or sub-expression you want to examine.
3097  expression examination, and the customizable pop-up examine selection,  For custom expression examination, and the powerful customizable
3098  @xref{Custom Expression Examination}.  pop-up examine selection, @xref{Custom Expression Examination}.
3099    
3100  @cindex Printing expressions, on calling stack  @cindex Printing expressions, on calling stack
3101  @cindex Restrictions for expression printing  @cindex Restrictions for expression printing
# Line 2782  with a @samp{( )} will be interpreted as Line 3117  with a @samp{( )} will be interpreted as
3117  @cindex ROUTINE_NAMES, IDL procedure  @cindex ROUTINE_NAMES, IDL procedure
3118  N.B.: printing values of expressions on higher levels of the calling  N.B.: printing values of expressions on higher levels of the calling
3119  stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES},  stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES},
3120  which may or may not be available in future versions of IDL.  which may or may not be available in future versions of IDL.  Caveat
3121    Examinor.
3122  @end itemize  @end itemize
3123    
3124  @defopt idlwave-shell-expression-face  @defopt idlwave-shell-expression-face
# Line 2792  the expression printed by IDL. Line 3128  the expression printed by IDL.
3128  @end defopt  @end defopt
3129    
3130  @defopt idlwave-shell-output-face  @defopt idlwave-shell-output-face
3131  The face for @code{idlwave-shell-output-overlay}.  The face for @code{idlwave-shell-output-overlay}.  
3132  Allows to choose the font, color and other properties for the most  Allows to choose the font, color and other properties for the most
3133  recent output of IDL when examining an expression."  recent output of IDL when examining an expression."
3134  @end defopt  @end defopt
3135    
3136  @defopt idlwave-shell-separate-examine-output (@code{t})  @defopt idlwave-shell-separate-examine-output (@code{t})
3137  If non-@code{nil}, re-direct the output of examine commands to a special  If non-@code{nil}, re-direct the output of examine commands to a special
3138  @file{*Examine*} buffer, instead of in the shell itself.  @file{*Examine*} buffer, instead of in the shell itself.
3139  @end defopt  @end defopt
3140    
3141  @node Custom Expression Examination,  , Examining Variables, The IDLWAVE Shell  @node Custom Expression Examination,  , Examining Variables, The IDLWAVE Shell
# Line 2812  endless (just look, for instance, at the Line 3148  endless (just look, for instance, at the
3148  @code{widget_info()}).  Rather than attempt to include them all, IDLWAVE  @code{widget_info()}).  Rather than attempt to include them all, IDLWAVE
3149  provides two easy methods to customize your own commands, with a special  provides two easy methods to customize your own commands, with a special
3150  mouse examine command, and two macros for generating your own examine  mouse examine command, and two macros for generating your own examine
3151  bindings.  key and mouse bindings.
3152    
3153  The most powerful and flexible mouse examine command is available on  The most powerful and flexible mouse examine command of all is
3154  @kbd{C-S-Mouse-2}.  Just as for all the other mouse examine commands, it  available on @kbd{C-S-Mouse-2}.  Just as for all the other mouse
3155  permits click or drag expression selection, but instead of sending  examine commands, it permits click or drag expression selection, but
3156  hard-coded commands to the shell, it pops-up a customizable selection  instead of sending hard-coded commands to the shell, it pops-up a
3157  list of examine functions to choose among, configured with the  customizable selection list of examine functions to choose among,
3158  @code{idlwave-shell-examine-alist} variable.  This variable is a list of  configured with the @code{idlwave-shell-examine-alist}
3159  key-value pairs (an @emph{alist} in Emacs parlance), where the keys name  variable@footnote{In Electric Debug Mode (@pxref{Electric Debug
3160  the command, and the values are the command strings, in which the text  Mode}), the key @kbd{x} provides a single-character shortcut interface
3161  @code{___} (three underscores) will be replaced by the selected  to the same examine functions for the expression at point or marked by
3162  expression before being sent to the shell.  An example might be key  the region.}.  This variable is a list of key-value pairs (an
3163  @code{Structure Help} with value @code{help,___,/STRUCTURE}.  @emph{alist} in Emacs parlance), where the key gives a name to be
3164  @code{idlwave-shell-examine-alist} comes by default with a large list of  shown for the examine command, and the value is the command strings
3165  examine commands, but can be easily customized to add more.  itself, in which the text @code{___} (three underscores) will be
3166    replaced by the selected expression before being sent to the shell.
3167  In addition to the pop-up mouse command, you can easily create your own  An example might be key @code{Structure Help} with value
3168  customized bindings to inspect expressions using the two convenience  @code{help,___,/STRUCTURE}.  In that case, you'd be prompted with
3169  macros @code{idlwave-shell-inspect} and  @emph{Structure Help}, which might send something like
3170  @code{idlwave-shell-mouse-inspect}.  These create keyboard or  @code{help,var,/STRUCTURE} to the shell for output.
3171  mouse-based custom inspections of variables, sharing all the same  @code{idlwave-shell-examine-alist} comes configured by default with a
3172  properties of the built-in examine commands.  Both functions take a  large list of examine commands, but you can easily customize it to add
3173  single string argument sharing the syntax of the  your own.
3174    
3175    In addition to configuring the functions available to the pop-up mouse
3176    command, you can easily create your own customized bindings to inspect
3177    expressions using the two convenience macros
3178    @code{idlwave-shell-examine} and @code{idlwave-shell-mouse-examine}.
3179    These create keyboard or mouse-based custom inspections of variables,
3180    sharing all the same properties of the built-in examine commands.
3181    Both functions take a single string argument sharing the syntax of the
3182  @code{idlwave-shell-examine-alist} values, e.g.:  @code{idlwave-shell-examine-alist} values, e.g.:
3183    
3184  @lisp  @lisp
3185  (add-hook 'idlwave-shell-mode-hook  (add-hook 'idlwave-shell-mode-hook
3186            (lambda ()            (lambda ()
3187              (idlwave-shell-define-key-both [s-down-mouse-2]              (idlwave-shell-define-key-both [s-down-mouse-2]
3188                                   (idlwave-shell-mouse-examine                                   (idlwave-shell-mouse-examine
3189                                    "print, size(___,/DIMENSIONS)"))                                    "print, size(___,/DIMENSIONS)"))
3190              (idlwave-shell-define-key-both [f9] (idlwave-shell-examine              (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
3191                                         "print, size(___,/DIMENSIONS)"))                                         "print, size(___,/DIMENSIONS)"))
3192              (idlwave-shell-define-key-both [f10] (idlwave-shell-examine              (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
3193                                          "print,size(___,/TNAME)"))                                          "print,size(___,/TNAME)"))
3194              (idlwave-shell-define-key-both [f11] (idlwave-shell-examine              (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
3195                                          "help,___,/STRUCTURE"))))                                          "help,___,/STRUCTURE"))))
3196  @end lisp  @end lisp                                        
3197                
3198  @noindent Now pressing @key{f9}, or middle-mouse dragging with the  @noindent Now pressing @key{f9}, or middle-mouse dragging with the
3199  @key{SUPER} key depressed, will print the dimensions of the nearby or  @key{SUPER} key depressed, will print the dimensions of the nearby or
3200  highlighted expression.  Pressing @key{f10} will give the type string,  highlighted expression.  Pressing @key{f10} will give the type string,
# Line 2858  and @key{f11} will show the contents of Line 3202  and @key{f11} will show the contents of
3202  see, the possibilities are only marginally finite.  see, the possibilities are only marginally finite.
3203    
3204  @defopt idlwave-shell-examine-alist  @defopt idlwave-shell-examine-alist
3205  An alist of examine commands in which the keys name the command and are  An alist of examine commands in which the keys name the command and
3206  displayed in the selection pop-up, and the values are custom IDL examine  are displayed in the selection pop-up, and the values are custom IDL
3207  command strings to send, after all instances of @code{___} are replaced  examine command strings to send, after all instances of @code{___}
3208  by the indicated expression.  (three underscores) are replaced by the indicated expression.
3209  @end defopt  @end defopt
3210    
3211    
# Line 2872  by the indicated expression. Line 3216  by the indicated expression.
3216  @menu  @menu
3217  * Installing IDLWAVE::          How to install the distribution  * Installing IDLWAVE::          How to install the distribution
3218  * Installing Online Help::      Where to get the additional files needed  * Installing Online Help::      Where to get the additional files needed
 * Upgrading from idl.el::       Necessary configuration changes  
3219  @end menu  @end menu
3220    
3221  @node Installing IDLWAVE, Installing Online Help, Installation, Installation  @node Installing IDLWAVE, Installing Online Help, Installation, Installation
# Line 2889  IDLWAVE is part of Emacs 21.1 and later. Line 3232  IDLWAVE is part of Emacs 21.1 and later.
3232  and can be installed from  and can be installed from
3233  @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site}  @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site}
3234  with the normal package management system on XEmacs 21.  These  with the normal package management system on XEmacs 21.  These
3235  pre-installed versions should work out-of-the-box.  However, the files  pre-installed versions should work out-of-the-box.  However, the HTML
3236  required for online help are not distributed with XEmacs/Emacs and have  files required for online HTML help are not distributed with
3237  to be installed separately@footnote{Due to copyright reasons, the ASCII  XEmacs/Emacs and have to be installed separately@footnote{Due to
3238  version of the IDL manual cannot be distributed under the GPL.}  copyright reasons, the HTML version of the IDL manual cannot be
3239  (@pxref{Installing Online Help}).  distributed under the GPL.}  (@pxref{Installing Online Help}).
3240    
3241  You can also download IDLWAVE and install it yourself from  You can also download IDLWAVE and install it yourself from
3242  @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}.  Follow the  @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}.  Follow the
3243  instructions in the INSTALL file.  instructions in the INSTALL file.
3244    
3245  @node Installing Online Help, Upgrading from idl.el, Installing IDLWAVE, Installation  @node Installing Online Help,  , Installing IDLWAVE, Installation
3246  @section Installing Online Help  @section Installing Online Help
3247  @cindex Installing online help  @cindex Installing online help
3248  @cindex Online Help, Installation  @cindex Online Help, Installation
3249    
3250  If you want to use the online help display, two additional files (an  If you want to use the online help display, an additional set of files
3251  ASCII version of the IDL documentation and a topics/code file) must be  (HTML versions of the IDL documentation) must be installed.  These
3252  installed.  These files can also be downloaded from  files can also be downloaded from @uref{@value{IDLWAVE-HOMEPAGE}, the
3253  @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}.  You need to  maintainers webpage}.  You need to place the files somewhere on your
3254  place the files somewhere on your system and tell IDLWAVE where they are  system and tell IDLWAVE where they are with
 with  
   
 @lisp  
 (setq idlwave-help-directory "/path/to/help/files/")  
 @end lisp  
   
 @node Upgrading from idl.el,  , Installing Online Help, Installation  
 @section Upgrading from the old @b{@file{idl.el}} file  
 @cindex Upgrading from old @b{@file{idl.el}}  
 @cindex Renaming old variables  
 @cindex Old variables, renaming  
 @kindex M-@key{TAB}  
   
 If you have been using the old @file{idl.el} and @file{idl-shell.el}  
 files and would like to use IDLWAVE, you need to update your  
 customization in @file{.emacs}.  
3255    
 @enumerate  
 @item  
 Change all variable and function prefixes from @samp{idl-} to @samp{idlwave-}.  
 @item  
 Remove the now invalid @code{autoload} and @code{auto-mode-alist} forms  
 pointing to the @file{idl.el} and @file{idl-shell.el} files.  Install  
 the new autoload forms.  
 @item  
 If you have been using the hook function recommended in earlier versions  
 to get a separate frame for the IDL shell, remove that command from your  
 @code{idlwave-shell-mode-hook}.  Instead, set the variable  
 @code{idlwave-shell-use-dedicated-frame} with  
3256  @lisp  @lisp
3257  (setq idlwave-shell-use-dedicated-frame t)  (setq idlwave-html-help-location "/path/to/help/dir/") ;e.g. /usr/local/etc
3258  @end lisp  @end lisp
3259  @item  
3260  The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character.  Note that the help package only changes with new versions of the IDL
3261  Like in many other Emacs modes, @kbd{M-@key{TAB}} now does  documentation, and need not be updated unless your version of IDL
3262  completion.  Inserting a TAB has therefore been moved to  changes.
 @kbd{C-@key{TAB}}.  On a character based terminal you can also use  
 @kbd{C-c @key{SPC}}.  
 @end enumerate  
3263    
3264  @node Acknowledgements, Sources of Routine Info, Installation, Top  @node Acknowledgements, Sources of Routine Info, Installation, Top
3265  @chapter Acknowledgements  @chapter Acknowledgements
# Line 2973  of the package from version 3.0, during Line 3285  of the package from version 3.0, during
3285  everything, modernized IDLWAVE with many new features, and developed the  everything, modernized IDLWAVE with many new features, and developed the
3286  manual.  manual.
3287    
3288  @item  @item
3289  @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current  @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current
3290  maintainer, as of version 4.10, helped shape object method completion  maintainer, as of version 4.10, helped shape object method completion
3291  and most new features introduced in versions 4.x.  and most new features introduced in versions 4.x, and added
3292    significant new capabilities for versions 5.x.
3293  @end itemize  @end itemize
3294    
3295  @noindent  @noindent
# Line 2985  with patches, ideas, bug reports and sug Line 3298  with patches, ideas, bug reports and sug
3298    
3299  @itemize @minus  @itemize @minus
3300  @item  @item
3301  Ulrik Dickow <dickow@@nbi.dk>  Ulrik Dickow <dickow__at__nbi.dk>
3302  @item  @item
3303  Eric E. Dors <edors@@lanl.gov>  Eric E. Dors <edors__at__lanl.gov>
3304  @item  @item
3305  Stein Vidar H. Haugan <s.v.h.haugan@@astro.uio.no>  Stein Vidar H. Haugan <s.v.h.haugan__at__astro.uio.no>
3306  @item  @item
3307  David Huenemoerder <dph@@space.mit.edu>  David Huenemoerder <dph__at__space.mit.edu>
3308  @item  @item
3309  Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de>  Kevin Ivory <Kevin.Ivory__at__linmpi.mpg.de>
3310  @item  @item
3311  Dick Jackson <dick@@d-jackson.com>  Dick Jackson <dick__at__d-jackson.com>
3312  @item  @item
3313  Xuyong Liu <liu@@stsci.edu>  Xuyong Liu <liu__at__stsci.edu>
3314  @item  @item
3315  Simon Marshall <Simon.Marshall@@esrin.esa.it>  Simon Marshall <Simon.Marshall__at__esrin.esa.it>
3316  @item  @item
3317  Craig Markwardt <craigm@@cow.physics.wisc.edu>  Craig Markwardt <craigm__at__cow.physics.wisc.edu>
3318  @item  @item
3319  Laurent Mugnier <mugnier@@onera.fr>  Laurent Mugnier <mugnier__at__onera.fr>
3320  @item  @item
3321  Lubos Pochman <lubos@@rsinc.com>  Lubos Pochman <lubos__at__rsinc.com>
3322  @item  @item
3323  Bob Portmann <portmann@@al.noaa.gov>  Bob Portmann <portmann__at__al.noaa.gov>
3324  @item  @item
3325  Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov>  Patrick M. Ryan <pat__at__jaameri.gsfc.nasa.gov>
3326  @item  @item
3327  Marty Ryba <ryba@@ll.mit.edu>  Marty Ryba <ryba__at__ll.mit.edu>
3328  @item  @item
3329  Phil Williams <williams@@irc.chmcc.org>  Phil Williams <williams__at__irc.chmcc.org>
3330  @item  @item
3331  Phil Sterne <sterne@@dublin.llnl.gov>  Phil Sterne <sterne__at__dublin.llnl.gov>
3332    @item
3333    Paul Sorenson <aardvark62__at__msn.com>
3334  @end itemize  @end itemize
3335    
3336  @noindent  @noindent
3337  Thanks to everyone!  Thanks to everyone!
3338    
3339  @node Sources of Routine Info, Configuration Examples, Acknowledgements, Top  @node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top
3340  @appendix Sources of Routine Info  @appendix Sources of Routine Info
3341    
3342  @cindex Sources of routine information  @cindex Sources of routine information
# Line 3033  know about the accessible routines. Line 3348  know about the accessible routines.
3348  @menu  @menu
3349  * Routine Definitions::         Where IDL Routines are defined.  * Routine Definitions::         Where IDL Routines are defined.
3350  * Routine Information Sources::  So how does IDLWAVE know about...  * Routine Information Sources::  So how does IDLWAVE know about...
3351  * Library Catalog::             Scanning the Libraries for Routine Info  * Catalogs::                    
3352  * Load-Path Shadows::           Routines defined in several places  * Load-Path Shadows::           Routines defined in several places
3353  * Documentation Scan::          Scanning the IDL Manuals  * Documentation Scan::          Scanning the IDL Manuals
3354  @end menu  @end menu
# Line 3051  know about the accessible routines. Line 3366  know about the accessible routines.
3366  several places:  several places:
3367    
3368  @enumerate  @enumerate
3369  @item  @item
3370  @emph{Builtin routines} are defined inside IDL itself.  The source  @emph{Builtin routines} are defined inside IDL itself.  The source
3371  code of such routines is not available.  code of such routines is not available.
3372  @item  @item
3373  Routines which are @emph{part of the current program}, are defined in a  Routines which are @emph{part of the current program}, are defined in a
3374  file explicitly compiled by the user.  This file may or may not be  file explicitly compiled by the user.  This file may or may not be
3375  located on the IDL search path.  located on the IDL search path.
3376  @item  @item
3377  @emph{Library routines} are defined in files located on IDL's search  @emph{Library routines} are defined in files located on IDL's search
3378  path, and will not need to be manually compiled.  When a library routine  path, and will not need to be manually compiled.  When a library routine
3379  is called for the first time, IDL will find the source file and compile  is called for the first time, IDL will find the source file and compile
# Line 3072  or included as dynamically loaded module Line 3387  or included as dynamically loaded module
3387  cannot provide routine info and completion for such external routines.  cannot provide routine info and completion for such external routines.
3388  @end enumerate  @end enumerate
3389    
3390  @node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info  @node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info
3391  @appendixsec Routine Information Sources  @appendixsec Routine Information Sources
3392  @cindex Routine info sources  @cindex Routine info sources
3393  @cindex Builtin list of routines  @cindex Builtin list of routines
# Line 3087  routines on a system, IDLWAVE collects d Line 3402  routines on a system, IDLWAVE collects d
3402  @enumerate  @enumerate
3403    
3404  @item  @item
3405  It has a @emph{builtin list} with the properties of the builtin IDL  It has a @emph{builtin list} with information about the routines IDL
3406  routines.  IDLWAVE @value{VERSION} is distributed with a list of  ships with.  IDLWAVE @value{VERSION} is distributed with a list of
3407  @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords,  @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords,
3408  reflecting IDL version @value{IDLVERSION}.  This list has been created  reflecting IDL version @value{IDLVERSION}.  This list has been created
3409  by scanning the IDL manuals and is stored in the file  by scanning the IDL manuals and is stored in the file
3410  @file{idlw-rinfo.el}.  @xref{Documentation Scan}, for information on how  @file{idlw-rinfo.el}.  @xref{Documentation Scan}, for information on
3411  to regenerate this file for new versions of IDL.  how to regenerate this file for new versions of IDL.
3412    
3413  @item  @item
3414  It @emph{scans} all @emph{buffers} of the current Emacs session for  It @emph{scans} all @emph{buffers} of the current Emacs session for
3415  routine definitions.  This is done automatically when routine  routine definitions.  This is done automatically when routine
3416  information or completion is first requested by the user.  Each new  information or completion is first requested by the user.  Each new
3417  buffer and each buffer which is saved after making changes is also  buffer and each buffer saved after making changes is also scanned. The
3418  scanned. The command @kbd{C-c C-i} (@code{idlwave-update-routine-info})  command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used
3419  can be used at any time to rescan all buffers.  at any time to rescan all buffers.
3420    
3421  @item  @item
3422  If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will  If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will
# Line 3113  requested by the user, and each time an Line 3428  requested by the user, and each time an
3428  routine data.  routine data.
3429    
3430  @item  @item
3431  IDLWAVE can scan all or selected library source files and store the  Many popular libraries are distributed with routine information
3432  result in a file which will be automatically loaded just like  already scanned into @emph{library catalogs} (@pxref{Library
3433  @file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to  Catalogs}).  These per-directory catalog files can also be built by
3434  scan library files.  the user with the supplied @file{idlwave_catalog} tool.
3435    
3436    @item
3437    IDLWAVE can scan selected directories of source files and store the
3438    result in a single @emph{user catalog} file which will be
3439    automatically loaded just like @file{idlw-rinfo.el}. @xref{User
3440    Catalog}, for information on how to scan files in this way.
3441  @end enumerate  @end enumerate
3442    
3443  Loading routine and catalog information is a time consuming process.  Loading routine and catalog information can be a time consuming process,
3444  Depending on the system and network configuration it can take up to 30  especially over slow networks.  Depending on the system and network
3445  seconds.  In order to minimize the waiting time upon your first  configuration it could take up to 30 seconds.  In order to minimize the
3446  completion or routine info command in a session, IDLWAVE uses Emacs idle  wait time upon your first completion or routine info command in a
3447  time to do the initialization in 5 steps, yielding to user input in  session, IDLWAVE uses Emacs idle time to do the initialization in six
3448  between.  If this gets into your way, set the variable  steps, yielding to user input in between.  If this gets into your way,
3449  @code{idlwave-init-rinfo-when-idle-after} to 0 (zero).  set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero).
3450    The more routines documented in library and user catalogs, the slower
3451    the loading will be, so reducing this number can help alleviate any long
3452    load times.
3453    
3454  @defopt idlwave-init-rinfo-when-idle-after (@code{10})  @defopt idlwave-init-rinfo-when-idle-after (@code{10})
3455  Seconds of idle time before routine info is automatically initialized.  Seconds of idle time before routine info is automatically initialized.
# Line 3144  Non-@code{nil} means query the shell for Line 3468  Non-@code{nil} means query the shell for
3468  Controls under what circumstances routine info is updated automatically.  Controls under what circumstances routine info is updated automatically.
3469  @end defopt  @end defopt
3470    
3471  @node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info  @ifhtml
3472  @appendixsec Library Catalog  <A NAME="CATALOGS"></A>
3473  @cindex Library scan  @end ifhtml
3474  @cindex Library catalog  @node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
3475    @appendixsec Catalogs
3476    @cindex Catalogs
3477    
3478    @emph{Catalogs} are files containing scanned information on individual
3479    routines, including arguments and keywords, calling sequence, file path,
3480    class and procedure vs. function type, etc.  They represent a way of
3481    extending the internal built-in information available for IDL system
3482    routines (@pxref{Routine Info}) to other source collections.
3483    
3484    Starting with version 5.0, there are two types of catalogs available
3485    with IDLWAVE.  The traditional @emph{user catalog} and the newer
3486    @emph{library catalogs}.  Although they can be used interchangeably, the
3487    library catalogs are more flexible, and preferred.  There are few
3488    occasions when a user catalog might be preferred --- read below.  Both
3489    types of catalogs can coexist without causing problems.
3490    
3491    To facilitate the catalog systems, IDLWAVE stores information it gathers
3492    from the shell about the IDL search paths, and can write this
3493    information out automatically, or on-demand (menu @code{Debug->Save Path
3494    Info}).  On systems with no shell from which to discover the path
3495    information (e.g. Windows), a library path must be specified in
3496    @code{idlwave-library-path} to allow library catalogs to be located, and
3497    to setup directories for user catalog scan (@pxref{User Catalog} for
3498    more on this variable).
3499    
3500    @defopt idlwave-auto-write-path  (@code{t})
3501    Write out information on the !PATH and !DIR paths from IDL automatically
3502    when they change and when the Shell is closed.  These paths are needed
3503    to locate library catalogs.
3504    @end defopt
3505    
3506    @defopt idlwave-library-path
3507    IDL library path for Windows and MacOS.  Not needed under Unix/MacOSX.
3508    @end defopt
3509    
3510    @defopt idlwave-system-directory
3511    The IDL system directory for Windows and MacOS.  Not needed under
3512    Unix/MacOSX (obtained from the Shell).
3513    @end defopt
3514    
3515    @defopt idlwave-config-directory (@file{~/.idlwave})
3516    Default path where IDLWAVE saves configuration information and any
3517    user catalog.
3518    @end defopt
3519    
3520    @menu
3521    * Library Catalogs::            
3522    * User Catalog::                
3523    @end menu
3524    
3525    @ifhtml
3526    <A NAME="LIBRARY_CATALOGS"></A>
3527    @end ifhtml
3528    @node Library Catalogs, User Catalog, Catalogs, Catalogs
3529    @appendixsubsec Library Catalogs
3530    @cindex @file{.idlwave_catalog}
3531    @cindex Library catalogs
3532    @cindex @code{idlwave_catalog}
3533    
3534    Library catalogs are files named @file{.idlwave_catalog} stored in
3535    directories containing @code{.pro} routine files.  They are discovered
3536    on the IDL search path and loaded automatically when routine information
3537    is read.  Each catalog file documents the routines found in that
3538    directory --- one catalog per directory.  Every catalog has a library
3539    name associated with it (e.g. @emph{AstroLib}).  This name will be shown
3540    briefly when the catalog is found, and in the routine info of routines
3541    it documents.
3542    
3543    Many popular libraries of routines are shipped with IDLWAVE catalog
3544    files by default, and so will be automatically discovered.  Library
3545    catalogs are scanned externally to Emacs using a tool provided with
3546    IDLWAVE.  Each catalog can be re-scanned independently of any other.
3547    Catalogs can easily be made available system-wide with a common source
3548    repository, providing uniform routine information, and lifting the
3549    burden of scanning from the user (who may not even know they're using a
3550    scanned catalog).  Since all catalogs are independent, they can be
3551    re-scanned automatically to gather updates, e.g. in a @file{cron} job.
3552    Scanning is much faster than with the built-in user catalog method.  One
3553    minor disadvantage: the entire IDL search path is scanned for catalog
3554    files every time IDLWAVE starts up, which might be slow over a network.
3555    
3556    A Perl tool to create library catalogs is distributed with IDLWAVE:
3557    @code{idlwave_catalog}.  It can be called quite simply:
3558    @example
3559    idlwave_catalog MyLib
3560    @end example
3561    
3562    @noindent This would scan all directories recursively beneath the current and
3563    populate them with @file{.idlwave_catalog} files, tagging the routines
3564    found with the name library ``MyLib''.  The full usage information:
3565    
3566    @example
3567    Usage: idlwave_catalog  [-l] [-v] [-d] [-s] [-f] [-h] libname
3568           libname - Unique name of the catalog (4 or more alphanumeric
3569                     characters).
3570                -l - Scan local directory only, otherwise recursively
3571                     catalog all directories at or beneath this one.
3572                -v - Print verbose information.
3573                -d - Instead of scanning, delete all .idlwave_catalog files
3574                     here or below.
3575                -s - Be silent.
3576                -f - Force overwriting any catalogs found with a different
3577                     library name.
3578                -h - Print this usage.
3579    @end example
3580    
3581    To re-load the library catalogs on the IDL path, force a system routine
3582    info update using a single prefix to @code{idlwave-update-routine-info}:
3583    @kbd{C-u C-c C-i}.
3584    
3585    @defopt idlwave-use-library-catalogs  (@code{t})
3586    Whether to search for and load library catalogs.  Only disable if
3587    performance is a problem and the catalogs are not needed.
3588    @end defopt
3589    
3590    @node User Catalog,  , Library Catalogs, Catalogs
3591    @appendixsubsec User Catalog
3592    @cindex User catalog
3593  @cindex IDL library routine info  @cindex IDL library routine info
3594  @cindex Windows  @cindex Windows
3595  @cindex MacOS  @cindex MacOS
3596  @cindex IDL variable @code{!DIR}  @cindex IDL variable @code{!DIR}
3597  @cindex @code{!DIR}, IDL variable  @cindex @code{!DIR}, IDL variable
3598    
3599    The user catalog is the old routine catalog system.  It is produced
3600    within Emacs, and stored in a single file in the user's home directory
3601    (@file{.idlwave/idlusercat.el} by default).  Although library catalogs
3602    are more flexible, there may be reasons to prefer a user catalog
3603    instead, including:
3604    
3605  IDLWAVE can extract routine information from library modules and store  @itemize @bullet
3606  that information in a file.  To do this, the variable  @item The scan is internal to Emacs, so you don't need a working Perl
3607  @code{idlwave-libinfo-file} needs to contain the path to a file in an  installation, as you do for library catalogs.
3608  existing directory (the default is @code{"~/.idlcat.el"}).  Since the  @item Can be used to scan directories for which the user has no write
3609  file will contain lisp code, its name should end in @file{.el}.  Under  privileges.
3610  Windows and MacOS, you also need to specify the search path for IDL  @item Easy widget-based path selection.
3611  library files in the variable @code{idlwave-library-path}, and the  @end itemize
3612  location of the IDL directory (the value of the @code{!DIR} system  
3613  variable) in the variable @code{idlwave-system-directory}, like  However, no routine info is available in the user catalog by default;
3614  this@footnote{The initial @samp{+} leads to recursive expansion of the  the user must actively complete a scan.  In addition, this type of
3615  path, just like in IDL}:  catalog is all or nothing: if a single routine changes, the entire
3616    catalog must be rescanned to update it.  Creating the user catalog is
3617    also much slower than scanning library catalogs.
3618    
3619    You can scan any of the directories on the currently known path.  Under
3620    Windows and MacOS (not OSX), you need to specify the IDL search path in
3621    the variable @code{idlwave-library-path}, and the location of the IDL
3622    directory (the value of the @code{!DIR} system variable) in the variable
3623    @code{idlwave-system-directory}, like this@footnote{The initial @samp{+}
3624    leads to recursive expansion of the path, just like in IDL}:
3625    
3626  @lisp  @lisp
3627  (setq idlwave-library-path  (setq idlwave-library-path
3628          '("+c:/RSI/IDL54/lib/" "+c:/user/me/idllibs" ))          '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs"))
3629  (setq idlwave-system-directory "c:/RSI/IDL54/")  (setq idlwave-system-directory "c:/RSI/IDL56/")
3630  @end lisp  @end lisp
3631    
3632  @noindent Under GNU and UNIX, these values will be automatically inferred from  @noindent Under GNU and UNIX, these values will be automatically gathered from
3633  an IDLWAVE shell.  the IDLWAVE shell.
3634    
3635  The command @kbd{M-x idlwave-create-libinfo-file} can then be used to  The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item
3636  scan library files.  It brings up a widget in which you can select some  @samp{IDLWAVE->Routine Info->Select Catalog Directories} can then be
3637  or all directories on the search path.  If you only want to have routine  used to create a user catalog.  It brings up a widget in which you can
3638  and completion info of some libraries, it is sufficient to scan those  select some or all directories on the search path.  Directories which
3639  directories.  However, if you want IDLWAVE to detect possible name  already contain a library catalog are marked with @samp{[LIB]}, and need
3640  conflicts with routines defined in other libraries, the whole pass  not be scanned (although there is no harm if you do so, other than the
3641  should be scanned.  additional memory used for the duplication).
3642    
3643  After selecting directories, click on the @w{@samp{[Scan & Save]}}  After selecting directories, click on the @w{@samp{[Scan & Save]}}
3644  button in the widget to scan all files in the selected directories and  button in the widget to scan all files in the selected directories and
3645  write the resulting routine information into the file  write out the resulting routine information.  In order to update the
3646  @code{idlwave-libinfo-file}.  In order to update the library information  library information using the directory selection, call the command
 from the same directories, call the command  
3647  @code{idlwave-update-routine-info} with a double prefix argument:  @code{idlwave-update-routine-info} with a double prefix argument:
3648  @w{@kbd{C-u C-u C-c C-i}}.  This will rescan files in the previously  @w{@kbd{C-u C-u C-c C-i}}.  This will rescan files in the previously
3649  selected directories, write an updated version of the libinfo file and  selected directories, write an updated version of the user catalog file
3650  rebuild IDLWAVE's internal lists.  If you give three prefix arguments  and rebuild IDLWAVE's internal lists.  If you give three prefix
3651  @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a background  arguments @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a
3652  job@footnote{Unix systems only, I think.}.  You can continue to work,  background job@footnote{Unix systems only, I think.}.  You can continue
3653  and the library catalog will be re-read when it is ready.  to work, and the library catalog will be re-read when it is ready.  If
3654    you find you need to update the user catalog often, you should consider
3655  A note of caution:  Depending on your local installation, the IDL  building a library catalog for your routines instead (@pxref{Library
3656  library can be very large.  Parsing it for routine information will take  Catalogs}).
 time and loading this information into Emacs can require a  
 significant amount of memory.  However, having this information  
 available will be a great help.  
   
 @defopt idlwave-libinfo-file  
 File for routine information of the IDL library.  
 @end defopt  
   
 @defopt idlwave-library-path  
 IDL library path for Windows and MacOS.  Not needed under Unix.  
 @end defopt  
   
 @defopt idlwave-system-directory  
 The IDL system directory for Windows and MacOS.  Not needed under Unix.  
 @end defopt  
3657    
3658  @defopt idlwave-special-lib-alist  @defopt idlwave-special-lib-alist
3659  Alist of regular expressions matching special library directories.  Alist of regular expressions matching special library directories for
3660    labeling in routine-info display.
3661  @end defopt  @end defopt
3662    
3663  @node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info  @node Load-Path Shadows, Documentation Scan, Catalogs, Sources of Routine Info
3664  @appendixsec Load-Path Shadows  @appendixsec Load-Path Shadows
3665  @cindex Load-path shadows  @cindex Load-path shadows
3666  @cindex Shadows, load-path  @cindex Shadows, load-path
# Line 3229  Alist of regular expressions matching sp Line 3670  Alist of regular expressions matching sp
3670  @cindex Application, testing for shadowing  @cindex Application, testing for shadowing
3671  @cindex Buffer, testing for shadowing  @cindex Buffer, testing for shadowing
3672    
3673  IDLWAVE can compile a list of routines which are defined in several  IDLWAVE can compile a list of routines which are (re-)defined in more
3674  different files.  Since one definition will hide (shadow) the others  than one file.  Since one definition will hide (shadow) the others
3675  depending on which file is compiled first, such multiple definitions are  depending on which file is compiled first, such multiple definitions are
3676  called "load-path shadows".  IDLWAVE has several routines to scan for  called "load-path shadows".  IDLWAVE has several routines to scan for
3677  load path shadows.  The output is placed into the special buffer  load path shadows.  The output is placed into the special buffer
3678  @file{*Shadows*}.  The format of the output is identical to the source  @file{*Shadows*}.  The format of the output is identical to the source
3679  section of the routine info buffer (@pxref{Routine Info}).  The  section of the routine info buffer (@pxref{Routine Info}).  The
3680  different definitions of a routine are listed in the sequence of  different definitions of a routine are ordered by @emph{likelihood of
3681  @emph{likelihood of use}.  So the first entry will be most likely the  use}.  So the first entry will be most likely the one you'll get if an
3682  one you'll get if an unsuspecting command uses that routine.  Before  unsuspecting command uses that routine.  Before listing shadows, you
3683  listing shadows, you should make sure that routine info is up-to-date by  should make sure that routine info is up-to-date by pressing @kbd{C-c
3684  pressing @kbd{C-c C-i}.  Here are the different routines:  C-i}.  Here are the different routines (also available in the Menu
3685    @samp{IDLWAVE->Routine Info}):
3686    
3687  @table @asis  @table @asis
3688  @item @kbd{M-x idlwave-list-buffer-load-path-shadows}  @item @kbd{M-x idlwave-list-buffer-load-path-shadows}
# Line 3257  then check for shadowing. Line 3699  then check for shadowing.
3699  This command checks all routines accessible to IDLWAVE for conflicts.  This command checks all routines accessible to IDLWAVE for conflicts.
3700  @end table  @end table
3701    
3702  For these commands to work properly you should have scanned the entire  For these commands to work fully you need to scan the entire load path
3703  load path, not just selected directories.  Also, IDLWAVE should be able  in either a user or library catalog.  Also, IDLWAVE should be able to
3704  to distinguish between the system library files (normally installed in  distinguish between the system library files (normally installed in
3705  @file{/usr/local/rsi/idl/lib}) and any site specific or user specific  @file{/usr/local/rsi/idl/lib}) and any site specific or user specific
3706  files.  Therefore, such local files should not be installed inside the  files.  Therefore, such local files should not be installed inside the
3707  @file{lib} directory of the IDL directory.  This is also advisable for  @file{lib} directory of the IDL directory.  This is also advisable for
# Line 3279  Another way to find out if a specific ro Line 3721  Another way to find out if a specific ro
3721  on the load path is routine info display (@pxref{Routine Info}).  on the load path is routine info display (@pxref{Routine Info}).
3722    
3723  @node Documentation Scan,  , Load-Path Shadows, Sources of Routine Info  @node Documentation Scan,  , Load-Path Shadows, Sources of Routine Info
3724  @appendixsec Documentation Scan  @appendixsec Documentation Scan
3725  @cindex @file{get_rinfo}  @cindex @file{get_html_rinfo}
3726  @cindex @file{idlw-rinfo.el}  @cindex @file{idlw-rinfo.el}
 @cindex @file{idlw-help.txt}  
 @cindex @file{idlw-help.el}  
3727  @cindex Scanning the documentation  @cindex Scanning the documentation
3728  @cindex Perl program, to create @file{idlw-rinfo.el}  @cindex Perl program, to create @file{idlw-rinfo.el}
3729    
3730  IDLWAVE derives it knowledge about system routines from the IDL  IDLWAVE derives its knowledge about system routines from the IDL
3731  manuals.  The file @file{idlw-rinfo.el} contains the routine information  manuals.  The file @file{idlw-rinfo.el} contains the routine information
3732  for the IDL system routines.  The Online Help feature of IDLWAVE  for the IDL system routines, and links to relevant sections of the HTML
3733  requires ASCII versions of some IDL manuals to be available in a  documentation.  The Online Help feature of IDLWAVE requires HTML
3734  specific format (@file{idlw-help.txt}), along with an Emacs-Lisp file  versions of the IDL manuals to be available; the HTML documentation is
3735  @file{idlw-help.el} with supporting code and pointers to the ASCII file.  not distributed with IDLWAVE by default, but must be downloaded
3736    separately from the @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers
3737  All 3 files can be derived from the IDL documentation.  If you are  webpage}.
3738  lucky, the maintainer of IDLWAVE will always have access to the newest  
3739  version of IDL and provide updates.  The IDLWAVE distribution also  The HTML files and related images can be produced from the
3740  contains the Perl program @file{get_rinfo} which constructs these files  @file{idl.chm} HTMLHelp file distributed with IDL using the free
3741  by scanning selected files from the IDL documentation.  Instructions on  Microsoft HTML Help Workshop.  If you are lucky, the maintainer of
3742  how to use @file{get_rinfo} are in the program itself.  IDLWAVE will always have access to the newest version of IDL and
3743    provide updates.  The IDLWAVE distribution also contains the Perl
3744  One particularly frustrating situation occurs when a new IDL version is  program @file{get_html_rinfo} which constructs the
3745  released without the associated documentation updates.  Instead, a  @file{idlw-rinfo.el} file by scanning the HTML documents produced from
3746  @emph{What's New} file containing new and updated documentation is  the IDL documentation.  Instructions on how to use
3747  shipped alongside the previous version's reference material.  The  @file{get_html_rinfo} are in the program itself.
3748  @file{get_rinfo} script can merge this new information into the standard  
3749  help text and routine information, as long as it is pre-formatted in a  @node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top
3750  simple way.  See @file{get_rinfo} for more information.  @appendix HTML Help Browser Tips
3751    @cindex Browser Tips
3752    
3753    There are a wide variety of possible browsers to use for displaying
3754    the online HTML help available with IDLWAVE (starting with version
3755    5.0).  Since IDLWAVE runs on a many different system types, a single
3756    browser configuration is not possible, but choices abound.
3757    
3758    On many systems, the default browser configured in
3759    @code{browse-url-browser-function}, and hence inherited by default by
3760    @code{idlwave-help-browser-function}, is Netscape.  Unfortunately, the
3761    HTML manuals decompiled from the original RSI source contain
3762    formatting structures which Netscape 4.x does not handle well, though
3763    they are still readable.  A much better choice is Mozilla, or one of
3764    the Mozilla-derived browsers such as
3765    @uref{http://galeon.sourceforge.net/,Galeon} (Linux),
3766    @uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or
3767    @uref{http://www.mozilla.org/projects/firebird/,Firebird} (all
3768    platforms).  Newer versions of Emacs provide a browser-function choice
3769    @code{browse-url-gnome-moz} which uses the Gnome-configured browser.
3770    
3771    Note that the HTML files decompiled from RSI Microsoft Help sources
3772    contain specific references to the @samp{Symbol} font, which by default
3773    is not permitted in normal encodings (it's technically illegal).  Though
3774    it only impacts a few symbols, you can trick Mozilla-based browsers into
3775    recognizing @samp{Symbol} by following the directions
3776    @uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}.  With this
3777    fix in place, HTML help pages look almost identical to their PDF
3778    equivalents (yet can be bookmarked, browsed as history, searched, etc.).
3779    
3780    @noindent Individual platform recommendations:
3781    
3782    @itemize @bullet
3783    @item Windows: The native Microsoft HTMLHelp browser is preferred,
3784    with even better results using the free
3785    @uref{http://www.keyworks.net/keyhh.htm,@code{KEYHH}} program to
3786    permit IDL help to be targetted to a single window.  To use HTMLHelp,
3787    specify @code{idlwave-help-use-hh} as @code{'hh} or @code{'keyhh}.
3788    One bonus: since IDL is shipped with the @file{idl.chm} help file, you
3789    don't need to download the HTML help package.  @xref{Help with HTML
3790    Documentation}.
3791    @item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser
3792    and its associated
3793    @uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode
3794    provide in-buffer browsing with image display, and excellent speed and
3795    formatting.  Both the Emacs mode and the browser itself must be
3796    downloaded separately.  To use this browser, include
3797    
3798    @lisp
3799    (setq idlwave-help-browser-function 'w3m-browse-url)
3800    @end lisp
3801    
3802  @node Configuration Examples, Windows and MacOS, Sources of Routine Info, Top  in your @file{.emacs}.  Setting a few other nice @code{w3m} options
3803    cuts down on screen clutter:
3804    
3805    @lisp
3806    (setq w3m-use-tab nil
3807          w3m-use-header-line nil
3808          w3m-use-toolbar nil)
3809    @end lisp
3810    
3811    If you use a dedicated frame for help, you might want to add the
3812    following, to get consistent behavior with the @kbd{q} key:
3813    
3814    @lisp
3815    ;; Close my help window when w3m closes.
3816    (defadvice w3m-close-window (after idlwave-close activate)
3817      (if (boundp 'idlwave-help-frame)
3818          (idlwave-help-quit)))
3819    @end lisp
3820    
3821    Note that you can open the file in an external browser from within
3822    @code{w3m} using @kbd{M}.
3823    @end itemize
3824    
3825    @node Configuration Examples, Windows and MacOS, HTML Help Browser Tips, Top
3826  @appendix Configuration Examples  @appendix Configuration Examples
3827  @cindex Configuration examples  @cindex Configuration examples
3828  @cindex Example configuration  @cindex Example configuration
# Line 3370  user is King! Line 3883  user is King!
3883  (setq idlwave-main-block-indent 3)  (setq idlwave-main-block-indent 3)
3884  (setq idlwave-end-offset -3)  (setq idlwave-end-offset -3)
3885  (setq idlwave-continuation-indent 1)  (setq idlwave-continuation-indent 1)
3886  (setq idlwave-begin-line-comment "^;[^;]")  ; Leave ";" but not ";;"  (setq idlwave-begin-line-comment "^;[^;]")  ; Leave ";" but not ";;"
3887                                              ; anchored at start of line.                                              ; anchored at start of line.
3888  (setq idlwave-surround-by-blank t)      ; Turn on padding ops =,<,>  (setq idlwave-surround-by-blank t)      ; Turn on padding ops =,<,>
3889  (setq idlwave-pad-keyword nil)          ; Remove spaces for keyword '='  (setq idlwave-pad-keyword nil)          ; Remove spaces for keyword '='
# Line 3388  user is King! Line 3901  user is King!
3901                              ("SETPROPERTY" .t)                              ("SETPROPERTY" .t)
3902                              ("GETPROPERTY" .t)))                              ("GETPROPERTY" .t)))
3903    
3904    ;; Using w3m for help (must install w3m and emacs-w3m)
3905    (autoload 'w3m-browse-url "w3m" "Interface for w3m on Emacs." t)
3906    (setq idlwave-help-browser-function 'w3m-browse-url
3907          w3m-use-tab nil ; no tabs, location line, or toolbar
3908          w3m-use-header-line nil
3909          w3m-use-toolbar nil)
3910    
3911    ;; Close my help window or frame when w3m closes with `q'
3912    (defadvice w3m-close-window (after idlwave-close activate)
3913      (if (boundp 'idlwave-help-frame)
3914          (idlwave-help-quit)))
3915    
3916  ;; Some setting can only be done from a mode hook.  Here is an example:  ;; Some setting can only be done from a mode hook.  Here is an example:
3917  (add-hook 'idlwave-mode-hook  (add-hook 'idlwave-mode-hook
3918    (lambda ()    (lambda ()
# Line 3395  user is King! Line 3920  user is King!
3920      ;; Run other functions here      ;; Run other functions here
3921      (font-lock-mode 1)                   ; Turn on font-lock mode      (font-lock-mode 1)                   ; Turn on font-lock mode
3922      (idlwave-auto-fill-mode 0)           ; Turn off auto filling      (idlwave-auto-fill-mode 0)           ; Turn off auto filling
3923        (setq idlwave-help-browser-function 'browse-url-w3)
3924    
3925      ;; Pad with 1 space (if -n is used then make the      ;; Pad with 1 space (if -n is used then make the
3926      ;; padding a minimum of n spaces.)  The defaults use -1      ;; padding a minimum of n spaces.)  The defaults use -1
# Line 3424  user is King! Line 3950  user is King!
3950      ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference.      ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference.
3951    
3952      ;; Some personal abbreviations      ;; Some personal abbreviations
3953      (define-abbrev idlwave-mode-abbrev-table      (define-abbrev idlwave-mode-abbrev-table  
3954        (concat idlwave-abbrev-start-char "wb") "widget_base()"        (concat idlwave-abbrev-start-char "wb") "widget_base()"
3955        (idlwave-keyword-abbrev 1))        (idlwave-keyword-abbrev 1))
3956      (define-abbrev idlwave-mode-abbrev-table      (define-abbrev idlwave-mode-abbrev-table  
3957        (concat idlwave-abbrev-start-char "on") "obj_new()"        (concat idlwave-abbrev-start-char "on") "obj_new()"
3958        (idlwave-keyword-abbrev 1))        (idlwave-keyword-abbrev 1))
3959      ))      ))
# Line 3445  user is King! Line 3971  user is King!
3971  (add-hook 'idlwave-shell-mode-hook  (add-hook 'idlwave-shell-mode-hook
3972            (lambda ()            (lambda ()
3973              ;; Set up some custom key and mouse examine commands              ;; Set up some custom key and mouse examine commands
3974              (idlwave-shell-define-key-both [s-down-mouse-2]              (idlwave-shell-define-key-both [s-down-mouse-2]
3975                                   (idlwave-shell-mouse-examine                                   (idlwave-shell-mouse-examine
3976                                    "print, size(___,/DIMENSIONS)"))                                    "print, size(___,/DIMENSIONS)"))
3977              (idlwave-shell-define-key-both [f9] (idlwave-shell-examine              (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
3978                                         "print, size(___,/DIMENSIONS)"))                                         "print, size(___,/DIMENSIONS)"))
3979              (idlwave-shell-define-key-both [f10] (idlwave-shell-examine              (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
3980                                          "print,size(___,/TNAME)"))                                          "print,size(___,/TNAME)"))
3981              (idlwave-shell-define-key-both [f11] (idlwave-shell-examine              (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
3982                                          "help,___,/STRUCTURE"))))                                          "help,___,/STRUCTURE"))))
# Line 3459  user is King! Line 3985  user is King!
3985  @ifhtml  @ifhtml
3986  <A NAME="WIN_MAC"></A>  <A NAME="WIN_MAC"></A>
3987  @end ifhtml  @end ifhtml
3988  @node Windows and MacOS, Index, Configuration Examples, Top  @node Windows and MacOS, Troubleshooting, Configuration Examples, Top
3989  @appendix Windows and MacOS  @appendix Windows and MacOS
3990  @cindex Windows  @cindex Windows
3991  @cindex MacOS  @cindex MacOS
3992    @cindex MacOSX
3993    
3994  IDLWAVE was developed on a UNIX system.  However, due to the portability  IDLWAVE was developed on a UNIX system.  However, thanks to the
3995  of Emacs, much of IDLWAVE does also work under different operating  portability of Emacs, much of IDLWAVE does also work under different
3996  systems like Windows (with NTEmacs or NTXEmacs) or MacOS.  operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS.
3997    
3998  The only problem really is that RSI does not provide a command-line  The only real problem is that RSI does not provide a command-line
3999  version of IDL for Windows or MacOS with which IDLWAVE can  version of IDL for Windows or MacOS(<=9) with which IDLWAVE can
4000  interact@footnote{Call your RSI representative and complain --- it  interact@footnote{Call your RSI representative and complain --- it
4001  should be trivial for them to provide one.  And if enough people ask  should be trivial for them to provide one.  And if enough people ask for
4002  for it, maybe they will.  The upcoming IDL for Mac OSX is slated to  it, maybe they will.  The new MacOSX version of IDL @emph{does} have a
4003  have a command-line version.}.  Therefore the IDLWAVE Shell does not  shell and works well with IDLWAVE.}.  As a result, the IDLWAVE Shell
4004  work and you have to rely on IDLDE to run and debug your programs.  does not work and you have to rely on IDLDE to run and debug your
4005  However, editing IDL source files with Emacs/IDLWAVE works with all  programs.  However, editing IDL source files with Emacs/IDLWAVE works
4006  bells and whistles, including routine info, completion and fast online  with all bells and whistles, including routine info, completion and fast
4007  help.  Only a small amount of additional information must be specified  online help.  Only a small amount of additional information must be
4008  in your .emacs file: the path names which, on a UNIX system, are  specified in your @file{.emacs} file: the path names which, on a UNIX
4009  automatically gathered by talking to the IDL program.  system, are automatically gathered by talking to the IDL program.
4010    
4011  Here is an example of the additional configuration needed for a Windows  Here is an example of the additional configuration needed for a Windows
4012  system.  I am assuming that IDLWAVE has been installed in  system.  I am assuming that IDLWAVE has been installed in
# Line 3487  system.  I am assuming that IDLWAVE has Line 4014  system.  I am assuming that IDLWAVE has
4014  @w{@samp{C:\RSI\IDL55}}.  @w{@samp{C:\RSI\IDL55}}.
4015    
4016  @lisp  @lisp
4017  ;; location of the lisp files (needed if IDLWAVE is not part of  ;; location of the lisp files (needed if IDLWAVE is not part of
4018  ;; the X/Emacs installation)  ;; the X/Emacs installation)
4019  (setq load-path (cons "c:/program files/IDLWAVE" load-path))  (setq load-path (cons "c:/program files/IDLWAVE" load-path))
4020    
# Line 3499  system.  I am assuming that IDLWAVE has Line 4026  system.  I am assuming that IDLWAVE has
4026  ;; location of the IDL system directory (try "print,!DIR")  ;; location of the IDL system directory (try "print,!DIR")
4027  (setq idlwave-system-directory "c:/RSI/IDL55/")  (setq idlwave-system-directory "c:/RSI/IDL55/")
4028    
4029  ;; location of the IDLWAVE help files idlw-help.el and idlw-help.txt.  ;; specify using the HTMLHelp documentation for online help, with the
4030  (setq idlwave-help-directory "c:/IDLWAVE")  ;;  KEYHH helper routine (Windows only)
4031    (setq idlwave-use-hh 'keyhh)
4032    
4033  ;; file in which to store the user catalog info  ;; file in which to store the user catalog info
4034  (setq idlwave-libinfo-file "c:/IDLWAVE/idlcat.el")  (setq idlwave-user-catalog-file "c:/IDLWAVE/idlcat.el")
4035  @end lisp  @end lisp
4036    
4037  @noindent Furthermore, Windows sometimes tries to outsmart you --- make  @noindent Furthermore, Windows sometimes tries to outsmart you --- make
4038  sure you check the following things:  sure you check the following things:
4039    
4040  @itemize @bullet  @itemize @bullet
4041  @item When you download the IDLWAVE distribution, make sure you save the  @item When you download the IDLWAVE distribution, make sure you save the
4042  files under the names @file{idlwave.tar.gz} and  file under the names @file{idlwave.tar.gz}.
 @file{idlwave-help-tar.gz}.  
 @item Be sure that your software for untarring/ungzipping is @emph{NOT}  
 doing smart CR/LF conversion (WinZip users will find this in  
 Options:Configuration:Miscellaneous, change the setting, then re-open  
 the archive).  This adds one byte per line, throwing off the  
 byte-counts for the help file lookups and defeating fast online help lookup.  
4043  @item M-TAB switches among running programs --- use Esc-TAB  @item M-TAB switches among running programs --- use Esc-TAB
4044  instead.  instead.
4045  @item Other issues as yet unnamed...  @item Other issues as yet unnamed...
4046  @end itemize  @end itemize
4047    
4048    Windows users who'd like to make use of IDLWAVE's context-aware HTML
4049    help can skip the browser and use the HTMLHelp functionality directly.
4050    @xref{Help with HTML Documentation}.
4051    
4052    @ifhtml
4053    <A NAME="TROUBLE"></A>
4054    @end ifhtml
4055    @node Troubleshooting, Index, Windows and MacOS, Top
4056    @appendix Troubleshooting
4057    @cindex Troubleshooting
4058    
4059    Although IDLWAVE usually installs and works without difficulty, a few
4060    common problems and their solutions are documented below.
4061    
4062    @enumerate
4063    
4064    @item @strong{Whenever an IDL error occurs or a breakpoint is hit, I get
4065    errors or strange behavior when I try to type anything into some of my
4066    IDLWAVE buffers.}
4067    
4068    This is a @emph{feature}, not an error.  You're in @emph{Electric
4069    Debug Mode} (@pxref{Electric Debug Mode}).  You should see
4070    @code{*Debugging*} in the mode-line.  The buffer is read-only and all
4071    debugging and examination commands are available as single keystrokes;
4072    @kbd{C-?} lists these shortcuts.  Use @kbd{q} to quit the mode, and
4073    customize the variable @code{idlwave-shell-automatic-electric-debug}
4074    if you prefer not to enter electric debug on breakpoints@dots{} but
4075    you really should try it before you disable it!  You can also
4076    customize this variable to enter debug mode when errors are
4077    encountered too.  
4078    
4079    @item @strong{I get errors like @samp{Searching for program: no such
4080    file or directory, idl} when attempting to start the IDL shell.}
4081    
4082    IDLWAVE needs to know where IDL is in order to run it as a process.
4083    By default, it attempts to invoke it simply as @samp{idl}, which
4084    presumes such an executable is on your search path.  You need to
4085    ensure @samp{idl} is on your @samp{$PATH}, or specify the full
4086    pathname to the idl program with the variable
4087    @code{idlwave-shell-explicit-file-name}.  Note that you may need to
4088    set your shell search path in two places when running Emacs as an Aqua
4089    application with MacOSX; see the next topic.
4090    
4091    @item @strong{IDLWAVE is disregarding my @samp{IDL_PATH} which I set
4092    under MacOSX}
4093    
4094    If you run Emacs directly as an Aqua application, rather than from the
4095    console shell, the environment is set not from your usual shell
4096    configuration files (e.g. @file{.cshrc}), but from the file
4097    @file{~/.MacOSX/environment.plist}.  Either include your path settings
4098    there, or start Emacs and IDLWAVE from the shell.
4099    
4100    @item @strong{I get errors like @samp{Symbol's function is void:
4101    overlayp} when trying to start the shell in XEmacs}
4102    
4103    You don't have the @samp{fsf-compat} package installed, which IDLWAVE
4104    needs to run under XEmacs.  Install it and, if necessary, insert
4105    @code{(require 'overlay)} in your @file{.emacs}.
4106    
4107    @item @strong{I'm getting errors like @samp{Symbol's value as variable is void:
4108    cl-builtin-gethash} on completion or routine info.}
4109    
4110    This error arises if you upgraded Emacs from 20.x to 21.x without
4111    re-installing IDLWAVE.  Old Emacs and new Emacs are not byte-compatible
4112    in compiled lisp files.  Presumably, you kept the original .elc files in
4113    place, and this is the source of the error.  If you recompile (or just
4114    "make; make install") from source, it should resolve this problem.
4115    Another option is to recompile the @file{idlw*.el} files by hand using
4116    @kbd{M-x byte-compile-file}.  Why not take the opportunity to grab the
4117    latest IDLWAVE version at @uref{@value{IDLWAVE-HOMEPAGE}, the
4118    maintainers webpage}
4119    
4120    @item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches
4121    windows on my desktop.}
4122    
4123    Your system is trapping @kbd{M-@key{TAB}} and using it for its own
4124    nefarious purposes: Emacs never sees the keystrokes.  On many Unix
4125    systems, you can reconfigure your window manager to use another key
4126    sequence for switching among windows.  Another option is to use the
4127    equivalent sequence @kbd{@key{ESC}-@key{TAB}}.
4128    
4129    @item @strong{When stopping at breakpoints or errors, IDLWAVE does not
4130    seem to highlight the relevant line in the source.}
4131    
4132    IDLWAVE scans for error and halt messages and highlights the stop
4133    location in the correct file.  However, if you've changed the system
4134    variable @samp{!ERROR_STATE.MSG_PREFIX}, it is unable to parse these
4135    message correctly.  Don't do that.
4136    
4137    @item @strong{IDLWAVE doesn't work correctly when using ENVI.}
4138    
4139    Though IDLWAVE was not written with ENVI in mind, it works just fine
4140    with it, as long as you update the prompt it's looking for (@samp{IDL>
4141    } by default).  You can do this with the variable
4142    @code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g.,
4143    in your @file{.emacs}:
4144    
4145    @lisp
4146    (setq idlwave-shell-prompt-pattern "^\\(ENVI\\|IDL\\)> ")
4147    @end lisp
4148    
4149    @item @strong{Attempts to set breakpoints fail: no breakpoint is
4150    indicated in the IDLWAVE buffer.}
4151    
4152    IDL changed its breakpoint reporting format starting with IDLv5.5.  The
4153    first version of IDLWAVE to support the new format is IDLWAVE v4.10.  If
4154    you have an older version and are using IDL >v5.5, you need to upgrade,
4155    and/or make sure your recent version of IDLWAVE is being found on the
4156    Emacs load-path (see the next entry).  You can list the version being
4157    used with @kbd{C-h v idlwave-mode-version @key{RET}}.
4158    
4159    @item @strong{I installed a new version of IDLWAVE, but the old
4160    version is still being used} or @strong{IDLWAVE works, but when I
4161    tried to install the optional modules @file{idlw-roprompt.el} or
4162    @file{idlw-complete-structtag}, I get errors like @samp{Cannot open
4163    load file}}.
4164    
4165    The problem is that your Emacs is not finding the version of IDLWAVE you
4166    installed.  Many Emacsen come with an older bundled copy of IDLWAVE
4167    (e.g. v4.7 for Emacs 21.x), which is likely what's being used instead.
4168    You need to make sure your Emacs @emph{load-path} contains the directory
4169    where IDLWAVE is installed (@file{/usr/local/share/emacs/site-lisp}, by
4170    default), @emph{before} Emacs' default search directories.  You can
4171    accomplish this by putting the following in your @file{.emacs}:
4172    
4173    @lisp
4174    (setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path))
4175    @end lisp
4176    
4177    @noindent You can check on your load-path value using @kbd{C-h v
4178    load-path @key{RET}}.
4179    
4180    @item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.}
4181    
4182    Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated
4183    programming mode for CORBA's Interface Definition Language (you should
4184    see @samp{(IDL)}, not @samp{(IDLWAVE)} in the mode-line).  One
4185    solution: don't name your file @file{.idl}, but rather @file{.pro}.
4186    Another solution: make sure @file{.idl} files load IDLWAVE instead of
4187    @samp{idl-mode} by adding the following to your @file{.emacs}:
4188    
4189    @lisp
4190    (setcdr (rassoc 'idl-mode auto-mode-alist) 'idlwave-mode)
4191    @end lisp
4192    
4193    @item @strong{The routine info for my local routines is out of date!}
4194    
4195    IDLWAVE collects routine info from various locations (@pxref{Routine
4196    Information Sources}).  Routines in files visited in a buffer or
4197    compiled in the shell should be up to date.  For other routines, the
4198    information is only as current as the most recent scan.  If you have a
4199    rapidly changing set of routines, and you'd like the latest routine
4200    information to be available for it, one powerful technique makes use of
4201    the library catalog tool, @samp{idlwave_catalog}.  Simply add a line to
4202    your @samp{cron} file (@samp{crontab -e} will let you edit this on some
4203    systems), like this:
4204    
4205    @example
4206    45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib)
4207    @end example
4208    
4209    @noindent where @samp{MyLib} is the name of your library.  This will
4210    rescan all @file{.pro} files at or below @file{/path/to/myidllib} every
4211    week night at 3:45am.  You can even scan site-wide libraries with this
4212    method, and the most recent information will be available to all users.
4213    
4214    @item @strong{All the Greek-font characters in the HTML help are
4215    displayed as Latin characters!}
4216    
4217    Unfortunately, the HTMLHelp files RSI provides attempt to switch to
4218    @samp{Symbol} font to display Greek characters, which is not really an
4219    permitted method for doing this in HTML.  There is a "workaround" for
4220    many browsers: @xref{HTML Help Browser Tips}.
4221    
4222    @item @strong{In the shell, my long commands are truncated at 256 characters!}
4223    
4224    This actually happens when running IDL in an XTerm as well.  There are
4225    a couple of work arounds: @code{define_key,/control,'^d'} (e.g. in
4226    your @file{$IDL_STARTUP} file) will disable the @samp{EOF} character
4227    and give you a 512 character limit.  You won't be able to use
4228    @key{C-d} to quit the shell, however.  Another possibility is
4229    @code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a
4230    memory-bounded limit), but disables the processing of background
4231    widget events (those with @code{/NO_BLOCK} passed to @code{XManager}).
4232    
4233    @end enumerate
4234    
4235  @node Index,  , Windows and MacOS, Top  @node Index,  , Troubleshooting, Top
4236  @unnumbered Index  @unnumbered Index
4237  @printindex cp  @printindex cp
4238    

Legend:
Removed from v.1.18.4.3  
changed lines
  Added in v.1.18.4.4

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26