2 |
@c %**start of header |
@c %**start of header |
3 |
@setfilename ../info/idlwave |
@setfilename ../info/idlwave |
4 |
@settitle IDLWAVE User Manual |
@settitle IDLWAVE User Manual |
|
@dircategory Emacs |
|
|
@direntry |
|
|
* IDLWAVE: (idlwave). Major mode and shell for IDL and WAVE/CL files. |
|
|
@end direntry |
|
5 |
@synindex ky cp |
@synindex ky cp |
6 |
@syncodeindex vr cp |
@syncodeindex vr cp |
7 |
@syncodeindex fn cp |
@syncodeindex fn cp |
8 |
@set VERSION 4.7 |
@set VERSION 4.15 |
9 |
@set EDITION 4.7 |
@set EDITION 4.15 |
10 |
@set IDLVERSION 5.4 |
@set IDLVERSION 5.5 |
11 |
@set NSYSROUTINES 1287 |
@set NSYSROUTINES 1324 |
12 |
@set NSYSKEYWORDS 5724 |
@set NSYSKEYWORDS 6129 |
13 |
@set DATE December 2000 |
@set DATE September 2002 |
14 |
@set AUTHOR Carsten Dominik |
@set AUTHOR J.D. Smith & Carsten Dominik |
15 |
@set AUTHOR-EMAIL dominik@@astro.uva.nl |
@set AUTHOR-EMAIL dominik@@astro.uva.nl |
16 |
@set MAINTAINER John-David Smith |
@set MAINTAINER J.D. Smith |
17 |
@set MAINTAINER-EMAIL jdsmith@@astro.cornell.edu |
@set MAINTAINER-EMAIL jdsmith@@as.arizona.edu |
18 |
@set IDLWAVE-HOMEPAGE http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave |
@set IDLWAVE-HOMEPAGE http://idlwave.org/ |
19 |
@c %**end of header |
@c %**end of header |
|
@finalout |
|
20 |
|
|
21 |
@ifinfo |
@copying |
22 |
This file documents IDLWAVE, a major mode for editing IDL and |
This file documents IDLWAVE, a major mode for editing IDL files with |
23 |
WAVE/CL files with Emacs. It also implements a shell for running IDL as |
Emacs, and interacting with an IDL shell run as a subprocess. |
|
a subprocess. |
|
24 |
|
|
25 |
This is edition @value{EDITION} of the IDLWAVE User Manual for |
This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE |
26 |
IDLWAVE @value{VERSION} |
@value{VERSION} |
27 |
|
|
28 |
Copyright (c) 1999, 2000, 2001 Free Software Foundation, Inc. |
Copyright @copyright{} 1999, 2000, 2001, 2002 Free Software Foundation, |
29 |
|
Inc. |
30 |
|
|
31 |
|
@quotation |
32 |
Permission is granted to copy, distribute and/or modify this document |
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 |
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 |
any later version published by the Free Software Foundation; with no |
45 |
Documentation License. If you want to distribute this document |
Documentation License. If you want to distribute this document |
46 |
separately from the collection, you can do so by adding a copy of the |
separately from the collection, you can do so by adding a copy of the |
47 |
license to the document, as described in section 6 of the license. |
license to the document, as described in section 6 of the license. |
48 |
@end ifinfo |
@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 |
57 |
|
|
58 |
@titlepage |
@titlepage |
59 |
@title IDLWAVE User Manual |
@title IDLWAVE User Manual |
60 |
@subtitle Major Emacs mode and shell for IDL and WAVE/CL files |
@subtitle Emacs major mode and shell for IDL |
61 |
@subtitle Edition @value{EDITION}, @value{DATE} |
@subtitle Edition @value{EDITION}, @value{DATE} |
62 |
|
|
63 |
@author by Carsten Dominik |
@author by Carsten Dominik & J.D. Smith |
64 |
@page |
@page |
65 |
This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for |
This is edition @value{EDITION} of the @cite{IDLWAVE User Manual} for |
66 |
IDLWAVE version @value{VERSION}, @value{DATE}. |
IDLWAVE version @value{VERSION}, @value{DATE}. |
|
@sp 2 |
|
|
Copyright @copyright{} 1999, 2000, 2001 Free Software Foundation, Inc. |
|
|
@sp 2 |
|
67 |
@cindex Copyright, of IDLWAVE |
@cindex Copyright, of IDLWAVE |
68 |
|
@insertcopying |
|
Permission is granted to copy, distribute and/or modify this document |
|
|
under the terms of the GNU Free Documentation License, Version 1.1 or |
|
|
any later version published by the Free Software Foundation; with no |
|
|
Invariant Sections, with the Front-Cover texts being ``A GNU |
|
|
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the |
|
|
license is included in the section entitled ``GNU Free Documentation |
|
|
License'' in the Emacs manual. |
|
|
|
|
|
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify |
|
|
this GNU Manual, like GNU software. Copies published by the Free |
|
|
Software Foundation raise funds for GNU development.'' |
|
|
|
|
|
This document is part of a collection distributed under the GNU Free |
|
|
Documentation License. If you want to distribute this document |
|
|
separately from the collection, you can do so by adding a copy of the |
|
|
license to the document, as described in section 6 of the license. |
|
69 |
@end titlepage |
@end titlepage |
70 |
@contents |
@contents |
71 |
|
|
75 |
|
|
76 |
@node Top, Introduction, (dir), (dir) |
@node Top, Introduction, (dir), (dir) |
77 |
|
|
78 |
IDLWAVE is a package to support editing command files for the |
IDLWAVE is a package which supports editing source for the |
79 |
Interactive Data Language (IDL), and for running IDL as an inferior |
Interactive Data Language (IDL), and running IDL as an inferior |
80 |
shell. |
shell. |
81 |
|
|
82 |
@end ifnottex |
@end ifnottex |
83 |
|
|
84 |
@menu |
@menu |
85 |
* Introduction:: What IDLWAVE is and what not |
* Introduction:: What IDLWAVE is and what it's not |
86 |
* IDLWAVE in a Nutshell:: One page quick-start guide |
* IDLWAVE in a Nutshell:: One page quick-start guide |
87 |
* Getting Started:: Tutorial |
* Getting Started:: Tutorial |
88 |
* The IDLWAVE Major Mode:: The mode to edit IDL programs |
* The IDLWAVE Major Mode:: The mode to edit IDL programs |
89 |
* The IDLWAVE Shell:: The mode to run IDL as inferior program |
* The IDLWAVE Shell:: The mode to run IDL as an inferior program |
90 |
* Installation:: How to Install or Upgrade |
* Installation:: How to Install or Upgrade |
91 |
* Acknowledgement:: Who helped |
* Acknowledgements:: Who did what |
92 |
* Sources of Routine Info:: How does IDLWAVE know about routine XYZ |
* Sources of Routine Info:: How does IDLWAVE know about routine XYZ |
93 |
* Configuration Examples:: The user is king... |
* Configuration Examples:: The user is king... |
94 |
|
* Windows and MacOS:: What still works, and how |
95 |
* Index:: Fast access |
* Index:: Fast access |
96 |
|
|
97 |
@detailmenu --- The Detailed Node Listing --- |
@detailmenu |
98 |
|
--- The Detailed Node Listing --- |
99 |
|
|
100 |
|
Getting Started (Tutorial) |
101 |
|
|
102 |
|
* Lesson I -- Development Cycle:: |
103 |
|
* Lesson II -- Customization:: |
104 |
|
* Lesson III -- Library Catalog:: |
105 |
|
|
106 |
The IDLWAVE Major Mode |
The IDLWAVE Major Mode |
107 |
|
|
109 |
* Routine Info:: Calling Sequence and Keyword List |
* Routine Info:: Calling Sequence and Keyword List |
110 |
* Online Help:: One key press from source to help |
* Online Help:: One key press from source to help |
111 |
* Completion:: Completing routine names and Keywords |
* Completion:: Completing routine names and Keywords |
112 |
* Routine Source:: How to visit the source file of routine XYZ |
* Routine Source:: Finding routines, the easy way |
113 |
* Resolving Routines:: Force the Shell to compile a routine |
* Resolving Routines:: Force the Shell to compile a routine |
114 |
* Code Templates:: Abbreviations for frequent constructs |
* Code Templates:: Frequent code constructs |
115 |
|
* Abbreviations:: Abbreviations for common commands |
116 |
* Actions:: Changing case, Padding, End checking |
* Actions:: Changing case, Padding, End checking |
117 |
* Doc Header:: Inserting a standard header |
* Doc Header:: Inserting a standard header |
118 |
* Motion Commands:: Moving through the structure of a program |
* Motion Commands:: Moving through the structure of a program |
121 |
Code Formatting |
Code Formatting |
122 |
|
|
123 |
* Code Indentation:: Reflecting the logical structure |
* Code Indentation:: Reflecting the logical structure |
124 |
|
* Continued Statement Indentation:: |
125 |
* Comment Indentation:: Special indentation for comment lines |
* Comment Indentation:: Special indentation for comment lines |
126 |
* Continuation Lines:: Splitting statements over lines |
* Continuation Lines:: Splitting statements over lines |
127 |
* Syntax Highlighting:: Font-lock support |
* Syntax Highlighting:: Font-lock support |
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? |
134 |
|
* Object Method Completion in the Shell:: |
135 |
|
* Class and Keyword Inheritance:: obj->Method, _EXTRA=e |
136 |
|
* Structure Tag Completion:: Completing state.Tag |
137 |
|
|
138 |
Actions |
Actions |
139 |
|
|
140 |
* Block Boundary Check:: Is the END correct |
* Block Boundary Check:: Is the END statement correct? |
141 |
* Padding Operators:: Enforcing space around `=' etc |
* Padding Operators:: Enforcing space around `=' etc |
142 |
* Case Changes:: Enforcing upper case keywords |
* Case Changes:: Enforcing upper case keywords |
143 |
|
|
145 |
|
|
146 |
* Starting the Shell:: How to launch IDL as a subprocess |
* Starting the Shell:: How to launch IDL as a subprocess |
147 |
* Using the Shell:: Interactively working with the Shell |
* Using the Shell:: Interactively working with the Shell |
148 |
* Debugging IDL Programs:: Compilation/Debugging |
* Commands Sent to the Shell:: |
149 |
|
* Debugging IDL Programs:: |
150 |
|
* Examining Variables:: |
151 |
|
* Custom Expression Examination:: |
152 |
|
|
153 |
Debugging IDL Programs |
Debugging IDL Programs |
154 |
|
|
155 |
* Compiling Programs:: Compiling buffers under the shell |
* Debug Key Bindings:: |
156 |
* Breakpoints and Stepping:: Deciding where to stop and look |
* Compiling Programs:: |
157 |
* Examining Variables:: What is the value now? |
* Breakpoints and Stepping:: |
158 |
|
* Walking the Calling Stack:: |
159 |
|
|
160 |
Installation |
Installation |
161 |
|
|
185 |
@cindex @file{idl-shell.el} |
@cindex @file{idl-shell.el} |
186 |
@cindex Feature overview |
@cindex Feature overview |
187 |
|
|
188 |
IDLWAVE is a package to support editing command files for the |
IDLWAVE is a package which supports editing source files for the |
189 |
Interactive Data Language (IDL), and for running IDL as an inferior |
Interactive Data Language (IDL@footnote{IDL is a registered trademark of |
190 |
shell. It also can be used for WAVE/CL command files, but the support |
Research Systems, Inc., a Kodak Company}), and for running IDL as an |
191 |
for these is limited. Note that this package has nothing to do with the |
inferior shell@footnote{Note that this package has nothing to do with |
192 |
Interface Definition Language as part of the Common Object Request |
the Interface Definition Language, part of the Common Object Request |
193 |
Broker Architecture (CORBA). |
Broker Architecture (CORBA)}. It can also be used for editing source |
194 |
|
files for the related WAVE/CL language, but with only limited |
195 |
IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el} |
support. |
196 |
files written by Chris Chase. The modes and files had to be renamed |
|
197 |
because of a name space conflict with CORBAs @code{idl-mode}, defined in |
IDLWAVE consists of two main parts: a major mode for editing IDL source |
198 |
Emacs in the file @file{cc-mode.el}. If you have been using the old |
files files (@code{idlwave-mode}) and a mode for running the IDL program |
199 |
files, check @ref{Upgrading from idl.el} for information on how to |
as an inferior shell (@code{idlwave-shell-mode}). Although one mode can |
200 |
switch. |
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: |
|
IDLWAVE consists of two parts: A major mode for editing command files |
|
|
(@code{idlwave-mode}) and a mode to allow running the IDL program as an |
|
|
inferior shell (@code{idlwave-shell-mode}). Both modes work closely |
|
|
together and form a complete development environment. |
|
|
|
|
|
Here is a brief summary of what IDLWAVE does. |
|
202 |
|
|
203 |
@itemize @bullet |
@itemize @bullet |
204 |
@item |
@item |
205 |
Code indentation and formatting. |
Code indentation and formatting. |
206 |
@item |
@item |
207 |
Font-lock support on three levels. |
Three level syntax highlighting support. |
|
@item |
|
|
Display of calling sequence and keywords of more than 1000 IDL |
|
|
routines and any routines in your local IDL library. |
|
208 |
@item |
@item |
209 |
Name space conflict search. |
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. |
212 |
@item |
@item |
213 |
Fast context-sensitive online help. |
Routine name space conflict search, likelihood-of-use ranking. |
214 |
|
@item |
215 |
|
Fast, context-sensitive online help. |
216 |
@item |
@item |
217 |
Context sensitive completion of routine names and keywords. |
Context sensitive completion of routine names and keywords. |
218 |
@item |
@item |
219 |
Insertion of code templates. |
Easy insertion of code templates. |
220 |
@item |
@item |
221 |
Actions to enforce coding standards during typing. |
Automatic corrections to enforce a variety of customizable coding |
222 |
|
standards. |
223 |
@item |
@item |
224 |
Block structure check. |
Integrity checks and auto-termination of logical blocks. |
225 |
@item |
@item |
226 |
Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). |
Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). |
227 |
@item |
@item |
228 |
Documentation support. |
Documentation support. |
229 |
@item |
@item |
230 |
Running IDL as inferior process. |
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. |
236 |
@item |
@item |
237 |
Shell with history search, command line editing and completion. |
Quick, source-guided navigation of the calling stack, with variable |
238 |
|
inspection, etc. |
239 |
@item |
@item |
240 |
Compilation, execution and debugging of programs directly from the source |
Examining variables and expressions with a mouse click. |
|
buffer. |
|
241 |
@item |
@item |
242 |
Examining expressions with a mouse click. |
And much, much more... |
243 |
@end itemize |
@end itemize |
244 |
|
|
245 |
@ifnottex |
@ifnottex |
246 |
@cindex Screenshots |
@cindex Screenshots |
247 |
Here are a number of screenshots showing IDLWAVE in action. |
Here are a number of screenshots showing IDLWAVE in action: |
248 |
|
|
249 |
@itemize @bullet |
@itemize @bullet |
250 |
@item |
@item |
251 |
@uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/font-lock.gif, |
@uref{http://idlwave.org/screenshots/emacs_21_nav.gif,An IDLWAVE buffer} |
|
XEmacs 21.1 with formatted and fontified code} |
|
252 |
@item |
@item |
253 |
@uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/rinfo.gif, |
@uref{http://idlwave.org/screenshots/emacs_21_keys.gif,A keyword being completed} |
|
XEmacs 21.1 displaying routine info} |
|
254 |
@item |
@item |
255 |
@uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/complete.gif, |
@uref{http://idlwave.org/screenshots/emacs_21_help.gif,Online help text.} |
|
XEmacs 21.1 completing a keyword} |
|
256 |
@item |
@item |
257 |
@uref{http://www.strw.leidenuniv.nl/~dominik/Tools/idlwave/shell.gif, |
@uref{http://idlwave.org/screenshots/emacs_21_ri.gif,Routine information displayed} |
258 |
XEmacs 21.1 with debugging toolbar; execution stopped at a breakpoint} |
@item |
259 |
|
@uref{http://idlwave.org/screenshots/emacs_21_bp.gif,Debugging code |
260 |
|
stopped at a breakpoint} |
261 |
@end itemize |
@end itemize |
262 |
@end ifnottex |
@end ifnottex |
263 |
|
|
264 |
In this manual, each section contains a list of user options related to |
IDLWAVE is the successor to the @file{idl.el} and @file{idl-shell.el} |
265 |
the subject. Don't be confused by the shear number of options available |
files written by Chris Chase. The modes and files had to be renamed |
266 |
-- in most cases the default settings are just fine. The variables are |
because of a name space conflict with CORBA's @code{idl-mode}, defined in |
267 |
listed here to make sure you know where to look if you want to change |
Emacs in the file @file{cc-mode.el}. If you have been using the old |
268 |
things. For a full description of what a particular variable does and |
files, check @ref{Upgrading from idl.el} for information on how to |
269 |
how to configure it, see the documentation string of that variable. |
switch. |
270 |
Some configuration examples are also given in the appendix. |
|
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. |
279 |
|
|
280 |
@node IDLWAVE in a Nutshell, Getting Started, Introduction, Top |
@node IDLWAVE in a Nutshell, Getting Started, Introduction, Top |
281 |
@chapter IDLWAVE in a Nutshell |
@chapter IDLWAVE in a Nutshell |
290 |
@tab Indent the current line relative to context. |
@tab Indent the current line relative to context. |
291 |
@item @kbd{C-M-\} |
@item @kbd{C-M-\} |
292 |
@tab Re-indent all lines in the current region. |
@tab Re-indent all lines in the current region. |
293 |
|
@item @kbd{C-u @key{TAB}} |
294 |
|
@tab Re-indent all lines in the current statement. |
295 |
@item @kbd{M-@key{RET}} |
@item @kbd{M-@key{RET}} |
296 |
@tab Start a continuation line. Or split the current line at point. |
@tab Start a continuation line, or split the current line at point. |
297 |
@item @kbd{M-q} |
@item @kbd{M-q} |
298 |
@tab Fill the current comment paragraph. |
@tab Fill the current comment paragraph. |
299 |
@item @kbd{C-c ?} |
@item @kbd{C-c ?} |
300 |
@tab Display calling sequence, keywords of the procedure/function call |
@tab Display calling sequence and keywords for the procedure or function call |
301 |
at point. |
at point. |
302 |
@item @kbd{M-?} |
@item @kbd{M-?} |
303 |
@tab Context sensitive online help. |
@tab Load context sensitive online help for nearby routine, keyword, etc. |
304 |
@item @kbd{M-@key{TAB}} |
@item @kbd{M-@key{TAB}} |
305 |
@tab Complete a procedure name, function name or keyword in the buffer. |
@tab Complete a procedure name, function name or keyword in the buffer. |
306 |
@item @kbd{C-c C-i} |
@item @kbd{C-c C-i} |
307 |
@tab Update IDLWAVE's knowledge about functions and procedures. |
@tab Update IDLWAVE's knowledge about functions and procedures. |
308 |
@item @kbd{C-c C-v} |
@item @kbd{C-c C-v} |
309 |
@tab Find the source code of a procedure/function. |
@tab Visit the source code of a procedure/function. |
310 |
@item @kbd{C-c C-h} |
@item @kbd{C-c C-h} |
311 |
@tab Insert a standard documentation header. |
@tab Insert a standard documentation header. |
312 |
@item @kbd{C-c C-m} |
@item @kbd{C-c @key{RET}} |
313 |
@tab Insert a new timestamp and history item in the documentation header. |
@tab Insert a new timestamp and history item in the documentation header. |
314 |
@end multitable |
@end multitable |
315 |
|
|
319 |
@item @kbd{C-c C-s} |
@item @kbd{C-c C-s} |
320 |
@tab Start IDL as a subprocess and/or switch to the interaction buffer. |
@tab Start IDL as a subprocess and/or switch to the interaction buffer. |
321 |
@item @kbd{M-p} |
@item @kbd{M-p} |
322 |
@tab Cycle back through IDL command history matching command line input. |
@tab Cycle back through IDL command history. |
323 |
@item @kbd{M-n} |
@item @kbd{M-n} |
324 |
@tab Cycle forward. |
@tab Cycle forward. |
325 |
@item @kbd{M-@key{TAB}} |
@item @kbd{M-@key{TAB}} |
329 |
@item @kbd{C-c C-d C-x} |
@item @kbd{C-c C-d C-x} |
330 |
@tab Goto next syntax error. |
@tab Goto next syntax error. |
331 |
@item @kbd{C-c C-d C-b} |
@item @kbd{C-c C-d C-b} |
332 |
@tab Set a breakpoint at the current source line. |
@tab Set a breakpoint at the nearest viable source line. |
333 |
@item @kbd{C-c C-d C-d} |
@item @kbd{C-c C-d C-d} |
334 |
@tab Clear the current breakpoint. |
@tab Clear the nearest breakpoint. |
335 |
@item @kbd{C-c C-d C-p} |
@item @kbd{C-c C-d C-p} |
336 |
@tab Ask IDL to print the value of the expression near point. |
@tab Print the value of the expression near point in IDL. |
337 |
@end multitable |
@end multitable |
338 |
|
|
339 |
@subheading Commonly used Settings in @file{.emacs} |
@subheading Commonly used Settings in @file{.emacs} |
340 |
@lisp |
@lisp |
341 |
;; Change the indentation preferences |
;; Change the indentation preferences |
342 |
(setq idlwave-main-block-indent 2 ; default 0 |
(setq idlwave-main-block-indent 2 ; default 0 |
343 |
idlwave-block-indent 2 ; default 4 |
idlwave-block-indent 2 ; default 4 |
344 |
idlwave-end-offset -2) ; default -4 |
idlwave-end-offset -2) ; default -4 |
345 |
|
;; Start autoloading routine info after 2 idle seconds |
346 |
|
(setq idlwave-init-rinfo-when-idle-after 2) |
347 |
;; Pad some operators with spaces |
;; Pad some operators with spaces |
348 |
(setq idlwave-do-actions t |
(setq idlwave-do-actions t |
349 |
idlwave-surround-by-blank t) |
idlwave-surround-by-blank t) |
353 |
(setq idlwave-shell-automatic-start t) |
(setq idlwave-shell-automatic-start t) |
354 |
;; Bind debugging commands with CONTROL and SHIFT modifiers |
;; Bind debugging commands with CONTROL and SHIFT modifiers |
355 |
(setq idlwave-shell-debug-modifiers '(control shift)) |
(setq idlwave-shell-debug-modifiers '(control shift)) |
356 |
;; Where are the online help files? |
;; Specify the online help files' location. |
357 |
(setq idlwave-help-directory "~/.idlwave") |
(setq idlwave-help-directory "~/.idlwave") |
358 |
@end lisp |
@end lisp |
359 |
|
|
360 |
|
@ifhtml |
361 |
|
<A NAME="TUTORIAL"></A> |
362 |
|
@end ifhtml |
363 |
@node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top |
@node Getting Started, The IDLWAVE Major Mode, IDLWAVE in a Nutshell, Top |
364 |
@chapter Getting Started (Tutorial) |
@chapter Getting Started (Tutorial) |
365 |
@cindex Quick-Start |
@cindex Quick-Start |
366 |
@cindex Tutorial |
@cindex Tutorial |
367 |
@cindex Getting Started |
@cindex Getting Started |
368 |
|
|
369 |
@section Lession I: Development Cycle |
@menu |
370 |
|
* Lesson I -- Development Cycle:: |
371 |
|
* Lesson II -- Customization:: |
372 |
|
* Lesson III -- Library Catalog:: |
373 |
|
@end menu |
374 |
|
|
375 |
|
@node Lesson I -- Development Cycle, Lesson II -- Customization, Getting Started, Getting Started |
376 |
|
@section Lesson I: Development Cycle |
377 |
|
|
378 |
The purpose of this tutorial is to guide you through a very basic |
The purpose of this tutorial is to guide you through a very basic |
379 |
development cycle with IDLWAVE. We will type a simple program into a |
development cycle using IDLWAVE. We will paste a simple program into a |
380 |
buffer and use the shell to compile, debug and run this program. On the |
buffer and use the shell to compile, debug and run it. On the way we |
381 |
way we will use the most important commands in IDLWAVE. Note |
will use many of the important IDLWAVE commands. Note however that |
382 |
however that there is much more funtionality available in IDLWAVE than |
there are many more capabilities in IDLWAVE than covered here, which can |
383 |
we cover here, and it will pay off greatly if eventually you go further |
be discovered by reading the entire manual. |
384 |
and read the whole manual. |
|
385 |
|
It is assumed that you have access to Emacs or XEmacs with the full |
386 |
I assume that you have access to Emacs or XEmacs with the full IDLWAVE |
IDLWAVE package including online help (@pxref{Installation}). We also |
387 |
package including online help (@pxref{Installation}). I also assume |
assume that you are familiar with Emacs and can read the nomenclature of |
388 |
that you are familiar with Emacs and can read the nomenclature of key |
key presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL} |
389 |
presses in Emacs (in particular, @kbd{C} stands for @key{CONTROL} and |
and @kbd{M} for @key{META} (often the @key{ALT} key carries this |
|
@kbd{M} for @key{META} (often the @key{ALT} key carries this |
|
390 |
functionality)). |
functionality)). |
391 |
|
|
392 |
Open a new source file by typing |
Open a new source file by typing: |
393 |
|
|
394 |
@example |
@example |
395 |
@kbd{C-x C-f tutorial.pro @key{RET}} |
@kbd{C-x C-f tutorial.pro @key{RET}} |
396 |
@end example |
@end example |
397 |
|
|
398 |
A buffer for this file will pop up, and it should be in IDLWAVE mode. |
A buffer for this file will pop up, and it should be in IDLWAVE mode, as |
399 |
You can see this by looking at the mode line, just below the editing |
shown in the mode line just below the editing window. Also, the menu |
400 |
window. Also, the menu bar should contain entries @samp{IDLWAVE} and |
bar should contain entries @samp{IDLWAVE} and @samp{Debug}. |
|
@samp{Debug}. |
|
401 |
|
|
402 |
Now cut-and-paste the following program, also available as |
Now cut-and-paste the following code, also available as |
403 |
@file{tutorial.pro} in the IDLWAVE distribution. |
@file{tutorial.pro} in the IDLWAVE distribution. |
404 |
|
|
405 |
@example |
@example |
412 |
y1 = y * delta |
y1 = y * delta |
413 |
return, d + floor(m1*30.6)+floor(y1*365.25)+5 |
return, d + floor(m1*30.6)+floor(y1*365.25)+5 |
414 |
end |
end |
415 |
|
|
416 |
function weekday,day,month,year |
function weekday,day,month,year |
417 |
;; compute weekday number for date |
;; compute weekday number for date |
418 |
nr = daynr(day,month,year) |
nr = daynr(day,month,year) |
419 |
return, nr mod 7 |
return, nr mod 7 |
420 |
end |
end |
421 |
|
|
422 |
pro plot_wday,day,month |
pro plot_wday,day,month |
423 |
;; Plot the weekday of a date in the first 10 years of this century. |
;; Plot the weekday of a date in the first 10 years of this century. |
424 |
years = 2000,+indgen(10) |
years = 2000,+indgen(10) |
425 |
wdays = intarr(10) |
wdays = intarr(10) |
426 |
for i=0,n_elements(wdays)-1 do begin |
for i=0,n_elements(wdays)-1 do begin |
427 |
wdays[i] = weekday(day,month,years[i]) |
wdays[i] = weekday(day,month,years[i]) |
428 |
end |
end |
429 |
plot,years,wdays,YS=2,YT="Wday (0=sunday)" |
plot,years,wdays,YS=2,YT="Wday (0=Sunday)" |
430 |
end |
end |
431 |
@end example |
@end example |
432 |
|
|
433 |
The indentation probably looks funny, since it's different from the |
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 |
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 |
line it up (or more quickly @emph{select} the entire buffer with |
436 |
@kbd{C-x h} followed by @kbd{C-M-\}). Notice how different syntactical |
@kbd{C-x h}, and indent the whole region with @kbd{C-M-\}). Notice how |
437 |
elements are highlighted in different colors, if you have set up support |
different syntactical elements are highlighted in different colors, if |
438 |
for font-lock. |
you have set up support for font-lock. |
439 |
|
|
440 |
Let's check out two particular editing features of IDLWAVE. Place the |
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 |
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 |
@key{SPC}. IDLWAVE blinks back to the beginning of the block and |
443 |
changes the generic @code{end} to the specific @code{endfor} |
changes the generic @code{end} to the specific @code{endfor} |
444 |
automatically. Now place the cursor in any line you would like to split |
automatically. Now place the cursor in any line you would like to split |
445 |
into two and press @kbd{M-@key{RET}}. The line is split at the cursor |
and press @kbd{M-@key{RET}}. The line is split at the cursor position, |
446 |
position, with the continuation @samp{$} and indentation all taken care |
with the continuation @samp{$} and indentation all taken care of. Use |
447 |
of. Use @kbd{C-/} to undo the last change. |
@kbd{C-/} to undo the last change. |
448 |
|
|
449 |
The procedure @code{plot_wday} is supposed to plot the weekday of a given |
The procedure @code{plot_wday} is supposed to plot the weekday of a |
450 |
date for the first 10 years of the 21st century. I have put in a few |
given date for the first 10 years of the 21st century. As in most code, |
451 |
bugs which we are going to fix now. |
there are a few bugs, which we are going to use IDLWAVE to help us fix. |
452 |
|
|
453 |
First, let's launch the IDLWAVE shell. You do this with the command |
First, let's launch the IDLWAVE shell. You do this with the command |
454 |
@kbd{C-c C-s}. The Emacs window will split and display IDL running in a |
@kbd{C-c C-s}. The Emacs window will split and display IDL running in a |
455 |
shell interaction buffer. Type a few commands like @code{print,!PI} to |
shell interaction buffer. Type a few commands like @code{print,!PI} to |
456 |
convince yourself that you can work there like in an xterminal, or the |
convince yourself that you can work there just as well as in a terminal, |
457 |
IDLDE. Use the arrow keys to cycle through your command history. Are |
or the IDLDE. Use the arrow keys to cycle through your command history. |
458 |
we having fun now? |
Are we having fun now? |
459 |
|
|
460 |
Now go back to the source window and type @kbd{C-c C-d C-c} to compile |
Now go back to the source window and type @kbd{C-c C-d C-c} to compile |
461 |
the program. If you watch the shell buffer, you see that IDLWAVE types |
the program. If you watch the shell buffer, you see that IDLWAVE types |
462 |
@samp{.run tutorial.pro} for you. But the compilation fails because |
@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 |
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 |
is highlighted and the cursor positioned at the error, so remove the |
465 |
comma (you should only need to hit Delete!). Compile again, using the |
comma (you should only need to hit @kbd{Delete}!). Compile again, using |
466 |
same keystrokes as before. Notice that the file is saved for you. This |
the same keystrokes as before. Notice that the file is automatically |
467 |
time everything should work fine, and you should see the three routines |
saved for you. This time everything should work fine, and you should |
468 |
compile. |
see the three routines compile. |
469 |
|
|
470 |
Now we want to use the command to plot the weekdays for January 1st. We |
Now we want to use the command to plot the day of the week on January |
471 |
could type the full command ourselves, but why do that? Go back to the |
1st. We could type the full command ourselves, but why do that? Go |
472 |
shell window, type @samp{plot_} and hit @key{TAB}. After a bit of a |
back to the shell window, type @samp{plot_} and hit @key{TAB}. After a |
473 |
delay (while IDLWAVE initializes its routine info database), the window |
bit of a delay (while IDLWAVE initializes its routine info database, if |
474 |
will split to show all procedures it knows starting with that string, |
necessary), the window will split to show all procedures it knows |
475 |
and @w{@code{plot_wday}} should be one of them. Saving the buffer was |
starting with that string, and @w{@code{plot_wday}} should be one of |
476 |
enough to tell IDLWAVE about this new routine. Click with the middle |
them. Saving the buffer alerted IDLWAVE about this new routine. Click |
477 |
mouse button on @code{plot_wday} and it will be copied to the shell |
with the middle mouse button on @code{plot_wday} and it will be copied |
478 |
buffer, or if you prefer, add @samp{w} to @samp{plot_} to make it |
to the shell buffer, or if you prefer, add @samp{w} to @samp{plot_} to |
479 |
unambiguous, hit @key{TAB}, and the full routine name will be completed. |
make it unambiguous, hit @key{TAB} again, and the full routine name will |
480 |
Now provide the two arguments: |
be completed. Now provide the two arguments: |
481 |
|
|
482 |
@example |
@example |
483 |
plot_wday,1,1 |
plot_wday,1,1 |
484 |
@end example |
@end example |
485 |
|
|
|
|
|
486 |
and press @key{RET}. This fails with an error message telling you the |
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 |
@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' |
again? Go back to the source window and put the cursor into the `plot' |
489 |
line, and press @kbd{C-c ?}. This pops up the routine info window for |
line, and press @kbd{C-c ?}. This shows the routine info window for the |
490 |
the plot routine, which contains a list of keywords, and the argument |
plot routine, which contains a list of keywords, along with the argument |
491 |
list. Oh, we wanted @code{YTITLE}. Fix that up. Recompile with |
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 |
@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. |
the @key{UP} arrow to recall the previous command and execute again. |
494 |
|
|
495 |
This time we get a plot, but it is pretty ugly -- the points are all |
This time we get a plot, but it is pretty ugly --- the points are all |
496 |
connected with a line. Hmm, isn't there a way for @code{plot} to use |
connected with a line. Hmm, isn't there a way for @code{plot} to use |
497 |
symbols instead? What was that keyword? Position the cursor on the |
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 |
plot line after a comma (where you'd normally type a keyword), and hit |
502 |
to be? With the cursor on or after the keyword, press @kbd{M-?} for |
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 |
online help (alternatively, you could have right clicked on the colored |
504 |
keyword itself in the completion list). The online help window will pop |
keyword itself in the completion list). The online help window will pop |
505 |
up showing the documentation for the @code{PYSM} keyword. Ok, let's use |
up showing the documentation for the @code{PYSM} keyword. OK, let's use |
506 |
diamonds=4. Fix this, recompile (you know the command by now: @kbd{C-c |
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 |
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 |
to recall it by now: @kbd{C-c C-s}) and execute again. Now things look |
509 |
pretty good. |
pretty good. |
510 |
|
|
511 |
Lets try a different day - how about April fool's day? |
Let's try a different day --- how about April fool's day? |
512 |
|
|
513 |
@example |
@example |
514 |
plot_wday,1,4 |
plot_wday,1,4 |
515 |
@end example |
@end example |
516 |
|
|
517 |
Oops, this looks very wrong. All April fool's days cannot be |
Oops, this looks very wrong. All April fool's days cannot be Fridays! |
518 |
Fridays! We've got a bug in the program, perhaps in the @code{daynr} |
We've got a bug in the program, perhaps in the @code{daynr} function. |
519 |
function. Lets put a breakpoint on the last line there. Position the |
Let's put a breakpoint on the last line there. Position the cursor on |
520 |
cursor on the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. |
the @samp{return, d+...} line and press @kbd{C-c C-d C-b}. IDL sets a |
521 |
IDL sets a breakpoint (as you see in the shell window), and the line is |
breakpoint (as you see in the shell window), and the line is highlighted |
522 |
highlighted in some way. Back to the shell buffer, re-execute the |
in some way. Back to the shell buffer, re-execute the previous command. |
523 |
previous command. IDL stops at the line with the breakpoint. Now hold |
IDL stops at the line with the breakpoint. Now hold down the SHIFT key |
524 |
down the SHIFT key and click with the middle mouse button on a few |
and click with the middle mouse button on a few variables there: |
525 |
variables there: @samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe |
@samp{d}, @samp{y}, @samp{m}, @samp{y1}, etc. Maybe @code{d} isn't the |
526 |
@code{d} isn't the correct type. CONTROL-SHIFT middle-click on it for |
correct type. CONTROL-SHIFT middle-click on it for help. Well, it's an |
527 |
help. Well, it's an integer, so that's not the problem. Aha, @samp{y1} |
integer, so that's not the problem. Aha, @samp{y1} is zero, but it |
528 |
is zero, but it should be the year, depending on delta. Shift click |
should be the year, depending on delta. Shift click @samp{delta} to see |
529 |
@samp{delta} to see that it's 0. Below, we see the offending line: |
that it's 0. Below, we see the offending line: @samp{y1=y*delta...} the |
530 |
@samp{y1=y*delta...} the multiplication should have been a minus sign! |
multiplication should have been a minus sign! So fix the line to read: |
|
So fix the line to |
|
531 |
|
|
532 |
@example |
@example |
533 |
y1 = y - delta |
y1 = y - delta |
538 |
Change the code to plot 100 years and see that every 28 years, the |
Change the code to plot 100 years and see that every 28 years, the |
539 |
sequence of weekdays repeats. |
sequence of weekdays repeats. |
540 |
|
|
541 |
@section Lession II: Customization |
@node Lesson II -- Customization, Lesson III -- Library Catalog, Lesson I -- Development Cycle, Getting Started |
542 |
|
@section Lesson II: Customization |
543 |
|
|
544 |
Emacs is probably the most customizable piece of software available, and |
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 |
it would be a shame if you did not make use of this and adapt IDLWAVE to |
546 |
your own preferences. Customizing Emacs or IDLWAVE means that you have |
your own preferences. Customizing Emacs or IDLWAVE is accomplished by |
547 |
to set Lisp variables in the @file{.emacs} file in your home directory. |
setting Lisp variables in the @file{.emacs} file in your home directory |
548 |
This looks scary to many people because of all the parenthesis. |
--- but do not be dismayed; for the most part, you can just copy and work |
549 |
However, you can just cut and paste the examples given here and work |
from the examples given here. |
550 |
from there. |
|
551 |
|
Let's first use a boolean variable. These are variables which you turn |
552 |
Lets first use a boolean variable. These are variables which you turn |
on or off, much like a checkbox. A value of @samp{t} means on, a value |
553 |
on or off, much like a checkbox. A value of @samp{t} means on, a |
of @samp{nil} means off. Copy the following line into your |
|
value of @samp{nil} means off. Copy the following line into your |
|
554 |
@file{.emacs} file, exit and restart Emacs. |
@file{.emacs} file, exit and restart Emacs. |
555 |
|
|
556 |
@lisp |
@lisp |
563 |
@samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this |
@samp{IF}, @samp{begin} to @samp{BEGIN}. If you don't like this |
564 |
behavior, remove the option again from your @file{.emacs} file. |
behavior, remove the option again from your @file{.emacs} file. |
565 |
|
|
566 |
Now I bet you have your own indentation preferences for IDL code. For |
You likely have your own indentation preferences for IDL code. For |
567 |
example, I like to indent the main block of an IDL program a bit, |
example, some like to indent the main block of an IDL program from the |
568 |
different from the conventions used by RSI. Also, I'd like to use only |
margin, different from the conventions used by RSI, and use only 3 |
569 |
3 spaces as indentation between @code{BEGIN} and @code{END}. Try the |
spaces as indentation between @code{BEGIN} and @code{END}. Try the |
570 |
following lines in @file{.emacs} |
following lines in @file{.emacs}: |
571 |
|
|
572 |
@lisp |
@lisp |
573 |
(setq idlwave-main-block-indent 2) |
(setq idlwave-main-block-indent 2) |
575 |
(setq idlwave-end-offset -3) |
(setq idlwave-end-offset -3) |
576 |
@end lisp |
@end lisp |
577 |
|
|
578 |
Restart Emacs, take the program we developed in the first part of this |
Restart Emacs, and re-indent the program we developed in the first part |
579 |
tutorial and re-indent it with @kbd{C-c h} and @kbd{C-M-\}. You |
of this tutorial with @kbd{C-c h} and @kbd{C-M-\}. You may want to keep |
580 |
probably want to keep these lines in @file{.emacs}, with values adjusted |
these lines in @file{.emacs}, with values adjusted to your likings. If |
581 |
to your likings. If you want to get more information about any of these |
you want to get more information about any of these variables, type, |
582 |
variables, type, e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. |
e.g., @kbd{C-h v idlwave-main-block-indent @key{RET}}. To find which |
583 |
To find which variables can be customized, look for items marked |
variables can be customized, look for items marked @samp{User Option:} |
584 |
@samp{User Option:} in the manual. |
throughout this manual. |
585 |
|
|
586 |
If you cannot wrap your head around this Lisp stuff, there is another, |
If you cannot seem to master this Lisp customization in @file{.emacs}, |
587 |
more user-friendly way to customize all the IDLWAVE variables. You can |
there is another, more user-friendly way to customize all the IDLWAVE |
588 |
access it through the IDLWAVE menu in one of the @file{.pro} buffers, |
variables. You can access it through the IDLWAVE menu in one of the |
589 |
option @code{Customize->Browse IDLWAVE Group}. Here you'll be presented |
@file{.pro} buffers, menu item @code{Customize->Browse IDLWAVE |
590 |
with all the various variables grouped into categories. You can |
Group}. Here you'll be presented with all the various variables grouped |
591 |
navigate the hierarchy (e.g. Idlwave Code Formatting->Idlwave Main Block |
into categories. You can navigate the hierarchy (e.g. Idlwave Code |
592 |
Indent), read about the variables, change them, and `Save for Future |
Formatting->Idlwave Main Block Indent), read about the variables, change |
593 |
Sessions'. Few of these variables need customization, but you can |
them, and `Save for Future Sessions'. Few of these variables need |
594 |
exercise considerable control over IDLWAVE's functionality with them. |
customization, but you can exercise considerable control over IDLWAVE's |
595 |
|
functionality with them. |
596 |
Many people I talk to find the key bindings used for the debugging |
|
597 |
commands too long and complicated. Do I always have to type @kbd{C-c |
You may also find the key bindings used for the debugging commands too |
598 |
C-d C-c} to get a single simple command? Due to Emacs rules and |
long and complicated. Often we have heard such complaints, ``Do I |
599 |
conventions I cannot make better bindings by default, but you can. |
really have to type @kbd{C-c C-d C-c} to run a simple command?'' Due to |
600 |
First, there is a way to assign all debugging commands in a single sweep |
Emacs rules and conventions, shorter bindings cannot be set by default, |
601 |
to other combinations. The only problem is that we have to use |
but you can enable them. First, there is a way to assign all debugging |
602 |
something which Emacs does not need for other important commands. A |
commands in a single sweep to other combinations. The only problem is |
603 |
good option is to execute debugging commands by holding down |
that we have to use something which Emacs does not need for other |
604 |
@key{CONTROL} and @key{SHIFT} while pressing a single character: |
important commands. One good option is to execute debugging commands by |
605 |
@kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for compiling the |
holding down @key{CONTROL} and @key{SHIFT} while pressing a single |
606 |
current source file, @kbd{C-S-a} for deleting all breakpoints. You can |
character: @kbd{C-S-b} for setting a breakpoint, @kbd{C-S-c} for |
607 |
have this with |
compiling the current source file, @kbd{C-S-a} for deleting all |
608 |
|
breakpoints. You can enable this with: |
609 |
|
|
610 |
@lisp |
@lisp |
611 |
(setq idlwave-shell-debug-modifiers '(shift control)) |
(setq idlwave-shell-debug-modifiers '(shift control)) |
612 |
@end lisp |
@end lisp |
613 |
|
|
614 |
If you have a special keyboard with for example a @key{HYPER} key, you |
@noindent If you have a special keyboard with, for example, a |
615 |
could use |
@key{HYPER} key, you could even shorten that: |
616 |
|
|
617 |
@lisp |
@lisp |
618 |
(setq idlwave-shell-debug-modifiers '(hyper)) |
(setq idlwave-shell-debug-modifiers '(hyper)) |
619 |
@end lisp |
@end lisp |
620 |
|
|
621 |
instead to get compilation on @kbd{H-c}. |
@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 |
You can also assign specific commands to function keys. This you must |
unused key -- consult your system documentation. |
624 |
do in the @emph{mode-hook}, a special function which is run when a new |
|
625 |
buffer gets set up. Keybindings can only be done when the buffer |
You can also assign specific commands to keys. This you must do in the |
626 |
exists. The possibilities for key customization are endless. Here we |
@emph{mode-hook}, a special function which is run when a new buffer gets |
627 |
set function keys f5-f8 to common debugging commands. |
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. |
630 |
|
|
631 |
@lisp |
@lisp |
632 |
;; First for the source buffer |
;; First for the source buffer |
645 |
(local-set-key [f8] 'idlwave-shell-clear-all-bp))) |
(local-set-key [f8] 'idlwave-shell-clear-all-bp))) |
646 |
@end lisp |
@end lisp |
647 |
|
|
648 |
@section Lession III: Library Catalog |
@node Lesson III -- Library Catalog, , Lesson II -- Customization, Getting Started |
649 |
|
@section Lesson III: Library Catalog |
650 |
|
|
651 |
We have already used the routine info display in the first part of this |
We have already used the routine info display in the first part of this |
652 |
tutorial. This was the key @kbd{C-c ?} which displays information about |
tutorial. This was the key @kbd{C-c ?} which displays information about |
653 |
the IDL routine near the cursor position. Wouldn't it be nice |
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 |
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 |
huge amount of code in major extension libraries like JHUPL or the |
665 |
collects information for each and every IDL routine on your search path. |
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 |
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 |
directory and will from now one be automatically loaded whenever you use |
668 |
IDLWAVE. Try to use routine info (@kbd{C-c ?}) or completion |
IDLWAVE. You may find it necessary to rebuild the catalog on occasion |
669 |
(@kbd{M-<TAB>}) while on any routine or partial routine name you know to |
as your local libraries change. Try to use routine info (@kbd{C-c ?}) |
670 |
be located in the library. E.g., if you have scanned the IDL-Astro |
or completion (@kbd{M-@key{TAB}}) while on any routine or partial routine |
671 |
library: |
name you know to be located in the library. E.g., if you have scanned |
672 |
|
the IDL-Astro library: |
673 |
|
|
674 |
@example |
@example |
675 |
a=readf@key{M-<TAB>} |
a=readf@key{M-<TAB>} |
694 |
the possibilities not discussed in this short tutorial. Read the |
the possibilities not discussed in this short tutorial. Read the |
695 |
manual, look at the documentation strings of interesting variables (with |
manual, look at the documentation strings of interesting variables (with |
696 |
@kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining |
@kbd{C-h v idlwave<-variable-name> @key{RET}}) and ask the remaining |
697 |
questions on @code{comp.lang.idl-pvwave}. |
questions on the newsgroup @code{comp.lang.idl-pvwave}. |
698 |
|
|
699 |
@node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top |
@node The IDLWAVE Major Mode, The IDLWAVE Shell, Getting Started, Top |
700 |
@chapter The IDLWAVE Major Mode |
@chapter The IDLWAVE Major Mode |
701 |
@cindex IDLWAVE major mode |
@cindex IDLWAVE major mode |
702 |
@cindex Major mode, @code{idlwave-mode} |
@cindex Major mode, @code{idlwave-mode} |
703 |
|
|
704 |
The IDLWAVE major mode supports editing IDL and WAVE/CL command files. |
The IDLWAVE major mode supports editing IDL source files. In this |
705 |
In this chapter we describe the main features of the mode and how to |
chapter we describe the main features of the mode and how to customize |
706 |
customize them. |
them. |
707 |
|
|
708 |
@menu |
@menu |
709 |
* Code Formatting:: Making code look nice |
* Code Formatting:: Making code look nice |
710 |
* Routine Info:: Calling Sequence and Keyword List |
* Routine Info:: Calling Sequence and Keyword List |
711 |
* Online Help:: One key press from source to help |
* Online Help:: One key press from source to help |
712 |
* Completion:: Completing routine names and Keywords |
* Completion:: Completing routine names and Keywords |
713 |
* Routine Source:: How to visit the source file of routine XYZ |
* Routine Source:: Finding routines, the easy way |
714 |
* Resolving Routines:: Force the Shell to compile a routine |
* Resolving Routines:: Force the Shell to compile a routine |
715 |
* Code Templates:: Abbreviations for frequent constructs |
* Code Templates:: Frequent code constructs |
716 |
|
* Abbreviations:: Abbreviations for common commands |
717 |
* Actions:: Changing case, Padding, End checking |
* Actions:: Changing case, Padding, End checking |
718 |
* Doc Header:: Inserting a standard header |
* Doc Header:: Inserting a standard header |
719 |
* Motion Commands:: Moving through the structure of a program |
* Motion Commands:: Moving through the structure of a program |
727 |
|
|
728 |
@menu |
@menu |
729 |
* Code Indentation:: Reflecting the logical structure |
* Code Indentation:: Reflecting the logical structure |
730 |
|
* Continued Statement Indentation:: |
731 |
* Comment Indentation:: Special indentation for comment lines |
* Comment Indentation:: Special indentation for comment lines |
732 |
* Continuation Lines:: Splitting statements over lines |
* Continuation Lines:: Splitting statements over lines |
733 |
* Syntax Highlighting:: Font-lock support |
* Syntax Highlighting:: Font-lock support |
734 |
|
* Octals and Highlighting:: Why "123 causes problems |
735 |
@end menu |
@end menu |
736 |
|
|
737 |
@node Code Indentation, Comment Indentation, Code Formatting, Code Formatting |
The IDL language, with it's early roots in FORTRAN, modern |
738 |
@subsection Code Indentation |
implementation in C, and liberal borrowing of features of many vector |
739 |
@cindex Code indentation |
languages along its 25+ year history, has inherited an unusual mix of |
740 |
@cindex Indentation |
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 |
Like all Emacs programming modes, IDLWAVE performs code indentation. |
impossible to adapt. Much can be gleaned from studying available IDL |
743 |
The @key{TAB} key indents the current line relative to context. |
code libraries for coding style pointers, but, due to the variety of |
744 |
@key{LFD} insert a newline and indents the new line. The indentation is |
IDL syntax elements, replicating this style can be challenging at |
745 |
governed by a number of variables. |
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. |
749 |
|
|
750 |
@cindex Foreign code, adapting |
@cindex Foreign code, adapting |
751 |
@cindex Indentation, of foreign code |
@cindex Indentation, of foreign code |
757 |
current subprogram). @xref{Actions}, for information how to impose |
current subprogram). @xref{Actions}, for information how to impose |
758 |
additional formatting conventions on foreign code. |
additional formatting conventions on foreign code. |
759 |
|
|
760 |
@defopt idlwave-main-block-indent (@code{0}) |
@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 |
|
|
772 |
|
@defopt idlwave-main-block-indent (@code{0}) |
773 |
Extra indentation for the main block of code. That is the block between |
Extra indentation for the main block of code. That is the block between |
774 |
the FUNCTION/PRO statement and the END statement for that program |
the FUNCTION/PRO statement and the END statement for that program |
775 |
unit. |
unit. |
776 |
@end defopt |
@end defopt |
777 |
|
|
778 |
@defopt idlwave-block-indent (@code{5}) |
@defopt idlwave-block-indent (@code{4}) |
779 |
Extra indentation applied to block lines. If you change this, you |
Extra indentation applied to block lines. If you change this, you |
780 |
probably also want to change @code{idlwave-end-offset}. |
probably also want to change @code{idlwave-end-offset}. |
781 |
@end defopt |
@end defopt |
786 |
BEGIN lines. |
BEGIN lines. |
787 |
@end defopt |
@end defopt |
788 |
|
|
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 |
|
|
824 |
|
You can instruct IDLWAVE when to avoid using this special continuation |
825 |
|
indentation by setting the variable |
826 |
|
@code{idlwave-max-extra-continuation-indent}, which specifies the |
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. |
838 |
|
|
839 |
|
|
840 |
@defopt idlwave-continuation-indent (@code{2}) |
@defopt idlwave-continuation-indent (@code{2}) |
841 |
Extra indentation applied to continuation lines and inside unbalanced |
Extra indentation applied to normal continuation lines. |
|
parenthesis. |
|
842 |
@end defopt |
@end defopt |
843 |
|
|
844 |
@node Comment Indentation, Continuation Lines, Code Indentation, Code Formatting |
@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. |
857 |
|
@end defopt |
858 |
|
|
859 |
|
@node Comment Indentation, Continuation Lines, Continued Statement Indentation, Code Formatting |
860 |
@subsection Comment Indentation |
@subsection Comment Indentation |
861 |
@cindex Comment indentation |
@cindex Comment indentation |
862 |
@cindex Hanging paragraphs |
@cindex Hanging paragraphs |
873 |
@item @code{;;} |
@item @code{;;} |
874 |
@tab Lines starting with two semicolons are indented like the surrounding code. |
@tab Lines starting with two semicolons are indented like the surrounding code. |
875 |
@item @code{;} |
@item @code{;} |
876 |
@tab Lines starting with a single semicolon are indent to a minimum column. |
@tab Lines starting with a single semicolon are indented to a minimum column. |
877 |
@end multitable |
@end multitable |
878 |
|
|
879 |
@noindent |
@noindent |
880 |
The indentation of comments starting in column 0 is never changed. |
The indentation of comments starting in column 0 is never changed. |
881 |
|
|
882 |
@defopt idlwave-no-change-comment |
@defopt idlwave-no-change-comment |
883 |
The indentation of a comment starting with this regexp will not be changed. |
The indentation of a comment starting with this regexp will not be |
884 |
|
changed. |
885 |
@end defopt |
@end defopt |
886 |
|
|
887 |
@defopt idlwave-begin-line-comment |
@defopt idlwave-begin-line-comment |
903 |
@kindex M-@key{RET} |
@kindex M-@key{RET} |
904 |
In IDL, a newline character terminates a statement unless preceded by a |
In IDL, a newline character terminates a statement unless preceded by a |
905 |
@samp{$}. If you would like to start a continuation line, use |
@samp{$}. If you would like to start a continuation line, use |
906 |
@kbd{M-@key{RET}} which calls the command @code{idlwave-split-line}. It |
@kbd{M-@key{RET}}, which calls the command @code{idlwave-split-line}. |
907 |
inserts a @samp{$} to indicate that the following line is a continuation |
It inserts the continuation character @samp{$}, terminates the line and |
908 |
of the current line, terminates the line with a newline and indents the |
indents the new line. The command @kbd{M-@key{RET}} can also be invoked |
909 |
new line. The command @kbd{M-@key{RET}} can also be used in the middle |
inside a string to split it at that point, in which case the @samp{+} |
910 |
of a line to split the line at that point. When used inside a long |
concatenation operator is used. |
|
string constant, the string is split with the @samp{+} concatenation |
|
|
operator. |
|
911 |
|
|
912 |
@cindex Filling |
@cindex Filling |
913 |
@cindex @code{auto-fill-mode} |
@cindex @code{auto-fill-mode} |
914 |
@cindex Hanging paragraphs |
@cindex Hanging paragraphs |
915 |
When filling comment paragraphs, IDLWAVE overloads the normal filling |
When filling comment paragraphs, IDLWAVE overloads the normal filling |
916 |
functions and uses a function which creates hanging paragraphs as they |
functions and uses a function which creates the hanging paragraphs |
917 |
are customary in the IDL routine headers. When @code{auto-fill-mode} is |
customary in IDL routine headers. When @code{auto-fill-mode} is turned |
918 |
turned on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If |
on (toggle with @kbd{C-c C-a}), comments will be auto-filled. If the |
919 |
the first line of a paragraph is matched by |
first line of a paragraph contains a match for |
920 |
@code{idlwave-hang-indent-regexp}, subsequent lines are indented to |
@code{idlwave-hang-indent-regexp} (a dash-space by default), subsequent |
921 |
after the position of this match, as in the following example. |
lines are positioned to line up after it, as in the following example. |
922 |
|
|
923 |
@example |
@example |
924 |
; INPUTS: |
@group |
925 |
|
;================================= |
926 |
; x - an array containing |
; x - an array containing |
927 |
; lots of interesting numbers. |
; lots of interesting numbers. |
928 |
; |
; |
929 |
; y - another variable where |
; y - another variable where |
930 |
; a hanging paragraph is used |
; a hanging paragraph is used |
931 |
; to describe it. |
; to describe it. |
932 |
|
;================================= |
933 |
|
@end group |
934 |
@end example |
@end example |
935 |
|
|
936 |
@kindex M-q |
@kindex M-q |
937 |
You also refill a comment paragraph with @kbd{M-q}. |
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. |
941 |
|
|
942 |
@defopt idlwave-fill-comment-line-only (@code{t}) |
@defopt idlwave-fill-comment-line-only (@code{t}) |
943 |
Non-@code{nil} means auto fill will only operate on comment lines. |
Non-@code{nil} means auto fill will only operate on comment lines. |
959 |
line of the paragraph. |
line of the paragraph. |
960 |
@end defopt |
@end defopt |
961 |
|
|
962 |
@defopt idlwave-hang-indent-regexp |
@defopt idlwave-hang-indent-regexp (@code{"- "}) |
963 |
Regular expression matching the position of the hanging indent |
Regular expression matching the position of the hanging indent |
964 |
in the first line of a comment paragraph. |
in the first line of a comment paragraph. |
965 |
@end defopt |
@end defopt |
966 |
|
|
967 |
@defopt idlwave-use-last-hang-indent (@code{nil}) |
@defopt idlwave-use-last-hang-indent (@code{nil}) |
968 |
Non-@code{nil} means use last match on line for |
Non-@code{nil} means use last match on line for |
969 |
@code{idlwave-indent-regexp}. |
@code{idlwave-indent-regexp}. |
970 |
@end defopt |
@end defopt |
971 |
|
|
972 |
@node Syntax Highlighting, , Continuation Lines, Code Formatting |
@node Syntax Highlighting, Octals and Highlighting, Continuation Lines, Code Formatting |
973 |
@subsection Syntax Highlighting |
@subsection Syntax Highlighting |
974 |
@cindex Syntax highlighting |
@cindex Syntax highlighting |
975 |
@cindex Highlighting of syntax |
@cindex Highlighting of syntax |
977 |
|
|
978 |
Highlighting of keywords, comments, strings etc. can be accomplished |
Highlighting of keywords, comments, strings etc. can be accomplished |
979 |
with @code{font-lock}. If you are using @code{global-font-lock-mode} |
with @code{font-lock}. If you are using @code{global-font-lock-mode} |
980 |
(on Emacs), or have @code{font-lock} turned on in any other buffer in |
(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 not, |
XEmacs, it should also automatically work in IDLWAVE buffers. If you'd |
982 |
you can enforce it with the following line in your @file{.emacs} |
prefer invoking font-lock individually by mode, you can enforce it in |
983 |
|
@code{idlwave-mode} with the following line in your @file{.emacs}: |
984 |
|
|
985 |
@lisp |
@lisp |
986 |
(add-hook 'idlwave-mode-hook 'turn-on-font-lock) |
(add-hook 'idlwave-mode-hook 'turn-on-font-lock) |
987 |
@end lisp |
@end lisp |
988 |
|
|
989 |
IDLWAVE supports 3 levels of syntax highlighting. The variable |
@noindent IDLWAVE supports 3 increasing levels of syntax highlighting. |
990 |
@code{font-lock-maximum-decoration} determines which level is selected. |
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}. |
994 |
|
|
995 |
@defopt idlwave-default-font-lock-items |
@defopt idlwave-default-font-lock-items |
996 |
Items which should be fontified on the default fontification level |
Items which should be fontified on the default fontification level |
997 |
2. |
2. |
998 |
@end defopt |
@end defopt |
999 |
|
|
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 |
|
|
1030 |
@node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode |
@node Routine Info, Online Help, Code Formatting, The IDLWAVE Major Mode |
1031 |
@section Routine Info |
@section Routine Info |
1032 |
@cindex Routine info |
@cindex Routine info |
1036 |
@cindex Shell, querying for routine info |
@cindex Shell, querying for routine info |
1037 |
|
|
1038 |
@kindex C-c C-i |
@kindex C-c C-i |
1039 |
IDL defines more than one thousand procedures, functions and object |
IDL comes bundled with more than one thousand procedures, functions |
1040 |
methods. This large command set makes it difficult to remember the |
and object methods, and large libraries typically contain hundreds or |
1041 |
calling sequence and keywords of a command. IDLWAVE contains a list of |
even thousands more (each with a few to tens of keywords and |
1042 |
all builtin routines with calling sequences and keywords@footnote{This |
arguments). This large command set can make it difficult to remember |
1043 |
list was created by scanning the IDL manual and might contain (very few) |
the calling sequence and keywords for the routines you use, but |
1044 |
errors. Please report any detected errors to the maintainer, so that |
IDLWAVE can help. It builds up routine information using a wide |
1045 |
they can be fixed.}. It also scans Emacs buffers and library files for |
variety of sources: IDLWAVE in fact knows far more about the routines |
1046 |
routine definitions and queries the IDLWAVE-Shell for the properties of |
on your system than IDL itself. It maintains a list of all built-in |
1047 |
modules currently compiled under the shell. This information is updated |
routines, with calling sequences and keywords@footnote{This list is |
1048 |
automatically. If you think the information is not up-to-date, use |
created by scanning the IDL manuals and might contain (very few) |
1049 |
@kbd{C-c C-i} (@code{idlwave-update-routine-info}) to enforce a global |
errors. Please report any errors to the maintainer, so that they can |
1050 |
update. |
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}). |
1056 |
|
|
1057 |
@kindex C-c ? |
@kindex C-c ? |
1058 |
To display the information about a routine, press @kbd{C-c ?} which |
To display the information about a routine, press @kbd{C-c ?}, which |
1059 |
calls the command @code{idlwave-routine-info}. When the current cursor |
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 |
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, |
function, information will be displayed about the routine. For example, |
1062 |
consider the cursor positions in the following line |
consider the indicated cursor positions in the following line: |
1063 |
|
|
1064 |
@example |
@example |
1065 |
plot,x,alog(x+5*sin(x) + 2), |
plot,x,alog(x+5*sin(x) + 2), |
1066 |
|
| | | | | | | | |
1067 |
1 2 3 4 5 6 7 8 |
1 2 3 4 5 6 7 8 |
1068 |
@end example |
@end example |
1069 |
|
|
1070 |
@cindex Default routine, for info and help |
@cindex Default routine, for info and help |
1071 |
On positions 1,2 and 8, information about the @samp{plot} procedure will |
On positions 1,2 and 8, information about the @samp{plot} procedure will |
1072 |
be shown. On positions 3,4, and 7, the @samp{alog} function will be |
be shown. On positions 3,4, and 7, the @samp{alog} function will be |
1073 |
described, while positions 5 and 6 will select the @samp{sin} function. |
described, while positions 5 and 6 will investigate the @samp{sin} |
1074 |
|
function. |
1075 |
|
|
1076 |
When you ask for routine information about an object method, and the |
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 |
method exists in several classes, IDLWAVE queries for the class of the |
1078 |
object. |
object, unless the class is already known through a text property on the |
1079 |
|
@samp{->} operator (@pxref{Object Method Completion and Class |
1080 |
|
Ambiguity}), or by having been explicitly included in the call |
1081 |
|
(e.g. @code{a->myclass::Foo}). |
1082 |
|
|
1083 |
@cindex Calling sequences |
@cindex Calling sequences |
1084 |
@cindex Keywords of a routine |
@cindex Keywords of a routine |
1105 |
IDLWAVE, several @samp{Source} lines will point to the different files. |
IDLWAVE, several @samp{Source} lines will point to the different files. |
1106 |
This may indicate that your routine is shadowing a library routine, |
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 |
which may or may not be what you want (@pxref{Load-Path Shadows}). The |
1108 |
information about the calling sequence and the keywords is derived from |
information about the calling sequence and keywords is derived from the |
1109 |
the first source listed. Library routines can only be supported if you |
first source listed. Library routines are supported only if you have |
1110 |
have scanned the local IDL library (@pxref{Library Catalog}). The source |
scanned your local IDL libraries (@pxref{Library Catalog}). The source |
1111 |
entry consists of a @emph{source category}, a set of @emph{flags} and |
entry consists of a @emph{source category}, a set of @emph{flags} and |
1112 |
the path to the @emph{source file}. The following categories |
the path to the @emph{source file}. The following categories exist: |
|
exist: |
|
1113 |
|
|
1114 |
@multitable @columnfractions .15 .85 |
@multitable @columnfractions .15 .85 |
1115 |
@item @i{System} |
@item @i{System} |
1116 |
@tab A system routine, but we do not know if it is @i{Builtin} or |
@tab A system routine of unknown origin. When the system library has |
1117 |
@i{SystemLib}. When the system library has bee scanned |
been scanned (@pxref{Library Catalog}), this category will automatically |
1118 |
(@pxref{Library Catalog}), this category will automatically split into the |
split into the next two. |
|
next two. |
|
1119 |
@item @i{Builtin} |
@item @i{Builtin} |
1120 |
@tab A builtin routine with no source code available. |
@tab A builtin system routine with no source code available. |
1121 |
@item @i{SystemLib} |
@item @i{SystemLib} |
1122 |
@tab A library routine in the official lib directory @file{!DIR/lib}. |
@tab A library system routine in the official lib directory @file{!DIR/lib}. |
1123 |
@item @i{Obsolete} |
@item @i{Obsolete} |
1124 |
@tab A library routine in the official lib directory @file{!DIR/lib/obsolete}. |
@tab A library routine in the official lib directory @file{!DIR/lib/obsolete}. |
1125 |
@item @i{Library} |
@item @i{Library} |
1126 |
@tab A file on IDL's search path @code{!PATH}. |
@tab A routine in a file on IDL's search path @code{!PATH}. |
1127 |
@item @i{Other} |
@item @i{Other} |
1128 |
@tab Any other file not known to be on the search path. |
@tab Any other routine with a file not known to be on the search path. |
1129 |
@item @i{Unresolved} |
@item @i{Unresolved} |
1130 |
@tab The shell lists this routine as unresolved. |
@tab An otherwise unkown routine the shell lists as unresolved |
1131 |
|
(referenced, but not compiled). |
1132 |
@end multitable |
@end multitable |
1133 |
|
|
1134 |
You can define additional categories based on the file name and path |
You can create additional categories based on the routine's filepath |
1135 |
with the variable @code{idlwave-special-lib-alist}. |
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. |
1138 |
|
|
1139 |
@cindex Flags, in routine info |
@cindex Flags, in routine info |
1140 |
@cindex Duplicate routines |
@cindex Duplicate routines |
1141 |
@cindex Multiply defined routines |
@cindex Multiply defined routines |
1142 |
@cindex Routine definitions, multiple |
@cindex Routine definitions, multiple |
1143 |
The flags @code{[CSB]} indicate if the file is known to IDLWAVE from the |
The flags @code{[CSB]} indicate the source of the information IDLWAVE |
1144 |
library catalog (@w{@code{[C--]}}, @pxref{Library Catalog}), from the Shell |
has regarding the file: from a library catalog (@w{@code{[C--]}}, |
1145 |
(@w{@code{[-S-]}}) or from an Emacs buffer (@w{@code{[--B]}}). |
@pxref{Library Catalog}), from the IDL Shell (@w{@code{[-S-]}}) or from |
1146 |
Combinations are possible. If a file contains multiple definitions of |
an Emacs buffer (@w{@code{[--B]}}). Combinations are possible (a |
1147 |
the same routine, the file name will be prefixed with @samp{(Nx)} where |
compiled library routine visited in a buffer might read |
1148 |
@samp{N} is the number of definitions. |
@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. |
1151 |
|
|
1152 |
@cindex Online Help from the routine info buffer |
@cindex Online Help from the routine info buffer |
1153 |
@cindex Active text, in routine info |
@cindex Active text, in routine info |
1154 |
@cindex Inserting keywords, from routine info |
@cindex Inserting keywords, from routine info |
1155 |
@cindex Source file, access from routine info |
@cindex Source file, access from routine info |
1156 |
Some of the text in the @file{*Help*} buffer will be active (it |
Some of the text in the @file{*Help*} routine info buffer will be active |
1157 |
highlights when you move the mouse over it). Clicking on these items |
(it is highlighted when the mouse moves over it). Typically, clicking |
1158 |
will have the following effects: |
with the right mouse button invokes online help lookup, and clicking |
1159 |
|
with the middle mouse button inserts keywords or visits files: |
1160 |
|
|
1161 |
@multitable @columnfractions 0.15 0.85 |
@multitable @columnfractions 0.15 0.85 |
1162 |
@item @i{Usage} |
@item @i{Usage} |
1163 |
@tab If online help is installed, a click with the @emph{right} mouse |
@tab If online help is installed, a click with the @emph{right} mouse |
1164 |
button on the @i{Usage:} line will access the help for the |
button on the @i{Usage:} line will access the help for the |
1165 |
routine (@pxref{Online Help}). |
routine (@pxref{Online Help}). |
1166 |
@item @i{Keyword} |
@item @i{Keyword} |
1167 |
@tab Online help about keywords is also available with the |
@tab Online help about keywords is also available with the |
1168 |
@emph{right} mouse button. Clicking on a keyword with the @emph{middle} |
@emph{right} mouse button. Clicking on a keyword with the @emph{middle} |
1180 |
@tab The @i{Classes} line is only included in the routine info window if |
@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 |
the current class inherits from other classes. You can click with the |
1182 |
@emph{middle} mouse button to display routine info about the current |
@emph{middle} mouse button to display routine info about the current |
1183 |
method in other classes on the inheritance chain. |
method in other classes on the inheritance chain, if such a method |
1184 |
|
exists there. |
1185 |
@end multitable |
@end multitable |
1186 |
|
|
1187 |
@defopt idlwave-resize-routine-help-window (@code{t}) |
@defopt idlwave-resize-routine-help-window (@code{t}) |
1188 |
Non-@code{nil} means, resize the Routine-info @file{*Help*} window to |
Non-@code{nil} means resize the Routine-info @file{*Help*} window to |
1189 |
fit the content. |
fit the content. |
1190 |
@end defopt |
@end defopt |
1191 |
|
|
1197 |
Maximum number of source files displayed in the Routine Info window. |
Maximum number of source files displayed in the Routine Info window. |
1198 |
@end defopt |
@end defopt |
1199 |
|
|
|
@page |
|
1200 |
|
|
1201 |
@node Online Help, Completion, Routine Info, The IDLWAVE Major Mode |
@node Online Help, Completion, Routine Info, The IDLWAVE Major Mode |
1202 |
@section Online Help |
@section Online Help |
1211 |
For IDL system routines, RSI provides extensive documentation. IDLWAVE |
For IDL system routines, RSI provides extensive documentation. IDLWAVE |
1212 |
can access an ASCII version of this documentation very quickly and |
can access an ASCII version of this documentation very quickly and |
1213 |
accurately. This is @emph{much} faster than using the IDL online help |
accurately. This is @emph{much} faster than using the IDL online help |
1214 |
application, also because usually IDLWAVE gets you to the right place in |
application, because IDLWAVE usually gets you to the right place in the |
1215 |
the docs directly, without additional browsing and scrolling. For this |
documentation directly, without any additional browsing and scrolling. |
1216 |
online help to work, you need an ASCII version of the IDL documentation |
For this online help to work, an ASCII version of the IDL documentation, |
1217 |
which is not part of the standard IDLWAVE distribution. The required |
which is not part of the standalone IDLWAVE distribution, is required. |
1218 |
files can be downloaded from @uref{@value{IDLWAVE-HOMEPAGE}, the |
The necessary help files can be downloaded from |
1219 |
maintainers webpage}. As the text is extracted from PDF files, the |
@uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. The text |
1220 |
formatting of the help text is good for normal text, but graphics and |
extracted from the PDF files is fine for normal documentation |
1221 |
multiline equations will not be well represented. See also |
paragraphs, but graphics and multiline equations will not be well |
1222 |
@ref{Documentation Scan}. |
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. |
1232 |
|
|
1233 |
@cindex Source code, as online help |
@cindex Source code, as online help |
1234 |
@cindex DocLib header, as online help |
@cindex DocLib header, as online help |
1235 |
For routines which are not documented in the IDL manual (for example |
For routines which are not documented in the IDL manual (for example |
1236 |
your own routines), the source code is used as help text. If the |
personal or library routines), the source code itself is used as help |
1237 |
requested information can be found in a (more or less) standard DocLib |
text. If the requested information can be found in a (more or less) |
1238 |
file header, IDLWAVE shows the header. Otherwise the routine definition |
standard DocLib file header, IDLWAVE shows the header (scrolling down to |
1239 |
statement (@code{pro}/@code{function}) is shown. |
appropriate keyword). Otherwise the routine definition statement |
1240 |
|
(@code{pro}/@code{function}) is shown. |
1241 |
|
|
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 |
|
|
1250 |
@kindex M-? |
@kindex M-? |
1251 |
In any IDL program, press @kbd{M-?} (@code{idlwave-context-help}) or |
In any IDL program (or, as with most IDLWAVE commands, in the IDL |
1252 |
click with @kbd{S-Mouse-3} to access context sensitive online help. The |
Shell), press @kbd{M-?} (@code{idlwave-context-help}), or click with |
1253 |
following locations are recognized as context: |
@kbd{S-Mouse-3} to access context sensitive online help. The following |
1254 |
|
locations are recognized context for help: |
1255 |
|
|
1256 |
@cindex Context, for online help |
@cindex Context, for online help |
1257 |
@multitable @columnfractions .25 .75 |
@multitable @columnfractions .25 .75 |
1258 |
@item @i{Routine name} |
@item @i{Routine name} |
1259 |
@tab The name of a routine (function, procedure, method). |
@tab The name of a routine (function, procedure, method). |
1260 |
@item @i{Keyword Parameter} |
@item @i{Keyword Parameter} |
1261 |
@tab Keyword parameter of a routine. |
@tab A keyword parameter of a routine. |
1262 |
@item @i{System Variable} |
@item @i{System Variable} |
1263 |
@tab System variable like @code{!DPI}. |
@tab System variables like @code{!DPI}. |
1264 |
@item @i{IDL Statement} |
@item @i{IDL Statement} |
1265 |
@tab Like @code{PRO}, @code{REPEAT}, or @code{COMPILE_OPT}. |
@tab Statements like @code{PRO}, @code{REPEAT}, @code{COMPILE_OPT}, etc. |
1266 |
@item @i{Class name} |
@item @i{Class name} |
1267 |
@tab Class name in @code{OBJ_NEW} call. |
@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. |
1270 |
@item @i{Executive Command} |
@item @i{Executive Command} |
1271 |
@tab Executive command like @code{.RUN}. Mostly useful in the shell. |
@tab An executive command like @code{.RUN}. Mostly useful in the shell. |
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}. |
1276 |
@item @i{Default} |
@item @i{Default} |
1277 |
@tab The routine that would be selected for routine info display. |
@tab The routine that would be selected for routine info display. |
1278 |
@end multitable |
@end multitable |
1295 |
Routine Info display. Click with @kbd{Mouse-3} on an item to see the |
Routine Info display. Click with @kbd{Mouse-3} on an item to see the |
1296 |
corresponding help (@pxref{Routine Info}). |
corresponding help (@pxref{Routine Info}). |
1297 |
@item |
@item |
1298 |
When using completion and Emacs pops up a window with possible |
When using completion and Emacs pops up a @file{*Completions*} buffer |
1299 |
completions, clicking with @kbd{Mouse-3} on a completion item invokes |
with possible completions, clicking with @kbd{Mouse-3} on a completion |
1300 |
help on that item (@pxref{Completion}). |
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). |
1303 |
@end itemize |
@end itemize |
1304 |
@noindent |
@noindent |
1305 |
In both cases, a blue face indicates that the item is documented in the |
In both cases, a blue face indicates that the item is documented in the |
1306 |
IDL manual. |
IDL manual, but an attempt will be made to visit non-blue items directly |
1307 |
|
in the originating source file. |
|
@page |
|
1308 |
|
|
1309 |
@cindex Help application, key bindings |
@cindex Help application, key bindings |
1310 |
@cindex Key bindings, in help application |
@cindex Key bindings, in help application |
1311 |
The help window is normally displayed in a separate frame. The |
The help window is normally displayed in a separate frame. The |
1312 |
following commands can be used to navigate inside the help system. |
following commands can be used to navigate inside the help system: |
1313 |
|
|
1314 |
@multitable @columnfractions .15 .85 |
@multitable @columnfractions .15 .85 |
1315 |
@item @kbd{@key{SPACE}} |
@item @kbd{@key{SPACE}} |
1338 |
|
|
1339 |
@sp 1 |
@sp 1 |
1340 |
@noindent When the help text is a source file, the following commands |
@noindent When the help text is a source file, the following commands |
1341 |
are also available. |
are also available: |
1342 |
|
|
1343 |
@multitable @columnfractions .15 .85 |
@multitable @columnfractions .15 .85 |
1344 |
@item @kbd{h} |
@item @kbd{h} |
1345 |
@tab Jump to DocLib Header of the routine whose source is displayed |
@tab Jump to DocLib Header of the routine whose source is displayed |
1359 |
@end defopt |
@end defopt |
1360 |
|
|
1361 |
@defopt idlwave-help-use-dedicated-frame (@code{t}) |
@defopt idlwave-help-use-dedicated-frame (@code{t}) |
1362 |
Non-nil means, use a separate frame for Online Help if possible. |
Non-@code{nil} means use a separate frame for Online Help if possible. |
1363 |
@end defopt |
@end defopt |
1364 |
|
|
1365 |
@defopt idlwave-help-frame-parameters |
@defopt idlwave-help-frame-parameters |
1375 |
@end defopt |
@end defopt |
1376 |
|
|
1377 |
@defopt idlwave-help-fontify-source-code (@code{nil}) |
@defopt idlwave-help-fontify-source-code (@code{nil}) |
1378 |
Non-nil means, fontify source code displayed as help. |
Non-@code{nil} means fontify source code displayed as help. |
1379 |
@end defopt |
@end defopt |
1380 |
|
|
1381 |
@defopt idlwave-help-source-try-header (@code{t}) |
@defopt idlwave-help-source-try-header (@code{t}) |
1382 |
Non-nil means, try to find help in routine header when displaying source |
Non-@code{nil} means try to find help in routine header when displaying source |
1383 |
file. |
file. |
1384 |
@end defopt |
@end defopt |
1385 |
|
|
1386 |
@defopt idlwave-help-link-face |
@defopt idlwave-help-link-face |
1387 |
The face for links to IDLWAVE online help. |
The face for links in IDLWAVE online help. |
1388 |
@end defopt |
@end defopt |
1389 |
|
|
1390 |
@defopt idlwave-help-activate-links-agressively (@code{t}) |
@defopt idlwave-help-activate-links-aggressively (@code{t}) |
1391 |
Non-@code{nil} means, make all possible links in help window active. |
Non-@code{nil} means make all possible links in help window active. |
1392 |
@end defopt |
@end defopt |
1393 |
|
|
1394 |
@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode |
@node Completion, Routine Source, Online Help, The IDLWAVE Major Mode |
1403 |
|
|
1404 |
@kindex M-@key{TAB} |
@kindex M-@key{TAB} |
1405 |
@kindex C-c C-i |
@kindex C-c C-i |
1406 |
IDLWAVE offers completion for class names, routine names and keywords. |
IDLWAVE offers completion for class names, routine names, keywords, |
1407 |
As in many programming modes, completion is bound to @kbd{M-@key{TAB}}. |
system variables, class structure tags, regular structure tags and file |
1408 |
Completion uses the same internal information as routine info, so when |
names. As in many programming modes, completion is bound to |
1409 |
necessary it can be updated with @kbd{C-c C-i} |
@kbd{M-@key{TAB}} (or @kbd{@key{TAB}} in the IDLWAVE Shell --- |
1410 |
(@code{idlwave-update-routine-info}). |
@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}). |
1413 |
|
|
1414 |
The completion function is context sensitive and figures out what to |
The completion function is context sensitive and figures out what to |
1415 |
complete at point. Here are example lines and what @kbd{M-@key{TAB}} |
complete based location of the point. Here are example lines and what |
1416 |
would try to complete when the cursor is on the position marked with a |
@kbd{M-@key{TAB}} would try to complete when the cursor is on the |
1417 |
@samp{*}. |
position marked with a @samp{_}: |
1418 |
|
|
1419 |
@example |
@example |
1420 |
plo* @r{Procedure} |
plo_ @r{Procedure} |
1421 |
x = a* @r{Function} |
x = a_ @r{Function} |
1422 |
plot,xra* @r{Keyword of @code{plot} procedure} |
plot,xra_ @r{Keyword of @code{plot} procedure} |
1423 |
plot,x,y,/x* @r{Keyword of @code{plot} procedure} |
plot,x,y,/x_ @r{Keyword of @code{plot} procedure} |
1424 |
plot,min(* @r{Keyword of @code{min} function} |
plot,min(_ @r{Keyword of @code{min} function} |
1425 |
obj -> a* @r{Object method (procedure)} |
obj -> a_ @r{Object method (procedure)} |
1426 |
a(2,3) = obj -> a* @r{Object method (function)} |
a(2,3) = obj -> a_ @r{Object method (function)} |
1427 |
x = obj_new('IDL* @r{Class name} |
x = obj_new('IDL_ @r{Class name} |
1428 |
x = obj_new('MyCl',a* @r{Keyword to @code{Init} method in class @code{MyCl}} |
x = obj_new('MyCl',a_ @r{Keyword to @code{Init} method in class @code{MyCl}} |
1429 |
pro A* @r{Class name} |
pro A_ @r{Class name} |
1430 |
pro * @r{Fill in @code{Class::} of first method in this file} |
pro _ @r{Fill in @code{Class::} of first method in this file} |
1431 |
!v* @r{System variable} |
!v_ @r{System variable} |
1432 |
!version.t* @r{Structure tag of system variable} |
!version.t_ @r{Structure tag of system variable} |
1433 |
self.g* @r{Class structure tag in methods} |
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)} |
1436 |
@end example |
@end example |
1437 |
|
|
1438 |
|
@cindex Completion, ambiguity |
1439 |
|
@cindex Completion, forcing function name |
1440 |
|
The only place where completion is ambiguous is procedure/function |
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}}. |
1445 |
|
|
1446 |
@cindex Scrolling the @file{*Completions*} window |
@cindex Scrolling the @file{*Completions*} window |
1447 |
@cindex Completion, scrolling |
@cindex Completion, scrolling |
1448 |
@cindex Completion, Online Help |
@cindex Completion, Online Help |
1452 |
@kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each |
@kbd{M-@key{TAB}} repeatedly. Online help (if installed) for each |
1453 |
possible completion is available by clicking with @kbd{Mouse-3} on the |
possible completion is available by clicking with @kbd{Mouse-3} on the |
1454 |
item. Items for which system online help (from the IDL manual) is |
item. Items for which system online help (from the IDL manual) is |
1455 |
available will be displayed in a different font. For other items, the |
available will be emphasized (e.g. colored blue). For other items, the |
1456 |
corresponding source code or DocLib header is available as help text. |
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. |
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 |
1483 |
|
|
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? |
1492 |
|
* Object Method Completion in the Shell:: |
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 |
1499 |
@cindex Case of completed words |
@cindex Case of completed words |
1500 |
@cindex Mixed case completion |
@cindex Mixed case completion |
1501 |
The case of the completed words is determined by what is already in the |
The case of the completed words is determined by what is already in the |
1505 |
The default is to use upper case for procedures, functions and keywords, |
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 |
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 |
conventions in the IDL manuals. These defaults can be changed with the |
1508 |
variable @code{idlwave-completion-case}. |
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}. |
1514 |
|
|
1515 |
@defopt idlwave-completion-case |
@defopt idlwave-completion-case |
1516 |
Association list setting the case (UPPER/lower/Capitalized/...) of completed |
Association list setting the case (UPPER/lower/Capitalized/MixedCase...) |
1517 |
words. |
of completed words. |
1518 |
@end defopt |
@end defopt |
1519 |
|
|
1520 |
@defopt idlwave-completion-force-default-case (@code{nil}) |
@defopt idlwave-completion-force-default-case (@code{nil}) |
1521 |
Non-@code{nil} means, completion will always honor the settings in |
Non-@code{nil} means completion will always honor the settings in |
1522 |
@code{idlwave-completion-case}. When nil (the default), lower case |
@code{idlwave-completion-case}. When nil (the default), entirely lower |
1523 |
strings will be completed to lower case. |
case strings will always be completed to lower case, no matter what the |
1524 |
|
settings in @code{idlwave-completion-case}. |
1525 |
@end defopt |
@end defopt |
1526 |
|
|
1527 |
@defopt idlwave-complete-empty-string-as-lower-case (@code{nil}) |
@defopt idlwave-complete-empty-string-as-lower-case (@code{nil}) |
1528 |
Non-@code{nil} means, the empty string is considered lower case for |
Non-@code{nil} means the empty string is considered lower case for |
|
completion. |
|
|
@end defopt |
|
|
|
|
|
@defopt idlwave-keyword-completion-adds-equal (@code{t}) |
|
|
Non-@code{nil} means, completion automatically adds @samp{=} after |
|
|
completed keywords. |
|
|
@end defopt |
|
|
|
|
|
@defopt idlwave-function-completion-adds-paren (@code{t}) |
|
|
Non-@code{nil} means, completion automatically adds @samp{(} after |
|
|
completed function. A value of `2' means, also add the closing |
|
|
parenthesis and position cursor between the two. |
|
|
@end defopt |
|
|
|
|
|
@defopt idlwave-completion-restore-window-configuration (@code{t}) |
|
|
Non-@code{nil} means, restore window configuration after successful |
|
1529 |
completion. |
completion. |
1530 |
@end defopt |
@end defopt |
1531 |
|
|
1532 |
@defopt idlwave-highlight-help-links-in-completion (@code{t}) |
@node Object Method Completion and Class Ambiguity, Object Method Completion in the Shell, Case of Completed Words, Completion |
1533 |
Non-nil means, highlight completions for which system help is available. |
@subsection Object Method Completion and Class Ambiguity |
|
@end defopt |
|
|
|
|
|
@subsubheading Object Method Completion and Class Ambiguity |
|
1534 |
@cindex Object methods |
@cindex Object methods |
1535 |
@cindex Class ambiguity |
@cindex Class ambiguity |
1536 |
@cindex @code{self} object, default class |
@cindex @code{self} object, default class |
1537 |
An object method is not uniquely determined without the object's class. |
An object method is not uniquely determined without the object's class. |
1538 |
Since the class part is usually omitted in the source code, IDLWAVE |
Since the class is almost always omitted in the calling source, IDLWAVE |
1539 |
considers all available methods in all classes as possible completions |
considers all available methods in all classes as possible method name |
1540 |
of an object method name. For keywords, the combined keywords of the |
completions. The combined list of keywords of the current method in |
1541 |
current method in all available classes will be considered. In the |
@emph{all} known classes which contain that method will be considered |
1542 |
@file{*Completions*} buffer, the classes allowed for each completion |
for keyword completion. In the @file{*Completions*} buffer, the |
1543 |
will be shown next to the item (see option |
matching classes will be shown next to each item (see option |
1544 |
@code{idlwave-completion-show-classes}). As a special case, the class |
@code{idlwave-completion-show-classes}). As a special case, the class |
1545 |
of an object called @samp{self} object is always the class of the |
of an object called @samp{self} is always taken to be the class of the |
1546 |
current routine. All classes it inherits from are considered as well |
current routine. All classes it inherits from are considered as well |
1547 |
where appropriate. |
where appropriate. |
1548 |
|
|
1551 |
You can also call @code{idlwave-complete} with a prefix arg: @kbd{C-u |
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 |
M-@key{TAB}}. IDLWAVE will then prompt you for the class in order to |
1553 |
narrow down the number of possible completions. The variable |
narrow down the number of possible completions. The variable |
1554 |
@code{idlwave-query-class} can be configured to make this behavior the |
@code{idlwave-query-class} can be configured to make such prompting the |
1555 |
default (not recommended). After you have specified the class |
default for all methods (not recommended), or selectively for very |
1556 |
for a particular statement (e.g. when completing the method), IDLWAVE |
common methods for which the number of completing keywords would be too |
1557 |
can remember it for the rest of the editing session. Subsequent |
large (e.g. @code{Init}). |
1558 |
completions in the same statement (e.g. keywords) can then reuse this |
|
1559 |
class information. Remembering the class works by placing a text |
@cindex Saving object class on @code{->} |
1560 |
property in the object operator @samp{->}. This is not enabled by |
@cindex @code{->} |
1561 |
default - the variable @code{idlwave-store-inquired-class} can be used |
After you have specified the class for a particular statement (e.g. when |
1562 |
to turn it on. |
completing the method), IDLWAVE can remember it for the rest of the |
1563 |
|
editing session. Subsequent completions in the same statement |
1564 |
@defopt idlwave-support-inheritance (@code{t}) |
(e.g. keywords) can then reuse this class information. This works by |
1565 |
Non-@code{nil} means, treat inheritance with completion, online help etc. |
placing a text property on the method invocation operator @samp{->}, |
1566 |
@end defopt |
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. |
1569 |
|
|
1570 |
@defopt idlwave-completion-show-classes (@code{1}) |
@defopt idlwave-completion-show-classes (@code{1}) |
1571 |
Non-@code{nil} means, show classes in @file{*Completions*} buffer when |
Non-@code{nil} means show classes in @file{*Completions*} buffer when |
1572 |
completing object methods and keywords. |
completing object methods and keywords. |
1573 |
@end defopt |
@end defopt |
1574 |
|
|
1575 |
@defopt idlwave-completion-fontify-classes (@code{t}) |
@defopt idlwave-completion-fontify-classes (@code{t}) |
1576 |
Non-@code{nil} means, fontify the classes in completions buffer. |
Non-@code{nil} means fontify the classes in completions buffer. |
1577 |
@end defopt |
@end defopt |
1578 |
|
|
1579 |
@defopt idlwave-query-class (@code{nil}) |
@defopt idlwave-query-class (@code{nil}) |
1581 |
@end defopt |
@end defopt |
1582 |
|
|
1583 |
@defopt idlwave-store-inquired-class (@code{nil}) |
@defopt idlwave-store-inquired-class (@code{nil}) |
1584 |
Non-@code{nil} means, store class of a method call as text property on |
Non-@code{nil} means store class of a method call as text property on |
1585 |
@samp{->}. |
@samp{->}. |
1586 |
@end defopt |
@end defopt |
1587 |
|
|
1590 |
text property. |
text property. |
1591 |
@end defopt |
@end defopt |
1592 |
|
|
1593 |
@node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode |
@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 |
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 |
|
|
1633 |
|
IDLWAVE can accommodate this special synergy between class and keyword |
1634 |
|
inheritance: if @code{_EXTRA} or @code{_REF_EXTRA} is detected among a |
1635 |
|
method's keyword parameters, all keywords of superclass versions of the |
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. |
1644 |
|
|
1645 |
|
@defopt idlwave-support-inheritance (@code{t}) |
1646 |
|
Non-@code{nil} means consider inheritance during completion, online help etc. |
1647 |
|
@end defopt |
1648 |
|
|
1649 |
|
@defopt idlwave-keyword-class-inheritance |
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 |
1653 |
|
|
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, |
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 |
1665 |
|
completion module: @file{idlw-complete-structtag.el}. Tag completion in |
1666 |
|
structures is highly ambiguous (much more so than @samp{self} |
1667 |
|
completion), so @code{idlw-complete-structtag} makes an unusual and very |
1668 |
|
specific assumption: the exact same variable name is used to refer to |
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 |
1671 |
|
refer to the same structure with the same variable name |
1672 |
|
(e.g. @samp{state}), structure tags which are read from its definition |
1673 |
|
in the same file can be used for completion. |
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 |
1679 |
|
(add-hook 'idlwave-load-hook |
1680 |
|
(lambda () (require 'idlw-complete-structtag))) |
1681 |
|
@end lisp |
1682 |
|
|
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 |
|
|
1686 |
|
@node Routine Source, Resolving Routines, Completion, The IDLWAVE Major Mode |
1687 |
@section Routine Source |
@section Routine Source |
1688 |
@cindex Routine source file |
@cindex Routine source file |
1689 |
@cindex Module source file |
@cindex Module source file |
1690 |
@cindex Source file, of a routine |
@cindex Source file, of a routine |
1691 |
@kindex C-c C-v |
@kindex C-c C-v |
1692 |
Apart from clicking on a @i{Source:} line in the routine info window, |
In addition to clicking on a @i{Source:} line in the routine info |
1693 |
there is also another way to find the source file of a routine. The |
window, there is another way to quickly visit the source file of a |
1694 |
command @kbd{C-c C-v} (@code{idlwave-find-module}) asks for a module |
routine. The command @kbd{C-c C-v} (@code{idlwave-find-module}) asks |
1695 |
name, offering the same default as @code{idlwave-routine-info} would |
for a module name, offering the same default as |
1696 |
have used. In the minibuffer, specify a complete routine name |
@code{idlwave-routine-info} would have used, taken from nearby buffer |
1697 |
(including the class part). IDLWAVE will display the source file in |
contents. In the minibuffer, specify a complete routine name (including |
1698 |
another window. |
any class part). IDLWAVE will display the source file in another |
1699 |
|
window, positioned at the routine in question. |
1700 |
|
|
1701 |
@cindex Buffers, killing |
@cindex Buffers, killing |
1702 |
@cindex Killing autoloaded buffers |
@cindex Killing autoloaded buffers |
1703 |
Since getting the source of a routine into a buffer is so easy with |
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 |
IDLWAVE, too many buffers visiting different IDL source files are |
1705 |
sometimes created. The special command @kbd{C-c C-k} |
sometimes created. The special command @kbd{C-c C-k} |
1706 |
(@code{idlwave-kill-autoloaded-buffers}) can be used to remove these |
(@code{idlwave-kill-autoloaded-buffers}) can be used to easily remove |
1707 |
buffers. |
these buffers. |
1708 |
|
|
1709 |
@node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode |
@node Resolving Routines, Code Templates, Routine Source, The IDLWAVE Major Mode |
1710 |
@section Resolving Routines |
@section Resolving Routines |
1723 |
library modules will then be available without the need to compile the |
library modules will then be available without the need to compile the |
1724 |
modules first, and even without a running shell. |
modules first, and even without a running shell. |
1725 |
|
|
1726 |
@xref{Sources of Routine Info}, for in-depth information where IDLWAVE |
@xref{Sources of Routine Info}, for more information on the ways IDLWAVE |
1727 |
collects data about routines, and how to update this information. |
collects data about routines, and how to update this information. |
1728 |
|
|
1729 |
|
@node Code Templates, Abbreviations, Resolving Routines, The IDLWAVE Major Mode |
|
@node Code Templates, Actions, Resolving Routines, The IDLWAVE Major Mode |
|
1730 |
@section Code Templates |
@section Code Templates |
1731 |
@cindex Code templates |
@cindex Code templates |
|
@cindex Abbreviations |
|
1732 |
@cindex Templates |
@cindex Templates |
1733 |
|
|
1734 |
IDLWAVE can insert IDL code templates into the buffer. For a few |
IDLWAVE can insert IDL code templates into the buffer. For a few |
1745 |
@tab @code{WHILE} loop template |
@tab @code{WHILE} loop template |
1746 |
@end multitable |
@end multitable |
1747 |
|
|
1748 |
Otherwise, special abbreviations are used. Emacs abbreviations are |
All code templates are also available as abbreviations |
1749 |
expanded by typing text into the buffer and pressing @key{SPC} or |
(@pxref{Abbreviations}). |
1750 |
@key{RET}. The special abbreviations used to insert code templates all |
|
1751 |
start with a @samp{\} (the backslash). Here are a few examples of |
@node Abbreviations, Actions, Code Templates, The IDLWAVE Major Mode |
1752 |
predefined abbreviations. For a full list, use @kbd{M-x |
@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 |
1767 |
idlwave-list-abbrevs}. |
idlwave-list-abbrevs}. |
1768 |
|
|
1769 |
|
Template abbreviations: |
1770 |
|
|
1771 |
@multitable @columnfractions .15 .85 |
@multitable @columnfractions .15 .85 |
1772 |
@item @code{\pr} |
@item @code{\pr} |
1773 |
@tab @code{PROCEDURE} template |
@tab @code{PROCEDURE} template |
1785 |
@tab @code{IF} statement template |
@tab @code{IF} statement template |
1786 |
@item @code{\elif} |
@item @code{\elif} |
1787 |
@tab @code{IF-ELSE} statement template |
@tab @code{IF-ELSE} statement template |
1788 |
|
@end multitable |
1789 |
|
|
1790 |
|
String abbreviations: |
1791 |
|
|
1792 |
|
@multitable @columnfractions .15 .85 |
1793 |
|
@item @code{\ap} |
1794 |
|
@tab @code{arg_present()} |
1795 |
@item @code{\b} |
@item @code{\b} |
1796 |
@tab @code{BEGIN} |
@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,} |
1899 |
@end multitable |
@end multitable |
1900 |
|
|
1901 |
The templates are expanded in upper or lower case, depending upon the |
@noindent You can easily add your own abbreviations or override existing |
1902 |
variables @code{idlwave-abbrev-change-case} and |
abbrevs with @code{define-abbrev} in your mode hook, using the |
1903 |
@code{idlwave-reserved-word-upcase}. |
convenience function @code{idlwave-define-abbrev}: |
1904 |
|
|
1905 |
|
@lisp |
1906 |
|
(add-hook 'idlwave-mode-hook |
1907 |
|
(lambda () |
1908 |
|
(idlwave-define-abbrev "wb" "widget_base()" |
1909 |
|
(idlwave-keyword-abbrev 1)) |
1910 |
|
(idlwave-define-abbrev "ine" "IF N_Elements() EQ 0 THEN" |
1911 |
|
(idlwave-keyword-abbrev 11)))) |
1912 |
|
@end lisp |
1913 |
|
|
1914 |
|
Notice how the abbreviation (here @emph{wb}) and its expansion |
1915 |
|
(@emph{widget_base()}) are given as arguments, and the single argument to |
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 |
1921 |
|
the variables @code{idlwave-abbrev-change-case} and, for reserved word |
1922 |
|
templates, @code{idlwave-reserved-word-upcase} (@pxref{Case Changes}). |
1923 |
|
|
1924 |
@defopt idlwave-abbrev-start-char (@code{"\"}) |
@defopt idlwave-abbrev-start-char (@code{"\"}) |
1925 |
A single character string used to start abbreviations in abbrev |
A single character string used to start abbreviations in abbrev mode. |
1926 |
mode. |
Beware of common characters which might naturally occur in sequence with |
1927 |
|
abbreviation strings. |
1928 |
@end defopt |
@end defopt |
1929 |
|
|
1930 |
@defopt idlwave-abbrev-move (@code{t}) |
@defopt idlwave-abbrev-move (@code{t}) |
1931 |
Non-@code{nil} means the abbrev hook can move point, e.g. to end up |
Non-@code{nil} means the abbrev hook can move point, e.g. to end up |
1932 |
between the parenthesis of a function call. |
between the parentheses of a function call. |
1933 |
@end defopt |
@end defopt |
1934 |
|
|
1935 |
@node Actions, Doc Header, Code Templates, The IDLWAVE Major Mode |
@node Actions, Doc Header, Abbreviations, The IDLWAVE Major Mode |
1936 |
@section Actions |
@section Actions |
1937 |
@cindex Actions |
@cindex Actions |
1938 |
@cindex Coding standards, enforcing |
@cindex Coding standards, enforcing |
1939 |
|
|
1940 |
@emph{Actions} are special commands which are executed automatically |
@emph{Actions} are special formatting commands which are executed |
1941 |
while you write code in order to check the structure of the program or |
automatically while you write code in order to check the structure of |
1942 |
to enforce coding standards. Most actions which have been implemented |
the program or to enforce coding standards. Most actions which have |
1943 |
in IDLWAVE are turned off by default, assuming that the average user |
been implemented in IDLWAVE are turned off by default, assuming that the |
1944 |
wants her code the way she writes it. But if you are a lazy typist and |
average user wants her code the way she writes it. But if you are a |
1945 |
want your code to adhere to certain standards, they can be |
lazy typist and want your code to adhere to certain standards, actions |
1946 |
helpful. |
can be helpful. |
1947 |
|
|
1948 |
Action can be applied in three ways: |
Actions can be applied in three ways: |
1949 |
|
|
1950 |
@itemize @bullet |
@itemize @bullet |
1951 |
@item |
@item |
1961 |
@item |
@item |
1962 |
@cindex Foreign code, adapting |
@cindex Foreign code, adapting |
1963 |
@cindex Actions, applied to foreign code |
@cindex Actions, applied to foreign code |
1964 |
Action can also be applied to a larger piece of code, e.g. in order to |
Actions can also be applied to a larger piece of code, e.g. to convert |
1965 |
convert foreign code to your own style. To do this, mark the relevant |
foreign code to your own style. To do this, mark the relevant part of |
1966 |
part of the code and execute @kbd{M-x expand-region-abbrevs}. Useful |
the code and execute @kbd{M-x expand-region-abbrevs}. Useful marking |
1967 |
marking commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the |
commands are @kbd{C-x h} (the entire file) or @kbd{C-M-h} (the current |
1968 |
current subprogram). @xref{Code Indentation}, for information how to |
subprogram). @xref{Code Indentation}, for information how to adjust the |
1969 |
adjust the indentation of the code. |
indentation of the code. |
1970 |
@end itemize |
@end itemize |
1971 |
|
|
1972 |
@defopt idlwave-do-actions (@code{nil}) |
@defopt idlwave-do-actions (@code{nil}) |
1974 |
@end defopt |
@end defopt |
1975 |
|
|
1976 |
@menu |
@menu |
1977 |
* Block Boundary Check:: Is the END correct |
* Block Boundary Check:: Is the END statement correct? |
1978 |
* Padding Operators:: Enforcing space around `=' etc |
* Padding Operators:: Enforcing space around `=' etc |
1979 |
* Case Changes:: Enforcing upper case keywords |
* Case Changes:: Enforcing upper case keywords |
1980 |
@end menu |
@end menu |
1991 |
Whenever you type an @code{END} statement, IDLWAVE finds the |
Whenever you type an @code{END} statement, IDLWAVE finds the |
1992 |
corresponding start of the block and the cursor blinks back to that |
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 |
location for a second. If you have typed a specific @code{END}, like |
1994 |
@code{ENDIF} or @code{ENDCASE}, you get a warning if that kind of END |
@code{ENDIF} or @code{ENDCASE}, you get a warning if that terminator |
1995 |
does not match the type of block it terminates. |
does not match the type of block it terminates. |
1996 |
|
|
1997 |
Set the variable @code{idlwave-expand-generic-end} in order to have all |
Set the variable @code{idlwave-expand-generic-end} in order to have all |
1998 |
generic @code{END} statements automatically expanded to a specific type. |
generic @code{END} statements automatically expanded to the appropriate |
1999 |
You can also type @kbd{C-c ]} to close the current block by inserting |
type. You can also type @kbd{C-c ]} to close the current block by |
2000 |
the appropriate @code{END} statement. |
inserting the appropriate @code{END} statement. |
2001 |
|
|
2002 |
@defopt idlwave-show-block (@code{t}) |
@defopt idlwave-show-block (@code{t}) |
2003 |
Non-@code{nil} means point blinks to block beginning for |
Non-@code{nil} means point blinks to block beginning for |
2009 |
@end defopt |
@end defopt |
2010 |
|
|
2011 |
@defopt idlwave-reindent-end (@code{t}) |
@defopt idlwave-reindent-end (@code{t}) |
2012 |
Non-nil means re-indent line after END was typed. |
Non-@code{nil} means re-indent line after END was typed. |
2013 |
@end defopt |
@end defopt |
2014 |
|
|
2015 |
@node Padding Operators, Case Changes, Block Boundary Check, Actions |
@node Padding Operators, Case Changes, Block Boundary Check, Actions |
2019 |
@cindex Space, around operators |
@cindex Space, around operators |
2020 |
|
|
2021 |
Some operators can be automatically surrounded by spaces. This can |
Some operators can be automatically surrounded by spaces. This can |
2022 |
happen when the operator is typed, or also later when the line is |
happen when the operator is typed, or later when the line is indented. |
2023 |
indented. IDLWAVE contains this setting for the operators @samp{&}, |
IDLWAVE can pad the operators @samp{&}, @samp{<}, @samp{>}, @samp{,}, |
2024 |
@samp{<}, @samp{>}, @samp{,}, @samp{=}, and @samp{->}@footnote{Operators |
@samp{=}, and @samp{->}, but this feature is turned off by default. If |
2025 |
longer than one character can only be padded during line indentation.}, |
you want to turn it on, customize the variables |
2026 |
but the feature is turned off by default. If you want to turn it on, |
@code{idlwave-surround-by-blank} and @code{idlwave-do-actions}. You can |
2027 |
customize the variables @code{idlwave-surround-by-blank} and |
also define similar actions for other operators by using the function |
2028 |
@code{idlwave-do-actions}. You can also define similar actions for |
@code{idlwave-action-and-binding} in the mode hook. For example, to |
2029 |
other operators by using the function @code{idlwave-action-and-binding} |
enforce space padding of the @samp{+} and @samp{*} operators, try this |
2030 |
in the mode hook. For example, to enforce space padding of the @samp{+} |
in @file{.emacs} |
|
and @samp{*} operators, try this in @file{.emacs} |
|
2031 |
|
|
2032 |
@lisp |
@lisp |
2033 |
(add-hook 'idlwave-mode-hook |
(add-hook 'idlwave-mode-hook |
2038 |
@end lisp |
@end lisp |
2039 |
|
|
2040 |
@defopt idlwave-surround-by-blank (@code{nil}) |
@defopt idlwave-surround-by-blank (@code{nil}) |
2041 |
Non-@code{nil} means, enable @code{idlwave-surround}. If non-nil, |
Non-@code{nil} means enable @code{idlwave-surround}. If non-@code{nil}, |
2042 |
@samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are |
@samp{=}, @samp{<}, @samp{>}, @samp{&}, @samp{,}, @samp{->} are |
2043 |
surrounded with spaces by @code{idlwave-surround}. |
surrounded with spaces by @code{idlwave-surround}. |
2044 |
@end defopt |
@end defopt |
2069 |
(idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" |
(idlwave-action-and-binding "\\<\\(pro\\|function\\)\\>[ \t]*\\<" |
2070 |
'(capitalize-word 1) t) |
'(capitalize-word 1) t) |
2071 |
;; Capitalize common block name |
;; Capitalize common block name |
2072 |
(idlwave-action-and-binding "\\<common\\>[ \t]+\\<" |
(idlwave-action-and-binding "\\<common\\>[ \t]+\\<" |
2073 |
'(capitalize-word 1) t))) |
'(capitalize-word 1) t))) |
2074 |
@end lisp |
@end lisp |
2075 |
|
|
2076 |
For more information, see the documentation string for the function |
For more information, see the documentation string for the function |
2077 |
@code{idlwave-action-and-binding}. |
@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}. |
2080 |
|
|
2081 |
@defopt idlwave-abbrev-change-case (@code{nil}) |
@defopt idlwave-abbrev-change-case (@code{nil}) |
2082 |
Non-@code{nil} means all abbrevs will be forced to either upper or lower |
Non-@code{nil} means all abbrevs will be forced to either upper or lower |
2084 |
@end defopt |
@end defopt |
2085 |
|
|
2086 |
@defopt idlwave-reserved-word-upcase (@code{nil}) |
@defopt idlwave-reserved-word-upcase (@code{nil}) |
2087 |
Non-@code{nil} means, reserved words will be made upper case via abbrev |
Non-@code{nil} means reserved words will be made upper case via abbrev |
2088 |
expansion. |
expansion. |
2089 |
@end defopt |
@end defopt |
2090 |
|
|
2096 |
@cindex Modification timestamp |
@cindex Modification timestamp |
2097 |
@cindex Header, for file documentation |
@cindex Header, for file documentation |
2098 |
@cindex Timestamp, in doc header. |
@cindex Timestamp, in doc header. |
2099 |
@cindex Changelog, in doc header. |
@cindex ChangeLog, in doc header. |
2100 |
|
|
2101 |
@kindex C-c C-h |
@kindex C-c C-h |
2102 |
@kindex C-c C-m |
@kindex C-c C-m |
2103 |
The command @kbd{C-c C-h} inserts a standard routine header into the |
The command @kbd{C-c C-h} inserts a standard routine header into the |
2104 |
buffer, with the usual fields for documentation. One of the keywords is |
buffer, with the usual fields for documentation (a different header can |
2105 |
|
be specified with @code{idlwave-file-header}). One of the keywords is |
2106 |
@samp{MODIFICATION HISTORY} under which the changes to a routine can be |
@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 |
recorded. The command @kbd{C-c C-m} jumps to the @samp{MODIFICATION |
2108 |
HISTORY} of the current routine or file and inserts the user |
HISTORY} of the current routine or file and inserts the user name with a |
2109 |
name with a timestamp. |
timestamp. |
2110 |
|
|
2111 |
@defopt idlwave-file-header |
@defopt idlwave-file-header |
2112 |
The doc-header template or a path to a file containing it. |
The doc-header template or a path to a file containing it. |
2113 |
@end defopt |
@end defopt |
2114 |
|
|
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 |
|
|
2120 |
@defopt idlwave-timestamp-hook |
@defopt idlwave-timestamp-hook |
2121 |
The hook function used to update the timestamp of a function. |
The hook function used to update the timestamp of a function. |
2122 |
@end defopt |
@end defopt |
2145 |
|
|
2146 |
IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages |
IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages |
2147 |
which make it easy to jump to the definitions of functions and |
which make it easy to jump to the definitions of functions and |
2148 |
procedures in the current file. |
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 |
2156 |
|
|
2157 |
Several commands allow to move quickly through the structure of an IDL |
In addition, @file{Speedbar} support allows convenient navigation of a |
2158 |
program. These are |
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: |
2163 |
|
|
2164 |
@multitable @columnfractions .15 .85 |
@multitable @columnfractions .15 .85 |
2165 |
@item @kbd{C-M-a} |
@item @kbd{C-M-a} |
2206 |
|
|
2207 |
|
|
2208 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2209 |
@node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top |
@node The IDLWAVE Shell, Installation, The IDLWAVE Major Mode, Top |
2210 |
@chapter The IDLWAVE Shell |
@chapter The IDLWAVE Shell |
2211 |
@cindex IDLWAVE shell |
@cindex IDLWAVE shell |
2216 |
@cindex Windows |
@cindex Windows |
2217 |
@cindex MacOS |
@cindex MacOS |
2218 |
|
|
2219 |
The IDLWAVE shell is an Emacs major mode which allows to run the IDL |
The IDLWAVE shell is an Emacs major mode which permits running the IDL |
2220 |
program as an inferior process of Emacs. It can be used to work with |
program as an inferior process of Emacs, and works closely with the |
2221 |
IDL interactively, to compile and run IDL programs in Emacs buffers and |
IDLWAVE major mode in buffers. It can be used to work with IDL |
2222 |
to debug these programs. The IDLWAVE shell uses @file{comint}, an Emacs |
interactively, to compile and run IDL programs in Emacs buffers and to |
2223 |
packages which handles the communication with the IDL program. |
debug these programs. The IDLWAVE shell is built upon @file{comint}, an |
2224 |
Unfortunately IDL for Windows and MacOS does not allow the interaction |
Emacs packages which handles the communication with the IDL program. |
2225 |
with Emacs@footnote{Please inform the maintainer if you come up with a way |
Unfortunately IDL for Windows and MacOS do not have command-prompt |
2226 |
to make the IDLWAVE shell work on these systems.}, so the IDLWAVE shell |
versions and thus do not allow the interaction with |
2227 |
only works under GNU and Unix. |
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 |
2229 |
|
currently only works under Unix. |
2230 |
|
|
2231 |
@menu |
@menu |
2232 |
* Starting the Shell:: How to launch IDL as a subprocess |
* Starting the Shell:: How to launch IDL as a subprocess |
2233 |
* Using the Shell:: Interactively working with the Shell |
* Using the Shell:: Interactively working with the Shell |
2234 |
* Debugging IDL Programs:: Compilation/Debugging |
* Commands Sent to the Shell:: |
2235 |
|
* Debugging IDL Programs:: |
2236 |
|
* Examining Variables:: |
2237 |
|
* Custom Expression Examination:: |
2238 |
@end menu |
@end menu |
2239 |
|
|
2240 |
@node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell |
@node Starting the Shell, Using the Shell, The IDLWAVE Shell, The IDLWAVE Shell |
2251 |
@kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to |
@kbd{C-c C-s}. It creates a buffer @file{*idl*} which is used to |
2252 |
interact with the shell. If the shell is already running, @kbd{C-c C-s} |
interact with the shell. If the shell is already running, @kbd{C-c C-s} |
2253 |
will simple switch to the shell buffer. The command @kbd{C-c C-l} |
will simple switch to the shell buffer. The command @kbd{C-c C-l} |
2254 |
(@code{idlwave-shell-recenter-shell-window}) displays the |
(@code{idlwave-shell-recenter-shell-window}) displays the shell window |
2255 |
shell window without selecting it. |
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}. |
2258 |
|
|
2259 |
In order to create a separate frame for the IDLWAVE shell buffer, call |
In order to create a separate frame for the IDLWAVE shell buffer, call |
2260 |
@code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or |
@code{idlwave-shell} with a prefix argument: @kbd{C-u C-c C-s} or |
2261 |
@kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell |
@kbd{C-u C-c C-l}. If you always want a dedicated frame for the shell |
2262 |
window, configure the variable |
window, configure the variable |
2263 |
@code{idlwave-shell-use-dedicated-frame}. |
@code{idlwave-shell-use-dedicated-frame}. |
2264 |
|
|
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 |
The shell can also be started automatically when another command tries |
@example |
2270 |
to send a command to it. To enable auto start, set the variable |
emacs -geometry 80x32 -eval "(idlwave-shell 'quick)" |
2271 |
@code{idlwave-shell-automatic-start} to @code{t}. |
@end example |
2272 |
|
|
2273 |
@defopt idlwave-shell-explicit-file-name |
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}) |
2277 |
This is the command to run IDL. |
This is the command to run IDL. |
2278 |
@end defopt |
@end defopt |
2279 |
|
|
2289 |
Name to be associated with the IDL process. |
Name to be associated with the IDL process. |
2290 |
@end defopt |
@end defopt |
2291 |
|
|
2292 |
@defopt idlwave-shell-automatic-start |
@defopt idlwave-shell-automatic-start (@code{nil}) |
2293 |
Non-@code{nil} means attempt to invoke idlwave-shell if not already |
Non-@code{nil} means attempt to invoke idlwave-shell if not already |
2294 |
running. |
running. |
2295 |
@end defopt |
@end defopt |
2298 |
Initial commands, separated by newlines, to send to IDL. |
Initial commands, separated by newlines, to send to IDL. |
2299 |
@end defopt |
@end defopt |
2300 |
|
|
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 |
2308 |
|
|
2309 |
@defopt idlwave-shell-use-dedicated-frame (@code{nil}) |
@defopt idlwave-shell-use-dedicated-frame (@code{nil}) |
2310 |
Non-@code{nil} means, IDLWAVE should use a special frame to display |
Non-@code{nil} means IDLWAVE should use a special frame to display |
2311 |
shell buffer. |
shell buffer. |
2312 |
@end defopt |
@end defopt |
2313 |
|
|
2314 |
@defopt idlwave-shell-frame-parameters |
@defopt idlwave-shell-frame-parameters |
2315 |
The frame parameters for a dedicated idlwave-shell frame. |
The frame parameters for a dedicated idlwave-shell frame. |
2316 |
@end defopt |
@end defopt |
2317 |
|
|
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 |
|
|
2323 |
@defopt idlwave-shell-temp-pro-prefix |
@defopt idlwave-shell-temp-pro-prefix |
2324 |
The prefix for temporary IDL files used when compiling regions. |
The prefix for temporary IDL files used when compiling regions. |
2325 |
@end defopt |
@end defopt |
2329 |
Hook for customizing @code{idlwave-shell-mode}. |
Hook for customizing @code{idlwave-shell-mode}. |
2330 |
@end defopt |
@end defopt |
2331 |
|
|
2332 |
@node Using the Shell, Debugging IDL Programs, Starting the Shell, The IDLWAVE Shell |
@node Using the Shell, Commands Sent to the Shell, Starting the Shell, The IDLWAVE Shell |
2333 |
@section Using the Shell |
@section Using the Shell |
2334 |
@cindex Comint |
@cindex Comint |
2335 |
@cindex Shell, basic commands |
@cindex Shell, basic commands |
2340 |
history just like in an X terminal@footnote{This is different from |
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 |
normal Emacs/Comint behavior, but more like an xterm. If you prefer the |
2342 |
default comint functionality, check the variable |
default comint functionality, check the variable |
2343 |
@code{idlwave-shell-arrows-do-history}.}. Here is a list of |
@code{idlwave-shell-arrows-do-history}.}. The history is preserved |
2344 |
commonly used commands. |
between emacs and IDL sessions. Here is a list of commonly used |
2345 |
|
commands: |
2346 |
|
|
2347 |
@multitable @columnfractions .12 .88 |
@multitable @columnfractions .12 .88 |
2348 |
@item @key{UP} |
@item @key{UP}, @key{M-p} |
2349 |
@tab Cycle backwards in input history |
@tab Cycle backwards in input history |
2350 |
@item @key{DOWN} |
@item @key{DOWN}, @key{M-n} |
2351 |
@tab Cycle forwards in input history |
@tab Cycle forwards in input history |
|
@item @kbd{M-p} |
|
|
@tab Cycle backwards in input history @emph{matching input} |
|
|
@item @kbd{M-n} |
|
|
@tab Cycle forwards in input history @emph{matching input} |
|
2352 |
@item @kbd{M-r} |
@item @kbd{M-r} |
2353 |
@tab Previous input matching a regexp |
@tab Previous input matching a regexp |
2354 |
@item @kbd{M-s} |
@item @kbd{M-s} |
2355 |
@tab Next input that matches a regexp |
@tab Next input matching a regexp |
2356 |
@item @kbd{return} |
@item @kbd{return} |
2357 |
@tab Send input or copy line to current prompt |
@tab Send input or copy line to current prompt |
2358 |
@item @kbd{C-c C-a} |
@item @kbd{C-c C-a} |
2376 |
@end multitable |
@end multitable |
2377 |
|
|
2378 |
In addition to these standard @file{comint} commands, |
In addition to these standard @file{comint} commands, |
2379 |
@code{idlwave-shell-mode} provides many of the commands which simplify |
@code{idlwave-shell-mode} provides many of the same commands which |
2380 |
writing IDL code, including abbreviations, online help, and completion. |
simplify writing IDL code available in IDLWAVE buffers. This includes |
2381 |
See @ref{Routine Info} and @ref{Online Help} and @ref{Completion} for more |
abbreviations, online help, and completion. See @ref{Routine Info} and |
2382 |
information on these commands. |
@ref{Online Help} and @ref{Completion} for more information on these |
2383 |
|
commands. |
2384 |
|
|
2385 |
@cindex Completion, in the shell |
@cindex Completion, in the shell |
2386 |
@cindex Routine info, in the shell |
@cindex Routine info, in the shell |
2387 |
@cindex Online Help, in the shell |
@cindex Online Help, in the shell |
2388 |
@multitable @columnfractions .12 .88 |
@multitable @columnfractions .12 .88 |
2389 |
@item @kbd{@key{TAB}} |
@item @kbd{@key{TAB}} |
2390 |
@tab Completion of file names, routine names and keywords |
@tab Completion of file names (between quotes and after executive |
2391 |
(@code{idlwave-shell-complete}) |
commands @samp{.run} and @samp{.compile}), routine names, class names, |
2392 |
|
keywords, system variables, system variable tags etc. |
2393 |
|
(@code{idlwave-shell-complete}). |
2394 |
@item @kbd{M-@key{TAB}} |
@item @kbd{M-@key{TAB}} |
2395 |
@tab Same as @key{TAB} |
@tab Same as @key{TAB} |
2396 |
@item @kbd{C-c ?} |
@item @kbd{C-c ?} |
2411 |
history like xterm. |
history like xterm. |
2412 |
@end defopt |
@end defopt |
2413 |
|
|
2414 |
|
@defopt idlwave-shell-comint-settings |
2415 |
|
Alist of special settings for the comint variables in the IDLWAVE Shell. |
2416 |
|
@end defopt |
2417 |
|
|
2418 |
@defopt idlwave-shell-file-name-chars |
@defopt idlwave-shell-file-name-chars |
2419 |
The characters allowed in file names, as a string. Used for file name |
The characters allowed in file names, as a string. Used for file name |
2420 |
completion. |
completion. |
2444 |
automatic switches of the input mode. |
automatic switches of the input mode. |
2445 |
|
|
2446 |
@defopt idlwave-shell-use-input-mode-magic (@code{nil}) |
@defopt idlwave-shell-use-input-mode-magic (@code{nil}) |
2447 |
Non-nil means, IDLWAVE should check for input mode spells in output. |
Non-@code{nil} means IDLWAVE should check for input mode spells in |
2448 |
|
output. |
2449 |
@end defopt |
@end defopt |
2450 |
|
|
2451 |
@defopt idlwave-shell-input-mode-spells |
@defopt idlwave-shell-input-mode-spells |
2453 |
modes. |
modes. |
2454 |
@end defopt |
@end defopt |
2455 |
|
|
2456 |
@node Debugging IDL Programs, , Using the Shell, The IDLWAVE Shell |
@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 |
2494 |
@section Debugging IDL Programs |
@section Debugging IDL Programs |
2495 |
@cindex Debugging |
@cindex Debugging |
2496 |
@cindex Keybindings for debugging |
@cindex Keybindings for debugging |
2497 |
@cindex Toolbar |
@cindex Toolbar |
2498 |
|
|
|
@kindex C-c C-d |
|
2499 |
Programs can be compiled, run, and debugged directly from the source |
Programs can be compiled, run, and debugged directly from the source |
2500 |
buffer in Emacs. The IDLWAVE shell installs key bindings both in the |
buffer in Emacs. IDLWAVE makes compiling and debugging IDL programs |
2501 |
shell buffer and in all IDL code buffers of the current Emacs session. |
far less cumbersome by providing a full-featured, |
2502 |
On Emacs versions which support this, it also installs a debugging |
key/menu/toolbar-driven interface to commands like @code{breakpoint}, |
2503 |
toolbar. The display of the toolbar can be toggled with @kbd{C-c C-d |
@code{.step}, @code{.run}, etc. |
2504 |
C-t} (@code{idlwave-shell-toggle-toolbar}). |
|
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 |
2518 |
|
* Debug Key Bindings:: |
2519 |
|
* Compiling Programs:: |
2520 |
|
* Breakpoints and Stepping:: |
2521 |
|
* Walking the Calling Stack:: |
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 |
2528 |
|
|
2529 |
The debugging key bindings are by default on the prefix key @kbd{C-c |
The debugging key bindings are by default on the prefix key @kbd{C-c |
2530 |
C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d |
C-d}, so for example setting a breakpoint is done with @kbd{C-c C-d |
2531 |
C-b}, compiling a source file with @kbd{C-c C-d C-c}. If you find this |
C-b}, and compiling a source file with @kbd{C-c C-d C-c}. If you find |
2532 |
too much work you can choose a combination of modifier keys which is not |
this too much work, you can easily configure IDLWAVE to use one or more |
2533 |
used by other commands. For example, if you write in @file{.emacs} |
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}: |
2537 |
|
|
2538 |
@lisp |
@lisp |
2539 |
(setq idlwave-shell-debug-modifiers '(control shift)) |
(setq idlwave-shell-debug-modifiers '(control shift)) |
2540 |
@end lisp |
@end lisp |
2541 |
|
|
2542 |
a breakpoint can be set by pressing @kbd{b} while holding down |
@noindent a breakpoint can be set by pressing @kbd{b} while holding down |
2543 |
@kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a |
@kbd{shift} and @kbd{control} keys, i.e. @kbd{C-S-b}. Compiling a |
2544 |
source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d} |
source file will be on @kbd{C-S-c}, deleting a breakpoint @kbd{C-S-d}, |
2545 |
etc. In the remainder of this chapter we will assume that the @kbd{C-c |
etc. In the remainder of this chapter we will assume that the @kbd{C-c |
2546 |
C-d} bindings are active, but each of these bindings will have an |
C-d} bindings are active, but each of these bindings will have an |
2547 |
equivalent single-keypress shortcut with the modifiers given in the |
equivalent single-keypress shortcut if modifiers are given in the |
2548 |
@code{idlwave-shell-debug-modifiers} variable. |
@code{idlwave-shell-debug-modifiers} variable (see @pxref{Lesson II -- |
2549 |
|
Customization}). |
2550 |
|
|
2551 |
@defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) |
@defopt idlwave-shell-prefix-key (@kbd{C-c C-d}) |
2552 |
The prefix key for the debugging map |
The prefix key for the debugging map |
2554 |
@end defopt |
@end defopt |
2555 |
|
|
2556 |
@defopt idlwave-shell-activate-prefix-keybindings (@code{t}) |
@defopt idlwave-shell-activate-prefix-keybindings (@code{t}) |
2557 |
Non-@code{nil} means, debug commands will be bound to the prefix |
Non-@code{nil} means debug commands will be bound to the prefix |
2558 |
key, like @kbd{C-c C-d C-b}. |
key, like @kbd{C-c C-d C-b}. |
2559 |
@end defopt |
@end defopt |
2560 |
|
|
2561 |
@defopt idlwave-shell-debug-modifiers (@code{nil}) |
@defopt idlwave-shell-debug-modifiers (@code{nil}) |
2562 |
List of modifier keys to use for binding debugging commands in the shell |
List of modifier keys to use for additional binding of debugging |
2563 |
and in source buffers. |
commands in the shell and source buffers. Can be one or more of |
2564 |
@end defopt |
@code{control}, @code{meta}, @code{super}, @code{hyper}, @code{alt}, and |
2565 |
|
@code{shift}. |
|
@defopt idlwave-shell-use-toolbar (@code{t}) |
|
|
Non-@code{nil} means, use the debugging toolbar in all IDL related |
|
|
buffers. |
|
2566 |
@end defopt |
@end defopt |
2567 |
|
|
2568 |
|
@node Compiling Programs, Breakpoints and Stepping, Debug Key Bindings, Debugging IDL Programs |
|
@menu |
|
|
* Compiling Programs:: Compiling buffers under the shell |
|
|
* Breakpoints and Stepping:: Deciding where to stop and look |
|
|
* Examining Variables:: What is the value now? |
|
|
@end menu |
|
|
|
|
|
@node Compiling Programs, Breakpoints and Stepping, Debugging IDL Programs, Debugging IDL Programs |
|
2569 |
@subsection Compiling Programs |
@subsection Compiling Programs |
2570 |
@cindex Compiling programs |
@cindex Compiling programs |
2571 |
@cindex Programs, compiling |
@cindex Programs, compiling |
2575 |
@kindex C-c C-d C-c |
@kindex C-c C-d C-c |
2576 |
In order to compile the current buffer under the IDLWAVE shell, press |
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 |
@kbd{C-c C-d C-c} (@code{idlwave-save-and-run}). This first saves the |
2578 |
current buffer and then send the command @samp{.run path/to/file} to the |
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 |
shell. You can also execute @kbd{C-c C-d C-c} from the shell buffer, in |
2580 |
which case the most recently compiled buffer will be saved and |
which case the most recently compiled buffer will be saved and |
2581 |
re-compiled. |
re-compiled. |
2582 |
|
|
2583 |
When developing or debugging a program, it is often necessary to execute |
When developing or debugging a program, it is often necessary to execute |
2584 |
the same command line many times. A convenient way to do this is |
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}). |
@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 |
This command first resets IDL from a state of interrupted execution by |
2590 |
prefix argument: @kbd{C-u C-c C-d C-y}. |
prefix argument: @kbd{C-u C-c C-d C-y}. |
2591 |
|
|
2592 |
@defopt idlwave-shell-mark-stop-line (@code{t}) |
@defopt idlwave-shell-mark-stop-line (@code{t}) |
2593 |
Non-@code{nil} means, mark the source code line where IDL is currently |
Non-@code{nil} means mark the source code line where IDL is currently |
2594 |
stopped. The value decides about the preferred method. Legal values |
stopped. The value specifies the preferred method. Legal values are |
2595 |
are @code{nil}, @code{t}, @code{arrow}, and @code{face}. |
@code{nil}, @code{t}, @code{arrow}, and @code{face}. |
2596 |
@end defopt |
@end defopt |
2597 |
|
|
2598 |
@defopt idlwave-shell-overlay-arrow (@code{">"}) |
@defopt idlwave-shell-overlay-arrow (@code{">"}) |
2599 |
The overlay arrow to display at source lines where execution |
The overlay arrow to display at source lines where execution halts, if |
2600 |
halts. |
configured in @code{idlwave-shell-mark-stop-line}. |
2601 |
@end defopt |
@end defopt |
2602 |
|
|
2603 |
@defopt idlwave-shell-stop-line-face |
@defopt idlwave-shell-stop-line-face |
2604 |
The face which highlights the source line where IDL is |
The face which highlights the source line where IDL is stopped, if |
2605 |
stopped. |
configured in @code{idlwave-shell-mark-stop-line}. |
2606 |
@end defopt |
@end defopt |
2607 |
|
|
2608 |
@node Breakpoints and Stepping, Examining Variables, Compiling Programs, Debugging IDL Programs |
@node Breakpoints and Stepping, Walking the Calling Stack, Compiling Programs, Debugging IDL Programs |
2609 |
@subsection Breakpoints and Stepping |
@subsection Breakpoints and Stepping |
2610 |
@cindex Breakpoints |
@cindex Breakpoints |
2611 |
@cindex Stepping |
@cindex Stepping |
2616 |
You can set breakpoints and step through a program with IDLWAVE. |
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 |
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 |
with @kbd{C-c C-d C-b} (@code{idlwave-shell-break-here}). With a prefix |
2619 |
arg of 1, the breakpoint gets a @code{/ONCE} keyword, meaning that it |
arg of 1 (i.e. @kbd{C-1 C-c C-d C-b}), the breakpoint gets a |
2620 |
will be deleted after first use. With a numeric prefix greater than |
@code{/ONCE} keyword, meaning that it will be deleted after first use. |
2621 |
one, the breakpoint will only be active the @code{nth} time it is hit. |
With a numeric prefix greater than one (e.g. @kbd{C-4 C-c C-d C-b}), the |
2622 |
To clear the breakpoint in the current line, use @kbd{C-c C-d C-d} |
breakpoint will only be active the @code{nth} time it is hit. With a |
2623 |
(@code{idlwave-clear-current-bp}). To clear all breakpoints, use |
single non-numeric prefix (i.e. @kbd{C-u C-c C-d C-b}), prompt for a |
2624 |
@kbd{C-c C-d C-a} (@code{idlwave-clear-all-bp}). Breakpoint lines are |
condition --- an IDL expression to be evaulated and trigger the |
2625 |
highlighted in the source code. |
breakpoint only if true. To clear the breakpoint in the current line, |
2626 |
|
use @kbd{C-c C-d C-d} (@code{idlwave-clear-current-bp}). When executed |
2627 |
Once the program has stopped somewhere, you can step through it. Here |
from the shell window, the breakpoint where IDL is currently stopped |
2628 |
is a summary of the breakpoint and stepping commands: |
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 |
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. |
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 |
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 |
2643 |
|
breakpoint and stepping commands: |
2644 |
|
|
2645 |
@multitable @columnfractions .23 .77 |
@multitable @columnfractions .23 .77 |
2646 |
@item @kbd{C-c C-d C-b} |
@item @kbd{C-c C-d C-b} |
2674 |
@end multitable |
@end multitable |
2675 |
|
|
2676 |
@defopt idlwave-shell-mark-breakpoints (@code{t}) |
@defopt idlwave-shell-mark-breakpoints (@code{t}) |
2677 |
Non-@code{nil} means, mark breakpoints in the source file buffers. The |
Non-@code{nil} means mark breakpoints in the source file buffers. The |
2678 |
value indicates the preferred method. Legal values are @code{nil}, |
value indicates the preferred method. Legal values are @code{nil}, |
2679 |
@code{t}, @code{face}, and @code{glyph}. |
@code{t}, @code{face}, and @code{glyph}. |
2680 |
@end defopt |
@end defopt |
2684 |
@code{idlwave-shell-mark-breakpoints} has the value @code{face}. |
@code{idlwave-shell-mark-breakpoints} has the value @code{face}. |
2685 |
@end defopt |
@end defopt |
2686 |
|
|
2687 |
@node Examining Variables, , Breakpoints and Stepping, Debugging IDL Programs |
@node Walking the Calling Stack, , Breakpoints and Stepping, Debugging IDL Programs |
2688 |
@subsection Examining Variables |
@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 |
|
|
2706 |
|
@ifhtml |
2707 |
|
<A NAME="EXAMINE"></A> |
2708 |
|
@end ifhtml |
2709 |
|
@node Examining Variables, Custom Expression Examination, Debugging IDL Programs, The IDLWAVE Shell |
2710 |
|
@section Examining Variables |
2711 |
@cindex @code{PRINT} expressions |
@cindex @code{PRINT} expressions |
2712 |
@cindex @code{HELP}, on expressions |
@cindex @code{HELP}, on expressions |
2713 |
@cindex Expressions, printing |
@cindex Expressions, printing |
2714 |
@cindex Expressions, help |
@cindex Expressions, help |
2715 |
|
@cindex Printing expressions |
2716 |
@cindex Mouse binding to print expressions |
@cindex Mouse binding to print expressions |
2717 |
|
|
2718 |
@kindex C-c C-d C-p |
@kindex C-c C-d C-p |
2719 |
When execution is stopped you can examine the values of variables. The |
Do you find yourself repeatedly typing, e.g. @code{print,n_elements(x)}, |
2720 |
command @kbd{C-c C-d C-p} prints the expression at point, while @kbd{C-c |
and similar statements to remind yourself of the |
2721 |
C-d ?} shows help on this expression. The expression at point is an |
type/size/structure/value/etc. of variables and expressions in your code |
2722 |
array expression or a function call, or the contents of a pair of |
or at the command line? IDLWAVE has a suite of special commands to |
2723 |
parenthesis. The selected expression becomes highlighted in the source |
automate these types of variables or expression examinations. They work |
2724 |
code for a short time. Calling the above commands with a prefix |
by sending statements to the shell formatted to include the indicated |
2725 |
argument will prompt for an expression instead of using the one at |
expression. |
2726 |
point. |
|
2727 |
|
These examination commands can be used in the shell or buffer at any |
2728 |
It is very convenient to click with the mouse on expressions to retrieve |
time (as long as the shell is running), and are very useful when |
2729 |
their value. Expression printing is also bound to @kbd{S-Mouse-2} and |
execution is stopped in a buffer due to a triggered breakpoint or error, |
2730 |
expression help to @kbd{C-S-Mouse-2}. I.e. you need to hold down |
or while composing a long command in the IDLWAVE shell. In the latter |
2731 |
@key{SHIFT} and @key{CONTROL} while clicking with the mouse. |
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 |
2733 |
|
the constituents of a command you're building without interrupting the |
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 |
2756 |
|
@kbd{S-Mouse-2} to print an expression and @kbd{C-M-Mouse-2} to invoke |
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 |
|
|
|
@cindex Calling stack, motion |
|
2765 |
@cindex Printing expressions, on calling stack |
@cindex Printing expressions, on calling stack |
2766 |
@cindex Restrictions for expression printing |
@cindex Restrictions for expression printing |
2767 |
Printing of expressions also works on higher levels of the calling |
The same variable inspection commands work both in the IDL Shell and |
2768 |
stack. This means that you can examine the values of variables and |
IDLWAVE buffers, and even for variables at higher levels of the calling |
2769 |
expressions inside the routine which called the current routine etc. |
stack. For instance, if you're stopped at a breakpoint in a routine, |
2770 |
Use the commands @kbd{C-c C-d C-@key{UP}} |
you can examine the values of variables and expressions inside its |
2771 |
(@code{idlwave-shell-stack-up}) and @kbd{C-c C-d C-@key{DOWN}} |
calling routine, and so on, all the way up through the calling stack. |
2772 |
(@code{idlwave-shell-stack-down}) or the corresponding toolbar buttons |
Simply step up the stack, and print variables as you see them |
2773 |
to move through the calling stack. The mode line of the shell window |
(@pxref{Walking the Calling Stack}, for information on stepping back |
2774 |
will indicate the routine and the calling stack level which define the |
through the calling stack). The following restrictions apply for all |
2775 |
context for printing expressions. The following restrictions apply for |
levels except the current: |
|
all levels except the current: |
|
2776 |
|
|
2777 |
@itemize @bullet |
@itemize @bullet |
2778 |
@item |
@item |
2780 |
with a @samp{( )} will be interpreted as function calls. |
with a @samp{( )} will be interpreted as function calls. |
2781 |
@item |
@item |
2782 |
@cindex ROUTINE_NAMES, IDL procedure |
@cindex ROUTINE_NAMES, IDL procedure |
2783 |
Printing values of expressions on higher levels of the calling stack |
N.B.: printing values of expressions on higher levels of the calling |
2784 |
uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, which may |
stack uses the @emph{unsupported} IDL routine @code{ROUTINE_NAMES}, |
2785 |
or may not be available in future versions of IDL. |
which may or may not be available in future versions of IDL. |
2786 |
@end itemize |
@end itemize |
2787 |
|
|
2788 |
@defopt idlwave-shell-expression-face |
@defopt idlwave-shell-expression-face |
2791 |
the expression printed by IDL. |
the expression printed by IDL. |
2792 |
@end defopt |
@end defopt |
2793 |
|
|
2794 |
@defopt idlwave-shell-print-expression-function (@code{nil}) |
@defopt idlwave-shell-output-face |
2795 |
A function to handle special display of evaluated expressions. |
The face for @code{idlwave-shell-output-overlay}. |
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 |
2802 |
|
@file{*Examine*} buffer, instead of in the shell itself. |
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 |
2818 |
|
@kbd{C-S-Mouse-2}. Just as for all the other mouse examine commands, it |
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}. |
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. |
2830 |
|
|
2831 |
|
In addition to the pop-up mouse command, you can easily create your own |
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.: |
2839 |
|
|
2840 |
|
@lisp |
2841 |
|
(add-hook 'idlwave-shell-mode-hook |
2842 |
|
(lambda () |
2843 |
|
(idlwave-shell-define-key-both [s-down-mouse-2] |
2844 |
|
(idlwave-shell-mouse-examine |
2845 |
|
"print, size(___,/DIMENSIONS)")) |
2846 |
|
(idlwave-shell-define-key-both [f9] (idlwave-shell-examine |
2847 |
|
"print, size(___,/DIMENSIONS)")) |
2848 |
|
(idlwave-shell-define-key-both [f10] (idlwave-shell-examine |
2849 |
|
"print,size(___,/TNAME)")) |
2850 |
|
(idlwave-shell-define-key-both [f11] (idlwave-shell-examine |
2851 |
|
"help,___,/STRUCTURE")))) |
2852 |
|
@end lisp |
2853 |
|
|
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 |
2862 |
|
displayed in the selection pop-up, and the values are custom IDL examine |
2863 |
|
command strings to send, after all instances of @code{___} are replaced |
2864 |
|
by the indicated expression. |
2865 |
@end defopt |
@end defopt |
2866 |
|
|
2867 |
@node Installation, Acknowledgement, The IDLWAVE Shell, Top |
|
2868 |
|
@node Installation, Acknowledgements, The IDLWAVE Shell, Top |
2869 |
@chapter Installation |
@chapter Installation |
2870 |
@cindex Installation |
@cindex Installation |
2871 |
|
|
2890 |
@uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site} |
@uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,the XEmacs ftp site} |
2891 |
with the normal package management system on XEmacs 21. These |
with the normal package management system on XEmacs 21. These |
2892 |
pre-installed versions should work out-of-the-box. However, the files |
pre-installed versions should work out-of-the-box. However, the files |
2893 |
needed for online help are not distributed with XEmacs/Emacs and have to |
required for online help are not distributed with XEmacs/Emacs and have |
2894 |
be installed separately@footnote{Due to copyright reasons, the ASCII |
to be installed separately@footnote{Due to copyright reasons, the ASCII |
2895 |
version of the IDL manual cannot be distributed under the GPL.} |
version of the IDL manual cannot be distributed under the GPL.} |
2896 |
(@pxref{Installing Online Help}). |
(@pxref{Installing Online Help}). |
2897 |
|
|
2899 |
@uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. Follow the |
@uref{@value{IDLWAVE-HOMEPAGE}, the maintainers webpage}. Follow the |
2900 |
instructions in the INSTALL file. |
instructions in the INSTALL file. |
2901 |
|
|
2902 |
@node Installing Online Help, Upgrading from idl.el , Installing IDLWAVE, Installation |
@node Installing Online Help, Upgrading from idl.el, Installing IDLWAVE, Installation |
2903 |
@section Installing Online Help |
@section Installing Online Help |
2904 |
@cindex Installing online help |
@cindex Installing online help |
2905 |
@cindex Online Help, Installation |
@cindex Online Help, Installation |
2941 |
@lisp |
@lisp |
2942 |
(setq idlwave-shell-use-dedicated-frame t) |
(setq idlwave-shell-use-dedicated-frame t) |
2943 |
@end lisp |
@end lisp |
2944 |
@item |
@item |
2945 |
The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character. |
The key sequence @kbd{M-@key{TAB}} no longer inserts a TAB character. |
2946 |
Like in many other Emacs modes, @kbd{M-@key{TAB}} now does |
Like in many other Emacs modes, @kbd{M-@key{TAB}} now does |
2947 |
completion. Inserting a TAB has therefore been moved to |
completion. Inserting a TAB has therefore been moved to |
2949 |
@kbd{C-c @key{SPC}}. |
@kbd{C-c @key{SPC}}. |
2950 |
@end enumerate |
@end enumerate |
2951 |
|
|
2952 |
@node Acknowledgement, Sources of Routine Info, Installation, Top |
@node Acknowledgements, Sources of Routine Info, Installation, Top |
2953 |
@chapter Acknowledgement |
@chapter Acknowledgements |
2954 |
@cindex Acknowledgement |
@cindex Acknowledgements |
2955 |
@cindex Maintainer, of IDLWAVE |
@cindex Maintainer, of IDLWAVE |
2956 |
@cindex Authors, of IDLWAVE |
@cindex Authors, of IDLWAVE |
2957 |
@cindex Contributors, to IDLWAVE |
@cindex Contributors, to IDLWAVE |
2968 |
for several years. |
for several years. |
2969 |
|
|
2970 |
@item |
@item |
2971 |
@uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}}, who have |
@uref{mailto:dominik@@astro.uva.nl, @b{Carsten Dominik}} was in charge |
2972 |
been in charge of the package since version 3.0, and also wrote this |
of the package from version 3.0, during which time he overhauled almost |
2973 |
|
everything, modernized IDLWAVE with many new features, and developed the |
2974 |
manual. |
manual. |
2975 |
|
|
2976 |
@item |
@item |
2977 |
@uref{mailto: jdsmith@@astro.cornell.edu, @b{John-David Smith}}, |
@uref{mailto:jdsmith@@as.arizona.edu, @b{J.D. Smith}}, the current |
2978 |
current maintainer, who is also responsible for this manual's |
maintainer, as of version 4.10, helped shape object method completion |
2979 |
maintenance. John-David has also shaped Object method completion and |
and most new features introduced in versions 4.x. |
|
most new features in version 4.0 with his ideas, bug reports, and |
|
|
patient explanations of IDL internals. |
|
2980 |
@end itemize |
@end itemize |
2981 |
|
|
2982 |
@noindent |
@noindent |
2995 |
@item |
@item |
2996 |
Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de> |
Kevin Ivory <Kevin.Ivory@@linmpi.mpg.de> |
2997 |
@item |
@item |
2998 |
|
Dick Jackson <dick@@d-jackson.com> |
2999 |
|
@item |
3000 |
Xuyong Liu <liu@@stsci.edu> |
Xuyong Liu <liu@@stsci.edu> |
3001 |
@item |
@item |
3002 |
Simon Marshall <Simon.Marshall@@esrin.esa.it> |
Simon Marshall <Simon.Marshall@@esrin.esa.it> |
3007 |
@item |
@item |
3008 |
Lubos Pochman <lubos@@rsinc.com> |
Lubos Pochman <lubos@@rsinc.com> |
3009 |
@item |
@item |
3010 |
|
Bob Portmann <portmann@@al.noaa.gov> |
3011 |
|
@item |
3012 |
Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov> |
Patrick M. Ryan <pat@@jaameri.gsfc.nasa.gov> |
3013 |
@item |
@item |
3014 |
Marty Ryba <ryba@@ll.mit.edu> |
Marty Ryba <ryba@@ll.mit.edu> |
3021 |
@noindent |
@noindent |
3022 |
Thanks to everyone! |
Thanks to everyone! |
3023 |
|
|
3024 |
@node Sources of Routine Info, Configuration Examples, Acknowledgement, Top |
@node Sources of Routine Info, Configuration Examples, Acknowledgements, Top |
3025 |
@appendix Sources of Routine Info |
@appendix Sources of Routine Info |
3026 |
|
|
3027 |
@cindex Sources of routine information |
@cindex Sources of routine information |
3028 |
In @ref{Routine Info} and @ref{Completion} it was shown how IDLWAVE |
In @ref{Routine Info} and @ref{Completion} we showed how IDLWAVE |
3029 |
displays the calling sequence and keywords of routines, and how it |
displays the calling sequence and keywords of routines, and completes |
3030 |
completes routine names and keywords. For these features to work, |
routine names and keywords. For these features to work, IDLWAVE must |
3031 |
IDLWAVE must know about the accessible routines. |
know about the accessible routines. |
3032 |
|
|
3033 |
@menu |
@menu |
3034 |
* Routine Definitions:: Where IDL Routines are defined. |
* Routine Definitions:: Where IDL Routines are defined. |
3039 |
@end menu |
@end menu |
3040 |
|
|
3041 |
@node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info |
@node Routine Definitions, Routine Information Sources, Sources of Routine Info, Sources of Routine Info |
3042 |
@section Routine Definitions |
@appendixsec Routine Definitions |
3043 |
@cindex Routine definitions |
@cindex Routine definitions |
3044 |
@cindex IDL variable @code{!PATH} |
@cindex IDL variable @code{!PATH} |
3045 |
@cindex @code{!PATH}, IDL variable |
@cindex @code{!PATH}, IDL variable |
3047 |
@cindex @code{LINKIMAGE}, IDL routine |
@cindex @code{LINKIMAGE}, IDL routine |
3048 |
@cindex External routines |
@cindex External routines |
3049 |
|
|
3050 |
Routines which can be used in an IDL program can be defined in several |
@noindent Routines which can be used in an IDL program can be defined in |
3051 |
places: |
several places: |
3052 |
|
|
3053 |
@enumerate |
@enumerate |
3054 |
@item |
@item |
3055 |
@emph{Builtin routines} are defined inside IDL itself. The source |
@emph{Builtin routines} are defined inside IDL itself. The source |
3056 |
code of such routines is not accessible to the user. |
code of such routines is not available. |
3057 |
@item |
@item |
3058 |
Routines @emph{part of the current program} are defined in a file which |
Routines which are @emph{part of the current program}, are defined in a |
3059 |
is explicitly compiled by the user. This file may or may not be located |
file explicitly compiled by the user. This file may or may not be |
3060 |
on the IDL search path. |
located on the IDL search path. |
3061 |
@item |
@item |
3062 |
@emph{Library routines} are defined in special files which are located |
@emph{Library routines} are defined in files located on IDL's search |
3063 |
somewhere on IDL's search path. When a library routine is called for |
path, and will not need to be manually compiled. When a library routine |
3064 |
the first time, IDL will find the source file and compile it |
is called for the first time, IDL will find the source file and compile |
3065 |
dynamically. |
it dynamically. A special sub-category of library routines are the |
3066 |
|
@emph{system routines} distributed with IDL, and usually available in |
3067 |
|
the @file{lib} subdirectory of the IDL distribution. |
3068 |
@item |
@item |
3069 |
External routines written in other languages (like Fortran or C) can be |
External routines written in other languages (like Fortran or C) can be |
3070 |
called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, |
called with @code{CALL_EXTERNAL}, linked into IDL via @code{LINKIMAGE}, |
3071 |
or included as dynamically loaded modules (DLMs). Currently IDLWAVE |
or included as dynamically loaded modules (DLMs). Currently IDLWAVE |
3072 |
cannot provide routine info and completion for external |
cannot provide routine info and completion for such external routines. |
|
routines. |
|
3073 |
@end enumerate |
@end enumerate |
3074 |
|
|
3075 |
@node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info |
@node Routine Information Sources, Library Catalog, Routine Definitions, Sources of Routine Info |
3076 |
@section Routine Information Sources |
@appendixsec Routine Information Sources |
3077 |
@cindex Routine info sources |
@cindex Routine info sources |
3078 |
@cindex Builtin list of routines |
@cindex Builtin list of routines |
3079 |
@cindex Updating routine info |
@cindex Updating routine info |
3081 |
@cindex Buffers, scanning for routine info |
@cindex Buffers, scanning for routine info |
3082 |
@cindex Shell, querying for routine info |
@cindex Shell, querying for routine info |
3083 |
|
|
3084 |
In oder to know about as many routines as possible, IDLWAVE will do the |
@noindent To maintain the most comprehensive information about all IDL |
3085 |
following to collect information: |
routines on a system, IDLWAVE collects data from many sources: |
3086 |
|
|
3087 |
@enumerate |
@enumerate |
3088 |
|
|
3092 |
@value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords, |
@value{NSYSROUTINES} routines and @value{NSYSKEYWORDS} keywords, |
3093 |
reflecting IDL version @value{IDLVERSION}. This list has been created |
reflecting IDL version @value{IDLVERSION}. This list has been created |
3094 |
by scanning the IDL manuals and is stored in the file |
by scanning the IDL manuals and is stored in the file |
3095 |
@file{idlw-rinfo.el}. @xref{Documentation Scan}, for |
@file{idlw-rinfo.el}. @xref{Documentation Scan}, for information on how |
3096 |
information how to regenerate this file for new versions of IDL. |
to regenerate this file for new versions of IDL. |
3097 |
|
|
3098 |
@item |
@item |
3099 |
It @emph{scans} all @emph{buffers} of the current Emacs session for |
It @emph{scans} all @emph{buffers} of the current Emacs session for |
3100 |
routine definitions. This is done automatically when routine |
routine definitions. This is done automatically when routine |
3101 |
information or completion is first requested by the user. Each new |
information or completion is first requested by the user. Each new |
3104 |
can be used at any time to rescan all buffers. |
can be used at any time to rescan all buffers. |
3105 |
|
|
3106 |
@item |
@item |
3107 |
If you have an IDLWAVE-Shell running as inferior process of the current |
If you have an IDLWAVE-Shell running in the Emacs session, IDLWAVE will |
3108 |
Emacs session, IDLWAVE will @emph{query the shell} for compiled routines |
@emph{query the shell} for compiled routines and their arguments. This |
3109 |
and their arguments. This happens automatically when routine |
happens automatically when routine information or completion is first |
3110 |
information or completion is first requested by the user, and each time |
requested by the user, and each time an Emacs buffer is compiled with |
3111 |
an Emacs buffer is compiled with @kbd{C-c C-d C-c}. The command |
@kbd{C-c C-d C-c}. Though rarely necessary, the command @kbd{C-c C-i} |
3112 |
@kbd{C-c C-i} (@code{idlwave-update-routine-info}) can be used to ask |
(@code{idlwave-update-routine-info}) can be used to update the shell |
3113 |
the shell again at any time. |
routine data. |
3114 |
|
|
3115 |
@item |
@item |
3116 |
IDLWAVE can scan all or selected library files and store the result in a |
IDLWAVE can scan all or selected library source files and store the |
3117 |
file which will be automatically loaded just like |
result in a file which will be automatically loaded just like |
3118 |
@file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to |
@file{idlw-rinfo.el}. @xref{Library Catalog}, for information how to |
3119 |
scan library files. |
scan library files. |
3120 |
@end enumerate |
@end enumerate |
3121 |
|
|
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 |
|
|
3134 |
@defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) |
@defopt idlwave-scan-all-buffers-for-routine-info (@code{t}) |
3135 |
Non-@code{nil} means, scan all buffers for IDL programs when updating |
Non-@code{nil} means scan all buffers for IDL programs when updating |
3136 |
info. |
info. |
3137 |
@end defopt |
@end defopt |
3138 |
|
|
3145 |
@end defopt |
@end defopt |
3146 |
|
|
3147 |
@node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info |
@node Library Catalog, Load-Path Shadows, Routine Information Sources, Sources of Routine Info |
3148 |
@section Library Catalog |
@appendixsec Library Catalog |
3149 |
@cindex Library scan |
@cindex Library scan |
3150 |
@cindex Library catalog |
@cindex Library catalog |
3151 |
@cindex IDL library routine info |
@cindex IDL library routine info |
3163 |
Windows and MacOS, you also need to specify the search path for IDL |
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 |
library files in the variable @code{idlwave-library-path}, and the |
3165 |
location of the IDL directory (the value of the @code{!DIR} system |
location of the IDL directory (the value of the @code{!DIR} system |
3166 |
variable) in the variable @code{idlwave-system-directory}. Under Unix and GNU, |
variable) in the variable @code{idlwave-system-directory}, like |
3167 |
these values will be automatically inferred from an IDLWAVE |
this@footnote{The initial @samp{+} leads to recursive expansion of the |
3168 |
shell. |
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 |
|
|
3176 |
|
@noindent Under GNU and UNIX, these values will be automatically inferred from |
3177 |
|
an IDLWAVE shell. |
3178 |
|
|
3179 |
The command @kbd{M-x idlwave-create-libinfo-file} can then be used to |
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 |
scan library files. It brings up a widget in which you can select some |
3182 |
and completion info of some libraries, it is sufficient to scan those |
and completion info of some libraries, it is sufficient to scan those |
3183 |
directories. However, if you want IDLWAVE to detect possible name |
directories. However, if you want IDLWAVE to detect possible name |
3184 |
conflicts with routines defined in other libraries, the whole pass |
conflicts with routines defined in other libraries, the whole pass |
3185 |
should be scanned. |
should be scanned. |
3186 |
|
|
3187 |
After selecting directories, click on the @w{@samp{[Scan & Save]}} |
After selecting directories, click on the @w{@samp{[Scan & Save]}} |
3188 |
button in the widget to scan all files in the selected directories and |
button in the widget to scan all files in the selected directories and |
3192 |
@code{idlwave-update-routine-info} with a double prefix argument: |
@code{idlwave-update-routine-info} with a double prefix argument: |
3193 |
@w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously |
@w{@kbd{C-u C-u C-c C-i}}. This will rescan files in the previously |
3194 |
selected directories, write an updated version of the libinfo file and |
selected directories, write an updated version of the libinfo file and |
3195 |
rebuild IDLWAVEs internal lists. |
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 |
3197 |
|
job@footnote{Unix systems only, I think.}. You can continue to work, |
3198 |
|
and the library catalog will be re-read when it is ready. |
3199 |
|
|
3200 |
A note of caution: Depending on your local installation, the IDL |
A note of caution: Depending on your local installation, the IDL |
3201 |
library can be very large. Parsing it for routine information will take |
library can be very large. Parsing it for routine information will take |
3208 |
@end defopt |
@end defopt |
3209 |
|
|
3210 |
@defopt idlwave-library-path |
@defopt idlwave-library-path |
3211 |
IDL library path for Windows and MacOS. Not needed under GNU and Unix. |
IDL library path for Windows and MacOS. Not needed under Unix. |
3212 |
@end defopt |
@end defopt |
3213 |
|
|
3214 |
@defopt idlwave-system-directory |
@defopt idlwave-system-directory |
3215 |
The IDL system directory for Windows and MacOS. Not needed under GNU and Unix. |
The IDL system directory for Windows and MacOS. Not needed under Unix. |
3216 |
@end defopt |
@end defopt |
3217 |
|
|
3218 |
@defopt idlwave-special-lib-alist |
@defopt idlwave-special-lib-alist |
3220 |
@end defopt |
@end defopt |
3221 |
|
|
3222 |
@node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info |
@node Load-Path Shadows, Documentation Scan, Library Catalog, Sources of Routine Info |
3223 |
@section Load-Path Shadows |
@appendixsec Load-Path Shadows |
3224 |
@cindex Load-path shadows |
@cindex Load-path shadows |
3225 |
@cindex Shadows, load-path |
@cindex Shadows, load-path |
3226 |
@cindex Duplicate routines |
@cindex Duplicate routines |
3237 |
@file{*Shadows*}. The format of the output is identical to the source |
@file{*Shadows*}. The format of the output is identical to the source |
3238 |
section of the routine info buffer (@pxref{Routine Info}). The |
section of the routine info buffer (@pxref{Routine Info}). The |
3239 |
different definitions of a routine are listed in the sequence of |
different definitions of a routine are listed in the sequence of |
3240 |
@emph{likelyhood of use}. So the first entry will be most likely the |
@emph{likelihood of use}. So the first entry will be most likely the |
3241 |
one you'll get if an unsuspecting command uses that routine. Before |
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 |
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: |
pressing @kbd{C-c C-i}. Here are the different routines: |
3258 |
@end table |
@end table |
3259 |
|
|
3260 |
For these commands to work properly you should have scanned the entire |
For these commands to work properly you should have scanned the entire |
3261 |
load path, not just selected directories. Also, IDLWAVE should be able to |
load path, not just selected directories. Also, IDLWAVE should be able |
3262 |
distinguish between the system library files (normally installed in |
to distinguish between the system library files (normally installed in |
3263 |
@file{/usr/local/rsi/idl/lib}) and any site specific or user specific |
@file{/usr/local/rsi/idl/lib}) and any site specific or user specific |
3264 |
files. Therefore, such local files should not be installed |
files. Therefore, such local files should not be installed inside the |
3265 |
inside the @file{lib} directory of the IDL directory. This is of course |
@file{lib} directory of the IDL directory. This is also advisable for |
3266 |
also advisable for many other reasons. |
many other reasons. |
3267 |
|
|
3268 |
@cindex Windows |
@cindex Windows |
3269 |
@cindex MacOS |
@cindex MacOS |
3279 |
on the load path is routine info display (@pxref{Routine Info}). |
on the load path is routine info display (@pxref{Routine Info}). |
3280 |
|
|
3281 |
@node Documentation Scan, , Load-Path Shadows, Sources of Routine Info |
@node Documentation Scan, , Load-Path Shadows, Sources of Routine Info |
3282 |
@section Documentation Scan |
@appendixsec Documentation Scan |
3283 |
@cindex @file{get_rinfo} |
@cindex @file{get_rinfo} |
3284 |
@cindex @file{idlw-rinfo.el} |
@cindex @file{idlw-rinfo.el} |
3285 |
@cindex @file{idlw-help.txt} |
@cindex @file{idlw-help.txt} |
3301 |
by scanning selected files from the IDL documentation. Instructions on |
by scanning selected files from the IDL documentation. Instructions on |
3302 |
how to use @file{get_rinfo} are in the program itself. |
how to use @file{get_rinfo} are in the program itself. |
3303 |
|
|
3304 |
@node Configuration Examples, Index, Sources of Routine Info, Top |
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 |
3313 |
@appendix Configuration Examples |
@appendix Configuration Examples |
3314 |
@cindex Configuration examples |
@cindex Configuration examples |
3315 |
@cindex Example configuration |
@cindex Example configuration |
3318 |
@cindex Interview, with the maintainer |
@cindex Interview, with the maintainer |
3319 |
|
|
3320 |
@noindent |
@noindent |
3321 |
@b{Question:} So now you have all these complicated configuration |
@b{Question:} You have all these complicated configuration options in |
3322 |
options in your package, but which ones do @emph{you} as the maintainer |
your package, but which ones do @emph{you} as the maintainer actually |
3323 |
actually set in your own configuration? |
set in your own configuration? |
3324 |
|
|
3325 |
@noindent |
@noindent |
3326 |
@b{Answer:} Hardly any. As the maintainer, I set the default of most |
@b{Answer:} Not many, beyond custom key bindings. I set most defaults |
3327 |
options to what I think is best. However, the default settings do not |
the way that seems best. However, the default settings do not turn on |
3328 |
turn on features which |
features which: |
3329 |
|
|
3330 |
@itemize @minus |
@itemize @minus |
3331 |
@item |
@item |
3332 |
are not self-evident (i.e. too magic) when used by an unsuspecting user |
are not self-evident (i.e. too magic) when used by an unsuspecting user. |
3333 |
@item |
@item |
3334 |
are too intrusive |
are too intrusive. |
3335 |
@item |
@item |
3336 |
will not work properly on all Emacs installations out there |
will not work properly on all Emacs installations. |
3337 |
@item |
@item |
3338 |
break with widely used standards. |
break with widely used standards. |
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. |
3344 |
@end itemize |
@end itemize |
3345 |
|
|
3346 |
@noindent To see what I mean, here is the @emph{entire} configuration I |
@noindent To see what I mean, here is the @emph{entire} configuration |
3347 |
have in my @file{.emacs}: |
the old maintainer had in his @file{.emacs}: |
3348 |
|
|
3349 |
@lisp |
@lisp |
3350 |
(setq idlwave-shell-debug-modifiers '(control shift) |
(setq idlwave-shell-debug-modifiers '(control shift) |
3351 |
idlwave-store-inquired-class t |
idlwave-store-inquired-class t |
3352 |
idlwave-shell-automatic-start t |
idlwave-shell-automatic-start t |
3353 |
idlwave-main-block-indent 2 |
idlwave-main-block-indent 2 |
3354 |
|
idlwave-init-rinfo-when-idle-after 2 |
3355 |
idlwave-help-dir "~/lib/emacs/idlwave" |
idlwave-help-dir "~/lib/emacs/idlwave" |
3356 |
idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib") |
idlwave-special-lib-alist '(("/idl-astro/" . "AstroLib") |
3357 |
("/jhuapl/" . "JHUAPL-Lib") |
("/jhuapl/" . "JHUAPL-Lib") |
3359 |
@end lisp |
@end lisp |
3360 |
|
|
3361 |
However, if you are an Emacs power-user and want IDLWAVE to work |
However, if you are an Emacs power-user and want IDLWAVE to work |
3362 |
completely differently, the options allow you to change almost every |
completely differently, you can change almost every aspect of it. Here |
3363 |
aspect of it. Here is an example of a much more extensive configuration |
is an example of a much more extensive configuration of IDLWAVE. The |
|
of IDLWAVE. To say it again - this is not what I recommend, but the |
|
3364 |
user is King! |
user is King! |
3365 |
|
|
3366 |
@example |
@example |
3370 |
(setq idlwave-main-block-indent 3) |
(setq idlwave-main-block-indent 3) |
3371 |
(setq idlwave-end-offset -3) |
(setq idlwave-end-offset -3) |
3372 |
(setq idlwave-continuation-indent 1) |
(setq idlwave-continuation-indent 1) |
3373 |
(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" |
(setq idlwave-begin-line-comment "^;[^;]") ; Leave ";" but not ";;" |
3374 |
; anchored at start of line. |
; anchored at start of line. |
3375 |
(setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> |
(setq idlwave-surround-by-blank t) ; Turn on padding ops =,<,> |
3376 |
(setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' |
(setq idlwave-pad-keyword nil) ; Remove spaces for keyword '=' |
3381 |
(setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill |
(setq idlwave-hang-indent-regexp ": ") ; Change from "- " for auto-fill |
3382 |
(setq idlwave-show-block nil) ; Turn off blinking to begin |
(setq idlwave-show-block nil) ; Turn off blinking to begin |
3383 |
(setq idlwave-abbrev-move t) ; Allow abbrevs to move point |
(setq idlwave-abbrev-move t) ; Allow abbrevs to move point |
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))) |
3390 |
|
|
3391 |
;; Some setting can only be done from a mode hook. Here is an example: |
;; Some setting can only be done from a mode hook. Here is an example: |
|
|
|
3392 |
(add-hook 'idlwave-mode-hook |
(add-hook 'idlwave-mode-hook |
3393 |
(lambda () |
(lambda () |
|
(setq abbrev-mode 1) ; Turn on abbrevs (-1 for off) |
|
3394 |
(setq case-fold-search nil) ; Make searches case sensitive |
(setq case-fold-search nil) ; Make searches case sensitive |
3395 |
;; Run other functions here |
;; Run other functions here |
3396 |
(font-lock-mode 1) ; Turn on font-lock mode |
(font-lock-mode 1) ; Turn on font-lock mode |
3397 |
(idlwave-auto-fill-mode 0) ; Turn off auto filling |
(idlwave-auto-fill-mode 0) ; Turn off auto filling |
3398 |
;; |
|
3399 |
;; Pad with 1 space (if -n is used then make the |
;; Pad with 1 space (if -n is used then make the |
3400 |
;; padding a minimum of n spaces.) The defaults use -1 |
;; padding a minimum of n spaces.) The defaults use -1 |
3401 |
;; instead of 1. |
;; instead of 1. |
3403 |
(idlwave-action-and-binding "<" '(idlwave-surround 1 1)) |
(idlwave-action-and-binding "<" '(idlwave-surround 1 1)) |
3404 |
(idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-))) |
(idlwave-action-and-binding ">" '(idlwave-surround 1 1 '(?-))) |
3405 |
(idlwave-action-and-binding "&" '(idlwave-surround 1 1)) |
(idlwave-action-and-binding "&" '(idlwave-surround 1 1)) |
3406 |
;; |
|
3407 |
;; Only pad after comma and with exactly 1 space |
;; Only pad after comma and with exactly 1 space |
3408 |
(idlwave-action-and-binding "," '(idlwave-surround nil 1)) |
(idlwave-action-and-binding "," '(idlwave-surround nil 1)) |
3409 |
(idlwave-action-and-binding "&" '(idlwave-surround 1 1)) |
(idlwave-action-and-binding "&" '(idlwave-surround 1 1)) |
3410 |
;; |
|
3411 |
;; Pad only after `->', remove any space before the arrow |
;; Pad only after `->', remove any space before the arrow |
3412 |
(idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2)) |
(idlwave-action-and-binding "->" '(idlwave-surround 0 -1 nil 2)) |
3413 |
;;; |
|
3414 |
;; Set some personal bindings |
;; Set some personal bindings |
3415 |
;; (In this case, makes `,' have the normal self-insert behavior.) |
;; (In this case, makes `,' have the normal self-insert behavior.) |
3416 |
(local-set-key "," 'self-insert-command) |
(local-set-key "," 'self-insert-command) |
3417 |
|
(local-set-key [f5] 'idlwave-shell-break-here) |
3418 |
|
(local-set-key [f6] 'idlwave-shell-clear-current-bp) |
3419 |
|
|
3420 |
;; Create a newline, indenting the original and new line. |
;; Create a newline, indenting the original and new line. |
3421 |
;; A similar function that does _not_ reindent the original |
;; A similar function that does _not_ reindent the original |
3422 |
;; line is on "\C-j" (The default for emacs programming modes). |
;; line is on "\C-j" (The default for emacs programming modes). |
3423 |
(local-set-key "\n" 'idlwave-newline) |
(local-set-key "\n" 'idlwave-newline) |
3424 |
;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. |
;; (local-set-key "\C-j" 'idlwave-newline) ; My preference. |
3425 |
|
|
3426 |
|
;; Some personal abbreviations |
3427 |
|
(define-abbrev idlwave-mode-abbrev-table |
3428 |
|
(concat idlwave-abbrev-start-char "wb") "widget_base()" |
3429 |
|
(idlwave-keyword-abbrev 1)) |
3430 |
|
(define-abbrev idlwave-mode-abbrev-table |
3431 |
|
(concat idlwave-abbrev-start-char "on") "obj_new()" |
3432 |
|
(idlwave-keyword-abbrev 1)) |
3433 |
)) |
)) |
3434 |
|
|
3435 |
;;; Settings for IDLWAVE SHELL mode |
;;; Settings for IDLWAVE SHELL mode |
3440 |
(setq idlwave-shell-explicit-file-name "wave") |
(setq idlwave-shell-explicit-file-name "wave") |
3441 |
(setq idlwave-shell-process-name "wave") |
(setq idlwave-shell-process-name "wave") |
3442 |
(setq idlwave-shell-use-toolbar nil) ; No toolbar |
(setq idlwave-shell-use-toolbar nil) ; No toolbar |
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 |
3448 |
|
(idlwave-shell-define-key-both [s-down-mouse-2] |
3449 |
|
(idlwave-shell-mouse-examine |
3450 |
|
"print, size(___,/DIMENSIONS)")) |
3451 |
|
(idlwave-shell-define-key-both [f9] (idlwave-shell-examine |
3452 |
|
"print, size(___,/DIMENSIONS)")) |
3453 |
|
(idlwave-shell-define-key-both [f10] (idlwave-shell-examine |
3454 |
|
"print,size(___,/TNAME)")) |
3455 |
|
(idlwave-shell-define-key-both [f11] (idlwave-shell-examine |
3456 |
|
"help,___,/STRUCTURE")))) |
3457 |
@end example |
@end example |
3458 |
|
|
3459 |
@node Index, , Configuration Examples, Top |
@ifhtml |
3460 |
|
<A NAME="WIN_MAC"></A> |
3461 |
|
@end ifhtml |
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 |
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. |
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 |
3490 |
|
;; location of the lisp files (needed if IDLWAVE is not part of |
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 |
3513 |
|
@item When you download the IDLWAVE distribution, make sure you save the |
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 |
3528 |
@unnumbered Index |
@unnumbered Index |
3529 |
@printindex cp |
@printindex cp |
3530 |
|
|
3531 |
@bye |
@bye |
|
|
|