Commit | Line | Data |
---|---|---|
797c8ebc CD |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
58d8692a | 3 | @setfilename ../info/idlwave |
797c8ebc | 4 | @settitle IDLWAVE User Manual |
797c8ebc CD |
5 | @synindex ky cp |
6 | @syncodeindex vr cp | |
7 | @syncodeindex fn cp | |
76959b77 S |
8 | @set VERSION 4.15 |
9 | @set EDITION 4.15 | |
5af23035 | 10 | @set IDLVERSION 5.5 |
76959b77 S |
11 | @set NSYSROUTINES 1324 |
12 | @set NSYSKEYWORDS 6129 | |
13 | @set DATE September 2002 | |
5af23035 | 14 | @set AUTHOR J.D. Smith & Carsten Dominik |
797c8ebc | 15 | @set AUTHOR-EMAIL dominik@@astro.uva.nl |
5af23035 S |
16 | @set MAINTAINER J.D. Smith |
17 | @set MAINTAINER-EMAIL jdsmith@@as.arizona.edu | |
18 | @set IDLWAVE-HOMEPAGE http://idlwave.org/ | |
797c8ebc | 19 | @c %**end of header |
797c8ebc | 20 | |
18f952d5 | 21 | @copying |
5af23035 S |
22 | This file documents IDLWAVE, a major mode for editing IDL files with |
23 | Emacs, and interacting with an IDL shell run as a subprocess. | |
24 | ||
25 | This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE | |
26 | @value{VERSION} | |
27 | ||
28 | Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, | |
29 | Inc. | |
30 | ||
18f952d5 | 31 | @quotation |
32d4cddb S |
32 | Permission is granted to copy, distribute and/or modify this document |
33 | under the terms of the GNU Free Documentation License, Version 1.1 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. | |
18f952d5 KB |
48 | @end quotation |
49 | @end copying | |
50 | ||
51 | @dircategory Emacs | |
52 | @direntry | |
53 | * IDLWAVE: (idlwave). Major mode and shell for IDL files. | |
54 | @end direntry | |
55 | ||
56 | @finalout | |
797c8ebc CD |
57 | |
58 | @titlepage | |
59 | @title IDLWAVE User Manual | |
5af23035 | 60 | @subtitle Emacs major mode and shell for IDL |
797c8ebc CD |
61 | @subtitle Edition @value{EDITION}, @value{DATE} |
62 | ||
5af23035 | 63 | @author by Carsten Dominik & J.D. Smith |
797c8ebc | 64 | @page |
797c8ebc | 65 | This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for |
a8e833f3 | 66 | IDLWAVE version @value{VERSION}, @value{DATE}. |
a8e833f3 | 67 | @cindex Copyright, of IDLWAVE |
18f952d5 | 68 | @insertcopying |
797c8ebc | 69 | @end titlepage |
a8e833f3 CD |
70 | @contents |
71 | ||
797c8ebc CD |
72 | @page |
73 | ||
a8e833f3 CD |
74 | @ifnottex |
75 | ||
797c8ebc CD |
76 | @node Top, Introduction, (dir), (dir) |
77 | ||
5af23035 S |
78 | IDLWAVE is a package which supports editing source for the |
79 | Interactive Data Language (IDL), and running IDL as an inferior | |
a8e833f3 | 80 | shell. |
797c8ebc | 81 | |
a8e833f3 | 82 | @end ifnottex |
797c8ebc CD |
83 | |
84 | @menu | |
5af23035 | 85 | * Introduction:: What IDLWAVE is and what it's not |
797c8ebc | 86 | * IDLWAVE in a Nutshell:: One page quick-start guide |
aea44e56 | 87 | * Getting Started:: Tutorial |
797c8ebc | 88 | * The IDLWAVE Major Mode:: The mode to edit IDL programs |
5af23035 | 89 | * The IDLWAVE Shell:: The mode to run IDL as an inferior program |
177c0ea7 | 90 | * Installation:: How to Install or Upgrade |
5af23035 | 91 | * Acknowledgements:: Who did what |
177c0ea7 | 92 | * Sources of Routine Info:: How does IDLWAVE know about routine XYZ |
797c8ebc | 93 | * Configuration Examples:: The user is king... |
5af23035 | 94 | * Windows and MacOS:: What still works, and how |
797c8ebc CD |
95 | * Index:: Fast access |
96 | ||
5af23035 S |
97 | @detailmenu |
98 | --- The Detailed Node Listing --- | |
99 | ||
100 | Getting Started (Tutorial) | |
101 | ||
177c0ea7 JB |
102 | * Lesson I -- Development Cycle:: |
103 | * Lesson II -- Customization:: | |
104 | * Lesson III -- Library Catalog:: | |
797c8ebc CD |
105 | |
106 | The IDLWAVE Major Mode | |
107 | ||
108 | * Code Formatting:: Making code look nice | |
a8e833f3 CD |
109 | * Routine Info:: Calling Sequence and Keyword List |
110 | * Online Help:: One key press from source to help | |
797c8ebc | 111 | * Completion:: Completing routine names and Keywords |
5af23035 | 112 | * Routine Source:: Finding routines, the easy way |
a8e833f3 | 113 | * Resolving Routines:: Force the Shell to compile a routine |
5af23035 S |
114 | * Code Templates:: Frequent code constructs |
115 | * Abbreviations:: Abbreviations for common commands | |
797c8ebc CD |
116 | * Actions:: Changing case, Padding, End checking |
117 | * Doc Header:: Inserting a standard header | |
118 | * Motion Commands:: Moving through the structure of a program | |
119 | * Misc Options:: Things that fit nowhere else | |
120 | ||
121 | Code Formatting | |
122 | ||
123 | * Code Indentation:: Reflecting the logical structure | |
177c0ea7 | 124 | * Continued Statement Indentation:: |
797c8ebc CD |
125 | * Comment Indentation:: Special indentation for comment lines |
126 | * Continuation Lines:: Splitting statements over lines | |
127 | * Syntax Highlighting:: Font-lock support | |
5af23035 S |
128 | * Octals and Highlighting:: Why "123 causes problems |
129 | ||
130 | Completion | |
131 | ||
132 | * Case of Completed Words:: CaseOFcomPletedWords | |
133 | * Object Method Completion and Class Ambiguity:: obj->Method, what? | |
177c0ea7 | 134 | * Object Method Completion in the Shell:: |
5af23035 S |
135 | * Class and Keyword Inheritance:: obj->Method, _EXTRA=e |
136 | * Structure Tag Completion:: Completing state.Tag | |
797c8ebc CD |
137 | |
138 | Actions | |
139 | ||
76959b77 | 140 | * Block Boundary Check:: Is the END statement correct? |
797c8ebc CD |
141 | * Padding Operators:: Enforcing space around `=' etc |
142 | * Case Changes:: Enforcing upper case keywords | |
143 | ||
144 | The IDLWAVE Shell | |
145 | ||
146 | * Starting the Shell:: How to launch IDL as a subprocess | |
147 | * Using the Shell:: Interactively working with the Shell | |
177c0ea7 JB |
148 | * Commands Sent to the Shell:: |
149 | * Debugging IDL Programs:: | |
150 | * Examining Variables:: | |
151 | * Custom Expression Examination:: | |
797c8ebc CD |
152 | |
153 | Debugging IDL Programs | |
154 | ||
177c0ea7 JB |
155 | * Debug Key Bindings:: |
156 | * Compiling Programs:: | |
157 | * Breakpoints and Stepping:: | |
158 | * Walking the Calling Stack:: | |
797c8ebc CD |
159 | |
160 | Installation | |
161 | ||
162 | * Installing IDLWAVE:: How to install the distribution | |
a8e833f3 | 163 | * Installing Online Help:: Where to get the additional files needed |
797c8ebc CD |
164 | * Upgrading from idl.el:: Necessary configuration changes |
165 | ||
166 | Sources of Routine Info | |
167 | ||
168 | * Routine Definitions:: Where IDL Routines are defined. | |
a8e833f3 | 169 | * Routine Information Sources:: So how does IDLWAVE know about... |
aea44e56 | 170 | * Library Catalog:: Scanning the Libraries for Routine Info |
a8e833f3 CD |
171 | * Load-Path Shadows:: Routines defined in several places |
172 | * Documentation Scan:: Scanning the IDL Manuals | |
173 | ||
797c8ebc CD |
174 | @end detailmenu |
175 | @end menu | |
176 | ||
177 | @node Introduction, IDLWAVE in a Nutshell, Top, Top | |
178 | @chapter Introduction | |
179 | @cindex Introduction | |
180 | @cindex CORBA (Common Object Request Broker Architecture) | |
a8e833f3 CD |
181 | @cindex Interface Definition Language |
182 | @cindex Interactive Data Language | |
797c8ebc | 183 | @cindex cc-mode.el |
a8e833f3 CD |
184 | @cindex @file{idl.el} |
185 | @cindex @file{idl-shell.el} | |
797c8ebc CD |
186 | @cindex Feature overview |
187 | ||
5af23035 S |
188 | IDLWAVE is a package which supports editing source files for the |
189 | Interactive Data Language (IDL@footnote{IDL is a registered trademark of | |
190 | Research Systems, Inc., a Kodak Company}), and for running IDL as an | |
191 | inferior shell@footnote{Note that this package has nothing to do with | |
192 | the Interface Definition Language, part of the Common Object Request | |
193 | Broker Architecture (CORBA)}. It can also be used for editing source | |
194 | files for the related WAVE/CL language, but with only limited | |
177c0ea7 | 195 | support. |
5af23035 S |
196 | |
197 | IDLWAVE consists of two main parts: a major mode for editing IDL source | |
198 | files files (@code{idlwave-mode}) and a mode for running the IDL program | |
199 | as an inferior shell (@code{idlwave-shell-mode}). Although one mode can | |
200 | be used without the other, both work together closely to form a complete | |
201 | development environment. Here is a brief summary of what IDLWAVE does: | |
797c8ebc CD |
202 | |
203 | @itemize @bullet | |
177c0ea7 | 204 | @item |
797c8ebc CD |
205 | Code indentation and formatting. |
206 | @item | |
5af23035 | 207 | Three level syntax highlighting support. |
177c0ea7 | 208 | @item |
5af23035 S |
209 | Context-sensitive display of calling sequences and keywords for more |
210 | than 1000 native IDL routines, extendible to any number of additional | |
211 | routines in your local IDL libraries. | |
a8e833f3 | 212 | @item |
76959b77 | 213 | Routine name space conflict search, likelihood-of-use ranking. |
a8e833f3 | 214 | @item |
5af23035 | 215 | Fast, context-sensitive online help. |
797c8ebc CD |
216 | @item |
217 | Context sensitive completion of routine names and keywords. | |
218 | @item | |
5af23035 | 219 | Easy insertion of code templates. |
797c8ebc | 220 | @item |
5af23035 S |
221 | Automatic corrections to enforce a variety of customizable coding |
222 | standards. | |
797c8ebc | 223 | @item |
5af23035 | 224 | Integrity checks and auto-termination of logical blocks. |
797c8ebc | 225 | @item |
a8e833f3 CD |
226 | Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). |
227 | @item | |
797c8ebc CD |
228 | Documentation support. |
229 | @item | |
5af23035 S |
230 | Running IDL as an inferior Shell with history search, command line |
231 | editing and all the completion and routine info capabilities present in | |
232 | IDL source buffers. | |
233 | @item | |
234 | Compilation, execution and interactive debugging of programs directly | |
235 | from the source buffer. | |
797c8ebc | 236 | @item |
5af23035 S |
237 | Quick, source-guided navigation of the calling stack, with variable |
238 | inspection, etc. | |
797c8ebc | 239 | @item |
5af23035 | 240 | Examining variables and expressions with a mouse click. |
797c8ebc | 241 | @item |
5af23035 | 242 | And much, much more... |
797c8ebc CD |
243 | @end itemize |
244 | ||
245 | @ifnottex | |
246 | @cindex Screenshots | |
5af23035 | 247 | Here are a number of screenshots showing IDLWAVE in action: |
a8e833f3 | 248 | |
797c8ebc CD |
249 | @itemize @bullet |
250 | @item | |
5af23035 | 251 | @uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer} |
797c8ebc | 252 | @item |
5af23035 | 253 | @uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed} |
797c8ebc | 254 | @item |
5af23035 | 255 | @uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.} |
797c8ebc | 256 | @item |
5af23035 S |
257 | @uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed} |
258 | @item | |
259 | @uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code | |
260 | stopped at a breakpoint} | |
797c8ebc CD |
261 | @end itemize |
262 | @end ifnottex | |
263 | ||
5af23035 S |
264 | IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el} |
265 | files written by Chris Chase. The modes and files had to be renamed | |
266 | because of a name space conflict with CORBA's @code{idl-mode}, defined in | |
267 | Emacs in the file @file{cc-mode.el}. If you have been using the old | |
268 | files, check @ref{Upgrading from idl.el} for information on how to | |
269 | switch. | |
270 | ||
271 | In this manual, each section ends with a list of related user options. | |
272 | Don't be confused by the sheer number of options available --- in most | |
273 | cases the default settings are just fine. The variables are listed here | |
274 | to make sure you know where to look if you want to change anything. For | |
275 | a full description of what a particular variable does and how to | |
276 | configure it, see the documentation string of that variable (available | |
277 | with @kbd{C-h v}). Some configuration examples are also given in the | |
278 | appendix. | |
797c8ebc | 279 | |
aea44e56 | 280 | @node IDLWAVE in a Nutshell, Getting Started, Introduction, Top |
797c8ebc | 281 | @chapter IDLWAVE in a Nutshell |
a8e833f3 | 282 | @cindex Summary of important commands |
797c8ebc CD |
283 | @cindex IDLWAVE in a Nutshell |
284 | @cindex Nutshell, IDLWAVE in a | |
285 | ||
797c8ebc CD |
286 | @subheading Editing IDL Programs |
287 | ||
288 | @multitable @columnfractions .15 .85 | |
289 | @item @key{TAB} | |
290 | @tab Indent the current line relative to context. | |
718fb8a1 | 291 | @item @kbd{C-M-\} |
797c8ebc | 292 | @tab Re-indent all lines in the current region. |
5af23035 S |
293 | @item @kbd{C-u @key{TAB}} |
294 | @tab Re-indent all lines in the current statement. | |
797c8ebc | 295 | @item @kbd{M-@key{RET}} |
5af23035 | 296 | @tab Start a continuation line, or split the current line at point. |
797c8ebc CD |
297 | @item @kbd{M-q} |
298 | @tab Fill the current comment paragraph. | |
299 | @item @kbd{C-c ?} | |
5af23035 | 300 | @tab Display calling sequence and keywords for the procedure or function call |
797c8ebc | 301 | at point. |
a8e833f3 | 302 | @item @kbd{M-?} |
5af23035 | 303 | @tab Load context sensitive online help for nearby routine, keyword, etc. |
797c8ebc CD |
304 | @item @kbd{M-@key{TAB}} |
305 | @tab Complete a procedure name, function name or keyword in the buffer. | |
306 | @item @kbd{C-c C-i} | |
307 | @tab Update IDLWAVE's knowledge about functions and procedures. | |
308 | @item @kbd{C-c C-v} | |
5af23035 | 309 | @tab Visit the source code of a procedure/function. |
797c8ebc CD |
310 | @item @kbd{C-c C-h} |
311 | @tab Insert a standard documentation header. | |
5af23035 | 312 | @item @kbd{C-c @key{RET}} |
797c8ebc CD |
313 | @tab Insert a new timestamp and history item in the documentation header. |
314 | @end multitable | |
315 | ||
316 | @subheading Running the IDLWAVE Shell, Debugging Programs | |
317 | ||
318 | @multitable @columnfractions .15 .85 | |
319 | @item @kbd{C-c C-s} | |
320 | @tab Start IDL as a subprocess and/or switch to the interaction buffer. | |
797c8ebc | 321 | @item @kbd{M-p} |
5af23035 | 322 | @tab Cycle back through IDL command history. |
797c8ebc CD |
323 | @item @kbd{M-n} |
324 | @tab Cycle forward. | |
325 | @item @kbd{M-@key{TAB}} | |
326 | @tab Complete a procedure name, function name or keyword in the shell buffer. | |
327 | @item @kbd{C-c C-d C-c} | |
328 | @tab Save and compile the source file in the current buffer. | |
329 | @item @kbd{C-c C-d C-x} | |
330 | @tab Goto next syntax error. | |
331 | @item @kbd{C-c C-d C-b} | |
5af23035 | 332 | @tab Set a breakpoint at the nearest viable source line. |
797c8ebc | 333 | @item @kbd{C-c C-d C-d} |
5af23035 | 334 | @tab Clear the nearest breakpoint. |
797c8ebc | 335 | @item @kbd{C-c C-d C-p} |
5af23035 | 336 | @tab Print the value of the expression near point in IDL. |
797c8ebc CD |
337 | @end multitable |
338 | ||
339 | @subheading Commonly used Settings in @file{.emacs} | |
340 | @lisp | |
341 | ;; Change the indentation preferences | |
5af23035 S |
342 | (setq idlwave-main-block-indent 2 ; default 0 |
343 | idlwave-block-indent 2 ; default 4 | |
344 | idlwave-end-offset -2) ; default -4 | |
345 | ;; Start autoloading routine info after 2 idle seconds | |
346 | (setq idlwave-init-rinfo-when-idle-after 2) | |
ea442c62 CD |
347 | ;; Pad some operators with spaces |
348 | (setq idlwave-do-actions t | |
349 | idlwave-surround-by-blank t) | |
ea442c62 CD |
350 | ;; Syntax Highlighting |
351 | (add-hook 'idlwave-mode-hook 'turn-on-font-lock) | |
aea44e56 CD |
352 | ;; Automatically start the shell when needed |
353 | (setq idlwave-shell-automatic-start t) | |
354 | ;; Bind debugging commands with CONTROL and SHIFT modifiers | |
355 | (setq idlwave-shell-debug-modifiers '(control shift)) | |
5af23035 | 356 | ;; Specify the online help files' location. |
a8e833f3 | 357 | (setq idlwave-help-directory "~/.idlwave") |
797c8ebc CD |
358 | @end lisp |
359 | ||
76959b77 S |
360 | @ifhtml |
361 | <A NAME="TUTORIAL"></A> | |
362 | @end ifhtml | |
aea44e56 CD |
363 | @node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top |
364 | @chapter Getting Started (Tutorial) | |
365 | @cindex Quick-Start | |
366 | @cindex Tutorial | |
367 | @cindex Getting Started | |
368 | ||
5af23035 | 369 | @menu |
177c0ea7 JB |
370 | * Lesson I -- Development Cycle:: |
371 | * Lesson II -- Customization:: | |
372 | * Lesson III -- Library Catalog:: | |
5af23035 S |
373 | @end menu |
374 | ||
375 | @node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started | |
376 | @section Lesson I: Development Cycle | |
aea44e56 CD |
377 | |
378 | The purpose of this tutorial is to guide you through a very basic | |
5af23035 S |
379 | development cycle using IDLWAVE. We will paste a simple program into a |
380 | buffer and use the shell to compile, debug and run it. On the way we | |
381 | will use many of the important IDLWAVE commands. Note however that | |
382 | there are many more capabilities in IDLWAVE than covered here, which can | |
383 | be discovered by reading the entire manual. | |
384 | ||
385 | It is assumed that you have access to Emacs or XEmacs with the full | |
386 | IDLWAVE package including online help (@pxref{Installation}). We also | |
387 | assume that you are familiar with Emacs and can read the nomenclature of | |
388 | key presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL} | |
389 | and @kbd{M} for @key{META} (often the @key{ALT} key carries this | |
aea44e56 CD |
390 | functionality)). |
391 | ||
5af23035 | 392 | Open a new source file by typing: |
aea44e56 CD |
393 | |
394 | @example | |
395 | @kbd{C-x C-f tutorial.pro @key{RET}} | |
396 | @end example | |
397 | ||
5af23035 S |
398 | A buffer for this file will pop up, and it should be in IDLWAVE mode, as |
399 | shown in the mode line just below the editing window. Also, the menu | |
400 | bar should contain entries @samp{IDLWAVE} and @samp{Debug}. | |
aea44e56 | 401 | |
5af23035 | 402 | Now cut-and-paste the following code, also available as |
aea44e56 CD |
403 | @file{tutorial.pro} in the IDLWAVE distribution. |
404 | ||
405 | @example | |
406 | function daynr,d,m,y | |
407 | ;; compute a sequence number for a date | |
408 | ;; works 1901-2099. | |
409 | if y lt 100 then y = y+1900 | |
410 | if m le 2 then delta = 1 else delta = 0 | |
411 | m1 = m + delta*12 + 1 | |
412 | y1 = y * delta | |
413 | return, d + floor(m1*30.6)+floor(y1*365.25)+5 | |
414 | end | |
177c0ea7 | 415 | |
aea44e56 CD |
416 | function weekday,day,month,year |
417 | ;; compute weekday number for date | |
418 | nr = daynr(day,month,year) | |
419 | return, nr mod 7 | |
420 | end | |
177c0ea7 | 421 | |
aea44e56 CD |
422 | pro plot_wday,day,month |
423 | ;; Plot the weekday of a date in the first 10 years of this century. | |
424 | years = 2000,+indgen(10) | |
425 | wdays = intarr(10) | |
426 | for i=0,n_elements(wdays)-1 do begin | |
5af23035 | 427 | wdays[i] = weekday(day,month,years[i]) |
aea44e56 | 428 | end |
5af23035 | 429 | plot,years,wdays,YS=2,YT="Wday (0=Sunday)" |
aea44e56 CD |
430 | end |
431 | @end example | |
432 | ||
433 | The indentation probably looks funny, since it's different from the | |
434 | settings you use, so use the @key{TAB} key in each line to automatically | |
435 | line it up (or more quickly @emph{select} the entire buffer with | |
5af23035 S |
436 | @kbd{C-x h}, and indent the whole region with @kbd{C-M-\}). Notice how |
437 | different syntactical elements are highlighted in different colors, if | |
438 | you have set up support for font-lock. | |
aea44e56 CD |
439 | |
440 | Let's check out two particular editing features of IDLWAVE. Place the | |
441 | cursor after the @code{end} statement of the @code{for} loop and press | |
442 | @key{SPC}. IDLWAVE blinks back to the beginning of the block and | |
443 | changes the generic @code{end} to the specific @code{endfor} | |
444 | automatically. Now place the cursor in any line you would like to split | |
5af23035 S |
445 | and press @kbd{M-@key{RET}}. The line is split at the cursor position, |
446 | with the continuation @samp{$} and indentation all taken care of. Use | |
447 | @kbd{C-/} to undo the last change. | |
aea44e56 | 448 | |
5af23035 S |
449 | The procedure @code{plot_wday} is supposed to plot the weekday of a |
450 | given date for the first 10 years of the 21st century. As in most code, | |
451 | there are a few bugs, which we are going to use IDLWAVE to help us fix. | |
aea44e56 CD |
452 | |
453 | First, let's launch the IDLWAVE shell. You do this with the command | |
454 | @kbd{C-c C-s}. The Emacs window will split and display IDL running in a | |
455 | shell interaction buffer. Type a few commands like @code{print,!PI} to | |
5af23035 S |
456 | convince yourself that you can work there just as well as in a terminal, |
457 | or the IDLDE. Use the arrow keys to cycle through your command history. | |
458 | Are we having fun now? | |
aea44e56 CD |
459 | |
460 | Now go back to the source window and type @kbd{C-c C-d C-c} to compile | |
461 | the program. If you watch the shell buffer, you see that IDLWAVE types | |
462 | @samp{.run tutorial.pro} for you. But the compilation fails because | |
463 | there is a comma in the line @samp{years=...}. The line with the error | |
464 | is highlighted and the cursor positioned at the error, so remove the | |
5af23035 S |
465 | comma (you should only need to hit @kbd{Delete}!). Compile again, using |
466 | the same keystrokes as before. Notice that the file is automatically | |
467 | saved for you. This time everything should work fine, and you should | |
468 | see the three routines compile. | |
469 | ||
470 | Now we want to use the command to plot the day of the week on January | |
471 | 1st. We could type the full command ourselves, but why do that? Go | |
472 | back to the shell window, type @samp{plot_} and hit @key{TAB}. After a | |
473 | bit of a delay (while IDLWAVE initializes its routine info database, if | |
474 | necessary), the window will split to show all procedures it knows | |
475 | starting with that string, and @w{@code{plot_wday}} should be one of | |
476 | them. Saving the buffer alerted IDLWAVE about this new routine. Click | |
477 | with the middle mouse button on @code{plot_wday} and it will be copied | |
478 | to the shell buffer, or if you prefer, add @samp{w} to @samp{plot_} to | |
479 | make it unambiguous, hit @key{TAB} again, and the full routine name will | |
480 | be completed. Now provide the two arguments: | |
aea44e56 CD |
481 | |
482 | @example | |
483 | plot_wday,1,1 | |
484 | @end example | |
485 | ||
aea44e56 CD |
486 | and press @key{RET}. This fails with an error message telling you the |
487 | @code{YT} keyword to plot is ambiguous. What are the allowed keywords | |
488 | again? Go back to the source window and put the cursor into the `plot' | |
5af23035 S |
489 | line, and press @kbd{C-c ?}. This shows the routine info window for the |
490 | plot routine, which contains a list of keywords, along with the argument | |
aea44e56 CD |
491 | list. Oh, we wanted @code{YTITLE}. Fix that up. Recompile with |
492 | @kbd{C-c C-d C-c}. Jump back into the shell with @kbd{C-c C-s}, press | |
493 | the @key{UP} arrow to recall the previous command and execute again. | |
494 | ||
5af23035 | 495 | This time we get a plot, but it is pretty ugly --- the points are all |
aea44e56 CD |
496 | connected with a line. Hmm, isn't there a way for @code{plot} to use |
497 | symbols instead? What was that keyword? Position the cursor on the | |
498 | plot line after a comma (where you'd normally type a keyword), and hit | |
499 | @kbd{M-@key{Tab}}. A long list of plot's keywords appears. Aha, there | |
500 | it is, @code{PSYM}. Middle click to insert it. An @samp{=} sign is | |
501 | included for you too. Now what were the values of @code{PSYM} supposed | |
502 | to be? With the cursor on or after the keyword, press @kbd{M-?} for | |
503 | online help (alternatively, you could have right clicked on the colored | |
504 | keyword itself in the completion list). The online help window will pop | |
5af23035 | 505 | up showing the documentation for the @code{PYSM} keyword. OK, let's use |
aea44e56 CD |
506 | diamonds=4. Fix this, recompile (you know the command by now: @kbd{C-c |
507 | C-d C-c}, go back to the shell (if it's vanished, you know the command | |
508 | to recall it by now: @kbd{C-c C-s}) and execute again. Now things look | |
509 | pretty good. | |
510 | ||
5af23035 | 511 | Let's try a different day --- how about April fool's day? |
aea44e56 CD |
512 | |
513 | @example | |
514 | plot_wday,1,4 | |
515 | @end example | |
516 | ||
5af23035 S |
517 | Oops, this looks very wrong. All April fool's days cannot be Fridays! |
518 | We've got a bug in the program, perhaps in the @code{daynr} function. | |
519 | Let's put a breakpoint on the last line there. Position the cursor on | |
520 | the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a | |
521 | breakpoint (as you see in the shell window), and the line is highlighted | |
522 | in some way. Back to the shell buffer, re-execute the previous command. | |
523 | IDL stops at the line with the breakpoint. Now hold down the SHIFT key | |
524 | and click with the middle mouse button on a few variables there: | |
525 | @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't the | |
526 | correct type. CONTROL-SHIFT middle-click on it for help. Well, it's an | |
527 | integer, so that's not the problem. Aha, @samp{y1} is zero, but it | |
528 | should be the year, depending on delta. Shift click @samp{delta} to see | |
529 | that it's 0. Below, we see the offending line: @samp{y1=y*delta...} the | |
530 | multiplication should have been a minus sign! So fix the line to read: | |
aea44e56 CD |
531 | |
532 | @example | |
533 | y1 = y - delta | |
534 | @end example | |
535 | ||
536 | Now remove all breakpoints: @kbd{C-c C-d C-a}. Recompile and rerun the | |
537 | command. Everything should now work fine. How about those leap years? | |
538 | Change the code to plot 100 years and see that every 28 years, the | |
539 | sequence of weekdays repeats. | |
540 | ||
5af23035 S |
541 | @node Lesson II -- Customization, Lesson III -- Library Catalog, Lesson I -- Development Cycle, Getting Started |
542 | @section Lesson II: Customization | |
aea44e56 CD |
543 | |
544 | Emacs is probably the most customizable piece of software available, and | |
545 | it would be a shame if you did not make use of this and adapt IDLWAVE to | |
5af23035 S |
546 | your own preferences. Customizing Emacs or IDLWAVE is accomplished by |
547 | setting Lisp variables in the @file{.emacs} file in your home directory | |
548 | --- but do not be dismayed; for the most part, you can just copy and work | |
549 | from the examples given here. | |
550 | ||
551 | Let's first use a boolean variable. These are variables which you turn | |
552 | on or off, much like a checkbox. A value of @samp{t} means on, a value | |
553 | of @samp{nil} means off. Copy the following line into your | |
aea44e56 CD |
554 | @file{.emacs} file, exit and restart Emacs. |
555 | ||
556 | @lisp | |
557 | (setq idlwave-reserved-word-upcase t) | |
558 | @end lisp | |
559 | ||
560 | When this option is turned on, each reserved word you type into an IDL | |
561 | source buffer will be converted to upper case when you press @key{SPC} | |
562 | or @key{RET} right after the word. Try it out! @samp{if} changes to | |
563 | @samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this | |
564 | behavior, remove the option again from your @file{.emacs} file. | |
565 | ||
5af23035 S |
566 | You likely have your own indentation preferences for IDL code. For |
567 | example, some like to indent the main block of an IDL program from the | |
568 | margin, different from the conventions used by RSI, and use only 3 | |
569 | spaces as indentation between @code{BEGIN} and @code{END}. Try the | |
570 | following lines in @file{.emacs}: | |
aea44e56 CD |
571 | |
572 | @lisp | |
573 | (setq idlwave-main-block-indent 2) | |
574 | (setq idlwave-block-indent 3) | |
575 | (setq idlwave-end-offset -3) | |
576 | @end lisp | |
577 | ||
5af23035 S |
578 | Restart Emacs, and re-indent the program we developed in the first part |
579 | of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may want to keep | |
580 | these lines in @file{.emacs}, with values adjusted to your likings. If | |
581 | you want to get more information about any of these variables, type, | |
582 | e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. To find which | |
583 | variables can be customized, look for items marked @samp{User Option:} | |
584 | throughout this manual. | |
585 | ||
586 | If you cannot seem to master this Lisp customization in @file{.emacs}, | |
587 | there is another, more user-friendly way to customize all the IDLWAVE | |
588 | variables. You can access it through the IDLWAVE menu in one of the | |
589 | @file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE | |
590 | Group}. Here you'll be presented with all the various variables grouped | |
591 | into categories. You can navigate the hierarchy (e.g. Idlwave Code | |
592 | Formatting->Idlwave Main Block Indent), read about the variables, change | |
593 | them, and `Save for Future Sessions'. Few of these variables need | |
594 | customization, but you can exercise considerable control over IDLWAVE's | |
595 | functionality with them. | |
596 | ||
597 | You may also find the key bindings used for the debugging commands too | |
598 | long and complicated. Often we have heard such complaints, ``Do I | |
599 | really have to type @kbd{C-c C-d C-c} to run a simple command?'' Due to | |
600 | Emacs rules and conventions, shorter bindings cannot be set by default, | |
601 | but you can enable them. First, there is a way to assign all debugging | |
602 | commands in a single sweep to other combinations. The only problem is | |
603 | that we have to use something which Emacs does not need for other | |
604 | important commands. One good option is to execute debugging commands by | |
605 | holding down @key{CONTROL} and @key{SHIFT} while pressing a single | |
606 | character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for | |
607 | compiling the current source file, @kbd{C-S-a} for deleting all | |
608 | breakpoints. You can enable this with: | |
aea44e56 CD |
609 | |
610 | @lisp | |
611 | (setq idlwave-shell-debug-modifiers '(shift control)) | |
612 | @end lisp | |
613 | ||
5af23035 S |
614 | @noindent If you have a special keyboard with, for example, a |
615 | @key{HYPER} key, you could even shorten that: | |
aea44e56 CD |
616 | |
617 | @lisp | |
618 | (setq idlwave-shell-debug-modifiers '(hyper)) | |
619 | @end lisp | |
620 | ||
5af23035 S |
621 | @noindent to get compilation on @kbd{H-c}. Often, a modifier key like |
622 | @key{HYPER} or @key{SUPER} is bound or can be bound to an otherwise | |
623 | unused key -- consult your system documentation. | |
aea44e56 | 624 | |
5af23035 S |
625 | You can also assign specific commands to keys. This you must do in the |
626 | @emph{mode-hook}, a special function which is run when a new buffer gets | |
627 | set up. Keybindings can only be done when the buffer exists. The | |
628 | possibilities for key customization are endless. Here we set function | |
629 | keys f5-f8 to common debugging commands. | |
aea44e56 CD |
630 | |
631 | @lisp | |
632 | ;; First for the source buffer | |
633 | (add-hook 'idlwave-mode-hook | |
634 | (lambda () | |
635 | (local-set-key [f5] 'idlwave-shell-break-here) | |
636 | (local-set-key [f6] 'idlwave-shell-clear-current-bp) | |
637 | (local-set-key [f7] 'idlwave-shell-cont) | |
638 | (local-set-key [f8] 'idlwave-shell-clear-all-bp))) | |
639 | ;; Then for the shell buffer | |
640 | (add-hook 'idlwave-shell-mode-hook | |
641 | (lambda () | |
642 | (local-set-key [f5] 'idlwave-shell-break-here) | |
643 | (local-set-key [f6] 'idlwave-shell-clear-current-bp) | |
644 | (local-set-key [f7] 'idlwave-shell-cont) | |
645 | (local-set-key [f8] 'idlwave-shell-clear-all-bp))) | |
646 | @end lisp | |
647 | ||
5af23035 S |
648 | @node Lesson III -- Library Catalog, , Lesson II -- Customization, Getting Started |
649 | @section Lesson III: Library Catalog | |
aea44e56 CD |
650 | |
651 | We have already used the routine info display in the first part of this | |
177c0ea7 | 652 | tutorial. This was the key @kbd{C-c ?} which displays information about |
aea44e56 CD |
653 | the IDL routine near the cursor position. Wouldn't it be nice |
654 | to have the same available for your own library routines and for the | |
655 | huge amount of code in major extension libraries like JHUPL or the | |
656 | IDL-Astro library? To do this, you must give IDLWAVE a chance to study | |
657 | these routines first. We call this @emph{Building the library catalog}. | |
658 | ||
659 | From the IDLWAVE entry in the menu bar, select @code{Routine Info/Select | |
660 | Catalog Directories}. If necessary, start the shell first with @kbd{C-c | |
661 | C-s} (@pxref{Starting the Shell}). IDLWAVE will find out about the IDL | |
662 | @code{!PATH} variable and offer a list of directories on the path. | |
663 | Simply select them all (or whichever you want) and click on the | |
664 | @samp{Scan&Save} button. Then go for a cup of coffee while IDLWAVE | |
665 | collects information for each and every IDL routine on your search path. | |
666 | All this information is written to the file @file{.idlcat} in your home | |
667 | directory and will from now one be automatically loaded whenever you use | |
5af23035 S |
668 | IDLWAVE. You may find it necessary to rebuild the catalog on occasion |
669 | as your local libraries change. Try to use routine info (@kbd{C-c ?}) | |
670 | or completion (@kbd{M-@key{TAB}}) while on any routine or partial routine | |
671 | name you know to be located in the library. E.g., if you have scanned | |
672 | the IDL-Astro library: | |
aea44e56 CD |
673 | |
674 | @example | |
675 | a=readf@key{M-<TAB>} | |
676 | @end example | |
677 | ||
678 | ||
679 | expands to `readfits('. Then try | |
680 | ||
681 | @example | |
682 | a=readfits(@key{C-c ?} | |
683 | @end example | |
684 | ||
685 | and you get: | |
686 | ||
687 | @example | |
688 | Usage: Result = READFITS(filename, header, heap) | |
689 | ... | |
690 | @end example | |
691 | ||
692 | I hope you made it until here. Now you are set to work with IDLWAVE. | |
693 | On the way you will want to change other things, and to learn more about | |
694 | the possibilities not discussed in this short tutorial. Read the | |
695 | manual, look at the documentation strings of interesting variables (with | |
696 | @kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining | |
5af23035 | 697 | questions on the newsgroup @code{comp.lang.idl-pvwave}. |
aea44e56 CD |
698 | |
699 | @node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top | |
797c8ebc CD |
700 | @chapter The IDLWAVE Major Mode |
701 | @cindex IDLWAVE major mode | |
702 | @cindex Major mode, @code{idlwave-mode} | |
703 | ||
5af23035 S |
704 | The IDLWAVE major mode supports editing IDL source files. In this |
705 | chapter we describe the main features of the mode and how to customize | |
706 | them. | |
797c8ebc CD |
707 | |
708 | @menu | |
709 | * Code Formatting:: Making code look nice | |
a8e833f3 CD |
710 | * Routine Info:: Calling Sequence and Keyword List |
711 | * Online Help:: One key press from source to help | |
797c8ebc | 712 | * Completion:: Completing routine names and Keywords |
5af23035 | 713 | * Routine Source:: Finding routines, the easy way |
a8e833f3 | 714 | * Resolving Routines:: Force the Shell to compile a routine |
5af23035 S |
715 | * Code Templates:: Frequent code constructs |
716 | * Abbreviations:: Abbreviations for common commands | |
797c8ebc CD |
717 | * Actions:: Changing case, Padding, End checking |
718 | * Doc Header:: Inserting a standard header | |
719 | * Motion Commands:: Moving through the structure of a program | |
720 | * Misc Options:: Things that fit nowhere else | |
721 | @end menu | |
722 | ||
723 | @node Code Formatting, Routine Info, The IDLWAVE Major Mode, The IDLWAVE Major Mode | |
724 | @section Code Formatting | |
725 | @cindex Code formatting | |
726 | @cindex Formatting, of code | |
727 | ||
728 | @menu | |
729 | * Code Indentation:: Reflecting the logical structure | |
177c0ea7 | 730 | * Continued Statement Indentation:: |
797c8ebc CD |
731 | * Comment Indentation:: Special indentation for comment lines |
732 | * Continuation Lines:: Splitting statements over lines | |
733 | * Syntax Highlighting:: Font-lock support | |
5af23035 | 734 | * Octals and Highlighting:: Why "123 causes problems |
797c8ebc CD |
735 | @end menu |
736 | ||
5af23035 S |
737 | The IDL language, with it's early roots in FORTRAN, modern |
738 | implementation in C, and liberal borrowing of features of many vector | |
739 | languages along its 25+ year history, has inherited an unusual mix of | |
740 | syntax elements. Left to his or her own devices, a novice IDL | |
741 | programmer will often conjure code which is very difficult to read and | |
742 | impossible to adapt. Much can be gleaned from studying available IDL | |
76959b77 S |
743 | code libraries for coding style pointers, but, due to the variety of |
744 | IDL syntax elements, replicating this style can be challenging at | |
745 | best. Luckily, IDLWAVE understands the structure of IDL code very | |
746 | well, and takes care of almost all formatting issues for you. After | |
747 | configuring it to match your coding standards, you can rely on it to | |
748 | help keep your code neat and organized. | |
797c8ebc CD |
749 | |
750 | @cindex Foreign code, adapting | |
751 | @cindex Indentation, of foreign code | |
718fb8a1 | 752 | @kindex C-M-\ |
797c8ebc | 753 | To re-indent a larger portion of code (e.g. when working with foreign code |
718fb8a1 | 754 | written with different conventions), use @kbd{C-M-\} |
797c8ebc | 755 | (@code{indent-region}) after marking the relevant code. Useful marking |
718fb8a1 | 756 | commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the |
797c8ebc CD |
757 | current subprogram). @xref{Actions}, for information how to impose |
758 | additional formatting conventions on foreign code. | |
759 | ||
5af23035 S |
760 | @node Code Indentation, Continued Statement Indentation, Code Formatting, Code Formatting |
761 | @subsection Code Indentation | |
762 | @cindex Code indentation | |
763 | @cindex Indentation | |
764 | ||
765 | Like all Emacs programming modes, IDLWAVE performs code indentation. | |
766 | The @key{TAB} key indents the current line relative to context. | |
767 | @key{LFD} insert a newline and indents the new line. The indentation is | |
768 | governed by a number of variables. IDLWAVE indents blocks (between | |
769 | @code{PRO}/@code{FUNCTION}/@code{BEGIN} and @code{END}), and | |
770 | continuation lines. | |
771 | ||
177c0ea7 | 772 | @defopt idlwave-main-block-indent (@code{0}) |
797c8ebc CD |
773 | Extra indentation for the main block of code. That is the block between |
774 | the FUNCTION/PRO statement and the END statement for that program | |
a8e833f3 | 775 | unit. |
797c8ebc CD |
776 | @end defopt |
777 | ||
5af23035 | 778 | @defopt idlwave-block-indent (@code{4}) |
797c8ebc | 779 | Extra indentation applied to block lines. If you change this, you |
a8e833f3 | 780 | probably also want to change @code{idlwave-end-offset}. |
797c8ebc CD |
781 | @end defopt |
782 | ||
783 | @defopt idlwave-end-offset (@code{-4}) | |
784 | Extra indentation applied to block END lines. A value equal to negative | |
785 | @code{idlwave-block-indent} will make END lines line up with the block | |
a8e833f3 | 786 | BEGIN lines. |
797c8ebc CD |
787 | @end defopt |
788 | ||
5af23035 S |
789 | @node Continued Statement Indentation, Comment Indentation, Code Indentation, Code Formatting |
790 | @subsection Continued Statement Indentation | |
791 | @cindex Indentation, continued statement | |
792 | @cindex Continued statement indentation | |
793 | Continuation lines (following a line ending with @code{$}) can receive a | |
794 | fixed indentation offset from the main level, but in several situations | |
795 | IDLWAVE can use a special form of indentation which aligns continued | |
796 | statements more naturally. Special indentation is calculated for | |
797 | continued routine definition statements and calls, enclosing parentheses | |
798 | (like function calls, structure/class definitions, explicit structures | |
799 | or lists, etc.), and continued assignments. An attempt is made to line | |
800 | up with the first non-whitespace character after the relevant opening | |
801 | punctuation mark (@code{,},@code{(},@code{@{},@code{[},@code{=}). For | |
802 | lines without any non-comment characters on the line with the opening | |
803 | punctuation, the continued line(s) are aligned just past the | |
804 | punctuation. An example: | |
805 | ||
806 | @example | |
807 | function foo, a, b, $ | |
808 | c, d | |
809 | bar = sin( a + b + $ | |
810 | c + d) | |
811 | end | |
812 | @end example | |
813 | @noindent | |
814 | ||
815 | The only drawback to this special continued statement indentation is | |
816 | that it consumes more space, e.g., for long function names or left hand | |
817 | sides of an assignment: | |
818 | ||
819 | @example | |
820 | function thisfunctionnameisverylongsoitwillleavelittleroom, a, b, $ | |
821 | c, d | |
822 | @end example | |
823 | ||
76959b77 | 824 | You can instruct IDLWAVE when to avoid using this special continuation |
5af23035 S |
825 | indentation by setting the variable |
826 | @code{idlwave-max-extra-continuation-indent}, which specifies the | |
76959b77 S |
827 | maximum additional indentation beyond the basic indent to be |
828 | tolerated, otherwise defaulting to a fixed-offset from the enclosing | |
829 | indent (the size of which offset is set in | |
830 | @code{idlwave-continuation-indent}). Also, since the indentation | |
831 | level can be somewhat dynamic in continued statements with special | |
832 | continuation indentation, especially if | |
833 | @code{idlwave-max-extra-continuation-indent} is small, the key | |
834 | @kbd{C-u @key{TAB}} will re-indent all lines in the current statement. | |
835 | Note that @code{idlwave-indent-to-open-paren}, if non-nil, overrides | |
836 | the @code{idlwave-max-extra-continuation-indent} limit, for | |
837 | parentheses only, forcing them always to line up. | |
5af23035 S |
838 | |
839 | ||
797c8ebc | 840 | @defopt idlwave-continuation-indent (@code{2}) |
5af23035 S |
841 | Extra indentation applied to normal continuation lines. |
842 | @end defopt | |
843 | ||
844 | @defopt idlwave-max-extra-continuation-indent (@code{20}) | |
845 | The maximum additional indentation (over the basic continuation-indent) | |
846 | that will be permitted for special continues. To effectively disable | |
847 | special continuation indentation, set to @code{0}. To enable it | |
848 | constantly, set to a large number (like @code{100}). Note that the | |
849 | indentation in a long continued statement never decreases from line to | |
850 | line, outside of nested parentheses statements. | |
851 | @end defopt | |
852 | ||
853 | @defopt idlwave-indent-to-open-paren (@code{t}) | |
854 | Non-@code{nil} means indent continuation lines to innermost open | |
855 | parenthesis, regardless of whether the | |
856 | @code{idlwave-max-extra-continuation-indent} limit is satisfied. | |
797c8ebc CD |
857 | @end defopt |
858 | ||
5af23035 | 859 | @node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting |
797c8ebc CD |
860 | @subsection Comment Indentation |
861 | @cindex Comment indentation | |
862 | @cindex Hanging paragraphs | |
863 | @cindex Paragraphs, filling | |
864 | @cindex Paragraphs, hanging | |
865 | ||
866 | In IDL, lines starting with a @samp{;} are called @emph{comment lines}. | |
867 | Comment lines are indented as follows: | |
868 | ||
869 | @multitable @columnfractions .1 .90 | |
870 | @item @code{;;;} | |
871 | @tab The indentation of lines starting with three semicolons remains | |
872 | unchanged. | |
873 | @item @code{;;} | |
874 | @tab Lines starting with two semicolons are indented like the surrounding code. | |
875 | @item @code{;} | |
76959b77 | 876 | @tab Lines starting with a single semicolon are indented to a minimum column. |
797c8ebc CD |
877 | @end multitable |
878 | ||
a8e833f3 | 879 | @noindent |
797c8ebc CD |
880 | The indentation of comments starting in column 0 is never changed. |
881 | ||
882 | @defopt idlwave-no-change-comment | |
5af23035 S |
883 | The indentation of a comment starting with this regexp will not be |
884 | changed. | |
797c8ebc CD |
885 | @end defopt |
886 | ||
887 | @defopt idlwave-begin-line-comment | |
a8e833f3 | 888 | A comment anchored at the beginning of line. |
797c8ebc CD |
889 | @end defopt |
890 | ||
891 | @defopt idlwave-code-comment | |
a8e833f3 CD |
892 | A comment that starts with this regexp is indented as if it is a part of |
893 | IDL code. | |
797c8ebc CD |
894 | @end defopt |
895 | ||
896 | @node Continuation Lines, Syntax Highlighting, Comment Indentation, Code Formatting | |
897 | @subsection Continuation Lines and Filling | |
898 | @cindex Continuation lines | |
899 | @cindex Line splitting | |
a8e833f3 | 900 | @cindex String splitting |
797c8ebc | 901 | @cindex Splitting, of lines |
797c8ebc | 902 | |
a8e833f3 | 903 | @kindex M-@key{RET} |
797c8ebc CD |
904 | In IDL, a newline character terminates a statement unless preceded by a |
905 | @samp{$}. If you would like to start a continuation line, use | |
5af23035 S |
906 | @kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}. |
907 | It inserts the continuation character @samp{$}, terminates the line and | |
908 | indents the new line. The command @kbd{M-@key{RET}} can also be invoked | |
909 | inside a string to split it at that point, in which case the @samp{+} | |
910 | concatenation operator is used. | |
797c8ebc | 911 | |
a8e833f3 CD |
912 | @cindex Filling |
913 | @cindex @code{auto-fill-mode} | |
914 | @cindex Hanging paragraphs | |
797c8ebc | 915 | When filling comment paragraphs, IDLWAVE overloads the normal filling |
5af23035 S |
916 | functions and uses a function which creates the hanging paragraphs |
917 | customary in IDL routine headers. When @code{auto-fill-mode} is turned | |
918 | on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If the | |
919 | first line of a paragraph contains a match for | |
920 | @code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent | |
921 | lines are positioned to line up after it, as in the following example. | |
797c8ebc CD |
922 | |
923 | @example | |
5af23035 S |
924 | @group |
925 | ;================================= | |
797c8ebc CD |
926 | ; x - an array containing |
927 | ; lots of interesting numbers. | |
928 | ; | |
929 | ; y - another variable where | |
930 | ; a hanging paragraph is used | |
931 | ; to describe it. | |
5af23035 S |
932 | ;================================= |
933 | @end group | |
797c8ebc CD |
934 | @end example |
935 | ||
a8e833f3 | 936 | @kindex M-q |
5af23035 S |
937 | You can also refill a comment at any time paragraph with @kbd{M-q}. |
938 | Comment delimiting lines as in the above example, consisting of one or | |
939 | more @samp{;} followed by one or more of the characters @samp{+=-_*}, | |
940 | are kept in place, as is. | |
797c8ebc CD |
941 | |
942 | @defopt idlwave-fill-comment-line-only (@code{t}) | |
943 | Non-@code{nil} means auto fill will only operate on comment lines. | |
944 | @end defopt | |
945 | ||
946 | @defopt idlwave-auto-fill-split-string (@code{t}) | |
947 | Non-@code{nil} means auto fill will split strings with the IDL @samp{+} | |
948 | operator. | |
949 | @end defopt | |
950 | ||
951 | @defopt idlwave-split-line-string (@code{t}) | |
952 | Non-@code{nil} means @code{idlwave-split-line} will split strings with | |
953 | @samp{+}. | |
954 | @end defopt | |
955 | ||
a8e833f3 | 956 | @defopt idlwave-hanging-indent (@code{t}) |
797c8ebc CD |
957 | Non-@code{nil} means comment paragraphs are indented under the hanging |
958 | indent given by @code{idlwave-hang-indent-regexp} match in the first | |
a8e833f3 | 959 | line of the paragraph. |
797c8ebc CD |
960 | @end defopt |
961 | ||
5af23035 | 962 | @defopt idlwave-hang-indent-regexp (@code{"- "}) |
797c8ebc | 963 | Regular expression matching the position of the hanging indent |
a8e833f3 | 964 | in the first line of a comment paragraph. |
797c8ebc CD |
965 | @end defopt |
966 | ||
967 | @defopt idlwave-use-last-hang-indent (@code{nil}) | |
968 | Non-@code{nil} means use last match on line for | |
177c0ea7 | 969 | @code{idlwave-indent-regexp}. |
797c8ebc CD |
970 | @end defopt |
971 | ||
5af23035 | 972 | @node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting |
797c8ebc CD |
973 | @subsection Syntax Highlighting |
974 | @cindex Syntax highlighting | |
a8e833f3 | 975 | @cindex Highlighting of syntax |
797c8ebc CD |
976 | @cindex Font lock |
977 | ||
978 | Highlighting of keywords, comments, strings etc. can be accomplished | |
a8e833f3 | 979 | with @code{font-lock}. If you are using @code{global-font-lock-mode} |
5af23035 S |
980 | (in Emacs), or have @code{font-lock} turned on in any other buffer in |
981 | XEmacs, it should also automatically work in IDLWAVE buffers. If you'd | |
982 | prefer invoking font-lock individually by mode, you can enforce it in | |
983 | @code{idlwave-mode} with the following line in your @file{.emacs}: | |
797c8ebc CD |
984 | |
985 | @lisp | |
986 | (add-hook 'idlwave-mode-hook 'turn-on-font-lock) | |
987 | @end lisp | |
988 | ||
5af23035 S |
989 | @noindent IDLWAVE supports 3 increasing levels of syntax highlighting. |
990 | The variable @code{font-lock-maximum-decoration} determines which level | |
991 | is selected. Individual categories of special tokens can be selected | |
992 | for highlighting using the variable | |
993 | @code{idlwave-default-font-lock-items}. | |
797c8ebc CD |
994 | |
995 | @defopt idlwave-default-font-lock-items | |
996 | Items which should be fontified on the default fontification level | |
177c0ea7 | 997 | 2. |
797c8ebc CD |
998 | @end defopt |
999 | ||
5af23035 S |
1000 | @node Octals and Highlighting, , Syntax Highlighting, Code Formatting |
1001 | @subsection Octals and Highlighting | |
1002 | @cindex Syntax highlighting, Octals | |
1003 | @cindex Highlighting of syntax, Octals | |
1004 | ||
1005 | A rare syntax highlighting problem results from the extremely | |
1006 | unfortunate notation for octal numbers in IDL: @code{"123}. This | |
1007 | unpaired quotation mark is very difficult to parse, given that it can be | |
1008 | mixed on a single line with any number of strings. Emacs will | |
1009 | incorrectly identify this as a string, and the highlighting of following | |
1010 | lines of code can be distorted, since the string is never terminated. | |
1011 | ||
1012 | One solution to this involves terminating the mistakenly identified | |
1013 | string yourself by providing a closing quotation mark in a comment: | |
1014 | ||
1015 | @example | |
1016 | string("305B) + $ ;" <--- for font-lock | |
1017 | ' is an Angstrom.' | |
1018 | @end example | |
1019 | ||
1020 | @noindent A far better solution is to abandon this notation for octals | |
1021 | altogether, and use the more sensible alternative IDL provides: | |
1022 | ||
1023 | @example | |
1024 | string('305'OB) + ' is an Angstrom.' | |
1025 | @end example | |
1026 | ||
1027 | @noindent This simultaneously solves the font-lock problem and is more | |
1028 | consistent with the notation for hexadecimal numbers, e.g. @code{'C5'XB}. | |
1029 | ||
a8e833f3 | 1030 | @node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode |
797c8ebc CD |
1031 | @section Routine Info |
1032 | @cindex Routine info | |
a8e833f3 CD |
1033 | @cindex Updating routine info |
1034 | @cindex Scanning buffers for routine info | |
1035 | @cindex Buffers, scanning for routine info | |
1036 | @cindex Shell, querying for routine info | |
797c8ebc | 1037 | |
a8e833f3 | 1038 | @kindex C-c C-i |
76959b77 S |
1039 | IDL comes bundled with more than one thousand procedures, functions |
1040 | and object methods, and large libraries typically contain hundreds or | |
1041 | even thousands more (each with a few to tens of keywords and | |
1042 | arguments). This large command set can make it difficult to remember | |
1043 | the calling sequence and keywords for the routines you use, but | |
1044 | IDLWAVE can help. It builds up routine information using a wide | |
1045 | variety of sources: IDLWAVE in fact knows far more about the routines | |
1046 | on your system than IDL itself. It maintains a list of all built-in | |
1047 | routines, with calling sequences and keywords@footnote{This list is | |
1048 | created by scanning the IDL manuals and might contain (very few) | |
1049 | errors. Please report any errors to the maintainer, so that they can | |
1050 | be fixed.}. It also scans Emacs buffers and library files for routine | |
1051 | definitions, and queries the IDLWAVE-Shell for information about | |
1052 | routines currently compiled there. This information is updated | |
1053 | automatically, and so should usually be current. To force a global | |
1054 | update and refresh the routine information, use @kbd{C-c C-i} | |
1055 | (@code{idlwave-update-routine-info}). | |
797c8ebc | 1056 | |
a8e833f3 | 1057 | @kindex C-c ? |
5af23035 | 1058 | To display the information about a routine, press @kbd{C-c ?}, which |
797c8ebc CD |
1059 | calls the command @code{idlwave-routine-info}. When the current cursor |
1060 | position is on the name or in the argument list of a procedure or | |
1061 | function, information will be displayed about the routine. For example, | |
5af23035 | 1062 | consider the indicated cursor positions in the following line: |
797c8ebc CD |
1063 | |
1064 | @example | |
1065 | plot,x,alog(x+5*sin(x) + 2), | |
5af23035 | 1066 | | | | | | | | | |
797c8ebc CD |
1067 | 1 2 3 4 5 6 7 8 |
1068 | @end example | |
1069 | ||
a8e833f3 | 1070 | @cindex Default routine, for info and help |
797c8ebc CD |
1071 | On positions 1,2 and 8, information about the @samp{plot} procedure will |
1072 | be shown. On positions 3,4, and 7, the @samp{alog} function will be | |
5af23035 | 1073 | described, while positions 5 and 6 will investigate the @samp{sin} |
177c0ea7 | 1074 | function. |
5af23035 | 1075 | |
797c8ebc CD |
1076 | When you ask for routine information about an object method, and the |
1077 | method exists in several classes, IDLWAVE queries for the class of the | |
5af23035 S |
1078 | object, unless the class is already known through a text property on the |
1079 | @samp{->} operator (@pxref{Object Method Completion and Class | |
28665d46 | 1080 | Ambiguity}), or by having been explicitly included in the call |
5af23035 | 1081 | (e.g. @code{a->myclass::Foo}). |
797c8ebc CD |
1082 | |
1083 | @cindex Calling sequences | |
1084 | @cindex Keywords of a routine | |
a8e833f3 | 1085 | @cindex Routine source information |
797c8ebc | 1086 | The description displayed contains the calling sequence, the list of |
a8e833f3 | 1087 | keywords and the source location of this routine. It looks like this: |
797c8ebc CD |
1088 | |
1089 | @example | |
a8e833f3 CD |
1090 | Usage: XMANAGER, NAME, ID |
1091 | Keywords: BACKGROUND CATCH CLEANUP EVENT_HANDLER GROUP_LEADER | |
1092 | JUST_REG MODAL NO_BLOCK | |
1093 | Source: SystemLib [CSB] /soft1/idl53/lib/xmanager.pro | |
797c8ebc CD |
1094 | @end example |
1095 | ||
a8e833f3 CD |
1096 | @cindex Categories, of routines |
1097 | @cindex Load-path shadows | |
1098 | @cindex Shadows, load-path | |
1099 | @cindex IDL variable @code{!PATH} | |
1100 | @cindex @code{!PATH}, IDL variable | |
1101 | @cindex IDL variable @code{!DIR} | |
1102 | @cindex @code{!DIR}, IDL variable | |
1103 | ||
1104 | If a definition of this routine exists in several files accessible to | |
1105 | IDLWAVE, several @samp{Source} lines will point to the different files. | |
1106 | This may indicate that your routine is shadowing a library routine, | |
1107 | which may or may not be what you want (@pxref{Load-Path Shadows}). The | |
5af23035 S |
1108 | information about the calling sequence and keywords is derived from the |
1109 | first source listed. Library routines are supported only if you have | |
1110 | scanned your local IDL libraries (@pxref{Library Catalog}). The source | |
a8e833f3 | 1111 | entry consists of a @emph{source category}, a set of @emph{flags} and |
5af23035 | 1112 | the path to the @emph{source file}. The following categories exist: |
a8e833f3 CD |
1113 | |
1114 | @multitable @columnfractions .15 .85 | |
1115 | @item @i{System} | |
5af23035 S |
1116 | @tab A system routine of unknown origin. When the system library has |
1117 | been scanned (@pxref{Library Catalog}), this category will automatically | |
1118 | split into the next two. | |
a8e833f3 | 1119 | @item @i{Builtin} |
5af23035 | 1120 | @tab A builtin system routine with no source code available. |
a8e833f3 | 1121 | @item @i{SystemLib} |
5af23035 | 1122 | @tab A library system routine in the official lib directory @file{!DIR/lib}. |
a8e833f3 CD |
1123 | @item @i{Obsolete} |
1124 | @tab A library routine in the official lib directory @file{!DIR/lib/obsolete}. | |
1125 | @item @i{Library} | |
5af23035 | 1126 | @tab A routine in a file on IDL's search path @code{!PATH}. |
a8e833f3 | 1127 | @item @i{Other} |
5af23035 | 1128 | @tab Any other routine with a file not known to be on the search path. |
a8e833f3 | 1129 | @item @i{Unresolved} |
177c0ea7 | 1130 | @tab An otherwise unkown routine the shell lists as unresolved |
5af23035 | 1131 | (referenced, but not compiled). |
a8e833f3 CD |
1132 | @end multitable |
1133 | ||
5af23035 S |
1134 | You can create additional categories based on the routine's filepath |
1135 | with the variable @code{idlwave-special-lib-alist}. This is useful for | |
1136 | easy discrimination of various libraries, or even versions of the same | |
1137 | library. | |
a8e833f3 CD |
1138 | |
1139 | @cindex Flags, in routine info | |
1140 | @cindex Duplicate routines | |
1141 | @cindex Multiply defined routines | |
1142 | @cindex Routine definitions, multiple | |
5af23035 S |
1143 | The flags @code{[CSB]} indicate the source of the information IDLWAVE |
1144 | has regarding the file: from a library catalog (@w{@code{[C--]}}, | |
1145 | @pxref{Library Catalog}), from the IDL Shell (@w{@code{[-S-]}}) or from | |
1146 | an Emacs buffer (@w{@code{[--B]}}). Combinations are possible (a | |
1147 | compiled library routine visited in a buffer might read | |
1148 | @w{@code{[CSB]}}). If a file contains multiple definitions of the same | |
1149 | routine, the file name will be prefixed with @samp{(Nx)} where @samp{N} | |
1150 | is the number of definitions. | |
a8e833f3 CD |
1151 | |
1152 | @cindex Online Help from the routine info buffer | |
1153 | @cindex Active text, in routine info | |
1154 | @cindex Inserting keywords, from routine info | |
1155 | @cindex Source file, access from routine info | |
5af23035 S |
1156 | Some of the text in the @file{*Help*} routine info buffer will be active |
1157 | (it is highlighted when the mouse moves over it). Typically, clicking | |
1158 | with the right mouse button invokes online help lookup, and clicking | |
1159 | with the middle mouse button inserts keywords or visits files: | |
a8e833f3 CD |
1160 | |
1161 | @multitable @columnfractions 0.15 0.85 | |
1162 | @item @i{Usage} | |
1163 | @tab If online help is installed, a click with the @emph{right} mouse | |
1164 | button on the @i{Usage:} line will access the help for the | |
177c0ea7 | 1165 | routine (@pxref{Online Help}). |
a8e833f3 CD |
1166 | @item @i{Keyword} |
1167 | @tab Online help about keywords is also available with the | |
1168 | @emph{right} mouse button. Clicking on a keyword with the @emph{middle} | |
1169 | mouse button will insert this keyword in the buffer from where | |
1170 | @code{idlwave-routine-info} was called. Holding down @key{SHIFT} while | |
1171 | clicking also adds the initial @samp{/}. | |
1172 | @item @i{Source} | |
1173 | @tab Clicking with the @emph{middle} mouse button on a @samp{Source} line | |
1174 | finds the source file of the routine and visits it in another window. | |
1175 | Another click on the same line switches back to the buffer from which | |
1176 | @kbd{C-c ?} was called. If you use the @emph{right} mouse button, the | |
1177 | source will not be visited by a buffer, but displayed in the online help | |
1178 | window. | |
aea44e56 CD |
1179 | @item @i{Classes} |
1180 | @tab The @i{Classes} line is only included in the routine info window if | |
1181 | the current class inherits from other classes. You can click with the | |
1182 | @emph{middle} mouse button to display routine info about the current | |
5af23035 S |
1183 | method in other classes on the inheritance chain, if such a method |
1184 | exists there. | |
a8e833f3 | 1185 | @end multitable |
797c8ebc | 1186 | |
a8e833f3 | 1187 | @defopt idlwave-resize-routine-help-window (@code{t}) |
5af23035 | 1188 | Non-@code{nil} means resize the Routine-info @file{*Help*} window to |
a8e833f3 CD |
1189 | fit the content. |
1190 | @end defopt | |
797c8ebc | 1191 | |
a8e833f3 CD |
1192 | @defopt idlwave-special-lib-alist |
1193 | Alist of regular expressions matching special library directories. | |
1194 | @end defopt | |
797c8ebc | 1195 | |
a8e833f3 CD |
1196 | @defopt idlwave-rinfo-max-source-lines (@code{5}) |
1197 | Maximum number of source files displayed in the Routine Info window. | |
1198 | @end defopt | |
797c8ebc | 1199 | |
797c8ebc | 1200 | |
a8e833f3 CD |
1201 | @node Online Help, Completion, Routine Info, The IDLWAVE Major Mode |
1202 | @section Online Help | |
1203 | ||
1204 | @cindex Online Help | |
1205 | @cindex @file{idlw-help.txt} | |
1206 | @cindex @file{idlw-help.el} | |
1207 | @cindex IDL manual, ASCII version | |
1208 | @cindex Installing online help | |
1209 | @cindex Online Help, Installation | |
1210 | @cindex Speed, of online help | |
1211 | For IDL system routines, RSI provides extensive documentation. IDLWAVE | |
1212 | can access an ASCII version of this documentation very quickly and | |
1213 | accurately. This is @emph{much} faster than using the IDL online help | |
76959b77 S |
1214 | application, because IDLWAVE usually gets you to the right place in the |
1215 | documentation directly, without any additional browsing and scrolling. | |
1216 | For this online help to work, an ASCII version of the IDL documentation, | |
1217 | which is not part of the standalone IDLWAVE distribution, is required. | |
1218 | The necessary help files can be downloaded from | |
5af23035 S |
1219 | @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. The text |
1220 | extracted from the PDF files is fine for normal documentation | |
1221 | paragraphs, but graphics and multiline equations will not be well | |
1222 | formatted. See also @ref{Documentation Scan}. | |
1223 | ||
1224 | @cindex Updated online help | |
1225 | @cindex Online help, updates | |
1226 | @cindex @code{<NEW>..</NEW>} | |
1227 | Occasionally RSI releases a synopsis of new features in an IDL release, | |
1228 | without simultaneously updating the documentation files, instead | |
1229 | preferring a @i{What's New} document which describes the changes. These | |
1230 | updates are incorporated directly into the IDLWAVE online help, and are | |
1231 | delimited in @code{<NEW>..</NEW>} blocks. | |
a8e833f3 CD |
1232 | |
1233 | @cindex Source code, as online help | |
1234 | @cindex DocLib header, as online help | |
1235 | For routines which are not documented in the IDL manual (for example | |
76959b77 S |
1236 | personal or library routines), the source code itself is used as help |
1237 | text. If the requested information can be found in a (more or less) | |
1238 | standard DocLib file header, IDLWAVE shows the header (scrolling down to | |
1239 | appropriate keyword). Otherwise the routine definition statement | |
5af23035 | 1240 | (@code{pro}/@code{function}) is shown. |
a8e833f3 | 1241 | |
76959b77 S |
1242 | @cindex Structure tags, in online help |
1243 | @cindex Class tags, in online help | |
1244 | Help is also available for class structure tags (@code{self.TAG}), and | |
1245 | generic structure tags, if structure tag completion is enabled | |
1246 | (@pxref{Structure Tag Completion}). This is implemented by visiting the | |
1247 | tag within the class or structure definition source itself. Help is not | |
1248 | available on built-in system class tags. | |
1249 | ||
a8e833f3 | 1250 | @kindex M-? |
5af23035 S |
1251 | In any IDL program (or, as with most IDLWAVE commands, in the IDL |
1252 | Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with | |
32d4cddb | 1253 | @kbd{S-Mouse-3} to access context sensitive online help. The following |
5af23035 | 1254 | locations are recognized context for help: |
a8e833f3 CD |
1255 | |
1256 | @cindex Context, for online help | |
1257 | @multitable @columnfractions .25 .75 | |
1258 | @item @i{Routine name} | |
1259 | @tab The name of a routine (function, procedure, method). | |
1260 | @item @i{Keyword Parameter} | |
5af23035 | 1261 | @tab A keyword parameter of a routine. |
a8e833f3 | 1262 | @item @i{System Variable} |
5af23035 | 1263 | @tab System variables like @code{!DPI}. |
a8e833f3 | 1264 | @item @i{IDL Statement} |
5af23035 | 1265 | @tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. |
a8e833f3 | 1266 | @item @i{Class name} |
5af23035 S |
1267 | @tab A class name in an @code{OBJ_NEW} call. |
1268 | @item @i{Class Init} | |
1269 | @tab Beyond the class name in an @code{OBJ_NEW} call. | |
a8e833f3 | 1270 | @item @i{Executive Command} |
5af23035 | 1271 | @tab An executive command like @code{.RUN}. Mostly useful in the shell. |
76959b77 S |
1272 | @item @i{Structure Tags} |
1273 | @tab In structure tags like @code{state.xsize} | |
1274 | @item @i{Structure Tags} | |
1275 | @tab In class tags like @code{self.value}. | |
a8e833f3 CD |
1276 | @item @i{Default} |
1277 | @tab The routine that would be selected for routine info display. | |
1278 | @end multitable | |
1279 | ||
1280 | @cindex @code{OBJ_NEW}, special online help | |
1281 | Note that the @code{OBJ_NEW} function is special in that the help | |
1282 | displayed depends on the cursor position: If the cursor is on the | |
1283 | @samp{OBJ_NEW}, this function is described. If it is on the class name | |
1284 | inside the quotes, the documentation for the class is pulled up. If the | |
1285 | cursor is @emph{after} the class name, anywhere in the argument list, | |
1286 | the documentation for the corresponding @code{Init} method and its | |
1287 | keywords is targeted. | |
1288 | ||
1289 | @noindent Apart from source buffers, there are two more places from | |
1290 | which online help can be accessed. | |
1291 | ||
1292 | @itemize @bullet | |
1293 | @item | |
1294 | Online help for routines and keywords can be accessed through the | |
32d4cddb | 1295 | Routine Info display. Click with @kbd{Mouse-3} on an item to see the |
a8e833f3 CD |
1296 | corresponding help (@pxref{Routine Info}). |
1297 | @item | |
76959b77 S |
1298 | When using completion and Emacs pops up a @file{*Completions*} buffer |
1299 | with possible completions, clicking with @kbd{Mouse-3} on a completion | |
1300 | item invokes help on that item (@pxref{Completion}). Items for which | |
1301 | help is available in the online system documentation (vs. just the | |
1302 | program source itself) will be emphasized (e.g. colored blue). | |
a8e833f3 CD |
1303 | @end itemize |
1304 | @noindent | |
1305 | In both cases, a blue face indicates that the item is documented in the | |
5af23035 S |
1306 | IDL manual, but an attempt will be made to visit non-blue items directly |
1307 | in the originating source file. | |
a8e833f3 | 1308 | |
32d4cddb S |
1309 | @cindex Help application, key bindings |
1310 | @cindex Key bindings, in help application | |
a8e833f3 | 1311 | The help window is normally displayed in a separate frame. The |
5af23035 | 1312 | following commands can be used to navigate inside the help system: |
a8e833f3 CD |
1313 | |
1314 | @multitable @columnfractions .15 .85 | |
1315 | @item @kbd{@key{SPACE}} | |
1316 | @tab Scroll forward one page. | |
1317 | @item @kbd{@key{RET}} | |
1318 | @tab Scroll forward one line. | |
1319 | @item @kbd{@key{DEL}} | |
1320 | @tab Scroll back one page. | |
1321 | @item @kbd{n, p} | |
1322 | @tab Browse to the next or previous topic (in physical sequence). | |
1323 | @item @kbd{b, f} | |
1324 | @tab Move back and forward through the help topic history. | |
1325 | @item @kbd{c} | |
1326 | @tab Clear the history. | |
32d4cddb | 1327 | @item @kbd{Mouse-2} |
a8e833f3 CD |
1328 | @tab Follow a link. Active links are displayed in a different font. |
1329 | Items under @i{See Also} are active, and classes have links to their | |
1330 | methods and back. | |
1331 | @item @kbd{o} | |
1332 | @tab Open a topic. The topic can be selected with completion. | |
1333 | @item @kbd{*} | |
1334 | @tab Load the whole help file into Emacs, for global text searches. | |
1335 | @item @kbd{q} | |
1336 | @tab Kill the help window. | |
1337 | @end multitable | |
1338 | ||
1339 | @sp 1 | |
1340 | @noindent When the help text is a source file, the following commands | |
5af23035 S |
1341 | are also available: |
1342 | ||
a8e833f3 CD |
1343 | @multitable @columnfractions .15 .85 |
1344 | @item @kbd{h} | |
1345 | @tab Jump to DocLib Header of the routine whose source is displayed | |
1346 | as help. | |
1347 | @item @kbd{H} | |
1348 | @tab Jump to the first DocLib Header in the file. | |
1349 | @item @kbd{.} @r{(Dot)} | |
1350 | @tab Jump back and forth between the routine definition (the | |
1351 | @code{pro}/@code{function} statement) and the description of the help | |
1352 | item in the DocLib header. | |
1353 | @item @kbd{F} | |
1354 | @tab Fontify the buffer like source code. See the variable @code{idlwave-help-fontify-source-code}. | |
1355 | @end multitable | |
1356 | ||
1357 | @defopt idlwave-help-directory | |
1358 | The directory where idlw-help.txt and idlw-help.el are stored. | |
797c8ebc CD |
1359 | @end defopt |
1360 | ||
a8e833f3 | 1361 | @defopt idlwave-help-use-dedicated-frame (@code{t}) |
5af23035 | 1362 | Non-@code{nil} means use a separate frame for Online Help if possible. |
797c8ebc CD |
1363 | @end defopt |
1364 | ||
a8e833f3 CD |
1365 | @defopt idlwave-help-frame-parameters |
1366 | The frame parameters for the special Online Help frame. | |
1367 | @end defopt | |
1368 | ||
1369 | @defopt idlwave-max-popup-menu-items (@code{20}) | |
32d4cddb | 1370 | Maximum number of items per pane in pop-up menus. |
a8e833f3 CD |
1371 | @end defopt |
1372 | ||
1373 | @defopt idlwave-extra-help-function | |
1374 | Function to call for help if the normal help fails. | |
797c8ebc CD |
1375 | @end defopt |
1376 | ||
a8e833f3 | 1377 | @defopt idlwave-help-fontify-source-code (@code{nil}) |
5af23035 | 1378 | Non-@code{nil} means fontify source code displayed as help. |
a8e833f3 | 1379 | @end defopt |
797c8ebc | 1380 | |
a8e833f3 | 1381 | @defopt idlwave-help-source-try-header (@code{t}) |
5af23035 | 1382 | Non-@code{nil} means try to find help in routine header when displaying source |
a8e833f3 CD |
1383 | file. |
1384 | @end defopt | |
1385 | ||
1386 | @defopt idlwave-help-link-face | |
5af23035 | 1387 | The face for links in IDLWAVE online help. |
a8e833f3 CD |
1388 | @end defopt |
1389 | ||
5af23035 S |
1390 | @defopt idlwave-help-activate-links-aggressively (@code{t}) |
1391 | Non-@code{nil} means make all possible links in help window active. | |
aea44e56 CD |
1392 | @end defopt |
1393 | ||
a8e833f3 | 1394 | @node Completion, Routine Source, Online Help, The IDLWAVE Major Mode |
797c8ebc CD |
1395 | @section Completion |
1396 | @cindex Completion | |
a8e833f3 CD |
1397 | @cindex Keyword completion |
1398 | @cindex Method completion | |
1399 | @cindex Object method completion | |
1400 | @cindex Class name completion | |
1401 | @cindex Function name completion | |
1402 | @cindex Procedure name completion | |
1403 | ||
1404 | @kindex M-@key{TAB} | |
1405 | @kindex C-c C-i | |
5af23035 S |
1406 | IDLWAVE offers completion for class names, routine names, keywords, |
1407 | system variables, class structure tags, regular structure tags and file | |
1408 | names. As in many programming modes, completion is bound to | |
1409 | @kbd{M-@key{TAB}} (or @kbd{@key{TAB}} in the IDLWAVE Shell --- | |
1410 | @pxref{Using the Shell}). Completion uses exactly the same internal | |
1411 | information as routine info, so when necessary (rarely) it can be | |
1412 | updated with @kbd{C-c C-i} (@code{idlwave-update-routine-info}). | |
797c8ebc CD |
1413 | |
1414 | The completion function is context sensitive and figures out what to | |
5af23035 S |
1415 | complete based location of the point. Here are example lines and what |
1416 | @kbd{M-@key{TAB}} would try to complete when the cursor is on the | |
1417 | position marked with a @samp{_}: | |
797c8ebc CD |
1418 | |
1419 | @example | |
5af23035 S |
1420 | plo_ @r{Procedure} |
1421 | x = a_ @r{Function} | |
1422 | plot,xra_ @r{Keyword of @code{plot} procedure} | |
1423 | plot,x,y,/x_ @r{Keyword of @code{plot} procedure} | |
1424 | plot,min(_ @r{Keyword of @code{min} function} | |
1425 | obj -> a_ @r{Object method (procedure)} | |
1426 | a(2,3) = obj -> a_ @r{Object method (function)} | |
1427 | x = obj_new('IDL_ @r{Class name} | |
1428 | x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}} | |
1429 | pro A_ @r{Class name} | |
1430 | pro _ @r{Fill in @code{Class::} of first method in this file} | |
1431 | !v_ @r{System variable} | |
1432 | !version.t_ @r{Structure tag of system variable} | |
1433 | self.g_ @r{Class structure tag in methods} | |
1434 | state.w_ @r{Structure tag, if tag completion enabled} | |
1435 | name = 'a_ @r{File name (default inside quotes)} | |
797c8ebc CD |
1436 | @end example |
1437 | ||
5af23035 S |
1438 | @cindex Completion, ambiguity |
1439 | @cindex Completion, forcing function name | |
1440 | The only place where completion is ambiguous is procedure/function | |
76959b77 S |
1441 | @emph{keywords} versus @emph{functions}. After @samp{plot,x,_}, IDLWAVE |
1442 | will always assume a keyword to @samp{plot}. However, a function is | |
1443 | also a possible completion here. You can force completion of a function | |
1444 | name at such a location by using a prefix arg: @kbd{C-u M-@key{TAB}}. | |
5af23035 | 1445 | |
797c8ebc CD |
1446 | @cindex Scrolling the @file{*Completions*} window |
1447 | @cindex Completion, scrolling | |
a8e833f3 CD |
1448 | @cindex Completion, Online Help |
1449 | @cindex Online Help in @file{*Completions*} buffer | |
797c8ebc CD |
1450 | If the list of completions is too long to fit in the |
1451 | @file{*Completions*} window, the window can be scrolled by pressing | |
a8e833f3 | 1452 | @kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each |
32d4cddb | 1453 | possible completion is available by clicking with @kbd{Mouse-3} on the |
a8e833f3 | 1454 | item. Items for which system online help (from the IDL manual) is |
76959b77 S |
1455 | available will be emphasized (e.g. colored blue). For other items, the |
1456 | corresponding source code or DocLib header will be used as the help | |
1457 | text. | |
1458 | ||
1459 | @cindex Completion, cancelling | |
1460 | @cindex Cancelling completion | |
1461 | Completion is not a blocking operation --- you are free to continue | |
1462 | editing, enter commands, or simply ignore the @file{*Completions*} | |
1463 | buffer during a completion operation. If, however, the most recent | |
1464 | command was a completion, @kbd{C-g} will remove the buffer and restore | |
1465 | the window configuration. You can also remove the buffer at any time | |
1466 | with no negative consequences. | |
5af23035 S |
1467 | |
1468 | @defopt idlwave-keyword-completion-adds-equal (@code{t}) | |
1469 | Non-@code{nil} means completion automatically adds @samp{=} after | |
1470 | completed keywords. | |
1471 | @end defopt | |
1472 | ||
1473 | @defopt idlwave-function-completion-adds-paren (@code{t}) | |
1474 | Non-@code{nil} means completion automatically adds @samp{(} after | |
1475 | completed function. A value of `2' means also add the closing | |
1476 | parenthesis and position the cursor between the two. | |
1477 | @end defopt | |
1478 | ||
1479 | @defopt idlwave-completion-restore-window-configuration (@code{t}) | |
1480 | Non-@code{nil} means restore window configuration after successful | |
1481 | completion. | |
1482 | @end defopt | |
797c8ebc | 1483 | |
5af23035 S |
1484 | @defopt idlwave-highlight-help-links-in-completion (@code{t}) |
1485 | Non-@code{nil} means highlight completions for which system help is | |
1486 | available. | |
1487 | @end defopt | |
1488 | ||
1489 | @menu | |
1490 | * Case of Completed Words:: CaseOFcomPletedWords | |
1491 | * Object Method Completion and Class Ambiguity:: obj->Method, what? | |
177c0ea7 | 1492 | * Object Method Completion in the Shell:: |
5af23035 S |
1493 | * Class and Keyword Inheritance:: obj->Method, _EXTRA=e |
1494 | * Structure Tag Completion:: Completing state.Tag | |
1495 | @end menu | |
1496 | ||
1497 | @node Case of Completed Words, Object Method Completion and Class Ambiguity, Completion, Completion | |
1498 | @subsection Case of Completed Words | |
797c8ebc | 1499 | @cindex Case of completed words |
a8e833f3 | 1500 | @cindex Mixed case completion |
797c8ebc CD |
1501 | The case of the completed words is determined by what is already in the |
1502 | buffer. When the partial word being completed is all lower case, the | |
1503 | completion will be lower case as well. If at least one character is | |
1504 | upper case, the string will be completed in upper case or mixed case. | |
1505 | The default is to use upper case for procedures, functions and keywords, | |
1506 | and mixed case for object class names and methods, similar to the | |
1507 | conventions in the IDL manuals. These defaults can be changed with the | |
5af23035 S |
1508 | variable @code{idlwave-completion-case}. For instance, to enable |
1509 | mixed-case completion for routines in addition to classes and methods, | |
1510 | you need an entry such as @code{routine . preserve} in that variable. | |
1511 | To enable total control over the case of completed items, independent of | |
1512 | buffer context, set @code{idlwave-completion-force-default-case} to | |
1513 | non-@code{nil}. | |
797c8ebc CD |
1514 | |
1515 | @defopt idlwave-completion-case | |
5af23035 S |
1516 | Association list setting the case (UPPER/lower/Capitalized/MixedCase...) |
1517 | of completed words. | |
797c8ebc CD |
1518 | @end defopt |
1519 | ||
1520 | @defopt idlwave-completion-force-default-case (@code{nil}) | |
5af23035 S |
1521 | Non-@code{nil} means completion will always honor the settings in |
1522 | @code{idlwave-completion-case}. When nil (the default), entirely lower | |
1523 | case strings will always be completed to lower case, no matter what the | |
1524 | settings in @code{idlwave-completion-case}. | |
797c8ebc CD |
1525 | @end defopt |
1526 | ||
1527 | @defopt idlwave-complete-empty-string-as-lower-case (@code{nil}) | |
5af23035 | 1528 | Non-@code{nil} means the empty string is considered lower case for |
a8e833f3 | 1529 | completion. |
797c8ebc CD |
1530 | @end defopt |
1531 | ||
76959b77 | 1532 | @node Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion |
5af23035 | 1533 | @subsection Object Method Completion and Class Ambiguity |
797c8ebc CD |
1534 | @cindex Object methods |
1535 | @cindex Class ambiguity | |
a8e833f3 | 1536 | @cindex @code{self} object, default class |
797c8ebc | 1537 | An object method is not uniquely determined without the object's class. |
5af23035 S |
1538 | Since the class is almost always omitted in the calling source, IDLWAVE |
1539 | considers all available methods in all classes as possible method name | |
1540 | completions. The combined list of keywords of the current method in | |
1541 | @emph{all} known classes which contain that method will be considered | |
1542 | for keyword completion. In the @file{*Completions*} buffer, the | |
1543 | matching classes will be shown next to each item (see option | |
a8e833f3 | 1544 | @code{idlwave-completion-show-classes}). As a special case, the class |
5af23035 | 1545 | of an object called @samp{self} is always taken to be the class of the |
aea44e56 CD |
1546 | current routine. All classes it inherits from are considered as well |
1547 | where appropriate. | |
797c8ebc | 1548 | |
a8e833f3 CD |
1549 | @cindex Forcing class query. |
1550 | @cindex Class query, forcing | |
797c8ebc CD |
1551 | You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u |
1552 | M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to | |
1553 | narrow down the number of possible completions. The variable | |
5af23035 S |
1554 | @code{idlwave-query-class} can be configured to make such prompting the |
1555 | default for all methods (not recommended), or selectively for very | |
1556 | common methods for which the number of completing keywords would be too | |
177c0ea7 | 1557 | large (e.g. @code{Init}). |
76959b77 S |
1558 | |
1559 | @cindex Saving object class on @code{->} | |
1560 | @cindex @code{->} | |
1561 | After you have specified the class for a particular statement (e.g. when | |
1562 | completing the method), IDLWAVE can remember it for the rest of the | |
1563 | editing session. Subsequent completions in the same statement | |
1564 | (e.g. keywords) can then reuse this class information. This works by | |
1565 | placing a text property on the method invocation operator @samp{->}, | |
1566 | after which the operator will be shown in a different face. This is not | |
1567 | enabled by default --- the variable @code{idlwave-store-inquired-class} | |
1568 | can be used to turn it on. | |
aea44e56 | 1569 | |
ea442c62 | 1570 | @defopt idlwave-completion-show-classes (@code{1}) |
5af23035 | 1571 | Non-@code{nil} means show classes in @file{*Completions*} buffer when |
a8e833f3 | 1572 | completing object methods and keywords. |
797c8ebc CD |
1573 | @end defopt |
1574 | ||
1575 | @defopt idlwave-completion-fontify-classes (@code{t}) | |
5af23035 | 1576 | Non-@code{nil} means fontify the classes in completions buffer. |
797c8ebc CD |
1577 | @end defopt |
1578 | ||
1579 | @defopt idlwave-query-class (@code{nil}) | |
a8e833f3 | 1580 | Association list governing query for object classes during completion. |
797c8ebc CD |
1581 | @end defopt |
1582 | ||
1583 | @defopt idlwave-store-inquired-class (@code{nil}) | |
5af23035 | 1584 | Non-@code{nil} means store class of a method call as text property on |
a8e833f3 | 1585 | @samp{->}. |
797c8ebc CD |
1586 | @end defopt |
1587 | ||
1588 | @defopt idlwave-class-arrow-face | |
1589 | Face to highlight object operator arrows @samp{->} which carry a class | |
a8e833f3 | 1590 | text property. |
797c8ebc CD |
1591 | @end defopt |
1592 | ||
76959b77 S |
1593 | @node Object Method Completion in the Shell, Class and Keyword Inheritance, Object Method Completion and Class Ambiguity, Completion |
1594 | @subsection Object Method Completion in the Shell | |
1595 | @cindex Method Completion in Shell | |
1596 | In the IDLWAVE Shell (@pxref{The IDLWAVE Shell}), objects on which | |
1597 | methods are being invoked have a special property: they must exist as | |
1598 | variables, and so their class can be determined (for instance, using the | |
1599 | @code{obj_class()} function). In the Shell, when attempting completion, | |
1600 | routine info, or online help within a method routine, a query is sent to | |
1601 | determine the class of the object. If this query is successful, the | |
1602 | class found will be used to select appropriate completions, routine | |
1603 | info, or help. If unsuccessful, information from all known classes will | |
1604 | be used (as in the buffer). Setting the variable | |
1605 | @code{idlwave-store-inquired-class} can eliminate unnecessary repetitive | |
1606 | queries for the object's class, and speed up completion. | |
1607 | ||
1608 | @node Class and Keyword Inheritance, Structure Tag Completion, Object Method Completion in the Shell, Completion | |
5af23035 S |
1609 | @subsection Class and Keyword Inheritance |
1610 | @cindex Inheritance, class | |
1611 | @cindex Keyword inheritance | |
1612 | @cindex Inheritance, keyword | |
1613 | ||
1614 | Class inheritance affects which methods are called in IDL. An object of | |
1615 | a class which inherits methods from one or more superclasses can | |
1616 | override that method by defining its own method of the same name, extend | |
1617 | the method by calling the method(s) of its superclass(es) in its | |
1618 | version, or inherit the method directly by making no modifications. | |
1619 | IDLWAVE examines class definitions during completion and routine | |
1620 | information display, and records all inheritance information it finds. | |
1621 | This information is displayed if appropriate with the calling sequence | |
1622 | for methods (@pxref{Routine Info}), as long as variable | |
1623 | @code{idlwave-support-inheritance} is non-@code{nil}. | |
1624 | ||
1625 | In many class methods, @emph{keyword} inheritance (@code{_EXTRA} and | |
1626 | @code{_REF_EXTRA}) is used hand-in-hand with class inheritance and | |
1627 | method overriding. E.g., in a @code{SetProperty} method, this technique | |
1628 | allows a single call @code{obj->SetProperty} to set properties up the | |
1629 | entire class inheritance chain. This is often referred to as | |
1630 | @emph{chaining}, and is characterized by chained method calls like | |
1631 | @w{@code{self->MySuperClass::SetProperty,_EXTRA=e}}. | |
1632 | ||
28665d46 | 1633 | IDLWAVE can accommodate this special synergy between class and keyword |
76959b77 | 1634 | inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a |
5af23035 | 1635 | method's keyword parameters, all keywords of superclass versions of the |
76959b77 S |
1636 | method being considered are included in completion. There is of course |
1637 | no guarantee that this type of keyword chaining actually occurrs, but | |
1638 | for some methods it's a very convenient assumption. The variable | |
1639 | @code{idlwave-keyword-class-inheritance} can be used to configure which | |
1640 | methods have keyword inheritance treated in this simple, class-driven | |
1641 | way. By default, only @code{Init} and @code{(Get|Set)Property} are. | |
1642 | The completion buffer will label keywords based on their originating | |
1643 | class. | |
5af23035 S |
1644 | |
1645 | @defopt idlwave-support-inheritance (@code{t}) | |
1646 | Non-@code{nil} means consider inheritance during completion, online help etc. | |
1647 | @end defopt | |
1648 | ||
177c0ea7 | 1649 | @defopt idlwave-keyword-class-inheritance |
5af23035 S |
1650 | A list of regular expressions to match methods for which simple |
1651 | class-driven keyword inheritance will be used for Completion. | |
1652 | @end defopt | |
a8e833f3 | 1653 | |
5af23035 S |
1654 | @node Structure Tag Completion, , Class and Keyword Inheritance, Completion |
1655 | @subsection Structure Tag Completion | |
1656 | @cindex Completion, structure tag | |
1657 | @cindex Structure tag completion | |
1658 | ||
1659 | In many programs, especially those involving widgets, large structures | |
1660 | (e.g. the @samp{state} structure) are used to communicate among | |
1661 | routines. It is very convenient to be able to complete structure tags, | |
76959b77 S |
1662 | in the same way as for instance variables (tags) of the @samp{self} |
1663 | object (@pxref{Object Method Completion and Class Ambiguity}). Add-in | |
1664 | code for structure tag completion is available in the form of a loadable | |
5af23035 S |
1665 | completion module: @file{idlw-complete-structtag.el}. Tag completion in |
1666 | structures is highly ambiguous (much more so than @samp{self} | |
76959b77 | 1667 | completion), so @code{idlw-complete-structtag} makes an unusual and very |
5af23035 | 1668 | specific assumption: the exact same variable name is used to refer to |
76959b77 S |
1669 | the structure in all parts of the program. This is entirely unenforced |
1670 | by the IDL language, but is a typical convention. If you consistently | |
5af23035 S |
1671 | refer to the same structure with the same variable name |
1672 | (e.g. @samp{state}), structure tags which are read from its definition | |
76959b77 | 1673 | in the same file can be used for completion. |
5af23035 S |
1674 | |
1675 | Structure tag completion is not enabled by default. To enable it, | |
1676 | simply add the following to your @file{.emacs}: | |
1677 | ||
1678 | @lisp | |
177c0ea7 | 1679 | (add-hook 'idlwave-load-hook |
5af23035 S |
1680 | (lambda () (require 'idlw-complete-structtag))) |
1681 | @end lisp | |
1682 | ||
76959b77 S |
1683 | Once enabled, you'll also be able to access online help on the structure |
1684 | tags, using the usual methods (@pxref{Online Help}). | |
1685 | ||
5af23035 | 1686 | @node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode |
a8e833f3 CD |
1687 | @section Routine Source |
1688 | @cindex Routine source file | |
1689 | @cindex Module source file | |
1690 | @cindex Source file, of a routine | |
1691 | @kindex C-c C-v | |
5af23035 | 1692 | In addition to clicking on a @i{Source:} line in the routine info |
76959b77 S |
1693 | window, there is another way to quickly visit the source file of a |
1694 | routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks | |
1695 | for a module name, offering the same default as | |
1696 | @code{idlwave-routine-info} would have used, taken from nearby buffer | |
1697 | contents. In the minibuffer, specify a complete routine name (including | |
1698 | any class part). IDLWAVE will display the source file in another | |
1699 | window, positioned at the routine in question. | |
a8e833f3 CD |
1700 | |
1701 | @cindex Buffers, killing | |
1702 | @cindex Killing autoloaded buffers | |
1703 | Since getting the source of a routine into a buffer is so easy with | |
1704 | IDLWAVE, too many buffers visiting different IDL source files are | |
1705 | sometimes created. The special command @kbd{C-c C-k} | |
76959b77 S |
1706 | (@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove |
1707 | these buffers. | |
a8e833f3 CD |
1708 | |
1709 | @node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode | |
1710 | @section Resolving Routines | |
1711 | @cindex @code{RESOLVE_ROUTINE} | |
1712 | @cindex Compiling library modules | |
1713 | @cindex Routines, resolving | |
1714 | ||
1715 | The key sequence @kbd{C-c =} calls the command @code{idlwave-resolve} | |
1716 | and sends the line @samp{RESOLVE_ROUTINE, '@var{routine_name}'} to IDL | |
1717 | in order to resolve (compile) it. The default routine to be resolved is | |
1718 | taken from context, but you get a chance to edit it. | |
1719 | ||
1720 | @code{idlwave-resolve} is one way to get a library module within reach | |
1721 | of IDLWAVE's routine info collecting functions. A better way is to | |
aea44e56 | 1722 | scan (parts of) the library (@pxref{Library Catalog}). Routine info on |
a8e833f3 CD |
1723 | library modules will then be available without the need to compile the |
1724 | modules first, and even without a running shell. | |
1725 | ||
5af23035 | 1726 | @xref{Sources of Routine Info}, for more information on the ways IDLWAVE |
a8e833f3 CD |
1727 | collects data about routines, and how to update this information. |
1728 | ||
5af23035 | 1729 | @node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode |
797c8ebc CD |
1730 | @section Code Templates |
1731 | @cindex Code templates | |
797c8ebc CD |
1732 | @cindex Templates |
1733 | ||
1734 | IDLWAVE can insert IDL code templates into the buffer. For a few | |
32d4cddb | 1735 | templates, this is done with direct key bindings: |
797c8ebc CD |
1736 | |
1737 | @multitable @columnfractions .15 .85 | |
1738 | @item @kbd{C-c C-c} | |
1739 | @tab @code{CASE} statement template | |
1740 | @item @kbd{C-c C-f} | |
1741 | @tab @code{FOR} loop template | |
1742 | @item @kbd{C-c C-r} | |
1743 | @tab @code{REPEAT} loop template | |
1744 | @item @kbd{C-c C-w} | |
1745 | @tab @code{WHILE} loop template | |
1746 | @end multitable | |
1747 | ||
5af23035 S |
1748 | All code templates are also available as abbreviations |
1749 | (@pxref{Abbreviations}). | |
1750 | ||
1751 | @node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode | |
1752 | @section Abbreviations | |
1753 | @cindex Abbreviations | |
1754 | ||
1755 | Special abbreviations exist to enable rapid entry of commonly used | |
1756 | commands. Emacs abbreviations are expanded by typing text into the | |
1757 | buffer and pressing @key{SPC} or @key{RET}. The special abbreviations | |
1758 | used to insert code templates all start with a @samp{\} (the backslash), | |
1759 | or, optionally, any other character set in | |
1760 | @code{idlwave-abbrev-start-char}. IDLWAVE ensures that abbreviations are | |
1761 | only expanded where they should be (i.e., not in a string or comment), | |
1762 | and permits the point to be moved after an abbreviation expansion --- | |
1763 | very useful for positioning the mark inside of parentheses, etc. | |
1764 | ||
1765 | Special abbreviations are pre-defined for code templates and other | |
1766 | useful items. To visit the full list of abbreviations, use @kbd{M-x | |
797c8ebc CD |
1767 | idlwave-list-abbrevs}. |
1768 | ||
5af23035 S |
1769 | Template abbreviations: |
1770 | ||
797c8ebc CD |
1771 | @multitable @columnfractions .15 .85 |
1772 | @item @code{\pr} | |
1773 | @tab @code{PROCEDURE} template | |
1774 | @item @code{\fu} | |
1775 | @tab @code{FUNCTION} template | |
1776 | @item @code{\c} | |
1777 | @tab @code{CASE} statement template | |
1778 | @item @code{\f} | |
1779 | @tab @code{FOR} loop template | |
1780 | @item @code{\r} | |
1781 | @tab @code{REPEAT} loop template | |
1782 | @item @code{\w} | |
1783 | @tab @code{WHILE} loop template | |
1784 | @item @code{\i} | |
1785 | @tab @code{IF} statement template | |
1786 | @item @code{\elif} | |
1787 | @tab @code{IF-ELSE} statement template | |
5af23035 S |
1788 | @end multitable |
1789 | ||
1790 | String abbreviations: | |
1791 | ||
1792 | @multitable @columnfractions .15 .85 | |
1793 | @item @code{\ap} | |
1794 | @tab @code{arg_present()} | |
797c8ebc | 1795 | @item @code{\b} |
5af23035 S |
1796 | @tab @code{begin} |
1797 | @item @code{\cb} | |
1798 | @tab @code{byte()} | |
1799 | @item @code{\cc} | |
1800 | @tab @code{complex()} | |
1801 | @item @code{\cd} | |
1802 | @tab @code{double()} | |
1803 | @item @code{\cf} | |
1804 | @tab @code{float()} | |
1805 | @item @code{\cl} | |
1806 | @tab @code{long()} | |
1807 | @item @code{\co} | |
1808 | @tab @code{common} | |
1809 | @item @code{\cs} | |
1810 | @tab @code{string()} | |
1811 | @item @code{\cx} | |
1812 | @tab @code{fix()} | |
1813 | @item @code{\e} | |
1814 | @tab @code{else} | |
1815 | @item @code{\ec} | |
1816 | @tab @code{endcase} | |
1817 | @item @code{\ee} | |
1818 | @tab @code{endelse} | |
1819 | @item @code{\ef} | |
1820 | @tab @code{endfor} | |
1821 | @item @code{\ei} | |
1822 | @tab @code{endif else if} | |
1823 | @item @code{\el} | |
1824 | @tab @code{endif else} | |
1825 | @item @code{\en} | |
1826 | @tab @code{endif} | |
1827 | @item @code{\er} | |
1828 | @tab @code{endrep} | |
1829 | @item @code{\es} | |
1830 | @tab @code{endswitch} | |
1831 | @item @code{\ew} | |
1832 | @tab @code{endwhile} | |
1833 | @item @code{\g} | |
1834 | @tab @code{goto,} | |
1835 | @item @code{\h} | |
1836 | @tab @code{help,} | |
1837 | @item @code{\ik} | |
1838 | @tab @code{if keyword_set() then} | |
1839 | @item @code{\iap} | |
1840 | @tab @code{if arg_present() then} | |
1841 | @item @code{\ine} | |
1842 | @tab @code{if n_elements() eq 0 then} | |
1843 | @item @code{\inn} | |
1844 | @tab @code{if n_elements() ne 0 then} | |
1845 | @item @code{\k} | |
1846 | @tab @code{keyword_set()} | |
1847 | @item @code{\n} | |
1848 | @tab @code{n_elements()} | |
1849 | @item @code{\np} | |
1850 | @tab @code{n_params()} | |
1851 | @item @code{\oi} | |
1852 | @tab @code{on_ioerror,} | |
1853 | @item @code{\or} | |
1854 | @tab @code{openr,} | |
1855 | @item @code{\ou} | |
1856 | @tab @code{openu,} | |
1857 | @item @code{\ow} | |
1858 | @tab @code{openw,} | |
1859 | @item @code{\p} | |
1860 | @tab @code{print,} | |
1861 | @item @code{\pt} | |
1862 | @tab @code{plot,} | |
1863 | @item @code{\re} | |
1864 | @tab @code{read,} | |
1865 | @item @code{\rf} | |
1866 | @tab @code{readf,} | |
1867 | @item @code{\rt} | |
1868 | @tab @code{return} | |
1869 | @item @code{\ru} | |
1870 | @tab @code{readu,} | |
1871 | @item @code{\s} | |
1872 | @tab @code{size()} | |
1873 | @item @code{\sc} | |
1874 | @tab @code{strcompress()} | |
1875 | @item @code{\sl} | |
1876 | @tab @code{strlowcase()} | |
1877 | @item @code{\sm} | |
1878 | @tab @code{strmid()} | |
1879 | @item @code{\sn} | |
1880 | @tab @code{strlen()} | |
1881 | @item @code{\sp} | |
1882 | @tab @code{strpos()} | |
1883 | @item @code{\sr} | |
1884 | @tab @code{strtrim()} | |
1885 | @item @code{\st} | |
1886 | @tab @code{strput()} | |
1887 | @item @code{\su} | |
1888 | @tab @code{strupcase()} | |
1889 | @item @code{\t} | |
1890 | @tab @code{then} | |
1891 | @item @code{\u} | |
1892 | @tab @code{until} | |
1893 | @item @code{\wc} | |
1894 | @tab @code{widget_control,} | |
1895 | @item @code{\wi} | |
1896 | @tab @code{widget_info()} | |
1897 | @item @code{\wu} | |
1898 | @tab @code{writeu,} | |
797c8ebc | 1899 | @end multitable |
ea442c62 | 1900 | |
5af23035 | 1901 | @noindent You can easily add your own abbreviations or override existing |
32d4cddb | 1902 | abbrevs with @code{define-abbrev} in your mode hook, using the |
5af23035 S |
1903 | convenience function @code{idlwave-define-abbrev}: |
1904 | ||
1905 | @lisp | |
1906 | (add-hook 'idlwave-mode-hook | |
1907 | (lambda () | |
1908 | (idlwave-define-abbrev "wb" "widget_base()" | |
76959b77 S |
1909 | (idlwave-keyword-abbrev 1)) |
1910 | (idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN" | |
1911 | (idlwave-keyword-abbrev 11)))) | |
5af23035 S |
1912 | @end lisp |
1913 | ||
1914 | Notice how the abbreviation (here @emph{wb}) and its expansion | |
76959b77 | 1915 | (@emph{widget_base()}) are given as arguments, and the single argument to |
5af23035 S |
1916 | @code{idlwave-keyword-abbrev} (here @emph{1}) specifies how far back to |
1917 | move the point upon expansion (in this example, to put it between the | |
1918 | parentheses). | |
1919 | ||
1920 | The abbreviations are expanded in upper or lower case, depending upon | |
76959b77 S |
1921 | the variables @code{idlwave-abbrev-change-case} and, for reserved word |
1922 | templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}). | |
ea442c62 | 1923 | |
aea44e56 | 1924 | @defopt idlwave-abbrev-start-char (@code{"\"}) |
76959b77 S |
1925 | A single character string used to start abbreviations in abbrev mode. |
1926 | Beware of common characters which might naturally occur in sequence with | |
1927 | abbreviation strings. | |
797c8ebc CD |
1928 | @end defopt |
1929 | ||
1930 | @defopt idlwave-abbrev-move (@code{t}) | |
1931 | Non-@code{nil} means the abbrev hook can move point, e.g. to end up | |
76959b77 | 1932 | between the parentheses of a function call. |
797c8ebc CD |
1933 | @end defopt |
1934 | ||
5af23035 | 1935 | @node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode |
797c8ebc CD |
1936 | @section Actions |
1937 | @cindex Actions | |
1938 | @cindex Coding standards, enforcing | |
1939 | ||
76959b77 S |
1940 | @emph{Actions} are special formatting commands which are executed |
1941 | automatically while you write code in order to check the structure of | |
1942 | the program or to enforce coding standards. Most actions which have | |
1943 | been implemented in IDLWAVE are turned off by default, assuming that the | |
1944 | average user wants her code the way she writes it. But if you are a | |
1945 | lazy typist and want your code to adhere to certain standards, actions | |
1946 | can be helpful. | |
797c8ebc | 1947 | |
5af23035 | 1948 | Actions can be applied in three ways: |
a8e833f3 | 1949 | |
797c8ebc CD |
1950 | @itemize @bullet |
1951 | @item | |
1952 | Some actions are applied directly while typing. For example, pressing | |
1953 | @samp{=} can run a check to make sure that this operator is surrounded | |
1954 | by spaces and insert these spaces if necessary. Pressing @key{SPC} | |
1955 | after a reserved word can call a command to change the word to upper | |
a8e833f3 | 1956 | case. |
797c8ebc CD |
1957 | @item |
1958 | When a line is re-indented with @key{TAB}, actions can be applied to the | |
1959 | entire line. To enable this, the variable @code{idlwave-do-actions} | |
a8e833f3 | 1960 | must be non-@code{nil}. |
797c8ebc CD |
1961 | @item |
1962 | @cindex Foreign code, adapting | |
1963 | @cindex Actions, applied to foreign code | |
5af23035 S |
1964 | Actions can also be applied to a larger piece of code, e.g. to convert |
1965 | foreign code to your own style. To do this, mark the relevant part of | |
1966 | the code and execute @kbd{M-x expand-region-abbrevs}. Useful marking | |
1967 | commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current | |
1968 | subprogram). @xref{Code Indentation}, for information how to adjust the | |
1969 | indentation of the code. | |
797c8ebc CD |
1970 | @end itemize |
1971 | ||
1972 | @defopt idlwave-do-actions (@code{nil}) | |
1973 | Non-@code{nil} means performs actions when indenting. | |
1974 | @end defopt | |
1975 | ||
1976 | @menu | |
76959b77 | 1977 | * Block Boundary Check:: Is the END statement correct? |
797c8ebc CD |
1978 | * Padding Operators:: Enforcing space around `=' etc |
1979 | * Case Changes:: Enforcing upper case keywords | |
1980 | @end menu | |
1981 | ||
1982 | @node Block Boundary Check, Padding Operators, Actions, Actions | |
1983 | @subsection Block Boundary Check | |
1984 | @cindex Block boundary check | |
1985 | @cindex @code{END} type checking | |
1986 | @cindex @code{END}, automatic insertion | |
a8e833f3 | 1987 | @cindex @code{END}, expanding |
797c8ebc CD |
1988 | @cindex Block, closing |
1989 | @cindex Closing a block | |
1990 | ||
1991 | Whenever you type an @code{END} statement, IDLWAVE finds the | |
1992 | corresponding start of the block and the cursor blinks back to that | |
1993 | location for a second. If you have typed a specific @code{END}, like | |
5af23035 | 1994 | @code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator |
a8e833f3 | 1995 | does not match the type of block it terminates. |
797c8ebc CD |
1996 | |
1997 | Set the variable @code{idlwave-expand-generic-end} in order to have all | |
5af23035 S |
1998 | generic @code{END} statements automatically expanded to the appropriate |
1999 | type. You can also type @kbd{C-c ]} to close the current block by | |
2000 | inserting the appropriate @code{END} statement. | |
797c8ebc CD |
2001 | |
2002 | @defopt idlwave-show-block (@code{t}) | |
2003 | Non-@code{nil} means point blinks to block beginning for | |
a8e833f3 | 2004 | @code{idlwave-show-begin}. |
797c8ebc CD |
2005 | @end defopt |
2006 | ||
aea44e56 | 2007 | @defopt idlwave-expand-generic-end (@code{t}) |
797c8ebc CD |
2008 | Non-@code{nil} means expand generic END to ENDIF/ENDELSE/ENDWHILE etc. |
2009 | @end defopt | |
2010 | ||
a8e833f3 | 2011 | @defopt idlwave-reindent-end (@code{t}) |
5af23035 | 2012 | Non-@code{nil} means re-indent line after END was typed. |
a8e833f3 CD |
2013 | @end defopt |
2014 | ||
797c8ebc CD |
2015 | @node Padding Operators, Case Changes, Block Boundary Check, Actions |
2016 | @subsection Padding Operators | |
2017 | @cindex Padding operators with spaces | |
2018 | @cindex Operators, padding with spaces | |
a8e833f3 | 2019 | @cindex Space, around operators |
797c8ebc CD |
2020 | |
2021 | Some operators can be automatically surrounded by spaces. This can | |
5af23035 S |
2022 | happen when the operator is typed, or later when the line is indented. |
2023 | IDLWAVE can pad the operators @samp{&}, @samp{<}, @samp{>}, @samp{,}, | |
2024 | @samp{=}, and @samp{->}, but this feature is turned off by default. If | |
2025 | you want to turn it on, customize the variables | |
2026 | @code{idlwave-surround-by-blank} and @code{idlwave-do-actions}. You can | |
2027 | also define similar actions for other operators by using the function | |
2028 | @code{idlwave-action-and-binding} in the mode hook. For example, to | |
2029 | enforce space padding of the @samp{+} and @samp{*} operators, try this | |
2030 | in @file{.emacs} | |
797c8ebc CD |
2031 | |
2032 | @lisp | |
2033 | (add-hook 'idlwave-mode-hook | |
2034 | (lambda () | |
2035 | (setq idlwave-surround-by-blank t) ; Turn this type of actions on | |
2036 | (idlwave-action-and-binding "*" '(idlwave-surround 1 1)) | |
2037 | (idlwave-action-and-binding "+" '(idlwave-surround 1 1)))) | |
2038 | @end lisp | |
2039 | ||
2040 | @defopt idlwave-surround-by-blank (@code{nil}) | |
5af23035 | 2041 | Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil}, |
ea442c62 | 2042 | @samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are |
a8e833f3 | 2043 | surrounded with spaces by @code{idlwave-surround}. |
797c8ebc CD |
2044 | @end defopt |
2045 | ||
2046 | @defopt idlwave-pad-keyword (@code{t}) | |
a8e833f3 | 2047 | Non-@code{nil} means pad @samp{=} for keywords like assignments. |
797c8ebc CD |
2048 | @end defopt |
2049 | ||
2050 | @node Case Changes, , Padding Operators, Actions | |
2051 | @subsection Case Changes | |
2052 | @cindex Case changes | |
a8e833f3 CD |
2053 | @cindex Upcase, enforcing for reserved words |
2054 | @cindex Downcase, enforcing for reserved words | |
797c8ebc CD |
2055 | |
2056 | Actions can be used to change the case of reserved words or expanded | |
2057 | abbreviations by customizing the variables | |
2058 | @code{idlwave-abbrev-change-case} and | |
2059 | @code{idlwave-reserved-word-upcase}. If you want to change the case of | |
2060 | additional words automatically, put something like the following into | |
a8e833f3 | 2061 | your @file{.emacs} file: |
797c8ebc CD |
2062 | |
2063 | @lisp | |
2064 | (add-hook 'idlwave-mode-hook | |
2065 | (lambda () | |
2066 | ;; Capitalize system vars | |
2067 | (idlwave-action-and-binding idlwave-sysvar '(capitalize-word 1) t) | |
2068 | ;; Capitalize procedure name | |
2069 | (idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" | |
2070 | '(capitalize-word 1) t) | |
2071 | ;; Capitalize common block name | |
177c0ea7 | 2072 | (idlwave-action-and-binding "\\<common\\>[ \t]+\\<" |
797c8ebc CD |
2073 | '(capitalize-word 1) t))) |
2074 | @end lisp | |
2075 | ||
2076 | For more information, see the documentation string for the function | |
5af23035 S |
2077 | @code{idlwave-action-and-binding}. For information on controlling the |
2078 | case of routines, keywords, classes, and methods as they are completed, see | |
2079 | @ref{Completion}. | |
797c8ebc CD |
2080 | |
2081 | @defopt idlwave-abbrev-change-case (@code{nil}) | |
2082 | Non-@code{nil} means all abbrevs will be forced to either upper or lower | |
2083 | case. Legal values are @code{nil}, @code{t}, and @code{down}. | |
2084 | @end defopt | |
2085 | ||
2086 | @defopt idlwave-reserved-word-upcase (@code{nil}) | |
5af23035 | 2087 | Non-@code{nil} means reserved words will be made upper case via abbrev |
797c8ebc CD |
2088 | expansion. |
2089 | @end defopt | |
2090 | ||
2091 | ||
2092 | @node Doc Header, Motion Commands, Actions, The IDLWAVE Major Mode | |
2093 | @section Documentation Header | |
2094 | @cindex Documentation header | |
a8e833f3 | 2095 | @cindex DocLib header |
797c8ebc CD |
2096 | @cindex Modification timestamp |
2097 | @cindex Header, for file documentation | |
2098 | @cindex Timestamp, in doc header. | |
28665d46 | 2099 | @cindex ChangeLog, in doc header. |
797c8ebc | 2100 | |
a8e833f3 CD |
2101 | @kindex C-c C-h |
2102 | @kindex C-c C-m | |
797c8ebc | 2103 | The command @kbd{C-c C-h} inserts a standard routine header into the |
5af23035 S |
2104 | buffer, with the usual fields for documentation (a different header can |
2105 | be specified with @code{idlwave-file-header}). One of the keywords is | |
797c8ebc CD |
2106 | @samp{MODIFICATION HISTORY} under which the changes to a routine can be |
2107 | recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION | |
5af23035 S |
2108 | HISTORY} of the current routine or file and inserts the user name with a |
2109 | timestamp. | |
797c8ebc CD |
2110 | |
2111 | @defopt idlwave-file-header | |
2112 | The doc-header template or a path to a file containing it. | |
2113 | @end defopt | |
2114 | ||
5af23035 S |
2115 | @defopt idlwave-header-to-beginning-of-file (@code{nil}) |
2116 | Non-@code{nil} means the documentation header will always be at start | |
2117 | of file. | |
2118 | @end defopt | |
2119 | ||
797c8ebc CD |
2120 | @defopt idlwave-timestamp-hook |
2121 | The hook function used to update the timestamp of a function. | |
2122 | @end defopt | |
2123 | ||
2124 | @defopt idlwave-doc-modifications-keyword | |
2125 | The modifications keyword to use with the log documentation commands. | |
2126 | @end defopt | |
2127 | ||
2128 | @defopt idlwave-doclib-start | |
2129 | Regexp matching the start of a document library header. | |
2130 | @end defopt | |
2131 | ||
2132 | @defopt idlwave-doclib-end | |
2133 | Regexp matching the start of a document library header. | |
2134 | @end defopt | |
2135 | ||
2136 | @node Motion Commands, Misc Options, Doc Header, The IDLWAVE Major Mode | |
2137 | @section Motion Commands | |
2138 | @cindex Motion commands | |
2139 | @cindex Program structure, moving through | |
2140 | @cindex Code structure, moving through | |
a8e833f3 CD |
2141 | @cindex @file{Func-menu}, XEmacs package |
2142 | @cindex @file{Imenu}, Emacs package | |
2143 | @cindex Function definitions, jumping to | |
2144 | @cindex Procedure definitions, jumping to | |
2145 | ||
2146 | IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages | |
2147 | which make it easy to jump to the definitions of functions and | |
5af23035 S |
2148 | procedures in the current file with a pop-up selection. To bind |
2149 | @file{Imenu} to a mouse-press, use in your @file{.emacs}: | |
2150 | ||
2151 | @lisp | |
2152 | (define-key global-map [S-down-mouse-3] 'imenu) | |
2153 | @end lisp | |
2154 | ||
2155 | @cindex @file{Speedbar}, Emacs package | |
797c8ebc | 2156 | |
5af23035 S |
2157 | In addition, @file{Speedbar} support allows convenient navigation of a |
2158 | source tree of IDL routine files, quickly stepping to routine | |
2159 | definitions. See @code{Tools->Display Speedbar}. | |
2160 | ||
2161 | Several commands allow you to move quickly through the structure of an | |
2162 | IDL program: | |
797c8ebc CD |
2163 | |
2164 | @multitable @columnfractions .15 .85 | |
2165 | @item @kbd{C-M-a} | |
2166 | @tab Beginning of subprogram | |
2167 | @item @kbd{C-M-e} | |
2168 | @tab End of subprogram | |
2169 | @item @kbd{C-c @{} | |
2170 | @tab Beginning of block (stay inside the block) | |
2171 | @item @kbd{C-c @}} | |
2172 | @tab End of block (stay inside the block) | |
718fb8a1 | 2173 | @item @kbd{C-M-n} |
797c8ebc | 2174 | @tab Forward block (on same level) |
718fb8a1 | 2175 | @item @kbd{C-M-p} |
797c8ebc | 2176 | @tab Backward block (on same level) |
718fb8a1 | 2177 | @item @kbd{C-M-d} |
797c8ebc | 2178 | @tab Down block (enters a block) |
718fb8a1 | 2179 | @item @kbd{C-M-u} |
797c8ebc CD |
2180 | @tab Backward up block (leaves a block) |
2181 | @item @kbd{C-c C-n} | |
2182 | @tab Next Statement | |
2183 | @end multitable | |
2184 | ||
2185 | ||
2186 | @node Misc Options, , Motion Commands, The IDLWAVE Major Mode | |
2187 | @section Miscellaneous Options | |
a8e833f3 | 2188 | @cindex Hooks |
797c8ebc CD |
2189 | |
2190 | @defopt idlwave-help-application | |
2191 | The external application providing reference help for programming. | |
2192 | @end defopt | |
2193 | ||
2194 | @defopt idlwave-startup-message (@code{t}) | |
2195 | Non-@code{nil} means display a startup message when @code{idlwave-mode}' | |
2196 | is first called. | |
2197 | @end defopt | |
2198 | ||
2199 | @defopt idlwave-mode-hook | |
2200 | Normal hook. Executed when a buffer is put into @code{idlwave-mode}. | |
2201 | @end defopt | |
2202 | ||
2203 | @defopt idlwave-load-hook | |
2204 | Normal hook. Executed when @file{idlwave.el} is loaded. | |
2205 | @end defopt | |
2206 | ||
2207 | ||
2208 | ||
797c8ebc CD |
2209 | @node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top |
2210 | @chapter The IDLWAVE Shell | |
2211 | @cindex IDLWAVE shell | |
2212 | @cindex Major mode, @code{idlwave-shell-mode} | |
a8e833f3 CD |
2213 | @cindex IDL, as Emacs subprocess |
2214 | @cindex Subprocess of Emacs, IDL | |
2215 | @cindex Comint, Emacs package | |
2216 | @cindex Windows | |
2217 | @cindex MacOS | |
5af23035 S |
2218 | |
2219 | The IDLWAVE shell is an Emacs major mode which permits running the IDL | |
2220 | program as an inferior process of Emacs, and works closely with the | |
2221 | IDLWAVE major mode in buffers. It can be used to work with IDL | |
2222 | interactively, to compile and run IDL programs in Emacs buffers and to | |
2223 | debug these programs. The IDLWAVE shell is built upon @file{comint}, an | |
2224 | Emacs packages which handles the communication with the IDL program. | |
2225 | Unfortunately IDL for Windows and MacOS do not have command-prompt | |
2226 | versions and thus do not allow the interaction with | |
2227 | Emacs@footnote{Please inform the maintainer if you come up with a way to | |
2228 | make the IDLWAVE shell work on these systems.} --- so the IDLWAVE shell | |
76959b77 | 2229 | currently only works under Unix. |
797c8ebc CD |
2230 | |
2231 | @menu | |
2232 | * Starting the Shell:: How to launch IDL as a subprocess | |
2233 | * Using the Shell:: Interactively working with the Shell | |
177c0ea7 JB |
2234 | * Commands Sent to the Shell:: |
2235 | * Debugging IDL Programs:: | |
2236 | * Examining Variables:: | |
2237 | * Custom Expression Examination:: | |
797c8ebc CD |
2238 | @end menu |
2239 | ||
2240 | @node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell | |
2241 | @section Starting the Shell | |
2242 | @cindex Starting the shell | |
2243 | @cindex Shell, starting | |
2244 | @cindex Dedicated frame, for shell buffer | |
2245 | @cindex Frame, for shell buffer | |
a8e833f3 | 2246 | @cindex Subprocess of Emacs, IDL |
797c8ebc | 2247 | |
a8e833f3 | 2248 | @kindex C-c C-s |
797c8ebc CD |
2249 | The IDLWAVE shell can be started with the command @kbd{M-x |
2250 | idlwave-shell}. In @code{idlwave-mode} the function is bound to | |
2251 | @kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to | |
2252 | interact with the shell. If the shell is already running, @kbd{C-c C-s} | |
2253 | will simple switch to the shell buffer. The command @kbd{C-c C-l} | |
5af23035 S |
2254 | (@code{idlwave-shell-recenter-shell-window}) displays the shell window |
2255 | without selecting it. The shell can also be started automatically when | |
2256 | another command tries to send a command to it. To enable auto start, | |
2257 | set the variable @code{idlwave-shell-automatic-start} to @code{t}. | |
797c8ebc CD |
2258 | |
2259 | In order to create a separate frame for the IDLWAVE shell buffer, call | |
2260 | @code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or | |
2261 | @kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell | |
2262 | window, configure the variable | |
177c0ea7 | 2263 | @code{idlwave-shell-use-dedicated-frame}. |
797c8ebc | 2264 | |
5af23035 S |
2265 | To launch a quick IDLWAVE shell directly from a shell prompt without an |
2266 | IDLWAVE buffer (e.g., as a replacement for running inside an xterm), | |
2267 | define an alias with the following content: | |
2268 | ||
2269 | @example | |
2270 | emacs -geometry 80x32 -eval "(idlwave-shell 'quick)" | |
2271 | @end example | |
797c8ebc | 2272 | |
5af23035 S |
2273 | Replace the @samp{-geometry 80x32} option with @samp{-nw} if you prefer |
2274 | the Emacs process to run directly inside the terminal window. | |
2275 | ||
2276 | @defopt idlwave-shell-explicit-file-name (@file{idl}) | |
797c8ebc CD |
2277 | This is the command to run IDL. |
2278 | @end defopt | |
2279 | ||
2280 | @defopt idlwave-shell-command-line-options | |
2281 | A list of command line options for calling the IDL program. | |
2282 | @end defopt | |
2283 | ||
2284 | @defopt idlwave-shell-prompt-pattern | |
2285 | Regexp to match IDL prompt at beginning of a line. | |
2286 | @end defopt | |
2287 | ||
2288 | @defopt idlwave-shell-process-name | |
2289 | Name to be associated with the IDL process. | |
2290 | @end defopt | |
2291 | ||
5af23035 | 2292 | @defopt idlwave-shell-automatic-start (@code{nil}) |
797c8ebc CD |
2293 | Non-@code{nil} means attempt to invoke idlwave-shell if not already |
2294 | running. | |
2295 | @end defopt | |
2296 | ||
2297 | @defopt idlwave-shell-initial-commands | |
2298 | Initial commands, separated by newlines, to send to IDL. | |
2299 | @end defopt | |
2300 | ||
5af23035 S |
2301 | @defopt idlwave-shell-save-command-history (@code{t}) |
2302 | Non-@code{nil} means preserve command history between sessions. | |
2303 | @end defopt | |
2304 | ||
2305 | @defopt idlwave-shell-command-history-file (@file{~/.idlwhist}) | |
2306 | The file in which the command history of the idlwave shell is saved. | |
2307 | @end defopt | |
177c0ea7 | 2308 | |
797c8ebc | 2309 | @defopt idlwave-shell-use-dedicated-frame (@code{nil}) |
5af23035 | 2310 | Non-@code{nil} means IDLWAVE should use a special frame to display |
177c0ea7 | 2311 | shell buffer. |
797c8ebc CD |
2312 | @end defopt |
2313 | ||
2314 | @defopt idlwave-shell-frame-parameters | |
2315 | The frame parameters for a dedicated idlwave-shell frame. | |
2316 | @end defopt | |
2317 | ||
5af23035 S |
2318 | @defopt idlwave-shell-raise-frame (@code{t}) |
2319 | Non-@code{nil} means `idlwave-shell' raises the frame showing the shell | |
2320 | window. | |
2321 | @end defopt | |
2322 | ||
797c8ebc | 2323 | @defopt idlwave-shell-temp-pro-prefix |
a8e833f3 | 2324 | The prefix for temporary IDL files used when compiling regions. |
797c8ebc CD |
2325 | @end defopt |
2326 | ||
a8e833f3 | 2327 | @cindex Hooks |
797c8ebc CD |
2328 | @defopt idlwave-shell-mode-hook |
2329 | Hook for customizing @code{idlwave-shell-mode}. | |
2330 | @end defopt | |
2331 | ||
76959b77 | 2332 | @node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell |
797c8ebc | 2333 | @section Using the Shell |
a8e833f3 | 2334 | @cindex Comint |
797c8ebc CD |
2335 | @cindex Shell, basic commands |
2336 | ||
2337 | The IDLWAVE shell works in the same fashion as other shell modes in | |
2338 | Emacs. It provides command history, command line editing and job | |
aea44e56 CD |
2339 | control. The @key{UP} and @key{DOWN} arrows cycle through the input |
2340 | history just like in an X terminal@footnote{This is different from | |
2341 | normal Emacs/Comint behavior, but more like an xterm. If you prefer the | |
2342 | default comint functionality, check the variable | |
5af23035 S |
2343 | @code{idlwave-shell-arrows-do-history}.}. The history is preserved |
2344 | between emacs and IDL sessions. Here is a list of commonly used | |
2345 | commands: | |
797c8ebc CD |
2346 | |
2347 | @multitable @columnfractions .12 .88 | |
76959b77 | 2348 | @item @key{UP}, @key{M-p} |
aea44e56 | 2349 | @tab Cycle backwards in input history |
76959b77 | 2350 | @item @key{DOWN}, @key{M-n} |
aea44e56 | 2351 | @tab Cycle forwards in input history |
797c8ebc CD |
2352 | @item @kbd{M-r} |
2353 | @tab Previous input matching a regexp | |
2354 | @item @kbd{M-s} | |
76959b77 | 2355 | @tab Next input matching a regexp |
797c8ebc CD |
2356 | @item @kbd{return} |
2357 | @tab Send input or copy line to current prompt | |
2358 | @item @kbd{C-c C-a} | |
2359 | @tab Beginning of line; skip prompt | |
2360 | @item @kbd{C-c C-u} | |
2361 | @tab Kill input to beginning of line | |
2362 | @item @kbd{C-c C-w} | |
2363 | @tab Kill word before cursor | |
2364 | @item @kbd{C-c C-c} | |
2365 | @tab Send ^C | |
2366 | @item @kbd{C-c C-z} | |
2367 | @tab Send ^Z | |
2368 | @item @kbd{C-c C-\} | |
2369 | @tab Send ^\ | |
2370 | @item @kbd{C-c C-o} | |
2371 | @tab Delete last batch of process output | |
2372 | @item @kbd{C-c C-r} | |
2373 | @tab Show last batch of process output | |
2374 | @item @kbd{C-c C-l} | |
2375 | @tab List input history | |
2376 | @end multitable | |
2377 | ||
2378 | In addition to these standard @file{comint} commands, | |
76959b77 S |
2379 | @code{idlwave-shell-mode} provides many of the same commands which |
2380 | simplify writing IDL code available in IDLWAVE buffers. This includes | |
2381 | abbreviations, online help, and completion. See @ref{Routine Info} and | |
2382 | @ref{Online Help} and @ref{Completion} for more information on these | |
2383 | commands. | |
a8e833f3 CD |
2384 | |
2385 | @cindex Completion, in the shell | |
2386 | @cindex Routine info, in the shell | |
2387 | @cindex Online Help, in the shell | |
797c8ebc CD |
2388 | @multitable @columnfractions .12 .88 |
2389 | @item @kbd{@key{TAB}} | |
5af23035 S |
2390 | @tab Completion of file names (between quotes and after executive |
2391 | commands @samp{.run} and @samp{.compile}), routine names, class names, | |
2392 | keywords, system variables, system variable tags etc. | |
2393 | (@code{idlwave-shell-complete}). | |
797c8ebc CD |
2394 | @item @kbd{M-@key{TAB}} |
2395 | @tab Same as @key{TAB} | |
2396 | @item @kbd{C-c ?} | |
2397 | @tab Routine Info display (@code{idlwave-routine-info}) | |
2398 | @item @kbd{M-?} | |
2399 | @tab IDL online help on routine (@code{idlwave-routine-info-from-idlhelp}) | |
2400 | @item @kbd{C-c C-i} | |
2401 | @tab Update routine info from buffers and shell | |
2402 | (@code{idlwave-update-routine-info}) | |
2403 | @item @kbd{C-c C-v} | |
2404 | @tab Find the source file of a routine (@code{idlwave-find-module}) | |
2405 | @item @kbd{C-c =} | |
2406 | @tab Compile a library routine (@code{idlwave-resolve}) | |
2407 | @end multitable | |
2408 | ||
aea44e56 CD |
2409 | @defopt idlwave-shell-arrows-do-history (@code{t}) |
2410 | Non-@code{nil} means @key{UP} and @key{DOWN} arrows move through command | |
2411 | history like xterm. | |
2412 | @end defopt | |
2413 | ||
5af23035 S |
2414 | @defopt idlwave-shell-comint-settings |
2415 | Alist of special settings for the comint variables in the IDLWAVE Shell. | |
2416 | @end defopt | |
2417 | ||
797c8ebc CD |
2418 | @defopt idlwave-shell-file-name-chars |
2419 | The characters allowed in file names, as a string. Used for file name | |
a8e833f3 CD |
2420 | completion. |
2421 | @end defopt | |
2422 | ||
aea44e56 CD |
2423 | @defopt idlwave-shell-graphics-window-size |
2424 | Size of IDL graphics windows popped up by special IDLWAVE command. | |
2425 | @end defopt | |
2426 | ||
a8e833f3 CD |
2427 | @cindex Input mode |
2428 | @cindex Character input mode (Shell) | |
2429 | @cindex Line input mode (Shell) | |
2430 | @cindex Magic spells, for input mode | |
2431 | @cindex Spells, magic | |
2432 | IDLWAVE works in line input mode: You compose a full command line, using | |
2433 | all the power Emacs gives you to do this. When you press @key{RET}, the | |
2434 | whole line is sent to IDL. Sometimes it is necessary to send single | |
2435 | characters (without a newline), for example when an IDL program is | |
2436 | waiting for single character input with the @code{GET_KBRD} function. | |
2437 | You can send a single character to IDL with the command @kbd{C-c C-x} | |
2438 | (@code{idlwave-shell-send-char}). When you press @kbd{C-c C-y} | |
2439 | (@code{idlwave-shell-char-mode-loop}), IDLWAVE runs a blocking loop | |
2440 | which accepts characters and immediately sends them to IDL. The loop | |
2441 | can be exited with @kbd{C-g}. It terminates also automatically when the | |
2442 | current IDL command is finished. Check the documentation of the two | |
2443 | variables described below for a way to make IDL programs trigger | |
2444 | automatic switches of the input mode. | |
2445 | ||
2446 | @defopt idlwave-shell-use-input-mode-magic (@code{nil}) | |
5af23035 S |
2447 | Non-@code{nil} means IDLWAVE should check for input mode spells in |
2448 | output. | |
a8e833f3 CD |
2449 | @end defopt |
2450 | ||
2451 | @defopt idlwave-shell-input-mode-spells | |
2452 | The three regular expressions which match the magic spells for input | |
2453 | modes. | |
797c8ebc CD |
2454 | @end defopt |
2455 | ||
76959b77 S |
2456 | @node Commands Sent to the Shell, Debugging IDL Programs, Using the Shell, The IDLWAVE Shell |
2457 | @section Commands Sent to the Shell | |
2458 | @cindex Commands in shell, showing | |
2459 | @cindex Showing commands in shell | |
2460 | ||
2461 | The IDLWAVE buffers and shell interact very closely. In addition to the | |
2462 | normal commands you enter at the @code{IDL>} prompt, many other special | |
2463 | commands are sent to the shell, sometimes as a direct result of invoking | |
2464 | a key command, menu item, or toolbar button, but also automatically, as | |
2465 | part of the normal flow of information updates between the buffer and | |
2466 | shell. | |
2467 | ||
2468 | The commands sent include @code{breakpoint}, @code{.step} and other | |
2469 | debug commands (@pxref{Debugging IDL Programs}), @code{.run} and other | |
2470 | compilation statements (@pxref{Compiling Programs}), examination | |
2471 | commands like @code{print} and @code{help} (@pxref{Examining | |
2472 | Variables}), and other special purpose commands designed to keep | |
2473 | information on the running shell current. | |
2474 | ||
2475 | By default, much of this background shell input and output is hidden | |
2476 | from the user, but this is configurable. The custom variable | |
2477 | @code{idlwave-abbrev-show-commands} allows you to configure which | |
2478 | commands sent to the shell are shown there. For a related customization | |
2479 | for separating the output of @emph{examine} commands @xref{Examining | |
2480 | Variables}. | |
2481 | ||
2482 | @defopt idlwave-shell-show-commands (@code{'(run misc breakpoint)}) | |
2483 | A list of command types to echo in the shell when sent. Possible values | |
2484 | are @code{run} for @code{.run}, @code{.compile} and other run commands, | |
2485 | @code{misc} for lesser used commands like @code{window}, @code{retall}, | |
2486 | etc., @code{breakpoint} for breakpoint setting and clearing commands, | |
2487 | and @code{debug} for other debug, stepping, and continue commands. In | |
2488 | addition, if the variable is set to the single symbol @code{'everything}, | |
2489 | all the copious shell input is displayed (which is probably only useful | |
2490 | for debugging purposes). | |
2491 | @end defopt | |
2492 | ||
2493 | @node Debugging IDL Programs, Examining Variables, Commands Sent to the Shell, The IDLWAVE Shell | |
797c8ebc CD |
2494 | @section Debugging IDL Programs |
2495 | @cindex Debugging | |
2496 | @cindex Keybindings for debugging | |
2497 | @cindex Toolbar | |
2498 | ||
2499 | Programs can be compiled, run, and debugged directly from the source | |
76959b77 S |
2500 | buffer in Emacs. IDLWAVE makes compiling and debugging IDL programs |
2501 | far less cumbersome by providing a full-featured, | |
2502 | key/menu/toolbar-driven interface to commands like @code{breakpoint}, | |
2503 | @code{.step}, @code{.run}, etc. | |
2504 | ||
2505 | The IDLWAVE shell installs key bindings both in the shell buffer and in | |
2506 | all IDL code buffers of the current Emacs session, so debug commands | |
2507 | work in both places (in the shell, commands operate on the last file | |
2508 | compiled). On Emacs versions which support this, a debugging toolbar is | |
2509 | also installed. The display of the toolbar can be toggled with @kbd{C-c | |
2510 | C-d C-t} (@code{idlwave-shell-toggle-toolbar}). | |
2511 | ||
2512 | @defopt idlwave-shell-use-toolbar (@code{t}) | |
2513 | Non-@code{nil} means use the debugging toolbar in all IDL related | |
2514 | buffers. | |
2515 | @end defopt | |
2516 | ||
2517 | @menu | |
177c0ea7 JB |
2518 | * Debug Key Bindings:: |
2519 | * Compiling Programs:: | |
2520 | * Breakpoints and Stepping:: | |
2521 | * Walking the Calling Stack:: | |
76959b77 S |
2522 | @end menu |
2523 | ||
2524 | @node Debug Key Bindings, Compiling Programs, Debugging IDL Programs, Debugging IDL Programs | |
2525 | @subsection Debug Key Bindings | |
2526 | @kindex C-c C-d | |
2527 | @cindex Key bindings | |
797c8ebc | 2528 | |
32d4cddb | 2529 | The debugging key bindings are by default on the prefix key @kbd{C-c |
797c8ebc | 2530 | C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d |
76959b77 S |
2531 | C-b}, and compiling a source file with @kbd{C-c C-d C-c}. If you find |
2532 | this too much work, you can easily configure IDLWAVE to use one or more | |
2533 | modifier keys not in use by other commands, in lieu of the prefix | |
2534 | @kbd{C-c C-d} (though these bindings will typically also be available | |
2535 | --- see @code{idlwave-shell-activate-prefix-keybindings}). For example, | |
2536 | if you write in @file{.emacs}: | |
aea44e56 CD |
2537 | |
2538 | @lisp | |
2539 | (setq idlwave-shell-debug-modifiers '(control shift)) | |
2540 | @end lisp | |
2541 | ||
5af23035 | 2542 | @noindent a breakpoint can be set by pressing @kbd{b} while holding down |
aea44e56 | 2543 | @kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a |
5af23035 | 2544 | source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}, |
aea44e56 CD |
2545 | etc. In the remainder of this chapter we will assume that the @kbd{C-c |
2546 | C-d} bindings are active, but each of these bindings will have an | |
5af23035 S |
2547 | equivalent single-keypress shortcut if modifiers are given in the |
2548 | @code{idlwave-shell-debug-modifiers} variable (see @pxref{Lesson II -- | |
2549 | Customization}). | |
797c8ebc | 2550 | |
a8e833f3 | 2551 | @defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) |
797c8ebc | 2552 | The prefix key for the debugging map |
a8e833f3 | 2553 | @code{idlwave-shell-mode-prefix-map}. |
797c8ebc CD |
2554 | @end defopt |
2555 | ||
2556 | @defopt idlwave-shell-activate-prefix-keybindings (@code{t}) | |
5af23035 | 2557 | Non-@code{nil} means debug commands will be bound to the prefix |
797c8ebc CD |
2558 | key, like @kbd{C-c C-d C-b}. |
2559 | @end defopt | |
2560 | ||
aea44e56 | 2561 | @defopt idlwave-shell-debug-modifiers (@code{nil}) |
5af23035 | 2562 | List of modifier keys to use for additional binding of debugging |
76959b77 S |
2563 | commands in the shell and source buffers. Can be one or more of |
2564 | @code{control}, @code{meta}, @code{super}, @code{hyper}, @code{alt}, and | |
2565 | @code{shift}. | |
797c8ebc CD |
2566 | @end defopt |
2567 | ||
76959b77 | 2568 | @node Compiling Programs, Breakpoints and Stepping, Debug Key Bindings, Debugging IDL Programs |
797c8ebc CD |
2569 | @subsection Compiling Programs |
2570 | @cindex Compiling programs | |
2571 | @cindex Programs, compiling | |
2572 | @cindex Default command line, executing | |
2573 | @cindex Executing a default command line | |
2574 | ||
a8e833f3 | 2575 | @kindex C-c C-d C-c |
797c8ebc CD |
2576 | In order to compile the current buffer under the IDLWAVE shell, press |
2577 | @kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the | |
177c0ea7 JB |
2578 | current buffer and then sends the command @samp{.run path/to/file} to the |
2579 | shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in | |
797c8ebc CD |
2580 | which case the most recently compiled buffer will be saved and |
2581 | re-compiled. | |
2582 | ||
177c0ea7 | 2583 | When developing or debugging a program, it is often necessary to execute |
797c8ebc CD |
2584 | the same command line many times. A convenient way to do this is |
2585 | @kbd{C-c C-d C-y} (@code{idlwave-shell-execute-default-command-line}). | |
2586 | This command first resets IDL from a state of interrupted execution by | |
2587 | closing all files and returning to the main interpreter level. Then a | |
2588 | default command line is send to the shell. To edit the default command | |
2589 | line, call @code{idlwave-shell-execute-default-command-line} with a | |
a8e833f3 | 2590 | prefix argument: @kbd{C-u C-c C-d C-y}. |
797c8ebc CD |
2591 | |
2592 | @defopt idlwave-shell-mark-stop-line (@code{t}) | |
5af23035 S |
2593 | Non-@code{nil} means mark the source code line where IDL is currently |
2594 | stopped. The value specifies the preferred method. Legal values are | |
2595 | @code{nil}, @code{t}, @code{arrow}, and @code{face}. | |
797c8ebc CD |
2596 | @end defopt |
2597 | ||
a8e833f3 | 2598 | @defopt idlwave-shell-overlay-arrow (@code{">"}) |
5af23035 S |
2599 | The overlay arrow to display at source lines where execution halts, if |
2600 | configured in @code{idlwave-shell-mark-stop-line}. | |
797c8ebc CD |
2601 | @end defopt |
2602 | ||
2603 | @defopt idlwave-shell-stop-line-face | |
5af23035 S |
2604 | The face which highlights the source line where IDL is stopped, if |
2605 | configured in @code{idlwave-shell-mark-stop-line}. | |
797c8ebc CD |
2606 | @end defopt |
2607 | ||
5af23035 | 2608 | @node Breakpoints and Stepping, Walking the Calling Stack, Compiling Programs, Debugging IDL Programs |
797c8ebc CD |
2609 | @subsection Breakpoints and Stepping |
2610 | @cindex Breakpoints | |
2611 | @cindex Stepping | |
a8e833f3 | 2612 | @cindex Execution, controlled |
797c8ebc | 2613 | |
a8e833f3 CD |
2614 | @kindex C-c C-d C-b |
2615 | @kindex C-c C-d C-b | |
797c8ebc CD |
2616 | You can set breakpoints and step through a program with IDLWAVE. |
2617 | Setting a breakpoint in the current line of the source buffer is done | |
2618 | with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a prefix | |
76959b77 S |
2619 | arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a |
2620 | @code{/ONCE} keyword, meaning that it will be deleted after first use. | |
2621 | With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), the | |
2622 | breakpoint will only be active the @code{nth} time it is hit. With a | |
2623 | single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt for a | |
2624 | condition --- an IDL expression to be evaulated and trigger the | |
2625 | breakpoint only if true. To clear the breakpoint in the current line, | |
5af23035 S |
2626 | use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When executed |
2627 | from the shell window, the breakpoint where IDL is currently stopped | |
2628 | will be deleted. To clear all breakpoints, use @kbd{C-c C-d C-a} | |
2629 | (@code{idlwave-clear-all-bp}). Breakpoint lines are highlighted in the | |
76959b77 S |
2630 | source code. Note that IDL places breakpoints as close as possible on |
2631 | or after the line you specify. IDLWAVE queries the shell for the actual | |
2632 | breakpoint location which was set, so the exact line you specify may not | |
2633 | be marked. | |
5af23035 S |
2634 | |
2635 | Once the program has stopped somewhere, you can step through it. The | |
2636 | most important stepping commands are @kbd{C-c C-d C-s} to execute one | |
2637 | line of IDL code ("step into"); @kbd{C-c C-d C-n} to step a single line, | |
2638 | treating procedure and function calls as a single step ("step over"); | |
2639 | @kbd{C-c C-d C-h} to continue execution to the line at the cursor and | |
76959b77 S |
2640 | @kbd{C-c C-d C-r} to continue execution. @xref{Commands Sent to the |
2641 | Shell}, for information on displaying or hiding the breakpoint and | |
2642 | stepping commands the shell receives. Here is a summary of the | |
5af23035 | 2643 | breakpoint and stepping commands: |
797c8ebc | 2644 | |
a8e833f3 | 2645 | @multitable @columnfractions .23 .77 |
797c8ebc CD |
2646 | @item @kbd{C-c C-d C-b} |
2647 | @tab Set breakpoint (@code{idlwave-shell-break-here}) | |
2648 | @item @kbd{C-c C-d C-i} | |
2649 | @tab Set breakpoint in function named here (@code{idlwave-shell-break-in}) | |
2650 | @item @kbd{C-c C-d C-d} | |
2651 | @tab Clear current breakpoint (@code{idlwave-shell-clear-current-bp}) | |
2652 | @item @kbd{C-c C-d C-a} | |
2653 | @tab Clear all breakpoints (@code{idlwave-shell-clear-all-bp}) | |
2654 | @item @kbd{C-c C-d C-s} | |
2655 | @tab Step, into function calls (@code{idlwave-shell-step}) | |
2656 | @item @kbd{C-c C-d C-n} | |
2657 | @tab Step, over function calls (@code{idlwave-shell-stepover}) | |
2658 | @item @kbd{C-c C-d C-k} | |
2659 | @tab Skip one statement (@code{idlwave-shell-skip}) | |
2660 | @item @kbd{C-c C-d C-u} | |
2661 | @tab Continue to end of block (@code{idlwave-shell-up}) | |
2662 | @item @kbd{C-c C-d C-m} | |
2663 | @tab Continue to end of function (@code{idlwave-shell-return}) | |
2664 | @item @kbd{C-c C-d C-o} | |
2665 | @tab Continue past end of function (@code{idlwave-shell-out}) | |
2666 | @item @kbd{C-c C-d C-h} | |
2667 | @tab Continue to line at cursor position (@code{idlwave-shell-to-here}) | |
2668 | @item @kbd{C-c C-d C-r} | |
2669 | @tab Continue execution to next breakpoint (@code{idlwave-shell-cont}) | |
2670 | @item @kbd{C-c C-d C-up} | |
2671 | @tab Show higher level in calling stack (@code{idlwave-shell-stack-up}) | |
2672 | @item @kbd{C-c C-d C-down} | |
2673 | @tab Show lower level in calling stack (@code{idlwave-shell-stack-down}) | |
2674 | @end multitable | |
2675 | ||
2676 | @defopt idlwave-shell-mark-breakpoints (@code{t}) | |
5af23035 | 2677 | Non-@code{nil} means mark breakpoints in the source file buffers. The |
797c8ebc CD |
2678 | value indicates the preferred method. Legal values are @code{nil}, |
2679 | @code{t}, @code{face}, and @code{glyph}. | |
2680 | @end defopt | |
2681 | ||
2682 | @defopt idlwave-shell-breakpoint-face | |
2683 | The face for breakpoint lines in the source code if | |
a8e833f3 | 2684 | @code{idlwave-shell-mark-breakpoints} has the value @code{face}. |
797c8ebc CD |
2685 | @end defopt |
2686 | ||
5af23035 S |
2687 | @node Walking the Calling Stack, , Breakpoints and Stepping, Debugging IDL Programs |
2688 | @subsection Walking the Calling Stack | |
2689 | @cindex Calling stack, walking | |
2690 | ||
2691 | While debugging a program, it can be very useful to check the context in | |
2692 | which the current routine was called, for instance to help understand | |
2693 | the value of the arguments passed. To do so conveniently you need to | |
2694 | examine the calling stack. If execution is stopped somewhere deep in a | |
2695 | program, you can use the commands @kbd{C-c C-d C-@key{UP}} | |
2696 | (@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}} | |
2697 | (@code{idlwave-shell-stack-down}), or the corresponding toolbar buttons, | |
2698 | to move up or down through the calling stack. The mode line of the | |
2699 | shell window will indicate the position within the stack with a label | |
2700 | like @samp{[-3:MYPRO]}. The line of IDL code at that stack position | |
2701 | will be highlighted. If you continue execution, IDLWAVE will | |
2702 | automatically return to the current level. @xref{Examining Variables}, | |
2703 | for information how to examine the value of variables and expressions on | |
2704 | higher calling stack levels. | |
2705 | ||
76959b77 S |
2706 | @ifhtml |
2707 | <A NAME="EXAMINE"></A> | |
2708 | @end ifhtml | |
5af23035 S |
2709 | @node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell |
2710 | @section Examining Variables | |
797c8ebc CD |
2711 | @cindex @code{PRINT} expressions |
2712 | @cindex @code{HELP}, on expressions | |
2713 | @cindex Expressions, printing | |
2714 | @cindex Expressions, help | |
5af23035 | 2715 | @cindex Printing expressions |
797c8ebc CD |
2716 | @cindex Mouse binding to print expressions |
2717 | ||
a8e833f3 | 2718 | @kindex C-c C-d C-p |
5af23035 S |
2719 | Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)}, |
2720 | and similar statements to remind yourself of the | |
2721 | type/size/structure/value/etc. of variables and expressions in your code | |
2722 | or at the command line? IDLWAVE has a suite of special commands to | |
2723 | automate these types of variables or expression examinations. They work | |
2724 | by sending statements to the shell formatted to include the indicated | |
2725 | expression. | |
2726 | ||
2727 | These examination commands can be used in the shell or buffer at any | |
2728 | time (as long as the shell is running), and are very useful when | |
2729 | execution is stopped in a buffer due to a triggered breakpoint or error, | |
2730 | or while composing a long command in the IDLWAVE shell. In the latter | |
2731 | case, the command is sent to the shell and its output is visible, but | |
2732 | point remains unmoved in the command being composed --- you can inspect | |
28665d46 | 2733 | the constituents of a command you're building without interrupting the |
5af23035 S |
2734 | process of building it! You can even print arbitrary expressions from |
2735 | older input or output further up in the shell window --- any expression, | |
2736 | variable, number, or function you see can be examined. | |
2737 | ||
2738 | If the variable @code{idlwave-shell-separate-examine-output} is | |
2739 | non-@code{nil} (the default), all examine output will be sent to a | |
2740 | special @file{*Examine*} buffer, rather than the shell. The output of | |
2741 | prior examine commands is saved. In this buffer @key{c} clears the | |
2742 | contents, and @key{q} hides the buffer. | |
2743 | ||
2744 | The two most basic examine commands are bound to @kbd{C-c C-d C-p}, to | |
2745 | print the expression at point, and @kbd{C-c C-d ?}, to invoke help on | |
2746 | this expression. The expression at point is either an array expression | |
2747 | or a function call, or the contents of a pair of parentheses. The | |
2748 | selected expression is highlighted, and simultaneously the resulting | |
2749 | output is highlighted in the shell. Calling the above commands with a | |
2750 | prefix argument will prompt for an expression instead of using the one | |
2751 | at point. Two prefix arguments (@kbd{C-u C-u C-c C-d C-p}) will use the | |
2752 | current region as expression. | |
2753 | ||
2754 | For added speed and convenience, there are mouse bindings which allow | |
2755 | you to click on expressions and examine their values. Use | |
32d4cddb | 2756 | @kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke |
5af23035 S |
2757 | help (i.e. you need to hold down @key{META} and @key{CONTROL} while |
2758 | clicking with the middle mouse button). If you simply click, the | |
2759 | nearest expression will be selected in the same manner as described | |
2760 | above. You can also @emph{drag} the mouse in order to highlight exactly | |
2761 | a specific expression or sub-expression to be examined. For custom | |
2762 | expression examination, and the customizable pop-up examine selection, | |
2763 | @xref{Custom Expression Examination}. | |
2764 | ||
a8e833f3 CD |
2765 | @cindex Printing expressions, on calling stack |
2766 | @cindex Restrictions for expression printing | |
5af23035 S |
2767 | The same variable inspection commands work both in the IDL Shell and |
2768 | IDLWAVE buffers, and even for variables at higher levels of the calling | |
2769 | stack. For instance, if you're stopped at a breakpoint in a routine, | |
2770 | you can examine the values of variables and expressions inside its | |
2771 | calling routine, and so on, all the way up through the calling stack. | |
2772 | Simply step up the stack, and print variables as you see them | |
2773 | (@pxref{Walking the Calling Stack}, for information on stepping back | |
2774 | through the calling stack). The following restrictions apply for all | |
2775 | levels except the current: | |
ea442c62 CD |
2776 | |
2777 | @itemize @bullet | |
2778 | @item | |
2779 | Array expressions must use the @samp{[ ]} index delimiters. Identifiers | |
2780 | with a @samp{( )} will be interpreted as function calls. | |
2781 | @item | |
ea442c62 | 2782 | @cindex ROUTINE_NAMES, IDL procedure |
5af23035 S |
2783 | N.B.: printing values of expressions on higher levels of the calling |
2784 | stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, | |
2785 | which may or may not be available in future versions of IDL. | |
ea442c62 CD |
2786 | @end itemize |
2787 | ||
797c8ebc CD |
2788 | @defopt idlwave-shell-expression-face |
2789 | The face for @code{idlwave-shell-expression-overlay}. | |
2790 | Allows you to choose the font, color and other properties for | |
2791 | the expression printed by IDL. | |
2792 | @end defopt | |
2793 | ||
5af23035 | 2794 | @defopt idlwave-shell-output-face |
177c0ea7 | 2795 | The face for @code{idlwave-shell-output-overlay}. |
5af23035 S |
2796 | Allows to choose the font, color and other properties for the most |
2797 | recent output of IDL when examining an expression." | |
2798 | @end defopt | |
2799 | ||
2800 | @defopt idlwave-shell-separate-examine-output (@code{t}) | |
2801 | If non-@code{nil}, re-direct the output of examine commands to a special | |
177c0ea7 | 2802 | @file{*Examine*} buffer, instead of in the shell itself. |
5af23035 S |
2803 | @end defopt |
2804 | ||
2805 | @node Custom Expression Examination, , Examining Variables, The IDLWAVE Shell | |
2806 | @section Custom Expression Examination | |
2807 | @cindex Expressions, custom examination | |
2808 | @cindex Custom expression examination | |
2809 | ||
2810 | The variety of possible variable and expression examination commands is | |
2811 | endless (just look, for instance, at the keyword list to | |
2812 | @code{widget_info()}). Rather than attempt to include them all, IDLWAVE | |
2813 | provides two easy methods to customize your own commands, with a special | |
2814 | mouse examine command, and two macros for generating your own examine | |
2815 | bindings. | |
2816 | ||
2817 | The most powerful and flexible mouse examine command is available on | |
32d4cddb | 2818 | @kbd{C-S-Mouse-2}. Just as for all the other mouse examine commands, it |
5af23035 S |
2819 | permits click or drag expression selection, but instead of sending |
2820 | hard-coded commands to the shell, it pops-up a customizable selection | |
2821 | list of examine functions to choose among, configured with the | |
2822 | @code{idlwave-shell-examine-alist} variable. This variable is a list of | |
2823 | key-value pairs (an @emph{alist} in Emacs parlance), where the keys name | |
2824 | the command, and the values are the command strings, in which the text | |
2825 | @code{___} (three underscores) will be replaced by the selected | |
2826 | expression before being sent to the shell. An example might be key | |
2827 | @code{Structure Help} with value @code{help,___,/STRUCTURE}. | |
32d4cddb S |
2828 | @code{idlwave-shell-examine-alist} comes by default with a large list of |
2829 | examine commands, but can be easily customized to add more. | |
5af23035 | 2830 | |
32d4cddb | 2831 | In addition to the pop-up mouse command, you can easily create your own |
5af23035 S |
2832 | customized bindings to inspect expressions using the two convenience |
2833 | macros @code{idlwave-shell-inspect} and | |
2834 | @code{idlwave-shell-mouse-inspect}. These create keyboard or | |
2835 | mouse-based custom inspections of variables, sharing all the same | |
2836 | properties of the built-in examine commands. Both functions take a | |
2837 | single string argument sharing the syntax of the | |
2838 | @code{idlwave-shell-examine-alist} values, e.g.: | |
797c8ebc | 2839 | |
5af23035 S |
2840 | @lisp |
2841 | (add-hook 'idlwave-shell-mode-hook | |
2842 | (lambda () | |
177c0ea7 JB |
2843 | (idlwave-shell-define-key-both [s-down-mouse-2] |
2844 | (idlwave-shell-mouse-examine | |
5af23035 S |
2845 | "print, size(___,/DIMENSIONS)")) |
2846 | (idlwave-shell-define-key-both [f9] (idlwave-shell-examine | |
2847 | "print, size(___,/DIMENSIONS)")) | |
177c0ea7 | 2848 | (idlwave-shell-define-key-both [f10] (idlwave-shell-examine |
5af23035 S |
2849 | "print,size(___,/TNAME)")) |
2850 | (idlwave-shell-define-key-both [f11] (idlwave-shell-examine | |
2851 | "help,___,/STRUCTURE")))) | |
177c0ea7 JB |
2852 | @end lisp |
2853 | ||
5af23035 S |
2854 | @noindent Now pressing @key{f9}, or middle-mouse dragging with the |
2855 | @key{SUPER} key depressed, will print the dimensions of the nearby or | |
2856 | highlighted expression. Pressing @key{f10} will give the type string, | |
2857 | and @key{f11} will show the contents of a nearby structure. As you can | |
2858 | see, the possibilities are only marginally finite. | |
2859 | ||
2860 | @defopt idlwave-shell-examine-alist | |
2861 | An alist of examine commands in which the keys name the command and are | |
32d4cddb | 2862 | displayed in the selection pop-up, and the values are custom IDL examine |
5af23035 S |
2863 | command strings to send, after all instances of @code{___} are replaced |
2864 | by the indicated expression. | |
2865 | @end defopt | |
2866 | ||
2867 | ||
2868 | @node Installation, Acknowledgements, The IDLWAVE Shell, Top | |
797c8ebc CD |
2869 | @chapter Installation |
2870 | @cindex Installation | |
797c8ebc CD |
2871 | |
2872 | @menu | |
2873 | * Installing IDLWAVE:: How to install the distribution | |
a8e833f3 | 2874 | * Installing Online Help:: Where to get the additional files needed |
797c8ebc CD |
2875 | * Upgrading from idl.el:: Necessary configuration changes |
2876 | @end menu | |
2877 | ||
a8e833f3 | 2878 | @node Installing IDLWAVE, Installing Online Help, Installation, Installation |
797c8ebc CD |
2879 | @section Installing IDLWAVE |
2880 | ||
a8e833f3 CD |
2881 | @cindex FTP site |
2882 | @cindex URL, homepage for IDLWAVE | |
2883 | @cindex Homepage for IDLWAVE | |
2884 | @cindex IDLWAVE, homepage | |
2885 | @cindex XEmacs package IDLWAVE | |
2886 | @cindex Emacs, distributed with IDLWAVE | |
2887 | @cindex Copyright, of IDL manual | |
2888 | IDLWAVE is part of Emacs 21.1 and later. It is also an XEmacs package | |
ea442c62 | 2889 | and can be installed from |
797c8ebc | 2890 | @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site} |
a8e833f3 CD |
2891 | with the normal package management system on XEmacs 21. These |
2892 | pre-installed versions should work out-of-the-box. However, the files | |
5af23035 S |
2893 | required for online help are not distributed with XEmacs/Emacs and have |
2894 | to be installed separately@footnote{Due to copyright reasons, the ASCII | |
a8e833f3 CD |
2895 | version of the IDL manual cannot be distributed under the GPL.} |
2896 | (@pxref{Installing Online Help}). | |
797c8ebc CD |
2897 | |
2898 | You can also download IDLWAVE and install it yourself from | |
a8e833f3 CD |
2899 | @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. Follow the |
2900 | instructions in the INSTALL file. | |
2901 | ||
5af23035 | 2902 | @node Installing Online Help, Upgrading from idl.el, Installing IDLWAVE, Installation |
a8e833f3 CD |
2903 | @section Installing Online Help |
2904 | @cindex Installing online help | |
2905 | @cindex Online Help, Installation | |
797c8ebc | 2906 | |
a8e833f3 CD |
2907 | If you want to use the online help display, two additional files (an |
2908 | ASCII version of the IDL documentation and a topics/code file) must be | |
2909 | installed. These files can also be downloaded from | |
2910 | @uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. You need to | |
2911 | place the files somewhere on your system and tell IDLWAVE where they are | |
2912 | with | |
2913 | ||
2914 | @lisp | |
2915 | (setq idlwave-help-directory "/path/to/help/files/") | |
2916 | @end lisp | |
2917 | ||
2918 | @node Upgrading from idl.el, , Installing Online Help, Installation | |
797c8ebc CD |
2919 | @section Upgrading from the old @b{@file{idl.el}} file |
2920 | @cindex Upgrading from old @b{@file{idl.el}} | |
2921 | @cindex Renaming old variables | |
2922 | @cindex Old variables, renaming | |
a8e833f3 | 2923 | @kindex M-@key{TAB} |
797c8ebc CD |
2924 | |
2925 | If you have been using the old @file{idl.el} and @file{idl-shell.el} | |
2926 | files and would like to use IDLWAVE, you need to update your | |
2927 | customization in @file{.emacs}. | |
2928 | ||
2929 | @enumerate | |
2930 | @item | |
2931 | Change all variable and function prefixes from @samp{idl-} to @samp{idlwave-}. | |
2932 | @item | |
2933 | Remove the now invalid @code{autoload} and @code{auto-mode-alist} forms | |
a8e833f3 CD |
2934 | pointing to the @file{idl.el} and @file{idl-shell.el} files. Install |
2935 | the new autoload forms. | |
797c8ebc CD |
2936 | @item |
2937 | If you have been using the hook function recommended in earlier versions | |
2938 | to get a separate frame for the IDL shell, remove that command from your | |
2939 | @code{idlwave-shell-mode-hook}. Instead, set the variable | |
2940 | @code{idlwave-shell-use-dedicated-frame} with | |
2941 | @lisp | |
2942 | (setq idlwave-shell-use-dedicated-frame t) | |
2943 | @end lisp | |
177c0ea7 | 2944 | @item |
a8e833f3 | 2945 | The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character. |
32d4cddb | 2946 | Like in many other Emacs modes, @kbd{M-@key{TAB}} now does |
a8e833f3 CD |
2947 | completion. Inserting a TAB has therefore been moved to |
2948 | @kbd{C-@key{TAB}}. On a character based terminal you can also use | |
2949 | @kbd{C-c @key{SPC}}. | |
797c8ebc CD |
2950 | @end enumerate |
2951 | ||
5af23035 S |
2952 | @node Acknowledgements, Sources of Routine Info, Installation, Top |
2953 | @chapter Acknowledgements | |
2954 | @cindex Acknowledgements | |
a8e833f3 CD |
2955 | @cindex Maintainer, of IDLWAVE |
2956 | @cindex Authors, of IDLWAVE | |
2957 | @cindex Contributors, to IDLWAVE | |
2958 | @cindex Email address, of Maintainer | |
797c8ebc CD |
2959 | @cindex Thanks |
2960 | ||
a8e833f3 CD |
2961 | @noindent |
2962 | The main contributors to the IDLWAVE package have been: | |
797c8ebc | 2963 | |
a8e833f3 CD |
2964 | @itemize @minus |
2965 | @item | |
aea44e56 CD |
2966 | @uref{mailto:chase@@att.com, @b{Chris Chase}}, the original author. |
2967 | Chris wrote @file{idl.el} and @file{idl-shell.el} and maintained them | |
2968 | for several years. | |
a8e833f3 CD |
2969 | |
2970 | @item | |
5af23035 S |
2971 | @uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge |
2972 | of the package from version 3.0, during which time he overhauled almost | |
2973 | everything, modernized IDLWAVE with many new features, and developed the | |
df59879c | 2974 | manual. |
a8e833f3 | 2975 | |
177c0ea7 | 2976 | @item |
5af23035 S |
2977 | @uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current |
2978 | maintainer, as of version 4.10, helped shape object method completion | |
2979 | and most new features introduced in versions 4.x. | |
a8e833f3 CD |
2980 | @end itemize |
2981 | ||
2982 | @noindent | |
2983 | The following people have also contributed to the development of IDLWAVE | |
2984 | with patches, ideas, bug reports and suggestions. | |
797c8ebc CD |
2985 | |
2986 | @itemize @minus | |
2987 | @item | |
2988 | Ulrik Dickow <dickow@@nbi.dk> | |
2989 | @item | |
2990 | Eric E. Dors <edors@@lanl.gov> | |
2991 | @item | |
2992 | Stein Vidar H. Haugan <s.v.h.haugan@@astro.uio.no> | |
2993 | @item | |
2994 | David Huenemoerder <dph@@space.mit.edu> | |
2995 | @item | |
2996 | Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de> | |
2997 | @item | |
5af23035 S |
2998 | Dick Jackson <dick@@d-jackson.com> |
2999 | @item | |
797c8ebc CD |
3000 | Xuyong Liu <liu@@stsci.edu> |
3001 | @item | |
3002 | Simon Marshall <Simon.Marshall@@esrin.esa.it> | |
3003 | @item | |
aea44e56 CD |
3004 | Craig Markwardt <craigm@@cow.physics.wisc.edu> |
3005 | @item | |
797c8ebc CD |
3006 | Laurent Mugnier <mugnier@@onera.fr> |
3007 | @item | |
3008 | Lubos Pochman <lubos@@rsinc.com> | |
3009 | @item | |
76959b77 S |
3010 | Bob Portmann <portmann@@al.noaa.gov> |
3011 | @item | |
797c8ebc CD |
3012 | Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov> |
3013 | @item | |
3014 | Marty Ryba <ryba@@ll.mit.edu> | |
3015 | @item | |
3016 | Phil Williams <williams@@irc.chmcc.org> | |
3017 | @item | |
797c8ebc CD |
3018 | Phil Sterne <sterne@@dublin.llnl.gov> |
3019 | @end itemize | |
3020 | ||
a8e833f3 CD |
3021 | @noindent |
3022 | Thanks to everyone! | |
3023 | ||
5af23035 | 3024 | @node Sources of Routine Info, Configuration Examples, Acknowledgements, Top |
797c8ebc CD |
3025 | @appendix Sources of Routine Info |
3026 | ||
a8e833f3 | 3027 | @cindex Sources of routine information |
5af23035 S |
3028 | In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE |
3029 | displays the calling sequence and keywords of routines, and completes | |
3030 | routine names and keywords. For these features to work, IDLWAVE must | |
3031 | know about the accessible routines. | |
797c8ebc CD |
3032 | |
3033 | @menu | |
3034 | * Routine Definitions:: Where IDL Routines are defined. | |
a8e833f3 | 3035 | * Routine Information Sources:: So how does IDLWAVE know about... |
aea44e56 | 3036 | * Library Catalog:: Scanning the Libraries for Routine Info |
a8e833f3 CD |
3037 | * Load-Path Shadows:: Routines defined in several places |
3038 | * Documentation Scan:: Scanning the IDL Manuals | |
797c8ebc CD |
3039 | @end menu |
3040 | ||
3041 | @node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info | |
5af23035 | 3042 | @appendixsec Routine Definitions |
797c8ebc | 3043 | @cindex Routine definitions |
a8e833f3 CD |
3044 | @cindex IDL variable @code{!PATH} |
3045 | @cindex @code{!PATH}, IDL variable | |
3046 | @cindex @code{CALL_EXTERNAL}, IDL routine | |
3047 | @cindex @code{LINKIMAGE}, IDL routine | |
3048 | @cindex External routines | |
797c8ebc | 3049 | |
5af23035 S |
3050 | @noindent Routines which can be used in an IDL program can be defined in |
3051 | several places: | |
797c8ebc CD |
3052 | |
3053 | @enumerate | |
177c0ea7 | 3054 | @item |
a8e833f3 | 3055 | @emph{Builtin routines} are defined inside IDL itself. The source |
5af23035 | 3056 | code of such routines is not available. |
797c8ebc | 3057 | @item |
76959b77 S |
3058 | Routines which are @emph{part of the current program}, are defined in a |
3059 | file explicitly compiled by the user. This file may or may not be | |
3060 | located on the IDL search path. | |
177c0ea7 | 3061 | @item |
5af23035 | 3062 | @emph{Library routines} are defined in files located on IDL's search |
76959b77 S |
3063 | path, and will not need to be manually compiled. When a library routine |
3064 | is called for the first time, IDL will find the source file and compile | |
3065 | it dynamically. A special sub-category of library routines are the | |
5af23035 S |
3066 | @emph{system routines} distributed with IDL, and usually available in |
3067 | the @file{lib} subdirectory of the IDL distribution. | |
797c8ebc CD |
3068 | @item |
3069 | External routines written in other languages (like Fortran or C) can be | |
3070 | called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, | |
3071 | or included as dynamically loaded modules (DLMs). Currently IDLWAVE | |
5af23035 | 3072 | cannot provide routine info and completion for such external routines. |
797c8ebc CD |
3073 | @end enumerate |
3074 | ||
aea44e56 | 3075 | @node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info |
5af23035 | 3076 | @appendixsec Routine Information Sources |
797c8ebc | 3077 | @cindex Routine info sources |
a8e833f3 CD |
3078 | @cindex Builtin list of routines |
3079 | @cindex Updating routine info | |
3080 | @cindex Scanning buffers for routine info | |
3081 | @cindex Buffers, scanning for routine info | |
3082 | @cindex Shell, querying for routine info | |
797c8ebc | 3083 | |
5af23035 S |
3084 | @noindent To maintain the most comprehensive information about all IDL |
3085 | routines on a system, IDLWAVE collects data from many sources: | |
797c8ebc CD |
3086 | |
3087 | @enumerate | |
3088 | ||
3089 | @item | |
3090 | It has a @emph{builtin list} with the properties of the builtin IDL | |
3091 | routines. IDLWAVE @value{VERSION} is distributed with a list of | |
3092 | @value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords, | |
3093 | reflecting IDL version @value{IDLVERSION}. This list has been created | |
3094 | by scanning the IDL manuals and is stored in the file | |
5af23035 S |
3095 | @file{idlw-rinfo.el}. @xref{Documentation Scan}, for information on how |
3096 | to regenerate this file for new versions of IDL. | |
797c8ebc | 3097 | |
177c0ea7 | 3098 | @item |
797c8ebc CD |
3099 | It @emph{scans} all @emph{buffers} of the current Emacs session for |
3100 | routine definitions. This is done automatically when routine | |
a8e833f3 CD |
3101 | information or completion is first requested by the user. Each new |
3102 | buffer and each buffer which is saved after making changes is also | |
3103 | scanned. The command @kbd{C-c C-i} (@code{idlwave-update-routine-info}) | |
3104 | can be used at any time to rescan all buffers. | |
797c8ebc CD |
3105 | |
3106 | @item | |
5af23035 S |
3107 | If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will |
3108 | @emph{query the shell} for compiled routines and their arguments. This | |
3109 | happens automatically when routine information or completion is first | |
3110 | requested by the user, and each time an Emacs buffer is compiled with | |
3111 | @kbd{C-c C-d C-c}. Though rarely necessary, the command @kbd{C-c C-i} | |
3112 | (@code{idlwave-update-routine-info}) can be used to update the shell | |
3113 | routine data. | |
797c8ebc CD |
3114 | |
3115 | @item | |
5af23035 S |
3116 | IDLWAVE can scan all or selected library source files and store the |
3117 | result in a file which will be automatically loaded just like | |
aea44e56 | 3118 | @file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to |
a8e833f3 | 3119 | scan library files. |
797c8ebc CD |
3120 | @end enumerate |
3121 | ||
5af23035 S |
3122 | Loading routine and catalog information is a time consuming process. |
3123 | Depending on the system and network configuration it can take up to 30 | |
3124 | seconds. In order to minimize the waiting time upon your first | |
3125 | completion or routine info command in a session, IDLWAVE uses Emacs idle | |
3126 | time to do the initialization in 5 steps, yielding to user input in | |
3127 | between. If this gets into your way, set the variable | |
3128 | @code{idlwave-init-rinfo-when-idle-after} to 0 (zero). | |
3129 | ||
3130 | @defopt idlwave-init-rinfo-when-idle-after (@code{10}) | |
3131 | Seconds of idle time before routine info is automatically initialized. | |
3132 | @end defopt | |
3133 | ||
797c8ebc | 3134 | @defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) |
5af23035 | 3135 | Non-@code{nil} means scan all buffers for IDL programs when updating |
a8e833f3 | 3136 | info. |
797c8ebc CD |
3137 | @end defopt |
3138 | ||
3139 | @defopt idlwave-query-shell-for-routine-info (@code{t}) | |
3140 | Non-@code{nil} means query the shell for info about compiled routines. | |
3141 | @end defopt | |
3142 | ||
a8e833f3 CD |
3143 | @defopt idlwave-auto-routine-info-updates |
3144 | Controls under what circumstances routine info is updated automatically. | |
3145 | @end defopt | |
797c8ebc | 3146 | |
aea44e56 | 3147 | @node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info |
5af23035 | 3148 | @appendixsec Library Catalog |
797c8ebc | 3149 | @cindex Library scan |
aea44e56 | 3150 | @cindex Library catalog |
797c8ebc | 3151 | @cindex IDL library routine info |
a8e833f3 CD |
3152 | @cindex Windows |
3153 | @cindex MacOS | |
a8e833f3 CD |
3154 | @cindex IDL variable @code{!DIR} |
3155 | @cindex @code{!DIR}, IDL variable | |
3156 | ||
797c8ebc CD |
3157 | |
3158 | IDLWAVE can extract routine information from library modules and store | |
3159 | that information in a file. To do this, the variable | |
3160 | @code{idlwave-libinfo-file} needs to contain the path to a file in an | |
a8e833f3 CD |
3161 | existing directory (the default is @code{"~/.idlcat.el"}). Since the |
3162 | file will contain lisp code, its name should end in @file{.el}. Under | |
3163 | Windows and MacOS, you also need to specify the search path for IDL | |
3164 | library files in the variable @code{idlwave-library-path}, and the | |
3165 | location of the IDL directory (the value of the @code{!DIR} system | |
5af23035 S |
3166 | variable) in the variable @code{idlwave-system-directory}, like |
3167 | this@footnote{The initial @samp{+} leads to recursive expansion of the | |
3168 | path, just like in IDL}: | |
3169 | ||
3170 | @lisp | |
3171 | (setq idlwave-library-path | |
3172 | '("+c:/RSI/IDL54/lib/" "+c:/user/me/idllibs" )) | |
3173 | (setq idlwave-system-directory "c:/RSI/IDL54/") | |
3174 | @end lisp | |
3175 | ||
32d4cddb | 3176 | @noindent Under GNU and UNIX, these values will be automatically inferred from |
5af23035 | 3177 | an IDLWAVE shell. |
797c8ebc CD |
3178 | |
3179 | The command @kbd{M-x idlwave-create-libinfo-file} can then be used to | |
3180 | scan library files. It brings up a widget in which you can select some | |
a8e833f3 CD |
3181 | or all directories on the search path. If you only want to have routine |
3182 | and completion info of some libraries, it is sufficient to scan those | |
3183 | directories. However, if you want IDLWAVE to detect possible name | |
3184 | conflicts with routines defined in other libraries, the whole pass | |
177c0ea7 | 3185 | should be scanned. |
a8e833f3 CD |
3186 | |
3187 | After selecting directories, click on the @w{@samp{[Scan & Save]}} | |
3188 | button in the widget to scan all files in the selected directories and | |
797c8ebc CD |
3189 | write the resulting routine information into the file |
3190 | @code{idlwave-libinfo-file}. In order to update the library information | |
3191 | from the same directories, call the command | |
3192 | @code{idlwave-update-routine-info} with a double prefix argument: | |
a8e833f3 | 3193 | @w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously |
797c8ebc | 3194 | selected directories, write an updated version of the libinfo file and |
5af23035 S |
3195 | rebuild IDLWAVE's internal lists. If you give three prefix arguments |
3196 | @w{@kbd{C-u C-u C-u C-c C-i}}, updating will be done with a background | |
76959b77 | 3197 | job@footnote{Unix systems only, I think.}. You can continue to work, |
5af23035 | 3198 | and the library catalog will be re-read when it is ready. |
797c8ebc CD |
3199 | |
3200 | A note of caution: Depending on your local installation, the IDL | |
3201 | library can be very large. Parsing it for routine information will take | |
3202 | time and loading this information into Emacs can require a | |
a8e833f3 CD |
3203 | significant amount of memory. However, having this information |
3204 | available will be a great help. | |
797c8ebc CD |
3205 | |
3206 | @defopt idlwave-libinfo-file | |
3207 | File for routine information of the IDL library. | |
3208 | @end defopt | |
3209 | ||
3210 | @defopt idlwave-library-path | |
76959b77 | 3211 | IDL library path for Windows and MacOS. Not needed under Unix. |
797c8ebc CD |
3212 | @end defopt |
3213 | ||
a8e833f3 | 3214 | @defopt idlwave-system-directory |
76959b77 | 3215 | The IDL system directory for Windows and MacOS. Not needed under Unix. |
a8e833f3 CD |
3216 | @end defopt |
3217 | ||
3218 | @defopt idlwave-special-lib-alist | |
3219 | Alist of regular expressions matching special library directories. | |
3220 | @end defopt | |
3221 | ||
aea44e56 | 3222 | @node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info |
5af23035 | 3223 | @appendixsec Load-Path Shadows |
a8e833f3 CD |
3224 | @cindex Load-path shadows |
3225 | @cindex Shadows, load-path | |
3226 | @cindex Duplicate routines | |
3227 | @cindex Multiply defined routines | |
3228 | @cindex Routine definitions, multiple | |
3229 | @cindex Application, testing for shadowing | |
3230 | @cindex Buffer, testing for shadowing | |
3231 | ||
3232 | IDLWAVE can compile a list of routines which are defined in several | |
3233 | different files. Since one definition will hide (shadow) the others | |
3234 | depending on which file is compiled first, such multiple definitions are | |
3235 | called "load-path shadows". IDLWAVE has several routines to scan for | |
aea44e56 | 3236 | load path shadows. The output is placed into the special buffer |
a8e833f3 | 3237 | @file{*Shadows*}. The format of the output is identical to the source |
aea44e56 CD |
3238 | section of the routine info buffer (@pxref{Routine Info}). The |
3239 | different definitions of a routine are listed in the sequence of | |
5af23035 | 3240 | @emph{likelihood of use}. So the first entry will be most likely the |
aea44e56 CD |
3241 | one you'll get if an unsuspecting command uses that routine. Before |
3242 | listing shadows, you should make sure that routine info is up-to-date by | |
3243 | pressing @kbd{C-c C-i}. Here are the different routines: | |
a8e833f3 CD |
3244 | |
3245 | @table @asis | |
3246 | @item @kbd{M-x idlwave-list-buffer-load-path-shadows} | |
3247 | This commands checks the names of all routines defined in the current | |
3248 | buffer for shadowing conflicts with other routines accessible to | |
3249 | IDLWAVE. The command also has a key binding: @kbd{C-c C-b} | |
3250 | @item @kbd{M-x idlwave-list-shell-load-path-shadows}. | |
3251 | Checks all routines compiled under the shell for shadowing. This is | |
3252 | very useful when you have written a complete application. Just compile | |
3253 | the application, use @code{RESOLVE_ALL} to compile any routines used by | |
3254 | your code, update the routine info inside IDLWAVE with @kbd{C-c C-i} and | |
3255 | then check for shadowing. | |
3256 | @item @kbd{M-x idlwave-list-all-load-path-shadows} | |
aea44e56 | 3257 | This command checks all routines accessible to IDLWAVE for conflicts. |
a8e833f3 CD |
3258 | @end table |
3259 | ||
3260 | For these commands to work properly you should have scanned the entire | |
5af23035 S |
3261 | load path, not just selected directories. Also, IDLWAVE should be able |
3262 | to distinguish between the system library files (normally installed in | |
a8e833f3 | 3263 | @file{/usr/local/rsi/idl/lib}) and any site specific or user specific |
5af23035 S |
3264 | files. Therefore, such local files should not be installed inside the |
3265 | @file{lib} directory of the IDL directory. This is also advisable for | |
3266 | many other reasons. | |
a8e833f3 CD |
3267 | |
3268 | @cindex Windows | |
3269 | @cindex MacOS | |
3270 | @cindex IDL variable @code{!DIR} | |
3271 | @cindex @code{!DIR}, IDL variable | |
3272 | Users of Windows and MacOS also must set the variable | |
3273 | @code{idlwave-system-directory} to the value of the @code{!DIR} system | |
3274 | variable in IDL. IDLWAVE appends @file{lib} to the value of this | |
3275 | variable and assumes that all files found on that path are system | |
3276 | routines. | |
3277 | ||
3278 | Another way to find out if a specific routine has multiple definitions | |
3279 | on the load path is routine info display (@pxref{Routine Info}). | |
3280 | ||
3281 | @node Documentation Scan, , Load-Path Shadows, Sources of Routine Info | |
177c0ea7 | 3282 | @appendixsec Documentation Scan |
797c8ebc | 3283 | @cindex @file{get_rinfo} |
c142ce81 | 3284 | @cindex @file{idlw-rinfo.el} |
a8e833f3 CD |
3285 | @cindex @file{idlw-help.txt} |
3286 | @cindex @file{idlw-help.el} | |
3287 | @cindex Scanning the documentation | |
c142ce81 | 3288 | @cindex Perl program, to create @file{idlw-rinfo.el} |
797c8ebc | 3289 | |
a8e833f3 CD |
3290 | IDLWAVE derives it knowledge about system routines from the IDL |
3291 | manuals. The file @file{idlw-rinfo.el} contains the routine information | |
3292 | for the IDL system routines. The Online Help feature of IDLWAVE | |
3293 | requires ASCII versions of some IDL manuals to be available in a | |
3294 | specific format (@file{idlw-help.txt}), along with an Emacs-Lisp file | |
3295 | @file{idlw-help.el} with supporting code and pointers to the ASCII file. | |
3296 | ||
3297 | All 3 files can be derived from the IDL documentation. If you are | |
3298 | lucky, the maintainer of IDLWAVE will always have access to the newest | |
3299 | version of IDL and provide updates. The IDLWAVE distribution also | |
3300 | contains the Perl program @file{get_rinfo} which constructs these files | |
3301 | by scanning selected files from the IDL documentation. Instructions on | |
3302 | how to use @file{get_rinfo} are in the program itself. | |
797c8ebc | 3303 | |
5af23035 S |
3304 | One particularly frustrating situation occurs when a new IDL version is |
3305 | released without the associated documentation updates. Instead, a | |
3306 | @emph{What's New} file containing new and updated documentation is | |
3307 | shipped alongside the previous version's reference material. The | |
3308 | @file{get_rinfo} script can merge this new information into the standard | |
3309 | help text and routine information, as long as it is pre-formatted in a | |
3310 | simple way. See @file{get_rinfo} for more information. | |
3311 | ||
3312 | @node Configuration Examples, Windows and MacOS, Sources of Routine Info, Top | |
797c8ebc CD |
3313 | @appendix Configuration Examples |
3314 | @cindex Configuration examples | |
3315 | @cindex Example configuration | |
a8e833f3 CD |
3316 | @cindex @file{.emacs} |
3317 | @cindex Default settings, of options | |
3318 | @cindex Interview, with the maintainer | |
797c8ebc CD |
3319 | |
3320 | @noindent | |
5af23035 S |
3321 | @b{Question:} You have all these complicated configuration options in |
3322 | your package, but which ones do @emph{you} as the maintainer actually | |
3323 | set in your own configuration? | |
797c8ebc CD |
3324 | |
3325 | @noindent | |
5af23035 S |
3326 | @b{Answer:} Not many, beyond custom key bindings. I set most defaults |
3327 | the way that seems best. However, the default settings do not turn on | |
3328 | features which: | |
a8e833f3 | 3329 | |
797c8ebc CD |
3330 | @itemize @minus |
3331 | @item | |
5af23035 | 3332 | are not self-evident (i.e. too magic) when used by an unsuspecting user. |
797c8ebc | 3333 | @item |
5af23035 | 3334 | are too intrusive. |
797c8ebc | 3335 | @item |
5af23035 | 3336 | will not work properly on all Emacs installations. |
797c8ebc | 3337 | @item |
a8e833f3 | 3338 | break with widely used standards. |
5af23035 S |
3339 | @item |
3340 | use function or other non-standard keys. | |
3341 | @item | |
3342 | are purely personal customizations, like additional key bindings, and | |
3343 | library names. | |
797c8ebc CD |
3344 | @end itemize |
3345 | ||
5af23035 S |
3346 | @noindent To see what I mean, here is the @emph{entire} configuration |
3347 | the old maintainer had in his @file{.emacs}: | |
797c8ebc CD |
3348 | |
3349 | @lisp | |
aea44e56 | 3350 | (setq idlwave-shell-debug-modifiers '(control shift) |
797c8ebc CD |
3351 | idlwave-store-inquired-class t |
3352 | idlwave-shell-automatic-start t | |
a8e833f3 | 3353 | idlwave-main-block-indent 2 |
5af23035 | 3354 | idlwave-init-rinfo-when-idle-after 2 |
a8e833f3 CD |
3355 | idlwave-help-dir "~/lib/emacs/idlwave" |
3356 | idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib") | |
3357 | ("/jhuapl/" . "JHUAPL-Lib") | |
3358 | ("/dominik/lib/idl/" . "MyLib"))) | |
797c8ebc CD |
3359 | @end lisp |
3360 | ||
3361 | However, if you are an Emacs power-user and want IDLWAVE to work | |
5af23035 S |
3362 | completely differently, you can change almost every aspect of it. Here |
3363 | is an example of a much more extensive configuration of IDLWAVE. The | |
a8e833f3 | 3364 | user is King! |
797c8ebc CD |
3365 | |
3366 | @example | |
3367 | ;;; Settings for IDLWAVE mode | |
3368 | ||
3369 | (setq idlwave-block-indent 3) ; Indentation settings | |
3370 | (setq idlwave-main-block-indent 3) | |
3371 | (setq idlwave-end-offset -3) | |
3372 | (setq idlwave-continuation-indent 1) | |
177c0ea7 | 3373 | (setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" |
797c8ebc CD |
3374 | ; anchored at start of line. |
3375 | (setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> | |
3376 | (setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' | |
3377 | (setq idlwave-expand-generic-end t) ; convert END to ENDIF etc... | |
3378 | (setq idlwave-reserved-word-upcase t) ; Make reserved words upper case | |
3379 | ; (with abbrevs only) | |
3380 | (setq idlwave-abbrev-change-case nil) ; Don't force case of expansions | |
3381 | (setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill | |
3382 | (setq idlwave-show-block nil) ; Turn off blinking to begin | |
3383 | (setq idlwave-abbrev-move t) ; Allow abbrevs to move point | |
5af23035 S |
3384 | (setq idlwave-query-class '((method-default . nil) ; No query for method |
3385 | (keyword-default . nil); or keyword completion | |
3386 | ("INIT" . t) ; except for these | |
3387 | ("CLEANUP" . t) | |
3388 | ("SETPROPERTY" .t) | |
3389 | ("GETPROPERTY" .t))) | |
797c8ebc CD |
3390 | |
3391 | ;; Some setting can only be done from a mode hook. Here is an example: | |
797c8ebc CD |
3392 | (add-hook 'idlwave-mode-hook |
3393 | (lambda () | |
797c8ebc CD |
3394 | (setq case-fold-search nil) ; Make searches case sensitive |
3395 | ;; Run other functions here | |
3396 | (font-lock-mode 1) ; Turn on font-lock mode | |
3397 | (idlwave-auto-fill-mode 0) ; Turn off auto filling | |
5af23035 | 3398 | |
32d4cddb | 3399 | ;; Pad with 1 space (if -n is used then make the |
797c8ebc CD |
3400 | ;; padding a minimum of n spaces.) The defaults use -1 |
3401 | ;; instead of 1. | |
3402 | (idlwave-action-and-binding "=" '(idlwave-expand-equal 1 1)) | |
3403 | (idlwave-action-and-binding "<" '(idlwave-surround 1 1)) | |
3404 | (idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-))) | |
3405 | (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) | |
5af23035 | 3406 | |
797c8ebc CD |
3407 | ;; Only pad after comma and with exactly 1 space |
3408 | (idlwave-action-and-binding "," '(idlwave-surround nil 1)) | |
ea442c62 | 3409 | (idlwave-action-and-binding "&" '(idlwave-surround 1 1)) |
5af23035 | 3410 | |
ea442c62 CD |
3411 | ;; Pad only after `->', remove any space before the arrow |
3412 | (idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2)) | |
5af23035 | 3413 | |
797c8ebc CD |
3414 | ;; Set some personal bindings |
3415 | ;; (In this case, makes `,' have the normal self-insert behavior.) | |
3416 | (local-set-key "," 'self-insert-command) | |
5af23035 S |
3417 | (local-set-key [f5] 'idlwave-shell-break-here) |
3418 | (local-set-key [f6] 'idlwave-shell-clear-current-bp) | |
3419 | ||
797c8ebc CD |
3420 | ;; Create a newline, indenting the original and new line. |
3421 | ;; A similar function that does _not_ reindent the original | |
3422 | ;; line is on "\C-j" (The default for emacs programming modes). | |
3423 | (local-set-key "\n" 'idlwave-newline) | |
3424 | ;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. | |
5af23035 S |
3425 | |
3426 | ;; Some personal abbreviations | |
177c0ea7 | 3427 | (define-abbrev idlwave-mode-abbrev-table |
5af23035 S |
3428 | (concat idlwave-abbrev-start-char "wb") "widget_base()" |
3429 | (idlwave-keyword-abbrev 1)) | |
177c0ea7 | 3430 | (define-abbrev idlwave-mode-abbrev-table |
5af23035 S |
3431 | (concat idlwave-abbrev-start-char "on") "obj_new()" |
3432 | (idlwave-keyword-abbrev 1)) | |
797c8ebc CD |
3433 | )) |
3434 | ||
3435 | ;;; Settings for IDLWAVE SHELL mode | |
3436 | ||
3437 | (setq idlwave-shell-overlay-arrow "=>") ; default is ">" | |
3438 | (setq idlwave-shell-use-dedicated-frame t) ; Make a dedicated frame | |
3439 | (setq idlwave-shell-prompt-pattern "^WAVE> ") ; default is "^IDL> " | |
3440 | (setq idlwave-shell-explicit-file-name "wave") | |
3441 | (setq idlwave-shell-process-name "wave") | |
797c8ebc | 3442 | (setq idlwave-shell-use-toolbar nil) ; No toolbar |
5af23035 S |
3443 | |
3444 | ;; Most shell interaction settings can be done from the shell-mode-hook. | |
3445 | (add-hook 'idlwave-shell-mode-hook | |
3446 | (lambda () | |
3447 | ;; Set up some custom key and mouse examine commands | |
177c0ea7 JB |
3448 | (idlwave-shell-define-key-both [s-down-mouse-2] |
3449 | (idlwave-shell-mouse-examine | |
5af23035 S |
3450 | "print, size(___,/DIMENSIONS)")) |
3451 | (idlwave-shell-define-key-both [f9] (idlwave-shell-examine | |
3452 | "print, size(___,/DIMENSIONS)")) | |
177c0ea7 | 3453 | (idlwave-shell-define-key-both [f10] (idlwave-shell-examine |
5af23035 S |
3454 | "print,size(___,/TNAME)")) |
3455 | (idlwave-shell-define-key-both [f11] (idlwave-shell-examine | |
3456 | "help,___,/STRUCTURE")))) | |
797c8ebc CD |
3457 | @end example |
3458 | ||
76959b77 S |
3459 | @ifhtml |
3460 | <A NAME="WIN_MAC"></A> | |
3461 | @end ifhtml | |
5af23035 S |
3462 | @node Windows and MacOS, Index, Configuration Examples, Top |
3463 | @appendix Windows and MacOS | |
3464 | @cindex Windows | |
3465 | @cindex MacOS | |
3466 | ||
3467 | IDLWAVE was developed on a UNIX system. However, due to the portability | |
3468 | of Emacs, much of IDLWAVE does also work under different operating | |
3469 | systems like Windows (with NTEmacs or NTXEmacs) or MacOS. | |
3470 | ||
3471 | The only problem really is that RSI does not provide a command-line | |
76959b77 S |
3472 | version of IDL for Windows or MacOS with which IDLWAVE can |
3473 | interact@footnote{Call your RSI representative and complain --- it | |
3474 | should be trivial for them to provide one. And if enough people ask | |
3475 | for it, maybe they will. The upcoming IDL for Mac OSX is slated to | |
3476 | have a command-line version.}. Therefore the IDLWAVE Shell does not | |
3477 | work and you have to rely on IDLDE to run and debug your programs. | |
3478 | However, editing IDL source files with Emacs/IDLWAVE works with all | |
3479 | bells and whistles, including routine info, completion and fast online | |
3480 | help. Only a small amount of additional information must be specified | |
3481 | in your .emacs file: the path names which, on a UNIX system, are | |
3482 | automatically gathered by talking to the IDL program. | |
5af23035 S |
3483 | |
3484 | Here is an example of the additional configuration needed for a Windows | |
3485 | system. I am assuming that IDLWAVE has been installed in | |
3486 | @w{@samp{C:\Program Files\IDLWAVE}} and that IDL is installed in | |
3487 | @w{@samp{C:\RSI\IDL55}}. | |
3488 | ||
3489 | @lisp | |
177c0ea7 | 3490 | ;; location of the lisp files (needed if IDLWAVE is not part of |
5af23035 S |
3491 | ;; the X/Emacs installation) |
3492 | (setq load-path (cons "c:/program files/IDLWAVE" load-path)) | |
3493 | ||
3494 | ;; The location of the IDL library files, both from RSI and your own. | |
3495 | ;; note that the initial "+" expands the path recursively | |
3496 | (setq idlwave-library-path | |
3497 | '("+c:/RSI/IDL55/lib/" "+c:/user/me/idllibs" )) | |
3498 | ||
3499 | ;; location of the IDL system directory (try "print,!DIR") | |
3500 | (setq idlwave-system-directory "c:/RSI/IDL55/") | |
3501 | ||
3502 | ;; location of the IDLWAVE help files idlw-help.el and idlw-help.txt. | |
3503 | (setq idlwave-help-directory "c:/IDLWAVE") | |
3504 | ||
3505 | ;; file in which to store the user catalog info | |
3506 | (setq idlwave-libinfo-file "c:/IDLWAVE/idlcat.el") | |
3507 | @end lisp | |
3508 | ||
3509 | @noindent Furthermore, Windows sometimes tries to outsmart you --- make | |
3510 | sure you check the following things: | |
3511 | ||
3512 | @itemize @bullet | |
177c0ea7 | 3513 | @item When you download the IDLWAVE distribution, make sure you save the |
5af23035 S |
3514 | files under the names @file{idlwave.tar.gz} and |
3515 | @file{idlwave-help-tar.gz}. | |
3516 | @item Be sure that your software for untarring/ungzipping is @emph{NOT} | |
3517 | doing smart CR/LF conversion (WinZip users will find this in | |
3518 | Options:Configuration:Miscellaneous, change the setting, then re-open | |
3519 | the archive). This adds one byte per line, throwing off the | |
3520 | byte-counts for the help file lookups and defeating fast online help lookup. | |
3521 | @item M-TAB switches among running programs --- use Esc-TAB | |
3522 | instead. | |
3523 | @item Other issues as yet unnamed... | |
3524 | @end itemize | |
3525 | ||
3526 | ||
3527 | @node Index, , Windows and MacOS, Top | |
797c8ebc CD |
3528 | @unnumbered Index |
3529 | @printindex cp | |
3530 | ||
797c8ebc | 3531 | @bye |
6b61353c KH |
3532 | |
3533 | @ignore | |
3534 | arch-tag: f1d73958-1423-4127-b8aa-f7b953d64492 | |
3535 | @end ignore |