+
+;; 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\IDL62}}.
+
+@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/IDL55/lib/" "+c:/path/to/my/idllibs" ))
+
+;; location of the IDL system directory (try "print,!DIR")
+(setq idlwave-system-directory "c:/RSI/IDL62/")
+
+@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, Index, 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)