[elpa] externals/idlwave ebb0da8408 033/360: v4.13

[ELPA Syncer]

branch: externals/idlwave
commit ebb0da840854d6f6b8f055acf6015105b38e4125
Author: jdsmith <jdsmith>
Commit: jdsmith <jdsmith>

    v4.13
---
 idlwave.texi | 439 +++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 304 insertions(+), 135 deletions(-)

diff --git a/idlwave.texi b/idlwave.texi
index ec9f5376ac..dc873f28b6 100644
--- a/idlwave.texi
+++ b/idlwave.texi
@@ -9,16 +9,16 @@
 @synindex ky cp
 @syncodeindex vr cp
 @syncodeindex fn cp
-@set VERSION 4.12
-@set EDITION 4.12
+@set VERSION 4.13
+@set EDITION 4.13
 @set IDLVERSION 5.5
 @set NSYSROUTINES 1322
 @set NSYSKEYWORDS 5952
-@set DATE January 2002
+@set DATE May 2002
 @set AUTHOR J.D. Smith & Carsten Dominik
 @set AUTHOR-EMAIL dominik@@astro.uva.nl
 @set MAINTAINER J.D. Smith
-@set MAINTAINER-EMAIL jdsmith@@alum.mit.edu
+@set MAINTAINER-EMAIL jdsmith@@as.arizona.edu
 @set IDLWAVE-HOMEPAGE http://idlwave.org/
 @c %**end of header
 @finalout
@@ -144,6 +144,7 @@ The IDLWAVE Major Mode
 Code Formatting
 
 * Code Indentation::            Reflecting the logical structure
+* Continued Statement Indentation::  
 * Comment Indentation::         Special indentation for comment lines
 * Continuation Lines::          Splitting statements over lines
 * Syntax Highlighting::         Font-lock support
@@ -167,13 +168,14 @@ The IDLWAVE Shell
 * Starting the Shell::          How to launch IDL as a subprocess
 * Using the Shell::             Interactively working with the Shell
 * Debugging IDL Programs::      Compilation/Debugging
+* Examining Variables::         
+* Custom Expression Examination::  
 
 Debugging IDL Programs
 
 * Compiling Programs::          Compiling buffers under the shell
 * Breakpoints and Stepping::    Deciding where to stop and look
 * Walking the Calling Stack::   From where was this routine called?
-* Examining Variables::         What is the value now?
 
 Installation
 
@@ -205,11 +207,14 @@ Sources of Routine Info
 
 IDLWAVE is a package which supports editing source files for the
 Interactive Data Language (IDL@footnote{IDL is a registered trademark of
-Research Systems, Inc.}), and for running IDL as an inferior
-shell@footnote{Note that this package has nothing to do with the
-Interface Definition Language, part of the Common Object Request Broker
-Architecture (CORBA)}.  It can also be used for editing source files for
-the related WAVE/CL language, but with only limited support.
+Research Systems, Inc., a Kodak Company}), and for running IDL as an
+inferior shell@footnote{Note that this package has nothing to do with
+the Interface Definition Language, part of the Common Object Request
+Broker Architecture (CORBA)}.  It can also be used for editing source
+files for the related WAVE/CL language, but with only limited
+support. Note that this package has nothing to do with the Interface
+Definition Language, part of the Common Object Request Broker
+Architecture (CORBA).
 
 IDLWAVE consists of two main parts: a major mode for editing IDL source
 files files (@code{idlwave-mode}) and a mode for running the IDL program
@@ -307,6 +312,8 @@ appendix.
 @tab Indent the current line relative to context.
 @item @kbd{C-M-\}
 @tab Re-indent all lines in the current region.
+@item @kbd{C-u @key{TAB}}
+@tab Re-indent all lines in the current statement.
 @item @kbd{M-@key{RET}}
 @tab Start a continuation line, or split the current line at point.
 @item @kbd{M-q}
@@ -520,7 +527,7 @@ 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?
+Let's try a different day --- how about April fool's day?
 
 @example
 plot_wday,1,4
@@ -528,7 +535,7 @@ plot_wday,1,4
 
 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
+Let's 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.
@@ -560,9 +567,9 @@ setting Lisp variables in the @file{.emacs} file in your 
home directory
 --- but do not be dismayed; for the most part, you can just copy and work
 from the examples given here.
 
-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
+Let's 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
@@ -631,8 +638,8 @@ breakpoints.  You can enable this with:
 @end lisp
 
 @noindent to get compilation on @kbd{H-c}.  Often, a modifier key like
-@key{HYPER} can be bound to an otherwise unused key -- consult your
-system documentation.
+@key{HYPER} or @key{SUPER} is bound or can be bound to an otherwise
+unused key -- consult your system documentation.
 
 You can also assign specific commands to keys.  This you must do in the
 @emph{mode-hook}, a special function which is run when a new buffer gets
@@ -739,6 +746,7 @@ them.
 
 @menu
 * Code Indentation::            Reflecting the logical structure
+* Continued Statement Indentation::  
 * Comment Indentation::         Special indentation for comment lines
 * Continuation Lines::          Splitting statements over lines
 * Syntax Highlighting::         Font-lock support
@@ -748,39 +756,15 @@ them.
 The IDL language, with it's early roots in FORTRAN, modern
 implementation in C, and liberal borrowing of features of many vector
 languages along its 25+ year history, has inherited an unusual mix of
-syntax elements.  Left to his own devices, a new IDL programmer will
-often create code which is very difficult to read and impossible to
-adapt.  Luckily, IDLWAVE understands IDL code very well, and takes care
-of almost all formatting issues for you.  After configuring it to match
-your coding standard, you can rely on it almost entirely to keep your
-code organized.
-
-@node Code Indentation, Comment Indentation, Code Formatting, Code Formatting
-@subsection Code Indentation
-@cindex Code indentation
-@cindex Indentation
-
-Like all Emacs programming modes, IDLWAVE performs code indentation.
-The @key{TAB} key indents the current line relative to context.
-@key{LFD} insert a newline and indents the new line.  The indentation is
-governed by a number of variables.  IDLWAVE indents blocks (between
-@code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and
-continuation lines.
-
-Continuation lines normally receive a fixed indentation, but in
-pro/function definition statements and in procedure calls, continuation
-lines are aligned with the first character after the routine name.  In
-lines with unmatched opening parenthesis, the indentation is given by
-the opening parenthesis.  Here is an example.
-
-@example
-function foo, a, b,  $
-              c, d
-  bar =  sin( a + b + $
-              c + d)
-end
-@end example
-@noindent
+syntax elements.  Left to his or her own devices, a novice IDL
+programmer will often conjure code which is very difficult to read and
+impossible to adapt.  Much can be gleaned from studying available IDL
+code libraries for coding style pointers, but, due to the variety of IDL
+syntax elements, replicating this style can be challenging at best.
+Luckily, IDLWAVE understands the structure IDL code very well, and takes
+care of almost all formatting issues for you.  After configuring it to
+match your coding standards, you can rely on it to help keep your code
+neat and organized.
 
 @cindex Foreign code, adapting
 @cindex Indentation, of foreign code
@@ -792,6 +776,18 @@ commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} 
(the
 current subprogram). @xref{Actions}, for information how to impose
 additional formatting conventions on foreign code.
 
+@node Code Indentation, Continued Statement Indentation, Code Formatting, Code 
Formatting
+@subsection Code Indentation
+@cindex Code indentation
+@cindex Indentation
+
+Like all Emacs programming modes, IDLWAVE performs code indentation.
+The @key{TAB} key indents the current line relative to context.
+@key{LFD} insert a newline and indents the new line.  The indentation is
+governed by a number of variables.  IDLWAVE indents blocks (between
+@code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and
+continuation lines.
+
 @defopt idlwave-main-block-indent (@code{0}) 
 Extra indentation for the main block of code.  That is the block between
 the FUNCTION/PRO statement and the END statement for that program
@@ -809,15 +805,76 @@ Extra indentation applied to block END lines.  A value 
equal to negative
 BEGIN lines.
 @end defopt
 
+@node Continued Statement Indentation, Comment Indentation, Code Indentation, 
Code Formatting
+@subsection Continued Statement Indentation
+@cindex Indentation, continued statement
+@cindex Continued statement indentation
+Continuation lines (following a line ending with @code{$}) can receive a
+fixed indentation offset from the main level, but in several situations
+IDLWAVE can use a special form of indentation which aligns continued
+statements more naturally.  Special indentation is calculated for
+continued routine definition statements and calls, enclosing parentheses
+(like function calls, structure/class definitions, explicit structures
+or lists, etc.), and continued assignments.  An attempt is made to line
+up with the first non-whitespace character after the relevant opening
+punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}).  For
+lines without any non-comment characters on the line with the opening
+punctuation, the continued line(s) are aligned just past the
+punctuation.  An example:
+
+@example
+function foo, a, b,  $
+              c, d
+  bar =  sin( a + b + $
+              c + d)
+end
+@end example
+@noindent
+
+The only drawback to this special continued statement indentation is
+that it consumes more space, e.g., for long function names or left hand
+sides of an assignment:
+
+@example
+function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $
+                                                            c, d
+@end example
+
+You can instruct IDLWAVE when to use this special continuation
+indentation by setting the variable
+@code{idlwave-max-extra-continuation-indent}, which specifies the
+maximum additional indentation beyond the basic indent to be tolerated,
+otherwise defaulting to fixed-offset from the enclosing indent (the size
+of which offset is set in @code{idlwave-continuation-indent}).  Also,
+since the indentation level is somewhat dynamic in continued statements
+with special continuation indentation, especially if
+@code{idlwave-max-extra-continuation-indent} is small, the key @kbd{C-u
+@key{TAB}} will re-indent all lines in the current statement.  Note that
+@code{idlwave-indent-to-open-paren}, if non-nil, overrides the
+@code{idlwave-max-extra-continuation-indent} limit, for parentheses
+only, forcing them always to line up.
+
+
 @defopt idlwave-continuation-indent (@code{2})
 Extra indentation applied to normal continuation lines.
 @end defopt
 
+@defopt idlwave-max-extra-continuation-indent (@code{20})
+The maximum additional indentation (over the basic continuation-indent)
+that will be permitted for special continues.  To effectively disable
+special continuation indentation, set to @code{0}.  To enable it
+constantly, set to a large number (like @code{100}).  Note that the
+indentation in a long continued statement never decreases from line to
+line, outside of nested parentheses statements.
+@end defopt
+
 @defopt idlwave-indent-to-open-paren (@code{t})
-Non-@code{nil} means indent continuation lines to innermost open parenthesis.
+Non-@code{nil} means indent continuation lines to innermost open
+parenthesis, regardless of whether the
+@code{idlwave-max-extra-continuation-indent} limit is satisfied.
 @end defopt
 
-@node Comment Indentation, Continuation Lines, Code Indentation, Code 
Formatting
+@node Comment Indentation, Continuation Lines, Continued Statement 
Indentation, Code Formatting
 @subsection Comment Indentation
 @cindex Comment indentation
 @cindex Hanging paragraphs
@@ -1304,7 +1361,7 @@ The directory where idlw-help.txt and idlw-help.el are 
stored.
 @end defopt
 
 @defopt idlwave-help-use-dedicated-frame (@code{t})
-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.
 @end defopt
 
 @defopt idlwave-help-frame-parameters
@@ -1320,11 +1377,11 @@ Function to call for help if the normal help fails.
 @end defopt
 
 @defopt idlwave-help-fontify-source-code (@code{nil})
-Non-nil means fontify source code displayed as help.
+Non-@code{nil} means fontify source code displayed as help.
 @end defopt
 
 @defopt idlwave-help-source-try-header (@code{t})
-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
 file.
 @end defopt
 
@@ -1418,7 +1475,8 @@ completion.
 @end defopt
 
 @defopt idlwave-highlight-help-links-in-completion (@code{t})
-Non-nil means highlight completions for which system help is available.
+Non-@code{nil} means highlight completions for which system help is
+available.
 @end defopt
 
 @menu
@@ -1699,6 +1757,8 @@ Template abbreviations:
 String abbreviations:
 
 @multitable @columnfractions .15 .85
+@item @code{\ap}
+@tab @code{arg_present()}
 @item @code{\b}
 @tab @code{begin}
 @item @code{\cb}
@@ -1741,6 +1801,10 @@ String abbreviations:
 @tab @code{goto,}
 @item @code{\h}
 @tab @code{help,}
+@item @code{\ik}
+@tab @code{if keyword_set() then}
+@item @code{\iap}
+@tab @code{if arg_present() then}
 @item @code{\ine}
 @tab @code{if n_elements() eq 0 then}
 @item @code{\inn}
@@ -1801,21 +1865,24 @@ String abbreviations:
 @tab @code{writeu,}
 @end multitable
 
-@noindent You can easily add your own abbreviations with
-@code{define-abbrev} in your mode hook:
+@noindent You can easily add your own abbreviations or override existing
+abbrevs with @code{define-abbrev} in your mode hook using the
+convenience function @code{idlwave-define-abbrev}:
 
 @lisp
 (add-hook 'idlwave-mode-hook
           (lambda ()
-            (define-abbrev idlwave-mode-abbrev-table  
-              (concat idlwave-abbrev-start-char "ik") "if keyword_set() then"
-              (idlwave-keyword-abbrev 6))
+            (idlwave-define-abbrev "wb" "widget_base()"
+                                  (idlwave-keyword-abbrev 1))
+           (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN"
+                                  (idlwave-keyword-abbrev 11))))
 @end lisp
 
-Notice how the start character is prepended to the abbreviation (here
-@emph{ik}), and the argument to @code{idlwave-keyword-abbrev} (here
-@emph{6}) specifies how far back to move the point (in this example, to
-put it between the parentheses).
+Notice how the abbreviation (here @emph{wb}) and its expansion
+(@emph{widget_base()}) are given as argument, and the single argument to
+@code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to
+move the point upon expansion (in this example, to put it between the
+parentheses).
 
 The abbreviations are expanded in upper or lower case, depending upon
 the variables @code{idlwave-abbrev-change-case} and (for reserved word
@@ -1908,7 +1975,7 @@ Non-@code{nil} means expand generic END to 
ENDIF/ENDELSE/ENDWHILE etc.
 @end defopt
 
 @defopt idlwave-reindent-end (@code{t})
-Non-nil means re-indent line after END was typed.
+Non-@code{nil} means re-indent line after END was typed.
 @end defopt
 
 @node Padding Operators, Case Changes, Block Boundary Check, Actions
@@ -1937,7 +2004,7 @@ in @file{.emacs}
 @end lisp
 
 @defopt idlwave-surround-by-blank (@code{nil})
-Non-@code{nil} means enable @code{idlwave-surround}.  If non-nil,
+Non-@code{nil} means enable @code{idlwave-surround}.  If non-@code{nil},
 @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are
 surrounded with spaces by @code{idlwave-surround}.
 @end defopt
@@ -2132,6 +2199,8 @@ currently only works under Unix.
 * Starting the Shell::          How to launch IDL as a subprocess
 * Using the Shell::             Interactively working with the Shell
 * Debugging IDL Programs::      Compilation/Debugging
+* Examining Variables::         
+* Custom Expression Examination::  
 @end menu
 
 @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell
@@ -2344,7 +2413,8 @@ variables described below for a way to make IDL programs 
trigger
 automatic switches of the input mode.
 
 @defopt idlwave-shell-use-input-mode-magic (@code{nil})
-Non-nil means IDLWAVE should check for input mode spells in output.
+Non-@code{nil} means IDLWAVE should check for input mode spells in
+output.
 @end defopt
 
 @defopt idlwave-shell-input-mode-spells
@@ -2352,7 +2422,7 @@ The three regular expressions which match the magic 
spells for input
 modes.
 @end defopt
 
-@node Debugging IDL Programs,  , Using the Shell, The IDLWAVE Shell
+@node Debugging IDL Programs, Examining Variables, Using the Shell, The 
IDLWAVE Shell
 @section Debugging IDL Programs
 @cindex Debugging
 @cindex Keybindings for debugging
@@ -2369,19 +2439,20 @@ C-t} (@code{idlwave-shell-toggle-toolbar}).
 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}, 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}:
+too much work, you can add bindings for one or more 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
+@noindent 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
+equivalent single-keypress shortcut if modifiers are given in the
 @code{idlwave-shell-debug-modifiers} variable (see @pxref{Lesson II --
 Customization}).
 
@@ -2396,8 +2467,8 @@ key, like @kbd{C-c C-d C-b}.
 @end defopt
 
 @defopt idlwave-shell-debug-modifiers (@code{nil})
-List of modifier keys to use for binding debugging commands in the shell 
-and in source buffers.
+List of modifier keys to use for additional binding of debugging
+commands in the shell and source buffers.
 @end defopt
 
 @defopt idlwave-shell-use-toolbar (@code{t})
@@ -2410,7 +2481,6 @@ buffers.
 * Compiling Programs::          Compiling buffers under the shell
 * Breakpoints and Stepping::    Deciding where to stop and look
 * Walking the Calling Stack::   From where was this routine called?
-* Examining Variables::         What is the value now?
 @end menu
 
 @node Compiling Programs, Breakpoints and Stepping, Debugging IDL Programs, 
Debugging IDL Programs
@@ -2524,7 +2594,7 @@ The face for breakpoint lines in the source code if
 @code{idlwave-shell-mark-breakpoints} has the value @code{face}.
 @end defopt
 
-@node Walking the Calling Stack, Examining Variables, Breakpoints and 
Stepping, Debugging IDL Programs
+@node Walking the Calling Stack,  , Breakpoints and Stepping, Debugging IDL 
Programs
 @subsection Walking the Calling Stack
 @cindex Calling stack, walking
 
@@ -2543,8 +2613,8 @@ automatically return to the current level. 
@xref{Examining Variables},
 for information how to examine the value of variables and expressions on
 higher calling stack levels.
 
-@node Examining Variables,  , Walking the Calling Stack, Debugging IDL Programs
-@subsection Examining Variables
+@node Examining Variables, Custom Expression Examination, Debugging IDL 
Programs, The IDLWAVE Shell
+@section Examining Variables
 @cindex @code{PRINT} expressions
 @cindex @code{HELP}, on expressions
 @cindex Expressions, printing
@@ -2553,34 +2623,57 @@ higher calling stack levels.
 @cindex Mouse binding to print expressions
 
 @kindex C-c C-d C-p
-When execution is stopped in a buffer due to a breakpoint or error you
-can examine the values of variables.  The command @kbd{C-c C-d C-p}
-prints the expression at point, while @kbd{C-c C-d ?} invokes help on
+Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)},
+and similar statements to remind yourself of the
+type/size/structure/value/etc. of variables and expressions in your code
+or at the command line?  IDLWAVE has a suite of special commands to
+automate these types of variables or expression examinations.  They work
+by sending statements to the shell formatted to include the indicated
+expression.
+
+These examination commands can be used in the shell or buffer at any
+time (as long as the shell is running), and are very useful when
+execution is stopped in a buffer due to a triggered breakpoint or error,
+or while composing a long command in the IDLWAVE shell.  In the latter
+case, the command is sent to the shell and its output is visible, but
+point remains unmoved in the command being composed --- you can inspect
+the contituents of a command you're building without interrupting the
+process of building it!  You can even print arbitrary expressions from
+older input or output further up in the shell window --- any expression,
+variable, number, or function you see can be examined.
+
+The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to
+print the expression at point, and @kbd{C-c C-d ?}, to invoke help on
 this expression.  The expression at point is either an array expression
 or a function call, or the contents of a pair of parentheses.  The
-selected expression is highlighted in the source code for a short time.
-Calling the above commands with a prefix argument will prompt for an
-expression instead of using the one at point.  Two prefix arguments
-(@kbd{C-u C-u C-c C-d C-p}) will use the current region as expression.
-
-It is very convenient to click with the mouse on expressions to examine
-their values.  Use @kbd{S-mouse-2} to print an expression and
-@kbd{C-S-mouse-2} to invoke help help.  I.e. you need to hold down
-@key{SHIFT} and @key{CONTROL} while clicking with the middle mouse
-button.  If you simply click, the expression will be selected in the
-same way as described above.  But you can also drag the mouse in order
-to highlight a specific expression or sub-expression to be printed.
+selected expression is highlighted, and simultaneously the resulting
+output is highlighted in the shell.  Calling the above commands with a
+prefix argument will prompt for an expression instead of using the one
+at point.  Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will use the
+current region as expression.
+
+For added speed and convenience, there are mouse bindings which allow
+you to click on expressions and examine their values.  Use
+@kbd{S-mouse-2} to print an expression and @kbd{C-M-mouse-2} to invoke
+help.  I.e. you need to hold down @key{SHIFT} and @key{CONTROL} while
+clicking with the middle mouse button.  If you simply click, the nearest
+expression will be selected in the same manner as described above.  You
+can also @emph{drag} the mouse in order to highlight exactly a specific
+expression or sub-expression to be examined.  For custom expression
+examination, and the customizable pop-up examine selection, @xref{Custom
+Expression Examination}.
 
 @cindex Printing expressions, on calling stack
 @cindex Restrictions for expression printing
-The same printing commands work both in the IDL Shell and IDLWAVE
-buffers, and even for variables at higher levels of the calling stack.
-For instance, if you're stopped at a breakpoint in a routine, you can
-examine the values of variables and expressions inside its calling
-routine, and so on, up through the calling stack.  Simply step up the
-stack, and print variables as you see them (@pxref{Walking the Calling
-Stack}, for information on stepping back through the calling stack).
-The following restrictions apply for all levels except the current:
+The same variable inspection commands work both in the IDL Shell and
+IDLWAVE buffers, and even for variables at higher levels of the calling
+stack.  For instance, if you're stopped at a breakpoint in a routine,
+you can examine the values of variables and expressions inside its
+calling routine, and so on, all the way up through the calling stack.
+Simply step up the stack, and print variables as you see them
+(@pxref{Walking the Calling Stack}, for information on stepping back
+through the calling stack).  The following restrictions apply for all
+levels except the current:
 
 @itemize @bullet
 @item
@@ -2588,9 +2681,9 @@ Array expressions must use the @samp{[ ]} index 
delimiters.  Identifiers
 with a @samp{( )} will be interpreted as function calls.
 @item
 @cindex ROUTINE_NAMES, IDL procedure
-Printing values of expressions on higher levels of the calling stack
-uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, which may
-or may not be available in future versions of IDL.
+N.B.: printing values of expressions on higher levels of the calling
+stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES},
+which may or may not be available in future versions of IDL.
 @end itemize
 
 @defopt idlwave-shell-expression-face
@@ -2599,10 +2692,64 @@ Allows you to choose the font, color and other 
properties for
 the expression printed by IDL.
 @end defopt
 
-@defopt idlwave-shell-print-expression-function (@code{nil})
-A function to handle special display of evaluated expressions.
+@defopt idlwave-shell-output-face
+The face for @code{idlwave-shell-output-overlay}.  
+Allows to choose the font, color and other properties for the most
+recent output of IDL when examining an expression."
 @end defopt
 
+@defopt idlwave-shell-separate-examine-output (@code{t})
+If non-@code{nil}, re-direct the output of examine commands to a special
+buffer, instead of in the shell itself.
+@end defopt
+
+@node Custom Expression Examination,  , Examining Variables, The IDLWAVE Shell
+@section Custom Expression Examination
+@cindex Expressions, custom examination
+@cindex Custom expression examination
+
+You can easily create your own customized ways to inspect expressions
+using the two convenience macros @code{idlwave-shell-inspect} and
+@code{idlwave-shell-mouse-inspect}.  These create keyboard or
+mouse-based custom inspections of variables, sharing all the same
+properties of the built-in examine commands (e.g., mouse custom examines
+can be dragged over text to examine sub-expressions).  Both functions
+take a single string argument --- the examine command --- with the text
+@code{___} (three underscores) replaced by the expression, e.g.:
+
+@lisp
+(add-hook 'idlwave-shell-mode-hook
+          (lambda ()
+            (idlwave-shell-define-key-both [s-down-mouse-2] 
+                                 (idlwave-shell-mouse-examine 
+                                  "print, size(___,/DIMENSIONS)"))
+            (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
+                                       "print, size(___,/DIMENSIONS)"))
+            (idlwave-shell-define-key-both [f10] (idlwave-shell-examine 
+                                        "print,size(___,/TNAME)"))
+            (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
+                                        "help,___,/STRUCTURE"))))
+@end lisp                                        
+            
+@noindent Now pressing @key{f9}, or middle-mouse dragging with the
+@key{SUPER} key depressed, will print the dimensions of the nearby or
+highlighted expression.  Pressing @key{f10} will give the type string,
+and @key{f11} will show the contents of a nearby structure.  As you can
+see, the possibilities are only marginally finite.
+
+The most powerful mouse examine command, available on @kbd{C-S-mouse-2},
+expands on the idea of custom examines.  Just as for all the other mouse
+examine commands, it permites click or drag expression selection, but
+instead of sending a hard-coded command to the shell, it pops-up a
+customizable selection list of examine functions to choose among,
+configured with the @code{idlwave-shell-examine-alist} variable.
+
+@defopt idlwave-shell-examine-alist
+An alist of examine commands with the keys displayed in the selection
+popup, and the values a custom IDL expression examine command to send.
+@end defopt
+
+
 @node Installation, Acknowledgements, The IDLWAVE Shell, Top
 @chapter Installation
 @cindex Installation
@@ -2712,8 +2859,8 @@ everything, modernized IDLWAVE with many new features, 
and developed the
 manual.
 
 @item 
-@uref{mailto:jdsmith@@astro.cornell.edu, @b{J.D. Smith}}, the current
-maintainer, as of version 4.10.  I helped shape object method completion
+@uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current
+maintainer, as of version 4.10, helped shape object method completion
 and most new features introduced in versions 4.x.
 @end itemize
 
@@ -2733,6 +2880,8 @@ David Huenemoerder <dph@@space.mit.edu>
 @item
 Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de>
 @item
+Dick Jackson <dick@@d-jackson.com>
+@item
 Xuyong Liu <liu@@stsci.edu>
 @item
 Simon Marshall <Simon.Marshall@@esrin.esa.it>
@@ -3053,28 +3202,33 @@ simple way.  See @file{get_rinfo} for more information.
 @cindex Interview, with the maintainer
 
 @noindent
-@b{Question:} So now you have all these complicated configuration
-options in your package, but which ones do @emph{you} as the maintainer
-actually set in your own configuration?
+@b{Question:} You have all these complicated configuration options in
+your package, but which ones do @emph{you} as the maintainer actually
+set in your own configuration?
 
 @noindent
-@b{Answer:} Hardly any.  As the maintainer, I set the default of most
-options to what I think is best.  However, the default settings do not
-turn on features which:
+@b{Answer:} Not many, beyond custom key bindings.  I set most defaults
+the way that seems best.  However, the default settings do not turn on
+features which:
 
 @itemize @minus
 @item
-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.
 @item
-are too intrusive
+are too intrusive.
 @item
-will not work properly on all Emacs installations out there
+will not work properly on all Emacs installations.
 @item
 break with widely used standards.
+@item
+use function or other non-standard keys.
+@item
+are purely personal customizations, like additional key bindings, and
+library names.
 @end itemize
 
 @noindent To see what I mean, here is the @emph{entire} configuration
-the old maintainer has in his @file{.emacs}:
+the old maintainer had in his @file{.emacs}:
 
 @lisp
 (setq idlwave-shell-debug-modifiers '(control shift)
@@ -3119,14 +3273,13 @@ user is King!
                             ("GETPROPERTY" .t)))
 
 ;; Some setting can only be done from a mode hook.  Here is an example:
-
 (add-hook 'idlwave-mode-hook
   (lambda ()
     (setq case-fold-search nil)          ; Make searches case sensitive
     ;; Run other functions here
     (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
     ;; padding a minimum of n spaces.)  The defaults use -1
     ;; instead of 1.
@@ -3134,14 +3287,14 @@ user is King!
     (idlwave-action-and-binding "<" '(idlwave-surround 1 1))
     (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-)))
     (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
-    ;;
+
     ;; Only pad after comma and with exactly 1 space
     (idlwave-action-and-binding "," '(idlwave-surround nil 1))
     (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
-    ;;
+
     ;; Pad only after `->', remove any space before the arrow
     (idlwave-action-and-binding "->"  '(idlwave-surround 0 -1 nil 2))
-    ;;;
+
     ;; Set some personal bindings
     ;; (In this case, makes `,' have the normal self-insert behavior.)
     (local-set-key "," 'self-insert-command)
@@ -3171,6 +3324,20 @@ user is King!
 (setq idlwave-shell-explicit-file-name "wave")
 (setq idlwave-shell-process-name "wave")
 (setq idlwave-shell-use-toolbar nil)           ; No toolbar
+
+;; Most shell interaction settings can be done from the shell-mode-hook.
+(add-hook 'idlwave-shell-mode-hook
+          (lambda ()
+            ;; Set up some custom key and mouse examine commands
+            (idlwave-shell-define-key-both [s-down-mouse-2] 
+                                 (idlwave-shell-mouse-examine 
+                                  "print, size(___,/DIMENSIONS)"))
+            (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
+                                       "print, size(___,/DIMENSIONS)"))
+            (idlwave-shell-define-key-both [f10] (idlwave-shell-examine 
+                                        "print,size(___,/TNAME)"))
+            (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
+                                        "help,___,/STRUCTURE"))))
 @end example
 
 @node Windows and MacOS, Index, Configuration Examples, Top
@@ -3183,16 +3350,17 @@ of Emacs, much of IDLWAVE does also work under 
different operating
 systems like Windows (with NTEmacs or NTXEmacs) or MacOS.
 
 The only problem really is that RSI does not provide a command-line
-version of IDL for Windows or MacOS which IDLWAVE could communicate
+version of IDL for Windows or MacOS which IDLWAVE can interact
 with@footnote{Call your RSI representative and complain --- it should be
 trivial for them to provide one.  And if enough people ask for it, maybe
-they will.}.  Therefore the IDLWAVE Shell does not work and you have to
-rely on IDLDE to run and debug your programs.  However, editing IDL
-source files with Emacs/IDLWAVE works with all bells and whistles,
-including routine info, completion and fast online help.  Only a small
-amount of additional information must be specified in your .emacs file:
-You must specify path names which on a UNIX can be automatically
-gathered by talking to the IDL program.
+they will.  The upcoming IDL for Mac OSX is slated to have a
+command-line version.}.  Therefore the IDLWAVE Shell does not work and
+you have to rely on IDLDE to run and debug your programs.  However,
+editing IDL source files with Emacs/IDLWAVE works with all bells and
+whistles, including routine info, completion and fast online help.  Only
+a small amount of additional information must be specified in your
+.emacs file: You must specify path names which on a UNIX can be
+automatically gathered by talking to the IDL program.
 
 Here is an example of the additional configuration needed for a Windows
 system.  I am assuming that IDLWAVE has been installed in
@@ -3219,8 +3387,8 @@ system.  I am assuming that IDLWAVE has been installed in
 (setq idlwave-libinfo-file "c:/IDLWAVE/idlcat.el")
 @end lisp
 
-Furthermore, Windows sometimes tries to outsmart you --- make sure you
-check the following things:
+@noindent Furthermore, Windows sometimes tries to outsmart you --- make
+sure you check the following things:
 
 @itemize @bullet
 @item When you download the IDLWAVE distribution, make sure you save the 
@@ -3232,7 +3400,8 @@ Options:Configuration:Miscellaneous, change the setting, 
then re-open
 the archive).  This adds one byte per line, throwing off the
 byte-counts for the help file lookups and defeating fast online help lookup.
 @item M-TAB switches among running programs --- use Esc-TAB
-instead. FIXME:  unfinished. 
+instead.
+@item Other issues as yet unnamed...
 @end itemize