This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE
@value{VERSION}.
-Copyright @copyright{} 1999-2011 Free Software Foundation, Inc.
+Copyright @copyright{} 1999-2012 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
IDLWAVE is a package which supports editing source code written in the
Interactive Data Language (IDL), and running IDL as an inferior shell.
-@insertcopying
+@insertcopying
@end ifnottex
@menu
* 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::
+* Acknowledgments:: 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
Getting Started (Tutorial)
-* Lesson I -- Development Cycle::
-* Lesson II -- Customization::
-* Lesson III -- User Catalog::
+* Lesson I -- Development Cycle::
+* Lesson II -- Customization::
+* Lesson III -- User Catalog::
The IDLWAVE Major Mode
Code Formatting
* Code Indentation:: Reflecting the logical structure
-* Continued Statement Indentation::
+* Continued Statement Indentation::
* Comment Indentation:: Special indentation for comment lines
* Continuation Lines:: Splitting statements over lines
* Syntax Highlighting:: Font-lock support
Online Help
-* Help with HTML Documentation::
-* Help with Source::
+* 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::
+* Object Method Completion in the Shell::
* Class and Keyword Inheritance:: obj->Method, _EXTRA=e
* Structure Tag Completion:: Completing state.Tag
* 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::
+* 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::
+* 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::
+* Catalogs::
* Load-Path Shadows:: Routines defined in several places
* Documentation Scan:: Scanning the IDL Manuals
Catalogs
-* Library Catalogs::
-* User Catalog::
+* Library Catalogs::
+* User Catalog::
@end detailmenu
@end menu
what IDLWAVE does:
@itemize @bullet
-@item
+@item
Smart code indentation and automatic-formatting.
@item
Three level syntax highlighting support.
-@item
+@item
Context-sensitive display of calling sequences and keywords for more
-than 1000 native IDL routines, extendible to any additional number of
+than 1000 native IDL routines, extensible 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
@cindex Getting Started
@menu
-* Lesson I -- Development Cycle::
-* Lesson II -- Customization::
-* Lesson III -- User Catalog::
+* 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
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)
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
+routines and for the huge amount of code in major libraries like JHUAPL
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
@menu
* Code Indentation:: Reflecting the logical structure
-* Continued Statement Indentation::
+* Continued Statement Indentation::
* Comment Indentation:: Special indentation for comment lines
* Continuation Lines:: Splitting statements over lines
* Syntax Highlighting:: Font-lock support
routine. @xref{Actions}, for information how to impose additional
formatting conventions on foreign code.
-@defopt idlwave-main-block-indent (@code{2})
+@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.
@defopt idlwave-use-last-hang-indent (@code{nil})
Non-@code{nil} means use last match on line for
-@code{idlwave-indent-regexp}.
+@code{idlwave-indent-regexp}.
@end defopt
@node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting
@defopt idlwave-default-font-lock-items
Items which should be fontified on the default fontification level
-2.
+2.
@end defopt
@node Octals and Highlighting, , Syntax Highlighting, Code Formatting
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.
+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
@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
+@tab An otherwise unknown routine the shell lists as unresolved
(referenced, but not compiled).
@end multitable
@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}).
+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}
@menu
-* Help with HTML Documentation::
-* Help with Source::
+* Help with HTML Documentation::
+* Help with Source::
@end menu
@node Help with HTML Documentation, Help with Source, Online 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
+@end defopt
@defopt idlwave-html-help-location @file{/usr/local/etc/}
The directory where the @file{idl_html_help} HTML directory live.
corresponding source code or DocLib header will be used as the help
text.
-@cindex Completion, cancelling
-@cindex Cancelling completion
+@cindex Completion, canceling
+@cindex Canceling 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
@menu
* Case of Completed Words:: CaseOFcomPletedWords
* Object Method Completion and Class Ambiguity:: obj->Method, what?
-* Object Method Completion in the Shell::
+* Object Method Completion in the Shell::
* Class and Keyword Inheritance:: obj->Method, _EXTRA=e
* Structure Tag Completion:: Completing state.Tag
@end menu
@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}).
+large (e.g. @code{Init,SetProperty,GetProperty}).
@cindex Saving object class on @code{->}
@cindex @code{->}
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).
+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
Non-@code{nil} means consider inheritance during completion, online help etc.
@end defopt
-@defopt idlwave-keyword-class-inheritance
+@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
simply add the following to your @file{.emacs}:
@lisp
- (add-hook 'idlwave-load-hook
+ (add-hook 'idlwave-load-hook
(lambda () (require 'idlw-complete-structtag)))
@end lisp
(idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<"
'(capitalize-word 1) t)
;; Capitalize common block name
- (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"
+ (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"
'(capitalize-word 1) t)))
@end lisp
Normal hook. Executed when @file{idlwave.el} is loaded.
@end defopt
-@node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top
+@node The IDLWAVE Shell, Acknowledgments, The IDLWAVE Major Mode, Top
@chapter The IDLWAVE Shell
@cindex IDLWAVE shell
@cindex Major mode, @code{idlwave-shell-mode}
@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::
+* 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
@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}.
+@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
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.
@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
+@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 defopt
@menu
-* A Tale of Two Modes::
-* Debug Key Bindings::
-* Breakpoints and Stepping::
-* Compiling Programs::
-* Walking the Calling Stack::
-* Electric Debug Mode::
+* A Tale of Two Modes::
+* Debug Key Bindings::
+* Breakpoints and Stepping::
+* Compiling Programs::
+* Walking the Calling Stack::
+* Electric Debug Mode::
@end menu
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}).
+(@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).
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}.
+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
@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
+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.
@defopt idlwave-shell-electric-stop-color (Violet)
Default color of the stopped line overlay when in electric debug mode.
-@end defopt
+@end defopt
-@defopt idlwave-shell-electric-stop-line-face
+@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
@end defopt
@defopt idlwave-shell-output-face
-The face for @code{idlwave-shell-output-overlay}.
+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.
+@file{*Examine*} buffer, instead of in the shell itself.
@end defopt
@defopt idlwave-shell-max-print-length (200)
@lisp
(add-hook 'idlwave-shell-mode-hook
(lambda ()
- (idlwave-shell-define-key-both [s-down-mouse-2]
- (idlwave-shell-mouse-examine
+ (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
+ (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
-
+@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,
(three underscores) are replaced by the indicated expression.
@end defopt
-@node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top
-@chapter Acknowledgements
-@cindex Acknowledgements
+@node Acknowledgments, Sources of Routine Info, The IDLWAVE Shell, Top
+@chapter Acknowledgments
+@cindex Acknowledgments
@cindex Maintainer, of IDLWAVE
@cindex Authors, of IDLWAVE
@cindex Contributors, to IDLWAVE
everything, modernized IDLWAVE with many new features, and developed the
manual.
-@item
+@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
@noindent
Thanks to everyone!
-@node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top
+@node Sources of Routine Info, HTML Help Browser Tips, Acknowledgments, Top
@appendix Sources of Routine Info
@cindex Sources of routine information
@menu
* Routine Definitions:: Where IDL Routines are defined.
* Routine Information Sources:: So how does IDLWAVE know about...
-* Catalogs::
+* Catalogs::
* Load-Path Shadows:: Routines defined in several places
* Documentation Scan:: Scanning the IDL Manuals
@end menu
several places:
@enumerate
-@item
+@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.
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
+@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
Formerly, this list was created by scanning the IDL manuals to produce
the file @file{idlw-rinfo.el}.
-@item
+@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
@end defopt
@menu
-* Library Catalogs::
-* User Catalog::
+* Library Catalogs::
+* User Catalog::
@end menu
@html
@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
+@item Can be used to scan directories for which the user has no write
privileges.
@item Easy widget-based path selection.
@end itemize
on the load path is routine info display (@pxref{Routine Info}).
@node Documentation Scan, , Load-Path Shadows, Sources of Routine Info
-@appendixsec Documentation Scan
+@appendixsec Documentation Scan
@cindex @file{get_html_rinfo}
@cindex @file{idlw-rinfo.el}
@cindex Scanning the documentation
(setq idlwave-main-block-indent 3)
(setq idlwave-end-offset -3)
(setq idlwave-continuation-indent 1)
-(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;"
+(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 '='
;; (local-set-key "\C-j" 'idlwave-newline) ; My preference.
;; Some personal abbreviations
- (define-abbrev idlwave-mode-abbrev-table
+ (define-abbrev idlwave-mode-abbrev-table
(concat idlwave-abbrev-start-char "wb") "widget_base()"
(idlwave-keyword-abbrev 1))
- (define-abbrev idlwave-mode-abbrev-table
+ (define-abbrev idlwave-mode-abbrev-table
(concat idlwave-abbrev-start-char "on") "obj_new()"
(idlwave-keyword-abbrev 1))
))
(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
+ (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
+ (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>
+<A NAME="WINDOWS_MAC"></A>
@end html
@node Windows and MacOS, Troubleshooting, Configuration Examples, Top
@appendix Windows and MacOS
sure you check the following things:
@itemize @bullet
-@item When you download the IDLWAVE distribution, make sure you save the
+@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.
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.
+encountered.
@item @strong{I get errors like @samp{Searching for program: no such
file or directory, idl} when attempting to start the IDL shell.}
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}.
+@kbd{M-x byte-compile-file}.
@item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches
windows on my desktop.}
(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
+default), @emph{before} Emacs's default search directories. You can
accomplish this by putting the following in your @file{.emacs}:
@lisp
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).
+is updated).
Starting with IDL 6.2, the HTML help and its catalog are
distributed with IDL, and so should never be inconsistent.