Mercurial > emacs
changeset 84165:52263d6412ec
Move to ../doc/emacs/, misc/
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:37:28 +0000 |
| parents | 5c3bf00161fc |
| children | 9879cd42b099 |
| files | man/idlwave.texi |
| diffstat | 1 files changed, 0 insertions(+), 4327 deletions(-) [+] |
line wrap: on
line diff
--- a/man/idlwave.texi Thu Sep 06 04:37:22 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,4327 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename ../info/idlwave -@settitle IDLWAVE User Manual -@dircategory Emacs -@direntry -* IDLWAVE: (idlwave). Major mode and shell for IDL files. -@end direntry -@synindex ky cp -@syncodeindex vr cp -@syncodeindex fn cp -@set VERSION 6.1 -@set EDITION 6.1 -@set IDLVERSION 6.3 -@set NSYSROUTINES 4346 -@set DATE April, 2007 -@set AUTHOR J.D. Smith & Carsten Dominik -@set MAINTAINER J.D. Smith -@c %**end of header -@finalout - -@ifinfo -This file documents IDLWAVE, a major mode for editing IDL files with -Emacs, and interacting with an IDL shell run as a subprocess. - -This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE -@value{VERSION} - -Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005, - 2006, 2007 Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 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 -@title IDLWAVE User Manual -@subtitle Emacs major mode and shell for IDL -@subtitle Edition @value{EDITION}, @value{DATE} - -@author by J.D. Smith & Carsten Dominik -@page -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, 2002, 2003, 2004, 2005, - 2006, 2007 Free Software Foundation, Inc. -@sp 2 -@cindex Copyright, of IDLWAVE -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 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 - -@page - -@ifnottex - -@node Top, Introduction, (dir), (dir) - -IDLWAVE is a package which supports editing source code written in the -Interactive Data Language (IDL), and running IDL as an inferior shell. - -@end ifnottex - -@menu -* Introduction:: What IDLWAVE is, and what it is not -* IDLWAVE in a Nutshell:: One page quick-start guide -* Getting Started:: Tutorial -* The IDLWAVE Major Mode:: The mode for editing IDL programs -* The IDLWAVE Shell:: The mode for running IDL as an inferior program -* Acknowledgements:: Who did what -* Sources of Routine Info:: How does IDLWAVE know about routine XYZ -* HTML Help Browser Tips:: -* Configuration Examples:: The user is king -* Windows and MacOS:: What still works, and how -* Troubleshooting:: When good computers turn bad -* GNU Free Documentation License:: The license for this documentation. -* Index:: Fast access - -@detailmenu - --- The Detailed Node Listing --- - -Getting Started (Tutorial) - -* Lesson I -- Development Cycle:: -* Lesson II -- Customization:: -* Lesson III -- User Catalog:: - -The IDLWAVE Major Mode - -* Code Formatting:: Making code look nice -* Routine Info:: Calling Sequence and Keyword List -* Online Help:: One key press from source to help -* Completion:: Completing routine names and Keywords -* Routine Source:: Finding routines, the easy way -* Resolving Routines:: Force the Shell to compile a routine -* Code Templates:: Frequent code constructs -* Abbreviations:: Abbreviations for common commands -* Actions:: Changing case, Padding, End checking -* Doc Header:: Inserting a standard header -* Motion Commands:: Moving through the structure of a program -* Misc Options:: Things that fit nowhere else - -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 -* Octals and Highlighting:: Why "123 causes problems - -Online Help - -* Help with HTML Documentation:: -* Help with Source:: - -Completion - -* Case of Completed Words:: CaseOFcomPletedWords -* Object Method Completion and Class Ambiguity:: obj->Method, what? -* Object Method Completion in the Shell:: -* Class and Keyword Inheritance:: obj->Method, _EXTRA=e -* Structure Tag Completion:: Completing state.Tag - -Actions - -* Block Boundary Check:: Is the END statement correct? -* Padding Operators:: Enforcing space around `=' etc -* Case Changes:: Enforcing upper case keywords - -The IDLWAVE Shell - -* Starting the Shell:: How to launch IDL as a subprocess -* Using the Shell:: Interactively working with the Shell -* Commands Sent to the Shell:: -* Debugging IDL Programs:: -* Examining Variables:: -* Custom Expression Examination:: - -Debugging IDL Programs - -* A Tale of Two Modes:: -* Debug Key Bindings:: -* Breakpoints and Stepping:: -* Compiling Programs:: -* Walking the Calling Stack:: -* Electric Debug Mode:: - -Sources of Routine Info - -* Routine Definitions:: Where IDL Routines are defined. -* Routine Information Sources:: So how does IDLWAVE know about... -* Catalogs:: -* Load-Path Shadows:: Routines defined in several places -* Documentation Scan:: Scanning the IDL Manuals - -Catalogs - -* Library Catalogs:: -* User Catalog:: - -@end detailmenu -@end menu - -@node Introduction, IDLWAVE in a Nutshell, Top, Top -@chapter Introduction -@cindex Introduction -@cindex CORBA (Common Object Request Broker Architecture) -@cindex Interface Definition Language -@cindex Interactive Data Language -@cindex cc-mode.el -@cindex @file{idl.el} -@cindex @file{idl-shell.el} -@cindex Feature overview - -IDLWAVE is a package which supports editing source files written in -the Interactive Data Language (IDL), and running IDL as an inferior shell@footnote{IDLWAVE can also be used -for editing source files for the related WAVE/CL language, but with only -limited support.}. It is a feature-rich replacement for the IDLDE -development environment included with IDL, and uses the full power of -Emacs to make editing and running IDL programs easier, quicker, and more -structured. - -IDLWAVE consists of two main parts: a major mode for editing IDL -source files (@code{idlwave-mode}) and a mode for running the IDL -program as an inferior shell (@code{idlwave-shell-mode}). Although -one mode can be used without the other, both work together closely to -form a complete development environment. Here is a brief summary of -what IDLWAVE does: - -@itemize @bullet -@item -Smart code indentation and automatic-formatting. -@item -Three level syntax highlighting support. -@item -Context-sensitive display of calling sequences and keywords for more -than 1000 native IDL routines, extendible to any additional number of -local routines, and already available with many pre-scanned libraries. -@item -Fast, context-sensitive online HTML help, or source-header help for -undocumented routines. -@item -Context sensitive completion of routine names, keywords, system -variables, class names and much more. -@item -Easy insertion of code templates and abbreviations of common constructs. -@item -Automatic corrections to enforce a variety of customizable coding -standards. -@item -Integrity checks and auto-termination of logical blocks. -@item -Routine name space conflict search with likelihood-of-use ranking. -@item -Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). -@item -Documentation support. -@item -Running IDL as an inferior Shell with history search, command line -editing and all the completion and routine info capabilities present in -IDL source buffers. -@item -Full handling of debugging with breakpoints, with interactive setting -of break conditions, and easy stepping through code. -@item -Compilation, execution and interactive single-keystroke debugging of -programs directly from the source buffer. -@item -Quick, source-guided navigation of the calling stack, with variable -inspection, etc. -@item -Examining variables and expressions with a mouse click. -@item -And much, much more... -@end itemize - -@ifnottex -@cindex Screenshots -Here are a number of screenshots showing IDLWAVE in action: - -@itemize @bullet -@item -@uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer} -@item -@uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed} -@item -@uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.} -@item -@uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed} -@item -@uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code -stopped at a breakpoint} -@end itemize -@end ifnottex - -IDLWAVE is the distant successor to the @file{idl.el} and -@file{idl-shell.el} files written by Chris Chase. The modes and files -had to be renamed because of a name space conflict with CORBA's -@code{idl-mode}, defined in Emacs in the file @file{cc-mode.el}. - -In this manual, each section ends with a list of related user options. -Don't be confused by the sheer number of options available --- in most -cases the default settings are just fine. The variables are listed here -to make sure you know where to look if you want to change anything. For -a full description of what a particular variable does and how to -configure it, see the documentation string of that variable (available -with @kbd{C-h v}). Some configuration examples are also given in the -appendix. - -@node IDLWAVE in a Nutshell, Getting Started, Introduction, Top -@chapter IDLWAVE in a Nutshell -@cindex Summary of important commands -@cindex IDLWAVE in a Nutshell -@cindex Nutshell, IDLWAVE in a - -@subheading Editing IDL Programs - -@multitable @columnfractions .15 .85 -@item @key{TAB} -@tab Indent the current line relative to context. -@item @kbd{C-M-\} -@tab Re-indent all lines in the current region. -@item @kbd{C-M-q} -@tab Re-indent all lines in the current routine. -@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, splitting the current line at point. -@item @kbd{M-;} -@tab Start new comment at line beginning or after code, or (un)comment -highlighted region. -@item @kbd{M-q} -@tab Fill the current comment paragraph. -@item @kbd{C-c ?} -@tab Display calling sequence and keywords for the procedure or function call -at point. -@item @kbd{M-?} -@tab Load context sensitive online help for nearby routine, keyword, etc. -@item @kbd{M-@key{TAB}} -@tab Complete a procedure name, function name or keyword in the buffer. -@item @kbd{C-c C-i} -@tab Update IDLWAVE's knowledge about functions and procedures. -@item @kbd{C-c C-v} -@tab Visit the source code of a procedure/function. -@item @kbd{C-u C-c C-v} -@tab Visit the source code of a procedure/function in this buffer. -@item @kbd{C-c C-h} -@tab Insert a standard documentation header. -@item @kbd{C-c @key{RET}} -@tab Insert a new timestamp and history item in the documentation header. -@end multitable - -@subheading Running the IDLWAVE Shell, Debugging Programs - -@multitable @columnfractions .15 .85 -@item @kbd{C-c C-s} -@tab Start IDL as a subprocess and/or switch to the shell buffer. -@item @key{Up}, @kbd{M-p} -@tab Cycle back through IDL command history. -@item @key{Down},@kbd{M-n} -@tab Cycle forward. -@item @kbd{@key{TAB}} -@tab Complete a procedure name, function name or keyword in the shell buffer. -@item @kbd{C-c C-d C-c} -@tab Save and compile the source file in the current buffer. -@item @kbd{C-c C-d C-e} -@tab Compile and run the current region. -@item @kbd{C-c C-d C-x} -@tab Go to next syntax error. -@item @kbd{C-c C-d C-v} -@tab Switch to electric debug mode. -@item @kbd{C-c C-d C-b} -@tab Set a breakpoint at the nearest viable source line. -@item @kbd{C-c C-d C-d} -@tab Clear the nearest breakpoint. -@item @kbd{C-c C-d [} -@tab Go to the previous breakpoint. -@item @kbd{C-c C-d ]} -@tab Go to the next breakpoint. -@item @kbd{C-c C-d C-p} -@tab Print the value of the expression near point in IDL. -@end multitable - -@subheading Commonly used Settings in @file{.emacs} -@lisp -;; Change the indentation preferences -;; Start autoloading routine info after 2 idle seconds -(setq idlwave-init-rinfo-when-idle-after 2) -;; Pad operators with spaces -(setq idlwave-do-actions t - idlwave-surround-by-blank t) -;; Syntax Highlighting -(add-hook 'idlwave-mode-hook 'turn-on-font-lock) -;; 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)) -@end lisp - -@html -<A NAME="TUTORIAL"></A> -@end html - -@node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top -@chapter Getting Started (Tutorial) -@cindex Quick-Start -@cindex Tutorial -@cindex Getting Started - -@menu -* Lesson I -- Development Cycle:: -* Lesson II -- Customization:: -* Lesson III -- User Catalog:: -@end menu - -@node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started -@section Lesson I: Development Cycle - -The purpose of this tutorial is to guide you through a very basic -development cycle using IDLWAVE. We will paste a simple program into -a buffer and use the shell to compile, debug and run it. On the way -we will use many of the important IDLWAVE commands. Note, however, -that IDLWAVE has many more capabilities than covered here, which can -be discovered by reading the entire manual, or hovering over the -shoulder of your nearest IDLWAVE guru for a few days. - -It is assumed that you have access to Emacs or XEmacs with the full -IDLWAVE package including online help. We 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, -indicated in the mode line just below the editing window. Also, the -menu bar should contain @samp{IDLWAVE}. - -Now cut-and-paste the following code, 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}, and indent the whole region with -@kbd{C-M-\}). 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 (as long as the variable @code{idlwave-expand-generic-end} -is turned on --- @pxref{Lesson II -- Customization}). Now place the -cursor in any line you would like to split 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 day of the week -of a given date for the first 10 years of the 21st century. As in -most code, there are a few bugs, which we are going to use IDLWAVE to -help us fix. - -First, let's launch the IDLWAVE shell. You do this with the command -@kbd{C-c C-s}. The Emacs window will split or another window will popup -to display IDL running in a shell interaction buffer. Type a few -commands like @code{print,!PI} to convince yourself that you can work -there just as well as in a terminal, 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 @kbd{Delete}!). Compile again, using -the same keystrokes as before. Notice that the file is automatically -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 day of the week on 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, -if necessary), 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 alerted 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 (depending on what other routines -starting with @samp{plot_} you have installed on your system), hit -@key{TAB} again, and the full routine name will be completed. Now -provide the two arguments: - -@example -plot_wday,1,1 -@end example - -@noindent 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 shows the routine info -window for the plot routine, which contains a list of keywords, along -with 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). A browser will -pop up showing the HTML 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 what to do: @kbd{C-c C-s}) and execute again. Now things -look pretty good. - -Let's 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. -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 break line is -indicated. 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! -Hit @kbd{q} to exit the debugging mode, and fix the line to read: - -@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. - -@node Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started -@section Lesson II: Customization - -Emacs is probably the most customizable piece of software ever written, -and it would be a shame if you did not make use of this to adapt IDLWAVE -to your own preferences. Customizing Emacs or IDLWAVE is accomplished -by 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. - -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 -(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 and -restart Emacs. - -You likely have your own indentation preferences for IDL code. For -example, some may prefer to indent the main block of an IDL program -slightly from the margin and 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 1) -(setq idlwave-block-indent 3) -(setq idlwave-end-offset -3) -@end lisp - -Restart Emacs, and re-indent the program we developed in the first part -of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may 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:} -throughout this manual. - -If you cannot seem to master this Lisp customization in @file{.emacs}, -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, menu item @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. @samp{IDLWAVE -Code Formatting->Idlwave Abbrev And Indent Action->Idlwave Expand -Generic End} to turn on @code{END} expansion), 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. - -You may also find the key bindings used for the debugging commands too -long and complicated. Often we have heard complaints along the lines -of, ``Do I really have to go through the finger gymnastics of @kbd{C-c -C-d C-c} to run a simple command?'' Due to Emacs rules and -conventions, shorter bindings cannot be set by default, but you can -easily enable them. First, there is a way to assign all debugging -commands in a single sweep to another simpler combination. The only -problem is that we have to use something which Emacs does not need for -other important commands. One 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 (try it, it's easier). You can enable this with: - -@lisp -(setq idlwave-shell-debug-modifiers '(shift control)) -@end lisp - -@noindent If you have a special keyboard with, for example, a -@key{SUPER} key, you could even shorten that: - -@lisp -(setq idlwave-shell-debug-modifiers '(super)) -@end lisp - -@noindent to get compilation on @kbd{S-c}. Often, a modifier key like -@key{SUPER} or @key{HYPER} is bound or can be bound to an otherwise -unused key on your keyboard --- 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 IDLWAVE -buffer gets set up. The possibilities for key customization are -endless. Here we set function keys f4-f8 to common debugging commands. - -@lisp -;; First for the source buffer -(add-hook 'idlwave-mode-hook - (lambda () - (local-set-key [f4] 'idlwave-shell-retall) - (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 [f4] 'idlwave-shell-retall) - (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 - -@node Lesson III -- User Catalog, , Lesson II -- Customization, Getting Started -@section Lesson III: User and Library Catalogs - -We have already used the routine info display in the first part of this -tutorial. This was the invoked using @kbd{C-c ?}, and displays -information about the IDL routine near the cursor position. Wouldn't it -be nice to have the same kind of information available for your own -routines and for the huge amount of code in major libraries like JHUPL -or the IDL-Astro library? In many cases, you may already have this -information. Files named @file{.idlwave_catalog} in library directories -contain scanned information on the routines in that directory; many -popular libraries ship with these ``library catalogs'' pre-scanned. -Users can scan their own routines in one of two ways: either using the -supplied tool to scan directories and build their own -@file{.idlwave_catalog} files, or using the built-in method to create a -single ``user catalog'', which we'll show here. @xref{Catalogs}, for -more information on choosing which method to use. - -To build a user catalog, select @code{Routine Info/Select Catalog -Directories} from the IDLWAVE entry in the menu bar. 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 --- directories with existing library catalogs will not be -selected by default) 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{.idlwave/idlusercat.el} in your home -directory and will from now on automatically load whenever you use -IDLWAVE. You may find it necessary to rebuild the catalog on occasion -as your local libraries change, or build a library catalog for those -directories instead. Invoke routine info (@kbd{C-c ?}) or completion -(@kbd{M-@key{TAB}}) 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-@key{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 the newsgroup @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} - -The IDLWAVE major mode supports editing IDL source files. In this -chapter we describe the main features of the mode and how to customize -them. - -@menu -* Code Formatting:: Making code look nice -* Routine Info:: Calling Sequence and Keyword List -* Online Help:: One key press from source to help -* Completion:: Completing routine names and Keywords -* Routine Source:: Finding routines, the easy way -* Resolving Routines:: Force the Shell to compile a routine -* Code Templates:: Frequent code constructs -* Abbreviations:: Abbreviations for common commands -* Actions:: Changing case, Padding, End checking -* Doc Header:: Inserting a standard header -* Motion Commands:: Moving through the structure of a program -* Misc Options:: Things that fit nowhere else -@end menu - -@node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode -@section Code Formatting -@cindex Code formatting -@cindex Formatting, of code - -@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 -* Octals and Highlighting:: Why "123 causes problems -@end menu - -The IDL language, with its early roots in FORTRAN, modern -implementation in C, and liberal borrowing of features of many vector -and other languages along its 25+ year history, has inherited an -unusual mix of 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 of -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. - - -@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. - -@cindex Foreign code, adapting -@cindex Indentation, of foreign code -@kindex C-M-\ -To re-indent a larger portion of code (e.g. when working with foreign -code written with different conventions), use @kbd{C-M-\} -(@code{indent-region}) after marking the relevant code. Useful marking -commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current -subprogram). The command @kbd{C-M-q} reindents the entire current -routine. @xref{Actions}, for information how to impose additional -formatting conventions on foreign code. - -@defopt idlwave-main-block-indent (@code{2}) -Extra indentation for the main block of code. That is the block between -the FUNCTION/PRO statement and the END statement for that program -unit. -@end defopt - -@defopt idlwave-block-indent (@code{3}) -Extra indentation applied to block lines. If you change this, you -probably also want to change @code{idlwave-end-offset}. -@end defopt - -@defopt idlwave-end-offset (@code{-3}) -Extra indentation applied to block END lines. A value equal to negative -@code{idlwave-block-indent} will make END lines line up with the block -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 avoid using 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 a fixed-offset from the enclosing -indent (the size of which offset is set in -@code{idlwave-continuation-indent}). As a special case, continuations -of routine calls without any arguments or keywords will @emph{not} -align the continued line, under the assumption that you continued -because you needed the space. - -Also, since the indentation level can be 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-@code{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, regardless of whether the -@code{idlwave-max-extra-continuation-indent} limit is satisfied. -@end defopt - -@node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting -@subsection Comment Indentation -@cindex Comment indentation -@cindex Hanging paragraphs -@cindex Paragraphs, filling -@cindex Paragraphs, hanging - -In IDL, lines starting with a @samp{;} are called @emph{comment lines}. -Comment lines are indented as follows: - -@multitable @columnfractions .1 .90 -@item @code{;;;} -@tab The indentation of lines starting with three semicolons remains -unchanged. -@item @code{;;} -@tab Lines starting with two semicolons are indented like the surrounding code. -@item @code{;} -@tab Lines starting with a single semicolon are indented to a minimum column. -@end multitable - -@noindent -The indentation of comments starting in column 0 is never changed. - -@defopt idlwave-no-change-comment -The indentation of a comment starting with this regexp will not be -changed. -@end defopt - -@defopt idlwave-begin-line-comment -A comment anchored at the beginning of line. -@end defopt - -@defopt idlwave-code-comment -A comment that starts with this regexp is indented as if it is a part of -IDL code. -@end defopt - -@node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting -@subsection Continuation Lines and Filling -@cindex Continuation lines -@cindex Line splitting -@cindex String splitting -@cindex Splitting, of lines - -@kindex M-@key{RET} -In IDL, a newline character terminates a statement unless preceded by a -@samp{$}. If you would like to start a continuation line, use -@kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}. -It inserts the continuation character @samp{$}, terminates the line and -indents the new line. The command @kbd{M-@key{RET}} can also be invoked -inside a string to split it at that point, in which case the @samp{+} -concatenation operator is used. - -@cindex Filling -@cindex @code{auto-fill-mode} -@cindex Hanging paragraphs -When filling comment paragraphs, IDLWAVE overloads the normal filling -functions and uses a function which creates the hanging paragraphs -customary in IDL routine headers. When @code{auto-fill-mode} is turned -on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If the -first line of a paragraph contains a match for -@code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent -lines are positioned to line up after it, as in the following example. - -@example -@group -;================================= -; x - an array containing -; lots of interesting numbers. -; -; y - another variable where -; a hanging paragraph is used -; to describe it. -;================================= -@end group -@end example - -@kindex M-q -You can also refill a comment at any time paragraph with @kbd{M-q}. -Comment delimiting lines as in the above example, consisting of one or -more @samp{;} followed by one or more of the characters @samp{+=-_*}, -are kept in place, as is. - -@defopt idlwave-fill-comment-line-only (@code{t}) -Non-@code{nil} means auto fill will only operate on comment lines. -@end defopt - -@defopt idlwave-auto-fill-split-string (@code{t}) -Non-@code{nil} means auto fill will split strings with the IDL @samp{+} -operator. -@end defopt - -@defopt idlwave-split-line-string (@code{t}) -Non-@code{nil} means @code{idlwave-split-line} will split strings with -@samp{+}. -@end defopt - -@defopt idlwave-hanging-indent (@code{t}) -Non-@code{nil} means comment paragraphs are indented under the hanging -indent given by @code{idlwave-hang-indent-regexp} match in the first -line of the paragraph. -@end defopt - -@defopt idlwave-hang-indent-regexp (@code{"- "}) -Regular expression matching the position of the hanging indent -in the first line of a comment paragraph. -@end defopt - -@defopt idlwave-use-last-hang-indent (@code{nil}) -Non-@code{nil} means use last match on line for -@code{idlwave-indent-regexp}. -@end defopt - -@node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting -@subsection Syntax Highlighting -@cindex Syntax highlighting -@cindex Highlighting of syntax -@cindex Font lock - -Highlighting of keywords, comments, strings etc. can be accomplished -with @code{font-lock}. If you are using @code{global-font-lock-mode} -(in Emacs), or have @code{font-lock} turned on in any other buffer in -XEmacs, it should also automatically work in IDLWAVE buffers. If you'd -prefer invoking font-lock individually by mode, you can enforce it in -@code{idlwave-mode} with the following line in your @file{.emacs}: - -@lisp -(add-hook 'idlwave-mode-hook 'turn-on-font-lock) -@end lisp - -@noindent IDLWAVE supports 3 increasing levels of syntax highlighting. -The variable @code{font-lock-maximum-decoration} determines which level -is selected. Individual categories of special tokens can be selected -for highlighting using the variable -@code{idlwave-default-font-lock-items}. - -@defopt idlwave-default-font-lock-items -Items which should be fontified on the default fontification level -2. -@end defopt - -@node Octals and Highlighting, , Syntax Highlighting, Code Formatting -@subsection Octals and Highlighting -@cindex Syntax highlighting, Octals -@cindex Highlighting of syntax, Octals - -A rare syntax highlighting problem results from an extremely unfortunate -notation for octal numbers in IDL: @code{"123}. This unpaired quotation -mark is very difficult to parse, given that it can be mixed on a single -line with any number of strings. Emacs will incorrectly identify this -as a string, and the highlighting of following lines of code can be -distorted, since the string is never terminated. - -One solution to this involves terminating the mistakenly identified -string yourself by providing a closing quotation mark in a comment: - -@example - string("305B) + $ ;" <--- for font-lock - ' is an Angstrom.' -@end example - -@noindent A far better solution is to abandon this notation for octals -altogether, and use the more sensible alternative IDL provides: - -@example - string('305'OB) + ' is an Angstrom.' -@end example - -@noindent This simultaneously solves the font-lock problem and is more -consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}. - -@node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode -@section Routine Info -@cindex Routine info -@cindex Updating routine info -@cindex Scanning buffers for routine info -@cindex Buffers, scanning for routine info -@cindex Shell, querying for routine info - -@kindex C-c C-i -IDL comes bundled with more than one thousand procedures, functions -and object methods, and large libraries typically contain hundreds or -even thousands more (each with a few to tens of keywords and -arguments). This large command set can make it difficult to remember -the calling sequence and keywords for the routines you use, but -IDLWAVE can help. It builds up routine information from a wide -variety of sources; IDLWAVE in fact knows far more about the -@samp{.pro} routines on your system than IDL itself! It maintains a -list of all built-in routines, with calling sequences and -keywords@footnote{This list is created by scanning the IDL manuals and -might contain (very few) errors. Please report any errors to the -maintainer, so that they can be fixed.}. It also scans Emacs buffers -for routine definitions, queries the IDLWAVE-Shell for information -about routines currently compiled there, and automatically locates -library and user-created catalogs. This information is updated -automatically, and so should usually be current. To force a global -update and refresh the routine information, use @kbd{C-c C-i} -(@code{idlwave-update-routine-info}). - -@kindex C-c ? -To display the information about a routine, press @kbd{C-c ?}, which -calls the command @code{idlwave-routine-info}. When the current cursor -position is on the name or in the argument list of a procedure or -function, information will be displayed about the routine. For example, -consider the indicated cursor positions in the following line: - -@example -plot,x,alog(x+5*sin(x) + 2), - | | | | | | | | - 1 2 3 4 5 6 7 8 -@end example - -@cindex Default routine, for info and help -On positions 1,2 and 8, information about the @samp{plot} procedure will -be shown. On positions 3,4, and 7, the @samp{alog} function will be -described, while positions 5 and 6 will investigate the @samp{sin} -function. - -When you ask for routine information about an object method, and the -method exists in several classes, IDLWAVE queries for the class of the -object, unless the class is already known through a text property on the -@samp{->} operator (@pxref{Object Method Completion and Class -Ambiguity}), or by having been explicitly included in the call -(e.g. @code{a->myclass::Foo}). - -@cindex Calling sequences -@cindex Keywords of a routine -@cindex Routine source information -The description displayed contains the calling sequence, the list of -keywords and the source location of this routine. It looks like this: - -@example -Usage: XMANAGER, NAME, ID -Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER - JUST_REG MODAL NO_BLOCK -Source: SystemLib [LCSB] /soft1/idl53/lib/xmanager.pro -@end example - -@cindex Categories, of routines -@cindex Load-path shadows -@cindex Shadows, load-path -@cindex IDL variable @code{!PATH} -@cindex @code{!PATH}, IDL variable -@cindex IDL variable @code{!DIR} -@cindex @code{!DIR}, IDL variable - -If a definition of this routine exists in several files accessible to -IDLWAVE, several @samp{Source} lines will point to the different -files. This may indicate that your routine is shadowing a system -library routine, which may or may not be what you want -(@pxref{Load-Path Shadows}). The information about the calling -sequence and keywords is derived from the first source listed. -Library routines are available only if you have scanned your local IDL -directories or are using pre-scanned libraries (@pxref{Catalogs}). -The source entry consists of a @emph{source category}, a set of -@emph{flags} and the path to the @emph{source file}. The following -default categories exist: - -@multitable @columnfractions .15 .85 -@item @i{System} -@tab A system routine of unknown origin. When the system library has -been scanned as part of a catalog (@pxref{Catalogs}), this category -will automatically split into the next two. -@item @i{Builtin} -@tab A builtin system routine with no source code available. -@item @i{SystemLib} -@tab A library system routine in the official lib directory @file{!DIR/lib}. -@item @i{Obsolete} -@tab A library routine in the official lib directory @file{!DIR/lib/obsolete}. -@item @i{Library} -@tab A routine in a file on IDL's search path @code{!PATH}. -@item @i{Other} -@tab Any other routine with a file not known to be on the search path. -@item @i{Unresolved} -@tab An otherwise unknown routine the shell lists as unresolved -(referenced, but not compiled). -@end multitable - -Any routines discovered in library catalogs (@pxref{Library -Catalogs}), will display the category assigned during creation, -e.g. @samp{NasaLib}. For routines not discovered in this way, you can -create additional categories based on the routine's filename using the -variable @code{idlwave-special-lib-alist}. - -@cindex Flags, in routine info -@cindex Duplicate routines -@cindex Multiply defined routines -@cindex Routine definitions, multiple -The flags @code{[LCSB]} indicate the source of the information IDLWAVE -has regarding the file: from a library catalog (@w{@code{[L---]}}), -from a user catalog (@w{@code{[-C--]}}, from the IDL Shell -(@w{@code{[--S-]}}) or from an Emacs buffer (@w{@code{[---B]}}). -Combinations are possible (a compiled library routine visited in a -buffer might read @w{@code{[L-SB]}}). If a file contains multiple -definitions of the same routine, the file name will be prefixed with -@samp{(Nx)} where @samp{N} is the number of definitions. - -@cindex Online Help from the routine info buffer -@cindex Active text, in routine info -@cindex Inserting keywords, from routine info -@cindex Source file, access from routine info -Some of the text in the @file{*Help*} routine info buffer will be active -(it is highlighted when the mouse moves over it). Typically, clicking -with the right mouse button invokes online help lookup, and clicking -with the middle mouse button inserts keywords or visits files: - -@multitable @columnfractions 0.15 0.85 -@item @i{Usage} -@tab If online help is installed, a click with the @emph{right} mouse -button on the @i{Usage:} line will access the help for the -routine (@pxref{Online Help}). -@item @i{Keyword} -@tab Online help about keywords is also available with the -@emph{right} mouse button. Clicking on a keyword with the @emph{middle} -mouse button will insert this keyword in the buffer from where -@code{idlwave-routine-info} was called. Holding down @key{SHIFT} while -clicking also adds the initial @samp{/}. -@item @i{Source} -@tab Clicking with the @emph{middle} mouse button on a @samp{Source} line -finds the source file of the routine and visits it in another window. -Another click on the same line switches back to the buffer from which -@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, if such a method -exists there. -@end multitable - -@defopt idlwave-resize-routine-help-window (@code{t}) -Non-@code{nil} means resize the Routine-info @file{*Help*} window to -fit the content. -@end defopt - -@defopt idlwave-special-lib-alist -Alist of regular expressions matching special library directories. -@end defopt - -@defopt idlwave-rinfo-max-source-lines (@code{5}) -Maximum number of source files displayed in the Routine Info window. -@end defopt - - -@html -<A NAME="ONLINE_HELP"></A> -@end html -@node Online Help, Completion, Routine Info, The IDLWAVE Major Mode -@section Online Help - -@cindex Online Help -@cindex @file{idlw-help.txt} -@cindex @file{idlw-help.el} -@cindex Installing online help -@cindex Online Help, Installation -@cindex Speed, of online help -@cindex XML Help Catalog - -For IDL system routines, extensive documentation is supplied with IDL. -IDLWAVE can access the HTML version of this documentation very quickly -and accurately, based on the local context. This can be @emph{much} -faster than using the IDL online help application, because IDLWAVE -usually gets you to the right place in the documentation directly --- -e.g. a specific keyword of a routine --- without any additional browsing -and scrolling. - -For this online help to work, an HTML version of the IDL documentation -is required. Beginning with IDL 6.2, HTML documentation is distributed -directly with IDL, along with an XML-based catalog of routine -information. By default, IDLWAVE automatically attempts to convert this -XML catalog into a format Emacs can more easily understand, and caches -this information in your @code{idlwave_config_directory} -(@file{~/.idlwave/}, by default). It also re-scans the XML catalog if -it is newer than the current cached version. You can force rescan with -the menu entry @code{IDLWAVE->Routine Info->Rescan XML Help Catalog}. - -Before IDL 6.2, the HTML help was not distributed with IDL, and was not -part of the standalone IDLWAVE distribution, but had to be downloaded -separately. This is no longer necessary: all help and routine -information is supplied with IDL versions 6.2 and later. - -There are a variety of options for displaying the HTML help: see below. -Help for routines without HTML documentation is also available, by using -the routine documentation header and/or routine source. - -@kindex M-? -In any IDL program (or, as with most IDLWAVE commands, in the IDL -Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with -@kbd{S-Mouse-3} to access context sensitive online help. The following -locations are recognized context for help: - -@cindex Context, for online help -@multitable @columnfractions .25 .75 -@item @i{Routine names} -@tab The name of a routine (function, procedure, method). -@item @i{Keyword Parameters} -@tab A keyword parameter of a routine. -@item @i{System Variables} -@tab System variables like @code{!DPI}. -@item @i{System Variable Tags} -@tab System variables tags like @code{!D.X_SIZE}. -@item @i{IDL Statements} -@tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. -@item @i{IDL Controls} -@tab Control structures like @code{FOR}, @code{SWITCH}, etc. -@item @i{Class names} -@tab A class name in an @code{OBJ_NEW} call. -@item @i{Class Init Keywords} -@tab Beyond the class name in an @code{OBJ_NEW} call. -@item @i{Executive Command} -@tab An executive command like @code{.RUN}. Mostly useful in the shell. -@item @i{Structure Tags} -@tab Structure tags like @code{state.xsize} -@item @i{Class Tags} -@tab Class tags like @code{self.value}. -@item @i{Default} -@tab The routine that would be selected for routine info display. -@end multitable - -@cindex @code{OBJ_NEW}, special online help -Note that the @code{OBJ_NEW} function is special in that the help -displayed depends on the cursor position. If the cursor is on the -@samp{OBJ_NEW}, this function is described. If it is on the class -name inside the quotes, the documentation for the class is pulled up. -If the cursor is @emph{after} the class name, anywhere in the argument -list, the documentation for the corresponding @code{Init} method and -its keywords is targeted. - -Apart from an IDLWAVE buffer or shell, there are two more places from -which online help can be accessed. - -@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 -corresponding help (@pxref{Routine Info}). -@item -When using completion and Emacs pops up a @file{*Completions*} buffer -with possible completions, clicking with @kbd{Mouse-3} on a completion -item invokes help on that item (@pxref{Completion}). Items for which -help is available in the online system documentation (vs. just the -program source itself) will be emphasized (e.g. colored blue). -@end itemize -@noindent -In both cases, a blue face indicates that the item is documented in -the IDL manual, but an attempt will be made to visit non-blue items -directly in the originating source file. - - -@menu -* Help with HTML Documentation:: -* Help with Source:: -@end menu - -@node Help with HTML Documentation, Help with Source, Online Help, Online Help -@subsection Help with HTML Documentation -@cindex HTML Help -@cindex Help using HTML manuals -@cindex IDL manual, HTML version -@cindex IDL Assistant - -Help using the HTML documentation is invoked with the built-in Emacs -command @code{browse-url}, which displays the relevant help topic in a -browser of your choosing. Beginning with version 6.2, IDL comes with -the help browser @emph{IDL Assistant}, which it uses by default for -displaying online help on all supported platforms. This browser -offers topical searches, an index, and is also now the default and -recommended IDLWAVE help browser. The variable -@code{idlwave-help-use-assistant} controls whether this browser is -used. Note that, due to limitations in the Assistant, invoking help -within IDLWAVE and @code{? topic} within IDL will result in two -running copies of Assistant. - -Aside from the IDL Assistant, there are many possible browsers to choose -among, with differing advantages and disadvantages. The variable -@code{idlwave-help-browser-function} controls which browser help is sent -to (as long as @code{idlwave-help-use-assistant} is not set). This -function is used to set the variable @code{browse-url-browser-function} -locally for IDLWAVE help only. Customize the latter variable to see -what choices of browsers your system offers. Certain browsers like -@code{w3} (bundled with many versions of Emacs) and @code{w3m} -(@uref{http://emacs-w3m.namazu.org/}) are run within Emacs, and use -Emacs buffers to display the HTML help. This can be convenient, -especially on small displays, and images can even be displayed in-line -on newer Emacs versions. However, better formatting results are often -achieved with external browsers, like Mozilla. IDLWAVE assumes any -browser function containing "w3" is displayed in a local buffer. If you -are using another Emacs-local browser for which this is not true, set -the variable @code{idlwave-help-browser-is-local}. - -With IDL 6.2 or later, it is important to ensure that the variable -@code{idlwave-system-directory} is set (@pxref{Catalogs}). One easy way -to ensure this is to run the IDL Shell (@kbd{C-c C-s}). It will be -queried for this directory, and the results will be cached to file for -subsequent use. - -@xref{HTML Help Browser Tips}, for more information on selecting and -configuring a browser for use with IDL's HTML help system. - -@defopt idlwave-html-system-help-location @file{help/online_help} -Relative directory of the system-supplied HTML help directory, -considered with respect to @code{idlwave-system-directory}. Relevant -for IDL 6.2 and greater. Should not change. -@end defopt - -@defopt idlwave-html-help-location @file{/usr/local/etc/} -The directory where the @file{idl_html_help} HTML directory live. -Obsolete and ignored for IDL 6.2 and greater -(@code{idlwave-html-system-help-location} is used instead). -@end defopt - -@defopt idlwave-help-use-assistant @code{t} -If set, use the IDL Assistant if possible for online HTML help, -otherwise use the browser function specified in -@code{idlwave-help-browser-function}. -@end defopt - -@defopt idlwave-help-browser-function -The browser function to use to display IDLWAVE HTML help. Should be -one of the functions available for setting -@code{browse-url-browser-function}, which see. -@end defopt - -@defopt idlwave-help-browser-is-local -Is the browser selected in @code{idlwave-help-browser-function} run in a -local Emacs buffer or window? Defaults to @code{t} if the function -contains "-w3". -@end defopt - -@defopt idlwave-help-link-face -The face for links to IDLWAVE online help. -@end defopt - -@node Help with Source, , Help with HTML Documentation, Online Help -@subsection Help with Source -@cindex Help using routine source - -@cindex Source code, as online help -@cindex DocLib header, as online help -For routines which are not documented in an HTML manual (for example -personal or library routines), the source code itself is used as help -text. If the requested information can be found in a (more or less) -standard DocLib file header, IDLWAVE shows the header (scrolling down to -a keyword, if appropriate). Otherwise the routine definition statement -(@code{pro}/@code{function}) is shown. The doclib header sections which -are searched for include @samp{NAME} and @samp{KEYWORDS}. Localization -support can be added by customizing the @code{idlwave-help-doclib-name} -and @code{idlwave-help-doclib-keyword} variables. - -@cindex Structure tags, in online help -@cindex Class tags, in online help -Help is also available for class structure tags (@code{self.TAG}), and -generic structure tags, if structure tag completion is enabled -(@pxref{Structure Tag Completion}). This is implemented by visiting the -tag within the class or structure definition source itself. Help is not -available on built-in system class tags. - -The help window is normally displayed in the same frame, but can be -popped-up in a separate frame. The following commands can be used to -navigate inside the help system for source files: - -@multitable @columnfractions .15 .85 -@item @kbd{@key{SPACE}} -@tab Scroll forward one page. -@item @kbd{@key{RET}} -@tab Scroll forward one line. -@item @kbd{@key{DEL}} -@tab Scroll back one page. -@item @kbd{h} -@tab Jump to DocLib Header of the routine whose source is displayed -as help. -@item @kbd{H} -@tab Jump to the first DocLib Header in the file. -@item @kbd{.} @r{(Dot)} -@tab Jump back and forth between the routine definition (the -@code{pro}/@code{function} statement) and the description of the help -item in the DocLib header. -@item @kbd{F} -@tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}. -@item @kbd{q} -@tab Kill the help window. -@end multitable - - -@defopt idlwave-help-use-dedicated-frame (@code{nil}) -Non-@code{nil} means use a separate frame for Online Help if possible. -@end defopt - -@defopt idlwave-help-frame-parameters -The frame parameters for the special Online Help frame. -@end defopt - -@defopt idlwave-max-popup-menu-items (@code{20}) -Maximum number of items per pane in pop-up menus. -@end defopt - -@defopt idlwave-extra-help-function -Function to call for help if the normal help fails. -@end defopt - -@defopt idlwave-help-fontify-source-code (@code{nil}) -Non-@code{nil} means fontify source code displayed as help. -@end defopt - -@defopt idlwave-help-source-try-header (@code{t}) -Non-@code{nil} means try to find help in routine header when -displaying source file. -@end defopt - -@defopt idlwave-help-doclib-name (@code{"name"}) -The case-insensitive heading word in doclib headers to locate the -@emph{name} section. Can be a regexp, e.g. @code{"\\(name\\|nom\\)"}. -@end defopt - -@defopt idlwave-help-doclib-keyword (@code{"KEYWORD"}) -The case-insensitive heading word in doclib headers to locate the -@emph{keywords} section. Can be a regexp. -@end defopt - - -@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode -@section Completion -@cindex Completion -@cindex Keyword completion -@cindex Method completion -@cindex Object method completion -@cindex Class name completion -@cindex Function name completion -@cindex Procedure name completion - -@kindex M-@key{TAB} -@kindex C-c C-i -IDLWAVE offers completion for class names, routine names, keywords, -system variables, system variable tags, class structure tags, regular -structure tags and file names. As in many programming modes, completion -is bound to @kbd{M-@key{TAB}} (or simply @kbd{@key{TAB}} in the IDLWAVE -Shell --- @pxref{Using the Shell}). Completion uses exactly the same -internal information as routine info, so when necessary (rarely) it can -be updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}). - -The completion function is context sensitive and figures out what to -complete based on the location of the point. Here are example lines and -what @kbd{M-@key{TAB}} would try to complete when the cursor is on the -position marked with a @samp{_}: - -@example -plo_ @r{Procedure} -x = a_ @r{Function} -plot,xra_ @r{Keyword of @code{plot} procedure} -plot,x,y,/x_ @r{Keyword of @code{plot} procedure} -plot,min(_ @r{Keyword of @code{min} function} -obj -> a_ @r{Object method (procedure)} -a[2,3] = obj -> a_ @r{Object method (function)} -x = obj_new('IDL_ @r{Class name} -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} -state.w_ @r{Structure tag, if tag completion enabled} -name = 'a_ @r{File name (default inside quotes)} -@end example - -@cindex Completion, ambiguity -@cindex Completion, forcing function name -The only place where completion is ambiguous is procedure/function -@emph{keywords} versus @emph{functions}. After @samp{plot,x,_}, IDLWAVE -will always assume a keyword to @samp{plot}. However, a function is -also a possible completion here. You can force completion of a function -name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}. - -Giving two prefix arguments (@kbd{C-u C-u M-@key{TAB}}) prompts for a -regular expression to search among the commands to be completed. As -an example, completing a blank line in this way will allow you to -search for a procedure matching a regexp. - -@cindex Scrolling the @file{*Completions*} window -@cindex Completion, scrolling -@cindex Completion, Online Help -@cindex Online Help in @file{*Completions*} buffer -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 -item. Items for which system online help (from the IDL manual) is -available will be emphasized (e.g. colored blue). For other items, the -corresponding source code or DocLib header will be used as the help -text. - -@cindex Completion, cancelling -@cindex Cancelling completion -Completion is not a blocking operation --- you are free to continue -editing, enter commands, or simply ignore the @file{*Completions*} -buffer during a completion operation. If, however, the most recent -command was a completion, @kbd{C-g} will remove the buffer and restore -the window configuration. You can also remove the buffer at any time -with no negative consequences. - -@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 the cursor between the two. -@end defopt - -@defopt idlwave-completion-restore-window-configuration (@code{t}) -Non-@code{nil} means restore window configuration after successful -completion. -@end defopt - -@defopt idlwave-highlight-help-links-in-completion (@code{t}) -Non-@code{nil} means highlight completions for which system help is -available. -@end defopt - -@menu -* Case of Completed Words:: CaseOFcomPletedWords -* Object Method Completion and Class Ambiguity:: obj->Method, what? -* Object Method Completion in the Shell:: -* Class and Keyword Inheritance:: obj->Method, _EXTRA=e -* Structure Tag Completion:: Completing state.Tag -@end menu - -@node Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion -@subsection Case of Completed Words -@cindex Case of completed words -@cindex Mixed case completion -IDL is a case-insensitive language, so casing is a matter of style -only. IDLWAVE helps maintain a consistent casing style for completed -items. The case of the completed words is determined by what is -already in the buffer. As an exception, when the partial word being -completed is all lower case, the completion will be lower case as -well. If at least one character is upper case, the string will be -completed in upper case or mixed case, depending on the value of the -variable @code{idlwave-completion-case}. The default is to use upper -case for procedures, functions and keywords, and mixed case for object -class names and methods, similar to the conventions in the IDL -manuals. For instance, to enable mixed-case completion for routines -in addition to classes and methods, you need an entry such as -@code{(routine . preserve)} in that variable. To enable total control -over the case of completed items, independent of buffer context, set -@code{idlwave-completion-force-default-case} to non-@code{nil}. - -@defopt idlwave-completion-case -Association list setting the case (UPPER/lower/Capitalized/MixedCase...) -of completed words. -@end defopt - -@defopt idlwave-completion-force-default-case (@code{nil}) -Non-@code{nil} means completion will always honor the settings in -@code{idlwave-completion-case}. When nil (the default), entirely lower -case strings will always be completed to lower case, no matter what the -settings in @code{idlwave-completion-case}. -@end defopt - -@defopt idlwave-complete-empty-string-as-lower-case (@code{nil}) -Non-@code{nil} means the empty string is considered lower case for -completion. -@end defopt - -@node Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion -@subsection Object Method Completion and Class Ambiguity -@cindex Object methods -@cindex Class ambiguity -@cindex @code{self} object, default class -An object method is not uniquely determined without the object's class. -Since the class is almost always omitted in the calling source (as -required to obtain the true benefits of object-based programming), -IDLWAVE considers all available methods in all classes as possible -method name completions. The combined list of keywords of the current -method in @emph{all} known classes which contain that method will be -considered for keyword completion. In the @file{*Completions*} buffer, -the matching classes will be shown next to each item (see option -@code{idlwave-completion-show-classes}). As a special case, the class -of an object called @samp{self} is always taken to be the class of the -current routine, when in an IDLWAVE buffer. All inherits classes are -considered as well. - -@cindex Forcing class query. -@cindex Class query, forcing -You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u -M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to -narrow down the number of possible completions. The variable -@code{idlwave-query-class} can be configured to make such prompting the -default for all methods (not recommended), or selectively for very -common methods for which the number of completing keywords would be too -large (e.g. @code{Init,SetProperty,GetProperty}). - -@cindex Saving object class on @code{->} -@cindex @code{->} -After you have specified the class for a particular statement (e.g. when -completing the method), IDLWAVE can remember it for the rest of the -editing session. Subsequent completions in the same statement -(e.g. keywords) can then reuse this class information. This works by -placing a text property on the method invocation operator @samp{->}, -after which the operator will be shown in a different face (bold by -default). The variable @code{idlwave-store-inquired-class} can be used -to turn it off or on. - -@defopt idlwave-completion-show-classes (@code{1}) -Non-@code{nil} means show up to that many classes in -@file{*Completions*} buffer when completing object methods and -keywords. -@end defopt - -@defopt idlwave-completion-fontify-classes (@code{t}) -Non-@code{nil} means fontify the classes in completions buffer. -@end defopt - -@defopt idlwave-query-class (@code{nil}) -Association list governing query for object classes during completion. -@end defopt - -@defopt idlwave-store-inquired-class (@code{t}) -Non-@code{nil} means store class of a method call as text property on -@samp{->}. -@end defopt - -@defopt idlwave-class-arrow-face -Face to highlight object operator arrows @samp{->} which carry a saved -class text property. -@end defopt - -@node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion -@subsection Object Method Completion in the Shell -@cindex Method Completion in Shell -In the IDLWAVE Shell (@pxref{The IDLWAVE Shell}), objects on which -methods are being invoked have a special property: they must exist as -variables, and so their class can be determined (for instance, using the -@code{obj_class()} function). In the Shell, when attempting completion, -routine info, or online help within a method routine, a query is sent to -determine the class of the object. If this query is successful, the -class found will be used to select appropriate completions, routine -info, or help. If unsuccessful, information from all known classes will -be used (as in the buffer). - -@node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion -@subsection Class and Keyword Inheritance -@cindex Inheritance, class -@cindex Keyword inheritance -@cindex Inheritance, keyword - -Class inheritance affects which methods are called in IDL. An object of -a class which inherits methods from one or more superclasses can -override that method by defining its own method of the same name, extend -the method by calling the method(s) of its superclass(es) in its -version, or inherit the method directly by making no modifications. -IDLWAVE examines class definitions during completion and routine -information display, and records all inheritance information it finds. -This information is displayed if appropriate with the calling sequence -for methods (@pxref{Routine Info}), as long as variable -@code{idlwave-support-inheritance} is non-@code{nil}. - -In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and -@code{_REF_EXTRA}) is used hand-in-hand with class inheritance and -method overriding. E.g., in a @code{SetProperty} method, this technique -allows a single call @code{obj->SetProperty} to set properties up the -entire class inheritance chain. This is often referred to as -@emph{chaining}, and is characterized by chained method calls like -@w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}. - -IDLWAVE can accommodate this special synergy between class and keyword -inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a -method's keyword parameters, all keywords of superclass versions of -the method being considered can be included in completion. There is -of course no guarantee that this type of keyword chaining actually -occurs, but for some methods it's a very convenient assumption. The -variable @code{idlwave-keyword-class-inheritance} can be used to -configure which methods have keyword inheritance treated in this -simple, class-driven way. By default, only @code{Init} and -@code{(Get|Set)Property} are. The completion buffer will label -keywords based on their originating class. - -@defopt idlwave-support-inheritance (@code{t}) -Non-@code{nil} means consider inheritance during completion, online help etc. -@end defopt - -@defopt idlwave-keyword-class-inheritance -A list of regular expressions to match methods for which simple -class-driven keyword inheritance will be used for Completion. -@end defopt - -@node Structure Tag Completion, , Class and Keyword Inheritance, Completion -@subsection Structure Tag Completion -@cindex Completion, structure tag -@cindex Structure tag completion - -In many programs, especially those involving widgets, large structures -(e.g. the @samp{state} structure) are used to communicate among -routines. It is very convenient to be able to complete structure tags, -in the same way as for instance variables (tags) of the @samp{self} -object (@pxref{Object Method Completion and Class Ambiguity}). Add-in -code for structure tag completion is available in the form of a loadable -completion module: @file{idlw-complete-structtag.el}. Tag completion in -structures is highly ambiguous (much more so than @samp{self} -completion), so @code{idlw-complete-structtag} makes an unusual and very -specific assumption: the exact same variable name is used to refer to -the structure in all parts of the program. This is entirely unenforced -by the IDL language, but is a typical convention. If you consistently -refer to the same structure with the same variable name -(e.g. @samp{state}), structure tags which are read from its definition -in the same file can be used for completion. - -Structure tag completion is not enabled by default. To enable it, -simply add the following to your @file{.emacs}: - -@lisp - (add-hook 'idlwave-load-hook - (lambda () (require 'idlw-complete-structtag))) -@end lisp - -Once enabled, you'll also be able to access online help on the structure -tags, using the usual methods (@pxref{Online Help}). In addition, -structure variables in the shell will be queried for tag names, similar -to the way object variables in the shell are queried for method names. -So, e.g.: - -@example -IDL> st.[Tab] -@end example - -@noindent will complete with all structure fields of the structure -@code{st}. - -@node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode -@section Routine Source -@cindex Routine source file -@cindex Module source file -@cindex Source file, of a routine -@kindex C-c C-v -In addition to clicking on a @i{Source:} line in the routine info -window, there is another way to quickly visit the source file of a -routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks -for a module name, offering the same default as -@code{idlwave-routine-info} would have used, taken from nearby buffer -contents. In the minibuffer, specify a complete routine name (including -any class part). IDLWAVE will display the source file in another -window, positioned at the routine in question. You can also limit this -to a routine in the current buffer only, with completion, and a -context-sensitive default, by using a single prefix (@kbd{C-u C-c C-v}) -or the convenience binding @kbd{C-c C-t}. - -@cindex Buffers, killing -@cindex Killing autoloaded buffers -Since getting the source of a routine into a buffer is so easy with -IDLWAVE, too many buffers visiting different IDL source files are -sometimes created. The special command @kbd{C-c C-k} -(@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove -these buffers. - -@node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode -@section Resolving Routines -@cindex @code{RESOLVE_ROUTINE} -@cindex Compiling library modules -@cindex Routines, resolving - -The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve} -and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL -in order to resolve (compile) it. The default routine to be resolved is -taken from context, but you get a chance to edit it. Usually this is -not necessary, since IDL automatically discovers routines on its path. - -@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 -keep routine information available in catalogs (@pxref{Catalogs}). -Routine info on modules will then be available without the need to -compile the modules first, and even without a running shell. - -@xref{Sources of Routine Info}, for more information on the ways IDLWAVE -collects data about routines, and how to update this information. - -@node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode -@section Code Templates -@cindex Code templates -@cindex Templates - -IDLWAVE can insert IDL code templates into the buffer. For a few -templates, this is done with direct key bindings: - -@multitable @columnfractions .15 .85 -@item @kbd{C-c C-c} -@tab @code{CASE} statement template -@item @kbd{C-c C-f} -@tab @code{FOR} loop template -@item @kbd{C-c C-r} -@tab @code{REPEAT} loop template -@item @kbd{C-c C-w} -@tab @code{WHILE} loop template -@end multitable - -All code templates are also available as abbreviations -(@pxref{Abbreviations}). - -@node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode -@section Abbreviations -@cindex Abbreviations - -Special abbreviations exist to enable rapid entry of commonly used -commands. Emacs abbreviations are expanded by typing text into the -buffer and pressing @key{SPC} or @key{RET}. The special abbreviations -used to insert code templates all start with a @samp{\} (the backslash), -or, optionally, any other character set in -@code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are -only expanded where they should be (i.e., not in a string or comment), -and permits the point to be moved after an abbreviation expansion --- -very useful for positioning the mark inside of parentheses, etc. - -Special abbreviations are pre-defined for code templates and other -useful items. To visit the full list of abbreviations, use @kbd{M-x -idlwave-list-abbrevs}. - -Template abbreviations: - -@multitable @columnfractions .15 .85 -@item @code{\pr} -@tab @code{PROCEDURE} template -@item @code{\fu} -@tab @code{FUNCTION} template -@item @code{\c} -@tab @code{CASE} statement template -@item @code{\f} -@tab @code{FOR} loop template -@item @code{\r} -@tab @code{REPEAT} loop template -@item @code{\w} -@tab @code{WHILE} loop template -@item @code{\i} -@tab @code{IF} statement template -@item @code{\elif} -@tab @code{IF-ELSE} statement template -@end multitable - -String abbreviations: - -@multitable @columnfractions .15 .85 -@item @code{\ap} -@tab @code{arg_present()} -@item @code{\b} -@tab @code{begin} -@item @code{\cb} -@tab @code{byte()} -@item @code{\cc} -@tab @code{complex()} -@item @code{\cd} -@tab @code{double()} -@item @code{\cf} -@tab @code{float()} -@item @code{\cl} -@tab @code{long()} -@item @code{\co} -@tab @code{common} -@item @code{\cs} -@tab @code{string()} -@item @code{\cx} -@tab @code{fix()} -@item @code{\e} -@tab @code{else} -@item @code{\ec} -@tab @code{endcase} -@item @code{\ee} -@tab @code{endelse} -@item @code{\ef} -@tab @code{endfor} -@item @code{\ei} -@tab @code{endif else if} -@item @code{\el} -@tab @code{endif else} -@item @code{\en} -@tab @code{endif} -@item @code{\er} -@tab @code{endrep} -@item @code{\es} -@tab @code{endswitch} -@item @code{\ew} -@tab @code{endwhile} -@item @code{\g} -@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} -@tab @code{if n_elements() ne 0 then} -@item @code{\k} -@tab @code{keyword_set()} -@item @code{\n} -@tab @code{n_elements()} -@item @code{\np} -@tab @code{n_params()} -@item @code{\oi} -@tab @code{on_ioerror,} -@item @code{\or} -@tab @code{openr,} -@item @code{\ou} -@tab @code{openu,} -@item @code{\ow} -@tab @code{openw,} -@item @code{\p} -@tab @code{print,} -@item @code{\pt} -@tab @code{plot,} -@item @code{\pv} -@tab @code{ptr_valid()} -@item @code{\re} -@tab @code{read,} -@item @code{\rf} -@tab @code{readf,} -@item @code{\rt} -@tab @code{return} -@item @code{\ru} -@tab @code{readu,} -@item @code{\s} -@tab @code{size()} -@item @code{\sc} -@tab @code{strcompress()} -@item @code{\sl} -@tab @code{strlowcase()} -@item @code{\sm} -@tab @code{strmid()} -@item @code{\sn} -@tab @code{strlen()} -@item @code{\sp} -@tab @code{strpos()} -@item @code{\sr} -@tab @code{strtrim()} -@item @code{\st} -@tab @code{strput()} -@item @code{\su} -@tab @code{strupcase()} -@item @code{\t} -@tab @code{then} -@item @code{\u} -@tab @code{until} -@item @code{\wc} -@tab @code{widget_control,} -@item @code{\wi} -@tab @code{widget_info()} -@item @code{\wu} -@tab @code{writeu,} -@end multitable - -@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 () - (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 abbreviation (here @emph{wb}) and its expansion -(@emph{widget_base()}) are given as arguments, 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 -templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}). - -@defopt idlwave-abbrev-start-char (@code{"\"}) -A single character string used to start abbreviations in abbrev mode. -Beware of common characters which might naturally occur in sequence with -abbreviation strings. -@end defopt - -@defopt idlwave-abbrev-move (@code{t}) -Non-@code{nil} means the abbrev hook can move point, e.g. to end up -between the parentheses of a function call. -@end defopt - -@node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode -@section Actions -@cindex Actions -@cindex Coding standards, enforcing - -@emph{Actions} are special formatting commands which are executed -automatically while you write code in order to check the structure of -the program or to enforce coding standards. Most actions which have -been implemented in IDLWAVE are turned off by default, assuming that the -average user wants her code the way she writes it. But if you are a -lazy typist and want your code to adhere to certain standards, actions -can be helpful. - -Actions can be applied in three ways: - -@itemize @bullet -@item -Some actions are applied directly while typing. For example, pressing -@samp{=} can run a check to make sure that this operator is surrounded -by spaces and insert these spaces if necessary. Pressing @key{SPC} -after a reserved word can call a command to change the word to upper -case. -@item -When a line is re-indented with @key{TAB}, actions can be applied to the -entire line. To enable this, the variable @code{idlwave-do-actions} -must be non-@code{nil}. -@item -@cindex Foreign code, adapting -@cindex Actions, applied to foreign code -Actions can also be applied to a larger piece of code, e.g. to convert -foreign code to your own style. To do this, mark the relevant part of -the code and execute @kbd{M-x expand-region-abbrevs}. Useful marking -commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current -subprogram). @xref{Code Indentation}, for information how to adjust the -indentation of the code. -@end itemize - -@defopt idlwave-do-actions (@code{nil}) -Non-@code{nil} means performs actions when indenting. Individual action -settings are described below and set separately. -@end defopt - -@menu -* Block Boundary Check:: Is the END statement correct? -* Padding Operators:: Enforcing space around `=' etc -* Case Changes:: Enforcing upper case keywords -@end menu - -@node Block Boundary Check, Padding Operators, Actions, Actions -@subsection Block Boundary Check -@cindex Block boundary check -@cindex @code{END} type checking -@cindex @code{END}, automatic insertion -@cindex @code{END}, expanding -@cindex Block, closing -@cindex Closing a block - -Whenever you type an @code{END} statement, IDLWAVE finds the -corresponding start of the block and the cursor blinks back to that -location for a second. If you have typed a specific @code{END}, like -@code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator -does not match the type of block it terminates. - -Set the variable @code{idlwave-expand-generic-end} in order to have all -generic @code{END} statements automatically expanded to the appropriate -type. You can also type @kbd{C-c ]} to close the current block by -inserting the appropriate @code{END} statement. - -@defopt idlwave-show-block (@code{t}) -Non-@code{nil} means point blinks to block beginning for -@code{idlwave-show-begin}. -@end defopt - -@defopt idlwave-expand-generic-end (@code{t}) -Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc. -@end defopt - -@defopt idlwave-reindent-end (@code{t}) -Non-@code{nil} means re-indent line after END was typed. -@end defopt - -@node Padding Operators, Case Changes, Block Boundary Check, Actions -@subsection Padding Operators -@cindex Padding operators with spaces -@cindex Operators, padding with spaces -@cindex Space, around operators - -Some operators can be automatically surrounded by spaces. This can -happen when the operator is typed, or later when the line is indented. -IDLWAVE can pad the operators @samp{<}, @samp{>}, @samp{,}, @samp{=}, -and @samp{->}, as well as the modified assignment operators -(@samp{AND=}, @samp{OR=}, etc.). This feature is turned off by default. -If you want to turn it on, customize the variables -@code{idlwave-surround-by-blank} and @code{idlwave-do-actions} and turn -both on. You can also define similar actions for other operators by -using the function @code{idlwave-action-and-binding} in the mode hook. -For example, to enforce space padding of the @samp{+} and @samp{*} -operators (outside of strings and comments, of course), try this in -@file{.emacs} - -@lisp -(add-hook 'idlwave-mode-hook - (lambda () - (setq idlwave-surround-by-blank t) ; Turn this type of actions on - (idlwave-action-and-binding "*" '(idlwave-surround 1 1)) - (idlwave-action-and-binding "+" '(idlwave-surround 1 1)))) -@end lisp - -Note that the modified assignment operators which begin with a word -(@samp{AND=}, @samp{OR=}, @samp{NOT=}, etc.) require a leading space to -be recognized (e.g @code{vAND=4} would be interpreted as a variable -@code{vAND}). Also note that, since e.g., @code{>} and @code{>=} are -both valid operators, it is impossible to surround both by blanks while -they are being typed. Similarly with @code{&} and @code{&&}. For -these, a compromise is made: the padding is placed on the left, and if -the longer operator is keyed in, on the right as well (otherwise you -must insert spaces to pad right yourself, or press simply press Tab to -repad everything if @code{idlwave-do-actions} is on). - -@defopt idlwave-surround-by-blank (@code{nil}) -Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil}, -@samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->}, and the -modified assignment operators (@samp{AND=}, @samp{OR=}, etc.) are -surrounded with spaces by @code{idlwave-surround}. -@end defopt - -@defopt idlwave-pad-keyword (@code{t}) -Non-@code{nil} means space-pad the @samp{=} in keyword assignments. -@end defopt - -@node Case Changes, , Padding Operators, Actions -@subsection Case Changes -@cindex Case changes -@cindex Upcase, enforcing for reserved words -@cindex Downcase, enforcing for reserved words - -Actions can be used to change the case of reserved words or expanded -abbreviations by customizing the variables -@code{idlwave-abbrev-change-case} and -@code{idlwave-reserved-word-upcase}. If you want to change the case of -additional words automatically, put something like the following into -your @file{.emacs} file: - -@lisp -(add-hook 'idlwave-mode-hook - (lambda () - ;; Capitalize system vars - (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t) - ;; Capitalize procedure name - (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" - '(capitalize-word 1) t) - ;; Capitalize common block name - (idlwave-action-and-binding "\\<common\\>[ \t]+\\<" - '(capitalize-word 1) t))) -@end lisp - -For more information, see the documentation string for the function -@code{idlwave-action-and-binding}. For information on controlling the -case of routines, keywords, classes, and methods as they are completed, see -@ref{Completion}. - -@defopt idlwave-abbrev-change-case (@code{nil}) -Non-@code{nil} means all abbrevs will be forced to either upper or lower -case. Valid values are @code{nil}, @code{t}, and @code{down}. -@end defopt - -@defopt idlwave-reserved-word-upcase (@code{nil}) -Non-@code{nil} means reserved words will be made upper case via abbrev -expansion. -@end defopt - - -@node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode -@section Documentation Header -@cindex Documentation header -@cindex DocLib header -@cindex Modification timestamp -@cindex Header, for file documentation -@cindex Timestamp, in doc header. -@cindex Changelog, in doc header. - -@kindex C-c C-h -@kindex C-c C-m -The command @kbd{C-c C-h} inserts a standard routine header into the -buffer, with the usual fields for documentation (a different header can -be specified with @code{idlwave-file-header}). One of the keywords is -@samp{MODIFICATION HISTORY} under which the changes to a routine can be -recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION -HISTORY} of the current routine or file and inserts the user name with a -timestamp. - -@defopt idlwave-file-header -The doc-header template or a path to a file containing it. -@end defopt - -@defopt idlwave-header-to-beginning-of-file (@code{nil}) -Non-@code{nil} means the documentation header will always be at start -of file. -@end defopt - -@defopt idlwave-timestamp-hook -The hook function used to update the timestamp of a function. -@end defopt - -@defopt idlwave-doc-modifications-keyword -The modifications keyword to use with the log documentation commands. -@end defopt - -@defopt idlwave-doclib-start -Regexp matching the start of a document library header. -@end defopt - -@defopt idlwave-doclib-end -Regexp matching the start of a document library header. -@end defopt - -@node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode -@section Motion Commands -@cindex Motion commands -@cindex Program structure, moving through -@cindex Code structure, moving through -@cindex @file{Func-menu}, XEmacs package -@cindex @file{Imenu}, Emacs package -@cindex Function definitions, jumping to -@cindex Procedure definitions, jumping to - -IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages -which make it easy to jump to the definitions of functions and -procedures in the current file with a pop-up selection. To bind -@file{Imenu} to a mouse-press, use in your @file{.emacs}: - -@lisp -(define-key global-map [S-down-mouse-3] 'imenu) -@end lisp - -@cindex @file{Speedbar}, Emacs package - -In addition, @file{Speedbar} support allows convenient navigation of a -source tree of IDL routine files, quickly stepping to routine -definitions. See @code{Tools->Display Speedbar}. - -Several commands allow you to move quickly through the structure of an -IDL program: - -@multitable @columnfractions .15 .85 -@item @kbd{C-M-a} -@tab Beginning of subprogram -@item @kbd{C-M-e} -@tab End of subprogram -@item @kbd{C-c @{} -@tab Beginning of block (stay inside the block) -@item @kbd{C-c @}} -@tab End of block (stay inside the block) -@item @kbd{C-M-n} -@tab Forward block (on same level) -@item @kbd{C-M-p} -@tab Backward block (on same level) -@item @kbd{C-M-d} -@tab Down block (enters a block) -@item @kbd{C-M-u} -@tab Backward up block (leaves a block) -@item @kbd{C-c C-n} -@tab Next Statement -@end multitable - - -@node Misc Options, , Motion Commands, The IDLWAVE Major Mode -@section Miscellaneous Options -@cindex Hooks - -@defopt idlwave-help-application -The external application providing reference help for programming. -@end defopt - -@defopt idlwave-startup-message (@code{t}) -Non-@code{nil} means display a startup message when @code{idlwave-mode}' -is first called. -@end defopt - -@defopt idlwave-mode-hook -Normal hook. Executed when a buffer is put into @code{idlwave-mode}. -@end defopt - -@defopt idlwave-load-hook -Normal hook. Executed when @file{idlwave.el} is loaded. -@end defopt - -@node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top -@chapter The IDLWAVE Shell -@cindex IDLWAVE shell -@cindex Major mode, @code{idlwave-shell-mode} -@cindex IDL, as Emacs subprocess -@cindex Subprocess of Emacs, IDL -@cindex Comint, Emacs package -@cindex Windows -@cindex MacOS - -The IDLWAVE shell is an Emacs major mode which permits running the IDL -program as an inferior process of Emacs, and works closely with the -IDLWAVE major mode in buffers. It can be used to work with IDL -interactively, to compile and run IDL programs in Emacs buffers and to -debug these programs. The IDLWAVE shell is built on @file{comint}, an -Emacs packages which handles the communication with the IDL program. -Unfortunately, IDL for Windows does not have command-prompt versions and -thus do not allow the interaction with Emacs --- so the IDLWAVE shell -currently only works under Unix and MacOSX. - -@menu -* Starting the Shell:: How to launch IDL as a subprocess -* Using the Shell:: Interactively working with the Shell -* Commands Sent to the Shell:: -* Debugging IDL Programs:: -* Examining Variables:: -* Custom Expression Examination:: -@end menu - -@node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell -@section Starting the Shell -@cindex Starting the shell -@cindex Shell, starting -@cindex Dedicated frame, for shell buffer -@cindex Frame, for shell buffer -@cindex Subprocess of Emacs, IDL - -@kindex C-c C-s -The IDLWAVE shell can be started with the command @kbd{M-x -idlwave-shell}. In @code{idlwave-mode} the function is bound to -@kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to -interact with the shell. If the shell is already running, @kbd{C-c -C-s} will simply switch to the shell buffer. The command @kbd{C-c -C-l} (@code{idlwave-shell-recenter-shell-window}) displays the shell -window without selecting it. The shell can also be started -automatically when another command tries to send a command to it. To -enable auto start, set the variable -@code{idlwave-shell-automatic-start} to @code{t}. - -In order to create a separate frame for the IDLWAVE shell buffer, call -@code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or -@kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell -window, configure the variable -@code{idlwave-shell-use-dedicated-frame}. - -To launch a quick IDLWAVE shell directly from a shell prompt without -an IDLWAVE buffer (e.g., as a replacement for running inside an -xterm), define a system alias with the following content: - -@example -emacs -geometry 80x32 -eval "(idlwave-shell 'quick)" -@end example - -Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer -the Emacs process to run directly inside the terminal window. - -@cindex ENVI -@cindex IDL> Prompt - -To use IDLWAVE with ENVI or other custom packages which change the -@samp{IDL> } prompt, you must change the -@code{idlwave-shell-prompt-pattern}, which defaults to @samp{"^ ?IDL> -"}. Normally, you can just replace the @samp{IDL} in this expression -with the prompt you see. A suitable pattern which matches the prompt -for both ENVI and IDL simultaneously is @samp{"^ ?\\(ENVI\\|IDL\\)> "}. - -@defopt idlwave-shell-explicit-file-name (@file{idl}) -This is the command to run IDL. -@end defopt - -@defopt idlwave-shell-command-line-options -A list of command line options for calling the IDL program. -@end defopt - -@defopt idlwave-shell-prompt-pattern -Regexp to match IDL prompt at beginning of a line. -@end defopt - -@defopt idlwave-shell-process-name -Name to be associated with the IDL process. -@end defopt - -@defopt idlwave-shell-automatic-start (@code{nil}) -Non-@code{nil} means attempt to invoke idlwave-shell if not already -running. -@end defopt - -@defopt idlwave-shell-initial-commands -Initial commands, separated by newlines, to send to IDL. -@end defopt - -@defopt idlwave-shell-save-command-history (@code{t}) -Non-@code{nil} means preserve command history between sessions. -@end defopt - -@defopt idlwave-shell-command-history-file (@file{~/.idlwave/.idlwhist}) -The file in which the command history of the idlwave shell is saved. -Unless it's an absolute path, it goes in -@code{idlwave-config-directory}. -@end defopt - -@defopt idlwave-shell-use-dedicated-frame (@code{nil}) -Non-@code{nil} means IDLWAVE should use a special frame to display the -shell buffer. -@end defopt - -@defopt idlwave-shell-use-dedicated-window (@code{nil}) -Non-@code{nil} means use a dedicated window for the shell, taking care -not it replace it with other buffers. -@end defopt - -@defopt idlwave-shell-frame-parameters -The frame parameters for a dedicated idlwave-shell frame. -@end defopt - -@defopt idlwave-shell-raise-frame (@code{t}) -Non-@code{nil} means `idlwave-shell' raises the frame showing the shell -window. -@end defopt - -@defopt idlwave-shell-temp-pro-prefix -The prefix for temporary IDL files used when compiling regions. -@end defopt - -@cindex Hooks -@defopt idlwave-shell-mode-hook -Hook for customizing @code{idlwave-shell-mode}. -@end defopt - -@node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell -@section Using the Shell -@cindex Comint -@cindex Shell, basic commands - -The IDLWAVE shell works in the same fashion as other shell modes in -Emacs. It provides command history, command line editing and job -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}.}. The history is preserved -between emacs and IDL sessions. Here is a list of commonly used -commands: - -@multitable @columnfractions .12 .88 -@item @key{UP}, @key{M-p} -@tab Cycle backwards in input history -@item @key{DOWN}, @key{M-n} -@tab Cycle forwards in input history -@item @kbd{M-r} -@tab Previous input matching a regexp -@item @kbd{M-s} -@tab Next input matching a regexp -@item @kbd{return} -@tab Send input or copy line to current prompt -@item @kbd{C-c C-a} -@tab Beginning of line; skip prompt -@item @kbd{C-c C-u} -@tab Kill input to beginning of line -@item @kbd{C-c C-w} -@tab Kill word before cursor -@item @kbd{C-c C-c} -@tab Send ^C -@item @kbd{C-c C-z} -@tab Send ^Z -@item @kbd{C-c C-\} -@tab Send ^\ -@item @kbd{C-c C-o} -@tab Delete last batch of process output -@item @kbd{C-c C-r} -@tab Show last batch of process output -@item @kbd{C-c C-l} -@tab List input history -@end multitable - -In addition to these standard @file{comint} commands, -@code{idlwave-shell-mode} provides many of the same commands which -simplify writing IDL code available in IDLWAVE buffers. This includes -abbreviations, online help, and completion. See @ref{Routine Info} and -@ref{Online Help} and @ref{Completion} for more information on these -commands. - -@cindex Completion, in the shell -@cindex Routine info, in the shell -@cindex Online Help, in the shell -@multitable @columnfractions .12 .88 -@item @kbd{@key{TAB}} -@tab Completion of file names (between quotes and after executive -commands @samp{.run} and @samp{.compile}), routine names, class names, -keywords, system variables, system variable tags etc. -(@code{idlwave-shell-complete}). -@item @kbd{M-@key{TAB}} -@tab Same as @key{TAB} -@item @kbd{C-c ?} -@tab Routine Info display (@code{idlwave-routine-info}) -@item @kbd{M-?} -@tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp}) -@item @kbd{C-c C-i} -@tab Update routine info from buffers and shell -(@code{idlwave-update-routine-info}) -@item @kbd{C-c C-v} -@tab Find the source file of a routine (@code{idlwave-find-module}) -@item @kbd{C-c C-t} -@tab Find the source file of a routine in the currently visited file -(@code{idlwave-find-module-this-file}). -@item @kbd{C-c =} -@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-comint-settings -Alist of special settings for the comint variables in the IDLWAVE Shell. -@end defopt - -@defopt idlwave-shell-file-name-chars -The characters allowed in file names, as a string. Used for file name -completion. -@end defopt - -@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) -@cindex Magic spells, for input mode -@cindex Spells, magic -IDLWAVE works in line input mode: You compose a full command line, using -all the power Emacs gives you to do this. When you press @key{RET}, the -whole line is sent to IDL. Sometimes it is necessary to send single -characters (without a newline), for example when an IDL program is -waiting for single character input with the @code{GET_KBRD} function. -You can send a single character to IDL with the command @kbd{C-c C-x} -(@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y} -(@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop -which accepts characters and immediately sends them to IDL. The loop -can be exited with @kbd{C-g}. It terminates also automatically when the -current IDL command is finished. Check the documentation of the two -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-@code{nil} means IDLWAVE should check for input mode spells in -output. -@end defopt - -@defopt idlwave-shell-input-mode-spells -The three regular expressions which match the magic spells for input -modes. -@end defopt - -@node Commands Sent to the Shell, Debugging IDL Programs, Using the Shell, The IDLWAVE Shell -@section Commands Sent to the Shell -@cindex Commands in shell, showing -@cindex Showing commands in shell - -The IDLWAVE buffers and shell interact very closely. In addition to the -normal commands you enter at the @code{IDL>} prompt, many other special -commands are sent to the shell, sometimes as a direct result of invoking -a key command, menu item, or toolbar button, but also automatically, as -part of the normal flow of information updates between the buffer and -shell. - -The commands sent include @code{breakpoint}, @code{.step} and other -debug commands (@pxref{Debugging IDL Programs}), @code{.run} and other -compilation statements (@pxref{Compiling Programs}), examination -commands like @code{print} and @code{help} (@pxref{Examining -Variables}), and other special purpose commands designed to keep -information on the running shell current. - -By default, much of this background shell input and output is hidden -from the user, but this is configurable. The custom variable -@code{idlwave-abbrev-show-commands} allows you to configure which -commands sent to the shell are shown there. For a related customization -for separating the output of @emph{examine} commands, see @ref{Examining -Variables}. - -@defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)}) -A list of command types to echo in the shell when sent. Possible values -are @code{run} for @code{.run}, @code{.compile} and other run commands, -@code{misc} for lesser used commands like @code{window}, -@code{retall},@code{close}, etc., @code{breakpoint} for breakpoint -setting and clearing commands, and @code{debug} for other debug, -stepping, and continue commands. In addition, if the variable is set to -the single symbol @code{'everything}, all the copious shell input is -displayed (which is probably only useful for debugging purposes). -N.B. For hidden commands which produce output by side-effect, that -output remains hidden (e.g., stepping through a @code{print} command). -As a special case, any error message in the output will be displayed -(e.g., stepping to an error). -@end defopt - -@node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell -@section Debugging IDL Programs -@cindex Debugging -@cindex Keybindings for debugging -@cindex Toolbar - -Programs can be compiled, run, and debugged directly from the source -buffer in Emacs, walking through arbitrarily deeply nested code, -printing expressions and skipping up and down the calling stack along -the way. IDLWAVE makes compiling and debugging IDL programs far less -cumbersome by providing a full-featured, key/menu/toolbar-driven -interface to commands like @code{breakpoint}, @code{.step}, -@code{.run}, etc. It can even perform complex debug operations not -natively supported by IDL (like continuing to the line at the cursor). - -The IDLWAVE shell installs key bindings both in the shell buffer and -in all IDL code buffers of the current Emacs session, so debug -commands work in both places (in the shell, commands operate on the -last file compiled). On Emacs versions which support it, a debugging -toolbar is also installed. The toolbar display can be toggled with -@kbd{C-c C-d C-t} (@code{idlwave-shell-toggle-toolbar}). - - -@defopt idlwave-shell-use-toolbar (@code{t}) -Non-@code{nil} means use the debugging toolbar in all IDL related -buffers. -@end defopt - -@menu -* A Tale of Two Modes:: -* Debug Key Bindings:: -* Breakpoints and Stepping:: -* Compiling Programs:: -* Walking the Calling Stack:: -* Electric Debug Mode:: -@end menu - - -@node A Tale of Two Modes, Debug Key Bindings, Debugging IDL Programs, Debugging IDL Programs -@subsection A Tale of Two Modes -@cindex Electric Debug Mode -@cindex Debugging Interface - -The many debugging, compiling, and examination commands provided in -IDLWAVE are available simultaneously through two different interfaces: -the original, multi-key command interface, and the new Electric Debug -Mode. The functionality they offer is similar, but the way you interact -with them is quite different. The main difference is that, in Electric -Debug Mode, the source buffers are made read-only, and single -key-strokes are used to step through, examine expressions, set and -remove breakpoints, etc. The same variables, prefix arguments, and -settings apply to both versions, and both can be used interchangeably. -By default, when breakpoints are hit, Electric Debug Mode is enabled. -The traditional interface is described first. @xref{Electric Debug -Mode}, for more on that mode. Note that electric debug mode can be -prevented from activating automatically by customizing the variable -@code{idlwave-shell-automatic-electric-debug}. - -@node Debug Key Bindings, Breakpoints and Stepping, A Tale of Two Modes, Debugging IDL Programs -@subsection Debug Key Bindings -@kindex C-c C-d -@cindex Key bindings - -The standard debugging key bindings are always available 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}, and compiling a source file with @kbd{C-c -C-d C-c}. You can also easily configure IDLWAVE to use one or more -modifier keys not in use by other commands, in lieu of the prefix -@kbd{C-c C-d} (though these bindings will typically also be available ---- see @code{idlwave-shell-activate-prefix-keybindings}). For -example, if you include in @file{.emacs}: - -@lisp -(setq idlwave-shell-debug-modifiers '(control shift)) -@end lisp - -@noindent a breakpoint can then 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 shortcut if modifiers are given in the -@code{idlwave-shell-debug-modifiers} variable (@pxref{Lesson II -- -Customization}). A much simpler and faster form of debugging for -running code is also available by default --- see @ref{Electric Debug -Mode}. - -@defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) -The prefix key for the debugging map -@code{idlwave-shell-mode-prefix-map}. -@end defopt - -@defopt idlwave-shell-activate-prefix-keybindings (@code{t}) -Non-@code{nil} means debug commands will be bound to the prefix -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 additional, alternative binding of -debugging commands in the shell and source buffers. Can be one or -more of @code{control}, @code{meta}, @code{super}, @code{hyper}, -@code{alt}, and @code{shift}. -@end defopt - -@node Breakpoints and Stepping, Compiling Programs, Debug Key Bindings, Debugging IDL Programs -@subsection Breakpoints and Stepping -@cindex Breakpoints -@cindex Stepping -@cindex Execution, controlled - -@kindex C-c C-d C-b -@kindex C-c C-d C-b -IDLWAVE helps you set breakpoints and step through code. Setting a -breakpoint in the current line of the source buffer is accomplished -with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a -prefix arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a -@code{/ONCE} keyword, meaning that it will be deleted after first use. -With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), -the breakpoint will only be active the @code{nth} time it is hit. -With a single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt -for a condition --- an IDL expression to be evaluated and trigger the -breakpoint only if true. To clear the breakpoint in the current line, -use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When -executed from the shell window, the breakpoint where IDL is currently -stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d -C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled -and re-enabled: @kbd{C-c C-d C-\} -(@code{idlwave-shell-toggle-enable-current-bp}). - -Breakpoint lines are highlighted or indicated with an icon in the source -code (different icons for conditional, after, and other break types). -Disabled breakpoints are @emph{grayed out} by default. Note that IDL -places breakpoints as close as possible on or after the line you -specify. IDLWAVE queries the shell for the actual breakpoint location -which was set, so the exact line you specify may not be marked. You can -re-sync the breakpoint list and update the display at any time (e.g., if -you add or remove some on the command line) using @kbd{C-c C-d C-l}. - -In recent IDLWAVE versions, the breakpoint line is highlighted when the -mouse is moved over it, and a tooltip pops up describing the break -details. @kbd{Mouse-3} on the breakpoint line pops up a menu of -breakpoint actions, including clearing, disabling, and adding or -changing break conditions or ``after'' break count. - -Once the program has stopped somewhere, you can step through it. The -most important stepping commands are @kbd{C-c C-d C-s} to execute one -line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line, -treating procedure and function calls as a single step ("step over"); -@kbd{C-c C-d C-h} to continue execution to the line at the cursor and -@kbd{C-c C-d C-r} to continue execution. @xref{Commands Sent to the -Shell}, for information on displaying or hiding the breakpoint and -stepping commands the shell receives. Here is a summary of the -breakpoint and stepping commands: - -@multitable @columnfractions .23 .77 -@item @kbd{C-c C-d C-b} -@tab Set breakpoint (@code{idlwave-shell-break-here}) -@item @kbd{C-c C-d C-i} -@tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) -@item @kbd{C-c C-d C-d} -@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) -@item @kbd{C-c C-d C-a} -@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) -@item @kbd{C-c C-d [} -@tab Go to the previous breakpoint (@code{idlwave-shell-goto-previous-bp}) -@item @kbd{C-c C-d ]} -@tab Go to the next breakpoint (@code{idlwave-shell-goto-next-bp}) -@item @kbd{C-c C-d C-\} -@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) -@item @kbd{C-c C-d C-j} -@tab Set a breakpoint at the beginning of the enclosing routine. -@item @kbd{C-c C-d C-s} -@tab Step, into function calls (@code{idlwave-shell-step}) -@item @kbd{C-c C-d C-n} -@tab Step, over function calls (@code{idlwave-shell-stepover}) -@item @kbd{C-c C-d C-k} -@tab Skip one statement (@code{idlwave-shell-skip}) -@item @kbd{C-c C-d C-u} -@tab Continue to end of block (@code{idlwave-shell-up}) -@item @kbd{C-c C-d C-m} -@tab Continue to end of function (@code{idlwave-shell-return}) -@item @kbd{C-c C-d C-o} -@tab Continue past end of function (@code{idlwave-shell-out}) -@item @kbd{C-c C-d C-h} -@tab Continue to line at cursor position (@code{idlwave-shell-to-here}) -@item @kbd{C-c C-d C-r} -@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) -@item @kbd{C-c C-d C-up} -@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) -@item @kbd{C-c C-d C-down} -@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) -@end multitable - -All of these commands have equivalents in Electric Debug Mode, which -provides faster single-key access (@pxref{Electric Debug Mode}). - -The line where IDL is currently stopped, at breakpoints, halts, and -errors, etc., is marked with a color overlay or arrow, depending on the -setting in @code{idlwave-shell-mark-stop-line}. If an overlay face is -used to mark the stop line (as it is by default), when stepping through -code, the face color is temporarily changed to gray, until IDL completes -the next command and moves to the new line. - -@defopt idlwave-shell-mark-breakpoints (@code{t}) -Non-@code{nil} means mark breakpoints in the source file buffers. The -value indicates the preferred method. Valid values are @code{nil}, -@code{t}, @code{face}, and @code{glyph}. -@end defopt - -@defopt idlwave-shell-breakpoint-face -The face for breakpoint lines in the source code if -@code{idlwave-shell-mark-breakpoints} has the value @code{face}. -@end defopt - -@defopt idlwave-shell-breakpoint-popup-menu (@code{t}) -Whether to pop-up a menu and present a tooltip description on -breakpoint lines. -@end defopt - -@defopt idlwave-shell-mark-stop-line (@code{t}) -Non-@code{nil} means mark the source code line where IDL is currently -stopped. The value specifies the preferred method. Valid values are -@code{nil}, @code{t}, @code{arrow}, and @code{face}. -@end defopt - -@defopt idlwave-shell-overlay-arrow (@code{">"}) -The overlay arrow to display at source lines where execution halts, if -configured in @code{idlwave-shell-mark-stop-line}. -@end defopt - -@defopt idlwave-shell-stop-line-face -The face which highlights the source line where IDL is stopped, if -configured in @code{idlwave-shell-mark-stop-line}. -@end defopt - - -@node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs -@subsection Compiling Programs -@cindex Compiling programs -@cindex Programs, compiling -@cindex Default command line, executing -@cindex Executing a default command line - -@kindex C-c C-d C-c -In order to compile the current buffer under the IDLWAVE shell, press -@kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the -current buffer and then sends the command @samp{.run path/to/file} to the -shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in -which case the most recently compiled buffer will be saved and -re-compiled. - -When developing or debugging a program, it is often necessary to execute -the same command line many times. A convenient way to do this is -@kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}). -This command first resets IDL from a state of interrupted execution by -closing all files and returning to the main interpreter level. Then a -default command line is send to the shell. To edit the default command -line, call @code{idlwave-shell-execute-default-command-line} with a -prefix argument: @kbd{C-u C-c C-d C-y}. If no default command line has -been set (or you give two prefix arguments), the last command on the -@code{comint} input history is sent. - -@kindex C-c C-d C-e -@cindex Compiling regions -For quickly compiling and running the currently marked region as a main -level program @kbd{C-c C-d C-e} (@code{idlwave-shell-run-region}) is -very useful. A temporary file is created holding the contents of the -current region (with @code{END} appended), and run from the shell. - -@node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs -@subsection Walking the Calling Stack -@cindex Calling stack, walking - -While debugging a program, it can be very useful to check the context in -which the current routine was called, for instance to help understand -the value of the arguments passed. To do so conveniently you need to -examine the calling stack. If execution is stopped somewhere deep in a -program, you can use the commands @kbd{C-c C-d C-@key{UP}} -(@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}} -(@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons, -to move up or down through the calling stack. The mode line of the -shell window will indicate the position within the stack with a label -like @samp{[-3:MYPRO]}. The line of IDL code at that stack position -will be highlighted. If you continue execution, IDLWAVE will -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. - -@html -<A NAME="EDEBUG"></A> -@end html -@node Electric Debug Mode, , Walking the Calling Stack, Debugging IDL Programs -@subsection Electric Debug Mode -@cindex Electric Debug Mode -@cindex @samp{*Debugging*} - -Even with a convenient debug key prefix enabled, repetitive stepping, -variable examination (@pxref{Examining Variables}), and other debugging -activities can be awkward and slow using commands which require multiple -keystrokes. Luckily, there's a better way, inspired by the lisp e-debug -mode, and available through the @emph{Electric Debug Mode}. By default, -as soon as a breakpoint is hit, this minor mode is enabled. The buffer -showing the line where execution has halted is switched to Electric -Debug Mode. This mode is visible as @samp{*Debugging*} in the mode -line, and a different face (violet by default, if color is available) -for the line stopped at point. The buffer is made read-only and -single-character bindings for the most commonly used debugging commands -are enabled. These character commands (a list of which is available -with @kbd{C-?}) are: - -@multitable @columnfractions .2 .8 -@item @kbd{a} -@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) -@item @kbd{b} -@tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here}) -@item @kbd{d} -@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) -@item @kbd{e} -@tab Prompt for expression to print (@code{idlwave-shell-clear-current-bp}). -@item @kbd{h} -@tab Continue to the line at cursor position (@code{idlwave-shell-to-here}) -@item @kbd{i} -@tab Set breakpoint in module named here (@code{idlwave-shell-break-in}) -@item @kbd{[} -@tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp}) -@item @kbd{]} -@tab Go to the next breakpoint in the file -(@code{idlwave-shell-goto-next-bp}) -@item @kbd{\} -@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) -@item @kbd{j} -@tab Set breakpoint at beginning of enclosing routine (@code{idlwave-shell-break-this-module}) -@item @kbd{k} -@tab Skip one statement (@code{idlwave-shell-skip}) -@item @kbd{m} -@tab Continue to end of function (@code{idlwave-shell-return}) -@item @kbd{n} -@tab Step, over function calls (@code{idlwave-shell-stepover}) -@item @kbd{o} -@tab Continue past end of function (@code{idlwave-shell-out}) -@item @kbd{p} -@tab Print expression near point or in region with @kbd{C-u p} (@code{idlwave-shell-print}) -@item @kbd{q} -@tab End the debugging session and return to the Shell's main level -(@code{idlwave-shell-retall}) -@item @kbd{r} -@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) -@item @kbd{s} or @kbd{@key{SPACE}} -@tab Step, into function calls (@code{idlwave-shell-step}) -@item @kbd{t} -@tab Print a calling-level traceback in the shell -@item @kbd{u} -@tab Continue to end of block (@code{idlwave-shell-up}) -@item @kbd{v} -@tab Turn Electric Debug Mode off -(@code{idlwave-shell-electric-debug-mode}) -@item @kbd{x} -@tab Examine expression near point (or in region with @kbd{C-u x}) -with shortcut of examine type. -@item @kbd{z} -@tab Reset IDL (@code{idlwave-shell-reset}) -@item @kbd{+} or @kbd{=} -@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) -@item @kbd{-} or @kbd{_} -@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) -@item @kbd{?} -@tab Help on expression near point or in region with @kbd{C-u ?} -(@code{idlwave-shell-help-expression}) -@item @kbd{C-?} -@tab Show help on the commands available. -@end multitable - -Most single-character electric debug bindings use the final keystroke -of the equivalent multiple key commands (which are of course also -still available), but some differ (e.g. @kbd{e},@kbd{t},@kbd{q},@kbd{x}). -Some have additional convenience bindings (like @kbd{@key{SPACE}} for -stepping). All prefix and other argument options described in this -section for the commands invoked by electric debug bindings are still -valid. For example, @kbd{C-u b} sets a conditional breakpoint, just -as it did with @kbd{C-u C-c C-d C-b}. - -You can toggle the electric debug mode at any time in a buffer using -@kbd{C-c C-d C-v} (@kbd{v} to turn it off while in the mode), or from -the Debug menu. Normally the mode will be enabled and disabled at the -appropriate times, but occasionally you might want to edit a file -while still debugging it, or switch to the mode for conveniently -setting lots of breakpoints. - -To quickly abandon a debugging session and return to normal editing at -the Shell's main level, use @kbd{q} (@code{idlwave-shell-retall}). -This disables electric debug mode in all IDLWAVE buffers@footnote{Note -that this binding is not symmetric: @kbd{C-c C-d C-q} is bound to -@code{idlwave-shell-quit}, which quits your IDL session.}. Help is -available for the command shortcuts with @kbd{C-?}. If you find this -mode gets in your way, you can keep it from automatically activating -by setting the variable @code{idlwave-shell-automatic-electric-debug} -to @code{nil}, or @code{'breakpoint}. If you'd like the convenient -electric debug shortcuts available also when run-time errors are -encountered, set to @code{t}. - -@defopt idlwave-shell-automatic-electric-debug (@code{'breakpoint}) -Whether to enter electric debug mode automatically when a breakpoint -or run-time error is encountered, and then disable it in all buffers -when the $MAIN$ level is reached (either through normal program -execution, or retall). In addition to @code{nil} for never, and -@code{t} for both breakpoints and errors, this can be -@code{'breakpoint} (the default) to enable it only at breakpoint -halts. -@end defopt - -@defopt idlwave-shell-electric-stop-color (Violet) -Default color of the stopped line overlay when in electric debug mode. -@end defopt - -@defopt idlwave-shell-electric-stop-line-face -The face to use for the stopped line. Defaults to a face similar to the -modeline, with color @code{idlwave-shell-electric-stop-color}. -@end defopt - -@defopt idlwave-shell-electric-zap-to-file (@code{t}) -If set, when entering electric debug mode, select the window displaying -the file where point is stopped. This takes point away from the shell -window, but is useful for immediate stepping, etc. -@end defopt - -@html -<A NAME="EXAMINE"></A> -@end html -@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 & help -@cindex Examining expressions -@cindex Printing expressions -@cindex Mouse binding to print expressions - -@kindex C-c C-d C-p -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 variable or expression examinations. They work -by sending statements to the shell formatted to include the indicated -expression, and can be accessed in several ways. - -These @emph{examine} 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 constituents 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. - -If the variable @code{idlwave-shell-separate-examine-output} is -non-@code{nil} (the default), all examine output will be sent to a -special @file{*Examine*} buffer, rather than the shell. The output of -prior examine commands is saved in this buffer. In this buffer @key{c} -clears the contents, and @key{q} hides the buffer. - -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@footnote{Available as @kbd{p} and @kbd{?} in Electric -Debug Mode (@pxref{Electric Debug Mode})}. The expression at point is -either an array expression or a function call, or the contents of a pair -of parentheses. The chosen expression is highlighted, and -simultaneously the resulting output is highlighted in the shell or -separate output buffer. Calling the above commands with a prefix -argument will use the current region as expression instead of using the -one at point. which can be useful for examining complicated, multi-line -expressions. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will -prompt for an expression to print directly. By default, when invoking -print, only an initial portion of long arrays will be printed, up to -@code{idlwave-shell-max-print-length}. - -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{META} 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 the specific expression or sub-expression you want to examine. -For custom expression examination, and the powerful customizable -pop-up examine selection, @xref{Custom Expression Examination}. - -@cindex Printing expressions, on calling stack -@cindex Restrictions for expression printing -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 -Array expressions must use the @samp{[ ]} index delimiters. Identifiers -with a @samp{( )} will be interpreted as function calls. -@item -@cindex ROUTINE_NAMES, IDL procedure -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. Caveat -Examinor. -@end itemize - -@defopt idlwave-shell-expression-face -The face for @code{idlwave-shell-expression-overlay}. -Allows you to choose the font, color and other properties for -the expression printed by IDL. -@end defopt - -@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 -@file{*Examine*} buffer, instead of in the shell itself. -@end defopt - -@defopt idlwave-shell-max-print-length (200) -The maximum number of leading array entries to print, when examining -array expressions. -@end defopt - -@node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell -@section Custom Expression Examination -@cindex Expressions, custom examination -@cindex Custom expression examination - -The variety of possible variable and expression examination commands is -endless (just look, for instance, at the keyword list to -@code{widget_info()}). Rather than attempt to include them all, IDLWAVE -provides two easy methods to customize your own commands, with a special -mouse examine command, and two macros for generating your own examine -key and mouse bindings. - -The most powerful and flexible mouse examine command of all is -available on @kbd{C-S-Mouse-2}. Just as for all the other mouse -examine commands, it permits click or drag expression selection, but -instead of sending hard-coded commands 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@footnote{In Electric Debug Mode (@pxref{Electric Debug -Mode}), the key @kbd{x} provides a single-character shortcut interface -to the same examine functions for the expression at point or marked by -the region.}. This variable is a list of key-value pairs (an -@emph{alist} in Emacs parlance), where the key gives a name to be -shown for the examine command, and the value is the command strings -itself, in which the text @code{___} (three underscores) will be -replaced by the selected expression before being sent to the shell. -An example might be key @code{Structure Help} with value -@code{help,___,/STRUCTURE}. In that case, you'd be prompted with -@emph{Structure Help}, which might send something like -@code{help,var,/STRUCTURE} to the shell for output. -@code{idlwave-shell-examine-alist} comes configured by default with a -large list of examine commands, but you can easily customize it to add -your own. - -In addition to configuring the functions available to the pop-up mouse -command, you can easily create your own customized bindings to inspect -expressions using the two convenience macros -@code{idlwave-shell-examine} and @code{idlwave-shell-mouse-examine}. -These create keyboard or mouse-based custom inspections of variables, -sharing all the same properties of the built-in examine commands. -Both functions take a single string argument sharing the syntax of the -@code{idlwave-shell-examine-alist} values, 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. - -@defopt idlwave-shell-examine-alist -An alist of examine commands in which the keys name the command and -are displayed in the selection pop-up, and the values are custom IDL -examine command strings to send, after all instances of @code{___} -(three underscores) are replaced by the indicated expression. -@end defopt - -@node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top -@chapter Acknowledgements -@cindex Acknowledgements -@cindex Maintainer, of IDLWAVE -@cindex Authors, of IDLWAVE -@cindex Contributors, to IDLWAVE -@cindex Email address, of Maintainer -@cindex Thanks - -@noindent -The main contributors to the IDLWAVE package have been: - -@itemize @minus -@item -@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}} was in charge -of the package from version 3.0, during which time he overhauled almost -everything, modernized IDLWAVE with many new features, and developed the -manual. - -@item -@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, and introduced many -new features for IDLWAVE versions 5.x and 6.x. -@end itemize - -@noindent -The following people have also contributed to the development of IDLWAVE -with patches, ideas, bug reports and suggestions. - -@itemize @minus -@item -Ulrik Dickow <dickow__at__nbi.dk> -@item -Eric E. Dors <edors__at__lanl.gov> -@item -Stein Vidar H. Haugan <s.v.h.haugan__at__astro.uio.no> -@item -David Huenemoerder <dph__at__space.mit.edu> -@item -Kevin Ivory <Kevin.Ivory__at__linmpi.mpg.de> -@item -Dick Jackson <dick__at__d-jackson.com> -@item -Xuyong Liu <liu__at__stsci.edu> -@item -Simon Marshall <Simon.Marshall__at__esrin.esa.it> -@item -Craig Markwardt <craigm__at__cow.physics.wisc.edu> -@item -Laurent Mugnier <mugnier__at__onera.fr> -@item -Lubos Pochman <lubos__at__rsinc.com> -@item -Bob Portmann <portmann__at__al.noaa.gov> -@item -Patrick M. Ryan <pat__at__jaameri.gsfc.nasa.gov> -@item -Marty Ryba <ryba__at__ll.mit.edu> -@item -Phil Williams <williams__at__irc.chmcc.org> -@item -Phil Sterne <sterne__at__dublin.llnl.gov> -@item -Paul Sorenson <aardvark62__at__msn.com> -@end itemize - -Doug Dirks was instrumental in providing the crucial IDL XML catalog to -support HTML help with IDL v6.2 and later, and Ali Bahrami provided -scripts and documentation to interface with the IDL Assistant. - -@noindent -Thanks to everyone! - -@node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top -@appendix Sources of Routine Info - -@cindex Sources of routine information -In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE -displays the calling sequence and keywords of routines, and completes -routine names and keywords. For these features to work, IDLWAVE must -know about the accessible routines. - -@menu -* Routine Definitions:: Where IDL Routines are defined. -* Routine Information Sources:: So how does IDLWAVE know about... -* Catalogs:: -* Load-Path Shadows:: Routines defined in several places -* Documentation Scan:: Scanning the IDL Manuals -@end menu - -@node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info -@appendixsec Routine Definitions -@cindex Routine definitions -@cindex IDL variable @code{!PATH} -@cindex @code{!PATH}, IDL variable -@cindex @code{CALL_EXTERNAL}, IDL routine -@cindex @code{LINKIMAGE}, IDL routine -@cindex External routines - -@noindent Routines which can be used in an IDL program can be defined in -several places: - -@enumerate -@item -@emph{Builtin routines} are defined inside IDL itself. The source code -of such routines is not available, but instead are learned about through -the IDL documentation. -@item -Routines which are @emph{part of the current program}, are defined in a -file explicitly compiled by the user. This file may or may not be -located on the IDL search path. -@item -@emph{Library routines} are defined in files located on IDL's search -path. When a library routine is called for the first time, IDL will -find the source file and compile it dynamically. A special sub-category -of library routines are the @emph{system routines} distributed with IDL, -and usually available in the @file{lib} subdirectory of the IDL -distribution. -@item -External routines written in other languages (like Fortran or C) can be -called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, -or included as dynamically loaded modules (DLMs). Currently IDLWAVE -cannot provide routine info and completion for such external routines, -except by querying the Shell for calling information (DLMs only). -@end enumerate - -@node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info -@appendixsec Routine Information Sources -@cindex Routine info sources -@cindex Builtin list of routines -@cindex Updating routine info -@cindex Scanning buffers for routine info -@cindex Buffers, scanning for routine info -@cindex Shell, querying for routine info - -@noindent To maintain the most comprehensive information about all IDL -routines on a system, IDLWAVE collects data from many sources: - -@enumerate - -@item -It has a @emph{builtin list} with information about the routines IDL -ships with. IDLWAVE @value{VERSION} is distributed with a list of -@value{NSYSROUTINES} routines and object methods, reflecting IDL version -@value{IDLVERSION}. As of IDL v6.2, the routine info is distributed -directly with IDL in the form of an XML catalog which IDLWAVE scans. -Formerly, this list was created by scanning the IDL manuals to produce -the file @file{idlw-rinfo.el}. - -@item -IDLWAVE @emph{scans} all its @emph{buffers} in the current Emacs session -for routine definitions. This is done automatically when routine -information or completion is first requested by the user. Each new -buffer and each buffer saved after making changes is also scanned. The -command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used -at any time to rescan all buffers. - -@item -If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will -@emph{query the shell} for compiled routines and their arguments. This -happens automatically when routine information or completion is first -requested by the user. Each time an Emacs buffer is compiled with -@kbd{C-c C-d C-c}, the routine info for that file is queried. Though -rarely necessary, the command @kbd{C-c C-i} -(@code{idlwave-update-routine-info}) can be used to explicitly update -the shell routine data. - -@item -Many popular libraries are distributed with routine information already -scanned into @emph{library catalogs} (@pxref{Library Catalogs}). These -per-directory catalog files can also be built by the user with the -supplied @file{idlwave_catalog} tool. They are automatically discovered -by IDLWAVE. - -@item -IDLWAVE can scan selected directories of source files and store the -result in a single @emph{user catalog} file which will be -automatically loaded just like @file{idlw-rinfo.el}. @xref{User -Catalog}, for information on how to scan files in this way. -@end enumerate - -Loading all the routine and catalog information can be a time consuming -process, especially over slow networks. Depending on the system and -network configuration it could take up to 30 seconds (though locally on -fast systems is usually only a few seconds). In order to minimize the -wait time upon your first completion or routine info command in a -session, IDLWAVE uses Emacs idle time to do the initialization in six -steps, yielding to user input in between. If this gets into your way, -set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero). -The more routines documented in library and user catalogs, the slower -the loading will be, so reducing this number can help alleviate any long -load times. - -@defopt idlwave-init-rinfo-when-idle-after (@code{10}) -Seconds of idle time before routine info is automatically initialized. -@end defopt - -@defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) -Non-@code{nil} means scan all buffers for IDL programs when updating -info. -@end defopt - -@defopt idlwave-query-shell-for-routine-info (@code{t}) -Non-@code{nil} means query the shell for info about compiled routines. -@end defopt - -@defopt idlwave-auto-routine-info-updates -Controls under what circumstances routine info is updated automatically. -@end defopt - -@html -<A NAME="CATALOGS"></A> -@end html -@node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info -@appendixsec Catalogs -@cindex Catalogs - -@emph{Catalogs} are files containing scanned information on individual -routines, including arguments and keywords, calling sequence, file path, -class and procedure vs. function type, etc. They represent a way of -extending the internal built-in information available for IDL system -routines (@pxref{Routine Info}) to other source collections. - -Starting with version 5.0, there are two types of catalogs available -with IDLWAVE. The traditional @emph{user catalog} and the newer -@emph{library catalogs}. Although they can be used interchangeably, the -library catalogs are more flexible, and preferred. There are few -occasions when a user catalog might be preferred --- read below. Both -types of catalogs can coexist without causing problems. - -To facilitate the catalog systems, IDLWAVE stores information it gathers -from the shell about the IDL search paths, and can write this -information out automatically, or on-demand (menu @code{Debug->Save Path -Info}). On systems with no shell from which to discover the path -information (e.g. Windows), a library path must be specified in -@code{idlwave-library-path} to allow library catalogs to be located, and -to setup directories for user catalog scan (@pxref{User Catalog} for -more on this variable). Note that, before the shell is running, IDLWAVE -can only know about the IDL search path by consulting the file pointed -to by @code{idlwave-path-file} (@file{~/.idlwave/idlpath.el}, by -default). If @code{idlwave-auto-write-path} is enabled (which is the -default), the paths are written out whenever the IDLWAVE shell is -started. - -@defopt idlwave-auto-write-path (@code{t}) -Write out information on the !PATH and !DIR paths from IDL automatically -when they change and when the Shell is closed. These paths are needed -to locate library catalogs. -@end defopt - -@defopt idlwave-library-path -IDL library path for Windows and MacOS. Under Unix/MacOSX, will be -obtained from the Shell when run. -@end defopt - -@defopt idlwave-system-directory -The IDL system directory for Windows and MacOS. Also needed for -locating HTML help and the IDL Assistant for IDL v6.2 and later. Under -Unix/MacOSX, will be obtained from the Shell and recorded, if run. -@end defopt - -@defopt idlwave-config-directory (@file{~/.idlwave}) -Default path where IDLWAVE saves configuration information, a user -catalog (if any), and a cached scan of the XML catalog (IDL v6.2 and -later). -@end defopt - -@menu -* Library Catalogs:: -* User Catalog:: -@end menu - -@html -<A NAME="LIBRARY_CATALOGS"></A> -@end html -@node Library Catalogs, User Catalog, Catalogs, Catalogs -@appendixsubsec Library Catalogs -@cindex @file{.idlwave_catalog} -@cindex Library catalogs -@cindex @code{idlwave_catalog} - -Library catalogs consist of files named @file{.idlwave_catalog} stored -in directories containing @code{.pro} routine files. They are -discovered on the IDL search path and loaded automatically when routine -information is read. Each catalog file documents the routines found in -that directory --- one catalog per directory. Every catalog has a -library name associated with it (e.g. @emph{AstroLib}). This name will -be shown briefly when the catalog is found, and in the routine info of -routines it documents. - -Many popular libraries of routines are shipped with IDLWAVE catalog -files by default, and so will be automatically discovered. Library -catalogs are scanned externally to Emacs using a tool provided with -IDLWAVE. Each catalog can be re-scanned independently of any other. -Catalogs can easily be made available system-wide with a common source -repository, providing uniform routine information, and lifting the -burden of scanning from the user (who may not even know they're using a -scanned catalog). Since all catalogs are independent, they can be -re-scanned automatically to gather updates, e.g. in a @file{cron} job. -Scanning is much faster than with the built-in user catalog method. One -minor disadvantage: the entire IDL search path is scanned for catalog -files every time IDLWAVE starts up, which might be slow if accessing IDL -routines over a slow network. - -A Perl tool to create library catalogs is distributed with IDLWAVE: -@code{idlwave_catalog}. It can be called quite simply: -@example -idlwave_catalog MyLib -@end example - -@noindent This will scan all directories recursively beneath the current and -populate them with @file{.idlwave_catalog} files, tagging the routines -found there with the name library ``MyLib''. The full usage -information: - -@example -Usage: idlwave_catalog [-l] [-v] [-d] [-s] [-f] [-h] libname - libname - Unique name of the catalog (4 or more alphanumeric - characters). - -l - Scan local directory only, otherwise recursively - catalog all directories at or beneath this one. - -v - Print verbose information. - -d - Instead of scanning, delete all .idlwave_catalog files - here or below. - -s - Be silent. - -f - Force overwriting any catalogs found with a different - library name. - -h - Print this usage. -@end example - -To re-load the library catalogs on the IDL path, force a system routine -info update using a single prefix to @code{idlwave-update-routine-info}: -@kbd{C-u C-c C-i}. - -@defopt idlwave-use-library-catalogs (@code{t}) -Whether to search for and load library catalogs. Disable if load -performance is a problem and/or the catalogs are not needed. -@end defopt - -@node User Catalog, , Library Catalogs, Catalogs -@appendixsubsec User Catalog -@cindex User catalog -@cindex IDL library routine info -@cindex Windows -@cindex MacOS -@cindex IDL variable @code{!DIR} -@cindex @code{!DIR}, IDL variable - -The user catalog is the old routine catalog system. It is produced -within Emacs, and stored in a single file in the user's home directory -(@file{.idlwave/idlusercat.el} by default). Although library catalogs -are more flexible, there may be reasons to prefer a user catalog -instead, including: - -@itemize @bullet -@item The scan is internal to Emacs, so you don't need a working Perl -installation, as you do for library catalogs. -@item Can be used to scan directories for which the user has no write -privileges. -@item Easy widget-based path selection. -@end itemize - -However, no routine info is available in the user catalog by default; -the user must actively complete a scan. In addition, this type of -catalog is all or nothing: if a single routine changes, the entire -catalog must be rescanned to update it. Creating the user catalog is -also much slower than scanning library catalogs. - -You can scan any of the directories on the currently known path. Under -Windows and MacOS (not OSX), you need to specify the IDL search path in -the variable @code{idlwave-library-path}, and the location of the IDL -directory (the value of the @code{!DIR} system variable) in the variable -@code{idlwave-system-directory}, like this@footnote{The initial @samp{+} -leads to recursive expansion of the path, just like in IDL}: - -@lisp -(setq idlwave-library-path - '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs")) -(setq idlwave-system-directory "c:/RSI/IDL56/") -@end lisp - -@noindent Under GNU/Linux and UNIX, these values will be automatically -gathered from the IDLWAVE shell, if run. - -The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item -@samp{IDLWAVE->Routine Info->Select Catalog Directories}) can then be -used to create a user catalog. It brings up a widget in which you can -select some or all directories on the search path. Directories which -already contain a library catalog are marked with @samp{[LIB]}, and need -not be scanned (although there is no harm if you do so, other than the -additional memory used for the duplication). - -After selecting directories, click on the @w{@samp{[Scan & Save]}} -button in the widget to scan all files in the selected directories and -write out the resulting routine information. In order to update the -library information using the directory selection, call the command -@code{idlwave-update-routine-info} with a double prefix argument: -@w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously -selected directories, write an updated version of the user catalog file -and rebuild IDLWAVE's internal lists. If you give three prefix -arguments @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a -background job@footnote{Unix systems only, I think.}. You can continue -to work, and the library catalog will be re-read when it is ready. If -you find you need to update the user catalog often, you should consider -building a library catalog for your routines instead (@pxref{Library -Catalogs}). - -@defopt idlwave-special-lib-alist -Alist of regular expressions matching special library directories for -labeling in routine-info display. -@end defopt - -@node Load-Path Shadows, Documentation Scan, Catalogs, Sources of Routine Info -@appendixsec Load-Path Shadows -@cindex Load-path shadows -@cindex Shadows, load-path -@cindex Duplicate routines -@cindex Multiply defined routines -@cindex Routine definitions, multiple -@cindex Application, testing for shadowing -@cindex Buffer, testing for shadowing - -IDLWAVE can compile a list of routines which are (re-)defined in more -than one file. 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 the special buffer -@file{*Shadows*}. The format of the output is identical to the source -section of the routine info buffer (@pxref{Routine Info}). The -different definitions of a routine are ordered by @emph{likelihood 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 (also available in the Menu -@samp{IDLWAVE->Routine Info}): - -@table @asis -@item @kbd{M-x idlwave-list-buffer-load-path-shadows} -This commands checks the names of all routines defined in the current -buffer for shadowing conflicts with other routines accessible to -IDLWAVE. The command also has a key binding: @kbd{C-c C-b} -@item @kbd{M-x idlwave-list-shell-load-path-shadows}. -Checks all routines compiled under the shell for shadowing. This is -very useful when you have written a complete application. Just compile -the application, use @code{RESOLVE_ALL} to compile any routines used by -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 checks all routines accessible to IDLWAVE for conflicts. -@end table - -For these commands to work fully you need to scan the entire load path -in either a user or library catalog. Also, IDLWAVE should be able to -distinguish between the system library files (normally installed in -@file{/usr/local/rsi/idl/lib}) and any site specific or user specific -files. Therefore, such local files should not be installed inside the -@file{lib} directory of the IDL directory. This is also advisable for -many other reasons. - -@cindex Windows -@cindex MacOS -@cindex IDL variable @code{!DIR} -@cindex @code{!DIR}, IDL variable -Users of Windows and MacOS (not X) also must set the variable -@code{idlwave-system-directory} to the value of the @code{!DIR} system -variable in IDL. IDLWAVE appends @file{lib} to the value of this -variable and assumes that all files found on that path are system -routines. - -Another way to find out if a specific routine has multiple definitions -on the load path is routine info display (@pxref{Routine Info}). - -@node Documentation Scan, , Load-Path Shadows, Sources of Routine Info -@appendixsec Documentation Scan -@cindex @file{get_html_rinfo} -@cindex @file{idlw-rinfo.el} -@cindex Scanning the documentation -@cindex Perl program, to create @file{idlw-rinfo.el} - -@strong{Starting with version 6.2, IDL is distributed directly with HTML -online help, and an XML-based catalog of routine information}. This -makes scanning the manuals with the tool @file{get_html_rinfo}, and the -@file{idlw-rinfo.el} file it produced, as described here, entirely -unnecessary. The information is left here for users wishing to produce -a catalog of older IDL versions' help. - - -IDLWAVE derives its knowledge about system routines from the IDL -manuals. The file @file{idlw-rinfo.el} contains the routine information -for the IDL system routines, and links to relevant sections of the HTML -documentation. The Online Help feature of IDLWAVE requires HTML -versions of the IDL manuals to be available; the HTML documentation is -not distributed with IDLWAVE by default, but must be downloaded -separately. - -The HTML files and related images can be produced from the -@file{idl.chm} HTMLHelp file distributed with IDL using the free -Microsoft HTML Help Workshop. If you are lucky, the maintainer of -IDLWAVE will always have access to the newest version of IDL and provide -updates. The IDLWAVE distribution also contains the Perl program -@file{get_html_rinfo} which constructs the @file{idlw-rinfo.el} file by -scanning the HTML documents produced from the IDL documentation. -Instructions on how to use @file{get_html_rinfo} are in the program -itself. - -@node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top -@appendix HTML Help Browser Tips -@cindex Browser Tips - -There are a wide variety of possible browsers to use for displaying -the online HTML help available with IDLWAVE (starting with version -5.0). Since IDL v6.2, a single cross-platform HTML help browser, the -@emph{IDL Assistant} is distributed with IDL. If this help browser is -available, it is the preferred choice, and the default. The variable -@code{idlwave-help-use-assistant}, enabled by default, controls -whether this help browser is used. If you use the IDL Assistant, the -tips here are not relevant. - -Since IDLWAVE runs on a many different system types, a single browser -configuration is not possible, but choices abound. On many systems, -the default browser configured in @code{browse-url-browser-function}, -and hence inherited by default by -@code{idlwave-help-browser-function}, is Netscape. Unfortunately, the -HTML manuals decompiled from the original source contain formatting -structures which Netscape 4.x does not handle well, though they are -still readable. A much better choice is Mozilla, or one of the -Mozilla-derived browsers such as -@uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux), -@uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or -@uref{http://www.mozilla.org/projects/firebird/,Firebird} (all -platforms). Newer versions of Emacs provide a browser-function choice -@code{browse-url-gnome-moz} which uses the Gnome-configured browser. - -Note that the HTML files decompiled from the help sources contain -specific references to the @samp{Symbol} font, which by default is not -permitted in normal encodings (it's invalid, technically). Though it -only impacts a few symbols, you can trick Mozilla-based browsers into -recognizing @samp{Symbol} by following the directions -@uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With -this fix in place, HTML help pages look almost identical to their PDF -equivalents (yet can be bookmarked, browsed as history, searched, -etc.). - -@noindent Individual platform recommendations: - -@itemize @bullet -@item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser -and its associated -@uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode -provide in-buffer browsing with image display, and excellent speed and -formatting. Both the Emacs mode and the browser itself must be -downloaded separately. To use this browser, include - -@lisp -(setq idlwave-help-browser-function 'w3m-browse-url) -@end lisp - -in your @file{.emacs}. Setting a few other nice @code{w3m} options -cuts down on screen clutter: - -@lisp -(setq w3m-use-tab nil - w3m-use-header-line nil - w3m-use-toolbar nil) -@end lisp - -If you use a dedicated frame for help, you might want to add the -following, to get consistent behavior with the @kbd{q} key: - -@lisp -;; Close my help window when w3m closes. -(defadvice w3m-close-window (after idlwave-close activate) - (if (boundp 'idlwave-help-frame) - (idlwave-help-quit))) -@end lisp - -Note that you can open the file in an external browser from within -@code{w3m} using @kbd{M}. -@end itemize - -@node Configuration Examples, Windows and MacOS, HTML Help Browser Tips, Top -@appendix Configuration Examples -@cindex Configuration examples -@cindex Example configuration -@cindex @file{.emacs} -@cindex Default settings, of options -@cindex Interview, with the maintainer - -@noindent -@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:} 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. -@item -are too intrusive. -@item -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 had in his @file{.emacs}: - -@lisp -(setq idlwave-shell-debug-modifiers '(control shift) - idlwave-store-inquired-class t - idlwave-shell-automatic-start t - idlwave-main-block-indent 2 - idlwave-init-rinfo-when-idle-after 2 - idlwave-help-dir "~/lib/emacs/idlwave" - idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib") - ("/jhuapl/" . "JHUAPL-Lib") - ("/dominik/lib/idl/" . "MyLib"))) -@end lisp - -However, if you are an Emacs power-user and want IDLWAVE to work -completely differently, you can change almost every aspect of it. Here -is an example of a much more extensive configuration of IDLWAVE. The -user is King! - -@example -;;; Settings for IDLWAVE mode - -(setq idlwave-block-indent 3) ; Indentation settings -(setq idlwave-main-block-indent 3) -(setq idlwave-end-offset -3) -(setq idlwave-continuation-indent 1) -(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" - ; anchored at start of line. -(setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> -(setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' -(setq idlwave-expand-generic-end t) ; convert END to ENDIF etc... -(setq idlwave-reserved-word-upcase t) ; Make reserved words upper case - ; (with abbrevs only) -(setq idlwave-abbrev-change-case nil) ; Don't force case of expansions -(setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill -(setq idlwave-show-block nil) ; Turn off blinking to begin -(setq idlwave-abbrev-move t) ; Allow abbrevs to move point -(setq idlwave-query-class '((method-default . nil) ; No query for method - (keyword-default . nil); or keyword completion - ("INIT" . t) ; except for these - ("CLEANUP" . t) - ("SETPROPERTY" .t) - ("GETPROPERTY" .t))) - -;; Using w3m for help (must install w3m and emacs-w3m) -(autoload 'w3m-browse-url "w3m" "Interface for w3m on Emacs." t) -(setq idlwave-help-browser-function 'w3m-browse-url - w3m-use-tab nil ; no tabs, location line, or toolbar - w3m-use-header-line nil - w3m-use-toolbar nil) - -;; Close my help window or frame when w3m closes with `q' -(defadvice w3m-close-window (after idlwave-close activate) - (if (boundp 'idlwave-help-frame) - (idlwave-help-quit))) - -;; 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 - (setq idlwave-help-browser-function 'browse-url-w3) - - ;; 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)) - (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) - (local-set-key [f5] 'idlwave-shell-break-here) - (local-set-key [f6] 'idlwave-shell-clear-current-bp) - - ;; Create a newline, indenting the original and new line. - ;; A similar function that does _not_ reindent the original - ;; line is on "\C-j" (The default for emacs programming modes). - (local-set-key "\n" 'idlwave-newline) - ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. - - ;; Some personal abbreviations - (define-abbrev idlwave-mode-abbrev-table - (concat idlwave-abbrev-start-char "wb") "widget_base()" - (idlwave-keyword-abbrev 1)) - (define-abbrev idlwave-mode-abbrev-table - (concat idlwave-abbrev-start-char "on") "obj_new()" - (idlwave-keyword-abbrev 1)) - )) - -;;; Settings for IDLWAVE SHELL mode - -(setq idlwave-shell-overlay-arrow "=>") ; default is ">" -(setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame -(setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> " -(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 - -@html -<A NAME="WIN_MAC"></A> -@end html -@node Windows and MacOS, Troubleshooting, Configuration Examples, Top -@appendix Windows and MacOS -@cindex Windows -@cindex MacOS -@cindex MacOSX - -IDLWAVE was developed on a UNIX system. However, thanks to the -portability of Emacs, much of IDLWAVE does also work under different -operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS. - -The only real problem is that there is no command-line version of IDL -for Windows or MacOS(<=9) with which IDLWAVE can interact. As a -result, 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 @file{.emacs} file: -the path names which, on a UNIX system, are 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 -@w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in -@w{@samp{C:\RSI\IDL63}}. - -@lisp -;; location of the lisp files (only needed if IDLWAVE is not part of -;; your default X/Emacs installation) -(setq load-path (cons "c:/program files/IDLWAVE" load-path)) - -;; The location of the IDL library directories, both standard, and your own. -;; note that the initial "+" expands the path recursively -(setq idlwave-library-path - '("+c:/RSI/IDL63/lib/" "+c:/path/to/my/idllibs" )) - -;; location of the IDL system directory (try "print,!DIR") -(setq idlwave-system-directory "c:/RSI/IDL63/") - -@end lisp - -@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 -file under the names @file{idlwave.tar.gz}. -@item M-TAB switches among running programs --- use Esc-TAB -instead. -@item Other issues as yet unnamed... -@end itemize - -Windows users who'd like to make use of IDLWAVE's context-aware HTML -help can skip the browser and use the HTMLHelp functionality directly. -@xref{Help with HTML Documentation}. - -@html -<A NAME="TROUBLE"></A> -@end html -@node Troubleshooting, GNU Free Documentation License, Windows and MacOS, Top -@appendix Troubleshooting -@cindex Troubleshooting - -Although IDLWAVE usually installs and works without difficulty, a few -common problems and their solutions are documented below. - -@enumerate - -@item @strong{Whenever an IDL error occurs or a breakpoint is hit, I get -errors or strange behavior when I try to type anything into some of my -IDLWAVE buffers.} - -This is a @emph{feature}, not an error. You're in @emph{Electric -Debug Mode} (@pxref{Electric Debug Mode}). You should see -@code{*Debugging*} in the mode-line. The buffer is read-only and all -debugging and examination commands are available as single keystrokes; -@kbd{C-?} lists these shortcuts. Use @kbd{q} to quit the mode, and -customize the variable @code{idlwave-shell-automatic-electric-debug} -if you prefer not to enter electric debug on breakpoints@dots{} but -you really should try it before you disable it! You can also -customize this variable to enter debug mode when errors are -encountered. - -@item @strong{I get errors like @samp{Searching for program: no such -file or directory, idl} when attempting to start the IDL shell.} - -IDLWAVE needs to know where IDL is in order to run it as a process. -By default, it attempts to invoke it simply as @samp{idl}, which -presumes such an executable is on your search path. You need to -ensure @samp{idl} is on your @samp{$PATH}, or specify the full -pathname to the idl program with the variable -@code{idlwave-shell-explicit-file-name}. Note that you may need to -set your shell search path in two places when running Emacs as an Aqua -application with MacOSX; see the next topic. - -@item @strong{IDLWAVE is disregarding my @samp{IDL_PATH} which I set -under MacOSX} - -If you run Emacs directly as an Aqua application, rather than from the -console shell, the environment is set not from your usual shell -configuration files (e.g. @file{.cshrc}), but from the file -@file{~/.MacOSX/environment.plist}. Either include your path settings -there, or start Emacs and IDLWAVE from the shell. - -@item @strong{I get errors like @samp{Symbol's function is void: -overlayp}} - -You don't have the @samp{fsf-compat} package installed, which IDLWAVE -needs to run under XEmacs. Install it, or find an XEmacs distribution -which includes it by default. - -@item @strong{I'm getting errors like @samp{Symbol's value as variable is void: -cl-builtin-gethash} on completion or routine info.} - -This error arises if you upgraded Emacs from 20.x to 21.x without -re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible -in compiled lisp files. Presumably, you kept the original .elc files in -place, and this is the source of the error. If you recompile (or just -"make; make install") from source, it should resolve this problem. -Another option is to recompile the @file{idlw*.el} files by hand using -@kbd{M-x byte-compile-file}. - -@item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches -windows on my desktop.} - -Your system is trapping @kbd{M-@key{TAB}} and using it for its own -nefarious purposes: Emacs never sees the keystrokes. On many Unix -systems, you can reconfigure your window manager to use another key -sequence for switching among windows. Another option is to use the -equivalent sequence @kbd{@key{ESC}-@key{TAB}}. - -@item @strong{When stopping at breakpoints or errors, IDLWAVE does not -seem to highlight the relevant line in the source.} - -IDLWAVE scans for error and halt messages and highlights the stop -location in the correct file. However, if you've changed the system -variable @samp{!ERROR_STATE.MSG_PREFIX}, it is unable to parse these -message correctly. Don't do that. - -@item @strong{IDLWAVE doesn't work correctly when using ENVI.} - -Though IDLWAVE was not written with ENVI in mind, it works just fine -with it, as long as you update the prompt it's looking for (@samp{IDL> -} by default). You can do this with the variable -@code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g., -in your @file{.emacs}: - -@lisp -(setq idlwave-shell-prompt-pattern "^\r? ?\\(ENVI\\|IDL\\)> ") -@end lisp - -@item @strong{Attempts to set breakpoints fail: no breakpoint is -indicated in the IDLWAVE buffer.} - -IDL changed its breakpoint reporting format starting with IDLv5.5. The -first version of IDLWAVE to support the new format is IDLWAVE v4.10. If -you have an older version and are using IDL >v5.5, you need to upgrade, -and/or make sure your recent version of IDLWAVE is being found on the -Emacs load-path (see the next entry). You can list the version being -used with @kbd{C-h v idlwave-mode-version @key{RET}}. - -@item @strong{I installed a new version of IDLWAVE, but the old -version is still being used} or @strong{IDLWAVE works, but when I -tried to install the optional modules @file{idlw-roprompt.el} or -@file{idlw-complete-structtag}, I get errors like @samp{Cannot open -load file}}. - -The problem is that your Emacs is not finding the version of IDLWAVE you -installed. Many Emacsen come with an older bundled copy of IDLWAVE -(e.g. v4.7 for Emacs 21.x), which is likely what's being used instead. -You need to make sure your Emacs @emph{load-path} contains the directory -where IDLWAVE is installed (@file{/usr/local/share/emacs/site-lisp}, by -default), @emph{before} Emacs' default search directories. You can -accomplish this by putting the following in your @file{.emacs}: - -@lisp -(setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path)) -@end lisp - -@noindent You can check on your load-path value using @kbd{C-h v -load-path @key{RET}}, and @kbd{C-h m} in an IDLWAVE buffer should show -you the version Emacs is using. - -@item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.} - -Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated -programming mode for CORBA's Interface Definition Language (you should -see @samp{(IDL)}, not @samp{(IDLWAVE)} in the mode-line). One -solution: don't name your file @file{.idl}, but rather @file{.pro}. -Another solution: make sure @file{.idl} files load IDLWAVE instead of -@samp{idl-mode} by adding the following to your @file{.emacs}: - -@lisp -(setcdr (rassoc 'idl-mode auto-mode-alist) 'idlwave-mode) -@end lisp - -@item @strong{The routine info for my local routines is out of date!} - -IDLWAVE collects routine info from various locations (@pxref{Routine -Information Sources}). Routines in files visited in a buffer or -compiled in the shell should be up to date. For other routines, the -information is only as current as the most recent scan. If you have a -rapidly changing set of routines, and you'd like the latest routine -information to be available for it, one powerful technique is to make -use of the library catalog tool, @samp{idlwave_catalog}. Simply add a -line to your @samp{cron} file (@samp{crontab -e} will let you edit this -on some systems), like this - -@example -45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib) -@end example - -@noindent where @samp{MyLib} is the name of your library. This will -rescan all @file{.pro} files at or below @file{/path/to/myidllib} every -week night at 3:45am. You can even scan site-wide libraries with this -method, and the most recent information will be available to all users. -Since the scanning is very fast, there is very little impact. - -@item @strong{All the Greek-font characters in the HTML help are -displayed as Latin characters!} - -Unfortunately, the HTMLHelp files RSI provides attempt to switch to -@samp{Symbol} font to display Greek characters, which is not really an -permitted method for doing this in HTML. There is a "workaround" for -some browsers: @xref{HTML Help Browser Tips}. - -@item @strong{In the shell, my long commands are truncated at 256 characters!} - -This actually happens when running IDL in an XTerm as well. There are -a couple of workarounds: @code{define_key,/control,'^d'} (e.g. in -your @file{$IDL_STARTUP} file) will disable the @samp{EOF} character -and give you a 512 character limit. You won't be able to use -@key{C-d} to quit the shell, however. Another possibility is -@code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a -memory-bounded limit), but disables the processing of background -widget events (those with @code{/NO_BLOCK} passed to @code{XManager}). - -@item @strong{When I invoke IDL HTML help on a routine, the page which -is loaded is one page off, e.g. for @code{CONVERT_COORD}, I get -@code{CONTOUR}.} - -You have a mismatch between your help index and the HTML help package -you downloaded. You need to ensure you download a ``downgrade kit'' if -you are using anything older than the latest HTML help package. A new -help package appears with each IDL release (assuming the documentation -is updated). -Starting with IDL 6.2, the HTML help and its catalog are -distributed with IDL, and so should never be inconsistent. - -@item @strong{I get errors such as @samp{void-variable -browse-url-browser-function} or similar when attempting to load IDLWAVE -under XEmacs.} - -You don't have the @samp{browse-url} (or other required) XEmacs package. -Unlike GNU Emacs, XEmacs distributes many packages separately from the -main program. IDLWAVE is actually among these, but is not always the -most up to date. When installing IDLWAVE as an XEmacs package, it -should prompt you for required additional packages. When installing it -from source, it won't and you'll get this error. The easiest solution -is to install all the packages when you install XEmacs (the so-called -@samp{sumo} bundle). The minimum set of XEmacs packages required by -IDLWAVE is @samp{fsf-compat, xemacs-base, mail-lib}. - -@end enumerate - -@node GNU Free Documentation License, Index, Troubleshooting, Top -@appendix GNU Free Documentation License -@include doclicense.texi - -@node Index, , GNU Free Documentation License, Top -@unnumbered Index -@printindex cp - -@bye - -@ignore - arch-tag: f1d73958-1423-4127-b8aa-f7b953d64492 -@end ignore