@synindex ky cp
@syncodeindex vr cp
@syncodeindex fn cp
-@set VERSION 4.2
-@set EDITION 4.2
-@set IDLVERSION 5.3
-@set NSYSROUTINES 1251
-@set NSYSKEYWORDS 5287
-@set DATE June 2000
+@set VERSION 4.7
+@set EDITION 4.7
+@set IDLVERSION 5.4
+@set NSYSROUTINES 1287
+@set NSYSKEYWORDS 5724
+@set DATE December 2000
@set AUTHOR Carsten Dominik
@set AUTHOR-EMAIL dominik@@astro.uva.nl
@set MAINTAINER Carsten Dominik
This is edition @value{EDITION} of the IDLWAVE User Manual for
IDLWAVE @value{VERSION}
-Copyright (c) 1999, 2000 Free Software Foundation, Inc.
+Copyright (c) 1999, 2000, 2001 Free Software Foundation, Inc.
-Permission is granted to make and distribute verbatim
-copies of this manual provided the copyright notice and
-this permission notice are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX
-and print the results, provided the printed document
-carries a copying permission notice identical to this
-one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified
-versions of this manual under the conditions for
-verbatim copying, provided that the entire resulting
-derived work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute
-translations of this manual into another language,
-under the above conditions for modified versions,
-except that this permission notice may be stated in a
-translation approved by the Free Software Foundation.
+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.
@end ifinfo
@titlepage
@author by Carsten Dominik
@page
-Copyright @copyright{} 1999, 2000 Free Software Foundation, Inc.
-
-@sp 2
This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for
IDLWAVE version @value{VERSION}, @value{DATE}.
-
@sp 2
-
+Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc.
+@sp 2
@cindex Copyright, of IDLWAVE
-Permission is granted to make and distribute verbatim
-copies of this manual provided the copyright notice and
-this permission notice are preserved on all copies.
-
-Permission is granted to copy and distribute modified
-versions of this manual under the conditions for
-verbatim copying, provided that the entire resulting
-derive work is distributed under the terms of a permission
-notice identical to this one.
-
-Permission is granted to copy and distribute
-translations of this manual into another language,
-under the above conditions for modified versions,
-except that this permission notice may be stated in a
-translation approved by the Free Software Foundation.
+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.
@end titlepage
@contents
@menu
* Introduction:: What IDLWAVE is and what not
* IDLWAVE in a Nutshell:: One page quick-start guide
+* Getting Started:: Tutorial
* The IDLWAVE Major Mode:: The mode to edit IDL programs
* The IDLWAVE Shell:: The mode to run IDL as inferior program
* Installation:: How to Install or Upgrade
* Routine Definitions:: Where IDL Routines are defined.
* Routine Information Sources:: So how does IDLWAVE know about...
-* Library Scan:: Scanning the Libraries for Routine Info
+* Library Catalog:: Scanning the Libraries for Routine Info
* Load-Path Shadows:: Routines defined in several places
* Documentation Scan:: Scanning the IDL Manuals
Font-lock support on three levels.
@item
Display of calling sequence and keywords of more than 1000 IDL
-routines routines and any routines in your local IDL library.
+routines and any routines in your local IDL library.
@item
Name space conflict search.
@item
how to configure it, see the documentation string of that variable.
Some configuration examples are also given in the appendix.
-@node IDLWAVE in a Nutshell, The IDLWAVE Major Mode, Introduction, Top
+@node IDLWAVE in a Nutshell, Getting Started, Introduction, Top
@chapter IDLWAVE in a Nutshell
-@cindex Quick-Start
-@cindex Getting Started
@cindex Summary of important commands
@cindex IDLWAVE in a Nutshell
@cindex Nutshell, IDLWAVE in a
;; Pad some operators with spaces
(setq idlwave-do-actions t
idlwave-surround-by-blank t)
-;; Automatically expand END to ENDIF, ENDELSE, ...
-(setq idlwave-expand-generic-end t)
;; Syntax Highlighting
(add-hook 'idlwave-mode-hook 'turn-on-font-lock)
-;; Automatically start the shell when needed, in dedicated frame
-(setq idlwave-shell-automatic-start t
- idlwave-shell-use-dedicated-frame t)
+;; Automatically start the shell when needed
+(setq idlwave-shell-automatic-start t)
+;; Bind debugging commands with CONTROL and SHIFT modifiers
+(setq idlwave-shell-debug-modifiers '(control shift))
;; Where are the online help files?
(setq idlwave-help-directory "~/.idlwave")
@end lisp
-@node The IDLWAVE Major Mode, The IDLWAVE Shell, IDLWAVE in a Nutshell, Top
+@node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top
+@chapter Getting Started (Tutorial)
+@cindex Quick-Start
+@cindex Tutorial
+@cindex Getting Started
+
+@section Lession I: Development Cycle
+
+The purpose of this tutorial is to guide you through a very basic
+development cycle with IDLWAVE. We will type a simple program into a
+buffer and use the shell to compile, debug and run this program. On the
+way we will use the most important commands in IDLWAVE. Note
+however that there is much more funtionality available in IDLWAVE than
+we cover here, and it will pay off greatly if eventually you go further
+and read the whole manual.
+
+I assume that you have access to Emacs or XEmacs with the full IDLWAVE
+package including online help (@pxref{Installation}). I also assume
+that you are familiar with Emacs and can read the nomenclature of key
+presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL} and
+@kbd{M} for @key{META} (often the @key{ALT} key carries this
+functionality)).
+
+Open a new source file by typing
+
+@example
+@kbd{C-x C-f tutorial.pro @key{RET}}
+@end example
+
+A buffer for this file will pop up, and it should be in IDLWAVE mode.
+You can see this by looking at the mode line, just below the editing
+window. Also, the menu bar should contain entries @samp{IDLWAVE} and
+@samp{Debug}.
+
+Now cut-and-paste the following program, also available as
+@file{tutorial.pro} in the IDLWAVE distribution.
+
+@example
+function daynr,d,m,y
+ ;; compute a sequence number for a date
+ ;; works 1901-2099.
+ if y lt 100 then y = y+1900
+ if m le 2 then delta = 1 else delta = 0
+ m1 = m + delta*12 + 1
+ y1 = y * delta
+ return, d + floor(m1*30.6)+floor(y1*365.25)+5
+end
+
+function weekday,day,month,year
+ ;; compute weekday number for date
+ nr = daynr(day,month,year)
+ return, nr mod 7
+end
+
+pro plot_wday,day,month
+ ;; Plot the weekday of a date in the first 10 years of this century.
+ years = 2000,+indgen(10)
+ wdays = intarr(10)
+ for i=0,n_elements(wdays)-1 do begin
+ wdays[i] = weekday(day,month,years[i])
+ end
+ plot,years,wdays,YS=2,YT="Wday (0=sunday)"
+end
+@end example
+
+The indentation probably looks funny, since it's different from the
+settings you use, so use the @key{TAB} key in each line to automatically
+line it up (or more quickly @emph{select} the entire buffer with
+@kbd{C-x h} followed by @kbd{M-C-\}). Notice how different syntactical
+elements are highlighted in different colors, if you have set up support
+for font-lock.
+
+Let's check out two particular editing features of IDLWAVE. Place the
+cursor after the @code{end} statement of the @code{for} loop and press
+@key{SPC}. IDLWAVE blinks back to the beginning of the block and
+changes the generic @code{end} to the specific @code{endfor}
+automatically. Now place the cursor in any line you would like to split
+into two and press @kbd{M-@key{RET}}. The line is split at the cursor
+position, with the continuation @samp{$} and indentation all taken care
+of. Use @kbd{C-/} to undo the last change.
+
+The procedure @code{plot_wday} is supposed to plot the weekday of a given
+date for the first 10 years of the 21st century. I have put in a few
+bugs which we are going to fix now.
+
+First, let's launch the IDLWAVE shell. You do this with the command
+@kbd{C-c C-s}. The Emacs window will split and display IDL running in a
+shell interaction buffer. Type a few commands like @code{print,!PI} to
+convince yourself that you can work there like in an xterminal, or the
+IDLDE. Use the arrow keys to cycle through your command history. Are
+we having fun now?
+
+Now go back to the source window and type @kbd{C-c C-d C-c} to compile
+the program. If you watch the shell buffer, you see that IDLWAVE types
+@samp{.run tutorial.pro} for you. But the compilation fails because
+there is a comma in the line @samp{years=...}. The line with the error
+is highlighted and the cursor positioned at the error, so remove the
+comma (you should only need to hit Delete!). Compile again, using the
+same keystrokes as before. Notice that the file is saved for you. This
+time everything should work fine, and you should see the three routines
+compile.
+
+Now we want to use the command to plot the weekdays for January 1st. We
+could type the full command ourselves, but why do that? Go back to the
+shell window, type @samp{plot_} and hit @key{TAB}. After a bit of a
+delay (while IDLWAVE initializes its routine info database), the window
+will split to show all procedures it knows starting with that string,
+and @w{@code{plot_wday}} should be one of them. Saving the buffer was
+enough to tell IDLWAVE about this new routine. Click with the middle
+mouse button on @code{plot_wday} and it will be copied to the shell
+buffer, or if you prefer, add @samp{w} to @samp{plot_} to make it
+unambiguous, hit @key{TAB}, and the full routine name will be completed.
+Now provide the two arguments:
+
+@example
+plot_wday,1,1
+@end example
+
+
+and press @key{RET}. This fails with an error message telling you the
+@code{YT} keyword to plot is ambiguous. What are the allowed keywords
+again? Go back to the source window and put the cursor into the `plot'
+line, and press @kbd{C-c ?}. This pops up the routine info window for
+the plot routine, which contains a list of keywords, and the argument
+list. Oh, we wanted @code{YTITLE}. Fix that up. Recompile with
+@kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press
+the @key{UP} arrow to recall the previous command and execute again.
+
+This time we get a plot, but it is pretty ugly -- the points are all
+connected with a line. Hmm, isn't there a way for @code{plot} to use
+symbols instead? What was that keyword? Position the cursor on the
+plot line after a comma (where you'd normally type a keyword), and hit
+@kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, there
+it is, @code{PSYM}. Middle click to insert it. An @samp{=} sign is
+included for you too. Now what were the values of @code{PSYM} supposed
+to be? With the cursor on or after the keyword, press @kbd{M-?} for
+online help (alternatively, you could have right clicked on the colored
+keyword itself in the completion list). The online help window will pop
+up showing the documentation for the @code{PYSM} keyword. Ok, let's use
+diamonds=4. Fix this, recompile (you know the command by now: @kbd{C-c
+C-d C-c}, go back to the shell (if it's vanished, you know the command
+to recall it by now: @kbd{C-c C-s}) and execute again. Now things look
+pretty good.
+
+Lets try a different day - how about April fool's day?
+
+@example
+plot_wday,1,4
+@end example
+
+ Oops, this looks very wrong. All April fool's days cannot be
+Fridays! We've got a bug in the program, perhaps in the @code{daynr}
+function. Lets put a breakpoint on the last line there. Position the
+cursor on the @samp{return, d+...} line and press @kbd{C-c C-d C-b}.
+IDL sets a breakpoint (as you see in the shell window), and the line is
+highlighted in some way. Back to the shell buffer, re-execute the
+previous command. IDL stops at the line with the breakpoint. Now hold
+down the SHIFT key and click with the middle mouse button on a few
+variables there: @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe
+@code{d} isn't the correct type. CONTROL-SHIFT middle-click on it for
+help. Well, it's an integer, so that's not the problem. Aha, @samp{y1}
+is zero, but it should be the year, depending on delta. Shift click
+@samp{delta} to see that it's 0. Below, we see the offending line:
+@samp{y1=y*delta...} the multiplication should have been a minus sign!
+So fix the line to
+
+@example
+y1 = y - delta
+@end example
+
+Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the
+command. Everything should now work fine. How about those leap years?
+Change the code to plot 100 years and see that every 28 years, the
+sequence of weekdays repeats.
+
+@section Lession II: Customization
+
+Emacs is probably the most customizable piece of software available, and
+it would be a shame if you did not make use of this and adapt IDLWAVE to
+your own preferences. Customizing Emacs or IDLWAVE means that you have
+to set Lisp variables in the @file{.emacs} file in your home directory.
+This looks scary to many people because of all the parenthesis.
+However, you can just cut and paste the examples given here and work
+from there.
+
+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 of @samp{nil} means off. Copy the following line into your
+@file{.emacs} file, exit and restart Emacs.
+
+@lisp
+(setq idlwave-reserved-word-upcase t)
+@end lisp
+
+When this option is turned on, each reserved word you type into an IDL
+source buffer will be converted to upper case when you press @key{SPC}
+or @key{RET} right after the word. Try it out! @samp{if} changes to
+@samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this
+behavior, remove the option again from your @file{.emacs} file.
+
+Now I bet you have your own indentation preferences for IDL code. For
+example, I like to indent the main block of an IDL program a bit,
+different from the conventions used by RSI. Also, I'd like to use only
+3 spaces as indentation between @code{BEGIN} and @code{END}. Try the
+following lines in @file{.emacs}
+
+@lisp
+(setq idlwave-main-block-indent 2)
+(setq idlwave-block-indent 3)
+(setq idlwave-end-offset -3)
+@end lisp
+
+Restart Emacs, take the program we developed in the first part of this
+tutorial and re-indent it with @kbd{C-c h} and @kbd{M-C-\}. You
+probably want to keep these lines in @file{.emacs}, with values adjusted
+to your likings. If you want to get more information about any of these
+variables, type, e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}.
+To find which variables can be customized, look for items marked
+@samp{User Option:} in the manual.
+
+If you cannot wrap your head around this Lisp stuff, there is another,
+more user-friendly way to customize all the IDLWAVE variables. You can
+access it through the IDLWAVE menu in one of the @file{.pro} buffers,
+option @code{Customize->Browse IDLWAVE Group}. Here you'll be presented
+with all the various variables grouped into categories. You can
+navigate the hierarchy (e.g. Idlwave Code Formatting->Idlwave Main Block
+Indent), read about the variables, change them, and `Save for Future
+Sessions'. Few of these variables need customization, but you can
+exercise considerable control over IDLWAVE's functionality with them.
+
+Many people I talk to find the key bindings used for the debugging
+commands too long and complicated. Do I always have to type @kbd{C-c
+C-d C-c} to get a single simple command? Due to Emacs rules and
+conventions I cannot make better bindings by default, but you can.
+First, there is a way to assign all debugging commands in a single sweep
+to other combinations. The only problem is that we have to use
+something which Emacs does not need for other important commands. A
+good option is to execute debugging commands by holding down
+@key{CONTROL} and @key{SHIFT} while pressing a single character:
+@kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for compiling the
+current source file, @kbd{C-S-a} for deleting all breakpoints. You can
+have this with
+
+@lisp
+(setq idlwave-shell-debug-modifiers '(shift control))
+@end lisp
+
+If you have a special keyboard with for example a @key{HYPER} key, you
+could use
+
+@lisp
+(setq idlwave-shell-debug-modifiers '(hyper))
+@end lisp
+
+instead to get compilation on @kbd{H-c}.
+
+You can also assign specific commands to function keys. This you must
+do in the @emph{mode-hook}, a special function which is run when a new
+buffer gets set up. Keybindings can only be done when the buffer
+exists. The possibilities for key customization are endless. Here we
+set function keys f5-f8 to common debugging commands.
+
+@lisp
+;; First for the source buffer
+(add-hook 'idlwave-mode-hook
+ (lambda ()
+ (local-set-key [f5] 'idlwave-shell-break-here)
+ (local-set-key [f6] 'idlwave-shell-clear-current-bp)
+ (local-set-key [f7] 'idlwave-shell-cont)
+ (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
+;; Then for the shell buffer
+(add-hook 'idlwave-shell-mode-hook
+ (lambda ()
+ (local-set-key [f5] 'idlwave-shell-break-here)
+ (local-set-key [f6] 'idlwave-shell-clear-current-bp)
+ (local-set-key [f7] 'idlwave-shell-cont)
+ (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
+@end lisp
+
+@section Lession III: Library Catalog
+
+We have already used the routine info display in the first part of this
+tutorial. This was the key @kbd{C-c ?} which displays information about
+the IDL routine near the cursor position. Wouldn't it be nice
+to have the same available for your own library routines and for the
+huge amount of code in major extension libraries like JHUPL or the
+IDL-Astro library? To do this, you must give IDLWAVE a chance to study
+these routines first. We call this @emph{Building the library catalog}.
+
+From the IDLWAVE entry in the menu bar, select @code{Routine Info/Select
+Catalog Directories}. If necessary, start the shell first with @kbd{C-c
+C-s} (@pxref{Starting the Shell}). IDLWAVE will find out about the IDL
+@code{!PATH} variable and offer a list of directories on the path.
+Simply select them all (or whichever you want) and click on the
+@samp{Scan&Save} button. Then go for a cup of coffee while IDLWAVE
+collects information for each and every IDL routine on your search path.
+All this information is written to the file @file{.idlcat} in your home
+directory and will from now one be automatically loaded whenever you use
+IDLWAVE. Try to use routine info (@kbd{C-c ?}) or completion
+(@kbd{M-<TAB>}) while on any routine or partial routine name you know to
+be located in the library. E.g., if you have scanned the IDL-Astro
+library:
+
+@example
+ a=readf@key{M-<TAB>}
+@end example
+
+
+expands to `readfits('. Then try
+
+@example
+ a=readfits(@key{C-c ?}
+@end example
+
+and you get:
+
+@example
+Usage: Result = READFITS(filename, header, heap)
+...
+@end example
+
+I hope you made it until here. Now you are set to work with IDLWAVE.
+On the way you will want to change other things, and to learn more about
+the possibilities not discussed in this short tutorial. Read the
+manual, look at the documentation strings of interesting variables (with
+@kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining
+questions on @code{comp.lang.idl-pvwave}.
+
+@node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top
@chapter The IDLWAVE Major Mode
@cindex IDLWAVE major mode
@cindex Major mode, @code{idlwave-mode}
which may or may not be what you want (@pxref{Load-Path Shadows}). The
information about the calling sequence and the keywords is derived from
the first source listed. Library routines can only be supported if you
-have scanned the local IDL library (@pxref{Library Scan}). The source
+have scanned the local IDL library (@pxref{Library Catalog}). The source
entry consists of a @emph{source category}, a set of @emph{flags} and
the path to the @emph{source file}. The following categories
exist:
@item @i{System}
@tab A system routine, but we do not know if it is @i{Builtin} or
@i{SystemLib}. When the system library has bee scanned
-(@pxref{Library Scan}), this category will automatically split into the
+(@pxref{Library Catalog}), this category will automatically split into the
next two.
@item @i{Builtin}
@tab A builtin routine with no source code available.
@cindex Multiply defined routines
@cindex Routine definitions, multiple
The flags @code{[CSB]} indicate if the file is known to IDLWAVE from the
-library catalog (@w{@code{[C--]}}, @pxref{Library Scan}), from the Shell
+library catalog (@w{@code{[C--]}}, @pxref{Library Catalog}), from the Shell
(@w{@code{[-S-]}}) or from an Emacs buffer (@w{@code{[--B]}}).
Combinations are possible. If a file contains multiple definitions of
the same routine, the file name will be prefixed with @samp{(Nx)} where
@kbd{C-c ?} was called. If you use the @emph{right} mouse button, the
source will not be visited by a buffer, but displayed in the online help
window.
+@item @i{Classes}
+@tab The @i{Classes} line is only included in the routine info window if
+the current class inherits from other classes. You can click with the
+@emph{middle} mouse button to display routine info about the current
+method in other classes on the inheritance chain.
@end multitable
@defopt idlwave-resize-routine-help-window (@code{t})
@kindex M-?
In any IDL program, press @kbd{M-?} (@code{idlwave-context-help}) or
-click with @kbd{S-mouse-3} to access context sensitive online help. The
+click with @kbd{S-Mouse-3} to access context sensitive online help. The
following locations are recognized as context:
@cindex Context, for online help
@itemize @bullet
@item
Online help for routines and keywords can be accessed through the
-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
corresponding help (@pxref{Routine Info}).
@item
When using completion and Emacs pops up a window with possible
-completions, clicking with @kbd{mouse-3} on a completion item invokes
+completions, clicking with @kbd{Mouse-3} on a completion item invokes
help on that item (@pxref{Completion}).
@end itemize
@noindent
@tab Move back and forward through the help topic history.
@item @kbd{c}
@tab Clear the history.
-@item @kbd{mouse-2}
+@item @kbd{Mouse-2}
@tab Follow a link. Active links are displayed in a different font.
Items under @i{See Also} are active, and classes have links to their
methods and back.
The face for links to IDLWAVE online help.
@end defopt
+@defopt idlwave-help-activate-links-agressively (@code{t})
+Non-@code{nil} means, make all possible links in help window active.
+@end defopt
+
@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode
@section Completion
@cindex Completion
x = obj_new('MyCl',a* @r{Keyword to @code{Init} method in class @code{MyCl}}
pro A* @r{Class name}
pro * @r{Fill in @code{Class::} of first method in this file}
+!v* @r{System variable}
+!version.t* @r{Structure tag of system variable}
+self.g* @r{Class structure tag in methods}
@end example
@cindex Scrolling the @file{*Completions*} window
If the list of completions is too long to fit in the
@file{*Completions*} window, the window can be scrolled by pressing
@kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each
-possible completion is available by clicking with @kbd{mouse-3} on the
+possible completion is available by clicking with @kbd{Mouse-3} on the
item. Items for which system online help (from the IDL manual) is
available will be displayed in a different font. For other items, the
corresponding source code or DocLib header is available as help text.
will be shown next to the item (see option
@code{idlwave-completion-show-classes}). As a special case, the class
of an object called @samp{self} object is always the class of the
-current routine.
+current routine. All classes it inherits from are considered as well
+where appropriate.
@cindex Forcing class query.
@cindex Class query, forcing
default - the variable @code{idlwave-store-inquired-class} can be used
to turn it on.
+@defopt idlwave-support-inheritance (@code{t})
+Non-@code{nil} means, treat inheritance with completion, online help etc.
+@end defopt
+
@defopt idlwave-completion-show-classes (@code{1})
Non-@code{nil} means, show classes in @file{*Completions*} buffer when
completing object methods and keywords.
@code{idlwave-resolve} is one way to get a library module within reach
of IDLWAVE's routine info collecting functions. A better way is to
-scan (parts of) the library (@pxref{Library Scan}). Routine info on
+scan (parts of) the library (@pxref{Library Catalog}). Routine info on
library modules will then be available without the need to compile the
modules first, and even without a running shell.
variables @code{idlwave-abbrev-change-case} and
@code{idlwave-reserved-word-upcase}.
-@defopt idlwave-abbrev-start-char
+@defopt idlwave-abbrev-start-char (@code{"\"})
A single character string used to start abbreviations in abbrev
mode.
@end defopt
@code{idlwave-show-begin}.
@end defopt
-@defopt idlwave-expand-generic-end (@code{nil})
+@defopt idlwave-expand-generic-end (@code{t})
Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc.
@end defopt
The IDLWAVE shell works in the same fashion as other shell modes in
Emacs. It provides command history, command line editing and job
-control. Here is a list of commonly used commands.
+control. The @key{UP} and @key{DOWN} arrows cycle through the input
+history just like in an X terminal@footnote{This is different from
+normal Emacs/Comint behavior, but more like an xterm. If you prefer the
+default comint functionality, check the variable
+@code{idlwave-shell-arrows-do-history}.}. Here is a list of
+commonly used commands.
@multitable @columnfractions .12 .88
+@item @key{UP}
+@tab Cycle backwards in input history
+@item @key{DOWN}
+@tab Cycle forwards in input history
@item @kbd{M-p}
-@tab Cycle backwards in input history matching input
+@tab Cycle backwards in input history @emph{matching input}
@item @kbd{M-n}
-@tab Cycle forwards
+@tab Cycle forwards in input history @emph{matching input}
@item @kbd{M-r}
@tab Previous input matching a regexp
@item @kbd{M-s}
@tab Compile a library routine (@code{idlwave-resolve})
@end multitable
+@defopt idlwave-shell-arrows-do-history (@code{t})
+Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command
+history like xterm.
+@end defopt
+
@defopt idlwave-shell-file-name-chars
The characters allowed in file names, as a string. Used for file name
completion.
@end defopt
-@page
+@defopt idlwave-shell-graphics-window-size
+Size of IDL graphics windows popped up by special IDLWAVE command.
+@end defopt
+
@cindex Input mode
@cindex Character input mode (Shell)
@cindex Line input mode (Shell)
The debugging keybindings are by default on the prefix key @kbd{C-c
C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d
-C-b}. If you find this too much work and your ALT key is still
-available, turn on the variable
-@code{idlwave-shell-activate-alt-keybindings} in order to get breakpoint
-setting on @kbd{A-b}. In the remainder of this chapter we will assume
-that the @kbd{C-c C-d} bindings are active.
+C-b}, compiling a source file with @kbd{C-c C-d C-c}. If you find this
+too much work you can choose a combination of modifier keys which is not
+used by other commands. For example, if you write in @file{.emacs}
+
+@lisp
+(setq idlwave-shell-debug-modifiers '(control shift))
+@end lisp
+
+a breakpoint can be set by pressing @kbd{b} while holding down
+@kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a
+source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}
+etc. In the remainder of this chapter we will assume that the @kbd{C-c
+C-d} bindings are active, but each of these bindings will have an
+equivalent single-keypress shortcut with the modifiers given in the
+@code{idlwave-shell-debug-modifiers} variable.
@defopt idlwave-shell-prefix-key (@kbd{C-c C-d})
The prefix key for the debugging map
key, like @kbd{C-c C-d C-b}.
@end defopt
-@defopt idlwave-shell-activate-alt-keybindings (@code{nil})
-Non-@code{nil} means, debug commands will be bound to alternate
-keys, like @kbd{A-b}.
+@defopt idlwave-shell-debug-modifiers (@code{nil})
+List of modifier keys to use for binding debugging commands in the shell
+and in source buffers.
@end defopt
@defopt idlwave-shell-use-toolbar (@code{t})
point.
It is very convenient to click with the mouse on expressions to retrieve
-their value. Expression printing is also bound to @kbd{S-mouse-2} and
-expression help to @kbd{C-S-mouse-2}. I.e. you need to hold down
+their value. Expression printing is also bound to @kbd{S-Mouse-2} and
+expression help to @kbd{C-S-Mouse-2}. I.e. you need to hold down
@key{SHIFT} and @key{CONTROL} while clicking with the mouse.
@cindex Calling stack, motion
@end lisp
@item
The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character.
-Like in in many other Emacs modes, @kbd{M-@key{TAB}} now does
+Like in many other Emacs modes, @kbd{M-@key{TAB}} now does
completion. Inserting a TAB has therefore been moved to
@kbd{C-@key{TAB}}. On a character based terminal you can also use
@kbd{C-c @key{SPC}}.
@itemize @minus
@item
-@uref{mailto:chase@@att.com, @b{Chris Chase}} wrote
-@file{idl.el} and @file{idl-shell.el} and maintained them for several
-years.
+@uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author.
+Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them
+for several years.
@item
-@uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} has been in
-charge of the package since version 3.0. He renamed the package to
-IDLWAVE, rewrote and added large parts and is the current maintainer.
+@uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}}, current author
+and maintainer. I have been in charge of the package since version
+3.0. I am also responsible for the manual.
@item
@uref{mailto:jdsmith@@astrosun.tn.cornell.edu, @b{J.D. Smith}} has
@item
Simon Marshall <Simon.Marshall@@esrin.esa.it>
@item
+Craig Markwardt <craigm@@cow.physics.wisc.edu>
+@item
Laurent Mugnier <mugnier@@onera.fr>
@item
Lubos Pochman <lubos@@rsinc.com>
@menu
* Routine Definitions:: Where IDL Routines are defined.
* Routine Information Sources:: So how does IDLWAVE know about...
-* Library Scan:: Scanning the Libraries for Routine Info
+* Library Catalog:: Scanning the Libraries for Routine Info
* Load-Path Shadows:: Routines defined in several places
* Documentation Scan:: Scanning the IDL Manuals
@end menu
routines.
@end enumerate
-@node Routine Information Sources, Library Scan, Routine Definitions, Sources of Routine Info
+@node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info
@section Routine Information Sources
@cindex Routine info sources
@cindex Builtin list of routines
@item
IDLWAVE can scan all or selected library files and store the result in a
file which will be automatically loaded just like
-@file{idlw-rinfo.el}. @xref{Library Scan}, for information how to
+@file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to
scan library files.
@end enumerate
Controls under what circumstances routine info is updated automatically.
@end defopt
-@node Library Scan, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
-@section Library Scan
+@node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
+@section Library Catalog
@cindex Library scan
+@cindex Library catalog
@cindex IDL library routine info
@cindex Windows
@cindex MacOS
Alist of regular expressions matching special library directories.
@end defopt
-@node Load-Path Shadows, Documentation Scan, Library Scan, Sources of Routine Info
+@node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info
@section Load-Path Shadows
@cindex Load-path shadows
@cindex Shadows, load-path
different files. Since one definition will hide (shadow) the others
depending on which file is compiled first, such multiple definitions are
called "load-path shadows". IDLWAVE has several routines to scan for
-load path shadows. The output is placed into s special buffer
+load path shadows. The output is placed into the special buffer
@file{*Shadows*}. The format of the output is identical to the source
-section of the routine info buffer (@pxref{Routine Info}). Before
-calling these routines, you should make sure that routine info is
-up-to-date by pressing @kbd{C-c C-i}. Here are the different routines:
+section of the routine info buffer (@pxref{Routine Info}). The
+different definitions of a routine are listed in the sequence of
+@emph{likelyhood of use}. So the first entry will be most likely the
+one you'll get if an unsuspecting command uses that routine. Before
+listing shadows, you should make sure that routine info is up-to-date by
+pressing @kbd{C-c C-i}. Here are the different routines:
@table @asis
@item @kbd{M-x idlwave-list-buffer-load-path-shadows}
your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and
then check for shadowing.
@item @kbd{M-x idlwave-list-all-load-path-shadows}
-This command finally checks all routines accessible to IDLWAVE for
-shadowing conflicts.
+This command checks all routines accessible to IDLWAVE for conflicts.
@end table
For these commands to work properly you should have scanned the entire
have in my @file{.emacs}:
@lisp
-(setq idlwave-shell-activate-alt-keybindings t
- idlwave-expand-generic-end t
+(setq idlwave-shell-debug-modifiers '(control shift)
idlwave-store-inquired-class t
idlwave-shell-automatic-start t
idlwave-main-block-indent 2
(font-lock-mode 1) ; Turn on font-lock mode
(idlwave-auto-fill-mode 0) ; Turn off auto filling
;;
- ;; Pad with with 1 space (if -n is used then make the
+ ;; Pad with 1 space (if -n is used then make the
;; padding a minimum of n spaces.) The defaults use -1
;; instead of 1.
(idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1))