1 |
\input texinfo @c -*-texinfo-*- |
\input texinfo @c -*-texinfo-*- |
2 |
@c %**start of header |
@c %**start of header |
3 |
@setfilename ../info/idlwave |
@setfilename idlwave |
4 |
@settitle IDLWAVE User Manual |
@settitle IDLWAVE User Manual |
5 |
|
@dircategory Emacs |
6 |
|
@direntry |
7 |
|
* IDLWAVE: (idlwave). Major mode and shell for IDL files. |
8 |
|
@end direntry |
9 |
@synindex ky cp |
@synindex ky cp |
10 |
@syncodeindex vr cp |
@syncodeindex vr cp |
11 |
@syncodeindex fn cp |
@syncodeindex fn cp |
12 |
@set VERSION 4.15 |
@set VERSION 5.5 |
13 |
@set EDITION 4.15 |
@set EDITION 5.5 |
14 |
@set IDLVERSION 5.5 |
@set IDLVERSION 6.1 |
15 |
@set NSYSROUTINES 1324 |
@set NSYSROUTINES 1850 |
16 |
@set NSYSKEYWORDS 6129 |
@set NSYSKEYWORDS 7685 |
17 |
@set DATE September 2002 |
@set DATE November, 2004 |
18 |
@set AUTHOR J.D. Smith & Carsten Dominik |
@set AUTHOR J.D. Smith & Carsten Dominik |
19 |
@set AUTHOR-EMAIL dominik@@astro.uva.nl |
@set AUTHOR-EMAIL jdsmith@@as.arizona.edu |
20 |
@set MAINTAINER J.D. Smith |
@set MAINTAINER J.D. Smith |
21 |
@set MAINTAINER-EMAIL jdsmith@@as.arizona.edu |
@set MAINTAINER-EMAIL jdsmith@@as.arizona.edu |
22 |
@set IDLWAVE-HOMEPAGE http://idlwave.org/ |
@set IDLWAVE-HOMEPAGE http://idlwave.org/ |
23 |
@c %**end of header |
@c %**end of header |
24 |
|
@finalout |
25 |
|
|
26 |
@copying |
@ifinfo |
27 |
This file documents IDLWAVE, a major mode for editing IDL files with |
This file documents IDLWAVE, a major mode for editing IDL files with |
28 |
Emacs, and interacting with an IDL shell run as a subprocess. |
Emacs, and interacting with an IDL shell run as a subprocess. |
29 |
|
|
30 |
This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE |
This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE |
31 |
@value{VERSION} |
@value{VERSION} |
32 |
|
|
33 |
Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, |
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 Free Software |
34 |
Inc. |
Foundation, Inc. |
35 |
|
|
|
@quotation |
|
36 |
Permission is granted to copy, distribute and/or modify this document |
Permission is granted to copy, distribute and/or modify this document |
37 |
under the terms of the GNU Free Documentation License, Version 1.1 or |
under the terms of the GNU Free Documentation License, Version 1.1 or |
38 |
any later version published by the Free Software Foundation; with no |
any later version published by the Free Software Foundation; with no |
49 |
Documentation License. If you want to distribute this document |
Documentation License. If you want to distribute this document |
50 |
separately from the collection, you can do so by adding a copy of the |
separately from the collection, you can do so by adding a copy of the |
51 |
license to the document, as described in section 6 of the license. |
license to the document, as described in section 6 of the license. |
52 |
@end quotation |
@end ifinfo |
|
@end copying |
|
|
|
|
|
@dircategory Emacs |
|
|
@direntry |
|
|
* IDLWAVE: (idlwave). Major mode and shell for IDL files. |
|
|
@end direntry |
|
|
|
|
|
@finalout |
|
53 |
|
|
54 |
@titlepage |
@titlepage |
55 |
@title IDLWAVE User Manual |
@title IDLWAVE User Manual |
56 |
@subtitle Emacs major mode and shell for IDL |
@subtitle Emacs major mode and shell for IDL |
57 |
@subtitle Edition @value{EDITION}, @value{DATE} |
@subtitle Edition @value{EDITION}, @value{DATE} |
58 |
|
|
59 |
@author by Carsten Dominik & J.D. Smith |
@author by J.D. Smith & Carsten Dominik |
60 |
@page |
@page |
61 |
This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for |
This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for |
62 |
IDLWAVE version @value{VERSION}, @value{DATE}. |
IDLWAVE version @value{VERSION}, @value{DATE}. |
63 |
|
@sp 2 |
64 |
|
Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 Free Software |
65 |
|
Foundation, Inc. |
66 |
|
@sp 2 |
67 |
@cindex Copyright, of IDLWAVE |
@cindex Copyright, of IDLWAVE |
68 |
@insertcopying |
Permission is granted to copy, distribute and/or modify this document |
69 |
|
under the terms of the GNU Free Documentation License, Version 1.1 or |
70 |
|
any later version published by the Free Software Foundation; with no |
71 |
|
Invariant Sections, with the Front-Cover texts being ``A GNU |
72 |
|
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the |
73 |
|
license is included in the section entitled ``GNU Free Documentation |
74 |
|
License'' in the Emacs manual. |
75 |
|
|
76 |
|
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
77 |
|
this GNU Manual, like GNU software. Copies published by the Free |
78 |
|
Software Foundation raise funds for GNU development.'' |
79 |
|
|
80 |
|
This document is part of a collection distributed under the GNU Free |
81 |
|
Documentation License. If you want to distribute this document |
82 |
|
separately from the collection, you can do so by adding a copy of the |
83 |
|
license to the document, as described in section 6 of the license. |
84 |
@end titlepage |
@end titlepage |
85 |
@contents |
@contents |
86 |
|
|
90 |
|
|
91 |
@node Top, Introduction, (dir), (dir) |
@node Top, Introduction, (dir), (dir) |
92 |
|
|
93 |
IDLWAVE is a package which supports editing source for the |
IDLWAVE is a package which supports editing source code written in the |
94 |
Interactive Data Language (IDL), and running IDL as an inferior |
Interactive Data Language (IDL), and running IDL as an inferior shell. |
|
shell. |
|
95 |
|
|
96 |
@end ifnottex |
@end ifnottex |
97 |
|
|
98 |
@menu |
@menu |
99 |
* Introduction:: What IDLWAVE is and what it's not |
* Introduction:: What IDLWAVE is, and what it is not |
100 |
* IDLWAVE in a Nutshell:: One page quick-start guide |
* IDLWAVE in a Nutshell:: One page quick-start guide |
101 |
* Getting Started:: Tutorial |
* Getting Started:: Tutorial |
102 |
* The IDLWAVE Major Mode:: The mode to edit IDL programs |
* The IDLWAVE Major Mode:: The mode for editing IDL programs |
103 |
* The IDLWAVE Shell:: The mode to run IDL as an inferior program |
* The IDLWAVE Shell:: The mode for running IDL as an inferior program |
104 |
* Installation:: How to Install or Upgrade |
* Installation:: How to Install or Upgrade |
105 |
* Acknowledgements:: Who did what |
* Acknowledgements:: Who did what |
106 |
* Sources of Routine Info:: How does IDLWAVE know about routine XYZ |
* Sources of Routine Info:: How does IDLWAVE know about routine XYZ |
107 |
* Configuration Examples:: The user is king... |
* HTML Help Browser Tips:: |
108 |
|
* Configuration Examples:: The user is king |
109 |
* Windows and MacOS:: What still works, and how |
* Windows and MacOS:: What still works, and how |
110 |
|
* Troubleshooting:: When good computers turn bad |
111 |
* Index:: Fast access |
* Index:: Fast access |
112 |
|
|
113 |
@detailmenu |
@detailmenu |
115 |
|
|
116 |
Getting Started (Tutorial) |
Getting Started (Tutorial) |
117 |
|
|
118 |
* Lesson I -- Development Cycle:: |
* Lesson I -- Development Cycle:: |
119 |
* Lesson II -- Customization:: |
* Lesson II -- Customization:: |
120 |
* Lesson III -- Library Catalog:: |
* Lesson III -- User Catalog:: |
121 |
|
|
122 |
The IDLWAVE Major Mode |
The IDLWAVE Major Mode |
123 |
|
|
137 |
Code Formatting |
Code Formatting |
138 |
|
|
139 |
* Code Indentation:: Reflecting the logical structure |
* Code Indentation:: Reflecting the logical structure |
140 |
* Continued Statement Indentation:: |
* Continued Statement Indentation:: |
141 |
* Comment Indentation:: Special indentation for comment lines |
* Comment Indentation:: Special indentation for comment lines |
142 |
* Continuation Lines:: Splitting statements over lines |
* Continuation Lines:: Splitting statements over lines |
143 |
* Syntax Highlighting:: Font-lock support |
* Syntax Highlighting:: Font-lock support |
144 |
* Octals and Highlighting:: Why "123 causes problems |
* Octals and Highlighting:: Why "123 causes problems |
145 |
|
|
146 |
|
Online Help |
147 |
|
|
148 |
|
* Help with HTML Documentation:: |
149 |
|
* Help with Source:: |
150 |
|
|
151 |
Completion |
Completion |
152 |
|
|
153 |
* Case of Completed Words:: CaseOFcomPletedWords |
* Case of Completed Words:: CaseOFcomPletedWords |
154 |
* Object Method Completion and Class Ambiguity:: obj->Method, what? |
* Object Method Completion and Class Ambiguity:: obj->Method, what? |
155 |
* Object Method Completion in the Shell:: |
* Object Method Completion in the Shell:: |
156 |
* Class and Keyword Inheritance:: obj->Method, _EXTRA=e |
* Class and Keyword Inheritance:: obj->Method, _EXTRA=e |
157 |
* Structure Tag Completion:: Completing state.Tag |
* Structure Tag Completion:: Completing state.Tag |
158 |
|
|
166 |
|
|
167 |
* Starting the Shell:: How to launch IDL as a subprocess |
* Starting the Shell:: How to launch IDL as a subprocess |
168 |
* Using the Shell:: Interactively working with the Shell |
* Using the Shell:: Interactively working with the Shell |
169 |
* Commands Sent to the Shell:: |
* Commands Sent to the Shell:: |
170 |
* Debugging IDL Programs:: |
* Debugging IDL Programs:: |
171 |
* Examining Variables:: |
* Examining Variables:: |
172 |
* Custom Expression Examination:: |
* Custom Expression Examination:: |
173 |
|
|
174 |
Debugging IDL Programs |
Debugging IDL Programs |
175 |
|
|
176 |
* Debug Key Bindings:: |
* A Tale of Two Modes:: |
177 |
* Compiling Programs:: |
* Debug Key Bindings:: |
178 |
* Breakpoints and Stepping:: |
* Breakpoints and Stepping:: |
179 |
* Walking the Calling Stack:: |
* Compiling Programs:: |
180 |
|
* Walking the Calling Stack:: |
181 |
|
* Electric Debug Mode:: |
182 |
|
|
183 |
Installation |
Installation |
184 |
|
|
185 |
* Installing IDLWAVE:: How to install the distribution |
* Installing IDLWAVE:: How to install the distribution |
186 |
* Installing Online Help:: Where to get the additional files needed |
* Installing Online Help:: Where to get the additional files needed |
|
* Upgrading from idl.el:: Necessary configuration changes |
|
187 |
|
|
188 |
Sources of Routine Info |
Sources of Routine Info |
189 |
|
|
190 |
* Routine Definitions:: Where IDL Routines are defined. |
* Routine Definitions:: Where IDL Routines are defined. |
191 |
* Routine Information Sources:: So how does IDLWAVE know about... |
* Routine Information Sources:: So how does IDLWAVE know about... |
192 |
* Library Catalog:: Scanning the Libraries for Routine Info |
* Catalogs:: |
193 |
* Load-Path Shadows:: Routines defined in several places |
* Load-Path Shadows:: Routines defined in several places |
194 |
* Documentation Scan:: Scanning the IDL Manuals |
* Documentation Scan:: Scanning the IDL Manuals |
195 |
|
|
196 |
|
Catalogs |
197 |
|
|
198 |
|
* Library Catalogs:: |
199 |
|
* User Catalog:: |
200 |
|
|
201 |
@end detailmenu |
@end detailmenu |
202 |
@end menu |
@end menu |
203 |
|
|
212 |
@cindex @file{idl-shell.el} |
@cindex @file{idl-shell.el} |
213 |
@cindex Feature overview |
@cindex Feature overview |
214 |
|
|
215 |
IDLWAVE is a package which supports editing source files for the |
IDLWAVE is a package which supports editing source files written in |
216 |
Interactive Data Language (IDL@footnote{IDL is a registered trademark of |
the Interactive Data Language (IDL@footnote{IDL is a registered |
217 |
Research Systems, Inc., a Kodak Company}), and for running IDL as an |
trademark of Research Systems, Inc., a Kodak Company}), and running |
218 |
inferior shell@footnote{Note that this package has nothing to do with |
IDL as an inferior shell@footnote{Note that this package has nothing |
219 |
the Interface Definition Language, part of the Common Object Request |
to do with the Interface Definition Language, part of the Common |
220 |
Broker Architecture (CORBA)}. It can also be used for editing source |
Object Request Broker Architecture (CORBA)}@footnote{IDLWAVE can also |
221 |
files for the related WAVE/CL language, but with only limited |
be used for editing source files for the related WAVE/CL language, but |
222 |
support. |
with only limited support.}. It is a feature-rich replacement for the |
223 |
|
IDLDE development environment bundled with IDL, and uses the full |
224 |
IDLWAVE consists of two main parts: a major mode for editing IDL source |
power of Emacs to make editing and running IDL programs easier, |
225 |
files files (@code{idlwave-mode}) and a mode for running the IDL program |
quicker, and more structured. |
226 |
as an inferior shell (@code{idlwave-shell-mode}). Although one mode can |
|
227 |
be used without the other, both work together closely to form a complete |
IDLWAVE consists of two main parts: a major mode for editing IDL |
228 |
development environment. Here is a brief summary of what IDLWAVE does: |
source files (@code{idlwave-mode}) and a mode for running the IDL |
229 |
|
program as an inferior shell (@code{idlwave-shell-mode}). Although |
230 |
|
one mode can be used without the other, both work together closely to |
231 |
|
form a complete development environment. Here is a brief summary of |
232 |
|
what IDLWAVE does: |
233 |
|
|
234 |
@itemize @bullet |
@itemize @bullet |
235 |
@item |
@item |
236 |
Code indentation and formatting. |
Smart code indentation and automatic-formatting. |
237 |
@item |
@item |
238 |
Three level syntax highlighting support. |
Three level syntax highlighting support. |
239 |
@item |
@item |
240 |
Context-sensitive display of calling sequences and keywords for more |
Context-sensitive display of calling sequences and keywords for more |
241 |
than 1000 native IDL routines, extendible to any number of additional |
than 1000 native IDL routines, extendible to any additional number of |
242 |
routines in your local IDL libraries. |
local routines, and already available with many pre-scanned libraries. |
243 |
@item |
@item |
244 |
Routine name space conflict search, likelihood-of-use ranking. |
Routine name space conflict search with likelihood-of-use ranking. |
245 |
@item |
@item |
246 |
Fast, context-sensitive online help. |
Fast, context-sensitive online HTML help, or source-header help for |
247 |
|
undocumented routines. |
248 |
@item |
@item |
249 |
Context sensitive completion of routine names and keywords. |
Context sensitive completion of routine names, keywords, system |
250 |
|
variables, class names and much more. |
251 |
@item |
@item |
252 |
Easy insertion of code templates. |
Easy insertion of code templates and abbreviations of common constructs. |
253 |
@item |
@item |
254 |
Automatic corrections to enforce a variety of customizable coding |
Automatic corrections to enforce a variety of customizable coding |
255 |
standards. |
standards. |
264 |
editing and all the completion and routine info capabilities present in |
editing and all the completion and routine info capabilities present in |
265 |
IDL source buffers. |
IDL source buffers. |
266 |
@item |
@item |
267 |
Compilation, execution and interactive debugging of programs directly |
Compilation, execution and interactive single-keystroke debugging of |
268 |
from the source buffer. |
programs directly from the source buffer. |
269 |
@item |
@item |
270 |
Quick, source-guided navigation of the calling stack, with variable |
Quick, source-guided navigation of the calling stack, with variable |
271 |
inspection, etc. |
inspection, etc. |
294 |
@end itemize |
@end itemize |
295 |
@end ifnottex |
@end ifnottex |
296 |
|
|
297 |
IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el} |
IDLWAVE is the distant successor to the @file{idl.el} and |
298 |
files written by Chris Chase. The modes and files had to be renamed |
@file{idl-shell.el} files written by Chris Chase. The modes and files |
299 |
because of a name space conflict with CORBA's @code{idl-mode}, defined in |
had to be renamed because of a name space conflict with CORBA's |
300 |
Emacs in the file @file{cc-mode.el}. If you have been using the old |
@code{idl-mode}, defined in Emacs in the file @file{cc-mode.el}. |
|
files, check @ref{Upgrading from idl.el} for information on how to |
|
|
switch. |
|
301 |
|
|
302 |
In this manual, each section ends with a list of related user options. |
In this manual, each section ends with a list of related user options. |
303 |
Don't be confused by the sheer number of options available --- in most |
Don't be confused by the sheer number of options available --- in most |
338 |
@tab Update IDLWAVE's knowledge about functions and procedures. |
@tab Update IDLWAVE's knowledge about functions and procedures. |
339 |
@item @kbd{C-c C-v} |
@item @kbd{C-c C-v} |
340 |
@tab Visit the source code of a procedure/function. |
@tab Visit the source code of a procedure/function. |
341 |
|
@item @kbd{C-u C-c C-v} |
342 |
|
@tab Visit the source code of a procedure/function in this buffer. |
343 |
@item @kbd{C-c C-h} |
@item @kbd{C-c C-h} |
344 |
@tab Insert a standard documentation header. |
@tab Insert a standard documentation header. |
345 |
@item @kbd{C-c @key{RET}} |
@item @kbd{C-c @key{RET}} |
355 |
@tab Cycle back through IDL command history. |
@tab Cycle back through IDL command history. |
356 |
@item @kbd{M-n} |
@item @kbd{M-n} |
357 |
@tab Cycle forward. |
@tab Cycle forward. |
358 |
@item @kbd{M-@key{TAB}} |
@item @kbd{@key{TAB}} |
359 |
@tab Complete a procedure name, function name or keyword in the shell buffer. |
@tab Complete a procedure name, function name or keyword in the shell buffer. |
360 |
@item @kbd{C-c C-d C-c} |
@item @kbd{C-c C-d C-c} |
361 |
@tab Save and compile the source file in the current buffer. |
@tab Save and compile the source file in the current buffer. |
362 |
@item @kbd{C-c C-d C-x} |
@item @kbd{C-c C-d C-x} |
363 |
@tab Goto next syntax error. |
@tab Go to next syntax error. |
364 |
|
@item @kbd{C-c C-d C-v} |
365 |
|
@tab Switch to electric debug mode. |
366 |
@item @kbd{C-c C-d C-b} |
@item @kbd{C-c C-d C-b} |
367 |
@tab Set a breakpoint at the nearest viable source line. |
@tab Set a breakpoint at the nearest viable source line. |
368 |
@item @kbd{C-c C-d C-d} |
@item @kbd{C-c C-d C-d} |
369 |
@tab Clear the nearest breakpoint. |
@tab Clear the nearest breakpoint. |
370 |
|
@item @kbd{C-c C-d [} |
371 |
|
@tab Go to the previous breakpoint. |
372 |
|
@item @kbd{C-c C-d ]} |
373 |
|
@tab Go to the next breakpoint. |
374 |
@item @kbd{C-c C-d C-p} |
@item @kbd{C-c C-d C-p} |
375 |
@tab Print the value of the expression near point in IDL. |
@tab Print the value of the expression near point in IDL. |
376 |
@end multitable |
@end multitable |
392 |
(setq idlwave-shell-automatic-start t) |
(setq idlwave-shell-automatic-start t) |
393 |
;; Bind debugging commands with CONTROL and SHIFT modifiers |
;; Bind debugging commands with CONTROL and SHIFT modifiers |
394 |
(setq idlwave-shell-debug-modifiers '(control shift)) |
(setq idlwave-shell-debug-modifiers '(control shift)) |
|
;; Specify the online help files' location. |
|
|
(setq idlwave-help-directory "~/.idlwave") |
|
395 |
@end lisp |
@end lisp |
396 |
|
|
397 |
@ifhtml |
@ifhtml |
404 |
@cindex Getting Started |
@cindex Getting Started |
405 |
|
|
406 |
@menu |
@menu |
407 |
* Lesson I -- Development Cycle:: |
* Lesson I -- Development Cycle:: |
408 |
* Lesson II -- Customization:: |
* Lesson II -- Customization:: |
409 |
* Lesson III -- Library Catalog:: |
* Lesson III -- User Catalog:: |
410 |
@end menu |
@end menu |
411 |
|
|
412 |
@node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started |
@node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started |
413 |
@section Lesson I: Development Cycle |
@section Lesson I: Development Cycle |
414 |
|
|
415 |
The purpose of this tutorial is to guide you through a very basic |
The purpose of this tutorial is to guide you through a very basic |
416 |
development cycle using IDLWAVE. We will paste a simple program into a |
development cycle using IDLWAVE. We will paste a simple program into |
417 |
buffer and use the shell to compile, debug and run it. On the way we |
a buffer and use the shell to compile, debug and run it. On the way |
418 |
will use many of the important IDLWAVE commands. Note however that |
we will use many of the important IDLWAVE commands. Note, however, |
419 |
there are many more capabilities in IDLWAVE than covered here, which can |
that IDLWAVE has many more capabilities than covered here, which can |
420 |
be discovered by reading the entire manual. |
be discovered by reading the entire manual, or hovering over the |
421 |
|
shoulder of your nearest IDLWAVE guru for a few days. |
422 |
|
|
423 |
It is assumed that you have access to Emacs or XEmacs with the full |
It is assumed that you have access to Emacs or XEmacs with the full |
424 |
IDLWAVE package including online help (@pxref{Installation}). We also |
IDLWAVE package including online help (@pxref{Installation}). We also |
433 |
@kbd{C-x C-f tutorial.pro @key{RET}} |
@kbd{C-x C-f tutorial.pro @key{RET}} |
434 |
@end example |
@end example |
435 |
|
|
436 |
A buffer for this file will pop up, and it should be in IDLWAVE mode, as |
A buffer for this file will pop up, and it should be in IDLWAVE mode, |
437 |
shown in the mode line just below the editing window. Also, the menu |
indicated in the mode line just below the editing window. Also, the |
438 |
bar should contain entries @samp{IDLWAVE} and @samp{Debug}. |
menu bar should contain @samp{IDLWAVE}. |
439 |
|
|
440 |
Now cut-and-paste the following code, also available as |
Now cut-and-paste the following code, also available as |
441 |
@file{tutorial.pro} in the IDLWAVE distribution. |
@file{tutorial.pro} in the IDLWAVE distribution. |
450 |
y1 = y * delta |
y1 = y * delta |
451 |
return, d + floor(m1*30.6)+floor(y1*365.25)+5 |
return, d + floor(m1*30.6)+floor(y1*365.25)+5 |
452 |
end |
end |
453 |
|
|
454 |
function weekday,day,month,year |
function weekday,day,month,year |
455 |
;; compute weekday number for date |
;; compute weekday number for date |
456 |
nr = daynr(day,month,year) |
nr = daynr(day,month,year) |
457 |
return, nr mod 7 |
return, nr mod 7 |
458 |
end |
end |
459 |
|
|
460 |
pro plot_wday,day,month |
pro plot_wday,day,month |
461 |
;; Plot the weekday of a date in the first 10 years of this century. |
;; Plot the weekday of a date in the first 10 years of this century. |
462 |
years = 2000,+indgen(10) |
years = 2000,+indgen(10) |
469 |
@end example |
@end example |
470 |
|
|
471 |
The indentation probably looks funny, since it's different from the |
The indentation probably looks funny, since it's different from the |
472 |
settings you use, so use the @key{TAB} key in each line to automatically |
settings you use, so use the @key{TAB} key in each line to |
473 |
line it up (or more quickly @emph{select} the entire buffer with |
automatically line it up (or, more quickly, @emph{select} the entire |
474 |
@kbd{C-x h}, and indent the whole region with @kbd{C-M-\}). Notice how |
buffer with @kbd{C-x h}, and indent the whole region with |
475 |
different syntactical elements are highlighted in different colors, if |
@kbd{C-M-\}). Notice how different syntactical elements are |
476 |
you have set up support for font-lock. |
highlighted in different colors, if you have set up support for |
477 |
|
font-lock. |
478 |
|
|
479 |
Let's check out two particular editing features of IDLWAVE. Place the |
Let's check out two particular editing features of IDLWAVE. Place the |
480 |
cursor after the @code{end} statement of the @code{for} loop and press |
cursor after the @code{end} statement of the @code{for} loop and press |
481 |
@key{SPC}. IDLWAVE blinks back to the beginning of the block and |
@key{SPC}. IDLWAVE blinks back to the beginning of the block and |
482 |
changes the generic @code{end} to the specific @code{endfor} |
changes the generic @code{end} to the specific @code{endfor} |
483 |
automatically. Now place the cursor in any line you would like to split |
automatically (as long as the variable @code{idlwave-expand-generic-end} |
484 |
and press @kbd{M-@key{RET}}. The line is split at the cursor position, |
is turned on --- @pxref{Lesson II -- Customization}). Now place the |
485 |
with the continuation @samp{$} and indentation all taken care of. Use |
cursor in any line you would like to split and press @kbd{M-@key{RET}}. |
486 |
@kbd{C-/} to undo the last change. |
The line is split at the cursor position, with the continuation @samp{$} |
487 |
|
and indentation all taken care of. Use @kbd{C-/} to undo the last |
488 |
The procedure @code{plot_wday} is supposed to plot the weekday of a |
change. |
489 |
given date for the first 10 years of the 21st century. As in most code, |
|
490 |
there are a few bugs, which we are going to use IDLWAVE to help us fix. |
The procedure @code{plot_wday} is supposed to plot the day of the week |
491 |
|
of a given date for the first 10 years of the 21st century. As in |
492 |
|
most code, there are a few bugs, which we are going to use IDLWAVE to |
493 |
|
help us fix. |
494 |
|
|
495 |
First, let's launch the IDLWAVE shell. You do this with the command |
First, let's launch the IDLWAVE shell. You do this with the command |
496 |
@kbd{C-c C-s}. The Emacs window will split and display IDL running in a |
@kbd{C-c C-s}. The Emacs window will split or another window will popup |
497 |
shell interaction buffer. Type a few commands like @code{print,!PI} to |
to display IDL running in a shell interaction buffer. Type a few |
498 |
convince yourself that you can work there just as well as in a terminal, |
commands like @code{print,!PI} to convince yourself that you can work |
499 |
or the IDLDE. Use the arrow keys to cycle through your command history. |
there just as well as in a terminal, or the IDLDE. Use the arrow keys |
500 |
Are we having fun now? |
to cycle through your command history. Are we having fun now? |
501 |
|
|
502 |
Now go back to the source window and type @kbd{C-c C-d C-c} to compile |
Now go back to the source window and type @kbd{C-c C-d C-c} to compile |
503 |
the program. If you watch the shell buffer, you see that IDLWAVE types |
the program. If you watch the shell buffer, you see that IDLWAVE types |
511 |
|
|
512 |
Now we want to use the command to plot the day of the week on January |
Now we want to use the command to plot the day of the week on January |
513 |
1st. We could type the full command ourselves, but why do that? Go |
1st. We could type the full command ourselves, but why do that? Go |
514 |
back to the shell window, type @samp{plot_} and hit @key{TAB}. After a |
back to the shell window, type @samp{plot_} and hit @key{TAB}. After |
515 |
bit of a delay (while IDLWAVE initializes its routine info database, if |
a bit of a delay (while IDLWAVE initializes its routine info database, |
516 |
necessary), the window will split to show all procedures it knows |
if necessary), the window will split to show all procedures it knows |
517 |
starting with that string, and @w{@code{plot_wday}} should be one of |
starting with that string, and @w{@code{plot_wday}} should be one of |
518 |
them. Saving the buffer alerted IDLWAVE about this new routine. Click |
them. Saving the buffer alerted IDLWAVE about this new routine. |
519 |
with the middle mouse button on @code{plot_wday} and it will be copied |
Click with the middle mouse button on @code{plot_wday} and it will be |
520 |
to the shell buffer, or if you prefer, add @samp{w} to @samp{plot_} to |
copied to the shell buffer, or if you prefer, add @samp{w} to |
521 |
make it unambiguous, hit @key{TAB} again, and the full routine name will |
@samp{plot_} to make it unambiguous (depending on what other routines |
522 |
be completed. Now provide the two arguments: |
starting with @samp{plot_} you have installed on your system), hit |
523 |
|
@key{TAB} again, and the full routine name will be completed. Now |
524 |
|
provide the two arguments: |
525 |
|
|
526 |
@example |
@example |
527 |
plot_wday,1,1 |
plot_wday,1,1 |
528 |
@end example |
@end example |
529 |
|
|
530 |
and press @key{RET}. This fails with an error message telling you the |
@noindent and press @key{RET}. This fails with an error message telling |
531 |
@code{YT} keyword to plot is ambiguous. What are the allowed keywords |
you the @code{YT} keyword to plot is ambiguous. What are the allowed |
532 |
again? Go back to the source window and put the cursor into the `plot' |
keywords again? Go back to the source window and put the cursor into |
533 |
line, and press @kbd{C-c ?}. This shows the routine info window for the |
the `plot' line and press @kbd{C-c ?}. This shows the routine info |
534 |
plot routine, which contains a list of keywords, along with the argument |
window for the plot routine, which contains a list of keywords, along |
535 |
list. Oh, we wanted @code{YTITLE}. Fix that up. Recompile with |
with the argument list. Oh, we wanted @code{YTITLE}. Fix that up. |
536 |
@kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press |
Recompile with @kbd{C-c C-d C-c}. Jump back into the shell with |
537 |
the @key{UP} arrow to recall the previous command and execute again. |
@kbd{C-c C-s}, press the @key{UP} arrow to recall the previous command |
538 |
|
and execute again. |
539 |
|
|
540 |
This time we get a plot, but it is pretty ugly --- the points are all |
This time we get a plot, but it is pretty ugly --- the points are all |
541 |
connected with a line. Hmm, isn't there a way for @code{plot} to use |
connected with a line. Hmm, isn't there a way for @code{plot} to use |
542 |
symbols instead? What was that keyword? Position the cursor on the |
symbols instead? What was that keyword? Position the cursor on the |
543 |
plot line after a comma (where you'd normally type a keyword), and hit |
plot line after a comma (where you'd normally type a keyword), and hit |
544 |
@kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, there |
@kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, |
545 |
it is, @code{PSYM}. Middle click to insert it. An @samp{=} sign is |
there it is, @code{PSYM}. Middle click to insert it. An @samp{=} |
546 |
included for you too. Now what were the values of @code{PSYM} supposed |
sign is included for you too. Now what were the values of @code{PSYM} |
547 |
to be? With the cursor on or after the keyword, press @kbd{M-?} for |
supposed to be? With the cursor on or after the keyword, press |
548 |
online help (alternatively, you could have right clicked on the colored |
@kbd{M-?} for online help (alternatively, you could have right clicked |
549 |
keyword itself in the completion list). The online help window will pop |
on the colored keyword itself in the completion list). A browser will |
550 |
up showing the documentation for the @code{PYSM} keyword. OK, let's use |
pop up showing the HTML documentation for the @code{PYSM} keyword. |
551 |
diamonds=4. Fix this, recompile (you know the command by now: @kbd{C-c |
OK, let's use diamonds=4. Fix this, recompile (you know the command |
552 |
C-d C-c}, go back to the shell (if it's vanished, you know the command |
by now: @kbd{C-c C-d C-c}), go back to the shell (if it's vanished, |
553 |
to recall it by now: @kbd{C-c C-s}) and execute again. Now things look |
you know what to do: @kbd{C-c C-s}) and execute again. Now things |
554 |
pretty good. |
look pretty good. |
555 |
|
|
556 |
Let's try a different day --- how about April fool's day? |
Let's try a different day --- how about April fool's day? |
557 |
|
|
563 |
We've got a bug in the program, perhaps in the @code{daynr} function. |
We've got a bug in the program, perhaps in the @code{daynr} function. |
564 |
Let's put a breakpoint on the last line there. Position the cursor on |
Let's put a breakpoint on the last line there. Position the cursor on |
565 |
the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a |
the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a |
566 |
breakpoint (as you see in the shell window), and the line is highlighted |
breakpoint (as you see in the shell window), and the break line is |
567 |
in some way. Back to the shell buffer, re-execute the previous command. |
indicated. Back to the shell buffer, re-execute the previous command. |
568 |
IDL stops at the line with the breakpoint. Now hold down the SHIFT key |
IDL stops at the line with the breakpoint. Now hold down the SHIFT |
569 |
and click with the middle mouse button on a few variables there: |
key and click with the middle mouse button on a few variables there: |
570 |
@samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't the |
@samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't |
571 |
correct type. CONTROL-SHIFT middle-click on it for help. Well, it's an |
the correct type. CONTROL-SHIFT middle-click on it for help. Well, |
572 |
integer, so that's not the problem. Aha, @samp{y1} is zero, but it |
it's an integer, so that's not the problem. Aha, @samp{y1} is zero, |
573 |
should be the year, depending on delta. Shift click @samp{delta} to see |
but it should be the year, depending on delta. Shift click |
574 |
that it's 0. Below, we see the offending line: @samp{y1=y*delta...} the |
@samp{delta} to see that it's 0. Below, we see the offending line: |
575 |
multiplication should have been a minus sign! So fix the line to read: |
@samp{y1=y*delta...} the multiplication should have been a minus sign! |
576 |
|
Hit @kbd{q} to exit the debugging mode, and fix the line to read: |
577 |
|
|
578 |
@example |
@example |
579 |
y1 = y - delta |
y1 = y - delta |
584 |
Change the code to plot 100 years and see that every 28 years, the |
Change the code to plot 100 years and see that every 28 years, the |
585 |
sequence of weekdays repeats. |
sequence of weekdays repeats. |
586 |
|
|
587 |
@node Lesson II -- Customization, Lesson III -- Library Catalog, Lesson I -- Development Cycle, Getting Started |
@node Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started |
588 |
@section Lesson II: Customization |
@section Lesson II: Customization |
589 |
|
|
590 |
Emacs is probably the most customizable piece of software available, and |
Emacs is probably the most customizable piece of software ever |
591 |
it would be a shame if you did not make use of this and adapt IDLWAVE to |
written, and it would be a shame if you did not make use of this and |
592 |
your own preferences. Customizing Emacs or IDLWAVE is accomplished by |
adapt IDLWAVE to your own preferences. Customizing Emacs or IDLWAVE |
593 |
setting Lisp variables in the @file{.emacs} file in your home directory |
is accomplished by setting Lisp variables in the @file{.emacs} file in |
594 |
--- but do not be dismayed; for the most part, you can just copy and work |
your home directory --- but do not be dismayed; for the most part, you |
595 |
from the examples given here. |
can just copy and work from the examples given here. |
596 |
|
|
597 |
Let's first use a boolean variable. These are variables which you turn |
Let's first use a boolean variable. These are variables which you turn |
598 |
on or off, much like a checkbox. A value of @samp{t} means on, a value |
on or off, much like a checkbox. A value of @samp{t} means on, a value |
607 |
source buffer will be converted to upper case when you press @key{SPC} |
source buffer will be converted to upper case when you press @key{SPC} |
608 |
or @key{RET} right after the word. Try it out! @samp{if} changes to |
or @key{RET} right after the word. Try it out! @samp{if} changes to |
609 |
@samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this |
@samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this |
610 |
behavior, remove the option again from your @file{.emacs} file. |
behavior, remove the option again from your @file{.emacs} file and |
611 |
|
restart Emacs. |
612 |
|
|
613 |
You likely have your own indentation preferences for IDL code. For |
You likely have your own indentation preferences for IDL code. For |
614 |
example, some like to indent the main block of an IDL program from the |
example, some like to indent the main block of an IDL program from the |
635 |
variables. You can access it through the IDLWAVE menu in one of the |
variables. You can access it through the IDLWAVE menu in one of the |
636 |
@file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE |
@file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE |
637 |
Group}. Here you'll be presented with all the various variables grouped |
Group}. Here you'll be presented with all the various variables grouped |
638 |
into categories. You can navigate the hierarchy (e.g. Idlwave Code |
into categories. You can navigate the hierarchy (e.g. @samp{IDLWAVE |
639 |
Formatting->Idlwave Main Block Indent), read about the variables, change |
Code Formatting->Idlwave Abbrev And Indent Action->Idlwave Expand |
640 |
them, and `Save for Future Sessions'. Few of these variables need |
Generic End} to turn on @code{END} expansion), read about the variables, |
641 |
customization, but you can exercise considerable control over IDLWAVE's |
change them, and `Save for Future Sessions'. Few of these variables |
642 |
functionality with them. |
need customization, but you can exercise considerable control over |
643 |
|
IDLWAVE's functionality with them. |
644 |
|
|
645 |
You may also find the key bindings used for the debugging commands too |
You may also find the key bindings used for the debugging commands too |
646 |
long and complicated. Often we have heard such complaints, ``Do I |
long and complicated. Often we have heard complaints along the lines |
647 |
really have to type @kbd{C-c C-d C-c} to run a simple command?'' Due to |
of, ``Do I really have to go through the finger gymnastics of @kbd{C-c |
648 |
Emacs rules and conventions, shorter bindings cannot be set by default, |
C-d C-c} to run a simple command?'' Due to Emacs rules and |
649 |
but you can enable them. First, there is a way to assign all debugging |
conventions, shorter bindings cannot be set by default, but you can |
650 |
commands in a single sweep to other combinations. The only problem is |
easily enable them. First, there is a way to assign all debugging |
651 |
that we have to use something which Emacs does not need for other |
commands in a single sweep to another simpler combination. The only |
652 |
important commands. One good option is to execute debugging commands by |
problem is that we have to use something which Emacs does not need for |
653 |
holding down @key{CONTROL} and @key{SHIFT} while pressing a single |
other important commands. One good option is to execute debugging |
654 |
character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for |
commands by holding down @key{CONTROL} and @key{SHIFT} while pressing |
655 |
compiling the current source file, @kbd{C-S-a} for deleting all |
a single character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} |
656 |
breakpoints. You can enable this with: |
for compiling the current source file, @kbd{C-S-a} for deleting all |
657 |
|
breakpoints (try it, it's easier). You can enable this with: |
658 |
|
|
659 |
@lisp |
@lisp |
660 |
(setq idlwave-shell-debug-modifiers '(shift control)) |
(setq idlwave-shell-debug-modifiers '(shift control)) |
661 |
@end lisp |
@end lisp |
662 |
|
|
663 |
@noindent If you have a special keyboard with, for example, a |
@noindent If you have a special keyboard with, for example, a |
664 |
@key{HYPER} key, you could even shorten that: |
@key{SUPER} key, you could even shorten that: |
665 |
|
|
666 |
@lisp |
@lisp |
667 |
(setq idlwave-shell-debug-modifiers '(hyper)) |
(setq idlwave-shell-debug-modifiers '(super)) |
668 |
@end lisp |
@end lisp |
669 |
|
|
670 |
@noindent to get compilation on @kbd{H-c}. Often, a modifier key like |
@noindent to get compilation on @kbd{S-c}. Often, a modifier key like |
671 |
@key{HYPER} or @key{SUPER} is bound or can be bound to an otherwise |
@key{SUPER} or @key{HYPER} is bound or can be bound to an otherwise |
672 |
unused key -- consult your system documentation. |
unused key on your keyboard --- consult your system documentation. |
673 |
|
|
674 |
You can also assign specific commands to keys. This you must do in the |
You can also assign specific commands to keys. This you must do in the |
675 |
@emph{mode-hook}, a special function which is run when a new buffer gets |
@emph{mode-hook}, a special function which is run when a new IDLWAVE |
676 |
set up. Keybindings can only be done when the buffer exists. The |
buffer gets set up. The possibilities for key customization are |
677 |
possibilities for key customization are endless. Here we set function |
endless. Here we set function keys f4-f8 to common debugging commands. |
|
keys f5-f8 to common debugging commands. |
|
678 |
|
|
679 |
@lisp |
@lisp |
680 |
;; First for the source buffer |
;; First for the source buffer |
681 |
(add-hook 'idlwave-mode-hook |
(add-hook 'idlwave-mode-hook |
682 |
(lambda () |
(lambda () |
683 |
|
(local-set-key [f4] 'idlwave-shell-retall) |
684 |
(local-set-key [f5] 'idlwave-shell-break-here) |
(local-set-key [f5] 'idlwave-shell-break-here) |
685 |
(local-set-key [f6] 'idlwave-shell-clear-current-bp) |
(local-set-key [f6] 'idlwave-shell-clear-current-bp) |
686 |
(local-set-key [f7] 'idlwave-shell-cont) |
(local-set-key [f7] 'idlwave-shell-cont) |
688 |
;; Then for the shell buffer |
;; Then for the shell buffer |
689 |
(add-hook 'idlwave-shell-mode-hook |
(add-hook 'idlwave-shell-mode-hook |
690 |
(lambda () |
(lambda () |
691 |
|
(local-set-key [f4] 'idlwave-shell-retall) |
692 |
(local-set-key [f5] 'idlwave-shell-break-here) |
(local-set-key [f5] 'idlwave-shell-break-here) |
693 |
(local-set-key [f6] 'idlwave-shell-clear-current-bp) |
(local-set-key [f6] 'idlwave-shell-clear-current-bp) |
694 |
(local-set-key [f7] 'idlwave-shell-cont) |
(local-set-key [f7] 'idlwave-shell-cont) |
695 |
(local-set-key [f8] 'idlwave-shell-clear-all-bp))) |
(local-set-key [f8] 'idlwave-shell-clear-all-bp))) |
696 |
@end lisp |
@end lisp |
697 |
|
|
698 |
@node Lesson III -- Library Catalog, , Lesson II -- Customization, Getting Started |
@node Lesson III -- User Catalog, , Lesson II -- Customization, Getting Started |
699 |
@section Lesson III: Library Catalog |
@section Lesson III: User and Library Catalogs |
700 |
|
|
701 |
We have already used the routine info display in the first part of this |
We have already used the routine info display in the first part of this |
702 |
tutorial. This was the key @kbd{C-c ?} which displays information about |
tutorial. This was the invoked using @kbd{C-c ?}, and displays |
703 |
the IDL routine near the cursor position. Wouldn't it be nice |
information about the IDL routine near the cursor position. Wouldn't it |
704 |
to have the same available for your own library routines and for the |
be nice to have the same kind of information available for your own |
705 |
huge amount of code in major extension libraries like JHUPL or the |
routines and for the huge amount of code in major libraries like JHUPL |
706 |
IDL-Astro library? To do this, you must give IDLWAVE a chance to study |
or the IDL-Astro library? In many cases, you may already have this |
707 |
these routines first. We call this @emph{Building the library catalog}. |
information. Files named @file{.idlwave_catalog} in library directories |
708 |
|
contain scanned information on the routines in that directory; many |
709 |
From the IDLWAVE entry in the menu bar, select @code{Routine Info/Select |
popular libraries ship with these ``library catalogs'' pre-scanned. |
710 |
Catalog Directories}. If necessary, start the shell first with @kbd{C-c |
Users can scan their own routines in one of two ways: either using the |
711 |
C-s} (@pxref{Starting the Shell}). IDLWAVE will find out about the IDL |
supplied tool to scan directories and build their own |
712 |
@code{!PATH} variable and offer a list of directories on the path. |
@file{.idlwave_catalog} files, or using the built-in method to create a |
713 |
Simply select them all (or whichever you want) and click on the |
single ``user catalog'', which we'll show here. @xref{Catalogs}, for |
714 |
@samp{Scan&Save} button. Then go for a cup of coffee while IDLWAVE |
more information on choosing which method to use. |
715 |
collects information for each and every IDL routine on your search path. |
|
716 |
All this information is written to the file @file{.idlcat} in your home |
To build a user catalog, select @code{Routine Info/Select Catalog |
717 |
directory and will from now one be automatically loaded whenever you use |
Directories} from the IDLWAVE entry in the menu bar. If necessary, |
718 |
|
start the shell first with @kbd{C-c C-s} (@pxref{Starting the Shell}). |
719 |
|
IDLWAVE will find out about the IDL @code{!PATH} variable and offer a |
720 |
|
list of directories on the path. Simply select them all (or whichever |
721 |
|
you want --- directories with existing library catalogs will not be |
722 |
|
selected by default) and click on the @samp{Scan&Save} button. Then |
723 |
|
go for a cup of coffee while IDLWAVE collects information for each and |
724 |
|
every IDL routine on your search path. All this information is |
725 |
|
written to the file @file{.idlwave/idlusercat.el} in your home |
726 |
|
directory and will from now on automatically load whenever you use |
727 |
IDLWAVE. You may find it necessary to rebuild the catalog on occasion |
IDLWAVE. You may find it necessary to rebuild the catalog on occasion |
728 |
as your local libraries change. Try to use routine info (@kbd{C-c ?}) |
as your local libraries change, or build a library catalog for those |
729 |
or completion (@kbd{M-@key{TAB}}) while on any routine or partial routine |
directories instead. Invoke routine info (@kbd{C-c ?}) or completion |
730 |
name you know to be located in the library. E.g., if you have scanned |
(@kbd{M-@key{TAB}}) on any routine or partial routine name you know to |
731 |
the IDL-Astro library: |
be located in the library. E.g., if you have scanned the IDL-Astro |
732 |
|
library: |
733 |
|
|
734 |
@example |
@example |
735 |
a=readf@key{M-<TAB>} |
a=readf@key{M-@key{TAB}} |
736 |
@end example |
@end example |
737 |
|
|
|
|
|
738 |
expands to `readfits('. Then try |
expands to `readfits('. Then try |
739 |
|
|
740 |
@example |
@example |
749 |
@end example |
@end example |
750 |
|
|
751 |
I hope you made it until here. Now you are set to work with IDLWAVE. |
I hope you made it until here. Now you are set to work with IDLWAVE. |
752 |
On the way you will want to change other things, and to learn more about |
On the way you will want to change other things, and to learn more |
753 |
the possibilities not discussed in this short tutorial. Read the |
about the possibilities not discussed in this short tutorial. Read |
754 |
manual, look at the documentation strings of interesting variables (with |
the manual, look at the documentation strings of interesting variables |
755 |
@kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining |
(with @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the |
756 |
questions on the newsgroup @code{comp.lang.idl-pvwave}. |
remaining questions on the newsgroup @code{comp.lang.idl-pvwave}. |
757 |
|
|
758 |
@node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top |
@node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top |
759 |
@chapter The IDLWAVE Major Mode |
@chapter The IDLWAVE Major Mode |
786 |
|
|
787 |
@menu |
@menu |
788 |
* Code Indentation:: Reflecting the logical structure |
* Code Indentation:: Reflecting the logical structure |
789 |
* Continued Statement Indentation:: |
* Continued Statement Indentation:: |
790 |
* Comment Indentation:: Special indentation for comment lines |
* Comment Indentation:: Special indentation for comment lines |
791 |
* Continuation Lines:: Splitting statements over lines |
* Continuation Lines:: Splitting statements over lines |
792 |
* Syntax Highlighting:: Font-lock support |
* Syntax Highlighting:: Font-lock support |
793 |
* Octals and Highlighting:: Why "123 causes problems |
* Octals and Highlighting:: Why "123 causes problems |
794 |
@end menu |
@end menu |
795 |
|
|
796 |
The IDL language, with it's early roots in FORTRAN, modern |
The IDL language, with its early roots in FORTRAN, modern |
797 |
implementation in C, and liberal borrowing of features of many vector |
implementation in C, and liberal borrowing of features of many vector |
798 |
languages along its 25+ year history, has inherited an unusual mix of |
and other languages along its 25+ year history, has inherited an |
799 |
syntax elements. Left to his or her own devices, a novice IDL |
unusual mix of syntax elements. Left to his or her own devices, a |
800 |
programmer will often conjure code which is very difficult to read and |
novice IDL programmer will often conjure code which is very difficult |
801 |
impossible to adapt. Much can be gleaned from studying available IDL |
to read and impossible to adapt. Much can be gleaned from studying |
802 |
code libraries for coding style pointers, but, due to the variety of |
available IDL code libraries for coding style pointers, but, due to |
803 |
IDL syntax elements, replicating this style can be challenging at |
the variety of IDL syntax elements, replicating this style can be |
804 |
best. Luckily, IDLWAVE understands the structure of IDL code very |
challenging at best. Luckily, IDLWAVE understands the structure of |
805 |
well, and takes care of almost all formatting issues for you. After |
IDL code very well, and takes care of almost all formatting issues for |
806 |
configuring it to match your coding standards, you can rely on it to |
you. After configuring it to match your coding standards, you can |
807 |
help keep your code neat and organized. |
rely on it to help keep your code neat and organized. |
808 |
|
|
|
@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). @xref{Actions}, for information how to impose |
|
|
additional formatting conventions on foreign code. |
|
809 |
|
|
810 |
@node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting |
@node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting |
811 |
@subsection Code Indentation |
@subsection Code Indentation |
819 |
@code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and |
@code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and |
820 |
continuation lines. |
continuation lines. |
821 |
|
|
822 |
@defopt idlwave-main-block-indent (@code{0}) |
@cindex Foreign code, adapting |
823 |
|
@cindex Indentation, of foreign code |
824 |
|
@kindex C-M-\ |
825 |
|
To re-indent a larger portion of code (e.g. when working with foreign code |
826 |
|
written with different conventions), use @kbd{C-M-\} |
827 |
|
(@code{indent-region}) after marking the relevant code. Useful marking |
828 |
|
commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the |
829 |
|
current subprogram). @xref{Actions}, for information how to impose |
830 |
|
additional formatting conventions on foreign code. |
831 |
|
|
832 |
|
@defopt idlwave-main-block-indent (@code{0}) |
833 |
Extra indentation for the main block of code. That is the block between |
Extra indentation for the main block of code. That is the block between |
834 |
the FUNCTION/PRO statement and the END statement for that program |
the FUNCTION/PRO statement and the END statement for that program |
835 |
unit. |
unit. |
887 |
maximum additional indentation beyond the basic indent to be |
maximum additional indentation beyond the basic indent to be |
888 |
tolerated, otherwise defaulting to a fixed-offset from the enclosing |
tolerated, otherwise defaulting to a fixed-offset from the enclosing |
889 |
indent (the size of which offset is set in |
indent (the size of which offset is set in |
890 |
@code{idlwave-continuation-indent}). Also, since the indentation |
@code{idlwave-continuation-indent}). As a special case, continuations |
891 |
level can be somewhat dynamic in continued statements with special |
of routine calls without any arguments or keywords will @emph{not} |
892 |
continuation indentation, especially if |
align the continued line, under the assumption that you continued |
893 |
|
because you needed the space. |
894 |
|
|
895 |
|
Also, since the indentation level can be somewhat dynamic in continued |
896 |
|
statements with special continuation indentation, especially if |
897 |
@code{idlwave-max-extra-continuation-indent} is small, the key |
@code{idlwave-max-extra-continuation-indent} is small, the key |
898 |
@kbd{C-u @key{TAB}} will re-indent all lines in the current statement. |
@kbd{C-u @key{TAB}} will re-indent all lines in the current statement. |
899 |
Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil}, overrides |
Note that @code{idlwave-indent-to-open-paren}, if non-nil, overrides |
900 |
the @code{idlwave-max-extra-continuation-indent} limit, for |
the @code{idlwave-max-extra-continuation-indent} limit, for |
901 |
parentheses only, forcing them always to line up. |
parentheses only, forcing them always to line up. |
902 |
|
|
1030 |
|
|
1031 |
@defopt idlwave-use-last-hang-indent (@code{nil}) |
@defopt idlwave-use-last-hang-indent (@code{nil}) |
1032 |
Non-@code{nil} means use last match on line for |
Non-@code{nil} means use last match on line for |
1033 |
@code{idlwave-indent-regexp}. |
@code{idlwave-indent-regexp}. |
1034 |
@end defopt |
@end defopt |
1035 |
|
|
1036 |
@node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting |
@node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting |
1058 |
|
|
1059 |
@defopt idlwave-default-font-lock-items |
@defopt idlwave-default-font-lock-items |
1060 |
Items which should be fontified on the default fontification level |
Items which should be fontified on the default fontification level |
1061 |
2. |
2. |
1062 |
@end defopt |
@end defopt |
1063 |
|
|
1064 |
@node Octals and Highlighting, , Syntax Highlighting, Code Formatting |
@node Octals and Highlighting, , Syntax Highlighting, Code Formatting |
1066 |
@cindex Syntax highlighting, Octals |
@cindex Syntax highlighting, Octals |
1067 |
@cindex Highlighting of syntax, Octals |
@cindex Highlighting of syntax, Octals |
1068 |
|
|
1069 |
A rare syntax highlighting problem results from the extremely |
A rare syntax highlighting problem results from an extremely unfortunate |
1070 |
unfortunate notation for octal numbers in IDL: @code{"123}. This |
notation for octal numbers in IDL: @code{"123}. This unpaired quotation |
1071 |
unpaired quotation mark is very difficult to parse, given that it can be |
mark is very difficult to parse, given that it can be mixed on a single |
1072 |
mixed on a single line with any number of strings. Emacs will |
line with any number of strings. Emacs will incorrectly identify this |
1073 |
incorrectly identify this as a string, and the highlighting of following |
as a string, and the highlighting of following lines of code can be |
1074 |
lines of code can be distorted, since the string is never terminated. |
distorted, since the string is never terminated. |
1075 |
|
|
1076 |
One solution to this involves terminating the mistakenly identified |
One solution to this involves terminating the mistakenly identified |
1077 |
string yourself by providing a closing quotation mark in a comment: |
string yourself by providing a closing quotation mark in a comment: |
1105 |
even thousands more (each with a few to tens of keywords and |
even thousands more (each with a few to tens of keywords and |
1106 |
arguments). This large command set can make it difficult to remember |
arguments). This large command set can make it difficult to remember |
1107 |
the calling sequence and keywords for the routines you use, but |
the calling sequence and keywords for the routines you use, but |
1108 |
IDLWAVE can help. It builds up routine information using a wide |
IDLWAVE can help. It builds up routine information from a wide |
1109 |
variety of sources: IDLWAVE in fact knows far more about the routines |
variety of sources; IDLWAVE in fact knows far more about the |
1110 |
on your system than IDL itself. It maintains a list of all built-in |
@samp{.pro} routines on your system than IDL itself! It maintains a |
1111 |
routines, with calling sequences and keywords@footnote{This list is |
list of all built-in routines, with calling sequences and |
1112 |
created by scanning the IDL manuals and might contain (very few) |
keywords@footnote{This list is created by scanning the IDL manuals and |
1113 |
errors. Please report any errors to the maintainer, so that they can |
might contain (very few) errors. Please report any errors to the |
1114 |
be fixed.}. It also scans Emacs buffers and library files for routine |
maintainer, so that they can be fixed.}. It also scans Emacs buffers |
1115 |
definitions, and queries the IDLWAVE-Shell for information about |
for routine definitions, queries the IDLWAVE-Shell for information |
1116 |
routines currently compiled there. This information is updated |
about routines currently compiled there, and automatically locates |
1117 |
|
library and user-created catalogs. This information is updated |
1118 |
automatically, and so should usually be current. To force a global |
automatically, and so should usually be current. To force a global |
1119 |
update and refresh the routine information, use @kbd{C-c C-i} |
update and refresh the routine information, use @kbd{C-c C-i} |
1120 |
(@code{idlwave-update-routine-info}). |
(@code{idlwave-update-routine-info}). |
1136 |
On positions 1,2 and 8, information about the @samp{plot} procedure will |
On positions 1,2 and 8, information about the @samp{plot} procedure will |
1137 |
be shown. On positions 3,4, and 7, the @samp{alog} function will be |
be shown. On positions 3,4, and 7, the @samp{alog} function will be |
1138 |
described, while positions 5 and 6 will investigate the @samp{sin} |
described, while positions 5 and 6 will investigate the @samp{sin} |
1139 |
function. |
function. |
1140 |
|
|
1141 |
When you ask for routine information about an object method, and the |
When you ask for routine information about an object method, and the |
1142 |
method exists in several classes, IDLWAVE queries for the class of the |
method exists in several classes, IDLWAVE queries for the class of the |
1143 |
object, unless the class is already known through a text property on the |
object, unless the class is already known through a text property on the |
1144 |
@samp{->} operator (@pxref{Object Method Completion and Class |
@samp{->} operator (@pxref{Object Method Completion and Class |
1145 |
Ambiguity}), or by having been explicitly included in the call |
Ambiguity}), or by having been explicity included in the call |
1146 |
(e.g. @code{a->myclass::Foo}). |
(e.g. @code{a->myclass::Foo}). |
1147 |
|
|
1148 |
@cindex Calling sequences |
@cindex Calling sequences |
1155 |
Usage: XMANAGER, NAME, ID |
Usage: XMANAGER, NAME, ID |
1156 |
Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER |
Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER |
1157 |
JUST_REG MODAL NO_BLOCK |
JUST_REG MODAL NO_BLOCK |
1158 |
Source: SystemLib [CSB] /soft1/idl53/lib/xmanager.pro |
Source: SystemLib [LCSB] /soft1/idl53/lib/xmanager.pro |
1159 |
@end example |
@end example |
1160 |
|
|
1161 |
@cindex Categories, of routines |
@cindex Categories, of routines |
1167 |
@cindex @code{!DIR}, IDL variable |
@cindex @code{!DIR}, IDL variable |
1168 |
|
|
1169 |
If a definition of this routine exists in several files accessible to |
If a definition of this routine exists in several files accessible to |
1170 |
IDLWAVE, several @samp{Source} lines will point to the different files. |
IDLWAVE, several @samp{Source} lines will point to the different |
1171 |
This may indicate that your routine is shadowing a library routine, |
files. This may indicate that your routine is shadowing a system |
1172 |
which may or may not be what you want (@pxref{Load-Path Shadows}). The |
library routine, which may or may not be what you want |
1173 |
information about the calling sequence and keywords is derived from the |
(@pxref{Load-Path Shadows}). The information about the calling |
1174 |
first source listed. Library routines are supported only if you have |
sequence and keywords is derived from the first source listed. |
1175 |
scanned your local IDL libraries (@pxref{Library Catalog}). The source |
Library routines are available only if you have scanned your local IDL |
1176 |
entry consists of a @emph{source category}, a set of @emph{flags} and |
directories or are using pre-scanned libraries (@pxref{Catalogs}). |
1177 |
the path to the @emph{source file}. The following categories exist: |
The source entry consists of a @emph{source category}, a set of |
1178 |
|
@emph{flags} and the path to the @emph{source file}. The following |
1179 |
|
default categories exist: |
1180 |
|
|
1181 |
@multitable @columnfractions .15 .85 |
@multitable @columnfractions .15 .85 |
1182 |
@item @i{System} |
@item @i{System} |
1183 |
@tab A system routine of unknown origin. When the system library has |
@tab A system routine of unknown origin. When the system library has |
1184 |
been scanned (@pxref{Library Catalog}), this category will automatically |
been scanned as part of a catalog (@pxref{Catalogs}), this category |
1185 |
split into the next two. |
will automatically split into the next two. |
1186 |
@item @i{Builtin} |
@item @i{Builtin} |
1187 |
@tab A builtin system routine with no source code available. |
@tab A builtin system routine with no source code available. |
1188 |
@item @i{SystemLib} |
@item @i{SystemLib} |
1194 |
@item @i{Other} |
@item @i{Other} |
1195 |
@tab Any other routine with a file not known to be on the search path. |
@tab Any other routine with a file not known to be on the search path. |
1196 |
@item @i{Unresolved} |
@item @i{Unresolved} |
1197 |
@tab An otherwise unkown routine the shell lists as unresolved |
@tab An otherwise unkown routine the shell lists as unresolved |
1198 |
(referenced, but not compiled). |
(referenced, but not compiled). |
1199 |
@end multitable |
@end multitable |
1200 |
|
|
1201 |
You can create additional categories based on the routine's filepath |
Any routines discovered in library catalogs (@pxref{Library |
1202 |
with the variable @code{idlwave-special-lib-alist}. This is useful for |
Catalogs}), will display the category assigned during creation, |
1203 |
easy discrimination of various libraries, or even versions of the same |
e.g. @samp{NasaLib}. For routines not discovered in this way, you can |
1204 |
library. |
create additional categories based on the routine's filename using the |
1205 |
|
variable @code{idlwave-special-lib-alist}. |
1206 |
|
|
1207 |
@cindex Flags, in routine info |
@cindex Flags, in routine info |
1208 |
@cindex Duplicate routines |
@cindex Duplicate routines |
1209 |
@cindex Multiply defined routines |
@cindex Multiply defined routines |
1210 |
@cindex Routine definitions, multiple |
@cindex Routine definitions, multiple |
1211 |
The flags @code{[CSB]} indicate the source of the information IDLWAVE |
The flags @code{[LCSB]} indicate the source of the information IDLWAVE |
1212 |
has regarding the file: from a library catalog (@w{@code{[C--]}}, |
has regarding the file: from a library catalog (@w{@code{[L---]}}), |
1213 |
@pxref{Library Catalog}), from the IDL Shell (@w{@code{[-S-]}}) or from |
from a user catalog (@w{@code{[-C--]}}, from the IDL Shell |
1214 |
an Emacs buffer (@w{@code{[--B]}}). Combinations are possible (a |
(@w{@code{[--S-]}}) or from an Emacs buffer (@w{@code{[---B]}}). |
1215 |
compiled library routine visited in a buffer might read |
Combinations are possible (a compiled library routine visited in a |
1216 |
@w{@code{[CSB]}}). If a file contains multiple definitions of the same |
buffer might read @w{@code{[L-SB]}}). If a file contains multiple |
1217 |
routine, the file name will be prefixed with @samp{(Nx)} where @samp{N} |
definitions of the same routine, the file name will be prefixed with |
1218 |
is the number of definitions. |
@samp{(Nx)} where @samp{N} is the number of definitions. |
1219 |
|
|
1220 |
@cindex Online Help from the routine info buffer |
@cindex Online Help from the routine info buffer |
1221 |
@cindex Active text, in routine info |
@cindex Active text, in routine info |
1230 |
@item @i{Usage} |
@item @i{Usage} |
1231 |
@tab If online help is installed, a click with the @emph{right} mouse |
@tab If online help is installed, a click with the @emph{right} mouse |
1232 |
button on the @i{Usage:} line will access the help for the |
button on the @i{Usage:} line will access the help for the |
1233 |
routine (@pxref{Online Help}). |
routine (@pxref{Online Help}). |
1234 |
@item @i{Keyword} |
@item @i{Keyword} |
1235 |
@tab Online help about keywords is also available with the |
@tab Online help about keywords is also available with the |
1236 |
@emph{right} mouse button. Clicking on a keyword with the @emph{middle} |
@emph{right} mouse button. Clicking on a keyword with the @emph{middle} |
1266 |
@end defopt |
@end defopt |
1267 |
|
|
1268 |
|
|
1269 |
|
@ifhtml |
1270 |
|
<A NAME="ONLINE_HELP"></A> |
1271 |
|
@end ifhtml |
1272 |
@node Online Help, Completion, Routine Info, The IDLWAVE Major Mode |
@node Online Help, Completion, Routine Info, The IDLWAVE Major Mode |
1273 |
@section Online Help |
@section Online Help |
1274 |
|
|
1275 |
@cindex Online Help |
@cindex Online Help |
1276 |
@cindex @file{idlw-help.txt} |
@cindex @file{idlw-help.txt} |
1277 |
@cindex @file{idlw-help.el} |
@cindex @file{idlw-help.el} |
|
@cindex IDL manual, ASCII version |
|
1278 |
@cindex Installing online help |
@cindex Installing online help |
1279 |
@cindex Online Help, Installation |
@cindex Online Help, Installation |
1280 |
@cindex Speed, of online help |
@cindex Speed, of online help |
|
For IDL system routines, RSI provides extensive documentation. IDLWAVE |
|
|
can access an ASCII version of this documentation very quickly and |
|
|
accurately. This is @emph{much} faster than using the IDL online help |
|
|
application, because IDLWAVE usually gets you to the right place in the |
|
|
documentation directly, without any additional browsing and scrolling. |
|
|
For this online help to work, an ASCII version of the IDL documentation, |
|
|
which is not part of the standalone IDLWAVE distribution, is required. |
|
|
The necessary help files can be downloaded from |
|
|
@uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. The text |
|
|
extracted from the PDF files is fine for normal documentation |
|
|
paragraphs, but graphics and multiline equations will not be well |
|
|
formatted. See also @ref{Documentation Scan}. |
|
|
|
|
|
@cindex Updated online help |
|
|
@cindex Online help, updates |
|
|
@cindex @code{<NEW>..</NEW>} |
|
|
Occasionally RSI releases a synopsis of new features in an IDL release, |
|
|
without simultaneously updating the documentation files, instead |
|
|
preferring a @i{What's New} document which describes the changes. These |
|
|
updates are incorporated directly into the IDLWAVE online help, and are |
|
|
delimited in @code{<NEW>..</NEW>} blocks. |
|
|
|
|
|
@cindex Source code, as online help |
|
|
@cindex DocLib header, as online help |
|
|
For routines which are not documented in the IDL 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 |
|
|
appropriate keyword). Otherwise the routine definition statement |
|
|
(@code{pro}/@code{function}) is shown. |
|
1281 |
|
|
1282 |
@cindex Structure tags, in online help |
For IDL system routines, RSI provides extensive documentation. |
1283 |
@cindex Class tags, in online help |
IDLWAVE can access an HTML version of this documentation very quickly |
1284 |
Help is also available for class structure tags (@code{self.TAG}), and |
and accurately. This is @emph{much} faster than using the IDL online |
1285 |
generic structure tags, if structure tag completion is enabled |
help application, because IDLWAVE usually gets you to the right place |
1286 |
(@pxref{Structure Tag Completion}). This is implemented by visiting the |
in the documentation directly --- e.g. a specific keyword of a routine |
1287 |
tag within the class or structure definition source itself. Help is not |
--- without any additional browsing and scrolling. For this online |
1288 |
available on built-in system class tags. |
help to work, an HTML version of the IDL documentation, which is not |
1289 |
|
part of the standalone IDLWAVE distribution, is required. The |
1290 |
|
necessary files can be downloaded from @uref{@value{IDLWAVE-HOMEPAGE}, |
1291 |
|
the maintainers webpage}. There are a variety of options for |
1292 |
|
displaying the HTML help: see below. Help for routines without HTML |
1293 |
|
documentation is also available, using the routine documentation |
1294 |
|
header and/or source. |
1295 |
|
|
1296 |
@kindex M-? |
@kindex M-? |
1297 |
In any IDL program (or, as with most IDLWAVE commands, in the IDL |
In any IDL program (or, as with most IDLWAVE commands, in the IDL |
1307 |
@tab A keyword parameter of a routine. |
@tab A keyword parameter of a routine. |
1308 |
@item @i{System Variable} |
@item @i{System Variable} |
1309 |
@tab System variables like @code{!DPI}. |
@tab System variables like @code{!DPI}. |
1310 |
|
@item @i{System Variable Tags} |
1311 |
|
@tab System variables tags like @code{!D.X_SIZE}. |
1312 |
@item @i{IDL Statement} |
@item @i{IDL Statement} |
1313 |
@tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. |
@tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. |
1314 |
@item @i{Class name} |
@item @i{Class name} |
1318 |
@item @i{Executive Command} |
@item @i{Executive Command} |
1319 |
@tab An executive command like @code{.RUN}. Mostly useful in the shell. |
@tab An executive command like @code{.RUN}. Mostly useful in the shell. |
1320 |
@item @i{Structure Tags} |
@item @i{Structure Tags} |
1321 |
@tab In structure tags like @code{state.xsize} |
@tab Structure tags like @code{state.xsize} |
1322 |
@item @i{Structure Tags} |
@item @i{Class Tags} |
1323 |
@tab In class tags like @code{self.value}. |
@tab Class tags like @code{self.value}. |
1324 |
@item @i{Default} |
@item @i{Default} |
1325 |
@tab The routine that would be selected for routine info display. |
@tab The routine that would be selected for routine info display. |
1326 |
@end multitable |
@end multitable |
1327 |
|
|
1328 |
@cindex @code{OBJ_NEW}, special online help |
@cindex @code{OBJ_NEW}, special online help |
1329 |
Note that the @code{OBJ_NEW} function is special in that the help |
Note that the @code{OBJ_NEW} function is special in that the help |
1330 |
displayed depends on the cursor position: If the cursor is on the |
displayed depends on the cursor position. If the cursor is on the |
1331 |
@samp{OBJ_NEW}, this function is described. If it is on the class name |
@samp{OBJ_NEW}, this function is described. If it is on the class |
1332 |
inside the quotes, the documentation for the class is pulled up. If the |
name inside the quotes, the documentation for the class is pulled up. |
1333 |
cursor is @emph{after} the class name, anywhere in the argument list, |
If the cursor is @emph{after} the class name, anywhere in the argument |
1334 |
the documentation for the corresponding @code{Init} method and its |
list, the documentation for the corresponding @code{Init} method and |
1335 |
keywords is targeted. |
its keywords is targeted. |
1336 |
|
|
1337 |
@noindent Apart from source buffers, there are two more places from |
Apart from an IDLWAVE buffer or shell, there are two more places from |
1338 |
which online help can be accessed. |
which online help can be accessed. |
1339 |
|
|
1340 |
@itemize @bullet |
@itemize @bullet |
1350 |
program source itself) will be emphasized (e.g. colored blue). |
program source itself) will be emphasized (e.g. colored blue). |
1351 |
@end itemize |
@end itemize |
1352 |
@noindent |
@noindent |
1353 |
In both cases, a blue face indicates that the item is documented in the |
In both cases, a blue face indicates that the item is documented in |
1354 |
IDL manual, but an attempt will be made to visit non-blue items directly |
the IDL manual, but an attempt will be made to visit non-blue items |
1355 |
in the originating source file. |
directly in the originating source file. |
1356 |
|
|
1357 |
@cindex Help application, key bindings |
|
1358 |
@cindex Key bindings, in help application |
@menu |
1359 |
The help window is normally displayed in a separate frame. The |
* Help with HTML Documentation:: |
1360 |
following commands can be used to navigate inside the help system: |
* Help with Source:: |
1361 |
|
@end menu |
1362 |
|
|
1363 |
|
@node Help with HTML Documentation, Help with Source, Online Help, Online Help |
1364 |
|
@subsection Help with HTML Documentation |
1365 |
|
@cindex HTML Help |
1366 |
|
@cindex Help using HTML manuals |
1367 |
|
@cindex IDL manual, HTML version |
1368 |
|
|
1369 |
|
Help using the HTML documentation is invoked with the built-in Emacs |
1370 |
|
command @code{browse-url}, which displays the relevant help topic in a |
1371 |
|
browser of your choosing. There are many possible browsers to choose |
1372 |
|
among, with differing advantages and disadvantages. The variable |
1373 |
|
@code{idlwave-help-browser-function} controls which browser help is |
1374 |
|
sent to. This function is used to set the variable |
1375 |
|
@code{browse-url-browser-function} locally for IDLWAVE help only. |
1376 |
|
Customize this variable to see what choices of browsers your system |
1377 |
|
offers. |
1378 |
|
|
1379 |
|
Certain browsers like @code{w3} (bundled with many versions of Emacs) |
1380 |
|
and @code{w3m} (@uref{http://emacs-w3m.namazu.org/}, the author's help |
1381 |
|
browser of choice) are run within Emacs, and use Emacs buffers to |
1382 |
|
display the HTML help. This can be convenient, especially on small |
1383 |
|
displays, and images can even be displayed in-line on new Emacs |
1384 |
|
versions. However, better formatting results are often achieved with |
1385 |
|
external browsers, like Mozilla. IDLWAVE assumes any browser function |
1386 |
|
containing "w3" is displayed in a local buffer. If you are using |
1387 |
|
another Emacs-local browser for which this is not true, set the |
1388 |
|
variable @code{idlwave-help-browser-is-local}. |
1389 |
|
|
1390 |
|
@emph{N.B. For Windows users}: IDLWAVE can bring up RSI help directly |
1391 |
|
in the Microsoft HTMLHelp documentation supplied with IDL: no |
1392 |
|
additional help files are needed. Be sure to set |
1393 |
|
@code{idlwave-system-directory} and the help file will be found |
1394 |
|
automatically (or, alternatively, specify its location directly with |
1395 |
|
@code{idlwave-html-help-location}). The variable |
1396 |
|
@code{idlwave-help-use-hh} controls whether HTMLHelp is used, and |
1397 |
|
which application is called to invoke it (@code{HH} is the default). |
1398 |
|
The free helper application @code{KEYHH} |
1399 |
|
(@uref{http://www.keyworks.net/keyhh.htm}) can be used instead, and is |
1400 |
|
preferrable, as it permits loading new help topics into the same help |
1401 |
|
window. @code{KEYHH} must be downloaded and installed separately. |
1402 |
|
|
1403 |
|
@xref{HTML Help Browser Tips}, for more information on selecting and |
1404 |
|
configuring a browser for use with IDL's HTML help system. |
1405 |
|
|
1406 |
|
@defopt idlwave-html-help-location @file{/usr/local/etc} |
1407 |
|
The directory where the @file{idl_html_help} dir or @file{idl.chm} |
1408 |
|
HTMLHelp files live. |
1409 |
|
@end defopt |
1410 |
|
|
1411 |
|
@defopt idlwave-help-use-hh @code{nil} |
1412 |
|
If set to @code{'hh} or @code{'keyhh}, use Windows native HTMLHelp |
1413 |
|
with the specified help application. |
1414 |
|
@end defopt |
1415 |
|
|
1416 |
|
@defopt idlwave-help-browser-function |
1417 |
|
The browser function to use to display IDLWAVE HTML help. Should be |
1418 |
|
one of the functions available for setting |
1419 |
|
@code{browse-url-browser-function}, which see. |
1420 |
|
@end defopt |
1421 |
|
|
1422 |
|
@defopt idlwave-help-browser-is-local |
1423 |
|
Is the browser selected in @code{idlwave-help-browser-function} run in a |
1424 |
|
local Emacs buffer? Defaults to @code{t} if the function contains |
1425 |
|
"-w3". |
1426 |
|
@end defopt |
1427 |
|
|
1428 |
|
@defopt idlwave-help-link-face |
1429 |
|
The face for links to IDLWAVE online help. |
1430 |
|
@end defopt |
1431 |
|
|
1432 |
|
@node Help with Source, , Help with HTML Documentation, Online Help |
1433 |
|
@subsection Help with Source |
1434 |
|
@cindex Help using routine source |
1435 |
|
|
1436 |
|
@cindex Source code, as online help |
1437 |
|
@cindex DocLib header, as online help |
1438 |
|
For routines which are not documented in an HTML manual (for example |
1439 |
|
personal or library routines), the source code itself is used as help |
1440 |
|
text. If the requested information can be found in a (more or less) |
1441 |
|
standard DocLib file header, IDLWAVE shows the header (scrolling down to |
1442 |
|
a keyword, if appropriate). Otherwise the routine definition statement |
1443 |
|
(@code{pro}/@code{function}) is shown. The doclib header sections which |
1444 |
|
are searched for include @samp{NAME} and @samp{KEYWORDS}. Localization |
1445 |
|
support can be added by customizing the @code{idlwave-help-doclib-name} |
1446 |
|
and @code{idlwave-help-doclib-keyword} variables. |
1447 |
|
|
1448 |
|
@cindex Structure tags, in online help |
1449 |
|
@cindex Class tags, in online help |
1450 |
|
Help is also available for class structure tags (@code{self.TAG}), and |
1451 |
|
generic structure tags, if structure tag completion is enabled |
1452 |
|
(@pxref{Structure Tag Completion}). This is implemented by visiting the |
1453 |
|
tag within the class or structure definition source itself. Help is not |
1454 |
|
available on built-in system class tags. |
1455 |
|
|
1456 |
|
The help window is normally displayed in the same frame, but can be |
1457 |
|
popped-up in a separate frame. The following commands can be used to |
1458 |
|
navigate inside the help system for source files: |
1459 |
|
|
1460 |
@multitable @columnfractions .15 .85 |
@multitable @columnfractions .15 .85 |
1461 |
@item @kbd{@key{SPACE}} |
@item @kbd{@key{SPACE}} |
1464 |
@tab Scroll forward one line. |
@tab Scroll forward one line. |
1465 |
@item @kbd{@key{DEL}} |
@item @kbd{@key{DEL}} |
1466 |
@tab Scroll back one page. |
@tab Scroll back one page. |
|
@item @kbd{n, p} |
|
|
@tab Browse to the next or previous topic (in physical sequence). |
|
|
@item @kbd{b, f} |
|
|
@tab Move back and forward through the help topic history. |
|
|
@item @kbd{c} |
|
|
@tab Clear the history. |
|
|
@item @kbd{Mouse-2} |
|
|
@tab Follow a link. Active links are displayed in a different font. |
|
|
Items under @i{See Also} are active, and classes have links to their |
|
|
methods and back. |
|
|
@item @kbd{o} |
|
|
@tab Open a topic. The topic can be selected with completion. |
|
|
@item @kbd{*} |
|
|
@tab Load the whole help file into Emacs, for global text searches. |
|
|
@item @kbd{q} |
|
|
@tab Kill the help window. |
|
|
@end multitable |
|
|
|
|
|
@sp 1 |
|
|
@noindent When the help text is a source file, the following commands |
|
|
are also available: |
|
|
|
|
|
@multitable @columnfractions .15 .85 |
|
1467 |
@item @kbd{h} |
@item @kbd{h} |
1468 |
@tab Jump to DocLib Header of the routine whose source is displayed |
@tab Jump to DocLib Header of the routine whose source is displayed |
1469 |
as help. |
as help. |
1475 |
item in the DocLib header. |
item in the DocLib header. |
1476 |
@item @kbd{F} |
@item @kbd{F} |
1477 |
@tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}. |
@tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}. |
1478 |
|
@item @kbd{q} |
1479 |
|
@tab Kill the help window. |
1480 |
@end multitable |
@end multitable |
1481 |
|
|
|
@defopt idlwave-help-directory |
|
|
The directory where idlw-help.txt and idlw-help.el are stored. |
|
|
@end defopt |
|
1482 |
|
|
1483 |
@defopt idlwave-help-use-dedicated-frame (@code{t}) |
@defopt idlwave-help-use-dedicated-frame (@code{nil}) |
1484 |
Non-@code{nil} means use a separate frame for Online Help if possible. |
Non-@code{nil} means use a separate frame for Online Help if possible. |
1485 |
@end defopt |
@end defopt |
1486 |
|
|
1501 |
@end defopt |
@end defopt |
1502 |
|
|
1503 |
@defopt idlwave-help-source-try-header (@code{t}) |
@defopt idlwave-help-source-try-header (@code{t}) |
1504 |
Non-@code{nil} means try to find help in routine header when displaying source |
Non-@code{nil} means try to find help in routine header when |
1505 |
file. |
displaying source file. |
1506 |
@end defopt |
@end defopt |
1507 |
|
|
1508 |
@defopt idlwave-help-link-face |
@defopt idlwave-help-doclib-name (@code{"name"}) |
1509 |
The face for links in IDLWAVE online help. |
The case-insensitive heading word in doclib headers to locate the |
1510 |
|
@emph{name} section. Can be a regexp, e.g. @code{"\\(name\\|nom\\)"}. |
1511 |
@end defopt |
@end defopt |
1512 |
|
|
1513 |
@defopt idlwave-help-activate-links-aggressively (@code{t}) |
@defopt idlwave-help-doclib-keyword (@code{"KEYWORD"}) |
1514 |
Non-@code{nil} means make all possible links in help window active. |
The case-insensitive heading word in doclib headers to locate the |
1515 |
|
@emph{keywords} section. Can be a regexp. |
1516 |
@end defopt |
@end defopt |
1517 |
|
|
1518 |
|
|
1519 |
@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode |
@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode |
1520 |
@section Completion |
@section Completion |
1521 |
@cindex Completion |
@cindex Completion |
1529 |
@kindex M-@key{TAB} |
@kindex M-@key{TAB} |
1530 |
@kindex C-c C-i |
@kindex C-c C-i |
1531 |
IDLWAVE offers completion for class names, routine names, keywords, |
IDLWAVE offers completion for class names, routine names, keywords, |
1532 |
system variables, class structure tags, regular structure tags and file |
system variables, system variable tags, class structure tags, regular |
1533 |
names. As in many programming modes, completion is bound to |
structure tags and file names. As in many programming modes, |
1534 |
@kbd{M-@key{TAB}} (or @kbd{@key{TAB}} in the IDLWAVE Shell --- |
completion is bound to @kbd{M-@key{TAB}} (or @kbd{@key{TAB}} in the |
1535 |
@pxref{Using the Shell}). Completion uses exactly the same internal |
IDLWAVE Shell --- @pxref{Using the Shell}). Completion uses exactly |
1536 |
information as routine info, so when necessary (rarely) it can be |
the same internal information as routine info, so when necessary |
1537 |
updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}). |
(rarely) it can be updated with @kbd{C-c C-i} |
1538 |
|
(@code{idlwave-update-routine-info}). |
1539 |
|
|
1540 |
The completion function is context sensitive and figures out what to |
The completion function is context sensitive and figures out what to |
1541 |
complete based location of the point. Here are example lines and what |
complete based location of the point. Here are example lines and what |
1569 |
also a possible completion here. You can force completion of a function |
also a possible completion here. You can force completion of a function |
1570 |
name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}. |
name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}. |
1571 |
|
|
1572 |
|
Giving two prefix arguments (@kbd{C-u C-u M-@key{TAB}}) prompts for a |
1573 |
|
regular expression to search among the commands to be completed. As |
1574 |
|
an example, completing a blank line in this way will allow you to |
1575 |
|
search for a procedure matching a regexp. |
1576 |
|
|
1577 |
@cindex Scrolling the @file{*Completions*} window |
@cindex Scrolling the @file{*Completions*} window |
1578 |
@cindex Completion, scrolling |
@cindex Completion, scrolling |
1579 |
@cindex Completion, Online Help |
@cindex Completion, Online Help |
1620 |
@menu |
@menu |
1621 |
* Case of Completed Words:: CaseOFcomPletedWords |
* Case of Completed Words:: CaseOFcomPletedWords |
1622 |
* Object Method Completion and Class Ambiguity:: obj->Method, what? |
* Object Method Completion and Class Ambiguity:: obj->Method, what? |
1623 |
* Object Method Completion in the Shell:: |
* Object Method Completion in the Shell:: |
1624 |
* Class and Keyword Inheritance:: obj->Method, _EXTRA=e |
* Class and Keyword Inheritance:: obj->Method, _EXTRA=e |
1625 |
* Structure Tag Completion:: Completing state.Tag |
* Structure Tag Completion:: Completing state.Tag |
1626 |
@end menu |
@end menu |
1629 |
@subsection Case of Completed Words |
@subsection Case of Completed Words |
1630 |
@cindex Case of completed words |
@cindex Case of completed words |
1631 |
@cindex Mixed case completion |
@cindex Mixed case completion |
1632 |
The case of the completed words is determined by what is already in the |
IDL is a case-insensitive language, so casing is a matter of style |
1633 |
buffer. When the partial word being completed is all lower case, the |
only. IDLWAVE helps maintain a consistent casing style for completed |
1634 |
completion will be lower case as well. If at least one character is |
items. The case of the completed words is determined by what is |
1635 |
upper case, the string will be completed in upper case or mixed case. |
already in the buffer. As an exception, when the partial word being |
1636 |
The default is to use upper case for procedures, functions and keywords, |
completed is all lower case, the completion will be lower case as |
1637 |
and mixed case for object class names and methods, similar to the |
well. If at least one character is upper case, the string will be |
1638 |
conventions in the IDL manuals. These defaults can be changed with the |
completed in upper case or mixed case, depending on the value of the |
1639 |
variable @code{idlwave-completion-case}. For instance, to enable |
variable @code{idlwave-completion-case}. The default is to use upper |
1640 |
mixed-case completion for routines in addition to classes and methods, |
case for procedures, functions and keywords, and mixed case for object |
1641 |
you need an entry such as @code{routine . preserve} in that variable. |
class names and methods, similar to the conventions in the IDL |
1642 |
To enable total control over the case of completed items, independent of |
manuals. For instance, to enable mixed-case completion for routines |
1643 |
buffer context, set @code{idlwave-completion-force-default-case} to |
in addition to classes and methods, you need an entry such as |
1644 |
non-@code{nil}. |
@code{(routine . preserve)} in that variable. To enable total control |
1645 |
|
over the case of completed items, independent of buffer context, set |
1646 |
|
@code{idlwave-completion-force-default-case} to non-@code{nil}. |
1647 |
|
|
1648 |
@defopt idlwave-completion-case |
@defopt idlwave-completion-case |
1649 |
Association list setting the case (UPPER/lower/Capitalized/MixedCase...) |
Association list setting the case (UPPER/lower/Capitalized/MixedCase...) |
1687 |
@code{idlwave-query-class} can be configured to make such prompting the |
@code{idlwave-query-class} can be configured to make such prompting the |
1688 |
default for all methods (not recommended), or selectively for very |
default for all methods (not recommended), or selectively for very |
1689 |
common methods for which the number of completing keywords would be too |
common methods for which the number of completing keywords would be too |
1690 |
large (e.g. @code{Init}). |
large (e.g. @code{Init}). |
1691 |
|
|
1692 |
@cindex Saving object class on @code{->} |
@cindex Saving object class on @code{->} |
1693 |
@cindex @code{->} |
@cindex @code{->} |
1701 |
can be used to turn it on. |
can be used to turn it on. |
1702 |
|
|
1703 |
@defopt idlwave-completion-show-classes (@code{1}) |
@defopt idlwave-completion-show-classes (@code{1}) |
1704 |
Non-@code{nil} means show classes in @file{*Completions*} buffer when |
Non-@code{nil} means show up to that many classes in |
1705 |
completing object methods and keywords. |
@file{*Completions*} buffer when completing object methods and |
1706 |
|
keywords. |
1707 |
@end defopt |
@end defopt |
1708 |
|
|
1709 |
@defopt idlwave-completion-fontify-classes (@code{t}) |
@defopt idlwave-completion-fontify-classes (@code{t}) |
1764 |
@emph{chaining}, and is characterized by chained method calls like |
@emph{chaining}, and is characterized by chained method calls like |
1765 |
@w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}. |
@w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}. |
1766 |
|
|
1767 |
IDLWAVE can accommodate this special synergy between class and keyword |
IDLWAVE can accomodate this special synergy between class and keyword |
1768 |
inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a |
inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a |
1769 |
method's keyword parameters, all keywords of superclass versions of the |
method's keyword parameters, all keywords of superclass versions of |
1770 |
method being considered are included in completion. There is of course |
the method being considered can be included in completion. There is |
1771 |
no guarantee that this type of keyword chaining actually occurrs, but |
of course no guarantee that this type of keyword chaining actually |
1772 |
for some methods it's a very convenient assumption. The variable |
occurrs, but for some methods it's a very convenient assumption. The |
1773 |
@code{idlwave-keyword-class-inheritance} can be used to configure which |
variable @code{idlwave-keyword-class-inheritance} can be used to |
1774 |
methods have keyword inheritance treated in this simple, class-driven |
configure which methods have keyword inheritance treated in this |
1775 |
way. By default, only @code{Init} and @code{(Get|Set)Property} are. |
simple, class-driven way. By default, only @code{Init} and |
1776 |
The completion buffer will label keywords based on their originating |
@code{(Get|Set)Property} are. The completion buffer will label |
1777 |
class. |
keywords based on their originating class. |
1778 |
|
|
1779 |
@defopt idlwave-support-inheritance (@code{t}) |
@defopt idlwave-support-inheritance (@code{t}) |
1780 |
Non-@code{nil} means consider inheritance during completion, online help etc. |
Non-@code{nil} means consider inheritance during completion, online help etc. |
1781 |
@end defopt |
@end defopt |
1782 |
|
|
1783 |
@defopt idlwave-keyword-class-inheritance |
@defopt idlwave-keyword-class-inheritance |
1784 |
A list of regular expressions to match methods for which simple |
A list of regular expressions to match methods for which simple |
1785 |
class-driven keyword inheritance will be used for Completion. |
class-driven keyword inheritance will be used for Completion. |
1786 |
@end defopt |
@end defopt |
1810 |
simply add the following to your @file{.emacs}: |
simply add the following to your @file{.emacs}: |
1811 |
|
|
1812 |
@lisp |
@lisp |
1813 |
(add-hook 'idlwave-load-hook |
(add-hook 'idlwave-load-hook |
1814 |
(lambda () (require 'idlw-complete-structtag))) |
(lambda () (require 'idlw-complete-structtag))) |
1815 |
@end lisp |
@end lisp |
1816 |
|
|
1830 |
@code{idlwave-routine-info} would have used, taken from nearby buffer |
@code{idlwave-routine-info} would have used, taken from nearby buffer |
1831 |
contents. In the minibuffer, specify a complete routine name (including |
contents. In the minibuffer, specify a complete routine name (including |
1832 |
any class part). IDLWAVE will display the source file in another |
any class part). IDLWAVE will display the source file in another |
1833 |
window, positioned at the routine in question. |
window, positioned at the routine in question. You can also visit a |
1834 |
|
routine in the current buffer, with completion, by using a single prefix |
1835 |
|
(@kbd{C-u C-c C-v}). |
1836 |
|
|
1837 |
@cindex Buffers, killing |
@cindex Buffers, killing |
1838 |
@cindex Killing autoloaded buffers |
@cindex Killing autoloaded buffers |
1855 |
|
|
1856 |
@code{idlwave-resolve} is one way to get a library module within reach |
@code{idlwave-resolve} is one way to get a library module within reach |
1857 |
of IDLWAVE's routine info collecting functions. A better way is to |
of IDLWAVE's routine info collecting functions. A better way is to |
1858 |
scan (parts of) the library (@pxref{Library Catalog}). Routine info on |
keep routine information available in catalogs (@pxref{Catalogs}). |
1859 |
library modules will then be available without the need to compile the |
Routine info on modules will then be available without the need to |
1860 |
modules first, and even without a running shell. |
compile the modules first, and even without a running shell. |
1861 |
|
|
1862 |
@xref{Sources of Routine Info}, for more information on the ways IDLWAVE |
@xref{Sources of Routine Info}, for more information on the ways IDLWAVE |
1863 |
collects data about routines, and how to update this information. |
collects data about routines, and how to update this information. |
2106 |
@end itemize |
@end itemize |
2107 |
|
|
2108 |
@defopt idlwave-do-actions (@code{nil}) |
@defopt idlwave-do-actions (@code{nil}) |
2109 |
Non-@code{nil} means performs actions when indenting. |
Non-@code{nil} means performs actions when indenting. Individual action |
2110 |
|
settings are described below and set separately. |
2111 |
@end defopt |
@end defopt |
2112 |
|
|
2113 |
@menu |
@menu |
2206 |
(idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" |
(idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" |
2207 |
'(capitalize-word 1) t) |
'(capitalize-word 1) t) |
2208 |
;; Capitalize common block name |
;; Capitalize common block name |
2209 |
(idlwave-action-and-binding "\\<common\\>[ \t]+\\<" |
(idlwave-action-and-binding "\\<common\\>[ \t]+\\<" |
2210 |
'(capitalize-word 1) t))) |
'(capitalize-word 1) t))) |
2211 |
@end lisp |
@end lisp |
2212 |
|
|
2233 |
@cindex Modification timestamp |
@cindex Modification timestamp |
2234 |
@cindex Header, for file documentation |
@cindex Header, for file documentation |
2235 |
@cindex Timestamp, in doc header. |
@cindex Timestamp, in doc header. |
2236 |
@cindex ChangeLog, in doc header. |
@cindex Changelog, in doc header. |
2237 |
|
|
2238 |
@kindex C-c C-h |
@kindex C-c C-h |
2239 |
@kindex C-c C-m |
@kindex C-c C-m |
2357 |
program as an inferior process of Emacs, and works closely with the |
program as an inferior process of Emacs, and works closely with the |
2358 |
IDLWAVE major mode in buffers. It can be used to work with IDL |
IDLWAVE major mode in buffers. It can be used to work with IDL |
2359 |
interactively, to compile and run IDL programs in Emacs buffers and to |
interactively, to compile and run IDL programs in Emacs buffers and to |
2360 |
debug these programs. The IDLWAVE shell is built upon @file{comint}, an |
debug these programs. The IDLWAVE shell is built on @file{comint}, an |
2361 |
Emacs packages which handles the communication with the IDL program. |
Emacs packages which handles the communication with the IDL program. |
2362 |
Unfortunately IDL for Windows and MacOS do not have command-prompt |
Unfortunately IDL for Windows does not have command-prompt versions |
2363 |
versions and thus do not allow the interaction with |
and thus do not allow the interaction with Emacs@footnote{Please |
2364 |
Emacs@footnote{Please inform the maintainer if you come up with a way to |
inform the maintainer if you come up with a way to make the IDLWAVE |
2365 |
make the IDLWAVE shell work on these systems.} --- so the IDLWAVE shell |
shell work on these systems.} --- so the IDLWAVE shell currently only |
2366 |
currently only works under Unix. |
works under Unix and MacOSX. |
2367 |
|
|
2368 |
@menu |
@menu |
2369 |
* Starting the Shell:: How to launch IDL as a subprocess |
* Starting the Shell:: How to launch IDL as a subprocess |
2370 |
* Using the Shell:: Interactively working with the Shell |
* Using the Shell:: Interactively working with the Shell |
2371 |
* Commands Sent to the Shell:: |
* Commands Sent to the Shell:: |
2372 |
* Debugging IDL Programs:: |
* Debugging IDL Programs:: |
2373 |
* Examining Variables:: |
* Examining Variables:: |
2374 |
* Custom Expression Examination:: |
* Custom Expression Examination:: |
2375 |
@end menu |
@end menu |
2376 |
|
|
2377 |
@node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell |
@node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell |
2386 |
The IDLWAVE shell can be started with the command @kbd{M-x |
The IDLWAVE shell can be started with the command @kbd{M-x |
2387 |
idlwave-shell}. In @code{idlwave-mode} the function is bound to |
idlwave-shell}. In @code{idlwave-mode} the function is bound to |
2388 |
@kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to |
@kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to |
2389 |
interact with the shell. If the shell is already running, @kbd{C-c C-s} |
interact with the shell. If the shell is already running, @kbd{C-c |
2390 |
will simple switch to the shell buffer. The command @kbd{C-c C-l} |
C-s} will simply switch to the shell buffer. The command @kbd{C-c |
2391 |
(@code{idlwave-shell-recenter-shell-window}) displays the shell window |
C-l} (@code{idlwave-shell-recenter-shell-window}) displays the shell |
2392 |
without selecting it. The shell can also be started automatically when |
window without selecting it. The shell can also be started |
2393 |
another command tries to send a command to it. To enable auto start, |
automatically when another command tries to send a command to it. To |
2394 |
set the variable @code{idlwave-shell-automatic-start} to @code{t}. |
enable auto start, set the variable |
2395 |
|
@code{idlwave-shell-automatic-start} to @code{t}. |
2396 |
|
|
2397 |
In order to create a separate frame for the IDLWAVE shell buffer, call |
In order to create a separate frame for the IDLWAVE shell buffer, call |
2398 |
@code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or |
@code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or |
2399 |
@kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell |
@kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell |
2400 |
window, configure the variable |
window, configure the variable |
2401 |
@code{idlwave-shell-use-dedicated-frame}. |
@code{idlwave-shell-use-dedicated-frame}. |
2402 |
|
|
2403 |
To launch a quick IDLWAVE shell directly from a shell prompt without an |
To launch a quick IDLWAVE shell directly from a shell prompt without |
2404 |
IDLWAVE buffer (e.g., as a replacement for running inside an xterm), |
an IDLWAVE buffer (e.g., as a replacement for running inside an |
2405 |
define an alias with the following content: |
xterm), define a system alias with the following content: |
2406 |
|
|
2407 |
@example |
@example |
2408 |
emacs -geometry 80x32 -eval "(idlwave-shell 'quick)" |
emacs -geometry 80x32 -eval "(idlwave-shell 'quick)" |
2411 |
Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer |
Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer |
2412 |
the Emacs process to run directly inside the terminal window. |
the Emacs process to run directly inside the terminal window. |
2413 |
|
|
2414 |
|
@cindex ENVI |
2415 |
|
@cindex IDL> Prompt |
2416 |
|
|
2417 |
|
To use IDLWAVE with ENVI or other custom packages which change the |
2418 |
|
@samp{IDL> } prompt, you must change the |
2419 |
|
@code{idlwave-shell-prompt-pattern}, which defaults to @samp{"^ ?IDL> |
2420 |
|
"}. Normally, you can just replace the @samp{IDL} in this expression |
2421 |
|
with the prompt you see. A suitable pattern which matches the prompt |
2422 |
|
for both ENVI and IDL simultaneously is @samp{"^ ?\\(ENVI\\|IDL\\)> "}. |
2423 |
|
|
2424 |
@defopt idlwave-shell-explicit-file-name (@file{idl}) |
@defopt idlwave-shell-explicit-file-name (@file{idl}) |
2425 |
This is the command to run IDL. |
This is the command to run IDL. |
2426 |
@end defopt |
@end defopt |
2450 |
Non-@code{nil} means preserve command history between sessions. |
Non-@code{nil} means preserve command history between sessions. |
2451 |
@end defopt |
@end defopt |
2452 |
|
|
2453 |
@defopt idlwave-shell-command-history-file (@file{~/.idlwhist}) |
@defopt idlwave-shell-command-history-file (@file{~/.idlwave/.idlwhist}) |
2454 |
The file in which the command history of the idlwave shell is saved. |
The file in which the command history of the idlwave shell is saved. |
2455 |
|
Unless it's an absolute path, it goes in |
2456 |
|
@code{idlwave-config-directory}. |
2457 |
@end defopt |
@end defopt |
2458 |
|
|
2459 |
@defopt idlwave-shell-use-dedicated-frame (@code{nil}) |
@defopt idlwave-shell-use-dedicated-frame (@code{nil}) |
2460 |
Non-@code{nil} means IDLWAVE should use a special frame to display |
Non-@code{nil} means IDLWAVE should use a special frame to display the |
2461 |
shell buffer. |
shell buffer. |
2462 |
@end defopt |
@end defopt |
2463 |
|
|
2626 |
from the user, but this is configurable. The custom variable |
from the user, but this is configurable. The custom variable |
2627 |
@code{idlwave-abbrev-show-commands} allows you to configure which |
@code{idlwave-abbrev-show-commands} allows you to configure which |
2628 |
commands sent to the shell are shown there. For a related customization |
commands sent to the shell are shown there. For a related customization |
2629 |
for separating the output of @emph{examine} commands @xref{Examining |
for separating the output of @emph{examine} commands, see @ref{Examining |
2630 |
Variables}. |
Variables}. |
2631 |
|
|
2632 |
@defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)}) |
@defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)}) |
2633 |
A list of command types to echo in the shell when sent. Possible values |
A list of command types to echo in the shell when sent. Possible values |
2634 |
are @code{run} for @code{.run}, @code{.compile} and other run commands, |
are @code{run} for @code{.run}, @code{.compile} and other run commands, |
2635 |
@code{misc} for lesser used commands like @code{window}, @code{retall}, |
@code{misc} for lesser used commands like @code{window}, |
2636 |
etc., @code{breakpoint} for breakpoint setting and clearing commands, |
@code{retall},@code{close}, etc., @code{breakpoint} for breakpoint |
2637 |
and @code{debug} for other debug, stepping, and continue commands. In |
setting and clearing commands, and @code{debug} for other debug, |
2638 |
addition, if the variable is set to the single symbol @code{'everything}, |
stepping, and continue commands. In addition, if the variable is set to |
2639 |
all the copious shell input is displayed (which is probably only useful |
the single symbol @code{'everything}, all the copious shell input is |
2640 |
for debugging purposes). |
displayed (which is probably only useful for debugging purposes). |
2641 |
|
N.B. For hidden commands which produce output by side-effect, that |
2642 |
|
output remains hidden (e.g., stepping through a @code{print} command). |
2643 |
|
As a special case, any error message in the output will be displayed |
2644 |
|
(e.g., stepping to an error). |
2645 |
@end defopt |
@end defopt |
2646 |
|
|
2647 |
@node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell |
@node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell |
2651 |
@cindex Toolbar |
@cindex Toolbar |
2652 |
|
|
2653 |
Programs can be compiled, run, and debugged directly from the source |
Programs can be compiled, run, and debugged directly from the source |
2654 |
buffer in Emacs. IDLWAVE makes compiling and debugging IDL programs |
buffer in Emacs, walking through arbitrarily deeply nested code, |
2655 |
far less cumbersome by providing a full-featured, |
printing expressions and skipping up and down the calling stack along |
2656 |
key/menu/toolbar-driven interface to commands like @code{breakpoint}, |
the way. IDLWAVE makes compiling and debugging IDL programs far less |
2657 |
@code{.step}, @code{.run}, etc. |
cumbersome by providing a full-featured, key/menu/toolbar-driven |
2658 |
|
interface to commands like @code{breakpoint}, @code{.step}, |
2659 |
The IDLWAVE shell installs key bindings both in the shell buffer and in |
@code{.run}, etc. It can even perform complex debug operations not |
2660 |
all IDL code buffers of the current Emacs session, so debug commands |
natively supported by IDL (like continuing to the line at the cursor). |
2661 |
work in both places (in the shell, commands operate on the last file |
|
2662 |
compiled). On Emacs versions which support this, a debugging toolbar is |
The IDLWAVE shell installs key bindings both in the shell buffer and |
2663 |
also installed. The display of the toolbar can be toggled with @kbd{C-c |
in all IDL code buffers of the current Emacs session, so debug |
2664 |
C-d C-t} (@code{idlwave-shell-toggle-toolbar}). |
commands work in both places (in the shell, commands operate on the |
2665 |
|
last file compiled). On Emacs versions which support it, a debugging |
2666 |
|
toolbar is also installed. The toolbar display can be toggled with |
2667 |
|
@kbd{C-c C-d C-t} (@code{idlwave-shell-toggle-toolbar}). |
2668 |
|
|
2669 |
|
|
2670 |
@defopt idlwave-shell-use-toolbar (@code{t}) |
@defopt idlwave-shell-use-toolbar (@code{t}) |
2671 |
Non-@code{nil} means use the debugging toolbar in all IDL related |
Non-@code{nil} means use the debugging toolbar in all IDL related |
2673 |
@end defopt |
@end defopt |
2674 |
|
|
2675 |
@menu |
@menu |
2676 |
* Debug Key Bindings:: |
* A Tale of Two Modes:: |
2677 |
* Compiling Programs:: |
* Debug Key Bindings:: |
2678 |
* Breakpoints and Stepping:: |
* Breakpoints and Stepping:: |
2679 |
* Walking the Calling Stack:: |
* Compiling Programs:: |
2680 |
|
* Walking the Calling Stack:: |
2681 |
|
* Electric Debug Mode:: |
2682 |
@end menu |
@end menu |
2683 |
|
|
2684 |
@node Debug Key Bindings, Compiling Programs, Debugging IDL Programs, Debugging IDL Programs |
|
2685 |
|
@node A Tale of Two Modes, Debug Key Bindings, Debugging IDL Programs, Debugging IDL Programs |
2686 |
|
@subsection A Tale of Two Modes |
2687 |
|
@cindex Electric Debug Mode |
2688 |
|
@cindex Debugging Interface |
2689 |
|
|
2690 |
|
The many debugging, compiling, and examination commands provided in |
2691 |
|
IDLWAVE are available simultaneously through two different interfaces: |
2692 |
|
the original, multi-key command interface, and the new Electric Debug |
2693 |
|
Mode. The functionality they offer is similar, but the way you |
2694 |
|
interact with them is quite different. The main difference is that, |
2695 |
|
in Electric Debug Mode, the source buffers are made read-only, and |
2696 |
|
single key-strokes are used to step through, examine expressions, set |
2697 |
|
and remove breakpoints, etc. The same variables, prefix arguments, |
2698 |
|
and settings apply to both versions, and both can be used |
2699 |
|
interchangeably. By default, when breakpoints are hit, Electric Debug |
2700 |
|
Mode is enabled. The traditional interface is described first. |
2701 |
|
@xref{Electric Debug Mode}, for more on that mode. |
2702 |
|
|
2703 |
|
|
2704 |
|
@sp 1 |
2705 |
|
@noindent @strong{Note that electric debug mode can be prevented from |
2706 |
|
activating automatically by customizing the variable |
2707 |
|
@code{idlwave-shell-automatic-electric-debug}.} |
2708 |
|
|
2709 |
|
@node Debug Key Bindings, Breakpoints and Stepping, A Tale of Two Modes, Debugging IDL Programs |
2710 |
@subsection Debug Key Bindings |
@subsection Debug Key Bindings |
2711 |
@kindex C-c C-d |
@kindex C-c C-d |
2712 |
@cindex Key bindings |
@cindex Key bindings |
2713 |
|
|
2714 |
The debugging key bindings are by default on the prefix key @kbd{C-c |
The standard debugging key bindings are always available by default on |
2715 |
C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d |
the prefix key @kbd{C-c C-d}, so, for example, setting a breakpoint is |
2716 |
C-b}, and compiling a source file with @kbd{C-c C-d C-c}. If you find |
done with @kbd{C-c C-d C-b}, and compiling a source file with @kbd{C-c |
2717 |
this too much work, you can easily configure IDLWAVE to use one or more |
C-d C-c}. You can also easily configure IDLWAVE to use one or more |
2718 |
modifier keys not in use by other commands, in lieu of the prefix |
modifier keys not in use by other commands, in lieu of the prefix |
2719 |
@kbd{C-c C-d} (though these bindings will typically also be available |
@kbd{C-c C-d} (though these bindings will typically also be available |
2720 |
--- see @code{idlwave-shell-activate-prefix-keybindings}). For example, |
--- see @code{idlwave-shell-activate-prefix-keybindings}). For |
2721 |
if you write in @file{.emacs}: |
example, if you include in @file{.emacs}: |
2722 |
|
|
2723 |
@lisp |
@lisp |
2724 |
(setq idlwave-shell-debug-modifiers '(control shift)) |
(setq idlwave-shell-debug-modifiers '(control shift)) |
2725 |
@end lisp |
@end lisp |
2726 |
|
|
2727 |
@noindent a breakpoint can be set by pressing @kbd{b} while holding down |
@noindent a breakpoint can then be set by pressing @kbd{b} while holding down |
2728 |
@kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a |
@kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a |
2729 |
source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}, |
source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}, |
2730 |
etc. In the remainder of this chapter we will assume that the @kbd{C-c |
etc. In the remainder of this chapter we will assume that the |
2731 |
C-d} bindings are active, but each of these bindings will have an |
@kbd{C-c C-d} bindings are active, but each of these bindings will |
2732 |
equivalent single-keypress shortcut if modifiers are given in the |
have an equivalent shortcut if modifiers are given in the |
2733 |
@code{idlwave-shell-debug-modifiers} variable (see @pxref{Lesson II -- |
@code{idlwave-shell-debug-modifiers} variable (@pxref{Lesson II -- |
2734 |
Customization}). |
Customization}). A much simpler and faster form of debugging for |
2735 |
|
running code is also available by default --- see @ref{Electric Debug |
2736 |
|
Mode}. |
2737 |
|
|
2738 |
@defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) |
@defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) |
2739 |
The prefix key for the debugging map |
The prefix key for the debugging map |
2746 |
@end defopt |
@end defopt |
2747 |
|
|
2748 |
@defopt idlwave-shell-debug-modifiers (@code{nil}) |
@defopt idlwave-shell-debug-modifiers (@code{nil}) |
2749 |
List of modifier keys to use for additional binding of debugging |
List of modifier keys to use for additional, alternative binding of |
2750 |
commands in the shell and source buffers. Can be one or more of |
debugging commands in the shell and source buffers. Can be one or |
2751 |
@code{control}, @code{meta}, @code{super}, @code{hyper}, @code{alt}, and |
more of @code{control}, @code{meta}, @code{super}, @code{hyper}, |
2752 |
@code{shift}. |
@code{alt}, and @code{shift}. |
|
@end defopt |
|
|
|
|
|
@node Compiling Programs, Breakpoints and Stepping, Debug Key Bindings, 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}. |
|
|
|
|
|
@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. Legal 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}. |
|
2753 |
@end defopt |
@end defopt |
2754 |
|
|
2755 |
@node Breakpoints and Stepping, Walking the Calling Stack, Compiling Programs, Debugging IDL Programs |
@node Breakpoints and Stepping, Compiling Programs, Debug Key Bindings, Debugging IDL Programs |
2756 |
@subsection Breakpoints and Stepping |
@subsection Breakpoints and Stepping |
2757 |
@cindex Breakpoints |
@cindex Breakpoints |
2758 |
@cindex Stepping |
@cindex Stepping |
2760 |
|
|
2761 |
@kindex C-c C-d C-b |
@kindex C-c C-d C-b |
2762 |
@kindex C-c C-d C-b |
@kindex C-c C-d C-b |
2763 |
You can set breakpoints and step through a program with IDLWAVE. |
IDLWAVE helps you set breakpoints and step through code. Setting a |
2764 |
Setting a breakpoint in the current line of the source buffer is done |
breakpoint in the current line of the source buffer is accomplished |
2765 |
with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a prefix |
with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a |
2766 |
arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a |
prefix arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a |
2767 |
@code{/ONCE} keyword, meaning that it will be deleted after first use. |
@code{/ONCE} keyword, meaning that it will be deleted after first use. |
2768 |
With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), the |
With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), |
2769 |
breakpoint will only be active the @code{nth} time it is hit. With a |
the breakpoint will only be active the @code{nth} time it is hit. |
2770 |
single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt for a |
With a single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt |
2771 |
condition --- an IDL expression to be evaulated and trigger the |
for a condition --- an IDL expression to be evaulated and trigger the |
2772 |
breakpoint only if true. To clear the breakpoint in the current line, |
breakpoint only if true. To clear the breakpoint in the current line, |
2773 |
use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When executed |
use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When |
2774 |
from the shell window, the breakpoint where IDL is currently stopped |
executed from the shell window, the breakpoint where IDL is currently |
2775 |
will be deleted. To clear all breakpoints, use @kbd{C-c C-d C-a} |
stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d |
2776 |
(@code{idlwave-clear-all-bp}). Breakpoint lines are highlighted in the |
C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled |
2777 |
source code. Note that IDL places breakpoints as close as possible on |
and re-enabled: @kbd{C-c C-d C-\} |
2778 |
or after the line you specify. IDLWAVE queries the shell for the actual |
(@code{idlwave-shell-toggle-enable-current-bp}). |
2779 |
breakpoint location which was set, so the exact line you specify may not |
|
2780 |
be marked. |
|
2781 |
|
Breakpoint lines are highlighted or indicated with an icon in the |
2782 |
|
source code (different icons for conditional, after, and other break |
2783 |
|
types). Disabled breakpoints are @emph{grayed out} by default. Note |
2784 |
|
that IDL places breakpoints as close as possible on or after the line |
2785 |
|
you specify. IDLWAVE queries the shell for the actual breakpoint |
2786 |
|
location which was set, so the exact line you specify may not be |
2787 |
|
marked. You can re-sync the breakpoint list and display at any time |
2788 |
|
(e.g., if you add or remove some on the command line) using @kbd{C-c |
2789 |
|
C-d C-l}. |
2790 |
|
|
2791 |
Once the program has stopped somewhere, you can step through it. The |
Once the program has stopped somewhere, you can step through it. The |
2792 |
most important stepping commands are @kbd{C-c C-d C-s} to execute one |
most important stepping commands are @kbd{C-c C-d C-s} to execute one |
2807 |
@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) |
@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) |
2808 |
@item @kbd{C-c C-d C-a} |
@item @kbd{C-c C-d C-a} |
2809 |
@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) |
@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) |
2810 |
|
@item @kbd{C-c C-d [} |
2811 |
|
@tab Go to the previous breakpoint (@code{idlwave-shell-goto-previous-bp}) |
2812 |
|
@item @kbd{C-c C-d ]} |
2813 |
|
@tab Go to the next breakpoint (@code{idlwave-shell-goto-next-bp}) |
2814 |
|
@item @kbd{C-c C-d C-\} |
2815 |
|
@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) |
2816 |
|
@item @kbd{C-c C-d C-j} |
2817 |
|
@tab Set a breakpoint at the beginning of the enclosing routine. |
2818 |
@item @kbd{C-c C-d C-s} |
@item @kbd{C-c C-d C-s} |
2819 |
@tab Step, into function calls (@code{idlwave-shell-step}) |
@tab Step, into function calls (@code{idlwave-shell-step}) |
2820 |
@item @kbd{C-c C-d C-n} |
@item @kbd{C-c C-d C-n} |
2830 |
@item @kbd{C-c C-d C-h} |
@item @kbd{C-c C-d C-h} |
2831 |
@tab Continue to line at cursor position (@code{idlwave-shell-to-here}) |
@tab Continue to line at cursor position (@code{idlwave-shell-to-here}) |
2832 |
@item @kbd{C-c C-d C-r} |
@item @kbd{C-c C-d C-r} |
2833 |
@tab Continue execution to next breakpoint (@code{idlwave-shell-cont}) |
@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) |
2834 |
@item @kbd{C-c C-d C-up} |
@item @kbd{C-c C-d C-up} |
2835 |
@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) |
@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) |
2836 |
@item @kbd{C-c C-d C-down} |
@item @kbd{C-c C-d C-down} |
2837 |
@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) |
@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) |
2838 |
@end multitable |
@end multitable |
2839 |
|
|
2840 |
|
All of these commands have equivalents in Electric Debug Mode, which |
2841 |
|
provides faster access (@pxref{Electric Debug Mode}). |
2842 |
|
|
2843 |
@defopt idlwave-shell-mark-breakpoints (@code{t}) |
@defopt idlwave-shell-mark-breakpoints (@code{t}) |
2844 |
Non-@code{nil} means mark breakpoints in the source file buffers. The |
Non-@code{nil} means mark breakpoints in the source file buffers. The |
2845 |
value indicates the preferred method. Legal values are @code{nil}, |
value indicates the preferred method. Legal values are @code{nil}, |
2851 |
@code{idlwave-shell-mark-breakpoints} has the value @code{face}. |
@code{idlwave-shell-mark-breakpoints} has the value @code{face}. |
2852 |
@end defopt |
@end defopt |
2853 |
|
|
2854 |
@node Walking the Calling Stack, , Breakpoints and Stepping, Debugging IDL Programs |
@node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs |
2855 |
|
@subsection Compiling Programs |
2856 |
|
@cindex Compiling programs |
2857 |
|
@cindex Programs, compiling |
2858 |
|
@cindex Default command line, executing |
2859 |
|
@cindex Executing a default command line |
2860 |
|
|
2861 |
|
@kindex C-c C-d C-c |
2862 |
|
In order to compile the current buffer under the IDLWAVE shell, press |
2863 |
|
@kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the |
2864 |
|
current buffer and then sends the command @samp{.run path/to/file} to the |
2865 |
|
shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in |
2866 |
|
which case the most recently compiled buffer will be saved and |
2867 |
|
re-compiled. |
2868 |
|
|
2869 |
|
When developing or debugging a program, it is often necessary to execute |
2870 |
|
the same command line many times. A convenient way to do this is |
2871 |
|
@kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}). |
2872 |
|
This command first resets IDL from a state of interrupted execution by |
2873 |
|
closing all files and returning to the main interpreter level. Then a |
2874 |
|
default command line is send to the shell. To edit the default command |
2875 |
|
line, call @code{idlwave-shell-execute-default-command-line} with a |
2876 |
|
prefix argument: @kbd{C-u C-c C-d C-y}. If no default command line has |
2877 |
|
been set (or you give two prefix arguments), the last command on the |
2878 |
|
@code{comint} input history is sent. |
2879 |
|
|
2880 |
|
@defopt idlwave-shell-mark-stop-line (@code{t}) |
2881 |
|
Non-@code{nil} means mark the source code line where IDL is currently |
2882 |
|
stopped. The value specifies the preferred method. Legal values are |
2883 |
|
@code{nil}, @code{t}, @code{arrow}, and @code{face}. |
2884 |
|
@end defopt |
2885 |
|
|
2886 |
|
@defopt idlwave-shell-overlay-arrow (@code{">"}) |
2887 |
|
The overlay arrow to display at source lines where execution halts, if |
2888 |
|
configured in @code{idlwave-shell-mark-stop-line}. |
2889 |
|
@end defopt |
2890 |
|
|
2891 |
|
@defopt idlwave-shell-stop-line-face |
2892 |
|
The face which highlights the source line where IDL is stopped, if |
2893 |
|
configured in @code{idlwave-shell-mark-stop-line}. |
2894 |
|
@end defopt |
2895 |
|
|
2896 |
|
@node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs |
2897 |
@subsection Walking the Calling Stack |
@subsection Walking the Calling Stack |
2898 |
@cindex Calling stack, walking |
@cindex Calling stack, walking |
2899 |
|
|
2913 |
higher calling stack levels. |
higher calling stack levels. |
2914 |
|
|
2915 |
@ifhtml |
@ifhtml |
2916 |
|
<A NAME="EDEBUG"></A> |
2917 |
|
@end ifhtml |
2918 |
|
@node Electric Debug Mode, , Walking the Calling Stack, Debugging IDL Programs |
2919 |
|
@subsection Electric Debug Mode |
2920 |
|
@cindex Electric Debug Mode |
2921 |
|
@cindex @samp{*Debugging*} |
2922 |
|
|
2923 |
|
Even with a convenient debug key prefix enabled, repetitive stepping, |
2924 |
|
variable examination (@pxref{Examining Variables}), and other |
2925 |
|
debugging activities can be awkward and slow using commands which |
2926 |
|
require multiple keystrokes. Luckily, there's a better way, inspired |
2927 |
|
by the lisp e-debug mode, and available through the @emph{Electric |
2928 |
|
Debug Mode}. By default, as soon as a breakpoint is hit, this minor |
2929 |
|
mode is enabled. The buffer showing the line where execution has |
2930 |
|
halted is switched to Electric Debug Mode. This mode is visible as |
2931 |
|
@samp{*Debugging*} in the mode line, and a different face (violet by |
2932 |
|
default, where color is available) for the line stopped at point. The |
2933 |
|
buffer is made read-only and single-character bindings for the most |
2934 |
|
commonly used debugging commands are enabled: |
2935 |
|
|
2936 |
|
@multitable @columnfractions .2 .8 |
2937 |
|
@item @kbd{a} |
2938 |
|
@tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) |
2939 |
|
@item @kbd{b} |
2940 |
|
@tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here}) |
2941 |
|
@item @kbd{d} |
2942 |
|
@tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) |
2943 |
|
@item @kbd{h} |
2944 |
|
@tab Continue to the line at cursor position (@code{idlwave-shell-to-here}) |
2945 |
|
@item @kbd{i} |
2946 |
|
@tab Set breakpoint in function named here (@code{idlwave-shell-break-in}) |
2947 |
|
@item @kbd{[} |
2948 |
|
@tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp}) |
2949 |
|
@item @kbd{]} |
2950 |
|
@tab Go to the next breakpoint in the file |
2951 |
|
(@code{idlwave-shell-goto-next-bp}) |
2952 |
|
@item @kbd{\} |
2953 |
|
@tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp}) |
2954 |
|
@item @kbd{j} |
2955 |
|
@tab Set breakpoint at beginning of enclosing routine (@code{idlwave-shell-break-this-module}) |
2956 |
|
@item @kbd{k} |
2957 |
|
@tab Skip one statement (@code{idlwave-shell-skip}) |
2958 |
|
@item @kbd{m} |
2959 |
|
@tab Continue to end of function (@code{idlwave-shell-return}) |
2960 |
|
@item @kbd{n} |
2961 |
|
@tab Step, over function calls (@code{idlwave-shell-stepover}) |
2962 |
|
@item @kbd{o} |
2963 |
|
@tab Continue past end of function (@code{idlwave-shell-out}) |
2964 |
|
@item @kbd{p} |
2965 |
|
@tab Print expression near point or in region with @kbd{C-u p} (@code{idlwave-shell-print}) |
2966 |
|
@item @kbd{q} |
2967 |
|
@tab End the debugging session and return to the Shell's main level |
2968 |
|
(@code{idlwave-shell-retall}) |
2969 |
|
@item @kbd{r} |
2970 |
|
@tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont}) |
2971 |
|
@item @kbd{s} or @kbd{@key{SPACE}} |
2972 |
|
@tab Step, into function calls (@code{idlwave-shell-step}) |
2973 |
|
@item @kbd{t} |
2974 |
|
@tab Print a calling-level traceback in the shell |
2975 |
|
@item @kbd{u} |
2976 |
|
@tab Continue to end of block (@code{idlwave-shell-up}) |
2977 |
|
@item @kbd{v} |
2978 |
|
@tab Turn Electric Debug Mode off |
2979 |
|
(@code{idlwave-shell-electric-debug-mode}) |
2980 |
|
@item @kbd{x} |
2981 |
|
@tab Examine expression near point (or in region with @kbd{C-u x}) |
2982 |
|
with shortcut of examine type. |
2983 |
|
@item @kbd{z} |
2984 |
|
@tab Reset IDL (@code{idlwave-shell-reset}) |
2985 |
|
@item @kbd{+} or @kbd{=} |
2986 |
|
@tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) |
2987 |
|
@item @kbd{-} or @kbd{_} |
2988 |
|
@tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) |
2989 |
|
@item @kbd{?} |
2990 |
|
@tab Help on expression near point or in region with @kbd{C-u ?} |
2991 |
|
(@code{idlwave-shell-help-expression}) |
2992 |
|
@item @kbd{C-?} |
2993 |
|
@tab Show help on the commands available. |
2994 |
|
@end multitable |
2995 |
|
|
2996 |
|
Most single-character electric debug bindings use the final keystroke |
2997 |
|
of the equivalent multiple key commands (which are of course also |
2998 |
|
still available), but some differ (e.g. @kbd{t},@kbd{q},@kbd{x}). |
2999 |
|
Some have additional convenience bindings (like @kbd{@key{SPACE}} for |
3000 |
|
stepping). All prefix and other argument options described in this |
3001 |
|
section for the commands invoked by electric debug bindings are still |
3002 |
|
valid. For example, @kbd{C-u b} sets a conditional breakpoint, just |
3003 |
|
as it did with @kbd{C-u C-c C-d C-b}. |
3004 |
|
|
3005 |
|
You can toggle the electric debug mode at any time in a buffer using |
3006 |
|
@kbd{C-c C-d C-v} (@kbd{v} to turn it off while in the mode), or from |
3007 |
|
the Debug menu. Normally the mode will be enabled and disabled at the |
3008 |
|
appropriate times, but occassionally you might want to edit a file |
3009 |
|
while still debugging it, or switch to the mode for conveniently |
3010 |
|
setting lots of breakpoints. |
3011 |
|
|
3012 |
|
To quickly abandon a debugging session and return to normal editing at |
3013 |
|
the Shell's main level, use @kbd{q} (@code{idlwave-shell-retall}). |
3014 |
|
This disables electric debug mode in all IDLWAVE buffers@footnote{Note |
3015 |
|
that this binding is not symmetric: @kbd{C-c C-d C-q} is bound to |
3016 |
|
@code{idlwave-shell-quit}, which quits your IDL session.}. Help is |
3017 |
|
available for the command shortcuts with @kbd{C-?}. If you find this |
3018 |
|
mode gets in your way, you can keep it from automatically activating |
3019 |
|
by setting the variable @code{idlwave-shell-automatic-electric-debug} |
3020 |
|
to @code{nil}, or @code{'breakpoint}. If you'd like the convenient |
3021 |
|
electric debug shortcuts available also when run-time errors are |
3022 |
|
encountered, set to @code{t}. |
3023 |
|
|
3024 |
|
@defopt idlwave-shell-automatic-electric-debug (@code{'breakpoint}) |
3025 |
|
Whether to enter electric debug mode automatically when a breakpoint |
3026 |
|
or run-time error is encountered, and then disable it in all buffers |
3027 |
|
when the $MAIN$ level is reached (either through normal program |
3028 |
|
execution, or retall). In addition to @code{nil} for never, and |
3029 |
|
@code{t} for both breakpoints and errors, this can be |
3030 |
|
@code{'breakpoint} (the default) to enable it only at breakpoint |
3031 |
|
halts. |
3032 |
|
@end defopt |
3033 |
|
|
3034 |
|
@defopt idlwave-shell-electric-zap-to-file (@code{t}) |
3035 |
|
If set, when entering electric debug mode, select the window displaying |
3036 |
|
the file where point is stopped. This takes point away from the shell |
3037 |
|
window, but is useful for immediate stepping, etc. |
3038 |
|
@end defopt |
3039 |
|
|
3040 |
|
@ifhtml |
3041 |
<A NAME="EXAMINE"></A> |
<A NAME="EXAMINE"></A> |
3042 |
@end ifhtml |
@end ifhtml |
3043 |
@node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell |
@node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell |
3044 |
@section Examining Variables |
@section Examining Variables |
3045 |
@cindex @code{PRINT} expressions |
@cindex @code{PRINT} expressions |
3046 |
@cindex @code{HELP}, on expressions |
@cindex @code{HELP}, on expressions |
3047 |
@cindex Expressions, printing |
@cindex Expressions, printing & help |
3048 |
@cindex Expressions, help |
@cindex Examining expressions |
3049 |
@cindex Printing expressions |
@cindex Printing expressions |
3050 |
@cindex Mouse binding to print expressions |
@cindex Mouse binding to print expressions |
3051 |
|
|
3052 |
@kindex C-c C-d C-p |
@kindex C-c C-d C-p |
3053 |
Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)}, |
Do you find yourself repeatedly typing, |
3054 |
and similar statements to remind yourself of the |
e.g. @code{print,n_elements(x)}, and similar statements to remind |
3055 |
type/size/structure/value/etc. of variables and expressions in your code |
yourself of the type/size/structure/value/etc. of variables and |
3056 |
or at the command line? IDLWAVE has a suite of special commands to |
expressions in your code or at the command line? IDLWAVE has a suite |
3057 |
automate these types of variables or expression examinations. They work |
of special commands to automate these types of variable or expression |
3058 |
by sending statements to the shell formatted to include the indicated |
examinations. They work by sending statements to the shell formatted |
3059 |
expression. |
to include the indicated expression. |
3060 |
|
|
3061 |
These examination commands can be used in the shell or buffer at any |
These examination commands can be used in the shell or buffer at any |
3062 |
time (as long as the shell is running), and are very useful when |
time (as long as the shell is running), and are very useful when |
3064 |
or while composing a long command in the IDLWAVE shell. In the latter |
or while composing a long command in the IDLWAVE shell. In the latter |
3065 |
case, the command is sent to the shell and its output is visible, but |
case, the command is sent to the shell and its output is visible, but |
3066 |
point remains unmoved in the command being composed --- you can inspect |
point remains unmoved in the command being composed --- you can inspect |
3067 |
the constituents of a command you're building without interrupting the |
the contituents of a command you're building without interrupting the |
3068 |
process of building it! You can even print arbitrary expressions from |
process of building it! You can even print arbitrary expressions from |
3069 |
older input or output further up in the shell window --- any expression, |
older input or output further up in the shell window --- any expression, |
3070 |
variable, number, or function you see can be examined. |
variable, number, or function you see can be examined. |
3077 |
|
|
3078 |
The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to |
The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to |
3079 |
print the expression at point, and @kbd{C-c C-d ?}, to invoke help on |
print the expression at point, and @kbd{C-c C-d ?}, to invoke help on |
3080 |
this expression. The expression at point is either an array expression |
this expression@footnote{Available as @kbd{p} and @kbd{?} in Electric |
3081 |
or a function call, or the contents of a pair of parentheses. The |
Debug Mode (@pxref{Electric Debug Mode})}. The expression at point is |
3082 |
selected expression is highlighted, and simultaneously the resulting |
either an array expression or a function call, or the contents of a |
3083 |
output is highlighted in the shell. Calling the above commands with a |
pair of parentheses. The selected expression is highlighted, and |
3084 |
prefix argument will prompt for an expression instead of using the one |
simultaneously the resulting output is highlighted in the shell. |
3085 |
at point. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will use the |
Calling the above commands with a prefix argument will use the current |
3086 |
current region as expression. |
region as expression instead of using the one at point. Two prefix |
3087 |
|
arguments (@kbd{C-u C-u C-c C-d C-p}) will prompt for an expression. |
3088 |
|
|
3089 |
For added speed and convenience, there are mouse bindings which allow |
For added speed and convenience, there are mouse bindings which allow |
3090 |
you to click on expressions and examine their values. Use |
you to click on expressions and examine their values. Use |
3092 |
help (i.e. you need to hold down @key{META} and @key{CONTROL} while |
help (i.e. you need to hold down @key{META} and @key{CONTROL} while |
3093 |
clicking with the middle mouse button). If you simply click, the |
clicking with the middle mouse button). If you simply click, the |
3094 |
nearest expression will be selected in the same manner as described |
nearest expression will be selected in the same manner as described |
3095 |
above. You can also @emph{drag} the mouse in order to highlight exactly |
above. You can also @emph{drag} the mouse in order to highlight |
3096 |
a specific expression or sub-expression to be examined. For custom |
exactly the specific expression or sub-expression you want to examine. |
3097 |
expression examination, and the customizable pop-up examine selection, |
For custom expression examination, and the powerful customizable |
3098 |
@xref{Custom Expression Examination}. |
pop-up examine selection, @xref{Custom Expression Examination}. |
3099 |
|
|
3100 |
@cindex Printing expressions, on calling stack |
@cindex Printing expressions, on calling stack |
3101 |
@cindex Restrictions for expression printing |
@cindex Restrictions for expression printing |
3117 |
@cindex ROUTINE_NAMES, IDL procedure |
@cindex ROUTINE_NAMES, IDL procedure |
3118 |
N.B.: printing values of expressions on higher levels of the calling |
N.B.: printing values of expressions on higher levels of the calling |
3119 |
stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, |
stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, |
3120 |
which may or may not be available in future versions of IDL. |
which may or may not be available in future versions of IDL. Caveat |
3121 |
|
Examinor. |
3122 |
@end itemize |
@end itemize |
3123 |
|
|
3124 |
@defopt idlwave-shell-expression-face |
@defopt idlwave-shell-expression-face |
3128 |
@end defopt |
@end defopt |
3129 |
|
|
3130 |
@defopt idlwave-shell-output-face |
@defopt idlwave-shell-output-face |
3131 |
The face for @code{idlwave-shell-output-overlay}. |
The face for @code{idlwave-shell-output-overlay}. |
3132 |
Allows to choose the font, color and other properties for the most |
Allows to choose the font, color and other properties for the most |
3133 |
recent output of IDL when examining an expression." |
recent output of IDL when examining an expression." |
3134 |
@end defopt |
@end defopt |
3135 |
|
|
3136 |
@defopt idlwave-shell-separate-examine-output (@code{t}) |
@defopt idlwave-shell-separate-examine-output (@code{t}) |
3137 |
If non-@code{nil}, re-direct the output of examine commands to a special |
If non-@code{nil}, re-direct the output of examine commands to a special |
3138 |
@file{*Examine*} buffer, instead of in the shell itself. |
@file{*Examine*} buffer, instead of in the shell itself. |
3139 |
@end defopt |
@end defopt |
3140 |
|
|
3141 |
@node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell |
@node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell |
3148 |
@code{widget_info()}). Rather than attempt to include them all, IDLWAVE |
@code{widget_info()}). Rather than attempt to include them all, IDLWAVE |
3149 |
provides two easy methods to customize your own commands, with a special |
provides two easy methods to customize your own commands, with a special |
3150 |
mouse examine command, and two macros for generating your own examine |
mouse examine command, and two macros for generating your own examine |
3151 |
bindings. |
key and mouse bindings. |
3152 |
|
|
3153 |
The most powerful and flexible mouse examine command is available on |
The most powerful and flexible mouse examine command of all is |
3154 |
@kbd{C-S-Mouse-2}. Just as for all the other mouse examine commands, it |
available on @kbd{C-S-Mouse-2}. Just as for all the other mouse |
3155 |
permits click or drag expression selection, but instead of sending |
examine commands, it permits click or drag expression selection, but |
3156 |
hard-coded commands to the shell, it pops-up a customizable selection |
instead of sending hard-coded commands to the shell, it pops-up a |
3157 |
list of examine functions to choose among, configured with the |
customizable selection list of examine functions to choose among, |
3158 |
@code{idlwave-shell-examine-alist} variable. This variable is a list of |
configured with the @code{idlwave-shell-examine-alist} |
3159 |
key-value pairs (an @emph{alist} in Emacs parlance), where the keys name |
variable@footnote{In Electric Debug Mode (@pxref{Electric Debug |
3160 |
the command, and the values are the command strings, in which the text |
Mode}), the key @kbd{x} provides a single-character shortcut interface |
3161 |
@code{___} (three underscores) will be replaced by the selected |
to the same examine functions for the expression at point or marked by |
3162 |
expression before being sent to the shell. An example might be key |
the region.}. This variable is a list of key-value pairs (an |
3163 |
@code{Structure Help} with value @code{help,___,/STRUCTURE}. |
@emph{alist} in Emacs parlance), where the key gives a name to be |
3164 |
@code{idlwave-shell-examine-alist} comes by default with a large list of |
shown for the examine command, and the value is the command strings |
3165 |
examine commands, but can be easily customized to add more. |
itself, in which the text @code{___} (three underscores) will be |
3166 |
|
replaced by the selected expression before being sent to the shell. |
3167 |
In addition to the pop-up mouse command, you can easily create your own |
An example might be key @code{Structure Help} with value |
3168 |
customized bindings to inspect expressions using the two convenience |
@code{help,___,/STRUCTURE}. In that case, you'd be prompted with |
3169 |
macros @code{idlwave-shell-inspect} and |
@emph{Structure Help}, which might send something like |
3170 |
@code{idlwave-shell-mouse-inspect}. These create keyboard or |
@code{help,var,/STRUCTURE} to the shell for output. |
3171 |
mouse-based custom inspections of variables, sharing all the same |
@code{idlwave-shell-examine-alist} comes configured by default with a |
3172 |
properties of the built-in examine commands. Both functions take a |
large list of examine commands, but you can easily customize it to add |
3173 |
single string argument sharing the syntax of the |
your own. |
3174 |
|
|
3175 |
|
In addition to configuring the functions available to the pop-up mouse |
3176 |
|
command, you can easily create your own customized bindings to inspect |
3177 |
|
expressions using the two convenience macros |
3178 |
|
@code{idlwave-shell-examine} and @code{idlwave-shell-mouse-examine}. |
3179 |
|
These create keyboard or mouse-based custom inspections of variables, |
3180 |
|
sharing all the same properties of the built-in examine commands. |
3181 |
|
Both functions take a single string argument sharing the syntax of the |
3182 |
@code{idlwave-shell-examine-alist} values, e.g.: |
@code{idlwave-shell-examine-alist} values, e.g.: |
3183 |
|
|
3184 |
@lisp |
@lisp |
3185 |
(add-hook 'idlwave-shell-mode-hook |
(add-hook 'idlwave-shell-mode-hook |
3186 |
(lambda () |
(lambda () |
3187 |
(idlwave-shell-define-key-both [s-down-mouse-2] |
(idlwave-shell-define-key-both [s-down-mouse-2] |
3188 |
(idlwave-shell-mouse-examine |
(idlwave-shell-mouse-examine |
3189 |
"print, size(___,/DIMENSIONS)")) |
"print, size(___,/DIMENSIONS)")) |
3190 |
(idlwave-shell-define-key-both [f9] (idlwave-shell-examine |
(idlwave-shell-define-key-both [f9] (idlwave-shell-examine |
3191 |
"print, size(___,/DIMENSIONS)")) |
"print, size(___,/DIMENSIONS)")) |
3192 |
(idlwave-shell-define-key-both [f10] (idlwave-shell-examine |
(idlwave-shell-define-key-both [f10] (idlwave-shell-examine |
3193 |
"print,size(___,/TNAME)")) |
"print,size(___,/TNAME)")) |
3194 |
(idlwave-shell-define-key-both [f11] (idlwave-shell-examine |
(idlwave-shell-define-key-both [f11] (idlwave-shell-examine |
3195 |
"help,___,/STRUCTURE")))) |
"help,___,/STRUCTURE")))) |
3196 |
@end lisp |
@end lisp |
3197 |
|
|
3198 |
@noindent Now pressing @key{f9}, or middle-mouse dragging with the |
@noindent Now pressing @key{f9}, or middle-mouse dragging with the |
3199 |
@key{SUPER} key depressed, will print the dimensions of the nearby or |
@key{SUPER} key depressed, will print the dimensions of the nearby or |
3200 |
highlighted expression. Pressing @key{f10} will give the type string, |
highlighted expression. Pressing @key{f10} will give the type string, |
3202 |
see, the possibilities are only marginally finite. |
see, the possibilities are only marginally finite. |
3203 |
|
|
3204 |
@defopt idlwave-shell-examine-alist |
@defopt idlwave-shell-examine-alist |
3205 |
An alist of examine commands in which the keys name the command and are |
An alist of examine commands in which the keys name the command and |
3206 |
displayed in the selection pop-up, and the values are custom IDL examine |
are displayed in the selection pop-up, and the values are custom IDL |
3207 |
command strings to send, after all instances of @code{___} are replaced |
examine command strings to send, after all instances of @code{___} |
3208 |
by the indicated expression. |
(three underscores) are replaced by the indicated expression. |
3209 |
@end defopt |
@end defopt |
3210 |
|
|
3211 |
|
|
3216 |
@menu |
@menu |
3217 |
* Installing IDLWAVE:: How to install the distribution |
* Installing IDLWAVE:: How to install the distribution |
3218 |
* Installing Online Help:: Where to get the additional files needed |
* Installing Online Help:: Where to get the additional files needed |
|
* Upgrading from idl.el:: Necessary configuration changes |
|
3219 |
@end menu |
@end menu |
3220 |
|
|
3221 |
@node Installing IDLWAVE, Installing Online Help, Installation, Installation |
@node Installing IDLWAVE, Installing Online Help, Installation, Installation |
3232 |
and can be installed from |
and can be installed from |
3233 |
@uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site} |
@uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site} |
3234 |
with the normal package management system on XEmacs 21. These |
with the normal package management system on XEmacs 21. These |
3235 |
pre-installed versions should work out-of-the-box. However, the files |
pre-installed versions should work out-of-the-box. However, the HTML |
3236 |
required for online help are not distributed with XEmacs/Emacs and have |
files required for online HTML help are not distributed with |
3237 |
to be installed separately@footnote{Due to copyright reasons, the ASCII |
XEmacs/Emacs and have to be installed separately@footnote{Due to |
3238 |
version of the IDL manual cannot be distributed under the GPL.} |
copyright reasons, the HTML version of the IDL manual cannot be |
3239 |
(@pxref{Installing Online Help}). |
distributed under the GPL.} (@pxref{Installing Online Help}). |
3240 |
|
|
3241 |
You can also download IDLWAVE and install it yourself from |
You can also download IDLWAVE and install it yourself from |
3242 |
@uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. Follow the |
@uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. Follow the |
3243 |
instructions in the INSTALL file. |
instructions in the INSTALL file. |
3244 |
|
|
3245 |
@node Installing Online Help, Upgrading from idl.el, Installing IDLWAVE, Installation |
@node Installing Online Help, , Installing IDLWAVE, Installation |
3246 |
@section Installing Online Help |
@section Installing Online Help |
3247 |
@cindex Installing online help |
@cindex Installing online help |
3248 |
@cindex Online Help, Installation |
@cindex Online Help, Installation |
3249 |
|
|
3250 |
If you want to use the online help display, two additional files (an |
If you want to use the online help display, an additional set of files |
3251 |
ASCII version of the IDL documentation and a topics/code file) must be |
(HTML versions of the IDL documentation) must be installed. These |
3252 |
installed. These files can also be downloaded from |
files can also be downloaded from @uref{@value{IDLWAVE-HOMEPAGE}, the |
3253 |
@uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. You need to |
maintainers webpage}. You need to place the files somewhere on your |
3254 |
place the files somewhere on your system and tell IDLWAVE where they are |
system and tell IDLWAVE where they are with |
|
with |
|
|
|
|
|
@lisp |
|
|
(setq idlwave-help-directory "/path/to/help/files/") |
|
|
@end lisp |
|
|
|
|
|
@node Upgrading from idl.el, , Installing Online Help, Installation |
|
|
@section Upgrading from the old @b{@file{idl.el}} file |
|
|
@cindex Upgrading from old @b{@file{idl.el}} |
|
|
@cindex Renaming old variables |
|
|
@cindex Old variables, renaming |
|
|
@kindex M-@key{TAB} |
|
|
|
|
|
If you have been using the old @file{idl.el} and @file{idl-shell.el} |
|
|
files and would like to use IDLWAVE, you need to update your |
|
|
customization in @file{.emacs}. |
|
3255 |
|
|
|
@enumerate |
|
|
@item |
|
|
Change all variable and function prefixes from @samp{idl-} to @samp{idlwave-}. |
|
|
@item |
|
|
Remove the now invalid @code{autoload} and @code{auto-mode-alist} forms |
|
|
pointing to the @file{idl.el} and @file{idl-shell.el} files. Install |
|
|
the new autoload forms. |
|
|
@item |
|
|
If you have been using the hook function recommended in earlier versions |
|
|
to get a separate frame for the IDL shell, remove that command from your |
|
|
@code{idlwave-shell-mode-hook}. Instead, set the variable |
|
|
@code{idlwave-shell-use-dedicated-frame} with |
|
3256 |
@lisp |
@lisp |
3257 |
(setq idlwave-shell-use-dedicated-frame t) |
(setq idlwave-html-help-location "/path/to/help/dir/") ;e.g. /usr/local/etc |
3258 |
@end lisp |
@end lisp |
3259 |
@item |
|
3260 |
The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character. |
Note that the help package only changes with new versions of the IDL |
3261 |
Like in many other Emacs modes, @kbd{M-@key{TAB}} now does |
documentation, and need not be updated unless your version of IDL |
3262 |
completion. Inserting a TAB has therefore been moved to |
changes. |
|
@kbd{C-@key{TAB}}. On a character based terminal you can also use |
|
|
@kbd{C-c @key{SPC}}. |
|
|
@end enumerate |
|
3263 |
|
|
3264 |
@node Acknowledgements, Sources of Routine Info, Installation, Top |
@node Acknowledgements, Sources of Routine Info, Installation, Top |
3265 |
@chapter Acknowledgements |
@chapter Acknowledgements |
3285 |
everything, modernized IDLWAVE with many new features, and developed the |
everything, modernized IDLWAVE with many new features, and developed the |
3286 |
manual. |
manual. |
3287 |
|
|
3288 |
@item |
@item |
3289 |
@uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current |
@uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current |
3290 |
maintainer, as of version 4.10, helped shape object method completion |
maintainer, as of version 4.10, helped shape object method completion |
3291 |
and most new features introduced in versions 4.x. |
and most new features introduced in versions 4.x, and added |
3292 |
|
significant new capabilities for versions 5.x. |
3293 |
@end itemize |
@end itemize |
3294 |
|
|
3295 |
@noindent |
@noindent |
3298 |
|
|
3299 |
@itemize @minus |
@itemize @minus |
3300 |
@item |
@item |
3301 |
Ulrik Dickow <dickow@@nbi.dk> |
Ulrik Dickow <dickow__at__nbi.dk> |
3302 |
@item |
@item |
3303 |
Eric E. Dors <edors@@lanl.gov> |
Eric E. Dors <edors__at__lanl.gov> |
3304 |
@item |
@item |
3305 |
Stein Vidar H. Haugan <s.v.h.haugan@@astro.uio.no> |
Stein Vidar H. Haugan <s.v.h.haugan__at__astro.uio.no> |
3306 |
@item |
@item |
3307 |
David Huenemoerder <dph@@space.mit.edu> |
David Huenemoerder <dph__at__space.mit.edu> |
3308 |
@item |
@item |
3309 |
Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de> |
Kevin Ivory <Kevin.Ivory__at__linmpi.mpg.de> |
3310 |
@item |
@item |
3311 |
Dick Jackson <dick@@d-jackson.com> |
Dick Jackson <dick__at__d-jackson.com> |
3312 |
@item |
@item |
3313 |
Xuyong Liu <liu@@stsci.edu> |
Xuyong Liu <liu__at__stsci.edu> |
3314 |
@item |
@item |
3315 |
Simon Marshall <Simon.Marshall@@esrin.esa.it> |
Simon Marshall <Simon.Marshall__at__esrin.esa.it> |
3316 |
@item |
@item |
3317 |
Craig Markwardt <craigm@@cow.physics.wisc.edu> |
Craig Markwardt <craigm__at__cow.physics.wisc.edu> |
3318 |
@item |
@item |
3319 |
Laurent Mugnier <mugnier@@onera.fr> |
Laurent Mugnier <mugnier__at__onera.fr> |
3320 |
@item |
@item |
3321 |
Lubos Pochman <lubos@@rsinc.com> |
Lubos Pochman <lubos__at__rsinc.com> |
3322 |
@item |
@item |
3323 |
Bob Portmann <portmann@@al.noaa.gov> |
Bob Portmann <portmann__at__al.noaa.gov> |
3324 |
@item |
@item |
3325 |
Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov> |
Patrick M. Ryan <pat__at__jaameri.gsfc.nasa.gov> |
3326 |
@item |
@item |
3327 |
Marty Ryba <ryba@@ll.mit.edu> |
Marty Ryba <ryba__at__ll.mit.edu> |
3328 |
@item |
@item |
3329 |
Phil Williams <williams@@irc.chmcc.org> |
Phil Williams <williams__at__irc.chmcc.org> |
3330 |
@item |
@item |
3331 |
Phil Sterne <sterne@@dublin.llnl.gov> |
Phil Sterne <sterne__at__dublin.llnl.gov> |
3332 |
|
@item |
3333 |
|
Paul Sorenson <aardvark62__at__msn.com> |
3334 |
@end itemize |
@end itemize |
3335 |
|
|
3336 |
@noindent |
@noindent |
3337 |
Thanks to everyone! |
Thanks to everyone! |
3338 |
|
|
3339 |
@node Sources of Routine Info, Configuration Examples, Acknowledgements, Top |
@node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top |
3340 |
@appendix Sources of Routine Info |
@appendix Sources of Routine Info |
3341 |
|
|
3342 |
@cindex Sources of routine information |
@cindex Sources of routine information |
3348 |
@menu |
@menu |
3349 |
* Routine Definitions:: Where IDL Routines are defined. |
* Routine Definitions:: Where IDL Routines are defined. |
3350 |
* Routine Information Sources:: So how does IDLWAVE know about... |
* Routine Information Sources:: So how does IDLWAVE know about... |
3351 |
* Library Catalog:: Scanning the Libraries for Routine Info |
* Catalogs:: |
3352 |
* Load-Path Shadows:: Routines defined in several places |
* Load-Path Shadows:: Routines defined in several places |
3353 |
* Documentation Scan:: Scanning the IDL Manuals |
* Documentation Scan:: Scanning the IDL Manuals |
3354 |
@end menu |
@end menu |
3366 |
several places: |
several places: |
3367 |
|
|
3368 |
@enumerate |
@enumerate |
3369 |
@item |
@item |
3370 |
@emph{Builtin routines} are defined inside IDL itself. The source |
@emph{Builtin routines} are defined inside IDL itself. The source |
3371 |
code of such routines is not available. |
code of such routines is not available. |
3372 |
@item |
@item |
3373 |
Routines which are @emph{part of the current program}, are defined in a |
Routines which are @emph{part of the current program}, are defined in a |
3374 |
file explicitly compiled by the user. This file may or may not be |
file explicitly compiled by the user. This file may or may not be |
3375 |
located on the IDL search path. |
located on the IDL search path. |
3376 |
@item |
@item |
3377 |
@emph{Library routines} are defined in files located on IDL's search |
@emph{Library routines} are defined in files located on IDL's search |
3378 |
path, and will not need to be manually compiled. When a library routine |
path, and will not need to be manually compiled. When a library routine |
3379 |
is called for the first time, IDL will find the source file and compile |
is called for the first time, IDL will find the source file and compile |
3387 |
cannot provide routine info and completion for such external routines. |
cannot provide routine info and completion for such external routines. |
3388 |
@end enumerate |
@end enumerate |
3389 |
|
|
3390 |
@node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info |
@node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info |
3391 |
@appendixsec Routine Information Sources |
@appendixsec Routine Information Sources |
3392 |
@cindex Routine info sources |
@cindex Routine info sources |
3393 |
@cindex Builtin list of routines |
@cindex Builtin list of routines |
3402 |
@enumerate |
@enumerate |
3403 |
|
|
3404 |
@item |
@item |
3405 |
It has a @emph{builtin list} with the properties of the builtin IDL |
It has a @emph{builtin list} with information about the routines IDL |
3406 |
routines. IDLWAVE @value{VERSION} is distributed with a list of |
ships with. IDLWAVE @value{VERSION} is distributed with a list of |
3407 |
@value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords, |
@value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords, |
3408 |
reflecting IDL version @value{IDLVERSION}. This list has been created |
reflecting IDL version @value{IDLVERSION}. This list has been created |
3409 |
by scanning the IDL manuals and is stored in the file |
by scanning the IDL manuals and is stored in the file |
3410 |
@file{idlw-rinfo.el}. @xref{Documentation Scan}, for information on how |
@file{idlw-rinfo.el}. @xref{Documentation Scan}, for information on |
3411 |
to regenerate this file for new versions of IDL. |
how to regenerate this file for new versions of IDL. |
3412 |
|
|
3413 |
@item |
@item |
3414 |
It @emph{scans} all @emph{buffers} of the current Emacs session for |
It @emph{scans} all @emph{buffers} of the current Emacs session for |
3415 |
routine definitions. This is done automatically when routine |
routine definitions. This is done automatically when routine |
3416 |
information or completion is first requested by the user. Each new |
information or completion is first requested by the user. Each new |
3417 |
buffer and each buffer which is saved after making changes is also |
buffer and each buffer saved after making changes is also scanned. The |
3418 |
scanned. The command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) |
command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used |
3419 |
can be used at any time to rescan all buffers. |
at any time to rescan all buffers. |
3420 |
|
|
3421 |
@item |
@item |
3422 |
If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will |
If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will |
3428 |
routine data. |
routine data. |
3429 |
|
|
3430 |
@item |
@item |
3431 |
IDLWAVE can scan all or selected library source files and store the |
Many popular libraries are distributed with routine information |
3432 |
result in a file which will be automatically loaded just like |
already scanned into @emph{library catalogs} (@pxref{Library |
3433 |
@file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to |
Catalogs}). These per-directory catalog files can also be built by |
3434 |
scan library files. |
the user with the supplied @file{idlwave_catalog} tool. |
3435 |
|
|
3436 |
|
@item |
3437 |
|
IDLWAVE can scan selected directories of source files and store the |
3438 |
|
result in a single @emph{user catalog} file which will be |
3439 |
|
automatically loaded just like @file{idlw-rinfo.el}. @xref{User |
3440 |
|
Catalog}, for information on how to scan files in this way. |
3441 |
@end enumerate |
@end enumerate |
3442 |
|
|
3443 |
Loading routine and catalog information is a time consuming process. |
Loading routine and catalog information can be a time consuming process, |
3444 |
Depending on the system and network configuration it can take up to 30 |
especially over slow networks. Depending on the system and network |
3445 |
seconds. In order to minimize the waiting time upon your first |
configuration it could take up to 30 seconds. In order to minimize the |
3446 |
completion or routine info command in a session, IDLWAVE uses Emacs idle |
wait time upon your first completion or routine info command in a |
3447 |
time to do the initialization in 5 steps, yielding to user input in |
session, IDLWAVE uses Emacs idle time to do the initialization in six |
3448 |
between. If this gets into your way, set the variable |
steps, yielding to user input in between. If this gets into your way, |
3449 |
@code{idlwave-init-rinfo-when-idle-after} to 0 (zero). |
set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero). |
3450 |
|
The more routines documented in library and user catalogs, the slower |
3451 |
|
the loading will be, so reducing this number can help alleviate any long |
3452 |
|
load times. |
3453 |
|
|
3454 |
@defopt idlwave-init-rinfo-when-idle-after (@code{10}) |
@defopt idlwave-init-rinfo-when-idle-after (@code{10}) |
3455 |
Seconds of idle time before routine info is automatically initialized. |
Seconds of idle time before routine info is automatically initialized. |
3468 |
Controls under what circumstances routine info is updated automatically. |
Controls under what circumstances routine info is updated automatically. |
3469 |
@end defopt |
@end defopt |
3470 |
|
|
3471 |
@node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info |
@ifhtml |
3472 |
@appendixsec Library Catalog |
<A NAME="CATALOGS"></A> |
3473 |
@cindex Library scan |
@end ifhtml |
3474 |
@cindex Library catalog |
@node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info |
3475 |
|
@appendixsec Catalogs |
3476 |
|
@cindex Catalogs |
3477 |
|
|
3478 |
|
@emph{Catalogs} are files containing scanned information on individual |
3479 |
|
routines, including arguments and keywords, calling sequence, file path, |
3480 |
|
class and procedure vs. function type, etc. They represent a way of |
3481 |
|
extending the internal built-in information available for IDL system |
3482 |
|
routines (@pxref{Routine Info}) to other source collections. |
3483 |
|
|
3484 |
|
Starting with version 5.0, there are two types of catalogs available |
3485 |
|
with IDLWAVE. The traditional @emph{user catalog} and the newer |
3486 |
|
@emph{library catalogs}. Although they can be used interchangeably, the |
3487 |
|
library catalogs are more flexible, and preferred. There are few |
3488 |
|
occasions when a user catalog might be preferred --- read below. Both |
3489 |
|
types of catalogs can coexist without causing problems. |
3490 |
|
|
3491 |
|
To facilitate the catalog systems, IDLWAVE stores information it gathers |
3492 |
|
from the shell about the IDL search paths, and can write this |
3493 |
|
information out automatically, or on-demand (menu @code{Debug->Save Path |
3494 |
|
Info}). On systems with no shell from which to discover the path |
3495 |
|
information (e.g. Windows), a library path must be specified in |
3496 |
|
@code{idlwave-library-path} to allow library catalogs to be located, and |
3497 |
|
to setup directories for user catalog scan (@pxref{User Catalog} for |
3498 |
|
more on this variable). |
3499 |
|
|
3500 |
|
@defopt idlwave-auto-write-path (@code{t}) |
3501 |
|
Write out information on the !PATH and !DIR paths from IDL automatically |
3502 |
|
when they change and when the Shell is closed. These paths are needed |
3503 |
|
to locate library catalogs. |
3504 |
|
@end defopt |
3505 |
|
|
3506 |
|
@defopt idlwave-library-path |
3507 |
|
IDL library path for Windows and MacOS. Not needed under Unix/MacOSX. |
3508 |
|
@end defopt |
3509 |
|
|
3510 |
|
@defopt idlwave-system-directory |
3511 |
|
The IDL system directory for Windows and MacOS. Not needed under |
3512 |
|
Unix/MacOSX (obtained from the Shell). |
3513 |
|
@end defopt |
3514 |
|
|
3515 |
|
@defopt idlwave-config-directory (@file{~/.idlwave}) |
3516 |
|
Default path where IDLWAVE saves configuration information and any |
3517 |
|
user catalog. |
3518 |
|
@end defopt |
3519 |
|
|
3520 |
|
@menu |
3521 |
|
* Library Catalogs:: |
3522 |
|
* User Catalog:: |
3523 |
|
@end menu |
3524 |
|
|
3525 |
|
@ifhtml |
3526 |
|
<A NAME="LIBRARY_CATALOGS"></A> |
3527 |
|
@end ifhtml |
3528 |
|
@node Library Catalogs, User Catalog, Catalogs, Catalogs |
3529 |
|
@appendixsubsec Library Catalogs |
3530 |
|
@cindex @file{.idlwave_catalog} |
3531 |
|
@cindex Library catalogs |
3532 |
|
@cindex @code{idlwave_catalog} |
3533 |
|
|
3534 |
|
Library catalogs are files named @file{.idlwave_catalog} stored in |
3535 |
|
directories containing @code{.pro} routine files. They are discovered |
3536 |
|
on the IDL search path and loaded automatically when routine information |
3537 |
|
is read. Each catalog file documents the routines found in that |
3538 |
|
directory --- one catalog per directory. Every catalog has a library |
3539 |
|
name associated with it (e.g. @emph{AstroLib}). This name will be shown |
3540 |
|
briefly when the catalog is found, and in the routine info of routines |
3541 |
|
it documents. |
3542 |
|
|
3543 |
|
Many popular libraries of routines are shipped with IDLWAVE catalog |
3544 |
|
files by default, and so will be automatically discovered. Library |
3545 |
|
catalogs are scanned externally to Emacs using a tool provided with |
3546 |
|
IDLWAVE. Each catalog can be re-scanned independently of any other. |
3547 |
|
Catalogs can easily be made available system-wide with a common source |
3548 |
|
repository, providing uniform routine information, and lifting the |
3549 |
|
burden of scanning from the user (who may not even know they're using a |
3550 |
|
scanned catalog). Since all catalogs are independent, they can be |
3551 |
|
re-scanned automatically to gather updates, e.g. in a @file{cron} job. |
3552 |
|
Scanning is much faster than with the built-in user catalog method. One |
3553 |
|
minor disadvantage: the entire IDL search path is scanned for catalog |
3554 |
|
files every time IDLWAVE starts up, which might be slow over a network. |
3555 |
|
|
3556 |
|
A Perl tool to create library catalogs is distributed with IDLWAVE: |
3557 |
|
@code{idlwave_catalog}. It can be called quite simply: |
3558 |
|
@example |
3559 |
|
idlwave_catalog MyLib |
3560 |
|
@end example |
3561 |
|
|
3562 |
|
@noindent This would scan all directories recursively beneath the current and |
3563 |
|
populate them with @file{.idlwave_catalog} files, tagging the routines |
3564 |
|
found with the name library ``MyLib''. The full usage information: |
3565 |
|
|
3566 |
|
@example |
3567 |
|
Usage: idlwave_catalog [-l] [-v] [-d] [-s] [-f] [-h] libname |
3568 |
|
libname - Unique name of the catalog (4 or more alphanumeric |
3569 |
|
characters). |
3570 |
|
-l - Scan local directory only, otherwise recursively |
3571 |
|
catalog all directories at or beneath this one. |
3572 |
|
-v - Print verbose information. |
3573 |
|
-d - Instead of scanning, delete all .idlwave_catalog files |
3574 |
|
here or below. |
3575 |
|
-s - Be silent. |
3576 |
|
-f - Force overwriting any catalogs found with a different |
3577 |
|
library name. |
3578 |
|
-h - Print this usage. |
3579 |
|
@end example |
3580 |
|
|
3581 |
|
To re-load the library catalogs on the IDL path, force a system routine |
3582 |
|
info update using a single prefix to @code{idlwave-update-routine-info}: |
3583 |
|
@kbd{C-u C-c C-i}. |
3584 |
|
|
3585 |
|
@defopt idlwave-use-library-catalogs (@code{t}) |
3586 |
|
Whether to search for and load library catalogs. Only disable if |
3587 |
|
performance is a problem and the catalogs are not needed. |
3588 |
|
@end defopt |
3589 |
|
|
3590 |
|
@node User Catalog, , Library Catalogs, Catalogs |
3591 |
|
@appendixsubsec User Catalog |
3592 |
|
@cindex User catalog |
3593 |
@cindex IDL library routine info |
@cindex IDL library routine info |
3594 |
@cindex Windows |
@cindex Windows |
3595 |
@cindex MacOS |
@cindex MacOS |
3596 |
@cindex IDL variable @code{!DIR} |
@cindex IDL variable @code{!DIR} |
3597 |
@cindex @code{!DIR}, IDL variable |
@cindex @code{!DIR}, IDL variable |
3598 |
|
|
3599 |
|
The user catalog is the old routine catalog system. It is produced |
3600 |
|
within Emacs, and stored in a single file in the user's home directory |
3601 |
|
(@file{.idlwave/idlusercat.el} by default). Although library catalogs |
3602 |
|
are more flexible, there may be reasons to prefer a user catalog |
3603 |
|
instead, including: |
3604 |
|
|
3605 |
IDLWAVE can extract routine information from library modules and store |
@itemize @bullet |
3606 |
that information in a file. To do this, the variable |
@item The scan is internal to Emacs, so you don't need a working Perl |
3607 |
@code{idlwave-libinfo-file} needs to contain the path to a file in an |
installation, as you do for library catalogs. |
3608 |
existing directory (the default is @code{"~/.idlcat.el"}). Since the |
@item Can be used to scan directories for which the user has no write |
3609 |
file will contain lisp code, its name should end in @file{.el}. Under |
privileges. |
3610 |
Windows and MacOS, you also need to specify the search path for IDL |
@item Easy widget-based path selection. |
3611 |
library files in the variable @code{idlwave-library-path}, and the |
@end itemize |
3612 |
location of the IDL directory (the value of the @code{!DIR} system |
|
3613 |
variable) in the variable @code{idlwave-system-directory}, like |
However, no routine info is available in the user catalog by default; |
3614 |
this@footnote{The initial @samp{+} leads to recursive expansion of the |
the user must actively complete a scan. In addition, this type of |
3615 |
path, just like in IDL}: |
catalog is all or nothing: if a single routine changes, the entire |
3616 |
|
catalog must be rescanned to update it. Creating the user catalog is |
3617 |
|
also much slower than scanning library catalogs. |
3618 |
|
|
3619 |
|
You can scan any of the directories on the currently known path. Under |
3620 |
|
Windows and MacOS (not OSX), you need to specify the IDL search path in |
3621 |
|
the variable @code{idlwave-library-path}, and the location of the IDL |
3622 |
|
directory (the value of the @code{!DIR} system variable) in the variable |
3623 |
|
@code{idlwave-system-directory}, like this@footnote{The initial @samp{+} |
3624 |
|
leads to recursive expansion of the path, just like in IDL}: |
3625 |
|
|
3626 |
@lisp |
@lisp |
3627 |
(setq idlwave-library-path |
(setq idlwave-library-path |
3628 |
'("+c:/RSI/IDL54/lib/" "+c:/user/me/idllibs" )) |
'("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs")) |
3629 |
(setq idlwave-system-directory "c:/RSI/IDL54/") |
(setq idlwave-system-directory "c:/RSI/IDL56/") |
3630 |
@end lisp |
@end lisp |
3631 |
|
|
3632 |
@noindent Under GNU and UNIX, these values will be automatically inferred from |
@noindent Under GNU and UNIX, these values will be automatically gathered from |
3633 |
an IDLWAVE shell. |
the IDLWAVE shell. |
3634 |
|
|
3635 |
The command @kbd{M-x idlwave-create-libinfo-file} can then be used to |
The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item |
3636 |
scan library files. It brings up a widget in which you can select some |
@samp{IDLWAVE->Routine Info->Select Catalog Directories} can then be |
3637 |
or all directories on the search path. If you only want to have routine |
used to create a user catalog. It brings up a widget in which you can |
3638 |
and completion info of some libraries, it is sufficient to scan those |
select some or all directories on the search path. Directories which |
3639 |
directories. However, if you want IDLWAVE to detect possible name |
already contain a library catalog are marked with @samp{[LIB]}, and need |
3640 |
conflicts with routines defined in other libraries, the whole pass |
not be scanned (although there is no harm if you do so, other than the |
3641 |
should be scanned. |
additional memory used for the duplication). |
3642 |
|
|
3643 |
After selecting directories, click on the @w{@samp{[Scan & Save]}} |
After selecting directories, click on the @w{@samp{[Scan & Save]}} |
3644 |
button in the widget to scan all files in the selected directories and |
button in the widget to scan all files in the selected directories and |
3645 |
write the resulting routine information into the file |
write out the resulting routine information. In order to update the |
3646 |
@code{idlwave-libinfo-file}. In order to update the library information |
library information using the directory selection, call the command |
|
from the same directories, call the command |
|
3647 |
@code{idlwave-update-routine-info} with a double prefix argument: |
@code{idlwave-update-routine-info} with a double prefix argument: |
3648 |
@w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously |
@w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously |
3649 |
selected directories, write an updated version of the libinfo file and |
selected directories, write an updated version of the user catalog file |
3650 |
rebuild IDLWAVE's internal lists. If you give three prefix arguments |
and rebuild IDLWAVE's internal lists. If you give three prefix |
3651 |
@w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a background |
arguments @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a |
3652 |
job@footnote{Unix systems only, I think.}. You can continue to work, |
background job@footnote{Unix systems only, I think.}. You can continue |
3653 |
and the library catalog will be re-read when it is ready. |
to work, and the library catalog will be re-read when it is ready. If |
3654 |
|
you find you need to update the user catalog often, you should consider |
3655 |
A note of caution: Depending on your local installation, the IDL |
building a library catalog for your routines instead (@pxref{Library |
3656 |
library can be very large. Parsing it for routine information will take |
Catalogs}). |
|
time and loading this information into Emacs can require a |
|
|
significant amount of memory. However, having this information |
|
|
available will be a great help. |
|
|
|
|
|
@defopt idlwave-libinfo-file |
|
|
File for routine information of the IDL library. |
|
|
@end defopt |
|
|
|
|
|
@defopt idlwave-library-path |
|
|
IDL library path for Windows and MacOS. Not needed under Unix. |
|
|
@end defopt |
|
|
|
|
|
@defopt idlwave-system-directory |
|
|
The IDL system directory for Windows and MacOS. Not needed under Unix. |
|
|
@end defopt |
|
3657 |
|
|
3658 |
@defopt idlwave-special-lib-alist |
@defopt idlwave-special-lib-alist |
3659 |
Alist of regular expressions matching special library directories. |
Alist of regular expressions matching special library directories for |
3660 |
|
labeling in routine-info display. |
3661 |
@end defopt |
@end defopt |
3662 |
|
|
3663 |
@node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info |
@node Load-Path Shadows, Documentation Scan, Catalogs, Sources of Routine Info |
3664 |
@appendixsec Load-Path Shadows |
@appendixsec Load-Path Shadows |
3665 |
@cindex Load-path shadows |
@cindex Load-path shadows |
3666 |
@cindex Shadows, load-path |
@cindex Shadows, load-path |
3670 |
@cindex Application, testing for shadowing |
@cindex Application, testing for shadowing |
3671 |
@cindex Buffer, testing for shadowing |
@cindex Buffer, testing for shadowing |
3672 |
|
|
3673 |
IDLWAVE can compile a list of routines which are defined in several |
IDLWAVE can compile a list of routines which are (re-)defined in more |
3674 |
different files. Since one definition will hide (shadow) the others |
than one file. Since one definition will hide (shadow) the others |
3675 |
depending on which file is compiled first, such multiple definitions are |
depending on which file is compiled first, such multiple definitions are |
3676 |
called "load-path shadows". IDLWAVE has several routines to scan for |
called "load-path shadows". IDLWAVE has several routines to scan for |
3677 |
load path shadows. The output is placed into the special buffer |
load path shadows. The output is placed into the special buffer |
3678 |
@file{*Shadows*}. The format of the output is identical to the source |
@file{*Shadows*}. The format of the output is identical to the source |
3679 |
section of the routine info buffer (@pxref{Routine Info}). The |
section of the routine info buffer (@pxref{Routine Info}). The |
3680 |
different definitions of a routine are listed in the sequence of |
different definitions of a routine are ordered by @emph{likelihood of |
3681 |
@emph{likelihood of use}. So the first entry will be most likely the |
use}. So the first entry will be most likely the one you'll get if an |
3682 |
one you'll get if an unsuspecting command uses that routine. Before |
unsuspecting command uses that routine. Before listing shadows, you |
3683 |
listing shadows, you should make sure that routine info is up-to-date by |
should make sure that routine info is up-to-date by pressing @kbd{C-c |
3684 |
pressing @kbd{C-c C-i}. Here are the different routines: |
C-i}. Here are the different routines (also available in the Menu |
3685 |
|
@samp{IDLWAVE->Routine Info}): |
3686 |
|
|
3687 |
@table @asis |
@table @asis |
3688 |
@item @kbd{M-x idlwave-list-buffer-load-path-shadows} |
@item @kbd{M-x idlwave-list-buffer-load-path-shadows} |
3699 |
This command checks all routines accessible to IDLWAVE for conflicts. |
This command checks all routines accessible to IDLWAVE for conflicts. |
3700 |
@end table |
@end table |
3701 |
|
|
3702 |
For these commands to work properly you should have scanned the entire |
For these commands to work fully you need to scan the entire load path |
3703 |
load path, not just selected directories. Also, IDLWAVE should be able |
in either a user or library catalog. Also, IDLWAVE should be able to |
3704 |
to distinguish between the system library files (normally installed in |
distinguish between the system library files (normally installed in |
3705 |
@file{/usr/local/rsi/idl/lib}) and any site specific or user specific |
@file{/usr/local/rsi/idl/lib}) and any site specific or user specific |
3706 |
files. Therefore, such local files should not be installed inside the |
files. Therefore, such local files should not be installed inside the |
3707 |
@file{lib} directory of the IDL directory. This is also advisable for |
@file{lib} directory of the IDL directory. This is also advisable for |
3721 |
on the load path is routine info display (@pxref{Routine Info}). |
on the load path is routine info display (@pxref{Routine Info}). |
3722 |
|
|
3723 |
@node Documentation Scan, , Load-Path Shadows, Sources of Routine Info |
@node Documentation Scan, , Load-Path Shadows, Sources of Routine Info |
3724 |
@appendixsec Documentation Scan |
@appendixsec Documentation Scan |
3725 |
@cindex @file{get_rinfo} |
@cindex @file{get_html_rinfo} |
3726 |
@cindex @file{idlw-rinfo.el} |
@cindex @file{idlw-rinfo.el} |
|
@cindex @file{idlw-help.txt} |
|
|
@cindex @file{idlw-help.el} |
|
3727 |
@cindex Scanning the documentation |
@cindex Scanning the documentation |
3728 |
@cindex Perl program, to create @file{idlw-rinfo.el} |
@cindex Perl program, to create @file{idlw-rinfo.el} |
3729 |
|
|
3730 |
IDLWAVE derives it knowledge about system routines from the IDL |
IDLWAVE derives its knowledge about system routines from the IDL |
3731 |
manuals. The file @file{idlw-rinfo.el} contains the routine information |
manuals. The file @file{idlw-rinfo.el} contains the routine information |
3732 |
for the IDL system routines. The Online Help feature of IDLWAVE |
for the IDL system routines, and links to relevant sections of the HTML |
3733 |
requires ASCII versions of some IDL manuals to be available in a |
documentation. The Online Help feature of IDLWAVE requires HTML |
3734 |
specific format (@file{idlw-help.txt}), along with an Emacs-Lisp file |
versions of the IDL manuals to be available; the HTML documentation is |
3735 |
@file{idlw-help.el} with supporting code and pointers to the ASCII file. |
not distributed with IDLWAVE by default, but must be downloaded |
3736 |
|
separately from the @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers |
3737 |
All 3 files can be derived from the IDL documentation. If you are |
webpage}. |
3738 |
lucky, the maintainer of IDLWAVE will always have access to the newest |
|
3739 |
version of IDL and provide updates. The IDLWAVE distribution also |
The HTML files and related images can be produced from the |
3740 |
contains the Perl program @file{get_rinfo} which constructs these files |
@file{idl.chm} HTMLHelp file distributed with IDL using the free |
3741 |
by scanning selected files from the IDL documentation. Instructions on |
Microsoft HTML Help Workshop. If you are lucky, the maintainer of |
3742 |
how to use @file{get_rinfo} are in the program itself. |
IDLWAVE will always have access to the newest version of IDL and |
3743 |
|
provide updates. The IDLWAVE distribution also contains the Perl |
3744 |
One particularly frustrating situation occurs when a new IDL version is |
program @file{get_html_rinfo} which constructs the |
3745 |
released without the associated documentation updates. Instead, a |
@file{idlw-rinfo.el} file by scanning the HTML documents produced from |
3746 |
@emph{What's New} file containing new and updated documentation is |
the IDL documentation. Instructions on how to use |
3747 |
shipped alongside the previous version's reference material. The |
@file{get_html_rinfo} are in the program itself. |
3748 |
@file{get_rinfo} script can merge this new information into the standard |
|
3749 |
help text and routine information, as long as it is pre-formatted in a |
@node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top |
3750 |
simple way. See @file{get_rinfo} for more information. |
@appendix HTML Help Browser Tips |
3751 |
|
@cindex Browser Tips |
3752 |
|
|
3753 |
|
There are a wide variety of possible browsers to use for displaying |
3754 |
|
the online HTML help available with IDLWAVE (starting with version |
3755 |
|
5.0). Since IDLWAVE runs on a many different system types, a single |
3756 |
|
browser configuration is not possible, but choices abound. |
3757 |
|
|
3758 |
|
On many systems, the default browser configured in |
3759 |
|
@code{browse-url-browser-function}, and hence inherited by default by |
3760 |
|
@code{idlwave-help-browser-function}, is Netscape. Unfortunately, the |
3761 |
|
HTML manuals decompiled from the original RSI source contain |
3762 |
|
formatting structures which Netscape 4.x does not handle well, though |
3763 |
|
they are still readable. A much better choice is Mozilla, or one of |
3764 |
|
the Mozilla-derived browsers such as |
3765 |
|
@uref{http://galeon.sourceforge.net/,Galeon} (Linux), |
3766 |
|
@uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or |
3767 |
|
@uref{http://www.mozilla.org/projects/firebird/,Firebird} (all |
3768 |
|
platforms). Newer versions of Emacs provide a browser-function choice |
3769 |
|
@code{browse-url-gnome-moz} which uses the Gnome-configured browser. |
3770 |
|
|
3771 |
|
Note that the HTML files decompiled from RSI Microsoft Help sources |
3772 |
|
contain specific references to the @samp{Symbol} font, which by default |
3773 |
|
is not permitted in normal encodings (it's technically illegal). Though |
3774 |
|
it only impacts a few symbols, you can trick Mozilla-based browsers into |
3775 |
|
recognizing @samp{Symbol} by following the directions |
3776 |
|
@uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With this |
3777 |
|
fix in place, HTML help pages look almost identical to their PDF |
3778 |
|
equivalents (yet can be bookmarked, browsed as history, searched, etc.). |
3779 |
|
|
3780 |
|
@noindent Individual platform recommendations: |
3781 |
|
|
3782 |
|
@itemize @bullet |
3783 |
|
@item Windows: The native Microsoft HTMLHelp browser is preferred, |
3784 |
|
with even better results using the free |
3785 |
|
@uref{http://www.keyworks.net/keyhh.htm,@code{KEYHH}} program to |
3786 |
|
permit IDL help to be targetted to a single window. To use HTMLHelp, |
3787 |
|
specify @code{idlwave-help-use-hh} as @code{'hh} or @code{'keyhh}. |
3788 |
|
One bonus: since IDL is shipped with the @file{idl.chm} help file, you |
3789 |
|
don't need to download the HTML help package. @xref{Help with HTML |
3790 |
|
Documentation}. |
3791 |
|
@item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser |
3792 |
|
and its associated |
3793 |
|
@uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode |
3794 |
|
provide in-buffer browsing with image display, and excellent speed and |
3795 |
|
formatting. Both the Emacs mode and the browser itself must be |
3796 |
|
downloaded separately. To use this browser, include |
3797 |
|
|
3798 |
|
@lisp |
3799 |
|
(setq idlwave-help-browser-function 'w3m-browse-url) |
3800 |
|
@end lisp |
3801 |
|
|
3802 |
@node Configuration Examples, Windows and MacOS, Sources of Routine Info, Top |
in your @file{.emacs}. Setting a few other nice @code{w3m} options |
3803 |
|
cuts down on screen clutter: |
3804 |
|
|
3805 |
|
@lisp |
3806 |
|
(setq w3m-use-tab nil |
3807 |
|
w3m-use-header-line nil |
3808 |
|
w3m-use-toolbar nil) |
3809 |
|
@end lisp |
3810 |
|
|
3811 |
|
If you use a dedicated frame for help, you might want to add the |
3812 |
|
following, to get consistent behavior with the @kbd{q} key: |
3813 |
|
|
3814 |
|
@lisp |
3815 |
|
;; Close my help window when w3m closes. |
3816 |
|
(defadvice w3m-close-window (after idlwave-close activate) |
3817 |
|
(if (boundp 'idlwave-help-frame) |
3818 |
|
(idlwave-help-quit))) |
3819 |
|
@end lisp |
3820 |
|
|
3821 |
|
Note that you can open the file in an external browser from within |
3822 |
|
@code{w3m} using @kbd{M}. |
3823 |
|
@end itemize |
3824 |
|
|
3825 |
|
@node Configuration Examples, Windows and MacOS, HTML Help Browser Tips, Top |
3826 |
@appendix Configuration Examples |
@appendix Configuration Examples |
3827 |
@cindex Configuration examples |
@cindex Configuration examples |
3828 |
@cindex Example configuration |
@cindex Example configuration |
3883 |
(setq idlwave-main-block-indent 3) |
(setq idlwave-main-block-indent 3) |
3884 |
(setq idlwave-end-offset -3) |
(setq idlwave-end-offset -3) |
3885 |
(setq idlwave-continuation-indent 1) |
(setq idlwave-continuation-indent 1) |
3886 |
(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" |
(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" |
3887 |
; anchored at start of line. |
; anchored at start of line. |
3888 |
(setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> |
(setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> |
3889 |
(setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' |
(setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' |
3901 |
("SETPROPERTY" .t) |
("SETPROPERTY" .t) |
3902 |
("GETPROPERTY" .t))) |
("GETPROPERTY" .t))) |
3903 |
|
|
3904 |
|
;; Using w3m for help (must install w3m and emacs-w3m) |
3905 |
|
(autoload 'w3m-browse-url "w3m" "Interface for w3m on Emacs." t) |
3906 |
|
(setq idlwave-help-browser-function 'w3m-browse-url |
3907 |
|
w3m-use-tab nil ; no tabs, location line, or toolbar |
3908 |
|
w3m-use-header-line nil |
3909 |
|
w3m-use-toolbar nil) |
3910 |
|
|
3911 |
|
;; Close my help window or frame when w3m closes with `q' |
3912 |
|
(defadvice w3m-close-window (after idlwave-close activate) |
3913 |
|
(if (boundp 'idlwave-help-frame) |
3914 |
|
(idlwave-help-quit))) |
3915 |
|
|
3916 |
;; Some setting can only be done from a mode hook. Here is an example: |
;; Some setting can only be done from a mode hook. Here is an example: |
3917 |
(add-hook 'idlwave-mode-hook |
(add-hook 'idlwave-mode-hook |
3918 |
(lambda () |
(lambda () |
3920 |
;; Run other functions here |
;; Run other functions here |
3921 |
(font-lock-mode 1) ; Turn on font-lock mode |
(font-lock-mode 1) ; Turn on font-lock mode |
3922 |
(idlwave-auto-fill-mode 0) ; Turn off auto filling |
(idlwave-auto-fill-mode 0) ; Turn off auto filling |
3923 |
|
(setq idlwave-help-browser-function 'browse-url-w3) |
3924 |
|
|
3925 |
;; Pad with 1 space (if -n is used then make the |
;; Pad with 1 space (if -n is used then make the |
3926 |
;; padding a minimum of n spaces.) The defaults use -1 |
;; padding a minimum of n spaces.) The defaults use -1 |
3950 |
;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. |
;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. |
3951 |
|
|
3952 |
;; Some personal abbreviations |
;; Some personal abbreviations |
3953 |
(define-abbrev idlwave-mode-abbrev-table |
(define-abbrev idlwave-mode-abbrev-table |
3954 |
(concat idlwave-abbrev-start-char "wb") "widget_base()" |
(concat idlwave-abbrev-start-char "wb") "widget_base()" |
3955 |
(idlwave-keyword-abbrev 1)) |
(idlwave-keyword-abbrev 1)) |
3956 |
(define-abbrev idlwave-mode-abbrev-table |
(define-abbrev idlwave-mode-abbrev-table |
3957 |
(concat idlwave-abbrev-start-char "on") "obj_new()" |
(concat idlwave-abbrev-start-char "on") "obj_new()" |
3958 |
(idlwave-keyword-abbrev 1)) |
(idlwave-keyword-abbrev 1)) |
3959 |
)) |
)) |
3971 |
(add-hook 'idlwave-shell-mode-hook |
(add-hook 'idlwave-shell-mode-hook |
3972 |
(lambda () |
(lambda () |
3973 |
;; Set up some custom key and mouse examine commands |
;; Set up some custom key and mouse examine commands |
3974 |
(idlwave-shell-define-key-both [s-down-mouse-2] |
(idlwave-shell-define-key-both [s-down-mouse-2] |
3975 |
(idlwave-shell-mouse-examine |
(idlwave-shell-mouse-examine |
3976 |
"print, size(___,/DIMENSIONS)")) |
"print, size(___,/DIMENSIONS)")) |
3977 |
(idlwave-shell-define-key-both [f9] (idlwave-shell-examine |
(idlwave-shell-define-key-both [f9] (idlwave-shell-examine |
3978 |
"print, size(___,/DIMENSIONS)")) |
"print, size(___,/DIMENSIONS)")) |
3979 |
(idlwave-shell-define-key-both [f10] (idlwave-shell-examine |
(idlwave-shell-define-key-both [f10] (idlwave-shell-examine |
3980 |
"print,size(___,/TNAME)")) |
"print,size(___,/TNAME)")) |
3981 |
(idlwave-shell-define-key-both [f11] (idlwave-shell-examine |
(idlwave-shell-define-key-both [f11] (idlwave-shell-examine |
3982 |
"help,___,/STRUCTURE")))) |
"help,___,/STRUCTURE")))) |
3985 |
@ifhtml |
@ifhtml |
3986 |
<A NAME="WIN_MAC"></A> |
<A NAME="WIN_MAC"></A> |
3987 |
@end ifhtml |
@end ifhtml |
3988 |
@node Windows and MacOS, Index, Configuration Examples, Top |
@node Windows and MacOS, Troubleshooting, Configuration Examples, Top |
3989 |
@appendix Windows and MacOS |
@appendix Windows and MacOS |
3990 |
@cindex Windows |
@cindex Windows |
3991 |
@cindex MacOS |
@cindex MacOS |
3992 |
|
@cindex MacOSX |
3993 |
|
|
3994 |
IDLWAVE was developed on a UNIX system. However, due to the portability |
IDLWAVE was developed on a UNIX system. However, thanks to the |
3995 |
of Emacs, much of IDLWAVE does also work under different operating |
portability of Emacs, much of IDLWAVE does also work under different |
3996 |
systems like Windows (with NTEmacs or NTXEmacs) or MacOS. |
operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS. |
3997 |
|
|
3998 |
The only problem really is that RSI does not provide a command-line |
The only real problem is that RSI does not provide a command-line |
3999 |
version of IDL for Windows or MacOS with which IDLWAVE can |
version of IDL for Windows or MacOS(<=9) with which IDLWAVE can |
4000 |
interact@footnote{Call your RSI representative and complain --- it |
interact@footnote{Call your RSI representative and complain --- it |
4001 |
should be trivial for them to provide one. And if enough people ask |
should be trivial for them to provide one. And if enough people ask for |
4002 |
for it, maybe they will. The upcoming IDL for Mac OSX is slated to |
it, maybe they will. The new MacOSX version of IDL @emph{does} have a |
4003 |
have a command-line version.}. Therefore the IDLWAVE Shell does not |
shell and works well with IDLWAVE.}. As a result, the IDLWAVE Shell |
4004 |
work and you have to rely on IDLDE to run and debug your programs. |
does not work and you have to rely on IDLDE to run and debug your |
4005 |
However, editing IDL source files with Emacs/IDLWAVE works with all |
programs. However, editing IDL source files with Emacs/IDLWAVE works |
4006 |
bells and whistles, including routine info, completion and fast online |
with all bells and whistles, including routine info, completion and fast |
4007 |
help. Only a small amount of additional information must be specified |
online help. Only a small amount of additional information must be |
4008 |
in your .emacs file: the path names which, on a UNIX system, are |
specified in your @file{.emacs} file: the path names which, on a UNIX |
4009 |
automatically gathered by talking to the IDL program. |
system, are automatically gathered by talking to the IDL program. |
4010 |
|
|
4011 |
Here is an example of the additional configuration needed for a Windows |
Here is an example of the additional configuration needed for a Windows |
4012 |
system. I am assuming that IDLWAVE has been installed in |
system. I am assuming that IDLWAVE has been installed in |
4014 |
@w{@samp{C:\RSI\IDL55}}. |
@w{@samp{C:\RSI\IDL55}}. |
4015 |
|
|
4016 |
@lisp |
@lisp |
4017 |
;; location of the lisp files (needed if IDLWAVE is not part of |
;; location of the lisp files (needed if IDLWAVE is not part of |
4018 |
;; the X/Emacs installation) |
;; the X/Emacs installation) |
4019 |
(setq load-path (cons "c:/program files/IDLWAVE" load-path)) |
(setq load-path (cons "c:/program files/IDLWAVE" load-path)) |
4020 |
|
|
4026 |
;; location of the IDL system directory (try "print,!DIR") |
;; location of the IDL system directory (try "print,!DIR") |
4027 |
(setq idlwave-system-directory "c:/RSI/IDL55/") |
(setq idlwave-system-directory "c:/RSI/IDL55/") |
4028 |
|
|
4029 |
;; location of the IDLWAVE help files idlw-help.el and idlw-help.txt. |
;; specify using the HTMLHelp documentation for online help, with the |
4030 |
(setq idlwave-help-directory "c:/IDLWAVE") |
;; KEYHH helper routine (Windows only) |
4031 |
|
(setq idlwave-use-hh 'keyhh) |
4032 |
|
|
4033 |
;; file in which to store the user catalog info |
;; file in which to store the user catalog info |
4034 |
(setq idlwave-libinfo-file "c:/IDLWAVE/idlcat.el") |
(setq idlwave-user-catalog-file "c:/IDLWAVE/idlcat.el") |
4035 |
@end lisp |
@end lisp |
4036 |
|
|
4037 |
@noindent Furthermore, Windows sometimes tries to outsmart you --- make |
@noindent Furthermore, Windows sometimes tries to outsmart you --- make |
4038 |
sure you check the following things: |
sure you check the following things: |
4039 |
|
|
4040 |
@itemize @bullet |
@itemize @bullet |
4041 |
@item When you download the IDLWAVE distribution, make sure you save the |
@item When you download the IDLWAVE distribution, make sure you save the |
4042 |
files under the names @file{idlwave.tar.gz} and |
file under the names @file{idlwave.tar.gz}. |
|
@file{idlwave-help-tar.gz}. |
|
|
@item Be sure that your software for untarring/ungzipping is @emph{NOT} |
|
|
doing smart CR/LF conversion (WinZip users will find this in |
|
|
Options:Configuration:Miscellaneous, change the setting, then re-open |
|
|
the archive). This adds one byte per line, throwing off the |
|
|
byte-counts for the help file lookups and defeating fast online help lookup. |
|
4043 |
@item M-TAB switches among running programs --- use Esc-TAB |
@item M-TAB switches among running programs --- use Esc-TAB |
4044 |
instead. |
instead. |
4045 |
@item Other issues as yet unnamed... |
@item Other issues as yet unnamed... |
4046 |
@end itemize |
@end itemize |
4047 |
|
|
4048 |
|
Windows users who'd like to make use of IDLWAVE's context-aware HTML |
4049 |
|
help can skip the browser and use the HTMLHelp functionality directly. |
4050 |
|
@xref{Help with HTML Documentation}. |
4051 |
|
|
4052 |
|
@ifhtml |
4053 |
|
<A NAME="TROUBLE"></A> |
4054 |
|
@end ifhtml |
4055 |
|
@node Troubleshooting, Index, Windows and MacOS, Top |
4056 |
|
@appendix Troubleshooting |
4057 |
|
@cindex Troubleshooting |
4058 |
|
|
4059 |
|
Although IDLWAVE usually installs and works without difficulty, a few |
4060 |
|
common problems and their solutions are documented below. |
4061 |
|
|
4062 |
|
@enumerate |
4063 |
|
|
4064 |
|
@item @strong{Whenever an IDL error occurs or a breakpoint is hit, I get |
4065 |
|
errors or strange behavior when I try to type anything into some of my |
4066 |
|
IDLWAVE buffers.} |
4067 |
|
|
4068 |
|
This is a @emph{feature}, not an error. You're in @emph{Electric |
4069 |
|
Debug Mode} (@pxref{Electric Debug Mode}). You should see |
4070 |
|
@code{*Debugging*} in the mode-line. The buffer is read-only and all |
4071 |
|
debugging and examination commands are available as single keystrokes; |
4072 |
|
@kbd{C-?} lists these shortcuts. Use @kbd{q} to quit the mode, and |
4073 |
|
customize the variable @code{idlwave-shell-automatic-electric-debug} |
4074 |
|
if you prefer not to enter electric debug on breakpoints@dots{} but |
4075 |
|
you really should try it before you disable it! You can also |
4076 |
|
customize this variable to enter debug mode when errors are |
4077 |
|
encountered too. |
4078 |
|
|
4079 |
|
@item @strong{I get errors like @samp{Searching for program: no such |
4080 |
|
file or directory, idl} when attempting to start the IDL shell.} |
4081 |
|
|
4082 |
|
IDLWAVE needs to know where IDL is in order to run it as a process. |
4083 |
|
By default, it attempts to invoke it simply as @samp{idl}, which |
4084 |
|
presumes such an executable is on your search path. You need to |
4085 |
|
ensure @samp{idl} is on your @samp{$PATH}, or specify the full |
4086 |
|
pathname to the idl program with the variable |
4087 |
|
@code{idlwave-shell-explicit-file-name}. Note that you may need to |
4088 |
|
set your shell search path in two places when running Emacs as an Aqua |
4089 |
|
application with MacOSX; see the next topic. |
4090 |
|
|
4091 |
|
@item @strong{IDLWAVE is disregarding my @samp{IDL_PATH} which I set |
4092 |
|
under MacOSX} |
4093 |
|
|
4094 |
|
If you run Emacs directly as an Aqua application, rather than from the |
4095 |
|
console shell, the environment is set not from your usual shell |
4096 |
|
configuration files (e.g. @file{.cshrc}), but from the file |
4097 |
|
@file{~/.MacOSX/environment.plist}. Either include your path settings |
4098 |
|
there, or start Emacs and IDLWAVE from the shell. |
4099 |
|
|
4100 |
|
@item @strong{I get errors like @samp{Symbol's function is void: |
4101 |
|
overlayp} when trying to start the shell in XEmacs} |
4102 |
|
|
4103 |
|
You don't have the @samp{fsf-compat} package installed, which IDLWAVE |
4104 |
|
needs to run under XEmacs. Install it and, if necessary, insert |
4105 |
|
@code{(require 'overlay)} in your @file{.emacs}. |
4106 |
|
|
4107 |
|
@item @strong{I'm getting errors like @samp{Symbol's value as variable is void: |
4108 |
|
cl-builtin-gethash} on completion or routine info.} |
4109 |
|
|
4110 |
|
This error arises if you upgraded Emacs from 20.x to 21.x without |
4111 |
|
re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible |
4112 |
|
in compiled lisp files. Presumably, you kept the original .elc files in |
4113 |
|
place, and this is the source of the error. If you recompile (or just |
4114 |
|
"make; make install") from source, it should resolve this problem. |
4115 |
|
Another option is to recompile the @file{idlw*.el} files by hand using |
4116 |
|
@kbd{M-x byte-compile-file}. Why not take the opportunity to grab the |
4117 |
|
latest IDLWAVE version at @uref{@value{IDLWAVE-HOMEPAGE}, the |
4118 |
|
maintainers webpage} |
4119 |
|
|
4120 |
|
@item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches |
4121 |
|
windows on my desktop.} |
4122 |
|
|
4123 |
|
Your system is trapping @kbd{M-@key{TAB}} and using it for its own |
4124 |
|
nefarious purposes: Emacs never sees the keystrokes. On many Unix |
4125 |
|
systems, you can reconfigure your window manager to use another key |
4126 |
|
sequence for switching among windows. Another option is to use the |
4127 |
|
equivalent sequence @kbd{@key{ESC}-@key{TAB}}. |
4128 |
|
|
4129 |
|
@item @strong{When stopping at breakpoints or errors, IDLWAVE does not |
4130 |
|
seem to highlight the relevant line in the source.} |
4131 |
|
|
4132 |
|
IDLWAVE scans for error and halt messages and highlights the stop |
4133 |
|
location in the correct file. However, if you've changed the system |
4134 |
|
variable @samp{!ERROR_STATE.MSG_PREFIX}, it is unable to parse these |
4135 |
|
message correctly. Don't do that. |
4136 |
|
|
4137 |
|
@item @strong{IDLWAVE doesn't work correctly when using ENVI.} |
4138 |
|
|
4139 |
|
Though IDLWAVE was not written with ENVI in mind, it works just fine |
4140 |
|
with it, as long as you update the prompt it's looking for (@samp{IDL> |
4141 |
|
} by default). You can do this with the variable |
4142 |
|
@code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g., |
4143 |
|
in your @file{.emacs}: |
4144 |
|
|
4145 |
|
@lisp |
4146 |
|
(setq idlwave-shell-prompt-pattern "^\\(ENVI\\|IDL\\)> ") |
4147 |
|
@end lisp |
4148 |
|
|
4149 |
|
@item @strong{Attempts to set breakpoints fail: no breakpoint is |
4150 |
|
indicated in the IDLWAVE buffer.} |
4151 |
|
|
4152 |
|
IDL changed its breakpoint reporting format starting with IDLv5.5. The |
4153 |
|
first version of IDLWAVE to support the new format is IDLWAVE v4.10. If |
4154 |
|
you have an older version and are using IDL >v5.5, you need to upgrade, |
4155 |
|
and/or make sure your recent version of IDLWAVE is being found on the |
4156 |
|
Emacs load-path (see the next entry). You can list the version being |
4157 |
|
used with @kbd{C-h v idlwave-mode-version @key{RET}}. |
4158 |
|
|
4159 |
|
@item @strong{I installed a new version of IDLWAVE, but the old |
4160 |
|
version is still being used} or @strong{IDLWAVE works, but when I |
4161 |
|
tried to install the optional modules @file{idlw-roprompt.el} or |
4162 |
|
@file{idlw-complete-structtag}, I get errors like @samp{Cannot open |
4163 |
|
load file}}. |
4164 |
|
|
4165 |
|
The problem is that your Emacs is not finding the version of IDLWAVE you |
4166 |
|
installed. Many Emacsen come with an older bundled copy of IDLWAVE |
4167 |
|
(e.g. v4.7 for Emacs 21.x), which is likely what's being used instead. |
4168 |
|
You need to make sure your Emacs @emph{load-path} contains the directory |
4169 |
|
where IDLWAVE is installed (@file{/usr/local/share/emacs/site-lisp}, by |
4170 |
|
default), @emph{before} Emacs' default search directories. You can |
4171 |
|
accomplish this by putting the following in your @file{.emacs}: |
4172 |
|
|
4173 |
|
@lisp |
4174 |
|
(setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path)) |
4175 |
|
@end lisp |
4176 |
|
|
4177 |
|
@noindent You can check on your load-path value using @kbd{C-h v |
4178 |
|
load-path @key{RET}}. |
4179 |
|
|
4180 |
|
@item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.} |
4181 |
|
|
4182 |
|
Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated |
4183 |
|
programming mode for CORBA's Interface Definition Language (you should |
4184 |
|
see @samp{(IDL)}, not @samp{(IDLWAVE)} in the mode-line). One |
4185 |
|
solution: don't name your file @file{.idl}, but rather @file{.pro}. |
4186 |
|
Another solution: make sure @file{.idl} files load IDLWAVE instead of |
4187 |
|
@samp{idl-mode} by adding the following to your @file{.emacs}: |
4188 |
|
|
4189 |
|
@lisp |
4190 |
|
(setcdr (rassoc 'idl-mode auto-mode-alist) 'idlwave-mode) |
4191 |
|
@end lisp |
4192 |
|
|
4193 |
|
@item @strong{The routine info for my local routines is out of date!} |
4194 |
|
|
4195 |
|
IDLWAVE collects routine info from various locations (@pxref{Routine |
4196 |
|
Information Sources}). Routines in files visited in a buffer or |
4197 |
|
compiled in the shell should be up to date. For other routines, the |
4198 |
|
information is only as current as the most recent scan. If you have a |
4199 |
|
rapidly changing set of routines, and you'd like the latest routine |
4200 |
|
information to be available for it, one powerful technique makes use of |
4201 |
|
the library catalog tool, @samp{idlwave_catalog}. Simply add a line to |
4202 |
|
your @samp{cron} file (@samp{crontab -e} will let you edit this on some |
4203 |
|
systems), like this: |
4204 |
|
|
4205 |
|
@example |
4206 |
|
45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib) |
4207 |
|
@end example |
4208 |
|
|
4209 |
|
@noindent where @samp{MyLib} is the name of your library. This will |
4210 |
|
rescan all @file{.pro} files at or below @file{/path/to/myidllib} every |
4211 |
|
week night at 3:45am. You can even scan site-wide libraries with this |
4212 |
|
method, and the most recent information will be available to all users. |
4213 |
|
|
4214 |
|
@item @strong{All the Greek-font characters in the HTML help are |
4215 |
|
displayed as Latin characters!} |
4216 |
|
|
4217 |
|
Unfortunately, the HTMLHelp files RSI provides attempt to switch to |
4218 |
|
@samp{Symbol} font to display Greek characters, which is not really an |
4219 |
|
permitted method for doing this in HTML. There is a "workaround" for |
4220 |
|
many browsers: @xref{HTML Help Browser Tips}. |
4221 |
|
|
4222 |
|
@item @strong{In the shell, my long commands are truncated at 256 characters!} |
4223 |
|
|
4224 |
|
This actually happens when running IDL in an XTerm as well. There are |
4225 |
|
a couple of work arounds: @code{define_key,/control,'^d'} (e.g. in |
4226 |
|
your @file{$IDL_STARTUP} file) will disable the @samp{EOF} character |
4227 |
|
and give you a 512 character limit. You won't be able to use |
4228 |
|
@key{C-d} to quit the shell, however. Another possibility is |
4229 |
|
@code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a |
4230 |
|
memory-bounded limit), but disables the processing of background |
4231 |
|
widget events (those with @code{/NO_BLOCK} passed to @code{XManager}). |
4232 |
|
|
4233 |
|
@end enumerate |
4234 |
|
|
4235 |
@node Index, , Windows and MacOS, Top |
@node Index, , Troubleshooting, Top |
4236 |
@unnumbered Index |
@unnumbered Index |
4237 |
@printindex cp |
@printindex cp |
4238 |
|
|