84302
|
1 \input texinfo @c -*-texinfo-*-
|
|
2 @c %**start of header
|
|
3 @setfilename ../info/idlwave
|
|
4 @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
|
|
10 @syncodeindex vr cp
|
|
11 @syncodeindex fn cp
|
|
12 @set VERSION 6.1
|
|
13 @set EDITION 6.1
|
|
14 @set IDLVERSION 6.3
|
|
15 @set NSYSROUTINES 4346
|
|
16 @set DATE April, 2007
|
|
17 @set AUTHOR J.D. Smith & Carsten Dominik
|
|
18 @set MAINTAINER J.D. Smith
|
|
19 @c %**end of header
|
|
20 @finalout
|
|
21
|
|
22 @ifinfo
|
|
23 This file documents IDLWAVE, a major mode for editing IDL files with
|
|
24 Emacs, and interacting with an IDL shell run as a subprocess.
|
|
25
|
|
26 This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE
|
|
27 @value{VERSION}
|
|
28
|
|
29 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
|
|
30 2006, 2007 Free Software Foundation, Inc.
|
|
31
|
|
32 Permission is granted to copy, distribute and/or modify this document
|
|
33 under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
34 any later version published by the Free Software Foundation; with no
|
|
35 Invariant Sections, with the Front-Cover texts being ``A GNU
|
|
36 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
|
|
37 license is included in the section entitled ``GNU Free Documentation
|
|
38 License'' in the Emacs manual.
|
|
39
|
|
40 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
|
|
41 this GNU Manual, like GNU software. Copies published by the Free
|
|
42 Software Foundation raise funds for GNU development.''
|
|
43
|
|
44 This document is part of a collection distributed under the GNU Free
|
|
45 Documentation License. If you want to distribute this document
|
|
46 separately from the collection, you can do so by adding a copy of the
|
|
47 license to the document, as described in section 6 of the license.
|
|
48 @end ifinfo
|
|
49
|
|
50 @titlepage
|
|
51 @title IDLWAVE User Manual
|
|
52 @subtitle Emacs major mode and shell for IDL
|
|
53 @subtitle Edition @value{EDITION}, @value{DATE}
|
|
54
|
|
55 @author by J.D. Smith & Carsten Dominik
|
|
56 @page
|
|
57 This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for
|
|
58 IDLWAVE version @value{VERSION}, @value{DATE}.
|
|
59 @sp 2
|
|
60 Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004, 2005,
|
|
61 2006, 2007 Free Software Foundation, Inc.
|
|
62 @sp 2
|
|
63 @cindex Copyright, of IDLWAVE
|
|
64 Permission is granted to copy, distribute and/or modify this document
|
|
65 under the terms of the GNU Free Documentation License, Version 1.2 or
|
|
66 any later version published by the Free Software Foundation; with no
|
|
67 Invariant Sections, with the Front-Cover texts being ``A GNU
|
|
68 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
|
|
69 license is included in the section entitled ``GNU Free Documentation
|
|
70 License'' in the Emacs manual.
|
|
71
|
|
72 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
|
|
73 this GNU Manual, like GNU software. Copies published by the Free
|
|
74 Software Foundation raise funds for GNU development.''
|
|
75
|
|
76 This document is part of a collection distributed under the GNU Free
|
|
77 Documentation License. If you want to distribute this document
|
|
78 separately from the collection, you can do so by adding a copy of the
|
|
79 license to the document, as described in section 6 of the license.
|
|
80 @end titlepage
|
|
81 @contents
|
|
82
|
|
83 @page
|
|
84
|
|
85 @ifnottex
|
|
86
|
|
87 @node Top, Introduction, (dir), (dir)
|
|
88
|
|
89 IDLWAVE is a package which supports editing source code written in the
|
|
90 Interactive Data Language (IDL), and running IDL as an inferior shell.
|
|
91
|
|
92 @end ifnottex
|
|
93
|
|
94 @menu
|
|
95 * Introduction:: What IDLWAVE is, and what it is not
|
|
96 * IDLWAVE in a Nutshell:: One page quick-start guide
|
|
97 * Getting Started:: Tutorial
|
|
98 * The IDLWAVE Major Mode:: The mode for editing IDL programs
|
|
99 * The IDLWAVE Shell:: The mode for running IDL as an inferior program
|
|
100 * Acknowledgements:: Who did what
|
|
101 * Sources of Routine Info:: How does IDLWAVE know about routine XYZ
|
|
102 * HTML Help Browser Tips::
|
|
103 * Configuration Examples:: The user is king
|
|
104 * Windows and MacOS:: What still works, and how
|
|
105 * Troubleshooting:: When good computers turn bad
|
|
106 * GNU Free Documentation License:: The license for this documentation.
|
|
107 * Index:: Fast access
|
|
108
|
|
109 @detailmenu
|
|
110 --- The Detailed Node Listing ---
|
|
111
|
|
112 Getting Started (Tutorial)
|
|
113
|
|
114 * Lesson I -- Development Cycle::
|
|
115 * Lesson II -- Customization::
|
|
116 * Lesson III -- User Catalog::
|
|
117
|
|
118 The IDLWAVE Major Mode
|
|
119
|
|
120 * Code Formatting:: Making code look nice
|
|
121 * Routine Info:: Calling Sequence and Keyword List
|
|
122 * Online Help:: One key press from source to help
|
|
123 * Completion:: Completing routine names and Keywords
|
|
124 * Routine Source:: Finding routines, the easy way
|
|
125 * Resolving Routines:: Force the Shell to compile a routine
|
|
126 * Code Templates:: Frequent code constructs
|
|
127 * Abbreviations:: Abbreviations for common commands
|
|
128 * Actions:: Changing case, Padding, End checking
|
|
129 * Doc Header:: Inserting a standard header
|
|
130 * Motion Commands:: Moving through the structure of a program
|
|
131 * Misc Options:: Things that fit nowhere else
|
|
132
|
|
133 Code Formatting
|
|
134
|
|
135 * Code Indentation:: Reflecting the logical structure
|
|
136 * Continued Statement Indentation::
|
|
137 * Comment Indentation:: Special indentation for comment lines
|
|
138 * Continuation Lines:: Splitting statements over lines
|
|
139 * Syntax Highlighting:: Font-lock support
|
|
140 * Octals and Highlighting:: Why "123 causes problems
|
|
141
|
|
142 Online Help
|
|
143
|
|
144 * Help with HTML Documentation::
|
|
145 * Help with Source::
|
|
146
|
|
147 Completion
|
|
148
|
|
149 * Case of Completed Words:: CaseOFcomPletedWords
|
|
150 * Object Method Completion and Class Ambiguity:: obj->Method, what?
|
|
151 * Object Method Completion in the Shell::
|
|
152 * Class and Keyword Inheritance:: obj->Method, _EXTRA=e
|
|
153 * Structure Tag Completion:: Completing state.Tag
|
|
154
|
|
155 Actions
|
|
156
|
|
157 * Block Boundary Check:: Is the END statement correct?
|
|
158 * Padding Operators:: Enforcing space around `=' etc
|
|
159 * Case Changes:: Enforcing upper case keywords
|
|
160
|
|
161 The IDLWAVE Shell
|
|
162
|
|
163 * Starting the Shell:: How to launch IDL as a subprocess
|
|
164 * Using the Shell:: Interactively working with the Shell
|
|
165 * Commands Sent to the Shell::
|
|
166 * Debugging IDL Programs::
|
|
167 * Examining Variables::
|
|
168 * Custom Expression Examination::
|
|
169
|
|
170 Debugging IDL Programs
|
|
171
|
|
172 * A Tale of Two Modes::
|
|
173 * Debug Key Bindings::
|
|
174 * Breakpoints and Stepping::
|
|
175 * Compiling Programs::
|
|
176 * Walking the Calling Stack::
|
|
177 * Electric Debug Mode::
|
|
178
|
|
179 Sources of Routine Info
|
|
180
|
|
181 * Routine Definitions:: Where IDL Routines are defined.
|
|
182 * Routine Information Sources:: So how does IDLWAVE know about...
|
|
183 * Catalogs::
|
|
184 * Load-Path Shadows:: Routines defined in several places
|
|
185 * Documentation Scan:: Scanning the IDL Manuals
|
|
186
|
|
187 Catalogs
|
|
188
|
|
189 * Library Catalogs::
|
|
190 * User Catalog::
|
|
191
|
|
192 @end detailmenu
|
|
193 @end menu
|
|
194
|
|
195 @node Introduction, IDLWAVE in a Nutshell, Top, Top
|
|
196 @chapter Introduction
|
|
197 @cindex Introduction
|
|
198 @cindex CORBA (Common Object Request Broker Architecture)
|
|
199 @cindex Interface Definition Language
|
|
200 @cindex Interactive Data Language
|
|
201 @cindex cc-mode.el
|
|
202 @cindex @file{idl.el}
|
|
203 @cindex @file{idl-shell.el}
|
|
204 @cindex Feature overview
|
|
205
|
|
206 IDLWAVE is a package which supports editing source files written in
|
|
207 the Interactive Data Language (IDL), and running IDL as an inferior shell@footnote{IDLWAVE can also be used
|
|
208 for editing source files for the related WAVE/CL language, but with only
|
|
209 limited support.}. It is a feature-rich replacement for the IDLDE
|
|
210 development environment included with IDL, and uses the full power of
|
|
211 Emacs to make editing and running IDL programs easier, quicker, and more
|
|
212 structured.
|
|
213
|
|
214 IDLWAVE consists of two main parts: a major mode for editing IDL
|
|
215 source files (@code{idlwave-mode}) and a mode for running the IDL
|
|
216 program as an inferior shell (@code{idlwave-shell-mode}). Although
|
|
217 one mode can be used without the other, both work together closely to
|
|
218 form a complete development environment. Here is a brief summary of
|
|
219 what IDLWAVE does:
|
|
220
|
|
221 @itemize @bullet
|
|
222 @item
|
|
223 Smart code indentation and automatic-formatting.
|
|
224 @item
|
|
225 Three level syntax highlighting support.
|
|
226 @item
|
|
227 Context-sensitive display of calling sequences and keywords for more
|
|
228 than 1000 native IDL routines, extendible to any additional number of
|
|
229 local routines, and already available with many pre-scanned libraries.
|
|
230 @item
|
|
231 Fast, context-sensitive online HTML help, or source-header help for
|
|
232 undocumented routines.
|
|
233 @item
|
|
234 Context sensitive completion of routine names, keywords, system
|
|
235 variables, class names and much more.
|
|
236 @item
|
|
237 Easy insertion of code templates and abbreviations of common constructs.
|
|
238 @item
|
|
239 Automatic corrections to enforce a variety of customizable coding
|
|
240 standards.
|
|
241 @item
|
|
242 Integrity checks and auto-termination of logical blocks.
|
|
243 @item
|
|
244 Routine name space conflict search with likelihood-of-use ranking.
|
|
245 @item
|
|
246 Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs).
|
|
247 @item
|
|
248 Documentation support.
|
|
249 @item
|
|
250 Running IDL as an inferior Shell with history search, command line
|
|
251 editing and all the completion and routine info capabilities present in
|
|
252 IDL source buffers.
|
|
253 @item
|
|
254 Full handling of debugging with breakpoints, with interactive setting
|
|
255 of break conditions, and easy stepping through code.
|
|
256 @item
|
|
257 Compilation, execution and interactive single-keystroke debugging of
|
|
258 programs directly from the source buffer.
|
|
259 @item
|
|
260 Quick, source-guided navigation of the calling stack, with variable
|
|
261 inspection, etc.
|
|
262 @item
|
|
263 Examining variables and expressions with a mouse click.
|
|
264 @item
|
|
265 And much, much more...
|
|
266 @end itemize
|
|
267
|
|
268 @ifnottex
|
|
269 @cindex Screenshots
|
|
270 Here are a number of screenshots showing IDLWAVE in action:
|
|
271
|
|
272 @itemize @bullet
|
|
273 @item
|
|
274 @uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer}
|
|
275 @item
|
|
276 @uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed}
|
|
277 @item
|
|
278 @uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.}
|
|
279 @item
|
|
280 @uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed}
|
|
281 @item
|
|
282 @uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code
|
|
283 stopped at a breakpoint}
|
|
284 @end itemize
|
|
285 @end ifnottex
|
|
286
|
|
287 IDLWAVE is the distant successor to the @file{idl.el} and
|
|
288 @file{idl-shell.el} files written by Chris Chase. The modes and files
|
|
289 had to be renamed because of a name space conflict with CORBA's
|
|
290 @code{idl-mode}, defined in Emacs in the file @file{cc-mode.el}.
|
|
291
|
|
292 In this manual, each section ends with a list of related user options.
|
|
293 Don't be confused by the sheer number of options available --- in most
|
|
294 cases the default settings are just fine. The variables are listed here
|
|
295 to make sure you know where to look if you want to change anything. For
|
|
296 a full description of what a particular variable does and how to
|
|
297 configure it, see the documentation string of that variable (available
|
|
298 with @kbd{C-h v}). Some configuration examples are also given in the
|
|
299 appendix.
|
|
300
|
|
301 @node IDLWAVE in a Nutshell, Getting Started, Introduction, Top
|
|
302 @chapter IDLWAVE in a Nutshell
|
|
303 @cindex Summary of important commands
|
|
304 @cindex IDLWAVE in a Nutshell
|
|
305 @cindex Nutshell, IDLWAVE in a
|
|
306
|
|
307 @subheading Editing IDL Programs
|
|
308
|
|
309 @multitable @columnfractions .15 .85
|
|
310 @item @key{TAB}
|
|
311 @tab Indent the current line relative to context.
|
|
312 @item @kbd{C-M-\}
|
|
313 @tab Re-indent all lines in the current region.
|
|
314 @item @kbd{C-M-q}
|
|
315 @tab Re-indent all lines in the current routine.
|
|
316 @item @kbd{C-u @key{TAB}}
|
|
317 @tab Re-indent all lines in the current statement.
|
|
318 @item @kbd{M-@key{RET}}
|
|
319 @tab Start a continuation line, splitting the current line at point.
|
|
320 @item @kbd{M-;}
|
|
321 @tab Start new comment at line beginning or after code, or (un)comment
|
|
322 highlighted region.
|
|
323 @item @kbd{M-q}
|
|
324 @tab Fill the current comment paragraph.
|
|
325 @item @kbd{C-c ?}
|
|
326 @tab Display calling sequence and keywords for the procedure or function call
|
|
327 at point.
|
|
328 @item @kbd{M-?}
|
|
329 @tab Load context sensitive online help for nearby routine, keyword, etc.
|
|
330 @item @kbd{M-@key{TAB}}
|
|
331 @tab Complete a procedure name, function name or keyword in the buffer.
|
|
332 @item @kbd{C-c C-i}
|
|
333 @tab Update IDLWAVE's knowledge about functions and procedures.
|
|
334 @item @kbd{C-c C-v}
|
|
335 @tab Visit the source code of a procedure/function.
|
|
336 @item @kbd{C-u C-c C-v}
|
|
337 @tab Visit the source code of a procedure/function in this buffer.
|
|
338 @item @kbd{C-c C-h}
|
|
339 @tab Insert a standard documentation header.
|
|
340 @item @kbd{C-c @key{RET}}
|
|
341 @tab Insert a new timestamp and history item in the documentation header.
|
|
342 @end multitable
|
|
343
|
|
344 @subheading Running the IDLWAVE Shell, Debugging Programs
|
|
345
|
|
346 @multitable @columnfractions .15 .85
|
|
347 @item @kbd{C-c C-s}
|
|
348 @tab Start IDL as a subprocess and/or switch to the shell buffer.
|
|
349 @item @key{Up}, @kbd{M-p}
|
|
350 @tab Cycle back through IDL command history.
|
|
351 @item @key{Down},@kbd{M-n}
|
|
352 @tab Cycle forward.
|
|
353 @item @kbd{@key{TAB}}
|
|
354 @tab Complete a procedure name, function name or keyword in the shell buffer.
|
|
355 @item @kbd{C-c C-d C-c}
|
|
356 @tab Save and compile the source file in the current buffer.
|
|
357 @item @kbd{C-c C-d C-e}
|
|
358 @tab Compile and run the current region.
|
|
359 @item @kbd{C-c C-d C-x}
|
|
360 @tab Go to next syntax error.
|
|
361 @item @kbd{C-c C-d C-v}
|
|
362 @tab Switch to electric debug mode.
|
|
363 @item @kbd{C-c C-d C-b}
|
|
364 @tab Set a breakpoint at the nearest viable source line.
|
|
365 @item @kbd{C-c C-d C-d}
|
|
366 @tab Clear the nearest breakpoint.
|
|
367 @item @kbd{C-c C-d [}
|
|
368 @tab Go to the previous breakpoint.
|
|
369 @item @kbd{C-c C-d ]}
|
|
370 @tab Go to the next breakpoint.
|
|
371 @item @kbd{C-c C-d C-p}
|
|
372 @tab Print the value of the expression near point in IDL.
|
|
373 @end multitable
|
|
374
|
|
375 @subheading Commonly used Settings in @file{.emacs}
|
|
376 @lisp
|
|
377 ;; Change the indentation preferences
|
|
378 ;; Start autoloading routine info after 2 idle seconds
|
|
379 (setq idlwave-init-rinfo-when-idle-after 2)
|
|
380 ;; Pad operators with spaces
|
|
381 (setq idlwave-do-actions t
|
|
382 idlwave-surround-by-blank t)
|
|
383 ;; Syntax Highlighting
|
|
384 (add-hook 'idlwave-mode-hook 'turn-on-font-lock)
|
|
385 ;; Automatically start the shell when needed
|
|
386 (setq idlwave-shell-automatic-start t)
|
|
387 ;; Bind debugging commands with CONTROL and SHIFT modifiers
|
|
388 (setq idlwave-shell-debug-modifiers '(control shift))
|
|
389 @end lisp
|
|
390
|
|
391 @html
|
|
392 <A NAME="TUTORIAL"></A>
|
|
393 @end html
|
|
394
|
|
395 @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top
|
|
396 @chapter Getting Started (Tutorial)
|
|
397 @cindex Quick-Start
|
|
398 @cindex Tutorial
|
|
399 @cindex Getting Started
|
|
400
|
|
401 @menu
|
|
402 * Lesson I -- Development Cycle::
|
|
403 * Lesson II -- Customization::
|
|
404 * Lesson III -- User Catalog::
|
|
405 @end menu
|
|
406
|
|
407 @node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started
|
|
408 @section Lesson I: Development Cycle
|
|
409
|
|
410 The purpose of this tutorial is to guide you through a very basic
|
|
411 development cycle using IDLWAVE. We will paste a simple program into
|
|
412 a buffer and use the shell to compile, debug and run it. On the way
|
|
413 we will use many of the important IDLWAVE commands. Note, however,
|
|
414 that IDLWAVE has many more capabilities than covered here, which can
|
|
415 be discovered by reading the entire manual, or hovering over the
|
|
416 shoulder of your nearest IDLWAVE guru for a few days.
|
|
417
|
|
418 It is assumed that you have access to Emacs or XEmacs with the full
|
|
419 IDLWAVE package including online help. We also assume that you are
|
|
420 familiar with Emacs and can read the nomenclature of key presses in
|
|
421 Emacs (in particular, @kbd{C} stands for @key{CONTROL} and @kbd{M} for
|
|
422 @key{META} (often the @key{ALT} key carries this functionality)).
|
|
423
|
|
424 Open a new source file by typing:
|
|
425
|
|
426 @example
|
|
427 @kbd{C-x C-f tutorial.pro @key{RET}}
|
|
428 @end example
|
|
429
|
|
430 A buffer for this file will pop up, and it should be in IDLWAVE mode,
|
|
431 indicated in the mode line just below the editing window. Also, the
|
|
432 menu bar should contain @samp{IDLWAVE}.
|
|
433
|
|
434 Now cut-and-paste the following code, also available as
|
|
435 @file{tutorial.pro} in the IDLWAVE distribution.
|
|
436
|
|
437 @example
|
|
438 function daynr,d,m,y
|
|
439 ;; compute a sequence number for a date
|
|
440 ;; works 1901-2099.
|
|
441 if y lt 100 then y = y+1900
|
|
442 if m le 2 then delta = 1 else delta = 0
|
|
443 m1 = m + delta*12 + 1
|
|
444 y1 = y * delta
|
|
445 return, d + floor(m1*30.6)+floor(y1*365.25)+5
|
|
446 end
|
|
447
|
|
448 function weekday,day,month,year
|
|
449 ;; compute weekday number for date
|
|
450 nr = daynr(day,month,year)
|
|
451 return, nr mod 7
|
|
452 end
|
|
453
|
|
454 pro plot_wday,day,month
|
|
455 ;; Plot the weekday of a date in the first 10 years of this century.
|
|
456 years = 2000,+indgen(10)
|
|
457 wdays = intarr(10)
|
|
458 for i=0,n_elements(wdays)-1 do begin
|
|
459 wdays[i] = weekday(day,month,years[i])
|
|
460 end
|
|
461 plot,years,wdays,YS=2,YT="Wday (0=Sunday)"
|
|
462 end
|
|
463 @end example
|
|
464
|
|
465 The indentation probably looks funny, since it's different from the
|
|
466 settings you use, so use the @key{TAB} key in each line to
|
|
467 automatically line it up (or, more quickly, @emph{select} the entire
|
|
468 buffer with @kbd{C-x h}, and indent the whole region with
|
|
469 @kbd{C-M-\}). Notice how different syntactical elements are
|
|
470 highlighted in different colors, if you have set up support for
|
|
471 font-lock.
|
|
472
|
|
473 Let's check out two particular editing features of IDLWAVE. Place the
|
|
474 cursor after the @code{end} statement of the @code{for} loop and press
|
|
475 @key{SPC}. IDLWAVE blinks back to the beginning of the block and
|
|
476 changes the generic @code{end} to the specific @code{endfor}
|
|
477 automatically (as long as the variable @code{idlwave-expand-generic-end}
|
|
478 is turned on --- @pxref{Lesson II -- Customization}). Now place the
|
|
479 cursor in any line you would like to split and press @kbd{M-@key{RET}}.
|
|
480 The line is split at the cursor position, with the continuation @samp{$}
|
|
481 and indentation all taken care of. Use @kbd{C-/} to undo the last
|
|
482 change.
|
|
483
|
|
484 The procedure @code{plot_wday} is supposed to plot the day of the week
|
|
485 of a given date for the first 10 years of the 21st century. As in
|
|
486 most code, there are a few bugs, which we are going to use IDLWAVE to
|
|
487 help us fix.
|
|
488
|
|
489 First, let's launch the IDLWAVE shell. You do this with the command
|
|
490 @kbd{C-c C-s}. The Emacs window will split or another window will popup
|
|
491 to display IDL running in a shell interaction buffer. Type a few
|
|
492 commands like @code{print,!PI} to convince yourself that you can work
|
|
493 there just as well as in a terminal, or the IDLDE. Use the arrow keys
|
|
494 to cycle through your command history. Are we having fun now?
|
|
495
|
|
496 Now go back to the source window and type @kbd{C-c C-d C-c} to compile
|
|
497 the program. If you watch the shell buffer, you see that IDLWAVE types
|
|
498 @samp{.run "tutorial.pro"} for you. But the compilation fails because
|
|
499 there is a comma in the line @samp{years=...}. The line with the error
|
|
500 is highlighted and the cursor positioned at the error, so remove the
|
|
501 comma (you should only need to hit @kbd{Delete}!). Compile again, using
|
|
502 the same keystrokes as before. Notice that the file is automatically
|
|
503 saved for you. This time everything should work fine, and you should
|
|
504 see the three routines compile.
|
|
505
|
|
506 Now we want to use the command to plot the day of the week on January
|
|
507 1st. We could type the full command ourselves, but why do that? Go
|
|
508 back to the shell window, type @samp{plot_} and hit @key{TAB}. After
|
|
509 a bit of a delay (while IDLWAVE initializes its routine info database,
|
|
510 if necessary), the window will split to show all procedures it knows
|
|
511 starting with that string, and @w{@code{plot_wday}} should be one of
|
|
512 them. Saving the buffer alerted IDLWAVE about this new routine.
|
|
513 Click with the middle mouse button on @code{plot_wday} and it will be
|
|
514 copied to the shell buffer, or if you prefer, add @samp{w} to
|
|
515 @samp{plot_} to make it unambiguous (depending on what other routines
|
|
516 starting with @samp{plot_} you have installed on your system), hit
|
|
517 @key{TAB} again, and the full routine name will be completed. Now
|
|
518 provide the two arguments:
|
|
519
|
|
520 @example
|
|
521 plot_wday,1,1
|
|
522 @end example
|
|
523
|
|
524 @noindent and press @key{RET}. This fails with an error message telling
|
|
525 you the @code{YT} keyword to plot is ambiguous. What are the allowed
|
|
526 keywords again? Go back to the source window and put the cursor into
|
|
527 the `plot' line and press @kbd{C-c ?}. This shows the routine info
|
|
528 window for the plot routine, which contains a list of keywords, along
|
|
529 with the argument list. Oh, we wanted @code{YTITLE}. Fix that up.
|
|
530 Recompile with @kbd{C-c C-d C-c}. Jump back into the shell with
|
|
531 @kbd{C-c C-s}, press the @key{UP} arrow to recall the previous command
|
|
532 and execute again.
|
|
533
|
|
534 This time we get a plot, but it is pretty ugly --- the points are all
|
|
535 connected with a line. Hmm, isn't there a way for @code{plot} to use
|
|
536 symbols instead? What was that keyword? Position the cursor on the
|
|
537 plot line after a comma (where you'd normally type a keyword), and hit
|
|
538 @kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha,
|
|
539 there it is, @code{PSYM}. Middle click to insert it. An @samp{=}
|
|
540 sign is included for you too. Now what were the values of @code{PSYM}
|
|
541 supposed to be? With the cursor on or after the keyword, press
|
|
542 @kbd{M-?} for online help (alternatively, you could have right clicked
|
|
543 on the colored keyword itself in the completion list). A browser will
|
|
544 pop up showing the HTML documentation for the @code{PYSM} keyword.
|
|
545 OK, let's use diamonds=4. Fix this, recompile (you know the command
|
|
546 by now: @kbd{C-c C-d C-c}), go back to the shell (if it's vanished,
|
|
547 you know what to do: @kbd{C-c C-s}) and execute again. Now things
|
|
548 look pretty good.
|
|
549
|
|
550 Let's try a different day --- how about April fool's day?
|
|
551
|
|
552 @example
|
|
553 plot_wday,1,4
|
|
554 @end example
|
|
555
|
|
556 Oops, this looks very wrong. All April Fool's days cannot be Fridays!
|
|
557 We've got a bug in the program, perhaps in the @code{daynr} function.
|
|
558 Let's put a breakpoint on the last line there. Position the cursor on
|
|
559 the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a
|
|
560 breakpoint (as you see in the shell window), and the break line is
|
|
561 indicated. Back to the shell buffer, re-execute the previous command.
|
|
562 IDL stops at the line with the breakpoint. Now hold down the SHIFT
|
|
563 key and click with the middle mouse button on a few variables there:
|
|
564 @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't
|
|
565 the correct type. CONTROL-SHIFT middle-click on it for help. Well,
|
|
566 it's an integer, so that's not the problem. Aha, @samp{y1} is zero,
|
|
567 but it should be the year, depending on delta. Shift click
|
|
568 @samp{delta} to see that it's 0. Below, we see the offending line:
|
|
569 @samp{y1=y*delta...} the multiplication should have been a minus sign!
|
|
570 Hit @kbd{q} to exit the debugging mode, and fix the line to read:
|
|
571
|
|
572 @example
|
|
573 y1 = y - delta
|
|
574 @end example
|
|
575
|
|
576 Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the
|
|
577 command. Everything should now work fine. How about those leap years?
|
|
578 Change the code to plot 100 years and see that every 28 years, the
|
|
579 sequence of weekdays repeats.
|
|
580
|
|
581 @node Lesson II -- Customization, Lesson III -- User Catalog, Lesson I -- Development Cycle, Getting Started
|
|
582 @section Lesson II: Customization
|
|
583
|
|
584 Emacs is probably the most customizable piece of software ever written,
|
|
585 and it would be a shame if you did not make use of this to adapt IDLWAVE
|
|
586 to your own preferences. Customizing Emacs or IDLWAVE is accomplished
|
|
587 by setting Lisp variables in the @file{.emacs} file in your home
|
|
588 directory --- but do not be dismayed; for the most part, you can just
|
|
589 copy and work from the examples given here.
|
|
590
|
|
591 Let's first use a boolean variable. These are variables which you turn
|
|
592 on or off, much like a checkbox. A value of @samp{t} means on, a value
|
|
593 of @samp{nil} means off. Copy the following line into your
|
|
594 @file{.emacs} file, exit and restart Emacs.
|
|
595
|
|
596 @lisp
|
|
597 (setq idlwave-reserved-word-upcase t)
|
|
598 @end lisp
|
|
599
|
|
600 When this option is turned on, each reserved word you type into an IDL
|
|
601 source buffer will be converted to upper case when you press @key{SPC}
|
|
602 or @key{RET} right after the word. Try it out! @samp{if} changes to
|
|
603 @samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this
|
|
604 behavior, remove the option again from your @file{.emacs} file and
|
|
605 restart Emacs.
|
|
606
|
|
607 You likely have your own indentation preferences for IDL code. For
|
|
608 example, some may prefer to indent the main block of an IDL program
|
|
609 slightly from the margin and use only 3 spaces as indentation between
|
|
610 @code{BEGIN} and @code{END}. Try the following lines in @file{.emacs}:
|
|
611
|
|
612 @lisp
|
|
613 (setq idlwave-main-block-indent 1)
|
|
614 (setq idlwave-block-indent 3)
|
|
615 (setq idlwave-end-offset -3)
|
|
616 @end lisp
|
|
617
|
|
618 Restart Emacs, and re-indent the program we developed in the first part
|
|
619 of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may want to keep
|
|
620 these lines in @file{.emacs}, with values adjusted to your likings. If
|
|
621 you want to get more information about any of these variables, type,
|
|
622 e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. To find which
|
|
623 variables can be customized, look for items marked @samp{User Option:}
|
|
624 throughout this manual.
|
|
625
|
|
626 If you cannot seem to master this Lisp customization in @file{.emacs},
|
|
627 there is another, more user-friendly way to customize all the IDLWAVE
|
|
628 variables. You can access it through the IDLWAVE menu in one of the
|
|
629 @file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE
|
|
630 Group}. Here you'll be presented with all the various variables grouped
|
|
631 into categories. You can navigate the hierarchy (e.g. @samp{IDLWAVE
|
|
632 Code Formatting->Idlwave Abbrev And Indent Action->Idlwave Expand
|
|
633 Generic End} to turn on @code{END} expansion), read about the variables,
|
|
634 change them, and `Save for Future Sessions'. Few of these variables
|
|
635 need customization, but you can exercise considerable control over
|
|
636 IDLWAVE's functionality with them.
|
|
637
|
|
638 You may also find the key bindings used for the debugging commands too
|
|
639 long and complicated. Often we have heard complaints along the lines
|
|
640 of, ``Do I really have to go through the finger gymnastics of @kbd{C-c
|
|
641 C-d C-c} to run a simple command?'' Due to Emacs rules and
|
|
642 conventions, shorter bindings cannot be set by default, but you can
|
|
643 easily enable them. First, there is a way to assign all debugging
|
|
644 commands in a single sweep to another simpler combination. The only
|
|
645 problem is that we have to use something which Emacs does not need for
|
|
646 other important commands. One good option is to execute debugging
|
|
647 commands by holding down @key{CONTROL} and @key{SHIFT} while pressing
|
|
648 a single character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c}
|
|
649 for compiling the current source file, @kbd{C-S-a} for deleting all
|
|
650 breakpoints (try it, it's easier). You can enable this with:
|
|
651
|
|
652 @lisp
|
|
653 (setq idlwave-shell-debug-modifiers '(shift control))
|
|
654 @end lisp
|
|
655
|
|
656 @noindent If you have a special keyboard with, for example, a
|
|
657 @key{SUPER} key, you could even shorten that:
|
|
658
|
|
659 @lisp
|
|
660 (setq idlwave-shell-debug-modifiers '(super))
|
|
661 @end lisp
|
|
662
|
|
663 @noindent to get compilation on @kbd{S-c}. Often, a modifier key like
|
|
664 @key{SUPER} or @key{HYPER} is bound or can be bound to an otherwise
|
|
665 unused key on your keyboard --- consult your system documentation.
|
|
666
|
|
667 You can also assign specific commands to keys. This you must do in the
|
|
668 @emph{mode-hook}, a special function which is run when a new IDLWAVE
|
|
669 buffer gets set up. The possibilities for key customization are
|
|
670 endless. Here we set function keys f4-f8 to common debugging commands.
|
|
671
|
|
672 @lisp
|
|
673 ;; First for the source buffer
|
|
674 (add-hook 'idlwave-mode-hook
|
|
675 (lambda ()
|
|
676 (local-set-key [f4] 'idlwave-shell-retall)
|
|
677 (local-set-key [f5] 'idlwave-shell-break-here)
|
|
678 (local-set-key [f6] 'idlwave-shell-clear-current-bp)
|
|
679 (local-set-key [f7] 'idlwave-shell-cont)
|
|
680 (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
|
|
681 ;; Then for the shell buffer
|
|
682 (add-hook 'idlwave-shell-mode-hook
|
|
683 (lambda ()
|
|
684 (local-set-key [f4] 'idlwave-shell-retall)
|
|
685 (local-set-key [f5] 'idlwave-shell-break-here)
|
|
686 (local-set-key [f6] 'idlwave-shell-clear-current-bp)
|
|
687 (local-set-key [f7] 'idlwave-shell-cont)
|
|
688 (local-set-key [f8] 'idlwave-shell-clear-all-bp)))
|
|
689 @end lisp
|
|
690
|
|
691 @node Lesson III -- User Catalog, , Lesson II -- Customization, Getting Started
|
|
692 @section Lesson III: User and Library Catalogs
|
|
693
|
|
694 We have already used the routine info display in the first part of this
|
|
695 tutorial. This was the invoked using @kbd{C-c ?}, and displays
|
|
696 information about the IDL routine near the cursor position. Wouldn't it
|
|
697 be nice to have the same kind of information available for your own
|
|
698 routines and for the huge amount of code in major libraries like JHUPL
|
|
699 or the IDL-Astro library? In many cases, you may already have this
|
|
700 information. Files named @file{.idlwave_catalog} in library directories
|
|
701 contain scanned information on the routines in that directory; many
|
|
702 popular libraries ship with these ``library catalogs'' pre-scanned.
|
|
703 Users can scan their own routines in one of two ways: either using the
|
|
704 supplied tool to scan directories and build their own
|
|
705 @file{.idlwave_catalog} files, or using the built-in method to create a
|
|
706 single ``user catalog'', which we'll show here. @xref{Catalogs}, for
|
|
707 more information on choosing which method to use.
|
|
708
|
|
709 To build a user catalog, select @code{Routine Info/Select Catalog
|
|
710 Directories} from the IDLWAVE entry in the menu bar. If necessary,
|
|
711 start the shell first with @kbd{C-c C-s} (@pxref{Starting the Shell}).
|
|
712 IDLWAVE will find out about the IDL @code{!PATH} variable and offer a
|
|
713 list of directories on the path. Simply select them all (or whichever
|
|
714 you want --- directories with existing library catalogs will not be
|
|
715 selected by default) and click on the @samp{Scan&Save} button. Then
|
|
716 go for a cup of coffee while IDLWAVE collects information for each and
|
|
717 every IDL routine on your search path. All this information is
|
|
718 written to the file @file{.idlwave/idlusercat.el} in your home
|
|
719 directory and will from now on automatically load whenever you use
|
|
720 IDLWAVE. You may find it necessary to rebuild the catalog on occasion
|
|
721 as your local libraries change, or build a library catalog for those
|
|
722 directories instead. Invoke routine info (@kbd{C-c ?}) or completion
|
|
723 (@kbd{M-@key{TAB}}) on any routine or partial routine name you know to
|
|
724 be located in the library. E.g., if you have scanned the IDL-Astro
|
|
725 library:
|
|
726
|
|
727 @example
|
|
728 a=readf@key{M-@key{TAB}}
|
|
729 @end example
|
|
730
|
|
731 expands to `readfits('. Then try
|
|
732
|
|
733 @example
|
|
734 a=readfits(@key{C-c ?}
|
|
735 @end example
|
|
736
|
|
737 and you get:
|
|
738
|
|
739 @example
|
|
740 Usage: Result = READFITS(filename, header, heap)
|
|
741 ...
|
|
742 @end example
|
|
743
|
|
744 I hope you made it until here. Now you are set to work with IDLWAVE.
|
|
745 On the way you will want to change other things, and to learn more
|
|
746 about the possibilities not discussed in this short tutorial. Read
|
|
747 the manual, look at the documentation strings of interesting variables
|
|
748 (with @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the
|
|
749 remaining questions on the newsgroup @code{comp.lang.idl-pvwave}.
|
|
750
|
|
751 @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top
|
|
752 @chapter The IDLWAVE Major Mode
|
|
753 @cindex IDLWAVE major mode
|
|
754 @cindex Major mode, @code{idlwave-mode}
|
|
755
|
|
756 The IDLWAVE major mode supports editing IDL source files. In this
|
|
757 chapter we describe the main features of the mode and how to customize
|
|
758 them.
|
|
759
|
|
760 @menu
|
|
761 * Code Formatting:: Making code look nice
|
|
762 * Routine Info:: Calling Sequence and Keyword List
|
|
763 * Online Help:: One key press from source to help
|
|
764 * Completion:: Completing routine names and Keywords
|
|
765 * Routine Source:: Finding routines, the easy way
|
|
766 * Resolving Routines:: Force the Shell to compile a routine
|
|
767 * Code Templates:: Frequent code constructs
|
|
768 * Abbreviations:: Abbreviations for common commands
|
|
769 * Actions:: Changing case, Padding, End checking
|
|
770 * Doc Header:: Inserting a standard header
|
|
771 * Motion Commands:: Moving through the structure of a program
|
|
772 * Misc Options:: Things that fit nowhere else
|
|
773 @end menu
|
|
774
|
|
775 @node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode
|
|
776 @section Code Formatting
|
|
777 @cindex Code formatting
|
|
778 @cindex Formatting, of code
|
|
779
|
|
780 @menu
|
|
781 * Code Indentation:: Reflecting the logical structure
|
|
782 * Continued Statement Indentation::
|
|
783 * Comment Indentation:: Special indentation for comment lines
|
|
784 * Continuation Lines:: Splitting statements over lines
|
|
785 * Syntax Highlighting:: Font-lock support
|
|
786 * Octals and Highlighting:: Why "123 causes problems
|
|
787 @end menu
|
|
788
|
|
789 The IDL language, with its early roots in FORTRAN, modern
|
|
790 implementation in C, and liberal borrowing of features of many vector
|
|
791 and other languages along its 25+ year history, has inherited an
|
|
792 unusual mix of syntax elements. Left to his or her own devices, a
|
|
793 novice IDL programmer will often conjure code which is very difficult
|
|
794 to read and impossible to adapt. Much can be gleaned from studying
|
|
795 available IDL code libraries for coding style pointers, but, due to
|
|
796 the variety of IDL syntax elements, replicating this style can be
|
|
797 challenging at best. Luckily, IDLWAVE understands the structure of
|
|
798 IDL code very well, and takes care of almost all formatting issues for
|
|
799 you. After configuring it to match your coding standards, you can
|
|
800 rely on it to help keep your code neat and organized.
|
|
801
|
|
802
|
|
803 @node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting
|
|
804 @subsection Code Indentation
|
|
805 @cindex Code indentation
|
|
806 @cindex Indentation
|
|
807
|
|
808 Like all Emacs programming modes, IDLWAVE performs code indentation.
|
|
809 The @key{TAB} key indents the current line relative to context.
|
|
810 @key{LFD} insert a newline and indents the new line. The indentation is
|
|
811 governed by a number of variables. IDLWAVE indents blocks (between
|
|
812 @code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and
|
|
813 continuation lines.
|
|
814
|
|
815 @cindex Foreign code, adapting
|
|
816 @cindex Indentation, of foreign code
|
|
817 @kindex C-M-\
|
|
818 To re-indent a larger portion of code (e.g. when working with foreign
|
|
819 code written with different conventions), use @kbd{C-M-\}
|
|
820 (@code{indent-region}) after marking the relevant code. Useful marking
|
|
821 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current
|
|
822 subprogram). The command @kbd{C-M-q} reindents the entire current
|
|
823 routine. @xref{Actions}, for information how to impose additional
|
|
824 formatting conventions on foreign code.
|
|
825
|
|
826 @defopt idlwave-main-block-indent (@code{2})
|
|
827 Extra indentation for the main block of code. That is the block between
|
|
828 the FUNCTION/PRO statement and the END statement for that program
|
|
829 unit.
|
|
830 @end defopt
|
|
831
|
|
832 @defopt idlwave-block-indent (@code{3})
|
|
833 Extra indentation applied to block lines. If you change this, you
|
|
834 probably also want to change @code{idlwave-end-offset}.
|
|
835 @end defopt
|
|
836
|
|
837 @defopt idlwave-end-offset (@code{-3})
|
|
838 Extra indentation applied to block END lines. A value equal to negative
|
|
839 @code{idlwave-block-indent} will make END lines line up with the block
|
|
840 BEGIN lines.
|
|
841 @end defopt
|
|
842
|
|
843 @node Continued Statement Indentation, Comment Indentation, Code Indentation, Code Formatting
|
|
844 @subsection Continued Statement Indentation
|
|
845 @cindex Indentation, continued statement
|
|
846 @cindex Continued statement indentation
|
|
847 Continuation lines (following a line ending with @code{$}) can receive a
|
|
848 fixed indentation offset from the main level, but in several situations
|
|
849 IDLWAVE can use a special form of indentation which aligns continued
|
|
850 statements more naturally. Special indentation is calculated for
|
|
851 continued routine definition statements and calls, enclosing parentheses
|
|
852 (like function calls, structure/class definitions, explicit structures
|
|
853 or lists, etc.), and continued assignments. An attempt is made to line
|
|
854 up with the first non-whitespace character after the relevant opening
|
|
855 punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}). For
|
|
856 lines without any non-comment characters on the line with the opening
|
|
857 punctuation, the continued line(s) are aligned just past the
|
|
858 punctuation. An example:
|
|
859
|
|
860 @example
|
|
861 function foo, a, b, $
|
|
862 c, d
|
|
863 bar = sin( a + b + $
|
|
864 c + d)
|
|
865 end
|
|
866 @end example
|
|
867 @noindent
|
|
868
|
|
869 The only drawback to this special continued statement indentation is
|
|
870 that it consumes more space, e.g., for long function names or left hand
|
|
871 sides of an assignment:
|
|
872
|
|
873 @example
|
|
874 function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $
|
|
875 c, d
|
|
876 @end example
|
|
877
|
|
878 You can instruct IDLWAVE when to avoid using this special continuation
|
|
879 indentation by setting the variable
|
|
880 @code{idlwave-max-extra-continuation-indent}, which specifies the
|
|
881 maximum additional indentation beyond the basic indent to be
|
|
882 tolerated, otherwise defaulting to a fixed-offset from the enclosing
|
|
883 indent (the size of which offset is set in
|
|
884 @code{idlwave-continuation-indent}). As a special case, continuations
|
|
885 of routine calls without any arguments or keywords will @emph{not}
|
|
886 align the continued line, under the assumption that you continued
|
|
887 because you needed the space.
|
|
888
|
|
889 Also, since the indentation level can be somewhat dynamic in continued
|
|
890 statements with special continuation indentation, especially if
|
|
891 @code{idlwave-max-extra-continuation-indent} is small, the key
|
|
892 @kbd{C-u @key{TAB}} will re-indent all lines in the current statement.
|
|
893 Note that @code{idlwave-indent-to-open-paren}, if non-@code{nil},
|
|
894 overrides the @code{idlwave-max-extra-continuation-indent} limit, for
|
|
895 parentheses only, forcing them always to line up.
|
|
896
|
|
897
|
|
898 @defopt idlwave-continuation-indent (@code{2})
|
|
899 Extra indentation applied to normal continuation lines.
|
|
900 @end defopt
|
|
901
|
|
902 @defopt idlwave-max-extra-continuation-indent (@code{20})
|
|
903 The maximum additional indentation (over the basic continuation-indent)
|
|
904 that will be permitted for special continues. To effectively disable
|
|
905 special continuation indentation, set to @code{0}. To enable it
|
|
906 constantly, set to a large number (like @code{100}). Note that the
|
|
907 indentation in a long continued statement never decreases from line to
|
|
908 line, outside of nested parentheses statements.
|
|
909 @end defopt
|
|
910
|
|
911 @defopt idlwave-indent-to-open-paren (@code{t})
|
|
912 Non-@code{nil} means indent continuation lines to innermost open
|
|
913 parenthesis, regardless of whether the
|
|
914 @code{idlwave-max-extra-continuation-indent} limit is satisfied.
|
|
915 @end defopt
|
|
916
|
|
917 @node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting
|
|
918 @subsection Comment Indentation
|
|
919 @cindex Comment indentation
|
|
920 @cindex Hanging paragraphs
|
|
921 @cindex Paragraphs, filling
|
|
922 @cindex Paragraphs, hanging
|
|
923
|
|
924 In IDL, lines starting with a @samp{;} are called @emph{comment lines}.
|
|
925 Comment lines are indented as follows:
|
|
926
|
|
927 @multitable @columnfractions .1 .90
|
|
928 @item @code{;;;}
|
|
929 @tab The indentation of lines starting with three semicolons remains
|
|
930 unchanged.
|
|
931 @item @code{;;}
|
|
932 @tab Lines starting with two semicolons are indented like the surrounding code.
|
|
933 @item @code{;}
|
|
934 @tab Lines starting with a single semicolon are indented to a minimum column.
|
|
935 @end multitable
|
|
936
|
|
937 @noindent
|
|
938 The indentation of comments starting in column 0 is never changed.
|
|
939
|
|
940 @defopt idlwave-no-change-comment
|
|
941 The indentation of a comment starting with this regexp will not be
|
|
942 changed.
|
|
943 @end defopt
|
|
944
|
|
945 @defopt idlwave-begin-line-comment
|
|
946 A comment anchored at the beginning of line.
|
|
947 @end defopt
|
|
948
|
|
949 @defopt idlwave-code-comment
|
|
950 A comment that starts with this regexp is indented as if it is a part of
|
|
951 IDL code.
|
|
952 @end defopt
|
|
953
|
|
954 @node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting
|
|
955 @subsection Continuation Lines and Filling
|
|
956 @cindex Continuation lines
|
|
957 @cindex Line splitting
|
|
958 @cindex String splitting
|
|
959 @cindex Splitting, of lines
|
|
960
|
|
961 @kindex M-@key{RET}
|
|
962 In IDL, a newline character terminates a statement unless preceded by a
|
|
963 @samp{$}. If you would like to start a continuation line, use
|
|
964 @kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}.
|
|
965 It inserts the continuation character @samp{$}, terminates the line and
|
|
966 indents the new line. The command @kbd{M-@key{RET}} can also be invoked
|
|
967 inside a string to split it at that point, in which case the @samp{+}
|
|
968 concatenation operator is used.
|
|
969
|
|
970 @cindex Filling
|
|
971 @cindex @code{auto-fill-mode}
|
|
972 @cindex Hanging paragraphs
|
|
973 When filling comment paragraphs, IDLWAVE overloads the normal filling
|
|
974 functions and uses a function which creates the hanging paragraphs
|
|
975 customary in IDL routine headers. When @code{auto-fill-mode} is turned
|
|
976 on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If the
|
|
977 first line of a paragraph contains a match for
|
|
978 @code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent
|
|
979 lines are positioned to line up after it, as in the following example.
|
|
980
|
|
981 @example
|
|
982 @group
|
|
983 ;=================================
|
|
984 ; x - an array containing
|
|
985 ; lots of interesting numbers.
|
|
986 ;
|
|
987 ; y - another variable where
|
|
988 ; a hanging paragraph is used
|
|
989 ; to describe it.
|
|
990 ;=================================
|
|
991 @end group
|
|
992 @end example
|
|
993
|
|
994 @kindex M-q
|
|
995 You can also refill a comment at any time paragraph with @kbd{M-q}.
|
|
996 Comment delimiting lines as in the above example, consisting of one or
|
|
997 more @samp{;} followed by one or more of the characters @samp{+=-_*},
|
|
998 are kept in place, as is.
|
|
999
|
|
1000 @defopt idlwave-fill-comment-line-only (@code{t})
|
|
1001 Non-@code{nil} means auto fill will only operate on comment lines.
|
|
1002 @end defopt
|
|
1003
|
|
1004 @defopt idlwave-auto-fill-split-string (@code{t})
|
|
1005 Non-@code{nil} means auto fill will split strings with the IDL @samp{+}
|
|
1006 operator.
|
|
1007 @end defopt
|
|
1008
|
|
1009 @defopt idlwave-split-line-string (@code{t})
|
|
1010 Non-@code{nil} means @code{idlwave-split-line} will split strings with
|
|
1011 @samp{+}.
|
|
1012 @end defopt
|
|
1013
|
|
1014 @defopt idlwave-hanging-indent (@code{t})
|
|
1015 Non-@code{nil} means comment paragraphs are indented under the hanging
|
|
1016 indent given by @code{idlwave-hang-indent-regexp} match in the first
|
|
1017 line of the paragraph.
|
|
1018 @end defopt
|
|
1019
|
|
1020 @defopt idlwave-hang-indent-regexp (@code{"- "})
|
|
1021 Regular expression matching the position of the hanging indent
|
|
1022 in the first line of a comment paragraph.
|
|
1023 @end defopt
|
|
1024
|
|
1025 @defopt idlwave-use-last-hang-indent (@code{nil})
|
|
1026 Non-@code{nil} means use last match on line for
|
|
1027 @code{idlwave-indent-regexp}.
|
|
1028 @end defopt
|
|
1029
|
|
1030 @node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting
|
|
1031 @subsection Syntax Highlighting
|
|
1032 @cindex Syntax highlighting
|
|
1033 @cindex Highlighting of syntax
|
|
1034 @cindex Font lock
|
|
1035
|
|
1036 Highlighting of keywords, comments, strings etc. can be accomplished
|
|
1037 with @code{font-lock}. If you are using @code{global-font-lock-mode}
|
|
1038 (in Emacs), or have @code{font-lock} turned on in any other buffer in
|
|
1039 XEmacs, it should also automatically work in IDLWAVE buffers. If you'd
|
|
1040 prefer invoking font-lock individually by mode, you can enforce it in
|
|
1041 @code{idlwave-mode} with the following line in your @file{.emacs}:
|
|
1042
|
|
1043 @lisp
|
|
1044 (add-hook 'idlwave-mode-hook 'turn-on-font-lock)
|
|
1045 @end lisp
|
|
1046
|
|
1047 @noindent IDLWAVE supports 3 increasing levels of syntax highlighting.
|
|
1048 The variable @code{font-lock-maximum-decoration} determines which level
|
|
1049 is selected. Individual categories of special tokens can be selected
|
|
1050 for highlighting using the variable
|
|
1051 @code{idlwave-default-font-lock-items}.
|
|
1052
|
|
1053 @defopt idlwave-default-font-lock-items
|
|
1054 Items which should be fontified on the default fontification level
|
|
1055 2.
|
|
1056 @end defopt
|
|
1057
|
|
1058 @node Octals and Highlighting, , Syntax Highlighting, Code Formatting
|
|
1059 @subsection Octals and Highlighting
|
|
1060 @cindex Syntax highlighting, Octals
|
|
1061 @cindex Highlighting of syntax, Octals
|
|
1062
|
|
1063 A rare syntax highlighting problem results from an extremely unfortunate
|
|
1064 notation for octal numbers in IDL: @code{"123}. This unpaired quotation
|
|
1065 mark is very difficult to parse, given that it can be mixed on a single
|
|
1066 line with any number of strings. Emacs will incorrectly identify this
|
|
1067 as a string, and the highlighting of following lines of code can be
|
|
1068 distorted, since the string is never terminated.
|
|
1069
|
|
1070 One solution to this involves terminating the mistakenly identified
|
|
1071 string yourself by providing a closing quotation mark in a comment:
|
|
1072
|
|
1073 @example
|
|
1074 string("305B) + $ ;" <--- for font-lock
|
|
1075 ' is an Angstrom.'
|
|
1076 @end example
|
|
1077
|
|
1078 @noindent A far better solution is to abandon this notation for octals
|
|
1079 altogether, and use the more sensible alternative IDL provides:
|
|
1080
|
|
1081 @example
|
|
1082 string('305'OB) + ' is an Angstrom.'
|
|
1083 @end example
|
|
1084
|
|
1085 @noindent This simultaneously solves the font-lock problem and is more
|
|
1086 consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}.
|
|
1087
|
|
1088 @node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode
|
|
1089 @section Routine Info
|
|
1090 @cindex Routine info
|
|
1091 @cindex Updating routine info
|
|
1092 @cindex Scanning buffers for routine info
|
|
1093 @cindex Buffers, scanning for routine info
|
|
1094 @cindex Shell, querying for routine info
|
|
1095
|
|
1096 @kindex C-c C-i
|
|
1097 IDL comes bundled with more than one thousand procedures, functions
|
|
1098 and object methods, and large libraries typically contain hundreds or
|
|
1099 even thousands more (each with a few to tens of keywords and
|
|
1100 arguments). This large command set can make it difficult to remember
|
|
1101 the calling sequence and keywords for the routines you use, but
|
|
1102 IDLWAVE can help. It builds up routine information from a wide
|
|
1103 variety of sources; IDLWAVE in fact knows far more about the
|
|
1104 @samp{.pro} routines on your system than IDL itself! It maintains a
|
|
1105 list of all built-in routines, with calling sequences and
|
|
1106 keywords@footnote{This list is created by scanning the IDL manuals and
|
|
1107 might contain (very few) errors. Please report any errors to the
|
|
1108 maintainer, so that they can be fixed.}. It also scans Emacs buffers
|
|
1109 for routine definitions, queries the IDLWAVE-Shell for information
|
|
1110 about routines currently compiled there, and automatically locates
|
|
1111 library and user-created catalogs. This information is updated
|
|
1112 automatically, and so should usually be current. To force a global
|
|
1113 update and refresh the routine information, use @kbd{C-c C-i}
|
|
1114 (@code{idlwave-update-routine-info}).
|
|
1115
|
|
1116 @kindex C-c ?
|
|
1117 To display the information about a routine, press @kbd{C-c ?}, which
|
|
1118 calls the command @code{idlwave-routine-info}. When the current cursor
|
|
1119 position is on the name or in the argument list of a procedure or
|
|
1120 function, information will be displayed about the routine. For example,
|
|
1121 consider the indicated cursor positions in the following line:
|
|
1122
|
|
1123 @example
|
|
1124 plot,x,alog(x+5*sin(x) + 2),
|
|
1125 | | | | | | | |
|
|
1126 1 2 3 4 5 6 7 8
|
|
1127 @end example
|
|
1128
|
|
1129 @cindex Default routine, for info and help
|
|
1130 On positions 1,2 and 8, information about the @samp{plot} procedure will
|
|
1131 be shown. On positions 3,4, and 7, the @samp{alog} function will be
|
|
1132 described, while positions 5 and 6 will investigate the @samp{sin}
|
|
1133 function.
|
|
1134
|
|
1135 When you ask for routine information about an object method, and the
|
|
1136 method exists in several classes, IDLWAVE queries for the class of the
|
|
1137 object, unless the class is already known through a text property on the
|
|
1138 @samp{->} operator (@pxref{Object Method Completion and Class
|
|
1139 Ambiguity}), or by having been explicitly included in the call
|
|
1140 (e.g. @code{a->myclass::Foo}).
|
|
1141
|
|
1142 @cindex Calling sequences
|
|
1143 @cindex Keywords of a routine
|
|
1144 @cindex Routine source information
|
|
1145 The description displayed contains the calling sequence, the list of
|
|
1146 keywords and the source location of this routine. It looks like this:
|
|
1147
|
|
1148 @example
|
|
1149 Usage: XMANAGER, NAME, ID
|
|
1150 Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER
|
|
1151 JUST_REG MODAL NO_BLOCK
|
|
1152 Source: SystemLib [LCSB] /soft1/idl53/lib/xmanager.pro
|
|
1153 @end example
|
|
1154
|
|
1155 @cindex Categories, of routines
|
|
1156 @cindex Load-path shadows
|
|
1157 @cindex Shadows, load-path
|
|
1158 @cindex IDL variable @code{!PATH}
|
|
1159 @cindex @code{!PATH}, IDL variable
|
|
1160 @cindex IDL variable @code{!DIR}
|
|
1161 @cindex @code{!DIR}, IDL variable
|
|
1162
|
|
1163 If a definition of this routine exists in several files accessible to
|
|
1164 IDLWAVE, several @samp{Source} lines will point to the different
|
|
1165 files. This may indicate that your routine is shadowing a system
|
|
1166 library routine, which may or may not be what you want
|
|
1167 (@pxref{Load-Path Shadows}). The information about the calling
|
|
1168 sequence and keywords is derived from the first source listed.
|
|
1169 Library routines are available only if you have scanned your local IDL
|
|
1170 directories or are using pre-scanned libraries (@pxref{Catalogs}).
|
|
1171 The source entry consists of a @emph{source category}, a set of
|
|
1172 @emph{flags} and the path to the @emph{source file}. The following
|
|
1173 default categories exist:
|
|
1174
|
|
1175 @multitable @columnfractions .15 .85
|
|
1176 @item @i{System}
|
|
1177 @tab A system routine of unknown origin. When the system library has
|
|
1178 been scanned as part of a catalog (@pxref{Catalogs}), this category
|
|
1179 will automatically split into the next two.
|
|
1180 @item @i{Builtin}
|
|
1181 @tab A builtin system routine with no source code available.
|
|
1182 @item @i{SystemLib}
|
|
1183 @tab A library system routine in the official lib directory @file{!DIR/lib}.
|
|
1184 @item @i{Obsolete}
|
|
1185 @tab A library routine in the official lib directory @file{!DIR/lib/obsolete}.
|
|
1186 @item @i{Library}
|
|
1187 @tab A routine in a file on IDL's search path @code{!PATH}.
|
|
1188 @item @i{Other}
|
|
1189 @tab Any other routine with a file not known to be on the search path.
|
|
1190 @item @i{Unresolved}
|
|
1191 @tab An otherwise unknown routine the shell lists as unresolved
|
|
1192 (referenced, but not compiled).
|
|
1193 @end multitable
|
|
1194
|
|
1195 Any routines discovered in library catalogs (@pxref{Library
|
|
1196 Catalogs}), will display the category assigned during creation,
|
|
1197 e.g. @samp{NasaLib}. For routines not discovered in this way, you can
|
|
1198 create additional categories based on the routine's filename using the
|
|
1199 variable @code{idlwave-special-lib-alist}.
|
|
1200
|
|
1201 @cindex Flags, in routine info
|
|
1202 @cindex Duplicate routines
|
|
1203 @cindex Multiply defined routines
|
|
1204 @cindex Routine definitions, multiple
|
|
1205 The flags @code{[LCSB]} indicate the source of the information IDLWAVE
|
|
1206 has regarding the file: from a library catalog (@w{@code{[L---]}}),
|
|
1207 from a user catalog (@w{@code{[-C--]}}, from the IDL Shell
|
|
1208 (@w{@code{[--S-]}}) or from an Emacs buffer (@w{@code{[---B]}}).
|
|
1209 Combinations are possible (a compiled library routine visited in a
|
|
1210 buffer might read @w{@code{[L-SB]}}). If a file contains multiple
|
|
1211 definitions of the same routine, the file name will be prefixed with
|
|
1212 @samp{(Nx)} where @samp{N} is the number of definitions.
|
|
1213
|
|
1214 @cindex Online Help from the routine info buffer
|
|
1215 @cindex Active text, in routine info
|
|
1216 @cindex Inserting keywords, from routine info
|
|
1217 @cindex Source file, access from routine info
|
|
1218 Some of the text in the @file{*Help*} routine info buffer will be active
|
|
1219 (it is highlighted when the mouse moves over it). Typically, clicking
|
|
1220 with the right mouse button invokes online help lookup, and clicking
|
|
1221 with the middle mouse button inserts keywords or visits files:
|
|
1222
|
|
1223 @multitable @columnfractions 0.15 0.85
|
|
1224 @item @i{Usage}
|
|
1225 @tab If online help is installed, a click with the @emph{right} mouse
|
|
1226 button on the @i{Usage:} line will access the help for the
|
|
1227 routine (@pxref{Online Help}).
|
|
1228 @item @i{Keyword}
|
|
1229 @tab Online help about keywords is also available with the
|
|
1230 @emph{right} mouse button. Clicking on a keyword with the @emph{middle}
|
|
1231 mouse button will insert this keyword in the buffer from where
|
|
1232 @code{idlwave-routine-info} was called. Holding down @key{SHIFT} while
|
|
1233 clicking also adds the initial @samp{/}.
|
|
1234 @item @i{Source}
|
|
1235 @tab Clicking with the @emph{middle} mouse button on a @samp{Source} line
|
|
1236 finds the source file of the routine and visits it in another window.
|
|
1237 Another click on the same line switches back to the buffer from which
|
|
1238 @kbd{C-c ?} was called. If you use the @emph{right} mouse button, the
|
|
1239 source will not be visited by a buffer, but displayed in the online help
|
|
1240 window.
|
|
1241 @item @i{Classes}
|
|
1242 @tab The @i{Classes} line is only included in the routine info window if
|
|
1243 the current class inherits from other classes. You can click with the
|
|
1244 @emph{middle} mouse button to display routine info about the current
|
|
1245 method in other classes on the inheritance chain, if such a method
|
|
1246 exists there.
|
|
1247 @end multitable
|
|
1248
|
|
1249 @defopt idlwave-resize-routine-help-window (@code{t})
|
|
1250 Non-@code{nil} means resize the Routine-info @file{*Help*} window to
|
|
1251 fit the content.
|
|
1252 @end defopt
|
|
1253
|
|
1254 @defopt idlwave-special-lib-alist
|
|
1255 Alist of regular expressions matching special library directories.
|
|
1256 @end defopt
|
|
1257
|
|
1258 @defopt idlwave-rinfo-max-source-lines (@code{5})
|
|
1259 Maximum number of source files displayed in the Routine Info window.
|
|
1260 @end defopt
|
|
1261
|
|
1262
|
|
1263 @html
|
|
1264 <A NAME="ONLINE_HELP"></A>
|
|
1265 @end html
|
|
1266 @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode
|
|
1267 @section Online Help
|
|
1268
|
|
1269 @cindex Online Help
|
|
1270 @cindex @file{idlw-help.txt}
|
|
1271 @cindex @file{idlw-help.el}
|
|
1272 @cindex Installing online help
|
|
1273 @cindex Online Help, Installation
|
|
1274 @cindex Speed, of online help
|
|
1275 @cindex XML Help Catalog
|
|
1276
|
|
1277 For IDL system routines, extensive documentation is supplied with IDL.
|
|
1278 IDLWAVE can access the HTML version of this documentation very quickly
|
|
1279 and accurately, based on the local context. This can be @emph{much}
|
|
1280 faster than using the IDL online help application, because IDLWAVE
|
|
1281 usually gets you to the right place in the documentation directly ---
|
|
1282 e.g. a specific keyword of a routine --- without any additional browsing
|
|
1283 and scrolling.
|
|
1284
|
|
1285 For this online help to work, an HTML version of the IDL documentation
|
|
1286 is required. Beginning with IDL 6.2, HTML documentation is distributed
|
|
1287 directly with IDL, along with an XML-based catalog of routine
|
|
1288 information. By default, IDLWAVE automatically attempts to convert this
|
|
1289 XML catalog into a format Emacs can more easily understand, and caches
|
|
1290 this information in your @code{idlwave_config_directory}
|
|
1291 (@file{~/.idlwave/}, by default). It also re-scans the XML catalog if
|
|
1292 it is newer than the current cached version. You can force rescan with
|
|
1293 the menu entry @code{IDLWAVE->Routine Info->Rescan XML Help Catalog}.
|
|
1294
|
|
1295 Before IDL 6.2, the HTML help was not distributed with IDL, and was not
|
|
1296 part of the standalone IDLWAVE distribution, but had to be downloaded
|
|
1297 separately. This is no longer necessary: all help and routine
|
|
1298 information is supplied with IDL versions 6.2 and later.
|
|
1299
|
|
1300 There are a variety of options for displaying the HTML help: see below.
|
|
1301 Help for routines without HTML documentation is also available, by using
|
|
1302 the routine documentation header and/or routine source.
|
|
1303
|
|
1304 @kindex M-?
|
|
1305 In any IDL program (or, as with most IDLWAVE commands, in the IDL
|
|
1306 Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with
|
|
1307 @kbd{S-Mouse-3} to access context sensitive online help. The following
|
|
1308 locations are recognized context for help:
|
|
1309
|
|
1310 @cindex Context, for online help
|
|
1311 @multitable @columnfractions .25 .75
|
|
1312 @item @i{Routine names}
|
|
1313 @tab The name of a routine (function, procedure, method).
|
|
1314 @item @i{Keyword Parameters}
|
|
1315 @tab A keyword parameter of a routine.
|
|
1316 @item @i{System Variables}
|
|
1317 @tab System variables like @code{!DPI}.
|
|
1318 @item @i{System Variable Tags}
|
|
1319 @tab System variables tags like @code{!D.X_SIZE}.
|
|
1320 @item @i{IDL Statements}
|
|
1321 @tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc.
|
|
1322 @item @i{IDL Controls}
|
|
1323 @tab Control structures like @code{FOR}, @code{SWITCH}, etc.
|
|
1324 @item @i{Class names}
|
|
1325 @tab A class name in an @code{OBJ_NEW} call.
|
|
1326 @item @i{Class Init Keywords}
|
|
1327 @tab Beyond the class name in an @code{OBJ_NEW} call.
|
|
1328 @item @i{Executive Command}
|
|
1329 @tab An executive command like @code{.RUN}. Mostly useful in the shell.
|
|
1330 @item @i{Structure Tags}
|
|
1331 @tab Structure tags like @code{state.xsize}
|
|
1332 @item @i{Class Tags}
|
|
1333 @tab Class tags like @code{self.value}.
|
|
1334 @item @i{Default}
|
|
1335 @tab The routine that would be selected for routine info display.
|
|
1336 @end multitable
|
|
1337
|
|
1338 @cindex @code{OBJ_NEW}, special online help
|
|
1339 Note that the @code{OBJ_NEW} function is special in that the help
|
|
1340 displayed depends on the cursor position. If the cursor is on the
|
|
1341 @samp{OBJ_NEW}, this function is described. If it is on the class
|
|
1342 name inside the quotes, the documentation for the class is pulled up.
|
|
1343 If the cursor is @emph{after} the class name, anywhere in the argument
|
|
1344 list, the documentation for the corresponding @code{Init} method and
|
|
1345 its keywords is targeted.
|
|
1346
|
|
1347 Apart from an IDLWAVE buffer or shell, there are two more places from
|
|
1348 which online help can be accessed.
|
|
1349
|
|
1350 @itemize @bullet
|
|
1351 @item
|
|
1352 Online help for routines and keywords can be accessed through the
|
|
1353 Routine Info display. Click with @kbd{Mouse-3} on an item to see the
|
|
1354 corresponding help (@pxref{Routine Info}).
|
|
1355 @item
|
|
1356 When using completion and Emacs pops up a @file{*Completions*} buffer
|
|
1357 with possible completions, clicking with @kbd{Mouse-3} on a completion
|
|
1358 item invokes help on that item (@pxref{Completion}). Items for which
|
|
1359 help is available in the online system documentation (vs. just the
|
|
1360 program source itself) will be emphasized (e.g. colored blue).
|
|
1361 @end itemize
|
|
1362 @noindent
|
|
1363 In both cases, a blue face indicates that the item is documented in
|
|
1364 the IDL manual, but an attempt will be made to visit non-blue items
|
|
1365 directly in the originating source file.
|
|
1366
|
|
1367
|
|
1368 @menu
|
|
1369 * Help with HTML Documentation::
|
|
1370 * Help with Source::
|
|
1371 @end menu
|
|
1372
|
|
1373 @node Help with HTML Documentation, Help with Source, Online Help, Online Help
|
|
1374 @subsection Help with HTML Documentation
|
|
1375 @cindex HTML Help
|
|
1376 @cindex Help using HTML manuals
|
|
1377 @cindex IDL manual, HTML version
|
|
1378 @cindex IDL Assistant
|
|
1379
|
|
1380 Help using the HTML documentation is invoked with the built-in Emacs
|
|
1381 command @code{browse-url}, which displays the relevant help topic in a
|
|
1382 browser of your choosing. Beginning with version 6.2, IDL comes with
|
|
1383 the help browser @emph{IDL Assistant}, which it uses by default for
|
|
1384 displaying online help on all supported platforms. This browser
|
|
1385 offers topical searches, an index, and is also now the default and
|
|
1386 recommended IDLWAVE help browser. The variable
|
|
1387 @code{idlwave-help-use-assistant} controls whether this browser is
|
|
1388 used. Note that, due to limitations in the Assistant, invoking help
|
|
1389 within IDLWAVE and @code{? topic} within IDL will result in two
|
|
1390 running copies of Assistant.
|
|
1391
|
|
1392 Aside from the IDL Assistant, there are many possible browsers to choose
|
|
1393 among, with differing advantages and disadvantages. The variable
|
|
1394 @code{idlwave-help-browser-function} controls which browser help is sent
|
|
1395 to (as long as @code{idlwave-help-use-assistant} is not set). This
|
|
1396 function is used to set the variable @code{browse-url-browser-function}
|
|
1397 locally for IDLWAVE help only. Customize the latter variable to see
|
|
1398 what choices of browsers your system offers. Certain browsers like
|
|
1399 @code{w3} (bundled with many versions of Emacs) and @code{w3m}
|
|
1400 (@uref{http://emacs-w3m.namazu.org/}) are run within Emacs, and use
|
|
1401 Emacs buffers to display the HTML help. This can be convenient,
|
|
1402 especially on small displays, and images can even be displayed in-line
|
|
1403 on newer Emacs versions. However, better formatting results are often
|
|
1404 achieved with external browsers, like Mozilla. IDLWAVE assumes any
|
|
1405 browser function containing "w3" is displayed in a local buffer. If you
|
|
1406 are using another Emacs-local browser for which this is not true, set
|
|
1407 the variable @code{idlwave-help-browser-is-local}.
|
|
1408
|
|
1409 With IDL 6.2 or later, it is important to ensure that the variable
|
|
1410 @code{idlwave-system-directory} is set (@pxref{Catalogs}). One easy way
|
|
1411 to ensure this is to run the IDL Shell (@kbd{C-c C-s}). It will be
|
|
1412 queried for this directory, and the results will be cached to file for
|
|
1413 subsequent use.
|
|
1414
|
|
1415 @xref{HTML Help Browser Tips}, for more information on selecting and
|
|
1416 configuring a browser for use with IDL's HTML help system.
|
|
1417
|
|
1418 @defopt idlwave-html-system-help-location @file{help/online_help}
|
|
1419 Relative directory of the system-supplied HTML help directory,
|
|
1420 considered with respect to @code{idlwave-system-directory}. Relevant
|
|
1421 for IDL 6.2 and greater. Should not change.
|
|
1422 @end defopt
|
|
1423
|
|
1424 @defopt idlwave-html-help-location @file{/usr/local/etc/}
|
|
1425 The directory where the @file{idl_html_help} HTML directory live.
|
|
1426 Obsolete and ignored for IDL 6.2 and greater
|
|
1427 (@code{idlwave-html-system-help-location} is used instead).
|
|
1428 @end defopt
|
|
1429
|
|
1430 @defopt idlwave-help-use-assistant @code{t}
|
|
1431 If set, use the IDL Assistant if possible for online HTML help,
|
|
1432 otherwise use the browser function specified in
|
|
1433 @code{idlwave-help-browser-function}.
|
|
1434 @end defopt
|
|
1435
|
|
1436 @defopt idlwave-help-browser-function
|
|
1437 The browser function to use to display IDLWAVE HTML help. Should be
|
|
1438 one of the functions available for setting
|
|
1439 @code{browse-url-browser-function}, which see.
|
|
1440 @end defopt
|
|
1441
|
|
1442 @defopt idlwave-help-browser-is-local
|
|
1443 Is the browser selected in @code{idlwave-help-browser-function} run in a
|
|
1444 local Emacs buffer or window? Defaults to @code{t} if the function
|
|
1445 contains "-w3".
|
|
1446 @end defopt
|
|
1447
|
|
1448 @defopt idlwave-help-link-face
|
|
1449 The face for links to IDLWAVE online help.
|
|
1450 @end defopt
|
|
1451
|
|
1452 @node Help with Source, , Help with HTML Documentation, Online Help
|
|
1453 @subsection Help with Source
|
|
1454 @cindex Help using routine source
|
|
1455
|
|
1456 @cindex Source code, as online help
|
|
1457 @cindex DocLib header, as online help
|
|
1458 For routines which are not documented in an HTML manual (for example
|
|
1459 personal or library routines), the source code itself is used as help
|
|
1460 text. If the requested information can be found in a (more or less)
|
|
1461 standard DocLib file header, IDLWAVE shows the header (scrolling down to
|
|
1462 a keyword, if appropriate). Otherwise the routine definition statement
|
|
1463 (@code{pro}/@code{function}) is shown. The doclib header sections which
|
|
1464 are searched for include @samp{NAME} and @samp{KEYWORDS}. Localization
|
|
1465 support can be added by customizing the @code{idlwave-help-doclib-name}
|
|
1466 and @code{idlwave-help-doclib-keyword} variables.
|
|
1467
|
|
1468 @cindex Structure tags, in online help
|
|
1469 @cindex Class tags, in online help
|
|
1470 Help is also available for class structure tags (@code{self.TAG}), and
|
|
1471 generic structure tags, if structure tag completion is enabled
|
|
1472 (@pxref{Structure Tag Completion}). This is implemented by visiting the
|
|
1473 tag within the class or structure definition source itself. Help is not
|
|
1474 available on built-in system class tags.
|
|
1475
|
|
1476 The help window is normally displayed in the same frame, but can be
|
|
1477 popped-up in a separate frame. The following commands can be used to
|
|
1478 navigate inside the help system for source files:
|
|
1479
|
|
1480 @multitable @columnfractions .15 .85
|
|
1481 @item @kbd{@key{SPACE}}
|
|
1482 @tab Scroll forward one page.
|
|
1483 @item @kbd{@key{RET}}
|
|
1484 @tab Scroll forward one line.
|
|
1485 @item @kbd{@key{DEL}}
|
|
1486 @tab Scroll back one page.
|
|
1487 @item @kbd{h}
|
|
1488 @tab Jump to DocLib Header of the routine whose source is displayed
|
|
1489 as help.
|
|
1490 @item @kbd{H}
|
|
1491 @tab Jump to the first DocLib Header in the file.
|
|
1492 @item @kbd{.} @r{(Dot)}
|
|
1493 @tab Jump back and forth between the routine definition (the
|
|
1494 @code{pro}/@code{function} statement) and the description of the help
|
|
1495 item in the DocLib header.
|
|
1496 @item @kbd{F}
|
|
1497 @tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}.
|
|
1498 @item @kbd{q}
|
|
1499 @tab Kill the help window.
|
|
1500 @end multitable
|
|
1501
|
|
1502
|
|
1503 @defopt idlwave-help-use-dedicated-frame (@code{nil})
|
|
1504 Non-@code{nil} means use a separate frame for Online Help if possible.
|
|
1505 @end defopt
|
|
1506
|
|
1507 @defopt idlwave-help-frame-parameters
|
|
1508 The frame parameters for the special Online Help frame.
|
|
1509 @end defopt
|
|
1510
|
|
1511 @defopt idlwave-max-popup-menu-items (@code{20})
|
|
1512 Maximum number of items per pane in pop-up menus.
|
|
1513 @end defopt
|
|
1514
|
|
1515 @defopt idlwave-extra-help-function
|
|
1516 Function to call for help if the normal help fails.
|
|
1517 @end defopt
|
|
1518
|
|
1519 @defopt idlwave-help-fontify-source-code (@code{nil})
|
|
1520 Non-@code{nil} means fontify source code displayed as help.
|
|
1521 @end defopt
|
|
1522
|
|
1523 @defopt idlwave-help-source-try-header (@code{t})
|
|
1524 Non-@code{nil} means try to find help in routine header when
|
|
1525 displaying source file.
|
|
1526 @end defopt
|
|
1527
|
|
1528 @defopt idlwave-help-doclib-name (@code{"name"})
|
|
1529 The case-insensitive heading word in doclib headers to locate the
|
|
1530 @emph{name} section. Can be a regexp, e.g. @code{"\\(name\\|nom\\)"}.
|
|
1531 @end defopt
|
|
1532
|
|
1533 @defopt idlwave-help-doclib-keyword (@code{"KEYWORD"})
|
|
1534 The case-insensitive heading word in doclib headers to locate the
|
|
1535 @emph{keywords} section. Can be a regexp.
|
|
1536 @end defopt
|
|
1537
|
|
1538
|
|
1539 @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode
|
|
1540 @section Completion
|
|
1541 @cindex Completion
|
|
1542 @cindex Keyword completion
|
|
1543 @cindex Method completion
|
|
1544 @cindex Object method completion
|
|
1545 @cindex Class name completion
|
|
1546 @cindex Function name completion
|
|
1547 @cindex Procedure name completion
|
|
1548
|
|
1549 @kindex M-@key{TAB}
|
|
1550 @kindex C-c C-i
|
|
1551 IDLWAVE offers completion for class names, routine names, keywords,
|
|
1552 system variables, system variable tags, class structure tags, regular
|
|
1553 structure tags and file names. As in many programming modes, completion
|
|
1554 is bound to @kbd{M-@key{TAB}} (or simply @kbd{@key{TAB}} in the IDLWAVE
|
|
1555 Shell --- @pxref{Using the Shell}). Completion uses exactly the same
|
|
1556 internal information as routine info, so when necessary (rarely) it can
|
|
1557 be updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}).
|
|
1558
|
|
1559 The completion function is context sensitive and figures out what to
|
|
1560 complete based on the location of the point. Here are example lines and
|
|
1561 what @kbd{M-@key{TAB}} would try to complete when the cursor is on the
|
|
1562 position marked with a @samp{_}:
|
|
1563
|
|
1564 @example
|
|
1565 plo_ @r{Procedure}
|
|
1566 x = a_ @r{Function}
|
|
1567 plot,xra_ @r{Keyword of @code{plot} procedure}
|
|
1568 plot,x,y,/x_ @r{Keyword of @code{plot} procedure}
|
|
1569 plot,min(_ @r{Keyword of @code{min} function}
|
|
1570 obj -> a_ @r{Object method (procedure)}
|
|
1571 a[2,3] = obj -> a_ @r{Object method (function)}
|
|
1572 x = obj_new('IDL_ @r{Class name}
|
|
1573 x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}}
|
|
1574 pro A_ @r{Class name}
|
|
1575 pro _ @r{Fill in @code{Class::} of first method in this file}
|
|
1576 !v_ @r{System variable}
|
|
1577 !version.t_ @r{Structure tag of system variable}
|
|
1578 self.g_ @r{Class structure tag in methods}
|
|
1579 state.w_ @r{Structure tag, if tag completion enabled}
|
|
1580 name = 'a_ @r{File name (default inside quotes)}
|
|
1581 @end example
|
|
1582
|
|
1583 @cindex Completion, ambiguity
|
|
1584 @cindex Completion, forcing function name
|
|
1585 The only place where completion is ambiguous is procedure/function
|
|
1586 @emph{keywords} versus @emph{functions}. After @samp{plot,x,_}, IDLWAVE
|
|
1587 will always assume a keyword to @samp{plot}. However, a function is
|
|
1588 also a possible completion here. You can force completion of a function
|
|
1589 name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}.
|
|
1590
|
|
1591 Giving two prefix arguments (@kbd{C-u C-u M-@key{TAB}}) prompts for a
|
|
1592 regular expression to search among the commands to be completed. As
|
|
1593 an example, completing a blank line in this way will allow you to
|
|
1594 search for a procedure matching a regexp.
|
|
1595
|
|
1596 @cindex Scrolling the @file{*Completions*} window
|
|
1597 @cindex Completion, scrolling
|
|
1598 @cindex Completion, Online Help
|
|
1599 @cindex Online Help in @file{*Completions*} buffer
|
|
1600 If the list of completions is too long to fit in the
|
|
1601 @file{*Completions*} window, the window can be scrolled by pressing
|
|
1602 @kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each
|
|
1603 possible completion is available by clicking with @kbd{Mouse-3} on the
|
|
1604 item. Items for which system online help (from the IDL manual) is
|
|
1605 available will be emphasized (e.g. colored blue). For other items, the
|
|
1606 corresponding source code or DocLib header will be used as the help
|
|
1607 text.
|
|
1608
|
|
1609 @cindex Completion, cancelling
|
|
1610 @cindex Cancelling completion
|
|
1611 Completion is not a blocking operation --- you are free to continue
|
|
1612 editing, enter commands, or simply ignore the @file{*Completions*}
|
|
1613 buffer during a completion operation. If, however, the most recent
|
|
1614 command was a completion, @kbd{C-g} will remove the buffer and restore
|
|
1615 the window configuration. You can also remove the buffer at any time
|
|
1616 with no negative consequences.
|
|
1617
|
|
1618 @defopt idlwave-keyword-completion-adds-equal (@code{t})
|
|
1619 Non-@code{nil} means completion automatically adds @samp{=} after
|
|
1620 completed keywords.
|
|
1621 @end defopt
|
|
1622
|
|
1623 @defopt idlwave-function-completion-adds-paren (@code{t})
|
|
1624 Non-@code{nil} means completion automatically adds @samp{(} after
|
|
1625 completed function. A value of `2' means also add the closing
|
|
1626 parenthesis and position the cursor between the two.
|
|
1627 @end defopt
|
|
1628
|
|
1629 @defopt idlwave-completion-restore-window-configuration (@code{t})
|
|
1630 Non-@code{nil} means restore window configuration after successful
|
|
1631 completion.
|
|
1632 @end defopt
|
|
1633
|
|
1634 @defopt idlwave-highlight-help-links-in-completion (@code{t})
|
|
1635 Non-@code{nil} means highlight completions for which system help is
|
|
1636 available.
|
|
1637 @end defopt
|
|
1638
|
|
1639 @menu
|
|
1640 * Case of Completed Words:: CaseOFcomPletedWords
|
|
1641 * Object Method Completion and Class Ambiguity:: obj->Method, what?
|
|
1642 * Object Method Completion in the Shell::
|
|
1643 * Class and Keyword Inheritance:: obj->Method, _EXTRA=e
|
|
1644 * Structure Tag Completion:: Completing state.Tag
|
|
1645 @end menu
|
|
1646
|
|
1647 @node Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion
|
|
1648 @subsection Case of Completed Words
|
|
1649 @cindex Case of completed words
|
|
1650 @cindex Mixed case completion
|
|
1651 IDL is a case-insensitive language, so casing is a matter of style
|
|
1652 only. IDLWAVE helps maintain a consistent casing style for completed
|
|
1653 items. The case of the completed words is determined by what is
|
|
1654 already in the buffer. As an exception, when the partial word being
|
|
1655 completed is all lower case, the completion will be lower case as
|
|
1656 well. If at least one character is upper case, the string will be
|
|
1657 completed in upper case or mixed case, depending on the value of the
|
|
1658 variable @code{idlwave-completion-case}. The default is to use upper
|
|
1659 case for procedures, functions and keywords, and mixed case for object
|
|
1660 class names and methods, similar to the conventions in the IDL
|
|
1661 manuals. For instance, to enable mixed-case completion for routines
|
|
1662 in addition to classes and methods, you need an entry such as
|
|
1663 @code{(routine . preserve)} in that variable. To enable total control
|
|
1664 over the case of completed items, independent of buffer context, set
|
|
1665 @code{idlwave-completion-force-default-case} to non-@code{nil}.
|
|
1666
|
|
1667 @defopt idlwave-completion-case
|
|
1668 Association list setting the case (UPPER/lower/Capitalized/MixedCase...)
|
|
1669 of completed words.
|
|
1670 @end defopt
|
|
1671
|
|
1672 @defopt idlwave-completion-force-default-case (@code{nil})
|
|
1673 Non-@code{nil} means completion will always honor the settings in
|
|
1674 @code{idlwave-completion-case}. When nil (the default), entirely lower
|
|
1675 case strings will always be completed to lower case, no matter what the
|
|
1676 settings in @code{idlwave-completion-case}.
|
|
1677 @end defopt
|
|
1678
|
|
1679 @defopt idlwave-complete-empty-string-as-lower-case (@code{nil})
|
|
1680 Non-@code{nil} means the empty string is considered lower case for
|
|
1681 completion.
|
|
1682 @end defopt
|
|
1683
|
|
1684 @node Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion
|
|
1685 @subsection Object Method Completion and Class Ambiguity
|
|
1686 @cindex Object methods
|
|
1687 @cindex Class ambiguity
|
|
1688 @cindex @code{self} object, default class
|
|
1689 An object method is not uniquely determined without the object's class.
|
|
1690 Since the class is almost always omitted in the calling source (as
|
|
1691 required to obtain the true benefits of object-based programming),
|
|
1692 IDLWAVE considers all available methods in all classes as possible
|
|
1693 method name completions. The combined list of keywords of the current
|
|
1694 method in @emph{all} known classes which contain that method will be
|
|
1695 considered for keyword completion. In the @file{*Completions*} buffer,
|
|
1696 the matching classes will be shown next to each item (see option
|
|
1697 @code{idlwave-completion-show-classes}). As a special case, the class
|
|
1698 of an object called @samp{self} is always taken to be the class of the
|
|
1699 current routine, when in an IDLWAVE buffer. All inherits classes are
|
|
1700 considered as well.
|
|
1701
|
|
1702 @cindex Forcing class query.
|
|
1703 @cindex Class query, forcing
|
|
1704 You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u
|
|
1705 M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to
|
|
1706 narrow down the number of possible completions. The variable
|
|
1707 @code{idlwave-query-class} can be configured to make such prompting the
|
|
1708 default for all methods (not recommended), or selectively for very
|
|
1709 common methods for which the number of completing keywords would be too
|
|
1710 large (e.g. @code{Init,SetProperty,GetProperty}).
|
|
1711
|
|
1712 @cindex Saving object class on @code{->}
|
|
1713 @cindex @code{->}
|
|
1714 After you have specified the class for a particular statement (e.g. when
|
|
1715 completing the method), IDLWAVE can remember it for the rest of the
|
|
1716 editing session. Subsequent completions in the same statement
|
|
1717 (e.g. keywords) can then reuse this class information. This works by
|
|
1718 placing a text property on the method invocation operator @samp{->},
|
|
1719 after which the operator will be shown in a different face (bold by
|
|
1720 default). The variable @code{idlwave-store-inquired-class} can be used
|
|
1721 to turn it off or on.
|
|
1722
|
|
1723 @defopt idlwave-completion-show-classes (@code{1})
|
|
1724 Non-@code{nil} means show up to that many classes in
|
|
1725 @file{*Completions*} buffer when completing object methods and
|
|
1726 keywords.
|
|
1727 @end defopt
|
|
1728
|
|
1729 @defopt idlwave-completion-fontify-classes (@code{t})
|
|
1730 Non-@code{nil} means fontify the classes in completions buffer.
|
|
1731 @end defopt
|
|
1732
|
|
1733 @defopt idlwave-query-class (@code{nil})
|
|
1734 Association list governing query for object classes during completion.
|
|
1735 @end defopt
|
|
1736
|
|
1737 @defopt idlwave-store-inquired-class (@code{t})
|
|
1738 Non-@code{nil} means store class of a method call as text property on
|
|
1739 @samp{->}.
|
|
1740 @end defopt
|
|
1741
|
|
1742 @defopt idlwave-class-arrow-face
|
|
1743 Face to highlight object operator arrows @samp{->} which carry a saved
|
|
1744 class text property.
|
|
1745 @end defopt
|
|
1746
|
|
1747 @node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion
|
|
1748 @subsection Object Method Completion in the Shell
|
|
1749 @cindex Method Completion in Shell
|
|
1750 In the IDLWAVE Shell (@pxref{The IDLWAVE Shell}), objects on which
|
|
1751 methods are being invoked have a special property: they must exist as
|
|
1752 variables, and so their class can be determined (for instance, using the
|
|
1753 @code{obj_class()} function). In the Shell, when attempting completion,
|
|
1754 routine info, or online help within a method routine, a query is sent to
|
|
1755 determine the class of the object. If this query is successful, the
|
|
1756 class found will be used to select appropriate completions, routine
|
|
1757 info, or help. If unsuccessful, information from all known classes will
|
|
1758 be used (as in the buffer).
|
|
1759
|
|
1760 @node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion
|
|
1761 @subsection Class and Keyword Inheritance
|
|
1762 @cindex Inheritance, class
|
|
1763 @cindex Keyword inheritance
|
|
1764 @cindex Inheritance, keyword
|
|
1765
|
|
1766 Class inheritance affects which methods are called in IDL. An object of
|
|
1767 a class which inherits methods from one or more superclasses can
|
|
1768 override that method by defining its own method of the same name, extend
|
|
1769 the method by calling the method(s) of its superclass(es) in its
|
|
1770 version, or inherit the method directly by making no modifications.
|
|
1771 IDLWAVE examines class definitions during completion and routine
|
|
1772 information display, and records all inheritance information it finds.
|
|
1773 This information is displayed if appropriate with the calling sequence
|
|
1774 for methods (@pxref{Routine Info}), as long as variable
|
|
1775 @code{idlwave-support-inheritance} is non-@code{nil}.
|
|
1776
|
|
1777 In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and
|
|
1778 @code{_REF_EXTRA}) is used hand-in-hand with class inheritance and
|
|
1779 method overriding. E.g., in a @code{SetProperty} method, this technique
|
|
1780 allows a single call @code{obj->SetProperty} to set properties up the
|
|
1781 entire class inheritance chain. This is often referred to as
|
|
1782 @emph{chaining}, and is characterized by chained method calls like
|
|
1783 @w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}.
|
|
1784
|
|
1785 IDLWAVE can accommodate this special synergy between class and keyword
|
|
1786 inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a
|
|
1787 method's keyword parameters, all keywords of superclass versions of
|
|
1788 the method being considered can be included in completion. There is
|
|
1789 of course no guarantee that this type of keyword chaining actually
|
|
1790 occurs, but for some methods it's a very convenient assumption. The
|
|
1791 variable @code{idlwave-keyword-class-inheritance} can be used to
|
|
1792 configure which methods have keyword inheritance treated in this
|
|
1793 simple, class-driven way. By default, only @code{Init} and
|
|
1794 @code{(Get|Set)Property} are. The completion buffer will label
|
|
1795 keywords based on their originating class.
|
|
1796
|
|
1797 @defopt idlwave-support-inheritance (@code{t})
|
|
1798 Non-@code{nil} means consider inheritance during completion, online help etc.
|
|
1799 @end defopt
|
|
1800
|
|
1801 @defopt idlwave-keyword-class-inheritance
|
|
1802 A list of regular expressions to match methods for which simple
|
|
1803 class-driven keyword inheritance will be used for Completion.
|
|
1804 @end defopt
|
|
1805
|
|
1806 @node Structure Tag Completion, , Class and Keyword Inheritance, Completion
|
|
1807 @subsection Structure Tag Completion
|
|
1808 @cindex Completion, structure tag
|
|
1809 @cindex Structure tag completion
|
|
1810
|
|
1811 In many programs, especially those involving widgets, large structures
|
|
1812 (e.g. the @samp{state} structure) are used to communicate among
|
|
1813 routines. It is very convenient to be able to complete structure tags,
|
|
1814 in the same way as for instance variables (tags) of the @samp{self}
|
|
1815 object (@pxref{Object Method Completion and Class Ambiguity}). Add-in
|
|
1816 code for structure tag completion is available in the form of a loadable
|
|
1817 completion module: @file{idlw-complete-structtag.el}. Tag completion in
|
|
1818 structures is highly ambiguous (much more so than @samp{self}
|
|
1819 completion), so @code{idlw-complete-structtag} makes an unusual and very
|
|
1820 specific assumption: the exact same variable name is used to refer to
|
|
1821 the structure in all parts of the program. This is entirely unenforced
|
|
1822 by the IDL language, but is a typical convention. If you consistently
|
|
1823 refer to the same structure with the same variable name
|
|
1824 (e.g. @samp{state}), structure tags which are read from its definition
|
|
1825 in the same file can be used for completion.
|
|
1826
|
|
1827 Structure tag completion is not enabled by default. To enable it,
|
|
1828 simply add the following to your @file{.emacs}:
|
|
1829
|
|
1830 @lisp
|
|
1831 (add-hook 'idlwave-load-hook
|
|
1832 (lambda () (require 'idlw-complete-structtag)))
|
|
1833 @end lisp
|
|
1834
|
|
1835 Once enabled, you'll also be able to access online help on the structure
|
|
1836 tags, using the usual methods (@pxref{Online Help}). In addition,
|
|
1837 structure variables in the shell will be queried for tag names, similar
|
|
1838 to the way object variables in the shell are queried for method names.
|
|
1839 So, e.g.:
|
|
1840
|
|
1841 @example
|
|
1842 IDL> st.[Tab]
|
|
1843 @end example
|
|
1844
|
|
1845 @noindent will complete with all structure fields of the structure
|
|
1846 @code{st}.
|
|
1847
|
|
1848 @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode
|
|
1849 @section Routine Source
|
|
1850 @cindex Routine source file
|
|
1851 @cindex Module source file
|
|
1852 @cindex Source file, of a routine
|
|
1853 @kindex C-c C-v
|
|
1854 In addition to clicking on a @i{Source:} line in the routine info
|
|
1855 window, there is another way to quickly visit the source file of a
|
|
1856 routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks
|
|
1857 for a module name, offering the same default as
|
|
1858 @code{idlwave-routine-info} would have used, taken from nearby buffer
|
|
1859 contents. In the minibuffer, specify a complete routine name (including
|
|
1860 any class part). IDLWAVE will display the source file in another
|
|
1861 window, positioned at the routine in question. You can also limit this
|
|
1862 to a routine in the current buffer only, with completion, and a
|
|
1863 context-sensitive default, by using a single prefix (@kbd{C-u C-c C-v})
|
|
1864 or the convenience binding @kbd{C-c C-t}.
|
|
1865
|
|
1866 @cindex Buffers, killing
|
|
1867 @cindex Killing autoloaded buffers
|
|
1868 Since getting the source of a routine into a buffer is so easy with
|
|
1869 IDLWAVE, too many buffers visiting different IDL source files are
|
|
1870 sometimes created. The special command @kbd{C-c C-k}
|
|
1871 (@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove
|
|
1872 these buffers.
|
|
1873
|
|
1874 @node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode
|
|
1875 @section Resolving Routines
|
|
1876 @cindex @code{RESOLVE_ROUTINE}
|
|
1877 @cindex Compiling library modules
|
|
1878 @cindex Routines, resolving
|
|
1879
|
|
1880 The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve}
|
|
1881 and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL
|
|
1882 in order to resolve (compile) it. The default routine to be resolved is
|
|
1883 taken from context, but you get a chance to edit it. Usually this is
|
|
1884 not necessary, since IDL automatically discovers routines on its path.
|
|
1885
|
|
1886 @code{idlwave-resolve} is one way to get a library module within reach
|
|
1887 of IDLWAVE's routine info collecting functions. A better way is to
|
|
1888 keep routine information available in catalogs (@pxref{Catalogs}).
|
|
1889 Routine info on modules will then be available without the need to
|
|
1890 compile the modules first, and even without a running shell.
|
|
1891
|
|
1892 @xref{Sources of Routine Info}, for more information on the ways IDLWAVE
|
|
1893 collects data about routines, and how to update this information.
|
|
1894
|
|
1895 @node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode
|
|
1896 @section Code Templates
|
|
1897 @cindex Code templates
|
|
1898 @cindex Templates
|
|
1899
|
|
1900 IDLWAVE can insert IDL code templates into the buffer. For a few
|
|
1901 templates, this is done with direct key bindings:
|
|
1902
|
|
1903 @multitable @columnfractions .15 .85
|
|
1904 @item @kbd{C-c C-c}
|
|
1905 @tab @code{CASE} statement template
|
|
1906 @item @kbd{C-c C-f}
|
|
1907 @tab @code{FOR} loop template
|
|
1908 @item @kbd{C-c C-r}
|
|
1909 @tab @code{REPEAT} loop template
|
|
1910 @item @kbd{C-c C-w}
|
|
1911 @tab @code{WHILE} loop template
|
|
1912 @end multitable
|
|
1913
|
|
1914 All code templates are also available as abbreviations
|
|
1915 (@pxref{Abbreviations}).
|
|
1916
|
|
1917 @node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode
|
|
1918 @section Abbreviations
|
|
1919 @cindex Abbreviations
|
|
1920
|
|
1921 Special abbreviations exist to enable rapid entry of commonly used
|
|
1922 commands. Emacs abbreviations are expanded by typing text into the
|
|
1923 buffer and pressing @key{SPC} or @key{RET}. The special abbreviations
|
|
1924 used to insert code templates all start with a @samp{\} (the backslash),
|
|
1925 or, optionally, any other character set in
|
|
1926 @code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are
|
|
1927 only expanded where they should be (i.e., not in a string or comment),
|
|
1928 and permits the point to be moved after an abbreviation expansion ---
|
|
1929 very useful for positioning the mark inside of parentheses, etc.
|
|
1930
|
|
1931 Special abbreviations are pre-defined for code templates and other
|
|
1932 useful items. To visit the full list of abbreviations, use @kbd{M-x
|
|
1933 idlwave-list-abbrevs}.
|
|
1934
|
|
1935 Template abbreviations:
|
|
1936
|
|
1937 @multitable @columnfractions .15 .85
|
|
1938 @item @code{\pr}
|
|
1939 @tab @code{PROCEDURE} template
|
|
1940 @item @code{\fu}
|
|
1941 @tab @code{FUNCTION} template
|
|
1942 @item @code{\c}
|
|
1943 @tab @code{CASE} statement template
|
|
1944 @item @code{\f}
|
|
1945 @tab @code{FOR} loop template
|
|
1946 @item @code{\r}
|
|
1947 @tab @code{REPEAT} loop template
|
|
1948 @item @code{\w}
|
|
1949 @tab @code{WHILE} loop template
|
|
1950 @item @code{\i}
|
|
1951 @tab @code{IF} statement template
|
|
1952 @item @code{\elif}
|
|
1953 @tab @code{IF-ELSE} statement template
|
|
1954 @end multitable
|
|
1955
|
|
1956 String abbreviations:
|
|
1957
|
|
1958 @multitable @columnfractions .15 .85
|
|
1959 @item @code{\ap}
|
|
1960 @tab @code{arg_present()}
|
|
1961 @item @code{\b}
|
|
1962 @tab @code{begin}
|
|
1963 @item @code{\cb}
|
|
1964 @tab @code{byte()}
|
|
1965 @item @code{\cc}
|
|
1966 @tab @code{complex()}
|
|
1967 @item @code{\cd}
|
|
1968 @tab @code{double()}
|
|
1969 @item @code{\cf}
|
|
1970 @tab @code{float()}
|
|
1971 @item @code{\cl}
|
|
1972 @tab @code{long()}
|
|
1973 @item @code{\co}
|
|
1974 @tab @code{common}
|
|
1975 @item @code{\cs}
|
|
1976 @tab @code{string()}
|
|
1977 @item @code{\cx}
|
|
1978 @tab @code{fix()}
|
|
1979 @item @code{\e}
|
|
1980 @tab @code{else}
|
|
1981 @item @code{\ec}
|
|
1982 @tab @code{endcase}
|
|
1983 @item @code{\ee}
|
|
1984 @tab @code{endelse}
|
|
1985 @item @code{\ef}
|
|
1986 @tab @code{endfor}
|
|
1987 @item @code{\ei}
|
|
1988 @tab @code{endif else if}
|
|
1989 @item @code{\el}
|
|
1990 @tab @code{endif else}
|
|
1991 @item @code{\en}
|
|
1992 @tab @code{endif}
|
|
1993 @item @code{\er}
|
|
1994 @tab @code{endrep}
|
|
1995 @item @code{\es}
|
|
1996 @tab @code{endswitch}
|
|
1997 @item @code{\ew}
|
|
1998 @tab @code{endwhile}
|
|
1999 @item @code{\g}
|
|
2000 @tab @code{goto,}
|
|
2001 @item @code{\h}
|
|
2002 @tab @code{help,}
|
|
2003 @item @code{\ik}
|
|
2004 @tab @code{if keyword_set() then}
|
|
2005 @item @code{\iap}
|
|
2006 @tab @code{if arg_present() then}
|
|
2007 @item @code{\ine}
|
|
2008 @tab @code{if n_elements() eq 0 then}
|
|
2009 @item @code{\inn}
|
|
2010 @tab @code{if n_elements() ne 0 then}
|
|
2011 @item @code{\k}
|
|
2012 @tab @code{keyword_set()}
|
|
2013 @item @code{\n}
|
|
2014 @tab @code{n_elements()}
|
|
2015 @item @code{\np}
|
|
2016 @tab @code{n_params()}
|
|
2017 @item @code{\oi}
|
|
2018 @tab @code{on_ioerror,}
|
|
2019 @item @code{\or}
|
|
2020 @tab @code{openr,}
|
|
2021 @item @code{\ou}
|
|
2022 @tab @code{openu,}
|
|
2023 @item @code{\ow}
|
|
2024 @tab @code{openw,}
|
|
2025 @item @code{\p}
|
|
2026 @tab @code{print,}
|
|
2027 @item @code{\pt}
|
|
2028 @tab @code{plot,}
|
|
2029 @item @code{\pv}
|
|
2030 @tab @code{ptr_valid()}
|
|
2031 @item @code{\re}
|
|
2032 @tab @code{read,}
|
|
2033 @item @code{\rf}
|
|
2034 @tab @code{readf,}
|
|
2035 @item @code{\rt}
|
|
2036 @tab @code{return}
|
|
2037 @item @code{\ru}
|
|
2038 @tab @code{readu,}
|
|
2039 @item @code{\s}
|
|
2040 @tab @code{size()}
|
|
2041 @item @code{\sc}
|
|
2042 @tab @code{strcompress()}
|
|
2043 @item @code{\sl}
|
|
2044 @tab @code{strlowcase()}
|
|
2045 @item @code{\sm}
|
|
2046 @tab @code{strmid()}
|
|
2047 @item @code{\sn}
|
|
2048 @tab @code{strlen()}
|
|
2049 @item @code{\sp}
|
|
2050 @tab @code{strpos()}
|
|
2051 @item @code{\sr}
|
|
2052 @tab @code{strtrim()}
|
|
2053 @item @code{\st}
|
|
2054 @tab @code{strput()}
|
|
2055 @item @code{\su}
|
|
2056 @tab @code{strupcase()}
|
|
2057 @item @code{\t}
|
|
2058 @tab @code{then}
|
|
2059 @item @code{\u}
|
|
2060 @tab @code{until}
|
|
2061 @item @code{\wc}
|
|
2062 @tab @code{widget_control,}
|
|
2063 @item @code{\wi}
|
|
2064 @tab @code{widget_info()}
|
|
2065 @item @code{\wu}
|
|
2066 @tab @code{writeu,}
|
|
2067 @end multitable
|
|
2068
|
|
2069 @noindent You can easily add your own abbreviations or override existing
|
|
2070 abbrevs with @code{define-abbrev} in your mode hook, using the
|
|
2071 convenience function @code{idlwave-define-abbrev}:
|
|
2072
|
|
2073 @lisp
|
|
2074 (add-hook 'idlwave-mode-hook
|
|
2075 (lambda ()
|
|
2076 (idlwave-define-abbrev "wb" "widget_base()"
|
|
2077 (idlwave-keyword-abbrev 1))
|
|
2078 (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN"
|
|
2079 (idlwave-keyword-abbrev 11))))
|
|
2080 @end lisp
|
|
2081
|
|
2082 Notice how the abbreviation (here @emph{wb}) and its expansion
|
|
2083 (@emph{widget_base()}) are given as arguments, and the single argument to
|
|
2084 @code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to
|
|
2085 move the point upon expansion (in this example, to put it between the
|
|
2086 parentheses).
|
|
2087
|
|
2088 The abbreviations are expanded in upper or lower case, depending upon
|
|
2089 the variables @code{idlwave-abbrev-change-case} and, for reserved word
|
|
2090 templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}).
|
|
2091
|
|
2092 @defopt idlwave-abbrev-start-char (@code{"\"})
|
|
2093 A single character string used to start abbreviations in abbrev mode.
|
|
2094 Beware of common characters which might naturally occur in sequence with
|
|
2095 abbreviation strings.
|
|
2096 @end defopt
|
|
2097
|
|
2098 @defopt idlwave-abbrev-move (@code{t})
|
|
2099 Non-@code{nil} means the abbrev hook can move point, e.g. to end up
|
|
2100 between the parentheses of a function call.
|
|
2101 @end defopt
|
|
2102
|
|
2103 @node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode
|
|
2104 @section Actions
|
|
2105 @cindex Actions
|
|
2106 @cindex Coding standards, enforcing
|
|
2107
|
|
2108 @emph{Actions} are special formatting commands which are executed
|
|
2109 automatically while you write code in order to check the structure of
|
|
2110 the program or to enforce coding standards. Most actions which have
|
|
2111 been implemented in IDLWAVE are turned off by default, assuming that the
|
|
2112 average user wants her code the way she writes it. But if you are a
|
|
2113 lazy typist and want your code to adhere to certain standards, actions
|
|
2114 can be helpful.
|
|
2115
|
|
2116 Actions can be applied in three ways:
|
|
2117
|
|
2118 @itemize @bullet
|
|
2119 @item
|
|
2120 Some actions are applied directly while typing. For example, pressing
|
|
2121 @samp{=} can run a check to make sure that this operator is surrounded
|
|
2122 by spaces and insert these spaces if necessary. Pressing @key{SPC}
|
|
2123 after a reserved word can call a command to change the word to upper
|
|
2124 case.
|
|
2125 @item
|
|
2126 When a line is re-indented with @key{TAB}, actions can be applied to the
|
|
2127 entire line. To enable this, the variable @code{idlwave-do-actions}
|
|
2128 must be non-@code{nil}.
|
|
2129 @item
|
|
2130 @cindex Foreign code, adapting
|
|
2131 @cindex Actions, applied to foreign code
|
|
2132 Actions can also be applied to a larger piece of code, e.g. to convert
|
|
2133 foreign code to your own style. To do this, mark the relevant part of
|
|
2134 the code and execute @kbd{M-x expand-region-abbrevs}. Useful marking
|
|
2135 commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current
|
|
2136 subprogram). @xref{Code Indentation}, for information how to adjust the
|
|
2137 indentation of the code.
|
|
2138 @end itemize
|
|
2139
|
|
2140 @defopt idlwave-do-actions (@code{nil})
|
|
2141 Non-@code{nil} means performs actions when indenting. Individual action
|
|
2142 settings are described below and set separately.
|
|
2143 @end defopt
|
|
2144
|
|
2145 @menu
|
|
2146 * Block Boundary Check:: Is the END statement correct?
|
|
2147 * Padding Operators:: Enforcing space around `=' etc
|
|
2148 * Case Changes:: Enforcing upper case keywords
|
|
2149 @end menu
|
|
2150
|
|
2151 @node Block Boundary Check, Padding Operators, Actions, Actions
|
|
2152 @subsection Block Boundary Check
|
|
2153 @cindex Block boundary check
|
|
2154 @cindex @code{END} type checking
|
|
2155 @cindex @code{END}, automatic insertion
|
|
2156 @cindex @code{END}, expanding
|
|
2157 @cindex Block, closing
|
|
2158 @cindex Closing a block
|
|
2159
|
|
2160 Whenever you type an @code{END} statement, IDLWAVE finds the
|
|
2161 corresponding start of the block and the cursor blinks back to that
|
|
2162 location for a second. If you have typed a specific @code{END}, like
|
|
2163 @code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator
|
|
2164 does not match the type of block it terminates.
|
|
2165
|
|
2166 Set the variable @code{idlwave-expand-generic-end} in order to have all
|
|
2167 generic @code{END} statements automatically expanded to the appropriate
|
|
2168 type. You can also type @kbd{C-c ]} to close the current block by
|
|
2169 inserting the appropriate @code{END} statement.
|
|
2170
|
|
2171 @defopt idlwave-show-block (@code{t})
|
|
2172 Non-@code{nil} means point blinks to block beginning for
|
|
2173 @code{idlwave-show-begin}.
|
|
2174 @end defopt
|
|
2175
|
|
2176 @defopt idlwave-expand-generic-end (@code{t})
|
|
2177 Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc.
|
|
2178 @end defopt
|
|
2179
|
|
2180 @defopt idlwave-reindent-end (@code{t})
|
|
2181 Non-@code{nil} means re-indent line after END was typed.
|
|
2182 @end defopt
|
|
2183
|
|
2184 @node Padding Operators, Case Changes, Block Boundary Check, Actions
|
|
2185 @subsection Padding Operators
|
|
2186 @cindex Padding operators with spaces
|
|
2187 @cindex Operators, padding with spaces
|
|
2188 @cindex Space, around operators
|
|
2189
|
|
2190 Some operators can be automatically surrounded by spaces. This can
|
|
2191 happen when the operator is typed, or later when the line is indented.
|
|
2192 IDLWAVE can pad the operators @samp{<}, @samp{>}, @samp{,}, @samp{=},
|
|
2193 and @samp{->}, as well as the modified assignment operators
|
|
2194 (@samp{AND=}, @samp{OR=}, etc.). This feature is turned off by default.
|
|
2195 If you want to turn it on, customize the variables
|
|
2196 @code{idlwave-surround-by-blank} and @code{idlwave-do-actions} and turn
|
|
2197 both on. You can also define similar actions for other operators by
|
|
2198 using the function @code{idlwave-action-and-binding} in the mode hook.
|
|
2199 For example, to enforce space padding of the @samp{+} and @samp{*}
|
|
2200 operators (outside of strings and comments, of course), try this in
|
|
2201 @file{.emacs}
|
|
2202
|
|
2203 @lisp
|
|
2204 (add-hook 'idlwave-mode-hook
|
|
2205 (lambda ()
|
|
2206 (setq idlwave-surround-by-blank t) ; Turn this type of actions on
|
|
2207 (idlwave-action-and-binding "*" '(idlwave-surround 1 1))
|
|
2208 (idlwave-action-and-binding "+" '(idlwave-surround 1 1))))
|
|
2209 @end lisp
|
|
2210
|
|
2211 Note that the modified assignment operators which begin with a word
|
|
2212 (@samp{AND=}, @samp{OR=}, @samp{NOT=}, etc.) require a leading space to
|
|
2213 be recognized (e.g @code{vAND=4} would be interpreted as a variable
|
|
2214 @code{vAND}). Also note that, since e.g., @code{>} and @code{>=} are
|
|
2215 both valid operators, it is impossible to surround both by blanks while
|
|
2216 they are being typed. Similarly with @code{&} and @code{&&}. For
|
|
2217 these, a compromise is made: the padding is placed on the left, and if
|
|
2218 the longer operator is keyed in, on the right as well (otherwise you
|
|
2219 must insert spaces to pad right yourself, or press simply press Tab to
|
|
2220 repad everything if @code{idlwave-do-actions} is on).
|
|
2221
|
|
2222 @defopt idlwave-surround-by-blank (@code{nil})
|
|
2223 Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil},
|
|
2224 @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->}, and the
|
|
2225 modified assignment operators (@samp{AND=}, @samp{OR=}, etc.) are
|
|
2226 surrounded with spaces by @code{idlwave-surround}.
|
|
2227 @end defopt
|
|
2228
|
|
2229 @defopt idlwave-pad-keyword (@code{t})
|
|
2230 Non-@code{nil} means space-pad the @samp{=} in keyword assignments.
|
|
2231 @end defopt
|
|
2232
|
|
2233 @node Case Changes, , Padding Operators, Actions
|
|
2234 @subsection Case Changes
|
|
2235 @cindex Case changes
|
|
2236 @cindex Upcase, enforcing for reserved words
|
|
2237 @cindex Downcase, enforcing for reserved words
|
|
2238
|
|
2239 Actions can be used to change the case of reserved words or expanded
|
|
2240 abbreviations by customizing the variables
|
|
2241 @code{idlwave-abbrev-change-case} and
|
|
2242 @code{idlwave-reserved-word-upcase}. If you want to change the case of
|
|
2243 additional words automatically, put something like the following into
|
|
2244 your @file{.emacs} file:
|
|
2245
|
|
2246 @lisp
|
|
2247 (add-hook 'idlwave-mode-hook
|
|
2248 (lambda ()
|
|
2249 ;; Capitalize system vars
|
|
2250 (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t)
|
|
2251 ;; Capitalize procedure name
|
|
2252 (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<"
|
|
2253 '(capitalize-word 1) t)
|
|
2254 ;; Capitalize common block name
|
|
2255 (idlwave-action-and-binding "\\<common\\>[ \t]+\\<"
|
|
2256 '(capitalize-word 1) t)))
|
|
2257 @end lisp
|
|
2258
|
|
2259 For more information, see the documentation string for the function
|
|
2260 @code{idlwave-action-and-binding}. For information on controlling the
|
|
2261 case of routines, keywords, classes, and methods as they are completed, see
|
|
2262 @ref{Completion}.
|
|
2263
|
|
2264 @defopt idlwave-abbrev-change-case (@code{nil})
|
|
2265 Non-@code{nil} means all abbrevs will be forced to either upper or lower
|
|
2266 case. Valid values are @code{nil}, @code{t}, and @code{down}.
|
|
2267 @end defopt
|
|
2268
|
|
2269 @defopt idlwave-reserved-word-upcase (@code{nil})
|
|
2270 Non-@code{nil} means reserved words will be made upper case via abbrev
|
|
2271 expansion.
|
|
2272 @end defopt
|
|
2273
|
|
2274
|
|
2275 @node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode
|
|
2276 @section Documentation Header
|
|
2277 @cindex Documentation header
|
|
2278 @cindex DocLib header
|
|
2279 @cindex Modification timestamp
|
|
2280 @cindex Header, for file documentation
|
|
2281 @cindex Timestamp, in doc header.
|
|
2282 @cindex Changelog, in doc header.
|
|
2283
|
|
2284 @kindex C-c C-h
|
|
2285 @kindex C-c C-m
|
|
2286 The command @kbd{C-c C-h} inserts a standard routine header into the
|
|
2287 buffer, with the usual fields for documentation (a different header can
|
|
2288 be specified with @code{idlwave-file-header}). One of the keywords is
|
|
2289 @samp{MODIFICATION HISTORY} under which the changes to a routine can be
|
|
2290 recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION
|
|
2291 HISTORY} of the current routine or file and inserts the user name with a
|
|
2292 timestamp.
|
|
2293
|
|
2294 @defopt idlwave-file-header
|
|
2295 The doc-header template or a path to a file containing it.
|
|
2296 @end defopt
|
|
2297
|
|
2298 @defopt idlwave-header-to-beginning-of-file (@code{nil})
|
|
2299 Non-@code{nil} means the documentation header will always be at start
|
|
2300 of file.
|
|
2301 @end defopt
|
|
2302
|
|
2303 @defopt idlwave-timestamp-hook
|
|
2304 The hook function used to update the timestamp of a function.
|
|
2305 @end defopt
|
|
2306
|
|
2307 @defopt idlwave-doc-modifications-keyword
|
|
2308 The modifications keyword to use with the log documentation commands.
|
|
2309 @end defopt
|
|
2310
|
|
2311 @defopt idlwave-doclib-start
|
|
2312 Regexp matching the start of a document library header.
|
|
2313 @end defopt
|
|
2314
|
|
2315 @defopt idlwave-doclib-end
|
|
2316 Regexp matching the start of a document library header.
|
|
2317 @end defopt
|
|
2318
|
|
2319 @node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode
|
|
2320 @section Motion Commands
|
|
2321 @cindex Motion commands
|
|
2322 @cindex Program structure, moving through
|
|
2323 @cindex Code structure, moving through
|
|
2324 @cindex @file{Func-menu}, XEmacs package
|
|
2325 @cindex @file{Imenu}, Emacs package
|
|
2326 @cindex Function definitions, jumping to
|
|
2327 @cindex Procedure definitions, jumping to
|
|
2328
|
|
2329 IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages
|
|
2330 which make it easy to jump to the definitions of functions and
|
|
2331 procedures in the current file with a pop-up selection. To bind
|
|
2332 @file{Imenu} to a mouse-press, use in your @file{.emacs}:
|
|
2333
|
|
2334 @lisp
|
|
2335 (define-key global-map [S-down-mouse-3] 'imenu)
|
|
2336 @end lisp
|
|
2337
|
|
2338 @cindex @file{Speedbar}, Emacs package
|
|
2339
|
|
2340 In addition, @file{Speedbar} support allows convenient navigation of a
|
|
2341 source tree of IDL routine files, quickly stepping to routine
|
|
2342 definitions. See @code{Tools->Display Speedbar}.
|
|
2343
|
|
2344 Several commands allow you to move quickly through the structure of an
|
|
2345 IDL program:
|
|
2346
|
|
2347 @multitable @columnfractions .15 .85
|
|
2348 @item @kbd{C-M-a}
|
|
2349 @tab Beginning of subprogram
|
|
2350 @item @kbd{C-M-e}
|
|
2351 @tab End of subprogram
|
|
2352 @item @kbd{C-c @{}
|
|
2353 @tab Beginning of block (stay inside the block)
|
|
2354 @item @kbd{C-c @}}
|
|
2355 @tab End of block (stay inside the block)
|
|
2356 @item @kbd{C-M-n}
|
|
2357 @tab Forward block (on same level)
|
|
2358 @item @kbd{C-M-p}
|
|
2359 @tab Backward block (on same level)
|
|
2360 @item @kbd{C-M-d}
|
|
2361 @tab Down block (enters a block)
|
|
2362 @item @kbd{C-M-u}
|
|
2363 @tab Backward up block (leaves a block)
|
|
2364 @item @kbd{C-c C-n}
|
|
2365 @tab Next Statement
|
|
2366 @end multitable
|
|
2367
|
|
2368
|
|
2369 @node Misc Options, , Motion Commands, The IDLWAVE Major Mode
|
|
2370 @section Miscellaneous Options
|
|
2371 @cindex Hooks
|
|
2372
|
|
2373 @defopt idlwave-help-application
|
|
2374 The external application providing reference help for programming.
|
|
2375 @end defopt
|
|
2376
|
|
2377 @defopt idlwave-startup-message (@code{t})
|
|
2378 Non-@code{nil} means display a startup message when @code{idlwave-mode}'
|
|
2379 is first called.
|
|
2380 @end defopt
|
|
2381
|
|
2382 @defopt idlwave-mode-hook
|
|
2383 Normal hook. Executed when a buffer is put into @code{idlwave-mode}.
|
|
2384 @end defopt
|
|
2385
|
|
2386 @defopt idlwave-load-hook
|
|
2387 Normal hook. Executed when @file{idlwave.el} is loaded.
|
|
2388 @end defopt
|
|
2389
|
|
2390 @node The IDLWAVE Shell, Acknowledgements, The IDLWAVE Major Mode, Top
|
|
2391 @chapter The IDLWAVE Shell
|
|
2392 @cindex IDLWAVE shell
|
|
2393 @cindex Major mode, @code{idlwave-shell-mode}
|
|
2394 @cindex IDL, as Emacs subprocess
|
|
2395 @cindex Subprocess of Emacs, IDL
|
|
2396 @cindex Comint, Emacs package
|
|
2397 @cindex Windows
|
|
2398 @cindex MacOS
|
|
2399
|
|
2400 The IDLWAVE shell is an Emacs major mode which permits running the IDL
|
|
2401 program as an inferior process of Emacs, and works closely with the
|
|
2402 IDLWAVE major mode in buffers. It can be used to work with IDL
|
|
2403 interactively, to compile and run IDL programs in Emacs buffers and to
|
|
2404 debug these programs. The IDLWAVE shell is built on @file{comint}, an
|
|
2405 Emacs packages which handles the communication with the IDL program.
|
|
2406 Unfortunately, IDL for Windows does not have command-prompt versions and
|
|
2407 thus do not allow the interaction with Emacs --- so the IDLWAVE shell
|
|
2408 currently only works under Unix and MacOSX.
|
|
2409
|
|
2410 @menu
|
|
2411 * Starting the Shell:: How to launch IDL as a subprocess
|
|
2412 * Using the Shell:: Interactively working with the Shell
|
|
2413 * Commands Sent to the Shell::
|
|
2414 * Debugging IDL Programs::
|
|
2415 * Examining Variables::
|
|
2416 * Custom Expression Examination::
|
|
2417 @end menu
|
|
2418
|
|
2419 @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell
|
|
2420 @section Starting the Shell
|
|
2421 @cindex Starting the shell
|
|
2422 @cindex Shell, starting
|
|
2423 @cindex Dedicated frame, for shell buffer
|
|
2424 @cindex Frame, for shell buffer
|
|
2425 @cindex Subprocess of Emacs, IDL
|
|
2426
|
|
2427 @kindex C-c C-s
|
|
2428 The IDLWAVE shell can be started with the command @kbd{M-x
|
|
2429 idlwave-shell}. In @code{idlwave-mode} the function is bound to
|
|
2430 @kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to
|
|
2431 interact with the shell. If the shell is already running, @kbd{C-c
|
|
2432 C-s} will simply switch to the shell buffer. The command @kbd{C-c
|
|
2433 C-l} (@code{idlwave-shell-recenter-shell-window}) displays the shell
|
|
2434 window without selecting it. The shell can also be started
|
|
2435 automatically when another command tries to send a command to it. To
|
|
2436 enable auto start, set the variable
|
|
2437 @code{idlwave-shell-automatic-start} to @code{t}.
|
|
2438
|
|
2439 In order to create a separate frame for the IDLWAVE shell buffer, call
|
|
2440 @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or
|
|
2441 @kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell
|
|
2442 window, configure the variable
|
|
2443 @code{idlwave-shell-use-dedicated-frame}.
|
|
2444
|
|
2445 To launch a quick IDLWAVE shell directly from a shell prompt without
|
|
2446 an IDLWAVE buffer (e.g., as a replacement for running inside an
|
|
2447 xterm), define a system alias with the following content:
|
|
2448
|
|
2449 @example
|
|
2450 emacs -geometry 80x32 -eval "(idlwave-shell 'quick)"
|
|
2451 @end example
|
|
2452
|
|
2453 Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer
|
|
2454 the Emacs process to run directly inside the terminal window.
|
|
2455
|
|
2456 @cindex ENVI
|
|
2457 @cindex IDL> Prompt
|
|
2458
|
|
2459 To use IDLWAVE with ENVI or other custom packages which change the
|
|
2460 @samp{IDL> } prompt, you must change the
|
|
2461 @code{idlwave-shell-prompt-pattern}, which defaults to @samp{"^ ?IDL>
|
|
2462 "}. Normally, you can just replace the @samp{IDL} in this expression
|
|
2463 with the prompt you see. A suitable pattern which matches the prompt
|
|
2464 for both ENVI and IDL simultaneously is @samp{"^ ?\\(ENVI\\|IDL\\)> "}.
|
|
2465
|
|
2466 @defopt idlwave-shell-explicit-file-name (@file{idl})
|
|
2467 This is the command to run IDL.
|
|
2468 @end defopt
|
|
2469
|
|
2470 @defopt idlwave-shell-command-line-options
|
|
2471 A list of command line options for calling the IDL program.
|
|
2472 @end defopt
|
|
2473
|
|
2474 @defopt idlwave-shell-prompt-pattern
|
|
2475 Regexp to match IDL prompt at beginning of a line.
|
|
2476 @end defopt
|
|
2477
|
|
2478 @defopt idlwave-shell-process-name
|
|
2479 Name to be associated with the IDL process.
|
|
2480 @end defopt
|
|
2481
|
|
2482 @defopt idlwave-shell-automatic-start (@code{nil})
|
|
2483 Non-@code{nil} means attempt to invoke idlwave-shell if not already
|
|
2484 running.
|
|
2485 @end defopt
|
|
2486
|
|
2487 @defopt idlwave-shell-initial-commands
|
|
2488 Initial commands, separated by newlines, to send to IDL.
|
|
2489 @end defopt
|
|
2490
|
|
2491 @defopt idlwave-shell-save-command-history (@code{t})
|
|
2492 Non-@code{nil} means preserve command history between sessions.
|
|
2493 @end defopt
|
|
2494
|
|
2495 @defopt idlwave-shell-command-history-file (@file{~/.idlwave/.idlwhist})
|
|
2496 The file in which the command history of the idlwave shell is saved.
|
|
2497 Unless it's an absolute path, it goes in
|
|
2498 @code{idlwave-config-directory}.
|
|
2499 @end defopt
|
|
2500
|
|
2501 @defopt idlwave-shell-use-dedicated-frame (@code{nil})
|
|
2502 Non-@code{nil} means IDLWAVE should use a special frame to display the
|
|
2503 shell buffer.
|
|
2504 @end defopt
|
|
2505
|
|
2506 @defopt idlwave-shell-use-dedicated-window (@code{nil})
|
|
2507 Non-@code{nil} means use a dedicated window for the shell, taking care
|
|
2508 not it replace it with other buffers.
|
|
2509 @end defopt
|
|
2510
|
|
2511 @defopt idlwave-shell-frame-parameters
|
|
2512 The frame parameters for a dedicated idlwave-shell frame.
|
|
2513 @end defopt
|
|
2514
|
|
2515 @defopt idlwave-shell-raise-frame (@code{t})
|
|
2516 Non-@code{nil} means `idlwave-shell' raises the frame showing the shell
|
|
2517 window.
|
|
2518 @end defopt
|
|
2519
|
|
2520 @defopt idlwave-shell-temp-pro-prefix
|
|
2521 The prefix for temporary IDL files used when compiling regions.
|
|
2522 @end defopt
|
|
2523
|
|
2524 @cindex Hooks
|
|
2525 @defopt idlwave-shell-mode-hook
|
|
2526 Hook for customizing @code{idlwave-shell-mode}.
|
|
2527 @end defopt
|
|
2528
|
|
2529 @node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell
|
|
2530 @section Using the Shell
|
|
2531 @cindex Comint
|
|
2532 @cindex Shell, basic commands
|
|
2533
|
|
2534 The IDLWAVE shell works in the same fashion as other shell modes in
|
|
2535 Emacs. It provides command history, command line editing and job
|
|
2536 control. The @key{UP} and @key{DOWN} arrows cycle through the input
|
|
2537 history just like in an X terminal@footnote{This is different from
|
|
2538 normal Emacs/Comint behavior, but more like an xterm. If you prefer the
|
|
2539 default comint functionality, check the variable
|
|
2540 @code{idlwave-shell-arrows-do-history}.}. The history is preserved
|
|
2541 between emacs and IDL sessions. Here is a list of commonly used
|
|
2542 commands:
|
|
2543
|
|
2544 @multitable @columnfractions .12 .88
|
|
2545 @item @key{UP}, @key{M-p}
|
|
2546 @tab Cycle backwards in input history
|
|
2547 @item @key{DOWN}, @key{M-n}
|
|
2548 @tab Cycle forwards in input history
|
|
2549 @item @kbd{M-r}
|
|
2550 @tab Previous input matching a regexp
|
|
2551 @item @kbd{M-s}
|
|
2552 @tab Next input matching a regexp
|
|
2553 @item @kbd{return}
|
|
2554 @tab Send input or copy line to current prompt
|
|
2555 @item @kbd{C-c C-a}
|
|
2556 @tab Beginning of line; skip prompt
|
|
2557 @item @kbd{C-c C-u}
|
|
2558 @tab Kill input to beginning of line
|
|
2559 @item @kbd{C-c C-w}
|
|
2560 @tab Kill word before cursor
|
|
2561 @item @kbd{C-c C-c}
|
|
2562 @tab Send ^C
|
|
2563 @item @kbd{C-c C-z}
|
|
2564 @tab Send ^Z
|
|
2565 @item @kbd{C-c C-\}
|
|
2566 @tab Send ^\
|
|
2567 @item @kbd{C-c C-o}
|
|
2568 @tab Delete last batch of process output
|
|
2569 @item @kbd{C-c C-r}
|
|
2570 @tab Show last batch of process output
|
|
2571 @item @kbd{C-c C-l}
|
|
2572 @tab List input history
|
|
2573 @end multitable
|
|
2574
|
|
2575 In addition to these standard @file{comint} commands,
|
|
2576 @code{idlwave-shell-mode} provides many of the same commands which
|
|
2577 simplify writing IDL code available in IDLWAVE buffers. This includes
|
|
2578 abbreviations, online help, and completion. See @ref{Routine Info} and
|
|
2579 @ref{Online Help} and @ref{Completion} for more information on these
|
|
2580 commands.
|
|
2581
|
|
2582 @cindex Completion, in the shell
|
|
2583 @cindex Routine info, in the shell
|
|
2584 @cindex Online Help, in the shell
|
|
2585 @multitable @columnfractions .12 .88
|
|
2586 @item @kbd{@key{TAB}}
|
|
2587 @tab Completion of file names (between quotes and after executive
|
|
2588 commands @samp{.run} and @samp{.compile}), routine names, class names,
|
|
2589 keywords, system variables, system variable tags etc.
|
|
2590 (@code{idlwave-shell-complete}).
|
|
2591 @item @kbd{M-@key{TAB}}
|
|
2592 @tab Same as @key{TAB}
|
|
2593 @item @kbd{C-c ?}
|
|
2594 @tab Routine Info display (@code{idlwave-routine-info})
|
|
2595 @item @kbd{M-?}
|
|
2596 @tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp})
|
|
2597 @item @kbd{C-c C-i}
|
|
2598 @tab Update routine info from buffers and shell
|
|
2599 (@code{idlwave-update-routine-info})
|
|
2600 @item @kbd{C-c C-v}
|
|
2601 @tab Find the source file of a routine (@code{idlwave-find-module})
|
|
2602 @item @kbd{C-c C-t}
|
|
2603 @tab Find the source file of a routine in the currently visited file
|
|
2604 (@code{idlwave-find-module-this-file}).
|
|
2605 @item @kbd{C-c =}
|
|
2606 @tab Compile a library routine (@code{idlwave-resolve})
|
|
2607 @end multitable
|
|
2608
|
|
2609 @defopt idlwave-shell-arrows-do-history (@code{t})
|
|
2610 Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command
|
|
2611 history like xterm.
|
|
2612 @end defopt
|
|
2613
|
|
2614 @defopt idlwave-shell-comint-settings
|
|
2615 Alist of special settings for the comint variables in the IDLWAVE Shell.
|
|
2616 @end defopt
|
|
2617
|
|
2618 @defopt idlwave-shell-file-name-chars
|
|
2619 The characters allowed in file names, as a string. Used for file name
|
|
2620 completion.
|
|
2621 @end defopt
|
|
2622
|
|
2623 @defopt idlwave-shell-graphics-window-size
|
|
2624 Size of IDL graphics windows popped up by special IDLWAVE command.
|
|
2625 @end defopt
|
|
2626
|
|
2627 @cindex Input mode
|
|
2628 @cindex Character input mode (Shell)
|
|
2629 @cindex Line input mode (Shell)
|
|
2630 @cindex Magic spells, for input mode
|
|
2631 @cindex Spells, magic
|
|
2632 IDLWAVE works in line input mode: You compose a full command line, using
|
|
2633 all the power Emacs gives you to do this. When you press @key{RET}, the
|
|
2634 whole line is sent to IDL. Sometimes it is necessary to send single
|
|
2635 characters (without a newline), for example when an IDL program is
|
|
2636 waiting for single character input with the @code{GET_KBRD} function.
|
|
2637 You can send a single character to IDL with the command @kbd{C-c C-x}
|
|
2638 (@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y}
|
|
2639 (@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop
|
|
2640 which accepts characters and immediately sends them to IDL. The loop
|
|
2641 can be exited with @kbd{C-g}. It terminates also automatically when the
|
|
2642 current IDL command is finished. Check the documentation of the two
|
|
2643 variables described below for a way to make IDL programs trigger
|
|
2644 automatic switches of the input mode.
|
|
2645
|
|
2646 @defopt idlwave-shell-use-input-mode-magic (@code{nil})
|
|
2647 Non-@code{nil} means IDLWAVE should check for input mode spells in
|
|
2648 output.
|
|
2649 @end defopt
|
|
2650
|
|
2651 @defopt idlwave-shell-input-mode-spells
|
|
2652 The three regular expressions which match the magic spells for input
|
|
2653 modes.
|
|
2654 @end defopt
|
|
2655
|
|
2656 @node Commands Sent to the Shell, Debugging IDL Programs, Using the Shell, The IDLWAVE Shell
|
|
2657 @section Commands Sent to the Shell
|
|
2658 @cindex Commands in shell, showing
|
|
2659 @cindex Showing commands in shell
|
|
2660
|
|
2661 The IDLWAVE buffers and shell interact very closely. In addition to the
|
|
2662 normal commands you enter at the @code{IDL>} prompt, many other special
|
|
2663 commands are sent to the shell, sometimes as a direct result of invoking
|
|
2664 a key command, menu item, or toolbar button, but also automatically, as
|
|
2665 part of the normal flow of information updates between the buffer and
|
|
2666 shell.
|
|
2667
|
|
2668 The commands sent include @code{breakpoint}, @code{.step} and other
|
|
2669 debug commands (@pxref{Debugging IDL Programs}), @code{.run} and other
|
|
2670 compilation statements (@pxref{Compiling Programs}), examination
|
|
2671 commands like @code{print} and @code{help} (@pxref{Examining
|
|
2672 Variables}), and other special purpose commands designed to keep
|
|
2673 information on the running shell current.
|
|
2674
|
|
2675 By default, much of this background shell input and output is hidden
|
|
2676 from the user, but this is configurable. The custom variable
|
|
2677 @code{idlwave-abbrev-show-commands} allows you to configure which
|
|
2678 commands sent to the shell are shown there. For a related customization
|
|
2679 for separating the output of @emph{examine} commands, see @ref{Examining
|
|
2680 Variables}.
|
|
2681
|
|
2682 @defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)})
|
|
2683 A list of command types to echo in the shell when sent. Possible values
|
|
2684 are @code{run} for @code{.run}, @code{.compile} and other run commands,
|
|
2685 @code{misc} for lesser used commands like @code{window},
|
|
2686 @code{retall},@code{close}, etc., @code{breakpoint} for breakpoint
|
|
2687 setting and clearing commands, and @code{debug} for other debug,
|
|
2688 stepping, and continue commands. In addition, if the variable is set to
|
|
2689 the single symbol @code{'everything}, all the copious shell input is
|
|
2690 displayed (which is probably only useful for debugging purposes).
|
|
2691 N.B. For hidden commands which produce output by side-effect, that
|
|
2692 output remains hidden (e.g., stepping through a @code{print} command).
|
|
2693 As a special case, any error message in the output will be displayed
|
|
2694 (e.g., stepping to an error).
|
|
2695 @end defopt
|
|
2696
|
|
2697 @node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell
|
|
2698 @section Debugging IDL Programs
|
|
2699 @cindex Debugging
|
|
2700 @cindex Keybindings for debugging
|
|
2701 @cindex Toolbar
|
|
2702
|
|
2703 Programs can be compiled, run, and debugged directly from the source
|
|
2704 buffer in Emacs, walking through arbitrarily deeply nested code,
|
|
2705 printing expressions and skipping up and down the calling stack along
|
|
2706 the way. IDLWAVE makes compiling and debugging IDL programs far less
|
|
2707 cumbersome by providing a full-featured, key/menu/toolbar-driven
|
|
2708 interface to commands like @code{breakpoint}, @code{.step},
|
|
2709 @code{.run}, etc. It can even perform complex debug operations not
|
|
2710 natively supported by IDL (like continuing to the line at the cursor).
|
|
2711
|
|
2712 The IDLWAVE shell installs key bindings both in the shell buffer and
|
|
2713 in all IDL code buffers of the current Emacs session, so debug
|
|
2714 commands work in both places (in the shell, commands operate on the
|
|
2715 last file compiled). On Emacs versions which support it, a debugging
|
|
2716 toolbar is also installed. The toolbar display can be toggled with
|
|
2717 @kbd{C-c C-d C-t} (@code{idlwave-shell-toggle-toolbar}).
|
|
2718
|
|
2719
|
|
2720 @defopt idlwave-shell-use-toolbar (@code{t})
|
|
2721 Non-@code{nil} means use the debugging toolbar in all IDL related
|
|
2722 buffers.
|
|
2723 @end defopt
|
|
2724
|
|
2725 @menu
|
|
2726 * A Tale of Two Modes::
|
|
2727 * Debug Key Bindings::
|
|
2728 * Breakpoints and Stepping::
|
|
2729 * Compiling Programs::
|
|
2730 * Walking the Calling Stack::
|
|
2731 * Electric Debug Mode::
|
|
2732 @end menu
|
|
2733
|
|
2734
|
|
2735 @node A Tale of Two Modes, Debug Key Bindings, Debugging IDL Programs, Debugging IDL Programs
|
|
2736 @subsection A Tale of Two Modes
|
|
2737 @cindex Electric Debug Mode
|
|
2738 @cindex Debugging Interface
|
|
2739
|
|
2740 The many debugging, compiling, and examination commands provided in
|
|
2741 IDLWAVE are available simultaneously through two different interfaces:
|
|
2742 the original, multi-key command interface, and the new Electric Debug
|
|
2743 Mode. The functionality they offer is similar, but the way you interact
|
|
2744 with them is quite different. The main difference is that, in Electric
|
|
2745 Debug Mode, the source buffers are made read-only, and single
|
|
2746 key-strokes are used to step through, examine expressions, set and
|
|
2747 remove breakpoints, etc. The same variables, prefix arguments, and
|
|
2748 settings apply to both versions, and both can be used interchangeably.
|
|
2749 By default, when breakpoints are hit, Electric Debug Mode is enabled.
|
|
2750 The traditional interface is described first. @xref{Electric Debug
|
|
2751 Mode}, for more on that mode. Note that electric debug mode can be
|
|
2752 prevented from activating automatically by customizing the variable
|
|
2753 @code{idlwave-shell-automatic-electric-debug}.
|
|
2754
|
|
2755 @node Debug Key Bindings, Breakpoints and Stepping, A Tale of Two Modes, Debugging IDL Programs
|
|
2756 @subsection Debug Key Bindings
|
|
2757 @kindex C-c C-d
|
|
2758 @cindex Key bindings
|
|
2759
|
|
2760 The standard debugging key bindings are always available by default on
|
|
2761 the prefix key @kbd{C-c C-d}, so, for example, setting a breakpoint is
|
|
2762 done with @kbd{C-c C-d C-b}, and compiling a source file with @kbd{C-c
|
|
2763 C-d C-c}. You can also easily configure IDLWAVE to use one or more
|
|
2764 modifier keys not in use by other commands, in lieu of the prefix
|
|
2765 @kbd{C-c C-d} (though these bindings will typically also be available
|
|
2766 --- see @code{idlwave-shell-activate-prefix-keybindings}). For
|
|
2767 example, if you include in @file{.emacs}:
|
|
2768
|
|
2769 @lisp
|
|
2770 (setq idlwave-shell-debug-modifiers '(control shift))
|
|
2771 @end lisp
|
|
2772
|
|
2773 @noindent a breakpoint can then be set by pressing @kbd{b} while holding down
|
|
2774 @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a
|
|
2775 source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d},
|
|
2776 etc. In the remainder of this chapter we will assume that the
|
|
2777 @kbd{C-c C-d} bindings are active, but each of these bindings will
|
|
2778 have an equivalent shortcut if modifiers are given in the
|
|
2779 @code{idlwave-shell-debug-modifiers} variable (@pxref{Lesson II --
|
|
2780 Customization}). A much simpler and faster form of debugging for
|
|
2781 running code is also available by default --- see @ref{Electric Debug
|
|
2782 Mode}.
|
|
2783
|
|
2784 @defopt idlwave-shell-prefix-key (@kbd{C-c C-d})
|
|
2785 The prefix key for the debugging map
|
|
2786 @code{idlwave-shell-mode-prefix-map}.
|
|
2787 @end defopt
|
|
2788
|
|
2789 @defopt idlwave-shell-activate-prefix-keybindings (@code{t})
|
|
2790 Non-@code{nil} means debug commands will be bound to the prefix
|
|
2791 key, like @kbd{C-c C-d C-b}.
|
|
2792 @end defopt
|
|
2793
|
|
2794 @defopt idlwave-shell-debug-modifiers (@code{nil})
|
|
2795 List of modifier keys to use for additional, alternative binding of
|
|
2796 debugging commands in the shell and source buffers. Can be one or
|
|
2797 more of @code{control}, @code{meta}, @code{super}, @code{hyper},
|
|
2798 @code{alt}, and @code{shift}.
|
|
2799 @end defopt
|
|
2800
|
|
2801 @node Breakpoints and Stepping, Compiling Programs, Debug Key Bindings, Debugging IDL Programs
|
|
2802 @subsection Breakpoints and Stepping
|
|
2803 @cindex Breakpoints
|
|
2804 @cindex Stepping
|
|
2805 @cindex Execution, controlled
|
|
2806
|
|
2807 @kindex C-c C-d C-b
|
|
2808 @kindex C-c C-d C-b
|
|
2809 IDLWAVE helps you set breakpoints and step through code. Setting a
|
|
2810 breakpoint in the current line of the source buffer is accomplished
|
|
2811 with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a
|
|
2812 prefix arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a
|
|
2813 @code{/ONCE} keyword, meaning that it will be deleted after first use.
|
|
2814 With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}),
|
|
2815 the breakpoint will only be active the @code{nth} time it is hit.
|
|
2816 With a single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt
|
|
2817 for a condition --- an IDL expression to be evaluated and trigger the
|
|
2818 breakpoint only if true. To clear the breakpoint in the current line,
|
|
2819 use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When
|
|
2820 executed from the shell window, the breakpoint where IDL is currently
|
|
2821 stopped will be deleted. To clear all breakpoints, use @kbd{C-c C-d
|
|
2822 C-a} (@code{idlwave-clear-all-bp}). Breakpoints can also be disabled
|
|
2823 and re-enabled: @kbd{C-c C-d C-\}
|
|
2824 (@code{idlwave-shell-toggle-enable-current-bp}).
|
|
2825
|
|
2826 Breakpoint lines are highlighted or indicated with an icon in the source
|
|
2827 code (different icons for conditional, after, and other break types).
|
|
2828 Disabled breakpoints are @emph{grayed out} by default. Note that IDL
|
|
2829 places breakpoints as close as possible on or after the line you
|
|
2830 specify. IDLWAVE queries the shell for the actual breakpoint location
|
|
2831 which was set, so the exact line you specify may not be marked. You can
|
|
2832 re-sync the breakpoint list and update the display at any time (e.g., if
|
|
2833 you add or remove some on the command line) using @kbd{C-c C-d C-l}.
|
|
2834
|
|
2835 In recent IDLWAVE versions, the breakpoint line is highlighted when the
|
|
2836 mouse is moved over it, and a tooltip pops up describing the break
|
|
2837 details. @kbd{Mouse-3} on the breakpoint line pops up a menu of
|
|
2838 breakpoint actions, including clearing, disabling, and adding or
|
|
2839 changing break conditions or ``after'' break count.
|
|
2840
|
|
2841 Once the program has stopped somewhere, you can step through it. The
|
|
2842 most important stepping commands are @kbd{C-c C-d C-s} to execute one
|
|
2843 line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line,
|
|
2844 treating procedure and function calls as a single step ("step over");
|
|
2845 @kbd{C-c C-d C-h} to continue execution to the line at the cursor and
|
|
2846 @kbd{C-c C-d C-r} to continue execution. @xref{Commands Sent to the
|
|
2847 Shell}, for information on displaying or hiding the breakpoint and
|
|
2848 stepping commands the shell receives. Here is a summary of the
|
|
2849 breakpoint and stepping commands:
|
|
2850
|
|
2851 @multitable @columnfractions .23 .77
|
|
2852 @item @kbd{C-c C-d C-b}
|
|
2853 @tab Set breakpoint (@code{idlwave-shell-break-here})
|
|
2854 @item @kbd{C-c C-d C-i}
|
|
2855 @tab Set breakpoint in module named here (@code{idlwave-shell-break-in})
|
|
2856 @item @kbd{C-c C-d C-d}
|
|
2857 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp})
|
|
2858 @item @kbd{C-c C-d C-a}
|
|
2859 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp})
|
|
2860 @item @kbd{C-c C-d [}
|
|
2861 @tab Go to the previous breakpoint (@code{idlwave-shell-goto-previous-bp})
|
|
2862 @item @kbd{C-c C-d ]}
|
|
2863 @tab Go to the next breakpoint (@code{idlwave-shell-goto-next-bp})
|
|
2864 @item @kbd{C-c C-d C-\}
|
|
2865 @tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp})
|
|
2866 @item @kbd{C-c C-d C-j}
|
|
2867 @tab Set a breakpoint at the beginning of the enclosing routine.
|
|
2868 @item @kbd{C-c C-d C-s}
|
|
2869 @tab Step, into function calls (@code{idlwave-shell-step})
|
|
2870 @item @kbd{C-c C-d C-n}
|
|
2871 @tab Step, over function calls (@code{idlwave-shell-stepover})
|
|
2872 @item @kbd{C-c C-d C-k}
|
|
2873 @tab Skip one statement (@code{idlwave-shell-skip})
|
|
2874 @item @kbd{C-c C-d C-u}
|
|
2875 @tab Continue to end of block (@code{idlwave-shell-up})
|
|
2876 @item @kbd{C-c C-d C-m}
|
|
2877 @tab Continue to end of function (@code{idlwave-shell-return})
|
|
2878 @item @kbd{C-c C-d C-o}
|
|
2879 @tab Continue past end of function (@code{idlwave-shell-out})
|
|
2880 @item @kbd{C-c C-d C-h}
|
|
2881 @tab Continue to line at cursor position (@code{idlwave-shell-to-here})
|
|
2882 @item @kbd{C-c C-d C-r}
|
|
2883 @tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont})
|
|
2884 @item @kbd{C-c C-d C-up}
|
|
2885 @tab Show higher level in calling stack (@code{idlwave-shell-stack-up})
|
|
2886 @item @kbd{C-c C-d C-down}
|
|
2887 @tab Show lower level in calling stack (@code{idlwave-shell-stack-down})
|
|
2888 @end multitable
|
|
2889
|
|
2890 All of these commands have equivalents in Electric Debug Mode, which
|
|
2891 provides faster single-key access (@pxref{Electric Debug Mode}).
|
|
2892
|
|
2893 The line where IDL is currently stopped, at breakpoints, halts, and
|
|
2894 errors, etc., is marked with a color overlay or arrow, depending on the
|
|
2895 setting in @code{idlwave-shell-mark-stop-line}. If an overlay face is
|
|
2896 used to mark the stop line (as it is by default), when stepping through
|
|
2897 code, the face color is temporarily changed to gray, until IDL completes
|
|
2898 the next command and moves to the new line.
|
|
2899
|
|
2900 @defopt idlwave-shell-mark-breakpoints (@code{t})
|
|
2901 Non-@code{nil} means mark breakpoints in the source file buffers. The
|
|
2902 value indicates the preferred method. Valid values are @code{nil},
|
|
2903 @code{t}, @code{face}, and @code{glyph}.
|
|
2904 @end defopt
|
|
2905
|
|
2906 @defopt idlwave-shell-breakpoint-face
|
|
2907 The face for breakpoint lines in the source code if
|
|
2908 @code{idlwave-shell-mark-breakpoints} has the value @code{face}.
|
|
2909 @end defopt
|
|
2910
|
|
2911 @defopt idlwave-shell-breakpoint-popup-menu (@code{t})
|
|
2912 Whether to pop-up a menu and present a tooltip description on
|
|
2913 breakpoint lines.
|
|
2914 @end defopt
|
|
2915
|
|
2916 @defopt idlwave-shell-mark-stop-line (@code{t})
|
|
2917 Non-@code{nil} means mark the source code line where IDL is currently
|
|
2918 stopped. The value specifies the preferred method. Valid values are
|
|
2919 @code{nil}, @code{t}, @code{arrow}, and @code{face}.
|
|
2920 @end defopt
|
|
2921
|
|
2922 @defopt idlwave-shell-overlay-arrow (@code{">"})
|
|
2923 The overlay arrow to display at source lines where execution halts, if
|
|
2924 configured in @code{idlwave-shell-mark-stop-line}.
|
|
2925 @end defopt
|
|
2926
|
|
2927 @defopt idlwave-shell-stop-line-face
|
|
2928 The face which highlights the source line where IDL is stopped, if
|
|
2929 configured in @code{idlwave-shell-mark-stop-line}.
|
|
2930 @end defopt
|
|
2931
|
|
2932
|
|
2933 @node Compiling Programs, Walking the Calling Stack, Breakpoints and Stepping, Debugging IDL Programs
|
|
2934 @subsection Compiling Programs
|
|
2935 @cindex Compiling programs
|
|
2936 @cindex Programs, compiling
|
|
2937 @cindex Default command line, executing
|
|
2938 @cindex Executing a default command line
|
|
2939
|
|
2940 @kindex C-c C-d C-c
|
|
2941 In order to compile the current buffer under the IDLWAVE shell, press
|
|
2942 @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the
|
|
2943 current buffer and then sends the command @samp{.run path/to/file} to the
|
|
2944 shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in
|
|
2945 which case the most recently compiled buffer will be saved and
|
|
2946 re-compiled.
|
|
2947
|
|
2948 When developing or debugging a program, it is often necessary to execute
|
|
2949 the same command line many times. A convenient way to do this is
|
|
2950 @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}).
|
|
2951 This command first resets IDL from a state of interrupted execution by
|
|
2952 closing all files and returning to the main interpreter level. Then a
|
|
2953 default command line is send to the shell. To edit the default command
|
|
2954 line, call @code{idlwave-shell-execute-default-command-line} with a
|
|
2955 prefix argument: @kbd{C-u C-c C-d C-y}. If no default command line has
|
|
2956 been set (or you give two prefix arguments), the last command on the
|
|
2957 @code{comint} input history is sent.
|
|
2958
|
|
2959 @kindex C-c C-d C-e
|
|
2960 @cindex Compiling regions
|
|
2961 For quickly compiling and running the currently marked region as a main
|
|
2962 level program @kbd{C-c C-d C-e} (@code{idlwave-shell-run-region}) is
|
|
2963 very useful. A temporary file is created holding the contents of the
|
|
2964 current region (with @code{END} appended), and run from the shell.
|
|
2965
|
|
2966 @node Walking the Calling Stack, Electric Debug Mode, Compiling Programs, Debugging IDL Programs
|
|
2967 @subsection Walking the Calling Stack
|
|
2968 @cindex Calling stack, walking
|
|
2969
|
|
2970 While debugging a program, it can be very useful to check the context in
|
|
2971 which the current routine was called, for instance to help understand
|
|
2972 the value of the arguments passed. To do so conveniently you need to
|
|
2973 examine the calling stack. If execution is stopped somewhere deep in a
|
|
2974 program, you can use the commands @kbd{C-c C-d C-@key{UP}}
|
|
2975 (@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}}
|
|
2976 (@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons,
|
|
2977 to move up or down through the calling stack. The mode line of the
|
|
2978 shell window will indicate the position within the stack with a label
|
|
2979 like @samp{[-3:MYPRO]}. The line of IDL code at that stack position
|
|
2980 will be highlighted. If you continue execution, IDLWAVE will
|
|
2981 automatically return to the current level. @xref{Examining Variables},
|
|
2982 for information how to examine the value of variables and expressions on
|
|
2983 higher calling stack levels.
|
|
2984
|
|
2985 @html
|
|
2986 <A NAME="EDEBUG"></A>
|
|
2987 @end html
|
|
2988 @node Electric Debug Mode, , Walking the Calling Stack, Debugging IDL Programs
|
|
2989 @subsection Electric Debug Mode
|
|
2990 @cindex Electric Debug Mode
|
|
2991 @cindex @samp{*Debugging*}
|
|
2992
|
|
2993 Even with a convenient debug key prefix enabled, repetitive stepping,
|
|
2994 variable examination (@pxref{Examining Variables}), and other debugging
|
|
2995 activities can be awkward and slow using commands which require multiple
|
|
2996 keystrokes. Luckily, there's a better way, inspired by the lisp e-debug
|
|
2997 mode, and available through the @emph{Electric Debug Mode}. By default,
|
|
2998 as soon as a breakpoint is hit, this minor mode is enabled. The buffer
|
|
2999 showing the line where execution has halted is switched to Electric
|
|
3000 Debug Mode. This mode is visible as @samp{*Debugging*} in the mode
|
|
3001 line, and a different face (violet by default, if color is available)
|
|
3002 for the line stopped at point. The buffer is made read-only and
|
|
3003 single-character bindings for the most commonly used debugging commands
|
|
3004 are enabled. These character commands (a list of which is available
|
|
3005 with @kbd{C-?}) are:
|
|
3006
|
|
3007 @multitable @columnfractions .2 .8
|
|
3008 @item @kbd{a}
|
|
3009 @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp})
|
|
3010 @item @kbd{b}
|
|
3011 @tab Set breakpoint, @kbd{C-u b} for a conditional break, @kbd{C-n b} for nth hit (@code{idlwave-shell-break-here})
|
|
3012 @item @kbd{d}
|
|
3013 @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp})
|
|
3014 @item @kbd{e}
|
|
3015 @tab Prompt for expression to print (@code{idlwave-shell-clear-current-bp}).
|
|
3016 @item @kbd{h}
|
|
3017 @tab Continue to the line at cursor position (@code{idlwave-shell-to-here})
|
|
3018 @item @kbd{i}
|
|
3019 @tab Set breakpoint in module named here (@code{idlwave-shell-break-in})
|
|
3020 @item @kbd{[}
|
|
3021 @tab Go to the previous breakpoint in the file (@code{idlwave-shell-goto-previous-bp})
|
|
3022 @item @kbd{]}
|
|
3023 @tab Go to the next breakpoint in the file
|
|
3024 (@code{idlwave-shell-goto-next-bp})
|
|
3025 @item @kbd{\}
|
|
3026 @tab Disable/Enable current breakpoint (@code{idlwave-shell-toggle-enable-current-bp})
|
|
3027 @item @kbd{j}
|
|
3028 @tab Set breakpoint at beginning of enclosing routine (@code{idlwave-shell-break-this-module})
|
|
3029 @item @kbd{k}
|
|
3030 @tab Skip one statement (@code{idlwave-shell-skip})
|
|
3031 @item @kbd{m}
|
|
3032 @tab Continue to end of function (@code{idlwave-shell-return})
|
|
3033 @item @kbd{n}
|
|
3034 @tab Step, over function calls (@code{idlwave-shell-stepover})
|
|
3035 @item @kbd{o}
|
|
3036 @tab Continue past end of function (@code{idlwave-shell-out})
|
|
3037 @item @kbd{p}
|
|
3038 @tab Print expression near point or in region with @kbd{C-u p} (@code{idlwave-shell-print})
|
|
3039 @item @kbd{q}
|
|
3040 @tab End the debugging session and return to the Shell's main level
|
|
3041 (@code{idlwave-shell-retall})
|
|
3042 @item @kbd{r}
|
|
3043 @tab Continue execution to next breakpoint, if any (@code{idlwave-shell-cont})
|
|
3044 @item @kbd{s} or @kbd{@key{SPACE}}
|
|
3045 @tab Step, into function calls (@code{idlwave-shell-step})
|
|
3046 @item @kbd{t}
|
|
3047 @tab Print a calling-level traceback in the shell
|
|
3048 @item @kbd{u}
|
|
3049 @tab Continue to end of block (@code{idlwave-shell-up})
|
|
3050 @item @kbd{v}
|
|
3051 @tab Turn Electric Debug Mode off
|
|
3052 (@code{idlwave-shell-electric-debug-mode})
|
|
3053 @item @kbd{x}
|
|
3054 @tab Examine expression near point (or in region with @kbd{C-u x})
|
|
3055 with shortcut of examine type.
|
|
3056 @item @kbd{z}
|
|
3057 @tab Reset IDL (@code{idlwave-shell-reset})
|
|
3058 @item @kbd{+} or @kbd{=}
|
|
3059 @tab Show higher level in calling stack (@code{idlwave-shell-stack-up})
|
|
3060 @item @kbd{-} or @kbd{_}
|
|
3061 @tab Show lower level in calling stack (@code{idlwave-shell-stack-down})
|
|
3062 @item @kbd{?}
|
|
3063 @tab Help on expression near point or in region with @kbd{C-u ?}
|
|
3064 (@code{idlwave-shell-help-expression})
|
|
3065 @item @kbd{C-?}
|
|
3066 @tab Show help on the commands available.
|
|
3067 @end multitable
|
|
3068
|
|
3069 Most single-character electric debug bindings use the final keystroke
|
|
3070 of the equivalent multiple key commands (which are of course also
|
|
3071 still available), but some differ (e.g. @kbd{e},@kbd{t},@kbd{q},@kbd{x}).
|
|
3072 Some have additional convenience bindings (like @kbd{@key{SPACE}} for
|
|
3073 stepping). All prefix and other argument options described in this
|
|
3074 section for the commands invoked by electric debug bindings are still
|
|
3075 valid. For example, @kbd{C-u b} sets a conditional breakpoint, just
|
|
3076 as it did with @kbd{C-u C-c C-d C-b}.
|
|
3077
|
|
3078 You can toggle the electric debug mode at any time in a buffer using
|
|
3079 @kbd{C-c C-d C-v} (@kbd{v} to turn it off while in the mode), or from
|
|
3080 the Debug menu. Normally the mode will be enabled and disabled at the
|
|
3081 appropriate times, but occasionally you might want to edit a file
|
|
3082 while still debugging it, or switch to the mode for conveniently
|
|
3083 setting lots of breakpoints.
|
|
3084
|
|
3085 To quickly abandon a debugging session and return to normal editing at
|
|
3086 the Shell's main level, use @kbd{q} (@code{idlwave-shell-retall}).
|
|
3087 This disables electric debug mode in all IDLWAVE buffers@footnote{Note
|
|
3088 that this binding is not symmetric: @kbd{C-c C-d C-q} is bound to
|
|
3089 @code{idlwave-shell-quit}, which quits your IDL session.}. Help is
|
|
3090 available for the command shortcuts with @kbd{C-?}. If you find this
|
|
3091 mode gets in your way, you can keep it from automatically activating
|
|
3092 by setting the variable @code{idlwave-shell-automatic-electric-debug}
|
|
3093 to @code{nil}, or @code{'breakpoint}. If you'd like the convenient
|
|
3094 electric debug shortcuts available also when run-time errors are
|
|
3095 encountered, set to @code{t}.
|
|
3096
|
|
3097 @defopt idlwave-shell-automatic-electric-debug (@code{'breakpoint})
|
|
3098 Whether to enter electric debug mode automatically when a breakpoint
|
|
3099 or run-time error is encountered, and then disable it in all buffers
|
|
3100 when the $MAIN$ level is reached (either through normal program
|
|
3101 execution, or retall). In addition to @code{nil} for never, and
|
|
3102 @code{t} for both breakpoints and errors, this can be
|
|
3103 @code{'breakpoint} (the default) to enable it only at breakpoint
|
|
3104 halts.
|
|
3105 @end defopt
|
|
3106
|
|
3107 @defopt idlwave-shell-electric-stop-color (Violet)
|
|
3108 Default color of the stopped line overlay when in electric debug mode.
|
|
3109 @end defopt
|
|
3110
|
|
3111 @defopt idlwave-shell-electric-stop-line-face
|
|
3112 The face to use for the stopped line. Defaults to a face similar to the
|
|
3113 modeline, with color @code{idlwave-shell-electric-stop-color}.
|
|
3114 @end defopt
|
|
3115
|
|
3116 @defopt idlwave-shell-electric-zap-to-file (@code{t})
|
|
3117 If set, when entering electric debug mode, select the window displaying
|
|
3118 the file where point is stopped. This takes point away from the shell
|
|
3119 window, but is useful for immediate stepping, etc.
|
|
3120 @end defopt
|
|
3121
|
|
3122 @html
|
|
3123 <A NAME="EXAMINE"></A>
|
|
3124 @end html
|
|
3125 @node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell
|
|
3126 @section Examining Variables
|
|
3127 @cindex @code{PRINT} expressions
|
|
3128 @cindex @code{HELP}, on expressions
|
|
3129 @cindex Expressions, printing & help
|
|
3130 @cindex Examining expressions
|
|
3131 @cindex Printing expressions
|
|
3132 @cindex Mouse binding to print expressions
|
|
3133
|
|
3134 @kindex C-c C-d C-p
|
|
3135 Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)},
|
|
3136 and similar statements to remind yourself of the
|
|
3137 type/size/structure/value/etc. of variables and expressions in your code
|
|
3138 or at the command line? IDLWAVE has a suite of special commands to
|
|
3139 automate these types of variable or expression examinations. They work
|
|
3140 by sending statements to the shell formatted to include the indicated
|
|
3141 expression, and can be accessed in several ways.
|
|
3142
|
|
3143 These @emph{examine} commands can be used in the shell or buffer at any
|
|
3144 time (as long as the shell is running), and are very useful when
|
|
3145 execution is stopped in a buffer due to a triggered breakpoint or error,
|
|
3146 or while composing a long command in the IDLWAVE shell. In the latter
|
|
3147 case, the command is sent to the shell and its output is visible, but
|
|
3148 point remains unmoved in the command being composed --- you can inspect
|
|
3149 the constituents of a command you're building without interrupting the
|
|
3150 process of building it! You can even print arbitrary expressions from
|
|
3151 older input or output further up in the shell window --- any expression,
|
|
3152 variable, number, or function you see can be examined.
|
|
3153
|
|
3154 If the variable @code{idlwave-shell-separate-examine-output} is
|
|
3155 non-@code{nil} (the default), all examine output will be sent to a
|
|
3156 special @file{*Examine*} buffer, rather than the shell. The output of
|
|
3157 prior examine commands is saved in this buffer. In this buffer @key{c}
|
|
3158 clears the contents, and @key{q} hides the buffer.
|
|
3159
|
|
3160 The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to
|
|
3161 print the expression at point, and @kbd{C-c C-d ?}, to invoke help on
|
|
3162 this expression@footnote{Available as @kbd{p} and @kbd{?} in Electric
|
|
3163 Debug Mode (@pxref{Electric Debug Mode})}. The expression at point is
|
|
3164 either an array expression or a function call, or the contents of a pair
|
|
3165 of parentheses. The chosen expression is highlighted, and
|
|
3166 simultaneously the resulting output is highlighted in the shell or
|
|
3167 separate output buffer. Calling the above commands with a prefix
|
|
3168 argument will use the current region as expression instead of using the
|
|
3169 one at point. which can be useful for examining complicated, multi-line
|
|
3170 expressions. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will
|
|
3171 prompt for an expression to print directly. By default, when invoking
|
|
3172 print, only an initial portion of long arrays will be printed, up to
|
|
3173 @code{idlwave-shell-max-print-length}.
|
|
3174
|
|
3175 For added speed and convenience, there are mouse bindings which allow
|
|
3176 you to click on expressions and examine their values. Use
|
|
3177 @kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke
|
|
3178 help (i.e. you need to hold down @key{META} and @key{CONTROL} while
|
|
3179 clicking with the middle mouse button). If you simply click, the
|
|
3180 nearest expression will be selected in the same manner as described
|
|
3181 above. You can also @emph{drag} the mouse in order to highlight
|
|
3182 exactly the specific expression or sub-expression you want to examine.
|
|
3183 For custom expression examination, and the powerful customizable
|
|
3184 pop-up examine selection, @xref{Custom Expression Examination}.
|
|
3185
|
|
3186 @cindex Printing expressions, on calling stack
|
|
3187 @cindex Restrictions for expression printing
|
|
3188 The same variable inspection commands work both in the IDL Shell and
|
|
3189 IDLWAVE buffers, and even for variables at higher levels of the calling
|
|
3190 stack. For instance, if you're stopped at a breakpoint in a routine,
|
|
3191 you can examine the values of variables and expressions inside its
|
|
3192 calling routine, and so on, all the way up through the calling stack.
|
|
3193 Simply step up the stack, and print variables as you see them
|
|
3194 (@pxref{Walking the Calling Stack}, for information on stepping back
|
|
3195 through the calling stack). The following restrictions apply for all
|
|
3196 levels except the current:
|
|
3197
|
|
3198 @itemize @bullet
|
|
3199 @item
|
|
3200 Array expressions must use the @samp{[ ]} index delimiters. Identifiers
|
|
3201 with a @samp{( )} will be interpreted as function calls.
|
|
3202 @item
|
|
3203 @cindex ROUTINE_NAMES, IDL procedure
|
|
3204 N.B.: printing values of expressions on higher levels of the calling
|
|
3205 stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES},
|
|
3206 which may or may not be available in future versions of IDL. Caveat
|
|
3207 Examinor.
|
|
3208 @end itemize
|
|
3209
|
|
3210 @defopt idlwave-shell-expression-face
|
|
3211 The face for @code{idlwave-shell-expression-overlay}.
|
|
3212 Allows you to choose the font, color and other properties for
|
|
3213 the expression printed by IDL.
|
|
3214 @end defopt
|
|
3215
|
|
3216 @defopt idlwave-shell-output-face
|
|
3217 The face for @code{idlwave-shell-output-overlay}.
|
|
3218 Allows to choose the font, color and other properties for the most
|
|
3219 recent output of IDL when examining an expression."
|
|
3220 @end defopt
|
|
3221
|
|
3222 @defopt idlwave-shell-separate-examine-output (@code{t})
|
|
3223 If non-@code{nil}, re-direct the output of examine commands to a special
|
|
3224 @file{*Examine*} buffer, instead of in the shell itself.
|
|
3225 @end defopt
|
|
3226
|
|
3227 @defopt idlwave-shell-max-print-length (200)
|
|
3228 The maximum number of leading array entries to print, when examining
|
|
3229 array expressions.
|
|
3230 @end defopt
|
|
3231
|
|
3232 @node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell
|
|
3233 @section Custom Expression Examination
|
|
3234 @cindex Expressions, custom examination
|
|
3235 @cindex Custom expression examination
|
|
3236
|
|
3237 The variety of possible variable and expression examination commands is
|
|
3238 endless (just look, for instance, at the keyword list to
|
|
3239 @code{widget_info()}). Rather than attempt to include them all, IDLWAVE
|
|
3240 provides two easy methods to customize your own commands, with a special
|
|
3241 mouse examine command, and two macros for generating your own examine
|
|
3242 key and mouse bindings.
|
|
3243
|
|
3244 The most powerful and flexible mouse examine command of all is
|
|
3245 available on @kbd{C-S-Mouse-2}. Just as for all the other mouse
|
|
3246 examine commands, it permits click or drag expression selection, but
|
|
3247 instead of sending hard-coded commands to the shell, it pops-up a
|
|
3248 customizable selection list of examine functions to choose among,
|
|
3249 configured with the @code{idlwave-shell-examine-alist}
|
|
3250 variable@footnote{In Electric Debug Mode (@pxref{Electric Debug
|
|
3251 Mode}), the key @kbd{x} provides a single-character shortcut interface
|
|
3252 to the same examine functions for the expression at point or marked by
|
|
3253 the region.}. This variable is a list of key-value pairs (an
|
|
3254 @emph{alist} in Emacs parlance), where the key gives a name to be
|
|
3255 shown for the examine command, and the value is the command strings
|
|
3256 itself, in which the text @code{___} (three underscores) will be
|
|
3257 replaced by the selected expression before being sent to the shell.
|
|
3258 An example might be key @code{Structure Help} with value
|
|
3259 @code{help,___,/STRUCTURE}. In that case, you'd be prompted with
|
|
3260 @emph{Structure Help}, which might send something like
|
|
3261 @code{help,var,/STRUCTURE} to the shell for output.
|
|
3262 @code{idlwave-shell-examine-alist} comes configured by default with a
|
|
3263 large list of examine commands, but you can easily customize it to add
|
|
3264 your own.
|
|
3265
|
|
3266 In addition to configuring the functions available to the pop-up mouse
|
|
3267 command, you can easily create your own customized bindings to inspect
|
|
3268 expressions using the two convenience macros
|
|
3269 @code{idlwave-shell-examine} and @code{idlwave-shell-mouse-examine}.
|
|
3270 These create keyboard or mouse-based custom inspections of variables,
|
|
3271 sharing all the same properties of the built-in examine commands.
|
|
3272 Both functions take a single string argument sharing the syntax of the
|
|
3273 @code{idlwave-shell-examine-alist} values, e.g.:
|
|
3274
|
|
3275 @lisp
|
|
3276 (add-hook 'idlwave-shell-mode-hook
|
|
3277 (lambda ()
|
|
3278 (idlwave-shell-define-key-both [s-down-mouse-2]
|
|
3279 (idlwave-shell-mouse-examine
|
|
3280 "print, size(___,/DIMENSIONS)"))
|
|
3281 (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
|
|
3282 "print, size(___,/DIMENSIONS)"))
|
|
3283 (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
|
|
3284 "print,size(___,/TNAME)"))
|
|
3285 (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
|
|
3286 "help,___,/STRUCTURE"))))
|
|
3287 @end lisp
|
|
3288
|
|
3289 @noindent Now pressing @key{f9}, or middle-mouse dragging with the
|
|
3290 @key{SUPER} key depressed, will print the dimensions of the nearby or
|
|
3291 highlighted expression. Pressing @key{f10} will give the type string,
|
|
3292 and @key{f11} will show the contents of a nearby structure. As you can
|
|
3293 see, the possibilities are only marginally finite.
|
|
3294
|
|
3295 @defopt idlwave-shell-examine-alist
|
|
3296 An alist of examine commands in which the keys name the command and
|
|
3297 are displayed in the selection pop-up, and the values are custom IDL
|
|
3298 examine command strings to send, after all instances of @code{___}
|
|
3299 (three underscores) are replaced by the indicated expression.
|
|
3300 @end defopt
|
|
3301
|
|
3302 @node Acknowledgements, Sources of Routine Info, The IDLWAVE Shell, Top
|
|
3303 @chapter Acknowledgements
|
|
3304 @cindex Acknowledgements
|
|
3305 @cindex Maintainer, of IDLWAVE
|
|
3306 @cindex Authors, of IDLWAVE
|
|
3307 @cindex Contributors, to IDLWAVE
|
|
3308 @cindex Email address, of Maintainer
|
|
3309 @cindex Thanks
|
|
3310
|
|
3311 @noindent
|
|
3312 The main contributors to the IDLWAVE package have been:
|
|
3313
|
|
3314 @itemize @minus
|
|
3315 @item
|
|
3316 @uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author.
|
|
3317 Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them
|
|
3318 for several years.
|
|
3319
|
|
3320 @item
|
|
3321 @uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge
|
|
3322 of the package from version 3.0, during which time he overhauled almost
|
|
3323 everything, modernized IDLWAVE with many new features, and developed the
|
|
3324 manual.
|
|
3325
|
|
3326 @item
|
|
3327 @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current
|
|
3328 maintainer, as of version 4.10, helped shape object method completion
|
|
3329 and most new features introduced in versions 4.x, and introduced many
|
|
3330 new features for IDLWAVE versions 5.x and 6.x.
|
|
3331 @end itemize
|
|
3332
|
|
3333 @noindent
|
|
3334 The following people have also contributed to the development of IDLWAVE
|
|
3335 with patches, ideas, bug reports and suggestions.
|
|
3336
|
|
3337 @itemize @minus
|
|
3338 @item
|
|
3339 Ulrik Dickow <dickow__at__nbi.dk>
|
|
3340 @item
|
|
3341 Eric E. Dors <edors__at__lanl.gov>
|
|
3342 @item
|
|
3343 Stein Vidar H. Haugan <s.v.h.haugan__at__astro.uio.no>
|
|
3344 @item
|
|
3345 David Huenemoerder <dph__at__space.mit.edu>
|
|
3346 @item
|
|
3347 Kevin Ivory <Kevin.Ivory__at__linmpi.mpg.de>
|
|
3348 @item
|
|
3349 Dick Jackson <dick__at__d-jackson.com>
|
|
3350 @item
|
|
3351 Xuyong Liu <liu__at__stsci.edu>
|
|
3352 @item
|
|
3353 Simon Marshall <Simon.Marshall__at__esrin.esa.it>
|
|
3354 @item
|
|
3355 Craig Markwardt <craigm__at__cow.physics.wisc.edu>
|
|
3356 @item
|
|
3357 Laurent Mugnier <mugnier__at__onera.fr>
|
|
3358 @item
|
|
3359 Lubos Pochman <lubos__at__rsinc.com>
|
|
3360 @item
|
|
3361 Bob Portmann <portmann__at__al.noaa.gov>
|
|
3362 @item
|
|
3363 Patrick M. Ryan <pat__at__jaameri.gsfc.nasa.gov>
|
|
3364 @item
|
|
3365 Marty Ryba <ryba__at__ll.mit.edu>
|
|
3366 @item
|
|
3367 Phil Williams <williams__at__irc.chmcc.org>
|
|
3368 @item
|
|
3369 Phil Sterne <sterne__at__dublin.llnl.gov>
|
|
3370 @item
|
|
3371 Paul Sorenson <aardvark62__at__msn.com>
|
|
3372 @end itemize
|
|
3373
|
|
3374 Doug Dirks was instrumental in providing the crucial IDL XML catalog to
|
|
3375 support HTML help with IDL v6.2 and later, and Ali Bahrami provided
|
|
3376 scripts and documentation to interface with the IDL Assistant.
|
|
3377
|
|
3378 @noindent
|
|
3379 Thanks to everyone!
|
|
3380
|
|
3381 @node Sources of Routine Info, HTML Help Browser Tips, Acknowledgements, Top
|
|
3382 @appendix Sources of Routine Info
|
|
3383
|
|
3384 @cindex Sources of routine information
|
|
3385 In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE
|
|
3386 displays the calling sequence and keywords of routines, and completes
|
|
3387 routine names and keywords. For these features to work, IDLWAVE must
|
|
3388 know about the accessible routines.
|
|
3389
|
|
3390 @menu
|
|
3391 * Routine Definitions:: Where IDL Routines are defined.
|
|
3392 * Routine Information Sources:: So how does IDLWAVE know about...
|
|
3393 * Catalogs::
|
|
3394 * Load-Path Shadows:: Routines defined in several places
|
|
3395 * Documentation Scan:: Scanning the IDL Manuals
|
|
3396 @end menu
|
|
3397
|
|
3398 @node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info
|
|
3399 @appendixsec Routine Definitions
|
|
3400 @cindex Routine definitions
|
|
3401 @cindex IDL variable @code{!PATH}
|
|
3402 @cindex @code{!PATH}, IDL variable
|
|
3403 @cindex @code{CALL_EXTERNAL}, IDL routine
|
|
3404 @cindex @code{LINKIMAGE}, IDL routine
|
|
3405 @cindex External routines
|
|
3406
|
|
3407 @noindent Routines which can be used in an IDL program can be defined in
|
|
3408 several places:
|
|
3409
|
|
3410 @enumerate
|
|
3411 @item
|
|
3412 @emph{Builtin routines} are defined inside IDL itself. The source code
|
|
3413 of such routines is not available, but instead are learned about through
|
|
3414 the IDL documentation.
|
|
3415 @item
|
|
3416 Routines which are @emph{part of the current program}, are defined in a
|
|
3417 file explicitly compiled by the user. This file may or may not be
|
|
3418 located on the IDL search path.
|
|
3419 @item
|
|
3420 @emph{Library routines} are defined in files located on IDL's search
|
|
3421 path. When a library routine is called for the first time, IDL will
|
|
3422 find the source file and compile it dynamically. A special sub-category
|
|
3423 of library routines are the @emph{system routines} distributed with IDL,
|
|
3424 and usually available in the @file{lib} subdirectory of the IDL
|
|
3425 distribution.
|
|
3426 @item
|
|
3427 External routines written in other languages (like Fortran or C) can be
|
|
3428 called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE},
|
|
3429 or included as dynamically loaded modules (DLMs). Currently IDLWAVE
|
|
3430 cannot provide routine info and completion for such external routines,
|
|
3431 except by querying the Shell for calling information (DLMs only).
|
|
3432 @end enumerate
|
|
3433
|
|
3434 @node Routine Information Sources, Catalogs, Routine Definitions, Sources of Routine Info
|
|
3435 @appendixsec Routine Information Sources
|
|
3436 @cindex Routine info sources
|
|
3437 @cindex Builtin list of routines
|
|
3438 @cindex Updating routine info
|
|
3439 @cindex Scanning buffers for routine info
|
|
3440 @cindex Buffers, scanning for routine info
|
|
3441 @cindex Shell, querying for routine info
|
|
3442
|
|
3443 @noindent To maintain the most comprehensive information about all IDL
|
|
3444 routines on a system, IDLWAVE collects data from many sources:
|
|
3445
|
|
3446 @enumerate
|
|
3447
|
|
3448 @item
|
|
3449 It has a @emph{builtin list} with information about the routines IDL
|
|
3450 ships with. IDLWAVE @value{VERSION} is distributed with a list of
|
|
3451 @value{NSYSROUTINES} routines and object methods, reflecting IDL version
|
|
3452 @value{IDLVERSION}. As of IDL v6.2, the routine info is distributed
|
|
3453 directly with IDL in the form of an XML catalog which IDLWAVE scans.
|
|
3454 Formerly, this list was created by scanning the IDL manuals to produce
|
|
3455 the file @file{idlw-rinfo.el}.
|
|
3456
|
|
3457 @item
|
|
3458 IDLWAVE @emph{scans} all its @emph{buffers} in the current Emacs session
|
|
3459 for routine definitions. This is done automatically when routine
|
|
3460 information or completion is first requested by the user. Each new
|
|
3461 buffer and each buffer saved after making changes is also scanned. The
|
|
3462 command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used
|
|
3463 at any time to rescan all buffers.
|
|
3464
|
|
3465 @item
|
|
3466 If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will
|
|
3467 @emph{query the shell} for compiled routines and their arguments. This
|
|
3468 happens automatically when routine information or completion is first
|
|
3469 requested by the user. Each time an Emacs buffer is compiled with
|
|
3470 @kbd{C-c C-d C-c}, the routine info for that file is queried. Though
|
|
3471 rarely necessary, the command @kbd{C-c C-i}
|
|
3472 (@code{idlwave-update-routine-info}) can be used to explicitly update
|
|
3473 the shell routine data.
|
|
3474
|
|
3475 @item
|
|
3476 Many popular libraries are distributed with routine information already
|
|
3477 scanned into @emph{library catalogs} (@pxref{Library Catalogs}). These
|
|
3478 per-directory catalog files can also be built by the user with the
|
|
3479 supplied @file{idlwave_catalog} tool. They are automatically discovered
|
|
3480 by IDLWAVE.
|
|
3481
|
|
3482 @item
|
|
3483 IDLWAVE can scan selected directories of source files and store the
|
|
3484 result in a single @emph{user catalog} file which will be
|
|
3485 automatically loaded just like @file{idlw-rinfo.el}. @xref{User
|
|
3486 Catalog}, for information on how to scan files in this way.
|
|
3487 @end enumerate
|
|
3488
|
|
3489 Loading all the routine and catalog information can be a time consuming
|
|
3490 process, especially over slow networks. Depending on the system and
|
|
3491 network configuration it could take up to 30 seconds (though locally on
|
|
3492 fast systems is usually only a few seconds). In order to minimize the
|
|
3493 wait time upon your first completion or routine info command in a
|
|
3494 session, IDLWAVE uses Emacs idle time to do the initialization in six
|
|
3495 steps, yielding to user input in between. If this gets into your way,
|
|
3496 set the variable @code{idlwave-init-rinfo-when-idle-after} to 0 (zero).
|
|
3497 The more routines documented in library and user catalogs, the slower
|
|
3498 the loading will be, so reducing this number can help alleviate any long
|
|
3499 load times.
|
|
3500
|
|
3501 @defopt idlwave-init-rinfo-when-idle-after (@code{10})
|
|
3502 Seconds of idle time before routine info is automatically initialized.
|
|
3503 @end defopt
|
|
3504
|
|
3505 @defopt idlwave-scan-all-buffers-for-routine-info (@code{t})
|
|
3506 Non-@code{nil} means scan all buffers for IDL programs when updating
|
|
3507 info.
|
|
3508 @end defopt
|
|
3509
|
|
3510 @defopt idlwave-query-shell-for-routine-info (@code{t})
|
|
3511 Non-@code{nil} means query the shell for info about compiled routines.
|
|
3512 @end defopt
|
|
3513
|
|
3514 @defopt idlwave-auto-routine-info-updates
|
|
3515 Controls under what circumstances routine info is updated automatically.
|
|
3516 @end defopt
|
|
3517
|
|
3518 @html
|
|
3519 <A NAME="CATALOGS"></A>
|
|
3520 @end html
|
|
3521 @node Catalogs, Load-Path Shadows, Routine Information Sources, Sources of Routine Info
|
|
3522 @appendixsec Catalogs
|
|
3523 @cindex Catalogs
|
|
3524
|
|
3525 @emph{Catalogs} are files containing scanned information on individual
|
|
3526 routines, including arguments and keywords, calling sequence, file path,
|
|
3527 class and procedure vs. function type, etc. They represent a way of
|
|
3528 extending the internal built-in information available for IDL system
|
|
3529 routines (@pxref{Routine Info}) to other source collections.
|
|
3530
|
|
3531 Starting with version 5.0, there are two types of catalogs available
|
|
3532 with IDLWAVE. The traditional @emph{user catalog} and the newer
|
|
3533 @emph{library catalogs}. Although they can be used interchangeably, the
|
|
3534 library catalogs are more flexible, and preferred. There are few
|
|
3535 occasions when a user catalog might be preferred --- read below. Both
|
|
3536 types of catalogs can coexist without causing problems.
|
|
3537
|
|
3538 To facilitate the catalog systems, IDLWAVE stores information it gathers
|
|
3539 from the shell about the IDL search paths, and can write this
|
|
3540 information out automatically, or on-demand (menu @code{Debug->Save Path
|
|
3541 Info}). On systems with no shell from which to discover the path
|
|
3542 information (e.g. Windows), a library path must be specified in
|
|
3543 @code{idlwave-library-path} to allow library catalogs to be located, and
|
|
3544 to setup directories for user catalog scan (@pxref{User Catalog} for
|
|
3545 more on this variable). Note that, before the shell is running, IDLWAVE
|
|
3546 can only know about the IDL search path by consulting the file pointed
|
|
3547 to by @code{idlwave-path-file} (@file{~/.idlwave/idlpath.el}, by
|
|
3548 default). If @code{idlwave-auto-write-path} is enabled (which is the
|
|
3549 default), the paths are written out whenever the IDLWAVE shell is
|
|
3550 started.
|
|
3551
|
|
3552 @defopt idlwave-auto-write-path (@code{t})
|
|
3553 Write out information on the !PATH and !DIR paths from IDL automatically
|
|
3554 when they change and when the Shell is closed. These paths are needed
|
|
3555 to locate library catalogs.
|
|
3556 @end defopt
|
|
3557
|
|
3558 @defopt idlwave-library-path
|
|
3559 IDL library path for Windows and MacOS. Under Unix/MacOSX, will be
|
|
3560 obtained from the Shell when run.
|
|
3561 @end defopt
|
|
3562
|
|
3563 @defopt idlwave-system-directory
|
|
3564 The IDL system directory for Windows and MacOS. Also needed for
|
|
3565 locating HTML help and the IDL Assistant for IDL v6.2 and later. Under
|
|
3566 Unix/MacOSX, will be obtained from the Shell and recorded, if run.
|
|
3567 @end defopt
|
|
3568
|
|
3569 @defopt idlwave-config-directory (@file{~/.idlwave})
|
|
3570 Default path where IDLWAVE saves configuration information, a user
|
|
3571 catalog (if any), and a cached scan of the XML catalog (IDL v6.2 and
|
|
3572 later).
|
|
3573 @end defopt
|
|
3574
|
|
3575 @menu
|
|
3576 * Library Catalogs::
|
|
3577 * User Catalog::
|
|
3578 @end menu
|
|
3579
|
|
3580 @html
|
|
3581 <A NAME="LIBRARY_CATALOGS"></A>
|
|
3582 @end html
|
|
3583 @node Library Catalogs, User Catalog, Catalogs, Catalogs
|
|
3584 @appendixsubsec Library Catalogs
|
|
3585 @cindex @file{.idlwave_catalog}
|
|
3586 @cindex Library catalogs
|
|
3587 @cindex @code{idlwave_catalog}
|
|
3588
|
|
3589 Library catalogs consist of files named @file{.idlwave_catalog} stored
|
|
3590 in directories containing @code{.pro} routine files. They are
|
|
3591 discovered on the IDL search path and loaded automatically when routine
|
|
3592 information is read. Each catalog file documents the routines found in
|
|
3593 that directory --- one catalog per directory. Every catalog has a
|
|
3594 library name associated with it (e.g. @emph{AstroLib}). This name will
|
|
3595 be shown briefly when the catalog is found, and in the routine info of
|
|
3596 routines it documents.
|
|
3597
|
|
3598 Many popular libraries of routines are shipped with IDLWAVE catalog
|
|
3599 files by default, and so will be automatically discovered. Library
|
|
3600 catalogs are scanned externally to Emacs using a tool provided with
|
|
3601 IDLWAVE. Each catalog can be re-scanned independently of any other.
|
|
3602 Catalogs can easily be made available system-wide with a common source
|
|
3603 repository, providing uniform routine information, and lifting the
|
|
3604 burden of scanning from the user (who may not even know they're using a
|
|
3605 scanned catalog). Since all catalogs are independent, they can be
|
|
3606 re-scanned automatically to gather updates, e.g. in a @file{cron} job.
|
|
3607 Scanning is much faster than with the built-in user catalog method. One
|
|
3608 minor disadvantage: the entire IDL search path is scanned for catalog
|
|
3609 files every time IDLWAVE starts up, which might be slow if accessing IDL
|
|
3610 routines over a slow network.
|
|
3611
|
|
3612 A Perl tool to create library catalogs is distributed with IDLWAVE:
|
|
3613 @code{idlwave_catalog}. It can be called quite simply:
|
|
3614 @example
|
|
3615 idlwave_catalog MyLib
|
|
3616 @end example
|
|
3617
|
|
3618 @noindent This will scan all directories recursively beneath the current and
|
|
3619 populate them with @file{.idlwave_catalog} files, tagging the routines
|
|
3620 found there with the name library ``MyLib''. The full usage
|
|
3621 information:
|
|
3622
|
|
3623 @example
|
|
3624 Usage: idlwave_catalog [-l] [-v] [-d] [-s] [-f] [-h] libname
|
|
3625 libname - Unique name of the catalog (4 or more alphanumeric
|
|
3626 characters).
|
|
3627 -l - Scan local directory only, otherwise recursively
|
|
3628 catalog all directories at or beneath this one.
|
|
3629 -v - Print verbose information.
|
|
3630 -d - Instead of scanning, delete all .idlwave_catalog files
|
|
3631 here or below.
|
|
3632 -s - Be silent.
|
|
3633 -f - Force overwriting any catalogs found with a different
|
|
3634 library name.
|
|
3635 -h - Print this usage.
|
|
3636 @end example
|
|
3637
|
|
3638 To re-load the library catalogs on the IDL path, force a system routine
|
|
3639 info update using a single prefix to @code{idlwave-update-routine-info}:
|
|
3640 @kbd{C-u C-c C-i}.
|
|
3641
|
|
3642 @defopt idlwave-use-library-catalogs (@code{t})
|
|
3643 Whether to search for and load library catalogs. Disable if load
|
|
3644 performance is a problem and/or the catalogs are not needed.
|
|
3645 @end defopt
|
|
3646
|
|
3647 @node User Catalog, , Library Catalogs, Catalogs
|
|
3648 @appendixsubsec User Catalog
|
|
3649 @cindex User catalog
|
|
3650 @cindex IDL library routine info
|
|
3651 @cindex Windows
|
|
3652 @cindex MacOS
|
|
3653 @cindex IDL variable @code{!DIR}
|
|
3654 @cindex @code{!DIR}, IDL variable
|
|
3655
|
|
3656 The user catalog is the old routine catalog system. It is produced
|
|
3657 within Emacs, and stored in a single file in the user's home directory
|
|
3658 (@file{.idlwave/idlusercat.el} by default). Although library catalogs
|
|
3659 are more flexible, there may be reasons to prefer a user catalog
|
|
3660 instead, including:
|
|
3661
|
|
3662 @itemize @bullet
|
|
3663 @item The scan is internal to Emacs, so you don't need a working Perl
|
|
3664 installation, as you do for library catalogs.
|
|
3665 @item Can be used to scan directories for which the user has no write
|
|
3666 privileges.
|
|
3667 @item Easy widget-based path selection.
|
|
3668 @end itemize
|
|
3669
|
|
3670 However, no routine info is available in the user catalog by default;
|
|
3671 the user must actively complete a scan. In addition, this type of
|
|
3672 catalog is all or nothing: if a single routine changes, the entire
|
|
3673 catalog must be rescanned to update it. Creating the user catalog is
|
|
3674 also much slower than scanning library catalogs.
|
|
3675
|
|
3676 You can scan any of the directories on the currently known path. Under
|
|
3677 Windows and MacOS (not OSX), you need to specify the IDL search path in
|
|
3678 the variable @code{idlwave-library-path}, and the location of the IDL
|
|
3679 directory (the value of the @code{!DIR} system variable) in the variable
|
|
3680 @code{idlwave-system-directory}, like this@footnote{The initial @samp{+}
|
|
3681 leads to recursive expansion of the path, just like in IDL}:
|
|
3682
|
|
3683 @lisp
|
|
3684 (setq idlwave-library-path
|
|
3685 '("+c:/RSI/IDL56/lib/" "+c:/user/me/idllibs"))
|
|
3686 (setq idlwave-system-directory "c:/RSI/IDL56/")
|
|
3687 @end lisp
|
|
3688
|
|
3689 @noindent Under GNU/Linux and UNIX, these values will be automatically
|
|
3690 gathered from the IDLWAVE shell, if run.
|
|
3691
|
|
3692 The command @kbd{M-x idlwave-create-user-catalog-file} (or the menu item
|
|
3693 @samp{IDLWAVE->Routine Info->Select Catalog Directories}) can then be
|
|
3694 used to create a user catalog. It brings up a widget in which you can
|
|
3695 select some or all directories on the search path. Directories which
|
|
3696 already contain a library catalog are marked with @samp{[LIB]}, and need
|
|
3697 not be scanned (although there is no harm if you do so, other than the
|
|
3698 additional memory used for the duplication).
|
|
3699
|
|
3700 After selecting directories, click on the @w{@samp{[Scan & Save]}}
|
|
3701 button in the widget to scan all files in the selected directories and
|
|
3702 write out the resulting routine information. In order to update the
|
|
3703 library information using the directory selection, call the command
|
|
3704 @code{idlwave-update-routine-info} with a double prefix argument:
|
|
3705 @w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously
|
|
3706 selected directories, write an updated version of the user catalog file
|
|
3707 and rebuild IDLWAVE's internal lists. If you give three prefix
|
|
3708 arguments @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a
|
|
3709 background job@footnote{Unix systems only, I think.}. You can continue
|
|
3710 to work, and the library catalog will be re-read when it is ready. If
|
|
3711 you find you need to update the user catalog often, you should consider
|
|
3712 building a library catalog for your routines instead (@pxref{Library
|
|
3713 Catalogs}).
|
|
3714
|
|
3715 @defopt idlwave-special-lib-alist
|
|
3716 Alist of regular expressions matching special library directories for
|
|
3717 labeling in routine-info display.
|
|
3718 @end defopt
|
|
3719
|
|
3720 @node Load-Path Shadows, Documentation Scan, Catalogs, Sources of Routine Info
|
|
3721 @appendixsec Load-Path Shadows
|
|
3722 @cindex Load-path shadows
|
|
3723 @cindex Shadows, load-path
|
|
3724 @cindex Duplicate routines
|
|
3725 @cindex Multiply defined routines
|
|
3726 @cindex Routine definitions, multiple
|
|
3727 @cindex Application, testing for shadowing
|
|
3728 @cindex Buffer, testing for shadowing
|
|
3729
|
|
3730 IDLWAVE can compile a list of routines which are (re-)defined in more
|
|
3731 than one file. Since one definition will hide (shadow) the others
|
|
3732 depending on which file is compiled first, such multiple definitions are
|
|
3733 called "load-path shadows". IDLWAVE has several routines to scan for
|
|
3734 load path shadows. The output is placed into the special buffer
|
|
3735 @file{*Shadows*}. The format of the output is identical to the source
|
|
3736 section of the routine info buffer (@pxref{Routine Info}). The
|
|
3737 different definitions of a routine are ordered by @emph{likelihood of
|
|
3738 use}. So the first entry will be most likely the one you'll get if an
|
|
3739 unsuspecting command uses that routine. Before listing shadows, you
|
|
3740 should make sure that routine info is up-to-date by pressing @kbd{C-c
|
|
3741 C-i}. Here are the different routines (also available in the Menu
|
|
3742 @samp{IDLWAVE->Routine Info}):
|
|
3743
|
|
3744 @table @asis
|
|
3745 @item @kbd{M-x idlwave-list-buffer-load-path-shadows}
|
|
3746 This commands checks the names of all routines defined in the current
|
|
3747 buffer for shadowing conflicts with other routines accessible to
|
|
3748 IDLWAVE. The command also has a key binding: @kbd{C-c C-b}
|
|
3749 @item @kbd{M-x idlwave-list-shell-load-path-shadows}.
|
|
3750 Checks all routines compiled under the shell for shadowing. This is
|
|
3751 very useful when you have written a complete application. Just compile
|
|
3752 the application, use @code{RESOLVE_ALL} to compile any routines used by
|
|
3753 your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and
|
|
3754 then check for shadowing.
|
|
3755 @item @kbd{M-x idlwave-list-all-load-path-shadows}
|
|
3756 This command checks all routines accessible to IDLWAVE for conflicts.
|
|
3757 @end table
|
|
3758
|
|
3759 For these commands to work fully you need to scan the entire load path
|
|
3760 in either a user or library catalog. Also, IDLWAVE should be able to
|
|
3761 distinguish between the system library files (normally installed in
|
|
3762 @file{/usr/local/rsi/idl/lib}) and any site specific or user specific
|
|
3763 files. Therefore, such local files should not be installed inside the
|
|
3764 @file{lib} directory of the IDL directory. This is also advisable for
|
|
3765 many other reasons.
|
|
3766
|
|
3767 @cindex Windows
|
|
3768 @cindex MacOS
|
|
3769 @cindex IDL variable @code{!DIR}
|
|
3770 @cindex @code{!DIR}, IDL variable
|
|
3771 Users of Windows and MacOS (not X) also must set the variable
|
|
3772 @code{idlwave-system-directory} to the value of the @code{!DIR} system
|
|
3773 variable in IDL. IDLWAVE appends @file{lib} to the value of this
|
|
3774 variable and assumes that all files found on that path are system
|
|
3775 routines.
|
|
3776
|
|
3777 Another way to find out if a specific routine has multiple definitions
|
|
3778 on the load path is routine info display (@pxref{Routine Info}).
|
|
3779
|
|
3780 @node Documentation Scan, , Load-Path Shadows, Sources of Routine Info
|
|
3781 @appendixsec Documentation Scan
|
|
3782 @cindex @file{get_html_rinfo}
|
|
3783 @cindex @file{idlw-rinfo.el}
|
|
3784 @cindex Scanning the documentation
|
|
3785 @cindex Perl program, to create @file{idlw-rinfo.el}
|
|
3786
|
|
3787 @strong{Starting with version 6.2, IDL is distributed directly with HTML
|
|
3788 online help, and an XML-based catalog of routine information}. This
|
|
3789 makes scanning the manuals with the tool @file{get_html_rinfo}, and the
|
|
3790 @file{idlw-rinfo.el} file it produced, as described here, entirely
|
|
3791 unnecessary. The information is left here for users wishing to produce
|
|
3792 a catalog of older IDL versions' help.
|
|
3793
|
|
3794
|
|
3795 IDLWAVE derives its knowledge about system routines from the IDL
|
|
3796 manuals. The file @file{idlw-rinfo.el} contains the routine information
|
|
3797 for the IDL system routines, and links to relevant sections of the HTML
|
|
3798 documentation. The Online Help feature of IDLWAVE requires HTML
|
|
3799 versions of the IDL manuals to be available; the HTML documentation is
|
|
3800 not distributed with IDLWAVE by default, but must be downloaded
|
|
3801 separately.
|
|
3802
|
|
3803 The HTML files and related images can be produced from the
|
|
3804 @file{idl.chm} HTMLHelp file distributed with IDL using the free
|
|
3805 Microsoft HTML Help Workshop. If you are lucky, the maintainer of
|
|
3806 IDLWAVE will always have access to the newest version of IDL and provide
|
|
3807 updates. The IDLWAVE distribution also contains the Perl program
|
|
3808 @file{get_html_rinfo} which constructs the @file{idlw-rinfo.el} file by
|
|
3809 scanning the HTML documents produced from the IDL documentation.
|
|
3810 Instructions on how to use @file{get_html_rinfo} are in the program
|
|
3811 itself.
|
|
3812
|
|
3813 @node HTML Help Browser Tips, Configuration Examples, Sources of Routine Info, Top
|
|
3814 @appendix HTML Help Browser Tips
|
|
3815 @cindex Browser Tips
|
|
3816
|
|
3817 There are a wide variety of possible browsers to use for displaying
|
|
3818 the online HTML help available with IDLWAVE (starting with version
|
|
3819 5.0). Since IDL v6.2, a single cross-platform HTML help browser, the
|
|
3820 @emph{IDL Assistant} is distributed with IDL. If this help browser is
|
|
3821 available, it is the preferred choice, and the default. The variable
|
|
3822 @code{idlwave-help-use-assistant}, enabled by default, controls
|
|
3823 whether this help browser is used. If you use the IDL Assistant, the
|
|
3824 tips here are not relevant.
|
|
3825
|
|
3826 Since IDLWAVE runs on a many different system types, a single browser
|
|
3827 configuration is not possible, but choices abound. On many systems,
|
|
3828 the default browser configured in @code{browse-url-browser-function},
|
|
3829 and hence inherited by default by
|
|
3830 @code{idlwave-help-browser-function}, is Netscape. Unfortunately, the
|
|
3831 HTML manuals decompiled from the original source contain formatting
|
|
3832 structures which Netscape 4.x does not handle well, though they are
|
|
3833 still readable. A much better choice is Mozilla, or one of the
|
|
3834 Mozilla-derived browsers such as
|
|
3835 @uref{http://galeon.sourceforge.net/,Galeon} (GNU/Linux),
|
|
3836 @uref{http://www.mozilla.org/projects/camino/,Camino} (MacOSX), or
|
|
3837 @uref{http://www.mozilla.org/projects/firebird/,Firebird} (all
|
|
3838 platforms). Newer versions of Emacs provide a browser-function choice
|
|
3839 @code{browse-url-gnome-moz} which uses the Gnome-configured browser.
|
|
3840
|
|
3841 Note that the HTML files decompiled from the help sources contain
|
|
3842 specific references to the @samp{Symbol} font, which by default is not
|
|
3843 permitted in normal encodings (it's invalid, technically). Though it
|
|
3844 only impacts a few symbols, you can trick Mozilla-based browsers into
|
|
3845 recognizing @samp{Symbol} by following the directions
|
|
3846 @uref{http://hutchinson.belmont.ma.us/tth/Xfonts.html, here}. With
|
|
3847 this fix in place, HTML help pages look almost identical to their PDF
|
|
3848 equivalents (yet can be bookmarked, browsed as history, searched,
|
|
3849 etc.).
|
|
3850
|
|
3851 @noindent Individual platform recommendations:
|
|
3852
|
|
3853 @itemize @bullet
|
|
3854 @item Unix/MacOSX: The @uref{http://www.w3m.org,@code{w3m}} browser
|
|
3855 and its associated
|
|
3856 @uref{http://emacs-w3m.namazu.org/,@code{emacs-w3m}} emacs mode
|
|
3857 provide in-buffer browsing with image display, and excellent speed and
|
|
3858 formatting. Both the Emacs mode and the browser itself must be
|
|
3859 downloaded separately. To use this browser, include
|
|
3860
|
|
3861 @lisp
|
|
3862 (setq idlwave-help-browser-function 'w3m-browse-url)
|
|
3863 @end lisp
|
|
3864
|
|
3865 in your @file{.emacs}. Setting a few other nice @code{w3m} options
|
|
3866 cuts down on screen clutter:
|
|
3867
|
|
3868 @lisp
|
|
3869 (setq w3m-use-tab nil
|
|
3870 w3m-use-header-line nil
|
|
3871 w3m-use-toolbar nil)
|
|
3872 @end lisp
|
|
3873
|
|
3874 If you use a dedicated frame for help, you might want to add the
|
|
3875 following, to get consistent behavior with the @kbd{q} key:
|
|
3876
|
|
3877 @lisp
|
|
3878 ;; Close my help window when w3m closes.
|
|
3879 (defadvice w3m-close-window (after idlwave-close activate)
|
|
3880 (if (boundp 'idlwave-help-frame)
|
|
3881 (idlwave-help-quit)))
|
|
3882 @end lisp
|
|
3883
|
|
3884 Note that you can open the file in an external browser from within
|
|
3885 @code{w3m} using @kbd{M}.
|
|
3886 @end itemize
|
|
3887
|
|
3888 @node Configuration Examples, Windows and MacOS, HTML Help Browser Tips, Top
|
|
3889 @appendix Configuration Examples
|
|
3890 @cindex Configuration examples
|
|
3891 @cindex Example configuration
|
|
3892 @cindex @file{.emacs}
|
|
3893 @cindex Default settings, of options
|
|
3894 @cindex Interview, with the maintainer
|
|
3895
|
|
3896 @noindent
|
|
3897 @b{Question:} You have all these complicated configuration options in
|
|
3898 your package, but which ones do @emph{you} as the maintainer actually
|
|
3899 set in your own configuration?
|
|
3900
|
|
3901 @noindent
|
|
3902 @b{Answer:} Not many, beyond custom key bindings. I set most defaults
|
|
3903 the way that seems best. However, the default settings do not turn on
|
|
3904 features which:
|
|
3905
|
|
3906 @itemize @minus
|
|
3907 @item
|
|
3908 are not self-evident (i.e. too magic) when used by an unsuspecting user.
|
|
3909 @item
|
|
3910 are too intrusive.
|
|
3911 @item
|
|
3912 will not work properly on all Emacs installations.
|
|
3913 @item
|
|
3914 break with widely used standards.
|
|
3915 @item
|
|
3916 use function or other non-standard keys.
|
|
3917 @item
|
|
3918 are purely personal customizations, like additional key bindings, and
|
|
3919 library names.
|
|
3920 @end itemize
|
|
3921
|
|
3922 @noindent To see what I mean, here is the @emph{entire} configuration
|
|
3923 the old maintainer had in his @file{.emacs}:
|
|
3924
|
|
3925 @lisp
|
|
3926 (setq idlwave-shell-debug-modifiers '(control shift)
|
|
3927 idlwave-store-inquired-class t
|
|
3928 idlwave-shell-automatic-start t
|
|
3929 idlwave-main-block-indent 2
|
|
3930 idlwave-init-rinfo-when-idle-after 2
|
|
3931 idlwave-help-dir "~/lib/emacs/idlwave"
|
|
3932 idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib")
|
|
3933 ("/jhuapl/" . "JHUAPL-Lib")
|
|
3934 ("/dominik/lib/idl/" . "MyLib")))
|
|
3935 @end lisp
|
|
3936
|
|
3937 However, if you are an Emacs power-user and want IDLWAVE to work
|
|
3938 completely differently, you can change almost every aspect of it. Here
|
|
3939 is an example of a much more extensive configuration of IDLWAVE. The
|
|
3940 user is King!
|
|
3941
|
|
3942 @example
|
|
3943 ;;; Settings for IDLWAVE mode
|
|
3944
|
|
3945 (setq idlwave-block-indent 3) ; Indentation settings
|
|
3946 (setq idlwave-main-block-indent 3)
|
|
3947 (setq idlwave-end-offset -3)
|
|
3948 (setq idlwave-continuation-indent 1)
|
|
3949 (setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;"
|
|
3950 ; anchored at start of line.
|
|
3951 (setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,>
|
|
3952 (setq idlwave-pad-keyword nil) ; Remove spaces for keyword '='
|
|
3953 (setq idlwave-expand-generic-end t) ; convert END to ENDIF etc...
|
|
3954 (setq idlwave-reserved-word-upcase t) ; Make reserved words upper case
|
|
3955 ; (with abbrevs only)
|
|
3956 (setq idlwave-abbrev-change-case nil) ; Don't force case of expansions
|
|
3957 (setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill
|
|
3958 (setq idlwave-show-block nil) ; Turn off blinking to begin
|
|
3959 (setq idlwave-abbrev-move t) ; Allow abbrevs to move point
|
|
3960 (setq idlwave-query-class '((method-default . nil) ; No query for method
|
|
3961 (keyword-default . nil); or keyword completion
|
|
3962 ("INIT" . t) ; except for these
|
|
3963 ("CLEANUP" . t)
|
|
3964 ("SETPROPERTY" .t)
|
|
3965 ("GETPROPERTY" .t)))
|
|
3966
|
|
3967 ;; Using w3m for help (must install w3m and emacs-w3m)
|
|
3968 (autoload 'w3m-browse-url "w3m" "Interface for w3m on Emacs." t)
|
|
3969 (setq idlwave-help-browser-function 'w3m-browse-url
|
|
3970 w3m-use-tab nil ; no tabs, location line, or toolbar
|
|
3971 w3m-use-header-line nil
|
|
3972 w3m-use-toolbar nil)
|
|
3973
|
|
3974 ;; Close my help window or frame when w3m closes with `q'
|
|
3975 (defadvice w3m-close-window (after idlwave-close activate)
|
|
3976 (if (boundp 'idlwave-help-frame)
|
|
3977 (idlwave-help-quit)))
|
|
3978
|
|
3979 ;; Some setting can only be done from a mode hook. Here is an example:
|
|
3980 (add-hook 'idlwave-mode-hook
|
|
3981 (lambda ()
|
|
3982 (setq case-fold-search nil) ; Make searches case sensitive
|
|
3983 ;; Run other functions here
|
|
3984 (font-lock-mode 1) ; Turn on font-lock mode
|
|
3985 (idlwave-auto-fill-mode 0) ; Turn off auto filling
|
|
3986 (setq idlwave-help-browser-function 'browse-url-w3)
|
|
3987
|
|
3988 ;; Pad with 1 space (if -n is used then make the
|
|
3989 ;; padding a minimum of n spaces.) The defaults use -1
|
|
3990 ;; instead of 1.
|
|
3991 (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1))
|
|
3992 (idlwave-action-and-binding "<" '(idlwave-surround 1 1))
|
|
3993 (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-)))
|
|
3994 (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
|
|
3995
|
|
3996 ;; Only pad after comma and with exactly 1 space
|
|
3997 (idlwave-action-and-binding "," '(idlwave-surround nil 1))
|
|
3998 (idlwave-action-and-binding "&" '(idlwave-surround 1 1))
|
|
3999
|
|
4000 ;; Pad only after `->', remove any space before the arrow
|
|
4001 (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2))
|
|
4002
|
|
4003 ;; Set some personal bindings
|
|
4004 ;; (In this case, makes `,' have the normal self-insert behavior.)
|
|
4005 (local-set-key "," 'self-insert-command)
|
|
4006 (local-set-key [f5] 'idlwave-shell-break-here)
|
|
4007 (local-set-key [f6] 'idlwave-shell-clear-current-bp)
|
|
4008
|
|
4009 ;; Create a newline, indenting the original and new line.
|
|
4010 ;; A similar function that does _not_ reindent the original
|
|
4011 ;; line is on "\C-j" (The default for emacs programming modes).
|
|
4012 (local-set-key "\n" 'idlwave-newline)
|
|
4013 ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference.
|
|
4014
|
|
4015 ;; Some personal abbreviations
|
|
4016 (define-abbrev idlwave-mode-abbrev-table
|
|
4017 (concat idlwave-abbrev-start-char "wb") "widget_base()"
|
|
4018 (idlwave-keyword-abbrev 1))
|
|
4019 (define-abbrev idlwave-mode-abbrev-table
|
|
4020 (concat idlwave-abbrev-start-char "on") "obj_new()"
|
|
4021 (idlwave-keyword-abbrev 1))
|
|
4022 ))
|
|
4023
|
|
4024 ;;; Settings for IDLWAVE SHELL mode
|
|
4025
|
|
4026 (setq idlwave-shell-overlay-arrow "=>") ; default is ">"
|
|
4027 (setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame
|
|
4028 (setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> "
|
|
4029 (setq idlwave-shell-explicit-file-name "wave")
|
|
4030 (setq idlwave-shell-process-name "wave")
|
|
4031 (setq idlwave-shell-use-toolbar nil) ; No toolbar
|
|
4032
|
|
4033 ;; Most shell interaction settings can be done from the shell-mode-hook.
|
|
4034 (add-hook 'idlwave-shell-mode-hook
|
|
4035 (lambda ()
|
|
4036 ;; Set up some custom key and mouse examine commands
|
|
4037 (idlwave-shell-define-key-both [s-down-mouse-2]
|
|
4038 (idlwave-shell-mouse-examine
|
|
4039 "print, size(___,/DIMENSIONS)"))
|
|
4040 (idlwave-shell-define-key-both [f9] (idlwave-shell-examine
|
|
4041 "print, size(___,/DIMENSIONS)"))
|
|
4042 (idlwave-shell-define-key-both [f10] (idlwave-shell-examine
|
|
4043 "print,size(___,/TNAME)"))
|
|
4044 (idlwave-shell-define-key-both [f11] (idlwave-shell-examine
|
|
4045 "help,___,/STRUCTURE"))))
|
|
4046 @end example
|
|
4047
|
|
4048 @html
|
|
4049 <A NAME="WIN_MAC"></A>
|
|
4050 @end html
|
|
4051 @node Windows and MacOS, Troubleshooting, Configuration Examples, Top
|
|
4052 @appendix Windows and MacOS
|
|
4053 @cindex Windows
|
|
4054 @cindex MacOS
|
|
4055 @cindex MacOSX
|
|
4056
|
|
4057 IDLWAVE was developed on a UNIX system. However, thanks to the
|
|
4058 portability of Emacs, much of IDLWAVE does also work under different
|
|
4059 operating systems like Windows (with NTEmacs or NTXEmacs) or MacOS.
|
|
4060
|
|
4061 The only real problem is that there is no command-line version of IDL
|
|
4062 for Windows or MacOS(<=9) with which IDLWAVE can interact. As a
|
|
4063 result, the IDLWAVE Shell does not work and you have to rely on IDLDE
|
|
4064 to run and debug your programs. However, editing IDL source files
|
|
4065 with Emacs/IDLWAVE works with all bells and whistles, including
|
|
4066 routine info, completion and fast online help. Only a small amount of
|
|
4067 additional information must be specified in your @file{.emacs} file:
|
|
4068 the path names which, on a UNIX system, are automatically gathered by
|
|
4069 talking to the IDL program.
|
|
4070
|
|
4071 Here is an example of the additional configuration needed for a Windows
|
|
4072 system. I am assuming that IDLWAVE has been installed in
|
|
4073 @w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in
|
|
4074 @w{@samp{C:\RSI\IDL63}}.
|
|
4075
|
|
4076 @lisp
|
|
4077 ;; location of the lisp files (only needed if IDLWAVE is not part of
|
|
4078 ;; your default X/Emacs installation)
|
|
4079 (setq load-path (cons "c:/program files/IDLWAVE" load-path))
|
|
4080
|
|
4081 ;; The location of the IDL library directories, both standard, and your own.
|
|
4082 ;; note that the initial "+" expands the path recursively
|
|
4083 (setq idlwave-library-path
|
|
4084 '("+c:/RSI/IDL63/lib/" "+c:/path/to/my/idllibs" ))
|
|
4085
|
|
4086 ;; location of the IDL system directory (try "print,!DIR")
|
|
4087 (setq idlwave-system-directory "c:/RSI/IDL63/")
|
|
4088
|
|
4089 @end lisp
|
|
4090
|
|
4091 @noindent Furthermore, Windows sometimes tries to outsmart you --- make
|
|
4092 sure you check the following things:
|
|
4093
|
|
4094 @itemize @bullet
|
|
4095 @item When you download the IDLWAVE distribution, make sure you save the
|
|
4096 file under the names @file{idlwave.tar.gz}.
|
|
4097 @item M-TAB switches among running programs --- use Esc-TAB
|
|
4098 instead.
|
|
4099 @item Other issues as yet unnamed...
|
|
4100 @end itemize
|
|
4101
|
|
4102 Windows users who'd like to make use of IDLWAVE's context-aware HTML
|
|
4103 help can skip the browser and use the HTMLHelp functionality directly.
|
|
4104 @xref{Help with HTML Documentation}.
|
|
4105
|
|
4106 @html
|
|
4107 <A NAME="TROUBLE"></A>
|
|
4108 @end html
|
|
4109 @node Troubleshooting, GNU Free Documentation License, Windows and MacOS, Top
|
|
4110 @appendix Troubleshooting
|
|
4111 @cindex Troubleshooting
|
|
4112
|
|
4113 Although IDLWAVE usually installs and works without difficulty, a few
|
|
4114 common problems and their solutions are documented below.
|
|
4115
|
|
4116 @enumerate
|
|
4117
|
|
4118 @item @strong{Whenever an IDL error occurs or a breakpoint is hit, I get
|
|
4119 errors or strange behavior when I try to type anything into some of my
|
|
4120 IDLWAVE buffers.}
|
|
4121
|
|
4122 This is a @emph{feature}, not an error. You're in @emph{Electric
|
|
4123 Debug Mode} (@pxref{Electric Debug Mode}). You should see
|
|
4124 @code{*Debugging*} in the mode-line. The buffer is read-only and all
|
|
4125 debugging and examination commands are available as single keystrokes;
|
|
4126 @kbd{C-?} lists these shortcuts. Use @kbd{q} to quit the mode, and
|
|
4127 customize the variable @code{idlwave-shell-automatic-electric-debug}
|
|
4128 if you prefer not to enter electric debug on breakpoints@dots{} but
|
|
4129 you really should try it before you disable it! You can also
|
|
4130 customize this variable to enter debug mode when errors are
|
|
4131 encountered.
|
|
4132
|
|
4133 @item @strong{I get errors like @samp{Searching for program: no such
|
|
4134 file or directory, idl} when attempting to start the IDL shell.}
|
|
4135
|
|
4136 IDLWAVE needs to know where IDL is in order to run it as a process.
|
|
4137 By default, it attempts to invoke it simply as @samp{idl}, which
|
|
4138 presumes such an executable is on your search path. You need to
|
|
4139 ensure @samp{idl} is on your @samp{$PATH}, or specify the full
|
|
4140 pathname to the idl program with the variable
|
|
4141 @code{idlwave-shell-explicit-file-name}. Note that you may need to
|
|
4142 set your shell search path in two places when running Emacs as an Aqua
|
|
4143 application with MacOSX; see the next topic.
|
|
4144
|
|
4145 @item @strong{IDLWAVE is disregarding my @samp{IDL_PATH} which I set
|
|
4146 under MacOSX}
|
|
4147
|
|
4148 If you run Emacs directly as an Aqua application, rather than from the
|
|
4149 console shell, the environment is set not from your usual shell
|
|
4150 configuration files (e.g. @file{.cshrc}), but from the file
|
|
4151 @file{~/.MacOSX/environment.plist}. Either include your path settings
|
|
4152 there, or start Emacs and IDLWAVE from the shell.
|
|
4153
|
|
4154 @item @strong{I get errors like @samp{Symbol's function is void:
|
|
4155 overlayp}}
|
|
4156
|
|
4157 You don't have the @samp{fsf-compat} package installed, which IDLWAVE
|
|
4158 needs to run under XEmacs. Install it, or find an XEmacs distribution
|
|
4159 which includes it by default.
|
|
4160
|
|
4161 @item @strong{I'm getting errors like @samp{Symbol's value as variable is void:
|
|
4162 cl-builtin-gethash} on completion or routine info.}
|
|
4163
|
|
4164 This error arises if you upgraded Emacs from 20.x to 21.x without
|
|
4165 re-installing IDLWAVE. Old Emacs and new Emacs are not byte-compatible
|
|
4166 in compiled lisp files. Presumably, you kept the original .elc files in
|
|
4167 place, and this is the source of the error. If you recompile (or just
|
|
4168 "make; make install") from source, it should resolve this problem.
|
|
4169 Another option is to recompile the @file{idlw*.el} files by hand using
|
|
4170 @kbd{M-x byte-compile-file}.
|
|
4171
|
|
4172 @item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches
|
|
4173 windows on my desktop.}
|
|
4174
|
|
4175 Your system is trapping @kbd{M-@key{TAB}} and using it for its own
|
|
4176 nefarious purposes: Emacs never sees the keystrokes. On many Unix
|
|
4177 systems, you can reconfigure your window manager to use another key
|
|
4178 sequence for switching among windows. Another option is to use the
|
|
4179 equivalent sequence @kbd{@key{ESC}-@key{TAB}}.
|
|
4180
|
|
4181 @item @strong{When stopping at breakpoints or errors, IDLWAVE does not
|
|
4182 seem to highlight the relevant line in the source.}
|
|
4183
|
|
4184 IDLWAVE scans for error and halt messages and highlights the stop
|
|
4185 location in the correct file. However, if you've changed the system
|
|
4186 variable @samp{!ERROR_STATE.MSG_PREFIX}, it is unable to parse these
|
|
4187 message correctly. Don't do that.
|
|
4188
|
|
4189 @item @strong{IDLWAVE doesn't work correctly when using ENVI.}
|
|
4190
|
|
4191 Though IDLWAVE was not written with ENVI in mind, it works just fine
|
|
4192 with it, as long as you update the prompt it's looking for (@samp{IDL>
|
|
4193 } by default). You can do this with the variable
|
|
4194 @code{idlwave-shell-prompt-pattern} (@pxref{Starting the Shell}), e.g.,
|
|
4195 in your @file{.emacs}:
|
|
4196
|
|
4197 @lisp
|
|
4198 (setq idlwave-shell-prompt-pattern "^\r? ?\\(ENVI\\|IDL\\)> ")
|
|
4199 @end lisp
|
|
4200
|
|
4201 @item @strong{Attempts to set breakpoints fail: no breakpoint is
|
|
4202 indicated in the IDLWAVE buffer.}
|
|
4203
|
|
4204 IDL changed its breakpoint reporting format starting with IDLv5.5. The
|
|
4205 first version of IDLWAVE to support the new format is IDLWAVE v4.10. If
|
|
4206 you have an older version and are using IDL >v5.5, you need to upgrade,
|
|
4207 and/or make sure your recent version of IDLWAVE is being found on the
|
|
4208 Emacs load-path (see the next entry). You can list the version being
|
|
4209 used with @kbd{C-h v idlwave-mode-version @key{RET}}.
|
|
4210
|
|
4211 @item @strong{I installed a new version of IDLWAVE, but the old
|
|
4212 version is still being used} or @strong{IDLWAVE works, but when I
|
|
4213 tried to install the optional modules @file{idlw-roprompt.el} or
|
|
4214 @file{idlw-complete-structtag}, I get errors like @samp{Cannot open
|
|
4215 load file}}.
|
|
4216
|
|
4217 The problem is that your Emacs is not finding the version of IDLWAVE you
|
|
4218 installed. Many Emacsen come with an older bundled copy of IDLWAVE
|
|
4219 (e.g. v4.7 for Emacs 21.x), which is likely what's being used instead.
|
|
4220 You need to make sure your Emacs @emph{load-path} contains the directory
|
|
4221 where IDLWAVE is installed (@file{/usr/local/share/emacs/site-lisp}, by
|
|
4222 default), @emph{before} Emacs' default search directories. You can
|
|
4223 accomplish this by putting the following in your @file{.emacs}:
|
|
4224
|
|
4225 @lisp
|
|
4226 (setq load-path (cons "/usr/local/share/emacs/site-lisp" load-path))
|
|
4227 @end lisp
|
|
4228
|
|
4229 @noindent You can check on your load-path value using @kbd{C-h v
|
|
4230 load-path @key{RET}}, and @kbd{C-h m} in an IDLWAVE buffer should show
|
|
4231 you the version Emacs is using.
|
|
4232
|
|
4233 @item @strong{IDLWAVE is screwing up the formatting of my @file{.idl} files.}
|
|
4234
|
|
4235 Actually, this isn't IDLWAVE at all, but @samp{idl-mode}, an unrelated
|
|
4236 programming mode for CORBA's Interface Definition Language (you should
|
|
4237 see @samp{(IDL)}, not @samp{(IDLWAVE)} in the mode-line). One
|
|
4238 solution: don't name your file @file{.idl}, but rather @file{.pro}.
|
|
4239 Another solution: make sure @file{.idl} files load IDLWAVE instead of
|
|
4240 @samp{idl-mode} by adding the following to your @file{.emacs}:
|
|
4241
|
|
4242 @lisp
|
|
4243 (setcdr (rassoc 'idl-mode auto-mode-alist) 'idlwave-mode)
|
|
4244 @end lisp
|
|
4245
|
|
4246 @item @strong{The routine info for my local routines is out of date!}
|
|
4247
|
|
4248 IDLWAVE collects routine info from various locations (@pxref{Routine
|
|
4249 Information Sources}). Routines in files visited in a buffer or
|
|
4250 compiled in the shell should be up to date. For other routines, the
|
|
4251 information is only as current as the most recent scan. If you have a
|
|
4252 rapidly changing set of routines, and you'd like the latest routine
|
|
4253 information to be available for it, one powerful technique is to make
|
|
4254 use of the library catalog tool, @samp{idlwave_catalog}. Simply add a
|
|
4255 line to your @samp{cron} file (@samp{crontab -e} will let you edit this
|
|
4256 on some systems), like this
|
|
4257
|
|
4258 @example
|
|
4259 45 3 * * 1-5 (cd /path/to/myidllib; /path/to/idlwave_catalog MyLib)
|
|
4260 @end example
|
|
4261
|
|
4262 @noindent where @samp{MyLib} is the name of your library. This will
|
|
4263 rescan all @file{.pro} files at or below @file{/path/to/myidllib} every
|
|
4264 week night at 3:45am. You can even scan site-wide libraries with this
|
|
4265 method, and the most recent information will be available to all users.
|
|
4266 Since the scanning is very fast, there is very little impact.
|
|
4267
|
|
4268 @item @strong{All the Greek-font characters in the HTML help are
|
|
4269 displayed as Latin characters!}
|
|
4270
|
|
4271 Unfortunately, the HTMLHelp files RSI provides attempt to switch to
|
|
4272 @samp{Symbol} font to display Greek characters, which is not really an
|
|
4273 permitted method for doing this in HTML. There is a "workaround" for
|
|
4274 some browsers: @xref{HTML Help Browser Tips}.
|
|
4275
|
|
4276 @item @strong{In the shell, my long commands are truncated at 256 characters!}
|
|
4277
|
|
4278 This actually happens when running IDL in an XTerm as well. There are
|
|
4279 a couple of workarounds: @code{define_key,/control,'^d'} (e.g. in
|
|
4280 your @file{$IDL_STARTUP} file) will disable the @samp{EOF} character
|
|
4281 and give you a 512 character limit. You won't be able to use
|
|
4282 @key{C-d} to quit the shell, however. Another possibility is
|
|
4283 @code{!EDIT_INPUT=0}, which gives you an @emph{infinite} limit (OK, a
|
|
4284 memory-bounded limit), but disables the processing of background
|
|
4285 widget events (those with @code{/NO_BLOCK} passed to @code{XManager}).
|
|
4286
|
|
4287 @item @strong{When I invoke IDL HTML help on a routine, the page which
|
|
4288 is loaded is one page off, e.g. for @code{CONVERT_COORD}, I get
|
|
4289 @code{CONTOUR}.}
|
|
4290
|
|
4291 You have a mismatch between your help index and the HTML help package
|
|
4292 you downloaded. You need to ensure you download a ``downgrade kit'' if
|
|
4293 you are using anything older than the latest HTML help package. A new
|
|
4294 help package appears with each IDL release (assuming the documentation
|
|
4295 is updated).
|
|
4296 Starting with IDL 6.2, the HTML help and its catalog are
|
|
4297 distributed with IDL, and so should never be inconsistent.
|
|
4298
|
|
4299 @item @strong{I get errors such as @samp{void-variable
|
|
4300 browse-url-browser-function} or similar when attempting to load IDLWAVE
|
|
4301 under XEmacs.}
|
|
4302
|
|
4303 You don't have the @samp{browse-url} (or other required) XEmacs package.
|
|
4304 Unlike GNU Emacs, XEmacs distributes many packages separately from the
|
|
4305 main program. IDLWAVE is actually among these, but is not always the
|
|
4306 most up to date. When installing IDLWAVE as an XEmacs package, it
|
|
4307 should prompt you for required additional packages. When installing it
|
|
4308 from source, it won't and you'll get this error. The easiest solution
|
|
4309 is to install all the packages when you install XEmacs (the so-called
|
|
4310 @samp{sumo} bundle). The minimum set of XEmacs packages required by
|
|
4311 IDLWAVE is @samp{fsf-compat, xemacs-base, mail-lib}.
|
|
4312
|
|
4313 @end enumerate
|
|
4314
|
|
4315 @node GNU Free Documentation License, Index, Troubleshooting, Top
|
|
4316 @appendix GNU Free Documentation License
|
|
4317 @include doclicense.texi
|
|
4318
|
|
4319 @node Index, , GNU Free Documentation License, Top
|
|
4320 @unnumbered Index
|
|
4321 @printindex cp
|
|
4322
|
|
4323 @bye
|
|
4324
|
|
4325 @ignore
|
|
4326 arch-tag: f1d73958-1423-4127-b8aa-f7b953d64492
|
|
4327 @end ignore
|