/[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 by eliz, Sat Dec 1 13:08:48 2001 UTC revision 1.18.4.1 by miles, Fri Apr 4 06:20:48 2003 UTC
# Line 2  Line 2 
2  @c %**start of header  @c %**start of header
3  @setfilename ../info/idlwave  @setfilename ../info/idlwave
4  @settitle IDLWAVE User Manual  @settitle IDLWAVE User Manual
 @dircategory Emacs  
 @direntry  
 * IDLWAVE: (idlwave).   Major mode and shell for IDL and WAVE/CL files.  
 @end direntry  
5  @synindex ky cp  @synindex ky cp
6  @syncodeindex vr cp  @syncodeindex vr cp
7  @syncodeindex fn cp  @syncodeindex fn cp
8  @set VERSION 4.7  @set VERSION 4.15
9  @set EDITION 4.7  @set EDITION 4.15
10  @set IDLVERSION 5.4  @set IDLVERSION 5.5
11  @set NSYSROUTINES 1287  @set NSYSROUTINES 1324
12  @set NSYSKEYWORDS 5724  @set NSYSKEYWORDS 6129
13  @set DATE December 2000  @set DATE September 2002
14  @set AUTHOR Carsten Dominik  @set AUTHOR J.D. Smith & Carsten Dominik
15  @set AUTHOR-EMAIL dominik@@astro.uva.nl  @set AUTHOR-EMAIL dominik@@astro.uva.nl
16  @set MAINTAINER John-David Smith  @set MAINTAINER J.D. Smith
17  @set MAINTAINER-EMAIL jdsmith@@astro.cornell.edu  @set MAINTAINER-EMAIL jdsmith@@as.arizona.edu
18  @set IDLWAVE-HOMEPAGE http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave  @set IDLWAVE-HOMEPAGE http://idlwave.org/
19  @c %**end of header  @c %**end of header
 @finalout  
20    
21  @ifinfo  @copying
22  This file documents IDLWAVE, a major mode for editing IDL and  This file documents IDLWAVE, a major mode for editing IDL files with
23  WAVE/CL files with Emacs.  It also implements a shell for running IDL as  Emacs, and interacting with an IDL shell run as a subprocess.
 a subprocess.  
24    
25  This is edition @value{EDITION} of the IDLWAVE User Manual for  This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE
26  IDLWAVE @value{VERSION}  @value{VERSION}
27    
28  Copyright (c) 1999, 2000, 2001 Free Software Foundation, Inc.  Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation,
29    Inc.
30    
31    @quotation
32  Permission is granted to copy, distribute and/or modify this document  Permission is granted to copy, distribute and/or modify this document
33  under the terms of the GNU Free Documentation License, Version 1.1 or  under the terms of the GNU Free Documentation License, Version 1.1 or
34  any later version published by the Free Software Foundation; with no  any later version published by the Free Software Foundation; with no
# Line 49  This document is part of a collection di Line 45  This document is part of a collection di
45  Documentation License.  If you want to distribute this document  Documentation License.  If you want to distribute this document
46  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
47  license to the document, as described in section 6 of the license.  license to the document, as described in section 6 of the license.
48  @end ifinfo  @end quotation
49    @end copying
50    
51    @dircategory Emacs
52    @direntry
53    * IDLWAVE: (idlwave).   Major mode and shell for IDL files.
54    @end direntry
55    
56    @finalout
57    
58  @titlepage  @titlepage
59  @title IDLWAVE User Manual  @title IDLWAVE User Manual
60  @subtitle Major Emacs mode and shell for IDL and WAVE/CL files  @subtitle Emacs major mode and shell for IDL
61  @subtitle Edition @value{EDITION}, @value{DATE}  @subtitle Edition @value{EDITION}, @value{DATE}
62    
63  @author by Carsten Dominik  @author by Carsten Dominik & J.D. Smith
64  @page  @page
65  This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for  This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for
66  IDLWAVE version @value{VERSION}, @value{DATE}.  IDLWAVE version @value{VERSION}, @value{DATE}.
 @sp 2  
 Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc.  
 @sp 2  
67  @cindex Copyright, of IDLWAVE  @cindex Copyright, of IDLWAVE
68    @insertcopying
 Permission is granted to copy, distribute and/or modify this document  
 under the terms of the GNU Free Documentation License, Version 1.1 or  
 any later version published by the Free Software Foundation; with no  
 Invariant Sections, with the Front-Cover texts being ``A GNU  
 Manual'', and with the Back-Cover Texts as in (a) below.  A copy of the  
 license is included in the section entitled ``GNU Free Documentation  
 License'' in the Emacs manual.  
   
 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify  
 this GNU Manual, like GNU software.  Copies published by the Free  
 Software Foundation raise funds for GNU development.''  
   
 This document is part of a collection distributed under the GNU Free  
 Documentation License.  If you want to distribute this document  
 separately from the collection, you can do so by adding a copy of the  
 license to the document, as described in section 6 of the license.  
69  @end titlepage  @end titlepage
70  @contents  @contents
71    
# Line 90  license to the document, as described in Line 75  license to the document, as described in
75    
76  @node Top, Introduction, (dir), (dir)  @node Top, Introduction, (dir), (dir)
77    
78  IDLWAVE is a package to support editing command files for the  IDLWAVE is a package which supports editing source for the
79  Interactive Data Language (IDL), and for running IDL as an inferior  Interactive Data Language (IDL), and running IDL as an inferior
80  shell.  shell.
81    
82  @end ifnottex  @end ifnottex
83    
84  @menu  @menu
85  * Introduction::                What IDLWAVE is and what not  * Introduction::                What IDLWAVE is and what it's not
86  * IDLWAVE in a Nutshell::       One page quick-start guide  * IDLWAVE in a Nutshell::       One page quick-start guide
87  * Getting Started::             Tutorial  * Getting Started::             Tutorial
88  * The IDLWAVE Major Mode::      The mode to edit IDL programs  * The IDLWAVE Major Mode::      The mode to edit IDL programs
89  * The IDLWAVE Shell::           The mode to run IDL as inferior program  * The IDLWAVE Shell::           The mode to run IDL as an inferior program
90  * Installation::                How to Install or Upgrade                * Installation::                How to Install or Upgrade
91  * Acknowledgement::             Who helped    * Acknowledgements::            Who did what
92  * Sources of Routine Info::     How does IDLWAVE know about routine XYZ      * Sources of Routine Info::     How does IDLWAVE know about routine XYZ
93  * Configuration Examples::      The user is king...  * Configuration Examples::      The user is king...
94    * Windows and MacOS::           What still works, and how
95  * Index::                       Fast access  * Index::                       Fast access
96    
97  @detailmenu --- The Detailed Node Listing ---  @detailmenu
98     --- The Detailed Node Listing ---
99    
100    Getting Started (Tutorial)
101    
102    * Lesson I -- Development Cycle::
103    * Lesson II -- Customization::
104    * Lesson III -- Library Catalog::
105    
106  The IDLWAVE Major Mode  The IDLWAVE Major Mode
107    
# Line 116  The IDLWAVE Major Mode Line 109  The IDLWAVE Major Mode
109  * Routine Info::                Calling Sequence and Keyword List  * Routine Info::                Calling Sequence and Keyword List
110  * Online Help::                 One key press from source to help  * Online Help::                 One key press from source to help
111  * Completion::                  Completing routine names and Keywords  * Completion::                  Completing routine names and Keywords
112  * Routine Source::              How to visit the source file of routine XYZ  * Routine Source::              Finding routines, the easy way
113  * Resolving Routines::          Force the Shell to compile a routine  * Resolving Routines::          Force the Shell to compile a routine
114  * Code Templates::              Abbreviations for frequent constructs  * Code Templates::              Frequent code constructs
115    * Abbreviations::               Abbreviations for common commands
116  * Actions::                     Changing case, Padding, End checking  * Actions::                     Changing case, Padding, End checking
117  * Doc Header::                  Inserting a standard header  * Doc Header::                  Inserting a standard header
118  * Motion Commands::             Moving through the structure of a program  * Motion Commands::             Moving through the structure of a program
# Line 127  The IDLWAVE Major Mode Line 121  The IDLWAVE Major Mode
121  Code Formatting  Code Formatting
122    
123  * Code Indentation::            Reflecting the logical structure  * Code Indentation::            Reflecting the logical structure
124    * Continued Statement Indentation::
125  * Comment Indentation::         Special indentation for comment lines  * Comment Indentation::         Special indentation for comment lines
126  * Continuation Lines::          Splitting statements over lines  * Continuation Lines::          Splitting statements over lines
127  * Syntax Highlighting::         Font-lock support  * Syntax Highlighting::         Font-lock support
128    * Octals and Highlighting::     Why "123 causes problems
129    
130    Completion
131    
132    * Case of Completed Words::     CaseOFcomPletedWords
133    * Object Method Completion and Class Ambiguity::  obj->Method, what?
134    * Object Method Completion in the Shell::
135    * Class and Keyword Inheritance::  obj->Method, _EXTRA=e
136    * Structure Tag Completion::    Completing state.Tag
137    
138  Actions  Actions
139    
140  * Block Boundary Check::        Is the END correct  * Block Boundary Check::        Is the END statement correct?
141  * Padding Operators::           Enforcing space around `=' etc  * Padding Operators::           Enforcing space around `=' etc
142  * Case Changes::                Enforcing upper case keywords  * Case Changes::                Enforcing upper case keywords
143    
# Line 141  The IDLWAVE Shell Line 145  The IDLWAVE Shell
145    
146  * Starting the Shell::          How to launch IDL as a subprocess  * Starting the Shell::          How to launch IDL as a subprocess
147  * Using the Shell::             Interactively working with the Shell  * Using the Shell::             Interactively working with the Shell
148  * Debugging IDL Programs::      Compilation/Debugging  * Commands Sent to the Shell::
149    * Debugging IDL Programs::
150    * Examining Variables::
151    * Custom Expression Examination::
152    
153  Debugging IDL Programs  Debugging IDL Programs
154    
155  * Compiling Programs::          Compiling buffers under the shell  * Debug Key Bindings::
156  * Breakpoints and Stepping::    Deciding where to stop and look  * Compiling Programs::
157  * Examining Variables::         What is the value now?  * Breakpoints and Stepping::
158    * Walking the Calling Stack::
159    
160  Installation  Installation
161    
# Line 177  Sources of Routine Info Line 185  Sources of Routine Info
185  @cindex @file{idl-shell.el}  @cindex @file{idl-shell.el}
186  @cindex Feature overview  @cindex Feature overview
187    
188  IDLWAVE is a package to support editing command files for the  IDLWAVE is a package which supports editing source files for the
189  Interactive Data Language (IDL), and for running IDL as an inferior  Interactive Data Language (IDL@footnote{IDL is a registered trademark of
190  shell.  It also can be used for WAVE/CL command files, but the support  Research Systems, Inc., a Kodak Company}), and for running IDL as an
191  for these is limited.  Note that this package has nothing to do with the  inferior shell@footnote{Note that this package has nothing to do with
192  Interface Definition Language as part of the Common Object Request  the Interface Definition Language, part of the Common Object Request
193  Broker Architecture (CORBA).  Broker Architecture (CORBA)}.  It can also be used for editing source
194    files for the related WAVE/CL language, but with only limited
195  IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el}  support.
196  files written by Chris Chase.  The modes and files had to be renamed  
197  because of a name space conflict with CORBAs @code{idl-mode}, defined in  IDLWAVE consists of two main parts: a major mode for editing IDL source
198  Emacs in the file @file{cc-mode.el}.  If you have been using the old  files files (@code{idlwave-mode}) and a mode for running the IDL program
199  files, check @ref{Upgrading from idl.el} for information on how to  as an inferior shell (@code{idlwave-shell-mode}).  Although one mode can
200  switch.  be used without the other, both work together closely to form a complete
201    development environment. Here is a brief summary of what IDLWAVE does:
 IDLWAVE consists of two parts: A major mode for editing command files  
 (@code{idlwave-mode}) and a mode to allow running the IDL program as an  
 inferior shell (@code{idlwave-shell-mode}).  Both modes work closely  
 together and form a complete development environment.  
   
 Here is a brief summary of what IDLWAVE does.  
202    
203  @itemize @bullet  @itemize @bullet
204  @item  @item
205  Code indentation and formatting.  Code indentation and formatting.
206  @item  @item
207  Font-lock support on three levels.  Three level syntax highlighting support.
 @item  
 Display of calling sequence and keywords of more than 1000 IDL  
 routines and any routines in your local IDL library.  
208  @item  @item
209  Name space conflict search.  Context-sensitive display of calling sequences and keywords for more
210    than 1000 native IDL routines, extendible to any number of additional
211    routines in your local IDL libraries.
212  @item  @item
213  Fast context-sensitive online help.  Routine name space conflict search, likelihood-of-use ranking.
214    @item
215    Fast, context-sensitive online help.
216  @item  @item
217  Context sensitive completion of routine names and keywords.  Context sensitive completion of routine names and keywords.
218  @item  @item
219  Insertion of code templates.  Easy insertion of code templates.
220  @item  @item
221  Actions to enforce coding standards during typing.  Automatic corrections to enforce a variety of customizable coding
222    standards.
223  @item  @item
224  Block structure check.  Integrity checks and auto-termination of logical blocks.
225  @item  @item
226  Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs).  Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs).
227  @item  @item
228  Documentation support.  Documentation support.
229  @item  @item
230  Running IDL as inferior process.  Running IDL as an inferior Shell with history search, command line
231    editing and all the completion and routine info capabilities present in
232    IDL source buffers.
233    @item
234    Compilation, execution and interactive debugging of programs directly
235    from the source buffer.
236  @item  @item
237  Shell with history search, command line editing and completion.  Quick, source-guided navigation of the calling stack, with variable
238    inspection, etc.
239  @item  @item
240  Compilation, execution and debugging of programs directly from the source  Examining variables and expressions with a mouse click.
 buffer.    
241  @item  @item
242  Examining expressions with a mouse click.  And much, much more...
243  @end itemize  @end itemize
244    
245  @ifnottex  @ifnottex
246  @cindex Screenshots  @cindex Screenshots
247  Here are a number of screenshots showing IDLWAVE in action.  Here are a number of screenshots showing IDLWAVE in action:
248    
249  @itemize @bullet  @itemize @bullet
250  @item  @item
251  @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/font-lock.gif,  @uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer}
 XEmacs 21.1 with formatted and fontified code}  
252  @item  @item
253  @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/rinfo.gif,  @uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed}
 XEmacs 21.1 displaying routine info}  
254  @item  @item
255  @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/complete.gif,  @uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.}
 XEmacs 21.1 completing a keyword}  
256  @item  @item
257  @uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/shell.gif,  @uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed}
258  XEmacs 21.1 with debugging toolbar; execution stopped at a breakpoint}  @item
259    @uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code
260    stopped at a breakpoint}
261  @end itemize  @end itemize
262  @end ifnottex  @end ifnottex
263    
264  In this manual, each section contains a list of user options related to  IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el}
265  the subject.  Don't be confused by the shear number of options available  files written by Chris Chase.  The modes and files had to be renamed
266  -- in most cases the default settings are just fine.  The variables are  because of a name space conflict with CORBA's @code{idl-mode}, defined in
267  listed here to make sure you know where to look if you want to change  Emacs in the file @file{cc-mode.el}.  If you have been using the old
268  things.  For a full description of what a particular variable does and  files, check @ref{Upgrading from idl.el} for information on how to
269  how to configure it, see the documentation string of that variable.  switch.
270  Some configuration examples are also given in the appendix.  
271    In this manual, each section ends with a list of related user options.
272    Don't be confused by the sheer number of options available --- in most
273    cases the default settings are just fine.  The variables are listed here
274    to make sure you know where to look if you want to change anything.  For
275    a full description of what a particular variable does and how to
276    configure it, see the documentation string of that variable (available
277    with @kbd{C-h v}).  Some configuration examples are also given in the
278    appendix.
279    
280  @node IDLWAVE in a Nutshell, Getting Started, Introduction, Top  @node IDLWAVE in a Nutshell, Getting Started, Introduction, Top
281  @chapter IDLWAVE in a Nutshell  @chapter IDLWAVE in a Nutshell
# Line 274  Some configuration examples are also giv Line 290  Some configuration examples are also giv
290  @tab Indent the current line relative to context.  @tab Indent the current line relative to context.
291  @item @kbd{C-M-\}  @item @kbd{C-M-\}
292  @tab Re-indent all lines in the current region.  @tab Re-indent all lines in the current region.
293    @item @kbd{C-u @key{TAB}}
294    @tab Re-indent all lines in the current statement.
295  @item @kbd{M-@key{RET}}  @item @kbd{M-@key{RET}}
296  @tab Start a continuation line.  Or split the current line at point.  @tab Start a continuation line, or split the current line at point.
297  @item @kbd{M-q}  @item @kbd{M-q}
298  @tab Fill the current comment paragraph.  @tab Fill the current comment paragraph.
299  @item @kbd{C-c ?}  @item @kbd{C-c ?}
300  @tab Display calling sequence, keywords of the procedure/function call  @tab Display calling sequence and keywords for the procedure or function call
301  at point.  at point.
302  @item @kbd{M-?}  @item @kbd{M-?}
303  @tab Context sensitive online help.  @tab Load context sensitive online help for nearby routine, keyword, etc.
304  @item @kbd{M-@key{TAB}}  @item @kbd{M-@key{TAB}}
305  @tab Complete a procedure name, function name or keyword in the buffer.  @tab Complete a procedure name, function name or keyword in the buffer.
306  @item @kbd{C-c C-i}  @item @kbd{C-c C-i}
307  @tab Update IDLWAVE's knowledge about functions and procedures.  @tab Update IDLWAVE's knowledge about functions and procedures.
308  @item @kbd{C-c C-v}  @item @kbd{C-c C-v}
309  @tab Find the source code of a procedure/function.  @tab Visit the source code of a procedure/function.
310  @item @kbd{C-c C-h}  @item @kbd{C-c C-h}
311  @tab Insert a standard documentation header.  @tab Insert a standard documentation header.
312  @item @kbd{C-c C-m}  @item @kbd{C-c @key{RET}}
313  @tab Insert a new timestamp and history item in the documentation header.  @tab Insert a new timestamp and history item in the documentation header.
314  @end multitable  @end multitable
315    
# Line 301  at point. Line 319  at point.
319  @item @kbd{C-c C-s}  @item @kbd{C-c C-s}
320  @tab Start IDL as a subprocess and/or switch to the interaction buffer.  @tab Start IDL as a subprocess and/or switch to the interaction buffer.
321  @item @kbd{M-p}  @item @kbd{M-p}
322  @tab Cycle back through IDL command history matching command line input.  @tab Cycle back through IDL command history.
323  @item @kbd{M-n}  @item @kbd{M-n}
324  @tab Cycle forward.  @tab Cycle forward.
325  @item @kbd{M-@key{TAB}}  @item @kbd{M-@key{TAB}}
# Line 311  at point. Line 329  at point.
329  @item @kbd{C-c C-d C-x}  @item @kbd{C-c C-d C-x}
330  @tab Goto next syntax error.  @tab Goto next syntax error.
331  @item @kbd{C-c C-d C-b}  @item @kbd{C-c C-d C-b}
332  @tab Set a breakpoint at the current source line.  @tab Set a breakpoint at the nearest viable source line.
333  @item @kbd{C-c C-d C-d}  @item @kbd{C-c C-d C-d}
334  @tab Clear the current breakpoint.  @tab Clear the nearest breakpoint.
335  @item @kbd{C-c C-d C-p}  @item @kbd{C-c C-d C-p}
336  @tab Ask IDL to print the value of the expression near point.  @tab Print the value of the expression near point in IDL.
337  @end multitable  @end multitable
338    
339  @subheading Commonly used Settings in @file{.emacs}  @subheading Commonly used Settings in @file{.emacs}
340  @lisp  @lisp
341  ;; Change the indentation preferences  ;; Change the indentation preferences
342  (setq idlwave-main-block-indent 2         ; default  0  (setq idlwave-main-block-indent 2   ; default  0
343        idlwave-block-indent 2              ; default  4        idlwave-block-indent 2        ; default  4
344        idlwave-end-offset -2)              ; default -4        idlwave-end-offset -2)        ; default -4
345    ;; Start autoloading routine info after 2 idle seconds
346    (setq idlwave-init-rinfo-when-idle-after 2)
347  ;; Pad some operators with spaces  ;; Pad some operators with spaces
348  (setq idlwave-do-actions t  (setq idlwave-do-actions t
349        idlwave-surround-by-blank t)        idlwave-surround-by-blank t)
# Line 333  at point. Line 353  at point.
353  (setq idlwave-shell-automatic-start t)  (setq idlwave-shell-automatic-start t)
354  ;; Bind debugging commands with CONTROL and SHIFT modifiers  ;; Bind debugging commands with CONTROL and SHIFT modifiers
355  (setq idlwave-shell-debug-modifiers '(control shift))  (setq idlwave-shell-debug-modifiers '(control shift))
356  ;; Where are the online help files?  ;; Specify the online help files' location.
357  (setq idlwave-help-directory "~/.idlwave")  (setq idlwave-help-directory "~/.idlwave")
358  @end lisp  @end lisp
359    
360    @ifhtml
361    <A NAME="TUTORIAL"></A>
362    @end ifhtml
363  @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top  @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top
364  @chapter Getting Started (Tutorial)  @chapter Getting Started (Tutorial)
365  @cindex Quick-Start  @cindex Quick-Start
366  @cindex Tutorial  @cindex Tutorial
367  @cindex Getting Started  @cindex Getting Started
368    
369  @section Lession I: Development Cycle  @menu
370    * Lesson I -- Development Cycle::
371    * Lesson II -- Customization::
372    * Lesson III -- Library Catalog::
373    @end menu
374    
375    @node  Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started
376    @section Lesson I: Development Cycle
377    
378  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
379  development cycle with IDLWAVE.  We will type a simple program into a  development cycle using IDLWAVE.  We will paste a simple program into a
380  buffer and use the shell to compile, debug and run this program.  On the  buffer and use the shell to compile, debug and run it.  On the way we
381  way we will use the most important commands in IDLWAVE.  Note  will use many of the important IDLWAVE commands.  Note however that
382  however that there is much more funtionality available in IDLWAVE than  there are many more capabilities in IDLWAVE than covered here, which can
383  we cover here, and it will pay off greatly if eventually you go further  be discovered by reading the entire manual.
384  and read the whole manual.  
385    It is assumed that you have access to Emacs or XEmacs with the full
386  I assume that you have access to Emacs or XEmacs with the full IDLWAVE  IDLWAVE package including online help (@pxref{Installation}).  We also
387  package including online help (@pxref{Installation}).  I also assume  assume that you are familiar with Emacs and can read the nomenclature of
388  that you are familiar with Emacs and can read the nomenclature of key  key presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL}
389  presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL} and  and @kbd{M} for @key{META} (often the @key{ALT} key carries this
 @kbd{M} for @key{META} (often the @key{ALT} key carries this  
390  functionality)).  functionality)).
391    
392  Open a new source file by typing  Open a new source file by typing:
393    
394  @example  @example
395  @kbd{C-x C-f tutorial.pro @key{RET}}  @kbd{C-x C-f tutorial.pro @key{RET}}
396  @end example  @end example
397    
398  A buffer for this file will pop up, and it should be in IDLWAVE mode.  A buffer for this file will pop up, and it should be in IDLWAVE mode, as
399  You can see this by looking at the mode line, just below the editing  shown in the mode line just below the editing window.  Also, the menu
400  window.  Also, the menu bar should contain entries @samp{IDLWAVE} and  bar should contain entries @samp{IDLWAVE} and @samp{Debug}.
 @samp{Debug}.  
401    
402  Now cut-and-paste the following program, also available as  Now cut-and-paste the following code, also available as
403  @file{tutorial.pro} in the IDLWAVE distribution.  @file{tutorial.pro} in the IDLWAVE distribution.
404    
405  @example  @example
# Line 384  function daynr,d,m,y Line 412  function daynr,d,m,y
412    y1 = y * delta    y1 = y * delta
413    return, d + floor(m1*30.6)+floor(y1*365.25)+5    return, d + floor(m1*30.6)+floor(y1*365.25)+5
414  end  end
415        
416  function weekday,day,month,year  function weekday,day,month,year
417    ;; compute weekday number for date    ;; compute weekday number for date
418    nr = daynr(day,month,year)    nr = daynr(day,month,year)
419    return, nr mod 7    return, nr mod 7
420  end  end
421        
422  pro plot_wday,day,month  pro plot_wday,day,month
423    ;; 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.
424    years = 2000,+indgen(10)    years = 2000,+indgen(10)
425    wdays = intarr(10)    wdays = intarr(10)
426    for i=0,n_elements(wdays)-1 do begin    for i=0,n_elements(wdays)-1 do begin
427       wdays[i] =  weekday(day,month,years[i])        wdays[i] =  weekday(day,month,years[i])
428    end    end
429    plot,years,wdays,YS=2,YT="Wday (0=sunday)"    plot,years,wdays,YS=2,YT="Wday (0=Sunday)"
430  end  end
431  @end example  @end example
432    
433  The indentation probably looks funny, since it's different from the  The indentation probably looks funny, since it's different from the
434  settings you use, so use the @key{TAB} key in each line to automatically  settings you use, so use the @key{TAB} key in each line to automatically
435  line it up (or more quickly @emph{select} the entire buffer with  line it up (or more quickly @emph{select} the entire buffer with
436  @kbd{C-x h} followed by @kbd{C-M-\}).  Notice how different syntactical  @kbd{C-x h}, and indent the whole region with @kbd{C-M-\}).  Notice how
437  elements are highlighted in different colors, if you have set up support  different syntactical elements are highlighted in different colors, if
438  for font-lock.  you have set up support for font-lock.
439    
440  Let's check out two particular editing features of IDLWAVE.  Place the  Let's check out two particular editing features of IDLWAVE.  Place the
441  cursor after the @code{end} statement of the @code{for} loop and press  cursor after the @code{end} statement of the @code{for} loop and press
442  @key{SPC}.  IDLWAVE blinks back to the beginning of the block and  @key{SPC}.  IDLWAVE blinks back to the beginning of the block and
443  changes the generic @code{end} to the specific @code{endfor}  changes the generic @code{end} to the specific @code{endfor}
444  automatically.  Now place the cursor in any line you would like to split  automatically.  Now place the cursor in any line you would like to split
445  into two and press @kbd{M-@key{RET}}.  The line is split at the cursor  and press @kbd{M-@key{RET}}.  The line is split at the cursor position,
446  position, with the continuation @samp{$} and indentation all taken care  with the continuation @samp{$} and indentation all taken care of.  Use
447  of.  Use @kbd{C-/} to undo the last change.  @kbd{C-/} to undo the last change.
448    
449  The procedure @code{plot_wday} is supposed to plot the weekday of a given  The procedure @code{plot_wday} is supposed to plot the weekday of a
450  date for the first 10 years of the 21st century.  I have put in a few  given date for the first 10 years of the 21st century.  As in most code,
451  bugs which we are going to fix now.  there are a few bugs, which we are going to use IDLWAVE to help us fix.
452    
453  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
454  @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 and display IDL running in a
455  shell interaction buffer.  Type a few commands like @code{print,!PI} to  shell interaction buffer.  Type a few commands like @code{print,!PI} to
456  convince yourself that you can work there like in an xterminal, or the  convince yourself that you can work there just as well as in a terminal,
457  IDLDE.  Use the arrow keys to cycle through your command history.  Are  or the IDLDE.  Use the arrow keys to cycle through your command history.
458  we having fun now?  Are we having fun now?
459    
460  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
461  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
462  @samp{.run tutorial.pro} for you.  But the compilation fails because  @samp{.run tutorial.pro} for you.  But the compilation fails because
463  there is a comma in the line @samp{years=...}.  The line with the error  there is a comma in the line @samp{years=...}.  The line with the error
464  is highlighted and the cursor positioned at the error, so remove the  is highlighted and the cursor positioned at the error, so remove the
465  comma (you should only need to hit Delete!).  Compile again, using the  comma (you should only need to hit @kbd{Delete}!).  Compile again, using
466  same keystrokes as before.  Notice that the file is saved for you.  This  the same keystrokes as before.  Notice that the file is automatically
467  time everything should work fine, and you should see the three routines  saved for you.  This time everything should work fine, and you should
468  compile.  see the three routines compile.
469    
470  Now we want to use the command to plot the weekdays for January 1st.  We  Now we want to use the command to plot the day of the week on January
471  could type the full command ourselves, but why do that?  Go back to the  1st.  We could type the full command ourselves, but why do that?  Go
472  shell window, type @samp{plot_} and hit @key{TAB}.  After a bit of a  back to the shell window, type @samp{plot_} and hit @key{TAB}.  After a
473  delay (while IDLWAVE initializes its routine info database), the window  bit of a delay (while IDLWAVE initializes its routine info database, if
474  will split to show all procedures it knows starting with that string,  necessary), the window will split to show all procedures it knows
475  and @w{@code{plot_wday}} should be one of them.  Saving the buffer was  starting with that string, and @w{@code{plot_wday}} should be one of
476  enough to tell IDLWAVE about this new routine.  Click with the middle  them.  Saving the buffer alerted IDLWAVE about this new routine.  Click
477  mouse button on @code{plot_wday} and it will be copied to the shell  with the middle mouse button on @code{plot_wday} and it will be copied
478  buffer, or if you prefer, add @samp{w} to @samp{plot_} to make it  to the shell buffer, or if you prefer, add @samp{w} to @samp{plot_} to
479  unambiguous, hit @key{TAB}, and the full routine name will be completed.  make it unambiguous, hit @key{TAB} again, and the full routine name will
480  Now provide the two arguments:  be completed.  Now provide the two arguments:
481    
482  @example  @example
483  plot_wday,1,1  plot_wday,1,1
484  @end example  @end example
485    
   
486  and press @key{RET}.  This fails with an error message telling you the  and press @key{RET}.  This fails with an error message telling you the
487  @code{YT} keyword to plot is ambiguous.  What are the allowed keywords  @code{YT} keyword to plot is ambiguous.  What are the allowed keywords
488  again?  Go back to the source window and put the cursor into the `plot'  again?  Go back to the source window and put the cursor into the `plot'
489  line, and press @kbd{C-c ?}.  This pops up the routine info window for  line, and press @kbd{C-c ?}.  This shows the routine info window for the
490  the plot routine, which contains a list of keywords, and the argument  plot routine, which contains a list of keywords, along with the argument
491  list.  Oh, we wanted @code{YTITLE}.  Fix that up.  Recompile with  list.  Oh, we wanted @code{YTITLE}.  Fix that up.  Recompile with
492  @kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press  @kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press
493  the @key{UP} arrow to recall the previous command and execute again.  the @key{UP} arrow to recall the previous command and execute again.
494    
495  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
496  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
497  symbols instead?  What was that keyword?  Position the cursor on the  symbols instead?  What was that keyword?  Position the cursor on the
498  plot line after a comma (where you'd normally type a keyword), and hit  plot line after a comma (where you'd normally type a keyword), and hit
# Line 475  included for you too.  Now what were the Line 502  included for you too.  Now what were the
502  to be?  With the cursor on or after the keyword, press @kbd{M-?} for  to be?  With the cursor on or after the keyword, press @kbd{M-?} for
503  online help (alternatively, you could have right clicked on the colored  online help (alternatively, you could have right clicked on the colored
504  keyword itself in the completion list).  The online help window will pop  keyword itself in the completion list).  The online help window will pop
505  up showing the documentation for the @code{PYSM} keyword.  Ok, let's use  up showing the documentation for the @code{PYSM} keyword.  OK, let's use
506  diamonds=4.  Fix this, recompile (you know the command by now: @kbd{C-c  diamonds=4.  Fix this, recompile (you know the command by now: @kbd{C-c
507  C-d C-c}, go back to the shell (if it's vanished, you know the command  C-d C-c}, go back to the shell (if it's vanished, you know the command
508  to recall it by now: @kbd{C-c C-s}) and execute again.  Now things look  to recall it by now: @kbd{C-c C-s}) and execute again.  Now things look
509  pretty good.  pretty good.
510    
511  Lets try a different day - how about April fool's day?  Let's try a different day --- how about April fool's day?
512    
513  @example  @example
514  plot_wday,1,4  plot_wday,1,4
515  @end example  @end example
516    
517     Oops, this looks very wrong.  All April fool's days cannot be  Oops, this looks very wrong.  All April fool's days cannot be Fridays!
518  Fridays!  We've got a bug in the program, perhaps in the @code{daynr}  We've got a bug in the program, perhaps in the @code{daynr} function.
519  function.  Lets put a breakpoint on the last line there.  Position the  Let's put a breakpoint on the last line there.  Position the cursor on
520  cursor on the @samp{return, d+...} line and press @kbd{C-c C-d C-b}.  the @samp{return, d+...} line and press @kbd{C-c C-d C-b}.  IDL sets a
521  IDL sets a breakpoint (as you see in the shell window), and the line is  breakpoint (as you see in the shell window), and the line is highlighted
522  highlighted in some way.  Back to the shell buffer, re-execute the  in some way.  Back to the shell buffer, re-execute the previous command.
523  previous command.  IDL stops at the line with the breakpoint.  Now hold  IDL stops at the line with the breakpoint.  Now hold down the SHIFT key
524  down the SHIFT key and click with the middle mouse button on a few  and click with the middle mouse button on a few variables there:
525  variables there: @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc.  Maybe  @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc.  Maybe @code{d} isn't the
526  @code{d} isn't the correct type.  CONTROL-SHIFT middle-click on it for  correct type.  CONTROL-SHIFT middle-click on it for help.  Well, it's an
527  help.  Well, it's an integer, so that's not the problem.  Aha, @samp{y1}  integer, so that's not the problem.  Aha, @samp{y1} is zero, but it
528  is zero, but it should be the year, depending on delta.  Shift click  should be the year, depending on delta.  Shift click @samp{delta} to see
529  @samp{delta} to see that it's 0.  Below, we see the offending line:  that it's 0.  Below, we see the offending line: @samp{y1=y*delta...} the
530  @samp{y1=y*delta...} the multiplication should have been a minus sign!  multiplication should have been a minus sign!  So fix the line to read:
 So fix the line to  
531    
532  @example  @example
533  y1 = y - delta  y1 = y - delta
# Line 512  command.  Everything should now work fin Line 538  command.  Everything should now work fin
538  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
539  sequence of weekdays repeats.  sequence of weekdays repeats.
540    
541  @section Lession II: Customization  @node  Lesson II -- Customization, Lesson III -- Library Catalog, Lesson I -- Development Cycle, Getting Started
542    @section Lesson II: Customization
543    
544  Emacs is probably the most customizable piece of software available, and  Emacs is probably the most customizable piece of software available, and
545  it would be a shame if you did not make use of this and adapt IDLWAVE to  it would be a shame if you did not make use of this and adapt IDLWAVE to
546  your own preferences.  Customizing Emacs or IDLWAVE means that you have  your own preferences.  Customizing Emacs or IDLWAVE is accomplished by
547  to set Lisp variables in the @file{.emacs} file in your home directory.  setting Lisp variables in the @file{.emacs} file in your home directory
548  This looks scary to many people because of all the parenthesis.  --- but do not be dismayed; for the most part, you can just copy and work
549  However, you can just cut and paste the examples given here and work  from the examples given here.
550  from there.  
551    Let's first use a boolean variable.  These are variables which you turn
552  Lets first use a boolean variable.  These are variables which you turn  on or off, much like a checkbox. A value of @samp{t} means on, a value
553  on or off, much like a checkbox. A value of @samp{t} means on, a  of @samp{nil} means off.  Copy the following line into your
 value of @samp{nil} means off.  Copy the following line into your  
554  @file{.emacs} file, exit and restart Emacs.  @file{.emacs} file, exit and restart Emacs.
555    
556  @lisp  @lisp
# Line 537  or @key{RET} right after the word.  Try Line 563  or @key{RET} right after the word.  Try
563  @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
564  behavior, remove the option again from your @file{.emacs} file.  behavior, remove the option again from your @file{.emacs} file.
565    
566  Now I bet you have your own indentation preferences for IDL code.  For  You likely have your own indentation preferences for IDL code.  For
567  example, I like to indent the main block of an IDL program a bit,  example, some like to indent the main block of an IDL program from the
568  different from the conventions used by RSI.  Also, I'd like to use only  margin, different from the conventions used by RSI, and use only 3
569  3 spaces as indentation between @code{BEGIN} and @code{END}.  Try the  spaces as indentation between @code{BEGIN} and @code{END}.  Try the
570  following lines in @file{.emacs}  following lines in @file{.emacs}:
571    
572  @lisp  @lisp
573  (setq idlwave-main-block-indent 2)  (setq idlwave-main-block-indent 2)
# Line 549  following lines in @file{.emacs} Line 575  following lines in @file{.emacs}
575  (setq idlwave-end-offset -3)  (setq idlwave-end-offset -3)
576  @end lisp  @end lisp
577    
578  Restart Emacs, take the program we developed in the first part of this  Restart Emacs, and re-indent the program we developed in the first part
579  tutorial and re-indent it with @kbd{C-c h} and @kbd{C-M-\}.  You  of this tutorial with @kbd{C-c h} and @kbd{C-M-\}.  You may want to keep
580  probably want to keep these lines in @file{.emacs}, with values adjusted  these lines in @file{.emacs}, with values adjusted to your likings.  If
581  to your likings.  If you want to get more information about any of these  you want to get more information about any of these variables, type,
582  variables, type, e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}.  e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}.  To find which
583  To find which variables can be customized, look for items marked  variables can be customized, look for items marked @samp{User Option:}
584  @samp{User Option:} in the manual.  throughout this manual.
585    
586  If you cannot wrap your head around this Lisp stuff, there is another,  If you cannot seem to master this Lisp customization in @file{.emacs},
587  more user-friendly way to customize all the IDLWAVE variables.  You can  there is another, more user-friendly way to customize all the IDLWAVE
588  access it through the IDLWAVE menu in one of the @file{.pro} buffers,  variables.  You can access it through the IDLWAVE menu in one of the
589  option @code{Customize->Browse IDLWAVE Group}. Here you'll be presented  @file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE
590  with all the various variables grouped into categories.  You can  Group}. Here you'll be presented with all the various variables grouped
591  navigate the hierarchy (e.g. Idlwave Code Formatting->Idlwave Main Block  into categories.  You can navigate the hierarchy (e.g. Idlwave Code
592  Indent), read about the variables, change them, and `Save for Future  Formatting->Idlwave Main Block Indent), read about the variables, change
593  Sessions'.  Few of these variables need customization, but you can  them, and `Save for Future Sessions'.  Few of these variables need
594  exercise considerable control over IDLWAVE's functionality with them.  customization, but you can exercise considerable control over IDLWAVE's
595    functionality with them.
596  Many people I talk to find the key bindings used for the debugging  
597  commands too long and complicated.  Do I always have to type @kbd{C-c  You may also find the key bindings used for the debugging commands too
598  C-d C-c} to get a single simple command?  Due to Emacs rules and  long and complicated.  Often we have heard such complaints, ``Do I
599  conventions I cannot make better bindings by default, but you can.  really have to type @kbd{C-c C-d C-c} to run a simple command?''  Due to
600  First, there is a way to assign all debugging commands in a single sweep  Emacs rules and conventions, shorter bindings cannot be set by default,
601  to other combinations.  The only problem is that we have to use  but you can enable them.  First, there is a way to assign all debugging
602  something which Emacs does not need for other important commands.  A  commands in a single sweep to other combinations.  The only problem is
603  good option is to execute debugging commands by holding down  that we have to use something which Emacs does not need for other
604  @key{CONTROL} and @key{SHIFT} while pressing a single character:  important commands.  One good option is to execute debugging commands by
605  @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for compiling the  holding down @key{CONTROL} and @key{SHIFT} while pressing a single
606  current source file, @kbd{C-S-a} for deleting all breakpoints.  You can  character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for
607  have this with  compiling the current source file, @kbd{C-S-a} for deleting all
608    breakpoints.  You can enable this with:
609    
610  @lisp  @lisp
611  (setq idlwave-shell-debug-modifiers '(shift control))  (setq idlwave-shell-debug-modifiers '(shift control))
612  @end lisp  @end lisp
613    
614  If you have a special keyboard with for example a @key{HYPER} key, you  @noindent If you have a special keyboard with, for example, a
615  could use  @key{HYPER} key, you could even shorten that:
616    
617  @lisp  @lisp
618  (setq idlwave-shell-debug-modifiers '(hyper))  (setq idlwave-shell-debug-modifiers '(hyper))
619  @end lisp  @end lisp
620    
621  instead to get compilation on @kbd{H-c}.  @noindent to get compilation on @kbd{H-c}.  Often, a modifier key like
622    @key{HYPER} or @key{SUPER} is bound or can be bound to an otherwise
623  You can also assign specific commands to function keys.  This you must  unused key -- consult your system documentation.
624  do in the @emph{mode-hook}, a special function which is run when a new  
625  buffer gets set up.  Keybindings can only be done when the buffer  You can also assign specific commands to keys.  This you must do in the
626  exists.  The possibilities for key customization are endless.  Here we  @emph{mode-hook}, a special function which is run when a new buffer gets
627  set function keys f5-f8 to common debugging commands.  set up.  Keybindings can only be done when the buffer exists.  The
628    possibilities for key customization are endless.  Here we set function
629    keys f5-f8 to common debugging commands.
630    
631  @lisp  @lisp
632  ;; First for the source buffer  ;; First for the source buffer
# Line 616  set function keys f5-f8 to common debugg Line 645  set function keys f5-f8 to common debugg
645      (local-set-key [f8] 'idlwave-shell-clear-all-bp)))      (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
646  @end lisp  @end lisp
647    
648  @section Lession III: Library Catalog  @node  Lesson III -- Library Catalog,  , Lesson II -- Customization, Getting Started
649    @section Lesson III: Library Catalog
650    
651  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
652  tutorial.  This was the key @kbd{C-c ?} which displays information about  tutorial.  This was the key @kbd{C-c ?} which displays information about
653  the IDL routine near the cursor position.  Wouldn't it be nice  the IDL routine near the cursor position.  Wouldn't it be nice
654  to have the same available for your own library routines and for the  to have the same available for your own library routines and for the
655  huge amount of code in major extension libraries like JHUPL or the  huge amount of code in major extension libraries like JHUPL or the
# Line 635  Simply select them all (or whichever you Line 665  Simply select them all (or whichever you
665  collects information for each and every IDL routine on your search path.  collects information for each and every IDL routine on your search path.
666  All this information is written to the file @file{.idlcat} in your home  All this information is written to the file @file{.idlcat} in your home
667  directory and will from now one be automatically loaded whenever you use  directory and will from now one be automatically loaded whenever you use
668  IDLWAVE.  Try to use routine info (@kbd{C-c ?}) or completion  IDLWAVE.  You may find it necessary to rebuild the catalog on occasion
669  (@kbd{M-<TAB>}) while on any routine or partial routine name you know to  as your local libraries change.  Try to use routine info (@kbd{C-c ?})
670  be located in the library.  E.g., if you have scanned the IDL-Astro  or completion (@kbd{M-@key{TAB}}) while on any routine or partial routine
671  library:  name you know to be located in the library.  E.g., if you have scanned
672    the IDL-Astro library:
673    
674  @example  @example
675      a=readf@key{M-<TAB>}      a=readf@key{M-<TAB>}
# Line 663  On the way you will want to change other Line 694  On the way you will want to change other
694  the possibilities not discussed in this short tutorial.  Read the  the possibilities not discussed in this short tutorial.  Read the
695  manual, look at the documentation strings of interesting variables (with  manual, look at the documentation strings of interesting variables (with
696  @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining  @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining
697  questions on @code{comp.lang.idl-pvwave}.  questions on the newsgroup @code{comp.lang.idl-pvwave}.
698    
699  @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top  @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top
700  @chapter The IDLWAVE Major Mode  @chapter The IDLWAVE Major Mode
701  @cindex IDLWAVE major mode  @cindex IDLWAVE major mode
702  @cindex Major mode, @code{idlwave-mode}  @cindex Major mode, @code{idlwave-mode}
703    
704  The IDLWAVE major mode supports editing IDL and WAVE/CL command files.  The IDLWAVE major mode supports editing IDL source files.  In this
705  In this chapter we describe the main features of the mode and how to  chapter we describe the main features of the mode and how to customize
706  customize them.  them.
707    
708  @menu  @menu
709  * Code Formatting::             Making code look nice  * Code Formatting::             Making code look nice
710  * Routine Info::                Calling Sequence and Keyword List  * Routine Info::                Calling Sequence and Keyword List
711  * Online Help::                 One key press from source to help  * Online Help::                 One key press from source to help
712  * Completion::                  Completing routine names and Keywords  * Completion::                  Completing routine names and Keywords
713  * Routine Source::              How to visit the source file of routine XYZ  * Routine Source::              Finding routines, the easy way
714  * Resolving Routines::          Force the Shell to compile a routine  * Resolving Routines::          Force the Shell to compile a routine
715  * Code Templates::              Abbreviations for frequent constructs  * Code Templates::              Frequent code constructs
716    * Abbreviations::               Abbreviations for common commands
717  * Actions::                     Changing case, Padding, End checking  * Actions::                     Changing case, Padding, End checking
718  * Doc Header::                  Inserting a standard header  * Doc Header::                  Inserting a standard header
719  * Motion Commands::             Moving through the structure of a program  * Motion Commands::             Moving through the structure of a program
# Line 695  customize them. Line 727  customize them.
727    
728  @menu  @menu
729  * Code Indentation::            Reflecting the logical structure  * Code Indentation::            Reflecting the logical structure
730    * Continued Statement Indentation::
731  * Comment Indentation::         Special indentation for comment lines  * Comment Indentation::         Special indentation for comment lines
732  * Continuation Lines::          Splitting statements over lines  * Continuation Lines::          Splitting statements over lines
733  * Syntax Highlighting::         Font-lock support  * Syntax Highlighting::         Font-lock support
734    * Octals and Highlighting::     Why "123 causes problems
735  @end menu  @end menu
736    
737  @node Code Indentation, Comment Indentation, Code Formatting, Code Formatting  The IDL language, with it's early roots in FORTRAN, modern
738  @subsection Code Indentation  implementation in C, and liberal borrowing of features of many vector
739  @cindex Code indentation  languages along its 25+ year history, has inherited an unusual mix of
740  @cindex Indentation  syntax elements.  Left to his or her own devices, a novice IDL
741    programmer will often conjure code which is very difficult to read and
742  Like all Emacs programming modes, IDLWAVE performs code indentation.  impossible to adapt.  Much can be gleaned from studying available IDL
743  The @key{TAB} key indents the current line relative to context.  code libraries for coding style pointers, but, due to the variety of
744  @key{LFD} insert a newline and indents the new line.  The indentation is  IDL syntax elements, replicating this style can be challenging at
745  governed by a number of variables.  best.  Luckily, IDLWAVE understands the structure of IDL code very
746    well, and takes care of almost all formatting issues for you.  After
747    configuring it to match your coding standards, you can rely on it to
748    help keep your code neat and organized.
749    
750  @cindex Foreign code, adapting  @cindex Foreign code, adapting
751  @cindex Indentation, of foreign code  @cindex Indentation, of foreign code
# Line 720  commands are @kbd{C-x h} (the entire fil Line 757  commands are @kbd{C-x h} (the entire fil
757  current subprogram). @xref{Actions}, for information how to impose  current subprogram). @xref{Actions}, for information how to impose
758  additional formatting conventions on foreign code.  additional formatting conventions on foreign code.
759    
760  @defopt idlwave-main-block-indent (@code{0})  @node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting
761    @subsection Code Indentation
762    @cindex Code indentation
763    @cindex Indentation
764    
765    Like all Emacs programming modes, IDLWAVE performs code indentation.
766    The @key{TAB} key indents the current line relative to context.
767    @key{LFD} insert a newline and indents the new line.  The indentation is
768    governed by a number of variables.  IDLWAVE indents blocks (between
769    @code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and
770    continuation lines.
771    
772    @defopt idlwave-main-block-indent (@code{0})
773  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
774  the FUNCTION/PRO statement and the END statement for that program  the FUNCTION/PRO statement and the END statement for that program
775  unit.  unit.
776  @end defopt  @end defopt
777    
778  @defopt idlwave-block-indent (@code{5})  @defopt idlwave-block-indent (@code{4})
779  Extra indentation applied to block lines.  If you change this, you  Extra indentation applied to block lines.  If you change this, you
780  probably also want to change @code{idlwave-end-offset}.  probably also want to change @code{idlwave-end-offset}.
781  @end defopt  @end defopt
# Line 737  Extra indentation applied to block END l Line 786  Extra indentation applied to block END l
786  BEGIN lines.  BEGIN lines.
787  @end defopt  @end defopt
788    
789    @node Continued Statement Indentation, Comment Indentation, Code Indentation, Code Formatting
790    @subsection Continued Statement Indentation
791    @cindex Indentation, continued statement
792    @cindex Continued statement indentation
793    Continuation lines (following a line ending with @code{$}) can receive a
794    fixed indentation offset from the main level, but in several situations
795    IDLWAVE can use a special form of indentation which aligns continued
796    statements more naturally.  Special indentation is calculated for
797    continued routine definition statements and calls, enclosing parentheses
798    (like function calls, structure/class definitions, explicit structures
799    or lists, etc.), and continued assignments.  An attempt is made to line
800    up with the first non-whitespace character after the relevant opening
801    punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}).  For
802    lines without any non-comment characters on the line with the opening
803    punctuation, the continued line(s) are aligned just past the
804    punctuation.  An example:
805    
806    @example
807    function foo, a, b,  $
808                  c, d
809      bar =  sin( a + b + $
810                  c + d)
811    end
812    @end example
813    @noindent
814    
815    The only drawback to this special continued statement indentation is
816    that it consumes more space, e.g., for long function names or left hand
817    sides of an assignment:
818    
819    @example
820    function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $
821                                                                c, d
822    @end example
823    
824    You can instruct IDLWAVE when to avoid using this special continuation
825    indentation by setting the variable
826    @code{idlwave-max-extra-continuation-indent}, which specifies the
827    maximum additional indentation beyond the basic indent to be
828    tolerated, otherwise defaulting to a fixed-offset from the enclosing
829    indent (the size of which offset is set in
830    @code{idlwave-continuation-indent}).  Also, since the indentation
831    level can be somewhat dynamic in continued statements with special
832    continuation indentation, especially if
833    @code{idlwave-max-extra-continuation-indent} is small, the key
834    @kbd{C-u @key{TAB}} will re-indent all lines in the current statement.
835    Note that @code{idlwave-indent-to-open-paren}, if non-nil, overrides
836    the @code{idlwave-max-extra-continuation-indent} limit, for
837    parentheses only, forcing them always to line up.
838    
839    
840  @defopt idlwave-continuation-indent (@code{2})  @defopt idlwave-continuation-indent (@code{2})
841  Extra indentation applied to continuation lines and inside unbalanced  Extra indentation applied to normal continuation lines.
 parenthesis.  
842  @end defopt  @end defopt
843    
844  @node Comment Indentation, Continuation Lines, Code Indentation, Code Formatting  @defopt idlwave-max-extra-continuation-indent (@code{20})
845    The maximum additional indentation (over the basic continuation-indent)
846    that will be permitted for special continues.  To effectively disable
847    special continuation indentation, set to @code{0}.  To enable it
848    constantly, set to a large number (like @code{100}).  Note that the
849    indentation in a long continued statement never decreases from line to
850    line, outside of nested parentheses statements.
851    @end defopt
852    
853    @defopt idlwave-indent-to-open-paren (@code{t})
854    Non-@code{nil} means indent continuation lines to innermost open
855    parenthesis, regardless of whether the
856    @code{idlwave-max-extra-continuation-indent} limit is satisfied.
857    @end defopt
858    
859    @node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting
860  @subsection Comment Indentation  @subsection Comment Indentation
861  @cindex Comment indentation  @cindex Comment indentation
862  @cindex Hanging paragraphs  @cindex Hanging paragraphs
# Line 759  unchanged. Line 873  unchanged.
873  @item @code{;;}  @item @code{;;}
874  @tab Lines starting with two semicolons are indented like the surrounding code.  @tab Lines starting with two semicolons are indented like the surrounding code.
875  @item @code{;}  @item @code{;}
876  @tab Lines starting with a single semicolon are indent to a minimum column.  @tab Lines starting with a single semicolon are indented to a minimum column.
877  @end multitable  @end multitable
878    
879  @noindent  @noindent
880  The indentation of comments starting in column 0 is never changed.  The indentation of comments starting in column 0 is never changed.
881    
882  @defopt idlwave-no-change-comment  @defopt idlwave-no-change-comment
883  The indentation of a comment starting with this regexp will not be changed.  The indentation of a comment starting with this regexp will not be
884    changed.
885  @end defopt  @end defopt
886    
887  @defopt idlwave-begin-line-comment  @defopt idlwave-begin-line-comment
# Line 788  IDL code. Line 903  IDL code.
903  @kindex M-@key{RET}  @kindex M-@key{RET}
904  In IDL, a newline character terminates a statement unless preceded by a  In IDL, a newline character terminates a statement unless preceded by a
905  @samp{$}.  If you would like to start a continuation line, use  @samp{$}.  If you would like to start a continuation line, use
906  @kbd{M-@key{RET}} which calls the command @code{idlwave-split-line}.  It  @kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}.
907  inserts a @samp{$} to indicate that the following line is a continuation  It inserts the continuation character @samp{$}, terminates the line and
908  of the current line, terminates the line with a newline and indents the  indents the new line.  The command @kbd{M-@key{RET}} can also be invoked
909  new line.  The command @kbd{M-@key{RET}} can also be used in the middle  inside a string to split it at that point, in which case the @samp{+}
910  of a line to split the line at that point.  When used inside a long  concatenation operator is used.
 string constant, the string is split with the @samp{+} concatenation  
 operator.  
911    
912  @cindex Filling  @cindex Filling
913  @cindex @code{auto-fill-mode}  @cindex @code{auto-fill-mode}
914  @cindex Hanging paragraphs  @cindex Hanging paragraphs
915  When filling comment paragraphs, IDLWAVE overloads the normal filling  When filling comment paragraphs, IDLWAVE overloads the normal filling
916  functions and uses a function which creates hanging paragraphs as they  functions and uses a function which creates the hanging paragraphs
917  are customary in the IDL routine headers.  When @code{auto-fill-mode} is  customary in IDL routine headers.  When @code{auto-fill-mode} is turned
918  turned on (toggle with @kbd{C-c C-a}), comments will be auto-filled.  If  on (toggle with @kbd{C-c C-a}), comments will be auto-filled.  If the
919  the first line of a paragraph is matched by  first line of a paragraph contains a match for
920  @code{idlwave-hang-indent-regexp}, subsequent lines are indented to  @code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent
921  after the position of this match, as in the following example.  lines are positioned to line up after it, as in the following example.
922    
923  @example  @example
924  ; INPUTS:  @group
925    ;=================================
926  ; x - an array containing  ; x - an array containing
927  ;     lots of interesting numbers.  ;     lots of interesting numbers.
928  ;  ;
929  ; y - another variable where  ; y - another variable where
930  ;     a hanging paragraph is used  ;     a hanging paragraph is used
931  ;     to describe it.  ;     to describe it.
932    ;=================================
933    @end group
934  @end example  @end example
935    
936  @kindex M-q  @kindex M-q
937  You also refill a comment paragraph with @kbd{M-q}.  You can also refill a comment at any time paragraph with @kbd{M-q}.
938    Comment delimiting lines as in the above example, consisting of one or
939    more @samp{;} followed by one or more of the characters @samp{+=-_*},
940    are kept in place, as is.
941    
942  @defopt idlwave-fill-comment-line-only (@code{t})  @defopt idlwave-fill-comment-line-only (@code{t})
943  Non-@code{nil} means auto fill will only operate on comment lines.  Non-@code{nil} means auto fill will only operate on comment lines.
# Line 840  indent given by @code{idlwave-hang-inden Line 959  indent given by @code{idlwave-hang-inden
959  line of the paragraph.  line of the paragraph.
960  @end defopt  @end defopt
961    
962  @defopt idlwave-hang-indent-regexp  @defopt idlwave-hang-indent-regexp (@code{"- "})
963  Regular expression matching the position of the hanging indent  Regular expression matching the position of the hanging indent
964  in the first line of a comment paragraph.  in the first line of a comment paragraph.
965  @end defopt  @end defopt
966    
967  @defopt idlwave-use-last-hang-indent (@code{nil})  @defopt idlwave-use-last-hang-indent (@code{nil})
968  Non-@code{nil} means use last match on line for  Non-@code{nil} means use last match on line for
969  @code{idlwave-indent-regexp}.  @code{idlwave-indent-regexp}.
970  @end defopt  @end defopt
971    
972  @node Syntax Highlighting,  , Continuation Lines, Code Formatting  @node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting
973  @subsection Syntax Highlighting  @subsection Syntax Highlighting
974  @cindex Syntax highlighting  @cindex Syntax highlighting
975  @cindex Highlighting of syntax  @cindex Highlighting of syntax
# Line 858  Non-@code{nil} means use last match on l Line 977  Non-@code{nil} means use last match on l
977    
978  Highlighting of keywords, comments, strings etc. can be accomplished  Highlighting of keywords, comments, strings etc. can be accomplished
979  with @code{font-lock}.  If you are using @code{global-font-lock-mode}  with @code{font-lock}.  If you are using @code{global-font-lock-mode}
980  (on Emacs), or have @code{font-lock} turned on in any other buffer in  (in Emacs), or have @code{font-lock} turned on in any other buffer in
981  XEmacs, it should also automatically work in IDLWAVE buffers.  If not,  XEmacs, it should also automatically work in IDLWAVE buffers.  If you'd
982  you can enforce it with the following line in your @file{.emacs}  prefer invoking font-lock individually by mode, you can enforce it in
983    @code{idlwave-mode} with the following line in your @file{.emacs}:
984    
985  @lisp  @lisp
986  (add-hook 'idlwave-mode-hook 'turn-on-font-lock)  (add-hook 'idlwave-mode-hook 'turn-on-font-lock)
987  @end lisp  @end lisp
988    
989  IDLWAVE supports 3 levels of syntax highlighting.  The variable  @noindent IDLWAVE supports 3 increasing levels of syntax highlighting.
990  @code{font-lock-maximum-decoration} determines which level is selected.  The variable @code{font-lock-maximum-decoration} determines which level
991    is selected.  Individual categories of special tokens can be selected
992    for highlighting using the variable
993    @code{idlwave-default-font-lock-items}.
994    
995  @defopt idlwave-default-font-lock-items  @defopt idlwave-default-font-lock-items
996  Items which should be fontified on the default fontification level  Items which should be fontified on the default fontification level
997  2.  2.
998  @end defopt  @end defopt
999    
1000    @node Octals and Highlighting,  , Syntax Highlighting, Code Formatting
1001    @subsection Octals and Highlighting
1002    @cindex Syntax highlighting, Octals
1003    @cindex Highlighting of syntax, Octals
1004    
1005    A rare syntax highlighting problem results from the extremely
1006    unfortunate notation for octal numbers in IDL: @code{"123}.  This
1007    unpaired quotation mark is very difficult to parse, given that it can be
1008    mixed on a single line with any number of strings.  Emacs will
1009    incorrectly identify this as a string, and the highlighting of following
1010    lines of code can be distorted, since the string is never terminated.
1011    
1012    One solution to this involves terminating the mistakenly identified
1013    string yourself by providing a closing quotation mark in a comment:
1014    
1015    @example
1016      string("305B) + $ ;" <--- for font-lock
1017       ' is an Angstrom.'
1018    @end example
1019    
1020    @noindent A far better solution is to abandon this notation for octals
1021    altogether, and use the more sensible alternative IDL provides:
1022    
1023    @example
1024       string('305'OB) + ' is an Angstrom.'
1025    @end example
1026    
1027    @noindent This simultaneously solves the font-lock problem and is more
1028    consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}.
1029    
1030  @node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode  @node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode
1031  @section Routine Info  @section Routine Info
1032  @cindex Routine info  @cindex Routine info
# Line 883  Items which should be fontified on the d Line 1036  Items which should be fontified on the d
1036  @cindex Shell, querying for routine info  @cindex Shell, querying for routine info
1037    
1038  @kindex C-c C-i  @kindex C-c C-i
1039  IDL defines more than one thousand procedures, functions and object  IDL comes bundled with more than one thousand procedures, functions
1040  methods.  This large command set makes it difficult to remember the  and object methods, and large libraries typically contain hundreds or
1041  calling sequence and keywords of a command.  IDLWAVE contains a list of  even thousands more (each with a few to tens of keywords and
1042  all builtin routines with calling sequences and keywords@footnote{This  arguments).  This large command set can make it difficult to remember
1043  list was created by scanning the IDL manual and might contain (very few)  the calling sequence and keywords for the routines you use, but
1044  errors.  Please report any detected errors to the maintainer, so that  IDLWAVE can help.  It builds up routine information using a wide
1045  they can be fixed.}.  It also scans Emacs buffers and library files for  variety of sources: IDLWAVE in fact knows far more about the routines
1046  routine definitions and queries the IDLWAVE-Shell for the properties of  on your system than IDL itself.  It maintains a list of all built-in
1047  modules currently compiled under the shell.  This information is updated  routines, with calling sequences and keywords@footnote{This list is
1048  automatically.  If you think the information is not up-to-date, use  created by scanning the IDL manuals and might contain (very few)
1049  @kbd{C-c C-i} (@code{idlwave-update-routine-info}) to enforce a global  errors.  Please report any errors to the maintainer, so that they can
1050  update.  be fixed.}.  It also scans Emacs buffers and library files for routine
1051    definitions, and queries the IDLWAVE-Shell for information about
1052    routines currently compiled there.  This information is updated
1053    automatically, and so should usually be current.  To force a global
1054    update and refresh the routine information, use @kbd{C-c C-i}
1055    (@code{idlwave-update-routine-info}).
1056    
1057  @kindex C-c ?  @kindex C-c ?
1058  To display the information about a routine, press @kbd{C-c ?} which  To display the information about a routine, press @kbd{C-c ?}, which
1059  calls the command @code{idlwave-routine-info}.  When the current cursor  calls the command @code{idlwave-routine-info}.  When the current cursor
1060  position is on the name or in the argument list of a procedure or  position is on the name or in the argument list of a procedure or
1061  function, information will be displayed about the routine.  For example,  function, information will be displayed about the routine.  For example,
1062  consider the cursor positions in the following line  consider the indicated cursor positions in the following line:
1063    
1064  @example  @example
1065  plot,x,alog(x+5*sin(x) + 2),  plot,x,alog(x+5*sin(x) + 2),
1066      |  |   |   |   |  |  |    |
1067    1  2   3   4   5  6  7    8    1  2   3   4   5  6  7    8
1068  @end example  @end example
1069    
1070  @cindex Default routine, for info and help  @cindex Default routine, for info and help
1071  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
1072  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
1073  described, while positions 5 and 6 will select the @samp{sin} function.  described, while positions 5 and 6 will investigate the @samp{sin}
1074    function.
1075    
1076  When you ask for routine information about an object method, and the  When you ask for routine information about an object method, and the
1077  method exists in several classes, IDLWAVE queries for the class of the  method exists in several classes, IDLWAVE queries for the class of the
1078  object.  object, unless the class is already known through a text property on the
1079    @samp{->} operator (@pxref{Object Method Completion and Class
1080    Ambiguity}), or by having been explicitly included in the call
1081    (e.g. @code{a->myclass::Foo}).
1082    
1083  @cindex Calling sequences  @cindex Calling sequences
1084  @cindex Keywords of a routine  @cindex Keywords of a routine
# Line 941  If a definition of this routine exists i Line 1105  If a definition of this routine exists i
1105  IDLWAVE, several @samp{Source} lines will point to the different files.  IDLWAVE, several @samp{Source} lines will point to the different files.
1106  This may indicate that your routine is shadowing a library routine,  This may indicate that your routine is shadowing a library routine,
1107  which may or may not be what you want (@pxref{Load-Path Shadows}).  The  which may or may not be what you want (@pxref{Load-Path Shadows}).  The
1108  information about the calling sequence and the keywords is derived from  information about the calling sequence and keywords is derived from the
1109  the first source listed.  Library routines can only be supported if you  first source listed.  Library routines are supported only if you have
1110  have scanned the local IDL library (@pxref{Library Catalog}).  The source  scanned your local IDL libraries (@pxref{Library Catalog}).  The source
1111  entry consists of a @emph{source category}, a set of @emph{flags} and  entry consists of a @emph{source category}, a set of @emph{flags} and
1112  the path to the @emph{source file}.  The following categories  the path to the @emph{source file}.  The following categories exist:
 exist:  
1113    
1114  @multitable @columnfractions .15 .85  @multitable @columnfractions .15 .85
1115  @item @i{System}  @item @i{System}
1116  @tab A system routine, but we do not know if it is @i{Builtin} or  @tab A system routine of unknown origin.  When the system library has
1117  @i{SystemLib}.  When the system library has bee scanned  been scanned (@pxref{Library Catalog}), this category will automatically
1118  (@pxref{Library Catalog}), this category will automatically split into the  split into the next two.
 next two.  
1119  @item @i{Builtin}  @item @i{Builtin}
1120  @tab A builtin routine with no source code available.  @tab A builtin system routine with no source code available.
1121  @item @i{SystemLib}  @item @i{SystemLib}
1122  @tab A library routine in the official lib directory @file{!DIR/lib}.  @tab A library system routine in the official lib directory @file{!DIR/lib}.
1123  @item @i{Obsolete}  @item @i{Obsolete}
1124  @tab A library routine in the official lib directory @file{!DIR/lib/obsolete}.  @tab A library routine in the official lib directory @file{!DIR/lib/obsolete}.
1125  @item @i{Library}  @item @i{Library}
1126  @tab A file on IDL's search path @code{!PATH}.  @tab A routine in a file on IDL's search path @code{!PATH}.
1127  @item @i{Other}  @item @i{Other}
1128  @tab Any other file not known to be on the search path.  @tab Any other routine with a file not known to be on the search path.
1129  @item @i{Unresolved}  @item @i{Unresolved}
1130  @tab The shell lists this routine as unresolved.  @tab An otherwise unkown routine the shell lists as unresolved
1131    (referenced, but not compiled).
1132  @end multitable  @end multitable
1133    
1134  You can define additional categories based on the file name and path  You can create additional categories based on the routine's filepath
1135  with the variable @code{idlwave-special-lib-alist}.  with the variable @code{idlwave-special-lib-alist}.  This is useful for
1136    easy discrimination of various libraries, or even versions of the same
1137    library.
1138    
1139  @cindex Flags, in routine info  @cindex Flags, in routine info
1140  @cindex Duplicate routines  @cindex Duplicate routines
1141  @cindex Multiply defined routines  @cindex Multiply defined routines
1142  @cindex Routine definitions, multiple  @cindex Routine definitions, multiple
1143  The flags @code{[CSB]} indicate if the file is known to IDLWAVE from the  The flags @code{[CSB]} indicate the source of the information IDLWAVE
1144  library catalog (@w{@code{[C--]}}, @pxref{Library Catalog}), from the Shell  has regarding the file: from a library catalog (@w{@code{[C--]}},
1145  (@w{@code{[-S-]}}) or from an Emacs buffer (@w{@code{[--B]}}).  @pxref{Library Catalog}), from the IDL Shell (@w{@code{[-S-]}}) or from
1146  Combinations are possible.  If a file contains multiple definitions of  an Emacs buffer (@w{@code{[--B]}}).  Combinations are possible (a
1147  the same routine, the file name will be prefixed with @samp{(Nx)} where  compiled library routine visited in a buffer might read
1148  @samp{N} is the number of definitions.  @w{@code{[CSB]}}).  If a file contains multiple definitions of the same
1149    routine, the file name will be prefixed with @samp{(Nx)} where @samp{N}
1150    is the number of definitions.
1151    
1152  @cindex Online Help from the routine info buffer  @cindex Online Help from the routine info buffer
1153  @cindex Active text, in routine info  @cindex Active text, in routine info
1154  @cindex Inserting keywords, from routine info  @cindex Inserting keywords, from routine info
1155  @cindex Source file, access from routine info  @cindex Source file, access from routine info
1156  Some of the text in the @file{*Help*} buffer will be active (it  Some of the text in the @file{*Help*} routine info buffer will be active
1157  highlights when you move the mouse over it).  Clicking on these items  (it is highlighted when the mouse moves over it).  Typically, clicking
1158  will have the following effects:  with the right mouse button invokes online help lookup, and clicking
1159    with the middle mouse button inserts keywords or visits files:
1160    
1161  @multitable @columnfractions 0.15 0.85  @multitable @columnfractions 0.15 0.85
1162  @item @i{Usage}  @item @i{Usage}
1163  @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
1164  button on the @i{Usage:} line will access the help for the  button on the @i{Usage:} line will access the help for the
1165  routine (@pxref{Online Help}).    routine (@pxref{Online Help}).
1166  @item @i{Keyword}  @item @i{Keyword}
1167  @tab Online help about keywords is also available with the  @tab Online help about keywords is also available with the
1168  @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 1012  window. Line 1180  window.
1180  @tab The @i{Classes} line is only included in the routine info window if  @tab The @i{Classes} line is only included in the routine info window if
1181  the current class inherits from other classes.  You can click with the  the current class inherits from other classes.  You can click with the
1182  @emph{middle} mouse button to display routine info about the current  @emph{middle} mouse button to display routine info about the current
1183  method in other classes on the inheritance chain.  method in other classes on the inheritance chain, if such a method
1184    exists there.
1185  @end multitable  @end multitable
1186    
1187  @defopt idlwave-resize-routine-help-window (@code{t})  @defopt idlwave-resize-routine-help-window (@code{t})
1188  Non-@code{nil} means, resize the Routine-info @file{*Help*} window to  Non-@code{nil} means resize the Routine-info @file{*Help*} window to
1189  fit the content.  fit the content.
1190  @end defopt  @end defopt
1191    
# Line 1028  Alist of regular expressions matching sp Line 1197  Alist of regular expressions matching sp
1197  Maximum number of source files displayed in the Routine Info window.  Maximum number of source files displayed in the Routine Info window.
1198  @end defopt  @end defopt
1199    
 @page  
1200    
1201  @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode  @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode
1202  @section Online Help  @section Online Help
# Line 1043  Maximum number of source files displayed Line 1211  Maximum number of source files displayed
1211  For IDL system routines, RSI provides extensive documentation.  IDLWAVE  For IDL system routines, RSI provides extensive documentation.  IDLWAVE
1212  can access an ASCII version of this documentation very quickly and  can access an ASCII version of this documentation very quickly and
1213  accurately.  This is @emph{much} faster than using the IDL online help  accurately.  This is @emph{much} faster than using the IDL online help
1214  application, also because usually IDLWAVE gets you to the right place in  application, because IDLWAVE usually gets you to the right place in the
1215  the docs directly, without additional browsing and scrolling.  For this  documentation directly, without any additional browsing and scrolling.
1216  online help to work, you need an ASCII version of the IDL documentation  For this online help to work, an ASCII version of the IDL documentation,
1217  which is not part of the standard IDLWAVE distribution.  The required  which is not part of the standalone IDLWAVE distribution, is required.
1218  files can be downloaded from @uref{@value{IDLWAVE-HOMEPAGE}, the  The necessary help files can be downloaded from
1219  maintainers webpage}.  As the text is extracted from PDF files, the  @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}.  The text
1220  formatting of the help text is good for normal text, but graphics and  extracted from the PDF files is fine for normal documentation
1221  multiline equations will not be well represented.  See also  paragraphs, but graphics and multiline equations will not be well
1222  @ref{Documentation Scan}.  formatted.  See also @ref{Documentation Scan}.
1223    
1224    @cindex Updated online help
1225    @cindex Online help, updates
1226    @cindex @code{<NEW>..</NEW>}
1227    Occasionally RSI releases a synopsis of new features in an IDL release,
1228    without simultaneously updating the documentation files, instead
1229    preferring a @i{What's New} document which describes the changes.  These
1230    updates are incorporated directly into the IDLWAVE online help, and are
1231    delimited in @code{<NEW>..</NEW>} blocks.
1232    
1233  @cindex Source code, as online help  @cindex Source code, as online help
1234  @cindex DocLib header, as online help  @cindex DocLib header, as online help
1235  For routines which are not documented in the IDL manual (for example  For routines which are not documented in the IDL manual (for example
1236  your own routines), the source code is used as help text.  If the  personal or library routines), the source code itself is used as help
1237  requested information can be found in a (more or less) standard DocLib  text.  If the requested information can be found in a (more or less)
1238  file header, IDLWAVE shows the header.  Otherwise the routine definition  standard DocLib file header, IDLWAVE shows the header (scrolling down to
1239  statement (@code{pro}/@code{function}) is shown.  appropriate keyword).  Otherwise the routine definition statement
1240    (@code{pro}/@code{function}) is shown.
1241    
1242    @cindex Structure tags, in online help
1243    @cindex Class tags, in online help
1244    Help is also available for class structure tags (@code{self.TAG}), and
1245    generic structure tags, if structure tag completion is enabled
1246    (@pxref{Structure Tag Completion}).  This is implemented by visiting the
1247    tag within the class or structure definition source itself.  Help is not
1248    available on built-in system class tags.
1249    
1250  @kindex M-?  @kindex M-?
1251  In any IDL program, press @kbd{M-?} (@code{idlwave-context-help}) or  In any IDL program (or, as with most IDLWAVE commands, in the IDL
1252  click with @kbd{S-Mouse-3} to access context sensitive online help.  The  Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with
1253  following locations are recognized as context:  @kbd{S-Mouse-3} to access context sensitive online help.  The following
1254    locations are recognized context for help:
1255    
1256  @cindex Context, for online help  @cindex Context, for online help
1257  @multitable @columnfractions .25 .75  @multitable @columnfractions .25 .75
1258  @item @i{Routine name}  @item @i{Routine name}
1259  @tab The name of a routine (function, procedure, method).  @tab The name of a routine (function, procedure, method).
1260  @item @i{Keyword Parameter}  @item @i{Keyword Parameter}
1261  @tab Keyword parameter of a routine.  @tab A keyword parameter of a routine.
1262  @item @i{System Variable}  @item @i{System Variable}
1263  @tab System variable like @code{!DPI}.  @tab System variables like @code{!DPI}.
1264  @item @i{IDL Statement}  @item @i{IDL Statement}
1265  @tab Like @code{PRO}, @code{REPEAT}, or @code{COMPILE_OPT}.  @tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc.
1266  @item @i{Class name}  @item @i{Class name}
1267  @tab Class name in @code{OBJ_NEW} call.  @tab A class name in an @code{OBJ_NEW} call.
1268    @item @i{Class Init}
1269    @tab Beyond the class name in an @code{OBJ_NEW} call.
1270  @item @i{Executive Command}  @item @i{Executive Command}
1271  @tab Executive command like @code{.RUN}.  Mostly useful in the shell.  @tab An executive command like @code{.RUN}.  Mostly useful in the shell.
1272    @item @i{Structure Tags}
1273    @tab In structure tags like @code{state.xsize}
1274    @item @i{Structure Tags}
1275    @tab In class tags like @code{self.value}.
1276  @item @i{Default}  @item @i{Default}
1277  @tab The routine that would be selected for routine info display.  @tab The routine that would be selected for routine info display.
1278  @end multitable  @end multitable
# Line 1102  Online help for routines and keywords ca Line 1295  Online help for routines and keywords ca
1295  Routine Info display.  Click with @kbd{Mouse-3} on an item to see the  Routine Info display.  Click with @kbd{Mouse-3} on an item to see the
1296  corresponding help (@pxref{Routine Info}).  corresponding help (@pxref{Routine Info}).
1297  @item  @item
1298  When using completion and Emacs pops up a window with possible  When using completion and Emacs pops up a @file{*Completions*} buffer
1299  completions, clicking with @kbd{Mouse-3} on a completion item invokes  with possible completions, clicking with @kbd{Mouse-3} on a completion
1300  help on that item (@pxref{Completion}).  item invokes help on that item (@pxref{Completion}).  Items for which
1301    help is available in the online system documentation (vs. just the
1302    program source itself) will be emphasized (e.g. colored blue).
1303  @end itemize  @end itemize
1304  @noindent  @noindent
1305  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 the
1306  IDL manual.  IDL manual, but an attempt will be made to visit non-blue items directly
1307    in the originating source file.
 @page  
1308    
1309  @cindex Help application, key bindings  @cindex Help application, key bindings
1310  @cindex Key bindings, in help application  @cindex Key bindings, in help application
1311  The help window is normally displayed in a separate frame.  The  The help window is normally displayed in a separate frame.  The
1312  following commands can be used to navigate inside the help system.  following commands can be used to navigate inside the help system:
1313    
1314  @multitable  @columnfractions .15 .85  @multitable  @columnfractions .15 .85
1315  @item @kbd{@key{SPACE}}  @item @kbd{@key{SPACE}}
# Line 1144  methods and back. Line 1338  methods and back.
1338    
1339  @sp 1  @sp 1
1340  @noindent When the help text is a source file, the following commands  @noindent When the help text is a source file, the following commands
1341  are also available.  are also available:
1342    
1343  @multitable  @columnfractions .15 .85  @multitable  @columnfractions .15 .85
1344  @item @kbd{h}  @item @kbd{h}
1345  @tab Jump to DocLib Header of the routine whose source is displayed  @tab Jump to DocLib Header of the routine whose source is displayed
# Line 1164  The directory where idlw-help.txt and id Line 1359  The directory where idlw-help.txt and id
1359  @end defopt  @end defopt
1360    
1361  @defopt idlwave-help-use-dedicated-frame (@code{t})  @defopt idlwave-help-use-dedicated-frame (@code{t})
1362  Non-nil means, use a separate frame for Online Help if possible.  Non-@code{nil} means use a separate frame for Online Help if possible.
1363  @end defopt  @end defopt
1364    
1365  @defopt idlwave-help-frame-parameters  @defopt idlwave-help-frame-parameters
# Line 1180  Function to call for help if the normal Line 1375  Function to call for help if the normal
1375  @end defopt  @end defopt
1376    
1377  @defopt idlwave-help-fontify-source-code (@code{nil})  @defopt idlwave-help-fontify-source-code (@code{nil})
1378  Non-nil means, fontify source code displayed as help.  Non-@code{nil} means fontify source code displayed as help.
1379  @end defopt  @end defopt
1380    
1381  @defopt idlwave-help-source-try-header (@code{t})  @defopt idlwave-help-source-try-header (@code{t})
1382  Non-nil means, try to find help in routine header when displaying source  Non-@code{nil} means try to find help in routine header when displaying source
1383  file.  file.
1384  @end defopt  @end defopt
1385    
1386  @defopt idlwave-help-link-face  @defopt idlwave-help-link-face
1387  The face for links to IDLWAVE online help.  The face for links in IDLWAVE online help.
1388  @end defopt  @end defopt
1389    
1390  @defopt idlwave-help-activate-links-agressively (@code{t})  @defopt idlwave-help-activate-links-aggressively (@code{t})
1391  Non-@code{nil} means, make all possible links in help window active.  Non-@code{nil} means make all possible links in help window active.
1392  @end defopt  @end defopt
1393    
1394  @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode  @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode
# Line 1208  Non-@code{nil} means, make all possible Line 1403  Non-@code{nil} means, make all possible
1403    
1404  @kindex M-@key{TAB}  @kindex M-@key{TAB}
1405  @kindex C-c C-i  @kindex C-c C-i
1406  IDLWAVE offers completion for class names, routine names and keywords.  IDLWAVE offers completion for class names, routine names, keywords,
1407  As in many programming modes, completion is bound to @kbd{M-@key{TAB}}.  system variables, class structure tags, regular structure tags and file
1408  Completion uses the same internal information as routine info, so when  names.  As in many programming modes, completion is bound to
1409  necessary it can be updated with @kbd{C-c C-i}  @kbd{M-@key{TAB}} (or @kbd{@key{TAB}} in the IDLWAVE Shell ---
1410  (@code{idlwave-update-routine-info}).  @pxref{Using the Shell}).  Completion uses exactly the same internal
1411    information as routine info, so when necessary (rarely) it can be
1412    updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}).
1413    
1414  The completion function is context sensitive and figures out what to  The completion function is context sensitive and figures out what to
1415  complete at point.  Here are example lines and what @kbd{M-@key{TAB}}  complete based location of the point.  Here are example lines and what
1416  would try to complete when the cursor is on the position marked with a  @kbd{M-@key{TAB}} would try to complete when the cursor is on the
1417  @samp{*}.  position marked with a @samp{_}:
1418    
1419  @example  @example
1420  plo*                    @r{Procedure}  plo_                    @r{Procedure}
1421  x = a*                  @r{Function}  x = a_                  @r{Function}
1422  plot,xra*               @r{Keyword of @code{plot} procedure}  plot,xra_               @r{Keyword of @code{plot} procedure}
1423  plot,x,y,/x*            @r{Keyword of @code{plot} procedure}  plot,x,y,/x_            @r{Keyword of @code{plot} procedure}
1424  plot,min(*              @r{Keyword of @code{min} function}  plot,min(_              @r{Keyword of @code{min} function}
1425  obj -> a*               @r{Object method (procedure)}  obj -> a_               @r{Object method (procedure)}
1426  a(2,3) = obj -> a*      @r{Object method (function)}  a(2,3) = obj -> a_      @r{Object method (function)}
1427  x = obj_new('IDL*       @r{Class name}  x = obj_new('IDL_       @r{Class name}
1428  x = obj_new('MyCl',a*   @r{Keyword to @code{Init} method in class @code{MyCl}}  x = obj_new('MyCl',a_   @r{Keyword to @code{Init} method in class @code{MyCl}}
1429  pro A*                  @r{Class name}  pro A_                  @r{Class name}
1430  pro *                   @r{Fill in @code{Class::} of first method in this file}  pro _                   @r{Fill in @code{Class::} of first method in this file}
1431  !v*                     @r{System variable}  !v_                     @r{System variable}
1432  !version.t*             @r{Structure tag of system variable}  !version.t_             @r{Structure tag of system variable}
1433  self.g*                 @r{Class structure tag in methods}  self.g_                 @r{Class structure tag in methods}
1434    state.w_                @r{Structure tag, if tag completion enabled}
1435    name = 'a_              @r{File name (default inside quotes)}
1436  @end example  @end example
1437    
1438    @cindex Completion, ambiguity
1439    @cindex Completion, forcing function name
1440    The only place where completion is ambiguous is procedure/function
1441    @emph{keywords} versus @emph{functions}.  After @samp{plot,x,_}, IDLWAVE
1442    will always assume a keyword to @samp{plot}.  However, a function is
1443    also a possible completion here.  You can force completion of a function
1444    name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}.
1445    
1446  @cindex Scrolling the @file{*Completions*} window  @cindex Scrolling the @file{*Completions*} window
1447  @cindex Completion, scrolling  @cindex Completion, scrolling
1448  @cindex Completion, Online Help  @cindex Completion, Online Help
# Line 1245  If the list of completions is too long t Line 1452  If the list of completions is too long t
1452  @kbd{M-@key{TAB}} repeatedly.  Online help (if installed) for each  @kbd{M-@key{TAB}} repeatedly.  Online help (if installed) for each
1453  possible completion is available by clicking with @kbd{Mouse-3} on the  possible completion is available by clicking with @kbd{Mouse-3} on the
1454  item.  Items for which system online help (from the IDL manual) is  item.  Items for which system online help (from the IDL manual) is
1455  available will be displayed in a different font.  For other items, the  available will be emphasized (e.g. colored blue).  For other items, the
1456  corresponding source code or DocLib header is available as help text.  corresponding source code or DocLib header will be used as the help
1457    text.
1458    
1459    @cindex Completion, cancelling
1460    @cindex Cancelling completion
1461    Completion is not a blocking operation --- you are free to continue
1462    editing, enter commands, or simply ignore the @file{*Completions*}
1463    buffer during a completion operation.  If, however, the most recent
1464    command was a completion, @kbd{C-g} will remove the buffer and restore
1465    the window configuration.  You can also remove the buffer at any time
1466    with no negative consequences.
1467    
1468    @defopt idlwave-keyword-completion-adds-equal (@code{t})
1469    Non-@code{nil} means completion automatically adds @samp{=} after
1470    completed keywords.
1471    @end defopt
1472    
1473    @defopt idlwave-function-completion-adds-paren (@code{t})
1474    Non-@code{nil} means completion automatically adds @samp{(} after
1475    completed function.  A value of `2' means also add the closing
1476    parenthesis and position the cursor between the two.
1477    @end defopt
1478    
1479    @defopt idlwave-completion-restore-window-configuration (@code{t})
1480    Non-@code{nil} means restore window configuration after successful
1481    completion.
1482    @end defopt
1483    
1484    @defopt idlwave-highlight-help-links-in-completion (@code{t})
1485    Non-@code{nil} means highlight completions for which system help is
1486    available.
1487    @end defopt
1488    
1489    @menu
1490    * Case of Completed Words::     CaseOFcomPletedWords
1491    * Object Method Completion and Class Ambiguity::  obj->Method, what?
1492    * Object Method Completion in the Shell::
1493    * Class and Keyword Inheritance::  obj->Method, _EXTRA=e
1494    * Structure Tag Completion::    Completing state.Tag
1495    @end menu
1496    
1497    @node  Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion
1498    @subsection Case of Completed Words
1499  @cindex Case of completed words  @cindex Case of completed words
1500  @cindex Mixed case completion  @cindex Mixed case completion
1501  The case of the completed words is determined by what is already in the  The case of the completed words is determined by what is already in the
# Line 1257  upper case, the string will be completed Line 1505  upper case, the string will be completed
1505  The default is to use upper case for procedures, functions and keywords,  The default is to use upper case for procedures, functions and keywords,
1506  and mixed case for object class names and methods, similar to the  and mixed case for object class names and methods, similar to the
1507  conventions in the IDL manuals.  These defaults can be changed with the  conventions in the IDL manuals.  These defaults can be changed with the
1508  variable @code{idlwave-completion-case}.  variable @code{idlwave-completion-case}.  For instance, to enable
1509    mixed-case completion for routines in addition to classes and methods,
1510    you need an entry such as @code{routine . preserve} in that variable.
1511    To enable total control over the case of completed items, independent of
1512    buffer context, set @code{idlwave-completion-force-default-case} to
1513    non-@code{nil}.
1514    
1515  @defopt idlwave-completion-case  @defopt idlwave-completion-case
1516  Association list setting the case (UPPER/lower/Capitalized/...) of completed  Association list setting the case (UPPER/lower/Capitalized/MixedCase...)
1517  words.  of completed words.
1518  @end defopt  @end defopt
1519    
1520  @defopt idlwave-completion-force-default-case (@code{nil})  @defopt idlwave-completion-force-default-case (@code{nil})
1521  Non-@code{nil} means, completion will always honor the settings in  Non-@code{nil} means completion will always honor the settings in
1522  @code{idlwave-completion-case}.  When nil (the default), lower case  @code{idlwave-completion-case}.  When nil (the default), entirely lower
1523  strings will be completed to lower case.  case strings will always be completed to lower case, no matter what the
1524    settings in @code{idlwave-completion-case}.
1525  @end defopt  @end defopt
1526    
1527  @defopt idlwave-complete-empty-string-as-lower-case (@code{nil})  @defopt idlwave-complete-empty-string-as-lower-case (@code{nil})
1528  Non-@code{nil} means, the empty string is considered lower case for  Non-@code{nil} means the empty string is considered lower case for
 completion.  
 @end defopt  
   
 @defopt idlwave-keyword-completion-adds-equal (@code{t})  
 Non-@code{nil} means, completion automatically adds @samp{=} after  
 completed keywords.  
 @end defopt  
   
 @defopt idlwave-function-completion-adds-paren (@code{t})  
 Non-@code{nil} means, completion automatically adds @samp{(} after  
 completed function.  A value of `2' means, also add the closing  
 parenthesis and position cursor between the two.  
 @end defopt  
   
 @defopt idlwave-completion-restore-window-configuration (@code{t})  
 Non-@code{nil} means, restore window configuration after successful  
1529  completion.  completion.
1530  @end defopt  @end defopt
1531    
1532  @defopt idlwave-highlight-help-links-in-completion (@code{t})  @node  Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion
1533  Non-nil means, highlight completions for which system help is available.  @subsection Object Method Completion and Class Ambiguity
 @end defopt  
   
 @subsubheading Object Method Completion and Class Ambiguity  
1534  @cindex Object methods  @cindex Object methods
1535  @cindex Class ambiguity  @cindex Class ambiguity
1536  @cindex @code{self} object, default class  @cindex @code{self} object, default class
1537  An object method is not uniquely determined without the object's class.  An object method is not uniquely determined without the object's class.
1538  Since the class part is usually omitted in the source code, IDLWAVE  Since the class is almost always omitted in the calling source, IDLWAVE
1539  considers all available methods in all classes as possible completions  considers all available methods in all classes as possible method name
1540  of an object method name.  For keywords, the combined keywords of the  completions.  The combined list of keywords of the current method in
1541  current method in all available classes will be considered.  In the  @emph{all} known classes which contain that method will be considered
1542  @file{*Completions*} buffer, the classes allowed for each completion  for keyword completion.  In the @file{*Completions*} buffer, the
1543  will be shown next to the item (see option  matching classes will be shown next to each item (see option
1544  @code{idlwave-completion-show-classes}).  As a special case, the class  @code{idlwave-completion-show-classes}).  As a special case, the class
1545  of an object called @samp{self} object is always the class of the  of an object called @samp{self} is always taken to be the class of the
1546  current routine.  All classes it inherits from are considered as well  current routine.  All classes it inherits from are considered as well
1547  where appropriate.  where appropriate.
1548    
# Line 1316  where appropriate. Line 1551  where appropriate.
1551  You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u  You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u
1552  M-@key{TAB}}.  IDLWAVE will then prompt you for the class in order to  M-@key{TAB}}.  IDLWAVE will then prompt you for the class in order to
1553  narrow down the number of possible completions.  The variable  narrow down the number of possible completions.  The variable
1554  @code{idlwave-query-class} can be configured to make this behavior the  @code{idlwave-query-class} can be configured to make such prompting the
1555  default (not recommended).  After you have specified the class  default for all methods (not recommended), or selectively for very
1556  for a particular statement (e.g. when completing the method), IDLWAVE  common methods for which the number of completing keywords would be too
1557  can remember it for the rest of the editing session.  Subsequent  large (e.g. @code{Init}).
1558  completions in the same statement (e.g. keywords) can then reuse this  
1559  class information.  Remembering the class works by placing a text  @cindex Saving object class on @code{->}
1560  property in the object operator @samp{->}.  This is not enabled by  @cindex @code{->}
1561  default - the variable @code{idlwave-store-inquired-class} can be used  After you have specified the class for a particular statement (e.g. when
1562  to turn it on.  completing the method), IDLWAVE can remember it for the rest of the
1563    editing session.  Subsequent completions in the same statement
1564  @defopt idlwave-support-inheritance (@code{t})  (e.g. keywords) can then reuse this class information.  This works by
1565  Non-@code{nil} means, treat inheritance with completion, online help etc.  placing a text property on the method invocation operator @samp{->},
1566  @end defopt  after which the operator will be shown in a different face.  This is not
1567    enabled by default --- the variable @code{idlwave-store-inquired-class}
1568    can be used to turn it on.
1569    
1570  @defopt idlwave-completion-show-classes (@code{1})  @defopt idlwave-completion-show-classes (@code{1})
1571  Non-@code{nil} means, show classes in @file{*Completions*} buffer when  Non-@code{nil} means show classes in @file{*Completions*} buffer when
1572  completing object methods and keywords.  completing object methods and keywords.
1573  @end defopt  @end defopt
1574    
1575  @defopt idlwave-completion-fontify-classes (@code{t})  @defopt idlwave-completion-fontify-classes (@code{t})
1576  Non-@code{nil} means, fontify the classes in completions buffer.  Non-@code{nil} means fontify the classes in completions buffer.
1577  @end defopt  @end defopt
1578    
1579  @defopt idlwave-query-class (@code{nil})  @defopt idlwave-query-class (@code{nil})
# Line 1344  Association list governing query for obj Line 1581  Association list governing query for obj
1581  @end defopt  @end defopt
1582    
1583  @defopt idlwave-store-inquired-class (@code{nil})  @defopt idlwave-store-inquired-class (@code{nil})
1584  Non-@code{nil} means, store class of a method call as text property on  Non-@code{nil} means store class of a method call as text property on
1585  @samp{->}.  @samp{->}.
1586  @end defopt  @end defopt
1587    
# Line 1353  Face to highlight object operator arrows Line 1590  Face to highlight object operator arrows
1590  text property.  text property.
1591  @end defopt  @end defopt
1592    
1593  @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode  @node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion
1594    @subsection Object Method Completion in the Shell
1595    @cindex Method Completion in Shell
1596    In the IDLWAVE Shell (@pxref{The IDLWAVE Shell}), objects on which
1597    methods are being invoked have a special property: they must exist as
1598    variables, and so their class can be determined (for instance, using the
1599    @code{obj_class()} function).  In the Shell, when attempting completion,
1600    routine info, or online help within a method routine, a query is sent to
1601    determine the class of the object.  If this query is successful, the
1602    class found will be used to select appropriate completions, routine
1603    info, or help.  If unsuccessful, information from all known classes will
1604    be used (as in the buffer).  Setting the variable
1605    @code{idlwave-store-inquired-class} can eliminate unnecessary repetitive
1606    queries for the object's class, and speed up completion.
1607    
1608    @node   Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion
1609    @subsection Class and Keyword Inheritance
1610    @cindex Inheritance, class
1611    @cindex Keyword inheritance
1612    @cindex Inheritance, keyword
1613    
1614    Class inheritance affects which methods are called in IDL.  An object of
1615    a class which inherits methods from one or more superclasses can
1616    override that method by defining its own method of the same name, extend
1617    the method by calling the method(s) of its superclass(es) in its
1618    version, or inherit the method directly by making no modifications.
1619    IDLWAVE examines class definitions during completion and routine
1620    information display, and records all inheritance information it finds.
1621    This information is displayed if appropriate with the calling sequence
1622    for methods (@pxref{Routine Info}), as long as variable
1623    @code{idlwave-support-inheritance} is non-@code{nil}.
1624    
1625    In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and
1626    @code{_REF_EXTRA}) is used hand-in-hand with class inheritance and
1627    method overriding.  E.g., in a @code{SetProperty} method, this technique
1628    allows a single call @code{obj->SetProperty} to set properties up the
1629    entire class inheritance chain.  This is often referred to as
1630    @emph{chaining}, and is characterized by chained method calls like
1631    @w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}.
1632    
1633    IDLWAVE can accommodate this special synergy between class and keyword
1634    inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a
1635    method's keyword parameters, all keywords of superclass versions of the
1636    method being considered are included in completion.  There is of course
1637    no guarantee that this type of keyword chaining actually occurrs, but
1638    for some methods it's a very convenient assumption.  The variable
1639    @code{idlwave-keyword-class-inheritance} can be used to configure which
1640    methods have keyword inheritance treated in this simple, class-driven
1641    way.  By default, only @code{Init} and @code{(Get|Set)Property} are.
1642    The completion buffer will label keywords based on their originating
1643    class.
1644    
1645    @defopt idlwave-support-inheritance (@code{t})
1646    Non-@code{nil} means consider inheritance during completion, online help etc.
1647    @end defopt
1648    
1649    @defopt idlwave-keyword-class-inheritance
1650    A list of regular expressions to match methods for which simple
1651    class-driven keyword inheritance will be used for Completion.
1652    @end defopt
1653    
1654    @node    Structure Tag Completion,  , Class and Keyword Inheritance, Completion
1655    @subsection Structure Tag Completion
1656    @cindex Completion, structure tag
1657    @cindex Structure tag completion
1658    
1659    In many programs, especially those involving widgets, large structures
1660    (e.g. the @samp{state} structure) are used to communicate among
1661    routines.  It is very convenient to be able to complete structure tags,
1662    in the same way as for instance variables (tags) of the @samp{self}
1663    object (@pxref{Object Method Completion and Class Ambiguity}).  Add-in
1664    code for structure tag completion is available in the form of a loadable
1665    completion module: @file{idlw-complete-structtag.el}.  Tag completion in
1666    structures is highly ambiguous (much more so than @samp{self}
1667    completion), so @code{idlw-complete-structtag} makes an unusual and very
1668    specific assumption: the exact same variable name is used to refer to
1669    the structure in all parts of the program.  This is entirely unenforced
1670    by the IDL language, but is a typical convention.  If you consistently
1671    refer to the same structure with the same variable name
1672    (e.g. @samp{state}), structure tags which are read from its definition
1673    in the same file can be used for completion.
1674    
1675    Structure tag completion is not enabled by default.  To enable it,
1676    simply add the following to your @file{.emacs}:
1677    
1678    @lisp
1679       (add-hook 'idlwave-load-hook
1680                 (lambda () (require 'idlw-complete-structtag)))
1681    @end lisp
1682    
1683    Once enabled, you'll also be able to access online help on the structure
1684    tags, using the usual methods (@pxref{Online Help}).
1685    
1686    @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode
1687  @section Routine Source  @section Routine Source
1688  @cindex Routine source file  @cindex Routine source file
1689  @cindex Module source file  @cindex Module source file
1690  @cindex Source file, of a routine  @cindex Source file, of a routine
1691  @kindex C-c C-v  @kindex C-c C-v
1692  Apart from clicking on a @i{Source:} line in the routine info window,  In addition to clicking on a @i{Source:} line in the routine info
1693  there is also another way to find the source file of a routine.  The  window, there is another way to quickly visit the source file of a
1694  command @kbd{C-c C-v} (@code{idlwave-find-module}) asks for a module  routine.  The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks
1695  name, offering the same default as @code{idlwave-routine-info} would  for a module name, offering the same default as
1696  have used.  In the minibuffer, specify a complete routine name  @code{idlwave-routine-info} would have used, taken from nearby buffer
1697  (including the class part).  IDLWAVE will display the source file in  contents.  In the minibuffer, specify a complete routine name (including
1698  another window.  any class part).  IDLWAVE will display the source file in another
1699    window, positioned at the routine in question.
1700    
1701  @cindex Buffers, killing  @cindex Buffers, killing
1702  @cindex Killing autoloaded buffers  @cindex Killing autoloaded buffers
1703  Since getting the source of a routine into a buffer is so easy with  Since getting the source of a routine into a buffer is so easy with
1704  IDLWAVE, too many buffers visiting different IDL source files are  IDLWAVE, too many buffers visiting different IDL source files are
1705  sometimes created.  The special command @kbd{C-c C-k}  sometimes created.  The special command @kbd{C-c C-k}
1706  (@code{idlwave-kill-autoloaded-buffers}) can be used to remove these  (@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove
1707  buffers.  these buffers.
1708    
1709  @node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode  @node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode
1710  @section Resolving Routines  @section Resolving Routines
# Line 1393  scan (parts of) the library (@pxref{Libr Line 1723  scan (parts of) the library (@pxref{Libr
1723  library modules will then be available without the need to compile the  library modules will then be available without the need to compile the
1724  modules first, and even without a running shell.  modules first, and even without a running shell.
1725    
1726  @xref{Sources of Routine Info}, for in-depth information where IDLWAVE  @xref{Sources of Routine Info}, for more information on the ways IDLWAVE
1727  collects data about routines, and how to update this information.  collects data about routines, and how to update this information.
1728    
1729    @node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode
 @node Code Templates, Actions, Resolving Routines, The IDLWAVE Major Mode  
1730  @section Code Templates  @section Code Templates
1731  @cindex Code templates  @cindex Code templates
 @cindex Abbreviations  
1732  @cindex Templates  @cindex Templates
1733    
1734  IDLWAVE can insert IDL code templates into the buffer.  For a few  IDLWAVE can insert IDL code templates into the buffer.  For a few
# Line 1417  templates, this is done with direct key Line 1745  templates, this is done with direct key
1745  @tab @code{WHILE} loop template  @tab @code{WHILE} loop template
1746  @end multitable  @end multitable
1747    
1748  Otherwise, special abbreviations are used.  Emacs abbreviations are  All code templates are also available as abbreviations
1749  expanded by typing text into the buffer and pressing @key{SPC} or  (@pxref{Abbreviations}).
1750  @key{RET}.  The special abbreviations used to insert code templates all  
1751  start with a @samp{\} (the backslash).  Here are a few examples of  @node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode
1752  predefined abbreviations.   For a full list, use @kbd{M-x  @section Abbreviations
1753    @cindex Abbreviations
1754    
1755    Special abbreviations exist to enable rapid entry of commonly used
1756    commands.  Emacs abbreviations are expanded by typing text into the
1757    buffer and pressing @key{SPC} or @key{RET}.  The special abbreviations
1758    used to insert code templates all start with a @samp{\} (the backslash),
1759    or, optionally, any other character set in
1760    @code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are
1761    only expanded where they should be (i.e., not in a string or comment),
1762    and permits the point to be moved after an abbreviation expansion ---
1763    very useful for positioning the mark inside of parentheses, etc.
1764    
1765    Special abbreviations are pre-defined for code templates and other
1766    useful items.  To visit the full list of abbreviations, use @kbd{M-x
1767  idlwave-list-abbrevs}.  idlwave-list-abbrevs}.
1768    
1769    Template abbreviations:
1770    
1771  @multitable @columnfractions .15 .85  @multitable @columnfractions .15 .85
1772  @item @code{\pr}  @item @code{\pr}
1773  @tab @code{PROCEDURE} template  @tab @code{PROCEDURE} template
# Line 1441  idlwave-list-abbrevs}. Line 1785  idlwave-list-abbrevs}.
1785  @tab @code{IF} statement template  @tab @code{IF} statement template
1786  @item @code{\elif}  @item @code{\elif}
1787  @tab @code{IF-ELSE} statement template  @tab @code{IF-ELSE} statement template
1788    @end multitable
1789    
1790    String abbreviations:
1791    
1792    @multitable @columnfractions .15 .85
1793    @item @code{\ap}
1794    @tab @code{arg_present()}
1795  @item @code{\b}  @item @code{\b}
1796  @tab @code{BEGIN}  @tab @code{begin}
1797    @item @code{\cb}
1798    @tab @code{byte()}
1799    @item @code{\cc}
1800    @tab @code{complex()}
1801    @item @code{\cd}
1802    @tab @code{double()}
1803    @item @code{\cf}
1804    @tab @code{float()}
1805    @item @code{\cl}
1806    @tab @code{long()}
1807    @item @code{\co}
1808    @tab @code{common}
1809    @item @code{\cs}
1810    @tab @code{string()}
1811    @item @code{\cx}
1812    @tab @code{fix()}
1813    @item @code{\e}
1814    @tab @code{else}
1815    @item @code{\ec}
1816    @tab @code{endcase}
1817    @item @code{\ee}
1818    @tab @code{endelse}
1819    @item @code{\ef}
1820    @tab @code{endfor}
1821    @item @code{\ei}
1822    @tab @code{endif else if}
1823    @item @code{\el}
1824    @tab @code{endif else}
1825    @item @code{\en}
1826    @tab @code{endif}
1827    @item @code{\er}
1828    @tab @code{endrep}
1829    @item @code{\es}
1830    @tab @code{endswitch}
1831    @item @code{\ew}
1832    @tab @code{endwhile}
1833    @item @code{\g}
1834    @tab @code{goto,}
1835    @item @code{\h}
1836    @tab @code{help,}
1837    @item @code{\ik}
1838    @tab @code{if keyword_set() then}
1839    @item @code{\iap}
1840    @tab @code{if arg_present() then}
1841    @item @code{\ine}
1842    @tab @code{if n_elements() eq 0 then}
1843    @item @code{\inn}
1844    @tab @code{if n_elements() ne 0 then}
1845    @item @code{\k}
1846    @tab @code{keyword_set()}
1847    @item @code{\n}
1848    @tab @code{n_elements()}
1849    @item @code{\np}
1850    @tab @code{n_params()}
1851    @item @code{\oi}
1852    @tab @code{on_ioerror,}
1853    @item @code{\or}
1854    @tab @code{openr,}
1855    @item @code{\ou}
1856    @tab @code{openu,}
1857    @item @code{\ow}
1858    @tab @code{openw,}
1859    @item @code{\p}
1860    @tab @code{print,}
1861    @item @code{\pt}
1862    @tab @code{plot,}
1863    @item @code{\re}
1864    @tab @code{read,}
1865    @item @code{\rf}
1866    @tab @code{readf,}
1867    @item @code{\rt}
1868    @tab @code{return}
1869    @item @code{\ru}
1870    @tab @code{readu,}
1871    @item @code{\s}
1872    @tab @code{size()}
1873    @item @code{\sc}
1874    @tab @code{strcompress()}
1875    @item @code{\sl}
1876    @tab @code{strlowcase()}
1877    @item @code{\sm}
1878    @tab @code{strmid()}
1879    @item @code{\sn}
1880    @tab @code{strlen()}
1881    @item @code{\sp}
1882    @tab @code{strpos()}
1883    @item @code{\sr}
1884    @tab @code{strtrim()}
1885    @item @code{\st}
1886    @tab @code{strput()}
1887    @item @code{\su}
1888    @tab @code{strupcase()}
1889    @item @code{\t}
1890    @tab @code{then}
1891    @item @code{\u}
1892    @tab @code{until}
1893    @item @code{\wc}
1894    @tab @code{widget_control,}
1895    @item @code{\wi}
1896    @tab @code{widget_info()}
1897    @item @code{\wu}
1898    @tab @code{writeu,}
1899  @end multitable  @end multitable
1900    
1901  The templates are expanded in upper or lower case, depending upon the  @noindent You can easily add your own abbreviations or override existing
1902  variables @code{idlwave-abbrev-change-case} and  abbrevs with @code{define-abbrev} in your mode hook, using the
1903  @code{idlwave-reserved-word-upcase}.  convenience function @code{idlwave-define-abbrev}:
1904    
1905    @lisp
1906    (add-hook 'idlwave-mode-hook
1907              (lambda ()
1908                (idlwave-define-abbrev "wb" "widget_base()"
1909                         (idlwave-keyword-abbrev 1))
1910                (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN"
1911                         (idlwave-keyword-abbrev 11))))
1912    @end lisp
1913    
1914    Notice how the abbreviation (here @emph{wb}) and its expansion
1915    (@emph{widget_base()}) are given as arguments, and the single argument to
1916    @code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to
1917    move the point upon expansion (in this example, to put it between the
1918    parentheses).
1919    
1920    The abbreviations are expanded in upper or lower case, depending upon
1921    the variables @code{idlwave-abbrev-change-case} and, for reserved word
1922    templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}).
1923    
1924  @defopt idlwave-abbrev-start-char (@code{"\"})  @defopt idlwave-abbrev-start-char (@code{"\"})
1925  A single character string used to start abbreviations in abbrev  A single character string used to start abbreviations in abbrev mode.
1926  mode.  Beware of common characters which might naturally occur in sequence with
1927    abbreviation strings.
1928  @end defopt  @end defopt
1929    
1930  @defopt idlwave-abbrev-move (@code{t})  @defopt idlwave-abbrev-move (@code{t})
1931  Non-@code{nil} means the abbrev hook can move point, e.g. to end up  Non-@code{nil} means the abbrev hook can move point, e.g. to end up
1932  between the parenthesis of a function call.  between the parentheses of a function call.
1933  @end defopt  @end defopt
1934    
1935  @node Actions, Doc Header, Code Templates, The IDLWAVE Major Mode  @node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode
1936  @section Actions  @section Actions
1937  @cindex Actions  @cindex Actions
1938  @cindex Coding standards, enforcing  @cindex Coding standards, enforcing
1939    
1940  @emph{Actions} are special commands which are executed automatically  @emph{Actions} are special formatting commands which are executed
1941  while you write code in order to check the structure of the program or  automatically while you write code in order to check the structure of
1942  to enforce coding standards.  Most actions which have been implemented  the program or to enforce coding standards.  Most actions which have
1943  in IDLWAVE are turned off by default, assuming that the average user  been implemented in IDLWAVE are turned off by default, assuming that the
1944  wants her code the way she writes it.  But if you are a lazy typist and  average user wants her code the way she writes it.  But if you are a
1945  want your code to adhere to certain standards, they can be  lazy typist and want your code to adhere to certain standards, actions
1946  helpful.  can be helpful.
1947    
1948  Action can be applied in three ways:  Actions can be applied in three ways:
1949    
1950  @itemize @bullet  @itemize @bullet
1951  @item  @item
# Line 1488  must be non-@code{nil}. Line 1961  must be non-@code{nil}.
1961  @item  @item
1962  @cindex Foreign code, adapting  @cindex Foreign code, adapting
1963  @cindex Actions, applied to foreign code  @cindex Actions, applied to foreign code
1964  Action can also be applied to a larger piece of code, e.g. in order to  Actions can also be applied to a larger piece of code, e.g. to convert
1965  convert foreign code to your own style.  To do this, mark the relevant  foreign code to your own style.  To do this, mark the relevant part of
1966  part of the code and execute @kbd{M-x expand-region-abbrevs}.  Useful  the code and execute @kbd{M-x expand-region-abbrevs}.  Useful marking
1967  marking commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the  commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current
1968  current subprogram). @xref{Code Indentation}, for information how to  subprogram). @xref{Code Indentation}, for information how to adjust the
1969  adjust the indentation of the code.  indentation of the code.
1970  @end itemize  @end itemize
1971    
1972  @defopt idlwave-do-actions (@code{nil})  @defopt idlwave-do-actions (@code{nil})
# Line 1501  Non-@code{nil} means performs actions wh Line 1974  Non-@code{nil} means performs actions wh
1974  @end defopt  @end defopt
1975    
1976  @menu  @menu
1977  * Block Boundary Check::        Is the END correct  * Block Boundary Check::        Is the END statement correct?
1978  * Padding Operators::           Enforcing space around `=' etc  * Padding Operators::           Enforcing space around `=' etc
1979  * Case Changes::                Enforcing upper case keywords  * Case Changes::                Enforcing upper case keywords
1980  @end menu  @end menu
# Line 1518  Non-@code{nil} means performs actions wh Line 1991  Non-@code{nil} means performs actions wh
1991  Whenever you type an @code{END} statement, IDLWAVE finds the  Whenever you type an @code{END} statement, IDLWAVE finds the
1992  corresponding start of the block and the cursor blinks back to that  corresponding start of the block and the cursor blinks back to that
1993  location for a second.  If you have typed a specific @code{END}, like  location for a second.  If you have typed a specific @code{END}, like
1994  @code{ENDIF} or @code{ENDCASE}, you get a warning if that kind of END  @code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator
1995  does not match the type of block it terminates.  does not match the type of block it terminates.
1996    
1997  Set the variable @code{idlwave-expand-generic-end} in order to have all  Set the variable @code{idlwave-expand-generic-end} in order to have all
1998  generic @code{END} statements automatically expanded to a specific type.  generic @code{END} statements automatically expanded to the appropriate
1999  You can also type @kbd{C-c ]} to close the current block by inserting  type.  You can also type @kbd{C-c ]} to close the current block by
2000  the appropriate @code{END} statement.  inserting the appropriate @code{END} statement.
2001    
2002  @defopt idlwave-show-block (@code{t})  @defopt idlwave-show-block (@code{t})
2003  Non-@code{nil} means point blinks to block beginning for  Non-@code{nil} means point blinks to block beginning for
# Line 1536  Non-@code{nil} means expand generic END Line 2009  Non-@code{nil} means expand generic END
2009  @end defopt  @end defopt
2010    
2011  @defopt idlwave-reindent-end (@code{t})  @defopt idlwave-reindent-end (@code{t})
2012  Non-nil means re-indent line after END was typed.  Non-@code{nil} means re-indent line after END was typed.
2013  @end defopt  @end defopt
2014    
2015  @node Padding Operators, Case Changes, Block Boundary Check, Actions  @node Padding Operators, Case Changes, Block Boundary Check, Actions
# Line 1546  Non-nil means re-indent line after END w Line 2019  Non-nil means re-indent line after END w
2019  @cindex Space, around operators  @cindex Space, around operators
2020    
2021  Some operators can be automatically surrounded by spaces.  This can  Some operators can be automatically surrounded by spaces.  This can
2022  happen when the operator is typed, or also later when the line is  happen when the operator is typed, or later when the line is indented.
2023  indented.  IDLWAVE contains this setting for the operators @samp{&},  IDLWAVE can pad the operators @samp{&}, @samp{<}, @samp{>}, @samp{,},
2024  @samp{<}, @samp{>}, @samp{,}, @samp{=}, and @samp{->}@footnote{Operators  @samp{=}, and @samp{->}, but this feature is turned off by default.  If
2025  longer than one character can only be padded during line indentation.},  you want to turn it on, customize the variables
2026  but the feature is turned off by default.  If you want to turn it on,  @code{idlwave-surround-by-blank} and @code{idlwave-do-actions}.  You can
2027  customize the variables @code{idlwave-surround-by-blank} and  also define similar actions for other operators by using the function
2028  @code{idlwave-do-actions}.  You can also define similar actions for  @code{idlwave-action-and-binding} in the mode hook.  For example, to
2029  other operators by using the function @code{idlwave-action-and-binding}  enforce space padding of the @samp{+} and @samp{*} operators, try this
2030  in the mode hook.  For example, to enforce space padding of the @samp{+}  in @file{.emacs}
 and @samp{*} operators, try this in @file{.emacs}  
2031    
2032  @lisp  @lisp
2033  (add-hook 'idlwave-mode-hook  (add-hook 'idlwave-mode-hook
# Line 1566  and @samp{*} operators, try this in @fil Line 2038  and @samp{*} operators, try this in @fil
2038  @end lisp  @end lisp
2039    
2040  @defopt idlwave-surround-by-blank (@code{nil})  @defopt idlwave-surround-by-blank (@code{nil})
2041  Non-@code{nil} means, enable @code{idlwave-surround}.  If non-nil,  Non-@code{nil} means enable @code{idlwave-surround}.  If non-@code{nil},
2042  @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are  @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are
2043  surrounded with spaces by @code{idlwave-surround}.  surrounded with spaces by @code{idlwave-surround}.
2044  @end defopt  @end defopt
# Line 1597  your @file{.emacs} file: Line 2069  your @file{.emacs} file:
2069       (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<"       (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<"
2070                                   '(capitalize-word 1) t)                                   '(capitalize-word 1) t)
2071       ;;  Capitalize common block name       ;;  Capitalize common block name
2072       (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"       (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"
2073                                   '(capitalize-word 1) t)))                                   '(capitalize-word 1) t)))
2074  @end lisp  @end lisp
2075    
2076  For more information, see the documentation string for the function  For more information, see the documentation string for the function
2077  @code{idlwave-action-and-binding}.  @code{idlwave-action-and-binding}.  For information on controlling the
2078    case of routines, keywords, classes, and methods as they are completed, see
2079    @ref{Completion}.
2080    
2081  @defopt idlwave-abbrev-change-case (@code{nil})  @defopt idlwave-abbrev-change-case (@code{nil})
2082  Non-@code{nil} means all abbrevs will be forced to either upper or lower  Non-@code{nil} means all abbrevs will be forced to either upper or lower
# Line 1610  case.  Legal values are @code{nil}, @cod Line 2084  case.  Legal values are @code{nil}, @cod
2084  @end defopt  @end defopt
2085    
2086  @defopt idlwave-reserved-word-upcase (@code{nil})  @defopt idlwave-reserved-word-upcase (@code{nil})
2087  Non-@code{nil} means, reserved words will be made upper case via abbrev  Non-@code{nil} means reserved words will be made upper case via abbrev
2088  expansion.  expansion.
2089  @end defopt  @end defopt
2090    
# Line 1622  expansion. Line 2096  expansion.
2096  @cindex Modification timestamp  @cindex Modification timestamp
2097  @cindex Header, for file documentation  @cindex Header, for file documentation
2098  @cindex Timestamp, in doc header.  @cindex Timestamp, in doc header.
2099  @cindex Changelog, in doc header.  @cindex ChangeLog, in doc header.
2100    
2101  @kindex C-c C-h  @kindex C-c C-h
2102  @kindex C-c C-m  @kindex C-c C-m
2103  The command @kbd{C-c C-h} inserts a standard routine header into the  The command @kbd{C-c C-h} inserts a standard routine header into the
2104  buffer, with the usual fields for documentation.  One of the keywords is  buffer, with the usual fields for documentation (a different header can
2105    be specified with @code{idlwave-file-header}).  One of the keywords is
2106  @samp{MODIFICATION HISTORY} under which the changes to a routine can be  @samp{MODIFICATION HISTORY} under which the changes to a routine can be
2107  recorded.  The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION  recorded.  The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION
2108  HISTORY} of the current routine or file and inserts the user  HISTORY} of the current routine or file and inserts the user name with a
2109  name with a timestamp.  timestamp.
2110    
2111  @defopt idlwave-file-header  @defopt idlwave-file-header
2112  The doc-header template or a path to a file containing it.  The doc-header template or a path to a file containing it.
2113  @end defopt  @end defopt
2114    
2115    @defopt idlwave-header-to-beginning-of-file (@code{nil})
2116    Non-@code{nil} means the documentation header will always be at start
2117    of file.
2118    @end defopt
2119    
2120  @defopt idlwave-timestamp-hook  @defopt idlwave-timestamp-hook
2121  The hook function used to update the timestamp of a function.  The hook function used to update the timestamp of a function.
2122  @end defopt  @end defopt
# Line 1665  Regexp matching the start of a document Line 2145  Regexp matching the start of a document
2145    
2146  IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages  IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages
2147  which make it easy to jump to the definitions of functions and  which make it easy to jump to the definitions of functions and
2148  procedures in the current file.  procedures in the current file with a pop-up selection.  To bind
2149    @file{Imenu} to a mouse-press, use in your @file{.emacs}:
2150    
2151    @lisp
2152    (define-key global-map [S-down-mouse-3] 'imenu)
2153    @end lisp
2154    
2155    @cindex @file{Speedbar}, Emacs package
2156    
2157  Several commands allow to move quickly through the structure of an IDL  In addition, @file{Speedbar} support allows convenient navigation of a
2158  program.  These are  source tree of IDL routine files, quickly stepping to routine
2159    definitions.  See @code{Tools->Display Speedbar}.
2160    
2161    Several commands allow you to move quickly through the structure of an
2162    IDL program:
2163    
2164  @multitable @columnfractions .15 .85  @multitable @columnfractions .15 .85
2165  @item @kbd{C-M-a}  @item @kbd{C-M-a}
# Line 1715  Normal hook.  Executed when @file{idlwav Line 2206  Normal hook.  Executed when @file{idlwav
2206    
2207    
2208    
   
   
   
   
   
   
   
   
   
   
   
   
   
2209  @node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top  @node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top
2210  @chapter The IDLWAVE Shell  @chapter The IDLWAVE Shell
2211  @cindex IDLWAVE shell  @cindex IDLWAVE shell
# Line 1738  Normal hook.  Executed when @file{idlwav Line 2216  Normal hook.  Executed when @file{idlwav
2216  @cindex Windows  @cindex Windows
2217  @cindex MacOS  @cindex MacOS
2218    
2219  The IDLWAVE shell is an Emacs major mode which allows to run the IDL  The IDLWAVE shell is an Emacs major mode which permits running the IDL
2220  program as an inferior process of Emacs.  It can be used to work with  program as an inferior process of Emacs, and works closely with the
2221  IDL interactively, to compile and run IDL programs in Emacs buffers and  IDLWAVE major mode in buffers.  It can be used to work with IDL
2222  to debug these programs.  The IDLWAVE shell uses @file{comint}, an Emacs  interactively, to compile and run IDL programs in Emacs buffers and to
2223  packages which handles the communication with the IDL program.  debug these programs.  The IDLWAVE shell is built upon @file{comint}, an
2224  Unfortunately IDL for Windows and MacOS does not allow the interaction  Emacs packages which handles the communication with the IDL program.
2225  with Emacs@footnote{Please inform the maintainer if you come up with a way  Unfortunately IDL for Windows and MacOS do not have command-prompt
2226  to make the IDLWAVE shell work on these systems.}, so the IDLWAVE shell  versions and thus do not allow the interaction with
2227  only works under GNU and Unix.  Emacs@footnote{Please inform the maintainer if you come up with a way to
2228    make the IDLWAVE shell work on these systems.} --- so the IDLWAVE shell
2229    currently only works under Unix.
2230    
2231  @menu  @menu
2232  * Starting the Shell::          How to launch IDL as a subprocess  * Starting the Shell::          How to launch IDL as a subprocess
2233  * Using the Shell::             Interactively working with the Shell  * Using the Shell::             Interactively working with the Shell
2234  * Debugging IDL Programs::      Compilation/Debugging  * Commands Sent to the Shell::
2235    * Debugging IDL Programs::
2236    * Examining Variables::
2237    * Custom Expression Examination::
2238  @end menu  @end menu
2239    
2240  @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 1768  idlwave-shell}.  In @code{idlwave-mode} Line 2251  idlwave-shell}.  In @code{idlwave-mode}
2251  @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
2252  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 C-s}
2253  will simple switch to the shell buffer.  The command @kbd{C-c C-l}  will simple switch to the shell buffer.  The command @kbd{C-c C-l}
2254  (@code{idlwave-shell-recenter-shell-window}) displays the  (@code{idlwave-shell-recenter-shell-window}) displays the shell window
2255  shell window without selecting it.  without selecting it.  The shell can also be started automatically when
2256    another command tries to send a command to it.  To enable auto start,
2257    set the variable @code{idlwave-shell-automatic-start} to @code{t}.
2258    
2259  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
2260  @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
2261  @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
2262  window, configure the variable  window, configure the variable
2263  @code{idlwave-shell-use-dedicated-frame}.  @code{idlwave-shell-use-dedicated-frame}.
2264    
2265    To launch a quick IDLWAVE shell directly from a shell prompt without an
2266    IDLWAVE buffer (e.g., as a replacement for running inside an xterm),
2267    define an alias with the following content:
2268    
2269  The shell can also be started automatically when another command tries  @example
2270  to send a command to it.  To enable auto start, set the variable  emacs -geometry 80x32 -eval "(idlwave-shell 'quick)"
2271  @code{idlwave-shell-automatic-start} to @code{t}.  @end example
2272    
2273  @defopt idlwave-shell-explicit-file-name  Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer
2274    the Emacs process to run directly inside the terminal window.
2275    
2276    @defopt idlwave-shell-explicit-file-name (@file{idl})
2277  This is the command to run IDL.  This is the command to run IDL.
2278  @end defopt  @end defopt
2279    
# Line 1797  Regexp to match IDL prompt at beginning Line 2289  Regexp to match IDL prompt at beginning
2289  Name to be associated with the IDL process.  Name to be associated with the IDL process.
2290  @end defopt  @end defopt
2291    
2292  @defopt idlwave-shell-automatic-start  @defopt idlwave-shell-automatic-start  (@code{nil})
2293  Non-@code{nil} means attempt to invoke idlwave-shell if not already  Non-@code{nil} means attempt to invoke idlwave-shell if not already
2294  running.  running.
2295  @end defopt  @end defopt
# Line 1806  running. Line 2298  running.
2298  Initial commands, separated by newlines, to send to IDL.  Initial commands, separated by newlines, to send to IDL.
2299  @end defopt  @end defopt
2300    
2301    @defopt idlwave-shell-save-command-history (@code{t})
2302    Non-@code{nil} means preserve command history between sessions.
2303    @end defopt
2304    
2305    @defopt idlwave-shell-command-history-file (@file{~/.idlwhist})
2306    The file in which the command history of the idlwave shell is saved.
2307    @end defopt
2308    
2309  @defopt idlwave-shell-use-dedicated-frame (@code{nil})  @defopt idlwave-shell-use-dedicated-frame (@code{nil})
2310  Non-@code{nil} means, IDLWAVE should use a special frame to display  Non-@code{nil} means IDLWAVE should use a special frame to display
2311  shell buffer.  shell buffer.
2312  @end defopt  @end defopt
2313    
2314  @defopt idlwave-shell-frame-parameters  @defopt idlwave-shell-frame-parameters
2315  The frame parameters for a dedicated idlwave-shell frame.  The frame parameters for a dedicated idlwave-shell frame.
2316  @end defopt  @end defopt
2317    
2318    @defopt idlwave-shell-raise-frame (@code{t})
2319    Non-@code{nil} means `idlwave-shell' raises the frame showing the shell
2320    window.
2321    @end defopt
2322    
2323  @defopt idlwave-shell-temp-pro-prefix  @defopt idlwave-shell-temp-pro-prefix
2324  The prefix for temporary IDL files used when compiling regions.  The prefix for temporary IDL files used when compiling regions.
2325  @end defopt  @end defopt
# Line 1824  The prefix for temporary IDL files used Line 2329  The prefix for temporary IDL files used
2329  Hook for customizing @code{idlwave-shell-mode}.  Hook for customizing @code{idlwave-shell-mode}.
2330  @end defopt  @end defopt
2331    
2332  @node Using the Shell, Debugging IDL Programs, Starting the Shell, The IDLWAVE Shell  @node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell
2333  @section Using the Shell  @section Using the Shell
2334  @cindex Comint  @cindex Comint
2335  @cindex Shell, basic commands  @cindex Shell, basic commands
# Line 1835  control.  The @key{UP} and @key{DOWN} ar Line 2340  control.  The @key{UP} and @key{DOWN} ar
2340  history just like in an X terminal@footnote{This is different from  history just like in an X terminal@footnote{This is different from
2341  normal Emacs/Comint behavior, but more like an xterm.  If you prefer the  normal Emacs/Comint behavior, but more like an xterm.  If you prefer the
2342  default comint functionality, check the variable  default comint functionality, check the variable
2343  @code{idlwave-shell-arrows-do-history}.}.  Here is a list of  @code{idlwave-shell-arrows-do-history}.}.  The history is preserved
2344  commonly used commands.  between emacs and IDL sessions.  Here is a list of commonly used
2345    commands:
2346    
2347  @multitable @columnfractions .12 .88  @multitable @columnfractions .12 .88
2348  @item @key{UP}  @item @key{UP}, @key{M-p}
2349  @tab Cycle backwards in input history  @tab Cycle backwards in input history
2350  @item @key{DOWN}  @item @key{DOWN}, @key{M-n}
2351  @tab Cycle forwards in input history  @tab Cycle forwards in input history
 @item @kbd{M-p}  
 @tab Cycle backwards in input history @emph{matching input}  
 @item @kbd{M-n}  
 @tab Cycle forwards in input history @emph{matching input}  
2352  @item @kbd{M-r}  @item @kbd{M-r}
2353  @tab Previous input matching a regexp  @tab Previous input matching a regexp
2354  @item @kbd{M-s}  @item @kbd{M-s}
2355  @tab Next input that matches a regexp  @tab Next input matching a regexp
2356  @item @kbd{return}  @item @kbd{return}
2357  @tab Send input or copy line to current prompt  @tab Send input or copy line to current prompt
2358  @item @kbd{C-c C-a}  @item @kbd{C-c C-a}
# Line 1874  commonly used commands. Line 2376  commonly used commands.
2376  @end multitable  @end multitable
2377    
2378  In addition to these standard @file{comint} commands,  In addition to these standard @file{comint} commands,
2379  @code{idlwave-shell-mode} provides many of the commands which simplify  @code{idlwave-shell-mode} provides many of the same commands which
2380  writing IDL code, including abbreviations, online help, and completion.  simplify writing IDL code available in IDLWAVE buffers.  This includes
2381  See @ref{Routine Info} and @ref{Online Help} and @ref{Completion} for more  abbreviations, online help, and completion.  See @ref{Routine Info} and
2382  information on these commands.  @ref{Online Help} and @ref{Completion} for more information on these
2383    commands.
2384    
2385  @cindex Completion, in the shell  @cindex Completion, in the shell
2386  @cindex Routine info, in the shell  @cindex Routine info, in the shell
2387  @cindex Online Help, in the shell  @cindex Online Help, in the shell
2388  @multitable @columnfractions .12 .88  @multitable @columnfractions .12 .88
2389  @item @kbd{@key{TAB}}  @item @kbd{@key{TAB}}
2390  @tab  Completion of file names, routine names and keywords  @tab  Completion of file names (between quotes and after executive
2391  (@code{idlwave-shell-complete})  commands @samp{.run} and @samp{.compile}), routine names, class names,
2392    keywords, system variables, system variable tags etc.
2393    (@code{idlwave-shell-complete}).
2394  @item @kbd{M-@key{TAB}}  @item @kbd{M-@key{TAB}}
2395  @tab Same as @key{TAB}  @tab Same as @key{TAB}
2396  @item @kbd{C-c ?}  @item @kbd{C-c ?}
# Line 1906  Non-@code{nil} means @key{UP} and @key{D Line 2411  Non-@code{nil} means @key{UP} and @key{D
2411  history like xterm.  history like xterm.
2412  @end defopt  @end defopt
2413    
2414    @defopt idlwave-shell-comint-settings
2415    Alist of special settings for the comint variables in the IDLWAVE Shell.
2416    @end defopt
2417    
2418  @defopt idlwave-shell-file-name-chars  @defopt idlwave-shell-file-name-chars
2419  The characters allowed in file names, as a string.  Used for file name  The characters allowed in file names, as a string.  Used for file name
2420  completion.  completion.
# Line 1935  variables described below for a way to m Line 2444  variables described below for a way to m
2444  automatic switches of the input mode.  automatic switches of the input mode.
2445    
2446  @defopt idlwave-shell-use-input-mode-magic (@code{nil})  @defopt idlwave-shell-use-input-mode-magic (@code{nil})
2447  Non-nil means, IDLWAVE should check for input mode spells in output.  Non-@code{nil} means IDLWAVE should check for input mode spells in
2448    output.
2449  @end defopt  @end defopt
2450    
2451  @defopt idlwave-shell-input-mode-spells  @defopt idlwave-shell-input-mode-spells
# Line 1943  The three regular expressions which matc Line 2453  The three regular expressions which matc
2453  modes.  modes.
2454  @end defopt  @end defopt
2455    
2456  @node Debugging IDL Programs,  , Using the Shell, The IDLWAVE Shell  @node Commands Sent to the Shell, Debugging IDL Programs, Using the Shell, The IDLWAVE Shell
2457    @section Commands Sent to the Shell
2458    @cindex Commands in shell, showing
2459    @cindex Showing commands in shell
2460    
2461    The IDLWAVE buffers and shell interact very closely.  In addition to the
2462    normal commands you enter at the @code{IDL>} prompt, many other special
2463    commands are sent to the shell, sometimes as a direct result of invoking
2464    a key command, menu item, or toolbar button, but also automatically, as
2465    part of the normal flow of information updates between the buffer and
2466    shell.
2467    
2468    The commands sent include @code{breakpoint}, @code{.step} and other
2469    debug commands (@pxref{Debugging IDL Programs}), @code{.run} and other
2470    compilation statements (@pxref{Compiling Programs}), examination
2471    commands like @code{print} and @code{help} (@pxref{Examining
2472    Variables}), and other special purpose commands designed to keep
2473    information on the running shell current.
2474    
2475    By default, much of this background shell input and output is hidden
2476    from the user, but this is configurable.  The custom variable
2477    @code{idlwave-abbrev-show-commands} allows you to configure which
2478    commands sent to the shell are shown there.  For a related customization
2479    for separating the output of @emph{examine} commands @xref{Examining
2480    Variables}.
2481    
2482    @defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)})
2483    A list of command types to echo in the shell when sent.  Possible values
2484    are @code{run} for @code{.run}, @code{.compile} and other run commands,
2485    @code{misc} for lesser used commands like @code{window}, @code{retall},
2486    etc., @code{breakpoint} for breakpoint setting and clearing commands,
2487    and @code{debug} for other debug, stepping, and continue commands.  In
2488    addition, if the variable is set to the single symbol @code{'everything},
2489    all the copious shell input is displayed (which is probably only useful
2490    for debugging purposes).
2491    @end defopt
2492    
2493    @node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell
2494  @section Debugging IDL Programs  @section Debugging IDL Programs
2495  @cindex Debugging  @cindex Debugging
2496  @cindex Keybindings for debugging  @cindex Keybindings for debugging
2497  @cindex Toolbar  @cindex Toolbar
2498    
 @kindex C-c C-d  
2499  Programs can be compiled, run, and debugged directly from the source  Programs can be compiled, run, and debugged directly from the source
2500  buffer in Emacs.  The IDLWAVE shell installs key bindings both in the  buffer in Emacs.  IDLWAVE makes compiling and debugging IDL programs
2501  shell buffer and in all IDL code buffers of the current Emacs session.  far less cumbersome by providing a full-featured,
2502  On Emacs versions which support this, it also installs a debugging  key/menu/toolbar-driven interface to commands like @code{breakpoint},
2503  toolbar.  The display of the toolbar can be toggled with @kbd{C-c C-d  @code{.step}, @code{.run}, etc.
2504  C-t} (@code{idlwave-shell-toggle-toolbar}).  
2505    The IDLWAVE shell installs key bindings both in the shell buffer and in
2506    all IDL code buffers of the current Emacs session, so debug commands
2507    work in both places (in the shell, commands operate on the last file
2508    compiled).  On Emacs versions which support this, a debugging toolbar is
2509    also installed.  The display of the toolbar can be toggled with @kbd{C-c
2510    C-d C-t} (@code{idlwave-shell-toggle-toolbar}).
2511    
2512    @defopt idlwave-shell-use-toolbar (@code{t})
2513    Non-@code{nil} means use the debugging toolbar in all IDL related
2514    buffers.
2515    @end defopt
2516    
2517    @menu
2518    * Debug Key Bindings::
2519    * Compiling Programs::
2520    * Breakpoints and Stepping::
2521    * Walking the Calling Stack::
2522    @end menu
2523    
2524    @node Debug Key Bindings, Compiling Programs, Debugging IDL Programs, Debugging IDL Programs
2525    @subsection Debug Key Bindings
2526    @kindex C-c C-d
2527    @cindex Key bindings
2528    
2529  The debugging key bindings are by default on the prefix key @kbd{C-c  The debugging key bindings are by default on the prefix key @kbd{C-c
2530  C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d  C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d
2531  C-b}, compiling a source file with @kbd{C-c C-d C-c}.  If you find this  C-b}, and compiling a source file with @kbd{C-c C-d C-c}.  If you find
2532  too much work you can choose a combination of modifier keys which is not  this too much work, you can easily configure IDLWAVE to use one or more
2533  used by other commands.  For example, if you write in @file{.emacs}  modifier keys not in use by other commands, in lieu of the prefix
2534    @kbd{C-c C-d} (though these bindings will typically also be available
2535    --- see @code{idlwave-shell-activate-prefix-keybindings}).  For example,
2536    if you write in @file{.emacs}:
2537    
2538  @lisp  @lisp
2539  (setq idlwave-shell-debug-modifiers '(control shift))  (setq idlwave-shell-debug-modifiers '(control shift))
2540  @end lisp  @end lisp
2541    
2542  a breakpoint can be set by pressing @kbd{b} while holding down  @noindent a breakpoint can be set by pressing @kbd{b} while holding down
2543  @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}.  Compiling a  @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}.  Compiling a
2544  source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}  source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d},
2545  etc.  In the remainder of this chapter we will assume that the @kbd{C-c  etc.  In the remainder of this chapter we will assume that the @kbd{C-c
2546  C-d} bindings are active, but each of these bindings will have an  C-d} bindings are active, but each of these bindings will have an
2547  equivalent single-keypress shortcut with the modifiers given in the  equivalent single-keypress shortcut if modifiers are given in the
2548  @code{idlwave-shell-debug-modifiers} variable.  @code{idlwave-shell-debug-modifiers} variable (see @pxref{Lesson II --
2549    Customization}).
2550    
2551  @defopt idlwave-shell-prefix-key (@kbd{C-c C-d})  @defopt idlwave-shell-prefix-key (@kbd{C-c C-d})
2552  The prefix key for the debugging map  The prefix key for the debugging map
# Line 1981  The prefix key for the debugging map Line 2554  The prefix key for the debugging map
2554  @end defopt  @end defopt
2555    
2556  @defopt idlwave-shell-activate-prefix-keybindings (@code{t})  @defopt idlwave-shell-activate-prefix-keybindings (@code{t})
2557  Non-@code{nil} means, debug commands will be bound to the prefix  Non-@code{nil} means debug commands will be bound to the prefix
2558  key, like @kbd{C-c C-d C-b}.  key, like @kbd{C-c C-d C-b}.
2559  @end defopt  @end defopt
2560    
2561  @defopt idlwave-shell-debug-modifiers (@code{nil})  @defopt idlwave-shell-debug-modifiers (@code{nil})
2562  List of modifier keys to use for binding debugging commands in the shell  List of modifier keys to use for additional binding of debugging
2563  and in source buffers.  commands in the shell and source buffers.  Can be one or more of
2564  @end defopt  @code{control}, @code{meta}, @code{super}, @code{hyper}, @code{alt}, and
2565    @code{shift}.
 @defopt idlwave-shell-use-toolbar (@code{t})  
 Non-@code{nil} means, use the debugging toolbar in all IDL related  
 buffers.  
2566  @end defopt  @end defopt
2567    
2568    @node Compiling Programs, Breakpoints and Stepping, Debug Key Bindings, Debugging IDL Programs
 @menu  
 * Compiling Programs::          Compiling buffers under the shell  
 * Breakpoints and Stepping::    Deciding where to stop and look  
 * Examining Variables::         What is the value now?  
 @end menu  
   
 @node Compiling Programs, Breakpoints and Stepping, Debugging IDL Programs, Debugging IDL Programs  
2569  @subsection Compiling Programs  @subsection Compiling Programs
2570  @cindex Compiling programs  @cindex Compiling programs
2571  @cindex Programs, compiling  @cindex Programs, compiling
# Line 2012  buffers. Line 2575  buffers.
2575  @kindex C-c C-d C-c  @kindex C-c C-d C-c
2576  In order to compile the current buffer under the IDLWAVE shell, press  In order to compile the current buffer under the IDLWAVE shell, press
2577  @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}).  This first saves the  @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}).  This first saves the
2578  current buffer and then send the command @samp{.run path/to/file} to the  current buffer and then sends the command @samp{.run path/to/file} to the
2579  shell.  You can also execute @kbd{C-c C-d C-c} from the shell buffer, in  shell.  You can also execute @kbd{C-c C-d C-c} from the shell buffer, in
2580  which case the most recently compiled buffer will be saved and  which case the most recently compiled buffer will be saved and
2581  re-compiled.  re-compiled.
2582    
2583  When developing or debugging a program, it is often necessary to execute  When developing or debugging a program, it is often necessary to execute
2584  the same command line many times.  A convenient way to do this is  the same command line many times.  A convenient way to do this is
2585  @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}).  @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}).
2586  This command first resets IDL from a state of interrupted execution by  This command first resets IDL from a state of interrupted execution by
# Line 2027  line, call @code{idlwave-shell-execute-d Line 2590  line, call @code{idlwave-shell-execute-d
2590  prefix argument: @kbd{C-u C-c C-d C-y}.  prefix argument: @kbd{C-u C-c C-d C-y}.
2591    
2592  @defopt idlwave-shell-mark-stop-line (@code{t})  @defopt idlwave-shell-mark-stop-line (@code{t})
2593  Non-@code{nil} means, mark the source code line where IDL is currently  Non-@code{nil} means mark the source code line where IDL is currently
2594  stopped.  The value decides about the preferred method.  Legal values  stopped.  The value specifies the preferred method.  Legal values are
2595  are @code{nil}, @code{t}, @code{arrow}, and @code{face}.  @code{nil}, @code{t}, @code{arrow}, and @code{face}.
2596  @end defopt  @end defopt
2597    
2598  @defopt idlwave-shell-overlay-arrow (@code{">"})  @defopt idlwave-shell-overlay-arrow (@code{">"})
2599  The overlay arrow to display at source lines where execution  The overlay arrow to display at source lines where execution halts, if
2600  halts.  configured in @code{idlwave-shell-mark-stop-line}.
2601  @end defopt  @end defopt
2602    
2603  @defopt idlwave-shell-stop-line-face  @defopt idlwave-shell-stop-line-face
2604  The face which highlights the source line where IDL is  The face which highlights the source line where IDL is stopped, if
2605  stopped.  configured in @code{idlwave-shell-mark-stop-line}.
2606  @end defopt  @end defopt
2607    
2608  @node Breakpoints and Stepping, Examining Variables, Compiling Programs, Debugging IDL Programs  @node Breakpoints and Stepping, Walking the Calling Stack, Compiling Programs, Debugging IDL Programs
2609  @subsection Breakpoints and Stepping  @subsection Breakpoints and Stepping
2610  @cindex Breakpoints  @cindex Breakpoints
2611  @cindex Stepping  @cindex Stepping
# Line 2053  stopped. Line 2616  stopped.
2616  You can set breakpoints and step through a program with IDLWAVE.  You can set breakpoints and step through a program with IDLWAVE.
2617  Setting a breakpoint in the current line of the source buffer is done  Setting a breakpoint in the current line of the source buffer is done
2618  with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}).  With a prefix  with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}).  With a prefix
2619  arg of 1, the breakpoint gets a @code{/ONCE} keyword, meaning that it  arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a
2620  will be deleted after first use.  With a numeric prefix greater than  @code{/ONCE} keyword, meaning that it will be deleted after first use.
2621  one, the breakpoint will only be active the @code{nth} time it is hit.  With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), the
2622  To clear the breakpoint in the current line, use @kbd{C-c C-d C-d}  breakpoint will only be active the @code{nth} time it is hit.  With a
2623  (@code{idlwave-clear-current-bp}).  To clear all breakpoints, use  single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt for a
2624  @kbd{C-c C-d C-a} (@code{idlwave-clear-all-bp}).  Breakpoint lines are  condition --- an IDL expression to be evaulated and trigger the
2625  highlighted in the source code.  breakpoint only if true.  To clear the breakpoint in the current line,
2626    use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}).  When executed
2627  Once the program has stopped somewhere, you can step through it.  Here  from the shell window, the breakpoint where IDL is currently stopped
2628  is a summary of the breakpoint and stepping commands:  will be deleted.  To clear all breakpoints, use @kbd{C-c C-d C-a}
2629    (@code{idlwave-clear-all-bp}).  Breakpoint lines are highlighted in the
2630    source code.  Note that IDL places breakpoints as close as possible on
2631    or after the line you specify.  IDLWAVE queries the shell for the actual
2632    breakpoint location which was set, so the exact line you specify may not
2633    be marked.
2634    
2635    Once the program has stopped somewhere, you can step through it.  The
2636    most important stepping commands are @kbd{C-c C-d C-s} to execute one
2637    line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line,
2638    treating procedure and function calls as a single step ("step over");
2639    @kbd{C-c C-d C-h} to continue execution to the line at the cursor and
2640    @kbd{C-c C-d C-r} to continue execution.  @xref{Commands Sent to the
2641    Shell}, for information on displaying or hiding the breakpoint and
2642    stepping commands the shell receives.  Here is a summary of the
2643    breakpoint and stepping commands:
2644    
2645  @multitable @columnfractions .23 .77  @multitable @columnfractions .23 .77
2646  @item @kbd{C-c C-d C-b}  @item @kbd{C-c C-d C-b}
# Line 2096  is a summary of the breakpoint and stepp Line 2674  is a summary of the breakpoint and stepp
2674  @end multitable  @end multitable
2675    
2676  @defopt idlwave-shell-mark-breakpoints (@code{t})  @defopt idlwave-shell-mark-breakpoints (@code{t})
2677  Non-@code{nil} means, mark breakpoints in the source file buffers.  The  Non-@code{nil} means mark breakpoints in the source file buffers.  The
2678  value indicates the preferred method.  Legal values are @code{nil},  value indicates the preferred method.  Legal values are @code{nil},
2679  @code{t}, @code{face}, and @code{glyph}.  @code{t}, @code{face}, and @code{glyph}.
2680  @end defopt  @end defopt
# Line 2106  The face for breakpoint lines in the sou Line 2684  The face for breakpoint lines in the sou
2684  @code{idlwave-shell-mark-breakpoints} has the value @code{face}.  @code{idlwave-shell-mark-breakpoints} has the value @code{face}.
2685  @end defopt  @end defopt
2686    
2687  @node Examining Variables,  , Breakpoints and Stepping, Debugging IDL Programs  @node Walking the Calling Stack,  , Breakpoints and Stepping, Debugging IDL Programs
2688  @subsection Examining Variables  @subsection Walking the Calling Stack
2689    @cindex Calling stack, walking
2690    
2691    While debugging a program, it can be very useful to check the context in
2692    which the current routine was called, for instance to help understand
2693    the value of the arguments passed.  To do so conveniently you need to
2694    examine the calling stack.  If execution is stopped somewhere deep in a
2695    program, you can use the commands @kbd{C-c C-d C-@key{UP}}
2696    (@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}}
2697    (@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons,
2698    to move up or down through the calling stack.  The mode line of the
2699    shell window will indicate the position within the stack with a label
2700    like @samp{[-3:MYPRO]}.  The line of IDL code at that stack position
2701    will be highlighted.  If you continue execution, IDLWAVE will
2702    automatically return to the current level. @xref{Examining Variables},
2703    for information how to examine the value of variables and expressions on
2704    higher calling stack levels.
2705    
2706    @ifhtml
2707    <A NAME="EXAMINE"></A>
2708    @end ifhtml
2709    @node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell
2710    @section Examining Variables
2711  @cindex @code{PRINT} expressions  @cindex @code{PRINT} expressions
2712  @cindex @code{HELP}, on expressions  @cindex @code{HELP}, on expressions
2713  @cindex Expressions, printing  @cindex Expressions, printing
2714  @cindex Expressions, help  @cindex Expressions, help
2715    @cindex Printing expressions
2716  @cindex Mouse binding to print expressions  @cindex Mouse binding to print expressions
2717    
2718  @kindex C-c C-d C-p  @kindex C-c C-d C-p
2719  When execution is stopped you can examine the values of variables.  The  Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)},
2720  command @kbd{C-c C-d C-p} prints the expression at point, while @kbd{C-c  and similar statements to remind yourself of the
2721  C-d ?} shows help on this expression.  The expression at point is an  type/size/structure/value/etc. of variables and expressions in your code
2722  array expression or a function call, or the contents of a pair of  or at the command line?  IDLWAVE has a suite of special commands to
2723  parenthesis.  The selected expression becomes highlighted in the source  automate these types of variables or expression examinations.  They work
2724  code for a short time.  Calling the above commands with a prefix  by sending statements to the shell formatted to include the indicated
2725  argument will prompt for an expression instead of using the one at  expression.
2726  point.  
2727    These examination commands can be used in the shell or buffer at any
2728  It is very convenient to click with the mouse on expressions to retrieve  time (as long as the shell is running), and are very useful when
2729  their value.  Expression printing is also bound to @kbd{S-Mouse-2} and  execution is stopped in a buffer due to a triggered breakpoint or error,
2730  expression help to @kbd{C-S-Mouse-2}.  I.e. you need to hold down  or while composing a long command in the IDLWAVE shell.  In the latter
2731  @key{SHIFT} and @key{CONTROL} while clicking with the mouse.  case, the command is sent to the shell and its output is visible, but
2732    point remains unmoved in the command being composed --- you can inspect
2733    the constituents of a command you're building without interrupting the
2734    process of building it!  You can even print arbitrary expressions from
2735    older input or output further up in the shell window --- any expression,
2736    variable, number, or function you see can be examined.
2737    
2738    If the variable @code{idlwave-shell-separate-examine-output} is
2739    non-@code{nil} (the default), all examine output will be sent to a
2740    special @file{*Examine*} buffer, rather than the shell.  The output of
2741    prior examine commands is saved.  In this buffer @key{c} clears the
2742    contents, and @key{q} hides the buffer.
2743    
2744    The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to
2745    print the expression at point, and @kbd{C-c C-d ?}, to invoke help on
2746    this expression.  The expression at point is either an array expression
2747    or a function call, or the contents of a pair of parentheses.  The
2748    selected expression is highlighted, and simultaneously the resulting
2749    output is highlighted in the shell.  Calling the above commands with a
2750    prefix argument will prompt for an expression instead of using the one
2751    at point.  Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will use the
2752    current region as expression.
2753    
2754    For added speed and convenience, there are mouse bindings which allow
2755    you to click on expressions and examine their values.  Use
2756    @kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke
2757    help (i.e. you need to hold down @key{META} and @key{CONTROL} while
2758    clicking with the middle mouse button).  If you simply click, the
2759    nearest expression will be selected in the same manner as described
2760    above.  You can also @emph{drag} the mouse in order to highlight exactly
2761    a specific expression or sub-expression to be examined.  For custom
2762    expression examination, and the customizable pop-up examine selection,
2763    @xref{Custom Expression Examination}.
2764    
 @cindex Calling stack, motion  
2765  @cindex Printing expressions, on calling stack  @cindex Printing expressions, on calling stack
2766  @cindex Restrictions for expression printing  @cindex Restrictions for expression printing
2767  Printing of expressions also works on higher levels of the calling  The same variable inspection commands work both in the IDL Shell and
2768  stack.  This means that you can examine the values of variables and  IDLWAVE buffers, and even for variables at higher levels of the calling
2769  expressions inside the routine which called the current routine etc.  stack.  For instance, if you're stopped at a breakpoint in a routine,
2770  Use the commands @kbd{C-c C-d C-@key{UP}}  you can examine the values of variables and expressions inside its
2771  (@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}}  calling routine, and so on, all the way up through the calling stack.
2772  (@code{idlwave-shell-stack-down}) or the corresponding toolbar buttons  Simply step up the stack, and print variables as you see them
2773  to move through the calling stack.  The mode line of the shell window  (@pxref{Walking the Calling Stack}, for information on stepping back
2774  will indicate the routine and the calling stack level which define the  through the calling stack).  The following restrictions apply for all
2775  context for printing expressions.  The following restrictions apply for  levels except the current:
 all levels except the current:  
2776    
2777  @itemize @bullet  @itemize @bullet
2778  @item  @item
# Line 2149  Array expressions must use the @samp{[ ] Line 2780  Array expressions must use the @samp{[ ]
2780  with a @samp{( )} will be interpreted as function calls.  with a @samp{( )} will be interpreted as function calls.
2781  @item  @item
2782  @cindex ROUTINE_NAMES, IDL procedure  @cindex ROUTINE_NAMES, IDL procedure
2783  Printing values of expressions on higher levels of the calling stack  N.B.: printing values of expressions on higher levels of the calling
2784  uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, which may  stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES},
2785  or may not be available in future versions of IDL.  which may or may not be available in future versions of IDL.
2786  @end itemize  @end itemize
2787    
2788  @defopt idlwave-shell-expression-face  @defopt idlwave-shell-expression-face
# Line 2160  Allows you to choose the font, color and Line 2791  Allows you to choose the font, color and
2791  the expression printed by IDL.  the expression printed by IDL.
2792  @end defopt  @end defopt
2793    
2794  @defopt idlwave-shell-print-expression-function (@code{nil})  @defopt idlwave-shell-output-face
2795  A function to handle special display of evaluated expressions.  The face for @code{idlwave-shell-output-overlay}.
2796    Allows to choose the font, color and other properties for the most
2797    recent output of IDL when examining an expression."
2798    @end defopt
2799    
2800    @defopt idlwave-shell-separate-examine-output (@code{t})
2801    If non-@code{nil}, re-direct the output of examine commands to a special
2802    @file{*Examine*} buffer, instead of in the shell itself.
2803    @end defopt
2804    
2805    @node Custom Expression Examination,  , Examining Variables, The IDLWAVE Shell
2806    @section Custom Expression Examination
2807    @cindex Expressions, custom examination
2808    @cindex Custom expression examination
2809    
2810    The variety of possible variable and expression examination commands is
2811    endless (just look, for instance, at the keyword list to
2812    @code{widget_info()}).  Rather than attempt to include them all, IDLWAVE
2813    provides two easy methods to customize your own commands, with a special
2814    mouse examine command, and two macros for generating your own examine
2815    bindings.
2816    
2817    The most powerful and flexible mouse examine command is available on
2818    @kbd{C-S-Mouse-2}.  Just as for all the other mouse examine commands, it
2819    permits click or drag expression selection, but instead of sending
2820    hard-coded commands to the shell, it pops-up a customizable selection
2821    list of examine functions to choose among, configured with the
2822    @code{idlwave-shell-examine-alist} variable.  This variable is a list of
2823    key-value pairs (an @emph{alist} in Emacs parlance), where the keys name
2824    the command, and the values are the command strings, in which the text
2825    @code{___} (three underscores) will be replaced by the selected
2826    expression before being sent to the shell.  An example might be key
2827    @code{Structure Help} with value @code{help,___,/STRUCTURE}.
2828    @code{idlwave-shell-examine-alist} comes by default with a large list of
2829    examine commands, but can be easily customized to add more.
2830    
2831    In addition to the pop-up mouse command, you can easily create your own
2832    customized bindings to inspect expressions using the two convenience
2833    macros @code{idlwave-shell-inspect} and
2834    @code{idlwave-shell-mouse-inspect}.  These create keyboard or
2835    mouse-based custom inspections of variables, sharing all the same
2836    properties of the built-in examine commands.  Both functions take a
2837    single string argument sharing the syntax of the
2838    @code{idlwave-shell-examine-alist} values, e.g.:
2839    
2840    @lisp
2841    (add-hook 'idlwave-shell-mode-hook
2842              (lambda ()
2843                (idlwave-shell-define-key-both [s-down-mouse-2]
2844                                     (idlwave-shell-mouse-examine
2845                                      "print, size(___,/DIMENSIONS)"))
2846                (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
2847                                           "print, size(___,/DIMENSIONS)"))
2848                (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
2849                                            "print,size(___,/TNAME)"))
2850                (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
2851                                            "help,___,/STRUCTURE"))))
2852    @end lisp
2853    
2854    @noindent Now pressing @key{f9}, or middle-mouse dragging with the
2855    @key{SUPER} key depressed, will print the dimensions of the nearby or
2856    highlighted expression.  Pressing @key{f10} will give the type string,
2857    and @key{f11} will show the contents of a nearby structure.  As you can
2858    see, the possibilities are only marginally finite.
2859    
2860    @defopt idlwave-shell-examine-alist
2861    An alist of examine commands in which the keys name the command and are
2862    displayed in the selection pop-up, and the values are custom IDL examine
2863    command strings to send, after all instances of @code{___} are replaced
2864    by the indicated expression.
2865  @end defopt  @end defopt
2866    
2867  @node Installation, Acknowledgement, The IDLWAVE Shell, Top  
2868    @node Installation, Acknowledgements, The IDLWAVE Shell, Top
2869  @chapter Installation  @chapter Installation
2870  @cindex Installation  @cindex Installation
2871    
# Line 2189  and can be installed from Line 2890  and can be installed from
2890  @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site}  @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site}
2891  with the normal package management system on XEmacs 21.  These  with the normal package management system on XEmacs 21.  These
2892  pre-installed versions should work out-of-the-box.  However, the files  pre-installed versions should work out-of-the-box.  However, the files
2893  needed for online help are not distributed with XEmacs/Emacs and have to  required for online help are not distributed with XEmacs/Emacs and have
2894  be installed separately@footnote{Due to copyright reasons, the ASCII  to be installed separately@footnote{Due to copyright reasons, the ASCII
2895  version of the IDL manual cannot be distributed under the GPL.}  version of the IDL manual cannot be distributed under the GPL.}
2896  (@pxref{Installing Online Help}).  (@pxref{Installing Online Help}).
2897    
# Line 2198  You can also download IDLWAVE and instal Line 2899  You can also download IDLWAVE and instal
2899  @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}.  Follow the  @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}.  Follow the
2900  instructions in the INSTALL file.  instructions in the INSTALL file.
2901    
2902  @node Installing Online Help, Upgrading from idl.el  , Installing IDLWAVE, Installation  @node Installing Online Help, Upgrading from idl.el, Installing IDLWAVE, Installation
2903  @section Installing Online Help  @section Installing Online Help
2904  @cindex Installing online help  @cindex Installing online help
2905  @cindex Online Help, Installation  @cindex Online Help, Installation
# Line 2240  to get a separate frame for the IDL shel Line 2941  to get a separate frame for the IDL shel
2941  @lisp  @lisp
2942  (setq idlwave-shell-use-dedicated-frame t)  (setq idlwave-shell-use-dedicated-frame t)
2943  @end lisp  @end lisp
2944  @item  @item
2945  The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character.  The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character.
2946  Like in many other Emacs modes, @kbd{M-@key{TAB}} now does  Like in many other Emacs modes, @kbd{M-@key{TAB}} now does
2947  completion.  Inserting a TAB has therefore been moved to  completion.  Inserting a TAB has therefore been moved to
# Line 2248  completion.  Inserting a TAB has therefo Line 2949  completion.  Inserting a TAB has therefo
2949  @kbd{C-c @key{SPC}}.  @kbd{C-c @key{SPC}}.
2950  @end enumerate  @end enumerate
2951    
2952  @node Acknowledgement, Sources of Routine Info, Installation, Top  @node Acknowledgements, Sources of Routine Info, Installation, Top
2953  @chapter Acknowledgement  @chapter Acknowledgements
2954  @cindex Acknowledgement  @cindex Acknowledgements
2955  @cindex Maintainer, of IDLWAVE  @cindex Maintainer, of IDLWAVE
2956  @cindex Authors, of IDLWAVE  @cindex Authors, of IDLWAVE
2957  @cindex Contributors, to IDLWAVE  @cindex Contributors, to IDLWAVE
# Line 2267  Chris wrote @file{idl.el} and @file{idl- Line 2968  Chris wrote @file{idl.el} and @file{idl-
2968  for several years.  for several years.
2969    
2970  @item  @item
2971  @uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}}, who have  @uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge
2972  been in charge of the package since version 3.0, and also wrote this  of the package from version 3.0, during which time he overhauled almost
2973    everything, modernized IDLWAVE with many new features, and developed the
2974  manual.  manual.
2975    
2976  @item  @item
2977  @uref{mailto: jdsmith@@astro.cornell.edu, @b{John-David Smith}},  @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current
2978  current maintainer, who is also responsible for this manual's  maintainer, as of version 4.10, helped shape object method completion
2979  maintenance.  John-David has also shaped Object method completion and  and most new features introduced in versions 4.x.
 most new features in version 4.0 with his ideas, bug reports, and  
 patient explanations of IDL internals.  
2980  @end itemize  @end itemize
2981    
2982  @noindent  @noindent
# Line 2295  space.mit.edu> Line 2995  space.mit.edu>
2995  @item  @item
2996  Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de>  Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de>
2997  @item  @item
2998    Dick Jackson <dick@@d-jackson.com>
2999    @item
3000  Xuyong Liu <liu@@stsci.edu>  Xuyong Liu <liu@@stsci.edu>
3001  @item  @item
3002  Simon Marshall <Simon.Marshall@@esrin.esa.it>  Simon Marshall <Simon.Marshall@@esrin.esa.it>
# Line 2305  onera.fr> Line 3007  onera.fr>
3007  @item  @item
3008  Lubos Pochman <lubos@@rsinc.com>  Lubos Pochman <lubos@@rsinc.com>
3009  @item  @item
3010    Bob Portmann <portmann@@al.noaa.gov>
3011    @item
3012  Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov>  Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov>
3013  @item  @item
3014  Marty Ryba <ryba@@ll.mit.edu>  Marty Ryba <ryba@@ll.mit.edu>
# Line 2317  dublin.llnl.gov> Line 3021  dublin.llnl.gov>
3021  @noindent  @noindent
3022  Thanks to everyone!  Thanks to everyone!
3023    
3024  @node Sources of Routine Info, Configuration Examples, Acknowledgement, Top  @node Sources of Routine Info, Configuration Examples, Acknowledgements, Top
3025  @appendix Sources of Routine Info  @appendix Sources of Routine Info
3026    
3027  @cindex Sources of routine information  @cindex Sources of routine information
3028  In @ref{Routine Info} and @ref{Completion} it was shown how IDLWAVE  In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE
3029  displays the calling sequence and keywords of routines, and how it  displays the calling sequence and keywords of routines, and completes
3030  completes routine names and keywords.  For these features to work,  routine names and keywords.  For these features to work, IDLWAVE must
3031  IDLWAVE must know about the accessible routines.  know about the accessible routines.
3032    
3033  @menu  @menu
3034  * Routine Definitions::         Where IDL Routines are defined.  * Routine Definitions::         Where IDL Routines are defined.
# Line 2335  IDLWAVE must know about the accessible r Line 3039  IDLWAVE must know about the accessible r
3039  @end menu  @end menu
3040    
3041  @node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info  @node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info
3042  @section Routine Definitions  @appendixsec Routine Definitions
3043  @cindex Routine definitions  @cindex Routine definitions
3044  @cindex IDL variable @code{!PATH}  @cindex IDL variable @code{!PATH}
3045  @cindex @code{!PATH}, IDL variable  @cindex @code{!PATH}, IDL variable
# Line 2343  IDLWAVE must know about the accessible r Line 3047  IDLWAVE must know about the accessible r
3047  @cindex @code{LINKIMAGE}, IDL routine  @cindex @code{LINKIMAGE}, IDL routine
3048  @cindex External routines  @cindex External routines
3049    
3050  Routines which can be used in an IDL program can be defined in several  @noindent Routines which can be used in an IDL program can be defined in
3051  places:  several places:
3052    
3053  @enumerate  @enumerate
3054  @item  @item
3055  @emph{Builtin routines} are defined inside IDL itself.  The source  @emph{Builtin routines} are defined inside IDL itself.  The source
3056  code of such routines is not accessible to the user.  code of such routines is not available.
3057  @item  @item
3058  Routines @emph{part of the current program} are defined in a file which  Routines which are @emph{part of the current program}, are defined in a
3059  is explicitly compiled by the user.  This file may or may not be located  file explicitly compiled by the user.  This file may or may not be
3060  on the IDL search path.  located on the IDL search path.
3061  @item  @item
3062  @emph{Library routines} are defined in special files which are located  @emph{Library routines} are defined in files located on IDL's search
3063  somewhere on IDL's search path.  When a library routine is called for  path, and will not need to be manually compiled.  When a library routine
3064  the first time, IDL will find the source file and compile it  is called for the first time, IDL will find the source file and compile
3065  dynamically.  it dynamically.  A special sub-category of library routines are the
3066    @emph{system routines} distributed with IDL, and usually available in
3067    the @file{lib} subdirectory of the IDL distribution.
3068  @item  @item
3069  External routines written in other languages (like Fortran or C) can be  External routines written in other languages (like Fortran or C) can be
3070  called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE},  called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE},
3071  or included as dynamically loaded modules (DLMs).  Currently IDLWAVE  or included as dynamically loaded modules (DLMs).  Currently IDLWAVE
3072  cannot provide routine info and completion for external  cannot provide routine info and completion for such external routines.
 routines.  
3073  @end enumerate  @end enumerate
3074    
3075  @node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info  @node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info
3076  @section Routine Information Sources  @appendixsec Routine Information Sources
3077  @cindex Routine info sources  @cindex Routine info sources
3078  @cindex Builtin list of routines  @cindex Builtin list of routines
3079  @cindex Updating routine info  @cindex Updating routine info
# Line 2376  routines. Line 3081  routines.
3081  @cindex Buffers, scanning for routine info  @cindex Buffers, scanning for routine info
3082  @cindex Shell, querying for routine info  @cindex Shell, querying for routine info
3083    
3084  In oder to know about as many routines as possible, IDLWAVE will do the  @noindent To maintain the most comprehensive information about all IDL
3085  following to collect information:  routines on a system, IDLWAVE collects data from many sources:
3086    
3087  @enumerate  @enumerate
3088    
# Line 2387  routines.  IDLWAVE @value{VERSION} is di Line 3092  routines.  IDLWAVE @value{VERSION} is di
3092  @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords,  @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords,
3093  reflecting IDL version @value{IDLVERSION}.  This list has been created  reflecting IDL version @value{IDLVERSION}.  This list has been created
3094  by scanning the IDL manuals and is stored in the file  by scanning the IDL manuals and is stored in the file
3095  @file{idlw-rinfo.el}.  @xref{Documentation Scan}, for  @file{idlw-rinfo.el}.  @xref{Documentation Scan}, for information on how
3096  information how to regenerate this file for new versions of IDL.  to regenerate this file for new versions of IDL.
3097    
3098  @item  @item
3099  It @emph{scans} all @emph{buffers} of the current Emacs session for  It @emph{scans} all @emph{buffers} of the current Emacs session for
3100  routine definitions.  This is done automatically when routine  routine definitions.  This is done automatically when routine
3101  information or completion is first requested by the user.  Each new  information or completion is first requested by the user.  Each new
# Line 2399  scanned. The command @kbd{C-c C-i} (@cod Line 3104  scanned. The command @kbd{C-c C-i} (@cod
3104  can be used at any time to rescan all buffers.  can be used at any time to rescan all buffers.
3105    
3106  @item  @item
3107  If you have an IDLWAVE-Shell running as inferior process of the current  If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will
3108  Emacs session, IDLWAVE will @emph{query the shell} for compiled routines  @emph{query the shell} for compiled routines and their arguments.  This
3109  and their arguments.  This happens automatically when routine  happens automatically when routine information or completion is first
3110  information or completion is first requested by the user, and each time  requested by the user, and each time an Emacs buffer is compiled with
3111  an Emacs buffer is compiled with @kbd{C-c C-d C-c}.  The command  @kbd{C-c C-d C-c}.  Though rarely necessary, the command @kbd{C-c C-i}
3112  @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used to ask  (@code{idlwave-update-routine-info}) can be used to update the shell
3113  the shell again at any time.  routine data.
3114    
3115  @item  @item
3116  IDLWAVE can scan all or selected library files and store the result in a  IDLWAVE can scan all or selected library source files and store the
3117  file which will be automatically loaded just like  result in a file which will be automatically loaded just like
3118  @file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to  @file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to
3119  scan library files.  scan library files.
3120  @end enumerate  @end enumerate
3121    
3122    Loading routine and catalog information is a time consuming process.
3123    Depending on the system and network configuration it can take up to 30
3124    seconds.  In order to minimize the waiting time upon your first
3125    completion or routine info command in a session, IDLWAVE uses Emacs idle
3126    time to do the initialization in 5 steps, yielding to user input in
3127    between.  If this gets into your way, set the variable
3128    @code{idlwave-init-rinfo-when-idle-after} to 0 (zero).
3129    
3130    @defopt idlwave-init-rinfo-when-idle-after (@code{10})
3131    Seconds of idle time before routine info is automatically initialized.
3132    @end defopt
3133    
3134  @defopt idlwave-scan-all-buffers-for-routine-info (@code{t})  @defopt idlwave-scan-all-buffers-for-routine-info (@code{t})
3135  Non-@code{nil} means, scan all buffers for IDL programs when updating  Non-@code{nil} means scan all buffers for IDL programs when updating
3136  info.  info.
3137  @end defopt  @end defopt
3138    
# Line 2428  Controls under what circumstances routin Line 3145  Controls under what circumstances routin
3145  @end defopt  @end defopt
3146    
3147  @node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info  @node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
3148  @section Library Catalog  @appendixsec Library Catalog
3149  @cindex Library scan  @cindex Library scan
3150  @cindex Library catalog  @cindex Library catalog
3151  @cindex IDL library routine info  @cindex IDL library routine info
# Line 2446  file will contain lisp code, its name sh Line 3163  file will contain lisp code, its name sh
3163  Windows and MacOS, you also need to specify the search path for IDL  Windows and MacOS, you also need to specify the search path for IDL
3164  library files in the variable @code{idlwave-library-path}, and the  library files in the variable @code{idlwave-library-path}, and the
3165  location of the IDL directory (the value of the @code{!DIR} system  location of the IDL directory (the value of the @code{!DIR} system
3166  variable) in the variable @code{idlwave-system-directory}.  Under Unix and GNU,  variable) in the variable @code{idlwave-system-directory}, like
3167  these values will be automatically inferred from an IDLWAVE  this@footnote{The initial @samp{+} leads to recursive expansion of the
3168  shell.  path, just like in IDL}:
3169    
3170    @lisp
3171    (setq idlwave-library-path
3172            '("+c:/RSI/IDL54/lib/" "+c:/user/me/idllibs" ))
3173    (setq idlwave-system-directory "c:/RSI/IDL54/")
3174    @end lisp
3175    
3176    @noindent Under GNU and UNIX, these values will be automatically inferred from
3177    an IDLWAVE shell.
3178    
3179  The command @kbd{M-x idlwave-create-libinfo-file} can then be used to  The command @kbd{M-x idlwave-create-libinfo-file} can then be used to
3180  scan library files.  It brings up a widget in which you can select some  scan library files.  It brings up a widget in which you can select some
# Line 2456  or all directories on the search path. Line 3182  or all directories on the search path.
3182  and completion info of some libraries, it is sufficient to scan those  and completion info of some libraries, it is sufficient to scan those
3183  directories.  However, if you want IDLWAVE to detect possible name  directories.  However, if you want IDLWAVE to detect possible name
3184  conflicts with routines defined in other libraries, the whole pass  conflicts with routines defined in other libraries, the whole pass
3185  should be scanned.  should be scanned.
3186    
3187  After selecting directories, click on the @w{@samp{[Scan & Save]}}  After selecting directories, click on the @w{@samp{[Scan & Save]}}
3188  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
# Line 2466  from the same directories, call the comm Line 3192  from the same directories, call the comm
3192  @code{idlwave-update-routine-info} with a double prefix argument:  @code{idlwave-update-routine-info} with a double prefix argument:
3193  @w{@kbd{C-u C-u C-c C-i}}.  This will rescan files in the previously  @w{@kbd{C-u C-u C-c C-i}}.  This will rescan files in the previously
3194  selected directories, write an updated version of the libinfo file and  selected directories, write an updated version of the libinfo file and
3195  rebuild IDLWAVEs internal lists.  rebuild IDLWAVE's internal lists.  If you give three prefix arguments
3196    @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a background
3197    job@footnote{Unix systems only, I think.}.  You can continue to work,
3198    and the library catalog will be re-read when it is ready.
3199    
3200  A note of caution:  Depending on your local installation, the IDL  A note of caution:  Depending on your local installation, the IDL
3201  library can be very large.  Parsing it for routine information will take  library can be very large.  Parsing it for routine information will take
# Line 2479  File for routine information of the IDL Line 3208  File for routine information of the IDL
3208  @end defopt  @end defopt
3209    
3210  @defopt idlwave-library-path  @defopt idlwave-library-path
3211  IDL library path for Windows and MacOS.  Not needed under GNU and Unix.  IDL library path for Windows and MacOS.  Not needed under Unix.
3212  @end defopt  @end defopt
3213    
3214  @defopt idlwave-system-directory  @defopt idlwave-system-directory
3215  The IDL system directory for Windows and MacOS.  Not needed under GNU and Unix.  The IDL system directory for Windows and MacOS.  Not needed under Unix.
3216  @end defopt  @end defopt
3217    
3218  @defopt idlwave-special-lib-alist  @defopt idlwave-special-lib-alist
# Line 2491  Alist of regular expressions matching sp Line 3220  Alist of regular expressions matching sp
3220  @end defopt  @end defopt
3221    
3222  @node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info  @node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info
3223  @section Load-Path Shadows  @appendixsec Load-Path Shadows
3224  @cindex Load-path shadows  @cindex Load-path shadows
3225  @cindex Shadows, load-path  @cindex Shadows, load-path
3226  @cindex Duplicate routines  @cindex Duplicate routines
# Line 2508  load path shadows.  The output is placed Line 3237  load path shadows.  The output is placed
3237  @file{*Shadows*}.  The format of the output is identical to the source  @file{*Shadows*}.  The format of the output is identical to the source
3238  section of the routine info buffer (@pxref{Routine Info}).  The  section of the routine info buffer (@pxref{Routine Info}).  The
3239  different definitions of a routine are listed in the sequence of  different definitions of a routine are listed in the sequence of
3240  @emph{likelyhood of use}.  So the first entry will be most likely the  @emph{likelihood of use}.  So the first entry will be most likely the
3241  one you'll get if an unsuspecting command uses that routine.  Before  one you'll get if an unsuspecting command uses that routine.  Before
3242  listing shadows, you should make sure that routine info is up-to-date by  listing shadows, you should make sure that routine info is up-to-date by
3243  pressing @kbd{C-c C-i}.  Here are the different routines:  pressing @kbd{C-c C-i}.  Here are the different routines:
# Line 2529  This command checks all routines accessi Line 3258  This command checks all routines accessi
3258  @end table  @end table
3259    
3260  For these commands to work properly you should have scanned the entire  For these commands to work properly you should have scanned the entire
3261  load path, not just selected directories.  Also, IDLWAVE should be able to  load path, not just selected directories.  Also, IDLWAVE should be able
3262  distinguish between the system library files (normally installed in  to distinguish between the system library files (normally installed in
3263  @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
3264  files.  Therefore, such local files should not be installed  files.  Therefore, such local files should not be installed inside the
3265  inside the @file{lib} directory of the IDL directory.  This is of course  @file{lib} directory of the IDL directory.  This is also advisable for
3266  also advisable for many other reasons.  many other reasons.
3267    
3268  @cindex Windows  @cindex Windows
3269  @cindex MacOS  @cindex MacOS
# Line 2550  Another way to find out if a specific ro Line 3279  Another way to find out if a specific ro
3279  on the load path is routine info display (@pxref{Routine Info}).  on the load path is routine info display (@pxref{Routine Info}).
3280    
3281  @node Documentation Scan,  , Load-Path Shadows, Sources of Routine Info  @node Documentation Scan,  , Load-Path Shadows, Sources of Routine Info
3282  @section Documentation Scan  @appendixsec Documentation Scan
3283  @cindex @file{get_rinfo}  @cindex @file{get_rinfo}
3284  @cindex @file{idlw-rinfo.el}  @cindex @file{idlw-rinfo.el}
3285  @cindex @file{idlw-help.txt}  @cindex @file{idlw-help.txt}
# Line 2572  contains the Perl program @file{get_rinf Line 3301  contains the Perl program @file{get_rinf
3301  by scanning selected files from the IDL documentation.  Instructions on  by scanning selected files from the IDL documentation.  Instructions on
3302  how to use @file{get_rinfo} are in the program itself.  how to use @file{get_rinfo} are in the program itself.
3303    
3304  @node Configuration Examples, Index, Sources of Routine Info, Top  One particularly frustrating situation occurs when a new IDL version is
3305    released without the associated documentation updates.  Instead, a
3306    @emph{What's New} file containing new and updated documentation is
3307    shipped alongside the previous version's reference material.  The
3308    @file{get_rinfo} script can merge this new information into the standard
3309    help text and routine information, as long as it is pre-formatted in a
3310    simple way.  See @file{get_rinfo} for more information.
3311    
3312    @node Configuration Examples, Windows and MacOS, Sources of Routine Info, Top
3313  @appendix Configuration Examples  @appendix Configuration Examples
3314  @cindex Configuration examples  @cindex Configuration examples
3315  @cindex Example configuration  @cindex Example configuration
# Line 2581  how to use @file{get_rinfo} are in the p Line 3318  how to use @file{get_rinfo} are in the p
3318  @cindex Interview, with the maintainer  @cindex Interview, with the maintainer
3319    
3320  @noindent  @noindent
3321  @b{Question:} So now you have all these complicated configuration  @b{Question:} You have all these complicated configuration options in
3322  options in your package, but which ones do @emph{you} as the maintainer  your package, but which ones do @emph{you} as the maintainer actually
3323  actually set in your own configuration?  set in your own configuration?
3324    
3325  @noindent  @noindent
3326  @b{Answer:} Hardly any.  As the maintainer, I set the default of most  @b{Answer:} Not many, beyond custom key bindings.  I set most defaults
3327  options to what I think is best.  However, the default settings do not  the way that seems best.  However, the default settings do not turn on
3328  turn on features which  features which:
3329    
3330  @itemize @minus  @itemize @minus
3331  @item  @item
3332  are not self-evident (i.e. too magic) when used by an unsuspecting user  are not self-evident (i.e. too magic) when used by an unsuspecting user.
3333  @item  @item
3334  are too intrusive  are too intrusive.
3335  @item  @item
3336  will not work properly on all Emacs installations out there  will not work properly on all Emacs installations.
3337  @item  @item
3338  break with widely used standards.  break with widely used standards.
3339    @item
3340    use function or other non-standard keys.
3341    @item
3342    are purely personal customizations, like additional key bindings, and
3343    library names.
3344  @end itemize  @end itemize
3345    
3346  @noindent To see what I mean, here is the @emph{entire} configuration I  @noindent To see what I mean, here is the @emph{entire} configuration
3347  have in my @file{.emacs}:  the old maintainer had in his @file{.emacs}:
3348    
3349  @lisp  @lisp
3350  (setq idlwave-shell-debug-modifiers '(control shift)  (setq idlwave-shell-debug-modifiers '(control shift)
3351        idlwave-store-inquired-class t        idlwave-store-inquired-class t
3352        idlwave-shell-automatic-start t        idlwave-shell-automatic-start t
3353        idlwave-main-block-indent 2        idlwave-main-block-indent 2
3354          idlwave-init-rinfo-when-idle-after 2
3355        idlwave-help-dir "~/lib/emacs/idlwave"        idlwave-help-dir "~/lib/emacs/idlwave"
3356        idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib")        idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib")
3357                                    ("/jhuapl/" . "JHUAPL-Lib")                                    ("/jhuapl/" . "JHUAPL-Lib")
# Line 2616  have in my @file{.emacs}: Line 3359  have in my @file{.emacs}:
3359  @end lisp  @end lisp
3360    
3361  However, if you are an Emacs power-user and want IDLWAVE to work  However, if you are an Emacs power-user and want IDLWAVE to work
3362  completely differently, the options allow you to change almost every  completely differently, you can change almost every aspect of it.  Here
3363  aspect of it.  Here is an example of a much more extensive configuration  is an example of a much more extensive configuration of IDLWAVE.  The
 of IDLWAVE.  To say it again - this is not what I recommend, but the  
3364  user is King!  user is King!
3365    
3366  @example  @example
# Line 2628  user is King! Line 3370  user is King!
3370  (setq idlwave-main-block-indent 3)  (setq idlwave-main-block-indent 3)
3371  (setq idlwave-end-offset -3)  (setq idlwave-end-offset -3)
3372  (setq idlwave-continuation-indent 1)  (setq idlwave-continuation-indent 1)
3373  (setq idlwave-begin-line-comment "^;[^;]")  ; Leave ";" but not ";;"  (setq idlwave-begin-line-comment "^;[^;]")  ; Leave ";" but not ";;"
3374                                              ; anchored at start of line.                                              ; anchored at start of line.
3375  (setq idlwave-surround-by-blank t)      ; Turn on padding ops =,<,>  (setq idlwave-surround-by-blank t)      ; Turn on padding ops =,<,>
3376  (setq idlwave-pad-keyword nil)          ; Remove spaces for keyword '='  (setq idlwave-pad-keyword nil)          ; Remove spaces for keyword '='
# Line 2639  user is King! Line 3381  user is King!
3381  (setq idlwave-hang-indent-regexp ": ")  ; Change from "- " for auto-fill  (setq idlwave-hang-indent-regexp ": ")  ; Change from "- " for auto-fill
3382  (setq idlwave-show-block nil)           ; Turn off blinking to begin  (setq idlwave-show-block nil)           ; Turn off blinking to begin
3383  (setq idlwave-abbrev-move t)            ; Allow abbrevs to move point  (setq idlwave-abbrev-move t)            ; Allow abbrevs to move point
3384    (setq idlwave-query-class '((method-default . nil) ; No query for method
3385                                (keyword-default . nil); or keyword completion
3386                                ("INIT" . t)           ; except for these
3387                                ("CLEANUP" . t)
3388                                ("SETPROPERTY" .t)
3389                                ("GETPROPERTY" .t)))
3390    
3391  ;; 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:
   
3392  (add-hook 'idlwave-mode-hook  (add-hook 'idlwave-mode-hook
3393    (lambda ()    (lambda ()
     (setq abbrev-mode 1)                 ; Turn on abbrevs (-1 for off)  
3394      (setq case-fold-search nil)          ; Make searches case sensitive      (setq case-fold-search nil)          ; Make searches case sensitive
3395      ;; Run other functions here      ;; Run other functions here
3396      (font-lock-mode 1)                   ; Turn on font-lock mode      (font-lock-mode 1)                   ; Turn on font-lock mode
3397      (idlwave-auto-fill-mode 0)           ; Turn off auto filling      (idlwave-auto-fill-mode 0)           ; Turn off auto filling
3398      ;;  
3399      ;; Pad with 1 space (if -n is used then make the      ;; Pad with 1 space (if -n is used then make the
3400      ;; padding a minimum of n spaces.)  The defaults use -1      ;; padding a minimum of n spaces.)  The defaults use -1
3401      ;; instead of 1.      ;; instead of 1.
# Line 2657  user is King! Line 3403  user is King!
3403      (idlwave-action-and-binding "<" '(idlwave-surround 1 1))      (idlwave-action-and-binding "<" '(idlwave-surround 1 1))
3404      (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-)))      (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-)))
3405      (idlwave-action-and-binding "&" '(idlwave-surround 1 1))      (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
3406      ;;  
3407      ;; Only pad after comma and with exactly 1 space      ;; Only pad after comma and with exactly 1 space
3408      (idlwave-action-and-binding "," '(idlwave-surround nil 1))      (idlwave-action-and-binding "," '(idlwave-surround nil 1))
3409      (idlwave-action-and-binding "&" '(idlwave-surround 1 1))      (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
3410      ;;  
3411      ;; Pad only after `->', remove any space before the arrow      ;; Pad only after `->', remove any space before the arrow
3412      (idlwave-action-and-binding "->"  '(idlwave-surround 0 -1 nil 2))      (idlwave-action-and-binding "->"  '(idlwave-surround 0 -1 nil 2))
3413      ;;;  
3414      ;; Set some personal bindings      ;; Set some personal bindings
3415      ;; (In this case, makes `,' have the normal self-insert behavior.)      ;; (In this case, makes `,' have the normal self-insert behavior.)
3416      (local-set-key "," 'self-insert-command)      (local-set-key "," 'self-insert-command)
3417        (local-set-key [f5] 'idlwave-shell-break-here)
3418        (local-set-key [f6] 'idlwave-shell-clear-current-bp)
3419    
3420      ;; Create a newline, indenting the original and new line.      ;; Create a newline, indenting the original and new line.
3421      ;; A similar function that does _not_ reindent the original      ;; A similar function that does _not_ reindent the original
3422      ;; line is on "\C-j" (The default for emacs programming modes).      ;; line is on "\C-j" (The default for emacs programming modes).
3423      (local-set-key "\n" 'idlwave-newline)      (local-set-key "\n" 'idlwave-newline)
3424      ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference.      ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference.
3425    
3426        ;; Some personal abbreviations
3427        (define-abbrev idlwave-mode-abbrev-table
3428          (concat idlwave-abbrev-start-char "wb") "widget_base()"
3429          (idlwave-keyword-abbrev 1))
3430        (define-abbrev idlwave-mode-abbrev-table
3431          (concat idlwave-abbrev-start-char "on") "obj_new()"
3432          (idlwave-keyword-abbrev 1))
3433      ))      ))
3434    
3435  ;;; Settings for IDLWAVE SHELL mode  ;;; Settings for IDLWAVE SHELL mode
# Line 2683  user is King! Line 3440  user is King!
3440  (setq idlwave-shell-explicit-file-name "wave")  (setq idlwave-shell-explicit-file-name "wave")
3441  (setq idlwave-shell-process-name "wave")  (setq idlwave-shell-process-name "wave")
3442  (setq idlwave-shell-use-toolbar nil)           ; No toolbar  (setq idlwave-shell-use-toolbar nil)           ; No toolbar
3443    
3444    ;; Most shell interaction settings can be done from the shell-mode-hook.
3445    (add-hook 'idlwave-shell-mode-hook
3446              (lambda ()
3447                ;; Set up some custom key and mouse examine commands
3448                (idlwave-shell-define-key-both [s-down-mouse-2]
3449                                     (idlwave-shell-mouse-examine
3450                                      "print, size(___,/DIMENSIONS)"))
3451                (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
3452                                           "print, size(___,/DIMENSIONS)"))
3453                (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
3454                                            "print,size(___,/TNAME)"))
3455                (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
3456                                            "help,___,/STRUCTURE"))))
3457  @end example  @end example
3458    
3459  @node Index,  , Configuration Examples, Top  @ifhtml
3460    <A NAME="WIN_MAC"></A>
3461    @end ifhtml
3462    @node Windows and MacOS, Index, Configuration Examples, Top
3463    @appendix Windows and MacOS
3464    @cindex Windows
3465    @cindex MacOS
3466    
3467    IDLWAVE was developed on a UNIX system.  However, due to the portability
3468    of Emacs, much of IDLWAVE does also work under different operating
3469    systems like Windows (with NTEmacs or NTXEmacs) or MacOS.
3470    
3471    The only problem really is that RSI does not provide a command-line
3472    version of IDL for Windows or MacOS with which IDLWAVE can
3473    interact@footnote{Call your RSI representative and complain --- it
3474    should be trivial for them to provide one.  And if enough people ask
3475    for it, maybe they will.  The upcoming IDL for Mac OSX is slated to
3476    have a command-line version.}.  Therefore the IDLWAVE Shell does not
3477    work and you have to rely on IDLDE to run and debug your programs.
3478    However, editing IDL source files with Emacs/IDLWAVE works with all
3479    bells and whistles, including routine info, completion and fast online
3480    help.  Only a small amount of additional information must be specified
3481    in your .emacs file: the path names which, on a UNIX system, are
3482    automatically gathered by talking to the IDL program.
3483    
3484    Here is an example of the additional configuration needed for a Windows
3485    system.  I am assuming that IDLWAVE has been installed in
3486    @w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in
3487    @w{@samp{C:\RSI\IDL55}}.
3488    
3489    @lisp
3490    ;; location of the lisp files (needed if IDLWAVE is not part of
3491    ;; the X/Emacs installation)
3492    (setq load-path (cons "c:/program files/IDLWAVE" load-path))
3493    
3494    ;; The location of the IDL library files, both from RSI and your own.
3495    ;; note that the initial "+" expands the path recursively
3496    (setq idlwave-library-path
3497            '("+c:/RSI/IDL55/lib/" "+c:/user/me/idllibs" ))
3498    
3499    ;; location of the IDL system directory (try "print,!DIR")
3500    (setq idlwave-system-directory "c:/RSI/IDL55/")
3501    
3502    ;; location of the IDLWAVE help files idlw-help.el and idlw-help.txt.
3503    (setq idlwave-help-directory "c:/IDLWAVE")
3504    
3505    ;; file in which to store the user catalog info
3506    (setq idlwave-libinfo-file "c:/IDLWAVE/idlcat.el")
3507    @end lisp
3508    
3509    @noindent Furthermore, Windows sometimes tries to outsmart you --- make
3510    sure you check the following things:
3511    
3512    @itemize @bullet
3513    @item When you download the IDLWAVE distribution, make sure you save the
3514    files under the names @file{idlwave.tar.gz} and
3515    @file{idlwave-help-tar.gz}.
3516    @item Be sure that your software for untarring/ungzipping is @emph{NOT}
3517    doing smart CR/LF conversion (WinZip users will find this in
3518    Options:Configuration:Miscellaneous, change the setting, then re-open
3519    the archive).  This adds one byte per line, throwing off the
3520    byte-counts for the help file lookups and defeating fast online help lookup.
3521    @item M-TAB switches among running programs --- use Esc-TAB
3522    instead.
3523    @item Other issues as yet unnamed...
3524    @end itemize
3525    
3526    
3527    @node Index,  , Windows and MacOS, Top
3528  @unnumbered Index  @unnumbered Index
3529  @printindex cp  @printindex cp
3530    
3531  @bye  @bye
   

Legend:
Removed from v.1.18  
changed lines
  Added in v.1.18.4.1

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